Debugging Scripts

Microsoft® Script Debugger provides you with a comprehensive debugging environment for testing and correcting errors in your Web document scripts. You can use the debugger to test scripts written in Microsoft Visual Basic® Scripting Edition (VBScript) and Microsoft JScript, as well as programs written in Sun Microsystems® Java™ and run using the Microsoft Java Virtual Machine (VM). If you have installed an alternative scripting language, such as REXX or Perl, you can also debug scripts in that language.

You can use Microsoft Script Debugger to debug both client scripts and server scripts:

• Client scripts consist of statements that appear on the HTML page. The script is executed by the Web browser either when the document is loaded, or in response to an event such as a button click.

• Server scripts consist of statements embedded in an ASP page (Active Server Page). The script is executed by the Microsoft Internet Information Server (IIS) server when the page is requested by the browser but before the content is sent to the browser. Server scripts typically manage links between pages, process HTML forms, interact with databases, and so on.

Working with Microsoft Script Debugger

Microsoft Script Debugger works the way many debuggers do, by allowing you to:

• View the source code of the script you are debugging.

• Control the pace of script execution.

• View and change variable and property values.

• View and control script flow.

Viewing Source

When you work with Microsoft Script Debugger, you see the script you are debugging in a window. The following illustration shows a typical debugging session:

Note   You cannot change text in the window - documents are read-only while you are debugging. However, you can save the document under a new name, then open the new document and modify it. For details, see Managing Documents.

Controlling Program Execution

To control program execution, you set breakpoints, which are places where the script should pause and call the debugger. When you set breakpoints, the line containing the breakpoint is highlighted in the editing window, as shown in the following illustration:

After setting breakpoints, you run the document containing the script. When execution reaches the first breakpoint, the script pauses and starts the Script Debugger. The current line is marked in the editing window, as shown in the following illustration:

After reaching a breakpoint, you can execute, or step into, individual lines in your script. As you step through lines, the script executes and you can see the effect of each line.

If you reach a point in your script that calls another procedure (a function, subroutine, or the script associated with an object or applet) you enter (step into) the procedure or run (step over) it and stop at the next line. At any point, you can jump to the end (step out) of the current procedure and carry on with the rest of the script.

Viewing and Changing Values

While debugging, you can view and change the values of variables or properties. Because you are making changes directly to a running script, you can affect the way the script executes by changing values in it. After changing values, you can continue with the script and see the effect of your change.

To view and change values, you use the Command window. You can evaluate any expression in the window and can enter script commands and see their effect. You enter commands in the language of the script currently executing. The following illustration shows how you can get the value of a variable using VBScript:

And the following shows the same, but in JScript:

Viewing and Controlling Program Flow

The Call Stack window allows you to trace the procedures and functions that are currently executing. While debugging you can view the flow of control from procedure to procedure. You can also select a procedure in the call stack and jump directly to it, and then continue running the script. The following illustration shows a typical call stack:

See Also

For general information about debugging, see the following topics:

• Understanding Script Errors

• Server Script Debugging

• Client Script Debugging

• Debugging Tips and Tricks

• Preventing Bugs

For specific information about using the Script Debugger, see the following topics.

• Starting the Script Debugger

• Choosing a Document to Work With

• Setting Breakpoints

• Clearing Breakpoints

• Stepping Through Scripts

• Viewing and Changing Values

• Executing Script Commands

• Viewing the Call Stack

• Managing Documents

• Debugging the Global.asa File

• Debugging Java Programs

For details about the Script Debugger toolbar, menus, and windows, see the following topics:

• Debug Toolbar Reference

• Debug Menu

• File Menu

• Running Documents Window

• Call Stack Window

• Command Window

• Debugger Tab, Options_Window

Understanding Script Errors

Errors in scripts can take three forms: syntax errors, runtime errors, and logic errors.

Syntax Errors

Syntax errors occur if you mistype a keyword, forget to close a multiline command (such as DO ... LOOP), or introduce a similar syntax error. If your script includes a syntax error, the script will not execute, and an error message is generated.

Note   In some programming environments, syntax errors are referred to as pre-processor, compilation, or compile-time errors.

The result of a syntax error depends on what type of debugging you are doing:

• If the syntax error is in a server script, and if debugging is enabled for the ASP-based application, document processing stops. The server starts the script debugger, which displays the error message. If the browser that requested the document is on a different computer, the browser displays an error indicating that the document could not be found, as shown in the following illustration:

  

• If the syntax error is in a server script, but debugging is not enabled for the ASP-based application, error text is passed through and displayed in the client browser instead of the requested page, as shown in the following illustration:

  

• If the syntax error is in a client script, the document loads, but the script in which the error occurs does not run properly. The exact behavior of the script at that point will depend on where in the script the error occurs. Each time the script is run, the error message appears again. A typical error message looks like the following illustration:

  

