Copyright This is version 1.0.1 of Postgres Forms, a client application for postgreSQL. Copyright (C) 2004 Willem Herremans This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA A copy of the GNU General Public License can be displayed with the menu item 'License' under 'Help'. Please send bugs, fixes, suggestions, and improvements to willem.herremans@belgacom.net Introduction Postgres Forms is a client application with a graphical user interface for the postgreSQL data base server. It enables the user: - to design forms for adding, modifying or deleting records of data base tables; - to design links (one to many relationships) from one form to another, for navigating in the data base; - to design and to generate reports based on the data in a table or view; - to edit and to execute SQL statements. Postgres Forms is implemented in Tcl/Tk, but there is no need for the user to program anything in Tcl/Tk. The user has to use SQL for creating tables and views and for designing forms and links. Postgres Forms makes no attempt to hide the underlying SQL. On the contrary, in most cases, it shows both the SQL statements it sends to the postgreSQL server and the results it gets back. Postgres Forms has been designed and tested with version 8.4 of Tcl/Tk and with version 7.3.2. of the PostgreSQL database server. For more information on Tcl/Tk and PostgreSQL look at http://www.tcl.tk and http://www.postgresql.org respectively. Postgres Forms needs either the Pgtcl package or the pgintcl package to communicate with PostgreSQL database server. Both can be obtained from http://gborg.postgresql.org. 1. Main window The main window has a menu-bar with menu-items: Database, Reports/Queries, Tools, Help. 1.1. Database menu The Database item opens a sub-menu with the following items: - Open... : open a data base; - Close : closes the current data base; - Exit : exit from Postgres Forms. 1.1.1. Opening a data base After selecting 'Open...', you are prompted to enter the parameters for opening a particular data base residing on a particular host. These parameters are (copy of the postgreSQL documentation): - host: Name of host to connect to. If a non-zero-length string is specified, TCP/IP communication is used. Using this parameter causes a hostname look-up. See hostaddr. - hostaddr : IP address of host to connect to. This should be in standard numbers-and-dots form, as used by the BSD functions inet_aton et al. If a non-zero-length string is specified, TCP/IP communication is used. Using hostaddr instead of host allows the application to avoid a host name look-up, which may be important in applications with time constraints. However, Kerberos authentication requires the host name. The following therefore applies. If host is specified without hostaddr, a hostname look-up is forced. If hostaddr is specified without host, the value for hostaddr gives the remote address; if Kerberos is used, this causes a reverse name query. If both host and hostaddr are specified, the value for hostaddr gives the remote address; the value for host is ignored, unless Kerberos is used, in which case that value is used for Kerberos authentication. Note that authentication is likely to fail if libpq is passed a host name which is not the name of the machine at hostaddr. Without both a host name and host address, libpq will connect using a local Unix domain socket. - port : Port number to connect to at the server host, or socket filename extension for Unix-domain connections. - dbname : The database name. - user : User name to connect as. - password : Password to be used if the server demands password authentication. Default values for the parameters host, hostaddr, port, user and dbname are read from the user's options file (see section 1.2.1. Options). All parameters, except dbname, can be typed directly on the window that is displayed. The 'dbname' can be selected from a list 'dblist' defined in the user's options file. The following figure shows the main window of Postgres Forms:
Above the listbox, there are 2 radio buttons:
- a radio button [ o Normal mode] to activate normal mode;
- a radio button [ o Design mode] to activate design mode.
In "Normal mode" only the user defined forms are visible.
In "Design mode" only the forms for the pfm_* tables are
visible. These are the forms which can be used to define forms, links,
valuelists and reports:
The following forms are predefined and can be used to add, modify or
delete form definitions:
- pfm_form : a table defining the forms of the data base;
- pfm_attribute: a table defining the form attributes;
- pfm_value_list : a table defining the value lists for
attributes;
- pfm_value : a table defining the values of the lists
defined in pfm_value_lists.
- pfm_link : a table defining the links between forms;
- pfm_report: a table defining a report;
- pfm_section: a tables defining a report's sections, layout and
fields.
See section "4 The pfm_* tables" for details.
1.1.2. Close data base
By selecting Database - Close, you close the currently open data
base. The list-box on the main window becomes empty.
1.1.3. Exit
When you select Database - Exit, the Postgres Forms application is
closed.
1.2. Reports/Queries
The "Reports/Queries" menu item has the following sub-items:
- Run SQL: enter, edit and run SQL commands
- Run report : run a report that has been defined previously
1.2.1. Run SQL
When you select this menu item, the following window is opened:
It has two text areas, one for the SQL statements, another for the
results.
This tool is in fact nothing more than a GUI-frontend for the psql
interactive terminal that is included in postgreSQL.
When you press the [Run] button, all the text present in the SQL
statement text area is sent to psql.
If you enter more than 1 SQL statement in the text area, the
statements have to be separated with ";".
Apart from SQL statements, you can also enter the psql "\"
commands. E.g.
- \? : returns the psql on-line help on the "\" command;
- \h : returns the list of SQL statements for which psql provides
on-line help;
- \h <SQL statement> : returns the on-line help for the SQL
statement.
Every time the [Run] button is pressed, psql is invoked, the commands
in the SQL statement area are sent to it, the results are returned in
the result text area and psql ends. The next time [Run] is pressed,
psql is invoked again, i.e. psql is not kept alive between two runs.
Consequently, if you want to use commands like "\x", you have to enter
them in the SQL area, just before the SQL statements for which you
want "\x" to apply.
Every time you press [Run] the commands in the SQL area are stored in
the command history. You can scroll through the command history using
the [Back] end [Forward] buttons.
The result area is not cleared when another run is done, i.e. the
result of a new run is appended to the result already present in the
result area. You can clear the result area explicitly by pressing the
[Clear] button.
The text in the result area can be printed or saved to file, using the
[Print result] or [Save result] buttons respectively.
The 'Print result' feature is described in more detail in section
1.2.3. Print result
Notes:
- The result area is shared between the "Run SQL" and "Run report"
commands. So, it is possible to combine the results from Run SQL
and Run report into one file or into one printout.
- Using the radio buttons [SQL] and [Report], it is possible to
toggle between "SQL" and "Report" mode. When doing so, the
result area is not cleared.
1.2.2. Run report
When you select this menu item, the following window is opened:
The upper part of the window, shows the list of reports that have been
defined in the database.
When you press the [Run] button, the highlighted report is executed
and its results are appended to the text already present in the result
area.
The text in the result area can be printed or saved to file, using the
[Print result] or [Save result] buttons respectively.
The 'Print result' feature is described in more detail in section
1.2.3. Print result
Notes:
- The result area is shared between the "Run SQL" and "Run report"
commands. So, it is possible to combine the results from Run SQL
and Run report into one file or into one printout.
- Using the radio buttons [SQL] and [Report], it is possible to
toggle between "SQL" and "Report" mode. When doing so, the
result area is not cleared.
How to define a report is explained in a section 6. Designing a
report.
1.2.3. Print result
When you press [Print result], a window is displayed which shows the
print command as it is defined by the option 'printcmd' (see section
1.3.1. Options).
The value of this option should be a print command that accepts plain
(ascii) text from standard input such as
'kprinter -Plp-text --stdin', 'lpr -Plp-ascii', or 'a2ps ...'.
The printcmd option may contain parameters of the form
'$(parameter_name[=default_value])' where '[=default_value]' is
optional. For each such parameter, a text entry is displayed on the
window, offering the user the possibility to provide a value for the
parameter. If a default_value is specified, that value is already
displayed in the corresponding text entry.
The default value for the printcmd option is:
a2ps --printer=display --$(portrait_or_landscape=portrait)
--rows=$(nr-of-rows=1) --columns=$(nr-of-columns=1) --major=rows
--chars-per-line=$(nr_of_chars_per_line=90)
--center-title=$(title=Report)
The default print command has the following features:
- it uses 'a2ps', a versatile tool that converts plain (ascii)
text to postscript and which can print several virtual pages on
one physical page;
- it sends the output to 'display', i.e. a print preview is shown
in 'ghostview' from which it is possible to really print the
result;
- it has parameters and default values for:
o orientation for the physical page (portrait or landscape),
default: portrait;
o number of rows (i.e. number of virtual pages on one physical
page in the vertical direction), default: 1;
o number of columns (i.e. number of virtual pages on one
physical page in the horizontal direction), default: 1;
o number of characters per line on the virtual page (the font
size is automatically adjusted), default: 90;
o title, default: Report.
Note: Due to a limitation of the Tcl 'exec' command, it is
currently not possible to have more than 1 word for
the title. As soon as the title has 2 words,
even if it is enclosed in single or double quotes,
exec sends it as 2 separate arguments to a2ps which
then considers the second word as the name of a file
to print.
The next figure shows the window that is displayed if the default
print command is used with Print result:
1.3. Tools
The tools menu has a number of menu items, which are described
below.
1.3.1. Options
Postgres Forms has a number of options that are stored in a text
file, named .pfmrc, in the user's home directory. These options can be
viewed and modified by selecting the Tools - Options menu item.
The options are:
- dblist : the list of data bases from which the user can select
one to open;
default : list of the data bases on the local host.
- host : the default value of the 'host' parameter for open data
base;
default : empty string, i.e. not specified, i.e. localhost
- hostaddr : the default value of the 'hostaddr' parameter for
open data base;
default : empty string, i.e. not specified, i.e. localhost
- port : the default value of the 'port' parameter for open data
base;
default : 5432
- user : the default value of the 'user' parameter for open data
base;
default : the user's logon id.
- dbname: the default value of the 'dbname' parameter for open
data base;
default : the data base with the same name as the user's logon
id.
- printcmd : the default print command behind the [Print
result] button of the SQL/Report window. See section
1.2.3. Print result for details.
default:
a2ps --printer=display --$(portrait_or_landscape=portrait)
--rows=$(nr-of-rows=1) --columns=$(nr-of-columns=1)
--major=rows --chars-per-line=$(nr_of_chars_per_line=90)
--center-title=$(title=Report)
If you start Postgres Forms for the first time, the options have their
default values. On later occasions, the options are read from the
options file ~/.pfmrc.
1.3.2. Install pfm_* tables
When the menu item 'Tools - Install pfm_* tables' is selected, the
tables pfm_form, pfm_attribute, pfm_link, pfm_value_list, pfm_value,
pfm_report, pfm_section and the views pfm_table and pfm_table_def are
installed and initialised in the currently opened data base.
If no data base is open, or if the currently opened data base already
contains pfm_* tables, an error message is displayed.
The initial values for the pfm_* tables are such that the forms, links
and value lists, necessary for administering the pfm_* tables, are
defined.
1.4. Help
The Help menu has 2 sub-items:
- Help file : displays this very file;
- License : displays the GNU General Public License;
- About : displays some general information about postgres
forms, such as: version, copyright and whether it is using
Pgtcl or pgintcl to communicate with postgreSQL.
2. Query mode of a form
A form has a one-to-one relation with just 1 database table. Only the
data of that table can be administered by means of the form. This
table is henceforth referred to as "the form's main table".
However, the form also has a one-to-one relationship with just one SQL
SELECT statement, which generates the data that are displayed on the
form.
In the simplest case the SQL SELECT statement is just:
SELECT oid, <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.
See section 4.1. pfm_form for details.
When a form is opened, by pressing the [Open] button on the main
window, it is first in "query mode".
In "query mode", the form displays :
- a text area containing the SQL SELECT related to the form;
- a radio button labeled "WHERE";
- a text field, nearby the "WHERE" radio button, in which the user
can type a conditional expression for the "WHERE" clause of the
SQL SELECT statement;
- a radio button labeled "ORDER BY";
- a text field, nearby the "ORDER BY" radio button, in which the
user can type an "ORDER BY" clause of the SQL SELECT statement;
- an [Execute] button to execute the specified SQL statement;
- a [Quit] button to return to the main window;
- a button for each table attribute, labeled with the attribute's
name and which can be used to paste the attribute's name into the
"WHERE" or "ORDER BY" clause at the cursor position.
- a button for table attributes with 'typeofget' tgList or tgLink
(see section 4.2), labeled with the text 'select and paste value'
and which can be used to select a value from a list and paste it
into the "WHERE" or "ORDER BY" clause at the cursor
position. Although it is possible to paste a value into the
"ORDER BY" clause, it normally does not make sense.
The following figure shows the query mode of the form for table
"invoice" with attributes: id, customer, date. The form also displays
cust_name and invoice_total, which are derived from the tables
customer, order and product. These fields are read-only.
By pressing the "WHERE" and "ORDER BY" radio buttons, the user can
choose whether to edit the "WHERE" or the "ORDER BY" clause.
Initially, the status of the radio buttons is such that the "WHERE"
clause can be edited. By pressing the "ORDER BY" radio button, the
user can switch to the "ORDER BY" clause. By pressing the "WHERE"
radio button, the user can return to the "WHERE" clause, etc.
After pressing the "Execute" button, the SQL statement is executed,
the selected records are stored in an internal buffer and the form
enters the "edit mode".
3. Edit mode of a form
In "Edit mode" the form shows:
- the SQL SELECT statement related to the form;
- the text 'Record ' followed by n/m where n = index of current
record in the internal buffer, m = index of last record in the
internal buffer;
Note: The records are numbered starting from 1. The maximum
value for n is m+1. Record m+1 is a dummy, empty record
which cannot be update of deleted. Its status is always
"After last".
- a text field with the name of the form;
- a status field indicating whether the current record is "Not
Modified", "Updated", "Added", "Deleted", "After last" or "Not
added";
- the data of the current record (initially record number 1);
- buttons labeled [>>] which can be used to view the
attribute's data in a muli-line text window instead of a one
line entry;
- a button [Help] to display the online help for the form;
- the buttons [Next] and [Prev] which enable the user to scroll
through the selected records;
- a button [Update] which enables the user to modify the record
that is displayed (see below for details);
- a button [Add] to add new records (see below for details);
- a button [Delete] to delete the displayed record;
- a button for each link to another table, defined in the data
base table "pfm_link";
- a [Back] button which enables the user to return to the form
that was displayed before a "link" button was pressed;
Note: The [Back] button is displayed only if the form that is
being displayed is the result of pressing a "link" button.
- a [Quit] button to return to the main window;
- an [OK] button, which is used to confirm updates or additions of
records and which is not displayed until [Update] or [Add] is
pressed;
- a [Cancel] button, which is used to cancel updates or additions
of records and which is not displayed until [Update] or [Add] is
pressed;
- a text field showing the last UPDATE, INSERT or DELETE SQL
statement and its result.
When the form enters the "Edit mode", all the records' status fields
initially have the value "Not Modified".
3.1. Update record
After the user presses the [Update] button, Postgres Forms starts a
transaction by sending a 'BEGIN WORK' to Postgres. Then it re-reads
the current record and reserves it for update by sending a 'SELECT
... FOR UPDATE' to Postgres.
If that is successful, the form's table attributes become modifiable,
the buttons [OK] and [Cancel] are displayed and all the other buttons
on the form are deactivated.
The calculated fields and the attributes of tables other than the
form's main table are read-only and do not become modifiable.
Note: If the current record is already reserved for update by
another user, Postgres does not return from the 'SELECT
... FOR UPDATE' before the other user ends the reservation by
either 'COMMIT' or 'ROLLBACK'.
If the user presses [OK] the new values for the record are stored in
the data base and a 'COMMIT WORK' is sent to postgres. This ends the
transaction and releases the new record values to the data base.
The new values are also stored in the internal buffer. This means that
even if the modifications are such that the record would no longer be
selected by the original query, it stays in the internal buffer until
the form leaves the "Edit mode".
Similarly, the record keeps its position in the internal buffer, even
if the that is no longer the position it would get according to the
initial "ORDER BY" clause.
If the user presses [Cancel], the modifications are discarded, and a
'ROLLBACK WORK' is sent to postgres. This ends the transaction and
leaves the record in the same state as before the beginning of the
transaction.
Also in the internal buffer, the record keeps the values it received
at the re-read operation at the beginning of the transaction. The
record's status field is not modified either.
After pressing [OK], the SQL UPDATE statement, the SQL COMMIT WORK and
their results, are displayed in a separate "result frame" at the
bottom of the form.
After pressing [OK], the record's status field becomes "Updated" and
the modified record is reloaded from the database. The result is that
the record's read-only data, such as calculated fields and attributes
of other than the main table are refreshed, taking into account the
changes of the modified data.
3.2. Add record
After the user has pressed the [Add] button, the displayed record's
attributes become modifiable in the same way as for "update
record". The buttons [OK] and [Cancel] are displayed and all the other
buttons on the form are deactivated.
If you want to use the default value for an attribute which has been
defined with CREATE TABLE or with ALTER TABLE, just type "=" for its
value. One of the uses of this feature is to let postgreSQL determine
a next value from a sequence for an attribute of type "serial".
NOTE: Because of this feature, it is not possible to assign "=" as the
value of an attribute using "Add record". However, the "=" does
not have this special meaning for "Update record". So, if it is
really necessary to assign the value "=", you can first assign
another value with "Add record", and set it to "=" it with
"Update record" afterwards.
If the user presses [OK], the new record is stored, both in the data
base and in the form's internal buffer. In the form's internal buffer,
it becomes the last record. This means that even if the new record's
values are such that the record would not be selected by original
query, it stays in the internal buffer until the form leaves the "Edit
mode".
Similarly, the record gets the last position in the internal buffer,
even if the that is not the position it would get according to the
initial "ORDER BY" clause.
If the user presses [Cancel], the new record discarded, i.e. it is
neither stored in the data base, nor in the form's internal buffer.
After pressing [OK]:
- the SQL INSERT statement, and its result, are displayed in a
separate "result frame" of the form;
- the record's status field becomes "Added";
- the record is reloaded so that the read-only data, such as
calculated fields and attributes of other than the main table,
are also displayed for the newly added record;
- the 'last record number' in the internal buffer is incremented
with 1, which is shown on the 'current record number'/'last
record number' display.
- if the insert fails, the values entered by the user stay on the
screen, the status field becomes "Not added" and the current
record number becomes 'last record nr + 1'.
3.3. Delete record
If the user presses the [Delete] button, the current record is deleted
from the data base. It is not deleted from the internal buffer, but
its attributes are all put to an empty string and its status field is
put to "Deleted".
3.4. Status field
The status field is a property of a record in the form's internal
buffer. It is kept in the internal buffer until the form leaves the
"Edit mode" and it is displayed on the form. The possible values are:
- Not Modified : the record was not modified since the form was
opened;
- Updated : the record has been updated since the form was opened;
- Added : the recorded was added since the form was opened;
- Deleted : the record has been deleted since the form was opened;
- After last : the current record pointer is 1 after the last
record in the internal buffer.
- Not added : the last "Add" operation has failed and the
current record pointer is 1 after the last record
in the internal buffer.
3.5. Links to other tables
A link is a pointer from a tuple of data base table A to 0 or more
tuples of data base table B. It is a query on table B which is based
on the values of the attributes of the tuple of table A from which the
link originates.
Let us consider the form of table A and a link between table A and
table B which is defined by A.attrib1 = B.attrib2.
On the form of table A, this link is represented by a button labeled
[B]. Pressing button [B], does the following:
- the SQL statement 'SELECT * FROM B WHERE B.attrib2 = A.attrib1'
is executed in which 'A.attrib1' has the value of the current
record in form A;
- the form A is closed;
- the form B is opened directly in "Edit mode" where the
underlying SQL SELECT statement is the one defined under the
first bullet item.
Every link is defined by a record in the pfm_link data base table.
Note: Postgres Forms does not provide any checks to safeguard
the referential integrity of the data base in case of updates or
deletions. However, postgreSQL provides these functions as
'foreign key' table constraints (see postgreSQL documentation).
3.6. Filling out a form
After pressing [Update] or [Add], the user can fill out a form,
i.e. provide values for the table's attributes.
The user can provide values for the attributes in one of the following
ways, depending on the attribute's "type of get" (see section
4.2. pfm_attribute):
- tgDirect: the user directly types a value for the attribute;
- tgExpression: the user can type an expression which is first
evaluated before it is stored as a new value for the attribute
(e.g. 1.0/7.75);
- tgList: the user selects a value by means of a list-box
containing a predefined list of possible values;
- tgLink: the user selects a value by means of a list-box
containing a list which is the result from a query on another
table.
- tgReadOnly: the attribute cannot be modified by the user.
Notes:
- When selecting a value from a list, the user can specify a
search string at the top of the list box. Every time the [Go]
button is pressed the next list item matching the search string
is selected. The search is case sensitive and may contain '*'
and '?', where '*' means any sequence of characters and '?'
means any single character.
- When "type of get" is tgLink or tgList, the user normally
selects a value from the list, but by pressing the [>>]
button instead of opening the listbox, a new window is opened
in which the user can directly type a value.
3.7. Views
For a "view" it is possible to define a form in Postgres Forms in the
same way as for a "table", but it is not possible to update a view.
The buttons [Update], [Add] and [Delete] are absent on a form for a
view.
4. The pfm_* tables
Per data base, pfm uses tables with a name starting with "pfm_*" to
store the definition of forms and reports. Additionally, there is a
view "pfm_table" which allows the user to display the attribute names
and types of all tables of the data base.
4.1. pfm_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;
- sqlselect : the expression 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_having : an optional 'GROUP BY' clause, not
including the words 'GROUP BY', followed by an optional 'HAVING'
clause;
- view : a boolean indicating whether or not the
"tablename" is a view;
- 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.
- 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 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 and groupby_having
attributes of pfm_form; and
- the optional WHERE and ORDER BY clauses provided by the user
when opening the form.
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. If the form's main table is not a view, the 'sqlselect' must
contain the 'oid' of the main table. If the form's main table
is a view, the 'sqlselect' must not contain the 'oid' of the
main table.
Note: The 'oid' is the 'object identifier'. It uniquely
identifies a row in a table. All tables (not views)
implicitly have an oid in postgreSQL. Postgres Forms
needs it for identifying a row when issuing an SQL UPDATE
or DELETE FROM command. There is no need to display this
attribute on the form, i.e. it is not necessary to define
it as an attribute in pfm_attribute.
4. The 'sqlfrom' is either just the name of the form's main table,
or it is a JOIN clause in which 1 of the tables 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 product form of the sample database
tablename:
product
sqlselect:
oid, id, name, description, nr_in_stock, price
sqlfrom:
product
groupby_having:
-
Example 2: the SQL SELECT for the invoice form of the sample database
tablename:
invoice
sqlselect:
invoice.oid, invoice.id, invoice.customer, invoice."date",
customer.name AS cust_name, SUM(p.price * o.nr) AS invoice_total
sqlfrom:
( (invoice LEFT OUTER JOIN customer ON (invoice.customer = customer.id)
) LEFT OUTER JOIN "order" o ON (invoice.id = o.invoice)
) LEFT OUTER JOIN product p ON (o.product = p.id)
groupby_having:
invoice.oid, invoice.id, invoice.customer, invoice."date",
customer.name
4.2. pfm_attribute
The table "pfm_attribute" defines all the properties of form attributes.
It has the following attributes:
- form : the "name" of the form to which the attribute
belongs;
- attribute : the name of the attribute; this must be equal
to the name of the corresponding attribute of the form's SQL
SELECT statement;
- typeofattrib : the type of attribute:
o taQuoted: the value provided by the user is put
between single quotes when it is transferred to SQL
UPDATE or INSERT statements;
o taNotQuoted: the value provided by the user is not
quoted when it is transferred to SQL UPDATE or INSERT
statements.
Hint: In general, all attribute values must be quoted, exept
the values or expressions for numeric attributes.
- typeofget: defines how the user provides a value for the
attribute; possible values are:
o tgDirect: the user types the value directly;
o tgExpression: the user types an expression which is first
evaluated before it is passed to SQL UPDATE or INSERT;
Note: Even with tgDirect it is possible to enter an
expression as new value for an attribute, but then
the expression is evaluated by postgres whereas with
tgExpression, the expression is first evaluated by
Tcl before the SQL statement is sent to postgres.
o tgList: the user selects a value by means of a list box
containing a list of values defined in table "pfm_value";
o tgLink: the user selects a value by means of a list box
containing a list of values which is the result from a
query on another table.
o tgReadOnly: this attribute cannot be modified by
the user.
Note: All calculated attributes and all attributes from
tables other than the form's main table should be
declared 'read-only'. If this rule is not observed,
the Add and Update operations on this form will fail.
- sqlselect: the SQL SELECT statement which is used to fill the
list box with possible values for the attribute (only meaningful
if typeofget = tgLink).
Note :
o The sqlselect may return more than 1 attribute. If so, all
the attributes are displayed in the list-box, but only the
first one is used for updating the attribute.
- valuelist : the "name" of the value list defined in table
"pfm_value_list" (only meaningful if typeofget = tgList);
- nr: a number which determines the order in which attributes are
displayed on the form;
4.3. pfm_value_list
The table "pfm_value_list" contains all the value lists of all the forms.
Its only attribute is
- name : a name uniquely identifying the value list.
4.4. pfm_value
The table "pfm_value" contains all the values of the lists defined in
pfm_value_list.
It has the following attributes:
- valuelist : the name of the valuelist to which this value belongs
- value : a character string;
- description : a description of the value.
4.5. pfm_link
The table "pfm_link" defines all the links between forms.
It has the following attributes:
- fromform : the name of the form from which the link
originates;
- toform : the name of the form to which the link leads;
- sqlwhere : the "WHERE"-clause of the SQL SELECT statement in
which the value of an attribute of the "from"-form may be
represented by $(attrib-x), where 'attrib-x' is the name of the
attribute;
- orderby : an 'order by' clause which determines the order of the
records in the 'toform';
- displayattrib : a space separated list of
attributes of the 'fromform', the value of which is displayed on
the 'toform' to remind the user from which record the link
originated.
4.6. pfm_report
The table pfm_report defines all the reports for the current data
base.
pfm_report has the following attributes:
- name: the name of the report. This is the name that
appears in the selection list.
- description: free text describing the purpose of the
report in more detail.
- table_or_view: the table or view from which the report is
derived
- sqlwhere: an optional "WHERE"-clause (without the word
"WHERE") that can be included in the SELECT ... FROM
table_or_view. See below for details.
- orderby : an optional "ORDER BY"-clause (without the words
"ORDER BY") that can be included in the SELECT ... FROM
table_or_view
The sqlwhere may contain one or more parameters for which a value is
requested at "Run report" time. A parameter in the sqlwhere must be
formatted as $(parameter_name).
Example:
sqlwhere: (customer='$(customer_name)') AND ("date" >= '$(begin_date)')
When the report is run, the user is prompted to enter values for the
parameters "customer_name" and "begin_date". Then the report data are
selected from the table_or_view by applying a where clause which is
obtained from the sqlwhere in which $(customer_name) and $(begin_date)
are replaced with the values entered by the user.
4.7. pfm_section
The table pfm_section contains all the sections of the reports defined
in pfm_report. A report must have one section at least.
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, ... which uniquely identifies a
section within a report and which also defines an order of the
sections.
- layout: can be "row", "column" or "table".
- fieldlist: a list of field specifiers, one for each field to be
printed in this section of the report (see below for details).
The fieldlist must be formatted as follows:
{attribute_1 label_1 alignment_1}{attribute_2 label_2 alignment_2}...
{attribute_N label_N alignment_N}
where :
- attribute_i is the name of the view attribute that has to be
printed in the i-th field of this section;
- 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.
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 layout.
All sections of a report, except the last one (i.e. the one with the
highest level), are "group level sections".
When the report is being generated, first the records resulting from
"SELECT * FROM table_or_view WHERE sqlwhere ORDER BY orderby" are
stored internally.
Then the data of the first record are printed, first the fields of the
level 1 section, then the fields of the level 2 section, etc. up to
the fields of the last section.
When the next records are being printed, the "group level sections"
are only printed when at least one of the fields belonging to that
section has a value different from the corresponding field of the
previously printed section of the same level.
Only the highest level section (which is not a "group level section")
is printed for all records.
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.
4.8. pfm_table
pfm_table is a view which contains a record for every table, view or
sequence in the database.
It has the following attributes:
- Name: the name of a relation (table or view) in the current data
base;
- Schema: the name of the "schema" to which the table, view or
sequence belongs;
- Type: "table", "view" or "sequence"
- Owner: the owner of the table, view or sequence
The user can browse the data in pfm_table by opening the form with the
same name, but since it is a "view", it is not possible to modify the
data directly.
4.9. pfm_table_def
pfm_table def is a view which contains a record for every attribute in
the data base.
It has the following attributes:
- Tablename: the name of the table to which the attribute belongs;
- Attribute: the name of the attribute
- Type: the data type of the attribute
The user can browse the data in pfm_table by following the
"Attributes" link from the pfm_table form.
4.8. The links between the pfm_* tables
The following drawing shows the links between the pfm_* tables:
The referential integrity is guaranteed by the following table
constraints which are introduced by 'Tools - Install pfm_* tables':
ALTER TABLE pfm_attribute ADD CONSTRAINT ref_form
FOREIGN KEY (form) REFERENCES pfm_form (name)
ON DELETE CASCADE ON UPDATE CASCADE;
ALTER TABLE pfm_link ADD CONSTRAINT ref_fromform
FOREIGN KEY (fromform) REFERENCES pfm_form (name)
ON DELETE CASCADE ON UPDATE CASCADE;
ALTER TABLE pfm_link ADD CONSTRAINT ref_toform
FOREIGN KEY (toform) REFERENCES pfm_form (name)
ON DELETE CASCADE ON UPDATE CASCADE;
ALTER TABLE pfm_value ADD CONSTRAINT ref_list
FOREIGN KEY (valuelist) REFERENCES pfm_value_list (name)
ON DELETE CASCADE ON UPDATE CASCADE;
ALTER TABLE pfm_attribute ADD CONSTRAINT ref_value_list
FOREIGN KEY (valuelist) REFERENCES pfm_value_list (name)
ON DELETE RESTRICT ON UPDATE CASCADE;
5. Designing a form
Designing a form is in fact nothing more than filling out the data
base tables pfm_forms, pfm_attribute, pfm_value_list, pfm_value and
pfm_link defined in section 4. The pfm_* tables.
This is done using the forms that are predefined for these tables.
Note: Postgres Forms does not offer the possibility to define
data base tables or to modify their definition. That can be done
using SQL statements CREATE TABLE ... or ALTER TABLE .... using
the "Run SQL" function of Postgres Forms (see 1.2.1. Run SQL) or
from 'psql', the interactive SQL terminal of postgreSQL.
5.1. Modifying or adding a form
To modify or add a form:
- press the [o Design mode] radio button on the main window. The
pfm_form form now becomes visible in the listbox on the main
window;
- Select the pfm_form form and then open it;
- If you want to modify an existing form, select the form you want
to modify either by specifying a"WHERE" clause, or by scrolling
through the already defined forms until you reach the one you
want to modify;
- If you want to add a new form, don't specify a "WHERE" clause,
just press [Execute] and then press the [Add] button;
- Now it is possible to modify the name of the form, the name of
the database table and the showform boolean.
5.2. Defining a form's attributes
First proceed as explained in the previous section to make the form
you want to work on visible in the pfm_form form.
Then, follow the 'Attributes' link by pressing the [Attributes]
button. This results in the form pfm_attribute being opened with all
the attributes of the selected form loaded in the internal record
buffer.
Here you can add, delete or modify the form's attribute definitions as
appropriate. Note, that it is possible for the form to have less
attributes than the table corresponding to the form, but all the
attributes defined in the form must exist, with the same name, in the
table corresponding to the form.
See section 4.2. pfm_attribute for a description of the attributes
of pfm_attribute.
It may be necessary to add a value list for some attributes. See
section 5.4. Defining value lists.
When finished, press [Back] to return to the form defining the
selected form.
5.3. Defining links between forms
First proceed as explained in the section "5.1. Modifying or adding a
from" to make the form you want to work on visible in the pfm_form
form.
To define links originating from the selected form, press the
[Originating links] button. Then add, modify, delete links as
appropriate. See section pfm_link for a description of the
attributes of pfm_link.
When finished, press [Back] to return to the form defining the
selected form.
To define links terminating on the selected form, press the
[Terminating links] button. Then add, modify, delete links as
appropriate.
When finished, press [Back] to return to the form defining the
selected form.
Links allow the user of Postgres Forms to jump from one table/form to
another while taking into account the relationships between the
tables.
5.4. Defining value lists
To modify an existing value list, select the form 'pfm_value_list' in
the main window and press the [open] button.
Then, specify a query to select that value list and press the
[Execute] button. This results in the selected value list to be
displayed. Here you can modify it's name or delete it.
To add, modify or delete the list's values, press the [Values]
button. This opens the pfm_value form with all the list's values in
Postgres Form's internal buffer. Here, you can modify, add, delete
values.
To define a new value list, select the form 'pfm_value_list' in
the main window and press the [open] button.
Then, specify a query with no "WHERE"-clause Then press [Add] and
specify the name of the new value list.
To insert values for the list, press the [Values] link-button.
6. Designing a report
6.1. Creating a view
The first thing you need to design a report is a view which can
generate all the data you need for the report.
You can use the "Run SQL" function of Postgres Forms to define a view.
Example:
CREATE VIEW invoice_report AS
SELECT
c.id AS cust_id, c.name AS customer, c.street, c.post_code,
c.town, c.country, c.telephone, c.e_mail,
i.id AS invoice, i.date,
o.nr, o.product AS prod_nr,
p.name AS product, p.price, (o.nr * p.price)::numeric(9,2) AS total
FROM customer c, invoice i, "order" o, product p
WHERE (c.id = i.customer) AND (i.id = o.invoice) AND (o.product = p.id)
ORDER BY c.id, i.id;
This view generates the "raw" data of the report. You can display
these raw data by:
\x
SELECT * FROM invoice_report
Note: the "\x" is used to request a column layout rather than a table
layout, which would be too wide to fit on a page. (See man psql
for an explanation).
The result is:
-[ RECORD 1 ]--------------------
cust_id | 2
customer | Nelly Peeters
street | Grote Markt 11
post_code | 7023
town | Sint-Niklaas
country | België
telephone | 03 911 22 45
e_mail | n.peeters@pandora.be
invoice | 1
date | 2003-11-24
nr | 1
prod_nr | 1
product | SuSE 8.2 personal
price | 23.20
total | 23.20
-[ RECORD 2 ]--------------------
cust_id | 2
customer | Nelly Peeters
street | Grote Markt 11
post_code | 7023
town | Sint-Niklaas
country | België
telephone | 03 911 22 45
e_mail | n.peeters@pandora.be
invoice | 1
date | 2003-11-24
nr | 1
prod_nr | 4
product | Windows XP upgrade
price | 399.00
total | 399.00
-[ RECORD 3 ]--------------------
cust_id | 3
customer | Frans Van Langenacker
street | Transvaalstraat 23
post_code | 2030
town | Antwerpen
country | België
telephone | 03 326 25 60
e_mail | fvla@vt4.be
invoice | 6
date | 2003-12-10
nr | 2
prod_nr | 5
product | Tcl/Tk
price | 12.30
total | 24.60
-[ RECORD 4 ]--------------------
cust_id | 3
customer | Frans Van Langenacker
street | Transvaalstraat 23
post_code | 2030
town | Antwerpen
country | België
telephone | 03 326 25 60
e_mail | fvla@vt4.be
invoice | 6
date | 2003-12-10
nr | 2
prod_nr | 6
product | postgreSQL
price | 15.60
total | 31.20
-[ RECORD 5 ]--------------------
cust_id | 3
customer | Frans Van Langenacker
street | Transvaalstraat 23
post_code | 2030
town | Antwerpen
country | België
telephone | 03 326 25 60
e_mail | fvla@vt4.be
invoice | 7
date | 2003-12-12
nr | 3
prod_nr | 1
product | SuSE 8.2 personal
price | 23.20
total | 69.60
-[ RECORD 6 ]--------------------
cust_id | 3
customer | Frans Van Langenacker
street | Transvaalstraat 23
post_code | 2030
town | Antwerpen
country | België
telephone | 03 326 25 60
e_mail | fvla@vt4.be
invoice | 7
date | 2003-12-12
nr | 1
prod_nr | 4
product | Windows XP upgrade
price | 399.00
total | 399.00
Postgres Forms has tools to easily layout a report for these
data. That is explained in the next section.
6.2. Designing the report layout
Enter the design mode by pressing the [o Design mode] radio button on
the main window.
Then select the form pfm_report and open it.
Don't specify a query, press [Execute] and then [Add].
Then you can enter the data as explained in section 4.6. pfm_report.
The next figure shows a possible report definition for our example:
Because of the $(customer_name) and $(begin_date) in the sqlwhere, the
user will be prompted to enter customer_name and begin_date when the
report is run.
Then press the [Sections] button to define the sections and their
layout.
Look at the view definition in section 6.1. Creating a view.
Because of the order specified in the view, all records related to a
customer will be grouped together. So, we can introduce a first group
level section for the customer data.
Within, the records related to a customer, all the records related to
an invoice will be grouped together. So, we can introduce a second
group level section for the invoice data.
Finally, within the records related to an invoice, we will find the
order and product data, but without further grouping (no order is
specified). So, this leads us to the last section, which is not a
group level section.
Possible section definitions for the 3 sections are listed below:
level : 1
layout : column
fieldlist : {cust_id "Customer Id"} {customer Name} {street Address}
{post_code ZIP} {town Town} {country Country}
{telephone Tel.} {e_mail E-mail}
level : 2
layout : row
fieldlist : {invoice "Invoice nr."} {date "Date"}
level : 3
layout : table
fieldlist : {nr "nr. of units" r} {prod_nr "Prod. nr" r}
{product "Product" l} {price "unit price" r} {total "Total price" r}
When this report is run (Menu Reports/Queries, Run report, Select
"Invoices", press [Run]), a report with the following layout is
generated:
Show invoices for a particular customer since a certain date
------------------------------------------------------------
Report : Invoices
View : invoice_report
Where : (customer='Frans Van Langenacker') AND ("date" >= '2003-01-01')
Date : 16-Dec-2003
----------------------------
Customer Id : 3
Name : Frans Van Langenacker
Address : Transvaalstraat 23
ZIP : 2030
Town : Antwerpen
Country : België
Tel. : 03 326 25 60
E-mail : fvla@vt4.be
----------------------------
Invoice nr.: 6; Date: 2003-12-10;
nr. of units | Prod. nr | Product | unit price | Total price
--------------+----------+--------------------+------------+-------------
2 | 6 | postgreSQL | 15.60 | 31.20
2 | 5 | Tcl/Tk | 12.30 | 24.60
Invoice nr.: 7; Date: 2003-12-12;
nr. of units | Prod. nr | Product | unit price | Total price
--------------+----------+--------------------+------------+-------------
3 | 1 | SuSE 8.2 personal | 23.20 | 69.60
1 | 4 | Windows XP upgrade | 399.00 | 399.00
7. Hints for installing and using PostgreSQL
This is no replacement for the postgreSQL documentation. It only gives
some hints for installing and using PostgreSQL in combination with
Postgres Forms.
7.1. Getting started
After you have installed postgreSQL, you have to initialise the so
called 'database cluster'. This is in fact the directory that will
contain all the databases.
To do so, you need to have the postgreSQL user account. This is the
UNIX user who owns all the data and who owns the server process. It is
often the user with login id 'postgres', but that depends on how
postgreSQL is installed. This user is a kind of super-user who can
access all databases, but it must not be the system's superuser.
- Login as user postgres.
- init the database cluster, e.g.
initdb -D /var/lib/pgsql/data --encoding=LATIN1 --lc-collate=C
See section 7.2. for the 'encoding issue'.
- start the postmaster (i.e. the database server)
- createdb postgres
- createuser <user name> where <user name> is the
login id of a user who will use PostgreSQL. Answer the questions
from createuser. The rest of this section assumes that the user
has the right to create/drop databases.
- createdb <user name> where <user name> is the login
id of a previously created user. This will allow the user to
start psql by just typing 'psql', because, by default, the
database with the user's name is openend.
7.2. Character encoding
The Pgtcl package causes Postgres Forms to present itself to the
database server as a client application using character encoding UTF-8
(UNICODE).
The default character encoding used by the PostgreSQL database server
is SQL-ASCII. This character encoding is not suitable for texts
containing special characters like ë, é, è, etc.
When you create a database, you can specify another encoding for the
database (e.g. CREATE DATABASE sample ENCODING='LATIN1', see
PostgreSQL documentation for more details). Postgres Forms can work
with database server encodings 'LATIN1', (i.e. iso 8859-1) and
'UTF-8'. PostgreSQL automatically performs the necessary conversions
on the communications between client and server.
However, if the database server uses 'UTF-8' encoding you may get some
surprises when using the psql interactive terminal of PostgreSQL:
psql, by default, uses the same encoding as the database server, but
the terminal application like xterm, normally uses LATIN1. The result
is, that special characters are not displayed correctly on the xterm
if the server encoding is 'UTF-8'. This can be solved by putting the
client_encoding to LATIN1, but that is an extra complication.
So, the best choice for the database server encoding is probably
'LATIN1', unless of course, you would really need the extra
possibilities offered by UTF-8.
'LATIN1' works well with both psql and Postgres Forms.
It is also worth considering to choose 'LATIN1' when running initdb:
initdb -D /var/lib/pgsql/data --encoding=LATIN1 --lc-collate=C
Then all database that are subsequently created, are by default
LATIN1.
7.3. Installing a new database
First create the new database:
- either createdb --encoding=LATIN1 newdbname;
- or CREATE DATABSE newdbname ENCODING='LATIN1' from psql or from
the Run SQL window of Postgres Forms.
Don't forget to add the newdbname in the dblist option of Postgres
Forms, using menu Tools - Options.
Then open newdbname and install the pfm_* tables by invoking Tools -
Install pfm_* tables.
7.4. Some genreal hints about SQL
Here are some hints about SQL. For full documentation see PostgreSQL
documentation.
- The SQL language is not case sensitive, but it is customary to
use upper case for SQL statements.
- PostgreSQL always converts the names of tables and attributes to
lower case, regardless of the case typed by the user, unless
these names are enclosed in double quotes. Example:
CREATE TABLE Customer (
Id serial,
Name text);
is implicitly and silently converted to:
CREATE TABLE customer (
id serial,
name text);
If you really want Customer, Id and Name, you have to write:
CREATE TABLE "Customer" (
"Id" serial,
"Name" text);
- SQL keywords are not allowed as names of tables or attributes,
unless they are enclosed in double quotes. Example:
CREATE TABLE order ( ...
is not accepted because 'order' is an SQL keyword, but you can
use
CREATE TABLE "order"
to create a table with the name 'order'.
- Postgres Forms automatically encloses the names of tables and
attributes in double quotes for the SQL statements it generates
itself. However, the user still has to take care when entering
SQL statements, or parts of SQL statements, in the pfm_* tables.
8. The sample database
8.1. Installing the sample database
The sample data base is included in the distribution and can be
installed as follows:
1. Create the database:
createdb --encoding=LATIN1 sample
This assumes that you are known to postgreSQL as a user who has
the right to create databases.
2. Fill the database:
psql -e sample < ~/pfm/install_sample.sql
3. Don't forget to add the name 'sample' in the dblist option of
Postgres Forms, using menu Tools - Options. Then you can open
and experiment with the sample database.
8.2. Structure of the sample database
The tables of the sample database have been created with the following
SQL statements:
CREATE TABLE customer (
id serial primary key,
name text,
street text,
post_code text,
town text,
country text,
telephone text,
e_mail text
);
CREATE TABLE product (
id serial primary key,
name text,
description text,
nr_in_stock integer,
price numeric(8,2)
);
CREATE TABLE "order" (
invoice integer,
product integer,
nr integer
);
CREATE TABLE invoice (
id serial primary key,
customer integer,
date date
);
The following figure shows the links between the tables of the sample
database:
The referential integrity of the database is guaranteed by PostgreSQL
table constraints, which have been created with the following SQL
statements:
ALTER TABLE ONLY invoice
ADD CONSTRAINT ref_customer
FOREIGN KEY (customer) REFERENCES customer(id)
ON UPDATE CASCADE ON DELETE RESTRICT;
ALTER TABLE ONLY "order"
ADD CONSTRAINT ref_invoice
FOREIGN KEY (invoice) REFERENCES invoice(id)
ON UPDATE CASCADE ON DELETE CASCADE;
ALTER TABLE ONLY "order"
ADD CONSTRAINT ref_product
FOREIGN KEY (product) REFERENCES product(id)
ON UPDATE CASCADE ON DELETE RESTRICT;