Appendix E VBScript Error Codes and the Err Object

Here you'll find all the error codes associated with VBScript along with the Err object.

Runtime Errors

Runtime errors occur wherever your script attempts to perform an invalid action. The vast majority of these errors should be caught during the debugging and testing stage. VBScript contains 43 runtime errors, which are listed in the following table with their decimal and hexadecimal representations.

Syntax Errors

Syntax errors occur wherever your script contains statements that do not follow the pre-defined rules for that language. This type of error should be caught during development. VBScript contains 49 syntax errors, listed in the following table with their decimal and hexadecimal representations.

The Err Object

Errors usually make their way into code and as such it's important to be able to spot them and remove them. At the core of this is error handling using the Err object.

Let's take a quick tour of the Err object and the On Err statement and look at ways to make use of them in VBScript code.

Err Object

The Err object is the heart and soul of error handling in VBScript, and exposes information about runtime errors through its properties. Unlike other objects in VBScript, it is an intrinsic object with global scope; hence, there is no need to declare and initialize the Err object.

Initially the Err properties are either zero-length strings or , and when a runtime error occurs the properties of the Err object get populated by the generator of the error (e.g. VBScript, an Automation object, or by the programmer). Err.Number contains an integer, and Number is the default property of the Err object. It is easy to test whether the error actually occurred with an If ErrThen statement because of automatic conversion between integer and Boolean subtypes : the integer (no error) converts to Boolean False , and all other numbers evaluate to True .

The following example illustrates a partial IE VBScript (although it could just as easily be from a .wsc , or .hta file) in which the programmer raises one of the predefined VBScript errors. Note that the Err object is not declared and it cannot be created as a separate object.

Err Object Properties

Let's take a look at the Err object properties.

Description

The Description property returns or sets a descriptive string associated with an error. By default this is a zero-length string until the property is set by the programmer or by the generator of an error. The description is useful when displaying or logging errors and when raising custom errors. If the programmer raises one of the default runtime errors, the Description property contains the string associated with the error.

Syntax

Err.Description [= stringexpression]

Example Usage

This sample script will produce Variable in undefined inside a message box.

HelpContext

The HelpContext property is used to automatically display the Help topic specified in the HelpFile property. This property either sets or retrieves the value of the help context. If both HelpFile and HelpContext are empty, the value of Number is checked. If

Number corresponds to a VBScript runtime error value, then the VBScript help context ID for the error is used.

This property is rarely used, and requires coordination between the person authoring the Help system and the scripter.

Finally, use of the HelpFile and HelpContext only make sense in a non-IE setting with the older .hlp system. Newer HTML help simply uses HTML documents, which may be displayed under most circumstances using techniques discussed in HTML Help manuals.

The following sample illustrates the use of the traditional .hlp files with the Windows Script Host.

Syntax

Err.HelpContext [= contextID]

Example Usage

On Error Resume Next Dim Msg Err.Clear Err.Raise 6 Generate Overflow error. Err.Helpfile = c: windows help yourHelp.hlp Err.HelpContext = 21 If Err.Number <> 0 Then Msg = Press Help to see & Err.Helpfile & topic for & _ the following HelpContext: & Err.HelpContext MsgBox Msg, , error: & Err.Description, Err.Helpfile, Err.HelpContext End If

HelpFile

The HelpFile property is used to set and retrieve a fully qualified path to a programmer- authored Help File. Often it is used in conjunction with the HelpContext property-see the notes and the earlier example. The most common way of setting the value is through the Err.Raise method.

Syntax

Err.HelpFile [= filepath]

Number

This is the default property of the Err object, and returns or sets a numeric value specifying an error. Custom error handling functions utilize the Number property to diagnose the runtime error.

When setting or retrieving a custom error, the vbObjectErr constant is used to ensure that custom errors do not conflict with VBScript and common Automation Errs .

Syntax

Err.Number [= errornumber]

Example Usage

On Error Resume Next Err.Raise vbObjectError + 16, ,CustomObject Error Raise Custom Error #16. If Err.Number <> 0 Then (If Err Then) can be used too MsgBox (Error # & CStr(Err.Number) & & Err.Description) End If

The preceding sample code sets a custom error number in Err.Number through the Err.Raise method, and then displays the return value through a Message Box ( MsgBox ).

Source

The Source property sets or returns the name of the object or application that reported the error. Most commonly the source is the class name or ProgID of the object generating the error.

Most of the time the Source property will show ³Microsoft VBScript ³, but in cases where the error occurs while accessing a property or method of an Automation object, the source property will show the component's class name. This is not only useful because it allows for a greater degree of granularity (or visibility) in error handling, but it also allows for better error display and logging possibilities. This property can be set through the Err.Raise method in both VBScript and in custom COM components .

