ENABLE PROGRAM

Enable a user exit program 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)-+------------------+-+-+     
     | |                      '-GALOCATION(cvda)-' | |     
     | '-GAENTRYNAME(data-value)-------------------' |     
     +-INDOUBTWAIT ----------------------------------+     
     +-LINKEDITMODE----------------------------------+     
     +-+-QUASIRENT---------------+-------------------+     
     | +-THREADSAFE--+---------+-+                   |     
     | |             '-OPENAPI-' |                   |     
     | +-REQUIRED--+---------+---+                   |     
     | |           '-OPENAPI-'   |                   |     
     | '-OPENAPI-----------------'                   |     
     +-PURGEABLE-------------------------------------+     
     +-SHUTDOWN -------------------------------------+     
     +-SPI-------------------------------------------+     
     +-START-----------------------------------------+     
     +-TALENGTH(data-value)--------------------------+     
     '-TASKSTART-------------------------------------'

Conditions: INVEXITREQ, NOTAUTH

Description

The initial ENABLE PROGRAM command for an exit:

Defines it as an exit to the running CICS region and names it
Sets the initial status (whether it is available for running and the points at which it is called)
Allocates work areas
Loads the associated load module if required and establishes the entry point for the exit

After the initial ENABLE PROGRAM command that defines the exit, you can add or remove points at which the exit is executed, or change its availability dynamically, with ENABLE PROGRAM and DISABLE PROGRAM commands, until you disable the exit with the EXITALL option, which deletes the definition of the exit. See the description of the DISABLE PROGRAM command for the relationships between options on the two commands.

For programming information about exits, and a list of exit points, see Customizing with user exit programs. You can also read 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 program. 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 PROGRAM command that defines the exit.

If you specify LINKEDITMODE for a task-related user exit, the top bit (bit 0) of the entry address must contain the addressing mode (AMODE) indicator:

AMODE(24): bit 0 is 0 and bit 31 is 0.
AMODE(31): bit 0 is 1 and bit 31 is 0.

ENTRYNAME(data-value)

Specifies the 8-character name of the global or task-related user exit program 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 PROGRAM command that defines the exit, you must use the same combination of ENTRYNAME and PROGRAM values to identify the exit on subsequent ENABLE PROGRAM, DISABLE PROGRAM, 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.

You can name only one exit point on each ENABLE PROGRAM command. If the same exit is to be invoked from multiple exit points, you must use a separate ENABLE PROGRAM 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 PROGRAM command specifying FORMATEDF.

GAENTRYNAME(data-value)

Specifies the 8-character name of a currently enabled global or task-related user exit program whose global work area is to be shared by the exit program 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 that use 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 PROGRAM 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. Start of change

Specify the GALOCATION option to choose the location of the storage for the global work area. End of change

GALENGTH is valid only on the initial ENABLE PROGRAM command that defines the exit.

CICS does not return the address of the global work area on the ENABLE PROGRAM 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 a value of 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.

GALOCATION(cvda)

Specifies the location of the storage that CICS provides as a global work area for this exit program. You must also specify the GALENGTH option to create the global work area. CVDA values are as follows:

LOC24: The global work area is in 24-bit storage. This is the default location.
LOC31: The global work area is in 31-bit storage.

CICS does not return the address of the global work area on the ENABLE PROGRAM command. You can use an EXTRACT EXIT command to determine the address. End of change

INDOUBTWAIT (task-related user exits only)

Specifies that the task-related user exit supports the indoubt protocol.

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 PROGRAM command that defines the exit.

Avoid the use of the LINKEDITMODE option where the TRUE has been link-edited in AMODE(24). This combination forces the TRUE always to run AMODE(24), which has the following disadvantages:

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 program for TASKSTART and LINKEDITMODE causes CICS to force all transactions to run with TASKDATALOC(BELOW) if the associated load module is link-edited in 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.

For best performance, your task-related user exits should be written so that they can always run AMODE(31), should be link-edited in AMODE(31), and should be enabled with the LINKEDITMODE option.

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.

Start of change If you specify OPENAPI without REQUIRED, CICS enforces REQUIRED by default. A task-related user exit that specifies OPENAPI must be written to threadsafe standards. End of change

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 Calling an OPENAPI task-related user exit.

Note:

When a task-related user exit program is enabled REQUIRED and OPENAPI, it is treated the same as if it were enabled THREADSAFE and OPENAPI. For compatibility, an INQUIRE EXITPROGRAM command for either combination will always return THREADSAFE, OPENAPI. An INQUIRE EXITPROGRAM command will return REQUIRED, CICSAPI only for a task-related user exit program enabled REQUIRED and CICSAPI. End of change

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 that are active in the task-related user exit to be purged. The task-related user exit must be written to process the purged response from the wait correctly if this option is to be used. You can turn this option off with a DISABLE PROGRAM command specifying PURGEABLE.

QUASIRENT

Specifies that the global user exit program or task-related user exit program is quasi-reentrant, and relies on the serialization provided by CICS when accessing shared resources. The 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 user exit under the QR TCB.

A task-related user exit program is allowed to use MVS services. If it does so, it must switch to its own private TCB before issuing calls to these services, and switch back again before returning to its caller.

REQUIRED (task-related user exits only)

Specifies that the task-related user exit program is to run on an open TCB. If OPENAPI is specified, an L8 open TCB is used. If OPENAPI is not specified, any eligible key-8 open TCB can be used: L8, T8, or X8. If REQUIRED is not specified, the task-related user exit must use only the CICS API, or perform its own TCB switch to invoke non-CICS services. End of change

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 PROGRAM command specifying SHUTDOWN.

SPI (task-related user exits only)

Specifies that the task-related user exit program is to be invoked if an INQUIRE EXITPROGRAM command that names it specifies the CONNECTST option, the 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 Introduction to the task-related user exit mechanism.

START

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

When a stopped task-related user exit program 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 that 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 PROGRAM 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 local work area, or task 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 local work areas.

Start of change When you specify the LINKEDITMODE option on this command, and the task-related user exit program is link-edited in AMODE(31), the local work area is located in 31-bit storage. If you do not specify the LINKEDITMODE option, or if the task-related user exit program is link-edited in AMODE(24), the local work area is located in 24-bit storage. End of change

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 want. (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 PROGRAM command that can be executed before the recovery part of CICS initialization.

You can turn off these invocations with a DISABLE PROGRAM command specifying TASKSTART.

THREADSAFE

Specifies that the global user exit program or 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. A threadsafe program uses appropriate serialization techniques when accessing any shared resources.

A threadsafe 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. (For task-related user exits only, if OPENAPI is also specified CICS will always invoke the task-related user exit under an L8 open TCB.)

Conditions

INVEXITREQ

The INVEXITREQ condition of the ENABLE PROGRAM 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. In addition a RESP2 value of 1 is returned.
X'804000': The name specified in the EXIT option is not a valid global user exit point. In addition a RESP2 value of 2 is returned.
X'802000': The exit program is already enabled. ENTRY, LINKEDITMODE, TALENGTH, GAENTRY, GALENGTH, QUASIRENT, and THREADSAFE are valid only on the initial ENABLE command that defines the exit. In addition a RESP2 value of 3 is returned.
X'801000': The exit is already associated with the exit point specified in the EXIT option. In addition a RESP2 value of 4 is returned.
X'800800': The exit program specified in the GAENTRYNAME option is not enabled. In addition a RESP2 value of 5 is returned.
X'800400': The exit program specified in the GAENTRYNAME option does not own a work area. In addition a RESP2 value of 6 is returned.
X'800040': The length specified in the GALENGTH option exceeds the maximum allowed of 65516. In addition a RESP2 value of 10 is returned.
X'800020': The CVDA value specified for the GALOCATION option is not valid. In addition a RESP2 value of 11 is returned.

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 a global user exit program

EXEC CICS ENABLE PROGRAM('EP') ENTRYNAME('EP1')
     EXIT('XFCREQ') START

This example defines exit program 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)

This example defines an exit program named EP2, which is 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 is obtained, which is to be owned by EP2. Start of change To locate the global work area in 31-bit storage, specify the CVDA LOC31 for the GALOCATION option of the command. End of change

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 this example defines exit program EP3, which is associated with exit point XTDOUT. CICS loads module EP3 if necessary. EP3 is to use the global work area that is owned by exit program EP2. (This assumes that the ENABLE command in the previous example 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 global work area on any of those invocations.

Example: Enabling a task-related user exit program

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 program 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 program. Start of change To locate the global work area in 31-bit storage, specify the CVDA LOC31 for the GALOCATION option of the command. End of change The command also schedules the allocation of a further 750-byte local work area for each task that invokes RM1. The second command makes the exit program available for execution.

dfha8_enableprogram.html | Timestamp icon

Last updated: Thursday, 27 June 2019