Updated: 11 December 1998

OpenVMS Linker Utility Manual

For VAX linking, you include a transfer vector in a link operation as you would any other object module. However, to ensure upward compatibility, you must make sure that the transfer vector always appears in the same location in the image. The best way to accomplish this is to make the transfer vector always appear at the beginning of the image by forcing the linker to process it first. If you put the transfer vector file in a named cluster, using the CLUSTER= option, and specify it as the first option in an options file that can generate a cluster, the transfer vector will appear at the beginning of the file. (For more information about controlling cluster creation, see Section 2.3.)

The following example illustrates how to include the transfer vector in the link operation, using the CLUSTER= option, so that the linker processes it first:

$ LINK/SHAREABLE MY_MATH, SYS$INPUT/OPT (1) GSMATCH=lequal,1,1000 (2) CLUSTER=trans_vec_clus,,,MY_MATH_TRANS_VEC.OBJ [Ctrl/Z]

1. To enable images that linked against a shareable image to run with various versions of the shareable image, you must specify the identification numbers of the image. By default, the linker assigns a unique identification number to each version of a shareable image. At run time, if the ID of the shareable image as it is listed in the executable image does not match the ID of the shareable image the image activator finds to activate, the activation will abort. For information about using the GSMATCH= option to specify ID numbers, see the description of the GSMATCH= option in Part 2.
2. This CLUSTER= option causes the linker to create the named cluster TRANS_VEC_CLUS and to put the transfer vector file in this cluster.

For VAX linking, you can create a based shareable image by specifying the BASE= option in a linker options file. In a based image, you specify the starting address at which you want the linker to begin allocating memory for the image. For more information about the BASE= option, see Part 2.

Digital does not recommend using based shareable images.

Based shareable Alpha images are not supported.

4.3 Declaring Universal Symbols in Alpha Shareable Images

For Alpha linking, you declare universal symbols by listing them in a SYMBOL_VECTOR= option. For each symbol listed in the SYMBOL_VECTOR= option, the linker creates an entry in the shareable image's symbol vector and creates an entry for the symbol in the shareable image's global symbol table (GST). When the shareable image is included in a subsequent link operation, the linker processes the symbols listed in its GST.

To implement Example 4-2 as an Alpha shareable image, you must declare the universal symbols in the image by using the following LINK command:

$ LINK/SHAREABLE MY_MATH, SYS$INPUT/OPT GSMATCH=lequal,1,1000 SYMBOL_VECTOR=(myadd=PROCEDURE,- mysub=PROCEDURE,- mymul=PROCEDURE,- mydiv=PROCEDURE,- my_symbol=DATA,- my_data=PSECT) [Ctrl/Z]

You must identify the type of symbol vector entry you want to create by specifying a keyword. The linker allows you to create symbol vector entries for procedures, data (relocatable or constant), and for global data implemented as an overlaid program section.

A symbol vector entry is a pair of quadwords that contains information about the symbol. The contents of these quadwords depends on what the symbol represents. If the symbol represents a procedure, the symbol vector entry contains the address of the procedure entry point and the address of the procedure descriptor. If the symbol represents a data location, the symbol vector entry contains the address of the data location. If the symbol represents a data constant, the symbol vector entry contains the actual value of the constant.

When you create the shareable image (by linking it specifying the /SHARE qualifier), the value of a universal symbol listed in the GST is the offset of its entry into the symbol vector (expressed as the offset z in Figure 4-2).

When you include this shareable image in a subsequent link operation, the linker puts this value in the linkage pair in the linkage section of the executable image that references the symbol. (A linkage pair is a data structure defined by the OpenVMS calling standard.)

At run time, when the image activator loads the shareable image into memory, it calculates the actual locations of the routines and relocatable data within the image and stores these values in the symbol vector. The image activator then fixes up the references to these symbols in the executable image that references symbols in the shareable image, moving the values from the symbol vector in the shareable image into the linkage section in the executable image. When the executable image makes the call to the procedure, shown as the Jump-to-Subroutine (JSR) instruction sequence in Figure 4-2, control is transferred directly to the location of the procedure within the shareable image.

