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: | 7e0bacedf928095b29e7166eacd2356e |
| 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
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> <i>dbcmd 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> <b>eval</b> <i>sql</i> 97 + ?<i>array-name 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 + parray values<br> 139 + 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 + 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>}