$SndMail

Send an email message

Note: Many $functions now have corresponding Object Oriented methods. The OO equivalent for $SndMail is the Email class, which uses Janus Sockets.

Overview

The SOUL $SndMail function simplifies sending an email message to issuing a single function call. You can easily send an email message using SOUL without writing a procedure and without having an extensive knowledge of sockets or SMTP protocol.

Internet Protocol (IP) addressing

On z/OS systems only, Model 204 supports both IPv6 and IPv4 addressing.

Limitations of $SndMail under z/VM and z/VSE

$SndMail is supported with the following exceptions:

• The SMTPCADD and SMTPSADD addresses must be supplied in internet protocol (IP) address protocol, not as domain names. You must supply IPv4 (dotted-decimal) internet addresses for the SMTPCADD and SMTPSADD parameters.
• Likewise, if the client and server names are specified using the SMAILD image rather than using the CCAIN parameters SMTPCADD and SMTPSADD, the SERVERDDNAME and CLIENTDDNAME values must be supplied rather than the SERVERNAME and CLIENTNAME values.
• Model 204 does not support IPv6 addressing on z/VM or z/VSE systems.

Enabling $SndMail

The first requirement for enabling the use of $SndMail is to set the following four required CCAIN parameters:

Parameter	SMTP purpose
SMTPCADD	SMTP client address. The client is the Model 204 address space. On z/OS systems: Set this parameter to one of the following: Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM. Dotted decimal address, such as 182.148.55.206. IPV6 address, with up to 8 halfwords separated by colons, such as C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01. In other words, the double colon shows that there are missing halfwords of binary zeros. On z/VM or z/VSE systems: Set this parameter to the dotted decimal address, such as 182.148.55.206.
SMTPCPRT	SMTP client port. The default value is 7700.
SMTPSADD	SMTP server address. On z/OS systems: Set this parameter to one of the following: Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM. Dotted decimal address, such as 182.148.55.206. IPV6 address, with up to 8 halfwords separated by colons, such as C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01. On z/VM or z/VSE systems: Set this parameter to the dotted decimal address, such as 182.148.55.206.
SMTPSPRT	SMTP server port. The default value is 25, which is standard for most SMTP servers.

Your system manager can dynamically reset these parameters while the run is up. If you use the domain name for either SMTPCADD or SMTPSADD, you must have the following DD allocated to the Online:

//SYSTCPD DD DSN=TCPIP.PROFILE(TCPDATA),DISP=SHR

This is the TCP/IP profile data set required to support the resolution of IP domain names.

On some SMTP servers, a valid email address is required for the %from argument in the $SndMail function. Most SMTP activity requires a valid SMTP server.

$SndMail and BATCH204

$SndMail is supported in BATCH204 if you relink BATCH204 with the following objects after V7R4 installation:

• TC62 (or TC62DOS on z/VSE systems)
• TCIU
• TCSE
• LU62
• FUNR (or FUNRDOS on z/VSE systems)

After relinking you need to ensure that the following SMTP parameters are set in the ONLINE and BATCH204 CCAIN:

• SMTPCADD
• SMTPSADD
• SMTPCPRT
• SMTPSPRT

$SndMail syntax

The $SndMail function sends an email message using the values you enter for the $SndMail arguments. $SndMail lets you send an email message with an optional attachment.

The syntax for the $SndMail function is:

$SndMail(%subj, %rcpt, %body, %from, %to, %cc, %bcc, 'EMAILD', %attach, 'C')

Where:

• %SUBJ, which is optional, specifies a %variable or literal that contains the topic line.
• %RCPT, which is optional, specifies a %variable or an image that contains the destination addresses, separated by commas.

  If %RCPT is omitted, the destination addresses are taken from the %TO, %CC and %BCC arguments.

  If %RCPT is an image, the image name must be enclosed within quotation marks, for example 'DEPT-ADDR'.

