Document revision date: 19 July 1999

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	See reference description.
/BPAGE	See reference description.
/BRIEF	None
/[NO]CONTIGUOUS	/NOCONTIGUOUS
/[NO]CROSS_REFERENCE	/NOCROSS_REFERENCE
/[NO]DEBUG[=file-spec]	/NODEBUG
/[NO]DEMAND_ZERO[=per_page]	/DEMAND_ZERO (Alpha linking only)
/[NO]DSF[=file-spec]	/NODSF (Alpha linking only)
/[NO]EXECUTABLE[=file-spec]	/EXECUTABLE
/FULL	None
/[NO]GST	/GST (Alpha linking only)
/HEADER	None
/INCLUDE=(module-name[,...])	None
/[NO]INFORMATIONALS	/INFORMATIONALS
/LIBRARY	None
/[NO]MAP[=file-spec]	/NOMAP
/[NO]NATIVE_ONLY	/NATIVE_ONLY (Alpha linking only)
/OPTIONS	None
/P0IMAGE	None
/PROTECT	None
/[NO]REPLACE	/REPLACE (Alpha linking only)
/[NO]SECTION_BINDING[=(CODE,DATA)]	/NOSECTION_BINDING (Alpha linking only)
/SELECTIVE_SEARCH	None
/[NO]SHAREABLE[=file-spec]	/NOSHAREABLE
/[NO]SYMBOL_TABLE[=file-spec]	/NOSYMBOL_TABLE
/[NO]SYSEXE	/NOSYSEXE (Alpha linking only)
/[NO]SYSLIB	/SYSLIB
/[NO]SYSSHR	/SYSSHR
/[NO]SYSTEM[=base-address]	/NOSYSTEM
/[NO]TRACEBACK	/TRACEBACK
/[NO]THREADS_ENABLE	/NOTHREADS_ENABLE
/[NO]USERLIBRARY[=(table[,...])]	/USERLIBRARY=ALL
/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

Directs the linker to produce an OpenVMS Alpha image. The default action, when neither /ALPHA nor /VAX is specified, 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.6.

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.

Specifies the page size the linker should use when it creates the image sections 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 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 image sections that the linker allocates on page boundaries. When you specify a larger page size, the origin of 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 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.)

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

Example

$ LINK/BPAGE=16 MY_PROG.OBJ
 
      

Including the value 16 with the /BPAGE qualifier causes the linker to create image sections 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

A brief map contains the following sections:

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

In contrast, 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.

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

/MAP/NOCROSS_REFERENCE (default)

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.

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 a debugger symbol table (DST) using DBG and TBT object language records and to give the debugger control when the image is run.

Format

/DEBUG[=file-spec]

/NODEBUG (default)

Qualifier Values

file-spec

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 OpenVMS Debugger Manual for additional information.

If you specify the /DEBUG qualifier with a file specification, the user-written debugger module identified by the file specification 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 because the debugger module code is processed by the linker together with program code.

Description

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

To debug a shareable image, you must include it in a link operation that creates an executable image. Specify the /DEBUG qualifier when compiling the source modules that comprise the shareable image and specify the /DEBUG qualifier when linking the shareable image.

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 Alpha linking, enables demand-zero image section production for both executable and shareable images.

Format

/DEMAND_ZERO (default)

/DEMAND_ZERO[=per_page]

/NODEMAND_ZERO

Qualifier Values

per_page

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 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 image sections. (For more information about demand-zero image section production, see Section 3.4.3.)

If you specify the /NODEMAND_ZERO qualifier, the linker still gathers uninitialized program sections into demand-zero 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 image sections containing the NOMOD program sections into regular image sections and sets the copy-on-reference [CRF] attribute if the write [WRT] attribute is set.)

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

PSECT_ATTR=psect-name,MOD

Note that only language processors can set the NOMOD attribute of a program 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-image-section basis.

$ LINK/NODEMAND_ZERO=PER_PAGE 
 
      

