Compaq Fortran
User Manual for
OpenVMS Alpha Systems

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.
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.
The SHOW LOGICAL DBG$PROCESS command shows that the logical name DBG$PROCESS is undefined, thus the debugger starts in the default configuration.
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).
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.
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.
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
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.
The DEPOSIT command assigns K the value it should have now: 1.
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.
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.
The EXIT command returns control temporarily to DCL level so that you can correct the source file and recompile and relink the program.
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.)
The revised program is compiled and linked.
The RUN SQUARES (DCL command) starts the debugger using the revised program so that its correct execution can be verified.
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.
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.
The EXIT command ends the debugging session, returning control to DCL level.

4.4 Displaying Compaq Fortran Variables

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

4.4.1 Accessing Compaq Fortran Common Block Variables

To display common block variables, type 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 Compaq Fortran Derived-Type Variables

To display derived-type structure variables, type 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 Compaq Fortran Record Variables

To display a field in a record structure, type the EXAMINE command followed by the record name, a period (.), and the field name. To display the entire record structure, type EXAMINE command 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 Compaq Fortran Array Variables

To display one or more array elements, type the EXAMINE command followed by the array name and subscripts in parentheses, as in Fortran source statements. To display the entire array, type 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 Compaq Fortran Module Variables

To display a variable defined in a module, type 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

4.5 Debugger Command Summary

The following sections list all the debugger commands and any related DCL commands in functional groupings, along with brief descriptions. See the debugger's online help for complete details on commands.

During a debugging session, you can get online HELP on any command and its qualifiers by typing the HELP command followed by the name of the command in question. The HELP command has the following form:

HELP command

4.5.1 Starting and Terminating a Debugging Session

$ RUN	Invokes the debugger if LINK/DEBUG was used.
$ RUN/[NO]DEBUG	Controls whether the debugger is invoked when the program is executed.
DBG> Ctrl/Z or EXIT	Ends a debugging session, executing all exit handlers.
DBG> QUIT	Ends a debugging session without executing any exit handlers declared in the program.
DBG> Ctrl/C	Aborts program execution or a debugger command without interrupting the debugging session.
DBG> SET DBG> SHOW ABORT_KEY	Assigns the default Ctrl/C abort function to another Ctrl-key sequence or identifies the Ctrl-key sequence currently defined for the abort function.
$ Ctrl/Y DEBUG	The sequence Ctrl/Y DEBUG interrupts a program that is running without debugger control and invokes the debugger.
DBG> ATTACH	Passes control of your terminal from the current process to another process (similar to the DCL command ATTACH).
DBG> SPAWN	Creates a subprocess; lets you issue DCL commands without interrupting your debugging context (similar to the DCL command SPAWN).
$ DEBUG/KEEP	Invokes the kept debugger, which allows certain additional commands to be used, including RUN and RERUN.
DBG> RUN image-name	When using the kept debugger, runs the specified program.
DBG> RERUN	When using the kept debugger, runs the last program executed again.

4.5.2 Controlling and Monitoring Program Execution

GO	Starts or resumes program execution.
STEP	Executes the program up to the next line, instruction, or specified instruction.
SET SHOW STEP	Establishes or displays the default qualifiers for the STEP command.
SET SHOW CANCEL ACTIVATE DEACTIVATE BREAK	Sets, displays, cancels, activates, or deactivates breakpoints.
SET SHOW CANCEL ACTIVATE DEACTIVATE TRACE	Sets, displays, cancels, activates, or deactivates tracepoints.
SET SHOW CANCEL ACTIVATE DEACTIVATE WATCH	Sets, displays, cancels, activates, or deactivates watchpoints.
SHOW CALLS	Identifies the currently active subroutine calls.
SHOW STACK	Gives additional information about the currently active subroutine calls.
CALL	Calls a subroutine.

4.5.3 Examining and Manipulating Data

EXAMINE	Displays the value of a variable or the contents of a program location
SET MODE [NO]OPERANDS	Controls whether the address and contents of the instruction operands are displayed when you examine an instruction.
DEPOSIT	Changes the value of a variable or the contents of a program location.
EVALUATE	Evaluates a language or address expression.

4.5.4 Controlling Type Selection and Symbolization

SET SHOW CANCEL RADIX	Establishes the radix for data entry and display, displays the radix, or restores the radix.
SET SHOW CANCEL TYPE	Establishes the type for program locations that are not associated with a compiler generated type, displays the type, or restores the type.
SET MODE [NO]G_FLOAT	Controls whether double-precision floating-point constants are interpreted as G_FLOAT or D_FLOAT. You can also use SET TYPE or EXAMINE commands to define untyped program locations, such as SET TYPE S_FLOAT, EXAMINE/T_FLOAT, or EXAMINE/X_FLOAT.

4.5.5 Controlling Symbol Lookup

SHOW SYMBOL	Displays symbols in your program
SET SHOW MODULE	Sets a module by loading its symbol records into the debugger's symbol table, identifies a set module, or cancels a set module.
SET SHOW IMAGE	Sets a shareable image by loading data structures into the debugger's symbol table, identifies a set image, or cancels a set image.
SET MODE [NO]DYNAMIC	Controls whether modules and shareable images are set automatically when the debugger interrupts execution.
SET SHOW CANCEL SCOPE	Establishes, displays, or restores the scope for symbol lookup.
SET MODE [NO]LINE	Controls whether code locations are displayed as line numbers or routine-name + byte offset.
SET MODE [NO]SYMBOLIC	Controls whether code locations are displayed symbolically or as numeric addresses.
SYMBOLIZE	Converts a virtual address to a symbolic address.

4.5.6 Displaying Source Code

TYPE	Displays lines of source code.
EXAMINE/SOURCE	Displays the source code at the location specified by the address expression.
SET SHOW CANCEL SOURCE	Creates, displays, or cancels a source directory search list.
SEARCH	Searches the source code for the specified string.
SET SHOW SEARCH	Establishes or displays the default qualifiers for the SEARCH command.
SET STEP [NO]SOURCE	Enables or disables the display of source code after a STEP command has been executed or at a breakpoint, tracepoint, or watchpoint.
SET SHOW MAX_SOURCE_FILES	Establishes or displays the maximum number of source files that may be kept open at one time.
SET SHOW MARGINS	Establishes or displays the left and right margin settings for displaying source code.

4.5.7 Using Screen Mode

SET MODE [NO]SCREEN	Enables or disables screen mode.
SET MODE [NO]SCROLL	Controls whether an output display is updated line by line or once per command.
DISPLAY	Modifies an existing display.
SET SHOW CANCEL DISPLAY	Creates, identifies, or deletes a display.
SET SHOW CANCEL WINDOW	Creates, identifies, or deletes a window definition.
SELECT	Selects a display for a display attribute.
SHOW SELECT	Identifies the displays selected for each of the display attributes.
SCROLL	Scrolls a display.
SAVE	Saves the current contents of a display and writes it to another display.
EXTRACT	Saves a display or the current screen state and writes it to a file.
EXPAND	Expands or contracts a display.
MOVE	Moves a display across the screen.
SET SHOW TERMINAL	Establishes or displays the height and width of the screen.
Ctrl/W DISPLAY/REFRESH	Refreshes the screen.

4.5.8 Editing Source Code

EDIT	Invokes an editor during a debugging session.
SET SHOW EDITOR	Establishes or identifies the editor invoked by the EDIT command.

4.5.9 Defining Symbols

DEFINE	Defines a symbol as an address, command, value, or process group.
DELETE	Deletes symbol definitions.
SET SHOW DEFINE	Establishes or displays the default qualifier for the DEFINE command.
SHOW SYMBOL/DEFINED	Identifies symbols that have been defined.

4.5.10 Using Keypad Mode

SET MODE [NO]KEYPAD	Enables or disables keypad mode.
DEFINE/KEY	Creates key definitions.
DELETE/KEY	Deletes key definitions.
SET KEY	Establishes the key definition state.
SHOW KEY	Displays key definitions.

4.5.11 Using Command Procedures and Log Files

DECLARE	Defines parameters to be passed to command procedures.
SET SHOW LOG	Specifies or identifies the debugger log file.
SET OUTPUT [NO]LOG	Controls whether a debugging session is logged.
SET OUTPUT [NO]SCREEN_LOG	Controls whether, in screen mode, the screen contents are logged as the screen is updated.
SET OUTPUT [NO]VERIFY	Controls whether debugger commands are displayed as a command procedure is executed.
SHOW OUTPUT	Displays the current output options established by the SET OUTPUT command.
SET SHOW ATSIGN	Establishes or displays the default file specification that the debugger uses to search for command procedures.
@file-spec	Executes a command procedure.

