Lesson 9 - Exploring the Report Procedure

Top  Previous  Next

Clarion has many powerful reporting features and we want to systematically cover all of them. However, you the developer, probably have a particular report you need to produce by yesterday! You may only want to read about those features that will help you produce your particular report right now. Therefore, this chapter provides a "how to" reference for common report effects and functions such as sorting, totaling, page breaking, etc.

This chapter provides a list of report functions and effects that developers are frequently or occasionally asked to provide. It provides a general description of how to create specific report effects, plus a reference to those parts of the Report Designer that are needed to produce the particular effect.

This chapter also suggests a proper sequence for building reports. For example, we discuss the features that define tables and keys and establish page size, orientation, and margins before the features that lay out other parts of the report.

The list of effects is not comprehensive, but instead attempts to launch you quickly into doing a variety of report functions. Once you understand how to create these basic effects, you will be well on your way to creating truly dazzling special effects for your reports.

For systematic coverage of all Report Designer tools and features, see the Report Designer chapter topic.


Common Reporting Tasks


Creating the Report Procedure

If you have not defined a report procedure, you may do so by opening the Application Tree dialog and pressing the INSERT key, or by pressing the New Procedure button. When the Select Procedure Type dialog opens, select Report from the Templates tab.



This creates a report procedure. and opens its Procedure Properties dialog. You should next specify the report’s tables and keys as described immediately below.

Alternatively, you may use the Report Wizard to help you define your report procedure.


Specifying Tables

The first logical step in preparing a report is to specify the tables and keys your report procedure uses. You should do this from the Data / Tables Pad, before starting the Report Designer.



The tables you specify determine which data dictionary columns can appear on your report. You may specify more than one table to report on, that is, a primary table plus secondary related tables and even other unrelated tables. See Adding Relationships.


To specify the tables for your report


Open the Data / Tables Pad. Use this dialog to tell the Application Generator which tables and keys your report procedure uses.


Highlight the <ToDo> item for your report procedure, and press the Add button in the Data / Tables Pad toolbar. This opens the Select a Table dialog.


Select the table you wish to report from.

This sets the table and closes the Select a Table dialog. The <ToDo> item is replaced by the primary table you chose.


Printing From More Than One Table (Adding Secondary Tables)


From the Data / Tables Pad, select the primary table for your report procedure, and press the Add button in the Data / Tables Pad toolbar.

This opens the Select a Table dialog, listing tables related to the primary table. On the other tab, is all the tables in your dictionary.


DOUBLE-CLICK or select the additional table you wish to report.

This sets the table and closes the Select a Table dialog. Repeat these steps for any other tables, related or otherwise. When adding tables, you may also select a secondary table, and then choose from tables related only to the secondary table.

All the columns from the primary table and the secondary tables may be displayed on your report, and they are available for sorting and filtering as well.


Specifying Keys (Sort Order)

The keys (or indices) you specify for your report procedure will determine the sequence in which the report items appear. The keys should also determine break variables and nesting order of any group breaks.

Adding secondary tables (see above) to your procedure also gives you another logical column to break on—that is, the common columns linking the two tables.


The ABC Report Template lets you specify other sort columns in addition to the key you set in the Data / Tables Pad. See Procedure Templates—Report Template in the core help.

To specify the keys for your report:


From the Data / Tables Pad, select the primary table for your report procedure, and press the Change button in the Data / Tables Pad toolbar. This opens the Select Key from dialog.


DOUBLE-CLICK or select the key you want for this report. This sets the key and closes the Select Key from dialog.


Specifying Which Rows to Print (Range Limits & Filters)

You don’t always want to print all the rows in a table. Often, you want to specify a subset of rows to print. You can specify a subset of rows to print by using Range Limits, Filters, or both.

You should use Range Limits whenever possible to specify your row selection, because Range Limits use table keys and are therefore very fast. When Range Limits cannot provide a narrow enough selection criterion, you can add Filters to restrict your report to precisely the rows you need.

To specify Range Limits and Filters, open the Procedure Properties dialog for your report, then press the Report Properties button.


Specifying Paper Size and Orientation

Paper size and text-to-paper orientation should be carefully thought out and established early in the report development process. Changing these settings after the report columns, headings, etc. have been laid out usually results in redoing much of the layout work.

To set the paper size and orientation, open the Properties Pad in the Report Designer. Choose Report Designer  Properties, then select and edit the Paper Type property.

Measurement Unit

To change the page measurement unit, edit the Units property in the Properties Pad. Select dialog units, thousandths of inches, millimeters, or points from the Units drop-down list.

Dialog units are defined as one-quarter the average character width by one-eighth the average quality height. The size of a dialog unit depends on the size of the default font for the report. This measurement is based on the font specified in the FONT attribute of the report or on the printer’s default font.


Specifying Report Margins

