Load a program from the CICS® DFHRPL concatenation library 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. See
the CICS Application
Programming Guide
for more information about transaction affinities.
Description
Load makes available to the invoking
task a copy of an application program, table, or map. If the program is defined
with RELOAD=NO, it is only fetched from the library where it resides, 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. (See the CICS Application Programming Guide for
further details about maps.) Using LOAD can reduce system overhead.
Options
- ENTRY(ptr-ref)
- specifies
the pointer reference that is to be set to the address of the entry point
in the program that has been loaded.
The top bit of the address is set
on if the program is defined with AMODE=31.
For assembler programs
without an explicit ENTRY defined in the linkedit definitions, the entry point
returned depends on (1) whether there is a CICS stub, and (2) 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 executed 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 32KB.
- HOLD
- specifies
that the loaded program, table, or map is not to be released (if still available)
when the task issuing 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 must be issued to get rid of 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 32KB.
- 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
- INVREQ
- RESP2
values:
- 30
- The program manager domain has not yet been initialized. This is probably
due to a load request having been made in a first stage PLT.
Default action: terminate the task abnormally.
- LENGERR
- RESP2
values:
- 19
- LENGTH is used and the length of the loaded program is not less than 32KB.
Default action: terminate the task abnormally.
- NOTAUTH
- RESP2
values:
- 101
- A resource security check has failed on PROGRAM(name).
Default action: terminate the task abnormally.
- PGMIDERR
- RESP2
values:
- 1
- A program, table, or map has no entry in the PPT 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 because:
- 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.
In order to reset the load status the load module must be in the
DFHRPL 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, 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 the PPT table, or was not enabled.
- 23
- The program autoinstall control program returned invalid data.
- 24
- Define for the program failed due to autoinstall returning an invalid
program name or definition.
- 42
- An attempt has been made to LOAD a JVM program. This is invalid because Java™ byte
codes programs are not managed by CICS Loader.
Default action: terminate the task abnormally.
Examples
The following example shows how to load
a user-prepared table called TB1:
EXEC CICS LOAD PROGRAM('TB1') SET(PTR)