HP OpenVMS Systems Documentation

HP OpenVMS Linker Utility Manual

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]/NOBRIEF/NOCROSS_REFERENCE/NOFULL (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

On OpenVMS I64, the /MAP qualifier causes the linker to produce a default image map file containing the following sections:

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

On OpenVMS Alpha and VAX, the /MAP qualifier causes the linker to produce a default image map file containing the following sections:

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

See Chapter 5 (I64) and Chapter 9 (Alpha and VAX) 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.

$ LINK MY_PROG,MY_SUB/MAP
      

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

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

This example directs the linker to produce an image map with the default name of .MAP, because SYS$INPUT is a device specification without a file name.

For I64 and Alpha systems, prevents the linker from generating procedure signature information.

Format

/NATIVE_ONLY (default)

/NONATIVE_ONLY

Qualifier Values

None.

Description

For I64 and Alpha systems, prevents the linker from generating procedure signature information. Procedure signatures are required to allow the native code being linked to interoperate with images translated from either VAX or Alpha binary code. To build an executable or shareable image that calls or can be called by translated code, link it using /NONATIVE_ONLY. Code that is to interoperate with translated images must also be compiled using the /TIE qualifier. (See the associated compiler documentation for details.)

Example

$ LINK/NATIVE_ONLY MY_PROG

      

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

$ LINK/NONATIVE_ONLY MY_PROG

      

In this example, the linker creates an image, named MY_PROG.EXE, that can interoperate with translated OpenVMS 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

/NOP0IMAGE (default)

Qualifier Values

None.

Description

For Alpha and VAX, 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 segments (I64) or image sections (Alpha) 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.

For I64, HP recommends that you protect the whole image with the /PROTECT qualifier; see Section 4.4.)

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.

This qualifier is ignored by the OpenVMS I64 Linker.

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

This qualifier is ignored by the OpenVMS I64 Linker. The I64 linker always produces images that can be installed as resident images.

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_ATTRIBUTE= 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/SHAREABLE/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.

Instructs the OpenVMS I64 linker to set certain attributes for segments.

Format

/SEGMENT_ATTRIBUTE=(segm-attribute[,...])

Qualifier Values

segm-attribute

The I64 Linker accepts the following keywords to set segment attributes

CODE=address_region
DYNAMIC=address_region
SHORT=WRITE
SYMBOL_VECTOR=[NO]SHORT

where an address_region can be specified with keywords P0 and P2.

Description

By default, the linker puts the dynamic segment, which contains information for the image activator, into P2 space. For images not activated by the OpenVMS image activator, DYNAMIC=P0 forces the linker to put the dynamic segment into P0 space. This qualifier is primarily used by system developers.

With the CODE=P2 keyword, the I64 Linker allows you to assign code segments to P2 space. When the image activator activates the image, the code segments will be placed in P2 space. If you use this keyword, be aware that all code addresses will be 64 bits wide. Your exception handlers must use only the 64-bit versions of the signal and mechanism arrays and should be prepared to handle a 64-bit PC.

The SHORT_DATA=WRITE keyword allows you to combine the read-only and the read-write short data segments into a single segment, reclaiming up to 65,535 bytes of unused, read-only space (when /BPAGE=16, the default value). When setting SHORT_DATA to WRITE, your program may accidentally write to formerly read-only data. Therefore, this qualifier is recommended only if your short data segment has reached the limit of 4 MB.

By default, for shareable images, the linker stores the symbol vector into the read-only short data segment. By specifying SYMBOL_VECTOR=NOSHORT, the linker collects the symbol vector into a read-only data segment of the default cluster. If the shareable image has none, such a segment is created. This frees up the short data of the symbol vector entries. This qualifier is recommended only if your short data segment has reached the limit of 4 MB.

When this qualifier is appended to an input file specification, the linker processes only those symbols in the input file that have been referenced by previously processed input files.

Format

input-file-name/SELECTIVE_SEARCH

Qualifier Values

input-file-name

The input file you want included in the link operation. The /SELECTIVE_SEARCH qualifier works with object modules and shareable images only. This qualifier is illegal with library files. (To process the modules in a library selectively, you specify the /SELECTIVE_SEARCH qualifier when inserting the files into the library. For more information, see the HP OpenVMS Command Definition, Librarian, and Message Utilities Manual.)

Description

If you do not specify the /SELECTIVE_SEARCH qualifier with an input file, the linker includes all the input file's global symbols in the linker's internal global symbol table for symbol resolution by default.

