HFZUTIL ListHF user exit

The following describes the HFZUTIL ListHF user exit.

Purpose

This exit can be used to control the listing of a fault entry during history file management using the HFZUTIL 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 - HFZUTIL 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 HFZUTIL 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.

Z Abend Investigator 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 - HFZUTIL 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 - HFZUTIL 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

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

Figure 1. Sample REXX HFZUTIL 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

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

and the HFZUTIL batch utility control statement

Exits(LISTHF(REXX(ABC)))

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

Example 2

The following is an example of an HFZUTIL 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 Z Abend Investigator 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 HFZUTIL 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 HFZUTIL 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 HFZUTIL 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 HFZSUTL1 in the HFZ.SHFZSAM1 data set.

The following JCL could be used to run the sample:

//HFZUTIL  JOB parms
//RUNUTIL  EXEC PGM=HFZUTIL
//SYSPRINT DD SYSOUT=*
//MYREP    DD SYSOUT=*
//COMMA    DD SYSOUT=*
//HFZTRACE DD SYSOUT=*       (Optional)
//HFZEXEC  DD DISP=SHR,DSN=HFZ.SHFZSAM1
//SYSIN    DD  *
Exits(LISTHF(REXX(HFZSUTL1)))
FILES(my.histfile)
LISTHF
/*