Debugging Scripts

Bugs are errors in a script that keep it from performing as intended. Debugging is the process of locating and fixing these errors. The most common bugs are typographical errors in scripts or malformed instructions. Scripter detects these types of errors immediately when you try to run a script. The program beeps, highlights the line containing the error in red (or whatever color has been set with View | Colors command), and displays an error message on the status bar.

Viewing Errors

Before running a script, verify that the View | Status Bar command is enabled, otherwise you will not see the error message. To resolve the errors that Scripter immediately detects, you usually must interpret the error message and correct the indicated problem. Typical errors are typing mistakes, unbalanced parentheses, misuse of a BASIC language instruction, or failure to declare variables in a DIM statement (if you use the OPTION EXPLICIT statement). If you do not see an obvious problem, refer to the online BASIC language help to make sure you are using the right syntax.

Run-Time Errors

Scripts that encounter errors midway through script execution may be fixed much the same way as syntax errors. The error message should guide your actions. Some run-time errors cannot be detected until they are executed, such as when you try to open a file that does not exist. In these cases, you need to check for error conditions in your scripts. For example, use the DIR function to make sure a file exists before trying to open it. Alternatively, you can use the ON ERROR GOTO statement to specify an error handling section to execute when a procedure encounters a run-time error:

Sub OpenFile(mvApp As Object, filename As String)

On Error Goto ErrLabel

mvApp.Documents.Open filename

Exit Sub

ErrLabel:

MsgBox "Unable to open file " & filename

Exit ' Must use RESUME or EXIT at end of error handling code

End Sub

Script Runs Incorrectly

Most difficult to correct are scripts which run, but do not work as expected. Fixing these scripts is hard because you do not know which line or statement is causing the problem. Scripter provides a number of debugging features to help you locate the source of problems.

Debug.Print

Probably the simplest debugging technique is to insert instructions into your script to monitor the progress of the script and display the values of variables at various points throughout the script. Use the Debug.Print statement to display information in the Scripter immediate window:

Debug.Print "The value of variable X is "; X

To clear the contents of the immediate window, select the text in the window and press either DEL or BACKSPACE.

Stop or Pause

Insert the STOP instruction to pause script execution where you think there might be a problem. While the script is paused, you can examine and change the values of program variables. If a running script appears unresponsive, it may be stuck in an infinite loop. Select the Script | Pause command or click the $image\scr-pause.gif$ button to pause the script. To resume executing a paused script, select the Script | Run command or click $image\scr-run.gif$ .

Viewing Variable Values

While a script is paused, there are several ways to view the value of a variable:

In the immediate window, type a question mark followed by the variable name and press ENTER. The current value of the variable is displayed.
In the code window, place the cursor on the variable name you want to examine (that is, click on the variable name in the code window). Press SHIFT+F9, select the Debug | Quick Watch command, or click the $image\scr-watch.gif$ button on the toolbar. The current value of the variable is displayed in the immediate window.
To continuously monitor a variable's value, click on the variable name in the code window, and press CTRL+F9 or select the Debug | Add Watch command. Alternatively, type the variable name in the watch window and press ENTER. The variable name and its value are displayed in the watch window. Every time script execution pauses, the variable value is automatically updated. To clear a variable from the watch window, highlight the line showing the variable value and press the DEL or BACKSPACE key.

Changing Variable Values

To change the value of a variable, type an assignment expression in the immediate window and press ENTER. For example, type "A=5" (without quotes) and press ENTER to assign a new value to the variable named "A."

Step

A powerful debugging technique is to watch Scripter execute your script one line at a time. This lets you check the effect of each instruction and verify that the script is doing what you expect. While stepping through a script, you can examine and change the values of script variables. Select the Script | Run command or click $image\scr-run.gif$ to resume script execution at full speed after stepping through script instructions.

To execute your script one line at a time press the F8 key or select the Debug | Step Into command. The first line of the script is executed (or, if the script was paused, the next highlighted line is executed). The next line is highlighted and a yellow arrow appears to the left of the next line. To execute the highlighted instruction, press F8 again.

If a statement calls a subroutine or function that is defined within your script, the highlight will move into the called procedure. To keep from tracing execution into a called procedure, press SHIFT+F8 or select the Debug | Step Over command. This executes the whole subroutine or function in a single step.

If you accidentally step into a procedure, press CTRL+F8 or select the Debug | Step Out command. This executes all remaining instructions in a procedure, and returns the highlight to the instruction that called the procedure.

If you do not see the next highlighted instruction, select the Debug | Show Next Statement command to scroll the highlighted line into view.

Sometimes you may want to skip the execution of some instructions or you may want to execute the same instructions several times without restarting the script. To change the next instruction line, click on the line you want to execute next and select the Debug | Set Next Statement command.

Breakpoint

Watching Scripter execute every line of the script may be too time consuming. In this case, a breakpoint pauses the script where you think there might be a problem. A breakpoint is a line of code that you mark. When Scripter encounters a line marked as a breakpoint, it pauses the script just as if it had executed a STOP instruction. Breakpoints are more convenient than STOP instructions because they may be set and cleared while a script is paused, whereas STOP instructions may be changed only after a script has ended.

To set a breakpoint, click in the break bar area next to the line you want to mark. The break bar is the area to the left of the code window, between the sheet tabs and the code window. Alternatively, click on the line you want to mark, and press F9 or select the Debug | Toggle Break command. The line becomes highlighted in red, and a round marker appears in the break bar area.

To clear a breakpoint, click on the round marker, or move the cursor to the marked line and press F9 or select the Debug | Toggle Break command again. You can clear all breakpoints by pressing SHIFT+CTRL+F9 or selecting the Debug | Clear All Breaks command.

A quick alternative to setting a breakpoint is the Debug | Step To Cursor command. This command has the same effect as setting a breakpoint on the current line, running the script, and then clearing the breakpoint after script execution has paused on the current line.

Trace

To check flow of execution through your script without having to watch each line of the script being executed, try using the TRACE function. To activate the trace function type "Trace" (without the quotes) in the immediate window and press ENTER. Trace On is displayed in the immediate window. As the script is run, the location of every instruction being executed is printed in the immediate window. After the script finishes, the trace function is automatically disabled.

Stack

If you nest procedure calls (that is, one procedure calls another procedure, which calls yet another procedure, and so forth), the stack window may be useful. When a script is paused, the stack window lists the procedures that have been called, and the order in which they were called. For instance, if the Main procedure calls procedure "A" which in turn calls procedure "B," the stack window displays three lines, one for each of the called procedures. Clicking on a line in the stack window moves the corresponding procedure into view in the code window.

Module Files

Click the loaded window tab in the immediate window area to see which module files are currently being interpreted by Scripter. The loaded files include the current script file and any modules it includes with the '#Uses statement.