Load a program from the CICS® DFHRPL or dynamic LIBRARY concatenation into main storage.
LOAD >>-LOAD--PROGRAM(name)--+--------------+------------------------> '-SET(ptr-ref)-' >--+--------------------+--+----------------+--+------+-------->< +-LENGTH(data-area)--+ '-ENTRY(ptr-ref)-' '-HOLD-' '-FLENGTH(data-area)-'
Conditions: INVREQ, LENGERR, NOTAUTH, PGMIDERR
This command is threadsafe.
Note for dynamic transaction routing: Using LOAD with HOLD, or using a resource that has been defined with RELOAD=YES, could create inter-transaction affinities that adversely affect the use of dynamic transaction routing. For more information about transaction affinities, see Affinity.
Description
Load makes a copy of an application program, table, or map available to the invoking task. If the program is defined with RELOAD=NO, it is fetched from the LIBRARY concatenation where it resides only if there is not a copy already in main storage. If the program is defined with RELOAD=YES, a new copy is always fetched from the LIBRARY concatenation. (See Basic mapping support for further details about maps.) Using LOAD can reduce system overhead.
Options
- ENTRY(ptr-ref)
Specifies
the pointer reference to be set to the address of the entry point
in the program that has been loaded. CICS program load services set
the entry point according to the addressing mode of the load module:- AMODE(24): bit 0 is 0 and bit 31 is 0.
- AMODE(31): bit 0 is 1 and bit 31 is 0.
- AMODE(64): bit 0 is 0 and bit 31 is 1.
For assembler programs without an explicit ENTRY defined in the linkedit definitions, the entry point returned depends on whether there is a CICS stub, and whether the LOAD command is issued from a PLT program:- If there is a CICS stub, the entry point address is incremented for this stub unless the LOAD command is issued from a PLT program run during the first phase of initialization or the final phase of shutdown.
- If there is not a CICS stub, the entry point address is the same as the load point address.
- FLENGTH(data-area)
- Specifies a fullword binary area to be set to the length of the loaded program, table, or map. Use FLENGTH if the length of the loaded program is greater than 32 KB.
- HOLD
- Specifies
that the loaded program, table, or map is not to be released (if still
available) when the task that issues the LOAD command is terminated;
it is to be released only in response to a RELEASE command from this
task or from another task.
If you omit HOLD, the program, table, or map is released when the task that issued the load terminates or issues a RELEASE command.
If, however, the program is defined with RELOAD=YES, neither of the above apply. RELEASE does not work, and a FREEMAIN request must be issued to remove the program.
- LENGTH(data-area)
- Specifies a halfword binary value to be set to the length of the loaded program, table, or map. To avoid raising the LENGERR condition, use FLENGTH if the length of the loaded program is likely to be greater than 32 KB.
- PROGRAM(name)
- Specifies the identifier (1 - 8 characters) of a program, table, or map to be loaded. The specified name must have been defined as a program to CICS, though if AUTOINSTALL is active, a definition is autoinstalled.
- SET(ptr-ref)
- Specifies the pointer reference that is to be set to the address at which a program, table, or map is loaded.
Conditions
- 16 INVREQ
- RESP2
values:
- 30
- The program manager domain is not yet initialized. This is probably because a load request was made in a first stage PLT.
Default action: terminate the task abnormally.
- 22 LENGERR
- RESP2
values:
- 19
- LENGTH is used and the length of the loaded program is greater than 32 KB.
Default action: terminate the task abnormally.
- 70 NOTAUTH
- RESP2
values:
- 101
- A resource security check has failed on PROGRAM(name).
Default action: terminate the task abnormally.
- 27 PGMIDERR
- RESP2
values:
- 1
- A program, table, or map has no installed resource definition and either program autoinstall was switched off, or the program autoinstall control program indicated that the program should not be autoinstalled.
- 2
- A program is disabled.
- 3
- A program could not be loaded for one of the following reasons:
- This was the first load of the program and the program load failed, usually because the load module could not be found.
- This was a subsequent load of the program, but the first load failed.
To reset the load status, the load module must be in the DFHRPL or dynamic LIBRARY concatenation, and a SET PROGRAM NEWCOPY will be required.
- 9
- The installed program definition is for a remote program.
- 21
- The program autoinstall control program failed either because the program autoinstall control program is incorrect, or incorrectly defined, or as a result of an abend in the program autoinstall control program. Program autoinstall is disabled and message DFHPG0202 or DFHPG0203 written to the CSPL.
- 22
- The model returned by the program autoinstall control program was not defined in CICS, or was not enabled.
- 23
- The program autoinstall control program returned invalid data.
- 24
- Define for the program failed because autoinstall returned an invalid program name or definition.
- 42
- An attempt has been made to LOAD a JVM program. This action is not valid because Java™ byte code programs are not managed by CICS Loader.
Default action: terminate the task abnormally.
Example
EXEC CICS LOAD PROGRAM('TB1') SET(PTR)