======================================================================
INTERACTIVE DEBUGGER
======================================================================
PRODUCT: R:BASE VERSION : 4.0
AREA : TRACE CATEGORY: DEBUGGING DOCUMENT#: 657
======================================================================
The TRACE command in R:BASE 4.0 makes debugging any RBASE ASCII code
easier and less time consuming for both beginners and experts. Anyone
can use TRACE. It steps you through application code line by line,
checking for errors; it displays variable values as they change; and
it also has many other features to make debugging your code easy.
Starting TRACE
=============
Start the debugger either by using the Debugger option on the
Applications menu or by entering the TRACE command at the R> prompt.
When you use the Debugger option on the Applications menu, a menu
appears with a list of applications (.apx files) from which to choose.
Also on the menu is the Other... option, which prompts you for the
drive, directory, and name of the file to debug.
When using TRACE from the R> prompt the syntax is as follows:
TRACE filename.ext
If an application is involved, use this syntax:
TRACE application IN application.apx
Using TRACE
===========
Once you're in the debugger, the program code appears on the screen.
Near the top is a reverse video bar showing the line of code to be
executed next. At the bottom of the screen on the right side is the
name of the file you are currently debugging, the line number of the
current cursor position, and the total number of lines in the file.
Two important features of the debugger are the F10 key and the F6 key.
The F10 key steps through the code line by line, executing each line as
if you were running the commands normally. The F6 key allows you to
view variables and see their values change as you step through the code.
The debugger executes your code just as if you were running the
application. Menus appear, reports are printed, screen messages appear,
and forms display for data entry and editing. The debugger pauses for
user input where necessary; respond as if the application were running
normally.
An Example
==========
Below is a sample ASCII file to demonstrate the use of the F10 and F6
keys in the debugger. The file includes some errors so it demonstrates
what happens in the debugger when an error is encountered.
*(* TEST.CMD - an experimental test file that has no real use *)
SET QUOTE = "SET VAR v1 = 'this is a test'
SET VAR v2 = (SLEN(. v1))
SET VAR v3 = 1
WHILE v3 v2 THEN
SET VAR v3 = (. v3 + 1)
CLEAR ALL VAR
SET QUOTE= '
Running this file at the R> prompt with MESSAGES and ERROR MESSAGES ON
produces a "Syntax is incorrect for the command" error message and a
"Missing ENDWHILE, ENDIF or ENDSW" error message. Use the debugger to
find the commands or section of code that is generating the errors.
At the R> prompt, enter TRACE TEST.CMD. The code displays on the screen
and the reverse video bar is on line 3, SET QUOTES=". Note that the
initial comment line is ignored.
Press F10 to step through the code. The reverse video bar moves from
line 3 to line 4 with no errors. Press F10 again to move from line 4
to line 5, and you get an error.
The message indicates that the error occurred on line 4. The reverse
video bar is on line 5, but line 5 has not yet been executed. Press a
key to continue. Line 5 is still highlighted; it does not execute until
you press F10.
The error has occurred because of the incorrect use of quotation marks.
You can correct the error with either the R:BASE editor or another ASCII
text editor; you cannot edit the command file code directly in TRACE.
Because one error can cause others, always exit the debugger and fix an
error, then restart the debugger and continue. That way you'll know the
errors you're getting aren't due to an earlier problem in the program.
When you have corrected the first problem, restart the debugger and step
down to line 5 with the F10 key. Now press F6 to examine the variables.
Check off the variables to view (v2 and v3), and then press F2. The
checked variables and their current values are now displayed at the top
of the debugger screen. It's easy to see whether they have the correct
value and change correctly as you step through the program.
Press F10 and continue down through the sample program to line 7, where
the debugger tries to execute the WHILE statement. The debugger returns
you to the R> prompt or the menus with the "No ENDWHILE, ENDIF or ENDSW"
error message. The last line the debugger was able to execute was the
WHILE statement that is missing the ENDWHILE. The debugger checks for
an ENDWHILE statement before moving to the next line of code. Note that
you got an R:BASE error message, not a debugger error message. In some
cases the debugger is unable to continue and exits with a normal R:BASE
error message.
Add an ENDWHILE command after the SET VAR v3=(.v3+1) command. Restart
the debugger and using F10 and F6, step through the WHILE loop with the
F10 and F6 keys. You can see the control variable (v3) change at the top
of the debugger screen.
Continuous Execution
====================
The F10 key is useful for stepping through program code line by line,
but debugging hundreds of lines of code with it can become cumbersome.
The F5 key continuously executes code rather than stepping through line
by line. Pressing F5 on the first line of code causes the debugger to
execute the code until it comes to an error or a break point or runs
another file.
A break point is a line of code in which you designate that the debugger
is to stop executing. To set a break point, use the mouse or cursor keys
to move the cursor to the line of code on which to stop. Press F9 to set
the break point, then press F5. The debugger begins executing from the
highlighted line of code, not the current cursor position. You don't
have to move back to the top of the file once you have set a break point.
Just press F5 - the debugger remembers the last line of code it executed.
The debugger executes code until it reaches the break point, finds an
error, or encounters a RUN command. Respond normally to menus and provide
other user input as necessary. Keep pressing F5 until the debugger stops
at your break point. Then use F10 to single step through to the error and
use F6 to view variables.
TRACE Options
=============
The TRACE command includes many other options. The ones described above
can quickly get you started debugging your custom program code.
You can see a brief description of each function key by pressing Shift-F1
while in the debugger. For more detailed information on the debugger,
refer to the Command Dictionary and the Guide to Software Installation
and New Features.