HP OpenVMS Linker Utility Manual

1.3 Specifying Linker Output Files

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.

Table 1-2 Output Files Generated by the Linker
File Default
File Type Description

Executable image .EXE A program that can be run at the command line. This image is the default output file created by the linker. Specify the /EXECUTABLE qualifier to create an executable image.

Shareable image .EXE A collection of procedures and data that usually can be referenced after being included in a link operation in which another image is created. Specify the /SHAREABLE qualifier to create a shareable image.

System image ¹ .EXE A program that is meant to be run as a standalone system. Specify the /SYSTEM qualifier to create a system image.

Symbol table file .STB An object module containing the global symbol table from an executable or system image, or the universal symbol table from a shareable image. Specify the /SYMBOL_TABLE qualifier to create a symbol table file.

Map file .MAP A text file created by the linker that provides information about the layout of the image and statistics about the link operation. Specify the /MAP qualifier to create a map file.

Debug symbol file ² .DSF A file containing debug information for use by the OpenVMS Debugger or System Code Debugger. Specify the /DSF qualifier to create a debug symbol file.
See HP OpenVMS Debugger Manual and Writing OpenVMS Alpha Device Drivers in C for guidelines on using the system code debugger.

**Table 1-2 Output Files Generated by the Linker**
File	Default File Type	Description
Executable image	.EXE	A program that can be run at the command line. This image is the default output file created by the linker. Specify the /EXECUTABLE qualifier to create an executable image.
Shareable image	.EXE	A collection of procedures and data that usually can be referenced after being included in a link operation in which another image is created. Specify the /SHAREABLE qualifier to create a shareable image.
System image ¹	.EXE	A program that is meant to be run as a standalone system. Specify the /SYSTEM qualifier to create a system image.
Symbol table file	.STB	An object module containing the global symbol table from an executable or system image, or the universal symbol table from a shareable image. Specify the /SYMBOL_TABLE qualifier to create a symbol table file.
Map file	.MAP	A text file created by the linker that provides information about the layout of the image and statistics about the link operation. Specify the /MAP qualifier to create a map file.
Debug symbol file ²	.DSF	A file containing debug information for use by the OpenVMS Debugger or System Code Debugger. Specify the /DSF qualifier to create a debug symbol file. See HP OpenVMS Debugger Manual and Writing OpenVMS Alpha Device Drivers in C for guidelines on using the system code debugger.

¹Alpha and VAX specific.
²I64 and Alpha specific.
³I64 specific.

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) $

1.3.3 Creating a System Image (Alpha and VAX)

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

1.3.4 Creating a Symbol Table File

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.

Table 1-3 Linker Qualifiers
Qualifier Supported Platform Description

/ALPHA Alpha, VAX Directs the linker to build an OpenVMS Alpha image. Section 1.5 describes this qualifier in more detail.

/BASE_ADDRESS I64 Directs the linker to suggest a starting address for an executable image, when used in the boot process. This starting address is ignored by the image activator.

/BPAGE I64, Alpha, VAX Specifies the page size the linker should use when creating image sections or segments.

/BRIEF I64, Alpha, VAX Directs the linker to create a brief image map. Must be specified with the /MAP qualifier.

/CONTIGUOUS I64, Alpha, VAX Directs the linker to attempt to store the output image in contiguous disk blocks.

/CROSS_REFERENCE I64, Alpha, VAX 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 I64, Alpha, VAX Directs the linker to include debug information in the image and to give control to the OpenVMS Debugger when the image is run.

/DEMAND_ZERO I64, Alpha Controls how the linker creates demand-zero image sections or segments.

/DNI I64 Controls the processing of demangling information.

/DSF I64, Alpha Directs the linker to create a file called a debug symbol file (DSF) for use by OpenVMS debuggers.

/EXECUTABLE I64, Alpha, VAX Directs the linker to create an executable image.

/FP_MODE I64 Directs the linker to set the program's initial floating-point mode in case it was not supplied by the main module.

/FULL I64, Alpha, VAX Directs the linker to create a full image map. Used only with the /MAP qualifier.

/GST I64, Alpha Directs the linker to include symbols that have been declared universal in the global symbol table (GST) of a shareable image. Use /NOGST to create an image with an empty GST. As such, /NOGST allows you to ship a shareable image that cannot be linked against. This qualifier is not supported for VAX linking.

/HEADER I64, Alpha, VAX Directs the linker to include an image header in a system image. Used only with the /SYSTEM qualifier. Accepted on I64 but not processed.

/INCLUDE I64, Alpha, VAX 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.

/INFORMATIONALS I64, Alpha, VAX Directs the linker to output informational messages produced by a link operation. /NOINFORMATIONALS directs the linker to suppress informational messages.

/LIBRARY I64, Alpha, VAX Identifies the input file to which it is appended as a library file.

/MAP I64, Alpha, VAX Directs the linker to create an image map.

/NATIVE_ONLY I64, Alpha Directs the linker to create an image that cannot operate with a translated OpenVMS image.

/OPTIONS I64, Alpha, VAX Identifies an input file as a linker options file.

