HP OpenVMS Systems Documentation

HP OpenVMS Linker Utility Manual

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.

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

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.

1.2.2 Shareable Images as Linker Input Files

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.

Shareable images can provide the following benefits:

• Reducing total link processing time. Because the linker needs only to read the activation information and to process the 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 the image, or initialize the image 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 8.
• 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.

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 8.) 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 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.)

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 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:

$ LIBRARIAN/LIST/NAMES MYMATH_LIB
Directory of ELF OBJECT library WORK:[PROGS]MYMATH_LIB.OLB;1 on
30-MAR-2005 09:59:06
Creation date:  30-MAR-2005 09:58:53      Creator:  Librarian I01-29
Revision date:  30-MAR-2005 09:58:53      Library format:   6.0
Number of modules:      1                 Max. key length:  1024
Other entries:          4                 Preallocated index blocks:    213
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 HP 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 6.)
  When the linker finds the symbol name of a definition in the library's name table, it includes the associated library element 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. For shareable image libraries, the linker takes the image name from the library and attempts to translate it in order to find the image. If that fails, 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 IA64$LIBRARY for I64 links, ALPHA$LIBRARY for Alpha links, or SYS$LIBRARY for VAX 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 6.2.3.3 for more information about default library processing.

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:

$ LINK MY_MAIN_PROGRAM, MY_SYMBOL_TABLE

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 (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 4 includes descriptions of 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 might exceed the buffer capacity of the command language interpreter

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 or modules, such as the /SELECTIVE_SEARCH, /LIBRARY (optionally followed by /INCLUDE) or /SHAREABLE (optionally followed by /SELECTIVE_SEARCH) qualifier.
• Do not specify an options file within an options file.
• Enter at most 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.

MOD1.OBJ,MOD7.OBJ,LIB3.OLB/LIBRARY,-
LIB4/LIBRARY/INCLUDE=(MODX,MODY,MODZ),-
MOD12.OBJ/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:

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

When you specify SYS$INPUT as an interactive options file, 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]

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:

$ @LINKPROC