Updated: 11 December 1998

OpenVMS Linker Utility Manual

An executable image is a file that can be executed by the RUN command. An executable image is made up of an image header (which contains image identification information and the image section descriptors [ISDs] that define the memory requirements of the image), a global symbol table, and the executable machine code. An executable image may reference one or more shareable images.

To create an executable image, you can specify the /EXECUTABLE qualifier. Note, however, that the linker creates executable images by default. For example, the command used to create the executable image in Example 1-1 did not specify the /EXECUTABLE qualifier:

$ LINK HELLO

By default, the linker uses the name of the first input file specified as the name of the image file, giving the file the .EXE file type. However, you can alter this default naming convention. For more information, see the LINK command description in Part 2.

1.3.2 Creating a Shareable Image

A shareable image is similar to an executable image except that it cannot be executed from a command line. To run a shareable image, include it in a link operation in which an executable image is created. A shareable image is made up of an image header, a global symbol table, and executable machine code, just as an executable image is.

To create a shareable image, specify the /SHAREABLE qualifier in the LINK command line, as in the following example:

$ LINK/SHAREABLE MY_SHARE, MY_UNIVERSALS/OPT

Note that the preceding LINK command includes the options file MY_UNIVERSALS.OPT. To make symbols in the shareable image available for other modules to link against, you must declare them as universal symbols in a linker options file. The mechanism used to declare universal symbols is different for VAX linking and Alpha linking. For complete information about creating and using shareable images with examples, see Chapter 4.

1.3.3 Creating a System Image

A system image is an image that does not run under the control of the operating system. It is intended for standalone operation only.

By default, system images do not contain an image header as executable images and shareable images do. You can create a system image with a header by specifying the /HEADER qualifier. System images do not contain global symbol tables.

To create a system image, specify the /SYSTEM qualifier in the LINK command line, as in the following example:

$ LINK/SYSTEM MY_SYSTEM_IMAGE

1.3.4 Creating a Symbol Table File

A symbol table file is an object module, produced by the linker, that contains all the global symbol definitions in the image. You can create a symbol table for any type of image: executable, shareable, or system. For executable images and system images, the symbol table contains a listing of the global symbols in the image. For shareable images, the symbol table lists the universal symbols in the image.

For VAX linking, symbol table files can be specified as input files in link operations. For more information, see Section 1.2.4.

For Alpha linking, the symbol table files created by the linker cannot be used as input files in subsequent link operations. Symbol table files are intended to be used with the System Dump Analyzer utility (SDA) as an aid to debugging.

To create a symbol table file, specify the /SYMBOL_TABLE qualifier in the LINK command line. In the following link operation in which an executable image is created, a symbol table file is requested:

$ LINK/SYMBOL_TABLE MY_EXECUTABLE_IMAGE

By default, the linker uses the name of the first input file specified as the name of the symbol table file, giving the file the .STB file type. However, you can alter this default naming convention. For more information, see the description of the /SYMBOL_TABLE qualifier in Part 2.

1.3.5 Creating a Map File

The linker can generate a diagnostic file, called an image map, which you can use to locate link-time errors, to study the image layout, and to keep track of global symbols. The image map provides information about the linking process, including the following types of information:

• A listing of the object modules included in the link operation
• A listing of the image sections created by the linker for the image
• A listing of all the program sections created by the linker
• A listing of all the global and universal symbols resolved by the linker for the image
• A compilation of summary statistics about the link operation

To create an image map file, specify the /MAP qualifier on the LINK command line. In batch mode, the linker creates a map file by default. When you invoke the linker interactively (at the DCL command prompt), you must request a map explicitly. By default, the linker uses the name of the first input file specified as the name of the map file, giving the file the .MAP file type. However, you can alter this default naming convention. For more information, see the LINK command description in Part 2.

For example, to generate a map file in Example 1-1, you would specify the /MAP qualifier as in the following example:

$ LINK/MAP HELLO

You can determine the information contained in the image map by specifying additional qualifiers that are related to the /MAP qualifier. For example, by specifying the /BRIEF qualifier with the /MAP qualifier, you can generate a map file that contains only a subset of the total information that can be returned. For complete information about creating a map file and the contents of a map file, see Chapter 5.

1.3.6 Creating a Debug Symbol File (Alpha Images Only)

For Alpha linking, a debug symbol file (DSF) is a file containing debug information for use by the OpenVMS Alpha System-Code Debugger. To create a debug symbol file, specify the /DSF qualifier in the LINK command line, as in the following example:

$ LINK/DSF MY_PROJ.OBJ

By default, the linker uses the name of the first input file specified as the name of the DSF file, giving the file the .DSF file type. However, you can alter this default naming convention. For more information, see the description of the /DSF qualifier in Part II.

1.4 Optimizing the Performance of Alpha Images

For Alpha linking, the linker performs certain optimizations by default to improve the performance of the images it creates. In addition, you can improve the performance of installed images by installing them as resident images. The following sections describe these optimizations.

1.4.1 Linker Default Image Optimizations (Alpha Images Only)

On Alpha systems, compilers generate a Jump to Subroutine (JSR) instruction sequence to implement procedure calls. The first instruction in this sequence, a Load Quadword (LDQ) instruction, loads the first quadword of the linkage pair into register 26. This quadword contains the code address of the procedure. The second LDQ instruction loads the second quadword of the linkage pair, which contains the address of the routine's procedure descriptor, into register 27. Once the registers have been loaded, the JSR instruction is executed with the contents of register 26 passed as an argument. The following example illustrates the JSR instruction sequence:

LDQ R26,x(LS) ; x(LS) is the code address of the routine to be called LDQ R27,x+8(LS) ; x+8(LS) is the address of the procedure descriptor JSR R26,R26 ;

On Alpha systems, 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 instruction sequence. In a BSR instruction, the destination can be expressed as an offset, requiring fewer memory fetches than a JSR instruction sequence. If you replace the JSR instruction with the BSR instruction, you no longer have to load R26 with the code address.

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 take advantage of this performance enhancement, compilers flag each use of the JSR instruction sequence. The linker examines each use of the JSR instruction sequence and attempts to replace it with the BSR instruction sequence wherever possible. You can prevent the linker from performing code replacement by specifying the /NOREPLACE qualifier. For more information about the /REPLACE qualifier, see Part 2.

When the linker replaces the JSR instruction with a BSR instruction, it also replaces the first LDQ instruction used to load R26 with a BIS instruction because it no longer needs to load R26 with the code address from the linkage pair. Independent of the JSR replacement, the linker also replaces the second LDQ instruction used to load R27 with the procedure descriptor address with a Load Address (LDA) instruction, if possible. The following example illustrates the BSR instruction sequence that replaces the JSR instruction sequence:

BIS R31,R31,R31 ; equivalent to a NOP LDA R27,x(LS) ; x is offset from linkage section to procedure descriptor BSR R26,displ ; branch

When debugging, be aware that instructions you expect to find may have been replaced as follows:

• LDQ replaced with BIS
• LDQ replaced with LDA
• JSR replaced with BSR

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.

1.4.2 Installing Images as Resident Images (Alpha Systems Only)

On Alpha systems, another way to improve the performance of an executable image or a shareable image is to install it as a resident image. The Install utility moves certain portions of resident images into a granularity hint region (GHR) in system space; there, they function as a large single page with granularity hints set, which provides better performance.

To create a resident image, specify the /RESIDENT qualifier on the Install utility command line, as in the following example:

$ INSTALL ADD/RESIDENT MY_PROG.EXE

