Documenting the TCL interface (CVS 149)
FossilOrigin-Name: 7e0bacedf928095b29e7166eacd2356e8169d6dd
This commit is contained in:
drh
parent
05a1c8d08c
commit
9b0d0a8bc5
@ -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)
|
||||
|
||||
|
||||
21
manifest
21
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
|
||||
|
||||
@ -1 +1 @@
|
||||
ed5f5404ad804aec21ad971d59af834929381b5b
|
||||
7e0bacedf928095b29e7166eacd2356e8169d6dd
|
||||
@ -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; i<nCol; i++){
|
||||
Tcl_SetVar2(cbData->interp, 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;
|
||||
}
|
||||
|
||||
/*
|
||||
|
||||
@ -17,6 +17,10 @@ proc chng {date desc} {
|
||||
puts "<DD><P><UL>$desc</UL></P></DD>"
|
||||
}
|
||||
|
||||
chng {2000 Sep 30 (1.0.8)} {
|
||||
<li>Begin writing documentation on the TCL interface.</li>
|
||||
}
|
||||
|
||||
chng {2000 Sep 29 (Not Released)} {
|
||||
<li>Added the <b>sqlite_get_table()</b> API</li>
|
||||
<li>Updated the documtation for due to the above change.</li>
|
||||
|
||||
@ -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 {<html>
|
||||
<head><title>SQLite: An SQL Database Library Built Atop GDBM</title></head>
|
||||
@ -40,7 +40,7 @@ an example of how to use the SQLite library.</p>
|
||||
<li>Very simple
|
||||
<a href="c_interface.html">C/C++ interface</a> requires the use of only
|
||||
three functions and one opaque structure.</li>
|
||||
<li>A <a href="http://dev.scriptics.com/">Tcl</a> interface is
|
||||
<li>A <a href="tclsqlite.html">Tcl</a> interface is
|
||||
included.</li>
|
||||
<li>Command-line access program <a href="sqlite.html">sqlite</a> uses
|
||||
the <a href="http://www.google.com/search?q=gnu+readline+library">GNU
|
||||
@ -100,6 +100,7 @@ on tables where many entries in the table have the same index key.</p>
|
||||
command-line utility.</li>
|
||||
<li>The <a href="lang.html">SQL Language</a> subset understood by SQLite.</li>
|
||||
<li>The <a href="c_interface.html">C/C++ Interface</a>.</li>
|
||||
<li>The <a href="tclsqlite.html">Tcl Interface</a>.</li>
|
||||
<li>The <a href="fileformat.html">file format</a> used by SQLite databases.</li>
|
||||
<li>The <a href="arch.html">Architecture of the SQLite Library</a> describes
|
||||
how the library is put together.</li>
|
||||
|
||||
206
www/tclsqlite.tcl
Normal file
206
www/tclsqlite.tcl
Normal file
@ -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 {<html>
|
||||
<head>
|
||||
<title>The Tcl interface to the SQLite library</title>
|
||||
</head>
|
||||
<body bgcolor=white>
|
||||
<h1 align=center>
|
||||
The Tcl interface to the SQLite library
|
||||
</h1>}
|
||||
puts "<p align=center>
|
||||
(This page was last modified on [lrange $rcsid 3 4] GMT)
|
||||
</p>"
|
||||
|
||||
puts {
|
||||
<p>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.</p>
|
||||
|
||||
<h2>The API</h2>
|
||||
|
||||
<p>The interface to the SQLite library consists of single
|
||||
tcl command named <b>sqlite</b>. Because there is only this
|
||||
one interface command, the interface is not placed in a separate
|
||||
namespace.</p>
|
||||
|
||||
<p>The <b>sqlite</b> command is used as follows:</p>
|
||||
|
||||
<blockquote>
|
||||
<b>sqlite</b> <i>dbcmd database-directory-name</i>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
The <b>sqlite</b> 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 <b>sqlite</b> 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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Once an SQLite database is open, it can be controlled using
|
||||
methods of the <i>dbcmd</i>. There are currently 5 methods
|
||||
defined:</p>
|
||||
|
||||
<p>
|
||||
<ul>
|
||||
<li> busy
|
||||
<li> close
|
||||
<li> complete
|
||||
<li> eval
|
||||
<li> timeout
|
||||
</ul>
|
||||
</p>
|
||||
|
||||
<p>We will explain all of these methods, though not in that order.
|
||||
We will be begin with the "close" method.</p>
|
||||
|
||||
<h2>The "close" method</h2>
|
||||
|
||||
<p>
|
||||
As its name suggests, the "close" method to an SQLite database just
|
||||
closes the database. This has the side-effect of deleting the
|
||||
<i>dbcmd</i> Tcl command. Here is an example of opening and then
|
||||
immediately closing a database:
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<b>sqlite db1 ./testdb<br>
|
||||
db1 close</b>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
If you delete the <i>dbcmd</i> directly, that has the same effect
|
||||
as invoking the "close" method. So the following code is equivalent
|
||||
to the previous:</p>
|
||||
|
||||
<blockquote>
|
||||
<b>sqlite db1 ./testdb<br>
|
||||
rename db1 {}</b>
|
||||
</blockquote>
|
||||
|
||||
<h2>The "eval" method</h2>
|
||||
|
||||
<p>
|
||||
The most useful <i>dbcmd</i> method is "eval". The eval method is used
|
||||
to execute SQL on the database. The syntax of the eval method looks
|
||||
like this:</p>
|
||||
|
||||
<blockquote>
|
||||
<i>dbcmd</i> <b>eval</b> <i>sql</i>
|
||||
?<i>array-name script</i>?
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
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:</p>
|
||||
|
||||
<blockquote>
|
||||
<b>sqlite db1 ./testdb<br>
|
||||
db1 eval {CREATE TABLE t1(a int, b text)}</b>
|
||||
</blockquote>
|
||||
|
||||
<p>The above code creates a new table named <b>t1</b> with columns
|
||||
<b>a</b> and <b>b</b>. What could be simplier?</p>
|
||||
|
||||
<p>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:</p>
|
||||
|
||||
<blockquote>
|
||||
<b>db1 eval {INSERT INTO t1 VALUES(1,'hello')}<br>
|
||||
db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}<br>
|
||||
db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}<br>
|
||||
set x [db1 eval {SELECT * FROM t1 ORDER BY a}]</b>
|
||||
</blockquote>
|
||||
|
||||
<p>The variable <b>$x</b> is set by the above code to</p>
|
||||
|
||||
<blockquote>
|
||||
<b>1 hello 2 goodbye 3 howdy!</b>
|
||||
</blockquote>
|
||||
|
||||
<p>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:</p>
|
||||
|
||||
<blockquote>
|
||||
<b>db1 eval {SELECT * FROM t1 ORDER BY a} values {<br>
|
||||
parray values<br>
|
||||
puts ""<br>
|
||||
}</b>
|
||||
</blockquote>
|
||||
|
||||
<p>This last code will give the following output:</p>
|
||||
|
||||
<blockquote><b>
|
||||
values(*) = a b<br>
|
||||
values(a) = 1<br>
|
||||
values(b) = hello<p>
|
||||
|
||||
values(*) = a b<br>
|
||||
values(a) = 2<br>
|
||||
values(b) = goodbye<p>
|
||||
|
||||
values(*) = a b<br>
|
||||
values(a) = 3<br>
|
||||
values(b) = howdy!</b>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<b>db1 eval {SELECT * FROM t1 ORDER BY a} {} {<br>
|
||||
puts "a=$a b=$b"<br>
|
||||
}</b>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
From this we get the following output
|
||||
</p>
|
||||
|
||||
<blockquote><b>
|
||||
a=1 b=hello<br>
|
||||
a=2 b=goodbye<br>
|
||||
a=3 b=howdy!</b>
|
||||
</blockquote>
|
||||
|
||||
<h2>The "complete" method</h2>
|
||||
<i>TBD</i>
|
||||
|
||||
<h2>The "timeout" method</h2>
|
||||
<i>TBD</i>
|
||||
|
||||
<h2>The "busy" method</h2>
|
||||
<i>TBD</i>
|
||||
|
||||
|
||||
}
|
||||
|
||||
puts {
|
||||
<p><hr /></p>
|
||||
<p><a href="index.html"><img src="/goback.jpg" border=0 />
|
||||
Back to the SQLite Home Page</a>
|
||||
</p>
|
||||
|
||||
</body></html>}
|
||||
Loading…
Reference in New Issue
Block a user