LOAD-MODULE - define a load module (BLS, BS2000 systems)

The LOAD-MODULE control statement allows you to define the name, version and properties of load modules. If you use the BLS interface, this statement must be issued for all load modules that can be exchanged or loaded as independent units during the program run. Each load module must be defined in a separate LOAD-MODULE statement.

The load modules that can be processed with BLS are either LLMs (link and load modules) or OMs (object modules). However, it is recommended that the program components and data areas to be loaded dynamically are linked to LLMs (see the BLS manuals).

A load module can contain several program units and data areas, which are defined using PROGRAM or AREA statements. You can assign one or more PROGRAM and/or AREA statements to a single LOAD-MODULE statement. This takes place on the basis of the load module name lmodname, which must also be entered in the LOAD-MODULE operand of the PROGRAM or AREA statement. However, it is also possible to generate LOAD-MODULE statements without assigning a PROGRAM or AREA statement (e.g. load modules that contain parts of the runtime system of a programming language).

At least one LOAD-MODULE statement must be generated if the "program exchange" function (KDCAPPL PROGRAM=NEW) is to be used on BS2000 systems.

When starting the UTM application, the load modules are loaded in accordance with the sequence of LOAD-MODULE statements and the value of the LOAD-MODE operand. The load sequence is as follows:

• The basic part of the application, including all load modules linked in statically to the application program (LOAD-MODE=STATIC).

• All load modules loaded into a global common memory pool when starting the UTM application. These are generated with LOAD-MODULE LOAD-MODE=(POOL, poolname,...) and MPOOL poolname,SCOPE=GLOBAL. The common memory pools are loaded in accordance with the sequence of MPOOL statements in the generation run. Within a pool, the sequence of LOAD-MODULE statements that refer to this pool applies.

• All load modules loaded into a local common memory pool when starting the UTM application. These are generated with LOAD-MODULE LOAD-MODE=(POOL, poolname,...) and MPOOL poolname,SCOPE=GROUP. The pools are loaded in accordance with the sequence of MPOOL statements. Within a pool, the sequence of LOAD-MODULE statements that refer to this pool applies.

• All load modules to be loaded dynamically as independent units during startup. These are generated with LOAD-MODULE LOAD-MODE=STARTUP. The load modules are loaded in accordance with the sequence of LOAD-MODULE statements defined in this way.

Load modules generated with LOAD-MODE=ONCALL are loaded the first time an assigned program unit is called.

Please note the following:

• Load modules containing TCB entries cannot be exchanged.

• When dynamically linking a load module with the generation ALTERNATE-LIBRARIES=YES, you must ensure that only RTS modules are actually linked. This is because when load modules are exchanged, only the load module itself is removed from memory. If the load module is used to dynamically load other modules using the autolink function, these modules remain in memory following the exchange process even though shared data structures, for example, have been modified.

• When linking with the SYSLNK.CRTE.PARTIAL-BIND library, the entry ALTERNATE-LIBRARIES=YES is not required for load modules that only contain C code and possibly data objects (areas), and should therefore be avoided.

LOAD-MODULE

lmodname   [ ,ALTERNATE-LIBRARIES={ NO | YES }  [ ,LIB=libname ]  [ ,LOAD-MODE={ STARTUP |                  ONCALL |                  STATIC |                  (POOL,poolname,{ NO-PRIVATE-SLICE |                                   STARTUP |                                   ONCALL } )                  } ]  ,VERSION={ version | *HIGHEST-EXISTING | *UPPER-LIMIT }

lmodname	Name of the load module up to 32 characters in length This name is subject to the same rules as the element names of a program library (see also "Format of names").
ALTERNATE-LIBRARIES=
	This is used to control the autolink function when dynamically linking the private slice of the load module.
NO	The autolink function is not executed when linking the load module. Default: NO
YES	The BLS autolink function is activated. For instance, if a load module requires other RTS modules for exchange purposes and these have not yet been loaded into memory, this function is used to load these RTS modules dynamically. Before starting the UTM application, the required RTS libraries must be reserved with Linkname BLSLIBnn (00 <= nn <= 99). If open external references cannot be resolved by the loaded modules, these libraries are then searched in ascending order (as specified in nn) for appropriate definitions when dynamically loading the load modules. ALTERNATE-LIBRARIES=YES may only be used to dynamically load RTS modules and not to dynamically load user programs. Further information on the Autolink function can be found in the openUTM manual “Using UTM Applications on BS2000 Systems”. The operand values LOAD-MODE=STATIC / (POOL,poolname,NO-PRIVATE-SLICE) cannot be combined with ALTERNATE-LIBRARIES=YES. Such a combination will be rejected by the KDCDEF run.
LIB=	libname Program library from which the load module is to be loaded dynamically.  libname can be up to 54 characters in length. If LOAD-MODE = STATIC, the LIB= operand is ignored. In all other cases, you must assign a value to LIB= either in the LOAD-MODULE statement or in a preceding DEFAULT statement.
LOAD-MODE=	Load mode of the load module
STARTUP	The load module is loaded dynamically as an independent unit when the application is started. External references from the subsystem, from class 3/4 memory, and from all other modules of the UTM application which are already loaded are resolved. For runtime system functions, see also the description of the operand ALTERNATE-LIBRARIES=YES. Load modules which are generated with LOAD-MODE=STARTUP and which contain TCB entries must not be exchanged during runtime. Default: STARTUP
ONCALL	The load module is loaded dynamically as an independent unit the first time a program unit or conversation exit assigned to the load module is called. External references from class 3/4 memory and from all other modules of the UTM application which are already loaded are resolved. Load modules containing TCB entries must not be generated with LOAD-MODE=ONCALL. If you are working with several processes, this load module must not be overwritten in the library LIB=libname during runtime. Otherwise, different versions of the load module will be executed during the application run.
STATIC	The load module must be linked in statically to the application program.
(POOL,poolname, NO-PRIVATE-SLICE)
	The memory pool is defined using the MPOOL statement. poolname can be up to 50 characters in length. When the application is started, the load module is loaded into the common memory pool poolname. It is not divided into public and private slices. A private slice is therefore not linked (even statically) into the application program.
(POOL,poolname, STARTUP)
	When the application is started, the public slice of the load module is loaded into the common memory pool poolname. The private slice belonging to the load module is then loaded into the local task memory.
(POOL,poolname, ONCALL)
	When the application is started, the public slice of the load module is loaded into the common memory pool poolname. The private slice belonging to the load module is then loaded into the local task memory when the first program unit assigned to this load module is called. Only external references from class 3/4 memory, from the subsystems, and from the local memory pool are resolved.
VERSION=version | *HIGHEST-EXISTING | *UPPER-LIMIT
	Version of the load module. version can be up to 24 characters in length.
*UPPER-LIMIT	If VERSION=*UPPER-LIMIT (or VERSION=@) is specified then the BLS addresses the load module lmodname in a PLAM library, which was last entered in this PLAM library without an explicit version specification. If you work with explicit versions in LMS, you cannot use @ as the load module version. The rules governing the versions of elements in a program library also apply to name allocation. However, there is one limitation: if version contains the character “.” then the version must start with a letter.
*HIGHEST-EXISTING	Every time the application is started and at every application exchange, the highest version of this module that exists in the library is loaded, i.e. For the first task (application start) or the initiating task (before application exchange), UTM determines the highest current element version for all load modules generated with VERSION=*HIGHEST-EXISTING. This element version is then also used to load modules that are not loaded until later, e.g. because they are generated with LOAD-MODE=ONCALL. When starting follow-up tasks for an application and when reloading the application program after a PEND ER, the version of this module that is loaded is the one that is already loaded by the other tasks in the application or that was loaded in this task before the PEND ER. For LOAD-MODULE statements generated with LOAD-MODE=STATIC, specifying VERSION=*HIGHEST-EXISTING is not permitted.