set rcsid {$Id: capi3ref.tcl,v 1.38 2006/04/05 01:08:35 drh Exp $}source common.tclheader {C/C++ Interface For SQLite Version 3}puts {<h2>C/C++ Interface For SQLite Version 3</h2>}proc api {name prototype desc {notused x}} {  global apilist  if {$name==""} {    regsub -all {sqlite3_[a-z0-9_]+\(} $prototype \      {[lappend name [string trimright & (]]} x1    subst $x1  }  lappend apilist [list $name $prototype $desc]}api {result-codes} {#define SQLITE_OK           0   /* Successful result */#define SQLITE_ERROR        1   /* SQL error or missing database */#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */#define SQLITE_PERM         3   /* Access permission denied */#define SQLITE_ABORT        4   /* Callback routine requested an abort */#define SQLITE_BUSY         5   /* The database file is locked */#define SQLITE_LOCKED       6   /* A table in the database is locked */#define SQLITE_NOMEM        7   /* A malloc() failed */#define SQLITE_READONLY     8   /* Attempt to write a readonly database */#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */#define SQLITE_CORRUPT     11   /* The database disk image is malformed */#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */#define SQLITE_FULL        13   /* Insertion failed because database is full */#define SQLITE_CANTOPEN    14   /* Unable to open the database file */#define SQLITE_PROTOCOL    15   /* Database lock protocol error */#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */#define SQLITE_SCHEMA      17   /* The database schema changed */#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */#define SQLITE_MISMATCH    20   /* Data type mismatch */#define SQLITE_MISUSE      21   /* Library used incorrectly */#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */#define SQLITE_AUTH        23   /* Authorization denied */#define SQLITE_ROW         100  /* sqlite_step() has another row ready */#define SQLITE_DONE        101  /* sqlite_step() has finished executing */} {Many SQLite functions return an integer result code from the set shownabove in order to indicates success or failure.}api {} {  const char *sqlite3_libversion(void);} {  Return a pointer to a string which contains the version number of  the library.  The same string is available in the global  variable named "sqlite3_version".  This interface is provided since  windows is unable to access global variables in DLLs.}api {} {  void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);} {  Aggregate functions use this routine to allocate  a structure for storing their state.  The first time this routine  is called for a particular aggregate, a new structure of size nBytes  is allocated, zeroed, and returned.  On subsequent calls (for the  same aggregate instance) the same buffer is returned.  The implementation  of the aggregate can use the returned buffer to accumulate data.  The buffer allocated is freed automatically by SQLite.}api {} {  int sqlite3_aggregate_count(sqlite3_context*);} {  This function is deprecated.   It continues to exist so as not to  break any legacy code that might happen to use it.  But it should not  be used in any new code.  In order to encourage people to not use this function, we are not going  to tell you what it does.}api {} {  int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));  int sqlite3_bind_double(sqlite3_stmt*, int, double);  int sqlite3_bind_int(sqlite3_stmt*, int, int);  int sqlite3_bind_int64(sqlite3_stmt*, int, long long int);  int sqlite3_bind_null(sqlite3_stmt*, int);  int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));  int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));  #define SQLITE_STATIC      ((void(*)(void *))0)  #define SQLITE_TRANSIENT   ((void(*)(void *))-1)} { In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(), one or more literals can be replace by a parameter "?" or ":AAA" or "\$VVV" where AAA is an alphanumeric identifier and VVV is a variable name according to the syntax rules of the TCL programming language. The values of these parameters (also called "host parameter names") can be set using the sqlite3_bind_*() routines. The first argument to the sqlite3_bind_*() routines always is a pointer to the sqlite3_stmt structure returned from sqlite3_prepare().  The second argument is the index of the parameter to be set.  The first parameter has an index of 1. When the same named parameter is used more than once, second and subsequent occurrences have the same index as the first occurrence.  The index for named parameters can be looked up using the sqlite3_bind_parameter_name() API if desired. The third argument is the value to bind to the parameter. In those routines that have a fourth argument, its value is the number of bytes in the parameter.  To be clear: the value is the number of bytes in the string, not the number of characters.  The number of bytes does not include the zero-terminator at the end of strings. If the fourth parameter is negative, the length of the string is number of bytes up to the first zero terminator. The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and sqlite3_bind_text16() is a destructor used to dispose of the BLOB or text after SQLite has finished with it.  If the fifth argument is the special value SQLITE_STATIC, then the library assumes that the information is in static, unmanaged space and does not need to be freed.  If the fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its own private copy of the data before returning. The sqlite3_bind_*() routines must be called after sqlite3_prepare() or sqlite3_reset() and before sqlite3_step(). Bindings are not cleared by the sqlite3_reset() routine. Unbound parameters are interpreted as NULL. These routines return SQLITE_OK on success or an error code if anything goes wrong.  SQLITE_RANGE is returned if the parameter index is out of range.  SQLITE_NOMEM is returned if malloc fails. SQLITE_MISUSE is returned if these routines are called on a virtual machine that is the wrong state or which has already been finalized.}api {} {  int sqlite3_bind_parameter_count(sqlite3_stmt*);} {  Return the number of parameters in the precompiled statement given as  the argument.}api {} {  const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int n);} {  Return the name of the n-th parameter in the precompiled statement.  Parameters of the form ":AAA" or "\$VVV" have a name which is the  string ":AAA" or "\$VVV".  In other words, the initial ":" or "$"  is included as part of the name.  Parameters of the form "?" have no name.  If the value n is out of range or if the n-th parameter is nameless,  then NULL is returned.  The returned string is always in the  UTF-8 encoding.}api {} {  int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);} {  Return the index of the parameter with the given name.  The name must match exactly.  If there is no parameter with the given name, return 0.  The string zName is always in the UTF-8 encoding.}api {} {  int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);} { This routine identifies a callback function that might be invoked whenever an attempt is made to open a database table  that another thread or process has locked. If the busy callback is NULL, then SQLITE_BUSY is returned immediately upon encountering the lock. If the busy callback is not NULL, then the callback will be invoked with two arguments.  The second argument is the number of prior calls to the busy callback for the same lock.  If the busy callback returns 0, then no additional attempts are made to access the database and SQLITE_BUSY is returned. If the callback returns non-zero, then another attempt is made to open the database for reading and the cycle repeats. The presence of a busy handler does not guarantee that it will be invoked when there is lock contention. If SQLite determines that invoking the busy handler could result in a deadlock, it will return SQLITE_BUSY instead. Consider a scenario where one process is holding a read lock that it is trying to promote to a reserved lock and a second process is holding a reserved lock that it is trying to promote to an exclusive lock.  The first process cannot proceed because it is blocked by the second and the second process cannot proceed because it is blocked by the first.  If both processes invoke the busy handlers, neither will make any progress.  Therefore, SQLite returns SQLITE_BUSY for the first process, hoping that this will induce the first process to release its read lock and allow the second process to proceed. The default busy callback is NULL. Sqlite is re-entrant, so the busy handler may start a new query.  (It is not clear why anyone would every want to do this, but it is allowed, in theory.)  But the busy handler may not close the database.  Closing the database from a busy handler will delete  data structures out from under the executing query and will  probably result in a coredump.}api {} {  int sqlite3_busy_timeout(sqlite3*, int ms);} { This routine sets a busy handler that sleeps for a while when a table is locked.  The handler will sleep multiple times until  at least "ms" milliseconds of sleeping have been done.  After "ms" milliseconds of sleeping, the handler returns 0 which causes sqlite3_exec() to return SQLITE_BUSY. Calling this routine with an argument less than or equal to zero turns off all busy handlers.}api {} {  int sqlite3_changes(sqlite3*);} { This function returns the number of database rows that were changed (or inserted or deleted) by the most recently completed INSERT, UPDATE, or DELETE statement.  Only changes that are directly specified by the INSERT, UPDATE, or DELETE statement are counted.  Auxiliary changes caused by triggers are not counted.  Use the sqlite3_total_changes() function to find the total number of changes including changes caused by triggers. Within the body of a trigger, the sqlite3_changes() function does work to report the number of rows that were changed for the most recently completed INSERT, UPDATE, or DELETE statement within the trigger body. SQLite implements the command "DELETE FROM table" without a WHERE clause by dropping and recreating the table.  (This is much faster than going through and deleting individual elements from the table.)  Because of this optimization, the change count for "DELETE FROM table" will be zero regardless of the number of elements that were originally in the table. To get an accurate count of the number of rows deleted, use "DELETE FROM table WHERE 1" instead.}api {} {  int sqlite3_total_changes(sqlite3*);} {  This function returns the total number of database rows that have  be modified, inserted, or deleted since the database connection was  created using sqlite3_open().  All changes are counted, including  changes by triggers and changes to TEMP and auxiliary databases.  Except, changes to the SQLITE_MASTER table (caused by statements   such as CREATE TABLE) are not counted.  Nor are changes counted when  an entire table is deleted using DROP TABLE.  See also the sqlite3_changes() API.  SQLite implements the command "DELETE FROM table" without a WHERE clause  by dropping and recreating the table.  (This is much faster than going  through and deleting individual elements form the table.)  Because of  this optimization, the change count for "DELETE FROM table" will be  zero regardless of the number of elements that were originally in the  table. To get an accurate count of the number of rows deleted, use  "DELETE FROM table WHERE 1" instead.}api {} {  int sqlite3_close(sqlite3*);} {  Call this function with a pointer to a structure that was previously  returned from sqlite3_open() or sqlite3_open16()  and the corresponding database will by closed.  SQLITE_OK is returned if the close is successful.  If there are  prepared statements that have not been finalized, then SQLITE_BUSY  is returned.  SQLITE_ERROR might be returned if the argument is not  a valid connection pointer returned by sqlite3_open() or if the connection  pointer has been closed previously.}api {} {const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);int sqlite3_column_bytes(sqlite3_stmt*, int iCol);int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);double sqlite3_column_double(sqlite3_stmt*, int iCol);int sqlite3_column_int(sqlite3_stmt*, int iCol);long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);int sqlite3_column_type(sqlite3_stmt*, int iCol);#define SQLITE_INTEGER  1#define SQLITE_FLOAT    2#define SQLITE_TEXT     3#define SQLITE_BLOB     4#define SQLITE_NULL     5} { These routines return information about the information in a single column of the current result row of a query.  In every case the first argument is a pointer to the SQL statement that is being executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and the second argument is the index of the column for which information  should be returned.  iCol is zero-indexed.  The left-most column has an index of 0.