Margins for the various report sections (FORMs, page HEADERs, page FOOTERs, and the detail print area) are all set independently of each other, therefore, there is no one margin setting that applies to the entire report. You may specify these margins visually with the Report Designer’s Page Layout View. Please note that the boundaries of each of these structures may overlap.

To use the Page Layout View effectively, you should maximize the window so you can see as much of the report at one time as possible. Then use the TAB key to select the report section to reposition (the Report Designer displays the selected section in the status bar at the bottom of the window). Finally, set the position of the selected section by clicking and dragging its interior, or position one or two edges of the selected section by clicking and dragging one of its handles.

You may also specify the margins of the FORM, page HEADER, page FOOTER, and detail print area on the Position tab of the respective Form Properties, Page/Group Header Properties, Page/Group Footer Properties, and Report Properties dialogs.


The Detail Print Area

The detail print area is defined by the REPORT structure’s AT attribute. The four rules you should understand and remember about the detail print area are:


Every DETAIL, group HEADER, and group FOOTER is printed within the boundaries of the detail print area.


The boundaries of the detail print area may be set with the Report Designer’s Page Layout View or with the Position (AT) properties of the Report’s Properties Pad dialog.


Each item within the detail print area is printed relative to the previous item printed.


The relative position of items printed within the detail print area may be set with the Position tab of the item’s Properties dialog, or by dragging the item’s handles in Band View.


Positioning and Alignment


The AT Attribute

Select the Position properties in the Report’s Properties Pad to set the AT attribute for various report structures. The AT attribute on print structures performs two different functions, depending upon the structure on which it is placed.

When placed on a FORM, page HEADER, or page FOOTER, the AT attribute defines the position and size of the structure. The position specified by the x and y parameters is relative to the top left corner of the page.

When placed on a DETAIL, a BREAK, a group HEADER, or group FOOTER, the structure is printed relative to the previous item printed, according to the following rules (unless the ABSOLUTE attribute is present):


The width and height parameters of the AT attribute specify the minimum size of the structure.


The structure is actually printed at the next available position within the detail print area.


The position specified by the x and y parameters of the structure’s AT attribute is an offset from the next available print position within the detail print area.


The first item is printed at the top left corner of the detail print area (at the offset specified by its AT attribute).


Next and subsequent items are printed relative to the ending position of the previous item:


If there is room to print the next item beside the previous item, it is printed there. If not, it is printed below the previous item.


Precise Positioning and Alignment

There are four major tools to help you precisely align your report data: Grid Snap, alignment tools, the Position properties of the respective properties dialogs, and constrained dragging. Grid Snap is discussed in Report Designer— Menus. The alignment tools are discussed above in Report Designer— Toolboxes.


For precise positioning, edit the Position properties of the respective properties pad. When you position a structure on screen, the smallest unit you can move it is usually 1/96 inch. However, the Position properties lets you specify position by thousandths of inches.


Constrained Dragging

Press and hold the SHIFT key while dragging a control to limit the control’s movement to a single axis. That is, SHIFT + DRAG moves a control either horizontally or vertically, but not both.


Skipping Blank Lines

Use the SKIP attribute on a STRING control to suppress printing an empty string. That is, an empty STRING with SKIP attribute on a line by itself takes up no vertical space on the page.

For labels or other reports that may have an empty STRING on the same line as non-empty STRINGS, you can populate a series of local STRING variables, such as AddressColumn1 and AddressColumn2, on your report rather than the optional database columns. Then embed source code such as:


 IF MBR:Address2                  !If 2nd address line not empty

   AddressColumn1 = MBR:Address2  !assign it to the report column

   AddressColumn2 = CLIP(MBR:City)&', '&MBR:State&' '&MBR:Zip

 ELSE                             !If 2nd address line is empty

   AddressColumn1 = CLIP(MBR:City)&', '&MBR:State&' '&MBR:Zip

   AddressColumn2 = ''            !skip it



Alternatively, you can populate a TEXT control on your report whose USE variable is a STRING that is long enough to contain the entire series of optional and required database columns. Then embed source code such as:


TextColumn = CLIP(FirstName)&' '&MBR:LastName&'<13,10>' !name + return

TextColumn = CLIP(TextColumn)&MBR:Address1&'<13,10>'    !address + return

IF MBR:Address2                                         !if address2 exists

 TextColumn = CLIP(TextColumn)&MBR:Address2 &'<13,10>' !address2 + return


TextColumn = CLIP(TextColumn)&CLIP(MBR:City)&', '&MBR:State&' '&MBR:Zip



Handling Different Size Memos

Use the RESIZE attribute on a TEXT control to allow the control (and the report band) to expand to accommodate all of the text. That is, with the RESIZE attribute, you need not make the report band or the TEXT control as large as the largest data item to be printed. Make the controls as small as the smallest item and the report engine expands the controls for larger items.


Specifying a "Pre-printed" Form

