Debugger

The Manifold Debugger provides an integrated debugger for use with scripting in Manifold System. The debugger is included within Manifold Enterprise Edition and is an option for Professional Edition. Users who do not have Enterprise Edition or the Debugger option for Professional will not be able to use Debugger features. The Debugger also requires installation of Microsoft facilities that support debugging of ActiveX scripts (see below).

The debugger works together with the Call Stack , Variables and Watches panes and is controlled by the Tools toolbar configured with debugger commands when a script is open. The Edit - Breakpoints command is used to set breakpoints for use with the debugger.

Scripts associated with Active Columns can also run in the debugger. To debug an Active Column script, right click on an Active Column cell and choose Run under Debugger from the pop up menu. Doing this runs the function, which will generate values for the active column in the context of the clicked cell. All regular runs of Active Column functions are done without the debugger.

If the Debugger is installed, when a script has the focus the tools toolbar will have debugger commands enabled. The debugger helps us develop and debug scripts in the scripting language of our choice. Commands will be enabled in the debugger toolbar as make sense given the execution state of the script.

	Run	Run a script.
	Run under Debugger	Run a script under control of the debugger.
	Pause	Pause execution of a script.
	Stop	Stop execution of a script.
	Step Over	Step over a routine.
	Step Into	Step into a routine.
	Step Out	Step out of a routine.

What is a Debugger?

A debugger is a specialized execution environment within which programs (like Manifold scripts) may be run in a controlled way that helps debug those programs. When a script is running under the control of a debugger it may be started and stopped, paused, re-started at a different location in the code, automatically stopped whenever it reaches a marked breakpoint and so on. At any time when a progam is paused or stopped we can see what are the values of any variables or other information we would like to know.

To understand what a debugger does, let's take a moment to consider the old-fashioned way of writing and debugging programs. Traditionally, we can write a program that consists of one or more functions. If it works the first time without any flaws we're somewhat surprised but happy. More frequently a new program of any complexity will not work quite right the first time or it will exhibit unexpected behavior (a "bug") when it functions. To track down any problems we have to know what is going on inside the program as it executes.

The traditional way of finding out what a program is doing while it is executing is to insert additional lines of code for debugging purposes. For example, if we are not sure that the program reaches a particular function correctly we might insert a few lines of code that when that function is reached will print out some text like "Got to AddNextRecord() OK" or which might print out the values of variables that we suspect are being mishandled with printed output like "Executing LoopRecord with RecordNum = 36".

As any professional programmer knows, it's really tedious to lard up one's code with lots of extra debugging statements. Adding extra statements is slow and there is always the risk of forgetting some debugging statements within production code or of inadvertently changing the execution of a program by the debugging code.

A much faster way to debug code is to use a debugger like the Manifold debugger. The Manifold debugger takes advantage of features built into Microsoft's Active X scripting environment to provide sophisticated, professional-class debugging capability.

To stop the execution of a program at any given location, insert a breakpoint at that spot using the Edit - Breakpoints command. Whenever program flow reaches a breakpoint the program will pause at that point. We can then see the contents of any variables using the Variables pane. If we like, we can even change the content of any variable by changing it's value in the the Variables pane.

The tools toolbar allows us to control program flow within the script. Using the Call Stack pane we can even jump to different parts of the script. The Watches pane allows us to see variables, process parameters and even computed expressions. All together the ensemble of debugger tools toolbar commands and the Call Stack, Variables and Watches panes allow us to control and examine the execution of a script with much greater convenience and flexibility than is possible using traditional methods.

Debugger Tutorial

The following sequence of steps shows operation of the debugger together with Call Stack, Variables and Watches panes.

Launch Manifold, open a new project and create two scripts. The first script, called A, is as follows:

The second script, called B, is:

Using Edit - Breakpoints place breakpoints in the scripts as shown above.
Try running script A or B from the project pane. Verify that both scripts display a "Hello!" message.
Turn on the Call Stack, Variables and Watches panes and dock them so that all three panes are visible.
Open script A and run it under the debugger using the toolbar button in the Tools toolbar or the Script - Run under debugger menu command.
The script will stop at the breakpoint in the fourth line of script A. The Call Stack pane shows that we’re within "Main" at line 4. The Variables pane shows "components" and "anotherScript" variables. The Watches pane is empty.
In the Variables pane, expand the components entry. The Count item shows that component set consists of two components (script A and script B). The other two items variables are internal to Manifold and may be replaced in future editions with a more sensible list of components. Expand the anotherScript item. The Name item shows the name of the script component. Other items show the script language, script text and various other properties. Press in the Show Common Properties button in the the pane toolbar. This shows the Application and Parent properties that are common to all Manifold objects. Note that we can expand components and then expand its Application property, then expand the Application’s ActiveDocument property and so on. Press out the Show Type button within the pane toolbar. This will hide the Type column so there will be more room for the Name and Value columns.
In the Watches pane, click the New Watch button and enter "components". This will display the contents of the components variable in a manner similar to the Variables pane. Click the New Watch button once more and enter "components.Count + 1". This will display "3". Double-click the empty line below the list of watches (an alternative way to create a new watch) and enter "Application". This will display the built-in Application object. Click on the first watch to highlight it and click the Delete Watch button within the toolbar. This will delete the selected watch. Note that the Delete Watch button won’t work on a subitem. For example, it won’t work on the Application.ActiveDocument item within the Application watch. The Show Common Properties and Show Type buttons operate do the analogous buttons in the Variables pane toolbar.
Click the Step Into button within the Tools toolbar or choose the equivalent command in the Script menu. This will step into script B.

