INQUIRE PROGRAM

Retrieve information about a program, map set, or partition set.

Read syntax diagramSkip visual syntax diagramINQUIRE PROGRAM
 
>>-INQUIRE PROGRAM(data-value)---------------------------------->
 
   .-----------------------------.
   V                             |
>----+-------------------------+-+-----------------------------><
     +-APIST(cvda)-------------+
     +-CEDFSTATUS(cvda)--------+
     +-COBOLTYPE(cvda)---------+
     +-COPY(cvda)--------------+
     +-CONCURRENCY(cvda)-------+
     +-DATALOCATION(cvda)------+
     +-DYNAMSTATUS(cvda)-------+
     +-ENTRYPOINT(ptr-ref)-----+
     +-EXECKEY(cvda)-----------+
     +-EXECUTIONSET(cvda)------+
     +-HOLDSTATUS(cvda)--------+
     +-JVMCLASS(data-area)-----+
     +-JVMDEBUG(cvda)----------+
     +-JVMPROFILE(data-area)---+
     +-LANGDEDUCED(cvda)-------+
     +-LANGUAGE(cvda)----------+
     +-LENGTH(data-area)-------+
     +-LOADPOINT(ptr-ref)------+
     +-LPASTATUS(cvda)---------+
     +-PROGTYPE(cvda)----------+
     +-REMOTENAME(data-area)---+
     +-REMOTESYSTEM(data-area)-+
     +-RESCOUNT(data-area)-----+
     +-RUNTIME(cvda)-----------+
     +-SHARESTATUS(cvda)-------+
     +-STATUS(cvda)------------+
     +-TRANSID(data-area)------+
     '-USECOUNT(data-area)-----'
 

Conditions: END, ILLOGIC, NOTAUTH, PGMIDERR

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

Description

The INQUIRE PROGRAM command returns information about a particular program, map set, or partition set installed in your CICS system. All of these resources are load modules and, therefore, CICS uses the same INQUIRE command for all three. To avoid confusion, we use the word module to refer to the object of your inquiry, except in some cases where the option applies only to executable programs.

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

Browsing

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 order, and you can specify a starting point with the AT option if you wish. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.

Options

Start of changeAPIST(cvda) (programs only) End of change
Start of changereturns a CVDA value indicating the API attribute of the installed program definition. The API attribute is used for application programs, PLT programs, user replaceable modules and task related user exits. The API attribute is not used for global user exits. CVDA values are:
CICSAPI
The program is restricted to use of the CICS permitted application programming interfaces only. Dependent upon the program's CONCURRENCY setting, the application will either always run on the quasi-reentrant (QR) TCB, or if it is defined as threadsafe it may run on whichever TCB in use by CICS at the time which is determined as suitable.
OPENAPI
The program is not restricted to the CICS permitted application program interfaces only. CICS will execute the program on its own L8 or L9 mode open TCB dependent upon the EXECKEY setting. If when executing a CICS command, CICS requires a switch to QR TCB, it will return to the open TCB before handing control back to the application program. OPENAPI requires the program to be coded to threadsafe standards and defined with CONCURRENCY(THREADSAFE).
Notes:
  1. The API attribute on the installed program resource definition for a task-related user exit program is not changed by any options specified on an ENABLE command. For a task-related user exit program, CICS always returns a CVDA using the values defined in the program resource definition.
  2. You cannot modify a program's API attribute using the SPI--the API option is not supported on the EXEC CICS SET PROGRAM command. You can only change the API attribute by redefining the program's API option in the CICS program resource definition, or in the program autoinstall model, and reinstalling the definition.
End of change
CEDFSTATUS(cvda) (programs only)
returns a CVDA value indicating the action taken by the execution diagnostic facility (EDF) transaction if this module is executed under EDF. CVDA values are:
CEDF
EDF diagnostic screens are displayed. If the program was translated with the EDF option, all EDF screens are displayed; if it was translated with NOEDF, only the program initiation and termination screens appear.
NOCEDF
No EDF screens are displayed.
NOTAPPLIC
EDF is not applicable because the module is a remote program, a map set, or a partition set.
COBOLTYPE(cvda) (programs only)
returns a CVDA value indicating 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. CVDA values are:
COBOL
The module is an OS/VS COBOL program. (OS/VS COBOL programs cannot run under CICS® Transaction Server for z/OS® Version 3.)
COBOLII
The module is a VS COBOL II program.
NOTAPPLIC
COBOL type does not apply, because the module is a remote program, a map set, or a partition set. This CVDA value is always returned for JVM programs.
NOTINIT
The module is defined as a COBOL program, but the type cannot be determined because the module has not been loaded yet.
CONCURRENCY
returns a CVDA indicating the concurrency attribute of the installed program definition. The CVDA values are:
QUASIRENT
The program is defined as being quasi-reentrant, and is able to run only under the CICS QR TCB.
THREADSAFE
The program is defined as threadsafe, and is able to run 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.
Notes:
  1. If the program is not yet loaded (or is waiting to be reloaded following a NEWCOPY or PHASEIN request), the concurrency attribute is derived from the installed program resource definition. Note that the default for the program definition is QUASIRENT. However, in the case of a Language Environment-conforming program, the concurrency as originally defined can be overridden when the program is subsequently loaded. If CICS finds that the program itself contains a CONCURRENCY value defined by Language Environment run-time options, the installed program resource definition is updated by the Language Environment run-time option.
  2. The CONCURRENCY attribute on the installed program resource definition is not changed by the FORCEQR system initialization parameter. CICS returns a CVDA of THREADSAFE for a threadsafe-defined program, even if FORCEQR=YES is specified.
  3. The CONCURRENCY attribute on the installed program resource definition for a task-related user exit program is not changed by any options specified on an ENABLE command. For a task-related user exit program, CICS always returns a CVDA using the values defined in the program resource definition.

    Start of changeYou cannot modify a program's concurrency attribute using the SPI--the CONCURRENCY option is not supported on the EXEC CICS SET PROGRAM command. You can only change the concurrency by redefining the program's CONCURRENCY option in the CICS program resource definition, or in the program autoinstall model, and then reinstalling the definition.End of change

