Reports

Although you might use the report wizard to build the first version of a report, you can also choose to build a report manually. This chapter describes the creation of a simple report in order to understand how the report layout areas and the report structure work together to comprise a report.

For more sample reports, refer to Appendix E, "Sample Reports."

Creating a Report

You create a report by selecting from the File menu NewReport. Panther asks whether you want to use the report wizard:

For information about using the report wizard, refer to Chapter 5, "Report Wizard," in Using the Editors. To build a report manually, choose No. When you make this choice, Panther opens an unnamed report file and displays its layout window:

The layout window is one of two editing windows that you use to build a report. The second window shows the report structure and is opened by choosing ViewReport Structure. These windows offer complementary views into the report definition:

Layout window

Defines the format and content of report output. It typically contains one or more layout areas, named spaces whose contents are output at runtime. A layout area is invoked through a print node in the report structure. The timing and sequence of the layout area's output depends on execution of its print node. For more information about the layout window, refer to Chapter 2, "Introducing Report Layout."

Report Structure window

Schematically shows how a report executes. Stages of report execution are depicted in a hierarchy composed of nodes. The topmost node defines a report; when this report runs, all nodes below and subordinate to it execute in top-down order. For more information about the structure window, refer to Chapter 3, "Introducing Report Structure."

---

Laying Out the Report

The layout window typically contains several layout areas that define different components of a report's output—for example, detail data, column headings, page header and footer, and group subtotals. A layout area outputs data through the widgets that populate it. Each widget's properties determine the source and format of its data; the widget's position within the layout area determines where that output appears in relation to other output from the same layout area.

Most report output is generated through two widget types:

• dynamic output widgets get their data at runtime—for example, from a database or from other widgets.

• static output widgets have their data set in the editor; their data remain constant.

For example, the following report outputs order information and contains three elements—a page header, detail output, and page footer:

Figure 4-1 Report whose output is composed of page header and footer data, and detail data.

Output for each of these elements is defined in its own layout area. The following sections show how to create each of these layout areas.

Creating the Detail Layout

Detail data is typically derived from a database; the data is output through dynamic output widgets whose database properties specify the source of their output. You can easily populate a detail layout area by copying widgets from an open repository whose entries were imported from a database.

How to Create the vbizplus.dic Repository

1. Choose FileNewRepository.
2. Enter the name vbizplus.dic.
3. Choose FileOpenDatabase.

   • Choose the engine and connection: Accept the jdb engine and dm_jdb0_conn connection.

   • Select or specify the vbizplus database and choose Open.

4. Choose FileImportDatabase Objects, then choose Select All. Choose Import and then, once the import is complete, Close.

The import process creates a repository entry for each imported table; included are a table view with the text widgets for every database table name, database columns, link widgets for table relations, and the primary key information. Table relationship information is stored in link widgets. Table views and link widgets are used by the transaction manager to fetch data.

For more information about repositories and importing database tables, refer to Chapter 11, "Creating and Using a Repository," in Application Development Guide.

This report's detail section is output through a layout area whose widgets are copied from the vbizplus.dic repository. Creating this layout area is a two-step process:

• Define the layout area.

• Populate the layout area by copying widgets from the open repository.

How to Define the Detail's Layout Area

1. Give the layout window focus.

2. Choose CreateLayout Area or .
3. Point and click where you want the new area to appear in the layout window.

   Panther creates an unnamed layout area widget, which defines the area above it:

   

   Note: You can locate a layout area anywhere within the layout window without regard to its actual output when the report is generated.

4. Name the layout area:

   • Select the layout area widget.

   • Give focus to the Properties window.

   • Under Identity, set the Name property to data.
     

1. Open the vbizplus.dic repository if necessary.
2. Open two repository entries: orders and order_items.
3. Copy these widgets into the data layout area (either drag and drop or copy and paste):

   • From orders:

     distrib_id, order_num, order_date

   • From order_items:

     price, qty, and link widget K1order_items

     Note that odrer_date is to the right of price and qty in this example.

     Panther automatically converts all copied widgets (except the link widget) into dynamic output widgets. Since the repository entries are imported from database tables, widgets can have the same name on more than one entry. Copy the widgets from parent table views first.

4. Move the link widget below the layout area widget, near the bottom of the layout window. Widgets that are outside a defined layout area cannot output any data.
5. Rearrange and realign the other copied widgets on the same row—from the Edit menu, use AlignBottom and SpaceHorizontal.
6. If desired, edit the widgets' properties to change their format, size, and font. For example, you can set order_date's Format Type property to MON/DATE/YR2 and its Max Data Length property to 8.

   Note: Font properties for a report exist at three levels: for individual widgets, for report layout areas, and for the report as a whole.

7. If necessary, close up unnecessary white space within the layout area:

   • Select and drag the output widgets closer to the top of the layout area.

   • Drag the layout area widget closer to the output widgets.

     Note: To resize an output widget, do not drag the widget by its edge; set the widget size by setting the font size and length property.

The layout window should look like this:

Defining the Page Header Layout

The page header output shown earlier contains several static output widgets that contain column headings, a static output widget that contains the report title, and a dynamic output widget that contains the system date.

Creating this layout area is two-step process:

• Define a layout area.

• Populate the layout area by creating widgets.

How to Define the Page Header's Layout Area

1. Give the layout window focus.
2. Choose CreateLayout Area or the corresponding toolbox button.
3. Point and click below the data layout area.
4. Name the new layout area page_header.
5. If necessary, resize the layout area by dragging the layout area widget up or down.
   

1. Give the layout window focus.

2. Choose CreateStatic Output or .
3. Create the widget by pointing and clicking in the page_header area.
4. Edit the widget's Label property—for example, Distrib ID for the widget above distrib_id's output.
5. Repeat steps 2-5 for each column heading and the report's title.
6. Position the widgets as necessary.
7. If desired, edit the widgets' properties to change their format, size, and font. For example, the widget that contains the report's title has its Bold property set to Yes and its Font Size property set to 14.
   

1. Choose CreateDynamic Output or .
2. Create the widget by pointing and clicking in the page_header area.
3. Under Geometry, set Max Data Length to 8.
4. Set these properties under Format/Display:

   Data Formatting = Date/Time
Format Type = MON/DATE/YR2
System Update = Yes

   If desired, edit other properties. For example, you might want this widget to have the same font size and attributes as the report title.

5. Align the widget and the report title on the same row.

Finally, create a line widget below the column headings. The layout window now contains two layout areas that look like this:

Defining the Page Footer Layout

The page footer output shown earlier contains two widgets: a static output widget whose Label property is set to Page, and a widget that outputs the current page number.

How to Define the Footer with Page Number

1. Create a layout area below page_header and set the name of the layout area widget to page_footer.
2. Create a static label and set its Label property to Page.
3. Create a page number widget.

   1. Choose CreateDynamic Output or the corresponding toolbox button.

   2. Create the widget by pointing and clicking in the page_footer area.

   3. Under Composition, set the widget's Value property to Page Number and under Geometry, set Max Data Length to 3.

   4. Close up the space between this widget and the static label and align them horizontally.

The finished layout window should look like this:

For more information on layout area properties, refer to "Editing Layout Area Properties."

Building the Report Structure

While layout areas define the physical layouts used by a report and the relative positions for the widgets within the layout areas, specifications for report generation are defined in the report structure. To view a report's structure window, choose ViewReport Structure. A new report has this empty structure:

The initial structure begins with an unnamed report node. This node and the nodes connected to it define the report. Through their properties, each one defines an aspect of the report or an action performed during execution. For more about node types, refer to "Node Classes and Types."

To generate the report shown in Figure 4-1, you need to modify this structure to include these nodes:

• Print nodes that output the page header and footer data.

• A detail node that specifies how the report gets its data.

• A print node that outputs detail data.

• A group node that specifies to group data for each distributor ID.

How to Print Page Header and Footer Data

1. Give focus to the Report Structure window.

2. Choose CreatePrint or .
3. Click on the empty page header node (labeled Header).

   Panther creates a print node directly below the page format node, which replaces the empty page header:

   

4. Bring the Properties window forward by double-clicking on the indicator to the right of the new print node.
5. Under Identity, set the print node's Area property to page_header: either select this layout area from the drop-down list, or enter the name directly.
6. Choose CreatePrint or the corresponding toolbox button.
7. Click on the empty footer node.

   Panther replaces the empty footer node with a print node.

