Reports

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:

• Report node

• Subreport node

• Call node

• Instance node

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:

   • The current report file—A named report in the current file can be invoked by any other report in the same file.

   • An included report file—If the report file's Inclusions property specifies other files, any named report from the included files can be invoked as a subreport.

   • Another report file—To invoke an external report—that is, a report defined in a non-included file—qualify the report name with the name of the file that stores it:

     report-filename!report-name

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

Setting Subreport Composition

Three Composition properties control subreport output:

Indent

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.

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:

• No (default)—The subreport begins with no groups in effect; the first group node encountered in the subreport begins a new group hierarchy.

• Yes—Groups set in the calling report remain in effect for the subreport; groups specified in the subreport are added to the existing hierarchy. The subreport also inherits the parent report's current break level to prevent duplication of break headers in the subreport.

  Execution of a detail node normally forces an initial break for all groups. If a subreport has a detail node and detail processing is already underway in the calling report, you can avoid redundant break processing by setting Use Caller Groups for the subreport node to Yes. The subreport inherits the caller's break hierarchy and the current break level. When the first fetch of a detail node is executed in the subreport, initial breaks are forced only for break levels subordinate to the calling report's current level.

  The report structure location of a subreport node that uses its caller's groups determines which group levels are affected:

  Invoked from:	Affected group levels in subreport:
  detail node	None
  group header/ footer	Lower levels only
  page format/ instance node	The subreport inherits the break level current in the parent when the calling subreport node is processed. The subreport's detail node forces initial breaks at all lower levels. If no break level is active, the detail statement forces breaks at all levels.

Use Caller Format

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

• No (default)—The subreport uses the property settings of its own page format node—Page Size, Orientation, and Floating Footer; it also uses the actions attached to its own page header and footer sections. If any page format properties in the subreport are left empty, the subreport uses the caller's settings.

• Yes—Panther uses the caller's page format node and ignores the one in the subreport.

  When Use Caller Format is set to No, Panther processes page footer actions differently for internal and external subreports:

• If the subreport is internal—that is, stored in the caller's report file or included at runtime—Panther executes the subreport's page footer actions on the current page.

• If the subreport is external, Panther continues to execute the caller's page footer actions for the current page; the subreport's page headers and footers execute only on the first new page that the subreport itself generates. When control returns to the caller, Panther restores its page header and footer actions only when the current page ends.

  To ensure that Panther processes an external subreport's page header and footer actions immediately after it is invoked, force a page break before the subreport starts. To restore its caller's page header and footer actions right after the subreport ends, force a page break before the caller resumes control.

  Note: A subreport that is invoked from a report's page header or footer always uses the primary report's Page Size and Orientation properties. The subreport's header and footer sections and their actions are ignored.

---

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:

   • Type the code directly in the JPL Program Text window.

   • Choose the Editor button to invoke your local text editor.

   • Read in an existing file by choosing the Read File button. The Select File dialog box opens, where you can identify the file.

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:

• Invoke initialization and clean-up procedures such as opening and closing a database connection. Refer to "Connecting to a Database" for more information.

• Produce title and trailer pages. Refer to "Generating Title and Trailer Pages" for more information.

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:

• A subreport node can invoke a report that is defined in another file by specifying the file name and the name of the report—for example, title.rpt!main.

• A report can specify report files to be included through its Report Files property. All report definitions, layout areas, and widgets in the included files are accessible to the entire report.

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:

report-filename!report-name

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.