Figure 4-2 Accessing Universal Symbols Specified Using the SYMBOL_VECTOR = Option

Note that, unlike VAX linking, global symbols implemented as overlaid program sections are not universal by default. Instead, you control which of these symbols is a universal symbol by including it in the SYMBOL_VECTOR= option, specifying the PSECT keyword. The example declares the program section my_data as a universal symbol.

You must specify the qualifier /EXTERN_MODEL=COMMON on the compile command line to make the DEC C for OpenVMS Alpha compiler implement the symbol as an overlaid program section. If you do not specify the COMMON keyword, the default keyword is RELAXED_REFDEF.

4.3.1 Symbol Definitions Point to Shareable Image Psects (Alpha Linking Only)

On Alpha systems, the linker cannot overlay program sections that are referenced by symbol definitions with shareable image program sections of the same name. The C compiler generates symbol definition records that contain the index of an overlaid program section when the relaxed ref-def extern model is used (the default).

Shareable image program sections are created when you link a shareable image and use the PSECT keyword in your SYMBOL_VECTOR option.

If the linker detects this condition, it issues the following error:

%LINK-E-SHRSYMFND, shareable image psect <name> was pointed to by a symbol definition %LINK-E-NOIMGFIL, image file not created

The link continues, but no image is created. To work around this restriction, change the symbol vector keyword to DATA, or recompile your C program with the qualifier /EXTERN=COMMON.

For more information, see the DEC C for OpenVMS Alpha documentation.)

The name of a symbol implemented as an overlaid program section can duplicate the name of a symbol representing a procedure or data location. If the program section specified in a SYMBOL_VECTOR= option does not exist, the linker issues a warning, places zeros in the symbol vector entry, and does not create an entry for the program section in the image's GST.

4.3.2 Creating Upwardly Compatible Shareable Images (Alpha Linking Only)

The SYMBOL_VECTOR= option allows you to create upwardly compatible shareable images without requiring you to create transfer vectors as for VAX images.

However, as with transfer vectors, to ensure upward compatibility when using a SYMBOL_VECTOR= option, you must preserve the order and placement of the entries in the symbol vector with each relinking. Do not delete existing entries. Add new entries only at the end of the list. If you use multiple SYMBOL_VECTOR= option statements in a single options file to declare the universal symbols, you must also maintain the order of the SYMBOL_VECTOR= option statements in the options file. If you specify SYMBOL_VECTOR= options in separate options files, make sure the linker always processes the options files in the same order. (The linker creates only one symbol vector for an image.)

Note, however, that there is no need to anchor the symbol vector at a particular location in memory, as you would anchor a transfer vector for a VAX link. The value at link time of a universal symbol in an Alpha shareable image is its location in the symbol vector, expressed as an offset from the base of the symbol vector, and the location of the symbol vector is stored in the image header. (For VAX linking, the value of a universal symbol at link time is the location of the symbol in the image, expressed as an offset from the base of the image.) Thus, the relative position of the symbol vector within the image does not affect upward compatibility.

4.3.3 Deleting Universal Symbols Without Disturbing Upward Compatibility (Alpha Linking Only)

To delete a universal symbol without disturbing the upward compatibility of an image, use the PRIVATE_PROCEDURE or PRIVATE_DATA keywords. In the following example, the symbol mysub is deleted using the PRIVATE_PROCEDURE keyword:

$ LINK/SHAREABLE MY_MATH, SYS$INPUT/OPT GSMATCH=lequal,1,1000 SYMBOL_VECTOR=(myadd=PROCEDURE,- mysub=PRIVATE_PROCEDURE,- mymul=PROCEDURE,- mydiv=PROCEDURE,- my_symbol=DATA,- my_data=PSECT) [Ctrl/z]

When you specify the PRIVATE_PROCEDURE or PRIVATE_DATA keyword in the SYMBOL_VECTOR= option, the linker creates symbol vector entries for the symbols but does not create an entry for the symbol in the GST of the image. The symbol still exists in the symbol vector and none of the other symbol vector entries have been disturbed. Images that were linked with previous versions of the shareable image that reference the symbol will still work, but the symbol will not be available for new images to link against.

