SEND-EMAIL

File	212
Statement	`PROCESS`
Task	This view provides the support for sending electronic mails.

Relevant Error Codes

Code	Text
530	Access denied by Security Facility.
675	`HOST-CODE-PAGE` not supported
699	Not enough main storage available.
798	Task was not started under TSOS.
799	Entire Systems Management Adapter internal error.
809	Subsystem not active.
895	`RECIPIENT` must be specified.
895	`SUBJECT` must be specified.
896	Error occurred when executing E-Mail.
897	Mailer response: :1:.
986	No or not enough space for `E-mail Control Block`.
986	No or not enough space for `E-mail Data Block`.

Field Descriptions

Dictionary Field Name	Format/ Length/ Desc/ Mu	Description
ATTACHMENT-SUFFIX	(A4)	The field has a maximum length of 4 characters, so for example if the user sets ATTACHMENT-SUFFIX := 'html' or ATTACHMENT-SUFFIX := 'txt', .html resp. .txt will be appended to the attachment name, making it a valid file extension for e.g. Windows. Also, whole web pages, stored in a DS/Member, can be sent with ATTACHMENT-SUFFIX := 'html' for easier access in a web browser directly from the mail client.
	D
BCC-RECIPIENT	(A128)	Array of max. 20 recipients receiving a "blind carbon copy" of this mail. If blank, no "blind carbon copy" will be sent. This field is optional.
	D
	M/20
CC-RECIPIENT	(A128)	Array of max. 20 recipients receiving a "carbon copy" of this mail. If blank, no "carbon copy" will be sent. This field is optional.
	D
	M/20
DSNAME	(A54)	Fully qualified file name that is attached to this mail as a text file.
	D
ELEMENT	(A64)	Name of LMS element to be attached to this mail.
	D
ELEMENT-TYPE	(A8)	Type of LMS element to be attached to this mail.
	D	Types C and L are not supported.
ELEMENT-PASSWORD	(A8)	Password, for protected element.
	D
ELEMENT-VERSION	(A24)	Version of LMS element to be attached to this mail.
	D
EXTENDED-TEXT	(A250)	Array of max. 60 SMTP reply codes and texts from mail server in case of rejected [CC-/BCC-]RECIPIENTs.
	M/60
FROM-NAME	(A128)	last_name and first_name as additional sender information. Field must not contain any quotation marks. The required quotation marks in the mail header will be added automatically.
	D
FUNCTION	(A8)	Function to be performed. Possible options:
	D	Blank Default. Write a mail record.
		CLOSE All mail records have been written.
		Specify this on the last request.
HOST-CODE-PAGE	(A8)	This field identifies the host code page of all SEND-EMAIL input fields provided by the user. If omitted, ESA uses the value supplied with the startup parameter HOST-CODE-PAGE.
	D	Possible coded character sets (CCS):
		EDF03DRV EBCDIC.DF.03 ISO-7-bit German
		EDF03IRV EBCDIC.DF.03 ISO-7-bit International
		EDF041 EBCDIC.DF.04 ISO-8-bit International
		EDF04DRV EBCDIC.DF.04 ISO-8-bit German
		EDF04F EBCDIC with EURO symbol (ISO code
		variant ISO 8859-15)
IDENTIFIER	(A8)	Required if multiple update views are executing in parallel. All requests for the same view must have the same identifier.
	D
IGNORE-RCPT-REJECT	(A3)	Possible values:
	D	NO The e-mail is not sent if a specified
		RECIPIENT is rejected by the SMTP server
		(default).
		YES The e-mail is sent even if a specified
		RECIPIENT is rejected by the SMTP server.
PASSWORD	(A8)	Password of protected file.
	D
RECIPIENT	(A128)	Array of max. 20 recipients receiving this mail.
	D	At least one recipient is required for the first SEND-EMAIL request to send this mail.
	M/20
RECORD	(A253)	Mail record to be written as line in the message body.
	D	Note:
		If the first RECORD starts with the string "<html" or "<!DOCTYPE HTML", the e-mail is sent with an indication that it contains text in HTML format, otherwise it will be sent as plain text.
REPLY-TO	(A128)	The specified mail address is sent to all mail recipients to provide a specifiy reply address. This field is optional. If omitted, user ID and host name are taken to compose the reply address.
	D
