DISABLE PROGRAM

Terminate or otherwise modify the invocation of a user exit.

DISABLE PROGRAM

Conditions: INVEXITREQ, NOTAUTH

Description

The DISABLE PROGRAM command changes the status of a global or task-related user exit, reversing the effects of corresponding options in an ENABLE PROGRAM command.

You use it to:

Remove points at which a particular exit is invoked
Make the exit unavailable for execution (without removing its status as an exit)
Delete its definition as an exit entirely.

Options on the DISABLE PROGRAM command correspond to those on the ENABLE command:

ENTRYNAME and PROGRAM identify the exit to be disabled, and you must use exactly the same combination of values that you did in the ENABLE command that defined the exit.
EXIT, FORMATEDF, SHUTDOWN, and TASKSTART reverse the effect of the same-named options on ENABLE PROGRAM; that is, they turn off invocation of the exit at the points specified.
STOP reverses the effect of START, making the exit unavailable for execution.
EXITALL deletes the definition entirely, reversing the effect of the ENABLE PROGRAM that created the exit. Work areas and the load module associated with the exit may be deleted as well.

For programming information about CICS exits, see Global user exit programs and Task-related user exit programs; you should also see the general discussion of commands that modify exits in Exit-related commands.

Note: One or more of STOP, EXIT, and EXITALL is required for a global user exit, and one or more of STOP, EXITALL, TASKSTART, SHUTDOWN, and FORMATEDF is required for a task-related user exit.

Options

ENTRYNAME(data-value)

Specifies the name of the global or task-related user exit whose status is to be changed. If you omit ENTRYNAME, CICS assumes that the name of the exit is the same as the load module name given in the PROGRAM option. Therefore, you must use the same combination of ENTRYNAME and PROGRAM values on DISABLE commands as was specified on the initial ENABLE command that defined the exit.

EXIT(data-value) (global user exits only)

Specifies the name of the global user exit point from which this exit program is to be dissociated. It causes CICS to stop invoking the exit at this point but does not, of itself, cause CICS to delete the associated load module from virtual storage, even if it is no longer being used at any exit points. Exit point names are eight characters long.

EXITALL

Causes CICS to discard the definition of the exit. For a global user exit, EXITALL dissociates the exit from all of the exit points from which it currently is invoked. If possible, the associated load module is deleted from virtual storage.

For a task-related user exit, the associated load module is deleted from virtual storage if it is not in use by another exit and if the ENTRY option was not specified in the ENABLE command that defined the exit. If the exit owns a global work area, the work area is released as soon as no other exits are sharing it.

EXITALL implies STOP, so the exit becomes unavailable for execution. For a task-related user exit, you must avoid requesting this function until all tasks that have used the exit have ended; the results of EXITALL before that point are unpredictable. This means that for start-of-task, end-of-task and shutdown calls, when all task related user exits would be called and a DISABLE EXITALL command is issued from the current TRUE for itself then the number of TRUEs called is unpredictable. If the need arises for the exit to be refreshed then the TRUE should disable itself using the STOP option and invoke a separate task to issue the DISABLE with the EXITALL option.

FORMATEDF (task-related user exits only)

Indicates that the exit should not be invoked to format EDF screens. You can reinstate invocation at EDF points with an ENABLE command specifying FORMATEDF.

PROGRAM(data-value)

Specifies the 8-character name of the load module that contains the entry point for the exit. This name is also used as the name of the exit when ENTRYNAME is not specified; see the ENTRYNAME option.

PURGEABLE (task-related user exits only)

Removes the ability to be purged from CICS waits while active in the task-related user exit. You can turn this on with an ENABLE command specifying PURGEABLE.

SHUTDOWN (task-related user exits only)

Indicates that the exit should not be invoked at CICS shutdown. You can reinstate invocation at shutdown with an ENABLE command specifying SHUTDOWN.

SPI (task-related user exits only)

Specifies that the task-related user exit is no longer to be invoked if an INQUIRE EXITPROGRAM command specifies the CONNECTST or QUALIFIER option, or both.

STOP

Specifies that the exit is to be made unavailable for execution, but is to remain enabled (defined as an exit). You can make the exit available for execution again with an ENABLE command specifying 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).

TASKSTART (task-related user exits only)

Indicates that the exit should not be invoked at the start and end of each task. You can reinstate these invocations with an ENABLE command specifying TASKSTART.

Conditions

INVEXITREQ

The INVEXITREQ condition of the DISABLE 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, which can have the values shown in the following list.

X'808000': The load module named on the PROGRAM parameter has not been defined to CICS, or the load module is not in the load library, or the load module has been disabled. In addition a RESP2 value of 1 is returned.
X'804000': The value of EXIT is not a valid exit point. In addition a RESP2 value of 2 is returned.
X'800200': The exit identified by the PROGRAM value is not defined as an exit. In addition a RESP2 value of 7 is returned.
X'800100': The exit identified by ENTRYNAME is not defined as an exit. In addition a RESP2 value of 8 is returned.
X'800080': The exit is currently invoked by another task (see note). In addition a RESP2 value of 9 is returned.

Note: The INVEXITREQ condition with X'0080' in the second and third bytes can occur:

If you issue the DISABLE request while a task using the exit has been suspended temporarily because of a request for a CICS service within the exit. The normal action for this condition is to retry the DISABLE request.
If you issue the DISABLE request while another task is using the exit but running under a different task control block (TCB). The normal action for this condition is to retry the DISABLE request.
When a DISABLE request with EXITALL or EXIT has been specified, but the exit has already terminated abnormally. In this case, the use count of the associated load module remains greater than zero. The exit cannot be dissociated from any exit point, and the load module cannot be deleted from virtual storage. The exit can, however, be made unavailable for execution by issuing a DISABLE STOP command.

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

The following example makes exit EP2 non-executable. It does not dissociate it from the exit points with which it is associated, however, or delete its definition as an exit. It can be made available again by issuing an ENABLE PROGRAM('EP2') START command.
```
EXEC CICS DISABLE PROGRAM('EP2') STOP
```
The following example stops global user exit ZX from being invoked at exit point XTDREQ. ZX is still defined, however, and if it is associated with other exit points, it is still invoked at them.
```
EXEC CICS DISABLE ENTRYNAME ('ZX') PROGRAM('EP3')
EXIT('XTDREQ')
```
The following example dissociates EP3 from all points at which invocation was requested (exit points, in the case of a global user exit; task start, shutdown, and so on, in the case of a task-related user exit), and discards the definition of the exit. If the load module EP3 is not in use, it is deleted.
```
EXEC CICS DISABLE PROGRAM('EP3') EXITALL
```