Report, Label

These commands let you generate reports and labels created with the Report and Label designers. They have a multitude of options—some fairly new, others as old as Xbase itself.

Usage

REPORT FORM ReportFileName | ?
       [ Scope ] [ FOR lForExpression ] 
       [ WHILE lWhileExpression ]
       [ RANGE nStartPage [ , nEndPage ] ]
       [ PREVIEW [ [ WINDOW DefiningWindow ] 
          [ IN  WINDOW ContainingWindow ]
          | IN SCREEN ]
         [ NOWAIT ]  
         | TO FILE OutFileName [ ASCII ]
         | TO PRINTER [ PROMPT ] ] 
       [ NOCONSOLE ] [ NOEJECT ]
       [ HEADING cHeadingText ] [ PLAIN ] [ SUMMARY ]
       [ ENVIRONMENT ] [ PDSETUP ]
       [ NOOPTIMIZE ]
       [ NAME ObjectName ]
LABEL [ FORM LabelFileName | FORM ? ]
       [ Scope ] [ FOR lForExpression ] 
       [ WHILE lWhileExpression ]
       [ PREVIEW [ IN SCREEN ] [ NOWAIT ] 
         | TO FILE OutFileName [ ASCII ]
         | TO PRINTER [ PROMPT ] ] 
       [ NOCONSOLE ] 
       [ ENVIRONMENT ] [ PDSETUP ] [ SAMPLE ]
       [ NOOPTIMIZE ]
       [ NAME ObjectName ]

The "FORM" in REPORT FORM and LABEL FORM stands for "format" and, in fact, you can still write it that way. More importantly, the term "format" makes it clear what these commands do—they produce a report or a label based on a specified format.

LABEL has a neat trick. If you just type LABEL without FORM, you're prompted to choose a label file. For both labels and reports, specifying ? does the same thing.

The Scope, FOR and WHILE clauses limit output to the records meeting those conditions. See "Xbase Xplained" for details.

Report and label output can be sent various places. By default, it appears in the active window. You can suppress that output with NOCONSOLE. Specifying PREVIEW puts the output in the Print Preview window. Preview mode is much better in VFP than in FoxPro 2.x, with a dockable toolbar, an assortment of zoom ratios and a NOWAIT clause that lets you put up a report and then continue a program. Starting in VFP 5, you can also define a window for the Preview and give it a custom title and appearance (much as you can for a Browse). Then, you can use the WINDOW clause to put the preview in the custom window.

VFP 6 added even more options. First, the IN WINDOW option lets you confine the preview to a specified window. Second, when you have a top-level form, issuing PREVIEW without specifying a window puts the preview in that window—this is a major improvement over previous versions, which put the preview into the main VFP window, often hidden in a top-level-form-based application. Finally, the IN SCREEN clause is for those rare cases where you're working in a top-level window, but want the preview in the main VFP window. We can't quite imagine that situation, but we're sure it'll help someone, somewhere. The LABEL command doesn't offer the WINDOW clause, but does preview in a top-level window and supports the IN SCREEN clause, even though it's not documented.

The biggest remaining weakness in report previews is that you can only zoom up to 100%. We can think of plenty of situations where we'd like to zoom to 150% or 200% or even 400%—we sure do it in other applications. Also, the ability to specify the exact zoom magnification would be nice, rather than being locked into a few choices. Word's Print Preview features options like "Page Width" and "Text Width" that speed the ability to see everything at the highest magnification.

There are two ways to send report or label output to a file. If you specify TO FILE without the ASCII clause, all the codes for the specified printer go with it. You can then send that file to the printer at your leisure. The ASCII clause, on the other hand, lets you create a file that a human can read, instead of one filled with gobbledygook printer control. The output with ASCII is VFP's best guess of a character-based layout from a graphical one—this option is best for columnar reports without many fonts, sizes or multiple rows of information to line up. Not only that, it's fast—really fast. On the other other hand, the formatting you get with ASCII is pretty basic. Finally, you can send your report to the printer. Add the PROMPT clause to let the user choose a printer; otherwise, FoxPro uses the printer you specified in Page Setup or the Windows default, if you didn't change it. There are several problems with the PROMPT clause in VFP 5—they're documented in the Microsoft Knowledge Base, so we won't repeat them here. The RANGE clause lets you indicate which pages of a report should be produced. It's ignored when you specify PREVIEW, but does affect output to the screen, printer or a file. Very handy for those times when one page of a 30-page report gets jammed in the printer. In VFP 7, the upper limit for RANGE has been raised to 65,534 (yeah, right, like someone's going to read a report that long).NOEJECT and PDSETUP have something in common. They don't do anything with Visual FoxPro reports. Both have their origins in FoxPro for DOS, where they were very handy.

ENVIRONMENT is almost as useless. It applies only to reports converted from older versions of FoxPro, where you didn't have properties like AutoOpenTables available. With the ENVIRONMENT clause, the report's data environment is opened regardless of the setting of AutoOpenTables.

HEADING and PLAIN also date way, way back. HEADING was designed to let you specify a page heading for a report when you run it—it let you send things like "First Quarter 1995" and so forth, putting what you send on the last line of the Page Header band. HEADING still works, but it doesn't pay any attention to what's already on that line, clobbering any text already there. We recommend you avoid it and simply use expressions in your reports. PLAIN eliminates page headings from the report—note that you get no page headings at all, not even on the first page, as Help says.

SUMMARY omits the detail band. All the other bands appear. It's one way to get (surprise) summary information.

The SAMPLE clause of LABEL doesn't do a thing and, in fact, is no longer documented. In FoxPro/DOS, it let you print a test label to see if the labels were properly aligned in the printer. Microsoft doesn't believe anyone uses dot-matrix printers with Windows, so you can't do this. Instead, we recommend you run a test set in a loop with LABEL FORM MyLabel NEXT nHowManyToASheet until the operator is happy with the results.

NOOPTIMIZE slows down your report. See SET OPTIMIZE if you think you might need to use this.

Last, but by no means least, is the NAME clause. Although reports and labels are not objects (in the OOP sense), their data environments are. The NAME clause lets you assign a name to the DataEnvironment of a report or label. You can use that name in method code (which seems like a bad idea to us—use This instead) or from the Command Window or a program; with the NOWAIT clause of PREVIEW, your program can still be running while the preview is displayed. You can also reference the data environment from code running in the entry and exit events for the report's bands. We haven't ever actually used these abilities in an application, but it's nice to know they're there. By the way, if you don't include the NAME clause, you can still reference the data environment by using the report name.

Example

* Put a report preview in a specified window.
DEFINE WINDOW RepPreview FROM 0,0 to 50,100 ;
   title "Employees"
REPORT FORM Employees PREVIEW ;
   WINDOW RepPreview NOWAIT
LABEL FORM Customer TO PRINT
REPORT FORM Employees TO FILE emps.txt ASCII
REPORT FORM SaleHist TO PRINT RANGE 5,7

Since VFP 3, when you printed reports, the Print Spooler dialog displayed "Visual FoxPro Report" while the report was queued to print. Starting in VFP 7, the name of the report or label is passed to the Print Spooler dialog. Now the dialog doesn't give away what language your application was written in, and it also makes it far easier to delete specific reports from the queue when you know their names.