Writing a program error program

Considerations common to all user-replaceable programs

Note that the comments contained in General notes about user-replaceable programs apply to this section.

The CICS-supplied default program error program (DFHPEP) contains code to:

The source of DFHPEP is provided in assembler-language and C versions; you can modify one of these to include your own logic, or you can write your own program error program in any of the languages supported by CICS. There is a discussion of the reasons for using your own program error program in the CICS Recovery and Restart Guide. Note, however, that when writing a program error program you are subject to specific restrictions:

The default DFHPEP module is a dummy module. If you want to customize it, you have to code the source yourself. To help you, a listing of DFHPEP is provided in Figure 14. When you have written your program error program, translate and assemble it, and use it to replace the supplied dummy program. For information about the job control statements necessary to assemble and link-edit user-replaceable programs, refer to Assembling and link-editing user-replaceable programs.

Information available to DFHPEP in the communication area includes:

Note that information about the PSW, registers, execution key, and type of storage "hit" is meaningful only if the abend occurred in the local system; these fields are set to zeros if the abend occurred in a DPL server program running in a remote system.

In order to disable the transaction, you should assign the value ‘PEP_COM_RETURN_DISABLE’ to the field PEP_COM_RETURN_CODE. Otherwise, you should allow the field to default to zero, or set it to the value ‘PEP_COM_RETURN_OK’. CICS does not allow CICS-supplied transactions to be disabled; you should not, therefore, attempt to disable transactions whose IDs begin with "C".

The assembler-language source code of the default program error program is shown in Figure 14. The communication area is shown in Figure 15.

Figure 14. Source code of the default program error program (DFHPEP)
DFHEISTG DSECT ,
*
*        Insert your own storage definitions here
*
         DFHPCOM TYPE=DSECT
***********************************************************************
* * * * *              P R O G R A M   E R R O R              * * * * *
* * * * *                    P R O G R A M                    * * * * *
***********************************************************************
DFHPEP   CSECT                     PROGRAM ERROR PROGRAM CSECT
DFHPEP   RMODE ANY
         DFHREGS ,                 EQUATE REGISTERS
         XR    R1,R1
         ICM   R1,B'0011',EIBCALEN Get Commarea length
         BZ    RETURNX             ...no Commarea; exit
         EXEC CICS ADDRESS COMMAREA(R2) ,
         USING DFHPEP_COMMAREA,R2
*
*        Insert your own code here
*
         LA    R1,PEP_COM_RETURN_OK
         B     RETURN
         DFHEJECT
*
RETURNER DS    0H                  Return for error cases
         LA    R1,PEP_COM_RETURN_DISABLE
RETURN   DS    0H
         ST    R1,PEP_COM_RETURN_CODE
RETURNX  DS    0H
         EXEC CICS RETURN ,
         END   DFHPEP
 

Figure 15. Source of DFHPEP communication area (assembler-language)
DFHPEP_COMMAREA DSECT
*
*                      Standard header section
*
PEP_COM_STANDARD              DS     0F
PEP_COM_FUNCTION              DS     CL1       Always '1'
PEP_COM_COMPONENT             DS     CL2       Always 'PC'
PEP_COM_RESERVED              DS     C         Reserved
*
*                      Abend codes and EIB
*
PEP_COM_CURRENT_ABEND_CODE    DS     CL4       Current abend code
PEP_COM_ORIGINAL_ABEND_CODE   DS     CL4       Original abend code
PEP_COM_USERS_EIB             DS     CL(EIBRLDBK-EIBTIME+L'EIBRLDBK)
*                                       EIB at last EXEC CICS command
*
*  Debugging information (program, PSW, registers and execution key at
*  time of abend, hit storage indicator).  If the abend occurred in a
*  DPL server program running remotely, only program is meaningful.
*
PEP_COM_DEBUG                 DS     0F
PEP_COM_ABPROGRAM             DS     CL8       Program causing abend
PEP_COM_PSW                   DS     CL8       PSW at abend
*                                              (codes ASRA, ASRB, AICA, ASRD)

PEP_COM_REGISTERS             DS     CL64      GP registers at abend
*                                              (registers 0-15)
PEP_COM_KEY                   DS     X         Execution key at abend
*                                              (ASRA and ASRB only)
PEP_COM_USER_KEY              EQU    9         User key
PEP_COM_CICS_KEY              EQU    8         CICS key
*
PEP_COM_STORAGE_HIT           DS     X         Storage type hit by 0C4
*                                              (ASRA only)
PEP_COM_NO_HIT                EQU    0         No hit, or not 0C4
PEP_COM_CDSA_HIT              EQU    1         CDSA hit
PEP_COM_ECDSA_HIT             EQU    2         ECDSA hit
PEP_COM_ERDSA_HIT             EQU    3         ERDSA hit
PEP_COM_RDSA_HIT              EQU    4         RDSA hit
PEP_COM_EUDSA_HIT             EQU    5         EUDSA hit
PEP_COM_UDSA_HIT              EQU    6         EUDSA hit
*
PEP_COM_SPACE                 DS     X         Subspace/basespace
PEP_COM_NOSPACE               EQU    0
PEP_COM_SUBSPACE              EQU    10        Abending task was in
*                                              subspace
PEP_COM_BASESPACE             EQU    11        Abending task was in
*                                              basespace
PEP_COM_PADDING               DS     CL2       Reserved
*
*                      Return code
*
PEP_COM_RETURN_CODE           DS     F
PEP_COM_RETURN_OK             EQU    0
PEP_COM_RETURN_DISABLE        EQU    4         Disable transaction
*
*       Additional Program status word information
*
PEP_COM_INT                   DS     CL8       PSW interrupt codes
*
*                             length of DFHPEP_COMMAREA
PEP_COM_LEN EQU *-PEP_COM_STANDARD

Related tasks
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Related reference
The sample program error programs
User-replaceable programs and the storage protection facility
[[ Contents Previous Page | Next Page Index ]]