CICS Condition Management

Condition management is a fundamental aspect of CICS programming that allows you to handle exception conditions gracefully. When CICS commands encounter unusual situations, they generate exception conditions. Understanding how to manage these conditions is essential for building robust, production-ready CICS applications.

Think of condition management like having a safety net for your program. Just as a trapeze artist has a net to catch them if they fall, condition management catches errors and allows your program to handle them gracefully instead of crashing unexpectedly.

What is Condition Management?

Condition management in CICS refers to the mechanisms available to handle exception conditions that occur during the execution of CICS commands. An exception condition is an abnormal situation that arises when a CICS command encounters an unexpected or error state.

Without proper condition management, when an exception occurs, CICS typically terminates the task abnormally, resulting in an incomplete transaction and potential data inconsistency. Condition management allows you to:

• Prevent Unexpected Terminations: Handle errors gracefully instead of allowing program abends
• Provide User Feedback: Inform users about errors in a meaningful way
• Implement Recovery Logic: Attempt to recover from error conditions when possible
• Maintain Data Integrity: Ensure transactions complete successfully or roll back properly
• Improve Debugging: Log errors and provide diagnostic information

Types of Exception Conditions

CICS exception conditions can be categorized into several types:

• File Operation Conditions: NOTFND (record not found), DUPREC (duplicate record), ENDDATA (end of file)
• Map Operation Conditions: MAPFAIL (map receive failed), LENGERR (length error)
• Program Control Conditions: PGMIDERR (program not found), INVREQ (invalid request)
• Queue Operation Conditions: ITEMERR (item not found), QIDERR (invalid queue ID)
• System Conditions: ILLOGIC (logical error), various system-level errors

HANDLE CONDITION Command

The HANDLE CONDITION command is used to specify a label or paragraph that receives control when a specific exception condition occurs. This allows you to implement custom error handling logic for anticipated conditions.

Syntax

1
2
3
4
5
6
EXEC CICS HANDLE CONDITION
     condition-name(label-name)
     [condition-name2(label-name2)]
     ...
     [ERROR(general-error-label)]
END-EXEC.

Parameters:

• condition-name: The name of the exception condition to handle (e.g., NOTFND, DUPREC, MAPFAIL)
• label-name: The paragraph or section name where control should be transferred
• ERROR: Optional catch-all condition for any error not explicitly specified

Basic Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
IDENTIFICATION DIVISION.
PROGRAM-ID. HANDLE-EXAMPLE.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CUSTOMER-RECORD.
   05 CUST-ID        PIC X(8).
   05 CUST-NAME      PIC X(30).
   05 CUST-ADDRESS   PIC X(50).
 
PROCEDURE DIVISION.
    *> Set up condition handlers before commands that might fail
    EXEC CICS HANDLE CONDITION
         NOTFND(RECORD-NOT-FOUND)
         DUPREC(DUPLICATE-RECORD)
         ERROR(GENERAL-ERROR)
    END-EXEC.
 
    *> Attempt to read a customer record
    EXEC CICS READ
         DATASET('CUSTFILE')
         INTO(CUSTOMER-RECORD)
         RIDFLD(CUST-ID)
    END-EXEC.
 
    *> If we reach here, the read was successful
    DISPLAY 'Customer record read successfully'
    EXEC CICS RETURN END-EXEC.
 
RECORD-NOT-FOUND.
    DISPLAY 'ERROR: Customer record not found'
    EXEC CICS RETURN END-EXEC.
 
DUPLICATE-RECORD.
    DISPLAY 'ERROR: Duplicate record detected'
    EXEC CICS RETURN END-EXEC.
 
GENERAL-ERROR.
    DISPLAY 'ERROR: An unexpected error occurred'
    EXEC CICS RETURN END-EXEC.

In this example, if the READ command cannot find the record, control transfers to RECORD-NOT-FOUND. If a duplicate record is detected during a WRITE operation, control goes to DUPLICATE-RECORD. Any other unhandled error goes to GENERAL-ERROR.

Handling Multiple Conditions

