CSSMTP user exit version 3 and version 4

Use the Communication Server SMTP (CSSMTP) exit to check, and subsequently accept or reject, outbound mail from the JES spool data set. For example, you can code an exit to check the MAIL FROM: string on outbound mail.

CSSMTP uses the Dynamic Exit Facility (CSVDYNEX macro) provided by MVS. See z/OS MVS Programming: Assembler Services Guide for more information.

The USEREXIT statement in the CSSMTP configuration, along with the MODIFY CSSMTP,USEREXIT command, defines which user exit is called by CSSMTP. For compatibility with the SMTP server, VERSION2 is provided. VERSION3 is provided to take advantage of the additional features provided by CSSMTP. VERSION4 is like VERSION3 but also provides information about the job that spooled the SYSOUT including the jobname, the job ID, and the job userid.

A sample VERSION3 user exit is included in member CSSMTPV3 in SEZAINST. The name of the macro is EZAYSMTP and the macro is located in SEZANMAC.

The parameter list for the VERSION4 user exit is generated by specifying VERSION=4 on the EZAYSMTP macro call.

EZAYSMTP VERSION=4

If the USEREXIT statement specifies VERSION2, then only RFC 821 syntax for the mail read from JES spool files is allowed. If the USEREXIT statement specifies VERSION3 or NONE, then RFC 821 and RFC 2821 syntax for the mail read from JES spool file is allowed. See USEREXIT statement for more information.

CSSMTPV3 is provided as a programming guide to aid in the implementation of the local policies. It can be found in SEZAINST. If using the CSSMTP exit, a name token (EZATCPIPCSSMTPV3) must be established in SYS1.PARMLIB(PROGxx). If using the VERSION4 CSSMTP exit, a name token (EZATCPIPCSSMTPV4) must be established in SYS1.PARMLIB(PROGxx). See z/OS MVS Initialization and Tuning Guide for more information.

You can use the SETPROG EXIT command to activate and deactivate EZATCPIPCSSMTPV3 or EZATCPIPCSSMTPV4 exit routines. Seez/OS MVS System Commands for more information.

When you design the CSSMTP exit, consider some of the following design points. Code the exit as efficiently as possible; take all efforts to avoid excessive processing or waiting (for example. I/O operations and DNS resolver calls, while within the exit). Efforts to reject mail might be more efficient if extensive scanning of the data portion of the mail message can be avoided. The exit can allow processing to continue or reject the entire mail message and does not have the ability to reject individual segments of a mail message. The mail message contents cannot be changed in any way by the exit. The exit can accept a mail message at any point and disable further exit calls for that mail message. Only commands that are currently implemented by the CSSMTP program and that are syntactically correct are passed to the exit program.

Read and understand RFCs 2505 and RFC 2635 before undertaking this coding effort. More information about CSSMTP commands and standards are documented in RFCs 2821 and 2822.

The CSSMTP dynamically determines if a CSSMTP exit program exists. This determination is based upon the CSSMTP exit program association with the name token EZATCPIPCSSMTPV3 or EZATCPIPCSSMTPV4 using the MVS SETPROG command. If you determine that the exit program needs to be called to interrogate data coming from the JES spool data set, follow these steps:

This topic describes how to call the exit program to interrogate data coming from the JES spool data set.

Perform the following steps to call the exit program to interrogate data coming from the JES spool data set:

1. Add code to the user exit program so that the program is compatible with the JES connection.
   Rules:

   • The connection ID is always the value 257.
   • The EZBPIPV4 field that represents the remote IP address is always 0 for the JES connection.

   For SAF token information, the EZBPTOKP field contains the address of the token. The SAF token length is 80 bytes and the SAF token version is 1. The SAF token provides information about the submitting user ID and the submitter node of the JES data. This data can be compared to the sender information about the MAIL FROM: string. For more information about what is provided in the SAF token, see the ICHRUTKN information in z/OS Security Server RACF Data Areas.

   _________________________________________________________________

2. Compile the user exit with the version 3 or version 4 copy of the EZAYSMTP DSECT. This action recognizes the changes in the parameter list.

   Specify the user exit version in the VERSION parameter of the EZAYSMTP macro call.

   Examples:

               EZAYSMTP VERSION=3         Generate version3 parameters
               EZAYSMTP VERSION=4         Generate version4 parameters
   

   _________________________________________________________________

3. Write the exit in Assembler language. You must use standard z/OS® Assembler entry and exit linkage. See z/OS MVS Programming: Assembler Services Guide for the linkage conventions.

   _________________________________________________________________

A return code of 8 or 12 results in a reply message that is listed in the log and in the error report. The JES spool file is then subject to the action of the BadSpoolDisp statement. See BadSpoolDisp statement for details. See Registers at exit for details about exit return codes.

The user exit is passed by the generated undeliverable mail notification and the error report.

Restriction: This exit must be reentrant and amode 31 in an authorized library.

The exit is invoked with the settings shown in Table 2.