September 2007
Newsletter

Updated October 2008

IOFTech    Maintenance   Release8G       Newsletters    Doc    FAQ    Contact    Home

Did you ever need to be notified by email when a job fails?  Did you ever want to send output from a batch job to someone via email or FTP?  Now there is a simple way to satisfy these requirements with the IOFSEND facility.

• Introduction
• XMITIP
• IOFSEND Batch Step
• SENDMAIL IOF Command
• Email Format
• Installation Instructions

Note that this newsletter was updated in October 2008 to add significant new features including the ability to send job output via FTP.  The new features require that optional fix T8C9064 be installed.  This fix can be applied whether or not IOFSEND was previously installed on a system.

There are many requirements to send JES2 job output to end users via email or FTP.  These include:  

• the need to notify one or more users via email when a critical job or systems task fails.
• the need to provide detailed information about how a job failed.
• the convenience of sending batch output to a user via email.
• the need to send a copy of a job to a PC via FTP or email for archival.

IOF now provides a simple mechanism for using email to notify a user of a job's completion and to optionally attach reports from the job. The notification can be unconditional or dependent on the success or failure of the job. You can also select reports to be emailed directly from IOF display screens.

The XMITIP Shareware Package developed by Lionel Dyck at Kaiser Permanente, Walnut Creek, CA provides a simple  z/OS interface to email.  XMITIP is a series of Rexx execs and is already installed on many z/OS sites.  It can be downloaded from the Internet at no charge. 

The IOF SENDMAIL interface is a series of  IOF Rexx execs that interface IOF to XMITIP.  SENDMAIL provides the ability to send jobs, output groups or sysout data sets to a PC user via email.   These execs are included in the IOF 8D clist library and can be installed on earlier releases with an optional fix.  SENDMAIL is pre-installed on release 8D.

The XMITIP Package

Lionel Dyck, developer of XMITIP, describes it in the XMITIP Guide  Introduction as follows:

XMITIP is a mainframe based electronic mail application that is capable of sending electronic mail to any valid Intranet or Internet address. Along with messages, XMITIP can also send mainframe files in one of several different file attachment formats. The recipients can be on any mail system that connects to the Internet (the world) or Intranet (in house). The Simple Mail Transport Protocol, or SMTP, is used for sending the mail with data sets attached using the appropriate SMTP statements. The name, XMITIP, derives from the TSO TRANSMIT command, which has an alias of XMIT, and from IP, which stands for Internet Protocol. Thus XMITIP is TSO TRANSMIT using the Internet Protocol. XMITIP can be executed as a step within a batch job, under TSO as a command, or under ISPF using a robust ISPF interface. It can also be used within an automated operations tool to generate messages related to system events. XMITIP can be used very effectively as a step within a batch job to send a report generated by that job via electronic mail rather than printing the report. With this approach the report will arrive in the intended users electronic mail inbox within a few minutes after the job completes. This is much faster than waiting for the hours for the report to be printed, removed from the printer, separated from the other reports that were printed at the same time, and then delivered or placed in a mail box for pickup. The user can then view the report online or print as their needs dictate. Some of the features of XMITIP are:

• send electronic mail to one or more addresses
• send a quick message as a page
• send one or more data sets as file attachments in one of the following formats: plain text, HTML, Rich Text Format (RTF), Portable Document Format (PDF), Comma Separated Value (CSV), TSO Transmit (XMIT), and binary
• supports address lists
• supports CC and BCC
• supports Priority, Sensitivity, and Importance
• The ISPF interface:
• field level help for all entry fields
• validation of all entered fields
• address table for lookup and selection
• data set table for multiple data set selection and formatting
• reports the complete XMITIP command syntax generated
• option to create a file with a complete Batch Job which can be submitted, browsed, edited, or copied.

The ISPF interface is an excellent tool to use to model the XMITIP usage and once it is working completely then the generated command can be integrated into a batch job step or TSO application. Included with the XMITIP package are several tools that can be used to invoke XMITIP from other applications. These tools interface to XMITIP from SDSF, from IOF, and from other ISPF applications. XMITIP is written almost completely in z/OS REXX, with one z/OS Assembler program that performs the MIME (Multipurpose Internet Mail Encoding) used for PDF and Binary attachments. The ISPF interface is also written in z/OS REXX using the z/OS ISPF APIs.

If the XMITIP package is already installed at this site, the rest of this section can be skipped.  If XMITIP is not installed, at least the basic parts must be installed before the IOF SENDMAIL interface can be used to send job output via email.  XMITIP is not required to send output via FTP. 

XMITIP can be ordered from Lionel Dyck's web page at:

        http://www.lbdsoftware.com/xmitip.html

This web site gives a good insight into the capabilities of XMITIP. It also provides documentation and installation hints.

