IDIUTIL ListHF user exit

The following describes the IDIUTIL ListHF user exit.

Purpose

This exit can be used to control the listing of a fault entry during history file management using the IDIUTIL batch utility with the LISTHF control statement (for details, see LISTHF control statement). This control is provided by setting the data area field UTL.PERFORM_ACTION to 'Y' if the entry should be listed, or to 'N' if not. The field UTL.PERFORM_ACTION is set to 'Y' before invoking the exit. See UTL - IDIUTIL Batch Utility user exit parameter list for details about the UTL data area.

The fault entries for which the user exit is invoked are those that match the specified LISTHF control statement criteria.

When invoked

This exit is invoked once for each fault entry in a history file whenever the IDIUTIL batch utility is executed using the LISTHF control statement.

Parameters

How parameters are passed to the exit depends on the exit type, REXX or load module.

Fault Analyzer initializes the parameter lists using current values for the particular fault and processing options in effect before invoking the Notification user exit.

REXX

Two stems are available to the exit:

ENV.
Contains defined symbols for all fields in the ENV data area (see ENV - Common exit environment information).
UTL.
Contains defined symbols for all fields in the UTL data area (see UTL - IDIUTIL Batch Utility user exit parameter list).

The defined variable names are identical to the field names. For example, to access the field VERSION in the ENV data area, use the REXX variable ENV.VERSION.

Load module

At entry to this exit, R1 contains the 31-bit address of a parameter list comprising two fullwords:

31-bit ENV address in word 1.
Address of an ENV data area (see ENV - Common exit environment information).
31-bit UTL address in word 2.
Address of a UTL data area (see UTL - IDIUTIL Batch Utility user exit parameter list).

Note: The high-order bit is on to indicate that this parameter is the last parameter passed.

Example 1: Invoking the IDIUTIL ListHF user exit

The following is an example of an IDIUTIL ListHF user exit that is written in REXX.

Figure 1. Sample REXX IDIUTIL ListHF user exit 1

/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if UTL.VERSION <> 1 then
  say 'Note: UTL data area version change - field usage review required!'
UTL.PERFORM_ACTION = 'Y'  /* List current entry */

If the above sample exit existed as member ABC in data set X.Y.Z, then providing the JCL DD statement

//IDIEXEC DD DISP=SHR,DSN=X.Y.Z

and the IDIUTIL batch utility control statement

Exits(LISTHF(REXX(ABC)))

in your IDIUTIL batch utility history file management job would cause the exit to be invoked.

Example 2: Creating a custom report and CSV file of fault entries with the IDIUTIL ListHF user exit

The following is an example of an IDIUTIL ListHF user exit that is written in REXX.

This sample exit shows how one might write a customized report, as well as a comma-delimited file that can be used as input to a spreadsheet application.

In addition to the fields used, any other fields that are available from the ENV or UTL data areas can be included.

The report that is written by the provided sample includes the columns:

Fault ID
Date
Time
Lock
Username
User Title
CPU Sec

See Available columns for explanations of the column data, except for "CPU Sec", which is the total CPU time used by Fault Analyzer based on ENV.CPU_HSECONDS. See CPU_HSECONDS in ENV - Common exit environment information for more information about this value.

The customized report is written to DDname MYREP. A MYREP DD statement must be included in the IDIUTIL job that invokes this exit, for example:

//MYREP DD SYSOUT=*

The comma-delimited file is written to DDname COMMA. A COMMA DD statement must be included in the IDIUTIL job that invokes this exit, for example:

//COMMA DD SYSOUT=*

The persistent user field, ENV.USER_1, is used to record the fact that the report header has been written.

Figure 2. Sample REXX IDIUTIL ListHF user exit 2

/* First ensure that the current data area versions match the         */
/* versions as at the time of coding the exit.                        */
If ENV.VERSION <> 5 Then
  Say 'Note: ENV data area version change - field usage review',
      'required!'
If UTL.VERSION <> 2 then
  Say 'Note: UTL data area version change - field usage review',
      'required!'
If ENV.USER_1='' Then Do
  /* Write report header */
  out.1="Fault ID Date       Time     Lock Username",
        "User Title                               CPU Sec"
  out.2="-------- ---------- -------- ---- --------",
        "---------------------------------------- -------"
  ADDRESS MVS "EXECIO 2 DISKW MYREP (STEM out."
  /* Write comma-delimited file header */
  out.1="Fault ID,Date,Time,Lock,Username,User Title,CPU Sec"
  ADDRESS MVS "EXECIO 1 DISKW COMMA (STEM out."
  ENV.USER_1='done'     /* Flag header done.                          */
End
/* The fault ID value is placed right-aligned in a work field.        */
fault_id=COPIES(' ',8-length(ENV.FAULT_ID))||ENV.FAULT_ID
/* The following lines use the REXX INSERT command to ensure that the */
/* work fields for each value are padded with blanks to fit the       */
/* report column width.                                               */
/* For information about the maximum with of any field, refer to the  */
/* User's Guide and Reference "Data Areas" chapter.                   */
abend_date=INSERT(ENV.ABEND_DATE,'',,10)
abend_time=INSERT(ENV.ABEND_TIME,'',,8)
lock_flag =INSERT(ENV.LOCK_FLAG,'',,4)
user_name =INSERT(ENV.USER_NAME,'',,8)
user_title=INSERT(ENV.USER_TITLE,'',,40)
/* If available, the CPU time in 1/100s of a second is changed to a   */
/* number of seconds with two decimal digits.                         */
if ENV.CPU_HSECONDS='' then cpu_sec=''
else cpu_sec=FORMAT(ENV.CPU_HSECONDS/100,4,2)
/* Write report line for this fault entry.                            */
out.1=fault_id abend_date abend_time lock_flag user_name user_title,
      cpu_sec
ADDRESS MVS "EXECIO 1 DISKW MYREP (STEM out."
/* Write comma-delimited line for this fault entry.                   */
out.1=fault_id","abend_date","abend_time","lock_flag","user_name,
      ","user_title","cpu_sec
ADDRESS MVS "EXECIO 1 DISKW COMMA (STEM out."
UTL.PERFORM_ACTION='N'  /* Optionally, suppress the standard report.  */
Exit 0

The above sample exit is provided as member IDISUTL1 in the IDI.SIDISAM1 data set.

The following JCL could be used to run the sample:

//IDIUTIL  JOB parms
//RUNUTIL  EXEC PGM=IDIUTIL
//SYSPRINT DD SYSOUT=*
//MYREP    DD SYSOUT=*
//COMMA    DD SYSOUT=*
//IDITRACE DD SYSOUT=*       (Optional)
//IDIEXEC  DD DISP=SHR,DSN=IDI.SIDISAM1
//SYSIN    DD  *
Exits(LISTHF(REXX(IDISUTL1)))
FILES(my.histfile)
LISTHF
/*

Example 3: Collecting abend data for later statistical analysis with the IDIUTIL user exit

History files are dynamic. A fault entry can be deleted from a history file explicitly or by automatic space management. If you want to use fault entry data as input to an analytics application, you might need to collect and preserve the fault entry data outside of the history file. The IDISUTL2 member of the IDI.SIDISAM1 data set is a sample REXX program that you can run regularly for this purpose.

The sample JCL at the end of the IDISUTL2 member runs the RUNUTIL and MERGE steps:

The RUNUTIL step runs IDISUTL2 as an IDIUTIL LISTHF user exit to generate a CSV-format file of the fault entries from one or more history file data sets. (This step is described in Example 2.)
The MERGE step appends the CSV data collected in the RUNUTIL step to the cumulative file specified by the ALLDATA DD statement.