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.

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

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:

• /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_EXC (abbreviation of /SYNCHRONOUS_EXCEPTIONS) 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.12.
• On Compaq Fortran run-time errors, see Chapter 7.

This chapter is an introduction to using the OpenVMS Debugger with Compaq Fortran programs. This chapter provides the following information:

• An overview of the debugger ( Section 4.1)
• Information to get you started using the debugger ( Section 4.2)
• A sample terminal session that demonstrates using the debugger ( Section 4.3)
• A list of the debugger commands by function ( Section 4.5)
• Locating an exception ( Section 4.6)
• Locating unaligned data ( Section 4.7)

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 Compaq Fortran programs. The section focuses on basic debugger functions, to get you started quickly. It also provides any debugger information that is specific to Compaq Fortran.

For More Information:

• About the OpenVMS Debugger (not specific to the Compaq Fortran language), see the 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 Compaq 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.12 and Section 3.3.

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, type:

$ DEFINE DBG$PROCESS DEFAULT

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

If the DECwindows^tm 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, typed 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 type 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 type the command SET SCREEN NOSCREEN).

For More Information:

On the DECwindows Motif debugger interface (including a source browser) and screen mode, see the 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 Alpha DEBUG 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 a Compaq 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 a Compaq 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, type GO once to get to the beginning of the main program.

The DBG> prompt indicates that you can now type debugger commands. At this point, if you type 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 Alpha DEBUG 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 OpenVMS Debugger Manual.

4.2.4 Debugger Commands Used Often

You can use the following debugger commands when debugging any program:

• To get help on debugger commands, type the HELP command.
• To control program execution, type the GO, STEP, CALL, or EXIT commands. To control whether the STEP command steps into or over a routine (or performs other functions), you can use the SET STEP command or qualifiers to the STEP command (such as STEP/OVER).
• To look at the contents of a location, type the EXAMINE command.
• To modify the contents of a location, type the DEPOSIT command.
• To view source lines, you usually use the TYPE command.
• You can use the debugger SPAWN command (followed by the desired DCL command) to execute a DCL command. For instance, if you have some mail messages you need to read, type the following:

  DBG> SPAWN MAIL

For More Information:

• About the types of available Debugger commands, see Section 4.5
• On the available Debugger commands, see the OpenVMS Debugger Manual.

The OpenVMS Debugger supports breakpoints, tracepoints, and watchpoints to help you find out what happens at critical points in your program.

Set a breakpoint if you want the debugger to stop program execution at a certain point in your program (routine, line number, and so on). After you set a breakpoint and begin program execution, execution stops at the breakpoint, allowing you to look at the contents of program variables to see if they contain the correct values.

Use the following commands to control breakpoints:

• To set a breakpoint, use one of the forms of the SET BREAK commands. You can also specify an action for the breakpoint, such as displaying the value of a variable.
• To view the currently set breakpoints, use the SHOW BREAK command.
• To cancel a breakpoint, use CANCEL BREAK. You can temporarily deactivate a breakpoint with a DEACTIVATE BREAK command, which you can later activate with an ACTIVATE BREAK command.

Set a tracepoint to request that the debugger display messages when certain parts of your program execute. You can also specify an action for the tracepoint, such as displaying the value of a variable. Unlike breakpoints, execution continues past the tracepoint. For example, a tracepoint lets you see how many times a routine gets called.

Use the following commands to control tracepoints:

• To set a tracepoint, use one of the forms of the SET TRACE commands. You can also specify an action for the tracepoint, such as displaying the current value of a variable.
• To view the currently set tracepoints, use a SHOW TRACE command.
• To cancel a tracepoint, use a CANCEL TRACE command. You can temporarily deactivate a tracepoint with a DEACTIVATE TRACE command, which you can later activate with an ACTIVATE TRACE command.

Set a watchpoint to request that the debugger stop execution when the values of certain variables (or memory locations) change. A breakpoint stops execution when a certain part of program is reached. In contrast, a watchpoint stops execution when a certain value changes.

The following commands are usually used to control watchpoints:

