Pre-Linking C and C++ Programs

Introduction

This chapter describes how to use the cool utility program to pre-link C and C++ programs you have compiled. First, there is a discussion of cool, which is followed by sections that describe the syntax for invoking cool and each of the options that may be specified.

The cool Pre-Linker

The cool utility program is an object code preprocessor that assists in the link-editing of C and C++ programs. cool merges initialization CSECTs for static and external variables; the IBM linkage editor does not have this capability. When the -Krent or -Krentext compiler option is used to allow reentrant modification of data, the compiler creates a separate CSECT to contain the external variable initialization data for each compilation. Data to be used for the initialization of external variables are read during program start-up and copied to dynamically allocated memory. This copy process is necessary to support reentrant execution. (If no external variables are initialized in a compilation, then the CSECT is not created. When the -Krent option is used, this applies to static as well as external variables.)

If more than one compilation initializes external variables, then all of the initialization CSECTs must be merged before the program can be linked. If they are not combined, the linkage editor ignores all but the first compilation's data since they all have the same CSECT name. Therefore, some initializations would be skipped during execution, with unpredictable results.

The cool utility merges this initialization data by combining all of the object code for a given program in a manner similar to the CMS loader or MVS linkage editor. If any of the object files contain an initialization CSECT, cool retains the initialization data and then deletes the CSECT from the object file. When all of the object files are processed, cool produces a single object file containing one copy of the initialization CSECT, followed by the preprocessed object files.

The cool utility also checks for external variables with multiple initial values during the merge. cool issues a warning for external variables with multiple initial values.

When the use of extended names is specified by the -Kextname compiler option, cool performs additional preprocessing. Under the -Kextname option, the compiler creates special data objects in the object file that contains the original C or C++ identifiers and their associated short forms. The cool utility reads these data objects and then creates unique external symbols in the output object file, thus enabling the linkage editor or loader to properly link the output object file by using these unique external symbols.

Note the following:

Syntax

As described in Chapter 2, "Using the SAS/C® Cross-Platform Compiler and C++ Development System" on page 9, the basic syntax for invoking the cool pre-linker is as follows:

 cool [options] [filename1 [filename2...]]
The options argument can be one or more of the cool options listed in Table 13 on page 55 and described in the section "Option Descriptions" on page 57. Note that some functions requested on the mainframe using COOL control statements, such as GATHER and INSERT, are specified to cool on the workstation using options.

Note: You must use the -o option to specify an output file when you invoke cool directly.

Specifying cool Options at Compilation

Most cool options have two forms:

When you call cool directly, you specify one or more of the options listed in Table 13 on page 55. When you specify cool options at compilation, you specify the compiler driver form of the option. Table 13 on page 55 lists each cool option and its corresponding compiler driver form. The compiler driver form begins with -A. The two forms are not interchangeable: You cannot use cool options with the sascc370 and sasCC370 compiler drivers, and you cannot use the compiler driver options with cool.

For example, the compiler driver form of the -p option is -Aprem. The rules for specifying this option are as follows:

cool -p filename
sascc370 -Aprem filename
cool -Aprem filename
Note: You can also specify cool options at compilation by prepending the option with -Wl (-W followed by the letter l). For details on specifying the compilation phase, refer to Chapter 3, "Compiling C and C++ Programs" on page 23. Also see Appendix E, "Compatibility Notes."

Specifying Control Statements

Each cool input file may contain object code, control statements, or both. Control statements must be stored in the EBCDIC character set. Each control statement must be an 80-byte card image, padded with EBCDIC blanks if necessary. Control statements must not be separated by new-line characters. The atoe utility described in Chapter 8, "Conversion of Existing Programs" on page 67 is useful when generating these card images. Any of the COOL control statements described in the SAS/C Compiler and Library User's Guide, Fourth Edition can be used with cool.

Pre-Linker Defaults

Most cool compiler driver options that begin with -A have both a positive and negative form. Most of these default to their negative form if unspecified, but a few default to their positive form.

