0000835: Support write of files as mail attachment over the SYSOUT(TCPCSMTP)

(0001230)
Falk Reichbott (administrator)
2019-05-08 11:02

Technote (FAQ)

Question

Is it possible to send an email attachment outbound from z/OS using either the Simple Mail Transfer Program (SMTP) or Communications Server SMTP (CSSMTP) applications?
Answer

Yes, but the SMTP and CSSMTP applications do not directly support email attachments. For more information on the limitations of SMTP and CSMTP in sending email attachments, see topic 15.3 Multipurpose Internet Mail Extensions (MIME) in the IBM Redbooks publication TCP/IP Tutorial and Technical Overview.

It is possible to send an email attachment by coding Multipurpose Internet Mail Extensions (MIME) headers within the email body. This Technote contains two examples of how to use MIME with the SMTP or CSSMTP servers. The second example also illustrates how to use concatenated datasets within an email body.

Both of these working (tested) examples will send a base64 encoded certificate as an attachment in an email. The base64 encoded certificate was created using the z/OS Resource Access Control Facility (RACF) EXPORT FORMAT(CERTB64) command.

Note that these attachments are composed of Extended Binary Coded Decimal Interchange Code (EBCDIC) characters. You cannot send a binary or non-text attachment because the SMTP and CSSMTP applications will translate everything into American Standard Code for Information Interchange (ASCII) before sending the content to a destination SMTP mailer on the network.

Example 1: system input stream (in line) MIME content

//SMTPBAT EXEC PGM=IEBGENER
//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSUT2 DD SYSOUT=(B,CSSMTP)
//SYSUT1 DD *
HELO ADCDTEST
MAIL FROM:<ibmuser@zpdt.example.com>
RCPT TO:<mattenuttall@example.net>
DATA
From: matt@zpdt.example.com
To: mattenuttall@example.net
Subject: MIME test
MIME-Version: 1.0
Content-type: multipart/mixed; boundary="=_frontier"

Comments can go here if you like..
--=_frontier
Content-Type: text/plain;

Hi Friend;
This is the body of the message. I have attached a Base 64 encoded certificate.
Regards -- Matt

--=_frontier
Content-Type: application;
Content-Disposition: attachment; filename=cert.cer;
Content-Transfer-Encoding: 8bit;

