INQUIRE EXITPROGRAM

Retrieve information about a user exit.

INQUIRE EXITPROGRAM

Read syntax diagramSkip visual syntax diagramINQUIRE EXITPROGRAM( data-value)EXIT( data-value)ENTRYNAME( data-area)APIST( cvda)CONCURRENTST( cvda)CONNECTST( cvda)ENTRY( ptr-ref)FORMATEDFST( cvda)GAENTRYNAME( data-area)GALENGTH( data-area)GAUSECOUNT( data-area) INDOUBTST( cvda)NUMEXITS( data-area)PURGEABLEST( cvda)QUALIFIER( data-area)SHUTDOWNST( cvda)SPIST( cvda)STARTSTATUS( cvda)TALENGTH( data-area)TASKSTARTST( cvda)USECOUNT( data-area)

Conditions: END, ILLOGIC, INVREQ, NOTAUTH, PGMIDERR

This command is threadsafe.

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

The INQUIRE EXITPROGRAM command returns information about a global or task-related user exit. You identify the exit about which you are inquiring with the ENTRYNAME and EXITPROGRAM options.

Browsing

You can also browse through the exit definitions in two different ways. To look at all of the global user exits defined at a particular exit point, you specify the exit point on the command that starts the browse, thus:
INQUIRE EXITPROGRAM EXIT(data-value) START

To look at all user exits, both global and task-related, you omit the EXIT option on the command that starts the browse. You can distinguish between the two types by looking at the NUMEXITS value, which is zero for a task-related exit and positive for a global exit.

On either type of browse, the sequence in which the exits are retrieved is the time order in which they were enabled.

Options

APIST
returns a CVDA indicating which APIs the user exit program uses.
CVDA values are:
BASEAPI
CICSAPI has replaced BASEAPI. Both these CVDA values have the same meaning, and, for compatibility, BASEAPI is still accepted by the translator.
CICSAPI
The user exit program is enabled without the OPENAPI option. This means it is restricted to the CICS permitted programming interfaces. In releases before CICS TS for z/OS®, Version 3, this CVDA was called BASEAPI.
OPENAPI
The task-related user exit program is enabled with the OPENAPI option. This means it is permitted to use non-CICS API, for which purpose CICS will give control to the task-related user exit under an L8 mode open TCB. OPENAPI assumes that the program is written to threadsafe standards.
CONCURRENTST
returns a CVDA indicating the concurrency status of the global or task-related user exit program. This is the value of the CONCURRENCY attribute of the PROGRAM definition, or of any override specified by the latest ENABLE command for this program.

CVDA values are:

QUASIRENT
The exit program is defined as being quasi-reentrant, and is able to run only under the CICS QR TCB when invoking CICS services through the CICS API. To use any MVS™ services, a task-related user exit program must switch to a privately-managed TCB.
THREADSAFE
The exit program is defined as threadsafe, and is capable of running on an open TCB.

For task-related user exit programs only, if the APIST option returns OPENAPI the program will always be invoked under an open TCB.

For both global and task-related user exit programs, an APIST option of CICSAPI means that the program is invoked under whichever TCB is in use by its user task when the program is given control. This could be either an open TCB or the CICS QR TCB.

REQUIRED (task-related user exits only)
The exit program is always run on an open TCB. If OPENAPI is specified, an L8 open TCB is used. If OPENAPI is not specified, then any eligible key 8 open TCB is used, L8, T8, or X8.
Note: When a task-related user exit 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. For a task-related user exit enabled REQUIRED and CICSAPI, INQUIRE EXITPROGRAM will return REQUIRED, CICSAPI.
CONNECTST(cvda) (task-related user exits only)
returns a CVDA value indicating the state of the connection between the exit and the external resource manager that it supports. CONNECTST enables you to determine whether the specified exit has connected to its resource manager, so that CICS tasks can safely issue API requests to the resource manager.

