SQLite

**    May you find forgiveness for yourself and forgive others.
**    May you share freely, never taking more than you give.
**
*************************************************************************
** This header file defines the interface that the SQLite library
** presents to client programs.
**
** @(#) $Id: sqlite.h.in,v 1.154 2006/01/10 15:18:28 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.

** sufficient memory to prevent the limit from being exceeded, the memory is
** allocated anyway and the current operation proceeds.
**
** This function is only available if the library was compiled without the 
** SQLITE_OMIT_MEMORY_MANAGEMENT option set. It is a no-op unless 
** memory-management has been enabled.
*/
void sqlite3_soft_heap_limit(int);

/*
** Undo the hack that converts floating point types to integer for
** builds on processors without floating point support.
*/
#ifdef SQLITE_OMIT_FLOATING_POINT
# undef double
#endif

#ifdef __cplusplus
}  /* End of the 'extern "C"' block */
#endif
#endif

/*
** 2001 September 15
**
** The author disclaims copyright to this source code.  In place of
** a legal notice, here is a blessing:
**
**    May you do good and not evil.
**    May you find forgiveness for yourself and forgive others.
**    May you share freely, never taking more than you give.
**
*************************************************************************
** Internal interface definitions for SQLite.
**
** @(#) $Id: sqliteInt.h,v 1.459 2006/01/10 15:18:28 drh Exp $
*/
#ifndef _SQLITEINT_H_
#define _SQLITEINT_H_

/*
** Extra interface definitions for those who need them
*/

*/
struct ThreadData {
  u8 isInit;               /* True if structure has been initialised */
  u8 mallocFailed;         /* True after a malloc() has failed */

#ifndef SQLITE_OMIT_MEMORY_MANAGEMENT
  u8 useMemoryManagement;  /* True if memory-management is enabled */
  int nSoftHeapLimit;      /* Suggested max mem allocation.  No limit if <0 */
  int nAlloc;              /* Number of bytes currently allocated */
  Pager *pPager;           /* Linked list of all pagers in this thread */
#endif

#ifndef SQLITE_OMIT_SHARED_CACHE
  u8 useSharedData;        /* True if shared pagers and schemas are enabled */
  BtShared *pBtree;        /* Linked list of all currently open BTrees */
#endif

#ifdef SQLITE_MEMDEBUG
  int nMaxAlloc;           /* High water mark of ThreadData.nAlloc */
  int mallocAllowed;       /* assert() in sqlite3Malloc() if not set */
  int isFail;              /* True if all malloc() calls should fail */
  const char *zFile;       /* Filename to associate debugging info with */
  int iLine;               /* Line number to associate debugging info with */
  void *pFirst;            /* Pointer to linked list of allocations */
#endif
};

** the column that is that key.   Otherwise Table.iPKey is negative.  Note
** that the datatype of the PRIMARY KEY must be INTEGER for this field to
** be set.  An INTEGER PRIMARY KEY is used as the rowid for each row of
** the table.  If a table has no INTEGER PRIMARY KEY, then a random rowid
** is generated for each row of the table.  Table.hasPrimKey is true if
** the table has any PRIMARY KEY, INTEGER or otherwise.
**


