Debugging Phantom Scripts

The Phantom Debugger

The Phantom Debugger is a separate program that attaches itself to Phantom for Windows and allows you to

Start and stop playback of the currently selected Phantom script.
View the values of all variables in the running script in real time.
Single-step. Execute the statements in your script one at a time.
Watchpoints. Cause your script to halt when a variable changes value or acquires a specific value.
Filter the variables displayed so that only the values of interest are displayed.

The Phantom Debugger main window is shown below.

The Phantom Debugger main window is composed of three areas. The uppermost area displays the statements of the Phantom script as they are executed. This is the same information that appears in the Phantom Control Panel log window. To the right of the debugger log window is a column of buttons that you use to control Phantom's execution during a debugging session. The bottom portion of the Phantom Debugger main window contains an alphabetized list of the variables that have been created by the script and their current contents.

The Phantom Debugger main window can be resized to allow viewing of more information or to minimize the amount of screen space used.

Note that executables generated from phantom scripts can only be debugged using the Phantom Debugger is the "Enable EXE Debugging" checkbox in the Phantom Options Dialog was checked when the executable was generated.

Starting a Debugging Session

To begin debugging a script, start the Phantom Debugger after Phantom itself has been started. If you start the debugger first, it cannot connect to Phantom and after you start Phantom you will have to execute a script from Phantom to initiate the debugger session.

Select the script that you wish to debug in the Phantom Control Panel. You can now initiate playback using the debugger's Play or FastPlay buttons. The script will stop after the first few lines have been executed. You can now click on the Go button to execute your script at normal speed or on the Step button to execute statements one at a time. The statement just executed is displayed in the log pane at the top of the debugger window. The variables created by your script are displayed in the lower pane.

Breakpoints

You can insert Breakpoint statements in your scripts to cause the debugger to automatically halt at that point in your script. Breakpoint statements have no effect if the debugger is not running when the script is executed.

Watchpoints

The debugger Settings menu allows you to set watchpoints and filters. A watchpoint is a condition that, when it occurs, will cause your script to halt in the debugger. The dialog presented to edit watchpoints is show below.

You specify the variable that you are interested in using the combobox at the upper left. The variables currently shown in the variables pane of the debugger are included in the list. You can select one of these or type in the variable name yourself. You can specify that execution should halt when the value of the variable changes or when the variable acquires a specific value using the radio buttons below the combobox.

Click on the Add button to add your new watchpoint to the list in the lower portion of the dialog. If the checkbox at the left of the watchpoint is checked, the watchpoint is active and will be checked during script execution if watchpoints are enabled. (Watchpoints are enabled using the Settings menu of the debugger.)

When you are satisfied with your watchpoints, click on Ok to save them. Clicking on Cancel will discard the changes you made.

When you use the Go button, if watchpoints are enabled and an active watchpoint is in the list, watchpoints will be examined after each instruction execution. This process slows execution of scripts significantly, so you will want to make sure watchpoints are disabled when you are not using them.

You can change the watchpoints while a script is in execution. It can be especially useful to enable and disable watchpoints individually as script execution proceeds.

Filters

Filters restrict the variables shown in the variable list of the debugger to only those variables you are interested in. Two filters are available. The intrinsic variable filter, enabled with the Hide Intrinsic Variables menu item, elminates all the variables automatically created by Phantom with the exception of the variable TimedOut.

You can create a filter of your own using the Edit Filter menu item. A list of the variables currently listed in the debugger variable list is shown. You checkmark the variables that you wish to remain present in the variable list. If the filter is enabled with the Enable Filter menu item, variables not on the list will be removed from the debugger variable list.

Problems With the Debugger

The Phantom Debugger is very new and problems can occur when executing scripts at normal speed with the debugger, especially if the scripts perform a significant amount of mouse or keystroke playback or manipulation of windows on the screen. We hope to address these problems soon, but the utility of the debugger is so high that we felt it was better to release it in its current state than to delay until all the problems were addressed.

If the debugger appears to hang during playback, try using Ctrl-Esc to regain control.

Other Information

If you use the SetPhantom LoggingOff statement in your script, the debugging output is not affected.

The output of Log statements is written to the debugger log as well as to the Phantom log window.