Postgres Forms (pfm) is 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 is included in the 'doc'
subdirectory of this software package.

Please send bug reports and feature requests via the corresponding
facilities on the home page of Postgres Forms (pfm):

http://gborg.postgresql.org/project/pfm/

Please send all other comments or questions to the mailing list:

pfm-comments@gborg.postgresql.org

or directly to me:

willem.herremans@tiscali.be


Getting started:
---------------

Postgres Forms (pfm) has been designed and tested on Linux. It may
work on other UNIXes as well, but it has not been tested.

To get Postgres Forms (pfm) running you need a running postgreSQL
database server and at least 1 database (which may be empty) that you
can access. See postgreSQL documentation for details.

Postgres Forms has been designed and tested with postgreSQL version
7.4.2, but it probably works with some older and newer versions as
well. You can obtain postgreSQL from http://www.postgresql.org.

You also need one of the packages: Pgtcl or pgintcl to communicate
with the postgreSQL database server.

Two versions of pgintcl are included in the pfm distribution: 1.5.0
and 2.1.0.

Pgtcl can be obtained from:

http://gborg.postgresql.org/project/pgtclng/projdisplay.php

pgintcl can be obtained from:

http://gborg.postgresql.org/project/pgintcl/projdisplay.php

Notes:

    - If you intend to use pgintcl, the 'tcpip_socket' connection
      parameter has to be set 'true' in postgresql.conf. This can be a
      security risk. See postgreSQL documentation for details.

    - The Pgtcl package offers better performance, but needs to be
      built, whereas the pgintcl package is just a Tcl script that can
      be called by pfm.

    - If the pgin.tcl file is present in the installation directory,
      pfm sources it and does not attempt to load the Pgtcl package.

    - Postgres Forms has been designed and tested with versions 1.5.1
      of package Pgtcl and with versions 1.5.0 and 2.1.0 of pgintcl.

    - pgintcl 1.5.0. works with postgreSQL version 6.4 or higher.

    - pgintcl 2.1.0 works with postgreSQL version 7.4. or higher.

    - A copy of both pgintcl 1.5.0 and pgintcl 2.1.0 are included in
      pfm distribution and will be installed when required by the GUI
      install program.

Postgres Forms has been designed and tested with Tcl/Tk version
8.4. It also requires the package Iwidgets, which in turn requires
Itcl and Itk.

You can do one of the following to get the proper Tcl/Tk run time
environment:

   1. If these packages are already installed on your system, you can
      let pfm use them.

      Note: You can verify the presence of Tcl/Tk as follows. From the
            command prompt type 'wish'.  You should get a '%' prompt
            and an empty window, titled 'wish'. To see the version,
            type 'info tclversion' at the '%' prompt. You should get
            8.4.  Then type, package require Iwidgets.  You should get
            3.0.1 or preferrably 4.0.1.

   2. If you don't have these packages, and if you are on a PC with
      Linux, you can use the Tclkit run time environment which is
      included in the pfm distribution.

   3. You can install the required packages. The ActiveTcl
      distribution, that you can download from

      http://www.activestate.com/Products/ActiveTcl/

      includes the required packages Iwidgets, Itcl and Itk.


Installation with the GUI installer (only on PC with Linux)
-----------------------------------------------------------

