DBX90(1)

NAME
dbx90 — a Fortran-oriented debugger for use with the NAG Fortran compiler.

USAGE
dbx90 [option]... executable-file

DESCRIPTION
dbx90 is a Fortran-oriented debugger for use with the NAG Fortran Compiler on Unix-like systems (e.g. Linux, Solaris). Its syntax is quite similar to that of dbx, which it invokes as a sub-process to carry out the actual machine-dependent debugging commands. (On gcc-based implementations, gdb is used.)

The program to be debugged should be compiled and linked with the -g90 option. This creates a debug information (.g90) file for each Fortran source file.

If the environment variable DBX90_DBXPATH is defined, dbx90 will use it to locate the native debugger instead of the built-in path.

OPTIONS

-compatible
    This permits dbx90 to debug code compiled by the NAG Fortran Compiler using the -compatible option.

-I pathname
    Add pathname to the list of directories which are to be searched for module information (.mod) files and debug information (.g90) files. The current working directory is always searched first, then any directories named in -I options, then the compiler's library directory (usually `/usr/local/lib/NAG_Fortran' or `/opt/NAG_Fortran/lib')

-Qpath path
    Set the compiler's library directory to path. This is only used for finding the module information (.mod) files for intrinsic modules.

@CODE{DBX90} COMMANDS

alias
    List command aliases.

alias name text
    Create a new alias name with the replacement value text. The replacement text is not limited to a single word but may contain spaces.

assign var = expr
    Assign the value of expr to variable var. The variable can be scalar, an array (including an array section), a scalar component, or an element of an array component, but cannot be of derived type. The value must be a scalar expression (see "Expressions" for more details).

cont
    Continue execution from where it was stopped (either by a breakpoint or an interrupt).

delete n
    Delete breakpoint number n.

delete all
    Delete all breakpoints.

display
    List the expressions to be displayed after each breakpoint is reached.

display expr
    Add expr to the list of expressions to display after each breakpoint. Expr may also be an array section.

dump
    Display all local variables and their values.

down [n]
    Move the focus down (i.e. to the procedure called by the current procedure). If n is present, move down n levels.

help [topic]
    Display a brief help message on the specified topic, or on using dbx90 generally.

history
    List the history command buffer. Old commands can be executed with:

    !!  repeat last command,

    ! n repeat command n in the history buffer, and

    ! -n
        repeat the nth last command.

history n
    Set the size of the history command buffer to n commands. The default size of the history command buffer is 20.

if expr
    This is actually a suffix to the breakpoint (`stop') commands not an independent command. It prevents the triggering of the breakpoint until the expression expr (a scalar expression) is .TRUE. (or non-zero).

list [line1[,line2]]
    Display the next 10 lines of the program, display line line1 of the current file or display lines line1 to line2 of the current file.

next [n]
    Execute the next n lines (default 1) of the current (or parent) procedure. Any procedure reference in these lines will be executed in its entirety unless a breakpoint is contained therein.

print expr [,expr]...
    Display the value of expr, which can be a scalar expression, array section, derived type component,or a variable of any data type. Several expressions may be given separated by commas.

quit
    Exit from dbx90, immediately terminating any program being debugged.

raw dbx-command
    Pass dbx-command directly to "dbx". This is not recommended for normal use.

rerun [command-line]
    Begin a new execution of the program, passing command-line to it (if present) or the command-line from the previous run or rerun command if not.

run [command-line]
    Begin a new execution of the program, passing command-line to it (if present) or blank command line if not.

scope [name]
    Display the current procedure name or set the focus to the specified procedure name.

status
    List the breakpoints which are currently set.

step [n]
    Execute the next n lines (default 1) of the program, counting lines in referenced procedures (i.e. step into procedure references).

stop name
    Set a breakpoint which triggers when variable name is accessed. Note that name cannot be `at' or `in'. This command is not available on Solaris or HP-UX.

stop at lineno
    Set a breakpoint at line lineno of the file containing the current procedure.

stop in name
    Set a breakpoint at the beginning of procedure name. Note that this breakpoint occurs at the beginning of procedure initialisation, not at the first executable statement. If there is no procedure called `MAIN', the main program can be specified using that name.

undisplay expr
    Remove expr from the "display" list.

up [n]
    Move the focus up (i.e. to the caller of the current procedure). If n is present, move up n levels.

whatis name
    Describe how name would be explicitly declared.

where
    Display the stack of active procedures with their dummy argument names.

which name
    Display the fully qualified form of name which can be used for access from another scope.

@CODE{DBX90} EXPRESSIONS

  Scalar expressions
Scalar expressions in dbx90 are composed of literal constants, scalar variable references including array elements, intrinsic operations and parentheses.

Literal constants can be of any intrinsic type, e.g.

INTEGER
    42

REAL
    1.2
    1.3e2

COMPLEX
    (5.2,6.3)

CHARACTER
    "string"

LOGICAL
    .TRUE.
    .T.

Subscript expressions must be scalar and of type INTEGER.

All intrinsic operations are supported except for exponentiation and concatenation, that is:
    +, -, *, /, ==, /=, <, <=, >, >=, .AND., .OR., .NOT., .EQV., .NEQV., .EQ., .NE., .LT., .LE., .GT., .GE.
(Operator names are not case-sensitive).

Note: array operations and operations involving variables of complex, character or derived type are not supported.

  Array sections
Assignment, printing and displaying of array sections follows the Fortran syntax, e.g.

   ARRAY(:)
   ARRAY(1:5)
   ARRAY(1:10:2)

If the stride is supplied it must be a positive scalar expression - negative strides are not supported. All subscript expressions must be scalar - vector subscripts are not supported.

  Derived type component specification
Individual components of a derived type scalar or array may be printed using normal Fortran syntax.

For example,

     print var%a
will print the "a" component of derived type "var".

Components of all data types are supported.

Components which are of derived type will be displayed recursively until either:

•   there are no further nested derived types, or

•   a derived type array component is reached.

Array components of intrinsic data types will be truncated to `<array>', and derived type array components will be truncated to `<derived type array>'.

Allocatable components of derived types are supported.

Derived type assignment is not supported; however, scalar non-derived-type components may be assigned values.

@CODE{DBX90} COMMAND ALIASES
The following set of command aliases are defined:

  a      assign
  b      stop at
  bp     stop in
  c      cont
  h      history
  l      list
  n      next
  p      print
  q      quit
  r      rerun
  s      step

New aliases may be created using the alias command, e.g.

  alias xp1 print x+1

@CODE{DBX90} LIMITATIONS
Breakpoints set at the beginning of a routine occur before procedure initialisation; at this point attempting to print or display an assumed-shape dummy argument, a variable with a complicated EQUIVALENCE or an automatic variable will produce dbx crashes, dbx90 crashes or nonsensical output. Execution must be stepped to the first executable statement (e.g. using the next command or by setting a second breakpoint) before any of these will work satisfactorily.

Strides in array sections must be positive.

EXAMPLE OF @CODE{DBX90}
This is an example of the use of dbx90 in debugging some Fortran code which contains both COMMON blocks and modules.

The file to be debugged is called `fh4.f90' and contains:

    MODULE fh4
      REAL r
    END MODULE fh4
    PROGRAM fh4_prog
      USE fh4
      COMMON/fh4com/i
      i = 2
      CALL sub
      PRINT *,i,r
    END PROGRAM fh4_prog
    SUBROUTINE sub
      USE fh4
      COMMON/fh4com/i
      r = 0.5*i
      i = i*3
    END SUBROUTINE sub

It is first compiled with the -g90 option and then run under dbx90:

    % nagfor -g90 -o fh4 fh4.f90
    % dbx90 fh4
    NAG dbx90 Version 5.2(22)
    Copyright 1995-2008 The Numerical Algorithms Group Ltd., Oxford, U.K.
    GNU gdb Red Hat Linux (6.5-15.fc6rh)
    Copyright (C) 2006 Free Software Foundation, Inc.
    GDB is free software, covered by the GNU General Public License, and you are
    welcome to change it and/or distribute copies of it under certain conditions.
    Type "show copying" to see the conditions.
    There is absolutely no warranty for GDB.  Type "show warranty" for details.
    This GDB was configured as "i386-redhat-linux-gnu"...Using host libthread_db lib
    rary "/lib/libthread_db.so.1".
    (dbx90)

Setting a breakpoint in routine SUB and running the program.

    (dbx90) stop in sub
    [1] stop in SUB in file "fh4.f90"
    (dbx90) run
    stopped in SUB at line 16 in file "fh4.f90"
       16     r = 0.5*i
    (dbx90)

Printing the value of a variable, which may be local, in a COMMON block, or in a USEd module.

    (dbx90) print i
    I = 2
    (dbx90) next
    17        i = i*3
    (dbx90) print r
    R = 1
    (dbx90) next
    18      END SUBROUTINE sub
    (dbx90) print i
    I = 6

Variables can also be assigned values.

    (dbx90) assign i = 7
    I  = 7
    (dbx90) cont
     7   1.0000000
    Program exited normally.
    (dbx90) quit
    %

TROUBLESHOOTING @CODE{DBX90}
The diagnostic messages produced by dbx90 itself are intended to be self-explanatory.

If you receive the error message `Cannot exec dbx' when starting dbx90 then you must set the environment variable DBX90_DBXPATH to the pathname of dbx (or gdb, or xdb).

SEE ALSO
dbx(1), gdb(1), nagfor(1).

BUGS
It is called dbx90 because it was first available for Fortran 90; that name is no longer appropriate. Please report any other bugs found to `support@nag.co.uk' or `support@nag.com', along with any suggestions for improvements.