Macro type: type S (E form/L form/D form/C form/M form) (see "Macro format")
Like the MAIL-FILE command, the MAILFIL macro sends a file as an attachment to an email. A user ID is specified as the receiver of the email. The sender is the user ID of the calling task. MAIL-FILE takes over the email address entered in the EMAIL-ADDRESS field of these user entries as the sender. How you ascertain the receiver and sender addresses, in particular when an address list is used, is described in the section "Selecting email addresses by means of the job name".
A PLAM library member, a SAM or ISAM file and the contents of the system file SYSLST or SYSOUT can be sent. A PAM file can be sent only if the content is available in PDF format. The user task under which MAILFIL is executed must have the required access rights. The file attribute CCS name is evaluated in the case of automatic character set conversion. Optionally the caller can specify that the file is to be deleted automatically after it has been sent.
To execute the macro the “Mail-Sender” function of the software product interNet Services must be available, and at least one email address must be entered in the user entry of the TSOS system ID.
The call is rejected if no email address is entered in the receiver’s user entry. If no email address is entered for the caller, the address of the receiver or TSOS is entered instead as the sender.
If the email cannot be delivered (e.g. because the address is invalid), a bounce mail is sent to the email address of TSOS to request systems support to check the incorrect address. If more than one email address is entered for TSOS, the first address is used for the bounce mail.
The MAIL-FILE functionality is also used by other components of BS2000 to send log files:
At job termination
In the EXIT-JOB (or LOGOFF), CANCEL-JOB and ENTER-PROCEDURE commands, transfer to SYSLST or SYSOUT at job termination can be requested instead of a printout. The default value *STDOUT directs output to the output medium defined in the system parameter SSMOUT (printer or email).In the case of outputs from utility routines
Currently HSMS V9.0 and higher and MAREN V12.0 and higher support the transfer of output information and logs.
Format
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
PATHNAM
Selects the file which is to be sent or the PLAM library of the library member which is to be sent.
=<c-string 1..54: filename 1..54>
Path name of the file or library name.
The following restrictions apply fo files which are to be sent:
The file is a SAM or ISAM file. A PAM file is sent only if the content is in PDF format.
The file may not be empty.
The name may specify a single file generation but not a file generation group.
It can also be a temporary file.
A privileged user (TSOS privilege) can also specify temporary files of another task.
A privileged user can also specify temporary files which reside on a different pubset from the default pubset of the user ID.The file may not be only accessible via an RFA connection.
=<var: char:54>
Only possible with MF=M:
Symbolic address of a memory area of 54 bytes in which the path name of the file to be sent is stored.
=*SYSOUT
Specifies the system file SYSOUT. This specification is possible only if the SYSOUT file is assigned a file or file generation on disk which was created using the access method SAM.
The specification is rejected in the following cases:
The assigned file is still empty.
The SYSOUT file has the primary allocation.
The DUMMY file, a temporary file, a PLAM library member or an S variable is assigned.
=*SYSLST
Specifies the system file SYSLST. This specification is rejected in the following cases:
SYSLST is empty.
The DUMMY file, a temporary file, a PLAM library member or an S variable is assigned.
The assigned file or file generation is not resident on disk or was not created using the access method SAM.
=(*SYSLST,<integer 1..99>)
Specifies a SYSLST file from the set SYSLST01 through SYSLST99. This specification is possible only if the SYSLST file is assigned a file or file generation on disk which was created using the access method SAM.
The specification is rejected in the following cases:
The assigned file is still empty.
The SYSLST file has the primary allocation.
The DUMMY file, a temporary file, a PLAM library member or an S variable is assigned.
LIBELEM
PLAM library member which is to be sent. The name of the PLAM library must also be specified in the PATHNAM operand.
Only text members and PDF files can be sent. Text members are members of the types S, M, J, P, D, X and types derived from these provided they contain no block-oriented records. A member which contains block-oriented records is sent only if its content is in PDF format.
=*NONE
No library member is to be sent. The PATHNAM operand contains the information about the file which is to be sent.
=(<element>,<version>,<typ>)
Specifies the name, version and type of a member which is to be sent which belongs to the PLAM library specified in the PATHNAM operand.
<element>=<c-string 1..64: composed-name 1..64> with under
Name of the library member which is to be sent.
<element>=<var: char:64>
Only possible with MF=M:
Symbolic address of a memory area of 64 bytes in which the name of the library member which is to be sent is stored.
<version>=*HIGHEST
Selects the highest existing version of all members which have the specified name and the specified type.
<version>=*UPPER
Selects the highest possible version (X'FF') of all members which have the specified name and the specified type.
<version>=<c-string 1..24: composed-name 1..24> with under
Version of the library member which is to be sent.
<version>=<var: char:24>
Only possible with MF=M:
Symbolic address of a memory area of 24 bytes in which the version of the library member which is to be sent is stored.
<typ>=<c-string 1..8: alphanum-name 1..8>
Type of the library member which is to be sent.
<version>=<var: char:8>
Only possible with MF=M:
Symbolic address of a memory area of 8 bytes in which the type of the library member which is to be sent is stored.
USERID
User ID whose entry in the user catalog contains the receiver’s email address.
=*OWN
The default value is *OWN, i.e. the logon user ID of the calling task. If the user entry contains a list with more than one email address, a receiver address may be selected in accordance with the job name (see "Selecting email addresses by means of the job name").
=<c-string 1..8: name 1..8>
User ID from whose user entry the receiver’s email address is ascertained.
=<var: char:8>
Only possible with MF=M:
Symbolic address of a memory area of 8 bytes in which the receiver’s user ID is stored.
SUBJECT
Specifies the subject of the email.
Note
As the BCAM name of the sending BS2000 system is already contained in the text of the email which is sent, it need not be entered specially in the subject line.
=*STD
*STD specifies that the email should have a standardized subject text which, in addition to the information “from BS2000”, also contains the sender ID and the file name.
=<c-string 1..256 with-low>
Subject of the email. Case-sensitive. You are recommended to stick to the international character set.
=<var: char:8>
Only possible with MF=M:
Symbolic address of a memory area of 256 bytes in which the subject of the email is stored.
DELETE
Specifies whether the file or the PLAM library member should be automatically deleted after it has been sent successfully:
If the system file SYSLST is to be sent and SYSLST has the primary allocation, DELETE=*YES applies.
If the system file SYSLST or SYSOUT is to be sent and the system file is assigned to a file or file generation, it is not deleted automatically.
=*NO
The file or the PLAM library member is not deleted. The file or the PLAM library member is available again immediately after MAIL-FILE is called.
=*YES
The file is automatically deleted after it has been sent successfully. A file is regarded as having been sent successfully even if it cannot be delivered (e.g. because the email address is unknown).
=*DESTROY
This specification has the same effect as DELETE=*YES. In addition, the file or member content is overwritten with binary zeros when it is deleted.
EQUATES
Control operand; for MF=C and MF=D only:
Specifies whether equates are also to be generated for the values of the fields of the parameter area when the parameter area is expanded.
= *YES
When the parameter area is expanded, equates are also generated for the values of the fields of the parameter area.
= *NO
When the parameter area is expanded, no equates are generated for the values of the fields of the parameter area.
VERSION
Controls generation of the parameter area or of the function call. When the function call is generated, the operand must have the same value as when generating the associated parameter area.
= 1
Generates the parameter area or function call applicable for BS2000/OSD V8.0 (it is not possible to specify a library member).
= 2
Generates the parameter area or function call applicable for BS2000/OSD V9.0 and higher.
Layout of the parameter area
The parameter area must be aligned on a word boundary. It begins with a standard header which MAILFIL initializes as follows:
Function Unit Number | 22 |
Function Number | 32 |
Interface Version Number | 2 if VERSION=2 is specified, 1 otherwise |
Return Code | -1 |
Macro expansion with MF=D and default values for EQUATES, PREFIX and 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
Return code
The return code is placed in the standard header of the parameter area. The parameter area may then not be located in the read-only area, otherwise the program terminates.
The following return codes are generated by MAIL-FILE:
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'00' | X'0000' | No error |
X'00' | X'01' | X'0554' | Format of file name invalid |
X'00' | X'01' | X'0576' | Incorrect operand combination or UNUSED fields not deleted |
X'00' | X'20' | X'05C7' | Internal error in DMS |
X'00' | X'40' | X'05FC' | User ID not entered |
X'00' | X'40' | X'0694' | Not permissible to send file |
X'00' | X'40' | X'0695' | Email address missing |
X'00' | X'40' | X'0696' | Email address of TSOS missing |
Further return codes, whose meanings are defined by conventions valid for all macros, can be found in the table on "Standard header" (standard header).
Furthermore, return codes of DMS interfaces (see the FSTAT and ERASE macros ) and of the Mail-Sender interfaces (YMLSML macro of the software product interNet Services) can be transferred.
When a PLAM library member is specified (LIBELEM operand), return codes from ILAM interfaces (see the PMATCH, PMDTCH, PMOPEN, PMCLOS, PMGETA, PMPOSA, PMDELM macros of the ILAM interface for PLAM) can be transferred. The maincodes of the ILAM interfaces correspond to the decimal message numbers of the PLAM messages (i.e., for example, maincode 00CB corresponds to PLAM message PLA0203).
You can obtain detailed information using /HELP-MSG <msgid>.
Sample calling sequence
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'
Selecting email addresses by means of the job name
MAIL-FILE ascertains the email addresses of the receiver and the sender by means of the user entry of each of the user IDs concerned. To execute the command the user IDs of the receiver and of the sender must each contain an email address (see the SHOW-USER-ATTRIBUTES command, EMAIL-ADDRESS output field). The entry can also contain an address list, i.e. multiple email addresses separated by a comma.
When the sender’s user entry contains an address list, the first address is used as the sender address.
When the receiver’s user entry contains an address list, MAIL-FILE makes a distinction between whether the caller’s user ID (*OWN) or a “foreign” user ID was specified as the receiver. If a foreign user ID is specified, MAIL-FILE sends the email to all addresses. If the home user ID is specified, MAIL-FILE selects the addresses by means of the job name of the calling task:
An address is searched for in which a partial name of the local address part (ahead of the @) begins with the job name (not case-sensitive). Partial names are separated from one another by a period (e.g. first-name.last-name).
For example, the following addresses are selected from the address listAnna.Huber@xy,Anja.Bauer@xy,Anton.Baumann@xy:
Anna.Huber@xywith the job names: ANN, HU, HUBERAnja.Bauer@xywith the job names: ANJ, ANJA, BAUE, BAUERAnton.Baumann@xywith the job names: ANT, BAUM, BAUMAN
Optionally you can also prefix the addresses in the user entry with “address names” in parentheses.
Example: (ANH)Anna.Huber@xy,(ANB)Anja.Bauer@xy,(BMN)Anton.Baumann@xy
The following addresses, for example, are then selected from this address list:
Anna.Huber@xywith the job names: ANH and ANN, HU, HUBERAnja.Bauer@xywith the job names: ANB and ANJ, ANJA, BAUE, BAUERAnton.Baumann@xywith the job names: BMN and ANT, BAUM, BAUMAN
If the job name matches more than one address, the address is selected whose partial name which matches the job name is the shortest. From the address listBeate.Pauli@xy,Pauline.Beck@xy,Paul.Becker@xy, for example, the following addresses are selected:
Beate.Pauli@xywith the job names: PAULI, BEAPauline.Beck@xywith the job names: PAULIN, BE, BECKPaul.Becker@xywith the job names: P, PAUL, BECKER
If the partial name which matches the job name is equally short in more than one address, the first of these addresses is selected.
If more than one partial name in an address matches the job name, only the first partial name is taken into account.
If the calling task does not have a job name or the job name does not match any address in the address list, the following procedure applies:
When the receiver address is ascertained, the entire address list is used, i.e. the email is sent to all addresses.
When the sender address is ascertained, only the first address in the address list is used.