SQLite

**    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;
  }

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

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