HP OpenVMS Systems Documentation

HP OpenVMS Linker Utility Manual

In this example, the linker appears to loop. The file DOES_NOT_EXIST.OBJ, as included in the argument list, does not exist. An RMS_RELATED_CONTEXT= option is not specified (and, therefore, defaults to YES). With multiple logical names and a search list for the logical RESD$, determining that this file is missing takes very long.

1. These commands define logical names and equivalents.
2. Each time you press Ctrl/T, the CPU and IO values increase, but the MEM and PF values do not, indicating that LIB$FIND_FILE has been called with RMS related name context.

  $  DEFINE DSKD$ WORK4:[TEST.LINKER.OBJ.]
  $  DEFINE RESD$ ROOT$, ROOT2$, ROOT3$, ROOT4$, ROOT5$, DISK_READ$:[SYS.]
  $  DEFINE ROOT$ WORK4:[TEST.PUBLIC.TEST.]
  $  DEFINE ROOT2$ WORK4:[TEST.LINKER.]
  $  DEFINE ROOT3$ WORK4:[TEST.UTIL32.]
  $  DEFINE ROOT4$ WORK4:[TEST.PUBLIC.]
  $  DEFINE ROOT5$ WORK4:[TEST.PUBLIC.TMP.]
  $  LINK/MAP/FULL/CROSS_REFERENCE/EXECUTABLE=ALPHA.EXE SYS$INPUT/OPTIONS
      RMS_RELATED_CONTEXT=NO
          RESD$:[TMPOBJ]A.OBJ,RESD$:[SRC]B.OBJ,RESD$:[SRC]C,DSKD$:[OBJ]D.OBJ
          DSKD$:[OBJ]E,RESD$:[TMPSRC]F.OBJ,RESD$:[TEST]G.OBJ
          RESD$:[SRC.OBJ]H,RESD$:[COM]DOES_NOT_EXIST.OBJ
  [Ctrl/Z]

  %LINK-F-OPENIN, error opening DISK_RESD$:[SYS.][COM]DOES_NOT_EXIST.OBJ; as input
       -RMS-E-FNF, file not found
  $

      

In this example, using an options file with RMS_RELATED_CONTEXT set to NO, causes the link operation to finish immediately because it determines quickly the missing file.

Specifies the size of the user-mode stack.

Format

STACK=number-of-pagelets

STACK=20 (default)

Option Values

number-of-pagelets

Specifies the size of the stack in pagelets (512-byte units).

Description

If you do not specify the STACK= option, the linker allocates 20 pagelets (512-byte units) for the user-mode stack. Note that the stack is usually located at the lower end of the used P1 space and that additional space for the user-mode stack is automatically allocated - growing into unused, lower P1 space, if needed, during program execution.

The STACK= option is primarily used to set the stack size for images that are linked with the /P0IMAGE qualifier, where the stack growth is limited by the mapped images. Depending on the layout of the images, the stack can grow into a writable data segment (I64) or image section (Alpha and VAX) and corrupt the data.

The STACK= option may be specified only in a link operation that produces an executable image. Shareable images share the stack with the executable image.

Directs the linker to define an absolute global symbol with the specified name and assign it the specified value. You can use this option to specify a link-time constant.

Format

SYMBOL=symbol-name,symbol-value

Option Values

symbol-name

A character string up to 31 characters in length.

symbol-value

The value you want to assign to the symbol. An absolute global symbol has a fixed numeric value and is therefore not relocatable. Thus, the value must be a number.

On I64, the numeric value is a 64-bit value.

Description

The definition of a symbol specified by the SYMBOL= option constitutes the first definition of that symbol, and it overrides subsequent definitions of the symbol in input object modules. In particular:

• If the symbol is defined as relocatable in an input object module, the linker ignores this definition, uses the definition specified by the SYMBOL= option, and issues a warning message.
• If the symbol is defined as absolute in an input object module, the linker ignores this definition and uses the definition specified by the SYMBOL= option; however, it does not issue a warning message.

For more information about symbol resolution, see Chapter 2 (I64) and Chapter 6 (Alpha and VAX).

Note The SYMBOL= option cannot be used to define a symbol used in the SYMBOL_VECTOR= option or the UNIVERSAL= option.

Example

$  LINK MY_PROG,SYS$INPUT/OPTIONS
SYMBOL=ITERATIONS,15
[Ctrl/Z]
      

In this example, the program MY_PROG contains a loop, which is performed ITERATIONS times. In this link operation, for the image MY_PROG, the value of ITERATIONS, even if defined in an object module, is set to 15.

For I64 and Alpha linking, specifies whether the linker should include global symbols in a symbol table file produced in a link operation in which a shareable image is created. By default, the linker includes only universal symbols in a symbol table file associated with a shareable image.

Format

SYMBOL_TABLE=GLOBALS/UNIVERSALS

SYMBOL_TABLE=UNIVERSALS (default)

Option Values

GLOBALS

Specifies that the linker should include global symbols and universal symbols in the symbol table file associated with the shareable image.

UNIVERSALS

Specifies that the linker should include only universal symbols in the symbol table file associated with the shareable image.

Description

This option may be specified only in the creation of a shareable image. Note that the symbol table file affected by this option cannot be used as input in a subsequent link operation but is intended to be used with the OpenVMS System Dump Analyzer utility (SDA) as an aid to debugging.

Example

$  LINK/SHAREABLE/SYMBOL_TABLE  MY_SHARE,SYS$INPUT/OPTIONS
GSMATCH=LEQUAL,1,1000
SYMBOL_VECTOR=(PROC1=PROCEDURE,-
               PROC2=PROCEDURE,-
               PROC4=PROCEDURE)
SYMBOL_TABLE=GLOBALS
[Ctrl/Z]
      

In the example, the symbols PROC1, PROC2, and PROC4 are declared as universal symbols. Normally, these symbols would be the only symbols to appear in a symbol table file associated with this shareable image. (The symbol table file duplicates the global symbol table of the shareable image.) However, because the SYMBOL_TABLE=GLOBALS option is specified, the linker also puts all the global symbols in the shareable image into the symbol table file. You must specify the /SYMBOL_TABLE qualifier to obtain a symbol table file.

For I64 and Alpha linking, declares universal symbols in shareable images.

Format

SYMBOL_VECTOR=([alias/]name=entry-type[,...])

Option Values

alias

Optionally specifies an alias name for the symbol you want to declare universal. When specified, the alias name appears in the global symbol table (GST) of the image and values associated with the name specified in the symbol-name parameter appear in the symbol vector of the image.

Note that you can specify alias names only for symbol vector entries declared using the DATA or PROCEDURE keywords. For more information about symbol vector entry types, see the following table.

name

Specifies the name of the symbol or the name of a program section in the shareable image that you want to declare universal.

entry-type

Specifies the type of the symbol vector entry. The following table lists the types of symbol vector entries supported by the linker along with the keyword you use to specify them:

Keyword	Function
DATA 1	Creates a symbol vector entry for data (relocatable or constant). The linker creates an entry for the symbol in the GST of the shareable image.
PROCEDURE 1	Creates a symbol vector entry for a procedure and creates an entry for the symbol in the GST of the shareable image.
PRIVATE_DATA	Creates a symbol vector entry for data; however, the linker does not create an entry for the data in the GST of the shareable image. Thus, the symbol is not available for other modules to link against.
PRIVATE_PROCEDURE	Creates a symbol vector entry for a procedure; however, the linker does not create an entry for the procedure in the GST of the shareable image. Thus, the symbol is not available for other modules to link against.
PSECT	Creates a symbol vector entry for a program section and creates an entry for the program section in the GST of the shareable image. 2
SPARE	Use this keyword to create a placeholder. SPARE allows you to preserve the order of the symbol vector entries when you need to create an upwardly compatible shareable image. The SPARE keyword is used alone; it is not preceded by a symbol name and equal sign.

Description

The linker creates an entry in the GST of a shareable image for each name listed in the SYMBOL_VECTOR= option, unless the symbol is declared private, the /NOGST qualifier is specified, or the symbol is the internal name for an alias. Symbols and program sections that appear in the GST of a shareable image are available for external modules to link against. For more information about creating and using shareable images, see Chapter 4 (I64) and Chapter 8 (Alpha).

Example

$  LINK/SHAREABLE MY_SHARE,SYS$INPUT/OPTIONS
GSMATCH=LEQUAL,1,1000
SYMBOL_VECTOR=(MY_ADD=PROCEDURE,-
               MY_SUB=PROCEDURE,-
               SPARE,-
               SPARE,-
               MY_DATA=DATA,-
               MY_DATA_PSECT=PSECT)
[Ctrl/Z]
      

This example creates a symbol vector with entries for procedures, data, and a program section.

$  LINK/SHAREABLE MY_SHARE,SYS$INPUT/OPTIONS
GSMATCH=LEQUAL,1,1001
SYMBOL_VECTOR=(MY_ADD=PRIVATE_PROCEDURE,-
               DEPRECATED_SUB=PRIVATE_PROCEDURE,-
               MY_ADD/UPDATED_ADD=PROCEDURE,-
               MY_SUB/UPDATED_SUB=PROCEDURE,-
               MY_DATA=DATA,-
               MY_DATA_PSECT=PSECT)
[Ctrl/Z]
      

