| Navigation: User's Guide and Tutorials > Advanced Topics > The Debugger >====== Debugger Options ====== |    |
Starting the Debugger
The debugger runs as a separate application, but you can start it either from the development environment, or directly from Windows. Starting from Windows, with the development environment unloaded, means more system resources are available for your application and the debugger. The debugger can also debug multiple programs at the same time.
Starting the debugger from the development environment
1.Choose Project 
Debug Project or press the 
button on the toolbar.
The environment checks the project information for options and settings and starts the debugger.
or…
2.Compile and link your application by pressing the 
button, then, with the compile results dialog still open, press the Debug button.
Starting the debugger from the environment sets the working directory to the debuggee program's directory. This ensures the debugger will use any applicable configuration (.INI) files and redirection (.RED) files.
Start the debugger from Windows
When you start the debugger from Windows, you should take steps to set the proper working directory'usually the directory that contains the debuggee. For example, create a Windows shortcut that sets the “Start in” directory.
1.With your preferred method (Start menu, Explorer, Program Manager, etc.) start Cladb.EXE.
2.Choose File File to Debug, then choose an .EXE file in the Windows file dialog.
When debugging, run only the debugger and the debuggee programs. By doing so, you won't lose data in other applications if a problem occurs during the debugging process.
Loading the Source Files
The source associated with the debuggee program is automatically loaded and is available for your examination. However, you may specify any additional source files you want the debugger to manage.
To specify additional source files
1.Choose Window Source.
This opens the Select Source dialog.
2.Highlight a source file then press the OK button.
Repeat for each source file you want to debug.
Setting Debugger Options
The debugger Setup menu provides two choices: Options and Install as System Debugger. Use Options to customize the debugger.
Options
Choose the Setup Options command to access the following options:
Redirection File
The debugger uses the redirection file to find project components. A redirection file is optional and follows the same conventions as the Project redirection file.
Clarion Run-time
Specifies the Clarion dynamic link library (DLL) linked into the .EXE being debugged.
Stop At Program Entrypoint
Tells the debugger to stop the debuggee program at its entrypoint upon initial program load. Initial program load (and start) occurs when you choose File File to Debug and select the .EXE file from the Windows file dialog.
Checking this option lets you survey the status of your program at the earliest possible point of execution without explicitly setting a breakpoint.
Stop At First Source Line
Tells the debugger to stop the debuggee program at its first line of executable code upon initial program load. Initial program load (and start) occurs when you choose File File to Debug and select the .EXE file from the Windows file dialog.
Give Debugger Focus When Debuggee Suspended
When the debuggee is suspended at a breakpoint, focus immediately returns to the debugger.
Open Procedure Window on Startup
Tells the debugger to open the Procedures In window on debugger startup. See Debugger Windows.
Stop on dynamic DLL load
Tells the debugger to suspend debuggee execution when a dynamic DLL load (demand load) is detected. This gives you the opportunity to examine the newly loaded code and set breakpoints before anything else happens.
Allow stepping into Kernel
Lets the debugger examine the Windows Kernel32.dll. This setting could cause system lock ups, so use with care.
Show unmangled procedure names
Check this box to display procedure names as they appear in source code. Clear the box to show the mangled names that allow procedure overloading.
Custom Font
Check this box to set a custom font to use during the debugging session. A Font Dialog window is provided. Press the ellipsis button at any time to modify the existing font. The default value is your System Font.
Install as System Debugger
Installs the debugger as the system debugger. In this configuration, the debugger is available whenever a program crashes. This is shown with the Debug button on the GPF dialog.
Debugger Windows
The debugger contains a collection of child windows that track information about the debuggee program. These windows are:
·The Procedures window
·The Globals window
·The Stack Trace window
·The Watch window
·The source window
·The disassembly window
·The memory window
After you start the debugger, take a moment to arrange the various windows in a format that is comfortable for you. Position the most important windows where you can quickly scan for the information you need. Iconize or close unneeded windows. Use the Window menu to open windows of special interest.
By default, the debugger initially opens three windows: the Procedures window, the Globals window, the Stack Trace window, and the source window.
The Procedures window
The Procedures window lists the procedures in the debuggee and their associated source modules. CLICK on a procedure name to display its associated source or assembler code.
Use the Procedures window to navigate through your source code.
The Globals window
The Globals window displays the current value of each global variable, as well as various Library States (Clarion runtime library functions such as ACCEPTED, EVENT(), FIELD(), etc.).
The Globals window contains expandable tree controls, so you can hide variables you don't want to see. Variables with a ( + ) button are expandable by clicking on them. Variables with a ( - ) button are contractible by clicking on them.
RIGHT-CLICK on a variable to change its value.
The Stack Trace window
The Stack Trace window shows the current register and local variable values. The variable name is on the left and its value in decimal format then in hexadecimal format is on the right. This information is for the current thread only.
The Stack Trace window contains expandable tree controls, so you can hide variables you don't want to see. Variables with a ( + ) button are expandable by clicking on them. Variables with a ( - ) button are contractible by clicking on them.
The Stack Trace window has a step locator: type a letter to search for variables beginning with that letter.
The Stack Trace window has the following special functionality:
RIGHT-CLICK on a variable to change its value.
RIGHT-CLICK on a variable to monitor its value.
RIGHT-CLICK on a call to locate its corresponding source line or assembler line. This is the option you use to quickly find a line of source that caused a GPF.
RIGHT-CLICK on a register to examine the memory pointed to by the register.
The Watch window
The Watch window lets you pick specific variables (local, global, or both) and “Library States” to monitor during the debugging process. That is, rather than searching through the Stack Trace window and the Globals window with each debugging cycle, you can add the variables to the Watch window and examine all the pertinent values in one place.
To place variables in the Watch window: in the Stack Trace window or the Globals window, RIGHT-CLICK on an item (variable or Library State), then choose Watch variable. This opens the Watch window and places the selected item in the window.
The Source window
Displays a source module. There may be multiple source windows open showing different source modules. The title bar shows the module name. The cursor is green. This cursor simply marks a line for your use. It may or may not mark the program's current position. Breakpoint lines are red. If the current line is also a breakpoint line, it is yellow.
Use the source window's task bar buttons to control the execution of the debuggee and to set and remove breakpoints. The taskbar buttons correspond to the options on the popup menu which can be accessed by right-clicking anywhere in the window. See Running the Program below for a description of each command.
RIGHT-CLICK anywhere in the window to access the popup menu.
The Disassembly window
Displays assembler code. There may be multiple disassembly windows open. The title bar shows the .EXE name. The cursor is green. This cursor simply marks a line for your use. It may or may not mark the program's current position. Breakpoint lines are red. If a line is both the cursor and a breakpoint line, it is yellow.
Blue text has a corresponding source statement associated with it. Moving the cursor to a line with blue text moves the cursor in the source window to the corresponding source line.
Use the disassembly window's task bar buttons to control the execution of the debuggee, and to set and remove breakpoints. The taskbar buttons correspond to the options on the popup menu which can be accessed by right-clicking anywhere in the window. See Running the Program below for a description of each command.
The disassembly window has two vertical scroll bars. The left bar scrolls 64K of code at a time, the right bar scrolls 1 display line at a time.
RIGHT-CLICK anywhere in the window to access the popup menu.
The Memory window
Displays memory allocated to the debuggee. The title bar shows the .EXE name. The memory window has two vertical scroll bars. The left bar scrolls 64K of memory at a time, the right bar scrolls 1 display line at a time.
Setting Breakpoints
Normally, when debugging an application, you identify a small part of the program that produces incorrect output, or crashes. The debugging process for this situation will probably require running just that part of the program, and stopping it at one or more points to check its status.
Breakpoints allow you to automatically halt execution at the line of code at which (or near which) you think the problem occurs. Your program runs up to the breakpoint, then halts and turns control back to the debugger. You can then check the contents of variables to identify the cause of the problem, and step through from that point on.
When you set a breakpoint, the line where the breakpoint occurs appears in red in the source and disassembly windows.
Breakpoints appear yellow when you first create them because both the red breakpoint color and the green cursor color are present.
To set a breakpoint
1.Navigate to the source or assembler code where you want the debugger to break.
CLICK on a procedure name in the Procedures window to jump to that procedure. Or RIGHT-CLICK in the source window to access the Find command to find a text string.
2.Highlight the line of code to break on.
3.Press the breakpoint (B) button.
The breakpoint button acts as a toggle. Pressing it a second time removes the breakpoint.
Running the Program
The taskbar buttons on the source windows and the disassembly windows control execution of your program. Similar taskbars appear on each source and disassembly window. It makes no difference which taskbar you use. Program execution always continues from the point at which it stopped.
Alternatively, you can use the popup menus available in each window. The taskbar commands are duplicated on the respective popup menus of the source and disassembly windows. RIGHT-CLICK anywhere in the window to access the popup menu.
Go (G)
Advances the program from its current position to the next breakpoint. If no breakpoints are encountered, the program keeps running.
Step Assembler (S)
Advances the program from its current position, one line of assembler code at a time.
Step Over Assembler (O)
Advances the program from its current position to the next assembler breakpoint, without executing any statements in between.
Step Source (T)
Advances the program from its current position, one line of source code at a time.
Step Over Source (E)
Advances the program from its current position to the next source breakpoint, without executing any statements in between.
Go Cursor (C)
Advances the program from its current position to the cursor. This has the effect of making the cursor a temporary, one-time-only breakpoint.
Locate Line/Offset ( L )
Advances the cursor (not the program) to the line number (or offset for assembler) you specify.
Find (F)
Advances the cursor (not the program) to the source string you specify (source window only).
Find Again (A)
Advances the cursor (not the program) to the source string specified for the previous Find command (source window only).
Editing Variables at Run Time
Examining Variable Values
The best way to examine variable values at run-time is to look for them in either the Globals window or the Stack Trace window. Global variables are shown in the Globals window and local variables are shown in the Stack Trace window in both decimal and hexadecimal format.
Both windows contain tree controls, so that you can expand only the variables you want to examine. Controls containing a ( + ) are expandable by clicking on them. Controls containing a ( - ) are contractible by clicking on them.
The Stack Trace window also shows machine register values and locates the memory area the register points to. RIGHT-CLICK the register, or highlight it and press enter, to examine the correct memory location in the memory window.
Changing Variable Values
RIGHT-CLICK on a variable, or highlight it and press enter, in either the Globals window or the Stack Trace window to change its value.