Note that XMITIP is a series of Rexx execs that interface to SMTP on the z/OS site.  See the IBM manuals for information on installing SMTP if it is not already installed at your site.

The IOF email applications use only a small part of the XMITIP package.  In fact, IOF SENDMAIL uses only four Rexx execs provided in the XMITIP package.  These execs  are:

• XMITIP - The command used to send a message
• XMITIPCU - The XMITIP customization exec.  This exec must be edited to specify local parameters and definitions  
• XMITLDAP - The local LDAP customization exec. This exec must be edited to specify local parameters if you chose to use the LDAP interface.
• XMITIPZP - The exec called when the ZIP parameter is specified.

If you want to install only enough of XMITIP to support the IOF mail applications,  these three execs are all that you need.  Lional Dyck has permitted us to re-distribute these execs as an IOF optional fix so long as we give full credit to Lionel and Kaiser Permanente for the XMITIP development.  Because XMITIP is continually improving and evolving, we encourage you to download the official version from the web site shown above and to install and use the full package.

IOF Optional fix T8x9059  adds the first three XMITIP execs listed above to your IOF CLIST library.  This fix should not be applied if you already run XMITIP at your site.  If you subsequently install the full XMITIP package at your site, XMITIP, XMITIPCU and XMITLDAP should be removed from the IOF CLIST library.

IOFSEND Batch Step

The IOFSEND cataloged procedure shown below runs the IOFSNDME Rexx exec as a job step in batch TSO.  It notifies a user by email that a job has run and optionally attaches the job's output.  The IOFSEND cataloged procedure should be added to PROCLIB to simplify running the IOFSNDME exec in batch TSO.

A sample cataloged  procedure is shown below.  The procedure has 4 keyword parameters:
 

 //IOFSEND PROC TO=,FROM=,DATA=,DSNDS='IOF.IOFT8C0' 
 //* 
 //*    Send current job results via email 
 //* 
 //*    Input parms are: 
 //*      TO=Required SENDTO email address 
 //*      FROM=Optional FROM email address 
 //*      DATA=           send just the IOF Job Summary 
 //*      DATA=JESDS      add LOG, JCL and MESSAGES data sets 
 //*      DATA=ALL        add all sysout data sets 
 //* 
 //SEND EXEC PGM=IKJEFT1B,PARM='IOFSNDME &TO &DATA FROM &FROM'
 //SYSTSPRT DD SYSOUT=*       XMITIP diagnostic information goes here
 //SYSPROC  DD DISP=SHR,DSN=&DSNDS..CLIST 
 //SYSEXEC  DD DISP=SHR,DSN=SYSTSI.XMITIP.EXEC   xmitip exec library
 //SYSHELP  DD DISP=SHR,DSN=&DSNDS..HELP 
 //SYSTSIN  DD DUMMY  

If the XMITIP execs are included in the IOF CLIST library, the SYSEXEC DD statement is not required . 

Several examples of using IOFSEND with parameters are shown below.  The JCL shown is added as the last step of a JOB or STC.

//NOTIFY  EXEC  IOFSEND,TO='jsmith@aol.com',COND=EVEN

//ABNDNTFY EXEC  IOFSEND,COND=ONLY,
//               TO='job@tsi.net,operator@tsi.net',
//               DATA=JESDS

//      IF    (ABEND | RC > ) THEN
//SEND  EXEC IOFSEND,
//      DATA=ALL,
//      TO='jimboy@mynet.net',
//      FROM='Operator@mycc.com'
//      ENDIF

IOFSEND provides a valuable communication tool to internet users when used with the JCL IF/THEN/ELSE statements or with the COND parameter.  Simple JCL additions can cause users to be notified via email when a job runs, or just when it fails.    A copy of the IOF Job Summary Display for the job will be attached to the email by default.  The Log, JCL and Messages data sets can be added to the attachment by specifying DATA=JESDS.  All sysout data sets can be added to the attachment by specifying DATA=ALL.

IOFSEND SYSIN Parameters

IOFSEND parameters can also be specified in the optional SYSIN dataset.  SYSIN parameters offer significant additional function:

• Allow  FTP parameters to be specified
• Allow selection of specific sysout data sets
• Support for additional email parameters
• Allow output to be zipped

Click here to see detailed specifications of SYSIN parameters.

SENDMAIL IOF Command

The SENDMAIL IOF command is used to send a JOB, Output Group or Sysout Data Set via XMITIP from an interactive IOF session.   SENDMAIL is an ISPF application that prompts for SENDTO, CC, BCC and FROM addresses.  SENDMAIL is both a primary command and a line command on the Job List Menu, Output Group Display, and IOF Job Summary.  For simplicity, SENDMAIL is the only IOF command used on each of these panels.  SENDMAIL can be abbreviated "SEN".

SENDMAIL Option Menu

