HP OpenVMS Systems Documentation

HP OpenVMS Linker Utility Manual

Invokes the OpenVMS Linker utility to link one or more input files into a program image and defines the execution characteristics of the image.

Format

LINK file-spec [,...]

Qualifiers	Defaults
/ALPHA	Platform dependent (Alpha and VAX),
	see reference description.
/BASE_ADDRESS[=address]	/NOBASE_ADDRESS (I64 only)
/BPAGE[=page-size-indicator]	Platform dependent,
	see reference description.
/BRIEF	None.
/CONTIGUOUS	/NOCONTIGUOUS
/CROSS_REFERENCE	None.
/DEBUG[=file-spec]	/NODEBUG
/DEMAND_ZERO[=PER_PAGE]	/DEMAND_ZERO (I64 and Alpha)
/DNI	/DNI (I64 only)
(Display Name Information)
/DSF[=file-spec]	/NODSF (I64 and Alpha)
(Debug Symbol File)
/EXECUTABLE[=file-spec]	/EXECUTABLE
/FP_MODE=keyword	/NOFP_MODE (I64 only)
/FULL[=(keyword[,...])]	None.
/GST	/GST (I64 and Alpha)
(Global Symbol Table)
/HEADER	/NOHEADER (Alpha and VAX) *
/INCLUDE=(module-name[,...])	None.
/INFORMATIONALS	/INFORMATIONALS
/LIBRARY	None.
/MAP[=file-spec]	/NOMAP (in interactive mode)
/NATIVE_ONLY	/NATIVE_ONLY (I64 and Alpha)
/OPTIONS	None.
/P0IMAGE	/NOP0IMAGE
/PROTECT	/NOPROTECT
/REPLACE	/REPLACE (Alpha only) *
/SECTION_BINDING[=(CODE,DATA)]	/NOSECTION_BINDING (Alpha only) *
/SEGMENT_ATTRIBUTE=(segm-attribute,[...])	None. (I64 only)
/SELECTIVE_SEARCH	None.
/SHAREABLE[=file-spec]	/NOSHAREABLE
/SYMBOL_TABLE[=file-spec]	/NOSYMBOL_TABLE
/SYSEXE	/NOSYSEXE (I64 and Alpha)
/SYSLIB	/SYSLIB
/SYSSHR	/SYSSHR
/SYSTEM[=base-address]	/NOSYSTEM (Alpha and VAX)
/THREADS_ENABLE	/NOTHREADS_ENABLE
/TRACE	/TRACE
/USERLIBRARY[=(table[,...])]	/USERLIBRARY=ALL
/VAX	Platform dependent (Alpha and VAX),
	see reference description.

Parameters

file-spec [,...]

Specifies one or more input files (wildcard characters are not allowed). Input files may be object modules, shareable images, libraries to be searched for external references or from which specific modules are to be included, or options files to be read by the linker. Separate multiple input file specifications with commas (,) or plus signs (+). In either case, the linker creates a single image file.

If you omit the file type in an input file specification, the linker supplies default file types, based on the nature of the input file. For object modules, the default file type is .OBJ. For more information about specifying input files, see Chapter 1.

This section describes the LINK command qualifiers.

/ALPHA (Alpha and VAX)

Directs the linker to produce an OpenVMS Alpha image.

On OpenVMS Alpha or VAX systems, when neither /ALPHA nor /VAX is specified, the default action is to create an OpenVMS VAX image on an OpenVMS VAX system and to create an OpenVMS Alpha image on an OpenVMS Alpha system.

Format

/ALPHA

Qualifier Values

None.

Description

This qualifier is used to instruct the linker to accept OpenVMS Alpha object files and library files to produce an OpenVMS Alpha image.

You must inform the linker where OpenVMS Alpha system libraries and shareable images are located with the logical names ALPHA$LOADABLE_IMAGES and ALPHA$LIBRARY. On an OpenVMS Alpha system, these logicals are already defined to point to the correct directories on the current system disk. On OpenVMS VAX, you must define these logical names so that they translate to the location of an OpenVMS Alpha system disk residing on the system where the Alpha linking is to occur.

For more information on cross-architecture linking, see Section 1.5.

Example

