INQUIRE PROGRAM

Retrieves information about a program.

Syntax

INQUIRE PROGRAM

Read syntax diagramSkip visual syntax diagramINQUIRE PROGRAM(data-value)CEDFSTATUS( cvda)COBOLTYPE( cvda)COPY( cvda)DATALOCATION( cvda)ENTRYPOINT( ptr-ref)EXECKEY( cvda)EXECUTIONSET( cvda)HOLDSTATUS( cvda)LANGUAGE( cvda)LENGTH( data-area)LOADPOINT( ptr-ref)LPASTATUS( cvda)PROGTYPE( cvda)REMOTENAME( data-area)REMOTESYSTEM( data-area)RESCOUNT( data-area)SHARESTATUS( cvda)STATUS( cvda)TRANSID( data-area)USECOUNT( data-area)

Conditions: END, ILLOGIC, PGMIDERR

 

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

Description

The INQUIRE PROGRAM command returns information about a particular program or data module that is installed in your CICS® system.

CICS determines the information that you request from the resource definition and, where applicable, the load module. Information from the module takes precedence over that which is in the definition if a conflict occurs. However, CICS inspects a module only if it is already loaded and is the copy that is currently available for use. CICS does not do a load for an INQUIRE PROGRAM command.

Comments

You can also browse through the definitions of these three types of resources in your system by using the browse options (START, AT, NEXT, and END) on INQUIRE PROGRAM commands. In browse mode, the definitions are returned in alphabetical sequence, and you can specify a starting point with the AT option if you want. For general information about browsing, syntax, exception conditions, and examples, see Use of CICS API commands.

Options

CEDFSTATUS(cvda) (programs only)
Returns a CVDA value that indicates the action that is taken by the execution diagnostic facility (EDF) transaction if this module is executed under EDF. The CVDA values are:
CEDF
The EDF diagnostic screens are displayed. If the program was translated with the CEDF value, all the EDF screens are displayed; if it was translated with the NOEDF value, no EDF screens are displayed.
NOCEDF
No EDF screens are displayed.
NOTAPPLIC
EDF is not applicable because the module is a remote program or a data module.

TXSeries for Multiplatforms always returns the CEDF value.

COBOLTYPE(cvda) (programs only)
Returns a CVDA value that indicates the type of COBOL in which the module is written, if it is a COBOL program. The type is determined by inspecting the load module. The CVDA values are:
MFCOBOL
The module is a Micro Focus COBOL program.
IBMCOBOL
The module is an IBM® COBOL program.
COBOLIT
The module is a COBOLIT COBOL program.
NOTAPPLIC
COBOL type does not apply, because the module is a remote program or a data module or not a COBOL program.
NOTINIT
The type cannot be determined because the module has not yet been initialized.

TXSeries for Multiplatforms always returns the NOTAPPLIC value if the COBOL type of the program is not the MFCOBOL, IBMCOBOL or the COBOLIT value.

COPY(cvda)
Returns a CVDA value that indicates whether a new copy of the module is required to make it available for use. To make the module available again, you must issue a SET PROGRAM COPY command or its CEMT equivalent. Before doing so, ensure that the program exists in one of the libraries that are in the concatenation. The CVDA values are:
NOTREQUIRED
A new copy is not required.
REQUIRED
A new copy is required.

TXSeries for Multiplatforms always returns the NOTREQUIRED value.

DATALOCATION(cvda) (programs only)
Returns a CVDA value that indicates whether this module can accept data addresses higher than 16 MB. The CVDA values are:
ANY
The program can accept an address above 16 MB.
BELOW
The program requires any data address that is returned to it from CICS to be less than 16 MB.
NOTAPPLIC
The option is not applicable because the module is a remote program or a data module.

TXSeries for Multiplatforms never returns the BELOW value.

ENTRYPOINT(ptr-ref) (programs only)
Returns the entry point of the module, if it is loaded for the task. If the module has not been loaded for the task or is a remote program or a data module, a null pointer (X'FF000000') is returned.

TXSeries for Multiplatforms always returns a null pointer.

EXECKEY(cvda) (programs only)
Returns a CVDA value that indicates the storage key of the module, if it is an executable program. The CVDA values are:
CICSEXECKEY
The program executes in CICS key.
NOTAPPLIC
The module is a remote program or a data module.
USEREXECKEY
The program executes in user key.

TXSeries for Multiplatforms always returns the CICSEXECKEY value.

EXECUTIONSET(cvda) (programs only)
Returns a CVDA value that indicates whether the module is restricted to the distributed program link subset of the CICS API. The CVDA values are:
DPLSUBSET
The program is always restricted.
FULLAPI
The program is not restricted unless invoked remotely.
NOTAPPLIC
The EXECUTIONSET option does not apply because the module is a remote program or a data module.

