c89 — Compiler invocation using host environment variables

Description

The c89, cc, and c++ commands call other programs for each step of the compilation, assemble, and link-editing phases. Table 1 contains the step name and the name of the document that describes the program you use for that step and the document that describes any messages issued by that program, and prefixes to those messages.

Execution of any Language Environment® program can result in runtime messages. These messages are described in z/OS Language Environment Runtime Messages and have an EDC prefix.

First, the c89, cc, and c++ commands perform the compilation phase (including preprocessing) by compiling all source file operands (file.C, file.i, and file.c, as appropriate). For the c++ command, if automatic template generation is being used (which is the default), then z/OS XL C++ source files may be created or updated in the tempinc subdirectory of the working directory during the compilation phase (the tempinc subdirectory will be created if it does not already exist). Then, the c89, cc, and c++ commands perform the assemble phase by assembling all operands of the file.s form. The result of each compile step and each assemble step is a file.o file. If all compilations and assemblies are successful, or if only file.o and/or file.a files are specified, the c89, cc, and c++ commands proceed to the link-editing phase. For the c++ command, the link-editing phase begins with an automatic template generation step when applicable. For IPA (Interprocedural Analysis) optimization an additional IPA Link step comes next. The link-edit step is last. See the environment variable prefix_STEPS under Environment variables for more information about the link-editing phase steps.

In the link-editing phase, the c89, cc, and c++ commands combine all file.o files from the compilation phase along with any file.o files that were specified on the command line. For the c++ command, this is preceded by compiling all C++ source files in the tempinc subdirectory of the working directory (possibly creating and updating additional C++ source files during the automatic template generation step). After compiling all the C++ source files, the resulting object files are combined along with the file.o files from the compilation phase and the command line. Any file.a files, file.x files and -l libname operands that were specified are also used.

The usual output of the link-editing phase is an executable file. For the c89, cc, and c++ commands to produce an executable file, you must specify at least one operand which is of other than -l libname form. If -r is used, the output file is not executable.

For more information about automatic template generation, see z/OS XL C/C++ User's Guide and the information on "Using TEMPINC or NOTEMPINC" in z/OS XL C/C++ Programming Guide. Note that the c++ command only supports using the tempinc subdirectory of the working directory for automatic template generation.

For more information on IPA, see Options.

Options

–+

Specifies that all source files are to be recognized as C++ source files. All file.s, file.o, and file.a files will continue to be recognized as assembler source, object, and archive files respectively. However, any C file.c or file.i files will be processed as corresponding C++ file.C or file.i files, and any other file suffix which would otherwise be unrecognized will be processed as a file.C file.

This option effectively overrides the environment variable prefix_EXTRA_ARGS. This option is only supported by the c++ command.

-C

Specifies that C and C++ source comments should be retained by the preprocessor. By default, all comments are removed by the preprocessor. This option is ignored except when used with the -E option.

-c

Specifies that only compilations and assemblies be done. Link-edit is not done.

-D name[=value]

Defines a C or C++ macro for use in compilation. If only name is provided, a value of 1 is used for the macro it specifies. For information about macros that the c89/cc/c++ command automatically defines, see Usage Note 5 and Usage Note 13.

Notes:

• The xlc utility has slightly different semantics for processing -D options.
• As of z/OS V1R12, to define a macro name that contains an escape character (that is, the backslash) using an option such as -D or -Wc,DEFINE, you must specify the option in a way that can preserve the backslash character when the macro reaches the compiler parser. Because an option passes through the UNIX shell and the compiler options processor, both of which are sensitive to backslash characters, the rules for such characters must be followed to ensure that the compiler parser receives a macro with the backslash character. The UNIX shell and the compiler options parser both interpret and consume backslash characters that are unquoted or quoted by double quotation marks. On the other hand, the UNIX shell does not interpret backslash characters that are quoted by single quotation marks, while the compiler options parser is not sensitive to single quotation marks. For example, for the compiler parser to receive \u0024 as the macro symbol, the compiler options processor must receive \\u0024, so you must specify -D'\\u0024' or -D"\\\u0024" on the command line. This also applies to the -Wc,DEFINE option, which is an alternative method of defining macros (for example, -Wc,'DEFINE(\\u0024)' or -Wc,"DEFINE(\\\u0024)"). The same is true for any compiler option that requires the use of a backslash to suppress special meaning of a particular character.

-E

Specifies that output of the compiler preprocessor phase be copied to stdout. Object files are not created, and no link-editing is performed.

-e function