SUBJECT	(A253)	Specifies the subject of the mail.
	D	Field is required for the first SEND-EMAIL request.

Example

The following example illustrates the usage of the SEND-EMAIL view. The PROCESS statement is encapsulated in subroutine SUB-SEND-EMAIL.

DEFINE DATA LOCAL
1 SEND-EMAIL VIEW OF SEND-EMAIL
  2 ERROR-CODE
  2 ERROR-TEXT
  2 NODE
  2 NODE-NAME
  2 SYSTEM-CODE
  2 SYSTEM-MESSAGE-CODE
  2 FUNCTION
  2 SUBJECT
  2 RECORD
  2 RECIPIENT    (1:20)
  2 CC-RECIPIENT (1:20)
  2 IDENTIFIER
1 #FUNCTION      (A008) INIT <" ">
1 #SUBJECT       (A128) INIT <"Test mail">
1 #RECORD        (A080)
1 REDEFINE #RECORD
  2 #RECORD1     (A040)
  2 #RECORD2     (A040)
1 #RECIPIENT     (A128) INIT <"email_address"> <-- change this
1 #NODE          (N005) INIT <node>            <-- change this
END-DEFINE
*
ASSIGN #RECORD1   = "Dear User,"
ASSIGN #RECORD2   = " "
PERFORM SUB-SEND-EMAIL
*
ASSIGN #RECORD1   = "this is a mail sent by a Natural test pr"
ASSIGN #RECORD2   = "ogram."
PERFORM SUB-SEND-EMAIL
*
ASSIGN #RECORD1   = " "
ASSIGN #RECORD2   = " "
PERFORM SUB-SEND-EMAIL
*
ASSIGN #RECORD1  = "Best Regards,"
ASSIGN #RECORD2  = " "
PERFORM SUB-SEND-EMAIL
*
ASSIGN #RECORD1  = "NPR Development"
ASSIGN #RECORD2  = " "
PERFORM SUB-SEND-EMAIL
*
ASSIGN #FUNCTION = 'CLOSE'
ASSIGN #RECORD1  = " "
ASSIGN #RECORD2  = " "
PERFORM SUB-SEND-EMAIL
*
DEFINE SUBROUTINE SUB-SEND-EMAIL
  PROCESS SEND-EMAIL USING NODE      = #NODE
                       ,   FUNCTION  = #FUNCTION
                       ,   SUBJECT   = #SUBJECT
                       ,   RECORD    = #RECORD
                       ,   RECIPIENT = #RECIPIENT
*
  IF ERROR-CODE NE 0
    WRITE    9X   '=' ERROR-CODE
          /  9X   '=' ERROR-TEXT
          /  8X   '=' SYSTEM-CODE
                / '=' SYSTEM-MESSAGE-CODE
    NEWPAGE
    STOP
  END-IF
END-SUBROUTINE
END

Supplementary Information about SEND-EMAIL

The SEND-EMAIL view implements a text-based mail client. The message body is created based on text lines specified in field RECORD. To support a varying number of text lines, SEND-EMAIL was designed as an update view. The mail message body is closed by specifying FUNCTION='CLOSE'.

RECORD is defined as a 253-byte character field. The data specified in the RECORD field will be terminated by carriage return and line feed in the message body.

A zero ERROR-CODE is returned from SEND-EMAIL if the e-mail has been accepted by the SMTP server. This does not necessarily mean that the e-mail could be delivered to the specified RECIPIENT(s) and CC-RECIPIENT(s).

A character set translation is needed before sending all mail data to the configured SMTP target host. Therefore, the input EBCDIC data will be converted to ASCII code page ISO 8859-1. No special characters are supported as RECORD data.

Currently, the SEND-EMAIL view does not support data encryption. The maximum size of one e-mail is limited to 1MB.

The at-sign @ as part of various mail addresses can be supplied as (a) (left bracket, lower case a, right bracket) to simplify the input procedure. If you encounter problems with the @ character, use (a) instead. Error ESY5879 Mailer response: Send RCPT TO failed with RC 550 indicates problems with the RECIPIENT field.

For more information about e-mail administration, see the subsection Run E-Mail Client.