---------------------------------------------------------------------
NAME
    Postgres95_betcl     - Postgres95 backend Tcl support

COPYRIGHT
    This software is copyrighted by Jan Wieck - Hamburg.

    The  following  terms  apply to all files associated with the
    software unless explicitly disclaimed in individual files.

    The author hereby grants permission  to  use,  copy,  modify,
    distribute,  and  license this software and its documentation
    for any purpose, provided that existing copyright notices are
    retained  in  all  copies  and  that  this notice is included
    verbatim in any distributions. No written agreement, license,
    or  royalty  fee  is required for any of the authorized uses.
    Modifications to this software may be  copyrighted  by  their
    author  and  need  not  follow  the licensing terms described
    here, provided that the new terms are  clearly  indicated  on
    the first page of each file where they apply.

    IN NO EVENT SHALL THE AUTHOR OR DISTRIBUTORS BE LIABLE TO ANY
    PARTY  FOR  DIRECT,   INDIRECT,   SPECIAL,   INCIDENTAL,   OR
    CONSEQUENTIAL   DAMAGES  ARISING  OUT  OF  THE  USE  OF  THIS
    SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN
    IF  THE  AUTHOR  HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH
    DAMAGE.

    THE  AUTHOR  AND  DISTRIBUTORS  SPECIFICALLY   DISCLAIM   ANY
    WARRANTIES,  INCLUDING,  BUT  NOT  LIMITED  TO,  THE  IMPLIED
    WARRANTIES  OF  MERCHANTABILITY,  FITNESS  FOR  A  PARTICULAR
    PURPOSE,  AND NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON
    AN "AS IS" BASIS, AND THE AUTHOR  AND  DISTRIBUTORS  HAVE  NO
    OBLIGATION   TO   PROVIDE   MAINTENANCE,   SUPPORT,  UPDATES,
    ENHANCEMENTS, OR MODIFICATIONS.
---------------------------------------------------------------------

DESCRIPTION

    Postgres95_betcl  is  an  extension to the Postgres95 DBMS to
    support backend functions written in Tcl.

    The Postgres95 DBMS has the capability to  be  extended  with
    user  functions  written  in  C.  Postgres95_betcl is such an
    extension that loads Tcl  code  fragments  into  a  safe  Tcl
    interpreter  inside  the  backend for execution as functions.
    The whole module is table and (per database)  startup  script
    driven. The per database startup scripts can be customized by
    the  DBA  to  enable/disable  features  of  the  module.  The
    features in detail are:

    *   Access  to  stdout  and/or stderr channels of the backend
        process for direct output into the postmaster log.


    *   Capability to force other source fragments to  be  loaded
        immediately.

    *   Capability  to  execute subsequent SQL queries inside the
        Tcl function code.

REQUIREMENTS

    *   Operating system where dynamic loading of the  Postgres95
        DBMS is supported.

    *   Postgres95 DBMS version 1.01 or later (actually tested up
        to version 1.05). There is a bug in the code dealing with
        temporary  result  classes. A source patch is included in
        Postgres95_betcl.

    *   Package Pqatcl  as  the  installation  commands  and  the
        function manager tool use it to access the database.

    *   Tcl7.5p1/Tk4.1p1

WARNING

    This  extension is experimental!!! Functions in general (SQL,
    C and now Tcl) cause the  backend  to  allocate  memory  that
    doesn't get freed if they execute subsequent SQL queries.

    The Function manager tool isn't complete up to now!!!

EXAMPLE

    Suggest we have the following tables:

        create table mytable (
            name char8,
            vkey char8)

        create table valtab (
            key char8,
            val char8)

    mytable.vkey  points to an instance in valtab where it is not
    guaranteed that such an instance exists. If you  now  execute
    the query

        select M.name, V.val from mytable M, valtab V
            where M.vkey = V.key

    you would not get instances of mytable where no corresponding
    record in valtab exists. There's no easy way  for  valtab  to
    fallback to a default value.

    After  installing the betcl support for a database we use the
    function manager tool to install the following Tcl source and
    declare it as function:

        # Tcl backend function get_valtab(char8)
        # Return the value of a key lookup into valtab
        # with fallback to a default key or a static value.
        #
        # Return type is 'char8'
        # Arg key type is 'char8'

        proc get_valtab {key} {

            # Get the value for 'key'
            set n [EXECSQL select single val as value     \
                    from valtab where key = '$key']
            if {$n > 0} return $value

            # Not found - try to get the default
            set n [EXECSQL select single val as value     \
                    from valtab where key = 'DFLKEY']
            if {$n > 0} return $value

            # No default either - return a static value
            return "DFLVAL"
        }

    Now we could execute the following query:

        select name, get_valtab(vkey) from mytable

    Nice, isn't it?


INSTALLATION

    Move  the  archive libbetcl.tar to the home of the Postgres95
    superuser and unpack it there. This  will  produce  the  file
    ./temp_unlink.diff and the source tree ./src/libbetcl/.

    The  diff's  must be applied to the sources of the backend to
    work around a bug in the postgres backend. The bug causes the
    backend  to  try to unlink temporary relations resulting from
    queries inside extension modules  twice.  The  second  unlink
    fails  and  the  backend  enters  an  infinite  loop of error
    recovery where the unlink is tried again.

    Change to the libbetcl source directory and do

        make install

    This causes the files libbetcl.so, BETCL_main_script.tcl  and
    BETCL_safe_script.tcl  to  be  installed in $(LIBDIR) and the
    commands betclinstall and betcluninstall into $(BINDIR).

    The function manager tool isn't complete up  to  now.  So  it
    isn't installed right now. Use it at your own risk.

    Enable  Tcl function support on a database with betclinstall.
    Play around with it.
