This chapter describes how to produce an executable image from a Compaq Fortran object file, how to execute the resulting image, and how to isolate run-time errors.

The primary functions of the linker are to allocate virtual memory within the executable image, to resolve symbolic references among object modules being linked, to assign values to relocatable global symbols, to perform relocation, and to perform any requested special-purpose tasks. The linker creates an executable or shareable image that you can run on an OpenVMS system.

For any Compaq Fortran program unit, the object file generated by the compiler may contain calls and references to Compaq Fortran run-time procedures, which the linker locates automatically in the default system object libraries, such as IMAGELIB.OLB. These libraries are described in the OpenVMS Linker Utility Manual.

This chapter provides information on the following topics:

• The LINK command, including qualifiers, input files, output files, and using libraries ( Section 3.1)
• Running Compaq Fortran programs ( Section 3.2)
• Using symbol table and traceback information to locate the cause of run-time errors ( Section 3.3)

The topics in this chapter are confined to areas of particular interest to Compaq Fortran programmers.

For More Information:

On linker capabilities and detailed descriptions of LINK command qualifiers and options, see the OpenVMS Linker Utility Manual.

3.1 The LINK Command

The LINK command initiates the linking of the object file. The command has the following form:

LINK[/command-qualifiers] file-spec[/file-qualifiers]...

/command-qualifiers

Specify output file options.

file-spec

Specifies the input object file to be linked.

/file-qualifiers

Specify input file options.

In interactive mode, you can issue the LINK command without a file specification. The system then requests the file specifications with the following prompt:

_File:

You can enter multiple file specifications by separating them with commas (,) or plus signs (+). When used with the LINK command, the comma has the same effect as the plus sign; a single executable image is created from the input files specified. If no output file is specified, the linker produces an executable image with the same name as that of the first object file and with a file type of EXE.

Table 3-1 lists the linker qualifiers of particular interest to Compaq Fortran users.

Table 3-1 LINK Command Qualifiers

Function	Qualifiers	Defaults
Request output file, define a file specification, and specify whether to create an executable or shareable image.	/EXECUTABLE[=file-spec] /SHAREABLE[=file-spec] (see Section 3.1.1.1)	/EXECUTABLE= name.EXE where name is the name of the first input file. /NOSHAREABLE
Allow the executable image to interoperate with nonnative shared libraries.	/[NO]NATIVE_ONLY (see Section 3.1.1.2)	/NATIVE_ONLY (see Section 3.1.1)
Request and specify the contents of an image map (memory allocation) listing.	/BRIEF /[NO]CROSS_REFERENCE /FULL /[NO]MAP (see Section 3.1.1.3)	/NOCROSS_REFERENCE /NOMAP (interactive) /MAP= name.MAP (batch) where name is the name of the first input file.
Specify the amount of debugging information.	/[NO]DEBUG /[NO]TRACEBACK (see Section 3.1.2)	/NODEBUG /TRACEBACK
Indicate the type of input files and request the inclusion of only certain object modules.	/INCLUDE=(module-name...) /LIBRARY /SELECTIVE_SEARCH as positional qualifier: /SHAREABLE (see Section 3.1.3)	Not applicable.
Request or disable the searching of default user libraries and system libraries.	/[NO]SYSLIB /[NO]SYSSHR /[NO]USERLIBRARY[=table]	/SYSLIB /SYSSHR /USERLIBRARY=ALL
Indicate that an input file is a linker options file.	/OPTIONS (see Section 3.1.5)	Not applicable.
Request a symbol table.	/[NO]SYMBOL_TABLE[=file-spec] (see Section 3.1.4)	/NOSYMBOL_TABLE

3.1.1 Linker Output File Qualifiers

You can use qualifiers on the LINK command line to control the output produced by the linker. You can also specify whether traceback and debugging information is included. (The /DEBUG and /TRACEBACK qualifiers are described in Section 3.1.2.)

Linker output consists of an image file and, optionally, a map file. The qualifiers that control image and map files are described under the headings that follow.

3.1.1.1 Image File Qualifiers

The LINK command /[NO]EXECUTABLE and /[NO]SHAREABLE qualifiers control whether the linker creates an executable image, a shareable image, or no image file.

