Prima Publishing, Rockland, CA.

Rod Paddock, Ron Talmage, John Petersen

Introduction

This chapter is dedicated to perhaps the most forgotten—yet one of the most important—elements of application development: debugging. Often, an application development environment is evaluated only in terms of its design (form, menu, reports, and so on), data handling, and language facilities. A list of necessary components for any development environment must include robust debugging facilities. Code that is error-free or classes with a superior design usually are the results of many failed attempts. For debugging facilities to be truly effective, they must be robust enough to be integrated into the normal course of development, not just relegated to being an afterthought once the code has been written. Also, debugging tools must help you to quickly diagnose what is wrong so that a fix can be quickly implemented. This chapter covers techniques to integrate the Visual FoxPro debugging tools into your development efforts.

Visual FoxPro’s Debugging Tools—Up Close and Personal

While Version 3.0 of Visual FoxPro was object-oriented and vastly improved over earlier versions of FoxPro, its debugging tools remained basically unchanged. Despite all that version 3.0 had to offer, the lack of good debugging support was a chief complaint among the population of FoxPro developers. In version 3.0 developers had a simple debugging window that could echo back the values stored by variables and the results of native VFP functions. In addition, a trace window gave developers the ability to step through code one line at a time.

In developing Visual FoxPro 5.0, Microsoft listened to the FoxPro development community, and put together a serious set of debugging tools. Essentially, Visual FoxPro 5.0 includes the Visual C++ Debugger, which is recognized by developers as one of the best. You will find that the new debugger is really a collection of windows, each devoted to a specific debugging task. The new layout is devoted to the central concept of helping Visual FoxPro developers produce and debug applications as quickly as possible.

Configuring the Debugging Environment

Just as you configure the environment for your application, you also must configure the environment for debugging. As with other configuration options in Visual FoxPro, there are two methods for making required settings. The first is to make your settings once and have these settings available to future Visual FoxPro sessions. The second, less preferred method is to manually make the required settings each time Visual FoxPro is started. This chapter focuses on the first method.

The Options dialog box, which is accessed from the Tools menu, has a new Debug tab in version 5.0.

The Debug tab is divided into three sections. The first section allows you to specify the type of debug environment you want to use, and whether you want to display timer events.

Debugging Environment Options

Two Environment options are available: Debug Frame and FoxPro Frame. When Debug Frame is chosen, the Debugger appears in its own window, separate from the main Visual FoxPro window. Using this option adds the Debugger choice to the Tools menu. The biggest advantage to using Debug Frame is the fact that Windows treats the Debugger not only as a separate window, but as a separate application. With this setup, it’s easy to switch between the Debugger and your application by pressing Alt+Tab.

The alternative is to select FoxPro Frame. In this scenario, all debugging activities occur in the context of the main Visual FoxPro window. Instead of a Debugger choice, the Tools menu contains a menu choice for each of the debugging windows. When one of the windows is selected for use from the menu, that window and its toolbar appear within the confines of the main Visual FoxPro window. This setup resembles the debugging environment in earlier versions of FoxPro and Visual FoxPro.

Displaying Timer Events

While the Timer controls in Visual FoxPro are very useful and powerful, they are somewhat incompatible with debugging processes such as stepping through code. Consider this scenario:

A Timer control in your application has an Interval property of 2000 (2 seconds). The sole purpose of the timer is to check to see if a specific text file exists. If the text file does exist, certain operations will be performed. At the same time, you’re engaged in a debugging effort regarding some method code in one of your application’s forms. Unfortunately, every two seconds, you are immediately whisked away from the code you’re stepping through to the timer’s method code. If that text file is found, the interruption from your primary process of debugging code may be longer.

You want the best of both worlds in this case; that is, you want to do the following:

• Have all the timer events fire
• Prevent your debugging processes from interruption by timer events

As long as you have the Display Timer Events check box deselected, you can step through code without having the Trace window display timer code when the timer events fire.

Additional Debug Options

The remaining portion of the Debug Page in the Options dialog box is devoted to configuring characteristics of each debugging window. As you select each window in the option group, the contents in the lower half of the page change. Common to all windows is the ability to change the font and the foreground/background coloring of normal and selected text. The Call Stack, Output, and Trace windows have additional options that can be set using this dialog box. The following sections provide a brief overview of the options available for each debugging window. Detailed description is reserved for the "Debugging Windows" section later in this chapter.

Call Stack Window Options

• Show call stack order—By selecting this option, you elect to see a number next to each program name.
• Show current line indicator—By selecting this option, you elect to have a small yellow arrow indicate which program line is currently executing.
• Show call stack arrow—By selecting this option, you elect to have a small black arrow indicate which program is currently displayed in the Trace window. With this option turned on, it’s easy to differentiate between code that is currently executing and code that is currently being viewed in the Trace window.

• Log Debug Output—By selecting this option, you specify that whatever is echoed to the Output window should also be placed in a text file with an LOG extension.
• Append—Selecting this option preserves the content of an existing log file by appending new information to the end of the log file.
• Overwrite—Selecting this option causes the log file to be replaced with new information from the current debugging session.

• Show line numbers—Selecting this option allows the associated line number to be viewed at the left side of the Trace window.
• Trace between breakpoints—Selecting this option allows only the code between two points to be executed at the throttle speed.
• Pause between line execution—This is the throttle setting, which specifies the delay (in seconds) that Visual FoxPro waits before executing the next line of code.

