PAL CARD CATALOG ENTRY

SHORT DESCRIPTION

Format and generate a report


MOVEMENT WITHIN THE PAL CARD CATALOG
Move to top-level taxonomy
Move to keyword list

ASSET PROFILE

UNIT NAME
Report
VERSION
1
REVIEW CODE
C1 1.0 A
INET ADDRESS
sun1.disacim.osd.mil (134.152.9.140)
AUTHOR
Retired Army Personnel Systems
Software Development Center
Washington, D.C.
RIGHTS
Approved for Public Release; Distribution Unlimited
COPYRIGHT
None -- Public Domain.
DATE CREATED
July 9, 1991
DATE RELEASED
January 17, 1994
DATE LAST UPDATED
January 17, 1994
LOCATION
DSRS Library
PAL
ENVIRONMENT
DEC Microvax II/VMS DEC Ada Version 2.0.
LIMITATIONS
Not documented in PAL database
CERTIFICATION
Ada System Certifier_1 1.0
Date/Time of Processing: Wednesday 25 May       1994 02:24:55Pm
Overall Assessment of System: OK
Classification of System: A
Basis of Classification --
Syntax Errors                               PASS
Completeness                                PASS
Independence from External Libraries        PASS
Independence from a Specific Ada Compiler   PASS

Number of ...
Files               3
Library Units      10
Lines            3645
Statements        595
Comments         1960

FILE LISTING

Directory Display


languages/ada/swcomps/dsrs/report:
  File Name                 Size
  ---------                 ----
  report.zip              48,519

languages/ada/swcomps/dsrs/strutil:
  File Name                 Size
  ---------                 ----
  strutil.zip             23,876

languages/ada/swcomps/dsrs/charutil:
  File Name                 Size
  ---------                 ----
  charutil.zip            15,401


Totals
  ==============  ==============
    3 Files               87,796

ABSTRACT

                                     Report
                                   01D001P3.1
                               (Old ID: WIC0004A)
PURPOSE/INTENDED USE:
Report is a generic Ada package that allows a user to create and output
reports of any format according to the actual generic parameters. Data
records are read from an input text file, formatted according to user
specifications, and written to a report file.  This report file can then
be written to the standard output device.  Any additional operations
needed can be built out of the operations provided in this package.

The actual generic parameters control the basic information about the
report:
    o  Report page width.
    o  Report page length.
    o  Number of lines per report record.
    o  Number of words (items) in each input data record.
    o  Number of words (items) that repeat in each input data record.
    o  Number of blank lines between each report record.
    o  Number of report records per group of records.
    o  Maximum number of fields in a line of information.
    o  Number of lines of totals information.
    o  Procedure to write a cover sheet.
    o  Procedure to write headers for each page.
    o  Procedure to write footers for each page.
    o  Procedure to write a totals information at the end of the report.

EXAMPLE APPLICATIONS:
Reuse of this package would be valuable when an application needs to
produce formatted output from a text file. An example of instantiating
this package for a system wanting to produce a formatted report from a
text data file is as follows: 
      
   package New_Report is new Report 
      (Report_Page_Width  => 80,        Report_Page_Length => 51,
       Num_Of_Info_Lines  => 4,         Num_Of_Info_Words  => 20,
       Num_Of_Constant_Words     => 0,  Num_Of_Lines_Between_Info => 1,
       Num_Of_Grouped_Info       => 1,  Max_Num_Of_Fields_In_Line => 5,
       Num_Of_Lines_For_Totals   => 0,  Cover_Sheet => Generate_Cover,
       Header => Generate_Header,       Footer => Generate_Footer);

CERTIFICATION LEVEL:
Report is certified at Level 4.  This means that the Defense Information
Systems  Agency/Center for Information Management Software Reuse Program
(SRP) management  office has successfully compiled the code of this
Reusable Software Asset (RSA)  and measured maintainability,
portability, reliability and reusability.  In  addition, this RSA
includes a test suite and a Reuser's Manual, which will be  provided
when the asset is extracted. 
 
IMPLEMENTATION ISSUES:
Report depends on (withs) String_Utilities (01D001O3). The code supplied
when Report is extracted includes four template subprograms. Report
depends on (withs) the four subprograms.  Report and the four
subprograms all depend on the Ada predefined package Text_Io. The four
subprograms are: 

   -- Default procedure for generic formal procedure Cover_Sheet.
   procedure Produce_Cover_Sheet (Report : in Text_Io.File_Type;
                                 Error  : out BOOLEAN) is 

   -- Default procedure for generic formal procedure Header.
   procedure Produce_Header (Report : in Text_Io.File_Type;
                            Error  : out BOOLEAN) is

   -- Default procedure for generic formal procedure Footer.
   procedure Produce_Footer (Report             : in Text_Io.File_Type;
                            Report_Page_Number : in out NATURAL;
                            Error              : out BOOLEAN) is

   -- Default procedure for generic formal procedure Totals.
   procedure Produce_Totals (Report        : in Text_Io.File_Type;
                            Error         : out BOOLEAN) is 

