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

• To get help on debugger commands, enter the HELP command.
• To control program execution, enter 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, enter the EXAMINE command.
• To modify the contents of a location, enter 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, enter 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 HP 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, enter 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, enter 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 HP Fortran

In general, the debugger supports the data types and operators of HP 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, HP 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, enter the HELP LANGUAGE command at the DBG> prompt.
• On HP Fortran little endian data type representation, see Chapter 8.
• On the FORTRAN /FLOAT qualifier, see Section 2.3.22.

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 DEBUG (IA64 Debug64) 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 DEBUG (IA64 Debug64) 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) $

1. The /DEBUG qualifier on the DCL FORTRAN command directs the compiler to write the symbol information associated with SQUARES into the object module, SQUARES.OBJ, in addition to the code and data for the program.
   The /NOOPTIMIZE qualifier disables optimization by the FORTRAN compiler, to ensure that the executable code matches the source code of the program. Debugging optimized code can be confusing because the contents of some program locations might be inconsistent with what you would expect from viewing the source code.
2. The /DEBUG qualifier on the DCL LINK command causes the linker to include all symbol information that is contained in SQUARES.OBJ in the executable image.
3. The SHOW LOGICAL DBG$PROCESS command shows that the logical name DBG$PROCESS is undefined, thus the debugger starts in the default configuration.
4. The DCL command RUN SQUARES starts the debugger, which displays its banner and the debugger prompt, DBG>. You can now enter debugger commands. The informational message identifies the source language of the program (FORTRAN) and the name of the main program unit (SQUARES).
   After the RUN SQUARES command, execution is initially paused at the start of the main program unit (line 1 of SQUARES, in this example).
5. You decide to test the values of variables N and K after the READ statement has been executed and the value 0 has been assigned to K.
   The command STEP 5 executes 5 source lines of the program. Execution is now paused at line 9. The STEP command ignores source lines that do not result in executable code; also, by default, the debugger identifies the source line at which execution is paused.
6. The command EXAMINE N, K displays the current values of N and K. Their values are correct at this point in the execution of the program.
7. The command STEP 2 executes the program into the loop (lines 9 to 11) that copies and squares all nonzero elements of INARR into OUTARR
8. The command EXAMINE I,K displays the current values of I and K.
   I has the expected value, 1. But K has the value 0 instead of 1, which is the expected value. To fix this error, K should be incremented in the loop just before it is used in line 11.
9. The DEPOSIT command assigns K the value it should have now: 1.
10. The SET TRACE command is now used to patch the program so that the value of K is incremented automatically in the loop. The command sets a tracepoint that triggers every time execution reaches line 11:
    • The /SILENT qualifier suppresses the "trace at" message that would otherwise appear each time line 11 is executed.
    • The DO clause issues the DEPOSIT K = K + 1 command every time the tracepoint is triggered.
11. To test the patch, the GO command starts execution from the current location.
    The program output shows that the patched program works properly. The EXITSTATUS message shows that the program executed to completion.
12. The EXIT command returns control temporarily to DCL level so that you can correct the source file and recompile and relink the program.
13. The DCL command EDIT invokes an editor and the source file is edited to add K = K + 1 after line 10, as shown. (Compiler-assigned line numbers have been added to clarify the example.)
14. The revised program is compiled and linked.
15. The RUN SQUARES (DCL command) starts the debugger using the revised program so that its correct execution can be verified.
16. The SET BREAK command sets a breakpoint that triggers every time line 12 is executed. The DO clause displays the values of I and K automatically when the breakpoint triggers.
    The SHOW BREAK command displays the currently set breakpoints.
    The TYPE 7:14 command displays source lines 7 to 14.
17. The GO command starts execution.
    At the first breakpoint, the value of K is 1, indicating that the program is running correctly so far. Each additional GO command shows the current values of I and K. After two GO commands, K is now 3, as expected. However, I is 4, because one of the INARR elements was zero so that lines 11 and 12 were not executed (and K was not incremented) for that iteration of the DO loop. This confirms that the program is running correctly.
18. The EXIT command ends the debugging session, returning control to DCL level.

You usually display the values of variables by using the debugger EXAMINE command, which accepts numerous qualifiers.

4.4.1 Accessing HP Fortran Common Block Variables

To display common block variables, enter the EXAMINE command followed by the variable names that make up the common block. For example:

DBG> TYPE 1:8 1: 2: PROGRAM TEST 3: INTEGER*4 INT4 4: CHARACTER(LEN=1) CHR 5: COMMON /COM_STRA/ INT4, CHR 6: CHR = 'L' 7: INT4 = 0 8: END PROGRAM TEST DBG> STEP 3 stepped to TEST\%LINE 8 8: END PROGRAM TEST DBG> EXAMINE CHR, INT4 TEST\CHR: 'L' TEST\INT4: 0

4.4.2 Accessing HP Fortran Derived-Type Variables

To display derived-type structure variables, enter the EXAMINE command followed by the derived-type variable name, a period (.) (or a %), and the member name. For example:

DBG> TYPE 1:6 1: PROGRAM TEST 2: 3: TYPE X 4: INTEGER A(5) 5: END TYPE X 6: TYPE (X) Z 7: 8: Z%A = 1 DBG> STEP 2 stepped to TEST\%LINE 10 10: END PROGRAM TEST DBG> EXAMINE Z.A TEST\Z.A(1:5) (1): 1 (2): 1 (3): 1 (4): 1 (5): 1

4.4.3 Accessing HP Fortran Record Variables

To display a field in a record structure, enter the EXAMINE command followed by the record name, a period (.), and the field name. To display the entire record structure, enter EXAMINE followed by the record name. For example:

DBG> TYPE 1:9 module TEST 1: PROGRAM TEST 2: STRUCTURE /STRA/ 3: INTEGER*4 INT4 4: CHARACTER(LEN=1) CHR 5: END STRUCTURE 6: RECORD /STRA/ REC 7: 8: REC.CHR = 'L' 9: END PROGRAM TEST DBG> STEP 2 stepped to TEST\%LINE 11 11: END PROGRAM TEST DBG> EXAMINE REC.CHR TEST\REC.CHR: 'L' DBG> EXAMINE REC.INT4 TEST\REC.INT4: 0 DBG> EXAMINE REC TEST\REC INT4: 0 CHR: 'L'

4.4.4 Accessing HP Fortran Array Variables

To display one or more array elements, enter the EXAMINE command followed by the array name and subscripts in parentheses, as in Fortran source statements. To display the entire array, enter EXAMINE following by the array name. For example:

DBG> TYPE 1:5 module ARRAY1 1: PROGRAM ARRAY1 2: INTEGER (KIND=4) ARRAY1(6) 3: ARRAY1 = 0 4: ARRAY1(1) = 1 5: ARRAY1(2) = 2 DBG> STEP 5 stepped to ARRAY1\%LINE 8 DBG> EXAMINE ARRAY1(1:2) ARRAY\ARRAY1(1): 1 ARRAY\ARRAY1(2): 2 DBG> EXAMINE ARRAY1 ARRAY\ARRAY1(1:6) (1): 1 (2): 2 (3): 0 (4): 0 (5): 0 (6): 0

4.4.5 Accessing HP Fortran Module Variables

To display a variable defined in a module, enter a SET MODULE command before examining module variables. For example, with a variable named PINTA defined in a module named MOD1, enter the following EXAMINE command to display its value:

DBG> SET MODULE MOD1 DBG> TYPE 1:6 1: PROGRAM USEMODULE 2: USE MOD1 3: INT4=0 4: INT4(1)=1 5: PINTA = 4 6: END PROGRAM USEMODULE DBG> STEP 4 stepped to USEMODULE\%LINE 6 6: END PROGRAM USEMODULE DBG> EXAMINE PINTA USEMODULE\PINTA: 4