/ Check-in [94aa2d32]
Login

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

Overview
Comment:Updates to the documentation on the TCL bindings. (CVS 2692)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 94aa2d32459e1cee2df21fcc7df76c73dab903cd
User & Date: drh 2005-09-13 07:00:06
Context
2005-09-13
16:12
Correct the sense of a test for SQLITE_DEBUG on the resent NDEBUG change. Ticket #1425 (CVS 2693) check-in: 81fdffdf user: drh tags: trunk
07:00
Updates to the documentation on the TCL bindings. (CVS 2692) check-in: 94aa2d32 user: drh tags: trunk
00:02
Fix a comment typo in the previous check-in. (CVS 2691) check-in: 49c95280 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/tclsqlite.tcl.

1
2
3
4
5
6
7
8
9
10
11
..
37
38
39
40
41
42
43
44


45
46
47
48
49
50




51
52
53
54
55
56
57

58
59
60
61
62
63
64
..
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
...
226
227
228
229
230
231
232


























233
234
235
236
237
238
239
...
264
265
266
267
268
269
270
































271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
...
422
423
424
425
426
427
428
429

430
431
432
433
434
435
436
...
451
452
453
454
455
456
457
458

459
460
461
462
463
464
465
#
# Run this Tcl script to generate the tclsqlite.html file.
#
set rcsid {$Id: tclsqlite.tcl,v 1.14 2005/08/02 17:38:19 drh Exp $}
source common.tcl
header {The Tcl interface to the SQLite library}
proc METHOD {name text} {
  puts "<a name=\"$name\">\n<h3>The \"$name\" method</h3>\n"
  puts $text
}
puts {
................................................................................
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>
The name of the database is just the name of a disk file in which
the database is stored.


</p>

<p>
Once an SQLite database is open, it can be controlled using 
methods of the <i>dbcmd</i>.  There are currently 19 methods
defined:</p>





<p>
<ul>
}
foreach m [lsort {
 authorizer
 busy

 changes
 close
 collate
 collation_needed
 commit_hook
 complete
 copy
................................................................................
</p>

<p>The use of each of these methods will be explained in the sequel, though
not in the order shown above.</p>

}

##############################################################################
METHOD close {

<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>sqlite3 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>sqlite3 db1 ./testdb<br>
rename db1 {}</b>
</blockquote>
}

##############################################################################
METHOD eval {
<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>

................................................................................
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>

}



























##############################################################################
METHOD transaction {

<p>
The "transaction" method is used to execute a TCL script inside an SQLite
database transaction.  The transaction is committed when the script completes,
................................................................................


<p>
The <i>transaction-type</i> can be one of <b>deferred</b>,
<b>exclusive</b> or <b>immediate</b>.  The default is deferred.
</p>
}

































##############################################################################
METHOD complete {

<p>
The "complete" method takes a string of supposed SQL as its only argument.
It returns TRUE if the string is a complete statement of SQL and FALSE if
there is more to be entered.</p>

<p>The "complete" method is useful when building interactive applications
in order to know when the user has finished entering a line of SQL code.
This is really just an interface to the <b>sqlite3_complete()</b> C
function.  Refer to the <a href="c_interface.html">C/C++ interface</a>
specification for additional information.</p>
}

##############################################################################
METHOD copy {

<p>
The "copy" method copies data from a file into a table.
................................................................................
}



##############################################################################
METHOD onecolumn {

<p>The "onecolumn" method works like "eval" in that it evaluates the

SQL query statement given as its argument.  The difference is that
"onecolumn" returns a single element which is the first column of the
first row of the query result.</p>

<p>This is a convenience method.  It saves the user from having to
do a "<tt>[lindex&nbsp;...&nbsp;0]</tt>" on the results of an "eval"
in order to extract a single column result.</p>
................................................................................
in the database that were inserted, deleted, and/or modified since the
current database connection was first opened.</p>
}

##############################################################################
METHOD authorizer {

<p>The "authorizer" method provides access to the sqlite3_set_authorizer

C/C++ interface.  The argument to authorizer is the name of a procedure that
is called when SQL statements are being compiled in order to authorize
certain operations.  The callback procedure takes 5 arguments which describe
the operation being coded.  If the callback returns the text string
"SQLITE_OK", then the operation is allowed.  If it returns "SQLITE_IGNORE",
then the operation is silently disabled.  If the return is "SQLITE_DENY"
then the compilation fails with an error.



|







 







|
>
>




|

>
>
>
>







>







 







<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>











|
|
|







 







|
>







 







|
>







1
2
3
4
5
6
7
8
9
10
11
..
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
..
88
89
90
91
92
93
94


























95
96
97
98
99
100
101
...
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
...
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
...
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
...
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
#
# Run this Tcl script to generate the tclsqlite.html file.
#
set rcsid {$Id: tclsqlite.tcl,v 1.15 2005/09/13 07:00:06 drh Exp $}
source common.tcl
header {The Tcl interface to the SQLite library}
proc METHOD {name text} {
  puts "<a name=\"$name\">\n<h3>The \"$name\" method</h3>\n"
  puts $text
}
puts {
................................................................................
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>
The name of the database is just the name of a disk file in which
the database is stored.  If the name of the database is an empty
string or the special name ":memory:" then a new database is created
in memory.
</p>

<p>
Once an SQLite database is open, it can be controlled using 
methods of the <i>dbcmd</i>.  There are currently 21 methods
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>
}
foreach m [lsort {
 authorizer
 busy
 cache
 changes
 close
 collate
 collation_needed
 commit_hook
 complete
 copy
................................................................................
</p>

<p>The use of each of these methods will be explained in the sequel, though
not in the order shown above.</p>

}



























##############################################################################
METHOD eval {
<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>

................................................................................
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>

}

##############################################################################
METHOD close {

<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>sqlite3 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>sqlite3 db1 ./testdb<br>
rename db1 {}</b>
</blockquote>
}

##############################################################################
METHOD transaction {

<p>
The "transaction" method is used to execute a TCL script inside an SQLite
database transaction.  The transaction is committed when the script completes,
................................................................................


<p>
The <i>transaction-type</i> can be one of <b>deferred</b>,
<b>exclusive</b> or <b>immediate</b>.  The default is deferred.
</p>
}

##############################################################################
METHOD cache {

<p>
The "eval" method described <a href="#eval">above</a> keeps a cache of
<a href="capi3ref.html#sqlite3_prepare">prepared statements</a>
for recently evaluated SQL commands.  
The "cache" method is used to control this cache.
The first form of this command is:</p>

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>cache size</b>&nbsp;&nbsp;<i>N</i>
</blockquote>

<p>This sets the maximum number of statements that can be cached.
The upper limit is 100.  The default is 10.  If you set the cache size
to 0, no caching is done.</p>

<p>The second form of the command is this:</p>


<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>cache flush</b>
</blockquote>

<p>The cache-flush method 
<a href="capi3ref.html#sqlite3_finalize">finalizes</a>
all prepared statements currently
in the cache.</p>

}

##############################################################################
METHOD complete {

<p>
The "complete" method takes a string of supposed SQL as its only argument.
It returns TRUE if the string is a complete statement of SQL and FALSE if
there is more to be entered.</p>

<p>The "complete" method is useful when building interactive applications
in order to know when the user has finished entering a line of SQL code.
This is really just an interface to the 
<a href="capi3ref.html#sqlite3_complete"><b>sqlite3_complete()</b></a> C
function.
}

##############################################################################
METHOD copy {

<p>
The "copy" method copies data from a file into a table.
................................................................................
}



##############################################################################
METHOD onecolumn {

<p>The "onecolumn" method works like 
"<a href="#eval">eval</a>" in that it evaluates the
SQL query statement given as its argument.  The difference is that
"onecolumn" returns a single element which is the first column of the
first row of the query result.</p>

<p>This is a convenience method.  It saves the user from having to
do a "<tt>[lindex&nbsp;...&nbsp;0]</tt>" on the results of an "eval"
in order to extract a single column result.</p>
................................................................................
in the database that were inserted, deleted, and/or modified since the
current database connection was first opened.</p>
}

##############################################################################
METHOD authorizer {

<p>The "authorizer" method provides access to the 
<a href="capi3ref.html#sqlite3_set_authorizer">sqlite3_set_authorizer</a>
C/C++ interface.  The argument to authorizer is the name of a procedure that
is called when SQL statements are being compiled in order to authorize
certain operations.  The callback procedure takes 5 arguments which describe
the operation being coded.  If the callback returns the text string
"SQLITE_OK", then the operation is allowed.  If it returns "SQLITE_IGNORE",
then the operation is silently disabled.  If the return is "SQLITE_DENY"
then the compilation fails with an error.