Debugging Script Objects in ASP Pages for Microsoft Visual InterDev 6.0 Developers

Susan Warren
Microsoft Corporation

May 26, 1999

Summary: Visual Studio® 6.0 Service Pack 3 and later supports tracing and debugging of Script Language objects in ASP pages. This important update catches errors that occur in lower-level components (such as during database access), traces events fired by script objects, and displays warnings when script objects encounter possible errors.

What Is the Scripting Object Model?

The Visual InterDev scripting object model defines a set of objects with 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®.

Unlike Visual Basic controls, the script objects in Visual InterDev don't 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.

Visual InterDev ships 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. 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:

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

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

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

When you create a new ASP page with Visual Studio 6.0, Service Pack 3 and later, the ASP page includes a script block at the top with debugging options.

Note   For projects created prior to installing Service Pack 3 and later, you must copy the new Script Library files into your project.

By default, the options are turned off. The script block looks like this:

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

Note   Script object debugging requires Microsoft JScript® 5.0 or higher to be running on the server. You can install JScript version 5.0 onto the server from the Microsoft Visual InterDev 6.0 CD or from the Microsoft Scripting Web site, located at http://msdn.microsoft.com/scripting/.

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=javascript>
// Set these to true to enable debugging or tracing
@set @debug = true
@set @trace = false
</SCRIPT>

Note   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 table. Details about the individual settings appear in later sections of this topic.

Option Description
@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 normally occur silently.

Note   If you set @trace to true, it overrides the settings for @trace_events and @trace_warnings. However, if @trace is false, you can turn each trace option on and off individually.

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=javascript>
@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.

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 JavaScript, you can call a global script that assigns a function pointer to a window object event, as in the following:

<SCRIPT LANGUAGE="JavaScript">
   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 above to call this script when the document first loads.

<SCRIPT LANGUAGE="JavaScript">
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 normal 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 ombeforeopen event.
EVENT TRACE: Recordset1 fired onrowenter event.
EVENT TRACE: Recordset1 fired ondatasetchanged event.
EVENT TRACE: Recordset1 fired ondatasetcomplete event.
(etc)

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

Note   Before you put your pages into production, be sure to set any debugging conditions to false.

For more details about conditional compilation, see the @if and @set commands in the Statements section of the Microsoft Scripting Web site, located at http://msdn.microsoft.com/scripting/default.htm?/scripting/JScript/doc/Jstoc.htm.

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.