LOAD

Load a program from the CICS® DFHRPL concatenation library into main storage.

Read syntax diagramSkip visual syntax diagram
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)