Notification user exit

The following describes the Notification user exit.

Purpose

This exit can be used to provide installation-specific notification about the recording of a fault in a history file, or the occurrence of a duplicate of an earlier fault. For example, the exit might send an email to the person who is responsible for the failing application.

The reason for invoking the exit is identified in the NFYTYPE field of the NFY data area as one of the following:
C
Fault created.

The name of the history file in which the fault was recorded is provided in the ENV.HFZHIST data area field, and the fault ID assigned to the recorded fault is available in the ENV.FAULT_ID data area field.

Z Abend Investigator issues message HFZ0003I to indicate the assigned fault ID and history file.

A copy of the synopsis section of the real-time report is available in the NFY.SYNOPSIS data area field. Each line of the synopsis is delimited by a new-line character (X'15'). Refer to the NFY data area for extra details regarding this field.

R
Recovery fault recording

This value indicates a fault that was created as a result of the recovery fault recording feature of Z Abend Investigator. (For more information about this feature, see Recovery fault recording.)

The name of the history file in which the fault was recorded is provided in the ENV.HFZHIST data area field, and the fault ID assigned to the recorded fault is available in the ENV.FAULT_ID data area field.

Z Abend Investigator issues message HFZ0126I to indicate the assigned fault ID and history file.

N
Normal duplicate.

This value indicates that the NoDup(NORMAL) option criteria matched for the current fault, and that no history file fault entry is therefore written. (For details about NoDup(NORMAL), see NoDup.)

The original history file name and fault ID are provided in the ENV.HFZHIST and ENV.FAULT_ID data area fields.

The DUPCOUNT field is set to 1.

F
Fast duplicate (CICS®).

This value indicates that the NoDup(CICSFAST) option criteria matched for the current fault, and that no analysis was therefore performed. (For details about NoDup(CICSFAST), see NoDup.)

If available, the original history file name and fault ID are provided in the ENV.HFZHIST and ENV.FAULT_ID data area fields.

The DUPCOUNT field is set to the number of duplicate occurrences for the 30-second recording period.

When invoked

This exit is invoked after Z Abend Investigator has finished the recording of a fault in the history file.

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:

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:

Calling a non-REXX logging routine from REXX

For a Notification user exit that is written in REXX that, for example, calls an external logging routine that is not written in REXX, two extra stem variables are provided. The stem variables can be used to pass all of the available data area values to the external routine. These stem variables are:
  • ENV.RECORD
  • NFY.RECORD
Each of these contain the entire ENV or NFY data area respectively, in a single REXX variable. Neither exist as fields in the respective data areas for non-REXX exits, as they each represent the entire data area, which is already provided.

By using these variables in an argument list for an external non-REXX routine, the REXX exit need not be concerned with changes that might occur to these data areas in the future.

The external routine should use the language-dependent data area mappings provided for access to any data values (see Load module exits). All values in the ENV.RECORD and NFY.RECORD variables are considered read only and cannot be updated by the external routine. If updates are required, these must be made in the appropriate data field stem variables by the REXX exit itself.

Example 1

The following is an example of a Notification user exit that is written in REXX. It issues a TSO SEND message.
Figure 1. Sample REXX Notification user exit 1
/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if NFY.VERSION <> 2 then
  say 'Note: NFY data area version change - field usage review required!'
/* Issue SEND command via TSO batch job */
queue "//NOTIFY   JOB  MSGCLASS=Z"
queue "//TSOBATCH EXEC PGM=IKJEFT01"
queue "//SYSTSPRT DD   SYSOUT=*"
queue "//SYSTSIN  DD   *"
/* Split the TSO SEND command over three data records that must
   each be padded with blanks to 80 bytes */
rec = "SEND 'Fault ID" ENV.FAULT_ID "assigned in history file -"
queue left(rec,80)
rec = strip(ENV.HFZHIST)||"' -"
queue left(rec,80)
rec = "USER("||strip(ENV.USER_ID)||") LOGON"
queue left(rec,80)
queue '/*'
/* 'Submit' the stacked TSO batch job */
n = queued()
if rc = 0 then do
   address mvs "EXECIO" n "DISKW DD1 (FINIS"
   "IDIFREE DD(DD1)"
end
exit 0
If the above sample exit existed as member ABC in data set X.Y.Z, then providing the following options in either the HFZCNF00 configuration member or the HFZOPTS user options file would cause it to be invoked:
DataSets(HFZEXEC(X.Y.Z))
Exits(NOTIFY(REXX(ABC)))

