Debugging Script Objects in ASP Pages

To debug script object in ASP pages, you should consider the following:

• What is the Scripting Object Model?

• Debugging and the Script Library

• Enabling Script Object Debugging

• Reporting Errors

• Tracing Events

• Tracing Warnings

What is the Scripting Object Model?

The ASP scripting object model defines a set of objects that have events, properties, and methods that you can use within your Web application. Most script objects represent user interface, elements like buttons and text boxes, and function in a manner similar to controls in Microsoft Visual Basic.

Script objects in Visual Studio 2010 do not require a special runtime; they are defined in script files that are included in your ASP page when you use the objects. Although these files are merely script, they encapsulate ActiveX Data Objects (ADO) commands and HTML elements to create sophisticated objects that support event-driven programming.

There are two versions of each script object: one that executes on the server in ASP for generic HTML 3.2 browsers, and another that executes on the client in Internet Explorer 4.0 and later versions. The programming model (events, methods, and properties) is identical for both versions. Script objects can be created and used directly from code, or with the help of Design-Time Controls. When the ASP page is saved, the script object code is persisted as a combination of standard HTML and script.

Debugging and the Script Library

Because script objects are themselves written in script, debugging the scripts you write that interact with the scripting object model can be complicated, for the following reasons:

• First, when you use the debugger to step through your own script, you can end up stepping into the unfamiliar and sophisticated code of the script library.

• Second, if an error occurs inside the script library, stepping through it can be tedious and might not help you pinpoint the error.

• Finally, it can sometimes be difficult to follow the sequence of events and the flow of control between your script and the scripting object model.

Now you can debug your application under these circumstances with these scripting object model debugging options:

• Catch low-level errors — If a script object, such as a Recordset, encounters an error, it can alert you with detailed error messages. This option helps you find errors with components that might fail for external reasons.

• Trace events — You can have the page display a listing of the events that are fired as they occur. This option helps you see when your scripts are being executed in relation to scripting object model events.

• Trace warnings — You can see warning messages indicating possible errors that otherwise occur silently. This option helps you find problems such as those caused by passing invalid parameters to a method.

Enabling Script Object Debugging

An ASP page ordinarily includes a script block at the top with debugging options. By default, the options are turned off. The script block looks like this:

<SCRIPT id=DebugDirectives runat=server language=JScript>

// Set these to true to enable debugging or tracing

@set @debug=false

@set @trace=false

</SCRIPT>

Script object debugging requires JScript 5.0 or higher to be running on the server. You can download JScript version 5.0 onto the server from the Microsoft Web site.

To enable debugging, set the debugging options that you want to true. For example, to catch low-level errors, change the block to this:

<SCRIPT id=DebugDirectives runat=server language=JScript>
// Set these to true to enable debugging or tracing
@set @debug = true
@set @trace = false
</SCRIPT>

The debugging option block must appear immediately following the @language directive at the top of the ASP page.

You can set four options in all, as described in the following list:

Name	Purpose
@debug	Reports selected errors in specific script objects..
@trace	Turns on both of the following trace options.
@trace_events	Turns on event tracing.
@trace_warnings	Turns on warnings for possible errors that ordinarily occur silently.

Details about the individual settings appear in later sections of this topic.

The individual tracing options are not part of the default script block in the ASP page, so you must add them if you want to set them individually. For example, the following enables only event tracing while leaving warnings off:

<SCRIPT id=DebugDirectives runat=server language=JScript>

@set @debug = false

@set @trace = false

@set @trace\_events = true

</SCRIPT>

If you are using Microsoft Internet Explorer 4.x, setting any of the @trace options will override the BODY tag, which can disable event binding in the BODY tag and will cause attributes to be ignored. This problem does not occur if you are using Internet Explorer 5.0 or later versions.

The following style of event binding will not work in Internet Explorer 4.0:

<BODY onload="initialize()">

To work around this limitation, use a different binding mechanism. If you are using Visual Basic, Scripting Edition (VBScript), you can use implicit binding:

<SCRIPT LANGUAGE="VBScript">

Function window_onload()

initialize()

End Function

</SCRIPT>

If you are using JScript, you can call a global script that assigns a function pointer to a window object event, as in the following:

