TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Controlling Execution

Once you start the debugger, program execution is under your control. You can let the program execute normally, or you can force program execution to stop at predetermined points or when predetermined conditions occur. When you have stopped a program, you can step through it and control its execution in many ways, depending on what kinds of debugging actions you want to perform.

You can control the execution of your program through commands that place breakpoints and continue execution. The breakpoints can have conditions and actions associated with them. You can step through your program at both the source and machine level, stepping either into or over subprograms (Ada) or functions (C/C++) at either level. You can also invoke subprograms (Ada) or functions (C/C++) in your program directly from the debugger.

These execution commands can be entered in several ways. If an external editor is being used, these commands can be accessed from the Debug menu. From the main Debugger window, they can be entered through the Execution menu or typed in through the Command Pane. If Show Source mode is active, a number of the Command-Line execution commands can be entered by simply positioning your cursor in the source window and entering a one letter command. Execution commands can also be entered in the Command Pane or through the non-GUI debugger.

The following sections are included in this chapter:


Executing and Stepping a Program

You can start executing your program either by continuing or stepping. When your program stops, by hitting a breakpoint, the debugger displays the current position. If you've selected the editor to display your source, the current position is selected (displayed in reverse video). In the debugger's source display pane, an arrow points to the current position.

The following are included in this section:

Execution Commands

When you start your program executing it always starts executing from the current position, even if you navigated to another location after it stopped. To start the program execution from the beginning use the Rerun command in the GUI, or the r command in the non-GUI debugger.

To stop the execution of a program being debugged, use the Debug > Stop (editor window), Execution > Stop (debugger windows) or stop (command-line) command. The program is stopped using a signal. To actually terminate a debugger session, use the File > Exit Debugger command from any debugger window, or the exit or quit commands in the non-GUI debugger.

The easiest way to start or stop the program executing is to use the hot buttons at the top of the debugger window. There are also a variety of other methods that are described below.

Table 10 Debugger Execution Commands
Operation
Command
Window
Rerun the program from its beginning
Debug > Rerun
Execution > Rerun


r
Editor
All debugger windows

Command Pane,
Source Pane,
Command-Line interface

Continue execution after the program has stopped for any reason.
Debug > Continue
Execution > Continue


g
Editor
All debugger windows

Command Pane,
Source Pane,
Command-Line interface

Continue all programs
Debug > Continue All
Execution > Continue All


g al
l
Editor
All debugger windows

Command Pane,
Command-Line interface

Continue execution and pass signal to program.
Debug > Step > Continue With Signal
Execution > Continue With Signal


gs
Editor
All debugger windows

Command Pane,
Command-Line interface

Repeat the previous step command.
Debug > Step > Repeat Step
Execution > Repeat Step


<Return>
Editor
All debugger windows

Command Pane,
Source Pane,
Command-Line interface

Execute until the current stack frame is completed and stops execution before the next statement.
Debug > Step > Run Returned
Execution > Run Returned


bd
Editor
All debugger windows

Command Pane,
Command-Line interface

Quickly go to any location currently displayed.
Debug > Step > Run To
Execution > Run To


b g d (sequence)
Editor
All debugger windows

Command Pane,
Source Pane,
Command-Line interface

Call subprogram
Debug > Call Subprogram
Execution > Call Subprogram


p
Editor
All debugger windows

Command Pane,
Command-Line interface

Stop program execution
Debug > Stop
Execution > Stop


stop
Editor
All debugger windows

Command Pane,
Command-Line interface

Exit the debugger
File > Exit Debugger

quit,exit
All debugger windows

Command Pane,
Command-Line interface

Return from called subprogram
Debug > Return from Call
Execution > Return from Call


return
Editor Window
All debugger windows

Command Pane,
Command-Line interface

Execute current program until value of named variable changes.
Debug > Watch Data

gw
All windows

Command Pane,
Command-Line interface

Change current PC to PC corresponding to specified line. or instruction
Debug > Jump To
Execution > Jump To


jump, jumpi
Editor Window
All debugger windows

Command Pane,
Command-Line interface

If you are using the debugger GUI, help information on each of these execution commands is available using the Help > On Context command or the Help button from any dialog box.

The command-line interfaces to the continue execution commands are detailed below.

g

Continue program execution

Syntax
Description

g continues executing all non-suspended programs from where they stopped. If a process is breakpointed because of a signal, g continues the process, ignoring the signal. Use the command gs to continue with the signal. Use the command gw to continue the program while watching for a variable value to change. The single-stepping commands execute the program but only for one source line or instruction.

Use g all to continue all programs not suspended by the suspend command.

If the program has not started execution, the g command runs the program, although no invocation processing (processing of I/O redirection, options and other parameters used by the program) is done. If the program exits or terminates, the g command reruns the program, using the invocation parameters used the last time the program was run. To rerun a program from the beginning at any time, use the r command.

If a program has been suspended by the suspend program command, it is not executed by the g command. The resume program command must be issued before the program can resume execution.

In Screen Mode

Type g in screen mode to continue the program; pressing Return is not required. With set safe on, the screen mode command becomes gg.

gs

Continue executing, pass signal to program (Native only)

Syntax
Arguments
Description

When a signal occurs in a program being debugged, the program is presented first to the debugger. The debugger announces the signal and the location at which it occurs and stops, waiting for commands. To continue execution of the program as though the signal has not occurred, use one of the regular stepping commands. To continue execution and pass the signal to the program, use the gs command. This is useful in debugging programs that do explicit signal handling.

For Ada, some signals are transferred into Ada exceptions by the Ada runtime system. If the program stops when it receives such a signal, type gs to raise the corresponding Ada exception. Note that the runtimes.dbrc file automatically does a gs for signals that are connected to exceptions so that this situation will only occur if the user disables the default gs actions.

Note that gs is sent to the current program only.

In Screen Mode

Precede this command with : and follow with Return.

gw

Continue execution until variable changes.

Syntax
Arguments
Description

For all systems except SGI, gw executes the current program until the value of the named variable changes. If an address is used, the specified number of bytes (number) at that address is polled for change.

For SGI, gw executes the current program until it reaches the instruction that is going to change the value of the named variable. The instruction is not executed. If an address used, the specified number of bytes (number) at that address is polled for change.

Note that gw is sent to the current program only.

For most systems, this breakpoint is useful but it can be slow since the polled value is checked after the each machine instruction executes. This is not true for SGI or System V/x86 systems.

gw does not detect memory that has been changed by a system call. For example, a program can use the read() system call to change the value at the memory address you are watching and you will not be notified.

In Screen Mode

Precede this command with : and follow with Return.

jump

Jump to line

Syntax
Arguments
Description

The jump command allows you to change the current PC to the PC corresponding to a line in the current file. It can be used to alter a program's normal flow of control. For example, you can use jump to force a program to execute the body of an if statement that the program would normally branch around. Similarly, you can use the jump command to re-execute a statement that you just stepped over, perhaps stepping into a called subprogram the second time around.

If line is not specified, the jump destination is the line part of the current position.

In Screen Mode

The current position is the line in the source window that contains the cursor. When the cursor is located in the source window, typing J is the same as a line mode jump command without any parameters. That is, the current PC is changed to the line containing the cursor.

In instruction submode, if you type J in the source window, it is interpreted as jumpi.


Warning: The jump command is inherently unsafe. The debugger makes no attempt to verify that the new PC location chosen will be result in successful subsequent execution. Use this command at your own risk.

jumpi

Jump to machine instruction

Syntax
Arguments
Description

The jumpi command allows you to change the current PC to the specified address. It can be used to alter a program's normal flow of control. For example, you can use jumpi to force a program to execute some machine instructions the program would normally branch around. Similarly, you can use the jumpi command to re-execute some instructions that you just stepped over, perhaps stepping into a called subprogram the second time around.

If instruction is not specified, the jumpi destination is the PC of the current position.

In Screen Mode

In instruction submode, if you type J in the source window, it is interpreted as jumpi.


