INQUIRE PROGRAM

Retrieves information about a program.

Syntax

INQUIRE PROGRAM

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).