/ Check-in [7e0baced]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Documenting the TCL interface (CVS 149)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:7e0bacedf928095b29e7166eacd2356e8169d6dd
User & Date: drh 2000-09-30 22:46:06
Context
2000-09-30
23:00
Version 1.0.8 (CVS 494) check-in: 384909e5 user: drh tags: trunk
22:46
Documenting the TCL interface (CVS 149) check-in: 7e0baced user: drh tags: trunk
2000-09-29
15:15
Fix a problem with the configure script (CVS 1703) check-in: ed5f5404 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to Makefile.in.

   209    209   
   210    210   crosscompile.html:	$(TOP)/www/crosscompile.tcl
   211    211   	tclsh $(TOP)/www/crosscompile.tcl >crosscompile.html
   212    212   
   213    213   mingw.html:	$(TOP)/www/mingw.tcl
   214    214   	tclsh $(TOP)/www/mingw.tcl >mingw.html
   215    215   
          216  +tclsqlite.html:	$(TOP)/www/tclsqlite.tcl
          217  +	tclsh $(TOP)/www/tclsqlite.tcl >tclsqlite.html
          218  +
   216    219   
   217    220   # Files to be published on the website.
   218    221   #
   219    222   PUBLISH = \
   220    223     sqlite.tar.gz \
   221    224     index.html \
   222    225     sqlite.html \
................................................................................
   225    228     lang.html \
   226    229     opcode.html \
   227    230     arch.html \
   228    231     arch.png \
   229    232     vdbe.html \
   230    233     c_interface.html \
   231    234     crosscompile.html \
   232         -  mingw.html
          235  +  mingw.html \
          236  +  tclsqlite.html
   233    237   
   234    238   website:	$(PUBLISH)
   235    239   
   236    240   publish:	$(PUBLISH)
   237    241   	chmod 0644 $(PUBLISH)
   238    242   	scp $(PUBLISH) hwaci@oak.he.net:public_html/sw/sqlite
   239    243   

Changes to VERSION.

     1         -1.0.7
            1  +1.0.8

Changes to src/tclsqlite.c.

    19     19   ** Author contact information:
    20     20   **   drh@hwaci.com
    21     21   **   http://www.hwaci.com/drh/
    22     22   **
    23     23   *************************************************************************
    24     24   ** A TCL Interface to SQLite
    25     25   **
    26         -** $Id: tclsqlite.c,v 1.9 2000/09/21 13:01:37 drh Exp $
           26  +** $Id: tclsqlite.c,v 1.10 2000/09/30 22:46:07 drh Exp $
    27     27   */
    28     28   #ifndef NO_TCL     /* Omit this whole file if TCL is unavailable */
    29     29   
    30     30   #include "sqlite.h"
    31     31   #include <tcl.h>
    32     32   #include <stdlib.h>
    33     33   #include <string.h>