The basic structure of the report (page width, page length, header
procedure, etc.) is defined during the instantiation of Report. The
generic formal  parameters are as follows:

   -- Page width for the report.
   Report_Page_Width         : POSITIVE := 80;
   -- Page length of the report MINUS the number of lines in the header and
   -- the footer.  
   Report_Page_Length        : POSITIVE := 60;
   -- Number of lines for each report record.  
   Num_Of_Info_Lines         : POSITIVE := 1;
   -- Number of words in each report record.
   Num_Of_Info_Words         : POSITIVE := 1;
   -- Number of words that repeat in all the report records.  
   Num_Of_Constant_Words     : NATURAL  := 0;
   -- Number of lines to skip between each report record.  
   Num_Of_Lines_Between_Info : NATURAL  := 1;
   -- Number of report records in a group.  
   Num_Of_Grouped_Info       : POSITIVE := 1;
   -- Maximum number of fields to be included in a line of information.   
   Max_Num_Of_Fields_In_Line : POSITIVE := 1;
   -- Number of lines to be used to output totals information.  
   Num_Of_Lines_For_Totals   : NATURAL  := 0;
   -- Outputs a cover sheet to the report file using Text_Io.
   with procedure Cover_Sheet (Report  : in Text_Io.File_Type;
                              Error   : out BOOLEAN) is Produce_Cover_Sheet;
   -- Outputs a header to the report file using Text_Io.
   with procedure Header (Report : in Text_Io.File_Type;
                         Error  : out BOOLEAN) is Produce_Header;
   -- Outputs a footer to the report file using Text_Io.
   with procedure Footer (Report             : in Text_Io.File_Type;
                         Report_Page_Number : in out NATURAL;
                         Error              : out BOOLEAN) is
                             Produce_Footer;
   -- Outputs totals information to the report file using Text_Io.
   with procedure Totals (Report        : in Text_Io.File_Type;
                         Error         : out BOOLEAN) is Produce_Totals;

If the Report_Page_Length plus the number of lines in header and footer
is not the same as the number of lines the printer to be used for output
counts before a form feed, the user needs to print an ASCII.FF at the
end of each report page (use the Footer for that). 

Report defines the following exceptions:       
  Input_File_Already_Open            Invalid_Input_File_Name      
  Report_File_Already_Open           Invalid_Report_File_Name     
  End_Of_Input_Line_Reached          Error_Formatting_Input_Line  
  Error_Generating_Cover_Sheet       Error_Generating_Header      
  Error_Generating_Footer            Error_Generating_Totals      

The generic actual parameters provided at the time of instantiation
describe the basic format of each report entry.  The actual parameters
to the procedure Report.Generate_Report provide the specifics of how the
data is formatted for each report entry.  The text file created by this
procedure contains the report data in printer ready format. The input
parameters to Report.Generate_Report that control the specific
information about the report are as follows: 
   o  Name of the input data file.
   o  Name of the output report file.
   o  Constant strings to be included in each report record.
   o  Format of each line of a report record.
   o  Length of each word in the input data record.
   o  Order in which each word in the input data record will be output.

The user has the option of deleting the generated report file after
writing the report. 

HARDWARE/ENVIRONMENT CONSTRAINTS AND LIMITATIONS:
This package was compiled, linked, and tested on a DEC Microvax II with
VMS  operating system and running the DEC Ada Version 2.0.

SUBUNITS:
Report has the following visible subunits:
   Generate_Report   Reads records from a text data file and formats
                     the data into report records.    
   Output_Report     Writes a report text file to standard output.  

DSRS CLASSIFICATION:
algorithm:  sequential
availability:  extractable
certification level:  level_4
component type:  implementation
data representation:  string
environment:  mvii/vms/vaxada
function:  edit
function:  format
function:  generate
function:  input/output
function:  report
language:  ada
object:  file
object:  record
originator:  raps
unit type:  generic_package
unit type:  package

LEGAL RESTRICTIONS:
This RSA contains public domain data with unlimited rights for all
users.   Extraction is permitted to all authorized library users. This
software and its documentation are provided "as is" and without any
expressed or implied warranties whatsoever.  No warranties as to
performance, merchantability, or fitness for a particular purpose exist.

The user is advised to test the software thoroughly before relying on
it.  The user must assume the entire risk and liability of using this
software.  In no event shall any person or organization of people be
held responsible for any direct, indirect, consequential or
inconsequential damages or lost profits. 

MISCELLANEOUS:
The standard for Level 4 certification has recently been upgraded. This
asset is currently undergoing modification to meet the new Level 4
requirements. 


REVISION HISTORY

January 17, 1994 Version 1 Original submission to PAL


RELEASE NOTICE

This prologue must be included in all copies of this software.
Restrictions on use or distribution:  NONE

LEGAL RESTRICTIONS:
This RSA contains public domain data with unlimited rights for all
users.   Extraction is permitted to all authorized library users. This
software and its documentation are provided "as is" and without any
expressed or implied warranties whatsoever.  No warranties as to
performance, merchantability, or fitness for a particular purpose exist.


DISCLAIMER

 This software and its documentation are provided "AS IS" and
without any expressed or implied warranties whatsoever.  No warranties
as to performance, merchantability, or fitness for a particular
purpose exist.
 The user is advised to test the software thoroughly before
relying on it.  The user must assume the entire risk and liability of
using this software.  In no event shall any person or organization of
people be held responsible for any direct, indirect, consequential or
inconsequential damages or lost profits.