Larry Teames On Reports

by Larry Teames

Published 1999-07-13    Printer-friendly version

Over the next few months, I will be designing a number of reports to illustrate approaches that can be used to handle various reporting issues, both common and uncommon. To make it easier for you to follow and later review what I cover, I have created a small dictionary (BREAKS.DCT), and the TPS files to go with it (LETTERS.TPS, BREAK1.TPS, and BREAK2.TPS). Also the resulting APP file(s) that I create will be available.

This month's APP file is CMEX01.APP.

I will be using Clarion5 (ABC) to build these applications, but in most cases I will use the legacy (non-ABC) embeds when placing source code in the report procedures. Personally, I find that the legacy embeds have better descriptions and finer resolution related to what I want to do and where I want to do it. Also, using this method you can look at the source file for the procedure and locate the ABC embed that correlates to the legacy embed that you just entered. This provides a very nice approach to making the transition from using legacy embeds to using ABC embeds

Summary Reporting

This month I've built a report that allows the user to decide whether they want to print invoices in detail form (all invoices with totals at the customer and report level), or in summary form (totals only).

I like to make a window for selection of report criteria (instead of using the report's progress window) when there are report variations available which might cause the user to run the report multiple times with different options chosen (see the SummaryReportSelect procedure below). I tend to have a menu option call the selection window, then the selection window calls the appropriate report (or the same report with different parameters, as in this case). This allows the user to run the report, then be returned to the selection window where they can change the selection criteria and run the report again, or exit the selection window when no more reports are needed.

The report procedure, SummaryReport, takes a single BYTE parameter (SummaryRequest) which is TRUE when the user selected Summary Report, and FALSE when they did not request the summary form of the report. Note that all the changes to the report are performed in the source code entered into the After Opening Report embed. I'll go over this code in detail later in this column.

Having decided that I wanted a single report to provide both detail and summary formats, I knew that I would need to HIDE all the information in the Detail band when the summary form was requested (when using the built-in breaking and totaling mechanism of the report engine, tallying of values is directly related to the printing process, so you have to continue to print the Detail band to get the totaling o occur). To more easily accomplish this, I placed a GROUP around the controls in the Detail band. This allows me to HIDE all controls in that band with a single statement, by simply hiding that GROUP. Note that I removed the display text of the GROUP, and unchecked the Boxed option so the box around the group doesn't print.

To set up the totaling, I used the Surrounding Break menu choice twice (from the Bands menu item): once to create the break on Name, and again to create the break on EndOfReport (I pressed "..." from the Break dialog, then New, to create the EndOfReport variable).

After creating these break groups, I selected each of these breaks and created a break footer for each. Then I added the controls I wanted to print at total time. For the amount fields, I set both to sum total type, to tally on printing the Detail band.

To facilitate the source code statements I would need, I added USE names to the Detail band (?DetailBand), and the Name break footer (?NameFooter).

The Tricks

This report will not only produce two different formats in terms of content, but will also modify the vertical spacing of the Name footer when the Summary format is requested (so that there is no extra whitespace between summary total lines). Additionally, the name of the report will be changed to identify the specific report format being printed.

All that's left is to enter the source code that will do all the work into the After Opening Report embed, as shown in Listing 1 (the numbers at the end of each line correlate with the legend that follows describing the purpose/effect of the code).

Listing 1.

IF SummaryRequest = True               !(1)
  SETTARGET(Report)                 !(2)
  ?ReportHeading{PROP:TEXT} = 'Example Summary Report'  !(3)       
  ?NameFooter{PROP:YPOS} = 0 - ?BR1:Name:2{PROP:YPOS}   !(4)
  ?NameFooter{PROP:HEIGHT} = ''             !(5)
  ?NameFooter{PROP:MINHEIGHT} = ''          !(6)
  ?DetailGroup{PROP:HIDE} = True            !(7)
  ?DetailBand{PROP:HEIGHT} = 0              !(8)
  ?DetailBand{PROP:MINHEIGHT} = 0           !(9)
  SETTARGET                     !(10)
END

1. Only change the report characteristics if the user selected the Summary format (which is passed to the Report via a procedure parameter).
2. Set the Report as the target of subsequent field equates so that the compiler knows that I am referring to controls on the Report instead of (by default) the active window.
3. Change the text of the report name string.
4. Causes all controls in the Name break footer to be adjusted "up" so that they are printed relative to YPOS zero (by converting the band's YPOS to a negative value equal to the YPOS of one of the topmost controls on the band).
5. Sets the HEIGHT of the band to the default setting (as opposed to setting it to zero, which would not be what I want). This setting causes the band to be only as tall as the sum (YPOS + HEIGHT) of the bottommost control on the band. Here I'm assuring that there is a minimum of vertical space between the lines printed. Note that the detail format generates significant space at the bottom of this band to better define where a break has occurred.
6. I also need to do the same to the minimum height of the band, since it was originally set to a fixed height when the report opened.
7. Next I hide all controls on the Detail band so they don't appear on the report when this band is printed.
8. I also want to set the PROP:HEIGHT of the Detail band to zero so that it causes no vertical movement when printed.
9. I also set the minimum height to assure no surprises at runtime.
10. Finally, I set the "target" back to the default (the currently active progress window).

Now I have a single report procedure that allows the end user to print two different formats of reports.

Obviously, a report with more controls and totals would likely require more source code to accomplish this, but the principals and approaches would remain the same as what I've illustrated here.

Next month, I'll tackle another example of a common reporting issue, so don't miss it!

Download the source code

---

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