REPORT FORM Command

Article
06/24/2008

Displays or prints a report specified by a report definition (.frx) file, for example, created with the CREATE REPORT or MODIFY REPORT command.

The REPORT FORM command can interpret Visual FoxPro label files (lbx format) as well as report files. You can also use REPORT FORM to run character-based report files created in FoxPro for MS-DOS.

REPORT FORM FileName1 | ? [ENVIRONMENT] [Scope] 
   [FOR lExpression1] [WHILE lExpression2] [NOOPTIMIZE]
   [RANGE nStartPage [, nEndPage]]
   [HEADING cHeadingText] [SUMMARY] [NORESET] [PLAIN]
   [NOCONSOLE | OFF] [PDSETUP] 
   [NAME ObjectName] 
   [OBJECT oReportListener | TYPE iExpression]
   [TO OutputDestination [NODIALOG]] 
   [PREVIEW [PreviewDestination] [NOWAIT] [WINDOW WindowName]]

Parameters

FileName1 | ?
Specifies the name of a report definition (.frx) file or displays the Open dialog box so you can choose an .frx file. By default, the report displays in the current output window.

Note

The default file name extension for a report definition file is .frx. If the .frx file is not in the default directory or folder, you must include file name with the path. Starting with Visual FoxPro 7.0, FileName1 is included in the status message, which appears when you include the TO clause. To suppress the status message, see the description for the TO clause.
[ENVIRONMENT]
Opens and restores all tables and relations in the data environment associated with the report even when AutoOpenTables is set to False (.F.).

Note

The ENVIRONMENT keyword is included for backward compatibility, for example, reports converted from earlier versions of FoxPro, such as 2.x reports.

To restore the data environment associated with a Visual FoxPro report, set the data environment's AutoOpenTables property to True (.T.) (default). To make sure that the report environment is closed when the report has finished printing, set the data environment's AutoCloseTables property to True (.T.) (default). For more information, see AutoOpenTables Property and AutoCloseTables Property.

[Scope]
Specifies a range of records to include in the report. Only the records that fall within the scope range are included in the report.

Note

When you include a Scope clause, the scope operates only on the table in the active work area.

The following table lists possible values for Scope.

Scope	Description
ALL	Include all records. (Default)
NEXT nRecords	Include the next nRecords number of records beginning with the current record.
RECORD nRecordNumber	Include only the specified record.
REST	Include a range of records beginning with the current record and ending with the last record.

For more information on scope clauses, see Scope Clauses.

[FOR lExpression1]
Prints data only in those records for which the logical expression specified by lExpression1 evaluates to Tue (.T.). By including the FOR clause, you can exclude records you do not want to print.

Tip

If lExpression1 is an optimizable expression, Rushmore Query Optimization optimizes REPORT FORM with the FOR clause. For best performance, use an optimizable expression in the FOR clause. For more information, see SET OPTIMIZE Command and Using Rushmore Query Optimization to Speed Data Access.
[WHILE lExpression2]
Prints data only while the logical expression specified by lExpression2 evaluates to True (.T.).
[NOOPTIMIZE]
Prevents Rushmore optimization for REPORT FORM.

For more information, see SET OPTIMIZE Command and Using Rushmore Query Optimization to Speed Data Access.
[RANGE nStartPage [, nEndPage]]
Specifies a range of pages to print or other output.

The nStartPage parameter specifies the first page to print, while the nEndPage parameter specifies the last page to print. If nEndPage is omitted, the last page to print defaults to 32,767.

Note

RANGE selects pages for output, while scope clauses, FOR, and WHILE clauses select records. These selection criteria do not have an effect if you choose to print from preview, unless you have specified object-assisted mode by using the OBJECT clause or SET REPORTBEHAVIOR 90. In object-assisted mode, you can print either the full RANGE you specified on the original REPORT FORM command or some subset of that page range, using the ReportListener.CommandClauses's PrintPageCurrent, PrintRangeFrom, and PrintRangeTo members. For more information, see OnPreviewClose Method.
[HEADING cHeadingText]
Specifies text to place as an additional heading on each page of the report. If you include the HEADING clause and PLAIN keyword, the PLAIN keyword takes precedence.
[SUMMARY]
Suppresses detail line printing so that only totals and subtotals print.
[NORESET]
Specifies that the _PAGENO and _PAGETOTAL system variables are not reset. The page count for the current report begins at the current values of these two variables. For more information, see _PAGENO System Variable and _PAGETOTAL System Variable.

Note

If you use the NORESET and RANGE keywords together, you must calculate beforehand which pages to print.
[PLAIN]
Suppresses page headings except at the beginning of the report.
[NOCONSOLE | OFF]
Suppresses displaying the report in the main Visual FoxPro window or a user-defined window when printing the report or sending it to a file.

Note

When you use Visual FoxPro 9.0's object-assisted output mode, REPORT FORM does not display the contents of your report to the current output window, so the NOCONSOLE and OFF keywords have no effect on native behavior. However, the keywords are available in the ReportListener.CommandClauses object. You can evaluate them in your ReportListener derived classes, and opt to suppress a display of report content or other user feedback based on their contents. For more information, see CommandClauses Property.
[PDSETUP]
Loads a printer driver setup.