Using the PRIVATE_PROCEDURE keyword, you can replace an entry for an obsolete procedure with a private entry for a procedure that returns a message that explains the status of the procedure.

4.3.4 Creating Run-Time Kits (Alpha Linking Only)

If you use shareable images in your application, you may want to ship a run-time kit with versions of these shareable images that cannot be used in link operations.

To do this, you must first link your application, declaring the universal symbols in the shareable images using the SYMBOL_VECTOR= option so that references to these symbols can be resolved. After the application is linked, you must then relink the shareable images so that they have fully populated symbol vectors but empty global symbol tables (GSTs). The fully populated symbol vectors allow your application to continue to use the shareable images at run time. The empty GSTs prevent other images from linking against your application.

To create this type of shareable image for a run-time kit (without having to disturb the SYMBOL_VECTOR= option statements in your application's options files), relink the shareable image after development is completed, specifying the /NOGST qualifier on the LINK command line. When you specify the /NOGST qualifier, the linker builds a complete symbol vector, containing the symbols you declared universal in the SYMBOL_VECTOR= option, but does not create entries for the symbols that you declared universal in the GST of the shareable image. For more information about the /GST qualifier, see Part 2.

4.3.5 Specifying an Alias Name for a Universal Symbol (Alpha Linking Only)

For Alpha linking, a universal symbol can have a name, called a universal alias, different from the name contributed by the object module in which it is defined. You specify the universal alias name when you declare the global symbol as a universal symbol using the SYMBOL_VECTOR= option. The universal alias name precedes the internal name of the global symbol, separated by a slash (/). In the following example, the global symbol mysub is declared as a universal symbol under the name sub_alias.

$ LINK/SHAREABLE MY_SHARE/SYS$INPUT/OPT SYMBOL_VECTOR=(myadd=procedure,- sub_alias/mysub=procedure,- mymul=procedure,- mydiv=procedure,- my_symbol=DATA,- my_data=PSECT) [Ctrl/Z]

You can specify universal alias names for symbols that represent procedures or data; you cannot declare a universal alias name for a symbol implemented as an overlaid program section. In link operations in which the shareable image is included, the calling modules must refer to the universal symbol by its universal alias name to enable the linker to resolve the symbolic reference.

In a privileged shareable image, calls from within the image that use the alias name result in a fix-up and subsequent vectoring through the privileged library vector (PLV), which results in a mode change. Calls from within the shareable image that use the internal name are done in the caller's mode. (Calls from external images always result in a fix-up.) For more information about creating a PLV, see the OpenVMS Programming Concepts Manual.

4.3.6 Improving the Performance of Installed Shareable Images (Alpha Linking Only)

For Alpha linking, you can improve the performance of an installed shareable image by installing it as a resident image (by using the /RESIDENT qualifier of the Install utility). INSTALL moves the executable, read-only pages of resident images into system space where they reside on huge pages. Executing your image in huge pages improves performance. See Section 1.4 for more information about installing shareable images as resident images.

This chapter describes how to interpret the information returned in an image map and describes the combinations of linker qualifiers used to obtain a map.

5.1 Overview

At your request, the linker can generate information that describes the contents of the image and the linking process itself. This information, called an image map, can be helpful when locating link-time errors, studying the layout of the image in virtual memory, and keeping track of global symbols.

You can obtain the following types of information about an image from its image map:

• The names of all modules included in the link operation, both explicitly in the LINK command and implicitly from libraries
• The names, sizes, and other information about the image sections that comprise the image
• The names, sizes, and locations of program sections within an image
• The names and values of all the global symbols referenced in the image, including the name of the module in which the symbol is defined and the names of the modules in which the symbol is referenced
• Statistical summary information about the image and the link operation itself

You determine which information the linker includes in a map file by specifying qualifiers in the LINK command line. If you specify the /MAP qualifier, the map file includes certain information by default (called the default map). You can also request a map file that contains less information about the image (called a brief map) or a map file that contains more information about the image (called a full map). Table 5-1 lists the LINK command qualifiers that affect map file production.

Table 5-1 LINK Command Map File Qualifiers

/MAP	Directs the linker to create a map file. This is the default for batch jobs. /NOMAP is the default for interactive link operations.
/BRIEF	When used in combination with the /MAP qualifier, directs the linker to create a map file that contains only a subset of all the possible information.
/FULL	When used in combination with the /MAP qualifier, directs the linker to create a map file that contains all the possible information.
/CROSS_REFERENCE	When used in combination with the /MAP qualifier, directs the linker to replace the Symbols By Name section with a Symbol Cross-Reference section, in which all the symbols in each module are listed with the modules in which they are called. You cannot request this type of listing in a brief map file.

5.2 Components of an Image Map File

The linker formats the information it includes in a map file into sections. Table 5-2 lists the sections of a map file in the order in which they appear in the file. The table also indicates whether the section appears in a brief map, full map, or default map file.

Table 5-2 Image Map Sections

Section Name	Description	Default Map	Full Map	Brief Map
Object Module Synopsis 1	Lists all the object modules in the image.	Yes	Yes	Yes
+Module Relocatable Reference Synopsis	Specifies the number of .ADDRESS directives in each module.	--	Yes	--
Image Section Synopsis	Lists all the image sections and clusters created by the linker.	--	Yes	--
Program Section Synopsis 1	Lists the program sections and their attributes.	Yes	Yes	--
Symbols By Name 1	Lists global symbol names and values.	Yes	Yes	--
Symbol Cross-Reference 1	Lists each symbol name, its value, the name of the module that defined it, and the names of the modules that refer to it. Replaces the Symbols By Name section when the /CROSS_REFERENCE qualifier is specified.	Yes	Yes	--
Symbols By Value	Lists all the symbols with their values (in hexadecimal representation).	--	Yes	--
Image Synopsis	Presents statistics and other information about the output image.	Yes	Yes	Yes
Link Run Statistics	Presents statistics about the link run that created the image.	Yes	Yes	Yes

The following sections describe each of the image map sections in detail. The examples of the map sections are taken from the map file created in a link operation of the executable image in Chapter 4.

5.2.1 Object Module Synopsis

The first section that appears in a map file is the Object Module Synopsis. This section lists the name of each module included in the link operation in the order in which it was processed. Note that shareable images included in the link operation are listed here as well. This section of the map file also includes other information about each module, arranged in columns, as in the following example:

+------------------------+ ! Object Module Synopsis ! +------------------------+ Module Name (1) Ident (2) Bytes (3) File (4) Creation Date (5) Creator (6) ----------- ----- ----- ----- ------------- ------- MY_MATH V1.0 0 WORK:[PROGS]MY_MATH.EXE;11 14-AUG-1996 12:27 Linker T10-37 MY_MAIN V1.0 553 WORK:[PROGS]MY_MAIN.OBJ;15 14-AUG-1996 12:27 DEC C X1.1-048E DECC$SHR V1.0 0 [SYSLIB]DECC$SHR.EXE;2 5-MAR-1996 07:49 Linker T10-03 SYS$PUBLIC_VECTORS X-26 0 [SYSLIB]SYS$PUBLIC_VECTORS.EXE;2 5-MAR-1996 07:34 Linker T10-03

1. Module Name. The name of each object module included in the link operation. The modules are listed in the order in which the linker processed them. If the linker encounters an error during its processing of an object module, an error message appears on the line directly following the line containing the name of that object module.
2. Ident. The text string in the IDENT field in an object module or in the image header of a shareable image.
3. Bytes. The number of bytes the object module contributes to the image. Because shareable images are activated at run time, the linker cannot calculate the size of their contributions to the image. Thus, the value 0 (zero) is associated with shareable images.
4. File. Full file specification of the input file, including device and directory. If the specification is longer than 35 characters, it is shortened by dropping the device portion of the file specification or both the device and directory portions of the file specification.
5. Creation Date. The date and time the file was created.
6. Creator. Identification of the language processor or other utility that created the file.

The order in which the modules are listed in this section reflects the order in which the linker processes the input files specified in the link operation. Note that the order of processing can be different from the order in which the files were specified in the command line. For more information about how the linker processes input files, see Chapter 2.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4548PRO_009.HTML