From 9b0d0a8bc5f5c1d0cea55db7f4fc25fb4636aaec Mon Sep 17 00:00:00 2001 From: drh Date: Sat, 30 Sep 2000 22:46:05 +0000 Subject: [PATCH] Documenting the TCL interface (CVS 149) FossilOrigin-Name: 7e0bacedf928095b29e7166eacd2356e8169d6dd --- Makefile.in | 6 +- VERSION | 2 +- manifest | 21 ++--- manifest.uuid | 2 +- src/tclsqlite.c | 5 +- www/changes.tcl | 4 + www/index.tcl | 5 +- www/tclsqlite.tcl | 206 ++++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 234 insertions(+), 17 deletions(-) create mode 100644 www/tclsqlite.tcl diff --git a/Makefile.in b/Makefile.in index 6d28a33662..37c7dab7a6 100644 --- a/Makefile.in +++ b/Makefile.in @@ -213,6 +213,9 @@ crosscompile.html: $(TOP)/www/crosscompile.tcl mingw.html: $(TOP)/www/mingw.tcl tclsh $(TOP)/www/mingw.tcl >mingw.html +tclsqlite.html: $(TOP)/www/tclsqlite.tcl + tclsh $(TOP)/www/tclsqlite.tcl >tclsqlite.html + # Files to be published on the website. # @@ -229,7 +232,8 @@ PUBLISH = \ vdbe.html \ c_interface.html \ crosscompile.html \ - mingw.html + mingw.html \ + tclsqlite.html website: $(PUBLISH) diff --git a/VERSION b/VERSION index 238d6e882a..b0f3d96f87 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.0.7 +1.0.8 diff --git a/manifest b/manifest index 85980a3070..fbd74ca813 100644 --- a/manifest +++ b/manifest @@ -1,9 +1,9 @@ -C Fix\sa\sproblem\swith\sthe\sconfigure\sscript\s(CVS\s1703) -D 2000-09-29T15:15:53 +C Documenting\sthe\sTCL\sinterface\s(CVS\s149) +D 2000-09-30T22:46:06 F COPYRIGHT 74a8a6531a42e124df07ab5599aad63870fa0bd4 -F Makefile.in 39f684ee06a661157793f01cce98d43026fc2c06 +F Makefile.in 2fe404a488607712e569d69974d7929bae06ad1e F README 51f6a4e7408b34afa5bc1c0485f61b6a4efb6958 -F VERSION c4ef5804e5824ee814fdd368026a5d21314bdbed +F VERSION c2e64b60cb74d152b5b5a0822f0e8cb673c928da F configure 3dc1edb9dcf60215e31ff72b447935ab62211442 x F configure.in d892ca33db7e88a055519ce2f36dcb11020e8fff F doc/lemon.html e233a3e97a779c7a87e1bc4528c664a58e49dd47 @@ -21,7 +21,7 @@ F src/shell.tcl 27ecbd63dd88396ad16d81ab44f73e6c0ea9d20e F src/sqlite.h.in 1e0e4495172f752935ad534871ff726ae509d2f0 F src/sqliteInt.h b65fdecac7281aafb4c9ff3e79ea1b5546478385 F src/table.c 12f0165b47178b54a675d25ed373ee7e798d6ff0 -F src/tclsqlite.c a08428125ba2429b71764d5365653771ded4a2b8 +F src/tclsqlite.c 7ccccae67fb36ed60ec98282953bf5dad0f9c16f F src/tokenize.c 097bec5843d4a0fb4509e036fee93bac080c5e73 F src/update.c 51b9ef7434b15e31096155da920302e9db0d27fc F src/util.c 782f87af3c48c898631a2d5b7074437c899f6f13 @@ -63,16 +63,17 @@ F www/arch.fig 4f246003b7da23bd63b8b0af0618afb4ee3055c8 F www/arch.png 8dae0766d42ed3de9ed013c1341a5792bcf633e6 F www/arch.tcl a40380c1fe0080c43e6cc5c20ed70731511b06be F www/c_interface.tcl 73b5c1354e250a12ceaaccc376611351c867146a -F www/changes.tcl e4fb0a308d62309dba40527ad3fddba825745e4c +F www/changes.tcl d62039b5387cc0871ec1bd3b15065a7c7d421cb1 F www/crosscompile.tcl 19734ce7f18b16ff2ed8479412abf8aca56e1dcc F www/fileformat.tcl cfb7fba80b7275555281ba2f256c00734bcdd1c9 -F www/index.tcl 2f5cc070b8fa8c3fc2f71bba4e6b7877d528fbde +F www/index.tcl b19418d506f90968deef972bf1b427d98bdf13e0 F www/lang.tcl 9192e114b19987e630a41e879585b87006eb84a1 F www/mingw.tcl fc5f4ba9d336b6e8c97347cc6496d6162461ef60 F www/opcode.tcl cb3a1abf8b7b9be9f3a228d097d6bf8b742c2b6f F www/sqlite.tcl cb0d23d8f061a80543928755ec7775da6e4f362f +F www/tclsqlite.tcl 21ecd82eaea3ce3d08593a9a2d2bfdb3c1f7b547 F www/vdbe.tcl bcbfc33bcdd0ebad95eab31286adb9e1bc289520 -P 2aeb82db3ef6fc13eafa4fcf614e8f1dfd247abf -R 374764ea3793b387c2fde1f92050f82f +P ed5f5404ad804aec21ad971d59af834929381b5b +R 3e751dc5aea8f130e00211562c95fd7d U drh -Z 42aab9ea0ff2eec024d3c6a658fe82fd +Z 7e17d7124dec057be794cd1546e45e70 diff --git a/manifest.uuid b/manifest.uuid index df24a18168..ab848b13dd 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -ed5f5404ad804aec21ad971d59af834929381b5b \ No newline at end of file +7e0bacedf928095b29e7166eacd2356e8169d6dd \ No newline at end of file diff --git a/src/tclsqlite.c b/src/tclsqlite.c index b4bdd88938..0399b3f198 100644 --- a/src/tclsqlite.c +++ b/src/tclsqlite.c @@ -23,7 +23,7 @@ ************************************************************************* ** A TCL Interface to SQLite ** -** $Id: tclsqlite.c,v 1.9 2000/09/21 13:01:37 drh Exp $ +** $Id: tclsqlite.c,v 1.10 2000/09/30 22:46:07 drh Exp $ */ #ifndef NO_TCL /* Omit this whole file if TCL is unavailable */ @@ -68,6 +68,7 @@ static int DbEvalCallback( int i, rc; if( cbData->zArray[0] ){ if( cbData->once ){ + Tcl_SetVar2(cbData->interp, cbData->zArray, "*", "", 0); for(i=0; iinterp, cbData->zArray, "*", azN[i], TCL_LIST_ELEMENT|TCL_APPEND_VALUE); @@ -87,7 +88,7 @@ static int DbEvalCallback( } cbData->once = 0; rc = Tcl_EvalObj(cbData->interp, cbData->pCode); - return rc; + return rc!=TCL_OK && rc!=TCL_CONTINUE; } /* diff --git a/www/changes.tcl b/www/changes.tcl index 5b6e9090bd..f2028309e9 100644 --- a/www/changes.tcl +++ b/www/changes.tcl @@ -17,6 +17,10 @@ proc chng {date desc} { puts "

    $desc

