CEELOAD macro — Dynamically load a Language Environment-conforming routine

CEELOAD is used to dynamically load a Language Environment-conforming routine. It does not create a nested enclave, so the target of CEELOAD must be a subroutine.

There is no corresponding service to delete Language Environment-conforming routines. You should not use system services to delete modules that you load using CEELOAD; during thread (if SCOPE=THREAD) or enclave (if SCOPE=ENCLAVE) termination, Language Environment deletes modules loaded by CEELOAD.

Using CEELOAD imposes restrictions on further dynamic loading or dynamic calls or fetches; results are unpredictable if these rules are violated.

You cannot dynamically load a routine with CEELOAD that has already been dynamically loaded by CEELOAD or has been fetched or dynamically called.
You cannot fetch or dynamically call a routine that has already been dynamically loaded by CEELOAD.

If CEELOAD completes successfully, the address of the loaded routine is found in R15. You can then invoke the routine using BALR 14,15 (or BASSM 14,15).

Language Environment returns the address of the target routine with the high-order bit indicating the addressing mode (AMODE) of the routine. Language Environment-enabled programs return in the AMODE in which they are entered. Because Language Environment does not provide any AMODE switching on behalf of the target routine, you must provide any necessary AMODE switching code.

The macro invocation destroys the following registers:

R0
R1
R14
R15 (upon return, contains the target address)

When the macro code is expanded and run, the following assumptions are made:

R12 points to the CAA.
R13 has a standard Language Environment DSA available.


Syntax

>>-label--CEELOAD--+---------------------+--,------------------->
                   +-NAME=--name---------+      
                   '-NAMEADDR=--nameaddr-'      

>--+---------------+--,--+-----------------+--,----------------->
   +-SCOPE=ENCLAVE-+     '-FEEDBACK=fbcode-'      
   '-SCOPE=THREAD--'                              

>--+--------------------+--------------------------------------><
   +-MF=I---------------+   
   +-MF=L---------------+   
   '-MF=(E,--ctrl_addr)-'

label

The assembler label you give to this invocation of the macro. A label is required if MF=L; otherwise it is optional.

NAME=

The name of the entry point to be loaded by Language Environment. If MF=I or MF=L, you must specify either NAME or NAMEADDR, but not both.

NAMEADDR=

The address of a halfword-prefixed name that should be loaded by Language Environment. This can be an A-type address or a register (register 2 through 11). If MF=I or MF=L, you must specify either NAME or NAMEADDR, but not both. The address of the name can be specified as a register using parentheses ().

SCOPE=THREAD

Indicates that the load is to be scoped to the thread level. Modules loaded at the thread level are deleted automatically at thread termination.

SCOPE=ENCLAVE

Indicates that the load is to be scoped to the enclave level. Modules loaded at the enclave level are deleted automatically at enclave termination. SCOPE=ENCLAVE is the default.

FEEDBACK=

The name of a variable to contain the resulting 12-byte feedback token. If you omit this parameter, any nonzero feedback token that results is signaled. The following symbolic conditions might be returned from this service:

Symbolic feedback code	Severity	Message number	Message text
CEE000	0	—	The service completed successfully.
CEE3DC	3	3500	Not enough storage was available to load `module-name`.
CEE3DD	3	3501	The module `module-name` was not found.
CEE3DE	3	3502	The module name `module-name` was too long.
CEE3DF	3	3503	The load request for module `module-name` was unsuccessful.
CEE39K	1	3380	The target load module was not recognized by Language Environment.
CEE38M	3	3350	CEE3ADM or CEE3MBR could not find the event handler.
CEE38N	3	3351	CEE3ADM or CEE3MBR could not properly initialize the event handler.
CEE38V	2	3359	The module or language list is not supported in this environment.

MF=I

Indicates the immediate form of the macro. The immediate form generates an inline parameter list, and generates nonreentrant code.

MF=L

Indicates the list form of the macro. A remote control program parameter list for the macro is defined, but the service is not invoked. The list form of the macro is usually used in conjunction with the execute form of the macro.

MF=(E, ctrl_addr)

Indicates the execute form of the macro. The service is invoked using the remote control program parameter list addressed by ctrl_addr (normally defined by the list form of the macro).

Only one of the MF=I, MF=L, or MF=(E, ctrl_addr) parameters can be coded for the same macro invocation. If none is coded, the immediate form of the macro is used.

The following example illustrates an invocation of the CEELOAD macro.

CLOADTST CEEENTRY MAIN=YES,PPA=LEPPA,AUTO=DSALGTH
********************************************************
* Copy parameters to be passed to CEELOAD
********************************************************
MVC LOADPL(PLLEN),PLLIST
********************************************************
* Invoke CEELOAD to load module HIWORLD
********************************************************
CEELOAD MF=(E,LOADPL)           LOAD ROUTINE
********************************************************
* Pass control to HIWORLD
********************************************************
BALR 14,15                      INVOKE ROUTINE
********************************************************
* Invoke CEETERM to return to Caller
********************************************************
CEETERM RC=(15),MF=(E,DSARPL)   BACK TO CALLER
********************************************************
* Constants
********************************************************
PLLIST   CEELOAD MF=L,NAME=HIWORLD,SCOPE=THREAD
PLLEN    EQU *-PLLIST
LEPPA   CEEPPA ,
********************************************************
* Mappings
********************************************************
CEECAA ,                 LE/370 COMMON ANCHOR AREA
********************************************************
* Workarea and DSA
********************************************************
CEEDSA ,                 LE/370 DYNAMIC STORAGE AREA
DSARPL CEETERM MF=L
DS    0F
LOADPL   DS    XL(PLLEN)
DSALGTH  EQU   *-CEEDSA
END

Usage notes:

Language Environment issues the appropriate load command according to the Language Environment search order (described in Program library definition and search order) and performs the necessary dynamic updates to accommodate the new load module.
Language Environment performs any language-related initialization required.
You cannot use CEELOAD to load a program object which was created using the program management binder. You can, however, use CEEFETCH for loading program objects.
You cannot use CEELOAD to load C++ modules, because C++ modules are always compiled RENT and have writable static that is not switched when control passes between functions.
#pragma linkage (xxx,fetchable) should not be used. If a module is linked with #pragma linkage (xxx,fetchable), it will have CEESTART as an entry point, which is not allowed, and the module could have writable static requirements that would not be handled using CEELOAD.
When using CEELOAD to load a C module, the function or functions within this module must not be designated as fetchable. The #pragma linkage (xxx,fetchable) directive should not be coded in the module. Instead, such modules should be fetched using the fetch() function.
#pragma linkage (xxx,COBOL) should not be used.
For C users, the load module entry point must be the function name, and cannot be CEESTART (nested environment initialization causes Language Environment to abend). You cannot use CEELOAD to load any function that uses writable static. The module must be built NORENT and the entry point must be a C function, not CEESTART.
This macro should not be used for DLLs.