$MODLOAD – Load module load

$MODLOAD – Load module load

z/OS JES2 Macros
SA32-0996-00

Use $MODLOAD to call the $MODLOAD routine that loads JES2 modules (supplied by IBM® and installation) and MVS™ style modules. The caller must perform any needed $MODCHKs on the module that was loaded, including resolving any dynamic tables or exit routines.

Note: If $MODLOAD is used for a module that has already been loaded and not deleted with $MODELET, the processing proceeds based on the REPLACE= value. If REPLACE=NO (the default), the module is not reloaded and the existing module returns. The subpool value is ignored. If REPLACE=YES is specified and the module is loaded, a new copy of the module is loaded and a new LMT is built. You must delete the old module and LMT using $MODELET.

Format description


>>-+--------+--$MODLOAD--+-------------------------+------------>
   '-symbol-'            '-NAME--=--+-'mod-name'-+-'   
                                    +-label------+     
                                    '-(--R--n--)-'     

>--+--------------------+--+----------------------+------------->
   |           .-JES2-. |  '-,SUBPOOL--=--+-nnn-+-'   
   '-,TYPE--=--+-OS---+-'                 '-LPA-'     

>--+---------------------------+-------------------------------->
   |              .-NO-------. |   
   '-,MESSAGE--=--+-IFEXISTS-+-'   
                  +-YES------+     
                  '-SUPPRESS-'     

>--+---------------------------+--+----------------------+-----><
   '-,ERRET--=--+-label------+-'  |              .-NO--. |   
                '-(--R--n--)-'    '-,REPLACE--=--+-YES-+-'

NAME=

Specifies the name of the module to be loaded by MODLOAD. Specify a 1- to 8-character module name, a label of a field that contains the name, or a register that contains the address of the name. This is a required keyword.

SUBPOOL=

Specifies the storage location into which the module should be loaded.

nnn: Specifies the subpool (0 to 255) for the directed load. The module is to be loaded using the standard module search algorithms.
LPA: Specifies the module is in LPA.

Note:

This parameter is supported for OS load modules only if SUBPOOL=LPA is specified.
It is suggested this parameter be used to load into the common storage area. However, all loads are supported.

TYPE=

Specifies the type of load module to be loaded. If the specified module is a JES2 module and successfully loaded, it receives a $LMT entry; OS load modules do not.

MESSAGE=

Specifies whether $MODLOAD issues the $HASP875 message if the load fails (return code 8).

IFEXISTS: If JES2 finds the module and the module has errors, $MODLOAD issues the message. If JES2 is unable to find the module, $MODLOAD does not issue the message.
YES: If any errors are encountered, $MODLOAD issues the message.
NO: If any errors are encountered, $MODLOAD does not issue the HASP875 message (returns message in R1). The caller must free the 128 byte message work area returned (Subpool = 0 key = 1).
SUPPRESS: Does not issue or return error message.

ERRET=

Specifies the label or register that contains the address of an error routine that receives control if the module is not successfully loaded.

REPLACE=

Specifies whether $MODLOAD fails a request or replaces the existing module if the module is already loaded.

NO: If the module is already loaded, $MODLOAD fails a request.
YES: If the module is already loaded, $MODLOAD replaces it. If the module is not loaded, $MODLOAD does not load it.

Note: REPLACE=YES does not delete the old module. The caller must perform $MODCHKs on the new module. If everything passes, call $MODELET with the old LMT to delete the original module.

Return codes

The following return codes (in decimal) are returned in register 15.

Return Code: Meaning
0: Load module is successfully loaded. If TYPE=JES2, register 1 contains the address of the $LMT. If TYPE=OS, register 1 contains the address of the load module.
4: If REPLACE=NO is specified, the load is not done because the module has already been loaded. R1 contains the LMT entry address. The information of load location requested on this call is ignored.
If REPLACE=YES is specified, the load is not done because the module is not loaded or is not loaded in the specified load location. R1 contains the LMT entry address or a value of zero.
8: Load fails. If MESSAGE=NO, R1 points to a work area that contains AL1(DIAGLEN),C'DIAGNOSTIC'.

Reason codes for return code 8

When $MODLOAD returns control, register 1 points to a storage area that contains the message text and a reason code. The structure of this storage is as follows: (byte 1 refers to the byte that register 1 points to; byte n refers to the last byte of the storage area)

Byte position

Contents

byte 1 and 2

These bytes are not part of the intended programming interface.

byte 3

The length of the message text portion of the variable length text field that follows.

byte 4 to byte n

Variable length text field. This field contains message text that explains the reason code, followed by a comma and a blank character. The blank character is followed by the character string RC=nn. The variable nn contains one of the following reason codes in character format. For a detailed explanation of the reason codes, see documentation for JES2 message $HASP875 in z/OS JES2 Messages.

Reason Code: Meaning
01: There is insufficient storage for the load module table entry.
02: The module cannot be loaded.
03: The module is not reentrant.
04: New CSA or LPA are not valid on a hot start.
05: There is insufficient storage to load the module
14: An exit 0 routine made a $MODLOAD call.

Environment

JES2 main task and initialization.
MVS WAIT may occur.

Attention:

An exit 0 routine must not use $MODLOAD to load common storage JES2 modules.