Metal C and MVS linkage conventions

Because Metal C follows MVS™ linkage conventions, it enables the compiler-generated code to interoperate directly with the existing code base to facilitate the following operations:

Passing parameters. See Parameter passing.
Returning values. See Return values.
Setting up function save areas. See Function save areas.

For detailed information about MVS linkage conventions, see the topic about linkage conventions in z/OS MVS Programming: Assembler Services Guide.

Parameter passing

The pointer to the parameter list is in GPR 1.

The parameter list is divided into slots.

The size of each slot depends on the addressing mode:
- For 31-bit mode (AMODE 31), each slot is four bytes in length.
- For 64-bit mode (AMODE 64), each slot is eight bytes in length.
Metal C derives the content of each slot from the function prototype, which follows C by-value semantics (that is, the value of the parameter is passed into the slot).
Notes:
1. If a parameter needs to be passed by reference, the function prototype must specify a pointer of the type to be passed.
2. Under AMODE 31 only: The high-order bit is set on the last parameter if both of the following are true:
  - The called function is a variable arguments function.
  - The last parameter passed is a pointer.

Return values

For any addressing mode, integral type values are returned in GPR 15. Under AMODE 31 only, a 64-bit integer value is returned in GPR 15 + GPR 0 (that is, the high-half of the 64-bit value is returned in GPR 15 and the low-half is returned in GPR 0). All other types are returned in a buffer whose address is passed as the first parameter.

Function save areas

GPR 13 contains the pointer to the dynamic storage area (DSA).

The DSA includes:

72-byte save area size for an AMODE 31 function.
Parameter area for calling other functions. The default pointer size for a parameter or return value is based on the amode attribute of the function prototype.
Temporary storage that is preallocated for the compiler-generated code and the user-defined automatic variables.

The save area is set up at the beginning of the DSA.

If the function calls only primary-mode functions, the save area format depends on the AMODE:

Under AMODE 31, the save area takes the standard 18-word format.
Under AMODE 64, the save area takes the 36-word F4SA format and the compiler will generate code to set up the F4SA signature in the second word of the save area.

If the function needs to call an AR-mode function, the save area will take the 54-word F7SA format, regardless of the addressing mode.

The F4SA signature generation can be suppressed by setting the &CCN_SASIG global SET symbol to 0 in your prolog code. For information about the &CCN_SASIG global SET symbol, see Table 2 User modifiable global SET symbols.

NAB linkage extension

Metal C code needs to use dynamic storage area (DSA) as stack space. Each time a function is called, its prolog code acquires this space and, when control is returned to the calling function, its epilog code releases the stack space.

Metal C avoids excessive acquisition and release operations by providing a mechanism that allows a called function to rely on pre-allocated stack space. This mechanism is the next available byte (NAB). All Metal C runtime library functions, as well as functions with a default prolog code, use it and expect the NAB address to be set by the calling function. The code that is generated to call a function includes the setup instructions to place the NAB address in the "Address of next save area" field in the save area. The called function simply goes to the calling function's save area to pick up the NAB address that points to its own stack space. As a result, the called function does not need to explicitly obtain and free its own stack space.

Note: If usage of the NAB linkage extension requires more stack space than has been allocated, there will be unexpected results. The program must establish a DSA that is large enough to ensure the availability of stack space to all downstream programs. Downstream programs include all functions that are defined in the program as well as the library functions listed in Function stack requirements.

The location of the "Address of next save area" field depends on the save area format:

In the standard 72-byte save area, it is the third word.
In the F4SA or F7SA save area, it is the 18th doubleword.