User Tools

Site Tools


lesson_9_exploring_the_report_procedure.htm
Navigation:  User's Guide and Tutorials > The Application >====== Lesson 9 - Exploring the Report Procedure ====== Previous pageReturn to chapter overviewNext page

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.

SelectReport.jpg

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.

FSPReport.jpg

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

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

2.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.

3.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)

1.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.

2.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.

TipBox.jpg

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:

1.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.

2.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 &amp; 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 BLTTRIA.jpg Properties, then select and edit the Paper Type property.

PaperType.jpg

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.

ReportPositionProperties.jpg

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.

TipBox.jpg

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)&amp;', '&amp;MBR:State&amp;' '&amp;MBR:Zip

 ELSE                             !If 2nd address line is empty

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

   AddressColumn2 = ''            !skip it

 END

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)&amp;' '&amp;MBR:LastName&amp;'<;13,10>' !name + return

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

IF MBR:Address2                                         !if address2 exists

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

END

TextColumn = CLIP(TextColumn)&amp;CLIP(MBR:City)&amp;', '&amp;MBR:State&amp;' '&amp;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

1.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.

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

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

No quotation marks are needed.

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

TipBox.jpg

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

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

For special effects

6.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

1.Use the Data / Tables Pad, or highlight a column in the Populate Column toolbox (choose Report Designer BLTTRIA.jpg Populate BLTTRIA.jpg 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.

2.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.

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

TipBox.jpg

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

For special effects:

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

5.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

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

2.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.

3.In the Variable entry, enter a break variable.

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

4.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.

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

6.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.

1.First, define a group break as described above.

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

3.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 BLTTRIA.jpg Group Footer from the menu.

Specifying Nested Group Breaks

A nested break is created the same way as the first break. The second break may be nested “within” the first break by placing the second break on the detail inside the first break. Alternatively, the second break may be added “outside” the first break by placing the second break on the first break.

When establishing nested breaks, you should coordinate the nesting order of the breaks with the sort order of the tables being processed. For example, if you have chosen a key composed of the Department, Title, and LastName columns, then you could similarly break on LastName, within Title, within Department.

You can review your key's component columns in the Data Dictionary's Column/Key Definitions dialog.

Adding secondary tables to your procedure also gives you another logical column to break on: that is, the common columns linking the two tables.

Specifying Page Breaking Behavior

Edit the properties of the group HEADERs, the DETAILs, and/or the group FOOTERs. There are several options available. The options are Page Before, Page After, With Next, and With Prior.

Creating Totals and Calculated Columns

See Specifying Columns to Print above.

A total column is simply a variable STRING control with the SUM attribute added. The AVE, CNT, MAX and MIN attributes similarly create averages, counts (tallies), maximum, and minimum columns. These attributes may be added by choosing from the Total type drop-down list in the String Properties dialog.

In addition, you can precisely control the totaling behavior by specifying the RESET attribute from the Reset on drop-down list and by specifying the TALLY attribute from the Tallies list on the Extra tab. Finally, you can get ultimate control by specifying a variable to receive intermediate values for the SUM, AVE, CNT, MAX, and MIN operations with the Using entry. You can perform custom calculations in embedded source using the intermediate variable to get any result you need.

TipBox.jpg

You cannot automatically calculate intermediate group level totals with Clarion's Report Procedure templates and STRINGs. For example, you cannot add together two group level totals to create a third total. This type of calculation requires manual tracking of group breaks.

In general, you place a total column in a page or group FOOTER so it can total the rows from the beginning of the report, from the beginning of the page, or from the beginning of the BREAK group. However, you can also place a total column in a DETAIL structure to provide a running total. A tally (CNT) column in the DETAIL can number the rows as they appear on the report.

To specify a total column

1.Place a variable string control as described in Specifying Columns to Print.

For example, if you want total sales from an order entry system, select the data dictionary column containing the sales value.

2.CLICK on the string control to select the string's Properties Pad dialog.

3.Choose a total type from the TotalType property drop-down list. Choose from Sum, Average, Minimum, Maximum, Count, and Page No.

4.Optionally, use the Reset property drop-down list to reset the total to zero before each page or before each break.

ReportTotalType.jpg

For example, if your report is page-based so you need a total for each page, select Page from the Reset property drop-down list. If you want totals per customer and you have defined a break on customer, select the customer break from the Reset property drop-down list. If you want a grand total, select <;None> from the Reset property drop-down list. See Grand Totals below.

5.Optionally, set the Tally property to specify when the calculation occurs.

By default, the specified calculation (SUM, CNT, MAX, MIN, AVG) occurs each time a report DETAIL is printed. This is true even if the calculated column is not in the DETAIL band and even if the calculated column is not in the lowest level child row of a multi-level table relationship.

In other words, use the Tally property list to limit the occurrence of the calculation to the printing of higher-level breaks. For example, in a report that prints a three level table relationship (Customer>Order>Item), where the column to total resides in the middle level (Order) and the report prints all three levels, select the OrderBreak in the Tally property list to increment the total each time the Order BREAK prints rather than each time the Item DETAIL prints.

TipBox.jpg

Don't choose the same break for both Reset and Tally. If you do, the result is always zero.

6.Optionally, set the Using property entry to specify a variable to receive intermediate values for the SUM, AVE, CNT, MAX, or MIN operation.

In effect, this gives you access to the Report Engine's totaling capabilities. You can use the specified variable within your own custom calculations in embedded source code. Please note the Report Engine only writes to the intermediate variable, it does not read or reuse the variable for subsequent calculations. Therefore, you cannot alter a total generated by the Report Engine; however, you can HIDE the column calculated by the report Engine and replace it with your own custom calculated column.

Sub-totals and Page Totals

Sub-totals are created simply by placing a total column within a page or group footer, and resetting the total to zero at the beginning of each page or group. Use the Reset property drop-down list in the string's Properties Pad dialog to reset the total to zero before each new page or group.

Grand Totals

In effect, grand totals are simply sub-totals based on a break variable that never changes.

To create a grand total for your report, add a group break on a variable that doesn't change throughout the report. Any other group breaks should be nested within this grand total group break.

Next add a footer to the grand total group break. Finally, add the sub-total to the group footer as described above. Do not reset the total to zero, that is, select <;None> from the Reset property drop-down list in the String Properties dialog.

Alternatively, you can create a separate DETAIL to calculate the grand total:

1.Add a new Detail band outside of any BREAK structures in the report.

2.Place your grand total columns on the new Detail band. Be sure to set Reset property to <;None> and specify the detail or break structures on which to tally the total in the Tally property.

3.Suppress the Detail band from automatically printing:

oOn the bands Properties Pad dialog, name a field equate label as the detail structure's USE property attribute.

oOn the Procedure Properties for the Report, press the Report Properties button, then select the Detail Filters tab. Highlight the grand total Detail band then press the Properties button. Then, in the Filter entry, enter False to suppress automatic printing.

4.Embed the following code to explicitly print your grand total detail band:

Clarion Templates     Before Print Preview

ABC Templates         ReportManager Method Executable Code Section

AskPreview()'Priority 1300

PRINT(RPT:MyGrandTotalDetailBand)

Row Totals

Displaying a row total (or any other calculation) requires two steps: assigning a value to a variable, then displaying the variable value in a string control (see Specifying Columns to Print above).

You can assign the value to the variable with embedded source code (see the Embedded Source Code topic) or with the Formula Editor (see the Formula Editor topic).

Whether you use the Formula Editor or embedded source, the key point to know is that the assignment should be done just prior to the PRINT statement. This table shows which embed point to use for each alternative:

Formula Before Print Detail
Clarion Templates Before Printing Detail Section
ABC Templates Process Manager Method Executable Code Section
TakeRecord(),BYTE

blk2blue.jpg

Page Numbers

Controlling/Resetting Page Numbers

Edit the properties of the group HEADERs, the DETAILs, and/or the group FOOTERs. There are several options available. The options are Page Before, Page After, With Next, With Prior, and New Page No.

Displaying Page Numbers

Use the ReportPageNumber template (see Control Templates in the core help Template Guide) or create your own page number control as follows:

1.Select the STRING tool from the Controls Toolbox, then DRAG AND DROP in the page header or footer band.

2.CLICK on the string control you just placed.

This selects the target string's Properties Pad dialog. In the Pad:

3.Set the VariableString property to TRUE.

4.In the Picture property entry, enter @pPage <;<;#p.

This picture token suppresses leading zeroes and displays the page number following the word “Page.”

5.In the Use property entry, enter a field equate label to reference the string in source code.

For example, enter ?PageCount. This need not reference a variable. The Report Engine generates its own variable to hold the page number.

6.From the TotalType property drop-down list, choose Page No.

Displaying Print Dates

To place a “Date Printed” in a report

Use the ReportDateStamp template or create your own date stamp control as follows:

1.Select the STRING tool from the Controls Toolbox, then DRAG AND DROP in the page header or footer band.

For a print date you generally use the page header or page footer.

2.CLICK on the string control you just placed.

This selects the target string's Properties Pad dialog. In the Pad:

3.In the Text property entry, enter a date picture (@d1, for example).

4.In the Use property entry, enter a local variable called PrintDate.

5.Press the Save and Close button to exit the Report Designer.

6.In the Data / Tables Pad, create a LONG local variable called PrintDate to match the variable you entered.

7.Press the Save and Close button to exit the Report Designer Editor, and return to the Application Tree.

To assign a value of TODAY() to PrintDate:

1.Select your target Report Procedure, and then press the Embeds button in the Application Tree.

2.In the Embedded Source dialog, DOUBLE-CLICK the following embed point:

Clarion Templates Procedure Setup
ABC Templates WindowManager Method Executable Code Section
Init()

2.3.In the Select embed type dialog, DOUBLE-CLICK SOURCE.

2.4.In the Text Editor enter this code:

PrintDate = TODAY()

2.5.Press the Save and Close button and save your embedded source.

blk2blue.jpg

Implementing Print Preview

Generate a report procedure with the Report template or the Report Wizard (see Lesson 2: The power of the Application Wizard). In the report procedure's Procedure Properties dialog, press the Report Properties button, then check the Print Preview box in the Report Properties dialog.

PrintPreview1.jpg

If you prefer to hand code your print preview process, see PREVIEW in the Language Reference for more information and examples.

Printing Labels (Dynamically)

NoteBox.jpg

This section shows only one technique for printing report labels. There is also a Label Wizard that we strongly recommend for you to use.

Printing labels simply means printing a multi-column report so that the report rows and columns match up with the commercial label forms you use.

In the real world, different users will have different label papers at different times, so ideally, the user should be able to specify the dimensions of the label paper at run-time, and the label report should fit the specified label paper.

To print dynamically sized labels:

2.6.Add a Labels table to your data dictionary.

2.7.Create Browse and Update procedures for the Labels table.

2.8.Create a Label Report procedure.

2.9.Add the Label table to the Label Report Table Schematic.

2.10.Embed code to do the run-time resizing.

Add a “Labels” Table to Your Data Dictionary

The table may use whichever file system you prefer, and should contain the following columns. No keys are required, but using LabelType as a unique key provides alphabetic sorting and prevents duplicate entries. See: Adding Tables to the Dictionary and Adding or Modifying Columns.

Name Type Length Initial Value
LabelType String 15
PageWidth Decimal 5,2
PageHeight Decimal 5,2
LabelWidth Decimal 5,2
LabelHeight Decimal 5,2
TopMargin Decimal 5,2
LeftMargin Decimal 5,2
FontSize Byte 11

Create a Browse and an Update Form for the Label Table

The fastest way to build these procedures is to use the Procedure Wizard.

2.11.From the Application Tree, press the INSERT key, or press the New Procedure button.

2.12.In the New Procedure dialog, enter a name (BrowseLabels) then press OK.

2.13.In the Select Procedure Type dialog, select the Browse Wizard in the Wizards tab.

2.14.Answer the Wizard's questions:

Choose the Labels table. Do allow the user to update rows. Do provide a “Select” button. The Wizard builds both procedures, then opens the Procedure Properties dialog for the Browse procedure.

2.15.Press the Save and Close button to exit the Procedure Properties dialog.

Create a Label Report Procedure

Your report should observe these conventions. The report columns should have Height and Width of Default and there should be only one column per line. Thus if you need to display FirstName and LastName on the same line, you should concatenate these columns into a single column.

2.16.Create a report for your address table (meaning the table that contains the addresses you wish to use).

Use the Report Wizard if you want, but don't worry about formatting yet. Just make sure the report contains all the name and address columns you need for your labels.

Call the label report as you would any other report.

2.17.From the Application Tree, select your report procedure and press the Report button to enter the Report Designer.

2.18.Delete all report sections, except the Detail section.

CLICK on the section's caption bar then press DELETE.

2.19.For report lines with more than one column, concatenate the columns and remove trailing spaces.

This step improves the appearance of your labels by removing unnecessary spaces. This step is also required to support the embedded code recommended below.

Follow the steps described in the How to CLIP and Concatenate Name Columns of the How Do I…? topic in the online help.

2.20.Set the properties for each report column.

TipBox.jpg

Use the Property Toolbar to identify the columns.

Arrange your name and address columns in a vertical format, that is, one column below another, starting at the top left corner of the Detail band. Use the Alignment tools for precise alignment. See Specifying Columns to Print above.

Remember to set the Height and Width properties of each column to Default.

Your report should look similar to the illustration.

LabelFormat.jpg

2.21.Specify a field equate label (USE attribute) for the Detail section.

CLICK on the detail then type ?detail in the Property Toolbar Use entry.

2.22.Press the Save and Close button to exit the Report Designer and save your changes.

Add the Label Table to the Report Table Schematic

This step ensures that the report procedure opens the Label table and therefore has access to the Label table's row buffer. The embedded code below uses the position and size values in this row buffer to assign run-time positions and sizes to the label report.

2.23.From the Application Tree, select your label report procedure, and then select the Data / Tables Pad.

2.24.From the Data / Tables Pad, select Other Tables, and press the Add button.

2.25.From the Select a Table dialog, DOUBLE-CLICK or select Labels.

Embed Run-time Resizing Code

Now we will embed code at three points in the report procedure:

2.26.Beginning of Procedure'call the BrowseLabels procedure to allow the user to specify the label paper to use.

2.27.After Opening Report'call the ResizeTheReport routine to assign the label sizes specified by the user.

2.28.Procedure Routines'the ResizeTheReport routine.

2.29.From the Application Tree, RIGHT-CLICK your label report procedure then choose Embeds from the popup menu.

2.30.From the Embedded Source dialog, DOUBLE-CLICK on the following embed point:

Clarion Templates Beginning of Procedure, After Opening Files
ABC Templates WindowManager Method Executable Code Section
Init()'Priority 7800

2.31.From the Select Embed Type dialog, DOUBLE-CLICK SOURCE and enter the following statements:

 !Allow Run-time Specification of Label Paper

 GlobalRequest = SelectRecord   !enable select button

 BrowseLabels                   !call BrowseLabels procedure

2.32.Exit the Text Editor and save your changes.

2.33.From the Embedded Source dialog, DOUBLE-CLICK on the following embed point:

Clarion Templates After Opening Report
ABC Templates WindowManager Method Executable Code Section
Open()'Priority 7800

2.34.From the Select Embed Type dialog, DOUBLE-CLICK SOURCE and enter the following statements.

DO ResizeTheReport

2.35.Exit the Text Editor and save your changes.

2.36.From the Embedded Source dialog, DOUBLE-CLICK the Procedure Routines embed point (ABC and Clarion Templates).

2.37.From the Select Embed Type dialog, DOUBLE-CLICK SOURCE and enter the following statements.

If you specified a label for your REPORT structure, change the report labels below to match your label.

ResizeTheReport  ROUTINE

!!=============================================================

!! Modify the report to fit specified label paper.

!! Assumes Report Measurement Unit is 1/1000 of an inch.

!!=============================================================

SETTARGET(report)  !Make report the target for property assignments

!!===========================================================

!! Define the REPORT's AT attribute (ie detail print area).

!! The detail print area should be the size of the entire page.

report{PROP:Width}  = LAB:PageWidth  * 1000

report{PROP:Height} = LAB:PageHeight * 1000

!! Adjust the margins to center the address text within each label.

report{PROP:Xpos}   = LAB:LeftMargin * 1000

report{PROP:Ypos}   = LAB:TopMargin  * 1000

!!===========================================================

!! Define the DETAIL's AT attribute.

!! The DETAIL should be the size of each individual label.

?detail{PROP:Width}  = LAB:LabelWidth  * 1000

?detail{PROP:Height} = LAB:LabelHeight * 1000

!!===========================================================

!! Adjust font size and vertical position of the report columns.

LOOP Fld#=FIRSTFIELD() TO LASTFIELD()     !Process all report columns

 Fld#{PROP:Fontsize} = LAB:FontSize       !Set font size

 IF Fld# > FIRSTFIELD()                   !Skip the first column,

  Fld#{PROP:Ypos}=BottomOfPreviousColumn# ! reposition the rest

 END

 BottomOfPreviousColumn#=Fld#{PROP:Ypos}+(16*LAB:FontSize)

 END

SETTARGET()        !Reset default target to the active window.

 EXIT   !Exit the ROUTINE.

That's it! Make and run your application. When you run your label report, you will have the opportunity to input the dimensions of your various label papers. The dimensions are stored in the Label table where they are available for your selection or modification each time you print labels.

Printing One Row per Page

To print a separate page for each row, check the PAGEAFTER box in the Detail Properties dialog. See Report Structures and Properties'Detail.

Printing Mail-Merge Documents

For a mail merge document, you usually place the name and address columns in the HEADER, and then reserve the DETAIL for a multi-line text control. See Page Header above. See Printing Multi-Line Text below.

Printing Graphics

Graphic controls embellish the report and guide the reader's eye to the data. The following controls allow you to add pictures, lines, and shapes to your report. See the Controls and Their Properties section for more information on the following controls.

Image

Most likely you will wish to place an image, such as a logo, in a HEADER. You may choose any of the graphic table formats supported for window controls; however, printing large images, especially .JPG files may present problems for some printers.

The most important consideration when placing an image is its size'Clarion automatically resizes the image to fit the control size. This may introduce distortion. WMF files distort the least, however, the simplest way to prevent distortion is to preserve the height to width ratio of your images.

To size a 640 x 480 pixel graphic, for example, determine its height-to-width ratio, which is 4:3. Plan an image box in the same ratio'for example, 2000 x 1500 thousandths, which represents a 2-inch by 1.5-inch box on the page.

TipBox.jpg

Whenever possible, use vector graphics such as the Windows Metafile Format (*.WMF). When you need to shrink or stretch them, their appearance is less subject to distortion than a bitmap.

To place an IMAGE control in your report:

2.38.Select the IMAGE control from the Controls toolbox, and DRAG and DROP to the band where you want to place the control.

The Report Designer places an IMAGE control in the report structure. The center of the crosshair positions the upper left corner of the control.

2.39.CLICK the control you just placed.

This selects the Image's Properties Pad dialog.

2.40.In the File property entry, enter the fully qualified image file name, or press the ellipsis (…) button to select the file from the Windows file dialog.

Clarion automatically links the image file into the executable when the file is explicitly named in the control, so you don't have to ship the image file separately.

2.41.In the Use property entry, enter a field equate label to refer to the image control in source code.

2.42.Enter the correct image size in the fixed Width and Height property entries.

2.43.Set the ImageMode drop list property to designate how the image will be displayed within the container control.

You may also resize the image by clicking and dragging its handles.

Line

Lines are the simplest means of visually separating sections or columns within your report. To place a line:

2.44.Select the LINE tool from the Controls toolbox, and DRAG and DROP to the band where you want to place the control.

The center of the crosshair positions the left end point. The Report Designer places a LINE control in the report structure. Relocate and resize the line by dragging its handles.

2.45.CLICK the control you just placed.

This selects the line's Properties Pad dialog.

2.46.In the Use property entry, enter a field equate label to refer to the line control in source code.

2.47.To specify a horizontal line, be sure to set the Fixed property to TRUE in the Height group, and enter a zero (0) in the box next to it. The height is the measure of the vertical distance between the origin and the end point; for a horizontal line, this is equal to zero. In the Width property, enter the length of the line in the Fixed property.

2.48.To specify a vertical line, set the Fixed property to TRUE in the Width group, and enter a zero (0) in the box next to it. The width is the measure of the horizontal distance between the origin and the end point; for a vertical line, this is equal to zero. In the Height group, type the length of the line in the Fixed property.

To specify a horizontal or vertical line the full width or height of the section, setthe Full property to TRUE.

TipBox.jpg

To create a horizontal divider line useful for splitting a HEADER from the DETAIL section, for example, check Full Width, and set the Fixed Height to zero.

2.49.To specify a line color, set the LineColor property, and then choose a color from the Color dialog.

Box

You can highlight a report column by placing a gray box underneath it. You can frame an entire area of a report by placing a box with no fill around it.

TipBox.jpg

When overlapping one control over another, choose Report Designer BLTTRIA.jpg Format BLTTRIA.jpg Order BLTTRIA.jpg Bring to Front to ensure the underlying control is printed before the overlying control; otherwise the overlying control may be obscured.

To place a box:

2.50.Select the BOX tool from the Controls Toolbox, and DRAG and DROP to the band where you want to place the control.

The center of the crosshair positions the upper left corner of the box. When you click, the Report Designer places a BOX control in the report structure. Resize and relocate the box by dragging its handles or its interior.

2.51.Select the box you just placed. This opens the Box Properties Pad dialog.

2.52.In the Use property entry, enter a field equate label to refer to the control in source code.

2.53.Set the COLOR property attributes.

If you want a solid box filled with color, enter a valid color equate in the check FillColor property or press the ellipsis (…) button to choose a color from the Fill Color dialog.

If you want a colored border, enter a valid color equate in the check BorderColor property or press the ellipsis (…) button to choose a color from the Border Color dialog.

2.54.If you want rounded corners for the box, set the Round box property to TRUE.

2.55.Enter the measurements you wish in the target Width and Height properties (AT).

TipBox.jpg

To create a border or 'frame' around the whole report, place a box in the Form band. Be sure the FORM is the full size of the page. Create a box with a border but no fill, and set the width and height to Full.

Ellipse

When placing an ELLIPSE in a report, follow the same procedures as for placing a box.

Printing Multi-line Text with Word-wrap

A multi-line text control can print a long string (such as a MEMO), automatically word-wrapping and printing as many lines as the MEMO's contents requires.

2.56.Select the TEXT tool from the Controls Toolbox, and DRAG and DROP to the band where you want to place the control.

The center of the crosshair positions the upper left corner of the control.

The Report Designer places a TEXT control in the report structure. Resize the text box by using the mouse to drag its handles.

2.57.CLICK the text control and choose Properties from the popup menu to open the Properties Pad for the Text coontrol.

2.58.Enter the name of the variable in the Use property.

2.59.Set the Resize property to TRUE.

2.60.You can optionally display Rich Text Format content by setting the RTF property to TRUE (UseRichTextFormat).

At run-time, the text expands downward, expanding the detail if necessary, to contain the entire text of the memo! If necessary, the text flows onto the following page. The RESIZE attribute only adjusts the height of the TEXT and the DETAIL.

Reports That Look Like Windows

The Report Designer gives you the ability to print on the page virtually anything you can put on the screen. This includes specialized controls such as list boxes, check boxes, group boxes, radio buttons, etc.

In most cases, setting control properties for a report is identical to setting control properties for a window. See the Controls and Their Properties topic for more information on each of the following controls.

Option Box

You may print an OPTION structure within your report. This appears on the page exactly as it does on screen'as an option box. You place an option structure on the page only to hold radio buttons. You may hide the box structure so that only the buttons print on the page.

2.61.Select the OPTION tool from the Controls toolbox, and DRAG and DROP to the band where you want to place the control.

The center of the crosshair positions the upper left corner of the box. The Report Designer places an OPTION structure within the report structure. Resize and relocate the option box by dragging its handles or its interior.

2.62.Select the option box you just placed. This selects the Options Properties Pad.

2.63.In the Text property entry, enter a caption for the option box.

If you choose not to hide the option box when printing, the caption appears at the upper left border of the box, just as it does on screen.

2.64.In the Use property entry, enter a field equate label to refer to the control in source code.

2.65.Set the Boxed property to FALSE to hide the box, but not the radio buttons.

You must add each radio button separately, placing them in the OPTION box.

Radio Button

Placing RADIO buttons in a printed report provides a visual aid to the user by showing the selected value as well as all the possible values for the column.

Before you place the radio buttons in the report, you must first place an OPTION structure, by using the Controls BLTTRIA.jpg Option Box command. The RADIO button must be placed inside the option box representing the OPTION structure. If you attempt to place a radio button without an OPTION structure, the Development Environment displays an error message.

2.66.Place an OPTION box as described above.

2.67.Select the RADIO tool from the Controls Toolbox, and DRAG and DROP to the band where you want to place the control.

The center of the crosshair positions the upper left corner of the radio button. The Report Designer places an RADIO control within the OPTION structure.

2.68.Select the radio button you just placed. This selects the Radio Button Properties Pad.

2.69.In the Text property entry, enter a caption for the radio button.

The caption appears beside the radio button, just as it does on screen.

2.70.In the Use property entry, enter a field equate label to refer to the control in source code.

The radio button automatically turns 'on' or 'off' according to the value of the variable specified in the OPTION box's USE attribute.

Check Box

The check box (CHECK control) provides an attractive way to display a yes/no choice for a column'the alternative might be an entire column that repeats “one,” “yes,” or even “.T.” for each row.

The printed check box looks similar to an on screen check box. To place the check box:

2.71.Select the CHECK tool from the Controls Toolbox, and DRAG and DROP to the band where you want to place the control.

The center of the crosshair positions the upper left corner of the check box.

2.72.Select the CHECK control. This selects the Check Box Properties Pad dialog.

2.73.In the Text property entry, enter a caption for the check box.

The caption appears beside the check box, just as it does on screen. You may make this text appear to the left or right of the checkbox by using the justification settings.

Group Box

The primary reason for placing a group box in a report is to make a group of controls on paper resemble their appearance on screen.

To place the GROUP control:

2.74.Select the GROUP tool from the Controls toolbox, and DRAG and DROP to the band where you want to place the control.

The center of the crosshair positions the upper left corner of the group box. The Report Designer places a GROUP structure within the report structure.

2.75.Select the control, or RIGHT-CLICK the control and choose Properties from the popup menu. This opens the Group Properties Pad dialog.

2.76.In the Text property entry, enter a caption for the group box.

This appears at the upper left border of the group box when the report prints, provided you set the Boxed property to TRUE.

2.77.In the Use property entry, enter a field equate label to refer to the control in source code.

Clear the Boxed box to hide the box, but not the internal controls.

2.78.Add additional controls to the group as needed.

List Box

When the data you require for the report exists in a QUEUE, you may place a list box in the report. The list box that appears on the page is similar to the LIST control that appears on screen, though it will obviously not have the same functionality'the printed page does not support scroll bars, for example.

Because a queue is required for a list box, and because Clarion's report template does not normally use a queue, several embedded source statements must be added to a template generated report procedure in order to use a list box. Alternatively, you may hand code the report procedure or use a report template that uses a queue.

At print time, the first time the code cycles through the report, it prints the LIST's header and the first item in the queue. Each additional cycle prints the next item of the queue without repeating the header. The LIST's header is automatically repeated for applicable page breaks and group breaks.

To place a list box in your template generated report:

2.79.Select the LIST tool from the Controls Toolbox, and DRAG and DROP to the band where you want to place the control. The center of the crosshair positions the upper left corner.

TipBox.jpg

Each listbox item prints as a “selected” item with the specified selected item colors. The default Windows colors for a selected item are “reverse video” (white-on-black). To produce normal black-on-white printing, use the List Box Formatter to set the Selected Text for each column to COLOR:Black and the Selected Background to COLOR:White.

2.80.Make the list box one (1) row high (about .220 inches).

2.81.Drag the bottom handle until only the list box headings are visible. This eliminates empty space between rows.

2.82.Make the detail band the same height as the list box.

Drag the list box to the top of the band or set its Y property coordinate to zero (0), then drag the bottom handle of the band to the bottom of the list box. This eliminates empty space between rows.

2.83.Select the list box to open the List Properties Pad.

2.84.In the Use property entry, enter a field equate label to refer to the control in source code.

2.85.In the From property entry, enter the label of the queue the list box displays.

Embeds Required for the List Box Processing:

Generally speaking, the embedded source statements need to do two things: declare the QUEUE and load the queue buffer with data.

2.86.Declare a QUEUE in the following embed point:

Clarion Templates: Data Section, Before Report Declaration
ABC Templates: Data Section, Before Report Declaration

  CustomerView  VIEW(Customer) !Template generated view

         PROJECT(CUST:Name)

         PROJECT(CUST:Phone)

         PROJECT(CUST:Zip)

        END

CusQ    QUEUE,PRE          !embedded QUEUE declaration

Name      LIKE(CUST:Name)

State     LIKE(CUST:Phone)

ZIP       LIKE(CUST:Zip)

    END

2.87.Load the queue in the following embed point:

Clarion Templates Before Printing Detail Section
ABC Templates ProcessManager Method Executable Code Section
Next(BYTE ProcessRecords=True),BYTE
Priority 7500

CusQ.Name  = CUST:Name       !copy VIEW buffer to QUEUE buffer

CusQ.Phone = CUST:Phone

CusQ.Zip  = CUST:Zip

Next: Lesson 10 - Procedure Basics

lesson_9_exploring_the_report_procedure.htm.txt · Last modified: 2021/04/15 15:57 by 127.0.0.1