4.5.12 Using Control Structures

IF	Executes a list of commands conditionally.
FOR	Executes a list of commands repetitively.
REPEAT	Executes a list of commands repetitively.
WHILE	Executes a list of commands conditionally, possibly multiple times.
EXITLOOP	Exits an enclosing WHILE, REPEAT, or FOR loop.

4.5.13 Additional Commands

SET PROMPT	Specifies the debugger prompt.
SET OUTPUT [NO]TERMINAL	Controls whether debugger output is displayed or suppressed, except for diagnostic messages.
SET SHOW LANGUAGE	Establishes or displays the current language.
SET SHOW EVENT_FACILITY	Establishes or identifies the current run-time facility for language-specific events.
SHOW EXIT_HANDLERS	Identifies the exit handlers declared in the program.
SET SHOW TASK	Modifies the tasking environment or displays task information.
DISABLE ENABLE SHOW AST	Disables the delivery of ASTs in the program, enables the delivery of ASTs, or identifies whether delivery is enabled or disabled.
SET MODE [NO]SEPARATE	Controls whether a separate window is created on a workstation for debugger input and output (this command has no effect on VT-series terminals).

For More Information:

On Debugger commands and the DECwindows Motif interface, see the OpenVMS Debugger Manual.
On Debugger command syntax, type the online debugger HELP command.

4.6 Locating an Exception

The OpenVMS Debugger supports the SET BREAK/EXCEPTION and SET TRACE/EXCEPTION commands to set a breakpoint or tracepoint when an exception occurs. To allow precise reporting of the exception, compile the program using:

The FORTRAN command qualifier /SYNCHRONOUS_EXCEPTIONS
The FORTRAN command qualifier /CHECK=ALL (in general) or /CHECK=FP_EXCEPTIONS (if you know it is a floating-point exception)
The FORTRAN command qualifiers /DEBUG and /NOOPTIMIZE

If you use the FORTRAN command qualifier /FLOAT=IEEE_FLOAT to specify IEEE floating-point (S_float and T_float) data, you can also use the /IEEE_MODE qualifier to indicate how exceptions should be handled.

For example, you might use the following commands to create the executable program:

$ FORTRAN/DEBUG/NOOPTIMIZE/FLOAT=IEEE_FLOAT/SYNCHRONOUS_EXC/CHECK=ALL TEST (1) $ LINK/DEBUG TEST $ RUN TEST OpenVMS Alpha DEBUG Version x.x-xxx %DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARES %DEBUG-I-NOTATMAIN, type GO to get to start of main program DBG> GO (2) break at routine TEST$MAIN 1: REAL (KIND=4) :: A,B DBG> SET BREAK/EXCEPTION DO (SHOW CALLS) (3) DBG> GO (4) %SYSTEM-F-HPARITH, high performance arithmetic trap, Imask=00000000, Fmask=00000002, summary=08, PC=00020050, PS=0000001B (5) -SYSTEM-F-FLTOVF, arithmetic trap,floating overflow at PC=00020050,PS=0000001B break on exception preceding TEST$MAIN\%LINE 3+20 3: B=A*A module name routine name line rel PC abs PC *TEST$MAIN TEST$MAIN 3 00000050 00020050 00000130 00020130 SHARE$DEC$FORRTL 00000000 000B0A30 00000130 00020130 00000000 84F4BAD8 DBG> TYPE 1:3 (6) 1: REAL (KIND=4) :: A,B 2: A=2.5138E20 3: B=A*A DBG> EXIT $

The FORTRAN command line specifies qualifiers that ensure reporting of exceptions and sufficient information for debugging.
The LINK command /DEBUG qualifier requests that debug symbol information be included in the executable image.
The first Debugger GO command is needed because run-time checking was requested.
The Debugger command SET BREAK/EXCEPTION sets a breakpoint for exceptions. If omitted, the exception is not reported.
The second Debugger GO command runs the program.
The "%SYSTEM-F-HPARITH, high performance arithmetic trap" message indicates an exception has occurred. The "-SYSTEM-F-FLTOVF, arithmetic trap, floating overflow " message indicates the type of exception. The remaining display (requested by SHOW CALLS command) shows the routine and line number where the error occurred.
The TYPE command displays the area of source code associated with the exception.