This example creates a symbol vector to be upward compatible with the shareable image from the last example. Images linked against the old shareable image continue to work. For calling MY_ADD and MY_SUB, they use the first and second entry. The old MY_ADD is still available, but no longer public. The old MY_SUB is replaced by DEPRECATED_SUB. Newly linked images will always use the third and fourth entry for MY_ADD and MY_SUB, the updated public interfaces. For MY_DATA and MY_DATA_PSECT, all images use entries 5 and 6 to reference the unchanged data interfaces.

$  LINK/SHAREABLE MY_SHARE,SYS$INPUT/OPTIONS
GSMATCH=LEQUAL,1,200
CASE_SENSITIVE=YES
SYMBOL_VECTOR=(       my_mul=PROCEDURE,-
               MY_MUL/my_mul=PROCEDURE,-
                      my_div=PROCEDURE,-
               MY_DIV/my_div=PROCEDURE,-
                       my_data=DATA,-
               MY_DATA/my_data=DATA)
CASE_SENSITIVE=NO
[Ctrl/Z]

      

This example creates a symbol vector or a shareable image with all the symbols in the GST as lowercase and uppercase names. This is useful if applications built in the traditional way (compilers uppercase global names) and built as in the Open Source environment (global names as-is) link against that shareable image.

For VAX linking, declares a symbol in a shareable image as universal, causing the linker to include it in the global symbol table of a shareable image.

Format

UNIVERSAL=symbol-name[,...]

Option Values

symbol-name

The name of the symbol or symbols you want to declare universal.

Description

This option may be specified only in the creation of a shareable image.

For more information about declaring universal symbols, refer to Chapter 8.

Example

$  LINK/SHAREABLE MY_SHARE,SYS$INPUT/OPTIONS
UNIVERSAL=MY_SYMBOL
[Ctrl/Z]
      

In this example, the linker includes the universal symbol MY_SYMBOL in the global symbol table of the shareable image MY_SHARE.EXE.

This glossary defines key terms for the OpenVMS Linker. The OpenVMS Linker is part of the OpenVMS operating system which is available on Integrity, Alpha, and VAX hardware platforms. Certain terminology commonly used by the linker on Alpha and VAX might be different on OpenVMS I64. Where applicable, cross-references are made between Alpha/VAX systems and I64 systems.

based cluster: Alpha and VAX systems. A cluster located at a base address using the CLUSTER= option.

brief map: Information produced by the linker when the /BRIEF qualifier is specified with the /MAP qualifier. A brief map contains only a subset of the default map. See also image map.

default map: Information produced by the linker when the /MAP qualifier is specified without the /BRIEF and /FULL qualifiers. See also image map.

demangler: A compiler tool that translates mangled names back to their source-name equivalents. Recent compilers are able to include demangling information when they generate their object modules. See also mangled name.

ELF: See Executable and Linkable Format (ELF).

Executable and Linkable Format (ELF): The object and image format as described in System V Application Binary Interface. The ELF format is extensible; that is, it can contain hardware and software extensions. For I64 systems, a hardware extension is used as described in the Intel Itanium Processor-specific Application Binary Interface. Based on that interface, a software extension to ELF is provided for OpenVMS systems (see the IPF/VMS Object/Image File Functional Specification). In the OpenVMS I64 extension, ELF is the object and image file format for object and image binaries. Compilers, assemblers, and other language processors whose output is used by the used by the OpenVMS Linker Utility must produce object files that conform to the OpenVMS extension of the ELF specification.

executable image: The primary type of image created from a link operation. This image can be executed from the DCL command line. See also shareable image.

fix-up: Executable and shareable images can have references to shareable images. At link time, when symbols are resolved, the address values are not known. They become visible when the image activator maps the shareable image. At that time, the image activator "fixes up" the references with the address values.

full map: Information produced by the linker when the /FULL qualifier is specified with the /MAP qualifier. To tailor the full information, you can use keywords to add or suppress specific information. See also image map.

function descriptor: An I64 term. As defined in the OpenVMS I64 Calling Standard, a function descriptor is the pairing of a code address and a global pointer. With this information, a call to the function (or procedure) can be made, and the called function can access its data by way of the global pointer.

hard definition: A symbol with compiler-supplied storage that is not in an overlaid section.

header table: An ELF term. The ELF format describes portions of the object and image modules, as well as their attributes, using section and segment headers. These headers are contained in two arrays of headers called the Section Header Table (for section headers) and the Program Header Table (for program segment headers). Only one header, the main ELF header, is not listed in either of these tables. It is located at the beginning of the module. See also Executable and Linkable Format.

image file: A file containing binary code and data of a program for an OpenVMS system; essentially, an image of what is in memory when the program is started. Also called an image.

image header: An Alpha and VAX term. The part of an executable or shareable image that describes the contents of the image file (the image sections). It is located at the beginning of the file.

image initialization: The part of the link operation where the linker, after it resolves references and obtains memory requirements, initializes the image by filling it with the compiled binary code and data.

