Loader XPI functions

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:

The DEFINE_PROGRAM call

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

Start of changeThis command is threadsafe.End of change

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:
  1. AMODE_ANY and AMODE 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|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.

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

Start of changeThis command is threadsafe.End of change

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:
  1. For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
  2. 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.
  3. 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.

The RELEASE_PROGRAM call

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

Start of changeThis command is threadsafe.End of change

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:
  1. For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
  2. ‘PROGRAM_NOT_DEFINED’ is returned if the program that you name is not known to the system.
  3. ‘PROGRAM_NOT_IN_USE’ is returned when the use count for the named program is already zero.

The DELETE_PROGRAM call

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

Start of changeThis command is threadsafe.End of change

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.

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