TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Navigation

Navigation in the debugger takes place in many ways. When the debugger has halted program execution, the debugger automatically displays the location in the source code at which execution has halted. At this point, you can visit an entity or another file, display the program call stack and move to any frame on the call stack.

The following are covered in this chapter:

For all navigation commands, it is important to understand the visibility rules used by the debugger as well as what is meant by the terms home position, current frame, and current position.


Visibility Rules

The debugger visibility rules determine which identifiers are visible at a given point in the program execution. The current frame establishes the current visibility rules using the following model:

For Ada:

If the current frame is an Ada subprogram, package or task, Ada visibility rules are used. However, since debugging is not the same as programming, these rules are extended in two ways.

First, if a name is not found based on the normal Ada visibility rules, a search is made of the Ada library for a library unit with that name. Therefore, all library units are visible regardless of what units are with'ed by the current context.

Second, a program-wide search is made for subprograms when a simple name is given as the argument to the b, v, edit and vb commands. That is, it looks at all the subprograms, tasks, and packages (with elaboration subprograms) in the entire program, for one whose simple name matches the name typed in for the command. The results of this search are merged with the results of searching using Ada visibility rules (including library search extension).

For C/C++:

C++ supports four kinds of name scopes: local, function, file and class. The debugger resolves local and function scope names the same as the C++ compiler based on the current debugging context. The debugger also provides access to function or class names that are not directly visible in the current debugging context. This capability allows users to call functions, set breakpoints, change context to functions or classes that are not directly visible.

File scope, or global function names may be referenced even when they are not visible from the current file. This is useful for navigation and setting breakpoints in non local functions. Class member functions may be referenced without their class qualification just like other global function names but class member data must be referenced according to the C++ member name rules.

Additional information on C++ scope can be found in C++ Scope/Name/Operators.

Home Position

The home position is the execution point in the current stack frame, the next instruction to execute. The line containing the home position is marked with an arrow.

When program execution moves to a new execution point, the home position changes as well. For the topmost frame(s), (that is., topmost non-inline frame plus any inline frames above it), the home position is the instruction that executes next. For all other frames, it is the call instruction that called the next higher non-inline frame.

* is recognized as a valid line number meaning "the line containing the home position." In the command-line debugger or the Command Pane you can use an asterisk as a command to move the current position to the home position.

Current Position

The current position is represented by a three-part identifier consisting of file, line number, and instruction address. This identifier represents the present location in the source program. In the debugger GUI, this information is displayed in the log window.

The v or Visit command permits changing the current position into an arbitrary file. The v command, without any parameters, displays the current position (except the instruction address).

The debugger keeps track of the current position to make certain frequently-used commands more convenient. In particular, the breakpoint and list commands use the current position as a default parameter. This section explains how the current position is initialized, how it is changed and how to find out what it is.

When a breakpoint occurs or after a call stack command is executed, the current position is set to the home position of the current frame. For the top frame of the call stack, this corresponds to the breakpoint. For all other frames, the home position is the location of the call to the next higher frame. You can change the current position using the call stack commands, the Visit command, the line number command, the listing commands and the searching commands.

Current Frame

The current frame is the current position on the call stack. When a breakpoint is announced, the current frame is always set to the breakpointed subprogram, package, task (Ada), function or class (C/C++). This frame is the topmost frame of the call stack. In moving up and down the call stack (cd and cu commands), the current frame is the frame moved to most recently. The current frame is always the topmost frame of a cs command listing.

Each frame has a current instruction associated with it. For the topmost non-inline frame, this is the instruction that executes next. For all other non-inline frames it is the call instruction that called the next higher non-inline frame. For inline frames, the current instruction is the same as the current instruction of the next lower non-inline frame. This current instruction address, plus the source line and filename that generated it, constitute the home position for that frame. In showing disassembled instructions, the home position (marked with *) is displayed next to the current instruction for the current frame

Change the current frame only with the Call Stack commands, or by running the program to a new breakpoint.

The current frame plays a central role in establishing what program names are currently visible at any point during a debugging session.

When a breakpoint is reached or a call stack command is executed, the current position is always set equal to the home position of the current frame. Examining the program source or instructions changes the current position. Return to home position in the current frame by typing

This command moves the current position to the home position of the current frame.


Display Source Code

It is often desirable or necessary to display sections of your program different from that current displayed either on the debugger window, the editor window or through the non-GUI debugger.

In the Main debugger window, display the source by using the View > Show Source command to display the Source Pane in this window. Use the scroll bar at the side of the Source Pane to display other sections of your program. Do the same in the Editor window.

There are also a number of commands used in the non-GUI debugger and which can be entered in the Command Pane for displaying different sections of your source program.

These commands are listed in the table below and discussed in detail following the table.

l
Display source code
w
Display window of source code
li
Display instructions
wi
Display window

The li and wi commands are discussed in the chapter on machine-level debugging.

l

List part of a source program

Syntax
Arguments
Description

l lists a specified number of lines of the current source file starting at the specified line. The default value for number is 10 which can be changed with the set lines number command. The default line is the current line, which is marked with < to the left. In screen mode the current line is the line under the cursor.

The possible forms of line are:

number

Move to specified line

+number

Move number lines forward

-number

Move number lines backward

*

Move to home position

After the l command is executed, the current line is the last line displayed. Consequently, typing l without parameters continues listing where the last l command stopped.

If * appears after the line number, that line is the current home position for this file. If = appears after the line number, a breakpoint is set for that line.

If - appears after the line number, a breakpoint is set in the code generated for this line but not on the first instruction. If both = and - apply to the same line, only one is displayed.

If + appears after the line number, this represents an inline frame.

In Screen Mode

Precede this command with : and follow with Return.

w

List a group of source lines

Syntax
Arguments
Description

The term "window" means a section of source text. Do not confuse it with the windows of the debugger.

w lists a window of source text around the specified line in the current file. This listing occurs in the Command/Log Window. If line is not specified, the center of the window is the line portion of the current position. If the line specification is *, the line portion of the current home position is used as the center of the window. If line is given, the current position moves to that line and the window surrounding that line is displayed.

The window is the specified number of lines large. (Default: 10.) Change the default with the set lines number command.

In Screen Mode

Precede this command with : and follow with Return.


Visit

In the debugger GUI or editor windows, use the Visit command to move to another language entity, subprogram, or file. There are also a number of commands that can be entered from the Command Pane or the non-GUI debuggerdebugger log to visit program and debugger constructs.

v
Navigate to a declaration, subprogram or source file (like vi tags)
vb
Visit breakpoint
/ ?
Search
edit
Edit subprogram or file
select task
Move to a new task (Ada only)
select program
Move to a new program
return
Return from all called subprograms (Ada) or functions (C/C++)

Move to Line Number

Syntax

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