CICS Error Handling: RESP, HANDLE ABEND, ABEND Codes — Complete Guide

Introduction: Why CICS Error Handling Is Different from Batch

In batch COBOL, an unhandled error typically results in a job step that ends with a non-zero return code — the operator sees an abend dump, the job is restarted, and the impact is contained to that one job. In CICS, an unhandled error ABENDs a task that may be serving one of thousands of simultaneous online users. A poorly handled CICS error can corrupt shared storage, hold locks that block other users, or — in extreme cases — crash the entire CICS region.

This makes robust error handling not just a coding best practice in CICS — it is a production reliability requirement. This guide covers the complete CICS error handling toolkit: RESP checking, HANDLE ABEND, intentional ABENDs, the most common ABEND codes and their causes, and production-quality error logging patterns.

The Modern Approach: RESP and RESP2

Every EXEC CICS command that can return an error condition supports the RESP and RESP2 options. Specifying these options suppresses the automatic CICS ABEND that would otherwise occur when a command fails, and instead populates the EIB fields EIBRESP and EIBRESP2 and your working-storage variables with the response codes.

WORKING-STORAGE SECTION.
01  WS-RESP     PIC S9(8) COMP VALUE ZERO.
01  WS-RESP2    PIC S9(8) COMP VALUE ZERO.

PROCEDURE DIVISION.
    EXEC CICS READ FILE('EMPFILE')
                   RIDFLD(WS-EMP-KEY)
                   INTO(WS-EMP-REC)
                   LENGTH(WS-EMP-LEN)
                   RESP(WS-RESP)
                   RESP2(WS-RESP2)
    END-EXEC

    EVALUATE WS-RESP
        WHEN DFHRESP(NORMAL)
            PERFORM DISPLAY-EMPLOYEE
        WHEN DFHRESP(NOTFND)
            *> Expected business condition — not an error
            MOVE 'EMPLOYEE NOT FOUND.' TO MSGO
            PERFORM SEND-MAP-DATAONLY
        WHEN DFHRESP(DISABLED)
            *> Configuration issue — tell DBA
            MOVE 'FILE DISABLED. CONTACT SUPPORT.' TO MSGO
            PERFORM SEND-MAP-DATAONLY
        WHEN OTHER
            *> Unexpected — log and present generic error
            PERFORM LOG-CICS-ERROR
            MOVE 'SYSTEM ERROR. PLEASE CONTACT SUPPORT.' TO MSGO
            PERFORM SEND-MAP-DATAONLY
    END-EVALUATE.

Key DFHRESP constants for file operations:

A Comprehensive Error Logging Routine

Every CICS program should have a standard error logging routine. The minimum information to log is: timestamp, transaction ID, terminal ID, program name, EIBRESP, EIBRESP2, EIBFN, and EIBRSRCE (the resource name involved in the failing command). Log to a Transient Data Queue or Temporary Storage queue for subsequent batch review.

WORKING-STORAGE SECTION.
01  WS-ERR-RECORD.
    05  WS-ERR-DATE    PIC X(10).
    05  WS-ERR-TIME    PIC X(08).
    05  WS-ERR-TRNID   PIC X(04).
    05  WS-ERR-TRMID   PIC X(04).
    05  WS-ERR-PGMID   PIC X(08).
    05  WS-ERR-RESP    PIC +9(8).
    05  WS-ERR-RESP2   PIC +9(8).
    05  WS-ERR-FN      PIC X(02).
    05  WS-ERR-RSRCE   PIC X(08).
    05  WS-ERR-MSG     PIC X(60).
01  WS-ABSTIME         PIC S9(15) COMP-3.

