Chapter 5. Defining the Report Structure

Each report file can contain one or more reports and can call reports in other report files. The processing order for a report file is determined through its structure nodes. This chapter describes the function of the following nodes:

Defining a Report

A report file contains one or more reports. Each report begins with a report node, which can name the report and specify its parameters. This node and its descendants comprise a single report.

Named and Unnamed Reports

The Report Structure window can contain multiple reports. Of these, only the first can be unnamed. Unnamed reports can be invoked through the name of the report file. For example, this runreport command runs the first report in report file expense_report, without regard to its Name property:

runreport expense_report

Alternatively, the following runreport command runs the report summary_rpt in the report file expense_reports:

runreport expense_reports!summary_rpt

An unnamed report can serve only as a main report; other reports in the same report file are typically invoked as subreports by the main report and by each other. Named reports can also be invoked externally—as main reports, or as subreports by reports in other files.

Refer to Chapter 9, "Running Reports," for more information.

Report Parameters

A report can define one or more parameters, which allows its caller to supply a corresponding number of arguments. This can be useful for setting a report's properties at runtime. For example, an argument that sets the WHERE clause in a report's SQL statement lets you specify sets of data each time you run the report. Or you can alternate layout areas for the report's title page, where the layout area to use is set through a command-line argument.

When you select the Parameters property, a dialog box opens. Enter the names of the parameters, one per line. You can enter the name of any dynamic output widget in the layout window or of the JPL global variable that is declared in the report file's unnamed procedure. Each parameter so named receives an argument when the report is run. The order in which parameters are specified determines the order in which arguments must be passed to the report.

If the report receives fewer arguments than the number of defined parameters, the values of the leftover parameters remain unchanged. If the report receives more arguments than the number of defined parameters, the extra arguments are ignored.

Invoking Subreports

In general, you can invoke any named report as a subreport at any stage of report execution. How you use a report can determine where you store it. If a report is intended to be invoked as a subreport by different reports, it probably makes sense to define it in a separate file where it can be accessed equally by all its users. Alternatively, if a subreport is invoked only by one report, you can define both in the same file.

How to Invoke a Subreport

  1. Create a subreport node in the report structure. Attach the subreport node at the point in the structure where you want its output to appear.
  2. Identify the desired report in the subreport node's Report Invocation property. The name that you enter must be defined in a report node's Name property. The report to invoke can be in one of three locations:

For more information about invoking external and included subreports, refer to "Building Modular Reports."

Setting Subreport Composition

Three Composition properties control subreport output:

Shifts right all subreport output from the caller's leftmost margin by the amount of space specified. Relative spacing within the subreport's output remains unchanged. Specify the amount of space to indent in this format:
indent-space [unit-spec]

Units of measurement (unit-spec) can be specified in inches (in), millimeters (mm), or characters (c—the default). If you specify dimensions in character (c) units, Panther uses the average character size in the report's default font to calculate a character unit's width.

Keep on Page
Determines whether subreports are split across pages. If you set this property to Yes, Panther keeps all output of the specified subreport together and unbroken. If the subreport can fit in the space remaining on the current page, it is output immediately; otherwise, Panther starts a new page.

If Keep on Page is set to No (the default), subreport output begins on the current page and continues on the following pages if needed.

Reserve Space
Sets the amount of space that the subreport occupies. This property must be set for subreports invoked from page footers; it is optional otherwise. This property is especially useful for printing on forms with a fixed-length space for the subreport data.

The default value is blank, which specifies to use only the amount of space required to output the entire report. You can set the amount of reserved space in inches (in), millimeters (mm), or characters (c—the default). For example, 5in reserves 5 inches to output the report, while 40 specifies to reserve 40 characters. If the value is in character (c) units, Panther uses the average character size in the report's default font to calculate a character unit's height.

If Reserve Space is set to a value, Panther assumes that the subreport occupies the stated area and computes page breaks accordingly. If the subreport contains less area than specified, Panther appends blank output to achieve the required size. If the subreport contains more than the specified number of lines, the output is truncated and an appropriate warning message is issued.

If Reserve Space is blank, Panther consolidates a subreport's leading and trailing blank lines with the adjacent output. Refer to "Consolidating Blank Space," for an explanation of blank line consolidation.