Tip   The text of the error message might not always reflect the exact error. For tips about finding errors, see Debugging Tips and Tricks.

If you write programs in other environments, you will notice that syntax errors are handled differently when you are writing HTML scripts. In Visual Basic, for example, syntax errors are caught by the interpreter as soon as you leave the line in which the error appears. However, when you write scripts for HTML documents, the code is not interpreted until the code is executed - namely, when the document is requested by a browser.

Runtime Errors

A runtime error occurs when a command attempts to perform an action that is invalid. For example, a runtime error occurs if you try to perform a calculation using a variable that has not been initialized.

The conditions that result in runtime errors depends on the language you are scripting with. A condition that might cause a runtime error in VBScript might not cause an error in JScript. For example, attempting to divide by zero results in a runtime error in VBScript, but not in JScript.

If there is a runtime error in a server script, and debugging is enabled for that application, the server starts the debugger, which displays an error message:

If a server script contains a runtime error and debugging is not enabled for that application, the error message text will appear in the client browser:

If a runtime error occurs in a client script, you might see an error such as the following when the document is loaded into Microsoft Internet Explorer:

The result of a runtime error is similar to that of a syntax error: if you are debugging on the server, an error message appears in the script debugger on the server. Otherwise, error text appears in the client browser.

Depending on the language you are using, you might be able to include statements in your scripts to trap runtime errors and run your own error procedures. For example, in VBScript, you can use the ON ERROR statement to establish error trapping. For more details, see the documentation for your scripting language.

Logic Errors

You commonly use the Script Debugger to help you track down logic errors. A logic error occurs when a script executes without errors, but the results are not what you intended. For example, a script might prompt the user for a password. If the script is supposed to prevent the user from proceeding without a valid password, but it doesn't, you have a logic error in the script. In the case, you might use the Script Debugger to run the document, and then step through each line to see why the script doesn't execute the logic the way you intended.

See Also

Client Script Debugging

Debugging Tips and Tricks

Preventing Bugs

Server Script Debugging

Server Script Debugging

Understanding how scripts in ASP pages are processed and how errors are handled can help you debug server scripts successfully. To debug server scripts - scripts in ASP pages - you run Microsoft Script Debugger on Microsoft Internet Information Server (IIS), version 4.0 or higher, and attach it to a currently running document.

Note   To debug client scripts, you must run Microsoft Script Debugger on the same computer that is running Microsoft Internet Explorer. For more details, see Client Script Debugging.

Processing Server Code

Script in an ASP page is not event-driven. Instead, when the page is requested, the server reads the page and processes all server script from top to bottom. Both syntax errors and runtime errors are caught immediately.

A special case for server scripts is the Global.asa file. The Application_OnStart and Session_OnStart procedures in this file are executed only once for an application and for a session. Therefore, you must embed debugging statements in the file. For details, see Debugging the Global.asa File.

Using the Script Debugger With Server Code

To use Microsoft Script Debugger, you must be sure that the debugger is enabled. For details about enabling and disabling the debugger for IIS, see "Debugging ASP Scripts" in the IIS documentation.

If the debugger is enabled:

• When the ASP-based application encounters an error (syntax or runtime) in an ASP page, the server stops processing and starts the debugger.

• Error information is displayed in message boxes on the server. If there is a syntax error, no content is sent to the client browser. If there is a runtime error, only the portion of the content up to the error is sent to the client browser.

  Note   If the debugger is enabled on the server, someone must attend the server to view and acknowledge error messages.

If the debugger is disabled:

• Error information is sent to the client browser and appears in the text of the page. It does not appear in a message box.

• You cannot invoke the debugger at all on the server.

See Also

Debugging Scripts

Starting the Script Debugger

Client Script Debugging

Understanding how scripts in HTML documents are processed and how errors are handled can help you debug client scripts successfully. To debug scripts in HTML documents, you run Microsoft Script Debugger on your client computer and attach it to a document currently running in Microsoft Internet Explorer or Outlook.

Note   To debug server scripts - scripts in ASP pages - you must run Microsoft Script Debugger on the same computer that is running Microsoft Internet Information Server (IIS). For details, see Server Script Debugging .

Processing Client Code

Client scripts (scripts in an HTML page) are processed by a browser such as Microsoft Internet Explorer. The browser calls the appropriate runtime module to process VBScript scripts, JScript scripts, or Java programs.

Client scripts are initially parsed when the HTML document is loaded into the browser. During this parsing phase, the browser reports any syntax errors that it finds.

After parsing a section of script, the browser executes it. Global or inline scripts, which are scripts that are not part of an event-handling subroutine or function, are executed immediately. Event-handling subroutines or functions, and procedures that are called by other procedures, are parsed immediately but are not executed until triggered by an event or called by another procedure.

If a runtime error occurs when a client script runs, an error message is displayed and script execution stops. The remainder of the HTML document can continue to run. If the script containing the error is called again, the error message is displayed again.

Using the Script Debugger With Client Scripts

If an error occurs in a client script, Microsoft Internet Explorer displays an error message indicating the error and the line on which it was found, as in the following illustration:

If you choose to view the source, Internet Explorer starts the debugger and displays the script in a read-only window. You can navigate in the document, set breakpoints, and run the document again. However, you cannot directly edit the source code in the debugger. If you have access to the original document file (the .htm file), you can make changes to that file, and then reload it in the browser.

Note   If you are debugging a client script generated by an ASP page, the line numbers reported in error messages refer to lines in the HTML document currently displayed in the browser. These usually do not correspond to line numbers in the original ASP page, because server script does not appear in the HTML output of an ASP page.

See Also

Debugging Scripts

Starting the Script Debugger

Debugging Tips and Tricks

The following tips can help you find errors in your scripts more easily while you are using Microsoft Script Debugger.

• If you are debugging server scripts, enable the Script Debugger. If the debugger is not enabled on the server, error messages are passed as text to the client browser, but you cannot use the Script Debugger with your server scripts.

• When the Script Debugger is enabled on the server, all server-side errors are passed to the debugger. Therefore, you should not enable the Script Debugger on the server unless you can work on the server itself.

• If you are working in a client browser that is not on the server, and if an error is displayed on the page, there is an error in the server script. If an error message is displayed in a dialog box, the error is in a client script.

• If there is a syntax error in an ASP page, the client browser will not display the syntax error (unless the browser is running on the server). Instead, the client browser displays an error indicating that the browser cannot open the page, and eventually times out.

• When looking at line numbers in error messages:
  • If there is an error in the server script, the line number displayed in the error message points exactly to the error in the ASP page.

  • If there is an error in a client script of an ASP page, the line number does not point to lines in the ASP page. Instead, it points to a line number in the HTML output of that ASP page. To see the line where the error has occurred, view the source of the HTML file in the client browser. Do not view the ASP page.

Common Error Messages

The following table lists common error messages that can occur while you are creating scripts, and possible explanations.

Common Wrrors While Running Scripts

Error	Possible explanation
Client browser hangs after requesting  ASP page	Syntax error in an ASP page. If debugging is enabled for the application to which the ASP page belongs, the server invokes the Script Debugger on the server.
Expected end of statement	Misspelled command. Missing End statement to close If, Function, Sub, etc.
Type mismatch	Call to undefined function (check for misspelled function name, in particular if the error says "Type mismatch: '<undefined>'").
IE cannot open the Internet site <URL> ... The operation completed successfully.	Attempt to display an ASP page that generates no HTML output. The script or scripts in the ASP page have executed successfully. You can avoid this error by adding HTML output to the ASP page, or including a Response.Redirect statement to move to a page that does have HTML output.
The HTTP headers are already written to the client browser.	Attempt to use Response.Redirect in an ASP page to display a different page after some portion of the current page has already been processed. For example, the server might have already processed and sent the <HTML> tag.

Preventing Bugs

The Script Debugger can help you quickly find and fix errors in your scripts. Even so, it is still easier to create scripts if you prevent bugs in the first place. Below you can find information about:

• Common sources of errors

• Tips for preventing errors

Common Sources of Errors

Studies show that developers tend to make the same types of mistakes, no matter what language they are using or what program they are writing. The following table lists common problems that lead to bugs and suggestions for avoiding them.

Common Sources of Programming Errors

Problem	Suggestion for avoiding
Wrong data type in a variable, such as expecting a text value from a property instead of a number.	Explicitly declare variables, even if not required. For example, in VBScript, use the dim statement, and in JScript, use the var statement. Use naming conventions to help you remember variable types, such as txtName for a string, fDone for a flag, and intCounter for a number.
Not understanding a function or procedure; calling the incorrect function.	Double-check that the function you are calling performs the task you want it to.
Incorrect arguments for functions; arguments passed in the wrong order; not understanding what values a function or procedure returns.	Check syntax for functions whenever using them. Avoid relying on default argument values.
Not understanding the meaning of a value, such as whether the values passed to a Move method represent pixels or another unit, or whether they are absolute or relative.	Double-check argument definitions for all functions and methods.
Not understanding a data structure, such as the object model for a system, or trivial misunderstandings such as assuming that an array index begins with 1 instead of 0.	Check documentation for information about structure.
Typographic errors, such as misspelling a variable name or keyword, or forgetting to close a bracket.	Use consistent names to help avoid confusion. Type the closing portion of a statement as soon as you type the opening portion. For example, when you are creating a server script, as soon as you type <%, type %>, and then fill in the statements between the tags.
Unexpected data, such as a user typing in a string when prompted for a number, or a number value outside the bounds of what the program can use.	Anticipate errors introduced by users and create error handling routines.
Not understanding language conventions, such as using the wrong type of quotation marks to enclose literals. This is an easy mistake to make when switching between languages such as between Visual Basic and SQL.	Familiarize yourself with the operators and conventions of the language you are using.

Tips for Preventing Errors

The following tips might help you prevent problems while scripting.

• Provide closing HTML tags, even if you think the browser will process the tag without its closing tag. For example, you might think that the browser will close an <OPTION> tag automatically, even if you do not include the </OPTION> tag. However, many browsers will not.

• Be aware that the values returned by some functions and properties vary depending on the situation or context. For example, the ADO record set object supports a property called RecordCount, which is documented as returning the number of records affected by a statement. However, the value returned in this property depends on the database. Microsoft SQL Server does not return a useful value in this property, so you should not rely on it in your script. Instead, you should check RecordSet.EOF, using code such as the following:

  Do While Not RecordSet.EOF
  	' Process here
  	RecordSet.MoveNext
  Loop
  

Starting Microsoft Script Debugger

You can make Microsoft Script Debugger available in different ways, depending on how it will be used.

If you are debugging scripts on the client side, make sure that you have Internet Explorer and the Script Debugger installed properly. If you are debugging scripts on the server side, you must explicitly enable debugging mode for each ASP application you want to use the debugger with, or you cannot invoke the Script Debugger. For information about client-side and server-side scripts, see Debugging Scripts. For details about enabling and disabling the debugger for IIS, see "Debugging ASP Scripts" in the IIS documentation.

The Script Debugger can be started in these ways:

• Manually   You can open the Script Debugger as a standalone application. You would do this, for example, if you wanted to start the debugger in order to trace a logic error.

• By Viewing Source   If you are working in a browser on the client side, you can open the debugger by choosing Source from the View menu of Microsoft Internet Explorer. If you are working on Microsoft Internet Information Server, you cannot open the Script Debugger this way.

• Programmatically   You can include a command in your script (such as Stop in VBScript or Debugger in JScript) that stops execution and starts the debugger.

• By responding to a script error   If an error occurs while a script is running, a message is displayed. If the error is in a client script, the message offers you the opportunity to open the debugger to view the error. For example, if you see a message such as the following, you can choose Yes to start the Script Debugger.

  

  If the error is in a server script and debugging is enabled for the ASP-based application, the server opens the Script Debugger automatically and displays an error message, as shown in the following illustration:

  

Note   Debugging scripts in the Global.asa file works slightly differently. For details, see Debugging the Global.asa File.

To start the script debugger manually

1. In Microsoft Internet Explorer, display the document you want to work with.

2. Choose the Windows Start menu, and then choose Microsoft Script Debugger from the Programs menu.

3. In the Script Debugger, choose the document to work with. For details, see Choosing a Document to Work With.

To start the script debugger by viewing source

1. In Microsoft Internet Explorer, display the document you want to work with.

2. From the View menu, choose Source.

After you have started the Script Debugger, you set one or more breakpoints, return to the document in Internet Explorer, and perform an action. For more information, see Setting Breakpoints.

See Also

Choosing a Document to Work With

Debugging Java Programs

Executing Script Commands

Setting Breakpoints

Stepping Through Scripts

Viewing and Changing Values

Viewing the Call Stack

Choosing a Document to Work With

You can debug scripts in any document currently executing in Internet Explorer, Microsoft Outlook™, or another ActiveX debugging host. If you are debugging a Java program, you can choose the name of the Java function that you want to debug.

To choose a document to work with

1. From the View menu, choose Running Documents.

   - or -

   Click  on the Debug toolbar.

2. In the Running Documents window, select from the drop-down list the name of an application whose document you want to debug.

   A list of open documents for that application appears in the text area below the drop-down list.

   

   Note   The Global.asa file is not included in the list of running documents. For information about how to debug scripts in the Global.asa file, see Debugging the Global.asa File.

3. In the text area, click the plus sign next to the application name to display a list of open documents for that application.

4. Double-click a document name to open it.

See Also

Debugging Java Programs

Managing Documents

Starting the Script Debugger

Setting Breakpoints

Setting a breakpoint allows you to specify where in a script you want to stop execution and start the debugger. For example, you might want to start the debugger at the beginning of a procedure or before a line that you suspect might cause an error.

You can set breakpoints on specific lines, which helps you to pinpoint problems at particular points in your scripts. You can also set a breakpoint on the first executable line in an HTML document or ASP page, which enables you to start debugging as soon the first line of script is executed. Setting a breakpoint for the first script statement in a document is particularly useful for debugging scripts that are executed as part of a document's OnLoad event and for debugging ASP pages.

To set a breakpoint

1. Display the document in Microsoft Internet Explorer.

