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.

Non-CICS default

NOUSRHDLR=((),OVR)

CICS® default

NOUSRHDLR=((),OVR)

Syntax

   .-NOUSRHDLR-.                                              
>>-+-USRHDLR---+--=--(--(--+--------+--,--+---------+--)--,----->
                           '-lmname-'     '-lmname2-'         

   .-OVR----.      
>--+-NONOVR-+--)-----------------------------------------------><

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.

OVR

Specifies that the option can be overridden.

NONOVR

Specifies that the option cannot be overridden.

CICS considerations

When specifying USRHDLR under CICS, lmname and lmname2 must be defined in the CICS PPT.

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 runtime 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 quotation marks 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,"").
• IBM® supplies a sample user-written condition handler found in SCEESAMP called CEEWUCHA. Under CICS, this handler will give you similar abend codes that were around in certain pre-Language Environment environments. The CEEWUCHA load module needs to be built using CEEWWCHA provided in SCEESAMP. Be aware that this handler has support for both COBOL and PL/I and 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 the CEEHDLR callable service in z/OS Language Environment Programming Reference.