INQUIRE PROGRAM

Description

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

CICS determines the information that 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, and does not attempt to autoinstall a resource for which it has no definition.

Browsing

You can browse through the definitions of programs, map sets, and partition sets 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 alphabetic order, and you can specify a starting point with the AT option if you want. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.

Private resources for applications

A program that is defined as part of an application installed on a platform is private to that version of that application. For supported resource types, including programs, a resource is private if the resource is defined in a CICS bundle that is packaged and installed as part of an application, either as part of the application bundle, or as part of the application binding bundle. A program that is auto-installed by a task for an application that is deployed on a platform is also private to that version of the application. A program that is defined by any other method is publicly available for all tasks, and is known as a public program. Note that a private program that is declared as an application entry point becomes a public program when the CICS bundle containing the statement of the application entry point is made available.

You can inquire on or browse private resources using the EXEC CICS INQUIRE system programming command for the resource type. By default, CICS searches for the resources that are available to the program where the EXEC CICS INQUIRE command is issued. You can also choose to browse private resources for a specified application.

The resource signature

You can use this command to retrieve the resource signature fields. You can use these fields to manage resources by capturing details of when the resource was defined, installed, and last changed. For more information, see Auditing resources. The resource signature fields are BUNDLE, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME, and INSTALLUSRID. See Summary of the resource signature field values for detailed information about the content of the resource signature fields.

Options

APIST(cvda) (programs only)

Returns a CVDA value that indicates 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.

The API attribute on the installed PROGRAM resource 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.

You cannot modify an API attribute of a program using the SPI. You can change the API attribute only by redefining the API option of the program in the CICS PROGRAM resource definition, or in the program autoinstall model, and reinstalling the definition. CVDA values are as follows:

CICSAPI

The program is restricted to use of only the CICS permitted application programming interfaces. If the program is defined with CONCURRENCY(QUASIRENT), it always runs on the quasi-reentrant (QR) TCB. If the program is defined as CONCURRENCY(THREADSAFE) it runs on whichever TCB in use by CICS at the time that is determined as suitable. If the program is defined as CONCURRENCY(REQUIRED), it always runs on an L8 open TCB.

OPENAPI

The program is not restricted to only the CICS permitted application programming interfaces. CICS runs the program on its own L8 or L9 mode open TCB, depending on the EXECKEY setting. If, when running a CICS command, CICS requires a switch to QR TCB, it returns to the open TCB before handing control back to the application program.

OPENAPI requires that the program is coded to threadsafe standards and defined with CONCURRENCY(THREADSAFE) or CONCURRENCY(REQUIRED). The preferred option is to use CONCURRENCY(REQUIRED) with OPENAPI, although CONCURRENCY(THREADSAFE) is allowed for compatibility with previous releases.

APPLICATION(data-area)

Specifies or returns the application name element of the application context. The application name can be up to 64 characters in length.

To browse private resources for an application deployed on a platform, use the APPLICATION, APPLMAJORVER, APPLMINORVER, APPLMICROVER, and PLATFORM options with the browse command START, to specify the platform, application name, and full version number for the application whose resources you want to browse.

For an inquiry on a public PROGRAM resource, the APPLICATION, APPLMAJORVER, APPLMINORVER, APPLMICROVER, and PLATFORM options return the name, version number, and platform of the application for which the program is defined as an application entry point. The OPERATION option returns the name of the relevant operation in the application. If the program is not defined as an application entry point, APPLICATION returns 64 blanks.

APPLMAJORVER(data-area)

Specifies or returns the application major version element of the application context, in fullword binary form. For an inquiry on a public PROGRAM resource, if the program is not defined as an application entry point, APPLMAJORVER returns a value of -1.

APPLMINORVER(data-area)

Specifies or returns the application minor version element of the application context, in fullword binary form. For an inquiry on a public PROGRAM resource, if the program is not defined as an application entry point, APPLMINORVER returns a value of -1.

APPLMICROVER(data-area)

Specifies or returns the application micro version element of the application context, in fullword binary form. For an inquiry on a public PROGRAM resource, if the program is not defined as an application entry point, APPLMICROVER returns a value of -1.

CEDFSTATUS(cvda) (programs only)

Returns a CVDA value that indicates the action taken by the execution diagnostic facility (EDF) transaction if this module is run under EDF. CVDA values are as follows:

CEDF

EDF diagnostic screens are displayed. If the program was translated with the EDF option, all EDF screens are displayed. If the program was translated with NOEDF, only the program initiation and termination screens appear.

NOCEDF

No EDF screens are displayed.

NOTAPPLIC

EDF does not apply because the module is a remote program, a map set, or a partition set.

CHANGEAGENT(cvda)

