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 ¹ HEXA Alignment on hexadecimal word (32-byte) boundaries.

6 ¹ -- Alignment on 64-byte boundaries.

7 ¹ -- 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

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 ¹	HEXA	Alignment on hexadecimal word (32-byte) boundaries.
6 ¹	--	Alignment on 64-byte boundaries.
7 ¹	--	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

¹I64 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

      $  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

Previous Next Contents Index