You can handle multiple conditions in a single HANDLE CONDITION command (up to 16 conditions):

1
2
3
4
5
6
7
8
EXEC CICS HANDLE CONDITION
     MAPFAIL(MAP-ERROR-HANDLER)
     LENGERR(LENGTH-ERROR-HANDLER)
     PGMIDERR(PROGRAM-ERROR-HANDLER)
     NOTFND(FILE-ERROR-HANDLER)
     DUPREC(DUPLICATE-HANDLER)
     ERROR(GENERAL-ERROR-HANDLER)
END-EXEC.

Scope of HANDLE CONDITION

HANDLE CONDITION remains active from where it appears until:

• The end of the program
• Another HANDLE CONDITION for the same condition is encountered (overrides the previous one)
• An IGNORE CONDITION for the same condition is encountered
• A NOHANDLE option is specified on a command (temporarily deactivates it for that command)

Important: HANDLE CONDITION applies only to the program where it's specified. It does not automatically apply to programs called via LINK, XCTL, or CALL.

RESP Option (Recommended Approach)

The RESP option is the modern, recommended approach for condition management. Instead of transferring control to a label, RESP sets a response code that you check after command execution. This provides more control and doesn't interrupt the normal program flow.

Syntax

1
2
3
4
5
6
7
8
9
10
EXEC CICS command-name
     [other-options]
     RESP(response-variable)
END-EXEC.
 
IF response-variable = 0 THEN
    *> Command succeeded
ELSE
    *> Handle error based on response code
END-IF.

RESP Option Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
IDENTIFICATION DIVISION.
PROGRAM-ID. RESP-EXAMPLE.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CUSTOMER-RECORD.
   05 CUST-ID        PIC X(8).
   05 CUST-NAME      PIC X(30).
 
01 WS-RESP           PIC S9(8) COMP.
01 WS-RESP2          PIC S9(8) COMP.
 
PROCEDURE DIVISION.
    *> Read customer record with RESP option
    EXEC CICS READ
         DATASET('CUSTFILE')
         INTO(CUSTOMER-RECORD)
         RIDFLD(CUST-ID)
         RESP(WS-RESP)
         RESP2(WS-RESP2)
    END-EXEC.
 
    *> Check response code
    EVALUATE WS-RESP
        WHEN 0
            DISPLAY 'Record read successfully'
            *> Continue normal processing
            
        WHEN 13  *> NOTFND condition
            DISPLAY 'ERROR: Customer record not found'
            *> Handle not found condition
            
        WHEN 22  *> DUPREC condition
            DISPLAY 'ERROR: Duplicate record'
            *> Handle duplicate condition
            
        WHEN OTHER
            DISPLAY 'ERROR: Unexpected error - Response: ' WS-RESP
            *> Handle other errors
    END-EVALUATE.
 
    EXEC CICS RETURN END-EXEC.

Response Code Values:

• 0: Normal (command completed successfully)
• 4: Warning (command completed with warnings)
• 8: Error (command failed)
• 13: NOTFND (record not found)
• 20: ENDDATA (end of file)
• 22: DUPREC (duplicate record)
• Other values: Various specific error conditions

Advantages of RESP Option

• No Control Transfer: Program flow continues normally, making code easier to follow
• Structured Error Handling: Use IF/EVALUATE statements for clear error logic
• Multiple Error Checks: Easy to check multiple conditions in sequence
• Better Debugging: Response codes provide specific error information
• Modern Best Practice: Recommended by IBM for new CICS applications

IGNORE CONDITION Command

The IGNORE CONDITION command tells CICS to take no action when a specific condition occurs. Execution continues to the next statement after the command that encountered the condition.

Syntax

1
2
3
4
5
EXEC CICS IGNORE CONDITION
     condition-name
     [condition-name2]
     ...
END-EXEC.

When to Use IGNORE CONDITION

Use IGNORE CONDITION when you've determined that a specific condition is safe to ignore in your context. Common scenarios include:

