 |
OpenVMS Linker Utility Manual
/FULL
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
This example directs the linker to produce a full image map named
MY_PROG.MAP.
/GST (Alpha Only)
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.
/HEADER
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.
/INCLUDE
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
| #1 |
$ 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.
| #2 |
$ 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.
/INFORMATIONALS
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.
/LIBRARY
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
| #1 |
$ 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.
| #2 |
$ 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.
/MAP
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
This example directs the linker to produce an image map with the
default name of MY_PROG.MAP.
| #2 |
$ 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.
/NATIVE_ONLY (Alpha Only)
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 Alpha1.
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.
Note
1 This manual has been archived but is
available on the OpenVMS documentation CD-ROM.
|
/OPTIONS
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
| #1 |
$ 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.
| #2 |
$ 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.
/P0IMAGE
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
This example directs the linker to set up an executable image named
MY_PROG.EXE to be run entirely in the P0 address space.
/PROTECT
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.
/REPLACE (Alpha Only)
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.
/SECTION_BINDING (Alpha Only)
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.
|