You can either install pfm at system level, such that it is available
for all users, or at individual user level. The installation procedure
is the same, unless specified otherwise.

  1.  For a system installation login as root.

  2.  Put the pfm_x_x_x.tar.gz file in the directory in which you want
      to install the pfm directory and its subdirectories. This
      directory will henceforth be referred to as PARENT.  For a
      system installation PARENT could be /opt or /usr/local; for an
      individual user installation PARENT could be the user's home
      directory (~). Wherever 'PARENT' occurs in the following,
      replace it with the real name of that directory.

  3.  cd to PARENT and unpack pfm_x_x_x.tar.gz:

      tar --extract --gunzip --verbose --no-same-owner --file=pfm_x_x_x.tar.gz

  4.  This creates the directory PARENT/pfm which contains all the
      required files.

  5.  cd to PARENT/pfm and run the install program by typing

      ./install

      on the command line.

      Note: It is important that you run this command from the pfm
            directory (PARENT/pfm).

  6.  This starts the GUI install program. Choose the appropriate
      values for the options and press "Finish"

  7.  The GUI install program does 2 things:

          - It writes a launch script with name 'pfm', in a directory
            of your choice. This enables you to launch pfm by just
            typing 'pfm' on the command line (on condition that the
            pfm launch script was written in a directory in your
            PATH).

          - It creates a symbolic link named 'pgin.tcl' in the pfm dir
            either to pgintcl 1.5.0 or pgintcl 2.1.0, or it deletes
            such a link when you have chosen to use Pgtcl.

      Notes:

         - If you already had a script called 'pfm' in the directory
           that you have chosen, the installer program renames it to
           pfm.bak, or pfm.bak1, pfm.bak2, ...etc.

         - If you already have another script called 'pfm' in another
           directory in your PATH, you may have to delete it, or
           rename one or the other. You can verify which script is
           'active' by typing 'which pfm' on the command line. The
           result should be the fully qualified filename of the pfm
           script installed by the installer program.

  8.  This completes the installation. If it was an installation at
      system level, all users can start pfm by typing 'pfm' on the
      command line. If it was an installation at user level, only the
      user who installed it can start pfm.

  9.  Open the database on which you want to use pfm.

 10.  You will be asked if you want to install the pfm_* tables. Answer
      "yes".

 11.  If the database that you are opening already contains the pfm_*
      tables from a previous version of pfm, you will be asked if you
      want to convert the pfm_* tables. 

      WARNING: Before answering "yes" to this question, make sure that
               you have a backup of your database. There is a
               conversion SQL script from lower to higher version, but
               not from higher to lower version.

 12.  You are ready to use pfm. More documentation is found in the
      on-line help-file.

Notes:

   - The on-line help is the file 'help.html' in the PARENT/pfm/doc
     directory. It can also be viewed by a web browser.

   - You can run the GUI install script at any time to modify the
     choices you have made before.


Manual installation
-------------------

  1.  Do steps 1 throygh 4 of the previous section.

  2.  cd PARENT/pfm

  3.  Configure the interface with postgreSQL:

      a) If you have Pgtcl installed on your system and you want to
         use it:

	 rm pgin.tcl

	 Note: If pgin.tcl does not exist in this directory, you can
	       jump to step 4.

      b) If you want to use pgintcl version 2.1.0:

         ln -s pgintcl-2.1.0/pgin.tcl pgintcl

      c) If you want to use pgintcl version 1.5.0:

         ln -s pgintcl-1.5.0/pgin.tcl pgintcl

  4.  Make a launch script, named pfm, in a directory in your PATH:

      a) If you have Tcl/Tk and the packages Iwidgets, Itk and Itcl
         installed on your system, and if you want to run in this
         environment, the launch script should contain the following
         lines:

         #!/bin/sh

	 wish PARENT/pfm/pfm.tcl PARENT/pfm

      b) If you want to use the Tclkit included in the pfm
         distribution instead (only included for Linux on PC), the
         launch script should contain the following lines:

	 #!/bin/sh

	 PARENT/pfm/tclkit/tclkit-linux-x86 PARENT/pfm/pfm.kit PARENT/pfm

  5.  Don't forget to chmod a+x pfm

  6.  This completes the installation. If it was an installation at
      system level, all users can start pfm by typing 'pfm' on the
      command line. If it was an installation at user level, only the
      user who installed it can start pfm.

  7.  You can now continue with steps 9 through 12 to get started with
      pfm.


Change log:
-----------