<SCRIPT LANGUAGE="JScript">
   window.onload = initialize
</SCRIPT>

If the BODY tag currently contains attributes, you should set these in script instead by setting properties of the document object. For example, if the BODY tag currently contains the attribute BGCOLOR="#FFFF00", you can set it using a script such as the following. Use the technique listed earlier in this section to call this script when the document first loads.

<SCRIPT LANGUAGE="JScript">
function initialize(){
   document.bgColor = "#FFFF00";
}
</SCRIPT>

Reporting Errors

Some script objects interact with other objects outside your page. For example, the Recordset object uses ADO to access databases. If errors occur during these interactions, the error information reported by the external object can be ambiguous or can seem incomplete in the context of your page.

The @debug option enables a reporting mechanism that catches and interprets a common set of these types of errors. Error information is written to the ASP page and appears along with the page's regular contents. In some cases, the underlying error message appears as well.

For example, if @debug is set to true, and if the Recordset object attempts to execute an invalid SQL statement, you might see something like the following in your page:

SCRIPTING OBJECT MODEL EXCEPTION:

FILE: recordset.asp

FUNCTION: Recordset1.open()

DESCRIPTION: Failed to open the ADO recordset. Check for the following

possible causes:

An invalid SQL statement.

Missing or invalid database object name (check Recordset DTC properties)

Missing parameters or parameter type mismatch (parameters must be set

before recordset is opened).

Tracing Events

When an ASP page uses the scripting object model, the individual script objects fire events in response to state changes (such as Recordset1_ondatasetcomplete) or in response to user actions (such as Button1_onclick). Often, you need to know when your own scripts are executing in relation to the events being fired by the scripting object model.

To do this, turn on event tracing by setting the @trace or @trace\_events option to true. When you enable event tracing, event information is written to the ASP page as it occurs. For example, a portion of an ASP page might look like this:

EVENT TRACE: thisPage fired oninit event.

EVENT TRACE: Recordset1 fired onbeforeopen event.

EVENT TRACE: Recordset1 fired onrowenter event.

EVENT TRACE: Recordset1 fired ondatasetchanged event.

EVENT TRACE: Recordset1 fired ondatasetcomplete event.

To determine when your script is being executed, include Response.Write statements at important points, as illustrated in the following script. The example sets a parameter for a recordset based on information in a text box. Each step is reported by displaying it on the page.

Sub btnQuery_onclick()

Recordset1.close()

Response.Write("Finished closing recordset.")

Recordset1.setParameter 1, txtLastName.value

Response.Write("Finished resetting query parameter.")

Recordset1.open()

Response.Write("Finished reopening recordset.")

End Sub

By using JScript conditional compilation commands, you can specify that your Response.Write statements appear in the page only if you set debugging options. For example, in the following block, the Response.Write statement is only executed if the @trace option is set to true:

@if (@trace)

Response.Write("Ready to set SQL statement parameters.");

@end

You are not limited to using the debugging options — you can create your own condition flags as well, as in the following example:

@set @trace\_custom = true

' ... other script here

@if (@trace_custom)

Response.Write("Ready to set SQL statement parameters.");

@end

For more details about conditional compilation, see the @if and @set commands in the Statements section of the Microsoft Scripting Web site.

Tracing Warnings

To make script objects as robust as possible and to minimize the display of unwanted

information on an ASP page, script objects generally do not report non-fatal errors. For example, if you pass an invalid value to a script object's method, and if the value does not cause the object to fail completely, the object will frequently continue executing without an error message. While you are developing your application, however, you will typically want to know if the script object has experienced a possible problem. Unreported problems can sometimes result in different problems later during page execution, making it harder to debug your page.

The solution is to trace warnings by setting the @trace or @trace\_warnings option to true. If a script object encounters a possible problem, it will then write information to the page in a format such as the following:

WARNING TRACE:

FILE: recordset.asp

FUNCTION: Recordset1.open()

DESCRIPTION: Recordset is already open.

See Also

Tasks

How to: Enable Script Debugging in Internet Explorer

Concepts

Understanding ASP Script Processing

Other Resources

Debugging ASP Applications