TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Debugging C/C++ Programs

The Apex debugger provides a variety of facilities for analyzing the behavior of programs developed using Apex. After you start the debugger, program execution is under your control. You can cause the program to execute; you can cause program execution to stop and wait for you to request further progress; you can examine source and object; and you can perform other debugging functions. For C/C++, Debugger keywords are case insensitive, as are the letters used in hex numbers. So PRINT == Print == print and OAC12 == Oac12. However, identifiers are case-sensitive, so Print Foo is not the same as Print foo. For Ada, input to the debugger is not case-sensitive; the name seat_cntl.lights is treated the same as SEAT_CNTL.LIGHTS or Seat_Cntl.Lights.

Prerequisites for this Module

Submodules in this Module

Average Time to Complete this Module

90 minutes.


Setting Up the Debugger Tutorial

The setup for the Debugger module takes about 10 minutes and creates the project1.ss/queens.wrk (Apex/Summit) or <vob_dir>/queens.rss (Apex/ClearCase) subdirectory, hereafter called the <debugger_sample_dir>.This view contains source code and an executable for the queens program that is used in the debugger module.

Note: You must execute the debugger setup in order to perform the debugger exercises.

For Apex/Summit:

To set up the debugger tutorial view, in an Apex xterm (created by the Tools > Shell command), enter:

For Apex/ClearCase:

    Note: You must be in the VOB directory when running this script.

To set up the debugger tutorial Rational subsystem, in an Apex xterm (created by the Tools > Shell command or click the Shell button on the Apex Panel Window), enter:

The setup is complete when a directory viewer containing <debugger_sample_dir> is visited and the Apex xterm displays the message "DEBUGGER TUTORIAL SETUP COMPLETED SUCCESSFULLY". Please do not try to continue until this window is displayed. The Jobs window is displayed several times as the queens.wrk view is being set up. If the directory-viewer window is not displayed, please see your system administrator and do not continue.

This might be a good time to take a break.


Running the Queens Program without the Debugger

You are first going to run the program without the debugger just to see what it does. You can start running a program by either issuing a File > Run command, or by double-clicking on the executable name in a viewer window. Either method displays the Run/Debug dialog box so you can enter the program's name and any required arguments.

You are going to run the queens program.

1. . Double-click on the main* object in the <debugger_sample_dir> viewer window. Note that the standard UNIX file types are also displayed (* is an executable) making it easier to identify executables.

2. . In the Run dialog box, select the Direct output to an xterm and Get input from an xterm options. Select OK to run the program.

3. . In the Input/Output window, enter a number between 4 and 12. The output of the queens program will be displayed in that window.

4. . Enter Control-C in the xterm window to kill this program.


Getting Started with the Debugger

Prerequisites

Topics in this Submodule

Time to Complete this Submodule

10 minutes.

Starting to Debug a Program

You are now going to run the queens program with the debugger.

1. . Double-click on the main* object in the <debugger_sample_dir> viewer window.

The Run/Debug dialog box is displayed.

2. . Select the Debug tab in the Run/Debug dialog box.

3. . Click on OK in the Run/Debug dialog box.

The Apex debugger can be configured to behave in one of two modes for the display of source code: either through one of the editors or through its own source pane in the Debugger Log window. You can configure the default source display method when the debugger starts up and you can toggle between modes during a debugging session by using the View > Show Source command. Directions for doing this can be found in Using the Apex Debugger.

Using an Apex editor to display source allows you to retain the full capabilities of the editor while you're debugging. For example, you can perform CMVC, compilation, or editing operations during a debugging session.This display mode is called editor mode. It is the default.

The debugger's source display is optimized for debugging. It doesn't provide facilities for editing, compilation, or source control, for example. It does provide extra features specifically designed for debugging. For example, it contains source indicators that show where breakpoints are set. This mode is called Show Source mode.

It will take a few moments for execution to get started. When the startup is complete, the following windows may be displayed depending on your default settings:

4. . In this tutorial, we will be using only the Debugger Log window (Show Source mode) so close the C/C++ Editor window by selecting the Close button on that window.

5. . In the Debugger Log window, if the source code is not displayed, select the View > Show Source command.

Automatic Debugger Log windows

The Debugger Log window

When the debugger is initially created, it automatically creates the Debugger Log window in which to record the status of the debugger. All interactions with the debugger are displayed in the Debugger Log window as a sequential log.

After you click on the OK or Apply button in the Run dialog box, the Debugger Log is raised and displays the current information on the job you are debugging:

The first message tells you the complete UNIX pathname of the executable.

As you do more in your debugging session, the number of messages displayed as you start debugging a program may increase.

The source code surrounding the current position is displayed in the Source Pane. The current execution position is indicated by an arrow to the left of the line numbers.

The Input/Output Window

The Input/Output window may also be raised when you start debugging the program. This is not an Apex window, but a standard Motif xterm in which the queens program executes.

Starting Execution

You are going to execute the main program.

