ENABLE PROGRAM

Enable a user exit program to allow it to be invoked.

Syntax

Warning: System commands are powerful as they provide information about the state of the system and allow changes to be made to it. System commands should be used only by authorized applications and users.

Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).

ENABLE PROGRAM

Read syntax diagramSkip visual syntax diagramENABLE PROGRAM( data-value)ENTRY( ptr-ref)ENTRYNAME( data-value)EXIT( data-value)FORMATEDFGALENGTH( data-value)GALOCATION( cvda)GAEXECUTABLEGAENTRYNAME( data-value)INDOUBTWAIT LINKEDITMODEQUASIRENTTHREADSAFEOPENAPIREQUIREDOPENAPIOPENAPIPURGEABLESHUTDOWN SPISTARTTALENGTH( data-value)TAEXECUTABLETASKSTART

Conditions: INVEXITREQ, NOTAUTH

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations.

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 DISABLE PROGRAM command for the relationships between options on the two commands.

For 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 that you specify must be within the virtual storage range that is occupied by the load module that is named in the PROGRAM option.

The use of the ENTRY option means that the module that is named in the PROGRAM option is already 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 using 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 is 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 extra points (within EDF), when the exit is invoked by a task that is running under EDF. The additional invocations allow the exit to format EDF displays and interpret changes that are made by the user to fields on the EDF screen. You can turn off EDF invocations with a DISABLE PROGRAM command that specifies 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 name is the name that is 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.

GAEXECUTABLE
Specifies that the global work area is to be allocated from one of the DSAs that is never protected from instruction execution. See CICS dynamic storage areas (DSAs).
Specify this option only if GALENGTH is also specified.
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 - 32767. The work area is initialized to binary zeros.

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 by 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.
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 is 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, write your task-related user exits so that they can always run AMODE(31), link-edit them in AMODE(31), and enable them with the LINKEDITMODE option.
OPENAPI (task-related user exits only)
Specifies that the task-related user exit program is using non-CICSCICS 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 REQUIRED, CICS enforces REQUIRED by default. A task-related user exit that specifies OPENAPI must be written to threadsafe standards.

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 always returns THREADSAFE, OPENAPI. An INQUIRE EXITPROGRAM command returns REQUIRED, CICSAPI only for a task-related user exit program enabled REQUIRED and CICSAPI.
PROGRAM(data-value)
Specifies the 8-character name of the load module that contains 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 the name of the load module.

PURGEABLE (task-related user exits only)
Allows tasks that enter 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 off this option 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 that is 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 it returns 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.
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 that specifies 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 (the adapter).

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. However, there is no corresponding error for global user exits 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 are issued. However, you can associate more exit points with the exit after it is started.

TAEXECUTABLE
Specifies that the local work area, or task work area, is to be allocated from one of the DSAs that is never protected from instruction execution. See CICS dynamic storage areas (DSAs).
Specify this option only if TALENGTH is also specified.
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 - 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.

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.

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 accounts for the possibility that, when accessing shared resources, other programs can 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 TCB can be either the QR TCB or an open TCB. (For task-related user exits only, if OPENAPI is also specified CICS always invokes 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 that is named in the PROGRAM option is not defined to CICS and cannot be autoinstalled, or is not in the load library, or is disabled, or is defined as remote, or does not contain the address that is specified in the ENTRY option. In addition, a RESP2 value of 1 is returned.
X'804000'
The name that is 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 that is specified in the EXIT option. In addition, a RESP2 value of 4 is returned.
X'800800'
The exit program that is specified in the GAENTRYNAME option is not enabled. In addition, a RESP2 value of 5 is returned.
X'800400'
The exit program that is specified in the GAENTRYNAME option does not own a work area. In addition, a RESP2 value of 6 is returned.
X'800040'
The length that is specified in the GALENGTH option exceeds the maximum that is allowed of 65516. In addition a RESP2 value of 10 is returned.
X'800020'
The CVDA value that is specified for the GALOCATION option is not valid. In addition, a RESP2 value of 11 is returned.
NOTAUTH
RESP2 values:
100
The user who is associated with the issuing task is not authorized to use this command.
101
The user who is 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

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('EP') ENTRYNAME('EP1')
     EXIT('XFCREQ') START
This example defines an exit program that is 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. To locate the global work area in 31-bit storage, specify the CVDA LOC31 for the GALOCATION option of the command:
EXEC CICS ENABLE PROGRAM('EP2') EXIT('XMNOUT')
     START ENTRY(EADDR) GALENGTH(500)
To allocate the global work area from one of the DSAs that are never protected from instruction execution, specify GAEXECUTABLE:
EXEC CICS ENABLE PROGRAM('EP2') EXIT('XMNOUT')
START ENTRY(EADDR) GALENGTH(500) GAEXECUTABLE
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 is already 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:
EXEC CICS ENABLE PROGRAM('EP3') EXIT('XTDOUT')
     GAENTRYNAME('EP2')
EXEC CICS ENABLE PROGRAM('EP3') EXIT('XTDIN')
EXEC CICS ENABLE PROGRAM('EP3') EXIT('XTDREQ') START

Example: Enabling a task-related user exit program

The first command defines the task-related user exit program RM1, loads EP9 (the load module that is executed initially) if it is not already resident, and allocates a 200-byte global work area to the exit program. To locate the global work area in 31-bit storage, specify the CVDA LOC31 for the GALOCATION option of the command. 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:
EXEC CICS ENABLE PROGRAM('EP9')
     TALENGTH(750) ENTRYNAME('RM1') GALENGTH(200)
 
EXEC CICS ENABLE PROGRAM('EP9')
     ENTRYNAME('RM1') START