CICS Problem Determination

When a CICS transaction fails or abends, problem determination is the process of finding out why. You use response codes (EIBRESP, EIBRESP2), error handling in your program (HANDLE CONDITION, NOHANDLE), dumps (transaction and system), and trace data to locate the cause. This page explains how to handle command responses, avoid unnecessary abends, and use dumps and trace to diagnose failures.

Explain Like I'm Five: What Is Problem Determination?

When something goes wrong in CICS, problem determination is like being a detective. You look at the clues: Did the program get an error code from CICS (EIBRESP)? Did the task dump? What did the trace show? By handling errors in code (so the program does not crash when something expected happens) and by using dumps and trace when something unexpected happens, you can find out what failed and fix it.

Response Codes: EIBRESP and EIBRESP2

After every EXEC CICS command, CICS sets EIBRESP (and often EIBRESP2) in the EIB. EIBRESP is a numeric or symbolic code: DFHRESP(NORMAL) (or the equivalent numeric value) means success. Other values indicate a condition such as NOTFND (resource or record not found), DUPREC (duplicate key), INVREQ (invalid request), LENGERR (length error), or NOSPACE. EIBRESP2 can hold a subcode or additional detail. Your program should check these after commands that can fail, unless you use HANDLE CONDITION to transfer control to an error paragraph. If you do not handle the condition and the response is not normal, CICS may abend the task.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
       EXEC CICS READ
           FILE('CUSTFILE')
           RIDFLD(WS-KEY)
           INTO(WS-RECORD)
           NOHANDLE
       END-EXEC
 
       IF EIBRESP NOT = DFHRESP(NORMAL)
           IF EIBRESP = DFHRESP(NOTFND)
               PERFORM RECORD-NOT-FOUND
           ELSE
               PERFORM LOG-AND-ABEND
           END-IF
       END-IF

Handling Conditions: HANDLE CONDITION and NOHANDLE

HANDLE CONDITION lets you declare what to do when a specific condition occurs. You name the condition (e.g. NOTFND, DUPREC) and a paragraph or section to branch to. When that condition happens on a subsequent EXEC CICS command, CICS transfers control to that paragraph instead of abending. You can have multiple HANDLE CONDITIONs for different conditions. RESP and RESP2 options on the command let you store the response in working-storage variables instead of (or in addition to) using the EIB. NOHANDLE on a command means "do not automatically handle any condition for this command"; the program must check EIBRESP (or RESP/RESP2) and branch itself. Use NOHANDLE when you want in-line checks after every command. Use HANDLE CONDITION when you prefer a single error paragraph for a set of commands.

1
2
3
4
5
6
7
8
9
10
11
12
       *> Branch to paragraph on condition
       EXEC CICS HANDLE CONDITION
           NOTFND(NOT-FOUND-PARA)
           DUPREC(DUPLICATE-PARA)
       END-EXEC
 
       EXEC CICS READ FILE('X') RIDFLD(WS-KEY) INTO(WS-REC) END-EXEC
       *> If NOTFND, control goes to NOT-FOUND-PARA
       ...
       NOT-FOUND-PARA.
           MOVE 'NOT FOUND' TO WS-MESSAGE
           EXEC CICS RETURN END-EXEC.

Abends and Abend Codes

When a task ends abnormally, CICS produces an abend. The abend code (e.g. in the dump or in monitoring) identifies the type of failure. Some abends are application-related (e.g. bad data, unhandled condition); others are system or resource-related. Dump codes control whether CICS takes a dump and what type (transaction vs system) and what action to take (e.g. shutdown, propagate in a sysplex). Understanding the abend code and the dump (if present) helps you see where the program was and what state the task was in when it failed.

Transaction Dumps vs System Dumps

A CICS transaction dump captures information for the failing task: trace entries, control blocks, and task-related storage. It is the right choice for debugging application and transaction abends. You can request a transaction dump when a task is suspended or suspected of looping. A CICS system dump captures the entire CICS address space (and possibly more). It is used for system-level problems and is often requested by IBM Support. For most application issues, the transaction dump and the program's error handling (EIBRESP, HANDLE CONDITION) are what you need first.

Trace and AUXTRACE

CICS trace (e.g. AUXTRACE) records execution flow and component activity. When formatted (e.g. with the EYU9XZUT or equivalent utility), it shows the sequence of CICS commands and events. That helps you see exactly which command was running when the failure occurred and what happened before it. Trace data is one of the key artifacts for problem determination; keep it when investigating an abend and consider enabling it for the transaction or region if you need to reproduce an issue.

Step-by-Step: Handling a Failing Command in Code

1. Decide whether to use HANDLE CONDITION (branch to paragraph) or NOHANDLE (check after command).
2. If NOHANDLE: after the EXEC CICS command, check EIBRESP (or the variable in RESP). If not DFHRESP(NORMAL), branch to error logic. Use EIBRESP2 if you need more detail.
3. If HANDLE CONDITION: code HANDLE CONDITION for each condition you expect (e.g. NOTFND), naming the paragraph to run. In that paragraph, handle the error (message, return, retry, or abend as appropriate).
4. Log or display the response code and key data when an error occurs so operations and support can diagnose.

Step-by-Step: Diagnosing an Abend

1. Note the abend code and transaction id. Check whether a transaction dump (or system dump) was taken.
2. If you have a dump, format it (e.g. DFHDUP for transaction dumps) and look at the failing instruction and the task's control blocks and storage.
3. Review trace (e.g. AUXTRACE) to see the last commands executed and the sequence of events.
4. Correlate with your program: was a condition (e.g. NOTFND) unhandled? Was there bad data or a wrong key? Fix the program (add handling or fix logic) or the data/environment as needed.

Best Practices

• Check EIBRESP (or RESP/RESP2) after every EXEC CICS command that can fail, or use HANDLE CONDITION for expected conditions.
• Use NOHANDLE when you want explicit in-line checks; use HANDLE CONDITION to centralize error handling for a set of commands.
• Log response codes and key identifiers (transaction, task, resource name) when errors occur to aid problem determination.
• For application abends, use transaction dumps and trace first; involve system dumps and IBM Support only for system-level issues.

Test Your Knowledge