src/interfaces/libpgtcl/README

   1 libpgtcl is a library that implements Tcl commands for front-end
   2 clients to interact with the Postgresql 6.3 (and perhaps later)
   3 backends.  See libpgtcl.doc for details.
   4
   5 For an example of how to build a new tclsh to use libpgtcl, see the
   6 directory ../bin/pgtclsh
   7
   8 Note this version is modified by NeoSoft to have the following additional
   9 features:
  10
  11 1. Postgres connections are a valid Tcl channel, and can therefore
  12    be manipulated by the interp command (ie. shared or transfered).
  13    A connection handle's results are transfered/shared with it.
  14    (Result handles are NOT channels, though it was tempting).  Note
  15    that a "close $connection" is now functionally identical to a
  16    "pg_disconnect $connection", although pg_connect must be used
  17    to create a connection.
  18
  19 2. Result handles are changed in format: ${connection}.<result#>.
  20    This just means for a connection 'pgtcl0', they look like pgtcl0.0,
  21    pgtcl0.1, etc.  Enforcing this syntax makes it easy to look up
  22    the real pointer by indexing into an array associated with the
  23    connection.
  24
  25 3. I/O routines are now defined for the connection handle.  I/O to/from
  26    the connection is only valid under certain circumstances: following
  27    the execution of the queries "copy <table> from stdin" or
  28    "copy <table> to stdout".  In these cases, the result handle obtains
  29    an intermediate status of "PGRES_COPY_IN" or "PGRES_COPY_OUT".  The
  30    programmer is then expected to use Tcl gets or read commands on the
  31    database connection (not the result handle) to extract the copy data.
  32    For copy outs, read until the standard EOF indication is encountered.
  33    For copy ins, puts a single terminator (\.).  The statement for this
  34    would be
  35         puts $conn "\\."      or       puts $conn {\.}
  36    In either case (upon detecting the EOF or putting the `\.', the status
  37    of the result handle will change to "PGRES_COMMAND_OK", and any further
  38    I/O attempts will cause a Tcl error.