USRHDLR | NOUSRHDLR

Derivation: USeR condition HanDLeR

USRHDLR registers a user condition handler at stack frame 0, allowing you to register a user condition handler without having to include a call to CEEHDLR in your application and then recompile the application.

The default value for non-CICS applications is NOUSRHDLR.

The default value for CICS® applications is NOUSRHDLR().


Syntax

   .-NOUsrhdlr-.                                     
>>-+-USrhdlr---+--(--+--------+--,--+---------+--)-------------><
                     '-lmname-'     '-lmname2-'

NOUSRHDLR: Does not register a user condition handler without recompiling an application to include a call to CEEHDLR.
USRHDLR: Registers a user condition handler without recompiling an application to include a call to CEEHDLR.
lmname: The name of a load module (or an alias name of a load module) that contains the user condition handler that is to be registered at stack frame 0. This parameter is optional.
lmname2: The name of a load module (or an alias name of a load module) that contains the user condition handler that is to be registered to get control after the enablement phase and before any other user condition handler. This parameter is optional.

CICS consideration

When specifying USRHDLR under CICS, lmname and lmname2 must be defined in the CICS system definition data set (CSD) for your CICS region, rather than using program autoinstall. This includes the sample user-written condition handler CEEWUCHA.

Usage notes

The user condition handler specified by the USRHDLR runtime option must be in a separate load module rather than be link-edited with the rest of the application.
The user condition handler lmname is invoked for conditions that are still unhandled after being presented to condition handlers for the main program.
The user condition handler lmname2 is invoked for each condition after the condition completes the enablement phase but before any other registered user condition handlers are given control.
You can use a user condition handler registered with the USRHDLR runtime option to return any of the result codes allowed for a user condition handler registered with the CEEHDLR callable service.
A condition that is percolated or promoted by a user condition handler registered to handle conditions at stack frame 0 using the USRHDLR run time option is not presented to any other user condition handler.
The loading of the user condition handlers lmname and lmname2 occurs only when that user condition handler needs to be invoked the first time.
If the load of either lmname or lmname2 fails, an error message is issued.
To turn off one of the suboptions previously specified by USRHDLR (lmname or lmname2), specify the option with either empty single quotes or empty double quotation marks. For example, to turn off the lmname2 suboption after it had been previously specified, use either USRHDLR(lmname,'') or USRHDLR(lmname,"").
In SCEESAMP, IBM® supplies a sample user-written condition handler, called CEEWUCHA. Under CICS, this handler will give you similar abend codes that existed in certain pre-Language Environment environments. The CEEWUCHA load module needs to be built using CEEWWCHA, which is also provided in SCEESAMP. This handler has support for both COBOL and PL/I; however, it is shipped with the PL/I-specific behavior commented out. If you want this PL/I behavior, modify the source before using CEEWWCHA.

For more information

For information about registering a user condition handler and its interfaces, see CEEHDLR—Register user-written condition handler.