Warning: The jumpi command is inherently unsafe. The debugger makes no attempt to verify that the new PC location chosen will be result in successful subsequent execution. Use this command at your own risk.

r

Run program.

Syntax
Arguments
Description

r runs or reruns all programs that are not suspended. r must be followed by a space, tab or newline. If it is followed immediately by a special character, the debugger assumes that r is the name of a variable and not the command. Note that all the characters after the r command (and the required space, tab or newline) are interpreted as a single entity.

The debugger resets all signals to their default before starting the process being debugged. The process has the same initial settings whether it is run under the debugger or from the shell.

If shell_arguments is specified, r runs the program as if it executes from the shell. The debugger supports a subset of shell command arguments. It supports the following arguments for I/O redirection: >, <, >> and >& (for redirecting both standard and error output). The debugger supports substitution for shell environment (exported) variables and ~name directory shorthand. Additionally, when argument strings contain dollar signs ($), backquotes (`), globbing meta symbols (*, ?, []); or in the case of 4.2 BSD UNIX, curly braces ({}) they are passed to the shell for evaluation. The debugger uses csh(1), sh(1), or the shell defined in the environment (exported) variable SHELL. Strings enclosed in double quotation marks are passed as a single argument after removing the quotes. Other parameters are passed (-o, -Pfoo) just like the shell.

This command starts or restarts the program from the beginning. To continue execution from a breakpoint or step, use g.

In Screen Mode

Typing r when in screen mode starts or restarts the program executing from the beginning. (Pressing Return is not required.) In `safe' mode, the command becomes rr.

To establish the invocation parameters in screen mode, first type a colon to get a line-prompt and then a full r command with invocation parameters, I/O redirection, etc. Alternatively, use set run shell_arguments after the colon. The debugger remembers I/O redirection and invocation parameters, so subsequent r commands without parameters re-use the parameters of the previous r command.

Typing set run without any parameters causes the r command to `forget' its I/O redirection and invocation parameters.

Return

Reexecute command.

Syntax
Description

Pressing the Return key repeats the most recent o, oi, i, ii, s, si, / ?, l, or li command. Debugging a program with r, gs, or g causes the Return key to lose its memory until one of the repeatable commands is used again.

In safe mode, this feature is disabled for the o, oi, s, and si commands.

In Screen Mode

Screen mode disables the use of Return to repeat the functions listed above. However, the dot (.) repeats the previous debugger command line.

exit

Terminate debugger session.

Syntax
Description

exit exits from the debugger. Also, use the quit command to exit the debugger.

If an exit is performed in the debugger before the program on the target completes, the program will be deleted.

In Screen Mode

Precede this command with : and follow with Return.

quit

Terminate debugger session.

Syntax
Description

quit exits the debugger. Also, use exit to exit the debugger.

If a quit is performed in the debugger before the program on the target completes, the program is deleted.

In Screen Mode

Precede this command with : and follow with Return.

stop

Stop program execution.

Syntax
Arguments
Description

Stop a running program(s) being debugged using a signal. If no arguments are specified, all running programs are stopped. If program_list is specified, only those running programs included in the list are stopped. Note that the program list must be preceded by the word program.

To terminate the debugger session, use exit or quit.

In Screen Mode

Precede this command with : and follow with Return.

Stepping Commands

Stepping commands allow users to walk through the code as it executes. This enables the programmer to read through the source code in execution order and limits the code to be read. Stepping commands are available to execute for a single line or instruction, stepping into or over called subprograms or functions.

Stepping allows you to control when the execution of a task will be stopped. For purposes of our discussion of stepping, a statement is a statement or declaration that has associated assembly code. Some declarations and statements are optimized away and thus have no associated assembly code.

If an exception occurs during a step command:

The normal completion of the step is determined as follows:

The following step commands are available (in order from least detailed to most detailed

Table 11 Debugger Stepping Commands
Operation
Command
Where
Step to the next statement in the same context.
Debug > Step > Step Over
Execution > Step Over


o
Editor
All debugger windows

Command Pane,
Source Pane,
Command-Line interface

If the current statement is not a procedure call, step to the next statement in the same context; if the current statement is a procedure/function call, step to the first statement of the procedure/function.
Debug > Step > Step Into
Execution > Step Into


i
Editor
All debugger windows

Command Pane,
Source Pane,
Command-Line interface

Step to the next source statement regardless of its containing unit. Each function call and each procedure call is stepped through statement by statement.
Debug > Step > Step Statement
Execution > Step Statement


s

Editor
All debugger windows

Command Pane,
Source Pane,
Command-Line interface

Step one machine instruction.
Debug > Step > Step Instruction
Execution > Step Instruction


si, ii
Editor
All debugger windows

Command Pane,
Command-Line interface

Step one machine instruction, stepping over called subprograms (Ada) or functions C/C++).
Debug > Step Over Instruction
Execution > Step Over Instruction


oi
Editor
All debugger windows

Command Pane,
Command-Line interface

Single step, pass signal to program
ss
Command Pane,
Command-line interface

Step over, pass signal to program
os
Command Pane
Command-Line interface

Step into, pass signal to program
is
Command Pane
Command-Line interface

If you are using the debugger GUI, help information on each of these stepping commands is available using the Help > On Context command or the Help button from any dialog box.

The command-line interfaces to the stepping commands are detailed below.

i

Single-step into program over function calls

Syntax
Description

The i command is used for stepping into procedure calls that have function calls as parameters. If the current statement is not a procedure call, i steps to the next statement in the same context. If the current statement is a procedure or function call, i steps to the first statement of the procedure. For example, using the i command (step into) on the following procedure call:

will step into f(), not g() or h().

For lines with multiple functions, the i command steps into the last function call of the line.

This command uses an implementation that uses a fairly simply heuristic to scan the instructions of a line looking for the last call. It steps over all calls but the last. This may give unexpected results in certain situations.

  • As always, stepping in optimized code may give unexpected behavior.
    In Screen Mode

    Precede this command with : and follow with Return.

    ii

    Single-step machine code into program

    Syntax
    Description

    ii single-steps the program one machine instruction and steps into a called subprogram (Ada) or function (C/C++). This is in contrast to the oi command, which single-steps one machine instruction but treats the machine call instruction as a single instruction, stepping over it. Other stepping instructions are gw (Ada only), s, si, ss, i, is, o, oi, and os.

    If the program has not executed, for example, right after invoking the debugger, ii starts the program, stepping one instruction. This relocates the current position from the main subprogram (Ada) or function (C/C++) to the actual starting subprogram (Ada) or function (C/C++) preceding the user program.

    In Screen Mode

    Precede this command with : and follow with Return.

    is

    Step into subprogram, pass signal to program (Native only)

    Syntax
    Description

    When a signal occurs in a program being debugged, it is passed first to the debugger. The debugger announces the signal and the location at which it occurs and stops, waiting for commands. To continue advancing as though the signal did not occur, use o or oi. To continue to step into the program over subprogram calls and pass the signal to the program, use the is command. This is useful in debugging programs that do explicit signal handling.

    For Ada, note that some signals are transposed into Ada exceptions by the Ada runtime system. If the program stops when it receives such a signal, type gs to continue execution.

    This command cancels the Return key memory.

    In Screen Mode

    Precede this command with : and follow with Return.

    o

    Step one source line over calls

    Syntax
    Description

    o single steps to the next source line for which the compiler generates code, stepping over subprogram (Ada) or function (C/C++) calls.

    Other stepping commands are gw (Ada only), s, si, ss, i, is, oi, and os. The s command steps one source line into called subprograms (Ada) or functions (C/C++). The i command steps into calls.

    If the program has not started or if it terminates, o starts the program, stepping one source line. This steps over all the library unit elaborations.

    Use two debugger parameters, alert_freq number and step_alert number, to track the number of instructions that are stepped. Using the default settings, a message is displayed after the first 1000 instructions are stepped (step_alert). After that, every 100 additional instructions stepped (alert_freq), generates a new message. These messages are periods - one after the initial number of instructions are stepped with a new period displayed for each 100 additional instructions stepped.

    In Screen Mode

    The o command is directly supported in screen mode: type o to single-step one source line over subprogram (Ada) or function (C/C++) calls. It is not necessary to press Return in screen mode.

    With safe mode set on, the screen mode command becomes oo.

    The number of instructions stepped appears as a number on the dashed line separating the command and source window. This number is first displayed after the first 1000 instructions are stepped (step_alert number). This number is incremented for every 100 instructions stepped after the initial display (alert_freq number).

    In instruction sub-mode, o is interpreted as oi.


    Warning: The o command does not advance over entry calls, only procedure calls.

    oi

    Single-step machine code over calls

    Syntax
    Description

    oi single-steps one machine instruction over call instructions.

    Other stepping commands are gw (Ada only), s, si, ss, i, is, ii, o, and os. The is and ii commands single-step one instruction into called subprogram (Ada) or function (C/C++).

    If the program has not executed or if it terminates, oi starts the program, stepping one instruction. This relocates the current position from the main subprogram (Ada) or function (C/C++) to the actual starting subprogram (Ada) or function (C/C++) preceding the user program.

    In Screen Mode

    Precede this command with : and follow with Return.

    In instruction sub-mode, o is the equivalent of oi.

    os

    Step over, pass signal to program(Native only)

    Syntax
    Description

    When a signal occurs in a program being debugged, it is passed first to the debugger. The debugger announces the signal and the location at which it occurs and stops, waiting for commands. To continue advancing as though the signal did not occur, use o or oi. To continue advancing and pass the signal to the program, use the os command. This is useful in debugging programs that do explicit signal handling. More information on signal handling can be found in Set/Ignore signals (Native only)

    For Ada, note that some signals are transposed into Ada exceptions by the Ada runtime system. If the program stops when it receives such a signal, type gs to continue execution.

    This command cancels the Return key memory.

    In Screen Mode

    Precede this command with : and follow with Return.

    s

    Single step source code into subprograms (Ada) or functions (C/C++)

    Syntax
    Description

    s single steps one line of source code, stepping into a called subprogram (Ada) or function (C/C++). If the debugger is currently on a source line containing subprogram (Ada) or function (C/C++) calls, s executes the program up to the point where it calls one of the subprograms (Ada) or functions (C/C++). The program then stops inside the called subprogram (Ada) or function (C/C++). The o command single-steps one line of source code but steps over subprogram (Ada) or function (C/C++) calls.

    In Ada, subprogram here means procedure, function, separate package body or instantiated generic package.

    If the program has not started —— for example, just after invoking the debugger —— the s command starts the program, stepping one source line. For Ada programs, this steps over all the library unit elaborations. Other stepping commands are gw (Ada only), si, ss, i, s, ii, o, oi, and os.

    A frequent debugging mistake is to use the s command to step into a subprogram (Ada) or function (C/C++) when the o command to step over the subprogram (Ada) or function (C/C++) is intended. The bd command sets a breakpoint at the place where the current subprogram (Ada) or function (C/C++) returns. To recover, use bd and then g. Usually, execution stops very close to where the o command stops. The breakpoint is deleted automatically so it is not encountered again. When stopped at the bd breakpoint at the middle of a source statement, use o to go to the beginning of the next statement.

    Use two debugger parameters, alert_freq number and step_alert number, to track the number of instructions that are stepped. Using the default settings, a message is displayed after the first 1000 instructions are stepped (step_alert). After that, every 100 additional instructions stepped (alert_freq), generates a new message. In line mode, these messages are periods - one after the initial number of instructions are stepped with a new period displayed for each 100 additional instructions stepped.

    Note: If you do a source level single step into an area of code for which there are no symbols, the debugger now does the equivalent of a bd followed by a g to try to get back to a point where source code exists.

    In Screen Mode

    Typing the s in screen mode single-steps the program one source line into called subprograms. Pressing Return is not required.

    In instruction sub-mode, s is interpreted as si.

    The number of instructions stepped appears as a number on the dashed line separating the command and source window. This number is first displayed after the first 1000 instructions are stepped (step_alert number). This number is incremented for every 100 instructions stepped after the initial display (alert_freq number).

    si

    Single-step machine code into program

    Syntax
    Description

    si single-steps the program one machine instruction and steps into a called subprogram (Ada) or function (C/C++). This is in contrast to the oi command, which single-steps one machine instruction but treats the machine call instruction as a single instruction, stepping over it. Other stepping instructions are gw (Ada only), s, ss, i, is, ii, o, oi, and os.

    If the program has not executed, for example, right after invoking the debugger, si starts the program, stepping one instruction. This relocates the current position from the main subprogram (Ada) or function (C/C++) to the actual starting subprogram (Ada) or function (C/C++) preceding the user program.

    In Screen Mode

    Precede this command with : and follow with Return.

    ss

    Single-step, pass signal to program (Native only)

    Syntax
    Description

    When a signal occurs in a program being debugged, first it is passed to the debugger. The debugger announces the signal and the location at which it occurs and stops, waiting for commands. To continue single-stepping as though the signal did not occur, use s or si. To continue single-stepping and pass the signal to the program, use the ss command. This is useful in debugging programs that do explicit signal handling.

    For Ada, note that some signals are transposed into Ada exceptions by the Ada runtime system. If the program stops when it receives such a signal, type gs to continue execution.

    Use two debugger parameters, alert_freq number and step_alert number, to track the number of instructions that are stepped. Using the default settings, a message is displayed after the first 1000 instructions are stepped (step_alert). After that, every 100 additional instructions stepped (alert_freq), generates a new message. In line mode, these messages are periods - one after the initial number of instructions are stepped with a new period displayed for each 100 additional instructions stepped.

    In Screen Mode

    Precede this command with : and follow with Return.

    The number of instructions stepped appears as a number on the dashed line separating the command and source window. This number is first `displayed after the first 1000 instructions are stepped (step_alert number). This number is incremented for every 100 instructions stepped after the initial display (alert_freq number).


    Breakpoints

    A breakpoint is a location (a point) in a program where the debugger is instructed to suspend (to break) the program execution. When execution commands are given, the debugger ensures that when execution reaches set breakpoints, the program `breaks' —— that is, the program stops executing.

    Object values, breakpoints, and exception handling can also be changed while the program is executing.

    You can set a breakpoint at an program unit (a package, task, or subprogram), a statement, or a declaration.

    Breakpoints have a state, a type, and a number.

    State
    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 breakpoint conditions are satisfied). Execution is stopped before the statement is executed. When a breakpoint is inactive, it has no effect on the execution of the program.

    In the debugger Source window, active breakpoints are indicated by a red stop sign. Inactive breakpoints are indicated by a green stop sign.

    Type
    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.
    Number
    Each breakpoint is numbered. When a breakpoint is encountered, the breakpoint number, location, and task name are displayed.

    For Ada, you can define a maximum of 64 breakpoints at a time. In addition to the 64 user breakpoints, a breakpoint is automatically set by Apex at a procedure in the Ada runtime system called Slight_Pause. This enables the debugger to recognize when a program is about to terminate because of an unhandled exception.

    You can set breakpoints in a generic instantiation. To do so, enter a subprogram in the instance (for example, v foo) and set the breakpoint(s). You can also set breakpoints in a generic instantiation if you are currently executing code inside the instance (e.g., you've stepped into the subprogram of an instance).

    If you position yourself in the source of a generic unit through some other method than described above, you cannot set breakpoints in the source of the generic unit. Attempting to do this causes an error message to be displayed: no instructions at this line. This happens, for example you position yourself in the source of the generic unit by using its source file name as the argument to the v command.

    The debugger deletes all breakpoints from a target upon exit.

    Conditional Breakpoints

    When a conditional breakpoint is reached, execution continues transparently if the condition is false. If the condition is true, the specified commands are performed.

    Possible forms for conditional breakpoints are:

    where the following terms are used:

    line|subprogram
    line number or subprogram name
    task
    task identifier
    expression
    the condition at the breakpoint (a non-zero value is defined as True)
    commands
    list of debugger commands to be executed

    Expressions are evaluated and (as with C expressions) 0 means False; other values mean True. All comparison operators (<,<=, =, etc.) return 0 for False and 1 for True.

    The debugger verifies that the conditional expression is valid when the breakpoint is set. The expression is verified using the Visibility Rules, etc., that exist when the breakpoint is hit and expression is actually evaluated.

    Specify a conditional breakpoint by using when expression after the breakpoint as shown in this example:

    This breaks the program at line 38 if col <= row.

    Alternatively, if expression then can be used. Any statements in the then clause are executed when the if expression is True. Any statements in the else clause are executed when the if expression is False. However, the debugger announces a breakpoint only when the if expression is True. For example,

    This sets a breakpoint at line 38. The debugger executes the then clause and announces a breakpoint when it reaches the breakpoint and col is less than row.

    In addition, you can set debugger commands to execute when the breakpoint is hit, but the condition is false. These commands take the form of an else clause, as shown here:

    In this example, the command p i between else and end if executes when the breakpoint at line 38 is reached but i > 5 is not true. This provides a tracking facility.

    The debugger supports line number breakpoints set for a specific task using the in clause. When the program reaches a breakpoint set with this clause, the debugger checks to see if the task executing is the one specified by the breakpoint. If not, the task is continued. If the executing task is the one specified by the breakpoint, the breakpoint is announced to the user.

    Breakpoint Commands

    Memory address in hexadecimal notation begins with a leading 0

    Table 12 shows the breakpoint commands available.

    Table 12 Breakpoint Commands
    Operation
    Command
    Window
    Create Breakpoint
    Breakpoints > New
    Breakpoints

    Debug > Break
    All debugger windows

    Debug > Break Here
    External editor

    b
    Source pane,
    Command Pane,
    Command-Line Interface


    bd, bi, br
    Command Pane,
    Command-Line Interface

    Delete Breakpoint(s)
    Breakpoints > Remove
    Breakpoints

    d
    Source Pane,
    Command Pane
    Command-Line Interface

    Activate Breakpoint(s)s
    Breakpoints > Activate
    Breakpoints

    Debug > Activate All Breaks
    External editor, all debugger windows

    b on, b on all
    Command Pane
    Command-Line Interface

    Deactivate Breakpoint(s)
    Breakpoints > Deactivate
    Breakpoints

    Debug > Deactivate All Breaks
    External editor, all debugger windows

    b off, b off all
    Command Pane
    Command-Line Interface

    List Breakpoints
    Windows > Breakpoints
    Debugger windows

    lb
    Command Pane
    Command-Line Interface

    Create Breakpoint

    There are a number of ways to create a breakpoint. You can open an editor window and choose the Debug > Break Here command, open the Breakpoints window and choose the Breakpoints > New command, or open any debugger window and choose the Debug > Break command.

    New breakpoints can also be set using the Command Pane or command-line interface debugger to type in the desired command. The command-line interface breakpoint commands are discussed in detail in Command-Line Interface - Create Breakpoint.

    If the Source pane is displayed, a simple breakpoint can be set by positioning your cursor on the line on which to set the breakpoint and entering b. A red stop sign appears to the left of the line number indicating an active breakpoint has been set at that line.

    Displaying the Set Breakpoint Dialog Box

    When you execute the Breakpoints > New command or the Debug > Break command in a Debugger window, the debugger displays the Set Breakpoint dialog box.

    When the editor window is open, the Debug > Break Here command does not ordinarily display a dialog box. However, you can force the display of the Set Breakpoint dialog box by Control-clicking the Debug > Break Here menu item. It will display the pathname of the selected source location in the Location field.

    Displaying the Breakpoints Window

    Display the Breakpoints window by opening the Debugger window and choosing Breakpoints from the Windows menu. You can also open the Breakpoints window by clicking the Breakpoints button on the Debugger window's button bar.

    Command-Line Interface - Create Breakpoint

    There are a number of breakpoint commands that can be used to create breakpoints using the debugger's command line interface. These are as follows:

    b

    Break at a line or beginning of a subprogram

    Syntax

    Ada:

    C/C++:

    Arguments
    Description

    This command sets a breakpoint. You can set breakpoints at a line in the current file, at the beginning of a subprogram (Ada), function (C/C++) or in a task (Ada). To set a breakpoint at a line in another file or subprogram (Ada) or function (C/C++), use the v (visit) command to locate the correct source file first.

    If subprogram (Ada), function (C/C++) or line is not specified, a breakpoint is set at the current position by using the line part of the current position three-part identifier (file, line number and instruction address). In line mode, the current position is marked with <.

    For Ada, you can set a breakpoint only in an instance of a generic. You cannot enter the source file of a generic, set a breakpoint and have that breakpoint exist in all instances of the generic.

    Each breakpoint set with b has a number. The number is displayed when the breakpoint is reached or when the lb command lists all breakpoints. Use the number to delete individual breakpoints with the d command.


    Warning: In a command block, commands occurring on the same line, but after one of the following commands are not executed.

    set, put, help, read, pass, put_line, run, / and ?

    For example, the end following the set signal 5 gs command is ignored.

    >b 133 begin set signal 5 gs; end

    Examples
    In Screen Mode

    The current position is the line in the source window that contains the cursor. When the cursor is located in the source window, typing b is the same as a line mode b command without any parameters. That is, a breakpoint is set on the line containing the cursor. The screen-mode b command is acknowledged immediately by the appearance of = to the left of the line on which the breakpoint is set.

    To set a breakpoint at the beginning of a subprogram while in screen mode, position the cursor on top of any letter of any occurrence of the name of a subprogram and press B. This has the same effect as typing b subprogram (Ada) or b function (C/C++) in line mode. An acknowledgment message is displayed at the bottom of the screen to indicate that the breakpoint has been set.

    If the subprogram (Ada) or function (C/C++) name is overloaded, the debugger prints a diagnostic showing the alternatives. Retype the B command preceding it with a number (matching an alternative shown in the diagnostic) to disambiguate it. That is, typing a number n before the B command has the same effect as typing b subprogram'n (Ada) or b function'n (C/C++) in line mode.

    To set a conditional breakpoint in screen mode, type : and enter the line-mode command.

    In instruction sub-mode, if you type b in the source window, it is interpreted as bi. However, when you enter commands preceded by a colon (:), b still means break-at-line. Type :bi to set an instruction breakpoint.

    bd

    Break after current subprogram

    Syntax

    Ada:

    C/C++:

    Arguments
  • expression

    An expression that is evaluated each time the breakpoint is reached. This evaluation takes place in the environment of the location of the breakpoint. If expression is False (0), the breakpoint is not announced and the program continues. If expression is True (non-zero), the breakpoint is announced.

  • task (Ada only)

    Task number of the task in which the breakpoint is announced. The task number is obtained using the lt command. The breakpoint is announced only for the specified task.

    Description

    bd sets a breakpoint in the subprogram (Ada) or function (C/C++) that called the current subprogram (Ada) or function (C/C++) (that is, one frame down from the current frame). The breakpoint is reached immediately when the current entity returns. The current subprogram (Ada) or function (C/C++) is the one represented by the current frame. Immediately means that the bd breakpoint is set in the first machine instruction following the current subprogram (Ada) or function (C/C++) return. This may not be on a source statement boundary. The breakpoint is removed automatically when it is reached. To get to the beginning of the next statement, use the o command.

    Usually, bd is used for stopping at the return of the current subprogram (Ada) or function (C/C++) after entering it by mistake with the s or si command.

    The simplest form of this command, bd, is used most often. For Ada, like the b and bi commands, you can specify the bd command for a particular task using the in task clause. A set of commands can be automatically executed at the breakpoint with a begin commands end block. Set a conditional bd breakpoint by using a when or if statement.

    In Screen Mode

    Precede this command with : and follow with Return.

    bi

    Break at machine instruction

    Syntax

    Ada:

    C/C++:

    Arguments
    Description

    bi sets a breakpoint at a specific machine instruction. Use li or wi to display instructions (disassembly) to indicate exactly where to set the instruction breakpoint.

    For Ada, set bi breakpoints for a particular task using the in task option.

    Execute a block of debugger commands automatically when the breakpoint is reached by appending a begin-end block. Set a conditional bi breakpoint with a when or if statement.

    Each breakpoint set with bi has a number. The number is displayed when the breakpoint is reached or when the lb command lists all breakpoints. Use the number to delete individual breakpoints with the d command.

    In Screen Mode

    Precede this command with : and follow with Return.

    In instruction sub-mode, if you type b in the source window, it is interpreted as bi. However, when you enter commands preceded by a colon (:), b still means break-at-line. Type :bi to set an instruction breakpoint.

    br

    Break return; set permanent breakpoint at return

    Syntax

    Ada:

    C/C++:

    Arguments
    Description

    The br command sets a permanent breakpoint (as opposed to the bd command) at the last-executed (return) instruction of the current subprogram. The breakpoint is not deleted after it is hit.

    On RISC machines which have delay slots, if the return instruction is followed by an instruction in the delay slot, the break is set in the delay slot if possible. If the CPU doesn't support setting breaks in delay slots, we back up one instruction and set the break there.

    br does not work for inlines. If you set a br in an inline, the break is set at the return from the procedure which contains the inline.

    When the code generator puts out more than one return instruction in a subprogram, setting one br puts a break at every return statement. If you already have another kind of break at one or more of the return instructions, br fails.

    In Screen Mode

    Breakpoints are not announced explicitly in screen mode. The debugger scrolls the source window if necessary to insure that the line containing the breakpoint is on the screen. Since the breakpoint is also the current home position, it is marked with a * as well as a = and the cursor is placed on the line.

    Ada:

    C/C++:

    bw

    Set a watchpoint

    Syntax
    Arguments
    Description

    bw sets a watchpoint in the user program. A watchpoint is a special breakpoint that is associated with a memory location. The breakpoint is hit when the memory location is accessed as described by the access argument to the bw command.

    Some targets provide a hardware or software interface to watchpoints. Targets with hardware support will run quickly when watchpoints are set in the program. Targets with software support will also run fairly quickly with watchpoints. Targets with no watchpoint support, however, will run very slowly. If this is the case, a warning message will be printed by the debugger. In addition, only the modify access (or write access) is available for targets without watchpoint support.


    Warning: The watchpoint mechanism takes advantage of hardware or software support when it is available on the target. If this support is not available, the debugger uses single stepping to watch objects. If single stepping is used, watchpoint execution will be slow. At the current time, watchpoints will be slow on all targets except SGI and PowerPC.

    Targets with watchpoint support only allow one watchpoint to be set per memory range.

    The types of access are:

    execute (cross only)
    The program stops and the watchpoint is announced when the instruction that is specified by the address argument is executed.
    read
    write read/write

    The debugger stops execution of the program and announces the watchpoint when the specified memory is read, written, or read or written, respectively.

    The announcement is made before or after the memory access, depending on the target support. The read and read/write accesses are only available on targets with either hardware or software support.

    modify
    The debugger stops execution and announces the watchpoint when the value of the specified memory is changed. This access is available on all targets, but is very slow on targets without hardware or software watchpoint support.

    Watchpoints are displayed and deleted with the normal breakpoint commands lb and d.

    In Screen Mode

    Precede this command with : and follow with Return.

    Activate Breakpoint(s)

    To activate an inactive breakpoint from the GUI:

    1 . Open the Breakpoints window.

    2 . Select the breakpoint you want to activate

    3 . Choose the Breakpoints > Activate command or click the up-arrow button in the Breakpoints window or select the Make Active button.

    To activate all breakpoints from the GUI:

    1 . Open any editor window or any debugger window.

    2 . Choose the Debug > Activate All command.

    You can also activate a breakpoint using the Command-Line interface by typing b on all|breakpoint_number(s) in the Command Pane. In Show Source mode, active breakpoints are indicated by a red stop sign to the left of the line number.

    b on

    Activate breakpoint(s)

    Syntax
    Arguments
    Description

    This command is used to activate a breakpoint which was previously set, then deactivated with b off. If this breakpoint conflicts with a breakpoint which was set since this breakpoint was deactivated, it will remain inactive.

    The b on and b off commands are convenient if you wish to flip between two or more sets of breakpoints, or if you have defined a complicated expression to be evaluated or list of commands to be executed at a breakpoint.

    Inactive breakpoints are marked with a # next to the line or source or disassembly. If there is more than one breakpoint on a given line, and you are displaying source, the mark for the active breaks, if any, (= or -) are displayed.

    Deactivate Breakpoint(s)

    To deactivate an active breakpoint from the GUI:

    1 . Open the Breakpoints window.

    2 . Select the breakpoint you want to deactivate.

    3 . Choose the Breakpoints > Deactivate command or click the down-arrow button in the Breakpoints window or select the Make Inactive button.

    To deactivate all breakpoints from the GUI:

    1 . Open any editor window or any debugger window.

    2 . Choose the Debug > Deactivate All command.

    You can also deactivate a breakpoint using the Command-Line interface by using the b off all| breakpoint_number(s) in the Command Pane. In Show Source mode, inactive breakpoints are indicated by a green stop sign to the left of the line number.

    b off

    Deactivate breakpoint(s)

    Syntax
    Arguments
    Description

    This command is used to deactivate a breakpoint which was previously set. Another breakpoint may be set at the same point while this breakpoint is inactive.

    The b on and b off commands are convenient if you wish to flip between two or more sets of breakpoints, or if you have defined a complicated expression to be evaluated or list of commands to be executed at a breakpoint.

    Delete Breakpoint(s)

    To remove a breakpoint:

    1 . Open the Breakpoints window.

    2 . Choose the breakpoint you want to remove. (The breakpoint can be active or inactive.)

    3 . Choose the Breakpoints > Remove command.

    You can also remove a breakpoint using the Command-Line interface by typing d in the Command Paneat the debugger log prompt. To remove all breakpoints, enter d all. To activate individual breakpoints, enter d breakpoint_number(s). If you are in Show Source mode, you can remove a breakpoint by positioning your cursor on the breakpoint and typing d.

    d

    Delete breakpoints

    Syntax
    Arguments
    Description

    d deletes the listed breakpoints. All breakpoints are deleted if all is used.

    Multiple breakpoint numbers comprising the breakpoint_number (obtained using lb and displayed in brackets) must be separated by commas in this command as illustrated here:

    Delete a breakpoint at any time.

    In scripts and command blocks, it is possible to delete a break at the current position without using the breakpoint number by simply using d alone. For example,

    In Screen Mode

    d deletes a breakpoint set on the line in the source window that contains the cursor. If a source line contains a breakpoint, = appears to the left of the line.

    Delete a breakpoint by moving the cursor to a line with = and typing d. Pressing Return is not necessary. The = disappears, showing that the breakpoint is gone.

    List Breakpoints

    To see a list of all breakpoints use the Windows > Breakpoints command or the lb command in the Command-Pane or the non-GUI debugger. If you use the Windows > Breakpoints command, the Breakpoints Window is displayed, as illustrated in Figure 3. This window has an area that displays the active breakpoints and an area that displays the inactive breakpoints.

    Figure 3 Breakpoints Window

    Each breakpoint has the following format:

    Ada:

    C/C++:

    In the Source pane, active breakpoints are indicated by a red stop sign to the left of the line number; inactive breakpoints are indicated by a green stop sign to the left of the line number

    To simply list all active breakpoints in the Log area of the main debugger window, or when using the non-GUI debugger, enter the lb command.

    lb

    List all currently set breakpoints

    Syntax
    Arguments
    Description

    lb with no arguments lists all currently set breakpoints in all programs. To the left of each breakpoint is a number in brackets. Delete the breakpoint with this number. For each breakpoint, the full name and sequence number of the task(s) associated with the breakpoint are also listed.

    If you have deactivated some breakpoints using the b off command, you will see the active breakpoints listed first, then the title "Inactive Breakpoints", followed by the list of breakpoints which are currently inactive.

    In Screen Mode

    Precede this command with : and follow with Return.

    Set/Ignore signals (Native only)

    Facilities to handle signals.

    Syntax
    Arguments
    Description

    The set switch enables you to instruct the debugger to treat signals in one of three ways: b, g and gs. These are described in the Arguments section above.

    The default setting for most signals is "b" (break).

    To display a list of signal names on UNIX-based systems, enter kill -l. For example, at the shell prompt:

    Inside the debugger, to display the current setting for each signal, enter signal [signal_list|all] [b|g|gs] [in task] without parameters:

    The debugger resets all signals to their default before starting the process being debugged. The process has the same initial settings whether it is run under the debugger or from the shell.

    You cannot change the behavior of two signals, ALRM and CONT.

    Exercise care in changing certain signal behaviors. For example, set signal INT g prevents interruption of the program by Intr (or Control-C).

    Classes (C/C++ only)

    For basic debugger operations on class member functions, such as setting breakpoints, a global search of the entire executable is performed, rather than a C/C++ file-scope search on the currently-visible compilation context. For instance, you can enter b foo::bar even if the definition for the class foo is not visible in the current context.

    Breakpoints

    A breakpoint on a member function can be set in a couple of ways. If the member function is indicated by:

  • a qualified or unqualified member function name
    Constructors

    Class constructors have the same name as their defining class. This creates an ambiguity when using the class name in debugger expressions. The resolution of the ambiguity by the debugger will depend on the context. When the class identifier is used in a navigation command or in a context where a class name is required the debugger will assume the class definition is desired. All other references to the class identifier will refer to the class constructor(s).

    Member Functions
    Virtual functions


    Handling Exceptions

    The Apex debugger lets you use exception handling to specify whether a program should stop when an exception is raised.

    When a program raises an exception, the debugger either catches it or propagates it. If there are no active exception handling commands, the debugger propagates all exceptions. You can instruct the debugger to either catch or propagate exceptions.

    When the debugger catches an exception, execution stops at the statement that raised the exception. The debugger ignores propagated exceptions and allows them to be handled as usual by the program being debugged. In this way, the debugger can ignore common exceptions that are not errors.

    At the lowest level, there is a location in the user level code which is executed every time an exception is raised. When the user specifies an exception command, the debugger places a breakpoint in this location. Then, any time an exception is raised, the program stops at this breakpoint and the debugger is notified. The debugger then checks whether the exception being raised has been defined to stop the program. If so, the exception is announced to the user and the user is given an opportunity to enter commands. During this process, the program is stopped. If not, the debugger restarts the program without notifying the user.

    Description - Ada

    Whenever you step your program, the debugger inserts an implicit catch breakpoint. Then if an exception gets raised while stepping the debugger announces it and you are positioned at the point where it was raised. For example:

    Whether you arrive at an exception via a catch breakpoint being hit or while stepping, if you type execute another step statement, the debugger will step your program to the handler for the exception.

    The debugger also sets an implicit breakpoint at a special location to catch exceptions which are propagated all the way out of a program or task. This happens if there is no user handler for the exception being raised.

    When an exception gets raised because of a compiler inserted constraint check failing, the debugger prints out extra information describing why the check failed.

    To maximize performance, the runtime does not save all of a program's registers while raising and propagating an exception. This limits the information available to the debugger after an exception is detected by the debugger. You can tell the runtime to same more complete information by entering:

    This allows the debugger to do a better job of printing out local variables and call stacks.

    Description - C/C++

    The debugger supports two commands, catch and propagate, for dealing with C/C++ exceptions:

    Where type_spec :== type_name | type_name * and function_or_line_number :== function_name | line_number the type_name must be visible from the current source file. The propagate command used in conjunction with other catch commands identifies scenarios where the user does not want the debugger to stop the program in response to an exception being thrown. A typical usage of these commands might be to catch all exceptions but propagate exceptions thrown in certain functions or propagate all exceptions that match a particular type profile.

    Examples

    Exception-Handling Commands

    Table 13 lists the exception-handling commands you can execute.

    Table 13 Exception-Handing Commands
    Operation
    Command
    Window
    Add Exception(s)
    Exceptions > New
    Exceptions
    Catch Exception(s)
    Debug > Catch
    Catch
    (hot button)

    All windows

    Debug > Catch Here
    Catch Here
    (hot button)

    All windows

    Debug > Catch All
    All windows

    catch
    Command Pane,
    Command-Line Interface

    Delete Exception
    Exceptions > Remove
    Exceptions
    List Exceptions
    Windows > Exceptions
    Debugger window

    Debug > Windows > Exceptions
    Editor Window

    le
    Command Pane,
    Command-Line Interface

    Propagate Exception(s)
    Debug > Propagate
    All windows

    Debug > Propagate Here
    Propagate Here
    (hot button)

    All windows

    Debug > Propagate All

    propagate all
    All windows

    Command Pane, Command-Line Interface


    propagate
    Command Pane,
    Command-Line Interface

    Raise Exception
    Raise Exception

    raise
    All windows

    Command Pane,
    Command-Line Interface

    Add Exception(s)

    When the Exception dialog box opens, you can add an exception to the debugger's list of requests. You can also specify whether the debugger should catch or propagate the specified exception when the exception is encountered. In addition, you can specify conditions under which this exception is to be caught or propagated.

    To add an exception-handling request to the debugger's list of requests, choose the Exceptions > New command from the Exceptions window, or choose the Debug > Catch or Debug > Propagate command from any debugger or editor window. Then follow these steps:

    1 . Position the cursor at the desired exception.

    2 . Click the Debug > Propagate or Debug > Catch button in the Exception dialog box.

    The debugger then places your new exception at the top of the debugger's request list.

    If a new exception request exactly matches an existing exception-handling request, the debugger removes the old request from its request list and adds the new request. Otherwise, the new exception-handling request is added to the top of the list.

    Each time the debugger encounters an exception, it examines the list of exception requests in order, from top down. If the raised exception does not match the first exception on the debugger's request list, the debugger moves to the next request. This process continues until the debugger finds a request that matches the raised exception.

    The first matching exception on the debugger's request list determine the action that is taken:

    Catch Exception(s)

    There are several ways to execute the catch exception-handling commands. You can:

    catch

    Break when a language exception occurs

    Syntax

    Ada:

    C/C++:

    Arguments
    Description

    catch sets a breakpoint that is reached when the named exception occurs. If the exception field is omitted, a breakpoint is announced when any exception occurs.

    For example:

    Like b, bd, and bi breakpoints, catch breakpoints can be set for a particular task, using the in task option (Ada only) and can be followed by a block of debugger commands to be executed when the breakpoint is reached.

    Each breakpoint set with b, bd, bi, or catch is given a number. The number is displayed when the breakpoint is reached or when all breakpoints are listed by the lb command. The number is used to delete individual breakpoints using the d command.

    The WITHIN Qualifier - Usage in Ada

    The WITHIN qualifier is used as follows.

    This instructs the debugger to stop the program whenever the exception Use_Error is raised by one of the routines in Text_Io. If Use_Error is raised by a routine in another package which is called by a Text_Io routine, though, the program will not stop.

    It is possible to have a line number specification on the catch WITHIN syntax line. For example, if you enter:

    this says to stop the program if the exception Program_Error is raised at line 35. You can also enter

    which says to stop the program if the exception Program_Error is raised at the current line.

    It is possible to have nested program regions for the WITHIN clause of a program region. If several regions overlap, the innermost region is selected. For example, if the following commands were entered:

    and Program_Error was raised in Text_Io.Set_Input, it would not be announced by the debugger.

    WITHIN clauses are independent of IN task clauses. It is possible to give catch commands in any combination of exceptions, program units and tasks, as long as there's no conflicting propagate specifications, or conflicting task specifications. For example,

    do not generate any conflicts.

    Thus, the only way to enter conflicting catch commands is if the exception name, program region, and task specification match exactly. For example, the following two commands:

    would cause an error message, but the following two commands would not:

    When the exception gets raised, the debugger only examines the catch commands appropriate to the current task. These include those that specify the current task and those with no task specifier. If this set has more than one command, it then selects the one(s) that specify the innermost program region. If this set has more than one command, it then selects the ones that specify the exception being raised. If this set has more than one command, it then selects the one that specifies the current task.

    The WITHIN Qualifier - Usage in C/C++

    The WITHIN qualifier is used as follows.

    This instructs the debugger to stop the program whenever int is thrown in func. If int is thrown by another routine, though, the program will not stop.

    It is possible to have a line number specification on the catch WITHIN syntax line. For example, you can enter:

    This says to stop the program if an int is thrown at line 35. You can also enter

    which says to stop the program if an int is thrown at the current line.

    It is possible to have nested program regions for the WITHIN clause of a program region. If several regions overlap, the innermost region is selected. For example, if the following commands were entered:

    and int was thrown in Text_Io.Set_Input, it would not be announced by the debugger.

    Thus, the only way to enter conflicting catch commands is if the exception name and program region match exactly. For example, the following two commands:

    would cause an error message, but the following two commands would not:

    When the exception gets raised, the debugger selects the one(s) that specify the innermost program region. If this set has more than one command, it then selects the ones that specify the exception being raised.

    In Screen Mode

    Precede this command with : and follow with Return.

    Delete Exception

    When the Exception window opens, you can remove an exception from the debugger's list of requests.

    To remove an exception from the debugger's list of requests, use the Exceptions > Remove command from the Exceptions window and follow these steps:

    1 . Position the cursor at the desired exception.

    2 . Click the Debug > Remove or Remove button in the Exceptions window.

    To delete exceptions from the Command Pane or the non-GUI debugger log prompt, use the d command. The exception number used by this command can be displayed using the le command.

    Propagate Exception(s)

    There are several ways to execute the propagate exception-handling commands. You can:

    propagate

    Break when language exception occurs

    Syntax

    Ada:

    C/C++:

    Arguments
    Description

    The propagate command indicates that the specified exception will not cause the program to stop in the specified program_unit or task (Ada only). If no exception name is specified, no exception will cause the program to stop in the specified program unit<ada,multi,nt> or task (Ada only).

    Catch and propagate breakpoints can coexist. A catch command without an exception name, WITHIN clause, or IN clause does not conflict with any legal propagate command. Thus, you can enter:

    This breaks for all exceptions except for those raised in the program unit My_Proc. or,<if you are working in Ada, you can enter:

    which would break for all exceptions except for those raised in task 3.

    If you want an action to be performed when the program stops even though there are propagate breakpoints active, you can associate these actions with a catch breakpoint. For example, if you enter:

    Now, whenever the program raises Constraint_Error, nothing will happen. For any other exception, however, the debugger stops the program, does a cs command, and continues the program.

    The following can be used to ignore several exceptions within the same task (Ada) or function (C/C++):

    Ada:

    C/C++:

    In Ada, this option can also be used to set breaks which would otherwise conflict in separate tasks.

    The WITHIN Qualifier - Usage in Ada

    The WITHIN qualifier is used as follows.

    This instructs the debugger to not stop the program whenever the exception Use_Error is raised by one of the routines in Text_Io.

    It is possible to have a line number specification on the propagate WITHIN syntax line. For example, if you enter

    this says not to stop the program if the exception Program_Error is raised at line 35. You can also enter

    which says not to stop the program if the exception Program_Error is raised at the current line.

    It is possible to have nested program regions for the WITHIN clause of a program region. If several regions overlap, the innermost region is selected. For example, if the following commands were entered:

    and Program_Error was raised in Text_Io.Set_Input, it would not be announced by the debugger.

    WITHIN clauses are independent of IN task clauses. It is possible to give catch commands in any combination of exceptions, program units and tasks, as long as there's no conflicting propagate specifications, or conflicting task specifications. For example,

    do not generate any conflicts.

    Thus, the only way to enter conflicting propagate commands is if the exception name, program region, and task specification match exactly. For example, the following two commands:

    would cause an error message, but the following two commands would not:

    When the exception gets raised, the debugger only examines the propagate commands appropriate to the current task. These include those that specify the current task and those with no task specifier. If this set has more than one command, it then selects the one(s) that specify the innermost program region. If this set has more than one command, it then selects the ones that specify the exception being raised. If this set has more than one command, it then selects the one that specifies the current task.

    The WITHIN Qualifier - Usage in C/C++

    The WITHIN qualifier is used as follows.

    This instructs the debugger to not stop the program whenever an int is thrown in func.

    It is possible to have a line number specification on the propagate WITHIN syntax line. For example, if you enter

    this says not to stop the program if the exception Program_Error is raised at line 35. You can also enter

    which says not to stop the program if a char* is thrown at the current line.

    It is possible to have nested program regions for the WITHIN clause of a program region. If several regions overlap, the innermost region is selected.

    The only way to enter conflicting propagate commands is if the exception name and program region match exactly. For example, the following two commands:

    would cause an error message, but the following two commands would not:

    When the int gets raised, the debugger only selects the one(s) that specify the innermost program region. If this set has more than one command, it then selects the ones that specify the exception being raised.

    In Screen Mode

    Precede this command with : and follow with Return.

    List Exceptions

    To see a list of all exceptions, use the Windows > Exceptions command from a debugger window, the Debug > Exceptions command from an editor window, or the le command in the Command-Pane or non-GUI debugger. If you use the Windows > Exceptions or the Debug > Windows > Exceptions command, the Exceptions Window is displayed.

    .

    To simply list all active breakpoints in the Log area of the main debugger window, or when using the non-GUI debugger, enter the le command.

    le

    List exceptions

    Syntax
    Description

    le lists all currently set catch/propagate exceptions in all programs. To the left of each breakpoint is a number in brackets. Delete the exception with this number using the d command.

    In Screen Mode

    Precede this command with : and follow with Return.

    Raise Exception

    To raise an exception, use the Debug > Raise Exception command from any debugger or editor window, or use the raise command in the Command Pane or with the non-GUI debugger.

    raise

    Raise exception

    Syntax
    Arguments
    Description

    The raise command raises the exception specified by exception_name.

    In Screen Mode

    Precede this command with : and follow with Return.


    User Subprogram Calling

    It is possible in the debugger to call a function or procedure (Ada) that is part of the program being debugged. This is referred to as "user subprogram calling". The commands associated with subprogramming calls and returns are as follows:

    Table 14 DebuggerSubprogram Call/Return Commands
    Operation
    Command
    Window
    Call subprogram
    Debug > Call Subprogram
    Execution > Call Subprogram (Ada only)

    p
    Editor Window
    All debugger windows

    Command Pane,
    Command-Line interface

    Return from called subprogram
    Debug > Return from Call
    Execution > Return from Call (Ada only)

    return
    Editor Window
    All debugger windows

    Command Pane,
    Command-Line interface

    If you are using the debugger GUI, help information on each of these execution commands is available using the Help > On Context command or the Help button from any dialog box.

    In the debugger GUI, the Debug > Call Subprogram (editor windows) or Execution > Call Subprogram (debugger windows) command is used. If either of these commands is invoked, a dialog appears in which the name of the subprogram to be called should be entered. The Return from Call command enables you to return from a called subprogram.

    Since user subprogram calling is treated as an expression by the debugger, the command-line interface to this functionality is the p command. For example.

    You can use subprogram calling to build customized displays for key objects and access data structure routines. Routines can be written to display data structures, to verify that data structures have certain properties (e.g., is the table sorted?) or to display and navigate through a complex data structure. Then, these routines can be accessed in the debugger.

    A subprogram called by the debugger is not limited to displaying numbers and text on the screen. The subprogram can prompt for input, read it and act on it interactively. It can also display output from the procedure or capture it in the debugger log file.

    Since these functions are written in Ada or C/C++ as part of the user program, they can be called from the program. For example, a subprogram can display data structures when an internal error is detected or prior to a catastrophic failure. If these subprograms are left in the program after it is deployed, they provide a method for debugging the program in the field at a customer site.

    Currently, calling lexically nested subprograms only works if the subprogram makes no reference to up-level variables. If you set a breakpoint in a lexically nested subprogram, call the subprogram, hit the breakpoint and try to examine up-level variables, the debugger is not able to find the address(es) of these variables.


    Warning: If the subprogram call hits a breakpoint, the program stops and the user can debug as normal; however, the debugger abandons evaluating the expression, if any. For example:

    Case 1: the user calls cos[] and has no breakpoints set in cos or in any routines that cos[] calls. The debugger prints the return value:

    Case 2: The user calls cos[] and has a breakpoint set in cos[]:

    Note that in this second case, the value is not printed. When the function returns from the user-generated call, i.e., from the debugger command p cos(45.0), because expression evaluation is interrupted by the breakpoint, the debugger makes no attempt to continue with expression evaluation.

    Case 3: The user calls foo([cos(45.0)), where foo is a function and has a breakpoint in cos[]:

    In this third case, the function that returned normally is cos, not foo(). foo() is never called because expression evaluation is abandoned during the call to cos() because of the breakpoint.

    The command-line interfaces for the return commands is detailed below. The p command is discussed in the Data display section.

    return

    Return from all called functions

    Syntax
    Arguments
    Description

    return returns from all the user procedures that are called using the debugger p proc(...) command. After issuing a return command, you are back to where the original user procedure was called -- return always returns from all of the nested user procedure calls from the call stack.

    Frequently it is convenient to write a subprogram (Ada) or function (C/C++) that takes a pointer to a complex data structure and displays it on the screen. The debugger p proc(...) command calls any subprogram (Ada) or function (C/C++) from the debugger. These subprograms (Ada) or functions (C/C++) that display data structures are a valuable tool for debugging but they can need to be debugged themselves. If the subprogram (Ada) or function (C/C++) that is called using p proc(...) faults, use the return command to return to the original program that is being debugged.

    Set a breakpoint in a subprogram (Ada) or function (C/C++) prior to calling it using p proc(...) After you hit this breakpoint, a different subprogram (Ada) or function (C/C++) can be called (that is, it is possible to nest user subprogram (Ada) or function (C/C++) calls). The return command clears all subprogram (Ada) or function (C/C++) calls.

    Note: The return read and return read all commands can be used within a breakpoint command block.

    read

    Syntax
    Arguments
    Description

    read switches the debugger input source from the keyboard to the named file. Additional read commands can occur in the file but are nested to only four levels. After executing the file, commands are again read from the keyboard (unless the command file contains an exit or quit command).

    In Screen Mode

    Precede this command with : and follow with Return.


    Embedded Execution Commands

    These commands are only available with the Apex Ada and Apex Duo embedded products.

    There are several specialized execution commands that pertain only to embedded or cross systems. These are listed in Table 15. Additional information is available on cross-debugging is available in the Programming for {Rexec, Tornado, LynxOS} guides.

    Table 15 Embedded Execution Commands
    Operation
    Command
    Window
    Download memory image to target
    File > Download

    load
    All debugger windows

    Command Pane,
    Command-Line interface

    Synchronize host and target
    File > Sync

    sync
    All debugger windows
    Command Pane,
    Command-Line interface

    Continue execution after the program has stopped for any reason.
    pass
    Command Pane,
    Command-Line interface

    If you are using the debugger GUI, help information on the File > Download and File > Sync commands is available using the Help > On Context command or the Help button from the dialog box.

    The command-line interfaces to the embedded execution commands are detailed below.

    load

    Download memory image.

    Syntax
    Arguments
    Description

    The load command is for Apex Cross debuggers only. Its purpose is to give the user more precise control over when the download operation takes place.

    After downloading a program, the PC is set to the kernel starting address.

    An alternative to the load command is the sync command. This attempts to synchronize the Apex Cross debugger with the current state of the target processor.

    When the Native debugger is invoked, it automatically sets up a program to run. When the Apex Cross debugger is invoked, it does not automatically download a program; the user must invoke the load command. As a result, right after debugger invocation many commands cannot be used until either the load or sync command is given.


    Warning: Commands occurring after a load command on the same line are not executed. For example, the end command in

    >b 133 load myfile.vox; end

    is not executed. In this case, the user will be prompted for additional input and will have to enter end again on the next line.

    sync

    Set/reset debugger.

    Syntax
    Arguments
    Description

    The sync command causes the debugger to flush all information it currently has about the target and re-read this information from the target. The debugger assimilates the current target state in much the same way it does when the target hits a breakpoint.

    Use of the sync command with no arguments sets up the current program state using the PC stored in TDM or an emulator.

    The purpose of the sync command is to better support the pass command. Using the pass command, it is possible to transparently alter the state of the target processor without the debugger knowing. If this happens, the debugger starts to behave incorrectly as values read from registers or memory do not correspond to what the debugger expects. The sync command tells the debugger to reset its expectations by reading the current state from the target.

    The sync start command does all the things that the load command does, except download code:

    1 . Get the start address of the user program in the VOX file. Then that address sets the current position.

    2 . Set the PC in TDM to point to the kernel start address.

    3 . Reset all the user breakpoints in the new image.

    4 . Set up the call stack to look as though the program has not executed.

    5 . Complete any additional activities necessary if debugging in a multiprogram environment.

    The sync expr command is much simpler. If expr is a numeric expression (03AB00, $pc+4, var), it is evaluated, converted to an address and that address is used as the next PC. If expr is a procedure, then the procedure address is used as the next PC. That value then becomes the next instruction that is executed.

    Note: If you start a debugging session, use only statistically allocated package variables or library level procedure names.

    You can use the sync command to connect the debugger to the current state of the target processor just after invoking the debugger. This is useful in certain cases. For example, if a target system executing without the debugger crashes, use the debugger to examine the crashed memory image symbolically. If several programs are executing independently on the target (for example, a kernel and user program), exit the debugger at a breakpoint while debugging one and then reinvoke in the library of the other. A sync command causes the debugger to pick up the state of execution, so both programs are debugged with symbolic information.

    The sync command cannot completely restore a debugging situation. In particular, if breakpoints are set in a memory image and the debugger is exited and reinvoked, a sync command picks the correct register values, but the debugger cannot recognize breakpoints that remain in the memory image. Disassembly over such breakpoints is incorrect; attempts to continue execution past such breakpoints fail.

    pass

    Pass command to target controlling agent.

    Syntax
    Arguments
    Description

    Cross debuggers are implemented by utilizing the support of what is called a target controlling agent. A microprocessor emulator or the Target Debug Monitor (TDM) are target controlling agents. These agents are often powerful debugging stations and can provide facilities that complement those provided by the Apex debugger.

    The pass command enables the user to send commands to the controlling agent. All the text following the pass keyword is sent to the agent. If any output is generated by the agent, it is displayed on the screen. You can configure TDM to handle passthru text.

    The pass command also permits debugger expressions to be evaluated with the resulting value replacing the expression in the passthru text. For example, suppose the variable xxx has the value 222 and is at location 07fff1680. The passthru command

    results in the following text:

    being passed down to the target controlling agent.

    To enhance the utility of the $eval capability, additional debugger-interpreted attributes are available. These are discussed under Expressions.


    Warning: Some caution must be exercised when using the pass command. When the target processor reaches a breakpoint, the debugger reads state information that it keeps resident on the host computer. A pass command can make this information invalid. For example, if the emulator command to single-step is passed to the emulator, the target real state is inconsistent with the state the debugger has saved.

    Use the sync instruction to synchronize the debugger with the current state of the target processor and the controlling agent.


    Warning: Commands occurring after a pass command on the same line are not executed. For example, the end command in

    >b 133 begin pass commands; end

    is not executed. In this case, the user will be prompted for additional input and will have to enter end again on the next line.


  • 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