From db06183c2272899364d2bd24dde9007d8a407d1d Mon Sep 17 00:00:00 2001
From: drh <drh@noemail.net>
Date: Thu, 26 Aug 2004 01:12:13 +0000
Subject: [PATCH] Update the TCL binding documentation to describe the newly
 added ability to specify TCL variable names in the body of an SQL statement.
 (CVS 1904)

FossilOrigin-Name: b3b9e58103dd6c65c55caf9a25bc1c257b37df88
---
 manifest          | 12 ++++++------
 manifest.uuid     |  2 +-
 www/tclsqlite.tcl | 29 ++++++++++++++++++++++++-----
 3 files changed, 31 insertions(+), 12 deletions(-)

diff --git a/manifest b/manifest
index fc1764e13d..c3fb81dd6c 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Protect\sTcl_Obj\spointers\sfrom\schange\susing\sTcl_IncrRefCount()\swhile\nexecuting\sSQL\sstatements\sin\sthe\sTCL\sbindings.\s(CVS\s1903)
-D 2004-08-26T00:56:05
+C Update\sthe\sTCL\sbinding\sdocumentation\sto\sdescribe\sthe\snewly\sadded\sability\nto\sspecify\sTCL\svariable\snames\sin\sthe\sbody\sof\san\sSQL\sstatement.\s(CVS\s1904)
+D 2004-08-26T01:12:14
 F Makefile.in 4a5e570a9e2d35b09c31b3cf01b78cea764ade4b
 F Makefile.linux-gcc a9e5a0d309fa7c38e7c14d3ecf7690879d3a5457
 F README f1de682fbbd94899d50aca13d387d1b3fd3be2dd
@@ -239,11 +239,11 @@ F www/quickstart.tcl 4e97bef825e6a4153c43afb9f97235fc4da278ab
 F www/speed.tcl 19cf0c1bf73c4b534dfafc95b3eacff4825740b4
 F www/sqlite.tcl b51fd15f0531a54874de785a9efba323eecd5975
 F www/support.tcl 96c8324cea27b5ded53ff5c60c127ba2053f688e
-F www/tclsqlite.tcl 06a86cba4d7fc88e2bcd633b57702d3d16abebb5
+F www/tclsqlite.tcl 560ecd6a916b320e59f2917317398f3d59b7cc25
 F www/vdbe.tcl 59288db1ac5c0616296b26dce071c36cb611dfe9
 F www/version3.tcl 092a01f5ef430d2c4acc0ae558d74c4bb89638a0
 F www/whentouse.tcl a8335bce47cc2fddb07f19052cb0cb4d9129a8e4
-P fd584d1ccf6643b723c2ff0a7a16c2aea3f1142c
-R c2945f067807301ea9f9b82dd56f837f
+P 6199f2f243514bbd4befbf768a7e03aec775bed2
+R f973acd39b99533a4d32c0284d2f7a6d
 U drh
-Z 3e4b219d5ef080e3900472694ea85d39
+Z e1a14528ab39e612df9c5d5bff54ca90
diff --git a/manifest.uuid b/manifest.uuid
index 538c0bf9e7..ad60b9d28e 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-6199f2f243514bbd4befbf768a7e03aec775bed2
\ No newline at end of file
+b3b9e58103dd6c65c55caf9a25bc1c257b37df88
\ No newline at end of file
diff --git a/www/tclsqlite.tcl b/www/tclsqlite.tcl
index e425b72e2e..a28486da72 100644
--- a/www/tclsqlite.tcl
+++ b/www/tclsqlite.tcl
@@ -1,7 +1,7 @@
 #
 # Run this Tcl script to generate the tclsqlite.html file.
 #
-set rcsid {$Id: tclsqlite.tcl,v 1.10 2004/07/21 14:54:50 drh Exp $}
+set rcsid {$Id: tclsqlite.tcl,v 1.11 2004/08/26 01:12:14 drh Exp $}
 source common.tcl
 header {The Tcl interface to the SQLite library}
 proc METHOD {name text} {
@@ -20,7 +20,7 @@ programming interface.</p>
 <p>The interface to the SQLite library consists of single
 tcl command named <b>sqlite</b> (version 2.8) or <b>sqlite3</b>
 (version 3.0).  Because there is only this
-one interface command, the interface is not placed in a separate
+one command, the interface is not placed in a separate
 namespace.</p>
 
 <p>The <b>sqlite3</b> command is used as follows:</p>
@@ -117,7 +117,7 @@ like this:</p>
 
 <blockquote>
 <i>dbcmd</i>&nbsp;&nbsp;<b>eval</b>&nbsp;&nbsp;<i>sql</i>
-&nbsp;&nbsp;&nbsp;&nbsp;?<i>array-name&nbsp;&nbsp;script</i>?
+&nbsp;&nbsp;&nbsp;&nbsp;?<i>array-name&nbsp;</i>?&nbsp;?<i>script</i>?
 </blockquote>
 
 <p>
@@ -187,13 +187,13 @@ 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
+If the array variable name is omitted or 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>
+<b>db1 eval {SELECT * FROM t1 ORDER BY a} {<br>
 &nbsp;&nbsp;&nbsp;&nbsp;puts "a=$a b=$b"<br>
 }</b>
 </blockquote>
@@ -207,6 +207,25 @@ a=1 b=hello<br>
 a=2 b=goodbye<br>
 a=3 b=howdy!</b>
 </blockquote>
+
+<p>
+Tcl variable names can appear in the SQL statement of the second argument
+in any position where it is legal to put a string or number literal.  The
+value of the variable is substituted for the variable name.  If the
+variable does not exist a NULL values is used.  For example:
+</p>
+
+<blockquote><b>
+db1 eval {INSERT INTO t1 VALUES(5,$bigblob)}
+</b></blockquote>
+
+<p>
+Note that it is not necessary to quote the $bigblob value.  That happens
+automatically.  If $bigblob 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.
+</p>
+
 }
 
 ##############################################################################