$ DEFINE ALPHA$LIBRARY DKB100:[VMS$COMMON.SYSLIB]
$ DEFINE ALPHA$LOADABLE_IMAGES DKB100:[VMS$COMMON.SYS$LDR]
$ LINK/ALPHA ALPHA.OBJ

      

This example, which is performed on an OpenVMS VAX system, shows the definition of logical names to point to the appropriate areas on an OpenVMS Alpha system disk mounted on device DKB100. The qualifier /ALPHA tells the linker to expect the object file, ALPHA.OBJ, to be an OpenVMS Alpha object file and to link it using the OpenVMS Alpha libraries and images on DKB100, if necessary.

This qualifier is valid only for the OpenVMS I64 Linker.

Assigns a virtual address for executable images that are not activated by the OpenVMS image activator, such as images used in the boot process.

Format

/BASE_ADDRESS=address

/NOBASE_ADDRESS (default)

Qualifier Values

address

The location at which you want the first segment of the executable image located. You can express this location as decimal (%D), octal (%O), or hexadecimal (%X) numbers. The default is hexadecimal.

Description

The /BASE_ADDRESS qualifier assigns a virtual address for executable images that are not activated by the OpenVMS image activator, such as images used in the boot process. The base address is the starting address that you want the linker to assign to an executable image. The OpenVMS image activator is free to ignore any linker-assigned starting address. This qualifier is used primarily by system developers.

The /BASE_ADDRESS qualifier does not replace the BASE= option or the base-address specifier in the CLUSTER= option, which is illegal on OpenVMS I64.

For all images (executable and shareable), the starting address is determined by the image activator. Any linker assigned address value can be changed when activating the image.

Specifies the page size the linker should use when it creates the segments (I64) or image sections (Alpha and VAX) that make up an image.

Format

/BPAGE[=page-size-indicator]

Qualifier Values

page-size-indicator

An integer that specifies a page size as the power of 2 required to create a page that size. For example, to get an 8 KB page size, specify the value 13 because 2¹³ equals 8K. The following table lists the page sizes supported by the linker with the defaults:

Value	Page Size	Defaults
9	512 bytes	Default value for VAX links when the /BPAGE qualifier is not specified.
13	8 KB	Default value for VAX links when the /BPAGE qualifier is specified without a value.
14	16 KB	--
15	32 KB	--
16	64 KB	Default value for I64 and Alpha links when /BPAGE is not specified or when the /BPAGE qualifier is specified without a value.

Description

The images the linker creates are made up of segments (I64) or image sections (Alpha and VAX) that the linker allocates on page boundaries. When you specify a larger page size, the origin of segments or image sections increases to the next multiple of that size.

An image linked to a page size that is larger than the page size of the CPU generally runs correctly, but it might consume more virtual address space.

For I64 and Alpha linking, by default the linker creates segments or image sections on 64 KB boundaries, thus allowing the images to run properly on any I64 and Alpha system, regardless of the hardware page size.

For VAX linking, linking a shareable image to a larger page size can cause the value of transfer vector offsets to change if they were not allocated in page 0 of the image. Do not link against a shareable image that was created with a different page size. (You cannot determine the page size used in the creation of a VAX image from the image.)

Example

$ LINK/BPAGE=16 MY_PROG.OBJ

      

Including the value 16 with the /BPAGE qualifier causes the linker to create segments (I64) or image sections (Alpha and VAX) on 64 KB page boundaries.

Directs the linker to produce a brief image map. For more information, see also the /MAP and /FULL qualifiers.

Format

/MAP/BRIEF

Qualifier Values

None.

Description

On I64, a brief map contains the following sections:

• Object and Image Synopsis
• Image Segment Synopsis
• Link Run Statistics

On Alpha and VAX, a brief map contains the following sections:

• Object Module Synopsis
• Image Section Synopsis
• Link Run Statistics

In contrast, the default image map on I64 contains the Object and Image Synopsis, Image Synopsis, Link Run Statistics, Program Section Synopsis, and Symbols By Name sections. On Alpha and VAX the default image map contains the Object Module Synopsis, Image Synopsis, Link Run Statistics, Program Section Synopsis, and Symbols By Name sections. For more information about image maps, see Chapter 5 (I64) and Chapter 9 (Alpha and VAX).

