The DEFINE_PROGRAM call
You can use the DEFINE_PROGRAM call to define new programs to the loader domain, or to change the details of programs that are already defined. The details that you provide are recorded on the local catalog, and become available immediately. They are used on all subsequent ACQUIRE requests for the named program.
Program definitions made using DEFINE_PROGRAM are not retained over an XRF takeover. Also,
the CSD is not updated; the loader domain definitions are.
DEFINE_PROGRAM
DFHLDLDX [CALL,]
[CLEAR,]
[IN,
FUNCTION(DEFINE_PROGRAM),
PROGRAM_NAME(name8 | string | 'string' ),
[EXECUTION_KEY(CICS|USER),]
[PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT),]
[PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY),]
[REQUIRED_AMODE(24|31|AMODE_ANY|64),]
[REQUIRED_RMODE(24|RMODE_ANY),]]
[OUT,
[NEW_PROGRAM_TOKEN(name8),]
RESPONSE(name1 | *),
REASON(name1 | *)]This command is threadsafe.
- EXECUTION_KEY(CICS|USER)
- Specifies, in conjunction with other program attributes, the type of dynamic storage area (DSA)
into which the loader is to load the program. For a list of DSAs, see CICS dynamic storage areas (DSAs).
- CICS
- For non-reentrant programs, the program is to be loaded into a CICS® DSA above or below the 16 MB line. The choice of CICS DSA depends on the residence mode (RMODE) attribute of the program, as defined to the
linkage-editor.
For reentrant RMODE(24) programs, the program is to be loaded into the CICS DSA below the 16MB line.
- USER
- For non-reentrant programs, the program is to be loaded into a user DSA above or below the 16 MB
line. The choice of user DSA depends on the residence mode (RMODE) attribute of the program, as
defined to the linkage-editor.
For reentrant RMODE(24) programs, the program is to be loaded into the user DSA below the 16 MB line.
Reentrant programs eligible to reside above the 16 MB line: If a program is link-edited as reentrant with AMODE(31),RMODE(ANY), the EXECUTION_KEY option is ignored, and it is loaded into a read-only DSA. For details of the type of storage allocated for this DSA, see the RENTPGM system initialization parameter.
- NEW_PROGRAM_TOKEN(name8)
- Returns the token supplied for the newly-defined program.
- name8
- The name of a location to contain the 8-byte token obtained.
- PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT)
- Specifies the residency status of the program.
- RELOAD
- Every ACQUIRE_PROGRAM request for this program is satisfied by
loading a new copy into storage. When a RELEASE request is issued
for a copy, it is removed from storage. Note: Do not use this attribute when defining an exit program.
- RESIDENT
- There is a single copy of the program that is not removed from storage unless it is deleted. RESIDENT programs must be at least quasi-reentrant.
- REUSABLE
- The program is at least quasi-reentrant; a single copy in storage can be used by several tasks in the system. A REUSABLE program becomes eligible for removal from storage as part of the normal dynamic program storage compression (DPSC) scheme when its use count reaches zero.
- TRANSIENT
- Similar to REUSABLE, except that the program is removed from storage immediately when its use count reaches zero. Specify this option only for less-frequently used programs, or for programs in systems that are critically short on storage.
- PROGRAM_NAME(name8 | string | "string")
- Specifies the name of the program to be defined.
- name8
- The name of a location where there is an 8-byte program name.
- string
- A string of characters, without intervening blanks, naming the program.
- "string"
- A string of characters within quotation marks. The string length is set to 8 by padding with blanks or by truncation.
- PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY)
- Specifies where to load the program from.
- PRIVATE
- The program is in the DFHRPL or dynamic LIBRARY concatenation. A PRIVATE program need not be reentrant, and is given only limited protection from unauthorized overwriting. The degree of protection depends on the type of dynamic storage area (DSA) into which the program is loaded. A CICS DSA cannot be overwritten by USER tasks. A read-only DSA cannot be overwritten by either USER tasks or CICS tasks. A user DSA has no protection from unauthorized overwriting.
- SHARED
- The program is located in the link pack area (LPA), is reentrant, and is protected.
- TYPE_ANY
- Either the copy in DFHRPL or dynamic LIBRARY concatenation, or the LPA copy of the program can be used, though preference is given to the LPA copy.
- REQUIRED_AMODE(24|31|AMODE_ANY|64)
- Specifies the addressing mode of the program. If, during subsequent
ACQUIRE_PROGRAM processing, no copy of the program that meets the
defined addressing requirement can be found, the ACQUIRE_PROGRAM call
receives an EXCEPTION response and the REASON value PROGRAM_NOT_FOUND.
Note:
- AMODE_ANY and AMODE 31 have identical meanings for this function.
- You cannot use this option to override the link-edited addressing mode of the program.
- REQUIRED_RMODE(24|RMODE_ANY)
- Specifies the residency mode of the program. If, during subsequent
ACQUIRE_PROGRAM processing, no copy of the program that meets the
defined addressing requirement can be found, the ACQUIRE_PROGRAM call
receives an EXCEPTION response and the REASON value PROGRAM_NOT_FOUND.
Note: You cannot use this option to override the link-edited residence mode of the program.
RESPONSE and REASON values for DEFINE_PROGRAM
| RESPONSE | REASON |
|---|---|
| OK | None |
| EXCEPTION | CATALOG_ERROR |
| CATALOG_NOT_OPERATIONAL | |
| 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.