next up previous contents
Next: 7 Editing a Report Up: DataVision version 0.2.0 Previous: 5 Creating a New   Contents

Subsections

6 The Anatomy of a Report

The data a report retrieves from the database is only part of a report. A report also includes headers and footers and may include groups of data, formulas to perform calculations, run-time parameters for which you are prompted, and running subtotals and totals.

A report is made up of a set of standard headers and footers as well as the report detail rows. Each part except the details is optional. Each part contains one or more sections that can be turned on or off (suppressed).

The parts that make up a report are:

Each section contains fields. A field may be a database column, a calculated formula, static text, a running subtotal, a special value like the report's title or the current page number or a parameter fields that allows you to specify values at report run time.

6.1 Report Parts

The Report Header is printed once at the beginning of the report on the first page. Typically, a report title is placed here.

The Page Header is printed at the top of each page (but after the Report Header on the first page). Often, column titles are placed here. In fact, when you place a database column in the Detail section, a title is automatically placed in the Page Header for you.

The Group Header is printed before the first row of data and again each time a group's value changes. Since groups can be nested, the group header for each group is printed in order.

The Detail section is printed once for each row of data.

The Group Footer is printed just before a group's value changes, and after the last row of data in the report. Since groups can be nested, the group footer for each group is printed in reverse order. Subtotals may be added here.

The Report Footer is printed once at the end of the report on the last page. This is where end-of-report grand totals belong.

The Page Footer is printed at the bottom of every page.

6.2 Fields

A field is a single unit of information. A database column field displays the value of a column in the database.

A static text field displays a text label.

A formula field contains a chunk of code that is evaluated when the report runs. Formula fields may use the values of any other fields, including other formula fields. For more information, see Section 6.3, Formulas.

A running subtotal field displays the total of a series of values. The values may come from any numeric database column or formula.

A special value field contains one of the following values:

A parameter field allows you to specify values at report run time. Parameter fields may be used anywhere: in formulas, in the report, or for limiting the records selected from the data (the Select Records... menu item).


6.3 Formulas

A formula can execute code that you write. This code write must be in a simple RPN mini-language (see Section 6.3.1, The RPN Mini-Language). Note: this language will change drastically in the future; hopefully to something more understandable such as embedded scripting language like Ruby.

Before being evaluated, the following substitutions are made to the formula text:


6.3.1 The RPN Mini-Language

The language used for formulas is extremely simple. It uses Reverse Polish Notation (RPN), long familiar to HP calculator users. Note: this formula language will change drastically in the future; hopefully to something more understandable such as embedded scripting language like Ruby.

After substituting the values of columns, formulas, and special values, only three things are allowed in a formula: numbers, strings, and operators.

6.3.1.1 Numbers

All numbers are treated as floating-point numbers.

6.3.1.2 Strings

Anything contained in double quotes or obtained from a column, formula, or special value that holds a string.

6.3.1.3 Operators

The available operators are:

+
Adds the two previous values, if they are both numbers. If either one is a string, they are both treated as strings and are concatenated. For example, ``1 " banana" +'' returns ``1 banana''.

-
Subtracts the previous value from the value before that. Both values must be numbers. For example, ``5 3 -'' subtracts 3 from 5, leaving 2.

*
Multiplies the two previous values. If the second previous value is a string and the previous value is a number, returns the string repeated number times. For example, ``"banana" 2 *'' returns ``bananabanana''.

/
Divides the second previous value by the first. Both values must be numbers. For example, ``10 2 /'' returns 5.

More operators are on the way.

6.4 Parameters

More needs to be written.

Create parameters using the Field Picker window. Select New Parameter... from the Field menu.

Drag parameters into the ``Select Records'' dialog or onto the report to use them. When a report that contains parameters is run, you will be asked to supply values for those parameters.

6.4.1 Example

Open the example report, and then select Select Records... from the Report menu. Type ``office.name = ?String Param'' and click ``OK''. The ``?String Param is the name of one of the parameters defined in the report XML file. (Alternately, you can open the Field Picker window and drag the ``office.name'' database field and the ``?String Param parameter from the list of items.)

Run the report. You will be asked to supply a string value. Accept the default value, ``Chicago''. The report will only display records whose office name matches ``Chicago''.


next up previous contents
Next: 7 Editing a Report Up: DataVision version 0.2.0 Previous: 5 Creating a New   Contents
Jim Menard 2002-04-18