HANDLE CONDITION
Handle conditions.
Syntax
This command is threadsafe.
NOHANDLE, RESP, and
RESP2 are common options that can be added to all EXEC CICS
commands to process error conditions. They are not explicitly included in the command syntax diagram
and option descriptions. For information about these common options and EXEC CICS
command syntax, see EXEC CICS command format and programming considerations.
Description
Use the HANDLE CONDITION command to specify the label to which control is to be passed if a condition occurs. You must include the name of the condition and, optionally, a label to which control is to be passed if the condition occurs.
If you omit the label parameter, any HANDLE CONDITION command for the condition is deactivated, and the default action is taken if the condition occurs. This is independent of the setting of the generalized ERROR condition.
You must ensure that the HANDLE CONDITION command is executed before the command that might result in the associated condition.
You cannot include more than 16 conditions in the same command. The conditions must be separated by at least one space. You must specify any additional conditions in further HANDLE CONDITION commands.
If a condition occurs that is not specified in a HANDLE CONDITION or IGNORE CONDITION command, the default action is taken. However, if the default action for such a condition terminates the task abnormally, and the condition ERROR has been specified, the action for ERROR is taken.
The label receives control in the same execution key as the execution key that the program was running in when the HANDLE CONDITION command was issued.
When CICS handles a condition, the application's program mask is restored to the value that it had when the EXEC CICS HANDLE CONDITION command was issued.
In a Java program, to handle a specific condition, such as PGMIDERR, use a catch clause that names the appropriate exception; in this example, InvalidProgramException. Alternatively, use a catch clause that names CicsConditionException, if all CICS® conditions are to be caught.
Scope
- An IGNORE CONDITION command for the same condition is encountered. The HANDLE CONDITION command is overridden.
- Another HANDLE CONDITION command for the same condition is encountered. The new command overrides the previous one.
- A LINK command is executed to call another CICS program. The HANDLE CONDITION options are not inherited by the linked-to program.
The HANDLE CONDITION command is temporarily deactivated by the NOHANDLE or RESP option on a command.
Language considerations
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.
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.
Options
- condition(label)
- Specifies the name of the condition. label specifies the location in the program to be branched to if the condition occurs.
For a list of the condition names which you would use as part of the HANDLE CONDITION command, see EIBRESP Table for CICS Condition names.
Example
The following example shows how to handle conditions such as DUPREC and LENGERR that can occur when you use a WRITE command to add a record to a data set. DUPREC is handled as a special case. Default action is taken for LENGERR (that is, the task is terminated abnormally). All other conditions are handled by the error routine ERRHANDL.
EXEC CICS HANDLE CONDITION
ERROR(ERRHANDL)
DUPREC(DUPRTN) LENGERR