Contents


Using inline assembly for z/OS XL C/C++ compiler

Two ways to use high-level languages in low-level programming

Comments

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
CharacteristicsASMMETAL
Supporting compiler C and C++ C
Controlling compiler options MVS: ASM
USS: -qasm
MVS: METAL
USS: -qmetal -S
Available release z/OS V2R1M1 z/OS V1R9
Hardware architecture All architecture levels ARCH(5) minimum
HLASM compiler requirement V2R1 HLASM plus APAR P121235
or
V2R2 HLASM
V1R9 HLASM
Output from the C/C++ compiler object file HLASM source code
User requires invoking HLASM to compile the source code No Yes
Linkage support All supported linkages by C and C++ MVS OS linkage only
Runtime library support z/OS C/C++ runtime library z/OS METAL C runtime library
Language environment support Yes No
METAL C generates code that is independent of LE
User customized prolog/epilog support No Yes
Modifiable assembly code generated by the compiler No Yes
AR-mode support No Yes
AMODE switching support No Yes

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
//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
Compiler option ASM METAL
ARMODE No Yes
ASMDATASIZE No Yes
ASMLIB Yes No
DSAUSER No Yes
EPILOG No Yes
GENASM No Yes
KEYWORD(asm) Yes No – before V2R1M1
Yes – V2R1M1 and later
PROLOG No Yes
RESERVED_REG No Yes
SYSSTATE No Yes

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
 ASMMETAL
keywords asm, __asm, __asm__ __asm, __asm__1
compiler predefined macros __IBM_ASM_SUPPORT = 1 __IBM_METAL__ = 1
__IBM_FAR_IS SUPPORTED__ = 1
#pragma insert_asm Not supported Supported
_Pragma("insert_asm") Not supported Supported

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:

  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
VariationsOption specification
PDS/PDSE MVS: CPARM=' ASMLIB(//''''SYS1.MACLIB'''')'
USS: -qasmlib="//'SYS1.MACLIB'"
Results: data set 'SYS1.MACLIB' is searched
USS directory MVS: CPARM='ASMLIB(/hlq/mymacrolib)'
USS: -qasmlib=/hlq/mymacrolib
Results: directory /hlq/mymacrolib is searched
Multiple options and mixed types MVS: CPARM='ASMLIB(/hlq/mymacrolib) , ASMLIB(//''''HLQ.MYMACLIB'''')'
USS: -qasmlib=/hlq/mymacrolib –qasmlib= "//'HLQ.MYMACLIB'"
Results: /hlq/mymacrolib and 'HLQ.MYMACLIB' are searched
Multiple suboptions and mixed types MVS: CPARM='ASMLIB(//''''HLQ.MYMACLIB'''', /hlq/mymacrolib, //''''SYS1.MACLIB'''')'
USS: -qasmlib="//'HLQ.MYMACLIB'": /hlq/mymacrolib:"//'SYS1.MACLIB'"
Results: 'HLQ.MYMACLIB', /hlq/mymacrolib , and 'SYS1.MACLIB' are searched
NOASMLIB MVS: CPARM='ASMLIB(/hlq/mymacrolib), NOASMLIB, ASMLIB(//''''HLQ.MYMACLIB'''')'
USS: -qasmlib=/hlq/mymacrolib -qnoasmlib -qasmlib="/'HLQ.MYMACLIB'"
Results: only 'HLQ.MYMACLIB' is searched

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:

  1. Data set SYS1.MACLIB
  2. Data set HLQ.MYMACLIB
  3. 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:

  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, Visda Vokhshoori and Milos Lalovic for their help and advice with this article.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=1017661
ArticleTitle=Using inline assembly for z/OS XL C/C++ compiler
publish-date=10162015