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 Z Abend Investigator determines the availability of either a message explanation or an abend code explanation and before presenting the explanation in the analysis report. If Z Abend Investigator 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 Z Abend Investigator, 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 Z Abend Investigator, 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 Z Abend Investigator. This provision is done by passing one record of the explanation at a time to Z Abend Investigator via the XPL data area.

Unless the name of a variable containing the explanation record is passed on the HFZWRITE 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 Z Abend Investigator depending on the exit type:
REXX
The Z Abend Investigator environment HFZWRITE command is used. To use this command, code a REXX statement as follows:
ADDRESS FAULTA 'HFZWRITE [var-name]'

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

For detailed information about the HFZWRITE command, see HFZWRITE 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  HFZSXPLA
         …
C:
#include "SAMPLES(HFZSXPLC)"
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 HFZSXPLB 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(HFZSXPLP) ;
 Dcl HFZWRITE         Entry Variable Options(Asm Byaddr) ;
   …
   Entryaddr(HFZWRITE) = Envptr->Write_Routine_EP ;
   Call HFZWRITE (Envptr->Env) ;
   …
 End PLIEXIT ;

Return codes from the write routine are the same as the return codes from the HFZWRITE REXX command, except that RC=8 (syntax error) cannot be returned. See HFZWRITE 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 HFZWRITE (or the write routine used by load module exits) and the record being ignored.

No formatting of text is performed by Z Abend Investigator. 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 Z Abend Investigator.

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 Message and Abend Code Explanation 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 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:'
  'HFZWRITE rec'
  rec = '  - A serious problem has occurred'
  'HFZWRITE rec'
  rec = '  - Any data produced should be ignored'
  'HFZWRITE 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 HFZCNF00 configuration member or the HFZOPTS user options file would cause it to be invoked:
DataSets(HFZEXEC(X.Y.Z))
Exits(MSGXPL(REXX(ABC)))