Updated: 11 December 1998

OpenVMS Linker Utility Manual

When a language processor translates a source language program, it produces an output file that contains one or more object modules. This output file, called an object file, has the default file type of .OBJ and is the primary form of linker input. At least one object file must be specified in any link operation. An object file may be specified in the command line or in an options file.

For example, in Example 1-1, the only input file specified on the LINK command line is the object module named HELLO.OBJ (the .OBJ file type does not need to be specified because it is the default):

$ LINK HELLO

An object module is comprised of a module header, global symbol directory (GSD) records, and text and information relocation commands. Language processors list the symbols defined externally to the module in the GSD. An object module is terminated by an end-of-module (EOM) record. A module can also contain debugger information and traceback information.

The linker processes the entire contents of an object file, that is, every object module in the file. It cannot selectively process object modules within an object file. The linker can process object modules selectively in an object module library (.OLB) file only.

You cannot examine an object module by using a text editor. The only way to examine an object file is by using the ANALYZE/OBJECT utility. This utility produces a report that lists the records that make up the object module. This report is primarily useful to compiler writers. (For information about using the ANALYZE command, see the OpenVMS DCL Dictionary.)

1.2.2 Shareable Images as Linker Input Files

A shareable image is the product of a link operation. A shareable image is not directly executable, that is, it cannot be executed by means of the DCL command RUN. To execute, a shareable image must first be included as input in a link operation that produces an executable image. (You can also activate a shareable image dynamically by using the LIB$FIND_IMAGE_SYMBOL routine. For more information, see the OpenVMS RTL Library (LIB$) Manual.) When that executable image is run, the shareable image is also activated by the image activator.

A shareable image file consists of an image header, one or more image sections, and a symbol table, which appears at the end of the file. This symbol table is, in fact, an object module whose records contain definitions of universal symbols in the shareable image. A universal symbol is to a shareable image what a global symbol is to a module, that is, it is a symbol that can be used to satisfy references in external modules.

Shareable images can provide the following benefits:

• Reducing total link processing time. Because the linker needs only to read the image header and to process the global symbol table in a shareable image, it takes less time for the linker to process a shareable image. The linker does not have to resolve symbolic references within the shareable image, sort program sections into image sections, or initialize the image section contents, as it does when processing object modules.
• Avoiding relinking entire applications. You can create a shareable image that can be modified, recompiled, and relinked without causing the images that were linked against previous versions of the shareable image to be relinked. This is called upward compatibility. For more information about this topic, see Chapter 4.
• Conserving disk space. Because many different executable images can be linked against the same shareable image, it is necessary to keep only a single copy of the shareable image on the disk. (Images that are linked with shareable images do not actually contain a copy of the shareable image.)
• Conserving physical memory. Because the system can map the shareable pages of an installed shareable image into the address space of many processes, each process does not need to have its own copy of these pages. Note that, to achieve this benefit, the shareable image must be installed using the Install utility, specifying the /SHARED qualifier.
• Reduction of paging I/O. Because a page in an installed shareable image may be mapped into the working set of several processes, it is more likely to be in physical memory, reducing paging I/O. Note that, to achieve this benefit, the shareable image must be installed using the Install utility, specifying the /SHARED qualifier.
• Implementing memory-resident databases. Because installed shareable images are memory resident, they simplify the implementation of applications, such as data acquisition and control systems, where response times are so critical that control variables and data readings must remain in main memory.
  For example, a shared database may be a named FORTRAN common block built into a shareable image. The shareable image may also include routines to synchronize access to such data. When applications link with the shareable image, they have easy access to the data (and routines).
  Note that, to achieve this benefit, the shareable image must be installed using the Install utility, specifying the /SHARED qualifier. If the shared database is writable, you must also specify the /WRITE qualifier.

