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 database.

    Non-cursor commands are simple SQL commands that manipulate 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 initialized 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
Send your comments and bug reports to Christopher Hylands, cxh@argon.berkeley.edu