FDR E-mail Notification Facility

FDR includes a facility that can send an e-mail message when an FDR operation on a volume completes unsuccessfully, successfully or both. This can be useful when you, the FDR user, are not on-site or are not monitoring FDR. If you have an alpha-numeric pager or cell phone capable of receiving text messages, this can also be used to send a message to the pager or cell phone.

Requirements for successful e-mail

To successfully send an e-mail from FDR, you must:

  • Be running the IBM TCP/IP product (a standard component of z/OS).
  • Have an external Internet connection to your mainframe that allows you to send e-mail or communicate with an external e-mail server. Your firewall, if any, must allow the e-mail or server connection.
  • Have access to a fully capable MTA mail server that supports Simple Mail Transfer Protocol (SMTP). This can be the optional SMTP mail server that is delivered with the IBM TCP/IP product (running on your z/OS system), or an external mail server (check with your mail server administrator to see if it is a fully capable MTA mail server that supports SMTP. CSSMTP is a mail-forwarding SMTP client application and is not a fully capable MTA.).
  • Run the FDR task under a IBM RACF userid with an OMVS segment (or the equivalent in other security systems), since the IBM TCP/IP product uses UNIX System Services (USS) sockets.

The Test E-mail Parameters Example can be used to test if the above requirements have been met and your e-mail parameters are correct.

Sending e-mail

E-mail notifications are supported by all FDR and FDRDSF dumps and restores, as well as all FDRABR operations (volume backups, application backups (FDRAPPL), Archive, and Superscratch).

By default, FDR sends an e-mail only when certain triggering error messages are issued. Optionally, an e-mail indicating a successful operation can be sent. If FDR issues consecutive triggering messages with identical text, the messages after the first are ignored.

The subject line for the e-mail and any message text desired can be specified, with any number of lines of text. FDR supports substituting certain strings in the subject or message text, allowing the message to include the FDR job and/or step name, the name of the system on which the operation executed, and the date/time of the e-mail. The text of the triggering FDR message is included, which usually identifies the volume.

FDR can also e-mail the complete set of messages generated by the FDR operation on the volume. For FDR and FDRDSF, this is supported only if using the FDR subtask option MAXTASKS=nn. For ABR, it is always supported.

The e-mail can be sent to up to five recipients. If your mail server supports group names, you can send it to a group name that can be distributed to many recipients.

If your pager or cell phone company supports sending text messages by e-mail, the message can be directed to your pager or cell phone. Consult your provider for the proper e-mail address and requirements.

FDREMAIL DD statement

To invoke the FDR e-mail facility for a given FDR step, include in the step JCL an FDREMAIL DD statement pointing to the e-mail control statements that are described below. This DD statement can specify a sequential data set, a member of a PDS, or in-line control statements. If it is a data set, it must be LRECL=80, RECFM=F or FB. If the DD statement specifies DUMMY, it is ignored.

No additional options are required, the presence of the DD statement is sufficient to activate the e-mail notification facility. However, to be notified of successful FDR operations as well as failures, specify the operand EMSG=OK on the DUMP or RESTORE statement. For example,

//FDREMAIL DD DISP=SHR,DSN=yourid.FDR.EMAIL //FDREMAIL DD DISP=SHR,DSN=yourid.FDR.CNTL(EMAIL) //FDREMAIL DD * .. e-mail statements .. /*

SYSTCPD DD statement

The SYSTCPD DD statement points to TCP/IP parameters used on your system. It is optional, but if it is present, and it contains the IP address of a domain name server, then you can specify the name of a mail server instead of its IP address; TCP/IP uses the domain name server to resolve the name. Your installation may have defined the name of a default TCPDATA data set, in which case the DD statement can be omitted.

If it is omitted and your installation has not defined a default TCPDATA, you need to specify the IP address of the mail server in “dotted-decimal” format.

If you do not know what to put on this DD statement, consult the system programmer responsible for TCP/IP on your system.

An example of a coded SYSTCPD statement is,

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