You can include PDSETUP to use a printer driver setup for printing character-based reports created in FoxPro for MS-DOS. PDSETUP is ignored when you print graphics-based reports created in Visual FoxPro.
[NAME ObjectName]
Specifies an object variable name for the data environment associated with the report.

Note

The data environment and the objects in the data environment have properties and methods, such as the AddObject method, that need to be set or called at run time. The object variable provides access to these properties and methods.

If you omit the NAME clause, Visual FoxPro uses the name of the report file, which can be referenced in code associated with events, by default.
[OBJECT oReportListener | TYPE iExpression ]
Invokes Visual FoxPro's object-assisted output mode. Use either an object reference to an object derived from the ReportListener base class, or a numeric value specifying a type of output. The OBJECT clause on an individual REPORT FORM command takes precedence over the current setting of SET REPORTBEHAVIOR. For more information, see ReportListener Object, ListenerType Property, and OutputType Property (Visual FoxPro).

[TO OutputDestination [NODIALOG]]
Specifies an output destination for the report. To suppress status messages that appear at run time, include the NODIALOG keyword.

Note

In output-assisted output mode, NODIALOG sets the ReportListener object's QuietMode property to .T. for the duration of the report run. For more information, see QuietMode Property.

The following table describes the possible values of OutputDestination.

OutputDestination	Description
[PRINTER [PROMPT] [NOPAGEEJECT] [NOEJECT]]	Sends the report to the printer. To display the Print dialog box before printing starts, include the PROMPT keyword. In object-assisted mode, the options enabled in the Print dialog box are affected by the ReportListener.CommandClauses.PrintPageCurrent member value. To specify that Visual FoxPro does not force a sheet eject at the end of a report and leaves the print job open, include the NOPAGEEJECT keyword. The next report printed is added to the open print job. You must make sure that the last report run does not have a NOPAGEEJECT clause so the print job can be closed. NOPAGEEJECT is valid only during program execution. It is disregarded when issued in the Command window. Changing between page orientations, such as landscape to portrait, between reports is not supported. You can chain multiple reports using NOPAGEEJECT and have page numbers continue from one report to the next. This is a useful technique for tasks such as faxing reports. The REPORT FORM command also allows a NOEJECT keyword, which Visual FoxPro no longer supports but was used in older DOS versions of FoxPro and FoxBASE+. This keyword does not perform any function but does not trigger an error.
[FILE] FileName2 [[ADDITIVE] ASCII]	Specifies the name of a text file to send the report to. The default file name extension for file created is .txt. When you omit the ASCII keyword or use Visual FoxPro's object-assisted output mode writes PostScript or other printer codes to the text file along with the content of your report. To create an ASCII text file from the report definition file, SET REPORTBEHAVIOR 80 and include the ASCII keyword. Note When you include the ASCII keyword, you can process a report on a computer that has no printer driver setups installed. Without the ASCII keyword, a REPORT FORM command issued on a computer that has no printer driver setups installed generates an error. An ASCII file contains only text. If the report is a character-based layout definition created in FoxPro for MS-DOS, dashes, and plus signs may be included to represent lines and shapes. Otherwise, any font or color settings, graphics, lines, rectangles, or rounded rectangles in the report definition file do not appear in the ASCII text file. You can specify the number of characters to place on each line and the number of lines to place on each page by using the _ASCIICOLS and _ASCIIROWS system variables. The default values for these system variables correspond to a standard portrait page. For more information, see _ASCIICOLS System Variable and _ASCIIROWS System Variable. To append new content to an ASCII file instead of overwriting it, precede the ASCII keyword with the ADDITIVE keyword. The ADDITIVE and ASCII keywords must be specified in the order shown.

[PRINTER [PROMPT] [NOPAGEEJECT] [NOEJECT]]

Sends the report to the printer.

To display the Print dialog box before printing starts, include the PROMPT keyword. In object-assisted mode, the options enabled in the Print dialog box are affected by the ReportListener.CommandClauses.PrintPageCurrent member value.

To specify that Visual FoxPro does not force a sheet eject at the end of a report and leaves the print job open, include the NOPAGEEJECT keyword. The next report printed is added to the open print job.

You must make sure that the last report run does not have a NOPAGEEJECT clause so the print job can be closed.

NOPAGEEJECT is valid only during program execution. It is disregarded when issued in the Command window. Changing between page orientations, such as landscape to portrait, between reports is not supported.

You can chain multiple reports using NOPAGEEJECT and have page numbers continue from one report to the next. This is a useful technique for tasks such as faxing reports.

The REPORT FORM command also allows a NOEJECT keyword, which Visual FoxPro no longer supports but was used in older DOS versions of FoxPro and FoxBASE+. This keyword does not perform any function but does not trigger an error.

[FILE] FileName2 [[ADDITIVE] ASCII]

Specifies the name of a text file to send the report to. The default file name extension for file created is .txt.

