This is pgin.tcl/NEWS, release notes and change information for pgin.tcl.
The project home page is: http://gborg.postgresql.org/project/pgintcl/
-----------------------------------------------------------------------------

* 2005-04-16 Released beta version 3.0.0

  This is a beta release which adds character set encoding/decoding to fix
  misbehavior of pgin.tcl when used with non-ASCII character sets. Like
  Pgtcl, pgtcl-ng, and libpgtcl, pgin.tcl now sets PostgreSQL
  client_encoding to Unicode, and sends/receives UTF-8 encoded text
  strings to/from PostgreSQL.  Pgin.tcl also recodes COPY data, which
  the libpq-based Tcl interfaces do not correctly handle at this time.

  (Thanks to pfm developer Willem Herremans, who first convinced me that
  encoding was broken in pgin.tcl, then provided the understanding of how
  Tcl and PostgreSQL handle character set conversions and how to get them
  to play nicely together.)

  There are no changes to the pgin.tcl command usage from 2.2.0.

  At this time, it hasn't been decided if there will be two versions of
  pgin.tcl - one for Unicode, and one without - or if only the Unicode
  encoding version will suffice.


* 2004-11-11 Released version 2.2.0

+ New commands: pg_escape_bytea and pg_unescape_bytea, which emulate the
  libpq functions PQescapeBytea() and PQunescapeBytea().  These were
  suggest by J. Levan, with a fast implementation of pg_unescape_bytea
  provided by B. Riefenstahl. Note however that pg_escape_bytea is slow.
  (If possible, use prepared queries in binary mode for bytea types,
  not escape/unescape.) Also note that pg_unescape_bytea only produces
  valid results for data formated by the PostgreSQL backend bytea
  output function; it is not an accurate emulation of PQunescapeBytea().

+ Compatibility fixes for extended error codes.
  The Gborg pgtcl project (Karl Lehenbauer) release 1.4 contains a way to
  fetch extended error field values which is different from the way
  pgin.tcl and pgtclng already did it, but better. They extended
  pg_result -error, where I added a new subcommand pg_result -errorField.
  For compatibility, pg_result -error and pg_result -errorField are now
  identical. If an optional code is supplied, that error field value
  will be returned. Also added variations on the code names that Gborg
  pgtcl uses.

* Performance fix for prepared queries: As found by Nigel J. Andrews,
  prepared queries were slower than they should be. The fix was to
  allow Tcl to buffer up the multiple messages making up a prepared
  query execution; for some reason this avoids a TCP/IP delay.


* 2004-06-01 Released version 2.1.0

+ New command: pg_exec_params, parse/bind/execute extended query protocol.
  This complements pg_exec_prepared, which works with a pre-prepared
  statement. Both are binary safe.

