Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

MAIL-FILE

&pagelevel(3)&pagelevel

Send file by email

Component:

BS2000

Functional area:

File processing

Domain:

FILE                                                                                                                                                     

Privileges:

STD-PROCESSING
HARDWARE-MAINTENANCE
SAT-FILE-EVALUATION
SAT-FILE-MANAGEMENT
SECURITY-ADMINISTRATION
TSOS

Function

The MAIL-FILE command 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. 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 element, 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 its content is in PDF format. 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 command 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 command 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 errors in the MSCF cluster
    In the MSCF configuration systems support can specify that a user ID will be notified by email if a critical situation (e.g. loss of connection) occurs.

  • In the case of outputs from utility routines
    Currently, HSMS and MAREN support the transfer of output information and logs. 

Format

MAIL-FILE

FILE-NAME = <filename 1..54> / *SYSLST(...) / *SYSOUT / *LIBRARY-ELEMENT(...)


*SYSLST(...)



|

SYSLST-NUMBER = *STD / <integer 1..99>


*LIBRARY-ELEMENT(...)



|

LIBRARY = <filename 1..54 without-vers>



|

,ELEMENT = <composed-name 1..64 with-under>



|


<composed-name 1..64> with-under(...)



|



|

VERSION = *HIGHEST-EXISTING / *UPPER-LIMIT / <composed-name 1..24 with-under>



|

,TYPE = <alphanum-name 1..8>

,TO = *USER(...)


*USER(...)



|

USER-IDENTIFICATION = *OWN / <name 1..8>

,SUBJECT = *STD / <c-string 1..256 with-low>

,DELETE-FILE = *NO / *YES / *DESTROY

Operands

FILE-NAME = <filename 1..54> / *SYSLST(...) / *SYSOUT / *LIBRARY-ELEMENT(...)
Selects the file to be sent.

FILE-NAME = <filename 1..54>
Name of the file to be sent:

  • The file is a SAM or ISAM file. A PAM file is sent only if its 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.

  • The file may not be only accessible via an RFA connection.

FILE-NAME = *SYSLST(...)
Specifies the system file SYSLST.

SYSLST-NUMBER = *STD
Specifies the system file SYSLST. The 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-NUMBER = <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.

FILE-NAME = *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.

FILE-NAME = *LIBRARY-ELEMENT(...)
An element of a PLAM library is to be sent. All user record types (1 to159) are sent.

LIBRARY = <filename 1..54 without-vers>
Name of the PLAM library.

ELEMENT = <composed-name 1..64 with-under>(...)
Name of the element.

VERSION =
Specifies the version of the element.

VERSION = *HIGHEST-EXISTING
Selects the highest existing version.

VERSION = *UPPER-LIMIT
Selects the highest possible version.

VERSION = <composed-name 1..24 with-under>
Selects the specified version.

TYPE = <alphanum-name 1..8>
Specifies the element type.
Only text elements and PDF files can be sent. Text elements are elements of the types S, M, J, P, D, X and types derived from these provided they contain no block-oriented records. An element containing block-oriented records is sent only if its content is in PDF format.

TO = *USER(...)
Specifies the receiver of the email.

USER-IDENTIFICATION = *OWN / <name 1..8>
User ID whose entry in the user catalog contains the receiver’s email address.
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 section "Return codes").

SUBJECT = *STD / <c-string 1..256 with-low>
Specifies the subject of the email.
*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.

DELETE-FILE = *NO / *YES / *DESTROY
Specifies whether the file or the PLAM library element 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-FILE=*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.

DELETE-FILE = *NO
The file or the PLAM library element is not deleted. The file or the PLAM library element is available again immediately after MAIL-FILE is called.

DELETE-FILE = *YES
The file or the PLAM library element is automatically deleted after it has been sent successfully. The file or the PLAM library element is regarded as having been sent successfully even if it cannot be delivered (e.g. because the email address is unknown).

DELETE-FILE = *DESTROY
This specification has the same effect as DELETE-FILE=*YES. In addition, the file or element content is overwritten with binary zeros when it is deleted. 