2. For client scripts, choose Source from the Internet Explorer View menu.

   - or -

   For server scripts, start the debugger as a standalone application, and then choose the document to work with. For details, see Starting the Script Debugger and Choosing a Document to Work With.

3. In Microsoft Script Debugger, place the insertion point in the line where you want the breakpoint.

   Note   If you are setting a breakpoint in a Java program, select the entire statement.

4. From the Debug menu, choose Toggle Breakpoint.

   - or -

   Click  on the Debug toolbar.

   The line where you set the breakpoint is displayed in red to indicate that it is a breakpoint.

   

5. Repeat Steps 2 and 3 for each breakpoint you want to set in the document.

6. Switch to Internet Explorer.

7. For client scripts, perform an action (such as clicking a button) that will start the script you want to debug.

   - or -

   For server scripts, refresh the document in the browser.

The debugger stops at the first breakpoint it encounters. You can now execute (step through) lines one by one. See Stepping Through Scripts.

Setting a breakpoint for the first script statement in a document is particularly useful for debugging scripts that are executed as part of a document's OnLoad event. The script in the handler for this event has already been executed by the time the HTML document has completed loading, and any breakpoints set after the HTML document has completed loading are lost when the document is refreshed. Therefore, use the following procedure to debug script statements in an OnLoad handler.

To set a breakpoint for the first script statement in a document

1. Display the document in Microsoft Internet Explorer, and then from the Internet Explorer View menu, choose Source.

   The Microsoft Script Debugger opens with the current document visible in Source view.

2. From the Debug menu, choose Break at Next Statement.

   - or -

   Click  on the Debug toolbar.

3. Switch to Internet Explorer, and then refresh the document.

   The debugger stops at the first script line that is executed.

Note   You cannot use this method to set breakpoints in the Global.asa file. For information about how to debug scripts in the Global.asa file, see Debugging the Global.asa File.

See Also

Clearing Breakpoints

Executing Script Commands

Stepping Through Scripts

Viewing and Changing Values

Clearing Breakpoints

If you no longer want to start the debugger at a breakpoint in your script, you can clear the breakpoint.

Note   Breakpoints are cleared automatically if you reload a document in Internet Explorer.

To clear a single breakpoint

1. Place the insertion point in a line marked as a breakpoint (a line in red).

2. From the Debug menu, choose Toggle Breakpoint.

   - or -

   Click  on the Debug toolbar.

   The line is redisplayed in normal text.

If you are finished debugging a script, you can clear all its breakpoints.

To clear all breakpoints

• From the Debug menu, choose Clear All Breakpoints.

  - or -

  Click  on the Debug toolbar.

  Lines that were marked in red as breakpoints are displayed in normal text.

See Also

Setting Breakpoints

Stepping Through Scripts

You can use Microsoft Script Debugger to execute (step through) individual lines in a script. You can then view and check the results of each script line.

If the script calls another procedure or function, you can step into the procedure. Alternatively, you can step over the procedure. In that case, the procedure is executed, and when it finishes, you are left on the line immediately following the call to that procedure.

To step through scripts

1. Load the document to debug in Internet Explorer.

2. Start the debugger. For details, see Starting the Script Debugger.

3. Set a breakpoint. See Setting Breakpoints.

4. From the Debug menu, choose Run.

   - or -

   Switch to Internet Explorer.

5. Client scripts: Perform an action (such as clicking a button) that causes the script to execute.

   Server scripts: Refresh the document.

   The Script Debugger stops at the first breakpoint, displaying it in the editing window:

   

6. To step through the script, choose one of the following commands from the Debug menu or click one of the following buttons on the Debug toolbar:

   Command	Button	Action
   Step Into		Moves to the next script line. If the script calls another procedure, Step Into proceeds through the lines of that procedure.
   Step Over	.	Skips called procedures. The procedure is executed, but the debugger does not step through its individual lines. Instead, the debugger moves to the next line in the current procedure after executing the called procedure.

7. To stop stepping through lines of a procedure before reaching its end, choose Step Out from the Debug menu or click  on the Debug toolbar.

   The debugger moves to the next statement following the procedure.

8. Continue stepping through the script until you reach the end of the document.

See Also

Debugging Java Programs

Setting Breakpoints

Viewing and Changing Values

Viewing the Call Stack

Viewing the Call Stack

While debugging scripts, you can see a list of procedures (subroutines, functions, event handlers, and other scripts) that are currently loaded. Each time a procedure is called, the name of the called procedure is added to the top of the call stack. When the procedure ends, its name is removed from the call stack.

Viewing the call stack can help you trace the course of execution through a series of nested procedures. You can also use the call stack to navigate within the document to a specific procedure. When you navigate to another procedure, you can set breakpoints there, change variable values, and so on.

However, using the call stack to navigate to another procedure does not change the currently executing line. Even if you set a breakpoint or variable value in another procedure, execution resumes from the line where it was halted. If you execute a command in the Command window after navigating to another procedure in the call stack, the context of the command is still the procedure where you are halted.

When you are debugging Java programs, the call stack includes currently loaded Java methods. You will therefore see a mixture of procedure names from VBScript or JScript and the names of Java methods.

To view the call stack

• From the View menu, choose Call Stack.

  - or -

  Click  on the Debug toolbar.

To jump to a specific procedure

• In the Call Stack window, double click the name of the procedure to jump to.

See Also

Debugging Java Programs

Executing Script Commands

Viewing and Changing Values

While a script is running, you can use the Command window to view and change the values of variables and properties in the script. The Command window is live in the context of the current script, so that changes you make there can directly affect the currently executing script.

The commands, values, and properties that you can use in the Command window depend on the environment in which the debugger is running:

• Language   When working in the Command window, you enter commands using the syntax of the scripting language currently executing.

• Variable values   You can view and change variables that are in scope while the Command window is running. These include variables in the script that is currently executing as well as global variables.

• Properties   You can get and set the properties of any objects that are available in the context you are running. For example, if you are working with the debugger while using Microsoft Internet Explorer, you can get and set properties for Internet Explorer objects such as Window, Document, Form, and so on. On the other hand, if you are debugging a server script, you have access to properties for objects such as Application and Session.

You can execute script commands any time that you are at a debugger breakpoint or have stepped from a breakpoint to other statements.

To view and change variable values

1. Load the document and start the debugger. For details, see Starting the Script Debugger.

   For information about debugging the Global.asa, see Debugging the Global.asa File.

2. Set at least one breakpoint.

3. Return to the document and perform an action such as clicking a button or refreshing the document that causes the script to execute. The Script Debugger stops at the first breakpoint.

4. From the View menu, choose Command Window.

   - or -

   Click  on the Debug toolbar.

5. To view the value of a variable or property, do one of the following, depending on what the current scripting language is:
   • If the language is VBScript, enter a command that generates output (such as ? or debug.write), a space, and the variable to see. For example, enter ? Document.Title to see the title of the current document.

   • If the language is JScript, enter the name of the variable.

   The value of the variable is displayed in the window. The following illustration shows an example in JScript:

   

6. To change the value of a variable, assign it a value using the syntax of the current script language, as in the following examples:

   Document.Title = Document.Title & "  (Debugging)"
   txtLoginName = "Admin"

See Also

Debugging Java Programs

Setting Breakpoints

Stepping Through Scripts

Viewing the Call Stack

Executing Script Commands

You can use the Command window to execute script commands directly  - that is, without having to place them in a script and then run the script's document. By running script commands in the Command window, you can:

• Query or change the value of a variable or property while a script is running. While execution is halted, you can assign the variable or property a new value as you would in a script. For more details, see Viewing and Changing Values.

• Call procedures as you would in a script.

• View debugging output while the script is running.

When you use the Command window to execute script commands, you are working in the same environment as the current scripts, and can therefore affect the way the script runs. For example, you can use commands in the Command window to change the values of variables or properties and therefore change the way a script executes. You can also create new objects and properties in the Command window exactly the way you would in a script.

You can execute script commands any time that you are at a debugger breakpoint or have stepped from a breakpoint to other statements.

When using the Command window, use the language of the currently executing procedure. For details about script commands, refer to the documentation for your scripting language.

To execute script commands immediately

1. From the View menu, choose Command Window.

   - or -

   Click  on the Debug toolbar.

2. In the Command window, type in the command, and then press ENTER.

When you enter commands into the Command window, error messages are not sent to the browser. Instead, the Command window handles the error itself by displaying a message, as shown in the following illustration:

See Also

Choosing a Document to Work With

Debugging Java Programs

Viewing and Changing Values

Managing Documents

You can manage HTML documents or ASP pages using the HTML source editor in the Microsoft Script Debugger. The editor allows you to:

• Create and edit documents.

• View source code with syntax coloration.

• Save the document currently being debugged to any available location.

When you are debugging a document, the document is displayed in the Script Debugger window as a read-only document. You therefore cannot directly change the document's source code. However, you can save the document under a new name, and then open the new document, make changes, save it again, and then reload it in the browser.

You manage files using commands on the File menu. For details, see File menu.

Debugging the Global.asa File

Debugging the Global.asa differs from debugging ASP files.

• You cannot request the Global.asa file specifically in the client browser. Instead, the server executes its procedures automatically when you request other files in the .ASP-based application. Therefore, you cannot use a browser command such as the View Source to start the debugger.

• Procedures in the Global.asa file are event driven, unlike procedures in ASP pages.

• Procedures in the Global.asa file usually run only once per application or once per session:
  • The Application_OnStart procedure executes the first time that any user accesses any page in an .ASP-based application.

  • The Application_OnEnd procedure executes only when the application is shut down.

  • The Session_OnStart procedure executes only once per user session.

  • The Session_OnEnd procedure executes only when a user's session times out or when a script explicitly calls the Session object's Abandon method.