+ pg_exec can take optional arguments which makes it a parameterized
  query like pg_exec_params, but with all text parameters and results.
  (idea from karl's implementation in Gborg pgtcl CVS).

+ New command: pg_quote, to quote and escape a string (from karl's
  implementation in Gborg pgtcl CVS), variation on pg_escape_string (which
  unfortunately was removed from Gborg pgtcl CVS, breaking compatibility).
  pgin.tcl will support both pg_escape_string and pg_quote.

+ Bug fix (GBorg #802) Fix typo in error return if pg_execute script throws
   an error (from n.j.andrews-at-investsystems.co.uk). Testing found
   another problem here; fixed error value returned.


* 2004-02-25 Version 2.0.1 (not released to Gborg)

+ New command option: pg_result $res -cmdStatus (suggested by levanj)
  Returns the command status tag, e.g. "INSERT 10020", for the result $res.


* 2004-02-14 Released version 2.0.0

Changes since beta release 2.0b1:

+ Pgin.tcl can now be installed as a Tcl package.

The package name is 'pgintcl'. (Not 'pgtcl', which is used by libpgtcl.
Since pgintcl is not 100% compatible, I didn't want to use the same name.
Also the version numbers of the two interfaces do not track.)
This means if you install pgin.tcl and pkgIndex.tcl into your package
directories, you can use {package require pgintcl} to load it.


+ Removed feature: Fetch all parameters with {pg_parameter_status $db}

Libpq does not support this, so to be compatible with future libpq-based
versions of the pgtcl interface, this feature was removed. You must supply
pg_parameter_status with a parameter name.


+ Documented incompatibility: pg_exec_prepared mixed text/binary return types

Although the pg_exec_prepared command in pgin.tcl supports mixing text and
binary return types, libpq does not, so libpq based versions of the pgtcl
interface will not work with these queries. This has now been noted in the
documentation, but support for these queries was not removed from pgin.tcl.


+ Incompatible feature change: Dealing with NULL values

Previous versions of pgin.tcl supported a command to set the string to be
returned if a database value was NULL: { pg_configure $db nulls "string" }.
This proved to be very inefficient to implement in the libpq-based version
of the pgtcl interface. It could slow down all queries, just to support a
feature that would be rarely used, so it was removed.  Instead, pgin.tcl
now only provides a way to determine if a database value is NULL:
    pg_result $res -getTuple $n
This returns a list of 1s and 0s indicating if each column in tuple $n
is NULL or not.


+ Command name change: Setting notice handler

In previous versions of pgin.tcl you could set the notice handler with:
    pg_configure $db notice ?command?
A new command is now used instead:
    pg_notice_handler $db ?command?
The pg_configure command is retained for compatibility but should not be
used.


+ Large Object Error Handling 'fixed'

Several of the Large Object calls had undefined or unclear error behavior,
and most were not documented in the PostgreSQL manual. Now pgin.tcl will
throw a Tcl error if any error occurs in any large object calls except for
pg_lo_read and pg_lo_write. Those two were already defined to return -1 on
error, so I left them that way even though I would prefer they threw errors.



* 2003-10-30 Released beta version 2.0b1:

This is a major rewrite for PostgreSQL-7.4 using the new V3 FE/BE protocol.

New commands for new features in the V3 protocol:
  pg_parameter_status       => Get backend-supplied parameter value
  pg_transaction_status     => Get current transaction/error state
  pg_exec_prepared          => Execute prepared SQL statement
  pg_result -errorField     => Show extended error code values
  pg_result -lxAttributes   => Show extended field attribute information

Changed commands: pg_configure no longer ignores the connection handle;
nulls and notice settings are now per-connection, not global to all
connections.

Change (incompatible): COPY FROM/TO must use the pg_copy_read and
pg_copy_write commands, and can not read / write the socket directly.
These calls were introduced in pgin.tcl-1.5.0, but were optional in that
version. Changes to the PostgreSQL protocol now makes it impossible for
pgin.tcl to support COPY with direct reading and writing the socket, so use
of these commands is not required.  See REFERENCE for more information.

The included sample tkpsql program has been updated in this release to be
more schema-aware, while still supporting pre-PostgreSQL-7.3 databases
(untested). Some new special queries were added.


* 2003-06-30 Released version 1.5.0

Change: default user name for connection now checks environment variable
USERNAME (for WindowsNT) after PGUSER, USER, and LOGNAME.

Fix: Tkpsql properly gets initial focus on startup on Windows.

Bug fix: Wrong data was returned by pg_result -getTuple, -list, or -llist
when the query contained duplicate column names. (For example:
       SELECT a.id, a.s, b.s FROM a, b WHERE a.id=b.id;
returns two columns named "s", and pg_result -getTuple incorrectly stored
the value from table "b" column "s" twice.) pgin.tcl now internally stores
values indexed by column number, not name, and will correctly store and
return all the values when those access methods are used.  Note that other
access methods such as pg_result -assign, -tupleArray, pg_select, and
pg_execute use the column name as an array index, so they are not
compatible with queries returning duplicate column names.  Also note you
really should use column name aliases when a query generates duplicate
column names. [gborg bug id #503]

New function: pg_escape_string to escape strings for SQL constants. This is
in the libpgtcl CVS.

Bug fixes for empty query. Previously threw an error, now properly handles
an empty query return and sets status to PGRES_EMPTY_QUERY.

Change: pg_result -cmdTuples returns "", not 0, for any SQL other than
Insert/Update/Delete, this apparently being the correct behavior per libpq.

Add support for overloaded fast-path function calls (same function name but
with different argument types).

Fix: pg_execute now handles empty query, COPY FROM, and COPY TO correctly.

New I/O routines for COPY FROM/TO: pg_copy_read and pg_copy_write. There is
no need to use these yet; you can just read and write from the connection
handle. I put them in for testing compatibility with the future PostgreSQL
FE/BE Protocol Version 3 pgin.tcl, where reading/writing from the connection
handle will not work.


* 2003-02-13 Released version 1.3.9

This is the first public release.

