METAL | NOMETAL (C only)

Pragma equivalent

None.

Purpose

Generates HLASM code that has no Language Environment® runtime dependencies and follows the MVS™ linkage conventions for passing parameters, returning values, and setting up function save areas. The METAL option also enables the inlined assembly support using the GCC-style of __asm statements.

Syntax

Defaults

NOMETAL

Usage

With the METAL option, the XL C compiler generated code does not have dependencies on the services provided by the Language Environment. The METAL option also instructs the XL C compiler to generate code that follows the standard system linkage conventions described in the MVS Programming: Assembler Services Guide. Thus the METAL option enables the use of C as the language for system programming where the Language Environment is either unavailable or undesirable, for example, writing system user exits.

Using the METAL option can be viewed as a joint venture between the compiler and users. The compiler is responsible for generating the machine instructions that represent the C program. Users are responsible for providing the stack space (or the dynamic storage area) required by the C program. Users can decide if the stack space is provided by using the default prolog and epilog code generated by the compiler, or by supplying their own prolog and epilog code. Users are also given the facilities to embed assembly statements within the C program so, for example, system macros can be invoked.

As a result, when the METAL option is used the final code generated by the XL C compiler is in HLASM source code format. You need to invoke the assembler as an additional step to produce the object code.

A subset of the C library functions is provided for Metal C. For further information on programming with Metal C and the library that is provided, see z/OS Metal C Programming Guide and Reference.

You may need to switch addressing mode (AMODE) between programs. The default AMODE assigned by the XL C compiler is based on the LP64 compiler option or the ILP32 compiler option. AMODE 64 is assigned when LP64 is specified and AMODE 31 is assigned when ILP32 is specified. The METAL option enables the XL C compiler to generate code for calling an external function with an AMODE that is different from the default AMODE. This capability supports the creation of METAL C programs that require AMODE switching across functions. The resulting compiler generated code follows the linkage conventions expected by the called function, particularly in the areas of save area format and the parameter list width. You can use the amode31 function attribute to mark an AMODE 31 function or the amode64 function attribute to mark an AMODE 64 function in your source files. The __ptr64 qualifier can be used when the METAL option is specified so that a 64-bit pointer can be handled by an AMODE 31 function without dereferencing it. For more information on the amode31 function attribute, amode64 function attribute, and the __ptr64 qualifier, see z/OS XL C/C++ Language Reference. z/OS Metal C Programming Guide and Reference describes the impact of AMODE switching across functions on the save area chain in the user-supplied prolog or epilog code and the restrictions that apply to AMODE switching across functions.

Note: Some Metal C header files such as stdio.h have the same names as header files for the Language Environment C/C++ Runtime Library. To avoid including these, or inadvertently including any other headers supported by the LE library and not by Metal C, remove the non-Metal libraries from the search order. Depending on how you specify the system library search path, you need to remove other libraries from the SYSLIB concatenation of the compiler, or specify the NOSEARCH compiler option before pointing to /usr/include/metal/.

The METAL option disables support for packed-decimal and decimal floating-point data types.

When the METAL option is specified, the following options are not supported.

DFP
DLL
EXPORTALL
REPORT
STACKPROTECT
XPLINK

METAL sets the following as defaults:

ASM
CSECT
FLOAT(IEEE)
HGPR(PRESERVE)
NODEBUG(FORMAT(DWARF), NOHOOK, SYMBOL)
NOKEYWORD(ASM)
NOLONGNAME
NORENT

METAL ignores the following:

GOFF
INLINE when OPTIMIZE(0) is in effect
INLRPT
TARGET
All INLINE suboptions

METAL ignores the following:

#pragma linkage
#pragma variable

In the z/OS® UNIX System Services environment:

When using the -qmetal option or the -Wc,METAL option, the -S flag must be explicitly specified; otherwise, the compiler issues an error message.
Note: Starting from z/OS V1R13, you can no longer use the GENASM option with the c89 utility by specifying -Wc,GENASM. Use the -S option instead. For more information about the -S flag, see Options.
The as utility can be used to produce the required object code from the compiler-generated HLASM source code.

Notes:

The compiler-generated code does not establish code base registers.
Because of the flat name space and the case insensitivity required by HLASM, the compiler prepends extra qualifiers to user names to maintain uniqueness of each name seen by HLASM. This is referred to as name-encoding. For local symbols, HLASM also has the 63-character length limit. Name-encoded local symbols have a maximum of 63 characters. External symbols are not subject to the name-encoding scheme as they need to be referenced by the exact names.
The maximum length of an external symbol allowed by HLASM is 256 characters. You must ensure that all external symbols are acceptable to HLASM.
You must provide C library functions that are not provided by IBM if you need them.
It is your responsibility to ensure the correctness of your assembly code, including prolog and epilog code, and inlined assembly code.
When binding or linking, you may need to specify the ENTRY name.
No ASCII version of the Metal C runtime libraries is available, even though the ASCII compiler option is supported.
The HLASM GOFF option is required to assemble the compiler-generated code when you specify any of these compiler options: LONGNAME, RENT.

IPA effects

In the IPA compile step, only IPA(NOOBJECT) is allowed. The IPA compile phase only produces a binary IPA object as the output file. It does not produce object code or HLASM source code. Therefore, the IPA(OBJECT) or GENASM option cannot be used. On z/OS UNIX, the -S flag must not be specified; otherwise, the compiler issues a warning message and ignores the -S flag.

During the IPA link phase, all external references must be resolved. For Metal C, IPA does not attempt to convert external object modules or load modules into object code for the inclusion in the IPA produced program. You need to provide the same set of library data sets to both IPA link and the binder for symbol resolution.

If you supply your own prolog/epilog code using the PROLOG and EPILOG compiler options, IPA link will keep the relationship between the prolog/epilog code and the designated functions at the compilation unit level.

If you have #pragma insert_asm in your source file, IPA link will assume the strong connection between the string provided by the pragma and the functions in the source file. IPA link will not move functions defined in that source file to anywhere else.

The output file from the IPA link step is one single HLASM source file for the whole program, and the GENASM option is required. Under z/OS UNIX, the output HLASM source file resides in the directory where the IPA link took place. The default output file name for z/OS UNIX is a.s. In BATCH mode, the output HLASM source file goes in the data set allocated to DD SYSLIN in the IPA link step.

Note: The HLASM GOFF option is required because the IPA link step defaults to LONGNAME.

Predefined macros

__IBM_METAL__ is predefined to 1 when METAL is in effect; otherwise it is undefined.
__IBM_FAR_IS SUPPORTED__ is predefined to 1 when METAL is in effect; otherwise it is undefined.

Examples

For examples that describe how to use the METAL compiler option, see z/OS Metal C Programming Guide and Reference.

Related information

For more information about related compiler options, the as command, and the CDAHLASM utility, see: