|
HP OpenVMS Systems Documentation |
|
HP OpenVMS Linker Utility Manual
4.2.3 Deleting Universal Symbols Without Disturbing Upward CompatibilityTo 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 still work, but the symbol is not 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 4.
For I64 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 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. The alias mechanism can also be used to map case sensitive symbols to case insensitive ones. With C and C++, case sensitivity becomes more important. You may want to create a shareable image that contains both symbols, so that object modules from traditional programming languages as MACRO and FORTRAN can link against your image as well as modules which compile from open sources and usually expect case sensitive names. In the following link operation for Example 4-2, for each routine or data, uppercase and lowercase symbols are defined with the alias mechanism, which are written into the GST.
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.
On I64, 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 loads the executable and read-only
segments of resident images into physical memory, with virtual
addresses in system space. Data or code of such images is directly
accessed from memory. That is, at run time image pages do not need to
be read from the image file. See INSTALL utility for more information
about installing images as resident images.
User-written system services allow user-mode programs to call routines that can perform functions that require privileges. These services are implemented in shareable images. Because of the privileged code, these images are also referred to as privileged shareable images. For security reasons, the privileged code and associated data must be protected from manipulations. Therefore, such images are also called protected shareable images. As you would create any other shareable image, create a privileged shareable image by specifying the /SHAREABLE qualifier in the LINK command. However, because the privileged routine entry points in privileged shareable images must be routed through the OpenVMS system service dispatcher in order to change mode to a more privileged mode, declaring these entry points as universal requires additional steps:
Chapter 5
|
| Qualifier | Description |
|---|---|
| /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 the default map sections. |
| /FULL |
When used in combination with the /MAP qualifier, directs the linker to
create a map file that contains extensive information of the image in
the map file. To tailor the full information to your needs, you can use
keywords to add or suppress specific information. The default value for
/FULL is SECTION_DETAILS.
|
| /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 I64 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.
| Section Name | Description | Default Map | Full Map |
Brief Map |
|---|---|---|---|---|
| Object and Image Synopsis+ | Lists all the object modules included in the image and the shareable images referenced in the order they are processed by the linker. | Yes | Yes | Yes |
| Cluster Synopsis | Lists all the clusters created by the linker | -- | Yes | -- |
| Image Segment Synopsis | Lists the image segments that were created | -- | Yes | -- |
| COMDAT Group Synopsis | Lists the processed groups ordered by group name | -- | Keyword GROUP_SECTIONS | -- |
| Program Section Synopsis+ | Lists the sections and their attributes. | 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. | Yes /CROSS | Yes /CROSS | -- |
| Symbols By Value | Lists all the symbols with their values in hexadecimal representation. | -- | Yes | -- |
| Cross Reference Footnotes | If the cross reference or the symbol value lists contain shortened name, this section is automatically created and the full names are listed. | YEs | Yes | -- |
| Mangled/Demangled Symbols | Lists all the mangled symbols with their demangled (source code) names. | -- | Keyword DEMANGLED_SYMBOLS | -- |
| 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. Quota usage keeps track of quotas being used by the I64 linker and may suggest which quota should be increased to improve performance. | Yes | Yes | Yes |
The following sections describe each of the image map sections.
5.2.1 Object and Image Synopsis
The first section that appears in a map file is the Object and Image
Synopsis, which lists the name of each object or shareable image
included in the link operation in the order in which they were
processed. This section of the map file also includes other information
about each module, arranged in columns. Example 5-1 shows the Object
and Image Synopsis map.
This section corresponds to the Alpha section titled Object Module Synopsis. To compare with the linker map on Alpha, see Section 9.2.1.
| Example 5-1 Object and Image Synopsis |
|---|
+---------------------------+
! Object and Image Synopsis !
+---------------------------+
(1) (2) (3) (4) (5) (6)
Module/Image File Ident Attributes Bytes Creation Date Creator
------------ ---- ----- ---------------- ----- ------------- -------
GETJPI V1.0 Lkg Dnrm 280 7-NOV-2006 15:50 HP C V7.2-002
DISK$USER:[JOE]GETJPI.OBJ;1
DECC$SHR V8.3-00 Lkg 0 27-OCT-2006 10:57 Linker T02-28
SYS$COMMON:[SYSLIB]DECC$SHR.EXE;1
SYS$PUBLIC_VECTORS X-3 Sel Lkg 0 27-OCT-2006 10:56 Linker T02-28
SYS$COMMON:[SYSLIB]SYS$PUBLIC_VECTORS.EXE;1
Key for Attributes
+------------------------------------------+
! Sel - Module was selectively searched !
! Lkg - Contains call linkage information !
! Dnrm - Denormal IEEE FP model !
+------------------------------------------+
|
The items in the following list correspond to the numbered items in the preceding figure:
Module/Image File Ident Attributes
------------ ---- ----- ----------------
NONE V1.0 Lkg
DISK1:[JOE]NONE.OBJ;1
NOFLOAT_CASE Lkg RFP
DISK1:[JOE]NOFLOAT.OBJ;1
DNORM_CASE Lkg Dnrm
DISK1:[JOE]DENORM_W.OBJ;1
FAST_CASE Lkg Fast
DISK1:[JOE]FAST_W.OBJ;1
NEPCT_CASE Lkg Inex
DISK1:[JOE]INEXACT_W.OBJ;1
SPCL_CASE Lkg Spcl
DISK1:[JOE]SPECIAL_W.OBJ;1
UNDER_CASE Lkg Undr
DISK1:[JOE]UNDERFLOW_W.OBJ;1
DG_FL_CASE Lkg VXfl
DISK1:[JOE]VAXFLOAT_W.OBJ;1
DECC$SHR V8.2-00 Lkg
RESD$:[SYSLIB]DECC$SHR.EXE;1
SYS$PUBLIC_VECTORS X-2 Sel Lkg
RESD$:[SYSLIB]SYS$PUBLIC_VECTORS.EXE;1
Key for Attributes
+------------------------------------------+
! Sel - Module was selectively searched !
! Lkg - Contains call linkage information !
! RFP - Conforms to the reduced FP model !
! VXfl - VAX Float FP model !
! Dnrm - Denormal IEEE FP model !
! Fast - Fast IEEE FP model !
! Inex - Inexact IEEE FP model !
! Undr - Underflow-to-zero IEEE FP model !
! Spcl - Special FP model !
+------------------------------------------+
|
| Previous | Next | Contents | Index |