When you omit the ASCII keyword or use Visual FoxPro's object-assisted output mode writes PostScript or other printer codes to the text file along with the content of your report. To create an ASCII text file from the report definition file, SET REPORTBEHAVIOR 80 and include the ASCII keyword.

Note

When you include the ASCII keyword, you can process a report on a computer that has no printer driver setups installed. Without the ASCII keyword, a REPORT FORM command issued on a computer that has no printer driver setups installed generates an error.

An ASCII file contains only text. If the report is a character-based layout definition created in FoxPro for MS-DOS, dashes, and plus signs may be included to represent lines and shapes. Otherwise, any font or color settings, graphics, lines, rectangles, or rounded rectangles in the report definition file do not appear in the ASCII text file. You can specify the number of characters to place on each line and the number of lines to place on each page by using the _ASCIICOLS and _ASCIIROWS system variables. The default values for these system variables correspond to a standard portrait page. For more information, see _ASCIICOLS System Variable and _ASCIIROWS System Variable.

To append new content to an ASCII file instead of overwriting it, precede the ASCII keyword with the ADDITIVE keyword. The ADDITIVE and ASCII keywords must be specified in the order shown.

[PREVIEW [ PreviewDestination] [NOWAIT][WINDOW WindowName]]
Displays the report in preview window instead of printing the report. By default, the preview window is modal but provides access to the Print Preview toolbar. The NOWAIT keyword specifies that Visual FoxPro does not wait at run time for the preview window to close before continuing program execution.

Tip

Character-based reports and labels created in FoxPro MS-DOS have a special character-based preview window. This mechanism is not affected by SET REPORTBEHAVIOR and does not support the OBJECT clause or WINDOW-related clauses.

If you include WINDOW <WindowName>, the preview window assumes the characteristics of the window, such as title, size, and so on, you specify with WindowName. WindowName can be the name property of a form object, or it can be a variable referencing a window created with DEFINE WINDOW. For more information, see DEFINE WINDOW Command.

The following table describes possible values for PreviewDestination. You can use the WINDOW clause alone or in combination with either PreviewDestination.

PreviewDestination	Description
[IN WINDOW WindowName]	Specifies a window for previewing a report. If you include IN WINDOW <WindowName>, the report is previewed in the window you specify with WindowName.
IN SCREEN	Specifies that the preview displays in the main Visual FoxPro window and cannot be moved outside it.

[IN WINDOW WindowName]

Specifies a window for previewing a report.

If you include IN WINDOW <WindowName>, the report is previewed in the window you specify with WindowName.

IN SCREEN

Specifies that the preview displays in the main Visual FoxPro window and cannot be moved outside it.

Remarks

When you use Visual FoxPro's object-assisted output mode, all the clauses of the REPORT FORM command are available to your ReportListener in its CommandClauses member object, with the exception of record selection clauses (scope, FOR, and WHILE). You can use the CommandClauses.RecordTotal attribute for information about the scope of the report run, or assign these values to your ReportListener object before running your report. The CommandClauses Property topic gives you more information about how each clause is represented in the CommandClauses member object.

Examples

Example 1

The following example shows how to run a batch report print job with two reports. Visual FoxPro runs through the set of reports twice to obtain a total page count, which is stored in the _PAGETOTAL system variable for enabling Page X of Y expressions in the report layouts.

Note

You can ensure that the report runs through twice by including _PAGETOTAL in your report expressions. If you do not need _PAGETOTAL but would like the two passes to run for other calculations, you can use object-assisted output mode and set the ReportListener TwoPassProcess property to .T.. For more information, see TwoPassProcess Property.

NORESET specifies that page numbers continue printing with the next report. NOPAGEEJECT specifies that the first page of the second report continue printing on the reverse side of the last page of the first report.

REPORT FORM myReport1.frx TO PRINTER NOPAGEEJECT
REPORT FORM myReport2.frx TO PRINTER NORESET
MESSAGEBOX("You printed " + ;
   TRANSFORM(_PAGETOTAL)+" pages.")

Example 2

The following example shows how you can view a preview before sending the report to a printer.

REPORT FORM myReport1.frx TO PRINTER PROMPT NODIALOG PREVIEW

To make the preview window modeless, the following code includes the NOWAIT keyword:

REPORT FORM myReport1.frx PREVIEW NOWAIT

To preview the results in a specific window, the following code includes the WINDOW clause to specify a window named MyWindow that you previously created with the DEFINE WINDOW command:

REPORT FORM myReport1.frx PREVIEW WINDOW MyWindow

Example 3

The following example shows how to send a report to an ASCII file. The _ASCIIROWS and _ASCIICOLS system variables define the number of lines and characters per line on the ASCII page. The REPORT FORM command prints a report named MyReport.frx to an ASCII file name MyFile.txt.

SET REPORTBEHAVIOR 80
_ASCIIROWS = nLines
_ASCIICOLS = nChars
REPORT FORM MyReport.frx TO FILE MyFile.txt ASCII

REPORT FORM Command

Parameters

Remarks

Examples

Example 1

Example 2

Example 3

See Also

Reference

Other Resources

Additional resources