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.