Loader domain’s specific gate

Table 61 summarizes the loader domain’s specific gate. It shows the level-1 trace point IDs of the modules providing the functions for the gate, the functions provided by the gate, and whether or not the functions are available through the exit programming interface (XPI).

Table 61. Loader domain’s specific gate
Gate Trace Function XPI
LDLD
LD 0001
LD 0002
ACQUIRE_PROGRAM
RELEASE_PROGRAM
REFRESH_PROGRAM
DEFINE_PROGRAM
INQUIRE_PROGRAM
DELETE_PROGRAM
START_BROWSE
GET_NEXT_PROGRAM
GET_NEXT_INSTANCE
END_BROWSE
IDENTIFY_PROGRAM
SET_OPTIONS
INQUIRE_OPTIONS
CATALOG_PROGRAMS
YES
YES
NO
YES
NO
YES
NO
NO
NO
NO
NO
NO
NO
NO

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

PROGRAM_NAME
specifies the name of the required program.
PROGRAM_TOKEN
is a valid program-identifying token as returned by a previous DEFINE or ACQUIRE request for the same program name.
[SUSPEND]
indicates 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. It can have either of these values:
YES|NO
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.

Output parameters

ENTRY_POINT
is the address of the entry point of the program instance.
[LOAD_POINT]
is the address of the load point of the program instance.
[PROGRAM_LENGTH]
is the length of the program instance in bytes.
[NEW_PROGRAM_TOKEN]
is the identifying token that may be used on subsequent ACQUIRE or RELEASE calls for this program name.
[PROGRAM_ATTRIBUTE]
reflects the program attribute from the program definition, and is used by the program manager domain to recognize RELOAD programs.
[LOCATION]
determines where the program instance for which the LOAD_POINT and ENTRY_POINT have been returned resides.
[COPY_STATUS]
indicates 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.
[FETCH_TIME]
is the time taken to load the program from the DFHRPL library. 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.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
LIBRARY_IO_ERROR
OS_STORAGE_SHORTAGE
ABEND
LOOP
EXCEPTION
PROGRAM_NOT_DEFINED
PROGRAM_NOT_FOUND
NO_STORAGE
INVALID INVALID_PROGRAM_TOKEN

LDLD gate, RELEASE_PROGRAM function

The RELEASE_PROGRAM function of the LDLD gate is used to inform the loader domain that use of a copy of the named program is no longer required. The use count of the specified program instance is decremented; if the use count reaches zero, and the program is eligible to be removed from memory, it is removed from memory.

Input parameters

PROGRAM_NAME
specifies the name of the program to be released.
PROGRAM_TOKEN
is the identifying token returned by the ACQUIRE request for this program.
ENTRY_POINT
specifies the address of the entry point of the module.

Output parameters

[LOAD_POINT]
is the address of the load point of the program instance.
[PROGRAM_LENGTH]
is the length of the program instance in bytes.
[LOCATION]
determines where the program instance for which the LOAD_POINT and ENTRY_POINT have been returned resides.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION
PROGRAM_NOT_DEFINED
PROGRAM_NOT_IN_USE
INVALID
INVALID_PROGRAM_TOKEN
INVALID_ENTRY_POINT

LDLD gate, REFRESH_PROGRAM function

The REFRESH_PROGRAM function of the LDLD gate is used to inform the loader domain that a new version of the program has been cataloged, and that this version of the named program should be used for all future ACQUIRE requests.

Input parameters

PROGRAM_NAME
specifies the name of the program that is to have a new version used.

Output parameters

[NEW_VERSION_FOUND]
indicates whether a new version of the program has been found.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER or EXCEPTION. Possible values are:
RESPONSE Possible REASON values
DISASTER
LIBRARY_IO_ERROR
OS_STORAGE_SHORTAGE
ABEND
LOOP
EXCEPTION
PROGRAM_NOT_DEFINED
PROGRAM_NOT_FOUND

LDLD gate, DEFINE_PROGRAM function

