HP OpenVMS Systems Documentation

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

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.

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.