ENABLE PROGRAM

Enable a user exit to allow it to be invoked.

Read syntax diagramSkip visual syntax diagramENABLE 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

Description

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.

Options

ENTRY(ptr-ref)
specifies a pointer reference that contains the entry point address of the global or task-related user exit. The address you specify must be within the virtual storage range occupied by the load module named in the PROGRAM option.

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.

ENTRYNAME(data-value)
specifies the 8-character name of the global or task-related user exit that is to be enabled. This name must be different from the name of any exit already established. It does not have to be defined to CICS other than by means of this command, and it need not be the name of a load module or an entry point to a load module.

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.

EXIT(data-value) (global user exits only)
specifies the 8-character name of a global user exit point with which this exit is to be associated. When an exit is "associated" with an exit point, it is invoked when CICS reaches that particular point in its management code, provided the exit has been "started" (made available for execution). Exit points are defined and named by CICS. For programming information about exits, and a list of exit points, see the CICS Customization Guide.

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.

FORMATEDF (task-related user exits only)
specifies that the exit is to be invoked at additional points (within EDF), when the exit is invoked by a task running under EDF. The additional invocations allow the exit to format EDF displays and interpret changes made by the user to fields on the EDF screen. You can turn off EDF invocations with a DISABLE command specifying FORMATEDF.
GAENTRYNAME(data-value)
specifies the 8-character name of a currently enabled global or task-related user exit whose global work area is to be shared by the exit being enabled. This is the name assigned to that exit when it was defined (its ENTRYNAME if one was used or its load module name from the PROGRAM option if not).

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(data-value)
specifies, as a halfword binary value, the length in bytes of the global work area that is to be provided by CICS for this exit. Valid lengths are 1 through 32767. The work area is initialized to binary zeros.

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.

Note:
Although the maximum GALENGTH that you can specify using this command at the terminal is 32767, there is no limit to the value you can request for GALENGTH if one of your programs issues the command. However, if more than 65535 is requested in this way, the request is truncated to the low order halfword of the requested amount. After any required truncation, if the value (which cannot now exceed 65535), exceeds 65516, an error response is issued for the INVEXITREQ condition.
INDOUBTWAIT (task-related user exits only)
specifies that the task-related user exit supports the in-doubt protocol. For information about the in-doubt protocol, see the CICS Customization Guide.
LINKEDITMODE (task-related user exits only)
specifies that the exit should be invoked in the addressing mode in which it was link-edited. If you do not specify LINKEDITMODE, it is invoked in the addressing mode of the caller. LINKEDITMODE is valid only on the initial ENABLE command that defines the exit.

You should avoid using LINKEDITMODE to force a task-related user exit to run in AMODE(24) because:

  • An exit link-edited in AMODE(24) cannot be invoked from a task running with TASKDATALOC(ANY). If you attempt to do this, the task abends with CICS abend code AEZB.
  • Enabling an exit for TASKSTART and LINKEDITMODE causes CICS to force all transactions to run with TASKDATALOC(BELOW) if the associated load module is link edited for AMODE(24).
  • For a CICS shutdown call, CICS ignores the LINKEDITMODE attribute and invokes the exit in the addressing mode of the task that performs this shutdown function. For some types of shutdown, the addressing mode of this task is not predefined.
OPENAPI (task-related user exits only)
specifies that the task-related user exit program is using non-CICS APIs. If the user application program that invokes the task-related user exit is defined as quasi-reentrant, CICS switches the user task to an L8 mode open TCB before passing control to the task-related user exit program. CICS assumes that a task-related user exit enabled with OPENAPI does not manage its own private pool of TCBs for non-CICS services, and can perform its processing on the L8 mode TCB.

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.

Note:
You do not explicitly enable the DB2 task-related user exit, because this is done automatically for you when you start the CICS DB2 adapter. If you are connected to DB2 Version 6 or later, the exit is enabled with OPENAPI and the adapter uses L8 mode TCBs provided by CICS. The number of open TCBs permitted for this purpose is controlled by the MAXOPENTCBS system initialization parameter (see the CICS System Definition Guide).

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.