Now that the environmental housekeeping details have been addressed, it’s time to dive into the details of how the Visual FoxPro debugging tools work. The remainder of this chapter focuses on the debugging windows and the various debugging tools that are available to help you in your development efforts. As is the case with any aspect of Visual FoxPro, there are several ways to accomplish any given task. Typically, you can accomplish each task either by using a menu or by issuing code. Rather than treating the code elements separately, they are included along with the discussion of their respective window or tool.

Debugging Windows

The heart of Visual FoxPro’s debugging capability lies within its collection of windows. The following list summarizes the purpose of each window:

• Watch—This window allows you to display the results of expressions, and to place breakpoints when expressions change value.
• Trace—The primary purpose of this window is to allow code execution one line at a time.
• Call Stack—This window displays a complete list of all currently running programs and methods.
• Locals—This window displays a list of all visible variables. It also acts as an object inspector, as visible properties of an object can be queried for their current values (and, if necessary, those values can be changed).
• Output—This window displays output as specified by the Debugout command as well as a listing of fired events if event tracking is enabled.

Activating the Debugger

There are several methods of activating the Debugger:

• Choose the Debugger option from the Tools menu.
• Enter the following code in the command window:

  Activate Window Debug

• Upon an assertion failure, click the Debug button in the Assertion Failure dialog box.
• Encounter a defined breakpoint that subsequently activates the Trace window.
• Issue the following command:

  Set Step On

Controlling the Appearance of the Debugger

You can configure the appearance of the Debugger to suit your needs, by controlling which windows are visible. The various debugging windows contained in the main Debugger window are actually toolbars; therefore, they can either float or be docked.

The Watch Window

The Watch window most closely resembles the Debug window that was included in previous versions of Visual FoxPro and FoxPro. Therefore, if you are experienced with debugging in previous versions, you basically know how to use the Watch window. The Watch window is just what the name says—it allows you to watch elements of your current Visual FoxPro session.

The Watch window has two basic purposes:

• Querying and changing the results of a Visual FoxPro expression
• Setting breakpoints to halt program execution

The above heading probably begs the question: What is a Visual FoxPro expression? Well, just about anything in Visual FoxPro is an expression. The following definition appears in the Visual FoxPro help file:

Expression: Any combination of variables, operators, constants, functions, and names of fields, controls, and properties that evaluates to a single value.

Table 3-1 Examples of Visual FoxPro Expressions
Type	Representation	Possible Value
Function	Date()	{01/01/96}
Variable	lcName	"Karl"
Property	Form1.Caption	"Customer Data Entry"
Object	txtState	Object Reference of Properties and Methods
Field	custnumber	500
Complex	lnPurch > 10000	.F.

In reality, this list could go on forever, as there are endless combinations of expressions in Visual FoxPro. Simply put, expressions lie at the heart of any Visual FoxPro application. Many bugs in applications result either from the absence of a variable where one was expected, or from data type mismatches. In any case, an expression—or lack thereof—is involved. During the course of testing and debugging, you often might peer inside the workings of the application to see the values of certain expressions.

To create a watch expression, all you need to do is enter the expression in the text box that appears at the very top of the Watch window. Once the expression has been entered, press the Enter key and the expression is added to the list below. Alternatively, right-click the Watch window to activate a context-sensitive menu, then choose the Insert Watch option. As another alternative, add watch expressions by dragging them directly from the editor or command window and dropping them inside the Watch window.

The first three variables in the Watch window are character, logical, and date type, respectively. These data types have always been supported by the Visual FoxPro Debug window. What deserves special attention is the fourth entry—this is the VFP application object, new to version 5.0. In addition to the capabilities already discussed, the Watch window is an object browser. When you add object variables to the Watch window, you can literally “drill down” to view all the exposed properties of a given object.

Changing the Contents of an Expression

An additional feature of the Watch window is the ability to change the value of a variable. For example, assume a variable named lnTotal evaluates to 100.00, and you want to change it to 1000.00. While the value could be changed directly in the command window, it should be noted that the command window usually is unavailable while an application is active. Rather, the value of lnTotal can be changed in the Watch window with the following steps:

1. Make sure that a watch expression has been created for lnTotal.
2. Highlight the row in the Watch window that corresponds to lnTotal.
3. Click the contents under the Value column.
4. Type a new value. For characters, the expression must be enclosed in quotation marks (" "). For dates, the expression must be enclosed in curly braces ({ }).
5. After you type the new value, press Enter or leave the current row.

Creating Breakpoints

A breakpoint is nothing more than a defined position in a program at which program execution is halted and control is returned to you, the developer. Breakpoints also can be defined at specified times; specifically, you can halt program execution when the value of a certain variable changes.

In order to create a breakpoint in the Watch window, double-click the gray bar at the left side of the window next to the variable you want to select. When the breakpoint is established, a small red dot appears. To remove the breakpoint, just double-click again so that the dot disappears.

TIP: When at all possible, rely on using breakpoints to suspend code execution rather than placing direct Suspend or Set Step On commands in your code. By using breakpoints, you eliminate the need to search through your code to remove Suspend commands and Set Step On calls prior to delivering your application.

For continuation of Chapter 3 and for information on ordering this book, please visit the Visual FoxPro 5 Enterprise Development page. Click the Sample Chapter jump in the left pane to read the second half of this chapter.