| Navigation: Language Reference > 7 - Reports > Report Structures >====== REPORT (declare a report structure) ====== |    |
| label | REPORT([jobname]), | AT( ) [, FONT( )] [, PRE( )] [, LANDSCAPE] [, PREVIEW] [, PAPER] |
| [,COLOR( )] | [ | THOUS | ] | ||
| MM | |||||
| POINTS |
| [FORM | ||
| controls | ||
| END ] | ||
| [HEADER | ||
| controls | ||
| END ] | ||
| label | DETAIL | |
| controls | ||
| END | ||
| label | [BREAK( ) | |
| group break structures | ||
| END ] | ||
| [FOOTER | ||
| controls | ||
| END ] | ||
| END |
| REPORT | Declares the beginning of a report data structure. |
| label | The name by which the REPORT structure is addressed in executable code. |
| jobname | Names the print job for the Windows Print Manager (PROP:Text). If omitted, the print job name will be “JOB_CWDEFAULT”. |
| AT | Specifies the size and location of the area for printing report detail, relative to the top left corner of the page (PROP:AT). |
| FONT | Specifies the default font for all controls in this report (PROP:FONT). If omitted, the printer's default font is used. |
| PRE | Specifies the label prefix for the report or structure. |
| LANDSCAPE | Specifies printing the report in landscape mode (PROP:LANDSCAPE). If omitted, printing defaults to portrait mode. |
| PREVIEW | Specifies report output to Windows metafiles; one file per report page (PROP:PREVIEW). |
| PAPER | Specifies the paper size for the report output. If omitted, the default printer's paper size is used. |
| COLOR | Specifies a background color for the REPORT and default background colors for the bands in the REPORT (PROP:COLOR). |
| THOUS | Specifies thousandths of an inch as the measurement unit used for all attributes which use coordinates (PROP:THOUS). |
| MM | Specifies millimeters as the measurement unit used for all attributes which use coordinates (PROP:MM). |
| POINTS | Specifies points as the measurement unit used for all attributes which use coordinates (PROP:POINTS). There are 72 points per inch, vertically and horizontally. |
| FORM | Page layout structure defining pre-printed items on every page. |
| controls | Report output controls. |
| HEADER | Page header structure, printed at the start of each page. |
| DETAIL | Report detail structure. |
| BREAK | A group break structure, defining the variable which causes a group break to occur when its value changes. |
| group break structures | Group break HEADER, FOOTER, and DETAIL structures, and/or other nested BREAK structures. |
| FOOTER | Page footer structure, printed at the end of each page. |
The REPORT statement declares the beginning of a report data structure. A REPORT structure must terminate with a period or END statement. Within the REPORT, the FORM, HEADER, DETAIL, FOOTER, and BREAK structures are the components that format the output of the report. A REPORT must be explicitly opened with the OPEN statement.
A REPORT with the PREVIEW attribute sends the report output to Windows metafiles containing one report page per file. The PREVIEW attribute names a QUEUE to receive the names of the metafiles. You can then create a window to display the report in an IMAGE control, using the QUEUE field contents (the file names) to set the IMAGE control's {PROP:Text} property. This allows the end user to view the report before printing.
The REPORT's AT attribute defines the area of each page devoted to printing DETAIL structures. This includes any HEADERs and FOOTERs that are contained within a BREAK structure (group headers and footers).
Only DETAIL structures can (and must) be printed with the PRINT statement. All other report structures (HEADER, FOOTER, and FORM) automatically print at the appropriate place in the report.
The FORM structure prints on every page except pages containing DETAIL structures with the ALONE attribute. Its format is determined once at the beginning of the report. This makes it the logical place to design a pre-printed form template, which is filled in by the subsequent HEADER, DETAIL, and FOOTER structures. The page HEADER and FOOTER structures are not within a BREAK structure. They automatically print whenever a page break occurs.
The BREAK structure defines a group break. It may contain its own HEADER, FOOTER, and DETAIL structures, and/or other nested BREAK structures. It may also contain multiple DETAIL structures. The HEADER and FOOTER structures that are within a BREAK structure are the group header and footer. They are automatically printed when the value in a specified group break variable changes.
A REPORT data structure never defaults as the current target for runtime property assignment the way the most recently opened WINDOW or APPLICATION structure does. Therefore, the REPORT label must be explicitly named as the target, or the SETTARGET statement must be used to make the REPORT the current target, before using runtime property assignment to a REPORT control. Since the graphics commands draw graphics only to the current target, the SETTARGET statement must be used to make the REPORT the current target before using the graphics procedures on a REPORT.
Page-based Printing
Clarion reports use a page-based printing paradigm instead of the line-based paradigm used by some older report generators. Instead of printing each line as its values are generated, nothing is sent to the printer until an entire page is ready to print. This means that the “print engine” in the Clarion runtime library can do a lot of work for you, based on the attributes you specify in the REPORT structure.
Some of the things that the “print engine” in the Clarion runtime library does for you are:
·Prints “pre-printed” forms on each page, that are then filled in by the data
·Calculates totals (count, sum, average, minimum, maximum)
·Automatically handles page breaks, including page headers and footers
·Automatically handles group breaks, including group headers and footers
·Provides complete widow/orphan control.
This automatic functionality makes the executable code required to print a complex report very small, making your programming job easier. Since the “print engine” is page-based, the concepts of headers and footers lose their context indicating both page positioning and print sequence, and only retain their meaning of print sequence. Headers are printed at the beginning of a print sequence, and footers are printed at the end–their actual positioning on the page is irrelevant. For example, you could position the page footer, containing page totals, to print at the top of the page.
See Also: PROP:AutoPaper