The data returned by the report's SQL SELECT statement may be
considered as a table with a column for each 'field' specified after
the word 'SELECT' and with a row for each record.

By specifying an 'ORDER BY' clause in the report's SQL SELECT
statement, it is possible to group rows with the same values for some
fields together.

The report generator has an "economy" algorithm which avoids printing
the same data repeatedly.

To control this you have to distribute the fields (columns) of the
table over n sections such that section 1 contains the fields that are
changing least frequently (when moving from one row to the next),
section 2 contains the fields that are changing more frequently, and
section n contains the fields that are changing at every row.

When the data of the first row of the table are printed, the data of
section 1 are printed first. Then, on the following line, indented by
one tab stop, the data of section 2 are printed. Then, on the
following line, indented by 2 tab stops, data of section 2 are
printed, etc.

[section 1] <--- row 1

    [section 2] <--- row 1

        [section 3]  <--- row 1

Then, when the next rows are being printed, data of the lower numbered
sections are only printed if they are different from the data of the
last printed section of the same number:

[section 1]

    [section 2]

        [section 3]  <--- row 1
        [section 3]  <--- row 2
        [section 3]  <--- row 3

    [section 2]

        [section 3]  <--- row 4
        [section 3]  <--- row 5

[section 1]

    [section 2]

        [section 3]  <--- row 6
        [section 3]  <--- row 7

The report generator also enables you to print a summary at every
point where a higher numbered section is about to be followed by a
lower numbered section:

[section 1]

    [section 2]

        [section 3]  <--- row 1
        [section 3]  <--- row 2
        [section 3]  <--- row 3

        [summary 3]

    [section 2]

        [section 3]  <--- row 4
        [section 3]  <--- row 5

        [summary 3]

    [summary 2]

[section 1]

    [section 2]

        [section 3]  <--- row 6
        [section 3]  <--- row 7

        [summary 3]

    [summary 2]

[summary 1]

A summary i is printed just before a lower numbered section j (j < i).
Its data can be calculated:

    - by applying one of the aggregate funtions: COUNT, SUM, AVG,
      STDDEV, MIN, MAX;

    - on the fields of the sections j (j >= i), between the last
      printed lower numbered section k (k < i), till the next (not
      yet printed) lower numbered section k (k < i).

In particular, summary 1 is printed at the end of the report, is
calculated from all the sections of the report and may be calculated
from all the fields.

A record in pfm_section defines a section and a summary of a report.

The table pfm_section has the following attributes:

    - report: the name of the report to which the section belongs

    - level: a number 1, 2, 3, 4, ... . The first level must be
      '1'. The next levels must be numbered consecutively. In the most
      simple report, there is only a section with level 1.

    - layout: can be "row", "column" or "table".

    - fieldlist: a space separated list of field specifiers,
      one for each field to be printed in the sections of this level
      (see below for details).

    - summary: a space separated list of summary field
      specifiers (see below for details).

The fieldlist is a SPACE separated list of field specifiers

    field_spec_1 field_spec_2 ... field_spec_N

where each field specifier is formatted as follows:

    {field_i label_i alignment_i max_length_i}

where :

    - field_i is the name of one of the columns returned by the
      report's SQL SELECT statement;

    - label_i is a string which has to be used as label for printing
      the i-th field of this section; if it consists of more than 1
      word, it must be delimited by double quotes (" .... ");

    - alignment_i is optional; if present, it is either l or r,
      indicating whether this field should be left or right aligned.

    - max_length_i is optional: if present, it is the maximum number
      of characters per line for printing the data of this field;
      lines longer than max_length_i will be wrapped by inserting
      one or more line breaks before printing.

      Notes :

          o The alignment is optional. If it is left out, left
            alignment is assumed by default.

          o The alignment only influences the table layout. Column and
            row layouts are unaffected by the alignment indicator.

          o Multi-line fields, i.e. fields containing more than one
            line of text are only formatted properly in a column or
            table layout.

          o For a table layout, pfm automatically calculates the column
            width that is required to display all data. So, normally
            you don't have to worry about column widths. However,
            sometimes, the data of a few records, make the columns
            excessively wide. That is where you might consider using
            "max_length_i" in the field specifier. If the data do not
            exceed that maximum, it won't have any effect.

          o Although 'alignment' and 'max_length' are both optional,
            you have to specify 'alignment' if you want to specify
            max_length.

