Windows Script Host tutorial: Debugging and testing your scripts

In part three of his Windows Script Host tutorial, Greg Shultz demonstrates how to use several techniques and applications to quickly locate errors in your scripts.

When you first get started with the Windows Script Host and its scripting languages, chances are that you’ll spend a lot of time tracking down errors in your scripts that prevent them from running correctly. These errors can be as simple as misspelling a keyword or forgetting a parenthesis or as complex as an error in how your script performs its job. The former type of error condition is referred to as a syntax error while the latter can be broken down into two subcategories: runtime errors and logic errors.

No matter how careful or experienced you are, it’s a given that some errors will appear in your scripts. Tracking down the causes of these errors and resolving them, often referred to as debugging, can be a very tricky procedure. However, the more you know about the typical error conditions, the easier it will be to troubleshoot or debug them. Keep in mind that debugging is a skill that will improve as you become more experienced with writing scripts.

In this Daily Drill Down, I’ll examine the common error conditions in detail, and I'll describe some techniques that you can use to debug your scripts. In addition, I’ll show you how to use a tool called the Microsoft Script Debugger to aid you in the debugging process.

As I show you how to debug and test scripts, I’ll assume that you’ve read parts one and two of this tutorial ("Windows Script Host tutorial: Pseudocode algorithms and other programming basics" and "Creating an integrated development environment for Windows Script Host"). I’ll also assume that you have installed and are using SynEdit as your customized Windows Script Host integrated development environment (IDE). Some of the debugging techniques that I’ll show you will take advantage of SynEdit as features to aid in debugging your scripts.

Next, you’ll need to have version 2 of the Windows Script Host in order to use some of the debugging techniques that I’ll explain in this Daily Drill Down. You can download the Windows Script Host 5.5 package from the Microsoft Windows Script Technologies Web site. Just follow the links to the Windows Script Host Downloads section. The Windows Script package includes Windows Script Host 2.0, VBScript 5.5, and JScript 5.5. Keep in mind that there are two versions of the package: one for Windows 2000 and one for Windows 95/98/NT.

Finally, download a copy of the free Microsoft Script Debugger from the Microsoft Scripting Technologies Web site. To find the download, select Script Debugger from the menu and open the Downloads page. Again, keep in mind that there are two versions of the Microsoft Script Debugger: one for Windows 95/98 and one for Windows NT/2000. Once you download Microsoft Script Debugger, run the executable file to install the program. The installation procedure won’t create a shortcut on your Start menu.

Debugging syntax errors
Let’s begin by examining the simplest types of errors and then move on to the more difficult ones. Syntax errors are the most common errors, and the easiest errors to make. A syntax error can occur as the result of the misspelling of a keyword, misplacing a keyword, or a mistake in punctuation.

Syntax errors will be recognized before any other type of error because they’re usually recognized at compilation time. While VBScript and JScript scripts aren’t really compiled languages in the truest sense of the word, they are indeed compiled on the fly by the Windows Script Host before they’re run. During this compilation phase, the Windows Script Host goes through each line in the script and translates the instructions, or commands, in the script into object code that the system can then run. If there are any mistakes in the script’s commands, Windows Script Host will find them at this time.

For example, a typical syntax error such as improper punctuation in a command would yield an error dialog box like the one shown in Figure A. As you can see, this error dialog box tells us that there needs to be closing parenthesis in character 51 of line 5.

Figure A
A typical syntax error is caused by not using the proper punctuation in a command.

If you’re using SynEdit as your customized IDE, debugging syntax errors is a much easier task. First, since you can actually launch your scripts from within SynEdit, the error message dialog box will appear right over SynEdit so that you can see both the error message and your script at the same time. Second, you can take advantage of the Cursor Status toolbar to quickly track down the location of the syntax error, as shown in Figure B.

Figure B
SynEdit’s Cursor Status toolbar makes it easy for you to quickly position your cursor at the exact location of the error.

