REPORT FORM
 Display a report to the console
------------------------------------------------------------------------------
 Syntax

     REPORT FORM <xcReport>
        [TO PRINTER] [TO FILE <xcFile>] [NOCONSOLE]
        [<scope>] [WHILE <lCondition>] [FOR <lCondition>]
        [PLAIN | HEADING <cHeading>] [NOEJECT] [SUMMARY]

 Arguments

     <xcReport> is the name of the report form (.frm) file that contains
     the definition of the REPORT.  If an extension is not specified, (.frm)
     is assumed.  <xcReport> can be specified as a literal string or as a
     character expression enclosed in parentheses.

     TO PRINTER echoes output to the printer.

     TO FILE <xcFile> echoes output without form feed characters (ASCII
     12) to a file.  If a file extension is not specified, .txt is added.
     You can specify <xcFile> as a literal string or as a character
     expression enclosed in parentheses.

     NOCONSOLE suppresses all REPORT FORM output to the console.  If not
     specified, output automatically displays to the console unless SET
     CONSOLE is OFF.

     <scope> is the portion of the current database file to report.  The
     default scope is ALL.

     WHILE <lCondition> specifies the set of records meeting the
     condition from the current record until the condition fails.

     FOR <lCondition> specifies the conditional set of records to report
     within the given scope.

     PLAIN suppresses the display of the date and page number, and causes
     the report to print without page breaks.  In addition, the report title
     and column headings display only at the top of the report.

     HEADING places the result of <cHeading> on the first line of each
     page.  <cHeading> is evaluated only once at the beginning of the report
     before the record pointer is moved.  If both PLAIN and HEADING are
     specified, PLAIN takes precedence.

     NOEJECT suppresses the initial page eject when the TO PRINTER clause
     is used.

     SUMMARY causes REPORT FORM to display only group, subgroup, and
     grand total lines.  Detail lines are suppressed.

 Description

     REPORT FORM is a console command that sequentially accesses records in
     the current work area and displays a tabular and optionally grouped
     report with page and column headings from a definition held in a .frm
     file.  The actual REPORT FORM file (.frm) is created using RL.EXE or
     dBASE III PLUS.  Refer to the "Report and Label Utility" chapter in the
     Programming and Utilities Guide for more information about creating
     report definitions.

     When invoked, REPORT FORM sends output to the screen and, optionally, to
     the printer and/or a file.  To suppress output to the screen while
     printing or echoing output to a file, SET CONSOLE OFF or use the
     NOCONSOLE keyword before the REPORT FORM invocation.

     When invoked, REPORT FORM searches the current SET PATH drive and
     directory if the <xcReport> file is not found in the current directory
     and the path is not specified.

 Notes

     .  Interrupting REPORT FORM: To allow the user to interrupt a
        REPORT FORM, use INKEY() to test for an interrupt key press, as a
        part of the FOR condition.  See the example below.

     .  Printer margin: REPORT FORM obeys the current SET MARGIN value
        for output echoed to the printer.

     .  Forcing formfeed characters into an output file: To include
        form feed characters when sending a REPORT FORM TO FILE, redirect
        printer output to a file using SET PRINTER like this:

        SET PRINTER TO <xcFile>
        REPORT FORM <xcReport> TO PRINTER
        SET PRINTER TO

     .  Reporting in a network environment: REPORT FORM commands
        executed in a network environment can be affected by changes made to
        database files by other users while the report is in progress.  For
        example, if a user changes a key value from "A" to "Z" while the
        report is printing, the same record could appear twice.

 Examples

     .  This example uses both a literal and an extended expression to
        execute a REPORT FORM:

        LOCAL xcReport := "Sales"
        USE Sales INDEX Sales NEW
        REPORT FORM Sales TO PRINTER FOR Branch = "100";
                  HEADING "Branch 100"
        REPORT FORM (xcReport) TO PRINTER FOR Branch != "100"

     .  This example interrupts a REPORT FORM using INKEY() to test
        whether the user has pressed the Esc key:

        #define K_ESC  27
        USE Sales INDEX Sales NEW
        REPORT FORM Sales WHILE INKEY() != K_ESC

 Files   Library is CLIPPER.LIB.