HP OpenVMS Linker Utility Manual
/VAX (Alpha and VAX)
Directs the linker to produce an OpenVMS VAX image. The default action,
when neither /ALPHA nor /VAX is specified, is to create an OpenVMS VAX
image on an OpenVMS VAX system and to create an OpenVMS Alpha image on
an OpenVMS Alpha system.
This qualifier is used to instruct the linker to accept OpenVMS VAX
object, image and library files to produce an OpenVMS VAX image.
You must inform the linker where OpenVMS VAX system libraries and
shareable images are located. On an OpenVMS VAX system, you use the
logical name SYS$LIBRARY to do this. On an OpenVMS Alpha system, you
use the logical name VAX$LIBRARY to do this. Therefore, if the link is
to occur on an OpenVMS Alpha system, you must define the logical
VAX$LIBRARY so that it translates to the location of an OpenVMS VAX
system disk residing on the system where the VAX linking is to occur.
For more information on cross-architecture linking, see Section 1.5.
$ DEFINE VAX$LIBRARY DKB200:[VMS$COMMON.SYSLIB]
$ LINK/VAX VAX.OBJ
This example, performed on an OpenVMS Alpha system, shows the
definition of the logical name VAX$LIBRARY to point to an OpenVMS VAX
system disk mounted on device DKB200 in the appropriate area. The
qualifier tells the linker to expect the object file, VAX.OBJ, to be an
OpenVMS VAX object file and to link it using the OpenVMS VAX libraries
and images on DKB200, if necessary.
This section describes the linker options that you can specify in a
linker options file. For information about creating and using linker
options files, see Chapter 1.
You can express numeric parameters in decimal (%D), hexadecimal (%X),
or octal (%O) radix by prefixing the number with the corresponding
radix operator. If no radix operator is specified, the linker assumes
The default and maximum numeric values in this manual are expressed in
decimal numbers, as are the values in any linker messages relating to
See reference description. (VAX only)
Platform specific (Alpha and VAX),
see reference description.
See reference description.
See reference description.
Approximately 96 (Alpha and VAX)
Name of the image
UNIVERSALS (I64 and Alpha)
None. (I64 and Alpha)
None. (VAX only)
BASE= (VAX Only)
For VAX linking, specifies the base address (starting address) that you
want the linker to assign to the image.
The address at which you want the image based. You can express the
number in decimal (%D), octal (%O), or hexadecimal (%X) notation. If
the address specified is not divisible by 512, the linker automatically
adjusts it upward to the next multiple of 512, that is, to the next
highest page boundary. Do not attempt to base an image linked with a
larger page size (specified using the /BPAGE qualifier).
The linker bases shareable images at address 0, by default, and bases
system images at address %X80000000, by default.
The BASE= option is illegal in a link operation that produces a system
image. To specify a base address for a system image, use the /SYSTEM
The BASE= option is not supported for I64 and Alpha linking. On I64,
you cannot create any based image. On Alpha, however, you can create a
based executable image but you cannot create a based shareable
On Alpha, you can set the base address for an executable image by
specifying the base address argument to the
CLUSTER=cluster-name,base-address option. On I64, the base
address argument must be omitted in a CLUSTER= option.
In general, the use of based images is not recommended. The image
activator, a component of the OpenVMS operating system, cannot relocate
a based image in the virtual address space, which can result in
conflicts in the address space: when two or more based images overlap.
It can also result in fragmentation of the used virtual address space.
The linker processes the BASE= option by assigning the specified base
address to the default cluster. If the linker creates additional
clusters before it searches the default libraries, which it does if a
CLUSTER= or COLLECT= option is specified or if a shareable image is
explicitly specified, the following effects may occur:
- If the additional clusters are based (that is, if the CLUSTER=
option specifies a base address or if the shareable image is a based
shareable image), the linker must check that memory requirements for
each based cluster do not conflict. Memory requirements conflict when
more than one cluster requires the same section of address space. If
they do conflict, the linker issues an error message and aborts the
linking operation. If they do not conflict, the linker allocates each
cluster the memory space it requests.
- If the additional clusters are not based, there will be no
conflicting memory requirements. However, the linker will place each
additional cluster at an address higher than that of the default
cluster (because the base address of the default cluster must be the
base address of the entire image). Consequently, the location of
clusters (relative to each other) in the image will differ from what
you would expect based on the position of each cluster in the cluster
list. (Remember that the additional clusters precede the default
cluster on the cluster list and that the linker typically allocates
memory for clusters beginning at the first cluster on the cluster list,
then the second, and so on.) For more information about the linker's
clustering algorithm, see Chapter 6. For more information about the
linker's memory allocation algorithm, see Chapter 7.
Directs the linker to preserve the mixture of uppercase and lowercase
characters used in character string arguments to linker options.
Enables case sensitivity. You can use any mixture of uppercase and
lowercase characters when specifying the keyword YES.
Disables case sensitivity. Note that you must use only uppercase
characters when specifying the keyword NO because case sensitivity is
enabled and the linker does not accept mixed case in keywords.
Once case sensitivity has been enabled, the linker preserves the case
of all succeeding character string arguments to linker options until
you explicitly disable it. When the CASE_SENSITIVE= option is disabled
(which is the default), the linker changes all the characters in a
character string to uppercase before processing the string.
Note that the CASE_SENSITIVE= option only affects how the linker
processes arguments to linker options. When it searches object files
and shareable image files for symbols that need to be resolved, the
linker preserves the case used in the symbol names (created by the
language compilers). Also, the names of the linker options (all the
characters preceding the equal sign, as in the NAME= option) are
unaffected by the case-sensitivity option. The linker changes all the
characters in option names to uppercase characters before processing
the option, even if case sensitivity has been enabled.
Carefully delimit the section of a linker options file in which you use
case sensitivity to avoid unintentional side effects. For example, if
you include options in the case sensitive region that accept keyword
arguments, such as YES, NO, EXE, and SHR, make sure the keywords are
specified using uppercase characters. Because these keywords appear
after the equal sign, they are affected by case sensitivity. Similarly,
character string arguments used to name a program section, cluster, or
image are also affected by case sensitivity.
Symbol names issued by compilers are uppercased by default. But you can
use compiler switches to preserve mixed-case source code names. Be
aware that this may result in mixed-case module or program section
names as well. For example, if you have a library include statement and
the module names in the library are mixed-case, then set
. to operate on mixed-case names in the options file,
The following excerpt from an options file illustrates how the linker
changes or preserves the syntactical elements of an option line. The
example contains mixed-case names that you want to preserve by setting
the linker to case-sensitive mode:
When processed by the linker, the text appears as follows:
The case of all names to the right of the first equal sign in each
option remains the same.
HP recommends that you switch to case sensitivity only when needed.
$ LINK/SHAREABLE/MAP/FULL TEST,SYS$INPUT/OPTIONS
In the example, the CASE_SENSITIVE= option with the value YES enables
case sensitivity in the linker options file. Because case sensitivity
has been enabled, the linker preserves the mix of uppercase and
lowercase characters used in character string arguments to all
succeeding linker options. In the example, this includes the character
string ImageName passed to the NAME= option and the character string
OneSymbol passed to the SYMBOL= option.
Specifying the CASE_SENSITIVE= option with the value NO turns off case
sensitivity. Note that you must use uppercase characters when
specifying the keyword NO. Because case sensitivity has been disabled,
the linker changes all the characters in the universal symbol myroutine
to uppercase. The following excerpt from the map file produced by this
link illustrates how these identifiers were stored by the linker:
Directs the linker to create a cluster. (The linker groups input files
into clusters before processing their contents.)
The name you want assigned to the cluster.
The base virtual address for the cluster. If you omit the base-address
value, you must still enter the comma.
On I64 systems, the base address must be omitted.
For Alpha linking, it is illegal to specify a base address for a
cluster when creating a shareable image.
pfc (page fault cluster)
The number of pagelets read into memory by the operating system when
the initial page fault occurs for a page in the cluster. If you do not
specify the pfc parameter, the operating system uses
the default value established by the system parameter PFCDEFAULT. If
you omit the page fault cluster value, you must still enter the comma.
The file you want the linker to place in the cluster. Note that you
should not specify in the LINK command itself any file that you specify
with the CLUSTER= option (unless you want to include two copies of the
file in the final image).
You can use the CLUSTER= option in the following ways:
- To control the order in which the linker processes input files
- To cause specified modules to be placed close together in virtual
If you do not specify the CLUSTER= option, the linker always creates at
least one cluster, called the default cluster. For more information
about how the linker creates clusters, see Chapter 2 (I64) and
Chapter 6 (Alpha and VAX).
You can also create a cluster by specifying the COLLECT= option
$ LINK MY_PROG,SYS$INPUT/OPTIONS CLUSTER=MY_CLUSTER,,,PROG2,PROG3
In this example, the linker creates a cluster, named MY_CLUSTER, that
contains the input files named PROG2.OBJ and PROG3.OBJ.
Directs the linker to place the specified program section (or program
sections) into the specified cluster.
Name of the cluster.
Name of the program sections (psects) you want placed in the cluster.
For I64 and Alpha linking, directs the linker to mark the cluster
'cluster-name' with the indicated qualifier keyword value. Attributes
set by this qualifier are only evaluated by the loader. This qualifier
is used to build OpenVMS drivers. See Writing OpenVMS Alpha Device Drivers in C for guidelines for
using this qualifier.
Marks the cluster 'cluster-name' as RESIDENT so that the segment (I64)
or image section (Alpha) created from that cluster has the RESIDENT
flag set. This will cause the loader to map the segment or image
section into non-paged memory.
Marks the cluster 'cluster-name' as INITIALIZATION_CODE so that the
segment (I64) or image section (Alpha) created from that cluster has
the INITALCOD flag set. The initialization code will be executed by the
loader. This keyword is specifically intended for use with program
sections from modules SYS$DOINIT and SYS$DRIVER_INIT in STARLET.OLB.
If the specified cluster does not already exist, the linker creates the
cluster when it processes the COLLECT= option.
The linker sets the global (GBL) attribute for all the program sections
specified, if they do not already have this attribute set. Program
sections exported from a shareable image referenced in the options file
with the /SHAREABLE qualifier cannot be specified in the COLLECT=
$ LINK MY_PROG,SYS$INPUT/OPTIONS
In the example, the linker creates the cluster named MY_CLUSTER, if it
does not already exist, and puts the program sections named PSECT2 and
PSECT3 in the cluster.
DZRO_MIN= (Alpha and VAX)
On Alpha and VAX systems, specifies the minimum number of contiguous,
uninitialized pages that the linker must find in an image section
before it can extract the pages from the image section and place them
in a newly created demand-zero image section. By creating demand-zero
image sections (image sections that do not contain initialized data),
the linker can reduce the size of images.
Specifies the minimum number of contiguous pages.
For VAX linking, the linker, by default, uses a minimum of 5 pages.
Each VAX page equals 512 bytes.
For Alpha linking, the linker, by default, uses a minimum of 1 page.
The size of an Alpha page is CPU-specific. The initial set of Alpha
systems uses an 8 KB page. The page size used is that of the current
link operation. (See the /BPAGE qualifier.)
The number of pages must be equal to or greater than the value
specified in the parameter.
A demand-zero image section contains uninitialized, writable pages,
which do not occupy physical space in the image file on disk, but
which, when accessed during program execution, are allocated memory and
initialized with binary zeros by the operating system. (For more
information about demand-zero compression on Alpha and VAX, see
When specifying a value for this option, be aware that a low value
(less than the default value) increases the likelihood that the linker
will encounter the required number of contiguous, uninitialized pages
and thus may increase the number of demand-zero image sections the
linker creates for the image (depending on the contents of the object
modules). While this can reduce the size of the image file on disk, it
can also decrease the image's paging performance during execution.
Conversely, a value higher than the default value decreases the
likelihood that the linker will encounter the required number of
contiguous, uninitialized pages; decreases the number of demand-zero
image sections the linker creates; and may increase the size of the
image file on disk but provide better paging performance during
The linker stops creating demand-zero image sections when the total
number of image sections in the image reaches the value specified by
the ISD_MAX= option or the default value. (For more information, see
the description of the ISD_MAX= option.)
The DZRO_MIN= option is illegal in a link operation that produces a
$ LINK MY_PROG,SYS$INPUT/OPTIONS
In this example, the value of the DZRO_MIN= is set to 15.
Sets match control parameters for a shareable image and specifies the
match algorithm. This option allows you to control whether executable
images that link with a shareable image must be relinked each time the
shareable image is updated and relinked.
Identifies the match algorithm used by the image activator. Specify one
of the following keywords:
Directs the image activator to allow the image to map to the referenced
shareable image when one condition is met:
- the major and minor ID for the shareable image, as saved at link
time in the image file, are equal to the IDs found in the actual
shareable image file at activation time.
Directs the image activator to allow the image to map to the referenced
shareable image when two conditions are met:
- the major ID for the shareable image, as saved at link time in the
image file, is equal to the major ID found in the actual shareable
image file at activation time
- the minor ID for the shareable image, as saved at link time in the
image file, is less than or equal to the minor ID found in the actual
shareable image file at activation time.
Directs the image activator to unconditionally allow the image to map
to the referenced shareable image:
Specifies the major identification number.
Specifies the minor identification number.
When a shareable image is created without specifying a GSMATCH= option,
the linker by default creates one. It sets the EQUAL match control and
uses portions of the image creation time, as a binary value, for the
major and minor IDs. In general this is sufficient to set a unique
value for the IDs each time the shareable image is linked. On I64, the
linker uses bits 40 through 54 of the binary time value for the major
ID and bits 8 through 39 for the minor ID. On Alpha and VAX, the linker
uses bits 32 through 46 of the binary time value for the major ID and
bits 16 through 31 for the minor ID.
The GSMATCH= option causes a major identification parameter (major-id),
a minor identification parameter (minor-id), and a match control
keyword to be stored in the shareable image file. The control keyword
together with the IDs is called the GSMATCH information.
When an image is linked with a shareable image, together with the
reference to the shareable image its GSMATCH information is saved in
the image file.
When the image is run, the image activator encounters the reference to
the shareable image. At this time, the image activator compares the
GSMATCH information as saved in the image with the GSMATCH information
retrieved from the actual shareable image. The implementation details
on I64 and Alpha are slightly different, the mechanism and its effects
are the same.
The following information describes the GSMATCH mechanism for an
executable image linked against a shareable image. "Executable" is used
to clearly differentiate between the referencing image and the
referenced image, the shareable image. However, in general any image,
executable or shareable, can be linked against a shareable image and
the described mechanism applies.
- On I64, the GSMATCH= option causes a major identification
parameter (major-id), a minor identification parameter (minor-id), and
a match control keyword to be stored in the dynamic segment of the
shareable image. It is the DT_VMS_IDENT field which holds this
When an executable image is linked with a shareable image, the dynamic
segment of the executable image contains the name of the shareable
image. This information is saved in the field DT_NEEDED. The name is
accompanied by the GSMATCH information of the shareable image, taken at
link time. This information is saved in the field DT_VMS_NEEDED_IDENT.
When the executable image is run and the image activator begins
processing the dynamic segment of the executable image, the image
activator encounters the name of the shareable image. At that time, the
image activator looks up the shareable image file based on this name,
either as a logical name, pointing to a file, or as a filename in the
directory SYS$LIBRARY. If an image file was found, the image activator
continues to process the GSMATCH information.
- On Alpha and VAX, the GSMATCH= option causes a major
identification parameter (major-id), a minor identification parameter
(minor-id), and a match control keyword to be stored in the image
header of the shareable image.
When an executable image is linked with a shareable image, the image
header of the executable image contains an image section descriptor
(ISD) for the shareable image (as well as an ISD for each image section
in the image). The ISD for the shareable image contains a major ID,
minor ID, and match control keyword, which the linker copies from the
shareable image at link time.
When the executable image is run and
the image activator begins processing the ISDs in the image header of
the executable image, the image activator encounters the ISD for the
shareable image. As such, the image activator looks up the shareable
image file based on its name, either as a logical name, pointing to a
file, or as a filename in the directory SYS$LIBRARY. If an image file
was found, the image activator compares the image section name in the
ISD to the image section name in the image header of the current
shareable image file. If the image section names do not match, the
image activator does not allow the executable image to map to the
shareable image, regardless of the GSMATCH parameters. If the image
section names match, the image activator continues to process the
- To process the GSMATCH information, the image activator compares
the major ID parameters. If they do not match, the image activator does
not allow the executable image to map to the shareable image unless
GSMATCH=ALWAYS has been specified.
If the major ID parameters
match, the image activator compares the minor ID parameters. If the
relation between the minor ID parameters does not satisfy the relation
specified by the match control keyword, the image activator does not
allow the executable image to map to the shareable image. Then the
image activator issues an error message stating that the executable
image must be relinked.
The match control keyword must be the same in both the shareable
and executable image files. If it is different, then the more
restrictive match is used. For example, if a shareable image is linked
with ALWAYS, and an executable image contains EQUAL (from an earlier
version of the shareable image), then the test at activation time will
Thus, to create an upwardly compatible shareable image, increment only
the value of the minor ID and leave unchanged the value of the major
ID. If the match control keyword is LEQUAL, the executable image that
links against it will run. (If the major ID is changed, executable
images can never map to the shareable image unless ALWAYS is
specified.) By using this convention, you can ensure that executable
images that linked with an older version of the shareable image can map
to the newer version.