DFSEMODL macro

The external subsystem module table (ESMT) is generated from a series of DFSEMODL statements, one for each module definition.

In addition to module definition information, information about the control block that is to contain the addresses of the modules when they are loaded is also supplied on DFSEMODL statements. IMS creates this control block before it loads the modules.

IMS provides the capability for up to three sets of modules to be loaded and anchored on separate control blocks. Accordingly, the ESMT consists of one to three subtables, each containing the specifications for a set of modules and their module address control block. The module address control block for external subsystem exit routines is the EEVT (external entry vector table).

When the module address control block is created, IMS stores its address into a source control block, which is the EEVTP (EEVT prefix).

The format of the DFSEMODL macro is:

(label)   DFSEMODL DSNAME=,SOURCE=,MODNAME=,DSLABEL=,
                   SUBPOOL=,OPTION=,END=

where:

(label): Is optional. If coded, the macro generates ESMT subtable labels. The last label on a macro statement in the series from which a subtable is generated is used as the subtable label.

The following parameters provide control block information and need only be specified once per subtable (for example, on the first DFSEMODL statement in the series). If specified on more than one statement, the first specifications encountered are used in generating the table.

DSNAME=

(p1,p2,p3)

p1: Name of the module address control block. The name must be specified (at least on one DFSEMODL statement) for each ESMT subtable.
p2: Module address control block size. The size must be specified. IMS obtains storage of the specified size to create the module address control block.
p3: Subpool number for the module address control block storage request. This parameter is optional. If 251 is not specified, IMS obtains the storage from subpool 230.

SOURCE=

(p1,p2)

p1: Name of the source control block. This parameter is required. DFSEEVTP must be specified. (See the following discussion.)
p2: Label in the source control block of the location to store module address control block address. This parameter is required.

The following parameters provide module definition information.

MODNAME=

Name of the module IMS is to load. MODNAME must be specified on all DFSEMODL statements that do not specify the END parameter. (END can be specified with or without MODNAME.)

DSLABEL=

Label in the module address control block of the location to store the module address after it is loaded. DSLABEL must be specified (when MODNAME is specified).

SUBPOOL=

For resources that reside on a PDS data set:

The subpool into which IMS is to load the module. SUBPOOL must be specified when MODNAME is specified. For the control region, IMS loads the module into the subpool specified. For dependent regions, IMS loads the module into subpool 251 if SUBPOOL=251 is specified. Otherwise, the module is loaded into subpool 230. Valid specifications are 0, 229, 230, 231, 241, 251, 252.

For modules that reside on a PDSE data set:

The SUBPOOL parameter is not used. Modules residing on a PDSE are loaded in one of the following methods:

Modules that are linked as reentrant (RENT) are loaded into subpool 252, key 0. These modules are not fetch-protected.
Modules that are linked as not reentrant (NORENT) are loaded into subpool 251, TCBKEY, and are fetch-protected. You must ensure that the correct protect key is in use before accessing these modules.

OPTION=

(p,p)

This parameter is optional. Two options, NOCTL and NODEP, are supported. (Position of an option in the subparameter list is not important.)

NOCTL: The module is not to be loaded in the control region.
NODEP: The module is not to be loaded in dependent regions.

The END parameter controls ESMT generation.

END=

YES: Must be specified to indicate the end of a subtable in the ESMT being generated. END=YES is used only when the ESMT is to contain more than one subtable. It is specified to end each subtable except the last (or only). DFSEMODL statements for the next subtable in the ESMT are to follow the END=YES specification.
LAST: Must be specified on the last DFSEMODL definition statement for the ESMT being generated. The next DFSEMODL or DFSEWAL statement (if any) causes a new ESMT generation to be started.

You must bind the ESMT module into a program library (SDFSRESL) using a binder ENTRY statement that specifies MAINEP as the entry point. A table definition header is generated at the end of the ESMT module. The ENTRY statement allows IMS to correctly reference the header for subsequent processing.

DFSEMODL supports an execute form (MF=E) for internal use only. It cannot be used for ESMT generation. The list form (MF=L) described is the default.

Mapping DSECTs for the module address and source control blocks must be included in the ESMT generation source, otherwise the assembly will fail.

The following restrictions apply to external subsystems:

Specifying the source control block.
DFSEEVTP must be specified as the source control block name (SOURCE(p1)) for all IMS-defined subtables. Otherwise, although DFSEMODL accepts other specifications, the module load process will fail, prohibiting a connection for the region experiencing the failure. The user must use the EEVTP mapping layout, as this is the layout that IMS expects.
Defining subsystem exit routine modules.
DFSEEVT must be specified as the module address control block name (DSNAME(p1)) for the subtable that contains the subsystem exit routine module definitions.

The module address control block size (DSNAME(p2)) must be specified according to the size indicated by the EEVT mapping (EEVTLGTH) as shown in Control block mapping in IMS Version 15.4 Exit Routines.

EEVPEEA must be specified as the label in the source control block (SOURCE(p2)) to anchor the module address control block (EEVT). IMS does not check for this (nor does the macro) but uses the offset generated from the label specified to store the address. If the offset is incorrect, IMS will not be able to activate the exit routines.

The label (DSLABEL) specified for a particular subsystem exit routine module is used to generate the offset that IMS uses to store the exit routine address in the module address control block (for example, in the EEVT). Thus these labels must be specified according to the EEVT mapping.
Generating additional subtables.
The ESMT must always have one subtable containing definitions for exit routine modules. The external subsystem could choose to have other modules needed in its ESAP anchored on a separate control block, which means that another subtable would be generated.

Although the DFSEMODL macro does not restrict the number of subtables that can be generated, problems can occur during processing if more than three (3) are generated. For each subtable, IMS creates a module address control block and stores its address in the EEVTP. There are only three fields in the EEVTP that could be used as anchors for these control blocks, one of them being the anchor for the EEVT.

The EEVTLDIR and EEVPEWA fields are not used by IMS and thus are available for this purpose. The discussion on defining external subsystem work areas in DFSEWAL macro suggests how EEVPEWA might be used to anchor a work area address control block.
Defining external subsystem-unique modules.
If the ESAP needs non-IMS exit routine modules (for example, modules that the external subsystem activates without any knowledge of or support from IMS), the external subsystem can define these modules in an additional subtable as previously discussed. The external subsystem must supply the mapping DSECT for the module address control block for these modules.

Recommendation: Do not define other modules in the subtable containing exit routine modules or extend the size of the EEVT to include their addresses. The EEVT is an IMS control block which IMS reserves the right to extend at any time, which could require the external subsystem to regenerate the ESMT and re-compile modules.