Returns a CVDA value that identifies the agent that made the last change to the resource definition. The possible values are as follows:

AUTOINSTALL

The resource was autoinstalled.

CREATESPI

The resource definition was last changed by an EXEC CICS CREATE command.

CSDAPI

The resource definition was last changed by a CEDA transaction or the programmable interface to DFHEDAP.

CSDBATCH

The resource definition was last changed by a DFHCSDUP job.

DREPAPI

The resource definition was last changed by a CICSPlex SM BAS API command.

SYSTEM

The resource definition was last changed by the CICS or CICSPlex system.

CHANGEAGREL(data-area)

Returns a 4-digit number of the CICS release that was running when the resource definition was last changed.

CHANGETIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource definition was last changed. For more information about the format of the ABSTIME value, see FORMATTIME.

CHANGEUSRID(data-area)

Returns the 8-character user ID that ran the change agent.

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. CVDA values are as follows:

COBOL

The module is an OS/VS COBOL program. (OS/VS COBOL programs cannot run under this CICS Transaction Server version.)

COBOLII

The module is a COBOL program that has been compiled with VS COBOL II or a more recent COBOL compiler.

NOTAPPLIC

The module has been loaded and it is not a COBOL program, or the module has not been loaded and it is not defined as a COBOL program.

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 value that indicates the concurrency attribute of the installed program definition. The CVDA values are as follows:

QUASIRENT

The program is defined as being quasi-reentrant, and can run only under the CICS QR TCB.

THREADSAFE

The program is defined as threadsafe, and can run under whichever TCB is in use by its user task when the program is given control. This can be either an open TCB or the CICS QR TCB.

REQUIRED

The program is defined as threadsafe, and must run on an open TCB. The type of open TCB used depends on the API setting.

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 later loaded. If CICS finds that the program itself contains a CONCURRENCY value defined by Language Environment® runtime options, the installed program resource definition is updated by the Language Environment runtime 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.

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

COPY(cvda)

Returns a CVDA value that indicates 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, issue a SET PROGRAM COPY command or its CEMT equivalent. Ensure that the program exists in one of the libraries in the DFHRPL or dynamic LIBRARY concatenation before doing so. CVDA values are as follows:

NOTREQUIRED

A new copy is not required. This CVDA value is always returned for Java™ programs that run in a JVM.

REQUIRED

A new copy is required.

DATALOCATION(cvda) (programs only)

Returns a CVDA value that indicates whether this module can accept data addresses higher than 16 MB. CVDA values are as follows:

ANY

The program can accept an address above 16 MB.

BELOW

The program requires any data address returned to it from CICS to be less than 16 MB.

NOTAPPLIC

The option does not apply because the module is a remote program, a map set, or a partition set.

DEFINESOURCE(data-area)

Returns the 8-character source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT value. For more information, see Summary of the resource signature field values.

DEFINETIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource definition was created.

DYNAMSTATUS(cvda) (programs only)

Returns a CVDA value that indicates whether, if the program is the subject of a program-link request, the request can be dynamically routed. CVDA values are as follows:

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

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 run 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 Dynamically routing DPL requests.

ENTRYPOINT(ptr-ref)

Returns the entry point of the module, if it is loaded. CICS program load services set the entry point according to the addressing mode of the load module:

• AMODE(24): bit 0 is 0 and bit 31 is 0.
• AMODE(31): bit 0 is 1 and bit 31 is 0.
• AMODE(64): bit 0 is 0 and bit 31 is 1.

If the module is not loaded, or is a remote program, or is a Java program that runs in a JVM, a null pointer (X'FF000000') is returned.

EXECKEY(cvda) (programs only)

Returns a CVDA value that indicates 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 CICS storage protection and transaction isolation. CVDA values are as follows:

CICSEXECKEY

The program runs in CICS key.

NOTAPPLIC

The module is a remote program, a map set, or a partition set.

USEREXECKEY

The program runs in user key.

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 EXECUTIONSET option applies only to executable programs, and governs the API only when a program is called locally. When it is called 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 as follows:

DPLSUBSET

The program is always restricted.

FULLAPI

The program is not restricted unless called 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 that indicates whether a copy of the module is currently loaded with the HOLD option. CVDA values are as follows:

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.

INSTALLAGENT(cvda)

Returns a CVDA value that identifies the agent that installed the resource. The possible values are as follows:

AUTOINSTALL

The resource was autoinstalled.

BUNDLE

The resource was installed by a bundle deployment.

CREATESPI

The resource was installed by an EXEC CICS CREATE command.

CSDAPI

The resource was installed by a CEDA transaction or the programmable interface to DFHEDAP.

GRPLIST

The resource was installed by GRPLIST INSTALL.

SYSTEM

The resource was installed by the CICS or CICSPlex SM system.

INSTALLTIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource was installed.

INSTALLUSRID(data-area)

Returns the 8-character user ID that installed the resource.

JVMCLASS(data-area) (Java programs only)

Returns the name, in 255 characters, of the main class in the Java program to be given control by the JVM, as specified in the program definition.

JVMPROFILE(data-area) (Java programs only)

Returns the name of the JVM profile that is to be used for the pooled JVM in which this Java program runs. The name can be up to 8 characters in length.

JVMSERVER(data-area) (Java programs only)

Returns the name of the JVM server in which this Java program runs. The name can be up to 8 characters in length.

LANGDEDUCED(cvda) (programs only)

Returns a CVDA value that indicates the language for the loaded module. 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 as follows:

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 that indicates the program language. The CICS program manager deduces the correct language, except for programs written in assembler without the DFHEAI or DFHEAG stub. In this case, the LANGUAGE attribute of the program definition is used to return a value. CVDA values are as follows:

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 that gives 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 Java program that runs in a JVM.

LIBRARY(data-area)

Returns the 8-character name of the library resource from which this program was loaded. This data area is blank if the program has not been loaded, or if the LPASTATUS is LPA, indicating that the program has been loaded from the LPA.

Note:

• If the program was loaded from an installed library, the LIBRARY and LIBRARYDSN names are returned.
• If the program was loaded from a library that has been disabled, the LIBRARY name is returned but the LIBRARYDSN is blank.
• If the program was loaded from a library that has been discarded, both LIBRARY and LIBRARYDSN names are blank.

LIBRARYDSN(data-area)

Returns the 44-character name of the data set from which the program was loaded. This data area is blank if the program has not been loaded, or if the LPASTATUS is LPA, indicating that the program has been loaded from the LPA.

• If the program was loaded from an installed library, the LIBRARY and LIBRARYDSN names are returned.
• If the program was loaded from a library that has been disabled, the LIBRARY name is returned but the LIBRARYDSN is blank.
• If the program was loaded from a library that has been discarded, both LIBRARY and LIBRARYDSN names are blank.

LOADPOINT(ptr-ref)

Returns the load address of the module. If it is not currently loaded, or if the program is a Java program running in a JVM, a null pointer (X'FF000000') is returned.

LPASTATUS(cvda)

Returns a CVDA value that indicates whether the module resided in the link pack area when it was last used. CVDA values are as follows:

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 Java program.

NOTLPA

The copy used was in CICS dynamic storage.

OPERATION(data-value)

Returns, in a 64-character area, the name of the application operation for which this program is defined as an entry point. If the program is not defined as an application entry point, OPERATION returns 64 blanks.

PLATFORM(data-area)

Specifies or returns the platform name element of the application context. The platform name can be up to 64 characters in length. For an inquiry on a public PROGRAM resource, if the resource is not defined as an application entry point, PLATFORM returns 64 blanks.

PROGRAM(data-value)

Specifies the name of the program, map set, or partition set about which you are inquiring. The name can be up to 8 characters in length.

PROGTYPE(cvda)

Returns a CVDA value that indicates the type of module. CVDA values are as follows:

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. The REMOTENAME option 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 that gives 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 Java program that runs in a JVM.

RESIDENCY(cvda) (programs only)

Returns a CVDA value that indicates the program's residency attributes. The CVDA values are as follows:

RESIDENT

The program is permanently resident. It is defined as RESIDENT(YES).

NONRESIDENT

The program has been defined as RESIDENT(NO).

RUNTIME(cvda)

Returns a CVDA value that indicates the runtime environment of the program. CVDA values are as follows:

JVM

The program is a Java program that runs in a Java Virtual Machine (JVM).

LE370

The program will run with Language Environment 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.

XPLINK

The program is a C or C++ program that has been compiled using the XPLINK option.

SHARESTATUS(cvda)

Returns a CVDA value that indicates where CICS obtains the module the next time a new copy is required. CVDA values are as follows:

NOTAPPLIC

SHARESTATUS does not apply because the module is a remote program or a Java program that runs in a JVM.

PRIVATE

The module is loaded from one of the libraries in the DFHRPL or dynamic LIBRARY concatenation.

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 that indicates whether the module is available for use. CVDA values are as follows:

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, runs remotely; that is, the transaction identifier that 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 that gives the total number of times the module has been used since the start of the current CICS session. The use count is provided for all modules including Java programs, except for remote programs. A value of -1 is returned if the program is remote.

Conditions

APPNOTFOUND

RESP2 values:

1

A START command has been issued specifying an application context. The named application is not found.

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 command, an earlier cataloging error has made a PROGRAM, MAPSET, or PARTITIONSET definition unusable, and the definition must be discarded and reinstalled.