C/C++ - Group home

There are two ways to use high-level languages in low-level programming for z/OS XLC C/C++ compiler.
Since z/OS V1R9 XL C, METAL C provided C language extensions to allow embedding High-Level Assembler (HLASM) instructions directly into the C programs. Starting with z/OS XL C/C++ V2.1.1, you can embed HLASM instructions in C/C++ programs. METAL C (referred to as METAL in this article) allows users to exploit MVS™ system services directly through system provided assembly macros. The latest inline assembly support (referred to as ASM in this article) allows embedding hardware instructions directly within the standard C and C++ programs with full language environment and run time library support. This article highlights the characteristics and the differences between ASM and METAL. It also shows how to use the ASMLIB option and data definition name (DDname) in conjunction with ASM to search for the assembler macros included in the source code.

ASM characteristics

• ASM is supported for both C and C++ compilers.
• ASM is easier for a user to generate the object code.
• ASM supports all compiler supported linkages including XPLINK and NOXPLINK.
• ASM supports all optimization levels including OPT(2), OPT(3), IPA, and HOT.
• ASM supports all addressing modes including ILP32 and LP64.
• The debug side file can be generated by the compiler if requested by the user.
• Full language environment runtime is available in ASM.

METAL characteristics

• METAL is supported for C only.
• METAL is used for system programming development.
• METAL uses MVS linkage convention.
• METAL supports all optimization levels including OPT(2), OPT(3), IPA, and HOT.
• METAL supports all addressing modes including ILP32 and LP64.
• There is no dependency on Language Environment (LE).
• METAL supports user specified function prolog and epilog.

ASM and METAL comparison

The major differences between ASM and METAL support are shown below:

Table 1. ASM and METAL comparison

Processing differences

The following examples use a simple program (example.c) to demonstrate how to use the ASM and alternatively, the METAL option to create the application. The return code from the execution of the application is 55.

example.c

int main (void) {
   int a=10, b=45 ;
   __asm (" AR %0,%1 " :"+r"(a) :"r"(b));
   return a;
}

Example 1. Building an application with ASM under z/OS UNIX System Services

1. Compile: xlc –c –qasm example.c
2. Link: xlc example.o
3. Run: a.out

Note: You can combine steps 1 and 2 into one step:

1. Compile and link: xlc –qasm example.c
2. Run: a.out

Example 2. Building an application with METAL under z/OS UNIX System Services

1. Compile: xlc -qmetal -S example.c
2. Assemble: as example.s
3. Link: ld –e main example.o
4. Run: a.out

Example 3. Building an application with ASM under z/OS batch

When the application is compiled with the ASM option, you can use the standard cataloged procedures for each step, or the combined cataloged procedures to build the application.

• Use EDCC to compile and CEEWL to link the program (see Listing 1).
• Use EDCCB to compile and link the program (see Listing 2).
• Use EDCCBG to compile, bind, and run the program (see Listing 3).

Listing 1. JCL that uses cataloged procedures EDCC and CEEWL to build the ASM application

Listing 2. JCL that uses cataloged procedure EDCCB to build the ASM application

Listing 3. JCL that uses cataloged procedure EDCCBG to build and run the ASM application

Example 4. Building an application with METAL under z/OS batch

When the application is complied with the METAL option, you cannot use the combined standard cataloged procedures to compile and bind the program. That is because the output from the compiler is HLASM source code that needs to be assembled by HLASM before the link step.

Listing 4. JCL that uses cataloged procedure EDCC and ASMAC to compile and assemble the METAL application

Other differences

There are some compiler options that can be used together with ASM or METAL during the compilation to enhance the inline assembly support. Table 2 shows which option can be used in conjunction with ASM or METAL

Table 2. Compatible compiler option

There are other differences in terms of keyword, predefined macros, and pragma support between ASM and METAL. Table 3 highlights the differences.

Table 3. Other technical differences

¹ If you want to use the keyword or token ASM in the embedded assembly statements, the token ASM can be accepted by doing one of the following:

• In the source code, add one of the following statements:
  • #define asm __asm
  • #define asm __asm__
• Specify compiler option KEYWORD(asm)

ASMLIB

There are three ways to instruct the compiler where to locate the macros that are included in the ASM statements:

1. ASMLIB compiler option
2. ASMLIB DDname statement
3. Both of the above, where compiler option takes precedence

Compiler option

This option gives the compiler the search paths for macro libraries. The specified macro library can be a Partitioned Data Set (PDS), a Partitioned Data Set Extended (PDSE), or a UNIX System Service (USS) directory, or a combination of all 3.

• NOASMLIB
  • NOASMLIB is the default option; it means no allocation for the ASMLIB DD.
  • Does not accept suboptions.
  • Clears all macro libraries specified in any previous ASMLIB options.
  • Does not deallocate ASMLIB DDname if it is allocated.
• ASMLIB(lib1,lib2,..)
  • Suboptions only accept fully qualified PDS names, PDSE names, and USS directories.
  • All data set names must start with //. For example, ASMLIB( //'SYS1.MACLIB').
• Multiple ASMLIB specifications result in the concatenation of the libraries in the order they are specified.

Examples

Table 4 shows how to search user defined and system macros through the ASMLIB compiler option.

Table 4. ASMLIB option usage examples

DDname

• Multiple DD statements that contain data sets and USS directories are allowed (see Listing 5).
• When the ASMLIB compiler option and ASMLIB DD statement are specified in the JCL at the same time, the libraries are concatenated as a search list. The compiler option takes precedence over the DDname (see Listing 6).

Listing 5. ASMLIB DDname examples

Result: the compiler uses the following search sequence:

1. Data set SYS1.MACLIB
2. Data set HLQ.MYMACLIB
3. Directory /hlq/mymacrolib

Listing 6. Example of ASMLIB compiler options and DDname

Result: the compiler uses the following search sequence:

1. Data set HLQ.MYMLIB2
2. Directory /hlq/mymacrolib2
3. Data set SYS1.MACLIB
4. Data set HLQ.MYMACLIB
5. Directory /hlq/mymacrolib

Note: HLQ.MYMLIB1 and /hlq/mymacrolib1 were cleared out by NOASMLIB.

Conclusion

The different inline assembly supports provided by the zOS XLC/C++ compiler are designed for different purposes. METAL C is meant for system programming development. ASM allows users to exploit the assembler macro libraries and hardware instructions in the standard Language Environment.

Acknowledgements

I would like to thank Rajan Bhakta and Milos Lalovic for their help and advice with this article.

Downloadable resources

• PDF of this content

Related topics

• z/OS XL C/C++ V2R1 User's guide (SC14-7307-01)
• z/OS V2R1 Metal C Programming Guide and Reference (SC14-7313-01)

​