Clarion Community Help

Before learning how to create a report using the Report Designer, it's important to understand how Clarion executes a report–in other words, the division of labor between the print engine and your source code, and the order in which Clarion processes all the sections of your report. Each section of the report is a data structure, and each in turn is contained in the REPORT structure.

Smart Processing

The REPORT data structure contains all the information necessary for formatting and printing each page. It automatically handles page overflow management, including widow and orphan control. This frees you from worrying about the “mechanics.”

This means that the Clarion executable code to print a report is simple and clean. The following example shows how a total of six lines of executable code can access the file and print a fully-formatted listing of all Customers. Since the Report Designer writes the entire REPORT data structure, this is all the code the programmer has to write:

CODE

OPEN(CustReport)           !Open report for processing

SET(Cus:NameKey)           !Top of file, alpha order

LOOP                       !Process the entire file

NEXT(CustomerFile)        !one record at a time

 IF ERRORCODE() THEN BREAK.  !Check for errors

PRINT(Rpt:Detail)         !PRINT tells the REPORT structure to do the work.

END

Of course, if you're using the Application Generator, you don't even have to write that much! In the example above, the PRINT statement prints a DETAIL structure for each record in the file retrieved with the NEXT statement inside the LOOP .

The REPORT data structure contains the items that belong on the page, plus the attributes that determine how they appear there. Since you visually design these in the Report Designer, the code example above really is all you have to do to print the report.

The PRINT statement automatically initiates the page overflow handling. This means that when the LOOP goes through enough records to fill up the page, it automatically generates any other structures on the page–the FOOTER, for example. Then it sends the entire page to the print spooler.

Order

The parts are wholly contained and managed within the REPORT data structure. The parts of the data structure are the FORM, PAGE, HEADER, DETAIL, and page FOOTER; their functions are fully described below. The REPORT data structure may also contain group BREAK structures. Each group BREAK structure can contain its own group HEADER, DETAIL, and FOOTER.

Normally, you want to design reports with only one DETAIL. When you generate reports using the Application Generator, they will probably have only one. This usually is the one inside the group BREAK structure. The Report Designer adds a DETAIL for each BREAK, for flexibility. You can delete the ones not used.

Once you know the order in which the parts generate at print time, you can understand how to use them better. For the following example, assume a report utilizing all the parts listed above, containing one group structure, with a DETAIL inside. Immediately upon the PRINT command:

1.The print engine composes the FORM, but does not send it to the print spooler yet. The FORM generates only once; the application repeats the FORM and does not recompose it for additional pages.

2.The print engine composes the page HEADER.

3.The print engine processes the group HEADER.

4.The application generates the DETAIL section (within the BREAK) for as many times as will fill the first page, continuously checking for group BREAKs.

If a BREAK occurs on the page:

5.The print engine composes the group FOOTER for the first group.

6.The print engine composes the group HEADER for the next group.

7.The application generates the DETAIL section for the next group of records, continuously checking for further group BREAKs.

At the bottom of the page:

8.The print engine checks for widows, increments the page count, and checks the next page for orphans.

9.The print engine composes the page FOOTER.

10.The print engine sends the entire first page to the print spooler.

11.For page two, since the FORM was composed already, it does not get regenerated, though it will print on the page. The application proceeds directly to the page HEADER.

12.The application repeats the procedures above for this and any additional pages.

Flexibility

The page-oriented nature of the Report Designer is the key to its flexibility. The print engine composes each page in its entirety before sending it to the printer. This means you may arrange the parts of the report into any page layout you wish.

You can place the FORM, page HEADER, and page FOOTER structures anywhere on the page, within certain limitations. Their placement does not affect the order that the application generates the parts.

That means you can physically place a page FOOTER above a page HEADER. Since the FOOTER generates only after the report processes all the records on the page, this allows you, for example, to place a page total above the records on the page.

You set the position and size of the DETAIL structure as an offset vs. the last DETAIL printed. The print engine prints each DETAIL from page top to page bottom. If the DETAIL is narrow enough so that more than one fits across the width of the page, they print in order left to right, top to bottom.

Group BREAK structures–group HEADER, group DETAIL and group FOOTER–all print as offsets within the DETAIL area, one after the other.

You can do some fancy footwork in cooperation with the print engine. For example, because the DETAIL structure must be printed with the PRINT statement, you can utilize embedded source to place conditional statements within your executable code, to print one DETAIL upon one condition, and another upon a different condition.

As long as you remember the order in which the application generates each section, which determines the current record and the values of the totals, tallies and other operations on the fields in each structure, you can build in a great deal of flexibility within the REPORT data structure, and let the print engine worry about fitting it all onto the page at runtime.