HP OpenVMS Linker Utility Manual
Previous Contents Index

6.2 Input File Processing for Symbol Resolution

The linker can include object modules, shareable images, and libraries in its symbol resolution processing. For VAX images, the linker can also include a symbol table file in its symbol resolution processing. (Options files, in which linker options and input files are specified, are not included in symbol resolution.)

By default, when the linker processes an object module or shareable image, it includes all the symbol definitions from the object module or shareable image in its processing. However, if you append the /SELECTIVE_SEARCH qualifier to the object module or shareable image file specification, the linker includes in its processing only those symbols from the object module or shareable image that define symbols referenced in a previously processed input file. (For more information about selectively processing input files, see Section 6.2.4.)

Table 6-1 summarizes how the linker processes these different types of input files when performing symbol resolution. The following sections provide more detail on the linker's processing of each type of input file.

Table 6-1 Linker Input File Processing
Input File How Processed
Object file (.OBJ) By default, the linker processes all the symbol definitions and references listed in the GSD of the module. If you append the /SELECTIVE_SEARCH qualifier to the input file specification, the linker includes in its processing only those symbol definitions from the GSD that resolve symbolic references found in previously processed input files.
Shareable image file (.EXE) By default, the linker processes all symbol definitions and references listed in the GST of the image. Note, however, to avoid cluttering the map file of the resultant image, the linker lists only those symbol definitions in the map file that are referenced by other modules.

If you append the /SELECTIVE_SEARCH qualifier to the input file specification, the linker includes in its processing only those symbol definitions from the GST that resolve symbolic references found in previously processed input files.

+Symbol table file (.STB) By default, the linker processes all the symbol definitions and references in the GSD of the module. If you append the /SELECTIVE_SEARCH qualifier to the input file specification, the linker includes in its processing only those symbol definitions from the module that resolve symbolic references found in previously processed input files.
Library files (.OLB) The linker searches the name table of the library for symbols that are undefined in previously processed input files. (A library file's name table lists all the symbols available in all of the modules it contains.) If the linker finds the definition of a symbol referenced by a previously processed input file, it includes in the link operation the module in the library that contains the definition of the symbol. Once the object module or shareable image is included in the link operation, the linker processes it as any other object module or shareable image.

If you append the /INCLUDE qualifier to a library file specification, the linker does not search the library's name table to find undefined symbolic references. Instead, the linker simply includes the specified object module or shareable image specified as a parameter to the /INCLUDE qualifier.

You cannot process a library file selectively. However, if the Librarian utility's /SELECTIVE_SEARCH qualifier was specified when the object module or shareable image was inserted into the library, the linker will process the module selectively when it extracts it from the library.

+VAX specific

6.2.1 Processing Object Modules

The way the linker processes object modules to resolve symbolic references illustrates how the linker processes most other input files. (Symbol table files are object modules. The GST of a shareable image, which the linker processes in symbol resolution, is also created as an object module appended to the shareable image.)

For example, the program in Example 6-1 references the symbol mysub.

Example 6-1 Module Containing a Symbolic Reference: my_main.c 

#include <stdio.h> 
 
int mysub(); 
 
main() 
{ 
   int num1, num2, result; 
 
   num1   = 5; 
   num2   = 6; 
   result = 0; 
 
   result = mysub( num1, num2 ); 
   printf("Result is: %d\n", result); 
}

Mysub, which Example 6-1 references, is defined in the program in Example 6-2.

Example 6-2 Module Containing a Symbol Definition: my_math.c 

int myadd(int value_1,int value_2) { 
   int result; 
 
   result = value_1 + value_2; 
   return( result); 
} 
 
int mysub(int value_1,int value_2) 
   int result; 
 
   result = value_1 - value_2; 
   return( result); 
} 
 
int mymul(int value_1,int value_2) 
   int result; 
 
   result = value_1 * value_2; 
   return( result); 
} 
 
int mydiv(int value_1,int value_2) 
   int result; 
 
   result = value_1 / value_2; 
   return( result); 
}

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. The example is from the analysis of an OpenVMS Alpha object module. Differences between the format of the symbol reference between VAX object files and Alpha object files are highlighted in the list following the example. 


