/*

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

 **

 *************************************************************************

 ** Main file for the SQLite library.  The routines in this file

 ** implement the programmer interface to the library.  Routines in

 ** other files are for internal use by SQLite and should not be

 ** accessed by users of the library.

 **

 ** $Id$

 */

 #include "sqliteInt.h"

 #include <ctype.h>

 /*

 ** The version of the library

 */

 const char sqlite3_version[] = SQLITE_VERSION;

 const char *sqlite3_libversion(void){ return sqlite3_version; }

 int sqlite3_libversion_number(void){ return SQLITE_VERSION_NUMBER; }

 int sqlite3_threadsafe(void){ return SQLITE_THREADSAFE; }

 /*

 ** If the following function pointer is not NULL and if

 ** SQLITE_ENABLE_IOTRACE is enabled, then messages describing

 ** I/O active are written using this function.  These messages

 ** are intended for debugging activity only.

 */

 void (*sqlite3_io_trace)(const char*, ...) = 0;

 /*

 ** If the following global variable points to a string which is the

 ** name of a directory, then that directory will be used to store

 ** temporary files.

 **

 ** See also the "PRAGMA temp_store_directory" SQL command.

 */

 char *sqlite3_temp_directory = 0;

 /*

 ** This is the default collating function named "BINARY" which is always

 ** available.

 */

 static int binCollFunc(

   void *NotUsed,

   int nKey1, const void *pKey1,

   int nKey2, const void *pKey2

 ){

   int rc, n;

   n = nKey1<nKey2 ? nKey1 : nKey2;

   rc = memcmp(pKey1, pKey2, n);

   if( rc==0 ){

     rc = nKey1 - nKey2;

   }

   return rc;

 }

 /*

 ** Another built-in collating sequence: NOCASE. 

 **

 ** This collating sequence is intended to be used for "case independant

 ** comparison". SQLite's knowledge of upper and lower case equivalents

 ** extends only to the 26 characters used in the English language.

 **

 ** At the moment there is only a UTF-8 implementation.

 */

 static int nocaseCollatingFunc(

   void *NotUsed,

   int nKey1, const void *pKey1,

   int nKey2, const void *pKey2

 ){

   int r = sqlite3StrNICmp(

       (const char *)pKey1, (const char *)pKey2, (nKey1<nKey2)?nKey1:nKey2);

   if( 0==r ){

     r = nKey1-nKey2;

   }

   return r;

 }

 /*

 ** Return the ROWID of the most recent insert

 */

 sqlite_int64 sqlite3_last_insert_rowid(sqlite3 *db){

   return db->lastRowid;

 }

 /*

 ** Return the number of changes in the most recent call to sqlite3_exec().

 */

 int sqlite3_changes(sqlite3 *db){

   return db->nChange;

 }

 /*

 ** Return the number of changes since the database handle was opened.

 */

 int sqlite3_total_changes(sqlite3 *db){

   return db->nTotalChange;

 }

 /*

 ** Close an existing SQLite database

 */

 int sqlite3_close(sqlite3 *db){

   HashElem *i;

   int j;

   if( !db ){

     return SQLITE_OK;

   }

   if( sqlite3SafetyCheck(db) ){

     return SQLITE_MISUSE;

   }

   sqlite3_mutex_enter(db->mutex);

 #ifdef SQLITE_SSE

   {

     extern void sqlite3SseCleanup(sqlite3*);

     sqlite3SseCleanup(db);

   }

 #endif 

   sqlite3ResetInternalSchema(db, 0);

   /* If a transaction is open, the ResetInternalSchema() call above

   ** will not have called the xDisconnect() method on any virtual

   ** tables in the db->aVTrans[] array. The following sqlite3VtabRollback()

   ** call will do so. We need to do this before the check for active

   ** SQL statements below, as the v-table implementation may be storing

   ** some prepared statements internally.

   */

   sqlite3VtabRollback(db);

   /* If there are any outstanding VMs, return SQLITE_BUSY. */

   if( db->pVdbe ){

     sqlite3Error(db, SQLITE_BUSY, 

         "Unable to close due to unfinalised statements");

     sqlite3_mutex_leave(db->mutex);

     return SQLITE_BUSY;

   }

   assert( !sqlite3SafetyCheck(db) );

   /* FIX ME: db->magic may be set to SQLITE_MAGIC_CLOSED if the database

   ** cannot be opened for some reason. So this routine needs to run in

   ** that case. But maybe there should be an extra magic value for the

   ** "failed to open" state.

   **

   ** TODO: Coverage tests do not test the case where this condition is

   ** true. It's hard to see how to cause it without messing with threads.

   */

   if( db->magic!=SQLITE_MAGIC_CLOSED && sqlite3SafetyOn(db) ){

     /* printf("DID NOT CLOSE\n"); fflush(stdout); */

     sqlite3_mutex_leave(db->mutex);

     return SQLITE_ERROR;

   }

   for(j=0; j<db->nDb; j++){

     struct Db *pDb = &db->aDb[j];

     if( pDb->pBt ){

       sqlite3BtreeClose(pDb->pBt);

       pDb->pBt = 0;

       if( j!=1 ){

         pDb->pSchema = 0;

       }

     }

   }

   sqlite3ResetInternalSchema(db, 0);

   assert( db->nDb<=2 );

   assert( db->aDb==db->aDbStatic );

   for(i=sqliteHashFirst(&db->aFunc); i; i=sqliteHashNext(i)){

     FuncDef *pFunc, *pNext;

     for(pFunc = (FuncDef*)sqliteHashData(i); pFunc; pFunc=pNext){

       pNext = pFunc->pNext;

       sqlite3_free(pFunc);

     }

   }

   for(i=sqliteHashFirst(&db->aCollSeq); i; i=sqliteHashNext(i)){

     CollSeq *pColl = (CollSeq *)sqliteHashData(i);

     /* Invoke any destructors registered for collation sequence user data. */

     for(j=0; j<3; j++){

       if( pColl[j].xDel ){

         pColl[j].xDel(pColl[j].pUser);

       }

     }

     sqlite3_free(pColl);

   }

   sqlite3HashClear(&db->aCollSeq);

 #ifndef SQLITE_OMIT_VIRTUALTABLE

   for(i=sqliteHashFirst(&db->aModule); i; i=sqliteHashNext(i)){

     Module *pMod = (Module *)sqliteHashData(i);

     if( pMod->xDestroy ){

       pMod->xDestroy(pMod->pAux);

     }

     sqlite3_free(pMod);

   }

   sqlite3HashClear(&db->aModule);

 #endif

   sqlite3HashClear(&db->aFunc);

   sqlite3Error(db, SQLITE_OK, 0); /* Deallocates any cached error strings. */

   if( db->pErr ){

     sqlite3ValueFree(db->pErr);

   }

   sqlite3CloseExtensions(db);

   db->magic = SQLITE_MAGIC_ERROR;

   /* The temp-database schema is allocated differently from the other schema

   ** objects (using sqliteMalloc() directly, instead of sqlite3BtreeSchema()).

   ** So it needs to be freed here. Todo: Why not roll the temp schema into

   ** the same sqliteMalloc() as the one that allocates the database 

   ** structure?

   */

   sqlite3_free(db->aDb[1].pSchema);

   sqlite3_mutex_leave(db->mutex);

   sqlite3_mutex_free(db->mutex);

   sqlite3_free(db);

   return SQLITE_OK;

 }

 /*

 ** Rollback all database files.

 */

 void sqlite3RollbackAll(sqlite3 *db){

   int i;

   int inTrans = 0;

   assert( sqlite3_mutex_held(db->mutex) );

   sqlite3MallocEnterBenignBlock(1);                 /* Enter benign region */

   for(i=0; i<db->nDb; i++){

     if( db->aDb[i].pBt ){

       if( sqlite3BtreeIsInTrans(db->aDb[i].pBt) ){

         inTrans = 1;

       }

       sqlite3BtreeRollback(db->aDb[i].pBt);

       db->aDb[i].inTrans = 0;

     }

   }

   sqlite3VtabRollback(db);

   sqlite3MallocLeaveBenignBlock();                 /* Leave benign region */

   if( db->flags&SQLITE_InternChanges ){

     sqlite3ExpirePreparedStatements(db);

     sqlite3ResetInternalSchema(db, 0);

   }

   /* If one has been configured, invoke the rollback-hook callback */

   if( db->xRollbackCallback && (inTrans || !db->autoCommit) ){

     db->xRollbackCallback(db->pRollbackArg);

   }

 }

 /*

 ** Return a static string that describes the kind of error specified in the

 ** argument.

 */

 const char *sqlite3ErrStr(int rc){

   const char *z;

   switch( rc & 0xff ){

     case SQLITE_ROW:

     case SQLITE_DONE:

     case SQLITE_OK:         z = "not an error";                          break;

     case SQLITE_ERROR:      z = "SQL logic error or missing database";   break;

     case SQLITE_PERM:       z = "access permission denied";              break;

     case SQLITE_ABORT:      z = "callback requested query abort";        break;

     case SQLITE_BUSY:       z = "database is locked";                    break;

     case SQLITE_LOCKED:     z = "database table is locked";              break;

     case SQLITE_NOMEM:      z = "out of memory";                         break;

     case SQLITE_READONLY:   z = "attempt to write a readonly database";  break;

     case SQLITE_INTERRUPT:  z = "interrupted";                           break;

     case SQLITE_IOERR:      z = "disk I/O error";                        break;

     case SQLITE_CORRUPT:    z = "database disk image is malformed";      break;

     case SQLITE_FULL:       z = "database or disk is full";              break;

     case SQLITE_CANTOPEN:   z = "unable to open database file";          break;

     case SQLITE_EMPTY:      z = "table contains no data";                break;

     case SQLITE_SCHEMA:     z = "database schema has changed";           break;

     case SQLITE_TOOBIG:     z = "String or BLOB exceeded size limit";    break;

     case SQLITE_CONSTRAINT: z = "constraint failed";                     break;

     case SQLITE_MISMATCH:   z = "datatype mismatch";                     break;

     case SQLITE_MISUSE:     z = "library routine called out of sequence";break;

     case SQLITE_NOLFS:      z = "kernel lacks large file support";       break;

     case SQLITE_AUTH:       z = "authorization denied";                  break;

     case SQLITE_FORMAT:     z = "auxiliary database format error";       break;

     case SQLITE_RANGE:      z = "bind or column index out of range";     break;

     case SQLITE_NOTADB:     z = "file is encrypted or is not a database";break;

     default:                z = "unknown error";                         break;

   }

   return z;

 }

 /*

 ** This routine implements a busy callback that sleeps and tries

 ** again until a timeout value is reached.  The timeout value is

 ** an integer number of milliseconds passed in as the first

 ** argument.

 */

 static int sqliteDefaultBusyCallback(

  void *ptr,               /* Database connection */

  int count                /* Number of times table has been busy */

 ){

 #if OS_WIN || (defined(HAVE_USLEEP) && HAVE_USLEEP)

   static const u8 delays[] =

      { 1, 2, 5, 10, 15, 20, 25, 25,  25,  50,  50, 100 };

   static const u8 totals[] =

      { 0, 1, 3,  8, 18, 33, 53, 78, 103, 128, 178, 228 };

 # define NDELAY (sizeof(delays)/sizeof(delays[0]))

   sqlite3 *db = (sqlite3 *)ptr;

   int timeout = db->busyTimeout;

   int delay, prior;

   assert( count>=0 );

   if( count < NDELAY ){

     delay = delays[count];

     prior = totals[count];

   }else{

     delay = delays[NDELAY-1];

     prior = totals[NDELAY-1] + delay*(count-(NDELAY-1));

   }

   if( prior + delay > timeout ){

     delay = timeout - prior;

     if( delay<=0 ) return 0;

   }

   sqlite3OsSleep(db->pVfs, delay*1000);

   return 1;

 #else

   sqlite3 *db = (sqlite3 *)ptr;

   int timeout = ((sqlite3 *)ptr)->busyTimeout;

   if( (count+1)*1000 > timeout ){

     return 0;

   }

   sqlite3OsSleep(db->pVfs, 1000000);

   return 1;

 #endif

 }

 /*

 ** Invoke the given busy handler.

 **

 ** This routine is called when an operation failed with a lock.

 ** If this routine returns non-zero, the lock is retried.  If it

 ** returns 0, the operation aborts with an SQLITE_BUSY error.

 */

 int sqlite3InvokeBusyHandler(BusyHandler *p){

   int rc;

   if( p==0 || p->xFunc==0 || p->nBusy<0 ) return 0;

   rc = p->xFunc(p->pArg, p->nBusy);

   if( rc==0 ){

     p->nBusy = -1;

   }else{

     p->nBusy++;

   }

   return rc; 

 }

 /*

 ** This routine sets the busy callback for an Sqlite database to the

 ** given callback function with the given argument.

 */

 int sqlite3_busy_handler(

   sqlite3 *db,

   int (*xBusy)(void*,int),

   void *pArg

 ){

   if( sqlite3SafetyCheck(db) ){

     return SQLITE_MISUSE;

   }

   sqlite3_mutex_enter(db->mutex);

   db->busyHandler.xFunc = xBusy;

   db->busyHandler.pArg = pArg;

   db->busyHandler.nBusy = 0;

   sqlite3_mutex_leave(db->mutex);

   return SQLITE_OK;

 }

 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK

 /*

 ** This routine sets the progress callback for an Sqlite database to the

 ** given callback function with the given argument. The progress callback will

 ** be invoked every nOps opcodes.

 */

 void sqlite3_progress_handler(

   sqlite3 *db, 

   int nOps,

   int (*xProgress)(void*), 

   void *pArg

 ){

   if( !sqlite3SafetyCheck(db) ){

     sqlite3_mutex_enter(db->mutex);

     if( nOps>0 ){

       db->xProgress = xProgress;

       db->nProgressOps = nOps;

       db->pProgressArg = pArg;

     }else{

       db->xProgress = 0;

       db->nProgressOps = 0;

       db->pProgressArg = 0;

     }

     sqlite3_mutex_leave(db->mutex);

   }

 }

 #endif

 /*

 ** This routine installs a default busy handler that waits for the

 ** specified number of milliseconds before returning 0.

 */

 int sqlite3_busy_timeout(sqlite3 *db, int ms){

   if( sqlite3SafetyCheck(db) ){

     return SQLITE_MISUSE;

   }

   if( ms>0 ){

     db->busyTimeout = ms;

     sqlite3_busy_handler(db, sqliteDefaultBusyCallback, (void*)db);

   }else{

     sqlite3_busy_handler(db, 0, 0);

   }

   return SQLITE_OK;

 }

 /*

 ** Cause any pending operation to stop at its earliest opportunity.

 */

 void sqlite3_interrupt(sqlite3 *db){

   if( db && (db->magic==SQLITE_MAGIC_OPEN || db->magic==SQLITE_MAGIC_BUSY) ){

     db->u1.isInterrupted = 1;

   }

 }

 /*

 ** This function is exactly the same as sqlite3_create_function(), except

 ** that it is designed to be called by internal code. The difference is

 ** that if a malloc() fails in sqlite3_create_function(), an error code

 ** is returned and the mallocFailed flag cleared. 

 */

 int sqlite3CreateFunc(

   sqlite3 *db,

   const char *zFunctionName,

   int nArg,

   int enc,

   void *pUserData,

   void (*xFunc)(sqlite3_context*,int,sqlite3_value **),

   void (*xStep)(sqlite3_context*,int,sqlite3_value **),

   void (*xFinal)(sqlite3_context*)

 ){

   FuncDef *p;

   int nName;

   assert( sqlite3_mutex_held(db->mutex) );

   if( sqlite3SafetyCheck(db) ){

     return SQLITE_MISUSE;

   }

   if( zFunctionName==0 ||

       (xFunc && (xFinal || xStep)) || 

       (!xFunc && (xFinal && !xStep)) ||

       (!xFunc && (!xFinal && xStep)) ||

       (nArg<-1 || nArg>127) ||

       (255<(nName = strlen(zFunctionName))) ){

     sqlite3Error(db, SQLITE_ERROR, "bad parameters");

     return SQLITE_ERROR;

   }

 #ifndef SQLITE_OMIT_UTF16

   /* If SQLITE_UTF16 is specified as the encoding type, transform this

   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the

   ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.

   **

   ** If SQLITE_ANY is specified, add three versions of the function

   ** to the hash table.

   */

   if( enc==SQLITE_UTF16 ){

     enc = SQLITE_UTF16NATIVE;

   }else if( enc==SQLITE_ANY ){

     int rc;

     rc = sqlite3CreateFunc(db, zFunctionName, nArg, SQLITE_UTF8,

          pUserData, xFunc, xStep, xFinal);

     if( rc==SQLITE_OK ){

       rc = sqlite3CreateFunc(db, zFunctionName, nArg, SQLITE_UTF16LE,

           pUserData, xFunc, xStep, xFinal);

     }

     if( rc!=SQLITE_OK ){

       return rc;

     }

     enc = SQLITE_UTF16BE;

   }

 #else

   enc = SQLITE_UTF8;

 #endif

   /* Check if an existing function is being overridden or deleted. If so,

   ** and there are active VMs, then return SQLITE_BUSY. If a function

   ** is being overridden/deleted but there are no active VMs, allow the

   ** operation to continue but invalidate all precompiled statements.

   */

   p = sqlite3FindFunction(db, zFunctionName, nName, nArg, enc, 0);

   if( p && p->iPrefEnc==enc && p->nArg==nArg ){

     if( db->activeVdbeCnt ){

       sqlite3Error(db, SQLITE_BUSY, 

         "Unable to delete/modify user-function due to active statements");

       assert( !db->mallocFailed );

       return SQLITE_BUSY;

     }else{

       sqlite3ExpirePreparedStatements(db);

     }

   }

   p = sqlite3FindFunction(db, zFunctionName, nName, nArg, enc, 1);

   assert(p || db->mallocFailed);

   if( !p ){

     return SQLITE_NOMEM;

   }

   p->flags = 0;

   p->xFunc = xFunc;

   p->xStep = xStep;

   p->xFinalize = xFinal;

   p->pUserData = pUserData;

   p->nArg = nArg;

   return SQLITE_OK;

 }

 /*

 ** Create new user functions.

 */

 int sqlite3_create_function(

   sqlite3 *db,

   const char *zFunctionName,

   int nArg,

   int enc,

   void *p,

   void (*xFunc)(sqlite3_context*,int,sqlite3_value **),

   void (*xStep)(sqlite3_context*,int,sqlite3_value **),

   void (*xFinal)(sqlite3_context*)

 ){

   int rc;

   sqlite3_mutex_enter(db->mutex);

   assert( !db->mallocFailed );

   rc = sqlite3CreateFunc(db, zFunctionName, nArg, enc, p, xFunc, xStep, xFinal);

   rc = sqlite3ApiExit(db, rc);

   sqlite3_mutex_leave(db->mutex);

   return rc;

 }

 #ifndef SQLITE_OMIT_UTF16

 int sqlite3_create_function16(

   sqlite3 *db,

   const void *zFunctionName,

   int nArg,

   int eTextRep,

   void *p,

   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),

   void (*xStep)(sqlite3_context*,int,sqlite3_value**),

   void (*xFinal)(sqlite3_context*)

 ){

   int rc;

   char *zFunc8;

   sqlite3_mutex_enter(db->mutex);

   assert( !db->mallocFailed );

   zFunc8 = sqlite3Utf16to8(db, zFunctionName, -1);

   rc = sqlite3CreateFunc(db, zFunc8, nArg, eTextRep, p, xFunc, xStep, xFinal);

   sqlite3_free(zFunc8);

   rc = sqlite3ApiExit(db, rc);

   sqlite3_mutex_leave(db->mutex);

   return rc;

 }

 #endif

 /*

 ** Declare that a function has been overloaded by a virtual table.

 **

 ** If the function already exists as a regular global function, then

 ** this routine is a no-op.  If the function does not exist, then create

 ** a new one that always throws a run-time error.  

 **

 ** When virtual tables intend to provide an overloaded function, they

 ** should call this routine to make sure the global function exists.

 ** A global function must exist in order for name resolution to work

 ** properly.

 */

 int sqlite3_overload_function(

   sqlite3 *db,

   const char *zName,

   int nArg

 ){

   int nName = strlen(zName);

   int rc;

   sqlite3_mutex_enter(db->mutex);

   if( sqlite3FindFunction(db, zName, nName, nArg, SQLITE_UTF8, 0)==0 ){

     sqlite3CreateFunc(db, zName, nArg, SQLITE_UTF8,

                       0, sqlite3InvalidFunction, 0, 0);

   }

   rc = sqlite3ApiExit(db, SQLITE_OK);

   sqlite3_mutex_leave(db->mutex);

   return rc;

 }

 #ifndef SQLITE_OMIT_TRACE

 /*

 ** Register a trace function.  The pArg from the previously registered trace

 ** is returned.  

 **

 ** A NULL trace function means that no tracing is executes.  A non-NULL

 ** trace is a pointer to a function that is invoked at the start of each

 ** SQL statement.

 */

 void *sqlite3_trace(sqlite3 *db, void (*xTrace)(void*,const char*), void *pArg){

   void *pOld;

   sqlite3_mutex_enter(db->mutex);

   pOld = db->pTraceArg;

   db->xTrace = xTrace;

   db->pTraceArg = pArg;

   sqlite3_mutex_leave(db->mutex);

   return pOld;

 }

 /*

 ** Register a profile function.  The pArg from the previously registered 

 ** profile function is returned.  

 **

 ** A NULL profile function means that no profiling is executes.  A non-NULL

 ** profile is a pointer to a function that is invoked at the conclusion of

 ** each SQL statement that is run.

 */

 void *sqlite3_profile(

   sqlite3 *db,

   void (*xProfile)(void*,const char*,sqlite_uint64),

   void *pArg

 ){

   void *pOld;

   sqlite3_mutex_enter(db->mutex);

   pOld = db->pProfileArg;

   db->xProfile = xProfile;

   db->pProfileArg = pArg;

   sqlite3_mutex_leave(db->mutex);

   return pOld;

 }

 #endif /* SQLITE_OMIT_TRACE */

 /*** EXPERIMENTAL ***

 **

 ** Register a function to be invoked when a transaction comments.

 ** If the invoked function returns non-zero, then the commit becomes a

 ** rollback.

 */

 void *sqlite3_commit_hook(

   sqlite3 *db,              /* Attach the hook to this database */

   int (*xCallback)(void*),  /* Function to invoke on each commit */

   void *pArg                /* Argument to the function */

 ){

   void *pOld;

   sqlite3_mutex_enter(db->mutex);

   pOld = db->pCommitArg;

   db->xCommitCallback = xCallback;

   db->pCommitArg = pArg;

   sqlite3_mutex_leave(db->mutex);

   return pOld;

 }

 /*

 ** Register a callback to be invoked each time a row is updated,

 ** inserted or deleted using this database connection.

 */

 void *sqlite3_update_hook(

   sqlite3 *db,              /* Attach the hook to this database */

   void (*xCallback)(void*,int,char const *,char const *,sqlite_int64),

   void *pArg                /* Argument to the function */

 ){

   void *pRet;

   sqlite3_mutex_enter(db->mutex);

   pRet = db->pUpdateArg;

   db->xUpdateCallback = xCallback;

   db->pUpdateArg = pArg;

   sqlite3_mutex_leave(db->mutex);

   return pRet;

 }

 /*

 ** Register a callback to be invoked each time a transaction is rolled

 ** back by this database connection.

 */

 void *sqlite3_rollback_hook(

   sqlite3 *db,              /* Attach the hook to this database */

   void (*xCallback)(void*), /* Callback function */

   void *pArg                /* Argument to the function */

 ){

   void *pRet;

   sqlite3_mutex_enter(db->mutex);

   pRet = db->pRollbackArg;

   db->xRollbackCallback = xCallback;

   db->pRollbackArg = pArg;

   sqlite3_mutex_leave(db->mutex);

   return pRet;

 }

 /*

 ** This routine is called to create a connection to a database BTree

 ** driver.  If zFilename is the name of a file, then that file is

 ** opened and used.  If zFilename is the magic name ":memory:" then

 ** the database is stored in memory (and is thus forgotten as soon as

 ** the connection is closed.)  If zFilename is NULL then the database

 ** is a "virtual" database for transient use only and is deleted as

 ** soon as the connection is closed.

 **

 ** A virtual database can be either a disk file (that is automatically

 ** deleted when the file is closed) or it an be held entirely in memory,

 ** depending on the values of the TEMP_STORE compile-time macro and the

 ** db->temp_store variable, according to the following chart:

 **

 **       TEMP_STORE     db->temp_store     Location of temporary database

 **       ----------     --------------     ------------------------------

 **           0               any             file

 **           1                1              file

 **           1                2              memory

 **           1                0              file

 **           2                1              file

 **           2                2              memory

 **           2                0              memory

 **           3               any             memory

 */

 int sqlite3BtreeFactory(

   const sqlite3 *db,        /* Main database when opening aux otherwise 0 */

   const char *zFilename,    /* Name of the file containing the BTree database */

   int omitJournal,          /* if TRUE then do not journal this file */

   int nCache,               /* How many pages in the page cache */

   int vfsFlags,             /* Flags passed through to vfsOpen */

   Btree **ppBtree           /* Pointer to new Btree object written here */

 ){

   int btFlags = 0;

   int rc;

   assert( sqlite3_mutex_held(db->mutex) );

   assert( ppBtree != 0);

   if( omitJournal ){

     btFlags |= BTREE_OMIT_JOURNAL;

   }

   if( db->flags & SQLITE_NoReadlock ){

     btFlags |= BTREE_NO_READLOCK;

   }

   if( zFilename==0 ){

 #if TEMP_STORE==0

     /* Do nothing */

 #endif

 #ifndef SQLITE_OMIT_MEMORYDB

 #if TEMP_STORE==1

     if( db->temp_store==2 ) zFilename = ":memory:";

 #endif

 #if TEMP_STORE==2

     if( db->temp_store!=1 ) zFilename = ":memory:";

 #endif

 #if TEMP_STORE==3

     zFilename = ":memory:";

 #endif

 #endif /* SQLITE_OMIT_MEMORYDB */

   }

   if( (vfsFlags & SQLITE_OPEN_MAIN_DB)!=0 && (zFilename==0 || *zFilename==0) ){

     vfsFlags = (vfsFlags & ~SQLITE_OPEN_MAIN_DB) | SQLITE_OPEN_TEMP_DB;

   }

   rc = sqlite3BtreeOpen(zFilename, (sqlite3 *)db, ppBtree, btFlags, vfsFlags);

   if( rc==SQLITE_OK ){

     sqlite3BtreeSetBusyHandler(*ppBtree, (void*)&db->busyHandler);

     sqlite3BtreeSetCacheSize(*ppBtree, nCache);

   }

   return rc;

 }

 /*

 ** Return UTF-8 encoded English language explanation of the most recent

 ** error.

 */

 const char *sqlite3_errmsg(sqlite3 *db){

   const char *z;

   if( !db ){

     return sqlite3ErrStr(SQLITE_NOMEM);

   }

   if( sqlite3SafetyCheck(db) || db->errCode==SQLITE_MISUSE ){

     return sqlite3ErrStr(SQLITE_MISUSE);

   }

   sqlite3_mutex_enter(db->mutex);

   assert( !db->mallocFailed );

   z = (char*)sqlite3_value_text(db->pErr);

   if( z==0 ){

     z = sqlite3ErrStr(db->errCode);

   }

   sqlite3_mutex_leave(db->mutex);

   return z;

 }

 #ifndef SQLITE_OMIT_UTF16

 /*

 ** Return UTF-16 encoded English language explanation of the most recent

 ** error.

 */

 const void *sqlite3_errmsg16(sqlite3 *db){

   /* Because all the characters in the string are in the unicode

   ** range 0x00-0xFF, if we pad the big-endian string with a 

   ** zero byte, we can obtain the little-endian string with

   ** &big_endian[1].

   */

   static const char outOfMemBe[] = {

     0, 'o', 0, 'u', 0, 't', 0, ' ', 

     0, 'o', 0, 'f', 0, ' ', 

     0, 'm', 0, 'e', 0, 'm', 0, 'o', 0, 'r', 0, 'y', 0, 0, 0

   };

   static const char misuseBe [] = {

     0, 'l', 0, 'i', 0, 'b', 0, 'r', 0, 'a', 0, 'r', 0, 'y', 0, ' ', 

     0, 'r', 0, 'o', 0, 'u', 0, 't', 0, 'i', 0, 'n', 0, 'e', 0, ' ', 

     0, 'c', 0, 'a', 0, 'l', 0, 'l', 0, 'e', 0, 'd', 0, ' ', 

     0, 'o', 0, 'u', 0, 't', 0, ' ', 

     0, 'o', 0, 'f', 0, ' ', 

     0, 's', 0, 'e', 0, 'q', 0, 'u', 0, 'e', 0, 'n', 0, 'c', 0, 'e', 0, 0, 0

   };

   const void *z;

   if( !db ){

     return (void *)(&outOfMemBe[SQLITE_UTF16NATIVE==SQLITE_UTF16LE?1:0]);

   }

   if( sqlite3SafetyCheck(db) || db->errCode==SQLITE_MISUSE ){

     return (void *)(&misuseBe[SQLITE_UTF16NATIVE==SQLITE_UTF16LE?1:0]);

   }

   sqlite3_mutex_enter(db->mutex);

   assert( !db->mallocFailed );

   z = sqlite3_value_text16(db->pErr);

   if( z==0 ){

     sqlite3ValueSetStr(db->pErr, -1, sqlite3ErrStr(db->errCode),

          SQLITE_UTF8, SQLITE_STATIC);

     z = sqlite3_value_text16(db->pErr);

   }

   sqlite3ApiExit(0, 0);

   sqlite3_mutex_leave(db->mutex);

   return z;

 }

 #endif /* SQLITE_OMIT_UTF16 */

 /*

 ** Return the most recent error code generated by an SQLite routine. If NULL is

 ** passed to this function, we assume a malloc() failed during sqlite3_open().

 */

 int sqlite3_errcode(sqlite3 *db){

   if( !db || db->mallocFailed ){

     return SQLITE_NOMEM;

   }

   if( sqlite3SafetyCheck(db) ){

     return SQLITE_MISUSE;

   }

   return db->errCode & db->errMask;

 }

 /*

 ** Create a new collating function for database "db".  The name is zName

 ** and the encoding is enc.

 */

 static int createCollation(

   sqlite3* db, 

   const char *zName, 

   int enc, 

   void* pCtx,

   int(*xCompare)(void*,int,const void*,int,const void*),

   void(*xDel)(void*)

 ){

   CollSeq *pColl;

   int enc2;

   if( sqlite3SafetyCheck(db) ){

     return SQLITE_MISUSE;

   }

   assert( sqlite3_mutex_held(db->mutex) );

   /* If SQLITE_UTF16 is specified as the encoding type, transform this

   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the

   ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.

   */

   enc2 = enc & ~SQLITE_UTF16_ALIGNED;

   if( enc2==SQLITE_UTF16 ){