1. . Iconify the Jobs window because it will not change as we run this program.

2. . Move the Input/Output window so that you can view both the Input/Output window and the Debugger Log window.

3. . In the Debugger Log window, select Execution > Continue to execute the program.

4. . In the main Input/Output window, enter a number between 4 and 12. The output of the queens program will be displayed in that window.

5. . In the Debugger Log window, select File > Kill. We want a new debugger session for the next phase.


Setting Breakpoints

Prerequisties

Topics in this Module

Time to Complete this Submodule

10 minutes.

Starting Execution

You are going to start executing the main program again so you can learn more about the debugger. This time you are going to use the File > Debug command. The File > Debug command is available in all windows.

1. . In the Debugger Log window, select File > Debug .

The Run dialog box is displayed.

    Note: 1) From the Debugger Log window, the Run dialog box defaults the Execute field to the previously run executable during this Apex session. The Debug option is also selected.

    Note: 2) The Run dialog box defaults depend on which window was used to issue the File > Debug command.

2. . Verify that the Execute field contains the executable <debugger_sample_dir>/main.

3. . Verify that the Context field contains <debugger_sample_dir>, your working view.

4. . Click on OK in the Run dialog box.

The Debugger Log window is raised to tell you that the main program is going to be run.

The Jobs window is raised.

A source window containing main.c is displayed in the Debugger Log.

5. . Iconify the Jobs window because it will not change as we run this program.

Setting a Breakpoint

Breakpoints define predetermined stopping places in the program. Whenever the conditions associated with a breakpoint are met, the program stops executing, allowing you to perform any debugger function including displaying or modifying objects.

To understand what this program is doing, you are going to set a breakpoint .

1. . Visit the file queens.c. (double-click on this file in the viewer window). The file will be displayed in an editor window.

2. . Page down this procedure using the scroll bars on the right or by pressing the page-down key on the keyboard until you see the is_safe statement.

3. . Position your cursor on the line:

4. . Issue a Debug > Break Here command.

The Debugger Log window displays a message indicating a breakpoint on line 12.

The Debug > Break Here command can be used in most situations. If you want to specify additional options, you can enter Control-Debug > Break Here in an editor window or click the Debug > Break... command in any debugger window.

5. . Bring up the Breakpoints window by selecting the Windows > Breakpoints command from the Debugger Log window.

The Breakpoints Window

The Breakpoints window displays all the currently defined breakpoints. The window has an active area that displays the active breakpoints and an inactive area that displays the inactive breakpoints.

A breakpoint is either active or inactive. When a breakpoint is active, it is installed in the program being debugged and will stop a task in which execution reaches the location where the breakpoint is placed (and any task, trip count, or breakpoint conditions are satisfied). When a breakpoint is inactive, it has no effect on the execution of the program.

A breakpoint is either permanent or temporary. Permanent breakpoints remain active as long as the program runs under the debugger or until they are explicitly removed. Temporary breakpoints are automatically deactivated after the first time they are encountered.

Each breakpoint in the Breakpoint window has the following format:

[breakpoint number] file:line number in executable_name

The Debug > Break Here command creates permanent, active breakpoints. You have created breakpoint 1, an active breakpoint listed in the Active area in the Breakpoints window.

Continuing Execution

Now that you have set your first breakpoint, you want the program to execute until it reaches this breakpoint location. Execution will stop before the statement at the breakpoint location is executed.

1. . In the Debugger Log window, select Execution > Continue.

The Debugger Log window displays a message indicating that the program has started running. While the program is executing, the menubar background is greyed out.

2. . In the main Input/Output window, enter a number between 4 and 12.

The program continues to execute until it reaches the breakpoint. When the breakpoint location is reached:

Deleting Breakpoints

Now that you are stopped at breakpoint 1, breakpoint 1 can be deleted.

1. . Select the breakpoint 1 line in the Breakpoints window.

The line is highlighted.

2. . Select Breakpoints > Remove.

The Breakpoints window updates to show no breakpoints.

The Debugger Log window displays a message indicating 1 breakpoint has been removed.

3. . In the Breakpoints window, select Close button because there are no breakpoints.

The Online Reference contains more information on breakpoints.


Stepping Through the Program

Prerequisites

Topics in this Submodule

Time to Complete this Submodule

15 minutes.

Stepping Through Execution

Stepping allows you to control when the execution of a function will be stopped. The Apex debugger considers a statement to be a C/C++ statement or declaration which has associated assembly code. Some declarations and statements are optimized away, and thus have no associated assembly code. The Apex statements have statement numbers as discussed in the "Setting Breakpoints" topic.

If editor mode is on, whenever the execution of a C/C++ function stops, the default is:

If source mode is on, whenever the execution of a C/C++ function stops, the default is:

There are three step commands for source (in order from least detailed to most detailed):
Step Command:
Use:
Step Over
Steps to the next statement in the same context. For example, steps over a subprogram call to the next statement.
Step Into
If the current statement is not a subprogram call, this command steps to the next statement in the same context. If the current statement is a subprogram call, steps to the first statement of the subprogram without stopping in any function that might be evaluated as parameters.
Step Statement
Steps to the next source statement regardless of where it is located. This includes subprograms.

