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 |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
d88b79818a6a9e0413b9560687ec3c79 |
User & Date: | drh 2007-06-19 17:48:57.000 |
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: 6f7d55aced 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: d88b79818a 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: dcb104bd41 user: drh tags: trunk) | |
Changes
Changes to src/tclsqlite.c.
︙ | ︙ | |||
8 9 10 11 12 13 14 | ** 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. ** | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | ** 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. |
︙ | ︙ | |||
906 907 908 909 910 911 912 | 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", | | < | | | | > | < | | | | | 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 | 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 | # # Run this Tcl script to generate the tclsqlite.html file. # | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | # # 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 { <h2>The Tcl interface to the SQLite library</h2> <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> <i>dbcmd database-name</i> |
︙ | ︙ | |||
44 45 46 47 48 49 50 | 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 | | | < < < < > > > > > | 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 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 | 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 cache 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> |
︙ | ︙ | |||
197 198 199 200 201 202 203 | 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> | | | | | > > > > > > > > > > > > > > > > > | 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 | 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 { |
︙ | ︙ | |||
581 582 583 584 585 586 587 588 589 590 591 592 593 594 | 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> } | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 | 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> <b>incrblob</b> <b>?-readonly??</b> <i>?DB? TABLE COLUMN 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> } |
︙ | ︙ |