There are four XPI loader functions. These are the DFHLDLDX calls ACQUIRE_PROGRAM,
RELEASE_PROGRAM, DEFINE_PROGRAM, and DELETE_PROGRAM.
DFHLDLDX calls cannot be used in any exit program
invoked from any global user exit point in the:
- Statistics domain
- Monitor domain
- Dump domain
- Dispatcher domain
- Transient data program.
DEFINE_PROGRAM allows you to define new programs to the loader domain,
or to change the details of programs that have already been defined. The
details that you provide are recorded on the local catalog, and become immediately
available. They are used on all subsequent ACQUIRE requests for the named
program. However, note that program definitions made in this way are not retained over an XRF takeover. Also, the CSD is not updated, only the loader domain definitions.
DEFINE_PROGRAM
DFHLDLDX [CALL,]
[CLEAR,]
[IN,
FUNCTION(DEFINE_PROGRAM),
PROGRAM_NAME(name8 | string | 'string' ),
[EXECUTION_KEY(CICS|USER),]
[PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT),]
[PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY),]
[REQUIRED_AMODE(24|31|AMODE_ANY),]
[REQUIRED_RMODE(24|RMODE_ANY),]]
[OUT,
[NEW_PROGRAM_TOKEN(name4),]
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- EXECUTION_KEY(CICS|USER)
- specifies, in conjunction with other program attributes, the type of
dynamic storage area (DSA) into which the loader is to load the program.
- CICS®
- For non-reentrant programs, means that the program is to be loaded into
a CICS DSA, above or below the 16MB line; that is, the CDSA or ECDSA. The
choice of CICS DSA is dependent on the residence mode (RMODE) attribute of the
program as defined to the linkage-editor.
For reentrant RMODE(24) programs,
means that the program is to be loaded into the CDSA.
- USER
- For non-reentrant programs, means that the program is to be loaded into
a user DSA, above or below the 16MB line; that is, the UDSA or EUDSA. The
choice of user DSA is dependent on the residence mode (RMODE) attribute of
the program as defined to the linkage-editor.
For reentrant RMODE(24) programs,
means that the program is to be loaded into the UDSA.
Reentrant programs eligible to reside above the
16MB line: If a program is link-edited as reentrant with AMODE(31),RMODE(ANY),
the EXECUTION_KEY option is ignored, and it is loaded into a read-only DSA
(the RDSA or ERDSA). For details of the type of storage allocated for the
ERDSA, see the RENTPGM system initialization parameter.
See Table 19 for
a summary of the effect of the EXECUTION_KEY option in conjunction with other
factors.
Table 19. Summary of attributes defining DSA eligibility
EXECUTION_KEY option |
Reentrant |
Above or below 16MB line |
Dynamic storage area (DSA) |
CICS |
No |
Below |
CDSA |
CICS |
Yes |
Below |
RDSA |
CICS |
No |
Above |
ECDSA |
CICS |
Yes |
Above |
ERDSA |
USER |
No |
Below |
UDSA |
USER |
Yes |
Below |
RDSA |
USER |
No |
Above |
EUDSA |
USER |
Yes |
Above |
ERDSA |
- NEW_PROGRAM_TOKEN(name4)
- returns the token supplied for the newly-defined program.
- name4
- The name of a location to contain the 4-byte token obtained.
- PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT)
- specifies the residency status of the program.
- RELOAD
- Every ACQUIRE_PROGRAM request for this program is satisfied by loading
a new copy into storage. When a RELEASE request is issued for a copy, it is
removed from storage.
Note:
Do not use this attribute when
defining an exit program.
- RESIDENT
- There is a single copy of the program that is not removed from storage
unless deleted. RESIDENT programs must be at least quasireentrant.
- REUSABLE
- The program is at least quasireentrant; a single copy in storage can
be used by several tasks in the system. A REUSABLE program becomes eligible
for removal from storage as part of the normal dynamic program compression
scheme when its use count reaches zero.
- TRANSIENT
- Similar to REUSABLE, except that the program is removed from storage
immediately its use count reaches zero. This should be specified only for
less-frequently used programs, or for programs in systems that are critically
short on storage.
- PROGRAM_NAME(name8 | string | "string")
- specifies the name of the program to be defined.
- name8
- The name of a location where there is an 8-byte program name.
- string
- A string of characters, without intervening blanks, naming the program.
- "string"
- A string of characters within quotation marks. The string length is
set to 8 by padding with blanks or by truncation.
- PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY)
- specifies where to load the program from.
- PRIVATE
- The program is in the relocatable program library (RPL). A PRIVATE program need not be reentrant, and is given only limited protection
from unauthorized overwriting. The degree of protection depends on the type
of dynamic storage area (DSA) into which the program is loaded (see the EXECUTION_KEY
option):
- DSA
- Protection from unauthorized overwriting
- CDSA
- Cannot be overwritten by USER tasks
- ECDSA
- Cannot be overwritten by USER tasks
- ERDSA
- Complete--cannot be overwritten by USER tasks or CICS tasks
- EUDSA
- None
- RDSA
- Complete--cannot be overwritten by USER tasks or CICS tasks
- UDSA
- None.
- 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 may be used, though preference
is given to the LPA copy.
- REQUIRED_AMODE(24|31|AMODE_ANY)
- specifies the addressing mode of the program. If, during subsequent
ACQUIRE_PROGRAM processing, no copy of the program that meets the defined
addressing requirement can be found, the ACQUIRE_PROGRAM call receives an ‘EXCEPTION’
response and the REASON value ‘PROGRAM_NOT_FOUND’.
Notes:
- AMODE_ANY and AMODE 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|RMODE_ANY)
- specifies the residency mode of the program. If, during subsequent ACQUIRE_PROGRAM
processing, no copy of the program that meets the defined addressing requirement
can be found, the ACQUIRE_PROGRAM call receives an ‘EXCEPTION’ response
and the REASON value ‘PROGRAM_NOT_FOUND’.
Note:
You cannot use this option to override the link-edited residence
mode of the program.
RESPONSE and REASON values for DEFINE_PROGRAM:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
CATALOG_ERROR |
|
CATALOG_NOT_OPERATIONAL |
DISASTER |
None |
INVALID |
None |
KERNERROR |
None |
PURGED |
None |
Note:
For more detail, refer to the explanation of RESPONSE and
REASON in
Making an XPI call.
ACQUIRE_PROGRAM returns the entry and load point addresses, the length,
and a new program token for a usable copy of the named program, which can
be identified by either its name or a program token.
ACQUIRE_PROGRAM
DFHLDLDX [CALL,]
[CLEAR,]
[IN,
FUNCTION(ACQUIRE_PROGRAM),
{PROGRAM_NAME(name8 | string | 'string')|
PROGRAM_TOKEN(name4)},
[SUSPEND(NO|YES),]]
[OUT,
ENTRY_POINT(name4 | (Ra)),
[LOAD_POINT(name4 | (Ra)),]
[NEW_PROGRAM_TOKEN(name4),]
[PROGRAM_ATTRIBUTE(name1 | (Rn)),]
[PROGRAM_LENGTH(name4 | (Rn)),]
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- ENTRY_POINT(name4 | (Ra))
- returns the program’s entry point address.
- name4
- The name of a 4-byte location to receive the 31-bit entry address
- (Ra)
- A register to receive the entry address.
- LOAD_POINT(name4 | (Ra))
- returns the program’s load point address.
- name4
- The name of a 4-byte location to receive the loaded address
- (Ra)
- A register that is to contain the load address.
- NEW_PROGRAM_TOKEN(name4)
- returns the new program token for a usable copy of the named program.
- name4
- The name of a location to receive a 4-byte token that identifies this
program and instance.
- PROGRAM_ATTRIBUTE(name1 | (Rn))
- returns the program attribute.
- name1
- The name of a 1-byte location to receive the program attribute.
- (Rn)
- A register in which the low-order byte receives the program attribute
and the other bytes are set to zero. It can have the values RELOAD, RESIDENT,
REUSABLE, or TRANSIENT.
- RELOAD
- The program is not reusable, and therefore several copies of the program
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 has the RESIDENT attribute by default. The
DELETE_PROGRAM call has no effect on this type of RESIDENT program.
- 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 use count drops to zero.
- PROGRAM_LENGTH(name4 | (Rn))
- returns the length of the named program.
- name4
- The name of a 4-byte location that is to receive the length in bytes,
expressed in binary
- (Rn)
- A register to contain the length in bytes, expressed in binary.
- PROGRAM_NAME(name8 | string | "string")
- specifies the name of the program to be acquired.
- name8
- The name of a location containing an 8-byte program name.
- string
- A string of characters naming the program.
- "string"
- A string 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 whose details are to be acquired.
- name4
- The name of a location containing a 4-byte token obtained by a previous
DEFINE_PROGRAM or ACQUIRE_PROGRAM call.
- SUSPEND(NO|YES)
- specifies whether execution is to be suspended until the request can
be granted.
RESPONSE and REASON values for ACQUIRE_PROGRAM:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
NO_STORAGE |
|
PROGRAM_NOT_DEFINED |
|
PROGRAM_NOT_FOUND |
DISASTER |
None |
INVALID |
None |
KERNERROR |
None |
PURGED |
None |
Notes:
- For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
- A REASON of ‘NO_STORAGE’ with a RESPONSE of ‘EXCEPTION’
means that there was insufficient storage to satisfy this request, and SUSPEND(NO)
was specified.
- A REASON of ‘PROGRAM_NOT_FOUND’ is returned if the program has
not been included in the library concatenation, or if the link-edit failed.
In such a case, the program is marked as "not executable"; it must
be re-linked before it can be successfully acquired.
RELEASE_PROGRAM decrements the use count of a currently loaded program
by one.
If the program has been defined with the RELOAD attribute, the storage
occupied by this copy of the program is released.
You should issue the ACQUIRE_PROGRAM and RELEASE_PROGRAM requests for a
single program during the same execution of the exit program. If you do not
want to do this, you should acquire the program once during CICS initialization,
and leave it resident until CICS termination.
RELEASE_PROGRAM
DFHLDLDX [CALL,]
[CLEAR,]
[IN,
FUNCTION(RELEASE_PROGRAM),
ENTRY_POINT(pointer),
{PROGRAM_NAME(name8 | string | 'string')|
PROGRAM_TOKEN(name4)},]
[OUT,
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- ENTRY_POINT(pointer)
- specifies the address of the entry point of this copy of the named program.
- PROGRAM_NAME(name8 | string | "string")
- specifies the name of the program to be released.
- name8
- The name of a location containing an 8-byte program name.
- string
- A string of characters naming the program.
- "string"
- A string 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 released.
- name4
- The name of a location containing an 4-byte token obtained by a previous
DEFINE_PROGRAM or ACQUIRE_PROGRAM call.
RESPONSE and REASON values for RELEASE_PROGRAM:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
PROGRAM_NOT_DEFINED |
|
PROGRAM_NOT_IN_USE |
DISASTER |
None |
INVALID |
None |
KERNERROR |
None |
PURGED |
None |
Notes:
- For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
- ‘PROGRAM_NOT_DEFINED’ is returned if the program that you name
is not known to the system.
- ‘PROGRAM_NOT_IN_USE’ is returned when the use count for the named
program is already zero.
DELETE_PROGRAM removes the definition of a named program from the catalog
and from the list of current programs. When this request executes successfully,
subsequent ACQUIRE_PROGRAM requests fail with a REASON value of ‘PROGRAM_NOT_DEFINED’.
DELETE_PROGRAM
DFHLDLDX [CALL,]
[CLEAR,]
[IN,
FUNCTION(DELETE_PROGRAM),
PROGRAM_NAME(name8 | string | 'string' ),]
[OUT,
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- PROGRAM_NAME(name8 | string | "string")
- specifies the name of the program to be deleted.
- name8
- The name of a location containing an 8-byte program name.
- string
- A string of characters naming the program.
- "string"
- A string in quotation marks. The string length is set to 8 by padding
with blanks or truncating.
RESPONSE and REASON values for DELETE_PROGRAM:
RESPONSE |
REASON |
OK |
None |
EXCEPTION |
PROGRAM_NOT_DEFINED |
DISASTER |
None |
INVALID |
None |
KERNERROR |
None |
PURGED |
None |
Note:
For more detail, refer to the explanation of RESPONSE and
REASON in
Making an XPI call.
[[ Contents Previous Page | Next Page Index ]]