................................................................................
    64     64     char ** azCol,         /* Data for each column */
    65     65     char ** azN            /* Name for each column */
    66     66   ){
    67     67     CallbackData *cbData = (CallbackData*)clientData;
    68     68     int i, rc;
    69     69     if( cbData->zArray[0] ){
    70     70       if( cbData->once ){
           71  +      Tcl_SetVar2(cbData->interp, cbData->zArray, "*", "", 0);
    71     72         for(i=0; i<nCol; i++){
    72     73           Tcl_SetVar2(cbData->interp, cbData->zArray, "*", azN[i],
    73     74              TCL_LIST_ELEMENT|TCL_APPEND_VALUE);
    74     75         }
    75     76       }
    76     77       for(i=0; i<nCol; i++){
    77     78         char *z = azCol[i];
................................................................................
    83     84         char *z = azCol[i];
    84     85         if( z==0 ) z = "";
    85     86         Tcl_SetVar(cbData->interp, azN[i], z, 0);
    86     87       }
    87     88     }
    88     89     cbData->once = 0;
    89     90     rc = Tcl_EvalObj(cbData->interp, cbData->pCode);
    90         -  return rc;
           91  +  return rc!=TCL_OK && rc!=TCL_CONTINUE;
    91     92   }
    92     93   
    93     94   /*
    94     95   ** This is an alternative callback for database queries.  Instead
    95     96   ** of invoking a TCL script to handle the result, this callback just
    96     97   ** appends each column of the result to a list.  After the query
    97     98   ** is complete, the list is returned.

Changes to www/changes.tcl.

    12     12   }
    13     13   
    14     14   
    15     15   proc chng {date desc} {
    16     16     puts "<DT><B>$date</B></DT>"
    17     17     puts "<DD><P><UL>$desc</UL></P></DD>"
    18     18   }
           19  +
           20  +chng {2000 Sep 30 (1.0.8)} {
           21  +<li>Begin writing documentation on the TCL interface.</li>
           22  +}
    19     23   
    20     24   chng {2000 Sep 29 (Not Released)} {
    21     25   <li>Added the <b>sqlite_get_table()</b> API</li>
    22     26   <li>Updated the documtation for due to the above change.</li>
    23     27   <li>Modified the <b>sqlite</b> shell to make use of the new
    24     28       sqlite_get_table() API in order to print a list of tables
    25     29       in multiple columns, similar to the way "ls" prints filenames.</li>

Changes to www/index.tcl.

     1      1   #
     2      2   # Run this TCL script to generate HTML for the index.html file.
     3      3   #
     4         -set rcsid {$Id: index.tcl,v 1.28 2000/08/18 09:58:52 drh Exp $}
            4  +set rcsid {$Id: index.tcl,v 1.29 2000/09/30 22:46:07 drh Exp $}
     5      5   
     6      6   puts {<html>
     7      7   <head><title>SQLite: An SQL Database Library Built Atop GDBM</title></head>
     8      8   <body bgcolor=white>
     9      9   <h1 align=center>SQLite: An SQL Database Library Built Atop
    10     10   <a href="http://www.gnu.org/software/gdbm/gdbm.html">GDBM</a></h1>
    11     11   <p align=center>}
................................................................................
    36     36   <li>A database is just a directory of GDBM files.</li>
    37     37   <li>Unlimited length records.</li>
    38     38   <li>Import and export data from 
    39     39   <a href="http://www.postgresql.org/">PostgreSQL</a>.</li>
    40     40   <li>Very simple 
    41     41   <a href="c_interface.html">C/C++ interface</a> requires the use of only
    42     42   three functions and one opaque structure.</li>
    43         -<li>A <a href="http://dev.scriptics.com/">Tcl</a> interface is
           43  +<li>A <a href="tclsqlite.html">Tcl</a> interface is
    44     44   included.</li>
    45     45   <li>Command-line access program <a href="sqlite.html">sqlite</a> uses
    46     46   the <a href="http://www.google.com/search?q=gnu+readline+library">GNU
    47     47   Readline library</a></li>
    48     48   <li>A Tcl-based test suite provides near 100% code coverage</li>
    49     49   <li>7500+ lines of C code.  No external dependencies other than GDBM.</li>
    50     50   <li>Built and tested under Linux, HPUX, and WinNT.</li>
................................................................................
    96     96   <p>The following documentation is currently available:</p>
    97     97   
    98     98   <p><ul>
    99     99   <li>Information on the <a href="sqlite.html">sqlite</a>
   100    100       command-line utility.</li>
   101    101   <li>The <a href="lang.html">SQL Language</a> subset understood by SQLite.</li>
   102    102   <li>The <a href="c_interface.html">C/C++ Interface</a>.</li>
          103  +<li>The <a href="tclsqlite.html">Tcl Interface</a>.</li>
   103    104   <li>The <a href="fileformat.html">file format</a> used by SQLite databases.</li>
   104    105   <li>The <a href="arch.html">Architecture of the SQLite Library</a> describes
   105    106       how the library is put together.</li>
   106    107   <li>A description of the <a href="opcode.html">virtual machine</a> that
   107    108       SQLite uses to access the database.</li>
   108    109   <li>Instructions for building 
   109    110       <a href="crosscompile.html">SQLite for Win98/NT</a> using the

Added www/tclsqlite.tcl.

            1  +#
            2  +# Run this Tcl script to generate the tclsqlite.html file.
            3  +#
            4  +set rcsid {$Id: tclsqlite.tcl,v 1.1 2000/09/30 22:46:07 drh Exp $}
            5  +
            6  +puts {<html>
            7  +<head>
            8  +  <title>The Tcl interface to the SQLite library</title>
            9  +</head>
           10  +<body bgcolor=white>
           11  +<h1 align=center>
           12  +The Tcl interface to the SQLite library
           13  +</h1>}
           14  +puts "<p align=center>
           15  +(This page was last modified on [lrange $rcsid 3 4] GMT)
           16  +</p>"
           17  +
           18  +puts {
           19  +<p>The SQLite library is designed to be very easy to use from
           20  +a Tcl or Tcl/Tk script.  This document gives an overview of the Tcl
           21  +programming interface.</p>
           22  +
           23  +<h2>The API</h2>
           24  +
           25  +<p>The interface to the SQLite library consists of single
           26  +tcl command named <b>sqlite</b>.  Because there is only this
           27  +one interface command, the interface is not placed in a separate
           28  +namespace.</p>
           29  +
           30  +<p>The <b>sqlite</b> command is used as follows:</p>
           31  +
           32  +<blockquote>
           33  +<b>sqlite</b>&nbsp;&nbsp;<i>dbcmd&nbsp;&nbsp;database-directory-name</i>
           34  +</blockquote>
           35  +
           36  +<p>
           37  +The <b>sqlite</b> command opens the SQLite database located in the
           38  +directory named by the second argument.  If the database or directory
           39  +does not exist, it is created.  The <b>sqlite</b> command 
           40  +also creates a new Tcl
           41  +command to control the database.  The name of the new Tcl command
           42  +is given by the first argument.  This approach is similar to the
           43  +way widgets are created in Tk.
           44  +</p>
           45  +
           46  +<p>
           47  +Once an SQLite database is open, it can be controlled using 
           48  +methods of the <i>dbcmd</i>.  There are currently 5 methods
           49  +defined:</p>
           50  +
           51  +<p>
           52  +<ul>
           53  +<li> busy
           54  +<li> close
           55  +<li> complete
           56  +<li> eval
           57  +<li> timeout
           58  +</ul>
           59  +</p>
           60  +
           61  +<p>We will explain all of these methods, though not in that order.
           62  +We will be begin with the "close" method.</p>
           63  +
           64  +<h2>The "close" method</h2>
           65  +
           66  +<p>
           67  +As its name suggests, the "close" method to an SQLite database just
           68  +closes the database.  This has the side-effect of deleting the
           69  +<i>dbcmd</i> Tcl command.  Here is an example of opening and then
           70  +immediately closing a database:
           71  +</p>
           72  +
           73  +<blockquote>
           74  +<b>sqlite db1 ./testdb<br>
           75  +db1 close</b>
           76  +</blockquote>
           77  +
           78  +<p>
           79  +If you delete the <i>dbcmd</i> directly, that has the same effect
           80  +as invoking the "close" method.  So the following code is equivalent
           81  +to the previous:</p>
           82  +
           83  +<blockquote>
           84  +<b>sqlite db1 ./testdb<br>
           85  +rename db1 {}</b>
           86  +</blockquote>
           87  +
           88  +<h2>The "eval" method</h2>
           89  +
           90  +<p>
           91  +The most useful <i>dbcmd</i> method is "eval".  The eval method is used
           92  +to execute SQL on the database.  The syntax of the eval method looks
           93  +like this:</p>
           94  +
           95  +<blockquote>
           96  +<i>dbcmd</i>&nbsp;&nbsp;<b>eval</b>&nbsp;&nbsp;<i>sql</i>
           97  +&nbsp;&nbsp;?<i>array-name&nbsp;&nbsp;script</i>?
           98  +</blockquote>
           99  +
          100  +<p>
          101  +The job of the eval method is to execute the SQL statement or statements
          102  +given in the second argument.  For example, to create a new table in
          103  +a database, you can do this:</p>
          104  +
          105  +<blockquote>
          106  +<b>sqlite db1 ./testdb<br>
          107  +db1 eval {CREATE TABLE t1(a int, b text)}</b>
          108  +</blockquote>
          109  +
          110  +<p>The above code creates a new table named <b>t1</b> with columns
          111  +<b>a</b> and <b>b</b>.  What could be simplier?</p>
          112  +
          113  +<p>Query results are returned as a list of column values.  If a
          114  +query requests 2 columns and there are 3 rows matching the query,
          115  +then the returned list will contain 6 elements.  For example:</p>
          116  +
          117  +<blockquote>
          118  +<b>db1 eval {INSERT INTO t1 VALUES(1,'hello')}<br>
          119  +db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}<br>
          120  +db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}<br>
          121  +set x [db1 eval {SELECT * FROM t1 ORDER BY a}]</b>
          122  +</blockquote>
          123  +
          124  +<p>The variable <b>$x</b> is set by the above code to</p>
          125  +
          126  +<blockquote>
          127  +<b>1 hello 2 goodbye 3 howdy!</b>
          128  +</blockquote>
          129  +
          130  +<p>You can also process the results of a query one row at a time
          131  +by specifying the name of an array variable and a script following
          132  +the SQL code.  For each row of the query result, the value of each
          133  +column will be inserted into the array variable and the script will
          134  +be executed.  For instance:</p>
          135  +
          136  +<blockquote>
          137  +<b>db1 eval {SELECT * FROM t1 ORDER BY a} values {<br>
          138  +&nbsp;&nbsp;&nbsp;&nbsp;parray values<br>
          139  +&nbsp;&nbsp;&nbsp;&nbsp;puts ""<br>
          140  +}</b>
          141  +</blockquote>
          142  +
          143  +<p>This last code will give the following output:</p>
          144  +
          145  +<blockquote><b>
          146  +values(*) = a b<br>
          147  +values(a) = 1<br>
          148  +values(b) = hello<p>
          149  +
          150  +values(*) = a b<br>
          151  +values(a) = 2<br>
          152  +values(b) = goodbye<p>
          153  +
          154  +values(*) = a b<br>
          155  +values(a) = 3<br>
          156  +values(b) = howdy!</b>
          157  +</blockquote>
          158  +
          159  +<p>
          160  +For each column in a row of the result, the name of that column
          161  +is used as an index in to array.  The value of the column is stored
          162  +in the corresponding array entry.  The special array index * is
          163  +used to store a list of column names in the order that they appear.
          164  +</p>
          165  +
          166  +<p>
          167  +If the array variable name is the empty string, then the value of
          168  +each column is stored in a variable with the same name as the column
          169  +itself.  For example:
          170  +</p>
          171  +
          172  +<blockquote>
          173  +<b>db1 eval {SELECT * FROM t1 ORDER BY a} {} {<br>
          174  +&nbsp;&nbsp;&nbsp;&nbsp;puts "a=$a b=$b"<br>
          175  +}</b>
          176  +</blockquote>
          177  +
          178  +<p>
          179  +From this we get the following output
          180  +</p>
          181  +
          182  +<blockquote><b>
          183  +a=1 b=hello<br>
          184  +a=2 b=goodbye<br>
          185  +a=3 b=howdy!</b>
          186  +</blockquote>
          187  +
          188  +<h2>The "complete" method</h2>
          189  +<i>TBD</i>
          190  +
          191  +<h2>The "timeout" method</h2>
          192  +<i>TBD</i>
          193  +
          194  +<h2>The "busy" method</h2>
          195  +<i>TBD</i>
          196  +
          197  +
          198  +}
          199  +
          200  +puts {
          201  +<p><hr /></p>
          202  +<p><a href="index.html"><img src="/goback.jpg" border=0 />
          203  +Back to the SQLite Home Page</a>
          204  +</p>
          205  +
          206  +</body></html>}