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.
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:
cool
more than once on any object file that was previously compiled with the
Kextname
option or prelinked with the -p
option.
cool
requires that each input object file have a
unique section name.
cool
utility also resolves external references with defining modules in ar370
archives.
cool
pre-linker is as follows:
The options argument can be one or more of thecool [
options
] [
filename1
[
filename2...
]]
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.
cool
options have two forms:
cool
directly
cool
options at compilation
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
directly, you specify the following
cool -p
filename
sascc370
(or sasCC370
) compiler driver, you specify the following:
sascc370 -Aprem
filename
Note: You can also specifycool -Aprem
filename
cool
options at compilation by prepending the option with -W
l (-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."
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
.
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.
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. | ------------------------------------------------------------------------------------------------------------
cool
option is
shown in parentheses. cool
options with no compiler driver form are described last.
generates an extended name-Acidxref
(-xxx
for standalonecool
)
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)
.
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.-Aclet
(-m
for standalonecool
)
causes-Acontinue
(-zc
for standalonecool
)
cool
to continue processing even if a corrupted ar370
archive is detected.
The -Acontinue
option is equivalent to the mainframe COOL
option CONTINUE
.
causes-Adupsname
(-zd
for standalonecool
)
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.
causes-Agmap
(-yg
for standalonecool
)
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.
specifies an external symbol that is to be resolved by-Ainsert=symbol
(-i symbol
for standalonecool
)
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.
generates an extended name-Alinkidxref
(-xxe
for standalonecool
)
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)
.
causes-Alist
(-yl
for standalonecool
)
cool
to echo input control statements to the listing file.
The -Alist
option is similar to the mainframe COOL
option LIST
.
specifies that-Anoextname
(-n
for standalonecool
)
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.
causes-Anoinceof
(-zi
for standalonecool
)
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
.
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-Anolineno
(-d
for standalonecool
)
-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
.
specifies that-Anortconst
(-r
for standalonecool
)
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
.
suppresses the generation of warning messages.-Anowarn
(-w
for standalonecool
)
The -Anowarn
option is equivalent to the mainframe COOL
option NOWARN
.
deletes extended function names CSECTs in all input object files. By default,-Anoxfnmkeep
(-f
for standalonecool
)
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
.
specifies the number of lines to print per page in the listing file. The default is 55 lines per page.-Apagesize=
nn (-s
nn for standalonecool
)
The -Apagesize
option is equivalent to the mainframe COOL
option PAGESIZE
.
specifies that-Aprem
(-p
for standalonecool
)
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
.
causes-Aprmap
(-yp
for standalonecool
)
cool
to include a pseudoregister map in the listing file.
The -Aprmap
option is similar to the mainframe COOL
option PRMAP
.
causes-Asmponly
(-vo
for standalonecool
)
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
.
causes-Asmpxivec
(-v
for standalonecool
)
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.
generates an extended name-Asnamexref
(-xxs
for standalonecool
)
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)
.
causes-Averbose
(-zv
for standalonecool
)
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
.
specifies that the extended external identifier CSECTs in all input files are retained. By default, these CSECTs are not retained.-Axsymkeep
(-e
for standalonecool
)
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
.
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-h
[name
] (standalonecool
)
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
.
identifies an-l
name
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 lib
name.a
. Note that there must not be a
space between -l
and name.
The -l
option has no effect unless the -L
directory option is also specified.
The -l
option is similar to the mainframe COOL
option ARLIB
.
specifies the name of a directory to be searched for-l
directory
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.
names the file in which the-o
filename
(standalonecool
only)
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.