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