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:

IDIADATA
IDIHIST
IDILANGX
IDILC
IDILCOB
IDILCOBO
IDILPLI
IDILPLIE
IDISYSDB

For the IDIADATA, IDILANGX, IDILC, IDILCOB, IDILCOBO, IDILPLI, IDILPLIE, and IDISYSDB DDnames, current data sets are provided as:

Pre-allocated data sets: These are data sets that were allocated prior to invoking Fault Analyzer, 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 Fault Analyzer.
Job-allocated data sets: These are DataSets option specifications from the user options file (IDIOPTS). 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 Fault Analyzer when it allocates this list of data sets.
Configuration data sets: These are DataSets option specifications from the IDICNF00 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 Fault Analyzer.

The final concatenation order of data sets is:

Pre-allocated data sets
Job-allocated data sets
Configuration data sets

For the IDIHIST DDname, the current history file is provided in the ENV.IDIHIST 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 IDIREPRT, which would allow an installation to control report destination attributes, such as the SYSOUT class. For more information on this type of IDIREPRT allocation, see Combining Fault Analyzer real-time reports, Controlling the SYSOUT class of real-time reports, and Suppressing real-time reports.

You can use the CTL.IDITRACE data area field to dynamically start or stop IDITRACE 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.

Fault Analyzer 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:

ENV.
Contains defined symbols for all fields in the ENV data area (see ENV - Common exit environment information).
CTL.
Contains defined symbols for all fields in the CTL data area (see CTL - Analysis Control 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 CTL address in word 2.
Address of a CTL data area (see CTL - Analysis Control 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 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.IDIHIST = 'MY.DB2.HIST'
  else if SUBSTR(ENV.JOB_NAME,1,3) = 'IMS' then
    ENV.IDIHIST = 'MY.IMS.HIST'
  else
    ENV.IDIHIST = '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 IDICNF00 configuration member or the IDIOPTS user options file would cause it to be invoked:

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