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, or log the fault via the ADFzCC Event Processing user exit.

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.IDIHIST data area field, and the fault ID assigned to the recorded fault is available in the ENV.FAULT_ID data area field.

Fault Analyzer issues message IDI0003I 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 Fault Analyzer. (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.IDIHIST data area field, and the fault ID assigned to the recorded fault is available in the ENV.FAULT_ID data area field.

Fault Analyzer issues message IDI0126I 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.IDIHIST 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.IDIHIST and ENV.FAULT_ID data area fields.

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

If you use the IDIWRITE command in a Notification user exit, Fault Analyzer invokes the ADFzCC Event Processing feature after the exit has completed, and uses the data that is written with the IDIWRITE command to pass to the ADFzCC Event Processing user exit. For more information about the ADFzCC Event Processing feature, see IBM Application Delivery Foundation for z/OS Common Components: Customization Guide and User Guide.

The data that is written using the IDIWRITE command by multiple Notification user exits is sent to the ADFzCC Event Processing user exit in a single call. However, it is recommended to not use IDIWRITE in your own Notification user exits. Instead, specify the sample Notification user exit IDISXEPN in the EXITS option as follows:

EXITS(NOTIFY(<existing exit names,>REXX(IDISXEPN)))

and ensure that it can be located via the IDIEXEC DDname.

The IDISXEPN sample exit sends all available ENV and NFY data to the ADFzCC Event Processing user exit by using the IDIWRITE command.

When you issue the IDIWRITE command from a Notification user exit, the data is passed to the ADFzCC Event Processing user exit. Before you issue the IDIWRITE command, the data to be written is placed in the NFY.DATA_BUFFER field, and the data length is specified in the NFY.DATA_LENGTH field.

After the Notification user exit has completed, the buffer contents are sent to the ADFzCC Event Processing user exit. For the format of the buffer, see the section about load module IPVEPSND in IBM Application Delivery Foundation for z/OS Common Components: Customization Guide and User Guide. Each segment in the buffer contains the contents of each individual call to the IDIWRITE command. When you use the sample exit IDISXEPN that is provided, each segment contains data in the following format:

data_area.field_name=value

For example:

ENV.JOB_NAME=BATCH1

By setting the NFY.EPX_DEBUG_OPT to * or any other nonblank character, the Notification user exit asks for any diagnostics from the ADFzCC Event Processing user exit to be written to IDITRACE.

Note: If the NFY.EPX_DEBUG_OPT is set to a non-blank character, the ADFzCC Event Processing user exit will run synchronously because the Notification user exit must wait until the ADFzCC Event Processing user exit has completed to receive debug information, which might impact the performance.

If you leave NFY.EPX_DEBUG_OPT blank (the default setting), Fault Analyzer continues without waiting for the Event Processing user exit to complete, but diagnostics are not written to IDITRACE.

If no Event Processing user exit is specified by using the ADFzCC EVENTPROCESSINGEXIT option, the data is ignored. For information about specifying an Event Processing user exit by using the EVENTPROCESSINGEXIT option, see IBM Application Delivery Foundation for z/OS Common Components: Customization Guide and User Guide.

If you use the IDIWRITE command in a Notification user exit, Fault Analyzer invokes the ADFzCC Event Processing feature after the exit has completed, and uses the data that is written with the IDIWRITE command to pass to the ADFzCC Event Processing user exit. For more information about the ADFzCC Event Processing feature, see IBM Application Delivery Foundation for z/OS Common Components: Customization Guide and User Guide.

The data that is written using the IDIWRITE command by multiple Notification user exits is sent to the ADFzCC Event Processing user exit in a single call. However, it is recommended to not use IDIWRITE in your own Notification user exits. Instead, specify the sample Notification user exit IDISXEPN in the EXITS option as follows:

EXITS(NOTIFY(<existing exit names,>REXX(IDISXEPN)))

and ensure that it can be located via the IDIEXEC DDname.

The IDISXEPN sample exit sends all available ENV and NFY data to the ADFzCC Event Processing user exit by using the IDIWRITE command.

When you issue the IDIWRITE command from a Notification user exit, the data is passed to the ADFzCC Event Processing user exit. Before you issue the IDIWRITE command, the data to be written is placed in the NFY.DATA_BUFFER field, and the data length is specified in the NFY.DATA_LENGTH field.

After the Notification user exit has completed, the buffer contents are sent to the ADFzCC Event Processing user exit. For the format of the buffer, see the section about load module IPVEPSND in IBM Application Delivery Foundation for z/OS Common Components: Customization Guide and User Guide. Each segment in the buffer contains the contents of each individual call to the IDIWRITE command. When you use the sample exit IDISXEPN that is provided, each segment contains data in the following format:

data_area.field_name=value

For example:

ENV.JOB_NAME=BATCH1

By setting the NFY.EPX_DEBUG_OPT to * or any other nonblank character, the Notification user exit asks for any diagnostics from the ADFzCC Event Processing user exit to be written to IDITRACE.

Note: If the NFY.EPX_DEBUG_OPT is set to a non-blank character, the ADFzCC Event Processing user exit will run synchronously because the Notification user exit must wait until the ADFzCC Event Processing user exit has completed to receive debug information, which might impact the performance.

If you leave NFY.EPX_DEBUG_OPT blank (the default setting), Fault Analyzer continues without waiting for the Event Processing user exit to complete, but diagnostics are not written to IDITRACE.

If no Event Processing user exit is specified by using the ADFzCC EVENTPROCESSINGEXIT option, the data is ignored. For information about specifying an Event Processing user exit by using the EVENTPROCESSINGEXIT option, see IBM Application Delivery Foundation for z/OS Common Components: Customization Guide and User Guide.

When invoked

This exit is invoked after Fault Analyzer 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.

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).
NFY.
Contains defined symbols for all fields in the NFY data area (see NFY - Notification 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 NFY address in word 2.
Address of an NFY data area (see NFY - Notification user exit parameter list).

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

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.IDIHIST)||"' -"
queue left(rec,80)
rec = "USER("||strip(ENV.USER_ID)||") LOGON"
queue left(rec,80)
queue '/*'
/* 'Submit' the stacked TSO batch job */
n = queued()
"IDIALLOC DD(DD1) SYSOUT PGM(INTRDR)"
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 IDICNF00 configuration member or the IDIOPTS user options file would cause it to be invoked:

DataSets(IDIEXEC(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.au.ibm.com"
queue "mail from:<"user"@pthmvs8.au.ibm.com>"
queue "rcpt to:<"user"@au1.ibm.com>"
queue "data"
queue "Date: " date('N') time('C')
queue "From:<"user"@pthmvs8.au.ibm.com>"
queue "To:<"user"@au1.ibm.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.IDIHIST)" for job "ENV.JOB_NAME
queue "program "ENV.EXEC_PGM_NAME" module "ENV.ABEND_MODULE_NAME"."
queue ""
n = queued()
"IDIALLOC DD(DD1) SYSOUT(A) DEST(PTHMVS8.SMTP)"
address mvs "EXECIO" n "DISKW DD1 (FINIS"
"IDIFREE 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 IDICNF00 configuration member or the IDIOPTS user options file would cause it to be invoked:

DataSets(IDIEXEC(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 IDICNF00 configuration member or the IDIOPTS user options file would cause it to be invoked:

DataSets(IDIEXEC(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=IDIDA,"
queue "// PARM=('/FAULTID("ENV.FAULT_ID")',"
queue "//       'GenerateSavedReport',"
queue "//      )"
queue "//IDIHIST  DD   DISP=SHR,DSN="ENV.IDIHIST
queue "//SYSPRINT DD   SYSOUT=*"
/* 'Submit' the stacked batch reanalysis job */
n = queued()
"IDIALLOC DD(DD1) SYSOUT PGM(INTRDR)"
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 IDICNF00 configuration member or the IDIOPTS user options file would cause it to be invoked:

DataSets(IDIEXEC(X.Y.Z))
Exits(NOTIFY(REXX(ABC)))