For every section, the layout can be defined as:

    - row: the section's field labels and field values are
      printed in one row in a format: label_1 : value_1; label_2 :
      value_2; ... etc.

    - column: the section's field labels are printed in a first
      column, the section's field values are printed in a second column.

    - table: the section's values are printed in a table with a
      column per field and a row per record, the section's field
      labels are used as column headers for the table.

The summary must be formatted as a space separated list of summary
specifiers:

    summary_spec_1 summary_sepc_2 .... summary_sepc_N

where each summary_spec is formatted as follows:

    {field_i aggregate_i format_i}

where:

    - field_i is the name of a field defined in the fieldlist of
      either this section, or another, higher numbered section;

    - aggregate_i is one of the aggregate functions: COUNT, SUM, AVG,
      STDDEV, MIN, MAX (see below for details); and

    - format_i is an optional 'ANSI C sprintf' formatting string (see
      below for details). If it is left out, the number is printed
      with maximum precision.


Aggregate functions:

In general, the aggregate functions, use the same "economy" algorithm
that is used for printing section data.

When all the fields of a section, which is not the highest numbered
section of the report, have the same values for a number of
consecutive rows, this section's data are only printed once for these
rows.

Similarly, these rows are only counted once by the aggregate functions
applied to a field of this section.

The aggregate functions that can be used in a summary are:

    - COUNT: Counts the number of rows. In this case, the field_i that
           is specified only determines which section is counted.

    - SUM: Calculates the sum of all the values of the specified
           field.

    - AVG: Calculates the average of the values of the specified
           field.

    - STDDEV: Calculates the sample standard deviation for the values of the
           specified field:

           SQRT (SUM( (value_i - AVG(value))**2 ) / (N - 1))

	   where :

               - value_1, value_2, ... value_N are the values of the
                 considered field;

               - AVG(value) is the average of the considered values;

               - N is the number of values.

    - MIN: Calculates the minimum of the values of the specified
           field.

    - MAX: Calculated the maximum of the values of the specified
           field.


'ANSI C sprintf' formatting string:

Here is a short overview of the 'ANSI C sprintf' formatting string. In
general its form is:

     %'MinWidth'.'Precision''Conversion'

where:

    - 'MinWidth' is an integer defining the minimum width (as number
      of characters) for the number to be printed. If the number does
      not need so much space, spaces are inserted in front of the
      number, unless MinWidth is negative. In that case, spaces are
      appended at the end. If the number needs more space than
      MinWidth, more space is used.

    - 'Precision' is an integer defining how many digits to print
      after the decimal point, or, in the case of g or G conversion,
      the total number of digits to appear, including those on both
      sides of the decimal point

    - 'Conversion' is one of:

          o d : convert integer to signed decimal string. In this case,
                there is no need to define a 'Precision'.

                Example: %1d

                         prints an integer and uses as many characters
                         as required.

          o f : convert floating point number to fixed point
                notation. In this case, 'Precision' defines the number
                of digits to print after the decimal point. If there
                are not enough digits available, trailing zeroes are
                appended.

                Example: %1.2f

                         prints a floating point number wiht 2 digits
                         after the decimal point and uses as many
                         characters as required.

          o e or E : Convert floating-point number to scientific
                notation in the form x.yyye±zz, where the number of
                y's is determined by the 'Precision' (default: 6). If
                the precision is 0 then no decimal point is output. If
                the E form is used then E is printed instead of e.

                Example: %1.5E

                         prints a floating point number in the form
                         x.yyyyy E±zz 

          o g or G : If the exponent is less than -4 or greater than
                or equal to the precision, then convert floating-point
                number as for %e or %E. Otherwise convert as for
                %f. Trailing zeroes and a trailing decimal point are
                omitted. In this case the 'Precision' specifies the
                total number of digits to appear, including those on
                both sides of the decimal point

                Example: %1.4G

                          prints 2345.0 as 2345
                          prints 234567.0 as 2.346E+05
                          prints 0.003456 as 0.003456
                          prints 0.00003456 as 3.456E-05