For example, to inquire about the connection to DBCTL, use an EXITPROGRAM value of DFHDBAT and an ENTRYNAME value of DBCTL. To inquire about the connection to DB2®, use an EXITPROGRAM value of DFHD2EX1, or DSN2EXT1 (DSN2EXT1 is still recognised for compatibility with earlier releases) , with an ENTRYNAME of DSNCSQL, or DSNCCMD.

CVDA values are:
CONNECTED
The task-related user exit is connected to its external resource manager subsystem, and API requests can be issued.
NOTAPPLIC
The exit is not a task-related user exit.
NOTCONNECTED
The task-related user exit is not connected to its external resource manager subsystem, and therefore API requests cannot be issued.
UNKNOWN
The task-related user exit has been enabled and started, but not enabled for SPI requests. UNKNOWN can also be returned if CICS is unable to call the task-related user exit. In both of these cases, CICS cannot tell whether it is connected to its external resource manager.

UNKNOWN is returned for all subsequent calls for the remaining lifetime of the task. A new task is able to call the task-related user exit and get the required information.

If the task-related user exit is not enabled, the INQUIRE command returns PGMIDERR. This also indicates that CICS is not connected to the resource manager.

Note: To determine whether DB2 or DBCTL is available, use CONNECTST rather than STARTSTATUS, because the task-related user exit can be started without having succeeded in making its database manager available to CICS.
ENTRY(ptr-ref)
returns a fullword binary field indicating the entry address of the user exit.
ENTRYNAME(data-area)
specifies the 8-character name of the exit about which you are inquiring. If you omit ENTRYNAME, CICS assumes that the name of the exit is the same as the name of the load module specified in the EXITPROGRAM option. Consequently, you must specify the same values for ENTRYNAME and EXITPROGRAM as were specified in the ENTRYNAME and PROGRAM options on the ENABLE command that created the exit. (EXITPROGRAM in this command corresponds to PROGRAM in an ENABLE command.)
EXIT(data-value) (global user exits only)
specifies the 8-character identifier of an exit point with which the exit about which you are inquiring is associated. You must specify an exit point when you inquire about a global user exit. Exit points do not apply to task-related user exits, however, and you must not specify this option when you inquire about such an exit.
EXITPROGRAM(data-value)
specifies the 8-character name of the load module associated with the exit about which you want information. This is the value that was specified in the PROGRAM option of the ENABLE command that defined the exit.
FORMATEDFST(cvda) (task-related user exits only)
returns a CVDA value indicating that the FORMATEDF option is enabled for the exit. FORMATEDF causes extra invocations of the exit for tasks executed under EDF, to format output screens and interpret input, and applies only to task-related user exits. CVDA values are:
FORMATEDF
FORMATEDF is turned on.
NOFORMATEDF
FORMATEDF processing is turned off.
NOTAPPLIC
This is a global user exit.
GAENTRYNAME(data-area)
returns the 8-character name of the user exit that owns the global work area used by the exit about which you are inquiring.

This value is returned only when the exit uses a global work area owned by another exit. Blanks are returned if it has allocated its own work area.

GALENGTH(data-area)
returns a halfword binary field indicating the length of the global work area for the exit.
Note: If a GALENGTH greater than 32767 has been defined (see GALENGTH for ENABLE PROGRAM for details), the response to this command reflects that higher value as follows:
  • If you issued the INQUIRE EXITPROGRAM command at your terminal, the response shows a negative value for GALENGTH.
  • If you issued the INQUIRE EXITPROGRAM command from a program, the high order bit of the response for GALENGTH is set. You must allow for this possibility when deciding what operation to next perform on the returned value.
GAUSECOUNT(data-area)
returns a halfword binary field indicating the total number of global or task-related user exits that are using the global work area owned by this exit. This count includes the owning exit program. A zero is returned if the exit is not the owner.
INDOUBTST(cvda)
returns a CVDA value indicating whether the task-related user exit is enabled with the INDOUBTWAIT keyword. CVDA values are:
NOTAPPLIC
The exit being inquired upon is a global user exit.
NOWAIT
The exit is not enabled with the INDOUBTWAIT keyword.
WAIT
The exit is enabled with the INDOUBTWAIT keyword.
NUMEXITS(data-area) (global user exits only)
returns a halfword binary field indicating the number of global user exit points at which the exit is enabled. A zero is returned if this is a task-related user exit.
PURGEABLEST(cvda) (task-related user exits only)
returns a CVDA value indicating whether the task-related user exit is enabled with the PURGEABLE keyword. CVDA values are:
NOTAPPLIC
The exit being inquired upon is a global user exit.
NOTPURGEABLE
Tasks are not purgeable from CICS waits within the task-related user exit.
PURGEABLE
Tasks are purgeable from CICS waits within the task-related user exit.
QUALIFIER(data-area)
returns, for a task-related user exit that is enabled for SPI calls, the 8-character qualifier returned by the exit.

For global user exits and task-related user exits that are not enabled for SPI calls, returns blanks.

SHUTDOWNST(cvda) (task-related user exits only)
returns a CVDA value indicating whether the SHUTDOWN option is enabled for the exit. SHUTDOWN causes invocation during CICS shutdown, and applies only to task-related user exits. CVDA values are:
NOSHUTDOWN
The exit is not invoked when a CICS shutdown occurs.
NOTAPPLIC
This is a global user exit.
SHUTDOWN
The exit is invoked when a CICS shutdown occurs.
SPIST(cvda)
returns a CVDA value indicating whether the task-related user exit is enabled for SPI calls. CVDA values are:
NOSPI
The exit is not enabled for SPI.
NOTAPPLIC
The exit being inquired upon is a global user exit. This occurs only when the INQUIRE command is explicitly for a global user exit. For example: 
INQUIRE EXITPROGRAM(abcd) exit(XFCREQ)

If you omit EXIT(XFCREQ), you are inquiring about a task-related user exit. Because all global user exits are, by default, task-related user exits as well, NOSPI is returned.

SPI
The exit is enabled for SPI.
STARTSTATUS(cvda)
returns a CVDA value identifying whether the exit is available for execution. CVDA values are:
STARTED
The exit program is available for execution; that is, the START option on an EXEC CICS ENABLE command is still in force.
STOPPED
The exit program is not available for execution; that is, the START option has not been issued, or has been revoked by the STOP option on an EXEC CICS DISABLE command.
TALENGTH(data-area) (task-related user exits only)
returns a halfword binary field indicating the length of the local (task-related) work area for the exit. Local work areas apply only to task-related user exits. A zero is returned if this is a global user exit.
TASKSTARTST(cvda) (task-related user exits only)
returns a CVDA value indicating whether the TASKSTART option is enabled for the exit. TASKSTART causes CICS to invoke the exit at the start and end of every task; it applies only to task-related user exits. CVDA values are:
NOTAPPLIC
This is a global user exit.
NOTASKSTART
The exit is not set for invocation at the start and end of every task.
TASKSTART
The exit is set for invocation at the start and end of every task.
USECOUNT(data-area)
returns the number of times the exit program has been invoked.
Note: The value returned is the total number of times this exit program has been invoked at all the global user exit points and task-related user exit invocation points that the exit program has been enabled and started at.

Conditions

END
RESP2 values:
2
There are no more resource definitions of this type.
ILLOGIC
RESP2 values:
1
You have issued a START command when a browse of this resource type is already in progress, or you have issued a NEXT or an END command when a browse of this resource type is not in progress.
INVREQ
RESP2 values:
3
The exit point identified by EXIT does not exist.
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.
PGMIDERR
RESP2 values:
1
The exit identified by EXITPROGRAM and ENTRYNAME is not enabled, or the EXIT parameter is missing on an inquiry on a global user exit, or is present on a task-related user exit.