For example, if you do not specify the -Adupsname option, cool does not allow the same SNAME to be used in multiple input files; specifying -Anodupsname has the same effect. Other options behave the opposite way. For example, cool processes extended names by default (-Aextname). To disable this feature, you must specify the -Anoextname option.

Table 13 on page 55 lists the default for each cool option with a positive and negative form.

Option Summary

The cool options are summarized in the following table. A more detailed description of each option is provided in the section "Option Descriptions" on page 57.

The first column lists the option's compiler driver form. This is the form of the option that you will probably use most often. The second column indicates whether the option can be negated. An exclamation point (!) means that the option can be negated. A plus sign (+) means that the option cannot be negated. Both compiler driver options and cool options can be negated. To negate a compiler driver option, precede the option name with no. For example, to negate the -Acontinue option, specify -Anocontinue. To negate a cool option, precede the option name with ! instead of -, for example !p. The third column lists the default for each option that can be negated. The fourth column lists the standalone cool option. This is the form of the option that you must specify when calling cool directly.

Note that some options have no compiler driver form; they can be used only when calling cool directly.

TABLE 13. cool Options

------------------------------------------------------------------------------------------------------------
| sascc370 Option     | Negation  | Default         | cool Option    | Description                         |
============================================================================================================
| -Acidxref           | !         | -Anocidxref     | -xxx           | Generates an extended name          |
|                     |           |                 |                | CID cross-reference.                |
------------------------------------------------------------------------------------------------------------
| -Aclet              | !         | -Anoclet        | -m             | Suppresses the generation of a      |
|                     |           |                 |                | non-zero return code for cool       |
|                     |           |                 |                | warnings, such as unresolved        |
|                     |           |                 |                | references, and allows an output    |
|                     |           |                 |                | object module to be stored.         |
------------------------------------------------------------------------------------------------------------
| -Acontinue          | !         | -Anocontinue    | -zc            | Continues processing even if a      |
|                     |           |                 |                | corrupted ar370 archive is          |
|                     |           |                 |                | detected.                           |
------------------------------------------------------------------------------------------------------------
| -Adupsname          | !         | -Anodupsname    | -zd            | Allows multiple input files to      |
|                     |           |                 |                | define the same SNAME.              |
------------------------------------------------------------------------------------------------------------
| -Aenexit=prog,data  | +         |                 | -xt prog,data  | Invokes a user exit program with    |
|                     |           |                 |                | optional data.                      |
------------------------------------------------------------------------------------------------------------
| -Agather=prefix     | +         |                 | -g prefix      | Specifies a 1- to 6-character       |
|                     |           |                 |                | GATHER prefix.                      |
------------------------------------------------------------------------------------------------------------
| -Agmap              | !         | -Anogmap        | -yg            | Includes "gathered" symbols in      |
|                     |           |                 |                | the listing file.                   |
------------------------------------------------------------------------------------------------------------
| -Ainsert=symbol     | +         |                 | -i symbol      | Specifies an external symbol that   |
|                     |           |                 |                | is to be resolved by the cool       |
|                     |           |                 |                | autocall mechanism.                 |
------------------------------------------------------------------------------------------------------------
| -Alinkidxref        | !         | -Anolinkidxref  | -xxe           | Generates an extended name          |
|                     |           |                 |                | LINKID cross-reference.             |
------------------------------------------------------------------------------------------------------------
| -Alist              | !         | -Anolist        | -yl            | Echo input control statements to    |
|                     |           |                 |                | the listing file.                   |
------------------------------------------------------------------------------------------------------------
| -Anoextname         | !         | -Aextname       | -n             | Specifies that cool will not        |
|                     |           |                 |                | process extended names.             |
------------------------------------------------------------------------------------------------------------
| -Anoinceof          | !         | -Ainceof        | -zi            | Processes data after an             |
|                     |           |                 |                | INCLUDE statement in an input       |
|                     |           |                 |                | file.                               |
------------------------------------------------------------------------------------------------------------
| -Anolineno          | !         | -Alineno        | -d             | Deletes all the line-number and     |
|                     |           |                 |                | offset table CSECTs.                |
------------------------------------------------------------------------------------------------------------
| -Anortconst         | !         | -Artconst       | -r             | Suppresses the copying of           |
|                     |           |                 |                | run-time constants CSECTs to        |
|                     |           |                 |                | the output object file.             |
------------------------------------------------------------------------------------------------------------
| -Anowarn            | !         | -Awarn          | -w             | Suppresses warning messages.        |
------------------------------------------------------------------------------------------------------------
| -Anoxfnmkeep        | !         | -Axfnmkeep      | -f             | Deletes extended function name      |
|                     |           |                 |                | CSECTs.                             |
------------------------------------------------------------------------------------------------------------
| -Apagesize=nn       | +         |                 | -snn           | Defines the number of lines to      |
|                     |           |                 |                | print per page in the listing file  |
------------------------------------------------------------------------------------------------------------
| -Aprem              | !         | -Anoprem        | -p             | Removes pseudoregisters from        |
|                     |           |                 |                | the output object file.             |
------------------------------------------------------------------------------------------------------------
| -Aprmap             | !         | -Anoprmap       | -yp            | Includes a pseudoregister map in    |
|                     |           |                 |                | the listing.                        |
------------------------------------------------------------------------------------------------------------
| -Asmponly           | !         | -Anosmponly     | -vo            | Creates only an @EXTVEC#            |
|                     |           |                 |                | CSECT.                              |
------------------------------------------------------------------------------------------------------------
| -Asmpxivec          | !         | -Anosmpxivec    | -v             | Creates an @EXTVEC# CSECT.          |
------------------------------------------------------------------------------------------------------------
| -Asnamexref         | !         | -Anosnamexref   | -xxs           | Generates an extended name          |
|                     |           |                 |                | SNAME cross-reference.              |
------------------------------------------------------------------------------------------------------------
| -Averbose           | !         | -Anoverbose     | -zv            | Prints additional informational     |
|                     |           |                 |                | messages.                           |
------------------------------------------------------------------------------------------------------------
| -Axsymkeep          | !         | -Anoxsymkeep    | -e             | Retains extended external           |
|                     |           |                 |                | identifier CSECTs.                  |
------------------------------------------------------------------------------------------------------------
|                     |           |                 |                |                                     |
------------------------------------------------------------------------------------------------------------
| -lname              |           |                 | -lname         | Identifies an ar370 archive,        |
|                     |           |                 |                | libname.a, containing files         |
|                     |           |                 |                | that may be included by cool to     |
|                     |           |                 |                | resolve external references.        |
------------------------------------------------------------------------------------------------------------
| -Ldirectory         |           |                 | -Ldirectory    | Specifies a directory that is       |
|                     |           |                 |                | searched for libname.a files.       |
------------------------------------------------------------------------------------------------------------
|                     |           |                 | -o filename    | Specifies an output file.           |
------------------------------------------------------------------------------------------------------------

