Reports

The Panther editor offers two views into a report file: the physical layouts used by a report are shown in the layout window, while specifications for report generation are schematically rendered in the Report Structure window. This chapter focuses on report structure components and their properties.

The report structure for any report is available by choosing ViewReport Structure.

Report Structure Window

The Report Structure window schematically shows how a report executes. Stages of report execution are depicted in a vertical 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 example, the following column report sorts orders from video store outlets by distributor name and order number:

Figure 3-1 Column report by distributor name and order number

Figure 3-2 shows how execution of this report is viewed through the Report Structure window and its corresponding layout window. The two windows offer complementary views into the same report definition:

Figure 3-2 Structure of report that outputs video outlet orders.

Figure 3-2 shows a report structure composed of these node types:

• The topmost unnamed node is a report node; it represents the desired report. All nodes attached to it comprise the report's definition. The Report Structure window can contain multiple reports, each beginning with a report node and representing separate report definitions. Of these, only the first report can be unnamed.

• A page format node follows the report node; it specifies page dimensions and orientation. Attached to it are two print nodes, which specify the layout areas to use for page header and footer output—page_header and page_footer, respectively. Because page headers and footers are above and below all other page output, these two nodes enclose the detail and group nodes.

• A detail node specifies the source of report data. In this case, the report relies upon Panther's transaction manager to use the table views and link widgets stored with this report to fetch the required data. Attached to this node is a single print node, which outputs each instance of the detail data.

• Three group nodes are attached to the detail node; these tell Panther how to organize data in the report. Each group node has a print node in its footer section, which outputs subtotals for its group.

Node Classes and Types

Nodes belong to one of two classes—structure nodes and action nodes:

• Each structure node determines an aspect of the report definition—for example, a page format node sets page dimensions and orientation, while a detail node determines how the report gets its data.

• Action nodes are attached to a structure node and determine report output and processing for that structure node—for example, a print node that is attached to a group node's footer section specifies the layout area to print after a break occurs within that group; a call node specifies a function to call; and so on.

Table 3-1 lists the different node types and summarizes their purpose:

You can attach any number and type of action nodes to all structure nodes except a report node. Action nodes can be attached in any order.

Node Hierarchy

The order of a report's structure nodes is summarized in this formula:

A report structure conforms to these rules:

• The first node in a structure must be a report node.

• A report node must be followed by a page format node, whose properties set page dimensions and orientation. A report can have multiple page format nodes; this lets you change a report's format at different stages of execution.

• After the page format node, a report can contain one or more instance and detail nodes in any order. Each detail node can have one or more group nodes. Typically, a report uses one set of data and has only one detail node.

• Each structure node except a report node can have one or more action nodes attached to it. Action nodes can be of any type and placed in any order.

The flexibility offered by report structures lets you create almost any flavor of report with as many levels of complexity as needed.

Editing the Report Structure

You can modify the report structure by adding, removing, and moving nodes. You can also control the amount of detail shown by collapsing and expanding portions of the structure's hierarchy.

How to Add a Node

1. Select the node type from either of the following:

   • Create menu—Select a node type from the list.

   • Tool box—Select the desired icon.
     

2. Select the node that is above the position desired for the new node.

Select a node and do one of the following:

• Choose EditCut or the Cut button from the toolbar.

  This places the removed node and its attachments in the structure's clipboard. You can then paste the node wherever its placement is valid in the report structure. The cut node remains in the clipboard until it is overwritten by the next Cut or Copy operation.

• Choose EditDelete or press the Delete key.

  The selected node and its attachments are removed from the structure and from memory; they can only be restored by choosing Undo.

How to Copy a Node

Select the node to copy and choose EditCopy or the Copy button from the toolbar.

This places a copy of the node and its attachments in the structure's clipboard. You can then paste the copy anywhere its placement is valid in the report structure. The copy remains in the clipboard until it is overwritten by the next Cut or Copy operation.

How to Paste a Node

1. Choose EditPaste or the Paste button from the toolbar.
2. Select the node that is above the position desired for the pasted node.

Select the node that you want to move. Do either of the following:

• From the Edit menu, choose ArrangeMove Up or ArrangeMove Down.

