ASPError Object

Introduced with ASP 3.0, the built-in ASPError object allows you to view detailed information about the last error that occurred in the script of an ASP page in the current session. This object, through its nine read-only properties, provides more detailed information about the type and source of errors than does the Err object provided in VBScript.

To use the ASPError object and its properties, you must call a new method of the Server object, GetLastError, which returns an ASPErrorObject with its properties' values set to reflect details about the last error that occurred in the script:

Dim objMyASPError
Set objMyASPError = Server.GetLastError

When you install IIS 5.0, by default, all preprocessing, script and runtime errors in ASP code cause IIS to stop processing the current script and redirect script execution to a custom error page named 500-100.ASP. This redirection occurs through an internal call to the Server.Transfer method which, as detailed in Chapter 9, shifts execution from one script to another while protecting all state information available in the first script.

The 500-100.ASP script (located by default in the C:\WINNT\Help\iisHelp\common directory) contains a call to the Server.GetLastError method. When this script is executed, it formats and displays the current property values of the ASPError object returned by this call to GetLastError.

You can use the default error page, 500-100.ASP, as-is; edit it to reflect your site's look and feel; or use the Internet Services Manager snap-in to redirect IIS to a page of your choosing (see Appendix D).

The properties, collections, methods, and events of the ASPError object are outlined in the following box.

**** BEGIN Error Generating Script #1 **** <HTML> <HEAD><TITLE> Error Generation Page #1 </TITLE></HEAD> <BODY> <% ' This page contains a syntax error. ' In the following For...Next loop, the keyword ' "For" is mispelled. Dim intCounter Fir intCounter = 1 to 100 %> Look everyone! I'm counting: <%=intCounter%><BR> <% Next %> </BODY> </HTML> **** END Error Generating Script #1 **** **** BEGIN Error Generating Script #2 **** <HTML> <HEAD><TITLE> Error Generation Page #2 </TITLE></HEAD> <BODY> <% ' This page contains a preprocessing error. ' The work "file" in the #INCLUDE preprocessor ' directive is mispelled: %>  </BODY> </HTML> **** END Error Generating Script #2 **** **** BEGIN Error Generating Script #3 **** <HTML> <HEAD><TITLE> Error Generation Page #3 </TITLE></HEAD> <BODY> <% ' This page contains a runtime error. ' In the following For...Next loop, when the ' intCounter variable gets to zero, the result ' is a divide by zero error. Dim intCounter Dim dblDivResult For intCounter = 1 to 100 dblDivResult = intCounter / (intCounter - 100) %> Look everyone! I'm dividing: <%=dblDivResult%><BR> <% Next %> </BODY> </HTML> **** END Error Generating Script #3 ****

**** BEGIN ASPCode Example Script **** <% ' This script demonstrates the use of the ASPCode ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the ASPCode property is " & objMyASPError.ASPCode %> **** END ASPCode Example Script ****

**** BEGIN ASPDescription Example Script **** <% ' This script demonstrates the use of the ASPDescription ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the ASPDescription property is " & _ objMyASPError.ASPDescription %> **** END ASPDescription Example Script ****

**** BEGIN Category Example Script **** <% ' This script demonstrates the use of the Category ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Category property is " & objMyASPError.Category %> **** END Category Example Script ****

**** BEGIN Column Example Script **** <% ' This script demonstrates the use of the Column ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Column property is " & objMyASPError.Column %> **** END Column Example Script ****

**** BEGIN Description Example Script **** <% ' This script demonstrates the use of the Description ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Description property is " & objMyASPError.Description %> **** END Description Example Script ****

**** BEGIN File Example Script **** <% ' This script demonstrates the use of the File ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the File property is " & objMyASPError.File %> **** END File Example Script ****

**** BEGIN Line Example Script **** <% ' This script demonstrates the use of the Line ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Line property is " & objMyASPError.Line %> **** END Line Example Script ****

