Enable a user exit to allow it to be invoked.
ENABLE PROGRAM >>-ENABLE PROGRAM(data-value)-----------------------------------> .---------------------------------. V | >----+-----------------------------+-+------------------------->< +-ENTRY(ptr-ref)--------------+ +-ENTRYNAME(data-value)-------+ +-EXIT(data-value)------------+ +-FORMATEDF-------------------+ +-+-GALENGTH(data-value)----+-+ | '-GAENTRYNAME(data-value)-' | +-INDOUBTWAIT-----------------+ +-LINKEDITMODE----------------+ +-+-QUASIRENT---------------+-+ | +-THREADSAFE--+---------+-+ | | | '-OPENAPI-' | | | '-OPENAPI-----------------' | +-PURGEABLE-------------------+ +-SHUTDOWN--------------------+ +-SPI-------------------------+ +-START-----------------------+ +-TALENGTH(data-value)--------+ '-TASKSTART-------------------'
Conditions: INVEXITREQ, NOTAUTH
The initial ENABLE PROGRAM command for an exit:
After the initial ENABLE command that defines the exit, you can add or remove points at which the exit is executed or change its availability dynamically with ENABLE and DISABLE commands, until you disable with the EXITALL option, which deletes the definition of the exit. See the description of that command on page DISABLE PROGRAM for the correspondence between options on the two commands.
For programming information about exits in CICS, see the CICS® Customization Guide; you should also see the general discussion of commands that modify exits in Exit-related commands.
The use of the ENTRY option means that the module named in the PROGRAM option has already been loaded or is permanently resident. CICS does not attempt to load the module, and also does not delete it when the user exit is disabled with EXITALL. If you omit ENTRY, CICS uses the first entry point in the load module and manages loading and deletion for you.
ENTRY is valid only on the initial ENABLE command that defines the exit.
If you specify LINKEDITMODE for a task-related user exit, the top bit of the entry address must contain the addressing mode (AMODE) indicator. The top bit is set if the exit is AMODE=31 and is zero if AMODE=24.
If you omit ENTRYNAME, the name of the exit defaults to the name of the load module specified in the PROGRAM option.
After the initial ENABLE command that defines the exit, you must use the same combination of ENTRYNAME and PROGRAM values to identify the exit on subsequent ENABLE, DISABLE, and EXTRACT EXIT commands.
You can name only one exit point on each ENABLE command. If the same exit is to be invoked from multiple exit points, you need a separate ENABLE command for each point.
It must own the work area (that is, GALENGTH must have been specified when it was originally enabled). CICS does not release a work area until all of the exits using it are disabled with EXITALL (no longer defined), but the owning exit must still be enabled for a new exit to share its work area.
GALENGTH and GAENTRYNAME are mutually exclusive and must be specified on the initial ENABLE command that defines the exit. If neither option is supplied, no global work area is provided.
GALENGTH is valid only on the initial ENABLE command that defines the exit.
CICS does not return the address of the work area on the ENABLE command; you can use an EXTRACT EXIT command to determine it.
You should avoid using LINKEDITMODE to force a task-related user exit to run in AMODE(24) because:
If you specify OPENAPI without THREADSAFE, CICS enforces THREADSAFE by default. A task-related user exit that specifies OPENAPI must be written to threadsafe standards.
If OPENAPI is omitted, CICS assumes that the task-related user exit is either using only the CICS API, or that it performs its own TCB switch to invoke non-CICS services.
For the rules that determine which calls to a task-related user exit cause the exit to be invoked on an L8 mode TCB or the QR TCB, and for other associated information, see the CICS Customization Guide.
If you omit the ENTRYNAME option, CICS assumes that the name of the exit is the same as that of the load module.
The task-related user exit program is invoked with an SPI call, allowing it to return CONNECTST and QUALIFIER information to the inquiring program. For details of RMI SPI calls, see the CICS Customization Guide.
When a STOPped task-related user exit gets invoked, the invoking code gets an AEY9 abend code. There is no corresponding error for global user exits, however, because CICS invokes only those exits associated with an exit point which are also available for execution (not stopped).
When a single global user exit is to be associated with several exit points, the START option allows you to delay execution of the exit until all the required ENABLE commands have been issued. You can, however, associate more exit points with the exit after it has been started.
The TASKSTART option is independent of the START option, but you should turn on START before or at the same time as TASKSTART, to avoid invoking the exit when it is not available for execution. In addition, you must not code the TASKSTART option on any ENABLE command that can be executed before the recovery part of CICS initialization.
You can turn off these invocations with a DISABLE command specifying TASKSTART.
A threadsafe task-related user exit program must be able to run under whichever TCB CICS invokes it. This could be either the QR TCB or an open TCB. (If OPENAPI is also specified, and when it is enabled, CICS will always invoke the task-related user exit under an L8 open TCB.)
EXEC CICS ENABLE PROGRAM('EP') ENTRYNAME('EP1')
EXIT('XFCREQ') START
Example 1 defines exit EP1, tells CICS that EP1 is to be invoked from exit point XFCREQ, and makes EP1 available for execution. No global work area is obtained. CICS loads the EP module if necessary.
EXEC CICS ENABLE PROGRAM('EP2') EXIT('XMNOUT')
START ENTRY(EADDR) GALENGTH(500)
Example 2 defines an exit named EP2 (named by default from its load module). This module is already loaded, and the entry point for the exit is in EADDR. The exit is to be executed at exit point XMNOUT, and it is available for execution. A global work area of 500 bytes, which is to be owned by EP2, is obtained.
EXEC CICS ENABLE PROGRAM('EP3') EXIT('XTDOUT')
GAENTRYNAME('EP2')
EXEC CICS ENABLE PROGRAM('EP3') EXIT('XTDIN')
EXEC CICS ENABLE PROGRAM('EP3') EXIT('XTDREQ') START
The first command of Example 3 defines exit EP3; it is associated with exit point XTDOUT. CICS loads module EP3 if necessary. EP3 is to use the work area that is owned by exit EP2. (This assumes that the ENABLE command in Example 2 has already been issued.)
The second command says that EP3 is also associated with exit point XTDIN. The third command says that EP3 is associated with exit point XTDREQ, and makes the exit available for execution. EP3 is now invoked from all of these exit points, and it can use EP2’s work area on any of those invocations.
EXEC CICS ENABLE PROGRAM('EP9')
TALENGTH(750) ENTRYNAME('RM1') GALENGTH(200)
EXEC CICS ENABLE PROGRAM('EP9')
ENTRYNAME('RM1') START
The first command defines the task-related user exit RM1, loads EP9 (the load module executed initially) if it is not already resident, and allocates a 200-byte global work area to the exit. It also schedules the allocation of a further 750-byte work area for each task that invokes RM1. The second command makes the exit available for execution.