_________________________________________________________________

NAME
     tclsql - tcl/SQL interface package
_________________________________________________________________

DESCRIPTION
     tclsql is a Tcl (Tool Command  Language)  interface  to  SQL
     (Structured  Query Language).  tclsql is probably INGRES 6.4
     specific, but it could be ported  to  other  SQL  platforms.
     The tclsql package includes two binaries:

     tclsql
          A version of tclTest with SQL extensions.

     sqlwish
          A version of wish with SQL extensions.

     There are three types of commands:  general  commands,  non-
     cursor commands and cursor commands.

          General commands control opening and closing the  data-
          base.

          Non-cursor commands are simple SQL commands that  mani-
          pulate  the  database.   For  example, a non-cursor SQL
          select statement will return results in a 2 dimensional
          Tcl array.

          Cursor commands use a user named SQL cursor  to  access
          the database.  Cursors allow a user to efficiently step
          through a the results of a select statement one row  at
          a time.  For example, a cursor SQL fetch statement will
          return results in a 1 dimensional Tcl array.

GENERAL TCLSQL COMMANDS
     SQLopendb database_name
          Open a database inside tcl

     SQLdbName
          Return the name of the currently open database.

     SQLcommit
          Commit SQL transactions to the database.

     SQLclosedb
          Close the open database inside tcl.

NON-CURSOR TCLSQL COMMANDS
     Non-cursor tclsql commands use an  internal  SQL  Data  Area
     (SQLDA)  structure.  The SQLDA structure is created and ini-
     tialized with the first call to SQLexec or SQLselect*.   The

     SQLDA structure is freed when SQLclosedb is called.

     Note that most non-cursor tclsql commands return values in a
     two dimensional Tcl array.

     SQLexec result_array sql_statement
          Execute an SQL statement inside tcl.

     SQLselect [-noheaders] [-1d] result_array select_statement
          Execute an SQL select statement inside tcl.

     SQLselectRow [-1d] row_number result_array select_statement
          Execute a select statement, get a specific row.

     SQLcolNamesSelect [-1d] result_array select_statement
          Execute a select statement, get the column names.

     SQLcolTypesSelect [-1d] result_array select_statement
          Execute a select statement, get the column types.

     SQLimmediate sql_statement
          Execute and SQL command.

     SQLdelete sql_delete_statement
          Delete a row from a table.

     SQLinsert sql_insert_statement
          Insert a row into a table.

     SQLupdate sql_update_statement
          Update columns in a table.

CURSOR TCLSQL COMMANDS
     If a cursor tclsql command returns values in  a  Tcl  array,
     then  the  default  behavior  is to return a one dimensional
     array.

     SQLdeclareCursor cursor
          Declare an SQL cursor.

     SQLprepareCursor cursor sql_statement
          Setup  an  internal  SQL  statement   for  access  from
          tcl.

     SQLdescribeCursor cursor [result_array] [row_indice]
          Setup   the   SQL   result   area,   get   the   column
          headers.

     SQLopenCursor cursor
          Open an SQL cursor for fetching.

     SQLisACursor cursor

          Return 1 if the cursor exists.

     SQLlistCursors result_array [row_indice]
          Get the names of all the cursors.

     SQLcloseCursor cursor
          Close an SQL cursor.

     SQLfetchCursor cursor result_array [row_indice]
          Fetch a row from an SQL cursor.

     SQLmoreRows
          Return 1 if there are more rows to fetch  from  an  SQL
          cursor.

     SQLcolNamesCursor cursor result_array [row_indice]
          Get the column  names of the query  associated  with  a
          cursor.

     SQLcolTypesCursor cursor result_array [row_indice]
          Get the column  types of the query  associated  with  a
          cursor.

     SQLdeleteCursor table_name cursor
          Delete a row from a table.

FILES IN THE DISTRIBUTION
     INSTALL
          To install tclsql, See the INSTALL file in  the  tclsql
          distribution.

     tests/
          The tests directory of the distribution contains  tests
          for  tclsql.   These  tests rely on the presence of the
          Ingres     tutorial      database,      located      in
          ~ingres/ingres/files/tutorial.   The  contents  of  the
          tables that we  use  are  in  tests/tutorial_db/.   The
          tests also provide examples of tclsql code.

     sqlbr
          A sample tclsql/tk application

     dbdict
          A sample tclsql/tk application

BUGS
     tclsql should follow John Ousterhout's tcl extension  recom-
     mendations, but it does not.

     tclsql clutters the name space with lots of new names.

     tclsql only works with Ingres.  sybtcl and oratcl work  with
     Sybase  and Oracle.  See ftp://harbor.ecn.purdue.edu/pub/tcl
     for more information.

     Send your comments and bug reports to  Christopher  Hylands,
     cxh@eecs.berkeley.edu