XPLINK | NOXPLINK

Pragma equivalent

None.

Purpose

Uses a z/OS® linkage specifically designed to increase performance.

Syntax

Defaults

NOXPLINK
For LP64, the default is XPLINK.
For BACKCHAIN, the default is NOBACKCHAIN.
For CALLBACK, the default is NOCALLBACK.
For GUARD, the default is GUARD.
For OSCALL, the default is NOSTACK.
For STOREARGS, the default is NOSTOREARGS. If DEBUG and NOOPTIMIZE are specified, the default is STOREARGS.

Parameters

BACKCHAIN | NOBACKCHAIN

If you specify BACKCHAIN, the compiler generates a prolog that saves information about the calling function in the stack frame of the called function. This facilitates debugging using storage dumps. Use this suboption in conjunction with STOREARGS to make storage dumps more useful.

CALLBACK | NOCALLBACK

XPLINK(CALLBACK) is primarily intended to enable function pointer calls across XPLINK DLLs and non-XPLINK programs. With XPLINK, function calls are supported across a DLL boundary with certain restrictions. In particular, if a function pointer is created by a non-XPLINK caller pointing to an XPLINK function, it can be passed as an argument via an exported function into the DLL, which can then use it as callback. This is because the compiler knows about the function pointer argument and is able to insert code to fix-up the function pointer. However, non-XPLINK function pointers passed into the DLL by other means are not supported. If you specify CALLBACK, all calls via function pointers will be considered potentially incompatible, and fix-up code will be inserted by the compiler at the locations of the incompatible DLL callbacks through function pointers to assist the call. The application will be impacted by a performance penalty. In an XPLINK(NOCALLBACK) compilation, if a function pointer is declared using the__callback qualifier keyword, the compiler will insert fix-up code to assist the call. For more information on The __callback type qualifier, see z/OS XL C/C++ Language Reference.

Note: In LP64 mode, the only linkage supported is XPLINK. Do not use XPLINK(CALLBACK) in LP64 mode.

GUARD | NOGUARD

If you specify NOGUARD, the compiler generates an explicit check for stack overflow, which enables the storage runtime option. Using NOGUARD causes a performance degradation at run time, even if you do not use the Language Environment® runtime STORAGE option.

OSCALL(NOSTACK| UPSTACK| DOWNSTACK)

This suboption directs the compiler to use the linkage (OS_NOSTACK, OS_UPSTACK, or OS_DOWNSTACK) as specified in this suboption for any #pragma linkage(identifier, OS) calls in your application.

Note: The OSCALL suboption should only be specified when the ILP32 compiler option is also specified.

This value causes the compiler to use the following linkage wherever linkage OS is specified by #pragma linkage in C, or the extern keyword in C++:

OSCALL suboption: Linkage specified in #pragma linkage/extern keyword
NOSTACK: OS_NOSTACK
UPSTACK: OS_UPSTACK
DOWNSTACK: OS_DOWNSTACK

For example, since the default of this option is NOSTACK, any #pragma linkage(identifier,OS) in C code, works just as if #pragma linkage(identifier,NOSTACK) had been specified.

The abbreviated form of this suboption is OSCALL(N | U | D).

This suboption only applies to routines that are referenced but not defined in the compilation unit.

STOREARGS| NOSTOREARGS

If you specify the STOREARGS suboption, the compiler generates code to store arguments that are normally only passed in registers, into the caller's argument area. This facilitates debugging using storage dumps. Use this suboption in conjunction with the BACKCHAIN suboption to make storage dumps more useful. Note that the values in the argument area may be modified by the called function.

The STOREARGS suboption is turned on by default when the DEBUG option is specified with the NOOPTIMIZE option. If any level of the OPTIMIZE option is specified, you need to explicitly specify the STOREARGS suboption. If any level of the OPTIMIZE option is specified together with XPLINK(NOSTOREARGS), parameter values will not be provided for function parameters passed in registers.

The abbreviated form of this suboption is STOR.

Usage

Using the XPLINK option increases the performance of C/C++ routines by reducing linkage overhead and by passing function call parameters in registers. It supports both reentrant and non-reentrant code, as well as calls to functions exported from DLLs.

The extra performance linkage resulting from XPLINK is a common linkage convention for C and C++. Therefore, it is possible for a C function pointer to reference a non-"extern C" C++ function. It is also possible for a non-"extern C" C++ function to reference a C function pointer. With this linkage, casting integers to function pointers is the same as on other platforms such as AIX®, making it easier to port applications to z/OS using the C/C++ compiler.