Basic e-mail statements

The FDREMAIL DD statement must point to the e-mail statements that define the mail server, the “sender’s” e-mail address, the recipients’ e-mail addresses, and the e-mail text. See Enhanced E-mail Statements for details on sending multiple messages and customizing the message.

These statements must appear in the order shown below, although optional statements can be omitted. Only the first 72 characters of each line are processed. Lines with an asterisk “*” in column 1 are treated as comments, except when they are data lines.

TCPNAME

This optional statement contains the name of the TCP/IP address space (started task) on the system where the FDR program is executing. If omitted, FDR connects to the first active TCP/IP address space, so it can usually be omitted unless a particular TCP/IP stack is needed. There must be exactly one space after TCPNAME. For example, TCPNAME ENSRV001

MAILSERVER

This optional statement contains the name or IP address of the mail server. This server must support the SMTP protocol (consult the mail server administrator if you are not sure). If omitted, FDR attempts to use the SMTP server running on the z/OS system; if that SMTP server is not active, a MAILSERVER statement must be provided. There must be exactly one space after MAILSERVER.

If you have included a SYSTCPD DD statement or your installation has defined a default TCPDATA data set, and the parameters specify the address of a domain name server, the name of the mail server can be specified. For example, MAILSERVER MAIL.MYCOMPANY.COM

The IP address of the mail server can also be specified in standard “dotted-decimal” format. If a name server is not available, the IP address must be specified. For example, MAILSERVER 123.45.6.234

Important

The TCP/IP PING command under TSO can be used to get the IP address of the mail server, for example, PING MAIL.MYCOMPANY.COM

FROM:

This required statement defines the e-mail address of the “sender” of the e-mail, in any format accepted by the mail server, up to 66 characters. This address is used by SMTP for notification of undeliverable messages. It may also be used by the mail server for authentication, so it may need to be a valid address known to that server. For example, FROM:<STORMGMT@MYCOMPANY.COM>

TO: or CC:

This statement defines the e-mail address of a recipient of the e-mail, in any format accepted by the mail server, up to 66 characters. At least one TO: statement must be included and up to five TO: or CC: statements. For example,

TO:<JANEDOE@MYCOMPANY.COM> TO:John_Smith@mycompany.com CC:Bob Jones<BJONES@MYCOMPANY.COM>

SUBJECT:

This required statement defines the subject for the e-mail message. The text may contain symbolic substitutions as described below. For example, SUBJECT: FDR FAILURE JOB=&JOBNAME

Data lines

Optionally include any number of data lines after the SUBJECT: statement to define the e-mail message to be sent. Do not forget that pagers and cell phones may truncate long messages. The text may contain symbolic substitutions as described below. For example,

FDR JOB &JOBNAME FAILED ON SYSTEM &SYSTEMS &MESSAGE

Symbolic substitution

The e-mail subject line or data lines may contain certain symbolic parameters, which FDR replaces with appropriate values before the e-mail is sent. The values are:

&JOBNAME

The name of the FDR job or started task.

&STEPNAME

The name of the FDR step.

&SYSTEMS

The name of the system on which FDR was executing.

&EMAILDATE

The date that the e-mail was generated by FDR, in mm/dd/yyyy format.

&EMAILEDAT

The date that the e-mail was generated by FDR, in dd/mm/yyyy (“European”) format.

&EMAILTIME

The time that the e-mail was generated by FDR, in hh:mm:ss.t format.

&MESSAGE or &MSG

The text of the FDR message that triggered the e-mail. This symbolic must be the last or only thing on the line on which it appears. If this symbolic does not appear in the e-mail text, the message is automatically included as the last line of the message, so it is usually not required unless you want to include the message in the subject text or position it.

&ALLMSG

Results in multiple lines in the e-mail, containing all of the messages associated with the volume. For FDR and FDRDSF, It works only if sub-tasking (MAXTASKS=nn) is used; it always works for FDRABR. This symbolic must be the only thing on the line on which it appears. Do not use on a SUBJECT: line.

