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.


dfhs3_LDLDacquire_program.html | Timestamp icon Last updated: Monday, 5 June 2017