Cleanup the TCL interface source code and add documentation for recently

added methods on the SQLite object of TCL. (CVS 4093)

FossilOrigin-Name: d88b79818a6a9e0413b9560687ec3c79fcb3dacc

manifest

@@ -1,5 +1,5 @@
-C In\sthe\sTCL\sbindings,\sif\sa\sTCL\svariable\shas\sa\sbytearray\srepresentation\sand\nthe\shost\sparameter\sstarts\swith\s@\sinstead\sof\s$,\sthen\salways\sstore\sthe\ncontent\sas\sa\sBLOB\snot\sas\sa\sstring\seven\sif\sa\sstring\srepresentation\sis\salso\navailable.\s(CVS\s4092)
+C Cleanup\sthe\sTCL\sinterface\ssource\scode\sand\sadd\sdocumentation\sfor\srecently\nadded\smethods\son\sthe\sSQLite\sobject\sof\sTCL.\s(CVS\s4093)
-D 2007-06-19T17:15:47
+D 2007-06-19T17:48:57
 F Makefile.in 5babd49c427a0e82e849c89a4d3c3c1e607ec014
 F Makefile.linux-gcc 2d8574d1ba75f129aba2019f0b959db380a90935
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -109,7 +109,7 @@ F src/sqlite3ext.h 7d0d363ea7327e817ef0dfe1b7eee1f171b72890
 F src/sqliteInt.h 07b0f7a4b7e849c9b96d921e9c5b32fc8802072c
 F src/sqliteLimit.h f14609c27636ebc217c9603ade26dbdd7d0f6afa
 F src/table.c a8de75bcedf84d4060d804264b067ab3b1a3561d
-F src/tclsqlite.c 344e28bd3a1b7480a1cbf642911a99122b72ef8e
+F src/tclsqlite.c df53bcb8239658c5ce45762c9837cc7f38c680de
 F src/test1.c a83c097ee1353e8982745ee1b78612fea7425602
 F src/test2.c 24458b17ab2f3c90cbc1c8446bd7ffe69be62f88
 F src/test3.c a280931fb40222b7c90da45eea926459beee8904
@@ -503,11 +503,11 @@ F www/speed.tcl 656ed5be8cc9d536353e1a96927b925634a62933
 F www/sqlite.tcl abb87f0d74a4fe9642987466bb59fe6abada988f
 F www/support.tcl 7961ce16290692578d783bb11f0dc8391a9be9c3
 F www/table-ex1b2.gif a588d21a2d88bb2a2ef0431fcc5ed5aa48c0bbc5
-F www/tclsqlite.tcl bb0d1357328a42b1993d78573e587c6dcbc964b9
+F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P 64bcc41f12e902fd025c9ba36c09dd6e4cf25923
+P dcb104bd41f5e992d4c84b8947cb5099ae746891
-R 77fe303dc438055db8d268fdb3354536
+R 2c8e4d427c1a25e275d6ce32dba71a8d
 U drh
-Z 1386ace3ab85ad3dfcfb4f374c31ada6
+Z 100864d73ffe0c8bd7da587cd9106c28

manifest.uuid

@@ -1 +1 @@
-dcb104bd41f5e992d4c84b8947cb5099ae746891
+d88b79818a6a9e0413b9560687ec3c79fcb3dacc

src/tclsqlite.c

@@ -12,7 +12,7 @@
 ** A TCL Interface to SQLite.  Append this file to sqlite3.c and
 ** compile the whole thing to build a TCL-enabled version of SQLite.
 **
-** $Id: tclsqlite.c,v 1.190 2007/06/19 17:15:47 drh Exp $
+** $Id: tclsqlite.c,v 1.191 2007/06/19 17:48:57 drh Exp $
 */
 #include "tcl.h"
 #include <errno.h>
