ASCL - Debugging Support

Contents

• Abstract
• Introduction
• Implementation
• Usage
• Example

Abstract

This article describes a small package which has proven quite usefull for debugging purposes. The intention was to make the debugging faciltity as independant as possible from the surrounding environment.

Introduction

The problem is quite known, you have to place some debugging information into a library which can be used either in an embeded system, a windows environment or a simple terminal environment. Simply placing Put_Lines in the code is not sufficient because i.e. Put_Lines in the OS/2 environenment are quite harmfull and in other environment i.e. your coffe maschine not possible.  During my testing expierence the following requierements have become a resonable standard:

• Different levels in the detail of the debugging trace may
  be adjustable, i.e. only call flow, data trace, etc..
• The call flow has to be made visible.
• In case of exceptions or errors a backtrace has to be 
  available.

Implementation

The is a package called  ASCL.Debugging_Support which provides an abstract data type which has to be extended.  The extention has to provide the output procedure. This procedure has to implement the actual output of the debugging information, which can be an output window, a led display, what so ever.

The package provides the following procedures:

• Enter / Leave
  Enter and Leave an named context like a procedure, function block of code. The name of the block is a string argument (see example ).
• Error
  Indicate that an error has occured.
• Trace
  Output some trace information within the current context.
  
• Set/Get
  Set and query the current debuging level. The following debugging
  levels are possible:
  
  • Quiet
    No debugging information at all.
  • Logic
    Only the call flow is shown.
  • Data
    Trace information is shown.

Usage

By defining different types of debug objects, different debugging  aspects of a system may be addressed, i.e. the GUI may use a different debugging object then the data base.

Example

The example given below shows how to extend the package how to apply it a small  execution example.

trst-debug.adb / .ads - Implementation of the debug interface

main.adb - Test program.

******* test-debug.ads
with ASCL.Debugging_Support;
package Test.Debug is
   type Object is new ASCL.Debugging_Support.Object with null record;
   procedure Output( this : in out Object;  text : in String );
end  Test.Debug;
 
******* test-debug.adb

with Ada.Text_IO;    use Ada.Text_IO;
with ASCL.Debugging_Support;
package body Test.Debug is
   procedure Output( this : in out Object;  text : in String ) is
   begin
      Put_Line( text );
   end Output;
end Test.Debug;
******* Main.adb
with ASCL.Debugging_Support;  use ASCL.Debugging_Support;
use  ASCL;
with Test.Debug;              use Test.Debug;
use Test;
procedure Main is
   D   : Debugging_Support.Handle := new Debug.Object;
begin
   Initialize( D.all );
   Set( D.all, Logic );
   declare
      O   ..............
      P   ..............
   begin
      Enter( d, " ** Persitant objects ** " );

      ........
      Leave( d, "" );
   end;
   Finalize( D.all );
exception
   when The_Error : Others =
      raise;
end Main;
Example output:
erdmann@boavista:~/ASCL/Library main
   - ASCL.OB.Peristant.Open
      - ASCL.OB.Peristant.Open_Or_Create_File
      <- ASCL.OB.Peristant.Open_Or_Create_File
      - ASCL.OB.Peristant.Open_Or_Create_File
      <- ASCL.OB.Peristant.Open_Or_Create_File
      - ASCL.OB.Peristant.Read_Object_Table
         - ASCL.OB.Peristant.Add_To_Object_Table  Pool= 1 Object= 1
         <- ASCL.OB.Peristant.Add_To_Object_Table  Pool= 1 Object= 1
         - ASCL.OB.Peristant.Add_To_Object_Table  Pool= 1 Object= 2
         <- ASCL.OB.Peristant.Add_To_Object_Table  Pool= 1 Object= 2
      <- ASCL.OB.Peristant.Read_Object_Table
   <- ASCL.OB.Peristant.Open
   - ASCL.OB.Peristant.Initialize  Object= 1 Pool= 1
      Object = 1 Pool   = 1 Offset = 1 Valid  =FALSE
      - ASCL.OB.Peristant.Add_To_Object_Table  Pool= 1 Object= 1
      <- ASCL.OB.Peristant.Add_To_Object_Table  Pool= 1 Object= 1
      - ASCL.OB.Peristant.Restore_Object
      <- ASCL.OB.Peristant.Restore_Object
   <- ASCL.OB.Peristant.Initialize  Object= 1 Pool= 1
   - ASCL.OB.Peristant.Initialize  Object= 2 Pool= 1
      Object = 2 Pool   = 1 Offset = 1 Valid  =FALSE
      - ASCL.OB.Peristant.Add_To_Object_Table  Pool= 1 Object= 2
      <- ASCL.OB.Peristant.Add_To_Object_Table  Pool= 1 Object= 2
      - ASCL.OB.Peristant.Make_New_Object_Data Object= 2
         Object = 2 Pool   = 1 Offset = 13 Valid  =TRUE
      <- ASCL.OB.Peristant.Make_New_Object_Data Object= 2
   <- ASCL.OB.Peristant.Initialize  Object= 2 Pool= 1
   -  ** Persitant objects **
Value =  1
   <-  ** Persitant objects **
   - ASCL.OB.Peristant.Finalize Object= 2
      - ASCL.OB.Peristant.Save_Object Object= 2
      <- ASCL.OB.Peristant.Save_Object Object= 2
   <- ASCL.OB.Peristant.Finalize Object= 2
   - ASCL.OB.Peristant.Finalize Object= 1
      - ASCL.OB.Peristant.Save_Object Object= 1
      <- ASCL.OB.Peristant.Save_Object Object= 1
   <- ASCL.OB.Peristant.Finalize Object= 1
   - ASCL.OB.Peristant.Close
      - ASCL.OB.Peristant.Write_Object_Table Pool = 1
*** Exception CONSTRAINT_ERROR in ASCL.OB.Peristant.Write_Object_Table.Write_Element  id =  1
Backtrace:
ASCL.OB.Peristant.Write_Object_Table Pool = 1
ASCL.OB.Peristant.Close
*** Exception CONSTRAINT_ERROR in ASCL.OB.Peristant.Close
Backtrace:
ASCL.OB.Peristant.Write_Object_Table Pool = 1
ASCL.OB.Peristant.Close
raised CONSTRAINT_ERROR

References

ASCL Package description