Purpose
Identifies the entry point of modules
that are used in interlanguage calls from C programs as well as the
linkage or calling convention that is used on a function call.
The
directive also designates other entry points within a program that
you can use in a fetch operation.
Syntax
>>-#--pragma--linkage------------------------------------------->
>--(--identifier,--+-OS------------------------+--)------------><
+-FETCHABLE-----------------+
+-PLI-----------------------+
+-COBOL---------------------+
+-FORTRAN--+--------------+-+
| '-, RETURNCODE-' |
+-OS_DOWNSTACK--------------+
+-OS_UPSTACK----------------+
+-OS_NOSTACK----------------+
'-REFERENCE-----------------'
Parameters
- identifier
- The name of a function that is to be the entry point of the module,
or a typedef name that will be used to define the entry point. (See
below for an example.)
- FETCHABLE
- Indicates
that identifier can be used in a fetch operation.
A fetched XPLINK module must have its entry point defined with a #pragma
linkage(..., fetchable) directive.
- OS
- Designates identifier as
an OS linkage entry point. OS linkage is the basic linkage convention
that is used by the operating system. If the caller is compiled with
NOXPLINK, on entry to the called routine, its register 13 points
to a standard Language Environment® stack frame, beginning with a 72-byte save area.
The stack frame is compatible with Language Environment languages
that expect by-reference calling conventions and with the Language
Environment-supplied assembler prologue macro. If the caller
is compiled with XPLINK, the behavior depends on the OSCALL suboption
of the XPLINK compiler option. This suboption selects the behavior
for linkage OS from among OS_DOWNSTACK, OS_UPSTACK, and OS_NOSTACK
(the default). This means that applications which use linkage OS to
communicate among C or C++ functions will need source changes when
recompiled with XPLINK. See the description that follows for REFERENCE.
- PLI
- Designates identifier as
a PL/I linkage entry point.
- COBOL
- Designates identifier as
a COBOL linkage entry point.
- FORTRAN
- Designates identifier as
a FORTRAN linkage entry point.
RETURNCODE indicates to the compiler
that the routine named by identifier is
a FORTRAN routine, which returns an alternate return code. It also
indicates that the routine is defined outside the translation unit.
You can retrieve the return code by using the fortrc function.
If the compiler finds the function definition inside the translation
unit, it issues an error message. Note that you can define functions
outside the translation unit, even if you do not specify the RETURNCODE
keyword.
- OS_DOWNSTACK
- Designates identifier as an OS linkage
entry point in XPLINK mode with a downward growing stack frame.
If
the function identified by identifier is
defined within the translation unit and is compiled using the NOXPLINK
option, the compiler issues an error message.
- OS_UPSTACK
- Designates identifier as an OS linkage
entry point in XPLINK mode with a traditional upward growing stack
frame.
This linkage is required for a new XPLINK downward-stack
routine to be able to call a traditional upward-stack OS routine.
This linkage explicitly invokes compatibility code to swap the stack
between the calling and the called routines.
If the function
identified by identifier is defined within
the translation unit and is compiled using the XPLINK option, the
compiler issues an error message. Typically, the identifier will
not be defined in a compilation. This is acceptable. In this case,
it is a reference to an external procedure that is separately compiled
with NOXPLINK.
- OS_NOSTACK
- Designates identifier as
an OS linkage entry point in XPLINK mode with no preallocated stack
frame. An argument list is constructed containing the addresses of
the actual arguments. The size of the address is 4-byte for 31-bit
and 8-byte for 64-bit. Register 1 is set to point to this argument
list. For 31-bit only, the last item in this list has its high
order bit set. For integer type arguments, the value passed is widened
to the size of the int type, that is 4-byte. Register
13 points to a save area that may not be followed by z/OS® Language Environment control
structures, such as the NAB. The size of the save area is 72-byte
for 31-bit and 144-byte for 64-bit. Register 14 contains the
return address. Register 15 contains the entry point of the called
function.
- REFERENCE
- This is synonymous with OS_UPSTACK in non-XPLINK mode and synonymous
with OS_DOWNSTACK in XPLINK mode. Unlike the linkage OS, this is not
affected by the OSCALL suboption of XPLINK. Consider using this
option instead to make the source code portable between XPLINK and
non-XPLINK
Usage
You can use a typedef in a
#pragma
linkage directive to associate a specific linkage convention with
a function type. In the following example, the directive associates
the OS linkage convention with the typedef
func_t:
typedef void func_t(void);
#pragma linkage (func_t,OS)
This typedef can then be used
in C declarations wherever a function should have OS linkage. In the
following example:
func_t myfunction;
myfunction is
declared as having type
func_t, which is associated
with OS linkage;
myfunction would therefore have
OS linkage.
Related information
- The XPLINK option in the z/OS XL
C/C++ User's Guide.