Updated: 11 December 1998

OpenVMS Linker Utility Manual

Directs the linker to create a full image map file. For more information, see also the /MAP, /CROSS_REFERENCE, and /BRIEF qualifiers.

Format

/MAP/FULL

Qualifier Values

None.

Description

A full map, which is the most complete image map, contains the following sections:

• Object Module Synopsis
• Module Relocatable Reference Synopsis (VAX linking only)
• Image Section Synopsis
• Program Section Synopsis
• Symbols By Name (and the Symbol Cross-Reference section if the /CROSS_REFERENCE qualifier is specified)
• Symbols By Value
• Image Synopsis
• Link Run Statistics

The full map also contains information about modules included from the default system libraries STARLET.OLB and IMAGELIB.OLB in the Object Module Synopsis, Program Section Synopsis, and Symbols By Name sections. For more information about image map files, see Chapter 5.

The /FULL qualifier is valid only if you also specify the /MAP qualifier in the LINK command. The /FULL qualifier is compatible with the /CROSS_REFERENCE qualifier, but it is not compatible with the /BRIEF qualifier.

Example

$ LINK/MAP/FULL MY_PROG
      

This example directs the linker to produce a full image map named MY_PROG.MAP.

For Alpha linking, directs the linker to include in the global symbol table (GST) of a shareable image those symbols that have been declared as universal symbols in a symbol vector.

Format

/GST (default)

/NOGST

Qualifier Values

None.

Description

By default, the linker lists in the global symbol table (GST) of a shareable image the global symbols in the image that have been declared universal. By listing these symbols in the GST, the linker allows them to be referenced in link operations where the shareable image is specified as an input file.

To create a shareable image that can be activated by the images that linked against it, but that cannot be used to resolve symbolic references in a link operation, you can specify the /NOGST qualifier. When this qualifier is specified, the linker creates the image with an empty GST. (The linker still creates a GST.) By using the /NOGST qualifier, you can create a run-time version of a shareable image without having to remove the symbol vector from the link operation.

The images that were linked against the shareable image can still access symbols within the image because the /NOGST qualifier does not affect the symbol vector in the image. A symbol vector is an array of linkage pairs that contains the address within the image of the symbols. The value of a universal symbol in the GST is the offset of its entry in the symbol vector. Thus, to the images that were linked against the shareable image, the value of the symbol is the offset of its entry into the symbol vector.

This qualifier is valid only when used with the /SHAREABLE qualifier to create a shareable image.

Example

$ LINK/NOGST/SHAREABLE MY_SHARE,UNIVERSALS/OPT
 
      

This example creates the shareable image MY_PROG.EXE without listing entries for universal symbols in its global symbol table. The image contains an empty global symbol table.

When specified with the /SYSTEM qualifier, directs the linker to include an image header in a system image.

Format

/HEADER

Qualifier Values

None.

Description

The linker always creates executable images and shareable images with headers; they are a required component of image files. The linker creates system images without a header by default. To create a system image with a header, you must specify the /HEADER qualifier along with the /SYSTEM qualifier on the command line.

The linker ignores the /HEADER qualifier if it is specified for any other type of image (executable or shareable).

Example

$ LINK/SYSTEM/HEADER MY_SYS
      

This example directs the linker to produce a system image named MY_SYS.EXE with an image header. For more information about when to specify the /HEADER qualifier with the /SYSTEM qualifier, see the description of the /SYSTEM qualifier.

Identifies the input file specification to which it is appended as a library file and directs the linker to include in the link operation the module or modules specified as the value of the qualifier.

Format

library-name/INCLUDE=(module-name[,...])

Qualifier Values

library-name

Specifies the name of the library from which you want a module or modules extracted. The file name must specify a library file. The linker assumes the default file type of .OLB.

module-name

Specifies the module or modules that you want to extract from the library. To specify more than one module, enclose the list in parentheses and separate the module names with commas.

Description

Note that the /INCLUDE qualifier does not cause the linker to process the library for the definitions of unresolved symbolic references. If you want the linker to search the library for definitions of unresolved symbols, you must also specify the /LIBRARY qualifier before the /INCLUDE qualifier.