" } +chng {2000 Sep 30 (1.0.8)} { +
  • Begin writing documentation on the TCL interface.
    • +} + chng {2000 Sep 29 (Not Released)} {
  • Added the sqlite_get_table() API
  • Updated the documtation for due to the above change.
    • diff --git a/www/index.tcl b/www/index.tcl index 2295a00087..39749ef123 100644 --- a/www/index.tcl +++ b/www/index.tcl @@ -1,7 +1,7 @@ # # Run this TCL script to generate HTML for the index.html file. # -set rcsid {$Id: index.tcl,v 1.28 2000/08/18 09:58:52 drh Exp $} +set rcsid {$Id: index.tcl,v 1.29 2000/09/30 22:46:07 drh Exp $} puts { SQLite: An SQL Database Library Built Atop GDBM @@ -40,7 +40,7 @@ an example of how to use the SQLite library.

  • Very simple C/C++ interface requires the use of only three functions and one opaque structure.
    • -
  • A Tcl interface is +
  • A Tcl interface is included.
  • Command-line access program sqlite uses the GNU @@ -100,6 +100,7 @@ on tables where many entries in the table have the same index key.

    command-line utility.
  • The SQL Language subset understood by SQLite.
  • The C/C++ Interface.
    • +
  • The Tcl Interface.
  • The file format used by SQLite databases.
  • The Architecture of the SQLite Library describes how the library is put together.
    • diff --git a/www/tclsqlite.tcl b/www/tclsqlite.tcl new file mode 100644 index 0000000000..5c575b48f9 --- /dev/null +++ b/www/tclsqlite.tcl @@ -0,0 +1,206 @@ +# +# Run this Tcl script to generate the tclsqlite.html file. +# +set rcsid {$Id: tclsqlite.tcl,v 1.1 2000/09/30 22:46:07 drh Exp $} + +puts { + + The Tcl interface to the SQLite library + + +

    +The Tcl interface to the SQLite library +

    } +puts "

    +(This page was last modified on [lrange $rcsid 3 4] GMT) +

    " + +puts { +

    The SQLite library is designed to be very easy to use from +a Tcl or Tcl/Tk script. This document gives an overview of the Tcl +programming interface.

    + +

    The API

    + +

    The interface to the SQLite library consists of single +tcl command named sqlite. Because there is only this +one interface command, the interface is not placed in a separate +namespace.

    + +

    The sqlite command is used as follows:

    + +
    +sqlite  dbcmd  database-directory-name +
    + +

    +The sqlite command opens the SQLite database located in the +directory named by the second argument. If the database or directory +does not exist, it is created. The sqlite command +also creates a new Tcl +command to control the database. The name of the new Tcl command +is given by the first argument. This approach is similar to the +way widgets are created in Tk. +

    + +

    +Once an SQLite database is open, it can be controlled using +methods of the dbcmd. There are currently 5 methods +defined:

    + +

    +

    +

    + +

    We will explain all of these methods, though not in that order. +We will be begin with the "close" method.

    + +

    The "close" method

    + +

    +As its name suggests, the "close" method to an SQLite database just +closes the database. This has the side-effect of deleting the +dbcmd Tcl command. Here is an example of opening and then +immediately closing a database: +

    + +
    +sqlite db1 ./testdb
    +db1 close     +
    + +

    +If you delete the dbcmd directly, that has the same effect +as invoking the "close" method. So the following code is equivalent +to the previous:

    + +
    +sqlite db1 ./testdb
    +rename db1 {}     +
    + +

    The "eval" method

    + +

    +The most useful dbcmd method is "eval". The eval method is used +to execute SQL on the database. The syntax of the eval method looks +like this:

    + +
    +dbcmd  eval  sql +  ?array-name  script? +
    + +

    +The job of the eval method is to execute the SQL statement or statements +given in the second argument. For example, to create a new table in +a database, you can do this:

    + +
    +sqlite db1 ./testdb
    +db1 eval {CREATE TABLE t1(a int, b text)}     +
    + +

    The above code creates a new table named t1 with columns +a and b. What could be simplier?

    + +

    Query results are returned as a list of column values. If a +query requests 2 columns and there are 3 rows matching the query, +then the returned list will contain 6 elements. For example:

    + +
    +db1 eval {INSERT INTO t1 VALUES(1,'hello')}
    +db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}
    +db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}
    +set x [db1 eval {SELECT * FROM t1 ORDER BY a}]     +
    + +

    The variable $x is set by the above code to

    + +
    +1 hello 2 goodbye 3 howdy! +
    + +

    You can also process the results of a query one row at a time +by specifying the name of an array variable and a script following +the SQL code. For each row of the query result, the value of each +column will be inserted into the array variable and the script will +be executed. For instance:

    + +
    +db1 eval {SELECT * FROM t1 ORDER BY a} values {
    +    parray values
    +    puts ""
    +}     +
    + +

    This last code will give the following output:

    + +
    +values(*) = a b
    +values(a) = 1
    +values(b) = hello

    + +values(*) = a b
    +values(a) = 2
    +values(b) = goodbye

    + +values(*) = a b
    +values(a) = 3
    +values(b) = howdy!     +

    + +

    +For each column in a row of the result, the name of that column +is used as an index in to array. The value of the column is stored +in the corresponding array entry. The special array index * is +used to store a list of column names in the order that they appear. +

    + +

    +If the array variable name is the empty string, then the value of +each column is stored in a variable with the same name as the column +itself. For example: +

    + +
    +db1 eval {SELECT * FROM t1 ORDER BY a} {} {
    +    puts "a=$a b=$b"
    +}     +
    + +

    +From this we get the following output +

    + +
    +a=1 b=hello
    +a=2 b=goodbye
    +a=3 b=howdy!     +
    + +

    The "complete" method

    +TBD + +

    The "timeout" method

    +TBD + +

    The "busy" method

    +TBD + + +} + +puts { +

    +

    +Back to the SQLite Home Page +

    + +}