HP OpenVMS Systems Documentation

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 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:

$ 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.

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 2.2.3.1, Section 2.2.3.2, and Section 2.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 2-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
MY_SYMBOL

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.

2.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 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 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 2.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 2.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 2.2.2).

2.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 2.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.

2.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 2.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]

If you are developing portable applications using the Compaq Network Application Support (NAS) products, a second image library, similar to IMAGELIB, is used. The second image library contains components that conform to NAS conventions rather than to OpenVMS conventions. By default, the linker will not search this library because it may contain symbols that do not conform to the OpenVMS global symbol naming rules.

If you want the linker to include the open image library in its processing, define the logical name LNK$OPEN_LIB with any nonnull string value. If the LNK$OPEN_LIB logical is defined at link time, the linker searches OPEN_LIB in the same way it searches IMAGELIB. The open image library search is in addition to any other searches, and it is done after user libraries are searched and before other system libraries are searched, as follows:

1. User libraries, if defined with LNK$LIBRARY_nnn
2. OPEN_LIB, if LNK$OPEN_LIB logical is defined
3. IMAGELIB, unless /NOSYSSHR is specified
4. STARLET, unless /NOSYSLIB is specified

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.2.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.2.1.)

$ LINK MY_MAIN, SYS$INPUT/OPT
MY_MATH/SHAREABLE/SELECTIVE_SEARCH
[Ctrl/Z]
%LINK-W-NUDFSYMS, 1 undefined symbol:
%LINK-I-UDFSYM,         MYSUB
%LINK-W-USEUNDEF, undefined symbol MYADD referenced
        in psect $CODE offset %X00000011
        in module MY_MAIN file WORK:[PROGRAMS]MY_MAIN.OBJ;6

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 example 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 OpenVMS Command Definition, Librarian, and Message Utilities Manual.)

$ LIBRARY/CREATE/INSERT MYMATH_LIB MY_MATH/SELECTIVE_SEARCH

For many link operations, the order in which the input files are specified in the LINK command is not important. However, in complex link operations that specify many library files or process input files selectively, to ensure that the linker resolves all the symbolic references among the input files as you intend, you may need to be aware of the order in which the linker processes the input files. To control the order in which the linker processes input files, you must understand how the linker parses the command line.

2.3.1 Understanding Cluster Creation

As it parses the command line, the linker groups the input files you specify into clusters and places these clusters on a cluster list. A cluster is an internal linker construct that determines image section creation. The position of an input file in a cluster and the position of that cluster on the linker's cluster list determine the order in which the linker processes the input files you specify.

The linker always creates at least one cluster, called the default cluster. The linker may create additional clusters, called named clusters, depending on the types of input files you specify and the linker options you specify. If it creates additional clusters, the linker places them on the cluster list ahead of the default cluster, in the order in which it encounters them in the options file. The default cluster appears at the end of the cluster list. (Within the default cluster, input files appear in the same order in which they are specified on the LINK command line.)

Clusters for shareable images specified in shareable image libraries appear after the default cluster on the cluster list because they are created later in linker processing, when the linker knows which shareable images in the library are needed for the link operation.

The linker groups input files into clusters according to file type. Table 2-2 lists the types of input files accepted by the linker and describes how the linker processes them when creating clusters.

The following example illustrates how the linker puts the various types of input files in clusters. To see which clusters the linker creates for this link operation, look at the Image Section Synopsis section of the image map file. Figure 2-3 illustrates the clusters created for this link operation.

$ DEFINE LNK$LIBRARY  SYS$DISK:[]MY_DEFAULT_LIB.OLB
$ LINK  MY_MAIN.OBJ, MY_LIB.OLB/LIBRARY, SYS$INPUT/OPT
CLUSTER=MY_CLUS,,,MY_PROG.OBJ
MY_SHARE.EXE/SHAREABLE
MY_SHARE_LIB.OLB/LIBRARY
MY_TAB.STB

Figure 2-3 Clusters Created for Sample Link

The linker processes input files in cluster order: processing each input file starting with the first file in the first cluster, then the second, and so on, until it has processed all files in the first cluster. Then it does the same for the second cluster, and the next, and so on, until it has processed all files in all clusters.