libpgtcl is a library that implements Tcl commands for front-end
clients to interact with Postgresql 7.2 (and perhaps later)
backends.  See libpgtcl.doc for details.

$Id: README,v 1.4 2002/11/04 17:44:53 karl Exp $

This is pgtcl version 1.4 beta 1

With version 1.4, Pgtcl has been internally overhauled and brought up to
date with the latest Tcl C-interface technology, while maintaining
nearly 100% compatibility with the pg_* Tcl interface provided by Pgtcl 1.3.

Most Tcl programs that used Pgtcl 1.3 will work without modification
under Pgtcl 1.4.

This is a transitional release, as pgtcl is moving out the of core and
into its own distribution.  This means that documentation also must be
collected and included, and a configure script must be created.

INSTALLING

For right now, decompress and untar libpgtcl in your postgres'
src/pgsql/interfaces directory:

    cd ...src/pgsql/interfaces
    mv libpgtcl olibpgtcl
    tar xzvf ...libpgtcl.tar.gz
    cd libpgtcl
    gmake
    gmake install

CHANGES

The main changes are:

    o Support has been dropped for Tcl 7.x.  We now support Tcl 8.0 and above,
      preferably Tcl 8.3 and above.

    o All commands have now been converted to use Tcl 8-style Tcl objects.

        The result is a probable increase in performance in all routines, with
        potentially huge performance increases in pg_select and pg_execute when
        used with complex Tcl code bodies.

    o A new experimental asynchronous interface has been added

	Requests can be issued to the backend without waiting for the
	results, allowing for user interfaces to still work, etc.
	Also, requests can now be cancelled while they're in process.

    o pg_* call arguments are now checked much more rigorously.

	Code previously using atoi() for integer conversions now
	uses Tcl_GetIntFromObj, etc.

	pg_* calls with too many arguments were often accepted without
	complaint.  These now generate standard Tcl "wrong # args"
	messages, etc.

    o Error reporting has been brought into more compliance with the
      Tcl way of doing things.

So some programs that might have been working properly but had certain
syntatically incorrect pg_* commands will now fail until fixed.

pg_result -assign and pg_result -assignbyidx used to return the array
name, which was superfluous because the array name was specified on the
command line.  They now return nothing.  *** POTENTIAL INCOMPATIBILITY ***

OLDER CHANGES

Here are some features that were added back in the 1998 - 1999 timeframe:

1. Postgres connections are a valid Tcl channel, and can therefore
   be manipulated by the interp command (ie. shared or transfered).
   A connection handle's results are transfered/shared with it.
   (Result handles are NOT channels, though it was tempting).  Note
   that a "close $connection" is now functionally identical to a
   "pg_disconnect $connection", although pg_connect must be used
   to create a connection.
   
2. Result handles are changed in format: ${connection}.<result#>.
   This just means for a connection 'pgtcl0', they look like pgtcl0.0,
   pgtcl0.1, etc.  Enforcing this syntax makes it easy to look up
   the real pointer by indexing into an array associated with the
   connection.

3. I/O routines are now defined for the connection handle.  I/O to/from
   the connection is only valid under certain circumstances: following
   the execution of the queries "copy <table> from stdin" or
   "copy <table> to stdout".  In these cases, the result handle obtains
   an intermediate status of "PGRES_COPY_IN" or "PGRES_COPY_OUT".  The
   programmer is then expected to use Tcl gets or read commands on the
   database connection (not the result handle) to extract the copy data.
   For copy outs, read until the standard EOF indication is encountered.
   For copy ins, puts a single terminator (\.).  The statement for this
   would be
	puts $conn "\\."      or       puts $conn {\.}
   In either case (upon detecting the EOF or putting the `\.', the status
   of the result handle will change to "PGRES_COMMAND_OK", and any further
   I/O attempts will cause a Tcl error.
