⟦e3f6dc015⟧

E3 Source Code



--| @SUMMARY This package is used for recording the instance of errors
--| in a log file and generating reports of those errors.
--|
--| @DESCRIPTION Error descriptions can be created and written to either
--| a Polymorphic_Sequential file or a pipe. Error descriptions include
--| the user that created the error, date that the error occurred, unit
--| and line number in which the error occured, and two labels. One label
--| is specified by one of the enumerated values used to instantiated the
--| generic. The other label is a severity label such as Error, Warning,
--| etc. The generation of reports from files containing error entries
--| is also provided.
--|
--| @INDICES (Error_Handling, Logging)
--|
with Io;
with Pipe;
with System_Utilities;
with List_Generic;
with Bounded_String;
with Time_Utilities;
with String_Map_Generic;
with Polymorphic_Sequential_Io;
generic
    type Item is (<>);
    with function Image (I : Item) return String;
package Unit_Error_Recording is

    package Pio renames Polymorphic_Sequential_Io;

    type Error_Data is private;

    type Error_Kind is (Error,  
                        Warning,  
                        Batch_Error,  
                        Batch_Warning,  
                        Stop_Recording);

    --| @DESCRIPTION Constructs error data which can then be written
    --| to a PIO file. The error data also contains the name of the
    --| user that created it and a timestamp.
    --|
    function Make (Label       : Item;
                   Kind        : Error_Kind := Error;
                   In_Unit     : String;
                   Line_Number : Natural) return Error_Data;

    function Kind (Of_Data : Error_Data) return Error_Kind;

    --| @PARAMETERS To_File should be open
    --|
    procedure Write (To_File : Pio.File_Type; D : Error_Data);

    --| @PARAMETERS From_File should be open
    --|
    procedure Read (From_File : Pio.File_Type; D : out Error_Data);

    --| @PARAMETERS To_File should be open
    --| @SPECIAL_NOTES If the Wait duration expires, no data is written
    --| and no indication is given.
    --|
    procedure Write (To_Pipe : in out Pipe.Handle;
                     D       :        Error_Data;
                     Wait    :        Duration);

    --| @PARAMETERS From_Pipe should be open
    --| @SPECIAL_NOTES If the Wait_Duration expires, the Timeout_Expired
    --| boolean will be set to True and the returned Error_Data will
    --| be null.
    --|
    procedure Read (From_Pipe       :     Pipe.Handle;
                    Wait            :     Duration;
                    D               : out Error_Data;
                    Timeout_Expired : out Boolean);

    --| @SPECIAL_NOTES Provided to allow alternative processing of log entries
    --|
    type Entry_Iterator is private;

    --| @DESCRIPTION Fills the iterator with error_data values
    --| recorded in the specified files. If From_Files does not resolve
    --| to any files, then a done iterator is returned. Locked files
    --| (those currently being written to) are also ignored.
    procedure Init (From_Files : String; Iter : in out Entry_Iterator);

    function  Done (Iter : Entry_Iterator) return Boolean;
    procedure Next (Iter : in out Entry_Iterator);

    function User_Name   (Iter : Entry_Iterator) return String;
    function Date        (Iter : Entry_Iterator) return Time_Utilities.Time;
    function Label       (Iter : Entry_Iterator) return Item;
    function Kind        (Iter : Entry_Iterator) return Error_Kind;
    function Unit        (Iter : Entry_Iterator) return String;
    function Line_Number (Iter : Entry_Iterator) return Natural;

    --| @SPECIAL_NOTES columns that can be selected to construct a report.
    type Column_Name is (User,  
                         Date,  
                         Incompatibility,  
                         Error_Designation,  
                         Unit_Name,  
                         Line_Number);

    type Column_List is array (Natural range <>) of Column_Name;

    --| @DESCRIPTION Constructs a report listing the Error_Data entries
    --| located in the specified set of files.
    --| @INDICES (Report_Generation)
    generic
        --| @SPECIAL_NOTES Specifies what items should be included in the
        --| report. The order of the columns also implies sort order.
        Included_Columns : Column_List;

        --| @SUMMARY The following functions are provided to
        --| filter error data items. For each Error_Data item in the
        --| list, the user name, data, label, kind, and unit_name is
        --| checked to see if it should be included in the report.
        --| If any of the functions return False, the entire Error_Data
        --| entry is excluded.
        with function Include      (User : String)              return Boolean;
        with function Include      (Date : Time_Utilities.Time) return Boolean;
        with function Include      (Label : Item)               return Boolean;
        with function Include      (Kind : Error_Kind)          return Boolean;
        with function Include_Unit (Unit : String)              return Boolean;

    procedure Generate_Report (From_Files : String;
                               To_File    : Io.File_Type := Io.Standard_Output);

    --| @DESCRIPTION Displays a summary table, collecting totals by
    --| Error_Kind and by label. It also computes the average numer
    --| of errors per user, per day, and per unit.
    --|
    procedure Display_Summary
                 (Of_Entries : in out Entry_Iterator; To_File : Io.File_Type);

private

    --| @SPECIAL_NOTES Largest pathnames possible
    Name_Length : constant := 256;

    subtype Name is Bounded_String.Variable_String (Name_Length);

    type Error_Data is
        record
            Label       : Item;
            Kind        : Error_Kind;
            Date        : Time_Utilities.Time := Time_Utilities.Get_Time;
            User        : Name := Bounded_String.Value
                                     (System_Utilities.User_Name, Name_Length);
            Unit        : Name;
            Line_Number : Natural;
        end record;

    package Data_List is new List_Generic (Error_Data);

    type Entry_Iterator is
        record
            List_Iter    : Data_List.Iterator;
            Current_Data : Error_Data;
        end record;

    --| @DESCRIPTION collects and display summary data
    package Summary is

        type Item_Count is array (Item) of Natural;

        type Error_Count is array (Error_Kind) of Natural;

        package Name_Map is new String_Map_Generic (1000, Natural);

        type Summary_Data is
            record
                Total_Count  : Natural;
                Item_Counts  : Item_Count;
                Error_Counts : Error_Count;
                Unit_Map     : Name_Map.Map;
                User_Map     : Name_Map.Map;
                Date_Map     : Name_Map.Map;
            end record;

        procedure Initialize (Summary : in out Summary_Data);

        --| @DESCRIPTION  Totals all entries, each item, and
        --| each error kind. Also adds the unit to the unit map, user
        --| to the user map, and Date to the Date_Map.
        --|
        procedure Add (D : Error_Data; To_Summary : in out Summary_Data);

        procedure Display (Summary : Summary_Data; To : Io.File_Type);

    end Summary;
end Unit_Error_Recording;
DataMuseum.dk

Rational R1000/400

⟦e3f6dc015⟧ Ada Source

Derivation

E3 Source Code

E3 Meta Data
