VBScript in a Nutshell

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.

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 which 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.

Tip

A particular On Error statement is valid until another On Error statement in the line of execution is encountered. This means that if Function A contains an On Error statement, and Function A calls Function B, but Function B does not contain an On Error statement, the error handling from Function A is still valid. Therefore, if an error occurs in Function B, it is the On Error statement in Function A that handles the error; in other words, when an error is encountered in Function B, program flow will immediately jump to the line of code that followed the call to Function B in Function A. When Function A completes execution, the On Error statement it contains also goes out of scope. This means that, if the routine that called Function A did not include an On Error statement, no error handling is in place.

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.

Exception Handling in ASP

ASP 3.0/IIS 5.0 (unlike previous versions of ASP) supports built-in exception handling. Errors in ASP scripts are handled automatically by the web server in one of three ways: by sending a default message to the client, by sending the client the contents of a particular file, or by redirecting the client to an error handling web page, depending on how the IIS has been configured. Within the errror handling page, the ASPError object can be examined to determine the cause of the error. In ASP 3.0, using the VBScript On Error Resume Next statement circumvents ASP’s built-in exception handling and replaces it with VBScript’s less flexible error handling system.

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 here 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.

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 an integer value that contains an error code value between and 65535, representing the last error. If the value of Err.Number is 0, no error has occurred. The 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, though, you can explicitly reset Err.Number to zero after an error by calling the Err object’s Clear method. The WSH script in Example 4.8 illustrates the importance of resetting the Err 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, though, there’s only been a single error in the script.

The Err object can be reset by using the Clear method (which is discussed in the next Section 4.2.2.2).

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 expression 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 error; in 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 (like Microsoft Excel or Microsoft Word) or a COM component.

Err object methods

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

Raise

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

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 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 nonzero, 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

<HTML>
<HEAD>
<TITLE>Using the Err Object</TITLE>
<SCRIPT LANGUAGE="vbscript">

Sub cmdButton1_OnClick
On Error Resume Next
errN = Document.frm1.errcode.value 
Err.Raise(errN)

If Err.Number <> 0 Then
 Alert "Error No:" & Err.Number & " - " & Err.Description
 Err.Number = 0
End If

End Sub

</SCRIPT>
</HEAD>
<BODY BGCOLOR="white">
<CENTER>
<H2>Generating an Error</H2>
<P>
<FORM NAME="frm1">
Enter an Error Code &nbsp;
<INPUT TYPE="text" NAME="errcode">
<INPUT TYPE="button" NAME="cmdButton1" VALUE="Generate Error">
</CENTER>
</BODY>
</HTML>

At present there is no definitive list of VBScript runtime error codes available from Microsoft. Table 4.1 lists a few of the most common runtime errors.

Tip

An Error Code Generator (ERRCODES1.HTML, ERRCODES1.ASP, and ERRCODES1.VBS), which allows you to generate a complete list of current VBScript error codes, can be found on the O’Reilly Visual Basic web site at http://vb.oreilly.com.

Table 4-1. Some Common VBScript Error Codes

Error Number	Description
5	Invalid procedure call
6	Overflow
7	Out of memory
9	Subscript out of range
11	Division by zero
13	Type mismatch

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

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 and the Err object’s Source and Description properties to a null string.

---

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

Err.Raise(ErrorNumber)

where source is the name of the module that generates the error, and description is a string describing the error. The latter parameter is useful in particular when handling an application-defined error. This topic—and therefore the complete syntax of the Raise method—is beyond the scope of this chapter.