Error Handling

Error handling does not involve finding errors in your scripts. Instead, use error-handling techniques to allow your program to continue executing even though a potentially fatal error has occurred. Ordinarily, all runtime errors that are generated by the VBScript engine are fatal, since execution of the current script is halted when the error occurs. Error handling allows you to inform the user of the problem and either halt execution of the program or, if it is prudent, continue executing the program.

4.2.1 The On Error Resume Next Statement

There are two main elements to error handling in VBScript. The first is the On Error statement, which informs the VBScript engine of your intention to handle errors yourself, rather than to allow the VBScript engine to display a typically uninformative error message and halt the program. This is done by inserting a statement like the following at the start of a procedure:

On Error Resume Next

This tells the VBScript engine that, should an error occur, you want it to continue executing the program starting with the line of code that directly follows the line in which the error occurred. For example, in the simple WSH script:

On Error Resume Next x = 10 y = 0 z = x / y Alert z

a "Cannot divide by Zero" error is generated on the fourth line of code because the value of y is 0. But because you've placed the On Error statement in line 1, program execution continues with line 5. The problem with this is that when an error is generated, the user is unaware of it; the only indication that an error has occurred is the blank Alert box (from line 5) that's displayed for the user.

This is where the second element of VBScript's error handling comes in. VBScript includes an error object, named Err, which, when used in conjunction with On Error Resume Next, adds much more functionality to error handling, allowing you to build robust programs and relatively sophisticated error-handling routines.

4.2.2 The Err Object

The Err object is part of the VBScript language and contains information about the last error to occur. By checking the properties of the Err object after a particular piece of code has executed, you can determine whether an error has occurred and, if so, which one. You can then decide what to do about the error you can, for instance, continue execution regardless of the error, or you can halt execution of the program. The main point is that error handling using On Error and the Err object puts you in control of errors, rather than allowing an error to take control of the program (and bring it to a grinding halt). To see how the Err object works and how you can use it within an error-handling regimen within your program, let's begin by taking a look at its properties and methods.

4.2.2.1 Err object properties

Like all object properties, the properties of the Err object can be accessed by using the name of the object, Err, the dot (or period) delimiter, and the property name. The Err object supports the following properties:

Number

The Number property is a Long value that contains an error code value between -2,147,483,648 and 2,147,483,647. (The possibility of a negative error code value seems incongruous but results from the fact that error codes are unsigned long integers, a data type not supported by VBScript.) VBScript itself provides error code values that range from 0 to 65,535. COM components, however, often provide values outside of this range. If the value of Err.Number is 0, no error has occurred. A line of code like the following, then, can be used to determine if an error has occurred:

If Err.Number <> 0 Then

Although the properties of the Err object provide information on the last error to occur in a script, they do not do so permanently. All the Err object properties, including the Number property, are set either to zero or to zero-length strings after an End Sub, End Function, Exit Sub, or Exit Function statement. In addition, you can explicitly reset Err.Number to zero after an error by calling the Err object'sClear method. The WSH script in Example 4-8 illustrates the importance of resetting theErr object after an error occurs.

Example 4-8. Failing to reset the Err object

Dim x, y ,z On Error Resume Next x = 10 y = 0 z = x / y If Err.Number <> 0 Then MsgBox "There's been an error #1" Else MsgBox z End IF z = x * y If Err.Number <> 0 Then MsgBox "There's been an error #2" Else MsgBox z End If End Sub

The division by zero on the fifth line of the script in Example 4-8 generates an error. Therefore, the conditional statement on line 6 evaluates to True and an error dialog is displayed. Program flow then continues at line 12. Line 12 is a perfectly valid assignment statement that always executes without error, but the Err.Number property still contains the error number from the previous error in line 5. As a result, the conditional statement on line 13 evaluates to True, and a second error dialog is displayed. Despite the two error messages, there's only been a single error in the script.

Description

The Description property contains a string that describes the last error that occurred. You can use the Description property to build your own message box alerting the user to an error, as the WSH script in Example 4-9 shows.

Example 4-9. Using the Description property to display error information

Dim x, y ,z On Error Resume Next x = 10 y = 0 z = x / y If Err.Number <> 0 Then MsgBox "Error number " & Err.Number & ", " & _ Err.Description & ", has occurred" Err.Clear Else MsgBox z End If z = x * y If Err.Number <> 0 Then MsgBox "Error No:" & Err.Number & " - " & _ Err.Description & " has occurred" Err.Clear Else Alert z End If

Source

The Source property contains a string that indicates the class name of the object or application that generated the error. You can use the Source property to provide users with additional information about an errorin particular, about where an error occurred.

The value of the Source property for all errors generated within scripted code is simply "Microsoft VBScript runtime error." This is true of all VBScript scripts, whether they're written for Active Server Pages, Windows Script Host, Internet Explorer, or Outlook forms. Obviously, this makes the Source property less than useful in many cases. However, you can assign a value to the Source property in your own error-handling routines to indicate the name of the function or procedure in which an error occurred. In addition, the primary use of the Source property is to signal an error that is generated by some other object, like an OLE automation server (such as Microsoft Excel or Microsoft Word).

4.2.2.2 Err object methods

The two methods of the Err object allow you to raise or clear an error, while simultaneously changing the values of one or more Err object properties. The two methods are:

Using the Err Object

Generating an Error

Enter an Error Code  

Raise

The Err.Raise method allows you to generate a runtime error. Its syntax is:[1]

[1] A more complete version of the syntax of the Raise method is:

Err.Raise(ErrorNumber)

where ErrorNumber is the numeric code for the error you'd like to generate. At first glance, generating an error within your script may seem like a very odd thing to want to do! However, there are times, particularly when you are creating large, complex scripts, that you need to test the effect a particular error will have on your script. The easiest way to do this is to generate the error by using the Err.Raise method and providing the error code to the ErrorNumber parameter, then sit back and note how your error-handling routine copes with the error, what the consequences of the error are, and what side effects the error has, if any. The client-side script in Example 4-10, for instance, allows the user to enter a number into a text box, which is passed as the error code value to the Err.Raise method. If the value of the error code is non-zero, an Alert box opens that displays the error code and its corresponding description. Figure 4-6, for instance, shows the Alert box that is displayed when the user enters a value of 13 into the text box.

Example 4-10. Calling the Err.Raise method

Figure 4-6. Generating a Type mismatch error at runtime

Table 4-1 lists a few of the most commonruntime errors.

Clear

The Clear method clears the information that the Err object is storing about the previous error; it takes no parameters. It sets the values of Err.Number to 0 and the Err object's Source and Description properties to a null string.