To create an image that can be installed as a resident image, you must specify both /SECTION_BINDING and /NOTRACEBACK qualifiers in the link operation. When you specify the /SECTION_BINDING qualifier, the linker does not replace JSR instruction sequences with the BSR instruction sequence if the replacement would create a dependency on image section layout. In addition, the linker checks for data references that would create dependencies on the layout of image sections. When it creates an image that can be installed as a resident image, the linker sets a flag in the image header.

For more information, see the descriptions of the /SECTION_BINDING and /TRACEBACK qualifiers in Part 2.

1.5 Controlling a Link Operation

The linker allows you to control various aspects of the link operation by specifying qualifiers and options. The following sections summarize the qualifiers and options supported by the linker. The remaining chapters of this manual describe how to use these qualifiers and options, and Part 2 provides reference information about each linker qualifier and option.

1.5.1 Linker Qualifiers

As with any DCL command, the LINK command supports qualifiers that allow you to control aspects of linker processing. The qualifiers supported by the linker allow you to:

• Identify input files. For example, you must identify library files by appending the /LIBRARY qualifier to the file specification. Section 1.2 describes these qualifiers.
• Specify output files. For example, you must specify the /SHAREABLE qualifier to direct the linker to create a shareable image. Section 1.3 describes these qualifiers.
• Control symbol resolution. For example, if you specify the /NOSYSLIB qualifier, the linker will not process the default system object library or the default system image library. Chapter 2 contains more information about this topic.
• Control image file creation. For example, if you specify the /CONTIGUOUS qualifier, the linker attempts to allocate contiguous disk blocks for the image file. Chapter 3 contains more information about this topic.

Table 1-3 lists the LINK command qualifiers alphabetically.

Table 1-3 Linker Qualifiers

Qualifier	Description
/ALPHA	Directs the linker to build an OpenVMS Alpha image. Section 1.6 describes this qualifier in more detail.
/BPAGE	Specifies the page size the linker should use when creating image sections.
/BRIEF	Directs the linker to create a brief image map. Must be specified with the /MAP qualifier.
/CONTIGUOUS	Directs the linker to attempt to store the output image in contiguous disk blocks.
/CROSS_REFERENCE	Directs the linker to replace the Symbols By Name section of the image map with the Symbol Cross-Reference section. Must be specified with the /MAP qualifier.
/DEBUG	Directs the linker to generate a debugger symbol table and to give control to the OpenVMS Debugger when the image is run.
++/DEMAND_ZERO	Controls how the linker creates demand-zero image sections in Alpha images. Not supported for VAX linking.
++/DSF	Directs the linker to create a file called a debug symbol file (DSF) for use by the OpenVMS Alpha System-Code Debugger.
/EXECUTABLE	Directs the linker to create an executable image.
/FULL	Directs the linker to create a full image map. Used only with the /MAP qualifier.
++/GST	Directs the linker to include symbols that have been declared universal in the global symbol table (GST) of a shareable image. Not supported for VAX linking.
/HEADER	Directs the linker to include an image header in a system image. Used only with the /SYSTEM qualifier.
/INCLUDE	Identifies the input file to which it is appended as a library file and directs the linker to include specific modules from the library in the link operation.
/LIBRARY	Identifies the input file to which it is appended as a library file.
/MAP	Directs the linker to create an image map.
++/NATIVE_ONLY	Directs the linker to create an Alpha image that cannot operate with a translated VAX image. Not supported for VAX linking.
/OPTIONS	Identifies an input file as a linker options file.
/P0IMAGE	Directs the linker to mark the specified executable image as one that can run only in P0 address space.
/PROTECT	Directs the linker to protect the shareable image from user-mode and supervisor-mode write access. Used with the /SHAREABLE qualifier when the linker creates a shareable image.
++/REPLACE	Directs the linker to perform certain optimizations that improve the performance of the resultant image. Not supported for VAX linking.
++/SECTION_BINDING	Directs the linker to check if the image contains dependencies on the layout of image sections that could interfere with a performance enhancement the Install utility can perform on images that are installed as resident images. Not supported for VAX linking.
/SELECTIVE_SEARCH	Directs the linker to include in the image's global symbol table (GST) only those global symbols that are defined in the file and referenced by previously processed files.
/SHAREABLE	Directs the linker to create a shareable image. It can also be used to identify an input file as a shareable image.
/SYMBOL_TABLE	Directs the linker to create a symbol table file.
++/SYSEXE	Directs the linker to process the OpenVMS Alpha executive file SYS$BASE_IMAGE.EXE (located in the directory pointed to by the logical name ALPHA$LOADABLE_IMAGES) to resolve references to symbols in a link operation. Not supported for VAX images.
/SYSLIB	Directs the linker to search the default system image library and the default system object library to resolve undefined symbolic references.
/SYSSHR	Directs the linker to search the default system shareable image library to resolve undefined symbolic references.
/SYSTEM	Directs the linker to create a system image.
/THREADS_ENABLE	Allows you to turn kernel threads on and off on a per-image basis.
/TRACEBACK	Directs the linker to include tracebacK information in the image.
/USERLIBRARY	Directs the linker to search default user libraries to resolve undefined symbolic references. /USERLIBRARY accepts a keyword (ALL, GROUP, PROCESS, SYSTEM, or NONE) to further specify which logical name tables to search for the definitions of default user libraries.
/VAX	Directs the linker to build an OpenVMS VAX image. Section 1.6 describes this qualifier in more detail.

