Chapter Contents
Previous
Next
Linking C Programs

COOL Options

This following table lists the options available for the COOL utility and the systems to which these options apply. A description of each option follows the table.

COOL Options
Option TSO CMS OS/390 Batch USS
--Agather


X
--Ainsert


X
allresident X X
X
arlib X


auto X X X
--Bep


X
--Blib


X
cics X X
X
cicsvse X X
X
clet X X X X
clet(all) X X X X
clet(noex) X X X X
continue X X X X
cxx X X

dupsname X X X X
endisplaylimit X X X X
enexit X X X X
enexitdata X X X X
entry X


enxref X X X X
extname X X X X
files

X
genmod
X

global
X

gmap X X X X
gos X X

inceof X X X X
--1


X
--L


X
lib X


libe
X

lineno X X X X
list X X X X
lked
X

lkedname X
X
load X

X
loadlib X


nocool X
X
output
X

pagesize X X X X
prem X X X X
print X X
X
prmap X X X X
rtconst X X X X
smpjclin X X X X
smponly X X X X
smpxivec X X X X
spe X X
X
start
X

term X X X
upper X X X X
verbose X X X X
warn X X X X
xfnmkeep X X X X
xsymkeep X X X X

-Agather= prefix (USS only)
specifies a prefix to be used by COOL in creating a table of symbols whose names begin with the prefix. The effect of this option is the same as if the input contained a GATHER prefix control statement. See The GATHER Statement for more information.

-Ainsert= symbol (USS only)
specifies a symbol which must be resolved during COOL processing. If the symbol is not defined in a COOL input file, the symbol will be resolved by autocall. The effect of this option is the same as if the input contained an INSERT symbol control statement.

allresident ( -Tallres under USS)
specifies use of the all-resident library. This option should be specified only when linking an all-resident program. If the application is intended to run under CICS, the cics or cicsvse option must also be specified so that the correct version of the all-resident library is used.

allowrecool
specifies that the output object deck can be reprocessed by COOL. Therefore, the deck is not marked as already processed by COOL.

The default noallowrecool specifies that the output object cannot be reprocessed by COOL. A later attempt to reprocess the deck with COOL will produce an error.

The short form for this option is -rc .

Note:   COOL does not modify the object deck to enable reprocessing. It is the user's responsibility to determine if a particular object is eligible for reprocessing.  [cautionend]

arlib
in TSO, identifies an AR370 archive containing members that may be included by COOL to resolve unresolved external references. The form of the arlib option is as follows: 
arlib(archive)

The archive parameter specifies the data set name of the AR370 archive. If the data set belongs to another user, the fully qualified name of the data set must be given, and the name must be preceded and followed by three single quotes.

auto
specifies that COOL should resolve external references by searching the SYSLIB PDS under OS/390 or by searching for TEXT files on an accessible minidisk on CMS. auto is the default. noauto suppresses resolution of external references from these sources. Note that when an unresolved reference to the symbol ref is processed, auto attempts to resolve it from SYSLIB(ref) on OS/390 or from ref TEXT on CMS. The auto option is similar to the AUTO option of the CMS load command.

-Bep= entry (USS only)
specifies the entry point required for the output load module. The default specification is -Bep=MAIN , which assigns the normal C entry point MAIN . The name specified must be an external symbol defined in the load module. See Specifying the Correct Entry Point for more information about entry point specifications. Note that you can suppress the normal entry point of MAIN without requesting any other entry-point by specifying -Bnoep . You should do this only when one of the object files to be linked includes an ENTRY linkage editor control statement.

-Blib= library (USS only)
specifies the name of an OS/390 library to use as a link-edit autocall library. Any number of autocall libraries may be specified, in either object module or load module format. These libraries are not accessed until COOL processing has completed. This means that any references, which can only be resolved from a -Blib library, will remain unresolved by COOL. Therefore, the -Aclet option should also be specified to allow link processing to occur. Note that the library name should not be preceded by a style prefix such as //dsn: , since only OS/390 libraries can be specified with this option.

cics ( -Tcics370 under USS)
specifies that the program should be linked for execution under CICS on OS/390. This option causes appropriate CICS libraries to be added to COOL's list of autocall libraries. The exact libraries that are used depend on whether other options, such as spe and allresident , were specified.

cicsvse ( -Tcicsvse under USS)
specifies that the program should be linked for execution under CICS on VSE. This option causes appropriate CICS libraries to be added to COOL's list of autocall libraries. The exact libraries that are used depend on whether other options, such as spe and allresident , were specified.

clet(all) (-Aclet or -Acletall under UNIX System Services)
specifies that COOL is to store an output file even if unresolved external reference errors occur. The unresolved references may be for either extended or non-extended names. Neither type of unresolved reference will result in an error return code. Under UNIX System Services, by default, no output file is generated if any missing symbols or other errors (RC >= 8) are detected by COOL. clet(noex) is the default in all other environments that COOL runs under.

In UNIX System Services, the -Aclet option is maintained for backward compatibility. It is equivalent to -Acletall.

Under OS/390 batch and TSO, the clet(all) option takes the following form: 

clet(all)

In CMS, the clet(all) option takes the following form: 

clet  all

clet(noex) (-Acletnoex under UNIX System Services)
specifies that COOL is to store an output file even if unresolved external reference errors occur. The unresolved references may be for either extended or non-extended names. Unresolved references to non-extended names do not result in an error return code. However, unresolved references to extended names result in an error return code. Under UNIX System Services, by default, no output file is generated if any missing symbols or errors (RC >= 8) are detected by COOL. Otherwise, this option is the default.

Under OS/390 batch and TSO, the clet(noex) option takes the following form: 

clet(noex)

In CMS, the clet(noex) option takes the following form: 

clet noex

continue ( -Acontinue under USS)
specifies that processing should continue even if a corrupted AR370 archive is detected.

cxx
specifies that the program being linked includes one or more C++ modules. This option makes the C++ library archive available for resolution of external references. This option should be specified even if the program does not directly use any C++ library functions.

dupsname ( -Adupsname under USS)
causes COOL to permit the same SNAME to be used in more than one input file. nodupsname is the default. Do not specify dupsname if any input module uses extended names, or the results will be unpredictable.

enexit ( -Aenexit under USS)
causes COOL to invoke a user exit without passing any data to the exit. See User Exit Selection of External Symbols for additional information.

endisplaylimit(nnn)
defines the maximum number of characters used to display extended names in messages and listings. nnn represents the maximum number of characters that can be used to display extended names. nnn can be an asterisk (*) specifying that extended names are to be fully displayed regardless of their length, or it can be a number. The minimum endisplaylimit default value of 91 is set internally and cannot be overridden. You can set the default value to a larger number, or use the asterisk to ensure the return of the full-length names, but you cannot set the default value to a number smaller than 91.

OS/390 batch and TSO
endisplaylimit
Under OS/390 batch and TSO, the endisplaylimit option takes the following form:

endisplaylimit(nnn)

UNIX System Services
Under UNIX System Services, the endisplaylimit option takes the following form:

-Aendisplaylimit=nnn

CMS
Under CMS, the endisplaylimit option takes the following form:

endisplaylimit nnn

Cross-Platform
See Chapter 6, "Prelinking C and C++ Programs" in the SAS/C Cross-Platform Compiler and C++ Development System: Usage and Reference for information on the cross-platform implementation of endisplaylimit.

enexitdata ( -Aenexitdata= data under USS)
causes COOL to invoke a user exit and pass one to eight characters of user-specified data. Under TSO and OS/390 batch, enexitdata has the following form: 
enexitdata(userdata)

Under CMS, the enexitdata option has the following form: 

enexitdata userdata

See User Exit Selection of External Symbols for additional information.

entry
In TSO, the keyword 
entry(name)

identifies the program's entry point or enables the linkage editor to determine the entry point. The entry keyword can be specified in the following ways:

entry(main)
for a program containing a main function. The actual entry point is MAIN.

entry(dyn)
for a reentrant dynamically loaded module. The actual entry point is #DYNAMN.

entry(dynnr)
for a non-reentrant dynamically loaded module. The actual entry point is #DYNAMNR.

entry(os)
for an OS SPE application with initial function osmain . The actual entry point is #OSEP.

entry(oe)
for an SPE application with initial function oemain , intended for use under the USS shell or from the pdscall utility. The actual entry point is #OEEP.

entry(none)
for allowing the linkage editor to select the entry point itself. Use of entry(none) is recommended only if a linkage editor entry statement is present in one of the input files. If entry is not specified, entry(main) is assumed, unless SPE is specified; in that case, entry(none) is assumed.

enxref ( -Asnamexref , -Acidxref , or -Alinkidxref under USS)
When producing object files that contain extended names, COOL produces by default three cross-references that are generated in a table that follows all other COOL output. These three cross-references are sname , cid , and linkid . sname is in alphabetical order by the sname that uniquely identifies an object file. cid displays the extended names in alphabetical order by C identifier. linkid displays the extended names in alphabetical order by a link id that COOL assigns. The enxref option controls the production of these cross-references so external symbols that are declared but not defined will be printed in the cross-references listing. noenxref suppresses the production of all extended names cross-references.

For Release 6.50, when the references option is specified for enxref , referenced symbols as well as defined symbols are included in the cross-reference listing.

You can use the references option (-Areferences under UNIX System Services) to modify the behavior of the sname, cid, or linkid cross-reference listing so that cross-references to external symbols that are declared but not defined are included in the listing. You must use the references option in conjunction with one or more of these listing options: sname, cid, or linkid. For example: 

enxref(sname references)
specifies an sname cross-reference listing that includes cross-references for external symbols that are declared but not defined.

In TSO, the enxref option takes the following form: 

enxref('cross-ref ,cross-ref ,cross-ref ')
where cross-ref is sname , cid , or linkid , or the negation. For example: 
enxref('nosname,cid')

suppresses the sname cross-reference and enables the CID cross-reference.

Under CMS, the enxref option takes the following form: 

enxref [cross-ref] [cross-ref] [cross-ref]
where cross-ref is sname , cid , or linkid , or the negation. For example: 
enxref nosname cid
suppresses the sname cross-reference and enables the cid cross-reference.

Under OS/390 batch, the enxref option takes the following form: 

enxref(cross-ref ,cross-ref ,cross-ref )
where cross-ref is sname , cid , or linkid , or the negation. For example: 
enxref(nosname,cid)
suppresses the sname cross-reference and enables the cid cross-reference.

Under USS, the sname , cid , and linkid cross-references are generated by the -Asnamexref , -Acidxref , and -Alinkidxref options, respectively.

extname ( -Aextname under USS)
specifies that COOL is to process extended names. extname is the default. noextname specifies that COOL will not process extended names. For more information on the extname option, refer to Compiler Options.

files
under OS/390, specifies the first 1 to 3 characters in DDnames referenced by COOL. The files option has the following form: 
files(xxx)
where xxx is from 1 to 3 characters. The default is SYS.

genmod
causes the COOL EXEC to create a module file using the specified name and GENMOD options. The genmod option takes the following form: 
genmod [filename [options]]

The genmod option must follow the use of any other option on the command line. The genmod option causes the COOL EXEC to issue the following CMS commands after COOL has created the COOL370 TEXT file: 