Examples

$ LINK MY_PROG,MY_LIB/INCLUDE=(MOD1,MOD2,MOD5)
 
      

This example directs the linker to include modules MOD1, MOD2, and MOD5 from the library MY_LIB.OLB in the link operation with MY_PROG.

$ LINK MY_PROG,MY_LIB/LIBRARY/INCLUDE=(MOD1,MOD2,MOD5)
 
      

This example directs the linker to extract modules MOD1, MOD2, and MOD5 from the library MY_LIB.OLB and then to search that library for symbol definitions that are unresolved in all four modules.

Directs the linker to output informational messages produced by a link operation.

Format

/INFORMATIONALS (default)

/NOINFORMATIONALS

Qualifier Values

None.

Description

The linker outputs informational messages by default. To suppress informational messages, specify the /NOINFORMATIONALS qualifier.

Example

$ LINK/NOINFORMATIONALS MY_PROG
 
      

When the /NOINFORMATIONALS qualifier is specified, informational messages are suppressed.

Identifies the input file specification to which it is appended as a library file and directs the linker to process the library's name table as part of its symbol resolution processing. When the linker finds in the library the definition of a symbol referenced in a previously processed input file, the linker includes from the library the module in which the symbol is defined.

Format

library-name/LIBRARY

Qualifier Values

library-name

Specifies the name of the library to be included in the link operation. You must specify a library file. The linker assumes the default file type of .OLB.

Description

The order in which a library file is specified in the command string (or in an options file) is important because the linker uses the library file to resolve undefined symbols in previously processed (not subsequently processed) modules only. For more information about how the linker processes input files to resolve symbolic references, see Chapter 2.

Examples

$ LINK MY_PROG,MY_LIB/LIBRARY,PROG2,PROG3
 
      

In this example, the linker uses the library MY_LIB.OLB to resolve undefined symbols in MY_PROG, but not in PROG2 or PROG3.

$ LINK MY_PROG,PROG2,PROG3,MY_LIB/LIBRARY
 
      

In this example, the linker can resolve undefined symbols in MY_PROG, PROG2, and PROG3 from the library MY_LIB.OLB.

Directs the linker to create an image map file. For more information, see also the /BRIEF, /CROSS_REFERENCE, and /FULL qualifiers.

Format

/MAP[=file-spec] (default in batch mode)

/NOMAP (default in interactive mode)

Qualifier Values

file-spec

If you enter a file specification with the /MAP qualifier, the linker creates an image map file with that file name. If you do not enter a file type after the file name, the linker assumes a file type of .MAP.

If you do not enter a file specification with the /MAP qualifier, the linker creates an image map file with the file name of the first input file specified on the command line and the file type .MAP. (If there are no input files specified on the command line, the linker names the map file .MAP.)

If you append the /MAP qualifier to one of the input file specifications, the linker creates an image map file with the file name of the file to which the qualifier is appended, using the .MAP file type.

Description

The /MAP qualifier causes the linker to produce a default image map file containing the following sections:

• Object Module Synopsis
• Image Section Synopsis
• Program Section Synopsis
• Symbols By Name
• Link Run Statistics

See Chapter 5 for more information about image map files.

Examples

$ LINK/MAP MY_PROG
      

This example directs the linker to produce an image map with the default name of MY_PROG.MAP.

$ LINK/MAP=MY_MAP MY_PROG
      

This example directs the linker to produce an image map with the name of MY_MAP.MAP instead of the default name of MY_PROG.MAP.

For Alpha linking, prevents the linker from passing along procedure signature block (PSB) information in special fix-ups to the image activator. The image activator uses this information to build jackets so that native OpenVMS Alpha images can call translated OpenVMS VAX images. Note that this qualifier does not prevent incoming calls from translated OpenVMS VAX images.

Format

/NATIVE_ONLY (default)

/NONATIVE_ONLY

Qualifier Values

None.

Description

Jacket routines reformat data passed in procedure calls between the VAX and Alpha architectures. Jackets are required in images that make calls to translated components.