• /EXECUTABLE---If you omit /EXECUTABLE and /SHAREABLE, the default is /EXECUTABLE, and the linker produces an executable image.
  To suppress production of an image, specify /NOEXECUTABLE. For example, in the following command, the file CIRCLE.OBJ is linked, but no image is generated:

  $ LINK/NOEXECUTABLE CIRCLE

  
  The /NOEXECUTABLE qualifier is useful if you want to verify the results of linking an object file without actually producing the image.
  To designate a file specification for an executable image, use the /EXECUTABLE qualifier in the following form:

  /EXECUTABLE=file-spec

  
  For example, the following command links the file CIRCLE.OBJ. The linker generates an executable image named TEST.EXE:

  $ LINK/EXECUTABLE=TEST CIRCLE

• /SHAREABLE---A shareable image has all of its internal references resolved, but must be linked with one or more object modules to produce an executable image. A shareable image file, for example, can contain a library of routines. To create a shareable image, specify the /SHAREABLE qualifier, as shown in the following example:

  $ LINK/SHAREABLE CIRCLE

  
  To include a shareable image as input to the linker, you can either use a linker options file or insert the shareable image into a shareable-image library and specify the library as input to the LINK command. By default, the linker automatically searches the system-supplied shareable-image library SYS$LIBRARY:IMAGELIB.OLB after searching any libraries you specify on the LINK command line.
  If you specify (or default to) /NOSHAREABLE, the linker creates an executable image, which cannot be linked with other images.
  You can also use the /SHAREABLE qualifier in an options file as a positional qualifier (following a file specification).
  To create a shareable-image library, use the LIBRARIAN command with the /CREATE and /INSERT qualifiers.

For More Information:

• On creating and populating libraries, see OpenVMS Command Definition, Librarian, and Message Utilities Manual.
• On libraries searched by the linker, see the OpenVMS Linker Utility Manual.

The FORTRAN command /[NO]TIE qualifier and the LINK command /[NO]NATIVE_ONLY qualifier together control whether procedure signature block (PSB) information is placed in the executable image.

The image activator uses the procedure signature block (PSB) information in the executable image to build jackets that allow calls (interoperability) with translated VAX shareable images. To allow interoperability with translated shareable images, you must:

• On the FORTRAN command line, specify the /TIE qualifier. This places the PSB information into the object module.
• On the LINK command line, specify /NONATIVE_ONLY. This propagates the PSB information from the object module into the executable image, so the image activator can use it with translated images.

The following command combination creates an executable image for translated image interoperability:

$ FORTRAN/TIE file $ LINK/NONATIVE_ONLY file

The FORTRAN command uses the /TIE qualifier, which places the PSB information in the object module. The LINK command /NONATIVE_ONLY qualifier propagates the PSB information in the object module into the executable image.

Unless you need the PSB information for calls to translated shareable images, avoid placing PSB information in the executable image to minimize its size for performance reasons.

The default for the FORTRAN command, /NOTIE, results in the PSB information not being placed in the object module. The default for the LINK command, /NATIVE_ONLY, results in the linker not passing any PSB information present in the object module into the executable image.

For example, the following command combination creates a executable image for native use only (no PSB information in the executable image):

$ FORTRAN/TIE file $ LINK file

The FORTRAN /TIE qualifier places the PSB information in the object module. By default, the linker does not propagates the PSB information, if found in the object module, to the executable image (default is /NATIVE_ONLY). The same object module might be retained and used in a different application that requires interoperability.

For More Information:

On interoperability, see Section A.6 and Migrating an Application from OpenVMS VAX to OpenVMS Alpha.

3.1.1.3 Map File Qualifiers

The LINK command /MAP qualifier and its keywords indicate whether a image map file is to be generated and, if so, the amount of information to be included in the image map file.

The map qualifiers are specified as follows:

/[NO]MAP[=file-spec] /BRIEF /CROSS_REFERENCE /FULL

In interactive mode, the default is to suppress the map; in batch mode, the default is to generate the map.

If you do not include a file specification with the /MAP qualifier, the map file has the name of the first input file and a file type of MAP. It is stored on the default device in the default directory.

The /BRIEF and /FULL qualifiers define the amount of information included in the map file. They function as follows:

• /BRIEF produces a summary of the image's characteristics and a list of contributing object modules.
• /FULL produces a summary of the image's characteristics and a list of contributing object modules (as produced by /BRIEF). It also produces a list, in symbol-name order, of global symbols and values (program, subroutine, and common block names, and names declared EXTERNAL) and a summary of characteristics of image sections in the linked image.

If neither /BRIEF nor /FULL is specified, the map file, by default, contains a summary of the image's characteristics, a list of contributing object modules (as produced by /BRIEF), and a list of global symbols and values, in symbol-name order.

You can use the /CROSS_REFERENCE qualifier with either the default or /FULL map qualifiers to request cross-reference information for global symbols. This cross-reference information indicates the object modules that define or refer to global symbols encountered during linking. The default is /NOCROSS_REFERENCE.

For More Information:

On image maps, see OpenVMS Linker Utility Manual.

3.1.2 /DEBUG and /TRACEBACK Qualifiers

The /DEBUG qualifier includes the debugger and places local symbol information (contained in the object modules) in the executable image. The default is /NODEBUG.

When you use the /TRACEBACK qualifier, run-time error messages are accompanied by a symbolic traceback. This shows the sequence of calls that transferred control to the program unit in which the error occurred. If you specify /NOTRACEBACK, this information is not produced. The default is /TRACEBACK.

If you specify /DEBUG, the traceback capability is automatically included, and the /TRACEBACK qualifier is ignored.

For More Information:

• On the OpenVMS debugger, see Chapter 4.
• On a sample traceback list, see Section 3.3.1.

The LINK command input file qualifier /LIBRARY identifies the input file as a library file. The LINK command /INCLUDE qualifier specifies the names of one or more object modules in a library to be used as input files. The /SELECTIVE_SEARCH qualifier indicates that only symbols referenced from previous input files be taken from the specified file's list of global symbols, rather than all of the input file's global symbols.

To specify a shareable image as an input file, place the /SHAREABLE positional qualifier after the file specification in a link options file. In contrast to the /SHAREABLE qualifier you use on a LINK command line to create a shareable image, the /SHAREABLE positional qualifier in a link options file specifies a shareable image input file.

Input files can be object files, previously linked shareable files, or library files.

• The /LIBRARY qualifier specifies that the input file is an object-module or shareable-image library that is to be searched to resolve undefined symbols referenced in other input object modules. The default file type is OLB.
  The /LIBRARY qualifier has the following form:

  file.type/LIBRARY

• The /INCLUDE qualifier specifies that the input file is an object-module or shareable-image library and that the object modules named are the only object modules in the library to be explicitly included as input. In the case of shareable-image libraries, the object module is the shareable-image name.
  The /INCLUDE qualifier has the following form:

  file.type/INCLUDE=module-name

  
  At least one object module name is required. To specify more than one, enclose the object module names in parentheses and separate the names with commas.
  The default file type is OLB. The /LIBRARY qualifier can also be used, with the same file specification, to indicate that the same library is to be searched for unresolved references.

• The /SELECTIVE_SEARCH qualifier specifies that the linker only include those global symbols already referenced from previous input files, instead of all the global symbols defined by the specified input file. The /SELECTIVE_SEARCH positional qualifier has the following form:

  file.OBJ/SELECTIVE_SEARCH

• When used as a positional qualifier in a linker options file, the /SHAREABLE qualifier specifies that the input file it follows is a shareable image. The /SHAREABLE positional qualifier has the following form:

  file.EXE/SHAREABLE

For More Information:

• On defining DCL commands, creating libraries, and related topics, see the OpenVMS Command Definition, Librarian, and Message Utilities Manual.
• On linker capabilities and detailed descriptions of LINK command qualifiers and options, see the OpenVMS Linker Utility Manual.

The /SYMBOL_TABLE qualifier requests that the symbol table be written to a file. You can specify the name of the file by using the following form:

/SYMBOL_TABLE=file-spec

If you omit the file name, the linker uses a default file type of STB.

3.1.5 Linker Options File Qualifier

The /OPTIONS qualifier identifies a file as a linker options file, which contains additional information about the current link operation.

file-spec/OPTIONS

The file specification is usually a file with default file type of OPT.

You can use an options file to specify additional information to the linker, including a shared image as input to the linker, declare universal symbols, and other features.

For more information on using an OPTIONS file, see the OpenVMS Linker Utility Manual.

3.1.6 Other Linker Qualifiers

This chapter discusses the more frequently used linker qualifiers. Other linker qualifiers specify additional libraries to be searched or to prevent default libraries from being searched, control image section characteristics and placement, creation of a global symbol table, and other linker operations.

Compaq Fortran programs should not be linked with certain linker qualifiers, such as /SYSTEM and /PROTECT.

3.1.7 Linker Messages

If the linker detects any errors while linking object modules, it displays messages about their cause and severity. If any errors or fatal conditions occur (severities E or F), the linker does not produce an image file.

Linker messages are descriptive; you do not normally need additional information to determine the specific error. Some of the more common errors that occur during linking are as follows:

• An object module has compilation errors. This error occurs when you attempt to link a object module that had warnings or errors during compilation. Although you can usually link compiled object modules for which the compiler generated messages, you should verify that the object modules actually produce the expected results during program execution.
• The object modules that are being linked define more than one transfer address. The linker generates a warning if more than one main program has been defined. This can occur, for example, when an extra END statement exists in the program. In this case, the image file created by the linker can be run; the entry point to which control is transferred is the first one that the linker finds.
• A reference to a symbol name remains unresolved. This error occurs when you omit required object module or library names on the LINK command line, and the linker cannot locate the definition for a specified global symbol reference.

If an error occurs when you link object modules, you can often correct it simply by reentering the command string and specifying the correct object files or libraries.

You can use the OpenVMS HELP/MESSAGE facility to view error recovery descriptions associated with messages from any OpenVMS facility.

For More Information:

On using the HELP/MESSAGE command, see OpenVMS System Messages: Companion Guide for Help Message Users.

3.2 Running Compaq Fortran Programs

This section describes the following considerations for executing Compaq Fortran programs on an OpenVMS operating system:

• Using the RUN command to execute programs interactively
• Passing status values to the command interpreter

The RUN command initiates execution of a program. The command has the following form:

RUN[/[NO]DEBUG] file-spec

You must specify the file name. If you omit optional elements of the file specification, the system automatically provides a default value. The default file type is EXE.

The /DEBUG qualifier allows you to use the debugger, even if you omitted this qualifier on the FORTRAN and LINK command lines. Refer to Section 3.3 for details.

3.2.2 System Processing at Image Exit

When the main program executes an END statement, or when any program unit in the program executes a STOP statement, the image is terminated. With the OpenVMS operating system, the termination of an image, or image exit, causes the system to perform a variety of clean-up operations during which open files are closed, system resources are freed, and so on.

3.2.3 Interrupting a Program

When you execute the RUN command interactively, you cannot execute any other program images or DCL commands until the current image completes. However, if your program is not performing as expected---if, for instance, you have reason to believe it is in an endless loop---you can interrupt it by using the Ctrl/Y key sequence. (You can also use the Ctrl/C key sequence, unless your program takes specific action in response to Ctrl/C.) For example:

$ RUN APPLIC [Ctrl/Y] $

This command interrupts the program APPLIC. After you have interrupted a program, you can terminate it by entering a DCL command that causes another image to be executed or by entering the DCL commands EXIT or STOP.

Following a Ctrl/Y interruption, you can also force an entry to the debugger by entering the DEBUG command.

Some of the other DCL commands you can enter have no direct effect on the image. After using them, you can resume the execution of the image with the DCL command CONTINUE. For example:

$ RUN APPLIC [Ctrl/Y] $ SHOW LOGICAL INFILE %SHOW-S-NOTRAN, no translation for logical name INFILE $ DEFINE INFILE $1$DUA1:[TESTFILES]JANUARY.DAT $ CONTINUE

As noted previously, you can use Ctrl/C to interrupt your program; in most cases, the effect of Ctrl/C and Ctrl/Y is the same. However, some programs (including programs you may write) establish particular actions to take to respond to Ctrl/C. If a program has no Ctrl/C handling routine, then Ctrl/C is the same as Ctrl/Y.

For More Information:

• On defining DCL commands, creating libraries, and related topics, see the OpenVMS Command Definition, Librarian, and Message Utilities Manual.
• On commands you can enter following a Ctrl/Y interruption without affecting the current image, see the OpenVMS DCL Concepts Manual.
• On an example of handling Ctrl/C interrupts, see Section E.2.

If you run your program as part of a command procedure, it is frequently useful to return a status value to the command procedure. This indicates whether the program actually executed properly.

To return such a status value, call the EXIT system subroutine rather than terminating execution with a STOP, RETURN, or END statement. The EXIT subroutine can be called from any executable program unit. It terminates your program and returns the value of the argument as the return status value of the program.

When the command interpreter receives a status value from a terminating program, it attempts to locate a corresponding message in a system message file or a user-defined message file. Every message that can be issued by a system program, command, or component, has a unique 32-bit numeric value associated with it. These 32-bit numeric values are called condition symbols. Condition symbols are described in Section 14.3.3.

The command interpreter does not display messages on completion of a program under the following circumstances:

• The EXIT argument specifies the value 1, corresponding to SUCCESS.
• The program does not return a value. If the program terminates with a RETURN, STOP, or END statement, a value of 1 is always returned and no message is displayed.

For More Information:

On the EXIT subroutine, see the Compaq Fortran Language Reference Manual.