** Table.tnum is the page number for the root BTree page of the table in the
** database file.  If Table.iDb is the index of the database table backend
** in sqlite.aDb[].  0 is for the main database and 1 is for the file that
** holds temporary tables and indices.  If Table.isTransient
** is true, then the table is stored in a file that is automatically deleted
** when the VDBE cursor to the table is closed.  In this case Table.tnum 
** refers VDBE cursor number that holds the table open, not to the root
** page number.  Transient tables are used to hold the results of a
** sub-query that appears instead of a real table name in the FROM clause 
** of a SELECT statement.
*/
struct Table {
  char *zName;     /* Name of the table */
  int nCol;        /* Number of columns in this table */
  Column *aCol;    /* Information about each column */
  int iPKey;       /* If not less then 0, use aCol[iPKey] as the primary key */
  Index *pIndex;   /* List of SQL indexes on this table. */
  int tnum;        /* Root BTree node for this table (see note above) */
  Select *pSelect; /* NULL for tables.  Points to definition if a view. */
  u8 readOnly;     /* True if this table should not be written by the user */
// u8 iDb;          /* Index into sqlite.aDb[] of the backend for this table */
  u8 isTransient;  /* True if automatically deleted when VDBE finishes */
  u8 hasPrimKey;   /* True if there exists a primary key */
  u8 keyConf;      /* What to do in case of uniqueness conflict on iPKey */
  u8 autoInc;      /* True if the integer primary key is autoincrement */
  int nRef;          /* Number of pointers to this Table */
  Trigger *pTrigger; /* List of SQL triggers on this table */
  FKey *pFKey;       /* Linked list of all foreign keys in this table */

** otherwise be equal, then return a result as if the second key
** were larger.
*/
struct KeyInfo {
  u8 enc;             /* Text encoding - one of the TEXT_Utf* values */
  u8 incrKey;         /* Increase 2nd key by epsilon before comparison */
  int nField;         /* Number of entries in aColl[] */
  u8 *aSortOrder;     /* If defined an aSortOrder[i] is true, sort DESC */
  CollSeq *aColl[1];  /* Collating sequence for each term of the key */
};

/*
** Each SQL index is represented in memory by an
** instance of the following structure.
**

  int nColumn;     /* Number of columns in the table used by this index */
  int *aiColumn;   /* Which columns are used by this index.  1st is 0 */
  unsigned *aiRowEst; /* Result of ANALYZE: Est. rows selected by each column */
  Table *pTable;   /* The SQL table being indexed */
  int tnum;        /* Page containing root of this index in database file */
  u8 onError;      /* OE_Abort, OE_Ignore, OE_Replace, or OE_None */
  u8 autoIndex;    /* True if is automatically created (ex: by UNIQUE) */
  // u8 iDb;          /* Index in sqlite.aDb[] of where this index is stored */
  char *zColAff;   /* String defining the affinity of each column */
  Index *pNext;    /* The next index associated with the same table */
  Schema *pSchema;
  KeyInfo keyInfo; /* Info on how to order keys.  MUST BE LAST */
};

/*
** Each token coming out of the lexer is an instance of
** this structure.  Tokens are also used as part of an expression.
**

** If the Expr is of type OP_Column, and the table it is selecting from
** is a disk table or the "old.*" pseudo-table, then pTab points to the
** corresponding table definition.
*/
struct Expr {
  u8 op;                 /* Operation performed by this node */
  char affinity;         /* The affinity of the column or 0 if not a column */
//u8 iDb;                /* Database referenced by this expression */
  u8 flags;              /* Various flags.  See below */
  CollSeq *pColl;        /* The collation type of the column or 0 */
  Expr *pLeft, *pRight;  /* Left and right subnodes */
  ExprList *pList;       /* A list of expressions used as function arguments
                         ** or in "<expr> IN (<expr-list)" */
  Token token;           /* An operand token */
  Token span;            /* Complete text of the expression */

**
*************************************************************************
** Utility functions used throughout sqlite.
**
** This file contains functions for allocating memory, comparing
** strings, and stuff like that.
**
** $Id: util.c,v 1.166 2006/01/10 15:18:28 drh Exp $
*/
#include "sqliteInt.h"
#include "os.h"
#include <stdarg.h>
#include <ctype.h>

/*

#define MAX(x,y) ((x)>(y)?(x):(y))

#if !defined(SQLITE_OMIT_MEMORY_MANAGEMENT) && !defined(SQLITE_OMIT_DISKIO)
/*
** Set the soft heap-size limit for the current thread. Passing a negative
** value indicates no limit.
*/
void sqlite3_soft_heap_limit(int n){
  sqlite3ThreadData()->nSoftHeapLimit = n;
}

/*
** Release memory held by SQLite instances created by the current thread.
*/
int sqlite3_release_memory(int n){

** successful is returned to the caller.
**
** If SQLITE_OMIT_MEMORY_MANAGEMENT is defined, this function is a no-op.
*/
#ifndef SQLITE_OMIT_MEMORY_MANAGEMENT
static void handleSoftLimit(int n){
  ThreadData *pTsd = sqlite3ThreadData();
  pTsd->nAlloc += n;
  if( n>0 && pTsd->nSoftHeapLimit>0 ){
    while( pTsd->nAlloc>pTsd->nSoftHeapLimit && sqlite3_release_memory(n) );
  }
}
#else
#define handleSoftLimit(x)
#endif

set rcsid {$Id: capi3ref.tcl,v 1.26 2006/01/10 15:18:28 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}
puts {
<h2>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {

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

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

  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.

  For any given database connection, SQLite requires that the
  following routines always be called from the same thread:
  sqlite3_open(), sqlite3_prepare(), sqlite3_step(), sqlite3_reset(),
  sqlite3_finalize(), and sqlite3_close().  On some operating systems
  (ex: windows and linux 2.6) you can get away with calling these routines
  from different threads as long as their executions never overlap in time
  and the shared cache is disabled.
  But when the shared cache is enabled, some information about the
  database connection is stored in thread-specific storage so that it
  will be available for sharing with other connections.  Consequently,
  the previously enumerated routines must always be called from the
  same thread when shared cache is enabled, regardless of what operating
  system is used.

  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 {} {
  int sqlite3_enable_memory_management(int);
} {
  This routine enables or disables heap memory management for the
  thread in which it is called.  Memory management is enabled if
  the argument is true and disabled if the argument is false.

  This routine must not be called when any database connections
  are active in the current thread.  Enabling or disabling memory
  management while there are active database connections will result
  in memory corruption.

  When memory management is enabled, SQLite tries to automatically
  recover from out-of-memory errors by freeing unused cache memory
  and retrying the allocation.
  This allows operations to continue when available memory is limit
  though with some loss of performance due to the reduction in cache
  size.

  The sqlite3_soft_heap_limit() API can be used to restrict SQLite's
  heap memory usage to a preset amount so that the reclamation of
  cache begins to occur before memory is exhausted.

  Memory management is enabled and disabled on a thread-by-thread basis.
  Each call to this routine enables or disabled memory management only for
  database connections created and used in the same thread in which this
  routine is called.

  For any given database connection, SQLite requires that the
  following routines always be called from the same thread:
  sqlite3_open(), sqlite3_prepare(), sqlite3_step(), sqlite3_reset(),
  sqlite3_finalize(), and sqlite3_close().  On some operating systems
  (ex: windows and linux 2.6) you can get away with calling these routines
  from different threads as long as their executions never overlap in time
  and memory management is disabled.
  But when the memory management is enabled, some information about the
  database connections is stored in thread-specific storage so that it
  will be available to remediate memory shortages.  Consequently,
  the previously enumerated routines must always be called from the
  same thread when memory management is enabled, regardless of what
  operating system is used.

  This routine returns SQLITE_OK if the memory management module was
  enabled or disabled successfully.  An error code is returned
  otherwise.

  Memory management is disabled by default for backwards compatibility
  and because it is normally only useful for embedded devices.  The
  code that implements the memory management feature can be omitted by
  recompiling SQLite with the SQLITE_OMIT_MEMORY_MANAGEMENT macro defined.
}

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.  

  If memory management has not been enabled by calling
  sqlite3_enable_memory_management() then this routine is a no-op
  and always returns 0.
}

api {} {
  void sqlite3_soft_heap_limit(int N);
} {
  This routine sets the soft heap limit for the current thread to N.
  If memory management is enabled on the thread  by the
  sqlite3_enable_memory_management() function and the total heap usage
  by SQLite in that thread exceeds N, then sqlite3_release_memory() is
  called to try to reduce the memory usage below the soft limit.

  A negative 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 negative.

  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 way the limit is 
  called a "soft" limit.  It is advisory only.

  If memory management is not enabled, the soft heap limit is ignored.
}

set n 0
set i 0
foreach item $apilist {
  set namelist [lindex $item 0]
  foreach name $namelist {
    set n_to_name($n) $name