• %BODY specifies a %variable or an image that contains the text of the message. If %BODY is an image, the image name must be enclosed in quotation marks, for example 'MSG-TXT'.
• %FROM specifies a %variable that contains the FROM header field of up to 255 bytes. Although %FROM is optional, you should supply it, otherwise messages could fail when speaking to another SMTP server. If %FROM is omitted, the logged-on user ID is used. The email server may append the domain name to the given %FROM value.
• %TO, %CC, and %BC, which are optional, specify a %variable that contains the TO, CC, and BCC header fields, respectively, of up to 255 bytes each.

  Address must be enclosed in carets (<>), for example: M204-help <M204support@rocketsoftware.com>.

• 'EMAILD', which is optional, specifies image data. The parameter provides the ability to override the values specified in CCAIN for SMTPSPRT, SMTPCPRT, SMTPSADD, and SMTPCADD. If 'EMAILD' is present, it must be in the following format, with the items in the following order:

  * EMAILD - IMAGE WITH SMTP PARAMETERS IMAGE EMAILD SERVERPORT IS BINARY LEN 4  ;*SMTPSPRT CLIENTPORT IS BINARY LEN 4  ;*SMTPCPRT SERVERNAME IS STRING LEN 255  ;*SMTPSADD CLIENTNAME IS STRING LEN 255  ;*SMTPCADD SERVERDD IS STRING LEN 15  ;*Server dotted decimal address IPv4 format (optional) CLIENTDD IS STRING LEN 15  ;*Client dotted decimal address IPv4 format (optional) SERVERIPV6 IS STRING LEN 45  ;*Server dotted decimal address IPv6 format (optional) CLIENTIPV6 IS STRING LEN 45  ;*Client dotted decimal address IPv6 format (optional) END IMAGE

  The SERVERIPV6 and CLIENTIPV6 fields are provided for the IPv6 colon-separated network addresses. These two fields are optional, to provide backward compatibility.

• %ATTACH, which is optional, specifies a %variable or literal with the name of an attachment that will be appended to the message. The attachment is assumed to be in the Universal Buffer at offset 0 (also called position 1). The length of the attachment is defined by the $Buffer_Used value. If the %ATTACH parameter is omitted, there is no attachment.

  The function encodes the attachment using Base64 encoding, and may also translate it depending on the 10th argument.

• 'C', which is optional and is available as of Model 204 version 7.5, specifies that the object in the buffer will be translated to ASCII before being attached to the email. Alternatively, you can set this parameter to a percent variable with the value 'C'. For example, translation to ASCII could be useful if the $SndMail attachment is a CLOB (CHARACTER-LARGE-OBJECT) such as a text document. If this argument is not specified with the value 'C' or 'c', the attachment is sent as binary, that is, without translation.

  In this example, the CLOB.TXT attachment will be translated to ASCII before being attached to the email:

  %RC = $SndMail(%SUBJECT,,%BODY,%FROM,%TO,,,,'CLOB.TXT','C')

Setting CCAIN parameters for $SndMail

You can set the following CCAIN parameters as default values for $SndMail.

