There are eight XPI program management functions. These are the DFHPGISX
calls:
- INQUIRE_PROGRAM
- INQUIRE_CURRENT_PROGRAM
- SET_PROGRAM
- START_BROWSE_PROGRAM
- GET_NEXT_PROGRAM
- END_BROWSE_PROGRAM
and the DFHPGAQX calls:
- INQUIRE_AUTOINSTALL
- SET_AUTOINSTALL
Used with the Loader functions DEFINE_PROGRAM, ACQUIRE_PROGRAM, RELEASE_PROGRAM,
and DELETE_PROGRAM, these calls give you a comprehensive set of tools for
manipulating programs. (Note, however, that the tokens returned in the NEW_PROGRAM_TOKEN
fields of DFHPGISX calls are different from those returned by DFHLDLDX Loader
calls. You should not use a token obtained from a DFHPGISX call in a DFHLDLDX
call, or vice versa.)
INQUIRE_PROGRAM returns information about the attributes of a specified
program.
INQUIRE_PROGRAM
DFHPGISX [CALL,]
[CLEAR,]
[IN,
FUNCTION(INQUIRE_PROGRAM),
{PROGRAM_NAME(name8 | string | 'string')|
PROGRAM_TOKEN(name4)},]
[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),]
[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),]
[SPECIFIED_RMODE(24|RMODE_ANY|RMODE_NOT_SPECIFIED),]
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- ACCESS(CICS|NONE|READ_ONLY|USER)
- returns a value indicating the type of storage into which the program
has been loaded.
- CICS®
- CICS-key
- NONE
- The program has not been loaded
- READ_ONLY
- Readonly
- USER
- User-key.
APIST(CICSAPI|OPENAPI)
returns a value indicating the API attribute of the installed program
definition.
- CICSAPI
- The program is restricted to use of the CICS permitted application programming
interfaces only.
- OPENAPI
- The program is not restricted to use of the CICS permitted application
programming interfaces only. It must be coded to threadsafe standards and
defined with CONCURRENCY(THREADSAFE).
- AVAIL_STATUS(DISABLED|ENABLED)
- returns a value indicating whether the program can be used--that
is, whether or not it has been enabled.
- CEDF_STATUS(CEDF|NOCEDF|NOT_APPLIC)
- returns the EDF status of the program.
- CEDF
- When the program is running under the control of the CICS execution diagnostic
facility (EDF), EDF diagnostic screens are displayed.
- NOCEDF
- EDF diagnostic screens are not displayed.
- NOT_APPLIC
- Not applicable. This is a mapset, partitionset, or a remote program.
CONCURRENCY(QUASIRENT|THREADSAFE)
returns a value indicating the concurrency attribute of the installed
program definition.
- 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.
Note:
In the case of 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 indicating whether or not the program can access data
located above the 16MB line.
- ANY
- The program can handle 31-bit addresses, and can therefore be passed
data located above or below the 16MB line.
- BELOW
- The program can handle only 24-bit addresses, and must therefore only
be passed data located below the 16MB line.
- NOT_APPLIC
- Not applicable. This is a mapset, partitionset, or a remote program.
- DYNAMIC_STATUS(DYNAMIC|NOT_DYNAMIC)
- returns a value indicating 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 execute.
- 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 execute 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 the CICS Intercommunication Guide.
- ENTRY_POINT(name4)
- returns the program’s entry point address, as it would be 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 16MB 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 is a mapset, 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 16MB 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 indicating 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 is a mapset, 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 indicating 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 may 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.
- LANGUAGE_DEFINED(ASSEMBLER|C370|COBOL|LE370| NOT_APPLIC|NOT_DEFINED|PLI)
- returns the programming language specified on the resource definition.
- LOAD_POINT(name4)
- returns the program’s load point address, as it would be returned
by a Loader domain ACQUIRE_PROGRAM call.
- LOAD_STATUS(LOADABLE|NOT_APPLIC|NOT_LOADABLE|NOT_LOADED)
- returns a value indicating 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 indicating 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 readonly dynamic storage area
- ESDSA
- The extended shared dynamic storage area
- LPA
- The link pack area
- NONE
- The program has not been loaded.
- RDSA
- The readonly dynamic storage area
- SDSA
- The shared dynamic storage area
- MODULE_TYPE(MAPSET|PARTITIONSET|PROGRAM)
- returns the kind 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 may 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 quasireentrant. Any program
of PROGRAM_TYPE SHARED is RESIDENT by default.
- REUSABLE
- Similar to RESIDENT, except that a REUSABLE program that is not in use
can be removed from storage by CICS, 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 containing an 8-byte program name.
- string
- A string of characters naming 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 identifying the program to be queried.
- name4
- The name of a location containing a 4-byte token obtained from a previous
INQUIRE_PROGRAM call.
- PROGRAM_TYPE(NOT_APPLIC|PRIVATE|SHARED|TYPE_ANY)
- returns a value indicating 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 relocatable program library (RPL).
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.
- TYPE_ANY
- Either the RPL or the LPA copy of the program can be used, though preference
is given to the LPA copy.
- PROGRAM_USAGE(APPLICATION|NUCLEUS)
- returns a value indicating 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 indicating 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.
- SPECIFIED_AMODE(24|31|AMODE_ANY|AMODE_NOT_SPECIFIED)
- returns the addressing mode 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 16MB line) 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 |
DISASTER |
ABEND |
|
LOCK_ERROR |
INVALID |
INVALID_PROGRAM_TOKEN |
KERNERROR |
None |
PURGED |
None |
INQUIRE_CURRENT_PROGRAM returns information about the attributes of the
program that is currently running. If this call is issued from within a global
or task-related user exit, it returns the attributes of the global or task-related
user exit program itself.
INQUIRE_CURRENT_PROGRAM
DFHPGISX [CALL,]
[CLEAR,]
[IN,
FUNCTION(INQUIRE_CURRENT_PROGRAM),]
[OUT,
[AVAIL_STATUS(DISABLED|ENABLED),]
[CEDF_STATUS(CEDF|NOCEDF|NOT_APPLIC),]
[CURRENT_AMODE(24|31),]
[CURRENT_CEDF_STATUS(CEDF|NOCEDF),]
[CURRENT_ENTRY_POINT(name4),]
[CURRENT_ENVIRONMENT(EXEC|GLUE|PLT|SYSTEM|TRUE|URM),]
[CURRENT_EXECUTION_SET(DPLSUBSET|FULLAPI),]
[CURRENT_LOAD_POINT(name4),]
[CURRENT_PROGRAM_LENGTH(name4),]
[CURRENT_PROGRAM_NAME(name8),]
[DATA_LOCATION(ANY|BELOW|NOT_APPLIC),]
[DYNAMIC_STATUS(DYNAMIC|NOT_DYNAMIC),]
[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),]
[INVOKING_ENVIRONMENT (EXEC|GLUE|PLT|SYSTEM|TRUE|URM),]
[INVOKING_PROGRAM_NAME(name8),]
[LANGUAGE_DEDUCED(ASSEMBLER|C370|COBOL|
COBOL2|LE370|NOT_APPLIC|NOT_DEDUCED|PLI),]
[LANGUAGE_DEFINED(ASSEMBLER|C370|COBOL|
LE370|NOT_APPLIC|NOT_DEFINED|PLI),]
[LOAD_STATUS(LOADABLE|NOT_APPLIC|NOT_LOADABLE|NOT_LOADED),]
[MODULE_TYPE(MAPSET|PARTITIONSET|PROGRAM),]
[NEW_PROGRAM_TOKEN(name4),]
[REMOTE_DEFINITION(LOCAL|REMOTE),]
[REMOTE_PROGID(name8),]
[REMOTE_SYSID(name4),]
[REMOTE_TRANID(name4),]
[RETURN_PROGRAM_NAME(name8),]
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
Note:
The options not described in the following list are identical
to the equivalent options of the INQUIRE_PROGRAM call.
- CURRENT_AMODE(24|31)
- returns the addressing mode which the running program is currently using.
- CURRENT_CEDF_STATUS(CEDF|NOCEDF)
- returns the EDF status of the current instance of the program. The value
returned is the same as for CEDF_STATUS, which is the EDF status specified
on the program definition. See the CEDF_STATUS option of INQUIRE_PROGRAM.
- CURRENT_ENTRY_POINT(name4)
- returns the entry point address of the current program.
- CURRENT_ENVIRONMENT(EXEC|GLUE|PLT|SYSTEM|TRUE|URM)
- returns the environment in which the current program is running--that
is, the type of program it is.
- EXEC
- User application program
- GLUE
- Global user exit program
- PLT
- Program list table program
- SYSTEM
- CICS system code
- TRUE
- Task-related user exit program
- URM
- User-replaceable program.
- CURRENT_EXECUTION_SET(DPLSUBSET|FULLAPI)
- returns the API execution set used by the current instance of the program.
The value returned is the same as for EXECUTION_SET (which is the API execution
set specified on the program definition) unless this
is the first program in a transaction, when the value may be different. This
is because the DPLSUBSET attribute applies only to linked-to programs. It
is ignored for the first program in a transaction, because this cannot be
the target of a DPL call. Therefore, for the first program in a transaction,
if EXECUTION_SET returns DPLSUBSET, CURRENT_EXECUTION_SET nevertheless returns
FULLAPI. See the EXECUTION_SET option of INQUIRE_PROGRAM.
- CURRENT_LOAD_POINT(name4)
- returns the load point address of the current program.
- CURRENT_PROGRAM_LENGTH(name4)
- returns the length of the current program, in bytes, expressed in binary.
- CURRENT_PROGRAM_NAME(name8)
- returns the name of the program that is currently running.
- INVOKING_ENVIRONMENT (EXEC|GLUE|PLT|SYSTEM|TRUE|URM)
- returns the environment from which the current program was invoked.
The values are as described for CURRENT_ENVIRONMENT.
- INVOKING_PROGRAM_NAME(name8)
- returns the name of the most recent program that
was not a global user exit or task-related user exit program to invoke
the current program.
- RETURN_PROGRAM_NAME(name8)
- returns the name of the program to which control will be returned, after
any intermediate global user exit or task-related user exit programs have
completed.
RESPONSE and REASON values for INQUIRE_CURRENT_PROGRAM:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
NO_CURRENT_PROGRAM |
DISASTER |
LOCK_ERROR |
|
ABEND |
INVALID |
None |
KERNERROR |
None |
PURGED |
None |
SET_PROGRAM allows you to set selected attributes in the definition of
a specified program.
SET_PROGRAM
DFHPGISX [CALL,]
[CLEAR,]
[IN,
FUNCTION(SET_PROGRAM),
{PROGRAM_NAME(name8 | string | 'string')|
PROGRAM_TOKEN(name4)},]
[AVAIL_STATUS(DISABLED|ENABLED),]
[CEDF_STATUS(CEDF|NOCEDF),]
[EXECUTION_KEY(CICS|USER),]
[EXECUTION_SET(DPLSUBSET|FULLAPI),]
[PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT),]
[PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY),]
[PROGRAM_USAGE(APPLICATION|NUCLEUS),]
[REQUIRED_AMODE(24|31|AMODE_ANY),]
[REQUIRED_RMODE(24|RMODE_ANY),]]
[OUT,
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- AVAIL_STATUS(DISABLED|ENABLED)
- specifies whether the program can be used--that is, whether or
not it is enabled.
- CEDF_STATUS(CEDF|NOCEDF)
- specifies whether, when the program is running under the control of
the CICS execution diagnostic facility (EDF), EDF diagnostic screens are
displayed.
- EXECUTION_KEY(CICS|USER)
- specifies the key in which CICS is to give control to the program. The
key 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 16MB line; that is, the
CDSA or ECDSA, depending on its residency mode (RMODE) attribute as defined
to the linkage-editor.
- USER
- CICS gives control to the program in user key. The program is loaded
into a user DSA, above or below the 16MB line; that is, the UDSA or EUDSA,
depending on its residency mode (RMODE) attribute as defined to the linkage-editor.
Note:
If the program has been link-edited as reentrant with
AMODE(31),RMODE(ANY), the EXECUTION_KEY option is ignored, and it is loaded
into the extended readonly DSA (ERDSA). For details of the type of storage
allocated for the ERDSA, see the RENTPGM system initialization parameter.
- EXECUTION_SET(DPLSUBSET|FULLAPI)
- specifies whether CICS is to link to and run the program as if it were running
in a remote CICS region.
Note:
EXECUTION_SET 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.
- 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.
- PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT)
- specifies the residency status of the program--that is, when its
storage is to be released.
- RELOAD
- The program is not reusable, and therefore several copies may be loaded.
A copy is removed from storage when a RELEASE_PROGRAM call (for that copy)
is issued.
- RESIDENT
- At any one time there will be no more than a single copy of the program
in storage, and this will not be removed unless deleted. RESIDENT programs
must be at least quasireentrant. Any program of PROGRAM_TYPE SHARED is RESIDENT
by default.
- REUSABLE
- Similar to RESIDENT, except that a REUSABLE program that is not in use
can be removed from storage by CICS, 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_NAME(name8 | string | 'string')
- specifies the name of the program whose attributes are to be changed.
- name8
- The name of a location containing an 8-byte program name.
- string
- A string of characters naming 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 identifying the program.
- name4
- The name of a location containing a 4-byte token obtained from a previous
INQUIRE_PROGRAM, INQUIRE_CURRENT_PROGRAM, START_BROWSE_PROGRAM, or GET_NEXT_PROGRAM
call.
- PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY)
- specifies where the program is to be loaded from.
- PRIVATE
- The program is in the relocatable program library (RPL). 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 located in the link pack area (LPA), is reentrant, and
is protected.
- TYPE_ANY
- Either the RPL or the LPA copy of the program can be used, though preference
is given to the LPA copy.
- PROGRAM_USAGE(APPLICATION|NUCLEUS)
- specifies whether the program is used as a CICS nucleus program or as a user application
program.
- REQUIRED_AMODE(24|31|AMODE_ANY)
- specifies the addressing mode of the program. If, during subsequent
processing, no copy of the program that meets the defined addressing requirement
can be found, an exception occurs.
Notes:
- AMODE_ANY and 31 have identical meanings for this function.
- You cannot use this option to override the link-edited addressing mode
of the program.
- REQUIRED_RMODE(24|AMODE_ANY)
- specifies the residency mode of the program (that is, whether it is
to be loaded above or below the 16MB line). If, during subsequent processing,
no copy of the program that meets the defined residency requirement can be
found, an exception occurs.
Note:
You cannot use this option to
override the link-edited residency mode of the program.
RESPONSE and REASON values for SET_PROGRAM:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
CEDF_STATUS_NOT_FOR_MAPSET |
|
CEDF_STATUS_NOT_FOR_PTNSET |
|
CEDF_STATUS_NOT_FOR_REMOTE |
|
EXEC_KEY_NOT_FOR_MAPSET |
|
EXEC_KEY_NOT_FOR_PTNSET |
|
EXEC_KEY_NOT_FOR_REMOTE |
|
EXEC_SET_NOT_FOR_MAPSET |
|
EXEC_SET_NOT_FOR_PTNSET |
|
EXEC_SET_NOT_FOR_REMOTE |
|
PROGRAM_NOT_DEFINED_TO_LD |
|
PROGRAM_NOT_DEFINED_TO_PG |
DISASTER |
ABEND |
|
CATALOG_ERROR |
|
CATALOG_NOT_OPERATIONAL |
|
LOCK_ERROR |
INVALID |
INVALID_MODE_COMBINATION |
|
INVALID_PROGRAM_NAME |
|
INVALID_PROGRAM_TOKEN |
|
INVALID_TYPE_ATTRIB_COMBIN |
KERNERROR |
None |
PURGED |
None |
START_BROWSE_PROGRAM returns a token that enables you to begin browsing
through program definitions, optionally starting at the definition of a specified
program.
START_BROWSE_PROGRAM
DFHPGISX [CALL,]
[CLEAR,]
[IN,
FUNCTION(START_BROWSE_PROGRAM),
[PROGRAM_NAME(name8 | string | 'string'),]]
[OUT,
BROWSE_TOKEN(name4)
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- BROWSE_TOKEN(name4)
- returns a token to be used on a GET_NEXT_PROGRAM call, to initiate a
sequential browse of program definitions.
- name4
- The name of a location to receive a 4-byte token.
- PROGRAM_NAME(name8 | string | 'string')
- specifies the name of the program whose definition you want to look
at first. The browsing sequence is alphabetical.
If there is no program with the specified name, CICS returns a token for the next definition
in the alphabetic sequence. If you do not specify a program, CICS returns a token
for the first definition.
- name8
- The name of a location containing an 8-byte program name.
- string
- A string of characters naming the program.
- 'string'
- A string of characters in quotation marks. The string length is set
to 8 by padding with blanks or truncating.
RESPONSE and REASON values for START_BROWSE_PROGRAM:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
None |
DISASTER |
ABEND |
|
INVALID_DIRECTORY |
|
LOCK_ERROR |
INVALID |
None |
KERNERROR |
None |
PURGED |
None |
GET_NEXT_PROGRAM allows you to inquire on the next program definition during
a browse sequence initiated by START_BROWSE_PROGRAM. The browsing sequence
is alphabetical. The end of the alphabetic list of definitions is indicated
by an 'END_LIST' exception response.
GET_NEXT_PROGRAM
DFHPGISX [CALL,]
[CLEAR,]
[IN,
FUNCTION(GET_NEXT_PROGRAM),
BROWSE_TOKEN(name4),]
[OUT,
PROGRAM_NAME(name8),
[ACCESS(CICS|NONE|READ_ONLY|USER),]
[AVAIL_STATUS(DISABLED|ENABLED),]
[CEDF_STATUS(CEDF|NOCEDF|NOT_APPLIC),]
[DATA_LOCATION(ANY|BELOW|NOT_APPLIC),]
[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),]
[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),]
[SPECIFIED_RMODE(24|RMODE_ANY|RMODE_NOT_SPECIFIED),]
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
Note:
The options not described in the following list are identical
to the equivalent options of the INQUIRE_PROGRAM call.
- BROWSE_TOKEN(name4)
- specifies a token identifying the definition to be browsed. This can
be either the token returned in the NEW_PROGRAM_TOKEN field of the last GET_NEXT_PROGRAM
call, or that in the BROWSE_TOKEN field of the START_BROWSE_PROGRAM call (this
token is updated after every GET_PROGRAM call).
- name4
- The name of a location containing a 4-byte token.
- NEW_PROGRAM_TOKEN(name4)
- returns a token that identifies the next definition in the browse sequence.
You can use it in the BROWSE_TOKEN field of your next GET_NEXT_PROGRAM call
(or END_BROWSE_PROGRAM call, if you want to end the sequence). You can also
use it in the PROGRAM_TOKEN field of INQUIRE_PROGRAM and SET_PROGRAM calls.
- name4
- The name of a location to receive a 4-byte token that identifies the
next program definition.
RESPONSE and REASON values for GET_NEXT_PROGRAM:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
END_LIST |
|
INVALID_BROWSE_TOKEN |
|
PROGRAM_NOT_DEFINED_TO_LD |
DISASTER |
ABEND |
|
LOCK_ERROR |
INVALID |
None |
KERNERROR |
None |
PURGED |
None |
END_BROWSE_PROGRAM allows you to end a browse of program definitions initiated
by START_BROWSE_PROGRAM.
END_BROWSE_PROGRAM
DFHPGISX [CALL,]
[CLEAR,]
[IN,
FUNCTION(END_BROWSE_PROGRAM),
BROWSE_TOKEN(name4),]
[OUT,
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- BROWSE_TOKEN(name4)
- specifies either the token returned in the NEW_PROGRAM_TOKEN field of
the last GET_NEXT_PROGRAM call, or that in the BROWSE_TOKEN field of the START_BROWSE_PROGRAM
call (this token is updated after every GET_NEXT_PROGRAM call).
RESPONSE and REASON values for END_BROWSE_PROGRAM:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
INVALID_BROWSE_TOKEN |
DISASTER |
ABEND |
|
LOCK_ERROR |
INVALID |
None |
KERNERROR |
None |
PURGED |
None |
INQUIRE_AUTOINSTALL returns information about the current settings of the
autoinstall function for programs, mapsets, and partitionsets.
INQUIRE_AUTOINSTALL
DFHPGAQX [CALL,]
[CLEAR,]
[IN,
FUNCTION(INQUIRE_AUTOINSTALL),]
[OUT,
[AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),]
[AUTOINSTALL_EXIT_NAME(name8),]
[AUTOINSTALL_STATE (ACTIVE|INACTIVE),]
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- AUTOINSTALL_CATALOG(ALL|MODIFY|NONE)
- returns the catalog status for autoinstalled program definitions.
- ALL
- All autoinstalled program, map, and partitionset definitions are cataloged.
- MODIFY
- Autoinstalled program, map, and partitionset definitions are recorded
on the CICS global catalog only if they are modified by a SET PROGRAM command
after being autoinstalled.
- NONE
- No autoinstalled program, map, or partitionset definitions are cataloged.
- AUTOINSTALL_EXIT_NAME(name8)
- returns the name of the user-replaceable autoinstall control program
for programs, mapsets, and partitionsets.
- AUTOINSTALL_STATE(ACTIVE|INACTIVE)
- returns the status of the program autoinstall function.
- ACTIVE
- Autoinstall is enabled for programs, mapsets, and partitionsets.
- INACTIVE
- Autoinstall is not enabled for programs, mapsets, and partitionsets.
RESPONSE and REASON values for INQUIRE_AUTOINSTALL:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
None |
DISASTER |
None |
INVALID |
INVALID_FUNCTION |
KERNERROR |
None |
PURGED |
None |
SET_AUTOINSTALL enables you to change the settings of the autoinstall function
for programs, mapsets, and partitionsets.
SET_AUTOINSTALL
DFHPGAQX [CALL,]
[CLEAR,]
[IN,
FUNCTION(SET_AUTOINSTALL),
[AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),]
[AUTOINSTALL_EXIT_NAME(name8),]
[AUTOINSTALL_STATE (ACTIVE|INACTIVE),]
[LANGUAGES_AVAILABLE(NO|YES),]]
[OUT,
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- AUTOINSTALL_CATALOG(ALL|MODIFY|NONE)
- specifies the catalog status for autoinstalled program definitions.
- ALL
- All autoinstalled program, map, and partitionset definitions are to
be cataloged.
- MODIFY
- Autoinstalled program, map, and partitionset definitions are to be recorded
on the CICS global catalog only if they are modified by a SET PROGRAM command
after being autoinstalled.
- NONE
- No autoinstalled program, map, or partitionset definitions are to be
cataloged.
- AUTOINSTALL_EXIT_NAME(name8)
- specifies the name of the user-replaceable autoinstall control program
for programs, mapsets, and partitionsets.
- AUTOINSTALL_STATE(ACTIVE|INACTIVE)
- specifies the status of the program autoinstall function.
- ACTIVE
- Enable autoinstall for programs, mapsets, and partitionsets.
- INACTIVE
- Disable autoinstall for programs, mapsets, and partitionsets.
- LANGUAGES_AVAILABLE(NO|YES)
- specifies whether the autoinstall control program can be called. It
can only be called after language establishment.
- NO
- The control program cannot be called.
- YES
- The control program can be called.
RESPONSE and REASON values for SET_AUTOINSTALL:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
None |
DISASTER |
None |
INVALID |
INVALID_FUNCTION |
KERNERROR |
None |
PURGED |
None |
[[ Contents Previous Page | Next Page Index ]]