Program management XPI functions

There are eight XPI program management functions. These are the DFHPGISX calls:

and the DFHPGAQX calls:

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

The INQUIRE_PROGRAM call

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 | *)]

Start of changeThis command is threadsafe.End of change

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.
Start of changeAPIST(CICSAPI|OPENAPI)End of change
Start of changereturns 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).
End of change
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.
Start of changeCONCURRENCY(QUASIRENT|THREADSAFE)End of change
Start of changereturns 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.
End of change
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

The INQUIRE_CURRENT_PROGRAM call

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 | *)]

Start of changeThis command is threadsafe.End of change

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

The SET_PROGRAM call

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 | *)]

Start of changeThis command is threadsafe.End of change

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:
  1. AMODE_ANY and 31 have identical meanings for this function.
  2. 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

The START_BROWSE_PROGRAM call

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 | *)]

Start of changeThis command is threadsafe.End of change

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

The GET_NEXT_PROGRAM call

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 | *)]

Start of changeThis command is threadsafe.End of change

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

The END_BROWSE_PROGRAM call

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 | *)]

Start of changeThis command is threadsafe.End of change

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

The INQUIRE_AUTOINSTALL call

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 | *)]

Start of changeThis command is threadsafe.End of change

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

The SET_AUTOINSTALL call

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 | *)]

Start of changeThis command is threadsafe.End of change

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

Related concepts
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Making an XPI call
Writing global user exit programs
Writing a task-related user exit program
Related reference
The XPI functions
[[ Contents Previous Page | Next Page Index ]]