LOG-CICS-ERROR.
    *── Capture time ─────────────────────────────────────────────
    EXEC CICS ASKTIME ABSTIME(WS-ABSTIME) END-EXEC
    EXEC CICS FORMATTIME ABSTIME(WS-ABSTIME)
              DDMMYYYY(WS-ERR-DATE)
              DATESEP('/')
              TIME(WS-ERR-TIME)
              TIMESEP(':')
    END-EXEC

    *── Populate error record ────────────────────────────────────
    MOVE EIBTRNID    TO WS-ERR-TRNID
    MOVE EIBTRMID    TO WS-ERR-TRMID
    MOVE 'EMPMAINT'  TO WS-ERR-PGMID
    MOVE EIBRESP     TO WS-ERR-RESP
    MOVE EIBRESP2    TO WS-ERR-RESP2
    MOVE EIBFN       TO WS-ERR-FN
    MOVE EIBRSRCE    TO WS-ERR-RSRCE
    MOVE WS-ERR-MSG  TO WS-ERR-MSG

    *── Write to error TDQ ───────────────────────────────────────
    EXEC CICS WRITEQ TD
              QUEUE('CSERR')
              FROM(WS-ERR-RECORD)
              LENGTH(LENGTH OF WS-ERR-RECORD)
    END-EXEC.

EXEC CICS HANDLE ABEND: Catching ABENDs

Before RESP checking became the standard, CICS programs used HANDLE ABEND to catch all ABENDs and route to a recovery paragraph:

PROCEDURE DIVISION.
    *── Set up global ABEND handler ──────────────────────────────
    EXEC CICS HANDLE ABEND
                     LABEL(ABEND-HANDLER)
    END-EXEC

    PERFORM MAIN-PROCESSING
    EXEC CICS RETURN END-EXEC.

ABEND-HANDLER.
    *── Control arrives here on any ABEND ────────────────────────
    *── EIBRESP, EIBFN, EIBRSRCE are set ────────────────────────
    PERFORM LOG-CICS-ERROR
    MOVE 'UNEXPECTED ERROR. TRANSACTION CANCELLED.' TO MSGO
    PERFORM SEND-ERR-MAP
    EXEC CICS RETURN END-EXEC.

HANDLE ABEND intercepts: program checks (ASRA), CICS-detected errors that would ABEND, and programmatic ABENDs from EXEC CICS ABEND. It does NOT intercept: system ABENDs caused by z/OS (SVC dumps, machine checks), or ABENDs in subprograms that have their own HANDLE ABEND in effect.

Important: HANDLE ABEND must be set up before the code that might ABEND. It stays in effect until cancelled with EXEC CICS HANDLE ABEND CANCEL.

For new development, RESP checking at each command is strongly preferred over HANDLE ABEND because it gives precise error handling at each command rather than catching everything in one catch-all handler.

EXEC CICS ABEND: Intentional Task Termination

Your program can intentionally ABEND a task — for example, when a truly unrecoverable error occurs and the program cannot clean up properly:

HANDLE-UNRECOVERABLE-ERROR.
    PERFORM LOG-CICS-ERROR

    *── Send error screen if terminal is available ───────────────
    MOVE 'FATAL ERROR - TRANSACTION ABENDED.' TO MSGO
    EXEC CICS SEND MAP('ERRMAPX')
                   MAPSET('ERRMAPS')
                   FROM(ERRMAPO)
                   ERASE
    END-EXEC

    *── ABEND with custom code - NODUMP for expected conditions ──
    EXEC CICS ABEND ABCODE('EMPE')
                    NODUMP
    END-EXEC.

Custom ABEND codes are four characters and appear in CICS job logs and CICS monitoring records. Choose meaningful codes (EMPE for employee program error, ORDN for order not found, etc.) that operations staff can identify. Use NODUMP when the error is expected and a dump would provide no additional diagnostic value. Omit NODUMP for truly unexpected conditions where a full memory dump is needed to debug.

Common CICS ABEND Codes and Their Causes

Understanding the standard CICS ABEND codes is essential for debugging production issues:

ASRA — Program Check

Cause: A machine-level program interruption occurred: data exception (non-numeric data in packed decimal field), divide by zero, addressing exception (access to invalid storage address), or operation exception.

Common code causes:

• Moving non-numeric data into a COMP-3 field and then doing arithmetic
• Accessing DFHCOMMAREA without checking EIBCALEN first (EIBCALEN = 0 → DFHCOMMAREA address is invalid)
• An uninitialised pointer variable used in a SET ADDRESS OF statement

Diagnosis: ASRA always generates a dump. Look at the Program Status Word (PSW) in the dump to find the failing instruction offset, then cross-reference to the COBOL source.

AICA — Runaway Task

