HP OpenVMS Systems Documentation

HP OpenVMS Linker Utility Manual

The primary output generated by the linker is an image file. In addition, the linker can generate other output files:

• On all platforms, a symbol table file and a map file
• On I64 and Alpha systems, a debug symbol file

Table 1-2 lists all the output files created by the linker.

You cannot examine an image file using a text editor. To examine an image file, check for errors in image format, and obtain other information about the image, you must use the ANALYZE/IMAGE utility. See the HP OpenVMS DCL Dictionary for information about using this utility.

The following sections describe each of the output files.

1.3.1 Creating an Executable Image

An executable image is a file that can be executed by the RUN command.

On I64 systems, an executable image conforms to the ELF specification. Typically, this image consists of header tables, note sections containing the image identification information, a dynamic segment containing the image activation information and shareable image dependencies, and program segments containing the image binaries that define the memory requirements of the image.

Alpha and VAX images are usually made up of an image header which contains image identification information and the image section descriptors (ISDs) that define the memory requirements and shareable image dependencies of the image binaries.

An executable image can 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 4.

1.3.2 Creating a Shareable Image

A shareable image is similar in structure and content to an executable image, though it differs in the way that shareable program sections are sorted. To make use of a shareable image, include it in a link operation in which another image is created.

In I64 images, the symbol table is an ELF section that contains the symbol information. In Alpha and VAX images, the symbol table resembles an appended object module that only contains the symbol information.

Note that the following LINK command includes an options file using SYS$INPUT. To make symbols in the shareable image available for other images to link against, you must declare them as universal symbols in a linker options file. The mechanism used to declare universal symbols for I64 and Alpha linking differs from VAX linking. For information and examples about creating and using shareable images, see Chapter 8.

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

$ LINK/SHAREABLE MY_SHARE, SYS$INPUT/OPTIONS
SYMBOL_VECTOR=(-
MY_ROUTINE=PROCEDURE,-
MY_COUNTER=DATA)
$

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

On I64 systems, system images that have no special format; they are simply OpenVMS images that conform to the ELF specification. These system images might have constraints that you may have to address (for example, limits to the number of program segments).

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

To create an Alpha or VAX 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 like an object module 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 I64 and Alpha linking, the symbol table files created by the linker cannot be used as input files in subsequent link operations.

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

On all platforms, symbol table files are intended to be used with 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 4.

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 segments (I64) or image sections (Alpha and VAX) 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 4.

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 information about creating a map file and the contents of a map file on I64, see Chapter 5. For information about creating a map file and the contents of a map file on Alpha and VAX, see Chapter 9.

1.3.6 Creating a Debug Symbol File (I64 and Alpha)

For I64 and Alpha linking, a debug symbol file (DSF) is a file containing debug information for use by the OpenVMS Debugger and the System Code Debugger (SCD). 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 IV.

1.4 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 4 provides reference information about each linker qualifier and option.

1.4.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 (I64) and Chapter 6 (Alpha and VAX) contain 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 (I64) and Chapter 7 (Alpha and VAX) contain 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 to identify the image.
• Declare universal symbols in shareable images. Using the UNIVERSAL= option for VAX linking and the SYMBOL_VECTOR= option for I64 and 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 the order of module processing and, therefore, 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.