COPY(cvda)
returns a CVDA value indicating whether a new copy of the module is required to make it available for use. This requirement occurs after CICS attempts to load the module and cannot find it, because CICS marks it "not loadable" to avoid the overhead of further load attempts. To make the module available again, you need to issue a SET PROGRAM COPY command or its CEMT equivalent. You should ensure that the program exists in one of the libraries in the DFHRPL concatenation before doing so. CVDA values are:
NOTREQUIRED
A new copy is not required. This CVDA value is always returned for JVM programs.
REQUIRED
A new copy is required.
DATALOCATION(cvda) (programs only)
returns a CVDA value indicating whether this module can accept data addresses higher than 16MB. CVDA values are:
ANY
The program can accept an address above 16MB.
BELOW
The program requires any data address returned to it from CICS to be less than 16MB.
NOTAPPLIC
The option is not applicable because the module is a remote program, a map set, or a partition set.
DYNAMSTATUS(cvda) (programs only)
returns a CVDA value indicating whether, if the program is the subject of a program-link request, the request can be dynamically routed. CVDA values are:
DYNAMIC
If the program is the subject of a program-link request, the CICS dynamic routing program is invoked. Providing that a remote server region is not named explicitly on the SYSID option of the LINK command, the routing program can route the request to the region on which the program is to execute.
NOTDYNAMIC
If the program is the subject of a program-link request, the dynamic routing program is not invoked.

For a distributed program link (DPL) request, the server region on which the program is to execute must be specified explicitly on the REMOTESYSTEM option of the PROGRAM definition or on the SYSID option of the LINK command; otherwise it defaults to the local region.

For information about the dynamic routing of DPL requests, see the CICS Intercommunication Guide.