Enhanced e-mail statements

In order to meet more complex notification requirements, the FDR e-mail facility can also:

  • Send varying e-mail text to different recipients (for example, send a one line notification to one address, and send the full set of messages to another).
  • Send different e-mail texts depending whether the volume completed successfully or unsuccessfully. You can even vary the e-mail text depending on the FDR message that triggered the e-mail.

The enhanced e-mail is invoked by an additional e-mail statement:

EMAIL:

Indicate the start of an e-mail message definition and terminates the data lines of the previous message. If omitted, there is only a single e-mail definition as described under Basic E-mail Statements. It can optionally appear before the first FROM: statement, and it is inserted after the data lines of a message definition to separate the next message definition. It has an optional operand MSG= that is separated from EMAIL: by one space.

The EMAIL: statement may be followed by the TCPNAME, MAILSERVER, and/or FROM: statements, but if omitted, the previous values are used. It must be followed by one to five TO: or CC: statements to define the recipients of this e-mail. The TO: and CC: statement(s) are followed by a new SUBJECT: statement and optionally new data lines to define the e-mail text.

The MSG= operand controls when the following e-mail is sent and has several forms:

MSG=OK

Send only for successful FDR volume operations (when the triggering message is not followed by “**”).

Important

You must specify the EMSG=OK operand on the main statement to invoke the e-mail processor for successful completions.

MSG=ERR

Send only for unsuccessful FDR volume operations (when the triggering message is followed by “**”).

MSG=nnn

MSG=(nnn,nnn,…)

Send only if the message that triggered the e-mail is FDRnnn. The triggering messages currently include FDR999 (successful, only if EMSG=OK was specified), FDR997 and FDR998 (completed with errors), FDR319 (subtask abend) and FDR302 (control card error) messages.

An example of enhanced e-mail statements is:

MAILSERVER 12.132.14.178 FROM:JOHNDOE@MYCOMPANY.COM EMAIL: MSG=ERR * SEND ALL FAILURE MESSAGES TO DICK TO:DICK<DICK@MYCOMPANY.COM> SUBJECT: FDR FAILED &JOBNAME &STEPNAME &SYSTEMS EMAIL: MSG=302 * IF JOB FAILED FOR CONTROL CARD ERRORS, NOTIFY JANE TO:JANE<JANE@MYCOMPANY.COM> SUBJECT: FDR CONTROL CARD ERROR &MESSAGE JOB &JOBNAME MUST BE RE-SUBMITTED EMAIL: MSG=OK * FOR SUCCESS, SEND ALL MESSAGES TO SPOT TO:SPOT<SPOT@MYCOMPANY.COM> SUBJECT: FDR MESSAGES: &MESSAGE &ALLMSG

Send e-mail for DUMP failure example

Send an e-mail if the FDR backup of volume DATA22 fails. Since no SYSTCPD DD statement is provided, the MAILSERVER statement must specify the IP address of the mail server. The e-mail includes the text of the error message.

//DUMP EXEC PGM=FDR,REGION=0M //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //DISK1 DD UNIT=SYSALLDA,VOL=SER=DATA22,DISP=OLD //TAPE1 DD DSN=BACKUP.VDATA22,UNIT=TAPE,DISP=(,CATLG,DELETE) //FDREMAIL DD * MAILSERVER 12.132.14.178 FROM:<ABC@MYCOMPANY.COM> TO:<XYZ@MYCOMPANY.COM> SUBJECT: DATA22 BACKUP FAILED /* //SYSIN DD * DUMP TYPE=FDR /*

Send e-mail for success or failure example

Send an e-mail for each volume in this step indicating success or failure. Since a SYSTCPD DD statement is provided, the MAILSERVER statement can specify the name of the mail server. “FDRLIST” is the name of a group that is interpreted by the mail server. The e-mail includes the text of the message to identify the volume.