Note that the /SELECTIVE_SEARCH qualifier does not affect the size of the resultant image. The entire object module is included in the image, even if only a subset of the symbols in its global symbol table are needed to resolve symbolic references. Specifying the /SELECTIVE_SEARCH qualifier can improve the performance of a link operation and conserve the linker's use of virtual memory.

Examples

$ LINK/MAP MY_MAIN,MY_PROG/SELECTIVE_SEARCH
      

In this example, the linker processes the object module MY_PROG.OBJ selectively. You can verify this processing by checking the list of symbols in the image map file created in this link. The only symbols from the file MY_PROG.OBJ that will appear in the map file are those symbols that were referenced by MY_MAIN.OBJ.

$ LINK/MAP=MY_MAIN/EXECUTABLE=MY_MAIN SYS$INPUT/OPTIONS
CLUSTER=MY_MAIN_CLUS,,,MY_MAIN
MY_SHARE/SHAREABLE/SELECTIVE_SEARCH
[Ctrl/Z]
      

In this example, the linker processes the shareable image MY_SHARE.EXE selectively. Note that, to ensure that the linker processes references to symbols in the shareable image before it processes the shareable image selectively, the input file MY_MAIN.OBJ is placed in a named cluster (MY_MAIN_CLUS), using the CLUSTER= option. If the object modules had been specified on the LINK command line, the linker would have put it in the default cluster. The linker processes named clusters before it processes the default cluster.

$ LIBRARIAN/INSERT/SELECTIVE_SEARCH MY_LIB MY_PROG
$ LINK MY_PROG,MY_LIB/LIBRARY
      

In this example, the object module MY_PROG.OBJ is inserted into the library MY_LIB.OLB selectively. When the library is specified in a link operation, the linker processes the object module selectively. This link operation is equivalent to the link operation in example 1.

When specified anywhere on the LINK command line, the /SHAREABLE qualifier directs the linker to create a shareable image. When the /SHAREABLE qualifier is appended to a file specification in a linker options file, it identifies the input file as a shareable image.

Format

/SHAREABLE[=file-spec]

/NOSHAREABLE (default)

shareable-image-file-name/SHAREABLE

Qualifier Values

file-spec

When the /SHAREABLE qualifier is used to create a shareable image, this parameter specifies the name you want the linker to assign to the shareable image being created. If you do not include a file specification, the linker assigns the shareable image the name of the file to which the /SHAREABLE qualifier is appended in the LINK command line. If the /SHAREABLE qualifier is not appended to an input file specification, the linker assigns to the shareable image the name of the first input file specified on the command line using the extension .EXE.

If you designate a file name but omit the file type, the linker assigns the shareable image the file type .EXE.

shareable-image-file-name

Specifies the name of a shareable image. Note that you can use the /SHAREABLE qualifier to identify a shareable image only in a linker options file. It is illegal to include a shareable image in a link operation by specifying it on the LINK command line.

Description

The linker creates executable images by default; you must specify the /SHAREABLE qualifier to create a shareable image. The /SHAREABLE qualifier is incompatible with the /SYSTEM qualifier.

For more information about creating and using shareable images, see Chapter 4 (I64) and Chapter 8 (Alpha and VAX).

Examples

$ LINK/SHAREABLE MY_SHARE,UNIVERSALS/OPTIONS
      

This example directs the linker to produce a shareable image named MY_SHARE.EXE. The options file UNIVERSALS.OPT contains declarations of the universal symbols in the shareable image.

$ LINK/SHAREABLE=MY_APP MY_SHARE,UNIVERSALS/OPTIONS
      

This example directs the linker to produce a shareable image named MY_APP.EXE using the object module MY_SHARE.OBJ as input.

$ TYPE MY_OPTIONS.OPT
MY_SHARE/SHAREABLE
$ LINK MY_PROG,MY_OPTIONS.OPT/OPTIONS

      

In this example, a shareable image is included in a link operation. The shareable image is specified in the options file MY_OPTIONS.OPT, which is specified as an input file on the LINK command line.

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

      

This example shows how the shareable image MY_SHARE.EXE is used, together with the object file MY_PROG.OBJ, to create an executable image named MY_PROG.EXE.

Note how you can specify options interactively at the command line by identifying the logical name SYS$INPUT as an options file. The linker interprets the lines following the LINK command as the contents of an options file, until you terminate the options by entering the Ctrl/Z key sequence.