File: tclsqlite.html

package info (click to toggle)
sqlite3 3.7.13-1%2Bdeb7u2
links: PTS
area: main
in suites: wheezy
size: 33,340 kB
sloc: ansic: 128,216; sh: 9,500; tcl: 8,265; makefile: 1,216; yacc: 1,029; awk: 187
file content (838 lines) | stat: -rw-r--r-- 30,717 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>The Tcl interface to the SQLite library</title>
<style type="text/css">
body {
    margin: auto;
    font-family: Verdana, sans-serif;
    padding: 8px 1%;
}

a { color: #044a64 }
a:visited { color: #734559 }

.logo { position:absolute; margin:3px; }
.tagline {
  float:right;
  text-align:right;
  font-style:italic;
  width:300px;
  margin:12px;
  margin-top:58px;
}

.toolbar {
  text-align: center;
  line-height: 1.6em;
  margin: 0;
  padding: 0px 8px;
}
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
.toolbar a:visited { color: white; }
.toolbar a:hover { color: #044a64; background: white; }

.content    { margin: 5%; }
.content dt { font-weight:bold; }
.content dd { margin-bottom: 25px; margin-left:20%; }
.content ul { padding:0px; padding-left: 15px; margin:0px; }

/* rounded corners */
.se  { background: url(images/se.gif) 100% 100% no-repeat #044a64}
.sw  { background: url(images/sw.gif) 0% 100% no-repeat }
.ne  { background: url(images/ne.gif) 100% 0% no-repeat }
.nw  { background: url(images/nw.gif) 0% 0% no-repeat }

/* Things for "fancyformat" documents start here. */
.fancy img+p {font-style:italic}
.fancy .codeblock i { color: darkblue; }
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
.fancy h2 { margin-left: 10px }
.fancy h3 { margin-left: 20px }
.fancy h4 { margin-left: 30px }
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
.fancy #toc a        { color: darkblue ; text-decoration: none }
.fancy .todo         { color: #AA3333 ; font-style : italic }
.fancy .todo:before  { content: 'TODO:' }
.fancy p.todo        { border: solid #AA3333 1px; padding: 1ex }
.fancy img { display:block; }
.fancy :link:hover, .fancy :visited:hover { background: wheat }
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
.fancy li p { margin: 1em 0 }
/* End of "fancyformat" specific rules. */

</style>
  
</head>
<body>
<div><!-- container div to satisfy validator -->

<a href="index.html">
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite Logo"
 border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>

<table width=100% style="clear:both"><tr><td>
  <div class="se"><div class="sw"><div class="ne"><div class="nw">
  <table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
  <td width=100%>
  <div class="toolbar">
    <a href="about.html">About</a>
    <a href="sitemap.html">Sitemap</a>
    <a href="docs.html">Documentation</a>
    <a href="download.html">Download</a>
    <a href="copyright.html">License</a>
    <a href="news.html">News</a>
    <a href="support.html">Support</a>
  </div>
<script>
  gMsg = "Search SQLite Docs..."
  function entersearch() {
    var q = document.getElementById("q");
    if( q.value == gMsg ) { q.value = "" }
    q.style.color = "black"
    q.style.fontStyle = "normal"
  }
  function leavesearch() {
    var q = document.getElementById("q");
    if( q.value == "" ) { 
      q.value = gMsg
      q.style.color = "#044a64"
      q.style.fontStyle = "italic"
    }
  }
</script>
<td>
    <div style="padding:0 1em 0px 0;white-space:nowrap">
    <form name=f method="GET" action="http://www.sqlite.org/search">
      <input id=q name=q type=text
       onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
      <input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
    </form>
    </div>
  </table>
</div></div></div></div>
</td></tr></table>
<div class=startsearch></div>
  



<h1 align=center>The Tcl interface to the SQLite library</h1>

<p>The SQLite library is designed to be very easy to use from
a <a href="http://www.tcl.tk">Tcl or Tcl/Tk</a> script.  SQLite
began as a <a href="http://www.tcl.tk/doc/tea/">Tcl extension</a>
and the primary <a href="testing.html">test suite</a> for SQLite is written in TCL.  SQLite
can be used with any programming language, but its connections to
TCL run deep.</p>

<p>This document gives an overview of the Tcl
programming interface for SQLite.</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>
</blockquote>

<p>
The <b>sqlite3</b> command opens the database named in the second
argument.  If the database does not already exist, it is
automatically created.
The <b>sqlite3</b> command also creates a new Tcl
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 
the special name "<a href="inmemorydb.html">:memory:</a>" then a new database is created
in memory.  If the name of the database is an empty string, then
the database is created in an empty file that is automatically deleted
when the database connection closes.
</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>

<li><a href="#authorizer">authorizer</a></li><li><a href="#backup">backup</a></li><li><a href="#busy">busy</a></li><li><a href="#cache">cache</a></li><li><a href="#changes">changes</a></li><li><a href="#close">close</a></li><li><a href="#collate">collate</a></li><li><a href="#collation_needed">collation_needed</a></li><li><a href="#commit_hook">commit_hook</a></li><li><a href="#complete">complete</a></li><li><a href="#copy">copy</a></li><li><a href="#enable_load_extension">enable_load_extension</a></li><li><a href="#errorcode">errorcode</a></li><li><a href="#eval">eval</a></li><li><a href="#exists">exists</a></li><li><a href="#function">function</a></li><li><a href="#incrblob">incrblob</a></li><li><a href="#last_insert_rowid">last_insert_rowid</a></li><li><a href="#nullvalue">nullvalue</a></li><li><a href="#onecolumn">onecolumn</a></li><li><a href="#profile">profile</a></li><li><a href="#progress">progress</a></li><li><a href="#restore">restore</a></li><li><a href="#rollback_hook">rollback_hook</a></li><li><a href="#status">status</a></li><li><a href="#timeout">timeout</a></li><li><a href="#total_changes">total_changes</a></li><li><a href="#trace">trace</a></li><li><a href="#transaction">transaction</a></li><li><a href="#unlock_notify">unlock_notify</a></li><li><a href="#update_hook">update_hook</a></li><li><a href="#version">version</a></li>
</ul>
</p>

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

<a name="eval"></a>
<h3>The "eval" method</h3>

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

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>eval</b>&nbsp;&nbsp;<i>sql</i>
&nbsp;&nbsp;&nbsp;&nbsp;?<i>array-name&nbsp;</i>?&nbsp;?<i>script</i>?
</blockquote>

<p>
The job of the eval method is to execute the SQL statement or statements
given in the second argument.  For example, to create a new table in
a database, you can do this:</p>

<blockquote>
<b>sqlite3 db1 ./testdb<br>
db1 eval {CREATE TABLE t1(a int, b text)}</b>
</blockquote>

<p>The above code creates a new table named <b>t1</b> with columns
<b>a</b> and <b>b</b>.  What could be simpler?</p>

<p>Query results are returned as a list of column values.  If a
query requests 2 columns and there are 3 rows matching the query,
then the returned list will contain 6 elements.  For example:</p>

<blockquote>
<b>db1 eval {INSERT INTO t1 VALUES(1,'hello')}<br>
db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}<br>
db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}<br>
set x &#91;db1 eval {SELECT * FROM t1 ORDER BY a}&#93;</b>
</blockquote>

<p>The variable <b>$x</b> is set by the above code to</p>

<blockquote>
<b>1 hello 2 goodbye 3 howdy!</b>
</blockquote>

<p>You can also process the results of a query one row at a time
by specifying the name of an array variable and a script following
the SQL code.  For each row of the query result, the values of all
columns will be inserted into the array variable and the script will
be executed.  For instance:</p>

<blockquote>
<b>db1 eval {SELECT * FROM t1 ORDER BY a} values {<br>
&nbsp;&nbsp;&nbsp;&nbsp;parray values<br>
&nbsp;&nbsp;&nbsp;&nbsp;puts ""<br>
}</b>
</blockquote>

<p>This last code will give the following output:</p>

<blockquote><b>
values(*) = a b<br>
values(a) = 1<br>
values(b) = hello<p>

values(*) = a b<br>
values(a) = 2<br>
values(b) = goodbye<p>

values(*) = a b<br>
values(a) = 3<br>
values(b) = howdy!</b>
</blockquote>

<p>
For each column in a row of the result, the name of that column
is used as an index in to array.  The value of the column is stored
in the corresponding array entry.  The special array index * is
used to store a list of column names in the order that they appear.
</p>

<p>
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>
&nbsp;&nbsp;&nbsp;&nbsp;puts "a=$a b=$b"<br>
}</b>
</blockquote>

<p>
From this we get the following output
</p>

<blockquote><b>
a=1 b=hello<br>
a=2 b=goodbye<br>
a=3 b=howdy!</b>
</blockquote>

<a name="varsubst"></a>

<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 "$".  Note that ":" works like "$" in all cases so the following
is another way to express the same statement:
</p>

<blockquote><b>
db1 eval {INSERT INTO t1 VALUES(5,:bigstring)}
</b></blockquote>

<p>The use of ":" instead of "$" before the name of a variable can 
sometimes be useful if the SQL text is enclosed in "..." instead of
{...}.  When the SQL is contained within "..." then TCL will do
the substitution of $-variables, which can lead to SQL injection if
extreme care is not used.  But TCL will never substitute a :-variable
regardless of whether "..." or {...} are used to enclose the SQL, so
the use of :-variables adds an extra measure of defense against SQL
injection.
</p>

<a name="close"></a>
<h3>The "close" method</h3>


<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>
<a name="transaction"></a>
<h3>The "transaction" method</h3>


<p>
The "transaction" method is used to execute a TCL script inside an SQLite
database transaction.  The transaction is committed when the script completes,
or it rolls back if the script fails.  If the transaction occurs within
another transaction (even one that is started manually using BEGIN) it
is a no-op.
</p>

<p>
The transaction command can be used to group together several SQLite
commands in a safe way.  You can always start transactions manually using
BEGIN, of
course.  But if an error occurs so that the COMMIT or ROLLBACK are never
run, then the database will remain locked indefinitely.  Also, BEGIN
does not nest, so you have to make sure no other transactions are active
before starting a new one.  The "transaction" method takes care of
all of these details automatically.
</p>

<p>
The syntax looks like this:
</p>

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>transaction</b>&nbsp;&nbsp;<i>?transaction-type?</i>
&nbsp;&nbsp;<i>SCRIPT,</i>
</blockquote>


<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>
<a name="cache"></a>
<h3>The "cache" method</h3>


<p>
The "eval" method described <a href="#eval">above</a> keeps a cache of
<a href="c3ref/prepare.html">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="c3ref/finalize.html">finalizes</a>
all prepared statements currently
in the cache.</p>

<a name="complete"></a>
<h3>The "complete" method</h3>


<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="c3ref/complete.html"><b>sqlite3_complete()</b></a> C
function.
<a name="copy"></a>
<h3>The "copy" method</h3>


<p>
The "copy" method copies data from a file into a table.
It returns the number of rows processed successfully from the file.
The syntax of the copy method looks like this:</p>

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>copy</b>&nbsp;&nbsp;<i>conflict-algorithm</i>
&nbsp;&nbsp;<i>table-name&nbsp;</i>&nbsp;&nbsp;<i>file-name&nbsp;</i>
&nbsp;&nbsp;&nbsp;&nbsp;?<i>column-separator&nbsp;</i>?
&nbsp;&nbsp;?<i>null-indicator</i>?
</blockquote>

<p>Conflict-algorithm must be one of the SQLite conflict algorithms for
the INSERT statement: <i>rollback</i>, <i>abort</i>,
<i>fail</i>,<i>ignore</i>, or <i>replace</i>. See the SQLite Language
section for <a href="lang.html#conflict">ON CONFLICT</a> for more information.
The conflict-algorithm must be specified in lower case.
</p>

<p>Table-name must already exists as a table.  File-name must exist, and
each row must contain the same number of columns as defined in the table.
If a line in the file contains more or less than the number of columns defined,
the copy method rollbacks any inserts, and returns an error.</p>

<p>Column-separator is an optional column separator string.  The default is
the ASCII tab character \t. </p>

<p>Null-indicator is an optional string that indicates a column value is null.
The default is an empty string.  Note that column-separator and
null-indicator are optional positional arguments; if null-indicator
is specified, a column-separator argument must be specified and
precede the null-indicator argument.</p>

<p>The copy method implements similar functionality to the <b>.import</b>
SQLite shell command. 
The SQLite 2.x <a href="lang.html#copy"><b>COPY</b></a> statement 
(using the PostgreSQL COPY file format)
can be implemented with this method as:</p>

<blockquote>
dbcmd&nbsp;&nbsp;copy&nbsp;&nbsp;$conflictalgo
&nbsp;&nbsp;$tablename&nbsp;&nbsp;&nbsp;$filename&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;\t&nbsp;
&nbsp;&nbsp;\\N
</blockquote>

<a name="timeout"></a>
<h3>The "timeout" method</h3>


<p>The "timeout" method is used to control how long the SQLite library
will wait for locks to clear before giving up on a database transaction.
The default timeout is 0 millisecond.  (In other words, the default behavior
is not to wait at all.)</p>

<p>The SQLite database allows multiple simultaneous
readers or a single writer but not both.  If any process is writing to
the database no other process is allows to read or write.  If any process
is reading the database other processes are allowed to read but not write.
The entire database shared a single lock.</p>

<p>When SQLite tries to open a database and finds that it is locked, it
can optionally delay for a short while and try to open the file again.
This process repeats until the query times out and SQLite returns a
failure.  The timeout is adjustable.  It is set to 0 by default so that
if the database is locked, the SQL statement fails immediately.  But you
can use the "timeout" method to change the timeout value to a positive
number.  For example:</p>

<blockquote><b>db1 timeout 2000</b></blockquote>

<p>The argument to the timeout method is the maximum number of milliseconds
to wait for the lock to clear.  So in the example above, the maximum delay
would be 2 seconds.</p>
<a name="busy"></a>
<h3>The "busy" method</h3>


<p>The "busy" method, like "timeout", only comes into play when the
database is locked.  But the "busy" method gives the programmer much more
control over what action to take.  The "busy" method specifies a callback
Tcl procedure that is invoked whenever SQLite tries to open a locked
database.  This callback can do whatever is desired.  Presumably, the
callback will do some other useful work for a short while (such as service
GUI events) then return
so that the lock can be tried again.  The callback procedure should
return "0" if it wants SQLite to try again to open the database and
should return "1" if it wants SQLite to abandon the current operation.
<a name="enable_load_extension"></a>
<h3>The "enable_load_extension" method</h3>


<p>The extension loading mechanism of SQLite (accessed using the
<a href="lang_corefunc.html#load_extension">load_extension()</a> SQL function) is turned off by default.  This is
a security precaution.  If an application wants to make use of the
<a href="lang_corefunc.html#load_extension">load_extension()</a> function it must first turn the capability on using
this method.</p>

<p>This method takes a single boolean argument which will turn the
extension loading functionality on or off.</p>

<p>This method maps to the <a href="c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a> C/C++
interface.</p>
<a name="exists"></a>
<h3>The "exists" method</h3>


<p>The "exists" method is similar to "onecolumn" and "eval" in that
it executes SQL statements.  The difference is that the "exists" method
always returns a boolean value which is TRUE if a query in the SQL
statement it executes returns one or more rows and FALSE if the SQL
returns an empty set.</p>

<p>The "exists" method is often used to test for the existence of
rows in a table.  For example:</p>

<blockquote><b>
if {&#91;db exists {SELECT 1 FROM table1 WHERE user=$user}&#93;} {<br>
&nbsp;&nbsp;&nbsp;# Processing if $user exists<br>
} else {<br>
&nbsp;&nbsp;&nbsp;# Processing if $user does not exist<br>
}
</b></blockquote>
<a name="last_insert_rowid"></a>
<h3>The "last_insert_rowid" method</h3>


<p>The "last_insert_rowid" method returns an integer which is the ROWID
of the most recently inserted database row.</p>
<a name="function"></a>
<h3>The "function" method</h3>


<p>The "function" method registers new SQL functions with the SQLite engine.
The arguments are the name of the new SQL function and a TCL command that
implements that function.  Arguments to the function are appended to the
TCL command before it is invoked.</p>

<p>
The following example creates a new SQL function named "hex" that converts
its numeric argument in to a hexadecimal encoded string:
</p>

<blockquote><b>
db function hex {format 0x%X}
</b></blockquote>

<a name="nullvalue"></a>
<h3>The "nullvalue" method</h3>


<p>
The "nullvalue" method changes the representation for NULL returned
as result of the "eval" method.</p>

<blockquote><b>
db1 nullvalue NULL
</b></blockquote>

<p>The "nullvalue" method is useful to differ between NULL and empty
column values as Tcl lacks a NULL representation.  The default
representation for NULL values is an empty string.</p>
<a name="onecolumn"></a>
<h3>The "onecolumn" method</h3>


<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>&#91;lindex&nbsp;...&nbsp;0&#93;</tt>" on the results of an "eval"
in order to extract a single column result.</p>
<a name="changes"></a>
<h3>The "changes" method</h3>


<p>The "changes" method returns an integer which is the number of rows
in the database that were inserted, deleted, and/or modified by the most
recent "eval" method.</p>
<a name="total_changes"></a>
<h3>The "total_changes" method</h3>


<p>The "total_changes" method returns an integer which is the number of rows
in the database that were inserted, deleted, and/or modified since the
current database connection was first opened.</p>
<a name="authorizer"></a>
<h3>The "authorizer" method</h3>


<p>The "authorizer" method provides access to the 
<a href="c3ref/set_authorizer.html">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.
</p>

<p>If the argument is an empty string then the authorizer is disabled.
If the argument is omitted, then the current authorizer is returned.</p>
<a name="progress"></a>
<h3>The "progress" method</h3>


<p>This method registers a callback that is invoked periodically during
query processing.  There are two arguments: the number of SQLite virtual
machine opcodes between invocations, and the TCL command to invoke.
Setting the progress callback to an empty string disables it.</p>

<p>The progress callback can be used to display the status of a lengthy
query or to process GUI events during a lengthy query.</p>
<a name="collate"></a>
<h3>The "collate" method</h3>


<p>This method registers new text collating sequences.  There are
two arguments: the name of the collating sequence and the name of a
TCL procedure that implements a comparison function for the collating
sequence.
</p>

<p>For example, the following code implements a collating sequence called
"NOCASE" that sorts in text order without regard to case:
</p>

<blockquote><b>
proc nocase_compare {a b} {<br>
&nbsp;&nbsp;&nbsp;&nbsp;return &#91;string compare &#91;string tolower $a&#93; &#91;string tolower $b&#93;&#93;<br>
}<br>
db collate NOCASE nocase_compare<br>
</b></blockquote>
<a name="collation_needed"></a>
<h3>The "collation_needed" method</h3>


<p>This method registers a callback routine that is invoked when the SQLite
engine needs a particular collating sequence but does not have that
collating sequence registered.  The callback can register the collating
sequence.  The callback is invoked with a single parameter which is the
name of the needed collating sequence.</p>
<a name="commit_hook"></a>
<h3>The "commit_hook" method</h3>


<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>
<a name="rollback_hook"></a>
<h3>The "rollback_hook" method</h3>


<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>
<a name="status"></a>
<h3>The "status" method</h3>

<p>This method returns status information from the most recently evaluated
SQL statement.  The status method takes a single argument which should be
either "steps" or "sorts".  If the argument is "steps", then the method
returns the number of full table scan steps that the previous SQL statement
evaluated.  If the argument is "sorts", the method returns the number of
sort operations.  This information can be used to detect queries that are
not using indices to speed search or sorting.</p>

<p>The status method is basically a wrapper on the
<a href="c3ref/stmt_status.html">sqlite3_stmt_status()</a> C-language interface.</p>
<a name="update_hook"></a>
<h3>The "update_hook" method</h3>


<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>
<a name="incrblob"></a>
<h3>The "incrblob" method</h3>


<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="c3ref/blob_open.html">sqlite3_blob_open()</a> C-language
interface.  Close the channel using the <b>close</b> command of TCL.
</p>
<a name="errorcode"></a>
<h3>The "errorcode" method</h3>


<p>This method returns the numeric error code that resulted from the most
recent SQLite operation.</p>
<a name="trace"></a>
<h3>The "trace" method</h3>


<p>The "trace" method registers a callback that is invoked as each SQL
statement is compiled.  The text of the SQL is appended as a single string
to the command before it is invoked.  This can be used (for example) to
keep a log of all SQL operations that an application performs.
</p>
<a name="backup"></a>
<h3>The "backup" method</h3>


<p>The "backup" method makes a backup copy of a live database.  The
command syntax is like this:</p>

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>backup</b>&nbsp;&nbsp;?<i>source-database</i>?&nbsp;&nbsp;<i>backup-filename</i>
</blockquote>

<p>The optional <i>source-database</i> argument tells which database in
the current connection should be backed up.  The default value is <b>main</b>
(or, in other words, the primary database file).  To back up TEMP tables
use <b>temp</b>.  To backup an auxiliary database added to the connection
using the <a href="lang_attach.html">ATTACH</a> command, use the name of that database as it was assigned
in the <a href="lang_attach.html">ATTACH</a> command.</p>

<p>The <i>backup-filename</i> is the name of a file into which the backup is
written.  <i>Backup-filename</i> does not have to exist ahead of time, but if
it does, it must be a well-formed SQLite database.</p>
<a name="restore"></a>
<h3>The "restore" method</h3>


<p>The "restore" method copies the content a separate database file 
into the current database connection, overwriting any preexisting content.
The command syntax is like this:</p>

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>restore</b>&nbsp;&nbsp;?<i>target-database</i>?&nbsp;&nbsp;<i>source-filename</i>
</blockquote>

<p>The optional <i>target-database</i> argument tells which database in
the current connection should be overwritten with new content.  
The default value is <b>main</b> 
(or, in other words, the primary database file).  To repopulate the TEMP tables
use <b>temp</b>.  To overwrite an auxiliary database added to the connection
using the <a href="lang_attach.html">ATTACH</a> command, use the name of that database as it was assigned
in the <a href="lang_attach.html">ATTACH</a> command.</p>

<p>The <i>source-filename</i> is the name of an existing well-formed SQLite
database file from which the content is extracted.</p>
<a name="version"></a>
<h3>The "version" method</h3>

  Return the current library version. For example, "3.6.17".
<a name="profile"></a>
<h3>The "profile" method</h3>

<p>This method is used to profile the execution of SQL statements run by
   the application. The syntax is as follows:
</p>

<blockquote>
<i>dbcmd</i>&nbsp;&nbsp;<b>profile</b>&nbsp;&nbsp;?<i>script</i>
</blockquote>

<p>Unless <i>script</i> is an empty string, this method arranges for the
<i>script</i> to be evaluated after the execution of each SQL statement.
Two arguments are appended to <i>script</i> before it is invoked: the
text of the SQL statement executed and the time elapsed while executing
the statement, in nanoseconds.
</p>
<p>A database handle may only have a single profile script registered at
any time. If there is already a script registered when the profile method
is invoked, the previous profile script is replaced by the new one. If the 
<i>script</i> argument is an empty string, any previously registered 
profile callback is canceled but no new profile script is registered.
</p>