Working with the debugger Foundation

The debugger's purpose is to help the programmer find and resolve program errors. This section discusses the capabilities offered by the debugger and offers advice on how to locate errors. Program errors leading to program termination must be differentiated from those that cannot be identified by the runtime system. Errors that cause program termination are relatively easy to locate, since the default error handling routine displays information about the type and location of the error on the screen. The most important information for locating a runtime error is the name of the routine and the source code line number in the PRG file where the error occurred. If the reason for the error is not obvious, a breakpoint can be set on this line in the debugger and the conditions leading to the runtime error examined with the debugger.

The debugger is started by entering XPPDBG <EXE file> on the command line. It loads the executable file <EXE file> and stops the Xbase++ application on the first executable program line. An implicit breakpoint is set on this line. If a runtime error occurs, the debugger identifies the name of the routine where the error occurred along with the line number in the PRG file. To set a breakpoint at this line, the option "Open Module" is selected in the file menu. This displays a selection window containing the names of all the PRG files. After the highlight is positioned on the name of the file where the routine causing the error is found, clicking the right mouse button on the highlighted file (or the key combination Ctrl+Return) will open a second window listing all the routines contained in the PRG file. The routine that generated the error can be selected from this list. Double clicking with the left mouse button or pressing the Return key opens the corresponding PRG file and positions the code window to the selected routine.

Within the code window the highlight should be positioned on the program line where the error occurred. A breakpoint is set by double clicking the left mouse button on the highlighted line or by pressing F9 or the Return key.

A debug session generally starts by setting breakpoints. Any number of breakpoints can be set. The option "Save Restart Info" can be selected in the options menu to save the breakpoints from one execution of the application to the next. The line numbers of the breakpoints are then saved in a file with the same file name as the application and the extension ".@@@".

After breakpoints are set, the application is run by pressing the F5 key. The colored area in the menu bar of the debugger changes from green to red. This indicates that the application, and not the debugger, has input focus. The debugger interrupts the application and regains control as soon as a breakpoint is reached. The colored highlight then changes from red back to green.

As soon as the debugger has interrupted the application at a breakpoint, the current status of the application can be more closely examined. The monitor window is opened from the monitor menu to display the contents of all visible variables. Variables are organized based on their storage class (LOCAL, STATIC, PRIVATE and PUBLIC). If a variable has an incorrect value, it can be changed using the debugger. To do this, the monitor window is selected by clicking the left mouse button or using the Tab key. Within the monitor window the highlight must be positioned on the corresponding variable. An edit window is then opened by clicking the left mouse button or pressing Return. The value of the variable can be edited in this window. The edit window is closed by selecting OK.

Variables with the data type character, numeric, date or logical can be displayed in an entry field where they can be edited. The display uses Xbase++ syntax. When changing a value, pay careful attention to the syntax. For example, delimiters must be present for a character string when a value of the character data type is edited. If the variable is a code block, the characters {|| and } must be included. The characters entered are compiled using the macro operator and the result is assigned to the variable.

If the variable to be edited is an array, the contents of the array elements can be viewed using the View pushbutton. The maximum number of elements displayed is 64. Elements in an array beyond this 64 element limit can be examined by entering the numeric index for the first array element to display in the entry field "Start".

The edit window displays only the essential information about an object, such as the name of the class to which the object belongs. The contents of the instance variables of an object are displayed by pressing the View pushbutton. Only the instance variables declared in the class are displayed. If the class is derived from other classes, the class names of the superclasses are also displayed. Selecting a superclass displays an edit window containing the instance variables for this class.

Only the instance variables of objects can be examined in the edit window of the debugger. In many cases the return value of a method needs to be checked. For example, the question might be "What is the class name of the parent of this Xbase Part?" The parent can only be determined using the method:setParent(): it does not appear in the list of instance variables. Problems such as this are solved using the command window of the debugger. To view the command window the option "Open Command Window" is selected to open the command window. Below this window the command line of the debugger is displayed and any expressions can be entered. After pressing the Return key the expression is executed and the result of the expression is displayed in the command window.

The parent of a particular Xbase Part can be determined on the command line of the debugger in two ways. If the variable oXbp contains an Xbase Part whose parent information is needed, either of the following two expressions can be used on the command line of the debugger to determine the parent class:

oXbp:setParent():className() 

dummy := oXbp:setParent() 

The first expression displays the class name of the parent in the command window. The second expression creates a PRIVATE variable referencing the parent. Selecting the option "Private" for the monitor window displays variables of the PRIVATE storage class. The parent of oXbp is displayed as the variable "dummy". This variable can be examined with the debugger in the manner described earlier.