This is pgin.tcl/README, describing pgin.tcl: A PostgreSQL interface in Tcl
Last updated for pgin.tcl-2.0b1 on 2003-10-30
The project home page is: http://gborg.postgresql.org/project/pgintcl/
-----------------------------------------------------------------------------

OVERVIEW:

This is a pure-Tcl interface to the PostgreSQL Database backend.  It
implements almost all the commands in libpgtcl, the primary Tcl interface
to PostgreSQL, plus it has some extensions.

I wrote this to be able to use Tcl/Tk database clients on platforms where
the PostgreSQL client library (libpq) and the Tcl interface (libpgtcl) are
not available (or were not available at the time, or were too much trouble
to build).

pgin.tcl uses the Tcl binary data and TCP socket features to communicate
directly with a PostgreSQL database server, using the internal PostgreSQL
frontend/backend protocol. Therefore, pgin.tcl is dependent on the
protocol, rather than being protected from its details as are libpq-based
applications. This version of pgin.tcl uses version 3 of the PostgreSQL
protocol, and only communicates with PostgreSQL-7.4 and higher.


CONTENTS:

  DOCUMENTATION:
           Note: In the zip distribution only, these files
           have a ".txt" extension and MS-DOS line endings.
    README ........... This file
    COPYING .......... The license for pgin.tcl (BSD/Berkeley Open Source)
    NEWS ............. Release information
    Changelog ........ (Not included with this release)
    REFERENCE ........ Reference documentation for programmers using pgin.tcl
    INTERNALS ........ Some information about the innards of pgin.tcl

  SCRIPTS:

    pgin.tcl ......... This is the complete implementation of the interface.
    tkpsql.tcl ....... An example wish script for interactive database querying


FEATURES:

+ Written completely in Tcl 
+ Implements virtually all the standard libpgtcl calls
+ Does large object calls
+ Supports listen/notify
+ Supports replacing the notice handler (extension to libpgtcl)
+ Supports the new pg_execute call
+ Supports PostgreSQL MD5 challenge/response authentication
+ New pg_result -cmdTuples returns the number of tuples affected by an 
  INSERT, DELETE, or UPDATE (feature in PostgreSQL 7.4 libpgtcl)
+ Supports user-defined result value for database NULL (extension to libpgtcl)
+ Implements new pg_result -list, and pg_result -llist (as found in new 
  beta libpgtcl)
+ Implements new pg_escape_string (in beta libpgtcl CVS)
+ Execute prepared statements with pg_exec_prepared, including sending
  and receiving un-escaped binary data (extension)
+ Get PostgreSQL parameters with: pg_parameter_status (extension)
+ Get transaction status with: pg_transaction_status (extension)
+ Access expanded error message fields with: pg_result -errorField
  (extension)
+ Access extended attribute information with: pg_result -lxAttributes
  (extension)


LIMITATIONS and DIFFERENCES:

+ pg_connect supports only the newer "-conninfo" style.
+ Does not support $HOME/.pgpass password file
+ Only talks to v3 backend (PostgreSQL 7.4 or higher required).
+ Uses only TCP/IP sockets (defaults host to localhost, postmaster needs -i)
+ Notification messages are only received while reading query results.
+ Performance isn't great, especially when retrieving large amounts of data.
+ The values of connection handles and result handles are of a different
  format than libpgtcl, but nobody should be relying on these anyway.
+ No pg_on_connection_loss (New at PostgreSQL 7.3)
+ No asynchronous calls (found in beta libpgtcl)
+ Support for COPY FROM/TO is not compatible with libpgtcl - must use
  pg_copy_read and pg_copy_write, no I/O directly to connection handle.
+ With libpgtcl, you can have up to 128 active result structures (so leaks
  can be caught). pgin.tcl has no limits and will not catch result structure
  leaks.


INSTALLATION AND USAGE:

There is no install script. Just copy the script "pgin.tcl" anywhere your
application can access it.  In your application, insert "source .../pgin.tcl"
at the top level, where ... is the directory. This must be run at the top
level, so if you need it inside a proc use uplevel as shown below.

Note: pgin.tcl is not yet a Tcl package, so you can't use [package require]
to load it.

You can use the included "tkpsql.tcl" script to try it out.  This is a
simple interactive GUI program to issue database queries, vaguely like the
Sybase ASA "dbisql" program.  On **ix systems, type "wish tkpsql.tcl" to
start it; under Windows you should be able to double click on it from
Explorer. You need to press F1 or click on the Run button after each query.

If you run tkpsql under "pgtksh" instead of "wish", it won't load pgin.tcl.
You can use this same method in your own scripts to conditionally load
pgin.tcl if needed. Here's how:
    if {[info commands pg_connect] == ""} {
      uplevel #0 {source [file join [file dirname [info script]] pgin.tcl]}
    }
If you run this under pgtclsh or pgtksh, it does nothing, otherwise it loads
pgin.tcl from the same directory as the script.


DOES IT WORK WITH PGACCESS?

This beta release has not been tested with PGAccess. The following applies
to previous versions of pgin.tcl:

Recent versions (CVS and/or snapshots after 2003-03-23) of PGAccess include
pgin.tcl and some changes to PGAccess to support it. You need to use the
"-pgintcl" command-line option to activate it. The next full release of
PGAccess should include pgin.tcl.

More information on PGAccess can be found at http://www.pgaccess.org

PGAccess -pgintcl on Windows supports PostgreSQL MD5 password protocol,
which is not available with the libpgtcl DLLs.
