LDLD gate, ACQUIRE_PROGRAM function
The ACQUIRE_PROGRAM function of the LDLD gate is used to obtain the entry point and load point addresses and the length of a usable copy of the named program. The program must previously have been identified to the system in a DEFINE request, either during this session or in a previous session, if the catalog is in use.
Input Parameters
- APPL_CONTEXT_TOKEN
- Optional parameter
- A token representing the application context of PLATFORM_ID, APPLICATION_ID, APPL_MAJOR_VER, APPL_MINOR_VER, and APPL_MICRO_VER.
- APPLICATION_ID
- Optional parameter
- The 64-character name of the application associated with the task.
- APPL_MAJOR_VER
- Optional parameter
- The fullword binary value that is the major version of the application associated with the task.
- APPL_MINOR_VER
- Optional parameter
- The fullword binary value that is the minor version of the application associated with the task.
- APPL_MICRO_VER
- Optional parameter
- The fullword binary value that is the micro version of the application associated with the task.
- PLATFORM_ID
- Optional parameter
- The 64-character name of the platform associated with the task.
- PROGRAM_NAME
- The name of the required program.
- PROGRAM_TOKEN
- A valid program-identifying token as returned by a previous DEFINE or ACQUIRE request for the same program name.
- SUSPEND
- Optional Parameter
- Whether the caller expects to receive control with an exception response if the loader encounters a shortage of virtual storage, or other transient error conditions. If there is insufficient storage to satisfy the request, SUSPEND(YES) causes the caller to be suspended until the request can be satisfied, and SUSPEND(NO) causes an exception response (reason NO_STORAGE) to be returned to the caller.
- Values for the parameter are:
- NO
- YES
Output Parameters
- REASON
- The following values are returned when RESPONSE is DISASTER:
- ABEND
- LIBRARY_IO_ERROR
- LOOP
- OS_STORAGE_SHORTAGE
- The following values are returned when RESPONSE is EXCEPTION:
- NO_STORAGE
- The following values are returned when RESPONSE is EXCEPTION:
- PROGRAM_NOT_DEFINED
- PROGRAM_NOT_FOUND
- The following values are returned when RESPONSE is INVALID:
- INVALID_PROGRAM_TOKEN
- RESPONSE
- Whether the domain call was successful. For more information, see RESPONSE parameter on domain interfaces.
- COPY_STATUS
- Optional Parameter
- Whether this request resulted in a physical load of the program into storage, and is used by the program manager domain to recognize that a COBOL program requires initialization.
- Values for the parameter are:
- NEW_COPY
- OLD_COPY
- ENTRY_POINT
- The address of the entry point of the program instance.
- FETCH_TIME
- Optional Parameter
- The time taken to load the program from the DFHRPL or dynamic LIBRARY concatenation. This is represented as the middle 4 bytes of a doubleword stored clock (STCK) value. If the acquired program resides in the MVS™ link pack area (LPA) or has already been loaded into one of the CICS® dynamic storage areas (DSAs), the returned value is zero.
- LOAD_POINT
- Optional Parameter
- The address of the load point of the program instance.
- LOCATION
- Optional Parameter
- Determines where the program instance for which the LOAD_POINT and ENTRY_POINT have been returned resides.
- Values for the parameter are:
- CDSA
- ECDSA
- ELPA
- ERDSA
- ESDSA
- LPA
- NONE
- RDSA
- SDSA
- NEW_APPL_CONTEXT_TOKEN
- Optional parameter
- A token to be used on subsequent calls, representing the application context of PLATFORM_ID, APPLICATION_ID, APPL_MAJOR_VER, APPL_MINOR_VER, and APPL_MICRO_VER.
- NEW_PROGRAM_TOKEN
- Optional Parameter
- The identifying token that may be used on subsequent ACQUIRE or RELEASE calls for this program name.
- PROGRAM_ATTRIBUTE
- Optional Parameter
- Reflects the program attribute from the program definition, and is used by the program manager domain to recognize RELOAD programs.
- Values for the parameter are:
- RELOAD
- RESIDENT
- REUSABLE
- TEST
- TRANSIENT
- PROGRAM_LENGTH
- Optional Parameter
- The length of the program instance in bytes.