The yellow execution arrow shows where execution has stopped. Click the Run Under Debugger button to continue execution. The script will stop on a breakpoint within the SayHello sub in script B.

Let's take a look at the Call Stack pane. The first line reads "SayHello" while both the second and third line read "Main". Press in the Show Module button to show the module (script) name for each call. Press in the Show Line Position button to show the position of a call within a line (useful when you have more than one call on the same line). Click the Show Language button to show the language of each script module. Click on the last call, for module A function Main line 4, to highlight it and click the Go To button in the Call Stack pane toolbar. This will activate script A and mark the location of this call in the script window with a green arrow:

It will also mark the respective item in the Call Stack pane with a green arrow as well:

The Variables pane will display "components" and "anotherScript" declared within the scope of this call. The "components.Count+1" entry in the Watches pane will read "3". Double-click the second line within the Call Stack pane, reading module B, function Main, line 7. Double-clicking a line in the Call Stack pane is an alternative way to Go To a call. This will activate script B.

Note that line 7 that contains the current call is marked with a green arrow and line 3 containing the current execution line is still displayed with a yellow arrow overlaid on the breakpoint dot. The Variables pane will display no entries since the Main routine in script B declares no local variables. The components.Count + 1 entry within the Watches pane will read "Variable is undefined: components" since "components" is inaccessible within the scope of the Main routine in script B.

Double-click the first line within the Call Stack pane, for module B, function SayHello and line 3. The Variables pane will display the name str and value "Hello!" as well as the type String if the Type column is on. The Watches pane will still refuse to evaluate the value of the components.Count+1 expression, since it inacessible with the scope of the SayHello routine.

In the Watches pane add a watch for the str variable. This will display "Hello!". Now, double-click the value box of the "str" variable (that is, click on the cell with "Hello!" in it) either within the Variables pane or within the Watches pane. Change "Hello!" to just "Hi!" and press Enter. Both Variables and Watches will now display the value of str as "Hi!". Click the Run Under Debugger button in the Tools toolbar to continue execution. Note that greeting in the message box has also changed to "Hi!". Click OK to dismiss the message and finish the script.
Note that all watches will turn to "Unavailable". We can still add or remove watches but we can not (obviously) edit their content. The Call Stack and Variables panes will disable their lists.

Installation Requirements

The Manifold Debugger is designed to work with Microsoft ActiveX scripting languages as used within Manifold System and to take advantage of the debugging capabilities Microsoft has built into the ActiveX ensemble of technologies.

To run the Debugger, you must therefore have the Microsoft Process Debug Manager (PDM) DLL installed on your system. This DLL gets installed with various Microsoft products aimed at scripting development. If you don't have the PDM or don't know if you have it, you must install the PDM on your machine. Unfortunately, due to what appears to be an inadvertent error in Microsoft licensing, although the PDM is freely usable and obtainable from Microsoft it is not included in the "redistributables" list covering all other Microsoft ActiveX components issued to developers like manifold.net for redistribution to end users. manifold.net therefore cannot provide the PDM as part of the Debugger installation on CD.

The easiest way to assure you have the PDM correctly installed on your system is to download any of the free Microsoft items that install it. The recommended choice is to install the Microsoft Script Debugger from the following URL (making sure to enter the entire URL as a single line in your browser):

http://msdn.microsoft.com/downloads/default.asp?URL=/downloads/sample.asp?url=/msdn-files/027/001/731/msdncompositedoc.xml

The above URL was correct at the time of this writing. If it is no longer active, visit the Manifold support page for a current URL, or search for "Microsoft Script Debugger" using Google or some other search engine to find Microsoft's new download page.

You must have Administrator privileges in Windows 2003, XP, 2000 and NT when installing the script debugger.

Note: The Microsoft Script Debugger is a small, simple, command-line debugger that also uses the PDM. It is more primitive than the Manifold Debugger, but it does install the PDM DLL required by the Manifold Debugger. Users new to working with debuggers may also find the documentation links available from the URL above to be a helpful introduction to debugging concepts used in the Microsoft scripting world by the Manifold Debugger and all other standard ActiveX scripting tools.

See Also

Panes used with the debugger include:

Call Stack

Variables
Watches

Back to Manifold Home Page