PROGRAM(data-value)
specifies the 8-character name of the load module containing the entry point of the exit. CICS uses the PROGRAM resource definition of this name to load the program, if necessary, and to verify that it is enabled and resides on the same CICS system as the exit. If no such definition exists, CICS attempts to build one dynamically if the system is defined to allow autoinstall of programs.

If you omit the ENTRYNAME option, CICS assumes that the name of the exit is the same as that of the load module.

PURGEABLE (task-related user exits only)
allows tasks that have entered a CICS wait state and are active in the task-related user exit, to be purged. The task-related user exit must be written to correctly process the purged response from the wait if this option is to be used. You can turn this off with a DISABLE command specifying PURGEABLE.
QUASIRENT (task-related user exits only)
specifies that the task-related user exit program is quasi-reentrant, and relies on the serialization provided by CICS when accessing shared resources. The task-related user exit program is restricted to the CICS permitted programming interfaces, and must comply with CICS quasi-reentrancy rules. CICS always invokes a quasi-reentrant task-related user exit under the QR TCB. If the task-related user exit program uses MVS services, it must switch to its own private TCB before issuing calls to these services, and switch back again before returning to its caller.
SHUTDOWN (task-related user exits only)
specifies that the exit is to be invoked during CICS shutdown processing. You can turn off the invocation with a DISABLE command specifying SHUTDOWN.
SPI (task-related user exits only)
specifies that the task-related user exit is to be invoked if an INQUIRE EXITPROGRAM command which names it specifies the CONNECTST or QUALIFIER option, or both.

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.

START
indicates that the exit is available for execution. You can turn availability on and off with ENABLE commands (specifying START) and DISABLE commands (specifying STOP), but the exit starts out in stopped mode and is not available until the first ENABLE with START.

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.

TALENGTH(data-value) (task-related user exits only)
specifies, as a halfword binary value, the length in bytes of the work area that CICS provides for each task that uses the exit. Valid lengths are 1 through 32767. CICS allocates the work area and initializes it to binary zeros before the first use of the exit by the task, and releases it at task end. If you do not specify TALENGTH, CICS does not create task work areas.
TASKSTART (task-related user exits only)
specifies that the exit is to be invoked at the start of every task. The exit is also invoked at end of task, but you can turn off this invocation within the exit if you wish. (The task that logs off an autoinstalled terminal in an MRO environment is an exception; it does not invoke the exit.)

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.

THREADSAFE (task-related user exits only)
specifies that the task-related user exit program is written to threadsafe standards, and takes into account the possibility that, when accessing shared resources, other programs may be executing concurrently and attempting to modify the same resources. It uses appropriate serialization techniques when accessing any shared resources.

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.)

Conditions

INVEXITREQ
The INVEXITREQ condition of the ENABLE command is indicated by X'80' in the first byte of EIBRCODE. The exact cause of the error can be determined by examining the second and third bytes of EIBRCODE.
X'808000'
The load module named in the PROGRAM option has not been defined to CICS and could not be autoinstalled, or is not in the load library, or has been disabled, or is defined as remote, or does not contain the address specified in the ENTRY option.
X'804000'
The name specified in the EXIT option is not a valid global user exit point.
X'802000'
The exit is already enabled. ENTRY, LINKEDITMODE, TALENGTH, GALENGTH and GAENTRY are valid only on the initial ENABLE command that defines the exit.
X'801000'
The exit is already associated with the exit point specified in the EXIT option.
X'800800'
The exit specified in the GAENTRYNAME option is not enabled.
X'800400'
The exit specified in the GAENTRYNAME option does not own a work area.
X'800040'
The length specified in GALENGTH option exceeds the maximum allowed of 65516.
NOTAUTH
RESP2 values:
100
The user associated with the issuing task is not authorized to use this command.
101
The user associated with the issuing task is not authorized to access this particular resource in the way required by this command.

Examples

Enabling global user exits

Example 1

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.

Example 2

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.

Example 3

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.

Enabling task-related user exits

Example

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.

[[ Contents Previous Page | Next Page Index ]]