CEEFETCH macro — Dynamically load a routine

CEEFETCH is used to dynamically load a routine.

Use the CEERELES macro to delete routines that are loaded with CEEFETCH. Do not use system services to delete modules that you load using CEEFETCH; during thread (if SCOPE=THREAD), enclave (if SCOPE=ENCLAVE), or process (if SCOPE=PROCESS) termination, Language Environment deletes modules that are loaded by CEEFETCH.

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

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.

     LA     2,RESET  SAVE BRANCH ADDRESS AND CURRENT
     BSM    2,0      AMODE IN REGISTER 2
     BASSM 14,15     CALL COBOL PROGRAM
     BSM    0,2      BRANCH AND RESTORE AMODE FROM REG. 2
RESET DS     OH

Syntax

>>-label--CEEFETCH--+---------------------+--,------------------>
                    +-NAME=--name---------+      
                    +-NAMEADDR=--nameaddr-+      
                    '-ENTRYPT=--entrypt---'      

   .-SCOPE=ENCLAVE-----.     .-SEARCH=MVS--------.      
>--+-------------------+--,--+-------------------+--,----------->
   +-+--------------+--+     +-+------------+----+      
   | '-SCOPE=THREAD-'  |     | '-SEARCH=HFS-'    |      
   '-+---------------+-'     +-+---------------+-+      
     '-SCOPE=PROCESS-'       | '-SEARCH=MVSHFS-' |      
                             '-+---------------+-'      
                               '-SEARCH=HFSMVS-'        

>--+---------------+--,--+---------------------+--,------------->
   '-TOKEN=--token-'     '-FTCHINFO=--ftchinfo-'      

                             .-MF=I-----------------.   
>--+-------------------+--,--+----------------------+----------><
   '-FEEDBACK=--fbcode-'     +-+------+-------------+   
                             | '-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 is specified; otherwise, it is optional.

NAME=name

The name of the entry point to be loaded by Language Environment. The maximum length of name is eight characters. If a longer name is needed, the NAMEADDR parameter must be used. You cannot specify NAME and NAMEADDR together.

NAMEADDR=nameaddr

The address of a halfword-prefixed name that should be loaded by Language Environment. A halfword prefix name is a string where the first two bytes identify the length of a name string and are followed by the name string itself. This can be an A-type address or a register (register 2 through 11). The address of the name can be specified as a register using parentheses (). The maximum length of the name is 1023 characters. You cannot specify NAME and NAMEADDR together.

ENTRYPT=entrypt

The name of a fullword address variable that contains the entry point for a module that was previously loaded or the register (enclosed in parentheses) containing the entry point for a module that was previously loaded. The NAME and NAMEADDR keywords are mutually exclusive with ENTRYPT. The SEARCH keyword is ignored when ENTRYPT is specified. The FTCHINFO keyword is required when ENTRYPT is specified. A corresponding “delete” using CEERELES can be done if CEEFETCH returns successfully.

SCOPE=THREAD

Indicates that the load is to be scoped to the thread level. Modules that are 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 that are loaded at the enclave level are deleted automatically at enclave termination. It is the default.

SCOPE=PROCESS

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

TOKEN=token

The name of a variable to contain the resulting 4-byte token. This variable must be passed to the CEERELES macro if the load module is to be deleted. If MF=I or MF=L are specified, you must specify TOKEN.

SEARCH=MVS

Indicates that only the MVS™ file system is to be searched for the load module. It is the default.

SEARCH=HFS

Indicates that only the HFS file system is to be searched for the load module.

SEARCH=MVSHFS

Indicates that the MVS file system is to be searched first and then the HFS file system for the load module.

SEARCH=HFSMVS

Indicates that the HFS file system is to be searched first and then the MVS file system for the load module.

FEEDBACK=fbcode

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.
CEE3N9	2	3817	The member event handler did not return a usable function pointer.
CEE38V	2	3359	The module or language list is not supported in this environment.
CEE3DV	3	3519	The version that is specified in the CEEFTCH control block passed to the CEEFETCH macro is not supported.
CEE3QS	1	3932	The system service CSVQUERY failed with return code <return_code> and reason code 0.

MF=I

Indicates the immediate form of the macro. The immediate form generates an inline parameter list and generates nonreentrant code. This is the default value.

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 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 (usually 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.

FTCHINFO=ftchinfo

The name of a fullword address variable that contains the address of a previously allocated FTCHINFO storage area or the register (enclosed in parentheses) containing the address of a pre-allocated FTCHINFO storage area, where the resulting module information is to be stored. The user must set the CEEFTCH_VERSION field in the FTCHINFO storage area. This keyword is useful for retrieving information about a target module whose characteristics are unknown. If the module is identified as a Language Environment® conforming AMODE 24 or AMODE 31 subroutine, then processing would be as normal, otherwise only a load of the target is attempted. Only an AMODE 24 or AMODE 31 target module can be recognized as a DLL. An AMODE 24 or AMODE 31 COBOL target is classified as a subroutine and follows the normal processing. The CEEFTCH macro provides the mapping for the FTCHINFO storage area. see the CEEFTCH macro — Generate a FTCHINFO mapping description for details about its contents.