If there is an error in the Global.asa file (either a syntax error or runtime error), the server stops the procedure containing the error. If the Script Debugger is enabled for that ASP-based application, the server starts the debugger and displays an error message. If the Script Debugger is not enabled, an error message is sent to the client browser. In either case, the procedure containing the error stops. If you fix the error in the Global.asa file and request a page from the application again, the procedures in the Global.asa are executed again when the ASP-based application is restarted.

To control when the Script Debugger is called from the Global.asa file, include a statement that starts the debugger explicitly, such as Stop in VBScript or Debugger in JScript. Place the statement at the beginning of the procedure, before any statements that you will want to step through.

When the application starts or when a user starts a new session, the corresponding procedure in the Global.asa file will run. The Script Debugger will start when the Stop or Debugger is executed. You can then step through the procedure normally, use the Command window to evaluate expressions and set values, and so on.

However, you cannot stop and restart the script by refreshing the Global.asa file. If you want to rerun the Application_OnStart script, you must stop the application and then restart it. If you want to rerun the Session_OnStart script, you can restart your browser, which starts a new session and reruns the Session_OnStart procedure. Alternatively, you can request a page that includes a script to call the Session object's Abandon method, and then start a new session.

Debugging Java Programs

You can use the Microsoft Script Debugger to debug your Java programs (applets and components). For the most part, debugging Java is identical to debugging VBScript or JScript scripts. In a few instances, however, you must follow special procedures.

This topic provides the following information about debugging Java programs:

• Obtaining a Version of Java for Debugging

• Setting Options for Java Debugging

• Compiling Java for Debugging

• Starting the Script Debugger for Java Programs

• Setting Breakpoints in Java Programs

• Working with the Call Stack in Java Programs

• Working with the Command Window in Java Programs

Obtaining a Version of Java for Debugging

To use the Microsoft Script Debugger to debug Java, you must be using Microsoft SDK for Java 2.0. This version of Java is enabled for ActiveX debugging. You can download and install a preview release of the SDK from the Microsoft Web site at this address:

http://www.microsoft.com/java/

Setting Options for Java Debugging

You must explicitly enable Java debugging in Microsoft Script Debugger.

To enable Java debugging

1. In Microsoft Script Debugger, choose Options from the View menu.

2. Under Java Debugging, set the option to enable Java debugging.

3. In Source Path, type the root path for your Java source files. The debugger will search this path for source code.

4. Choose OK to close the Options window, and then exit the Script Debugger.

Compiling Java for Debugging

To be able to debug Java code, you must compile it with a debug option. To enable this option:

• Use the Java compiler available with Microsoft SDK for Java 2.0. The compiler is in the SDK directory with this path and name:

  \BIN\JVC.EXE

• Compile with a debugging option. If you are compiling from the command line, compile with the -g switch. If you are compiling with the Microsoft VJ++, select the Java Virtual Machine Debug build type in the Project Settings dialog box.

Starting the Script Debugger for Java Programs

To debug Java programs, the Java applets or components must be available to the debugger.

To start the Script Debugger for Java programs

1. In Internet Explorer, load the HTML document containing the Java applet to debug.

2. If necessary, perform an action that starts the applet.

3. From the View menu, choose Source.

   Microsoft Script Debugger opens with the HTML document containing your applet loaded.

4. In the Running Documents window, select the Java code to debug.

   Tip   If you double-click a class name in the Running Documents window and see no result, check that the path to the source code is correct.

For more information about starting the debugger, see Starting the Script Debugger and Choosing a Document to Work With.

Setting Breakpoints in Java Programs

Depending on the compiler you used, when you are setting breakpoints in a Java program, you might need to select the entire Java code statement. For more information, see Setting Breakpoints.

Working with the Call Stack in Java Programs

When you are debugging Java programs, the Call Stack window displays the names of procedures (if any) in the current scripting language as well as the names of any Java methods currently active. For more information, see Viewing the Call Stack.

Working with the Command Window in Java Programs

Using the Command window in Microsoft Script Debugger, you can evaluate Java expressions the same way that you can when debugging with VBScript and JScript scripts.

For example, to examine the contents of a variable called nLimit, type nLimit into the command window. The value of the variable is immediately displayed on the next line.

For more information, see Executing Script Commands and Viewing and Changing Values.

Debug Toolbar Reference

You can use the following buttons on the Debug toolbar as shortcuts for common debugging tasks.

