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.
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.
- CICS®
- For non-reentrant programs, the program is to be loaded into a CICS DSA above or below the 16
MB line; that is, the CDSA or ECDSA. 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 CDSA.
- USER
- For non-reentrant programs, the program is to be loaded into a
user DSA above or below the 16 MB line; that is, the UDSA or EUDSA.
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 UDSA.
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 (the RDSA or ERDSA). For details of the type of storage allocated for the ERDSA, see the RENTPGM system initialization parameter.
See Table 1 for a summary of the effect of the EXECUTION_KEY option in conjunction with other factors.
Table 1. Summary of attributes defining DSA eligibility EXECUTION_KEY option Reentrant Above or below 16 MB line Dynamic storage area (DSA) CICS No Below CDSA CICS Yes Below RDSA CICS No Above ECDSA CICS Yes Above ERDSA USER No Below UDSA USER Yes Below RDSA USER No Above EUDSA USER Yes Above ERDSA - 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 (see the EXECUTION_KEY option):
- DSA
- Protection from unauthorized overwriting
- CDSA
- Cannot be overwritten by USER tasks.
- ECDSA
- Cannot be overwritten by USER tasks.
- ERDSA
- Complete: cannot be overwritten by USER tasks or CICS tasks.
- EUDSA
- None.
- RDSA
- Complete: cannot be overwritten by USER tasks or CICS tasks.
- UDSA
- None.
- 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 |