Option Descriptions

This section provides a more detailed description of each of the options listed in Table 13. The options are listed alphabetically by compiler driver name. The corresponding cool option is shown in parentheses. cool options with no compiler driver form are described last.

 -Acidxref (-xxx for standalone cool)
generates an extended name CID cross-reference table. The table is displayed following the other cool output directed to stdout. The extended names are displayed in alphabetical order by C identifier.

The -Acidxref option is similar to the mainframe COOL option ENXREF(CID).

 -Aclet (-m for standalone cool)
suppresses the generation of a non-zero return code for cool warnings, such as unresolved references, and allows an output object module to be stored.

 -Acontinue (-zc for standalone cool) 
causes cool to continue processing even if a corrupted ar370 archive is detected.

The -Acontinue option is equivalent to the mainframe COOL option CONTINUE.

 -Adupsname (-zd for standalone cool)
causes cool to permit the same SNAME to be used in more than one input file.

The -Adupsname option is equivalent to the mainframe COOL option DUPSNAME.

 -Aenexit=prog,data (-xt prog,data for standalone cool)
invokes a user exit program with optional data. The prog argument is the UNIX pathname to the program to be invoked. The data argument is 1 to 8 characters of data to be passed to the program; data is optional. For example, you would specify the following to invoke the program at /u/bin/myprog and pass it the value "1 2 3":

 -Aenexit=/u/bin/myprog,"1 2 3"
