HP OpenVMS Systems Documentation
HP OpenVMS Linker Utility Manual
1.2 Specifying Input to the Linker
You specify the files you want the linker to process on the LINK command line or in a linker options file. (Library files may also be specified as a user library, which the linker processes by default.) You must specify at least one input file in every link operation and, in every link operation, at least one input file must be an object module. Table 1-1 lists the different types of input files accepted by the linker, along with their default file types. (The defaults are used on all OpenVMS platforms.) The table also describes how you can specify the file in a link operation.
Only object files and image files of the same architecture can be combined to create an image.
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):
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 HP OpenVMS DCL Dictionary.
To provide useful input for a link operation, the shareable image offers symbols (for example, procedure names) that are external to the other input modules of the image. As a result, when the image is run, the image activator activates the shareable image at the same time so that code and data from the shareable image can be referenced.
A shareable image file consists of activation information, image binaries (code and data), and a symbol table. This symbol table contains definitions of universal symbols exported by the shareable image. A universal symbol is to a shareable image what a global symbol is to a module. That is, where a global symbol can be used to satisfy references external to an object module, a universal symbol can be used to satisfy references external to the shareable image.
188.8.131.52 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 8.) 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 the portions of the shareable image that can be shared. The system can map these portions as global sections into the address space of multiple processes. For portions of the image that are not shareable, each process gets a private copy at image activation time. For help in creating an image on I64 systems, see Chapter 3. For similar information about Alpha and VAX systems, see Chapter 7.
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 HP 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 and shareable images inserted in the library and associates the name of the symbol with the name of the module or shareable image in which it is defined.
Object module libraries contain copies of the object module. Shareable image libraries contain only the names of the shareable images. However, both object and shareable image libraries contain a name table, each entry associated with a definition in an object module or shareable image. Note that this is not the full symbol table of a module or a shareable image.
You cannot examine a library file using a text editor. To find out which modules a library contains, start 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
HP OpenVMS Command Definition, Librarian, and Message Utilities Manual.
1.2.4 Symbol Table Files as Linker Input Files (VAX Only)
A symbol table file is the product of a previous link operation or a language processor. A symbol table file is similar to an object module but it contains only a symbol table.
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 symbol table file during symbol resolution. If the symbol table file is the by-product of a link operation in which an executable image or system image was created, the symbol table 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 by default the names and values of the symbols in the image declared as universal.
For a symbol table file to be useful in link opertions, 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).
Symbol table files created by the linker during I64 and Alpha links can
be used as an aid to debugging 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 4 includes descriptions of 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:
HP 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: