![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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
- Breakpoints
- Handling Exceptions
- User Subprogram Calling
- Embedded Execution Commands (Ada only)
Executing and Stepping a ProgramYou 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.
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
Syntax
g [all]
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
gs [signal
]
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
gwname
|address
|register
[,number
]
Arguments
- address
Memory address. This is either decimal or hexadecimal. If hexadecimal, a leading 0 is required.
- name
- number
Number of bytes. This value is from 1 to 16 inclusive. [Default: 4].
- register
Allows users to watch registers when the register is specified. For example:
gw $pc
Only available where there is no target or OS support for watchpoints. Target Support is available on the PowerPC and i386 crosses and Software Support on SGI.
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
Syntax
jump [line
]
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
Syntax
jumpi [instruction
]
Arguments
- instruction
Address of a machine instruction. The address is a hexadecimal number (with a leading 0).
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
Syntax
r [shell_arguments
]
Arguments
- shell_arguments
Shell command arguments. The debugger uses csh(1), sh(1), or the shell defined in the environment (exported) variable SHELL. (native systems only)
Note: If more than one program is being debugged, arguments to the r command are not accepted. Users must use the set run command to specify command arguments for each program.
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
Syntax
Return
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
Syntax
exit
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
Syntax
quit
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
Syntax
stop [program list
]
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:
- If the exception is caught in the debugger, the step is not completed; when the program is continued, it executes to the normal completion of the step. That is:
- A step command is in progress.
- An exception is raised that is to be caught.
- The debugger catches the exception and stops execution.
- When execution is continued, the step command is completed.
- If the exception is not caught in the debugger, the program executes to the normal completion of the step.
The normal completion of the step is determined as follows:
- If the exception is handled by an exception handler within the scope of the step, the exception handler is executed and the step command continues as normal.
- If the exception is handled by an exception handler beyond the scope of the step, execution stops at the first statement in the exception handler and the step is considered completed.
- If the exception is not handled by an exception handler, the program terminates.
The following step commands are available (in order from least detailed to most detailed
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
i
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:
f(g(), h());
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.
- The last call is to a routine that has no debugging information this case, the i command will behave like an o command (Step Over). This last call may not even be explicit in the source code, as in the case of compiler generated calls to runtime routines. For example:
x := new integer'(foo(y)); (Ada) foo_type* x = new foo_type; (C++)
- The last call is conditionally called. For example:
if foo(x) and then bar(x) then (Ada) if (foo(x) && bar(x) {} (C++)
If bar() is not called, the i command will behave like an o command.
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
ii
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
is
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
o
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
oi
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
os
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
s
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
si
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
ss
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).
BreakpointsA 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.
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:
b [line
|subprogram
] [intask
] whenexpression
b [line
|subprogram
] [intask
] ifexpression
then [commands
] [else [commands
]] end [if] b [line
|subprogram
] [intask
] ifexpression
else [commands
] end [if]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:
b 38 when col <= row
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,
b 38 if col < row then p col; p row; end if
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:
b 38 if i > 5 else p i; end if
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.
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
b[line
|subprogram
] [in task] [begin commands end] b [line|subprogram] [in task] when expression b [line|subprogram] [in task] if expression then commands [else commands] end [if] b [line|subprogram] [in task] if expression else commands end [if]
b [line|function] [begin commands end] b [line|function] when expression b [line|function] if expression then commands [else commands] end [if] b [line|function] if expression else commands end [if]
Arguments
- commands
A sequence of one or more debugger commands that automatically execute when the breakpoint is reached. Use the following format:
begincommands
end
You can enter the commands on the same line separated by semicolons or enter each command on its own line as long as the first begin, then or else is on the same line as the b keyword. Any execution command in the commands sequence must be last. The second method (separate lines) is recommended. As each command of commands is entered on its own line, the debugger prompts with ?? for each new command until the sequence terminates with end (or an else in the case of an if...then...else). See the examples section below.
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
- 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.
Use the if statement to set a conditional breakpoint that conditionally executes debugger commands when the breakpoint is reached. expression is evaluated each time the breakpoint is reached. If it is True, the breakpoint is announced and any commands in a then clause execute. If the expression is False, the commands in an else clause execute, no breakpoint is announced and execution continues.
- function (C/C++ only)
Name of a function or class. If the function name given is a simple identifier, all functions and classes (with an elaboration function) in the program are visible.
The function can also be given as an expanded name. The leftmost simple name of an expanded name must be directly visible from the current context.
If the function name has multiple definitions, it is overloaded. The debugger prints a diagnostic showing the alternatives. Retype the b command attaching a '1, '2,... suffix (matching an alternative shown in the diagnostic) to the function name to disambiguate it. Alternatively, sometimes it is sufficient to use an expanded name to disambiguate it.
- line
Line number at which the breakpoint is set. line is typically a decimal number.
- subprogram (Ada only)
Name of a subprogram, task or package. If the subprogram name given is a simple identifier, all subprograms, tasks, and packages (with an elaboration subprogram) in the program are visible.
The subprogram can also be given as an expanded name (starting with standard if desired). The leftmost simple name of an expanded name must be directly visible from the current context or must be the name of a library unit.
If the subprogram name has multiple definitions, it is overloaded. The debugger prints a diagnostic showing the alternatives. Retype the b command attaching a '1, '2,... suffix (matching an alternative shown in the diagnostic) to the subprogram name to disambiguate it. Alternatively, sometimes it is sufficient to use an expanded name to disambiguate it.
- task
Task number of the task in which the breakpoint is announced. The task number is obtained with the lt command. The breakpoint is announced only for the specified task.
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
>b 537 (set breakpoint at line 537 of current source file) >b SORT_STAMPS (set breakpoint at procedure SORT_STAMPS) >b SORT when FIRST = "January" (conditional breakpoint Ada) >b SORT when FIRST == "January" (conditional breakpoint C/C++) >b MONTH_NO begin (command block) ??p month ??p date'string (Ada) ??p date_string (C/C++) ??g ??endIn 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
bd [intask
] [begincommands
end] bd [intask
] whenexpression
bd [intask
] ifexpression
thencommands
[elsecommands
] end [if] bd [intask
] ifexpression
elsecommands
end [if]
bd [begincommands
end] bd whenexpression
bd ifexpression
thencommands
[elsecommands
] end [if] bd ifexpression
elsecommands
end [if]Arguments
- commands
A sequence of one or more debugger commands that automatically execute when the breakpoint is reached. Use the following format:
begincommands
end
You can enter the commands on the same line separated by semicolons or enter each command on its own line as long as the first begin, then or else is on the same line as the b keyword. Any execution command in the commands sequence must be last. The second method (separate lines) is recommended. As each command of commands is entered on its own line, the debugger prompts with ?? for each new command until the sequence terminates with end (or an else in the case of an if...then...else).
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
Syntax
bi [instruction
] [intask
] [begincommands
end] bi [instruction
] [intask
] whenexpression
bi [instruction
] [intask
] ifexpression
thencommands
[elsecommands
] end [if] bi [instruction
] [intask
] ifexpression
elsecommands
end [if]
bi [instruction
] [begincommands
end] bi [instruction
] whenexpression
bi [instruction
] ifexpression
thencommands
[elsecommands
] end [if] bi [instruction
] ifexpression
elsecommands
end [if]
Arguments
- commands
A sequence of one or more debugger commands that automatically execute when the breakpoint is reached. The following format is used:
begincommands
end
You can enter the commands on the same line separated by semicolons or enter each command on its own line as long as the first begin, then or else is on the same line as the b keyword. Any execution command in the commands sequence must be last. The second method (separate lines) is recommended. As each command of commands is entered on its own line, the debugger prompts with ?? for each new command until the sequence terminates with end (or an else in the case of an if...then...else).
- 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.
- instruction
Address of a machine instruction. The address is a hexadecimal number (with a leading 0).
- 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
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
br [intask
] [begincommands
end] br [intask
] whenexpression
br [intask
] ifexpression
thencommands
[elsecommands
] end [if] br [intask
] ifexpression
elsecommands
end [if]
br [begincommands
end] br whenexpression
br ifexpression
thencommands
[elsecommands
] end [if] br ifexpression
elsecommands
end [if]Arguments
- commands
A sequence of one or more debugger commands that automatically execute when the breakpoint is reached. The following format is used:
begincommands
end
You can enter the commands on the same line separated by semicolons or enter each command on its own line as long as the first begin, then or else is on the same line as the b keyword. Any execution command in the commands sequence must be last. The second method (separate lines) is recommended. As each command of commands is entered on its own line, the debugger prompts with ?? for each new command until the sequence terminates with end (or an else in the case of an if...then...else).
- 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
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.
15 -- 16*= procedure TEST_SINGLE_DATE(DATE : STRING) is 17 DAY : CONVERT.DATE_REP; 18 TURN_CENTURY: constant STRING(1..2) := "00"; 19 begin
7 . int row = 0; 8 . int col = 0; 9 10*= while(col < col_range) { 11 . while(row < row_range && col < col_range) { 12 . if(is_safe(row, col)) {
bw
Syntax
bwname
|address
|register size access
[intask
][begincommands
end]Arguments
- access
Type of memory access. The allowed types are
x Execute
r Read
w Write
rw Read/write
m Modify [Default]
- address
Memory address in hexadecimal or decimal. For hexadecimal addresses, a leading 0 is required
- commands
A sequence of one or more debugger commands that automatically execute when the breakpoint is reached. Use the following format:
begincommands
end
You can enter the commands on the same line separated by semicolons or enter each command on its own line as long as the first begin, then or else is on the same line as the bw keyword. Any execution command in the commands sequence must be last. The second method (separate lines) is recommended. As each command of commands is entered on its own line, the debugger prompts with ?? for each new command until the sequence terminates with end (or an else in the case of an if...then...else).
- name
- register
Allows users to watch registers when the register is specified. For example:
bw $sp
Only available where there is no target or OS support for watchpoints. Target Support is available on the PowerPC and i386 crosses and Software Support on SGI.
- size
Number of bytes from 1 to 16. If no value is specified, the default size for addresses is 4 and the default size for a name is the size of that variable.
- 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
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.
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
Syntax
b on all b onbreakpoint_number
[,breakpoint_number
]...
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
Syntax
b off all b offbreakpoint_number
[,breakpoint_number
]...
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)
- 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
Syntax
d all|breakpoint_number
[,breakpoint_number
]...
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:
d 1, 2, 3
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,
b if condition then d b if other_condition then return read all else g; end if else g end;
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:
[breakpoint number
]file name
:line number
inunit name
intask task name
[task sequence number
]
[breakpoint number
]file name
:line number
infilename
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
lb [b | e]
Arguments
- b
List only non-catch/propagate breakpoints.
- e
List only catch/propagate breakpoints. These are breakpoints which occur on exceptions.
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)
Syntax
set signal[signal_list
|all] [b|g|gx]
Arguments
- all
- b
When the signal occurs it is announced and the program stops as if it reached a breakpoint.
- g
The signal is not announced and the debugger continues the program execution without passing the signal to the program.
- gs
On /proc systems, the process is configured so that, if possible, the signal is passed to the program without debugger notification (SIGTRAP cannot be handled this way). For ptrace systems, the signal stops the process, the debugger does not announce the signal and the program execution is continued with the signal passed to it. This option is useful when debugging programs with exception handlers for hardware exceptions.
- signal_list
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:
% kill -l HUP INT QUIT ILL TRAP ABRT EMT FPE BUS SEGV SYS PIPE ALRM TERM URG STOP TSTP CONT CHLD TTIN TTOU IO XCPU XFSZ VTALRM PROF WINCH LOST USR1 USR2
Inside the debugger, to display the current setting for each signal, enter signal [signal_list|all] [b|g|gs] [in task] without parameters:
>set signal b: hup..pipe, term..tstp, chld..USR2 g: cont gx: alrm
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:
- an instance of a class
a qualified or unqualified member function name
b class_name::member_function
b member_function
then an unconditional breakpoint will be set for all calls to the member function.
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).
v class_identifier // navigate to the class definition b class_identifier // set breakpoint at constructor b class_identifier::member // class_identifier refers to the class name p class_identifier // print addresses of constructor overloadingsNavigation to a constructor can be done by giving a qualified name of the constructor.
v class_identifier::class_identifier
Member Functions
- this
this is an implicit parameter that is passed to all non-static member functions. It is a pointer to class instance specified on the call to the member function and may be used to reference class members.
- Visibility from within member functions
Inside the body of a non static member function the class members are directly visible without explicit class instance qualification. The this parameter is implicitly used to qualify all such references. Calls to unqualified member functions from the debugger may be made in this situation.
- Calling member functions
The implicit this parameter identifying the class instance must be passed in to all non-static member functions. Static member functions may be called from the debugger without a qualifying class instance just like any normal function.
p static_member_function()
but all other member function calls must specify a class instance.
p class_instance.member_function()
Virtual functions
- Virtual table
Each class that contains virtual functions contains an implicit data member called virtual. Each virtual function is assigned a virtual index that is used by both the compiler and debugger to map virtual functions to the associated real function and to calculate the correct offset of the this pointer for the class object associated with the real function. The virtual index of a particular virtual function can be obtained by the p command.
- Virtual function operations
The debugger uses a virtual function's index to map virtual functions to the corresponding real function. This virtual table mapping is done to call virtual functions, navigate to virtual functions, or to print out the address and parameter profile of a virtual function.
Handling ExceptionsThe 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:
rdb error: spec of ex_utils not found in searched libraries EXCEPTION WHILE STEPPING -- stopped in +raise_interrupt at 042e1bc: lui gp,0fbf gp <- 0fbf0000
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:
>set except_stack
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:
catch [type_spec
] [WITHINfunction_or_line_number
] propagate [type_spec
] [WITHINfunction_or_line_number
]
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
catchThe debugger will stop the program when any exception is thrown.
catchouter_class::inner_class
The debugger will stop the program when any expression is thrown that matches outer_class::inner_class.
catch withinclass_name::func
The debugger will stop the program when any exception is thrown from within class_name::func.
catch within 125
The debugger will stop the program when any exception is thrown from line number 125 of the current source file.
catch short int * withinclass_name::func
The debugger will stop the program when a "short int *" object is thrown from within class_name::func.
propagateThe debugger will NOT stop the program when any exception is thrown.
propagateouter_class::inner_class
The debugger will NOT stop the program when any expression is thrown that matches outer_class::inner_class.
propagate withinclass_name::func
The debugger will NOT stop the program when any exception is thrown from within class_name::func.
propagate within 125The debugger will NOT stop the program when any exception is thrown from line number 125 of the current source file.
propagate short int * withinclass_name::func
The debugger will NOT stop the program when a "short int *" object is thrown from within class_name::func.
Exception-Handling Commands
Table 13 lists the exception-handling commands you can execute.
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:
- If a Catch request, the program is stopped, and the exception reported to the user.
- If a Propagate request, the exception is ignored, and the program continues as if the exception did not occur.
Catch Exception(s)
There are several ways to execute the catch exception-handling commands. You can:
- Choose the Catch command from the Debug menu in the editor window or any debugger window.
- Select the Debug > Windows menu from the editor window and then choose the Exceptions submenu. Apex then displays the Exceptions dialog box, which offers a complete selection of exception-handling commands.
- Enter the catch command-line interface debugger exception command in the Command Pane or through the batch-mode debugger.
catch
Break when a language exception occurs
Syntax
catch exception|all [WITHIN program_unit|line] [IN task][begin commands end] catch exception|all [WITHIN program_unit|line] [IN task] when expression catch exception|all [WITHIN program_unit|line] [IN task] if expression then commands [else commands] end [if] catch exception|all [WITHIN program_unit|line] [IN task] if expression else commands end [if]
catch exception|all [WITHIN program_unit|line][begin commands end] catch exception|all [WITHIN program_unit|line] when expression catch exception|all [WITHIN program_unit|line] if expression then commands [else commands] end [if] catch exception|all [WITHIN program_unit|line] if expression else commands end [if]Arguments
- all
All exceptions will be caught (i.e., all exceptions will cause the program to stop).
- commands
A sequence of one or more debugger commands that automatically execute when the breakpoint is reached. The following format is used:
begincommands
end
You can enter the commands on the same line separated by semicolons or enter each command on its own line as long as the first begin, then or else is on the same line as the b keyword. Any execution command (o, oi, i, ii, s, si, o, oi, i, ii, s, si, g, gw, r) in the commands sequence must be last. The second method (separate lines) is recommended. As each command of commands is entered on its own line, the debugger prompts with ?? for each new command until the sequence terminates with end (or an else in the case of an if...then...else).
- exception
- 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.
- line
Line number. If the exception occurs on this line, the exception is raised. If it does not occur at the specified line, the exception is not raised.
- program_unit
For Ada, the subprogram, package body or task body that specifies a region of code where, if an exception is raised, the catch command applies.
For C/C++, the function or class that specifies a region of code where, if an exception is raised, the catch command applies.
- 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
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.
>catch constraint_error (Ada) >catch int (C/C++)
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.
catch use_error within text_io
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:
catch program_error within 35
this says to stop the program if the exception Program_Error is raised at line 35. You can also enter
catch program_error within *
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:
catch program_error within text_io propagate program_error within text_io.set_input
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,
catch numeric_error within proc1 in task1 catch numeric_error within proc2 in task1 catch numeric_error within proc1 in task2 catch numeric_error within proc2 in task2
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:
propagate program_error catch program_error
would cause an error message, but the following two commands would not:
propagate program_error catch program_error in user_task
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.
catch int within func
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:
catch int within 35
This says to stop the program if an int is thrown at line 35. You can also enter
catch int within *
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:
catch int within text_io propagate int within text_io.set_input
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:
propagate int catch int
would cause an error message, but the following two commands would not:
propagate int catch int within func
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:
- Choose the Propagate command from the Debug menu in the editor window or any debugger window.
- Select the Debug > Windows menu from the editor window and then choose Exceptions. Apex then displays the Exceptions dialog box, which offers a complete selection of exception-handling commands.
- Enter the propagate command-line interface debugger exception command in the Command Pane or through the batch-mode debugger.
propagate
Break when language exception occurs
Syntax
propagateexception
|all [WITHINprogram_unit
|line
] [INtask
][begincommands
end] propagateexception
|all [WITHINprogram_unit|line
] [INtask
] whenexpression
propagateexception
|all [WITHINprogram_unit
|line
] [INtask
] ifexpression
thencommands
[elsecommands
] end [if] propagateexception
|all [WITHINprogram_unit
|line
] [INtask
] ifexpression
elsecommands
end [if]
propagateexception
|all [WITHINprogram_unit
|line
] [begincommands
end] propagateexception
|all [WITHINprogram_unit
|line
] whenexpression
propagateexception
|all [WITHINprogram_unit
|line
] ifexpression
thencommands
[elsecommands
] end [if] propagateexception
|all [WITHINprogram_unit
|line
] ifexpression
elsecommands
end [if]Arguments
- all
All exceptions will be propagated (i.e, no exception will cause the program to stop.
- commands
A sequence of one or more debugger commands that automatically execute when the breakpoint is reached. The following format is used:
begincommands
end
You can enter the commands on the same line separated by semicolons or enter each command on its own line as long as the first begin, then or else is on the same line as the b keyword. An execution command in the commands sequence must be last. The second method (separate lines) is recommended. As each command of commands is entered on its own line, the debugger prompts with ?? for each new command until the sequence terminates with end (or an else in the case of an if...then...else).
- exception
- 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.
- line
Line number. If the exception occurs on this line, the exception is raised. If it does not occur at the specified line, the exception is not raised.
- program_unit
Subprogram, package body,task body (Ada only), <c++>function or class (C/C++ only) that specifies a region of code where, if an exception is raised, the propagate command applies.
- 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
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:
catch propagate within my_proc
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:
catch propagate in 3
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:
catch begin cs; g; end propagate constraint_error<multi (Ada) propagate int<multi> (C/C++)
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++):
propagate constraint_error in task_b propagate numeric_error in task_b
propagate float propagate char*
In Ada, this option can also be used to set breaks which would otherwise conflict in separate tasks.
catch in task_a catch constraint_error in task_b propagate constraint_error in task_c
The WITHIN Qualifier - Usage in Ada
The WITHIN qualifier is used as follows.
propagate use_error within text_io
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
propagate program_error within 35
this says not to stop the program if the exception Program_Error is raised at line 35. You can also enter
propagate program_error within *
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:
catch program_error within text_io propagate program_error within text_io.set_input
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,
catch numeric_error within proc1 in task1 catch numeric_error within proc2 in task1 catch numeric_error within proc1 in task2 catch numeric_error within proc2 in task2
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:
propagate program_error catch program_error
would cause an error message, but the following two commands would not:
propagate program_error catch program_error in user_task
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.
propagate int within func
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
propagate char* within 35
this says not to stop the program if the exception Program_Error is raised at line 35. You can also enter
propagate char* within *
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:
propagate int catch int
would cause an error message, but the following two commands would not:
propagate int catch int within func
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
Syntax
le
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
Syntax
raiseexception_name
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 CallingIt 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:
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.
>p factor (5.0) 120
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:
> p cos(45.0) 0.5
Case 2: The user calls cos[] and has a breakpoint set in cos[]:
> p cos(45.0) [7] stopped at "/u/sbq/sincos/cos.c":494 in cos > ... -- the user debugs here, inside cos (or some subprogram > ... -- that cos has called). > g Procedure returned normally.
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[]:
> p foo(cos(45.0)) [7] stopped at "/u/sbq/sincos/cos.c":494 in cos > ... -- the user debugs here, inside cos (or some subprogram > ... -- that cos has called). > g Procedure returned normally.
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
return [read] [read all]
Arguments
- read
When executing a read filename command, return read terminates the reading of commands in filename. If the read filename command was typed at the terminal, the user gets a prompt at the terminal. If the read filename command is inside a file, the next command read is the command in that file following the read filename command. This command pops out of nested reads by one level.
- read all
This option returns from all files and the user gets a prompt at the terminal. For example, file a includes the command read b and file b contains the command read c. If during the execution of commands in file c a return read all command is encountered, all files are exited and a terminal prompt appears. This command pops out of all nested read commands.
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
readfilename
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 CommandsThese 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.
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
Syntax
load [[symbols]filename
]
Arguments
- filename
Name of the file to load. If no filename is given, the executable file named in the debugger invocation is downloaded.
- symbols
Read the symbols of the executable file but do not load the executable to the target. Note that the symbols of the executable named in the debugger invocation are always read during debugger startup.
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
Syntax
sync [expr
| START]
Arguments
- expr
The integer value at which to set value of the PC. For example, $pc+8 or global.start.
- START
Reset the program state as though the program is just loaded. The current source position becomes the start of the program and the PC is set to start execution at the start of the runtime. This argument is for your convenience if you load your program using some agent outside the debugger. Note that you must reload your program if you use this option, or inconsistent and perhaps baffling behavior occurs.
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
pass text
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
>pass ---- $eval(xxx) ------ $eval(xxx'address) ----
results in the following text:
---- 222 ------ 07fff1680 ----
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. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |