Analysis Control user exit

The following describes the Analysis Control user exit.

Purpose

This exit can be used to examine and override current settings of the following options:

DataSets
Data sets for the following DDnames are provided:
  • HFZADATA
  • HFZHIST
  • HFZLANGX
  • HFZLC
  • HFZLCOB
  • HFZLCOBO
  • HFZLPLI
  • HFZLPLIE
  • HFZSYSDB
For the HFZADATA, HFZLANGX, HFZLC, HFZLCOB, HFZLCOBO, HFZLPLI, HFZLPLIE, and HFZSYSDB DDnames, current data sets are provided as:
Pre-allocated data sets
These are data sets that were allocated prior to invoking Z Abend Investigator, for example, via JCL DD statements. Data sets for each DDname is provided in the CTL.ddname_PRE field.

The pre-allocated data set name fields are read-only and any changes are ignored by Z Abend Investigator.

Job-allocated data sets
These are DataSets option specifications from the user options file (HFZOPTS). Data sets for each DDname is provided in the CTL.ddname_JOB field.

Changes to the job-allocated data set name fields are honored by Z Abend Investigator when it allocates this list of data sets.

Configuration data sets
These are DataSets option specifications from the HFZCNF00 configuration member. Data sets for each DDname is provided in the CTL.ddname_CFG field.

Changes to the configuration data set name fields are honored by Z Abend Investigator.

The final concatenation order of data sets is:

  1. Pre-allocated data sets
  2. Job-allocated data sets
  3. Configuration data sets

For the HFZHIST DDname, the current history file is provided in the ENV.HFZHIST data area field. The user exit can choose to change this data set name, in which case the supplied data set name is used as the history file for the current fault.

The same rules for the use of substitution symbols in data set names which apply to the DataSets option (see DataSets option data set name substitution symbols), also apply to data set names returned by an Analysis Control user exit.

DeferredReport
The status of the DeferredReport option in effect is identified as either 'Y' (DeferredReport is in effect) or 'N' (DeferredReport is not in effect) in the CTL.DEFERREDREPORT_OPT data area field. Valid changes to this field override the current option setting.

Only applicable to real-time processing.

Detail
The abbreviated form of the Detail option in effect is provided in the CTL.DETAIL_OPT data area field. Valid changes to this field override the current option setting.

Not applicable to interactive reanalysis.

Exclude
The last matching Exclude criterion is provided in the CTL.EXCLUDE_CRITERION data area field. If the fault is excluded from analysis based on a matching Exclude criterion, then the CTL.EXCLUDE data area field is initialized to 'Y'. This field can be modified by the exit.

Only applicable to real-time processing.

Include
The last matching Include criterion is provided in the CTL.INCLUDE_CRITERION data area field. A blank Include criterion signifies the implicit product default, which is to include everything.

Only applicable to real-time processing.

Locale
The current locale name is provided in the CTL.LOCALE data area field. Valid changes to this field override the current option setting.

The LOCALE option suboption, FADATE, is provided in the CTL.FADATE data area field. Valid changes to this field override the current option setting.

RetainDump
The value of the RetainDump option in effect is provided in the CTL.RETAINDUMP_OPT data area field (the value provided in this field is the actual suboption of the RetainDump option, that is, "AUTO" or "ALL"). Valid changes to this field override the current option setting.

Note that an End Processing user exit (see End Processing user exit) might later override this option.

Only applicable to real-time processing.

Source
The status of the Source option in effect is identified as either 'Y' (Source is in effect) or 'N' (Source is not in effect) in the CTL.SOURCE_OPT data area field. Valid changes to this field override the current option setting.

Only applicable to real-time processing.

In addition, the Analysis Control user exit can perform allocations of other data sets that might not be specified via options or provided in the passed data areas. In real time, one such allocation could be for HFZREPRT, which would allow an installation to control report destination attributes, such as the SYSOUT class. For more information on this type of HFZREPRT allocation, see Combining Z Abend Investigator real-time reports, Controlling the SYSOUT class of real-time reports, and Suppressing real-time reports.

You can use the CTL.HFZTRACE data area field to dynamically start or stop HFZTRACE processing, or to direct the trace output to a data set.

When invoked

This exit is invoked after options processing has completed, and before the commencement of fault analysis.

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 Analysis Control 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:

Example

The following is an example of an Analysis Control user exit that is written in REXX.
Figure 1. Sample REXX Analysis Control user exit
/* REXX */
/* Check data areas used */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if CTL.VERSION <> 2 then
  say 'Note: CTL data area version change - field usage review required!'
if ENV.REALTIME = 'Y' then do  /* Exclude all MVSA jobs from analysis */
  if ENV.SYSTEM_NAME = 'MVSA' then
    CTL.Exclude = 'Y'
  /* Select a separate history file for DB2, IMS, and other jobs
     based on jobname */
  if SUBSTR(ENV.JOB_NAME,1,3) = 'DB2' then
    ENV.HFZHIST = 'MY.DB2.HIST'
  else if SUBSTR(ENV.JOB_NAME,1,3) = 'IMS' then
    ENV.HFZHIST = 'MY.IMS.HIST'
  else
    ENV.HFZHIST = 'MY.OTHER.HIST'
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(CONTROL(REXX(ABC)))