**** BEGIN Number Example Script **** <% ' This script demonstrates the use of the Number ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Number property is " & objMyASPError.Number %> **** END Number Example Script ****

**** BEGIN Source Example Script **** <% ' This script demonstrates the use of the Source ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Source property is " & objMyASPError.Source %> **** END Source Example Script ****

ASPCode

objASPError.ASPCode

The ASPCode property holds a numeric code representing the ASP-specific error that occurred in the script that raised the error. This property is populated by IIS if the error occurred in processing the ASP script. The ASPCode property is read-only.

Parameters
None

Example
This example assumes that the following code has been added to the default custom error script, 500-100.ASP, and that each of the three scripts shown at the end of the Comments/Troubleshooting section is used to raise an error that invokes it: ** BEGIN ASPCode Example Script <% ' This script demonstrates the use of the ASPCode ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the ASPCode property is " & objMyASPError.ASPCode %> END ASPCode Example Script When the error-generating scripts are executed, the preceding example script generates the following three responses: Error Generating Script #1: The value of the ASPCode property is [EMPTY] Error Generating Script #2: The value of the ASPCode property is ASP 0128** Error Generating Script #3: The value of the ASPCode property is [EMPTY]

Notes
As previously noted, the ASPCode property is not populated unless the error occurred when interpreting the ASP script itself. This covers all preprocessing directives.

ASPDescription

objASPError.ASPDescription

The ASPDescription property is a string value that IIS populates upon encountering an ASP error. It provides more descriptive data about the type of ASP error that occurred than does the ASPCode property. As with the ASPCode property, the ASPDescription property is only populated if the error that occurs is part of the interpretation of an ASP script, rather than as a result of a runtime error.

Parameters
None

Example
This example uses the error-generating scripts listed at the end of the Comments/Troubleshooting section. It assumes that the following code has been added to the default custom error script, 500-100.ASP: ** BEGIN ASPDescription Example Script <% ' This script demonstrates the use of the ASPDescription ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the ASPDescription property is " & _ objMyASPError.ASPDescription %> END ASPDescription Example Script When the error-generating scripts are executed, the preceding ASPDescription script generates the following three responses: Error Generating Script #1: The value of the ASPDescription property is [EMPTY] Error Generating Script #2: The value of the ASPDescription property is The Include file name must be specified using either the File or Virtual attribute.** Error Generating Script #3: The value of the ASPDescription property is [EMPTY]

Notes
Like ASPCode, the ASPDescription property is only useful for ASP interpretation-specific errors. The Description property of the ASPError object almost always provides the same or better information about the most recent error.

Category

objASPError.Category

The Category property holds a string that specifies the type of error that has occurred: IIS-specific, scripting language specific, or component specific.

Parameters
None

Example
This example uses the error-generating scripts listed at the end of the Comments/Troubleshooting section. It assumes that the following example code has been added to the default custom error script, 500-100.ASP: ** BEGIN Category Example Script <% ' This script demonstrates the use of the Category ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Category property is " & objMyASPError.Category %> END Category Example Script When the error-generating scripts are executed, this script generates the following three responses: Error Generating Script #1: The value of the Category property is Microsoft VBScript compilation Error Generating Script #2: The value of the Category property is Active Server Pages Error Generating Script #3: The value of the Category property is Microsoft VBScript runtime**

Notes
The Category property allows you to narrow down where to look for the error.

Column

objASPError.Column

The Column property holds a long value that specifies the specific character column containing the first character of the error-causing code.

Parameters
None

Example
This example uses the error-generating scripts listed at the end of the Comments/Troubleshooting section. It assumes that the following code has been added to the default custom error script, 500-100.ASP: ** BEGIN Column Example Script <% ' This script demonstrates the use of the Column ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Column property is " & objMyASPError.Column %> END Column Example Script ** When the error-generating scripts are executed, the preceding Column script generates the following three responses: Error Generating Script #1: The value of the Column property is 19 Error Generating Script #2: The value of the Column property is -1 Error Generating Script #3: The value of the Column property is -1

