![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Customizing the Debugger The Apex debugger simplifies interactive debugging by maintaining a record of its state. This debugger state includes:
- Debugger options
- Debugger variables
- Macro settings
- Type Display settings
- Breakpoint settings
- Exception settings
Any of these areas can be modified, saved, or restored. This chapter includes a discussion of the following:
- Debugger State
- Debugger Options
- Debugger Variables and Special Type Display
- Macro Preprocessing Support
- Target Environment Customization
- Terminal Control
Breakpoints and exceptions are discussed in Controlling Execution.
Debugger StateYou can save the debugger state across runs of the same program and for initializing the debugger state on a per-user and a per-program basis.
Debugger-state consists of the following:
- Values set using the View > Options command or set command.
- Debugger variables (View > Options values and predefined debugger variables such as $expand_pointers)
- User-defined debugger variables
- Macro definitions
- Type Display definitions
- Breakpoint settings
- Exception settings
Debugger State Files
The debugger looks for the initialization files listed in Table 17 when starting a debugging session. It is not mandatory that these files exist. Based on the existence of debugger state files, the debugger processes these files as described in Processing of State Files.
The state files contain debugger script commands that are read and executed by the debugger to set breakpoints, exception-handling requests, debugger options, and so forth. The syntax and semantics of this script language is fairly straightforward, and you are free to edit these files.
Note: Although you can edit these script files with a text editor, the script language is subject to change and is not supported or documented.
Processing of State Files
When you start debugging a program, the processing in Figure 7 occurs.
Figure 7 Processing State Files Algorithm
![]()
Commands for Saving and Restoring Debugger State
The following GUI commands are provided for saving and restoring the debugger state. The state command can be used in the Command Pane or non-GUI debugger.
- File > Debugger State > Clear Clear the debugger state: reset all View > Options option values to their defaults; reset all predefined debugger variables to their default values; delete all user defined debugger variables, macro definitions, type_display definitions, breakpoint settings, and catch/propagate settings
- File > Debugger State > Reset
resets the debugger state. This clears the debugger state and then runs the initialization process described in the previous topic.- File > Debugger State > Save saves the current debugger state. This command uses a dialog box that allows you to:
- Save the state in the use-state file.
- Save the state in the program-state file.
- Save the state in the user-specific program-state file.
- Save the state in a named file via a File Name field.
- Save the breakpoint settings
- Save the exception settings
- Save the user-defined debugger variables
- Save the macro settings
- Save the debugger options
- Save the type display settings
- File > Debugger State > Read invokes a dialog box that can read any particular state file. The dialog box has a text field for the filename to be read. The new state information is added on top of the existing state information.
- The state command, entered in either the Command Pane or the non-GUI debugger, also gives the users the ability to manage the debugger state and the debugger state files.
User-State Files
A user-state file is the debugger-initialization file for a particular user. You can save your personal preferences in a user-state file. For example, to propagate Constraint_Error by default when you debug any program with Apex:
- 1 . Begin debugging some program.
- 2 . Clear the debugger state by executing the File > Debugger State > Clear command.
- 3 . Set the exception to be propagated by executing the Debug > Propagate command. Enter Constraint_Error on the Exception line and make sure the Propagate diamond is selected.
- 4 . Save this setting by executing the File > Debugger State > Save command and select the Save Exceptions Setting entry.
- 5 . Save the debugger state in the user-state file by using the File > Debugger State > Save command.
Using a User-State File
When you start debugging a program, the user-state file is read according to the algorithm described in Processing of State Files.
You can also read any debugger file at any time during debugging using the File > Debugger State > Read. The new state information is added on top of the existing state information.
Program-State Files
A program-state file is the debugger-state file for a program. If there are particular exception requests, breakpoints, and debugger options that should be set by default for a particular executable. You can create a program-state file by following these steps:
- 1 . Start debugging the program.
- 2 . Execute the File > Debugger State > Clear command to clear the debugger state.
- 3 . Set the debugger state in the applicable dialog boxes to reflect the desired exception requests, breakpoint settings, debugger variables, macro and type display settings, and debugger options. For example, exception requests should be entered through the Exceptions window, breakpoints through the Breakpoints window, debugger options through the Options command, etc.
For example, if certain exceptions raised by a program do not signify errors, it may be convenient to propagate those particular exceptions by default.
- 4 . Choose the File > Debugger State > Save command to save the state in the program-state file. Make sure all the desired entries in this dialog box are selected before saving the state to a program-state file.
Using a Program-State File
When you start debugging a program, the program-state file is read according to the algorithm described in Processing of State Files.
You can also read any debugger-state file at any time during debugging using the File > Debugger State > Read. The new state information is added on top of the existing state information.
User-Specific Program-State Files
If there is more than one user debugging the same executable, each user can customize his or her individual debugging defaults for that executable by saving the desired state to the user-specific program-state file using the File > Debugger State > Save command. The steps are the same as those described in Using a Program-State File, except how to save to the user-specific program-state file.
Using a User-Specific Program-State File
When you start debugging a program, the program-state file is read according to the algorithm described in Processing of State Files.
Managing the Debugger State Using the State Command
The state command can be used to manage the debugger state either from the Command Pane in the debugger GUI or in the non-GUI debugger.
state
Syntax
state verb [flags] [state_file]
Arguments
- flags
Optional flags to the state command. Currently only the save verb has flags. These flags are listed in the Description below.
- state_file
Debugger state file. state_file is dependent on the verb which precedes it on the syntax line.
- verb
Action to be taken by the command. Valid values for verb are clear, delete, edit, read, reset, save, and show. These are described in the following section.
Description
The state command gives the user the ability to manage Debugger State and Debugger State Files (.dbrc files).
Note: := is allowed for assignment in all language contexts. In addition, // is allowed in all language contexts as a comment indicator. This allows multi-language programmers to assign debugger variables and have comments in their ~/.dbrc files, no matter what language the program they are debugging is written in.
The state_file parameter is required for the verbs delete, read, and save. It is optional for the edit verb and must be omitted for verbs clear, reset, and show.
The following verbs are available for use with this command:
- clear
Clear the debugger state: reset all set option values to their defaults; reset all predefined debugger variables to their default values; delete all user defined debugger variables, macro definitions, type_display definitions, breakpoint settings, and catch/propagate settings
- delete
Delete the specified state file. This verb also allows a state_file of the form "session all" which when specified, causes /tmp/*.ppid.dbrc" to be deleted.
- edit
Edit the specified state file. If no state file is specified, the debugger's current state is written to a temporary file which the user is allowed to edit. After exiting the editor, this temporary file is automatically read in by the debugger via the state read command after first doing a state clear.
- read
Read the specified state file.
- reset
The debugger state is cleared via state clear and then the debugger's state is reset by using the startup algorithm described above.
- save
Save the current debugger state to the specified file. The state save command can have an optional flags parameter of the form -ffff, where 'f' is one or more of the following characters: b, e, m, o, t, and v. The flags parameter specifies what portion of the debugger state to save If the flags parameter is omitted, all state is saved.
b Save breakpoint settings.
e Save exception settings.
m Save macro settings.
o Save debugger options.
t Save type_display definitions.
v Save user defined debugger variables.
- show
Show the current debugger state (as it would appear in a debugger state file).
Debugger OptionsYou can customize the debugger to suit your individual needs by setting debugger options. This can be done using either the debugger GUI View > Options command or the set command in the Command Pane or the non-GUI debugger.
Setting Debugger Options Using the View > Options Command
Selecting the View > Options command displays the Debugger Options dialog box. Through this dialog, you can set a number of debugger options (these options are part of the debugger state and can be saved using the File > Debugger State:Save command).
The available option categories are listed in Table 18. These are accessed by selecting Category on any of the options dialog boxes.
Source Display
When you select the View > Options command from any debugger window, the Debugger Options dialog box is displayed. This dialog box contains options relating to the display of source code, definition of search paths, and operations on the source code
Table 19 lists the options that are available from this dialog box.
Object Display
The Object Display Options dialog box is displayed by selecting the Object Display tab on the Debugger Options dialog box. These options control the display of objects and the format of entries on a number of the debugger windows.
Table 20 lists the options that are available from this dialog box.
Stack Display
The Stack Display Options screen is displayed by selecting the Stack Display tab on the Debugger Options dialog box.These options control the display of the call stack.
The following options are available from this screen.
Signals
The Signals dialog box is displayed by selecting the Signals tab on the Debugger Options dialog box.The Apex debugger provides a variety of methods for dealing with signals. The Signals dialog box contains a listing of each signal and the action the debugger will take when that signal is encountered. The following actions can be assigned to each signal:
- Break
When the signal occurs, it is announced and the program stops as if it reached a breakpoint
- Block
The debugger does not announce the signal but continues the program execution without reasserting the signal.
- Ignore
On /proc systems, the signal is passed to the program without debugger notification. 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.
The action of any signal can be changed by highlighting the signal line and then selecting one of the Change Action bars (Break, Block, Ignore) below the signal list.
The behavior of each signal is controlled separately, so as to ignore some and propagate others to the debugged program.
The behavior of two signals, ALRM and CONT, cannot be changed.
Exercise care in changing certain signal behaviors, since setting signal INT to Break would prevent interruption of the program by Control-C.
Logging
The Logging dialog box is displayed by selecting the Logging tab on the Debugger Options dialog box dialog box. The Logging dialog box allows you to start logging to a file. To enable logging of all commands and debugger output, select the Enable Logging option. If you wish the logging output to be written to a file, enter the debugger pathname of the file. If no file name is entered, logging is restarted to the log file most recently specified. To log only the debugger commands entered, select the Enable Command Logging button and enter the name of the desired file in which to store the commands.
Setting Debugger Options Using the set Command
The set command is used to set debugger options either from the Command Pane in the debugger GUI or in the non-GUI debugger.
set
Configuring the Debugger
The set command is used to establish debugger options. The simple command set, as well as the command set all, displays the current settings of all the options.
The set command can be used on a command line or supplied to the debugger at invocation using an invocation file.
The syntax of the set command is as follows:
set [option
[value
]]
In screen-mode, this command must be preceded with a colon (:) and followed by Return.
List of Debugger Options
The following options are available for the Apex debugger. Permissible settings for each option are shown in brackets following the option name. The default setting for the option is shown in brackets following the description of the option.
- alert_freq number
Update the alert message every number of instructions after the first warning. In screen mode, the number on the dashed line is updated. In line mode, a period (.) is displayed after each number of steps. [Default: 100]
- all
Print current settings of all set parameters (except signal, type_display, and run).
- async [on|off]
Force debugger to operate in asynchronous mode. If you switch to synchronous mode while the program is running (set async off), the debugger stops the program. [Default: off]
- attach_on_fork on|off
Enable debugging of both parent and child processes. When attach_on_fork is set to on, the debugger stops and announces the forking of a child process by the user's program. At this point, users can debug both the parent and child processes. When the child execs its own program, the debugger reads in the program's symbols and then stops and announces the exec(). At this point, users debug both the parent and child programs.
fork() calls called from system calls are ignored at all times.
Note: For the multi-exe debugger, attach_on_fork is process-specific. Users will need to enter set attach_on_fork after selecting each program to follow the fork.
When attach_on_fork is set to off, the debugger ignores all fork() and exec() system calls. [Default: off]
- bb [on|off]
Toggle breakpoint submode. If on, the screen mode 'set breakpoint' command is changed from b to bb. In screen mode, you may then use other two-character breakpoint commands, such as ba to list all breaks. [Default: off]
With bb on, these commands are available:
bb -- set a break at the current line
bc -- prompt for a condition or begin-end block
bi -- set a break at an address.
bl -- set a break at a line number
bo -- activate/deactivate a break at the current line
bs -- set a break at a subprogram name
bw -- prompt for a "when" statement
bx -- prompt for an exception name. If you hit the Return key, the debugger catches all exceptions.
When in screen mode, with bb on, note that you can activate and deactivate breakpoints with bo, rather than using boff and bon.
- break_spots [on|off]
Toggle display of break spots, icons which are displayed on every breakpointable line. In screen mode, break spots are periods ("."). [Default: on]
- case [on|off]
Make / and ? searches case sensitive. [Default: off]
- c_types [local|global]
Determine the scope of the search for C type declarations. local searches the current file and the include files for the type definition, global searches the entire executable and include files. While more comprehensive, use of global requires substantial additional time. [Default: local]
- cmd_log [on|off]
Determines if a commands file is saved when the user exits the debugger. The debugger saves all the commands issued by the GUI, user, and screen interface (rdb only) in a file called rdb.cmds.pid where pid is the PID of the debugger.
If cmd_log is set, the file is saved and the name of the file is announced when the debugger exits. If it is not set, the file is removed and no message is printed. If the debugger crashes, the file is saved, regardless of the cmd_log setting.
Users can then save this file to another file and invoke the debugger with this file to replay the last debug session.
%cp rdb.cmds.pid saved_cmd_file %rdb a.out < saved_cmd file
%cp rdb.cmds.pid saved_cmd_file %rdb a.out >read saved_cmd_file
The debugger attempts to open the rdb.cmds.pid file in the directory where the debugger is invoked. If that fails, the debugger checks for the TMPDIR environment variable. If it is set, the commands file is in $TMPDIR/rdb.cmds.pid. Otherwise, the debugger opens /tmp/rdb.cmds.pid.
- except_stack [on|off]
Save registers when performing exception unwinding. If off, the fast exception unwinding algorithms are in effect as it searches for an exception handler. However, if no handler is found, the debugger cannot determine what exception occurred or where it occurred. If on, the runtime system goes less fast but leaves more information for the debugger. [Default: on]
If except_stack is off (not being used) and no exception handler is found, a message indicates the debugger does not have enough information to find the line where the exception was raised.
If except_stack is on and no exception handler is found, additional information about the exception is available to the debugger.
- event [number]
Set the number of trace events to display in tl and tw commands.
- expanded_names [on|off]
Display fully expanded names instead of simple names. This effects:
- procedure/function names displayed by the cs, cd, cu, cb, ct, lb commands.
- task names displayed by the lt and task commands. (Ada)
- procedure/function names displayed in breakpoint announcements.
- names in some error messages.
- input [pty|tty||filename]
Set the input device for the program being debugged. If pty, the debugger passes input to your program. If tty, your program reads directly from the terminal If filename, your program reads from that file. [Default: pty]
- language [Ada | C | C++]
Specify the language of the program being debugged. The default is the language of the main program. Use this command to override this default. For all Apex cross systems, the main program must be an Ada program.
- lines number
Change the number of lines in the display produced by the l, li, w, and wi commands. number is decimal. [Default: 10]
- list_params[on|off]
Prevent/enable parameter display. When subprograms are displayed in cs and cd output, the debugger normally displays all of the subprogram parameters. Setting list_params to off prevents this display from occurring. [Default: on]
- log [off|filename]
Start logging to a file. If neither a file nor off is given, logging is restarted to the log file most recently specified. Note that you cannot set the log name to the same name as the rdb.cmds.pid file. [Default: off]
- measure [on|off]
When measure is set to on, a message is displayed after each breakpoint or step announcement giving the accumulated user and system CPU time of the process being debugged. This allows the user to measure the performance of pieces of code or called subprograms. This feature is only available in line mode for systems that use the /proc interface. [Default: off]
The first message looks like this:
--- usr: 00:13:81 sys: 00:00.7
All subsequent message look like this:
--- usr: 00:27.58 (00:13.77) sys: 00:00.7 (00:00.0)
The value in parentheses is the change from the previous line.
- memory address | range [r|w|rw] [cache|nocache] (Apex cross only)
Set permissions for memory at address or at the range of addresses indicated by <range>. <range> is denoted by <address .. address>).
set memory without arguments returns the current settings. set memory <address>| <range> with no permissions indicated (or with "--") protects that address or range of memory from both read and write.
These settings can prevent the debugger from writing on memory-mapped I/O ports.
Valid permissions are r (read), w (write) and rw (read/write).
In addition, for performance reasons, the debugger always tries to read at least 64 bytes when it reads memory. So if you type
> p ival
Where ival is a 32-bit integer starting at 0800020, the debugger will read up 64 bytes starting at 0800020 and keep this in a cache on the host. If subsequent reads of memory can be satisfied from the cache, they are.
The cache is flushed whenever the program is set in motion, for example, step commands, go commands, the r, and also the load and sync commands.
Control this caching behavior with the cache/nocache option to set memory. This setting can by used in addition to the memory range permissions above. For example,
% set memory 080000..088000 nocache
Nocache prevents the debugger from reading memory in 64-byte chunks and also from maintaining a copy of previously read memory on the host. When nocache is set on a range of memory, the debugger will read only the exact bytes that are required from this memory. If the above variable "ival" is in the memory range 080000..088000 then
number [on|off] Determine whether lines in the Source window (Screen Mode Operation only) are numbered. [Default: on]
obase number Set output number base for displaying commands to 8, 10 or 16. [Default: 10]
output [pty|tty||filename] Set output device for the program being debugged. If pty, output passes to the debugger. The debugger puts the output in the lower window. Write output from your program in your log file. If tty, output is written directly to the terminal, at the cursor. It is not logged.
overloaded_names[on|off] Prevent/enable overload analysis. When subprogram names are displayed in Call Stack and lb output, the debugger does overload analysis to append an 'n suffix to overloaded names. Setting overloaded_names to off prevents this analysis from happening and speeds up call stack output. Overloading is discussed in detail in Accessing Overloaded Objects. [Default: on]
page[on|off] Turn paging off or back on in the lower window of Screen Mode Operation. [Default: on]
persist [on|off] The debugger retains the previous file in the Source window when the current source file is not available. [Default: off]
prompt "new_prompt" Change the debugger prompt to the specified new_prompt, which must be in double quotes. [Default: >]
run shell_arguments Set up the invocation arguments for a program (I/O redirection, options, etc.) but do not start it. Without arguments, set run resets the arguments list to have no arguments. The next o, g, r, or s command restarts the program.
safe [on|off] Require certain single-letter commands (o, g, and r) to be typed twice in Screen Mode Operation for safety when debugging difficult constructs or when excessive line noise is experienced. [Default: off]
signal [signal_list|all] [b|g|gs] [in task] Set the listed signals to have the behavior specified by the last parameter. signal_list is a list of the standard signal numbers or names. (The command, kill -l prints a list of signal names.)
set signal without parameters shows the current setting for each signal. [Default: all b, except ALRM which is set to gs]
The set signal command is only valid on Native systems
The behavior of each signal is controlled separately so as to ignore some and propagate others to the debugged program.
The behavior of two signals, ALRM and CONT cannot be changed.
Exercise care in changing certain signal behaviors, since set signal INT g prevents interruption of the program by Control-C.
source path_list Establish the directory search path the debugger uses to find source files. path_list is a set of directory names, separated by spaces. [Default: current directory]
Append/prepend to the source list by referencing the variable $source in your set source command. For example:
set source $source /foo/bar set source /xyxxy/blue $source set source /xxx/yyy $source /zzz/aaa
The debugger expands environment variables in commands which reference file names. For example:
set source $HOME
stack_depth number Number of frames displayed when you display the Call Stack. [Default: 10]
step [fast|slow] (SGI native, x86, and Apex cross systems only) Increase single-stepping speed by sending a "step-in-range" message to the target. rather than a "step" message. This prevents the debugger from having to send a separate message to the target for each instruction when an s or o command is entered. For cross systems, only used on debuggers where TDM has the ability to single-step. [Default: fast]
step_alert number Print a message after a step (s) or step over (o) command steps number machine instructions. [Default: 1000]
tabs number Set the tab stop to number for listing source (l, li, w, wi and screen mode). [Default: 8]
task_id [on|off] Change the task display in the Task window (or in the output from the lt command) to show the strings that would be returned by the function Ada.Task_Identification.Image as specified in the Ada LRM section C.7.1.
For more information see "Task Names" in the Ada Runtime Guide.
trace options [on|off]
type_display [fully_rooted_type_name [begin command_list end] | off] Associate a type with a set of commands which are executed whenever the debugger is asked to display an object of that type. Without an argument set type_display displays the entire table of Type_Display settings. set type_display followed by a fully rooted type name lists the commands available for that type name. If the type name is followed by a command block, this will add a new type to the table or replace the command previously associated with the indicated type name. If off follows the type name, the type name is deleted from the table. More information can be found in Special Type Display.
value A valid setting for the option being set. These are listed with each option.
Description
set establishes various debugger parameters. The simple command set, as well as the command set all, displays the current settings of all the parameters except type_display.
Use set commands on a command line or supply to the debugger at invocation.
In Screen Mode
Precede this command with : and follow with Return.
Debugger Variables and Special Type DisplayYou can create a debugger string or integer variable using the define command. The debugger uses the initial value to set the type of the debugger variable. The define command has the following syntax
DEFINEname := value
where name must start with a $ and value must be a string or integer. For example,
DEFINE $message := |hit main breakpoint| DEFINE $year := 1995
These variables can be displayed, changed, or used as though they were normal language variables:
p $year $year <Assignment Operator> 1994 $year <Assignment Operator> $year + year_increment; P display_date($year, month, day)
These variables have no address or type, so that both of the following commands are illegal:
$year'address &year $year:a
The current list of user-defined debugger variables is displayed with the lv command. To display all debugger variables, including the debugger-defined functions (see Pseudo-Functions"), enter lv all.
Predefined Debugger Variables
Rational provides a set of predefined debugger variables. These can be displayed using the lv all command.
The following predefined debugger variables control the debugger's display of language expressions. They are:
- $display_levels
Governs the maximum level of nesting of data structures to which the debugger will descend before terminating the display of an expression. Each descent into an array, record, or pointer deference counts as a level of nesting. When the display level is exceeded, the debugger prints out "...". [Default: 4]
- $element_count
Specifies the maximum number of array elements (per dimension) that the debugger will display. [Default: 10]
- $expand_pointers
If $expand_pointers is not equal to 0, the debugger will automatically dereference pointers when it displays them and also display the object to which they point. [Default: 1]
For Apex Ada and Sienna C++ programs, pointers that point to a a structure of the same type as a containing structure will not be expanded. They are assumed to be the links in a linked data structure, such as a linked list. Any pointer can be manually expanded when viewed with the Object Display Window in the debugger GUI.
- $nested_type_display
If $nested_type_display is not equal to 0, the debugger will call the appropriate type_display routine for components of composite objects (for example, fields of a record, elements of an array). [Default: 1]
- $show_location
If $show_location is not equal to 0, the debugger will display the address of the object being displayed with the p command. [Default: 0]
- $type_display
If $type_display is not equal to 0, the debugger will use a type_display routine, if one is registered, when displaying an object with the p command. [Default: 1]
For example, suppose your program has the following type declarations:
type rec_type; type access_rec_type is access rec_type; type rec_type is record value: integer := 343; next: access_rec_type; more: integer := 216; end record;
When displaying an expression of type Access_Rec_Type using the default values for $expand_pointers and $display_levels, the output would look something like:
>p current 080a80 -> RECORD value: 10 next: 080a98 -> RECORD value: 9 next: 080ab0 -> RECORD ... more: 18 more: 20
The following predefined debugger variable is used for special type display:
- $variable
Has a value only during execution of the commands in the set type_display [fully_rooted_type_name [begin command_list end] | off] command list. You cannot change this variable directly; it takes on the identity of whatever object was selected by the P object command.
For example, suppose that variables day and yesterday are of type calendar.date. If you use the set type_display feature:
set type_display calendar.date begin p display_date($variable); end
and then ask the debugger to display the variables:
p day p yesterday
The debugger calls your Display_Date procedure as though you had typed:
p display_date(day) p display_date(yesterday)
Pseudo-Functions
There are several functions, which operate on $variable, or on other program variables:
- $pathname(object) returns string
Returns the full fully qualified name of object
- $declare_line(object) returns integer
Returns the line at which object was declared
- $declare_column(object) returns integer
Returns the column at which object was declared
- $declare_file(object) returns string
Returns the filename in which object was declared
- $string(string value|integer value) returns string
Transforms the output of a function to a string, which can then be passed to a user procedure.
- $name(variable) returns string
Returns the string which is the simple name of $variable. This function is used so that the user can pass the name of the current variable to a display procedure.
Note: The function $string(variable) attempts to turn the "value" of variable into a string, while $name(variable) returns the "name" of the variable.
- $type_of(variable) returns type
Returns the type of variable. variable must be an Ada or C/C++ object (Rational C/C++, not native C/C++).
User-Defined Debugger Variables
The define command should be used to create user-defined debugger variables.
define
Syntax
define $name := value
Arguments
- $name
$name can be any valid name, composed of letters, digits, and underscores. The first character must be a $. You may not choose a name which conflicts with one of the register names for your CPU. There is no limit on the number of debugger variables you can define. There is no scoping of debugger variables.
- value
The initial value for the debugger variable may be a string (a set of characters enclosed in double quotes), or a number. Integer variables are of type Long_Integer (32-bits on 32-bit hosts, 64-bit on 64-bit hosts). Strings are limited to 512 characters.
Description
You can create a debugger string or integer variable using the define command. The debugger uses the initial value to set the type of the debugger variable. For example, you can define a debugger integer variable:
define $i := 3
or a debugger string variable:
define $str := |any string|
You can redefine an existing debugger variable as long as the type remains the same:
define $str := |any other string|
or by using your language syntax, as with variables in your program's memory:
$i := $i + 1; $newstr := $str $newstr := |save this string|
List all debugger variables using the lv command:
lv
Print the value of a single variable using the p command, as you would any other variable:
p $i
and use the value in expressions as you would expect:
p $j + prog_var / 3
You can also pass these parameters to Ada or C/C++ user procedures:
p text_io.put_line($newstr) (Ada) p save_string (C/C++)
p print_integer($j)
Debugger variables can be used with Conditional Breakpoints to set a breakpoint which stops the program when it has hit the breakpoint a given number of times:
define $i := 0 b if $i = 20 then $i := 0 else $i := $i + 1; end
define $i = 0 b if $i == 20 then $i = 0 else $i = $i + 1; end
The breakpoint is announced after it's hit 20 times, and then $i is reset to 0.
Listing Debugger Variables
Debugger variables, both predefined and user-defined are listed using the lv command in either the Command Pane or in the non-GUI debugger.
lv
Syntax
lv [all]
Arguments
Description
You can create debugger string and integer variables using the define command. Then use lv to list all the debugger variables, with their values:
name value $i 03 $newstr |any other string| $str |any string|
Integer variables are displayed in the current base. Use the set obase number command to change the current base.
Special Type Display
You can associate a type with a set of commands which will be executed whenever you ask the debugger to display an object of that type.
This example assumes the following Ada code fragment:
with date; procedure example is y: date.year; yester_year: date.year; SET TYPE_DISPLAY date.year BEGIN P display_year($variable); END
p y
p yester_year
the debugger calls the procedure Display_Year with the correct value.
You can use the set type_display [fully_rooted_type_name [begin command_list end] | off] command as follows:
- set type_display
Displays the entire table of Type_Display settings.
- set type_display fully_rooted_type_name
Displays the commands for fully_rooted_type_name.
- set type_display fully_rooted_type_name
begin
command list
endAdds a new type to the table, or replaces the command previously associated with fully_rooted_type_name.
- set type_display fully_rooted_type_name off
Removes a previously-defined fully_rooted_type_name from the table.
The set type_display command does not currently check for a valid type, or for the existence of the display procedures being called. If the type is incorrectly spelled, or if type is not a fully-rooted name, you simply won't get a match when you attempt to print an object of that type. You can check the type of a given Ada object by using p object'type command.
If you have used set type_display to associate a type with a call to a display procedure in your program, and that display procedure does not exist, an error message is printed when you attempt to display the object.
If the type_name is matched, and the Display_Procedure does not exist, an error message is printed when you attempt to display the object.
When a type name is looked-up in the type_display table, the lookup is case insensitive for Ada, but is case sensitive for C and C++.
Basic C types and pointers to types are allowed in the set type_display command. For example:
set type_display unsigned int * begin ... end set type_display my_structure * begin ... end
The type entered in the type_display command should match the results of the $type_of() function for the given variable.
Macro Preprocessing SupportThe Apex debugger supports macro preprocessing as a mechanism to package a series of debugger commands and to parameterize those commands. The goal is to let the user create new commands by packaging debugger commands together and make that package appear like a single debugger command.
Preprocessor commands start and end macro definitions (Macro name and End Macro) and expand those definitions (by the appearance of a macro name).
The following debugger commands implement macro processing:
dm delete macros.
em edit macro
lm list macros.
pm print macro (do not execute)
All of these commands are case insensitive.
Macro Definition
A macro is defined as follows:
Macroname debugger command debugger command
... End Macro
The name of the macro cannot be the same as a debugger keyword that can appear at the beginning of a line. Thus, set is illegal while all is legal.
If text appears after the Macro name or End Macro, the debugger issues a warning and ignores the extra text.
After the debugger sees the Macro name, it changes the prompt to be the name of the macro being defined followed by the normal prompt. For example, if the debugger prompt is the default >, after seeing:
>macro pete
the debugger changes the prompt to:
pete>
The prompt is restored after the End Macro command.
If a Control-C is entered while entering the debugger commands in the macro body, the debugger abandons the macro definition and issues the normal command prompt.
Continuation lines are allowed. If the last non-blank, non-tab character of a macro line is a back slash (\), the next line is appended when the macro is expanded. Continuation characters on the last line of a macro are ignored.
Macro definitions with no commands are not allowed, but you can have macros with only comments in them.
You can't enter macro definitions if you're in screen mode.
Macro definitions can be put into an invocation file (.dbrc) or a debugger command file, but the definitions must be completed in the file. A macro definition cannot be started in .dbrc, for example, and finished interactively. For more details, see the section on the invocation file.
The debugger commands in a macro definition may reference parameters using the names $1, $2,... $9. See Macro Invocation for more information on parameters.
Macros cannot be defined within macro definitions.
It is also illegal to define recursive macros. These are macros which invoke themselves, or which invoke other macros which eventually invoke the macro being defined. This is checked as each line is entered. If the debugger detects recursion, it prints an error message containing the names of the macros in the recursive loop and rejects the line. The macro definition as a whole is not rejected, however. For example,
>macro fred fred>set fred>fred fred>lb fred>end macro
results in an error message on the second line of the macro. The macro is accepted by the debugger, as follows:
line 1:set line 1:lb
Macros can be invoked from debugger command files (using the read command) or from strings evaluated as debugger commands in the context of a pass command. Macros cannot be nested in this context, though, and read commands cannot be executed from a macro invocation or from a pass command. Note that the pass command is only applicable to embedded or cross systems.
Macro Invocation
name
[param1
[param2
[...]]]
The name of the macro is only recognized at the beginning of the line.
The scanning for parameters terminates at a newline.
When a macro is invoked, the debugger fully expands it before executing any of the commands within the expanded macro. If the macro being expanded invokes other macros, they are also expanded until the debugger has a set of commands which do not contain any macro invocations.
The debugger then executes these commands one at a time without echoing them.
This process stops when the set of commands is exhausted, a Control-C is hit, or one of the commands causes an error. This error could either be a syntax error or an error in command execution.
If the debugger encounters an error while executing a command from a macro expansion, it prints out the name of the macro from which the command was expanded and echoes the line which caused the error.
Macro invocations can appear in the invocation file, .dbrc or debugger command files.
Macro Invocation Parameters
Actual parameters are strings. An unquoted string parameter is terminated by a comma (,), space(s) ( ), or tab (^i). Multiple spaces can exist between parameters. A string parameter defined by double quotes (using the rules of Ada) is treated as a single parameter. It is terminated by the ending double quote. Prior to macro expansion, the outer double quotes are removed. For example, suppose the listem macro is defined as follows:
listem> lb $1 $2 $3
The following invocations are equivalent.
>listem 1,2,3 >listem 1 2 3 >listem 1, 2 3 >listem |1|2 3 >listem 1|2|,3
The listem macro is expanded as follows:
lb 1 2 3
It is also possible to pass strings that contain double quotes as macro parameters. Within a quoted string, a double quote is represented as two double quotes. For example:
"abc" gets passed as: abc
"a""bc" gets passed as: a"bc
"a"bc" causes an error message
"a""""bc" gets passed as: a""bc
"""" gets passed as: "Commas are necessary to indicate missing actual parameters from the macro invocation, unless only the trailing parameters are missing. For the following example macros:
foo - macro with three parameters baz - macro with four parameters
% foo one ,, three -- argument two is missing % baz one two,,four -- argument three is missing % foo ,two three -- argument one is missing % foo ,two,three -- argument one is missing % foo ,,three -- arguments one and two are missing % baz -- all four arguments are missing % baz one -- the last three arguments of baz are missing % baz one two -- the last two arguments of baz are missingIf a macro invocation refers to a parameter which does not appear in the actual parameter list, the debugger supplies the null string as the parameter unless a default value is provided. The definition of a macro can start off with default parameter values:
% macro foo % $1=33 -- default value for $1 is |33| % $2=xyz -- default value for $2 is |xyz| % begin % p name($1..$2) % end macro
The default value for a parameter is everything after the = up to (but not including) the end of line.
If default parameter values are given, then there must be a line with begin on it after the default values and before the actual body of the macro. If the keyword begin is omitted, the default parameter value assignments are interpreted as part of the macro.
When the actual parameters are expanded, the length of the line may increase. The expanded line cannot exceed the debugger's maximum line length, however (currently 1024).
em
Syntax
emname
Arguments
Description
The em command enables you to edit the macro defined by name.
em writes the text of the specified macro to a temporary file and invokes your default editor (using the environment variable "Editor") on it. After the editor is exited, the text of the file is read back in to the macro. If the named macro does not exist, a new macro is created.
pm
Syntax
pm name
Arguments
Description
The pm command expands a macro and prints out the expansion without executing its commands. For example, suppose you enter the macro break_at as follows:
>macro break_at break_at>/$1 break_at>b break_at>end macro
>pm break_at xyzzy
/xyzzy b
lm
Syntax
lm [name
] [ALL]
Arguments
Description
The lm command lists macros which have been defined. It has three forms.
lm with no parameter Lists the names of all currently defined macros
lm name Lists the complete text of the named macro
lm ALL Lists the complete text of all currently defined macros.
dm
Syntax
dm [name
] [ALL]
Arguments
Description
The dm command deletes macro definitions. dm name deletes the named macro while dm ALL deletes the definitions of all currently defined macros.
Target Environment CustomizationIt is possible to customize the target program environment using the env command from the Command Pane or the non-GUI debugger.
env
Customize target program environment
Syntax
env verb [param]
Arguments
- param
Variable or file name. param is dependent on the verb which precedes it on the syntax line.
- verb
Action to be taken by the command. Valid values for verb are set, unset, append, replace, edit and list.
Description
The env command in the debugger gives the user the ability to customize the environment of the target program. The following verbs are available for use with this command:
- set name=value
Set the environment variable name to value
- unset name
Unset the environment variable name
- append file
Add the file of environment variables indicated by file to the environment
- replace file
Replace the environment with the environment variables in the file indicated by file
- edit
- list
For entries in the file, the format is the format displayed by env command in the csh:
name=value
Any changes made to the environment do not effect the target program until it is rerun.
Terminal ControlNote: Terminal control is only applicable to the non-GUI Debugger
Description
The principal function of the set output command is to prevent the output of a program from overwriting the Source window when debugging in screen mode. If you use set output pty, output from your program prints in the lower window. If you use set output filename, output from your program writes to filename.
The debugger uses the pseudo terminal drivers (ptys) to position itself between the user terminal device and the process being debugged. set input and set output control this. If input is set to pty, the default standard input (file descriptor 0) for the user process is a pseudo terminal. Likewise, when output is set to pty, the default standard output (file descriptor 1) is the pseudo terminal, not the control terminal. The debugger does all terminal I/O on behalf of the process being debugged. When input or output is set to tty or to a file, the process being debugged has file descriptors for the actual terminal or file (assuming no I/O redirection is given with the r command).
If you are logging your debugging session and input is set to pty, all input to your program appears in the log. If output is set to pty, output from your program appears in the log.
The (default) use of ptys is transparent to most programs. However, when debugging a program that makes use of special video terminal features, this may not be desirable.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |