Linking C Programs

The COOL Object Code Preprocessor

COOL (C object-oriented linker) is a utility program that assists in the link-editing of C programs. COOL merges CSECTs for external or static variables; the IBM linkage editor does not have this capability. When the rent or rentext compiler option is used, the compiler creates a separate control section (CSECT) to contain the external variable initialization data (see Compiler-generated Names) for the current compilation. Data that are to be used for the initialization of external variables are copied during program startup from these CSECTs to dynamically allocated memory. This copy process is necessary to support reentrant execution. If the rentext option is used, only initialization data for external variables is stored in the initialization data CSECT. Also, with any compiler option, initialization data for __rent variables is stored in the initialization data CSECT. (If a compilation contains no initializations of any of the types described above, no initialization CSECT is created.)

If more than one compilation initializes applicable 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.

COOL merges this initialization data by combining all of the object code for a given program in a manner similar to the CMS loader or OS linkage editor. If any of the object modules contain an initialization CSECT, COOL retains the initialization data and then deletes the CSECT from the object module. When all of the object modules are processed, COOL produces a single object module containing a single merged initialization CSECT, followed by the preprocessed object files.

COOL also checks for __rent variables with multiple initial values during the merge. COOL issues a warning for external variables that have multiple initial values. (See Reentrant and Non-reentrant Identifiers for more information about external variables.)

COOL also prepares object files for linking when the extname compiler option is specified. Under the extname option, the compiler creates special data objects in the object file that contain the original C identifiers and their associated short forms. COOL 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. Refer to Linking Programs under CMS for more information about extended names processing.

Under CMS, C programs compiled with the rent or rentext option may exceed the LOAD pseudoregister limit. By default, COOL changes the pseudoregister definitions in the object modules to a form that the LOAD command can handle. For more information on COOL and the CMS LOAD command, refer to Linking Programs under CMS.

Prior to Release 6.50, a problem frequently encountered was an attempt to process an object deck with COOL that had already been prelinked by COOL. This caused a number of problems, not obviously related to the attempt to reprocess an object with COOL, and usually resulted in an ABEND. In this release, COOL marks each object deck as it is processed and if an attempt is made to reprocess the marked object, COOL produces a diagnostic message indicating the condition.

The new processing is divided into two phases. The first phase marks the output object deck to indicate it has already been processed with COOL. It is controlled by the allowrecool and noallowrecool options. The second phase detects that an input object deck has been marked to indicate it was previously processed. The second phase is controlled by the ignorerecool and noignorerecool options. By default, COOL marks the object deck to prevent an attempt to reprocess it. Also by default, COOL detects that the input object deck was previously processed by COOL.

Note: These defaults can cause COOL to indicate an error where it would not detect such an error in previous releases. Under certain restricted circumstances, it is possible to generate object code that can be successfully processed by COOL more than once. If this behavior is desired, the options can be specified such that the output object's decks are not marked and/or that such marking be ignored. [cautionend]

Note: You may not reprocess COOL output with COOL if any object file was compiled with the extname option. [cautionend]

When to Use COOL

You must use COOL to preprocess your object code if any of the following conditions apply:

More than one compilation initializes a __rent variable. There are four ways a variable is assigned the __rent attribute:
- The variable is external and the compiler option rent or rentext is used.
- The variable is static and the compiler option rent is used.
- The variable is external and the name begins with an underscore.
- The variable is declared __rent .
For more information on the __rent attribute see Reentrant and Non-reentrant Identifiers.
More than one compilation was compiled with the extname option.
Under CMS, the cumulative length of the pseudoregister vector exceeds the maximum size permitted by the loader.
At least one C++ function is used.
The SAS/C All-Resident Library was used.
Some of the object modules are stored in an AR370 archive.

Under OS/390, if you fail to run COOL in a situation that requires it, the linkage editor will generate message IEW0461 or IEW2480W referencing the symbol NO_CLINK . This message indicates that use of COOL was required, and that the resulting load module is unlikely to execute correctly.

Under CMS, if you attempt to load object code that requires the use of COOL and COOL has not been used to preprocess the object modules, the loader issues message DMSLIO020W referencing the symbol NO_CLINK . If this situation arises, the use of COOL is required.

A special case

For most programs compiled with the norent and noextname options, you do not need to use COOL. The only exception to this rule is if more than one compilation initializes external variables that begin with an underscore (such as the _options variable). External variables that begin with an underscore are always stored as pseudoregisters, even if the norent option is used; therefore, an initialization CSECT is created.

Using COOL to Link Programs

The design of COOL requires that all input to COOL be in the form of object modules, including any automatic call libraries. COOL also accepts control statements similar to those used by the linkage editor (see COOL Control Statements). As stated, the output from COOL is an object module and becomes input to the linkage editor or loader.

COOL processes object modules in the same order and with the same restrictions as imposed by the linkage editor. However, there is no guarantee that unresolved references during autocall processing are reconciled in the same order with COOL as with the linkage editor because the linkage editor may process the corresponding compilations in any order. The only time this could cause a problem is if several members of an autocall library contain copies of the same object module, in which case the copy that is actually used is unpredictable. Proper autocall library management should prevent this situation from occurring.

Chapter Contents
Previous
Next
Top of Page