In the Report Designer’s Report Form Band, place text or graphic controls in the form band. This specifies constant text or graphics which prints on every page. This underlying "form" prints independently of and "underneath" all other items on the report.

See Form in the Report Designer chapter.


Specifying Page Headers and Footers

In the Report Designer’s Band View, place text or graphic controls in the page header band or the page footer band. Use the Bands menu to add bands as required.

Page headers are composed prior to details and breaks. Page footers are composed after details and breaks. Both HEADERs and FOOTERs may be located anywhere on the page.

The data printed in the page headers and footers may be constant or variable. Page headers and footers are typically used to present report titles, fixed column headings, page numbers, print dates, company logos, etc.

See Report Designer—Page Header and Page Footer.


Specifying Column Headers and Report Titles

Static strings are good for printing column headings, report titles, and any other text that doesn’t change. You will usually want to place your titles and headings in the page header or the page form. If you need to print titles or headings that change, see Specifying Columns to Print.


See also Controls and Their Properties—String Properties.


To place a static string control in your report


Select the STRING control from the Controls Toolbox, and DRAG AND DROP in the band that displays the title (usually the page header).

The Report Designer places a STRING control in the report structure. The center of the crosshair positions the upper left corner of the string.


RIGHT-CLICK the control then choose Properties from the popup menu.


In the Properties Pad, enter the text to display in the Text property.

No quotation marks are needed.


Modify the Font property to specify the typeface, size, color, and style of the text.


Alternatively you may specify the text and it’s font with the Property toolbox. Choose Option Show Propertybox.


Specify the text justification with the Justification property drop-down list.


For special effects


Set TextColor and Angle properties.


Specifying Columns to Print (variable text)

Variable string controls are the basic unit for printing variable data in the report. Variable strings are also used for displaying totals and other calculated columns.

By using the USE variable, the report procedure accesses the memory variable or data dictionary column you want to print. The Report Designer formats the data according to the picture token you specify.

To place a variable string control in your report


Use the Data / Tables Pad, or highlight a column in the Populate Column toolbox (choose Report Designer Populate Column).

Using either method lets you place a data dictionary column only, without ever leaving the Report Designer. Using the Populate Column option lets you select from data dictionary columns and memory variables using the Select Columns dialog.


CLICK in the band that will contain the variable string (usually the detail, group header or group footer).

The Report Designer places a STRING control in the REPORT data structure with a variable as the string’s Use property, and sets the following string properties: the VariableString property is TRUE, a Text property picture token and a Justification value is provided based on the data dictionary information for the selected column or variable.

Alternatively, you can place a string control, then set the string properties manually to accomplish the same result: set the VariableString property to TRUE, type the variable name in the Use property, type a picture token in the Text property, and select a Justification value from the drop-down list.


Edit the Font property to specify the typeface, size, color, and style of the text.

Alternatively you may specify the text and it’s font with the Properties Toolbar. From the IDE Menu, choose Tools  Options REPORT Structure Designer Show Properties Toolbar.


For special effects:


In the Properties Pad, optionally set the TextColor and Angle properties.


Optionally, select a total type from the TotalType property drop-down list to create sums, averages, tallies (counts), page numbers, etc.


Specifying Group Breaks

In order to have meaningful groups or subtotals in your report, the report rows must be sorted properly.

To create a group break


In the Report Designer IDE Menu, choose Bands Surrounding Break.


Move the cursor over the detail band, then, when the cursor changes to a crosshair, CLICK in the DETAIL band.

This opens the Break Properties dialog.


In the Variable entry, enter a break variable.

At runtime, when the variable’s value changes, a new group begins.


In the Label entry, enter a valid Clarion label to use as a label for the BREAK structure.

This label may be referenced by the RESET and TALLY attributes.


In the Use entry, enter a field equate label to reference the BREAK in your source code.


Press the OK button.

This inserts the group BREAK. When the break variable changes, the report composes the group FOOTER and the next group HEADER defined for the break.


Specifying Group Headers and Footers

The print engine composes the group HEADER before the group DETAIL. The group HEADER is a good place to identify the group, for example, with a static string saying "Customer:" followed by a variable string displaying the customer name column.

The print engine composes the group FOOTER after the group DETAIL. The group FOOTER is a good place to summarize the group, for example, with a static string saying "Total:" followed by a variable string displaying a sum. See Creating Totals. See also Report Designer—Group Breaks—Group Headers and Group Footers.


First, define a group break as described above.


Choose Bands Group Header from the Report Designer IDE menu to define a group HEADER for the BREAK.


Move the cursor over the break band; when the cursor changes to a crosshair, CLICK in the BREAK caption bar.

This opens the Page/Group Header Properties dialog. Specify a field equate label and any special page breaking behavior.

4. Press the OK button.

This inserts the group HEADER band. You may place controls here just as in any other report band. Group footers are added similarly, using Bands