Button	Name
	Start or continue execution of the current document.
	Stop debugging.
	Break into the debugger at the next (or first) statement in a document. For more information, see Setting Breakpoints.
	Step into (execute) the next statement. For more information, see Stepping Through Scripts.
	Step over (skip) the next statement. For more information, see Stepping Through Scripts.
	Step out of (quit) the current function. For more information, see Stepping Through Scripts.
	Insert or remove a breakpoint. For more information, see Setting Breakpoints.
	Remove all breakpoints. For more information, see Clearing Breakpoints.
	Display Running Documents window and select a document to debug. For more information, see Choosing a Document to Work With.
	Display the call stack to view and navigate to nested procedures. For more information, see Viewing the Call Stack.
	Open Command window to type in commands or expressions, or to view and change variable values. For more information, see Executing Script Commands and Viewing and Changing Values.

File Menu (Microsoft Script Debugger)

The File menu contains commands that enable you to manage files while in the debugger.

File Menu Commands

New   Creates a new, blank document that you can edit using the Script Debugger editor.

Open   Opens a document so you can edit it.

Close   Closes the current document. If you have not saved the document since making a change, the Script Debugger prompts you to save it before closing it.

Save   Saves the current document under its original name. If you are debugging a document, that document is read-only, and you cannot save it under its original name.

Save As   Saves the current document under a new name. If you are debugging a document and want to save it, you must choose this command.

Save All   Saves all currently open documents that are not read-only.

Exit   Closes the Script Debugger.

See Also

Managing Documents

Debug Menu (Microsoft Script Debugger)

The Debug menu contains commands that enable you to manage how scripts are executed while you are debugging.

Debug Menu Commands

Run   Causes execution to resume from the current statement.

Stop Debugging   Runs the current script to the end without stopping at any breakpoints.

Break at Next Statement   Causes execution to stop at the next scripting statement. You typically choose this command, and then refresh the document in the browser.

Step Into   Executes one statement at a time from the current execution point. If the statement is a call to a procedure, the next statement displayed is the first statement in the procedure. If there is no current execution point, the Step Into command might appear to do nothing until you perform an action that triggers a script, such as clicking a button.

Step Over   Executes one statement from the current execution point. However, if the current statement contains a call to a procedure, the Step Over command executes the procedure as a unit, and then steps to the next statement in the current procedure. Therefore, the next statement displayed is the next statement in the current procedure even if the current statement is a call to another procedure.

Step Out   Executes the remaining lines of the current procedure. The next statement displayed is the statement following the procedure call. All of the script is executed between the current and the final execution points.

Toggle Breakpoint   Sets or removes a breakpoint at the current line. You cannot set a breakpoint on lines containing nonexecutable code such as comments, declaration statements, or blank lines.

Clear All Breakpoints   Removes all breakpoints in your script. Your script can still interrupt execution, however, if you have embedded a Stop (VBScript) or Debugger (JScript or Java) statements, or if a runtime error occurs in your code.

See Also

Setting Breakpoints

Clearing Breakpoints

Stepping Through Scripts

Running Documents Window (Microsoft Script Debugger)

The Running Documents window displays a list of documents that can currently be debugged.

To display this window, choose Running Documents from the View menu.

Running Documents window

The combo box at the top contains a list of applications that are currently running documents that you can debug.

In the tree view below the combo box, each node represents an application. Click the plus sign (+) next to the node to display a list of documents to debug, and then select the document you want to work with.

See Also

Choosing a Document to Work With

Call Stack Window (Microsoft Script Debugger)

The Call Stack window displays a list of active procedure calls.

To display this window, choose Call Stack from the View menu.

Call Stack window

When a procedure is called, the debugger adds its name to the list of in the Call Stack window. When a procedure finishes and returns control to the calling procedure, the debugger removes its name from the list in the Call Stack window.

Double-click a procedure in the list to see the place in code where it was called from.

The Call Stack window is a floating window that isn't affected when other windows are repositioned using the Cascade, Tile Horizontally, or Tile Vertically command on the Window menu.

See Also

Viewing the Call Stack

Command Window (Microsoft Script Debugger)

The Command Window displays information resulting from debugging statements in your scripts or from commands typed directly into the window.

To display this window, choose Command Window from the View menu.

Viewing variable value in Command window (JScript)

Use the Command window to:

• Enter commands and see their effect.

• Evaluate expressions, including functions, property settings, variable values, and so on.

• Change the value of a variable or property while a script is running. While execution is halted, assign the variable or property a new value as you would in code.

• View debugging output while the code is running.

When entering commands in the Command window, use the syntax for the current scripting language.

See Also

Executing Script Commands

Viewing and Changing Values

Debugger Tab, Options Window (Microsoft Script Debugger)

Contains options for debugging Java programs.

To display this window, choose Options from the View menu.

Tab Options

Java Debugging

Enable Java Debugging   Choose this option to enable the debugger to step through Java code. The Java source files must be available. For details, see Debugging Java Programs.

Source Path   Specify the root path on the server for your Java source files. The debugger will search this path for source code.