HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS Linker Utility Manual

Previous Contents Index

4.2.3 Deleting Universal Symbols Without Disturbing 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 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.

4.2.4 Creating Run-Time Kits

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.

4.2.5 Specifying an Alias Name for a Universal Symbol

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.

4.3 Improving the Performance of Installed Shareable Images

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.

4.4 Linking User-Written System Services

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:

  • Protect the privileged shareable image from user-mode or supervisor-mode write access--- Create a protected shareable image by specifying the /PROTECT qualifier. If you need to protect only certain segments in a privileged shareable image, use the PROTECT= option. For more information about this option, see Part 4.
  • Create a Privileged Library Vector (PLV) and put it in a protected section--- Create a PLV for a privileged shareable image. The image activator uses the information in the PLV to set up the change of mode code. You can create a protected shareable image by specifying the /PROTECT qualifier. For information about creating a PLV, see the HP OpenVMS Programming Concepts Manual.


On I64, HP recommends that you protect the entire image, rather than parts of the image (that is, individual image segments). Partial protection requires that you verify that all data to be protected is in the protected segment. Compilers for I64 put data in different types of sections. By doing so, it becomes difficult to control protection setting. For example, compilers put some data into short data sections. The linker then must collect these sections into short data segments, which cannot be collected into user-defined clusters (the only clusters that you can protect with the linker option). That is, for partially protected images, you need control over that location that the compiler puts all your data. The compiler of your choice might not offer a reliable method to do so; therefore; HP recommends protecting the entire image.

Chapter 5
Interpreting an Image Map File (I64)

This chapter describes how to interpret information in an image map created by the linker on OpenVMS I64 systems. It describes the combinations of linker qualifiers used to produce a map.

For information about interpreting an image map file on Alpha and VAX systems, see Chapter 9.

5.1 Overview of I64 Linker Map

At your request, the linker can generate information that describes the contents of the image and the linking process. This information, called an image map, can be helpful when determing programming and 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 segments that comprise the image
  • The names, sizes, and locations of 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 a 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
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.
  • DEMANGLED_SYMBOLS---Directs the OpenVMS I64 Linker to add a translation table of mangled and demangled (source code) names. You can request this section if you use a programming language, whose language processor performs name mangling (for example Ada and C++) and the compiler provides the necessary information within the object modules. The table contains names of global definitions, procedures and data. Please note, /DNI (to process display name information) must be be present, which is by default. See Section 5.4 for more information.
  • GROUP_SECTIONS---Directs the OpenVMS I64 Linker to list all processed groups (ELF COMDATs). For example C++ includes groups in its object modules and shareable images. Please note when linking against C++ shareable images, all groups of these images will be listed; even for short programs this will create a long list.
  • [NO]SECTION_DETAILS---Directs whether or not the OpenVMS I64 Linker suppresses zero length contributions in the Program Section Synopsis.
  • ALL---For the OpenVMS I64 Linker, the ALL keyword is equivalent to specifying all of the above listed keywords.
/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.

Table 5-2 I64 Image Map Sections
Section Name Description Default Map Full
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

+In a full map file, these sections include information about modules that were included in the link operation from libraries but were not explicitly specified on the LINK command line.

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
DECC$SHR                        V8.3-00            Lkg                   0  27-OCT-2006 10:57  Linker T02-28
SYS$PUBLIC_VECTORS              X-3            Sel Lkg                   0  27-OCT-2006 10:56  Linker T02-28

                 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:

  1. Module/Image. The name of each object module or shareable image included in the link operation. The modules/images are listed in the order in which the linker processed them. (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.) If the linker encounters an error during its processing of an object module or shareable image, an error message appears on the line directly following the line containing the name of that module or image.
    This column corresponds to the Module Name column on the Alpha linker map.
  2. File. Full file specification of the input file, including device and directory. The specification is printed on a separate line. It starts at the File column and continues across the other columns. If the specification is longer than 111 characters, it is shortened by dropping the device portion of the file specification or both the device and directory portions of the file specification.
  3. Attributes. The attributes displays four subcolumns of module attributes. An explanation of the abbreviations used appears in the Key for Attributes legend that appears at the end of the Object and Image Synopsis section:
    The first of the four subcolumns indicates whether the symbol search of the module was selective. If the symbol search was selective, the abbreviation Sel appears. If the symbol search of the module was not selective, this subcolumn is left blank.
    The second subcolumn indicates whether the module has call linkage information. If the module has call linkage information, Lkg appears. If the module does not have call linkage information, this subcolumn is left blank.
    The third subcolumn indicates whether the module was compiled with the Reduced Floating Point model. If it was, the abbreviation RFP appears. If the module was not compiled with the Reduced Floating Point model, this subcolumn is left blank. This designation is suppressed for shareable images.
    The fourth subcolumn indicates the whole program Floating Point mode for the module. Several abbreviations can appear in this column. For example Dnrm , the denormal IEEE FP model.
    The following example lists all of the possible abbreviations for this subcolumn in the Keys for Attributes legend. The Bytes, Creation Date and Creator columns are omitted from this example; refer to the preceding map example for the entire Object and Image Synopsis.

    Module/Image      File           Ident               Attributes
    ------------      ----           -----            ----------------
    NONE                              V1.0                 Lkg
    NOFLOAT_CASE                                           Lkg RFP
    DNORM_CASE                                             Lkg     Dnrm
    FAST_CASE                                              Lkg     Fast
    NEPCT_CASE                                             Lkg     Inex
    SPCL_CASE                                              Lkg     Spcl
    UNDER_CASE                                             Lkg     Undr
    DG_FL_CASE                                             Lkg     VXfl
    DECC$SHR                          V8.2-00              Lkg
    SYS$PUBLIC_VECTORS                X-2              Sel Lkg
                     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                  !
  4. Bytes. The number of bytes the object module contributes to the image. Because shareable images do not contribute to the image the value 0 (zero) appears in this column.
  5. Creation Date. The date and time the module or image was created.
  6. Creator. Identification of the language processor or other utility that created the module or image.

Previous Next Contents Index