Version 1.1.0 (2004-11-11):

    - Option "usePGPASSWORD" has been added. It determines whether pfm
      uses the environment variable PGPASSWORD to store the password
      entered by the user during the short time between clicking 'OK'
      on the 'Open database' window and the actual opening of the
      database. If this option is 'no', the user is not prompted for a
      password when opening a database, but then a properly configured
      ~/.pgpass file is required.

      Notes:

          o This option was added because, according to the postgreSQL
            documentation, the use of the PGPASSWORD environment
            variable is deprecated for security reasons.

          o The default value for this options is still 'yes', for
            backwards compatibilty and for getting started more
            easily. Consider changing this option to 'no'.

          o For connecting to postgreSQL via the Tcl interfaces Pgtcl
            or pgin.tcl, pfm reads the .pgpass file and supplies the
            password to postgreSQL via the "password" connection
            parameter. This was necessary because pgin.tcl ignores the
            pgpass file.

          o pfm supports the "\:" escape sequence in ~/.pgpass, but
            not the "\\" escape sequence. 

    - The connection parameter and option "hostaddr" have been dropped
      because psql does not have a matching "--hostaddr" option, which
      led to a behaviour that was difficult to understand and which
      was unnecessary complicated.

    - Behaviour of 'Run SQL' command history was improved again. In
      particular, the input screen is cleared automatically after
      pressing 'Run'. This saves the user pressing 'Clear' after every
      'Run'. In the case that he wants to see and reuse the command,
      he can do so by pressing 'Back'.

    - It has been reported (see bug 935) that pfm does not work with
      older versions of postgreSQL. The problem is probably only
      install_pfm.sql, which has been generated by pg_dump of 7.3.2.,
      but which is not understood by older versions of postgreSQL.
      install_pfm has been modified such that it probably also works
      with version 7.2.1. of postgreSQL.

      Note: I cannot test this myself, because I don't have access to
            a version 7.2.1. I would be quite happy to receive
            feedback on this.

      The views pfm_table, pfm_table_def and pfm_table_report have
      been dropped.

    - The help file has been improved on serveral points.

    - The report definition has changed significantly. The attributes
      'table_or_view', 'sqlwhere', and 'orderby' of pfm_report have
      been combined into one attribute 'sqlselect' which may contain
      parameters that are entered by the user at run-time. This
      enhances the user's possibilty to introduce run-time parameters
      for the report, and there is no need anymore to create a view
      for designing a report.

    - The menu-item "Tools -> Install pfm-* tables" has been
      dropped. Instead, the user is prompted to install the pfm_*
      tables when opening a database that does not contain them yet.

    - When opening a database containing the pfm_tables generated by
      an older version of pfm, the user is prompted to convert them to
      the new format.

    - An addressbook sample database has been added. The sample
      database of version 1.0.4. has been renamed to customerdb.
     
    - The groupby_having attribute of pfm_form has been renamed to
      groupby. The reason is that no HAVING CLAUSE should be specified
      in the definition of the form. The WHERE clause specified by the
      user when opening the form is automatically converted to a
      HAVING clause if there is a GROUP BY clause in the form
      definition.

    - pgintcl versions 2.1.0 and 1.5.0 have been included in the
      distribution.

    - Tclkit for linux on PC is included in the distribution.

    - A GUI install script is included in the distribution (only for
      Linux on PC).


Version 1.0.4. (2004-02-19):

    - Bugs solved:

          o 690: pfm hangs when psql exits

          o 691: The' Run SQL' command history behaves strangely
                 sometimes

          o 692: Printing fails if title contains several words

    - Feature request implemented:

          o 693: Character encoding for sending text to print command


Version 1.0.3. (2004-02-16):

    - Bug 686 solved: Connecting to psql fails in some cases:

      Database name, host or hostaddr, port, user and password
      specified by the user at database open are reused for invoking
      psql.

    - psql is invoked in a different way now: it is invoked when a
      database is opened and it is closed when the database is
      closed. The result is that the state of psql is no longer
      cleared after each command sent to psql.

    - The 'dblist' option is no longer read from the pg_database table
      when the options are reset to their default values. The default
      is now a list containing only the database with the same name as
      the user's logon name.

    - When opening a database, the user can either type the database
      name directly or select it from the 'dblist' option. When the
      database is successfully opened, the name is added to the
      'dblist' option if it was not already in it. The name of the
      last opened database becomes the default database for the next
      'open database'.
      

Version 1.0.2. (2004-02-12)

    - Bug 679 solved: Transaction kept open for too long.

    - Bug 680 solved: Updating a record already deleted by another
      user.

    - Contact information in copy right notices changed.

Version 1.0.1. (2004-02-06)

    - E-mail address in copy right notices changed back to personal
      E-mail because pfm-comments mailing list was out of order.

Version 1.0.0. (2004-02-05)

    - First published version