Return codes

(SC2)

SC1

Maincode

Meaning/Guaranteed messages



CMD0001

Command executed


1

CMD0202

Syntactical or semantic error in command


32

DMS05C7

Unexpected internal error in DMS


64

DMS0501

Requested catalog not available


64

DMS0512

Requested catalog not available


64

DMS051B

Requested user ID not in pubset


64

DMS051C

User not authorized to access pubset


64

DMS0535

Specified file not shareable


64

DMS0585

Error detected when processing catalog or multiprocessor system


64

DMS05FC

Specified user ID not in HOME pubset


64

DMS0681

DMS error during execution


64

DMS0684

File does not exist


64

DMS068A

Mail sender reported error


64

DMS068B

ILAM reported error


64

DMS0694

Not permissible to send file


64

DMS0695

Email address missing


64

DMS0696

Email address of TSOS user ID missing


130

DMS0524

System address space full


130

DMS0582

File is currently locked or in use and cannot be processed


130

DMS0585

Error detected when processing catalog or multiprocessor system


130

DMS0594

Not enough virtual memory available

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 (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. To execute the command at least the user ID of the receiver must contain at least one email 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. Only if the home user ID is specified does select the addresses by means of the job name of the calling task.

When the sender’s user entry contains an address list, MAIL-FILE selects the sender address by means of the job name of the calling task.

In the address list MAIL-FILE searches for an address 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 list Anna.Huber@xy,Anja.Bauer@xy,Anton.Baumann@xy:

  • Anna.Huber@xy with the job names: ANN, HU, HUBER

  • Anja.Bauer@xy with the job names: ANJ, ANJA, BAUE, BAUER

  • Anton.Baumann@xy with 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@xy with the job names: ANH and ANN, HU, HUBER

  • Anja.Bauer@xy with the job names: ANB and ANJ, ANJA, BAUE, BAUER

  • Anton.Baumann@xy with 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. For example, the following addresses are selected from the address list
Beate.Pauli@xy,Pauline.Beck@xy,Paul.Becker@xy:

  • Beate.Pauli@xy with the job names: PAULI, BEA

  • Pauline.Beck@xy with the job names: PAULIN, BE, BECK

  • Paul.Becker@xy with 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.

Example

/show-job-status   —————————————————————————————————————  (1)

%TSN:     3ZX9       TYPE:    3 DIALOG   NOW:     2012-04-15.150812
%JOBNAME: VOG        PRI:     0 210
%USERID:  COGNIBS3   JCLASS:  JCDSTD     LOGON:   2012-04-15.1428
%ACCNB:   89001      CPU-MAX:   9999     CPU-USED:000001.0700
%STATION: $$$06581   PROC:    FIREBALL
%TID:     00090119   UNP/Q#:    00/000
%CMD:     SHOW-JOB-STATUS
%MONJV:   *NONE

/show-user-attr

%SHOW-USER-ATTRIBUTES --- PUBSET TK82 - USER COGNIBS3       2012-04-15 15:09:05
  . 
  . 
%EMAIL-ADDRESS alfred.holli@incognito.de,
%              joachim.vogi@incognito.de,    —————————————————————————————   (2) 
%              johannes.kuli@incognito.de,
%              mathias.reh@incognito.de
  . 
  . 
%------------------------------------------------------------------------------
%SHOW-USER-ATTRIBUTES           END OF DISPLAY FOR USER COGNIBS3 ON PUBSET TK82

/mail-file dssm.lst   ————————————————————————————————————  (3)

(1)

The user has logged in under the user ID COGNIBS3 with the job name VOG.

(2)

4 email addresses are entered in the user entry (output abbreviated).

(3)

With MAIL-FILE the DSSM.LST file is sent to the home user ID. As the job name VOG can be assigned unambiguously to the address joachim.vogi@incognito.de from the address list of the user entry, MAIL-FILE uses this address as the sender and recipient (see opened email).

 

After the email arrives, it is opened on the PC:

Powered by Atlassian Confluence and Scroll Viewport.