FDEBUG - an interactive symbolic debug tool.

Request summary:

!TSS command
CAll name(expr,expr,...)
DONE
FUnction name
IF ( expr ) request
MAin
QUIT
REturn
SHow
SUbroutine name
[n] COntinue
[n] PAUSE
[n] PRINT expr, expr, ...
[n] STOP
n GOto label
var = expr

Usage:

integer di, do
...
call fdebug
call fdebug( di )
call fdebug( di, do )

Where:

di: is the logical unit from which to read debugging requests. This defaults to the terminal in TSS and unit 44 in batch.
do: is the logical unit on which to write the debugger's output. This defaults to the terminal in TSS or unit 06 in batch.

Description:

FDEBUG is a very powerful tool for finding out where a program is going wrong. It is normally used interactively at the terminal but may be driven by input from a file. FDEBUG is entered if it is called from your program, if a breakpoint (PAUSE request) from a previous call is encountered during execution, or if you hit break after calling FDEBUG for the first time.

If you hit carriage return immediately after entering FDEBUG, you will get a traceback showing the routines called to get your program to its present context. To get a traceback again, you must first use the MA, FU or SU request to reestablish the debugging context, then hit carriage return again. Note that until FDEBUG is called the first time, hitting break in TSS will cause your program to cease execution.

In batch, FDEBUG can be invoked by including the FDS option in the operand field of the $FORT77 control line. FDEBUG requests can be planted by supplying debugging requests on logical unit 44 using $DATA~44 or equivalent control cards. This works for both EXECUTE and RLHS activities.

In TSS, if you want FDEBUG to be called during F77 run-time initialization, you can specify the +FDS option on the F77 command line. You must also call FDEBUG at some convenient point in the program (say the first executable line of the main program).

Another way to call FDEBUG during TSS Fortran run-time initialization is to specify the +FDeBug option on the F77 command. As long as +FDS was specified when the program was compiled, you can use +FDeBug when running the compiled program.

f77 .h +fdebug 05</data

This works by setting switch bit 48, so the set of commands

switch +48
f77 .h 05</data

would have the same effect.

Requests:

With some exceptions, debugging requests can be executed in one of two ways. If a request is not preceded by a statement label, FDEBUG interprets the request immediately. If a request is preceded by a statement label, FDEBUG plants the request at the indicated statement. When the program is executing, such a request will be interpreted before the indicated statement is executed but after any requests previously planted at that statement are executed.

In the request descriptions below, the following conventions and notations are used.

The upper case portion of the request indicates the minimum acceptable abbreviation.
If the request is preceded by [n], it indicates a request that may be planted at the statement with label n for later interpretation.
"expr" denotes an expression formed from variables (including array elements), constants and the operators +, -, *, /, **, .EQ., .NE., .LE., .LT., .GE., .GT., .AND., .OR., and .NOT. The Fortran rules of expression formation apply, except that the exponent in ** must be INTEGER. Note also that function calls (built-in or external) are not permitted in expressions.

MAin, SUbroutine name, FUnction name: These requests establish the MAIN program or subprogram "name" as the context in which subsequent requests are to be interpreted. Whenever FDEBUG is entered, the context will initially be set to the Fortran subprogram in control at that time. The subroutine nesting list may be obtained whenever the context is changed, simply by typing a carriage return.
REturn: REturn returns control to the executing program.
SHow: SHow will display the location and text of currently planted requests.
!TSS command: This lets you call any TSS subsystem or command from FDEBUG. The request is not available in batch.
[n] STop, [n] DOne, [n] QUit: STop, DOne, QUit terminate execution of the program.
[n] PAuse: If the statement label is omitted, the request is ignored. Otherwise, a breakpoint is planted at the indicated statement. FDEBUG will be entered whenever the breakpoint is encountered during execution.
[n] PRint expr, expr, ...: The values of the expressions are printed in an appropriate format. At the moment it is not possible to specify a part of an array to be printed, but this can be accomplished with the CALL request (see below).
[n] var = expr: The value of the variable "var" is set to the value of "expr". The Fortran rules of assignment apply except that a CHARACTER expression may be assigned to an INTEGER.
[n] CAll GCALF7 (sub-name, arg, arg, ...): Subroutine "sub-name" is called. This request is provided so that the rather primitive output facilities in FDEBUG can be extended with user-supplied or system-supplied subroutines. Do not call subroutines which themselves contain planted FDEBUG requests, since hopeless confusion can result. It is not wise to call subprograms which perform Fortran I/O if FDEBUG gained control through an interrupt (break).
[n] IF ( expr ) request: The logical expression "expr" is evaluated and if the value is .TRUE., the request which follows will be interpreted.
[n] COntinue: If the statement label is omitted, the request is ignored. Otherwise all requests planted at that statement will be removed.
[n] GOto label: A GOTO statement is planted at the indicated statement. It must be planted and cannot be executed directly. Note that this request should be used with extreme caution, especially in optimized Fortran subprograms.

It should be pointed out that debugging of optimized programs may be complicated by the fact that the values of certain variables are often kept in registers rather than in memory. This is particularly true of DO loop indices in loops which exit only from the bottom. In this case, it is not possible to print the value of the DO loop index (it appears to remain constant) or to make use of the value in other ways.

To print the values of variables or segments of arrays in other than the default format, it has been found useful to have your program include subroutines similar to the following.

SUBROUTINE PR (A,N,FORMAT)
INTEGER A(N), FORMAT (1)
WRITE (6,FORMAT) A
RETURN
END

FDEBUG requests like

CALL PR (ARRAY,3,"(1X,3A6)")

can be used to print data under special formats. This example prints the first three elements of ARRAY under A6 format.

To make debugging link overlay jobs less tedious, there is a system supplied subroutine of the form

      SUBROUTINE LODLNK(LINK)
      CHARACTER*6 LINK
1     RETURN
      END

which is called by the LINK/LLINK overlay subroutine immediately after loading a link.

To pass control to FDEBUG after a certain link has been loaded, an appropriate conditional request may be planted in this subroutine. For example, the sequence

SUBROUTINE LODLNK
1 IF(LINK .EQ. "A") PAUSE

will plant a request which causes FDEBUG to be entered immediately after link A is loaded. Note that any requests previously planted in the region overlaid will be forgotten. The SHow request can always be used to discover which requests are still present. Note that CALL LINK can cause the currently executing link to be overlaid and thus destroy the subroutine nesting list and possibly LODLNK; therefore control is passed directly to the link entry point by LINK without calling LODLNK. In this case, it is not possible to pass control to FDEBUG and it is recommended that LLINK be used instead. Another virtue of using LLINK is that the program is more easily moved to other environments by simply supplying a dummy subroutine called LLINK.

Known Bugs:

The FDEBUG requests MAin, SUbroutine, and FUnction may not work in some programs (for unknown reasons).

When FDEBUG gets control before execution starts, it responds to requests with "symbol table empty or missing". The reason is that it has no context: use MAin, SUbroutine, or FUnction to give it one and you will be able to plant requests.

FDEBUG will not allow you to say GOTO label. You must plant this request (this is more of a restriction than a bug).

If the CAll request is used to call a debugging subroutine, break service is turned off. If the subroutine goes into a loop, no amount of hitting break will get you out.