Syntax

Err.Source [= stringexpression]

Example Usage

On Error Resume Next Err.Raise vbObjectError + 1, cTestClass, CustomObject Error If Err.Number <> 0 Then (If Err Then) can be used too MsgBox (Error # & CStr(Err.Number) & & Err.Description & Source: & Err.Source) End If

Err Object Methods

Let ²s take a look at the Err object methods.

Clear

The Clear method resets all of the properties of the Err object to either or a zero-length string. The Err object should ideally be reset after an error has been handled because of the deferred nature of error handling in VBScript, to avoid the potential mistake of handling the same error twice.

The Err object is additionally cleared by any of the following statements:

• On Error Resume Next
• On Error Goto
• Exit Sub
• Exit Function

Therefore, error-handling functions must be called before any of the preceding statements are executed.

Syntax

Err.Clear

Example Usage

On Error Resume Next The Err Object is Reset Err.Raise 5 Err.Clear If Err.Number = 0 Then (If Err Then) can be used too MsgBox (Error has been reset: Err.Number - & CStr(Err.Number)) End If

Raise

The Raise method generates a runtime error. All of the parameters of the Raise method, except for its number, are optional. When optional parameters are not specified, and the Err object has not been cleared, old values may appear.

The best practice is to use Err.Clear after error handling, and to inspect the Err object before using Err.Raise (in case an error has occurred in the meantime). When raising custom error numbers, the vbObjectErr constant should be added.

The HelpFile and HelpContext parameters are used with the traditional .hlp help, and not with the HTML help systems.

Raising errors is a popular technique to stop the execution of a procedure, and handle it via some error handling function. You may raise errors when data is invalid, and when you want to pass an error up the call stack. This is a popular technique when you want to change one error into another, so that it can be handled properly.

Syntax

Err.Raise (number, source, description, helpfile, helpcontext)

Example Usage

Dim strMsg On Error Resume Next Err.Raise vbObjectError + 1, prjProject.clsClass, Custom Error, c: windowsYourHelpfile.hlp, 1 If Err.Number <> 0 Then strMsg = Error Number: & CStr(Err.Number) & vbCrLf strMsg = strMsg & Description: & Err.Description & vbCrLf strMsg = strMsg & Source: & Err.Source If Err.HelpFile <> Then strMsg = strMsg & vbCrLf & Press Help to see the help file MsgBox strMsg, , Error: & Err.Description, Err.Helpfile, Err .HelpContext End If MsgBox strMsg No Help file available here Err.Clear End If

This example shows a common way of raising an error in Windows Script Host, where the help file is readily available.

vbObjectError Constant

This is a built-in constant that can be used in conjunction with programmer-defined errors and Err.Raise . It does not have to be declared or initialized ; its decimal value is -2147221504 (or -0 (8004000 in hexadecimal). Whereas previous examples have shown how to use the vbObjectError constant with the Err.Raise method, the following example shows a skeleton of a centralized error handler that combines Select Case with custom errors.

Example Usage

If Err.Number <> 0 Then this should call separate subs Select Case Err.Number Case vbObjectError + 1 call sub handling error 1 Case vbObjectError + 3 call sub handling error 3 Case Else call reporting sub to display errors End Select End If

On Error Resume Next

This statement enables error handling within the scope of a script or a procedure. Without the On Error Resume Next statement, the default runtime error handler displays the error and stops the execution of the script.

On Error Resume Next continues the execution of the script on the next line following the error. The error handling routine has to exist within the same scope as this statement. The statement becomes inactive with a call to another procedure or when an On Error Goto statement is used.

Syntax

On Error Resume Next

On Error Goto 0

The On Error Goto statement disables the error handling that was enabled by On Error Resume Next . This statement is especially useful in the testing stage, when there is a need to identify certain errors and yet handle others. On Error Goto can be placed immediately after the error handling procedure is called.

Like On Error Resume Next , this statement is also scope dependent.

Syntax

On Error Goto 0

Scope of On Error Statement and Differences Between VBScript's and VBs (or VBAs) Error Handling

It is important to understand the scope of the On Error statement; otherwise your error handling procedures may never execute. VBScript-unlike its parent language-does not support labels, and it does not support the VB On Error Goto label. Thus, VBScript provides support only for in-line error handlers that can cause understandable grief . Basically, in order to mimic a block of code in VB that would respond to an On Error Goto label statement you might be inclined to use several If Err Then statements in order to check for an error with each single line of execution. However, with a little bit of programming, this can easily be achieved by enabling an error handler around a given procedure. Should one of the lines in the procedure fail, the error can be thrown up the calling stack. Of course, there is no Resume statement, which complicates some of the scripting. This can only be circumvented by trying to correct the problem that generated the error and attempting to call the procedure again.

Before we look at some error handling techniques, let's examine the scope of error handling. The following script illustrates an important concept behind the scope of the error-enabling and error-disabling statements, as well as showing the differences in scope and the importance in clearing of errors.

Sub TestError() On Error Resume Next Err.Raise 6 Execution will continue MsgBox (TestError: Error # & CStr(Err.Number) & & Err.Description) Err.Clear End Sub Sub TestError2() Err.Clear Execution stops, moves up in scope MsgBox (TestError2: This will never Show Up) End Sub Main body of the script TestError() has local Error Handler no need for global Handler On Error Resume Next Call TestError() If Err.Number <> 0 Then MsgBox (Global: Error # & CStr(Err.Number) & & Err.Description) Err Clear Else MsgBox (Global: No Error, It was handled locally and cleared) End If TestError2 has no local error handler Call TestError2() If Err.Number <> 0 Then MsgBox (Global: Error # & CStr(Err.Number) & & Err.Description) Err.Clear End If Global script Error handling is turned off, cause crash On Error goto 0 Call TestError2()

Upon execution, the error is first handled locally, and after it is cleared, it is ignored. Next, the calls to the Test Error2() subroutine are first handled by the global error handler and, after it is disabled on the second-last line, a runtime error appears.

Now, to consider the importance of clearing errors and the scope of On Error Resume Next , we make two adjustments, commenting out certain code.

Sub TestError() On Error Resume Next Err.Raise 6 Execution will continue MsgBox (TestError: Error # & CStr(Err.Number) & & Err.Description) REM Err.Clear End Sub Sub TestError2() Err.Clear Execution stops, moves up in scope MsgBox (TestError2: This will never Show Up) End Sub Main body of the script TestError() has local Error Handler no need for global Handler REM On Error Resume Next

With these changes, an error message is still displayed after the call to TestError() , but the first call to the TestError2() subprocedure results in an invocation of the default error handler, and stoppage of the script immediately after the call, that is, the On Error Resume Next statement was local in scope to the TestError() subprocedure.

The following code illustrates the possibility of mimicking the On Error Goto label statement by encompassing a block of code in a procedure, rather than trapping errors inline, as in VB. Here the scripter can invoke an error handler at a higher level rather than at the level where the error occurred (in this case, a procedure without a local error handler).

Option Explicit Dim intZero, intNonZero, intResult intZero = 0 intNonZero = 1 Sub TestError() Statements that will execute MsgBox (This will always execute) now cause an error intResult = intNonZero / intZero causes error 11 Statements that will not execute if error occurs MsgBox (Finally executed, Result = & CStr(intResult)) End Sub simulate On Error Goto Label by having a block of code in a sub On Error Resume Next Call TestError() If Err.Number = 11 Then MsgBox Division By Zero - may still continue & vbCrLf & Err.Description Err.Clear intZero = 1 TestError() End If On Error Goto 0 kill other error handling

Error Handling in Internet Explorer

Besides VBScript itself, some Web authors might also turn to DHTML events. Internet Explorer's DHTML object model supports a variety of events, including events occurring as a result of an error. Essentially, this allows for a different degree of control when authoring scripts for IE. Thanks to the GetRef() function, which returns a pointer to a function, it is now possible to bind VBScript procedures to an event.

For instance, the following line will execute the RunMySub procedure in response to the Window .Onload event in IE.

Set Window.Onload = GetRef(RunMySub)

Similarly, you can write procedures that will execute when the OnError event is fired , either for an element or for the window object.

There are two additional techniques for error handling in IE:

• Centralized, through the use of the window.onerror event
• Decentralized, through the use of the element.onerror event

The following code example illustrates the old and the new syntax for handling DHTML errors.

Old Syntax

Function element_onerror (message, url, line)

element is the name of the element or window.

New Syntax

Set element.onerror = GetRef(functionName)

The new syntax allows us to bind functions to events, just like in JScript. Again, element is the name of the element or window, and functionName is an actual function or a sub.

There are a few important differences between the VBScript's error handling and the use of the onerror event in IE. Following is the list of a summary of the onerror IE handlers:

• Execution does not resume on the next line. The script may resume with the next user action or handled event-for example, the user ³clicks ³ on another element. If you want greater error-handling control in individual procedures executed in the browser, the On Error Resume Next statement should be used.
• All errors pertaining to the element (or window) are handled by the event unless handled via VBScript's On Error Resume Next technique.
• Errors can be passed to a higher-level element via event bubbling.
• Custom errors cannot be created; there is no Err.Raise counterpart in the DHTML object model.