In addition to qualifiers, the linker supports options that allow you to control other aspects of a link operation, such as the following:

• Specify image identification information. Using options such as NAME=, ID=, and GSMATCH=, you can supply values for fields in the image header.
• Declare universal symbols in shareable images. Using the UNIVERSAL= option for VAX linking and the SYMBOL_VECTOR= option for Alpha linking, you can make symbols in shareable images accessible to external modules.
• Group input files together. Using the CLUSTER= option or the COLLECT= option, you can specify which input files (or program sections in those input files) the linker should group together. This can affect symbol resolution.

Note that linker options must be specified in a linker options file. (See Section 1.2.5 for information about creating linker options files and specifying them in link operations.)

Table 1-4 lists all the linker options alphabetically.

Table 1-4 Linker Options

Option	Description
+BASE=	Sets the base virtual address for the image. Not supported for Alpha linking.
CASE_SENSITIVE=	Determines whether the linker preserves the mixture of uppercase and lowercase characters used in arguments to linker options.
CLUSTER=	Directs the linker to create a cluster, assign the cluster the name specified, and insert the input files specified in the cluster.
COLLECT=	Moves the specified program sections into the specified cluster.
DZRO_MIN=	Sets the minimum number of uninitialized, contiguous pages that must be found in an image section before the linker can extract the pages from the image section and create a demand-zero image section.
GSMATCH=	Sets match control parameters for a shareable image.
IDENTIFICATION=	Sets the image ID field in the image header.
IOSEGMENT=	Specifies the size of the image I/O segment.
ISD_MAX=	Specifies the maximum number of image sections.
NAME=	Sets the image name field in the image header.
PROTECT=	Directs the linker to protect one or more clusters from user-mode or supervisor-mode write access. Can be used only with shareable images.
PSECT_ATTR=	Assigns values to program section attributes.
STACK=	Sets the initial size of the user-mode stack.
SYMBOL=	Defines a global symbol and assigns it a value.
++SYMBOL_TABLE=	Specifies whether a symbol table file, produced in a link operation in which a shareable image is created, should contain all the global symbols as well as the universal symbols in the shareable image. By default, the linker includes only universal symbols. Not supported for VAX images.
++SYMBOL_VECTOR=	Declares a symbol in a shareable image as universal, making it accessible to external modules. Not supported for VAX images.
+UNIVERSAL=	Declares the specified global symbol as a universal symbol, making it accessible to external modules. Not supported for Alpha images.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4548PRO_002.HTML