• To set a watchpoint, use one of the forms of the SET WATCH commands. You can also specify an action for the watchpoint, such as displaying the value of a variable.
• To view the currently set watchpoints, use the SHOW WATCH command.
• To cancel a watchpoint, use CANCEL WATCH command. You can temporarily deactivate a watchpoint with a DEACTIVATE WATCH command, which you can later activate with an ACTIVATE WATCH command.

Before you set a breakpoint, tracepoint, or watchpoint, you can define the scope to be used (by using the SET SCOPE or SET MODULE command, for instance) or you can add a pathname prefix before a symbol name.

4.2.6 Ending a Debugging Session

To end a debugging session and return to the DCL level, type EXIT or press Ctrl/Z:

DBG> EXIT $

The following message, displayed during a debugging session, indicates that your program has completed normally:

%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion' DBG>

To continue debugging after seeing this message, type EXIT and start a new debugging session with the DCL RUN command.

If you specified the DEBUG command with the /KEEP qualifier when you invoked the debugger, you can run the same program again from within the debugging session (RERUN) and perform other functions.

4.2.7 Notes on Debugger Support for Compaq Fortran

In general, the debugger supports the data types and operators of Compaq Fortran and the other debugger-supported languages. However, the following are language-specific limitations and differences:

• Although the type codes for unsigned integers (BU, WU, LU) are used internally to describe the LOGICAL data types, the debugger treats LOGICAL variables and values as being signed when used in language expressions.
• The debugger prints the numeric values of LOGICAL variables or expressions instead of .TRUE. or .FALSE. Normally, only the low-order bit of a LOGICAL variable or value is significant (0 is .FALSE. and 1 is .TRUE.). However, Compaq Fortran does allow all bits in a LOGICAL value to be manipulated, and LOGICAL values can be used in integer expressions. For this reason, it is sometimes necessary to see the entire integer value of a LOGICAL variable or expression, which is what the debugger shows.
• Fortran modules (defined by a MODULE statement) are treated as debugger modules. To see whether a module is known to the debugger, use the SHOW MODULE command. To load the symbolic information about the Fortran module into the debugger, use a SET MODULE command (see Section 4.4.5).
• The default name for a main program unit is filename$MAIN, where filename is the name of your source file. If filename is larger than 26 characters and a name is not specified in a PROGRAM or BLOCK DATA statement, the name is truncated to 26 characters and $MAIN is appended to form the program name.
• COMPLEX constants such as (1.0, 2.0) are not supported in debugger expressions.
• Floating-point number representation depends on the specified precision (KIND) and the FORTRAN command /FLOAT qualifier used during compilation:
  • Single-precision numbers of type REAL (KIND=4) and COMPLEX (KIND=4) can be represented by the F_float or IEEE S_float format, depending on the FORTRAN command /FLOAT qualifier.
  • Double-precision numbers of type REAL (KIND=8) and COMPLEX (KIND=8) can be represented by the D_float, G_float, or IEEE T_float format, depending on the FORTRAN command /FLOAT qualifier.
  • Extended-precision numbers of type REAL (KIND=16) are always represented in X_float format (based on IEEE).

For More Information:

• About the supported data types and operators of any of the languages, type the HELP LANGUAGE command at the DBG> prompt.
• On Compaq Fortran little endian data type representation, see Chapter 8.
• On the FORTRAN /FLOAT qualifier, see Section 2.3.19.

Example 4-1 shows a program called SQUARES that requires debugging. The program was compiled and linked without diagnostic messages from either the compiler or the linker. Compiler-assigned line numbers have been added in the example so that you can identify the source lines referenced in the explanatory text.

Example 4-1 Sample Program SQUARES

1 PROGRAM SQUARES 2 INTEGER (KIND=4) :: INARR(20), OUTARR(20) 3 ! Read the input array from the data file. 4 OPEN(UNIT=8, FILE='datafile.dat', STATUS='OLD') 5 READ(8,*,END=5) N, (INARR(I), I=1,N) 6 5 CLOSE (UNIT=8) 7 ! Square all nonzero elements and store in OUTARR. 8 K = 0 9 DO I = 1, N 10 IF (INARR(I) .NE. 0) THEN 11 OUTARR(K) = INARR(I)**2 12 ENDIF 13 END DO 14 15 ! Print the squared output values. Then stop. 16 PRINT 20, K 17 20 FORMAT (' Number of nonzero elements is',I4) 18 DO I = 1, K 19 PRINT 30, I, OUTARR(I) 20 30 FORMAT(' Element',I4,' has value',I6) 21 END DO 22 END PROGRAM SQUARES

The program SQUARES performs the following functions:

1. Reads a sequence of integer numbers from a data file and saves these numbers in the array INARR (lines 4 and 5). The file DATAFILE.DAT contains one record with the integer values 4, 3, 2, 5, and 2. The first number (4) indicates the number of data items (array elements) that follow.
2. Enters a loop in which it copies the square of each nonzero integer into another array OUTARR (lines 9 through 13).
3. Prints the number of nonzero elements in the original sequence and the square of each such element (lines 16 through 21).

When you run SQUARES, it produces the following output, regardless of the number of nonzero elements in the data file:

$ RUN SQUARES Number of nonzero elements is 0

The error occurs because variable K, which keeps track of the current index into OUTARR, is not incremented in the loop on lines 9 through 13. The statement K = K + 1 should be inserted just before line 11.

Example 4-2 shows how to start the debugging session and use the debugger to find the error in the program in Example 4-1. Comments keyed to the callouts follow the example.

Example 4-2 Sample Debugging Session Using Program SQUARES

$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES (1) $ LINK/DEBUG SQUARES (2) $ SHOW LOGICAL DBG$PROCESS (3) %SHOW-S-NOTRAN, no translation for logical name DBG$PROCESS $ RUN SQUARES (4) OpenVMS Alpha DEBUG Version x.x-xxx %DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARES DBG> STEP 5 (5) stepped to SQUARES\%LINE 9 9: DO 10 I = 1, N DBG> EXAMINE N,K (6) SQUARES\N: 4 SQUARES\K: 0 DBG> STEP 2 (7) stepped to SQUARES\%LINE 11 11: OUTARR(K) = INARR(I)**2 DBG> EXAMINE I,K (8) SQUARES\I: 1 SQUARES\K: 0 DBG> DEPOSIT K = 1 (9) DBG> SET TRACE/SILENT %LINE 11 DO (DEPOSIT K = K + 1) (10) DBG> GO (11) Number of nonzero elements is 4 Element 1 has value 9 Element 2 has value 4 Element 3 has value 25 Element 4 has value 4 %DEBUG-I-EXITSTATUS, is 'SYSTEM-S-NORMAL, normal successful completion' DBG> EXIT (12) $ EDIT SQUARES.FOR (13) . . . 10: IF(INARR(I) .NE. 0) THEN 11: K = K + 1 12: OUTARR(K) = INARR(I)**2 13: ENDIF . . . $ FORTRAN/DEBUG/NOOPTIMIZE SQUARES (14) $ LINK/DEBUG SQUARES $ RUN SQUARES (15) OpenVMS Alpha DEBUG Version x.x-xxx %DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARES DBG> SET BREAK %LINE 12 DO (EXAMINE I,K) (16) DBG> SHOW BREAK breakpoint at SQUARES\%LINE 12 do (EXAMINE I,K) DBG> TYPE 7:14 module SQUARES 7: C ! Square all nonzero elements and store in OUTARR. 8: K = 0 9: DO I = 1, N 10: IF (INARR(I) .NE. 0) THEN 11: K = K + 1 12: OUTARR(K) = INARR(I)**2 13: ENDIF 14: END DO DBG> GO (17) break at SQUARES\%LINE 12 12: OUTARR(K) = INARR(I)**2 SQUARES\I: 1 SQUARES\K: 1 DBG> GO break at SQUARES\%LINE 12 12: OUTARR(K) = INARR(I)**2 SQUARES\I: 2 SQUARES\K: 2 DBG> GO break at SQUARES\%LINE 12 12: OUTARR(K) = INARR(I)**2 SQUARES\I: 3 SQUARES\K: 3 DBG> GO break at SQUARES\%LINE 12 12: OUTARR(K) = INARR(I)**2 SQUARES\I: 4 SQUARES\K: 4 DBG> GO Number of nonzero elements is 4 Element 1 has value 9 Element 2 has value 4 Element 3 has value 25 Element 4 has value 4 %DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion' DBG> EXIT (18) $