The SENDMAIL Option Menu is used to enter addresses and other parameters used by the SENDMAIL command.  This option menu is displayed whenever the SENDMAIL command is entered.

------------------- Send Output via XMITIP Options ----------------------
 COMMAND ===> 
 
    NOPROMPT   Disable this panel for the duration of this IOF session
               (Email information below will be used for all jobs) 

 Enter email addresses below where the job(s) should be sent. 

     To ===>  

     CC ===> 
    BCC ===> 
   From ===> 

 Enter the PC file name below or leave blank to have the default 
 file name of JOB/GRP/FILE.jobname.jobid.day.time 

 PC File 
  name ===> JOB.M18NEWOP.J716695._5-23-2007@16.18.html 

The TO address must be specified.  CC, BCC and FROM fields are optional.  When FROM is not specified, the TSO userid and default XMITIP server name are used as the FROM email address.

The default file name under which the output will be saved on the PC is displayed and can be changed on this menu.  Jobs and groups are typically saved as an HTML file, and sysout data sets are saved as a TEXT file by default.

Job List Menu and Output Group Display

SENDMAIL can be used as both a primary command and a line command on the Job List Menu and Output Group Display.

Primary Command

The SENDMAIL command used as a primary command on the Job List Menu or Output Group Display displays the Send Output via XMITIP Options.  The sole reason for this command is to allow addressing information to be specified once for a list of jobs or groups. 

Line Command

The SENDMAIL line command on the Job List Menu or Output Group Display causes the whole job or group to be packaged as HTML and sent via email.  The Send Output via XMITIP Email Options  panel will be displayed to get addressing parameters unless prompting was previously disabled for the IOF session.  The IOF Job Summary for the job, and all the sysout data sets of the job are attached to the email.  When the attachment is browsed by a web browser, the Job Summary data set section provides browser links to each sysout data set.

Job Summary

SENDMAIL can be used as both a primary command and a line command on the IOF Job Summary.

Primary Command

When SENDMAIL is used as a primary command on the Job Summary, the whole job is packaged and sent via XMITIP.  The Send Output via XMITIP Options menu is always displayed.  However, sysout data sets that are excluded from the Job Summary with the EXCLUDE command are not included in the email.  Otherwise, the SENDMAIL primary command on Job Summary has the identical output as that produced by the SENDMAIL line command on the Job List Menu.

Line Command

The SENDMAIL line command on the IOF Job Summary causes the sysout data set to be sent via email.  The Send Output via XMITIP Options menu is always displayed.  The default PC file type is TEXT although this can be overtyped on the Option Menu.

EMail Format

IOFSNDME and the SENDMAIL command produce very similar email formats.  The SUBJECT line describes the output that is included in the mail.  The message text provides slightly more information about the job, group or sysout data set.   A copy of the IOF Job Summary Panel and optionally sysout data sets are attached to the email.  The email client user is notified that a job has completed without opening the email.  More detail can be seen by opening the mail.  Finally, the full IOF Job Summary panel can be displayed to tell more about how the job ran by selecting and/or saving the attachment. 

A typical Outlook panel displaying jobs is shown below.  Note that the SUBJECT line shows the jobname, where it ran, and the job result.  Result of 0 means that all job steps ran with return code 0.  Result "*" means that at least one jobstep did not run.  System and user abends are displayed as Sccc and Ucccc.  The message for the first job, which had user abend 333, is shown below with additional information.

Installation Instructions

The IOF email application is packaged as an optional fix that is included in for all IOF release 8 cumulative fix (CFX) files. This application is not available for IOF release 7.  The fix number is T8x9064, where "x" is the release 8 version.  For example, T8C9064 is the fix for release 8C. 

T8x9064 supersedes fixes T8x9058 and T8x9060, and can be applied whether or not these fixes were previously applied.

Click here to download the cumulative fix file for your release.

Follow the instructions on the maintenance web page to download the appropriate CUMFIX file, receive it and apply the optional fix.  To display optional fixes you must enter OPT when the maintenance dialog displays available fixes. The maintenance adds the members listed below to your IOF libraries.  No other changes to IOF are made.  You will have to run the M13GEN job to install the SENDMAIL command.

If you are not already running XMITIP at the site, you can either order it from Lionel Dyck or apply optional fix T8x9059.  (x is your release 8 version of IOF).  This fix copies XMITIP, XMITIPCU and XMITLDAP to your IOF clist library.  Note that these members should be removed from the IOF clist library if you subsequently install the full XMITIP shareware package.

After applying fix T8x9064 (and T8x9059 if required) the SENDMAIL interactive command and the IOFSNDME  batch TSO command can be used to send jobs, groups or sysout data sets via email or FTP.  Look at the XMITIP command output to diagnose problems with the transmission.  The SYSTSPRT DD statement can be added to the IOFSEND  cataloged procedure to provide XMITIP diagnostic information from batch TSO steps.