End Processing user exit

The following describes the End Processing user exit.

Purpose

This exit can be used to control post-analysis actions taken by Fault Analyzer:

History file selection.
Following analysis, detailed information about the fault is available which might not have been available at the time of calling any Analysis Control user exits. Based on this, an End Processing user exit can choose to change the history file to be used by modifying the ENV.IDIHIST data area field.

Because information about duplicate faults depend on the history file that is selected, the End Processing user exit is invoked repeatedly until the history file name is no longer changed. On each reinvocation, duplicate fault information is updated for the history file specified on the previous invocation.

If an invalid history file is provided in the ENV.IDIHIST, then no reinvocation of the End Processing user exit occurs, and the history file that was current when the End Processing user exit was last invoked is used.
Duplicate fault determination.
By default, Fault Analyzer deems a fault a duplicate of another fault in the same history file if the characteristics of the faults match and they occurred within the number of hours in effect for the NoDup(NORMAL(hours)) option of each other (see NoDup for details). The End Processing user exit permits an installation to apply a different time interval for the determination of duplicate faults to the one in effect due to the NoDup option.
If a duplicate fault was found based on the fault characteristics alone, then the following information is provided:
- The field EPC.MINUTES_SINCE_LAST_DUP is initialized to the number of minutes elapsed since recording of the last duplicate fault. The value is in the range 0 - 99999 (values greater than the limit of this field are all presented as the maximum value, 99999). If no value is provided, no duplicate fault was found.
- The field EPC.DUPLICATE_COUNT shows the total number of times that a fault was deemed a duplicate, not including the current fault.
  This total is determined by accumulating all instances of duplicate recorded faults, in the same history file, going back as far as the NoDup(Normal(…)) time period in effect. Any recorded faults encountered whose duplicate criteria match the current fault accounts for one instance, and if duplicates have been recorded against the fault, the duplicate count of that fault is also added.
- The field ENV.FAULT_ID identifies the recorded duplicate fault by its fault ID.
- The fields ENV.DUP_DATE and ENV.DUP_TIME identify the date and time of most recent duplicate fault.
- The fields ENV.ORIGINAL_DATE and ENV.ORIGINAL_TIME identify the date and time when the original fault was recorded. These fields provide the user with the ability to determine duplicates on the basis of time since the original fault, as opposed to the last duplicate fault, if so desired.
If both the fault characteristics matched and the elapsed time did not exceed the number of hours in effect for the NoDup(NORMAL(hours)) option, the field EPC.IS_DUPLICATE is initialized to 'Y'. However, the final determination of whether the fault is a duplicate or not resides with the End Processing user exit. If the returned value of this field is 'Y', the last recorded duplicate fault's (if any) duplicate count is incremented by one and message IDI0044I is issued.

Note: CICS® or IMS™ fast duplicate fault suppression cannot be controlled using this exit. Only the NoDup(CICSFAST(…)) or the NoDup(ImageFast(…)) option (see NoDup) can be used to affect the determination of these types of duplicates. However, if a fault occurring under CICS® or IMS™ is not deemed a fast duplicate, then it is still considered for the normal type of duplicate suppression based on existing entries in the target history file and the NoDup(NORMAL(hours)) option in effect.
History file updates.
By default, Fault Analyzer suppresses the entire fault entry, including the minidump, if the current fault is found to be a duplicate of a previously recorded fault in the same history file. However, the minidump might also be suppressed if its size exceeds the limit imposed by the MaxMinidumpPages option in effect.
The possible reasons for suppression in the following fields:
- The ENV.MINIDUMP_PAGES field, containing the size of the minidump as a number of 4K pages.
- The EPC.IS_DUPLICATE field (see Duplicate fault determination above).
The suppression intent by Fault Analyzer is indicated by the initialization of the following fields, both of which can be overridden by the End Processing user exit:
- The EPC.SUPPRESS_MINIDUMP field. If set to 'Y', no minidump is written to the history file. If set to 'N', the minidump is written regardless of its size.
- The EPC.SUPPRESS_FAULT_ENTRY field. If set to 'Y', no recording of the current fault is made in the history file (including the minidump). If set to 'N', fault recording is performed and the minidump can be written subject to the EPC.SUPPRESS_MINIDUMP field.
Dump suppression.
The End Processing user exit can set the EPC.SUPPRESS_DUMP field to 'Y' if dumps should be suppressed, or to 'N' if they should be permitted to be taken.

Refer to Dump suppression for general information about dump suppression.

When invoked

This exit is invoked on completion of real-time analysis, prior to updating 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 End Processing 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).
EPC.
Contains defined symbols for all fields in the EPC data area (see EPC - End Processing 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 EPC address in word 2.
Address of an EPC data area (see EPC - End Processing user exit parameter list).

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

Example

The following is an example of an End Processing user exit that is written in REXX.

Figure 1. Sample REXX End Processing user exit

/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if EPC.VERSION <> 1 then
  say 'Note: EPC data area version change - field usage review required!'
if EPC.MINUTES_SINCE_LAST_DUP ¬= ' ' & EPC.MINUTES_SINCE_LAST_DUP < 48*60 then do
  /* Use 48 hours as the duplicate fault threshold */
  EPC.IS_DUPLICATE = 'Y'
  EPC.SUPPRESS_FAULT_ENTRY = 'Y'
end
EPC.SUPPRESS_DUMP = 'N'  /* Always permit dumps to be taken */
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(END(REXX(ABC)))