In this example, the linker performs demand zero compression on both a per-image-section basis and a per-page basis.

For Alpha linking, directs the linker to create a file called a debug symbol file (DSF) for use by the OpenVMS Debugger or the OpenVMS Alpha System-Code Debugger.

Format

/DSF[=file-spec]

/NODSF (default)

Qualifier Values

file-spec

Specifies the character string you want the linker to use as the name of the debug symbol file. If you do not include a file type in the character string, the linker appends the .DSF file type to the file name.

If you specify the /DSF qualifier without the file specification, the linker creates a debug symbol file with the file name of the first input file and the default file type .DSF. If you append the /DSF qualifier to one of the input file specifications, the linker creates a debug symbol file with the file name of the file to which the qualifier is appended and with the default file type .DSF.

The OpenVMS Debugger (whether you use it in System-Code Debugger mode or user mode) requires that the name of the DSF file be the same as the name of the image file, except that the file extension is .DSF. If you use an /EXECUTABLE or /SHAREABLE qualifier and a file name with the LINK command, you must also include the same file name with the /DSF qualifier. (You must also use the .DSF file type.)

Description

The /DSF qualifier directs the linker to create a separate file to contain the debug information required by the OpenVMS Alpha System-Code Debugger. The /DSF qualifier can be used with the /NOTRACEBACK qualifier to suppress the appearance of SYS$IMGSTA in the image's transfer array. The /DSF qualifier has no effect on the contents of the image, including the image header.

If you use both /DSF and /DEBUG qualifiers, the debug bit in the image header is set, and SYS$IMGSTA is included in the transfer array; however, no information for the symbolic debugger is included in the image file. The DSF file contains the symbolic debugger information. To use the information in the DSF file when you run the image, you must define the logical name DBG$IMAGE_DSF_PATH to point to disk and directory where the DSF file resides. For more information, see the OpenVMS Debugger Manual.

Example

$ LINK/DSF/NOTRACEBACK MY_PROG.OBJ
      

In this example, the linker will create the files MY_PROG.DSF and MY_PROG.EXE.

Directs the linker to create an executable image, as opposed to a shareable image or a system image.

Format

/EXECUTABLE[=file-spec] (default)

/NOEXECUTABLE

Qualifier Values

file-spec

Specifies the character string you want the linker to use as the name of the image file produced by the link operation. If you do not specify a file type in the character string, the linker assigns the .EXE file type by default.

If you do not specify a file name with the /EXECUTABLE qualifier, the linker creates an executable image with the file name of the first input file. If you append the /EXECUTABLE qualifier to an input file specification, the linker creates an executable image with the file name of the file to which the qualifier is appended.

Description

The /NOEXECUTABLE qualifier directs the linker to perform the linking operation but to not create an image file. Use the /NOEXECUTABLE qualifier to have the linker process the input files you specify without creating an image file to check for errors in your LINK command syntax or other link-time errors. You can also use the linker to produce a map file or symbol table file only by specifying the /NOEXECUTABLE qualifier with the /MAP qualifier or the /SYMBOL_TABLE qualifier.

The linker assumes the /EXECUTABLE qualifier as the default unless you specify the /NOEXECUTABLE qualifier, the /SHAREABLE qualifier, or the /SYSTEM qualifier. Note, however, that when used with the /SYSTEM qualifier, you can use the /EXECUTABLE qualifier to specify the name of a system image.

Examples

$ LINK/NOEXECUTABLE MY_PROG
      

This example directs the linker to link the object module in the file MY_PROG.OBJ without creating an image file.

$ LINK/EXECUTABLE MY_PROG
      

This example directs the linker to produce an executable image named MY_PROG.EXE. (The command line $ LINK MY_PROG will yield the same result because the /EXECUTABLE qualifier is the default.)

$ LINK/EXECUTABLE=MY_IMAGE MY_PROG
      

This example directs the linker to produce an executable image with the name MY_IMAGE.EXE instead of the name MY_PROG.EXE.

	privacy and legal statement
4548PRO_011.HTML