• You've already checked for the condition using RESP option
• The condition is expected and doesn't require special handling
• You want to use default CICS behavior for that condition

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
IDENTIFICATION DIVISION.
PROGRAM-ID. IGNORE-EXAMPLE.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01 MAP-DATA           PIC X(100).
 
PROCEDURE DIVISION.
    *> Ignore LENGERR for this RECEIVE command
    *> We'll handle length checking manually
    EXEC CICS IGNORE CONDITION
         LENGERR
    END-EXEC.
 
    EXEC CICS RECEIVE MAP('CUSTMAP')
         INTO(MAP-DATA)
         RESP(WS-RESP)
    END-EXEC.
 
    *> If LENGERR occurs, it's ignored and we continue here
    *> We can check WS-RESP to see if there were other errors
    IF WS-RESP = 0 THEN
        DISPLAY 'Map received successfully'
    END-IF.
 
    EXEC CICS RETURN END-EXEC.

Important: Be careful when using IGNORE CONDITION. Only ignore conditions that you've thoroughly analyzed and determined are safe to ignore. Ignoring critical conditions can lead to data corruption or unexpected program behavior.

NOHANDLE Option

The NOHANDLE option can be specified on any CICS command to temporarily deactivate HANDLE CONDITION and IGNORE CONDITION for that specific command. This allows you to use default CICS behavior for a particular command while maintaining condition handling for other commands.

Syntax

1
2
3
4
EXEC CICS command-name
     [other-options]
     NOHANDLE
END-EXEC.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
IDENTIFICATION DIVISION.
PROGRAM-ID. NOHANDLE-EXAMPLE.
 
PROCEDURE DIVISION.
    *> Set up condition handlers
    EXEC CICS HANDLE CONDITION
         NOTFND(ERROR-HANDLER)
         ERROR(GENERAL-ERROR)
    END-EXEC.
 
    *> This command uses the HANDLE CONDITION
    EXEC CICS READ
         DATASET('FILE1')
         INTO(WS-RECORD1)
         RIDFLD(WS-KEY1)
    END-EXEC.
 
    *> This command ignores HANDLE CONDITION and uses default behavior
    EXEC CICS READ
         DATASET('FILE2')
         INTO(WS-RECORD2)
         RIDFLD(WS-KEY2)
         NOHANDLE
    END-EXEC.
 
    *> This command again uses the HANDLE CONDITION
    EXEC CICS READ
         DATASET('FILE3')
         INTO(WS-RECORD3)
         RIDFLD(WS-KEY3)
    END-EXEC.
 
ERROR-HANDLER.
    DISPLAY 'Error handler called'
    EXEC CICS RETURN END-EXEC.
 
GENERAL-ERROR.
    DISPLAY 'General error handler called'
    EXEC CICS RETURN END-EXEC.

In this example, the second READ command uses NOHANDLE, so if NOTFND occurs, it won't transfer to ERROR-HANDLER. Instead, CICS takes the default action (typically task termination). The first and third READ commands still use the HANDLE CONDITION.

Common Exception Conditions

Understanding common exception conditions helps you write better error handling code. Here are the most frequently encountered conditions:

Condition Response Codes

When using the RESP option, each condition has a corresponding numeric response code:

• NOTFND: Response code 13 - Record not found
• DUPREC: Response code 22 - Duplicate record
• MAPFAIL: Response code 28 - Map receive failed
• LENGERR: Response code 26 - Length error
• PGMIDERR: Response code 20 - Program ID error
• INVREQ: Response code 16 - Invalid request
• ENDDATA: Response code 20 - End of data

Best Practices for Condition Management

1. Use RESP Option for New Code

Prefer the RESP option over HANDLE CONDITION for new CICS applications. It provides better control and maintains program flow.

2. Always Check Response Codes

After every CICS command that uses RESP, check the response code. Don't assume commands always succeed.

1
2
3
4
5
6
7
8
9
10
11
12
EXEC CICS READ
     DATASET('CUSTFILE')
     INTO(WS-RECORD)
     RIDFLD(WS-KEY)
     RESP(WS-RESP)
END-EXEC.
 
