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
- Compile:
xlc –c –qasm example.c
- Link:
xlc example.o
- Run:
a.out
Note: You can combine steps 1 and 2 into one step:
- Compile and link:
xlc –qasm example.c
- Run:
a.out
Example 2. Building an application with METAL under z/OS UNIX System Services
- Compile:
xlc -qmetal -S example.c
- Assemble:
as example.s
- Link:
ld –e main example.o
- 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
//jobcard information…
//PROC JCLLIB ORDER=(CBC.SCCNPRC, CEE.SCEEPROC)
//*-------------------------------------------------------------------
//* Compile step
//*-------------------------------------------------------------------
//COMP EXEC EDCC,
// OUTFILE='HLQ.OBJECT(EXAMPLE),DISP=SHR',
// CPARM='ASM'
//STEPLIB DD DSN=CBC.SCCNCMP,DISP=SHR
// DD DSN=CEE.SCEERUN,DISP=SHR
// DD DSN=CEE.SCEERUN2,DISP=SHR
// DD DSN=ASM.SASMMOD1,DISP=SHR
//COMPILE.SYSIN DD DATA,DLM='/>'
int main(void) {
int a=10, b=45 ;
__asm(" AR %0,%1 " :"+r"(a) :"r"(b));
return a;
}
/>
//*-------------------------------------------------------------------
//* Link step
//*-------------------------------------------------------------------
//LINK EXEC CEEWL,
// PARM= AMODE=31,CASE=MIXED
//SYSLMOD DD DSN=HLQ.LOAD(EXAMPLE),DISP=SHR
//OBJECT DD DSN=HLQ.OBJECT,DISP=SHR
//SYSLIN DD *
INCLUDE OBJECT(EXAMPLE)
/*
//SYSPRINT DD SYSOUT=*
//*-------------------------------------------------------------------
//* Run step
//*-------------------------------------------------------------------
//GO EXEC PGM=EXAMPLE
//STEPLIB DD DSN=HLQ.LOAD,DISP=SHR
|
Listing 2. JCL that uses cataloged procedure EDCCB to build the ASM application
//jobcard information…
//PROC JCLLIB ORDER=(CBC.SCCNPRC)
//*-------------------------------------------------------------------
//* Compile and bind step
//*-------------------------------------------------------------------
//COMP EXEC EDCCB,
// OUTFILE='HLQ.LOAD(EXAMPLE),DISP=SHR',
// CPARM='ASM'
//STEPLIB DD DSN=CBC.SCCNCMP,DISP=SHR
// DD DSN=CEE.SCEERUN,DISP=SHR
// DD DSN=CEE.SCEERUN2,DISP=SHR
// DD DSN=ASM.SASMMOD1,DISP=SHR
//COMPILE.SYSIN DD DATA,DLM='/>'
int main(void) {
int a=10, b=45 ;
__asm(" AR %0,%1 " :"+r"(a) :"r"(b));
return a;
}
/>
//*-------------------------------------------------------------------
//* Run step
//*-------------------------------------------------------------------
//GO EXEC PGM=EXAMPLE
//STEPLIB DD DSN=HLQ.LOAD,DISP=SHR
|
Listing 3. JCL that uses cataloged procedure EDCCBG to build and run the ASM application
//jobcard information…
//PROC JCLLIB ORDER=(CBC.SCCNPRC)
//*-------------------------------------------------------------------
//* Compile, bind and run
//*-------------------------------------------------------------------
//CBG EXEC EDCCBG,
// CPARM='ASM'
//STEPLIB DD DSN=CBC.SCCNCMP,DISP=SHR
// DD DSN=CEE.SCEERUN,DISP=SHR
// DD DSN=CEE.SCEERUN2,DISP=SHR
// DD DSN=ASM.SASMMOD1,DISP=SHR
//COMPILE.SYSIN DD DATA,DLM='/>'
int main(void) {
int a=10, b=45 ;
__asm(" AR %0,%1 " :"+r"(a) :"r"(b));
return a;
}
/>
|
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
//jobcard information...
//PROC JCLLIB ORDER=(CBC.SCCNPRC)
//*-------------------------------------------------------
//* Compile step
//*-------------------------------------------------------
//COMP EXEC EDCC,
// OUTFILE='HLQ.ASMSRC(EXAMPLE),DISP=SHR',
// CPARM='METAL'
//COMPILE.SYSIN DD DATA,DLM='/>'
int main(void) {
int a=10, b=45 ;
__asm (" AR %0,%1 " :"+r"(a) :"r"(b));
return a;
}
/>
//*-------------------------------------------------------
//* Assembly step
//*-------------------------------------------------------
//ASMC EXEC ASMAC
//SYSIN DD DSN=HLQ.ASMSRC(EXAMPLE),DISP=SHR
//SYSLIN DD DSN=HLQ.OBJECT(EXAMPLE),DISP=SHR
//*-------------------------------------------------------
//* Link step
//*-------------------------------------------------------
//LINK EXEC PGM=IEWL,
// PARM= AMODE=31,CASE=MIXED
//SYSLMOD DD DSN=HLQ.LOAD(EXAMPLE),DISP=SHR
//OBJECT DD DSN=HLQ.OBJECT,DISP=SHR
//SYSLIN DD DATA,DLM='/>'
INCLUDE OBJECT(EXAMPLE)
ENTRY main
/>
//SYSPRINT DD SYSOUT=*
//*-------------------------------------------------------
//* Run step
//*-------------------------------------------------------
//GO EXEC PGM=EXAMPLE
//STEPLIB DD DSN=HLQ.LOAD,DISP=SHR
|
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
1 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:
- ASMLIB compiler option
- ASMLIB DDname statement
- 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
//ASMLIB DD DSN=SYS1.MACLIB,DISP=SHR
// DD DSN=HLQ.MYMACLIB,DISP=SHR
// DD PATH='/hlq/mymacrolib',
// PATHOPTS=(ORDONLY,ONONBLOCK),
// PATHMODE=(SIRUSR,SIXUSR),
// FILEDATA=TEXT
|
Result: the compiler uses the following search sequence:
- Data set SYS1.MACLIB
- Data set HLQ.MYMACLIB
- Directory /hlq/mymacrolib
Listing 6. Example of ASMLIB compiler options and DDname
//COMP EXEC EDCC,
// CPARM='ASM OPTFILE(DD:XOPTS)'
//XOPTS DD DATA,DLM='/>'
ASMLIB(//'HLQ.MYMLIB1',/hlq/mymacrolib1)
NOASMLIB
ASMLIB(//'HLQ.MYMLIB2',/hlq/mymacrolib2)
/>
//ASMLIB DD DSN=SYS1.MACLIB,DISP=SHR
// DD DSN=HLQ.MYMACLIB,DISP=SHR
// DD PATH='/hlq/mymacrolib',
// PATHOPTS=(ORDONLY,ONONBLOCK),
// PATHMODE=(SIRUSR,SIXUSR),
// FILEDATA=TEXT
|
Result: the compiler uses the following search sequence:
- Data set HLQ.MYMLIB2
- Directory /hlq/mymacrolib2
- Data set SYS1.MACLIB
- Data set HLQ.MYMACLIB
- 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
Related topics