Chapter Contents
Previous
Next
Linking C Programs

COOL Control Statements

As mentioned, input to COOL can be either an object data set, control statements, or both. COOL control statements are listed in COOL Control Statements. An explanation of each statement follows the table.

COOL Control Statements
Control Statement Explanation
ARLIBRARYlibname(,libname . . .) libname refers to an AR370 archive. Under OS/390, libname is a DDname allocated to an AR370 archive. Under CMS, it is the filename of an AR370 archive.
INCLUDE filename filename refers to the sequential data set containing the object code to be input to COOL.
INCLUDElibname(member) libname refers to a partitioned data set. member is the member containing the object code to be input to COOL.
INSERTsymbol symbol is an external symbol. If symbol has not been resolved at the end of primary output processing, the automatic call-library mechanism attempts to resolve it. The INSERT statement is also passed to the linkage editor.
GATHERprefix prefix is a one-to-six character symbol.

The ARLIBRARY Statement

The ARLIBRARY statement is used to specify the location of an AR370 archive. The following syntax is used: 

ARLIBRARY name[,name...]

The name parameters are

COOL adds the libraries specified by the name parameters to the list of AR370 archives to be used as autocall input. Refer to Using AR370 Archives for additional information about using AR370 archives with COOL.

Note:    When the ARLIBRARY control statement is used under the USS OS/390 shell, the filename is interpreted as a DDname. You can use an environment variable to supply a pseudo-DDname in this case, as described under "USS I/O Considerations" in Chapter 3 of the SAS/C Library Reference, Volume 1.  [cautionend]

The INCLUDE Statement

The INCLUDE statement specifies the name of one or more additional files for COOL to use as input. The INCLUDE statement has two formats. The first is the following: 

INCLUDE filename [,...]

In TSO and under OS/390 batch, filename is a DDname that has been allocated to a sequential data set or member of a PDS. Under CMS, filename is the filename of a CMS file. The filetype of the file must be TEXT. The file can be on any ACCESSed disk.

The second format of the INCLUDE statement is the following: 

INCLUDE libname(member[,member])[,...]

In TSO and under OS/390 batch, libname is a DDname that has been allocated to a partitioned data set, and member is the name of a member of a PDS. Under CMS, libname is the name of a TEXT library. The filetype must be TXTLIB. The library can be on any ACCESSed disk. member is the name of a member in the TEXT library. The two formats can be combined on the same statement, for example 

INCLUDE MAINPROG,MYSUBS(SUB1,SUB2),SYSSUBS(GLBLFNC)

An included object file can contain an INCLUDE statement. The specified modules are also included, but any data in the including file after the INCLUDE statement is ignored unless the noinceof option is specified.

On CMS, the _INCLUDE environment variable can be used to specify shared file system directories to be searched for included files. For information on the _INCLUDE environment variable, refer to Specifying Shared File System Directories.

Note:    When the INCLUDE control statement is used under the USS OS/390 shell, the filename is interpreted as a DDname. You can use an environment variable to supply a pseudo-DDname in this case, as described under "USS I/O Considerations" in Chapter 3 of the SAS/C Library Reference, Volume 1.  [cautionend]

The INSERT Statement

The INSERT statement specifies one or more external symbols that are to be resolved, if necessary, via COOL's autocall mechanism. The format of the INSERT statement is 

INSERT symbol [,...]

If the symbol specified by INSERT is not resolved after all primary input has been processed, COOL attempts to resolve it by using automatic library call.

The GATHER Statement

The COOL object code preprocessor supports the GATHER control statement. Use of a GATHER control statement in a COOL input file causes COOL to create data tables based on the GATHER statement operands and append these tables to the COOL output object code. The capability of the GATHER statement was designed primarily for the SAS/C++ translator; occasions for using the GATHER statement will be rare.

Statement format

The format of the GATHER control statement is 

GATHER prefix [,prefix2... ]

where prefix is a one-to-six character symbol. The following statements are examples of valid GATHER control statements. 

GATHER ABC
GATHER INIT,TERM
GATHER I_


How COOL processes the GATHER statement

If at least one GATHER control statement is present in a COOL input file, COOL gathers the names of certain External Symbol Dictionary (ESD) items in a list. There is an ESD item for each external defined or referred entry in object code that names an external symbol. For more information, refer to the IBM OS/VS Linkage Editor and Loader, GC26-813. If the name of the ESD item begins with one of the prefixes given by a GATHER control statement, the name is added to a list of names with that prefix. The lists are used to create tables of pointers to the gathered objects that may be referenced in a C program.