The DEFINE_PROGRAM function of the LDLD gate is used to introduce a new program to the CICS system or to update the details of an existing program.

Input parameters

PROGRAM_NAME
specifies the name of the program whose attributes are to be set.
CATALOG_MODULE
indicates whether the program definition should be written to one of the catalogs. It can have either of these values:
YES|NO
UPDATE
indicates whether the loader domain should update the program definition if the loader domain already has a program definition for the program. If UPDATE(NO) is specified, and the loader domain already has a program definition for the specified program, PROGRAM_ALREADY_DEFINED is returned. It can have either of these values:
YES|NO
[EXECUTION_KEY]
is the execution key for the program. This is used to determine which DSA the program instance resides in. It can have either of these values:
USER|CICS
[PROGRAM_TYPE]
is the type of program copy to be used. It can have any of these values:
PRIVATE|SHARED|TYPE_ANY
[PROGRAM_USAGE]
defines whether the program is part of the CICS nucleus, or is an application program defined by the user. This determines whether the program definition is written to the local catalog or to the global catalog. It can have either of these values:
NUCLEUS|APPLICATION
[PROGRAM_ATTRIBUTE]
is a residency attribute to be associated with the program. It can have any of these values:
RESIDENT|REUSABLE|TRANSIENT|RELOAD
[REQUIRED_AMODE]
is the addressing mode required by CICS for the program. A program that does not have the required residency mode is not loaded. It can have any of these values:
24|31|AMODE_ANY
[REQUIRED_RMODE]
is the residency mode required by CICS for the program. A program that does not have the required mode requirements is not loaded. It can have any of these values:
24|RMODE_ANY

Output parameters

[NEW_PROGRAM_TOKEN]
is an identifying token that can be used on subsequent ACQUIRE or RELEASE calls for this program name.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION
CATALOG_NOT_OPERATIONAL
CATALOG_ERROR
INVALID_PROGRAM_NAME
PROGRAM_ALREADY_DEFINED
INVALID
INVALID_MODE_COMBINATION
INVALID_TYPE_ATTRIB_COMBIN

LDLD gate, INQUIRE_PROGRAM function

The INQUIRE_PROGRAM function of the LDLD gate is used to return the details of a specific program.

Input parameters

PROGRAM_NAME
specifies the name of the program whose attributes are being requested.
PROGRAM_TOKEN
is a valid program token as returned by a previous DEFINE or ACQUIRE request, or obtained from the PPT entry, for the program.

Output parameters

[NEW_PROGRAM_TOKEN]
is an identifying token that can be used on subsequent ACQUIRE or RELEASE calls for this program name.
[PROGRAM_TYPE]
is the current program copy type.
[PROGRAM_USAGE]
is the current usage definition.
[EXECUTION_KEY]
is the execution key for the program.
[PROGRAM_ATTRIBUTE]
is the current residency attribute of the program.
[SPECIFIED_AMODE]
is the addressing mode required by CICS for the program. A program that does not have the required residency mode is not loaded. If REQUIRED_AMODE was omitted when the program was defined, AMODE_NOT_SPECIFIED is returned.
[SPECIFIED_RMODE]
is the residency mode required by CICS for the program. A program that does not have the required residency mode is not loaded. If REQUIRED_RMODE was omitted when the program was defined, RMODE_NOT_SPECIFIED is returned.
[PROGRAM_LENGTH]
is the length of the program in bytes. If the program has not been used, this is zero.
[PROGRAM_USE_COUNT]
is the cumulative use count of the program.
[PROGRAM_USER_COUNT]
is the current number of users of the program.
[LOAD_POINT]
is the address of the load point of the last program instance created for this program name.
[ENTRY_POINT]
is the address of the entry point of the last program instance created for this program name.
[LOCATION]
indicates where the program for which the LOAD_POINT and ENTRY_POINT have been returned resides.
[ACCESS]
is the type of storage that the program resides in.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION PROGRAM_NOT_DEFINED
INVALID INVALID_PROGRAM_TOKEN

