HP OpenVMS Systems Documentation
HP OpenVMS Linker Utility Manual
|/ALPHA||Platform dependent (Alpha and VAX),|
|see reference description.|
|/BASE_ADDRESS[=address]||/NOBASE_ADDRESS (I64 only)|
|see reference description.|
|/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)|
|/FP_MODE=keyword||/NOFP_MODE (I64 only)|
|/GST||/GST (I64 and Alpha)|
|(Global Symbol Table)|
|/HEADER||/NOHEADER (Alpha and VAX) *|
|/MAP[=file-spec]||/NOMAP (in interactive mode)|
|/NATIVE_ONLY||/NATIVE_ONLY (I64 and Alpha)|
|/REPLACE||/REPLACE (Alpha only) *|
|/SECTION_BINDING[=(CODE,DATA)]||/NOSECTION_BINDING (Alpha only) *|
|/SEGMENT_ATTRIBUTE=(segm-attribute,[...])||None. (I64 only)|
|/SYSEXE||/NOSYSEXE (I64 and Alpha)|
|/SYSTEM[=base-address]||/NOSYSTEM (Alpha and VAX)|
|/VAX||Platform dependent (Alpha and VAX),|
|see reference description.|
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.
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.
$ 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.
addressThe 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.
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.
page-size-indicatorAn 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 213 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.
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.)
$ 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.
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.
$ 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.
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.
$ 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.
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.
$ 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.
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.
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
Start main Same as RUN Same as RUN None None /Trace
Enable traceback handler; start main Set initial breakpoint; start debugger Same as RUN Automatic: in image None /NoTrace
The linker converts /NoTrace to /Trace: see next row /Trace
Set initial breakpoint; start debugger Same as RUN Enable traceback handler; start main Automatic: in image Automatic: in image /NoTrace
Start main Same as RUN Same as RUN Not used Not used /Trace
Enable traceback handler; start main Set initial breakpoint; start debugger Same as RUN Automatic: in image 1 Manual: in DSF /NoTrace
The linker converts /NoTrace to /Trace: see next row /Trace
Set initial breakpoint; start debugger Same as RUN Enable traceback handler; start main Automatic: in image 1 Manual: in DSF
$ 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.
PER_PAGEOn 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.
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:
Note that only language processors can set the NOMOD attribute of a section.
In this example, the linker does not perform demand-zero compression.
In this example, the linker by default performs demand-zero compression on a per-segment (I64) or per-image-section (Alpha) basis.
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.