Gathered names

COOL inspects ESD items in the input object module(s) (including autocalled modules) that have the following types.

Some ESD items are not considered for gathering. An SD or LD whose name ends with an at sign (@), a colon (:), a dollar sign ($), an equal sign (=), a plus sign (+), a left angle bracket (<), a right angle bracket (>), or a question mark (?) is not considered since the compiler creates data objects with those names. An ER whose name matches a name of a GATHER table (see below) is not considered.

In C, the following objects can create SDs, LDs, and ERs:
LD label definitions, const extern objects, and extern objects when the norent compiler option is in effect.
ER references to functions, to const extern objects, and to extern objects when the norent compiler option is in effect.
SD No C source construct can create an SD that may be gathered. Note that COOL changes any underscore characters ( '_' ) in a prefix to pound signs ( '#' ). This corresponds to the compiler's changing of underscore characters in external names to pound signs.

Listing the gathered names

COOL prints the gathered names in its listing file if the gmap option has been specified. For a prefix with one or more matching gathered names, COOL prints 

GATHERED FOR PREFIX "xxxxxx":
   xxxxxxx1
   xxxxxxx2
   xxxxxxx3

where xxxxxxx1 , xxxxxxx2 , and so on, are the gathered names. For a prefix for which no matching names were found, COOL prints: 

GATHERED FOR PREFIX "xxxxxx": (NONE)


GATHER tables

For each prefix, COOL creates a GATHER table. A GATHER table is a const extern structure with the following definition: 

struct {
   int count;
   void *entry[N]
} xxxxxx$T;

The count field contains the number of gathered objects. If no names were found that matched the prefix, the count field is set to 0. entry is an array of (4-byte) pointers to the gathered objects. These pointers are in no particular order in the array. N is the number of gathered objects. xxxxxx is the prefix that was used to select the objects. For example, if the items in the table are __local function pointers whose names begin with INIT , then the GATHER table can be declared as follows: 

const extern struct {
   int count;
   __local void (*func[0] )();
} INIT$T;

Note that func can be declared as an array of length 0 , as shown above. This enables the GATHER table to be declared such that the programmer does not need to know the number of items in the array at compile-time.

CAUTION:
Use the dollars compiler option if your program contains references to GATHER table names. Since the name of the GATHER table always contains the dollar sign ($) character, programs containing references to GATHER table names must be compiled with the dollars compiler option. Alternately, the table can be given some other variable name, and the #pragma map directive can be used to assign it the external name of xxxxxx$T .  [cautionend]

An assembler language view

Each GATHER table is a separate CSECT (SD). The pointer array is a set of 0 or more V-type address constants (ERs).

For example, suppose a program contains declarations for four functions whose names start with init : init0001 , init0002 , init0003 , and init0004 and no

declarations or definitions of functions whose names start with term . Given the following control statement 

GATHER INIT,TERM

COOL creates GATHER tables as if object code from the following assembler language statements had been included: 

INIT$T   CSECT
         DC   F'4'
         DC   V(INIT0001)
         DC   V(INIT0002)
         DC   V(INIT0003)
         DC   V(INIT0004)
TERM$T   CSECT
         DC   F'0'
         END


Using GATHER tables

Suppose a number of functions need to be invoked upon entry to the main function of a program, and a number of other functions need to be invoked before the main function returns. The programmer specifies that these functions (and only these functions) will have names that begin with the characters init or term , depending on whether they are to be invoked upon program startup or termination, respectively. The number of functions will be unknown at compile time, as will the complete names. If all of the functions are located in the primary load module, they can be called via __local function pointers. The following GATHER control statement causes COOL to produce GATHER tables for these two sets of functions: 

GATHER INIT,TERM

The following program fragment illustrates how the main function might call the startup and termination functions via the GATHER tables. 

const extern struct {
                int count;
                __local void (*func[0] )();
                }  init$t, term$t;

int main()
{
   int i, rc;

   for (i = 0; i < init$t.count; i++) (*init$t.func[i] )();
   .
   .
   .
   for (i = 0; i < term$t.count; i++) (*term$t.func[i] )();
   return rc;

}

For more information about _ _local function pointers, refer to Local Function Pointers.


Chapter Contents
Previous
Next
Top of Page

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