User-written condition handler interface

Use CEEHDLR to register a user-written condition handler. See z/OS Language Environment Programming Reference for more information about CEEHDLR.

User-written condition handlers are automatically unregistered when the stack frame they're associated with is removed from the stack due to a return, GOTO out of block, or a move of the resume cursor. You can, however, call CEEHDLU to explicitly unregister a user-written condition handler. See z/OS Language Environment Programming Reference for more information about CEEHDLU.

Recursion is allowed if a handler is registered within a handler, and nested conditions are allowed.

It is invalid to promote a condition without returning a new condition token. You cannot promote a condition to a PL/I condition.

Syntax

>>-condition_handler--(--c_ctok--,--token--,--result_code--,---->

>--new_condition--)--------------------------------------------><

c_ctok (input)

A 12-byte condition token that identifies the current condition being processed. Language Environment uses this parameter to tell your condition handler what condition has occurred.

token (input)

A 4-byte integer that specifies the token you passed into Language Environment when this condition handler was registered by a call to the CEEHDLR callable service.

result_code (output)

A 4-byte integer that contains instructions about responses the user-written condition handler wants Language Environment to make when processing the condition. The result_code is passed by reference. Valid responses are shown in Table 1.

Table 1. Valid result codes from user-written condition handlers

Response	Result_Code value	Action
resume	10	Resume at the resume cursor (condition has been handled). Unless the resume cursor has been moved, this response can only be used if the condition being handled specifically allows this form of resumption.
percolate	20	Percolate to the next condition handler. If a result_code is not explicitly set by a handler, this is the default result_code.
	21	Percolate to the first user-written condition handler for the stack frame that is before the one to which the handle cursor points. This can skip a language-specific condition handler for this stack frame as well as the remaining user-written condition handlers in the queue for this stack frame.
promote	30	Promote to the next condition handler.
	31	Promote to the stack frame before the one to which the handle cursor points. This can skip a language-specific condition handler for this stack frame as well as any remaining user-written condition handler in the queue at this stack frame.
	32	Promote and restart condition handling at the first condition handler of the stack frame of the handle cursor.
fix-up and resume	60	Provide the fix-up actions indicated by new_condition and by any qualifying data values that apply to the condition; then resume execution. This response is only allowed if the resume cursor has not been moved and only if the condition being handled allows this response. new_condition must be set by the condition handler to request one of the specific actions for the condition.

If result_code is not explicitly set by the handler, the default response is Value=20, Percolate to the next condition handler.

new_condition (output)

A 12-byte condition token that represents either the promoted condition for a promote response (result_code values of 30, 31, and 32) or the requested fix-up actions for a fix-up and resume response (result_code value of 60).

When a result_code of 60, denoting fix-up and resume, is set by the condition handler, new_condition must be set to a condition token that indicates what fixup action is requested. Many conditions, including mathematical routines, use the condition tokens in Table 2 to resume with corrective action (either resume with new input value or resume with new output value). For some conditions, there may be other condition tokens that can be provided by the condition handler in new_condition to request specific fixup actions.

Table 2. Designating requested fixup actions

Symbolic feedback code (fc)	Severity	Message number	Fixup action
CEE0CE	1	398	Fixup with new input value. The service that signaled the condition is invoked again with the new argument value provided by the handler as qualifying data.
CEE0CF	1	399	Fixup with new output value. The service that signaled the condition returns as its result, the value provided by the handler as qualifying data.