The INQUIRE_PROGRAM call
INQUIRE_PROGRAM returns information about the attributes of a specified program.
INQUIRE_PROGRAM
DFHPGISX [CALL,]
[CLEAR,]
[IN,
FUNCTION(INQUIRE_PROGRAM),
[AC_APPLICATION_NAME(block-descriptor),]
[AC_MAJOR_VERSION(name4),]
[AC_MICRO_VERSION(name4),]
[AC_MINOR_VERSION(name4),]
[AC_PLATFORM_NAME(block-descriptor),]
[{PROGRAM_NAME(name8 | string | 'string')|
PROGRAM_TOKEN(name4)},]
[SHOW_PROGRAMS(PRIVATE|PRIVATE_AND_PUBLIC),]
[OUT,
[ACCESS(CICS|NONE|READ_ONLY|USER),]
[APIST(CICSAPI|OPENAPI),]
[AVAIL_STATUS(DISABLED|ENABLED),]
[CEDF_STATUS(CEDF|NOCEDF|NOT_APPLIC),]
[CONCURRENCY(QUASIRENT|THREADSAFE),]
[DATA_LOCATION(ANY|BELOW|NOT_APPLIC),]
[DYNAMIC_STATUS(DYNAMIC|NOT_DYNAMIC),]
[ENTRY_POINT(name4),]
[EXECUTION_KEY(CICS|NOT_APPLIC|USER),]
[EXECUTION_SET(DPLSUBSET|FULLAPI|NOT_APPLIC),]
[HOLD_STATUS(CICS_LIFE|NOT_APPLIC|TASK_LIFE),]
[INSTALL_TYPE(AUTO|CATALOG|GROUPLIST|MANUAL|RDO|SYSAUTO),]
[LANGUAGE_DEDUCED(ASSEMBLER|C370|COBOL|
COBOL2|LE370|NOT_APPLIC|NOT_DEDUCED|PLI),]
[LANGUAGE_DEFINED(ASSEMBLER|C370|COBOL|
LE370|NOT_APPLIC|NOT_DEFINED|PLI),]
[LIBRARY(name8),]
[LIBRARYDSN(name44),]
[LOAD_POINT(name4),]
[LOAD_STATUS(LOADABLE|NOT_APPLIC|NOT_LOADABLE|NOT_LOADED),]
[LOCATION(CDSA|ECDSA|ELPA|ERDSA|ESDSA|LPA|NONE|RDSA|SDSA),]
[MODULE_TYPE(MAPSET|PARTITIONSET|PROGRAM),]
[NEW_PROGRAM_TOKEN(name4),]
[PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT),]
[PROGRAM_LENGTH(name4),]
[PROGRAM_TYPE(NOT_APPLIC|PRIVATE|SHARED|TYPE_ANY),]
[PROGRAM_USAGE(APPLICATION|NUCLEUS),]
[PROGRAM_USE_COUNT(name4),]
[PROGRAM_USER_COUNT(name4),]
[REMOTE_DEFINITION(LOCAL|REMOTE),]
[REMOTE_PROGID(name8),]
[REMOTE_SYSID(name4),]
[REMOTE_TRANID(name4),]
[SPECIFIED_AMODE(24|31|AMODE_ANY|AMODE_NOT_SPECIFIED|64),]
[SPECIFIED_RMODE(24|RMODE_ANY|RMODE_NOT_SPECIFIED),]
RESPONSE(name1 | *),
REASON(name1 | *)]This command is threadsafe.
- AC_APPLICATION_NAME(block-descriptor)
- Specifies the address and length of the name of the application associated with the program. To inquire on private programs for applications deployed on platforms, you must specify the AC_APPLICATION_NAME, AC_MAJOR_VERSION, AC_MINOR_VERSION, AC_MICRO_VERSION, and AC_PLATFORM_NAME fields to provide a complete application context. For more information on block-descriptors, see XPI syntax.
- AC_MAJOR_VERSION(name4)
- Specifies the application major version in binary.
- AC_MICRO_VERSION(name4)
- Specifies the application micro version in binary.
- AC_MINOR_VERSION(name4)
- Specifies the application minor version in binary.
- AC_PLATFORM_NAME(block-descriptor)
- Specifies the address and length of the name of the platform associated with the program. For more information on block-descriptors, see XPI syntax.
- ACCESS(CICS|NONE|READ_ONLY|USER)
- Returns a value that indicates the type of storage into which
the program has been loaded.
- CICS®
- CICS-key.
- NONE
- The program has not been loaded.
- READ_ONLY
- Read-only.
- USER
- User-key.
- APIST(CICSAPI|OPENAPI)
- Returns a value that indicates the API attribute of the installed
program definition.
- CICSAPI
- The program is restricted to use of only the CICS permitted application programming interfaces.
- OPENAPI
- The program is not restricted to use of only the CICS permitted application programming interfaces. The program must be coded to threadsafe standards and defined with CONCURRENCY(THREADSAFE).
- AVAIL_STATUS(DISABLED|ENABLED)
- Returns a value that indicates whether the program can be used (ENABLED) or not (DISABLED).
- CEDF_STATUS(CEDF|NOCEDF|NOT_APPLIC)
- Returns the execution diagnostic facility (EDF) status of the
program.
- CEDF
- When the program is running under the control of the CICS EDF, EDF diagnostic screens are displayed.
- NOCEDF
- EDF diagnostic screens are not displayed.
- NOT_APPLIC
- Not applicable. This module is a mapset, a partitionset, or a remote program.
- CONCURRENCY(QUASIRENT|THREADSAFE)
- Returns a value that indicates the concurrency attribute of the
installed program definition.
- 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 could be either an open TCB or the CICS QR TCB.
Note: For a Language Environment-conforming program, the concurrency as originally defined can be overridden when the program is subsequently loaded. - DATA_LOCATION(ANY|BELOW|NOT_APPLIC)
- Returns a value that indicates whether the program can access
data located above the 16 MB line.
- ANY
- The program can handle 31-bit addresses, and can be passed data that is located above or below the 16 MB line.
- BELOW
- The program can handle only 24-bit addresses, and must therefore be passed only data that is located below the 16 MB line.
- NOT_APPLIC
- Not applicable. This module is a mapset, a partitionset, or a remote program.
- DYNAMIC_STATUS(DYNAMIC|NOT_DYNAMIC)
- Returns a value that indicates whether, if the program is the
subject of a program-link request, the request can be dynamically
routed.
- 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 EXEC CICS LINK command, the routing program can route the request to the region on which the program is to run.
- NOT_DYNAMIC
- 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 EXEC CICS LINK command. Otherwise, it defaults to the local region.
For information about the dynamic routing of DPL requests, see Dynamically routing DPL requests.
- ENTRY_POINT(name4)
- Returns the entry point address of the program entry point address, as returned by a loader domain ACQUIRE_PROGRAM call.
- EXECUTION_KEY(CICS|NOT_APPLIC|USER)
- Returns the key in which CICS gives
control to the program, which determines whether the program can modify
CICS-key storage.
- CICS
- CICS gives control to the program in CICS key. The program is loaded into a CICS dynamic storage area (DSA) above or below the 16 MB line; that is, the CDSA or ECDSA, depending on its residency mode (RMODE) attribute, as defined to the linkage-editor.
- NOT_APPLIC
- Not applicable. This module is a mapset, a partitionset, or a remote program.
- USER
- CICS gives control to the program in user key. The program is loaded into a user DSA above or below the 16 MB line; that is, the UDSA or EUDSA, depending on its residency mode (RMODE) attribute, as defined to the linkage-editor.
- EXECUTION_SET(DPLSUBSET|FULLAPI|NOT_APPLIC)
- Returns a value that indicates whether CICS links to and runs the program as if it
were running in a remote CICS region.
- DPLSUBSET
- CICS links to and runs the program with the API restrictions of a remote DPL program. The program can use only a subset of the CICS API.
- FULLAPI
- CICS links to and runs the program without the API restrictions of a remote DPL program. The program can use the full CICS API.
- NOT_APPLIC
- Not applicable. This module is a mapset, a partitionset, or a remote program. (The EXECUTIONSET option of DEFINE PROGRAM applies only to local program definitions. Its purpose is to test programs in a local CICS environment as if they were running as DPL programs.)
- HOLD_STATUS(CICS_LIFE|NOT_APPLIC|TASK_LIFE)
- Returns a value that indicates how long the program is to remain
loaded.
- CICS_LIFE
- The program remains loaded until CICS is shut down.
- NOT_APPLIC
- Not applicable. The program is not loaded, or is remote.
- TASK_LIFE
- The program remains loaded for the lifetime of the task.
- INSTALL_TYPE(AUTO|CATALOG|GROUPLIST|MANUAL|RDO|SYSAUTO)
- Returns the method that was used to install the PROGRAM resource
definition.
- AUTO
- Autoinstall.
- CATALOG
- The CICS global catalog, after a restart.
- GROUPLIST
- The CICS startup grouplist.
- MANUAL
- The program is a CICS internal module explicitly defined to the Program Manager by another CICS component.
- RDO
- RDO commands.
- SYSAUTO
- System autoinstall (that is, autoinstalled by CICS without calling the autoinstall user program). The program might be a CICS internal module or, for example, a first phase PLTPI program.
- LANGUAGE_DEDUCED(ASSEMBLER|C370|COBOL|COBOL2|LE370| NOT_APPLIC|NOT_DEDUCED|PLI)
- Returns the language deduced by CICS for the program. COBOL is OS/VS COBOL, which cannot run under this CICS version, and COBOL2 is either Enterprise COBOL or VS COBOL II.
- LANGUAGE_DEFINED(ASSEMBLER|C370|COBOL|LE370| NOT_APPLIC|NOT_DEFINED|PLI)
- Returns the programming language specified on the resource definition.
- LIBRARY(name)
- Returns the 8-character name of the LIBRARY resource from which this program was loaded. This field 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).
- LIBRARYDSN(name44)
- Returns the 44-character name of the data set from which the program
was loaded. This field 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 will be returned.
- If the program was loaded from a LIBRARY that has been disabled, the LIBRARY name will be returned but the LIBRARYDSN will be blank.
- If the program was loaded from a LIBRARY that has been discarded, both LIBRARY and LIBRARYDSN will be blank.
- LOAD_POINT(name4)
- Returns the load point address of the program, as returned by a loader domain ACQUIRE_PROGRAM call.
- LOAD_STATUS(LOADABLE|NOT_APPLIC|NOT_LOADABLE|NOT_LOADED)
- Returns a value that indicates whether or not the program can
be loaded.
- LOADABLE
- The program is loadable.
- NOT_APPLIC
- Not applicable. The program is remote.
- NOT_LOADABLE
- CICS has tried to load the program and failed; the program is not in the library.
- NOT_LOADED
- CICS has not yet tried to load the program.
- LOCATION(CDSA|ECDSA|ELPA|ERDSA|ESDSA|LPA|NONE|RDSA|SDSA)
- Returns a value that indicates where the most recently loaded
copy of the program resides.
- CDSA
- The CICS dynamic storage area
- ECDSA
- The extended CICS dynamic storage area
- ELPA
- The extended link pack area
- ERDSA
- The extended read-only dynamic storage area
- ESDSA
- The extended shared dynamic storage area
- LPA
- The link pack area
- NONE
- The program has not been loaded.
- RDSA
- The read-only dynamic storage area
- SDSA
- The shared dynamic storage area
- MODULE_TYPE(MAPSET|PARTITIONSET|PROGRAM)
- Returns the type of program resource.
- NEW_PROGRAM_TOKEN(name4)
- Returns a token that can be used to identify the named program.
- name4
- The name of a location to receive a 4-byte token that identifies this program.
If PROGRAM_NAME is specified on the request, NEW_PROGRAM_TOKEN is set to a program token that can be used on subsequent requests for the same program. If PROGRAM_TOKEN is specified on the request, NEW_PROGRAM_TOKEN is set to the same value.
- PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT)
- Returns the residency status of the program; that is, when its
storage is released.
- RELOAD
- The program is not reusable, and therefore several copies might be loaded. A copy is removed from storage when a RELEASE_PROGRAM call (for that copy) is issued.
- RESIDENT
- There is a single copy of the program that is not removed from storage unless deleted. RESIDENT programs must be at least quasi-reentrant. Any program of PROGRAM_TYPE SHARED is RESIDENT by default.
- REUSABLE
- Similar to RESIDENT, except that CICS can remove a REUSABLE program that is not in use from storage, for storage optimization reasons.
- TRANSIENT
- Similar to RESIDENT, except that a TRANSIENT program is removed from storage as soon as its user count drops to zero.
- PROGRAM_LENGTH(name4)
- Returns the length of the program, in bytes, expressed in binary.
- PROGRAM_NAME(name8 | string | 'string')
- Specifies the name of the program to be queried.
- name8
- The name of a location that contains an 8-byte program name.
- string
- A string of characters that name the program.
- 'string'
- A string of characters in quotation marks. The string length is set to 8 by padding with blanks or truncating.
- PROGRAM_TOKEN(name4)
- Specifies a token that identifies the program to be queried.
- name4
- The name of a location that contains a 4-byte token that was obtained from a previous INQUIRE_PROGRAM call.
- PROGRAM_TYPE(NOT_APPLIC|PRIVATE|SHARED|TYPE_ANY)
- Returns a value that indicates where the next new copy of the
program is to be loaded from.
- NOT_APPLIC
- Not applicable. The program is remote.
- PRIVATE
- The program is to be loaded from the DFHRPL or dynamic LIBRARY concatenation.. A PRIVATE program need not be reentrant, and is given only limited protection against unauthorized overwriting. The degree of protection depends on the type of dynamic storage area into which the program is loaded (see the description of the PROGRAM_TYPE option of the DEFINE_PROGRAM call).
- SHARED
- The program is to be loaded from the link pack area (LPA). SHARED
programs must be reentrant, and are protected.
The next time a NEWCOPY or PHASEIN is received, an LPA copy of the program is used if it is available. If no LPA version is available, the program is loaded from DFHRPL or dynamic LIBRARY concatenation.
- TYPE_ANY
- Either the copy in DFHRPL or a dynamic LIBRARY concatenation, or the LPA copy of the program can be used, although preference is given to the LPA copy.
- PROGRAM_USAGE(APPLICATION|NUCLEUS)
- Returns a value that indicates whether the program is used as a CICS nucleus program, or as a user application program.
- PROGRAM_USE_COUNT(name4)
- Returns the number of different users that have invoked the program.
- PROGRAM_USER_COUNT(name4)
- Returns the current number of users of the program.
- REMOTE_DEFINITION(LOCAL|REMOTE)
- Returns a value that indicates whether this program is a local or a remote resource. If it is a remote resource, CICS treats requests to link to the program as distributed program link (DPL) requests, and ships them to the remote region.
- REMOTE_PROGID(name8)
- Returns the name by which the program is known in the remote CICS region, if the program is a remote resource. If REMOTESYSTEM was specified on the PROGRAM definition, and REMOTENAME omitted, the remote name will be the same as the local name (that is, REMOTE_PROGID will default to the value of PROGRAM_NAME).
- REMOTE_SYSID(name4)
- Returns the name of the remote CICS region that owns the program, if the program is a remote resource.
- REMOTE_TRANID(name4)
- Returns the name of the transaction that the remote CICS attaches, and under which it runs the program, if the program is a remote resource.
- SHOW_PROGRAMS(PRIVATE|PRIVATE_AND_PUBLIC)
- If application context fields are specified for INQUIRE_PROGRAM,
SHOW_PROGRAMS defines the scope of the search.
- PRIVATE
- Searches only for private programs.
- PRIVATE_AND_PUBLIC
- Searches for private programs first, then public programs.
- SPECIFIED_AMODE(24|31|AMODE_ANY|AMODE_NOT_SPECIFIED|64)
- Returns the addressing mode that was specified on a DEFINE_PROGRAM call.
- SPECIFIED_RMODE(24|RMODE_ANY|RMODE_NOT_SPECIFIED)
- Returns the residency mode (that is, whether the program should be loaded above or below the 16 MB line) that was specified on a DEFINE_PROGRAM call.
RESPONSE and REASON values for INQUIRE_PROGRAM
| RESPONSE | REASON |
|---|---|
| OK | None |
| EXCEPTION | PROGRAM_NOT_DEFINED_TO_LD |
| PROGRAM_NOT_DEFINED_TO_PG | |
| APP_CONTEXT_NOT_FOUND | |
| DISASTER | ABEND |
| LOCK_ERROR | |
| INVALID | INVALID_PROGRAM_TOKEN |
| KERNERROR | None |
| PURGED | None |