HP OpenVMS Systems Documentation

HP OpenVMS Linker Utility Manual

Controls the processing of the demangling information. Specify /DNI (the default) to allow the linker to attempt symbol name demangling and move the necessary demangling information into the shareable image being created.

Format

/DNI (default)

/NODNI

Qualifier Values

None.

Description

The /DNI qualifier controls the processing of the demangling information.

The object modules generated by the HP C, HP C++, GNAT Pro Ada, and possibly other compilers can have symbol names in the symbol table that have been altered; a process is commonly referred to as "mangling". These names are the symbol names visible to the linker, which the linker uses for symbol resolution.

The reason for mangling can be an overload feature in the programming language or simply the need to uniquely shorten names. When you link such modules and get an undefined-symbol message, the linker displays only the symbol name from the object module's symbol table (that is, the mangled name). This processing makes it difficult to match the undefined, mangled symbol with the unmangled, source code name. The linker displays the source code name; that is, the linker can "demangle" the undefined symbol name. Further, if there is demangling information for universal symbols (that is, those to be exported from a shareable image), the linker can include that information in the generated shareable images so that when you link against the shareable image at a later time, the linker can demangle the name when it issues an error message.

The symbol resolution process remains unchanged. The linker still uses the mangled symbol names for symbol definitions and to resolve symbol references. The symbol vector option remains the same as well; it still requires the names found in the symbol tables (the mangled names).

Specify /DNI (the default) to allow the linker to attempt symbol name demangling and move the necessary demangling information into the shareable image being created. Specify /NODNI when:

• You do not want the demangled names to be displayed in error messages.
• You do not want the demangling information to be moved into the shareable image.

For I64 and Alpha linking, directs the linker to create a file called a debug symbol file (DSF) for use by the OpenVMS Debugger or the OpenVMS System-Code Debugger.

Format

/DSF[=file-spec]

/NODSF (default)

Qualifier Values

file-spec

Specifies the character string you want the linker to use as the name of the debug symbol file. If you do not include a file type in the character string, the linker appends the .DSF file type to the file name.

If you specify the /DSF qualifier without the file specification, the linker creates a debug symbol file with the file name of the first input file and the default file type .DSF. If you append the /DSF qualifier to one of the input file specifications, the linker creates a debug symbol file with the file name of the file to which the qualifier is appended and with the default file type .DSF.

The OpenVMS Debugger (whether you use it in System-Code Debugger mode or user mode) requires that the name of the DSF file be the same as the name of the image file, except that the file extension is .DSF. If you use the /EXECUTABLE or /SHAREABLE qualifier and a file name with the LINK command, you must also include the same file name with the /DSF qualifier. (You must also use the .DSF file type.)

Description

The /DSF qualifier directs the linker to create a separate file to contain the debug information used by the OpenVMS Debugger. The /DSF qualifier can be used with the /NOTRACE qualifier to suppress the call of SYS$IMGSTA at activation time. For I64 linking, the /DSF qualifier determines link flags and if traceback information is written into the image file (see Table 3-9). For Alpha linking, the /DSF qualifier has no effect on the contents of the image, including the image header. For more information on the effects of using /DSF combined with /DEBUG and /TRACE, see /DEBUG.

To use the information in the DSF file when you run the image and in case the DSF file is not in the same directory as the image file, you must define the logical name DBG$IMAGE_DSF_PATH to point to disk and directory where the DSF file resides. For more information, see the HP OpenVMS Debugger Manual.

Example

$ LINK/DSF/NOTRACE MY_PROG.OBJ
      

In this example, the linker creates the files MY_PROG.DSF and MY_PROG.EXE.

Directs the linker to create an executable image, as opposed to a shareable image or a system image.

Format

/EXECUTABLE[=file-spec] (default)

/NOEXECUTABLE

Qualifier Values

file-spec

Specifies the character string you want the linker to use as the name of the image file produced by the link operation. If you do not specify a file type in the character string, the linker assigns the .EXE file type by default.

If you do not specify a file name with the /EXECUTABLE qualifier, the linker creates an executable image with the file name of the first input file. If you append the /EXECUTABLE qualifier to an input file specification, the linker creates an executable image with the file name of the file to which the qualifier is appended.

Description

The /NOEXECUTABLE qualifier directs the linker to perform the linking operation but to not create an image file. Use the /NOEXECUTABLE qualifier to have the linker process the input files you specify without creating an image file to check for errors in your LINK command syntax or other link-time errors. You can also use the linker to produce a map file or symbol table file only by specifying the /NOEXECUTABLE qualifier with the /MAP qualifier or the /SYMBOL_TABLE qualifier.

The linker assumes the /EXECUTABLE qualifier as the default unless you specify the /NOEXECUTABLE qualifier, the /SHAREABLE qualifier, or the /SYSTEM qualifier. Note, however, that on Alpha and VAX, when used with the /SYSTEM qualifier, you can use the /EXECUTABLE qualifier to specify the name of a system image.

Examples

$ LINK/NOEXECUTABLE MY_PROG
      

This example directs the linker to link the object module in the file MY_PROG.OBJ without creating an image file.

$ LINK/EXECUTABLE MY_PROG
      

This example directs the linker to produce an executable image named MY_PROG.EXE. (The command line $ LINK MY_PROG will yield the same result because the /EXECUTABLE qualifier is the default.)

$ LINK/EXECUTABLE=MY_IMAGE MY_PROG
      

This example directs the linker to produce an executable image with the name MY_IMAGE.EXE instead of the name MY_PROG.EXE.

Determines the program's initial floating-point mode when one is not provided by the module that provides the main transfer address.

Format

/FP_MODE=keyword

/NOFP_MODE (default)

Qualifier Values

keyword

The OpenVMS I64 Linker accepts the following keywords to set the floating-point mode:

Keyword	Description
D_FLOAT, G_FLOAT	Sets VAX floating-point modes.
IEEE_FLOAT[=ieee_behavior]	Sets the IEEE floating-point mode to the default or a specific behavior. The OpenVMS I64 Linker accepts the following IEEE behavior keywords: FAST UNDERFLOW_TO_ZERO DENORM_RESULTS (default) INEXACT
LITERAL=fp_ctrl_mask	Sets the floating-point mode to a literal control mask. You can express this mask as a decimal (%D), octal (%O), or hexadecimal (%X) value (for example %X09800000, which is equivalent to the default, IEEE_FLOAT=DENORM_RESULTS).

Description

The OpenVMS I64 Linker determines the program's initial floating-point mode using the floating point mode provided by the module that provides the main transfer address. Use the /FP_MODE qualifier to set an initial floating point mode only if the module that provides the main transfer address does not provide an initial floating-point mode. The /FP_MODE qualifier does not override an initial floating point mode provided by the main transfer module.

For more information about the initial floating-point mode, see the HP OpenVMS Calling Standard Manual.

Directs the linker to create a full image map file. For more information, see also the /MAP, /CROSS_REFERENCE, and /BRIEF qualifiers.

Format

/MAP/FULL[=(keyword[,...])]

Qualifier Values

keyword (I64 only)

The OpenVMS I64 Linker accepts the following keywords to tailor the map (the default is /FULL=SECTION_DETAILS):

Keyword	Description
ALL	For the OpenVMS I64 Linker, the ALL keyword is equivalent to specifying the DEMANGLED_SYMBOLS, GROUP_SECTIONS and SECTION_DETAILS keywords.
DEMANGLED_SYMBOLS	For the I64 linker, when display name information is available and processed (DNI), directs the linker to add a translation table to the map file. The table contains both mangled and demangled names for global symbols.
GROUP_SECTIONS	Directs the OpenVMS I64 Linker to list all processed groups.
[NO]SECTION_DETAILS	Directs whether or not the OpenVMS I64 Linker suppresses zero length contributions in the Program Section Synopsis.

Description

On I64, a full map contains the following sections:

• Object and Image Synopsis
• Cluster Synopsis
• Image Segment Synopsis
• Program Section Synopsis
• Symbols By Name (and the Symbol Cross-Reference section if the /CROSS_REFERENCE qualifier is specified)
• Symbols By Value
• Image Synopsis
• Link Run Statistics

On Alpha and VAX, a full map contains the following sections:

• Object Module Synopsis
• Module Relocatable Reference Synopsis (VAX linking only)
• Image Section Synopsis
• Program Section Synopsis
• Symbols By Name (and the Symbol Cross-Reference section if the /CROSS_REFERENCE qualifier is specified)
• Symbols By Value
• Image Synopsis
• Link Run Statistics

By default, a full linker map on I64, Alpha, and VAX systems lists all the module contributions in the Program Section Synopsis.

The full map also contains information about modules included from the default system libraries STARLET.OLB and IMAGELIB.OLB in the Object Module Synopsis, Program Section Synopsis, and Symbols By Name sections. For more information about image map files, see Chapter 5 (I64) and Chapter 9.

The /FULL qualifier is valid only if you also specify the /MAP qualifier in the LINK command. The /FULL qualifier is compatible with the /CROSS_REFERENCE qualifier, but it is not compatible with the /BRIEF qualifier.

On I64, you can request a map section containing a translation table for the global symbol definitions. This table correlates the mangled symbol names with their demangled equivalents. By default, the linker does not generate this section in the map file. To request this section, specify the keyword DEMANGLED_SYMBOLS to the /FULL qualifier. As with other keywords for the /FULL qualifier, specify the /MAP qualifier. You should not specify the /NODNI qualifier. The translation table in the map can be helpful to verify the symbol vector entries.

Example

$ LINK/MAP/FULL MY_PROG
      

This example directs the linker to produce a full image map named MY_PROG.MAP.

For Alpha and I64 linking, directs the linker to include in the global symbol table (GST) of a shareable image those symbols that have been declared as universal symbols in a symbol vector.

Format

/GST (default)

/NOGST

Qualifier Values

None.

Description

By default, the linker lists in the GST of a shareable image the global symbols in the image that have been declared universal. By listing these symbols in the GST, the linker allows them to be referenced in link operations where the shareable image is specified as an input file.

To create a shareable image that can be activated by the images that linked against it, but that cannot be used to resolve symbolic references in a link operation, you can specify the /NOGST qualifier. When this qualifier is specified, the linker creates the image with an empty GST. (The linker still creates a GST.) By using the /NOGST qualifier, you can create a run-time version of a shareable image without having to remove the symbol vector from the link operation.

The images that were linked against the shareable image can still access symbols within the image because the /NOGST qualifier does not affect the symbol vector in the image.

This qualifier is valid only when used with the /SHAREABLE qualifier to create a shareable image.

Example

$ LINK/NOGST/SHAREABLE MY_SHARE,UNIVERSALS/OPTIONS

      

This example creates the shareable image MY_PROG.EXE without listing entries for universal symbols in its global symbol table. The image contains an empty global symbol table.

On Alpha and VAX systems, when specified with the /SYSTEM qualifier, directs the linker to include an image header in a system image.

This qualifier is ignored by the OpenVMS I64 Linker.

Format

/HEADER

/NOHEADER (default)

Qualifier Values

None.

Description

On Alpha and VAX systems, the linker always creates executable images and shareable images with headers; a required component of those image files. The linker creates system images without a header by default. To create a system image with a header, you must specify the /HEADER qualifier along with the /SYSTEM qualifier on the command line.

The linker ignores the /HEADER qualifier if it is specified for any other type of image (executable or shareable).

Example

$ LINK/SYSTEM/HEADER MY_SYS
      

This example directs the linker to produce a system image named MY_SYS.EXE with an image header. For more information about when to specify the /HEADER qualifier with the /SYSTEM qualifier, see the description of the /SYSTEM qualifier.

Identifies the input file specification to which it is appended as a library file and directs the linker to include in the link operation the module or modules specified as the value of the qualifier.

Format

library-name/INCLUDE=(module-name[,...])

Qualifier Values

library-name

Specifies the name of the library from which you want a module or modules extracted. The file name must specify a library file. The linker assumes the default file type of .OLB.

module-name

Specifies the module or modules that you want to extract from the library. To specify more than one module, enclose the list in parentheses and separate the module names with commas.

Description

Note that the /INCLUDE qualifier does not cause the linker to process the library for the definitions of unresolved symbolic references. If you want the linker to search the library for definitions of unresolved symbols, you must also specify the /LIBRARY qualifier before the /INCLUDE qualifier.

Examples

$ LINK MY_PROG,MY_LIB/INCLUDE=(MOD1,MOD2,MOD5)

      

This example directs the linker to include modules MOD1, MOD2, and MOD5 from the library MY_LIB.OLB in the link operation with MY_PROG.

$ LINK MY_PROG,MY_LIB/LIBRARY/INCLUDE=(MOD1,MOD2,MOD5)

      

This example directs the linker to extract modules MOD1, MOD2, and MOD5 from the library MY_LIB.OLB and then to search that library for symbol definitions that are unresolved in all four modules.

Directs the linker to output informational messages produced by a link operation.

Format

/INFORMATIONALS (default)

/NOINFORMATIONALS

Qualifier Values

None.

Description

The linker outputs informational messages by default. To suppress informational messages, specify the /NOINFORMATIONALS qualifier.

Example

$ LINK/NOINFORMATIONALS MY_PROG

      

When the /NOINFORMATIONALS qualifier is specified, informational messages are suppressed.

Identifies the input file specification to which it is appended as a library file and directs the linker to process the library's name table as part of its symbol resolution processing. When the linker finds in the library the definition of a symbol referenced in a previously processed input file, the linker includes from the library the module in which the symbol is defined.

Format

library-name/LIBRARY

Qualifier Values

library-name

Specifies the name of the library to be included in the link operation. You must specify a library file. The linker assumes the default file type of .OLB.

Description

The order in which a library file is specified in the command string (or in an options file) is important because the linker uses the library file to resolve undefined symbols in previously processed (not subsequently processed) modules only. For more information about how the linker processes input files to resolve symbolic references, see Chapter 2 (I64) and Chapter 6 (Alpha and VAX).

Note that shareable image libraries do not contain a copy of an image. They contain the image's name, the image's identification information and a table including the image's universal symbols. The identification information is provided by the GSMATCH= option, when the shareable image is linked. (See the GSMATCH= option for more information).

It is possible that a shareable image is relinked but a library is not updated. To handle this case, the linker looks for compatibility. On Alpha and VAX, the linker makes the same verification that the image activator does; that is, it uses the GSMATCH criteria to verify compatibility.

On VAX, the linker also compares against the date and time, signaling LINK-I-DATMISMCH, if they are different.

On Alpha, the initial behavior of the linker was the same as the VAX linker. The check was seen as too sensitive and the default behavior was changed to use only the GSMATCH criteria. If you prefer, you can obtain the former VAX behavior by setting the logical name LINK$SHR_DATE_CHECK.

Examples

$ LINK MY_PROG,MY_LIB/LIBRARY,PROG2,PROG3

      

In this example, the linker uses the library MY_LIB.OLB to resolve undefined symbols in MY_PROG, but not in PROG2 or PROG3.

$ LINK MY_PROG,PROG2,PROG3,MY_LIB/LIBRARY

      

In this example, the linker can resolve undefined symbols in MY_PROG, PROG2, and PROG3 from the library MY_LIB.OLB.