HP OpenVMS Systems Documentation

HP Fortran for OpenVMS
User Manual

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.3 Running HP Fortran Programs

This section describes the following considerations for executing HP 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:

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.4 for details.

3.3.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.3.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 HP 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 VMS DCL Concepts Manual.
• On an example of handling Ctrl/C interrupts, see Section F.2.

If you run your program as part of a command procedure, it is often 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.4.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 HP Fortran for OpenVMS Language Reference Manual.

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

• At compile time, you can specify the /DEBUG qualifier on the FORTRAN command line to ensure that symbolic information is created for use by the debugger.
• At link time, you can also specify the /DEBUG qualifier on the LINK command line to make the symbolic information available to the debugger.
• At run time, you can specify the /DEBUG qualifier on the RUN command line to invoke the debugger.

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

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 if there are errors.

3.4.2 Sample Source Program and Traceback

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

    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_EXCEPTIONS/                       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:

• /NOOPTIMIZE prevents optimizations that might prevent accurate reporting of information.
• /DEBUG=TRACEBACK, the default, ensures there is sufficient traceback information in the object file.
• /SYNCHRONOUS_EXCEPTIONS (Alpha only) ensures that exceptions reporting will be precise (reported at the statement line causing the error).
• /FLOAT=IEEE_FLOAT requests use of IEEE floating-point data types in memory.

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":

• The names under "Routine Name" show which routine or subprogram called the Run-Time Library, which subsequently reported the error.
• The value given for "Line Number" corresponds to the compiler-generated line number in the source program listing.

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:

• On the /OPTIMIZE qualifier, see Section 2.3.14.
• On HP Fortran run-time errors, see Chapter 7.

This chapter describes:

• Section 4.1, Debugger Overview
• Section 4.2, Getting Started with the Debugger
• Section 4.3, Sample Debugging Session
• Section 4.4, Displaying HP Fortran Variables
• Section 4.5, Debugger Command Summary
• Section 4.6, Locating an Exception
• Section 4.7, Locating Unaligned Data

A debugger is a tool that helps you locate run-time errors quickly. It is used with a program that has already been compiled and linked successfully, but does not run correctly. For example, the output may be obviously wrong, or the program goes into an infinite loop or terminates prematurely. The debugger enables you to observe and manipulate the program's execution interactively so you can locate the point at which the program stopped working correctly.

The OpenVMS Debugger is a symbolic debugger, which means that you can refer to program locations by the symbols (names) you used for those locations in your program---the names of variables, subroutines, labels, and so on. You do not need to use virtual addresses to refer to memory locations.

By issuing debugger commands at your terminal, you can perform the following operations:

• Start, stop, and resume the program's execution
• Trace the execution path of the program
• Monitor selected locations, variables, or events
• Examine and modify the contents of variables, or force events to occur
• Test the effect of some program modifications without having to edit, recompile, and relink the program

Such techniques allow you to isolate an error in your code much more quickly than you could without the debugger.

Once you have found the error in the program, you can then edit the source code and compile, link, and run the corrected version.

4.2 Getting Started with the Debugger

This section explains how to use the debugger with HP Fortran programs. The section focuses on basic debugger functions, to get you started quickly. It also provides any debugger information that is specific to HP Fortran.

For More Information:

• About the OpenVMS Debugger (not specific to the HP Fortran language), see the HP OpenVMS Debugger Manual.
• On OpenVMS Debugger commands, use online HELP during debugging sessions.

Before you can use the debugger, you must compile and link your program. The following example shows how to compile and link a HP Fortran program (consisting of a single compilation unit in the file INVENTORY.F90) prior to using the debugger.

$ FORTRAN/DEBUG/NOOPTIMIZE INVENTORY
$ LINK/DEBUG INVENTORY

The /DEBUG qualifier on the FORTRAN command line causes the compiler to write the debug symbol records associated with INVENTORY.F90 into the object module INVENTORY.OBJ. These records allow you to use the names of variables and other symbols declared in INVENTORY.F90 in debugger commands. (If your program has several compilation units, each of the program units that you want to debug must be compiled with the /DEBUG qualifier.)

Use the /NOOPTIMIZE qualifier when you compile a program in preparation for debugging. Otherwise, the object code is optimized (to reduce the size of the program and make it run faster), so that the symbolic evaluation of some program locations may be inconsistent with what you might expect from viewing the source code. For example, a variable in an optimized program may not be available. (After debugging the program, recompile it without the /NOOPTIMIZE qualifier.) For a description of the various optimizations performed by the compiler, see Chapter 5.

The /DEBUG qualifier on the LINK command line causes the linker to include all symbol information that is contained in INVENTORY.OBJ in the executable image. This qualifier also causes the OpenVMS image activator to start the debugger at run time. (If your program has several object modules, you may need to specify the other modules on the LINK command line.)