Stepping Over Calls

Before you begin this topic, you should be:

You are going to step over the call to the is_safe function.

1. . In the debugger main window, select Execution > Step Over. (Note that you can also execute a step over using the Step Over button, or by entering o in the Source or Log Pane.)

The debugger:

Stepping Into Calls

You are now going to step into the set_queen function.

2. . In the Debugger Log window, select Execution > Step Into. (Note that you can also execute a step into using the Step Into hot button, or by entering i in the Source or Log Pane.)

The debugger begins executing the call to set_queen(row,col) and stops at the first statement in the set_queen function.

Stepping Statements

The Step Statement command stops at all C/C++ statements, regardless of their containing files. This means each function call will be stepped through statement by statement.

You are going to step through several statements of the set_queen function.

3. . In the Debugger Log window, select Execution > Step Statement 4 times until the current position (where the arrow is) is on line 16. (Note that you can also execute a step statement using the Step Statement hot button, or by entering a in the Source or Log Pane.)

Note that the stepping commands are available in the editor window (under the Debug menu) and in all the debugger windows (under the Execution menu).

In the next topic, you will examine the values of some of the objects in this function.


Displaying Objects

Prerequisites

Topics in this Submodule

Time to Complete this Submodule

10 minutes.

Displaying the Value of an Object

Before you begin this topic, you should be:

The Apex debugger allows displaying the current value of an object in the Debugger Log window. This is done using the Debug > Show command. This command operates differently depending if you are in an editor window or in any debugger window.

You are going to examine the value of the row and board_size objects in the set_queen function. All these steps are performed from the Debugger Log window:

1. . Move the cursor to the row variable.

Use the mouse to position the cursor on row and click the left mouse button.

2. . In the Debugger Log window, select Debug > Show or use the Show Button. Note that the value of an object can also be displayed by placing the cursor on the object and entering p.

The Debugger Log window displays the current value of the row object. It should be 0. Note that the location of the object in memory may also displayed if the Show Location option is active.

You are now going to examine the value of the board_size object using the Show Data dialog box:

3. . In the Debugger Log window, select Debug > Show....

The Show Data dialog box is displayed.

4. . Enter the object name board_size in the Expression field. To display the location of this object in memory, may sure the Show Location button in this dialog box is selected.

5. . Click on OK.

The Debugger Log window displays the current value of the board_size variable. This should be the value you entered in the main Input/Output window. Note that the object location in memory is also displayed.

Modifying the Value of an Object

The Debug > Modify Data... command modifies the value of an object.

You want to change the size of the board for your queens solution.

1. . Click on the Debug > Modify Data... command.

The Modify Data dialog box is displayed.

2. . In the Expression field, enter board_size.

3. . In the New Value field, enter 10.

4. . Click OK.

The Debugger Log window displays a message indicating the value of board_size has been modified.


Setting Debugger Options

Prerequisites

Topics in this Submodule

Time to Complete this Submodule

5 minutes.

Setting Debugger Options

The debugger allows you to customize your usage of the debugger. The View > Options command sets debugger options such as default values for certain dialog boxes. When you select the View > Options command from any debugger window, the Debugger Options dialog box is displayed allowing you to customize your debugger.

Assume that you want to set the following debugger options:

1. . In the Debugger Log window (or any open debugger window), select View > Options.

The Debugger Options > Source Display dialog box is displayed.

2. . Change the Tab Size to 4.

3. . Deelect the Show Break Spots entry.

4. . Click on Apply. You will notice the disappearance of breakspots in the Source Pane.

5. . Select the Object Display Tab.

6. . In the Object Display tab, deselect the Show Location option.

7. . Click on OK.

Now that you have the debugger customized, you want to save these options so you do not have to set them each time you start Apex. This type of information is saved in debugger files. The next topic discusses these files.

Saving the Debugger State

You can save the debugger state across runs of the same program. You can also do so for initializing debugger state on a per-user basis and on a per-program basis. The debugger state information is preserved across debugging sessions if the corresponding debugger option is selected:

Debugger State Files

A user state file is used to save your personal preferences, regardless of which executable you are running.

A program state file is used to save state options that should be set by default for a particular executable:

A user-program state file is used to save each user's individual debugging defaults for that executable if there is more that one user debugging the executable.

A session-state file is used to save the debugger state for the last session of the program.

You are now going to save your current debugger defaults.

1. . In the Debugger Log window, select File > Debugger State > Save.

The Save Debugger State dialog box is displayed.

2. . Select the User State option and make sure all the debugger options settings/variables are selected.

3. . Click on OK.

The Debugger Log window displays a message indicating the information that has been saved.

The Online Reference provides additional information on debugger state files.

You are finished with the C++ Debugger module. Please kill the executable and close all open windows.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS