Compaq Fortran
User Manual for
OpenVMS Alpha Systems


Previous Contents Index


Chapter 3
Linking and Running Compaq Fortran Programs

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

For More Information:

3.1.1.2 The /NATIVE_ONLY Qualifier

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:

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:

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:

3.1.3 Linker Input File Qualifiers

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.

For More Information:

3.1.4 Linker Symbol Table Qualifier

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:

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:

3.2.1 The RUN Command

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:

3.2.4 Returning Status Values to the Command Interpreter

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:

For More Information:

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

3.3 Symbol Table and Traceback Information: Locating Run-Time Errors

Both the compiler and the OpenVMS Run-Time Library include facilities for detecting and reporting errors. You can use the OpenVMS Debugger and the traceback facility to help you locate errors that occur during program execution.

3.3.1 Effects of Error-Related Command Qualifiers

At each step in compiling, linking, and executing your program, you can specify command qualifiers that affect how errors are processed.

Table 3-2 summarizes the /DEBUG and /TRACEBACK qualifiers.

Table 3-2 /DEBUG and /TRACEBACK Qualifiers
Command Qualifier Effect
FORTRAN /DEBUG The Compaq Fortran compiler creates symbolic data needed by the debugger.

Default: /DEBUG=(NOSYMBOLS,TRACEBACK)

 
LINK /DEBUG Symbolic data created by the Compaq Fortran compiler is passed to the debugger.

Default: /NODEBUG

  /TRACEBACK Traceback information is passed to the debugger. Traceback will be produced.

Default: /TRACEBACK

 
RUN /DEBUG Invokes the debugger. The DBG> prompt will be displayed. Not needed if LINK/DEBUG was specified.
  /NODEBUG If /DEBUG was specified in the LINK command line, RUN/NODEBUG starts program execution without first invoking the debugger.

If an exception occurs and these qualifiers are not specified at any point in the compile-link-execute sequence, a traceback list is generated by default.

To perform symbolic debugging, you must use the /DEBUG qualifier with both the FORTRAN and LINK command lines; you do not need to specify it with the RUN command. If /DEBUG is omitted from either the FORTRAN or LINK command lines, you can still use it with the RUN command to invoke the debugger. However, any debugging you perform must then be done by specifying virtual addresses rather than symbolic names.

If you linked your program with the debugger, but wish to execute the program without debugger intervention, specify the following command:


$ RUN/NODEBUG program-name

If you specify LINK/NOTRACEBACK, you receive no traceback in the event of errors.

3.3.2 Sample Source Program and Traceback

Example 3-1 shows a sample source program and a traceback.

Example 3-1 Sample Compaq Fortran Program

    PROGRAM TRACE_TEST 
 
       REAL ST 
       ST = 2.4E20   ! Constant inside range for REAL*4 formats 
 
       CALL SUB1(ST) 
 
    END PROGRAM TRACE_TEST 
 
    SUBROUTINE SUB1(RV) 
       REAL RV,RES 
       RV = RV * RV  ! Generates overflow value 
       RES=LOG(RV)   ! Uses + Infinity value for IEEE floating-point data 
 
       RETURN 
    END SUBROUTINE SUB1 

The program (TRACEBK.F90) shown in Example 3-1 is compiled, linked, and run to generate the traceback information shown after the RUN command:


$ FORTRAN/NOOPTIMIZ/DEBUG=TRACEBACK/SYNCHRONOUS_EX/FLOAT=IEEE_FLOAT TRACEBK.F90
$ LINK TRACEBK 
$ RUN  TRACEBK 
%SYSTEM-F-HPARITH, high performance arithmetic trap, Imask=00000000, 
Fmask=00000001, summary=08, PC=0002007C, PS=0000001B
-SYSTEM-F-FLTOVF, arithmetic trap,floating overflow at PC=0002007C,PS=0000001B 
%TRACE-F-TRACEBACK, symbolic stack dump follows 
 Image Name   Module Name     Routine Name    Line Number  rel PC      abs PC 
 LINK_TRACEBA TRACE_TEST      SUB1                     10 0000007C    0002007C 
 LINK_TRACEBA TRACE_TEST      TRACE_TEST                6 00000030    00020030 
                                                        0 88EEFA50    88EEFA50

On the FORTRAN command line, the following qualifiers are used:

When an error condition is detected, you receive the appropriate message, followed by the traceback information. The Run-Time Library displays a message indicating the nature of the error and the address at which the error occurred (user PC). This is followed by the traceback information, which is presented in inverse order to the calls.

Values can be produced for relative and absolute PC, with no corresponding values for routine name and line. These PC values reflect procedure calls internal to the Run-Time Library.

Of particular interest are the values listed under "Routine Name" and "Line Number":

With this information, you can usually isolate the error in a short time.

If you specify either LINK/DEBUG or RUN/DEBUG, the debugger assumes control of execution and you do not receive a traceback list if an error occurs. To display traceback information, you can use the debugger command SHOW CALLS.

You should use the /NOOPTIMIZE qualifier on the FORTRAN command line whenever you use the debugger.

For More Information:


Previous Next Contents Index