The /BRIEF qualifier must be specified with the /MAP qualifier and is incompatible with the /FULL qualifier and the /CROSS_REFERENCE qualifier.

Example

$ LINK/MAP/BRIEF MY_PROG

      

In this example, the linker creates a brief image map with the file name MY_PROG.MAP.

Directs the linker to place the entire image in consecutive disk blocks. If sufficient contiguous space is not available on the output disk, the linker reports an error and terminates the link operation.

Format

/CONTIGUOUS

/NOCONTIGUOUS (default)

Qualifier Values

None.

Description

You can use the /CONTIGUOUS qualifier to speed up the activation time of any type of image because images usually activate more slowly if their image disk blocks are not contiguous. Note, however, that in most cases performance benefits do not warrant the use of the /CONTIGUOUS qualifier.

You can also use the /CONTIGUOUS qualifier when linking bootstrap programs for certain system images that require contiguity.

Even when you do not specify the /CONTIGUOUS qualifier, the file system tries to use contiguous disk blocks for images, if sufficient contiguous space is available.

Example

$ LINK/CONTIGUOUS MY_PROG
      

This example directs the linker to place the entire image named MY_PROG.EXE in consecutive disk blocks.

Directs the linker to replace the Symbols By Name section in a full or default image map with the Symbol Cross-Reference section.

Format

/MAP/CROSS_REFERENCE

Qualifier Values

None.

Description

The Symbol Cross-Reference section lists, in alphabetical order, the name of each global symbol, together with the following information about each:

• Its value
• The name of the first module in which it is defined
• The name of each module in which it is referenced

The number of symbols listed in the cross-reference section depends on whether the linker generates a full map or a default map. In a full map, this section includes global symbols from all modules in the image, including those extracted from all libraries. In a default map, this section does not include global symbols from modules extracted from the default system libraries IMAGELIB.OLB and STARLET.OLB. For more information about image map files, see Chapter 5 (I64) and Chapter 9 (Alpha and VAX).

The /CROSS_REFERENCE qualifier is incompatible with the /BRIEF qualifier.

Example

$ LINK/MAP/CROSS_REFERENCE MY_PROG
      

This example produces an image map file named MY_PROG.MAP that includes a Symbol Cross-Reference section.

Directs the linker to generate debug and traceback information and to give the debugger control when the image is run.

Format

/DEBUG[=file-spec]

/NODEBUG (default)

Qualifier Values

file-spec (Alpha and VAX)

Identifies a user-written debugger module.

If you specify the /DEBUG qualifier without entering a file specification, the OpenVMS Debugger gains control at run time. Requesting the OpenVMS Debugger does not affect the location of code within the image because the debugger is mapped into the process address space at run time, not at link time. See the HP OpenVMS Debugger Manual for additional information.

On I64 systems, a file specification is not allowed.

On Alpha and VAX, if you specify the /DEBUG qualifier with a file specification, the user-written debugger module that the file specification identifies gains control at run time. The linker assumes a default file type of .OBJ. Requesting a user- written debugger module does affect the location of code within the image.

Description

The /DEBUG qualifier automatically includes the /TRACE qualifier. If you specify the /DEBUG qualifier and the /NOTRACE qualifier, the linker overrides your specification and includes traceback information.

To debug a shareable image, you must compile and link it with the /DEBUG qualifier and then include it in a link operation that creates a debuggable image (that link operation must also use the /DEBUG qualifier).

On I64, the Table 3-10 indicates where global symbol definitions are written during a link operation that uses the debug related qualifiers as /DEBUG, /DSF or /TRACE. See also Table 3-9) how these qualifiers determine the link flags in the generated image.

For I64 and Alpha, the Table LINKER-1 shows the effects of debug-related qualifiers when running an image.

Table LINKER-1 Effects of /DEBUG, /DSF and /TRACE when Running an Image on I64 and Alpha

	RUN	RUN/DEBUG	RUN/NODEBUG	Traceback Info	Debug Info
/NoTrace /NoDebug /NoDSF	Start main	Same as RUN	Same as RUN	None	None
/Trace /NoDebug /NoDSF	Enable traceback handler; start main	Set initial breakpoint; start debugger	Same as RUN	Automatic: in image	None
/NoTrace /Debug /NoDSF	The linker converts /NoTrace to /Trace: see next row
/Trace /Debug /NoDSF	Set initial breakpoint; start debugger	Same as RUN	Enable traceback handler; start main	Automatic: in image	Automatic: in image
/NoTrace /NoDebug /DSF	Start main	Same as RUN	Same as RUN	Not used	Not used
/Trace /NoDebug /DSF	Enable traceback handler; start main	Set initial breakpoint; start debugger	Same as RUN	Automatic: in image 1	Manual: in DSF
/NoTrace /Debug /DSF	The linker converts /NoTrace to /Trace: see next row
/Trace /Debug /DSF	Set initial breakpoint; start debugger	Same as RUN	Enable traceback handler; start main	Automatic: in image 1	Manual: in DSF

Additional information:

• The VAX linker does not generate a DSF file. For VAX, a reduced table with /NoDSF lines applies.
• Start main - Execution starts at the main entry of the image
• None---No traceback or debug information is generated by the linker
• Enable traceback handler---In case of an error, a traceback with source line information is printed. if there is no handler, in case of an error, a register dump is printed.
• Set initial breakpoint---Depending on the programming language, the initial breakpoint may be at main or before main
• Start debugger---The debugger controls the execution of the image
• Not used---There is traceback or debug information in the image or DSF file, however it is not used.
• Automatic---Automatically found by the debugger.
• Manual---Automatically found by the debugger if the DSF is in the same directory as the image. Manually points to a different directory of the DSF file with the logical DBG$IMAGE_DSF_PATH.

Example

$ LINK/DEBUG MY_PROG
      

This example produces an executable image named MY_PROG.EXE. Upon image activation, control will be passed to the debugger.

For I64 and Alpha linking, enables demand-zero segment (I64) or image section (Alpha) production for both executable and shareable images.

Format

/DEMAND_ZERO (default)

/DEMAND_ZERO[=PER_PAGE]

/NODEMAND_ZERO

Qualifier Values

PER_PAGE

On I64, directs the linker to compress trailing zeros for each segment (that is, demand-zero compression of zeros on trailing pages).

On Alpha, enables the linker to perform demand-zero compression on Alpha images on a per-page basis. If this keyword is not used, the linker performs demand-zero compression on an image-section basis only.

Description

On I64 system, compilers identify uninitialized sections by setting the NOBITS section type, which is interpreted by the linker as the NOMOD program section attribute.

On Alpha systems, compilers identify to the linker which program sections have not been initialized by setting the NOMOD program section attribute.

The linker collects these uninitialized program sections into demand-zero segments (I64) or image sections (Alpha). (For more information about demand-zero segment or image section production, see Section 3.4.4 for I64 and Section 7.4.3 for Alpha.)

If you specify the /NODEMAND_ZERO qualifier, the linker still gathers uninitialized program sections into demand-zero segments or image sections but writes them to disk. Thus, the virtual memory layout of an image is the same when the /DEMAND_ZERO qualifier is specified and when the /NODEMAND_ZERO qualifier is specified.

If you specify the /NODEMAND_ZERO qualifier, the linker turns the demand-zero segments or image sections containing the NOMOD sections into regular segments or image sections. The Alpha linker sets the copy-on-reference (CRF) attribute if the write (WRT) attribute is set.

To force the linker to write a section to disk that otherwise would be included in a demand-zero segment or image section, turn off the NOMOD attribute of the section by using the PSECT_ATTRIBUTE= option, as in the following example:

PSECT_ATTRIBUTE=psect-name,MOD

Note that only language processors can set the NOMOD attribute of a section.

Examples

$ LINK/NODEMAND_ZERO

      

In this example, the linker does not perform demand-zero compression.

$ LINK/DEMAND_ZERO

      

In this example, the linker by default performs demand-zero compression on a per-segment (I64) or per-image-section (Alpha) basis.

$ LINK/DEMAND_ZERO=PER_PAGE

      

In this example, on I64, the linker performs demand-zero compression on both a per-segment and per-trailing-pages basis. On Alpha, the linker performs demand-zero compression on both a per-image-section basis and a per-page basis.