@@ -910,12 +910,12 @@ static int DbObjCmd(void *cd, Tcl_Interp *interp, int objc,Tcl_Obj *const*objv){
     "collation_needed",   "commit_hook",       "complete",
     "copy",               "enable_load_extension","errorcode",
     "eval",               "exists",            "function",
-    "incrblob",
+    "incrblob",           "interrupt",         "last_insert_rowid",
-    "interrupt",          "last_insert_rowid", "nullvalue",
+    "nullvalue",          "onecolumn",         "profile",
-    "onecolumn",          "profile",           "progress",
+    "progress",           "rekey",             "rollback_hook",
-    "rekey",              "rollback_hook",     "timeout",
+    "timeout",            "total_changes",     "trace",
-    "total_changes",      "trace",             "transaction",
+    "transaction",        "update_hook",       "version",
-    "update_hook",        "version",           0
+    0                    
   };
   enum DB_enum {
     DB_AUTHORIZER,        DB_BUSY,             DB_CACHE,
@@ -923,12 +923,11 @@ static int DbObjCmd(void *cd, Tcl_Interp *interp, int objc,Tcl_Obj *const*objv){
     DB_COLLATION_NEEDED,  DB_COMMIT_HOOK,      DB_COMPLETE,
     DB_COPY,              DB_ENABLE_LOAD_EXTENSION,DB_ERRORCODE,
     DB_EVAL,              DB_EXISTS,           DB_FUNCTION,
-    DB_INCRBLOB,
+    DB_INCRBLOB,          DB_INTERRUPT,        DB_LAST_INSERT_ROWID,
-    DB_INTERRUPT,         DB_LAST_INSERT_ROWID,DB_NULLVALUE,
+    DB_NULLVALUE,         DB_ONECOLUMN,        DB_PROFILE,
-    DB_ONECOLUMN,         DB_PROFILE,          DB_PROGRESS,
+    DB_PROGRESS,          DB_REKEY,            DB_ROLLBACK_HOOK,
-    DB_REKEY,             DB_ROLLBACK_HOOK,    DB_TIMEOUT,
+    DB_TIMEOUT,           DB_TOTAL_CHANGES,    DB_TRACE,
-    DB_TOTAL_CHANGES,     DB_TRACE,            DB_TRANSACTION,
+    DB_TRANSACTION,       DB_UPDATE_HOOK,      DB_VERSION
-    DB_UPDATE_HOOK,       DB_VERSION,          
   };
   /* don't leave trailing commas on DB_enum, it confuses the AIX xlc compiler */
 

www/tclsqlite.tcl

@@ -1,7 +1,7 @@
 #
 # Run this Tcl script to generate the tclsqlite.html file.
 #
-set rcsid {$Id: tclsqlite.tcl,v 1.16 2006/01/05 15:50:07 drh Exp $}
+set rcsid {$Id: tclsqlite.tcl,v 1.17 2007/06/19 17:48:57 drh Exp $}
 source common.tcl
 header {The Tcl interface to the SQLite library}
 proc METHOD {name text} {
@@ -18,8 +18,8 @@ programming interface.</p>
 <h3>The API</h3>
 
 <p>The interface to the SQLite library consists of single
-tcl command named <b>sqlite</b> (version 2.8) or <b>sqlite3</b>
+tcl command named <b>sqlite3</b>
-(version 3.0).  Because there is only this
+Because there is only this
 one command, the interface is not placed in a separate
 namespace.</p>
 
@@ -48,12 +48,8 @@ in memory.
 
 <p>
 Once an SQLite database is open, it can be controlled using 
-methods of the <i>dbcmd</i>.  There are currently 21 methods
+methods of the <i>dbcmd</i>.  There are currently 22 methods
-defined:</p>
+defined.</p>
-
-<p>The <b>sqlite3</b> also accepts an optional third argument called
-the "mode".  This argument is a legacy from SQLite version 2 and is
-currently ignored.</p>
 
 <p>
 <ul>
@@ -69,6 +65,7 @@ foreach m [lsort {
  commit_hook
  complete
  copy
+ enable_load_extension
  errorcode
  eval
  exists
@@ -76,11 +73,15 @@ foreach m [lsort {
  last_insert_rowid
  nullvalue
  onecolumn
+ profile
  progress
+ rollback_hook
  timeout
  total_changes
  trace
  transaction
+ update_hook
+ version
 }] {
  puts "<li><a href=\"#$m\">$m</a></li>"
 }
@@ -201,14 +202,31 @@ variable does not exist a NULL values is used.  For example:
 </p>
 
 <blockquote><b>
-db1 eval {INSERT INTO t1 VALUES(5,$bigblob)}
+db1 eval {INSERT INTO t1 VALUES(5,$bigstring)}
 </b></blockquote>
 
 <p>
-Note that it is not necessary to quote the $bigblob value.  That happens
+Note that it is not necessary to quote the $bigstring value.  That happens
-automatically.  If $bigblob is a large string or binary object, this
+automatically.  If $bigstring is a large string or binary object, this
 technique is not only easier to write, it is also much more efficient
-since it avoids making a copy of the content of $bigblob.
+since it avoids making a copy of the content of $bigstring.
+</p>
+
+<p>
+If the $bigstring variable has both a string and a "bytearray" representation,
+then TCL inserts the value as a string.  If it has only a "bytearray"
+representation, then the value is inserted as a BLOB.  To force a
+value to be inserted as a BLOB even if it also has a text representation,
+us a "@" character to in place of the "$".  Like this:
+</p>
+
+<blockquote><b>
+db1 eval {INSERT INTO t1 VALUES(5,@bigstring)}
+</b></blockquote>
+
+<p>
+If the variable does not have a bytearray representation, then "@" works
+just like "$".
 </p>
 
 }
@@ -586,6 +604,47 @@ an exception or returns a non-zero result, then the transaction rolls back
 rather than commit.</p>
 }
 
+##############################################################################
+METHOD rollback_hook {
+
+<p>This method registers a callback routine that is invoked just before
+SQLite tries to do a rollback.  The script argument is run without change.</p>
+}
+
+##############################################################################
+METHOD update_hook {
+
+<p>This method registers a callback routine that is invoked just before
+each row is modified by an UPDATE, INSERT, or DELETE statement.  Four
+arguments are appended to the callback before it is invoked:</p>
+
+<ul>
+<li>The keyword "INSERT", "UPDATE", or "DELETE", as appropriate</li>
+<li>The name of the database which is being changed</li>
+<li>The table that is being changed</li>
+<li>The rowid of the row in the table being changed</li>
+</ul>
+}
+
+##############################################################################
+METHOD incrblob {
+
+<p>This method opens a TCL channel that can be used to read or write
+into a preexisting BLOB in the database.  The syntax is like this:</p>
+
+<blockquote>
+<i>dbcmd</i>&nbsp;&nbsp;<b>incrblob</b>&nbsp;&nbsp;<b>?-readonly??</b>
+&nbsp;&nbsp;<i>?DB?&nbsp;&nbsp;TABLE&nbsp;&nbsp;COLUMN&nbsp;&nbsp;ROWID</i>
+</blockquote>
+
+<p>
+The command returns a new TCL channel for reading or writing to the BLOB.
+The channel is opened using the underlying 
+<a href="/capi3ref.html#sqlite3_blob_open">sqlite3_blob_open()</a> C-langauge
+interface.  Close the channel using the <b>close</b> command of TCL.
+</p>
+}
+
 ##############################################################################
 METHOD errorcode {