Example 2

The following is an example of a Notification user exit that is written in REXX. It sends an e-mail message via SMTP.
Figure 2. Sample SMTP REXX Notification user exit 2
/* REXX *
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if NFY.VERSION <> 2 then
  say 'Note: NFY data area version change - field usage review required!'
/* Issue SMTP message via SMTP batch interface */
user = strip(ENV.USER_ID)
queue "helo pthmvs8.hcl.com"
queue "mail from:<"user"@pthmvs8.hcl.com>"
queue "rcpt to:<"user"@hcl.com>"
queue "data"
queue "Date: " date('N') time('C')
queue "From:<"user"@pthmvs8.hcl.com>"
queue "To:<"user"@hcl.com>"
queue "Subject: Batch job "strip(ENV.JOB_NAME)" abend "ENV.ABEND_CODE
queue " "
queue "Fault ID "ENV.FAULT_ID" assigned in history file"
queue strip(ENV.HFZHIST)" for job "ENV.JOB_NAME
queue "program "ENV.EXEC_PGM_NAME" module "ENV.ABEND_MODULE_NAME"."
queue ""
n = queued()
"HFZALLOC DD(DD1) SYSOUT(A) DEST(PTHMVS8.SMTP)"
address mvs "EXECIO" n "DISKW DD1 (FINIS"
"HFZFREE DD(DD1)"
exit

The MVS™ TCP/IP SMTP environment must be available to your system for this exit to work.

The previous sample exit has been tested using the batch interface of the IBM® SMTP server provided with the IBM Communications Server product.

Successful delivery of the sample message is dependent on configuration of the IBM CS TCP/IP service and SMTP server, and a suitable TCP/IP network infrastructure being available on the system running the exit.

Factors such as the presence of firewalls, security software, and message filtering software on intermediate network nodes might affect successful delivery of the message.

If the above sample exit existed as member NOTIFY1 in data set TEST.EXEC.PDS, then providing the following options in either the HFZCNF00 configuration member or the HFZOPTS user options file would cause it to be invoked:
DataSets(HFZEXEC(TEST.EXEC.PDS))
Exits(NOTIFY(REXX(NOTIFY1)))

Example 3

The following is an example of a Notification user exit that is written in REXX. It extracts and shows all lines of the captured real-time synopsis.
Figure 3. Sample SMTP REXX Notification user exit 3
/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if NFY.VERSION <> 2 then
  say 'Note: NFY data area version change - field usage review required!'
/* Show synopsis */
rest = NFY.SYNOPSIS
do while rest<>''
  parse var rest nextline '15'x rest
  say nextline
end
exit 0

This example can, for example, be combined with example 2 above, to include the synopsis in an e-mail message.

If the above sample exit existed as member FRED in data set TEST.EXEC.PDS, then providing the following options in either the HFZCNF00 configuration member or the HFZOPTS user options file would cause it to be invoked:
DataSets(HFZEXEC(TEST.EXEC.PDS))
Exits(NOTIFY(REXX(FRED)))

Example 4

The following is an example of a Notification user exit that is written in REXX and can be used to submit a batch reanalysis job to generate a saved report for a DeferredReport fault entry.
Figure 4. Sample REXX Notification user exit 4
/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if NFY.VERSION <> 2 then
  say 'Note: NFY data area version change - field usage review required!'
queue "//GENREP   JOB  MSGCLASS=X"
queue "//FA       EXEC PGM=HFZDA,"
queue "// PARM=('/FAULTID("ENV.FAULT_ID")',"
queue "//       'GenerateSavedReport',"
queue "//      )"
queue "//HFZHIST  DD   DISP=SHR,DSN="ENV.HFZHIST
queue "//SYSPRINT DD   SYSOUT=*"
/* 'Submit' the stacked batch reanalysis job */
n = queued()
"HFZALLOC DD(DD1) SYSOUT PGM(INTRDR)"
if rc = 0 then do
   address mvs "EXECIO" n "DISKW DD1 (FINIS"
   "HFZFREE DD(DD1)"
end
exit 0                                                                   
If the above sample exit existed as member ABC in data set X.Y.Z, then providing the following options in either the HFZCNF00 configuration member or the HFZOPTS user options file would cause it to be invoked:
DataSets(HFZEXEC(X.Y.Z))
Exits(NOTIFY(REXX(ABC)))