• Press the Move Up or Move Down key. The logical keys for Move Up and Move Down are EXTU and EXTD, respectively. These are mapped by default, in both X and Windows, to the physical keys shift-uparrow and shift-downarrow, respectively.

  Note: You can move a node up and down only within its current level in the report structure hierarchy. For example, a call node that is subordinate to an instance node can be moved above or below other action nodes that belong to the same instance node; it cannot be moved anywhere else in the report structure. To move a node elsewhere in the hierarchy, use Cut and Paste.

How to Collapse and Expand the Structure View

Click on a node's type ID button to toggle all attached nodes in and out of view; or from the Edit menu, choose ArrangeExpand or ArrangeContract. Figure 3-3 shows how you can collapse and expand portions of the report structure.

Figure 3-3 Click on a node's type ID button to collapse and expand the view of its subordinate nodes.

You can also collapse or expand the entire structure. From the Edit menu, bring up the Arrange submenu and choose the desired option:

• Contract All—Hides all nodes in the structure window except report nodes.

• Expand All—Restores view of all nodes in the structure window.

Editing Node Properties

Through the Properties window, you can edit the properties of any selected node. To bring the Properties window into focus for the current node, give focus to the node. An arrow marks the selection; you can bring the Properties window forward by double-clicking on this arrow.

Each node type has one or more properties that are unique to it; these are discussed in later sections. Nodes also share a common set of Identity properties; these are discussed below.

Name

A node's Name property identifies it for programmatic access. Named nodes can be accessed at runtime in order to change their properties. For example, naming a print node lets you access its area property and set it according to the runtime context:

if amount < 0
{
   detail_output->area = "debit_entry"
}
else
{
   detail_output->area = "credit_entry"
}

Report nodes must be named in order to be explicitly invoked—for example, by another report or from the command line.

Refer to "Naming Conventions" in Using the Editors for more information about widget naming conventions and requirements.

Inherit From

Defines the source of inheritance for this report—the name of the repository report followed by the name of the parent object in this format:

repository-entry!widget-name

A node can inherit any properties that are set in its source, such as Break On and Orientation. However, nodes cannot inherit their relationships to each other as specified by their relative order in the repository entry's report structure.

For more information about inheritance, refer to "Controlling Inheritance" in Using the Editors.

Comments

By including a brief description of a node, you can save information about this node and its purpose:

1. Select the node.
2. Under Identity, select the Comments property. The Comments dialog box opens.
3. Enter or edit text through one of these actions:

• Type the text directly in the text area.

• Choose Editor to access your local editor as defined by setup variable SMEDITOR.

• Choose Read File to read in an external file located on your system.

• Choose Save File to save the comments to an external file.

4. Choose OK to save the comments and return to the Properties window.

You can review dependencies between a node and widgets in the layout window by selecting that node and choosing ReportShow Property Links. The Property Links dialog displays, which contains two types of entries:

• prop-name -> widget-name shows that this node's prop-name property is set to widget-name. For example, the links for a print node might include this entry:

  Area -> distrib_name_footer

  This entry shows that the print node's Area property specifies to output layout area distrib_name_footer.

• prop-name <- widget shows that a widget in the layout window specifies this node in its prop-name property. If widget is an unnamed widget, it is identified as Field #n, where n is its field number. For example, the links for a detail node might include this entry:

  Update In <- Tdistrib_name_qty

  This entry shows that the detail node is referenced by total widget Tdistrib_name_qty's Update In property.

  Note that group and detail nodes can be linked to a total or history widget's Initialize In and Update In properties even when those properties are blank. Panther infers the default for these properties from the node in which the widget is output.

For example, this dialog shows the links for a group node:

Figure 3-4 Property Links dialog shows the widgets that are specified in a node's properties.

Note: The Property Links dialog only shows links to existing widgets; if a property specifies a widget or node that does not exist—either because it is not yet created or it is included at runtime—the dialog omits this link.

Going to a Property Link

When you display the Property Links dialog, you can give focus to the widget or node specified in the selected entry by choosing Go To, or by double-clicking on the entry. If the widget is in the layout window, this window gets focus.