A Simple Job History System

This newsletter describes a simple job history system that is implemented with an IOF Rexx exec. IOF Rexx execs can extract all information displayed on IOF screens and execute all IOF functions. For tutorial purposes three intermediate versions of this sample Rexx exec are shown. All three versions will run.

First Version

The first version of our job history system appends the log, JCL and messages sysout data sets for a job to a sequential history data set. In this version the data set name is a constant (JOBS.JOBHIST) and minimal error checking is provided.

/*-- JOBHIST IOF Rexx Exec  ------------------------------*/
/*   Version 1. Minimal error checking version.           */
/*                                                        */
/*   This exec must be invoked from the IOF Job Summary   */
/*   Panel.  It snaps a copy of the job's system data     */
/*   sets to the user's JOBS.JOBHIST data set.            */
/*--------------------------------------------------------*/

/*--------------------------------------------------------*/
/*   Establish the IOF Rexx addressing environment.       */
/*--------------------------------------------------------*/

address IOF

/*--------------------------------------------------------*/
/*   Define the job history data set name. This data      */
/*   set name will be prefixed with the user's current    */
/*   TSO prefix.                                          */
/*--------------------------------------------------------*/

HistDSN = "JOBS.JOBHIST"

/*--------------------------------------------------------*/
/*   Determine if the history data set exists.  If it     */
/*   does not exist, create it.  Otherwise mod the new    */
/*   history to the existing data set.                    */
/*--------------------------------------------------------*/

if SYSDSN(HistDSN) \= "OK" then
  "SD DA("HistDSN") LRECL(133) RECFM(VBA) TRACKS(10,10)"
else
  "SD DA("HistDSN") MOD"

/*--------------------------------------------------------*/
/*   Snap a copy of the job's log, jcl and messages       */
/*   files to the history data set.                       */
/*--------------------------------------------------------*/

"1-3 SNAP"

/*--------------------------------------------------------*/
/*   Close the history data set.                          */
/*--------------------------------------------------------*/

"SNAPCLOS"

You can test this version by copying the Rexx exec above into your SYSPROC or SYSEXEC library as member JOBHIST. To save the history for a job, select it from the IOF Job List Menu. Then, enter %JOBHIST in the command area of the IOF Job Summary Panel  for the designated job.

Second Version

The second version adds the ability to specify the history data set name as an argument to the JOBHIST command. It also adds several error checks and issues appropriate error messages.

/*-- JOBHIST IOF Rexx Exec  ------------------------------*/
/*   Version 2.  Several error checks added. Optional     */
/*   history DSN from input argument.                     */
/*                                                        */
/*   This exec must be invoked from the IOF Job Summary   */
/*   Panel.  It snaps a copy of the job's system data     */
/*   sets to the user's JOBS.JOBHIST data set.            */
/*--------------------------------------------------------*/

/*--------------------------------------------------------*/
/*   Establish the IOF Rexx addressing environment.       */
/*--------------------------------------------------------*/

address IOF

/*--------------------------------------------------------*/
/*   Verify that JOBHIST was invoked on the IOF Job       */
/*   Summary Panel by checking the HELP panel name.       */
/*   Give error message and quit if on wrong panel.       */
/*--------------------------------------------------------*/

"TSICOPY NAME(HELP) TO(REXX) SECTION(PANEL)"
if help \= "JOBSUM" then do
  say "JOBHIST exec must be invoked on the Job Summary Panel"
  exit
  end

/*--------------------------------------------------------*/
/*   Define the job history data set name. This data      */
/*   set name will be prefixed with the user's current    */
/*   TSO prefix. If the caller supplied an argument to    */
/*   the exec, use it as the data set name.  Otherwise    */
/*   use the default data set name.                       */
/*--------------------------------------------------------*/

parse arg HistDSN
if HistDSN = '' then HistDSN = "JOBS.JOBHIST"

/*--------------------------------------------------------*/
/*   Determine if the history data set exists.  If it     */
/*   does not exist, create it.  Otherwise mod the new    */
/*   history to the existing data set.                    */
/*--------------------------------------------------------*/

if SYSDSN(HistDSN) \= "OK" then
  "SD DA("HistDSN") LRECL(133) RECFM(VBA) TRACKS(10,10)"
else
  "SD DA("HistDSN") MOD"

/*--------------------------------------------------------*/
/*   Check the return code from the SD command.  If non   */
/*   zero, quit with a WARNING message.  The return code  */
/*   keys the message.                                    */
/*--------------------------------------------------------*/

if rc \= 0 then do
  "WARNING" rc
  exit
  end

/*--------------------------------------------------------*/
/*   Snap a copy of the job's log, jcl and messages       */
/*   files to the history data set.                       */
/*--------------------------------------------------------*/

"1-3 SNAP"

/*--------------------------------------------------------*/
/*   Save the SNAP return code for possible WARNING.      */
/*--------------------------------------------------------*/

snaprc = rc

/*--------------------------------------------------------*/
/*   Close the history data set.                          */
/*--------------------------------------------------------*/

"SNAPCLOS"

/*--------------------------------------------------------*/
/*   Check SNAP return code. If non-zero, issue a         */
/*   WARNING message that describes the problem.          */
/*--------------------------------------------------------*/

if snaprc \= 0 then "WARNING" snaprc

Copy the new version to your SYSPROC or SYSEXEC library as member JOBHIST and enter %JOBHIST on the Job Summary Panel to test it. Optionally, you can enter %JOBHIST MY.HISTORY.DS to copy the job history to your data set MY.HISTORY.DS.

Third Version for IOF Release 7D

IOF Release 7D has several enhancements designed to simplify building Rexx execs and clists. This last version of JOBHIST uses features that are available only in Release 7D or later:

• The new TSIMSG command is used to raise standard IOF error messages instead of blasting them to the screen with Rexx "SAY" commands.
• The new SNAPTEXT command is used to add a skip to top-of-form and separator text before each new set of job history records.
• The new IOF$SH1 exec is called to add block header text between each new set of job history records.

Click here to see the Release 7D version of the JOBHIST exec.

Summary

Hopefully, this example has been useful in demonstrating how easy it is to tailor automated IOF functions using IOF execs and clists. If you have questions about these examples, send email to IOFTech@Triangle-Systems.Com. Additional examples of IOF execs and clists will be the subject of future newsletters.