This is pgin.tcl/INTERNALS, notes on internal implementation of pgin.tcl.
Last updated for pgin.tcl-1.5.0 on 2003-06-28
-----------------------------------------------------------------------------

INTERNAL IMPLEMENTATION NOTES:

This information is provided for maintenance, test, and debugging.

A connection handle is just a Tcl socket channel.

Multiple connections should work OK but have not been extensively tested.
Some variables are global to all connections (for example, what to
substitute for NULL).

Internal procedures, result structures, and other data are stored in a
namespace called "pgtcl".

A result structure is implemented as a variable result$N in the pgtcl
namespace, where N is an integer. (The value of N is stored in pgtcl::rn
and is incremented each time a new result structure is needed.) The result
handle is passed back to the caller as $N, just the integer. The result
structure is an array which stores all the meta-information about the
result as well as the result values.

The result structure array indexes in use are:

  Variables describing the overal result:
    result(conn)      The connection handle (the socket channel)
    result(nattr)     Number of attributes (columns)
    result(ntuple)    Number of tuples (rows)
    result(nmb)       Number of bytes in the data null-map
    result(status)    PostgreSQL status code, e.g. PGRES_TUPLES_OK
    result(error)     Error message if status is PGRES_FATAL_ERROR
    result(complete)  Command completion status, e.g. "INSERT 10101"

  Variables describing the attributes (columns) in the result:
    result(attribs)   A list of attribute names
    result(types)     A list of attribute type OIDs
    result(sizes)     A list of attribute byte lengths or -1 if variable
    result(modifs)    A list of size modifiers for attributes (not used)
       (These are proper Tcl lists containing the data for each attribute
       in order. The size modifiers are returned by the PostgreSQL backend
       but there is no interface in libpgtcl to get this information.)

  Variables storing the query result values:
    result($irow,$icol)  Data for tuple (row) $irow, attribute number $icol.
       (irow goes from 0 to result(ntuples)-1.
        icol goes from 0 to result(nattr)-1.)

(Note: Before pgin.tcl version 1.5.0, attribute names were used to index the
result values. Starting with 1.5.0, attribute numbers are used instead due
to problems with duplicate column names.)

The pg_exec call creates a new result structure. The pg_result call
retrieves information from the result structure and also frees the result
structure with the -clear option.  The result structure innards are also
directly accessed by some other routines, such as pg_select and pg_execute.
All result structures associated with a connection handle are freed when
the connection handle is closed by pg_disconnect.

The entire result of a query is stored before anything else happens (that
is, before pg_exec returns, and before pg_execute and pg_select process the
first row).  This is also true of libpq and libpgtcl, but Tcl is much
slower reading from the backend, and performance will suffer when queries
return large amounts of data. (The main slow-down seems to be when Tcl
needs to read null-terminated data from the socket, and has to get it one
character at a time.)

-----------------------------------------------------------------------------
NOTIFICATIONS

An array pgtcl::notify keeps track of notifications you want. The array is
indexed as pgtcl::notify(connection,name) where connection is the
connection handle (socket name) and name is the parameter used in
pg_listen. The value of an array element is the command to execute on
notification. Note that no data is passed - just the fact that the
notification occurred.

-----------------------------------------------------------------------------
LARGE OBJECTS

The large object calls are implemented using the PostgreSQL "fast-path"
function call interface (same as libpq). See the next section for more
information.

The pg_lo_creat command takes a mode argument. According to the PostgreSQL
libpq documentation, lo_creat should take "INV_READ", "INV_WRITE", or
"INV_READ|INV_WRITE".  (pgin.tcl accepts "r", "w", and "rw" as equivalent
to those respectively, but this is not compatible with libpgtcl.) It isn't
clear why you would ever create a large object with other than
"INV_READ|INV_WRITE".

The pg_lo_open command also takes a mode argument. According to the
PostgreSQL libpq documentation, lo_open takes the same mode values as
lo_creat.  But in libpgtcl the pg_lo_open command takes "r", "w", or "rw"
for the mode, for some reason. pgin.tcl accepts either form for mode,
but to be compatible with libpgtcl you should use "r", "w", or "rw"
with pg_lo_open instead of INV_READ, INV_WRITE, or INV_READ|INV_WRITE.


