Extended Names

COOL Extended Names Processing

The external symbol that the compiler assigns for an extended name is different for each compilation in which the name appears. For example, the external symbol for the definition of the my_structure_allocate function is based on the sum of the section name hash value and the offset of the extended name in the extended function names CSECT. The external symbol for a call to the same function in another compilation uses a number between 750000 and 999999.

The COOL object code preprocessor collects all the extended names in all the object files for a load module and assigns a unique external symbol to each extended name. The COOL utility preprocesses all object files that contain extended names CSECTs.

When the extname option has been specified and COOL detects an extended names CSECT in an input object file, COOL creates a table of external symbols and associated external names. COOL selects a unique external symbol for each extended name after all of the input files have been processed and then uses this external symbol to replace the compiler-assigned external symbol in the object code. Extended names processing is the default. Specify noextname to suppress extended names processing.

This paragraph gives an example of the way COOL assigns external symbols. In the object file for compilation A, the compiler uses the external symbol @@750078 to refer to Instance_Number . In the object file for compilation B, the compiler uses @@750012 to refer to the same name. While processing the two object files, COOL selects a third external symbol, @@750341, to represent Instance_Number and replaces all instances of @@750078 in compilation A and all instances of @@750012 in compilation B with this selection. The linkage editor can then link the load module correctly because the preprocessed object code contains a unique eight-character monocase external symbol for each extended name.

Note: If the ability to autocall a function with an extended name is a requirement and you cannot store the object code in an AR370 archive, you can use the #pragma map directive to map the symbol to an eight-character name. (See The AR370 Archive Utility.) [cautionend]

COOL Selection of External Symbols

COOL selects external symbols differently, depending on the type of extended name. For all extended names other than function names, COOL assigns external symbols by starting with @@750000 and incrementing by 1 for each new name. COOL changes all of the external symbols for all extended names, other than function names, that were assigned during compilation. There can be no more than 250,000 extended external identifiers in a load module.

For extended function names, COOL attempts to use the external symbol that the compiler assigns to the function definition. Because this symbol has been stored in the function prolog, all references to the function can use the same symbol. In the unlikely event that the compiler has assigned the same external symbol to more than one function, COOL selects the next higher unassigned value as the external symbol.

This paragraph gives an example of the way in which COOL assigns external symbols in this instance. The compiler has assigned @@189676 as the external symbol for both function_A in compilation A and funct ion_B in compilation B. COOL assigns a new external symbol for the second of these two functions that it finds in the object code. If it has not already been used, COOL assigns the next higher symbol, @@189677, to the second function.

User Exit Selection of External Symbols

COOL can call a user exit to create the external symbols instead of creating them itself. The exit supplies the numerical part of the external symbol in the form of an integer. The exit may choose the numbers using any algorithm, although it is assumed that in most cases it will reference a database of extended names. This functionality may be useful if the same external symbol is to be assigned to the same extended name in multiple load modules.

ENEXIT and ENEXITDATA options

The exit is enabled by one of two options. The first option is the enexit option. This option causes COOL to invoke the exit. The second is the enexitdata option. This option causes COOL to invoke the exit and pass one to eight characters of user-specified data. In TSO and OS/390 batch, this option has the following form:

enexitdata(userdata)

Under UNIX System Services (USS), the option is specified as follows:

-Aenexitdata=userdata

Under CMS, the option is specified as follows:

enexitdata userdata

The data are intended to give the exit a way to identify the object files that COOL is processing. For example, the userdata could be a load module name.

If either option is used, COOL tries to dynamically load a module named CLKEXIT. In TSO or OS/390 batch, this module must be located in STEPLIB, a task library, or the system link list. Under CMS, the module must be a member of a LOADLIB named DYNAMC LOADLIB. If the load module cannot be loaded, COOL terminates with an error message.

The exit is called once for each unique extended name in the COOL input files. The exit must return a valid value for every extended name. It is not possible for the exit to elect to return values for a proper subset of the extended names.

The exit itself takes the form of a dynamically loadable function having the prototype shown here:

int _dynamn(char UserData[8],
            const char *ExtendedName, int ExtendedNameLength,
            int FunctionFlag, int OldId, unsigned *NewId);

UserData is a pointer to an eight-byte array containing the one to eight characters of user data specified by the enexitdata option. Unused characters in the array are set to blanks. The exit can change the values in the UserData array. COOL always passes a pointer to the same array, so any changes made during a call to the exit are carried over to the next call. ExtendedName is a pointer to the extended (long) name. ExtendedNameLength is the length (1 to 65,535) of the extended name. FunctionFlag is set to a non-zero value if the name is an extended function name and is 0 otherwise. If FunctionFlag is nonzero, then OldId contains the integer part of the compiler-assigned external symbol. If FunctionFlag is 0, then the value in OldId has no meaning. NewId is a pointer to an unsigned int , into which the exit should store the integer part of the external symbol to be assigned by COOL. The value stored in

NewId must be between 0 and 999999 inclusive. If the exit returns a value that is not in this range, COOL terminates. The return code values are as follows:

0 indicates normal return. The exit supplied a value for NewId .

4 if returned on the first call to the exit, indicates that CLINK should continue normal extended names processing and not call the exit again.

Any other return code causes COOL to terminate immediately.

The exit runs as a function called from COOL; therefore, if the exit cannot continue execution, it can call the exit or abort functions. The exit can issue diagnostic messages by writing to STDERR. The exit should not write to STDOUT or any other file that may write to the DDname SYSPRINT because this may interfere with COOL's use of this DDname.

Chapter Contents
Previous
Next
Top of Page

0	indicates normal return. The exit supplied a value for `NewId` .
4	if returned on the first call to the exit, indicates that CLINK should continue normal extended names processing and not call the exit again.