Working backwards to solve mysterious syntax errors
Not all syntax errors will be as obvious as the one shown in the above example. In fact, Windows Script Host can sometimes misidentify the cause or location of a syntax error. It can even direct you to a line that doesn’t contain an error at all.

This misidentification usually occurs when there are two or more syntax errors in several consecutive lines. Furthermore, syntax errors can have a cascade effect. For example, one syntax error in line 2 can cause bogus syntax errors to appear in lines 3, 4, 5, 8, and 11. In this scenario, Windows Script Host might only identify a syntax error in line 11.

If, as you study the error message and the location it identifies, you find that everything looks okay in the line or that the error message doesn’t make any sense, work backwards from the location identified in the error message. As you do, chances are good that you’ll find an error. Once you find an error, fix that error, and then run (compile) the script again. Chances are good that you’ll solve your problem, and all the mysterious error messages will disappear. However, if you get another error message that doesn’t make sense, then use the same backtracking technique to locate an error, fix it, and then compile the script again.

The important thing to keep in mind when using this technique to solve mysterious syntax errors is to fix one error at a time. Doing so will allow you to methodically unravel the problem and eventually uncover the original location of the first syntax error.

If you try to fix more than one error at a time or attempt to fix a line that doesn’t appear to contain an error, chances are good that you’ll be misled by the bogus error messages, and this can create a bigger problem than the one actually causing the error message. The other thing to keep in mind is that if you’re totally baffled by a syntax error message, you can turn to the documentation.

Using the syntax error documentation
Sometimes syntax errors can be very complex, which may make it very difficult to identify them by sight. If you encounter a syntax error message that doesn’t seem to make sense, you can turn to the scripting language documentation for assistance.

Both the JScript and VBScript Help files have a section in the Language Reference chapter titled Errors. The Errors section contains a complete list of both syntax errors and runtime errors, which we’ll discuss in a moment. Each syntax error message in the list is a link to another page that contains a detailed description of the most common type of situation that can cause the syntax error, as well as a possible solution. You’ll also find that the each syntax error description contains links to other syntax errors that could be related. As such, if the solution presented isn’t the exact one for your particular problem, it will get you started in the right direction.

Runtime errors
Once you’ve cleaned up any syntax errors that may creep into your script, you may have to deal with runtime errors. Runtime errors are so named because they occur when you’re trying to run your script. While runtime errors can be caused by a mistake as simple as a misspelled command that eluded the syntax checking, most runtime errors are associated with the incorrect use of a scripting element—a command, function, statement, object, property, or a method.

While some runtime errors will cause Windows Script Host to halt program execution and display an error message dialog box, like the one shown in Figure C, many will simply cause the script to stop running without displaying any error message. Still other runtime errors will show up only occasionally; the rest of the time the script will run fine. As you can see, debugging runtime errors is much trickier than debugging syntax errors.

Figure C
Some runtime errors will cause Windows Script Host to display an error message dialog box.

If you see a runtime error message dialog box, check the Errors section in the Language Reference Help file. As with syntax errors, you’ll find that runtime error message documentation contains a detailed description of the most common cause of the error as well as possible solutions. You’ll also find links to related runtime errors. I’ll show you some methods of tracking down runtime errors, but before I do, let’s take a look at logic errors, as you’ll use similar methods to track down both.

Logic errors
Logic errors can result from any number of situations, from faulty reasoning, to an incorrect calculation, to a misunderstanding of how to use a scripting element, to a quirk in the operating system. Unfortunately, logic errors don’t result in any type of an error message dialog box. However, they usually show up when the result of your script isn’t what you intended it to be.

Since logic errors don’t result in an error message, tracking them down is a very intense operation that can take hours. Sometimes finding a logic error can mean going through your script line by line. However, using the right tools and techniques can make this job easier.

Using message tracing
Now, that you have a good idea of what runtime and logic errors are all about, let’s look at some techniques that you can use to debug them. One technique is known as message tracing. This type of debugging method is a manual operation and works well for short to medium-sized scripts.

