HP 3000 Manuals HP 3000 Manuals
Using xdb
The symbolic debugger xdb is a powerful debugging facility. Refer to the
HP Symbolic Debugger/iX User's Guide for a complete description of xdb.
There are two ways to compile your program with symbolic debugger
information:
* Use the info-string option to specify the symbolic debugger option
when you compile your program. For example:
:FTNXLLK test_xdb,testprog;INFO="symdebug xdb"
* Embed the symbolic debugger option in the first statement of your
source code. For example:
$SYMDEBUG XDB ON
PROGRAM test_debug
.
.
declarations
statements
.
.
END
To start the debugger on a program called test_xdb, execute the following
command:
xdb test_xdb
The symbolic debugger (xdb) is the primary tool for debugging a program
that does not execute properly. The debugger supports debugging
capabilities on C, FORTRAN, and Pascal programs.
In addition to the symbolic debugger, HP FORTRAN 77 offers a range
checking option for detecting run-time errors, as described earlier in
this chapter.
To analyze a program, the debugger uses the executable file and related
source files.
The debugger has many commands for viewing and manipulating your program.
This section discusses how you can use it to:
* Look at the execution stack
* Look at the contents of your source files
* Look at data values
* Control execution of your program with both single step execution
and the use of breakpoints
This section presents some basic getting started information for using
the symbolic debugger.
Table 9-1 lists some simple xdb commands that are described in this
chapter.
Table 9-1. Sample xdb Commands
-----------------------------------------------------------
| | |
| Command | Description |
| | |
-----------------------------------------------------------
| | |
| r | Run the program |
| | |
-----------------------------------------------------------
| | |
| b 82 | Set a breakpoint at line 82 |
| | |
-----------------------------------------------------------
| | |
| c | Continue running until the next |
| | breakpoint |
| | |
-----------------------------------------------------------
| | |
| s | Single step through the next source |
| | line |
| | |
-----------------------------------------------------------
| | |
| t | Print a trace of the current execution |
| | stack |
| | |
-----------------------------------------------------------
| | |
| v | View a "window" of lines |
| | |
-----------------------------------------------------------
| | |
| /string | Search forward in the source for |
| | string |
| | |
-----------------------------------------------------------
| | |
| p abc | Print the value of variable abc |
| | |
-----------------------------------------------------------
| | |
| p abc = 2.2 | Assign a new value to abc |
| | |
-----------------------------------------------------------
| | |
| p buffer\10d | Print the first 10 elements of array |
| | buffer in decimal format |
| | |
-----------------------------------------------------------
| | |
| q | Quit the debugger |
| | |
-----------------------------------------------------------
The Strategy
When your program does not execute properly, use the following strategy
to locate and correct any problems:
1. Invoke the symbolic debugger. The result is that you create a
debugging environment in which you can now execute your program.
2. Execute the program in the debugging environment and then use the
debugger commands to locate the execution bugs.
3. Once you have located the problem code, exit the debugger,
retrieve the appropriate source files, make the required changes,
recompile, and relink the program.
4. If your program still executes incorrectly, go back to running the
debugger.
Program Requirement
Before the symbolic debugger can be used to analyze a FORTRAN program,
you must compile the program with the SYMDEBUG XDB directive.
This ensures that necessary debugging information is incorporated into
the object code. Do not use the optimizer while debugging code because
the compiler cannot generate debug information and perform optimizations
at the same time.
Linker and Debugger Interaction
You should be aware that using the symbolic debugger greatly increases
the size of your program (often by a factor of two or three) because of
the tables it creates. When you execute your program in the debugger
environment, three tables are generated:
* A debug name and type table
* A value table
* A source line table
The debugger uses the first two tables to store information about program
status and data values, and it uses the latter to associate lines of
source code with object code.
Code for updating these tables is incorporated into a program's object
code. The result is that, once created by the debugger, the tables are
updated every time the linker is invoked to link the object files. The
linker does not allow you to inhibit this updating.
When your program is executing correctly and you no longer need the
symbolic debugger, you must recompile the source files and then relink
the object files to remove the debugging information. Without the
maintenance of the three debugger tables, the program occupies less space
and links faster. Also, in a program's production version, you probably
do not want to supply the debugger capabilities provided by the three
tables.
In some cases it may be necessary to maintain two versions of a program:
one with debugging information for software support purposes and a
production version that has the debugging information removed. If you
want the program to be sharable, it is necessary to remove the debugging
information from the production version because the debugger does not
work on sharable code.
Invoking the Debugger
Once you have prepared your program for the debugger and it is in an
executable file (in the following example called ALL), invoke the xdb
debugger by typing
xdb ALL
Note that xdb returns the number of procedures and, if you are not using
an HP terminal, prints the first executable line. If you are using an HP
terminal, the screen displays the first executable line of code
(surrounded by text) centered in the source window, a line with the file,
procedure, and line number information, and a command window. Then xdb
waits for you to input a command like
s
(which allows you to step through one line of code at a time).
Exiting the Debugger
To exit the debugger, type
q
You are prompted for confirmation that you really want to exit from xdb.
This is a safeguard in case you accidentally type the letter q.
Executing Your Program
To execute your program in the debugger environment, type
r
The r command allows you to specify any arguments that your program
needs. Simply follow the command with the argument list:
r; info="info string"; parm=375
Redirection arguments can be supplied as follows:
r; STDIN=READDATA; STDLIST=OUTFILE
This means that the input is coming from the file readdata and the output
is to be placed in the file outfile.
The program now has control and xdb waits for the program to terminate or
to receive a signal. A signal such as an interrupt from the terminal, a
memory fault, or a breakpoint in the program causes control to return to
xdb and the program to suspend.
If you need to kill the program process, type
k
which is interpreted by xdb as an interrupt signal.
Viewing the Execution Stack
The debugger supports an environment that provides detailed information
about the execution of your program. If the program halts incorrectly,
the debugger's execution stack can be useful in determining the reason.
Each time a routine is executed, the routine name is placed on the stack.
The bottom of the stack is always the main program routine and the top is
the name of the routine in which the program halted. To view the
debugger stack, type
t
The t command causes a maximum of 20 routine calls to be printed,
starting from the top of the stack. You can change the number of routine
calls shown by typing
t n
where n is the number of called routine names you want to see (a stack
depth of n).
The T command works the same as the t command, but the T command also
prints the values of the local variables for each of the routines on the
stack.
Viewing the Source File
The xdb debugger has several commands that you can use to look at your
program source file while you are in the debugger environment. The
debugger keeps track of the last file, routine, and line viewed (referred
to as the current file, current routine, and current line). The debugger
uses the last location viewed to determine the effect of several of its
commands.
The last viewed current values are not the same as the location of the
next line to be executed in the program. Changing the current file,
current routine, or current line by moving around in a source file does
not change the pointer to the next execution line. However, when program
execution is suspended, the last line executed becomes the current line
and the file and routine that contain it become the current file and
current routine.
To find out what the current file, routine, and line number values are,
type
v
The values are displayed in the form
file:procedure:line_number
To view a different file or routine, use the file or routine name as an
argument with the v command. For example, the command
v filename
makes filename the current file and displays its first executable line.
Similarly,
v procedurename
makes procedurename the current routine.
Once you are in the file or routine you want to view (that is, once it is
the current file), you can move around in the file with the p, +, -, /,
and ? commands. All of these commands change the current line value and
are described in the following sections.
The View Command.
The form of the view (v) command is
v line
where line is the line number of the first line you want printed in the
current file. If you do not specify line, the default is the current
line. Thus, typing v causes the current line to be printed in the center
of the source window, surrounded by the text file.
After using the v command, the new current line becomes the line
following the last line printed. If the line just printed is the last
line in the file, that line is the current line.
The Window Command.
The window (w) command changes the size of the source window to a new
value of n; n can range from 1 to 20. Changing the size of the source
window also changes the size of the command window.
The form of the command is
w n
The default value for n is two-thirds the length of the screen, minus
one. For most HP terminals, n is 15.
The Move Command.
The commands for moving around in a file, relative to the current line,
are + and -. The +n command moves n lines past the current line and the
-n command moves n lines before the current line. Specify the number of
lines you want to move by immediately following the command with the
number. If you do not specify the number of lines to move, the number
defaults to one.
For example,
+9
moves nine lines after the current line and the line you move to becomes
the new current line.
The Search Commands.
The / command searches forward through the current file and the ?
command searches backward. Follow both commands with the string you want
to search for. For example,
/doggie
causes a forward search for the string doggie.
Wild card characters and regular expressions that are supported by some
text editors are not supported by the debugger. You must literally
specify the string. If you do not specify a search string, the string
previously specified is used. Searches wrap around the beginning and end
of the file. When a search string is located, the line containing it
becomes the new current line.
Viewing Program Data
When your program execution is suspended, you can look at the current
values of its variables.
Listing the Variables.
The l command gives you a listing of the values of all of the parameters
and local variables in a particular routine. If l is typed by itself,
the listing is for the current routine. If you enter
l routine
the listing is for the routine in your program called routine.
Finding a Variable's Value.
You can find the value of a variable (or expression) with the p command:
p name
The debugger searches for a local variable or parameter called name in
the current routine.
The following example shows the command used with an expression:
p 1+2
The response is 3.
To find the value of a local variable or parameter in a routine other
than the current routine, type
p routine:name
which gives you the value of variable name during the most recent
execution of routine. If the debugger cannot find a local variable or
parameter called name in routine, the debugger looks for a common or
static variable with that name.
Execution Control
There are two primary ways of controlling the execution of your program
in the xdb environment:
* You can set breakpoints in the program that cause execution to be
suspended at particular locations.
* You can use the s or S commands to single step through the
program's execution.
Breakpoints
A breakpoint is a special debugger signal generator that can be inserted
in a particular location in your program where you want execution to
halt. Once you have halted the program, you can analyze its execution
environment.
To use breakpoints, you should know:
* How to set them
* How to recover from them
* How to delete them
Setting Breakpoints.
The command b sets breakpoints. It has many variations, but the simplest
one has the form
b
This causes a breakpoint to be set at the current line of the current
file and routine or the first executable statement following the current
line. Using the commands mentioned earlier in "Viewing the Source File"
, move to the location in your source file where you want the
breakpoint. The file, routine, and line that you move to becomes the new
current file, routine, and line. Type
v
to confirm what the current values are. To set the breakpoint, type
b
Another form of the b command allows you to specify any line in the
current file where you want a breakpoint set. It has the form
b n
where n is the number of the line.
Recovering from Breakpoints.
Breakpoints suspend program execution at particular locations. Once a
program is suspended, you can resume execution at the place where it
stopped with the c command.
Typing
c
causes the program to continue executing at the first executable
statement following the statement that caused its suspension.
Deleting Breakpoints.
To delete breakpoints from your program, use the db or db* command. The
db command removes one breakpoint, while db* removes all breakpoints. By
typing
db
you remove any breakpoint set at the current line. If there is no
breakpoint to remove, you receive a listing of all of the breakpoints in
your program. The lines of the listing are in the form
number routine:line count commands
number is an integer label that the debugger assigns to each breakpoint.
routine and line locate the breakpoint by routine name and line number.
count and commands are attributes of breakpoints that are described in
the HP Symbolic Debugger/iX User's Guide.
To request a listing of the breakpoints in your program, type
lb
To delete a breakpoint at a location other than the current line,
reference the breakpoint by the integer label number the debugger has
assigned to it. First, use the lb command to get a list of the
breakpoints and locate the one you want to delete. Next, use the number
label associated with the breakpoint together with the d command in the
form
d number
If you want to delete all of the breakpoints in your program, type
db*
Using Breakpoints for Execution Tracing.
One variation of the set breakpoint command is useful when you want to be
notified when a routine is called but do not want execution to halt. The
command
bp routine
causes routine's name to be printed when routine is called and then
resumes execution.
Single Step Commands
The commands for specifying single step execution of your program are the
s and S commands. Typing
s
executes one statement and suspends the program. Typing
s n
executes n statements before the program suspends.
The default value for n is 1.
The S command also allows single stepping through a program. When
routine calls are reached in the currently executing routine, they are
treated as statements and are executed. If, however, a called routine
contains a breakpoint, execution halts at that point. As with the s
command, you can specify the number of statements (n) to be executed.
To leave single step execution, use the c command. Typing
c
causes normal execution to resume.
Additional Debugger Capabilities
This chapter has given you a flavor of what the symbolic debugger can do
and how you use it; however, there is much more is available.
Capabilities that are not covered here are:
* The record/playback mechanism. Record mode allows you to record a
sequence of debugger commands that are required to get a program
into a particular state. You can then use the playback mode to
return the program to that state at any time.
* Assertion control commands. These commands are used to specify
sets of commands that are executed after every statement in your
program.
* Toggle disassembler/toggle source. This mode provides detailed
information by displaying the machine instructions and registers
used in the program's execution.
For more information on these capabilities, refer to the HP Symbolic
Debugger/iX User's Guide.
Removing Debugging Information
Once your program executes correctly, remove the debugging code that has
been incorporated into your program. The maintenance of the three tables
used by the symbolic debugger increases the amount of space required by
the program and slows down its linking speed. In addition, the tables
supply many debugging capabilities that are not necessary (and not
wanted) in the program's production version.
To remove the debugging code, you must recompile and relink the program
without the SYMDEBUG XDB directive.