4.  GLOBAL SYMBOL DIRECTORY (EOBJ$C_GSD) (1), 344 bytes 
               .
               .
               .
        9)  Global Symbol Specification (EGSD$C_SYM) (2)
                data type: DSC$K_DTYPE_Z (0) 
                symbol flags: 
                        (0)  EGSY$V_WEAK      0 
                        (1)  EGSY$V_DEF       0 
                        (2)  EGSY$V_UNI       0 
                        (3)  EGSY$V_REL       0 
                        (4)  EGSY$V_COMM      0 
                        (5)  EGSY$V_VECEP     0 (3)
                        (6)  EGSY$V_NORM      0 (4)
                symbol: "MYSUB"

  1. For VAX object files, the symbol for the global symbol directory is OBJ$C_GSD.
  2. For VAX object files, the symbol for a global symbol specification is GSD$C_SYM.
  3. For VAX object files, this field is not included.
  4. For VAX object files, this field is not included. For Alpha object files, the value of this field is always zero for symbolic references.

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 Alpha object module (performed using the ANALYZE/OBJECT utility) shows the format of a GSD symbol definition entry. Note that, in an OpenVMS Alpha object module, a symbol definition is listed as a Global Symbol Specification. 


4.  GLOBAL SYMBOL DIRECTORY (EOBJ$C_GSD), 46 bytes 
        .
        .
        .
        9)  Global Symbol Specification (EGSD$C_SYM) 
                data type: DSC$K_DTYPE_Z (0) 
                symbol flags: 
                        (0)  EGSY$V_WEAK      0 
                        (1)  EGSY$V_DEF       1 
                        (2)  EGSY$V_UNI       0 
                        (3)  EGSY$V_REL       1 
                        (4)  EGSY$V_COMM      0 
                        (5)  EGSY$V_VECEP     0 
                        (6)  EGSY$V_NORM      1 (1)
           (2)   psect: 3 
           (3)   value: 64 (%X'00000040') 
           (4)   code address psect: 5 
           (5)   code address: 8 (%X'00000008') 
                symbol: "MYSUB" 
         .
         .
         .

  1. The value of the EGSY$V_NORM flag is 1 if the symbol represents a procedure. The value is set to zero if the symbol represents data.
  2. The index of the program section that contains the procedure descriptor for mysub.
  3. The location of the procedure descriptor expressed as the offset from the starting address of the program section that contains the procedure descriptor.
  4. Index of program section that contains the code entry point.
  5. The location of the code entry point, expressed as the offset from the starting address of the program section that contains the entry point.

The following excerpt from an analysis of the OpenVMS VAX object module (performed using the ANALYZE/OBJECT utility) shows the format of a GSD symbol definition entry. Note that, on VAX systems, a symbol definition is listed as an Entry Point Symbol and Mask Definition record. 


4.  GLOBAL SYMBOL DIRECTORY (OBJ$C_GSD), 46 bytes 
        .
        .
        .
        2)  Entry Point Symbol and Mask Definition (GSD$C_EPM) 
                data type: DSC$K_DTYPE_Z (0) 
                symbol flags: 
                        (0)  GSY$V_WEAK       0 
                        (1)  GSY$V_DEF        1 
                        (2)  GSY$V_UNI        0 
                        (3)  GSY$V_REL        1 
                        (4)  GSY$V_COMM       0 
                psect: 0 
                value: 0 (%X'0000000C') 
                entry mask: <> 
                symbol: "MYSUB" 
        .
        .
        .

The value of the symbol is expressed as an offset into a program section.

When you link the modules shown in Example 6-1 and Example 6-2 together to create an image, you specify both object modules on the command line, as in the following example: 


$ LINK MY_MAIN, MY_MATH

When the linker processes these object modules, it reads the contents of the GSDs, obtaining the value of the symbol from the symbol definition.

Note that, for Alpha images, in the map file associated with the image, the value of the symbol mysub is the location within the image of the procedure descriptor for the routine. The procedure descriptor contains the address of the routine within the image.

For VAX images, the value of the symbol mysub is represented in the map file as the location of the entry point mask.

6.2.2 Processing Shareable Images

When the linker processes a shareable image specified as input in a link operation, it processes all the symbol definitions and references in the GST of the image. The GST contains all the universal symbols defined in the shareable image. Because the linker creates the GST of a shareable image in the format of an object module, the processing of shareable images for symbol resolution is similar to the processing of object modules. Note that the linker includes in the map file only those symbols that resolve references to avoid cluttering the listing with extraneous symbols.