image map: Information generated by the linker that describes the contents of the image and the linking process. The image map helps you determine programming and link-time errors, study the layout of the image in virtual memory, and keep track of global symbols. You control the information generated by the map by accepting the default map, or by specifying either a brief or full map. See also default map, full map, brief map.

image optimization: An I64 and Alpha term. Actions the linker takes to improve run-time performance of an image it creates. For example, for OpenVMS I64 images, the linker can optimize data references to the short data segment.

image relocations: Address suggested by the linker that that image activator uses to relocate the image. See relocations.

linkage pair: An Alpha term. A compiler-generated small data structure to implement a call. A linkage pair consists of the required information to make a call: the code address and the procedure descriptor address of a procedure. The linkage pair is not defined in the OpenVMS Alpha Calling Standard. It is an implementation detail used by compilers and understood by the linker.

local function descriptor: An I64 term. As defined in the OpenVMS I64 Calling Standard, a function descriptor is the pairing of a code address and a global pointer. With this information, a call to the function (or procedure) can be made and the called function can access its data by way of the global pointer. The calling standard requires a local function descriptor for each call to another image. Local function descriptors are set up by the linker. Although for each call a different local function descriptor can be used, the linker sets up and re-uses one local function descriptor per target function. The linker creates a fix-up for each local function descriptor. See also fix-up, official function descriptor.

mangled names: The process where some compilers create abbreviated symbol names to implement language features or to use shortened, unique names. For example, C++ compilers mangle symbol names to guarantee unique names for overloaded functions. See also demangler.

object file: A file produced from a source language by a language processor (compiler, assembler, etc.) that contains one or more object modules that serves as input to the linker. See also image file.

official function descriptor: An I64 term. As defined in the OpenVMS I64 Calling Standard, a function descriptor is the pairing of a code address and a global pointer. With this information, a call to the function (or procedure) can be made and the called function can access its data via the global pointer. The linker sets up an official function descriptor to implement calls to the function (or procedure). As such, an official function descriptor is an entry point. An entry is unique: there can be only one official function descriptor per function (or procedure). See also local function descriptor.

OpenVMS system: An HP system running the HP OpenVMS operating system. These include OpenVMS I64, Alpha, and VAX operating systems. See also system.

OpenVMS Alpha system: An HP Alpha system running the OpenVMS Alpha operating system. Also referred to as Alpha system or Alpha.

OpenVMS I64 system: An HP Integrity server running the OpenVMS I64 operating system. Also referred to as I64 system or I64.

OpenVMS VAX system: An HP VAX system running the OpenVMS VAX operating system. Also referred to as VAX system or VAX.

platform: A generic term referring to all systems of a specific processor architecture. For example, Intel Itanium. (See also system.)

privileged shareable image: A shareable image containing privileged code. For example, user-written system services allow user-mode programs to call routines that can perform functions that require privileges. These services are implemented in shareable images. Because of the presence of privileged code, they are referred to as privileged shareable images. See also protected shareable image.

program section: An area of memory that has a name, a length, and other attributes describing the intended or permitted usage of that portion of memory. Program sections are part of an object module. At link time, the user can set or change some of the attributes so the linker combines them in a manner that the user controls.

program segment: An I64 term. A chunk of the image binary, usually data or code. In general, everything that needs to be available to activate and run the image. See also image section.

protected shareable image: A shareable image created with the /PROTECT qualifier. Privileged shareable images must be protected from user-mode and supervisor-mode write access. See also privileged shareable image.

psect: See program section.

relaxed definition: See tentative definition.

relocations: The linker combines object binaries (code and data) from different object modules. The language processors do not know where their modules will be located in virtual address space. Therefore, the language processors generate information packets for the linker, called relocations, so that code execution and data references will work from any linker-chosen memory location. The linker applies these relocations to data. Because the image activator can place an image at any memory location, the linker produces relocations, called "image relocations", to assist the image activator. Code is always position independent, that is, it requires no relocations.

shareable image: A collection of data and program services that is a product of a link operation and is not directly executed from the DCL command line. To make use of a shareable image, it must first be included as input in a link operation that produces an executable image. See also executable image.

symbol resolution: The process of resolving references to symbols whose definitions are external to the module.

system: The computer hardware; the server. Distinguish from the operating system (for example, OpenVMS Alpha). See also platform.

system image: An Alpha and VAX term. A product of a link operation producing an image that can be run as a standalone program, without operating system support. Therefore, these images typically do not contain image activation information. On OpenVMS I64, images always contain image activation information. As a result, the I64 linker does not create system images. See also executable image.

tentative definition: A symbol definition without compiler supplied storage or storage in overlaid sections. There can be tentative definitions for a symbol in several modules. If no hard definition for the symbol is encountered, one of the tentative definitions for that symbol is selected by the linker to be the defining instance. See also hard definition.