Makrotyp: S-Typ (E-Form/L-Form/D-Form/C-Form/M-Form) (siehe "Typen von Makroaufrufen")
Der Makro MAILFIL sendet, analog zum Kommando MAIL-FILE, eine Datei als Anhang einer E-Mail. Als Empfänger der E-Mail wird eine Benutzerkennung angegeben. Absender ist die Benutzerkennung der aufrufenden Task. Aus dem EMAIL-ADDRESS-Feld dieser Benutzereinträge übernimmt MAIL-FILE die dort eingetragene E-Mail-Adresse. Die Ermittlung der Empfänger- und Absender-Adresse, insbesondere im Falle einer Adressliste, ist im Abschnitt „Selektion von E-Mail-Adressen über den Jobnamen" beschrieben.
Versendet werden kann ein PLAM-Bibliothekselement, eine SAM- oder ISAM-Datei sowie der Inhalt der Systemdatei SYSLST bzw. SYSOUT. Eine PAM-Datei kann nur versendet werden, wenn der Inhalt im PDF-Format vorliegt.
Die Benutzertask, unter der MAILFIL ausgeführt wird, muss die nötigen Zugriffsrechte besitzen. Bei der automatischen Zeichensatz-Konvertierung wird das Dateiattribut CCS-Name ausgewertet.
Optional kann der Aufrufer vereinbaren, dass die Datei nach dem Versenden automatisch gelöscht werden soll.
Zur Makroausführung muss die Funktion „Mail-Sender“ des Software-Produkts interNet-Services zur Verfügung stehen und im Benutzereintrag der Systemkennung TSOS muss mindestens eine E-Mail-Adresse eingetragen sein.
Der Aufruf wird abgewiesen, wenn im Benutzereintrag des Empfängers keine E-Mail-Adresse eingetragen ist. Wenn für den Aufrufer keine E-Mail-Adresse eingetragen ist. wird als Absender ersatzweise die Adresse des Empfängers oder TSOS eingesetzt.
Falls die E-Mail-Versand nicht zugestellt werden kann (z.B. wegen ungültiger Adresse), wird eine Bounce-Mail an die E-Mail-Adresse von TSOS gesendet um die Systembetreuung zur Überprüfung der fehlerhaften Adresse aufzufordern. Wenn für TSOS mehrere E-Mail-Adressen eingetragen sind, wird für die Bounce-Mail die erste Adresse verwendet.
Die MAIL-FILE-Funktionalität wird auch von anderen Komponenten des BS2000 zum Versenden von Protokolldateien verwendet:
bei der Auftragsbeendigung
In den Kommandos EXIT-JOB (bzw. LOGOFF), CANCEL-JOB und ENTER-PROCEDURE kann statt der Druckausgabe auch das Versenden von SYSLST bzw. SYSOUT bei Auftragsbeendigung angefordert werden. Mit der Voreinstellung *STDOUT erfolgt die Ausgabe über das im Systemparameter SSMOUT festgelegte Ausgabemedium (Drucker oder E-Mail).bei Ausgaben von Dienstprogrammen
Derzeit unterstützen HSMS ab V9.0 und MAREN ab V12.0 das Versenden von Ausgabeinformationen bzw. Protokollen.
Format
Operation | Operanden |
|
|
| |
| |
|
Operandenbeschreibung
PATHNAM
Wählt die zu versendende Datei bzw. die PLAM-Bibliothek des zu versendenden Bibliothekselements aus.
=<c-string 1..54: filename 1..54>
Pfadname bzw. Bibliotheksname.
Für zu versendende Dateien gelten folgende Einschränkungen:
Die Datei ist eine SAM- oder ISAM-Datei. Eine PAM-Datei wird nur versandt, wenn der Inhalt PDF-Format hat.
Die Datei darf nicht leer sein.
Der Name darf eine einzelne Dateigeneration bezeichnen, nicht jedoch eine Dateigenerationsgruppe.
Es kann auch eine temporäre Datei sein.
Ein privilegierter Benutzer (Privileg TSOS) kann auch temporäre Dateien einer anderen Task angeben. Er kann auch temporäre Dateien angeben, die auf einem anderen Pubset als dem Default-Pubset der Benutzerkennung liegen.Es darf keine Datei sein, die nur über eine RFA-Verbindung erreichbar ist.
=<var: char:54>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 54 Byte, in dem der Pfadname der zu sendenden Datei abgelegt ist.
=*SYSOUT
Bezeichnet die Systemdatei SYSOUT. Die Angabe ist nur möglich, wenn der SYSOUT-Datei eine Datei bzw. Dateigeneration auf Platte zugewiesen ist, die mit der Zugriffsmethode SAM erstellt wurde.
Die Angabe wird in folgenden Fällen abgewiesen:
Die zugewiesene Datei ist noch leer.
Die SYSOUT-Datei hat die Primärzuweisung.
Es ist die Pseudodatei DUMMY, eine temporäre Datei, ein PLAM-Bibliothekselement oder eine S-Variable zugewiesen.
=*SYSLST
Bezeichnet die Systemdatei SYSLST. In folgenden Fällen wird die Angabe abgewiesen:
SYSLST ist leer.
Es ist die Pseudodatei DUMMY, eine temporäre Datei, ein PLAM-Bibliothekselement oder eine S-Variable zugewiesen.
Die zugewiesene Datei bzw. Dateigeneration liegt nicht auf Platte oder wurde nicht mit der Zugriffsmethode SAM erstellt.
=(*SYSLST,<integer 1..99>)
Bezeichnet eine SYSLST-Datei aus der Menge SYSLST01 bis SYSLST99. Die Angabe ist nur möglich, wenn der SYSLST-Datei eine Datei bzw. Dateigeneration auf Platte zugewiesen ist, die mit der Zugriffsmethode SAM erstellt wurde.
Die Angabe wird in folgenden Fällen abgewiesen:
Die zugewiesene Datei ist noch leer.
Die SYSLST-Datei hat die Primärzuweisung.
Es ist die Pseudodatei DUMMY, eine temporäre Datei, ein PLAM-Bibliothekselement oder eine S-Variable zugewiesen.
LIBELEM
Zu sendendes PLAM-Bibliothekselement. Zusätzlich muss im Operanden PATHNAM der entsprechende Name der PLAM-Bibliothek angegeben werden.
Es können nur Textelemente und PDF-Dateien versandt werden. Textelemente sind Elemente der Typen S, M, J, P, D, X und davon abgeleiteter Typen, soweit sie keine blockorientierten Sätze enthalten. Ein Element, das blockorientierte Sätze enthält, wird nur versandt, wenn sein Inhalt PDF-Format hat.
=*NONE
Es soll kein Bibliothekselement versendet werden. Der Operand PATHNAM enthält die Angaben über die zu versendenden Datei.
=(<element>,<version>,<typ>)
Gibt Name, Version und Typ eines zu versendenden Elementes der im Operanden PATHNAM angegebenen PLAM-Bibliothek an.
<element>=<c-string 1..64: composed-name 1..64> with under
Name des zu versendenden Bibliothekselementes.
<element>=<var: char:64>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 64 Byte, in dem der Name des zu versendenden Bibliothekselementes abgelegt ist.
<version>=*HIGHEST
Wählt die höchste existierende Version aller Elemente aus, die den angegebenen Namen und den angegebenen Typ haben.
<version>=*UPPER
Wählt die höchste mögliche Version (X'FF') aller Elemente aus, die den angegebenen Namen und den angegebenen Typ haben.
<version>=<c-string 1..24: composed-name 1..24> with under
Version des zu versendenden Bibliothekselementes.
<version>=<var: char:24>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 24 Byte, in dem die Version des zu versendenden Bibliothekselementes abgelegt ist.
<typ>=<c-string 1..8: alphanum-name 1..8>
Typ des zu versendenden Bibliothekselementes.
<version>=<var: char:8>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 8 Byte, in dem der Typ des zu versendenden Bibliothekselementes abgelegt ist.
USERID
Benutzerkennung, deren Eintrag im Benutzerkatalog die E-Mail-Adresse des Empfängers enthält.
=*OWN
Voreingestellt ist *OWN, d.h. die Logon-Benutzerkennung der aufrufenden Task. Wenn der Benutzereintrag eine Liste mit mehreren E-Mail-Adressen enthält, wird ggf. eine Empfängeradresse in Abhängigkeit vom Jobnamen ausgewählt (siehe „Selektion von E-Mail-Adressen über den Jobnamen").
=<c-string 1..8: name 1..8>
Benutzerkennung, aus deren Benutzereintrag die E-Mail-Adresse des Empfängers ermittelt wird.
=<var: char:8>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 8 Byte, in dem die Benutzerkennung des Empfängers abgelegt ist.
SUBJECT
Bezeichnet den Betreff der E-Mail.
Hinweis
Da der BCAM-Name des absendenden BS2000-Systems bereits im Text der gesendeten E-Mail enthalten ist, muss er nicht extra in den Betreff aufgenommen werden.
=*STD
Mit *STD erhält die E-Mail einen standardisierten Betreff-Text, der neben dem Hinweis „von BS2000“ auch die Absenderkennung und den Dateinamen enthält.
=<c-string 1..256 with-low>
Betreff der E-Mail. Groß-/Kleinschreibung werden unterschieden. Es wird empfohlen, sich auf den internationalen Zeichensatz zu beschränken.
=<var: char:8>
Nur mit MF=M möglich:
Symbolische Adresse eines Speicherbereichs von 256 Byte, in dem der Betreff der E-Mail abgelegt ist.
DELETE
Gibt an, ob die Datei oder das PLAM-Bibliothekselement nach dem erfolgreichen Versenden automatisch gelöscht werden soll. Dabei ist zu beachten:
Wenn die Systemdatei SYSLST zu senden ist und SYSLST die Primärzuweisung besitzt, gilt DELETE=*YES.
Wenn die Systemdatei SYSLST bzw. SYSOUT zu senden ist und die Systemdatei einer Datei bzw. Dateigeneration zugewiesen ist, unterbleibt das automatische Löschen.
=*NO
Die Datei oder das PLAM-Bibliothekselement wird nicht gelöscht. Die Datei oder das PLAM-Bibliothekselement ist nach dem Aufruf von MAIL-FILE sofort wieder verfügbar.
=*YES
Die Datei oder das PLAM-Bibliothekselement wird nach erfolgreichem Senden automatisch gelöscht. Die Datei oder das PLAM-Bibliothekselement gilt auch dann als erfolgreich gesendet, wenn sie danach nicht zugestellt werden kann (z.B. wegen unbekannter E-Mail-Adresse).
=*DESTROY
Die Angabe wirkt wie DELETE=*YES. Zusätzlich wird der Datei- oder Elementinhalt beim Löschen mit binär null überschrieben.
EQUATES
Steuerungs-Operand nur für MF=C und MF=D:
Gibt an, ob bei der Expansion des Parameterbereichs auch Equates für die Werte der Felder des Parameterbereichs generiert werden sollen.
= *YES
Bei der Expansion des Parameterbereichs werden auch Equates für die Werte der Felder des Parameterbereichs generiert.
= *NO
Bei der Expansion des Parameterbereichs werden keine Equates für die Werte der Felder des Parameterbereichs generiert.
VERSION
Steuert die Generierung des Parameterbereichs bzw. des Funktionsaufrufs. Der Operand muss bei der Generierung des Funktionsaufrufs denselben Wert haben wie bei der Generierung des zugehörigen Parameterbereichs.
= 1
erzeugt den für BS2000/OSD-BC V8.0 gültigen Parameterbereich bzw. Funktionsaufruf (die Angabe eines Bibliothekselements ist nicht möglich).
= 2
erzeugt den ab BS2000/OSD-BC V9.0 gültigen Parameterbereich bzw. Funktionsaufruf.
Layout des Parameterbereichs
Der Parameterbereich muss auf Wortgrenze ausgerichtet sein. Er beginnt mit einem Standardheader, den MAILFIL wie folgt initialisiert:
Function Unit Number | 22 |
Function Number | 32 |
Interface Version Number | 2 bei Angabe von VERSION=2, sonst 1 |
Returncode | -1 |
Makroauflösung mit MF=D und Standardwerten für EQUATES, PREFIX und MACID:
MAILFIL MF=D,VERSION=2 DMAMDEPL DSECT , DMAMHDR DS 0A DMAMFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER DMAMIFID DS 0A 0 INTERFACE IDENTIFIER DMAMFCTU DS AL2 0 FUNCTION UNIT NUMBER DMAMFCT DS AL1 2 FUNCTION NUMBER DMAMFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER DMAMRET DS 0A 4 GENERAL RETURN CODE DMAMSRET DS 0AL2 4 SUB RETURN CODE DMAMSR2 DS AL1 4 SUB RETURN CODE 2 DMAMSR1 DS AL1 5 SUB RETURN CODE 1 DMAMMRET DS 0AL2 6 MAIN RETURN CODE DMAMMR2 DS AL1 6 MAIN RETURN CODE 2 DMAMMR1 DS AL1 7 MAIN RETURN CODE 1 DMAMFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH * DMAMPNAM DS CL54 Dateiname DMAMUSID DS CL8 Benutzerkennung oder Blank DMAMSUBJ DS CL256 Betreff oder Blank DMAMDELE DS FL1 automatisches Loeschen * DELETE - values DMAMDELN EQU 0 DELETE = NO DMAMDELY EQU 1 DELETE = YES DMAMDELD EQU 2 DELETE = DESTROY * DMAMPNSP DS FL1 Typ der PATHNAM-Angabe * PATHNAM - values DMAMBYFN EQU 0 PATHNAM = fnam DMAMSLST EQU 1 PATHNAM = *SYSLST DMAMBYSN EQU 2 (*SYSLST,n) DMAMSOUT EQU 3 PATHNAM = *SYSOUT * DMAMSYSNUM DS X Syslst number DMAMRES DS XL3 Alignment DMAMENAM DS CL64 Elementname oder Blank DMAMEVER DS CL24 Elementversion oder Blank DMAMETYP DS CL8 Elementtyp oder Blank DMAMRES2 DS XL4 Alignment DMAM# EQU *-DMAMHDR
Returncode
Der Returncode wird im Standardheader des Parameterbereichs abgelegt. Der Parameterbereich darf dann nicht im Read-only-Bereich liegen, sonst erfolgt Programmterminierung.
Folgende Returncodes werden von Mail-File erzeugt:
X'cc' | X'bb' | X'aaaa' | Erläuterung |
X'00' | X'00' | X'0000' | kein Fehler |
X'00' | X'01' | X'0554' | Format des Dateinamens unzulässig |
X'00' | X'01' | X'0576' | fehlerhafte Operandenkombination oder nicht gelöschte UNUSED-Felder |
X'00' | X'20' | X'05C7' | interner Fehler im DMS |
X'00' | X'40' | X'05FC' | Benutzerkennung nicht eingetragen |
X'00' | X'40' | X'0694' | Senden der Datei nicht erlaubt |
X'00' | X'40' | X'0695' | E-Mail-Adresse fehlt |
X'00' | X'40' | X'0696' | E-Mail-Adresse von TSOS fehlt |
Weitere Returncodes, deren Bedeutung durch Konvention makroübergreifend festgelegt ist, können der Tabelle auf "Standardheader" (Standardheader) entnommen werden.
Außerdem können Returncodes von DMS-Schnittstellen (siehe Makro FSTAT bzw. ERASE) sowie von der Mail-Sender-Schnittstelle (Makro YMLSML des Software-Produkts interNet-Services) durchgereicht werden.
Wenn ein PLAM-Bibliothekselement (Operand LIBELEM) angegeben ist, dann können außerdem Returncodes von ILAM-Schnittstellen (siehe Makros PMATCH, PMDTCH, PMOPEN, PMCLOS, PMGETA, PMPOSA, PMDELM der ILAM-Schnittstelle für PLAM) durchgereicht werden. Die Maincodes der ILAM-Schnittstellen entsprechen den dezimalen Meldungsnummern der PLAM-Meldungen (also zum Beispiel Maincode 00CB entspricht der PLAM-Meldung PLA0203).
Nähere Informationen können Sie mit /HELP-MSG <msgid> abfragen.
Beispiel für eine Aufruffolge
MVC MLFLMFC(256),MLFLMFL
MVC MLFLMFC+256(XMAM#-256),MLFLMFL+256
MAILFIL MF=M,PREFIX=X,DELETE=*DESTROY
MAILFIL MF=E,PARAM=MLFLMFC
.
.
MLFLMFC MAILFIL MF=C,PREFIX=X
MLFLMFL MAILFIL MF=L,PATHNAM='PN0',USERID='UI0'
Selektion von E-Mail-Adressen über den Jobnamen
MAIL-FILE ermittelt die E-Mail-Adressen von Empfänger und Absender über den Benutzereintrag der jeweiligen Benutzerkennung. Zur Ausführung des Kommandos müssen die Benutzerkennungen des Empfängers und des Absenders jeweils eine E-Mail-Adresse enthalten (siehe Kommando SHOW-USER-ATTRIBUTES, Ausgabefeld EMAIL-ADDRESS). Der Eintrag kann auch eine Adressliste, d.h. mehrere durch Komma getrennte E-Mail-Adressen enthalten.
Bei einer Adressliste im Benutzereintrag des Absenders wird die erste Adresse zur Absenderadresse.
Bei einer Adressliste im Benutzereintrag des Empfängers unterscheidet MAIL-FILE, ob als Empfänger die Benutzerkennung des Aufrufers (*OWN) oder eine „fremde“ Benutzerkennung angegeben wurde. Bei Angabe einer fremden Benutzerkennung verschickt MAIL-FILE die E-Mail an alle Adressen. Bei Angabe der eigenen Benutzerkennung, selektiert MAIL-FILE die Adressen über den Jobnamen der aufrufenden Task:
Es wird eine Adresse gesucht, bei der ein Teilname des lokalen Adressteils (vor dem @) mit dem Jobnamen beginnt (Groß-/Kleinschreibung bleiben unberücksichtigt). Teilnamen sind durch einen Punkt von einander getrennt (z.B. vorname.nachname).
Aus der Adressliste Anna.Huber@xy,Anja.Bauer@xy,Anton.Baumann@xy werden z.B. folgende Adressen selektiert:
Anna.Huber@xymit den Jobnamen: ANN, HU, HUBERAnja.Bauer@xymit den Jobnamen: ANJ, ANJA, BAUE, BAUERAnton.Baumann@xymit den Jobnamen: ANT, BAUM, BAUMAN
Zusätzlich kann auch die Möglichkeit genutzt werden, dass den Adressen im Benutzereintrag „Adressnamen“ in runden Klammern vorangestellt werden.
Beispiel: (ANH)Anna.Huber@xy,(ANB)Anja.Bauer@xy,(BMN)Anton.Baumann@xy
Aus dieser Adressliste werden dann z.B. folgende Adressen selektiert:
Anna.Huber@xymit den Jobnamen: ANH sowie ANN, HU, HUBERAnja.Bauer@xymit den Jobnamen: ANB sowie ANJ, ANJA, BAUE, BAUERAnton.Baumann@xymit den Jobnamen: BMN sowie ANT, BAUM, BAUMAN
Wenn der Jobname zu mehr als einer Adresse passt, wird diejenige Adresse selektiert, bei der der zum Jobnamen passende Teilname am kürzesten ist. Aus der Adressliste Beate.Pauli@xy,Pauline.Beck@xy,Paul.Becker@xy werden z.B. folgende Adressen selektiert:
Beate.Pauli@xymit den Jobnamen: PAULI, BEAPauline.Beck@xymit den Jobnamen: PAULIN, BE, BECKPaul.Becker@xymit den Jobnamen: P, PAUL, BECKER
Wenn bei mehreren Adressen der zum Jobnamen passende Teilname am kürzesten ist, wird von diesen Adressen die erste selektiert.
Wenn innerhalb einer Adresse mehrere Teilnamen zum Jobnamen passen, wird nur der erste Teilname berücksichtigt.
Wenn die aufrufende Task keinen Jobnamen besitzt oder der Jobname zu keiner Adresse der Adressliste passt, wird wie folgt vorgegangen:
Bei Ermittlung der Empfängeradresse wird die ganze Adressliste verwendet, also die E-Mail an alle Adressen verschickt.
Bei Ermittlung der Absenderadresse wird nur die erste Adresse der Adressliste verwendet.