Click above to get retro games delivered to your door ever month!

 FiveWin Report Engine
--------------------------------------------------------------------------------

  We want to thank our friend Ignacio Ortiz de Zu.iga for his excellent
  work and contribution to the FiveWin Report engine,

--------------------------------------------------------------------------------

  ( many thanks also to Roger Seiler for his great help on documenting the
    FiveWin Report Engine)

    All the reports have the following construction:

    LOCAL oReport

    REPORT oReport ...
    COLUMN ...
    COLUMN ...
    END REPORT

    ACTIVATE REPORT oReport ...

    As you can see the basic construction is very simple. Here is the
    complete syntax with all the optional bells and whistles:

    REPORT [ <oReport> ] ;
        [ TITLE <bTitle, ...> [< LEFT | CENTER | CENTERED | RIGHT > ] ];
        [ HEADER <bHead, ...> [< LEFT | CENTER | CENTERED | RIGHT > ] ];
        [ FOOTER <bFoot, ...> [< LEFT | CENTER | CENTERED | RIGHT > ] ];
        [ FONT <oFont, ...> ]  ;
        [ PEN <oPen, ...> ]  ;
        [ < lSum:SUMMARY >  ] ;
        [ < file: FILE |  FILENAME |  DISK >  <cRptFile> ] ;
        [ < resource: NAME |  RESNAME | RESOURCE >  <cResName> ] ;
        [ < toPrint: TO PRINTER >  ] ;
        [ < toScreen: PREVIEW >  ] ;
        [ TO FILE <toFile> ] ;
        [ TO DEVICE <oDevice> ] ;
        [ CAPTION <cName> ]

    GROUP [ <oRptGrp> ] ;
       [ ON <bGroup> ] ;
       [ HEADER <bHead> ] ;
       [ FOOTER <bFoot> ] ;
       [ FONT <uFont> ] ;
       [ < lEject:EJECT >  ]

    COLUMN [ <oRptCol> ] ;
        [ TITLE <bTitle, ...> ] ;
        [ AT <nCol> ] ;
        [ DATA <bData, ...> ] ;
        [ SIZE <nSize> ] ;
        [ PICTURE <cPicture, ...> ] ;
        [ FONT <uFont> ] ;
        [ < total: TOTAL >  [ FOR <bTotalExpr> ] ] ;
        [ < ColFmt:LEFT | CENTER | CENTERED | RIGHT >  ] ;
        [ < lShadow:SHADOW >  ] ;
        [ < lGrid:GRID >  [ <nPen> ] ]

    ENDREPORT

    ACTIVATE REPORT <oReport> ;
       [ FOR <for> ] ;
       [ WHILE <while> ] ;
       [ ON INIT <uInit> ] ;
       [ ON END <uEnd> ] ;
       [ ON STARTPAGE <uStartPage> ] ;
       [ ON ENDPAGE <uEndPage> ] ;
       [ ON STARTGROUP <uStartGroup> ] ;
       [ ON ENDGROUP <uEndGroup> ] ;
       [ ON STARTLINE <uStartLine> ] ;
       [ ON ENDLINE <uEndLine> ] ;
       [ ON CHANGE <bChange> ]


    With the command COLUMN (syntax above) you indicate all the
    columns that the report will have indicating the data and the
    title of each column. This can be very simple. For example:

    COLUMN TITLE "Name" DATA Test->Name

    ------------------------
    REP02.PRG

    IMPLEMENTING TOTALS:

    If you want a Total on any column just add the word TOTAL in the
    command, for example:

    COLUMN TITLE "Salary" DATA Test->Salary TOTAL

    ------------------------
    REP03.PRG

    HEADERS & FOOTERS:

    You can put any header and footer on the report by declaring them
    in the REPORT command. For example:

    REPORT oReport TITLE "My First Report" ;
         HEADER "This is the header" ;
         FOOTER "This is the footer"

    You can even specify how it will be written: left, centered or right,
    adding the word LEFT, RIGHT or CENTER|CENTERED. For example:

    REPORT oReport TITLE "My First Report" ;
         HEADER "This is the header" RIGHT ;
         FOOTER "This is the footer" CENTER

    Remember: by default Titles are centered and Headers and Footers are
    written on the left side.

    -------------------------
    REP04.PRG

    MULTILINE TITLES, HEADERS AND FOOTERS:

    If you want more than one line for a title just put a comma between
    each title. For example:

    REPORT oReport ;
        TITLE "My First Report", "with FiveWin"

    The same happens with headers and footers.

    The report engine NEVER puts a white line between the header and the
    title or between the title and the column titles. It is up to you to
    put the blank lines wherever you want them. For example, if you want
    to put a blank line between the header and the title, just indicate a
    second line on the header with nothing on it -- just an empty chain:

    REPORT oReport TITLE "My Report ;
         HEADER "My Header", " "

    -------------------------
    REP05.PRG

    USING EXPRESSIONS:

    You can put almost anything you want in your reports because you can
    use any expression that returns a character string, remember this is
    the key to do almost anything you want. For example, if you want to
    put the date() on the report plus the current page number, just
    do the following:

    REPORT oReport TITLE "My Report" ,;
     "date:"+DtoC(Date())  ;
          FOOTER "Page Number: "+ ;
                         Str(oReport:nPage,3)

    You can put expressions rather than character strings in almost
    anywhere: Titles, Headers, footers, Column titles, column data, etc...

    --------------------------
    REP06.PRG

    REPORT DESTINATION:

    By default, the report is sent to the printer, but you can change it
    when you create the report:

    REPORT oReport .... ;
        TO PRINTER  => (The default)

    REPORT oReport .... ;
        PREVIEW  => (To Screen)

    REPORT oReport .... ;
        TO FILE <cFile>  => (Txt format)

    When you send the report to the screen (PREVIEW), the report engine
    creates all the pages until you push the button Preview, and then
    you will immediately see the first page created.

    When you create a Report you can specify a caption for it. This
    caption would be the title of the preview Window if you send the
    report to the screen, or it will be the description on the spooler if
    you send it to the printer. (In previous releases we used the word
    NAME for this.)

    -------------------------------
    REP07.PRG

    USING FONTS:

    You can use any font you want with your reports. This is the way you
    use them:

    First you have to define them with the command DEFINE FONT oFont ....

     DEFINE FONT oFont1 NAME "ARIAL" SIZE 0,-10
     DEFINE FONT oFont2 NAME "ARIAL" SIZE 0,-10 BOLD

    The size (width,height) specs. use different units of measure when
    printed versus displayed on screen.  On screen, the units are pixels,
    but when printed, the units are font "points".  Thus, for printed
    text, we only use the second size specification (height) to give the
    point size, leaving the "width" as "0".  The point size is given as
    a negative number, i.e. "10 point" is "-10".  Remember that point
    size for proportionally spaced type is different than "pitch," which
    is the term often used for non-proportionally spaced "typewriter" type
    like Courier.  Point size refers to letter height, whereas pitch
    refers to the number of equal-spaced letters printed per inch. Regular
    "pica" sized typewriter type is 10 pitch - 10 letters per inch. But
    represented in point size, this is 12 point -- very confusing because
    the smaller "elite" typewriter type is 12 pitch - 12 letters per inch,
    which is 9 point.  (With "pitch," the bigger the number, the smaller
    the font -- just the opposite of how "point" size works.) Now to add
    to the confusion, remember that in this Report Engine, we let FiveWin
    know that we're working with point size instead of pixels by using
    negative numbers for points (and we must use points instead of pitch
    for equal-spaced fonts like Courier).  In this case, the "-" sign
    isn't mathematical -- it doesn't mean (as math rules would suggest)
    that your point size gets smaller as the integer gets bigger.  Just
    the reverse. The bigger the integer, the bigger the point size.  If
    you're still confused, there's a fellow named Guttenberg on CIS who
    can explain it all to you.

    When you create the report, you specify the fonts you want to use,
    separating each one with a comma.

    For example:

    REPORT oReport TITLE ..... ;
         FONT oFont1, oFont2, oFont3

    The first font in the list (oFont1) will be the standard font, so if
    you do not specify a font for a specific column it will use the
    standard font (oFont1).

    If you want a column to use the second font just do the following:

    COLUMN TITLE ... DATA .... FONT 2

    As you can see, you indicate the ordinal number in the list of fonts
    defined when you create the report.

    Again, you can use an expression this way:

    COLUMN TITLE ... DATA ... ;
          FONT iff(Test->Salary>1000,2,1)

    Remember to release the fonts after the report is done.

    Now here is the complete syntax:

    Defining a font:         DEFINE FONT <oFont> ;
                                [ NAME <cName> ] ;
                                [ SIZE <nWidth>, <nHeight> ] ;
                                [ FROM USER ];
                                [ BOLD ] ;
                                [ ITALIC ] ;
                                [ UNDERLINE ] ;
                                [ WEIGHT <nWeight> ] ;
                                [ OF <oDevice> ] ;

                                [ NESCAPEMENT <nEscapement> ] ;

                             ACTIVATE   FONT <oFont>

                             DEACTIVATE FONT <oFont>

                             RELEASE FONT <oFont>

                             SET FONT ;
                                [ OF <oWnd> ] ;
                                [ TO <oFont> ]


    <oFont>         A reference to the Font Object.

    <cName>         The name of the font. Example: Arial, Roman, etc...

    <nWidth>,       Dimensions of the font -- pixels for screen fonts, but
    <nHeight>          points for printed fonts.  For printed fonts, use
                       "0" for <nWidth> and use <nHeight> for the points with
                       a minus sign in front of the points number.

    <oWnd>          A reference to the Window container.

    <oDevice>       The device owner of the font.

    <nWeight>       The weight of the font.

    <nEscapement>   The escapement of the font.

    CLAUSES

    FROM USER       Displays the Font selection Dialog Box.

    BOLD            To create the font with bold feature.

    ITALIC          To create the font with italic feature.

    UNDERLINE       To create the font with underline feature.


    ------------------------------
    REP08.PRG

    CONFIGURING COLUMNS:

    When you create the columns, you can specify a lot of behavior:

    - PICTURE: As same as GETS
    - SIZE: Length of the column (number of Chars)
    - AT: Print at specific column (better not use it)
    - FONT: Font to use (number in the list of fonts)
    - TOTAL: if the column should have a total

    If you specify that the column has a total, the DATA should be a
    number. But if not, do not worry -- the report engine does not break.
    The TOTAL clause can have also a FOR condition. For example:

    COLUMN DATA ... TOTAL FOR Test->Name = "Peter"

    - LEFT|CENTER|CENTERED|RIGHT: You can also specify the way the text is
    going to be printed, left, center or right. By default, everything is
    left formated except numeric data which is right.

    ----------------------------
    REP09.PRG

    MULTILINE COLUMNS:

    This is something you will really love: suppose you need to put
    another column but you do not have enough width on the paper to do it?

    You could use a smaller font, but this is not the best way. The best
    way is to use multi lines for columns. That means that one database
    register can use more than one line on the report. So we can do
    something like this:

    Name                Salary
    =================== ===========
    Test->First         Test->Salary
    Test ->Last

    This is as simple as:

    COLUMN DATA Test->First, Test->Last

    Just separate with a comma the data you want to be printed.

    You can do the same with the column title, like this:

    COLUMN DATA Test->First, Test->Last ;
         TITLE "First Name" ,"Last Name"

    If you put a TOTAL on that column, all the numeric data will be added.
    All the data will have the same picture, but I will explain later
    how to change this behavior.

    --------------------------
    REP10.PRG

    MAKING GROUPS:

    To make a group means to have a subtotal on a particular kind of
    data. With the report form you can make two groups. With other report
    generators you can make up to 9, but with FiveWin Report Engine you
    have no limit.

    If you want the totals of the groups to be printed you must totalize
    at least one column.

    The data, of course, should be sorted in accord with the group
    expression.

    To make a Group just do the following:

    REPORT oReport ....
    COLUMN ....
    COLUMN ....

    GROUP ON Test->State EJECT

    END REPORT

    The report will totalize each column that has been created with the
    TOTAL clause for every State and will make a page eject when the
    State changes.

    You can even specify a Header, a Footer and a font to use for that
    group (just one line on Headers and Footers):

    GROUP ON Test->State ;
         FOOTER "Total State:"  ;
         FONT 2 ;
         EJECT

    Remember, you can have all the groups you want.

    --------------------------
    REP11.PRG

    SUMMARY REPORTS:

    If you specify the clause SUMMARY when you create the report:

    REPORT oReport TITLE ... SUMMARY

    it will only print the information about groups. So the clause
    SUMMARY should only be used when there is at least one group defined.

    When you use the SUMMARY clause the report engine does not put any
    group separator line.

    ---------------------------
    REP12.PRG

    CONTROLLING THE FLOW OF THE REPORT:

    When you activate the report, it is possible to define FOR and WHILE
    conditions. For example:

    ACTIVATE REPORT oReport    ;
         WHILE Test->State = "A"  ;
         FOR Test->Salary > 1000

    Because the report engine can make a report even from an array, by
    default the WHILE condition is "!Eof()". So if you change the WHILE
    condition, you must take care that if you are making a report from a
    database it is a good practice to include in the WHILE condition the
    text  ".and. !Eof()":

    ACTIVATE REPORT oReport    ;
         WHILE Test->State = "AZ"  .AND. !Eof() ;
         FOR Test->Salary > 100000

    You can even control the flow of the report in the same manner as you
    do with other windows.

    When you activate the report you can indicate functions that will be
    called when the report is in a particular state:

    ACTIVATE REPORT oReport ;
         ON INIT ... ;
         ON END .... ;
         ON STARTPAGE ....;
         ON ENDPAGE ... ;
         ON STARTGROUP .... ;
         ON ENDGROUP .... ;
         ON STARTLINE ... ;
         ON ENDLINE .... ;
         ON CHANGE ...

    The INIT function is called just one time on the first page after the
    column titles are printed.

    The END function is called just one time on the last page after the
    Grand totals are printed.

    The STARTPAGE is called on every start of a page. This is one of the
    most used because in this clause you will put bitmaps, lines, boxes,
    etc...

    The ENDPAGE is called on every end of a page, when all the text is
    printed (not very useful).

    The STARTGROUP is called on every start of a group and before the
    header of the group is printed (if there is one).

    The ENDGROUP is called on every end of a group.

    The STARTLINE is called on every start of a line of the report body.
    When STARTLINE is evaluated, the report engine is controlling if the
    following line will fit in the current page, and if not, it will do
    an Eject and start a new page. Be carefull when using STARTLINE,
    because if you use Multiline columns there will be at least two
    STARTLINES for each record processed.

    The ENDLINE is called on every end of line of the body report. When
    ENDLINE is evaluated all the line has been printed and the current
    report line is been incremented.

    The CHANGE is called on every "SKIP" if you are listing a database.
    For practical purposes, this function is called before the SKIP and
    not after. This is also a clause you will use a lot.

    In the source code we have include a blank line on StartGroup and a
    sound beep when the report is finished.

    IMPORTANT: Be careful when using these clauses. Remember you are
    inside the report flow, so you must take care of all the databases,
    indexes, etc.. that the report is using.