⟦4e943d4a1⟧

TextFile


  @node !Tools.Debug_Tools

  Package Debug_Tools provides a programmatic interface to the
  Debugger.  These subprograms can be used in a program to pass
  information back to the Debugger.  They can also be used to
  determine information about the task calling the subprograms,
  including the most recent exception raised, the current program
  counter location, the Debugger task name synonym, and so on.  The
  subprograms also provide a means for creating special display
  procedures for the Debugger to use to display the value variables
  of specific types (for example, when using the Debug.Put command),
  where users do not want the Debugger to use the structural type
  information for displaying these values.

  The preceding section describes package !Commands.Debug, which
  contains the interactive commands for Debugger operations.
  @node !Tools.Debug_Tools.Ada_Location

  function Ada_Location (Frame_Number  : Natural := 0;
                        Fully_Qualify : Boolean := True;
                        Machine_Info  : Boolean := False) return String;

  Returns a string representing the Ada name of the source location
  in the calling subprogram or a caller of the calling subprogram.

  The null string is returned if the frame specified by the Frame-
  _Number parameter does not exist.
  @node !Tools.Debug_Tools.Debug_Off

  procedure Debug_Off;

  Disables debugging in the calling task.

  This command allows a program to turn off debugging so that
  the Debugger does not interfere with program behavior.  When a
  program is being debugged, it can turn off debugging by calling the
  Debug_Off procedure; when the program desires to allow debugging
  again, it can call the Debug_On procedure.  When debugging is off,
  you are not able to control execution using the Debugger (including
  catching exceptions and so on).
  @node !Tools.Debug_Tools.Debug_On

  procedure Debug_On;

  Enables debugging for the calling task.

  Used only after the Debug_Off procedure has been called, the
  command allows a program to implement a region in which the
  Debugger will not interfere with program execution.  Such regions
  can be created by calling the Debug_Off procedure at the beginning
  of the region to tell the Debugger not to interfere until the next
  call to Debug_On, and then calling the Debug_On procedure at the
  end of the region to resume Debugger control.  During execution
  in this region, you are not able to control execution using the
  Debugger (including catching exceptions).

  Any tasks created from a region in which debugging is not enabled
  also do not have debugging enabled.  Once the Debug_On procedure
  has been called, tasks subsequently created will have debugging
  enabled.
  @node !Tools.Debug_Tools.Debugging

  function Debugging return Boolean;

  Returns true if the currently executing program is under the
  control of the Debugger; otherwise, the function returns false.
  @node !Tools.Debug_Tools.Get_Exception_Name

  function Get_Exception_Name (Fully_Qualify : Boolean := True;
                              Machine_Info  : Boolean := False)
                                                           return String;

  Returns the name of the most recently raised exception for the
  task that calls this function and, optionally, returns additional
  machine-related information about the exception.

  This function must be called directly or indirectly from an
  exception handler.  The null string is returned if no exception
  is currently active for the calling task.

  If Machine_Info is true, the address in which the exception was
  raised and the exception's machine representation are displayed.
  These numbers can be given to the Debug.Address_To_Location
  and Debug.Exception_To_Name procedures to get their source
  representations (assuming that the Ada units still exist and the
  exception was not raised or declared in a Command window).
  @node !Tools.Debug_Tools.Get_Raise_Location

  function Get_Raise_Location (Fully_Qualify : Boolean := True;
                              Machine_Info  : Boolean := False)
                                                           return String;

  Returns a representation of the location in the source from which
  the most recent exception for the task calling this function
  was raised and, optionally, returns additional machine-related
  information about the raise location.

  This function must be called directly or indirectly from an
  exception handler.  The null string is returned if no exception
  is currently active for the calling task or if problems are
  encountered getting the raise location information.

  If Machine_Info is true, the address in which the exception was
  raised and the exception's machine representation are displayed.
  These numbers can be given to the Debug.Address_To_Location
  and Debug.Exception_To_Name procedures to get their source
  representations (assuming that the Ada units still exist and the
  exception was not raised or declared in a Command window).
  @node !Tools.Debug_Tools.Get_Task_Name

  function Get_Task_Name return String;

  Returns any task name set by the Set_Task_Name procedure.

  This function allows a task to interrogate its name.  If the
  function is called by a task not in a job presently being debugged,
  the name passed to Set_Task_Name may or may not be returned.
  @node !Tools.Debug_Tools.Message

  procedure Message (Info : String);

  Causes a message to be displayed in the Debugger window.

  A call to the Message procedure from any task being debugged causes
  a message as specified by the Info parameter to be displayed in the
  Debugger window.

  If there is no Debugger for the session, the operation has no
  effect.

  This generic procedure provides facilities that enable you to
  write special display routines for the Debugger.  The Debugger
  uses the routines to display the value of variables and to perform
  other actions.  These display routines can be created for any type
  defined in the Rational Environment or in your applications.

  The display routines are created and then registered with the
  Debugger.  Once a special display is registered for a type, the
  Debugger uses it (instead of the structural type information from
  the type declaration) when the Debug.Put command is executed on
  variables of that type.  Registering a new special display for
  a type overrides any existing special displays for the type and
  the type's normal structural display.  Special displays can be
  unregistered to enable the use of a type's normal structural
  display.

  Special displays can be registered when the Debugger is started
  in the default Debugger_Initialization procedure.  If they are
  registered in this procedure, they will remain in effect until
  explicitly unregistered, until a new special display is registered
  for the type, until the user logs off from the session, or until
  the Debugger is killed.  Special displays can also be registered by
  the job being debugged.  In this case, the special display remains
  in effect during the life of the job, until the special display is
  unregistered, or until a new special display is registered for the
  type.

  Note that, by default, the Debugger has preregistered special
  displays for many of the important types defined in the

  specifications of the Rational Environment.  These displays can
  be redefined if necessary.  The types that have displays registered
  for them include:

     !Implementation.Activity_Implementation.Activity_Handle

     !Implementation.Activity_Implementation.Iterator

     !Implementation.Dependency_Data_Base.Iterator

     !Implementation.Dependency_Data_Base.Defid_Iterator

     !Implementation.Diana.Attr_List

     !Implementation.Diana.Attr_Name

     !Implementation.Diana.Comment

     !Implementation.Diana.Number_Rep

     !Implementation.Diana.Sequence

     !Implementation.Diana.Seq_Type

     !Implementation.Diana.Symbol_Rep

     !Implementation.Diana.Temp_Seq

     !Implementation.Diana.Tree

     !Implementation.Diana.Value

     !Implementation.Directory.Ada.Unit

     !Implementation.Directory.Class

     !Implementation.Directory.Naming.Iterator

     !Implementation.Directory.Object

     !Implementation.Directory.Object_Set.Iterator

     !Implementation.Directory.Object_Set.Set

     !Implementation.Directory.Traversal.Associated_Object_Iterator

     !Implementation.Directory.Traversal.Object_Iterator

     !Implementation.Directory.Traversal.Subobject_Iterator

     !Implementation.Directory.Traversal.Subunit_Iterator

     !Implementation.Directory.Traversal.Version_Iterator

     !Implementation.Directory.Version

     !Implementation.Error_Messages.Annotation

     !Implementation.Error_Messages.Errors

     !Implementation.Links_Implementation.Iterator

     !Implementation.Low_Level_Action.Id

     !Implementation.Switch_Implementation.Iterator

     !Implementation.Universal.Float

     !Implementation.Universal.Int

     !Implementation.Universal.Integer

     !Implementation.Universal.Real

     !Io.Device_Independent_Io.File_Type

     !Io.Io.File_Type

     !Io.Object_Set.Iterator

     !Io.Object_Set.Set

     !Io.Pipe.Handle

     !Io.Polymorphic_Io.File_Position

     !Io.Polymorphic_Io.Handle

     !Io.Polymorphic_Sequential_Io.File_Type

     !Io.Text_Io.File_Type

     !Io.Window_Io.File_Type

     !Lrm.Calendar.Time

     !Tools.Bounded_String.Variable_String

     !Tools.Directory_Tools.Object.Error_Code

     !Tools.Directory_Tools.Object.Handle

     !Tools.Directory_Tools.Object.Iterator

     !Tools.Directory_Tools.Object.Message_List

     !Tools.Directory_Tools.Object.Subclass

     !Tools.Link_Tools.Dependent_Iterator

     !Tools.Link_Tools.Link_Iterator

     !Tools.Profile.Response_Profile

     !Tools.Simple_Status.Condition

     !Tools.Simple_Status.Condition_Name

     !Tools.String_Table.Item

     !Tools.String_Table.Iterator

     !Tools.System_Utilities.Job_Iterator

     !Tools.System_Utilities.Session_Iterator

     !Tools.System_Utilities.Terminal_Iterator

     !Tools.Tape_Tools.Logical_Device

     !Tools.Unbounded_String.Variable_String

  Several important restrictions that apply to special displays are
  described under "Restrictions" in the reference entry for the
  Image generic formal function.

  The formal parameters to the generic are:
      generic
          type T is limited private;
          with function Image (Value           : T;
                              Level           : Natural;
                              Prefix          : String;
                              Expand_Pointers : Boolean) return String;
      procedure Register;

  These parameters define the type for which a special display is to
  be created and the function that returns the images of values of
  that type.  This function is used by the Debugger when performing
  puts on values of that type.  Instantiating the generic provides
  the registration procedure that can be called from your application
  (or by your Debugger_Initialization procedure) to register the
  special display.

  Example 1

  Even though there may be a structural display available for a type,
  a special display may be more convenient to use.  For example, data
  structures containing pointers are often difficult to visualize
  from the structural display.  The following example shows how a
  special display can be constructed for lists.  This special display
  outputs the elements in the list as a text string instead of the
  pointer chain connecting the list elements, as would typically be
  the case if a structural display were used.
      with List_Generic;
      package Integer_List is new List_Generic (Integer);
      -- Example uses list generic from !Tools.
      with Integer_List;
      package List_Display is
          -- This package implements the special display for values
          -- of type Integer_List.List.
          procedure Register;
          -- Causes the special display to be registered with the

          -- Debugger so that it will be used by the Debugger in
          -- subsequent Debug.Put commands instead of the normal
          -- structural display.
      end List_Display;
      with Debug_Tools;
      with String_Utilities;
      package body List_Display is
          function Element_Images (Value : Integer_List.List) return String is
          begin
             if Integer_List.Is_Empty (Value) then
                 return "";
             else
                 return String_Utilities.Number_To_String
                           (Integer_List.First (Value)) & " " &
                        Element_Images (Integer_List.Rest (Value));
             end if;
          end Element_Images;
          -- Recursive function that builds a string containing the
          -- the images of the items in a list ordered from left to
          -- right.
          function Image (Value : Integer_List.List;
                         Level : Natural;
                         Prefix : String;
                         Expand_Pointers : Boolean) return String is
          begin
             if Integer_List.Is_Empty (Value) then
                 return "the list is empty";
             else
                 return "( " & Element_Images (Value) & ")";
             end if;
          end Image;
          -- The Image function used in this special display displays
          -- lists with their elements ordered from left to right
          -- enclosed in parentheses.  E.g., "( 1 2 3 )".
          procedure Register_Special_Display is
             new Debug_Tools.Register (Integer_List.List, Image);
          procedure Register is
          begin
             Register_Special_Display;
          end Register;
      begin
          Register;  -- Registers the special display upon elaboration.
      end List_Display;
      with Text_Io;
      with Integer_List;
      with List_Display;
      procedure List_Test is
          -- This is a main program used to test the special display
          -- for Integer_List.List.
          L : Integer_List.List := Integer_List.Nil;
      begin
          L := Integer_List.Make (3, L);
          L := Integer_List.Make (2, L);
          L := Integer_List.Make (1, L);
          null;  -- A location on which to stop the Debugger.
      end List_Test;

  Assume that the List_Test procedure is run with the Debugger
  and stepped to the null statement.  If the Debug.Put command is
  executed at this point to display the value of L, the Debugger
  responds as follows in the Debugger window:
      Put ("%ROOT_TASK._1.L");
      {( 1 2 3 )}

  Example 2

  Sometimes it is helpful in testing an application program to be
  able to initiate the execution of subprograms as part of the
  job being debugged.  For example, when debugging an application
  using the Debugger, it might be helpful to be able to reset some
  of the state of the application, display status information, or
  dump/restore state, all by executing Debugger commands at certain
  times.  The special display facility can be used to do this.

  The strategy consists of defining types and objects of these types
  for each of the operations that you would like to trigger from
  the Debugger.  Special displays are then created and registered
  for each of these types.  These special displays can be designed
  to perform the actions desired.  Finally, to invoke the special
  display and to perform the action while debugging, simply execute
  the Debug.Put command on the object corresponding to the action you
  want to perform.  The Debugger will execute the associated special
  display routine that will perform the action.

  Here is a simple example of a package that implements such a
  strategy.  Note that the package would be withed into the library
  unit closure of the application.  In this example, the only effect
  of the operations is to write a message into a log file.  These
  actions typically would manipulate various pieces of the state of
  the application.
       package Debugger_Operations is
           -- This package implements various testing operations using
          -- the Debugger special display mechanism.  To perform the
          -- desired action, perform a Debug.Put command on the object
          -- of the appropriate type.
          type Reset_Type is new Boolean;
          type Display_Status_Type is new Boolean;
          type Dump_State_Type is new Boolean;
          type Restore_State_Type is new Boolean;
          -- Performing a Debug.Put on the following objects causes the
          -- associated action to be performed by the special display
          -- for their types.
          Reset          : Reset_Type := True;
          Display_Status : Display_Status_Type := True;
          Dump_State     : Dump_State_Type := True;
          Restore_State  : Restore_State_Type := True;
      end Debugger_Operations;
      with Text_Io;
      with Debug_Tools;
      package body Debugger_Operations is
          File : Text_Io.File_Type;
          Resetting : constant String := "... Resetting";
          Displaying_Status : constant String := "... Displaying status";
          Dumping_State : constant String := "... Dumping state";
          Restoring_State : constant String := "... Restoring state";
          function Reset_Implementation (Value : Reset_Type;
                                       Level : Natural;
                                       Prefix : String;
                                       Expand_Pointers : Boolean)
                                      return String is
          begin
             Text_Io.Put_Line (File, Resetting);
             return Resetting;
          end Reset_Implementation;
          function Display_Status_Implementation
                     (Value : Display_Status_Type;
                      Level : Natural;
                      Prefix : String;
                      Expand_Pointers : Boolean) return String is
          begin
             Text_Io.Put_Line (File, Displaying_Status);
             return Displaying_Status;

          end Display_Status_Implementation;
          function Dump_State_Implementation
                     (Value : Dump_State_Type;
                      Level : Natural;
                      Prefix : String;
                      Expand_Pointers : Boolean) return String is
          begin
             Text_Io.Put_Line (File, Dumping_State);
             Text_Io.Close (File);
             return Dumping_State;
          end Dump_State_Implementation;
          function Restore_State_Implementation
                     (Value : Restore_State_Type;
                      Level : Natural;
                      Prefix : String;
                      Expand_Pointers : Boolean) return String is
          begin
             Text_Io.Put_Line (File, Restoring_State);
             return Restoring_State;
          end Restore_State_Implementation;
          procedure Special_Display_Reset is
             new Debug_Tools.Register (Reset_Type, Reset_Implementation);
          procedure Special_Display_Display_Status is
             new Debug_Tools.Register (Display_Status_Type,
                                     Display_Status_Implementation);
          procedure Special_Display_Dump_State is
             new Debug_Tools.Register (Dump_State_Type,
                                     Dump_State_Implementation);
          procedure Special_Display_Restore_State is
             new Debug_Tools.Register (Restore_State_Type,
                                     Restore_State_Implementation);
      begin
          Special_Display_Reset;
          Special_Display_Display_Status;
          Special_Display_Dump_State;
          Special_Display_Restore_State;
          Text_Io.Create (File, Text_Io.Out_File, "$log_file");
      end Debugger_Operations;

  Example 3

  For debugging applications containing types with complex
  structures, it is often desirable to obtain different displays
  of the images of these types.  For example, you may want to obtain
  more or less detail, or you may want to look at different classes
  of information at different times during the debugging session.
  There are two approaches to using special displays to accomplish
  this.

  One approach is to use variables in the special display packages
  to indicate the level of detail or kind of information desired.
  The Image functions implementing the special display for a
  type can read these variables and, depending on their values,
  perform different actions.  The values of these variables can be
  manipulated by the Debug.Modify command or by the special displays,
  as described in Example 2 above.

  The other approach is to create multiple special displays and
  register and unregister them dynamically at various points in
  your application.  Note that this registration/unregistration can
  be accomplished explicitly in the application or by the special
  displays, as described in Example 2 above.
  @node !Tools.Debug_Tools.Image

  with function Image (Value           : T;
                      Level           : Natural;
                      Prefix          : String;
                      Expand_Pointers : Boolean) return String;

  Returns the string that is the image of the value of the Value
  parameter for the special display for T.
  @node !Tools.Debug_Tools.Register

  procedure Register;

  Registers a special display for a type with the Debugger.

  Registering a special display causes the Debugger to use your own
  display instead of the default the Debugger uses when values with
  the Debug.Put command.  Your display is the image function that is
  supplied as the value for the Image generic formal function in an
  instantiation of the Register procedure.  This function is used by
  the Debugger to compute the images of values of the type provided
  as the T generic formal type in the instantiation of the Register
  procedure.  See the introduction to the Register generic procedure
  for more information on special displays.

  If another special display is currently registered for the type, it
  is unregistered and the new function is substituted.

  Note that, by default, the Debugger has preregistered special
  displays for many of the important types defined in the
  specifications of the Rational Environment.  These displays can
  be redefined if necessary.  For a list of these types, see the
  introduction to the reference entry for the Register generic
  procedure.

  The Debugger command Debug.Show (Debug.Special_Types) can be used
  to get a list of the special displays that have been registered by
  the user for the job currently being debugged.  Note that this list
  will not include the Environment types automatically registered
  by the Debugger.  See the introduction to the Register generic
  procedure for a list of the preregistered Environment types.
  @node !Tools.Debug_Tools.T

  type T is limited private;

  Specifies the type for which the special display is being defined.
  @node !Tools.Debug_Tools.Set_Task_Name

  procedure Set_Task_Name (Name : String);

  Assigns a string nickname for the named task.

  The name can be used by the user in various Debugger commands as a
  synonym for the task.  If the command is called by a task in a job
  not presently being debugged, the call has no effect.  The nickname
  can also be set by the Debug.Set_Task_Name procedure.

  To use such a nickname in a command, the name must be preceded by a
  percent symbol (%).  The string passed to this procedure, however,
  should not have a leading percent symbol.

  It is good practice to call the Set_Task_Name procedure in
  important (if not all) tasks to identify them easily during
  debugging.  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.

  If the name passed to the Set_Task_Name procedure has already been
  used by a different task, the name is removed from that old task
  and assigned to the present caller to the Set_Task_Name procedure.
  Thus, only one task has a given name at a given time.

  The name Root_Task is automatically assigned to the root task (the
  command task) in a job.  To avoid confusion, it is best not to
  reassign this name.

  This generic procedure causes a special display registered for a
  type to no longer be used by the Debugger for displaying objects
  of the type.  When a special display is unregistered, the Debugger
  will use the structural information in the type declaration to
  display objects of these types.  For more information on special
  displays, see the Register generic procedure.

  The formal parameters to the generic are:
      generic
          type T is limited private;
      procedure Un_Register;

  The parameter defines the type for which a special display is no
  longer to be used.
  @node !Tools.Debug_Tools.T

  type T is limited private;

  Specifies the type for which the special display is to be removed.
  @node !Tools.Debug_Tools.Un_Register

  procedure Un_Register;

  Causes the Debugger to stop using the Image procedure last
  registered for computing the images of values of the T generic
  formal type in calls to the Debug.Put command for values of T type.

  After the call to Un_Register, the default display will be based on
  the structural information defining T.

  If no special displays are registered for the type, this procedure
  has no effect.
  @node !Tools.Debug_Tools.User_Break

  procedure User_Break (Info : String);

  Causes the calling task to stop as though a breakpoint were
  reached.

  The string specified by the Info parameter is displayed in the
  Debugger window along with a message that the task has stopped for
  a user break.
DataMuseum.dk

Rational R1000/400 Tapes

⟦4e943d4a1⟧ TextFile

Derivation

TextFile
