Building Metal C programs using z/OS UNIX System Services

There are three steps for building a Metal C program under z/OS® UNIX System Services:

  1. Use the xlc command to generate an HLASM source file.
  2. Use the as command to generate the object file.
  3. Use the ld command to generate the program.

Generating an HLASM source file using the xlc command

To generate an HLASM source file from a C source file, the xlc command must be invoked with the -qmetal option and the -S flag.
Note: Without the -S flag, the xlc utility invokes the compiler with the OBJECT option, which is in conflict with the METAL option. This causes the compiler to emit a severe error message and stop processing.

The generated HLASM source file has the same name as the C source file with the suffix derived from the ssuffix attribute in the xlc configuration file. The default suffix is s, so in the examples in this section, the HLASM source file name is mycode.s.

Figure 1. C compiler invocation to generate mycode.s
    xlc -S -qmetal mycode.c

Generating an object file from the HLASM source using the z/OS UNIX System Services as command

The generated object file does not have to be a z/OS UNIX file. The as command can write the object file directly to an MVS™ data set, as shown in Figure 2. The -o flag can be used to name the output file, where it can be a UNIX file or an MVS data set.

Figure 2. Command that invokes HLASM to assemble mycode.s
   as mycode.s

A successful assemble will produce mycode.o.

If the C source file was compiled with the LONGNAME compiler option, the generated HLASM source file will contain symbols that are more than eight characters in length. In that case, the HLASM GOFF option must be specified. Use the as utility -m flag to specify HLASM options, as shown in Figure 3.

Figure 3. Command that compiles an HLASM source file containing symbols longer than eight characters
   as -mgoff mycodelong.s

A successful assemble will produce mycodelong.o.

Creating a program with the z/OS UNIX System Services ld command

Use the ld command to link the object file produced by the as command into a program. The program does not have to be a z/OS UNIX file. The ld utility can write the program directly to a specified MVS data set.

Common ld command options that control the bind step are:
  • -e to specify the entry point.
  • -o to specify the name of the program created by the ld utility.
  • -V to direct the binder listing to stdout.
  • -b to specify other binder-specific options.
Note: If you compile your C source file with the LONGNAME option, you should use -b case=mixed and the -e option must specify the entry point in its original case, as shown in Figure 4.
Figure 4. Command that binds mycode.o and produces a Metal C program in an MVS data set
   ld -b case=mixed -e MYADD -o "//LOAD(mycode)" mycode.o

A successful bind produces HLQ.LOAD(MYCODE) with entry point MYADD.

Commands that compile and link applications that switch addressing modes

Figure 5 shows the commands that compile and link the programs in Figure 1.
Figure 5. Commands that compile and link programs with different addressing modes
xlc -S -qmetal a31.c                1 
xlc -S -qmetal -q64 a64a.c          2 
as -a=a31.lst -mgoff a31.s          3 
as -a=a64a.lst -mgoff a64a.s        3 
ld -o a.out a31.o a64a.o -e MAIN    4 
Notes:
  1. To generate an HLASM source file from a C source file, the xlc command must be invoked with the -qmetal option and the -S flag.
  2. The called program a64a.c is an external function in a separate source file.
  3. The -mgoff command is used to compile an HLASM source file containing symbols longer than eight characters.
  4. The ld command links the object file produced by the as command into a program. The -e command specifies the entry point.
Parent topic: Building Metal C programs