HP OpenVMS Systems Documentation
HP OpenVMS Linker Utility Manual
2.2.1 Processing Object Modules
The linker resolves symbolic references with their definitions. For example, the program in Example 2-1 references the symbol mysub .
mysub , which Example 1 references, is defined in the program in Example 2-2.
The GSD created by the language processor for the object module MY_MAIN.OBJ lists the reference to the symbol mysub . Because object modules cannot be examined using a text editor, the following representation of the GSD is taken from the output of the ANALYZE/OBJECT utility of the OpenVMS I64 object module MY_MAIN.OBJ.
The GSD created by the language processor for the object module MY_MATH.OBJ contains the definition of the symbol mysub , as well as the other symbols defined in the module. The definition of the symbol includes the value of the symbol.
The following excerpt from an analysis of the OpenVMS I64 object module (performed using the ANALYZE/OBJECT utility) shows the format of a GSD symbol definition entry.
When the linker processes these object modules, it reads the contents of the GSDs, obtaining the value of the symbol from the symbol definition.
For I64 images, the value of a symbol that is a function can be expressed in two ways:
The function descriptor created by the linker is a pair of quadwords that contain the Global Pointer (GP) for the image and the pointer to the entry point of the function. Note that on I64, the linker creates the function descriptors rather than the compiler. The linker also chooses the value for the GP, which is an address that the code segment uses to access the short data segment. It accesses different parts of the short data segment by using different offsets to the value the linker has chosen for the GP.
If the symbol is data, it can be either relocatable or not relocatable.
The linker uses the R prefix or suffix in the map to indicate
When the linker processes a shareable image, it processes all the universal symbol definitions in the GST of the image. Because the linker creates the GST of a shareable image in the same format as an object module's symbol table, the processing of shareable images for symbol resolution is similar to the processing of object modules. The linker sets an attribute that flags the symbol as protected, which also indicates a universal symbol when the linker creates an image. Note that the linker includes only those universal symbols in the map file that resolve references, thus eliminating extraneous symbols in the linker map.
For example, the program in Example 2-2 (in Section 2.2.1) can be implemented as a shareable image. (For information about creating a shareable image, see Chapter 4.) The shareable image can be included in the link operation as in the following example:
The GST created by the linker for the shareable image MY_MATH.EXE contains the universal definition of the symbol MYSUB , as well as the other symbols defined in the module.
Because images cannot be examined using a text editor, the following representations of the GST are taken from the output of the ANALYZE/IMAGE utility:
For I64 images, STV_PROTECTED indicates a universal definition. The "Symbol Type, STT_FUNC, indicates that this symbol represents a function (or procedure). The Function Type, VMS_SFT_SYMV_IDX, indicates that the symbol value (in this case 1) is the index into the symbol vector of the pointer to the function descriptor for MYSUB .
The analysis also lists all the indexes in the symbol vector. The following Index, which matches the previous value for the symbol, is 1. The entry in the symbol vector with the index value of 1, contains the value 30080, which is the address of a function descriptor for MYSUB . The function descriptor is a quadword pair. The first quadword is the address of the entry point for MYSUB (10020). The address 10020 is in a segment that has the execute flag set (that is, a code segment). The second quadword contains the global pointer chosen by the linker for the image (230000).
188.8.131.52 Implicit Processing of Shareable Images
For VAX linking, when you specify a shareable image in a link operation, the linker not only resolves symbols from the shareable image you specify but it also resolves symbols from all shareable images that the shareable image has been linked against (that is, the shareable image's dependency list).
The I64 linker performs like the Alpha linker in that it does not automatically scan down a shareable image's dependency list to resolve symbols. Instead, on I64 an image's dependency list is in the dynamic segment. It appears in an analysis near the top of the file under the title Shareable Image List, as in the following example analysis of MY_MAIN.EXE:
2.2.3 Processing Library Files
Libraries specified as input files in link operations contain either object modules or shareable images. The way in which the linker processes library files depends on how you specify the library in the link operation. Section 184.108.40.206, Section 220.127.116.11, and Section 18.104.22.168 describe these differences. Note, however, that once an object module or shareable image is included from the library into the link operation, the linker processes the file as it would any other object module or shareable image.
For example, to create a library and insert the object module version of the program in Example 2-2 into the library, you could specify the following command:
The librarian includes the module in its module list and all of the global symbols defined in the module in its name table. To view the library's module list and name table, specify the LIBRARY command with the /LIST and /NAMES qualifiers, as in the following example:
You can specify the library in the link operation using the following command:
The map file produced by the link operation verifies that the object
module MY_MATH.OBJ was included in the link operation.
When the linker processes a library file identified by the /LIBRARY qualifier, the linker processes the library's name table and looks for the definitions of symbols referenced in previously processed input files.
Note that in order to resolve a reference to a symbol defined in a library, the linker must first process the module that references the symbol before it processes the library file. As such, while the order of object modules and shareable images is not usually important in a link operation, how you order library files can be important. (For more information about controlling the order in which the linker processes input files, see Section 2.3.)
Once the object module or shareable image is included from the library into the link operation, the linker processes all the symbol definitions in a shareable image, and symbol definitions and references in an object module. If you want the linker to selectively process object modules or shareable images that are included in the link operation from a library, you must append the Librarian utility's /SELECTIVE_SEARCH qualifier to the file specification of the object module or shareable image when you insert it into the library. Appending the linker's /SELECTIVE_SEARCH qualifier to a library file specification in a link operation is illegal. For more information about processing input files selectively, see Section 2.2.4.
When the linker finds a symbol in the name table of an object module library, it:
When the linker finishes processing the library, it will have extracted all the modules that resolve references generated by modules that were previously extracted from the library.
When the linker finds a symbol in the name table of a shareable image library, it notes which shareable image contains the symbol and then looks for the shareable image to include it in the link operation. By default, the linker looks for the shareable image in the same device and directory as the library file
If the linker cannot find the shareable image in the device and directory of the library file, the linker looks for the shareable image in the directory pointed to by the logical name IA64$LIBRARY.
Once the linker locates the shareable image, it processes the shareable
image as it does any other shareable image (see Section 2.2.2).
If the library file is specified with the /INCLUDE qualifier, the linker does not process the library's name table. Instead, the linker includes in the link operation modules from the library specified with the /INCLUDE qualifier and processes these modules as it would any other object module or shareable image.
If you append both the /LIBRARY qualifier and the /INCLUDE qualifier to
a library file specification, the linker processes the library's name
table to search for modules that contain needed definitions. When the
linker finds an object module or shareable image in the library that
contains a needed definition, it processes it as described in
Section 22.214.171.124. In addition, the linker includes the modules specified
with the /INCLUDE qualifier in the link operation and processes them as
it would any other object module or shareable image.
In addition to the libraries you specify using the /LIBRARY qualifier or the /INCLUDE qualifier, the linker processes certain other libraries by default. The linker processes these default libraries in the following order:
2.2.4 Processing Input Files Selectively
By default, the linker processes all the symbol definitions and references in an object module or a shareable image specified as input in a link operation. However, if you append the /SELECTIVE_SEARCH qualifier to an input file specification, the linker processes from the input file only those symbol definitions that resolve references in previously processed input files.
Processing input files selectively can reduce the amount of time a link operation takes and can conserve the linker's use of virtual memory. Note, however, that selective processing can also introduce dependencies on the ordering of input files in the LINK command.
For example, in the link operation in Section 2.2.2, the linker processes the shareable image MY_MATH.EXE before it processes the object module MY_MAIN.OBJ because of the way in which the linker clusters input files. (For information about how the linker clusters input files, see Section 2.3.1.) When it processes the shareable image, the linker includes on its list of symbol definitions all the symbols defined in the shareable image. When it processes the object module MY_MAIN.OBJ and encounters the reference to the symbol mysub , the linker has the definition to resolve the reference.
If you append the /SELECTIVE_SEARCH qualifier to the shareable image file specification and all of the other input files are specified on the command line, the link will fail. In the following example, because the linker has no symbols on its undefined symbol list when it processes the shareable image file MY_MATH.EXE, it does not include any symbol definitions from the shareable image in its processing. When it subsequently processes the object module MY_MAIN.OBJ that references the symbol mysub , the linker cannot resolve the reference to the symbol. (For information about how to correct this link operation, see Section 2.3.1.)
To process object modules or shareable images in a library selectively, you must specify the /SELECTIVE_SEARCH qualifier when you insert the module in the library. The following command creates the library MYMATH_LIB.OLB and inserts the file MY_MATH.OBJ into the library. (For more information about using the Librarian utility, see the HP OpenVMS Command Definition, Librarian, and Message Utilities Manual.)