Visual InterDev

Debugging Script Objects in ASP Pages

Enabling Script Object Debugging

When you create a new ASP page, it 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=javascript>
// Set these to true to enable debugging or tracing
@set @debug=false
@set @trace=false
</SCRIPT>

Note Script object debugging requires 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 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.

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

<BODY onload="initialize()">

To work around this limitation, use a different binding mechanism. If you are using 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 ActiveX Data Objects (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 ondatasetcomplete) or in response to user actions (such as 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 JScript Language Reference.

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.