|
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: 215178 (0x3488a)
Types: TextFile
Names: »DEB_D2_2_UPGRADE_PACKAGE_HELP«
└─⟦5f3412b64⟧ Bits:30000745 8mm tape, Rational 1000, ENVIRONMENT 12_6_5 TOOLS
└─ ⟦91c658230⟧ »DATA«
└─⟦f6fec0485⟧
└─⟦this⟧
@node !Commands.Debug
Package !Commands.Debug contains the specific types, subtypes, and
procedures provided by the Rational Environment debugger for interactive
use.
Package !Tools.Debug_Tools provides procedures and functions through which
your programs can use the facilities of the debugger.
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
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
Creating and manipulating breakpoints:
Activate, Break, Remove
Handling exceptions: Catch, Exception_Name, Forget,
Propagate
Starting or restarting tasks: Clear_Stepping, Execute, Run,
Stop_Event, Xecute
Naming tasks: Set_Task_Name, Task_Name
Displaying task status: Information, Information_Type,
Task_Category, Task_Display
Holding and releasing tasks: Hold, Release
Stopping tasks: Stop
Killing tasks: Kill
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
debugger. These commands are summarized in Table 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 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 |
| |first one of the set of elements at the next |
| |lower level, in a syntactic sense, from the |
| |currently 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 |
| |currently 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 following command displays all breakpoints and their status:
Show (Breakpoints)
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 the "Debugger Naming" section of the Key Concepts 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_ | |
|Breakpoints |Lifetime |Breakpoint|
|Option Flag |Parameter |Type |
-------------------------------------
| | | |
|True |True |Permanent |
| | | |
-------------------------------------
| | | |
|True |False |Temporary |
| | | |
-------------------------------------
| | | |
|False |True |Temporary |
| | | |
-------------------------------------
| | | |
|False |False |Permanent |
| | | |
-------------------------------------
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 | | |
-------------------------------------
| | | 2|
|A special |Location |Stack_Frame |
|name | | |
-------------------------------------
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 the value is 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 where 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, Propagate 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 the "Debugger Naming" section of the Key Concepts 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
annotation 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 i|
| |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
commands 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 the "Debugger Naming" section of the Key Concepts and the Path_Name
subtype for more information on designating contexts with pathnames.
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
another 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 | | |
-------------------------------------
| | | 2|
|A special |Location |Stack_Frame |
|name | | |
-------------------------------------
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 the "Debugger Naming" section of the Key Concepts 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 is the functional equivalent of the Xecute command. They can
be used interchangeably.
Execute 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
procedure Xecute
@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 |Unsupported|
|Frames |stack information for the | | |
| |current task. Disabling this | | |
| |flag impairs some debugger | | |
| |operations. | | |
------------------------------------------------------------------
| | | | |
|Flag_Errors |Includes the string *** in |False |Supported |
| |error messages. | | |
------------------------------------------------------------------
| | | | |
|Hex_Values |Forces hexadecimal output from |False |Supported |
| |the Put command for certain | | |
| |values. | | |
------------------------------------------------------------------
| | | | |
|Interpret_ |Forces the Memory_Display |False |Unsupported|
|Import_Words |command to interpret words in | | |
| |the import space. | | |
------------------------------------------------------------------
| | | | |
|Interpreter_ |Displays the contents of the |False |Unsupported|
|Dump |interpreter stack after each | | |
| |instruction executed by the | | |
| |interpreter. | | |
------------------------------------------------------------------
| | | | |
|Interpreter_ |Prints information about |False |Unsupported|
|Trace |execution of interpreted code | | |
| |used to do object displays. | | |
------------------------------------------------------------------
| | | | |
|No_Pointers |Prevents display of actual |False |Supported |
| |pointer values. The value ppppp| | |
| |displays for all pointers. | | |
------------------------------------------------------------------
| | | | |
|No_Task_ |Prevents display of actual task|False |Supported |
|Numbers |numbers. The value xxxxx | | |
| |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
requests 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 Propagate ("All")
request 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 the "Debugger Naming" section of the Key Concepts 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 20th 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 20th through 29th 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 is
generally 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 | | |
-------------------------------------
| | | 2|
|A special |Location |Stack_Frame |
|name | | |
-------------------------------------
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 the "Debugger Naming" section of the Key Concepts 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 the "Debugger Naming" section of the Key Concepts 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
constants. 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 information
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
described 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 field|,
| |and variant fields) |
--------------------------------------------
| | |
|Element of an |Subscript list enclosed in|
|array |parentheses (the |
| |subscripts 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 the Key Concepts section in this book 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, Propagate 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 nonnull, In_Task designates the specified task. If the value is
null, In_Task designates no specific task and Propagate 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 the "Debugger Naming" section of the Key Concepts 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 lefthand 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 information 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 the "Debugger Naming" section of the Key Concepts 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
command. 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. For a synonym to be used
in a command, it must be preceded by a 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.
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 | | |
-------------------------------------
| | | 2|
|A special |Location |Stack_Frame |
|name | | |
-------------------------------------
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 the "Debugger Naming" section of the Key Concepts 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 10 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.User_Break in procedure A:
with Debug_Tools;
procedure Nested_Calls is
procedure A is
begin
Debug_Tools.User_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).
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.
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.
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.
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.
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 | | |
-------------------------------------
| | | 2|
|A special |At_Location|Stack_Frame |
|name | | |
-------------------------------------
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 the "Debugger Naming" section of the Key Concepts 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 for only 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 |Awaiting_ |The task is executing at |
|select-terminate for|Children_In_ |a select, with a |
|entry call with |Select |terminate alternative, |
|dependents | |and has dependent tasks |
| | |that cannot be |
| | |terminated. |
---------------------------------------------------------------
| | | |
|waiting at |Terminable_In_ |The task is blocked in a |
|select-terminate for|Select |select, with a terminate |
|entry 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 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 Xecute
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 | | |
-------------------------------------
| | | 2|
|A special |At_Location|Stack_Frame |
|name | | |
-------------------------------------
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 the "Debugger Naming" section of the Key Concepts 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
Initiates execution of the named task.
This command is the functional equivalent of the Execute command. They can be
used interchangeably.
The Xecute procedure 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 Xecute command for all tasks (Xecute ("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 Xecute 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 procedure 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 only the stopped tasks stopped are subject to hold
conditions.
REFERENCES
procedure Break
procedure Execute
procedure Hold
procedure Release
procedure Stop