DISABLE PROGRAM

Terminate or otherwise modify the invocation of a user exit.

Read syntax diagramSkip visual syntax diagramDISABLE PROGRAM
 
>>-DISABLE PROGRAM(data-value)--+-----------------------+------->
                                '-ENTRYNAME(data-value)-'
 
>--+------------------+--+-----------+--+-----------+----------->
   +-EXIT(data-value)-+  '-FORMATEDF-'  '-PURGEABLE-'
   '-EXITALL----------'
 
>--+----------+--+-----+--+------+--+-----------+--------------><
   '-SHUTDOWN-'  '-SPI-'  '-STOP-'  '-TASKSTART-'
 

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:

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

For programming information about CICS exits, see the CICS® Customization Guide; you should also see the general discussion of commands that modify exits in Exit-related commands.

Note:
One or more of STOP and (EXIT or 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; for programming information, including a list of exit points, see the CICS Customization Guide.
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.Start of changeThis 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 actually 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.End of change

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 whilst 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.
X'804000'
The value of EXIT is not a valid exit point.
X'800200'
The exit identified by the PROGRAM value is not defined as an exit.
X'800100'
The exit identified by ENTRYNAME is not defined as an exit.
X'800080'
The exit is currently invoked by another task (see note).
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.
  • 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

Example 1

EXEC CICS DISABLE PROGRAM('EP2') STOP

Example 1 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.

Example 2

EXEC CICS DISABLE ENTRYNAME ('ZX') PROGRAM('EP3')
EXIT('XTDREQ')

Example 2 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.

Example 3

EXEC CICS DISABLE PROGRAM('EP3') EXITALL

Example 3 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.

[[ Contents Previous Page | Next Page Index ]]