HP OpenVMS Systems Documentation
OpenVMS Linker Utility Manual
1.2.1 Object Modules as Linker Input Files
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):
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.)
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.
18.104.22.168 Including a Shareable Image in a Link Operation
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):
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.
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.
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:
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.)
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.
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:
For more information about creating and using libraries, see the
OpenVMS Command Definition, Librarian, and Message Utilities Manual.
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:
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
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:
Example 1-2 illustrates an options file, named PROJECT3.OPT, that contains both input file specifications and linker options.
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:
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:
Compaq 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, simply invoke the command procedure, as in the following example:
1.3 Specifying Linker Output Files
For Alpha linking only, the linker can generate 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 OpenVMS DCL Dictionary for information about using this utility.