|
HP OpenVMS Systems Documentation |
|
HP OpenVMS Linker Utility Manual
8.3 Declaring Universal Symbols in Alpha Shareable ImagesFor 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 8-2 as an Alpha shareable image, you must declare the universal symbols in the image by using the following LINK command:
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 8-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 8-2, control is transferred directly to the location of the procedure within the shareable image. Figure 8-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 HP 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.
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:
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 HP 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.
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.
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:
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.
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.
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.
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
HP OpenVMS Programming Concepts Manual.
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.
Chapter 9
|
| /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. |
The linker formats the information it includes in a map file into sections. Table 9-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.
| Section Name | Description | Default Map | Full Map |
Brief Map |
|---|---|---|---|---|
| Object Module Synopsis+ | 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+ | Lists the program sections and their attributes. | Yes | Yes | -- |
| Symbols By Name+ | Lists global symbol names and values. | Yes | Yes | -- |
| Symbol Cross-Reference+ | 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 8.
9.2.1 Object Module Synopsis (Alpha/VAX)
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 3-NOV-2000 12:27 Linker T10-37
MY_MAIN V1.0 553 WORK:[PROGS]MY_MAIN.OBJ;15 3-NOV-2000 12:27 COMPAQ C X1.1-048E
DECC$SHR V1.0 0 [SYSLIB]DECC$SHR.EXE;2 9-JUL-2000 07:49 Linker T10-03
SYS$PUBLIC_VECTORS
X-26 0 [SYSLIB]SYS$PUBLIC_VECTORS.EXE;2 9-JUL-2000 07:34 Linker T10-03
|
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 6.
9.2.2 Module Relocatable Reference Synopsis (VAX Linking Only)
For VAX linking, the information contained in the Module Relocatable Reference Synopsis section varies with the type of image being created. For shareable images, this section lists all of the modules that contain at least one .ADDRESS directive. For executable or system images, this section lists the names of all object modules containing at least one .ADDRESS reference to a shareable image. The section lists the modules in the order in which the linker processes them, including the number of .ADDRESS references found. The linker formats the information as in the following example:
+---------------------------------------+
! Module Relocatable Reference Synopsis !
+---------------------------------------+
Module Name (1) Number (2) Module Name Number Module Name Number
----------- ------ ----------- ------ ----------- ------
MAIN1 1
|
Note that you can reduce linker and image activator processing time by removing .ADDRESS directives from input files.
| Previous | Next | Contents | Index |