Larry Teames on Reports

by Larry Teames

Published 1999-04-05    Printer-friendly version

Back in the old days when men were men and computers were massive mainframes requiring entire floors of buildings to house all the different pieces of hardware that were connected to them, there were also huge, fast printers.

In many cases, these printers cranked out a thousand lines (about 20 pages) per minute or more, for hours on end. Back then, you couldn't just pop up a window with a page image on it, and navigate to the specific page you wanted to see, so we printed and printed and printed because that was the only way we had of getting the information we needed out of the computer. And almost without exception, what goes into a computer eventually needs to come out in hardcopy form.

These days, a PC with perhaps 10 to 20 times the power of those old computers takes up about 2 square feet of desktop or floor space, and probably has a printer attached that prints cleaner and crisper than any printer the "old guys" even dreamed of. Most printers for PCs are not as fast as those old line printers, but they seldom need to be, since we can usually see information of interest displayed on the PC monitor if we choose.

But one thing about printing reports hasn't changed:

If it's worth putting into a computer, someone, at some time, will need to get it out of the computer, and in a format that conveys the data in the most pleasing and informative way.

In other words, although we've probably diminished the need to actually produce a hardcopy of our reports in many cases (today we can view them on our monitors instead), we still need to see that information in a well designed format.

And that brings me to the reason for this column: How to get the most out of reporting in Clarion for Windows.

First Things First

Reporting in most Windows based programming languages is generally handled by a report writer add-on that is used to both design and run reports. Clarion for Windows has the Clarion Report Writer add-on. And it's a fine product capable of creating some nice reports.

But, CW also has a very powerful built-in Report Formatter for designing your report structures, and an internal Report Engine which generates reports from within your CW applications at runtime. Because the report is being generated from within your application, you have considerably more control over how it operates, even to the extent of making changes at runtime.

The CW Report Engine interprets the report structure, at runtime, and automatically prints much of the report for you.

The good news is that it handles things like page overflow, page numbering, and control breaks automatically.

The bad news is that it handles things like page overflow, page numbering, and control breaks automatically. (More on this dichotomy later in this series)

Strike Up The Band

The Clarion for Windows Report Engine prints reports using "bands". A band is a collection of controls that print together at the same time, either automatically, or when asked to do so from code you have written.

There are 7 band types available for use in creating Clarion Reports:

1. Page Header Band
2. Break Group Band
3. Group Header Band
4. Detail Band
5. Group Footer Band
6. Page Footer Band
7. Page Form Band

All bands except Detail Bands are typically printed automatically by the Report Engine.

Page Header Band

Prints automatically once per page before any other bands print on the page (although the Page Form is placed on the page prior to the page header printing). There can be only one Page Header Band defined for each Report. Prints in the Page Header Area.

Break Group Band

Does not contain controls that actually print, but rather defines the variable or file field that is used to determine when a control break occurs. There can be multiple Break Group Bands defined on a Report. To specify multiple levels of control breaks, you populate multiple Break Group bands, with the highest level of break first, followed by the next lower level of break, and so on, through the last break level you need.

Group Header Band

Prints automatically before any Detail bands for the same Break Group print. Only one Group Header Band may be defined for each Break Group defined. Prints in the Detail Area.

Detail Band

There may be as many Detail Bands defined in a Report as needed to print the various records and/or sets of information you require for your report. Prints in the Detail Area.

Group Footer Band

Prints automatically after the last Detail band for the same Break Group prints. Only one Group Footer Band may be defined for each Break Group defined. Prints in the Detail Area.

Page Footer Band

Prints automatically on each page. Generally, this band is generated immediately after printing the last Detail or Group related band that will fit in the current page's Detail area (more on exceptions to this later). Prints in the Page Footer Area.

Page Form Band

This band is generated only once each time the report is run. This occurs automatically and immediately before the first band of any other type is printed. Although this band is generally not needed or used in most reports, it can be used to produce "form" layouts where lots of lines and boxes are used to represent a preprinted form, and/or for printing watermark images on each page of the report. The Page Form Band Prints in the Page Form Area of each page of the report.

Figure 1. Report Formatter band view (click on image for a full-size version).

The AREAs Of A Report

As noted above, each of the 7 band types print in only one Area of a report.

The 4 Areas of a Report structure are:

1. Page Header Area
2. Detail Area
3. Page Footer Area
4. Page Form Area

Areas are a way of defining where on the report each band is limited to printing.

Page Header Area