Notes
The Column property is valuable in helping you locate erroneous syntax in your code. However, if the error is ASP-specific or the location where the error arises does not contain syntactically incorrect code, this value is -1 and, as such, is of limited use.

Description

objASPError.Description

The Description property is a string describing the last-occurring error. It is typically more descriptive and useful than the related ASPDescription property, except when the error is ASP interpretation-specific.

Parameters
None

Example
This example uses the error-generating scripts listed at the end of the Comments/Troubleshooting section. It assumes that the following code has been added to the default custom error script, 500-100.ASP: ** BEGIN Description Example Script <% ' This script demonstrates the use of the Description ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Description property is " & objMyASPError.Description %> END Description Example Script When the error-generating scripts are executed, the preceding Description script generates the following three responses: Error Generating Script #1: The value of the Description property is Expected end of statement Error Generating Script #2: The value of the Description property is Missing File or Virtual attribute Error Generating Script #3: The value of the Description property is Division by zero**

Notes
The Description property value is typically more descriptive than the other properties of the ASPError object. However, like all the other properties, it is of very little use to the end users of your ASP application. As such, it is important that any information you display explaining the cause of the error be informative or useful to the user. At the end of this chapter is an example of a customized 500-100.ASP script that you can use to display innocuous error information while still providing useful information to the developer of the script.

Comments/Troubleshooting



Many beginning ASP developers use the following code to enable debugging of their scripts using the Err object in VBScript: On Error Resume Next If you include this line of code in your script, then only preprocessing and script (syntax) errors will cause IIS to call the Server.Transfer method and redirect script execution to your 500-100.ASP script (or custom error-handling script). Runtime errors will not cause IIS to transfer processing to 500-100.ASP. For example, if you use this line of debugging code, you will not necessarily catch the error in the following block of code: Dim intCounter For intCounter = 1 to 100 intResult = intCounter / (intCounter - 100) Next In this snippet, you would have to add code before the Next statement to catch the division by zero error that will arise when `intCounter` is 100. Adding these lines to catch errors throughout your code is costly in processing time and error-prone in its own right, since you have to anticipate the line on which an error is likely to occur in order to effectively trap it. As a result, and because the ASPError object provides more information than the Err object, you should not use On Error Resume Next if you can avoid it. Another excellent use of the ASPError object page, 500-100.ASP (or similar, customized scripts for errors) is to handle errors that occur in a publicly available site. For example, you could customize the 500-100.ASP script to contain your site's color scheme and background and to include a Help phone number that could connect the user experiencing difficulty with someone who could help. And support personnel can field the call more effectively if you take advantage of the more extensive range of information that the ASPError object can provide to the 500-100.ASP script. Another possibility is to use 500-100.ASP to route an error notification to the appropriate personnel "in the background," and to hide the details of the error from the end user. This version of 500-100.ASP would simply display the fact that an error has occurred and that the user should try his or her action later, while—in the background—sending an error email to support personnel. An example script that performs these functions can be found at the end of this chapter. The code examples that illustrate the properties of the ASPError object all make use of three different error-generating scripts. The first contains a syntax error, the second contains an error in a preprocessing directive, and the third generates a runtime error. While the examples all make use of the same three ASP pages to generate errors, it is the contents of the custom error page 500-100.ASP that change to illustrate the particular property. The three ASP pages that raise errors are the following: ** BEGIN Error Generating Script #1 <HTML> <HEAD><TITLE> Error Generation Page #1 </TITLE></HEAD> <BODY> <% ' This page contains a syntax error. ' In the following For...Next loop, the keyword ' "For" is mispelled. Dim intCounter Fir intCounter = 1 to 100 %> Look everyone! I'm counting: <%=intCounter%><BR> <% Next %> </BODY> </HTML> END Error Generating Script #1 BEGIN Error Generating Script #2 <HTML> <HEAD><TITLE> Error Generation Page #2 </TITLE></HEAD> <BODY> <% ' This page contains a preprocessing error. ' The work "file" in the #INCLUDE preprocessor ' directive is mispelled: %> <!--#include fil=/headers/AdminHeader.INC --> </BODY> </HTML> END Error Generating Script #2 BEGIN Error Generating Script #3 <HTML> <HEAD><TITLE> Error Generation Page #3 </TITLE></HEAD> <BODY> <% ' This page contains a runtime error. ' In the following For...Next loop, when the ' intCounter variable gets to zero, the result ' is a divide by zero error. Dim intCounter Dim dblDivResult For intCounter = 1 to 100 dblDivResult = intCounter / (intCounter - 100) %> Look everyone! I'm dividing: <%=dblDivResult%><BR> <% Next %> </BODY> </HTML> END Error Generating Script #3 **

