| Previous | Contents | Index |
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.
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.
| 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 |
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.
$ LINK/NOEXECUTABLE CIRCLE |
|
/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 |
$ LINK/SHAREABLE CIRCLE |
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.
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]
|
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.
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.
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.
|
file.type/LIBRARY |
|
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.
|
file.OBJ/SELECTIVE_SEARCH |
|
file.EXE/SHAREABLE |
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.
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:
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.
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:
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.
| 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.
| Previous | Next | Contents | Index |