To include a shareable image in a link operation, you must specify the shareable image in an options file, identifying the input file as a shareable image by appending the /SHAREABLE qualifier to the file specification. You cannot specify a shareable image as an input file on the LINK command line. The following example illustrates an options file, named MY_OPTIONS_FILE.OPT, that contains an input file specification of the shareable image (the .EXE file type does not need to be specified because it is the default):

MY_SHARE/SHAREABLE

The following example illustrates the LINK command in which the options file is specified. (For more information about creating and using shareable images, see Chapter 4.) Note that the default file types for the options file and the object module do not need to be specified.

$ LINK MY_MAIN_PROGRAM,MY_OPTIONS_FILE/OPTIONS

By default, if you do not specify the device and directory in the file specification, the linker looks for shareable images in your default device and directory.

You link against shareable images in a shareable image library by specifying the library on the LINK command line or in a linker options file, identifying the file as a library by appending the /LIBRARY qualifier to the library file specification. You can include specific shareable images from the library in the link operation by appending the /INCLUDE qualifier to the library file specification, specifying which shareable images you want to include as parameters. (For more information about specifying library files in a link operation, see Section 1.2.3). By default, the linker looks for user library files in the current default directory.

Note that images that link against shareable images do not contain the shareable image but only a reference to it. When the executable image is activated, the image activator activates all the shareable images to which it has been linked. By default, each image maps its own copy of the shareable image's pages.

1.2.2.2 Installing a Shareable Image

If you install the shareable image (using the Install utility), all processes can share the same physical copy of the shareable image in memory. To take advantage of this feature, you must specify the ADD subcommand and the /SHARED qualifier on the INSTALL command line, as in the following example:

$ INSTALL ADD/SHARED WORK:[PROGRAMS]MY_SHARE.EXE

The system creates a set of global sections for those image sections in the shareable image that can be shared. The system can map these global sections into the address space of multiple processes. For those image sections that are not shareable (image sections with the copy-on-reference [CRF] attribute), each process gets a private copy. (See Chapter 3 for more information about program section and image section attributes.)