TXSeries for Multiplatforms never returns the DPLSUBSET value.

HOLDSTATUS(cvda) (data modules only)
Returns a CVDA value that indicates whether a copy of the module is currently loaded with the HOLD option. The CVDA values are:
HOLD
A copy is currently loaded with the HOLD option.
NOHOLD
No copy is currently loaded with the HOLD option.
NOTAPPLIC
The module is not currently loaded, or is a remote program.

TXSeries for Multiplatforms never returns the HOLD value.

LANGUAGE(cvda) (programs only)
Returns a CVDA value that indicates the language in which the module is written. This value is taken from the resource definition. The CVDA values are:
C
The language is C.
CPP
The language is C++.
COBOL
The language is MF COBOL or IBM COBOL or COBOL-IT.
JAVA
The language is Java™.
NOTAPPLIC
LANGUAGE does not apply because the module is a remote program or a data module.
PLI or PL1
The language is PL/I.
LENGTH(data-area) (data modules only)
Returns a 32-bit binary field that gives the length of the module in bytes. A value of zero is returned if the module has not been loaded in the current CICS session. A null value is returned if it is an executable program or a remote program.

TXSeries for Multiplatforms always returns a null value. Because the actual null value returned depends on the format of the user-defined data area, see Null values for a full description of the different types of null values.

LOADPOINT(ptr-ref) (data modules only)
Returns the load address of the module. If it is not currently loaded, a null pointer (X'FF000000') is returned.

TXSeries for Multiplatforms always returns a null pointer.

LPASTATUS(cvda)
Returns a CVDA value that indicates whether the module resided in the link pack area when it was last used. The CVDA values are:
LPA
The copy that was used was in shared storage.
NOTAPPLIC
The module has not been used or is a remote program.
NOTLPA
The copy that was used was in CICS dynamic storage.

TXSeries for Multiplatforms never returns the NOTLPA value.

PROGRAM(data-value)
Specifies the name of the program, map set, or table, as defined in the PD. The name can be up to eight characters long.
PROGTYPE(cvda)
Returns a CVDA value that indicates the type of module. The CVDA values are:
MAPSET
The module is a map set.
PARTITIONSET
The module is a partition set.
PROGRAM
The module is an executable program or data module.

TXSeries for Multiplatforms never returns the PARTITIONSET value.

REMOTENAME(data-area) (programs only)
Returns the eight-character name by which the module is known in the CICS region that is named in the REMOTESYSTEM option of its PPT definition. REMOTENAME applies only to programs, and only to those that are defined to be remote; for local programs and data modules, a null value is returned.
REMOTESYSTEM(data-area) (programs only)
Returns the four-character name of the CICS region in which the module is defined (from the REMOTESYSTEM value in the PPT definition). It applies only to programs, and only to those defined to be remote; for local programs and data modules, a null value is returned.
RESCOUNT(data-area)
Returns a 32-bit binary field that gives the number of separate uses of this module that are occurring at the time of this inquiry. A null value is returned if the module is a remote program. The actual null value returned depends on the format of the user-defined data area. See Null values for a full description of the different types of null values. This variable is supported for TABLES and MAP SETS only on TXSeries for Multiplatforms. Currently, it is not supported for PROGRAMS in TXSeries.
SHARESTATUS(cvda)
Returns a CVDA value that indicates where CICS should obtain the module the next time a new copy is required. The CVDA values are:
NOTAPPLIC
SHARESTATUS is not applicable because the module is a remote program.
SHARED
A shared copy will be used.
STATUS(cvda)
Returns a CVDA value that indicates whether the module is available for use. The CVDA values are:
DISABLED
The module is not available for use.
ENABLED
The module is available for use.
TRANSID(data-area) (programs only)
Returns the four-character name of the transaction under which this module, which must be a program, executes remotely (that is, the transaction identifier that the remote region assigns to execute the task that was created there, when a task in the local region LINKs to it). This value comes from the TRANSID option value in the PPT definition and applies only to programs that are defined as remote; for local programs and data modules, and when no TRANSID option is specified for a remote program, a null value is returned.
USECOUNT(data-area)

Returns a 32-bit binary field that gives the total number of times the module has been used since the start of the current CICS session. A null value is returned if the program is remote. See Null values for more information.

TXSeries for Multiplatforms always returns -1 for USECOUNT. It is currently not supported with TXSeries.

Conditions

END
RESP2 values:

No more resource definitions of this type exist (RESP2=2).

ILLOGIC
RESP2 values:

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 (RESP2=1).

PGMIDERR
RESP2 values:

The program cannot be found (RESP2=1).