Blog

Interpreting the Error Code and Description

Let’s look in a bit more detail at how the interpreter within the VBscript engine handles errors and how they are recorded in Err. Errors can be raised by the interpreter itself (and examples of these are the Subscript out of range and Division by zero errors above), but the main power of scripting is its use as an integration vehicle for COM components such as ASDI, and many of the errors that need to be handled will originate in such components. When an error occurs the interpreter is going to get an HRESULT, and possibly some additional context information — strings describing the error, and so on, and as it uses the standard programmatic interface to COM by calling IDispatch and therefore errors are returned in an EXCEPINFO structure. (This design dates back to the earliest days of COM; sorry.)

Making sense of those error numbers requires some delving into the depths of how COM represents errors — the HRESULT, which is a 32 bit unsigned integer where the high bit indicates whether it is an error or a success. The remaining bits in the high word indicate the “facility” of the error — into what broad category does this error fall? The low word indicates the specific error for that facility. HRESULTS are therefore usually talked about in hex, as the bit structure is a lot easier to read in hex! Consider 0x80070013, for example. The high bit is set, so this is an error. The facility code is 7 and the error code is 0x0013 = 19 in decimal. Some common facility codes are listed in Table 1 and Table 2 below.

Once the error winds its way back to the interpreter, the interpreter does a long jump to an error handling routine which saves off additional information that the interpreter knows. For instance, what is the name of the last-accessed variable — because some error messages include information like that. The interpreter then checks to see if we’re in ‘resume next’ mode, in which case it cleans up the stack, moves the instruction pointer to the next beginning-of-statement marker, and restarts the interpreter.

There is some additional goo that happens in here to make script debugging scenarios work. I won’t go into that — a discussion of all the ways that script errors and the debugger interact would be lengthy indeed. There is also code to handle weird scenarios — like, a JScript block with a try-catch calls a VBScript block which calls a JScript block, which throws an exception — but I won’t go into these, nor the detailed error tracking you’d observe if you were debugging the COM object itself — say through the Visual Studio debugger.

The implementation of the Err object should now be transparent — it simply looks at the information which the engine recorded at the time of the error. The error number, description, and so on, are reported as they were reported to us by the object which failed, assuming that the object returned error status. However for some common errors, when VBScript gets the error numbers back from calls to IDispatch objects, it replaces them with the equivalent VBScript error number. I have never particularly liked this feature, but VB6 does it, so we’re stuck with it for backwards compatibility reasons. This can be a little confusing if you’re debugging a problem — you see one error go out of the object, but a different error is reported to the host. The mapping table that VBScript uses is below at Table 1. (Note that there seems little logical structure to these codes, so don’t look for one. They seem to have been assigned for largely historic reasons, to the extent that the error codes listed in blue are the same as Altair BASIC which Microsoft’s first product, written by Bill Gates and Paul Allen back in 1975 for the Altair 8080!)

Table 1 — VBscript Errors Codes and Facility Mappings

Table 2 — Standard Facility Codes

Table 3 — Some Other Common Errors

This is only a subset of the errors that can be detected. Also many COM objects are designed to provide a scripting-friendly interface and therefore include call-back methods to allow the script to interrogate any errors raised in the COM object. For example in WMI:

   On Error Resume Next
   Set Test = GetObject _
              ("Winmgmts:root\cimv2:Win32_Printer.Name='TestPrinter'")
   Set WMI_Error = CreateObject("WbemScripting.SwbemLastEror")
   Wscript.Echo WMI_Error.Operation & VbTab & _
   WMI_Error.ParameterInfo & VbTab & WMI_Error.ProviderName

However, for the reasons I discuss in the next section, you should only need to exploit this richness in very limited circumstances.