Debugging

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.


Running, Pausing, and Stopping

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.


Crash Recovery

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.

  1. 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.
  2. The offending line of BASIC code will be highlighted in blue to show that execution is paused on that line.
  3. If there is a breakpoint set on that line, it will be highlighted in purple.
  4. 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.
  5. 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.


Breakpoints: Pausing in Routines

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

Removing a breakpoint

To unset (remove) a breakpoint you set previously, do just what you would do to add a breakpoint:

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.


Examining and Changing Variables

You may wish to examine and/or change the values of your variables. To edit a value, you need to pause your program.

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.