-----------------------------------------------------------------------------
FAST-PATH FUNCTION CALLS

Access to the PostgreSQL "Fast-path function call" interface is available
in pgin.tcl. This was written to implement the large object calls, and
general use is discouraged. See the libpq documentation for more details on
what this interface is and how to use it.

Internally, backend functions are called by their PostgreSQL OID, but
pgin.tcl handles the mapping of function name to OID for you.  The
fast-path function interface in pgin.tcl uses an array pgtcl::fnoids to
cache object IDs of the PostgreSQL functions.  One instance of this array
is shared among all connections, under the assumption that these OIDs are
common to all databases. (It is possible that if you have simultaneous
connections to multiple database servers running different versions of
PostgreSQL this could break.) The index to pgtcl::fnoids is the name
of the function, or the function plus argument type list, as supplied
to the pgin.tcl fast-path function call commands. The value of each
array index is the OID of the function.

PostgreSQL supports overloaded functions (same name, different number
and/or argument types). You can call overloaded functions with pgin.tcl by
specifying the argument type list after the function name. See examples
below. You must specify the argument list exactly like psql "\df" does - as
a list of correct type names, separated by a single comma and space. There
is currently no provision to distinguish functions by their return type. It
doesn't seem like there are any PostgreSQL functions which differ only by
return type.

If you supply the wrong number of arguments to the backend fast-path
function, the backend and front-end will lose synchronization and the
channel will be closed. This is true about libpq as well.  There may be
other errors which cause a disconnect.  Consider this a hint not to use
this interface casually.


Commands:

   pg_callfn $db "fname" result "arginfo" arg...

     Call a PostgreSQL backend function and store the result.
     Returns the size of the result in bytes.

     Parameters:

       $db is the connection handle.

       "fname" is the PostgreSQL function name. This is either a simple
       name, like "encode", or a name followed by a parenthesized
       argument type list, like "like(text, text)". The second form
       is needed to specify which of several overloaded functions you want
       to call.

       "result" is the name of a variable where the PostgreSQL backend
       function returned value is to be stored. The number of bytes
       stored in "result" is returned as the value of pg_callfn.

       "arginfo" is a list of argument descriptors. Each list element is
       one of the following:
           I    An integer32 argument is expected.
           S    A Tcl string argument is expected. The length of the
                string is used (remember Tcl strings can contain null bytes).
           n (an integer > 0)
                A Tcl string argument is expected, and exactly this many
                bytes of the string argument are passed (padding with null
                bytes if needed).

       arg...   Zero or more arguments to the PostgreSQL function follow.
                The number of arguments must match the number of elements
                in the "arginfo" list. The values are passed to the backend
                function according to the corresponding descriptor in
                "arginfo".

  For PostgreSQL backend functions which return a single integer32 argument,
  the following simplified interface is available:

   pg_callfn_int $db "fname" "arginfo" arg...
      
       The db, fname, arginfo, and other arguments are the same as
       for pg_callfn. The return value from pg_callfn_int is the
       integer32 value returned by the PostgreSQL backend function.

Examples:
    Note: These examples demonstrate the command, but in both of these
    cases you would be better off using an SQL query instead.

       set n [pg_callfn $db version result ""]
    This calls the backend function version() and stores the return
    value in $result and the result length in $n. 

       pg_callfn $db encode result {S S} $str base64
    This calls the backend function encode($str, "base64") with 2
    string arguments and stores the result in $result.

       pg_callfn_int $db length(text) S "This is a test"
    This calls the backend function length("This is a test"). Because
    there are multiple functions called length(), the argument type
    list "(text)" must be given after the function name. The length
    of the string (14) is returned by the function.

-----------------------------------------------------------------------------
MD5 AUTHENTICATION

MD5 authentication was added at PostgreSQL-7.2. This is a
challenge/response protocol which avoids having clear-text passwords passed
over the network. To activate this, the PostgreSQL administrator puts "md5"
in the pg_hba.conf file instead of "password". Pgin.tcl supports this
transparently; that is, if the backend requests MD5 authentication during
the connection, pg_connect will use this protocol. The MD5 implementation
was coded by the original author of pgin.tcl. It does not use the tcllib
implementation, which is significantly faster but much more complex.

-----------------------------------------------------------------------------