Note: The rules for quoting the data value are determined by your UNIX shell.

 -Agather=prefix (-g prefix for standalone cool)
causes cool to create data tables based on the prefix argument and append these tables to the cool output object code.

The -Agather option is similar to the GATHER control statement used with the mainframe COOL utility. The -Agather option is used primarily with C++; occasions for using the -Agather option are rare. Refer to the SAS/C Compiler and Library User's Guide, Fourth Edition for more information.

 -Agmap (-yg for standalone cool)
causes cool to print a cross-reference of "gathered" symbols in the listing file.

The -Agmap option is similar to the mainframe COOL option GMAP. Refer to the SAS/C Compiler and Library User's Guide, Fourth Edition for more information.

 -Ainsert=symbol (-i symbol for standalone cool)
specifies an external symbol that is to be resolved by cool, if necessary. If the symbol specified by the -Ainsert option is not resolved after all primary input has been processed, cool attempts to resolve it from an ar370 archive.

The -Ainsert option is similar to the INSERT control statement used with the mainframe COOL utility.

 -Alinkidxref (-xxe for standalone cool)
generates an extended name LINKID cross-reference table. The table is displayed following the other cool output directed to the standard output device. The extended names are displayed in alphabetical order using a link id that cool assigns.

The -Alinkidxref option is similar to the mainframe COOL option ENXREF(LINKID).

 -Alist (-yl for standalone cool) 
causes cool to echo input control statements to the listing file.

The -Alist option is similar to the mainframe COOL option LIST.

 -Anoextname (-n for standalone cool) 
specifies that cool will not process extended names. The -Anoextname option is equivalent to the mainframe COOL option NOEXTNAME.

For more information about extended names processing, see the description of the -Kextname compiler option in Chapter 3, "Compiling C and C++ Programs" on page 23.

 -Anoinceof (-zi for standalone cool) 
causes cool to process data following an INCLUDE statement in an input file. By default, cool ignores any data following an INCLLUDE statement for compatibility with the IBM linkage editor.

The -Anoinceof option is equivalent to the mainframe COOL option NOINCEOF.

 -Anolineno (-d for standalone cool) 
deletes all the line-number and offset table CSECTs from the output object code. These CSECTs are generated by the cross-platform compiler when the -Klineno compiler option is used.

Line-number and offset table CSECTs are used by the debugger and run-time library to compute the address of a source line number in a function. If these CSECTs are not present, the debugger cannot break on a source statement and run-time library ABEND tracebacks do not contain function line numbers.

The -Anolineno option is equivalent to the mainframe COOL option NOLINENO.

 -Anortconst (-r for standalone cool) 
specifies that cool is to suppress copying the run-time constants CSECTs from the output object file. The resulting object file will be somewhat smaller but certain information used by the debugger will not be available. By default, cool copies these CSECTs from the input file(s) to the output file.

The -Anortconst option is equivalent to the mainframe COOL option NORTCONST.

 -Anowarn (-w for standalone cool) 
suppresses the generation of warning messages.

The -Anowarn option is equivalent to the mainframe COOL option NOWARN.

 -Anoxfnmkeep (-f for standalone cool) 
deletes extended function names CSECTs in all input object files. By default, cool retains these CSECTs.

The extended function names CSECT may be useful at run time if you are using the SAS/C Debugger to debug your program. If the CSECT containing the extended function name is available, the debugger uses the extended name in displays and accepts the extended name in commands. Refer to the SAS/C Debugger User's Guide and Reference, Third Edition for more information about the debugger. Also, if the CSECT that contains the extended function name is present, the library ABEND-handler includes the extended name in ABEND tracebacks.

The -Anoxfnmkeep option is equivalent to the mainframe COOL option NOXFNMKEEP.

 -Apagesize=nn (-snn for standalone cool) 
specifies the number of lines to print per page in the listing file. The default is 55 lines per page.