For example, the program in Example 6-2 (in Section 6.2.1) can be implemented as a shareable image. (For information about creating a shareable image, see Chapter 8.) The shareable image can be included in the link operation as in the following example: 


$ LINK/MAP/FULL   MY_MAIN, SYS$INPUT/OPT 
MY_MATH/SHAREABLE

The GST created by the linker for the shareable image MY_MATH.EXE contains the 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 Alpha images, the universal symbol mysub in the shareable image MY_MATH.EXE appears in the GST of the image as a Universal Symbol Specification record, as illustrated in the following example: 


SHAREABLE IMAGE - GLOBAL SYMBOL TABLE 
            .
            .
            .
4.  GLOBAL SYMBOL DIRECTORY (EOBJ$C_EGSD), 200 bytes 
            .
            .
            .
        3) Universal Symbol Specification (EGSD$C_SYMG) 
                data type: DSC$K_DTYPE_Z (0) 
                symbol flags: 
                        (0)  EGSY$V_WEAK      0 
                        (1)  EGSY$V_DEF       1 
                        (2)  EGSY$V_UNI       1 
                        (3)  EGSY$V_REL       1 
                        (4)  EGSY$V_COMM      0 
                        (5)  EGSY$V_VECEP     0 
                        (6)  EGSY$V_NORM      1 
                psect: 0 
                value: 16 (%X'00000010') 
                symbol vector entry (procedure) 
                        %X'00000000 00010008' 
                        %X'00000000 00000040' 
                symbol: "MYSUB" 
            .
            .
            .

Note that the value of the symbol, as it appears in the Universal Symbol Specification, is the location of the symbol's entry in the image's symbol vector, expressed as an offset from the base of the symbol vector. The symbol vector entry contains the address of mysub's entry point and the address of its procedure descriptor. These locations are expressed as offsets from the base of the image. The entry for a symbol in the GST of an image is a duplicate of the symbol's entry in the symbol vector.

For VAX images, the universal symbol mysub in the shareable image MY_MATH.EXE appears in the GST of the image as an Entry Point Symbol and Mask Definition record, as illustrated in the following example: 


SHAREABLE IMAGE - GLOBAL SYMBOL TABLE 
            .
            .
            .
        2)  Entry Point Symbol and Mask Definition (GSD$C_EPM) 
                data type: DSC$K_DTYPE_Z (0) 
                symbol flags: 
                        (0)  GSY$V_WEAK       0 
                        (1)  GSY$V_DEF        1 
                        (2)  GSY$V_UNI        1 
                        (3)  GSY$V_REL        1 
                        (4)  GSY$V_COMM       0 
                psect: 0 
                value: 8 (%X'00000008') 
                entry mask: <> 
                symbol: "MYSUB" 
            .
            .
            .

Note that the flag GSY$V_UNI is set for universal symbols to distinguish them from global symbols in object modules that use the same record format.

Implicit Processing of Shareable Images

For VAX linking, when you specify a shareable image in a link operation, the linker not only processes the shareable image you specify, but also all the shareable images that the shareable image has been linked against. (A shareable image contains a global image section descriptor [GISD] for each shareable image to which it has been linked.)

For Alpha linking, the linker does not process the shareable images that the shareable image you specify has been linked against. (Shareable images on Alpha systems still contain GISDs for each shareable image that they have been linked against, however.) If your application's build procedure depends on implicit processing of shareable images, you may need to add these shareable images to your linker options file.

6.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 6.2.3.1, Section 6.2.3.2, and Section 6.2.3.3 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 6-2 into the library, you could specify the following command: 


$ LIBRARY/CREATE/INSERT MYMATH_LIB MY_MATH

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: 


$ LIBRARY/LIST/NAMES MYMATH_LIB
Directory of OBJECT library WORK:[PROGS]MYMATH_LIB.OLB;1 on 
3-NOV-2000 11:11:33 
Creation date:  3-NOV-2000 11:08:04      Creator:  VAX-11 Librarian V04-00 
Revision date:  3-NOV-2000 11:08:04      Library format:   3.0 
Number of modules:      1                Max. key length:  31 
Other entries:          5                Preallocated index blocks:     49 
Recoverable deleted blocks:      0       Total index blocks used:        2 
Max. Number history records:      20     Library history records:        0 
 
