Using the HANDLE CONDITION command

Use the HANDLE CONDITION command to specify the label to which control is to be passed if a condition occurs.

About this task

When you use this command, you must include the name of the condition and ensure that the HANDLE CONDITION command is executed before the command that might give rise to the associated condition.

Restriction: This command is supported only in COBOL, PL/I, and assembler language applications (but not AMODE(64) assembler language applications). It is not supported in all other supported high level languages.

You cannot include more than 16 conditions in the same command. You must specify any additional conditions in further HANDLE CONDITION commands. You can also use the ERROR condition in the same list to specify that all other conditions cause control to be passed to the same label.

The HANDLE CONDITION command for a given condition applies only to the program in which it is specified. The command remains active while the program is running, or until one of the following events:
  • An IGNORE CONDITION command for the same condition is met. The HANDLE CONDITION command is overridden.
  • Another HANDLE CONDITION command for the same condition is met. The new command overrides the previous one.

The HANDLE CONDITION command is temporarily deactivated by the NOHANDLE or RESP option on a command.

When control passes to another program, by a LINK or XCTL command, the HANDLE CONDITION commands that were active in the calling program are deactivated. When control returns to a program from a program at a lower logical level, the HANDLE CONDITION commands that were active in the higher-level program before control was transferred from it are reactivated, and those in the lower-level program are deactivated. (Refer to Application program logical levels for information about logical levels.)

The following example shows how to handle conditions, for example DUPREC and LENGERR, that can occur when you use a WRITE command to add a record to a data set. In the example, DUPREC is handled as a special case. Standard system action is taken for LENGERR; that is, terminate the task abnormally. All other conditions are handled by the error routine ERRHANDL. 
 EXEC CICS HANDLE CONDITION
ERROR(ERRHANDL)
DUPREC(DUPRTN) LENGERR
END-EXEC.

In a PL/I application program, a branch to a label in an inactive procedure or in an inactive begin block, caused by a condition, produces unpredictable results.

In an assembler language application program, when a branch to a label is caused by a condition, the registers in the application program are restored to their values in the program at the point where the command that caused the condition is issued.