If you do not install the shareable image specifying the /SHARED qualifier, each process receives a private copy of the image. (For information about installing images, see the OpenVMS System Manager's Manual.)

1.2.3 Library Files as Linker Input Files

A library file is a file produced by the Librarian utility (default file type is .OLB). The linker accepts object module libraries and shareable image libraries as input files.

1.2.3.1 Creating a Library File

You create a library by specifying the /CREATE qualifier with the LIBRARY command. In the following example, the object module MY_PROG.OBJ is inserted into the library MY_LIB.OLB:

$ LIBRARY/CREATE/INSERT MY_LIB MY_PROG

A library file contains a library header and a name table. A library name table lists all of the global symbols in all of the modules inserted in the library and associates the name of the symbol with the name of the module in which it is defined.

Object module libraries contain copies of the object module. Shareable image libraries do not contain the actual shareable image or a copy of its global symbol table (GST). Instead, shareable image libraries contain only the name of the shareable image that contains the definition. The linker looks for the shareable image in the device and directory in which the library resides. If the linker cannot find the shareable image at this location, it looks in the directory pointed to by the logical name SYS$LIBRARY for VAX links or ALPHA$LIBRARY for Alpha links.

You cannot examine a library file using a text editor. To find out which modules a library contains, invoke the Librarian utility with the /LIST qualifier. The Librarian utility lists the symbols defined in these modules if you also specify the /NAMES qualifier. In the following example, the library MYMATH_LIB.OLB contains the object module MYMATHROUTS.OBJ, which contains the definitions of the symbols myadd, mysub, mydiv, and mymul:

$ LIBRARIAN/LIST/NAMES MYMATH_LIB Directory of OBJECT library WORK:[PROGS]MYMATH_LIB.OLB;1 on 3-SEP-1996 08:39:27 Creation date: 3-SEP-1996 08:39:05 Creator: VAX-11 Librarian V04-00 Revision date: 3-SEP-1996 08:39:05 Library format: 3.0 Number of modules: 1 Max. key length: 31 Other entries: 4 Preallocated index blocks: 49 Recoverable deleted blocks: 0 Total index blocks used: 2 Max. Number history records: 20 Library history records: 0 Module MYMATHROUTS MYADD MYDIV MYMUL MYSUB

For more information about creating and using libraries, see the OpenVMS Command Definition, Librarian, and Message Utilities Manual.

1.2.3.2 Including a Library File in a Link Operation

You can specify a library file in a link operation in any of the following ways:

• Using the /LIBRARY qualifier. You can specify a library file on the LINK command line or in an options file, identifying the input file as a library by appending the /LIBRARY qualifier.
  When the linker processes a library file, it searches the library's name table for the definitions of symbols referenced in the other input files it has processed previously in the link operation. (Note that the order in which the linker processes a library file can affect symbol resolution. For more information, see Chapter 2.)
  When the linker finds the definition of a symbol in the library's name table, it includes the module that contains the definition in the link operation and processes it as it would any other object module or shareable image. For object module libraries, the linker extracts the object module from the library. The linker looks for the shareable image in the device and directory in which the library resides. If the linker cannot find the shareable image at this location, it looks in the directory pointed to by the logical name SYS$LIBRARY for VAX links or ALPHA$LIBRARY for Alpha links.
• Using the /INCLUDE qualifier. You can include specific modules from a library into a link operation by appending the /INCLUDE qualifier to the library file specification. You specify the modules you want included in the link operation as arguments to the qualifier.
  Note, however, that the linker does not process the name table of a library file specified using the /INCLUDE qualifier. The linker includes from the library the modules specified as arguments to the /INCLUDE qualifier into the link operation and processes them as it would any other object module or shareable image.
  If you append both the /LIBRARY qualifier and the /INCLUDE qualifier to a library file specification, the linker processes the library's name table and also includes the specified modules in the link operation.
• Defining the library as a default user library. You can include a library in a link operation by defining it as a default user library. To define a default user library, assign the name of the library as the value of one of the linker's LNK$LIBRARY logical names. The linker processes libraries pointed to by these logicals after processing all the other input files specified in the link operation. See Section 2.2.3.3 for more information about default library processing.

The example link of the Hello World! program in Section 1.1.2 included the C run-time library in the link operation as a default library.

1.2.4 Symbol Table Files as Linker Input Files

A symbol table file is the product of a previous link operation or a language processor. A symbol table file is an object module that contains only an object module header, a global symbol directory (GSD), and an end-of-module record.

For VAX linking, you can specify a symbol table file as input in a link operation as you would any other object module, as in the following example:

$ LINK MY_MAIN_PROGRAM, MY_SYMBOL_TABLE

The linker processes the GSD of the symbol table file during symbol resolution. If the symbol table file was the by-product of a link operation in which an executable image or system image was created, the GSD contains the names and values of every global symbol in the image. If the symbol table file is associated with a shareable image, it contains the names and values of the symbols in the image declared as universal.

Note that, for a symbol table file to be useful in link operations, the values associated with the symbols in the symbol table file must be constants. The value of symbols that represent addresses, such as a procedure entry point, can vary each time the image is activated (unless the image is based).

Note also that a symbol table file associated with a shareable image should not be specified as an input file in a link operation in place of the shareable image. The shareable image itself must be specified as input because the linker requires more information than can be found in a symbol table file, such as the memory requirements of the shareable image (contained in the image header).

For Alpha linking, symbol table files created by the linker cannot be used as input files in a link operation. A symbol table in an OpenVMS Alpha shareable image does not contain the actual value of a symbol, even for symbols that represent constants. Instead, the symbol table file contains the offset of the symbol's entry in the image's symbol vector.

For example, if the symbol FOO represents the constant 6000, in a VAX image the value of FOO in the symbol table file would be 6000. In an Alpha image, the value of FOO in the symbol table file would not be 6000 but another value that represented the symbol's position in the symbol vector as an offset from the base of the symbol vector, such as 48. This entry in the symbol vector contains the value 6000.

Symbol table files created by the linker during Alpha links can be used as an aid to debugging a module with the System Dump Analyzer utility (SDA).

1.2.5 Options Files as Linker Input Files

An options file is a standard text file you must use to specify linker options and shareable images specified as input files. You cannot specify linker options or shareable images on the LINK command line. Linker options, similar to linker qualifiers, allow you to control various aspects of the linker operation. Part 2 includes reference descriptions of all the options supported by the linker.

In addition, you can use options files to perform the following tasks:

• Specifying frequently used input file specifications
• Entering LINK commands that may exceed the buffer capacity of the command language interpreter (256 characters)

When creating a linker options file, keep in mind the following restrictions:

• Separate input file specifications with a comma (,).
• Do not enter any linker qualifiers except those required to identify input files, such as the /LIBRARY or /SHAREABLE qualifier.
• Do not specify an options file within an options file.
• Enter only one option per line.
• Continue a line by entering the continuation character (the hyphen [-]) at the end of the line.
• Enter comments after an exclamation point (!).
• You may abbreviate the name of a link option to as few letters as needed to make the abbreviation unique.

Example 1-2 illustrates an options file, named PROJECT3.OPT, that contains both input file specifications and linker options.

Example 1-2 Sample Linker Options File

MOD1,MOD7,LIB3/LIBRARY,- LIB4/LIBRARY/INCLUDE=(MODX,MODY,MODZ),- MOD12/SELECTIVE_SEARCH STACK=75 SYMBOL=JOBCODE,5

To use an options file in a link operation, specify the name of the options file on the command line, identifying the file as an options file by appending the linker qualifier /OPTIONS to the file specification (the .OPT file type does not need to be specified because it is the default), as in the following example:

$ LINK PROGA,PROGB,PROJECT3/OPTIONS

If you precede the link operation with the SET VERIFY command, DCL displays the contents of the options file as the file is processed.

If you want to use an options file in a command procedure or interactively on the command line, specify the input file as the logical name SYS$INPUT, appending the /OPTIONS qualifier to the logical name. DCL interprets the lines immediately following the LINK command as the contents of the options file. The following example illustrates a LINK command in a command procedure:

$ ! LIN command $ LINK MAIN,SUB1,SYS$INPUT/OPTIONS MYPROC/SHAREABLE SYS$LIBRARY:APPLPCKGE/SHAREABLE STACK=75 $

When you specify SYS$INPUT to create an options file interactively on the command line, you must terminate the options file by entering the Ctrl/Z key sequence, as in the following example:

$ LINK MAIN,SUB1,SUB2,SYS$INPUT:/OPTIONS MYPROC/SHAREABLE SYS$LIBRARY:APPLPCKGE/SHAREABLE STACK=75 [Ctrl/Z]

Digital recommends using command procedures to invoke the LINK command because it enables you to keep both the LINK command and all input file specifications, including any options files, together in a single file. To perform a link operation using a command procedure, you simply invoke the command procedure, as in the following example:

$ @LINKPROC

1.3 Specifying Linker Output Files

The primary output generated by the linker is an image file. In addition, the linker can generate two other output files: a symbol table file and a map file.

For Alpha linking only, the linker can generate 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 executed at the command line. Specify the /EXECUTABLE qualifier to create one. This is the default output file created by the linker.
Shareable image	.EXE	A program that can be run only after being included in a link operation in which an executable image is created. Specify the /SHAREABLE qualifier to create one.
System image	.EXE	A program that is meant to be run as a standalone system. Specify the /SYSTEM qualifier to create one.
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 one.
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 one.
++Debug symbol file	.DSF	A file containing symbol information for use by the OpenVMS Alpha System-Code Debugger. Specify the /DSF qualifier to create one. See Writing OpenVMS Alpha Device Drivers in C for guidelines on using the system-code debugger.

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 OpenVMS DCL Dictionary for information about using this utility.

The following sections describe each of the output files.

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

4548PRO_001.HTML