-----BEGIN CERTIFICATE-----
MIIBtTCCAV+gAwIBAgIBADANBgkqhkiG9w0BAQUFADAxMQ8wDQYDVQQGEwZDYW5h
ZGExDDAKBgNVBAoTA0lCTTEQMA4GA1UEAxMHTnV0dGFsbDAeFw0wMTAxMDEwNDAw
MDBaFw0yMjAxMDEwMzU5NTlaMDExDzANBgNVBAYTBkNhbmFkYTEMMAoGA1UEChMD
SUJNMRAwDgYDVQQDEwdOdXR0YWxsMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBANGt
XZC77TvlyUmCfJFB6FNBeabDFMZ27kVOoqzivNNAfS9nnZlKzhKAn8bZDKyN1VvE
Hqoc9ulJeHE06n7cI2MCAwEAAaNiMGAwPwYJYIZIAYb4QgENBDITMEdlbmVyYXRl
ZCBieSB0aGUgU2VjdXJpdHkgU2VydmVyIGZvciB6L09TIChSQUNGKTAdBgNVHQ4E
FgQUwXirDP0rK8sCfUUwqrArKvi2B6owDQYJKoZIhvcNAQEFBQADQQBjFTwMElwQ
XM38+5BZphwx7ZtdFWBFuOKv9H4mIVJ8rKmoBH7evul88tnuzM2iZ3F+cv4iKvh9
6IJwORKARTpa
-----END CERTIFICATE-----
--=_frontier
.
QUIT
/* END OF JCL

Why not use a DD card to point directly to the dataset containing the exported RACF certificate? RACF creates exported certificates with a variable blocking record format. The preceding example uses SYSUT1 with in stream Data Definition (DD). This means that the email content exists directly on the Job Entry Subsystem (JES) spool. JES spool files are a fixed record format environment. IEBGENER does not allow SYSUT1 to mix fixed and variable record formats.

One way to get around this is to use variable record format datasets for the entire mail contents: headers, data and attachments. This can be done with concatenated DDs. Our JCL now looks like example 2 below.

Example 2: email headers and attachments in VB datasets.

//SMTPBAT EXEC PGM=IEBGENER
//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSUT2 DD SYSOUT=(B,SMTP)
//SYSUT1 DD DISP=SHR,DSN=IBMUSER.SMTP.PREAMBLE
// DD DISP=SHR,DSN=IBMUSER.TESTCERT
// DD DISP=SHR,DSN=IBMUSER.SMTP.POSTFIX
/* END OF JCL

The contents of IBMUSER.SMTP.PREAMBLE in example 2 are as follows:

HELO ADCDTEST
MAIL FROM:<ibmuser@zpdt.example.com>
RCPT TO:<mattenuttall@example.net>
DATA
From: matt@zpdt.example.com
To: mattenuttall@example.net
Subject: MIME test
MIME-Version: 1.0
Content-type: multipart/mixed; boundary="=_frontier"

Comments can go here if you like..
--=_frontier
Content-Type: text/plain;

Hi Friend;
This is the body of the message. I have attached a Base 64 encoded
certificate for you.
Regards -- Matt

--=_frontier
Content-Type: application;
Content-Disposition: attachment; filename=cert.cer;
Content-Transfer-Encoding: 8bit;
<blank line here>

Note that there should always be a blank line after the content headers.
The contents of IBMUSER.SMTP.POSTFIX in example 2 are as follows:

--=_frontier
.
QUIT

The IBMUSER.TESTCERT dataset contains the certificate that was exported from the RACF database using base64 format.

For more information on the MIME encoding used in these examples, see Request For Comments (RFC) 2045, 2046 and 4288.

(0001231)
Falk Reichbott (administrator)
2019-05-08 11:09

https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.halz002/sendcssmtp.htm [^]

(0001302)
Falk Reichbott (administrator)
2020-03-13 01:54

Add format.mail() to SYSOUT allocation in FALLOC object

(0001303)
Falk Reichbott (administrator)
2020-03-13 01:54

Add format.mail() to SYSOUT allocation in FALLOC object

Issue History
Date Modified	Username	Field	Change
2016-11-23 17:38	Falk Reichbott	New Issue
2016-11-23 17:38	Falk Reichbott	Status	new => assigned
2016-11-23 17:38	Falk Reichbott	Assigned To	=> Falk Reichbott
2016-11-23 17:38	Falk Reichbott	Relationship added	related to 0000834
2017-01-02 14:30	Falk Reichbott	Summary	Support write of files as attachment over the SYSOUT(TCPCSMTP) => Support write of files as mail attachment over the SYSOUT(TCPCSMTP)
2017-08-31 16:54	Falk Reichbott	Target Version	5.1.16 => 5.1.18
2018-03-05 08:17	Falk Reichbott	Target Version	5.1.18 => 5.1.20
2019-02-28 17:35	Falk Reichbott	Target Version	5.1.20 => 5.1.22
2019-05-08 11:02	Falk Reichbott	Note Added: 0001230
2019-05-08 11:09	Falk Reichbott	Note Added: 0001231
2020-03-13 01:54	Falk Reichbott	Note Added: 0001302
2020-03-13 01:54	Falk Reichbott	Status	assigned => resolved
2020-03-13 01:54	Falk Reichbott	Fixed in Version	=> 5.1.22
2020-03-13 01:54	Falk Reichbott	Resolution	open => fixed
2020-03-13 01:54	Falk Reichbott	Note Added: 0001303

Notes
(0001230) Falk Reichbott (administrator) 2019-05-08 11:02	Technote (FAQ) Question Is it possible to send an email attachment outbound from z/OS using either the Simple Mail Transfer Program (SMTP) or Communications Server SMTP (CSSMTP) applications? Answer Yes, but the SMTP and CSSMTP applications do not directly support email attachments. For more information on the limitations of SMTP and CSMTP in sending email attachments, see topic 15.3 Multipurpose Internet Mail Extensions (MIME) in the IBM Redbooks publication TCP/IP Tutorial and Technical Overview. It is possible to send an email attachment by coding Multipurpose Internet Mail Extensions (MIME) headers within the email body. This Technote contains two examples of how to use MIME with the SMTP or CSSMTP servers. The second example also illustrates how to use concatenated datasets within an email body. Both of these working (tested) examples will send a base64 encoded certificate as an attachment in an email. The base64 encoded certificate was created using the z/OS Resource Access Control Facility (RACF) EXPORT FORMAT(CERTB64) command. Note that these attachments are composed of Extended Binary Coded Decimal Interchange Code (EBCDIC) characters. You cannot send a binary or non-text attachment because the SMTP and CSSMTP applications will translate everything into American Standard Code for Information Interchange (ASCII) before sending the content to a destination SMTP mailer on the network. Example 1: system input stream (in line) MIME content //SMTPBAT EXEC PGM=IEBGENER //SYSIN DD DUMMY //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSUT2 DD SYSOUT=(B,CSSMTP) //SYSUT1 DD * HELO ADCDTEST MAIL FROM:<ibmuser@zpdt.example.com> RCPT TO:<mattenuttall@example.net> DATA From: matt@zpdt.example.com To: mattenuttall@example.net Subject: MIME test MIME-Version: 1.0 Content-type: multipart/mixed; boundary="=_frontier" Comments can go here if you like.. --=_frontier Content-Type: text/plain; Hi Friend; This is the body of the message. I have attached a Base 64 encoded certificate. Regards -- Matt --=_frontier Content-Type: application; Content-Disposition: attachment; filename=cert.cer; Content-Transfer-Encoding: 8bit; -----BEGIN CERTIFICATE----- MIIBtTCCAV+gAwIBAgIBADANBgkqhkiG9w0BAQUFADAxMQ8wDQYDVQQGEwZDYW5h ZGExDDAKBgNVBAoTA0lCTTEQMA4GA1UEAxMHTnV0dGFsbDAeFw0wMTAxMDEwNDAw MDBaFw0yMjAxMDEwMzU5NTlaMDExDzANBgNVBAYTBkNhbmFkYTEMMAoGA1UEChMD SUJNMRAwDgYDVQQDEwdOdXR0YWxsMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBANGt XZC77TvlyUmCfJFB6FNBeabDFMZ27kVOoqzivNNAfS9nnZlKzhKAn8bZDKyN1VvE Hqoc9ulJeHE06n7cI2MCAwEAAaNiMGAwPwYJYIZIAYb4QgENBDITMEdlbmVyYXRl ZCBieSB0aGUgU2VjdXJpdHkgU2VydmVyIGZvciB6L09TIChSQUNGKTAdBgNVHQ4E FgQUwXirDP0rK8sCfUUwqrArKvi2B6owDQYJKoZIhvcNAQEFBQADQQBjFTwMElwQ XM38+5BZphwx7ZtdFWBFuOKv9H4mIVJ8rKmoBH7evul88tnuzM2iZ3F+cv4iKvh9 6IJwORKARTpa -----END CERTIFICATE----- --=_frontier . QUIT /* END OF JCL Why not use a DD card to point directly to the dataset containing the exported RACF certificate? RACF creates exported certificates with a variable blocking record format. The preceding example uses SYSUT1 with in stream Data Definition (DD). This means that the email content exists directly on the Job Entry Subsystem (JES) spool. JES spool files are a fixed record format environment. IEBGENER does not allow SYSUT1 to mix fixed and variable record formats. One way to get around this is to use variable record format datasets for the entire mail contents: headers, data and attachments. This can be done with concatenated DDs. Our JCL now looks like example 2 below. Example 2: email headers and attachments in VB datasets. //SMTPBAT EXEC PGM=IEBGENER //SYSIN DD DUMMY //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSUT2 DD SYSOUT=(B,SMTP) //SYSUT1 DD DISP=SHR,DSN=IBMUSER.SMTP.PREAMBLE // DD DISP=SHR,DSN=IBMUSER.TESTCERT // DD DISP=SHR,DSN=IBMUSER.SMTP.POSTFIX /* END OF JCL The contents of IBMUSER.SMTP.PREAMBLE in example 2 are as follows: HELO ADCDTEST MAIL FROM:<ibmuser@zpdt.example.com> RCPT TO:<mattenuttall@example.net> DATA From: matt@zpdt.example.com To: mattenuttall@example.net Subject: MIME test MIME-Version: 1.0 Content-type: multipart/mixed; boundary="=_frontier" Comments can go here if you like.. --=_frontier Content-Type: text/plain; Hi Friend; This is the body of the message. I have attached a Base 64 encoded certificate for you. Regards -- Matt --=_frontier Content-Type: application; Content-Disposition: attachment; filename=cert.cer; Content-Transfer-Encoding: 8bit; <blank line here> Note that there should always be a blank line after the content headers. The contents of IBMUSER.SMTP.POSTFIX in example 2 are as follows: --=_frontier . QUIT The IBMUSER.TESTCERT dataset contains the certificate that was exported from the RACF database using base64 format. For more information on the MIME encoding used in these examples, see Request For Comments (RFC) 2045, 2046 and 4288.

(0001231) Falk Reichbott (administrator) 2019-05-08 11:09	https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.halz002/sendcssmtp.htm [^]

(0001302) Falk Reichbott (administrator) 2020-03-13 01:54	Add format.mail() to SYSOUT allocation in FALLOC object

(0001303) Falk Reichbott (administrator) 2020-03-13 01:54	Add format.mail() to SYSOUT allocation in FALLOC object