I call this technique message tracing because what you actually do is insert messaging statements at various locations in your script that show you the results of certain variables at that particular point in the script. These messages allow you to trace the operation of the script by checking the results after each operation.

For example, when I was developing the RenameFiles.vbs script for my Daily Drill Down, "Create a file renaming script with Windows Script Host," I encountered some logic problems with the section of code that gathered the full path to the folder that was selected in the Browse dialog box. I used the message tracing technique to see what was happening at that point in the script. As you can see in the code segment shown in Figure D, I used MsgBox functions to display the contents of the pertinent variables between each line of the section of code that was causing problems.

Figure D
The message tracing technique uses the MsgBox function to display the data contained in variables at different sections of the script.

In this case, the first MsgBox function displays the contents of the SelectedFolder variable before the first line of code. That way I can be sure that the value stored in the variable is correct before the suspect lines of code are run. The second MsgBox function displays the result generated by the first line of code, while the third MsgBox function displays the result generated by the second line of code. In this way, I was able to see exactly what those two lines of code were doing.

The Microsoft Script Debugger
The second debugging technique is more sophisticated and involves using the Microsoft Script Debugger, which is a tool specifically designed for tracing VBScript and JScript scripts. While the Microsoft Script Debugger was originally intended for debugging scripts in HTML and ASP documents designed for Web browsers, you can use it to debug VBScript and JScript scripts designed for Windows Script Host.

Windows Script Host’s executable file provides you with an option for loading and executing scripts into the Microsoft Script Debugger. The command line is as follows:
Wscript.exe filename.ext //X

where filename.ext is the name of your script file and //X is the option that loads the Microsoft Script Debugger. To use this command, click Start | Run and type the command. When you do, the Windows Script Host launches the Microsoft Script Debugger with your script. You can then take advantage of the debugger’s features to investigate the problems with your script, as I’ll show you in a moment.

Adding the Microsoft Script Debugger to SynEdit
In part two of this tutorial, I showed you how to configure SynEdit as an IDE for the Windows Script Host. Since the goal of the creating the Windows Script Host IDE is to centralize all tasks associated with creating scripts, it makes sense that you’ll want to add the Microsoft Script Debugger to SynEdit. Fortunately, doing so is a snap.

To begin, open the Advanced menu, select Configure Compilers And Viewers, and click Add Program. When you see the Add/Edit Compiler Or Viewer dialog box, fill in the Program Name/Description and Command Line And Parameters text boxes, as shown in Figure E.

Figure E
To integrate the Microsoft Script Debugger into SynEdit, you’ll configure it to run as a compiler.

Now when you’re working with a script in SynEdit and need to debug the script, you can just press [F5] to open the Run Compiler/Viewer dialog box, select Microsoft Script Debugger from the list, and click OK. When you do, Microsoft Script Debugger will launch and display your script.

Using the Microsoft Script Debugger
Using the Microsoft Script Debugger is a bit confusing at first, but once you understand the basics, you’ll find that it’s an invaluable tool. With this in mind, let’s take a look at some of the basic debugging techniques that the Microsoft Script Debugger makes available. Keep in mind that there are many other features in the Microsoft Script Debugger and that you can learn more in the detailed Help file.

You’ll debug your script in the Microsoft Script Debugger much like you would using the manual message tracing technique I showed you earlier—by running the script and checking the variables. However, you’ll have much more control over the process. In addition to tracing the values of the variables in your script, you’ll also be able to trace the path of execution. In other words, you can watch as the debugger runs each line in the script. When it loads your script, the Microsoft Script Debugger immediately locates the first executable line in your code, highlights it, and then waits for you to tell it what to do, as shown in Figure F.

Figure F
When you first load your script into the Microsoft Script Debugger, it pauses or breaks at the first executable command in the script.

There are two methods of using Microsoft Script Debugger: You can step through the script one line at a time or you can set up breakpoints and have the script run until it encounters one, which will force the script to stop running. Let’s take a closer look at each method.

Stepping through
If you want to be able to precisely follow and control the execution of your code and check the values of variables at any time, you’ll want to use the step method. To do so, click the Step Into button on the Debug toolbar or press the [F8] shortcut key. Each time you do so, the debugger will execute the current line of code and then advance the highlighted pointer to the next line of code in the execution path, where it will stop and wait. This enables you to slowly follow the exact path that your script follows when it’s actually running. In between each step, you can then check the value of the variable, as I’ll explain below.

Using breakpoints
If you don’t need to follow the execution path through your code but want to test a section of code in your script to check the result generated by that section, you can use breakpoints. To set a breakpoint, select the line in your script at which you want execution to stop and click the Toggle Breakpoint button on the toolbar or press the [F9] key. When you do, that line will be highlighted in red and a stop sign icon will appear next to the line, as shown in Figure G.

Figure G
By setting a breakpoint, you can easily test individual sections of your script.

At this point, you’ll click the Run button on the Debug toolbar or press [F5]. When you do, your script will run as normal until it hits the breakpoint. You can then check the value of any variables that were accessed in that section of code.

Checking variable values
As you step through your script or run a section of script up to a breakpoint, you’ll want to be able to check the values of variables. To do so, click the Command Window button on the toolbar or select the command from the View menu. In VBScript, you can check the values when the Command Window appears by typing:
? variable name

where variable name is the name of the variable whose value you want to check. For example, to test the values of the NewString and OldString variables in the RenameFiles.vbs script, I typed the commands shown in Figure H.

Figure H
You can use the Command Window to view the values stored in variables.

If you’re using JScript, you have to use the Windows Script Host Echo method to look at the value of a variable. For example, to test the value of the NewString variable in the RenameFiles.js script, I typed the command shown in Figure I.

Figure I
To look at variables in JScript, you have to use the Windows Script Host Echo method.

Using the Call Stack feature
Microsoft Script Debugger has one other feature that you might find useful in debugging your scripts: the Call Stack feature. This feature’s main function is to show you a list of all the procedures (functions, subroutines, etc) that your script calls. This information can be helpful if you need to determine when or whether a function or procedure has been run. To access the Call Stack feature, click the Call Stack button on the toolbar or select the command from the View menu.

Debugging your script again
The Microsoft Script Debugger was originally designed to debug VBScript and JScript scripts in HTML documents and hasn’t been updated since 1997. Therefore, it doesn’t work perfectly for debugging Windows Script Host scripts. This obsolescence shows up in the way you have to load your scripts into the debugger—using the special Wscript command-line option. This is the only way to load a Windows Script Host script into the Microsoft Script Debugger.

What does this mean? Once you’ve run your script through the Microsoft Script Debugger, you can’t just re-run it again. In fact, all of the commands on the Debug toolbar and menu become unavailable. To debug your script again, you must close the Microsoft Script Debugger and reload it using the Wscript command shown above. However, if you’re launching the Microsoft Script Debugger from SynEdit, the process is very easy—just press [F5] and select the Microsoft Script Debugger.

When you’re writing a script for the Windows Script Host environment, chances are that you’ll spend a lot of time debugging your script in order to get it to run correctly. However, if you have a good understanding of the types of errors that you’ll encounter as well as some good debugging tools and techniques, you can be much more efficient at this phase of script development. In this Daily Drill Down, I’ve introduced you to the different types of error conditions, explained how to interpret them, and shown you that you can find more information on errors in the scripting language Help files. I also showed you several techniques that you can use to debug your scripts—including using the Microsoft Script Debugger.

About Greg Shultz

Greg Shultz is a freelance Technical Writer. Previously, he has worked as Documentation Specialist in the software industry, a Technical Support Specialist in educational industry, and a Technical Journalist in the computer publishing industry.

Editor's Picks