Move bundled copy of sqlite one level deeper to better separate it...

third_party/sqlite/www/capi3ref.tcl

-set rcsid {$Id: capi3ref.tcl,v 1.60 2007/05/19 06:48:43 danielk1977 Exp $}
-source common.tcl
-header {C/C++ Interface For SQLite Version 3}
-puts {
-<h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>
-}
-
-proc api {name prototype desc {notused x}} {
-  global apilist specialname
-  if {$name==""} {
-    regsub -all {sqlite3_[a-z0-9_]+\(} $prototype \
-      {[lappend name [string trimright & (]]} x1
-    subst $x1
-  } else {
-    lappend specialname $name
-  }
-  lappend apilist [list $name $prototype $desc]
-}
-
-api {extended-result-codes} {
-#define SQLITE_IOERR_READ       
-#define SQLITE_IOERR_SHORT_READ 
-#define SQLITE_IOERR_WRITE      
-#define SQLITE_IOERR_FSYNC      
-#define SQLITE_IOERR_DIR_FSYNC  
-#define SQLITE_IOERR_TRUNCATE   
-#define SQLITE_IOERR_FSTAT      
-#define SQLITE_IOERR_UNLOCK     
-#define SQLITE_IOERR_RDLOCK     
-...
-} {
-In its default configuration, SQLite API routines return one of 26 integer
-result codes described at result-codes.  However, experience has shown that
-many of these result codes are too course-grained.  They do not provide as
-much information about problems as users might like.  In an effort to
-address this, newer versions of SQLite (version 3.3.8 and later) include
-support for additional result codes that provide more detailed information
-about errors.  The extended result codes are enabled (or disabled) for 
-each database
-connection using the sqlite3_extended_result_codes() API.
-
-Some of the available extended result codes are listed above.
-We expect the number of extended result codes will be expand
-over time.  Software that uses extended result codes should expect
-to see new result codes in future releases of SQLite.
-
-The symbolic name for an extended result code always contains a related
-primary result code as a prefix.  Primary result codes contain a single
-"_" character.  Extended result codes contain two or more "_" characters.
-The numeric value of an extended result code can be converted to its
-corresponding primary result code by masking off the lower 8 bytes.
-
-A complete list of available extended result codes and
-details about the meaning of the various extended result codes can be
-found by consulting the C code, especially the sqlite3.h header
-file and its antecedent sqlite.h.in.  Additional information
-is also available at the SQLite wiki:
-http://www.sqlite.org/cvstrac/wiki?p=ExtendedResultCodes
-}
-
-
-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 shown
-above in order to indicates success or failure.
-
-The result codes above are the only ones returned by SQLite in its
-default configuration.  However, the sqlite3_extended_result_codes()
-API can be used to set a database connectoin to return more detailed
-result codes.  See the documentation on sqlite3_extended_result_codes()
-or extended-result-codes for additional information.
-}
-
-api {} {
-  int sqlite3_extended_result_codes(sqlite3*, int onoff);
-} {
-This routine enables or disabled extended-result-codes feature.
-By default, SQLite API routines return one of only 26 integer
-result codes described at result-codes.  When extended result codes
-are enabled by this routine, the repetoire of result codes can be
-much larger and can (hopefully) provide more detailed information
-about the cause of an error.
-
-The second argument is a boolean value that turns extended result
-codes on and off.  Extended result codes are off by default for
-backwards compatibility with older versions of SQLite.
-}
-
-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 is freed automatically by SQLite when the query that
-  invoked the aggregate function terminates.
-}
-
-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_v2() and sqlite3_prepare16_v2(),
- one or more literals can be replace by a parameter "?" or "?NNN"
- or ":AAA" or "@AAA" or "\$VVV" where NNN is an integer literal,
- 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_v2().  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 index for "?NNN"
- parametes is the value of NNN.  The NNN value must be between 1 and 999.
-
-
- 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 immediately, before the sqlite3_bind_*()
- routine returns.
-
- The sqlite3_bind_*() routines must be called after
- sqlite3_prepare_v2() 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 "@AAA" or "\$VVV" have a name which is the
-  string ":AAA" or "@AAA" or "\$VVV".  
-  In other words, the initial ":" or "$" or "@"
-  is included as part of the name.
-  Parameters of the form "?" or "?NNN" have no name.
-
-  The first bound parameter has an index of 1, not 0.
-
-  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 even if the named parameter was originally specified
-  as UTF-16 in sqlite3_prepare16_v2().
-}
-
-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
- first argument to the handler is a copy of the void* pointer which
- is the third argument to this routine.  The second argument to
- the handler is the number of times that the busy handler has
- been invoked for this locking event. 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.
-
- There can only be a single busy handler defined for each database
- connection.  Setting a new busy handler clears any previous one.
- Note that calling sqlite3_busy_timeout() will also set or clear
- the busy handler.
-}
-
-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.
-
- There can only be a single busy handler for a particular database
- connection.  If another busy handler was defined  
- (using sqlite3_busy_handler()) prior to calling
- this routine, that other busy handler is cleared.
-}
-
-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_v2()) 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.
-
- If the SQL statement is not currently point to a valid row, or if the
- the column index is out of range, the result is undefined.
-
- The sqlite3_column_type() routine returns the initial data type
- of the result column.  The returned value is one of SQLITE_INTEGER,
- SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL.  The value
- returned by sqlite3_column_type() is only meaningful if no type
- conversions have occurred as described below.  After a type conversion,
- the value returned by sqlite3_column_type() is undefined.  Future
- versions of SQLite may change the behavior of sqlite3_column_type()
- following a type conversion.
-
- If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 
- routine returns the number of bytes in that BLOB or string.
- If the result is a UTF-16 string, then sqlite3_column_bytes() converts
- the string to UTF-8 and then returns the number of bytes.
- If the result is a numeric value then sqlite3_column_bytes() uses
- sqlite3_snprintf() to convert that value to a UTF-8 string and returns
- the number of bytes in that string.
- The value returned does
- not include the \\000 terminator at the end of the string.  
-
- The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
- but leaves the result in UTF-16 instead of UTF-8.  
- The \\u0000 terminator is not included in this count.
-
- These routines attempt to convert the value where appropriate.  For
- example, if the internal representation is FLOAT and a text result
- is requested, sqlite3_snprintf() is used internally to do the conversion
- automatically.  The following table details the conversions that
- are applied:
-
-<blockquote>
-<table border="1">
-<tr><th>Internal Type</th><th>Requested Type</th><th>Conversion</th></tr>
-<tr><td> NULL    </td><td> INTEGER</td><td>Result is 0</td></tr>
-<tr><td> NULL </td><td>    FLOAT </td><td> Result is 0.0</td></tr>
-<tr><td> NULL </td><td>    TEXT </td><td>  Result is NULL pointer</td></tr>
-<tr><td> NULL </td><td>    BLOB </td><td>  Result is NULL pointer</td></tr>
-<tr><td> INTEGER </td><td> FLOAT </td><td> Convert from integer to float</td></tr>
-<tr><td> INTEGER </td><td> TEXT </td><td>  ASCII rendering of the integer</td></tr>
-<tr><td> INTEGER </td><td> BLOB </td><td>  Same as for INTEGER->TEXT</td></tr>
-<tr><td> FLOAT </td><td>   INTEGER</td><td>Convert from float to integer</td></tr>
-<tr><td> FLOAT </td><td>   TEXT </td><td>  ASCII rendering of the float</td></tr>
-<tr><td> FLOAT </td><td>   BLOB </td><td>  Same as FLOAT->TEXT</td></tr>
-<tr><td> TEXT </td><td>    INTEGER</td><td>Use atoi()</td></tr>
-<tr><td> TEXT </td><td>    FLOAT </td><td> Use atof()</td></tr>
-<tr><td> TEXT </td><td>    BLOB </td><td>  No change</td></tr>
-<tr><td> BLOB </td><td>    INTEGER</td><td>Convert to TEXT then use atoi()</td></tr>
-<tr><td> BLOB </td><td>    FLOAT </td><td> Convert to TEXT then use atof()</td></tr>
-<tr><td> BLOB </td><td>    TEXT </td><td>  Add a \\000 terminator if needed</td></tr>
-</table>
-</blockquote>
-
-  Note that when type conversions occur, pointers returned by prior
-  calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
-  sqlite3_column_text16() may be invalidated. 
-  Type conversions and pointer invalidations might occur
-  in the following cases:
-
-  <ul>
-  <li><p>
-  The initial content is a BLOB and sqlite3_column_text() 
-  or sqlite3_column_text16()
-  is called.  A zero-terminator might need to be added to the string.
-  </p></li>
-  <li><p>
-  The initial content is UTF-8 text and sqlite3_column_bytes16() or
-  sqlite3_column_text16() is called.  The content must be converted to UTF-16.
-  </p></li>
-  <li><p>
-  The initial content is UTF-16 text and sqlite3_column_bytes() or
-  sqlite3_column_text() is called.  The content must be converted to UTF-8.
-  </p></li>
-  </ul>
-
-  Conversions between UTF-16be and UTF-16le 
-  are always done in place and do
-  not invalidate a prior pointer, though of course the content of the buffer
-  that the prior pointer points to will have been modified.  Other kinds
-  of conversion are done in place when it is possible, but sometime it is
-  not possible and in those cases prior pointers are invalidated.  
-
-  The safest and easiest to remember policy is to invoke these routines
-  in one of the following ways:
-
-  <ul>
-  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
-  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
-  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
-  </ul>
-
-  In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
-  or sqlite3_column_text16() first to force the result into the desired
-  format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
-  find the size of the result.  Do not mix call to sqlite3_column_text() or
-  sqlite3_column_blob() with calls to sqlite3_column_bytes16().  And do not
-  mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
-}
-
-api {} {
-int sqlite3_column_count(sqlite3_stmt *pStmt);
-} {
- Return the number of columns in the result set returned by the prepared
- SQL statement. This routine returns 0 if pStmt is an SQL statement
- that does not return data (for example an UPDATE).
-
- See also sqlite3_data_count().
-}
-
-api {} {
-const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
-const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
-} {
- The first argument is a prepared SQL statement. If this statement
- is a SELECT statement, the Nth column of the returned result set 
- of the SELECT is a table column then the declared type of the table
- column is returned. If the Nth column of the result set is not a table
- column, then a NULL pointer is returned. The returned string is 
- UTF-8 encoded for sqlite3_column_decltype() and UTF-16 encoded
- for sqlite3_column_decltype16(). For example, in the database schema:
-
- <blockquote><pre>
- CREATE TABLE t1(c1 INTEGER);
- </pre></blockquote>
-
- And the following statement compiled:
-
- <blockquote><pre>
- SELECT c1 + 1, c1 FROM t1;
- </pre></blockquote>
-
- Then this routine would return the string "INTEGER" for the second
- result column (i==1), and a NULL pointer for the first result column
- (i==0).
-
- If the following statements were compiled then this routine would
- return "INTEGER" for the first (only) result column.
-
- <blockquote><pre>
- SELECT (SELECT c1) FROM t1;
- SELECT (SELECT c1 FROM t1);
- SELECT c1 FROM (SELECT c1 FROM t1);
- SELECT * FROM (SELECT c1 FROM t1);
- SELECT * FROM (SELECT * FROM t1);
- </pre></blockquote>
-}
-
-api {} {
-  int sqlite3_table_column_metadata(
-    sqlite3 *db,                /* Connection handle */
-    const char *zDbName,        /* Database name or NULL */
-    const char *zTableName,     /* Table name */
-    const char *zColumnName,    /* Column name */
-    char const **pzDataType,    /* OUTPUT: Declared data type */
-    char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
-    int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
-    int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
-    int *pAutoinc               /* OUTPUT: True if colums is auto-increment */
-  );
-} {
- This routine is used to obtain meta information about a specific column of a
- specific database table accessible using the connection handle passed as the
- first function argument.
-
- The column is identified by the second, third and fourth parameters to 
- this function. The second parameter is either the name of the database
- (i.e. "main", "temp" or an attached database) containing the specified
- table or NULL. If it is NULL, then all attached databases are searched
- for the table using the same algorithm as the database engine uses to 
- resolve unqualified table references.
-
- The third and fourth parameters to this function are the table and column 
- name of the desired column, respectively. Neither of these parameters 
- may be NULL.
-
- Meta information is returned by writing to the memory locations passed as
- the 5th and subsequent parameters to this function. Any of these 
- arguments may be NULL, in which case the corresponding element of meta 
- information is ommitted.
-
-<pre>
- Parameter     Output Type      Description
- -----------------------------------
-   5th         const char*      Declared data type 
-   6th         const char*      Name of the columns default collation sequence 
-   7th         int              True if the column has a NOT NULL constraint
-   8th         int              True if the column is part of the PRIMARY KEY
-   9th         int              True if the column is AUTOINCREMENT
-</pre>
-
- The memory pointed to by the character pointers returned for the 
- declaration type and collation sequence is valid only until the next 
- call to any sqlite API function.
-
- This function may load one or more schemas from database files. If an
- error occurs during this process, or if the requested table or column
- cannot be found, an SQLITE error code is returned and an error message
- left in the database handle (to be retrieved using sqlite3_errmsg()).
- Specifying an SQL view instead of a table as the third argument is also
- considered an error.
-
- If the specified column is "rowid", "oid" or "_rowid_" and an 
- INTEGER PRIMARY KEY column has been explicitly declared, then the output 
- parameters are set for the explicitly declared column. If there is no
- explicitly declared IPK column, then the data-type is "INTEGER", the
- collation sequence "BINARY" and the primary-key flag is set. Both
- the not-null and auto-increment flags are clear.
-
- This API is only available if the library was compiled with the
- SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
-}
-
-api {} {
-const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N);
-const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N);
-} {
-If the Nth column returned by statement pStmt is a column reference,
-these functions may be used to access the name of the database (either 
-"main", "temp" or the name of an attached database) that contains
-the column. If the Nth column is not a column reference, NULL is
-returned.
-
-See the description of function sqlite3_column_decltype() for a
-description of exactly which expressions are considered column references.
-
-Function sqlite3_column_database_name() returns a pointer to a UTF-8
-encoded string. sqlite3_column_database_name16() returns a pointer
-to a UTF-16 encoded string. 
-}
-
-api {} {
-const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N);
-const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N);
-} {
-If the Nth column returned by statement pStmt is a column reference,
-these functions may be used to access the schema name of the referenced 
-column in the database schema. If the Nth column is not a column 
-reference, NULL is returned.
-
-See the description of function sqlite3_column_decltype() for a
-description of exactly which expressions are considered column references.
-
-Function sqlite3_column_origin_name() returns a pointer to a UTF-8
-encoded string. sqlite3_column_origin_name16() returns a pointer
-to a UTF-16 encoded string. 
-}
-
-api {} {
-const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N);
-const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N);
-} {
-If the Nth column returned by statement pStmt is a column reference, 
-these functions may be used to access the name of the table that 
-contains the column.  If the Nth column is not a column reference, 
-NULL is returned.
-
-See the description of function sqlite3_column_decltype() for a
-description of exactly which expressions are considered column references.
-
-Function sqlite3_column_table_name() returns a pointer to a UTF-8
-encoded string. sqlite3_column_table_name16() returns a pointer
-to a UTF-16 encoded string. 
-}
-
-api {} {
-const char *sqlite3_column_name(sqlite3_stmt*,int);
-const void *sqlite3_column_name16(sqlite3_stmt*,int);
-} {
- The first argument is a prepared SQL statement. This function returns
- the column heading for the Nth column of that statement, where N is the
- second function argument.  The string returned is UTF-8 for
- sqlite3_column_name() and UTF-16 for sqlite3_column_name16().
-}
-
-api {} {
-void *sqlite3_commit_hook(sqlite3*, int(*xCallback)(void*), void *pArg);
-} {
- <i>Experimental</i>
-
- Register a callback function to be invoked whenever a new transaction
- is committed.  The pArg argument is passed through to the callback.
- callback.  If the callback function returns non-zero, then the commit
- is converted into a rollback.
-
- If another function was previously registered, its pArg value is returned.
- Otherwise NULL is returned.
-
- Registering a NULL function disables the callback.  Only a single commit
- hook callback can be registered at a time.
-}
-
-api {} {
-int sqlite3_complete(const char *sql);
-int sqlite3_complete16(const void *sql);
-} {
- These functions return true if the given input string comprises
- one or more complete SQL statements.
- The argument must be a nul-terminated UTF-8 string for sqlite3_complete()
- and a nul-terminated UTF-16 string for sqlite3_complete16().
-
- These routines do not check to see if the SQL statement is well-formed.
- They only check to see that the statement is terminated by a semicolon
- that is not part of a string literal and is not inside
- the body of a trigger.
-} {}
-
-api {} {
-int sqlite3_create_collation(
-  sqlite3*, 
-  const char *zName, 
-  int pref16, 
-  void*,
-  int(*xCompare)(void*,int,const void*,int,const void*)
-);
-int sqlite3_create_collation16(
-  sqlite3*, 
-  const char *zName, 
-  int pref16, 
-  void*,
-  int(*xCompare)(void*,int,const void*,int,const void*)
-);
-#define SQLITE_UTF8     1
-#define SQLITE_UTF16BE  2
-#define SQLITE_UTF16LE  3
-#define SQLITE_UTF16    4
-} {
- These two functions are used to add new collation sequences to the
- sqlite3 handle specified as the first argument. 
-
- The name of the new collation sequence is specified as a UTF-8 string
- for sqlite3_create_collation() and a UTF-16 string for
- sqlite3_create_collation16(). In both cases the name is passed as the
- second function argument.
-
- The third argument must be one of the constants SQLITE_UTF8,
- SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied
- routine expects to be passed pointers to strings encoded using UTF-8,
- UTF-16 little-endian or UTF-16 big-endian respectively.  The
- SQLITE_UTF16 constant indicates that text strings are expected in
- UTF-16 in the native byte order of the host machine.
-
- A pointer to the user supplied routine must be passed as the fifth
- argument. If it is NULL, this is the same as deleting the collation
- sequence (so that SQLite cannot call it anymore). Each time the user
- supplied function is invoked, it is passed a copy of the void* passed as
- the fourth argument to sqlite3_create_collation() or
- sqlite3_create_collation16() as its first argument.
-
- The remaining arguments to the user-supplied routine are two strings,
- each represented by a [length, data] pair and encoded in the encoding
- that was passed as the third argument when the collation sequence was
- registered. The user routine should return negative, zero or positive if
- the first string is less than, equal to, or greater than the second
- string. i.e. (STRING1 - STRING2).
-}
-
-api {} {
-int sqlite3_collation_needed(
-  sqlite3*, 
-  void*, 
-  void(*)(void*,sqlite3*,int eTextRep,const char*)
-);
-int sqlite3_collation_needed16(
-  sqlite3*, 
-  void*,
-  void(*)(void*,sqlite3*,int eTextRep,const void*)
-);
-} {
- To avoid having to register all collation sequences before a database
- can be used, a single callback function may be registered with the
- database handle to be called whenever an undefined collation sequence is
- required.
-
- If the function is registered using the sqlite3_collation_needed() API,
- then it is passed the names of undefined collation sequences as strings
- encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
- are passed as UTF-16 in machine native byte order. A call to either
- function replaces any existing callback.
-
- When the user-function is invoked, the first argument passed is a copy
- of the second argument to sqlite3_collation_needed() or
- sqlite3_collation_needed16(). The second argument is the database
- handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or
- SQLITE_UTF16LE, indicating the most desirable form of the collation
- sequence function required. The fourth argument is the name of the
- required collation sequence.
-
- The collation sequence is returned to SQLite by a collation-needed
- callback using the sqlite3_create_collation() or
- sqlite3_create_collation16() APIs, described above.
-}
-
-api {} {
-int sqlite3_create_function(
-  sqlite3 *,
-  const char *zFunctionName,
-  int nArg,
-  int eTextRep,
-  void *pUserData,
-  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
-  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
-  void (*xFinal)(sqlite3_context*)
-);
-int sqlite3_create_function16(
-  sqlite3*,
-  const void *zFunctionName,
-  int nArg,
-  int eTextRep,
-  void *pUserData,
-  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
-  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
-  void (*xFinal)(sqlite3_context*)
-);
-#define SQLITE_UTF8     1
-#define SQLITE_UTF16    2
-#define SQLITE_UTF16BE  3
-#define SQLITE_UTF16LE  4
-#define SQLITE_ANY      5
-} {
- These two functions are used to add SQL functions or aggregates
- implemented in C. The
- only difference between these two routines is that the second argument, the
- name of the (scalar) function or aggregate, is encoded in UTF-8 for
- sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
- The length of the name is limited to 255 bytes, exclusive of the 
- zero-terminator.  Note that the name length limit is in bytes, not
- characters.  Any attempt to create a function with a longer name
- will result in an SQLITE_ERROR error.
- 
- The first argument is the database handle that the new function or
- aggregate is to be added to. If a single program uses more than one
- database handle internally, then user functions or aggregates must 
- be added individually to each database handle with which they will be
- used.
-
- The third argument is the number of arguments that the function or
- aggregate takes. If this argument is -1 then the function or
- aggregate may take any number of arguments.  The maximum number
- of arguments to a new SQL function is 127.  A number larger than
- 127 for the third argument results in an SQLITE_ERROR error.
-
- The fourth argument, eTextRep, specifies what type of text arguments
- this function prefers to receive.  Any function should be able to work
- work with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
- more efficient with one representation than another.  Users are allowed
- to specify separate implementations for the same function which are called
- depending on the text representation of the arguments.  The the implementation
- which provides the best match is used.  If there is only a single
- implementation which does not care what text representation is used,
- then the fourth argument should be SQLITE_ANY.
-
- The fifth argument is an arbitrary pointer.  The function implementations
- can gain access to this pointer using the sqlite_user_data() API.
-
- The sixth, seventh and  eighth argumens, xFunc, xStep and xFinal, are
- pointers to user implemented C functions that implement the user
- function or aggregate. A scalar function requires an implementation of
- the xFunc callback only, NULL pointers should be passed as the xStep
- and xFinal arguments. An aggregate function requires an implementation
- of xStep and xFinal, and NULL should be passed for xFunc. To delete an
- existing user function or aggregate, pass NULL for all three function
- callbacks. Specifying an inconstant set of callback values, such as an
- xFunc and an xFinal, or an xStep but no xFinal, results in an SQLITE_ERROR
- return.
-}
-
-api {} {
-int sqlite3_data_count(sqlite3_stmt *pStmt);
-} {
- Return the number of values in the current row of the result set.
-
- After a call to sqlite3_step() that returns SQLITE_ROW, this routine
- will return the same value as the sqlite3_column_count() function.
- After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or
- error code, or before sqlite3_step() has been called on a 
- prepared SQL statement, this routine returns zero.
-}
-
-api {} {
-int sqlite3_errcode(sqlite3 *db);
-} {
- Return the error code for the most recent failed sqlite3_* API call associated
- with sqlite3 handle 'db'.  If a prior API call failed but the most recent
- API call succeeded, the return value from this routine is undefined. 
-
- Calls to many sqlite3_* functions set the error code and string returned
- by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16()
- (overwriting the previous values). Note that calls to sqlite3_errcode(),
- sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the
- results of future invocations.  Calls to API routines that do not return
- an error code (examples: sqlite3_data_count() or sqlite3_mprintf()) do
- not change the error code returned by this routine.
-
- Assuming no other intervening sqlite3_* API calls are made, the error
- code returned by this function is associated with the same error as
- the strings returned by sqlite3_errmsg() and sqlite3_errmsg16().
-} {}
-
-api {} {
-const char *sqlite3_errmsg(sqlite3*);
-const void *sqlite3_errmsg16(sqlite3*);
-} {
- Return a pointer to a UTF-8 encoded string (sqlite3_errmsg)
- or a UTF-16 encoded string (sqlite3_errmsg16) describing in English the
- error condition for the most recent sqlite3_* API call. The returned
- string is always terminated by an 0x00 byte.
-
- The string "not an error" is returned when the most recent API call was
- successful.
-}
-
-api {} {
-int sqlite3_exec(
-  sqlite3*,                     /* An open database */
-  const char *sql,              /* SQL to be executed */
-  sqlite_callback,              /* Callback function */
-  void *,                       /* 1st argument to callback function */
-  char **errmsg                 /* Error msg written here */
-);
-} {
- A function to executes one or more statements of SQL.
-
- If one or more of the SQL statements are queries, then
- the callback function specified by the 3rd argument is
- invoked once for each row of the query result.  This callback
- should normally return 0.  If the callback returns a non-zero
- value then the query is aborted, all subsequent SQL statements
- are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.
-
- The 1st argument is an arbitrary pointer that is passed
- to the callback function as its first argument.
-
- The 2nd argument to the callback function is the number of
- columns in the query result.  The 3rd argument to the callback
- is an array of strings holding the values for each column.
- The 4th argument to the callback is an array of strings holding
- the names of each column.
-
- The callback function may be NULL, even for queries.  A NULL
- callback is not an error.  It just means that no callback
- will be invoked.
-
- If an error occurs while parsing or evaluating the SQL (but
- not while executing the callback) then an appropriate error
- message is written into memory obtained from malloc() and
- *errmsg is made to point to that message.  The calling function
- is responsible for freeing the memory that holds the error
- message.   Use sqlite3_free() for this.  If errmsg==NULL,
- then no error message is ever written.
-
- The return value is is SQLITE_OK if there are no errors and
- some other return code if there is an error.  The particular
- return value depends on the type of error. 
-
- If the query could not be executed because a database file is
- locked or busy, then this function returns SQLITE_BUSY.  (This
- behavior can be modified somewhat using the sqlite3_busy_handler()
- and sqlite3_busy_timeout() functions.)
-} {}
-
-api {} {
-int sqlite3_finalize(sqlite3_stmt *pStmt);
-} {
- The sqlite3_finalize() function is called to delete a prepared
- SQL statement obtained by a previous call to sqlite3_prepare(),
- sqlite3_prepare_v2(), sqlite3_prepare16(), or sqlite3_prepare16_v2().
- If the statement was executed successfully, or
- not executed at all, then SQLITE_OK is returned. If execution of the
- statement failed then an error code is returned. 
-
- After sqlite_finalize() has been called, the statement handle is
- invalidated. Passing it to any other SQLite function may cause a
- crash.
-
- All prepared statements must finalized before sqlite3_close() is
- called or else the close will fail with a return code of SQLITE_BUSY.
-
- This routine can be called at any point during the execution of the
- virtual machine.  If the virtual machine has not completed execution
- when this routine is called, that is like encountering an error or
- an interrupt.  (See sqlite3_interrupt().)  Incomplete updates may be
- rolled back and transactions canceled,  depending on the circumstances,
- and the result code returned will be SQLITE_ABORT.
-}
-
-api {} {
-void *sqlite3_malloc(int);
-void *sqlite3_realloc(void*, int);
-void sqlite3_free(void*);
-} {
- These routines provide access to the memory allocator used by SQLite.
- Depending on how SQLite has been compiled and the OS-layer backend,
- the memory allocator used by SQLite might be the standard system
- malloc()/realloc()/free(), or it might be something different.  With
- certain compile-time flags, SQLite will add wrapper logic around the
- memory allocator to add memory leak and buffer overrun detection.  The
- OS layer might substitute a completely different memory allocator.
- Use these APIs to be sure you are always using the correct memory
- allocator.
- 
- The sqlite3_free() API, not the standard free() from the system library,
- should always be used to free the memory buffer returned by
- sqlite3_mprintf() or sqlite3_vmprintf() and to free the error message
- string returned by sqlite3_exec().  Using free() instead of sqlite3_free()
- might accidentally work on some systems and build configurations but 
- will fail on others.
-
- Compatibility Note:  Prior to version 3.4.0, the sqlite3_free API
- was prototyped to take a <tt>char*</tt> parameter rather than 
- <tt>void*</tt>.  Like this:
-<blockquote><pre>
-void sqlite3_free(char*);
-</pre></blockquote>
- The change to using <tt>void*</tt> might cause warnings when 
- compiling older code against
- newer libraries, but everything should still work correctly.
-}
-
-api {} {
-int sqlite3_get_table(
-  sqlite3*,              /* An open database */
-  const char *sql,       /* SQL to be executed */
-  char ***resultp,       /* Result written to a char *[]  that this points to */
-  int *nrow,             /* Number of result rows written here */
-  int *ncolumn,          /* Number of result columns written here */
-  char **errmsg          /* Error msg written here */
-);
-void sqlite3_free_table(char **result);
-} {
- This next routine is really just a wrapper around sqlite3_exec().
- Instead of invoking a user-supplied callback for each row of the
- result, this routine remembers each row of the result in memory
- obtained from malloc(), then returns all of the result after the
- query has finished. 
-
- As an example, suppose the query result where this table:
-
- <pre>
-        Name        | Age
-        -----------------------
-        Alice       | 43
-        Bob         | 28
-        Cindy       | 21
- </pre>
-
- If the 3rd argument were &azResult then after the function returns
- azResult will contain the following data:
-
- <pre>
-        azResult[0] = "Name";
-        azResult[1] = "Age";
-        azResult[2] = "Alice";
-        azResult[3] = "43";
-        azResult[4] = "Bob";
-        azResult[5] = "28";
-        azResult[6] = "Cindy";
-        azResult[7] = "21";
- </pre>
-
- Notice that there is an extra row of data containing the column
- headers.  But the *nrow return value is still 3.  *ncolumn is
- set to 2.  In general, the number of values inserted into azResult
- will be ((*nrow) + 1)*(*ncolumn).
-
- After the calling function has finished using the result, it should 
- pass the result data pointer to sqlite3_free_table() in order to 
- release the memory that was malloc-ed.  Because of the way the 
- malloc() happens, the calling function must not try to call 
- malloc() directly.  Only sqlite3_free_table() is able to release 
- the memory properly and safely.
-
- The return value of this routine is the same as from sqlite3_exec().
-}
-
-api {sqlite3_interrupt} {
- void sqlite3_interrupt(sqlite3*);
-} {
- This function causes any pending database operation to abort and
- return at its earliest opportunity.  This routine is typically
- called in response to a user action such as pressing "Cancel"
- or Ctrl-C where the user wants a long query operation to halt
- immediately.
-} {}
-
-api {} {
-long long int sqlite3_last_insert_rowid(sqlite3*);
-} {
- Each entry in an SQLite table has a unique integer key called the "rowid".
- The rowid is always available as an undeclared column
- named ROWID, OID, or _ROWID_.
- If the table has a column of type INTEGER PRIMARY KEY then that column
- is another an alias for the rowid.
-
- This routine
- returns the rowid of the most recent INSERT into the database
- from the database connection given in the first argument.  If
- no inserts have ever occurred on this database connection, zero
- is returned.
-
- If an INSERT occurs within a trigger, then the rowid of the
- inserted row is returned by this routine as long as the trigger
- is running.  But once the trigger terminates, the value returned
- by this routine reverts to the last value inserted before the
- trigger fired.
-} {}
-
-api {} {
-char *sqlite3_mprintf(const char*,...);
-char *sqlite3_vmprintf(const char*, va_list);
-} {
- These routines are variants of the "sprintf()" from the
- standard C library.  The resulting string is written into memory
- obtained from malloc() so that there is never a possibility of buffer
- overflow.  These routines also implement some additional formatting
- options that are useful for constructing SQL statements.
-
- The strings returned by these routines should be freed by calling
- sqlite3_free().
-
- All of the usual printf formatting options apply.  In addition, there
- is a "%q" option.  %q works like %s in that it substitutes a null-terminated
- string from the argument list.  But %q also doubles every '\\'' character.
- %q is designed for use inside a string literal.  By doubling each '\\''
- character it escapes that character and allows it to be inserted into
- the string.
-
- For example, so some string variable contains text as follows:
-
- <blockquote><pre>
-  char *zText = "It's a happy day!";
- </pre></blockquote>
-
- One can use this text in an SQL statement as follows:
-
- <blockquote><pre>
-  sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
-       callback1, 0, 0, zText);
-  </pre></blockquote>
-
- Because the %q format string is used, the '\\'' character in zText
- is escaped and the SQL generated is as follows:
-
- <blockquote><pre>
-  INSERT INTO table1 VALUES('It''s a happy day!')
- </pre></blockquote>
-
- This is correct.  Had we used %s instead of %q, the generated SQL
- would have looked like this:
-
-  <blockquote><pre>
-  INSERT INTO table1 VALUES('It's a happy day!');
-  </pre></blockquote>
-
- This second example is an SQL syntax error.  As a general rule you
- should always use %q instead of %s when inserting text into a string 
- literal.
-} {}
-
-api {} {
-char *sqlite3_snprintf(int bufSize, char *buf, const char *zFormat, ...);
-} {
-  This routine works like "sprintf()", writing a formatted string into
-  the buf[].  However, no more than bufSize characters will be written
-  into buf[].  This routine returns a pointer to buf[].  If bufSize is
-  greater than zero, then buf[] is guaranteed to be zero-terminated.
-
-  This routine uses the same extended formatting options as
-  sqlite3_mprintf() and sqlite3_vmprintf().
-
-  Note these differences with the snprintf() function found in many
-  standard libraries:  (1)  sqlite3_snprintf() returns a pointer to the
-  buffer rather than the number of characters written.  (It would,
-  arguably, be more useful to return the number of characters written,
-  but we discovered that after the interface had been published and
-  are unwilling to break backwards compatibility.)  (2)  The order
-  of the bufSize and buf parameter is reversed from snprintf().  
-  And (3) sqlite3_snprintf() always writes a zero-terminator if bufSize
-  is positive.  
-
-  Please do not use the return value of this routine.  We may
-  decide to make the minor compatibility break and change this routine
-  to return the number of characters written rather than a pointer to
-  the buffer in a future minor version increment.
-}
-
-api {} {
-int sqlite3_open(
-  const char *filename,   /* Database filename (UTF-8) */
-  sqlite3 **ppDb          /* OUT: SQLite db handle */
-);
-int sqlite3_open16(
-  const void *filename,   /* Database filename (UTF-16) */
-  sqlite3 **ppDb          /* OUT: SQLite db handle */
-);
-} {
- Open the sqlite database file "filename".  The "filename" is UTF-8
- encoded for sqlite3_open() and UTF-16 encoded in the native byte order
- for sqlite3_open16().  An sqlite3* handle is returned in *ppDb, even
- if an error occurs. If the database is opened (or created) successfully,
- then SQLITE_OK is returned. Otherwise an error code is returned. The
- sqlite3_errmsg() or sqlite3_errmsg16()  routines can be used to obtain
- an English language description of the error.
-
- If the database file does not exist, then a new database will be created
- as needed.
- The encoding for the database will be UTF-8 if sqlite3_open() is called and
- UTF-16 if sqlite3_open16 is used.
-
- Whether or not an error occurs when it is opened, resources associated
- with the sqlite3* handle should be released by passing it to
- sqlite3_close() when it is no longer required.
-
- The returned sqlite3* can only be used in the same thread in which it
- was created.  It is an error to call sqlite3_open() in one thread then
- pass the resulting database handle off to another thread to use.  This
- restriction is due to goofy design decisions (bugs?) in the way some
- threading implementations interact with file locks.
-
- Note to windows users:  The encoding used for the filename argument
- of sqlite3_open() must be UTF-8, not whatever codepage is currently
- defined.  Filenames containing international characters must be converted
- to UTF-8 prior to passing them into sqlite3_open().
-}
-
-api {} {
-int sqlite3_prepare_v2(
-  sqlite3 *db,            /* Database handle */
-  const char *zSql,       /* SQL statement, UTF-8 encoded */
-  int nBytes,             /* Length of zSql in bytes. */
-  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
-  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
-);
-int sqlite3_prepare16_v2(
-  sqlite3 *db,            /* Database handle */
-  const void *zSql,       /* SQL statement, UTF-16 encoded */
-  int nBytes,             /* Length of zSql in bytes. */
-  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
-  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
-);
-
-/* Legacy Interfaces */
-int sqlite3_prepare(
-  sqlite3 *db,            /* Database handle */
-  const char *zSql,       /* SQL statement, UTF-8 encoded */
-  int nBytes,             /* Length of zSql in bytes. */
-  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
-  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
-);
-int sqlite3_prepare16(
-  sqlite3 *db,            /* Database handle */
-  const void *zSql,       /* SQL statement, UTF-16 encoded */
-  int nBytes,             /* Length of zSql in bytes. */
-  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
-  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
-);
-} {
- To execute an SQL query, it must first be compiled into a byte-code
- program using one of these routines. 
-
- The first argument "db" is an SQLite database handle. The second
- argument "zSql" is the statement to be compiled, encoded as either
- UTF-8 or UTF-16.  The sqlite3_prepare_v2()
- interfaces uses UTF-8 and sqlite3_prepare16_v2()
- use UTF-16. If the next argument, "nBytes", is less
- than zero, then zSql is read up to the first nul terminator.  If
- "nBytes" is not less than zero, then it is the length of the string zSql
- in bytes (not characters).
-
- *pzTail is made to point to the first byte past the end of the first
- SQL statement in zSql.  This routine only compiles the first statement
- in zSql, so *pzTail is left pointing to what remains uncompiled.
-
- *ppStmt is left pointing to a compiled SQL statement that can be
- executed using sqlite3_step().  Or if there is an error, *ppStmt may be
- set to NULL.  If the input text contained no SQL (if the input is and
- empty string or a comment) then *ppStmt is set to NULL.  The calling
- procedure is responsible for deleting this compiled SQL statement
- using sqlite3_finalize() after it has finished with it.
-
- On success, SQLITE_OK is returned.  Otherwise an error code is returned.
-
- The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
- recommended for all new programs. The two older interfaces are retained
- for backwards compatibility, but their use is discouraged.
- In the "v2" interfaces, the prepared statement
- that is returned (the sqlite3_stmt object) contains a copy of the original
- SQL. This causes the sqlite3_step() interface to behave a differently in
- two ways:
-
- <ol>
- <li>
- If the database schema changes, instead of returning SQLITE_SCHEMA as it
- always used to do, sqlite3_step() will automatically recompile the SQL
- statement and try to run it again.  If the schema has changed in a way
- that makes the statement no longer valid, sqlite3_step() will still
- return SQLITE_SCHEMA.  But unlike the legacy behavior, SQLITE_SCHEMA is
- now a fatal error.  Calling sqlite3_prepare_v2() again will not make the
- error go away.  Note: use sqlite3_errmsg() to find the text of the parsing
- error that results in an SQLITE_SCHEMA return.
- </li>
-
- <li>
- When an error occurs, 
- sqlite3_step() will return one of the detailed result-codes
- like SQLITE_IOERR or SQLITE_FULL or SQLITE_SCHEMA directly. The
- legacy behavior was that sqlite3_step() would only return a generic
- SQLITE_ERROR code and you would have to make a second call to
- sqlite3_reset() in order to find the underlying cause of the problem.
- With the "v2" prepare interfaces, the underlying reason for the error is
- returned directly.
- </li>
- </ol>
-}
-
-api {} {
-void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
-} {
- <i>Experimental</i>
-
- This routine configures a callback function - the progress callback - that
- is invoked periodically during long running calls to sqlite3_exec(),
- sqlite3_step() and sqlite3_get_table().
- An example use for this API is to keep
- a GUI updated during a large query.
-
- The progress callback is invoked once for every N virtual machine opcodes,
- where N is the second argument to this function. The progress callback
- itself is identified by the third argument to this function. The fourth
- argument to this function is a void pointer passed to the progress callback
- function each time it is invoked.
-
- If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results 
- in less than N opcodes being executed, then the progress callback is not
- invoked.
- 
- To remove the progress callback altogether, pass NULL as the third
- argument to this function.
-
- If the progress callback returns a result other than 0, then the current 
- query is immediately terminated and any database changes rolled back. If the
- query was part of a larger transaction, then the transaction is not rolled
- back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. 
-
-}
-
-api {} {
-int sqlite3_reset(sqlite3_stmt *pStmt);
-} {
- The sqlite3_reset() function is called to reset a prepared SQL
- statement obtained by a previous call to 
- sqlite3_prepare_v2() or
- sqlite3_prepare16_v2() back to it's initial state, ready to be re-executed.
- Any SQL statement variables that had values bound to them using
- the sqlite3_bind_*() API retain their values.
-}
-
-api {} {
-void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));
-void sqlite3_result_double(sqlite3_context*, double);
-void sqlite3_result_error(sqlite3_context*, const char*, int);
-void sqlite3_result_error16(sqlite3_context*, const void*, int);
-void sqlite3_result_int(sqlite3_context*, int);
-void sqlite3_result_int64(sqlite3_context*, long long int);
-void sqlite3_result_null(sqlite3_context*);
-void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));
-void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));
-void sqlite3_result_text16be(sqlite3_context*, const void*, int n, void(*)(void*));
-void sqlite3_result_text16le(sqlite3_context*, const void*, int n, void(*)(void*));
-void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
-} {
- User-defined functions invoke these routines in order to
- set their return value.  The sqlite3_result_value() routine is used
- to return an exact copy of one of the arguments to the function.
-
- The operation of these routines is very similar to the operation of
- sqlite3_bind_blob() and its cousins.  Refer to the documentation there
- for additional information.
-}
-
-api {} {
-int sqlite3_set_authorizer(
-  sqlite3*,
-  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
-  void *pUserData
-);
-#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
-#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
-#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
-#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
-#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
-#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
-#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
-#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
-#define SQLITE_DELETE                9   /* Table Name      NULL            */
-#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
-#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
-#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
-#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
-#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
-#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
-#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
-#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
-#define SQLITE_INSERT               18   /* Table Name      NULL            */
-#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
-#define SQLITE_READ                 20   /* Table Name      Column Name     */
-#define SQLITE_SELECT               21   /* NULL            NULL            */
-#define SQLITE_TRANSACTION          22   /* NULL            NULL            */
-#define SQLITE_UPDATE               23   /* Table Name      Column Name     */
-#define SQLITE_ATTACH               24   /* Filename        NULL            */
-#define SQLITE_DETACH               25   /* Database Name   NULL            */
-#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
-#define SQLITE_REINDEX              27   /* Index Name      NULL            */
-#define SQLITE_ANALYZE              28   /* Table Name      NULL            */
-#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
-#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
-#define SQLITE_FUNCTION             31   /* Function Name   NULL            */
-
-#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
-#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
-} {
- This routine registers a callback with the SQLite library.  The
- callback is invoked by sqlite3_prepare_v2() to authorize various
- operations against the database.  The callback should
- return SQLITE_OK if access is allowed, SQLITE_DENY if the entire
- SQL statement should be aborted with an error and SQLITE_IGNORE
- if the operation should be treated as a no-op.
-
- Each database connection have at most one authorizer registered
- at a time one time.  Each call
- to sqlite3_set_authorizer() overrides the previous authorizer.
- Setting the callback to NULL disables the authorizer.
-
- The second argument to the access authorization function will be one
- of the defined constants shown.  These values signify what kind of operation
- is to be authorized.  The 3rd and 4th arguments to the authorization
- function will be arguments or NULL depending on which of the 
- codes is used as the second argument.  For example, if the the
- 2nd argument code is SQLITE_READ then the 3rd argument will be the name
- of the table that is being read from and the 4th argument will be the
- name of the column that is being read from.  Or if the 2nd argument
- is SQLITE_FUNCTION then the 3rd argument will be the name of the
- function that is being invoked and the 4th argument will be NULL.
-
- The 5th argument is the name
- of the database ("main", "temp", etc.) where applicable.  The 6th argument
- is the name of the inner-most trigger or view that is responsible for
- the access attempt or NULL if this access attempt is directly from 
- input SQL code.
-
- The return value of the authorization callback function should be one of the
- constants SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE.  A return of
- SQLITE_OK means that the operation is permitted and that 
- sqlite3_prepare_v2() can proceed as normal.
- A return of SQLITE_DENY means that the sqlite3_prepare_v2()
- should fail with an error.  A return of SQLITE_IGNORE causes the 
- sqlite3_prepare_v2() to continue as normal but the requested 
- operation is silently converted into a no-op.  A return of SQLITE_IGNORE
- in response to an SQLITE_READ or SQLITE_FUNCTION causes the column
- being read or the function being invoked to return a NULL.
-
- The intent of this routine is to allow applications to safely execute
- user-entered SQL.  An appropriate callback can deny the user-entered
- SQL access certain operations (ex: anything that changes the database)
- or to deny access to certain tables or columns within the database.
-
- SQLite is not reentrant through the authorization callback function.
- The authorization callback function should not attempt to invoke
- any other SQLite APIs for the same database connection.  If the
- authorization callback function invokes some other SQLite API, an
- SQLITE_MISUSE error or a segmentation fault may result.
-}
-
-api {} {
-int sqlite3_step(sqlite3_stmt*);
-} {
- After an SQL query has been prepared with a call to either
- sqlite3_prepare_v2() or sqlite3_prepare16_v2() or to one of
- the legacy interfaces sqlite3_prepare() or sqlite3_prepare16(),
- then this function must be
- called one or more times to execute the statement.
-
- The details of the behavior of this sqlite3_step() interface depend
- on whether the statement was prepared using the newer "v2" interface
- sqlite3_prepare_v2() and sqlite3_prepare16_v2() or the older legacy
- interface sqlite3_prepare() and sqlite3_prepare16().  The use of the
- new "v2" interface is recommended for new applications but the legacy
- interface will continue to be supported.
-
- In the lagacy interface, the return value will be either SQLITE_BUSY, 
- SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE.  With the "v2"
- interface, any of the other SQLite result-codes might be returned as
- well.
-
- SQLITE_BUSY means that the database engine attempted to open
- a locked database and there is no busy callback registered.
- Call sqlite3_step() again to retry the open.
-
- SQLITE_DONE means that the statement has finished executing
- successfully.  sqlite3_step() should not be called again on this virtual
- machine without first calling sqlite3_reset() to reset the virtual
- machine back to its initial state.
-
- If the SQL statement being executed returns any data, then 
- SQLITE_ROW is returned each time a new row of data is ready
- for processing by the caller. The values may be accessed using
- the sqlite3_column_int(), sqlite3_column_text(), and similar functions.
- sqlite3_step() is called again to retrieve the next row of data.
- 
- SQLITE_ERROR means that a run-time error (such as a constraint
- violation) has occurred.  sqlite3_step() should not be called again on
- the VM. More information may be found by calling sqlite3_errmsg().
- A more specific error code (example: SQLITE_INTERRUPT, SQLITE_SCHEMA,
- SQLITE_CORRUPT, and so forth) can be obtained by calling
- sqlite3_reset() on the prepared statement.  In the "v2" interface,
- the more specific error code is returned directly by sqlite3_step().
-
- SQLITE_MISUSE means that the this routine was called inappropriately.
- Perhaps it was called on a virtual machine that had already been
- finalized or on one that had previously returned SQLITE_ERROR or
- SQLITE_DONE.  Or it could be the case that a database connection
- is being used by a different thread than the one it was created it.
-
- <b>Goofy Interface Alert:</b>
- In the legacy interface, 
- the sqlite3_step() API always returns a generic error code,
- SQLITE_ERROR, following any error other than SQLITE_BUSY and SQLITE_MISUSE.
- You must call sqlite3_reset() (or sqlite3_finalize()) in order to find
- one of the specific result-codes that better describes the error.
- We admit that this is a goofy design.  The problem has been fixed
- with the "v2" interface.  If you prepare all of your SQL statements
- using either sqlite3_prepare_v2() or sqlite3_prepare16_v2() instead
- of the legacy sqlite3_prepare() and sqlite3_prepare16(), then the 
- more specific result-codes are returned directly by sqlite3_step().
- The use of the "v2" interface is recommended.
-}
-
-api {} {
-void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
-} {
- Register a function that is called each time an SQL statement is evaluated.
- The callback function is invoked on the first call to sqlite3_step() after
- calls to sqlite3_prepare_v2() or sqlite3_reset().
- This function can be used (for example) to generate
- a log file of all SQL executed against a database.  This can be
- useful when debugging an application that uses SQLite.
-}
-
-api {} {
-void *sqlite3_user_data(sqlite3_context*);
-} {
- The pUserData argument to the sqlite3_create_function() and
- sqlite3_create_function16() routines used to register user functions
- is available to the implementation of the function using this
- call.
-}
-
-api {} {
-const void *sqlite3_value_blob(sqlite3_value*);
-int sqlite3_value_bytes(sqlite3_value*);
-int sqlite3_value_bytes16(sqlite3_value*);
-double sqlite3_value_double(sqlite3_value*);
-int sqlite3_value_int(sqlite3_value*);
-long long int sqlite3_value_int64(sqlite3_value*);
-const unsigned char *sqlite3_value_text(sqlite3_value*);
-const void *sqlite3_value_text16(sqlite3_value*);
-const void *sqlite3_value_text16be(sqlite3_value*);
-const void *sqlite3_value_text16le(sqlite3_value*);
-int sqlite3_value_type(sqlite3_value*);
-} {
- This group of routines returns information about arguments to
- a user-defined function.  Function implementations use these routines
- to access their arguments.  These routines are the same as the
- sqlite3_column_... routines except that these routines take a single
- sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
- column number.
-
- See the documentation under sqlite3_column_blob for additional
- information.
-
- Please pay particular attention to the fact that the pointer that
- is returned from sqlite3_value_blob(), sqlite3_value_text(), or
- sqlite3_value_text16() can be invalidated by a subsequent call to
- sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite_value_text(),
- or sqlite3_value_text16().  
-}
-
-api {} {
-  int sqlite3_sleep(int);
-} {
- Sleep for a little while. The second parameter is the number of
- miliseconds to sleep for. 
-
- If the operating system does not support sleep requests with 
- milisecond time resolution, then the time will be rounded up to 
- the nearest second. The number of miliseconds of sleep actually 
- requested from the operating system is returned.
-}
-
-api {} {
-  int sqlite3_expired(sqlite3_stmt*);
-} {
- Return TRUE (non-zero) if the statement supplied as an argument needs
- to be recompiled.  A statement needs to be recompiled whenever the
- execution environment changes in a way that would alter the program
- that sqlite3_prepare() generates.  For example, if new functions or
- collating sequences are registered or if an authorizer function is
- added or changed.
-}
-
-api {} {
-  int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
-} {
- Move all bindings from the first prepared statement over to the second.
- This routine is useful, for example, if the first prepared statement
- fails with an SQLITE_SCHEMA error.  The same SQL can be prepared into
- the second prepared statement then all of the bindings transfered over
- to the second statement before the first statement is finalized.
-}
-
-api {} {
-  int sqlite3_global_recover();
-} {
- This function used to be involved in recovering from out-of-memory
- errors.  But as of SQLite version 3.3.0, out-of-memory recovery is
- automatic and this routine now does nothing.  THe interface is retained
- to avoid link errors with legacy code.
-}
-
-api {} {
-  int sqlite3_get_autocommit(sqlite3*);
-} {
- Test to see whether or not the database connection is in autocommit
- mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
- by default.  Autocommit is disabled by a BEGIN statement and reenabled
- by the next COMMIT or ROLLBACK.
-}
-
-api {} {
-  int sqlite3_clear_bindings(sqlite3_stmt*);
-} {
- Set all the parameters in the compiled SQL statement back to NULL.
-}
-
-api {} {
-  sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
-} {
- Return the sqlite3* database handle to which the prepared statement given
- in the argument belongs.  This is the same database handle that was
- the first argument to the sqlite3_prepare() that was used to create
- the statement in the first place.
-}
-
-api {} {
-  void *sqlite3_update_hook(
-    sqlite3*, 
-    void(*)(void *,int ,char const *,char const *,sqlite_int64),
-    void*
-  );
-} {
- Register a callback function with the database connection identified by the 
- first argument to be invoked whenever a row is updated, inserted or deleted.
- Any callback set by a previous call to this function for the same 
- database connection is overridden.
-
- The second argument is a pointer to the function to invoke when a 
- row is updated, inserted or deleted. The first argument to the callback is
- a copy of the third argument to sqlite3_update_hook. The second callback 
- argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending
- on the operation that caused the callback to be invoked. The third and 
- fourth arguments to the callback contain pointers to the database and 
- table name containing the affected row. The final callback parameter is 
- the rowid of the row. In the case of an update, this is the rowid after 
- the update takes place.
-
- The update hook is not invoked when internal system tables are
- modified (i.e. sqlite_master and sqlite_sequence).
-
- If another function was previously registered, its pArg value is returned.
- Otherwise NULL is returned.
-
- See also: sqlite3_commit_hook(), sqlite3_rollback_hook()
-}
-
-api {} {
-  void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
-} {
- Register a callback to be invoked whenever a transaction is rolled
- back. 
-
- The new callback function overrides any existing rollback-hook
- callback. If there was an existing callback, then it's pArg value 
- (the third argument to sqlite3_rollback_hook() when it was registered) 
- is returned. Otherwise, NULL is returned.
-
- For the purposes of this API, a transaction is said to have been 
- rolled back if an explicit "ROLLBACK" statement is executed, or
- an error or constraint causes an implicit rollback to occur. The 
- callback is not invoked if a transaction is automatically rolled
- back because the database connection is closed.
-}
-
-api {} {
-  int sqlite3_enable_shared_cache(int);
-} {
-  This routine enables or disables the sharing of the database cache
-  and schema data structures between connections to the same database.
-  Sharing is enabled if the argument is true and disabled if the argument
-  is false.
-
-  Cache sharing is enabled and disabled on a thread-by-thread basis.
-  Each call to this routine enables or disables cache sharing only for
-  connections created in the same thread in which this routine is called.
-  There is no mechanism for sharing cache between database connections
-  running in different threads.
-
-  Sharing must be disabled prior to shutting down a thread or else
-  the thread will leak memory.  Call this routine with an argument of
-  0 to turn off sharing.  Or use the sqlite3_thread_cleanup() API.
-
-  This routine must not be called when any database connections
-  are active in the current thread.  Enabling or disabling shared
-  cache while there are active database connections will result
-  in memory corruption.
-
-  When the shared cache is enabled, the
-  following routines must always be called from the same thread:
-  sqlite3_open(), sqlite3_prepare_v2(), sqlite3_step(), sqlite3_reset(),
-  sqlite3_finalize(), and sqlite3_close().
-  This is due to the fact that the shared cache makes use of
-  thread-specific storage so that it will be available for sharing
-  with other connections.
-
-  Virtual tables cannot be used with a shared cache.  When shared
-  cache is enabled, the sqlite3_create_module() API used to register
-  virtual tables will always return an error.
-
-  This routine returns SQLITE_OK if shared cache was
-  enabled or disabled successfully.  An error code is returned
-  otherwise.
-
-  Shared cache is disabled by default for backward compatibility.
-}
-
-api {} {
-  void sqlite3_thread_cleanup(void);
-} {
-  This routine makes sure that all thread local storage used by SQLite
-  in the current thread has been deallocated.  A thread can call this
-  routine prior to terminating in order to make sure there are no memory
-  leaks.
-
-  This routine is not strictly necessary.  If cache sharing has been
-  disabled using sqlite3_enable_shared_cache() and if all database
-  connections have been closed and if SQLITE_ENABLE_MEMORY_MANAGMENT is
-  on and all memory has been freed, then the thread local storage will
-  already have been automatically deallocated.  This routine is provided
-  as a convenience to the program who just wants to make sure that there
-  are no leaks.
-}
-
-api {} {
-  int sqlite3_release_memory(int N);
-} {
-  This routine attempts to free at least N bytes of memory from the caches
-  of database connecions that were created in the same thread from which this
-  routine is called.  The value returned is the number of bytes actually
-  freed.  
-
-  This routine is only available if memory management has been enabled
-  by compiling with the SQLITE_ENABLE_MEMORY_MANAGMENT macro.
-}
-
-api {} {
-  void sqlite3_soft_heap_limit(int N);
-} {
-  This routine sets the soft heap limit for the current thread to N.
-  If the total heap usage by SQLite in the current thread exceeds N,
-  then sqlite3_release_memory() is called to try to reduce the memory usage
-  below the soft limit.
-
-  Prior to shutting down a thread sqlite3_soft_heap_limit() must be set to 
-  zero (the default) or else the thread will leak memory. Alternatively, use
-  the sqlite3_thread_cleanup() API.
-
-  A negative or zero value for N means that there is no soft heap limit and
-  sqlite3_release_memory() will only be called when memory is exhaused.
-  The default value for the soft heap limit is zero.
-
-  SQLite makes a best effort to honor the soft heap limit.  But if it
-  is unable to reduce memory usage below the soft limit, execution will
-  continue without error or notification.  This is why the limit is 
-  called a "soft" limit.  It is advisory only.
-
-  This routine is only available if memory management has been enabled
-  by compiling with the SQLITE_ENABLE_MEMORY_MANAGMENT macro.
-}
-
-api {} {
-  void sqlite3_thread_cleanup(void);
-} {
-  This routine ensures that a thread that has used SQLite in the past
-  has released any thread-local storage it might have allocated.  
-  When the rest of the API is used properly, the cleanup of 
-  thread-local storage should be completely automatic.  You should
-  never really need to invoke this API.  But it is provided to you
-  as a precaution and as a potential work-around for future
-  thread-releated memory-leaks.
-}
-
-set n 0
-set i 0
-foreach item $apilist {
-  set namelist [lindex $item 0]
-  foreach name $namelist {
-    set n_to_name($n) $name
-    set n_to_idx($n) $i
-    set name_to_idx($name) $i
-    incr n
-  }
-  incr i
-}
-set i 0
-foreach name [lsort [array names name_to_idx]] {
-  set sname($i) $name
-  incr i
-}
-#parray n_to_name
-#parray n_to_idx
-#parray name_to_idx
-#parray sname
-incr n -1
-puts "<DIV class=pdf_ignore>"
-puts {<table width="100%" cellpadding="5"><tr>}
-set nrow [expr {($n+2)/3}]
-set i 0
-for {set j 0} {$j<3} {incr j} {
-  if {$j>0} {puts {<td width="10"></td>}}
-  puts {<td valign="top">}
-  set limit [expr {$i+$nrow}]
-  puts {<ul>}
-  while {$i<$limit && $i<$n} {
-    set name $sname($i)
-    if {[regexp {^sqlite} $name]} {set display $name} {set display <i>$name</i>}
-    puts "<li><a href=\"#$name\">$display</a></li>"
-    incr i
-  }
-  puts {</ul></td>}
-}
-puts "</table>"
-puts "<!-- $n entries.  $nrow rows in 3 columns -->"
-puts "</DIV>"
-
-proc resolve_name {ignore_list name} {
-  global name_to_idx
-  if {![info exists name_to_idx($name)] || [lsearch $ignore_list $name]>=0} {
-    return $name
-  } else {
-    return "<a href=\"#$name\">$name</a>"
-  }
-}
-
-foreach name [lsort [array names name_to_idx]] {
-  set i $name_to_idx($name)
-  if {[info exists done($i)]} continue
-  set done($i) 1
-  foreach {namelist prototype desc} [lindex $apilist $i] break
-  foreach name $namelist {
-    puts "<a name=\"$name\"></a>"
-  }
-  puts "<p><hr></p>"
-  puts "<blockquote><pre>"
-  regsub "^( *\n)+" $prototype {} p2
-  regsub "(\n *)+\$" $p2 {} p3
-  puts $p3
-  puts "</pre></blockquote>"
-  regsub -all {\[} $desc {\[} desc
-  regsub -all {sqlite3_[a-z0-9_]+} $desc "\[resolve_name $name &\]" d2
-  foreach x $specialname {
-    regsub -all $x $d2 "\[resolve_name $name &\]" d2
-  }
-  regsub -all "\n( *\n)+" [subst $d2] "</p>\n\n<p>" d3
-  puts "<p>$d3</p>"
-}
-
-puts "<DIV class=pdf_ignore>"
-footer $rcsid
-puts "</DIV>"