|
DataMuseum.dkPresents historical artifacts from the history of: Rational R1000/400 Tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about Rational R1000/400 Tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - downloadIndex: ┃ D T ┃
Length: 271366 (0x42406)
Types: TextFile
Names: »DEB_HELP«
└─⟦d10a02448⟧ Bits:30000409 8mm tape, Rational 1000, ENVIRONMENT, D_12_7_3
└─ ⟦fc9b38f02⟧ »DATA«
└─⟦f95d63c89⟧
└─⟦this⟧
@node !Commands.Debug
Package !Commands.Debug contains the specific types, subtypes, and
procedures provided by the Rational Environment debugger for interactive
use.
To use the facilities of the debugger from a program, see package
!Tools.Debug_Tools.
Note: These reference entries define the functionality of the package Debug
commands for the R1000 native debugger. However, this documentation can
also be used for reference with debuggers included in Rational's
cross-development facilities. Examples used in these reference entries
apply to the R1000 debugger, but they can also be used with CDF debuggers
in most cases.
RESOURCES IN PACKAGE DEBUG
The commands in package Debug fall into several functional groups. This
list includes all procedures in package Debug as well as selected types
and subtypes.
Selecting and terminating a debugger: Current_Debugger, Debug_Off, Kill
Displaying Ada program units: Display, Source
Displaying program state: Information, Information_Type, Stack
Displaying debugger state: Show
Handling variables: Modify, Put
Setting and removing breakpoints: Activate, Break, Remove
Handling exceptions: Catch, Exception_Name, Forget,
Propagate
Controlling tasks: Clear_Stepping, Execute, Hold, Kill,
Release, Run, Stop, Stop_Event
Naming tasks: Set_Task_Name, Task_Name
Displaying task status: Information, Information_Type,
Task_Category, Task_Display
Monitoring jobs: History_Display, Take_History,
Trace,
Trace_Event, Trace_To_File
Setting and resetting flags: Disable, Enable, Flag, Numeric,
Option,
Reset_Defaults, Set_Value
Setting contexts: Context, Context_Type
Displaying and translating machine values:
Address_To_Location, Convert,
Exception_To_Name,
Location_To_Address, Memory_Display
Displaying comments: Comment
COMMANDS FROM PACKAGE COMMON FOR THE DEBUGGER
Many commands from package !Commands.Common are supported for the debug-
ger. These commands are summarized in Table 9-1. Commands from package
Common typically are used through the key combinations to which they are
bound. For further information about these commands, see the Editing
Specific Types (EST) book, package Common.
Table 9-1 Commands from Package Common for the Debugger
---------------------------------------------------------------
| | |
|Key Bound To ... |Accomplishes ... |
---------------------------------------------------------------
| | |
|Common.Abandon |Deletes the debugger window if the debugger |
| |has been killed; otherwise, the command has |
| |no effect. This command has the same effect |
| |as the Release procedure. |
---------------------------------------------------------------
| | |
|Common.Create_ |Creates a command window below the current |
|Command |library window if one does not exist; |
| |otherwise, the procedure puts the cursor in |
| |the existing command window below the current|
| |library window. This command window initially|
| |has a use clause: |
| | |
| | use Editor, Common, Debug; |
| | |
| | |
| |This use clause provides direct visibility to|
| |the declarations in packages Editor, Common, |
| |and Debug without requiring qualification for|
| |names resolved in the command. |
---------------------------------------------------------------
| | |
|Common.Definition|Finds the Ada source of the designated |
| |element and brings up its image in a window |
| |on the screen, typically with the |
| |corresponding Ada source selected. |
---------------------------------------------------------------
| | |
|Common.Enclosing |Displays the library containing the command |
| |window from which the job being debugged was |
| |started. |
---------------------------------------------------------------
| | |
|Common.Object. |Selects a child element of the currently |
|Child |selected element. A child element is one of |
| |the elements at the next lower level, in a |
| |syntactic sense, from the currently selected |
| |element. If an object at that level has not |
| |been selected before, the smallest element |
| |enclosing the cursor is chosen. If an element|
| |at that level has been selected before, it is|
| |selected again. |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the first child of the currently |
|First_Child |selected element. The first child is the firs|
| |one of the set of elements at the next lower |
| |level, in a syntactic sense, from the cur- |
| |rently selected element. |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the last child of the currently |
|Last_Child |selected element. The last child is the last |
| |one of the set of elements at the next lower |
| |level, in a syntactic sense, from the cur- |
| |rently selected element. |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the Repeat next element past the |
|Next |currently selected element. A next element is|
| |the element at the same level, in a syntactic|
| |sense, as the current element that appears |
| |immediately after the current element. If no |
| |such selection can be made, the next element |
| |at the enclosing level is selected. |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the parent element of the currently |
|Parent |selected element. The parent element is the |
| |element that contains the current element at |
| |the next higher level, in a syntactic sense, |
| |from the current element. |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the Repeat previous element before |
|Previous |the currently selected element. A previous |
| |element is the element at the same level, in |
| |a syntactic sense, as the current element |
| |that appears immediately before the current |
| |element. If no such selection can be made, |
| |the previous element at the enclosing level |
| |is selected. |
---------------------------------------------------------------
| | |
|Common.Release |Deletes the debugger window if the debugger |
| |has been killed; otherwise, the command has |
| |no effect. This command has the same effect |
| |as the Abandon procedure. |
---------------------------------------------------------------
| | |
|Common.Write_File|Writes the current contents of the debugger |
| |window into the named file. |
---------------------------------------------------------------
@node !Commands.Debug.Activate
procedure Activate (Breakpoint : Natural);
DESCRIPTION
Activates a previously deactivated breakpoint.
Breakpoints reactivated with this command interrupt task execution at the
points at which they were initially set.
Note: When a job is being debugged, the breakpoints set in it are bound to
the Ada source of that job and persist in an inactive state beyond that
job unless they are removed. In subsequent jobs, previously defined
breakpoints can be activated.
PARAMETERS
Breakpoint : Natural;
Specifies which breakpoint to activate. A parameter value of 0 activates
all inactive breakpoints.
ERRORS
A breakpoint cannot be activated if the context in which it was created is
modified. For example, if the task to which the breakpoint applies does
not exist or the Ada unit with which it is associated has been modified
since debugging of the job began, the breakpoint is no longer valid. The
debugger displays both successful and failed breakpoint activations.
REFERENCES
procedure Break
procedure Remove
@node !Commands.Debug.Address_To_Location
procedure Address_To_Location (Address : String := "");
DESCRIPTION
Displays the source location corresponding to the address of the specified
machine instruction.
This command is the functional inverse of the Location_To_Address command.
PARAMETERS
Address : String := "";
Specifies the address of a machine instruction.
For the R1000 target, the address format is "#segment,#offset". The
segment value specifies the segment number in hexadecimal notation. The
offset specifies the location of the instruction in the segment. The pound
sign (#) is optional.
EXAMPLES
The following command:
Address_To_Location ("19901, 10")
displays:
Name: .PRODUCER_CONSUMER.QUEUE.1d
PC = #19901, #10
REFERENCES
procedure Location_To_Address
@node !Commands.Debug.Break
procedure Break (Location : Path_Name := "<SELECTION>";
Stack_Frame : Integer := 0;
Count : Positive := 1;
In_Task : Task_Name := "";
Default_Lifetime : Boolean := True);
DESCRIPTION
Creates a breakpoint at a specific location in the specified task.
A breakpoint interrupts execution of a task at a specified location (for
example, a statement or declaration) in the program source. The task stops
before the execution of the specified statement or declaration and the
debugger displays the breakpoint number and location. The task does not
resume execution until directed; the Run and Execute commands resume
execution of stopped tasks.
A breakpoint must be active to interrupt execution. Breakpoints are active
when created; they can be deactivated and reactivated at any time.
Breakpoints remain until they are deleted.
The Show (Breakpoints) command displays all breakpoints and their status.
Key Combinations
In the standard Environment keymap, the Break command with default values
is bound to a key combination. This binding provides several alternatives
for entering the command and specifying the location at which the
breakpoint is set:
* If the desired location appears on the screen, you can select the
location and press the key combination bound to the command. The
Location parameter resolves to the selected location.
* If the desired location is the first location in a specific stack frame,
you can press the numeric argument key corresponding to that frame and
then press the key combination bound to the command. The numeric
argument key specifies a value for the Stack_Frame parameter.
* If you want to specify the location explicitly, you enter the command
through a command window, filling in the Location parameter with either
an absolute or a relative pathname. You do not need to fill in the
Stack_Frame parameter; however, if you do, it will supplement a
relative pathname with the specified stack-frame number. (See the
Location parameter, below.)
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on designating locations.
Temporary and Permanent Breakpoints
Breakpoints can be either temporary or permanent. A temporary breakpoint
is deactivated after it interrupts the task. If the
Delete_Temporary_Breaks option flag is enabled, a temporary breakpoint is
deleted after it halts execution. The Permanent_Breakpoints option flag
determines the default type of breakpoints when they are created, and by
default it is enabled. However, whether or not Break applies the
Permanent_Breakpoints option flag depends on the value of the
Default_Lifetime parameter. If the Default_Lifetime parameter is set
to True (that is, it is enabled), the breakpoint is created with the
type of the Permanent_Breakpoints option flag. If the Default_Lifetime
parameter is set to False (that is, it is disabled), the breakpoint is
created with the opposite type of the Permanent_Breakpoints option
flag. The following table shows the possible combinations of this
option flag and parameter:
Breakpoint Type Interaction
---------------------------------
| | | |
| |Value of | |
|Permanent- |Default- |Break-|
|_Breakpoints |_Lifetime |point |
|Option Flag |Parameter |Type |
---------------------------------
| | | |
|True |True |Perman|
| | |ent |
---------------------------------
| | | |
|True |False |Tempor|
| | |ary |
---------------------------------
| | | |
|False |True |Tempor|
| | |ary |
---------------------------------
| | | |
|False |False |Perman|
| | |ent |
---------------------------------
If the Freeze_Tasks option flag is enabled when a breakpoint interrupts a
task, the debugger attempts to stop all tasks. The other tasks may not
actually stop because their current execution state may not allow it (for
example, they may be in rendezvous with the stopped task or waiting for
an entry call).
PARAMETERS
Location : Path_Name := "<SELECTION>";
Specifies the location at which the breakpoint is set. The location may be
an Ada program unit (a package, task, or subprogram), a frame reference, a
statement, or a declaration. By default, the value of Location is the
selected statement or declaration, but selections apply only if the
value of the Stack_Frame parameter is 0.
The value of Location can be an absolute pathname, a relative pathname, or
a special name that resolves to a designated location. The values of the
Location parameter and the Stack_Frame parameter together designate the
actual location at which the Break procedure creates a breakpoint.
These values define which parameter has precedence in determining the
breakpoint location, as shown in the following table:
Interaction of Location and Stack_Frame Parameters
------------------------------------
| | | |
| |Parameter |Parameter |
|If Location |Used |Used |
|Is: |If |If |
| |Stack_Frame|Stack_Frame|
| |= 0: |/= 0: |
------------------------------------
| | | |
|An absolute |Location |Location |
|pathname | | |
------------------------------------
| | | 1 |
|A relative |Location |Both |
|pathname | | |
------------------------------------
| | | |
|A special |Location |Stack2 |
|name | |Frame |
------------------------------------
1 If Location is a relative pathname and Stack_Frame is nonzero, Break
uses both parameters to designate a breakpoint location. The pathname
is prepended with _n., where n is the value of Stack_Frame. For example,
if the value of Stack_Frame is 3 and the value of Location is
"Commands.Filch", the pathname used is "_3.Commands.Filch".
2 If Location is a special name and Stack_Frame is nonzero, Stack_Frame
overrides Location and Break creates a breakpoint at the first location
in the frame specified by Stack_Frame.
If the Location parameter is null or an invalid selection reference, the
breakpoint is set in the first location in the current frame. If value of
Location cannot otherwise be resolved to a valid location, the debugger
reports an error.
The location cannot be a delay or terminate statement in a select
alternative or an entry declaration. If the location is a specific
instance of a generic, the break occurs only in that instance. If the
location specifies a generic definition, the break occurs in any
instance of the generic.
Stack_Frame : Integer := 0;
Specifies the stack frame in which to set a breakpoint. By default, this
parameter is ignored. Thus, this parameter is used only if it is nonzero
and if the value of the Location parameter is a relative pathname or a
special name. See the Location parameter for details.
Count : Positive := 1;
Specifies the number of times the statement in which the breakpoint is set
must be encountered in the execution of the program before the debugger
interrupts execution of the task. If Count = n, execution will be halted
just before the nth time the statement is executed. The default specifies
that the breakpoint interrupts execution the first time the statement is
encountered.
In_Task : Task_Name := "";
Specifies the task in which the breakpoint is set. The reserved name "all"
designates all tasks. The default value is the null string ("").
Breakpoints apply only to a specific task or to all tasks. If the value is
nonnull, In_Task designates the specified task. If null, In_Task designates
no specific task and the Break procedure chooses a default task based on
the control context:
* If the control context is set, the breakpoint is set for the task in
the control context.
* If the control context is not set, the breakpoint applies to all tasks,
including new tasks initiated after the breakpoint is set.
A breakpoint does not affect other tasks executing in the same location.
Default_Lifetime : Boolean := True;
Specifies whether the breakpoint is permanent or temporary. By default, the
breakpoint is permanent.
RESTRICTIONS
For the R1000 target, a maximum of 30 breakpoints can be set for specific
tasks. A maximum of 20 breakpoints can be set for all tasks. The two sets
are independent of each other. However, 16 active breakpoints of either
kind are accelerated; more than 16 active breakpoints slows execution.
EXAMPLES
When a breakpoint is triggered by a task, the debugger interrupts
execution and displays a status message. For example:
Break 2: .RECURSIVE_CALLS.3s [Task : ROOT_TASK, #674D8].
Breakpoint 2 deactivated.
The message specifies the breakpoint number, the location in which the task
stopped, and the task name. It also indicates that breakpoint 2 was
temporary and has been deactivated.
REFERENCES
procedure Activate
procedure Execute
type Option
subtype Path_Name
procedure Remove
procedure Show
subtype Task_Name
@node !Commands.Debug.Catch
procedure Catch (Name : Exception_Name := "<SELECTION>";
In_Task : Task_Name := "";
At_Location : Path_Name := "");
DESCRIPTION
Requests that the debugger halt task execution when a particular exception
is raised.
Propagate requests and catch requests combine to determine the action that
the debugger takes when an exception is raised. The debugger maintains a
list of catch and propagate requests entered by calls to the Catch and
Propagate procedures. When an exception in the user program is raised,
the debugger looks at this list to determine whether to stop the
program and inform the user. If the most specific request is a catch
request, the debugger halts execution; otherwise, it does not.
Specificity of Requests
More than one catch or propagate request can be in force simultaneously,
and when an exception is raised the debugger applies the most specific
request that includes the raised exception. The number and specificity of
parameter values determines the specificity of a catch request. More
precise parameter values supersede less precise values. The list below
defines the specificity order for each parameter:
* At_Location: A value that specifies a statement within a subprogram is
more specific than one that specifies only a subprogram. A value that
specifies a subprogram is more specific than one that specifies all
locations.
* In_Task: A value that specifies a task is more specific than one that
specifies all tasks.
* Name: A value that names an exception is more specific than one that
specifies implicit or all exceptions. A request that specifies implicit
exceptions is more specific than one that specifies all exceptions.
Note: The At_Location parameter supersedes the In_Task parameter, which
supersedes the Name parameter. For example, the debugger considers Catch
("All", "", "!TEST.DECONSTRUCT_NABOKOV") more specific than Catch ("All",
"34005", "").
By default, the debugger catches all exceptions (that is, the debugger
issues the equivalent of a Catch ("All","","") when started). Catching all
exceptions can be overridden with a propagate request that specifies either
individual or all exceptions. See the Propagate procedure for more details.
Matching Requests
If the parameters of a propagate request exactly match those of a catch
request, the debugger removes the catch request and applies the propagate
request. Otherwise, the Propagate command does not remove catch
requests. To remove a propagate or catch request, use the Forget command.
The Show (Exceptions) command displays all active catch and propagate
requests, ordered by specificity. The debugger lists the exception name,
location, and task restrictions for each request.
Interaction with Flags
If the Freeze_Tasks option flag is enabled when an exception is caught,
the debugger attempts to stop all tasks. The other tasks may not
actually stop because they may be in rendezvous with the stopped task or
waiting for an entry call.
If the Save_Exceptions option flag is enabled, the debugger retains catch
and propagate requests when the user begins debugging a new job. By
default, this option flag is disabled. See the Option type for more
details regarding option flags.
Unnamed Exceptions
Note: In some cases, the debugger cannot identify an exception. Exceptions
raised in Environment code, in code dissociated from its source (that is,
code from a code view or loaded main program), or in a unit modified since
debugger initiation may not be named. These exceptions are identified with
a hexadecimal number. They may also be identified with strings of the form
"<Unit=1234, Ord=2>" or "<Space=3, Index=234987>". The Information
(Exceptions) command displays details regarding all exceptions raised in
the debugger, including unnamed exceptions.
PARAMETERS
Name : Exception_Name := "<SELECTION>";
Specifies the exception to be caught by the request. The default value is
the name of the selected exception.
If the value of Name is the null string ("") or the reserved name "All",
the parameter identifies all exceptions. Also, if the value is a special
name (for example, "<SELECTION>") that cannot be resolved, the parameter
identifies all exceptions.
The reserved name "Implicit" identifies all exceptions raised implicitly
(that is, raised by a language construct other than a raise statement).
Implicit exceptions include only predefined exceptions such as
Constraint_Error and Tasking_Error.
If the exception name is not fully qualified, it is interpreted relative to
the current evaluation context.
Note: The debugger may use hexadecimal numbers to identify exceptions that
do not have names. This parameter accepts hexadecimal designations of
unnamed exceptions.
In_Task : Task_Name := "";
Specifies the task in which the exception will be caught. The reserved name
"All" designates all tasks. The default value is the null string ("").
Catch requests apply only to a specific task or to all tasks. If the value
is nonnull, In_Task designates the specified task. If the value is null,
In_Task designates no specific task and the Catch procedure chooses a
default task based on the control context:
* If the control context is set, the request applies to the task in the
control context.
* If the control context is not set, the request applies to all tasks,
including new tasks initiated after the request was issued.
Values for the In_Task parameter may be task synonyms created by
Debug.Set_Task_Name or Debug_Tools.Set_Task_Name. Task synonyms must be
prefixed with a percent symbol (%). Tasks may also be identified with task
numbers. If the task name is not fully qualified, the name is interpreted
relative to the current evaluation context.
At_Location : Path_Name := "";
Specifies the location in which the exception will be caught. This
parameter restricts the request to exceptions raised within the specified
location. If the pathname is not fully qualified, it is interpreted
relative to the current evaluation context. The default value is null,
which identifies all locations.
If the At_Location parameter specifies an Ada unit, the request applies
only to exceptions raised inside that unit. The request does not apply to
Ada units nested inside the selected unit (for example, procedures nested
within a package body, nested blocks, and accept statements).
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on designating locations.
RESTRICTIONS
The debugger allows a maximum of 40 catch and propagate requests.
EXAMPLES
Example 1
When the debugger catches an exception, it displays a status message:
Exception Constraint_Error caught at
.TEST_CASE.4s [Task : #1349704].
This includes the exception name, the exception location, and the name of
the task in which it was raised.
Example 2
A more specific request always supersedes a less specific one. A request
designating a single task, exception, or location takes precedence over
one designating all tasks, all exceptions, or all locations, respectively.
This applies to the interaction of catch and propagate requests:
Propagate (Name => "Constraint_Error",
In_Task => "All",
At_Location => "");
Propagate (Name => "All",
In_Task => "All",
At_Location => "!USERS.PHIL.TEST");
Catch (Name => "All",
In_Task => "1349704",
At_Location => "");
Any exceptions raised in !USERS.PHIL.TEST (the most specific request) do
not halt execution. The third request is more specific than the first, so
the Constraint_Error exception halts execution only if it is raised in
task 1349704; any other exception raised in task 1349704 also halts
execution.
Example 3
The name of an individual exception is considered more specific than the
reserved name "Implicit". The requests:
Catch (Name => "Implicit",
In_Task => "",
At_Location => "");
Propagate (Name => "Numeric_Error",
In_Task => "",
At_Location => "");
catch all implicitly raised exceptions other than Numeric_Error
exceptions.
Example 4
A request specifying a statement or declaration within an Ada unit is more
specific than a location specifying the entire Ada unit. The requests:
Catch (Name => "Status_Error",
In_Task => "",
At_Location => "Sandy.1");
Propagate (Name => "Status_Error",
In_Task => "",
At_Location => "Sandy");
catch Status_Error exceptions raised in the first statement of subprogram
Sandy, but they ignore Status_Error exceptions raised in the remainder of
the subprogram.
REFERENCES
subtype Exception_Name
procedure Forget
type Option
subtype Path_Name
procedure Propagate
procedure Show (Exceptions)
subtype Task_Name
@node !Commands.Debug.Clear_Stepping
procedure Clear_Stepping (For_Task : Task_Name := "");
DESCRIPTION
Removes all stepping conditions for the specified task.
Removing stepping conditions increases the speed of debugger execution.
PARAMETERS
For_Task : Task_Name := "";
Specifies the task for which stepping is canceled. The default value is the
null string (""), which resolves to the task specified by the current
control context. If the control context is not set to a specific task, the
parameter designates all tasks. The string "All" also represents all
tasks.
EXAMPLES
The command:
Clear_Stepping ("620E");
cancels all stepping conditions pending for task 620E.
REFERENCES
procedure Run
@node !Commands.Debug.Comment
procedure Comment (Information : String := "");
DESCRIPTION
Displays the value of the Information parameter in the debugger window.
The command can be used to place comments in the debugger window for anno-
tation of a debugging session.
PARAMETERS
Information : String := "";
Specifies the string displayed in the debugger window.
@node !Commands.Debug.Context
procedure Context (Set : Context_Type := Debug.Control;
To_Be : Path_Name := "<SELECTION>";
Stack_Frame : Integer := 0);
DESCRIPTION
Sets the specified context to the specified pathname.
By default, this command sets the control context to the selected item.
The debugger maintains two contexts: the control context and the
evaluation context. The debugger evaluates unqualified pathnames, task
names, and exception names in one of the two contexts. Context evaluation
does not apply to fully qualified pathnames, task names, or exception
names.
The following command displays the current control and evaluation
contexts:
Show (Contexts)
If the To_Be parameter specifies a selection, the command searches the
selection for a context in the stack for that selection. The Stack_Frame
parameter identifies the number of the frame that is the first search frame,
from which the command begins to search for a context. If Stack_Frame is
zero, the command substitutes the value of the Stack_Start flag. The
default value of Stack_Start is the first frame in the stack.
From the first search frame, the command searches a specific number of
frames, specified with the Stack_Count flag. The default number of search
frames is 10.
Control-Context Usage
The following table lists the manner in which various commands use the
control context:
Control-Context Usage
-----------------------------------------------
| | |
|Command |Control Context Used As: |
-----------------------------------------------
| | |
|Break |Default task to which the break is |
| |restricted. The control context also |
| |specifies which task's stack is used |
| |if the pathname in the command refers |
| |to a stack. |
-----------------------------------------------
| | |
|Catch |Task for which exception controls are |
| |set. |
-----------------------------------------------
| | |
|Clear_ |Default task for which stepping |
|Stepping|operations are canceled. |
-----------------------------------------------
| | |
|Display |Task whose stack is used if the |
| |pathname in the Display command refers|
| |to a stack. |
-----------------------------------------------
| | |
|Execute |Default task that is started. |
-----------------------------------------------
| | |
|Forget |Exception and task for which exception|
| |operations are cleared. |
-----------------------------------------------
| | |
|History_|Default task for which history |
|Display |information is displayed. |
-----------------------------------------------
| | |
|Hold |Default task that is held. |
-----------------------------------------------
| | |
|Propa- |Task for which exception controls are |
|gate |set. |
-----------------------------------------------
| | |
|Put |Task whose stack is used if the |
| |pathname in the Put command refers to |
| |a stack. |
-----------------------------------------------
| | |
|Release |Default task that is released. |
-----------------------------------------------
| | |
|Run |Default task for stepping. |
-----------------------------------------------
| | |
|Stack |Default task whose stack is displayed.|
-----------------------------------------------
| | |
|Stop |Default task that is stopped. |
-----------------------------------------------
| | |
|Take_ |Default task for which history |
|History |information is gathered. |
-----------------------------------------------
| | |
|Trace |Default task for which a tracing |
| |operation is enabled or disabled. |
-----------------------------------------------
The value of the control context can be the null string (""):
* For commands requiring a task designation, a null value defaults to all
tasks.
* For commands requiring a stack designation, a null value defaults to
the stack of the last task stopped by the debugger. Specifically, the
name of the last stopped task is used for interpreting pathnames in any
command.
* For certain commands (for example, Run and Stack), it is also the
default value for parameters designating tasks.
Evaluation-Context Usage
The following table lists the manner in which various commands use the
evaluation context:
Evaluation-Context Usage
----------------------------------------------
| | |
|Command|Evaluation Context Used As: |
----------------------------------------------
| | |
|Break |A context in which to interpret |
| |unqualified object names. |
----------------------------------------------
| | |
|Catch |A context for unqualified location and|
| |exception names. |
----------------------------------------------
| | |
|Context|A context for unqualified names for |
| |the control or evaluation context. |
----------------------------------------------
| | |
|Display|A context in which to interpret |
| |unqualified object names. |
----------------------------------------------
| | |
|Forget |A context for unqualified location and|
| |exception names. |
----------------------------------------------
| | |
|Modify |A context in which to interpret |
| |unqualified object names. |
----------------------------------------------
| | |
|Propa- |A context for unqualified location and|
|gate |exception names. |
----------------------------------------------
| | |
|Put |A context in which to interpret |
| |unqualified object names. |
----------------------------------------------
| | |
|Take_ |A context for unqualified location |
|History|names. |
----------------------------------------------
| | |
|Trace |A context for unqualified location |
| |names. |
----------------------------------------------
If a pathname is not qualified--that is, if it does not begin with a period
(.), underscore ( _ ), exclamation mark (!), dollar sign ($), double
dollar sign ($$), caret (^), or percent symbol (%)--the debugger prefixes
it with the evaluation context, using appropriate connecting punctuation.
PARAMETERS
Set : Context_Type := Debug.Control;
Specifies which context is set. The value can be either Control or
Evaluation.
To_Be : Path_Name := "<SELECTION>";
Specifies the value for the context. The default value is the context in
the selected item. By default, the value of To_Be is the selected item,
but selections apply only if the value of the Stack_Frame parameter is 0.
The null string ("") and the reserved name "All" are legal values for
To_Be, both of which identify all tasks.
The control context must be an Ada pathname to a task, a task number, or a
task synonym. The Debug.Set_Task_Name and Debug_Tools.Set_Task_Name com-
mands create task synonyms.
If the value of To_Be is not a task number, task synonym, or fully
qualified pathname, the Context procedure interprets it in the current
control or evaluation contexts as any other pathname. Context interprets
the pathname before defining the new value for the context; it uses the
current context to determine the new context.
The context must be valid both at the time it is specified and at the time
it is used. For example, an evaluation context of _4.X must be valid when
specified (frame 4 must exist and have an object X in it) and when it is
used (the Put ("Y") command is valid only when _4.X.Y exists).
The value of To_Be can be an absolute pathname, a relative pathname, or a
special name that resolves to an appropriate item. The values of the
To_Be parameter and the Stack_Frame parameter together designate the new
context. These values define which parameter has precedence in determining
the pathname, as shown in the following table:
Interaction of To_Be and Stack_Frame Parameters
------------------------------------
| | | |
| |Parameter |Parameter |
|If To_Be Is:|Used |Used |
| |If |If |
| |Stack_Frame|Stack_Frame|
| |= 0: |/= 0: |
------------------------------------
| | | |
|An absolute |To_Be |To_Be |
|pathname | | |
------------------------------------
| | | 1 |
|A relative |To_Be |Both |
|pathname | | |
------------------------------------
| | 2 | 3 |
|A special |To_Be |Both |
|name | | |
------------------------------------
1 If To_Be is a relative pathname and Stack_Frame is nonzero, the Context
procedure uses both parameters to designate the new context. The
pathname is prepended with _n., where n is the value of Stack_Frame. For
example, if the value of Stack_Frame is 3 and the value of To_Be is
"Commands.Filch", the pathname used is "_3.Commands.Filch".
2 If To_Be is a special name and Stack_Frame has the default value of
zero, Context searches the stack from the frame specified by the value of
the Stack_Start flag, the default value of which is also zero. Unless
either Stack_Frame or Stack_Start is set to a nonzero value, Context
searches from the first frame in the stack.
3 If To_Be is a special name and Stack_Frame designates a specific frame
(that is, it is nonzero), Context searches for the first occurrence of
the specified location in that frame and subsequent frames. Context
searches the number of frames specified by the Stack_Count numeric flag,
the default value of which is 10.
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on designating locations.
Stack_Frame : Integer := 0;
Specifies the stack frame that contains the context or that is the context.
By default, this parameter is ignored. Thus, this parameter is used only
if it is nonzero and if the value of To_Be is a relative pathname or a
special name. See the To_Be parameter for details.
RESTRICTIONS
The context pathname must be legal both when defined and when used by an-
other command.
EXAMPLES
The following sequence of commands shows the interaction of the control
and evaluation contexts as they are set with the Context command:
Context (Control, "%Session_Manager");
Stop;
Context (Evaluation, "_3.Session_Map");
The first command sets the control context to the specified task, evaluating
"%Session_Manager" as a task synonym. The Stop command stops the task
specified by the control context given in the first command. The next step
is to set an evaluation context based on the previously defined control
context. Since the control context is dynamic (that is, it may be assigned
to a different task at any time), the task assigned to the control context
must be stopped in order to interpret a pathname containing a stack
reference, such as _3.Session_Map, as the evaluation context. The third
command sets the evaluation context to the package Session_Map declared in
the subprogram running in stack frame 3 of the control-context task,
Session_Manager.
@node !Commands.Debug.Context_Type
type Context_Type is (Control, Evaluation);
DESCRIPTION
Defines the context types used by various debugger commands (specifically
the Context command).
ENUMERATIONS
Control
Specifies a task for use as the default task in commands that specify a
task.
Evaluation
Specifies a path prefix for unqualified pathnames in commands that require a
pathname.
REFERENCES
procedure Context
@node !Commands.Debug.Convert
procedure Convert (Number : String := "";
To_Base : Natural := 0);
DESCRIPTION
Converts the numeric string specified in the Number parameter to the base
defined by the To_Base parameter.
If To_Base is not specified, the command converts decimal numeric strings
to hexadecimal and other numeric strings to decimal.
This command uses 64-bit arithmetic.
PARAMETERS
Number : String := "";
Specifies the string representation of the number to be converted. Unless a
base is specified, the number is treated as a decimal representation. A
leading number symbol (#) indicates a hexadecimal number. The number and
base can also be specified in Ada style (for example, 8#177400#). Legal
bases are 2 through 16.
To_Base : Natural := 0;
Specifies the base to which the number is converted. Legal values are 2
through 16. The default value of To_Base depends on the value of the
Number parameter. If Number is decimal, To_Base is hexadecimal; otherwise,
To_Base is decimal.
@node !Commands.Debug.Current_Debugger
procedure Current_Debugger (Target : String := "");
DESCRIPTION
Designates the current debugger.
If there is more than one active debugger, this command designates which
one is the current debugger. All debugging commands are directed to the
current debugger.
This command applies to various targets with active debuggers in the
current session along with the R1000 native debugger. For more
information regarding each debugger, see the "Cross-Debugging" chapter of
the Cross-Development Facility User's Manual for the specific target.
PARAMETERS
Target : String := "";
Specifies the name of the debugger designated as current. The default value
is null.
If the value is the null string ("") and the cursor is in a debugger
window, the Current_Debugger procedure designates it as the current
debugger. If this command is invoked with a null value for Target and
the cursor is not in a specific debugger window, this command displays the
debugger window of the current debugger and moves the cursor into it.
@node !Commands.Debug.Debug_Off
procedure Debug_Off (Kill_Jobs : Boolean := False);
DESCRIPTION
Terminates debugging of the current job.
The job being debugged either continues normal execution or aborts, based
on the value of the Kill_Job parameter.
This Debug_Off command differs from the Debug_Tools.Debug_Off command,
which terminates debugging only if the task calling Debug_Tools.Debug_Off
is part of the job being debugged, and then it disables debugging only for
that task.
PARAMETERS
Kill_Job : Boolean := False;
Specifies, when True, that the job being debugged is aborted. If False, the
default value, the job continues normal execution.
REFERENCES
procedure Debug_Tools.Debug_Off
@node !Commands.Debug.Disable
procedure Disable (Variable : Option;
On : Boolean := False) renames Enable;
DESCRIPTION
Disables the option flag specified with the Variable parameter.
By default, this command disables the specified option flag. Disabling an
option flag sets it to False.
See the Option type for more information on the option flags.
PARAMETERS
Variable : Option;
Specifies the option flag that is to be enabled or disabled.
On : Boolean := False;
Specifies whether to enable or disable the option flag. If unspecified, the
option flag is disabled.
REFERENCES
procedure Enable
type Option
@node !Commands.Debug.Display
procedure Display (Location : Path_Name := "<SELECTION>";
Stack_Frame : Integer := 0;
Count : Natural := 0);
DESCRIPTION
Displays the specified source code with statement numbers in the debugger
window.
The length of the display is determined by the Count parameter.
The Location parameter references some location in the program or data.
The form and content of the display depends on the type of object
referenced by Location. See the description of the Location parameter,
below, for more details.
If the Location parameter refers to currently executing code, the asterisk
(*) or the pound sign (#) may appear next to statements and declarations
in the display:
* The asterisk identifies the statement now executing, or about to
execute, in the current task.
* The pound sign identifies statements or declarations executing in
subprogram frames other than the topmost frame.
Displays of source code include declaration and statement numbers used by
other commands (for example, Break and Task).
Displays of types include all characteristics of the type, even if the
type is private. Only private types declared in Environment code cannot be
displayed.
Note: For this command, the current task is the task specified by the
control context or the last task to stop if the control context is not
set.
The Declaration_Display option flag controls whether declarations are
shown as part of the display. By default, it is enabled, forcing
declaration displays. See the Option type for more details.
PARAMETERS
Location : Path_Name := "<SELECTION>";
Specifies a location in the source to display. The value of Location can be
the name of an Ada program unit (package, task, or subprogram), frame
reference, or a specific statement or declaration. All displays begin with
an initial statement or declaration and continue for the number of
statements, declarations, or combinations thereof specified by the Count
parameter.
If the value of the Location parameter is:
* An Ada program unit or frame reference, the initial statement or
declaration displayed is the first one in the program unit or frame,
respectively. Displays include both statements and declarations unless
the Declaration_Display option flag is disabled.
* A specific statement, that statement is the initial statement displayed
by the command and the display contains only statements.
* A specific declaration, that declaration is the initial declaration
displayed by the command and the display contains only declarations.
The value of Location can be an absolute pathname, a relative pathname, or
a special name that resolves to a designated location. The values of the
Location parameter and the Stack_Frame parameter together designate the
actual location displayed. These values define which parameter has
precedence in determining location, as shown in the following table:
Interaction of Location and Stack_Frame Parameters
------------------------------------
| | | |
| |Parameter |Parameter |
|If Location |Used |Used |
|Is: |If |If |
| |Stack_Frame|Stack_Frame|
| |= 0: |/= 0: |
------------------------------------
| | | |
|An absolute |Location |Location |
|pathname | | |
------------------------------------
| | | 1 |
|A relative |Location |Both |
|pathname | | |
------------------------------------
| | | |
|A special |Location |Stack2 |
|name | |Frame |
------------------------------------
1 If Location is a relative pathname and Stack_Frame is nonzero, the
Display procedure uses both parameters to designate a location. The
pathname is prepended with _n., where n is the value of Stack_Frame. For
example, if the value of Stack_Frame is 3, and the value of Location is
"Commands.Filch", the pathname that is used is "_3.Commands.Filch".
2 If Location is a special name and Stack_Frame is nonzero, then
Stack_Frame overrides Location and Display shows the source surrounding
the current statement or declaration in the frame specified by
Stack_Frame.
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on designating locations.
Stack_Frame : Integer := 0;
Specifies the stack frame displayed by this command. By default, this
parameter is ignored. Thus, this parameter is used only if it is nonzero
and if the value of the Location parameter is a relative pathname or a
special name. See the Location parameter for details.
Count : Natural := 0;
Specifies the number of statements, declarations, or combinations thereof
displayed. If Count is greater than the remaining length of the display
object, the display includes only the remainder of the object.
If the value of Count is 0 (the default), the command substitutes the
value of the Display_Count numeric flag. The default value of
Display_Count is 10. See the Numeric type for more details regarding
Display_Count.
RESTRICTIONS
This command cannot display code compiled without debug tables. The
Environment creates debug tables by default.
This command cannot display Environment code.
REFERENCES
procedure Context
type Numeric, enumeration Display_Count
type Option, enumeration Declaration_Display
procedure Source
procedure Debug_Tools.Register
@node !Commands.Debug.Enable
procedure Enable (Variable : Option;
On : Boolean := True);
DESCRIPTION
Enables the option flag specified by the Variable parameter.
By default, this command enables the specified option flag. Enabling an
option flag sets it to True.
See the Option type for more information on the option flags.
PARAMETERS
Variable : Option;
Specifies the option flag that is to be enabled or disabled.
On : Boolean := True;
Specifies whether to enable or disable the option flag. If unspecified, the
option flag is enabled.
REFERENCES
procedure Disable
type Option
@node !Commands.Debug.Exception_Name
subtype Exception_Name is String;
DESCRIPTION
Defines a string name for exceptions.
Several commands require specific names for exceptions. This subtype defines
the format of strings that denote a specific exception. There are three
legal forms for exception names, all of which are objects predefined by the
debugger:
* An Ada identifier evaluated in the current control or evaluation context
* A pathname
* A special name
The debugger also defines two inclusive values for this subtype:
* The null string ("") denotes all exceptions.
* The string "Implicit" denotes all exceptions raised implicitly.
Implicitly raised exceptions occur while executing a statement or
elaborating a declaration, not as the result of a raise statement.
Exception names that are special names resolve to contextual reference
designations (selection, image, cursor, and so on) defined by the
Environment. These special names have the form "<NAME>". If a special name
does not resolve to an exception (for example, if the special name is
"<SELECTION>" and the cursor is not in the selection), the value of the
exception name becomes the null string (""). That is, it designates all
exceptions. Special names are described in more detail in Parameter-Value
Conventions in the Reference Summary (RS) book.
The debugger resolves all predefined exception names as absolute values;
they are used with no qualification.
The following exception names are predefined in package Lrm.Standard:
Constraint_Error
Numeric_Error
Program_Error
Storage_Error
Tasking_Error
The debugger may display predefined exception names with an exception state
appended in parentheses. This state is a more exclusive index for an
exception, indicating its exact nature. The exception state, if one is
provided, is not part of the actual exception name; do not include it when
identifying an exception.
The following table includes the predefined exception names, states, and
operations that raise the exceptions:
Exception Descriptions
------------------------------------------------
| | |
|Exception Name |Description |
|(State) | |
------------------------------------------------
| | |
|Constraint_Error |Accessing an array element |
|(Array Index) |using a subscript that is |
| |out of the range of the |
| |array index type. |
------------------------------------------------
| | |
|Constraint_Error |Defining a case expression |
|(Case Range) |out of the bounds of the |
| |case statement. |
------------------------------------------------
| | |
|Constraint_Error |Accessing a field of variant|
|(Discriminant) |record that is not present |
| |in the specific record being|
| |accessed. |
------------------------------------------------
| | |
|Constraint_Error |Using an out-of-range |
|(Entry Family) |entry-family index. |
------------------------------------------------
| | |
|Constraint_Error |Raising an integer to a |
|(Exponent) |negative exponent. |
------------------------------------------------
| | |
|Constraint_Error |Concatenating beyond the |
|(Length Error) |upper bound of the index |
| |subtype. Refer to the |
| |Reference Manual for the Ada|
| |Programming Language, |
| |Section 4.5.3. |
------------------------------------------------
| | |
|Constraint_Error |Dereferencing a null |
|(Null Access) |pointer. |
------------------------------------------------
| | |
|Constraint_Error |Converting a value to a type|
|(Type Range) |that does not include the |
| |value in its range. |
------------------------------------------------
| | |
|Numeric_Error |Evaluating an expression |
|(Overflow) |that cannot be represented |
| |(for example, an |
| |uninitialized out |
| |parameter). |
------------------------------------------------
| | |
|Numeric_Error (Zero|Attempting to divide by |
|Divide) |zero. |
------------------------------------------------
| | |
|Program_Error |Accessing a program unit not|
|(Elaboration Order)|yet elaborated. |
------------------------------------------------
| | |
|Program_Error |Exiting a function by |
|(Function Exit) |executing past the last |
| |statement in the function. |
| |The last statement executed |
| |in a function must be a |
| |return statement. |
------------------------------------------------
| | |
|Program_Error |Executing an editor prompt |
|(Prompt Executed) |(for example, a [statement] |
| |prompt). |
------------------------------------------------
| | |
|Program_Error |Executing a select statement|
|(Select) |with no open alternatives. |
------------------------------------------------
| | |
|Storage_Error |(Reserved for future use.) |
|(Allocation) | |
------------------------------------------------
| | |
|Storage_Error |Nesting subprogram calls too|
|(Control) |deeply in a task. |
------------------------------------------------
| | |
|Storage_Error |Allocating too many objects.|
|(Data) |The Environment allocates |
| |a maximum amount of space |
| |for all objects designated |
| |by each access type; |
| |allocations beyond the |
| |maximum raise this |
| |exception. |
------------------------------------------------
| | |
|Storage_Error |Referencing too many objects|
|(Import) |from a package, task, or |
| |subprogram subunit. |
------------------------------------------------
| | |
|Storage_Error |Declaring too many tasks or |
|(Name) |packages. |
------------------------------------------------
| | |
|Storage_Error |Declaring an object greater |
|(Oversize Object) |than the maximum size |
| |allowed. |
------------------------------------------------
| | |
|Storage_Error |Executing an oversize job. |
|(Program) | |
------------------------------------------------
| | |
|Storage_Error |Queuing too many outstanding|
|(Queue) |entry calls for a task. |
------------------------------------------------
| | |
|Storage_Error |(Reserved for future use.) |
|(Resource) | |
------------------------------------------------
| | |
|Storage_Error |Defining too many types. |
|(Type) | |
------------------------------------------------
| | |
|Tasking_Error |Rendezvousing with an |
|(Abnormal Task) |aborted task. |
------------------------------------------------
| | |
|Tasking_Error |Propagating an exception out|
|(Activation) |of a child task during its |
| |activation. |
------------------------------------------------
| | |
|Tasking_Error |Accessing a terminated task.|
|(Completed Task) | |
------------------------------------------------
REFERENCES
procedure Catch
procedure Forget
subtype Path_Name
procedure Propagate
@node !Commands.Debug.Exception_To_Name
procedure Exception_To_Name (Implementation_Image : String := "");
DESCRIPTION
Displays the source name of the exception that corresponds to the specified
target-dependent representation.
The debugger may not know the name of an exception when it is raised. This
command attempts to determine a name for the exception identified by the
Implementation_Image parameter.
PARAMETERS
Implementation_Image : String := "";
Specifies a target-dependent representation of an exception.
For the R1000 target, the representation format is "#segment,#offset". The
segment value specifies the segment name of the memory space containing the
exception, in hexadecimal notation. The offset specifies the location of
the exception in the segment. The offset can be either decimal or
hexadecimal, with values preceded by the character # or containing the
letters a-f interpreted as hexadecimal.
A predefined exception can be specified by its exception number, either by
itself or with an address of 0 (that is, "0, exception number").
The representation can be in the form in which any exception is displayed
in the Environment.
Note: The debugger may use hexadecimal numbers to identify exceptions that
do not have names. This parameter accepts hexadecimal designations of
unnamed exceptions.
EXAMPLES
Entering this command with parameter values that specify a predefined
exception:
Exception_To_Name ("0,78");
produces the following display:
Exception_To_Name ("0,78");
Name: Predefined exception STORAGE_ERROR
REFERENCES
procedure Catch
@node !Commands.Debug.Execute
procedure Execute (Name : Task_Name := "");
DESCRIPTION
Initiates execution of the named task.
This command initiates execution from the current location in the named
task. The current location is the last statement executed in the named
task, usually the point at which execution is halted because:
* A breakpoint is encountered
* A Stop command is executed
* A Hold command is executed
* An exception is caught by the debugger
* The termination condition of a Run command is encountered
If the named task is already executing, the command has no effect.
Tasks subject to hold conditions must be started individually by name, or
the hold condition must be released with the Release command. Issuing an
Execute command for all tasks (Execute ("All")) releases only tasks not
specifically held by the debugger.
If the Freeze_Tasks option flag is enabled and all tasks are stopped
implicitly as a result of an individual task being stopped, the Execute
command resumes execution of these implicitly stopped tasks.
PARAMETERS
Name : Task_Name := "";
Specifies the task to be executed. The default value is the task specified
by the current control context. If the control context is not explicitly
set, execution resumes for all tasks not specifically held by the
debugger.
The reserved word "All" specifies all tasks not held by the debugger.
See the Hold command for more information on the held state.
ERRORS
The debugger displays No tasks are stopped when no tasks are currently
stopped in the debugger or when the stopped tasks are subject to hold
conditions.
REFERENCES
procedure Break
procedure Hold
procedure Release
procedure Stop
@node !Commands.Debug.Flag
procedure Flag (Variable : String := "";
To_Value : String := "TRUE");
DESCRIPTION
Sets the value of debugger flags.
Flags in the debugger control certain functions and provide special
facilities. The Variable parameter specifies the name of the flag and the
To_Value parameter specifies its value. The debugger ignores case when
evaluating flag names.
Legal flag names for this command include string names for the enumeration
values defined by the Option and Numeric types, as well as the following
predefined string flags (some of these flags are intended for internal use
only and are not supported by Rational):
Predefined String Flags
--------------------------------------------------------------
| | | | |
|Flag Names |Description |Default |Status |
| | |Value | |
--------------------------------------------------------------
| | | | |
|Cache_Stack_ |Maintains a cache of current |True |Unsuppo|
|Frames |stack information for the | |rted |
| |current task. Disabling this | | |
| |flag impairs some debugger | | |
| |operations. | | |
--------------------------------------------------------------
| | | | |
|Flag_Errors |Includes the string *** in |False |Support|
| |error messages. | |ed |
--------------------------------------------------------------
| | | | |
|Hex_Values |Forces hexadecimal output from |False |Support|
| |the Put command for certain | |ed |
| |values. | | |
--------------------------------------------------------------
| | | | |
|Interpret_ |Forces the Memory_Display |False |Unsuppo|
|Import_Words |command to interpret words in | |rted |
| |the import space. | | |
--------------------------------------------------------------
| | | | |
|Interpreter_ |Displays the contents of the |False |Unsuppo|
|Dump |interpreter stack after each | |rted |
| |instruction executed by the | | |
| |interpreter. | | |
--------------------------------------------------------------
| | | | |
|Interpreter_ |Prints information about |False |Unsuppo|
|Trace |execution of interpreted code | |rted |
| |used to do object displays. | | |
--------------------------------------------------------------
| | | | |
|No_Pointers |Prevents display of actual |False |Support|
| |pointer values. The value ppppp| |ed |
| |displays for all pointers. | | |
--------------------------------------------------------------
| | | | |
|No_Task_ |Prevents display of actual task|False |Support|
|Numbers |numbers. The value xxxxx | |ed |
| |displays for all tasks. | | |
--------------------------------------------------------------
PARAMETERS
Variable : String := "";
Specifies the name of the flag to be set.
To_Value : String := "TRUE";
Specifies the value to which the flag is set. The default value is True.
ERRORS
The debugger does not check for errors in flag names or values. Illegal
values can cause unexpected behavior in operations that depend on flag
values.
REFERENCES
type Numeric
type Option
@node !Commands.Debug.Forget
procedure Forget (Name : Exception_Name := "<SELECTION>";
In_Task : Task_Name := "";
At_Location : Path_Name := "");
DESCRIPTION
Removes catch and propagate requests.
By default, this command removes catch and propagate requests for the
selected exception in all tasks and locations.
A Forget command removes catch and propagate requests matching the
parameter values of the command. The debugger does not apply Forget
commands in order of specificity as it does catch and propagate requests.
Exceptions must be explicitly named for this command. An undefined value
for the Name parameter (for example, the null string) results in an error
instead of designating all exceptions (the standard functionality in the
debugger).
Note: A Forget command that applies to all exceptions in all tasks and
locations does not clear every catch and propagate request active in the
job currently being debugged. Either a Catch ("All") or a Propagate
("All") command is always active in the debugger and cannot be removed
with the Forget command.
PARAMETERS
Name : Exception_Name := "<SELECTION>";
Specifies the exception for which catch and propagate requests are removed.
The reserved name "All" selects all types of exceptions.
Note: The null string ("") is not a valid value for Exception_Name.
The reserved name "Implicit" identifies all exceptions raised implicitly
(that is, raised by a language construct other than a raise statement).
Implicit exceptions include only predefined exceptions such as
Constraint_Error and Tasking_Error.
Note: The debugger may use hexadecimal numbers to identify exceptions that
do not have names. This parameter accepts hexadecimal designations of
unnamed exceptions.
In_Task : Task_Name := "";
Specifies the task to which the request is limited. The reserved name "All"
selects all tasks. The default value is null.
Forget requests apply only to a specific task or to all tasks. If the value
is nonnull, In_Task designates the specified task. If the value is null,
In_Task designates no specific task and the Forget procedure chooses a
default task based on the control context:
* If the control context is set, the request applies to the task in the
control context.
* If the control context is not set, the request applies to all tasks.
Values for the In_Task parameter can be task synonyms created by
Debug.Set_Task_Name or Debug_Tools.Set_Task_Name. Task synonyms must be
prefixed with a percent symbol (%). Tasks can also be identified with task
numbers. If the task name is not fully qualified, the name is interpreted
relative to the current evaluation context.
At_Location : Path_Name := "";
Specifies the location to which the request is limited. This parameter
restricts the command to exceptions raised within the specified location.
If the pathname is not fully qualified, it is interpreted relative to the
current evaluation context. The default value is null, which identifies
all locations.
If the At_Location parameter specifies an Ada unit, the command applies
only to exceptions raised inside that unit. The command does not apply to
Ada units nested inside the selected unit (for example, procedures nested
within a package body, nested blocks, and accept statements).
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on designating locations.
REFERENCES
procedure Catch
procedure Propagate
procedure Show (Exceptions)
@node !Commands.Debug.Hex_Number
subtype Hex_Number is String;
DESCRIPTION
Limits a string representation to numeric values in base 16.
Note: All values of this subtype are interpreted as hexadecimal numbers;
values of this type need not be prefixed with "16#".
@node !Commands.Debug.History_Display
procedure History_Display (Start : Integer := 0;
Count : Integer := 0;
For_Task : Task_Name := "");
DESCRIPTION
Displays history entries for the specified task.
The debugger keeps an execution history for tasks when history logging is
enabled with the Take_History command. This history includes entries
regarding statements, calls, rendezvous, and exceptions. The
History_Display procedure selects sets of entries associated with a
specific task. By default, the command displays the ten most recent entries
for the specified task.
Unlike traces, history entries are saved in a circular buffer. That is,
the most recent events selected by the Take_History command are recorded
by the debugger in a buffer. When the buffer becomes full, the oldest
events are overwritten by new events. History_Display identifies entries in
this buffer relative to the most recent entry (see the Start parameter,
below).
PARAMETERS
Start : Integer := 0;
Specifies the starting entry (that is, the first entry displayed) for the
history display. For the default value of 0, this parameter substitutes
the value of the History_Start numeric flag, the default value of which is
10.
A positive value specifies the first event to be displayed, numbered
starting from the most recent entry. A negative value specifies the first
entry to be displayed, numbered starting from the oldest entry. If Start=
-20, the first entry displayed is the twentieth oldest event recorded in
the buffer.
Count : Integer := 0;
Specifies the number of entries displayed. For the default value of 0, this
parameter substitutes the value of the History_Count numeric flag, the
default value of which is 10.
The sign of the Count parameter determines which entries and in what order
they are displayed:
* If the value of Count is positive, History_Display displays the entries
succeeding the starting entry. The entries are displayed in order from
the oldest to the newest entry.
* If the value of Count is negative, History_Display displays the entries
preceding the starting entry. The entries are displayed in order from
the newest to the oldest entry.
The number of entries displayed, however, is always the absolute value of
the Count parameter (that is, History_Display disregards the sign of the
value in determining the length of the display). That is, if Start = 20
and Count = -10, the twentieth through twenty-ninth events are displayed
in order from newest to oldest.
For_Task : Task_Name := "";
Specifies the task for which this command displays history entries. If the
value is null, this parameter defaults to the task specified by the control
context. If the control context does not identify a specific task, the
command applies to all tasks.
EXAMPLES
The following is an example of a history display:
History of statements executed by all tasks : (oldest .. newest)
Timestamp Depth Location and Task
34656136386 2 .BUFFER.LENGTH.1d [QUEUE, #2F0D4]
+ 284 1 .PRODUCER_CONSUMER.CONSUMER.5s [CONSUMER, #2F8D4]
+ 522 2 .BUFFER.LENGTH.2d [QUEUE, #2F0D4]
+ 1136 2 ....1s
+ 1435 2 ....2s
+ 1705 1 .PRODUCER_CONSUMER.QUEUE.7s
+ 1992 1 ....8s
34657416781 1 .PRODUCER_CONSUMER.PRODUCER.3s [PRODUCER, #2F4D4]
34657816737 1 .PRODUCER_CONSUMER.CONSUMER.3S [CONSUMER, #2F8D4]
34658504120 1 .PRODUCER_CONSUMER.QUEUE.9s [QUEUE, #2F0D4]
* The first line describes the selection and order of history entries. In
this case, the statements from all tasks are displayed, from the oldest
entry to the newest entry. The second line lists the column headings.
* The first column is a measure of time in units of 3.2 microseconds.
* The second column is the stack depth of the task associated with that
entry.
* The third column is the name of that task.
* The last column specifies the statement or declaration that the named
task is executing.
Succeeding lines are individual history entries. The display truncates
succeeding statement and declaration names if they are identical. Elipses
(....) indicate name truncations.
Note: The debugger requires 280-300 time units (896-960 microseconds) to
record each entry in the history.
The previous display includes entries for multiple tasks. Limiting the
search to entries for task QUEUE, the command displays:
History of statements executed by QUEUE, #2F0D4 : (oldest .. newest)
Timestamp Depth Location
34656135064 2 .PRODUCER_CONSUMER.QUEUE.(accept GET).2s
+ 274 1 .PRODUCER_CONSUMER.QUEUE.4s
+ 714 1 ....7s
+ 1322 2 .BUFFER.LENGTH.1d
+ 1844 2 ....2d
+ 2458 2 ....1s
+ 2757 2 ....2s
+ 3027 1 .PRODUCER_CONSUMER.QUEUE.7s
+ 3314 1 ....8s
34658504120 1 ....9s
The task is identified in the first line, not in each entry. The command
also searches earlier in the history to select the ten most recent events
for task QUEUE.
REFERENCES
type Numeric
procedure Take_History
procedure Trace
type Trace_Event
@node !Commands.Debug.Hold
procedure Hold (Name : Task_Name := "");
DESCRIPTION
Stops execution of the specified task.
This command halts the specified task until it is explicitly released. You
can release a task using:
* A Release command that specifies the held task or all tasks
* An Execute or Run command that explicitly names the held task
The Execute ("All") and Run ("All") commands do not release tasks held by
this command.
The debugger displays a status message for each held task.
A hold takes effect after the current statement executes in the specified
task, as in the Stop command. Rendezvous, delays, and complex statements
complete before a hold takes effect.
If the Freeze_Tasks option flag is enabled, the debugger attempts to stop
all other tasks when any one task is stopped. The other tasks may not
actually stop because they may be in rendezvous with the stopped task,
waiting for an entry call, or otherwise blocked.
If the specified task is already held, this command has no effect.
The Hold command allows exclusion or inclusion of tasks from the normal
set of tasks running in a program. Tasks operating incorrectly (for
example, creating errors) may be held and the program allowed to continue
without their interference. Alternatively, the Hold ("All") command
followed by Execute commands specifying certain tasks causes execution to
be limited to those specified tasks while all others remain held.
PARAMETERS
Name : Task_Name := "";
Specifies the task to be held. The default value is the task specified by
the current control context. If the control context is not explicitly set,
the default value is all tasks.
The string "All" specifies all tasks.
REFERENCES
procedure Execute
procedure Release
procedure Run
procedure Stop
@node !Commands.Debug.Information
procedure Information
(Info_Type : Information_Type := Debug.Exceptions;
For_Task : Task_Name := "");
DESCRIPTION
Lists information about the specified task.
By default, the Information procedure lists exception names and locations
for all tasks.
The type of information displayed by this command depends on the type
specified by the Info_Type parameter. See the "Parameters" section, below,
for the format of each information type.
Enabling the Addresses option flag augments the information displayed by
this command. See the description in the "Parameters" section, below.
PARAMETERS
Info_Type : Information_Type := Debug.Exceptions;
Specifies the type of information listed by the command. The default value
is Exceptions.
For these values for Info_Type, the Information procedure displays the
following:
* If Info_Type specifies Exceptions, the Information command displays the
exception name and location of each active exception in the specified
task. An exception is active if the task is still executing code in
the handler for that exception. If the Addresses option flag is
enabled, Information also displays the program counter value, actual
exception name, and control offset of the exception.
Note: The control offset of the exception is Environment information
that contains the actual exception information. This information
generally is useful only in diagnosing system problems.
* If Info_Type specifies Rendezvous, the Information command lists the
partner name for each rendezvous currently in progress. A rendezvous is
in progress if the task is currently executing an accept statement for
an entry. If the Addresses option flag is enabled, Information also
displays the control offset of the task linkage.
* If Info_Type specifies Space, the Information command lists the current
and maximum allocations for the control and data memory spaces. If the
Addresses option flag is enabled, Information also displays the size of
each address space.
For_Task : Task_Name := "";
Specifies the task for which information is displayed. The default value is
the task specified by the current control context. If the control context
is not set to a specific task, the parameter designates all tasks.
REFERENCES
type Information_Type
type Option
@node !Commands.Debug.Information_Type
type Information_Type is (Exceptions, Rendezvous, Space);
DESCRIPTION
Defines the type of information displayed by various debugger commands
(specifically the Information procedure).
ENUMERATIONS
Exceptions
Specifies information about exceptions active in the specified task.
Rendezvous
Specifies information about current rendezvous in the specified task.
Space
Specifies information regarding memory space consumed by the specified task.
@node !Commands.Debug.Kill
procedure Kill (Job : Boolean := True;
Debugger : Boolean := False);
DESCRIPTION
Kills the current job, the current debugger, or both.
By default, this command kills the current job but not the debugger
itself. It is not necessary to kill the debugger if the current job
terminates or is killed.
You should not kill the debugger unless it is functioning abnormally.
Because the Environment will reuse the debugger if possible, you will save
time by keeping the debugger active instead of killing and restarting the
debugger for each job you debug.
You can kill the debugger and allow the current job to continue, but this
is not recommended. The safest method is to turn off debugging with the
Debug_Off (Kill_Job => False) command, which allows the current job to
finish, and then kill the debugger with a kill command.
PARAMETERS
Job : Boolean := True;
Specifies whether to kill the job currently being debugged. If True, the
job is killed. If False, this command should have no effect on the job
being debugged. The default value is True.
Debugger : Boolean := False;
Specifies whether to kill the debugger for the current session. If True,
the debugger is killed. The default value is False.
@node !Commands.Debug.Location_To_Address
procedure Location_To_Address (Location : Path_Name := "<SELECTION>";
Stack_Frame : Integer := 0);
DESCRIPTION
Displays the memory address for the machine instruction corresponding to
the specified location.
For the R1000 target, the format of memory addresses is
"#segment,#offset". The segment value specifies the segment number in
hexadecimal notation. The offset specifies the location of the instruction
in the segment.
This command is the functional inverse of the Address_To_Location command.
PARAMETERS
Location : Path_Name := "<SELECTION>";
Specifies the location for which the command returns the corresponding
memory address. A location can be an Ada program unit (a package, task, or
subprogram), a frame reference, a statement, or a declaration. By default,
the value of Location is the selected statement or declaration, but
selections apply only if the value of Stack_Frame is 0.
The value of Location can be an absolute pathname, a relative pathname, or
a special name that resolves to a designated location.
The values of the Location parameter and the Stack_Frame parameter
together designate the actual location to which this command applies.
These values define which parameter has precedence in determining the
location, as shown in the following table:
Interaction of Location and Stack_Frame Parameters
------------------------------------
| | | |
| |Parameter |Parameter |
|If Location |Used |Used |
|Is: |If |If |
| |Stack_Frame|Stack_Frame|
| |= 0: |/= 0: |
------------------------------------
| | | |
|An absolute |Location |Location |
|pathname | | |
------------------------------------
| | | 1 |
|A relative |Location |Both |
|pathname | | |
------------------------------------
| | | |
|A special |Location |Stack2 |
|name | |Frame |
------------------------------------
1 If Location is a relative pathname and Stack_Frame is nonzero,
Location_To_Address uses both parameters to designate the location. The
pathname is prepended with _n., where n is the value of Stack_Frame. For
example, if the value of Stack_Frame is 3 and the value of Location is
"Commands.Filch", the pathname used is "_3.Commands.Filch".
2 If Location is a special name and Stack_Frame is nonzero, Stack_Frame
overrides Location, and Location_To_Address returns the address of the
first location in the frame specified by Stack_Frame.
If the Location parameter is null or an invalid selection reference, this
command returns the address of the first location in the current frame. If
the value of Location cannot otherwise be resolved to a valid location,
the debugger reports an error.
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on designating locations.
Stack_Frame : Integer := 0;
Specifies the frame for which the command returns the corresponding memory
address. By default, this parameter is ignored. Thus, this parameter is
used only if it is nonzero and if the value of Location is a relative
pathname or a special name. See the Location parameter for details.
EXAMPLES
The following command with the default parameter:
Location_To_Address;
displays:
Name: .PRODUCER_CONSUMER.QUEUE.1d
PC = #19901, #10
REFERENCES
procedure Address_To_Location
@node !Commands.Debug.Memory_Display
procedure Memory_Display (Address : String := "";
Count : Natural := 0;
Format : String := "DATA");
DESCRIPTION
Displays the contents of absolute memory.
For the R1000 target, the format of the Address parameter is
"#segment,#offset". The segment specifies (in hexadecimal) the segment
address of the memory space to be displayed. The offset specifies the
starting location in the segment. The unit of the offset depends on the
Format parameter.
The display format is determined by the value of the Format parameter:
* Control words (displayed when the value of Format is "Control") are
interpreted according to the interpretation tag contained within the
word.
* Code segment words (displayed when the value of Format is "Code") are
disassembled into their symbolic form.
* All other types of memory units are displayed in hexadecimal.
If the Interpret_Control_Words option flag is disabled, Memory_Display
will not interpret control words. By default, it is enabled. Import words
are interpreted if the "Interpret_Import_Words" string flag is enabled. By
default, it is disabled.
PARAMETERS
Address : String := "";
Specifies the address at which to display memory. For the R1000, the
address format is "#segment,#offset". The segment value specifies the
segment number in hexadecimal notation. The offset specifies the location
of the instruction in the segment.
Count : Natural := 0;
Specifies the number of items to display. The meaning of this parameter is
interpreted differently for each target. For the R1000, Count specifies
the number of units displayed, starting from the memory address specified
by the Address parameter.
Format : String := "DATA";
Specifies the format of the memory to be displayed. The meaning of this
parameter is interpreted differently for each target. The legal values
for the R1000 debugger are:
Control Control word offset (memory unit is control stack
words)
Typ Type word offset (memory unit is type stack words)
Queue Bit offset (the display always starts on a full word
boundary; the starting offset will be the nearest
full word that contains the bit specified by the offset
section of the Address parameter)
Data Bit offset into the segment (the display always starts
on a full word boundary; the starting offset will be
the nearest full word that contains the bit specified
by the offset section of the Address parameter)
Import Word offset (memory unit is import words)
Code Instruction offset (memory unit is instructions)
System Bit offset (the display always starts on a full word
boundary; the starting offset will be the nearest
full word that contains the bit specified by the offset
section of the Address parameter)
@node !Commands.Debug.Modify
procedure Modify (New_Value : String := "";
Variable : Path_Name := "<SELECTION>";
Stack_Frame : Integer := 0);
DESCRIPTION
Modifies the value of the specified variable.
By default, the Modify command modifies the value of the selected variable
in the current frame of the last stopped task. The specified variable must
be a scalar. Structures such as records or arrays can be modified only by
changing the values of individual components.
The Modify command accesses variables according to the type of Ada unit in
which they were declared. Variables declared in a procedure or function
are elaborated each time that procedure or function is called, and the
Modify command accesses the individual instance of such a variable by its
stack frame. Variables declared in library-unit packages are elaborated
once, and the Modify command accesses such variables without reference to
stack frames.
Note: Unless the Variable and Stack_Frame parameters specify a specific
elaboration of a variable, the Modify command uses the current control
context and stack searching to determine which instance of that variable
to designate for modification. See the descriptions of these parameters
for more details.
Selecting Variables
* If the desired variable appears on the screen, you can select the
variable and press the key combination bound to the command. The
Variable parameter resolves to the selected variable.
* If you want to specify the variable explicitly, you enter the command
through a command window, filling in the Variable parameter with either
an absolute or a relative pathname. You do not need to fill in the
Stack_Frame parameter; however, if you do, it will supplement a
relative pathname with the specified stack frame number. (See the
Variable parameter, below.)
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on variable naming.
PARAMETERS
New_Value : String := "";
Specifies the new value of the variable.
Numeric values are specified with simple numeric representations.
Expressions are not allowed.
Enumeration values are specified with unqualified names of enumeration con-
stants. Because the variable name determines its type, enumerated values
for New_Value do not need to be qualified. For example, the string "Nul"
is sufficient to specify the character literal Ascii.Nul.
Variable : Path_Name := "<SELECTION>";
Specifies the variable to be modified. By default, the value of Variable is
the first occurrence of the specified variable in the current selection, but
selections apply only if the value of Stack_Frame is 0.
The value of Variable can be an absolute pathname, a relative pathname, or
a special name that resolves to a designated variable. The values of the
Variable parameter and the Stack_Frame parameter together designate the
actual variable whose value Modify changes. These values define which
parameter has precedence in determining the location, as shown in the
following table:
Interaction of Variable and Stack_Frame Parameters
------------------------------------
| | | |
| |Parameter |Parameter |
|If Variable |Used |Used |
|Is: |If |If |
| |Stack_Frame|Stack_Frame|
| |= 0: |/= 0: |
------------------------------------
| | | |
|An absolute |Variable |Variable |
|pathname | | |
------------------------------------
| | | 1 |
|A relative |Variable |Both |
|pathname | | |
------------------------------------
| | 2 | 3 |
|A special |Variable |Both |
|name | | |
------------------------------------
1 If Variable is a relative pathname and Stack_Frame designates a specific
frame (that is, it is nonzero), Modify uses both parameters to
designate a variable. The pathname is prepended with _n., where n is
the value of Stack_Frame. For example, if the value of Stack_Frame is
3 and the value of Variable is "Commands.Filch", the pathname used is
"_3.Commands.Filch".
2 If Variable is a special name and Stack_Frame has the default value of
zero, Modify searches the stack from the frame specified by the value of
the Stack_Start numeric flag, the default value of which is also zero.
Unless either Stack_Frame or Stack_Start is set to a nonzero value,
Modify searches from the first frame in the stack.
3 If Variable is a special name and Stack_Frame designates a specific frame
(that is, it is nonzero), Modify searches for the first occurrence of the
specified variable in that frame and subsequent frames. Modify searches
the number of frames specified by the Stack_Count numeric flag, the
default value of which is 10.
If the value of the Variable parameter is the null string (""), the Modify
procedure uses the current evaluation context to designate a variable to
modify, as follows:
* If the current evaluation context resolves to a variable, Modify
modifies that variable.
* If the current evaluation context does not resolve to a variable,
Variable defaults to a frame, which is an illegal value, and the
debugger reports an error.
Stack_Frame : Integer := 0;
Specifies the stack frame containing the variable to be modified. By
default, this parameter is ignored. Thus, this parameter is used only if
it is nonzero and if the value of Variable is a relative pathname or a
special name. See the Variable parameter for details.
RESTRICTIONS
The pathname must specify an object that is a variable.
The specified variable must have a simple data type (discrete, float, or
character).
Access types can be modified only to the value "Null". The following
objects cannot be modified:
* Variables of task types
* In parameters, which are actually constants
* Discriminants of variant records
* For-loop iteration variables
* Constants
ERRORS
The Variable parameter cannot specify a constant.
The Variable parameter cannot specify a variable of a structured type.
Structures such as records or arrays can be modified only by changing the
values of individual components.
REFERENCES
subtype Path_Name
procedure Put
@node !Commands.Debug.Numeric
type Numeric is (Display_Count, Display_Level, Element_Count,
First_Element, History_Count, History_Entries,
History_Start, Memory_Count, Pointer_Level,
Stack_Count, Stack_Start);
DESCRIPTION
Defines the set of numeric value flags used as default values by various
debugger commands.
Within the debugger, numeric value flags are called numeric flags. The
value of each numeric flag can be modified with the Set_Value command.
Each of the following numeric flags has a standard value. The standard
value is the initial value of the numeric flag when the debugger is
started. The debugger assigns values to these numeric flags from the
corresponding session switches. The switches have names of the form
Debug_xxx, where xxx is the numeric flag name. The standard values listed
below are the default values of these switches. See the Session Switches
section of the Session and Job Management (SJM) book for more information
on session switches.
Note: Type Option defines a set of Boolean value flags also used as default
values by various debugger commands. See the Option type for more
information on these flags.
ENUMERATIONS
Display_Count
Specifies the default value of the Count parameter in the Display command.
The standard value is 10.
Display_Level
Specifies the number of levels to expand complex data structures in the Put
command. Put does not display the remaining levels (that is, they are
elided). The standard value is 3.
Element_Count
Specifies the maximum number of elements in any array displayed with the
Put command. The standard value is 25.
First_Element
Specifies the first element of an array displayed with the Put command. The
standard value is 0.
History_Count
Specifies the default value for the Count parameter for the History_Display
command. The standard value is 10.
History_Entries
Specifies the maximum number of history entries kept by the debugger. The
standard value is 1,000. This flag is not currently supported.
History_Start
Specifies the oldest history entry displayed by the History_Display
command. This enumeration is the default value for the Start parameter.
The standard value is 10.
Memory_Count
Specifies the default value for the Count parameter in the Memory_Display
command. The standard value is 3.
Pointer_Level
Specifies the level of pointer values to be expanded in the display
produced by the Put command. The standard value is 3.
Stack_Count
Specifies the default value of the Count parameter used in various commands
(for example, Modify and Stack). The standard value is 10.
Stack_Start
Specifies the default starting frame number in various commands (for
example, Modify and Stack). The standard value is 1.
REFERENCES
procedure Display
procedure Flag
procedure History_Display
procedure Memory_Display
type Option
procedure Put
procedure Set_Value
procedure Stack
@node !Commands.Debug.Option
type Option is (Addresses, Break_At_Creation, Declaration_Display,
Delete_Temporary_Breaks, Display_Creation,
Echo_Commands, Freeze_Tasks, Include_Packages,
Interpret_Control_Words, Kill_Old_Jobs,
Machine_Level, No_History_Timestamps,
Optimize_Generic_History, Permanent_Breakpoints,
Put_Locals, Qualify_Stack_Names,
Require_Debug_Off, Save_Exceptions, Show_Location,
Timestamps);
DESCRIPTION
Defines the set of Boolean value flags used as default values by various
debugger commands.
Within the debugger, Boolean value flags are called option flags. The
value of each option flag can be modified with the Enable and Disable
commands.
Each of the following option flags has a standard value. The standard
value is the initial value of the option flag when the debugger is
started. The debugger assigns values to these option flags from the
corresponding session switches. The switches have names of the form
Debug_xxx, where xxx is the option flag name. The standard values listed
below are the default values of these switches. See the Session Switches
section of the Session and Job Management (SJM) book for more infor-
mation on session switches.
Note: Type Numeric defines a set of numeric value flags also used as
default values by various debugger commands. See the Numeric type for more
information on these flags.
ENUMERATIONS
Addresses
When enabled (True), includes machine information in displays produced by
Stack, Task_Display, Information, and Trace commands, and the standard
display message for stopped tasks. By default, this option flag is
disabled (False).
Break_At_Creation
When enabled (True), causes the equivalent of a breakpoint to be placed at
the point where new tasks begin elaboration. By default, this option flag
is disabled (False).
Declaration_Display
When enabled (True), forces listing of all declarations in source-code
listings by the Display command. By default, this option flag is enabled
(True).
Delete_Temporary_Breaks
When enabled (True), forces deletion of temporary breakpoints after the
debugger encounters them. By default, this option flag is disabled
(False).
Display_Creation
When enabled (True), forces a trace display for each task as it is
created. By default, this option flag is disabled (False).
Echo_Commands
When enabled (True), forces all debugger commands to be echoed in the
debugger window. By default, this option flag is enabled (True).
Freeze_Tasks
When enabled (True), requests that the debugger attempt to stop all tasks
when any task is stopped by the debugger. By default, this option flag is
disabled (False).
Include_Packages
When enabled (True), causes inclusion of elaborated packages in displays
generated by the Task_Display command. By default, this option flag is
disabled (False).
Interpret_Control_Words
When enabled (True), forces interpretation of control stack words
displayed by the Memory_Display command. By default, this option flag is
disabled (False).
Kill_Old_Jobs
When enabled (True), forces termination of the last job being debugged
when a new program is started. By default, this option flag is enabled
(True).
Machine_Level
When enabled (True), allows certain machine-level operations. By default,
this option flag is disabled (False).
No_History_Timestamps
When enabled (True), prevents inclusion of timestamps in history entries
displayed by the History_Display command. By default, this option flag is
enabled (True).
Optimize_Generic_History
When enabled (True), precludes history tracing for generic instances. A
history is taken only for the generic itself, which increases execution
speed for that generic. By default, this option flag is enabled (True).
Permanent_Breakpoints
When enabled (True), specifies whether breakpoints are permanent or
temporary. By default, this option flag is enabled (True).
Put_Locals
When enabled (True), causes display of local variables as well as formals
when procedure Put is called with locations that are packages or
subprograms. By default, this option flag is disabled (False).
Qualify_Stack_Names
When enabled (True), causes the names displayed by the Stack command to be
fully qualified. When disabled (False), the names are the simple names of
the subprograms executing in each frame. By default, this option flag is
disabled (False).
Require_Debug_Off
When enabled (True), prevents the initiation of a new debugger job from
forcing the termination of the current job. If this option flag is
enabled, the current job can terminate only by normal completion of the
job or by explicitly executing the Debug_Off command. If this option flag
is disabled, the current job will be terminated by the debugger when a
new job is initiated. By default, this option flag is disabled (False).
Save_Exceptions
When enabled (True), causes retention of exception-handling information
from the Catch and Propagate commands until the next debugging run. By
default, this option flag is disabled (False).
Show_Location
When enabled (True), causes highlighted display of current source location
for any task that stops in the debugger. The debugger displays source code
for only the control context task, the root task, or (in the case of the
Run command) all tasks. By default, this option flag is enabled (True).
Timestamps
When enabled (True), forces display of a timestamp for each command and
stopped task. By default, this option flag is disabled (False).
REFERENCES
procedure Break
procedure Disable
procedure Display
procedure Enable
procedure Flag
procedure History_Display
procedure Memory_Display
type Numeric
procedure Put
procedure Run
procedure Stack
procedure Stop
procedure Task_Display
procedure Trace
@node !Commands.Debug.Path_Name
subtype Path_Name is String;
DESCRIPTION
Defines a string used to reference declarations, objects, statements, or
types within program units.
This subtype defines the Ada string type used by commands in this package
to denote specific locations within program units. These string names use
existing Ada naming rules wherever possible and extend those rules to
define names for anonymous blocks, package and task bodies,
accept-statement bodies, locations within generic program units, and
overloaded names.
The Path_Name subtype defines two formats for pathname strings: full
pathnames and relative pathnames. Full pathnames identify an absolute
location within Ada source, beginning with a task or library name.
Relative pathnames are resolved within the current evaluation or control
context, or both, depending on the use of the pathname.
Statements and declarations are numbered. A pathname to a specific
statement or declaration includes the number of that statement or
declaration. Numbering of each group of declarations or statements is
independent and begins with 1. When source code is displayed, these
numbers appear at the beginning of statement or declaration lines. In
pathnames, statement numbers are differentiated from declaration numbers
by a suffix s (the default) for statements and d for declarations.
Pathnames can be special names (for example, "<SELECTION>") that specify a
location or object. These special names have the form "<NAME>" and are de-
scribed in more detail in Parameter-Value Conventions in the Reference
Summary (RS) book.
If a special name does not resolve to a location or object (for example,
if the special name is "<SELECTION>" and the cursor is not in the
selection), the debugger defaults to the null string (""), which is
interpreted differently by various commands.
Pathnames consist of a prefix and a final name component. The prefix of a
pathname refers to the context that contains the object identified by the
pathname. The final name component can be any of a number of disparate Ada
objects (statements, tasks, generics, and so on). The following table
defines what the final name component of a pathname would be for each object
type:
Pathname Construction
--------------------------------------------
| | |
|Object Type |Final Name Component in |
| |Pathname |
--------------------------------------------
| | |
|Library package |Simple name of the package|
--------------------------------------------
| | |
|Library |Simple name of the |
|subprogram |subprogram |
--------------------------------------------
| | |
|Library-unit |Simple name of the package|
|generic package | |
--------------------------------------------
| | |
|Library-unit |Simple name of the |
|generic |subprogram |
|subprogram | |
--------------------------------------------
| | |
|Library-unit |Simple name of the |
|generic |instantiation |
|instantiation | |
--------------------------------------------
| | |
|Package |Simple name of the package|
--------------------------------------------
| | |
|Task type |Simple name of the task |
| |type |
--------------------------------------------
| | |
|Generic instance |Simple name of the |
| |instantiation |
--------------------------------------------
| | |
|Generic package |Simple name of the generic|
|declaration |package |
--------------------------------------------
| | |
|Generic |Simple name of the generic|
|subprogram |subprogram |
|declaration | |
--------------------------------------------
| | |
|Subprogram |Simple name of the |
| |subprogram |
--------------------------------------------
| | |
|Block |Label on the block, if |
| |present, or the statement |
| |number of the block |
| |statement if no label is |
| |present (the statement |
| |number can be used as a |
| |name even if a label is |
| |present) |
--------------------------------------------
| | |
|Accept-statement |Statement number of the |
|block |accept statement (the |
| |accept statement is |
| |numbered as a normal Ada |
| |statement if it appears |
| |alone or as an arm of a |
| |select) |
--------------------------------------------
| | |
|Field of a record|Simple name of the field |
| |(this component applies |
| |to discriminants, fixed |
| |fields, and variant fields|
--------------------------------------------
| | |
|Element of an |Subscript list enclosed in|
|array |parentheses (the sub- |
| |scripts themselves must be|
| |simple constants of the |
| |appropriate type) |
--------------------------------------------
| | |
|Object designated|Name "All" |
|by a pointer | |
--------------------------------------------
The formal syntax definition of pathnames appears in the following
Backus-Naur form (BNF) definition:
Pathname ::= [Task_Prefix] [Frame_Prefix]
["." Name_Component_Sequence]
| Library_Prefix
["." Name_Component_Sequence]
| Universe_Prefix
[Name_Component_Sequence]
| Parent_Prefix
[Name_Component_Sequence]
| Parent_Library_Prefix
[Name_Component_Sequence]
| Parent_World_Prefix
[Name_Component_Sequence]
| Name_Component_Sequence
| Special_Name
Task_Prefix ::= "%" Task_Synonym
Library_Prefix ::= "." Library_Unit_Name
Frame_Prefix ::= "_" Frame_Number
Universe_Prefix ::= "!"
Parent_Prefix ::= "^"
Parent_Library
_Prefix ::= "$"
Parent_World
_Prefix ::= "$$"
Name_Component ::= Component
_Sequence | Package_Name ["." Component]
| Task_Name ["." Component]
| Task_Name ["._" Frame_Number]
| Record_Name ["." Component]
| Array_Name ["(" Index_List ")"]
| Subprogram_Name ["." Component]
| Block_Name ["." Component]
| Generic_Unit ["." Component]
| Generic_Instance ["." Component]
Special_Name ::= "< SELECTION>" | "< REGION>" | "< IMAGE>"
| "< CURSOR>"
Index_List ::= Index ["," Index_List]*
Index ::= Numeric_Literal | Identifier
Package_Name ::= Name_Component_Sequence
Task_Name ::= Name_Component_Sequence
Record_Name ::= Name_Component_Sequence
Array_Name ::= Name_Component_Sequence
Subprogram_Name ::= Name_Component_Sequence
Block_Name ::= Name_Component_Sequence
Component ::= Identifier ["'" Location_Attribute]
| Statement_Number
| Declaration_Number
Statement_Number ::= Positive ["s"]
Declaration_Number ::= Positive "d"
Positive ::= Digit+ (non-zero value)
Location_Attribute ::= "spec" | "body" | "N(" Nickname ")"
Nickname ::= Identifier | Positive
Task_Synonym ::= Identifier
Frame_Number ::= Positive | "-" Positive
Library_Unit_Name ::= Identifier
In addition to the BNF syntax definition, the following rules apply to
statement and declaration numbering:
* Use clauses and representation specifications are not numbered.
* Parameters (including generic formal parameters) are not numbered.
* Blocks are numbered separately, as are bodies of accepts, package
specs, and package bodies.
* Statements in exception handlers are numbered continuously with
preceding normal statements.
* Accept arms of select statements are numbered along with statements at
the same level as the enclosing select statement.
* Frame_Numbers are numbered with respect to the top of the stack (frame
1 is the topmost frame) unless preceded by a minus sign, in which case
the frames are relative to the bottom of the stack (frame -1 is the
bottommost frame).
* All imported library-unit names look through links. The local name of
an imported library unit is not known; only the actual name of the
imported unit is known. Use the Show (Libraries) command to see the
library-unit names that are known.
See Chapter 2, "Referencing Objects in the Debugger," for more details
regarding pathnames.
EXAMPLES
Qualified and Unqualified Pathnames
The following are examples of qualified and unqualified pathnames:
* %Session_Manager._5.Main_Process.4
The name begins with a percent symbol (%) and is qualified. Control and
evaluation contexts are not referenced. A task in the program has
called the Debug_Tools.Set_Task_Name command to give itself the name
Session_Manager. This name refers to statement 4 of a subprogram named
Main_Process that is declared in the subprogram executing in frame 5
of the stack of the task.
* !Users.Rab.Tests.Regression_Test_12
The name begins with an exclamation mark (!) and is fully qualified.
Neither the control nor the evaluation context is referenced. The
leading exclamation mark implies that the next name (Users) is a
library or library-unit name contained in the root of the directory
system.
The name refers to an object (probably a subprogram) called
Regression_Test_12 declared within !Users.Rab.Tests.
* _2.Condition
The leading underscore ( _ ) specifies a reference to stack frame number
2. The task referred to is based on the current control context. If the
control context is set to all tasks, then the stack of the last task to
stop in the debugger is referenced. An object named Condition,
declared in the subprogram executing in that frame, is designated.
* User_List.Next.Name
No leading special character begins the name. The name is relative to
the current evaluation context. Suppose Next and Name are fields of a
record and User_List and Next are accesses to that record type. Then
this name would refer to field Name of the record pointed to by field
Next of the record pointed to by User_List.
If the evaluation context is not set, the top frame of the task
specified by the control context (or the last task to stop if the
control context is not set) is referenced.
Task Names
The following are examples of task names:
* %Session_Manager
In this example, the name refers to a task that has assigned itself the
name Session_Manager. Control and evaluation contexts are not used.
* %620E
In this example, a task number is used to name the task. The task
number 620E was obtained from the Task_Display command or some other
debugger message that included the task number.
* .Configurator.Worker
The Ada name of a declared (or allocated) task can also be used.
Configurator represents a library unit and Worker a single task declared
in that unit.
* _4.Task_Pool(12)
An array of tasks, Task_Pool, declared in a subprogram that is
executing in frame 4 contains task names. Thus, each element (element
12 in this example) is a task.
Stack Object Names
The following are examples of names of objects and locations relative to a
stack:
* _3.12
A numeric suffix on an object name refers to a statement or declaration.
In this example, statement 12 of the subprogram executing in frame 3 of
the task specified by the control context (the last task to stop if
the control context is not set) is named.
* _1.Foo.12d
This name references declaration 12 of subprogram Foo that is declared
in the subprogram executing at frame 1 of the task designated by the
control context. Note that unless the evaluation context is nonnull,
the _1 prefix is used by default.
* Motor_State.Temperatures.Oil
Assume in this example that the evaluation context is null. Motor_State
is an object declared in the top frame of the task designated by the
control context. The exact interpretations of Temperature and Oil
depend on what Motor_State actually is.
Array Element Names
The following examples illustrate names of array elements.
Consider the following package:
package Data_Block is
type Color is (Red, Blue, Green);
Info : array (3 .. 35) of integer;
More_Info : array (1 .. 10, Color, Character) of Natural;
Char_Info : array (Character, Character) of integer;
end Data_Block;
* .Data_Block.Info(12)
Info names a single-dimensional array. This name references element 12
of the array.
* .Data_Block.More_Info(1,Blue,'a')
In this example, More_Info is a three-dimensional array. The first index
type is numeric, the second is an enumeration, and the third is also an
enumeration (Character type).
* .Data_Block.Char_Info(Nul,Bel)
Similarly, the two index types of this array are Character type. The
indices used are nongraphic literals.
REFERENCES
procedure Break
procedure Context
procedure Display
procedure Modify
procedure Put
@node !Commands.Debug.Propagate
procedure Propagate
(Name : Exception_Name := "<SELECTION>";
In_Task : Task_Name := "";
At_Location : Path_Name := "");
DESCRIPTION
Requests that the debugger continue task execution when a particular
exception is raised.
Propagate requests and catch requests combine to determine the action that
the debugger takes when an exception is raised. The debugger maintains a
list of catch and propagate requests entered by calls to the Catch and
Propagate procedures. When an exception in the user program is raised,
the debugger looks at this list to determine whether to stop the program
and inform the user. If the most specific request is a propagate request,
the debugger does not halt execution; otherwise, it does.
Specificity of Requests
More than one catch or propagate request can be in force simultaneously,
and when an exception is raised the debugger applies the most specific
request that includes the raised exception. The number and specificity of
parameter values determines the specificity of a propagate request. More
precise parameter values supersede less precise values. The list below
defines the specificity order for each parameter:
* At_Location: A value that specifies a statement within a subprogram is
more specific than one that specifies only a subprogram. A value that
specifies a subprogram is more specific than one that specifies all
locations.
* In_Task: A value that specifies a task is more specific than one that
specifies all tasks.
* Name: A value that names an exception is more specific than one that
specifies implicit or all exceptions. A request that specifies implicit
exceptions is more specific than one that specifies all exceptions.
Note: The At_Location parameter supersedes the In_Task parameter, which
supersedes the Name parameter. For example, the debugger considers
Propagate ("All", "", "!TEST.DECONSTRUCT_NABOKOV") more specific than
Propagate ("All", "34005", "").
By default, the debugger catches all exceptions (that is, the debugger
issues the equivalent of a Catch ("All","","") during initiation). To
override this default, enter a propagate request for all exceptions
(Propagate ("All","","")). This will remove the completely inclusive catch
request.
Matching Requests
If the parameters of a propagate request exactly match those of a catch
request, the debugger removes the catch request and applies the propagate
request. Otherwise, the Propagate command does not remove catch
requests. To remove a propagate or catch request, use the Forget command.
The Show (Exceptions) command displays all propagate and catch requests in
force, ordered by specificity. The debugger lists the exception name,
location, and task restrictions for each request.
Interaction with Flags
If the Save_Exceptions option flag is enabled, the debugger retains catch
and propagate requests when the user begins debugging a new job. By
default, this option flag is disabled. See the Option type for more
details regarding option flags.
Note: In some cases, the debugger cannot identify an exception. Exceptions
raised in Environment code, in archived source, or in a unit modified since
debugger initiation may not be named. These exceptions are identified with
a hexadecimal number. They may also be identified with strings of the form
"<Unit=1234, Ord=2>" or "<Space=3, Index=234987>". The Information
(Exceptions) command displays details regarding all exceptions raised in
the debugger, including unnamed exceptions.
PARAMETERS
Name : Exception_Name := "<SELECTION>";
Specifies the exception propagated by the request. The default value is the
name of the selected exception.
If the value of Name is the null string ("") or the reserved name "All",
the parameter identifies all exceptions. Also, if the value is a special
name (for example, "<SELECTION>") that cannot be resolved, the parameter
identifies all exceptions.
The reserved name "Implicit" identifies all exceptions raised implicitly
(that is, raised by a language construct other than a raise statement).
Implicit exceptions include only predefined exceptions such as
Constraint_Error and Tasking_Error.
If the exception name is not fully qualified, it is interpreted relative to
the current evaluation context.
Note: The debugger may use hexadecimal numbers to identify exceptions that
do not have names. This parameter accepts hexadecimal designations of
unnamed exceptions.
In_Task : Task_Name := "";
Specifies the task monitored for the exception selected by Exception_Name.
The reserved name "All" designates all tasks. The default value is the
null string ("").
Propagate requests apply only to a specific task or to all tasks. If the
value is non-null, In_Task designates the specified task. If the value is
null, In_Task designates no specific task and the Propagate command chooses
a default task based on the control context:
* If the control context is set, the request applies to the task in the
control context.
* If the control context is not set, the request applies to all tasks,
including new tasks initiated after the request was issued.
Values for the In_Task parameter may be task synonyms created by
Debug.Set_Task_Name or Debug_Tools.Set_Task_Name. Task synonyms must be
prefixed with a percent symbol (%). Tasks may also be identified with task
numbers. If the task name is not fully qualified, the name is interpreted
relative to the current evaluation context.
At_Location : Path_Name := "";
Specifies the location monitored for the exception selected by
Exception_Name. This parameter restricts the request to exceptions raised
within the specified location. If the pathname is not fully qualified, it
is interpreted relative to the current evaluation context. The default
value is null, which identifies all locations.
If the At_Location parameter specifies an Ada unit, the request applies
only to exceptions raised inside that unit. The request does not apply to
Ada units nested inside the selected unit (for example, procedures nested
within a package body, nested blocks, and accept statements).
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on designating locations.
RESTRICTIONS
The debugger allows a maximum of 40 catch and propagate requests.
EXAMPLES
A more restrictive specification always supersedes a less restrictive one.
A specification of a single task, exception, or location takes precedence
over a specification of all tasks, all exceptions, or all locations,
respectively.
Example 1
This applies to the interaction of propagate and catch requests:
Propagate (Name => "Constraint_Error",
In_Task => "All",
At_Location => "");
Propagate (Name => "All",
In_Task => "All",
At_Location => "!USERS.PHIL.TEST");
Catch (Name => "All",
In_Task => "1349704",
At_Location => "");
Any exceptions raised in !USERS.PHIL.TEST (the most specific request) do
not halt execution. The third request is more specific than the first, so
the Constraint_Error exception halts execution only if it is raised in
task 1349704; any other exception raised in task 1349704 also halts
execution.
Example 2
The name of an individual exception is considered more restrictive than
the reserved name "Implicit". The requests:
Catch (Name => "Implicit",
In_Task => "",
At_Location => "");
Propagate (Name => "Numeric_Error",
In_Task => "",
At_Location => "");
catch all implicitly raised exceptions other than Numeric_Error
exceptions.
Example 3
A location specifying a statement or declaration within an Ada unit is
more specific than a location specifying the entire Ada unit. The requests:
Catch (Name => "Status_Error",
In_Task => "",
At_Location => "Sandy.1");
Propagate (Name => "Status_Error",
In_Task => "",
At_Location => "Sandy");
catch Status_Error exceptions raised in the first statement of subprogram
Sandy, but they ignore Status_Error exceptions raised in the remainder of
the subprogram.
REFERENCES
procedure Catch
subtype Exception_Name
procedure Forget
type Option
subtype Path_Name
procedure Show (Exceptions)
subtype Task_Name
@node !Commands.Debug.Put
procedure Put (Variable : Path_Name := "<SELECTION>";
Stack_Frame : Integer := 0);
DESCRIPTION
Displays the value of the specified object.
By default, the Put command displays the value of the selected object in
the current frame of the last stopped task.
The Put command accesses variables according to the type of Ada unit in
which they were declared. Variables declared in a procedure or function
are elaborated each time that procedure or function is called, and Put
accesses the individual instance of such a variable by its stack frame.
Variables declared in library-unit packages are elaborated once, and the
Put command accesses such variables without reference to stack frames.
Note: Unless the Variable and Stack_Frame parameters specify a specific
elaboration of a variable, the Put command uses the current control
context and stack searching to determine which instance of that variable
to designate for modification. See the descriptions of these parameters
for more details.
Standard Displays
Displays of structured objects (records and arrays) depend on the values
of several numeric flags. The Put command displays a selection of array
elements from the specified structured object, starting with a specific
array element:
* The First_Element numeric flag determines the initial element.
* The Element_Count numeric flag determines the number of array elements
displayed.
* The value of the numeric flag Display_Level determines the number of
nesting levels displayed for a structured object.
* The value of the Pointer_Level numeric flag determines the level of
pointers in the structured object that are expanded for display.
The Set_Value command sets the values of numeric flags. See Set_Value and
type Numeric for more information regarding numeric flags.
Displays of strings consist of the contents of the string enclosed in
quotes. By default, the Put command displays only the first 73 characters
in a string. If the value of the Element_Count numeric flag is greater
than 73, Put defaults to the value of Element_Count for the number of
characters displayed. You can also use the First_Element and Element_Count
numeric flags to display different parts of a long string. Control
characters appear in inverse video, except for the linefeed character,
which breaks the line.
If the Variable parameter specifies an assignment statement, the Put
procedure displays the value of the left side of the statement. If
Variable specifies a return statement, Put displays the return value.
If the Put_Locals option flag is enabled, the Put procedure displays both
formal and local objects in subprograms.
Special Displays
The debugger provides default display mechanisms for all types, except for
some private Environment types. A special display function for a type can
be registered with the debugger using the generic procedure Register in
package Debug_Tools, allowing you to customize the formatting of all
objects of that type. When displaying an object of a type for which a
special type display function has been registered, the debugger uses
that special display function to display that object. Special display
functions can be initialized in the Debugger_Initialization procedure. See
the generic procedure Register in package Debug_Tools for more informa-
tion on using special displays.
The Put command displays images from special displays in braces ({ }) to
distinguish them from standard displays (that is, the displays predefined
by the debugger for various objects).
Selecting Variables
* If the desired object appears on the screen, you can select the object
and press the key combination bound to Put. The Variable parameter
resolves to the selected object.
* If you want to specify the object explicitly, enter the command through
a command window, filling in the Variable parameter with either an
absolute or a relative pathname. You do not need to fill in the
Stack_Frame parameter; however, if you do, it will supplement a
relative pathname with the specified stack-frame number. (See the
Variable parameter, below.)
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on object naming.
PARAMETERS
Variable : Path_Name := "<SELECTION>";
Specifies the object to be displayed. By default, the value of Variable is
the first occurrence of the specified object in the current selection, but
selections apply only if the value of Stack_Frame is 0.
The value of Variable can be an absolute pathname, a relative pathname, or
a special name that resolves to a designated object. The values of the
Variable parameter and the Stack_Frame parameter together designate the
actual object whose value the Put command displays. These values define
which parameter has precedence in determining the location, as shown in
the following table:
Interaction of Variable and Stack_Frame Parameters
------------------------------------
| | | |
| |Parameter |Parameter |
|If Variable |Used |Used |
|Is: |If |If |
| |Stack_Frame|Stack_Frame|
| |= 0: |/= 0: |
------------------------------------
| | | |
|An absolute |Variable |Variable |
|pathname | | |
------------------------------------
| | 1 | 2 |
|A relative |Variable |Both |
|pathname | | |
------------------------------------
| | | 3 |
|A special |Variable |Both |
|name | | |
------------------------------------
1 If Variable is a special name and Stack_Frame has the default value of
zero, Put searches from the frame specified by the value of the
Stack_Start numeric flag, the default value of which is also zero.
Unless either Stack_Frame or Stack_Start is set to a nonzero value, Put
searches from the first frame in the stack.
2 If Variable is a relative pathname and Stack_Frame is nonzero, Put uses
both parameters to designate an object. The pathname is prepended with
_n., where n is the value of Stack_Frame. For example, if the value of
Stack_Frame is 3 and the value of Variable is "Commands.Filch", the
pathname used is "_3.Commands.Filch".
3 If Variable is a special name and Stack_Frame designates a specific frame
(that is, it is nonzero), Put searches for the first occurrence of the
specified object in that frame and subsequent frames. Put searches the
number of frames specified by the Stack_Count numeric flag, the default
value of which is 10.
If the value of the Variable parameter is the null string (""), the
parameter designates the current evaluation context, the current control
context, or the first frame of the last stopped task, in order of
precedence.
Stack_Frame : Integer := 0;
Specifies the stack frame containing the object to be displayed. By
default, this parameter is ignored. Thus, this parameter is used only if
it is nonzero and if the value of Variable is a relative pathname or a
special name. See the Variable parameter for details.
RESTRICTIONS
The pathname must specify an object that has a value.
A specific package, task, or subprogram frame must be referenced by the
Variable parameter. The Put procedure cannot differentiate between
multiple activations of a subprogram, unless a selection is being used.
This condition also applies to generic packages and task types; a
specific instance must be referenced.
The Put procedure can display only single-dimensional arrays. Individual
elements of higher-dimensional arrays can be displayed, but not the entire
array.
ERRORS
The parameter specifies an object that has no value-for example, a field of
a variant record that is not present because of the value of the
discriminant.
A variable may be uninitialized; the Put command displays a random value
for uninitialized variables. For the R1000, the debugger displays
Uninitialized Value when Put attempts to display an uninitialized scalar.
A variable can include a subscript that is out of range for an array being
indexed.
A variable can dereference a pointer that is null.
The pathname of a variable must be legal. See type Path_Name for more
information. Put cannot modify the values of:
* Variables of task types
* In parameters
* For-loop variables
* Constants
EXAMPLES
A sample debugger session that includes use of the Put and Display
commands is shown below:
Beginning to debug: DEBUG_DOC.TEST_PROGRAMS.EXAMPLE_FOR_MANUAL'BODY'V(1) %
!USERS.BLB.DEBUG_DOC.TEST_PROGRAMS.EXAMPLE_FOR_MANUAL
Stop at: .command_procedure, Root task: [Task : ROOT_TASK, #1134E1].
Execute ("all");
User break: .EXAMPLE_FOR_MANUAL.1s [Task : ROOT_TASK, #1134E1].
Display ("%ROOT_TASK._1", 0);
procedure .EXAMPLE_FOR_MANUAL is
1 type TERMINAL is (VT100, DASHER, CIT500, ADM3);
2 type ID is new INTEGER;
3 type TERM_ARRAY is array (1 .. 3) of TERMINAL;
4 type R1 is record
F1 : INTEGER;
F2 : CHARACTER;
F3 : TERM_ARRAY;
end record;
5 type AR1 is access R1;
6 B1 : TERMINAL := DASHER;
7 B2 : ID := ID'FIRST;
8 B3 : R1 := R1'(F1 => 0, F2 => 'b', F3 => (VT100, DASHER, VT100));
9 B4 : AR1 := new R1'(F1 => -20, F2 => ASCII.ESC, F3 => (DASHER, ADM3,
CIT500));
begin
* 1 DEBUG_TOOLS.USER_BREAK ("");
end;
Now the values of the variables are displayed. Note that the default
context is the top frame of the last task to stop--in this case, the
procedure frame containing the variables of interest.
Before the first Put command is executed, the variable name B1 is selected.
The debugger echoes the following when [Put] is pressed:
Put ("%ROOT_TASK._1.B1");
DASHER
Note that although the Value parameter to the Put command specified that a
selection be used, the name of the selected object is echoed in the
command.
The following Put commands had string parameters of the form "b1" for
their Value parameters. Note that selection could have been used as well:
* Put ("b1");
Put ("%ROOT_TASK._1.b1");
DASHER
* Put ("b2");
Put ("%ROOT_TASK._1.b2");
-2147483647
* Put ("b3");
Put ("%ROOT_TASK._1.b3");
[ F1 => 0
F2 => 'b'
F3 =>
[ 1 .. 3 ]
[ 1 => VT100
2 => DASHER
3 => VT100 ]
]
* Put ("b4");
Put ("%ROOT_TASK._1.b4");
#1134E1 #80 -->
[ F1 => -20
F2 => ASCII.ESC
F3 =>
[ 1 .. 3 ]
[ 1 => DASHER
2 => ADM3
3 => CIT500 ]
]
* Put ("b4.f3(2)");
Put ("%ROOT_TASK._1.b4.f3(2)");
ADM3
* Put ("b4.f3(5)");
Put ("%ROOT_TASK._1.b4.f3(5)");
Display error:
Array index out of bounds
Display ("%ROOT_TASK._1.b4", 0);
access R1
Display ("%ROOT_TASK._1.b2", 0);
range -2147483647 .. 2147483647
REFERENCES
procedure Context
procedure Modify
type Numeric
type Option
subtype Path_Name
procedure Set_Value
procedure Debug_Tools.Register
procedure Debug_Tools.Un_Register
@node !Commands.Debug.Release
procedure Release (Name : Task_Name := "");
DESCRIPTION
Releases a task from the "held" state and moves it to the "stopped" state.
When held tasks are released to the stopped state, you can cause them to
resume execution with the Execute and Run commands.
PARAMETERS
Name : Task_Name := "";
Specifies the task to be released. The default value is the task specified
by the current control context. If the control context is not explicitly
set, the default value is all tasks.
The reserved word "All" specifies all tasks.
REFERENCES
procedure Execute
procedure Hold
procedure Stop
@node !Commands.Debug.Remove
procedure Remove (Breakpoint : Natural;
Delete : Boolean := False);
DESCRIPTION
Deactivates the specified breakpoint.
This command deactivates breakpoints set with the Break command. The
removed breakpoint will not interrupt execution unless it is reactivated
with the Activate command. The Remove command can delete a breakpoint
after it is deactivated. Deleted breakpoints no longer exist and cannot be
reactivated.
PARAMETERS
Breakpoint : Natural;
Specifies which breakpoint to deactivate. The value is the number assigned
to the breakpoint when it was created.
A value of 0 represents all breakpoints. Thus, Remove(0, True) deletes all
breakpoints.
Delete : Boolean := False;
Specifies whether to delete the breakpoint. The default value is False.
ERRORS
The breakpoint does not exist.
REFERENCES
procedure Activate
procedure Break
procedure Show (Breakpoints)
@node !Commands.Debug.Reset_Defaults
procedure Reset_Defaults;
DESCRIPTION
Resets all numeric, option, and string flags to their standard values and
unregisters all special displays.
See procedure Debug_Tools.Register for more information on special
displays.
From a login procedure, this command automatically starts the debugger,
but it does not display the debugger window.
@node !Commands.Debug.Run
procedure Run (Stop_At : Stop_Event := Debug.Statement;
Count : Positive := 1;
In_Task : Task_Name := "");
DESCRIPTION
Executes the specified task until the stop event has occurred the number of
times specified by the Count parameter.
By default, the last task to stop in the debugger is run.
The Run command executes the specified task until the stop condition
specified by the Stop_At parameter occurs the number of times specified by
Count. When this condition is met, Run displays the location of the next
statement and stops the task. The Stop_At parameter allows step-by-step
execution of a program. The stepping conditions of a Run command persist
if a task stops for a different reason (for example, a breakpoint or
exception). When execution resumes, the stepping condition is still in
force.
The Clear_Stepping command clears stepping conditions set for the Run com-
mand. See the Clear_Stepping procedure for more information.
The Run command resumes execution of all implicitly stopped tasks. If the
Freeze_Tasks option flag is enabled, all tasks stop implicitly when a
single task stops.
Note: Stepping reduces execution speed. To improve performance, you can
set a breakpoint before the area of interest in your program, use the
Execute command to run without stopping to the breakpoint, and then resume
execution with stepping for that area.
PARAMETERS
Stop_At : Stop_Event := Debug.Statement;
Specifies the event that will halt execution. The default is any statement.
Count : Positive := 1;
Specifies the repetition limit (that is, the number of times it is
executed) of the stop event specified by the Stop_At parameter. The default
value is 1, which specifies the first execution of the stop event.
In_Task : Task_Name := "";
Specifies the task to be run. The default is the task specified by the
control context. If the control context does not resolve to a task,
In_Task specifies the last stopped task. The reserved name "All" specifies
all tasks.
RESTRICTIONS
The debugger allows only one stepping operation per task. Starting a new
stepping operation cancels the existing operation.
ERRORS
For the R1000 target, the number of debugging operations that can be
applied to a specific task is limited. If too many breakpoints are set in a
given task, it may not be possible to execute the Run command for that
task.
EXAMPLES
When the debugger stops and displays:
Break 1: .STEPPING_TEST.2s [#620E]
the user enters the command:
Run (Statement, 3, "%602E");
and the debugger then displays:
Step: .STEPPING_TEST.5s [#620E]
REFERENCES
procedure Clear_Stepping
procedure Show (Steps)
@node !Commands.Debug.Set_Task_Name
procedure Set_Task_Name (For_Task : Task_Name := "";
To_Name : String := "");
DESCRIPTION
Assigns a string synonym to the specified task.
A synonym can be assigned to only one task; the debugger does not allow
synonyms to be overloaded. Reassigning a task synonym to a new task
removes that synonym from the task to which it was previously assigned.
The name Root_Task is automatically assigned to the root task (the command
task) in a job. Do not reassign the root-task synonym.
The Debug_Tools.Set_Task_Name command also assigns synonyms to tasks.
Most debugger commands recognize task synonyms. To be used in a command, a
synonym must be preceded by a percent symbol (%). The string passed to
this command, however, should not have a leading percent symbol.
It is good practice to call the Set_Task_Name procedure in important (if
not all) tasks to identify them easily during debugging. The call is
especially important when multiple instances of the same task are created.
It is some extra work to give each a unique name, but the effort often
greatly simplifies the task of understanding what is going on during
debugging.
The Debug_Tools.Set_Task_Name procedure also assigns synonyms to tasks.
Note, however, that the parameters differ from those for this command.
Note: Task synonyms were formerly documented as task nicknames.
PARAMETERS
For_Task : Task_Name := "";
Specifies the task to which a synonym is assigned. If the value is the null
string ("") and the control context resolves to a task, For_Task specifies
that task. If the value is the null string ("") and the control context
does not resolve to a task, For_Task specifies the last stopped task.
To_Name : String := "";
Specifies the name to be assigned to the task. The string must be a legal
Ada identifier. Strings containing illegal characters cause an error.
REFERENCES
type Path_Name
procedure Task_Display
procedure Debug_Tools.Set_Task_Name
@node !Commands.Debug.Set_Value
procedure Set_Value (Variable : Numeric;
To_Value : Integer):
DESCRIPTION
Sets a numeric value flag to the specified value.
See the Numeric type for more information on the numeric value flags.
PARAMETERS
Variable : Numeric;
Specifies the numeric variable to change.
To_Value : Integer;
Specifies the variable value.
REFERENCES
procedure Disable
procedure Enable
type Numeric
type Option
@node !Commands.Debug.Show
procedure Show (Values_For : State_Type := Debug.Breakpoints);
DESCRIPTION
Displays information about various debugger facilities.
By default, this command displays a list of all breakpoints.
A value of All_State for the Values_For parameter specifies all supported
information types (for example, Breakpoints, Contexts, Exceptions, and
so on). Other values refer only to individual types. The examples below
demonstrate the display format of each information type.
PARAMETERS
Values_For : State_Type := Debug.Breakpoints;
Specifies the information type displayed. The default value is Breakpoints.
See the State_Type type for details regarding other values.
EXAMPLES
The following examples show the different facilities and the content of
displays for those facilities.
Example 1
The command:
Show (Breakpoints);
produces the display:
Active Permanent Break 4 at !USERS.JACK.TEMP.3d [any task]
Inactive Permanent Break 5 at !USERS.JACK.T.1s [any task]
Active Temporary Break 6 at !USERS.JACK.JILL.1s [task : #2D110]
The display of breakpoint information lists the state (active or
inactive), type (permanent or temporary), number, location, and associated
task for all existing breakpoints.
Example 2
The command:
Show (Contexts);
displays the current control and evaluation contexts. The commands:
Context (Control, "%2D110");
Context (Evaluation, "!USERS.PHIL.PIE_CHART");
Show (Contexts);
produce the display:
Evaluation context: !users.phil.pie_chart
Control context: #2D110
The commands:
Context (Control, "All");
Context (Evaluation, "");
Show (Contexts);
produce the display:
Evaluation context:
Control context: all
Example 3
The command:
Show (Flags);
displays the name of each known flag and its current value:
DISPLAY_COUNT 10
DISPLAY_LEVEL 3
ELEMENT_COUNT 25
FIRST_ELEMENT 0
HISTORY_COUNT 10
HISTORY_ENTRIES 1000
HISTORY_START 10
MEMORY_COUNT 3
POINTER_LEVEL 3
STACK_COUNT 10
STACK_START 1
ADDRESSES FALSE
BREAK_AT_CREATION FALSE
DECLARATION_DISPLAY TRUE
DELETE_TEMPORARY_BREAKS FALSE
DISPLAY_CREATION FALSE
ECHO_COMMANDS TRUE
FREEZE_TASKS FALSE
INCLUDE_PACKAGES FALSE
INTERPRET_CONTROL_WORDS TRUE
KILL_OLD_JOBS TRUE
MACHINE_LEVEL FALSE
NO_HISTORY_TIMESTAMPS TRUE
OPTIMIZE_GENERIC_HISTORY TRUE
PERMANENT_BREAKPOINTS TRUE
PUT_LOCALS FALSE
QUALIFY_STACK_NAMES FALSE
REQUIRE_DEBUG_OFF FALSE
SAVE_EXCEPTIONS FALSE
SHOW_LOCATION TRUE
TIMESTAMPS FALSE
CACHE_STACK_FRAMES TRUE
Example 4
The command:
Show (Exceptions);
displays all active exception requests. At least one request is always
active; it indicates what to do for exceptions not covered by other
requests. The command lists exception requests from the most specific to
the least specific, since the debugger applies requests in order of
specificity. The following example shows how the display changes to reflect
new exception requests:
Show (Exceptions);
Debugger stops on: unlisted exceptions
Catch ("constraint_error", "all", "");
The exception constraint_error will be caught when raised in any
location in all tasks.
Propagate ("tasking_error", "all", "");
The exception tasking_error will be propagated when raised in any
location in all tasks.
Catch ("implicit", "all", "");
Implicit exceptions will be caught when raised in any location in
all tasks.
Show (Exceptions);
Debugger stops on: Constraint_Error
Debugger doesn't stop on: Tasking_Error
Debugger stops on: implicit
Debugger stops on: unlisted exceptions
Forget ("constraint_error", "all", "");
The exception constraint_error has been forgotten for all locations
in all tasks.
Propagate ("", "all", "");
Unlisted exceptions in unlisted locations and tasks will be propagated.
Catch ("!io.io_exceptions.layout_error", "1cf8e1", "");
The exception !io.io_exceptions.layout_error will be caught when
raised in any location in task #1CF8E1.
Show (Exceptions);
Debugger stops on: !Io.Io_Exceptions.Layout_Error when raised in
task
#1CF8E1
Debugger doesn't stop on: Tasking_Error
Debugger stops on: implicit
Debugger doesn't stop on: unlisted exceptions
Example 5
The command:
Show (Libraries);
lists the names of the currently registered libraries and their library
units.
If the Addresses option flag is enabled, the Show (Libraries) command
displays more specific information about the current libraries:
Show (Libraries);
Libraries in use by this program:
Library: TEST_LIBRARY
Main Unit: M1
Library Units:
package TEXT_IO
procedure TEST
procedure MAIN
Example 6
The command:
Show (Traces);
lists the information regarding the currently enabled tracing conditions.
For example:
Trace (TRUE, STATEMENT, "all", "");
Statement tracing has been enabled for all locations in all tasks.
Trace (TRUE, CALL, "%1cf8e1", "");
Call tracing has been enabled for all locations in
task A, #1CF8E1.
Show (Traces);
Tasks which are tracing calls:
#1CF8E1: at all locations
Tasks which are tracing statements:
all: at all locations
No tasks are tracing exceptions.
Example 7
This example displays a list of current history being recorded:
Take_History (TRUE, CALL, "all", "");
Call history-taking has been enabled for all locations in all tasks.
Take_History (TRUE, STATEMENT, "all", "");
Statement history-taking has been enabled for all locations in all
tasks.
Take_History (TRUE, EXCEPTION_RAISED, "all", "");
Exception history-taking has been enabled for all locations in all
tasks.
Show (Histories);
History of Calls is being recorded for:
all tasks at all locations
History of Statements is being recorded for:
all tasks at all locations
History of Exceptions is being recorded for:
all tasks at all locations
Example 8
This example displays a list of currently active stop and hold requests,
including specific entries for tasks exempt from global stop and hold
requests:
Hold ("all");
Each task will stop by its next statement.
Release ("%1cf8e1");
Fine.
Stop ("%1cf8e1");
Task #1CF8E1 will stop by its next statement.
Show (STOPS_AND_HOLDS);
Stops and Holds:
All tasks: Hold
#1CF8E1 Stop; exempt from hold all
Example 9
The following example lists the names of tasks currently executing with
stepping operations:
Show (Steps);
Task #1CF8E1 stepping statements.
REFERENCES
procedure Break
procedure Catch
procedure Context
procedure Enable
procedure Flag
procedure Forget
procedure Hold
procedure Propagate
procedure Run
procedure Set_Value
type State_Type
procedure Stop
procedure Trace
procedure Debug_Tools.Register
@node !Commands.Debug.Source
procedure Source (Location : Path_Name := ""
Stack_Frame : Integer := 0);
DESCRIPTION
Displays the program source for the specified location in an Environment
window.
By default, this command displays the location in the program source
specified by the current selection, if one exists, or the next statement in
the last stopped task.
The form of the source displayed depends on the type of object referenced
by the Location parameter. The following list includes the specific objects
and the corresponding sources:
Source Types
---------------------------------------
| | |
|Object |Source Displayed |
---------------------------------------
| | |
|Frame |Displays the subprogram |
|numbers |executing in that stack frame.|
---------------------------------------
| | |
|Task |Displays the task declaration.|
|names | |
---------------------------------------
| | |
|Declara-|Displays the unit containing |
|tions |the declaration, with the |
| |declaration highlighted. |
---------------------------------------
| | |
|State- |Displays the unit containing |
|ments |the statement, with the |
| |statement highlighted. |
---------------------------------------
| | |
|Library |Displays the library unit. |
|unit | |
---------------------------------------
For other objects, this command displays the object or its type.
PARAMETERS
Location : Path_Name := "";
Specifies the location to be displayed. A location can be an Ada program
unit (a package, task, or subprogram), a frame reference, a statement, or
a declaration. By default, the value of Location is the selected statement
or declaration, but selections apply only if the value of Stack_Frame
is 0.
The value of Location can be an absolute pathname, a relative pathname, or
a special name that resolves to a designated location. The values of the
Location parameter and the Stack_Frame parameter together designate the
actual location for which the Source procedure displays the program
source. These values define which parameter has precedence in determining
the location, as shown in the following table:
Interaction of Location and Stack_Frame Parameters
------------------------------------
| | | |
| |Parameter |Parameter |
|If Location |Used |Used |
|Is: |If |If |
| |Stack_Frame|Stack_Frame|
| |= 0: |/= 0: |
------------------------------------
| | | |
|An absolute |Location |Location |
|pathname | | |
------------------------------------
| | | 1 |
|A relative |Location |Both |
|pathname | | |
------------------------------------
| | | |
|A special |Location |Stack2 |
|name | |Frame |
------------------------------------
1 If Location is a relative pathname and Stack_Frame is nonzero, Source
uses both parameters to designate a location. The pathname is
prepended with _n., where n is the value of Stack_Frame. For example,
if the value of Stack_Frame is 3 and the value of Location is
"Commands.Filch", the pathname used is "_3.Commands.Filch".
2 If Location is a special name and Stack_Frame is nonzero, then
Stack_Frame overrides Location and Source displays the source for the
frame specified by Stack_Frame.
If the value of the Location parameter is the null string ("") or if the
value is a special name that cannot be resolved, the parameter designates
the location at which the last task stopped.
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on designating locations.
Stack_Frame : Integer := 0;
Specifies the frame to be displayed. By default, this parameter is ignored.
Thus, this parameter is used only if it is nonzero and if the value of
Location is a relative pathname or a special name. See the Location
parameter for details.
The value of Stack_Frame can be specified with a numeric argument key if
this command is entered with a key combination.
REFERENCES
procedure Display
@node !Commands.Debug.Stack
procedure Stack (For_Task : Task_Name := "";
Start : Integer := 0;
Count : Natural := 0);
DESCRIPTION
Displays the specified frames of the stack for the named task.
By default, the Stack procedure displays the first ten stack frames of the
last task to stop in the debugger.
If the specified task is running, the Stack commands temporarily stops the
task before displaying its stack. The task immediately resumes after Stack
completes the display. Since execution stacks are dynamic (that is, they
can change at any time), the information displayed by Stack may not
necessarily be accurate after the display completes. Stopping a task
freezes its frame stack so that the execution status of that task is
static. See the Stop command for more details about stopping tasks.
If the Addresses option flag is enabled, the Stack command includes the
program counter (segment and offset), stack-frame pointer value, outer
frame pointer (the pointer to the declarative context for the subprogram),
and the lexical level of the subprogram in the display for each frame. See
the Option type for more details regarding this option flag.
The Qualify_Stack_Names option flag forces full qualification of all Ada
names displayed by the Stack command. See the Option type for more details
regarding this option flag.
PARAMETERS
For_Task : Task_Name := "";
Specifies the name of the task whose stack is displayed. The default value
is the stack of the task specified by the current control context. If the
current control context does not resolve to a task name, For_Task specifies
the last stopped task.
Start : Integer := 0;
Specifies the starting frame for the display. The default value of 0 sets
Start to the value of the Stack_Start numeric flag, the default value of
which is 1.
The Stack command identifies frames sequentially from the first frame in the
stack for the current subprogram (the most recently called subprogram)
starting with 1. Negative values identify frames in reverse order from the
last frame. For example, a Start value of 1 specifies the first frame in the
stack and a value of -1 specifies the last frame.
Count : Natural := 0;
Specifies the number of frames displayed. The default value of 0 sets Count
to the value of the Stack_Count numeric flag, the default value of which
is 10.
ERRORS
The task name may be invalid.
The specified stack frames may not exist in the current task's stack.
EXAMPLES
Assume that the following program is being debugged and has stopped in the
breakpoint generated by the call to Debug_Tools.Break in procedure A:
with Debug_Tools;
procedure Nested_Calls is
procedure A is
begin
Debug_Tools.Break ("stopped in a");
end A;
procedure B is
begin
A;
end B;
procedure C is
begin
B;
end C;
procedure D is
begin
C;
end D;
begin
D;
end Nested_Calls;
Entering the Stack command with the default values displays the following
stack information in the debugger window:
Stack ("%ROOT_TASK", 0, 0);
Stack of task ROOT_TASK, #340E0:
_1: A.1s
_2: B.1s
_3: C.1s
_4: D.1s
_5: NESTED_CALLS.1s
_6: command_procedure.1s
_7: command_procedure [library elaboration block]
The first line contains the name of the task for this stack. In this case,
the task is the root task of the main program, with a string name of
Root_Task and the task number #340E0.
The subsequent lines display the frames of the stack for the task. Each
frame is prefixed with its number (for example, _1:) and contains the
location in the source program corresponding to that frame. The top frame,
frame 1, is the most recent frame. Earlier frames have higher numbers. In
this case, the bottom frame, number 7, is the code that elaborated the
command that called the Nested_Calls program.
If the Qualify_Stack_Names option flag is enabled (with the Enable
command), the stack frames will be displayed with the full pathnames for
their source locations. For example:
Enable (QUALIFY_STACK_NAMES, TRUE);
The QUALIFY_STACK_NAMES flag has been set to TRUE.
Stack ("%ROOT_TASK", 0, 0);
Stack of task ROOT_TASK, #340E0:
_1: .NESTED_CALLS.A.1s
_2: .NESTED_CALLS.B.1s
_3: .NESTED_CALLS.C.1s
_4: .NESTED_CALLS.D.1s
_5: .NESTED_CALLS.1s
_6: .command_procedure.1s
_7: .command_procedure [library elaboration block]
REFERENCES
type Numeric
type Option
@node !Commands.Debug.State_Type
type State_Type is (All_State, Breakpoints, Contexts, Exceptions,
Flags, Histories, Libraries, Special_Types,
Steps, Stops_And_Holds, Traces, Active_Items,
Exception_Cache, Inner_State, Statistics);
DESCRIPTION
Defines enumeration values for state information categories used by various
debugger commands (for example, the Show command).
ENUMERATIONS
All_State
Specifies inclusively the range of enumeration values from Breakpoints
through Stops_And_Holds.
Breakpoints
Specifies all active and inactive breakpoints.
Contexts
Specifies all control and evaluation contexts.
Exceptions
Specifies all exception requests (those issued by the Catch and Propagate
commands).
Flags
Specifies all flag values in the debugger, including Option and Numeric
flags and the flags set with the Flag command.
Histories
Specifies the history requests currently active.
Libraries
Specifies all active libraries.
Special_Types
Specifies the current set of registered special displays. See the
Debug_Tools.Register command for more information on special displays.
Steps
Specifies all currently stepping tasks.
Stops_And_Holds
Specifies all current stop and hold requests.
Traces
Specifies all tasks currently being traced.
Active_Items
For the use of Rational technical representatives only.
Exception_Cache
For the use of Rational technical representatives only.
Inner_State
For the use of Rational technical representatives only.
Statistics
For the use of Rational technical representatives only.
REFERENCES
procedure Show
procedure Debug_Tools.Register
@node !Commands.Debug.Stop
procedure Stop (Name : Task_Name := "");
DESCRIPTION
Stops execution of the specified task.
The specified task stops at the beginning of the next statement. This
command allows rendezvous and complex statements to complete before the
stop takes effect. Stop displays a status message for each task when it
stops.
If the Freeze_Tasks option flag is enabled, the debugger attempts to stop
all other tasks when any one task is stopped. The other tasks may not
actually stop because they may be in rendezvous with the stopped task,
waiting for an entry call, or otherwise blocked.
When a Stop command stops all tasks (for example, Stop ("All")), it also
applies to tasks initiated after the original Stop command was issued. For
example, individual tasks may resume execution because of specific
Execute commands, but new tasks created by those tasks would be stopped by
the overall Stop command.
PARAMETERS
Name : Task_Name := "";
Specifies the task to be stopped. The default value is the null string,
which defaults to the task specified by the current control context. If the
control context is not set, the default is all tasks.
The reserved name "All" specifies all tasks.
RESTRICTIONS
The specified task must exist.
EXAMPLES
The following example describes the sequence of events that occurs after a
Stop command is given when debugging a multitasking program:
Each task will stop by its next statement.
Stop: .PRODUCER_CONSUMER.CONSUMER.4S [Task : CONSUMER, #2F8D4].
Stop: .PRODUCER_CONSUMER.PRODUCER.4S [Task : PRODUCER, #2F4D4].
Stop: .PRODUCER_CONSUMER.QUEUE.7S [Task : QUEUE, #2F0D4].
The first line appears immediately after the Stop command is given. Then
each task stops one by one. There may be some delay, because each task
must complete its current statement or declaration before being stopped
by the debugger. If there are delay statements, rendezvous, or complex
statements, the task may require some time before being stopped.
REFERENCES
procedure Execute
procedure Hold
procedure Release
procedure Run
procedure Task_Display
@node !Commands.Debug.Stop_Event
type Stop_Event is (About_To_Return, Begin_Rendezvous,
End_Rendezvous, Local_Statement,
Machine_Instruction, Procedure_Entry,
Returned, Statement);
DESCRIPTION
Defines the events used to specify the stopping condition for a task
(specifically for the Run command).
Note: Some of the enumerations are not currently implemented; if used, an
error message is generated and the command is not executed.
ENUMERATIONS
About_To_Return
Specifies that the task is about to return from a subprogram. This
enumeration value specifies either a return statement or the end of a
subprogram. This enumeration not currently implemented.
Begin_Rendezvous
Specifies that the task is starting to rendezvous with another task. This
enumeration value applies only to the accepting task. Entry calls do not
cause tasks that are stepping to break until a rendezvous begins. This
enumeration not currently implemented.
End_Rendezvous
Specifies that the task is about to complete a rendezvous with another
task. This enumeration value applies only to the accepting task and occurs
after the last rendezvous statement executes. This enumeration not
currently implemented.
Local_Statement
Specifies that the task completed execution of the current statement.
Local_Statement treats subprograms called from the current statement as
part of that statement.
Machine_Instruction
Specifies that the task has completed execution of the current machine
instruction.
Procedure_Entry
Specifies that the task has entered a subprogram. The task stops before
elaboration of the first declaration or before execution of the first
statement if the subprogram does not include declarations. This
enumeration not currently implemented for certain cross-debuggers.
Returned
Specifies that the task has just returned from the current subprogram. Many
levels of returns may occur if a number of subprograms execute their last
statements simultaneously.
Statement
Specifies that the task has reached the beginning of the next statement. If
the current statement calls a subprogram, the task stops at the first
declaration or statement of the called subprogram.
@node !Commands.Debug.Take_History
procedure Take_History
(On : Boolean := True;
Event : Trace_Event := Debug.All_Events;
For_Task : Task_Name := "";
At_Location : Path_Name := "<SELECTION>";
Stack_Frame : Integer := 0);
DESCRIPTION
Enables or disables history recording for a specified task.
By default, this command initiates history recording for all events
occurring in all tasks in the selected location.
By using the parameters of Take_History to limit event entries, a history
request can be exclusive to individual tasks, locations, or types of
events. Although more than one history request can be active at any time,
all history entries are saved in one history buffer.
The history buffer is a circular buffer. That is, events selected by the
Take_History command are recorded by the debugger in the history buffer;
when the buffer becomes full, the oldest events are overwritten by new
events. See the "Restrictions" section, below, for the maximum number of
history entries.
The History_Display command displays selections of event entries from the
debugger history. See the History_Display procedure for more details.
The Trace command displays events of the current job in the debugger
window as they occur. See the Trace procedure for more details.
Note: The recording of history events reduces execution speed but is
significantly faster than tracing the same events.
PARAMETERS
On : Boolean := True;
Specifies whether to enable or disable history recording. The default value
is True (enabled).
Event : Trace_Event := Debug.All_Events;
Specifies the type of information to be recorded. By default, all events,
except the execution of machine instructions, are recorded. See the
Trace_Event type for more details.
For_Task : Task_Name := "";
Specifies the task for history recording. The default is the task specified
by the control context or, if the control context does not resolve to a
specific task, all tasks.
At_Location : Path_Name := "<SELECTION>";
Specifies a location to which history recording is restricted. At_Location
must specify a subprogram, statement, or all locations. By default, the
value of At_Location is the selected statement or declaration, but
selections apply only if the value of Stack_Frame is 0.
The value of At_Location can be an absolute pathname, a relative pathname,
or a special name that resolves to a designated location. The values of
the At_Location parameter and the Stack_Frame parameter together designate
the actual location to which history recording is limited. These values
define which parameter has precedence in determining the location, as
shown in the following table:
Interaction of At_Location and Stack_Frame Parameters
------------------------------------
| | | |
| |Parameter |Parameter |
|If |Used |Used |
|At_Location |If |If |
|Is: |Stack_Frame|Stack_Frame|
| |= 0: |/= 0: |
------------------------------------
| | | |
|An absolute |At_Location|At_Location|
|pathname | | |
------------------------------------
| | | 1 |
|A relative |At_Location|Both |
|pathname | | |
------------------------------------
| | | |
|A special |At_Location|Stack2 |
|name | |Frame |
------------------------------------
1 If At_Location is a relative pathname and Stack_Frame is nonzero,
Take_History uses both parameters to designate a location. The pathname
is prepended with _n., where n is the value of Stack_Frame. For
example, if the value of Stack_Frame is 3 and the value of
At_Location is "Commands.Filch", the pathname used is "_3.Commands.Filch".
2 If At_Location is a special name and Stack_Frame is nonzero, then
Stack_Frame overrides Location and Take_History limits recording to the
subprogram specified by Stack_Frame.
If the value of the At_Location parameter is the null string (""), the
parameter designates all locations. Also, if the value is a special name
that cannot be resolved, the parameter designates all locations.
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on designating locations.
Stack_Frame : Integer := 0;
Specifies the frame for which history is collected. By default, this
parameter is ignored. Thus, this parameter is used only if it is nonzero
and if the value of At_Location is a relative pathname or a special name.
See the At_Location parameter for details.
RESTRICTIONS
The debugger allows a maximum of 20 histories to be recorded
simultaneously.
The debugger keeps only the most recent 1,000 entries recorded for a
history.
EXAMPLES
With a selection that resolves to the location
".GENERAL.NATIVE.LOOP_BASE.9S", the command:
Take_History (True, Debug.All_Events, "", "<SELECTION>", 0);
produces the following output:
Take_History (TRUE, ALL_EVENTS, "all", ".GENERAL.NATIVE.LOOP_BASE.9S");
Call history-taking has been enabled for .GENERAL.NATIVE.LOOP_BASE.9S in
all tasks.
Exception history-taking has been enabled for
.GENERAL.NATIVE.LOOP_BASE.9S in all tasks.
Statement history-taking has been enabled for
.GENERAL.NATIVE.LOOP_BASE.9S in all tasks.
indicating that history taking has been enabled for the specified source
location in all tasks for all events except machine-instruction execution.
REFERENCES
procedure History_Display
procedure Trace
type Trace_Event
@node !Commands.Debug.Task_Category
type Task_Category is (All_Tasks, Blocked, Held, Not_Running,
Running, Stopped);
DESCRIPTION
Defines the set of tasks that can be displayed by various debugger commands
(for example, the Task_Display command).
This type defines subsets of all tasks in the current debugger job. The
Task_Display command displays information regarding these subsets.
ENUMERATIONS
All_Tasks
Specifies all tasks created within the job being debugged.
Blocked
Specifies all tasks currently blocked by external conditions (for example,
a rendezvous or delay), but not including tasks held or stopped by the
debugger.
Held
Specifies all tasks that are currently held by the debugger (tasks are held
by the Hold command).
Not_Running
Specifies all tasks not currently executing, including blocked, held, and
stopped tasks, and tasks executing delay statements.
Running
Specifies all tasks currently executing. This does not include tasks
executing delay statements, waiting for rendezvous, or stopped in the
debugger by breakpoints, exceptions, or similar events.
Stopped
Specifies all tasks currently stopped in the debugger. This includes tasks
held by the Hold command.
@node !Commands.Debug.Task_Display
procedure Task_Display
(For_Task : Task_Name := "";
Task_Set : Task_Category := Debug.All_Tasks);
DESCRIPTION
Displays information about the named task or set of tasks.
The Task_Display procedure lists the number, Ada name, priority, and
current state for the specified task. The command lists task synonyms (if
any have been assigned) and the current location of a task if it is
stopped. The state information listed for the task indicates whether the
task is running, is being stopped, or is stopped. If the task is running,
Task_Display shows its execution state. If it is stopped, Task_Display
indicates the reason it is stopped.
Note: The For_Task parameter overrides the Task_Set parameter, unless
For_Task specifies all tasks. See the "Parameters" section, below.
The Task_Display command does not list terminated tasks.
The following table lists the execution state message, state name, and
description for running tasks. (Task_Display does not actually show state
names for tasks.) These state names are valid only for the R1000 target.
Task-State Display Information
---------------------------------------------------------------
| | | |
|State Message |State Name |Description |
---------------------------------------------------------------
| | | |
|[No state message |Unblocked |The task is ready to |
|displayed] | |execute or is currently |
| | |executing. |
| | |Higher-priority tasks may|
| | |prevent the task from |
| | |running, but there is no |
| | |condition associated with|
| | |the task to keep it from |
| | |running. |
---------------------------------------------------------------
| | | |
|aborting task |Aborting_Module |The module is aborting a |
| | |task it has declared. |
---------------------------------------------------------------
| | | |
|activating child |Activating_ |The module is waiting for|
|packages |Module |child packages to become |
| | |elaborated. |
---------------------------------------------------------------
| | | |
|activating child |Activating_Tasks|The module is activating |
|tasks | |its child tasks. |
---------------------------------------------------------------
| | | |
|attempting entry |Attempting_Entry|The task is waiting for |
|call | |an accept on an entry |
| | |call to another task. |
---------------------------------------------------------------
| | | |
|being aborted |Blocking_In_ |The task is making |
| |Abort |another task abnormal |
| | |(see the Reference Manual|
| | |for the Ada Programming |
| | |Language, Section 9.10). |
---------------------------------------------------------------
| | | |
|delaying in wait |Delaying_In_ |The task is blocked in an|
|service |Wait_Service |Environment service with |
| | |a maximum wait time. |
---------------------------------------------------------------
| | | |
|in wait service |In_Wait_Service |The task is blocked in an|
| | |Environment service. |
---------------------------------------------------------------
| | | |
|package completed |In_Fs_Rendezvous|The task is waiting for |
| | |its parent to terminate |
| | |it after normal |
| | |completion of the task. |
---------------------------------------------------------------
| | | |
|terminated |Terminated |The task is terminated. |
---------------------------------------------------------------
| | | |
|waiting at accept |Blocking_On_ |The task is blocked at an|
|for entry call |Accept |accept statement, waiting|
| | |for an entry call. |
---------------------------------------------------------------
| | | |
|waiting at entry for|Blocking_On_ |The task is waiting for |
|accept |Entry |an entry call to be |
| | |accepted. |
---------------------------------------------------------------
| | | |
|waiting at select |Blocking_On_ |The task is blocked at a |
|for entry call |Select |select statement, waiting|
| | |for an entry call. |
---------------------------------------------------------------
| | | |
|waiting at |Delaying_On_ |The task is blocked in a |
|select-delay for |Select |select with a delay |
|entry call | |alternative, waiting for |
| | |an entry call. |
---------------------------------------------------------------
| | | |
|waiting at select- |Awaiting_ |The task is executing at |
|terminate for entry |Children_In_ |a select, with a ter- |
|call with dependents|Select |minate alternative, and |
| | |has dependent tasks that |
| | |cannot be terminated. |
---------------------------------------------------------------
| | | |
|waiting at select- |Terminable_In_ |The task is blocked in a |
|terminate for entry |Select |select, with a terminate |
|call | |alternative, waiting for |
| | |an entry call and can |
| | |terminate. |
---------------------------------------------------------------
| | | |
|waiting at timed |Delaying_On_ |The task is blocked at a |
|entry for accept |Entry |timed entry call waiting |
| | |for the called task to |
| | |accept the call. |
---------------------------------------------------------------
| | | |
|waiting for child |Declaring_Module|The module is declaring a|
|elaboration | |task or package. |
---------------------------------------------------------------
| | | |
|waiting for children|Awaiting_ |The task is waiting for |
| |Children |its child tasks to |
| | |terminate. |
---------------------------------------------------------------
| | | |
|waiting for delay |Delaying |The task is blocked at a |
| | |delay statement. |
---------------------------------------------------------------
| | | |
|waiting for parent |Awaiting_ |The module is waiting for|
|elaboration |Activation |a package or task it has |
| | |declared to become |
| | |activated. |
---------------------------------------------------------------
| | | |
|waiting for task |Awaiting_Task_ |The module is waiting for|
|activation |Activation |confirmation from child |
| | |tasks it has declared to |
| | |become activated. |
---------------------------------------------------------------
Note: State names are used by internal system utilities not included in
package Debug. See Operator.Internal_System_Diagnosis in the System
Management Utilities (SMU) book for more details.
PARAMETERS
For_Task : Task_Name := "";
Specifies the task for which this command displays information. The default
is the control-context task or, if the control context does not resolve to
a task name, all tasks.
The reserved name "All" specifies all tasks, unless the Task_Set parameter
specifies a task subset. Task_Set overrides For_Task if the latter specifies
all tasks.
Task_Set : Task_Category := Debug.All_Tasks;
Specifies a subset of tasks for which this command displays information.
The default value specifies all tasks. This parameter is ignored if the
For_Task parameter identifies a specific task.
ERRORS
The named task does not exist.
EXAMPLES
The following example illustrates the information listed by the
Task_Display procedure:
Job: 212, Root task: #2DCD4
ROOT_TASK, #2DCD4 (Root task): Running, waiting for children. [Pri = 1]
QUEUE, #2F0D4 (.PRODUCER_CONSUMER.QUEUE): Stop at .PRODUCER_CONSUMER.
QUEUE.7S. [Pri = 1]
PRODUCER, #2F4D4 (.PRODUCER_CONSUMER.PRODUCER): Stop at
.PRODUCER_CONSUMER.PRODUCER.4S. [Pri = 1]
CONSUMER, #2F8D4 (.PRODUCER_CONSUMER.CONSUMER): Stop at
.PRODUCER_CONSUMER.PRODUCER.4S. [Pri = 1]
The first line indicates the job number of the program being debugged and
the root task number of the job. The root task is the initial task created
for the current job being debugged.
Each entry includes the task name (if one is assigned to the task), the
task number, and the Ada name of the task in parentheses. Here, task
#2F0D4 is declared as task Queue within program unit Producer_Consumer.
Task #2DCD4 is the root task and has no Ada task declaration.
Task Queue is stopped at statement 7. Task #2DCD4 is currently not
stopped, but it is not ready to run because it is waiting for one or
more child tasks to be terminated.
@node !Commands.Debug.Task_Name
subtype Task_Name is String;
DESCRIPTION
Defines the name format for task names.
Debugger commands require a specific task name when identifying tasks. Task
names can take either of two forms: a hexadecimal number assigned by the
Environment or a user-defined string. Every task is assigned a
hexadecimal number when it is created.
Tasks can be assigned a string synonym in addition to their number. The
Set_Task_Name command can be used to assign unique task synonyms to
tasks. See the Set_Task_Name procedure for more details.
The Task_Display command lists all tasks with their number and Ada name.
Note: Task synonyms were formerly documented as task nicknames.
RESTRICTIONS
Task synonyms must be prefixed with the percent symbol (%). This character
identifies the name as a task synonym.
REFERENCES
procedure Break
procedure Execute
procedure Hold
procedure Run
procedure Set_Task_Name
procedure Stack
procedure Stop
procedure Task_Display
procedure Trace
procedure Debug_Tools.Set_Task_Name
@node !Commands.Debug.Trace
procedure Trace (On : Boolean := True;
Event : Trace_Event := Debug.All_Events;
In_Task : Task_Name := "";
At_Location : Path_Name := "<SELECTION>";
Stack_Frame : Integer := 0);
DESCRIPTION
Enables or disables tracing for a specified task.
By default, this command initiates tracing of all events occurring in all
tasks in the selected location.
The Trace procedure creates a trace request with the restrictions defined
in the parameters of the command. For each event that matches the
parameters of a trace request, the debugger displays a message in the
debugger window. These events include statements, declarations, calls,
rendezvous, and exceptions. Trace output can also be directed to a file
using the Trace_To_File command. The order in which events occur and the
debugger displays messages regarding them differs depending on the type of
event. The following list details the specific order for each event:
* Statement trace messages are displayed before the statement is
executed.
* Call trace messages are displayed before the first declaration or
statement of the subprogram is executed.
* Rendezvous trace messages are displayed before the first statement of
the rendezvous is executed.
* Exception trace messages are displayed immediately after the exception
is raised but before any stack frames are popped and before the handler
code is executed.
The debugger allows multiple simultaneous trace requests. This permits
tracing of more than one subprogram.
The Trace command does not maintain a buffer of history entries as the
Take_History command does. In a history, selected sets of messages can
be displayed, such as messages only from a specific task or for some range
of messages. See the Take_History and History_Display commands for more
information on histories.
Note: Tracing reduces execution speed.
PARAMETERS
On : Boolean := True;
Specifies whether to enable or disable the trace. By default, the trace is
enabled.
Event : Trace_Event := Debug.All_Events;
Specifies the class of execution events to be traced. The default is all
events.
In_Task : Task_Name := "";
Specifies the task to be traced. The default value is the null string ("").
Trace requests apply only to a specific task or to all tasks. If the value
is nonnull, In_Task designates the specified task. If the value is null,
In_Task designates no specific task and Trace chooses a default task based
on the control context:
* If the control context is set, the trace request is limited to the task
in the control context.
* If the control context is not set, the trace request applies to all
tasks.
At_Location : Path_Name := "<SELECTION>";
Specifies a location to which tracing is restricted. At_Location must
specify a subprogram, statement, or all locations. By default, the value
of At_Location is the selected statement or declaration, but selections
apply only if the value of Stack_Frame is 0.
The value of At_Location can be an absolute pathname, a relative pathname,
or a special name that resolves to a designated location. The values of
the At_Location parameter and the Stack_Frame parameter together designate
the actual location to which tracing is limited. These values define which
parameter has precedence in determining the location, as shown in the
following table:
Interaction of At_Location and Stack_Frame Parameters
------------------------------------
| | | |
| |Parameter |Parameter |
|If |Used |Used |
|At_Location |If |If |
|Is: |Stack_Frame|Stack_Frame|
| |= 0: |/= 0: |
------------------------------------
| | | |
|An absolute |At_Location|At_Location|
|pathname | | |
------------------------------------
| | | 1 |
|A relative |At_Location|Both |
|pathname | | |
------------------------------------
| | | |
|A special |At_Location|Stack2 |
|name | |Frame |
------------------------------------
1 If At_Location is a relative pathname and Stack_Frame is nonzero, Trace
uses both parameters to designate a location. The pathname is
prepended with _n., where n is the value of Stack_Frame. For example, if
the value of Stack_Frame is 3 and the value of At_Location is
"Commands.Filch", the pathname used is "_3.Commands.Filch".
2 If At_Location is a special name and Stack_Frame is nonzero, then
Stack_Frame overrides Location and Trace limits tracing to the
subprogram specified by Stack_Frame.
If the value of the At_Location parameter is the null string (""), the
parameter designates all locations. Also, if the value is a special name
that cannot be resolved, the parameter designates all locations.
See Chapter 2, "Referencing Objects in the Debugger," and the Path_Name
subtype for more information on designating locations.
Stack_Frame : Integer := 0;
Specifies the frame for which tracing is initiated. By default, this
parameter is ignored. Thus, this parameter is used only if it is
nonzero and if the value of At_Location is a relative pathname or a
special name. See the At_Location parameter for details.
The value of Stack_Frame can be specified with a numeric argument key if
this command is entered with a key combination.
RESTRICTIONS
The debugger allows a maximum of 20 simultaneous traces.
Tracing can be disabled only for a location in which it was enabled. The
disabling of tracing at a specific location cannot be used to achieve the
effect of tracing everywhere but in a specific location.
EXAMPLES
If the commands:
Trace (True, Statement, "%432E");
Trace (True, Call, "%542E");
Trace (True, Exception_Raised);
are issued, the sample trace messages would be:
Statement trace at !USERS.DRK.TEST_JOB.4s [Task : #432E].
Statement trace at !USERS.DRK.TEST_JOB.5s [Task : #432E].
Call trace at !USERS.DRK.READY [Task : #542E].
Call trace at !USERS.DRK.READY.SET [Task : #542E].
Call trace at !USERS.DRK.READY.GO [Task : #542E].
Call trace at !USERS.DRK.READY.GO.START [Task : #542E].
Call trace at !USERS.DRK.WAIT [Task : #542E].
Call trace at !USERS.DRK.POSTMORTEM [Task : #542E].
Exception trace at !USERS.DRK.INTERCEPT.7s [Task : #542E].
Exception was !USERS.DRK.OUT_OF_RANGE.
Each trace message identifies the type of trace, the current location of
the executing task, and the task name. Exception messages also name the
exception raised.
REFERENCES
procedure History_Display
procedure Take_History
type Trace_Event
procedure Trace_To_File
@node !Commands.Debug.Trace_Event
type Trace_Event is (All_Events, Call, Exception_Raised,
Machine_Instruction, Propagate_Exception,
Rendezvous, Statement);
DESCRIPTION
Defines the set of events that can be traced by debugger commands
(specifically the Trace and Take_History commands).
ENUMERATIONS
All_Events
Specifies calls, statements, and exceptions.
Call
Specifies subprogram calls.
Exception_Raised
Specifies points where exceptions are raised.
Machine_Instruction
Specifies execution of machine instructions.
Propagate_Exception
Not yet implemented.
Rendezvous
Not yet implemented.
Statement
Specifies all statements.
@node !Commands.Debug.Trace_To_File
procedure Trace_To_File (File_Name : String := ">> FILE NAME <<");
DESCRIPTION
Directs trace output to the file specified by the File_Name parameter.
Note: There is no default filename for this command.
The Trace_To_File procedure closes the current output file for tracing.
This command only designates an output file for trace requests; it does not
affect the application or interaction of trace requests.
If the File_Name parameter is null, this command redirects subsequent
output to the debugger window. If tracing output is currently directed
into a designated output file, the Trace_To_File ("") command redirects
tracing output to the debugger window and closes that output file.
PARAMETERS
File_Name : String := ">> FILE NAME <<";
Specifies the file to which commands send tracing output. The default
parameter placeholder must be replaced with a legal filename or the null
string (""). The null string resolves to the debugger window.
@node !Commands.Debug.Xecute
procedure Xecute (Name : Task_Name := "");
DESCRIPTION
This command is the functional equivalent of the Execute command. They can
be used interchangeably. See the Execute procedure.
REFERENCES
procedure Execute
@node !Commands.Debug_Maintenance
Package !Commands.Debug_Maintenance contains two procedures provided by
the Rational Environment debugger for interactive use.
For the specific types and subtypes and additional procedures available for
interactive use, see package !Commands.Debug.
To use the facilities of the debugger from a program, see package
!Tools.Debug_Tools.
Note: These reference entries define the functionality of the package
Debug_Maintenance commands for the R1000 native debugger. However, this
documentation also can be used for reference with debuggers included in
Rational's cross-development facilities. Examples used in these reference
entries apply to the R1000 debugger, but they also can be used with CDF
debuggers in most cases.
@node !Commands.Debug_Maintenance.Show_Version
procedure Show_Version;
DESCRIPTION
Displays the version of the current debugger.
EXAMPLES
The following is an example of a version display:
====================================
== Load Time Version Information ==
====================================
MACHINE => ARIADNE - Debugger Development (468255)
USER => PEG.S_1
DATE => June 3, 1992 at 10:10:25 AM
VERSION => 11.1.6.3
ACTIVITY => !DEB.CLI.R1000_ACTIVITY
Subsystem Spec_View Load_View Context
============= =============== ================ =======
DEBUG_SUPPORT NATIVE11_0_SPEC NATIVE_WORKING !DEB
HOST NATIVE10_1_SPEC NATIVE_WORKING !DEB
TARGET NATIVE11_0_SPEC NATIVE_WORKING !DEB
TEST_SUPPORT NATIVE10_SPEC NATIVE10_RELEASE !DEB
VERSION REV2_SPEC REV2_0 !CC
This display includes:
* Machine: Name of Rational machine on which the debugger was built
* User: Name of the user session under which the debugger was built
* Date: Date and time of the build
* Version: Version number for the current debugger
* Activity: A record of the actual activity used to build the debugger
* Subsystem, Spec_View, Load_View, and Context: Identification of the
specific subsystems used in this build
@node !Commands.Debug_Maintenance.Wait_For_Job
procedure Wait_For_Job;
DESCRIPTION
Causes the calling subprogram to wait while the debugger has the running
flag on.
This command is used in debugging scripts to control the flow in the
script. The command allows a script to wait for the current program to
stop before proceeding to the next step in the script.
If written as procedures, debugging scripts can be made part of a
permanent testing or regression-testing suite.
EXAMPLES
Assume that the following script is run from a command window while
debugging the Demo program. The script sets a breakpoint in the Factorial
subprogram, immediately after the local variable F has been set. Each
time the debugger stops at the breakpoint, the script displays the value
of F.
The Wait_for_Job command after each Debug.Execute command ensures that the
new value of F has been set before the script displays it.
with Debug;
with Debug_Maintenance;
procedure Example_Test_Script is
begin
Debug.Break
(".Demo.Factorial.3s"); -- Set break in Factorial
Debug.Execute; -- Run program in debugger
Debug_Maintenance.Wait_For_Job; -- Wait until debugger stops
Debug.Put ("F"); -- Display local variable
Debug.Execute; -- Allow program to continue
Debug_Maintenance.Wait_For_Job; -- Wait until debugger stops
Debug.Put ("F"); -- Display variable again
Debug.Execute; -- And so on ...
Debug_Maintenance.Wait_For_Job;
Debug.Put ("F");
end Example_Test_Script;
@node !Tools.Debug_Tools
Package !Tools.Debug_Tools provides procedures and functions through which
programs can use the facilities of the Rational Environment debugger.
For interactive debugger commands, see package !Commands.Debug and package
!Commands.Debug_Maintenance.
The procedures and functions of package Debug_Tools make interactive
debugging easier by:
* Performing tedious setup steps automatically, such as setting task
names
* Defining regions of code that do not need debugging or must run without
interference from the debugger
* Performing repetitive debugging steps automatically, such as displaying
a message or stack trace each time a particular place in the program is
reached
* Providing extra information, such as exception identification, beyond
that provided by the interactive debugger
* Providing special type displays of nonstandard data
* Supporting the creation of user-defined debugging commands
Note: The procedures and functions of Debug_Tools are executed when
called, whether or not the calling program is currently being debugged. If
time is critical in the application, use Debug_Tools sparingly or only in
nontime-critical locations.
RESOURCES IN PACKAGE DEBUG_TOOLS
The commands in package Debug_Tools fall into several functional groups.
This list includes all procedures, functions, and types in package
Debug_Tools.
Displaying program source locations: Ada_Location
Controlling debugging: Debug_Off, Debug_On, Debugging
Getting exception information: Get_Exception_Name,
Get_Raise_Location
Naming tasks: Get_Task_Name, Set_Task_Name
Annotating a debugging session: Message
Displaying data in special formats: Register, Register.Image, Register.T,
Un_Register, Un_Register.T
USING PACKAGE DEBUG_TOOLS WITH CROSS-DEBUGGERS
A version of package Debug_Tools is available with each Rational debugger.
However, the versions of package Debug_Tools included with Rational's
Cross-Development Facility (CDF) debuggers are substantially different
from the R1000 version documented here. This section summarizes the
similarities and differences.
The procedures and functions of Debug_Tools are always available to a
program, not only while it is running on the Rational Environment but also
after it has been downloaded to a final target where Environment resources
are not available. On the R1000, Debug_Tools is part of the Environment.
For CDF targets, any portion of Debug_Tools that a program uses is made
part of the program and downloaded with it.
All subprogram specifications, except for generic procedure Un_Register,
are the same on both R1000 and CDF versions of package Debug_Tools. This
allows code developed and tested in an R1000 view to be compiled in a
target-specific view with no code changes.
CDF versions of package Debug_Tools differ from the R1000 version in three
important ways:
* Space usage: Unlike the R1000 version of package Debug_Tools, which is
an integral part of the Rational Environment, CDF versions of
Debug_Tools are actually compiled and linked into the program being
debugged. As a result, any portion of Debug_Tools that a program uses
takes up space on the target machine. If space is critical on a CDF
target, consider not using Debug_Tools.
* Portability: In CDF versions of package Debug_Tools, generic procedure
Un_Register has one extra parameter. As a result, code that uses
procedure Un_Register must be modified when moved from an R1000 view to
a target-specific view. If portability is important, consider not using
this procedure.
* Effect: In CDF versions of package Debug_Tools, some subprograms may be
null stubs or may have nonstandard effects. For example, the
Ada_Location function cannot provide information on Ada source
locations on a target that does not have Ada source available; a CDF
version might return the local machine address instead.
The reference entries in this document define the functionality of the
tools in package Debug_Tools for the R1000 native debugger. This document
is also a general reference for CDF versions of the package. Examples used
in these reference entries apply to the R1000 debugger and, in most cases,
to the CDF debuggers.
See the debugger section of your CDF manual for details of specific CDF
implementations.
@node !Tools.Debug_Tools.Ada_Location
function Ada_Location (Frame_Number : Natural := 0;
Fully_Qualify : Boolean := True;
Machine_Info : Boolean := False)
return String;
DESCRIPTION
Returns the source location of a direct or indirect call to this function.
This function returns the source location of a call to this function or
the source location of any subprogram call that leads indirectly to a call
to this function. The level of the call in the calling stack is determined
by the value of the Frame_Number parameter.
The null string is returned if the frame specified by the Frame_Number
parameter does not exist.
This function can be used to provide call-stack traceback under control of
the application program. For traceback during interactive debugging, see
the Debug.Stack procedure.
PARAMETERS
Frame_Number : Natural := 0;
Specifies, when Frame_Number = 0, that the source location of the call to
Ada_Location be returned. Frame_Number = 1 specifies that the source
location of the call to the caller of Ada_Location be returned, and so on.
Fully_Qualify : Boolean := True;
Specifies whether to return the source location as a fully qualified
pathname. The default value is True.
When False, only the simple name of the subprogram that contains the
source location is returned.
Machine_Info : Boolean := False;
Specifies whether to include machine information in the string returned by
Ada_Location. The default value is False.
The machine information returned will be different for different targets.
return String;
Returns the Ada name of the specified source location. The name is returned
as a string. Setting the Fully_Qualify and Machine_Info parameters to True
increases the length of the string.
The string may contain blanks, but it will not contain control characters.
ERRORS
If no debugger is active for the session (either because no jobs have been
debugged since the user logged in or because the debugger has been
killed), Ada_Location returns the string Unknown - Debugger not started.
If Ada_Location references a frame for which no name is currently
available, it returns the string Unknown location.
EXAMPLES
Example 1
The statement:
Io.Put_Line (Debug_Tools.Ada_Location);
displays in an Environment output window the fully qualified source
location of the call to Ada_Location. For example, if this line were
executed in a library-level procedure Debug_Tools_Examples, the output
would be:
.DEBUG_TOOLS_EXAMPLES.2s
The same statement executed in subprogram Sub1 would display:
.DEBUG_TOOLS_EXAMPLES.SUB1.2s
Example 2
Sometimes it is useful to know not just the current source location but
also the execution path that led to this location. In interactive
debugging, the Debug.Stack command provides a traceback of the flow of
execution. Calling Ada_Location with the Frame_Number parameter greater
than zero provides a similar traceback under control of the running
program. For example, if these statements:
Io.Put_Line (Debug_Tools.Ada_Location);
Io.Put_Line (Debug_Tools.Ada_Location (Frame_Number => 1));
Io.Put_Line (Debug_Tools.Ada_Location (Frame_Number => 2));
are executed in procedure Sub2 of library procedure Debug_Tools_Examples,
the following is displayed in an Environment output window:
.DEBUG_TOOLS_EXAMPLES.SUB2.2s
.DEBUG_TOOLS_EXAMPLES.4s
.command_procedure.1s
The first line shows the source location of the call to Ada_Location. The
second line shows the location in Debug_Tools_Examples of this particular
call to Sub2. The third line shows that Debug_Tools_Examples was called
from a command procedure, in this case by executing it from a command
window.
Example 3
Display of execution flow is particularly helpful with library subprograms
and subprograms in library packages, either of which can be called from
many unrelated places in a system. If an error is detected in such a
subprogram, identifying the source of the call can be very difficult.
Ada_Location makes this easy. For example, assume a library package
More_Examples, which includes a visible subprogram Ada_Location_Example
(declared in the package specification) and a hidden subprogram Hidden
(declared only in the package body). If the same statements as in Example
2, above, are executed in the hidden procedure, and the visible procedure
is called from the example program, the following is displayed in the
Environment output window:
.MORE_EXAMPLES.HIDDEN.1s
.MORE_EXAMPLES.ADA_LOCATION_EXAMPLE.1s
.DEBUG_TOOLS_EXAMPLES.SUB3.2s
The first line shows the source location of the call to Ada_Location, which
in this case is in the hidden subprogram Hidden in package More_Examples.
The second line shows the location of the call to the hidden subprogram,
in this case in the visible subprogram Ada_Location_Example, in the same
package. The third line shows the location of the call to
Ada_Location_Example from outside the package, specifically in subprogram
Sub3 of program Debug_Tools_Examples.
Example 4
To display machine information, set the Machine_Info parameter to True:
Io.Put_Line (Debug_Tools.Ada_Location (Machine_Info => True));
The machine information shown will be different for different targets. On
the R1000, the following is displayed in an Environment output window:
.DEBUG_TOOLS_EXAMPLES.7s Pc = #7DD02, #39, Frame = #14F8BC, #18,
Lex = 2, Outer = #14FCBC, #0
In addition to the Ada source location, this version of the command
displays:
* Pc: Segment and offset
* Frame: Address of the current frame
* Lex: Static nesting depth of the procedure within which the object is
declared;
0 = import space, 1 = packages and tasks, 2+ = subprograms and blocks
* Outer: Address of the frame that corresponds to lex = 1
REFERENCES
procedure Debug.Stack
@node !Tools.Debug_Tools.Debug_Off
procedure Debug_Off;
DESCRIPTION
Disables debugging for the task calling this procedure.
Debug_Off disables all the structured execution features of the debugger,
including stepping, breaking, exception trapping, and so on. With
debugging disabled, the task executes normally, free from any interference
by the debugger.
The two procedures Debug_Off and Debug_On allow a program to define a
region in which the debugger will not interfere with program execution. To
define such a region, call procedure Debug_Off at the beginning of the
region to disable debugger interference, and then call procedure Debug_On
at the end of the region to resume debugger control. During execution in
this region, the task will run normally between Debug_Off and Debug_On,
without interference from the debugger or the debugger operator.
The debugger allows successive calls to Debug_Off and Debug_On so that
subprograms that do not require debugging can execute without
restrictions.
The initial debugging status of a task depends on the status of its parent
task at the time it was created. Debugging is initially disabled for all
child tasks created while debugging was disabled for the parent. Debugging
is initially enabled for all child tasks created while debugging was
enabled for the parent.
RESTRICTIONS
If this procedure is called from a job not currently being debugged, the
call is ignored and has no effect.
REFERENCES
procedure Debug_On
function Debugging
@node !Tools.Debug_Tools.Debug_On
procedure Debug_On;
DESCRIPTION
Enables debugging for the task calling this procedure.
Debug_On reenables debugging after it has been disabled with the Debug_Off
procedure. A task calling this procedure will subsequently execute with
all debugger-structured execution features enabled, including stepping,
breaking, exception trapping, and so on.
The two procedures Debug_Off and Debug_On allow a program to define a
region in which the debugger will not interfere with program execution. To
define such a region, call procedure Debug_Off at the beginning of the
region to disable debugger interference, and then call procedure Debug_On
at the end of the region to resume debugger control. During execution in
this region, the task will run normally between Debug_Off and Debug_On,
without interference from the debugger or the debugger operator.
The debugger allows successive calls to Debug_Off and Debug_On so that
subprograms that do not require debugging can execute without
restrictions.
The initial debugging status of a task depends on the status of its parent
task at the time it was created. Debugging is initially disabled for all
child tasks created while debugging was disabled for the parent. Debugging
is initially enabled for all child tasks created while debugging was
enabled for the parent.
Note: This procedure cannot initiate debugging from within a program that
was started without debugging enabled.
RESTRICTIONS
If this procedure is called from a job not currently being debugged, the
call is ignored and has no effect.
REFERENCES
procedure Debug_Off
function Debugging
@node !Tools.Debug_Tools.Debugging
function Debugging return Boolean;
DESCRIPTION
Returns a Boolean value indicating whether the currently executing program
is under control of the debugger, whether or not debugging is currently
enabled.
PARAMETERS
return Boolean;
Returns a Boolean value of True when the currently executing program is
under control of the debugger, whether or not debugging is currently
enabled; otherwise, the function returns False.
REFERENCES
procedure Debug_Off
procedure Debug_On
Editing Specific Types (EST), procedure Commands.Debug
@node !Tools.Debug_Tools.Get_Exception_Name
function Get_Exception_Name (Fully_Qualify : Boolean := True;
Machine_Info : Boolean := False)
return String;
DESCRIPTION
Returns the name of the exception most recently raised in the calling
task.
This function must be called directly or indirectly from an exception
handler. It returns the null string ("") if no exceptions are currently
active in the calling task.
If Machine_Info is enabled (True), the Get_Exception_Name function returns
both the machine representation of the most recently raised exception and
the machine address at which that exception was raised (the "raise
address"). You can then use this returned information in interactive
debugger commands. Invoking the Debug.Exception_To_Name command with the
exception's machine representation displays the name of the exception,
if the Ada units still exist and the exception was not raised or declared
in a command window. Invoking the Debug.Address_To_Location command with
the raise address displays the source location of the exception, with the
same restrictions.
PARAMETERS
Fully_Qualify : Boolean := True;
Specifies whether to return the exception name with a fully qualified
pathname. The default value is True.
When False, only the simple name of the exception is returned.
This parameter applies only to user-defined exceptions. With predefined
exceptions, only the simple name of the exception is returned,
regardless of the value of this parameter.
Machine_Info : Boolean := False;
Specifies whether machine information is returned. The default value is
False.
If the value of this parameter is True, the returned string includes the
address of the frame in which the exception was raised and the machine
representation of the exception. See Chapter 6, "Manipulating Exceptions,"
for an explanation of exception representations.
return String;
Returns information about the exception. The string may be relatively long
(that is, greater than 80 characters), especially if Fully_Qualify and
Machine_Info are both True.
ERRORS
If Get_Exception_Name is called while the task is not in an exception
handler, the following is displayed in an Environment output window:
Unknown exception raised at unknown address.
EXAMPLES
If a task is in an exception handler because of a Program_Error exception
and issues the call:
Io.Put_Line (Debug_Tools.Get_Exception_Name);
the following is displayed in an Environment output window:
Program_Error
If the Machine_Info parameter is set True in the call, as in:
Io.Put_Line (Debug_Tools.Get_Exception_Name (True, True));
the following is displayed in the Environment output window:
Program_Error<Space= 0, Index= 226> raised at #61902, #1B
You can then use the returned information in the following interactive
debugger commands:
Debug.Exception_To_Name ("0, 226");
Debug.Address_To_Location ("#61902, #1B");
which cause the following to be displayed in the debugger window:
Exception_To_Name ("0, 226");
Name: Predefined exception PROGRAM_ERROR
Address_To_Location ("#61902, #1B");
Name: .DEBUG_TOOLS_EXAMPLES.14s
PC = #61902, #1B
REFERENCES
procedure Debug.Address_To_Location
subtype Debug.Exception_Name
procedure Debug.Exception_To_Name
@node !Tools.Debug_Tools.Get_Raise_Location
function Get_Raise_Location (Fully_Qualify : Boolean := True;
Machine_Info : Boolean := False)
return String;
DESCRIPTION
Returns the address at which the most recent exception was raised in the
calling task.
This function must be called directly or indirectly from an exception
handler. It returns the null string ("") if no exceptions are currently
active in the calling task.
If Machine_Info is enabled (True), the Get_Raise_Location function returns
both the machine representation of the most recently raised exception and
the machine address at which that exception was raised (the "raise
address"). You can then use this returned information in interactive
debugger commands. Invoking the Debug.Exception_To_Name command with the
exception's machine representation displays the name of the exception,
if the Ada units still exist and the exception was not raised or declared
in a command window. Invoking the Debug.Address_To_Location command with
the raise address displays the source location of the exception, with the
same restrictions.
See Debug.Raise_Location for a list of valid exception names.
PARAMETERS
Fully_Qualify : Boolean := True;
Specifies whether the exception name is returned fully qualified. The
default value is True.
Machine_Info : Boolean := False;
Specifies whether machine information is returned. The default value is
False.
If the value of this parameter is True, the returned string includes the
address of the frame in which the exception was raised and the machine
representation of the exception. See Chapter 6, "Manipulating Exceptions,"
for an explanation of exception representations.
return String;
Returns information about the exception. The string may be relatively long
(that is, greater than 80 characters), especially if Fully_Qualify and
Machine_Info are both True.
RESTRICTIONS
If no debugger is active for the session (either because no jobs have been
debugged since the user logged in or because the debugger has been
killed), this function returns only low-level machine information:
Task #1CCD4:
Program_Error<Space= 0, Index= 226> raised at #61902, #1B
EXAMPLES
If a task with number 1CCD4 is in an exception handler because of a
Program_Error exception and issues the call:
Io.Put_Line (Debug_Tools.Get_Raise_Location);
the following is displayed in an Environment output window:
Task ROOT_TASK, #1CCD4:
Exception Program_Error raised at: .DEBUG_TOOLS_EXAMPLES.14s.
If the Machine_Info parameter is set True in the call, as in:
Io.Put_Line (Debug_Tools.Get_Raise_Location (True, True));
the following is displayed in the Environment output window:
Task ROOT_TASK, #1CCD4:
Exception Program_Error raised at: .DEBUG_TOOLS_EXAMPLES.14s.
Control offset: #19, Raise Pc: #61902, #1B, Exception name: (#E2)
You can then use the returned information in the following interactive
debugger commands:
Debug.Exception_To_Name ("#E2");
Debug.Address_To_Location ("#61902, #1B");
which cause the following to be displayed in the debugger window:
Exception_To_Name ("#E2");
Name: Predefined exception PROGRAM_ERROR
Address_To_Location ("#61902, #1B");
Name: .DEBUG_TOOLS_EXAMPLES.14s
PC = #61902, #1B
REFERENCES
procedure Debug.Address_To_Location
subtype Debug.Exception_Name
procedure Debug.Exception_To_Name
@node !Tools.Debug_Tools.Get_Task_Name
function Get_Task_Name return String;
DESCRIPTION
Returns a string synonym set by the Set_Task_Name procedure.
This function allows a task to interrogate its name. If no synonym has
been assigned to the calling task, the null string ("") is returned.
Note: Task synonyms were formerly documented as task nicknames.
PARAMETERS
return String;
Returns the synonym set by the Set_Task_Name procedure. The null string
("") is returned if no name has been assigned.
RESTRICTIONS
If this function is called from a job not currently being debugged, the
call always returns the null string ("").
EXAMPLES
If the root task of a program is being debugged and issues the call:
Io.Put_Line (Debug_Tools.Get_Task_Name);
the following is displayed in an Environment output window:
Root_Task
If the program had first set the name of its root task to "Main" by calling
the Set_Task_Name procedure, the following would have been displayed:
Main
REFERENCES
procedure Set_Task_Name
procedure Debug.Set_Task_Name
@node !Tools.Debug_Tools.Message
procedure Message (Info : String);
DESCRIPTION
Displays a message in the debugger window.
This procedure displays the string specified by the Info parameter.
This procedure can be used to place comments in the debugger window for
annotation of a debugging session.
PARAMETERS
Info : String;
Specifies the string to be displayed in the debugger window.
Multiple lines must be separated with linefeed characters (character type
Ascii.Lf).
EXAMPLES
If a task with number 1CCD4 issues the call:
Debug_Tools.Message ("here is a message");
the following message is displayed in the debugger window:
From task: ROOT_TASK, #1CCD4: here is a message
@node !Tools.Debug_Tools.Register
generic
type T is limited private;
with function Image (Value : T;
Level : Natural;
Prefix : String;
Expand_Pointers : Boolean) return String;
procedure Register;
DESCRIPTION
Registers a special display for a type with the debugger.
This generic procedure provides facilities that enable you to write
special type displays for the debugger. The debugger uses these routines
to format and display the value of variables and to perform other actions.
These display routines can be created for any object type defined in
the Rational Environment or in your applications.
Display routines must be created and then registered with the debugger. If
no special display is registered for a type, the debugger uses the
structural type information from the type declaration when the Debug.Put
command is executed on objects of that type. Once a special display is
registered for a type, the debugger uses the special type display instead
of the structural type information.
To implement a special display for a given type:
1. Create an appropriate Image function for the type. An Image function is
a function that returns an image (that is, a predefined display) of
the value of an object of that type. See the reference entry for
generic formal function Register.Image for a complete description of
Image functions.
2. Instantiate the generic procedure Register, giving as its parameters
the type for which you want a special display and the name of your
Image function for that type.
3. Call the instantiation from your application.
Registering a new special display for a type overrides both the type's
default structural display and any existing special display for the type.
If another special display is currently registered for the type, it is
automatically unregistered and the new function is substituted.
Special displays can also be unregistered to return to the use of a type's
normal structural display. See the reference entry for generic procedure
Un_Register.
Special type displays can be registered in two ways:
* In the default Debugger_Initialization procedure, which executes when
the debugger is started. In this case, the special display remains in
effect until explicitly unregistered, a new special display is
registered for the type, the user logs off from the session, or the
debugger is killed.
* In the job being debugged. In this case, the special display remains in
effect during the life of the job, until the special display is
explicitly unregistered, or until a new special display is registered
for the type.
The debugger has preregistered special displays for many of the important
types defined in the specifications of the Rational Environment. These
preregistered special displays can be redefined if necessary. For a list of
these types, see the section below entitled "Preregistered Special Type
Displays."
The Debug.Show (Debug.Special_Types) debugger command lists the special
type displays registered by the user for the job currently being debugged.
Note that this list will not include the Environment types
automatically registered by the debugger.
RESTRICTIONS
Many important restrictions apply to the Image function being registered.
See the "Restrictions" section of the reference entry for the generic
formal function Register.Image.
The source code for instantiations of the Register procedure must be on
the system on which the program being debugged is executing. This is an
important restriction to consider when using software that has been
distributed in the form of a code view. The code view can include the
Image functions needed for registration. However, views containing the
actual source code for the registration must exist on the same system as
the code view.
EXAMPLE 1
Even when a structural display is available for a type, a special display
may be more convenient to use. For example, data structures containing
pointers are often difficult to visualize from the structural display. The
following example shows how a special display can be constructed for
lists. This special display outputs the elements in the list as a text
string instead of as a pointer chain connecting the list elements, which
would be the case if a structural display were used.
------------------------------
with List_Generic;
package Integer_List is new List_Generic (Integer);
-- Example uses list generic from !Tools.
------------------------------
package List_Display is
-- This package implements the special display for values
-- of type Integer_List.List.
procedure Register;
-- Causes the special display to be registered with the
-- debugger so that it will be used by the debugger in
-- subsequent Debug.Put commands instead of the normal
-- structural display.
end List_Display;
------------------------------
with Integer_List;
with Debug_Tools;
with String_Utilities;
package body List_Display is
function Element_Images (Value : Integer_List.List)
return String is
-- This recursive function builds a string containing the
-- images of the items in a list ordered from left to right.
begin
if Integer_List.Is_Empty (Value) then
return "";
else
return String_Utilities.Number_To_String
(Integer_List.First (Value)) & " " &
Element_Images (Integer_List.Rest (Value));
end if;
end Element_Images;
function Image (Value : Integer_List.List;
Level : Natural;
Prefix : String;
Expand_Pointers : Boolean) return String is
-- The Image function used in this special display displays
-- lists with their elements ordered from left to right
-- enclosed in parentheses. For example: "( 1 2 3 )".
begin
if Integer_List.Is_Empty (Value) then
return "the list is empty";
else
return "( " & Element_Images (Value) & ")";
end if;
end Image;
procedure Register_Special_Display is
new Debug_Tools.Register (Integer_List.List, Image);
procedure Register is
begin
Register_Special_Display;
end Register;
begin
Register; -- Registers the special display upon elaboration.
end List_Display;
------------------------------
with Text_Io;
with Integer_List;
with List_Display;
procedure List_Test is
-- This is a main program used to test the special display
-- for Integer_List.List.
L : Integer_List.List := Integer_List.Nil;
begin
L := Integer_List.Make (3, L);
L := Integer_List.Make (2, L);
L := Integer_List.Make (1, L);
null; -- A location on which to stop the debugger.
end List_Test;
------------------------------
Assume that the List_Test procedure is run with the debugger and stepped
to the null statement. If the Debug.Put command is executed at this point
to display the value of L (Debug.Put ("L");), the debugger responds as
follows in the debugger window:
Put ("%ROOT_TASK._1.L");
{( 1 2 3 )}
EXAMPLE 2
Sometimes it is helpful in testing an application program to be able to
initiate the execution of subprograms as part of the job being debugged.
For example, when debugging an application using the debugger, it might be
helpful to be able to reset some of the state of the application, display
status information, or dump or restore state, all by executing debugger
commands at certain times. The special-display facility can be used to do
this.
The strategy consists of defining types and objects of these types for each
of the operations that you would like to trigger from the debugger.
Special-display functions are then created and registered for each of
these types. These special-display functions perform the actions desired.
Finally, to invoke the special display and to perform the action while
debugging, simply execute the Debug.Put command on the object
corresponding to the action you want to perform. The debugger will execute
the associated special-display routine that will perform the action.
Here is a simple example of a package that implements such a strategy.
Note that the package would be withed into the library-unit closure of the
application. In this example, the only effect of the operations is to
write a message into a text file. These actions typically would
manipulate various pieces of the state of the application.
------------------------------
package Debugger_Operations is
-- This package implements various testing operations using
-- the debugger special-display mechanism. To perform the
-- desired action, perform a Debug.Put command on the object
-- of the appropriate type.
type Reset_Type is new Boolean;
type Display_Status_Type is new Boolean;
type Dump_State_Type is new Boolean;
type Restore_State_Type is new Boolean;
-- Performing a Debug.Put on the following objects causes
-- the associated action to be performed by the special
-- display for their types.
Reset : Reset_Type := True;
Display_Status : Display_Status_Type := True;
Dump_State : Dump_State_Type := True;
Restore_State : Restore_State_Type := True;
end Debugger_Operations;
------------------------------
with Text_Io;
with Debug_Tools;
package body Debugger_Operations is
File : Text_Io.File_Type;
Resetting : constant String := "...Resetting";
Displaying_Status : constant String := "...Displaying status";
Dumping_State : constant String := "...Dumping state";
Restoring_State : constant String := "...Restoring state";
function Reset_Implementation (Value : Reset_Type;
Level : Natural;
Prefix : String;
Expand_Pointers : Boolean)
return String is
begin
Text_Io.Put_Line (File, Resetting);
return Resetting;
end Reset_Implementation;
function Display_Status_Implementation
(Value : Display_Status_Type;
Level : Natural;
Prefix : String;
Expand_Pointers : Boolean) return String is
begin
Text_Io.Put_Line (File, Displaying_Status);
return Displaying_Status;
end Display_Status_Implementation;
function Dump_State_Implementation
(Value : Dump_State_Type;
Level : Natural;
Prefix : String;
Expand_Pointers : Boolean) return String is
begin
Text_Io.Put_Line (File, Dumping_State);
Text_Io.Close (File);
return Dumping_State;
end Dump_State_Implementation;
function Restore_State_Implementation
(Value : Restore_State_Type;
Level : Natural;
Prefix : String;
Expand_Pointers : Boolean) return String is
begin
Text_Io.Put_Line (File, Restoring_State);
return Restoring_State;
end Restore_State_Implementation;
procedure Special_Display_Reset is
new Debug_Tools.Register (Reset_Type,
Reset_Implementation);
procedure Special_Display_Display_Status is
new Debug_Tools.Register (Display_Status_Type,
Display_Status_Implementation);
procedure Special_Display_Dump_State is
new Debug_Tools.Register (Dump_State_Type,
Dump_State_Implementation);
procedure Special_Display_Restore_State is
new Debug_Tools.Register (Restore_State_Type,
Restore_State_Implementation);
begin
Special_Display_Reset;
Special_Display_Display_Status;
Special_Display_Dump_State;
Special_Display_Restore_State;
Text_Io.Create (File, Text_Io.Out_File, "$log_file");
end Debugger_Operations;
EXAMPLE 3
For debugging applications containing types with complex structures, it is
often desirable to obtain different displays of the images of these types.
For example, you may want to obtain more or less detail, or you may want
to look at different classes of information at different times during the
debugging session. There are two approaches to using special displays to
accomplish this.
One approach is to use variables in the special display packages to
indicate the level of detail or kind of information desired. The image
functions implementing the special display for a type can read these
variables and, depending on their values, perform different actions. The
values of these variables can be manipulated by the Debug.Modify command
or by the special displays, as described in Example 2 above.
The other approach is to create multiple special displays and register and
unregister them dynamically at various points in your application. Note
that this registration/unregistration can be accomplished explicitly in
the application or by the special displays, as described in Example 2
above.
PREREGISTERED SPECIAL TYPE DISPLAYS
There are preregistered special displays for many of the important types
defined in the specifications of the Rational Environment. These
preregistered special displays can be redefined, if necessary. The types
for which displays are preregistered include:
!Implementation.Activity_Implementation.Activity_Handle
!Implementation.Activity_Implementation.Iterator
!Implementation.Dependency_Data_Base.Defid_Iterator
!Implementation.Dependency_Data_Base.Iterator
!Implementation.Diana.Attr_List
!Implementation.Diana.Attr_Name
!Implementation.Diana.Comment
!Implementation.Diana.Number_Rep
!Implementation.Diana.Seq_Type
!Implementation.Diana.Sequence
!Implementation.Diana.Symbol_Rep
!Implementation.Diana.Temp_Seq
!Implementation.Diana.Tree
!Implementation.Diana.Value
!Implementation.Directory.Ada.Unit
!Implementation.Directory.Class
!Implementation.Directory.Naming.Iterator
!Implementation.Directory.Object
!Implementation.Directory.Object_Set.Iterator
!Implementation.Directory.Object_Set.Set
!Implementation.Directory.Traversal.Associated_Object_Iterator
!Implementation.Directory.Traversal.Object_Iterator
!Implementation.Directory.Traversal.Subobject_Iterator
!Implementation.Directory.Traversal.Subunit_Iterator
!Implementation.Directory.Traversal.Version_Iterator
!Implementation.Directory.Version
!Implementation.Dtia_Client.Cursor
!Implementation.Dtia_Client.Image_Id
!Implementation.Dtia_Client.Selection
!Implementation.Error_Messages.Annotation
!Implementation.Error_Messages.Errors
!Implementation.Links_Implementation.Iterator
!Implementation.Low_Level_Action.Id
!Implementation.Switch_Implementation.Iterator
!Implementation.Universal.Float
!Implementation.Universal.Int
!Implementation.Universal.Integer
!Implementation.Universal.Real
!Io.Device_Independent_Io.File_Type
!Io.Io.File_Type
!Io.Object_Set.Iterator
!Io.Object_Set.Set
!Io.Pipe.Handle
!Io.Polymorphic_Io.File_Position
!Io.Polymorphic_Io.Handle !Io.Polymorphic_Sequential_Io.File_Type
!Io.Text_Io.File_Type
!Io.Window_Io.File_Type
!Lrm.Calendar.Time
!Tools.Bounded_String.Variable_String
!Tools.Design.Abstract_Document.Format_Info
!Tools.Design.Abstract_Document.Handle
!Tools.Design.Abstract_Document.Linkage_Info
!Tools.Design.Abstract_Document.Node
!Tools.Design.Document.Element
!Tools.Design.Document.Element_List
!Tools.Design.Element_Cache.Handle
!Tools.Design.Mapping.Target_Info
!Tools.Design.Pdl.Area
!Tools.Directory_Tools.Object.Error_Code
!Tools.Directory_Tools.Object.Handle
!Tools.Directory_Tools.Object.Iterator
!Tools.Directory_Tools.Object.Message_List
!Tools.Directory_Tools.Object.Subclass
!Tools.Gateway_Object.Handle
!Tools.Link_Tools.Dependent_Iterator
!Tools.Link_Tools.Link_Iterator
!Tools.Lrm.Ada_Program.Element
!Tools.Lrm.Ada_Program.Element_Iterator
!Tools.Lrm.Ada_Program.Element_List
!Tools.Lrm.Ada_Program.Line_Iterator
!Tools.Networking.Transport.Connection_Id
!Tools.Networking.Transport.Connection_Id_Iterator
!Tools.Networking.Transport.Network_Name_Iterator
!Tools.Networking.Transport.Route.Iterator
!Tools.Networking.Transport_Name.Host_Iterator
!Tools.Networking.Transport_Name.Service.Iterator
!Tools.Profile.Response_Profile
!Tools.Simple_Status.Condition
!Tools.Simple_Status.Condition_Name
!Tools.String_Table.Item
!Tools.String_Table.Iterator
!Tools.System_Utilities.Job_Iterator
!Tools.System_Utilities.Session_Iterator
!Tools.System_Utilities.Terminal_Iterator
!Tools.Tape_Tools.Logical_Device
!Tools.Unbounded_String.Variable_String
REFERENCES
generic formal function Register.Image
generic formal type Register.T
generic procedure Un_Register
procedure Debug.Show
type Debug.State_Type, enumeration Special_Types
@node !Tools.Debug_Tools.Register.Image
with function Image (Value : T;
Level : Natural;
Prefix : String;
Expand_Pointers : Boolean) return String;
DESCRIPTION
Returns a string that is the image of the value of the Value parameter.
The Image function returns a string that is an image (that is, a predefined
display) of the value of an object. The form and content of the image
depend on the user-defined type of the object. See generic procedure
Register for details regarding object types.
Display of Structured Objects
When displaying a structured object, such as a record, the debugger
displays the number of levels of structure specified by the Display_Level
numeric flag (Debug.Numeric.Display_Level). For example, if a record has
five levels of subrecords, and Display_Level is set to 3, only the top
three levels of the record are displayed.
The debugger manages this through an internal Level parameter that tracks
the number of levels to be displayed for the current structure. It is
initialized to the value of the Display_Level flag for each Put command,
reduced by 1 each time the debugger steps into a substructure, and
increased by 1 each time a substructure is finished. (Actually, the
traversal over a structure is implemented recursively, with (Level - 1)
passed to the Level parameter of the display subprogram when a sub-
structure is displayed.) When Level = 0 for a substructure, it is elided;
that is, nothing from the substructure is displayed.
If a special display is currently registered for a type, the debugger
always uses the registered Image function when displaying objects of that
type, even if the object being displayed is embedded in a larger
structure. For example, if a record has as one of its components an object
for which a special display has been registered, the debugger will call
the registered Image function to display that one object and use the
default structural display for the remainder of the record.
When calling an Image function, the debugger passes to the Level parameter
of the Image function the number of levels remaining to be displayed
(Level - 1). Thus the number of levels actually displayed by a given Image
function varies depending on the display nesting depth at the time the
Image function is called. If the Display_Level flag is set to 3, and the
debugger is already two levels deep in a record when an Image function is
called, the Image function displays only one additional level.
The debugger uses the Pointer_Level numeric flag
(Debug.Numeric.Pointer_Level) in a manner similar to the way Display_Level
is used, except that it is decreased only when a pointer is traversed. If
the current pointer level is greater than or equal to 1 when a registered
Image function is called, the debugger returns True to the Expand_Pointers
parameter of the Image function; otherwise, the debugger returns False.
User-Supplied Image Functions
For user-defined special displays, the Image function is written by the
user. It is recommended that the user's function follow the same
conventions used by the debugger and by the predefined Image functions.
However, this is not required.
The user's Image function should follow the same conventions with Level as
used by the debugger, but this is not required. For example, if Level = 1
is passed to a user-supplied Image function, the function should display
only one level of the specified object, but it can display more levels and
the debugger will still work. When Level = 0 for a substructure, nothing
from the substructure should be displayed.
A user's Image function should (but is not required to) use the value of
the Expand_Pointers parameter to determine whether to traverse pointers
when producing the image of an object.
A user's Image function should (but is not required to) prepend the Prefix
string to each display line after the first.
PARAMETERS
Value : T;
Specifies the value for which the image is to be computed.
Level : Natural;
Specifies the number of levels of detail to be displayed. This is
determined dynamically by the nesting level of Value in the structure
being displayed by the debugger and by the value of the Display_Level
flag. If Level = 0, the entire value should be elided (omitted).
Prefix : String;
Specifies the string to be prepended to the beginning of display lines
after the first. Each new line (that is, every segment following an
Ascii.Lf line terminator character) in the returned string should have
this prefix.
Expand_Pointers : Boolean;
Specifies, when enabled, that internal pointers should be traversed and
expanded when producing the image of the object. This is determined
dynamically by the nesting level of Value in the structure being displayed
by the debugger and by the value of the Pointer_Level flag.
return String;
Returns the image of the value of the Value parameter.
RESTRICTIONS
An Image function used to instantiate the generic Register procedure must
be defined in a place where it will still be elaborated when invoked by the
debugger. (This is consistent with the rules of Ada; it is illegal to
invoke a function that is not currently elaborated.) The easiest way to
ensure this is to declare the function registered with the debugger as a
type T's special-display function at the same level as T. For example, if
T is defined at the top level of a package P, the special-display function
for T should also be defined at the top level of P.
The Image function cannot call the debugger (specifically, it cannot call
any of the subprograms in packages Debug or Debug_Tools). Further, the
code in the Image function cannot be debugged using the debugger when
implicitly called as a result of performing the Debug.Put command. That
is, when specifying a special display with Put, the debugger cannot access
the underlying Image function for the variable type corresponding to
that special display.
Image functions execute as part of the debugger job itself, not as part of
the job being debugged. Consequently, Image functions are scheduled as
part of the debugger job. If an Image function is resource-intensive (or
goes into an infinite loop--see "Errors," below), the system may become
heavily loaded during execution of the Image function.
Because Image functions execute as part of the debugger job, they cannot
depend on job-dependent states of the Environment. For example, the
Standard_Output and Current_Output files from package !Io.Text_Io are
job-specific. If an Image function attempts to call the Text_Io.Put_Line
procedure using the value of Current_Output for the file, the output will
not go to the Current_Output defined for the application; instead, it will
go to the Current_Output defined for the debugger. This applies to all
job-dependent states, such as current context, current profile, current
activity, and so on.
ERRORS
If the Image function goes into an infinite loop, the Debug.Put command
that initiated the looping Image function will never complete. If this
situation occurs, use Debug.Kill to terminate debugging of the job and
start over after removing the infinite loop from the special display.
EXAMPLES
See generic procedure Register for examples of Image functions.
REFERENCES
generic procedure Register
type Debug.Numeric, enumeration Display_Level
type Debug.Numeric, enumeration Pointer_Level
@node !Tools.Debug_Tools.Register.T
type T is limited private;
DESCRIPTION
Specifies the type of the object for which the special display is being
defined.
REFERENCES
generic procedure Register
@node !Tools.Debug_Tools.Set_Task_Name
procedure Set_Task_Name (Name : String);
DESCRIPTION
Assigns a string synonym to the specified task.
This name is used within the debugger to make identifying tasks easier. It
is also useful for distinguishing between multiple activations of the same
task type.
Most debugger commands recognize task synonyms. To use a synonym in a com-
mand, precede it with a percent symbol (%). The string passed to this
procedure, however, should not have a leading percent symbol.
It is good practice to call the Set_Task_Name procedure in important (if
not all) tasks to identify them easily during debugging. This is
especially important when multiple activations of the same task type are
created. To aid differentiation between multiple activations of a task,
the debugger allows a unique synonym to be assigned to each activation. It
is some extra work to give each activation a unique name, but the effort
often greatly simplifies the task of understanding what is going on during
debugging.
A single synonym can be assigned to only one task; the debugger does not
allow synonyms to be overloaded. Reassigning a task synonym to a new task
removes that synonym from the task to which it was previously assigned.
Thus each activation of a task type must programmatically determine its
own task synonym unique from the synonyms created by other activations of
the same task type.
The name Root_Task is automatically assigned to the root task (the command
task) in a job. To avoid confusion, do not assign the Root_Task synonym to
any other task.
The Debug.Set_Task_Name command also assigns synonyms to tasks. However,
note that the parameters for Debug.Set_Task_Name differ from those for
this procedure.
Note: Task synonyms were formerly documented as task nicknames.
PARAMETERS
Name : String;
Specifies the name to be assigned to the task. The string must be a legal
Ada identifier. Strings containing illegal characters cause an error.
Keep the name reasonably short. Although names can be of any length,
debugger displays that include the task name are less readable if
excessively long names are used.
RESTRICTIONS
If this procedure is called from a job not currently being debugged, the
call is ignored and has no effect.
EXAMPLES
Example 1
The following code assigns the name My_Task to the current task. If there
is more than one activation of this task, only the last task to call
Set_Task_Name will retain the synonym.
Debug_Tools.Set_Task_Name ("My_Task");
Example 2
The following code assigns a unique name to each activation of the current
task. Each task will be named My_Task_n, where n is a unique number for
each task.
Unique_Number.Get (N);
Debug_Tools.Set_Task_Name
("My_Task_" & Integer'Image (N)
-- strip leading blank or minus from image of number
(Integer'Image (N)'First + 1 .. Integer'Image (N)'Last));
See Chapter 3, "Managing Tasks," for a complete example.
REFERENCES
procedure Get_Task_Name
subtype Debug.Path_Name
procedure Debug.Set_Task_Name
procedure Debug.Task_Display
@node !Tools.Debug_Tools.Un_Register
generic
type T is limited private;
procedure Un_Register;
DESCRIPTION
Cancels ("unregisters") the special display for a type.
This generic procedure revokes the registration of a special display
previously registered for an object type. For more information on special
displays, see the generic procedure Register.
Once a special display is unregistered, the default display for a variable
of this type is based on the structural information for the type. The
debugger no longer uses the Image procedure last registered to the type
for displays of variables of the type. The debugger uses the structural
information in the type declaration to display objects of this type in
the standard format, just as though no special display had been
registered.
Special displays do not stack. Regardless of the number of different
special displays that have been registered for the same type,
Un_Register causes a return to the original default structural display.
The parameter T defines the type for which a special display is
unregistered.
If no special displays are registered for the type, this procedure has no
effect.
Note: The specification of the generic procedure Un_Register is slightly
different for Rational's Cross-Development Facility (CDF) debuggers. See
the documentation for the appropriate CDF for more details.
REFERENCES
generic procedure Register
generic formal function Register.Image
generic formal type Un_Register.T
@node !Tools.Debug_Tools.Un_Register.T
type T is limited private;
DESCRIPTION
Specifies the type of the object for which the special display is removed.
REFERENCES
generic procedure Un_Register
@node !Tools.Debug_Tools.User_Break
procedure User_Break (Info : String);
DESCRIPTION
Causes the calling task to stop as though it had encountered a breakpoint.
This procedure interrupts execution of the current task in the same manner
as a breakpoint. When the debugger executes this procedure, it halts
execution and prints a status message that includes a string specified by
the Info parameter.
PARAMETERS
Info : String;
Specifies the string that is displayed in the debugger window.
Multiple lines must be separated with linefeed characters (character type
Ascii.Lf).
RESTRICTIONS
If this procedure is called from a job not currently being debugged, the
call is ignored and has no effect.
EXAMPLES
If a task with number 1CCD4 issues the call:
Debug_Tools.User_Break ("Serious error encountered");
the debugger stops the task and displays in the debugger window:
From task: ROOT_TASK, #1CCD4: Serious error encountered
User break: .DEBUG_TOOLS_EXAMPLES.CRASH.1s [Task : ROOT_TASK,
#1CCD4].
which identifies the task name and location of the call to the User_Break
procedure.