/ Check-in [d88b7981]
Login

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

Overview
Comment:Cleanup the TCL interface source code and add documentation for recently added methods on the SQLite object of TCL. (CVS 4093)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: d88b79818a6a9e0413b9560687ec3c79fcb3dacc
User & Date: drh 2007-06-19 17:48:57
Context
2007-06-19
23:01
Change the TCL bindings so that @aaa always treats the variable aaa as a bytearray and binds the value as a BLOB. This change is backwards compatible since the $ behavior is unchanged and @ was not accepted until the current round of changes. (CVS 4094) check-in: 6f7d55ac user: drh tags: trunk
17:48
Cleanup the TCL interface source code and add documentation for recently added methods on the SQLite object of TCL. (CVS 4093) check-in: d88b7981 user: drh tags: trunk
17:15
In the TCL bindings, if a TCL variable has a bytearray representation and the host parameter starts with @ instead of $, then always store the content as a BLOB not as a string even if a string representation is also available. (CVS 4092) check-in: dcb104bd user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/tclsqlite.c.

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
...
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
**    May you find forgiveness for yourself and forgive others.
**    May you share freely, never taking more than you give.
**
*************************************************************************
** 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 $
*/
#include "tcl.h"
#include <errno.h>

/*
** Some additional include files are needed if this file is not
** appended to the amalgamation.
................................................................................
  int rc = TCL_OK;
  static const char *DB_strs[] = {
    "authorizer",         "busy",              "cache",
    "changes",            "close",             "collate",
    "collation_needed",   "commit_hook",       "complete",
    "copy",               "enable_load_extension","errorcode",
    "eval",               "exists",            "function",
    "incrblob",
    "interrupt",          "last_insert_rowid", "nullvalue",
    "onecolumn",          "profile",           "progress",
    "rekey",              "rollback_hook",     "timeout",
    "total_changes",      "trace",             "transaction",
    "update_hook",        "version",           0
  };
  enum DB_enum {
    DB_AUTHORIZER,        DB_BUSY,             DB_CACHE,
    DB_CHANGES,           DB_CLOSE,            DB_COLLATE,
    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_INTERRUPT,         DB_LAST_INSERT_ROWID,DB_NULLVALUE,
    DB_ONECOLUMN,         DB_PROFILE,          DB_PROGRESS,
    DB_REKEY,             DB_ROLLBACK_HOOK,    DB_TIMEOUT,
    DB_TOTAL_CHANGES,     DB_TRACE,            DB_TRANSACTION,
    DB_UPDATE_HOOK,       DB_VERSION,          
  };
  /* don't leave trailing commas on DB_enum, it confuses the AIX xlc compiler */

  if( objc<2 ){
    Tcl_WrongNumArgs(interp, 1, objv, "SUBCOMMAND ...");
    return TCL_ERROR;
  }







|







 







|
|
|
|
|
|







|
<
|
|
|
|







8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
...
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926

927
928
929
930
931
932
933
934
935
936
937
**    May you find forgiveness for yourself and forgive others.
**    May you share freely, never taking more than you give.
**
*************************************************************************
** 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.191 2007/06/19 17:48:57 drh Exp $
*/
#include "tcl.h"
#include <errno.h>

/*
** Some additional include files are needed if this file is not
** appended to the amalgamation.
................................................................................
  int rc = TCL_OK;
  static const char *DB_strs[] = {
    "authorizer",         "busy",              "cache",
    "changes",            "close",             "collate",
    "collation_needed",   "commit_hook",       "complete",
    "copy",               "enable_load_extension","errorcode",
    "eval",               "exists",            "function",
    "incrblob",           "interrupt",         "last_insert_rowid",
    "nullvalue",          "onecolumn",         "profile",
    "progress",           "rekey",             "rollback_hook",
    "timeout",            "total_changes",     "trace",
    "transaction",        "update_hook",       "version",
    0                    
  };
  enum DB_enum {
    DB_AUTHORIZER,        DB_BUSY,             DB_CACHE,
    DB_CHANGES,           DB_CLOSE,            DB_COLLATE,
    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_INTERRUPT,        DB_LAST_INSERT_ROWID,

    DB_NULLVALUE,         DB_ONECOLUMN,        DB_PROFILE,
    DB_PROGRESS,          DB_REKEY,            DB_ROLLBACK_HOOK,
    DB_TIMEOUT,           DB_TOTAL_CHANGES,    DB_TRACE,
    DB_TRANSACTION,       DB_UPDATE_HOOK,      DB_VERSION
  };
  /* don't leave trailing commas on DB_enum, it confuses the AIX xlc compiler */

  if( objc<2 ){
    Tcl_WrongNumArgs(interp, 1, objv, "SUBCOMMAND ...");
    return TCL_ERROR;
  }

