XPLINK Assembler

The XPLINK support provided by the assembler macros EDCXPRLG and EDCXEPLG allows XPLINK C and C++ code to call routines that can be coded for performance, or to perform a function that can not be readily done in C/C++. The EDCXCALL macro allows XPLINK assembler to call routines in the same program object, or in a DLL. The following z/OS® Language Environment® books provide more information on XPLINK that may be useful to assembler programmers:

z/OS Language Environment Programming Guide — provides an overview of XPLINK and what it means to the application programmer. It also describes the Language Environment assembler support, including the CEEPDDA and CEEPLDA macros, which can be used to define and reference data from assembler.
z/OS Language Environment Writing Interlanguage Communication Applications — provides information on how assembler routines interact with routines coded in other high level languages.
z/OS Language Environment Debugging Guide — provides details on XPLINK, including information on building parameter lists for calling other XPLINK routines.

Coding XPLINK assembler routines differs from traditional non-XPLINK assembler in the following ways:

You use the EDCXPRLG and EDCXEPLG macros for entry/exit code, and the EDCXCALL macro to call other routines. These are documented in the section Using standard macros.
You use the following XPLINK register conventions within the XPLINK assembler routine:
- XPLINK parameter passing conventions: Registers 1, 2, and 3 are used to pass up to the first 3 integral values, and floating point registers will be used to pass floating point parameters.
- XPLINK DSA format: Note that the stack register (reg 4) is "biased". This means that you must add 2K (2048) to the stack register to get the actual start of the current routine's DSA. The z/OS Language Environment mapping macro CEEDSA contains a mapping of the XPLINK DSA, including the 2K bias (CEEDSAHP_BIAS). The caller's registers are saved in the DSA obtained by the callee. The callee's parameters (other than those passed in registers, if any), are built in the argument list in the callers DSA, and addressed there directly by the callee. There is no indirect access to the parameters via Register 1 as in OS linkage.
While EDCXPRLG and EDCXEPLG allow Language Environment conforming XPLINK assembler routines to be written, another alternative for XPLINK C/C++ callers is to designate the linkage as OS31_NOSTACK. For more information on OS31_NOSTACK see Using Linkage Specifications in C or C++. When the C/C++ caller designates the assembler routine as OS31_NOSTACK linkage, the assembler code can be written without using EDCXPRLG or EDCXEPLG (or any other Language Environment prolog or epilog macros). This can only be done when the assembler code has no dynamic stack storage requirements. With OS31_NOSTACK, standard OS linkage rules apply:
- Register 1 will be used to point to the parameter list.
- Register 13 will point to an 18 word savearea, provided to the callee for saving and restoring registers.
- Register 14 will be the return address for branching back to the caller.
- Register 15 will contain the address of the callee.

Table 1 shows the layout of the XPLINK interface. See z/OS Language Environment Vendor Interfaces for additional information about register usage and conventions, especially for details about passing parameters with XPLINK. For information on the registers which are saved in the register savearea of the XPLINK stack frame see z/OS Language Environment Programming Guide.

Table 1. Comparison of non-XPLINK and XPLINK register conventions
	Non-XPLINK	XPLINK
Stack Pointer	Reg 13	Reg 4 (biased)
Return Address	Reg 14	Reg 7
Entry point on entry	Reg 15	Reg 6 (not guaranteed; a routine may be called via branch relative)
Environment	Reg 0 (writeable static)	Reg 5
CAA Address	Reg 12	Reg 12
Input Parameter List	address in R1	Located at fixed offset 64 ('40'x) into the caller's stack frame (remember the 2K bias on R4). Additionally, any of General Registers 1, 2, and 3, and Floating Point Registers 0, 2, 4, and 6, may be used to pass parameters instead of the caller's stack frame.
Return code	Reg 15	R3 (extended return value in R1,R2)
Start address of callee's stack frame	Caller's NAB value	Caller's Reg 4 - DSA size
End address of callee's stack frame	Caller's NAB value + DSA size	Caller's Reg 4
Where caller's registers are saved	R0-R12 saved in caller's stack frame R13 saved in callee's stack frame R14-R15 saved in caller's stack frame	R0 not saved, not preserved R1-R3 not saved, not preserved R4 not saved, recalculated (or saved, restored) R5 not saved, not preserved R6 saved in callee's stack frame, not restored R7-R15 saved in callee's stack frame (R7 is the return register and is not guaranteed to be restored)