ENTRYPOINT(ptr-ref)
returns the entry point of the module, if it is loaded. The top bit of the address is set on if the addressing mode is 31 and off if it is 24. If the module has not been loaded, or is a remote program, or is a JVM program, a null pointer (X'FF000000') is returned.
EXECKEY(cvda) (programs only)
returns a CVDA value indicating the storage key of the module, if it is an executable program. The storage key can limit the areas of storage that the program can access, depending on other variables. See the ISOLATEST option of the INQUIRE TASK and INQUIRE TRANSACTION commands, the STOREPROTECT and TRANISOLATE options of the INQUIRE SYSTEM command, and the general discussion of storage protection in the CICS Application Programming Guide. CVDA values are:
CICSEXECKEY
The program executes in CICS key.
NOTAPPLIC
The module is a remote program, a map set, or a partition set.
USEREXECKEY
The program executes in user key.
EXECUTIONSET(cvda) (programs only)
returns a CVDA value indicating whether the module is restricted to the distributed program link subset of the CICS API. EXECUTIONSET applies only to executable programs, and governs the API only when a program is invoked locally. (When it is invoked remotely--that is, executing at or below the level of a program invoked by a distributed program link--a program is always restricted to this subset.) CVDA values are:
DPLSUBSET
The program is always restricted.
FULLAPI
The program is not restricted unless invoked remotely.
NOTAPPLIC
EXECUTIONSET does not apply because the module is a remote program, a map set, or a partition set.
HOLDSTATUS(cvda)
returns a CVDA value indicating whether a copy of the module is currently loaded with the HOLD option. 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.
JVMCLASS(data-area) (JVM programs only)
returns the name, in 255 characters, of any class specified in the program definition.
JVMDEBUG(cvda) (JVM programs only)
This option is obsolete. CICS always returns NODEBUG as the cvda value.
JVMPROFILE(data-area) (JVM programs only)
returns the 8-character name of the JVM profile associated with the program.
LANGDEDUCED(cvda) (programs only)
returns a CVDA value indicating the language (that is, the module is loaded). If the module is not yet loaded, CICS cannot deduce the language. In this case, the CVDA value indicates the defined language taken from the resource definition. CVDA values are:
ASSEMBLER
The language is assembler.
C
The language is C or C++.
COBOL
The language is COBOL.
JAVA
The language is Java.
LE370
The module, whatever its language, was compiled to run with Language Environment.
NOTAPPLIC
LANGUAGE does not apply because the module is a remote program, a map set, or a partition set.
NOTDEFINED
The language was not specified in the resource definition, and has not been loaded.
PLI or PL1
The language is PL/I.
LANGUAGE(cvda) (programs only)
returns a CVDA value indicating the program language. Start of changeThe CICS program manager deduces the correct language, except where programs are written in assembler and do not have the DFHEAI stub. In this case, the LANGUAGE attribute of the program definition is used to return a value.End of change CVDA values are:
ASSEMBLER
The language is assembler.
C
The language is C.
COBOL
The language is COBOL
LE370
The module, whatever its language, exploits multi-language support, or was compiled with a Language Environment-conforming compiler.
NOTAPPLIC
LANGUAGE does not apply because the module is a remote program, a map set, or a partition set.
NOTDEFINED
The language was not specified in the resource definition.
PLI or PL1
The language is PL/I.
LENGTH(data-area)
returns a fullword binary field giving the length of the module in bytes. A value of 0 is returned if the module has not been loaded in the current CICS session. A value of -1 is returned if it is a remote program, or a JVM program.
LOADPOINT(ptr-ref)
returns the load address of the module. If it is not currently loaded, or if the program is running under a JVM, a null pointer (X'FF000000') is returned.
LPASTATUS(cvda)
returns a CVDA value indicating whether the module resided in the link pack area when it was last used. CVDA values are:
LPA
The copy used was in the link pack area (LPA) or the extended link pack area (ELPA).
NOTAPPLIC
The module has not been used, is a remote program, or is a JVM program.
NOTLPA
The copy used was in CICS dynamic storage.
PROGRAM(data-value)
specifies the 8-character name of the program, map set, or partition set about which you are inquiring.
PROGTYPE(cvda)
returns a CVDA value indicating the type of module. CVDA values are:
MAPSET
The module is a map set. (MAP is still a synonym for MAPSET, but MAPSET is the preferred CVDA value.)
PARTITIONSET
The module is a partition set.
PROGRAM
The module is an executable program.
REMOTENAME(data-area) (programs only)
returns the 8-character name by which the module is known in the CICS region named in the REMOTESYSTEM option of its PROGRAM definition. REMOTENAME applies only to programs, and only to those defined to be remote; for local programs, map sets, and partition sets, the value returned is blanks.
REMOTESYSTEM(data-area) (programs only)
returns the 4-character name of the CICS region in which the module is defined (from the REMOTESYSTEM value in the PROGRAM definition). It applies only to programs, and only to those defined to be remote; for local programs, map sets, and partition sets, the value returned is blanks.
RESCOUNT(data-area)
returns a fullword binary field giving the number of separate uses of this module that are taking place at the time of this inquiry. A value of -1 is returned if the module is either a remote program, or a JVM program.
RUNTIME(cvda)
returns a CVDA value indicating the runtime environment of the program. CVDA values are:
JVM
The program is a Java program that will run under the control of a Java Virtual Machine.
Start of changeLENVEnd of change
The program will run with LE370 runtime support.
NONLE370
The program will run with a language-specific runtime environment.
NOTAPPLIC
RUNTIME does not apply because the module is a map set or a partition set.
UNKNOWN
The program runtime environment is unknown, because the program has not been loaded by CICS, and therefore its source language has not been deduced, which dictates the runtime environment to be used.
Start of changeXPLINKEnd of change
Start of changeThe program is a C or C++ program which has been compiled using the XPLINK option.End of change
SHARESTATUS(cvda)
returns a CVDA value indicating where CICS should obtain the module the next time a new copy is required. CVDA values are:
NOTAPPLIC
SHARESTATUS is not applicable because the module is a remote program or a JVM program.
PRIVATE
The module is loaded from the concatenated libraries named on the DFHRPL DD statement.
SHARED
The LPA copy is to be used, if one is available. If it is not, the module is loaded as if SHARESTATUS were PRIVATE.
STATUS(cvda)
returns a CVDA value indicating whether the module is available for use. 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 4-character name of the transaction under which this module, which must be a program, executes remotely (that is, the transaction identifier the remote region assigns to the task created there to execute it when a task in the local region LINKs to it). This value comes from the TRANSID option value in the PROGRAM definition and applies only to programs defined as remote; for local programs, map sets, and partition sets, and when no TRANSID is specified for a remote program, the value returned is blanks.
USECOUNT(data-area)
returns a fullword binary field giving the total number of times the module has been used since the start of the current CICS session. A value of -1 is returned if the program is remote, or a JVM program.

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.
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 program cannot be found. If this error occurs on an INQUIRE PROGRAM NEXT, an earlier cataloging error has made a PROGRAM, MAPSET, or PARTITIONSET definition unusable, and the definition must be discarded and reinstalled.
[[ Contents Previous Page | Next Page Index ]]