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(name8)},
[SUSPEND(NO|YES),]]
[OUT,
ENTRY_POINT(name4 | (Ra)),
[LOAD_POINT(name4 | (Ra)),]
[NEW_PROGRAM_TOKEN(name8),]
[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(name8)
- Returns the new program token for a usable copy of the named program.
- name8
- The name of a location to receive the 8-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(name8),
- Specifies a token identifying the program whose details are to
be acquired.
- name8
- The name of a location containing the 8-byte token obtained from 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 |
Note:
- 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.