The linker does not build jackets. It stores PSB data from the compiler in the fixup section. The image activator uses this saved PSB information to build jackets, if they are needed, when the image is activated. Compilers create PSBs when you specify the /TIE qualifier. (For more information, see the OpenVMS Alpha compiler documentation.)

For more information about creating OpenVMS Alpha images that can operate with OpenVMS VAX images, see Migrating an Application from OpenVMS VAX to OpenVMS Alpha.

Example

$ LINK/NATIVE_ONLY MY_PROG
 
      

In this example, the linker creates an image, named MY_PROG.EXE, that cannot interoperate with translated OpenVMS VAX images.

Identifies the input file specification to which it is appended as a linker options file.

Format

options-file-name/OPTIONS

Qualifier Values

options-file-name

The file specification of a linker options file. The linker assumes the file type .OPT by default.

Description

A linker options file can contain linker option specifications and input file specifications. For information about creating an options file, see Chapter 1.

Examples

$ LINK MY_PROG,MY_OPTIONS/OPTIONS
 
      

This example directs the linker to use an options file named MY_OPTIONS.OPT to produce an executable image named MY_PROG.EXE.

$ LINK MY_PROG,SYS$INPUT/OPTIONS 
MY_SHARE/SHAREABLE 
[Ctrl/Z]
 
      

This example illustrates how to create an options file interactively by specifying SYS$INPUT as the file specification. After entering the options, press Ctrl/Z to end the options file.

Directs the linker to place an executable image entirely in P0 address space. When the /P0IMAGE qualifier is specified, the user stack and OpenVMS RMS buffers, which usually reside in P1 space, are placed in P0 space by the image activator.

Format

/P0IMAGE

Qualifier Values

None.

Description

Note that the address of the stack shown in the map of an image linked with the /P0IMAGE qualifier does not reflect the true address of the stack at run time because, when /P0IMAGE is specified, the virtual address space for the stack is dynamically allocated at the end of P0 space at run time.

/P0IMAGE is used to create executable images that modify P1 address space.

Example

$ LINK/P0IMAGE MY_PROG
      

This example directs the linker to set up an executable image named MY_PROG.EXE to be run entirely in the P0 address space.

Directs the linker to protect an entire shareable image from user-mode write access and supervisor-mode write access. Can be specified only with the /SHAREABLE qualifier.

Format

/PROTECT

/NOPROTECT (default)

Qualifier Values

None.

Description

The /PROTECT qualifier protects an entire shareable image from user-mode write access and supervisor-mode write access. To protect only specific image sections within a shareable image, but not the entire shareable image, use the PROTECT= option. For more information about using the PROTECT= option, see its description later in this section.

The /PROTECT qualifier is commonly used to protect shareable images that are used to implement user-written system services (called privileged shareable images) from user-mode access. If only certain clusters in the shareable image need protection, use the PROTECT= option.

The /PROTECT qualifier is incompatible with the /EXECUTABLE qualifier and the /SYSTEM qualifier.

Example

$ LINK/SHAREABLE/PROTECT MY_SHARE
      

This example directs the linker to produce a privileged shareable image named MY_SHARE.EXE.

For Alpha linking, specifies that the linker should perform certain optimizations to improve the performance of the resultant image, when instructed by the compiler.

Format

/REPLACE (default)

/NOREPLACE

Qualifier Values

None.

Description

For Alpha linking, it is more efficient to execute a procedure call as a branch, using the BSR (Branch to Subroutine) instruction sequence, than it is to execute the call as a jump, using the JSR (Jump to Subroutine) instruction sequence. In a BSR instruction, the destination can be expressed as an offset, requiring fewer memory fetches than a JSR instruction sequence.

Compilers cannot always take advantage of the efficiency of the BSR instruction because the information needed to calculate the offset is not available until link time, when the linker lays out the image sections that make up the image. To achieve this performance enhancement, compilers flag uses of the JSR instruction sequence and the linker examines each use and attempts to replace it with the BSR instruction sequence wherever possible.

In addition to code replacement, the linker can also specify hints to improve the performance of the JSR instructions that remain in the image. A hint is used to index the instruction cache and can improve performance. Hints are generated for JSR instructions within the image and for JSR instructions to shareable images.

For more information about this optimization, see Section 1.4.

For Alpha linking, directs the linker to create an image that can be installed as a resident image and to flag coding practices in the image that would prevent this.

Format

/[NO]SECTION_BINDING[=(CODE,DATA)]

/NOSECTION_BINDING (default)

Qualifier Values

CODE

Prevents the linker from replacing the Jump to Subroutine (JSR) instruction sequence with the more efficient Branch to Subroutine (BSR) instruction sequence when the target of the branch crosses an image section boundary.

DATA

Directs the linker to check for address calculations that create dependencies on the layout of data image sections. The linker reports such occurrences.

When the /SECTION_BINDING qualifier is specified without either the CODE or DATA keyword, the linker performs both types of checking by default.

Description

For Alpha linking, you can improve the performance of an installed image by installing it as a resident image (by using the /RESIDENT qualifier of the Install utility). The Install utility moves portions of resident images into system space where they reside on a large single page with granularity hints set (called a granularity hint region or GHR), thus improving performance.

For an image to be installed as a resident image, it must not contain any dependencies on the layout of image sections, such as branch instructions that cross image section boundaries. The offsets calculated by the linker for such branches depend on the layout of the image sections. The relative position of the code image sections changes when they are moved to system space and the accuracy of the offsets calculated by the linker is destroyed. (These dependencies are created by the linker when it replaces the JSR instruction sequence with the BSR instruction sequence. For more information, see the description of the /REPLACE qualifier.)

When the /SECTION_BINDING qualifier is specified, the linker does not replace JSR instructions when the destination crosses an image section boundary. The linker still replaces the JSR instruction sequence for calls that stay within the boundaries of an image section.

In addition to eliminating image section layout dependencies in code image sections, the linker can also check the data image sections in an image to see if they contain coding practices that produce dependencies on image section layout. The image activator can reposition data image sections to eliminate the gaps in virtual memory left by the code image sections that were moved to system space. However, data image sections can also contain dependencies on image section layout. For example, when an image initializes an address by performing arithmetic on two addresses that reside in two different image sections, the address calculation creates a dependency on the layout of the data image sections, as in the following example:

OWN FOO: INITIAL ( FOO - BAR)

If the linker detects the compiler adding or subtracting two intra-image addresses, it assumes that a relative branch is being calculated and displays the following warning:

%LINK-W-BINDFAIL, failed to bind reference at %X00030000 between sections at locations %X00030000 and %X00010000 in module X file WORK:[TEST]X.OBJ;6

The warning message produced by the linker indicates the two addresses being operated on and the virtual address where it was trying to write the result. To find the source code that is creating the dependency, examine the map file to determine what entities reside at these addresses and then search the source code for places where they are used in calculations. In this example, module X contained a data cell, FOO, initialized with the difference between FOO's address and BAR's (as in the previous code example). In the image map, FOO resides at %X00030000 and BAR at %X00010000. Because these addresses appear in different image sections, the calculation introduces a dependency on the layout of image sections. To fix this dependency, rewrite the source code to remove the calculation or move the two data cells into the same image section by using the COLLECT= option or the PSECT_ATTR= option.

The linker issues a message for each address calculation in data image sections that create dependencies on the layout of image sections, as in the following example:

%LINK-W-BINDISABLE, section binding of data has been disabled %LINK-W-BINDFAIL, failed to bind reference at %X0000865D between sections at locations %X00008000 and %X00000000 in module MKDRIVER file X56Y_RESD$:[DRIVER.OBJ]DRIVER.OLB;1 %LINK-W-BINDFAIL, failed to bind reference at %X00008665 between sections at locations %X00008000 and %X00000000 in module MKDRIVER file X56Y_RESD$:[DRIVER.OBJ]DRIVER.OLB;1 %LINK-W-BINDFAIL, failed to bind reference at %X0000866D between sections at locations %X00008000 and %X00000000 in module MKDRIVER file X56Y_RESD$:[DRIVER.OBJ]DRIVER.OLB;1

Example

$ LINK/SHARE/SECTION_BINDING MY_PROG
      

In this example, the linker creates the image MY_PROG.EXE and processes it so that it can be installed as a resident image.

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

4548PRO_012.HTML