The -Apagesize option is equivalent to the mainframe COOL option PAGESIZE.

 -Aprem (-p for standalone cool) 
specifies that cool is to remove pseudoregisters from the output object file.

The -Aprem option is automatically enabled if either the -Tcms370 or the -Tpcms370 compiler option is specified.

The -Aprem option is equivalent to the mainframe COOL option PREM.

 -Aprmap (-yp for standalone cool) 
causes cool to include a pseudoregister map in the listing file.

The -Aprmap option is similar to the mainframe COOL option PRMAP.

 -Asmponly (-vo for standalone cool) 
causes cool to build the @EXTVEC# vector described under the -Asmpxivec option. The remaining portion of the cool output is suppressed, so that the entire object file consists of only the @EXTVEC# CSECT.

The -Asmponly option is equivalent to the mainframe COOL option SMPONLY.

 -Asmpxivec (-v for standalone cool) 
causes cool to build a vector named @EXTVEC# that references the sname@ vector generated by the -Ksmpxivec compiler option. The sname@ vector provides an alternate mechanism for reentrant initialization of static and extern data used with SMP update methods.

The -Asmpxivec option is equivalent to the mainframe COOL option SMPXIVEC. The -Ksmpxivec cross-platform compiler option is described in Chapter 3, "Compiling C and C++ Programs" on page 23. For more information about SMP, refer to Programmer's Report: SMP Packaging for SAS/C Based Products.

 -Asnamexref (-xxs for standalone cool) 
generates an extended name SNAME cross-reference table. This table is displayed in alphabetical order, sorted on the SNAME associated with each object file, following the other cool output directed to stdout.

The -Asnamexref option is similar to the mainframe COOL option ENXREF(SNAME).

 -Averbose (-zv for standalone cool) 
causes cool to produce extra messages about its processing. These messages are displayed on the standard error device, and are included in the listing if a listing file is being produced. These messages are particularly useful for determining how symbols are resolved.

The -Averbose option is equivalent to the mainframe COOL option VERBOSE.

 -Axsymkeep (-e for standalone cool) 
specifies that the extended external identifier CSECTs in all input files are retained. By default, these CSECTs are not retained.

Note that retaining the extended function names CSECT or the extended external identifier CSECT makes the resulting pre-linked object file somewhat larger.

The -Axsymkeep option is equivalent to the mainframe COOL option XSYMKEEP.

 -h [name] (standalone cool) 
produces a listing and, optionally, directs the listing to the specified file. If you do not specify a file name, the listing is directed to stdout (the standard output device). The listing file contains a list of the options that are in effect and copies of any diagnostic messages. All cool messages are directed to the listing file and to stderr (standard error device). "Trivial" messages, like banners and the cool return code message, are directed to the listing file and also to stdout, if stdout is not the listing and the -zv (verbose) option is specified.

When you specify any of the following cool options, -h is assumed: -yl, -yp, -yg, -xxe, -xxs, -xxx.

You can also use the -Klisting compiler option to produce a listing for all phases of the compilation, including the pre-linking phase. Message handling is the same as -h. When you specify any of the following cool options during compilation, -Klisting is assumed: -Alist, -Aprmap, -Agmap, -Alinkidxref, -Asnamexref, -Acidxref.

 -lname
identifies an ar370 archive containing members that may be included by cool to resolve unresolved external references. The name parameter specifies the filename of the ar370 archive. cool will look for the archive named libname.a. Note that there must not be a space between -l and name.

The -l option has no effect unless the -Ldirectory option is also specified.

The -l option is similar to the mainframe COOL option ARLIB.

 -ldirectory
specifies the name of a directory to be searched for ar370 archives. Note that there must not be a space between -L and directory.

The -L option is similar to the ARLIBRARY control statement used with the mainframe COOL utility.

 -o filename (standalone cool only) 
names the file in which the cool utility stores its output. This option must be specified when cool is invoked as a stand-alone utility. If cool is invoked by sascc370 or sasCC370, the output is directed to the a.out file by default unless the -o compiler option is specified.