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.
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.
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:
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>
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).
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.
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.