//BACKUP EXEC PGM=FDRDSF,REGION=0M //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSTCPD DD DISP=SHR,DSN=TCPIP.DATA(SYSTEM1) //FDREMAIL DD DISP=SHR,DSN=STGMGMT.FDR.CNTL(EMAIL) //DISK1 DD VOL=SER=BILL01,UNIT=SYSALLDA,DISP=SHR //DISK2 DD VOL=SER=BILL02,UNIT=SYSALLDA,DISP=SHR //DISK3 DD VOL=SER=BILL03,UNIT=SYSALLDA,DISP=SHR //TAPE1 DD DSN=BILL.BACKUP1(+1),DISP=(,CATLG), // UNIT=TAPE,VOL=(,RETAIN),LABEL=1,EXPDT=99000 //TAPE2 DD DSN=BILL.BACKUP2(+1),DISP=(,CATLG), // VOL=(,RETAIN,REF=*.TAPE1),LABEL=2,EXPDT=99000 //TAPE3 DD DSN=BILL.BACKUP3(+1),DISP=(,CATLG), // VOL=REF=*.TAPE2,LABEL=3,EXPDT=99000 //SYSIN DD * DUMP TYPE=FDR,EMSG=OK SELECT DSN=BILL.** /*

Data set “STGMGMT.FDR.CNTL(EMAIL)” contains:

MAILSERVER MAIL.MYCOMPANY.COM FROM:JOHN DOE<JOHNDOE@MYCOMPANY.COM> TO:FDRLIST@MYCOMPANY.COM SUBJECT: FDRDSF BACKUP ENDED &SYSTEMS, JOB &JOBNAME, STEP &STEPNAME MESSAGE - &MESSAGE

Send e-mail to several recipients for failures example

Send an e-mail to several recipients for each volume in this step that fails. The e-mail includes all messages generated for the failing volume. Also, send a 1-line notification to a pager.

//DUMP EXEC PGM=FDRABR,REGION=0M //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //FDREMAIL DD DISP=SHR,DSN=STGMGMT.FDR.CNTL(EMAILALL) //TAPE1 DD DSN=ABR1,UNIT=TAPE,DISP=(,KEEP),EXPDT=99000 //TAPE2 DD DSN=ABR2,UNIT=TAPE,DISP=(,KEEP),EXPDT=99000 //SYSIN DD * DUMP TYPE=FDR MOUNT VOLG=TSO /*

Data set “STGMGMT.FDR.CNTL(EMAILALL)” contains:

MAILSERVER MAIL.MYCOMPANY.COM FROM:<DILBERT@MYCOMPANY.COM> TO:<DOGBERT@MYCOMPANY.COM> TO:<CATBERT@MYCOMPANY.COM> CC:<DILBERT@MYCOMPANY.COM> SUBJECT: DUMP FAILED ON &SYSTEMS &EMAILDATE &EMAILTIME &MSG &ALLMSG EMAIL: TO:Pager<9735552345@VTEXT.COM> SUBJECT: FDR ERROR &MSG

Test e-mail parameters example

This job stream can be used to test your e-mail parameters and verify that you can successfully send an e-mail via SMTP. It causes a control statement error that invokes the e-mail facility.

//BADDUMP EXEC PGM=FDR,REGION=0M //STEPLIB DD DISP=SHR,DSN=fdr.loadlib //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //FDREMAIL DD * HELO domain_name|nnn.nnn.nnn.nnn MAILSERVER 12.132.14.178 FROM:Me<ME@MYCOMPANY.COM> TO:Me<ME@MYCOMPANY.COM> SUBJECT: E-MAIL TEST /* //SYSIN DD * DUMP TYPE=ZZZZ DELIBERATE CONTROL STATEMENT ERROR /*

Important

A “HELO” statement may be necessary to override the default value of “FDR” if the email server validates the domain name value sent by FDREMAIL as seen by an FDR258 message. The HELO statement can be specified as:

HELO

domain_name

The domain name of the email server.

nnn.nnn.nnn.nnn

The dotted-decimal IP address of the host email client.

Default: FDR


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*