File

objASPError.File

The File property contains the full path to the file containing the error-producing code. This filename contains the full path of the file from the web root.

Parameters
None

Example
This example uses the error-generating scripts listed at the end of the Comments/Troubleshooting section. It assumes that the following code has been added to the default custom error script, 500-100.ASP: ** BEGIN File Example Script <% ' This script demonstrates the use of the File ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the File property is " & objMyASPError.File %> END File Example Script When the error-generating scripts are executed, the preceding File script generates the following three responses: Error Generating Script #1: The value of the File property is /errorgen1.asp Error Generating Script #2: The value of the File property is /errorgen2.asp Error Generating Script #3: The value of the File property is /errorgen3.asp**

Notes
Note that the file path is listed from the web server's root path, not from the root of the current application.

Line

objASPError.Line

The Line property is a long value representing the line number where the error-producing code occurs.

Parameters
None

Example
This example uses the error-generating scripts listed at the end of the Comments/Troubleshooting section. It assumes that the following code has been added to the default custom error script, 500-100.ASP: ** BEGIN Line Example Script <% ' This script demonstrates the use of the Line ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Line property is " & objMyASPError.Line %> END Line Example Script ** When the error-generating scripts are executed, the preceding Line script generates the following three responses: Error Generating Script #1: The value of the Line property is 11 Error Generating Script #2: The value of the Line property is 11 Error Generating Script #3: The value of the Line property is 14

Notes
The line count starts with the very first ASP line of code and begins with 1.

Number

objASPError.Number

The Number property contains a long value that represents an error code returned by a COM component. This long value will be a standard COM error code.

Parameters
None

Example
This example uses the error-generating scripts listed at the end of the Comments/Troubleshooting section. It assumes that the following code has been added to the default custom error script, 500-100.ASP: ** BEGIN Number Example Script <% ' This script demonstrates the use of the Number ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Number property is " & objMyASPError.Number %> END Number Example Script When the error-generating scripts are executed, the following three responses are generated: Error Generating Script #1: The value of the Number property is -2146827263 Error Generating Script #2: The value of the Number property is -2147467259 Error Generating Script #3: The value of the Number property is -2146828277**

Notes
None

Source

objASPError.Source

The Source property is a string containing the line of code that caused the most recent error, if that code was syntactically incorrect.

Parameters
None

Example
This example uses the error-generating scripts listed at the end of the Comments/Troubleshooting section. It assumes that the following code has been added to the default custom error script, 500-100.ASP: ** BEGIN Source Example Script <% ' This script demonstrates the use of the Source ' property of the ASPError object. Dim objMyASPError Set objMyASPError = Server.GetLastError( ) Response.Write "The value of the Source property is " & objMyASPError.Source %> END Source Example Script When the error-generating scripts are executed, the preceding Source script generates the following three responses: Error Generating Script #1: The value of the Source property is Fir intCounter = 1 to 100** Error Generating Script #2: The value of the Source property is [EMPTY] Error Generating Script #3: The value of the Source property is [EMPTY]

Notes
As mentioned previously, the Source property is only useful if the error produced is syntax-related. Otherwise, this property is empty.