Writing a program error program
You can write a program error program that is based on the supplied default program, DFHPEP.
The CICS®-supplied default program error program (DFHPEP) contains code to obtain program addressability, access the communication area, and return control to CICS through an EXEC CICS RETURN command.
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 language that is supported by CICS. The program error program
is subject to specific restrictions:
- The name of your program must be DFHPEP.
- The program must not issue any EXEC CICS commands that use MRO or ISC facilities, such as distributed transaction processing or function shipping.
- The program must not issue any commands that access recoverable resources.
- The program cannot influence whether a transaction dump is taken.
The default DFHPEP module is a dummy module. To customize it, you must code the source yourself. A listing of DFHPEP is provided in Figure 1. After you write 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:
- The current abend code, at PEP_COM_CURRENT_ABEND_CODE.
- The original abend code, at PEP_COM_ORIGINAL_ABEND_CODE. The original and current abend codes are different if the transaction has experience more than one abend; for example, if the failing program abends while handling a previous abend. In this case, the original abend is the first abend that the transaction experienced.
- The EIB at the time of the last EXEC CICS command, at PEP_COM_USERS_EIB.
- The name of the program that suffered the (current) abend, at
PEP_COM_ABPROGRAM. PEP_COM_ABPROGRAM identifies the program as follows:
- If the abend occurred in a distributed program link (DPL) server program running in a remote system, it identifies the server program.
- If the abend is a local ASRA, ASRB, or ASRD abend, it identifies the program in which the program check or operating system abend occurred.
- In all other cases, it identifies the current program.
- The program status word (PSW) at the time of the (current) abend, at PEP_COM_PSW, or PEP_COM_PSW16 for a 16 byte PSW. The full contents of the PSW are significant only for the ASRA, ASRB, and ASRD abend codes. The last four bytes of PEP_COM_PSW and last eight bytes of PEP_COM_PSW16 (the PSW address) apply also to the AICA code.
- The GP registers (0-15) at the time of the (current) abend, at PEP_COM_REGISTERS.
- The execution key of the program at the time it suffered the (current) abend, at PEP_COM_KEY. The value of PEP_COM_KEY is significant only for the ASRA and ASRB abend codes.
- Whether the (current) abend occurred as the result of a storage protection exception, at PEP_COM_STORAGE_HIT. The value of PEP_COM_STORAGE_HIT is significant only for the ASRA abend code, and indicates which of the protected dynamic storage areas (the CDSA, RDSA, ECDSA, ERDSA, ETDSA, GCDSA or GUDSA), if any, the failing program attempted to overwrite.
- • Additional register information might be available. The additional information might include the 64-bit GP registers, the access registers, the floating point registers, and the vector registers. Indicators are set in the communication area to indicate which register values are available.
- If it is available, the Breaking Event Address is stored in the communication area. If it is not available, the Breaking Event Address is zero.
- Program status word interrupt information, at PEP_COM_INT.
Information about the PSW, registers, execution key, and type of protected storage the application attempted to overwrite 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.
To disable the transaction, assign the value PEP_COM_RETURN_DISABLE to the PEP_COM_RETURN_CODE field. Otherwise, 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; therefore do not attempt to disable transactions with IDs that start with the letter C.
Figure 1 shows the assembler language source code of the default program error program. Figure 2 through Figure 4 show the source code of the communication area.
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 2 through Figure 4 show the assembler language source code of the communication area of the default program error program.
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 UDSA hitPEP_COM_ETDSA_HIT EQU 7 ETDSA hit
PEP_COM_GCDSA_HIT EQU 8 GCDSA hit
PEP_COM_GUDSA_HIT EQU 9 GUDSA 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
** Breaking Event Address
*
PEP_COM_BEAR DS AD Breaking Event Addr
**
* Additional register information
*
DS 0D Force alignment
PEP_COM_FLAG1 DS X Flag byte
PEP_COM_GP64_REGS_AVAIL EQU X'80' 64 bit register values
* available in
* PEP_COM_G64_REGISTERS
PEP_COM_ACCESS_REGS_AVAIL EQU X'40' 64 bit register values
* available in
* PEP_COM_ACCESS_REGISTERS
PEP_COM_ORIGINAL_FPR_AVAIL EQU X'20' FPR 0, 2, 4 & 6 values
* available in
* PEP_COM_FP_REGISTERS
PEP_COM_ADDITIONAL_FPR_AVAIL EQU X'10' All FPR available in
* PEP_COM_FP_REGISTERS &
* FPCR in
* PEP_COM_FPC_REGISTER
DS CL7 Reserved
PEP_COM_GP64_REGISTERS DS CL128 64 bit GP registers
PEP_COM_FP_REGISTERS DS 0CL132 FP registers
PEP_COM_FP_REGISTER0 DS FD FP register 0
PEP_COM_FP_REGISTER1 DS FD FP register 1
PEP_COM_FP_REGISTER2 DS FD FP register 2
PEP_COM_FP_REGISTER3 DS FD FP register 3
PEP_COM_FP_REGISTER4 DS FD FP register 4
PEP_COM_FP_REGISTER5 DS FD FP register 5
PEP_COM_FP_REGISTER6 DS FD FP register 6
PEP_COM_FP_REGISTER7 DS FD FP register 7
PEP_COM_FP_REGISTER8 DS FD FP register 8
PEP_COM_FP_REGISTER9 DS FD FP register 9
PEP_COM_FP_REGISTER10 DS FD FP register 10
PEP_COM_FP_REGISTER11 DS FD FP register 11
PEP_COM_FP_REGISTER12 DS FD FP register 12
PEP_COM_FP_REGISTER13 DS FD FP register 13
PEP_COM_FP_REGISTER14 DS FD FP register 14
PEP_COM_FP_REGISTER14 DS FD FP register 15
PEP_COM_FPC_REGISTER DS F FPC register
PEP_COM_ACCESS_REGISTERS DS CL64 Access registers
**
* 16 byte PSW at time of abend
*
PEP_COM_PSW16 DS CL16 16 byte PSW
*
* Vector Register Information
*
PEP_COM_VR_REGISTERS DS 0CL512 VR registers
PEP_COM_VR_REGISTER0 DS CL16 VR Register 0
PEP_COM_VR_REGISTER1 DS CL16 VR Register 1
PEP_COM_VR_REGISTER2 DS CL16 VR Register 2
PEP_COM_VR_REGISTER3 DS CL16 VR Register 3
PEP_COM_VR_REGISTER4 DS CL16 VR Register 4
PEP_COM_VR_REGISTER5 DS CL16 VR Register 5
PEP_COM_VR_REGISTER6 DS CL16 VR Register 6
PEP_COM_VR_REGISTER7 DS CL16 VR Register 7
PEP_COM_VR_REGISTER8 DS CL16 VR Register 8
PEP_COM_VR_REGISTER9 DS CL16 VR Register 9
PEP_COM_VR_REGISTER10 DS CL16 VR Register 10
PEP_COM_VR_REGISTER11 DS CL16 VR Register 11
PEP_COM_VR_REGISTER12 DS CL16 VR Register 12
PEP_COM_VR_REGISTER13 DS CL16 VR Register 13
PEP_COM_VR_REGISTER14 DS CL16 VR Register 14
PEP_COM_VR_REGISTER15 DS CL16 VR Register 15
PEP_COM_VR_REGISTER16 DS CL16 VR Register 16
PEP_COM_VR_REGISTER17 DS CL16 VR Register 17
PEP_COM_VR_REGISTER18 DS CL16 VR Register 18
PEP_COM_VR_REGISTER19 DS CL16 VR Register 19
PEP_COM_VR_REGISTER20 DS CL16 VR Register 20
PEP_COM_VR_REGISTER21 DS CL16 VR Register 21
PEP_COM_VR_REGISTER22 DS CL16 VR Register 22
PEP_COM_VR_REGISTER23 DS CL16 VR Register 23
PEP_COM_VR_REGISTER24 DS CL16 VR Register 24
PEP_COM_VR_REGISTER25 DS CL16 VR Register 25
PEP_COM_VR_REGISTER26 DS CL16 VR Register 26
PEP_COM_VR_REGISTER27 DS CL16 VR Register 27
PEP_COM_VR_REGISTER28 DS CL16 VR Register 28
PEP_COM_VR_REGISTER29 DS CL16 VR Register 29
PEP_COM_VR_REGISTER30 DS CL16 VR Register 30
PEP_COM_VR_REGISTER31 DS CL16 VR Register 31
* length of DFHPEP_COMMAREA
*
PEP_COM_LEN EQU *-PEP_COM_STANDARD