• SMTPCADD is the default SMTP client address, the TCP/IP domain for the operating system, for $SndMail. You can sp ecify SMTPCADD as:
  • (z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.
  • (z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.
  • (z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as: C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01. In other words, the double colon shows that there are missing halfwords of binary zeros.

  You can override SMTPCADD for a specific call by entering a different value in the EMAILD argument of the $SndMail function call.

• SMTPCPRT is the default SMTP client port for the $SndMail function. The value can be any value in the user range — normally above 4095 and up to 32767.

  You can override SMTPCPRT for a specific call by entering a different value in the EMAILD argument of the $SndMail function call.

• SMTPSADD is the default SMTP server address for $SndMail. You can specify SMTPSADD as:
  • (z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.
  • (z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.
  • (z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as: C0:12:46:F0:00:00:00:01, which can also be written as C0:12:46:F0::01. In other words, the double colon shows that there are missing halfwords of binary zeros.

  You can override SMTPSADD for a specific call by entering a different value in the EMAILD argument of the $SndMail function call.

• SMTPSPRT is the default SMTP server port for $SndMail. SMTPSPRT is normally set to the standard SMTP value of 25. You can override SMTPSPRT for a specific call by entering a different value in the EMAILD argument of $SndMail.

Examples of running $SndMail

Example 1

%FROM = 'me@mydomain.com' %TO = 'My Friend <you@yourdomain.com>' %BNAME = 'mypicture.jpg' MODIFY BUFFER CLEAR IN LOBSVR FOR 1 RECORD WHERE SVRKEY = %SVRKEY %ISIZE = $LOBLEN(SVRLOB) PRINT 'SIZE OF ' WITH %SVRKEY WITH ' IS ' WITH %ISIZE BUFFER, 1, %ISIZE = SVRLOB, 1, %ISIZE END FOR PRINT 'BUFFER USED IS ' WITH $buffer_used %SUBJECT = 'THIS SENDS A JPG FROM LOBSVR - ' WITH %SVRKEY %BODY = 'THIS BODY CONTAINS ' WITH %SVRKEY %RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,%BNAME)

In the previous example, a binary object (BLOB) is retrieved from the database and placed at position 1 in the buffer. $SndMail sends this as a Base64-encoded attachment.

Note: The second parameter (the RCPTTO addresses) is omitted. The function creates this using the %TO parameter.

Example 2

%TO ='JANE <YOU@YOURCORP.COM>' %BODY='See you at 9:30 AM tomorrow in the conference room' %RC =$SNDMAIL(,,%BODY,,%TO)

Example 3

The EMAILD argument is used to override the default domain names and ports.

IMAGE EMAILD SERVERPORT IS BINARY LEN 4  ;*SMTPSPRT CLIENTPORT IS BINARY LEN 4  ;*SMTPCPRT SERVERNAME IS STRING LEN 255  ;*SMTPSADD CLIENTNAME IS STRING LEN 255  ;*SMTPCADD END IMAGE PREPARE IMAGE EMAILD %EMAILD:SERVERNAME = 'MAIL.SERVER.COM' %EMAILD:CLIENTNAME = 'MYMVSSYSTEM' %EMAILD:SERVERPORT = 25 %EMAILD:CLIENTPORT = 5601 %FROM = 'ME@MYCORP.COM' %TO = 'JANE <YOU@YOURCORP.COM>' * RCPTTO is defined as an image here, allowing the string of * addressees to be more than 255 bytes long. IMAGE RCPTTO EMRCPT1 IS STRING LEN 255 END IMAGE PREPARE IMAGE RCPTTO %RCPTTO:EMRCPT1 = 'YOU@YOURCORP.COM' IMAGE BODY BODY1 IS STRING LEN 240 BODY2 IS STRING LEN 240 END IMAGE PREPARE IMAGE BODY %S = 'EXAMPLE 1' /? SUBJECT LINE  ?/ %BODY:BODY1 = 'THIS IS BODY1 WHICH IS PART OF AN IMAGE' %BODY:BODY2 = 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG' %RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')

Example 4

This example illustrates using EMAILD in an IPV6 environment. The lines that differ from Example 3 are shown in bold.

IMAGE EMAILD SERVERPORT IS BINARY LEN 4  ;*SMTPSPRT CLIENTPORT IS BINARY LEN 4  ;*SMTPCPRT SERVERNAME IS STRING LEN 255  ;*SMTPSADD CLIENTNAME IS STRING LEN 255  ;*SMTPCADD SERVERDD IS STRING LEN 15  ;*Server dotted decimal address IPv4 format (optional) CLIENTDD IS STRING LEN 15  ;*Client dotted decimal address IPv4 format (optional) SERVERIPV6 IS STRING LEN 45  ;*Server dotted decimal address IPv6 format (optional) CLIENTIPV6 IS STRING LEN 45  ;*Client dotted decimal address IPv6 format (optional) END IMAGE PREPARE IMAGE EMAILD %EMAILD:SERVERPORT = 25 %EMAILD:CLIENTPORT = 5601 %EMAILD:SERVERNAME = 'MAIL.SERVER.COM' %EMAILD:CLIENTIPV6 = 'C0:12:46:F0::01' %FROM = 'ME@MYCORP.COM' %TO = 'JANE <YOU@YOURCORP.COM>' * RCPTTO is defined as an image here, allowing the string of * addressees to be more than 255 bytes long. IMAGE RCPTTO EMRCPT1 IS STRING LEN 255 END IMAGE PREPARE IMAGE RCPTTO %RCPTTO:EMRCPT1 = 'YOU@YOURCORP.COM' IMAGE BODY BODY1 IS STRING LEN 240 BODY2 IS STRING LEN 240 END IMAGE PREPARE IMAGE BODY %Y = $X2C('0D25') /? EBCDIC CRLF character is moved to %Y ?/ %S = 'EXAMPLE 1' /? SUBJECT LINE ?/ %BODY:BODY1 = %Y WITH 'THIS IS BODY1 WHICH IS PART OF AN IMAGE' /? %Y will be translated to ASCII CRLF ?/ %BODY:BODY2 = %Y WITH 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG' %RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')

ASCII translation

All text, except an optional binary attachment, is translated from EBCDIC to ASCII before sending.

Line ends

In text that is part of the header and body, you can enter line ends by including EBCDIC CRLF strings (X'0D25') that are translated to ASCII along with the rest of the text.

If you do not enter line ends, your images might display all on one line, depending on your email viewer.

The bold text in this snippet from Example 4 highlights the use of line ends:

PREPARE IMAGE BODY %Y = $X2C('0D25') /? EBCDIC CRLF character is moved to %Y ?/ %S = 'EXAMPLE 1' %BODY:BODY1 = %Y WITH 'THIS IS BODY1 WHICH IS PART OF AN IMAGE' /? %Y to be translated to ASCII CRLF ?/ %BODY:BODY2 = %Y WITH 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG' %RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')

Reserved names

$SndMail uses Interface names CCAEM000 through CCAEM999. The user does not specify these names — the link name is generated by the function.

Socket limits

Up to 31 sockets are available on each link. If no more sockets are available on a particular link (CCAEM000, for example), the next link is tried. Thus, a maximum of 31,000 simultaneous email threads is theoretically possible.

Size of email message

The FROM, TO, CC, BCC, RCPTTO addresses, and body length, excluding the optional binary attachment, must total less than 27454 bytes.

Return code

$SndMail returns a fixed full word binary return code. See Handling error condition return codes for possible values.

RCPTTO parameter

If the $SndMail EMAILD argument is omitted, the RCPTTO addresses are constructed from the addresses contained in the %TO, %CC, and %BCC arguments.

The sum of the lengths of the RCPTTO address string, (If supplied) and the body text cannot exceed 30,700.

Using quotation marks

You must enclose the names of images within quotation marks, for example: 'BODY'. However, do not enclose the percent variable values within quotation marks, for example: %SUBJECT, not '%SUBJECT'.

Server and client names in the EMAILD parameters

In the EMAILD image, on a z/OS system, you can specify either or both the server and client names as domain names, for example: SMTPSERVER.YOURDOMAIN.COM or as an Internet Protocol (IP) address. If you specify the domain name, a TCP/IP call looks up the IP address.

• If one field is present, all fields must be present, even if the optional fields are left blank.
• If a name or port field is absent, it is taken from the CCAIN parameters SMTPSADD, SMTPCADD, SMTPSPRT, and SMTPCPRT.

The two port parameters have defaults: the SMTPSPRT default is 25; the SMTPCPRT default is 7700.

The two address parameters, SMTPSADD and SMTPCADD, can be specified either as domain names of up to 255 bytes or as IP addresses. If the address begins with an alphabetic character (A to Z), it is automatically evaluated as a domain name.

The four CCAIN default parameters SMTPSADD, SMTPCADD, SMTPSPRT, and SMTPCPRT can be examined using VIEW and changed using RESET.

References

For more information about the standards used in this function, please refer to these Internet Request for Comments documents:

• RFC822, Standard for the format of ARPA Internet Text Messages
• RFC2821, Simple Mail Transfer Protocol
• RFC3548, The Base16, Base32, and Base64 Data Encoding

Error codes for $SndMail

$SndMail issues a return code. An error in $SndMail gives a return code of -1, and it is $StatusD that contains the error code.

The negative error codes starting with -999 are listed in Handling error condition return codes.

It is also possible that $SndMail will return a positive error code, which comes from TCP/IP and is documented in the IBM TCP/IP documentation, TCP/IP V3.2 for MVS: API Reference, Appendix D. For example, an error code of 60 means that the connection attempt timed out. $SOCKET calls give the same errors.

However, in the case of a non-zero (error) return code, the following message is issued to the user:

M204.2799: $SndMail error errortext

When an attempt is made to set or reset the SMTPCADD or SMTPSADD parameters and the address translation fails, Model 204 issues the following messages:

RESET SMTPCADD CCAGGGG *** M204.2834: ADDRESS LOOKUP FAILED FOR CCAGGGG *** 1 M204.1123: PARAMETER SMTPCADD NOT RESET

Handling error condition return codes

Handling error condition return codes lists the possible $SOCKET return codes.

$Socket return codes

SMTP Error text	Numeric value	Meaning
ERBADARG	-999	BAD ARGUMENT
ERNOTOPN	-998	NOT OPEN
ERNOSTOR	-997	NO STORAGE
ERIMAGER	-996	IMAGE FAILURE
ERBADLNK	-995	BAD LINK
ERNOTREL	-994	SOCD NOT RELEASED
ERPHYERR	-993	LINK DEAD
ERNOLINK	-992	LINK UNKNOWN
ERTRUNC	-991	VARIABLE TRUNCATION (READ CALL)
ERNOSOCK	-990	SOCKET NOT FOUND
ERTRUNC2	-989	TRUNCATION ERROR ON IMAGE
EROPSYS	-988	FUNCTION UNSUPPORTED ON THIS OPSYS
	-987	Not used
ERNOSRCD	-986	NO SRCD
ERFDSLIM	-985	TOO MANY SOCKETS
ERBADUBN	-984	UNIVERSAL BUFFER NOT THERE
ERBADUBL	-983	UNIVERSAL BUFFER LENGTH ERROR
ERBADUBA	-982	UNIVERSAL BUFFER ALLOCATION ERROR
EREMREAD	-981	ERROR WITH EMAIL SERVER READ
EREMWRIT	-980	ERROR WITH EMAIL SERVER WRITE
ERGHBERR	-979	SKIP=0 ERROR ON GETHOST CALL
ERGHERR1	-978	T1 LT 0 ERROR ON GETHOST CALL
ERGHERR2	-977	NO ADDRESSES RETURNED

When an error message (with code 5xx) is returned from the SMTP server, the following error message is displayed:

M204.2796: 'SMTP %C'

where %C is the error message returned by SMTP.

For the other error codes above, the following error message is returned, in addition to $StatusD being set.

M204.2799: '$SndMail error errorText'

where %C is listed in the following table:

Error text message possibilities for M204.2799

%C in message 2799	$StatusD code(s)
IN PARAMETER	999
- SOCKET NOT FOUND	990
- FUNCTION NOT SUPPORTED ON THIS SYSTEM	998
- NO SRCD	986
- TOO MANY SOCKETS	985
WITH UNIVERSAL BUFFER	984, 983, 982
Reading from SMTP server	981
Writing to SMTP server	980
Using GETHOSTBYNAME lookup	979, 978, 977
GETTING STORAGE	997
IN IMAGE PROCESSING	996
WITH TCP LINK	995, 998, 993, 992
- SOCD NOT RELEASED	994
READING DATA - TRUNCATION	991