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
- 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
- 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
/* 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 */
//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.
- Fault ID
- Date
- Time
- Lock
- Username
- User Title
- CPU Sec
//MYREP DD SYSOUT=*
//COMMA DD SYSOUT=*
The persistent user field, ENV.USER_1, is used to record the fact that the report header has been written.
/* 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.
//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
/*