Larry Teames On Reports

by Larry Teames

Published 1999-05-10    Printer-friendly version

Last month I explained what "areas" and "bands" are in the context of Clarion for Windows reporting. This month I'll begin looking at the Report Formatter available in the Clarion5 IDE.

However, rather than reiterating all the same information already available on this subject in the Clarion5 Help file, I'll try to limit my coverage to tips, tricks, and other tidbits of information that I think may help you complete your reporting tasks faster and with less effort.

For the record...

The Clarion Report Formatter can be very intimidating and frustrating when first used if you don't have a clear understanding of how it can be used. In effect, the report formatter is multiple formatters, each of which is almost identical to the window formatter. All of these formatters are linked together in a single interface. Of course, there are some control types that do not have any practical use in a report, and those types are not available in the formatter.

Tip: Save yourself some grief and forget about using the listbox control that's available in the formatter. It can seldom be made to produce desired results, and TopSpeed has gone on record stating that it will be removed from the formatter sometime in the future anyway.

From a user's perspective, each band is handled independently by it's own (window) formatter. And since they are all accessible at the same time, you not only have the ability to see how the controls align and relate to one another across bands, but can also perform some functions like control alignment against multiple controls in multiple bands in a single operation.

Before I go any further though, there are two very important rules that you should follow when formatting reports:

1. Save your report and application frequently!
2. Save your report and application frequently!

The report formatter does mostly good things, but occasionally it does some not-so-good things. So, save your work frequently by getting completely out of the formatter, and saving the application. I also tend to reboot my machine about every hour or so when doing intensive report formatting and testing.

Tip: I run the Resource Meter that comes with Windows 98 (RSRCMTR.EXE) from my StartUp group, and when the resources get to 40% or so, I always reboot

Rebooting gives Clarion (and your machine) a chance to recover some of the resources that may get locked or lost by the formatter, or other elements of the IDE.

I have created several thousand reports since I started using Clarion, and I simply don't have most of the weird problems that many users report related to using the report formatter. I believe that this frequent saving/rebooting is what makes the difference.

Before you proceed, you should read the following topics in the Clarion5 Help file in their entirety: "How to Use the Report Formatter - An Overview" through "How to Print Labels" (just keep hitting the >> button till you've gone through all the topics).

Doing so will assure that you are familiar with at least the basics of how the formatter is used. Be sure to pay particular attention to the topic "How to Control Page Breaks", since this discussion explains a great deal about how the Report Engine works. Of course, if you have already used the formatter to create numerous reports and feel that you already know the information contained there, you can skip the reading assignment.

Get Ready, Get Set...

What's the best or most correct way to design a report? In my opinion, there is no single best or correct way to design most reports. I'm certain that what works best for me is probably not the best way for everyone. However, in this column I will approach things in my own way, and you can try what I recommend, or not, as you like. The important thing is to try and understand the concepts and ideas that I describe and then use them in a way that complements your own work style.

I expect that most of you have already created several reports, and have experienced some level of frustration in doing so. One of the main reasons for these frustrations is that a great deal of what gets done on your reports is automatic. Although this can be a good thing, it can also be an irritation. I have found that in many of these situations, the only way to get the most from my efforts is to completely bypass the automatic functionality and write code to perform the same functionality and/or extend it to do that extra bit of work that the built-in functionality doesn't offer.

With all that in mind, let's take a look at the report formatter.

Exploring the Report Formatter

Figure 1 shows the main menu of the report formatter (RF):

Figure 1. The report formatter main menu.

On the EDIT menu (see Figure 2) probably the most frequently used selection is Report Properties, since it allows you access to most of the attributes of the report format.

Figure 2. The report formatter Edit menu.

Selecting the Report Properties menu option displays the window shown in Figure 3.

Figure 3. The report properties window showing the General tab.

The contents of the Job Name field will appear as the Job Name of the Windows Print Spooler. In a newly generated report, Job Name will be blank. I'd suggest that you always enter something into this field of every report, so that you (and your customers) can easily identify the report when it's spooled under Windows.

TIP: you can set/change this field at runtime by setting REPORT{PROP:TEXT}='My Report Name'. Do this in the After Opening Report embed, so that the change takes place before any print lines are generated.

Although you can change the Label and Prefix of the report, I always leave them set to their defaults ("REPORT" and "RPT"), since this is about as intuitive as it can get, and if all reports are referred to by the same name and prefix I don't have to remember differences from procedure to procedure.

Generally, I leave UNITS set to thousands of an inch, because this provides the finest resolution (for positioning controls, etc.) that most printer drivers are capable of. If you have a particular report which is best handled with millimeters, as may be the case when a preprinted form is formatted in MMs, then feel free to switch.

Figure 4. The report properties window showing the Extra tab.

Figure 4 shows the Preview field on the Extra tab. As the help file states, LEAVE THIS FIELD BLANK! Failure to do so tends to end with a GPF at runtime.

Figure 5. The report properties window showing the Color tab.

The Color tab (Figure 5) allows you to override the default Text Color and Text Background used on the report. My experience is that you will be better off by leaving these set to the default.

Figure 6. The report properties window showing the Position tab.

The Position tab (Figure 6) provides you with a way to set the position and size of the Detail Area (remember last month's subject?) of your report. Remember, you can also do this interactively by using the Page Layout View menu option (also described last month).

The X and Y positions define how far from the left and top edges of the paper you want the Detail Area positioned. Unless you just enjoy trying to figure out why your report acts so weird on different computers, never set the height or width to default.

Figure 7. The report properties window showing the Paper Size tab.

The Paper Size tab (Figure 6) is where you define the dimensions of the actual piece of paper that your report will print on. In addition to the numerous predefined paper sizes that are available from the drop down list (Letter, Legal, A4, etc.), you can also specify a page size other than those listed by selecting "Other" from the drop down list, and then entering the actual width and height of the paper your report will print on.

You should assure that the printers and printer driver(s) that your customers have will support custom paper sizes before you design a report using a non-standard size. You can do this by viewing the Properties of the printer driver in question, selecting the Paper tab, selecting the Custom paper size, and entering the dimensions of the page you want to use. If the driver does not allow you to perform this operation it will not support the paper size you are setting the report to.

TIP: to perform this test on a printer that you don't have attached to your computer, simply install the driver for that specific printer, then perform the test. When done, you can delete that printer driver.

Note that nearly all laser printers, and compatibles like DeskJets, are designed to use only a few fixed size papers, so defining other sizes will not be possible for these types of printers.

If you do try to use an unsupported paper size with any printer driver, the Clarion Print Engine will simply set the paper size to the default paper specified by the printer driver, and continue on with the report.

Figure 8. The report properties window showing the Actions tab.

The Action tab (Figure 8) has buttons for accessing the file tree, and the embed tree of the report procedure. My personal work habits have never led me to use these buttons since they don't seem to provide benefit over saving the report format, and exiting the formatter to access the file and/or embed tree. I suspect that continual use of either of these buttons during a formatting session would probably contribute to the probability of losing your work, but that's pure conjecture on my part.

The Font button on the Report Properties window allows you to specify the default font to be used when formatting and printing this report. The default font is the font used on all controls where no specific font is indicated. I generally prefer to use a TrueType font like Arial for most of my reporting. The TrueType fonts render better for previewing than do fixed pitch fonts.

The rest of the main menu choices are self explanatory or described well enough in the help file that they don't really need more description by me at this time.

What's coming up ...

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 will provide for download the APP, DCT, and data files used in these examples.

Hopefully as this series proceeds you'll begin to feel less frustrated and more in control when designing your reports.

Till next month, Happy Reporting!

---

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-2008 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