#pragma linkage (C only)

Category

Object code control

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


1  # pragma linkage  ( identifier,
2.1 OS
2.1 FETCHABLE
2.1 PLI
2.1 COBOL
2.1  FORTRAN?  , RETURNCODE
2.1 OS_DOWNSTACK
2.1 OS_UPSTACK
2.1 OS_NOSTACK
2.1 REFERENCE
1 )

Defaults

C linkage.

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