Loading and placement of installation load modules

Use the LOADmod(jxxxxxxx) initialization statement or the $ADD LOADmod(jxxxxxxx) command to direct the loading of all installation-defined load modules (such as user-defined exits). Exit routines must be loaded in this manner, rather than linking to JES2 load modules. JES2 only searches for installation-defined exit routines in user modules defined by the LOADmod(jxxxxxxx) initialization statement or the $ADD LOADmod(jxxxxxxx) command, in the reserved module names HASPXJ00 – J31, or in HASPXIT0; JES2 does not search for such routines in IBM-defined modules. The STORAGE= parameter specifies the area of storage where the load module is to be loaded. This is the copy that JES2 will use. Table 1 presents a summary of the manner in which JES2 directs the load of a load module based on initial placement of that load module and the LOADmod(jxxxxxxx) STORAGE= specification.

Note the following restrictions:

STORAGE=LPA is invalid if the load module is initially placed in STEPLIB only, LINKLIST only, or both STEPLIB and LINKLIST. JES2 issues message $HASP003 RC(31), MODULE COULD NOT BE LOADED.
All other STORAGE= requests are valid, but you may not receive the expected result (see Table 1).
You cannot load a module into the link pack area (LPA) following MVS™ initialization. You may only request that the copy of the module in LPA be used if multiple copies are found.

Table 1. Directed Load and Use of Modules Based on LOADMOD(jxxxxxxx) STORAGE= Specification
Location of Module is:	STORAGE=PVT, module is found in	STORAGE=CSA, module is found in	STORAGE=LPA, module is found in
STEPLIB Only	PVT	CSA	$HASP003 RC=31
LPA Only	LPA	LPA	LPA
LNKLST Only	PVT	CSA	$HASP003 RC=31
STEPLIB and LPA	PVT (STEPLIB)	CSA (STEPLIB)	LPA
STEPLIB and LNKLST	PVT	CSA (STEPLIB)	$HASP003 RC=31
LPA and LNKLST	LPA	LPA	LPA
STEPLIB, LPA and LNKLST	PVT (STEPLIB)	CSA (STEPLIB)	LPA

To place the load module either above or below 16 megabytes, use the linkage editor MODE statement or specify the RMODE= parameter on the $MODULE macro.

Figure 1 illustrates two ways to package an exit routine:

Figure 1. Methods of Packaging an Exit Routine

A JES2 $MODULE macro must be the first code-generating statement (immediately preceded by COPY $HASPGBL) in a source module to be assembled and either link edited separately and loaded at initialization or a source module to be added to a standard JES2 load module.

Note: The $MODULE macro call must occur prior to the first use of $ENTRY or $EXIT, and a JES2 $MODEND macro must be coded at the end of both types of source modules.

You can only code one $MODULE and one $MODEND macro in each source module. Further, when link editing exits into their own load modules (other than HASJES20), each source module must be linked into its own load module.

To locate the MITs of modules that are added to the standard JES2 load modules, JES2 uses weak external address constants. To locate the MITs of modules that are linked in their own load modules, JES2 assumes that the MIT, generated by $MODULE, is located at the front of the load module to which it points. The MITETBL, generated by $MODULE, is located at the end of a module loaded at initialization.

Note: For all exit routine source modules, that if an exit routine references the symbolic name of a control block field, the mapping macro for that control block must be included in the $MODULE macro list in the same source module as the exit routine at assembly time.

Furthermore, see Appendix C, “Hints for Coding JES2 Exit Routines” for a list of required mapping macros for individual exits. These macros are environment dependent and must be coded to prevent assembly errors and error messages.

The ENVIRON= operand of the $MODULE macro should be used to specify which JES2 operating environment the exit routine(s) is to execute. Each exit description in the “IBM-Defined Exits” reference section in IBM-defined exits includes a list of mapping macros normally required at assembly.