A form allows the user to administer the data of just one table. This
table is henceforth referred to as "the form's main table".

However, a form also has an SQL SELECT statement, which generates the
data that are displayed on it.

In the simplest case the SQL SELECT statement is just:

    SELECT <attributes of main table> FROM <main table>

In that case, the data which can be administered and the data which
are displayed on the form are the same.

In more complex cases, the <main table> can be JOINED with other
tables, which makes it possible to display data of other related
tables as well. These data cannot be modified by means of the form.

The table "pfm_form" has the following attributes:

    - name : the name of the form (usually equal to the name of
      the form's table);

    - tablename : the name of the form's main table;

    - pkey : the primary key of the form's main table, which may
      consist of more than one attribute. In that case pkey is a SPACE
      separated list of the attributes of the primary key;

      Note: If pkey is empty, the form is read-only, since pfm is
            unable to uniquely identify a record. You can use the
            'oid' as primary key, but according to the PostgreSQL
            documentation that is not recommended, unless you set a
            UNIQUE constraint on the 'oid'.

    - sqlselect : the attribute list of the form's SQL SELECT
      statement, not including the word 'SELECT';

    - sqlfrom : the FROM clause of the form's SQL SELECT statement,
      not including the word 'FROM';

    - groupby : an optional 'GROUP BY' clause, not including the words
      'GROUP BY';

    - sqlorderby : an optional 'ORDER BY' clause, not including the
      words 'ORDER BY';

    - sqllimit : an optional 'LIMIT' clause, only specifying the limit
      value as a positive integer;

      Notes:

          - This enables the designer of the form to avoid excessive
            memory usage by limiting the number of records loaded in
            the form's internal buffer. This may be useful for
            handling large tables.

          - If sqllimit is a positive integer, a

                   LIMIT sqllimit OFFSET 0

            is added to the form's SELECT when opening the form.

            This means that only 'sqllimit' records are loaded into
            the form's internal buffer. When the user moves beyond the
            last record in the internal buffer, the internal buffer is
            first cleared and then reloaded with the next 'sqllimit'
            records by re-executing the form's SELECT but now with
            another OFFSET in the LIMIT clause.

          - If sqllimit is an empty string, no LIMIT clause is
            appended to the form's SELECT.

          - Always specify an 'sqlorderby' if you specify an
            'sqllimit'.  See PostgreSQL documentation of LIMIT-clause
            in SELECT statement for more details.

    - showform : a boolean indicating whether the form is shown
      in "normal mode" (showform = 'true') or in "design mode"
      (showform = 'false'). Typically, showform is set 'true' for user
      defined forms and 'false' for the predefined pfm_* forms.

    - view : a boolean indicating whether or not the
      "tablename" is a view;

    - help : a text which is displayed when the user presses
      the [Help] key on the form.

The form's main table is defined by tablename. Only the data of
that table can be administered by using the form.

All the data generated by the form's SQL SELECT statement can be
displayed on the form. The SQL SELECT statement is defined by:

    - the sqlselect, sqlfrom, groupby, sqlorderby and sqllimit
      attributes of pfm_form; and

    - the optional WHERE and ORDER BY clauses provided by the user
      when opening the form.

Note: The WHERE clause provided by the user when opening the form, becomes
      a HAVING clause, if there is a GROUP BY clause.

The following rules should be observed when filling out sqlselect and
sqlfrom:

    1. The form's main table must appear in 'sqlfrom', and must not be
       aliased. Similarly, the main table's attributes appearing in
       'sqlselect' must not be aliased. The other tables appearing in
       the 'sqlfrom' may be aliased.

    2. The fields appearing in 'sqlselect' must have a unique, simple
       name without the need to precede them with a tablename. So,
       calculated fields must be given a name by aliasing and
       attributes of tables other than the main table may need to be
       aliased in order to have a unique, simple name.

    3. The 'sqlfrom' is either just the name of the form's main table,
       or it is a JOIN clause in which the 'LEFT' table is the form's
       main table. Several join clauses can be nested in order to
       involve more than 2 tables. See examples below.


Example 1: the SQL SELECT for the person form of the addressbook database


tablename:
    person

pkey:
    id

sqlselect:
    id, christian_name, name, street, town, "ZIPcode",
    country, category, description

sqlfrom:
    person

groupby:
    -


Example 2: the SQL SELECT for the memberlist form of the addressbook database


tablename:
    memberlist

pkey:
    group person

sqlselect:
    memberlist."group", memberlist.person, p.christian_name, p.name

sqlfrom:
    memberlist LEFT OUTER JOIN person p ON (p.id = memberlist.person)

groupby:
    -