UsersGuide:Chapter 12:The Debugger
From Real Software Documentation
The Debugger
When you start a debug build, Real Studio attempts to compile the application. If it finds no syntax errors, it launches the application in a new window and a Debugger panel called “Run” appears in the Real Studio IDE. It enables you to halt execution of your application and execute your code line-by-line while watching and modifying the values of your variables.
There are three Project menu commands that initiate a debugging session: Run, Run Remotely, and Run Paused.
- Run: Run compiles the application and, if the compiler finds no errors, launches the built application in a new window on your machine. This is the normal way to use the debugger.
- Run Remotely: Run Remotely enables you to test your application on other platforms. Real Studio builds the debug application, but launches it on the remote computer of your choice. Run Remotely is available only in the Professional and Enterprise versions of Real Studio. For more information, see the section Remote Debugging.
- Run Paused: Run Paused builds the application and starts the debugger but it does not launch the executable automatically. If you have resources that you need to be in a specific location for the debug app to run, you need to use Run Paused instead of Run.
Run Paused allows you to debug the Real Studio project but have an external entity responsible for launching the executable. You can then copy whatever resources your application needs into “the right location” in the debug app directory and then manually launch the executable. It will then connect to the debugger and you can continue to debug as usual.
It can be used for debugging Real Studio plug-ins at the same time as debugging Real Studio code.
Run Paused gives you a debug run that is more similar to what your release build will behave like as files and resources are located in the same places they will be in the final build.
The other choice you have is conditional compilation with different paths for the database in the debug build and the production version.
Breaking into the Debugger
While it is running, you can stop the application and monitor execution in the Debugger panel. There are several ways that Real Studio halts the compilation process:
You Have Set A Breakpoint In Your Code
A breakpoint is a marker you can set at a line of code. It tells Real Studio to stop execution and display the Debugger when it reaches that line of code. It stops just before it executes it. In the Code Editor, the lines that accept breakpoints are indicated by a dash in the first column, to the left of area that accepts code. You can set a breakpoint in the Code Editor simply by clicking on the dash. You can also add a breakpoint using the contextual menu. Place the insertion point on the line to which you want to add a breakpoint, right+click (Command-click on Macintosh), and choose Turn Breakpoint On from the contextual menu. You can set as many breakpoints as you wish.
In this illustration, a breakpoint is set. A red dot appears to the left of the line of code to indicate that a breakpoint has been set.
To remove a breakpoint, click on the red dot or place the insertion point in the line and chose Turn Breakpoint Off from the contextual menu.
Breakpoints are persistent. This means they will stay in your code until you remove them. You remove a breakpoint by clicking on the red circle. You can also clear all breakpoints by choosing Project ↠ Clear All Breakpoints.
 |