LDLD gate, DELETE_PROGRAM function

The DELETE_PROGRAM function of the LDLD gate is used to remove a program from the CICS system. All subsequent ACQUIRE requests for the named program fail with a reason of PROGRAM_NOT_DEFINED. Any instance of the program in use at the time the DELETE is received continue to exist until a RELEASE request reduces the use count to zero, at which time the instance is removed from memory.

Input parameters

PROGRAM_NAME
specifies the name of the program to be removed.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION PROGRAM_NOT_DEFINED

LDLD gate, START_BROWSE function

The START_BROWSE function of the LDLD gate is used to start a browse session.

Input parameters

[PROGRAM_NAME]
specifies the name of the program whose attributes are to be returned.
[ENTRY_POINT]
is the address of the entry point of the last program instance created for this program name.

Output parameters

BROWSE_TOKEN
is a token used to refer to this browse session on subsequent browse requests.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP

LDLD gate, GET_NEXT_PROGRAM function

The GET_NEXT_PROGRAM function of the LDLD gate is used to perform an INQUIRE function for the next program in the alphabetic sequence of programs in the current browse session.

Input parameters

BROWSE_TOKEN
is a valid browse token as returned by the preceding START_BROWSE request.

Output parameters

[PROGRAM_NAME]
is the name of the program whose attributes have been returned.
[PROGRAM_TYPE]
is the current program copy type.
[PROGRAM_USAGE]
is the current usage definition.
[EXECUTION_KEY]
is the execution key for the program.
[PROGRAM_ATTRIBUTE]
is the current residency attribute of the program.
[SPECIFIED_AMODE]
is the current addressing mode required by CICS for the program. If REQUIRED_AMODE was omitted when the program was defined, AMODE_NOT_SPECIFIED is returned.
[SPECIFIED_RMODE]
is the current residency mode required by CICS for the program. If REQUIRED_RMODE was omitted when the program was defined, RMODE_NOT_SPECIFIED is returned.
[PROGRAM_LENGTH]
is the length of the program in bytes. If the program has not been used, this is zero.
[PROGRAM_USE_COUNT]
is the cumulative use count of the program.
[PROGRAM_USER_COUNT]
is the current number of users of the program.
[LOAD_POINT]
is the address of the load point of the last program instance created for this program name.
[ENTRY_POINT]
is the address of the entry point of the last program instance created for this program name.
[LOCATION]
indicates where the program for which the LOAD_POINT and ENTRY_POINT have been returned resides.
[ACCESS]
is the type of storage that the program resides in.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION END_LIST
INVALID INVALID_BROWSE_TOKEN

LDLD gate, GET_NEXT_INSTANCE function

The GET_NEXT_INSTANCE function of the LDLD gate is used to browse the current program instances in ascending load point address sequence.

Input parameters

BROWSE_TOKEN
is a valid browse token as returned by the preceding START_BROWSE request.

Output parameters

[PROGRAM_NAME]
is the name of the program of which this is an instance.
[PROGRAM_TYPE]
is the current program copy type.
[PROGRAM_USAGE]
is the current usage definition.
[EXECUTION_KEY]
is the execution key for the program.
[PROGRAM_ATTRIBUTE]
is the current residency attribute of the program.
[SPECIFIED_AMODE]
is the current addressing mode required by CICS for the program. If REQUIRED_AMODE was omitted when the program was defined, AMODE_NOT_SPECIFIED is returned.
[SPECIFIED_RMODE]
is the current residency mode required by CICS for the program. If REQUIRED_RMODE was omitted when the program was defined, RMODE_NOT_SPECIFIED is returned.
[PROGRAM_LENGTH]
is the length of the program in bytes. If the program has not been used, this is zero.
[ENTRY_POINT]
is the address of the entry point of the last program instance created for this program name.
[LOAD_POINT]
is the address of the load point of the last program instance created for this program name.
[LOCATION]
indicates where the program instance for which the LOAD_POINT and ENTRY_POINT have been returned resides.
[ACCESS]
is the type of storage that the program resides in.
[INSTANCE_USE_COUNT]
is the current number of users of this instance.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION END_LIST
INVALID INVALID_BROWSE_TOKEN

LDLD gate, END_BROWSE function

The END_BROWSE function of the LDLD gate is used to end a browse session.

Input parameters

BROWSE_TOKEN
is the token identifying this browse session.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
INVALID INVALID_BROWSE_TOKEN

LDLD gate, IDENTIFY_PROGRAM function

The IDENTIFY_PROGRAM function of the LDLD gate is used to locate the program instance which contains the specified address.

Input parameters

ADDRESS
is a storage address.

Output parameters

[PROGRAM_NAME]
is the name of the program of which this is an instance.
[PROGRAM_TYPE]
is the current program copy type.
[PROGRAM_USAGE]
is the current usage definition.
[EXECUTION_KEY]
is the execution key for the program.
[PROGRAM_ATTRIBUTE]
is the current residency attribute of the program.
[SPECIFIED_AMODE]
is the addressing mode required by CICS for the program. A program that does not have the required residency mode is not loaded. If REQUIRED_AMODE was omitted when the program was defined, AMODE_NOT_SPECIFIED is returned.
[SPECIFIED_RMODE]
is the residency mode required by CICS for the program. A program that does not have the required residency mode is not loaded. If REQUIRED_RMODE was omitted when the program was defined, RMODE_NOT_SPECIFIED is returned.
[PROGRAM_LENGTH]
is the length of the program in bytes. If the program has not been used, this is zero.
[ENTRY_POINT]
is the address of the entry point of the last program instance created for this program name.
[LOAD_POINT]
is the address of the load point of the last program instance created for this program name.
[LOCATION]
indicates where the program instance for which the LOAD_POINT and ENTRY_POINT have been returned resides.
[ACCESS]
is the type of storage that the program resides in.
[INSTANCE_USE_COUNT]
is the current number of users of this instance.
[CSECT_NAME]
is the name of the CSECT within the module which contains the address. If no CSECT is available, the module name is returned.
[OFFSET_INTO_CSECT]
is the offset of the address within the CSECT. If no CSECT is available, the module name is returned.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER or EXCEPTION. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION INSTANCE_NOT_FOUND

LDLD gate, SET_OPTIONS function

The SET_OPTIONS function of the LDLD gate is used to set loader global options.

Input parameters

[LLACOPY]
indicates whether the loader is to use the MVS macro LLACOPY or BLDL to locate programs. It can have any of these values:
YES|NO|NEWCOPY
[SHARED_PROGRAMS]
indicates whether the loader is to use LPA-resident programs to satisfy ACQUIRE requests. It can have either of these values:
YES|NO
[STORAGE_FACTOR]
indicates the percentage of system free storage that may be occupied by program instances that have a zero use count.
[PRVMOD]
is a list of the names of modules that are not to be used from the MVS link pack area (LPA), but instead are to be loaded as private copies from the DFHRPL library.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION
CATALOG_NOT_OPERATIONAL
CATALOG_ERROR
INVALID INVALID_STORAGE_FACTOR

LDLD gate, INQUIRE_OPTIONS function

The INQUIRE_OPTIONS function of the LDLD gate is used to return loader global options.

Input parameters

None.

Output parameters

[SHARED_PROGRAMS]
indicates whether the loader is utilizing LPA-resident programs to satisfy ACQUIRE requests.
[STORAGE_FACTOR]
indicates the percentage of system free storage that may be occupied by program instances that have a zero use count.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP

LDLD gate, CATALOG_PROGRAMS function

The CATALOG_PROGRAMS function of the LDLD gate is used at the end of CICS initialization to request the loader domain to catalog all the program definitions that need cataloging. The call is issued by the DFHSIJ1 module.

Input parameters

None.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER or EXCEPTION. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION
CATALOG_NOT_OPERATIONAL
CATALOG_ERROR
[[ Contents Previous Page | Next Page Index ]]