TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Getting Started with the Debugger

This tutorial gives you a quick start in using the Apex debugger. It follows a hands-on approach in which you perform a series of exercises. When you are finished, you will be able to complete the basic debugger operations.

The following topics are covered in this chapter:


Prerequisites

To use this tutorial, you should have a general understanding of your:


Setting Up the Debugger Exercise

Before invoking the debugger, you must create a file to debug. To do this, complete the following steps:

1 . Start Apex by entering the apexinit command.

2 . Visit your home directory by typing a tilde (~) in the Visit field and select the Visit button.

3 . Create a subsystem named debug.ss using the File > New > New Subsystem command. Visit this subsystem.

4 . Create a working view named date.wrk using the File > New > New View command. Visit this view.

5 . For Ada, create the program to debug by selecting File > New > New Ada. In the New Ada dialog box, select Procedure Body and the name of date.

6 . Compile and link your program using the Compile > Link command. The executable is displayed in the debug.ss/date.wrk directory viewer as date*.

7 . Close the editor window using the File > Close command.


Starting to Debug a Program

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

1 . Select (highlight) the date* object in the directory viewer window.

2 . Select the File > Debug command.

The Run/Debug dialog box is displayed with the date executable program listed in the Program field.

3 . Click on OK in the Debug dialog box.

It will take a few moments for execution to get started. When the startup is complete, the following windows are displayed:

4 . Close the Editor window by selecting the Close button (or the File > Close command) on that window.

In this tutorial we will be using only the Debugger Window in Show Source mode.

5 . In the Debugger Window, select the View > Show Source command.

This causes the Source Pane to be displayed.


Starting Execution

You are going to execute the date program. This program prints out a message which is dependent on the time of day.

1 . If necessary, move the Input/Output window so that you can view both the Input/Output window and the Debugger window.

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

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

When execution finishes, the Debugger window Log area and status pane are updated. In the Input/Output window, the appropriate message appears. This is the output of the date program.


Setting Breakpoints

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.

Position your cursor on the line:

Ada:

C/C++:

1 . Issue a Debug > Break Here command.

The debugger displays a message indicating a breakpoint on the selected line and a red stop sign appears to the left of the line. Note that the line number may be slightly different depending on how many blank lines you used when you entered the program.

This 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.

2 . Bring up the Breakpoints window by selecting the Windows > Breakpoints command from the Debugger 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 main debugger window, select Execution > Continue.

A message is displayed indicating that the program has started running. While the program is executing, the menubar background is greyed out.

When the breakpoint location is reached, execution stops and the following changes are visible in the Debugger window:


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 window displays a message indicating the breakpoint has been removed.

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


Stepping Through the Program

Stepping allows you to control when the execution of a function will be stopped. The Apex debugger considers a statement to be an Ada or C++ statement or declaration which has associated assembly code. Some declarations and statements are optimized away, and thus have no associated assembly code. Stepping is described in detail in Executing and Stepping a Program.

In this section, you will use several types of stepping available with the Rational debugger.

Step Over
Steps to the next source line for which the compiler generates code, stepping over function calls
Step Into
Steps into the top-level function without stopping in functions called to evaluate parameters
Step Statement
Steps one line of source code, stepping into called functions, regardless of their containing files.

1 . In the debugger main window, select Execution > Step Over.

The debugger:

2 . To step into the cout function, select Execution > Step Into.

For C/C++, the debugger begins executing the call to cout and stops in iostream.h.

3 . To single step, select Execution > Step Statement.

For C/C++The date.C file is displayed with the current position now on either the else statement or the return statement, depending on the time of day.


Displaying Objects

The Apex debugger allows displaying the current value of an object in the Debugger window. This is done using the Debug > Show command.

You are going to examine the value of the Current_Time (Ada) or char_time (C/C++) object using the Show Data dialog box.

1 . Highlight Current_Time (Ada) or char_time(11) (C/C++).

2 . Select Debug > Show... to display the Show Data dialog box.

3 . In the Show Data dialog box, make sure the Show Location button is selected so that the memory location is also displayed.

4 . Click on OK. The current value of the Current_Time (Ada) or char_time(11) (C/C++) object is displayed in the Object Display window.

You are now going to examine the value of the Current_Time (Ada) or char_time(11) (C/C++) object using the simple Debug > Show command.

1 . Move the cursor to the Current_Time (Ada) or char_time(11) (C/C++) object and highlight the entire object.

2 . In the Debugger window, select Debug > Show or use the Show Hot Button.

The Debugger window displays the current value of the Current_Time (Ada) or char_time(11) (C/C++) object.


Modifying the Value of an Object

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

You want to change the value of piece.length.

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

The Modify Data dialog box is displayed.

2 . In the Expression field, enter Current_Time (Ada) or char_time(11) (C/C++).

3 . In the New Value field, enter a new value.

4 . In the filled in Modify Data dialog box, click OK.

The Debugger window displays a message indicating the value of Current_Time (Ada) or char_time(11) (C/C++) has been modified.


Assembly Mode

It is also possible to view disassembled text in the Source Pane. When Assembly Mode is active, breakpoint and stepping commands are interpreted at the instruction level.

1 . Select either the Disassembly hot button or the File > Disassembly command.

When disassembled text is displayed, the lines of source code are highlighted blue and the disassembly text is left in the normal color.

2 . Set a breakpoint at the current individual instruction in one of the following ways:

3 . To execute a Step Instruction command, in one of the following ways:

4 . Return to Source Mode by deselecting the Disassembly button or selecting the File > Disassembly command again.


Exiting the Debugger

To exit the debugger, select the File > Exit Debugger command.


Cleaning Up

Once you are finished with this tutorial, you may want to remove these files.

To delete everything you have created for this tutorial.

1 . From a directory viewer window, select File > Delete Object.

2 . In the Delete Object dialog box:

3 . Select OK. A Delete Subsystem confirmation box is displayed.

4 . Click on Yes to delete this entire subsystem.

All your files will be deleted and message will be displayed in the Messages window.


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