For More Information:

On the effects of specifying the /DEBUG qualifier on the FORTRAN, LINK, and RUN command lines, see Section 2.3.14 and Section 3.4.

4.2.2 Establishing the Debugging Configuration and Interface

Before invoking the debugger, check that the debugging configuration is appropriate for the kind of program you want to debug.

The configuration depends on the current value of the logical name DBG$PROCESS. Before invoking the debugger, issue the DCL command SHOW LOGICAL DBG$PROCESS to determine the current definition of DBG$PROCESS.

The default configuration is appropriate for almost all programs. To request the default debugging configuration. the logical name DBG$PROCESS is undefined or has the value DEFAULT. For example, the following command shows when DBG$PROCESS is undefined:

$ SHOW LOGICAL DBG$PROCESS
%SHOW-S-NOTRAN, no translation for logical name DBG$PROCESS

To define DBG$PROCESS to have a value of DEFAULT, enter:

$ DEFINE DBG$PROCESS DEFAULT

To remove (deassign) a logical name definition, use the DEASSIGN command.

If the DECwindows Motif product is installed and running on your workstation, by default the OpenVMS Debugger uses the DECwindows Motif interface. To use the character cell interface on a DECwindows system, define the logical:

$ DEFINE/PROCESS DBG$DECW$DISPLAY " "

To define this logical name for multiple users, use other logical name tables.

To enable use of the DECwindows interface, deassign the logical:

$ DEASSIGN/PROCESS DBG$DECW$DISPLAY

The DECwindows interface provides a main window in which portions are updated as the program executes, including the source code, entered commands, and debugger messages. This interface provides pull-down menus and uses the kept debugger (equivalent of DEBUG/KEEP).

The examples in this chapter show the command line (character cell) interface to the OpenVMS Debugger.

The character cell interface to the OpenVMS Debugger provides the following debugging interfaces:

• Screen mode
• Line-oriented mode

Screen mode is activated by pressed PF3 on the keypad (or enter the command SET MODE SCREEN). Screen mode allows the debugger character cell interface to simultaneously display separate groups of data similar to the DECwindows interface. For example, your screen might show the source code (SRC), debugger output (OUT), and debugger command input (PROMPT) displays.

While in screen mode, use the SHOW DISPLAY command to view the predefined displays and the DISPLAY command to define a new display. To view the keypad definitions in screen mode, press PF2 on the keypad.

To leave screen mode and resume line-oriented mode, press PF1 PF3 (or enter the command SET SCREEN NOSCREEN).

For More Information:

On the DECwindows Motif debugger interface (including a source browser) and screen mode, see the HP OpenVMS Debugger Manual.

4.2.3 Invoking the Debugger

After you compile and link your program and establish the appropriate debugging configuration, you can then invoke the debugger. To do so, enter the DCL command RUN, specifying the executable image of your program as the parameter. For example, enter the following command to debug the program INVENTORY:

$ RUN INVENTORY
         OpenVMS DEBUG (IA64 Debug64) Version x.x-xxx

%DEBUG-I-INITIAL, language is FORTRAN, module set to INVENTORY
DBG> GO
%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion'
DBG> EXAMINE N
INVENTORY\N: 4
DBG> EXIT
$

The diagnostic message that is displayed at the debugger startup indicates that this debugging session is initialized for an HP Fortran program and that the name of the main program unit is INVENTORY. In the initial "%DEBUG-I-INITIAL" message, the OpenVMS Debugger term "module" is equivalent to an HP Fortran "procedure."

When some qualifiers are used to compile (/WARNINGS=ALIGNMENT or most /CHECK keywords), the debugger does not start up in the main program. When this happens, enter GO once to get to the beginning of the main program.

The DBG> prompt indicates that you can now enter debugger commands. At this point, if you enter the GO command, program execution begins and continues until it is forced to pause or stop (for example, if the program prompts you for input or an error occurs).

You can specify the DEBUG command /KEEP qualifier to use the kept debugger. The kept debugger allows you to run one (or more) programs with the RUN command, rerun the last program run with a RERUN command, and connect and disconnect to a running process. For example:

$ DEBUG /KEEP 
         OpenVMS DEBUG (IA64 Debug64) Version x.x-xxx

DBG> RUN SQUARES 
%DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARES
DBG> GO
%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion'
DBG> RERUN 
DBG> STEP
 stepped to SQUARES\%LINE 4
 4:       OPEN(UNIT=8, FILE='DATAFILE.DAT', STATUS='OLD')
DBG> EXAMINE N
DEBUGEX$MAIN\N: 0
DBG> GO
%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion'
DBG> EX N
DEBUGEX$MAIN\N: 4
DBG> EXIT 

For more information on using the debugger and invoking the debugger for other display modes, see the HP OpenVMS Debugger Manual.