/P0IMAGE I64, Alpha, VAX Directs the linker to mark the specified executable image as one that can run only in P0 address space.

/PROTECT I64, Alpha, VAX 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 Alpha Directs the linker to perform certain optimizations that improve the performance of the resulting image.

/SECTION_BINDING Alpha Directs the linker to check whether the image to be created contains dependencies on the layout of image sections that could interfere with the performance enhancement if installed resident.

/SEGMENT_ATTRIBUTE I64 Directs the linker to set attributes for image segments.

/SELECTIVE_SEARCH I64, Alpha, VAX Directs the linker to include only those global symbols that are defined in the module or image and referenced by previously processed modules.

/SHAREABLE I64, Alpha, VAX Directs the linker to create a shareable image. Can also be used to identify an input file as a shareable image.

/SYMBOL_TABLE I64, Alpha, VAX Directs the linker to create a symbol table file.

/SYSEXE I64,Alpha Directs the linker to process the OpenVMS executive file SYS$BASE_IMAGE.EXE (located in the directory pointed to by the logical name IA64$LOADABLE_IMAGES or ALPHA$LOADABLE_IMAGES) to resolve references to symbols in a link operation.

/SYSLIB I64, Alpha, VAX Directs the linker to search the default system image library and the default system object library to resolve undefined symbolic references.

/SYSSHR I64, Alpha, VAX Directs the linker to search the default system shareable image library to resolve undefined symbolic references.

/SYSTEM Alpha,VAX Directs the linker to create a system image.

/THREADS_ENABLE I64, Alpha, VAX Directs the linker to enable features of the thread environment, in which the generated image is activated.

/TRACEBACK I64, Alpha, VAX Directs the linker to include traceback information in the image.

/USERLIBRARY I64, Alpha, VAX 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 Alpha, VAX Directs the linker to build an OpenVMS VAX image. Section 1.5 describes this qualifier in more detail.

**Table 1-3 Linker Qualifiers**
Qualifier	Supported Platform	Description
/ALPHA	Alpha, VAX	Directs the linker to build an OpenVMS Alpha image. Section 1.5 describes this qualifier in more detail.
/BASE_ADDRESS	I64	Directs the linker to suggest a starting address for an executable image, when used in the boot process. This starting address is ignored by the image activator.
/BPAGE	I64, Alpha, VAX	Specifies the page size the linker should use when creating image sections or segments.
/BRIEF	I64, Alpha, VAX	Directs the linker to create a brief image map. Must be specified with the /MAP qualifier.
/CONTIGUOUS	I64, Alpha, VAX	Directs the linker to attempt to store the output image in contiguous disk blocks.
/CROSS_REFERENCE	I64, Alpha, VAX	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	I64, Alpha, VAX	Directs the linker to include debug information in the image and to give control to the OpenVMS Debugger when the image is run.
/DEMAND_ZERO	I64, Alpha	Controls how the linker creates demand-zero image sections or segments.
/DNI	I64	Controls the processing of demangling information.
/DSF	I64, Alpha	Directs the linker to create a file called a debug symbol file (DSF) for use by OpenVMS debuggers.
/EXECUTABLE	I64, Alpha, VAX	Directs the linker to create an executable image.
/FP_MODE	I64	Directs the linker to set the program's initial floating-point mode in case it was not supplied by the main module.
/FULL	I64, Alpha, VAX	Directs the linker to create a full image map. Used only with the /MAP qualifier.
/GST	I64, Alpha	Directs the linker to include symbols that have been declared universal in the global symbol table (GST) of a shareable image. Use /NOGST to create an image with an empty GST. As such, /NOGST allows you to ship a shareable image that cannot be linked against. This qualifier is not supported for VAX linking.
/HEADER	I64, Alpha, VAX	Directs the linker to include an image header in a system image. Used only with the /SYSTEM qualifier. Accepted on I64 but not processed.
/INCLUDE	I64, Alpha, VAX	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.
/INFORMATIONALS	I64, Alpha, VAX	Directs the linker to output informational messages produced by a link operation. /NOINFORMATIONALS directs the linker to suppress informational messages.
/LIBRARY	I64, Alpha, VAX	Identifies the input file to which it is appended as a library file.
/MAP	I64, Alpha, VAX	Directs the linker to create an image map.
/NATIVE_ONLY	I64, Alpha	Directs the linker to create an image that cannot operate with a translated OpenVMS image.
/OPTIONS	I64, Alpha, VAX	Identifies an input file as a linker options file.
/P0IMAGE	I64, Alpha, VAX	Directs the linker to mark the specified executable image as one that can run only in P0 address space.
/PROTECT	I64, Alpha, VAX	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	Alpha	Directs the linker to perform certain optimizations that improve the performance of the resulting image.
/SECTION_BINDING	Alpha	Directs the linker to check whether the image to be created contains dependencies on the layout of image sections that could interfere with the performance enhancement if installed resident.
/SEGMENT_ATTRIBUTE	I64	Directs the linker to set attributes for image segments.
/SELECTIVE_SEARCH	I64, Alpha, VAX	Directs the linker to include only those global symbols that are defined in the module or image and referenced by previously processed modules.
/SHAREABLE	I64, Alpha, VAX	Directs the linker to create a shareable image. Can also be used to identify an input file as a shareable image.
/SYMBOL_TABLE	I64, Alpha, VAX	Directs the linker to create a symbol table file.
/SYSEXE	I64,Alpha	Directs the linker to process the OpenVMS executive file SYS$BASE_IMAGE.EXE (located in the directory pointed to by the logical name IA64$LOADABLE_IMAGES or ALPHA$LOADABLE_IMAGES) to resolve references to symbols in a link operation.
/SYSLIB	I64, Alpha, VAX	Directs the linker to search the default system image library and the default system object library to resolve undefined symbolic references.
/SYSSHR	I64, Alpha, VAX	Directs the linker to search the default system shareable image library to resolve undefined symbolic references.
/SYSTEM	Alpha,VAX	Directs the linker to create a system image.
/THREADS_ENABLE	I64, Alpha, VAX	Directs the linker to enable features of the thread environment, in which the generated image is activated.
/TRACEBACK	I64, Alpha, VAX	Directs the linker to include traceback information in the image.
/USERLIBRARY	I64, Alpha, VAX	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	Alpha, VAX	Directs the linker to build an OpenVMS VAX image. Section 1.5 describes this qualifier in more detail.