*> ALWAYS check the response
IF WS-RESP NOT = 0 THEN
    *> Handle error appropriately
    PERFORM ERROR-HANDLING
END-IF.

3. Provide Meaningful Error Messages

When handling errors, provide clear, user-friendly error messages that help users understand what went wrong and what they can do about it.

4. Log Errors for Debugging

Log error conditions with sufficient detail (response codes, context, timestamps) to help with debugging and troubleshooting in production.

5. Handle Conditions Before Commands

Always set up HANDLE CONDITION commands before the CICS commands that might trigger those conditions. HANDLE CONDITION must be executed before the condition occurs.

6. Use ERROR as a Safety Net

Include an ERROR condition handler as a catch-all for unexpected conditions. This prevents unhandled errors from causing unexpected program termination.

7. Be Careful with IGNORE CONDITION

Only ignore conditions that you've thoroughly analyzed. Ignoring critical conditions can lead to data corruption or security issues.

8. Test Error Conditions

Don't just test the happy path. Test error conditions to ensure your error handling works correctly. Use test data that triggers various error conditions.

Complete Example: File Processing with Error Handling

Here's a complete example showing proper condition management in a file processing scenario:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
IDENTIFICATION DIVISION.
PROGRAM-ID. FILE-PROCESSING-EXAMPLE.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CUSTOMER-RECORD.
   05 CUST-ID        PIC X(8).
   05 CUST-NAME      PIC X(30).
   05 CUST-ADDRESS   PIC X(50).
   05 CUST-BALANCE   PIC S9(9)V99 COMP-3.
 
01 WS-RESP           PIC S9(8) COMP.
01 WS-RESP2          PIC S9(8) COMP.
01 WS-ERROR-MSG      PIC X(80).
 
PROCEDURE DIVISION.
MAIN-PROCESSING.
    *> Set up error handlers using HANDLE CONDITION
    EXEC CICS HANDLE CONDITION
         ERROR(GENERAL-ERROR-HANDLER)
    END-EXEC.
 
    *> Read customer record with RESP option
    EXEC CICS READ
         DATASET('CUSTFILE')
         INTO(CUSTOMER-RECORD)
         RIDFLD(CUST-ID)
         RESP(WS-RESP)
         RESP2(WS-RESP2)
    END-EXEC.
 
    *> Check response and handle accordingly
    EVALUATE WS-RESP
        WHEN 0
            *> Success - process the record
            DISPLAY 'Customer: ' CUST-NAME
            DISPLAY 'Balance: ' CUST-BALANCE
            PERFORM PROCESS-CUSTOMER
            
        WHEN 13  *> NOTFND
            MOVE 'Customer record not found' TO WS-ERROR-MSG
            PERFORM DISPLAY-ERROR
            
        WHEN 22  *> DUPREC (shouldn't happen on READ, but handle it)
            MOVE 'Duplicate record error' TO WS-ERROR-MSG
            PERFORM DISPLAY-ERROR
            
        WHEN OTHER
            MOVE 'Unexpected error occurred' TO WS-ERROR-MSG
            PERFORM DISPLAY-ERROR
            *> Log the actual response code for debugging
            DISPLAY 'Response code: ' WS-RESP
    END-EVALUATE.
 
    EXEC CICS RETURN END-EXEC.
 
PROCESS-CUSTOMER.
    *> Business logic to process customer record
    *> This is where you'd implement your actual processing logic
    DISPLAY 'Processing customer record...'
    .
 
DISPLAY-ERROR.
    *> Display error message to user
    DISPLAY 'ERROR: ' WS-ERROR-MSG
    *> In a real application, you might send this to a map
    *> or log it to a file
    .
 
GENERAL-ERROR-HANDLER.
    *> Catch-all error handler for unhandled conditions
    DISPLAY 'A general error occurred'
    EXEC CICS RETURN END-EXEC.

This example demonstrates:

• Using HANDLE CONDITION with ERROR as a safety net
• Using RESP option for structured error checking
• EVALUATE statement for clear error handling logic
• Meaningful error messages
• Separation of error handling into separate paragraphs