Register a User-Written Condition Handler (CEEHDLR) API

The Register a User-Written Condition Handler (CEEHDLR) API registers a user-written condition handler for the current call stack entry.

Required Parameter Group

procedure (input)

An entry variable or constant for the procedure that is to be called to process the conditions.

token (input)

A pointer passed to the user-written condition handler at the time the procedure is called.

Omissible Parameter

fc (output)

A 12-byte feedback code.

Feedback Codes and Conditions

Usage Notes

• CEEHDLR is implemented as a builtin and therefore cannot have its address taken or be called through a procedure pointer.

• A queue of handlers is maintained for each call stack entry. The handlers are given control in LIFO order. That is, the handler most recently registered is the first one used for the call stack entry from which the call to CEEHDLR was made.

• Any registered user-written condition handlers that were not unregistered by the Unregister a User-Written Condition Handler (CEEHDLU) API, are unregistered automatically by ILE upon removal of the associated call stack entry from the call stack. For more information on unregistering user-written condition handlers, see Unregister a User-Written Condition Handler (CEEHDLU) API.

• The message CEE0257 occurs if the pointer contained in procedure is not a procedure pointer.

ILE Condition Handler Interface

Following is a description of the interface that the system uses to communicate with ILE condition handlers.

Authorities and Locks

None.

Required Parameter Group

C_CTOK (input)

Identifies the current condition being processed.

token (input)

The token that was passed to the system with the call to CEEHDLR that registered this condition handler.

result_code (output)

This field contains the instructions from the condition handler to the system regarding the actions that the system should take.

ILE condition handlers get control for all *ESCAPE, *STATUS, *NOTIFY, and function check messages. Not all result code actions are valid for all types of messages.

If the message is handled by the ILE condition handler, the result-code action is not performed.

If a result code is returned that is not valid, the following message occurs:

CEE0265	The result code received from a condition handler is not valid
Severity:30

Valid result codes are:

Resume

This result code can be used for all exception types.

10

Resume at the resume cursor, and handle the condition, as follows: Function Check (severity 4) The message appears in the job log. *ESCAPE (severity 2-4) The message appears in the job log. *STATUS (severity 1) The message does not appear in the job log. *NOTIFY The default reply is sent and the message appears in the job log.

Percolate

These result codes can be used for all exception types.

20

Percolate to the next condition handler.

21

Percolate to the next call stack entry. This can skip a high-level language condition handler for this call stack entry. Any remaining user handlers in the queue for this call stack entry also can be skipped. This handle cursor movement is in addition to any other handle cursor movement done explicitly in the handler, for example by the CEEMRCR API. The handle cursor is not moved past a call stack entry for a control boundary. The default condition handling actions are applied to the message. Default Responses to Unhandled Exceptions summarizes the default condition handling actions.

Promote

Only *ESCAPE and *STATUS messages may be promoted.

30	Promote to the next condition handler.
31	Promote to the next call stack entry. This may skip a high-level language condition handler for this call stack entry. Any remaining user handlers in the queue for this call stack entry also can be skipped. This handle cursor movement is in addition to any other handle cursor movement done explicitly in the handler, for example by the CEEMRCR API. The handle cursor is not moved past a call stack entry for a control boundary. The default condition handling actions are applied to the new message. Default Responses to Unhandled Exceptions summarizes the default condition handling actions.
32	Promote and restart condition handling with the first condition handler for the call stack entry at which the handle cursor currently points.

Note: It is not valid to promote a condition without returning a new condition token. If the original condition is returned in new_condition, the following message occurs:

CEE0262	The condition being promoted is not valid
Severity:30

new_condition (output)

The condition token representing the promoted condition. This field is used only for result_code values of 30, 31, and 32 denoting promote or fix-up and resume.