1.4.2 Link Options

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.

Table 1-4 Linker Options
Option Supported Platform Description

BASE= VAX Sets the base virtual address for the image.

CASE_SENSITIVE= I64, Alpha, VAX Determines whether the linker preserves the mixture of uppercase and lowercase characters used in arguments to linker options.

CLUSTER= I64, Alpha, VAX Directs the linker to create a cluster and to assign the cluster the specified name, and insert the input files specified in the cluster. Note that the base-address option value, which specifies the virtual address for the cluster, is valid on VAX, valid on Alpha for executable images only, and not accepted on I64. See the reference section CLUSTER= option for information about this and other option values.

COLLECT= I64, Alpha, VAX Moves the specified program sections into the specified cluster.

DZRO_MIN= Alpha, VAX 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= I64, Alpha, VAX Sets match control parameters for a shareable image.

IDENTIFICATION= I64, Alpha, VAX Sets the image ID field.

IOSEGMENT= I64, Alpha, VAX Specifies the size of the image I/O segment.

ISD_MAX= Alpha, VAX Specifies the maximum number of image sections.

NAME= I64, Alpha, VAX Sets the image name field.

PROTECT= I64, Alpha, VAX 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= I64, Alpha, VAX Assigns values and attributes to program sections.

RMS_RELATED_CONTEXT= I64, Alpha, VAX Determines RMS related-name context processing, also known as file specification "stickiness."

STACK= I64, Alpha, VAX Sets the initial size of the user-mode stack.

SYMBOL= I64, Alpha, VAX Defines a global symbol and assigns it a value.

SYMBOL_TABLE= I64, Alpha 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.

SYMBOL_VECTOR= I64, Alpha Exports symbols in a shareable image, making them accessible to external images.

UNIVERSAL= VAX Declares the specified global symbol as a universal symbol, making it accessible to external images.

**Table 1-4 Linker Options**
Option	Supported Platform	Description
BASE=	VAX	Sets the base virtual address for the image.
CASE_SENSITIVE=	I64, Alpha, VAX	Determines whether the linker preserves the mixture of uppercase and lowercase characters used in arguments to linker options.
CLUSTER=	I64, Alpha, VAX	Directs the linker to create a cluster and to assign the cluster the specified name, and insert the input files specified in the cluster. Note that the base-address option value, which specifies the virtual address for the cluster, is valid on VAX, valid on Alpha for executable images only, and not accepted on I64. See the reference section CLUSTER= option for information about this and other option values.
COLLECT=	I64, Alpha, VAX	Moves the specified program sections into the specified cluster.
DZRO_MIN=	Alpha, VAX	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=	I64, Alpha, VAX	Sets match control parameters for a shareable image.
IDENTIFICATION=	I64, Alpha, VAX	Sets the image ID field.
IOSEGMENT=	I64, Alpha, VAX	Specifies the size of the image I/O segment.
ISD_MAX=	Alpha, VAX	Specifies the maximum number of image sections.
NAME=	I64, Alpha, VAX	Sets the image name field.
PROTECT=	I64, Alpha, VAX	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=	I64, Alpha, VAX	Assigns values and attributes to program sections.
RMS_RELATED_CONTEXT=	I64, Alpha, VAX	Determines RMS related-name context processing, also known as file specification "stickiness."
STACK=	I64, Alpha, VAX	Sets the initial size of the user-mode stack.
SYMBOL=	I64, Alpha, VAX	Defines a global symbol and assigns it a value.
SYMBOL_TABLE=	I64, Alpha	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.
SYMBOL_VECTOR=	I64, Alpha	Exports symbols in a shareable image, making them accessible to external images.
UNIVERSAL=	VAX	Declares the specified global symbol as a universal symbol, making it accessible to external images.

Contents

Index