CICS HANDLE CONDITION

The HANDLE CONDITION command is used to manage specific conditions that may arise during execution. It represents a control passing label or paragraph to be executed if a defined condition occurs.

It is important to execute the HANDLE CONDITION command before the command that could trigger the condition. Additionally, users can specify up to 16 conditions in a single HANDLE CONDITION command.

• The HANDLE CONDITION command is only applicable to the specific program in which it is defined.
• If another HANDLE CONDITION command for the same condition is coded, the new command will override the previous one.
• HANDLE CONDITION options are applicable to the program where they are coded.

Why?

• Prevents unexpected transaction failures by handling predictable errors.
• Redirects execution to a user-defined error-handling section.
• Improves debugging by capturing and logging error details before terminating execution.

Key Features -

• Intercepts and handles specific error conditions instead of crashing the program.
• Transfers control to an error-handling routine when an error occurs.
• Only affects the conditions specified in the command.
• Multiple conditions can be handled in a single program.
• Can be disabled using the IGNORE or NOHANDLE option if needed.

Syntax -

EXEC CICS HANDLE CONDITION
     ERROR-CODE(LABEL)
     [ERROR-CODE2(LABEL2) ...]
     END-EXEC.

• ERROR-CODE - Specifies the CICS condition to handle (e.g., NOTFND, INVREQ). Common Error Codes -
  • NOTFND - Record not found in a VSAM file or DB2 table.
  • INVREQ - Invalid request made to CICS.
  • ILLOGIC - Logical error detected in VSAM file operations.
  • ITEMERR - Item requested in a queue or storage area does not exist.
  • DUPKEY - A duplicate key was found while inserting a record.
  • QIDERR - An invalid queue ID was used in a TS or TD queue.
• LABEL - Specifies the paragraph or section to which control is transferred if the error occurs.

Short Examples -

Scenario1 - Handling Record Not Found (NOTFND)

...
PROCEDURE DIVISION.

    EXEC CICS HANDLE CONDITION
         NOTFND(ERROR-HANDLER)
         END-EXEC.
		 
    EXEC CICS READ
         DATASET('CUSTFILE')
         INTO(WS-DATA)
         RESP(WS-RESP)
         END-EXEC.

    IF WS-RESP NOT = 0 THEN
       ...
	END-IF.

ERROR-HANDLER.
    MOVE "ERROR: Record not found in CUSTOMER-FILE "
	  TO ERROR-MSG1.
    
    EXEC CICS RETURN
         END-EXEC.

When the record is not found during the file read, the control transfers to the ERROR-HANDLER paragraph.

Scenario2 - Handling Multiple Error Conditions

...
PROCEDURE DIVISION.

    EXEC CICS HANDLE CONDITION
         DUPKEY(DUPLICATE-KEY-HANDLER)
         INVREQ(INVALID-REQUEST-HANDLER)
         END-EXEC.
		 
    EXEC CICS WRITE
         DATASET('CUSTFILE')
         FROM(WS-RECORD)
         RESP(WS-RESP)
         END-EXEC.

    IF WS-RESP NOT = 0 THEN
       ...
	END-IF.

DUPLICATE-KEY-HANDLER.
    MOVE "ERROR: Duplicate key detected"
	  TO ERROR-MSG1
    EXEC CICS RETURN
		END-EXEC.

INVALID-REQUEST-HANDLER.
    MOVE "ERROR: Invalid request made to CICS"
	  TO ERROR-MSG1
    EXEC CICS RETURN 
		END-EXEC.

When the record is already in the file during the file write, the control transfers to the DUPLICATE-KEY-HANDLER paragraph. If the file write request is invaid, then control transfers to INVALID-REQUEST-HANDLER paragraph.

---