You can not bind XPLINK object decks together with non-XPLINK object decks, with the exception of object decks using OS_UPSTACK or OS_NOSTACK. XPLINK parts of an application can work with non-XPLINK parts across DLL and fetch() boundaries.

When compiling using the XPLINK option, the compiler uses the following options as defaults:

CSECT()
GOFF
LONGNAME
NORENT

You may override these options. However, the XPLINK option requires the GOFF option. If you specify the NOGOFF option, the compiler issues a warning message and promotes the option to GOFF.

In addition, the XPLINK option requires that the value of ARCH must be 2 or greater. The compiler issues a message if you specify ARCH(0) or ARCH(1) with XPLINK and forces the value of ARCH to be 2.

Note: When using XPLINK and source files with duplicate file names, the linker may emit an error and discard one of the code sections. In this case, turn off the CSECT option by specifying NOCSECT.

To build a non-XPLINK C++ application, you can use the Standard C++ Library. It only supports dynamic binding by linking side-decks from CEE.SCEELIB(C128N). In addition, for iostream classes, you can either link the USL iostream Class Library objects from CBC.SCLBCPP or use the side-deck from CBC.SCLBSID(IOSTREAM) for the DLL version. If you are using USL iostream classes, you must ensure that the iostream header files are resolved from CEE.SCEEH.H.

To get the proper data set allocation at prelink/link time, the following c++ or cxx environment variables, if exported, should include the required concatenations. If they are unset, these variables take the default values, which already include the concatenations.

For static binding with USL iostream objects:

_CXX_PSYSIX="{_CXX_PLIB_PREFIX}.SCEELIB(C128N)"

_CXX_PSYSLIB="{_CXX_PLIB_PREFIX}.SCEEOBJ:{_CXX_PLIB_PREFIX}.SCEECPP:
  {_CXX_CLASSLIB_PREFIX}.SCLBCPP"

_CXX_LSYSLIB="{_CXX_PLIB_PREFIX}.SCEELKEX:{_CXX_PLIB_PREFIX}.SCEELKED"

For USL iostream DLL:

 _CXX_PSYSIX="{_CXX_CLASSLIB_PREFIX}.SCLBSID(IOSTREAM):
  {_CXX_PLIB_PREFIX}.SCEELIB(C128N)"

 _CXX_PSYSLIB="{_CXX_PLIB_PREFIX}.SCEEOBJ:{_CXX_PLIB_PREFIX}.SCEECPP"

 _CXX_LSYSLIB="{_CXX_PLIB_PREFIX}.SCEELKEX:{_CXX_PLIB_PREFIX}.SCEELKED"

For building without USL iostream DLL:

 _CXX_PSYSIX="{_CXX_PLIB_PREFIX}.SCEELIB(C128N)"

 _CXX_PSYSLIB="{_CXX_PLIB_PREFIX}.SCEEOBJ:{_CXX_PLIB_PREFIX}.SCEECPP"

 _CXX_LSYSLIB="{_CXX_PLIB_PREFIX}.SCEELKEX:{_CXX_PLIB_PREFIX}.SCEELKED"

The usage status of this option is inserted in the object file to aid you in diagnosing a problem with your program.

IPA effects

The IPA compile step generates information for the IPA link step. The IPA information in an IPA object file is always generated using the XOBJ format.

This option affects the IPA optimized object module that is generated by specifying the IPA(OBJECT) option. The object format used to encode this object depends on the GOFF option.

The IPA link step accepts the XPLINK option, but ignores it. This is because the linkage convention for a particular subprogram is set during source analysis based on the compile options and #pragmas. It is not possible to change this during the IPA link step.

The IPA link step links and merges the application code. All symbol definition and references are checked for compatible attributes, and subprogram calls are checked for compatible linkage conventions. If incompatibilities are found, a diagnostic message is issued and processing is terminated.

The IPA link step next optimizes the application code, and then divides it into sections for code generation. Each of these sections is a partition. The IPA link step uses information from the IPA compile step to determine if a subprogram can be placed in a particular partition. Only compatible subprograms are included in a given partition.

The value of the XPLINK option for a partition is set to the value of the first subprogram that is placed in the partition. The partition map sections of the IPA link step listing and the object module display the value of the XPLINK option.

Partitions with the XPLINK option are always generated with the GOFF option.

Predefined macros

__XPLINK__ is predefined to a value of 1 when the XPLINK compiler option is in effect; otherwise, it is undefined.