Module MY_MATH 
MYADD                            MYDIV 
MYMUL                            MYSUB

You can specify the library in the link operation using the following command: 


$ LINK/MAP/FULL   MY_MATH, MYMATH_LIB/LIBRARY

The map file produced by the link operation verifies that the object module MY_MATH.OBJ was included in the link operation.

6.2.3.1 Identifying Library Files Using the /LIBRARY Qualifier

When the linker processes a library file identified by the /LIBRARY qualifier, the linker processes the library's name table, looking for the definitions of symbols referenced in previously processed input files.

Note that, to resolve a reference to a symbol defined in a library, the linker must process the module that references the symbol before processing the library file. Thus, while the ordering of object modules and shareable images is not usually important in a link operation, the ordering of library files can be important. (For more information about controlling the order in which the linker processes input files, see Section 6.3.)

Once the object module or shareable image is included from the library into the link operation, the linker processes all the symbol definitions and references in the 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 6.2.4.

Processing Object Module Libraries

When the linker finds a symbol in the name table of an object module library, it extracts from the library the object module that contains the definition and includes it in the link operation. The linker then processes the GSD of the object module extracted from the library, adding an entry to the linker's list of symbol definitions for every symbol defined in the object module, and adding entries to the linker's undefined symbol list for all the symbols referenced by the module (as described in Section 6.2.1). The linker continues to process the undefined symbol list until there are no definitions in the library for any outstanding references. When the linker finishes processing the library, it has extracted all the modules that resolve references generated by modules previously extracted from the library.

Processing Shareable Image Libraries

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.

For VAX linking, 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 SYS$LIBRARY.

For Alpha linking, 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 ALPHA$LIBRARY.

Once it locates the shareable image, the linker processes the shareable image as it does any other shareable image (as described in Section 6.2.2).

6.2.3.2 Including Specific Modules from a Library Using the /INCLUDE Qualifier

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 the modules from the library specified in the /INCLUDE qualifier and processes them 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 6.2.3.1. In addition, the linker also 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.

6.2.3.3 Processing Default Libraries

In addition to the libraries you specify using the /LIBRARY qualifier or the /INCLUDE qualifier, the linker also processes certain other libraries by default. The linker processes these default libraries in the following order:

  1. Default user library files. You specify a default user library by associating the library with one of the linker's default logical names from the range LNK$LIBRARY, LNK$LIBRARY_1,... LNK$LIBRARY_999. If the /NOUSERLIBRARY qualifier is specified, the linker skips processing default user libraries. (For more information about defining a default user library, see the description of the /USERLIBRARY qualifier in Part 2.)
    If the default user library contains shareable images, the linker looks for the shareable image as described in Section 6.2.3.1.
  2. Default system shareable image library file. The linker processes the default system shareable image library IMAGELIB.OLB by default unless you specify the /NOSYSSHR or the /NOSYSLIB qualifier.
    Note that when the linker needs to include a shareable image from IMAGELIB.OLB in a link operation, it always looks for the shareable images in SYS$LIBRARY for VAX linking or ALPHA$LIBRARY for Alpha linking. The linker does not look for the shareable image in the device and directory of IMAGELIB.OLB as it does for other shareable image libraries.
  3. Default system object module library file. The linker processes the default system object library STARLET.OLB by default unless you specify the /NOSYSLIB qualifier.
    For Alpha linking, when the linker processes STARLET.OLB by default, it also processes the shareable image (SYS$PUBLIC_VECTORS.EXE). This shareable image is needed to resolve references to system services. (For VAX linking, references to system services are resolved by linking against the file SYS$P1_VECTOR, which resides in STARLET.OLB.)
    When STARLET is not processed by default (for example, when the /NOSYSLIB qualifier is specified), the linker does not process SYS$PUBLIC_VECTORS.EXE automatically, even if you explicitly specify STARLET.OLB in an options file.
    If you specify SYS$PUBLIC_VECTORS.EXE explicitly in an options file when it is already being processed by default, the linker displays the following warning: 


    %LINK-W-MULCLUOPT, cluster SYS$PUBLIC_VECTORS multiply defined 
        in options file [filename]

Previous Next Contents Index