Note: Use Reserve Space only for page footer subreports and fixed-length subreports. To keep a subreport from being split across pages, set Keep on Page to Yes.

Using Caller Settings

Two properties, Use Caller Groups and Use Caller Format, let you decide whether the subreport should use the calling report's group and page format node settings.

Note: A subreport that lacks its own group nodes always uses the caller's settings.

Use Caller Groups
Controls whether a subreport uses the caller's groups or its own:

Use Caller Format
Controls whether a subreport uses the caller's page format node or its own:

Calling Functions

Insert a call node wherever you want to execute a function written in JPL or C. A call node specifies the desired function through its Function Call property. A call node can invoke a JPL procedure or installed C function. For a description of specific uses of call nodes, refer to "Using Call Nodes."

The string that you enter in the Function Call property must use the syntax of JPL's call command. For example, a call node can invoke function myproc and pass string arguments hello and world by setting its Function Call property to this value:

myproc( "hello", "world" )

You can call any JPL procedure that is in the current report file, an included report file, or a public JPL file—that is, a file whose procedures are made accessible via the public command.

You can also call a C function if it is installed on the prototyped function list and linked into Panther. For information on installing prototyped functions, refer to "Installing Prototyped Functions" in Application Development Guide.

How to Create or Edit JPL Procedures in a Report File

  1. Give focus to the report's layout window.
  2. Under Inclusions, select the JPL Procedures property. The JPL Program Text dialog box opens.
  3. Enter or edit the JPL procedures with one of these methods:
  4. Choose OK to accept your changes and exit the window. Or discard your changes by choosing Cancel.

Processing One-Time Events

An instance node provides an all-purpose hook for one-time execution of the attached action nodes. For example, compare the page format nodes shown in Figure 5-1. The header sections of both contain a call node that calls function init. However, in the first case, the call node is attached directly to the page format node; at runtime, Panther calls init before each page is output, including the first one. In the second case, the call node is attached to an instance node; in this case, Panther calls init only once, before the first page is created:

Figure 5-1 An instance node's actions are executed only once.

You can attach any number and type of action nodes to an instance node; Panther performs these actions in order of appearance. Instance nodes are typically used to perform these tasks:

Building Modular Reports

You can build a report whose components are partially or entirely derived from other report files. This is particularly useful for objects that have the potential for being reused by different reports—for example, layouts for title and trailing pages or inserted reports.

A report can access the contents of another report file in two ways:

In both cases, Panther looks for the specified file in the application's memory-resident list, then in all open libraries.

Invoking External Report Files

A report can invoke a subreport that is stored in another file; the subreport node's Report Invocation property names the desired report with this syntax:


Including Report Files

A report file can specify to include one or more other files. At runtime, Panther views the file and its inclusions as a single virtual file. Consequently, reports in one file can reference components in any of the other files. For example, if report file x.rpt specifies to include y.rpt, at runtime Panther views the two files as one. Thus, subreport nodes in x.rpt can specify reports in y.rpt; similarly, print nodes in y.rpt can name layout areas that are in x.rpt.

How to Include Report Files

  1. Give focus to the layout window of the primary report file.
  2. Under Inclusions, select the Report Files property. Panther displays the Report Files dialog box:

  3. In the dialog box, enter the names of the report files you want to include. Each inclusion must be on a separate line. You can either type in the names directly or read in the contents of another file by choosing Insert File.

An included file can itself specify to include other files. For example, the following diagram illustrates a possible inclusions structure, where file a includes b and c, and c includes files d and e:

All names that might be cross-referenced among the primary file and its inclusions—for example, layout areas, reports, and nodes—should be unique; if redundant names occur, Panther resolves the ambiguity by using the first component that it finds among the child report files. For example, if files d, c and a all contain layout areas named page_header, Panther uses the layout area in d.

Caution: Multiple nesting levels contain the potential for circular references. A file should never include one of its predecessors.

Included Versus External Files

Panther opens and closes external subreports as needed at runtime, so you can invoke as many subreports from the main report as desired. The maximum number of inclusions for a single report is limited to 254 lines in the primary and included reports.