Cause: The task exceeded the maximum CPU time limit set in the CICS region's ICT (Interval Control Time) parameter or the MAXTASKS setting.

Common causes: An infinite loop (PERFORM UNTIL condition that never becomes true), a browse loop that never reaches ENDFILE, or a SQL query without a row limit that processes a full table scan on millions of rows.

Fix: Add loop termination guards, limit SQL result sets with FETCH FIRST, or increase the time limit for legitimately long-running tasks.

AEY9 — DB2 Not Available

Cause: The CICS-DB2 Attachment Facility is not active, or the DB2 subsystem specified in the DB2CONN resource is not running.

Common causes: DB2 is being recycled, the DB2 connection has not been started, or the EXEC SQL command specified a plan name that is not bound.

Fix: Ensure DB2 is running, verify the CICS DB2CONN and DB2ENTRY resource definitions, and ensure the application plan is bound with EXEC CICS START(DB2CONN).

AFCA — File Control Failure

Cause: A VSAM file control command resulted in a VSAM physical error that CICS could not handle. This is distinct from a logical error (NOTFND, DUPREC) — AFCA indicates VSAM itself encountered an I/O problem.

Common causes: VSAM dataset is physically corrupted, I/O error on the volume, or the dataset is in use by a conflicting process.

Fix: Run IDCAMS VERIFY to check the dataset integrity, then IDCAMS REPRO or RECOVER to repair it.

AEIA — Environment Error

Cause: A CICS command was issued in an inappropriate context — for example, attempting to issue a terminal I/O command when no terminal is associated with the task (e.g., a started task or a CICS trigger program).

AEIP — Program Not Executable

Cause: A program named in EXEC CICS LINK or XCTL is defined in the CSD but cannot be loaded — typically because the load module is missing from the CICS load library or the DFHRPL concatenation.

Structured Error Handling Template

Here is a production-quality error handling template for a CICS COBOL program:

*── Error handling constants ──────────────────────────────────────
01  WS-FATAL-ERROR-FLAG    PIC X VALUE 'N'.
    88  WS-FATAL-ERROR           VALUE 'Y'.

*── Standard error response macro (inline) ────────────────────────
*── After every EXEC CICS command: ───────────────────────────────
*──   IF WS-RESP NOT = DFHRESP(NORMAL) ───────────────────────────
*──     MOVE 'description' TO WS-ERR-MSG ─────────────────────────
*──     PERFORM LOG-AND-PRESENT-ERROR ────────────────────────────
*──     MOVE 'Y' TO WS-FATAL-ERROR-FLAG ──────────────────────────
*──   END-IF ─────────────────────────────────────────────────────

LOG-AND-PRESENT-ERROR.
    PERFORM LOG-CICS-ERROR
    MOVE 'SYSTEM ERROR OCCURRED. PLEASE TRY AGAIN.' TO MSGO
    PERFORM SEND-MAP-DATAONLY.

SEND-MAP-DATAONLY.
    EXEC CICS SEND MAP('EMPIMAP')
                   MAPSET('EMPIMAPS')
                   FROM(EMPIMAPO)
                   DATAONLY
                   RESP(WS-RESP)
    END-EXEC
    EXEC CICS RETURN
              TRANSID(EIBTRNID)
              COMMAREA(WS-COMMAREA)
              LENGTH(LENGTH OF WS-COMMAREA)
    END-EXEC.

Key Takeaways

CICS error handling is a critical production discipline. The modern approach — RESP and RESP2 on every command, EVALUATE WS-RESP for precise handling, and a standard LOG-CICS-ERROR routine — gives complete control and visibility without the unpredictability of catch-all HANDLE ABEND. Distinguish between expected business conditions (NOTFND, DUPREC — handle gracefully and continue), unexpected system conditions (DISABLED, NOSPACE — log and present a message), and fatal errors (AFCA, unrecoverable ASRA — log and use EXEC CICS ABEND). Master the common ABEND codes (ASRA, AICA, AEY9, AFCA) and you will be prepared to diagnose and fix the overwhelming majority of CICS production issues.

For understanding how CICS manages dynamic memory allocation within a task, continue with CICS Storage Control. For the complete CICS course, visit the CICS Mastery Course.