NOTE: Breakpoints have no effect in stand-alone applications you build by clicking the Build button in the Toolbar or by choosing Project ↠ Build Application. |
You use the Break Keyword
Instead of setting a break point in the Code Editor, as shown above, you can place the Break keyword in your code. When the compiler reaches this line of code, it breaks into the debugger as if a breakpoint had been set. With the Break keyword, you can set the breakpoint conditionally. For example, you if you want to break into the debugger only when the value of a variable is equal to a certain value, you can put the Break keyword in an If statement that tests for that value. It’s convenient to use the one-line version of the If statement, for example:
breaks into the debugger when a local variable equals 103.
You Have Pressed a Keyboard Equivalent
If you are running your project and you need to interrupt the code that is executing, press Control-C on Macintosh or either Ctrl+Break or F5 on Windows or Linux to halt code execution and display the Debugger. This is handy if you find yourself in an endless loop.
You can also switch back to the Development environment by clicking the Stop button in the Debugger Toolbar. Command-Shift-Period does not work under Mac OS X.
The illustration in the previous section shows execution paused at a breakpoint.
The Debugger Screen
The Debugger screen is divided into two panes. The Code Editor pane shows the method that is currently executing and the Variables pane shows the variables local to the method displayed in the Code Editor pane.
The Stack drop-down list, just above the Code Editor, contains the name of the current method, along with the list of methods that eventually invoked the current method. They are listed in the order that they were called. You can check the Stack drop-down list to verify that methods are actually called when you expect them to be called. You can view the code for any method listed in the Stack drop-down list by clicking on it.
Changing the Highlight Color
The highlight color can be set in the Code Editor panel of the Options dialog box (Preferences on Macintosh). It is called “Debugger Highlight” and is listed in the Syntax Highlighting listbox. Highlight “Debugger Highlight” and then click on the color patch to the right of the list to modify it. A Color Picker will appear. When you select your color and close the Color Picker, the new color will be shown in the Syntax Highlighting options.
The Variables Pane
The Variables pane contains a list of all the variables local to the method shown in the Code Editor area, along with their current values (if any).
Any objects (rather than variables) that are defined in the method are shown as hyperlinks rather than values. In the above screen shot, you can click the Self link to see its properties in the Variables pane, shown here.
Viewing and Changing the Values of String Variables
An important feature of the Debugger is that a variabler’s value can be changed while the application is running. You can change the value of most types of variables in the debugger. Exceptions are variants, enums, multiline strings, and array types.
A variable whose value can be changed has a Write icon to the right of its current value.
A variable whose value can be changed via its Viewer has a combination magnifying class/write icon.
The magnifying glass indicates that it has a separate Viewer. Click it to display the Viewer for the variable. A variable whose value can be viewed in a Viewer but cannot be changed has a magnifying glass icon without the Write icon.
For example, in the illustration above, the DisplaySaveDialog boolean variable has a Write icon. Click on it to get pop-up that enables you to change its value to True. The FileName variable has the Viewer/Write icon. Click it to display its Viewer. It is shown below.
The Viewer for a string variable whose value can be changed has three tab panels, Text, Binary, and Edit. The Text panel displays the current text of the string. The second panel shows the text in Binary, and the last panel, Edit, enables you to edit the value.
In addition to the current value of the string, the Text pane also displays its encoding and length. The “View As” drop-down list enables you to change the encoding used in the display. Normally, a string will be stored with the UTF-8 encoding and would be readable to you. If the string somehow has a Nil encoding or the wrong encoding, you can tell the Debugger to use an encoding that is useful to you. This affects only the encoding used in the Viewer; it does not change the encoding of the variable itself.
The Binary panel displays the string in hex. It enables you to detect the presence of any non-printable characters that may be in the string. Ordinarily, Real Studio stores strings in UTF-8 but you may get non-printable characters in a string if it represents raw data from a binary stream. For example, if the string has a null byte in the last position, it is easy to see it in the hex representation.
The Edit panel displays the text of the string in editable format. You can also assign a text encoding to the string.
You can change its value by modifying or replacing the text in the Content field.
If a variable has the magnifying glass icon, then its Viewer lacks the Edit panel.
Object Viewers
If you click a link in the Variables pane, it changes to show the current properties of the object you clicked. The top object, Globals, links to a pane that shows the values of your global variables, if any.
If you Shift-click (Command-click on Macintosh) on a link, the requested Object Viewer opens in a separate window. Otherwise, the new Object Viewer replaces the current Object Viewer in the IDE window.
You can also right+click (Control-click on Macintosh) on a link to display a contextual menu that lets you choose between opening the new Object Viewer in the IDE or in a new window. The latter is equivalent to Shift-clicking (Command-clicking on Macintosh) on the hyperlink.
The illustration below, shows the Object Viewer for an application’s main window. You get this by clicking the TextWindow link.
As you execute code line by line in the Debugger, the Object Viewer updates values in real time. In this way, you can see whether a particular value (or lack of a value) is causing the problem.
In the previous illustration the top link, Contents, displays a list of objects in the window. In this case, there are several buttons, a Canvas, and a TextField. Click the Contents link to examine these objects and click an object to display its variables.
Click a control to display its variables and objects, if any. In the case of TextWindow, several controls are contained within the window. They are listed on the Contents pane. For example, clicking the first link, TextField, shows its properties. As you drill down the hierarchy of objects, the pop-up menu above the variables pane enables you to jump back up to an earlier level in the hierarchy.
This sequence is repeated down to the last level of objects. For example, if a window contains an ImageWell control, it is listed on the window’s Contents pane. If the ImageWell has a picture assigned to its Image property, the picture is shown on the Contents pane of the ImageWell’s Object Viewer.
If the variable that you are investigating is an array, the array’s Object Viewer displays each value in the array and its index. For example, the Variables Object Viewer below shows that there are three arrays. Right+clicking on the aAddresses array to display its Object Viewer shows the values of each of its elements.
Viewing the Values of Singles and Doubles
A Single or Double in the Variables pane can be displayed in one of three formats, Decimal, Scientific Notation, or Rounded. The default is Decimal. To change the format, right+click on the value or the Write icon to display a contextual menu and then choose the desired format. When you click outside the field holding the value, the format changes.
Viewing the Values of Integers
An Integer in the Variables pane can be displayed in one of four formats: Decimal, Hex, Binary, or Octal. The default is Decimal.
To change the format, right+click on the value or the Write icon to display a contextual menu and then choose the desired format. When you click outside the field holding the value, the format changes.
Viewing the Values of Pop-ups and ComboBoxes
A PopupMenu or ComboBox in the Variables pane will have a hyperlink to its Viewer. Click on the link to get the Viewer for the control and then click the Contents link at the top of the Viewer. It is a hyperlink to a viewer for the items in the PopupMenu or ComboBox. Both the text and the rowtag associated with the item are shown. This is illustrated below.
Viewing the Values in a Structure
A structure appears in the Variables pane as an expandable item. Click the plus sign or arrow to expose the fields in the structure.
The values of fields can be changed in the debugger. If the value can be changed directly in the Variables pane, it will have the Write icon to the right. Select the current value and replace it.
String fields will have their own viewer just like the viewers in the section “Viewing and Changing the Values of String Variables”. Unlike string variables, string fields in a structure are of a fixed length. If there are fewer characters in the value than the declared length, then the unused characters are null. This can be seen in the Binary pane in the string field’s viewer.
Displaying the items in a ListBox
A ListBox appears in the Contents viewer of a window. Click it to get the Object Viewer for the ListBox and then click its Contents link to see the items in the ListBox.
In the Contents pane, the drop-down list above the list of items gives you the choice of viewing the ListBox’s items or the tags associated with each cell. Choose Tag to change the view to the Tags.
Displaying the values of a RecordSet
A RecordSet appears in the Variables pane as an object. Click its link to get its Object Viewer and then click its Contents link to see the current values of the fields in the RecordSet.
Viewing Shared Properties
If you have a class with only shared properties (and possibly methods) and you don’t have any instances of that class created in your code but want to see the class shared properties in the debugger, put code such as this in a shared method:
You now have an instance that you can easily see the shared properties.
Displaying Multiple Threads in the Debugger
If your application has more than one running thread, the Debugger displays an extra drop-down menu above the Code Editor area that allows you to choose the thread you want to watch. The new drop-down menu appears to the right of the Stack drop-down menu.
Controlling Execution
Using the Debugger’s Toolbar, you can control execution. Instead of just allowing your code to run normally, you can control execution on a line-by-line basis. The Debugger’s Toolbar has five buttons that perform the functions of the Debug menu items:
When the Debugger is active the Project.Step submenu offers the Over, Into, and Out commands as well. In addition, the Run button in the Main Toolbar has changed to Resume.
- Resume: (Main toolbar) Continues execution from the breakpoint line without further interruption. This exits from the Debugger screen.
- Pause: Pauses execution without stopping and exiting to the IDE.
- Stop: Stops execution and returns to the Real Studio IDE. This also exits from the Debugger, but without executing any more code.
- Step: Executes the current line (indicated by the highlight) and moves on to the next line. If the current line includes one of your methods, the Debugger executes the method but will not step through the method’s code.
- Step In: Executes the current line and moves on to the next line. If the current line includes one of your methods, the Debugger displays the method and steps through the method’s code.
- Step Out: Executes the rest of the method without stopping on each line. This is handy when you have used Step In to step through a method that was called by another method and now wish to continue code execution without stopping on each line.
- Edit Code: Jumps to the Code Editor for the method that is currently executing.
Use this button to modify code or correct errors in the current method. It does not close the Debugger tab.