Changes to www/tclsqlite.tcl.

1
2
3
4
5
6
7
8
9
10
11
..
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
..
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
..
65
66
67
68
69
70
71

72
73
74
75
76
77
78

79

80
81
82
83


84
85
86
87
88
89
90
...
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211

















212
213
214
215
216
217
218
...
581
582
583
584
585
586
587









































588
589
590
591
592
593
594
#
# 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 $}
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 {
................................................................................
<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>

<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>
(version 3.0).  Because there is only this
one command, the interface is not placed in a separate
namespace.</p>

<p>The <b>sqlite3</b> command is used as follows:</p>

<blockquote>
<b>sqlite3</b>&nbsp;&nbsp;<i>dbcmd&nbsp;&nbsp;database-name</i>
................................................................................
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
................................................................................
 changes
 close
 collate
 collation_needed
 commit_hook
 complete
 copy

 errorcode
 eval
 exists
 function
 last_insert_rowid
 nullvalue
 onecolumn

 progress

 timeout
 total_changes
 trace
 transaction


}] {
 puts "<li><a href=\"#$m\">$m</a></li>"
}
puts {
</ul>
</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>

}

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

................................................................................
METHOD commit_hook {

<p>This method registers a callback routine that is invoked just before
SQLite tries to commit changes to a database.  If the callback throws
an exception or returns a non-zero result, then the transaction rolls back
rather than commit.</p>
}










































##############################################################################
METHOD errorcode {

<p>This method returns the numeric error code that resulted from the most
recent SQLite operation.</p>
}



|







 







|
|







 







|
|
<
<
<
<







 







>







>

>




>
>







 







|



|
|

|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







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







1
2
3
4
5
6
7
8
9
10
11
..
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
..
44
45
46
47
48
49
50
51
52




53
54
55
56
57
58
59
..
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
...
198
199
200
201
202
203
204
205
206
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
...
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
#
# Run this Tcl script to generate the tclsqlite.html file.
#
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} {
  puts "<a name=\"$name\">\n<h3>The \"$name\" method</h3>\n"
  puts $text
}
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>

<h3>The API</h3>

<p>The interface to the SQLite library consists of single
tcl command named <b>sqlite3</b>
Because there is only this
one command, the interface is not placed in a separate
namespace.</p>

<p>The <b>sqlite3</b> command is used as follows:</p>

<blockquote>
<b>sqlite3</b>&nbsp;&nbsp;<i>dbcmd&nbsp;&nbsp;database-name</i>
................................................................................
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 22 methods
defined.</p>





<p>
<ul>
}
foreach m [lsort {
 authorizer
 busy
................................................................................
 changes
 close
 collate
 collation_needed
 commit_hook
 complete
 copy
 enable_load_extension
 errorcode
 eval
 exists
 function
 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>"
}
puts {
</ul>
</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,$bigstring)}
</b></blockquote>

<p>
Note that it is not necessary to quote the $bigstring value.  That happens
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 $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>

}

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

................................................................................
METHOD commit_hook {

<p>This method registers a callback routine that is invoked just before
SQLite tries to commit changes to a database.  If the callback throws
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 {

<p>This method returns the numeric error code that resulted from the most
recent SQLite operation.</p>
}