Before you ship your product, you should test
it to ensure it works under most conditions. Thus NewBASIC provides debugging
facilities. You may run your program from within the Builder. The Builder
catches run-time errors in your BASIC code and displays the offending line.
You can also use the Builder to examine your program's variables, making
sure they hold the values you expect. There are various controls allowing
you to pause your program at arbitrary places so that you can examine its
variables at critical times.
The NewBASIC Builder primary window contains
a row of buttons used to run, pause, step, and stop a program. Depending
on your context, one or more of these buttons is likely to be disabled. For
instance, the Stop button is greyed out if your program isn't running. This
section explains what each button does.
- The Run button runs your program. It brings up
the program's user interface (UI) components and runs the module_init( )
routine. Your program is then ready for use. Use this button to test your
program and make sure it works. Note that while your program is running,
you won't be able to change it: you won't be able to move its UI components
around or edit its BASIC code. To make changes, you'll need to stop your
program.
- The Pause button temporarily halts your program.
This allows you to check on the state of your program's variables.
( See Examining and Changing Variables.) If
your program was in the middle of executing a BASIC routine, the Editor window
appears and the next line to be executed is highlighted in blue. If there
was a breakpoint set on that line, then it is
highlighted in purple.
- The Continue button causes your program to resume
execution if it has been paused.
- The Stop button quits your program. You can then
change your program: moving, adding, and removing components and editing
its BASIC code.
- The Single Step button is only useful if you're
paused in a BASIC routine; it executes the next line of code and then pauses
again. If the next line of code is a routine call (i.e., a function call
or a subroutine call), then it pauses at the beginning of that routine.
- The Routine Step button acts like the Single
Step button, except in its treatment of routine calls. Where Single Step
pauses at the beginning of the called routine ("steps into the routine"),
Routine Step executes the called routine and pauses at the next line of the
current routine ("steps over the routine").
- The Finish button finishes execution of the current
routine. If the current routine was called by some other routine, then it
finishes and then execution pauses in the routine that called the current
routine. Otherwise, this button behaves like the Continue button.
Perhaps the most common way to find mistakes in programs is to crash them.
For example, you might press the Run button, interact with your program a
bit, and then hear a number of beeps until a dialog box appears displaying
something like RTE-16: Attempted to divide by zero? What should you
do?
Finding the mistakes
Try these steps when you see an error message.
Note the message in the dialog box. It will give you some idea of what went
wrong.
- Press the OK.
A Call Stack dialog box will appear, giving you
a backtrace, showing what routines were called
when the error occurred.
If the bad code is in the module that you're editing, the Editor window will
appear.
- The offending line of BASIC code will be highlighted in blue to show that
execution is paused on that line.
- If there is a breakpoint set on that line, it
will be highlighted in purple.
- Try to determine the problem by examining the BASIC code. You may also examine
the values of your variables for clues about why the crash happened when
it did.
- Once you've figured out what the problem is, you can either press the Continue
button to skip the offending statement and attempt to continue executing
the program, or press the Stop button so that you'll be able to make the
necessary changes to your program.
Sometimes, you'll want to pause execution at a precise point in a BASIC routine.
To do this, set a breakpoint on the line where you'd like to pause
execution. The pause will happen just before the line is executed.
Setting a breakpoint
To set a breakpoint in a line of BASIC code, view the appropriate routine
in the Editor window and
- if your program is paused, click the correct line:
- It is drawn with a red background, signaling
that there is a breakpoint set on that line.
- It is drawn with a purple background instead
of red, if execution is currently paused on that line.
- if you are not currently running your program ( it is stopped or paused
):
- Click on the correct line of BASIC code.
- Press the Editor window's Toggle Breakpoint button.
Removing a breakpoint
To unset (remove) a breakpoint you set previously, do just what you would
do to add a breakpoint:
- click on the line of BASIC code in the Editor window, and
- press the Toggle Breakpoint button if you're not paused.
The line of BASIC code, which was drawn with a red background when it had
a breakpoint set on it, should now be drawn with a
white background. (If execution is currently
paused on this line, then turning off the breakpoint on that line will cause
its background to go from purple to blue, not red to white.)
Running the code
Having set/unset your breakpoints, press the
Continue or Run button. If execution ever encounters a line of BASIC code
with a breakpoint set on it, it will pause immediately.
You may wish to examine and/or change the values of your variables. To edit
a value, you need to pause your program.
- For a list of global variables, choose Global
Variables... from the Debug menu.
- For a list of the routine's local variables (if
any), choose Local Variables... from the Debug menu.
Both the Global Variables dialog and the Locals dialog show a list of variables
with values. To examine the contents of an array or STRUCT variable, click
on that variable's entry. You can also click on the entries of simple variables
to examine their values more closely or to change their values--a dialog
box appears which shows the current value of the variable and allows you
to change that value.
To see variables from other scopes, choose Call
Stack... from the Debug menu. ( See Variable
Scope.) A dialog box will appear, showing the list of currently executing
routines. Choosing any of the routine names from the list in the Call Stack
dialog box makes a window called <Frame> appear, showing the variables
local to that routine. The Editor window will show the source code of this
routine.