Message and Abend Code Explanation user exit

The following describes the Message and Abend Code Explanation user exit.

Purpose

This exit can provide explanations of messages and abend codes for the analysis report. A Message and Abend Code Explanation user exit receives control after Fault Analyzer determines the availability of either a message explanation or an abend code explanation and before presenting the explanation in the analysis report. If Fault Analyzer finds an explanation using the softcopy books or override data sets, then the XPL.EXPLANATION_AVAILABLE data area field is set to 'Y'.

See XPL - Message and Abend Code Explanation user exit parameter list for details about the data area.

The Message and Abend Code Explanation user exit can:

Retain the explanation if one was found to be available by doing nothing
Provide an explanation if none was found, or replace one that was found

If a message explanation is being formatted by Fault Analyzer, the following information is provided in the XPL data area:

The actual text of the message that was issued.
This text is available in the fields MESSAGE_TEXT1 through MESSAGE_TEXT10. MESSAGE_TEXT1 is initialized to contain the first or only line of the message, MESSAGE_TEXT2 through MESSAGE_TEXT10 are used if the message consists of multiple lines.

Note: If the actual text of the message issued is not available, only the message ID is placed in the MESSAGE_TEXT1 field.

If an abend code explanation is being formatted by Fault Analyzer, the following information is provided in the XPL data area:

The abend code.
This code is available in the ABEND_CODE field. The contents of this field depends on the abend type. See below for details.
The abend reason code.
This code is available in the ABEND_REASON_CODE field as an 8-character hexadecimal value.
The abend module name.
This name is available in the ABEND_MODULE_NAME field.
The abend type.
This type is available in the ABEND_TYPE field which contains one of the following values:

C

Indicating a CICS® transaction abend.
The field ABEND_CODE contains a 4-character CICS® abend code.

D

Indicating a CICS® dump code.
The field ABEND_CODE contains a 4-character CICS® dump code.

S

Indicating a system abend.
The field ABEND_CODE contains a 3-character hexadecimal left-justified system abend code.

U

Indicating a user abend.
The field ABEND_CODE contains a 4-character decimal user abend code.

Based on the above information, a user exit can provide a missing explanation or a replacement of the one found by Fault Analyzer. This provision is done by passing one record of the explanation at a time to Fault Analyzer via the XPL data area.

Unless the name of a variable containing the explanation record is passed on the IDIWRITE command in a REXX EXEC, the explanation data record must be provided in the DATA_BUFFER field.

Having updated the XPL data area with the data record information, two different methods are available for passing the data to Fault Analyzer depending on the exit type:

REXX

The Fault Analyzer environment IDIWRITE command is used. To use this command, code a REXX statement as follows:

ADDRESS FAULTA 'IDIWRITE [var-name]'

Successful completion of the IDIWRITE command is indicated by a zero return code.

For detailed information about the IDIWRITE command, see IDIWRITE command.

Load module

The address of a write routine is available in the ENV.WRITE_ROUTINE_EP data area field, as a hexadecimal 31-bit address.

This routine must be invoked with R1 pointing to a fullword containing the address of the ENV data area. For example, the following code fragments of user exits in different programming languages could be used to invoke the write routine:

Assembler:

ASMEXIT  CSECT
         …
         L     R2,0(,R1)
         USING ENV,R2
         L     R3,4(,R1)
         USING XPL,R3
         …
         L     R15,ENV_WRITE_ROUTINE_EP
         LA    R1,ENV_VERSION
         ST    R1,*+8
         BAL   R1,*+8
         DC    F'0'
         BALR  R14,R15
         …
         COPY  IDISXPLA
         …

#include "SAMPLES(IDISXPLC)"
typedef void WRTN(ENV *pENV);
#pragma linkage(WRTN,OS)
int cexit(ENV *pENV, XPL *pXPL) {
  …
  WRTN *write_rtn;
  write_rtn = (WRTN *)pENV->WRITE_ROUTINE_EP;
  write_rtn(pENV);
  …
}

COBOL:

       …
       PROGRAM-ID. COBEXIT
       …
       LINKAGE SECTION.
           COPY IDISXPLB IN LIB.
       PROCEDURE DIVISION USING ENV, XPL.
       MAIN SECTION.
             …
             CALL WRITE-ROUTINE-EP USING ENV.
             …
       END PROGRAM COBEXIT.

PL/I:

 PLIEXIT: PROC (ENVPTR,XPLPTR)  OPTIONS(BYVALUE,FETCHABLE) ;
 Dcl (Envptr,Xplptr)     Pointer ;
 %include syslib(IDISXPLP) ;
 Dcl IDIWRITE         Entry Variable Options(Asm Byaddr) ;
   …
   Entryaddr(IDIWRITE) = Envptr->Write_Routine_EP ;
   Call IDIWRITE (Envptr->Env) ;
   …
 End PLIEXIT ;

Return codes from the write routine are the same as the return codes from the IDIWRITE REXX command, except that RC=8 (syntax error) cannot be returned. See IDIWRITE command.

The total number of characters that form the message or abend code explanation must not exceed max-chars in the following formula:

max-chars = 32752 - (num-recs * 2)

where num-recs is the total number of records.

An attempt to pass back a record that would cause the maximum number of characters to exceed max-chars results in RC=4 being returned by IDIWRITE (or the write routine used by load module exits) and the record being ignored.

No formatting of text is performed by Fault Analyzer. All records are presented in the analysis report exactly as they were provided by the Message and Abend Code Explanation user exit.

Records whose length exceed the formatting with at the time of presentation are wrapped at the current indentation, as determined by the leading number of blank characters in each record.

If more than one Message and Abend Code Explanation user exit provides a specific message or abend code explanation, then only the last explanation is used.

When invoked

This exit is invoked during formatting of the analysis report, regardless of the execution mode of Fault Analyzer.

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 Message and Abend Code Explanation 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).
XPL.
Contains defined symbols for all fields in the XPL data area (see XPL - Message and Abend Code Explanation 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 XPL address in word 2.
Address of an XPL data area (see XPL - Message and Abend Code Explanation 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 a Message and Abend Code Explanation user exit that is written in REXX.

Figure 1. Sample REXX Message and Abend Code Explanation user exit

/* REXX */
if ENV.VERSION <> 5 then
  say 'Note: ENV data area version change - field usage review required!'
if XPL.VERSION <> 1 then
  say 'Note: XPL data area version change - field usage review required!'
parse var XPL.MESSAGE_TEXT1 msgid msgtext
if msgid = 'MYMSG01' then do
  rec = 'This message indicates that:'
  'IDIWRITE rec'
  rec = '  - A serious problem has occurred'
  'IDIWRITE rec'
  rec = '  - Any data produced should be ignored'
  'IDIWRITE rec'
end

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(MSGXPL(REXX(ABC)))