with Type_Definitions, Implementation_Dependencies, Calendar; ---------------- package Read_Log is ---------------- --| Overview --| Read_Log is an input package used by the report generators for --| the Ada Testing and Evaluation Tools. It performs all input from the --| Execution Log File (ELF) that is used to dynamically record --| information about programs written in the Ada language. The --| ELF is used for output by the Run Time Monitor (RTM) to record --| runtime information about the execution of the Ada program being --| tested. It is used as input by various report generators which --| summarize the information and present it in a meaningful format. --| All output to the ELF by the Run Time Monitor is performed by the --| package Write_Log. --| N/A: Errors, Raises, Modifies, Requires -- Version : 3.1 -- Author : Jeff England -- Initial Release : 02/27/85 -- Last Modified : 05/14/85 use Type_Definitions, --| Global type declarations common to --| all of the Ada Testing and Analysis --| Tools Implementation_Dependencies, --| Ada compiler dependencies Calendar; --| Logfile_Input uses the standard Ada package Calendar --| to provide the standard interface to the system clock. Logfile_Access_Error : exception; --| Attempt to access unopened logfile Logfile_Sequence_Error : exception; --| Attempt to access in wrong order Invalid_Logfile_Format : exception; --| Invalid or no configuration data End_Of_Logfile : exception; --| Unchecked end of file reached Undefined_Unit : exception; --| No unit name defined for unit id ------------------ procedure Open_Log ( --| Opens the ELF for input by the report generators. Logfile_Name : in Filename; --| The name of the log file to be created Program_Name : out Ada_Name; --| The name of the main program unit Test_Ident : out Test_Identifier; --| A unique ID assigned by the tester Test_Date : out Time --| The date and time of the test ); --| Raises: Invalid_Log_File_Format, Logfile_Access_Error --| Effects --| This procedure opens the ELF for input by the report generators. --| If the file is successfully opened, it returns test configuration --| data recorded in the ELF by the RTM during execution of the Ada --| program under test. If the file is already open then the exception --| Logfile_Access_Error is raised. If the file is not successfully --| opened due to an IO error, then the standard Text_IO exceptions are --| allowed to pass unhandled back to the calling program. If the ELF is --| is determined to contain invalid or missing configuration data, --| then the exception Invalid_Log_File_Format is raised. --| Requires --| The ELF must contain test configuration data in the format --| created by the RTM via a call to the procedure Create_Log. --| N/A: Modifies, Errors ---------------------- procedure Get_Next_Key (--| Gets the next log file key from the ELF Key : in out Logfile_Keys --| Defines the type of data that is --| contained in the current ELF record ); --| Effects --| This procedure reads the next log file key (Key) from the ELF and --| returns it to the calling program. --| Requires --| The ELF must have been previously opened for input by the --| calling program via a call to the procedure Open_Log. --| N/A: Raises, Modifies, Errors ------------------------------ procedure Flush_Logfile_Record (--| Flush the current Logfile record Key : in Logfile_Keys --| The current logfile key ); --| Effects --| If Key is equal to the current log file key then the remainder of the --| current logfile record is flushed and the logfile is positioned at --| the beginning of the next logfile record. --| Requires --| The ELF must have been previously opened for input by the --| calling program via a call to the procedure Open_Log. --| The Logfile key for the current record must have already been --| read. The Key passed by the calling program must match the --| key for the current logfile record. --| N/A: Raises, Modifies, Errors ----------------------- procedure Get_Unit_Id (--| Gets unit ID for current unit from the ELF Unit_Identifier : out Program_Unit_Unique_Identifier --| A unique ID assigned by the Source Instrumenter ); --| Effects --| Gets and returns the program unit id (Unit_Identifier) from the ELF --| Requires --| The log file must have been previously opened by the calling --| program via a call to Open_Log. --| The current log file key (i.e., the previously read key) --| must be in UNIT_START..UNIT_STOP. --| N/A: Raises, Modifies, Errors ----------------------- procedure Get_Unit_Time (--| Gets the unit ID and start/stop time from ELF Unit_Identifier : out Program_Unit_Unique_Identifier; --| A unique ID assigned by the Source Instrumenter Logged_Time : out Calendar.Day_Duration --| The time that the unit was entered or exited ); --| Effects --| Gets and returns the program unit id (Unit_Identifier) and logged --| time (Log_Time) from the ELF. --| Requires --| The log file must have been previously opened by the calling --| program via a call to Open_Log. --| The current log file key (i.e., the previously read key) --| must be in UNIT_START..UNIT_STOP. --| N/A: Raises, Modifies, Errors ------------------------ procedure Get_Breakpoint ( --| Gets current breakpoint from the ELF Unit_Identifier : out Program_Unit_Unique_Identifier; --| A unique ID assigned by the Source Instrumenter Current_Breakpoint : out Breakpoint_Number_Range --| The breakpoint number assigned by the Source Instrumenter ); --| Effects --| Gets the program unit, and current breakpoint number from the --| Execution Log File. --| Requires --| The log file must have been previously opened by the calling --| program via a call to Open_Log. --| The current log file key (i.e., the previously read key) --| must be in BEGIN_IF..OTHER_BREAKPOINT. --| N/A: Raises, Modifies, Errors ------------------- function Call_Parameters --| Gets AutoPath procedure call parameter list return User_Input_String; --| The user specified input parameter list --| Raises: Logfile_Access_Error, Logfile_Sequence_Error, --| End_of_Log_File --| Effects --| Gets the AutoPath procedure call parameter list from the logfile --| for a single execution of the target Ada program. --| If the logfile is not open then the exception Logfile_Access_Error --| is raised. --| If an End of File (EOF) in the ELF is encountered, the exception --| End_of_Log_File is raised. --| If the current logfile key is not AUTOPATH_CALL --| then the exception Logfile_Sequence_Error is raised. --| Requires --| The log file must have been previously opened by the calling --| program via a call to Open_Log. --| The current log file key (i.e., the previously read key) --| must be AUTOPATH_CALL. --| N/A: Modifies, Errors ------------------- procedure Get_Value (--| Gets value of INTEGER variable from ELF Unit_Identifier : out Program_Unit_Unique_Identifier; --| A unique ID assigned by the Source Instrumenter Variable_Name : out Ada_Name; --| The unqualified variable name Value : out Integer --| The current value of variable ); --| Effects --| Gets integer values from the execution log file. --| Requires --| The log file must have been previously opened by the calling --| program via a call to Open_Log. --| The current log file key (i.e., the previously read key) --| must be INTEGER_VARIABLE. --| N/A: Raises, Modifies, Errors ------------------- procedure Get_Value (--| Gets value of LONG_INTEGER variable from ELF Unit_Identifier : out Program_Unit_Unique_Identifier; --| A unique ID assigned by the Source Instrumenter Variable_Name : out Ada_Name; --| The unqualified variable name Value : out Long_Integer --| The current value of variable ); --| Effects --| Gets long_integer values from the execution log file. --| Requires --| The log file must have been previously opened by the calling --| program via a call to Open_Log. --| The current log file key (i.e., the previously read key) --| must be LONG_INTEGER_VARIABLE. --| N/A: Raises, Modifies, Errors ------------------- procedure Get_Value (--| Gets value of FLOAT variable from ELF Unit_Identifier : out Program_Unit_Unique_Identifier; --| A unique ID assigned by the Source Instrumenter Variable_Name : out Ada_Name; --| The unqualified variable name Value : out Float --| The current value of variable ); --| Effects --| Gets floating point values from the execution log file. --| Requires --| The log file must have been previously opened by the calling --| program via a call to Open_Log. --| The current log file key (i.e., the previously read key) --| must be FLOAT_VARIABLE. --| N/A: Raises, Modifies, Errors ------------------- -- procedure Get_Value (--| Gets value of LONG_FLOAT variable from ELF -- Unit_Identifier : out Program_Unit_Unique_Identifier; --| A unique ID assigned by the Source Instrumenter -- Variable_Name : out Ada_Name; --| The unqualified variable name -- Value : out Long_Float --| The current value of variable -- ); --| Effects --| Gets long_float values from the execution log file. --| Requires --| The log file must have been previously opened by the calling --| program via a call to Open_Log. --| The current log file key (i.e., the previously read key) --| must be LONG_FLOAT_VARIABLE. --| N/A: Raises, Modifies, Errors ------------------- procedure Get_Value (--| Gets value of STRING variable from ELF Unit_Identifier : out Program_Unit_Unique_Identifier; --| A unique ID assigned by the Source Instrumenter Variable_Name : out Ada_Name; --| The unqualified variable name String_Value : out String_Variables --| The current value of variable ); --| Effects --| Gets string values from the execution log file. --| This procedure used to get the value of --| strings --| characters --| enumerated data types (including booleans) --| Requires --| The current log file key (i.e., the previously read key) --| must be STRING_VARIABLE. --| N/A: Raises, Modifies, Errors ------------------- function End_Of_Log --| Checks for End Of file in the ELF return Boolean; --| True if EOF is reached else false --| Raises: Logfile_Access_Error --| Effects --| This function checks for End Of File in the ELF and returns true --| if an EOF has been reached. --| If the logfile is not open then the exception Logfile_Access_Error --| is raised. --| Text_IO exceptions that may be raised are allowed to pass, unhandled, --| back to the calling program. --| Requires --| The log file must have been previously opened by the calling --| program via a call to Open_Log. --| N/A: Modifies, Errors ------------------------ procedure Find_Unit_Name ( --| Finds the name of a program unit Unit_Identifier : in Program_Unit_Unique_Identifier; --| A unique ID assigned by the Source Instrumenter Unit_Name : out Ada_Name --| The name of program unit ); --| Raises: Undefined_Program_Unit --| Effects --| Finds the program unit unit name (Unit_Name) corresponding to the --| program unit ID. If no UNIT_DEF record has been previously --| encountered in the ELF to associate a program unit name with --| the specified unit ID then the Undefined_Program_Unit exception --| is raised. --| Requires --| A program unit name (Unit_Name) must have been previously recorded --| in the ELF and assosiated with the specified unit id (Unit_Identifier) --| by the program that originally generated the log file via a call --| to the procedure Define_Comp_Unit. --| N/A: Modifies, Errors ------------------------------ function Number_Of_Breakpoints (--| Finds the number of breakpoints --| in a compilation unit Compilation_Unit_Name : in Ada_Name --| The name of the compilation unit ) return Breakpoint_Number_Range; --| Raises: Undefined_Program_Unit --| Effects --| Gets and returns the total number of breakpoints in the --| specified compilation unit. If the compilation unit has --| not been previously defined in the logfile then the --| exception Undefined_Program_Unit is raised. --| Requires --| The compilation unit name must have been previously --| returned to the calling program in a Unit ID by the --| the procedure Get_Unit_ID. --| N/A: Modifies, Errors -------------------- function Timing_Data --| Returns true if the logfile contains timing data return Boolean; --| Raises: Logfile_Access_Error --| Effects --| Returns true if the logfile contains timing data. Otherwise --| returns false. This function provides a mechanism for the --| calling program to determine whether or not timing data --| has been recorded in the logfile prior to calling other --| Read_Log procedures that read times from the logfile. --| If the logfile is not open then the exception --| Logfile_Access_Error is raised. --| Requires --| The target Ada program must have been executed with --| Tool_Name = Profile_Tool in order for timing data to have --| been recorded in the log file and the current log file --| key must be Timing_Overhead. The log file must have been --| previously opened by the calling program via a call to Open_Log. --| N/A: Modifies, Errors ----------------------------- function Accumulated_Overhead --| Returns the Accumulated timing overhead --| calculated during test program execution return Calendar.Day_Duration; --| Raises: Logfile_Access_Error --| Effects --| Gets and returns the total accumulated timing overhead --| calculated during execution of the target Ada program. --| If the logfile is not open or the current logfile key is --| not then the exception Logfile_Access_Error is raised. --| Requires --| The target Ada program must have been executed with --| Tool_Name = Profile_Tool in order for timing data to have --| been recorded in the log file and the current log file --| key must be Timing_Overhead. --| N/A: Modifies, Errors ------------------- procedure Close_Log; --| Closes the execution log file --| Raises: Logfile_Access_Error --| Effects --| Closes the execution log file. --| If the logfile is not open then the exception Logfile_Access_Error --| is raised. --| Requires --| The log file must have been previously opened by the calling --| program via a call to Open_Log. --| N/A: Modifies, Errors end Read_Log;