Link to XLnow Homepage
back to OnScript Homepage

Note: some of the features presented here require other software
 in addition to OnScript. See the Prerequisites section below.


Script Debugging with XLnow OnScript 1.0
Guessing where the errors in your script are and adding WScript.Echo commands to your script to find the errors is not a panacea for all scripting errors.
  Luckily there is a lot more you can do if you debug scripts with XLnow OnScript: Free Preview of OnScript
Watch OnScript display error messages and highlight the error line
  If your script does not run because of a parsing error or it stops when an error occurs at run time, OnScript will display the error message in the Output tab of the Command window.

OnScript displays the error message in the Output tab of the Command window.

In addition OnScript will highlight the offending line of your script and position the cursor in the script document.

OnScript highlights the offending line.

Get an error description from online help

Often the error message will not be very verbose and you might require additional information. You can get that from the online help by placing the cursor anywhere on the red error message and pressing F1. Or press the right mouse button on the error message to pop up the shortcut menu and select the “Error Description” command.

Get an error description from the online help.

This opens the online help and automatically shows the error description:

Show the error description.

Launch the debugger when an error occurs
Normally when you run a script and an error occurs, OnScript will display it in the Outline tab of the Command window as described above.

You can however configure OnScript to launch a script debugger whenever an error occurs. Choose Options from the Tools menu then enable the “Call debugger on error” option (see General tab, Debugger section).

Launch the script debugger.

Alternatively you can toggle this setting with a toolbar button. To make it accessible enable the Debug toolbar (Tools menu, Customize, Toolbars).

Enable the Debug toolbar.

When an error actually occurs, the “Just-In-Time Debugging” dialog will pop so you can choose if you want to debug the script or just report the error as usual. Selecting yes will load the debugger.

Just-In-Time Debugging dialog.

For this to work you need to install the Microsoft Windows Script Debugger (or another script debugger, such as the Microsoft Script Editor that comes with Office XP).
See the Prerequisites section below for details.

Set breakpoints in your code and launch the debugger
You can set a breakpoint by pressing F9 in the line you want the script to stop. Set as many breakpoints as you need. Pressing F9 again will clear the breakpoint again.

Set breakpoints in your code.

You can find more related commands in the Run menu and on the Debug toolbar (which is not enabled be default - enable it in the Customize dialog).

More related commands in the Run menu.

In addition, the Debug toolbar has commands to jump from one breakpoint to another – which is most practical when dealing with long scripts.

Jump from one breakpoint to another.

What’s wrong with guessing and debugging with WScript.Echo?
Well, there is not really anything wrong with it. It is just one technique amongst others and it can certainly help. We hope this text gives you some guidance in how to use debugging features specific to OnScript.

If you found our tips interesting you might also want to read the following article from the “Tales of the Script” archive in the TechNet Script Center:

What’s Wrong with My Script? - January 2004
"Provides tips and tricks for debugging those scripts that just don’t want to do what they’re supposed to."
Windows Script 5.6 Documentation

Make sure you have the Windows Script 5.6 Documentation installed and registered in the OnScript Editor. This will enable keyword and error help using F1.

When you run OnScript for the first time it attempts to find the documentation and register it. To check if this succeeded, open the OnScript Editor and switch the Workspace to the Helps tab. You should see an entry that looks like this:

Windows Script V5.6 Documentation.

Double-clicking the entry should open the help file in a separate window.

If you do not have the help file on your system, then download and install it. We have set up a link the documentation on in the Scripting Downloads section of this site. The installation will ask for a path to store the help file (the default is fine). It will then copy and register it and create a Start menu shortcut.

The last step is to tell OnScript about the new help file. You can do this by manually adding a new entry to the Helps tab (New Help command on the shortcut menu) and by associating the Help links of the various script file types with the help file on the Options dialog (Tools menu).

However, it is easier to accomplish this by using the “Register Script Help Files” command you can find in the Tools menu. This will configure all required settings in OnScript.

Register Script Help Files

To test your configuration, open a script file, select a keyword or place the cursor in a keyword and press F1. A separate window will show the help file opened on the appropriate page!

See the "Get an error description from online help" topic above on how to jump to the description of errors that occur in your scripts.

Microsoft Windows Script Debugger

The OnScript Editor will let you manage breakpoints and jump into the debugger when your script hits a breakpoint or if an error occurs. But in order to get some real debugging done OnScript alone is not enough - you will have to install a script debugger such as the Microsoft Windows Script Debugger. This is free tool and there is a download link in the Scripting Downloads section of this site. Installation is easy and includes documentation.

A while ago the Microsoft TechNet Scripting Guys published a great article on how to debug scripts using the Script Debugger, so make sure you check it out:

Bugs Check in but They Don’t Check Out - September 2004
"Just because we might never be able to get rid of computer bugs for good, that doesn’t mean we can’t track down and exterminate individual bugs, particularly those lurking within our scripts."