 |
HP OpenVMS Linker Utility Manual
On Alpha and VAX, the linker uses the same GSMATCH mechanism to check
the compatibility of the information in a shareable image library and
the shareable image file. For more information, see the description of
the /LIBRARY qualifier in /LIBRARY.
On I64 and Alpha, the image activator verifies the index (I64) or
offset (Alpha) of a referenced symbol in a shareable image; the index
or offset is then confirmed if it is within the symbol vector.
This additional step makes it possible to avoid relinking of some
images. To illustrate the feature, consider a shareable image with an
exported routine MY_ADD, created with a
SYMBOL_VECTOR=(MY_ADD=PROCEDURE) option. Consider also an updated
version of the shareable image with an improved MY_ADD routine but also
with an additional routine MY_SUB. That is, a shareable image created
with a SYMBOL_VECTOR=(MY_ADD=PROCEDURE,MY_SUB=PROCEDURE) option.
The usual way to make such a change upward compatible is by changing
the minor ID in the GSMATCH= option. (This method is also the required
way on VAX.) Now consider linking your application, which only calls
MY_ADD, with the new shareable image and shipping it to a customer
site, where only the old shareable image is available. This image will
not be activated with the old shareable image because of the GSMATCH
mechanism. It does not matter that the new symbol is not referenced and
that the application - if activated - would correctly work. To resolve
this GSMATCH conflict, the appliaction image needs to be relinked with
the old shareable image at the customer site or the updated shareable
image needs to be shipped with the application.
On I64 and Alpha, this condition can be avoided. By using an unchanged
minor ID in the GSMATCH= option, the updated shareable image is
downward compatible. Again, the application image only uses the old
interface (MY_ADD, in this example). Such images, although linked
against the new shareable image, can be activated with the old
shareable image. Any application image using the additional interface
(MY_SUB, in this example) will not be activated with the old shareable
image; the check fails, the index or offset of the new symbol is not
within the symbol vector of the old shareable image. The image
activation aborts with the secondary message -LOADER-E-BADSVINDX (I64)
or with the error message %IMGACT-F-SYMVECMIS (Alpha).
In such a situation, where you only add interfaces at the end of the
symbol vector, you can safely leave the minor ID of the updated
shareable image the same and rely on the check of the image activator.
Examples
| #1 |
$ LINK/SHAREABLE MY_SHARE,SYS$INPUT/OPTIONS
GSMATCH=LEQUAL,1,1000
[Ctrl/Z]
|
In this example, the GSMATCH= option sets the major and minor
identification numbers for this shareable image.
| #2 |
$ LINK/SHAREABLE MY_SHARE,SYS$INPUT/OPTIONS
GSMATCH=LEQUAL,1,1001
[Ctrl/Z]
|
In this example, the shareable image created in the previous example is
relinked and the minor identification number is incremented. Note that
executable images that link with the new version cannot map to the old
version, whereas executable images that link with the old version can
map to the new version.
| #3 |
$ LINK/SHAREABLE MY_SHARE,SYS$INPUT/OPTIONS
GSMATCH=ALWAYS,0,0
[Ctrl/Z]
|
By specifying the keyword ALWAYS, an executable image can run with any
version of the shareable image (newer or older).
IDENTIFICATION=
Sets the image-id field in the image file. The image identification
usually holds a version number of the image, but can be used for any
text to identify the generated image.
Format
IDENTIFICATION=id-name
Option Values
id-name
The maximum length of the identification character string is 15
characters. If the string contains characters other than uppercase and
lowercase A through Z, the numerals 0 through 9, the dollar sign, and
the underscore, enclose it in quotation marks.
Description
On I64, the identification string is saved in the NOTE section. On
Alpha and VAX, the text is saved in the image header.
When the IDENTIFICATION= option is not specified, the linker always
creates and saves a default identification. Because object modules have
identification strings as well, the linker tries to use them for the
image. If that fails, the linker uses the file type, explicitly or
implicitly specified for the image file. In such a case you may see the
identification ".EXE".
For the default image ID, the linker takes the first non-empty
identification string from an object module, when processing the input
files. Thereafter, the default image ID is only changed, if the linker
encounters an object module that provides the transfer address. (A
transfer address is the main entry point for the image.) The providing
module is seen as the main contributor and therefore should determine
the default image ID.
Because shareable images normally do not have a main entry point, the
default image ID usually remains as the ID of the first object module
processed.
On Alpha and VAX, when linking system image with /SYSTEM and /NOHEADER,
the IDENTIFICATION= option is accepted but is not saved in the image
file.
Example
|
$ LINK /EXECUTABLE=IA64_LINKER LINKER/OPTIONS,SYS$INPUT/OPTIONS
IDENTIFICATION="I02-31"
[Ctrl/Z]
|
In this example, it is shown how a version number of the I64 linker is
specified with the IDENTIFICATION= option. With the Analyze utility,
the image can be identified as the second major release of the I64
linker with version 31.
IOSEGMENT=
Specifies the amount of space to be allocated for the image I/O
segment, which holds the buffers and OpenVMS RMS control information
for all files used by the image.
Format
IOSEGMENT=number-of-pagelets[,[NO]P0BUFS]
IOSEGMENT=0,NOP0BUFS (default)
Option Values
number-of-pagelets
Specifies the number of pagelets (512-byte units) to be allocated for
the image I/O segment. By default, the operating system uses the value
set by the IMGIOCNT system parameter to determine the size of the image
I/O space.
[NO]P0BUFS
By default, the operating system allocates the I/O segment in the P1
region of the process space and, if additional space is needed, at the
end of the P0 region. If you specify NOP0BUFS, you deny OpenVMS RMS
additional pages in the P0 region.
Description
Specifying the value of number-of-pagelets to be
greater than the value of IMGIOCNT ensures the contiguity of P1 address
space, providing that OpenVMS RMS does not require more pages than the
value specified. If OpenVMS RMS requires more pagelets than the value
specified, the pagelets in the P0 region would be used (by default).
Note that if you specify NOP0BUFS and if OpenVMS RMS requires more
pagelets than have been allocated for it, OpenVMS RMS issues an error
message.
Example
|
$ LINK MY_PROG,SYS$INPUT/OPTIONS
IOSEGMENT=100,P0BUFS
[Ctrl/Z]
|
ISD_MAX= (Alpha and VAX)
On Alpha and VAX systems, specifies the maximum number of image
sections allowed in the image.
Format
ISD_MAX=number-of-image-sections
ISD_MAX=96 (default, approximate value)
Option Values
number-of-image-sections
The maximum number of image sections that may be created. You can
specify the value in hexadecimal (%X), decimal (%D), or octal (%O)
radix. The default is decimal radix.
Description
This option is used to control the linker's creation of demand-zero
image sections by imposing an upward limit on the number of total image
sections. Thus, if the linker is creating demand-zero image sections,
and if the total number of image sections reaches the ISD_MAX= value,
demand-zero image section creation ceases at that point. (For more
information about how the linker creates demand-zero image sections,
see Section 7.4.3.)
The ISD_MAX= option may be specified only in a link operation that
produces an executable image. The ISD_MAX= option is illegal in a link
operation that produces either a shareable or a system image.
The default value for ISD_MAX= is approximately 96. Note that any value
you specify is also an approximation. The linker determines an exact
ISD_MAX= value based on characteristics of the image, including the
different combinations of section attributes. The exact value, however,
will be equal to or slightly greater than what you specify; it will
never be less.
Example
|
$ LINK MY_PROG,SYS$INPUT/OPTIONS
ISD_MAX=126
[Ctrl/Z]
|
NAME=
Sets the image-name field in the image file. The image name is used on
Alpha and VAX systems to resolve self-references in the shareable image
list.
Format
NAME=image-name
Option Values
image-name
A character string up to 39 characters in length. If the name contains
characters other than uppercase and lowercase A through Z, the numerals
0 through 9, the dollar sign, and the underscore, enclose it in
quotation marks.
Description
If the NAME= option is not specified, the string specified with
/SHAREABLE or /EXECUTABLE is used for the image-name field. If no
string was specified to /SHAREABLE or /EXECUTABLE, the name of the
first module processed is used.
The NAME= option does not affect the name of the image file.
The image-name field is not used by the linker or librarian.
For Alpha and VAX linking, if a shareable image references its own
exported symbol (on Alpha, created with a SYMBOL_VECTOR clause that
contains an ALIAS keyword), the linker always uses the string from the
NAME= option to name the image in the shareable image list. When using
a different name than the image file, the to be generated shareable
image will not show in its own shareable image list. The image-name
field will not change when the image file is renamed. This way the
image activator can always resolve a self-reference.
On I64 systems, self-references is expressed differently. There is no
entry in the shareable image list for the current image.
Self-references are referred to with a special index value into the
shareable image list (-1 in the DT_VMS_FIXUP_NEEDED field) that results
in a set of DT_NEEDED entries. However, the NAME= option is supported
for compatibility reasons.
The following conventions describe the various names that apply to an
image:
- File name - Images are given an image file specification (for
example, FOO.EXE) that can be changed with the DCL command RENAME.
- Image name - The image name as specified with the NAME= option and
stored in the image file. This name can be different than the image
file specification name. However, if you do not use the NAME= option,
the name defaults to the image file specification name. The Analyze
utility displays this name as the "Image name". Once written to the
image file, you cannot change this name.
- Global Symbol Table Name - An additional name for the image is
associated with the global symbol table (GST) and stored in the image
for example in I64 images it is in a note of type NT_VMS_GSTNAM. The
linker sets this name to be the same as the image file specification
name. This name is used by the Librarian when you insert an image into
an image library. It is displayed by the Analyze utility as the Global
Symbol Table Name. Once written to the image file, you cannot change
this name.
Example
|
$ LINK MY_PROG,SYS$INPUT/OPTIONS
NAME=MY_IMAGE
[Ctrl/Z]
|
PROTECT=
Specifies that the segments (I64) or image sections (Alpha/VAX) in one
or more clusters in a shareable image should be protected from
user-mode or supervisor-mode write access.
Format
PROTECT=YES/NO
PROTECT=NO (default)
Option Values
YES
Enables protection for all the clusters defined in subsequent lines in
the options file by the CLUSTER= option or the COLLECT= option, up to a
line containing another PROTECT= option.
NO
Disables protection for all clusters specified on subsequent lines of a
linker options file by the CLUSTER= option or the COLLECT= option, up
to the line containing another PROTECT=YES option. Protection is
disabled by default.
Description
This option is used to protect segments or image sections that contain
privileged code or data in shareable images that implement user-written
system services (called privileged shareable images). For more
information about creating user-written system services, see the
HP OpenVMS Programming Concepts Manual.
Note that the protection applies to the segments and image sections the
linker creates from the cluster, not the cluster itself. A
cluster is an internal construct the linker uses to organize how it
processes input files. The linker communicates the actual memory
requirements of an image, including its protection, to the image
activator as segment or image section specifications.
If the entire shareable image needs to be protected, specify the
/PROTECT qualifier.
For I64, HP recommends that you protect the whole image with the
/PROTECT qualifier; see Section 4.4.)
Example
|
$ LINK/SHAREABLE=MY_SHARE SYS$INPUT/OPTIONS
PROTECT=YES
CLUSTER=A,,,MOD1,MOD2
SYMBOL_VECTOR=(ENTRY=PROCEDURE)
PROTECT=NO
CLUSTER=B,,,MOD3
COLLECT=A,PSECTX,PSECTY,PSECTZ
[Ctrl/Z]
|
In this example, the segments or image sections, created from the
modules MOD1 and MOD2 in cluster A are protected; the segments or image
sections, created from the module MOD3 in cluster B are not protected;
the segments or image sections into which the program sections PSECTX,
PSECTY, and PSECTZ are collected in cluster A are protected. Note that
other linker options, such as the SYMBOL_VECTOR= option in the example,
are not affected. Please note, the symbol vector, which is a NOWRT
program section by default, is not protected with this scheme. Its
program section is collected onto the default cluster.
PSECT_ATTRIBUTE=
Specifies the attributes of a program section.
Format
PSECT_ATTRIBUTE=psect-name,attribute-keyword[,...]
Option Values
psect-name
Specifies the name of the program section whose attributes you want to
set. The name may be a character string up to 31 characters in length.
attribute-keyword
One or more attributes, identified by a keyword or a number, separated
by commas. For a complete description of the program section attributes
see Section 3.2 (I64) and Section 7.2 (Alpha and VAX).
Settable attributes
- Alignment - Specify the alignment of the program section as an
integer that represents the power of 2 required to generate the desired
alignment or specify a keyword, if available.
| Power of 2 |
Keyword |
Meaning |
|
0
|
BYTE
|
Alignment on byte boundaries.
|
|
1
|
WORD
|
Alignment on word boundaries.
|
|
2
|
LONG
|
Alignment on longword boundaries.
|
|
3
|
QUAD
|
Alignment on quadword (8-byte) boundaries.
|
|
4
|
OCTA
|
Alignment on octaword (16-byte) boundaries.
|
|
5
1
|
HEXA
|
Alignment on hexadecimal word (32-byte) boundaries.
|
|
6
1
|
--
|
Alignment on 64-byte boundaries.
|
|
7
1
|
--
|
Alignment on 128-byte boundaries.
|
|
8
|
--
|
Alignment on 256-byte boundaries.
|
|
9
|
--
|
Alignment on 512-byte boundaries.
|
|
13
|
--
|
Alignment on 8 KB boundaries.
|
|
14
|
--
|
Alignment on 16 KB boundaries.
|
|
15
|
--
|
Alignment on 32 KB boundaries.
|
|
16
|
--
|
Alignment on 64 KB boundaries.
|
|
--
|
PAGE
|
Alignment on the default target page size, see the /BPAGE qualifier
|
1I64 only
ALLOC_64BIT/NOALLOC_64BIT (I64 only) - Allocate section in P2 space
EXE/NOEXE - Executability
GBL/LCL - Global/Local
MOD (I64 and Alpha) - Unmodified
OVR/CON - Overlaid/Concatenated
PIC/NOPIC (Alpha and VAX) - Position Independence
REL/ABS - Relocatable/Absolute
SHORT (I64 only) - Short Data
SHR/NOSHR - Shareability
SOLITARY - Solitary
VEC/NOVEC - Protected Vectors
WRT/NOWRT - Writability
Description
Attributes not specified in a PSECT_ATTRIBUTE= option remain unchanged.
If you specify a program section alignment that is greater than the
target page size, the linker issues a warning and adjusts the alignment
to be equal to the target page size.
By default, the linker aligns program sections, at a minimum, on the
boundary specified by the compiler.
The PSECT_ATTRIBUTE= option aligns the program section on the specified
boundary which should be equal to or greater than that which the
compiler specified. The linker does not align each individual
contribution to the section; rather, it aligns the total program
section. The linker follows the compiler's alignment specification when
it aligns each individual contribution.
Do not specify a smaller program section alignment with the
PSECT_ATTRIBUTE= option than the alignment that the compiler gave to
the program section.
On I64 systems, If you specify a smaller alignment for a program
section than any compiler-assigned alignment from all contributions to
this program section, the linker issues a warning. For example:
$ lINK HI,SYS$INPUT/OPTIONS
PSECT_ATTRIBUTE=$LITERAL$,BYTE
[Ctrl/Z]
%ILINK-W-CONFALGN, PSECT option alignment (1) less than compiler
assigned (16);
alignment ignored
section: $LITERAL$
module: HI
file: DISK$USER:[JOE]HI.OBJ;3
|
Please note, the alignment number in the linker message indicates a
multiple-of-bytes alignment, where 1 is a byte alignment and 16 is an
octaword alignment.
On Alpha and VAX systems, the linker inappropriately aligns the program
section on the boundary that you specified ("byte", in the preceding
code example), and places all the contributions to that program section
(from other modules you might have linked with "HI", in the example) on
boundaries that were not specified by the compiler. The linker does not
issue an error message.
Example
|
$ LINK MY_PROG,SYS$INPUT/OPTIONS
PSECT_ATTRIBUTE=MY_CONST,NOWRT
[Ctrl/Z]
|
In this example, the linker protects the program section MY_CONST from
write access and leaves all other attributes of MY_CINST unchanged.
RMS_RELATED_CONTEXT=
Enables or disables RMS related name context processing. This is also
known as file specification "stickiness." The default is to have RMS
related name context processing enabled. This default applies at the
start of each options file regardless of the setting in a previous
options file. The related name context itself (the collection of data
structures RMS maintains to supply the most recently specified fields)
does not carry over from one linker options file to the next. That is,
previously specified fields in the previous options file are not used
to fill in absent fields for file specifications in the current options
file.
Format
RMS_RELATED_CONTEXT=YES/NO
RMS_RELATED_CONTEXT=YES (default)
Option Values
YES
Enables RMS related name context processing. If an option
RMS_RELATED_CONTEXT=NO is in effect, its saved related name context is
restored. If RMS related name context processing is already enabled,
this option has no effect.
RMS related name context processing is enabled by default. Therefore
command line file specifications are processed with RMS related name
context. Also, RMS related name context processing is enabled at the
start of each options file. The related name context is limited to a
single options file. That is, the saved related name context is cleared
at the start of each options file.
NO
Disables RMS related name context processing. If an option
RMS_RELATED_CONTEXT=YES is in effect, the current name context is saved
for a possible future RMS_RELATED_CONTEXT=YES option. If RMS related
name context processing is already disabled, specifying
RMS_RELATED_CONTEXT=NO has no effect.
Description
When RMS related name processing is enabled (by default and at the
beginning of each options file), file specifications that do not have
all fields of the file specification present will have the missing
fields replaced with the corresponding fields most recently specified
in earlier file specifications. When disabled, fields in the file
specification that are absent are not replaced with corresponding
fields of previous file specifications.
When the RMS related name context processing is switched from enabled
to disabled, the current related name context is saved. Vice versa, if
the RMS related name context processing is switched from disabled to
enabled, the saved related name context is restored.
In combination with logical names and search lists, determining a
missing input file with RMS related name context processing enabled may
take long. To the user the link operations seems to hang or to loop. To
identify such a situation and to resolve it by determining which file
is missing, follow these steps:
- Specify SYS$INPUT/OPTIONS in the LINK command and press Return.
(The linker waits for you to enter option clauses for the link
operation from the terminal.)
- Enter the option clauses and include the following information:
- On the first line, specify:
RMS_RELATED_CONTEXT=NO
With the RMS_RELATED_CONTEXT= option set to NO, any missing file
listed in this options file generates an immediate "file not found"
message.
- On subsequent lines, specify the files to be linked, using full
file specifications in the form
disk:[dir]filename.ext
for every file. Full file specifications are required because when you
specify RMS_RELATED_CONTEXT=NO, file name "stickiness" is disabled.
- Press Ctrl/Z.
Example
|
$ LINK DSK:[TEST]A.OBJ, B.OBJ
|
In this example the RMS related name context processing is enabled by
default. The specified input file B.OBJ gets the name context
DSK:[TEST] from the previous input file DSK:[TEST]A.OBJ.
|
$ LINK/EXECUTABLE=A.EXE SYS$INPUT/OPTIONS
RMS_RELATED_CONTEXT=NO
DSK:[TEST]A.OBJ, DSK:[TEST]B.OBJ
[Ctrl/Z]
|
In this example the RMS related name context processing is disabled.
The full file specifications for both object modules are required. The
link operation is the same as in the previous example.
|
$ DEFINE DSKD$ WORK4:[TEST.LINKER.OBJ.](1)
$ DEFINE RESD$ ROOT$, ROOT2$, ROOT3$,
ROOT4$, ROOT5$, DISK_READ$:[SYS.]
$ DEFINE ROOT$ WORK4:[TEST.PUBLIC.TEST]
$ DEFINE ROOT2$ WORK4:[TEST.LINKER.]
$ DEFINE ROOT3$ WORK4:[TEST.UTIL32.]
$ DEFINE ROOT4$ WORK4:[TEST.PUBLIC.]
$ DEFINE ROOT5$ WORK4:[TEST.PUBLIC.TMP]
$ LINK/MAP/FULL/CROSS_REFERENCE/EXECUTABLE=ALPHA.EXE RESD$:[TMPOBJ]A.OBJ,-
_$ RESD$:[SRC]B.OBJ,C,DSKD$:[OBJ]D.OBJ,E,RESD$:[TMPSRC]F.OBJ,-
_$ RESD$:[TEST]G.OBJ,RESD$:[SRC.OBJ]H,RESD$:[COM]DOES_NOT_EXIST.OBJ
[Ctrl/T](2)
NODE6::_FTA183: 15:49:46 LINK CPU=00:02:30.04 PF=5154 IO=254510 MEM=134
[Ctrl/T]
NODE6::_FTA183: 15:49:46 LINK CPU=00:02:30.05 PF=5154 IO=254513 MEM=134
[Ctrl/T]
NODE6::_FTA183: 15:50:02 LINK CPU=00:02:38.27 PF=5154 IO=268246 MEM=134
[Ctrl/T]
NODE6::_FTA183: 15:50:02 LINK CPU=00:02:38.28 PF=5154 IO=268253 MEM=134
[Ctrl/T]
NODE6::_FTA183: 15:50:14 LINK CPU=00:02:44.70 PF=5154 IO=278883 MEM=134
|
|