Specifies the name of the function to be used as the entry point of the program. This can be useful when creating a fetchable program, or a non–C or non–C++ main, such as a COBOL program. Non–C++ linkage symbols of up to 1024 characters in length may be specified. You can specify an S-name by preceding the function name with double slash (//). (For more information about S-names, see Usage Note 23.)

Specify a null S-name ("-e //") so that no function name is identified by the c89/cc/c++ command as the entry point of the program. In that case, the Program Management Binder (link editor) default rules will determine the entry point of the program. For more information about the Program Management Binder and the ENTRY control statement, see z/OS MVS Program Management: User's Guide and Reference.

The function //ceestart is the default. When the default function entry point is used, a binder ORDER control statement is generated by the c89/cc/c++ command to cause the CEESTART code section to be ordered to the beginning of the program. Specify the name with a trailing blank to disable this behavior, as in "//ceestart ". For more information about the Program Management Binder and the ORDER control statement, see z/OS MVS Program Management: User's Guide and Reference.

This option might be required when building products which are intended to be installed using the IBM® SMP/E product. When installing ++MOD elements with SMP/E, binder control statements should be provided in the JCLIN created to install the product instead of being embedded in the elements themselves.

-F

Ignored by the cc command. Provided for compatibility with historical implementations of the cc command. Flagged as an error by the c89 and c++ commands.

-f

Ignored by the cc command. Provided for compatibility with historical implementations of the cc command. Flagged as an error by the c89 and c++ commands.

Historical implementations of C/C++ used this option to enable floating-point support. Floating-point is automatically included in z/OS XL C/C++. However, in z/OS XL C/C++, two types of floating-point support are available:

HEXADECIMAL

Base 16 IBM System z9® hexadecimal format. The IBM System z9 hexadecimal format is referred to as the hexadecimal floating-point format, and is unique to IBM System z9 hardware. This is the default.

IEEE754

Base 2 IEEE-754 binary format. The IEEE-754 binary format is referred to as binary floating-point format. The IEEE-754 binary format is the more common floating point format used on other platforms.

If you are porting an application from another platform, transmitting floating-point numbers between other platforms or workstations, or your application requires the larger exponent range provided by IEEE-754 binary format, then you should consider using IEEE floating-point. The z/OS XL C/C++ User's Guide contains more information on the FLOAT compiler option.

An example of compiling with IEEE-754 binary floating point format:

c89 -o outfile -Wc,'float(ieee)' file.c

-g

Specifies that a side file that contains symbolic information is emitted and the executable is to be loaded into read/write storage, which is required for source-level debugging with dbx, and other debuggers.

For 32-bit compiles, if the _DEBUG_FORMAT=ISD environment variable is exported, then -g specifies that the output file (executable) is to contain symbolic information and is to be loaded into read/write storage, which is required for source-level debugging with dbx, and other debuggers.

When specified for the compilation phase, the compiler produces symbolic information for source-level debugging.

When specified for the link-editing phase, the executable file is marked as being serially reusable and will always be loaded into read/write storage.

dbx requires that all the executables comprising the process be loaded into read/write storage so that it can set break points in these executables. When dbx is attached to a running process, this cannot be guaranteed because the process was already running and some executables were already loaded. There are two techniques that will cause all the executables comprising the process to be loaded into read-write storage:

1. Specify the -g option for the link-editing phase of each executable. After this is done, the executable is always loaded into read/write storage.
   Because the executable is marked as being serially reusable, this technique works except in cases where the executable must be marked as being reentrant. For example:

   • If the executable is to be used by multiple processes in the same user space.
   • If the executable is a DLL that is used on more than one thread in a multithreaded program.

   In these cases, use the following technique instead:

2. Do not specify the -g option during the link-editing phase so that the executable will be marked as being reentrant. Before invoking the program, export the environment variable _BPX_PTRACE_ATTACH with a value of YES. After you do this, then executables will be loaded into read/write storage regardless of their reusability attribute.

If you compile an MVS™ data set source using the -g option, you can use dbx to perform source-level debugging for the executable file. You must first issue the dbx use subcommand to specify a path of double slash (//), causing dbx to recognize that the symbolic name of the primary source file is an MVS data set. For information on the dbx command and its use subcommand, see use subcommand for dbx: Set the list of directories to be searched.

For more information on using dbx, see z/OS UNIX System Services Programming Tools.

The z/OS UNIX System Services web page also has more information about dbx. Go to http://www.ibm.com/systems/z/os/zos/features/unix/.

For more information on the _BPX_PTRACE_ATTACH environment variable, see z/OS UNIX System Services Programming: Assembler Callable Services Reference.

The GONUMBER option is automatically turned on by the -g option, but can also be turned on independently. There is no execution path overhead incurred for turning on this option, only some additional space for the saved line number tables.

For 31-bit compiles and In Storage Debug (ISD) information, the GONUMBER option generates tables that correspond to the input source file line numbers. These tables make it possible for Debug Tools and for error trace back information in CEE dumps to display the source line numbers. Having source line numbers in CEE dumps improves serviceability costs of applications in production.

An example of compiling with the GONUMBER compiler option:

c89 -o outfile -Wc,'GONUM' file.c

Note: -g forces the NOOPTIMIZE compiler option regardless of its position in the command line.

-I directory

Note: The I option signifies an uppercase i, not a lowercase L.

-I specifies the directories to be used during compilation in searching for include files (also called header files).

Absolute path names specified on #include directives are searched exactly as specified. The directories specified using the -I option or from the usual places are not searched.

If absolute path names are not specified on #include directives, then the search order is as follows:

1. Include files that are enclosed in double quotation marks (") are first searched for in the directory of the file containing the #include directive. Include files that are enclosed in angle-brackets (< >) skip this initial search.
2. The include files are then searched for in all directories specified by the -I option, in the order specified.
3. Finally, the include files are searched for in the usual places. (See Usage Note 4 for a description of the usual places.)

You can specify an MVS data set name as an include file search directory. Also, MVS data set names can explicitly be specified on #include directives. You can indicate both by specifying a leading double slash (//).

To include the include file DEF that is a member of the MVS PDS ABC.HDRS, code your C or C++ source as follows:

#include <//'abc.hdrs(def)'>

MVS data set include files are handled according to z/OS XL C/C++ compiler conversion rules (See Usage Note 4). When specifying an #include directive with a leading double slash (in a format other than #include<//'dsname'> and #include<//dd:ddname>), the specified name is paired only with MVS data set names specified on the -I option. That is, when you explicitly specify an MVS data set name, any z/OS UNIX file system directory names specified on the -I option are ignored.

Note: As of z/OS V1R12, a directory name that contains a comma must be quoted by double quotation marks, and the comma must be escaped by the backslash character. For example, -Imy,directory can result in two directories "my" and "directory". If the intended name is a single directory name that contains a comma, the option must be specified as -I"my\,directory" to suppress the special meaning of the comma as suboption separator.

-L directory

Specifies the directories to be used to search for archive libraries specified by the -l operand. The directories are searched in the order specified, followed by the usual places. You cannot specify an MVS data set as an archive library directory.

For information on specifying C370LIB libraries, see the description of the -l libname operand. Also see Usage Note 7 for a description of the usual places.

-0, -O (-1), -2, -3

Specifies the level of compiler optimization (including inlining) to be used. The level -1 (number one) is equivalent to -O (capital letter O). The level -3 gives the highest level of optimization. The default is -0 (level zero), no optimization and no inlining, when not using IPA (Interprocedural Analysis).

When optimization is specified, the default is ANSIALIAS. The ANSIALIAS default specifies whether type-based aliasing is to be used during optimization. That is, the optimizer assumes that pointers can only be used to access objects of the same type. Type-based aliasing improves optimization. Applications that use pointers that point to objects of a different type will need to specify NOANSIALIAS when the optimization compiler option is specified. If your application works when compiled with no optimization and fails when compiled with optimization, then try compiling your application with both optimization and NOANSIALIAS compiler options. The z/OS XL C/C++ User's Guide contains more information on ANSIALIAS.

Notes:

1. Options can also be specified as -O1 (using capital letter O), -O2, and -O3. For further information, see Usage Note 12.
2. These options cannot be overridden by specifying optimization options using the -Wc syntax. This behavior differs from the behavior of the xlc utility, which allows the use of -q and -Wc syntax to override the flag optimization options.

An example of a compile with the highest level of optimization and no type-based aliasing:

c89 -o outfile -O3 -Wc,NOANSIALIAS file.c

When optimization is specified, you may want to obtain a report on the amount of inlining performed and increase or decrease the level of inlining. More inlining will improve application performance and increase application memory usage. The z/OS XL C/C++ User's Guide contains more information on the INLINE compiler option.

An example of a compilation with optimization with no report generated, a threshold of 500 abstract code units, and a limit of 2500 abstract code units:

c89 -o outfile -O2 -Wc,'inline(auto,noreport,500,2500)' file.c

When using IPA, the default is -O (level 1) optimization and inlining. IPA optimization is independent from and can be specified in addition to this optimization level. IPA is further described in this topic.

If compiling with PDF, the same optimization level must be used in the PDF1 and PDF2 steps.

If you compile your program to take advantage of dbx source-level debugging and specify -g (see the -g option description in this topic), you will always get -0 (level zero) optimization regardless of which of these compiler optimization levels you specify.

In addition to using optimization techniques, you may want to control writable strings by using the #pragma strings(readonly) directive or the ROSTRING compiler option. As of z/OS Version 1 Release 2, ROSTRING is the default.

For more information on this topic, refer to reentrancy in z/OS XL C/C++ in z/OS XL C/C++ Programming Guide or the description of the ROSTRING option in the z/OS XL C/C++ User's Guide.

-o outfile

Specifies the out put file name of the c89/cc/c++ command.

If the -o option is specified in addition to the –c option, and only one source file is specified, then this option specifies the name of the output file associated with the one source file. See file.o under Operands for information on the default name of the output file.

Otherwise the -o option specifies the name of the executable file produced during the link-editing phase. The default output file is a.out.

-p

Ignored by the cc command. Provided for compatibility with historical implementations of the cc command. Flagged as an error by the c89 and c++ commands.

-q

Ignored by the cc command. Provided for compatibility with historical implementations of the cc command. Flagged as an error by the c89 and c++ commands.

-r

Specifies that the c89/cc/c++ command is to save relocation information about the object files which are processed. When the output file (as specified on –o) is created, it is not made an executable file. Instead, this output file can later be used as input to the c89/cc/c++ command. This can be used as an alternative to an archive library.

IPA usage note: When using -r and link-editing IPA compiled object files, you must link-edit with IPA (see the description of IPA under the -W option). However, the -r option is typically not useful when you create an IPA optimized program. This is because link-editing with IPA requires that all of the program information is available to the link editor. It is not acceptable to have unresolved symbols, especially the program entry point symbol, which is usually main. The -r option is normally used when you want to combine object files incrementally. Specify object files during the initial link-edit that uses -r. Later, specify the output of the initial link-edit, along with the remaining object files in a final link-edit that is done without using -r. When you want to combine IPA compiled object files, use the alternative that does not involve the link editor, that is, concatenating the object files into one larger file by using the cp or cat utilities. You can use this larger file later in a final link-edit when the remainder of the object files are also made available.

-S

Specifies that the output file produced by the compiler is in assembler source code format. The absence of the -S flag indicates that the output file produced is in object code format. The -S flag is supported only with the METAL compiler option. The compiler does not produce an object file when the -S flag is used.

By default, the assembler source file name is based on the C source file name specified on the command line. The suffix is determined based on the appropriate environment variable. However, the assembler source file name can be affected by the use of the -o option.

When you specify the -o option, the assembler source file name is based on the name specified with the option. For example, when you specify c89 -S -Wc,metal -c -o foo.x hello.c, the output assembler source file name is foo.x.

The following specifications have the same result:

c89 -S -Wc,metal hello.c
c89 -S -Wc,metal -o hello.s hello.c
c89 -S -Wc,metal -c hello.c 
c89 -S -Wc,metal -c -o hello.s hello.c 

-s

Specifies that the compilation phase is to produce a file.o file that does not include symbolic information, and that the link-editing phase produce an executable that is marked reentrant. This is the default behavior for the c89/cc/c++ command.

-U name

Undefines a C or C++ macro specified with name. This option affects only macros defined by the -D option, including those automatically specified by the c89/cc/c++ command. For information about macros that the c89/cc/c++ command automatically define, see Usage Note 5 and Usage note 13.

Note: The xlc utility uses different semantics for handling the -U option. See xlc — Compiler invocation using a customizable configuration file for more information.

-u function

Specifies the name of the function to be added to the list of symbols which are not yet defined. This can be useful if the only input to the c89/cc/c++ command is archive libraries. Non–C++ linkage symbols of up to 255 characters in length may be specified. You can specify an S-name by preceding the function name with double slash (//). (For more information about S-names, see Usage Note 23.) The function //ceemain is the default for non-IPA Link-editing, and the function main is the default for IPA Link-editing. However, if this -u option is used, or the DLL link editor option is used, then the default function is not added to the list.

-V

This verbose option produces and directs output to stdout as compiler, assembler, IPA linker, prelinker, and link editor listings. If the -O, -2, or -3 options are specified and cause the c89/cc/c++ command to use the compiler INLINE option, then the inline report is also produced with the compiler listing. Error output continues to be directed to stderr. Because this option causes the c89/cc/c++ command to change the options passed to the steps producing these listings so that they produce more information, it may also result in additional messages being directed to stderr. In the case of the compile step, it may also result in the return code of the compiler changing from 0 to 4.

Note: This option has a different meaning when using the xlc utility. See xlc — Compiler invocation using a customizable configuration file for more information.

-v

This verbose option causes pseudo-JCL to be written to stdout before the compiler, assembler, IPA linker, prelinker, and link editor programs are run.

It also causes phaseid information to be emitted in stderr:

FSUM0000I  Utility(c89)                      Level(UQ99999)

It provides information about exactly which compiler, prelinker, and link editor options are being passed, and also which data sets are being used. If you want to obtain this information without actually invoking the underlying programs, specify the -v option more than once on the c89/cc/c++ command string. For more information about the programs which are executed, see Usage Note 14.

-W phase, option[,option]…

Specifies options to be passed to the steps associated with the compile, assemble, or link-editing phases of the c89/cc/c++ command. The valid phase codes are:

0

Specifies the compile phase (used for both non-IPA and IPA compilation).

a

Specifies the assemble phase.

c

Same as phase code 0.

I

Enables IPA (Interprocedural Analysis) optimization.

Unlike other phase codes, the IPA phase code I does not require that any additional options be specified, but it does allow them. In order to pass IPA suboptions, specify those suboptions using the IPA phase code.

To specify that an IPA Compile should save source line number information, without writing a listing file, specify:

c89 -c -W I,list file.c

To specify that an IPA Link-edit should write the map file to stdout, specify:

c89 -W I,map file.o

l

Specifies the link-editing phase.

• To pass options to the prelinker, the first link-editing phase option must be p or P. All the following options are then prelink options.
  To write the prelink map to stdout, specify:

  c89 –W l,p,map file.c

  Note: The prelinker is no longer used in the link-editing phase in most circumstances. If it is not used, any options that are passed are accepted but ignored. See the environment variable prefix_STEPS under Environment variables for more information about the link-editing phase prelink step.
• To pass options to the IPA linker, the first link-editing phase option must be i or I. All the following options are then IPA Link options.
  To specify the size of the SPILL area to be used during an IPA Link-edit, you could specify:

  c89 –W l,I,"spill(256)" file.o

• To link-edit a DLL (Dynamic Link Library) and produce a sidedeck, the link-editing phase option DLL must be specified.
  To accomplish this task, you could specify:

  c89 –o outdll –W l,dll file.o

Most z/OS XL C/C++ extensions can be enabled by using this option. Those which do not directly pass options through to the underlying steps, or involve files which are extensions to the compile and link-edit model, are described here:

DLL (Dynamic Link Library)

A DLL is a part of a program that is not statically bound to the program. Instead, linkage to symbols (variables and functions) is completed dynamically at execution time. DLLs can improve storage utilization, because the program can be broken into smaller parts, and some parts may not always need to be loaded. DLLs can improve maintainability, because the individual parts can be managed and serviced separately.

In order to create a DLL, some symbols must be identified as being exported for use by other parts of the program. This can be done with the z/OS XL C/C++ #pragma export compiler directive, or by using the z/OS XL C/C++ EXPORTALL compiler option. If during the link-editing phase some of the parts have exported symbols, the executable which is created is a DLL. In addition to the DLL, a definition sidedeck is created, containing link-editing phase IMPORT control statements which name those symbols which were exported by the DLL. In order for the definition sidedeck to be created, the DLL link editor option must be specified. This definition sidedeck is subsequently used during the link-editing phase of a program which is to use the DLL. See the file.x operand description in the Operands topic for information on where the definition sidedeck is written. In order for the program to refer to symbols exported by the DLL, it must be compiled with the DLL compiler option.

To compile and link a program into a DLL, you could specify:

c89 -o outdll -W c,exportall -W l,dll file.c

To subsequently use file.x definition side-decks, specify them along with any other file.o object files specified for the c89/cc/c++ link-editing phase.

To accomplish this task, you could specify:

c89 –o myappl –W c,dll myappl.c outdll.x

In order to run an application which is link-edited with a definition sidedeck, the DLL must be made available (the definition sidedeck created along with the DLL is not needed at execution time). When the DLL resides in the z/OS UNIX file system, it must be in either the working directory or in a directory named on the LIBPATH environment variable. Otherwise it must be a member of a data set in the search order used for MVS programs.

Note: For non-DLL C++ compiles, a dummy definition side file will be allocated to prevent the binder from issuing a warning message. If you do want the binder to issue a warning message when an exported symbol is encountered, specify the DLL=NO option for the link-editing phase; for example:

 c++ -o outfile -W l,dll=no file.C

IPA (interprocedural analysis)

IPA optimization is independent from and can be used in addition to the c89/cc/c++ optimization level options (such as –O). IPA optimization can also improve the execution time of your application. IPA is a mechanism for performing optimizations across function boundaries, even across compilation units. It also performs optimizations not otherwise available with the z/OS XL C/C++ compiler.

When phase code I (capital letter I) is specified for the compilation phase, then IPA compilation steps are performed. When phase code I is specified for the link-editing phase, or when the first link-editing phase (code l) option is i or I, then an additional IPA Link step is performed prior to the prelink and link-edit steps.

With conventional compilation and link-editing, the object code generation takes place during the compilation phase. With IPA compilation and link-editing, the object code generation takes place during the link-editing phase. Therefore, you might need to request listing information about the program (such as with the -V option) during the link-editing phase.

Unlike the other phase codes, phase code I does not require that any additional options be specified. If they are, they should be specified for both the compilation and link-editing phases.

No additional preparation needs to be done in order to use IPA.

To create the executable myIPApgm using c89 with some existing source program mypgm.c, you could specify:

c89 –W I –o myIPApgm mypgm.c

When IPA is used with the c++ command, and automatic template generation is being used, phase code I will control whether the automatic template generation compiles are done using IPA. If you do not specify phase code I, then regular compiles will be done. Specifying I as the first option of the link-editing phase option (that is, -W l,I), causes the IPA linker to be used, but will not cause the IPA compiler to be used for automatic template generation unless phase code I (that is, -W I) is also specified.

The IPA Profile-Directed Feedback (PDF) option tunes optimizations, where results from sample program execution are used to improve optimization near conditional branches and in frequently executed code sections. The profiling information is placed in the file specified by the PDFNAME(filename) suboption. If PDFNAME(filename) is not specified, the default name of the file containing profile information is PDF.

Note: When using the c89 command to invoke the compiler for IPA Compile and IPA Link processing using a single command line, some compiler options are not passed to both the IPA Compile and IPA Link steps; for example, the LIST compiler option is not passed. If you want to pass it to both steps, you must use -Wl,I,list syntax so that it is also passed to the IPA Link step. The xlc utility passes all compiler options to both the IPA Compile and IPA Link step.

LP64

The LP64 option instructs the compiler to generate AMODE 64 code utilizing the z/Architecture® 64-bit instructions.

To compile 64-bit code, specify the z/OS XL C/C++ LP64 compiler option.

The following example shows how to compile and bind using the LP64 option:

c89 -o -W c,LP64 -Wl,LP64 file.c

XPLINK (Extra Performance Linkage)

z/OS XPLINK provides improved performance for many C/C++ programs. The XPLINK compiler option instructs the z/OS XL C/C++ compiler to generate high performance linkage for subroutine calls. It does so primarily by making subroutine calls as fast and efficient as possible, by reducing linkage overhead, and by passing function call parameters in registers. Furthermore, it reduces the data size by eliminating unused information from function control blocks.

An XPLINK-compiled program is implicitly a DLL-compiled program (the C/C++ DLL compiler option need not be specified along with the XPLINK option). XPLINK improves performance when crossing function boundaries, even across compilation units, since XPLINK uses a more efficient linkage mechanism.

For more information about the z/OS XL C/C++ XPLINK compiler option, refer to z/OS XL C/C++ User's Guide. For more information about Extra Performance Linkage, refer to z/OS Language Environment Programming Guide.

To use XPLINK, you must both compile and link-edit the program for XPLINK. All C and C++ source files must be compiled XPLINK, as you cannot statically link together XPLINK and non-XPLINK C and C++ object files (with the exception of non-XPLINK "OS" linkage). You can however mix XPLINK and non-XPLINK executables across DLL and fetch() boundaries.

To compile a program as XPLINK, specify the z/OS XL C/C++ XPLINK compiler option. If there are any exported symbols in the executable and you want to produce a definition sidedeck, specify the DLL link editor option. When XPLINK is specified in the link-editing step, different link-edit libraries will be used.

Following is an example of compiling and link-editing an XPLINK application in one command:

c89 -o outxpl -W c,XPLINK -W l,XPLINK,dll file.c

In order to execute an XPLINK program, the SCEERUN2 as well as the SCEERUN data set must be in the MVS program search order (see the prefix_PLIB_PREFIX environment variable).

You cannot use -W to override the compiler options that correspond to c89 flag options, with the following exceptions:

• Listing options (corresponding to -V)
• Inlining options (corresponding to -O, -2, and -3)
• Symbolic options (corresponding to -s and -g); symbolic options can be overridden only when neither -s nor -g is specified.

Notes:

1. Most compiler, prelinker, and IPA linker options have a positive and negative form. The negative form is the positive with a prepended NO (as in XREF and NOXREF).
2. The compiler #pragma options directives as well as any other #pragma directives which are overridden by compiler options, will have no effect in source code compiled by the c89/cc/c++ command.
3. Link editor options must be specified in the name=value format. Both the option name and value must be spelled out in full. If you do not specify a value, a default value of YES is used, except for the following options, which if specified without a value, have the default values shown here:

   ALIASES

   ALIASES=ALL

   DYNAM

   DYNAM=DLL

   LET

   LET=8

   LIST

   LIST=NOIMPORT

   Notes:

   1. The binder default is COMPAT=MIN. For downward compatibility (when - Wc,'target(release)' is used), COMPAT should also be used (for example, -Wl,compat=min, or the specific program object format level supported by the target deployment system, if it is known). For more information, see the Downward Compatibility section of z/OS XL C/C++ User's Guide.
   2. As of z/OS V1R8, the default for the COMPAT option is no longer emitted. In prior releases, the default was COMPAT=CURRENT.
   3. References throughout this document to the link editor are generic references. The c89/cc/c++ command specifically uses the Program Management binder for this function.
4. The z/OS XL C/C++ compiler is described in z/OS XL C/C++ User's Guide. Related information about the z/OS XL C/C++ runtime library, including information about DLL and IPA support, is described in z/OS XL C/C++ Programming Guide. Related information about the C and C++ languages, including information about compiler directives, is described in z/OS XL C/C++ Language Reference.
5. Since some compiler options are only used by z/OS XL C and some compiler options are only used by z/OS XL C++, you may get warning messages and a compiler return code of 4, if you use this option and compile both C and C++ source programs in the same c++ command invocation.
6. The prelinker is described in z/OS XL C/C++ User's Guide.
7. The z/OS XL C/C++ User's Guide also describes z/OS XL C/C++ compiler options.Any messages produced by it (CCN messages) are documented in z/OS XL C/C++ Messages.
8. You may see runtime messages (CEE or EDC) in executing your applications. These messages are described in z/OS Language Environment Debugging Guide.
9. The link editor (the Program Management binder) is described in z/OS MVS Program Management: User's Guide and Reference. The Program Management binder messages are described in z/OS MVS System Messages, Vol 8 (IEF-IGD).

Operands

The c89/cc/c++ command generally recognizes their file operand types by file suffixes. The suffixes shown here represent the default values used by the c89/cc/c++ command. See Environment variables for information about changing the suffixes to be used.

Environment variables

You can use environment variables to specify necessary system and operational information to the c89/cc/c++ command. When a particular environment variable is not set, the c89/cc/c++ command uses the default shown. For information about the JCL parameters used in these environment variables, see z/OS MVS JCL User's Guide.

_CCN_32_RUNOPTS

Specifies Language Environment runtime options that apply to the environment in which the 32-bit compiler components are running.

_CCN_64_RUNOPTS

Specifies Language Environment runtime options that apply to the environment in which the 64-bit compiler components are running.

_CCN_IPA_WORK_SPACE

The SPACE parameter used by the z/OS XL C/C++ compiler for the unnamed temporary work data set related to IPALINK.

When _CCN_IPA_WORK_SPACE is not specified, the default is to use the settings from prefix_WORK_SPACE. In this case, prefix_WORK_SPACE must be set large enough for the potentially large work files that can be generated by IPALINK. If _CCN_IPA_WORK_SPACE is used, prefix_WORK_SPACE can be tuned for the typically smaller work files generated by the rest of the compiler.

prefix_ACCEPTABLE_RC

The maximum allowed return code (result) of any step (compile, assemble, IPA Link, prelink, or link-edit). If the result is between zero and this value (inclusive), then it is treated internally by the c89/cc/c++ command exactly as if it were a zero result, except that message FSUM3065 is also issued. The default value is 4.

When used under the c89/cc/c++ command, the prelinker by default returns at least a 4 when there are duplicate symbols or unresolved writable static symbols (but not for other unresolved references). The link editor returns at least a 4 when there are duplicate symbols, and at least an 8 when there are unresolved references and automatic library call was used.

prefix_ASUFFIX (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes an archive file. This environment variable does not affect the treatment of archive libraries specified as -l operands, which are always prefixed with lib and suffixed with .a. The default value is a.

prefix_ASUFFIX_HOST (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes a library data set. This environment variable does not affect the treatment of data set libraries specified as -l operands, which are always used exactly as specified. The default value is LIB.

prefix_CCMODE

Controls how the c89/cc/c++ command does parsing. The default behavior of the c89/cc/c++ command is to expect all options to precede all operands. Setting this variable allows compatibility with historical implementations (other cc commands). When set to 1, the c89/cc/c++ command operates as follows:

• Options and operands can be interspersed.
• The double dash (––) is ignored.

Setting this variable to 0 results in the default behavior. The default value is 0.

prefix_CLASSLIB_PREFIX (Usage Note 17)

The prefix for the following named data sets used during the compilation phase and execution of your C++ application.

To be used, the following data sets must be cataloged:

• The data sets ${prefix_CLASSLIB_PREFIX}.SCLBH.+ contain the z/OS XL C++ Class Library include (header) files.
• The data set ${prefix_CLASSLIB_PREFIX}.SCLBSID contains the z/OS XL C++ Class Library definition side-decks.

The following data sets are also used:

The data sets ${prefix_CLASSLIB_PREFIX}.SCLBDLL and ${prefix_CLASSLIB_PREFIX}.SCLBDLL2 contain the z/OS XL C++ Class Library DLLs and messages.

The preceding data sets contain MVS programs that are invoked during the execution of a C++ application built by the c++ command. To be executed correctly, these data sets must be made part of the MVS search order. Regardless of the setting of this or any other c++ environment variable, the c++ command does not affect the MVS search order. These data sets are listed here for information only, to assist in identifying the correct data sets to be added to the MVS program search order.

The default value is the value of the environment variable: _CXX_CLIB_PREFIX

The prefix_CLASSLIB_PREFIX environment variable applies only to the c++ and cxx command names. _CXX is the only valid prefix.

prefix_CLASSVERSION

The version of the C++ Class Library to be invoked by the c++ command. The setting of this variable allows c++ to control which C++ Class Library named data sets are used during the c++ processing phases. It also sets default values for other environment variables.

The format of this variable is the same as the result of the Language Environment C/C++ runtime library function _librel(). See z/OS XL C/C++ Runtime Library Reference for a description of the _librel() function. The default value is the same as the value for the _CVERSION environment variable. If _CVERSION is not set, then the default value will be the result of the C/C++ runtime library _librel() function.

The prefix_CLASSVERSION environment variable applies only to the c++ and cxx command names. _CXX is the only valid prefix.

prefix_CLIB_PREFIX (Usage Note 17)

The prefix for the following named data set used during the compilation phase.

The data set ${prefix_CLIB_PREFIX}.SCCNCMP contains the compiler programs called by the c89/cc/c++ command.

The preceding data set contains MVS programs that are invoked during the execution of the c89/cc/c++ command and during the execution of a C/C++ application built by the c89/cc/c++ command. To be executed correctly, the data set must be made part of the MVS search order. Regardless of the setting of this or any other c89/cc/c++ environment variable, c89/cc/c++ does not affect the MVS search order. The data set is listed here for information only, to assist in identifying the correct data set to be added to the MVS program search order.

The following data set is also used:

The data set ${prefix_CLIB_PREFIX}.SCCNOBJ contains object files required to instrument the code for profile-driven feedback optimization.

The default value is CBC.

prefix_CMEMORY

A suggestion as to the use of compiler C/C++ Runtime Library memory files. When set to 0, the c89/cc/c++ command will prefer to use the compiler NOMEMORY option. When set to 1, c89/cc/c++ will prefer to use the compiler MEMORY option. When set to 1, and if the compiler MEMORY option can be used, c89/cc/c++ needs not allocate data sets for the corresponding work files. In this case it is the responsibility of the user to not override the compiler options (using the -W option) with the NOMEMORY option or any other compiler option which implies the NOMEMORY option.

The default value is 1.

prefix_CMSGS (Usage Note 14)

The Language Environment national language name used by the compiler program. A null value will cause the default Language Environment NATLANG runtime name to be used, and a non-null value must be a valid Language Environment NATLANG runtime option name (Language Environment runtime options are described in z/OS Language Environment Programming Guide . The default value is "" (null).

prefix_CNAME (Usage Note 14)

The name of the compiler program called by the c89/cc/c++ command. It must be a member of a data set in the search order used for MVS programs. The default value is CCNDRVR. If the c89/cc/c++ command is being used with prefix_CVERSION set to a release prior to z/OS V1R2, the default value will be CBCDRVR.

prefix_CSUFFIX (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes a C source file. The default value is c.

prefix_CSUFFIX_HOST (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes a C source data set. The default value is C.

prefix_CSYSLIB (Usage Note 4, Usage Note 16)

The system library data set concatenation to be used to resolve #include directives during compilation.

Normally #include directives are resolved using all the information specified including the directory name. When the c89/cc/c++ command can determine that the directory information can be used, such as when the Language Environment include (header) files are installed in the default location (in accordance with prefix_INCDIRS), then the default concatenation is "" (null).

When the c89/cc/c++ command cannot determine that the directory information can be used, then the default concatenation is:

"${prefix_PLIB_PREFIX}.SCEEH.H"
"${prefix_PLIB_PREFIX}.SCEEH.SYS.H"
"${prefix_PLIB_PREFIX}.SCEEH.ARPA.H"
"${prefix_PLIB_PREFIX}.SCEEH.NET.H"
"${prefix_PLIB_PREFIX}.SCEEH.NETINET.H"

When this variable is a null value, then no allocation is done for compiler system library data sets. In this case, the use of //DD:SYSLIB on the -I option and the #include directive will be unsuccessful. Unless there is a dependency on the use of //DD:SYSLIB, it is recommended that for improved performance this variable be allowed to default to a null value.

prefix_CVERSION

The version of the z/OS XL C/C++ compiler to be invoked by the c89/cc/c++ command. The setting of this variable allows the c89/cc/c++ command to control which z/OS XL C/C++ compiler program is invoked. It also sets default values for other environment variables.

The format of this variable is the same as the result of the Language Environment C/C++ runtime library function _librel(). See z/OS XL C/C++ Runtime Library Reference for a description of the _librel() function. The default value is the result of the C/C++ runtime library _librel() function.

prefix_CXXSUFFIX (Usage Note 15)

The suffix by which the c++ command recognizes a C++ source file. The default value is C. This environment variable is only supported by the c++ and cxx command names. _CXX is the only valid prefix.

prefix_CXXSUFFIX_HOST (Usage Note 15)

The suffix by which the c++ command recognizes a C++ source data set. The default value is CXX. This environment variable is only supported by the c++ and cxx command names. _CXX is the only valid prefix.

prefix_DAMPLEVEL

The minimum severity level of dynamic allocation messages returned by dynamic allocation message processing. Messages with severity greater than or equal to this number are written to stderr. However, if the number is out of the range shown here (that is, less than 0 or greater than 8), then the c89/cc/c++ dynamic allocation message processing is disabled. The default value is 4. Valid values are as follows:

0

Informational

1–4

Warning

5–8

Severe

prefix_DAMPNAME (Usage Note 14)

The name of the dynamic allocation message processing program called by the c89/cc/c++ command. It must be a member of a data set in the search order used for MVS programs. The default dynamic allocation message processing program is described in z/OS MVS Programming: Authorized Assembler Services Guide. The default value is IEFDB476.

prefix_DCBF2008 (Usage Note 21)

The DCB parameters used by the c89/cc/c++ command for data sets with the attributes of record format fixed unblocked and minimum block size of 2008. The block size must be in multiples of 8, and the maximum depends on the phase in which it is used but can be at least 5100. The default value is (RECFM=F,LRECL=4088,BLKSIZE=4088).

prefix_DCBU (Usage Note 21)

The DCB parameters used by the c89/cc/c++ command for data sets with the attributes of record format undefined and data set organization partitioned. This DCB is used by the c89/cc/c++ command for the output file when it is to be written to a data set. The default value is (RECFM=U,LRECL=0,BLKSIZE=6144,DSORG=PO).

prefix_DCB121M (Usage Note 21)

The DCB parameters used by the c89/cc/c++ command for data sets with the attributes of record format fixed blocked and logical record length 121, for data sets whose records may contain machine control characters. The default value is (RECFM=FBM,LRECL=121,BLKSIZE=3630).

prefix_DCB133M (Usage Note 21)

The DCB parameters used by the c89/cc/c++ command for data sets with the attributes of record format fixed blocked and logical record length 133, for data sets whose records may contain machine control characters. The default value is (RECFM=FBM,LRECL=133,BLKSIZE=3990).

prefix_DCB137 (Usage Note 21)

The DCB parameters used by the c89/cc/c++ command for data sets with the attributes of record format variable blocked and logical record length 137. The default value is (RECFM=VB,LRECL=137,BLKSIZE=882).

prefix_DCB137A (Usage Note 21)

The DCB parameters used by the c89/cc/c++ command for data sets with the attributes of record format variable blocked and logical record length 137, for data sets whose records may contain ISO/ANSI control characters. The default value is (RECFM=VB,LRECL=137,BLKSIZE=882).

prefix_DCB3200 (Usage Note 21)

The DCB parameters used by the c89/cc/c++ command for data sets with the attributes of record format fixed blocked and logical record length 3200. The default value is (RECFM=FB,LRECL=3200,BLKSIZE=12800).

prefix_DCB80 (Usage Note 21)

The DCB parameters used by the c89/cc/c++ command for data sets with the attributes of record format fixed blocked and logical record length 80. This value is also used when the c89/cc/c++ command allocates a new data set for an object file. The default value is (RECFM=FB,LRECL=80,BLKSIZE=3200).

prefix_DEBUG_FORMAT (Usage Note 21)

This variable is used to determine to which debug format (DWARF or ISD) the -g flag is translated. If _DEBUG_FORMAT is set to DWARF, then -g is translated to DEBUG(FORMAT(DWARF)). If _DEBUG_FORMAT is set to ISD, then -g is translated to TEST. The default value is DWARF.

Note: This environment variable only applies to 31-bit compiles.

prefix_ELINES

This variable controls whether the output of the -E option will include #line directives. #line directives provide information about the source file names and line numbers from which the preprocessed source came. The preprocessor only inserts #line directives where it is necessary. When set to 1, the output of the c89/cc/c++ -E option will include #line directives where necessary. When set to 0, the output will not include any #line directives. The default value is 0.

prefix_EXTRA_ARGS

The setting of this variable controls whether the c89/cc/c++ command treats a file operand with an unrecognized suffix as an error, or attempts to process it. When the c++ command -+ option is specified, all suffixes which otherwise would be unrecognized are instead recognized as C++ source, effectively disabling this environment variable. See Options for information on the -+ option.

When set to 0, the c89/cc/c++ command treats such a file as an error and the command will be unsuccessful, because the suffix will not be recognized.

When set to 1, the c89/cc/c++ command treats such a file as either an object file or a library, depending on the file itself. If it is neither an object file nor a library then the command will be unsuccessful, because the link-editing phase will be unable to process it. The default value for the c89 and c++ commands is 0. The default value for the cc command is 1.

prefix_IL6SYSIX (Usage Note 7, Usage Note 16)

The system definition sidedeck list that is used to resolve symbols during the IPA Link step of the link-editing phase when using LP64 (see the description of LP64 in Options). The default value is whatever prefix_L6SYSIX is set to or defaults to.

prefix_IL6SYSLIB (Usage Note 7, Usage Note 16)

The system library data set list that is used to resolve symbols during the IPA Link step of the link-editing phase when using LP64 (see the description of LP64 in Options). The default value is whatever prefix_L6SYSLIB is set to or defaults to.

prefix_ILCTL (Usage Note 14)

The name of the control file used by the IPA linker program. By default the control file is not used, so the -W option must be specified to enable its use, as in:

c89 -WI,control …

The default value is ipa.ctl.

prefix_ILMSGS (Usage Note 14)

The name of the message data set member, or the Language Environment national language name, used by the IPA linker program. The default value is whatever prefix_CMSGS is. So if prefix_CMSGS is set or defaults to "" (null), the default value is "" (null).

prefix_ILNAME (Usage Note 14)

The name of the IPA linker program called by the c89/cc command. It must be a member of a data set in the search order used for MVS programs. The default value is whatever prefix_CNAME is. So if prefix_CNAME is set or defaults to CCNDRVR the default value is CCNDRVR.

prefix_ILSUFFIX (Usage Note 15)

The suffix that the c89/cc command uses when creating an IPA linker output file. The default value is I.

prefix_ILSUFFIX_HOST (Usage Note 15)

The suffix that the c89/cc command uses when creating an IPA linker output data set. The default value is IPA.

prefix_ILSYSLIB (Usage Note 7, Usage Note 16)

The system library data set list to be used to resolve symbols during the IPA Link step of the link-editing phase of non-XPLINK programs. The default value is whatever prefix_PSYSLIB is set or defaults to, followed by whatever prefix_LSYSLIB is set or defaults to.

prefix_ILSYSIX (Usage Note 7, Usage Note 16)

The system definition sidedeck list to be used to resolve symbols during the IPA Link step of the link-editing phase in non-XPLINK programs. The default value is whatever prefix_PSYSIX is set or defaults to.

prefix_ILXSYSLIB (Usage Note 7, Usage Note 16)

The system library data set list to be used to resolve symbols during the IPA Link step of the link-editing phase when using XPLINK (see XPLINK (Extra Performance Linkage) in Options). The default value is whatever prefix_LXSYSLIB is set or defaults to.

prefix_ILXSYSIX (Usage Note 7, Usage Note 16)

The system definition sidedeck list to be used to resolve symbols during the IPA Link step of the link-editing phase when using XPLINK (see XPLINK (Extra Performance Linkage) in Options). The default value is whatever prefix_LXSYSIX is set or defaults to.

prefix_INCDIRS (Usage Note 22)

The directories used by the c89/cc/c++ command as a default place to search for include files during compilation (before searching prefix_INCLIBS and prefix_CSYSLIB). If the c++ command is not being used the default value is /usr/include. If the c++ command is being used the default value is /usr/include /usr/lpp/cbclib/include.

prefix_INCLIBS (Usage Note 22)

The directories used by the c89/cc/c++ command as a default place to search for include files during compilation (after searching prefix_INCDIRS and before searching prefix_CSYSLIB). The default value depends on whether or not the c++ command is being used. If the c++ command is not being used the default value is //'${prefix_PLIB_PREFIX}.SCEEH.+'

If the c++ command is being used, the default value is //'${prefix_PLIB_PREFIX}.SCEEH.+' //'${prefix_CLIB_PREFIX}.SCLBH.+'

prefix_ISUFFIX (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes a preprocessed C source file. The default value is i.

prefix_ISUFFIX_HOST (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes a preprocessed (expanded) C source data set. The default value is CEX.

prefix_IXXSUFFIX (Usage Note 15)

The suffix by which the c++ command recognizes a preprocessed C++ source file. The default value is i. This environment variable is only supported by the c++ and cxx command names. _CXX is the only valid prefix.

prefix_IXXSUFFIX_HOST (Usage Note 15)

The suffix by which the c++ command recognizes a preprocessed (expanded) C++ source data set. The default value is CEX. This environment variable is only supported by the c++ and cxx command names. _CXX is the valid prefix.

prefix_L6SYSIX (Usage Note 7, Usage Note 16)

The system definition sidedeck list that resolves symbols during the link-editing phase when using LP64 (see the description of LP64 in Options). A definition sidedeck contains link-editing phase IMPORT control statements, which name symbols that are exported by a DLL. The default value depends on whether or not the c++ command is used. If c++ is not used, the default value is: ${prefix_PLIB_PREFIX}.SCEELLIB(CELQS003). If c++ is used, the default value is the list concatenation:

"${prefix_PLIB_PREFIX}.SCEELIB(CELQS003,CELQSCPP,C64)"
"${prefix_CLASSLIB_PREFIX}.SCLBSID(IOSX64)"

prefix_L6SYSLIB (Usage Note 7, Usage Note 16)

The system library data set concatenation that is used to resolve symbols during the link-editing step when using LP64 (see the description of LP64 in Options). The default value is the concatenation:

"${prefix_PLIB_PREFIX}.SCEEBND2"
"${prefix_SLIB_PREFIX}.CSSLIB"

prefix_LIBDIRS (Usage Note 22)

The directories used by the c89/cc/c++ command as the default place to search for archive libraries which are specified using the -l operand. The default value is /lib /usr/lib.

prefix_LSYSLIB (Usage Note 7, Usage Note 16)

The system library data set concatenation to be used to resolve symbols during the IPA Link step and the link-edit step of the non-XPLINK link-editing phase. The prefix_PSYSLIB libraries always precede the prefix_LSYSLIB libraries when resolving symbols in the link-editing phase. The default value is the concatenation:

"${prefix_PLIB_PREFIX}.SCEELKEX"
"${prefix_PLIB_PREFIX}.SCEELKED"
"${prefix_SLIB_PREFIX}.CSSLIB"

prefix_LXSYSLIB (Usage Note 7, Usage Note 16)

The system library data set concatenation to be used to resolve symbols during the IPA Link step and the link-editing phase when using XPLINK (see XPLINK (Extra Performance Linkage) in Options). The default value is the concatenation:

"${prefix_PLIB_PREFIX}.SCEEBND2"
"${prefix_SLIB_PREFIX}.CSSLIB"

prefix_LXSYSIX (Usage Note 7, Usage Note 16)

The system definition sidedeck list to be used to resolve symbols during the link-editing phase when using XPLINK (see XPLINK (Extra Performance Linkage) in Options). A definition sidedeck contains link-editing phase IMPORT control statements naming symbols which are exported by a DLL. The default value depends on whether or not the c++ command is being used. For 32-bit objects, if c++ is not being used, the default value is the list ${prefix_PLIB_PREFIX}.SCEELIB(CELHS003,CELHS001). For 32-bit objects, if c++ is being used with prefix_PVERSION and prefix_CLASSVERSION defaulted to the current z/OS release, the default value is the list concatenation:

"${prefix_PLIB_PREFIX}.SCEELIB(CELHS003,CELHS001,CELHSCPP,C128)"
"${prefix_CLASSLIB_PREFIX}.SCLBSID(IOSTREAM,COMPLEX)"

For 32-bit objects, if the c++ command is being used with prefix_PVERSION and prefix_CLASSVERSION set to a release prior to z/OS V1R2 for a 32-bit program, the default value is the list concatenation:

"${prefix_PLIB_PREFIX}.SCEELIB(CELHS003,CELHS001,CELHSCPP)"
"${prefix_CLASSLIB_PREFIX}.SCLBSID(ASCCOLL,COMPLEX,IOSTREAM)"

Note: For 64–bit objects, see prefix_L6SYSIX.

prefix_MEMORY

A suggestion as to the use of XL C/C++ runtime library memory files by the c89/cc/c++ command. When set to 0, the c89/cc/c++ command uses temporary data sets for all work files. When set to 1, the c89/cc/c++ command uses memory files for all work files that it can. The default value is 1.

prefix_NEW_DATACLAS (Usage Note 18)

The DATACLAS parameter used by the c89/cc/c++ command for any new data sets it creates. The default value is "" (null).

prefix_NEW_DSNTYPE (Usage Note 18, Usage Note 20)

The DSNTYPE parameter used by the c89/cc/c++ command for any new data sets it creates. The default value is "" (null).

prefix_NEW_MGMTCLAS (Usage Note 18)

The MGMTCLAS parameter used by the c89/cc/c++ command for any new data sets it creates. The default value is "" (null).

prefix_NEW_SPACE (Usage Note 18, Usage Note 19)

The SPACE parameters used by the c89/cc/c++ commandfor any new data sets it creates. A value for the number of directory blocks should always be specified. When allocating a sequential data set, the c89/cc/c++ command automatically ignores the specification. The default value is (,(10,10,10)).

prefix_NEW_STORCLAS (Usage Note 18)

The STORCLAS parameter used by the c89/cc/c++ command for any new data sets it creates. The default value is "" (null).

prefix_NEW_UNIT (Usage Note 18)

The UNIT parameter used by the c89/cc/c++ command for any new data sets it creates. The default value is "" (null).

prefix_NOCMDOPTS (Usage Note 27)

Controls how the compiler processes the default options set by the c89 command. Setting this variable to 1, reverts the compiler to the behavior that was available prior to z/OS V1R5, when the compiler was unable to distinguish between the c89 defaults and the user-specified options. Setting this variable to 0, results in the default behavior where the compiler is now able to recognize c89 defaults. The default value is 0.

prefix_OPERANDS (Usage Note 22)

These operands are parsed as if they were specified after all other operands on the c89/cc/c++ command line. The default value is "" (null).

prefix_OPTIONS (Usage Note 22)

These options are parsed as if they were specified before all other options on the c89/cc/c++ command line. The default value is "" (null).

prefix_OSUFFIX (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes an object file. The default value is o.

prefix_OSUFFIX_HOST (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes an object data set. The default value is OBJ.

prefix_OSUFFIX_HOSTQUAL

The data set name of an object data set is determined by the setting of this option. If it is set to 0, then the suffix prefix_OSUFFIX_HOST is appended to the source data set name to produce the object data set name. If it is set to 1, then the suffix prefix_OSUFFIX_HOST replaces the last qualifier of the source data set name to produce the object data set name (unless there is only a single qualifier, in which case the suffix is appended). The default value is 1.

Note: Earlier versions of the c89 utility always appended the suffix, which was inconsistent with the treatment of files in the hierarchical file system. It is recommended that any existing data sets be converted to use the new convention.

prefix_OSUFFIX_HOSTRULE

The way in which suffixes are used for host data sets is determined by the setting of this option. If it is set to 0, then data set types are determined by the rule described in the note which follows. If it is set to 1, then the data set types are determined by last qualifier of the data set (just as a suffix is used to determine the type of hierarchical file system file). Each host file type has an environment variable by which the default suffix can be modified. The default value is 1.

Notes:

1. Earlier versions of the c89 utility scanned the data set name to determine if it was an object data set. It searched for the string OBJ in the data set name, exclusive of the first qualifier and the member name. If it was found, the data set was determined to be an object data set, and otherwise it was determined to be a C source data set. It is recommended that any existing data sets be converted to use the new convention. Also, because the earlier convention only provided for recognition of C source files, assembler source cannot be processed if it is used.
2. The c++ command does not support this environment variable, as the earlier convention would not provide for recognition of both C++ and C source files. Therefore regardless of its setting, the c++ command always behaves as if it is set to 1.

prefix_PLIB_PREFIX (Usage Note 17)

The prefix for the following named data sets used during the compilation, assemble, and link-editing phases, and during the execution of your application.

To be used, the following data sets must be cataloged:

• The data sets ${prefix_PLIB_PREFIX}.SCEEH.+ contain the include (header) files for use with the runtime library functions (where + can be any of H, SYS.H, ARPA.H, NET.H, and NETINET.H).
• The data set ${prefix_PLIB_PREFIX}.SCEEMAC contains COPY and MACRO files to be used during assembly.
• The data sets ${prefix_PLIB_PREFIX}.SCEEOBJ and ${prefix_PLIB_PREFIX}.SCEECPP contain runtime library bindings which exploit constructed reentrancy, used during the link-editing phase of non-XPLINK programs.
• The data set ${prefix_PLIB_PREFIX}.SCEELKEX contains C runtime library bindings which exploit L-names used during the link-editing phase of non-XPLINK programs. For more information about L-names, see usage note 23.
• The data set ${prefix_PLIB_PREFIX}.SCEELKED contains all other Language Environment runtime library bindings, used during the link-editing phase of non-XPLINK programs.
• The data set ${prefix_PLIB_PREFIX}.SCEEBND2 contains all static Language Environment runtime library bindings, used during the link-editing phase of XPLINK programs.
• The data set ${prefix_PLIB_PREFIX}.SCEELIB contains the definition side-decks for the runtime library bindings, used during the link-editing phase of XPLINK programs.

The following data sets are also used:

• The data sets ${prefix_PLIB_PREFIX}.SCEERUN and ${prefix_PLIB_PREFIX}.SCEERUN2 contains the runtime library programs.

These data sets contain MVS programs that are invoked during the execution of the c89/cc/c++ command and during the execution of a C/C++ application built by the c89/cc/c++ command. To be executed correctly, these data sets must be made part of the MVS search order. Regardless of the setting of this or any other c89/cc/c++ environment variable, the c89/cc/c++ command does not affect the MVS program search order. These data sets are listed here for information only, to assist in identifying the correct data sets to be added to the MVS program search order.

The default value is CEE.

prefix_PMEMORY

A suggestion as to the use of prelinker C/C++ Runtime Library memory files. When set to 0, the c89/cc/c++ command uses the prelinker NOMEMORY option. When set to 1, the c89/cc/c++ command uses the prelinker MEMORY option. The default value is 1.

prefix_PMSGS (Usage Note 14)

The name of the message data set used by the prelinker program. It must be a member of the cataloged data set ${prefix_PLIB_PREFIX}.SCEEMSGP. The default value is EDCPMSGE.

prefix_PNAME (Usage Note 14)

The name of the prelinker program called by the c89/cc/c++ command. It must be a member of a data set in the search order used for MVS programs. The prelinker program is shipped as a member of the ${prefix_PLIB_PREFIX}.SCEERUN data set. The default value is EDCPRLK.

prefix_PSUFFIX (Usage Note 15)

The suffix that the c89/cc/c++ command uses when creating a prelinker (composite object) output file. The default value is p.

prefix_PSUFFIX_HOST (Usage Note 15)

The suffix that the c89/cc/c++ command uses when creating a prelinker (composite object) output data set. The default value is CPOBJ.

prefix_PSYSIX (Usage Note 16)

The system definition sidedeck list to be used to resolve symbols during the non-XPLINK link-editing phase. A definition sidedeck contains link-editing phase IMPORT control statements naming symbols which are exported by a DLL. The default value when the c++ command is not being used is null. If the c++ command is being used with prefix_PVERSION and prefix_CLASSVERSION set or defaulted to the current z/OS release, the default value is the list concatenation:

"${prefix_PLIB_PREFIX}.SCEELIB(C128)"
"${prefix_CLASSLIB_PREFIX}.SCLBSID(IOSTREAM,COMPLEX)"

If the c++ command is being used with prefix_PVERSION and prefix_CLASSVERSION set to a release prior to z/OS V1R2, the default value is the list ${prefix_CLASSLIB_PREFIX}.SCLBSID(ASCCOLL,COMPLEX,IOSTREAM)

prefix_PSYSLIB (Usage Note 16)

The system library data set list to be used to resolve symbols during the non-XPLINK link-editing phase. The prefix_PSYSLIB libraries always precede the prefix_LSYSLIB libraries when resolving symbols in the link-editing phase. The default value depends on whether or not the c++ command is being used. If c++ is not being used, the default value is the list containing the single entry:

"${prefix_PLIB_PREFIX}.SCEEOBJ"

If c++ is being used, the default value is the list:

"${prefix_PLIB_PREFIX}.SCEEOBJ:${prefix_PLIB_PREFIX}.SCEECPP"

prefix_PVERSION (Usage Note 26)

The version of the Language Environment runtime library to be used with the c89/cc/c++ command. The setting of this variable allows c89/cc/c++ to control which Language Environment named data sets are used during the c89/cc/c++ processing phases. These named data sets include those required for use of the C/C++ runtime library as well as the ISO C++ Library. It also sets default values for other environment variables.

The format of this variable is the same as the result of the Language Environment C/C++ runtime library function _librel(). See z/OS XL C/C++ Runtime Library Reference for a description of the _librel() function. The default value is the result of the C/C++ runtime library _librel() function.

prefix_SLIB_PREFIX (Usage Note 17)

The prefix for the named data sets used by the link editor (CSSLIB) and the assembler system library data sets (MACLIB and MODGEN). The data set ${prefix_SLIB_PREFIX}.CSSLIB contains the z/OS UNIX assembler callable services bindings. The data sets ${prefix_SLIB_PREFIX}.MACLIB and ${prefix_SLIB_PREFIX}.MODGEN contain COPY and MACRO files to be used during assembly. These data sets must be cataloged to be used. The default value is SYS1.

prefix_SNAME (Usage Note 14)

The name of the assembler program called by the c89/cc/c++ command. It must be a member of a data set in the search order used for MVS programs. The default value is ASMA90.

prefix_SSUFFIX (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes an assembler source file. The default value is s.

prefix_SSUFFIX_HOST (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes an assembler source data set. The default value is ASM.

prefix_SSYSLIB (Usage Note 16)

The system library data set concatenation to be used to find COPY and MACRO files during assembly. The default concatenation is:

"${prefix_PLIB_PREFIX}.SCEEMAC"
"${prefix_SLIB_PREFIX}.MACLIB"
"${prefix_SLIB_PREFIX}.MODGEN"

prefix_STEPS

The steps that are executed for the link-editing phase can be controlled with this variable. For example, the prelinker step can be enabled, so that the inputs normally destined for the link editor instead go into the prelinker, and then the output of the prelinker becomes the input to the link editor.

This variable allows the prelinker to be used in order to produce output which is compatible with previous releases of the c89/cc/c++ command. The prelinker is normally used by the c89/cc/c++ command when the output file is a data set which is not a PDSE ( partitioned data set extended).

Note: The prelinker and XPLINK are incompatible. When using the link editor XPLINK option, the prelinker cannot be used. Thus, specifying the prelinker on this variable will have no effect.

The format of this variable is a set of binary switches which either enable (when turned on) or disable (when turned off) the corresponding step. Turning a switch on will not cause a step to be enabled if it was not already determined by the c89/cc/c++ command that any other conditions necessary for its use are satisfied. For example, the IPA Link step will not be executed unless the -W option is specified to enable the IPA linker. Enabling the IPA linker is described in Options.

Considering this variable to be a set of 32 switches, numbered left-to-right from 0 to 31, the steps corresponding to each of the switches are as follows:

0-27

Reserved

28

TEMPINC/IPATEMP

29

IPALINK

30

PRELINK

31

LINKEDIT

To override the default behavior of the c89/cc/c++ command and cause the prelinker step to be run (this is also the default when the output file is a data set which is not a PDSE), set this variable to: 0xffffffff or the equivalent, -1. The default value when the output file is a z/OS UNIX file or a PDSE data set is 0xfffffffd or the equivalent, -3.

Note: The IPATEMP step is the IPA equivalent of the TEMPINC (automatic template generation) step, just as the IPACOMP step is the IPA equivalent of the COMPILE step. See the description of IPA under the -W option for more information.

prefix_SUSRLIB (Usage Note 16)

The user library data set concatenation to be used to find COPY and MACRO files during assembly (before searching prefix_SSYSLIB). The default value is "" (null).

prefix_TMPS

The use of temporary files by the c89/cc/c++ command can be controlled with this variable.

The format of this variable is a set of binary switches which either cause a temporary file to be used (when turned on) or a permanent file to be used (when turned off) in the corresponding step.

The correspondence of these switches to steps is the same as for the variable prefix_STEPS. Only the prelinker and IPA linker output can be captured using this variable.

To capture the prelinker output, set this variable to: 0xfffffffD or the equivalent, -3. The default value is 0xffffffff or the equivalent, -1.

prefix_WORK_DATACLAS (Usage Note 18)

The DATACLAS parameter used by the c89/cc/c++ command for unnamed temporary (work) data sets. The default value is "" (null).

prefix_WORK_DSNTYPE (Usage Note 18, Usage Note 20)

The DSNTYPE parameter used by the c89/cc/c++ command for unnamed temporary (work) data sets. The default value is "" (null).

prefix_WORK_MGMTCLAS (Usage Note 18)

The MGMTCLAS parameter used by the c89/cc/c++ command for unnamed temporary (work) data sets. The default value is "" (null).

prefix_WORK_SPACE (Usage Note 18, Usage Note 19)

The SPACE parameters used by the c89/cc/c++ command for unnamed temporary (work) data sets. You must set prefix_MEMORY to 0 for the prefix_WORK_SPACE settings to take effect. The default value is (32000,(30,30)). See also _CCN_IPA_WORK_SPACE.

prefix_WORK_STORCLAS (Usage Note 18)

The STORCLAS parameter used by the c89/cc/c++ command for unnamed temporary (work) data sets. The default value is "" (null).

prefix_WORK_UNIT (Usage Note 18)

The UNIT parameter used by the c89/cc/c++ command for unnamed temporary (work) data sets. The default value is SYSDA.

prefix_XSUFFIX (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes a definition sidedeck file of exported symbols. The default value is x.

prefix_XSUFFIX_HOST (Usage Note 15)

The suffix by which the c89/cc/c++ command recognizes a definition sidedeck data set of exported symbols. The default value is EXP.

Files

libc.a

z/OS XL C/C++ runtime library function library (see Usage Note 7)

libm.a

C/C++ Runtime Library math function library (see Usage Note 7)

libl.a

lex function library

liby.a

yacc function library

/dev/fd0, /dev/fd1, …

Character special files required by the c89/cc/c++ command. For installation information, see z/OS UNIX System Services Planning.

/usr/include

The usual place to search for include files (see Usage Note 4)

/lib

The usual place to search for runtime library bindings (see Usage Note 7)

/usr/lib

The usual place to search for runtime library bindings (see Usage Note 7)

Usage notes

1. To be able to specify an operand that begins with a dash (–), before specifying any other operands that do not, you must use the double dash (––) end-of-options delimiter. This also applies to the specification of the –l operand. (See the description of environment variable prefix_CCMODE for an alternate style of argument parsing.)
2. When invoking the c89/cc/c++ command from the shell, any option-arguments or operands specified that contain characters with special meaning to the shell must be escaped. For example, some -W option-arguments contain parentheses. Source files specified as PDS member names contain parentheses; if they are specified as fully qualified names, they contain single quotation marks.

   To escape these special characters, either enclose the option-argument or operand in double quotation marks, or precede each character with a backslash.

3. Some c89/cc/c++ behavior applies only to hierarchical files (and not to data sets).
   • If the compile or assemble is not successful, the corresponding object file (file.o) is always removed.
   • If the DLL option is passed to the link-editing phase, and afterwards the file.x file exists but has a size of zero, then that file is removed.
4. MVS data sets may be used as the usual place to resolve C and C++ #include directives during compilation.

   Such data sets are installed with the Language Environment runtime library. When it is allocated, searching for these include files can be specified on the -I option as //DD:SYSLIB. (See the description of environment variable prefix_CSYSLIB for information.

   When include files are MVS PDS members, z/OS XL C/C++ uses conversion rules to transform the include (header) file name on a #include preprocessor directive into a member name. If the "//'dataset_prefix.+'" syntax is not used for the MVS data set which is being searched for the include file, then this transformation strips any directory name on the #include directive, and then takes the first 8 or fewer characters up to the first dot (.).

   If the "//'dataset_prefix.+'" syntax is used for the MVS data set which is being searched for the include file, then this transformation uses any directory name on the #include directive, and the characters following the first dot (.), and substitutes the "+" of the data set being searched with these qualifiers.

   In both cases the data set name and member name are converted to uppercase and underscores (_) are changed to at signs (@).

   If the include (header) files provided by the Language Environment runtime library are installed into the hierarchical file system in the default location (in accordance with the prefix_INCDIRS environment variable), then the compiler will use those files to resolve #include directives during compilation. The c89/cc/c++ command by default searches the directory /usr/include as the usual place, just before searching the data sets just described. See the description of environment variables prefix_CSYSLIB, prefix_INCDIRS, and prefix_INCLIBS for information about customizing the default directories to search.

5. Feature test macros control which symbols are made visible in a source file (typically a header file). The c89/cc/c++ command automatically defines the following feature test macros along with the errno macro, according to whether or not the cc command was invoked.
   • Other than cc
     • –D "errno=(*__errno())"
     • –D _OPEN_DEFAULT=1
   • cc
     • –D "errno=(*__errno())"
     • –D _OPEN_DEFAULT=0
     • –D _NO_PROTO=1

   The c89/cc/c++ command adds these macro definitions only after processing the command string. Therefore, you can override these macros by specifying -D or -U options for them on the command string.

6. The default LANGLVL and related compiler options are set according to whether the cc, c89, or c++ (cxx) command was invoked. These options affect various aspects of the compilation, such as z/OS XL C/C++ predefined macros, which are used like feature test macros to control which symbols are made visible in a source file (typically a header file), but are normally not defined or undefined except by this compiler option. They can also affect the language rules used by the compiler. For more information about the compiler options listed here, see z/OS XL C/C++ User's Guide . For more information about z/OS XL C/C++ predefined macros, see z/OS XL C/C++ Language Reference. The options are shown here in a syntax that the user can specify on the c89/cc/c++ command line to override them:
   • c89 (also c++ (cxx) when using a C++ compiler older than z/OS v1r2)
     • -W "c,langlvl(ansi),noupconv"
   • c++ (cxx)
     • -W "c,langlvl(extended,nolibext,nolonglong)
   • cc
     • -W "c,langlvl(commonc),upconv"
7. By default the usual place for the -L option search is the /lib directory followed by the /usr/lib directory. See the description of environment variable prefix_LIBDIRS for information on customizing the default directories to search.
   The archive libraries libc.a and libm.a exist as files in the usual place for consistency with other implementations. However, the runtime library bindings are not contained in them. Instead, MVS data sets installed with the Language Environment runtime library are used as the usual place to resolve runtime library bindings. In the final step of the link-editing phase, any MVS load libraries specified on the -l operand are searched in the order specified, followed by searching these data sets. See the prefix_PLIB_PREFIX description, as well as descriptions of the environment variables featured in the following list.

   • prefix_ILSYSLIB
   • prefix_ILSYSIX
   • prefix_LSYSLIB
   • prefix_PSYSIX
   • prefix_PSYSLIB

   This list of environment variables affects the link-editing phase of the c89 utility, but only for non-XPLINK link-editing. See XPLINK (Extra Performance Linkage) in Options.

   The following list of environment variables affects the link-editing phase of the c89 utility, but only for ILP32 XPLINK link-editing. See XPLINK (Extra Performance Linkage) in Options.

   • prefix_ILXSYSLIB
   • prefix_ILXSYSIX
   • prefix_LXSYSLIB
   • prefix_LXSYSIX
   The following list of environment variables affects the link-editing phase of the c89 utility, but only for LP64 link-editing. See the description of LP64 in Options.

   • prefix_IL6SYSLIB
   • prefix_IL6SYSIX
   • prefix_L6SYSLIB
   • prefix_L6SYSIX
8. Because archive library files are searched when their names are encountered, the placement of -l operands and file.a operands is significant. You may have to specify a library multiple times on the command string, if subsequent specification of file.o files requires that additional symbols be resolved from that library.
9. When the prelinker is used during the link-editing phase, you cannot use as input to the c89/cc/c++ command an executable file produced as output from a previous use of the c89/cc/c++ command. The output of c89/cc/c++ when the -r option is specified (which is not an executable file) may be used as input.
10. All MVS data sets used by the c89/cc/c++ command must be cataloged (including the system data sets installed with the z/OS XL C/C++ compiler and the Language Environment runtime library).
11. The c89/cc/c++ operation depends on the correct setting of their installation and configuration environment variables (see Environment variables). Also, they require that certain character special files are in the /dev directory. For additional installation and configuration information, see z/OS UNIX System Services Planning.
12. Normally, options and operands are processed in the order read (from left to right). Where there are conflicts, the last specification is used (such as with -g and -s). However, some c89 utility flag options will override others, regardless of the order in which they are specified. The option priorities, in order of highest to lowest, are as follows:

    -v specified twice

    The pseudo-JCL is printed only, but the effect of all the other options and operands as specified is reflected in the pseudo-JCL.

    -E

    Overrides -0, -O, -1, -2, -3, -V, -c, -g and -s (also ignores any file.s files).

    -g

    Overrides -0, -O, -1, -2, -3, and -s.

    -s

    Overrides -g (the last one specified is honored).

    -0 (zero), -O (capital letter O), -1, -2, -3, -V, -c

    All are honored if not overridden. -0, -O, -1, -2, -3 override each other (the last one specified is honored).

    Note: The preferred way for specifying optimization options, is -O (capital letter O) followed by a number; for example, -O2.

13. For options that have option-arguments, the meaning of multiple specifications of the options is as follows:

    -D

    All specifications are used. If the same name is specified on more than one -D option, only the first definition is used.

    -e

    The entry function used will be the one specified on the last -e option.

    -I

    All specifications are used. If the same directory is specified on more than one -I option, the directory is searched only the first time.

    -L

    All specifications are used. If the same directory is specified on more than one -L option, the directory is searched only the first time.

    -o

    The output file used will be the one specified on the last -o option.

    -U

    All specifications are used. The name is not defined, regardless of the position of this option relative to any -D option specifying the same name.

    -u

    All specifications are used. If a definition cannot be found for any of the functions specified, the link-editing phase will be unsuccessful.

    -W

    All specifications are used. All options specified for a phase are passed to it, as if they were concatenated together in the order specified.

14. The following environment variables can be at most eight characters in length. For those whose values specify the names of MVS programs to be executed, you can dynamically alter the search order used to find those programs by using the STEPLIB environment variable.

    c89/cc/c++ environment variables do not affect the MVS program search order. Also, for the c89/cc/c++ command to work correctly, the setting of the STEPLIB environment variable should reflect the Language Environment library in use at the time that c89/cc/c++ is invoked.

    For more information on the STEPLIB environment variable, see z/OS UNIX System Services Planning. It is also described under the sh command. Note that the STEPLIB allocation in the pseudo-JCL produced by the -v verbose option is shown as a comment, and has no effect on the MVS program search order. Its appearance in the pseudo-JCL is strictly informational.

    • prefix_CMSGS
    • prefix_CNAME
    • prefix_DAMPNAME
    • prefix_ILCTL
    • prefix_ILNAME
    • prefix_ILMSGS
    • prefix_PMSGS
    • prefix_PNAME
    • prefix_SNAME
15. The following environment variables can be at most 15 characters in length. You should not specify any dots (.) when setting these environment variables since they would then never match their corresponding operands:
    • prefix_ASUFFIX
    • prefix_ASUFFIX_HOST
    • prefix_CSUFFIX
    • prefix_CSUFFIX_HOST
    • prefix_CXXSUFFIX
    • prefix_CXXSUFFIX_HOST
    • prefix_ISUFFIX
    • prefix_ISUFFIX_HOST
    • prefix_ILSUFFIX
    • prefix_ILSUFFIX_HOST
    • prefix_IXXSUFFIX
    • prefix_IXXSUFFIX_HOST
    • prefix_OSUFFIX
    • prefix_OSUFFIX_HOST
    • prefix_PSUFFIX
    • prefix_PSUFFIX_HOST
    • prefix_SSUFFIX
    • prefix_SSUFFIX_HOST
    • prefix_XSUFFIX
    • prefix_XSUFFIX_HOST
16. The following environment variables are parsed as colon-delimited data set names, and represent a data set concatenation or a data set list. The maximum length of each specification is 1024 characters:
    • prefix_CSYSLIB
    • prefix_IL6SYSIX
    • prefix_IL6SYSLIB
    • prefix_ILSYSIX
    • prefix_ILSYSLIB
    • prefix_ILXSYSIX
    • prefix_ILXSYSLIB
    • prefix_L6SYSIX
    • prefix_L6SYSLIB
    • prefix_LSYSLIB
    • prefix_LXSYSIX
    • prefix_LXSYSLIB
    • prefix_PSYSIX
    • prefix_PSYSLIB
    • prefix_SSYSLIB
    • prefix_SUSRLIB
17. The following environment variables can be at most 44 characters in length:
    • prefix_CLASSLIB_PREFIX
    • prefix_CLIB_PREFIX
    • prefix_PLIB_PREFIX
    • prefix_SLIB_PREFIX
18. The following environment variables can be at most 63 characters in length:
    • prefix_NEW_DATACLAS
    • prefix_NEW_DSNTYPE
    • prefix_NEW_MGMTCLAS
    • prefix_NEW_SPACE
    • prefix_NEW_STORCLAS
    • prefix_NEW_UNIT
    • prefix_WORK_DATACLAS
    • prefix_WORK_DSNTYPE
    • prefix_WORK_MGMTCLAS
    • prefix_WORK_SPACE
    • prefix_WORK_STORCLAS
    • prefix_WORK_UNIT
19. The following environment variables are for specification of the SPACE parameter, and support only the syntax as shown with their default values (including all commas and parentheses). Also as shown with their default values, individual subparameters can be omitted, in which case the system defaults are used.
    • _CCN_IPA_WORK_SPACE
    • prefix_NEW_SPACE
    • prefix_WORK_SPACE
20. The following environment variables are for specification of the DSNTYPE parameter, and support only the subparameters LIBRARY or PDS (or null for no DSNTYPE):
    • prefix_NEW_DSNTYPE
    • prefix_WORK_DSNTYPE
21. The following environment variables can be at most 127 characters in length:
    • prefix_DCBF2008
    • prefix_DCBU
    • prefix_DCB121M
    • prefix_DCB133M
    • prefix_DCB137
    • prefix_DCB137A
    • prefix_DCB3200
    • prefix_DCB80
    • prefix_DEBUG_FORMAT
    These environment variables are for specification of DCB information, and support only the following DCB subparameters, with the noted restrictions:

    RECFM

    Incorrect values are ignored.

    LRECL

    None

    BLKSIZE

    None

    DSORG

    Incorrect values are treated as if no value had been specified.

22. The following environment variables are parsed as blank-delimited words, and therefore no embedded blanks or other white-space is allowed in the value specified. The maximum length of each word is 1024 characters:
    • prefix_INCDIRS
    • prefix_INCLIBS
    • prefix_LIBDIRS
    • prefix_OPTIONS
    • prefix_OPERANDS
23. An S-name is a short external symbol name, such as produced by the z/OS XL C/C++ compiler when compiling C programs with the NOLONGNAME option. An L-name is a long external symbol name, such as produced by the z/OS XL C/C++ compiler when compiling C programs with the LONGNAME option.
24. The z/OS XL C/C++ runtime library supports a file naming convention of // (the filename can begin with exactly two slashes). The c89/cc/c++ command indicates that the file naming convention of // can be used.

    However, the Shell and Utilities feature does not support this convention. Do not use this convention (//) unless it is specifically indicated (as here in c89/cc/c++). The z/OS Shell and Utilities feature does support the POSIX file naming convention where the file name can be selected from the set of character values excluding the slash and the null character.

25. When coding in C and C++, the c89, cc, and c++ commands, by default, produce reentrant executables. For more information about reentrancy, see z/OS XL C/C++ Programming Guide. When coding in assembly language, the code must not violate reentrancy. If it does, the resulting executable may not be reentrant.
26. The prefix_CVERSION, prefix_PVERSION and prefix_CLASSVERSION environment variables are set to a hex string in the format 0xPVVRRMMM where P is product, VV is version, RR is release and MMM is modification level. For example, the prefix_CVERSION and prefix_CLASSVERSION for the z/OS V1R2 compiler is 0x41020000.
27. c89 passes some options to the compiler so that expected behavior is achieved; for example, POSIX behavior. These options are passed onto the compiler as defaults that the user can overwrite. When default options passed by c89 are in conflict with options or pragmas that the user specified, the compiler issues diagnostic messages and may terminate processing. Since the user did not specify options that c89 passed as defaults, these messages may confuse the user. Prior to the z/OS V1R5 release, the compiler was unable to differentiate between the options that c89 passed as defaults and the user-specified options so it was unable to correctly resolve conflicting pragma/option combinations. In some cases, the compiler would overwrite pragmas with the options that c89 passed as defaults thus limiting a user's ability to use pragmas. As of z/OS V1R5, the compiler is now able to recognize c89 defaults and avoid confusion from messages for options, which were not explicitly specified by the user, and overriding pragmas, when the user did not explicitly request it. It is believed that most users will benefit from this feature so it is the default behavior. To enable the old behavior, environment variable prefix_NOCMDOPTS must have a nonzero value.
    The following sequence will preserve the old behavior:

    export _C89_NOCMDOPTS=1
    c89 -o hello hello.c

28. The following example shows the concatenation of data sets in environment variables. It shows how to use an environment variable to setup the SYSLIB DD when using the c89 command name:

    export _C89_LSYSLIB="CEE.SCEELKEX:CEE.SCEELKED:CBC.SCCNOBJ:SYS1.CSSLIB"

    This environment variable will produce the following SYSLIB concatenation:

    //SYSLIB   DD  DSN=CEE.SCEELKEX,DISP=SHR
    //         DD  DSN=CEE.SCEELKED,DISP=SHR
    //         DD  DSN=CBC.SCCNOBJ,DISP=SHR
    //         DD  DSN=SYS1.CSSLIB,DISP=SHR

Localization

Exit values

0

Successful completion.

1

Failure due to incorrect specification of the arguments.

2

Failure processing archive libraries:

• Archive library was not in any of the library directories specified.
• Archive library was incorrectly specified, or was not specified, following the -l operand.

3

Step of compilation, assemble, or link-editing phase was unsuccessful.

4

Dynamic allocation error, when preparing to call the compiler, assembler, IPA linker, prelinker, or link editor, for one of the following reasons:

• The file or data set name specified is incorrect.
• The file or data set name cannot be opened.

5

Dynamic allocation error, when preparing to call the compiler, assembler, prelinker, IPA linker, or link editor, due to an error being detected in the allocation information.

6

Error copying the file between a temporary data set and a hierarchical file system file (applies to the -2 option, when processing assembler source files, and -r option processing).

7

Error creating a temporary control input data set for the link-editing phase.

8

Error creating a temporary system input data set for the compile or link-editing phase.

Portability

For the c89 command, X/Open Portability Guide, POSIX.2 C-Language Development Utilities Option.

For the cc command, POSIX.2 C-Language Development Utilities Option, UNIX systems.

c89 -O2 hello.c
c89 -2 hello.c

c89 -o HelloWorld -2 -Wc,NOANSIALIAS -Wc,XPLINK\ 
-Wl,XPLINK -Wc,'FLOAT(IEEE)' -Wc,'GONUM' HelloWorld.c

Related information

ar, dbx, file, lex, makedepend, nm, strings, strip, yacc