This chapter describes how to install and use the Integrated Debugger Environment(IDE).
The ScriptEase Debugger makes it easy to follow what happens as the processor interprets a script, letting you watch it as it moves through each line of the script. You can open windows that will keep track of the variables in the script, allowing you to see their values and how and when they change. With the debugger, you can find the bugs that are tripping up your script in just a fraction of the time it would take without it.
The IDE debugger is only available for Windows 3.x (the executable is sedbgw16.exe) and Windows `NT and `95 (sedbgw32.exe). The debugger must be in the same directory as the ScriptEase processor (the ScriptEase installation process will put it in the correct place). Open the debugger by double clicking on its icon, dragging a script to its icon, or with the Window's Run command. If the debugger is already open, you can open a script in it with the Open command from the File menu, or by dragging a script directly to the debugger. The text of the script will appear in a window inside the debugger. The script window will have a white background, indicating that the debugger is in `text editor' mode. You can make and save changes to the script in the debugger when it is in this mode.
The Debugger and the ScriptEase processor work together to debug the script: the processor does the actual maneuvering through and interpretation of the script, whereas the debugger is like a window, letting you see what happens. Because of this close relationship between debugger and processor, the two must be kept in the same directory. At the very least, a shortcut or alias to the debugger must be in the same directory as the processor.
You can send a script to the debugger by dragging it to the debugger or its icon, or by opening the script from the debugger's File menu. Select Start from the Debug menu. The window background changes from white to grey, indicating you have gone into debugging mode. You cannot edit the script while it is in debugging mode, but all of the debugging options (described in this chapter) become available to you.
The ScriptEase Debugger has the following components: the menu bar, the tool bar, source windows, the watch window, the global variable window, the local variable window and the status bar. These features combine to allow you to control the flow of a debugging session, find out information about script that is running, and make any changes necessary to correct problems found.
The Menu Bar contains the following nine menus:
File - Commands for Opening, closing, saving, and printing files
Edit - Commands for cutting, pasting, and undoing changes in a file
View - Used to hide or display the tool bar and the status bar
Search - Search and search and replace
Options - Set Options for the Debugger
Run - Use to Stop or Go
Debug - All of the debug commands
Window - Commands to arrange and select windows
Help - Display help, and the about box
The File, Edit, View, Search, and Help menus are all standard Windows menus and should be self-explanatory. The Options, Run, Debug, and Window menu are described in further detail below.
The tool bar is displayed directly below the menu bar and has icons representing many of the most common debugger commands. Instead of selecting a command from a menu, you can click on the corresponding icon. Many of these same commands are also available as control key sequences and function keys(F1, F2, etc.).
Source windows are used by the IDE to display the source for the script that is currently being debugged. When the debugger is in text edit mode, the background of the source window will be white and you are able to edit and save files. When the window has a grey background, the debugger is in debug mode and you cannot change the text of the script.
The watch, local, and global windows display information about the data in your program. The global window shows all the known global variables. The local window shows all the known local variables. The watch window allows you to specify the exact variables you want to watch, and how you want to display them. You can also specify watch statements that will cause the script to stop when certain values are reached. These windows are opened from the Window menu.
The status bar at the bottom of the main window displays information about the active window of the IDE. It shows the current cursor position, and the state of the lock keys on your keyboard. It also gives information about the current state of the debugger.
The source mark is used to show the currently executing line in a ScriptEase script. You can set it to an image you like using the Options menu. It shows you what line the debugger is on in the currently loaded script.
The source mark should not be confused with the cursor. The cursor is used to select another line in a source window for the purpose of setting or clearing a breakpoint or stepping to a specific line number. The cursor is also used when the IDE is running in edit mode to select the insertion point in the script and to select text.
The Options menu has four options: Font, Tabs, Parameters, and Source Mark. Font lets you choose what font will be used to display text in the debugger's windows. Tabs allows you to set the number of spaces the debugger will insert when you hit the Tab key in text edit mode. Parameters allows you to load command line parameters into a script that is already in the debugger. Source Mark lets you change the appearance of the symbol used to mark your place in the script.
Use the Run menu to execute the script currently active in the debugger. When you use the Run menu, you are just executing the script; no other debugging features are possible. There are only two options on the Run menu: Stop and Go. Go executes the script; Stop terminates execution.
If you wish to run the script while in debugging mode, use the Stop and Go options on the Debug menu. If you want to run a script without selecting Start from the Debug menu first, you can do it this way; once you select Start from the Debug menu, however, the Run menu options will be greyed out and you must use the Debug menu to select Go.
The red and green buttons on the toolbar are the Stop and Go buttons. Clicking on these buttons is equivalent to selecting Stop or Go from the Debug menu. Once you have selected Go, the script executes until it ends; reaches any breakpoints or watchpoints that have been set (see the sections on Breakpoints, below); encounters an error that suspends operation of the script; or receives a Stop command. You can pause execution of the script by hitting the red Stop button on the toolbar, or by selecting Stop from the Debug menu.
To watch the script as it runs, set the Trace Go option from the Debug menu. When you select Go button, with the Trace Go option checked the script will run as before, but you can watch the code scroll through the debugger window, with a red marker pointing to the line currently being executed. The script will stop at any breakpoints. You can stop execution of the script by hitting the red Stop button on the toolbar, or by selecting Stop from the Debug menu.
Some parts of the script you will want to look at in greater detail than others. For example, an error message may have told you that the problem occurs in line 352. In this case, you'll want to run the script up to the point where the error occurred, and then stop it so that you can go through the lines step by step, watching what happens.
To go to a specific line in a script, select Step to Cursor from the Debug menu. The script will then run up until the point where the cursor is set, and then stop and wait for you to give it instructions on how to proceed. If the line that you select is never reached, the script will run to completion. To use the Step to Cursor command you must have the Trace Go option on the Debug menu checked, and the line the cursor is on must contain a statement - a line with just a semi-colon is OK, but a line with just a closing brace is not.
To step through a script line by line, use the Step Into option from the Debug menu. The debugger will execute the line that the cursor is on and move to the next line. Selecting Step Into again will execute that line, and so on. By going line by line like this you have a chance to stop and make sure that everything is working correctly before going through the next step. To see the values of the variables in the script, enter the variable into the Watch window or use the local or global watch windows(this is described in detail in a later section).
When the debugger comes to a line with a function call and you tell it to Step Into (via any of the three methods), it will jump to the first line of the function and continue stepping through the function. The variables listed in the watch window may change values if they aren't global variables and aren't passed to the function - remember, variables only have meaning within the functions in which they are created or passed to. (Global variables are always available to the functions in a script).
Note that the debugger will NOT step into functions that are a part of the ScriptEase libraries, (i.e., the functions that are not written in the script or included with .hmm files). These functions (such as GetArraySpan() and strftime()) have already been extensively tested by Nombas and are free of errors. Stepping into internal functions is the same as stepping over them.
If you are debugging a script and come to a line with a function call for a function that you don't want to step through, you can bypass it with the Step Over option from the Debug menu. The debugger will execute the function automatically and put the cursor on the next line following the function call, waiting for your instructions.
The remaining command for navigating through scripts is the Step Out option. The script will run automatically until the current function is finished, stopping on the next line after the function call. This is useful when you may have accidentally stepped into a function and simply want to return to where you started from.
You can watch variables change values as the script runs by listing them in a watch window. These windows let you keep track of the values of the variables used in your script, and watch them change while your script runs. The watch windows are controlled from the Window menu.
There are three watch windows: a global window, (lists all of a script's global variables and their values); a local window, (lists the variables and values available to whatever function the debugger is currently working in); and a general watch window, (keeps track of a user-specified list of variables). The watch windows are opened from the Window menu. Select Local to see a list of the local variables currently in use by your script, Global for a list of global variables, and Watch to open the user-specified watch window.
To register a variable in the user-specified watch window, either click on the `W' icon on the button bar, or open the Watch ->Add/Remove option from the Debug menu. Enter the variable name in the variable name window, and the way you want it displayed in the `View Expression As' window. The format used in the `View Expression As' window is the same as that for the sprintf statement, (e.g. %s for a string, %d for a decimal number, etc.). When you have entered in the variable name and the `View Expression As' format click on the `Add' button to add the watch to the variable list. When you close the `Add/Remove' Watch window you will see the variable you just entered listed in the Watch window. As the debugger steps through the script, you will be able to see the values for that variable as it changes while the script runs.
The `W' icon with a red circle/slash on it will clear the watch window. You can also do this from the Debug menu, selecting `Kill All' selection from the menu on the `Watches' option.
Sometimes when you run a script through the debugger you will want the script to run until it reaches a certain point. You may be interested in a certain function, and want to let the script run without intervention until it hits the line before that function, so you can watch the debugger step through the function in question. If you're not quite sure which part of a script is causing a problem, you can set multiple breakpoints in the hope that you might guess one of the places the script might reach while executing.
To do this, put your cursor on the line where you want the script to stop and click on the large B button on the toolbar. The line will be marked with a red octagon to indicate the line has a breakpoint. Alternately, the menu option Breakpoint on the Debug menu will open a window where you can set a breakpoint by line number.
Make sure the Trace Go option on the Debug menu is checked. Now start the script: select the Start option from the Debug menu, and then the Go option from the same menu. The script will run without intervention until it hits the line you marked. It will then wait for you to give it instructions for stepping through the script marking the line with the source mark.
You can have as many breakpoints as you want in a script, allowing you to skip over and stop numerous times.
The `B' button with superimposed red circle/slash will clear all of the breakpoints you have set, leaving your script breakpoint free.
If you only want to clear one breakpoint of several you may have set, put the cursor on the line containing the breakpoint and click on the `B' button on the toolbar. This will clear the breakpoint on that line. Alternately, you can open the breakpoints window (the Breakpoint option of the Debug Menu. The bottom portion of the window contains a box listing the breakpoints you have set. Select the one you wish to remove and click on Remove.
Sometimes you want to set a breakpoint when a variable reaches a certain value. For example, if you had a big loop, and wanted to look at what happened on the 200th iteration of the loop. Instead of having to step through the first 199 iterations, you can set a breakpoint for when the loop-counting variable reaches a certain value. The script will run automatically until the breakpoint is met, and then the debugger will take over and let you step through the script.
Setting variable-dependent breakpoints is done in the same window as setting watches. For example, suppose the loop mentioned above is initialized with a for statement:
We want the debugger to stop when x is equal to 199. In the expressions window (where we put the variable we wanted to watch) we'd instead put an expression, x==200, and in the breakpoint section to the right we click on `Is True'. Click on the `Add' button and close the window, and start the script Start and then Go from the Debug menu). The script will run as before, stopping when the value of x reaches 200.
Similarly, you can set the variable to break when the expression evaluates as false by checking the `Is False' button in the `Add/Remove' Watch window. Or you can put a variable name in the window and check `Changes' to break every time the value of a variable changes.
You can go in and change a variable's value while the debugger is at work by using the Variable option from the Debug menu. A window will open where you can enter the name of the variable you want to change, followed by an equals sign, and the value you want to change the variable to. When the script resumes execution, the variable will have been adjusted according to what you entered.
In order to edit and save text in the debugger, it must be in text editor mode (the script will have a white background) and not in debug mode (the script will have a grey background). To exit debugging mode without closing the debugger, select Abort from the Debug menu to abort the debugging and return the debugger to text editor mode. The background color of the script will change from gray to white. You can now make changes to your script and save them.