                         Alexander Kresin
                Clipper report engine (Windows version)

   In this article I'll tell you about a reports engine, which provides
 a storage of the output form descriptions in a textual file,
 rather than in a program's body, that allows to modify the forms of
 reports and create new without any changes in the program's code.

    The idea of building reports with form description, keeping
 in the separate textual file, isn't new. Multiple accounting packages uses
 one or another realization of this method. I don't going to analyse all
 known realizations and to compare its with mine. I want to say only that
 possibility of my engine sufficient to build the most varied output forms.

    But now - a digest of method.

    A textual file may include a lot of form descriptions. Application
 need to know file name and three-symbol code of report ( these can be kept
 in the program source, in ini file or in dbf reference book of reports ).

    The Form Description begins with word #BLANK/report_code and ends a word
 #ENDBLANK ( all keywords begin from the symbol # ). In the #BLANK directive
 after the code of report may follow the name of the font.
    If is necessary create several different output forms for one report
 is used following design:

   #BLOCK/report_code
   @form_code_1  Name_of_the_form_1
   @form_code_2  Name_of_the_form_2
   .....
   #ENDBLOCK

   And then in the file are placed form descriptions, beginning with
 #BLANK/form_code_1, #BLANK/form_code_2 and etc, or structures #BLOCK,
 embedded in first. Degree of nesting of structures #BLOCK... #ENDBLOCK
 theoretically not limited.

  The Form Description can contain:
  ) report headers and footers,
  ) page headers and footers,
  ) description of columns of report,
  ) groups descriptions.

    No one of these parts is obligatory. The form can consist only from the
 headers .

  Place can be reserved in the text of description for variables. In the
 description of headers and footers they begin a figured bracket with the
 following number ( two symbols ) of a variable, in the column description and
 groups - a square bracket with the number. If it is necessary to calculate
 a total of a row, you should place square parentheses with the same number
 as appropriate column variable, in the footer.
  At the end of description of the form are usually located descriptions of
 variables.
  They begin with the sign "@" with the following variable number.

 Here is some controlling strings for report engine.

#BLANK/cod/font   -   beginning of the form description,
                      cod has 3 symbols.
#ENDBLANK         -   end of the form description.
#PAGE             -   beginning of the page description.
#ENDPAGE          -   end of the form description.
#STR              -   beginning of the columns description.
#ENDSTR           -   end of the columns description.
#SUB              -   beginning of the group description.
#ENDSUB           -   end of the group description.
#SKIP n           -   skip n lines.
#FUNC expression; -   execute an expression.

~               ~              ~                         ~              4
   this is a directive to draw a box with a height of 4 lines, divided on
   columns in the places, specified by '~' symbols. ( Only first '~' specifies
   not divider, but a beginning of a directive. ).

~  1                                                         1          L
   this is a directive to draw a line from first '1' to second '1'.

~       ~               ~                 ~                    ~        ;
   this is a directive to set a tabulation for following output.

^n - set a font number n (its descrioption is in a line, beginning with
 '@^n='

@nn - expression for a variable number nn. This expression must be a character
 type and terminate with ';' .

---------------------------------------------------------------------------
 This package include:

   build.bat   -  batch file for building genrpt.exe
   build.lnk   -  blinker script file
   genrpt.prg  -  sample program for testing report engine including engine functions
   rasnkl.dbf,
   rashod.dbf,
   rashod.ntx  -  sample files
   wreest.txt  -  sample file with form description
   readme.txt  -  the file you are reading now
   
---------------------------------------------------------------------------
 (C) Alexander Kresin
 mailto:alex@belacy.belgorod.su
 http://members.xoom.com/alkresin/