CEEFETCH is used to dynamically load a routine.
Use the CEERELES macro to delete routines loaded with CEEFETCH.
You should 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 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.
For example:
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
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--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 containing the entry point
for a module that has been previously loaded or the register (enclosed
in parentheses) containing the entry point for a module that has been
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
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; this is the default.
- SCOPE=PROCESS
- Indicates that the load is to be scoped to the process level.
Modules 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 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; this 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 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 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 (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 containing 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 will be attempted. Only an AMODE
24 or AMODE 31 target module can be recognized as a DLL. An AMODE
24 or AMODE 31 COBOL target will be classified as a subroutine and
will follow 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.
Usage notes: - Language Environment issues
the appropriate load command according to Language Environment search
order (described in Program library definition and search order), and
performs the necessary dynamic updates to accommodate the load module.
- Language Environment performs
any language-related initialization required.
- Any COBOL, PL/I, or Fortran module that will be fetched, dynamically
called, or CEEFETCHed more than once must be reentrant.
- When using CEEFETCH to fetch a C module, the C module must contain #pragma linkage (xxx,fetchable).
For exceptions to this rule, see the fetch() information
in z/OS XL C/C++ Runtime Library Reference.
- CEEFETCH can be used in a non-XPLINK Assembler
program to fetch an XPLINK-compiled
module. The fetched XPLINK-compiled
module must contain #pragma linkage(xxx,fetchable). The
address of the target routine returned by CEEFETCH in R15 contains
any necessary glue code to call an XPLINK routine
from non-XPLINK,
and can still be invoked using BALR 14,15. All rules and restrictions
on the environment imposed by XPLINK still
apply. See Using Extra Performance Linkage (XPLINK).
- This macro should not be used for DLLs.
- When using CEEFETCH to fetch a C++ module, the C++ module must
contain #pragma linkage(xxx,fetchable) directive and must be declared
extern "C". See z/OS XL C/C++ Runtime Library Reference for
more information.
- The Fortran compilers do not conform to the Language Environment interface
conventions, thus Fortran targets will not be recognized as Language Environment conforming.
See Fortran Migration Guide for further information.
- The contents returned in R15 after a call to CEEFETCH should not
be reused as input to a follow-up call to CEEFETCH. This scenario
could result in the issue of the CEE3932W message.
- In a multithread environment, using a CEEFETCH / BALR (or BASSM)
/ CEERELES sequence on more than one thread is not supported if the
target routine is the same COBOL routine, even when the COBOL routine
is enabled for multithreading. COBOL does not allow a CANCEL of a
routine that is active on another thread.
- In a multithread environment, using a CEEFETCH / BALR (or BASSM)
/ CEERELES sequence on more than one thread is not supported if the
target routine is the same PL/I routine.