LOAD COOL370 (NOAUTO NOLIBE CLEAR
GENMOD filename   (options

where filename is either the filename specified following the genmod keyword or the first name specified in the COOL command. If no filenames are specified in the command, the COOL EXEC issues an error message.

global
specifies that the COOL EXEC should query the environment variable TXTLIBS in the GLOBALV group LC370 for the name or names of TXTLIBs that are to be GLOBALed before COOL begins execution. global is the default. noglobal suppresses automatic query of the environment variable TXTLIBS: the EXEC does not issue a GLOBAL TXTLIB command based on the environment variable. (See Other Environment Variables for more information.)

gmap ( -Agmap under USS)
causes a listing of any gathered names in the listing file. The gmap option causes the print option to be assumed and a listing file to be generated.

gos
specifies that the program should be linked for execution with the GOS (generalized operating system) libraries. This option causes the GOS library to be added to COOL's list of autocall libraries. Note that in TSO, the output of the COOL command is a load module, which may not be suitable for execution under the target operating system.

ignorerecool
specifies that if any marks are detected indicating that COOL has already processed an input object deck, then the marks are to be ignored. If the ignorerecool option is specified along with the verbose option, then a diagnostic message is issued and processing continues.

The default noignorerecool specifies that any mark indicating that COOL has already processed an input object deck should result in an error message and process termination.

The short form for this option is -ri .

inceof ( -Ainceof under USS)
specifies that when an INCLUDE statement is encountered in an included file, the specified file is included, but any data following the statement is ignored. The default is inceof . This is compatible with the behavior of the IBM linkage editor. noinceof can be specified to allow the use of multiple nested INCLUDE statements.

-l name (USS only)
specifies that the archive lib name .a is to be searched for unresolved external references. sascc370 looks for the archive in the directories specified by any -L option specifications before looking in the lib subdirectory of the directory where SAS/C was installed. Note that there must not be a space between -l and name. The -l option has no effect unless the -L option is also specified.

-L directory (USS only)
specifies a directory to be searched for archives requested by the -l option. The directories referenced by -L are searched in the order that the -L options appear on the command line. Note that there must not be a space between -L and directory.

lib
specifies the data set name of an autocall object library containing functions that are to be linked automatically into the program if referenced. This option takes the following form: 
lib (dsname)
where dsname is the data set name of an autocall object library. If the library belongs to another user, the fully qualified name of the data set must be given and the name must be preceded and followed by three single quotes. No final qualifier is assumed for a LIB data set. (Note that load module libraries cannot be used.)

libe
under CMS, the libe option causes COOL to search GLOBALed TXTLIBs during automatic symbol resolution. This option is in effect by default and may be turned off by specifying nolibe .

lineno ( -Alineno under USS)
controls line numbering. The COOL lineno option is similar to the compiler lineno option. You can specify either lineno or nolineno ; the default is lineno . If you specify nolineno ( -Anolineno under USS), COOL deletes all the line-number and offset table CSECTs from the output object code.

The line-number and offset table CSECTs are generated by the compiler when the compiler lineno option is used. (This is the default for the compiler.) These 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.

list ( -Alist under USS)
causes COOL to copy any control statements in its input to the listing file. list causes the print option to be assumed. The default is nolist .

lked
specifies that the COOL EXEC is to issue an LKED command for COOL370 TEXT, using the LKED options specified. The lked option must follow the use of all other COOL options on the command line. The lked option causes the COOL EXEC to issue the following CMS command after COOL has created the COOL370 TEXT file: 
LKED COOL370 (options
where options are any LKED command options specified following the lked keyword.

lkedname
specifies the name of the linkage editor to be invoked after COOL has completed. By default, the standard system linkage editor is invoked. This option is provided to allow sites which run the binder in place of the linkage editor to access the linkage editor instead.

load ( -o name under USS)
in TSO, names the data set in which the linkage editor stores the output load module. This option takes the form: 
load (dsname)
where dsname is the name of the data set in which the linkage editor stores the output load module. This keyword should specify a partitioned data set member. If the data set belongs to another user, the fully qualified name of the data set must be given, and the name must be preceded and followed by three single quotes. If the data set name is not specified within three single quotes, it is assumed to be a data set name with a final qualifier of LOAD. Additional considerations follow:

Under USS, the -o name option specifies the name of a file where the output load module is to be stored. This may be specified as either an HFS file or as a member of an OS/390 PDS. There must be a space between -o and name. If the output module is stored in an OS/390 PDS, the name should be prefixed with a //dsn: or //tso: prefix. If no -o option is specified, the linked output module is stored in the HFS file a.out . Note that if the sascc370 -c option is specified, the linkage editor is not invoked, and the -o option determines where the compiler's output is stored. See the description of the object option in Option Descriptions for details about the -c compiler option.

loadlib (also see -Blib )
specifies the data set name of an autocall load library containing modules that are to be linked automatically into the program if referenced. This option takes the following form: 
loadlib (dsname)
where dsname is the name of an autocall load library. If the library belongs to another user, the fully qualified name of the data set must be given, and the name must be preceded and followed by three single quotes. Note that modules in the loadlib data set are resolved by the linkage editor and not by COOL. COOL diagnoses any symbols which require resolution from this library as unresolved. No final qualifier is assumed for a loadlib data set. You must use loadlib , rather than lib , to reference libraries that are associated with IBM products such as ISPF and GDDM, since those libraries are stored in load module format.

nocool
specifies that the COOL preprocessor is not to be run. In this case, the input is processed only by the OS/390 linkage editor.

output
specifies the name of the COOL output file. Under CMS, the default COOL output file is COOL370 TEXT A1. If specified, the output option must be the last option on the COOL command line and is followed by all or part of a CMS fileid or Shared File System fileid.

A CMS fileid is specified as follows: 

COOL myprog (OUTPUT filename [[.]filetype [[.]filemode]]
where filename, filetype, and filemode identify the COOL output file. For example, the following command writes the COOL output file to AOUT TEXT A1: 
COOL myprog (output aout text a1

If you omit the filetype or filemode, COOL uses TEXT as the default filetype and an asterisk (*) as the default filemode.

An SFS fileid is specified as follows: 

COOL myprog (output sf:filename [filetype [dirname]]
where dirname is the complete directory name or the NAMEDEF that has been logically assigned to it. If you omit filetype or dirname, the default filetype is TEXT and the default directory name is a period (.).

Note:    The output option may not be used with the genmod , lked , or start option. Each of these options, if specified, must be the last option on the COOL command line.  [cautionend]

pagesize ( -Apagesize= nn under USS)
specifies the number of lines to print per page. Under TSO and OS/390 batch, the form of this option is as follows: 
pagesize(nn)

where nn is the number of lines. By default, pagesize(55) is specified.

Under CMS, the following form is used: 

pagesize nn

prem ( -Aprem under USS)
specifies that COOL is to remove pseudoregisters from the output object module. Under CMS, the default is prem ; under OS/390, the default is noprem ; under USS, the default is -Anoprem . Under CMS, the prem option allows limitations of the CMS loader to be bypassed. Under OS/390, this option has little use except in certain ILC applications. See the SAS/C Compiler Interlanguage Communication Feature User's Guide for further information.

print ( -Klisting under USS)
causes COOL to create a listing file that contains a list of the options that are in effect and copies of any diagnostic messages. Under CMS and OS/390, all messages are directed to the listing file and also to stderr if the term option is specified. Under USS, messages are always sent to stderr , as well as the listing file.

Under CMS, use the following syntax: 

print fileid

The fileid must be specified in compressed form, that is, with periods rather than spaces separating the components of the name. If print is not specified under CMS, the listing is produced in the file COOL370 COOLLIST.

In TSO, use the following syntax: 

print(filename)

If print is specified in TSO without a filename, the listing is directed to the terminal.

Note that the use of other options that write to the listing file cause the print option to be assumed, including list , prmap , gmap , and enxref . In TSO, if noprint is specified or defaulted, no listing is generated regardless of other option settings.

Under USS, the -Klisting compiler option produces a listing for all phases of the compilation. It also lets you specify the name of the listing file. When you specify any of the following COOL options during compilation, -Klisting is assumed: -Alist , -Aprmap , -Agmap , -Alinkidxref , -Asnamexref , -Aacidxref . See Compiler Options for details about -Klisting .

prmap ( -Aprmap under USS)
causes COOL to include a pseudoregister map in the listing file. If prmap is specified, print is implied and will produce a list of options in effect and diagnostic messages, in addition to the output requested by prmap . noprmap is the default.

rtconst ( -Artconst under USS)
specifies that COOL is to retain the run-time constants CSECTs in the output object file. This is the default. nortconst causes COOL to delete these CSECTs. The resulting object file will be somewhat smaller, but certain information used by the debugger will not be available.

smpjclin ( -Asmpjclin under USS)
generates a list of linkage editor INCLUDE statements for elements resolved as external references from SMP format libraries. The INCLUDE statements are written to the file identified by the DDname SYSJCLIN. Under CMS, a FILEDEF command can be used to define the DDname, and under the USS shell, the ddn_SYSJCLIN environment variable can be specified.

The list generated by the smpjclin option can be used to build an SMPJCLIN file that defines the structure of a software product, including its use of SAS/C Library elements. The SMPJCLIN file is used when an application is to be distributed in System Modification Program (SMP) format. The smpjclin option can only be used if you have SMP libraries. For more information, refer to Programmer's Report: SMP Packaging for SAS/C Based Products.

smponly ( -Asmponly under USS)
causes COOL to build the @EXTVEC# vector described under the spmxivec option. The remaining portion of the COOL output is suppressed so that the entire output object file will consist of only the @EXTVEC# CSECT.

smpxivec ( -Asmpxivec under USS)
causes COOL to build a vector named @EXTVEC# that references sname@. CSECTs that are generated when the smpxivec option is specified. This vector table is prepended to the COOL output file. The smpxivec option is provided to accommodate SMP update methods. Refer to SAS Programmer's Report: SMP Packaging for SAS/C Based Products for more information on this option.

spe ( -Tspe under USS)
specifies that the program should be linked for execution with the SPE (Systems Programming Environment) libraries. This option causes the SPE library to be added to COOL's list of autocall libraries.

start
specifies that the COOL EXEC is to issue a LOAD command for COOL370 TEXT, followed by a START command and any of the START options specified. The start option must follow the use of all other COOL options on the command line. The format of the start option is as follows: 
start options

The start option causes the COOL EXEC to issue the following CMS commands after COOL has created the COOL370 TEXT file: 

LOAD COOL370 (NOAUTO NOLIBE CLEAR
START options
where options are any START command options specified following the start keyword.

term
directs COOL error messages to stderr in addition to any other targets. No attempt is made to prevent a message from being sent to the same target via multiple files. In most environments, stderr is the user's terminal. For OS/390 batch, stderr references the DDname SYSTERM. noterm suppresses error message listing to stderr . The default is term .

upper ( -Aupper under USS)
produces all output messages in uppercase.

verbose ( -Averbose under USS)
causes COOL to produce extra messages about its processing, both to the terminal (if term is in effect) and to the listing (if a listing is being produced). These messages are useful for determining how symbols are resolved. The default is noverbose .

warn ( -Awarn under USS)
specifies that warning messages (associated with return code 4) are to be issued. warn is the default. nowarn suppresses warning messages.

xfnmkeep ( -Axfnmkeep under USS)
specifies that extended function name CSECTs are retained in all input object files. Note that this makes the resulting prelinked object file somewhat larger. By default, xfnmkeep is specified.

The extended function name CSECTs may be useful at runtime, if you are using the SAS/C Debugger. 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 for more information on the debugger.) Also, if the CSECT that contains the extended name is present, the library abend-handler includes the extended name in abend tracebacks.

See Extended Names for additional information about the xfnmkeep option.

xsymkeep ( -Axsymkeep under USS)
specifies that the extended external identifier CSECTs in all input files are retained. Note that this makes the resulting prelinked object file somewhat larger. By default, noxsymkeep is specified.

See Extended Names for additional information about the xsymkeep option.


Chapter Contents
Previous
Next
Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.