8. Set this print node's Area property to page_footer.

The report structure now contains print nodes for page header and footer output:

How to Fetch Data from a Database

A report relies on the structure's detail node to fetch data. Detail node properties specify how the report fetches its data; the print node attached to a detail node specifies when this data is presented.

1. Choose CreateDetail or .
2. Click on the page format node. Panther inserts a detail node beneath the page format node:
   

   The detail node's Data Source property (under Identity) is initially set to TM View. At runtime, this setting specifies that Panther's transaction manager generates the SQL needed to fetch the report data. A report created by the report wizard or built from repository components like this one contains the table views and link widgets required by the transaction manager.

   To make sure that the fetched data is sorted appropriately, set the root table view's Sort Widgets property:

3. Open the Widget List window (ViewWidget List) and select the orders table view widget.
4. Under Server ViewSelect Handling, set the Sort Widgets property to these widget names:

   distrib_id
   order_num
   order_date

1. Choose CreatePrint or the corresponding toolbox button.
2. Click on the detail node.

   Panther creates a print node directly below the detail node.

3. Set this print node's Area property to data.

The report structure now contains a print node for outputting its detail data:

How to Group Report Data

1. Choose CreateGroup or .
2. Click on the detail node.

   Panther creates a group node directly below the detail node.

3. Under Identity, set this group node's Break On property to distrib_id. This property specifies how to group data at runtime—in this case, to generate a group for each distrib_id value.
4. Under Composition, set the Print Break Value property to First Use Only. This setting ensures that only the first instance of each distrib_id value is output.

The report structure now contains a group node for grouping report data on distrib_id:

Testing the Report

The editor has its own viewer, which you can use to view report output at any stage of the editing process. To test the report built in previous sections:

1. Open the vbizplus database.
2. Choose FileTest Mode or the corresponding toolbar button.

The viewer outputs the report, scaled initially to fit in the viewer window. To view the report scaled to 100 percent, choose ViewActual Size or the corresponding toolbar button:

Figure 4-2 The report viewer lets you preview and evaluate report output during an editing session.

Figure 4-3 The final layout and Report Structure windows show how the views interact together to create the final report.

Adding an Item to the Repository

Panther can calculate certain values, such as group or report totals, which can be defined in the report. However, some information is not so easy to calculate, or it is useful to have available for more than one report. For example, for the orders in the vbizplus sample database, you would like to know the total price for each order. To make the totals available for all reports, and for the report wizard, you can add the value to the repository.

How to Add an Item to a Repository Entry

1. Open the editor.
2. Open the vbizplus.dic repository.
3. Open the order_items repository entry by viewing the repository table of contents. (Choose ViewRepository TOC and then select order_items from the list.)
4. Add a static label to the screen and set the label property to Total_price under Identity.
5. Add a single line text widget to the screen.

   1. Set the name property to total_price under Identity.

   2. Under DatabaseFetch Data, set Use in Select to Yes.

   3. Set the Expression subproperty to qty*price.

   4. Set GeometryMax Data Length to 6.

   5. Set Format/DisplayJustification to Right.

   6. Set Format/DisplayData Formatting to Numeric.

   7. Set Format/DisplayFormat Type to 2 dec places with commas.
6. Add the widget to the table view:

   1. Choose ViewWidget List.

   2. Select order_items.

   3. Choose EditGroupSelect Members.

   4. Add the item total_price to the selection group. (Use shift+click in Windows or Motif to select the item in addition to the others already selected.)

   5. Choose EditGroupUpdate Group Members.

The item order_total is now available for use in screens and reports.

Figure 4-4 The total price is now available for the report.

Running the Report

While you are developing a report, you can preview the output in the editor. After the report is finished, there are other ways to run the report. You can use the report viewer from the editor screen or from an application that uses the default Panther menu. From outside the editor, you can use the command line utility rwrun, or you can call the report from within another Panther application, using the JPL command runreport, or the library function sm_rw_runreport.

The report can be run locally, with its own connection to the database, or it can be run remotely in the three-tier environment, taking advantage of the server's connection to the database. To run it remotely, the report must reside in the server's library. The report can be viewed onscreen, saved to a file, or sent to a printer.

For more information, refer to Chapter 9, "Running Reports."