This is where the Page Header Band prints. This area can be located anywhere on the printed page, and can extend from top of page through bottom of page, although it is typically (by default) placed above the Detail Area. This area actually defines the width, height, and location of the Page Header band on the report.

Detail Area

This is where all bands except the Page Header, Page Footer, and Page Form print. In other words, all Detail bands, Group Headers, and Group Footers print in this area. As each of these band types print, they fill the Detail Area from top to bottom. When there is no longer enough space remaining in the Detail Area to accommodate the next Detail or Break band to be printed, page overflow occurs, causing the Page Footer to print, followed by an eject to the next page, and the printing of the Page Form and Page Header bands.

Page Footer Area

This is where the Page Footer Band prints. This area can be located anywhere on the printed page, and can extend from top of page through bottom of page, although it is typically (by default) placed below the Detail Area. This area actually defines the width, height, and location of the Page Footer band on the report.

Page Form Area

This area is generated only once per report (before any other band prints on the report), but prints on every page of the report. It typically extends from the top of page through the bottom of page. This area/band prints behind all other bands of the report and defines the width, height, and location of the Page Form band on the report.

You can use the Report Formatter's Page Layout View menu option to alter any of these Areas. When you alter the size and/or location of the Page Header Area, Page Footer Area, or Page Form Area, you are also modifying the actual size and location of the associated band for that area.

Figure 2. Report Formatter layout view (click on image for a full-size version).

However, when you modify the size and/or location of the Detail Area, you are actually changing the location and size of the main body of the report where all bands print except the Page Header, Page Footer, and Page Form bands print. This area corresponds to the Formatter's menu option Edit|Report Properties|Position Tab.

In the examples above, I have set the background colors of the various areas to make them more identifiable. The CYAN area is the Page Header area, the GREEN area is the Page Footer area. I have left the Detail Area with no background color so that you can see the Page Form area, which I have colored GREY.

Now take a quick look at the source for the Report structure for the example report layout so far. You can do this by pressing the "..." button to the right of the REPORT button on the Procedure Properties dialog.

Going directly to the source code for the report structure allows you to see exactly what the formatter has generated, and also allows you to make manual modifications, if desired.

Listing 1. The report structure.

       
        Report REPORT,AT(500,1500,7500,6563),PAPER(PAPER:USER,8500,8500), |
    PRE(RPT),FONT('Arial',10,,FONT:regular,CHARSET:ANSI), |
         THOUS
       HEADER,AT(500,500,7500,1000),COLOR(0FFFF80H)
         STRING('This is the Page Header Band '),AT(1427,167), |
       USE(?String1),TRN,CENTER,FONT(,20,,FONT:bold,CHARSET:ANSI), |
           #ORIG(?String1)
       END
EndOfReportBreak BREAK(EndOfReport)
         HEADER,AT(0,0)
         END
Detail   DETAIL
         END
         FOOTER,AT(0,0)
         END
       END
       FOOTER,AT(500,8073,7500,250),COLOR(0FF80H)
         STRING('This is the Page Footer Band'),AT(1990,-10), |
       USE(?String2),TRN,CENTER,FONT(,16,,,CHARSET:ANSI), |
           #ORIG(?String2)
       END
       FORM,AT(500,1490,7500,6583),COLOR(0EAEAEAH)
         STRING('This is the Page Form Band'),AT(313,21,6573,6563), |
       USE(?String3),TRN,FONT(,28,COLOR:Silver,FONT:bold,CHARSET:ANSI), |
           ANGLE(600),#ORIG(?String3)
       END
     END

I use this approach quite often to create things like duplicate bands or groups of controls, to duplicate the X/Y positions and/or size of some controls (using copy and paste) to other controls, and other modifications that are simply not possible or too cumbersome from the Report Formatter window.

For example, have you ever placed a BOX control on a report only to have it appear as an incredibly small spec that defies selection with the mouse cursor? Simply go to the source for the structure and change the width and height of the control to a value that makes the control large enough to get a mouse cursor on. What could be easier?

Hopefully, as this series of articles progresses, you'll begin to feel more "in control" while creating reports, and also learn some neat tricks that will make your report designing efforts less frustrating.

Next month: Exploring the Report Formatter

---

Larry Teames is an independent software developer, and one of the four founding members of Team TopSpeed. He is also president of Creative PC Solutions, Inc. which markets the popular Clarion 3rd party product Creative Reporting Tools.

Printer-friendly version

Copyright © 1999-2009 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942