rtabmap: sqlite3.c Source File

Go to the documentation of this file.
00001 /******************************************************************************
00002 ** This file is an amalgamation of many separate C source files from SQLite
00003 ** version 3.8.2.  By combining all the individual C code files into this 
00004 ** single large file, the entire code can be compiled as a single translation
00005 ** unit.  This allows many compilers to do optimizations that would not be
00006 ** possible if the files were compiled separately.  Performance improvements
00007 ** of 5% or more are commonly seen when SQLite is compiled as a single
00008 ** translation unit.
00009 **
00010 ** This file is all you need to compile SQLite.  To use SQLite in other
00011 ** programs, you need this file and the "sqlite3.h" header file that defines
00012 ** the programming interface to the SQLite library.  (If you do not have 
00013 ** the "sqlite3.h" header file at hand, you will find a copy embedded within
00014 ** the text of this file.  Search for "Begin file sqlite3.h" to find the start
00015 ** of the embedded sqlite3.h header file.) Additional code files may be needed
00016 ** if you want a wrapper to interface SQLite with your choice of programming
00017 ** language. The code for the "sqlite3" command-line shell is also in a
00018 ** separate file. This file contains only code for the core SQLite library.
00019 */
00020 #define SQLITE_CORE 1
00021 #define SQLITE_AMALGAMATION 1
00022 #ifndef SQLITE_PRIVATE
00023 # define SQLITE_PRIVATE static
00024 #endif
00025 #ifndef SQLITE_API
00026 # define SQLITE_API
00027 #endif
00028 /************** Begin file sqlite3.h *****************************************/
00029 /*
00030 ** 2001 September 15
00031 **
00032 ** The author disclaims copyright to this source code.  In place of
00033 ** a legal notice, here is a blessing:
00034 **
00035 **    May you do good and not evil.
00036 **    May you find forgiveness for yourself and forgive others.
00037 **    May you share freely, never taking more than you give.
00038 **
00039 *************************************************************************
00040 ** This header file defines the interface that the SQLite library
00041 ** presents to client programs.  If a C-function, structure, datatype,
00042 ** or constant definition does not appear in this file, then it is
00043 ** not a published API of SQLite, is subject to change without
00044 ** notice, and should not be referenced by programs that use SQLite.
00045 **
00046 ** Some of the definitions that are in this file are marked as
00047 ** "experimental".  Experimental interfaces are normally new
00048 ** features recently added to SQLite.  We do not anticipate changes
00049 ** to experimental interfaces but reserve the right to make minor changes
00050 ** if experience from use "in the wild" suggest such changes are prudent.
00051 **
00052 ** The official C-language API documentation for SQLite is derived
00053 ** from comments in this file.  This file is the authoritative source
00054 ** on how SQLite interfaces are suppose to operate.
00055 **
00056 ** The name of this file under configuration management is "sqlite.h.in".
00057 ** The makefile makes some minor changes to this file (such as inserting
00058 ** the version number) and changes its name to "sqlite3.h" as
00059 ** part of the build process.
00060 */
00061 #ifndef _SQLITE3_H_
00062 #define _SQLITE3_H_
00063 #include <stdarg.h>     /* Needed for the definition of va_list */
00064 
00065 /*
00066 ** Make sure we can call this stuff from C++.
00067 */
00068 #if 0
00069 extern "C" {
00070 #endif
00071 
00072 
00073 /*
00074 ** Add the ability to override 'extern'
00075 */
00076 #ifndef SQLITE_EXTERN
00077 # define SQLITE_EXTERN extern
00078 #endif
00079 
00080 #ifndef SQLITE_API
00081 # define SQLITE_API
00082 #endif
00083 
00084 
00085 /*
00086 ** These no-op macros are used in front of interfaces to mark those
00087 ** interfaces as either deprecated or experimental.  New applications
00088 ** should not use deprecated interfaces - they are support for backwards
00089 ** compatibility only.  Application writers should be aware that
00090 ** experimental interfaces are subject to change in point releases.
00091 **
00092 ** These macros used to resolve to various kinds of compiler magic that
00093 ** would generate warning messages when they were used.  But that
00094 ** compiler magic ended up generating such a flurry of bug reports
00095 ** that we have taken it all out and gone back to using simple
00096 ** noop macros.
00097 */
00098 #define SQLITE_DEPRECATED
00099 #define SQLITE_EXPERIMENTAL
00100 
00101 /*
00102 ** Ensure these symbols were not defined by some previous header file.
00103 */
00104 #ifdef SQLITE_VERSION
00105 # undef SQLITE_VERSION
00106 #endif
00107 #ifdef SQLITE_VERSION_NUMBER
00108 # undef SQLITE_VERSION_NUMBER
00109 #endif
00110 
00111 /*
00112 ** CAPI3REF: Compile-Time Library Version Numbers
00113 **
00114 ** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
00115 ** evaluates to a string literal that is the SQLite version in the
00116 ** format "X.Y.Z" where X is the major version number (always 3 for
00117 ** SQLite3) and Y is the minor version number and Z is the release number.)^
00118 ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
00119 ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
00120 ** numbers used in [SQLITE_VERSION].)^
00121 ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
00122 ** be larger than the release from which it is derived.  Either Y will
00123 ** be held constant and Z will be incremented or else Y will be incremented
00124 ** and Z will be reset to zero.
00125 **
00126 ** Since version 3.6.18, SQLite source code has been stored in the
00127 ** <a href="http://www.fossil-scm.org/">Fossil configuration management
00128 ** system</a>.  ^The SQLITE_SOURCE_ID macro evaluates to
00129 ** a string which identifies a particular check-in of SQLite
00130 ** within its configuration management system.  ^The SQLITE_SOURCE_ID
00131 ** string contains the date and time of the check-in (UTC) and an SHA1
00132 ** hash of the entire source tree.
00133 **
00134 ** See also: [sqlite3_libversion()],
00135 ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
00136 ** [sqlite_version()] and [sqlite_source_id()].
00137 */
00138 #define SQLITE_VERSION        "3.8.2"
00139 #define SQLITE_VERSION_NUMBER 3008002
00140 #define SQLITE_SOURCE_ID      "2013-12-06 14:53:30 27392118af4c38c5203a04b8013e1afdb1cebd0d"
00141 
00142 /*
00143 ** CAPI3REF: Run-Time Library Version Numbers
00144 ** KEYWORDS: sqlite3_version, sqlite3_sourceid
00145 **
00146 ** These interfaces provide the same information as the [SQLITE_VERSION],
00147 ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
00148 ** but are associated with the library instead of the header file.  ^(Cautious
00149 ** programmers might include assert() statements in their application to
00150 ** verify that values returned by these interfaces match the macros in
00151 ** the header, and thus insure that the application is
00152 ** compiled with matching library and header files.
00153 **
00154 ** <blockquote><pre>
00155 ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
00156 ** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
00157 ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
00158 ** </pre></blockquote>)^
00159 **
00160 ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
00161 ** macro.  ^The sqlite3_libversion() function returns a pointer to the
00162 ** to the sqlite3_version[] string constant.  The sqlite3_libversion()
00163 ** function is provided for use in DLLs since DLL users usually do not have
00164 ** direct access to string constants within the DLL.  ^The
00165 ** sqlite3_libversion_number() function returns an integer equal to
00166 ** [SQLITE_VERSION_NUMBER].  ^The sqlite3_sourceid() function returns 
00167 ** a pointer to a string constant whose value is the same as the 
00168 ** [SQLITE_SOURCE_ID] C preprocessor macro.
00169 **
00170 ** See also: [sqlite_version()] and [sqlite_source_id()].
00171 */
00172 SQLITE_API const char sqlite3_version[] = SQLITE_VERSION;
00173 SQLITE_API const char *sqlite3_libversion(void);
00174 SQLITE_API const char *sqlite3_sourceid(void);
00175 SQLITE_API int sqlite3_libversion_number(void);
00176 
00177 /*
00178 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics
00179 **
00180 ** ^The sqlite3_compileoption_used() function returns 0 or 1 
00181 ** indicating whether the specified option was defined at 
00182 ** compile time.  ^The SQLITE_ prefix may be omitted from the 
00183 ** option name passed to sqlite3_compileoption_used().  
00184 **
00185 ** ^The sqlite3_compileoption_get() function allows iterating
00186 ** over the list of options that were defined at compile time by
00187 ** returning the N-th compile time option string.  ^If N is out of range,
00188 ** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_ 
00189 ** prefix is omitted from any strings returned by 
00190 ** sqlite3_compileoption_get().
00191 **
00192 ** ^Support for the diagnostic functions sqlite3_compileoption_used()
00193 ** and sqlite3_compileoption_get() may be omitted by specifying the 
00194 ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
00195 **
00196 ** See also: SQL functions [sqlite_compileoption_used()] and
00197 ** [sqlite_compileoption_get()] and the [compile_options pragma].
00198 */
00199 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
00200 SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
00201 SQLITE_API const char *sqlite3_compileoption_get(int N);
00202 #endif
00203 
00204 /*
00205 ** CAPI3REF: Test To See If The Library Is Threadsafe
00206 **
00207 ** ^The sqlite3_threadsafe() function returns zero if and only if
00208 ** SQLite was compiled with mutexing code omitted due to the
00209 ** [SQLITE_THREADSAFE] compile-time option being set to 0.
00210 **
00211 ** SQLite can be compiled with or without mutexes.  When
00212 ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
00213 ** are enabled and SQLite is threadsafe.  When the
00214 ** [SQLITE_THREADSAFE] macro is 0, 
00215 ** the mutexes are omitted.  Without the mutexes, it is not safe
00216 ** to use SQLite concurrently from more than one thread.
00217 **
00218 ** Enabling mutexes incurs a measurable performance penalty.
00219 ** So if speed is of utmost importance, it makes sense to disable
00220 ** the mutexes.  But for maximum safety, mutexes should be enabled.
00221 ** ^The default behavior is for mutexes to be enabled.
00222 **
00223 ** This interface can be used by an application to make sure that the
00224 ** version of SQLite that it is linking against was compiled with
00225 ** the desired setting of the [SQLITE_THREADSAFE] macro.
00226 **
00227 ** This interface only reports on the compile-time mutex setting
00228 ** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with
00229 ** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
00230 ** can be fully or partially disabled using a call to [sqlite3_config()]
00231 ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
00232 ** or [SQLITE_CONFIG_MUTEX].  ^(The return value of the
00233 ** sqlite3_threadsafe() function shows only the compile-time setting of
00234 ** thread safety, not any run-time changes to that setting made by
00235 ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
00236 ** is unchanged by calls to sqlite3_config().)^
00237 **
00238 ** See the [threading mode] documentation for additional information.
00239 */
00240 SQLITE_API int sqlite3_threadsafe(void);
00241 
00242 /*
00243 ** CAPI3REF: Database Connection Handle
00244 ** KEYWORDS: {database connection} {database connections}
00245 **
00246 ** Each open SQLite database is represented by a pointer to an instance of
00247 ** the opaque structure named "sqlite3".  It is useful to think of an sqlite3
00248 ** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
00249 ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
00250 ** and [sqlite3_close_v2()] are its destructors.  There are many other
00251 ** interfaces (such as
00252 ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
00253 ** [sqlite3_busy_timeout()] to name but three) that are methods on an
00254 ** sqlite3 object.
00255 */
00256 typedef struct sqlite3 sqlite3;
00257 
00258 /*
00259 ** CAPI3REF: 64-Bit Integer Types
00260 ** KEYWORDS: sqlite_int64 sqlite_uint64
00261 **
00262 ** Because there is no cross-platform way to specify 64-bit integer types
00263 ** SQLite includes typedefs for 64-bit signed and unsigned integers.
00264 **
00265 ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
00266 ** The sqlite_int64 and sqlite_uint64 types are supported for backwards
00267 ** compatibility only.
00268 **
00269 ** ^The sqlite3_int64 and sqlite_int64 types can store integer values
00270 ** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The
00271 ** sqlite3_uint64 and sqlite_uint64 types can store integer values 
00272 ** between 0 and +18446744073709551615 inclusive.
00273 */
00274 #ifdef SQLITE_INT64_TYPE
00275   typedef SQLITE_INT64_TYPE sqlite_int64;
00276   typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
00277 #elif defined(_MSC_VER) || defined(__BORLANDC__)
00278   typedef __int64 sqlite_int64;
00279   typedef unsigned __int64 sqlite_uint64;
00280 #else
00281   typedef long long int sqlite_int64;
00282   typedef unsigned long long int sqlite_uint64;
00283 #endif
00284 typedef sqlite_int64 sqlite3_int64;
00285 typedef sqlite_uint64 sqlite3_uint64;
00286 
00287 /*
00288 ** If compiling for a processor that lacks floating point support,
00289 ** substitute integer for floating-point.
00290 */
00291 #ifdef SQLITE_OMIT_FLOATING_POINT
00292 # define double sqlite3_int64
00293 #endif
00294 
00295 /*
00296 ** CAPI3REF: Closing A Database Connection
00297 **
00298 ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
00299 ** for the [sqlite3] object.
00300 ** ^Calls to sqlite3_close() and sqlite3_close_v2() return SQLITE_OK if
00301 ** the [sqlite3] object is successfully destroyed and all associated
00302 ** resources are deallocated.
00303 **
00304 ** ^If the database connection is associated with unfinalized prepared
00305 ** statements or unfinished sqlite3_backup objects then sqlite3_close()
00306 ** will leave the database connection open and return [SQLITE_BUSY].
00307 ** ^If sqlite3_close_v2() is called with unfinalized prepared statements
00308 ** and unfinished sqlite3_backups, then the database connection becomes
00309 ** an unusable "zombie" which will automatically be deallocated when the
00310 ** last prepared statement is finalized or the last sqlite3_backup is
00311 ** finished.  The sqlite3_close_v2() interface is intended for use with
00312 ** host languages that are garbage collected, and where the order in which
00313 ** destructors are called is arbitrary.
00314 **
00315 ** Applications should [sqlite3_finalize | finalize] all [prepared statements],
00316 ** [sqlite3_blob_close | close] all [BLOB handles], and 
00317 ** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
00318 ** with the [sqlite3] object prior to attempting to close the object.  ^If
00319 ** sqlite3_close_v2() is called on a [database connection] that still has
00320 ** outstanding [prepared statements], [BLOB handles], and/or
00321 ** [sqlite3_backup] objects then it returns SQLITE_OK but the deallocation
00322 ** of resources is deferred until all [prepared statements], [BLOB handles],
00323 ** and [sqlite3_backup] objects are also destroyed.
00324 **
00325 ** ^If an [sqlite3] object is destroyed while a transaction is open,
00326 ** the transaction is automatically rolled back.
00327 **
00328 ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
00329 ** must be either a NULL
00330 ** pointer or an [sqlite3] object pointer obtained
00331 ** from [sqlite3_open()], [sqlite3_open16()], or
00332 ** [sqlite3_open_v2()], and not previously closed.
00333 ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
00334 ** argument is a harmless no-op.
00335 */
00336 SQLITE_API int sqlite3_close(sqlite3*);
00337 SQLITE_API int sqlite3_close_v2(sqlite3*);
00338 
00339 /*
00340 ** The type for a callback function.
00341 ** This is legacy and deprecated.  It is included for historical
00342 ** compatibility and is not documented.
00343 */
00344 typedef int (*sqlite3_callback)(void*,int,char**, char**);
00345 
00346 /*
00347 ** CAPI3REF: One-Step Query Execution Interface
00348 **
00349 ** The sqlite3_exec() interface is a convenience wrapper around
00350 ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
00351 ** that allows an application to run multiple statements of SQL
00352 ** without having to use a lot of C code. 
00353 **
00354 ** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
00355 ** semicolon-separate SQL statements passed into its 2nd argument,
00356 ** in the context of the [database connection] passed in as its 1st
00357 ** argument.  ^If the callback function of the 3rd argument to
00358 ** sqlite3_exec() is not NULL, then it is invoked for each result row
00359 ** coming out of the evaluated SQL statements.  ^The 4th argument to
00360 ** sqlite3_exec() is relayed through to the 1st argument of each
00361 ** callback invocation.  ^If the callback pointer to sqlite3_exec()
00362 ** is NULL, then no callback is ever invoked and result rows are
00363 ** ignored.
00364 **
00365 ** ^If an error occurs while evaluating the SQL statements passed into
00366 ** sqlite3_exec(), then execution of the current statement stops and
00367 ** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()
00368 ** is not NULL then any error message is written into memory obtained
00369 ** from [sqlite3_malloc()] and passed back through the 5th parameter.
00370 ** To avoid memory leaks, the application should invoke [sqlite3_free()]
00371 ** on error message strings returned through the 5th parameter of
00372 ** of sqlite3_exec() after the error message string is no longer needed.
00373 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
00374 ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
00375 ** NULL before returning.
00376 **
00377 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
00378 ** routine returns SQLITE_ABORT without invoking the callback again and
00379 ** without running any subsequent SQL statements.
00380 **
00381 ** ^The 2nd argument to the sqlite3_exec() callback function is the
00382 ** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()
00383 ** callback is an array of pointers to strings obtained as if from
00384 ** [sqlite3_column_text()], one for each column.  ^If an element of a
00385 ** result row is NULL then the corresponding string pointer for the
00386 ** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the
00387 ** sqlite3_exec() callback is an array of pointers to strings where each
00388 ** entry represents the name of corresponding result column as obtained
00389 ** from [sqlite3_column_name()].
00390 **
00391 ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
00392 ** to an empty string, or a pointer that contains only whitespace and/or 
00393 ** SQL comments, then no SQL statements are evaluated and the database
00394 ** is not changed.
00395 **
00396 ** Restrictions:
00397 **
00398 ** <ul>
00399 ** <li> The application must insure that the 1st parameter to sqlite3_exec()
00400 **      is a valid and open [database connection].
00401 ** <li> The application must not close the [database connection] specified by
00402 **      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
00403 ** <li> The application must not modify the SQL statement text passed into
00404 **      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
00405 ** </ul>
00406 */
00407 SQLITE_API int sqlite3_exec(
00408   sqlite3*,                                  /* An open database */
00409   const char *sql,                           /* SQL to be evaluated */
00410   int (*callback)(void*,int,char**,char**),  /* Callback function */
00411   void *,                                    /* 1st argument to callback */
00412   char **errmsg                              /* Error msg written here */
00413 );
00414 
00415 /*
00416 ** CAPI3REF: Result Codes
00417 ** KEYWORDS: SQLITE_OK {error code} {error codes}
00418 ** KEYWORDS: {result code} {result codes}
00419 **
00420 ** Many SQLite functions return an integer result code from the set shown
00421 ** here in order to indicate success or failure.
00422 **
00423 ** New error codes may be added in future versions of SQLite.
00424 **
00425 ** See also: [SQLITE_IOERR_READ | extended result codes],
00426 ** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes].
00427 */
00428 #define SQLITE_OK           0   /* Successful result */
00429 /* beginning-of-error-codes */
00430 #define SQLITE_ERROR        1   /* SQL error or missing database */
00431 #define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
00432 #define SQLITE_PERM         3   /* Access permission denied */
00433 #define SQLITE_ABORT        4   /* Callback routine requested an abort */
00434 #define SQLITE_BUSY         5   /* The database file is locked */
00435 #define SQLITE_LOCKED       6   /* A table in the database is locked */
00436 #define SQLITE_NOMEM        7   /* A malloc() failed */
00437 #define SQLITE_READONLY     8   /* Attempt to write a readonly database */
00438 #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
00439 #define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
00440 #define SQLITE_CORRUPT     11   /* The database disk image is malformed */
00441 #define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
00442 #define SQLITE_FULL        13   /* Insertion failed because database is full */
00443 #define SQLITE_CANTOPEN    14   /* Unable to open the database file */
00444 #define SQLITE_PROTOCOL    15   /* Database lock protocol error */
00445 #define SQLITE_EMPTY       16   /* Database is empty */
00446 #define SQLITE_SCHEMA      17   /* The database schema changed */
00447 #define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
00448 #define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
00449 #define SQLITE_MISMATCH    20   /* Data type mismatch */
00450 #define SQLITE_MISUSE      21   /* Library used incorrectly */
00451 #define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
00452 #define SQLITE_AUTH        23   /* Authorization denied */
00453 #define SQLITE_FORMAT      24   /* Auxiliary database format error */
00454 #define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
00455 #define SQLITE_NOTADB      26   /* File opened that is not a database file */
00456 #define SQLITE_NOTICE      27   /* Notifications from sqlite3_log() */
00457 #define SQLITE_WARNING     28   /* Warnings from sqlite3_log() */
00458 #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
00459 #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
00460 /* end-of-error-codes */
00461 
00462 /*
00463 ** CAPI3REF: Extended Result Codes
00464 ** KEYWORDS: {extended error code} {extended error codes}
00465 ** KEYWORDS: {extended result code} {extended result codes}
00466 **
00467 ** In its default configuration, SQLite API routines return one of 26 integer
00468 ** [SQLITE_OK | result codes].  However, experience has shown that many of
00469 ** these result codes are too coarse-grained.  They do not provide as
00470 ** much information about problems as programmers might like.  In an effort to
00471 ** address this, newer versions of SQLite (version 3.3.8 and later) include
00472 ** support for additional result codes that provide more detailed information
00473 ** about errors. The extended result codes are enabled or disabled
00474 ** on a per database connection basis using the
00475 ** [sqlite3_extended_result_codes()] API.
00476 **
00477 ** Some of the available extended result codes are listed here.
00478 ** One may expect the number of extended result codes will increase
00479 ** over time.  Software that uses extended result codes should expect
00480 ** to see new result codes in future releases of SQLite.
00481 **
00482 ** The SQLITE_OK result code will never be extended.  It will always
00483 ** be exactly zero.
00484 */
00485 #define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
00486 #define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
00487 #define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
00488 #define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
00489 #define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
00490 #define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
00491 #define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
00492 #define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
00493 #define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
00494 #define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
00495 #define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
00496 #define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
00497 #define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
00498 #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
00499 #define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
00500 #define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
00501 #define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
00502 #define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
00503 #define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
00504 #define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
00505 #define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))
00506 #define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
00507 #define SQLITE_IOERR_DELETE_NOENT      (SQLITE_IOERR | (23<<8))
00508 #define SQLITE_IOERR_MMAP              (SQLITE_IOERR | (24<<8))
00509 #define SQLITE_IOERR_GETTEMPPATH       (SQLITE_IOERR | (25<<8))
00510 #define SQLITE_IOERR_CONVPATH          (SQLITE_IOERR | (26<<8))
00511 #define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
00512 #define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
00513 #define SQLITE_BUSY_SNAPSHOT           (SQLITE_BUSY   |  (2<<8))
00514 #define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
00515 #define SQLITE_CANTOPEN_ISDIR          (SQLITE_CANTOPEN | (2<<8))
00516 #define SQLITE_CANTOPEN_FULLPATH       (SQLITE_CANTOPEN | (3<<8))
00517 #define SQLITE_CANTOPEN_CONVPATH       (SQLITE_CANTOPEN | (4<<8))
00518 #define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
00519 #define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
00520 #define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))
00521 #define SQLITE_READONLY_ROLLBACK       (SQLITE_READONLY | (3<<8))
00522 #define SQLITE_ABORT_ROLLBACK          (SQLITE_ABORT | (2<<8))
00523 #define SQLITE_CONSTRAINT_CHECK        (SQLITE_CONSTRAINT | (1<<8))
00524 #define SQLITE_CONSTRAINT_COMMITHOOK   (SQLITE_CONSTRAINT | (2<<8))
00525 #define SQLITE_CONSTRAINT_FOREIGNKEY   (SQLITE_CONSTRAINT | (3<<8))
00526 #define SQLITE_CONSTRAINT_FUNCTION     (SQLITE_CONSTRAINT | (4<<8))
00527 #define SQLITE_CONSTRAINT_NOTNULL      (SQLITE_CONSTRAINT | (5<<8))
00528 #define SQLITE_CONSTRAINT_PRIMARYKEY   (SQLITE_CONSTRAINT | (6<<8))
00529 #define SQLITE_CONSTRAINT_TRIGGER      (SQLITE_CONSTRAINT | (7<<8))
00530 #define SQLITE_CONSTRAINT_UNIQUE       (SQLITE_CONSTRAINT | (8<<8))
00531 #define SQLITE_CONSTRAINT_VTAB         (SQLITE_CONSTRAINT | (9<<8))
00532 #define SQLITE_CONSTRAINT_ROWID        (SQLITE_CONSTRAINT |(10<<8))
00533 #define SQLITE_NOTICE_RECOVER_WAL      (SQLITE_NOTICE | (1<<8))
00534 #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
00535 #define SQLITE_WARNING_AUTOINDEX       (SQLITE_WARNING | (1<<8))
00536 
00537 /*
00538 ** CAPI3REF: Flags For File Open Operations
00539 **
00540 ** These bit values are intended for use in the
00541 ** 3rd parameter to the [sqlite3_open_v2()] interface and
00542 ** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
00543 */
00544 #define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
00545 #define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
00546 #define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
00547 #define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
00548 #define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
00549 #define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */
00550 #define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */
00551 #define SQLITE_OPEN_MEMORY           0x00000080  /* Ok for sqlite3_open_v2() */
00552 #define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
00553 #define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
00554 #define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
00555 #define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
00556 #define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
00557 #define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
00558 #define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
00559 #define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
00560 #define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
00561 #define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
00562 #define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
00563 #define SQLITE_OPEN_WAL              0x00080000  /* VFS only */
00564 
00565 /* Reserved:                         0x00F00000 */
00566 
00567 /*
00568 ** CAPI3REF: Device Characteristics
00569 **
00570 ** The xDeviceCharacteristics method of the [sqlite3_io_methods]
00571 ** object returns an integer which is a vector of these
00572 ** bit values expressing I/O characteristics of the mass storage
00573 ** device that holds the file that the [sqlite3_io_methods]
00574 ** refers to.
00575 **
00576 ** The SQLITE_IOCAP_ATOMIC property means that all writes of
00577 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
00578 ** mean that writes of blocks that are nnn bytes in size and
00579 ** are aligned to an address which is an integer multiple of
00580 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
00581 ** that when data is appended to a file, the data is appended
00582 ** first then the size of the file is extended, never the other
00583 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
00584 ** information is written to disk in the same order as calls
00585 ** to xWrite().  The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
00586 ** after reboot following a crash or power loss, the only bytes in a
00587 ** file that were written at the application level might have changed
00588 ** and that adjacent bytes, even bytes within the same sector are
00589 ** guaranteed to be unchanged.
00590 */
00591 #define SQLITE_IOCAP_ATOMIC                 0x00000001
00592 #define SQLITE_IOCAP_ATOMIC512              0x00000002
00593 #define SQLITE_IOCAP_ATOMIC1K               0x00000004
00594 #define SQLITE_IOCAP_ATOMIC2K               0x00000008
00595 #define SQLITE_IOCAP_ATOMIC4K               0x00000010
00596 #define SQLITE_IOCAP_ATOMIC8K               0x00000020
00597 #define SQLITE_IOCAP_ATOMIC16K              0x00000040
00598 #define SQLITE_IOCAP_ATOMIC32K              0x00000080
00599 #define SQLITE_IOCAP_ATOMIC64K              0x00000100
00600 #define SQLITE_IOCAP_SAFE_APPEND            0x00000200
00601 #define SQLITE_IOCAP_SEQUENTIAL             0x00000400
00602 #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800
00603 #define SQLITE_IOCAP_POWERSAFE_OVERWRITE    0x00001000
00604 
00605 /*
00606 ** CAPI3REF: File Locking Levels
00607 **
00608 ** SQLite uses one of these integer values as the second
00609 ** argument to calls it makes to the xLock() and xUnlock() methods
00610 ** of an [sqlite3_io_methods] object.
00611 */
00612 #define SQLITE_LOCK_NONE          0
00613 #define SQLITE_LOCK_SHARED        1
00614 #define SQLITE_LOCK_RESERVED      2
00615 #define SQLITE_LOCK_PENDING       3
00616 #define SQLITE_LOCK_EXCLUSIVE     4
00617 
00618 /*
00619 ** CAPI3REF: Synchronization Type Flags
00620 **
00621 ** When SQLite invokes the xSync() method of an
00622 ** [sqlite3_io_methods] object it uses a combination of
00623 ** these integer values as the second argument.
00624 **
00625 ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
00626 ** sync operation only needs to flush data to mass storage.  Inode
00627 ** information need not be flushed. If the lower four bits of the flag
00628 ** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
00629 ** If the lower four bits equal SQLITE_SYNC_FULL, that means
00630 ** to use Mac OS X style fullsync instead of fsync().
00631 **
00632 ** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
00633 ** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
00634 ** settings.  The [synchronous pragma] determines when calls to the
00635 ** xSync VFS method occur and applies uniformly across all platforms.
00636 ** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
00637 ** energetic or rigorous or forceful the sync operations are and
00638 ** only make a difference on Mac OSX for the default SQLite code.
00639 ** (Third-party VFS implementations might also make the distinction
00640 ** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
00641 ** operating systems natively supported by SQLite, only Mac OSX
00642 ** cares about the difference.)
00643 */
00644 #define SQLITE_SYNC_NORMAL        0x00002
00645 #define SQLITE_SYNC_FULL          0x00003
00646 #define SQLITE_SYNC_DATAONLY      0x00010
00647 
00648 /*
00649 ** CAPI3REF: OS Interface Open File Handle
00650 **
00651 ** An [sqlite3_file] object represents an open file in the 
00652 ** [sqlite3_vfs | OS interface layer].  Individual OS interface
00653 ** implementations will
00654 ** want to subclass this object by appending additional fields
00655 ** for their own use.  The pMethods entry is a pointer to an
00656 ** [sqlite3_io_methods] object that defines methods for performing
00657 ** I/O operations on the open file.
00658 */
00659 typedef struct sqlite3_file sqlite3_file;
00660 struct sqlite3_file {
00661   const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
00662 };
00663 
00664 /*
00665 ** CAPI3REF: OS Interface File Virtual Methods Object
00666 **
00667 ** Every file opened by the [sqlite3_vfs.xOpen] method populates an
00668 ** [sqlite3_file] object (or, more commonly, a subclass of the
00669 ** [sqlite3_file] object) with a pointer to an instance of this object.
00670 ** This object defines the methods used to perform various operations
00671 ** against the open file represented by the [sqlite3_file] object.
00672 **
00673 ** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element 
00674 ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
00675 ** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed.  The
00676 ** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
00677 ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
00678 ** to NULL.
00679 **
00680 ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
00681 ** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().
00682 ** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]
00683 ** flag may be ORed in to indicate that only the data of the file
00684 ** and not its inode needs to be synced.
00685 **
00686 ** The integer values to xLock() and xUnlock() are one of
00687 ** <ul>
00688 ** <li> [SQLITE_LOCK_NONE],
00689 ** <li> [SQLITE_LOCK_SHARED],
00690 ** <li> [SQLITE_LOCK_RESERVED],
00691 ** <li> [SQLITE_LOCK_PENDING], or
00692 ** <li> [SQLITE_LOCK_EXCLUSIVE].
00693 ** </ul>
00694 ** xLock() increases the lock. xUnlock() decreases the lock.
00695 ** The xCheckReservedLock() method checks whether any database connection,
00696 ** either in this process or in some other process, is holding a RESERVED,
00697 ** PENDING, or EXCLUSIVE lock on the file.  It returns true
00698 ** if such a lock exists and false otherwise.
00699 **
00700 ** The xFileControl() method is a generic interface that allows custom
00701 ** VFS implementations to directly control an open file using the
00702 ** [sqlite3_file_control()] interface.  The second "op" argument is an
00703 ** integer opcode.  The third argument is a generic pointer intended to
00704 ** point to a structure that may contain arguments or space in which to
00705 ** write return values.  Potential uses for xFileControl() might be
00706 ** functions to enable blocking locks with timeouts, to change the
00707 ** locking strategy (for example to use dot-file locks), to inquire
00708 ** about the status of a lock, or to break stale locks.  The SQLite
00709 ** core reserves all opcodes less than 100 for its own use.
00710 ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
00711 ** Applications that define a custom xFileControl method should use opcodes
00712 ** greater than 100 to avoid conflicts.  VFS implementations should
00713 ** return [SQLITE_NOTFOUND] for file control opcodes that they do not
00714 ** recognize.
00715 **
00716 ** The xSectorSize() method returns the sector size of the
00717 ** device that underlies the file.  The sector size is the
00718 ** minimum write that can be performed without disturbing
00719 ** other bytes in the file.  The xDeviceCharacteristics()
00720 ** method returns a bit vector describing behaviors of the
00721 ** underlying device:
00722 **
00723 ** <ul>
00724 ** <li> [SQLITE_IOCAP_ATOMIC]
00725 ** <li> [SQLITE_IOCAP_ATOMIC512]
00726 ** <li> [SQLITE_IOCAP_ATOMIC1K]
00727 ** <li> [SQLITE_IOCAP_ATOMIC2K]
00728 ** <li> [SQLITE_IOCAP_ATOMIC4K]
00729 ** <li> [SQLITE_IOCAP_ATOMIC8K]
00730 ** <li> [SQLITE_IOCAP_ATOMIC16K]
00731 ** <li> [SQLITE_IOCAP_ATOMIC32K]
00732 ** <li> [SQLITE_IOCAP_ATOMIC64K]
00733 ** <li> [SQLITE_IOCAP_SAFE_APPEND]
00734 ** <li> [SQLITE_IOCAP_SEQUENTIAL]
00735 ** </ul>
00736 **
00737 ** The SQLITE_IOCAP_ATOMIC property means that all writes of
00738 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
00739 ** mean that writes of blocks that are nnn bytes in size and
00740 ** are aligned to an address which is an integer multiple of
00741 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
00742 ** that when data is appended to a file, the data is appended
00743 ** first then the size of the file is extended, never the other
00744 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
00745 ** information is written to disk in the same order as calls
00746 ** to xWrite().
00747 **
00748 ** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
00749 ** in the unread portions of the buffer with zeros.  A VFS that
00750 ** fails to zero-fill short reads might seem to work.  However,
00751 ** failure to zero-fill short reads will eventually lead to
00752 ** database corruption.
00753 */
00754 typedef struct sqlite3_io_methods sqlite3_io_methods;
00755 struct sqlite3_io_methods {
00756   int iVersion;
00757   int (*xClose)(sqlite3_file*);
00758   int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
00759   int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
00760   int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
00761   int (*xSync)(sqlite3_file*, int flags);
00762   int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
00763   int (*xLock)(sqlite3_file*, int);
00764   int (*xUnlock)(sqlite3_file*, int);
00765   int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
00766   int (*xFileControl)(sqlite3_file*, int op, void *pArg);
00767   int (*xSectorSize)(sqlite3_file*);
00768   int (*xDeviceCharacteristics)(sqlite3_file*);
00769   /* Methods above are valid for version 1 */
00770   int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
00771   int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
00772   void (*xShmBarrier)(sqlite3_file*);
00773   int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
00774   /* Methods above are valid for version 2 */
00775   int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
00776   int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
00777   /* Methods above are valid for version 3 */
00778   /* Additional methods may be added in future releases */
00779 };
00780 
00781 /*
00782 ** CAPI3REF: Standard File Control Opcodes
00783 **
00784 ** These integer constants are opcodes for the xFileControl method
00785 ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
00786 ** interface.
00787 **
00788 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
00789 ** opcode causes the xFileControl method to write the current state of
00790 ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
00791 ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
00792 ** into an integer that the pArg argument points to. This capability
00793 ** is used during testing and only needs to be supported when SQLITE_TEST
00794 ** is defined.
00795 ** <ul>
00796 ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
00797 ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
00798 ** layer a hint of how large the database file will grow to be during the
00799 ** current transaction.  This hint is not guaranteed to be accurate but it
00800 ** is often close.  The underlying VFS might choose to preallocate database
00801 ** file space based on this hint in order to help writes to the database
00802 ** file run faster.
00803 **
00804 ** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
00805 ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
00806 ** extends and truncates the database file in chunks of a size specified
00807 ** by the user. The fourth argument to [sqlite3_file_control()] should 
00808 ** point to an integer (type int) containing the new chunk-size to use
00809 ** for the nominated database. Allocating database file space in large
00810 ** chunks (say 1MB at a time), may reduce file-system fragmentation and
00811 ** improve performance on some systems.
00812 **
00813 ** <li>[[SQLITE_FCNTL_FILE_POINTER]]
00814 ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
00815 ** to the [sqlite3_file] object associated with a particular database
00816 ** connection.  See the [sqlite3_file_control()] documentation for
00817 ** additional information.
00818 **
00819 ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
00820 ** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by
00821 ** SQLite and sent to all VFSes in place of a call to the xSync method
00822 ** when the database connection has [PRAGMA synchronous] set to OFF.)^
00823 ** Some specialized VFSes need this signal in order to operate correctly
00824 ** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most 
00825 ** VFSes do not need this signal and should silently ignore this opcode.
00826 ** Applications should not call [sqlite3_file_control()] with this
00827 ** opcode as doing so may disrupt the operation of the specialized VFSes
00828 ** that do require it.  
00829 **
00830 ** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
00831 ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
00832 ** retry counts and intervals for certain disk I/O operations for the
00833 ** windows [VFS] in order to provide robustness in the presence of
00834 ** anti-virus programs.  By default, the windows VFS will retry file read,
00835 ** file write, and file delete operations up to 10 times, with a delay
00836 ** of 25 milliseconds before the first retry and with the delay increasing
00837 ** by an additional 25 milliseconds with each subsequent retry.  This
00838 ** opcode allows these two values (10 retries and 25 milliseconds of delay)
00839 ** to be adjusted.  The values are changed for all database connections
00840 ** within the same process.  The argument is a pointer to an array of two
00841 ** integers where the first integer i the new retry count and the second
00842 ** integer is the delay.  If either integer is negative, then the setting
00843 ** is not changed but instead the prior value of that setting is written
00844 ** into the array entry, allowing the current retry settings to be
00845 ** interrogated.  The zDbName parameter is ignored.
00846 **
00847 ** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
00848 ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
00849 ** persistent [WAL | Write Ahead Log] setting.  By default, the auxiliary
00850 ** write ahead log and shared memory files used for transaction control
00851 ** are automatically deleted when the latest connection to the database
00852 ** closes.  Setting persistent WAL mode causes those files to persist after
00853 ** close.  Persisting the files is useful when other processes that do not
00854 ** have write permission on the directory containing the database file want
00855 ** to read the database file, as the WAL and shared memory files must exist
00856 ** in order for the database to be readable.  The fourth parameter to
00857 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
00858 ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
00859 ** WAL mode.  If the integer is -1, then it is overwritten with the current
00860 ** WAL persistence setting.
00861 **
00862 ** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
00863 ** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
00864 ** persistent "powersafe-overwrite" or "PSOW" setting.  The PSOW setting
00865 ** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
00866 ** xDeviceCharacteristics methods. The fourth parameter to
00867 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
00868 ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
00869 ** mode.  If the integer is -1, then it is overwritten with the current
00870 ** zero-damage mode setting.
00871 **
00872 ** <li>[[SQLITE_FCNTL_OVERWRITE]]
00873 ** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
00874 ** a write transaction to indicate that, unless it is rolled back for some
00875 ** reason, the entire database file will be overwritten by the current 
00876 ** transaction. This is used by VACUUM operations.
00877 **
00878 ** <li>[[SQLITE_FCNTL_VFSNAME]]
00879 ** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
00880 ** all [VFSes] in the VFS stack.  The names are of all VFS shims and the
00881 ** final bottom-level VFS are written into memory obtained from 
00882 ** [sqlite3_malloc()] and the result is stored in the char* variable
00883 ** that the fourth parameter of [sqlite3_file_control()] points to.
00884 ** The caller is responsible for freeing the memory when done.  As with
00885 ** all file-control actions, there is no guarantee that this will actually
00886 ** do anything.  Callers should initialize the char* variable to a NULL
00887 ** pointer in case this file-control is not implemented.  This file-control
00888 ** is intended for diagnostic use only.
00889 **
00890 ** <li>[[SQLITE_FCNTL_PRAGMA]]
00891 ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA] 
00892 ** file control is sent to the open [sqlite3_file] object corresponding
00893 ** to the database file to which the pragma statement refers. ^The argument
00894 ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
00895 ** pointers to strings (char**) in which the second element of the array
00896 ** is the name of the pragma and the third element is the argument to the
00897 ** pragma or NULL if the pragma has no argument.  ^The handler for an
00898 ** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
00899 ** of the char** argument point to a string obtained from [sqlite3_mprintf()]
00900 ** or the equivalent and that string will become the result of the pragma or
00901 ** the error message if the pragma fails. ^If the
00902 ** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal 
00903 ** [PRAGMA] processing continues.  ^If the [SQLITE_FCNTL_PRAGMA]
00904 ** file control returns [SQLITE_OK], then the parser assumes that the
00905 ** VFS has handled the PRAGMA itself and the parser generates a no-op
00906 ** prepared statement.  ^If the [SQLITE_FCNTL_PRAGMA] file control returns
00907 ** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
00908 ** that the VFS encountered an error while handling the [PRAGMA] and the
00909 ** compilation of the PRAGMA fails with an error.  ^The [SQLITE_FCNTL_PRAGMA]
00910 ** file control occurs at the beginning of pragma statement analysis and so
00911 ** it is able to override built-in [PRAGMA] statements.
00912 **
00913 ** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
00914 ** ^The [SQLITE_FCNTL_BUSYHANDLER]
00915 ** file-control may be invoked by SQLite on the database file handle
00916 ** shortly after it is opened in order to provide a custom VFS with access
00917 ** to the connections busy-handler callback. The argument is of type (void **)
00918 ** - an array of two (void *) values. The first (void *) actually points
00919 ** to a function of type (int (*)(void *)). In order to invoke the connections
00920 ** busy-handler, this function should be invoked with the second (void *) in
00921 ** the array as the only argument. If it returns non-zero, then the operation
00922 ** should be retried. If it returns zero, the custom VFS should abandon the
00923 ** current operation.
00924 **
00925 ** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
00926 ** ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
00927 ** to have SQLite generate a
00928 ** temporary filename using the same algorithm that is followed to generate
00929 ** temporary filenames for TEMP tables and other internal uses.  The
00930 ** argument should be a char** which will be filled with the filename
00931 ** written into memory obtained from [sqlite3_malloc()].  The caller should
00932 ** invoke [sqlite3_free()] on the result to avoid a memory leak.
00933 **
00934 ** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
00935 ** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
00936 ** maximum number of bytes that will be used for memory-mapped I/O.
00937 ** The argument is a pointer to a value of type sqlite3_int64 that
00938 ** is an advisory maximum number of bytes in the file to memory map.  The
00939 ** pointer is overwritten with the old value.  The limit is not changed if
00940 ** the value originally pointed to is negative, and so the current limit 
00941 ** can be queried by passing in a pointer to a negative number.  This
00942 ** file-control is used internally to implement [PRAGMA mmap_size].
00943 **
00944 ** <li>[[SQLITE_FCNTL_TRACE]]
00945 ** The [SQLITE_FCNTL_TRACE] file control provides advisory information
00946 ** to the VFS about what the higher layers of the SQLite stack are doing.
00947 ** This file control is used by some VFS activity tracing [shims].
00948 ** The argument is a zero-terminated string.  Higher layers in the
00949 ** SQLite stack may generate instances of this file control if
00950 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
00951 **
00952 ** </ul>
00953 */
00954 #define SQLITE_FCNTL_LOCKSTATE               1
00955 #define SQLITE_GET_LOCKPROXYFILE             2
00956 #define SQLITE_SET_LOCKPROXYFILE             3
00957 #define SQLITE_LAST_ERRNO                    4
00958 #define SQLITE_FCNTL_SIZE_HINT               5
00959 #define SQLITE_FCNTL_CHUNK_SIZE              6
00960 #define SQLITE_FCNTL_FILE_POINTER            7
00961 #define SQLITE_FCNTL_SYNC_OMITTED            8
00962 #define SQLITE_FCNTL_WIN32_AV_RETRY          9
00963 #define SQLITE_FCNTL_PERSIST_WAL            10
00964 #define SQLITE_FCNTL_OVERWRITE              11
00965 #define SQLITE_FCNTL_VFSNAME                12
00966 #define SQLITE_FCNTL_POWERSAFE_OVERWRITE    13
00967 #define SQLITE_FCNTL_PRAGMA                 14
00968 #define SQLITE_FCNTL_BUSYHANDLER            15
00969 #define SQLITE_FCNTL_TEMPFILENAME           16
00970 #define SQLITE_FCNTL_MMAP_SIZE              18
00971 #define SQLITE_FCNTL_TRACE                  19
00972 
00973 /*
00974 ** CAPI3REF: Mutex Handle
00975 **
00976 ** The mutex module within SQLite defines [sqlite3_mutex] to be an
00977 ** abstract type for a mutex object.  The SQLite core never looks
00978 ** at the internal representation of an [sqlite3_mutex].  It only
00979 ** deals with pointers to the [sqlite3_mutex] object.
00980 **
00981 ** Mutexes are created using [sqlite3_mutex_alloc()].
00982 */
00983 typedef struct sqlite3_mutex sqlite3_mutex;
00984 
00985 /*
00986 ** CAPI3REF: OS Interface Object
00987 **
00988 ** An instance of the sqlite3_vfs object defines the interface between
00989 ** the SQLite core and the underlying operating system.  The "vfs"
00990 ** in the name of the object stands for "virtual file system".  See
00991 ** the [VFS | VFS documentation] for further information.
00992 **
00993 ** The value of the iVersion field is initially 1 but may be larger in
00994 ** future versions of SQLite.  Additional fields may be appended to this
00995 ** object when the iVersion value is increased.  Note that the structure
00996 ** of the sqlite3_vfs object changes in the transaction between
00997 ** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
00998 ** modified.
00999 **
01000 ** The szOsFile field is the size of the subclassed [sqlite3_file]
01001 ** structure used by this VFS.  mxPathname is the maximum length of
01002 ** a pathname in this VFS.
01003 **
01004 ** Registered sqlite3_vfs objects are kept on a linked list formed by
01005 ** the pNext pointer.  The [sqlite3_vfs_register()]
01006 ** and [sqlite3_vfs_unregister()] interfaces manage this list
01007 ** in a thread-safe way.  The [sqlite3_vfs_find()] interface
01008 ** searches the list.  Neither the application code nor the VFS
01009 ** implementation should use the pNext pointer.
01010 **
01011 ** The pNext field is the only field in the sqlite3_vfs
01012 ** structure that SQLite will ever modify.  SQLite will only access
01013 ** or modify this field while holding a particular static mutex.
01014 ** The application should never modify anything within the sqlite3_vfs
01015 ** object once the object has been registered.
01016 **
01017 ** The zName field holds the name of the VFS module.  The name must
01018 ** be unique across all VFS modules.
01019 **
01020 ** [[sqlite3_vfs.xOpen]]
01021 ** ^SQLite guarantees that the zFilename parameter to xOpen
01022 ** is either a NULL pointer or string obtained
01023 ** from xFullPathname() with an optional suffix added.
01024 ** ^If a suffix is added to the zFilename parameter, it will
01025 ** consist of a single "-" character followed by no more than
01026 ** 11 alphanumeric and/or "-" characters.
01027 ** ^SQLite further guarantees that
01028 ** the string will be valid and unchanged until xClose() is
01029 ** called. Because of the previous sentence,
01030 ** the [sqlite3_file] can safely store a pointer to the
01031 ** filename if it needs to remember the filename for some reason.
01032 ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
01033 ** must invent its own temporary name for the file.  ^Whenever the 
01034 ** xFilename parameter is NULL it will also be the case that the
01035 ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
01036 **
01037 ** The flags argument to xOpen() includes all bits set in
01038 ** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]
01039 ** or [sqlite3_open16()] is used, then flags includes at least
01040 ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. 
01041 ** If xOpen() opens a file read-only then it sets *pOutFlags to
01042 ** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.
01043 **
01044 ** ^(SQLite will also add one of the following flags to the xOpen()
01045 ** call, depending on the object being opened:
01046 **
01047 ** <ul>
01048 ** <li>  [SQLITE_OPEN_MAIN_DB]
01049 ** <li>  [SQLITE_OPEN_MAIN_JOURNAL]
01050 ** <li>  [SQLITE_OPEN_TEMP_DB]
01051 ** <li>  [SQLITE_OPEN_TEMP_JOURNAL]
01052 ** <li>  [SQLITE_OPEN_TRANSIENT_DB]
01053 ** <li>  [SQLITE_OPEN_SUBJOURNAL]
01054 ** <li>  [SQLITE_OPEN_MASTER_JOURNAL]
01055 ** <li>  [SQLITE_OPEN_WAL]
01056 ** </ul>)^
01057 **
01058 ** The file I/O implementation can use the object type flags to
01059 ** change the way it deals with files.  For example, an application
01060 ** that does not care about crash recovery or rollback might make
01061 ** the open of a journal file a no-op.  Writes to this journal would
01062 ** also be no-ops, and any attempt to read the journal would return
01063 ** SQLITE_IOERR.  Or the implementation might recognize that a database
01064 ** file will be doing page-aligned sector reads and writes in a random
01065 ** order and set up its I/O subsystem accordingly.
01066 **
01067 ** SQLite might also add one of the following flags to the xOpen method:
01068 **
01069 ** <ul>
01070 ** <li> [SQLITE_OPEN_DELETEONCLOSE]
01071 ** <li> [SQLITE_OPEN_EXCLUSIVE]
01072 ** </ul>
01073 **
01074 ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
01075 ** deleted when it is closed.  ^The [SQLITE_OPEN_DELETEONCLOSE]
01076 ** will be set for TEMP databases and their journals, transient
01077 ** databases, and subjournals.
01078 **
01079 ** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
01080 ** with the [SQLITE_OPEN_CREATE] flag, which are both directly
01081 ** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
01082 ** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the 
01083 ** SQLITE_OPEN_CREATE, is used to indicate that file should always
01084 ** be created, and that it is an error if it already exists.
01085 ** It is <i>not</i> used to indicate the file should be opened 
01086 ** for exclusive access.
01087 **
01088 ** ^At least szOsFile bytes of memory are allocated by SQLite
01089 ** to hold the  [sqlite3_file] structure passed as the third
01090 ** argument to xOpen.  The xOpen method does not have to
01091 ** allocate the structure; it should just fill it in.  Note that
01092 ** the xOpen method must set the sqlite3_file.pMethods to either
01093 ** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do
01094 ** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods
01095 ** element will be valid after xOpen returns regardless of the success
01096 ** or failure of the xOpen call.
01097 **
01098 ** [[sqlite3_vfs.xAccess]]
01099 ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
01100 ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
01101 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
01102 ** to test whether a file is at least readable.   The file can be a
01103 ** directory.
01104 **
01105 ** ^SQLite will always allocate at least mxPathname+1 bytes for the
01106 ** output buffer xFullPathname.  The exact size of the output buffer
01107 ** is also passed as a parameter to both  methods. If the output buffer
01108 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
01109 ** handled as a fatal error by SQLite, vfs implementations should endeavor
01110 ** to prevent this by setting mxPathname to a sufficiently large value.
01111 **
01112 ** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
01113 ** interfaces are not strictly a part of the filesystem, but they are
01114 ** included in the VFS structure for completeness.
01115 ** The xRandomness() function attempts to return nBytes bytes
01116 ** of good-quality randomness into zOut.  The return value is
01117 ** the actual number of bytes of randomness obtained.
01118 ** The xSleep() method causes the calling thread to sleep for at
01119 ** least the number of microseconds given.  ^The xCurrentTime()
01120 ** method returns a Julian Day Number for the current date and time as
01121 ** a floating point value.
01122 ** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
01123 ** Day Number multiplied by 86400000 (the number of milliseconds in 
01124 ** a 24-hour day).  
01125 ** ^SQLite will use the xCurrentTimeInt64() method to get the current
01126 ** date and time if that method is available (if iVersion is 2 or 
01127 ** greater and the function pointer is not NULL) and will fall back
01128 ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
01129 **
01130 ** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
01131 ** are not used by the SQLite core.  These optional interfaces are provided
01132 ** by some VFSes to facilitate testing of the VFS code. By overriding 
01133 ** system calls with functions under its control, a test program can
01134 ** simulate faults and error conditions that would otherwise be difficult
01135 ** or impossible to induce.  The set of system calls that can be overridden
01136 ** varies from one VFS to another, and from one version of the same VFS to the
01137 ** next.  Applications that use these interfaces must be prepared for any
01138 ** or all of these interfaces to be NULL or for their behavior to change
01139 ** from one release to the next.  Applications must not attempt to access
01140 ** any of these methods if the iVersion of the VFS is less than 3.
01141 */
01142 typedef struct sqlite3_vfs sqlite3_vfs;
01143 typedef void (*sqlite3_syscall_ptr)(void);
01144 struct sqlite3_vfs {
01145   int iVersion;            /* Structure version number (currently 3) */
01146   int szOsFile;            /* Size of subclassed sqlite3_file */
01147   int mxPathname;          /* Maximum file pathname length */
01148   sqlite3_vfs *pNext;      /* Next registered VFS */
01149   const char *zName;       /* Name of this virtual file system */
01150   void *pAppData;          /* Pointer to application-specific data */
01151   int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
01152                int flags, int *pOutFlags);
01153   int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
01154   int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
01155   int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
01156   void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
01157   void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
01158   void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
01159   void (*xDlClose)(sqlite3_vfs*, void*);
01160   int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
01161   int (*xSleep)(sqlite3_vfs*, int microseconds);
01162   int (*xCurrentTime)(sqlite3_vfs*, double*);
01163   int (*xGetLastError)(sqlite3_vfs*, int, char *);
01164   /*
01165   ** The methods above are in version 1 of the sqlite_vfs object
01166   ** definition.  Those that follow are added in version 2 or later
01167   */
01168   int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
01169   /*
01170   ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
01171   ** Those below are for version 3 and greater.
01172   */
01173   int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
01174   sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
01175   const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
01176   /*
01177   ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
01178   ** New fields may be appended in figure versions.  The iVersion
01179   ** value will increment whenever this happens. 
01180   */
01181 };
01182 
01183 /*
01184 ** CAPI3REF: Flags for the xAccess VFS method
01185 **
01186 ** These integer constants can be used as the third parameter to
01187 ** the xAccess method of an [sqlite3_vfs] object.  They determine
01188 ** what kind of permissions the xAccess method is looking for.
01189 ** With SQLITE_ACCESS_EXISTS, the xAccess method
01190 ** simply checks whether the file exists.
01191 ** With SQLITE_ACCESS_READWRITE, the xAccess method
01192 ** checks whether the named directory is both readable and writable
01193 ** (in other words, if files can be added, removed, and renamed within
01194 ** the directory).
01195 ** The SQLITE_ACCESS_READWRITE constant is currently used only by the
01196 ** [temp_store_directory pragma], though this could change in a future
01197 ** release of SQLite.
01198 ** With SQLITE_ACCESS_READ, the xAccess method
01199 ** checks whether the file is readable.  The SQLITE_ACCESS_READ constant is
01200 ** currently unused, though it might be used in a future release of
01201 ** SQLite.
01202 */
01203 #define SQLITE_ACCESS_EXISTS    0
01204 #define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */
01205 #define SQLITE_ACCESS_READ      2   /* Unused */
01206 
01207 /*
01208 ** CAPI3REF: Flags for the xShmLock VFS method
01209 **
01210 ** These integer constants define the various locking operations
01211 ** allowed by the xShmLock method of [sqlite3_io_methods].  The
01212 ** following are the only legal combinations of flags to the
01213 ** xShmLock method:
01214 **
01215 ** <ul>
01216 ** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
01217 ** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
01218 ** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
01219 ** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
01220 ** </ul>
01221 **
01222 ** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
01223 ** was given no the corresponding lock.  
01224 **
01225 ** The xShmLock method can transition between unlocked and SHARED or
01226 ** between unlocked and EXCLUSIVE.  It cannot transition between SHARED
01227 ** and EXCLUSIVE.
01228 */
01229 #define SQLITE_SHM_UNLOCK       1
01230 #define SQLITE_SHM_LOCK         2
01231 #define SQLITE_SHM_SHARED       4
01232 #define SQLITE_SHM_EXCLUSIVE    8
01233 
01234 /*
01235 ** CAPI3REF: Maximum xShmLock index
01236 **
01237 ** The xShmLock method on [sqlite3_io_methods] may use values
01238 ** between 0 and this upper bound as its "offset" argument.
01239 ** The SQLite core will never attempt to acquire or release a
01240 ** lock outside of this range
01241 */
01242 #define SQLITE_SHM_NLOCK        8
01243 
01244 
01245 /*
01246 ** CAPI3REF: Initialize The SQLite Library
01247 **
01248 ** ^The sqlite3_initialize() routine initializes the
01249 ** SQLite library.  ^The sqlite3_shutdown() routine
01250 ** deallocates any resources that were allocated by sqlite3_initialize().
01251 ** These routines are designed to aid in process initialization and
01252 ** shutdown on embedded systems.  Workstation applications using
01253 ** SQLite normally do not need to invoke either of these routines.
01254 **
01255 ** A call to sqlite3_initialize() is an "effective" call if it is
01256 ** the first time sqlite3_initialize() is invoked during the lifetime of
01257 ** the process, or if it is the first time sqlite3_initialize() is invoked
01258 ** following a call to sqlite3_shutdown().  ^(Only an effective call
01259 ** of sqlite3_initialize() does any initialization.  All other calls
01260 ** are harmless no-ops.)^
01261 **
01262 ** A call to sqlite3_shutdown() is an "effective" call if it is the first
01263 ** call to sqlite3_shutdown() since the last sqlite3_initialize().  ^(Only
01264 ** an effective call to sqlite3_shutdown() does any deinitialization.
01265 ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
01266 **
01267 ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
01268 ** is not.  The sqlite3_shutdown() interface must only be called from a
01269 ** single thread.  All open [database connections] must be closed and all
01270 ** other SQLite resources must be deallocated prior to invoking
01271 ** sqlite3_shutdown().
01272 **
01273 ** Among other things, ^sqlite3_initialize() will invoke
01274 ** sqlite3_os_init().  Similarly, ^sqlite3_shutdown()
01275 ** will invoke sqlite3_os_end().
01276 **
01277 ** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
01278 ** ^If for some reason, sqlite3_initialize() is unable to initialize
01279 ** the library (perhaps it is unable to allocate a needed resource such
01280 ** as a mutex) it returns an [error code] other than [SQLITE_OK].
01281 **
01282 ** ^The sqlite3_initialize() routine is called internally by many other
01283 ** SQLite interfaces so that an application usually does not need to
01284 ** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
01285 ** calls sqlite3_initialize() so the SQLite library will be automatically
01286 ** initialized when [sqlite3_open()] is called if it has not be initialized
01287 ** already.  ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
01288 ** compile-time option, then the automatic calls to sqlite3_initialize()
01289 ** are omitted and the application must call sqlite3_initialize() directly
01290 ** prior to using any other SQLite interface.  For maximum portability,
01291 ** it is recommended that applications always invoke sqlite3_initialize()
01292 ** directly prior to using any other SQLite interface.  Future releases
01293 ** of SQLite may require this.  In other words, the behavior exhibited
01294 ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
01295 ** default behavior in some future release of SQLite.
01296 **
01297 ** The sqlite3_os_init() routine does operating-system specific
01298 ** initialization of the SQLite library.  The sqlite3_os_end()
01299 ** routine undoes the effect of sqlite3_os_init().  Typical tasks
01300 ** performed by these routines include allocation or deallocation
01301 ** of static resources, initialization of global variables,
01302 ** setting up a default [sqlite3_vfs] module, or setting up
01303 ** a default configuration using [sqlite3_config()].
01304 **
01305 ** The application should never invoke either sqlite3_os_init()
01306 ** or sqlite3_os_end() directly.  The application should only invoke
01307 ** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
01308 ** interface is called automatically by sqlite3_initialize() and
01309 ** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
01310 ** implementations for sqlite3_os_init() and sqlite3_os_end()
01311 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
01312 ** When [custom builds | built for other platforms]
01313 ** (using the [SQLITE_OS_OTHER=1] compile-time
01314 ** option) the application must supply a suitable implementation for
01315 ** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
01316 ** implementation of sqlite3_os_init() or sqlite3_os_end()
01317 ** must return [SQLITE_OK] on success and some other [error code] upon
01318 ** failure.
01319 */
01320 SQLITE_API int sqlite3_initialize(void);
01321 SQLITE_API int sqlite3_shutdown(void);
01322 SQLITE_API int sqlite3_os_init(void);
01323 SQLITE_API int sqlite3_os_end(void);
01324 
01325 /*
01326 ** CAPI3REF: Configuring The SQLite Library
01327 **
01328 ** The sqlite3_config() interface is used to make global configuration
01329 ** changes to SQLite in order to tune SQLite to the specific needs of
01330 ** the application.  The default configuration is recommended for most
01331 ** applications and so this routine is usually not necessary.  It is
01332 ** provided to support rare applications with unusual needs.
01333 **
01334 ** The sqlite3_config() interface is not threadsafe.  The application
01335 ** must insure that no other SQLite interfaces are invoked by other
01336 ** threads while sqlite3_config() is running.  Furthermore, sqlite3_config()
01337 ** may only be invoked prior to library initialization using
01338 ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
01339 ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
01340 ** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
01341 ** Note, however, that ^sqlite3_config() can be called as part of the
01342 ** implementation of an application-defined [sqlite3_os_init()].
01343 **
01344 ** The first argument to sqlite3_config() is an integer
01345 ** [configuration option] that determines
01346 ** what property of SQLite is to be configured.  Subsequent arguments
01347 ** vary depending on the [configuration option]
01348 ** in the first argument.
01349 **
01350 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
01351 ** ^If the option is unknown or SQLite is unable to set the option
01352 ** then this routine returns a non-zero [error code].
01353 */
01354 SQLITE_API int sqlite3_config(int, ...);
01355 
01356 /*
01357 ** CAPI3REF: Configure database connections
01358 **
01359 ** The sqlite3_db_config() interface is used to make configuration
01360 ** changes to a [database connection].  The interface is similar to
01361 ** [sqlite3_config()] except that the changes apply to a single
01362 ** [database connection] (specified in the first argument).
01363 **
01364 ** The second argument to sqlite3_db_config(D,V,...)  is the
01365 ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code 
01366 ** that indicates what aspect of the [database connection] is being configured.
01367 ** Subsequent arguments vary depending on the configuration verb.
01368 **
01369 ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
01370 ** the call is considered successful.
01371 */
01372 SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
01373 
01374 /*
01375 ** CAPI3REF: Memory Allocation Routines
01376 **
01377 ** An instance of this object defines the interface between SQLite
01378 ** and low-level memory allocation routines.
01379 **
01380 ** This object is used in only one place in the SQLite interface.
01381 ** A pointer to an instance of this object is the argument to
01382 ** [sqlite3_config()] when the configuration option is
01383 ** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].  
01384 ** By creating an instance of this object
01385 ** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
01386 ** during configuration, an application can specify an alternative
01387 ** memory allocation subsystem for SQLite to use for all of its
01388 ** dynamic memory needs.
01389 **
01390 ** Note that SQLite comes with several [built-in memory allocators]
01391 ** that are perfectly adequate for the overwhelming majority of applications
01392 ** and that this object is only useful to a tiny minority of applications
01393 ** with specialized memory allocation requirements.  This object is
01394 ** also used during testing of SQLite in order to specify an alternative
01395 ** memory allocator that simulates memory out-of-memory conditions in
01396 ** order to verify that SQLite recovers gracefully from such
01397 ** conditions.
01398 **
01399 ** The xMalloc, xRealloc, and xFree methods must work like the
01400 ** malloc(), realloc() and free() functions from the standard C library.
01401 ** ^SQLite guarantees that the second argument to
01402 ** xRealloc is always a value returned by a prior call to xRoundup.
01403 **
01404 ** xSize should return the allocated size of a memory allocation
01405 ** previously obtained from xMalloc or xRealloc.  The allocated size
01406 ** is always at least as big as the requested size but may be larger.
01407 **
01408 ** The xRoundup method returns what would be the allocated size of
01409 ** a memory allocation given a particular requested size.  Most memory
01410 ** allocators round up memory allocations at least to the next multiple
01411 ** of 8.  Some allocators round up to a larger multiple or to a power of 2.
01412 ** Every memory allocation request coming in through [sqlite3_malloc()]
01413 ** or [sqlite3_realloc()] first calls xRoundup.  If xRoundup returns 0, 
01414 ** that causes the corresponding memory allocation to fail.
01415 **
01416 ** The xInit method initializes the memory allocator.  For example,
01417 ** it might allocate any require mutexes or initialize internal data
01418 ** structures.  The xShutdown method is invoked (indirectly) by
01419 ** [sqlite3_shutdown()] and should deallocate any resources acquired
01420 ** by xInit.  The pAppData pointer is used as the only parameter to
01421 ** xInit and xShutdown.
01422 **
01423 ** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
01424 ** the xInit method, so the xInit method need not be threadsafe.  The
01425 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
01426 ** not need to be threadsafe either.  For all other methods, SQLite
01427 ** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
01428 ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
01429 ** it is by default) and so the methods are automatically serialized.
01430 ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
01431 ** methods must be threadsafe or else make their own arrangements for
01432 ** serialization.
01433 **
01434 ** SQLite will never invoke xInit() more than once without an intervening
01435 ** call to xShutdown().
01436 */
01437 typedef struct sqlite3_mem_methods sqlite3_mem_methods;
01438 struct sqlite3_mem_methods {
01439   void *(*xMalloc)(int);         /* Memory allocation function */
01440   void (*xFree)(void*);          /* Free a prior allocation */
01441   void *(*xRealloc)(void*,int);  /* Resize an allocation */
01442   int (*xSize)(void*);           /* Return the size of an allocation */
01443   int (*xRoundup)(int);          /* Round up request size to allocation size */
01444   int (*xInit)(void*);           /* Initialize the memory allocator */
01445   void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
01446   void *pAppData;                /* Argument to xInit() and xShutdown() */
01447 };
01448 
01449 /*
01450 ** CAPI3REF: Configuration Options
01451 ** KEYWORDS: {configuration option}
01452 **
01453 ** These constants are the available integer configuration options that
01454 ** can be passed as the first argument to the [sqlite3_config()] interface.
01455 **
01456 ** New configuration options may be added in future releases of SQLite.
01457 ** Existing configuration options might be discontinued.  Applications
01458 ** should check the return code from [sqlite3_config()] to make sure that
01459 ** the call worked.  The [sqlite3_config()] interface will return a
01460 ** non-zero [error code] if a discontinued or unsupported configuration option
01461 ** is invoked.
01462 **
01463 ** <dl>
01464 ** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
01465 ** <dd>There are no arguments to this option.  ^This option sets the
01466 ** [threading mode] to Single-thread.  In other words, it disables
01467 ** all mutexing and puts SQLite into a mode where it can only be used
01468 ** by a single thread.   ^If SQLite is compiled with
01469 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
01470 ** it is not possible to change the [threading mode] from its default
01471 ** value of Single-thread and so [sqlite3_config()] will return 
01472 ** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
01473 ** configuration option.</dd>
01474 **
01475 ** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
01476 ** <dd>There are no arguments to this option.  ^This option sets the
01477 ** [threading mode] to Multi-thread.  In other words, it disables
01478 ** mutexing on [database connection] and [prepared statement] objects.
01479 ** The application is responsible for serializing access to
01480 ** [database connections] and [prepared statements].  But other mutexes
01481 ** are enabled so that SQLite will be safe to use in a multi-threaded
01482 ** environment as long as no two threads attempt to use the same
01483 ** [database connection] at the same time.  ^If SQLite is compiled with
01484 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
01485 ** it is not possible to set the Multi-thread [threading mode] and
01486 ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
01487 ** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
01488 **
01489 ** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
01490 ** <dd>There are no arguments to this option.  ^This option sets the
01491 ** [threading mode] to Serialized. In other words, this option enables
01492 ** all mutexes including the recursive
01493 ** mutexes on [database connection] and [prepared statement] objects.
01494 ** In this mode (which is the default when SQLite is compiled with
01495 ** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
01496 ** to [database connections] and [prepared statements] so that the
01497 ** application is free to use the same [database connection] or the
01498 ** same [prepared statement] in different threads at the same time.
01499 ** ^If SQLite is compiled with
01500 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
01501 ** it is not possible to set the Serialized [threading mode] and
01502 ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
01503 ** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
01504 **
01505 ** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
01506 ** <dd> ^(This option takes a single argument which is a pointer to an
01507 ** instance of the [sqlite3_mem_methods] structure.  The argument specifies
01508 ** alternative low-level memory allocation routines to be used in place of
01509 ** the memory allocation routines built into SQLite.)^ ^SQLite makes
01510 ** its own private copy of the content of the [sqlite3_mem_methods] structure
01511 ** before the [sqlite3_config()] call returns.</dd>
01512 **
01513 ** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
01514 ** <dd> ^(This option takes a single argument which is a pointer to an
01515 ** instance of the [sqlite3_mem_methods] structure.  The [sqlite3_mem_methods]
01516 ** structure is filled with the currently defined memory allocation routines.)^
01517 ** This option can be used to overload the default memory allocation
01518 ** routines with a wrapper that simulations memory allocation failure or
01519 ** tracks memory usage, for example. </dd>
01520 **
01521 ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
01522 ** <dd> ^This option takes single argument of type int, interpreted as a 
01523 ** boolean, which enables or disables the collection of memory allocation 
01524 ** statistics. ^(When memory allocation statistics are disabled, the 
01525 ** following SQLite interfaces become non-operational:
01526 **   <ul>
01527 **   <li> [sqlite3_memory_used()]
01528 **   <li> [sqlite3_memory_highwater()]
01529 **   <li> [sqlite3_soft_heap_limit64()]
01530 **   <li> [sqlite3_status()]
01531 **   </ul>)^
01532 ** ^Memory allocation statistics are enabled by default unless SQLite is
01533 ** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
01534 ** allocation statistics are disabled by default.
01535 ** </dd>
01536 **
01537 ** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
01538 ** <dd> ^This option specifies a static memory buffer that SQLite can use for
01539 ** scratch memory.  There are three arguments:  A pointer an 8-byte
01540 ** aligned memory buffer from which the scratch allocations will be
01541 ** drawn, the size of each scratch allocation (sz),
01542 ** and the maximum number of scratch allocations (N).  The sz
01543 ** argument must be a multiple of 16.
01544 ** The first argument must be a pointer to an 8-byte aligned buffer
01545 ** of at least sz*N bytes of memory.
01546 ** ^SQLite will use no more than two scratch buffers per thread.  So
01547 ** N should be set to twice the expected maximum number of threads.
01548 ** ^SQLite will never require a scratch buffer that is more than 6
01549 ** times the database page size. ^If SQLite needs needs additional
01550 ** scratch memory beyond what is provided by this configuration option, then 
01551 ** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
01552 **
01553 ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
01554 ** <dd> ^This option specifies a static memory buffer that SQLite can use for
01555 ** the database page cache with the default page cache implementation.  
01556 ** This configuration should not be used if an application-define page
01557 ** cache implementation is loaded using the SQLITE_CONFIG_PCACHE2 option.
01558 ** There are three arguments to this option: A pointer to 8-byte aligned
01559 ** memory, the size of each page buffer (sz), and the number of pages (N).
01560 ** The sz argument should be the size of the largest database page
01561 ** (a power of two between 512 and 32768) plus a little extra for each
01562 ** page header.  ^The page header size is 20 to 40 bytes depending on
01563 ** the host architecture.  ^It is harmless, apart from the wasted memory,
01564 ** to make sz a little too large.  The first
01565 ** argument should point to an allocation of at least sz*N bytes of memory.
01566 ** ^SQLite will use the memory provided by the first argument to satisfy its
01567 ** memory needs for the first N pages that it adds to cache.  ^If additional
01568 ** page cache memory is needed beyond what is provided by this option, then
01569 ** SQLite goes to [sqlite3_malloc()] for the additional storage space.
01570 ** The pointer in the first argument must
01571 ** be aligned to an 8-byte boundary or subsequent behavior of SQLite
01572 ** will be undefined.</dd>
01573 **
01574 ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
01575 ** <dd> ^This option specifies a static memory buffer that SQLite will use
01576 ** for all of its dynamic memory allocation needs beyond those provided
01577 ** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
01578 ** There are three arguments: An 8-byte aligned pointer to the memory,
01579 ** the number of bytes in the memory buffer, and the minimum allocation size.
01580 ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
01581 ** to using its default memory allocator (the system malloc() implementation),
01582 ** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  ^If the
01583 ** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
01584 ** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
01585 ** allocator is engaged to handle all of SQLites memory allocation needs.
01586 ** The first pointer (the memory pointer) must be aligned to an 8-byte
01587 ** boundary or subsequent behavior of SQLite will be undefined.
01588 ** The minimum allocation size is capped at 2**12. Reasonable values
01589 ** for the minimum allocation size are 2**5 through 2**8.</dd>
01590 **
01591 ** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
01592 ** <dd> ^(This option takes a single argument which is a pointer to an
01593 ** instance of the [sqlite3_mutex_methods] structure.  The argument specifies
01594 ** alternative low-level mutex routines to be used in place
01595 ** the mutex routines built into SQLite.)^  ^SQLite makes a copy of the
01596 ** content of the [sqlite3_mutex_methods] structure before the call to
01597 ** [sqlite3_config()] returns. ^If SQLite is compiled with
01598 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
01599 ** the entire mutexing subsystem is omitted from the build and hence calls to
01600 ** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
01601 ** return [SQLITE_ERROR].</dd>
01602 **
01603 ** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
01604 ** <dd> ^(This option takes a single argument which is a pointer to an
01605 ** instance of the [sqlite3_mutex_methods] structure.  The
01606 ** [sqlite3_mutex_methods]
01607 ** structure is filled with the currently defined mutex routines.)^
01608 ** This option can be used to overload the default mutex allocation
01609 ** routines with a wrapper used to track mutex usage for performance
01610 ** profiling or testing, for example.   ^If SQLite is compiled with
01611 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
01612 ** the entire mutexing subsystem is omitted from the build and hence calls to
01613 ** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
01614 ** return [SQLITE_ERROR].</dd>
01615 **
01616 ** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
01617 ** <dd> ^(This option takes two arguments that determine the default
01618 ** memory allocation for the lookaside memory allocator on each
01619 ** [database connection].  The first argument is the
01620 ** size of each lookaside buffer slot and the second is the number of
01621 ** slots allocated to each database connection.)^  ^(This option sets the
01622 ** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
01623 ** verb to [sqlite3_db_config()] can be used to change the lookaside
01624 ** configuration on individual connections.)^ </dd>
01625 **
01626 ** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
01627 ** <dd> ^(This option takes a single argument which is a pointer to
01628 ** an [sqlite3_pcache_methods2] object.  This object specifies the interface
01629 ** to a custom page cache implementation.)^  ^SQLite makes a copy of the
01630 ** object and uses it for page cache memory allocations.</dd>
01631 **
01632 ** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
01633 ** <dd> ^(This option takes a single argument which is a pointer to an
01634 ** [sqlite3_pcache_methods2] object.  SQLite copies of the current
01635 ** page cache implementation into that object.)^ </dd>
01636 **
01637 ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
01638 ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
01639 ** global [error log].
01640 ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
01641 ** function with a call signature of void(*)(void*,int,const char*), 
01642 ** and a pointer to void. ^If the function pointer is not NULL, it is
01643 ** invoked by [sqlite3_log()] to process each logging event.  ^If the
01644 ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
01645 ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
01646 ** passed through as the first parameter to the application-defined logger
01647 ** function whenever that function is invoked.  ^The second parameter to
01648 ** the logger function is a copy of the first parameter to the corresponding
01649 ** [sqlite3_log()] call and is intended to be a [result code] or an
01650 ** [extended result code].  ^The third parameter passed to the logger is
01651 ** log message after formatting via [sqlite3_snprintf()].
01652 ** The SQLite logging interface is not reentrant; the logger function
01653 ** supplied by the application must not invoke any SQLite interface.
01654 ** In a multi-threaded application, the application-defined logger
01655 ** function must be threadsafe. </dd>
01656 **
01657 ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
01658 ** <dd>^(This option takes a single argument of type int. If non-zero, then
01659 ** URI handling is globally enabled. If the parameter is zero, then URI handling
01660 ** is globally disabled.)^ ^If URI handling is globally enabled, all filenames
01661 ** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or
01662 ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
01663 ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
01664 ** connection is opened. ^If it is globally disabled, filenames are
01665 ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
01666 ** database connection is opened. ^(By default, URI handling is globally
01667 ** disabled. The default value may be changed by compiling with the
01668 ** [SQLITE_USE_URI] symbol defined.)^
01669 **
01670 ** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
01671 ** <dd>^This option takes a single integer argument which is interpreted as
01672 ** a boolean in order to enable or disable the use of covering indices for
01673 ** full table scans in the query optimizer.  ^The default setting is determined
01674 ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
01675 ** if that compile-time option is omitted.
01676 ** The ability to disable the use of covering indices for full table scans
01677 ** is because some incorrectly coded legacy applications might malfunction
01678 ** when the optimization is enabled.  Providing the ability to
01679 ** disable the optimization allows the older, buggy application code to work
01680 ** without change even with newer versions of SQLite.
01681 **
01682 ** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
01683 ** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
01684 ** <dd> These options are obsolete and should not be used by new code.
01685 ** They are retained for backwards compatibility but are now no-ops.
01686 ** </dd>
01687 **
01688 ** [[SQLITE_CONFIG_SQLLOG]]
01689 ** <dt>SQLITE_CONFIG_SQLLOG
01690 ** <dd>This option is only available if sqlite is compiled with the
01691 ** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
01692 ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
01693 ** The second should be of type (void*). The callback is invoked by the library
01694 ** in three separate circumstances, identified by the value passed as the
01695 ** fourth parameter. If the fourth parameter is 0, then the database connection
01696 ** passed as the second argument has just been opened. The third argument
01697 ** points to a buffer containing the name of the main database file. If the
01698 ** fourth parameter is 1, then the SQL statement that the third parameter
01699 ** points to has just been executed. Or, if the fourth parameter is 2, then
01700 ** the connection being passed as the second parameter is being closed. The
01701 ** third parameter is passed NULL In this case.  An example of using this
01702 ** configuration option can be seen in the "test_sqllog.c" source file in
01703 ** the canonical SQLite source tree.</dd>
01704 **
01705 ** [[SQLITE_CONFIG_MMAP_SIZE]]
01706 ** <dt>SQLITE_CONFIG_MMAP_SIZE
01707 ** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
01708 ** that are the default mmap size limit (the default setting for
01709 ** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
01710 ** ^The default setting can be overridden by each database connection using
01711 ** either the [PRAGMA mmap_size] command, or by using the
01712 ** [SQLITE_FCNTL_MMAP_SIZE] file control.  ^(The maximum allowed mmap size
01713 ** cannot be changed at run-time.  Nor may the maximum allowed mmap size
01714 ** exceed the compile-time maximum mmap size set by the
01715 ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
01716 ** ^If either argument to this option is negative, then that argument is
01717 ** changed to its compile-time default.
01718 **
01719 ** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
01720 ** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
01721 ** <dd>^This option is only available if SQLite is compiled for Windows
01722 ** with the [SQLITE_WIN32_MALLOC] pre-processor macro defined.
01723 ** SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
01724 ** that specifies the maximum size of the created heap.
01725 ** </dl>
01726 */
01727 #define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
01728 #define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
01729 #define SQLITE_CONFIG_SERIALIZED    3  /* nil */
01730 #define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
01731 #define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
01732 #define SQLITE_CONFIG_SCRATCH       6  /* void*, int sz, int N */
01733 #define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
01734 #define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
01735 #define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
01736 #define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
01737 #define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
01738 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 
01739 #define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
01740 #define SQLITE_CONFIG_PCACHE       14  /* no-op */
01741 #define SQLITE_CONFIG_GETPCACHE    15  /* no-op */
01742 #define SQLITE_CONFIG_LOG          16  /* xFunc, void* */
01743 #define SQLITE_CONFIG_URI          17  /* int */
01744 #define SQLITE_CONFIG_PCACHE2      18  /* sqlite3_pcache_methods2* */
01745 #define SQLITE_CONFIG_GETPCACHE2   19  /* sqlite3_pcache_methods2* */
01746 #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20  /* int */
01747 #define SQLITE_CONFIG_SQLLOG       21  /* xSqllog, void* */
01748 #define SQLITE_CONFIG_MMAP_SIZE    22  /* sqlite3_int64, sqlite3_int64 */
01749 #define SQLITE_CONFIG_WIN32_HEAPSIZE      23  /* int nByte */
01750 
01751 /*
01752 ** CAPI3REF: Database Connection Configuration Options
01753 **
01754 ** These constants are the available integer configuration options that
01755 ** can be passed as the second argument to the [sqlite3_db_config()] interface.
01756 **
01757 ** New configuration options may be added in future releases of SQLite.
01758 ** Existing configuration options might be discontinued.  Applications
01759 ** should check the return code from [sqlite3_db_config()] to make sure that
01760 ** the call worked.  ^The [sqlite3_db_config()] interface will return a
01761 ** non-zero [error code] if a discontinued or unsupported configuration option
01762 ** is invoked.
01763 **
01764 ** <dl>
01765 ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
01766 ** <dd> ^This option takes three additional arguments that determine the 
01767 ** [lookaside memory allocator] configuration for the [database connection].
01768 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
01769 ** pointer to a memory buffer to use for lookaside memory.
01770 ** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
01771 ** may be NULL in which case SQLite will allocate the
01772 ** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
01773 ** size of each lookaside buffer slot.  ^The third argument is the number of
01774 ** slots.  The size of the buffer in the first argument must be greater than
01775 ** or equal to the product of the second and third arguments.  The buffer
01776 ** must be aligned to an 8-byte boundary.  ^If the second argument to
01777 ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
01778 ** rounded down to the next smaller multiple of 8.  ^(The lookaside memory
01779 ** configuration for a database connection can only be changed when that
01780 ** connection is not currently using lookaside memory, or in other words
01781 ** when the "current value" returned by
01782 ** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
01783 ** Any attempt to change the lookaside memory configuration when lookaside
01784 ** memory is in use leaves the configuration unchanged and returns 
01785 ** [SQLITE_BUSY].)^</dd>
01786 **
01787 ** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
01788 ** <dd> ^This option is used to enable or disable the enforcement of
01789 ** [foreign key constraints].  There should be two additional arguments.
01790 ** The first argument is an integer which is 0 to disable FK enforcement,
01791 ** positive to enable FK enforcement or negative to leave FK enforcement
01792 ** unchanged.  The second parameter is a pointer to an integer into which
01793 ** is written 0 or 1 to indicate whether FK enforcement is off or on
01794 ** following this call.  The second parameter may be a NULL pointer, in
01795 ** which case the FK enforcement setting is not reported back. </dd>
01796 **
01797 ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
01798 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
01799 ** There should be two additional arguments.
01800 ** The first argument is an integer which is 0 to disable triggers,
01801 ** positive to enable triggers or negative to leave the setting unchanged.
01802 ** The second parameter is a pointer to an integer into which
01803 ** is written 0 or 1 to indicate whether triggers are disabled or enabled
01804 ** following this call.  The second parameter may be a NULL pointer, in
01805 ** which case the trigger setting is not reported back. </dd>
01806 **
01807 ** </dl>
01808 */
01809 #define SQLITE_DBCONFIG_LOOKASIDE       1001  /* void* int int */
01810 #define SQLITE_DBCONFIG_ENABLE_FKEY     1002  /* int int* */
01811 #define SQLITE_DBCONFIG_ENABLE_TRIGGER  1003  /* int int* */
01812 
01813 
01814 /*
01815 ** CAPI3REF: Enable Or Disable Extended Result Codes
01816 **
01817 ** ^The sqlite3_extended_result_codes() routine enables or disables the
01818 ** [extended result codes] feature of SQLite. ^The extended result
01819 ** codes are disabled by default for historical compatibility.
01820 */
01821 SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
01822 
01823 /*
01824 ** CAPI3REF: Last Insert Rowid
01825 **
01826 ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
01827 ** has a unique 64-bit signed
01828 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
01829 ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
01830 ** names are not also used by explicitly declared columns. ^If
01831 ** the table has a column of type [INTEGER PRIMARY KEY] then that column
01832 ** is another alias for the rowid.
01833 **
01834 ** ^The sqlite3_last_insert_rowid(D) interface returns the [rowid] of the 
01835 ** most recent successful [INSERT] into a rowid table or [virtual table]
01836 ** on database connection D.
01837 ** ^Inserts into [WITHOUT ROWID] tables are not recorded.
01838 ** ^If no successful [INSERT]s into rowid tables
01839 ** have ever occurred on the database connection D, 
01840 ** then sqlite3_last_insert_rowid(D) returns zero.
01841 **
01842 ** ^(If an [INSERT] occurs within a trigger or within a [virtual table]
01843 ** method, then this routine will return the [rowid] of the inserted
01844 ** row as long as the trigger or virtual table method is running.
01845 ** But once the trigger or virtual table method ends, the value returned 
01846 ** by this routine reverts to what it was before the trigger or virtual
01847 ** table method began.)^
01848 **
01849 ** ^An [INSERT] that fails due to a constraint violation is not a
01850 ** successful [INSERT] and does not change the value returned by this
01851 ** routine.  ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
01852 ** and INSERT OR ABORT make no changes to the return value of this
01853 ** routine when their insertion fails.  ^(When INSERT OR REPLACE
01854 ** encounters a constraint violation, it does not fail.  The
01855 ** INSERT continues to completion after deleting rows that caused
01856 ** the constraint problem so INSERT OR REPLACE will always change
01857 ** the return value of this interface.)^
01858 **
01859 ** ^For the purposes of this routine, an [INSERT] is considered to
01860 ** be successful even if it is subsequently rolled back.
01861 **
01862 ** This function is accessible to SQL statements via the
01863 ** [last_insert_rowid() SQL function].
01864 **
01865 ** If a separate thread performs a new [INSERT] on the same
01866 ** database connection while the [sqlite3_last_insert_rowid()]
01867 ** function is running and thus changes the last insert [rowid],
01868 ** then the value returned by [sqlite3_last_insert_rowid()] is
01869 ** unpredictable and might not equal either the old or the new
01870 ** last insert [rowid].
01871 */
01872 SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
01873 
01874 /*
01875 ** CAPI3REF: Count The Number Of Rows Modified
01876 **
01877 ** ^This function returns the number of database rows that were changed
01878 ** or inserted or deleted by the most recently completed SQL statement
01879 ** on the [database connection] specified by the first parameter.
01880 ** ^(Only changes that are directly specified by the [INSERT], [UPDATE],
01881 ** or [DELETE] statement are counted.  Auxiliary changes caused by
01882 ** triggers or [foreign key actions] are not counted.)^ Use the
01883 ** [sqlite3_total_changes()] function to find the total number of changes
01884 ** including changes caused by triggers and foreign key actions.
01885 **
01886 ** ^Changes to a view that are simulated by an [INSTEAD OF trigger]
01887 ** are not counted.  Only real table changes are counted.
01888 **
01889 ** ^(A "row change" is a change to a single row of a single table
01890 ** caused by an INSERT, DELETE, or UPDATE statement.  Rows that
01891 ** are changed as side effects of [REPLACE] constraint resolution,
01892 ** rollback, ABORT processing, [DROP TABLE], or by any other
01893 ** mechanisms do not count as direct row changes.)^
01894 **
01895 ** A "trigger context" is a scope of execution that begins and
01896 ** ends with the script of a [CREATE TRIGGER | trigger]. 
01897 ** Most SQL statements are
01898 ** evaluated outside of any trigger.  This is the "top level"
01899 ** trigger context.  If a trigger fires from the top level, a
01900 ** new trigger context is entered for the duration of that one
01901 ** trigger.  Subtriggers create subcontexts for their duration.
01902 **
01903 ** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
01904 ** not create a new trigger context.
01905 **
01906 ** ^This function returns the number of direct row changes in the
01907 ** most recent INSERT, UPDATE, or DELETE statement within the same
01908 ** trigger context.
01909 **
01910 ** ^Thus, when called from the top level, this function returns the
01911 ** number of changes in the most recent INSERT, UPDATE, or DELETE
01912 ** that also occurred at the top level.  ^(Within the body of a trigger,
01913 ** the sqlite3_changes() interface can be called to find the number of
01914 ** changes in the most recently completed INSERT, UPDATE, or DELETE
01915 ** statement within the body of the same trigger.
01916 ** However, the number returned does not include changes
01917 ** caused by subtriggers since those have their own context.)^
01918 **
01919 ** See also the [sqlite3_total_changes()] interface, the
01920 ** [count_changes pragma], and the [changes() SQL function].
01921 **
01922 ** If a separate thread makes changes on the same database connection
01923 ** while [sqlite3_changes()] is running then the value returned
01924 ** is unpredictable and not meaningful.
01925 */
01926 SQLITE_API int sqlite3_changes(sqlite3*);
01927 
01928 /*
01929 ** CAPI3REF: Total Number Of Rows Modified
01930 **
01931 ** ^This function returns the number of row changes caused by [INSERT],
01932 ** [UPDATE] or [DELETE] statements since the [database connection] was opened.
01933 ** ^(The count returned by sqlite3_total_changes() includes all changes
01934 ** from all [CREATE TRIGGER | trigger] contexts and changes made by
01935 ** [foreign key actions]. However,
01936 ** the count does not include changes used to implement [REPLACE] constraints,
01937 ** do rollbacks or ABORT processing, or [DROP TABLE] processing.  The
01938 ** count does not include rows of views that fire an [INSTEAD OF trigger],
01939 ** though if the INSTEAD OF trigger makes changes of its own, those changes 
01940 ** are counted.)^
01941 ** ^The sqlite3_total_changes() function counts the changes as soon as
01942 ** the statement that makes them is completed (when the statement handle
01943 ** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
01944 **
01945 ** See also the [sqlite3_changes()] interface, the
01946 ** [count_changes pragma], and the [total_changes() SQL function].
01947 **
01948 ** If a separate thread makes changes on the same database connection
01949 ** while [sqlite3_total_changes()] is running then the value
01950 ** returned is unpredictable and not meaningful.
01951 */
01952 SQLITE_API int sqlite3_total_changes(sqlite3*);
01953 
01954 /*
01955 ** CAPI3REF: Interrupt A Long-Running Query
01956 **
01957 ** ^This function causes any pending database operation to abort and
01958 ** return at its earliest opportunity. This routine is typically
01959 ** called in response to a user action such as pressing "Cancel"
01960 ** or Ctrl-C where the user wants a long query operation to halt
01961 ** immediately.
01962 **
01963 ** ^It is safe to call this routine from a thread different from the
01964 ** thread that is currently running the database operation.  But it
01965 ** is not safe to call this routine with a [database connection] that
01966 ** is closed or might close before sqlite3_interrupt() returns.
01967 **
01968 ** ^If an SQL operation is very nearly finished at the time when
01969 ** sqlite3_interrupt() is called, then it might not have an opportunity
01970 ** to be interrupted and might continue to completion.
01971 **
01972 ** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
01973 ** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
01974 ** that is inside an explicit transaction, then the entire transaction
01975 ** will be rolled back automatically.
01976 **
01977 ** ^The sqlite3_interrupt(D) call is in effect until all currently running
01978 ** SQL statements on [database connection] D complete.  ^Any new SQL statements
01979 ** that are started after the sqlite3_interrupt() call and before the 
01980 ** running statements reaches zero are interrupted as if they had been
01981 ** running prior to the sqlite3_interrupt() call.  ^New SQL statements
01982 ** that are started after the running statement count reaches zero are
01983 ** not effected by the sqlite3_interrupt().
01984 ** ^A call to sqlite3_interrupt(D) that occurs when there are no running
01985 ** SQL statements is a no-op and has no effect on SQL statements
01986 ** that are started after the sqlite3_interrupt() call returns.
01987 **
01988 ** If the database connection closes while [sqlite3_interrupt()]
01989 ** is running then bad things will likely happen.
01990 */
01991 SQLITE_API void sqlite3_interrupt(sqlite3*);
01992 
01993 /*
01994 ** CAPI3REF: Determine If An SQL Statement Is Complete
01995 **
01996 ** These routines are useful during command-line input to determine if the
01997 ** currently entered text seems to form a complete SQL statement or
01998 ** if additional input is needed before sending the text into
01999 ** SQLite for parsing.  ^These routines return 1 if the input string
02000 ** appears to be a complete SQL statement.  ^A statement is judged to be
02001 ** complete if it ends with a semicolon token and is not a prefix of a
02002 ** well-formed CREATE TRIGGER statement.  ^Semicolons that are embedded within
02003 ** string literals or quoted identifier names or comments are not
02004 ** independent tokens (they are part of the token in which they are
02005 ** embedded) and thus do not count as a statement terminator.  ^Whitespace
02006 ** and comments that follow the final semicolon are ignored.
02007 **
02008 ** ^These routines return 0 if the statement is incomplete.  ^If a
02009 ** memory allocation fails, then SQLITE_NOMEM is returned.
02010 **
02011 ** ^These routines do not parse the SQL statements thus
02012 ** will not detect syntactically incorrect SQL.
02013 **
02014 ** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior 
02015 ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
02016 ** automatically by sqlite3_complete16().  If that initialization fails,
02017 ** then the return value from sqlite3_complete16() will be non-zero
02018 ** regardless of whether or not the input SQL is complete.)^
02019 **
02020 ** The input to [sqlite3_complete()] must be a zero-terminated
02021 ** UTF-8 string.
02022 **
02023 ** The input to [sqlite3_complete16()] must be a zero-terminated
02024 ** UTF-16 string in native byte order.
02025 */
02026 SQLITE_API int sqlite3_complete(const char *sql);
02027 SQLITE_API int sqlite3_complete16(const void *sql);
02028 
02029 /*
02030 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
02031 **
02032 ** ^This routine sets a callback function that might be invoked whenever
02033 ** an attempt is made to open a database table that another thread
02034 ** or process has locked.
02035 **
02036 ** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
02037 ** is returned immediately upon encountering the lock.  ^If the busy callback
02038 ** is not NULL, then the callback might be invoked with two arguments.
02039 **
02040 ** ^The first argument to the busy handler is a copy of the void* pointer which
02041 ** is the third argument to sqlite3_busy_handler().  ^The second argument to
02042 ** the busy handler callback is the number of times that the busy handler has
02043 ** been invoked for this locking event.  ^If the
02044 ** busy callback returns 0, then no additional attempts are made to
02045 ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
02046 ** ^If the callback returns non-zero, then another attempt
02047 ** is made to open the database for reading and the cycle repeats.
02048 **
02049 ** The presence of a busy handler does not guarantee that it will be invoked
02050 ** when there is lock contention. ^If SQLite determines that invoking the busy
02051 ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
02052 ** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
02053 ** Consider a scenario where one process is holding a read lock that
02054 ** it is trying to promote to a reserved lock and
02055 ** a second process is holding a reserved lock that it is trying
02056 ** to promote to an exclusive lock.  The first process cannot proceed
02057 ** because it is blocked by the second and the second process cannot
02058 ** proceed because it is blocked by the first.  If both processes
02059 ** invoke the busy handlers, neither will make any progress.  Therefore,
02060 ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
02061 ** will induce the first process to release its read lock and allow
02062 ** the second process to proceed.
02063 **
02064 ** ^The default busy callback is NULL.
02065 **
02066 ** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
02067 ** when SQLite is in the middle of a large transaction where all the
02068 ** changes will not fit into the in-memory cache.  SQLite will
02069 ** already hold a RESERVED lock on the database file, but it needs
02070 ** to promote this lock to EXCLUSIVE so that it can spill cache
02071 ** pages into the database file without harm to concurrent
02072 ** readers.  ^If it is unable to promote the lock, then the in-memory
02073 ** cache will be left in an inconsistent state and so the error
02074 ** code is promoted from the relatively benign [SQLITE_BUSY] to
02075 ** the more severe [SQLITE_IOERR_BLOCKED].  ^This error code promotion
02076 ** forces an automatic rollback of the changes.  See the
02077 ** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
02078 ** CorruptionFollowingBusyError</a> wiki page for a discussion of why
02079 ** this is important.
02080 **
02081 ** ^(There can only be a single busy handler defined for each
02082 ** [database connection].  Setting a new busy handler clears any
02083 ** previously set handler.)^  ^Note that calling [sqlite3_busy_timeout()]
02084 ** will also set or clear the busy handler.
02085 **
02086 ** The busy callback should not take any actions which modify the
02087 ** database connection that invoked the busy handler.  Any such actions
02088 ** result in undefined behavior.
02089 ** 
02090 ** A busy handler must not close the database connection
02091 ** or [prepared statement] that invoked the busy handler.
02092 */
02093 SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
02094 
02095 /*
02096 ** CAPI3REF: Set A Busy Timeout
02097 **
02098 ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
02099 ** for a specified amount of time when a table is locked.  ^The handler
02100 ** will sleep multiple times until at least "ms" milliseconds of sleeping
02101 ** have accumulated.  ^After at least "ms" milliseconds of sleeping,
02102 ** the handler returns 0 which causes [sqlite3_step()] to return
02103 ** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
02104 **
02105 ** ^Calling this routine with an argument less than or equal to zero
02106 ** turns off all busy handlers.
02107 **
02108 ** ^(There can only be a single busy handler for a particular
02109 ** [database connection] any any given moment.  If another busy handler
02110 ** was defined  (using [sqlite3_busy_handler()]) prior to calling
02111 ** this routine, that other busy handler is cleared.)^
02112 */
02113 SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
02114 
02115 /*
02116 ** CAPI3REF: Convenience Routines For Running Queries
02117 **
02118 ** This is a legacy interface that is preserved for backwards compatibility.
02119 ** Use of this interface is not recommended.
02120 **
02121 ** Definition: A <b>result table</b> is memory data structure created by the
02122 ** [sqlite3_get_table()] interface.  A result table records the
02123 ** complete query results from one or more queries.
02124 **
02125 ** The table conceptually has a number of rows and columns.  But
02126 ** these numbers are not part of the result table itself.  These
02127 ** numbers are obtained separately.  Let N be the number of rows
02128 ** and M be the number of columns.
02129 **
02130 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
02131 ** There are (N+1)*M elements in the array.  The first M pointers point
02132 ** to zero-terminated strings that  contain the names of the columns.
02133 ** The remaining entries all point to query results.  NULL values result
02134 ** in NULL pointers.  All other values are in their UTF-8 zero-terminated
02135 ** string representation as returned by [sqlite3_column_text()].
02136 **
02137 ** A result table might consist of one or more memory allocations.
02138 ** It is not safe to pass a result table directly to [sqlite3_free()].
02139 ** A result table should be deallocated using [sqlite3_free_table()].
02140 **
02141 ** ^(As an example of the result table format, suppose a query result
02142 ** is as follows:
02143 **
02144 ** <blockquote><pre>
02145 **        Name        | Age
02146 **        -----------------------
02147 **        Alice       | 43
02148 **        Bob         | 28
02149 **        Cindy       | 21
02150 ** </pre></blockquote>
02151 **
02152 ** There are two column (M==2) and three rows (N==3).  Thus the
02153 ** result table has 8 entries.  Suppose the result table is stored
02154 ** in an array names azResult.  Then azResult holds this content:
02155 **
02156 ** <blockquote><pre>
02157 **        azResult&#91;0] = "Name";
02158 **        azResult&#91;1] = "Age";
02159 **        azResult&#91;2] = "Alice";
02160 **        azResult&#91;3] = "43";
02161 **        azResult&#91;4] = "Bob";
02162 **        azResult&#91;5] = "28";
02163 **        azResult&#91;6] = "Cindy";
02164 **        azResult&#91;7] = "21";
02165 ** </pre></blockquote>)^
02166 **
02167 ** ^The sqlite3_get_table() function evaluates one or more
02168 ** semicolon-separated SQL statements in the zero-terminated UTF-8
02169 ** string of its 2nd parameter and returns a result table to the
02170 ** pointer given in its 3rd parameter.
02171 **
02172 ** After the application has finished with the result from sqlite3_get_table(),
02173 ** it must pass the result table pointer to sqlite3_free_table() in order to
02174 ** release the memory that was malloced.  Because of the way the
02175 ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
02176 ** function must not try to call [sqlite3_free()] directly.  Only
02177 ** [sqlite3_free_table()] is able to release the memory properly and safely.
02178 **
02179 ** The sqlite3_get_table() interface is implemented as a wrapper around
02180 ** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
02181 ** to any internal data structures of SQLite.  It uses only the public
02182 ** interface defined here.  As a consequence, errors that occur in the
02183 ** wrapper layer outside of the internal [sqlite3_exec()] call are not
02184 ** reflected in subsequent calls to [sqlite3_errcode()] or
02185 ** [sqlite3_errmsg()].
02186 */
02187 SQLITE_API int sqlite3_get_table(
02188   sqlite3 *db,          /* An open database */
02189   const char *zSql,     /* SQL to be evaluated */
02190   char ***pazResult,    /* Results of the query */
02191   int *pnRow,           /* Number of result rows written here */
02192   int *pnColumn,        /* Number of result columns written here */
02193   char **pzErrmsg       /* Error msg written here */
02194 );
02195 SQLITE_API void sqlite3_free_table(char **result);
02196 
02197 /*
02198 ** CAPI3REF: Formatted String Printing Functions
02199 **
02200 ** These routines are work-alikes of the "printf()" family of functions
02201 ** from the standard C library.
02202 **
02203 ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
02204 ** results into memory obtained from [sqlite3_malloc()].
02205 ** The strings returned by these two routines should be
02206 ** released by [sqlite3_free()].  ^Both routines return a
02207 ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
02208 ** memory to hold the resulting string.
02209 **
02210 ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
02211 ** the standard C library.  The result is written into the
02212 ** buffer supplied as the second parameter whose size is given by
02213 ** the first parameter. Note that the order of the
02214 ** first two parameters is reversed from snprintf().)^  This is an
02215 ** historical accident that cannot be fixed without breaking
02216 ** backwards compatibility.  ^(Note also that sqlite3_snprintf()
02217 ** returns a pointer to its buffer instead of the number of
02218 ** characters actually written into the buffer.)^  We admit that
02219 ** the number of characters written would be a more useful return
02220 ** value but we cannot change the implementation of sqlite3_snprintf()
02221 ** now without breaking compatibility.
02222 **
02223 ** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
02224 ** guarantees that the buffer is always zero-terminated.  ^The first
02225 ** parameter "n" is the total size of the buffer, including space for
02226 ** the zero terminator.  So the longest string that can be completely
02227 ** written will be n-1 characters.
02228 **
02229 ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
02230 **
02231 ** These routines all implement some additional formatting
02232 ** options that are useful for constructing SQL statements.
02233 ** All of the usual printf() formatting options apply.  In addition, there
02234 ** is are "%q", "%Q", and "%z" options.
02235 **
02236 ** ^(The %q option works like %s in that it substitutes a nul-terminated
02237 ** string from the argument list.  But %q also doubles every '\'' character.
02238 ** %q is designed for use inside a string literal.)^  By doubling each '\''
02239 ** character it escapes that character and allows it to be inserted into
02240 ** the string.
02241 **
02242 ** For example, assume the string variable zText contains text as follows:
02243 **
02244 ** <blockquote><pre>
02245 **  char *zText = "It's a happy day!";
02246 ** </pre></blockquote>
02247 **
02248 ** One can use this text in an SQL statement as follows:
02249 **
02250 ** <blockquote><pre>
02251 **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
02252 **  sqlite3_exec(db, zSQL, 0, 0, 0);
02253 **  sqlite3_free(zSQL);
02254 ** </pre></blockquote>
02255 **
02256 ** Because the %q format string is used, the '\'' character in zText
02257 ** is escaped and the SQL generated is as follows:
02258 **
02259 ** <blockquote><pre>
02260 **  INSERT INTO table1 VALUES('It''s a happy day!')
02261 ** </pre></blockquote>
02262 **
02263 ** This is correct.  Had we used %s instead of %q, the generated SQL
02264 ** would have looked like this:
02265 **
02266 ** <blockquote><pre>
02267 **  INSERT INTO table1 VALUES('It's a happy day!');
02268 ** </pre></blockquote>
02269 **
02270 ** This second example is an SQL syntax error.  As a general rule you should
02271 ** always use %q instead of %s when inserting text into a string literal.
02272 **
02273 ** ^(The %Q option works like %q except it also adds single quotes around
02274 ** the outside of the total string.  Additionally, if the parameter in the
02275 ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
02276 ** single quotes).)^  So, for example, one could say:
02277 **
02278 ** <blockquote><pre>
02279 **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
02280 **  sqlite3_exec(db, zSQL, 0, 0, 0);
02281 **  sqlite3_free(zSQL);
02282 ** </pre></blockquote>
02283 **
02284 ** The code above will render a correct SQL statement in the zSQL
02285 ** variable even if the zText variable is a NULL pointer.
02286 **
02287 ** ^(The "%z" formatting option works like "%s" but with the
02288 ** addition that after the string has been read and copied into
02289 ** the result, [sqlite3_free()] is called on the input string.)^
02290 */
02291 SQLITE_API char *sqlite3_mprintf(const char*,...);
02292 SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
02293 SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
02294 SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
02295 
02296 /*
02297 ** CAPI3REF: Memory Allocation Subsystem
02298 **
02299 ** The SQLite core uses these three routines for all of its own
02300 ** internal memory allocation needs. "Core" in the previous sentence
02301 ** does not include operating-system specific VFS implementation.  The
02302 ** Windows VFS uses native malloc() and free() for some operations.
02303 **
02304 ** ^The sqlite3_malloc() routine returns a pointer to a block
02305 ** of memory at least N bytes in length, where N is the parameter.
02306 ** ^If sqlite3_malloc() is unable to obtain sufficient free
02307 ** memory, it returns a NULL pointer.  ^If the parameter N to
02308 ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
02309 ** a NULL pointer.
02310 **
02311 ** ^Calling sqlite3_free() with a pointer previously returned
02312 ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
02313 ** that it might be reused.  ^The sqlite3_free() routine is
02314 ** a no-op if is called with a NULL pointer.  Passing a NULL pointer
02315 ** to sqlite3_free() is harmless.  After being freed, memory
02316 ** should neither be read nor written.  Even reading previously freed
02317 ** memory might result in a segmentation fault or other severe error.
02318 ** Memory corruption, a segmentation fault, or other severe error
02319 ** might result if sqlite3_free() is called with a non-NULL pointer that
02320 ** was not obtained from sqlite3_malloc() or sqlite3_realloc().
02321 **
02322 ** ^(The sqlite3_realloc() interface attempts to resize a
02323 ** prior memory allocation to be at least N bytes, where N is the
02324 ** second parameter.  The memory allocation to be resized is the first
02325 ** parameter.)^ ^ If the first parameter to sqlite3_realloc()
02326 ** is a NULL pointer then its behavior is identical to calling
02327 ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
02328 ** ^If the second parameter to sqlite3_realloc() is zero or
02329 ** negative then the behavior is exactly the same as calling
02330 ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
02331 ** ^sqlite3_realloc() returns a pointer to a memory allocation
02332 ** of at least N bytes in size or NULL if sufficient memory is unavailable.
02333 ** ^If M is the size of the prior allocation, then min(N,M) bytes
02334 ** of the prior allocation are copied into the beginning of buffer returned
02335 ** by sqlite3_realloc() and the prior allocation is freed.
02336 ** ^If sqlite3_realloc() returns NULL, then the prior allocation
02337 ** is not freed.
02338 **
02339 ** ^The memory returned by sqlite3_malloc() and sqlite3_realloc()
02340 ** is always aligned to at least an 8 byte boundary, or to a
02341 ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
02342 ** option is used.
02343 **
02344 ** In SQLite version 3.5.0 and 3.5.1, it was possible to define
02345 ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
02346 ** implementation of these routines to be omitted.  That capability
02347 ** is no longer provided.  Only built-in memory allocators can be used.
02348 **
02349 ** Prior to SQLite version 3.7.10, the Windows OS interface layer called
02350 ** the system malloc() and free() directly when converting
02351 ** filenames between the UTF-8 encoding used by SQLite
02352 ** and whatever filename encoding is used by the particular Windows
02353 ** installation.  Memory allocation errors were detected, but
02354 ** they were reported back as [SQLITE_CANTOPEN] or
02355 ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
02356 **
02357 ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
02358 ** must be either NULL or else pointers obtained from a prior
02359 ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
02360 ** not yet been released.
02361 **
02362 ** The application must not read or write any part of
02363 ** a block of memory after it has been released using
02364 ** [sqlite3_free()] or [sqlite3_realloc()].
02365 */
02366 SQLITE_API void *sqlite3_malloc(int);
02367 SQLITE_API void *sqlite3_realloc(void*, int);
02368 SQLITE_API void sqlite3_free(void*);
02369 
02370 /*
02371 ** CAPI3REF: Memory Allocator Statistics
02372 **
02373 ** SQLite provides these two interfaces for reporting on the status
02374 ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
02375 ** routines, which form the built-in memory allocation subsystem.
02376 **
02377 ** ^The [sqlite3_memory_used()] routine returns the number of bytes
02378 ** of memory currently outstanding (malloced but not freed).
02379 ** ^The [sqlite3_memory_highwater()] routine returns the maximum
02380 ** value of [sqlite3_memory_used()] since the high-water mark
02381 ** was last reset.  ^The values returned by [sqlite3_memory_used()] and
02382 ** [sqlite3_memory_highwater()] include any overhead
02383 ** added by SQLite in its implementation of [sqlite3_malloc()],
02384 ** but not overhead added by the any underlying system library
02385 ** routines that [sqlite3_malloc()] may call.
02386 **
02387 ** ^The memory high-water mark is reset to the current value of
02388 ** [sqlite3_memory_used()] if and only if the parameter to
02389 ** [sqlite3_memory_highwater()] is true.  ^The value returned
02390 ** by [sqlite3_memory_highwater(1)] is the high-water mark
02391 ** prior to the reset.
02392 */
02393 SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
02394 SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
02395 
02396 /*
02397 ** CAPI3REF: Pseudo-Random Number Generator
02398 **
02399 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
02400 ** select random [ROWID | ROWIDs] when inserting new records into a table that
02401 ** already uses the largest possible [ROWID].  The PRNG is also used for
02402 ** the build-in random() and randomblob() SQL functions.  This interface allows
02403 ** applications to access the same PRNG for other purposes.
02404 **
02405 ** ^A call to this routine stores N bytes of randomness into buffer P.
02406 **
02407 ** ^The first time this routine is invoked (either internally or by
02408 ** the application) the PRNG is seeded using randomness obtained
02409 ** from the xRandomness method of the default [sqlite3_vfs] object.
02410 ** ^On all subsequent invocations, the pseudo-randomness is generated
02411 ** internally and without recourse to the [sqlite3_vfs] xRandomness
02412 ** method.
02413 */
02414 SQLITE_API void sqlite3_randomness(int N, void *P);
02415 
02416 /*
02417 ** CAPI3REF: Compile-Time Authorization Callbacks
02418 **
02419 ** ^This routine registers an authorizer callback with a particular
02420 ** [database connection], supplied in the first argument.
02421 ** ^The authorizer callback is invoked as SQL statements are being compiled
02422 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
02423 ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  ^At various
02424 ** points during the compilation process, as logic is being created
02425 ** to perform various actions, the authorizer callback is invoked to
02426 ** see if those actions are allowed.  ^The authorizer callback should
02427 ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
02428 ** specific action but allow the SQL statement to continue to be
02429 ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
02430 ** rejected with an error.  ^If the authorizer callback returns
02431 ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
02432 ** then the [sqlite3_prepare_v2()] or equivalent call that triggered
02433 ** the authorizer will fail with an error message.
02434 **
02435 ** When the callback returns [SQLITE_OK], that means the operation
02436 ** requested is ok.  ^When the callback returns [SQLITE_DENY], the
02437 ** [sqlite3_prepare_v2()] or equivalent call that triggered the
02438 ** authorizer will fail with an error message explaining that
02439 ** access is denied. 
02440 **
02441 ** ^The first parameter to the authorizer callback is a copy of the third
02442 ** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
02443 ** to the callback is an integer [SQLITE_COPY | action code] that specifies
02444 ** the particular action to be authorized. ^The third through sixth parameters
02445 ** to the callback are zero-terminated strings that contain additional
02446 ** details about the action to be authorized.
02447 **
02448 ** ^If the action code is [SQLITE_READ]
02449 ** and the callback returns [SQLITE_IGNORE] then the
02450 ** [prepared statement] statement is constructed to substitute
02451 ** a NULL value in place of the table column that would have
02452 ** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
02453 ** return can be used to deny an untrusted user access to individual
02454 ** columns of a table.
02455 ** ^If the action code is [SQLITE_DELETE] and the callback returns
02456 ** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
02457 ** [truncate optimization] is disabled and all rows are deleted individually.
02458 **
02459 ** An authorizer is used when [sqlite3_prepare | preparing]
02460 ** SQL statements from an untrusted source, to ensure that the SQL statements
02461 ** do not try to access data they are not allowed to see, or that they do not
02462 ** try to execute malicious statements that damage the database.  For
02463 ** example, an application may allow a user to enter arbitrary
02464 ** SQL queries for evaluation by a database.  But the application does
02465 ** not want the user to be able to make arbitrary changes to the
02466 ** database.  An authorizer could then be put in place while the
02467 ** user-entered SQL is being [sqlite3_prepare | prepared] that
02468 ** disallows everything except [SELECT] statements.
02469 **
02470 ** Applications that need to process SQL from untrusted sources
02471 ** might also consider lowering resource limits using [sqlite3_limit()]
02472 ** and limiting database size using the [max_page_count] [PRAGMA]
02473 ** in addition to using an authorizer.
02474 **
02475 ** ^(Only a single authorizer can be in place on a database connection
02476 ** at a time.  Each call to sqlite3_set_authorizer overrides the
02477 ** previous call.)^  ^Disable the authorizer by installing a NULL callback.
02478 ** The authorizer is disabled by default.
02479 **
02480 ** The authorizer callback must not do anything that will modify
02481 ** the database connection that invoked the authorizer callback.
02482 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
02483 ** database connections for the meaning of "modify" in this paragraph.
02484 **
02485 ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
02486 ** statement might be re-prepared during [sqlite3_step()] due to a 
02487 ** schema change.  Hence, the application should ensure that the
02488 ** correct authorizer callback remains in place during the [sqlite3_step()].
02489 **
02490 ** ^Note that the authorizer callback is invoked only during
02491 ** [sqlite3_prepare()] or its variants.  Authorization is not
02492 ** performed during statement evaluation in [sqlite3_step()], unless
02493 ** as stated in the previous paragraph, sqlite3_step() invokes
02494 ** sqlite3_prepare_v2() to reprepare a statement after a schema change.
02495 */
02496 SQLITE_API int sqlite3_set_authorizer(
02497   sqlite3*,
02498   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
02499   void *pUserData
02500 );
02501 
02502 /*
02503 ** CAPI3REF: Authorizer Return Codes
02504 **
02505 ** The [sqlite3_set_authorizer | authorizer callback function] must
02506 ** return either [SQLITE_OK] or one of these two constants in order
02507 ** to signal SQLite whether or not the action is permitted.  See the
02508 ** [sqlite3_set_authorizer | authorizer documentation] for additional
02509 ** information.
02510 **
02511 ** Note that SQLITE_IGNORE is also used as a [SQLITE_ROLLBACK | return code]
02512 ** from the [sqlite3_vtab_on_conflict()] interface.
02513 */
02514 #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
02515 #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
02516 
02517 /*
02518 ** CAPI3REF: Authorizer Action Codes
02519 **
02520 ** The [sqlite3_set_authorizer()] interface registers a callback function
02521 ** that is invoked to authorize certain SQL statement actions.  The
02522 ** second parameter to the callback is an integer code that specifies
02523 ** what action is being authorized.  These are the integer action codes that
02524 ** the authorizer callback may be passed.
02525 **
02526 ** These action code values signify what kind of operation is to be
02527 ** authorized.  The 3rd and 4th parameters to the authorization
02528 ** callback function will be parameters or NULL depending on which of these
02529 ** codes is used as the second parameter.  ^(The 5th parameter to the
02530 ** authorizer callback is the name of the database ("main", "temp",
02531 ** etc.) if applicable.)^  ^The 6th parameter to the authorizer callback
02532 ** is the name of the inner-most trigger or view that is responsible for
02533 ** the access attempt or NULL if this access attempt is directly from
02534 ** top-level SQL code.
02535 */
02536 /******************************************* 3rd ************ 4th ***********/
02537 #define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
02538 #define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
02539 #define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
02540 #define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
02541 #define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
02542 #define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
02543 #define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
02544 #define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
02545 #define SQLITE_DELETE                9   /* Table Name      NULL            */
02546 #define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
02547 #define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
02548 #define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
02549 #define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
02550 #define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
02551 #define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
02552 #define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
02553 #define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
02554 #define SQLITE_INSERT               18   /* Table Name      NULL            */
02555 #define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
02556 #define SQLITE_READ                 20   /* Table Name      Column Name     */
02557 #define SQLITE_SELECT               21   /* NULL            NULL            */
02558 #define SQLITE_TRANSACTION          22   /* Operation       NULL            */
02559 #define SQLITE_UPDATE               23   /* Table Name      Column Name     */
02560 #define SQLITE_ATTACH               24   /* Filename        NULL            */
02561 #define SQLITE_DETACH               25   /* Database Name   NULL            */
02562 #define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
02563 #define SQLITE_REINDEX              27   /* Index Name      NULL            */
02564 #define SQLITE_ANALYZE              28   /* Table Name      NULL            */
02565 #define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
02566 #define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
02567 #define SQLITE_FUNCTION             31   /* NULL            Function Name   */
02568 #define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
02569 #define SQLITE_COPY                  0   /* No longer used */
02570 
02571 /*
02572 ** CAPI3REF: Tracing And Profiling Functions
02573 **
02574 ** These routines register callback functions that can be used for
02575 ** tracing and profiling the execution of SQL statements.
02576 **
02577 ** ^The callback function registered by sqlite3_trace() is invoked at
02578 ** various times when an SQL statement is being run by [sqlite3_step()].
02579 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
02580 ** SQL statement text as the statement first begins executing.
02581 ** ^(Additional sqlite3_trace() callbacks might occur
02582 ** as each triggered subprogram is entered.  The callbacks for triggers
02583 ** contain a UTF-8 SQL comment that identifies the trigger.)^
02584 **
02585 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
02586 ** the length of [bound parameter] expansion in the output of sqlite3_trace().
02587 **
02588 ** ^The callback function registered by sqlite3_profile() is invoked
02589 ** as each SQL statement finishes.  ^The profile callback contains
02590 ** the original statement text and an estimate of wall-clock time
02591 ** of how long that statement took to run.  ^The profile callback
02592 ** time is in units of nanoseconds, however the current implementation
02593 ** is only capable of millisecond resolution so the six least significant
02594 ** digits in the time are meaningless.  Future versions of SQLite
02595 ** might provide greater resolution on the profiler callback.  The
02596 ** sqlite3_profile() function is considered experimental and is
02597 ** subject to change in future versions of SQLite.
02598 */
02599 SQLITE_API void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
02600 SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
02601    void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
02602 
02603 /*
02604 ** CAPI3REF: Query Progress Callbacks
02605 **
02606 ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
02607 ** function X to be invoked periodically during long running calls to
02608 ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
02609 ** database connection D.  An example use for this
02610 ** interface is to keep a GUI updated during a large query.
02611 **
02612 ** ^The parameter P is passed through as the only parameter to the 
02613 ** callback function X.  ^The parameter N is the approximate number of 
02614 ** [virtual machine instructions] that are evaluated between successive
02615 ** invocations of the callback X.  ^If N is less than one then the progress
02616 ** handler is disabled.
02617 **
02618 ** ^Only a single progress handler may be defined at one time per
02619 ** [database connection]; setting a new progress handler cancels the
02620 ** old one.  ^Setting parameter X to NULL disables the progress handler.
02621 ** ^The progress handler is also disabled by setting N to a value less
02622 ** than 1.
02623 **
02624 ** ^If the progress callback returns non-zero, the operation is
02625 ** interrupted.  This feature can be used to implement a
02626 ** "Cancel" button on a GUI progress dialog box.
02627 **
02628 ** The progress handler callback must not do anything that will modify
02629 ** the database connection that invoked the progress handler.
02630 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
02631 ** database connections for the meaning of "modify" in this paragraph.
02632 **
02633 */
02634 SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
02635 
02636 /*
02637 ** CAPI3REF: Opening A New Database Connection
02638 **
02639 ** ^These routines open an SQLite database file as specified by the 
02640 ** filename argument. ^The filename argument is interpreted as UTF-8 for
02641 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
02642 ** order for sqlite3_open16(). ^(A [database connection] handle is usually
02643 ** returned in *ppDb, even if an error occurs.  The only exception is that
02644 ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
02645 ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
02646 ** object.)^ ^(If the database is opened (and/or created) successfully, then
02647 ** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.)^ ^The
02648 ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
02649 ** an English language description of the error following a failure of any
02650 ** of the sqlite3_open() routines.
02651 **
02652 ** ^The default encoding for the database will be UTF-8 if
02653 ** sqlite3_open() or sqlite3_open_v2() is called and
02654 ** UTF-16 in the native byte order if sqlite3_open16() is used.
02655 **
02656 ** Whether or not an error occurs when it is opened, resources
02657 ** associated with the [database connection] handle should be released by
02658 ** passing it to [sqlite3_close()] when it is no longer required.
02659 **
02660 ** The sqlite3_open_v2() interface works like sqlite3_open()
02661 ** except that it accepts two additional parameters for additional control
02662 ** over the new database connection.  ^(The flags parameter to
02663 ** sqlite3_open_v2() can take one of
02664 ** the following three values, optionally combined with the 
02665 ** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
02666 ** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^
02667 **
02668 ** <dl>
02669 ** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
02670 ** <dd>The database is opened in read-only mode.  If the database does not
02671 ** already exist, an error is returned.</dd>)^
02672 **
02673 ** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
02674 ** <dd>The database is opened for reading and writing if possible, or reading
02675 ** only if the file is write protected by the operating system.  In either
02676 ** case the database must already exist, otherwise an error is returned.</dd>)^
02677 **
02678 ** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
02679 ** <dd>The database is opened for reading and writing, and is created if
02680 ** it does not already exist. This is the behavior that is always used for
02681 ** sqlite3_open() and sqlite3_open16().</dd>)^
02682 ** </dl>
02683 **
02684 ** If the 3rd parameter to sqlite3_open_v2() is not one of the
02685 ** combinations shown above optionally combined with other
02686 ** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
02687 ** then the behavior is undefined.
02688 **
02689 ** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
02690 ** opens in the multi-thread [threading mode] as long as the single-thread
02691 ** mode has not been set at compile-time or start-time.  ^If the
02692 ** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
02693 ** in the serialized [threading mode] unless single-thread was
02694 ** previously selected at compile-time or start-time.
02695 ** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
02696 ** eligible to use [shared cache mode], regardless of whether or not shared
02697 ** cache is enabled using [sqlite3_enable_shared_cache()].  ^The
02698 ** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
02699 ** participate in [shared cache mode] even if it is enabled.
02700 **
02701 ** ^The fourth parameter to sqlite3_open_v2() is the name of the
02702 ** [sqlite3_vfs] object that defines the operating system interface that
02703 ** the new database connection should use.  ^If the fourth parameter is
02704 ** a NULL pointer then the default [sqlite3_vfs] object is used.
02705 **
02706 ** ^If the filename is ":memory:", then a private, temporary in-memory database
02707 ** is created for the connection.  ^This in-memory database will vanish when
02708 ** the database connection is closed.  Future versions of SQLite might
02709 ** make use of additional special filenames that begin with the ":" character.
02710 ** It is recommended that when a database filename actually does begin with
02711 ** a ":" character you should prefix the filename with a pathname such as
02712 ** "./" to avoid ambiguity.
02713 **
02714 ** ^If the filename is an empty string, then a private, temporary
02715 ** on-disk database will be created.  ^This private database will be
02716 ** automatically deleted as soon as the database connection is closed.
02717 **
02718 ** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
02719 **
02720 ** ^If [URI filename] interpretation is enabled, and the filename argument
02721 ** begins with "file:", then the filename is interpreted as a URI. ^URI
02722 ** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
02723 ** set in the fourth argument to sqlite3_open_v2(), or if it has
02724 ** been enabled globally using the [SQLITE_CONFIG_URI] option with the
02725 ** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
02726 ** As of SQLite version 3.7.7, URI filename interpretation is turned off
02727 ** by default, but future releases of SQLite might enable URI filename
02728 ** interpretation by default.  See "[URI filenames]" for additional
02729 ** information.
02730 **
02731 ** URI filenames are parsed according to RFC 3986. ^If the URI contains an
02732 ** authority, then it must be either an empty string or the string 
02733 ** "localhost". ^If the authority is not an empty string or "localhost", an 
02734 ** error is returned to the caller. ^The fragment component of a URI, if 
02735 ** present, is ignored.
02736 **
02737 ** ^SQLite uses the path component of the URI as the name of the disk file
02738 ** which contains the database. ^If the path begins with a '/' character, 
02739 ** then it is interpreted as an absolute path. ^If the path does not begin 
02740 ** with a '/' (meaning that the authority section is omitted from the URI)
02741 ** then the path is interpreted as a relative path. 
02742 ** ^On windows, the first component of an absolute path 
02743 ** is a drive specification (e.g. "C:").
02744 **
02745 ** [[core URI query parameters]]
02746 ** The query component of a URI may contain parameters that are interpreted
02747 ** either by SQLite itself, or by a [VFS | custom VFS implementation].
02748 ** SQLite interprets the following three query parameters:
02749 **
02750 ** <ul>
02751 **   <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
02752 **     a VFS object that provides the operating system interface that should
02753 **     be used to access the database file on disk. ^If this option is set to
02754 **     an empty string the default VFS object is used. ^Specifying an unknown
02755 **     VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
02756 **     present, then the VFS specified by the option takes precedence over
02757 **     the value passed as the fourth parameter to sqlite3_open_v2().
02758 **
02759 **   <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
02760 **     "rwc", or "memory". Attempting to set it to any other value is
02761 **     an error)^. 
02762 **     ^If "ro" is specified, then the database is opened for read-only 
02763 **     access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the 
02764 **     third argument to sqlite3_open_v2(). ^If the mode option is set to 
02765 **     "rw", then the database is opened for read-write (but not create) 
02766 **     access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had 
02767 **     been set. ^Value "rwc" is equivalent to setting both 
02768 **     SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE.  ^If the mode option is
02769 **     set to "memory" then a pure [in-memory database] that never reads
02770 **     or writes from disk is used. ^It is an error to specify a value for
02771 **     the mode parameter that is less restrictive than that specified by
02772 **     the flags passed in the third parameter to sqlite3_open_v2().
02773 **
02774 **   <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
02775 **     "private". ^Setting it to "shared" is equivalent to setting the
02776 **     SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
02777 **     sqlite3_open_v2(). ^Setting the cache parameter to "private" is 
02778 **     equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
02779 **     ^If sqlite3_open_v2() is used and the "cache" parameter is present in
02780 **     a URI filename, its value overrides any behavior requested by setting
02781 **     SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
02782 ** </ul>
02783 **
02784 ** ^Specifying an unknown parameter in the query component of a URI is not an
02785 ** error.  Future versions of SQLite might understand additional query
02786 ** parameters.  See "[query parameters with special meaning to SQLite]" for
02787 ** additional information.
02788 **
02789 ** [[URI filename examples]] <h3>URI filename examples</h3>
02790 **
02791 ** <table border="1" align=center cellpadding=5>
02792 ** <tr><th> URI filenames <th> Results
02793 ** <tr><td> file:data.db <td> 
02794 **          Open the file "data.db" in the current directory.
02795 ** <tr><td> file:/home/fred/data.db<br>
02796 **          file:///home/fred/data.db <br> 
02797 **          file://localhost/home/fred/data.db <br> <td> 
02798 **          Open the database file "/home/fred/data.db".
02799 ** <tr><td> file://darkstar/home/fred/data.db <td> 
02800 **          An error. "darkstar" is not a recognized authority.
02801 ** <tr><td style="white-space:nowrap"> 
02802 **          file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
02803 **     <td> Windows only: Open the file "data.db" on fred's desktop on drive
02804 **          C:. Note that the %20 escaping in this example is not strictly 
02805 **          necessary - space characters can be used literally
02806 **          in URI filenames.
02807 ** <tr><td> file:data.db?mode=ro&cache=private <td> 
02808 **          Open file "data.db" in the current directory for read-only access.
02809 **          Regardless of whether or not shared-cache mode is enabled by
02810 **          default, use a private cache.
02811 ** <tr><td> file:/home/fred/data.db?vfs=unix-nolock <td>
02812 **          Open file "/home/fred/data.db". Use the special VFS "unix-nolock".
02813 ** <tr><td> file:data.db?mode=readonly <td> 
02814 **          An error. "readonly" is not a valid option for the "mode" parameter.
02815 ** </table>
02816 **
02817 ** ^URI hexadecimal escape sequences (%HH) are supported within the path and
02818 ** query components of a URI. A hexadecimal escape sequence consists of a
02819 ** percent sign - "%" - followed by exactly two hexadecimal digits 
02820 ** specifying an octet value. ^Before the path or query components of a
02821 ** URI filename are interpreted, they are encoded using UTF-8 and all 
02822 ** hexadecimal escape sequences replaced by a single byte containing the
02823 ** corresponding octet. If this process generates an invalid UTF-8 encoding,
02824 ** the results are undefined.
02825 **
02826 ** <b>Note to Windows users:</b>  The encoding used for the filename argument
02827 ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
02828 ** codepage is currently defined.  Filenames containing international
02829 ** characters must be converted to UTF-8 prior to passing them into
02830 ** sqlite3_open() or sqlite3_open_v2().
02831 **
02832 ** <b>Note to Windows Runtime users:</b>  The temporary directory must be set
02833 ** prior to calling sqlite3_open() or sqlite3_open_v2().  Otherwise, various
02834 ** features that require the use of temporary files may fail.
02835 **
02836 ** See also: [sqlite3_temp_directory]
02837 */
02838 SQLITE_API int sqlite3_open(
02839   const char *filename,   /* Database filename (UTF-8) */
02840   sqlite3 **ppDb          /* OUT: SQLite db handle */
02841 );
02842 SQLITE_API int sqlite3_open16(
02843   const void *filename,   /* Database filename (UTF-16) */
02844   sqlite3 **ppDb          /* OUT: SQLite db handle */
02845 );
02846 SQLITE_API int sqlite3_open_v2(
02847   const char *filename,   /* Database filename (UTF-8) */
02848   sqlite3 **ppDb,         /* OUT: SQLite db handle */
02849   int flags,              /* Flags */
02850   const char *zVfs        /* Name of VFS module to use */
02851 );
02852 
02853 /*
02854 ** CAPI3REF: Obtain Values For URI Parameters
02855 **
02856 ** These are utility routines, useful to VFS implementations, that check
02857 ** to see if a database file was a URI that contained a specific query 
02858 ** parameter, and if so obtains the value of that query parameter.
02859 **
02860 ** If F is the database filename pointer passed into the xOpen() method of 
02861 ** a VFS implementation when the flags parameter to xOpen() has one or 
02862 ** more of the [SQLITE_OPEN_URI] or [SQLITE_OPEN_MAIN_DB] bits set and
02863 ** P is the name of the query parameter, then
02864 ** sqlite3_uri_parameter(F,P) returns the value of the P
02865 ** parameter if it exists or a NULL pointer if P does not appear as a 
02866 ** query parameter on F.  If P is a query parameter of F
02867 ** has no explicit value, then sqlite3_uri_parameter(F,P) returns
02868 ** a pointer to an empty string.
02869 **
02870 ** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
02871 ** parameter and returns true (1) or false (0) according to the value
02872 ** of P.  The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
02873 ** value of query parameter P is one of "yes", "true", or "on" in any
02874 ** case or if the value begins with a non-zero number.  The 
02875 ** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
02876 ** query parameter P is one of "no", "false", or "off" in any case or
02877 ** if the value begins with a numeric zero.  If P is not a query
02878 ** parameter on F or if the value of P is does not match any of the
02879 ** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
02880 **
02881 ** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
02882 ** 64-bit signed integer and returns that integer, or D if P does not
02883 ** exist.  If the value of P is something other than an integer, then
02884 ** zero is returned.
02885 ** 
02886 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
02887 ** sqlite3_uri_boolean(F,P,B) returns B.  If F is not a NULL pointer and
02888 ** is not a database file pathname pointer that SQLite passed into the xOpen
02889 ** VFS method, then the behavior of this routine is undefined and probably
02890 ** undesirable.
02891 */
02892 SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
02893 SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
02894 SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
02895 
02896 
02897 /*
02898 ** CAPI3REF: Error Codes And Messages
02899 **
02900 ** ^The sqlite3_errcode() interface returns the numeric [result code] or
02901 ** [extended result code] for the most recent failed sqlite3_* API call
02902 ** associated with a [database connection]. If a prior API call failed
02903 ** but the most recent API call succeeded, the return value from
02904 ** sqlite3_errcode() is undefined.  ^The sqlite3_extended_errcode()
02905 ** interface is the same except that it always returns the 
02906 ** [extended result code] even when extended result codes are
02907 ** disabled.
02908 **
02909 ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
02910 ** text that describes the error, as either UTF-8 or UTF-16 respectively.
02911 ** ^(Memory to hold the error message string is managed internally.
02912 ** The application does not need to worry about freeing the result.
02913 ** However, the error string might be overwritten or deallocated by
02914 ** subsequent calls to other SQLite interface functions.)^
02915 **
02916 ** ^The sqlite3_errstr() interface returns the English-language text
02917 ** that describes the [result code], as UTF-8.
02918 ** ^(Memory to hold the error message string is managed internally
02919 ** and must not be freed by the application)^.
02920 **
02921 ** When the serialized [threading mode] is in use, it might be the
02922 ** case that a second error occurs on a separate thread in between
02923 ** the time of the first error and the call to these interfaces.
02924 ** When that happens, the second error will be reported since these
02925 ** interfaces always report the most recent result.  To avoid
02926 ** this, each thread can obtain exclusive use of the [database connection] D
02927 ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
02928 ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
02929 ** all calls to the interfaces listed here are completed.
02930 **
02931 ** If an interface fails with SQLITE_MISUSE, that means the interface
02932 ** was invoked incorrectly by the application.  In that case, the
02933 ** error code and message may or may not be set.
02934 */
02935 SQLITE_API int sqlite3_errcode(sqlite3 *db);
02936 SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
02937 SQLITE_API const char *sqlite3_errmsg(sqlite3*);
02938 SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
02939 SQLITE_API const char *sqlite3_errstr(int);
02940 
02941 /*
02942 ** CAPI3REF: SQL Statement Object
02943 ** KEYWORDS: {prepared statement} {prepared statements}
02944 **
02945 ** An instance of this object represents a single SQL statement.
02946 ** This object is variously known as a "prepared statement" or a
02947 ** "compiled SQL statement" or simply as a "statement".
02948 **
02949 ** The life of a statement object goes something like this:
02950 **
02951 ** <ol>
02952 ** <li> Create the object using [sqlite3_prepare_v2()] or a related
02953 **      function.
02954 ** <li> Bind values to [host parameters] using the sqlite3_bind_*()
02955 **      interfaces.
02956 ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
02957 ** <li> Reset the statement using [sqlite3_reset()] then go back
02958 **      to step 2.  Do this zero or more times.
02959 ** <li> Destroy the object using [sqlite3_finalize()].
02960 ** </ol>
02961 **
02962 ** Refer to documentation on individual methods above for additional
02963 ** information.
02964 */
02965 typedef struct sqlite3_stmt sqlite3_stmt;
02966 
02967 /*
02968 ** CAPI3REF: Run-time Limits
02969 **
02970 ** ^(This interface allows the size of various constructs to be limited
02971 ** on a connection by connection basis.  The first parameter is the
02972 ** [database connection] whose limit is to be set or queried.  The
02973 ** second parameter is one of the [limit categories] that define a
02974 ** class of constructs to be size limited.  The third parameter is the
02975 ** new limit for that construct.)^
02976 **
02977 ** ^If the new limit is a negative number, the limit is unchanged.
02978 ** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a 
02979 ** [limits | hard upper bound]
02980 ** set at compile-time by a C preprocessor macro called
02981 ** [limits | SQLITE_MAX_<i>NAME</i>].
02982 ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
02983 ** ^Attempts to increase a limit above its hard upper bound are
02984 ** silently truncated to the hard upper bound.
02985 **
02986 ** ^Regardless of whether or not the limit was changed, the 
02987 ** [sqlite3_limit()] interface returns the prior value of the limit.
02988 ** ^Hence, to find the current value of a limit without changing it,
02989 ** simply invoke this interface with the third parameter set to -1.
02990 **
02991 ** Run-time limits are intended for use in applications that manage
02992 ** both their own internal database and also databases that are controlled
02993 ** by untrusted external sources.  An example application might be a
02994 ** web browser that has its own databases for storing history and
02995 ** separate databases controlled by JavaScript applications downloaded
02996 ** off the Internet.  The internal databases can be given the
02997 ** large, default limits.  Databases managed by external sources can
02998 ** be given much smaller limits designed to prevent a denial of service
02999 ** attack.  Developers might also want to use the [sqlite3_set_authorizer()]
03000 ** interface to further control untrusted SQL.  The size of the database
03001 ** created by an untrusted script can be contained using the
03002 ** [max_page_count] [PRAGMA].
03003 **
03004 ** New run-time limit categories may be added in future releases.
03005 */
03006 SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
03007 
03008 /*
03009 ** CAPI3REF: Run-Time Limit Categories
03010 ** KEYWORDS: {limit category} {*limit categories}
03011 **
03012 ** These constants define various performance limits
03013 ** that can be lowered at run-time using [sqlite3_limit()].
03014 ** The synopsis of the meanings of the various limits is shown below.
03015 ** Additional information is available at [limits | Limits in SQLite].
03016 **
03017 ** <dl>
03018 ** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
03019 ** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
03020 **
03021 ** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
03022 ** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
03023 **
03024 ** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
03025 ** <dd>The maximum number of columns in a table definition or in the
03026 ** result set of a [SELECT] or the maximum number of columns in an index
03027 ** or in an ORDER BY or GROUP BY clause.</dd>)^
03028 **
03029 ** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
03030 ** <dd>The maximum depth of the parse tree on any expression.</dd>)^
03031 **
03032 ** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
03033 ** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
03034 **
03035 ** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
03036 ** <dd>The maximum number of instructions in a virtual machine program
03037 ** used to implement an SQL statement.  This limit is not currently
03038 ** enforced, though that might be added in some future release of
03039 ** SQLite.</dd>)^
03040 **
03041 ** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
03042 ** <dd>The maximum number of arguments on a function.</dd>)^
03043 **
03044 ** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
03045 ** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
03046 **
03047 ** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
03048 ** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
03049 ** <dd>The maximum length of the pattern argument to the [LIKE] or
03050 ** [GLOB] operators.</dd>)^
03051 **
03052 ** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
03053 ** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
03054 ** <dd>The maximum index number of any [parameter] in an SQL statement.)^
03055 **
03056 ** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
03057 ** <dd>The maximum depth of recursion for triggers.</dd>)^
03058 ** </dl>
03059 */
03060 #define SQLITE_LIMIT_LENGTH                    0
03061 #define SQLITE_LIMIT_SQL_LENGTH                1
03062 #define SQLITE_LIMIT_COLUMN                    2
03063 #define SQLITE_LIMIT_EXPR_DEPTH                3
03064 #define SQLITE_LIMIT_COMPOUND_SELECT           4
03065 #define SQLITE_LIMIT_VDBE_OP                   5
03066 #define SQLITE_LIMIT_FUNCTION_ARG              6
03067 #define SQLITE_LIMIT_ATTACHED                  7
03068 #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
03069 #define SQLITE_LIMIT_VARIABLE_NUMBER           9
03070 #define SQLITE_LIMIT_TRIGGER_DEPTH            10
03071 
03072 /*
03073 ** CAPI3REF: Compiling An SQL Statement
03074 ** KEYWORDS: {SQL statement compiler}
03075 **
03076 ** To execute an SQL query, it must first be compiled into a byte-code
03077 ** program using one of these routines.
03078 **
03079 ** The first argument, "db", is a [database connection] obtained from a
03080 ** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
03081 ** [sqlite3_open16()].  The database connection must not have been closed.
03082 **
03083 ** The second argument, "zSql", is the statement to be compiled, encoded
03084 ** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
03085 ** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
03086 ** use UTF-16.
03087 **
03088 ** ^If the nByte argument is less than zero, then zSql is read up to the
03089 ** first zero terminator. ^If nByte is non-negative, then it is the maximum
03090 ** number of  bytes read from zSql.  ^When nByte is non-negative, the
03091 ** zSql string ends at either the first '\000' or '\u0000' character or
03092 ** the nByte-th byte, whichever comes first. If the caller knows
03093 ** that the supplied string is nul-terminated, then there is a small
03094 ** performance advantage to be gained by passing an nByte parameter that
03095 ** is equal to the number of bytes in the input string <i>including</i>
03096 ** the nul-terminator bytes as this saves SQLite from having to
03097 ** make a copy of the input string.
03098 **
03099 ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
03100 ** past the end of the first SQL statement in zSql.  These routines only
03101 ** compile the first statement in zSql, so *pzTail is left pointing to
03102 ** what remains uncompiled.
03103 **
03104 ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
03105 ** executed using [sqlite3_step()].  ^If there is an error, *ppStmt is set
03106 ** to NULL.  ^If the input text contains no SQL (if the input is an empty
03107 ** string or a comment) then *ppStmt is set to NULL.
03108 ** The calling procedure is responsible for deleting the compiled
03109 ** SQL statement using [sqlite3_finalize()] after it has finished with it.
03110 ** ppStmt may not be NULL.
03111 **
03112 ** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
03113 ** otherwise an [error code] is returned.
03114 **
03115 ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
03116 ** recommended for all new programs. The two older interfaces are retained
03117 ** for backwards compatibility, but their use is discouraged.
03118 ** ^In the "v2" interfaces, the prepared statement
03119 ** that is returned (the [sqlite3_stmt] object) contains a copy of the
03120 ** original SQL text. This causes the [sqlite3_step()] interface to
03121 ** behave differently in three ways:
03122 **
03123 ** <ol>
03124 ** <li>
03125 ** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
03126 ** always used to do, [sqlite3_step()] will automatically recompile the SQL
03127 ** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
03128 ** retries will occur before sqlite3_step() gives up and returns an error.
03129 ** </li>
03130 **
03131 ** <li>
03132 ** ^When an error occurs, [sqlite3_step()] will return one of the detailed
03133 ** [error codes] or [extended error codes].  ^The legacy behavior was that
03134 ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
03135 ** and the application would have to make a second call to [sqlite3_reset()]
03136 ** in order to find the underlying cause of the problem. With the "v2" prepare
03137 ** interfaces, the underlying reason for the error is returned immediately.
03138 ** </li>
03139 **
03140 ** <li>
03141 ** ^If the specific value bound to [parameter | host parameter] in the 
03142 ** WHERE clause might influence the choice of query plan for a statement,
03143 ** then the statement will be automatically recompiled, as if there had been 
03144 ** a schema change, on the first  [sqlite3_step()] call following any change
03145 ** to the [sqlite3_bind_text | bindings] of that [parameter]. 
03146 ** ^The specific value of WHERE-clause [parameter] might influence the 
03147 ** choice of query plan if the parameter is the left-hand side of a [LIKE]
03148 ** or [GLOB] operator or if the parameter is compared to an indexed column
03149 ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
03150 ** </li>
03151 ** </ol>
03152 */
03153 SQLITE_API int sqlite3_prepare(
03154   sqlite3 *db,            /* Database handle */
03155   const char *zSql,       /* SQL statement, UTF-8 encoded */
03156   int nByte,              /* Maximum length of zSql in bytes. */
03157   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
03158   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
03159 );
03160 SQLITE_API int sqlite3_prepare_v2(
03161   sqlite3 *db,            /* Database handle */
03162   const char *zSql,       /* SQL statement, UTF-8 encoded */
03163   int nByte,              /* Maximum length of zSql in bytes. */
03164   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
03165   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
03166 );
03167 SQLITE_API int sqlite3_prepare16(
03168   sqlite3 *db,            /* Database handle */
03169   const void *zSql,       /* SQL statement, UTF-16 encoded */
03170   int nByte,              /* Maximum length of zSql in bytes. */
03171   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
03172   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
03173 );
03174 SQLITE_API int sqlite3_prepare16_v2(
03175   sqlite3 *db,            /* Database handle */
03176   const void *zSql,       /* SQL statement, UTF-16 encoded */
03177   int nByte,              /* Maximum length of zSql in bytes. */
03178   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
03179   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
03180 );
03181 
03182 /*
03183 ** CAPI3REF: Retrieving Statement SQL
03184 **
03185 ** ^This interface can be used to retrieve a saved copy of the original
03186 ** SQL text used to create a [prepared statement] if that statement was
03187 ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
03188 */
03189 SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
03190 
03191 /*
03192 ** CAPI3REF: Determine If An SQL Statement Writes The Database
03193 **
03194 ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
03195 ** and only if the [prepared statement] X makes no direct changes to
03196 ** the content of the database file.
03197 **
03198 ** Note that [application-defined SQL functions] or
03199 ** [virtual tables] might change the database indirectly as a side effect.  
03200 ** ^(For example, if an application defines a function "eval()" that 
03201 ** calls [sqlite3_exec()], then the following SQL statement would
03202 ** change the database file through side-effects:
03203 **
03204 ** <blockquote><pre>
03205 **    SELECT eval('DELETE FROM t1') FROM t2;
03206 ** </pre></blockquote>
03207 **
03208 ** But because the [SELECT] statement does not change the database file
03209 ** directly, sqlite3_stmt_readonly() would still return true.)^
03210 **
03211 ** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
03212 ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
03213 ** since the statements themselves do not actually modify the database but
03214 ** rather they control the timing of when other statements modify the 
03215 ** database.  ^The [ATTACH] and [DETACH] statements also cause
03216 ** sqlite3_stmt_readonly() to return true since, while those statements
03217 ** change the configuration of a database connection, they do not make 
03218 ** changes to the content of the database files on disk.
03219 */
03220 SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
03221 
03222 /*
03223 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
03224 **
03225 ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
03226 ** [prepared statement] S has been stepped at least once using 
03227 ** [sqlite3_step(S)] but has not run to completion and/or has not 
03228 ** been reset using [sqlite3_reset(S)].  ^The sqlite3_stmt_busy(S)
03229 ** interface returns false if S is a NULL pointer.  If S is not a 
03230 ** NULL pointer and is not a pointer to a valid [prepared statement]
03231 ** object, then the behavior is undefined and probably undesirable.
03232 **
03233 ** This interface can be used in combination [sqlite3_next_stmt()]
03234 ** to locate all prepared statements associated with a database 
03235 ** connection that are in need of being reset.  This can be used,
03236 ** for example, in diagnostic routines to search for prepared 
03237 ** statements that are holding a transaction open.
03238 */
03239 SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
03240 
03241 /*
03242 ** CAPI3REF: Dynamically Typed Value Object
03243 ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
03244 **
03245 ** SQLite uses the sqlite3_value object to represent all values
03246 ** that can be stored in a database table. SQLite uses dynamic typing
03247 ** for the values it stores.  ^Values stored in sqlite3_value objects
03248 ** can be integers, floating point values, strings, BLOBs, or NULL.
03249 **
03250 ** An sqlite3_value object may be either "protected" or "unprotected".
03251 ** Some interfaces require a protected sqlite3_value.  Other interfaces
03252 ** will accept either a protected or an unprotected sqlite3_value.
03253 ** Every interface that accepts sqlite3_value arguments specifies
03254 ** whether or not it requires a protected sqlite3_value.
03255 **
03256 ** The terms "protected" and "unprotected" refer to whether or not
03257 ** a mutex is held.  An internal mutex is held for a protected
03258 ** sqlite3_value object but no mutex is held for an unprotected
03259 ** sqlite3_value object.  If SQLite is compiled to be single-threaded
03260 ** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
03261 ** or if SQLite is run in one of reduced mutex modes 
03262 ** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
03263 ** then there is no distinction between protected and unprotected
03264 ** sqlite3_value objects and they can be used interchangeably.  However,
03265 ** for maximum code portability it is recommended that applications
03266 ** still make the distinction between protected and unprotected
03267 ** sqlite3_value objects even when not strictly required.
03268 **
03269 ** ^The sqlite3_value objects that are passed as parameters into the
03270 ** implementation of [application-defined SQL functions] are protected.
03271 ** ^The sqlite3_value object returned by
03272 ** [sqlite3_column_value()] is unprotected.
03273 ** Unprotected sqlite3_value objects may only be used with
03274 ** [sqlite3_result_value()] and [sqlite3_bind_value()].
03275 ** The [sqlite3_value_blob | sqlite3_value_type()] family of
03276 ** interfaces require protected sqlite3_value objects.
03277 */
03278 typedef struct Mem sqlite3_value;
03279 
03280 /*
03281 ** CAPI3REF: SQL Function Context Object
03282 **
03283 ** The context in which an SQL function executes is stored in an
03284 ** sqlite3_context object.  ^A pointer to an sqlite3_context object
03285 ** is always first parameter to [application-defined SQL functions].
03286 ** The application-defined SQL function implementation will pass this
03287 ** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
03288 ** [sqlite3_aggregate_context()], [sqlite3_user_data()],
03289 ** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
03290 ** and/or [sqlite3_set_auxdata()].
03291 */
03292 typedef struct sqlite3_context sqlite3_context;
03293 
03294 /*
03295 ** CAPI3REF: Binding Values To Prepared Statements
03296 ** KEYWORDS: {host parameter} {host parameters} {host parameter name}
03297 ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
03298 **
03299 ** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
03300 ** literals may be replaced by a [parameter] that matches one of following
03301 ** templates:
03302 **
03303 ** <ul>
03304 ** <li>  ?
03305 ** <li>  ?NNN
03306 ** <li>  :VVV
03307 ** <li>  @VVV
03308 ** <li>  $VVV
03309 ** </ul>
03310 **
03311 ** In the templates above, NNN represents an integer literal,
03312 ** and VVV represents an alphanumeric identifier.)^  ^The values of these
03313 ** parameters (also called "host parameter names" or "SQL parameters")
03314 ** can be set using the sqlite3_bind_*() routines defined here.
03315 **
03316 ** ^The first argument to the sqlite3_bind_*() routines is always
03317 ** a pointer to the [sqlite3_stmt] object returned from
03318 ** [sqlite3_prepare_v2()] or its variants.
03319 **
03320 ** ^The second argument is the index of the SQL parameter to be set.
03321 ** ^The leftmost SQL parameter has an index of 1.  ^When the same named
03322 ** SQL parameter is used more than once, second and subsequent
03323 ** occurrences have the same index as the first occurrence.
03324 ** ^The index for named parameters can be looked up using the
03325 ** [sqlite3_bind_parameter_index()] API if desired.  ^The index
03326 ** for "?NNN" parameters is the value of NNN.
03327 ** ^The NNN value must be between 1 and the [sqlite3_limit()]
03328 ** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
03329 **
03330 ** ^The third argument is the value to bind to the parameter.
03331 ** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
03332 ** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
03333 ** is ignored and the end result is the same as sqlite3_bind_null().
03334 **
03335 ** ^(In those routines that have a fourth argument, its value is the
03336 ** number of bytes in the parameter.  To be clear: the value is the
03337 ** number of <u>bytes</u> in the value, not the number of characters.)^
03338 ** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
03339 ** is negative, then the length of the string is
03340 ** the number of bytes up to the first zero terminator.
03341 ** If the fourth parameter to sqlite3_bind_blob() is negative, then
03342 ** the behavior is undefined.
03343 ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
03344 ** or sqlite3_bind_text16() then that parameter must be the byte offset
03345 ** where the NUL terminator would occur assuming the string were NUL
03346 ** terminated.  If any NUL characters occur at byte offsets less than 
03347 ** the value of the fourth parameter then the resulting string value will
03348 ** contain embedded NULs.  The result of expressions involving strings
03349 ** with embedded NULs is undefined.
03350 **
03351 ** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
03352 ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
03353 ** string after SQLite has finished with it.  ^The destructor is called
03354 ** to dispose of the BLOB or string even if the call to sqlite3_bind_blob(),
03355 ** sqlite3_bind_text(), or sqlite3_bind_text16() fails.  
03356 ** ^If the fifth argument is
03357 ** the special value [SQLITE_STATIC], then SQLite assumes that the
03358 ** information is in static, unmanaged space and does not need to be freed.
03359 ** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
03360 ** SQLite makes its own private copy of the data immediately, before
03361 ** the sqlite3_bind_*() routine returns.
03362 **
03363 ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
03364 ** is filled with zeroes.  ^A zeroblob uses a fixed amount of memory
03365 ** (just an integer to hold its size) while it is being processed.
03366 ** Zeroblobs are intended to serve as placeholders for BLOBs whose
03367 ** content is later written using
03368 ** [sqlite3_blob_open | incremental BLOB I/O] routines.
03369 ** ^A negative value for the zeroblob results in a zero-length BLOB.
03370 **
03371 ** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
03372 ** for the [prepared statement] or with a prepared statement for which
03373 ** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
03374 ** then the call will return [SQLITE_MISUSE].  If any sqlite3_bind_()
03375 ** routine is passed a [prepared statement] that has been finalized, the
03376 ** result is undefined and probably harmful.
03377 **
03378 ** ^Bindings are not cleared by the [sqlite3_reset()] routine.
03379 ** ^Unbound parameters are interpreted as NULL.
03380 **
03381 ** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
03382 ** [error code] if anything goes wrong.
03383 ** ^[SQLITE_RANGE] is returned if the parameter
03384 ** index is out of range.  ^[SQLITE_NOMEM] is returned if malloc() fails.
03385 **
03386 ** See also: [sqlite3_bind_parameter_count()],
03387 ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
03388 */
03389 SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
03390 SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
03391 SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
03392 SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
03393 SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
03394 SQLITE_API int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
03395 SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
03396 SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
03397 SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
03398 
03399 /*
03400 ** CAPI3REF: Number Of SQL Parameters
03401 **
03402 ** ^This routine can be used to find the number of [SQL parameters]
03403 ** in a [prepared statement].  SQL parameters are tokens of the
03404 ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
03405 ** placeholders for values that are [sqlite3_bind_blob | bound]
03406 ** to the parameters at a later time.
03407 **
03408 ** ^(This routine actually returns the index of the largest (rightmost)
03409 ** parameter. For all forms except ?NNN, this will correspond to the
03410 ** number of unique parameters.  If parameters of the ?NNN form are used,
03411 ** there may be gaps in the list.)^
03412 **
03413 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
03414 ** [sqlite3_bind_parameter_name()], and
03415 ** [sqlite3_bind_parameter_index()].
03416 */
03417 SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
03418 
03419 /*
03420 ** CAPI3REF: Name Of A Host Parameter
03421 **
03422 ** ^The sqlite3_bind_parameter_name(P,N) interface returns
03423 ** the name of the N-th [SQL parameter] in the [prepared statement] P.
03424 ** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
03425 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
03426 ** respectively.
03427 ** In other words, the initial ":" or "$" or "@" or "?"
03428 ** is included as part of the name.)^
03429 ** ^Parameters of the form "?" without a following integer have no name
03430 ** and are referred to as "nameless" or "anonymous parameters".
03431 **
03432 ** ^The first host parameter has an index of 1, not 0.
03433 **
03434 ** ^If the value N is out of range or if the N-th parameter is
03435 ** nameless, then NULL is returned.  ^The returned string is
03436 ** always in UTF-8 encoding even if the named parameter was
03437 ** originally specified as UTF-16 in [sqlite3_prepare16()] or
03438 ** [sqlite3_prepare16_v2()].
03439 **
03440 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
03441 ** [sqlite3_bind_parameter_count()], and
03442 ** [sqlite3_bind_parameter_index()].
03443 */
03444 SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
03445 
03446 /*
03447 ** CAPI3REF: Index Of A Parameter With A Given Name
03448 **
03449 ** ^Return the index of an SQL parameter given its name.  ^The
03450 ** index value returned is suitable for use as the second
03451 ** parameter to [sqlite3_bind_blob|sqlite3_bind()].  ^A zero
03452 ** is returned if no matching parameter is found.  ^The parameter
03453 ** name must be given in UTF-8 even if the original statement
03454 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
03455 **
03456 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
03457 ** [sqlite3_bind_parameter_count()], and
03458 ** [sqlite3_bind_parameter_index()].
03459 */
03460 SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
03461 
03462 /*
03463 ** CAPI3REF: Reset All Bindings On A Prepared Statement
03464 **
03465 ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
03466 ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
03467 ** ^Use this routine to reset all host parameters to NULL.
03468 */
03469 SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
03470 
03471 /*
03472 ** CAPI3REF: Number Of Columns In A Result Set
03473 **
03474 ** ^Return the number of columns in the result set returned by the
03475 ** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
03476 ** statement that does not return data (for example an [UPDATE]).
03477 **
03478 ** See also: [sqlite3_data_count()]
03479 */
03480 SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
03481 
03482 /*
03483 ** CAPI3REF: Column Names In A Result Set
03484 **
03485 ** ^These routines return the name assigned to a particular column
03486 ** in the result set of a [SELECT] statement.  ^The sqlite3_column_name()
03487 ** interface returns a pointer to a zero-terminated UTF-8 string
03488 ** and sqlite3_column_name16() returns a pointer to a zero-terminated
03489 ** UTF-16 string.  ^The first parameter is the [prepared statement]
03490 ** that implements the [SELECT] statement. ^The second parameter is the
03491 ** column number.  ^The leftmost column is number 0.
03492 **
03493 ** ^The returned string pointer is valid until either the [prepared statement]
03494 ** is destroyed by [sqlite3_finalize()] or until the statement is automatically
03495 ** reprepared by the first call to [sqlite3_step()] for a particular run
03496 ** or until the next call to
03497 ** sqlite3_column_name() or sqlite3_column_name16() on the same column.
03498 **
03499 ** ^If sqlite3_malloc() fails during the processing of either routine
03500 ** (for example during a conversion from UTF-8 to UTF-16) then a
03501 ** NULL pointer is returned.
03502 **
03503 ** ^The name of a result column is the value of the "AS" clause for
03504 ** that column, if there is an AS clause.  If there is no AS clause
03505 ** then the name of the column is unspecified and may change from
03506 ** one release of SQLite to the next.
03507 */
03508 SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
03509 SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
03510 
03511 /*
03512 ** CAPI3REF: Source Of Data In A Query Result
03513 **
03514 ** ^These routines provide a means to determine the database, table, and
03515 ** table column that is the origin of a particular result column in
03516 ** [SELECT] statement.
03517 ** ^The name of the database or table or column can be returned as
03518 ** either a UTF-8 or UTF-16 string.  ^The _database_ routines return
03519 ** the database name, the _table_ routines return the table name, and
03520 ** the origin_ routines return the column name.
03521 ** ^The returned string is valid until the [prepared statement] is destroyed
03522 ** using [sqlite3_finalize()] or until the statement is automatically
03523 ** reprepared by the first call to [sqlite3_step()] for a particular run
03524 ** or until the same information is requested
03525 ** again in a different encoding.
03526 **
03527 ** ^The names returned are the original un-aliased names of the
03528 ** database, table, and column.
03529 **
03530 ** ^The first argument to these interfaces is a [prepared statement].
03531 ** ^These functions return information about the Nth result column returned by
03532 ** the statement, where N is the second function argument.
03533 ** ^The left-most column is column 0 for these routines.
03534 **
03535 ** ^If the Nth column returned by the statement is an expression or
03536 ** subquery and is not a column value, then all of these functions return
03537 ** NULL.  ^These routine might also return NULL if a memory allocation error
03538 ** occurs.  ^Otherwise, they return the name of the attached database, table,
03539 ** or column that query result column was extracted from.
03540 **
03541 ** ^As with all other SQLite APIs, those whose names end with "16" return
03542 ** UTF-16 encoded strings and the other functions return UTF-8.
03543 **
03544 ** ^These APIs are only available if the library was compiled with the
03545 ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
03546 **
03547 ** If two or more threads call one or more of these routines against the same
03548 ** prepared statement and column at the same time then the results are
03549 ** undefined.
03550 **
03551 ** If two or more threads call one or more
03552 ** [sqlite3_column_database_name | column metadata interfaces]
03553 ** for the same [prepared statement] and result column
03554 ** at the same time then the results are undefined.
03555 */
03556 SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
03557 SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
03558 SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
03559 SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
03560 SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
03561 SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
03562 
03563 /*
03564 ** CAPI3REF: Declared Datatype Of A Query Result
03565 **
03566 ** ^(The first parameter is a [prepared statement].
03567 ** If this statement is a [SELECT] statement and the Nth column of the
03568 ** returned result set of that [SELECT] is a table column (not an
03569 ** expression or subquery) then the declared type of the table
03570 ** column is returned.)^  ^If the Nth column of the result set is an
03571 ** expression or subquery, then a NULL pointer is returned.
03572 ** ^The returned string is always UTF-8 encoded.
03573 **
03574 ** ^(For example, given the database schema:
03575 **
03576 ** CREATE TABLE t1(c1 VARIANT);
03577 **
03578 ** and the following statement to be compiled:
03579 **
03580 ** SELECT c1 + 1, c1 FROM t1;
03581 **
03582 ** this routine would return the string "VARIANT" for the second result
03583 ** column (i==1), and a NULL pointer for the first result column (i==0).)^
03584 **
03585 ** ^SQLite uses dynamic run-time typing.  ^So just because a column
03586 ** is declared to contain a particular type does not mean that the
03587 ** data stored in that column is of the declared type.  SQLite is
03588 ** strongly typed, but the typing is dynamic not static.  ^Type
03589 ** is associated with individual values, not with the containers
03590 ** used to hold those values.
03591 */
03592 SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
03593 SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
03594 
03595 /*
03596 ** CAPI3REF: Evaluate An SQL Statement
03597 **
03598 ** After a [prepared statement] has been prepared using either
03599 ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
03600 ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
03601 ** must be called one or more times to evaluate the statement.
03602 **
03603 ** The details of the behavior of the sqlite3_step() interface depend
03604 ** on whether the statement was prepared using the newer "v2" interface
03605 ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
03606 ** interface [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
03607 ** new "v2" interface is recommended for new applications but the legacy
03608 ** interface will continue to be supported.
03609 **
03610 ** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
03611 ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
03612 ** ^With the "v2" interface, any of the other [result codes] or
03613 ** [extended result codes] might be returned as well.
03614 **
03615 ** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
03616 ** database locks it needs to do its job.  ^If the statement is a [COMMIT]
03617 ** or occurs outside of an explicit transaction, then you can retry the
03618 ** statement.  If the statement is not a [COMMIT] and occurs within an
03619 ** explicit transaction then you should rollback the transaction before
03620 ** continuing.
03621 **
03622 ** ^[SQLITE_DONE] means that the statement has finished executing
03623 ** successfully.  sqlite3_step() should not be called again on this virtual
03624 ** machine without first calling [sqlite3_reset()] to reset the virtual
03625 ** machine back to its initial state.
03626 **
03627 ** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
03628 ** is returned each time a new row of data is ready for processing by the
03629 ** caller. The values may be accessed using the [column access functions].
03630 ** sqlite3_step() is called again to retrieve the next row of data.
03631 **
03632 ** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
03633 ** violation) has occurred.  sqlite3_step() should not be called again on
03634 ** the VM. More information may be found by calling [sqlite3_errmsg()].
03635 ** ^With the legacy interface, a more specific error code (for example,
03636 ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
03637 ** can be obtained by calling [sqlite3_reset()] on the
03638 ** [prepared statement].  ^In the "v2" interface,
03639 ** the more specific error code is returned directly by sqlite3_step().
03640 **
03641 ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
03642 ** Perhaps it was called on a [prepared statement] that has
03643 ** already been [sqlite3_finalize | finalized] or on one that had
03644 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
03645 ** be the case that the same database connection is being used by two or
03646 ** more threads at the same moment in time.
03647 **
03648 ** For all versions of SQLite up to and including 3.6.23.1, a call to
03649 ** [sqlite3_reset()] was required after sqlite3_step() returned anything
03650 ** other than [SQLITE_ROW] before any subsequent invocation of
03651 ** sqlite3_step().  Failure to reset the prepared statement using 
03652 ** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
03653 ** sqlite3_step().  But after version 3.6.23.1, sqlite3_step() began
03654 ** calling [sqlite3_reset()] automatically in this circumstance rather
03655 ** than returning [SQLITE_MISUSE].  This is not considered a compatibility
03656 ** break because any application that ever receives an SQLITE_MISUSE error
03657 ** is broken by definition.  The [SQLITE_OMIT_AUTORESET] compile-time option
03658 ** can be used to restore the legacy behavior.
03659 **
03660 ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
03661 ** API always returns a generic error code, [SQLITE_ERROR], following any
03662 ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
03663 ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
03664 ** specific [error codes] that better describes the error.
03665 ** We admit that this is a goofy design.  The problem has been fixed
03666 ** with the "v2" interface.  If you prepare all of your SQL statements
03667 ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
03668 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
03669 ** then the more specific [error codes] are returned directly
03670 ** by sqlite3_step().  The use of the "v2" interface is recommended.
03671 */
03672 SQLITE_API int sqlite3_step(sqlite3_stmt*);
03673 
03674 /*
03675 ** CAPI3REF: Number of columns in a result set
03676 **
03677 ** ^The sqlite3_data_count(P) interface returns the number of columns in the
03678 ** current row of the result set of [prepared statement] P.
03679 ** ^If prepared statement P does not have results ready to return
03680 ** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
03681 ** interfaces) then sqlite3_data_count(P) returns 0.
03682 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
03683 ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
03684 ** [sqlite3_step](P) returned [SQLITE_DONE].  ^The sqlite3_data_count(P)
03685 ** will return non-zero if previous call to [sqlite3_step](P) returned
03686 ** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
03687 ** where it always returns zero since each step of that multi-step
03688 ** pragma returns 0 columns of data.
03689 **
03690 ** See also: [sqlite3_column_count()]
03691 */
03692 SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
03693 
03694 /*
03695 ** CAPI3REF: Fundamental Datatypes
03696 ** KEYWORDS: SQLITE_TEXT
03697 **
03698 ** ^(Every value in SQLite has one of five fundamental datatypes:
03699 **
03700 ** <ul>
03701 ** <li> 64-bit signed integer
03702 ** <li> 64-bit IEEE floating point number
03703 ** <li> string
03704 ** <li> BLOB
03705 ** <li> NULL
03706 ** </ul>)^
03707 **
03708 ** These constants are codes for each of those types.
03709 **
03710 ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
03711 ** for a completely different meaning.  Software that links against both
03712 ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
03713 ** SQLITE_TEXT.
03714 */
03715 #define SQLITE_INTEGER  1
03716 #define SQLITE_FLOAT    2
03717 #define SQLITE_BLOB     4
03718 #define SQLITE_NULL     5
03719 #ifdef SQLITE_TEXT
03720 # undef SQLITE_TEXT
03721 #else
03722 # define SQLITE_TEXT     3
03723 #endif
03724 #define SQLITE3_TEXT     3
03725 
03726 /*
03727 ** CAPI3REF: Result Values From A Query
03728 ** KEYWORDS: {column access functions}
03729 **
03730 ** These routines form the "result set" interface.
03731 **
03732 ** ^These routines return information about a single column of the current
03733 ** result row of a query.  ^In every case the first argument is a pointer
03734 ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
03735 ** that was returned from [sqlite3_prepare_v2()] or one of its variants)
03736 ** and the second argument is the index of the column for which information
03737 ** should be returned. ^The leftmost column of the result set has the index 0.
03738 ** ^The number of columns in the result can be determined using
03739 ** [sqlite3_column_count()].
03740 **
03741 ** If the SQL statement does not currently point to a valid row, or if the
03742 ** column index is out of range, the result is undefined.
03743 ** These routines may only be called when the most recent call to
03744 ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
03745 ** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
03746 ** If any of these routines are called after [sqlite3_reset()] or
03747 ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
03748 ** something other than [SQLITE_ROW], the results are undefined.
03749 ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
03750 ** are called from a different thread while any of these routines
03751 ** are pending, then the results are undefined.
03752 **
03753 ** ^The sqlite3_column_type() routine returns the
03754 ** [SQLITE_INTEGER | datatype code] for the initial data type
03755 ** of the result column.  ^The returned value is one of [SQLITE_INTEGER],
03756 ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].  The value
03757 ** returned by sqlite3_column_type() is only meaningful if no type
03758 ** conversions have occurred as described below.  After a type conversion,
03759 ** the value returned by sqlite3_column_type() is undefined.  Future
03760 ** versions of SQLite may change the behavior of sqlite3_column_type()
03761 ** following a type conversion.
03762 **
03763 ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
03764 ** routine returns the number of bytes in that BLOB or string.
03765 ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
03766 ** the string to UTF-8 and then returns the number of bytes.
03767 ** ^If the result is a numeric value then sqlite3_column_bytes() uses
03768 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
03769 ** the number of bytes in that string.
03770 ** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
03771 **
03772 ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
03773 ** routine returns the number of bytes in that BLOB or string.
03774 ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
03775 ** the string to UTF-16 and then returns the number of bytes.
03776 ** ^If the result is a numeric value then sqlite3_column_bytes16() uses
03777 ** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
03778 ** the number of bytes in that string.
03779 ** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
03780 **
03781 ** ^The values returned by [sqlite3_column_bytes()] and 
03782 ** [sqlite3_column_bytes16()] do not include the zero terminators at the end
03783 ** of the string.  ^For clarity: the values returned by
03784 ** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
03785 ** bytes in the string, not the number of characters.
03786 **
03787 ** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
03788 ** even empty strings, are always zero-terminated.  ^The return
03789 ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
03790 **
03791 ** ^The object returned by [sqlite3_column_value()] is an
03792 ** [unprotected sqlite3_value] object.  An unprotected sqlite3_value object
03793 ** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
03794 ** If the [unprotected sqlite3_value] object returned by
03795 ** [sqlite3_column_value()] is used in any other way, including calls
03796 ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
03797 ** or [sqlite3_value_bytes()], then the behavior is undefined.
03798 **
03799 ** These routines attempt to convert the value where appropriate.  ^For
03800 ** example, if the internal representation is FLOAT and a text result
03801 ** is requested, [sqlite3_snprintf()] is used internally to perform the
03802 ** conversion automatically.  ^(The following table details the conversions
03803 ** that are applied:
03804 **
03805 ** <blockquote>
03806 ** <table border="1">
03807 ** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion
03808 **
03809 ** <tr><td>  NULL    <td> INTEGER   <td> Result is 0
03810 ** <tr><td>  NULL    <td>  FLOAT    <td> Result is 0.0
03811 ** <tr><td>  NULL    <td>   TEXT    <td> Result is a NULL pointer
03812 ** <tr><td>  NULL    <td>   BLOB    <td> Result is a NULL pointer
03813 ** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float
03814 ** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer
03815 ** <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT
03816 ** <tr><td>  FLOAT   <td> INTEGER   <td> [CAST] to INTEGER
03817 ** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float
03818 ** <tr><td>  FLOAT   <td>   BLOB    <td> [CAST] to BLOB
03819 ** <tr><td>  TEXT    <td> INTEGER   <td> [CAST] to INTEGER
03820 ** <tr><td>  TEXT    <td>  FLOAT    <td> [CAST] to REAL
03821 ** <tr><td>  TEXT    <td>   BLOB    <td> No change
03822 ** <tr><td>  BLOB    <td> INTEGER   <td> [CAST] to INTEGER
03823 ** <tr><td>  BLOB    <td>  FLOAT    <td> [CAST] to REAL
03824 ** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
03825 ** </table>
03826 ** </blockquote>)^
03827 **
03828 ** The table above makes reference to standard C library functions atoi()
03829 ** and atof().  SQLite does not really use these functions.  It has its
03830 ** own equivalent internal routines.  The atoi() and atof() names are
03831 ** used in the table for brevity and because they are familiar to most
03832 ** C programmers.
03833 **
03834 ** Note that when type conversions occur, pointers returned by prior
03835 ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
03836 ** sqlite3_column_text16() may be invalidated.
03837 ** Type conversions and pointer invalidations might occur
03838 ** in the following cases:
03839 **
03840 ** <ul>
03841 ** <li> The initial content is a BLOB and sqlite3_column_text() or
03842 **      sqlite3_column_text16() is called.  A zero-terminator might
03843 **      need to be added to the string.</li>
03844 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
03845 **      sqlite3_column_text16() is called.  The content must be converted
03846 **      to UTF-16.</li>
03847 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
03848 **      sqlite3_column_text() is called.  The content must be converted
03849 **      to UTF-8.</li>
03850 ** </ul>
03851 **
03852 ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
03853 ** not invalidate a prior pointer, though of course the content of the buffer
03854 ** that the prior pointer references will have been modified.  Other kinds
03855 ** of conversion are done in place when it is possible, but sometimes they
03856 ** are not possible and in those cases prior pointers are invalidated.
03857 **
03858 ** The safest and easiest to remember policy is to invoke these routines
03859 ** in one of the following ways:
03860 **
03861 ** <ul>
03862 **  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
03863 **  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
03864 **  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
03865 ** </ul>
03866 **
03867 ** In other words, you should call sqlite3_column_text(),
03868 ** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
03869 ** into the desired format, then invoke sqlite3_column_bytes() or
03870 ** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls
03871 ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
03872 ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
03873 ** with calls to sqlite3_column_bytes().
03874 **
03875 ** ^The pointers returned are valid until a type conversion occurs as
03876 ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
03877 ** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
03878 ** and BLOBs is freed automatically.  Do <b>not</b> pass the pointers returned
03879 ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
03880 ** [sqlite3_free()].
03881 **
03882 ** ^(If a memory allocation error occurs during the evaluation of any
03883 ** of these routines, a default value is returned.  The default value
03884 ** is either the integer 0, the floating point number 0.0, or a NULL
03885 ** pointer.  Subsequent calls to [sqlite3_errcode()] will return
03886 ** [SQLITE_NOMEM].)^
03887 */
03888 SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
03889 SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
03890 SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
03891 SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
03892 SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
03893 SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
03894 SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
03895 SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
03896 SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
03897 SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
03898 
03899 /*
03900 ** CAPI3REF: Destroy A Prepared Statement Object
03901 **
03902 ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
03903 ** ^If the most recent evaluation of the statement encountered no errors
03904 ** or if the statement is never been evaluated, then sqlite3_finalize() returns
03905 ** SQLITE_OK.  ^If the most recent evaluation of statement S failed, then
03906 ** sqlite3_finalize(S) returns the appropriate [error code] or
03907 ** [extended error code].
03908 **
03909 ** ^The sqlite3_finalize(S) routine can be called at any point during
03910 ** the life cycle of [prepared statement] S:
03911 ** before statement S is ever evaluated, after
03912 ** one or more calls to [sqlite3_reset()], or after any call
03913 ** to [sqlite3_step()] regardless of whether or not the statement has
03914 ** completed execution.
03915 **
03916 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
03917 **
03918 ** The application must finalize every [prepared statement] in order to avoid
03919 ** resource leaks.  It is a grievous error for the application to try to use
03920 ** a prepared statement after it has been finalized.  Any use of a prepared
03921 ** statement after it has been finalized can result in undefined and
03922 ** undesirable behavior such as segfaults and heap corruption.
03923 */
03924 SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
03925 
03926 /*
03927 ** CAPI3REF: Reset A Prepared Statement Object
03928 **
03929 ** The sqlite3_reset() function is called to reset a [prepared statement]
03930 ** object back to its initial state, ready to be re-executed.
03931 ** ^Any SQL statement variables that had values bound to them using
03932 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
03933 ** Use [sqlite3_clear_bindings()] to reset the bindings.
03934 **
03935 ** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
03936 ** back to the beginning of its program.
03937 **
03938 ** ^If the most recent call to [sqlite3_step(S)] for the
03939 ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
03940 ** or if [sqlite3_step(S)] has never before been called on S,
03941 ** then [sqlite3_reset(S)] returns [SQLITE_OK].
03942 **
03943 ** ^If the most recent call to [sqlite3_step(S)] for the
03944 ** [prepared statement] S indicated an error, then
03945 ** [sqlite3_reset(S)] returns an appropriate [error code].
03946 **
03947 ** ^The [sqlite3_reset(S)] interface does not change the values
03948 ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
03949 */
03950 SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
03951 
03952 /*
03953 ** CAPI3REF: Create Or Redefine SQL Functions
03954 ** KEYWORDS: {function creation routines}
03955 ** KEYWORDS: {application-defined SQL function}
03956 ** KEYWORDS: {application-defined SQL functions}
03957 **
03958 ** ^These functions (collectively known as "function creation routines")
03959 ** are used to add SQL functions or aggregates or to redefine the behavior
03960 ** of existing SQL functions or aggregates.  The only differences between
03961 ** these routines are the text encoding expected for
03962 ** the second parameter (the name of the function being created)
03963 ** and the presence or absence of a destructor callback for
03964 ** the application data pointer.
03965 **
03966 ** ^The first parameter is the [database connection] to which the SQL
03967 ** function is to be added.  ^If an application uses more than one database
03968 ** connection then application-defined SQL functions must be added
03969 ** to each database connection separately.
03970 **
03971 ** ^The second parameter is the name of the SQL function to be created or
03972 ** redefined.  ^The length of the name is limited to 255 bytes in a UTF-8
03973 ** representation, exclusive of the zero-terminator.  ^Note that the name
03974 ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.  
03975 ** ^Any attempt to create a function with a longer name
03976 ** will result in [SQLITE_MISUSE] being returned.
03977 **
03978 ** ^The third parameter (nArg)
03979 ** is the number of arguments that the SQL function or
03980 ** aggregate takes. ^If this parameter is -1, then the SQL function or
03981 ** aggregate may take any number of arguments between 0 and the limit
03982 ** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]).  If the third
03983 ** parameter is less than -1 or greater than 127 then the behavior is
03984 ** undefined.
03985 **
03986 ** ^The fourth parameter, eTextRep, specifies what
03987 ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
03988 ** its parameters.  Every SQL function implementation must be able to work
03989 ** with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
03990 ** more efficient with one encoding than another.  ^An application may
03991 ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
03992 ** times with the same function but with different values of eTextRep.
03993 ** ^When multiple implementations of the same function are available, SQLite
03994 ** will pick the one that involves the least amount of data conversion.
03995 ** If there is only a single implementation which does not care what text
03996 ** encoding is used, then the fourth argument should be [SQLITE_ANY].
03997 **
03998 ** ^(The fifth parameter is an arbitrary pointer.  The implementation of the
03999 ** function can gain access to this pointer using [sqlite3_user_data()].)^
04000 **
04001 ** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are
04002 ** pointers to C-language functions that implement the SQL function or
04003 ** aggregate. ^A scalar SQL function requires an implementation of the xFunc
04004 ** callback only; NULL pointers must be passed as the xStep and xFinal
04005 ** parameters. ^An aggregate SQL function requires an implementation of xStep
04006 ** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
04007 ** SQL function or aggregate, pass NULL pointers for all three function
04008 ** callbacks.
04009 **
04010 ** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,
04011 ** then it is destructor for the application data pointer. 
04012 ** The destructor is invoked when the function is deleted, either by being
04013 ** overloaded or when the database connection closes.)^
04014 ** ^The destructor is also invoked if the call to
04015 ** sqlite3_create_function_v2() fails.
04016 ** ^When the destructor callback of the tenth parameter is invoked, it
04017 ** is passed a single argument which is a copy of the application data 
04018 ** pointer which was the fifth parameter to sqlite3_create_function_v2().
04019 **
04020 ** ^It is permitted to register multiple implementations of the same
04021 ** functions with the same name but with either differing numbers of
04022 ** arguments or differing preferred text encodings.  ^SQLite will use
04023 ** the implementation that most closely matches the way in which the
04024 ** SQL function is used.  ^A function implementation with a non-negative
04025 ** nArg parameter is a better match than a function implementation with
04026 ** a negative nArg.  ^A function where the preferred text encoding
04027 ** matches the database encoding is a better
04028 ** match than a function where the encoding is different.  
04029 ** ^A function where the encoding difference is between UTF16le and UTF16be
04030 ** is a closer match than a function where the encoding difference is
04031 ** between UTF8 and UTF16.
04032 **
04033 ** ^Built-in functions may be overloaded by new application-defined functions.
04034 **
04035 ** ^An application-defined function is permitted to call other
04036 ** SQLite interfaces.  However, such calls must not
04037 ** close the database connection nor finalize or reset the prepared
04038 ** statement in which the function is running.
04039 */
04040 SQLITE_API int sqlite3_create_function(
04041   sqlite3 *db,
04042   const char *zFunctionName,
04043   int nArg,
04044   int eTextRep,
04045   void *pApp,
04046   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
04047   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
04048   void (*xFinal)(sqlite3_context*)
04049 );
04050 SQLITE_API int sqlite3_create_function16(
04051   sqlite3 *db,
04052   const void *zFunctionName,
04053   int nArg,
04054   int eTextRep,
04055   void *pApp,
04056   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
04057   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
04058   void (*xFinal)(sqlite3_context*)
04059 );
04060 SQLITE_API int sqlite3_create_function_v2(
04061   sqlite3 *db,
04062   const char *zFunctionName,
04063   int nArg,
04064   int eTextRep,
04065   void *pApp,
04066   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
04067   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
04068   void (*xFinal)(sqlite3_context*),
04069   void(*xDestroy)(void*)
04070 );
04071 
04072 /*
04073 ** CAPI3REF: Text Encodings
04074 **
04075 ** These constant define integer codes that represent the various
04076 ** text encodings supported by SQLite.
04077 */
04078 #define SQLITE_UTF8           1
04079 #define SQLITE_UTF16LE        2
04080 #define SQLITE_UTF16BE        3
04081 #define SQLITE_UTF16          4    /* Use native byte order */
04082 #define SQLITE_ANY            5    /* sqlite3_create_function only */
04083 #define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */
04084 
04085 /*
04086 ** CAPI3REF: Deprecated Functions
04087 ** DEPRECATED
04088 **
04089 ** These functions are [deprecated].  In order to maintain
04090 ** backwards compatibility with older code, these functions continue 
04091 ** to be supported.  However, new applications should avoid
04092 ** the use of these functions.  To help encourage people to avoid
04093 ** using these functions, we are not going to tell you what they do.
04094 */
04095 #ifndef SQLITE_OMIT_DEPRECATED
04096 SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
04097 SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
04098 SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
04099 SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
04100 SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
04101 SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
04102                       void*,sqlite3_int64);
04103 #endif
04104 
04105 /*
04106 ** CAPI3REF: Obtaining SQL Function Parameter Values
04107 **
04108 ** The C-language implementation of SQL functions and aggregates uses
04109 ** this set of interface routines to access the parameter values on
04110 ** the function or aggregate.
04111 **
04112 ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
04113 ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
04114 ** define callbacks that implement the SQL functions and aggregates.
04115 ** The 3rd parameter to these callbacks is an array of pointers to
04116 ** [protected sqlite3_value] objects.  There is one [sqlite3_value] object for
04117 ** each parameter to the SQL function.  These routines are used to
04118 ** extract values from the [sqlite3_value] objects.
04119 **
04120 ** These routines work only with [protected sqlite3_value] objects.
04121 ** Any attempt to use these routines on an [unprotected sqlite3_value]
04122 ** object results in undefined behavior.
04123 **
04124 ** ^These routines work just like the corresponding [column access functions]
04125 ** except that  these routines take a single [protected sqlite3_value] object
04126 ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
04127 **
04128 ** ^The sqlite3_value_text16() interface extracts a UTF-16 string
04129 ** in the native byte-order of the host machine.  ^The
04130 ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
04131 ** extract UTF-16 strings as big-endian and little-endian respectively.
04132 **
04133 ** ^(The sqlite3_value_numeric_type() interface attempts to apply
04134 ** numeric affinity to the value.  This means that an attempt is
04135 ** made to convert the value to an integer or floating point.  If
04136 ** such a conversion is possible without loss of information (in other
04137 ** words, if the value is a string that looks like a number)
04138 ** then the conversion is performed.  Otherwise no conversion occurs.
04139 ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
04140 **
04141 ** Please pay particular attention to the fact that the pointer returned
04142 ** from [sqlite3_value_blob()], [sqlite3_value_text()], or
04143 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
04144 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
04145 ** or [sqlite3_value_text16()].
04146 **
04147 ** These routines must be called from the same thread as
04148 ** the SQL function that supplied the [sqlite3_value*] parameters.
04149 */
04150 SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
04151 SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
04152 SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
04153 SQLITE_API double sqlite3_value_double(sqlite3_value*);
04154 SQLITE_API int sqlite3_value_int(sqlite3_value*);
04155 SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
04156 SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
04157 SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
04158 SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
04159 SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
04160 SQLITE_API int sqlite3_value_type(sqlite3_value*);
04161 SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
04162 
04163 /*
04164 ** CAPI3REF: Obtain Aggregate Function Context
04165 **
04166 ** Implementations of aggregate SQL functions use this
04167 ** routine to allocate memory for storing their state.
04168 **
04169 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called 
04170 ** for a particular aggregate function, SQLite
04171 ** allocates N of memory, zeroes out that memory, and returns a pointer
04172 ** to the new memory. ^On second and subsequent calls to
04173 ** sqlite3_aggregate_context() for the same aggregate function instance,
04174 ** the same buffer is returned.  Sqlite3_aggregate_context() is normally
04175 ** called once for each invocation of the xStep callback and then one
04176 ** last time when the xFinal callback is invoked.  ^(When no rows match
04177 ** an aggregate query, the xStep() callback of the aggregate function
04178 ** implementation is never called and xFinal() is called exactly once.
04179 ** In those cases, sqlite3_aggregate_context() might be called for the
04180 ** first time from within xFinal().)^
04181 **
04182 ** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer 
04183 ** when first called if N is less than or equal to zero or if a memory
04184 ** allocate error occurs.
04185 **
04186 ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
04187 ** determined by the N parameter on first successful call.  Changing the
04188 ** value of N in subsequent call to sqlite3_aggregate_context() within
04189 ** the same aggregate function instance will not resize the memory
04190 ** allocation.)^  Within the xFinal callback, it is customary to set
04191 ** N=0 in calls to sqlite3_aggregate_context(C,N) so that no 
04192 ** pointless memory allocations occur.
04193 **
04194 ** ^SQLite automatically frees the memory allocated by 
04195 ** sqlite3_aggregate_context() when the aggregate query concludes.
04196 **
04197 ** The first parameter must be a copy of the
04198 ** [sqlite3_context | SQL function context] that is the first parameter
04199 ** to the xStep or xFinal callback routine that implements the aggregate
04200 ** function.
04201 **
04202 ** This routine must be called from the same thread in which
04203 ** the aggregate SQL function is running.
04204 */
04205 SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
04206 
04207 /*
04208 ** CAPI3REF: User Data For Functions
04209 **
04210 ** ^The sqlite3_user_data() interface returns a copy of
04211 ** the pointer that was the pUserData parameter (the 5th parameter)
04212 ** of the [sqlite3_create_function()]
04213 ** and [sqlite3_create_function16()] routines that originally
04214 ** registered the application defined function.
04215 **
04216 ** This routine must be called from the same thread in which
04217 ** the application-defined function is running.
04218 */
04219 SQLITE_API void *sqlite3_user_data(sqlite3_context*);
04220 
04221 /*
04222 ** CAPI3REF: Database Connection For Functions
04223 **
04224 ** ^The sqlite3_context_db_handle() interface returns a copy of
04225 ** the pointer to the [database connection] (the 1st parameter)
04226 ** of the [sqlite3_create_function()]
04227 ** and [sqlite3_create_function16()] routines that originally
04228 ** registered the application defined function.
04229 */
04230 SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
04231 
04232 /*
04233 ** CAPI3REF: Function Auxiliary Data
04234 **
04235 ** These functions may be used by (non-aggregate) SQL functions to
04236 ** associate metadata with argument values. If the same value is passed to
04237 ** multiple invocations of the same SQL function during query execution, under
04238 ** some circumstances the associated metadata may be preserved.  An example
04239 ** of where this might be useful is in a regular-expression matching
04240 ** function. The compiled version of the regular expression can be stored as
04241 ** metadata associated with the pattern string.  
04242 ** Then as long as the pattern string remains the same,
04243 ** the compiled regular expression can be reused on multiple
04244 ** invocations of the same function.
04245 **
04246 ** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
04247 ** associated by the sqlite3_set_auxdata() function with the Nth argument
04248 ** value to the application-defined function. ^If there is no metadata
04249 ** associated with the function argument, this sqlite3_get_auxdata() interface
04250 ** returns a NULL pointer.
04251 **
04252 ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
04253 ** argument of the application-defined function.  ^Subsequent
04254 ** calls to sqlite3_get_auxdata(C,N) return P from the most recent
04255 ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
04256 ** NULL if the metadata has been discarded.
04257 ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
04258 ** SQLite will invoke the destructor function X with parameter P exactly
04259 ** once, when the metadata is discarded.
04260 ** SQLite is free to discard the metadata at any time, including: <ul>
04261 ** <li> when the corresponding function parameter changes, or
04262 ** <li> when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
04263 **      SQL statement, or
04264 ** <li> when sqlite3_set_auxdata() is invoked again on the same parameter, or
04265 ** <li> during the original sqlite3_set_auxdata() call when a memory 
04266 **      allocation error occurs. </ul>)^
04267 **
04268 ** Note the last bullet in particular.  The destructor X in 
04269 ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
04270 ** sqlite3_set_auxdata() interface even returns.  Hence sqlite3_set_auxdata()
04271 ** should be called near the end of the function implementation and the
04272 ** function implementation should not make any use of P after
04273 ** sqlite3_set_auxdata() has been called.
04274 **
04275 ** ^(In practice, metadata is preserved between function calls for
04276 ** function parameters that are compile-time constants, including literal
04277 ** values and [parameters] and expressions composed from the same.)^
04278 **
04279 ** These routines must be called from the same thread in which
04280 ** the SQL function is running.
04281 */
04282 SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
04283 SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
04284 
04285 
04286 /*
04287 ** CAPI3REF: Constants Defining Special Destructor Behavior
04288 **
04289 ** These are special values for the destructor that is passed in as the
04290 ** final argument to routines like [sqlite3_result_blob()].  ^If the destructor
04291 ** argument is SQLITE_STATIC, it means that the content pointer is constant
04292 ** and will never change.  It does not need to be destroyed.  ^The
04293 ** SQLITE_TRANSIENT value means that the content will likely change in
04294 ** the near future and that SQLite should make its own private copy of
04295 ** the content before returning.
04296 **
04297 ** The typedef is necessary to work around problems in certain
04298 ** C++ compilers.
04299 */
04300 typedef void (*sqlite3_destructor_type)(void*);
04301 #define SQLITE_STATIC      ((sqlite3_destructor_type)0)
04302 #define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)
04303 
04304 /*
04305 ** CAPI3REF: Setting The Result Of An SQL Function
04306 **
04307 ** These routines are used by the xFunc or xFinal callbacks that
04308 ** implement SQL functions and aggregates.  See
04309 ** [sqlite3_create_function()] and [sqlite3_create_function16()]
04310 ** for additional information.
04311 **
04312 ** These functions work very much like the [parameter binding] family of
04313 ** functions used to bind values to host parameters in prepared statements.
04314 ** Refer to the [SQL parameter] documentation for additional information.
04315 **
04316 ** ^The sqlite3_result_blob() interface sets the result from
04317 ** an application-defined function to be the BLOB whose content is pointed
04318 ** to by the second parameter and which is N bytes long where N is the
04319 ** third parameter.
04320 **
04321 ** ^The sqlite3_result_zeroblob() interfaces set the result of
04322 ** the application-defined function to be a BLOB containing all zero
04323 ** bytes and N bytes in size, where N is the value of the 2nd parameter.
04324 **
04325 ** ^The sqlite3_result_double() interface sets the result from
04326 ** an application-defined function to be a floating point value specified
04327 ** by its 2nd argument.
04328 **
04329 ** ^The sqlite3_result_error() and sqlite3_result_error16() functions
04330 ** cause the implemented SQL function to throw an exception.
04331 ** ^SQLite uses the string pointed to by the
04332 ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
04333 ** as the text of an error message.  ^SQLite interprets the error
04334 ** message string from sqlite3_result_error() as UTF-8. ^SQLite
04335 ** interprets the string from sqlite3_result_error16() as UTF-16 in native
04336 ** byte order.  ^If the third parameter to sqlite3_result_error()
04337 ** or sqlite3_result_error16() is negative then SQLite takes as the error
04338 ** message all text up through the first zero character.
04339 ** ^If the third parameter to sqlite3_result_error() or
04340 ** sqlite3_result_error16() is non-negative then SQLite takes that many
04341 ** bytes (not characters) from the 2nd parameter as the error message.
04342 ** ^The sqlite3_result_error() and sqlite3_result_error16()
04343 ** routines make a private copy of the error message text before
04344 ** they return.  Hence, the calling function can deallocate or
04345 ** modify the text after they return without harm.
04346 ** ^The sqlite3_result_error_code() function changes the error code
04347 ** returned by SQLite as a result of an error in a function.  ^By default,
04348 ** the error code is SQLITE_ERROR.  ^A subsequent call to sqlite3_result_error()
04349 ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
04350 **
04351 ** ^The sqlite3_result_error_toobig() interface causes SQLite to throw an
04352 ** error indicating that a string or BLOB is too long to represent.
04353 **
04354 ** ^The sqlite3_result_error_nomem() interface causes SQLite to throw an
04355 ** error indicating that a memory allocation failed.
04356 **
04357 ** ^The sqlite3_result_int() interface sets the return value
04358 ** of the application-defined function to be the 32-bit signed integer
04359 ** value given in the 2nd argument.
04360 ** ^The sqlite3_result_int64() interface sets the return value
04361 ** of the application-defined function to be the 64-bit signed integer
04362 ** value given in the 2nd argument.
04363 **
04364 ** ^The sqlite3_result_null() interface sets the return value
04365 ** of the application-defined function to be NULL.
04366 **
04367 ** ^The sqlite3_result_text(), sqlite3_result_text16(),
04368 ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
04369 ** set the return value of the application-defined function to be
04370 ** a text string which is represented as UTF-8, UTF-16 native byte order,
04371 ** UTF-16 little endian, or UTF-16 big endian, respectively.
04372 ** ^SQLite takes the text result from the application from
04373 ** the 2nd parameter of the sqlite3_result_text* interfaces.
04374 ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
04375 ** is negative, then SQLite takes result text from the 2nd parameter
04376 ** through the first zero character.
04377 ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
04378 ** is non-negative, then as many bytes (not characters) of the text
04379 ** pointed to by the 2nd parameter are taken as the application-defined
04380 ** function result.  If the 3rd parameter is non-negative, then it
04381 ** must be the byte offset into the string where the NUL terminator would
04382 ** appear if the string where NUL terminated.  If any NUL characters occur
04383 ** in the string at a byte offset that is less than the value of the 3rd
04384 ** parameter, then the resulting string will contain embedded NULs and the
04385 ** result of expressions operating on strings with embedded NULs is undefined.
04386 ** ^If the 4th parameter to the sqlite3_result_text* interfaces
04387 ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
04388 ** function as the destructor on the text or BLOB result when it has
04389 ** finished using that result.
04390 ** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
04391 ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
04392 ** assumes that the text or BLOB result is in constant space and does not
04393 ** copy the content of the parameter nor call a destructor on the content
04394 ** when it has finished using that result.
04395 ** ^If the 4th parameter to the sqlite3_result_text* interfaces
04396 ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
04397 ** then SQLite makes a copy of the result into space obtained from
04398 ** from [sqlite3_malloc()] before it returns.
04399 **
04400 ** ^The sqlite3_result_value() interface sets the result of
04401 ** the application-defined function to be a copy the
04402 ** [unprotected sqlite3_value] object specified by the 2nd parameter.  ^The
04403 ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
04404 ** so that the [sqlite3_value] specified in the parameter may change or
04405 ** be deallocated after sqlite3_result_value() returns without harm.
04406 ** ^A [protected sqlite3_value] object may always be used where an
04407 ** [unprotected sqlite3_value] object is required, so either
04408 ** kind of [sqlite3_value] object can be used with this interface.
04409 **
04410 ** If these routines are called from within the different thread
04411 ** than the one containing the application-defined function that received
04412 ** the [sqlite3_context] pointer, the results are undefined.
04413 */
04414 SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
04415 SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
04416 SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
04417 SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
04418 SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
04419 SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
04420 SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
04421 SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
04422 SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
04423 SQLITE_API void sqlite3_result_null(sqlite3_context*);
04424 SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
04425 SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
04426 SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
04427 SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
04428 SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
04429 SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
04430 
04431 /*
04432 ** CAPI3REF: Define New Collating Sequences
04433 **
04434 ** ^These functions add, remove, or modify a [collation] associated
04435 ** with the [database connection] specified as the first argument.
04436 **
04437 ** ^The name of the collation is a UTF-8 string
04438 ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
04439 ** and a UTF-16 string in native byte order for sqlite3_create_collation16().
04440 ** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
04441 ** considered to be the same name.
04442 **
04443 ** ^(The third argument (eTextRep) must be one of the constants:
04444 ** <ul>
04445 ** <li> [SQLITE_UTF8],
04446 ** <li> [SQLITE_UTF16LE],
04447 ** <li> [SQLITE_UTF16BE],
04448 ** <li> [SQLITE_UTF16], or
04449 ** <li> [SQLITE_UTF16_ALIGNED].
04450 ** </ul>)^
04451 ** ^The eTextRep argument determines the encoding of strings passed
04452 ** to the collating function callback, xCallback.
04453 ** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
04454 ** force strings to be UTF16 with native byte order.
04455 ** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
04456 ** on an even byte address.
04457 **
04458 ** ^The fourth argument, pArg, is an application data pointer that is passed
04459 ** through as the first argument to the collating function callback.
04460 **
04461 ** ^The fifth argument, xCallback, is a pointer to the collating function.
04462 ** ^Multiple collating functions can be registered using the same name but
04463 ** with different eTextRep parameters and SQLite will use whichever
04464 ** function requires the least amount of data transformation.
04465 ** ^If the xCallback argument is NULL then the collating function is
04466 ** deleted.  ^When all collating functions having the same name are deleted,
04467 ** that collation is no longer usable.
04468 **
04469 ** ^The collating function callback is invoked with a copy of the pArg 
04470 ** application data pointer and with two strings in the encoding specified
04471 ** by the eTextRep argument.  The collating function must return an
04472 ** integer that is negative, zero, or positive
04473 ** if the first string is less than, equal to, or greater than the second,
04474 ** respectively.  A collating function must always return the same answer
04475 ** given the same inputs.  If two or more collating functions are registered
04476 ** to the same collation name (using different eTextRep values) then all
04477 ** must give an equivalent answer when invoked with equivalent strings.
04478 ** The collating function must obey the following properties for all
04479 ** strings A, B, and C:
04480 **
04481 ** <ol>
04482 ** <li> If A==B then B==A.
04483 ** <li> If A==B and B==C then A==C.
04484 ** <li> If A&lt;B THEN B&gt;A.
04485 ** <li> If A&lt;B and B&lt;C then A&lt;C.
04486 ** </ol>
04487 **
04488 ** If a collating function fails any of the above constraints and that
04489 ** collating function is  registered and used, then the behavior of SQLite
04490 ** is undefined.
04491 **
04492 ** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
04493 ** with the addition that the xDestroy callback is invoked on pArg when
04494 ** the collating function is deleted.
04495 ** ^Collating functions are deleted when they are overridden by later
04496 ** calls to the collation creation functions or when the
04497 ** [database connection] is closed using [sqlite3_close()].
04498 **
04499 ** ^The xDestroy callback is <u>not</u> called if the 
04500 ** sqlite3_create_collation_v2() function fails.  Applications that invoke
04501 ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should 
04502 ** check the return code and dispose of the application data pointer
04503 ** themselves rather than expecting SQLite to deal with it for them.
04504 ** This is different from every other SQLite interface.  The inconsistency 
04505 ** is unfortunate but cannot be changed without breaking backwards 
04506 ** compatibility.
04507 **
04508 ** See also:  [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
04509 */
04510 SQLITE_API int sqlite3_create_collation(
04511   sqlite3*, 
04512   const char *zName, 
04513   int eTextRep, 
04514   void *pArg,
04515   int(*xCompare)(void*,int,const void*,int,const void*)
04516 );
04517 SQLITE_API int sqlite3_create_collation_v2(
04518   sqlite3*, 
04519   const char *zName, 
04520   int eTextRep, 
04521   void *pArg,
04522   int(*xCompare)(void*,int,const void*,int,const void*),
04523   void(*xDestroy)(void*)
04524 );
04525 SQLITE_API int sqlite3_create_collation16(
04526   sqlite3*, 
04527   const void *zName,
04528   int eTextRep, 
04529   void *pArg,
04530   int(*xCompare)(void*,int,const void*,int,const void*)
04531 );
04532 
04533 /*
04534 ** CAPI3REF: Collation Needed Callbacks
04535 **
04536 ** ^To avoid having to register all collation sequences before a database
04537 ** can be used, a single callback function may be registered with the
04538 ** [database connection] to be invoked whenever an undefined collation
04539 ** sequence is required.
04540 **
04541 ** ^If the function is registered using the sqlite3_collation_needed() API,
04542 ** then it is passed the names of undefined collation sequences as strings
04543 ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
04544 ** the names are passed as UTF-16 in machine native byte order.
04545 ** ^A call to either function replaces the existing collation-needed callback.
04546 **
04547 ** ^(When the callback is invoked, the first argument passed is a copy
04548 ** of the second argument to sqlite3_collation_needed() or
04549 ** sqlite3_collation_needed16().  The second argument is the database
04550 ** connection.  The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
04551 ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
04552 ** sequence function required.  The fourth parameter is the name of the
04553 ** required collation sequence.)^
04554 **
04555 ** The callback function should register the desired collation using
04556 ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
04557 ** [sqlite3_create_collation_v2()].
04558 */
04559 SQLITE_API int sqlite3_collation_needed(
04560   sqlite3*, 
04561   void*, 
04562   void(*)(void*,sqlite3*,int eTextRep,const char*)
04563 );
04564 SQLITE_API int sqlite3_collation_needed16(
04565   sqlite3*, 
04566   void*,
04567   void(*)(void*,sqlite3*,int eTextRep,const void*)
04568 );
04569 
04570 #ifdef SQLITE_HAS_CODEC
04571 /*
04572 ** Specify the key for an encrypted database.  This routine should be
04573 ** called right after sqlite3_open().
04574 **
04575 ** The code to implement this API is not available in the public release
04576 ** of SQLite.
04577 */
04578 SQLITE_API int sqlite3_key(
04579   sqlite3 *db,                   /* Database to be rekeyed */
04580   const void *pKey, int nKey     /* The key */
04581 );
04582 SQLITE_API int sqlite3_key_v2(
04583   sqlite3 *db,                   /* Database to be rekeyed */
04584   const char *zDbName,           /* Name of the database */
04585   const void *pKey, int nKey     /* The key */
04586 );
04587 
04588 /*
04589 ** Change the key on an open database.  If the current database is not
04590 ** encrypted, this routine will encrypt it.  If pNew==0 or nNew==0, the
04591 ** database is decrypted.
04592 **
04593 ** The code to implement this API is not available in the public release
04594 ** of SQLite.
04595 */
04596 SQLITE_API int sqlite3_rekey(
04597   sqlite3 *db,                   /* Database to be rekeyed */
04598   const void *pKey, int nKey     /* The new key */
04599 );
04600 SQLITE_API int sqlite3_rekey_v2(
04601   sqlite3 *db,                   /* Database to be rekeyed */
04602   const char *zDbName,           /* Name of the database */
04603   const void *pKey, int nKey     /* The new key */
04604 );
04605 
04606 /*
04607 ** Specify the activation key for a SEE database.  Unless 
04608 ** activated, none of the SEE routines will work.
04609 */
04610 SQLITE_API void sqlite3_activate_see(
04611   const char *zPassPhrase        /* Activation phrase */
04612 );
04613 #endif
04614 
04615 #ifdef SQLITE_ENABLE_CEROD
04616 /*
04617 ** Specify the activation key for a CEROD database.  Unless 
04618 ** activated, none of the CEROD routines will work.
04619 */
04620 SQLITE_API void sqlite3_activate_cerod(
04621   const char *zPassPhrase        /* Activation phrase */
04622 );
04623 #endif
04624 
04625 /*
04626 ** CAPI3REF: Suspend Execution For A Short Time
04627 **
04628 ** The sqlite3_sleep() function causes the current thread to suspend execution
04629 ** for at least a number of milliseconds specified in its parameter.
04630 **
04631 ** If the operating system does not support sleep requests with
04632 ** millisecond time resolution, then the time will be rounded up to
04633 ** the nearest second. The number of milliseconds of sleep actually
04634 ** requested from the operating system is returned.
04635 **
04636 ** ^SQLite implements this interface by calling the xSleep()
04637 ** method of the default [sqlite3_vfs] object.  If the xSleep() method
04638 ** of the default VFS is not implemented correctly, or not implemented at
04639 ** all, then the behavior of sqlite3_sleep() may deviate from the description
04640 ** in the previous paragraphs.
04641 */
04642 SQLITE_API int sqlite3_sleep(int);
04643 
04644 /*
04645 ** CAPI3REF: Name Of The Folder Holding Temporary Files
04646 **
04647 ** ^(If this global variable is made to point to a string which is
04648 ** the name of a folder (a.k.a. directory), then all temporary files
04649 ** created by SQLite when using a built-in [sqlite3_vfs | VFS]
04650 ** will be placed in that directory.)^  ^If this variable
04651 ** is a NULL pointer, then SQLite performs a search for an appropriate
04652 ** temporary file directory.
04653 **
04654 ** It is not safe to read or modify this variable in more than one
04655 ** thread at a time.  It is not safe to read or modify this variable
04656 ** if a [database connection] is being used at the same time in a separate
04657 ** thread.
04658 ** It is intended that this variable be set once
04659 ** as part of process initialization and before any SQLite interface
04660 ** routines have been called and that this variable remain unchanged
04661 ** thereafter.
04662 **
04663 ** ^The [temp_store_directory pragma] may modify this variable and cause
04664 ** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,
04665 ** the [temp_store_directory pragma] always assumes that any string
04666 ** that this variable points to is held in memory obtained from 
04667 ** [sqlite3_malloc] and the pragma may attempt to free that memory
04668 ** using [sqlite3_free].
04669 ** Hence, if this variable is modified directly, either it should be
04670 ** made NULL or made to point to memory obtained from [sqlite3_malloc]
04671 ** or else the use of the [temp_store_directory pragma] should be avoided.
04672 **
04673 ** <b>Note to Windows Runtime users:</b>  The temporary directory must be set
04674 ** prior to calling [sqlite3_open] or [sqlite3_open_v2].  Otherwise, various
04675 ** features that require the use of temporary files may fail.  Here is an
04676 ** example of how to do this using C++ with the Windows Runtime:
04677 **
04678 ** <blockquote><pre>
04679 ** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
04680 ** &nbsp;     TemporaryFolder->Path->Data();
04681 ** char zPathBuf&#91;MAX_PATH + 1&#93;;
04682 ** memset(zPathBuf, 0, sizeof(zPathBuf));
04683 ** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
04684 ** &nbsp;     NULL, NULL);
04685 ** sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);
04686 ** </pre></blockquote>
04687 */
04688 SQLITE_API char *sqlite3_temp_directory;
04689 
04690 /*
04691 ** CAPI3REF: Name Of The Folder Holding Database Files
04692 **
04693 ** ^(If this global variable is made to point to a string which is
04694 ** the name of a folder (a.k.a. directory), then all database files
04695 ** specified with a relative pathname and created or accessed by
04696 ** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
04697 ** to be relative to that directory.)^ ^If this variable is a NULL
04698 ** pointer, then SQLite assumes that all database files specified
04699 ** with a relative pathname are relative to the current directory
04700 ** for the process.  Only the windows VFS makes use of this global
04701 ** variable; it is ignored by the unix VFS.
04702 **
04703 ** Changing the value of this variable while a database connection is
04704 ** open can result in a corrupt database.
04705 **
04706 ** It is not safe to read or modify this variable in more than one
04707 ** thread at a time.  It is not safe to read or modify this variable
04708 ** if a [database connection] is being used at the same time in a separate
04709 ** thread.
04710 ** It is intended that this variable be set once
04711 ** as part of process initialization and before any SQLite interface
04712 ** routines have been called and that this variable remain unchanged
04713 ** thereafter.
04714 **
04715 ** ^The [data_store_directory pragma] may modify this variable and cause
04716 ** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,
04717 ** the [data_store_directory pragma] always assumes that any string
04718 ** that this variable points to is held in memory obtained from 
04719 ** [sqlite3_malloc] and the pragma may attempt to free that memory
04720 ** using [sqlite3_free].
04721 ** Hence, if this variable is modified directly, either it should be
04722 ** made NULL or made to point to memory obtained from [sqlite3_malloc]
04723 ** or else the use of the [data_store_directory pragma] should be avoided.
04724 */
04725 SQLITE_API char *sqlite3_data_directory;
04726 
04727 /*
04728 ** CAPI3REF: Test For Auto-Commit Mode
04729 ** KEYWORDS: {autocommit mode}
04730 **
04731 ** ^The sqlite3_get_autocommit() interface returns non-zero or
04732 ** zero if the given database connection is or is not in autocommit mode,
04733 ** respectively.  ^Autocommit mode is on by default.
04734 ** ^Autocommit mode is disabled by a [BEGIN] statement.
04735 ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
04736 **
04737 ** If certain kinds of errors occur on a statement within a multi-statement
04738 ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
04739 ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
04740 ** transaction might be rolled back automatically.  The only way to
04741 ** find out whether SQLite automatically rolled back the transaction after
04742 ** an error is to use this function.
04743 **
04744 ** If another thread changes the autocommit status of the database
04745 ** connection while this routine is running, then the return value
04746 ** is undefined.
04747 */
04748 SQLITE_API int sqlite3_get_autocommit(sqlite3*);
04749 
04750 /*
04751 ** CAPI3REF: Find The Database Handle Of A Prepared Statement
04752 **
04753 ** ^The sqlite3_db_handle interface returns the [database connection] handle
04754 ** to which a [prepared statement] belongs.  ^The [database connection]
04755 ** returned by sqlite3_db_handle is the same [database connection]
04756 ** that was the first argument
04757 ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
04758 ** create the statement in the first place.
04759 */
04760 SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
04761 
04762 /*
04763 ** CAPI3REF: Return The Filename For A Database Connection
04764 **
04765 ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename
04766 ** associated with database N of connection D.  ^The main database file
04767 ** has the name "main".  If there is no attached database N on the database
04768 ** connection D, or if database N is a temporary or in-memory database, then
04769 ** a NULL pointer is returned.
04770 **
04771 ** ^The filename returned by this function is the output of the
04772 ** xFullPathname method of the [VFS].  ^In other words, the filename
04773 ** will be an absolute pathname, even if the filename used
04774 ** to open the database originally was a URI or relative pathname.
04775 */
04776 SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
04777 
04778 /*
04779 ** CAPI3REF: Determine if a database is read-only
04780 **
04781 ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N
04782 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
04783 ** the name of a database on connection D.
04784 */
04785 SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
04786 
04787 /*
04788 ** CAPI3REF: Find the next prepared statement
04789 **
04790 ** ^This interface returns a pointer to the next [prepared statement] after
04791 ** pStmt associated with the [database connection] pDb.  ^If pStmt is NULL
04792 ** then this interface returns a pointer to the first prepared statement
04793 ** associated with the database connection pDb.  ^If no prepared statement
04794 ** satisfies the conditions of this routine, it returns NULL.
04795 **
04796 ** The [database connection] pointer D in a call to
04797 ** [sqlite3_next_stmt(D,S)] must refer to an open database
04798 ** connection and in particular must not be a NULL pointer.
04799 */
04800 SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
04801 
04802 /*
04803 ** CAPI3REF: Commit And Rollback Notification Callbacks
04804 **
04805 ** ^The sqlite3_commit_hook() interface registers a callback
04806 ** function to be invoked whenever a transaction is [COMMIT | committed].
04807 ** ^Any callback set by a previous call to sqlite3_commit_hook()
04808 ** for the same database connection is overridden.
04809 ** ^The sqlite3_rollback_hook() interface registers a callback
04810 ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
04811 ** ^Any callback set by a previous call to sqlite3_rollback_hook()
04812 ** for the same database connection is overridden.
04813 ** ^The pArg argument is passed through to the callback.
04814 ** ^If the callback on a commit hook function returns non-zero,
04815 ** then the commit is converted into a rollback.
04816 **
04817 ** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
04818 ** return the P argument from the previous call of the same function
04819 ** on the same [database connection] D, or NULL for
04820 ** the first call for each function on D.
04821 **
04822 ** The commit and rollback hook callbacks are not reentrant.
04823 ** The callback implementation must not do anything that will modify
04824 ** the database connection that invoked the callback.  Any actions
04825 ** to modify the database connection must be deferred until after the
04826 ** completion of the [sqlite3_step()] call that triggered the commit
04827 ** or rollback hook in the first place.
04828 ** Note that running any other SQL statements, including SELECT statements,
04829 ** or merely calling [sqlite3_prepare_v2()] and [sqlite3_step()] will modify
04830 ** the database connections for the meaning of "modify" in this paragraph.
04831 **
04832 ** ^Registering a NULL function disables the callback.
04833 **
04834 ** ^When the commit hook callback routine returns zero, the [COMMIT]
04835 ** operation is allowed to continue normally.  ^If the commit hook
04836 ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
04837 ** ^The rollback hook is invoked on a rollback that results from a commit
04838 ** hook returning non-zero, just as it would be with any other rollback.
04839 **
04840 ** ^For the purposes of this API, a transaction is said to have been
04841 ** rolled back if an explicit "ROLLBACK" statement is executed, or
04842 ** an error or constraint causes an implicit rollback to occur.
04843 ** ^The rollback callback is not invoked if a transaction is
04844 ** automatically rolled back because the database connection is closed.
04845 **
04846 ** See also the [sqlite3_update_hook()] interface.
04847 */
04848 SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
04849 SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
04850 
04851 /*
04852 ** CAPI3REF: Data Change Notification Callbacks
04853 **
04854 ** ^The sqlite3_update_hook() interface registers a callback function
04855 ** with the [database connection] identified by the first argument
04856 ** to be invoked whenever a row is updated, inserted or deleted in
04857 ** a rowid table.
04858 ** ^Any callback set by a previous call to this function
04859 ** for the same database connection is overridden.
04860 **
04861 ** ^The second argument is a pointer to the function to invoke when a
04862 ** row is updated, inserted or deleted in a rowid table.
04863 ** ^The first argument to the callback is a copy of the third argument
04864 ** to sqlite3_update_hook().
04865 ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
04866 ** or [SQLITE_UPDATE], depending on the operation that caused the callback
04867 ** to be invoked.
04868 ** ^The third and fourth arguments to the callback contain pointers to the
04869 ** database and table name containing the affected row.
04870 ** ^The final callback parameter is the [rowid] of the row.
04871 ** ^In the case of an update, this is the [rowid] after the update takes place.
04872 **
04873 ** ^(The update hook is not invoked when internal system tables are
04874 ** modified (i.e. sqlite_master and sqlite_sequence).)^
04875 ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
04876 **
04877 ** ^In the current implementation, the update hook
04878 ** is not invoked when duplication rows are deleted because of an
04879 ** [ON CONFLICT | ON CONFLICT REPLACE] clause.  ^Nor is the update hook
04880 ** invoked when rows are deleted using the [truncate optimization].
04881 ** The exceptions defined in this paragraph might change in a future
04882 ** release of SQLite.
04883 **
04884 ** The update hook implementation must not do anything that will modify
04885 ** the database connection that invoked the update hook.  Any actions
04886 ** to modify the database connection must be deferred until after the
04887 ** completion of the [sqlite3_step()] call that triggered the update hook.
04888 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
04889 ** database connections for the meaning of "modify" in this paragraph.
04890 **
04891 ** ^The sqlite3_update_hook(D,C,P) function
04892 ** returns the P argument from the previous call
04893 ** on the same [database connection] D, or NULL for
04894 ** the first call on D.
04895 **
04896 ** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
04897 ** interfaces.
04898 */
04899 SQLITE_API void *sqlite3_update_hook(
04900   sqlite3*, 
04901   void(*)(void *,int ,char const *,char const *,sqlite3_int64),
04902   void*
04903 );
04904 
04905 /*
04906 ** CAPI3REF: Enable Or Disable Shared Pager Cache
04907 **
04908 ** ^(This routine enables or disables the sharing of the database cache
04909 ** and schema data structures between [database connection | connections]
04910 ** to the same database. Sharing is enabled if the argument is true
04911 ** and disabled if the argument is false.)^
04912 **
04913 ** ^Cache sharing is enabled and disabled for an entire process.
04914 ** This is a change as of SQLite version 3.5.0. In prior versions of SQLite,
04915 ** sharing was enabled or disabled for each thread separately.
04916 **
04917 ** ^(The cache sharing mode set by this interface effects all subsequent
04918 ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
04919 ** Existing database connections continue use the sharing mode
04920 ** that was in effect at the time they were opened.)^
04921 **
04922 ** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
04923 ** successfully.  An [error code] is returned otherwise.)^
04924 **
04925 ** ^Shared cache is disabled by default. But this might change in
04926 ** future releases of SQLite.  Applications that care about shared
04927 ** cache setting should set it explicitly.
04928 **
04929 ** This interface is threadsafe on processors where writing a
04930 ** 32-bit integer is atomic.
04931 **
04932 ** See Also:  [SQLite Shared-Cache Mode]
04933 */
04934 SQLITE_API int sqlite3_enable_shared_cache(int);
04935 
04936 /*
04937 ** CAPI3REF: Attempt To Free Heap Memory
04938 **
04939 ** ^The sqlite3_release_memory() interface attempts to free N bytes
04940 ** of heap memory by deallocating non-essential memory allocations
04941 ** held by the database library.   Memory used to cache database
04942 ** pages to improve performance is an example of non-essential memory.
04943 ** ^sqlite3_release_memory() returns the number of bytes actually freed,
04944 ** which might be more or less than the amount requested.
04945 ** ^The sqlite3_release_memory() routine is a no-op returning zero
04946 ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
04947 **
04948 ** See also: [sqlite3_db_release_memory()]
04949 */
04950 SQLITE_API int sqlite3_release_memory(int);
04951 
04952 /*
04953 ** CAPI3REF: Free Memory Used By A Database Connection
04954 **
04955 ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
04956 ** memory as possible from database connection D. Unlike the
04957 ** [sqlite3_release_memory()] interface, this interface is in effect even
04958 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
04959 ** omitted.
04960 **
04961 ** See also: [sqlite3_release_memory()]
04962 */
04963 SQLITE_API int sqlite3_db_release_memory(sqlite3*);
04964 
04965 /*
04966 ** CAPI3REF: Impose A Limit On Heap Size
04967 **
04968 ** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the
04969 ** soft limit on the amount of heap memory that may be allocated by SQLite.
04970 ** ^SQLite strives to keep heap memory utilization below the soft heap
04971 ** limit by reducing the number of pages held in the page cache
04972 ** as heap memory usages approaches the limit.
04973 ** ^The soft heap limit is "soft" because even though SQLite strives to stay
04974 ** below the limit, it will exceed the limit rather than generate
04975 ** an [SQLITE_NOMEM] error.  In other words, the soft heap limit 
04976 ** is advisory only.
04977 **
04978 ** ^The return value from sqlite3_soft_heap_limit64() is the size of
04979 ** the soft heap limit prior to the call, or negative in the case of an
04980 ** error.  ^If the argument N is negative
04981 ** then no change is made to the soft heap limit.  Hence, the current
04982 ** size of the soft heap limit can be determined by invoking
04983 ** sqlite3_soft_heap_limit64() with a negative argument.
04984 **
04985 ** ^If the argument N is zero then the soft heap limit is disabled.
04986 **
04987 ** ^(The soft heap limit is not enforced in the current implementation
04988 ** if one or more of following conditions are true:
04989 **
04990 ** <ul>
04991 ** <li> The soft heap limit is set to zero.
04992 ** <li> Memory accounting is disabled using a combination of the
04993 **      [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
04994 **      the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
04995 ** <li> An alternative page cache implementation is specified using
04996 **      [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...).
04997 ** <li> The page cache allocates from its own memory pool supplied
04998 **      by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than
04999 **      from the heap.
05000 ** </ul>)^
05001 **
05002 ** Beginning with SQLite version 3.7.3, the soft heap limit is enforced
05003 ** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
05004 ** compile-time option is invoked.  With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
05005 ** the soft heap limit is enforced on every memory allocation.  Without
05006 ** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced
05007 ** when memory is allocated by the page cache.  Testing suggests that because
05008 ** the page cache is the predominate memory user in SQLite, most
05009 ** applications will achieve adequate soft heap limit enforcement without
05010 ** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT].
05011 **
05012 ** The circumstances under which SQLite will enforce the soft heap limit may
05013 ** changes in future releases of SQLite.
05014 */
05015 SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
05016 
05017 /*
05018 ** CAPI3REF: Deprecated Soft Heap Limit Interface
05019 ** DEPRECATED
05020 **
05021 ** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
05022 ** interface.  This routine is provided for historical compatibility
05023 ** only.  All new applications should use the
05024 ** [sqlite3_soft_heap_limit64()] interface rather than this one.
05025 */
05026 SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
05027 
05028 
05029 /*
05030 ** CAPI3REF: Extract Metadata About A Column Of A Table
05031 **
05032 ** ^This routine returns metadata about a specific column of a specific
05033 ** database table accessible using the [database connection] handle
05034 ** passed as the first function argument.
05035 **
05036 ** ^The column is identified by the second, third and fourth parameters to
05037 ** this function. ^The second parameter is either the name of the database
05038 ** (i.e. "main", "temp", or an attached database) containing the specified
05039 ** table or NULL. ^If it is NULL, then all attached databases are searched
05040 ** for the table using the same algorithm used by the database engine to
05041 ** resolve unqualified table references.
05042 **
05043 ** ^The third and fourth parameters to this function are the table and column
05044 ** name of the desired column, respectively. Neither of these parameters
05045 ** may be NULL.
05046 **
05047 ** ^Metadata is returned by writing to the memory locations passed as the 5th
05048 ** and subsequent parameters to this function. ^Any of these arguments may be
05049 ** NULL, in which case the corresponding element of metadata is omitted.
05050 **
05051 ** ^(<blockquote>
05052 ** <table border="1">
05053 ** <tr><th> Parameter <th> Output<br>Type <th>  Description
05054 **
05055 ** <tr><td> 5th <td> const char* <td> Data type
05056 ** <tr><td> 6th <td> const char* <td> Name of default collation sequence
05057 ** <tr><td> 7th <td> int         <td> True if column has a NOT NULL constraint
05058 ** <tr><td> 8th <td> int         <td> True if column is part of the PRIMARY KEY
05059 ** <tr><td> 9th <td> int         <td> True if column is [AUTOINCREMENT]
05060 ** </table>
05061 ** </blockquote>)^
05062 **
05063 ** ^The memory pointed to by the character pointers returned for the
05064 ** declaration type and collation sequence is valid only until the next
05065 ** call to any SQLite API function.
05066 **
05067 ** ^If the specified table is actually a view, an [error code] is returned.
05068 **
05069 ** ^If the specified column is "rowid", "oid" or "_rowid_" and an
05070 ** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
05071 ** parameters are set for the explicitly declared column. ^(If there is no
05072 ** explicitly declared [INTEGER PRIMARY KEY] column, then the output
05073 ** parameters are set as follows:
05074 **
05075 ** <pre>
05076 **     data type: "INTEGER"
05077 **     collation sequence: "BINARY"
05078 **     not null: 0
05079 **     primary key: 1
05080 **     auto increment: 0
05081 ** </pre>)^
05082 **
05083 ** ^(This function may load one or more schemas from database files. If an
05084 ** error occurs during this process, or if the requested table or column
05085 ** cannot be found, an [error code] is returned and an error message left
05086 ** in the [database connection] (to be retrieved using sqlite3_errmsg()).)^
05087 **
05088 ** ^This API is only available if the library was compiled with the
05089 ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
05090 */
05091 SQLITE_API int sqlite3_table_column_metadata(
05092   sqlite3 *db,                /* Connection handle */
05093   const char *zDbName,        /* Database name or NULL */
05094   const char *zTableName,     /* Table name */
05095   const char *zColumnName,    /* Column name */
05096   char const **pzDataType,    /* OUTPUT: Declared data type */
05097   char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
05098   int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
05099   int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
05100   int *pAutoinc               /* OUTPUT: True if column is auto-increment */
05101 );
05102 
05103 /*
05104 ** CAPI3REF: Load An Extension
05105 **
05106 ** ^This interface loads an SQLite extension library from the named file.
05107 **
05108 ** ^The sqlite3_load_extension() interface attempts to load an
05109 ** [SQLite extension] library contained in the file zFile.  If
05110 ** the file cannot be loaded directly, attempts are made to load
05111 ** with various operating-system specific extensions added.
05112 ** So for example, if "samplelib" cannot be loaded, then names like
05113 ** "samplelib.so" or "samplelib.dylib" or "samplelib.dll" might
05114 ** be tried also.
05115 **
05116 ** ^The entry point is zProc.
05117 ** ^(zProc may be 0, in which case SQLite will try to come up with an
05118 ** entry point name on its own.  It first tries "sqlite3_extension_init".
05119 ** If that does not work, it constructs a name "sqlite3_X_init" where the
05120 ** X is consists of the lower-case equivalent of all ASCII alphabetic
05121 ** characters in the filename from the last "/" to the first following
05122 ** "." and omitting any initial "lib".)^
05123 ** ^The sqlite3_load_extension() interface returns
05124 ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
05125 ** ^If an error occurs and pzErrMsg is not 0, then the
05126 ** [sqlite3_load_extension()] interface shall attempt to
05127 ** fill *pzErrMsg with error message text stored in memory
05128 ** obtained from [sqlite3_malloc()]. The calling function
05129 ** should free this memory by calling [sqlite3_free()].
05130 **
05131 ** ^Extension loading must be enabled using
05132 ** [sqlite3_enable_load_extension()] prior to calling this API,
05133 ** otherwise an error will be returned.
05134 **
05135 ** See also the [load_extension() SQL function].
05136 */
05137 SQLITE_API int sqlite3_load_extension(
05138   sqlite3 *db,          /* Load the extension into this database connection */
05139   const char *zFile,    /* Name of the shared library containing extension */
05140   const char *zProc,    /* Entry point.  Derived from zFile if 0 */
05141   char **pzErrMsg       /* Put error message here if not 0 */
05142 );
05143 
05144 /*
05145 ** CAPI3REF: Enable Or Disable Extension Loading
05146 **
05147 ** ^So as not to open security holes in older applications that are
05148 ** unprepared to deal with [extension loading], and as a means of disabling
05149 ** [extension loading] while evaluating user-entered SQL, the following API
05150 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
05151 **
05152 ** ^Extension loading is off by default.
05153 ** ^Call the sqlite3_enable_load_extension() routine with onoff==1
05154 ** to turn extension loading on and call it with onoff==0 to turn
05155 ** it back off again.
05156 */
05157 SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
05158 
05159 /*
05160 ** CAPI3REF: Automatically Load Statically Linked Extensions
05161 **
05162 ** ^This interface causes the xEntryPoint() function to be invoked for
05163 ** each new [database connection] that is created.  The idea here is that
05164 ** xEntryPoint() is the entry point for a statically linked [SQLite extension]
05165 ** that is to be automatically loaded into all new database connections.
05166 **
05167 ** ^(Even though the function prototype shows that xEntryPoint() takes
05168 ** no arguments and returns void, SQLite invokes xEntryPoint() with three
05169 ** arguments and expects and integer result as if the signature of the
05170 ** entry point where as follows:
05171 **
05172 ** <blockquote><pre>
05173 ** &nbsp;  int xEntryPoint(
05174 ** &nbsp;    sqlite3 *db,
05175 ** &nbsp;    const char **pzErrMsg,
05176 ** &nbsp;    const struct sqlite3_api_routines *pThunk
05177 ** &nbsp;  );
05178 ** </pre></blockquote>)^
05179 **
05180 ** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
05181 ** point to an appropriate error message (obtained from [sqlite3_mprintf()])
05182 ** and return an appropriate [error code].  ^SQLite ensures that *pzErrMsg
05183 ** is NULL before calling the xEntryPoint().  ^SQLite will invoke
05184 ** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns.  ^If any
05185 ** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],
05186 ** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.
05187 **
05188 ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
05189 ** on the list of automatic extensions is a harmless no-op. ^No entry point
05190 ** will be called more than once for each database connection that is opened.
05191 **
05192 ** See also: [sqlite3_reset_auto_extension()]
05193 ** and [sqlite3_cancel_auto_extension()]
05194 */
05195 SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
05196 
05197 /*
05198 ** CAPI3REF: Cancel Automatic Extension Loading
05199 **
05200 ** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the
05201 ** initialization routine X that was registered using a prior call to
05202 ** [sqlite3_auto_extension(X)].  ^The [sqlite3_cancel_auto_extension(X)]
05203 ** routine returns 1 if initialization routine X was successfully 
05204 ** unregistered and it returns 0 if X was not on the list of initialization
05205 ** routines.
05206 */
05207 SQLITE_API int sqlite3_cancel_auto_extension(void (*xEntryPoint)(void));
05208 
05209 /*
05210 ** CAPI3REF: Reset Automatic Extension Loading
05211 **
05212 ** ^This interface disables all automatic extensions previously
05213 ** registered using [sqlite3_auto_extension()].
05214 */
05215 SQLITE_API void sqlite3_reset_auto_extension(void);
05216 
05217 /*
05218 ** The interface to the virtual-table mechanism is currently considered
05219 ** to be experimental.  The interface might change in incompatible ways.
05220 ** If this is a problem for you, do not use the interface at this time.
05221 **
05222 ** When the virtual-table mechanism stabilizes, we will declare the
05223 ** interface fixed, support it indefinitely, and remove this comment.
05224 */
05225 
05226 /*
05227 ** Structures used by the virtual table interface
05228 */
05229 typedef struct sqlite3_vtab sqlite3_vtab;
05230 typedef struct sqlite3_index_info sqlite3_index_info;
05231 typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
05232 typedef struct sqlite3_module sqlite3_module;
05233 
05234 /*
05235 ** CAPI3REF: Virtual Table Object
05236 ** KEYWORDS: sqlite3_module {virtual table module}
05237 **
05238 ** This structure, sometimes called a "virtual table module", 
05239 ** defines the implementation of a [virtual tables].  
05240 ** This structure consists mostly of methods for the module.
05241 **
05242 ** ^A virtual table module is created by filling in a persistent
05243 ** instance of this structure and passing a pointer to that instance
05244 ** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
05245 ** ^The registration remains valid until it is replaced by a different
05246 ** module or until the [database connection] closes.  The content
05247 ** of this structure must not change while it is registered with
05248 ** any database connection.
05249 */
05250 struct sqlite3_module {
05251   int iVersion;
05252   int (*xCreate)(sqlite3*, void *pAux,
05253                int argc, const char *const*argv,
05254                sqlite3_vtab **ppVTab, char**);
05255   int (*xConnect)(sqlite3*, void *pAux,
05256                int argc, const char *const*argv,
05257                sqlite3_vtab **ppVTab, char**);
05258   int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
05259   int (*xDisconnect)(sqlite3_vtab *pVTab);
05260   int (*xDestroy)(sqlite3_vtab *pVTab);
05261   int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
05262   int (*xClose)(sqlite3_vtab_cursor*);
05263   int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
05264                 int argc, sqlite3_value **argv);
05265   int (*xNext)(sqlite3_vtab_cursor*);
05266   int (*xEof)(sqlite3_vtab_cursor*);
05267   int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
05268   int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
05269   int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
05270   int (*xBegin)(sqlite3_vtab *pVTab);
05271   int (*xSync)(sqlite3_vtab *pVTab);
05272   int (*xCommit)(sqlite3_vtab *pVTab);
05273   int (*xRollback)(sqlite3_vtab *pVTab);
05274   int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
05275                        void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
05276                        void **ppArg);
05277   int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
05278   /* The methods above are in version 1 of the sqlite_module object. Those 
05279   ** below are for version 2 and greater. */
05280   int (*xSavepoint)(sqlite3_vtab *pVTab, int);
05281   int (*xRelease)(sqlite3_vtab *pVTab, int);
05282   int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
05283 };
05284 
05285 /*
05286 ** CAPI3REF: Virtual Table Indexing Information
05287 ** KEYWORDS: sqlite3_index_info
05288 **
05289 ** The sqlite3_index_info structure and its substructures is used as part
05290 ** of the [virtual table] interface to
05291 ** pass information into and receive the reply from the [xBestIndex]
05292 ** method of a [virtual table module].  The fields under **Inputs** are the
05293 ** inputs to xBestIndex and are read-only.  xBestIndex inserts its
05294 ** results into the **Outputs** fields.
05295 **
05296 ** ^(The aConstraint[] array records WHERE clause constraints of the form:
05297 **
05298 ** <blockquote>column OP expr</blockquote>
05299 **
05300 ** where OP is =, &lt;, &lt;=, &gt;, or &gt;=.)^  ^(The particular operator is
05301 ** stored in aConstraint[].op using one of the
05302 ** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^
05303 ** ^(The index of the column is stored in
05304 ** aConstraint[].iColumn.)^  ^(aConstraint[].usable is TRUE if the
05305 ** expr on the right-hand side can be evaluated (and thus the constraint
05306 ** is usable) and false if it cannot.)^
05307 **
05308 ** ^The optimizer automatically inverts terms of the form "expr OP column"
05309 ** and makes other simplifications to the WHERE clause in an attempt to
05310 ** get as many WHERE clause terms into the form shown above as possible.
05311 ** ^The aConstraint[] array only reports WHERE clause terms that are
05312 ** relevant to the particular virtual table being queried.
05313 **
05314 ** ^Information about the ORDER BY clause is stored in aOrderBy[].
05315 ** ^Each term of aOrderBy records a column of the ORDER BY clause.
05316 **
05317 ** The [xBestIndex] method must fill aConstraintUsage[] with information
05318 ** about what parameters to pass to xFilter.  ^If argvIndex>0 then
05319 ** the right-hand side of the corresponding aConstraint[] is evaluated
05320 ** and becomes the argvIndex-th entry in argv.  ^(If aConstraintUsage[].omit
05321 ** is true, then the constraint is assumed to be fully handled by the
05322 ** virtual table and is not checked again by SQLite.)^
05323 **
05324 ** ^The idxNum and idxPtr values are recorded and passed into the
05325 ** [xFilter] method.
05326 ** ^[sqlite3_free()] is used to free idxPtr if and only if
05327 ** needToFreeIdxPtr is true.
05328 **
05329 ** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in
05330 ** the correct order to satisfy the ORDER BY clause so that no separate
05331 ** sorting step is required.
05332 **
05333 ** ^The estimatedCost value is an estimate of the cost of a particular
05334 ** strategy. A cost of N indicates that the cost of the strategy is similar
05335 ** to a linear scan of an SQLite table with N rows. A cost of log(N) 
05336 ** indicates that the expense of the operation is similar to that of a
05337 ** binary search on a unique indexed field of an SQLite table with N rows.
05338 **
05339 ** ^The estimatedRows value is an estimate of the number of rows that
05340 ** will be returned by the strategy.
05341 **
05342 ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
05343 ** structure for SQLite version 3.8.2. If a virtual table extension is
05344 ** used with an SQLite version earlier than 3.8.2, the results of attempting 
05345 ** to read or write the estimatedRows field are undefined (but are likely 
05346 ** to included crashing the application). The estimatedRows field should
05347 ** therefore only be used if [sqlite3_libversion_number()] returns a
05348 ** value greater than or equal to 3008002.
05349 */
05350 struct sqlite3_index_info {
05351   /* Inputs */
05352   int nConstraint;           /* Number of entries in aConstraint */
05353   struct sqlite3_index_constraint {
05354      int iColumn;              /* Column on left-hand side of constraint */
05355      unsigned char op;         /* Constraint operator */
05356      unsigned char usable;     /* True if this constraint is usable */
05357      int iTermOffset;          /* Used internally - xBestIndex should ignore */
05358   } *aConstraint;            /* Table of WHERE clause constraints */
05359   int nOrderBy;              /* Number of terms in the ORDER BY clause */
05360   struct sqlite3_index_orderby {
05361      int iColumn;              /* Column number */
05362      unsigned char desc;       /* True for DESC.  False for ASC. */
05363   } *aOrderBy;               /* The ORDER BY clause */
05364   /* Outputs */
05365   struct sqlite3_index_constraint_usage {
05366     int argvIndex;           /* if >0, constraint is part of argv to xFilter */
05367     unsigned char omit;      /* Do not code a test for this constraint */
05368   } *aConstraintUsage;
05369   int idxNum;                /* Number used to identify the index */
05370   char *idxStr;              /* String, possibly obtained from sqlite3_malloc */
05371   int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */
05372   int orderByConsumed;       /* True if output is already ordered */
05373   double estimatedCost;           /* Estimated cost of using this index */
05374   /* Fields below are only available in SQLite 3.8.2 and later */
05375   sqlite3_int64 estimatedRows;    /* Estimated number of rows returned */
05376 };
05377 
05378 /*
05379 ** CAPI3REF: Virtual Table Constraint Operator Codes
05380 **
05381 ** These macros defined the allowed values for the
05382 ** [sqlite3_index_info].aConstraint[].op field.  Each value represents
05383 ** an operator that is part of a constraint term in the wHERE clause of
05384 ** a query that uses a [virtual table].
05385 */
05386 #define SQLITE_INDEX_CONSTRAINT_EQ    2
05387 #define SQLITE_INDEX_CONSTRAINT_GT    4
05388 #define SQLITE_INDEX_CONSTRAINT_LE    8
05389 #define SQLITE_INDEX_CONSTRAINT_LT    16
05390 #define SQLITE_INDEX_CONSTRAINT_GE    32
05391 #define SQLITE_INDEX_CONSTRAINT_MATCH 64
05392 
05393 /*
05394 ** CAPI3REF: Register A Virtual Table Implementation
05395 **
05396 ** ^These routines are used to register a new [virtual table module] name.
05397 ** ^Module names must be registered before
05398 ** creating a new [virtual table] using the module and before using a
05399 ** preexisting [virtual table] for the module.
05400 **
05401 ** ^The module name is registered on the [database connection] specified
05402 ** by the first parameter.  ^The name of the module is given by the 
05403 ** second parameter.  ^The third parameter is a pointer to
05404 ** the implementation of the [virtual table module].   ^The fourth
05405 ** parameter is an arbitrary client data pointer that is passed through
05406 ** into the [xCreate] and [xConnect] methods of the virtual table module
05407 ** when a new virtual table is be being created or reinitialized.
05408 **
05409 ** ^The sqlite3_create_module_v2() interface has a fifth parameter which
05410 ** is a pointer to a destructor for the pClientData.  ^SQLite will
05411 ** invoke the destructor function (if it is not NULL) when SQLite
05412 ** no longer needs the pClientData pointer.  ^The destructor will also
05413 ** be invoked if the call to sqlite3_create_module_v2() fails.
05414 ** ^The sqlite3_create_module()
05415 ** interface is equivalent to sqlite3_create_module_v2() with a NULL
05416 ** destructor.
05417 */
05418 SQLITE_API int sqlite3_create_module(
05419   sqlite3 *db,               /* SQLite connection to register module with */
05420   const char *zName,         /* Name of the module */
05421   const sqlite3_module *p,   /* Methods for the module */
05422   void *pClientData          /* Client data for xCreate/xConnect */
05423 );
05424 SQLITE_API int sqlite3_create_module_v2(
05425   sqlite3 *db,               /* SQLite connection to register module with */
05426   const char *zName,         /* Name of the module */
05427   const sqlite3_module *p,   /* Methods for the module */
05428   void *pClientData,         /* Client data for xCreate/xConnect */
05429   void(*xDestroy)(void*)     /* Module destructor function */
05430 );
05431 
05432 /*
05433 ** CAPI3REF: Virtual Table Instance Object
05434 ** KEYWORDS: sqlite3_vtab
05435 **
05436 ** Every [virtual table module] implementation uses a subclass
05437 ** of this object to describe a particular instance
05438 ** of the [virtual table].  Each subclass will
05439 ** be tailored to the specific needs of the module implementation.
05440 ** The purpose of this superclass is to define certain fields that are
05441 ** common to all module implementations.
05442 **
05443 ** ^Virtual tables methods can set an error message by assigning a
05444 ** string obtained from [sqlite3_mprintf()] to zErrMsg.  The method should
05445 ** take care that any prior string is freed by a call to [sqlite3_free()]
05446 ** prior to assigning a new string to zErrMsg.  ^After the error message
05447 ** is delivered up to the client application, the string will be automatically
05448 ** freed by sqlite3_free() and the zErrMsg field will be zeroed.
05449 */
05450 struct sqlite3_vtab {
05451   const sqlite3_module *pModule;  /* The module for this virtual table */
05452   int nRef;                       /* NO LONGER USED */
05453   char *zErrMsg;                  /* Error message from sqlite3_mprintf() */
05454   /* Virtual table implementations will typically add additional fields */
05455 };
05456 
05457 /*
05458 ** CAPI3REF: Virtual Table Cursor Object
05459 ** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
05460 **
05461 ** Every [virtual table module] implementation uses a subclass of the
05462 ** following structure to describe cursors that point into the
05463 ** [virtual table] and are used
05464 ** to loop through the virtual table.  Cursors are created using the
05465 ** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
05466 ** by the [sqlite3_module.xClose | xClose] method.  Cursors are used
05467 ** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
05468 ** of the module.  Each module implementation will define
05469 ** the content of a cursor structure to suit its own needs.
05470 **
05471 ** This superclass exists in order to define fields of the cursor that
05472 ** are common to all implementations.
05473 */
05474 struct sqlite3_vtab_cursor {
05475   sqlite3_vtab *pVtab;      /* Virtual table of this cursor */
05476   /* Virtual table implementations will typically add additional fields */
05477 };
05478 
05479 /*
05480 ** CAPI3REF: Declare The Schema Of A Virtual Table
05481 **
05482 ** ^The [xCreate] and [xConnect] methods of a
05483 ** [virtual table module] call this interface
05484 ** to declare the format (the names and datatypes of the columns) of
05485 ** the virtual tables they implement.
05486 */
05487 SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
05488 
05489 /*
05490 ** CAPI3REF: Overload A Function For A Virtual Table
05491 **
05492 ** ^(Virtual tables can provide alternative implementations of functions
05493 ** using the [xFindFunction] method of the [virtual table module].  
05494 ** But global versions of those functions
05495 ** must exist in order to be overloaded.)^
05496 **
05497 ** ^(This API makes sure a global version of a function with a particular
05498 ** name and number of parameters exists.  If no such function exists
05499 ** before this API is called, a new function is created.)^  ^The implementation
05500 ** of the new function always causes an exception to be thrown.  So
05501 ** the new function is not good for anything by itself.  Its only
05502 ** purpose is to be a placeholder function that can be overloaded
05503 ** by a [virtual table].
05504 */
05505 SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
05506 
05507 /*
05508 ** The interface to the virtual-table mechanism defined above (back up
05509 ** to a comment remarkably similar to this one) is currently considered
05510 ** to be experimental.  The interface might change in incompatible ways.
05511 ** If this is a problem for you, do not use the interface at this time.
05512 **
05513 ** When the virtual-table mechanism stabilizes, we will declare the
05514 ** interface fixed, support it indefinitely, and remove this comment.
05515 */
05516 
05517 /*
05518 ** CAPI3REF: A Handle To An Open BLOB
05519 ** KEYWORDS: {BLOB handle} {BLOB handles}
05520 **
05521 ** An instance of this object represents an open BLOB on which
05522 ** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
05523 ** ^Objects of this type are created by [sqlite3_blob_open()]
05524 ** and destroyed by [sqlite3_blob_close()].
05525 ** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
05526 ** can be used to read or write small subsections of the BLOB.
05527 ** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
05528 */
05529 typedef struct sqlite3_blob sqlite3_blob;
05530 
05531 /*
05532 ** CAPI3REF: Open A BLOB For Incremental I/O
05533 **
05534 ** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
05535 ** in row iRow, column zColumn, table zTable in database zDb;
05536 ** in other words, the same BLOB that would be selected by:
05537 **
05538 ** <pre>
05539 **     SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
05540 ** </pre>)^
05541 **
05542 ** ^If the flags parameter is non-zero, then the BLOB is opened for read
05543 ** and write access. ^If it is zero, the BLOB is opened for read access.
05544 ** ^It is not possible to open a column that is part of an index or primary 
05545 ** key for writing. ^If [foreign key constraints] are enabled, it is 
05546 ** not possible to open a column that is part of a [child key] for writing.
05547 **
05548 ** ^Note that the database name is not the filename that contains
05549 ** the database but rather the symbolic name of the database that
05550 ** appears after the AS keyword when the database is connected using [ATTACH].
05551 ** ^For the main database file, the database name is "main".
05552 ** ^For TEMP tables, the database name is "temp".
05553 **
05554 ** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
05555 ** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
05556 ** to be a null pointer.)^
05557 ** ^This function sets the [database connection] error code and message
05558 ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related
05559 ** functions. ^Note that the *ppBlob variable is always initialized in a
05560 ** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob
05561 ** regardless of the success or failure of this routine.
05562 **
05563 ** ^(If the row that a BLOB handle points to is modified by an
05564 ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
05565 ** then the BLOB handle is marked as "expired".
05566 ** This is true if any column of the row is changed, even a column
05567 ** other than the one the BLOB handle is open on.)^
05568 ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
05569 ** an expired BLOB handle fail with a return code of [SQLITE_ABORT].
05570 ** ^(Changes written into a BLOB prior to the BLOB expiring are not
05571 ** rolled back by the expiration of the BLOB.  Such changes will eventually
05572 ** commit if the transaction continues to completion.)^
05573 **
05574 ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
05575 ** the opened blob.  ^The size of a blob may not be changed by this
05576 ** interface.  Use the [UPDATE] SQL command to change the size of a
05577 ** blob.
05578 **
05579 ** ^The [sqlite3_blob_open()] interface will fail for a [WITHOUT ROWID]
05580 ** table.  Incremental BLOB I/O is not possible on [WITHOUT ROWID] tables.
05581 **
05582 ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
05583 ** and the built-in [zeroblob] SQL function can be used, if desired,
05584 ** to create an empty, zero-filled blob in which to read or write using
05585 ** this interface.
05586 **
05587 ** To avoid a resource leak, every open [BLOB handle] should eventually
05588 ** be released by a call to [sqlite3_blob_close()].
05589 */
05590 SQLITE_API int sqlite3_blob_open(
05591   sqlite3*,
05592   const char *zDb,
05593   const char *zTable,
05594   const char *zColumn,
05595   sqlite3_int64 iRow,
05596   int flags,
05597   sqlite3_blob **ppBlob
05598 );
05599 
05600 /*
05601 ** CAPI3REF: Move a BLOB Handle to a New Row
05602 **
05603 ** ^This function is used to move an existing blob handle so that it points
05604 ** to a different row of the same database table. ^The new row is identified
05605 ** by the rowid value passed as the second argument. Only the row can be
05606 ** changed. ^The database, table and column on which the blob handle is open
05607 ** remain the same. Moving an existing blob handle to a new row can be
05608 ** faster than closing the existing handle and opening a new one.
05609 **
05610 ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
05611 ** it must exist and there must be either a blob or text value stored in
05612 ** the nominated column.)^ ^If the new row is not present in the table, or if
05613 ** it does not contain a blob or text value, or if another error occurs, an
05614 ** SQLite error code is returned and the blob handle is considered aborted.
05615 ** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or
05616 ** [sqlite3_blob_reopen()] on an aborted blob handle immediately return
05617 ** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle
05618 ** always returns zero.
05619 **
05620 ** ^This function sets the database handle error code and message.
05621 */
05622 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
05623 
05624 /*
05625 ** CAPI3REF: Close A BLOB Handle
05626 **
05627 ** ^Closes an open [BLOB handle].
05628 **
05629 ** ^Closing a BLOB shall cause the current transaction to commit
05630 ** if there are no other BLOBs, no pending prepared statements, and the
05631 ** database connection is in [autocommit mode].
05632 ** ^If any writes were made to the BLOB, they might be held in cache
05633 ** until the close operation if they will fit.
05634 **
05635 ** ^(Closing the BLOB often forces the changes
05636 ** out to disk and so if any I/O errors occur, they will likely occur
05637 ** at the time when the BLOB is closed.  Any errors that occur during
05638 ** closing are reported as a non-zero return value.)^
05639 **
05640 ** ^(The BLOB is closed unconditionally.  Even if this routine returns
05641 ** an error code, the BLOB is still closed.)^
05642 **
05643 ** ^Calling this routine with a null pointer (such as would be returned
05644 ** by a failed call to [sqlite3_blob_open()]) is a harmless no-op.
05645 */
05646 SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
05647 
05648 /*
05649 ** CAPI3REF: Return The Size Of An Open BLOB
05650 **
05651 ** ^Returns the size in bytes of the BLOB accessible via the 
05652 ** successfully opened [BLOB handle] in its only argument.  ^The
05653 ** incremental blob I/O routines can only read or overwriting existing
05654 ** blob content; they cannot change the size of a blob.
05655 **
05656 ** This routine only works on a [BLOB handle] which has been created
05657 ** by a prior successful call to [sqlite3_blob_open()] and which has not
05658 ** been closed by [sqlite3_blob_close()].  Passing any other pointer in
05659 ** to this routine results in undefined and probably undesirable behavior.
05660 */
05661 SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
05662 
05663 /*
05664 ** CAPI3REF: Read Data From A BLOB Incrementally
05665 **
05666 ** ^(This function is used to read data from an open [BLOB handle] into a
05667 ** caller-supplied buffer. N bytes of data are copied into buffer Z
05668 ** from the open BLOB, starting at offset iOffset.)^
05669 **
05670 ** ^If offset iOffset is less than N bytes from the end of the BLOB,
05671 ** [SQLITE_ERROR] is returned and no data is read.  ^If N or iOffset is
05672 ** less than zero, [SQLITE_ERROR] is returned and no data is read.
05673 ** ^The size of the blob (and hence the maximum value of N+iOffset)
05674 ** can be determined using the [sqlite3_blob_bytes()] interface.
05675 **
05676 ** ^An attempt to read from an expired [BLOB handle] fails with an
05677 ** error code of [SQLITE_ABORT].
05678 **
05679 ** ^(On success, sqlite3_blob_read() returns SQLITE_OK.
05680 ** Otherwise, an [error code] or an [extended error code] is returned.)^
05681 **
05682 ** This routine only works on a [BLOB handle] which has been created
05683 ** by a prior successful call to [sqlite3_blob_open()] and which has not
05684 ** been closed by [sqlite3_blob_close()].  Passing any other pointer in
05685 ** to this routine results in undefined and probably undesirable behavior.
05686 **
05687 ** See also: [sqlite3_blob_write()].
05688 */
05689 SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
05690 
05691 /*
05692 ** CAPI3REF: Write Data Into A BLOB Incrementally
05693 **
05694 ** ^This function is used to write data into an open [BLOB handle] from a
05695 ** caller-supplied buffer. ^N bytes of data are copied from the buffer Z
05696 ** into the open BLOB, starting at offset iOffset.
05697 **
05698 ** ^If the [BLOB handle] passed as the first argument was not opened for
05699 ** writing (the flags parameter to [sqlite3_blob_open()] was zero),
05700 ** this function returns [SQLITE_READONLY].
05701 **
05702 ** ^This function may only modify the contents of the BLOB; it is
05703 ** not possible to increase the size of a BLOB using this API.
05704 ** ^If offset iOffset is less than N bytes from the end of the BLOB,
05705 ** [SQLITE_ERROR] is returned and no data is written.  ^If N is
05706 ** less than zero [SQLITE_ERROR] is returned and no data is written.
05707 ** The size of the BLOB (and hence the maximum value of N+iOffset)
05708 ** can be determined using the [sqlite3_blob_bytes()] interface.
05709 **
05710 ** ^An attempt to write to an expired [BLOB handle] fails with an
05711 ** error code of [SQLITE_ABORT].  ^Writes to the BLOB that occurred
05712 ** before the [BLOB handle] expired are not rolled back by the
05713 ** expiration of the handle, though of course those changes might
05714 ** have been overwritten by the statement that expired the BLOB handle
05715 ** or by other independent statements.
05716 **
05717 ** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
05718 ** Otherwise, an  [error code] or an [extended error code] is returned.)^
05719 **
05720 ** This routine only works on a [BLOB handle] which has been created
05721 ** by a prior successful call to [sqlite3_blob_open()] and which has not
05722 ** been closed by [sqlite3_blob_close()].  Passing any other pointer in
05723 ** to this routine results in undefined and probably undesirable behavior.
05724 **
05725 ** See also: [sqlite3_blob_read()].
05726 */
05727 SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
05728 
05729 /*
05730 ** CAPI3REF: Virtual File System Objects
05731 **
05732 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
05733 ** that SQLite uses to interact
05734 ** with the underlying operating system.  Most SQLite builds come with a
05735 ** single default VFS that is appropriate for the host computer.
05736 ** New VFSes can be registered and existing VFSes can be unregistered.
05737 ** The following interfaces are provided.
05738 **
05739 ** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
05740 ** ^Names are case sensitive.
05741 ** ^Names are zero-terminated UTF-8 strings.
05742 ** ^If there is no match, a NULL pointer is returned.
05743 ** ^If zVfsName is NULL then the default VFS is returned.
05744 **
05745 ** ^New VFSes are registered with sqlite3_vfs_register().
05746 ** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
05747 ** ^The same VFS can be registered multiple times without injury.
05748 ** ^To make an existing VFS into the default VFS, register it again
05749 ** with the makeDflt flag set.  If two different VFSes with the
05750 ** same name are registered, the behavior is undefined.  If a
05751 ** VFS is registered with a name that is NULL or an empty string,
05752 ** then the behavior is undefined.
05753 **
05754 ** ^Unregister a VFS with the sqlite3_vfs_unregister() interface.
05755 ** ^(If the default VFS is unregistered, another VFS is chosen as
05756 ** the default.  The choice for the new VFS is arbitrary.)^
05757 */
05758 SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
05759 SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
05760 SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
05761 
05762 /*
05763 ** CAPI3REF: Mutexes
05764 **
05765 ** The SQLite core uses these routines for thread
05766 ** synchronization. Though they are intended for internal
05767 ** use by SQLite, code that links against SQLite is
05768 ** permitted to use any of these routines.
05769 **
05770 ** The SQLite source code contains multiple implementations
05771 ** of these mutex routines.  An appropriate implementation
05772 ** is selected automatically at compile-time.  ^(The following
05773 ** implementations are available in the SQLite core:
05774 **
05775 ** <ul>
05776 ** <li>   SQLITE_MUTEX_PTHREADS
05777 ** <li>   SQLITE_MUTEX_W32
05778 ** <li>   SQLITE_MUTEX_NOOP
05779 ** </ul>)^
05780 **
05781 ** ^The SQLITE_MUTEX_NOOP implementation is a set of routines
05782 ** that does no real locking and is appropriate for use in
05783 ** a single-threaded application.  ^The SQLITE_MUTEX_PTHREADS and
05784 ** SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
05785 ** and Windows.
05786 **
05787 ** ^(If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
05788 ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
05789 ** implementation is included with the library. In this case the
05790 ** application must supply a custom mutex implementation using the
05791 ** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
05792 ** before calling sqlite3_initialize() or any other public sqlite3_
05793 ** function that calls sqlite3_initialize().)^
05794 **
05795 ** ^The sqlite3_mutex_alloc() routine allocates a new
05796 ** mutex and returns a pointer to it. ^If it returns NULL
05797 ** that means that a mutex could not be allocated.  ^SQLite
05798 ** will unwind its stack and return an error.  ^(The argument
05799 ** to sqlite3_mutex_alloc() is one of these integer constants:
05800 **
05801 ** <ul>
05802 ** <li>  SQLITE_MUTEX_FAST
05803 ** <li>  SQLITE_MUTEX_RECURSIVE
05804 ** <li>  SQLITE_MUTEX_STATIC_MASTER
05805 ** <li>  SQLITE_MUTEX_STATIC_MEM
05806 ** <li>  SQLITE_MUTEX_STATIC_MEM2
05807 ** <li>  SQLITE_MUTEX_STATIC_PRNG
05808 ** <li>  SQLITE_MUTEX_STATIC_LRU
05809 ** <li>  SQLITE_MUTEX_STATIC_LRU2
05810 ** </ul>)^
05811 **
05812 ** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
05813 ** cause sqlite3_mutex_alloc() to create
05814 ** a new mutex.  ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
05815 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
05816 ** The mutex implementation does not need to make a distinction
05817 ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
05818 ** not want to.  ^SQLite will only request a recursive mutex in
05819 ** cases where it really needs one.  ^If a faster non-recursive mutex
05820 ** implementation is available on the host platform, the mutex subsystem
05821 ** might return such a mutex in response to SQLITE_MUTEX_FAST.
05822 **
05823 ** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
05824 ** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
05825 ** a pointer to a static preexisting mutex.  ^Six static mutexes are
05826 ** used by the current version of SQLite.  Future versions of SQLite
05827 ** may add additional static mutexes.  Static mutexes are for internal
05828 ** use by SQLite only.  Applications that use SQLite mutexes should
05829 ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
05830 ** SQLITE_MUTEX_RECURSIVE.
05831 **
05832 ** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
05833 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
05834 ** returns a different mutex on every call.  ^But for the static
05835 ** mutex types, the same mutex is returned on every call that has
05836 ** the same type number.
05837 **
05838 ** ^The sqlite3_mutex_free() routine deallocates a previously
05839 ** allocated dynamic mutex.  ^SQLite is careful to deallocate every
05840 ** dynamic mutex that it allocates.  The dynamic mutexes must not be in
05841 ** use when they are deallocated.  Attempting to deallocate a static
05842 ** mutex results in undefined behavior.  ^SQLite never deallocates
05843 ** a static mutex.
05844 **
05845 ** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
05846 ** to enter a mutex.  ^If another thread is already within the mutex,
05847 ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
05848 ** SQLITE_BUSY.  ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
05849 ** upon successful entry.  ^(Mutexes created using
05850 ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
05851 ** In such cases the,
05852 ** mutex must be exited an equal number of times before another thread
05853 ** can enter.)^  ^(If the same thread tries to enter any other
05854 ** kind of mutex more than once, the behavior is undefined.
05855 ** SQLite will never exhibit
05856 ** such behavior in its own use of mutexes.)^
05857 **
05858 ** ^(Some systems (for example, Windows 95) do not support the operation
05859 ** implemented by sqlite3_mutex_try().  On those systems, sqlite3_mutex_try()
05860 ** will always return SQLITE_BUSY.  The SQLite core only ever uses
05861 ** sqlite3_mutex_try() as an optimization so this is acceptable behavior.)^
05862 **
05863 ** ^The sqlite3_mutex_leave() routine exits a mutex that was
05864 ** previously entered by the same thread.   ^(The behavior
05865 ** is undefined if the mutex is not currently entered by the
05866 ** calling thread or is not currently allocated.  SQLite will
05867 ** never do either.)^
05868 **
05869 ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
05870 ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
05871 ** behave as no-ops.
05872 **
05873 ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
05874 */
05875 SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
05876 SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
05877 SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
05878 SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
05879 SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
05880 
05881 /*
05882 ** CAPI3REF: Mutex Methods Object
05883 **
05884 ** An instance of this structure defines the low-level routines
05885 ** used to allocate and use mutexes.
05886 **
05887 ** Usually, the default mutex implementations provided by SQLite are
05888 ** sufficient, however the user has the option of substituting a custom
05889 ** implementation for specialized deployments or systems for which SQLite
05890 ** does not provide a suitable implementation. In this case, the user
05891 ** creates and populates an instance of this structure to pass
05892 ** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
05893 ** Additionally, an instance of this structure can be used as an
05894 ** output variable when querying the system for the current mutex
05895 ** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
05896 **
05897 ** ^The xMutexInit method defined by this structure is invoked as
05898 ** part of system initialization by the sqlite3_initialize() function.
05899 ** ^The xMutexInit routine is called by SQLite exactly once for each
05900 ** effective call to [sqlite3_initialize()].
05901 **
05902 ** ^The xMutexEnd method defined by this structure is invoked as
05903 ** part of system shutdown by the sqlite3_shutdown() function. The
05904 ** implementation of this method is expected to release all outstanding
05905 ** resources obtained by the mutex methods implementation, especially
05906 ** those obtained by the xMutexInit method.  ^The xMutexEnd()
05907 ** interface is invoked exactly once for each call to [sqlite3_shutdown()].
05908 **
05909 ** ^(The remaining seven methods defined by this structure (xMutexAlloc,
05910 ** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
05911 ** xMutexNotheld) implement the following interfaces (respectively):
05912 **
05913 ** <ul>
05914 **   <li>  [sqlite3_mutex_alloc()] </li>
05915 **   <li>  [sqlite3_mutex_free()] </li>
05916 **   <li>  [sqlite3_mutex_enter()] </li>
05917 **   <li>  [sqlite3_mutex_try()] </li>
05918 **   <li>  [sqlite3_mutex_leave()] </li>
05919 **   <li>  [sqlite3_mutex_held()] </li>
05920 **   <li>  [sqlite3_mutex_notheld()] </li>
05921 ** </ul>)^
05922 **
05923 ** The only difference is that the public sqlite3_XXX functions enumerated
05924 ** above silently ignore any invocations that pass a NULL pointer instead
05925 ** of a valid mutex handle. The implementations of the methods defined
05926 ** by this structure are not required to handle this case, the results
05927 ** of passing a NULL pointer instead of a valid mutex handle are undefined
05928 ** (i.e. it is acceptable to provide an implementation that segfaults if
05929 ** it is passed a NULL pointer).
05930 **
05931 ** The xMutexInit() method must be threadsafe.  ^It must be harmless to
05932 ** invoke xMutexInit() multiple times within the same process and without
05933 ** intervening calls to xMutexEnd().  Second and subsequent calls to
05934 ** xMutexInit() must be no-ops.
05935 **
05936 ** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
05937 ** and its associates).  ^Similarly, xMutexAlloc() must not use SQLite memory
05938 ** allocation for a static mutex.  ^However xMutexAlloc() may use SQLite
05939 ** memory allocation for a fast or recursive mutex.
05940 **
05941 ** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
05942 ** called, but only if the prior call to xMutexInit returned SQLITE_OK.
05943 ** If xMutexInit fails in any way, it is expected to clean up after itself
05944 ** prior to returning.
05945 */
05946 typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
05947 struct sqlite3_mutex_methods {
05948   int (*xMutexInit)(void);
05949   int (*xMutexEnd)(void);
05950   sqlite3_mutex *(*xMutexAlloc)(int);
05951   void (*xMutexFree)(sqlite3_mutex *);
05952   void (*xMutexEnter)(sqlite3_mutex *);
05953   int (*xMutexTry)(sqlite3_mutex *);
05954   void (*xMutexLeave)(sqlite3_mutex *);
05955   int (*xMutexHeld)(sqlite3_mutex *);
05956   int (*xMutexNotheld)(sqlite3_mutex *);
05957 };
05958 
05959 /*
05960 ** CAPI3REF: Mutex Verification Routines
05961 **
05962 ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
05963 ** are intended for use inside assert() statements.  ^The SQLite core
05964 ** never uses these routines except inside an assert() and applications
05965 ** are advised to follow the lead of the core.  ^The SQLite core only
05966 ** provides implementations for these routines when it is compiled
05967 ** with the SQLITE_DEBUG flag.  ^External mutex implementations
05968 ** are only required to provide these routines if SQLITE_DEBUG is
05969 ** defined and if NDEBUG is not defined.
05970 **
05971 ** ^These routines should return true if the mutex in their argument
05972 ** is held or not held, respectively, by the calling thread.
05973 **
05974 ** ^The implementation is not required to provide versions of these
05975 ** routines that actually work. If the implementation does not provide working
05976 ** versions of these routines, it should at least provide stubs that always
05977 ** return true so that one does not get spurious assertion failures.
05978 **
05979 ** ^If the argument to sqlite3_mutex_held() is a NULL pointer then
05980 ** the routine should return 1.   This seems counter-intuitive since
05981 ** clearly the mutex cannot be held if it does not exist.  But
05982 ** the reason the mutex does not exist is because the build is not
05983 ** using mutexes.  And we do not want the assert() containing the
05984 ** call to sqlite3_mutex_held() to fail, so a non-zero return is
05985 ** the appropriate thing to do.  ^The sqlite3_mutex_notheld()
05986 ** interface should also return 1 when given a NULL pointer.
05987 */
05988 #ifndef NDEBUG
05989 SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
05990 SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
05991 #endif
05992 
05993 /*
05994 ** CAPI3REF: Mutex Types
05995 **
05996 ** The [sqlite3_mutex_alloc()] interface takes a single argument
05997 ** which is one of these integer constants.
05998 **
05999 ** The set of static mutexes may change from one SQLite release to the
06000 ** next.  Applications that override the built-in mutex logic must be
06001 ** prepared to accommodate additional static mutexes.
06002 */
06003 #define SQLITE_MUTEX_FAST             0
06004 #define SQLITE_MUTEX_RECURSIVE        1
06005 #define SQLITE_MUTEX_STATIC_MASTER    2
06006 #define SQLITE_MUTEX_STATIC_MEM       3  /* sqlite3_malloc() */
06007 #define SQLITE_MUTEX_STATIC_MEM2      4  /* NOT USED */
06008 #define SQLITE_MUTEX_STATIC_OPEN      4  /* sqlite3BtreeOpen() */
06009 #define SQLITE_MUTEX_STATIC_PRNG      5  /* sqlite3_random() */
06010 #define SQLITE_MUTEX_STATIC_LRU       6  /* lru page list */
06011 #define SQLITE_MUTEX_STATIC_LRU2      7  /* NOT USED */
06012 #define SQLITE_MUTEX_STATIC_PMEM      7  /* sqlite3PageMalloc() */
06013 
06014 /*
06015 ** CAPI3REF: Retrieve the mutex for a database connection
06016 **
06017 ** ^This interface returns a pointer the [sqlite3_mutex] object that 
06018 ** serializes access to the [database connection] given in the argument
06019 ** when the [threading mode] is Serialized.
06020 ** ^If the [threading mode] is Single-thread or Multi-thread then this
06021 ** routine returns a NULL pointer.
06022 */
06023 SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
06024 
06025 /*
06026 ** CAPI3REF: Low-Level Control Of Database Files
06027 **
06028 ** ^The [sqlite3_file_control()] interface makes a direct call to the
06029 ** xFileControl method for the [sqlite3_io_methods] object associated
06030 ** with a particular database identified by the second argument. ^The
06031 ** name of the database is "main" for the main database or "temp" for the
06032 ** TEMP database, or the name that appears after the AS keyword for
06033 ** databases that are added using the [ATTACH] SQL command.
06034 ** ^A NULL pointer can be used in place of "main" to refer to the
06035 ** main database file.
06036 ** ^The third and fourth parameters to this routine
06037 ** are passed directly through to the second and third parameters of
06038 ** the xFileControl method.  ^The return value of the xFileControl
06039 ** method becomes the return value of this routine.
06040 **
06041 ** ^The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes
06042 ** a pointer to the underlying [sqlite3_file] object to be written into
06043 ** the space pointed to by the 4th parameter.  ^The SQLITE_FCNTL_FILE_POINTER
06044 ** case is a short-circuit path which does not actually invoke the
06045 ** underlying sqlite3_io_methods.xFileControl method.
06046 **
06047 ** ^If the second parameter (zDbName) does not match the name of any
06048 ** open database file, then SQLITE_ERROR is returned.  ^This error
06049 ** code is not remembered and will not be recalled by [sqlite3_errcode()]
06050 ** or [sqlite3_errmsg()].  The underlying xFileControl method might
06051 ** also return SQLITE_ERROR.  There is no way to distinguish between
06052 ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
06053 ** xFileControl method.
06054 **
06055 ** See also: [SQLITE_FCNTL_LOCKSTATE]
06056 */
06057 SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
06058 
06059 /*
06060 ** CAPI3REF: Testing Interface
06061 **
06062 ** ^The sqlite3_test_control() interface is used to read out internal
06063 ** state of SQLite and to inject faults into SQLite for testing
06064 ** purposes.  ^The first parameter is an operation code that determines
06065 ** the number, meaning, and operation of all subsequent parameters.
06066 **
06067 ** This interface is not for use by applications.  It exists solely
06068 ** for verifying the correct operation of the SQLite library.  Depending
06069 ** on how the SQLite library is compiled, this interface might not exist.
06070 **
06071 ** The details of the operation codes, their meanings, the parameters
06072 ** they take, and what they do are all subject to change without notice.
06073 ** Unlike most of the SQLite API, this function is not guaranteed to
06074 ** operate consistently from one release to the next.
06075 */
06076 SQLITE_API int sqlite3_test_control(int op, ...);
06077 
06078 /*
06079 ** CAPI3REF: Testing Interface Operation Codes
06080 **
06081 ** These constants are the valid operation code parameters used
06082 ** as the first argument to [sqlite3_test_control()].
06083 **
06084 ** These parameters and their meanings are subject to change
06085 ** without notice.  These values are for testing purposes only.
06086 ** Applications should not use any of these parameters or the
06087 ** [sqlite3_test_control()] interface.
06088 */
06089 #define SQLITE_TESTCTRL_FIRST                    5
06090 #define SQLITE_TESTCTRL_PRNG_SAVE                5
06091 #define SQLITE_TESTCTRL_PRNG_RESTORE             6
06092 #define SQLITE_TESTCTRL_PRNG_RESET               7
06093 #define SQLITE_TESTCTRL_BITVEC_TEST              8
06094 #define SQLITE_TESTCTRL_FAULT_INSTALL            9
06095 #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     10
06096 #define SQLITE_TESTCTRL_PENDING_BYTE            11
06097 #define SQLITE_TESTCTRL_ASSERT                  12
06098 #define SQLITE_TESTCTRL_ALWAYS                  13
06099 #define SQLITE_TESTCTRL_RESERVE                 14
06100 #define SQLITE_TESTCTRL_OPTIMIZATIONS           15
06101 #define SQLITE_TESTCTRL_ISKEYWORD               16
06102 #define SQLITE_TESTCTRL_SCRATCHMALLOC           17
06103 #define SQLITE_TESTCTRL_LOCALTIME_FAULT         18
06104 #define SQLITE_TESTCTRL_EXPLAIN_STMT            19
06105 #define SQLITE_TESTCTRL_NEVER_CORRUPT           20
06106 #define SQLITE_TESTCTRL_LAST                    20
06107 
06108 /*
06109 ** CAPI3REF: SQLite Runtime Status
06110 **
06111 ** ^This interface is used to retrieve runtime status information
06112 ** about the performance of SQLite, and optionally to reset various
06113 ** highwater marks.  ^The first argument is an integer code for
06114 ** the specific parameter to measure.  ^(Recognized integer codes
06115 ** are of the form [status parameters | SQLITE_STATUS_...].)^
06116 ** ^The current value of the parameter is returned into *pCurrent.
06117 ** ^The highest recorded value is returned in *pHighwater.  ^If the
06118 ** resetFlag is true, then the highest record value is reset after
06119 ** *pHighwater is written.  ^(Some parameters do not record the highest
06120 ** value.  For those parameters
06121 ** nothing is written into *pHighwater and the resetFlag is ignored.)^
06122 ** ^(Other parameters record only the highwater mark and not the current
06123 ** value.  For these latter parameters nothing is written into *pCurrent.)^
06124 **
06125 ** ^The sqlite3_status() routine returns SQLITE_OK on success and a
06126 ** non-zero [error code] on failure.
06127 **
06128 ** This routine is threadsafe but is not atomic.  This routine can be
06129 ** called while other threads are running the same or different SQLite
06130 ** interfaces.  However the values returned in *pCurrent and
06131 ** *pHighwater reflect the status of SQLite at different points in time
06132 ** and it is possible that another thread might change the parameter
06133 ** in between the times when *pCurrent and *pHighwater are written.
06134 **
06135 ** See also: [sqlite3_db_status()]
06136 */
06137 SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
06138 
06139 
06140 /*
06141 ** CAPI3REF: Status Parameters
06142 ** KEYWORDS: {status parameters}
06143 **
06144 ** These integer constants designate various run-time status parameters
06145 ** that can be returned by [sqlite3_status()].
06146 **
06147 ** <dl>
06148 ** [[SQLITE_STATUS_MEMORY_USED]] ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>
06149 ** <dd>This parameter is the current amount of memory checked out
06150 ** using [sqlite3_malloc()], either directly or indirectly.  The
06151 ** figure includes calls made to [sqlite3_malloc()] by the application
06152 ** and internal memory usage by the SQLite library.  Scratch memory
06153 ** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
06154 ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
06155 ** this parameter.  The amount returned is the sum of the allocation
06156 ** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
06157 **
06158 ** [[SQLITE_STATUS_MALLOC_SIZE]] ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
06159 ** <dd>This parameter records the largest memory allocation request
06160 ** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
06161 ** internal equivalents).  Only the value returned in the
06162 ** *pHighwater parameter to [sqlite3_status()] is of interest.  
06163 ** The value written into the *pCurrent parameter is undefined.</dd>)^
06164 **
06165 ** [[SQLITE_STATUS_MALLOC_COUNT]] ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt>
06166 ** <dd>This parameter records the number of separate memory allocations
06167 ** currently checked out.</dd>)^
06168 **
06169 ** [[SQLITE_STATUS_PAGECACHE_USED]] ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
06170 ** <dd>This parameter returns the number of pages used out of the
06171 ** [pagecache memory allocator] that was configured using 
06172 ** [SQLITE_CONFIG_PAGECACHE].  The
06173 ** value returned is in pages, not in bytes.</dd>)^
06174 **
06175 ** [[SQLITE_STATUS_PAGECACHE_OVERFLOW]] 
06176 ** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
06177 ** <dd>This parameter returns the number of bytes of page cache
06178 ** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE]
06179 ** buffer and where forced to overflow to [sqlite3_malloc()].  The
06180 ** returned value includes allocations that overflowed because they
06181 ** where too large (they were larger than the "sz" parameter to
06182 ** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
06183 ** no space was left in the page cache.</dd>)^
06184 **
06185 ** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
06186 ** <dd>This parameter records the largest memory allocation request
06187 ** handed to [pagecache memory allocator].  Only the value returned in the
06188 ** *pHighwater parameter to [sqlite3_status()] is of interest.  
06189 ** The value written into the *pCurrent parameter is undefined.</dd>)^
06190 **
06191 ** [[SQLITE_STATUS_SCRATCH_USED]] ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt>
06192 ** <dd>This parameter returns the number of allocations used out of the
06193 ** [scratch memory allocator] configured using
06194 ** [SQLITE_CONFIG_SCRATCH].  The value returned is in allocations, not
06195 ** in bytes.  Since a single thread may only have one scratch allocation
06196 ** outstanding at time, this parameter also reports the number of threads
06197 ** using scratch memory at the same time.</dd>)^
06198 **
06199 ** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
06200 ** <dd>This parameter returns the number of bytes of scratch memory
06201 ** allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH]
06202 ** buffer and where forced to overflow to [sqlite3_malloc()].  The values
06203 ** returned include overflows because the requested allocation was too
06204 ** larger (that is, because the requested allocation was larger than the
06205 ** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
06206 ** slots were available.
06207 ** </dd>)^
06208 **
06209 ** [[SQLITE_STATUS_SCRATCH_SIZE]] ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
06210 ** <dd>This parameter records the largest memory allocation request
06211 ** handed to [scratch memory allocator].  Only the value returned in the
06212 ** *pHighwater parameter to [sqlite3_status()] is of interest.  
06213 ** The value written into the *pCurrent parameter is undefined.</dd>)^
06214 **
06215 ** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
06216 ** <dd>This parameter records the deepest parser stack.  It is only
06217 ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
06218 ** </dl>
06219 **
06220 ** New status parameters may be added from time to time.
06221 */
06222 #define SQLITE_STATUS_MEMORY_USED          0
06223 #define SQLITE_STATUS_PAGECACHE_USED       1
06224 #define SQLITE_STATUS_PAGECACHE_OVERFLOW   2
06225 #define SQLITE_STATUS_SCRATCH_USED         3
06226 #define SQLITE_STATUS_SCRATCH_OVERFLOW     4
06227 #define SQLITE_STATUS_MALLOC_SIZE          5
06228 #define SQLITE_STATUS_PARSER_STACK         6
06229 #define SQLITE_STATUS_PAGECACHE_SIZE       7
06230 #define SQLITE_STATUS_SCRATCH_SIZE         8
06231 #define SQLITE_STATUS_MALLOC_COUNT         9
06232 
06233 /*
06234 ** CAPI3REF: Database Connection Status
06235 **
06236 ** ^This interface is used to retrieve runtime status information 
06237 ** about a single [database connection].  ^The first argument is the
06238 ** database connection object to be interrogated.  ^The second argument
06239 ** is an integer constant, taken from the set of
06240 ** [SQLITE_DBSTATUS options], that
06241 ** determines the parameter to interrogate.  The set of 
06242 ** [SQLITE_DBSTATUS options] is likely
06243 ** to grow in future releases of SQLite.
06244 **
06245 ** ^The current value of the requested parameter is written into *pCur
06246 ** and the highest instantaneous value is written into *pHiwtr.  ^If
06247 ** the resetFlg is true, then the highest instantaneous value is
06248 ** reset back down to the current value.
06249 **
06250 ** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
06251 ** non-zero [error code] on failure.
06252 **
06253 ** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
06254 */
06255 SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
06256 
06257 /*
06258 ** CAPI3REF: Status Parameters for database connections
06259 ** KEYWORDS: {SQLITE_DBSTATUS options}
06260 **
06261 ** These constants are the available integer "verbs" that can be passed as
06262 ** the second argument to the [sqlite3_db_status()] interface.
06263 **
06264 ** New verbs may be added in future releases of SQLite. Existing verbs
06265 ** might be discontinued. Applications should check the return code from
06266 ** [sqlite3_db_status()] to make sure that the call worked.
06267 ** The [sqlite3_db_status()] interface will return a non-zero error code
06268 ** if a discontinued or unsupported verb is invoked.
06269 **
06270 ** <dl>
06271 ** [[SQLITE_DBSTATUS_LOOKASIDE_USED]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
06272 ** <dd>This parameter returns the number of lookaside memory slots currently
06273 ** checked out.</dd>)^
06274 **
06275 ** [[SQLITE_DBSTATUS_LOOKASIDE_HIT]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>
06276 ** <dd>This parameter returns the number malloc attempts that were 
06277 ** satisfied using lookaside memory. Only the high-water value is meaningful;
06278 ** the current value is always zero.)^
06279 **
06280 ** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE]]
06281 ** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>
06282 ** <dd>This parameter returns the number malloc attempts that might have
06283 ** been satisfied using lookaside memory but failed due to the amount of
06284 ** memory requested being larger than the lookaside slot size.
06285 ** Only the high-water value is meaningful;
06286 ** the current value is always zero.)^
06287 **
06288 ** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL]]
06289 ** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>
06290 ** <dd>This parameter returns the number malloc attempts that might have
06291 ** been satisfied using lookaside memory but failed due to all lookaside
06292 ** memory already being in use.
06293 ** Only the high-water value is meaningful;
06294 ** the current value is always zero.)^
06295 **
06296 ** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt>
06297 ** <dd>This parameter returns the approximate number of of bytes of heap
06298 ** memory used by all pager caches associated with the database connection.)^
06299 ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
06300 **
06301 ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
06302 ** <dd>This parameter returns the approximate number of of bytes of heap
06303 ** memory used to store the schema for all databases associated
06304 ** with the connection - main, temp, and any [ATTACH]-ed databases.)^ 
06305 ** ^The full amount of memory used by the schemas is reported, even if the
06306 ** schema memory is shared with other database connections due to
06307 ** [shared cache mode] being enabled.
06308 ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
06309 **
06310 ** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt>
06311 ** <dd>This parameter returns the approximate number of of bytes of heap
06312 ** and lookaside memory used by all prepared statements associated with
06313 ** the database connection.)^
06314 ** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
06315 ** </dd>
06316 **
06317 ** [[SQLITE_DBSTATUS_CACHE_HIT]] ^(<dt>SQLITE_DBSTATUS_CACHE_HIT</dt>
06318 ** <dd>This parameter returns the number of pager cache hits that have
06319 ** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT 
06320 ** is always 0.
06321 ** </dd>
06322 **
06323 ** [[SQLITE_DBSTATUS_CACHE_MISS]] ^(<dt>SQLITE_DBSTATUS_CACHE_MISS</dt>
06324 ** <dd>This parameter returns the number of pager cache misses that have
06325 ** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS 
06326 ** is always 0.
06327 ** </dd>
06328 **
06329 ** [[SQLITE_DBSTATUS_CACHE_WRITE]] ^(<dt>SQLITE_DBSTATUS_CACHE_WRITE</dt>
06330 ** <dd>This parameter returns the number of dirty cache entries that have
06331 ** been written to disk. Specifically, the number of pages written to the
06332 ** wal file in wal mode databases, or the number of pages written to the
06333 ** database file in rollback mode databases. Any pages written as part of
06334 ** transaction rollback or database recovery operations are not included.
06335 ** If an IO or other error occurs while writing a page to disk, the effect
06336 ** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The
06337 ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
06338 ** </dd>
06339 **
06340 ** [[SQLITE_DBSTATUS_DEFERRED_FKS]] ^(<dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt>
06341 ** <dd>This parameter returns zero for the current value if and only if
06342 ** all foreign key constraints (deferred or immediate) have been
06343 ** resolved.)^  ^The highwater mark is always 0.
06344 ** </dd>
06345 ** </dl>
06346 */
06347 #define SQLITE_DBSTATUS_LOOKASIDE_USED       0
06348 #define SQLITE_DBSTATUS_CACHE_USED           1
06349 #define SQLITE_DBSTATUS_SCHEMA_USED          2
06350 #define SQLITE_DBSTATUS_STMT_USED            3
06351 #define SQLITE_DBSTATUS_LOOKASIDE_HIT        4
06352 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE  5
06353 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL  6
06354 #define SQLITE_DBSTATUS_CACHE_HIT            7
06355 #define SQLITE_DBSTATUS_CACHE_MISS           8
06356 #define SQLITE_DBSTATUS_CACHE_WRITE          9
06357 #define SQLITE_DBSTATUS_DEFERRED_FKS        10
06358 #define SQLITE_DBSTATUS_MAX                 10   /* Largest defined DBSTATUS */
06359 
06360 
06361 /*
06362 ** CAPI3REF: Prepared Statement Status
06363 **
06364 ** ^(Each prepared statement maintains various
06365 ** [SQLITE_STMTSTATUS counters] that measure the number
06366 ** of times it has performed specific operations.)^  These counters can
06367 ** be used to monitor the performance characteristics of the prepared
06368 ** statements.  For example, if the number of table steps greatly exceeds
06369 ** the number of table searches or result rows, that would tend to indicate
06370 ** that the prepared statement is using a full table scan rather than
06371 ** an index.  
06372 **
06373 ** ^(This interface is used to retrieve and reset counter values from
06374 ** a [prepared statement].  The first argument is the prepared statement
06375 ** object to be interrogated.  The second argument
06376 ** is an integer code for a specific [SQLITE_STMTSTATUS counter]
06377 ** to be interrogated.)^
06378 ** ^The current value of the requested counter is returned.
06379 ** ^If the resetFlg is true, then the counter is reset to zero after this
06380 ** interface call returns.
06381 **
06382 ** See also: [sqlite3_status()] and [sqlite3_db_status()].
06383 */
06384 SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
06385 
06386 /*
06387 ** CAPI3REF: Status Parameters for prepared statements
06388 ** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters}
06389 **
06390 ** These preprocessor macros define integer codes that name counter
06391 ** values associated with the [sqlite3_stmt_status()] interface.
06392 ** The meanings of the various counters are as follows:
06393 **
06394 ** <dl>
06395 ** [[SQLITE_STMTSTATUS_FULLSCAN_STEP]] <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
06396 ** <dd>^This is the number of times that SQLite has stepped forward in
06397 ** a table as part of a full table scan.  Large numbers for this counter
06398 ** may indicate opportunities for performance improvement through 
06399 ** careful use of indices.</dd>
06400 **
06401 ** [[SQLITE_STMTSTATUS_SORT]] <dt>SQLITE_STMTSTATUS_SORT</dt>
06402 ** <dd>^This is the number of sort operations that have occurred.
06403 ** A non-zero value in this counter may indicate an opportunity to
06404 ** improvement performance through careful use of indices.</dd>
06405 **
06406 ** [[SQLITE_STMTSTATUS_AUTOINDEX]] <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>
06407 ** <dd>^This is the number of rows inserted into transient indices that
06408 ** were created automatically in order to help joins run faster.
06409 ** A non-zero value in this counter may indicate an opportunity to
06410 ** improvement performance by adding permanent indices that do not
06411 ** need to be reinitialized each time the statement is run.</dd>
06412 **
06413 ** [[SQLITE_STMTSTATUS_VM_STEP]] <dt>SQLITE_STMTSTATUS_VM_STEP</dt>
06414 ** <dd>^This is the number of virtual machine operations executed
06415 ** by the prepared statement if that number is less than or equal
06416 ** to 2147483647.  The number of virtual machine operations can be 
06417 ** used as a proxy for the total work done by the prepared statement.
06418 ** If the number of virtual machine operations exceeds 2147483647
06419 ** then the value returned by this statement status code is undefined.
06420 ** </dd>
06421 ** </dl>
06422 */
06423 #define SQLITE_STMTSTATUS_FULLSCAN_STEP     1
06424 #define SQLITE_STMTSTATUS_SORT              2
06425 #define SQLITE_STMTSTATUS_AUTOINDEX         3
06426 #define SQLITE_STMTSTATUS_VM_STEP           4
06427 
06428 /*
06429 ** CAPI3REF: Custom Page Cache Object
06430 **
06431 ** The sqlite3_pcache type is opaque.  It is implemented by
06432 ** the pluggable module.  The SQLite core has no knowledge of
06433 ** its size or internal structure and never deals with the
06434 ** sqlite3_pcache object except by holding and passing pointers
06435 ** to the object.
06436 **
06437 ** See [sqlite3_pcache_methods2] for additional information.
06438 */
06439 typedef struct sqlite3_pcache sqlite3_pcache;
06440 
06441 /*
06442 ** CAPI3REF: Custom Page Cache Object
06443 **
06444 ** The sqlite3_pcache_page object represents a single page in the
06445 ** page cache.  The page cache will allocate instances of this
06446 ** object.  Various methods of the page cache use pointers to instances
06447 ** of this object as parameters or as their return value.
06448 **
06449 ** See [sqlite3_pcache_methods2] for additional information.
06450 */
06451 typedef struct sqlite3_pcache_page sqlite3_pcache_page;
06452 struct sqlite3_pcache_page {
06453   void *pBuf;        /* The content of the page */
06454   void *pExtra;      /* Extra information associated with the page */
06455 };
06456 
06457 /*
06458 ** CAPI3REF: Application Defined Page Cache.
06459 ** KEYWORDS: {page cache}
06460 **
06461 ** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE2], ...) interface can
06462 ** register an alternative page cache implementation by passing in an 
06463 ** instance of the sqlite3_pcache_methods2 structure.)^
06464 ** In many applications, most of the heap memory allocated by 
06465 ** SQLite is used for the page cache.
06466 ** By implementing a 
06467 ** custom page cache using this API, an application can better control
06468 ** the amount of memory consumed by SQLite, the way in which 
06469 ** that memory is allocated and released, and the policies used to 
06470 ** determine exactly which parts of a database file are cached and for 
06471 ** how long.
06472 **
06473 ** The alternative page cache mechanism is an
06474 ** extreme measure that is only needed by the most demanding applications.
06475 ** The built-in page cache is recommended for most uses.
06476 **
06477 ** ^(The contents of the sqlite3_pcache_methods2 structure are copied to an
06478 ** internal buffer by SQLite within the call to [sqlite3_config].  Hence
06479 ** the application may discard the parameter after the call to
06480 ** [sqlite3_config()] returns.)^
06481 **
06482 ** [[the xInit() page cache method]]
06483 ** ^(The xInit() method is called once for each effective 
06484 ** call to [sqlite3_initialize()])^
06485 ** (usually only once during the lifetime of the process). ^(The xInit()
06486 ** method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^
06487 ** The intent of the xInit() method is to set up global data structures 
06488 ** required by the custom page cache implementation. 
06489 ** ^(If the xInit() method is NULL, then the 
06490 ** built-in default page cache is used instead of the application defined
06491 ** page cache.)^
06492 **
06493 ** [[the xShutdown() page cache method]]
06494 ** ^The xShutdown() method is called by [sqlite3_shutdown()].
06495 ** It can be used to clean up 
06496 ** any outstanding resources before process shutdown, if required.
06497 ** ^The xShutdown() method may be NULL.
06498 **
06499 ** ^SQLite automatically serializes calls to the xInit method,
06500 ** so the xInit method need not be threadsafe.  ^The
06501 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
06502 ** not need to be threadsafe either.  All other methods must be threadsafe
06503 ** in multithreaded applications.
06504 **
06505 ** ^SQLite will never invoke xInit() more than once without an intervening
06506 ** call to xShutdown().
06507 **
06508 ** [[the xCreate() page cache methods]]
06509 ** ^SQLite invokes the xCreate() method to construct a new cache instance.
06510 ** SQLite will typically create one cache instance for each open database file,
06511 ** though this is not guaranteed. ^The
06512 ** first parameter, szPage, is the size in bytes of the pages that must
06513 ** be allocated by the cache.  ^szPage will always a power of two.  ^The
06514 ** second parameter szExtra is a number of bytes of extra storage 
06515 ** associated with each page cache entry.  ^The szExtra parameter will
06516 ** a number less than 250.  SQLite will use the
06517 ** extra szExtra bytes on each page to store metadata about the underlying
06518 ** database page on disk.  The value passed into szExtra depends
06519 ** on the SQLite version, the target platform, and how SQLite was compiled.
06520 ** ^The third argument to xCreate(), bPurgeable, is true if the cache being
06521 ** created will be used to cache database pages of a file stored on disk, or
06522 ** false if it is used for an in-memory database. The cache implementation
06523 ** does not have to do anything special based with the value of bPurgeable;
06524 ** it is purely advisory.  ^On a cache where bPurgeable is false, SQLite will
06525 ** never invoke xUnpin() except to deliberately delete a page.
06526 ** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
06527 ** false will always have the "discard" flag set to true.  
06528 ** ^Hence, a cache created with bPurgeable false will
06529 ** never contain any unpinned pages.
06530 **
06531 ** [[the xCachesize() page cache method]]
06532 ** ^(The xCachesize() method may be called at any time by SQLite to set the
06533 ** suggested maximum cache-size (number of pages stored by) the cache
06534 ** instance passed as the first argument. This is the value configured using
06535 ** the SQLite "[PRAGMA cache_size]" command.)^  As with the bPurgeable
06536 ** parameter, the implementation is not required to do anything with this
06537 ** value; it is advisory only.
06538 **
06539 ** [[the xPagecount() page cache methods]]
06540 ** The xPagecount() method must return the number of pages currently
06541 ** stored in the cache, both pinned and unpinned.
06542 ** 
06543 ** [[the xFetch() page cache methods]]
06544 ** The xFetch() method locates a page in the cache and returns a pointer to 
06545 ** an sqlite3_pcache_page object associated with that page, or a NULL pointer.
06546 ** The pBuf element of the returned sqlite3_pcache_page object will be a
06547 ** pointer to a buffer of szPage bytes used to store the content of a 
06548 ** single database page.  The pExtra element of sqlite3_pcache_page will be
06549 ** a pointer to the szExtra bytes of extra storage that SQLite has requested
06550 ** for each entry in the page cache.
06551 **
06552 ** The page to be fetched is determined by the key. ^The minimum key value
06553 ** is 1.  After it has been retrieved using xFetch, the page is considered
06554 ** to be "pinned".
06555 **
06556 ** If the requested page is already in the page cache, then the page cache
06557 ** implementation must return a pointer to the page buffer with its content
06558 ** intact.  If the requested page is not already in the cache, then the
06559 ** cache implementation should use the value of the createFlag
06560 ** parameter to help it determined what action to take:
06561 **
06562 ** <table border=1 width=85% align=center>
06563 ** <tr><th> createFlag <th> Behavior when page is not already in cache
06564 ** <tr><td> 0 <td> Do not allocate a new page.  Return NULL.
06565 ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
06566 **                 Otherwise return NULL.
06567 ** <tr><td> 2 <td> Make every effort to allocate a new page.  Only return
06568 **                 NULL if allocating a new page is effectively impossible.
06569 ** </table>
06570 **
06571 ** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1.  SQLite
06572 ** will only use a createFlag of 2 after a prior call with a createFlag of 1
06573 ** failed.)^  In between the to xFetch() calls, SQLite may
06574 ** attempt to unpin one or more cache pages by spilling the content of
06575 ** pinned pages to disk and synching the operating system disk cache.
06576 **
06577 ** [[the xUnpin() page cache method]]
06578 ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
06579 ** as its second argument.  If the third parameter, discard, is non-zero,
06580 ** then the page must be evicted from the cache.
06581 ** ^If the discard parameter is
06582 ** zero, then the page may be discarded or retained at the discretion of
06583 ** page cache implementation. ^The page cache implementation
06584 ** may choose to evict unpinned pages at any time.
06585 **
06586 ** The cache must not perform any reference counting. A single 
06587 ** call to xUnpin() unpins the page regardless of the number of prior calls 
06588 ** to xFetch().
06589 **
06590 ** [[the xRekey() page cache methods]]
06591 ** The xRekey() method is used to change the key value associated with the
06592 ** page passed as the second argument. If the cache
06593 ** previously contains an entry associated with newKey, it must be
06594 ** discarded. ^Any prior cache entry associated with newKey is guaranteed not
06595 ** to be pinned.
06596 **
06597 ** When SQLite calls the xTruncate() method, the cache must discard all
06598 ** existing cache entries with page numbers (keys) greater than or equal
06599 ** to the value of the iLimit parameter passed to xTruncate(). If any
06600 ** of these pages are pinned, they are implicitly unpinned, meaning that
06601 ** they can be safely discarded.
06602 **
06603 ** [[the xDestroy() page cache method]]
06604 ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
06605 ** All resources associated with the specified cache should be freed. ^After
06606 ** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
06607 ** handle invalid, and will not use it with any other sqlite3_pcache_methods2
06608 ** functions.
06609 **
06610 ** [[the xShrink() page cache method]]
06611 ** ^SQLite invokes the xShrink() method when it wants the page cache to
06612 ** free up as much of heap memory as possible.  The page cache implementation
06613 ** is not obligated to free any memory, but well-behaved implementations should
06614 ** do their best.
06615 */
06616 typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
06617 struct sqlite3_pcache_methods2 {
06618   int iVersion;
06619   void *pArg;
06620   int (*xInit)(void*);
06621   void (*xShutdown)(void*);
06622   sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
06623   void (*xCachesize)(sqlite3_pcache*, int nCachesize);
06624   int (*xPagecount)(sqlite3_pcache*);
06625   sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
06626   void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
06627   void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*, 
06628       unsigned oldKey, unsigned newKey);
06629   void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
06630   void (*xDestroy)(sqlite3_pcache*);
06631   void (*xShrink)(sqlite3_pcache*);
06632 };
06633 
06634 /*
06635 ** This is the obsolete pcache_methods object that has now been replaced
06636 ** by sqlite3_pcache_methods2.  This object is not used by SQLite.  It is
06637 ** retained in the header file for backwards compatibility only.
06638 */
06639 typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
06640 struct sqlite3_pcache_methods {
06641   void *pArg;
06642   int (*xInit)(void*);
06643   void (*xShutdown)(void*);
06644   sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
06645   void (*xCachesize)(sqlite3_pcache*, int nCachesize);
06646   int (*xPagecount)(sqlite3_pcache*);
06647   void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
06648   void (*xUnpin)(sqlite3_pcache*, void*, int discard);
06649   void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
06650   void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
06651   void (*xDestroy)(sqlite3_pcache*);
06652 };
06653 
06654 
06655 /*
06656 ** CAPI3REF: Online Backup Object
06657 **
06658 ** The sqlite3_backup object records state information about an ongoing
06659 ** online backup operation.  ^The sqlite3_backup object is created by
06660 ** a call to [sqlite3_backup_init()] and is destroyed by a call to
06661 ** [sqlite3_backup_finish()].
06662 **
06663 ** See Also: [Using the SQLite Online Backup API]
06664 */
06665 typedef struct sqlite3_backup sqlite3_backup;
06666 
06667 /*
06668 ** CAPI3REF: Online Backup API.
06669 **
06670 ** The backup API copies the content of one database into another.
06671 ** It is useful either for creating backups of databases or
06672 ** for copying in-memory databases to or from persistent files. 
06673 **
06674 ** See Also: [Using the SQLite Online Backup API]
06675 **
06676 ** ^SQLite holds a write transaction open on the destination database file
06677 ** for the duration of the backup operation.
06678 ** ^The source database is read-locked only while it is being read;
06679 ** it is not locked continuously for the entire backup operation.
06680 ** ^Thus, the backup may be performed on a live source database without
06681 ** preventing other database connections from
06682 ** reading or writing to the source database while the backup is underway.
06683 ** 
06684 ** ^(To perform a backup operation: 
06685 **   <ol>
06686 **     <li><b>sqlite3_backup_init()</b> is called once to initialize the
06687 **         backup, 
06688 **     <li><b>sqlite3_backup_step()</b> is called one or more times to transfer 
06689 **         the data between the two databases, and finally
06690 **     <li><b>sqlite3_backup_finish()</b> is called to release all resources 
06691 **         associated with the backup operation. 
06692 **   </ol>)^
06693 ** There should be exactly one call to sqlite3_backup_finish() for each
06694 ** successful call to sqlite3_backup_init().
06695 **
06696 ** [[sqlite3_backup_init()]] <b>sqlite3_backup_init()</b>
06697 **
06698 ** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the 
06699 ** [database connection] associated with the destination database 
06700 ** and the database name, respectively.
06701 ** ^The database name is "main" for the main database, "temp" for the
06702 ** temporary database, or the name specified after the AS keyword in
06703 ** an [ATTACH] statement for an attached database.
06704 ** ^The S and M arguments passed to 
06705 ** sqlite3_backup_init(D,N,S,M) identify the [database connection]
06706 ** and database name of the source database, respectively.
06707 ** ^The source and destination [database connections] (parameters S and D)
06708 ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
06709 ** an error.
06710 **
06711 ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
06712 ** returned and an error code and error message are stored in the
06713 ** destination [database connection] D.
06714 ** ^The error code and message for the failed call to sqlite3_backup_init()
06715 ** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
06716 ** [sqlite3_errmsg16()] functions.
06717 ** ^A successful call to sqlite3_backup_init() returns a pointer to an
06718 ** [sqlite3_backup] object.
06719 ** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
06720 ** sqlite3_backup_finish() functions to perform the specified backup 
06721 ** operation.
06722 **
06723 ** [[sqlite3_backup_step()]] <b>sqlite3_backup_step()</b>
06724 **
06725 ** ^Function sqlite3_backup_step(B,N) will copy up to N pages between 
06726 ** the source and destination databases specified by [sqlite3_backup] object B.
06727 ** ^If N is negative, all remaining source pages are copied. 
06728 ** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
06729 ** are still more pages to be copied, then the function returns [SQLITE_OK].
06730 ** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
06731 ** from source to destination, then it returns [SQLITE_DONE].
06732 ** ^If an error occurs while running sqlite3_backup_step(B,N),
06733 ** then an [error code] is returned. ^As well as [SQLITE_OK] and
06734 ** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
06735 ** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
06736 ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
06737 **
06738 ** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if
06739 ** <ol>
06740 ** <li> the destination database was opened read-only, or
06741 ** <li> the destination database is using write-ahead-log journaling
06742 ** and the destination and source page sizes differ, or
06743 ** <li> the destination database is an in-memory database and the
06744 ** destination and source page sizes differ.
06745 ** </ol>)^
06746 **
06747 ** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
06748 ** the [sqlite3_busy_handler | busy-handler function]
06749 ** is invoked (if one is specified). ^If the 
06750 ** busy-handler returns non-zero before the lock is available, then 
06751 ** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
06752 ** sqlite3_backup_step() can be retried later. ^If the source
06753 ** [database connection]
06754 ** is being used to write to the source database when sqlite3_backup_step()
06755 ** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
06756 ** case the call to sqlite3_backup_step() can be retried later on. ^(If
06757 ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
06758 ** [SQLITE_READONLY] is returned, then 
06759 ** there is no point in retrying the call to sqlite3_backup_step(). These 
06760 ** errors are considered fatal.)^  The application must accept 
06761 ** that the backup operation has failed and pass the backup operation handle 
06762 ** to the sqlite3_backup_finish() to release associated resources.
06763 **
06764 ** ^The first call to sqlite3_backup_step() obtains an exclusive lock
06765 ** on the destination file. ^The exclusive lock is not released until either 
06766 ** sqlite3_backup_finish() is called or the backup operation is complete 
06767 ** and sqlite3_backup_step() returns [SQLITE_DONE].  ^Every call to
06768 ** sqlite3_backup_step() obtains a [shared lock] on the source database that
06769 ** lasts for the duration of the sqlite3_backup_step() call.
06770 ** ^Because the source database is not locked between calls to
06771 ** sqlite3_backup_step(), the source database may be modified mid-way
06772 ** through the backup process.  ^If the source database is modified by an
06773 ** external process or via a database connection other than the one being
06774 ** used by the backup operation, then the backup will be automatically
06775 ** restarted by the next call to sqlite3_backup_step(). ^If the source 
06776 ** database is modified by the using the same database connection as is used
06777 ** by the backup operation, then the backup database is automatically
06778 ** updated at the same time.
06779 **
06780 ** [[sqlite3_backup_finish()]] <b>sqlite3_backup_finish()</b>
06781 **
06782 ** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the 
06783 ** application wishes to abandon the backup operation, the application
06784 ** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
06785 ** ^The sqlite3_backup_finish() interfaces releases all
06786 ** resources associated with the [sqlite3_backup] object. 
06787 ** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
06788 ** active write-transaction on the destination database is rolled back.
06789 ** The [sqlite3_backup] object is invalid
06790 ** and may not be used following a call to sqlite3_backup_finish().
06791 **
06792 ** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
06793 ** sqlite3_backup_step() errors occurred, regardless or whether or not
06794 ** sqlite3_backup_step() completed.
06795 ** ^If an out-of-memory condition or IO error occurred during any prior
06796 ** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
06797 ** sqlite3_backup_finish() returns the corresponding [error code].
06798 **
06799 ** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
06800 ** is not a permanent error and does not affect the return value of
06801 ** sqlite3_backup_finish().
06802 **
06803 ** [[sqlite3_backup__remaining()]] [[sqlite3_backup_pagecount()]]
06804 ** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
06805 **
06806 ** ^Each call to sqlite3_backup_step() sets two values inside
06807 ** the [sqlite3_backup] object: the number of pages still to be backed
06808 ** up and the total number of pages in the source database file.
06809 ** The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces
06810 ** retrieve these two values, respectively.
06811 **
06812 ** ^The values returned by these functions are only updated by
06813 ** sqlite3_backup_step(). ^If the source database is modified during a backup
06814 ** operation, then the values are not updated to account for any extra
06815 ** pages that need to be updated or the size of the source database file
06816 ** changing.
06817 **
06818 ** <b>Concurrent Usage of Database Handles</b>
06819 **
06820 ** ^The source [database connection] may be used by the application for other
06821 ** purposes while a backup operation is underway or being initialized.
06822 ** ^If SQLite is compiled and configured to support threadsafe database
06823 ** connections, then the source database connection may be used concurrently
06824 ** from within other threads.
06825 **
06826 ** However, the application must guarantee that the destination 
06827 ** [database connection] is not passed to any other API (by any thread) after 
06828 ** sqlite3_backup_init() is called and before the corresponding call to
06829 ** sqlite3_backup_finish().  SQLite does not currently check to see
06830 ** if the application incorrectly accesses the destination [database connection]
06831 ** and so no error code is reported, but the operations may malfunction
06832 ** nevertheless.  Use of the destination database connection while a
06833 ** backup is in progress might also also cause a mutex deadlock.
06834 **
06835 ** If running in [shared cache mode], the application must
06836 ** guarantee that the shared cache used by the destination database
06837 ** is not accessed while the backup is running. In practice this means
06838 ** that the application must guarantee that the disk file being 
06839 ** backed up to is not accessed by any connection within the process,
06840 ** not just the specific connection that was passed to sqlite3_backup_init().
06841 **
06842 ** The [sqlite3_backup] object itself is partially threadsafe. Multiple 
06843 ** threads may safely make multiple concurrent calls to sqlite3_backup_step().
06844 ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
06845 ** APIs are not strictly speaking threadsafe. If they are invoked at the
06846 ** same time as another thread is invoking sqlite3_backup_step() it is
06847 ** possible that they return invalid values.
06848 */
06849 SQLITE_API sqlite3_backup *sqlite3_backup_init(
06850   sqlite3 *pDest,                        /* Destination database handle */
06851   const char *zDestName,                 /* Destination database name */
06852   sqlite3 *pSource,                      /* Source database handle */
06853   const char *zSourceName                /* Source database name */
06854 );
06855 SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
06856 SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
06857 SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
06858 SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
06859 
06860 /*
06861 ** CAPI3REF: Unlock Notification
06862 **
06863 ** ^When running in shared-cache mode, a database operation may fail with
06864 ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
06865 ** individual tables within the shared-cache cannot be obtained. See
06866 ** [SQLite Shared-Cache Mode] for a description of shared-cache locking. 
06867 ** ^This API may be used to register a callback that SQLite will invoke 
06868 ** when the connection currently holding the required lock relinquishes it.
06869 ** ^This API is only available if the library was compiled with the
06870 ** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
06871 **
06872 ** See Also: [Using the SQLite Unlock Notification Feature].
06873 **
06874 ** ^Shared-cache locks are released when a database connection concludes
06875 ** its current transaction, either by committing it or rolling it back. 
06876 **
06877 ** ^When a connection (known as the blocked connection) fails to obtain a
06878 ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
06879 ** identity of the database connection (the blocking connection) that
06880 ** has locked the required resource is stored internally. ^After an 
06881 ** application receives an SQLITE_LOCKED error, it may call the
06882 ** sqlite3_unlock_notify() method with the blocked connection handle as 
06883 ** the first argument to register for a callback that will be invoked
06884 ** when the blocking connections current transaction is concluded. ^The
06885 ** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
06886 ** call that concludes the blocking connections transaction.
06887 **
06888 ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
06889 ** there is a chance that the blocking connection will have already
06890 ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
06891 ** If this happens, then the specified callback is invoked immediately,
06892 ** from within the call to sqlite3_unlock_notify().)^
06893 **
06894 ** ^If the blocked connection is attempting to obtain a write-lock on a
06895 ** shared-cache table, and more than one other connection currently holds
06896 ** a read-lock on the same table, then SQLite arbitrarily selects one of 
06897 ** the other connections to use as the blocking connection.
06898 **
06899 ** ^(There may be at most one unlock-notify callback registered by a 
06900 ** blocked connection. If sqlite3_unlock_notify() is called when the
06901 ** blocked connection already has a registered unlock-notify callback,
06902 ** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
06903 ** called with a NULL pointer as its second argument, then any existing
06904 ** unlock-notify callback is canceled. ^The blocked connections 
06905 ** unlock-notify callback may also be canceled by closing the blocked
06906 ** connection using [sqlite3_close()].
06907 **
06908 ** The unlock-notify callback is not reentrant. If an application invokes
06909 ** any sqlite3_xxx API functions from within an unlock-notify callback, a
06910 ** crash or deadlock may be the result.
06911 **
06912 ** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
06913 ** returns SQLITE_OK.
06914 **
06915 ** <b>Callback Invocation Details</b>
06916 **
06917 ** When an unlock-notify callback is registered, the application provides a 
06918 ** single void* pointer that is passed to the callback when it is invoked.
06919 ** However, the signature of the callback function allows SQLite to pass
06920 ** it an array of void* context pointers. The first argument passed to
06921 ** an unlock-notify callback is a pointer to an array of void* pointers,
06922 ** and the second is the number of entries in the array.
06923 **
06924 ** When a blocking connections transaction is concluded, there may be
06925 ** more than one blocked connection that has registered for an unlock-notify
06926 ** callback. ^If two or more such blocked connections have specified the
06927 ** same callback function, then instead of invoking the callback function
06928 ** multiple times, it is invoked once with the set of void* context pointers
06929 ** specified by the blocked connections bundled together into an array.
06930 ** This gives the application an opportunity to prioritize any actions 
06931 ** related to the set of unblocked database connections.
06932 **
06933 ** <b>Deadlock Detection</b>
06934 **
06935 ** Assuming that after registering for an unlock-notify callback a 
06936 ** database waits for the callback to be issued before taking any further
06937 ** action (a reasonable assumption), then using this API may cause the
06938 ** application to deadlock. For example, if connection X is waiting for
06939 ** connection Y's transaction to be concluded, and similarly connection
06940 ** Y is waiting on connection X's transaction, then neither connection
06941 ** will proceed and the system may remain deadlocked indefinitely.
06942 **
06943 ** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
06944 ** detection. ^If a given call to sqlite3_unlock_notify() would put the
06945 ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
06946 ** unlock-notify callback is registered. The system is said to be in
06947 ** a deadlocked state if connection A has registered for an unlock-notify
06948 ** callback on the conclusion of connection B's transaction, and connection
06949 ** B has itself registered for an unlock-notify callback when connection
06950 ** A's transaction is concluded. ^Indirect deadlock is also detected, so
06951 ** the system is also considered to be deadlocked if connection B has
06952 ** registered for an unlock-notify callback on the conclusion of connection
06953 ** C's transaction, where connection C is waiting on connection A. ^Any
06954 ** number of levels of indirection are allowed.
06955 **
06956 ** <b>The "DROP TABLE" Exception</b>
06957 **
06958 ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost 
06959 ** always appropriate to call sqlite3_unlock_notify(). There is however,
06960 ** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
06961 ** SQLite checks if there are any currently executing SELECT statements
06962 ** that belong to the same connection. If there are, SQLITE_LOCKED is
06963 ** returned. In this case there is no "blocking connection", so invoking
06964 ** sqlite3_unlock_notify() results in the unlock-notify callback being
06965 ** invoked immediately. If the application then re-attempts the "DROP TABLE"
06966 ** or "DROP INDEX" query, an infinite loop might be the result.
06967 **
06968 ** One way around this problem is to check the extended error code returned
06969 ** by an sqlite3_step() call. ^(If there is a blocking connection, then the
06970 ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
06971 ** the special "DROP TABLE/INDEX" case, the extended error code is just 
06972 ** SQLITE_LOCKED.)^
06973 */
06974 SQLITE_API int sqlite3_unlock_notify(
06975   sqlite3 *pBlocked,                          /* Waiting connection */
06976   void (*xNotify)(void **apArg, int nArg),    /* Callback function to invoke */
06977   void *pNotifyArg                            /* Argument to pass to xNotify */
06978 );
06979 
06980 
06981 /*
06982 ** CAPI3REF: String Comparison
06983 **
06984 ** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications
06985 ** and extensions to compare the contents of two buffers containing UTF-8
06986 ** strings in a case-independent fashion, using the same definition of "case
06987 ** independence" that SQLite uses internally when comparing identifiers.
06988 */
06989 SQLITE_API int sqlite3_stricmp(const char *, const char *);
06990 SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
06991 
06992 /*
06993 ** CAPI3REF: String Globbing
06994 *
06995 ** ^The [sqlite3_strglob(P,X)] interface returns zero if string X matches
06996 ** the glob pattern P, and it returns non-zero if string X does not match
06997 ** the glob pattern P.  ^The definition of glob pattern matching used in
06998 ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
06999 ** SQL dialect used by SQLite.  ^The sqlite3_strglob(P,X) function is case
07000 ** sensitive.
07001 **
07002 ** Note that this routine returns zero on a match and non-zero if the strings
07003 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
07004 */
07005 SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);
07006 
07007 /*
07008 ** CAPI3REF: Error Logging Interface
07009 **
07010 ** ^The [sqlite3_log()] interface writes a message into the [error log]
07011 ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
07012 ** ^If logging is enabled, the zFormat string and subsequent arguments are
07013 ** used with [sqlite3_snprintf()] to generate the final output string.
07014 **
07015 ** The sqlite3_log() interface is intended for use by extensions such as
07016 ** virtual tables, collating functions, and SQL functions.  While there is
07017 ** nothing to prevent an application from calling sqlite3_log(), doing so
07018 ** is considered bad form.
07019 **
07020 ** The zFormat string must not be NULL.
07021 **
07022 ** To avoid deadlocks and other threading problems, the sqlite3_log() routine
07023 ** will not use dynamically allocated memory.  The log message is stored in
07024 ** a fixed-length buffer on the stack.  If the log message is longer than
07025 ** a few hundred characters, it will be truncated to the length of the
07026 ** buffer.
07027 */
07028 SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
07029 
07030 /*
07031 ** CAPI3REF: Write-Ahead Log Commit Hook
07032 **
07033 ** ^The [sqlite3_wal_hook()] function is used to register a callback that
07034 ** will be invoked each time a database connection commits data to a
07035 ** [write-ahead log] (i.e. whenever a transaction is committed in
07036 ** [journal_mode | journal_mode=WAL mode]). 
07037 **
07038 ** ^The callback is invoked by SQLite after the commit has taken place and 
07039 ** the associated write-lock on the database released, so the implementation 
07040 ** may read, write or [checkpoint] the database as required.
07041 **
07042 ** ^The first parameter passed to the callback function when it is invoked
07043 ** is a copy of the third parameter passed to sqlite3_wal_hook() when
07044 ** registering the callback. ^The second is a copy of the database handle.
07045 ** ^The third parameter is the name of the database that was written to -
07046 ** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
07047 ** is the number of pages currently in the write-ahead log file,
07048 ** including those that were just committed.
07049 **
07050 ** The callback function should normally return [SQLITE_OK].  ^If an error
07051 ** code is returned, that error will propagate back up through the
07052 ** SQLite code base to cause the statement that provoked the callback
07053 ** to report an error, though the commit will have still occurred. If the
07054 ** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
07055 ** that does not correspond to any valid SQLite error code, the results
07056 ** are undefined.
07057 **
07058 ** A single database handle may have at most a single write-ahead log callback 
07059 ** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
07060 ** previously registered write-ahead log callback. ^Note that the
07061 ** [sqlite3_wal_autocheckpoint()] interface and the
07062 ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
07063 ** those overwrite any prior [sqlite3_wal_hook()] settings.
07064 */
07065 SQLITE_API void *sqlite3_wal_hook(
07066   sqlite3*, 
07067   int(*)(void *,sqlite3*,const char*,int),
07068   void*
07069 );
07070 
07071 /*
07072 ** CAPI3REF: Configure an auto-checkpoint
07073 **
07074 ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
07075 ** [sqlite3_wal_hook()] that causes any database on [database connection] D
07076 ** to automatically [checkpoint]
07077 ** after committing a transaction if there are N or
07078 ** more frames in the [write-ahead log] file.  ^Passing zero or 
07079 ** a negative value as the nFrame parameter disables automatic
07080 ** checkpoints entirely.
07081 **
07082 ** ^The callback registered by this function replaces any existing callback
07083 ** registered using [sqlite3_wal_hook()].  ^Likewise, registering a callback
07084 ** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
07085 ** configured by this function.
07086 **
07087 ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
07088 ** from SQL.
07089 **
07090 ** ^Every new [database connection] defaults to having the auto-checkpoint
07091 ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
07092 ** pages.  The use of this interface
07093 ** is only necessary if the default setting is found to be suboptimal
07094 ** for a particular application.
07095 */
07096 SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
07097 
07098 /*
07099 ** CAPI3REF: Checkpoint a database
07100 **
07101 ** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X
07102 ** on [database connection] D to be [checkpointed].  ^If X is NULL or an
07103 ** empty string, then a checkpoint is run on all databases of
07104 ** connection D.  ^If the database connection D is not in
07105 ** [WAL | write-ahead log mode] then this interface is a harmless no-op.
07106 **
07107 ** ^The [wal_checkpoint pragma] can be used to invoke this interface
07108 ** from SQL.  ^The [sqlite3_wal_autocheckpoint()] interface and the
07109 ** [wal_autocheckpoint pragma] can be used to cause this interface to be
07110 ** run whenever the WAL reaches a certain size threshold.
07111 **
07112 ** See also: [sqlite3_wal_checkpoint_v2()]
07113 */
07114 SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
07115 
07116 /*
07117 ** CAPI3REF: Checkpoint a database
07118 **
07119 ** Run a checkpoint operation on WAL database zDb attached to database 
07120 ** handle db. The specific operation is determined by the value of the 
07121 ** eMode parameter:
07122 **
07123 ** <dl>
07124 ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
07125 **   Checkpoint as many frames as possible without waiting for any database 
07126 **   readers or writers to finish. Sync the db file if all frames in the log
07127 **   are checkpointed. This mode is the same as calling 
07128 **   sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.
07129 **
07130 ** <dt>SQLITE_CHECKPOINT_FULL<dd>
07131 **   This mode blocks (calls the busy-handler callback) until there is no
07132 **   database writer and all readers are reading from the most recent database
07133 **   snapshot. It then checkpoints all frames in the log file and syncs the
07134 **   database file. This call blocks database writers while it is running,
07135 **   but not database readers.
07136 **
07137 ** <dt>SQLITE_CHECKPOINT_RESTART<dd>
07138 **   This mode works the same way as SQLITE_CHECKPOINT_FULL, except after 
07139 **   checkpointing the log file it blocks (calls the busy-handler callback)
07140 **   until all readers are reading from the database file only. This ensures 
07141 **   that the next client to write to the database file restarts the log file 
07142 **   from the beginning. This call blocks database writers while it is running,
07143 **   but not database readers.
07144 ** </dl>
07145 **
07146 ** If pnLog is not NULL, then *pnLog is set to the total number of frames in
07147 ** the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to
07148 ** the total number of checkpointed frames (including any that were already
07149 ** checkpointed when this function is called). *pnLog and *pnCkpt may be
07150 ** populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK.
07151 ** If no values are available because of an error, they are both set to -1
07152 ** before returning to communicate this to the caller.
07153 **
07154 ** All calls obtain an exclusive "checkpoint" lock on the database file. If
07155 ** any other process is running a checkpoint operation at the same time, the 
07156 ** lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a 
07157 ** busy-handler configured, it will not be invoked in this case.
07158 **
07159 ** The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive 
07160 ** "writer" lock on the database file. If the writer lock cannot be obtained
07161 ** immediately, and a busy-handler is configured, it is invoked and the writer
07162 ** lock retried until either the busy-handler returns 0 or the lock is
07163 ** successfully obtained. The busy-handler is also invoked while waiting for
07164 ** database readers as described above. If the busy-handler returns 0 before
07165 ** the writer lock is obtained or while waiting for database readers, the
07166 ** checkpoint operation proceeds from that point in the same way as 
07167 ** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible 
07168 ** without blocking any further. SQLITE_BUSY is returned in this case.
07169 **
07170 ** If parameter zDb is NULL or points to a zero length string, then the
07171 ** specified operation is attempted on all WAL databases. In this case the
07172 ** values written to output parameters *pnLog and *pnCkpt are undefined. If 
07173 ** an SQLITE_BUSY error is encountered when processing one or more of the 
07174 ** attached WAL databases, the operation is still attempted on any remaining 
07175 ** attached databases and SQLITE_BUSY is returned to the caller. If any other 
07176 ** error occurs while processing an attached database, processing is abandoned 
07177 ** and the error code returned to the caller immediately. If no error 
07178 ** (SQLITE_BUSY or otherwise) is encountered while processing the attached 
07179 ** databases, SQLITE_OK is returned.
07180 **
07181 ** If database zDb is the name of an attached database that is not in WAL
07182 ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
07183 ** zDb is not NULL (or a zero length string) and is not the name of any
07184 ** attached database, SQLITE_ERROR is returned to the caller.
07185 */
07186 SQLITE_API int sqlite3_wal_checkpoint_v2(
07187   sqlite3 *db,                    /* Database handle */
07188   const char *zDb,                /* Name of attached database (or NULL) */
07189   int eMode,                      /* SQLITE_CHECKPOINT_* value */
07190   int *pnLog,                     /* OUT: Size of WAL log in frames */
07191   int *pnCkpt                     /* OUT: Total number of frames checkpointed */
07192 );
07193 
07194 /*
07195 ** CAPI3REF: Checkpoint operation parameters
07196 **
07197 ** These constants can be used as the 3rd parameter to
07198 ** [sqlite3_wal_checkpoint_v2()].  See the [sqlite3_wal_checkpoint_v2()]
07199 ** documentation for additional information about the meaning and use of
07200 ** each of these values.
07201 */
07202 #define SQLITE_CHECKPOINT_PASSIVE 0
07203 #define SQLITE_CHECKPOINT_FULL    1
07204 #define SQLITE_CHECKPOINT_RESTART 2
07205 
07206 /*
07207 ** CAPI3REF: Virtual Table Interface Configuration
07208 **
07209 ** This function may be called by either the [xConnect] or [xCreate] method
07210 ** of a [virtual table] implementation to configure
07211 ** various facets of the virtual table interface.
07212 **
07213 ** If this interface is invoked outside the context of an xConnect or
07214 ** xCreate virtual table method then the behavior is undefined.
07215 **
07216 ** At present, there is only one option that may be configured using
07217 ** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].)  Further options
07218 ** may be added in the future.
07219 */
07220 SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
07221 
07222 /*
07223 ** CAPI3REF: Virtual Table Configuration Options
07224 **
07225 ** These macros define the various options to the
07226 ** [sqlite3_vtab_config()] interface that [virtual table] implementations
07227 ** can use to customize and optimize their behavior.
07228 **
07229 ** <dl>
07230 ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT
07231 ** <dd>Calls of the form
07232 ** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
07233 ** where X is an integer.  If X is zero, then the [virtual table] whose
07234 ** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not
07235 ** support constraints.  In this configuration (which is the default) if
07236 ** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire
07237 ** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
07238 ** specified as part of the users SQL statement, regardless of the actual
07239 ** ON CONFLICT mode specified.
07240 **
07241 ** If X is non-zero, then the virtual table implementation guarantees
07242 ** that if [xUpdate] returns [SQLITE_CONSTRAINT], it will do so before
07243 ** any modifications to internal or persistent data structures have been made.
07244 ** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite 
07245 ** is able to roll back a statement or database transaction, and abandon
07246 ** or continue processing the current SQL statement as appropriate. 
07247 ** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
07248 ** [SQLITE_CONSTRAINT], SQLite handles this as if the ON CONFLICT mode
07249 ** had been ABORT.
07250 **
07251 ** Virtual table implementations that are required to handle OR REPLACE
07252 ** must do so within the [xUpdate] method. If a call to the 
07253 ** [sqlite3_vtab_on_conflict()] function indicates that the current ON 
07254 ** CONFLICT policy is REPLACE, the virtual table implementation should 
07255 ** silently replace the appropriate rows within the xUpdate callback and
07256 ** return SQLITE_OK. Or, if this is not possible, it may return
07257 ** SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT 
07258 ** constraint handling.
07259 ** </dl>
07260 */
07261 #define SQLITE_VTAB_CONSTRAINT_SUPPORT 1
07262 
07263 /*
07264 ** CAPI3REF: Determine The Virtual Table Conflict Policy
07265 **
07266 ** This function may only be called from within a call to the [xUpdate] method
07267 ** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The
07268 ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
07269 ** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode
07270 ** of the SQL statement that triggered the call to the [xUpdate] method of the
07271 ** [virtual table].
07272 */
07273 SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
07274 
07275 /*
07276 ** CAPI3REF: Conflict resolution modes
07277 **
07278 ** These constants are returned by [sqlite3_vtab_on_conflict()] to
07279 ** inform a [virtual table] implementation what the [ON CONFLICT] mode
07280 ** is for the SQL statement being evaluated.
07281 **
07282 ** Note that the [SQLITE_IGNORE] constant is also used as a potential
07283 ** return value from the [sqlite3_set_authorizer()] callback and that
07284 ** [SQLITE_ABORT] is also a [result code].
07285 */
07286 #define SQLITE_ROLLBACK 1
07287 /* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
07288 #define SQLITE_FAIL     3
07289 /* #define SQLITE_ABORT 4  // Also an error code */
07290 #define SQLITE_REPLACE  5
07291 
07292 
07293 
07294 /*
07295 ** Undo the hack that converts floating point types to integer for
07296 ** builds on processors without floating point support.
07297 */
07298 #ifdef SQLITE_OMIT_FLOATING_POINT
07299 # undef double
07300 #endif
07301 
07302 #if 0
07303 }  /* End of the 'extern "C"' block */
07304 #endif
07305 #endif /* _SQLITE3_H_ */
07306 
07307 /*
07308 ** 2010 August 30
07309 **
07310 ** The author disclaims copyright to this source code.  In place of
07311 ** a legal notice, here is a blessing:
07312 **
07313 **    May you do good and not evil.
07314 **    May you find forgiveness for yourself and forgive others.
07315 **    May you share freely, never taking more than you give.
07316 **
07317 *************************************************************************
07318 */
07319 
07320 #ifndef _SQLITE3RTREE_H_
07321 #define _SQLITE3RTREE_H_
07322 
07323 
07324 #if 0
07325 extern "C" {
07326 #endif
07327 
07328 typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
07329 
07330 /*
07331 ** Register a geometry callback named zGeom that can be used as part of an
07332 ** R-Tree geometry query as follows:
07333 **
07334 **   SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
07335 */
07336 SQLITE_API int sqlite3_rtree_geometry_callback(
07337   sqlite3 *db,
07338   const char *zGeom,
07339 #ifdef SQLITE_RTREE_INT_ONLY
07340   int (*xGeom)(sqlite3_rtree_geometry*, int n, sqlite3_int64 *a, int *pRes),
07341 #else
07342   int (*xGeom)(sqlite3_rtree_geometry*, int n, double *a, int *pRes),
07343 #endif
07344   void *pContext
07345 );
07346 
07347 
07348 /*
07349 ** A pointer to a structure of the following type is passed as the first
07350 ** argument to callbacks registered using rtree_geometry_callback().
07351 */
07352 struct sqlite3_rtree_geometry {
07353   void *pContext;                 /* Copy of pContext passed to s_r_g_c() */
07354   int nParam;                     /* Size of array aParam[] */
07355   double *aParam;                 /* Parameters passed to SQL geom function */
07356   void *pUser;                    /* Callback implementation user data */
07357   void (*xDelUser)(void *);       /* Called by SQLite to clean up pUser */
07358 };
07359 
07360 
07361 #if 0
07362 }  /* end of the 'extern "C"' block */
07363 #endif
07364 
07365 #endif  /* ifndef _SQLITE3RTREE_H_ */
07366 
07367 
07368 /************** End of sqlite3.h *********************************************/
07369 /************** Begin file sqliteInt.h ***************************************/
07370 /*
07371 ** 2001 September 15
07372 **
07373 ** The author disclaims copyright to this source code.  In place of
07374 ** a legal notice, here is a blessing:
07375 **
07376 **    May you do good and not evil.
07377 **    May you find forgiveness for yourself and forgive others.
07378 **    May you share freely, never taking more than you give.
07379 **
07380 *************************************************************************
07381 ** Internal interface definitions for SQLite.
07382 **
07383 */
07384 #ifndef _SQLITEINT_H_
07385 #define _SQLITEINT_H_
07386 
07387 /*
07388 ** These #defines should enable >2GB file support on POSIX if the
07389 ** underlying operating system supports it.  If the OS lacks
07390 ** large file support, or if the OS is windows, these should be no-ops.
07391 **
07392 ** Ticket #2739:  The _LARGEFILE_SOURCE macro must appear before any
07393 ** system #includes.  Hence, this block of code must be the very first
07394 ** code in all source files.
07395 **
07396 ** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch
07397 ** on the compiler command line.  This is necessary if you are compiling
07398 ** on a recent machine (ex: Red Hat 7.2) but you want your code to work
07399 ** on an older machine (ex: Red Hat 6.0).  If you compile on Red Hat 7.2
07400 ** without this option, LFS is enable.  But LFS does not exist in the kernel
07401 ** in Red Hat 6.0, so the code won't work.  Hence, for maximum binary
07402 ** portability you should omit LFS.
07403 **
07404 ** Similar is true for Mac OS X.  LFS is only supported on Mac OS X 9 and later.
07405 */
07406 #ifndef SQLITE_DISABLE_LFS
07407 # define _LARGE_FILE       1
07408 # ifndef _FILE_OFFSET_BITS
07409 #   define _FILE_OFFSET_BITS 64
07410 # endif
07411 # define _LARGEFILE_SOURCE 1
07412 #endif
07413 
07414 /*
07415 ** Include the configuration header output by 'configure' if we're using the
07416 ** autoconf-based build
07417 */
07418 #ifdef _HAVE_SQLITE_CONFIG_H
07419 #include "config.h"
07420 #endif
07421 
07422 /************** Include sqliteLimit.h in the middle of sqliteInt.h ***********/
07423 /************** Begin file sqliteLimit.h *************************************/
07424 /*
07425 ** 2007 May 7
07426 **
07427 ** The author disclaims copyright to this source code.  In place of
07428 ** a legal notice, here is a blessing:
07429 **
07430 **    May you do good and not evil.
07431 **    May you find forgiveness for yourself and forgive others.
07432 **    May you share freely, never taking more than you give.
07433 **
07434 *************************************************************************
07435 ** 
07436 ** This file defines various limits of what SQLite can process.
07437 */
07438 
07439 /*
07440 ** The maximum length of a TEXT or BLOB in bytes.   This also
07441 ** limits the size of a row in a table or index.
07442 **
07443 ** The hard limit is the ability of a 32-bit signed integer
07444 ** to count the size: 2^31-1 or 2147483647.
07445 */
07446 #ifndef SQLITE_MAX_LENGTH
07447 # define SQLITE_MAX_LENGTH 1000000000
07448 #endif
07449 
07450 /*
07451 ** This is the maximum number of
07452 **
07453 **    * Columns in a table
07454 **    * Columns in an index
07455 **    * Columns in a view
07456 **    * Terms in the SET clause of an UPDATE statement
07457 **    * Terms in the result set of a SELECT statement
07458 **    * Terms in the GROUP BY or ORDER BY clauses of a SELECT statement.
07459 **    * Terms in the VALUES clause of an INSERT statement
07460 **
07461 ** The hard upper limit here is 32676.  Most database people will
07462 ** tell you that in a well-normalized database, you usually should
07463 ** not have more than a dozen or so columns in any table.  And if
07464 ** that is the case, there is no point in having more than a few
07465 ** dozen values in any of the other situations described above.
07466 */
07467 #ifndef SQLITE_MAX_COLUMN
07468 # define SQLITE_MAX_COLUMN 2000
07469 #endif
07470 
07471 /*
07472 ** The maximum length of a single SQL statement in bytes.
07473 **
07474 ** It used to be the case that setting this value to zero would
07475 ** turn the limit off.  That is no longer true.  It is not possible
07476 ** to turn this limit off.
07477 */
07478 #ifndef SQLITE_MAX_SQL_LENGTH
07479 # define SQLITE_MAX_SQL_LENGTH 1000000000
07480 #endif
07481 
07482 /*
07483 ** The maximum depth of an expression tree. This is limited to 
07484 ** some extent by SQLITE_MAX_SQL_LENGTH. But sometime you might 
07485 ** want to place more severe limits on the complexity of an 
07486 ** expression.
07487 **
07488 ** A value of 0 used to mean that the limit was not enforced.
07489 ** But that is no longer true.  The limit is now strictly enforced
07490 ** at all times.
07491 */
07492 #ifndef SQLITE_MAX_EXPR_DEPTH
07493 # define SQLITE_MAX_EXPR_DEPTH 1000
07494 #endif
07495 
07496 /*
07497 ** The maximum number of terms in a compound SELECT statement.
07498 ** The code generator for compound SELECT statements does one
07499 ** level of recursion for each term.  A stack overflow can result
07500 ** if the number of terms is too large.  In practice, most SQL
07501 ** never has more than 3 or 4 terms.  Use a value of 0 to disable
07502 ** any limit on the number of terms in a compount SELECT.
07503 */
07504 #ifndef SQLITE_MAX_COMPOUND_SELECT
07505 # define SQLITE_MAX_COMPOUND_SELECT 500
07506 #endif
07507 
07508 /*
07509 ** The maximum number of opcodes in a VDBE program.
07510 ** Not currently enforced.
07511 */
07512 #ifndef SQLITE_MAX_VDBE_OP
07513 # define SQLITE_MAX_VDBE_OP 25000
07514 #endif
07515 
07516 /*
07517 ** The maximum number of arguments to an SQL function.
07518 */
07519 #ifndef SQLITE_MAX_FUNCTION_ARG
07520 # define SQLITE_MAX_FUNCTION_ARG 127
07521 #endif
07522 
07523 /*
07524 ** The maximum number of in-memory pages to use for the main database
07525 ** table and for temporary tables.  The SQLITE_DEFAULT_CACHE_SIZE
07526 */
07527 #ifndef SQLITE_DEFAULT_CACHE_SIZE
07528 # define SQLITE_DEFAULT_CACHE_SIZE  2000
07529 #endif
07530 #ifndef SQLITE_DEFAULT_TEMP_CACHE_SIZE
07531 # define SQLITE_DEFAULT_TEMP_CACHE_SIZE  500
07532 #endif
07533 
07534 /*
07535 ** The default number of frames to accumulate in the log file before
07536 ** checkpointing the database in WAL mode.
07537 */
07538 #ifndef SQLITE_DEFAULT_WAL_AUTOCHECKPOINT
07539 # define SQLITE_DEFAULT_WAL_AUTOCHECKPOINT  1000
07540 #endif
07541 
07542 /*
07543 ** The maximum number of attached databases.  This must be between 0
07544 ** and 62.  The upper bound on 62 is because a 64-bit integer bitmap
07545 ** is used internally to track attached databases.
07546 */
07547 #ifndef SQLITE_MAX_ATTACHED
07548 # define SQLITE_MAX_ATTACHED 10
07549 #endif
07550 
07551 
07552 /*
07553 ** The maximum value of a ?nnn wildcard that the parser will accept.
07554 */
07555 #ifndef SQLITE_MAX_VARIABLE_NUMBER
07556 # define SQLITE_MAX_VARIABLE_NUMBER 999
07557 #endif
07558 
07559 /* Maximum page size.  The upper bound on this value is 65536.  This a limit
07560 ** imposed by the use of 16-bit offsets within each page.
07561 **
07562 ** Earlier versions of SQLite allowed the user to change this value at
07563 ** compile time. This is no longer permitted, on the grounds that it creates
07564 ** a library that is technically incompatible with an SQLite library 
07565 ** compiled with a different limit. If a process operating on a database 
07566 ** with a page-size of 65536 bytes crashes, then an instance of SQLite 
07567 ** compiled with the default page-size limit will not be able to rollback 
07568 ** the aborted transaction. This could lead to database corruption.
07569 */
07570 #ifdef SQLITE_MAX_PAGE_SIZE
07571 # undef SQLITE_MAX_PAGE_SIZE
07572 #endif
07573 #define SQLITE_MAX_PAGE_SIZE 65536
07574 
07575 
07576 /*
07577 ** The default size of a database page.
07578 */
07579 #ifndef SQLITE_DEFAULT_PAGE_SIZE
07580 # define SQLITE_DEFAULT_PAGE_SIZE 1024
07581 #endif
07582 #if SQLITE_DEFAULT_PAGE_SIZE>SQLITE_MAX_PAGE_SIZE
07583 # undef SQLITE_DEFAULT_PAGE_SIZE
07584 # define SQLITE_DEFAULT_PAGE_SIZE SQLITE_MAX_PAGE_SIZE
07585 #endif
07586 
07587 /*
07588 ** Ordinarily, if no value is explicitly provided, SQLite creates databases
07589 ** with page size SQLITE_DEFAULT_PAGE_SIZE. However, based on certain
07590 ** device characteristics (sector-size and atomic write() support),
07591 ** SQLite may choose a larger value. This constant is the maximum value
07592 ** SQLite will choose on its own.
07593 */
07594 #ifndef SQLITE_MAX_DEFAULT_PAGE_SIZE
07595 # define SQLITE_MAX_DEFAULT_PAGE_SIZE 8192
07596 #endif
07597 #if SQLITE_MAX_DEFAULT_PAGE_SIZE>SQLITE_MAX_PAGE_SIZE
07598 # undef SQLITE_MAX_DEFAULT_PAGE_SIZE
07599 # define SQLITE_MAX_DEFAULT_PAGE_SIZE SQLITE_MAX_PAGE_SIZE
07600 #endif
07601 
07602 
07603 /*
07604 ** Maximum number of pages in one database file.
07605 **
07606 ** This is really just the default value for the max_page_count pragma.
07607 ** This value can be lowered (or raised) at run-time using that the
07608 ** max_page_count macro.
07609 */
07610 #ifndef SQLITE_MAX_PAGE_COUNT
07611 # define SQLITE_MAX_PAGE_COUNT 1073741823
07612 #endif
07613 
07614 /*
07615 ** Maximum length (in bytes) of the pattern in a LIKE or GLOB
07616 ** operator.
07617 */
07618 #ifndef SQLITE_MAX_LIKE_PATTERN_LENGTH
07619 # define SQLITE_MAX_LIKE_PATTERN_LENGTH 50000
07620 #endif
07621 
07622 /*
07623 ** Maximum depth of recursion for triggers.
07624 **
07625 ** A value of 1 means that a trigger program will not be able to itself
07626 ** fire any triggers. A value of 0 means that no trigger programs at all 
07627 ** may be executed.
07628 */
07629 #ifndef SQLITE_MAX_TRIGGER_DEPTH
07630 # define SQLITE_MAX_TRIGGER_DEPTH 1000
07631 #endif
07632 
07633 /************** End of sqliteLimit.h *****************************************/
07634 /************** Continuing where we left off in sqliteInt.h ******************/
07635 
07636 /* Disable nuisance warnings on Borland compilers */
07637 #if defined(__BORLANDC__)
07638 #pragma warn -rch /* unreachable code */
07639 #pragma warn -ccc /* Condition is always true or false */
07640 #pragma warn -aus /* Assigned value is never used */
07641 #pragma warn -csu /* Comparing signed and unsigned */
07642 #pragma warn -spa /* Suspicious pointer arithmetic */
07643 #endif
07644 
07645 /* Needed for various definitions... */
07646 #ifndef _GNU_SOURCE
07647 # define _GNU_SOURCE
07648 #endif
07649 
07650 #if defined(__OpenBSD__) && !defined(_BSD_SOURCE)
07651 # define _BSD_SOURCE
07652 #endif
07653 
07654 /*
07655 ** Include standard header files as necessary
07656 */
07657 #ifdef HAVE_STDINT_H
07658 #include <stdint.h>
07659 #endif
07660 #ifdef HAVE_INTTYPES_H
07661 #include <inttypes.h>
07662 #endif
07663 
07664 /*
07665 ** The following macros are used to cast pointers to integers and
07666 ** integers to pointers.  The way you do this varies from one compiler
07667 ** to the next, so we have developed the following set of #if statements
07668 ** to generate appropriate macros for a wide range of compilers.
07669 **
07670 ** The correct "ANSI" way to do this is to use the intptr_t type. 
07671 ** Unfortunately, that typedef is not available on all compilers, or
07672 ** if it is available, it requires an #include of specific headers
07673 ** that vary from one machine to the next.
07674 **
07675 ** Ticket #3860:  The llvm-gcc-4.2 compiler from Apple chokes on
07676 ** the ((void*)&((char*)0)[X]) construct.  But MSVC chokes on ((void*)(X)).
07677 ** So we have to define the macros in different ways depending on the
07678 ** compiler.
07679 */
07680 #if defined(__PTRDIFF_TYPE__)  /* This case should work for GCC */
07681 # define SQLITE_INT_TO_PTR(X)  ((void*)(__PTRDIFF_TYPE__)(X))
07682 # define SQLITE_PTR_TO_INT(X)  ((int)(__PTRDIFF_TYPE__)(X))
07683 #elif !defined(__GNUC__)       /* Works for compilers other than LLVM */
07684 # define SQLITE_INT_TO_PTR(X)  ((void*)&((char*)0)[X])
07685 # define SQLITE_PTR_TO_INT(X)  ((int)(((char*)X)-(char*)0))
07686 #elif defined(HAVE_STDINT_H)   /* Use this case if we have ANSI headers */
07687 # define SQLITE_INT_TO_PTR(X)  ((void*)(intptr_t)(X))
07688 # define SQLITE_PTR_TO_INT(X)  ((int)(intptr_t)(X))
07689 #else                          /* Generates a warning - but it always works */
07690 # define SQLITE_INT_TO_PTR(X)  ((void*)(X))
07691 # define SQLITE_PTR_TO_INT(X)  ((int)(X))
07692 #endif
07693 
07694 /*
07695 ** The SQLITE_THREADSAFE macro must be defined as 0, 1, or 2.
07696 ** 0 means mutexes are permanently disable and the library is never
07697 ** threadsafe.  1 means the library is serialized which is the highest
07698 ** level of threadsafety.  2 means the library is multithreaded - multiple
07699 ** threads can use SQLite as long as no two threads try to use the same
07700 ** database connection at the same time.
07701 **
07702 ** Older versions of SQLite used an optional THREADSAFE macro.
07703 ** We support that for legacy.
07704 */
07705 #if !defined(SQLITE_THREADSAFE)
07706 # if defined(THREADSAFE)
07707 #   define SQLITE_THREADSAFE THREADSAFE
07708 # else
07709 #   define SQLITE_THREADSAFE 1 /* IMP: R-07272-22309 */
07710 # endif
07711 #endif
07712 
07713 /*
07714 ** Powersafe overwrite is on by default.  But can be turned off using
07715 ** the -DSQLITE_POWERSAFE_OVERWRITE=0 command-line option.
07716 */
07717 #ifndef SQLITE_POWERSAFE_OVERWRITE
07718 # define SQLITE_POWERSAFE_OVERWRITE 1
07719 #endif
07720 
07721 /*
07722 ** The SQLITE_DEFAULT_MEMSTATUS macro must be defined as either 0 or 1.
07723 ** It determines whether or not the features related to 
07724 ** SQLITE_CONFIG_MEMSTATUS are available by default or not. This value can
07725 ** be overridden at runtime using the sqlite3_config() API.
07726 */
07727 #if !defined(SQLITE_DEFAULT_MEMSTATUS)
07728 # define SQLITE_DEFAULT_MEMSTATUS 1
07729 #endif
07730 
07731 /*
07732 ** Exactly one of the following macros must be defined in order to
07733 ** specify which memory allocation subsystem to use.
07734 **
07735 **     SQLITE_SYSTEM_MALLOC          // Use normal system malloc()
07736 **     SQLITE_WIN32_MALLOC           // Use Win32 native heap API
07737 **     SQLITE_ZERO_MALLOC            // Use a stub allocator that always fails
07738 **     SQLITE_MEMDEBUG               // Debugging version of system malloc()
07739 **
07740 ** On Windows, if the SQLITE_WIN32_MALLOC_VALIDATE macro is defined and the
07741 ** assert() macro is enabled, each call into the Win32 native heap subsystem
07742 ** will cause HeapValidate to be called.  If heap validation should fail, an
07743 ** assertion will be triggered.
07744 **
07745 ** If none of the above are defined, then set SQLITE_SYSTEM_MALLOC as
07746 ** the default.
07747 */
07748 #if defined(SQLITE_SYSTEM_MALLOC) \
07749   + defined(SQLITE_WIN32_MALLOC) \
07750   + defined(SQLITE_ZERO_MALLOC) \
07751   + defined(SQLITE_MEMDEBUG)>1
07752 # error "Two or more of the following compile-time configuration options\
07753  are defined but at most one is allowed:\
07754  SQLITE_SYSTEM_MALLOC, SQLITE_WIN32_MALLOC, SQLITE_MEMDEBUG,\
07755  SQLITE_ZERO_MALLOC"
07756 #endif
07757 #if defined(SQLITE_SYSTEM_MALLOC) \
07758   + defined(SQLITE_WIN32_MALLOC) \
07759   + defined(SQLITE_ZERO_MALLOC) \
07760   + defined(SQLITE_MEMDEBUG)==0
07761 # define SQLITE_SYSTEM_MALLOC 1
07762 #endif
07763 
07764 /*
07765 ** If SQLITE_MALLOC_SOFT_LIMIT is not zero, then try to keep the
07766 ** sizes of memory allocations below this value where possible.
07767 */
07768 #if !defined(SQLITE_MALLOC_SOFT_LIMIT)
07769 # define SQLITE_MALLOC_SOFT_LIMIT 1024
07770 #endif
07771 
07772 /*
07773 ** We need to define _XOPEN_SOURCE as follows in order to enable
07774 ** recursive mutexes on most Unix systems and fchmod() on OpenBSD.
07775 ** But _XOPEN_SOURCE define causes problems for Mac OS X, so omit
07776 ** it.
07777 */
07778 #if !defined(_XOPEN_SOURCE) && !defined(__DARWIN__) && !defined(__APPLE__)
07779 #  define _XOPEN_SOURCE 600
07780 #endif
07781 
07782 /*
07783 ** NDEBUG and SQLITE_DEBUG are opposites.  It should always be true that
07784 ** defined(NDEBUG)==!defined(SQLITE_DEBUG).  If this is not currently true,
07785 ** make it true by defining or undefining NDEBUG.
07786 **
07787 ** Setting NDEBUG makes the code smaller and faster by disabling the
07788 ** assert() statements in the code.  So we want the default action
07789 ** to be for NDEBUG to be set and NDEBUG to be undefined only if SQLITE_DEBUG
07790 ** is set.  Thus NDEBUG becomes an opt-in rather than an opt-out
07791 ** feature.
07792 */
07793 #if !defined(NDEBUG) && !defined(SQLITE_DEBUG) 
07794 # define NDEBUG 1
07795 #endif
07796 #if defined(NDEBUG) && defined(SQLITE_DEBUG)
07797 # undef NDEBUG
07798 #endif
07799 
07800 /*
07801 ** Enable SQLITE_ENABLE_EXPLAIN_COMMENTS if SQLITE_DEBUG is turned on.
07802 */
07803 #if !defined(SQLITE_ENABLE_EXPLAIN_COMMENTS) && defined(SQLITE_DEBUG)
07804 # define SQLITE_ENABLE_EXPLAIN_COMMENTS 1
07805 #endif
07806 
07807 /*
07808 ** The testcase() macro is used to aid in coverage testing.  When 
07809 ** doing coverage testing, the condition inside the argument to
07810 ** testcase() must be evaluated both true and false in order to
07811 ** get full branch coverage.  The testcase() macro is inserted
07812 ** to help ensure adequate test coverage in places where simple
07813 ** condition/decision coverage is inadequate.  For example, testcase()
07814 ** can be used to make sure boundary values are tested.  For
07815 ** bitmask tests, testcase() can be used to make sure each bit
07816 ** is significant and used at least once.  On switch statements
07817 ** where multiple cases go to the same block of code, testcase()
07818 ** can insure that all cases are evaluated.
07819 **
07820 */
07821 #ifdef SQLITE_COVERAGE_TEST
07822 SQLITE_PRIVATE   void sqlite3Coverage(int);
07823 # define testcase(X)  if( X ){ sqlite3Coverage(__LINE__); }
07824 #else
07825 # define testcase(X)
07826 #endif
07827 
07828 /*
07829 ** The TESTONLY macro is used to enclose variable declarations or
07830 ** other bits of code that are needed to support the arguments
07831 ** within testcase() and assert() macros.
07832 */
07833 #if !defined(NDEBUG) || defined(SQLITE_COVERAGE_TEST)
07834 # define TESTONLY(X)  X
07835 #else
07836 # define TESTONLY(X)
07837 #endif
07838 
07839 /*
07840 ** Sometimes we need a small amount of code such as a variable initialization
07841 ** to setup for a later assert() statement.  We do not want this code to
07842 ** appear when assert() is disabled.  The following macro is therefore
07843 ** used to contain that setup code.  The "VVA" acronym stands for
07844 ** "Verification, Validation, and Accreditation".  In other words, the
07845 ** code within VVA_ONLY() will only run during verification processes.
07846 */
07847 #ifndef NDEBUG
07848 # define VVA_ONLY(X)  X
07849 #else
07850 # define VVA_ONLY(X)
07851 #endif
07852 
07853 /*
07854 ** The ALWAYS and NEVER macros surround boolean expressions which 
07855 ** are intended to always be true or false, respectively.  Such
07856 ** expressions could be omitted from the code completely.  But they
07857 ** are included in a few cases in order to enhance the resilience
07858 ** of SQLite to unexpected behavior - to make the code "self-healing"
07859 ** or "ductile" rather than being "brittle" and crashing at the first
07860 ** hint of unplanned behavior.
07861 **
07862 ** In other words, ALWAYS and NEVER are added for defensive code.
07863 **
07864 ** When doing coverage testing ALWAYS and NEVER are hard-coded to
07865 ** be true and false so that the unreachable code they specify will
07866 ** not be counted as untested code.
07867 */
07868 #if defined(SQLITE_COVERAGE_TEST)
07869 # define ALWAYS(X)      (1)
07870 # define NEVER(X)       (0)
07871 #elif !defined(NDEBUG)
07872 # define ALWAYS(X)      ((X)?1:(assert(0),0))
07873 # define NEVER(X)       ((X)?(assert(0),1):0)
07874 #else
07875 # define ALWAYS(X)      (X)
07876 # define NEVER(X)       (X)
07877 #endif
07878 
07879 /*
07880 ** Return true (non-zero) if the input is a integer that is too large
07881 ** to fit in 32-bits.  This macro is used inside of various testcase()
07882 ** macros to verify that we have tested SQLite for large-file support.
07883 */
07884 #define IS_BIG_INT(X)  (((X)&~(i64)0xffffffff)!=0)
07885 
07886 /*
07887 ** The macro unlikely() is a hint that surrounds a boolean
07888 ** expression that is usually false.  Macro likely() surrounds
07889 ** a boolean expression that is usually true.  These hints could,
07890 ** in theory, be used by the compiler to generate better code, but
07891 ** currently they are just comments for human readers.
07892 */
07893 #define likely(X)    (X)
07894 #define unlikely(X)  (X)
07895 
07896 /************** Include hash.h in the middle of sqliteInt.h ******************/
07897 /************** Begin file hash.h ********************************************/
07898 /*
07899 ** 2001 September 22
07900 **
07901 ** The author disclaims copyright to this source code.  In place of
07902 ** a legal notice, here is a blessing:
07903 **
07904 **    May you do good and not evil.
07905 **    May you find forgiveness for yourself and forgive others.
07906 **    May you share freely, never taking more than you give.
07907 **
07908 *************************************************************************
07909 ** This is the header file for the generic hash-table implementation
07910 ** used in SQLite.
07911 */
07912 #ifndef _SQLITE_HASH_H_
07913 #define _SQLITE_HASH_H_
07914 
07915 /* Forward declarations of structures. */
07916 typedef struct Hash Hash;
07917 typedef struct HashElem HashElem;
07918 
07919 /* A complete hash table is an instance of the following structure.
07920 ** The internals of this structure are intended to be opaque -- client
07921 ** code should not attempt to access or modify the fields of this structure
07922 ** directly.  Change this structure only by using the routines below.
07923 ** However, some of the "procedures" and "functions" for modifying and
07924 ** accessing this structure are really macros, so we can't really make
07925 ** this structure opaque.
07926 **
07927 ** All elements of the hash table are on a single doubly-linked list.
07928 ** Hash.first points to the head of this list.
07929 **
07930 ** There are Hash.htsize buckets.  Each bucket points to a spot in
07931 ** the global doubly-linked list.  The contents of the bucket are the
07932 ** element pointed to plus the next _ht.count-1 elements in the list.
07933 **
07934 ** Hash.htsize and Hash.ht may be zero.  In that case lookup is done
07935 ** by a linear search of the global list.  For small tables, the 
07936 ** Hash.ht table is never allocated because if there are few elements
07937 ** in the table, it is faster to do a linear search than to manage
07938 ** the hash table.
07939 */
07940 struct Hash {
07941   unsigned int htsize;      /* Number of buckets in the hash table */
07942   unsigned int count;       /* Number of entries in this table */
07943   HashElem *first;          /* The first element of the array */
07944   struct _ht {              /* the hash table */
07945     int count;                 /* Number of entries with this hash */
07946     HashElem *chain;           /* Pointer to first entry with this hash */
07947   } *ht;
07948 };
07949 
07950 /* Each element in the hash table is an instance of the following 
07951 ** structure.  All elements are stored on a single doubly-linked list.
07952 **
07953 ** Again, this structure is intended to be opaque, but it can't really
07954 ** be opaque because it is used by macros.
07955 */
07956 struct HashElem {
07957   HashElem *next, *prev;       /* Next and previous elements in the table */
07958   void *data;                  /* Data associated with this element */
07959   const char *pKey; int nKey;  /* Key associated with this element */
07960 };
07961 
07962 /*
07963 ** Access routines.  To delete, insert a NULL pointer.
07964 */
07965 SQLITE_PRIVATE void sqlite3HashInit(Hash*);
07966 SQLITE_PRIVATE void *sqlite3HashInsert(Hash*, const char *pKey, int nKey, void *pData);
07967 SQLITE_PRIVATE void *sqlite3HashFind(const Hash*, const char *pKey, int nKey);
07968 SQLITE_PRIVATE void sqlite3HashClear(Hash*);
07969 
07970 /*
07971 ** Macros for looping over all elements of a hash table.  The idiom is
07972 ** like this:
07973 **
07974 **   Hash h;
07975 **   HashElem *p;
07976 **   ...
07977 **   for(p=sqliteHashFirst(&h); p; p=sqliteHashNext(p)){
07978 **     SomeStructure *pData = sqliteHashData(p);
07979 **     // do something with pData
07980 **   }
07981 */
07982 #define sqliteHashFirst(H)  ((H)->first)
07983 #define sqliteHashNext(E)   ((E)->next)
07984 #define sqliteHashData(E)   ((E)->data)
07985 /* #define sqliteHashKey(E)    ((E)->pKey) // NOT USED */
07986 /* #define sqliteHashKeysize(E) ((E)->nKey)  // NOT USED */
07987 
07988 /*
07989 ** Number of entries in a hash table
07990 */
07991 /* #define sqliteHashCount(H)  ((H)->count) // NOT USED */
07992 
07993 #endif /* _SQLITE_HASH_H_ */
07994 
07995 /************** End of hash.h ************************************************/
07996 /************** Continuing where we left off in sqliteInt.h ******************/
07997 /************** Include parse.h in the middle of sqliteInt.h *****************/
07998 /************** Begin file parse.h *******************************************/
07999 #define TK_SEMI                            1
08000 #define TK_EXPLAIN                         2
08001 #define TK_QUERY                           3
08002 #define TK_PLAN                            4
08003 #define TK_BEGIN                           5
08004 #define TK_TRANSACTION                     6
08005 #define TK_DEFERRED                        7
08006 #define TK_IMMEDIATE                       8
08007 #define TK_EXCLUSIVE                       9
08008 #define TK_COMMIT                         10
08009 #define TK_END                            11
08010 #define TK_ROLLBACK                       12
08011 #define TK_SAVEPOINT                      13
08012 #define TK_RELEASE                        14
08013 #define TK_TO                             15
08014 #define TK_TABLE                          16
08015 #define TK_CREATE                         17
08016 #define TK_IF                             18
08017 #define TK_NOT                            19
08018 #define TK_EXISTS                         20
08019 #define TK_TEMP                           21
08020 #define TK_LP                             22
08021 #define TK_RP                             23
08022 #define TK_AS                             24
08023 #define TK_WITHOUT                        25
08024 #define TK_COMMA                          26
08025 #define TK_ID                             27
08026 #define TK_INDEXED                        28
08027 #define TK_ABORT                          29
08028 #define TK_ACTION                         30
08029 #define TK_AFTER                          31
08030 #define TK_ANALYZE                        32
08031 #define TK_ASC                            33
08032 #define TK_ATTACH                         34
08033 #define TK_BEFORE                         35
08034 #define TK_BY                             36
08035 #define TK_CASCADE                        37
08036 #define TK_CAST                           38
08037 #define TK_COLUMNKW                       39
08038 #define TK_CONFLICT                       40
08039 #define TK_DATABASE                       41
08040 #define TK_DESC                           42
08041 #define TK_DETACH                         43
08042 #define TK_EACH                           44
08043 #define TK_FAIL                           45
08044 #define TK_FOR                            46
08045 #define TK_IGNORE                         47
08046 #define TK_INITIALLY                      48
08047 #define TK_INSTEAD                        49
08048 #define TK_LIKE_KW                        50
08049 #define TK_MATCH                          51
08050 #define TK_NO                             52
08051 #define TK_KEY                            53
08052 #define TK_OF                             54
08053 #define TK_OFFSET                         55
08054 #define TK_PRAGMA                         56
08055 #define TK_RAISE                          57
08056 #define TK_REPLACE                        58
08057 #define TK_RESTRICT                       59
08058 #define TK_ROW                            60
08059 #define TK_TRIGGER                        61
08060 #define TK_VACUUM                         62
08061 #define TK_VIEW                           63
08062 #define TK_VIRTUAL                        64
08063 #define TK_REINDEX                        65
08064 #define TK_RENAME                         66
08065 #define TK_CTIME_KW                       67
08066 #define TK_ANY                            68
08067 #define TK_OR                             69
08068 #define TK_AND                            70
08069 #define TK_IS                             71
08070 #define TK_BETWEEN                        72
08071 #define TK_IN                             73
08072 #define TK_ISNULL                         74
08073 #define TK_NOTNULL                        75
08074 #define TK_NE                             76
08075 #define TK_EQ                             77
08076 #define TK_GT                             78
08077 #define TK_LE                             79
08078 #define TK_LT                             80
08079 #define TK_GE                             81
08080 #define TK_ESCAPE                         82
08081 #define TK_BITAND                         83
08082 #define TK_BITOR                          84
08083 #define TK_LSHIFT                         85
08084 #define TK_RSHIFT                         86
08085 #define TK_PLUS                           87
08086 #define TK_MINUS                          88
08087 #define TK_STAR                           89
08088 #define TK_SLASH                          90
08089 #define TK_REM                            91
08090 #define TK_CONCAT                         92
08091 #define TK_COLLATE                        93
08092 #define TK_BITNOT                         94
08093 #define TK_STRING                         95
08094 #define TK_JOIN_KW                        96
08095 #define TK_CONSTRAINT                     97
08096 #define TK_DEFAULT                        98
08097 #define TK_NULL                           99
08098 #define TK_PRIMARY                        100
08099 #define TK_UNIQUE                         101
08100 #define TK_CHECK                          102
08101 #define TK_REFERENCES                     103
08102 #define TK_AUTOINCR                       104
08103 #define TK_ON                             105
08104 #define TK_INSERT                         106
08105 #define TK_DELETE                         107
08106 #define TK_UPDATE                         108
08107 #define TK_SET                            109
08108 #define TK_DEFERRABLE                     110
08109 #define TK_FOREIGN                        111
08110 #define TK_DROP                           112
08111 #define TK_UNION                          113
08112 #define TK_ALL                            114
08113 #define TK_EXCEPT                         115
08114 #define TK_INTERSECT                      116
08115 #define TK_SELECT                         117
08116 #define TK_DISTINCT                       118
08117 #define TK_DOT                            119
08118 #define TK_FROM                           120
08119 #define TK_JOIN                           121
08120 #define TK_USING                          122
08121 #define TK_ORDER                          123
08122 #define TK_GROUP                          124
08123 #define TK_HAVING                         125
08124 #define TK_LIMIT                          126
08125 #define TK_WHERE                          127
08126 #define TK_INTO                           128
08127 #define TK_VALUES                         129
08128 #define TK_INTEGER                        130
08129 #define TK_FLOAT                          131
08130 #define TK_BLOB                           132
08131 #define TK_REGISTER                       133
08132 #define TK_VARIABLE                       134
08133 #define TK_CASE                           135
08134 #define TK_WHEN                           136
08135 #define TK_THEN                           137
08136 #define TK_ELSE                           138
08137 #define TK_INDEX                          139
08138 #define TK_ALTER                          140
08139 #define TK_ADD                            141
08140 #define TK_TO_TEXT                        142
08141 #define TK_TO_BLOB                        143
08142 #define TK_TO_NUMERIC                     144
08143 #define TK_TO_INT                         145
08144 #define TK_TO_REAL                        146
08145 #define TK_ISNOT                          147
08146 #define TK_END_OF_FILE                    148
08147 #define TK_ILLEGAL                        149
08148 #define TK_SPACE                          150
08149 #define TK_UNCLOSED_STRING                151
08150 #define TK_FUNCTION                       152
08151 #define TK_COLUMN                         153
08152 #define TK_AGG_FUNCTION                   154
08153 #define TK_AGG_COLUMN                     155
08154 #define TK_UMINUS                         156
08155 #define TK_UPLUS                          157
08156 
08157 /************** End of parse.h ***********************************************/
08158 /************** Continuing where we left off in sqliteInt.h ******************/
08159 #include <stdio.h>
08160 #include <stdlib.h>
08161 #include <string.h>
08162 #include <assert.h>
08163 #include <stddef.h>
08164 
08165 /*
08166 ** If compiling for a processor that lacks floating point support,
08167 ** substitute integer for floating-point
08168 */
08169 #ifdef SQLITE_OMIT_FLOATING_POINT
08170 # define double sqlite_int64
08171 # define float sqlite_int64
08172 # define LONGDOUBLE_TYPE sqlite_int64
08173 # ifndef SQLITE_BIG_DBL
08174 #   define SQLITE_BIG_DBL (((sqlite3_int64)1)<<50)
08175 # endif
08176 # define SQLITE_OMIT_DATETIME_FUNCS 1
08177 # define SQLITE_OMIT_TRACE 1
08178 # undef SQLITE_MIXED_ENDIAN_64BIT_FLOAT
08179 # undef SQLITE_HAVE_ISNAN
08180 #endif
08181 #ifndef SQLITE_BIG_DBL
08182 # define SQLITE_BIG_DBL (1e99)
08183 #endif
08184 
08185 /*
08186 ** OMIT_TEMPDB is set to 1 if SQLITE_OMIT_TEMPDB is defined, or 0
08187 ** afterward. Having this macro allows us to cause the C compiler 
08188 ** to omit code used by TEMP tables without messy #ifndef statements.
08189 */
08190 #ifdef SQLITE_OMIT_TEMPDB
08191 #define OMIT_TEMPDB 1
08192 #else
08193 #define OMIT_TEMPDB 0
08194 #endif
08195 
08196 /*
08197 ** The "file format" number is an integer that is incremented whenever
08198 ** the VDBE-level file format changes.  The following macros define the
08199 ** the default file format for new databases and the maximum file format
08200 ** that the library can read.
08201 */
08202 #define SQLITE_MAX_FILE_FORMAT 4
08203 #ifndef SQLITE_DEFAULT_FILE_FORMAT
08204 # define SQLITE_DEFAULT_FILE_FORMAT 4
08205 #endif
08206 
08207 /*
08208 ** Determine whether triggers are recursive by default.  This can be
08209 ** changed at run-time using a pragma.
08210 */
08211 #ifndef SQLITE_DEFAULT_RECURSIVE_TRIGGERS
08212 # define SQLITE_DEFAULT_RECURSIVE_TRIGGERS 0
08213 #endif
08214 
08215 /*
08216 ** Provide a default value for SQLITE_TEMP_STORE in case it is not specified
08217 ** on the command-line
08218 */
08219 #ifndef SQLITE_TEMP_STORE
08220 # define SQLITE_TEMP_STORE 1
08221 # define SQLITE_TEMP_STORE_xc 1  /* Exclude from ctime.c */
08222 #endif
08223 
08224 /*
08225 ** GCC does not define the offsetof() macro so we'll have to do it
08226 ** ourselves.
08227 */
08228 #ifndef offsetof
08229 #define offsetof(STRUCTURE,FIELD) ((int)((char*)&((STRUCTURE*)0)->FIELD))
08230 #endif
08231 
08232 /*
08233 ** Macros to compute minimum and maximum of two numbers.
08234 */
08235 #define MIN(A,B) ((A)<(B)?(A):(B))
08236 #define MAX(A,B) ((A)>(B)?(A):(B))
08237 
08238 /*
08239 ** Check to see if this machine uses EBCDIC.  (Yes, believe it or
08240 ** not, there are still machines out there that use EBCDIC.)
08241 */
08242 #if 'A' == '\301'
08243 # define SQLITE_EBCDIC 1
08244 #else
08245 # define SQLITE_ASCII 1
08246 #endif
08247 
08248 /*
08249 ** Integers of known sizes.  These typedefs might change for architectures
08250 ** where the sizes very.  Preprocessor macros are available so that the
08251 ** types can be conveniently redefined at compile-type.  Like this:
08252 **
08253 **         cc '-DUINTPTR_TYPE=long long int' ...
08254 */
08255 #ifndef UINT32_TYPE
08256 # ifdef HAVE_UINT32_T
08257 #  define UINT32_TYPE uint32_t
08258 # else
08259 #  define UINT32_TYPE unsigned int
08260 # endif
08261 #endif
08262 #ifndef UINT16_TYPE
08263 # ifdef HAVE_UINT16_T
08264 #  define UINT16_TYPE uint16_t
08265 # else
08266 #  define UINT16_TYPE unsigned short int
08267 # endif
08268 #endif
08269 #ifndef INT16_TYPE
08270 # ifdef HAVE_INT16_T
08271 #  define INT16_TYPE int16_t
08272 # else
08273 #  define INT16_TYPE short int
08274 # endif
08275 #endif
08276 #ifndef UINT8_TYPE
08277 # ifdef HAVE_UINT8_T
08278 #  define UINT8_TYPE uint8_t
08279 # else
08280 #  define UINT8_TYPE unsigned char
08281 # endif
08282 #endif
08283 #ifndef INT8_TYPE
08284 # ifdef HAVE_INT8_T
08285 #  define INT8_TYPE int8_t
08286 # else
08287 #  define INT8_TYPE signed char
08288 # endif
08289 #endif
08290 #ifndef LONGDOUBLE_TYPE
08291 # define LONGDOUBLE_TYPE long double
08292 #endif
08293 typedef sqlite_int64 i64;          /* 8-byte signed integer */
08294 typedef sqlite_uint64 u64;         /* 8-byte unsigned integer */
08295 typedef UINT32_TYPE u32;           /* 4-byte unsigned integer */
08296 typedef UINT16_TYPE u16;           /* 2-byte unsigned integer */
08297 typedef INT16_TYPE i16;            /* 2-byte signed integer */
08298 typedef UINT8_TYPE u8;             /* 1-byte unsigned integer */
08299 typedef INT8_TYPE i8;              /* 1-byte signed integer */
08300 
08301 /*
08302 ** SQLITE_MAX_U32 is a u64 constant that is the maximum u64 value
08303 ** that can be stored in a u32 without loss of data.  The value
08304 ** is 0x00000000ffffffff.  But because of quirks of some compilers, we
08305 ** have to specify the value in the less intuitive manner shown:
08306 */
08307 #define SQLITE_MAX_U32  ((((u64)1)<<32)-1)
08308 
08309 /*
08310 ** The datatype used to store estimates of the number of rows in a
08311 ** table or index.  This is an unsigned integer type.  For 99.9% of
08312 ** the world, a 32-bit integer is sufficient.  But a 64-bit integer
08313 ** can be used at compile-time if desired.
08314 */
08315 #ifdef SQLITE_64BIT_STATS
08316  typedef u64 tRowcnt;    /* 64-bit only if requested at compile-time */
08317 #else
08318  typedef u32 tRowcnt;    /* 32-bit is the default */
08319 #endif
08320 
08321 /*
08322 ** Estimated quantities used for query planning are stored as 16-bit
08323 ** logarithms.  For quantity X, the value stored is 10*log2(X).  This
08324 ** gives a possible range of values of approximately 1.0e986 to 1e-986.
08325 ** But the allowed values are "grainy".  Not every value is representable.
08326 ** For example, quantities 16 and 17 are both represented by a LogEst
08327 ** of 40.  However, since LogEst quantatites are suppose to be estimates,
08328 ** not exact values, this imprecision is not a problem.
08329 **
08330 ** "LogEst" is short for "Logarithimic Estimate".
08331 **
08332 ** Examples:
08333 **      1 -> 0              20 -> 43          10000 -> 132
08334 **      2 -> 10             25 -> 46          25000 -> 146
08335 **      3 -> 16            100 -> 66        1000000 -> 199
08336 **      4 -> 20           1000 -> 99        1048576 -> 200
08337 **     10 -> 33           1024 -> 100    4294967296 -> 320
08338 **
08339 ** The LogEst can be negative to indicate fractional values. 
08340 ** Examples:
08341 **
08342 **    0.5 -> -10           0.1 -> -33        0.0625 -> -40
08343 */
08344 typedef INT16_TYPE LogEst;
08345 
08346 /*
08347 ** Macros to determine whether the machine is big or little endian,
08348 ** evaluated at runtime.
08349 */
08350 #ifdef SQLITE_AMALGAMATION
08351 SQLITE_PRIVATE const int sqlite3one = 1;
08352 #else
08353 SQLITE_PRIVATE const int sqlite3one;
08354 #endif
08355 #if defined(i386) || defined(__i386__) || defined(_M_IX86)\
08356                              || defined(__x86_64) || defined(__x86_64__)
08357 # define SQLITE_BIGENDIAN    0
08358 # define SQLITE_LITTLEENDIAN 1
08359 # define SQLITE_UTF16NATIVE  SQLITE_UTF16LE
08360 #else
08361 # define SQLITE_BIGENDIAN    (*(char *)(&sqlite3one)==0)
08362 # define SQLITE_LITTLEENDIAN (*(char *)(&sqlite3one)==1)
08363 # define SQLITE_UTF16NATIVE (SQLITE_BIGENDIAN?SQLITE_UTF16BE:SQLITE_UTF16LE)
08364 #endif
08365 
08366 /*
08367 ** Constants for the largest and smallest possible 64-bit signed integers.
08368 ** These macros are designed to work correctly on both 32-bit and 64-bit
08369 ** compilers.
08370 */
08371 #define LARGEST_INT64  (0xffffffff|(((i64)0x7fffffff)<<32))
08372 #define SMALLEST_INT64 (((i64)-1) - LARGEST_INT64)
08373 
08374 /* 
08375 ** Round up a number to the next larger multiple of 8.  This is used
08376 ** to force 8-byte alignment on 64-bit architectures.
08377 */
08378 #define ROUND8(x)     (((x)+7)&~7)
08379 
08380 /*
08381 ** Round down to the nearest multiple of 8
08382 */
08383 #define ROUNDDOWN8(x) ((x)&~7)
08384 
08385 /*
08386 ** Assert that the pointer X is aligned to an 8-byte boundary.  This
08387 ** macro is used only within assert() to verify that the code gets
08388 ** all alignment restrictions correct.
08389 **
08390 ** Except, if SQLITE_4_BYTE_ALIGNED_MALLOC is defined, then the
08391 ** underlying malloc() implemention might return us 4-byte aligned
08392 ** pointers.  In that case, only verify 4-byte alignment.
08393 */
08394 #ifdef SQLITE_4_BYTE_ALIGNED_MALLOC
08395 # define EIGHT_BYTE_ALIGNMENT(X)   ((((char*)(X) - (char*)0)&3)==0)
08396 #else
08397 # define EIGHT_BYTE_ALIGNMENT(X)   ((((char*)(X) - (char*)0)&7)==0)
08398 #endif
08399 
08400 /*
08401 ** Disable MMAP on platforms where it is known to not work
08402 */
08403 #if defined(__OpenBSD__) || defined(__QNXNTO__)
08404 # undef SQLITE_MAX_MMAP_SIZE
08405 # define SQLITE_MAX_MMAP_SIZE 0
08406 #endif
08407 
08408 /*
08409 ** Default maximum size of memory used by memory-mapped I/O in the VFS
08410 */
08411 #ifdef __APPLE__
08412 # include <TargetConditionals.h>
08413 # if TARGET_OS_IPHONE
08414 #   undef SQLITE_MAX_MMAP_SIZE
08415 #   define SQLITE_MAX_MMAP_SIZE 0
08416 # endif
08417 #endif
08418 #ifndef SQLITE_MAX_MMAP_SIZE
08419 # if defined(__linux__) \
08420   || defined(_WIN32) \
08421   || (defined(__APPLE__) && defined(__MACH__)) \
08422   || defined(__sun)
08423 #   define SQLITE_MAX_MMAP_SIZE 0x7fff0000  /* 2147418112 */
08424 # else
08425 #   define SQLITE_MAX_MMAP_SIZE 0
08426 # endif
08427 # define SQLITE_MAX_MMAP_SIZE_xc 1 /* exclude from ctime.c */
08428 #endif
08429 
08430 /*
08431 ** The default MMAP_SIZE is zero on all platforms.  Or, even if a larger
08432 ** default MMAP_SIZE is specified at compile-time, make sure that it does
08433 ** not exceed the maximum mmap size.
08434 */
08435 #ifndef SQLITE_DEFAULT_MMAP_SIZE
08436 # define SQLITE_DEFAULT_MMAP_SIZE 0
08437 # define SQLITE_DEFAULT_MMAP_SIZE_xc 1  /* Exclude from ctime.c */
08438 #endif
08439 #if SQLITE_DEFAULT_MMAP_SIZE>SQLITE_MAX_MMAP_SIZE
08440 # undef SQLITE_DEFAULT_MMAP_SIZE
08441 # define SQLITE_DEFAULT_MMAP_SIZE SQLITE_MAX_MMAP_SIZE
08442 #endif
08443 
08444 /*
08445 ** Only one of SQLITE_ENABLE_STAT3 or SQLITE_ENABLE_STAT4 can be defined.
08446 ** Priority is given to SQLITE_ENABLE_STAT4.  If either are defined, also
08447 ** define SQLITE_ENABLE_STAT3_OR_STAT4
08448 */
08449 #ifdef SQLITE_ENABLE_STAT4
08450 # undef SQLITE_ENABLE_STAT3
08451 # define SQLITE_ENABLE_STAT3_OR_STAT4 1
08452 #elif SQLITE_ENABLE_STAT3
08453 # define SQLITE_ENABLE_STAT3_OR_STAT4 1
08454 #elif SQLITE_ENABLE_STAT3_OR_STAT4
08455 # undef SQLITE_ENABLE_STAT3_OR_STAT4
08456 #endif
08457 
08458 /*
08459 ** An instance of the following structure is used to store the busy-handler
08460 ** callback for a given sqlite handle. 
08461 **
08462 ** The sqlite.busyHandler member of the sqlite struct contains the busy
08463 ** callback for the database handle. Each pager opened via the sqlite
08464 ** handle is passed a pointer to sqlite.busyHandler. The busy-handler
08465 ** callback is currently invoked only from within pager.c.
08466 */
08467 typedef struct BusyHandler BusyHandler;
08468 struct BusyHandler {
08469   int (*xFunc)(void *,int);  /* The busy callback */
08470   void *pArg;                /* First arg to busy callback */
08471   int nBusy;                 /* Incremented with each busy call */
08472 };
08473 
08474 /*
08475 ** Name of the master database table.  The master database table
08476 ** is a special table that holds the names and attributes of all
08477 ** user tables and indices.
08478 */
08479 #define MASTER_NAME       "sqlite_master"
08480 #define TEMP_MASTER_NAME  "sqlite_temp_master"
08481 
08482 /*
08483 ** The root-page of the master database table.
08484 */
08485 #define MASTER_ROOT       1
08486 
08487 /*
08488 ** The name of the schema table.
08489 */
08490 #define SCHEMA_TABLE(x)  ((!OMIT_TEMPDB)&&(x==1)?TEMP_MASTER_NAME:MASTER_NAME)
08491 
08492 /*
08493 ** A convenience macro that returns the number of elements in
08494 ** an array.
08495 */
08496 #define ArraySize(X)    ((int)(sizeof(X)/sizeof(X[0])))
08497 
08498 /*
08499 ** Determine if the argument is a power of two
08500 */
08501 #define IsPowerOfTwo(X) (((X)&((X)-1))==0)
08502 
08503 /*
08504 ** The following value as a destructor means to use sqlite3DbFree().
08505 ** The sqlite3DbFree() routine requires two parameters instead of the 
08506 ** one parameter that destructors normally want.  So we have to introduce 
08507 ** this magic value that the code knows to handle differently.  Any 
08508 ** pointer will work here as long as it is distinct from SQLITE_STATIC
08509 ** and SQLITE_TRANSIENT.
08510 */
08511 #define SQLITE_DYNAMIC   ((sqlite3_destructor_type)sqlite3MallocSize)
08512 
08513 /*
08514 ** When SQLITE_OMIT_WSD is defined, it means that the target platform does
08515 ** not support Writable Static Data (WSD) such as global and static variables.
08516 ** All variables must either be on the stack or dynamically allocated from
08517 ** the heap.  When WSD is unsupported, the variable declarations scattered
08518 ** throughout the SQLite code must become constants instead.  The SQLITE_WSD
08519 ** macro is used for this purpose.  And instead of referencing the variable
08520 ** directly, we use its constant as a key to lookup the run-time allocated
08521 ** buffer that holds real variable.  The constant is also the initializer
08522 ** for the run-time allocated buffer.
08523 **
08524 ** In the usual case where WSD is supported, the SQLITE_WSD and GLOBAL
08525 ** macros become no-ops and have zero performance impact.
08526 */
08527 #ifdef SQLITE_OMIT_WSD
08528   #define SQLITE_WSD const
08529   #define GLOBAL(t,v) (*(t*)sqlite3_wsd_find((void*)&(v), sizeof(v)))
08530   #define sqlite3GlobalConfig GLOBAL(struct Sqlite3Config, sqlite3Config)
08531 SQLITE_API   int sqlite3_wsd_init(int N, int J);
08532 SQLITE_API   void *sqlite3_wsd_find(void *K, int L);
08533 #else
08534   #define SQLITE_WSD 
08535   #define GLOBAL(t,v) v
08536   #define sqlite3GlobalConfig sqlite3Config
08537 #endif
08538 
08539 /*
08540 ** The following macros are used to suppress compiler warnings and to
08541 ** make it clear to human readers when a function parameter is deliberately 
08542 ** left unused within the body of a function. This usually happens when
08543 ** a function is called via a function pointer. For example the 
08544 ** implementation of an SQL aggregate step callback may not use the
08545 ** parameter indicating the number of arguments passed to the aggregate,
08546 ** if it knows that this is enforced elsewhere.
08547 **
08548 ** When a function parameter is not used at all within the body of a function,
08549 ** it is generally named "NotUsed" or "NotUsed2" to make things even clearer.
08550 ** However, these macros may also be used to suppress warnings related to
08551 ** parameters that may or may not be used depending on compilation options.
08552 ** For example those parameters only used in assert() statements. In these
08553 ** cases the parameters are named as per the usual conventions.
08554 */
08555 #define UNUSED_PARAMETER(x) (void)(x)
08556 #define UNUSED_PARAMETER2(x,y) UNUSED_PARAMETER(x),UNUSED_PARAMETER(y)
08557 
08558 /*
08559 ** Forward references to structures
08560 */
08561 typedef struct AggInfo AggInfo;
08562 typedef struct AuthContext AuthContext;
08563 typedef struct AutoincInfo AutoincInfo;
08564 typedef struct Bitvec Bitvec;
08565 typedef struct CollSeq CollSeq;
08566 typedef struct Column Column;
08567 typedef struct Db Db;
08568 typedef struct Schema Schema;
08569 typedef struct Expr Expr;
08570 typedef struct ExprList ExprList;
08571 typedef struct ExprSpan ExprSpan;
08572 typedef struct FKey FKey;
08573 typedef struct FuncDestructor FuncDestructor;
08574 typedef struct FuncDef FuncDef;
08575 typedef struct FuncDefHash FuncDefHash;
08576 typedef struct IdList IdList;
08577 typedef struct Index Index;
08578 typedef struct IndexSample IndexSample;
08579 typedef struct KeyClass KeyClass;
08580 typedef struct KeyInfo KeyInfo;
08581 typedef struct Lookaside Lookaside;
08582 typedef struct LookasideSlot LookasideSlot;
08583 typedef struct Module Module;
08584 typedef struct NameContext NameContext;
08585 typedef struct Parse Parse;
08586 typedef struct RowSet RowSet;
08587 typedef struct Savepoint Savepoint;
08588 typedef struct Select Select;
08589 typedef struct SelectDest SelectDest;
08590 typedef struct SrcList SrcList;
08591 typedef struct StrAccum StrAccum;
08592 typedef struct Table Table;
08593 typedef struct TableLock TableLock;
08594 typedef struct Token Token;
08595 typedef struct Trigger Trigger;
08596 typedef struct TriggerPrg TriggerPrg;
08597 typedef struct TriggerStep TriggerStep;
08598 typedef struct UnpackedRecord UnpackedRecord;
08599 typedef struct VTable VTable;
08600 typedef struct VtabCtx VtabCtx;
08601 typedef struct Walker Walker;
08602 typedef struct WhereInfo WhereInfo;
08603 
08604 /*
08605 ** Defer sourcing vdbe.h and btree.h until after the "u8" and 
08606 ** "BusyHandler" typedefs. vdbe.h also requires a few of the opaque
08607 ** pointer types (i.e. FuncDef) defined above.
08608 */
08609 /************** Include btree.h in the middle of sqliteInt.h *****************/
08610 /************** Begin file btree.h *******************************************/
08611 /*
08612 ** 2001 September 15
08613 **
08614 ** The author disclaims copyright to this source code.  In place of
08615 ** a legal notice, here is a blessing:
08616 **
08617 **    May you do good and not evil.
08618 **    May you find forgiveness for yourself and forgive others.
08619 **    May you share freely, never taking more than you give.
08620 **
08621 *************************************************************************
08622 ** This header file defines the interface that the sqlite B-Tree file
08623 ** subsystem.  See comments in the source code for a detailed description
08624 ** of what each interface routine does.
08625 */
08626 #ifndef _BTREE_H_
08627 #define _BTREE_H_
08628 
08629 /* TODO: This definition is just included so other modules compile. It
08630 ** needs to be revisited.
08631 */
08632 #define SQLITE_N_BTREE_META 10
08633 
08634 /*
08635 ** If defined as non-zero, auto-vacuum is enabled by default. Otherwise
08636 ** it must be turned on for each database using "PRAGMA auto_vacuum = 1".
08637 */
08638 #ifndef SQLITE_DEFAULT_AUTOVACUUM
08639   #define SQLITE_DEFAULT_AUTOVACUUM 0
08640 #endif
08641 
08642 #define BTREE_AUTOVACUUM_NONE 0        /* Do not do auto-vacuum */
08643 #define BTREE_AUTOVACUUM_FULL 1        /* Do full auto-vacuum */
08644 #define BTREE_AUTOVACUUM_INCR 2        /* Incremental vacuum */
08645 
08646 /*
08647 ** Forward declarations of structure
08648 */
08649 typedef struct Btree Btree;
08650 typedef struct BtCursor BtCursor;
08651 typedef struct BtShared BtShared;
08652 
08653 
08654 SQLITE_PRIVATE int sqlite3BtreeOpen(
08655   sqlite3_vfs *pVfs,       /* VFS to use with this b-tree */
08656   const char *zFilename,   /* Name of database file to open */
08657   sqlite3 *db,             /* Associated database connection */
08658   Btree **ppBtree,         /* Return open Btree* here */
08659   int flags,               /* Flags */
08660   int vfsFlags             /* Flags passed through to VFS open */
08661 );
08662 
08663 /* The flags parameter to sqlite3BtreeOpen can be the bitwise or of the
08664 ** following values.
08665 **
08666 ** NOTE:  These values must match the corresponding PAGER_ values in
08667 ** pager.h.
08668 */
08669 #define BTREE_OMIT_JOURNAL  1  /* Do not create or use a rollback journal */
08670 #define BTREE_MEMORY        2  /* This is an in-memory DB */
08671 #define BTREE_SINGLE        4  /* The file contains at most 1 b-tree */
08672 #define BTREE_UNORDERED     8  /* Use of a hash implementation is OK */
08673 
08674 SQLITE_PRIVATE int sqlite3BtreeClose(Btree*);
08675 SQLITE_PRIVATE int sqlite3BtreeSetCacheSize(Btree*,int);
08676 SQLITE_PRIVATE int sqlite3BtreeSetMmapLimit(Btree*,sqlite3_int64);
08677 SQLITE_PRIVATE int sqlite3BtreeSetPagerFlags(Btree*,unsigned);
08678 SQLITE_PRIVATE int sqlite3BtreeSyncDisabled(Btree*);
08679 SQLITE_PRIVATE int sqlite3BtreeSetPageSize(Btree *p, int nPagesize, int nReserve, int eFix);
08680 SQLITE_PRIVATE int sqlite3BtreeGetPageSize(Btree*);
08681 SQLITE_PRIVATE int sqlite3BtreeMaxPageCount(Btree*,int);
08682 SQLITE_PRIVATE u32 sqlite3BtreeLastPage(Btree*);
08683 SQLITE_PRIVATE int sqlite3BtreeSecureDelete(Btree*,int);
08684 SQLITE_PRIVATE int sqlite3BtreeGetReserve(Btree*);
08685 #if defined(SQLITE_HAS_CODEC) || defined(SQLITE_DEBUG)
08686 SQLITE_PRIVATE int sqlite3BtreeGetReserveNoMutex(Btree *p);
08687 #endif
08688 SQLITE_PRIVATE int sqlite3BtreeSetAutoVacuum(Btree *, int);
08689 SQLITE_PRIVATE int sqlite3BtreeGetAutoVacuum(Btree *);
08690 SQLITE_PRIVATE int sqlite3BtreeBeginTrans(Btree*,int);
08691 SQLITE_PRIVATE int sqlite3BtreeCommitPhaseOne(Btree*, const char *zMaster);
08692 SQLITE_PRIVATE int sqlite3BtreeCommitPhaseTwo(Btree*, int);
08693 SQLITE_PRIVATE int sqlite3BtreeCommit(Btree*);
08694 SQLITE_PRIVATE int sqlite3BtreeRollback(Btree*,int);
08695 SQLITE_PRIVATE int sqlite3BtreeBeginStmt(Btree*,int);
08696 SQLITE_PRIVATE int sqlite3BtreeCreateTable(Btree*, int*, int flags);
08697 SQLITE_PRIVATE int sqlite3BtreeIsInTrans(Btree*);
08698 SQLITE_PRIVATE int sqlite3BtreeIsInReadTrans(Btree*);
08699 SQLITE_PRIVATE int sqlite3BtreeIsInBackup(Btree*);
08700 SQLITE_PRIVATE void *sqlite3BtreeSchema(Btree *, int, void(*)(void *));
08701 SQLITE_PRIVATE int sqlite3BtreeSchemaLocked(Btree *pBtree);
08702 SQLITE_PRIVATE int sqlite3BtreeLockTable(Btree *pBtree, int iTab, u8 isWriteLock);
08703 SQLITE_PRIVATE int sqlite3BtreeSavepoint(Btree *, int, int);
08704 
08705 SQLITE_PRIVATE const char *sqlite3BtreeGetFilename(Btree *);
08706 SQLITE_PRIVATE const char *sqlite3BtreeGetJournalname(Btree *);
08707 SQLITE_PRIVATE int sqlite3BtreeCopyFile(Btree *, Btree *);
08708 
08709 SQLITE_PRIVATE int sqlite3BtreeIncrVacuum(Btree *);
08710 
08711 /* The flags parameter to sqlite3BtreeCreateTable can be the bitwise OR
08712 ** of the flags shown below.
08713 **
08714 ** Every SQLite table must have either BTREE_INTKEY or BTREE_BLOBKEY set.
08715 ** With BTREE_INTKEY, the table key is a 64-bit integer and arbitrary data
08716 ** is stored in the leaves.  (BTREE_INTKEY is used for SQL tables.)  With
08717 ** BTREE_BLOBKEY, the key is an arbitrary BLOB and no content is stored
08718 ** anywhere - the key is the content.  (BTREE_BLOBKEY is used for SQL
08719 ** indices.)
08720 */
08721 #define BTREE_INTKEY     1    /* Table has only 64-bit signed integer keys */
08722 #define BTREE_BLOBKEY    2    /* Table has keys only - no data */
08723 
08724 SQLITE_PRIVATE int sqlite3BtreeDropTable(Btree*, int, int*);
08725 SQLITE_PRIVATE int sqlite3BtreeClearTable(Btree*, int, int*);
08726 SQLITE_PRIVATE void sqlite3BtreeTripAllCursors(Btree*, int);
08727 
08728 SQLITE_PRIVATE void sqlite3BtreeGetMeta(Btree *pBtree, int idx, u32 *pValue);
08729 SQLITE_PRIVATE int sqlite3BtreeUpdateMeta(Btree*, int idx, u32 value);
08730 
08731 SQLITE_PRIVATE int sqlite3BtreeNewDb(Btree *p);
08732 
08733 /*
08734 ** The second parameter to sqlite3BtreeGetMeta or sqlite3BtreeUpdateMeta
08735 ** should be one of the following values. The integer values are assigned 
08736 ** to constants so that the offset of the corresponding field in an
08737 ** SQLite database header may be found using the following formula:
08738 **
08739 **   offset = 36 + (idx * 4)
08740 **
08741 ** For example, the free-page-count field is located at byte offset 36 of
08742 ** the database file header. The incr-vacuum-flag field is located at
08743 ** byte offset 64 (== 36+4*7).
08744 */
08745 #define BTREE_FREE_PAGE_COUNT     0
08746 #define BTREE_SCHEMA_VERSION      1
08747 #define BTREE_FILE_FORMAT         2
08748 #define BTREE_DEFAULT_CACHE_SIZE  3
08749 #define BTREE_LARGEST_ROOT_PAGE   4
08750 #define BTREE_TEXT_ENCODING       5
08751 #define BTREE_USER_VERSION        6
08752 #define BTREE_INCR_VACUUM         7
08753 #define BTREE_APPLICATION_ID      8
08754 
08755 /*
08756 ** Values that may be OR'd together to form the second argument of an
08757 ** sqlite3BtreeCursorHints() call.
08758 */
08759 #define BTREE_BULKLOAD 0x00000001
08760 
08761 SQLITE_PRIVATE int sqlite3BtreeCursor(
08762   Btree*,                              /* BTree containing table to open */
08763   int iTable,                          /* Index of root page */
08764   int wrFlag,                          /* 1 for writing.  0 for read-only */
08765   struct KeyInfo*,                     /* First argument to compare function */
08766   BtCursor *pCursor                    /* Space to write cursor structure */
08767 );
08768 SQLITE_PRIVATE int sqlite3BtreeCursorSize(void);
08769 SQLITE_PRIVATE void sqlite3BtreeCursorZero(BtCursor*);
08770 
08771 SQLITE_PRIVATE int sqlite3BtreeCloseCursor(BtCursor*);
08772 SQLITE_PRIVATE int sqlite3BtreeMovetoUnpacked(
08773   BtCursor*,
08774   UnpackedRecord *pUnKey,
08775   i64 intKey,
08776   int bias,
08777   int *pRes
08778 );
08779 SQLITE_PRIVATE int sqlite3BtreeCursorHasMoved(BtCursor*, int*);
08780 SQLITE_PRIVATE int sqlite3BtreeDelete(BtCursor*);
08781 SQLITE_PRIVATE int sqlite3BtreeInsert(BtCursor*, const void *pKey, i64 nKey,
08782                                   const void *pData, int nData,
08783                                   int nZero, int bias, int seekResult);
08784 SQLITE_PRIVATE int sqlite3BtreeFirst(BtCursor*, int *pRes);
08785 SQLITE_PRIVATE int sqlite3BtreeLast(BtCursor*, int *pRes);
08786 SQLITE_PRIVATE int sqlite3BtreeNext(BtCursor*, int *pRes);
08787 SQLITE_PRIVATE int sqlite3BtreeEof(BtCursor*);
08788 SQLITE_PRIVATE int sqlite3BtreePrevious(BtCursor*, int *pRes);
08789 SQLITE_PRIVATE int sqlite3BtreeKeySize(BtCursor*, i64 *pSize);
08790 SQLITE_PRIVATE int sqlite3BtreeKey(BtCursor*, u32 offset, u32 amt, void*);
08791 SQLITE_PRIVATE const void *sqlite3BtreeKeyFetch(BtCursor*, u32 *pAmt);
08792 SQLITE_PRIVATE const void *sqlite3BtreeDataFetch(BtCursor*, u32 *pAmt);
08793 SQLITE_PRIVATE int sqlite3BtreeDataSize(BtCursor*, u32 *pSize);
08794 SQLITE_PRIVATE int sqlite3BtreeData(BtCursor*, u32 offset, u32 amt, void*);
08795 SQLITE_PRIVATE void sqlite3BtreeSetCachedRowid(BtCursor*, sqlite3_int64);
08796 SQLITE_PRIVATE sqlite3_int64 sqlite3BtreeGetCachedRowid(BtCursor*);
08797 
08798 SQLITE_PRIVATE char *sqlite3BtreeIntegrityCheck(Btree*, int *aRoot, int nRoot, int, int*);
08799 SQLITE_PRIVATE struct Pager *sqlite3BtreePager(Btree*);
08800 
08801 SQLITE_PRIVATE int sqlite3BtreePutData(BtCursor*, u32 offset, u32 amt, void*);
08802 SQLITE_PRIVATE void sqlite3BtreeCacheOverflow(BtCursor *);
08803 SQLITE_PRIVATE void sqlite3BtreeClearCursor(BtCursor *);
08804 SQLITE_PRIVATE int sqlite3BtreeSetVersion(Btree *pBt, int iVersion);
08805 SQLITE_PRIVATE void sqlite3BtreeCursorHints(BtCursor *, unsigned int mask);
08806 
08807 #ifndef NDEBUG
08808 SQLITE_PRIVATE int sqlite3BtreeCursorIsValid(BtCursor*);
08809 #endif
08810 
08811 #ifndef SQLITE_OMIT_BTREECOUNT
08812 SQLITE_PRIVATE int sqlite3BtreeCount(BtCursor *, i64 *);
08813 #endif
08814 
08815 #ifdef SQLITE_TEST
08816 SQLITE_PRIVATE int sqlite3BtreeCursorInfo(BtCursor*, int*, int);
08817 SQLITE_PRIVATE void sqlite3BtreeCursorList(Btree*);
08818 #endif
08819 
08820 #ifndef SQLITE_OMIT_WAL
08821 SQLITE_PRIVATE   int sqlite3BtreeCheckpoint(Btree*, int, int *, int *);
08822 #endif
08823 
08824 /*
08825 ** If we are not using shared cache, then there is no need to
08826 ** use mutexes to access the BtShared structures.  So make the
08827 ** Enter and Leave procedures no-ops.
08828 */
08829 #ifndef SQLITE_OMIT_SHARED_CACHE
08830 SQLITE_PRIVATE   void sqlite3BtreeEnter(Btree*);
08831 SQLITE_PRIVATE   void sqlite3BtreeEnterAll(sqlite3*);
08832 #else
08833 # define sqlite3BtreeEnter(X) 
08834 # define sqlite3BtreeEnterAll(X)
08835 #endif
08836 
08837 #if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE
08838 SQLITE_PRIVATE   int sqlite3BtreeSharable(Btree*);
08839 SQLITE_PRIVATE   void sqlite3BtreeLeave(Btree*);
08840 SQLITE_PRIVATE   void sqlite3BtreeEnterCursor(BtCursor*);
08841 SQLITE_PRIVATE   void sqlite3BtreeLeaveCursor(BtCursor*);
08842 SQLITE_PRIVATE   void sqlite3BtreeLeaveAll(sqlite3*);
08843 #ifndef NDEBUG
08844   /* These routines are used inside assert() statements only. */
08845 SQLITE_PRIVATE   int sqlite3BtreeHoldsMutex(Btree*);
08846 SQLITE_PRIVATE   int sqlite3BtreeHoldsAllMutexes(sqlite3*);
08847 SQLITE_PRIVATE   int sqlite3SchemaMutexHeld(sqlite3*,int,Schema*);
08848 #endif
08849 #else
08850 
08851 # define sqlite3BtreeSharable(X) 0
08852 # define sqlite3BtreeLeave(X)
08853 # define sqlite3BtreeEnterCursor(X)
08854 # define sqlite3BtreeLeaveCursor(X)
08855 # define sqlite3BtreeLeaveAll(X)
08856 
08857 # define sqlite3BtreeHoldsMutex(X) 1
08858 # define sqlite3BtreeHoldsAllMutexes(X) 1
08859 # define sqlite3SchemaMutexHeld(X,Y,Z) 1
08860 #endif
08861 
08862 
08863 #endif /* _BTREE_H_ */
08864 
08865 /************** End of btree.h ***********************************************/
08866 /************** Continuing where we left off in sqliteInt.h ******************/
08867 /************** Include vdbe.h in the middle of sqliteInt.h ******************/
08868 /************** Begin file vdbe.h ********************************************/
08869 /*
08870 ** 2001 September 15
08871 **
08872 ** The author disclaims copyright to this source code.  In place of
08873 ** a legal notice, here is a blessing:
08874 **
08875 **    May you do good and not evil.
08876 **    May you find forgiveness for yourself and forgive others.
08877 **    May you share freely, never taking more than you give.
08878 **
08879 *************************************************************************
08880 ** Header file for the Virtual DataBase Engine (VDBE)
08881 **
08882 ** This header defines the interface to the virtual database engine
08883 ** or VDBE.  The VDBE implements an abstract machine that runs a
08884 ** simple program to access and modify the underlying database.
08885 */
08886 #ifndef _SQLITE_VDBE_H_
08887 #define _SQLITE_VDBE_H_
08888 /* #include <stdio.h> */
08889 
08890 /*
08891 ** A single VDBE is an opaque structure named "Vdbe".  Only routines
08892 ** in the source file sqliteVdbe.c are allowed to see the insides
08893 ** of this structure.
08894 */
08895 typedef struct Vdbe Vdbe;
08896 
08897 /*
08898 ** The names of the following types declared in vdbeInt.h are required
08899 ** for the VdbeOp definition.
08900 */
08901 typedef struct Mem Mem;
08902 typedef struct SubProgram SubProgram;
08903 
08904 /*
08905 ** A single instruction of the virtual machine has an opcode
08906 ** and as many as three operands.  The instruction is recorded
08907 ** as an instance of the following structure:
08908 */
08909 struct VdbeOp {
08910   u8 opcode;          /* What operation to perform */
08911   signed char p4type; /* One of the P4_xxx constants for p4 */
08912   u8 opflags;         /* Mask of the OPFLG_* flags in opcodes.h */
08913   u8 p5;              /* Fifth parameter is an unsigned character */
08914   int p1;             /* First operand */
08915   int p2;             /* Second parameter (often the jump destination) */
08916   int p3;             /* The third parameter */
08917   union {             /* fourth parameter */
08918     int i;                 /* Integer value if p4type==P4_INT32 */
08919     void *p;               /* Generic pointer */
08920     char *z;               /* Pointer to data for string (char array) types */
08921     i64 *pI64;             /* Used when p4type is P4_INT64 */
08922     double *pReal;         /* Used when p4type is P4_REAL */
08923     FuncDef *pFunc;        /* Used when p4type is P4_FUNCDEF */
08924     CollSeq *pColl;        /* Used when p4type is P4_COLLSEQ */
08925     Mem *pMem;             /* Used when p4type is P4_MEM */
08926     VTable *pVtab;         /* Used when p4type is P4_VTAB */
08927     KeyInfo *pKeyInfo;     /* Used when p4type is P4_KEYINFO */
08928     int *ai;               /* Used when p4type is P4_INTARRAY */
08929     SubProgram *pProgram;  /* Used when p4type is P4_SUBPROGRAM */
08930     int (*xAdvance)(BtCursor *, int *);
08931   } p4;
08932 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
08933   char *zComment;          /* Comment to improve readability */
08934 #endif
08935 #ifdef VDBE_PROFILE
08936   int cnt;                 /* Number of times this instruction was executed */
08937   u64 cycles;              /* Total time spent executing this instruction */
08938 #endif
08939 };
08940 typedef struct VdbeOp VdbeOp;
08941 
08942 
08943 /*
08944 ** A sub-routine used to implement a trigger program.
08945 */
08946 struct SubProgram {
08947   VdbeOp *aOp;                  /* Array of opcodes for sub-program */
08948   int nOp;                      /* Elements in aOp[] */
08949   int nMem;                     /* Number of memory cells required */
08950   int nCsr;                     /* Number of cursors required */
08951   int nOnce;                    /* Number of OP_Once instructions */
08952   void *token;                  /* id that may be used to recursive triggers */
08953   SubProgram *pNext;            /* Next sub-program already visited */
08954 };
08955 
08956 /*
08957 ** A smaller version of VdbeOp used for the VdbeAddOpList() function because
08958 ** it takes up less space.
08959 */
08960 struct VdbeOpList {
08961   u8 opcode;          /* What operation to perform */
08962   signed char p1;     /* First operand */
08963   signed char p2;     /* Second parameter (often the jump destination) */
08964   signed char p3;     /* Third parameter */
08965 };
08966 typedef struct VdbeOpList VdbeOpList;
08967 
08968 /*
08969 ** Allowed values of VdbeOp.p4type
08970 */
08971 #define P4_NOTUSED    0   /* The P4 parameter is not used */
08972 #define P4_DYNAMIC  (-1)  /* Pointer to a string obtained from sqliteMalloc() */
08973 #define P4_STATIC   (-2)  /* Pointer to a static string */
08974 #define P4_COLLSEQ  (-4)  /* P4 is a pointer to a CollSeq structure */
08975 #define P4_FUNCDEF  (-5)  /* P4 is a pointer to a FuncDef structure */
08976 #define P4_KEYINFO  (-6)  /* P4 is a pointer to a KeyInfo structure */
08977 #define P4_MEM      (-8)  /* P4 is a pointer to a Mem*    structure */
08978 #define P4_TRANSIENT  0   /* P4 is a pointer to a transient string */
08979 #define P4_VTAB     (-10) /* P4 is a pointer to an sqlite3_vtab structure */
08980 #define P4_MPRINTF  (-11) /* P4 is a string obtained from sqlite3_mprintf() */
08981 #define P4_REAL     (-12) /* P4 is a 64-bit floating point value */
08982 #define P4_INT64    (-13) /* P4 is a 64-bit signed integer */
08983 #define P4_INT32    (-14) /* P4 is a 32-bit signed integer */
08984 #define P4_INTARRAY (-15) /* P4 is a vector of 32-bit integers */
08985 #define P4_SUBPROGRAM  (-18) /* P4 is a pointer to a SubProgram structure */
08986 #define P4_ADVANCE  (-19) /* P4 is a pointer to BtreeNext() or BtreePrev() */
08987 
08988 /* Error message codes for OP_Halt */
08989 #define P5_ConstraintNotNull 1
08990 #define P5_ConstraintUnique  2
08991 #define P5_ConstraintCheck   3
08992 #define P5_ConstraintFK      4
08993 
08994 /*
08995 ** The Vdbe.aColName array contains 5n Mem structures, where n is the 
08996 ** number of columns of data returned by the statement.
08997 */
08998 #define COLNAME_NAME     0
08999 #define COLNAME_DECLTYPE 1
09000 #define COLNAME_DATABASE 2
09001 #define COLNAME_TABLE    3
09002 #define COLNAME_COLUMN   4
09003 #ifdef SQLITE_ENABLE_COLUMN_METADATA
09004 # define COLNAME_N        5      /* Number of COLNAME_xxx symbols */
09005 #else
09006 # ifdef SQLITE_OMIT_DECLTYPE
09007 #   define COLNAME_N      1      /* Store only the name */
09008 # else
09009 #   define COLNAME_N      2      /* Store the name and decltype */
09010 # endif
09011 #endif
09012 
09013 /*
09014 ** The following macro converts a relative address in the p2 field
09015 ** of a VdbeOp structure into a negative number so that 
09016 ** sqlite3VdbeAddOpList() knows that the address is relative.  Calling
09017 ** the macro again restores the address.
09018 */
09019 #define ADDR(X)  (-1-(X))
09020 
09021 /*
09022 ** The makefile scans the vdbe.c source file and creates the "opcodes.h"
09023 ** header file that defines a number for each opcode used by the VDBE.
09024 */
09025 /************** Include opcodes.h in the middle of vdbe.h ********************/
09026 /************** Begin file opcodes.h *****************************************/
09027 /* Automatically generated.  Do not edit */
09028 /* See the mkopcodeh.awk script for details */
09029 #define OP_Function        1 /* synopsis: r[P3]=func(r[P2@P5])             */
09030 #define OP_Savepoint       2
09031 #define OP_AutoCommit      3
09032 #define OP_Transaction     4
09033 #define OP_SorterNext      5
09034 #define OP_PrevIfOpen      6
09035 #define OP_NextIfOpen      7
09036 #define OP_Prev            8
09037 #define OP_Next            9
09038 #define OP_AggStep        10 /* synopsis: accum=r[P3] step(r[P2@P5])       */
09039 #define OP_Checkpoint     11
09040 #define OP_JournalMode    12
09041 #define OP_Vacuum         13
09042 #define OP_VFilter        14 /* synopsis: iPlan=r[P3] zPlan='P4'           */
09043 #define OP_VUpdate        15 /* synopsis: data=r[P3@P2]                    */
09044 #define OP_Goto           16
09045 #define OP_Gosub          17
09046 #define OP_Return         18
09047 #define OP_Not            19 /* same as TK_NOT, synopsis: r[P2]= !r[P1]    */
09048 #define OP_Yield          20
09049 #define OP_HaltIfNull     21 /* synopsis: if r[P3] null then halt          */
09050 #define OP_Halt           22
09051 #define OP_Integer        23 /* synopsis: r[P2]=P1                         */
09052 #define OP_Int64          24 /* synopsis: r[P2]=P4                         */
09053 #define OP_String         25 /* synopsis: r[P2]='P4' (len=P1)              */
09054 #define OP_Null           26 /* synopsis: r[P2..P3]=NULL                   */
09055 #define OP_Blob           27 /* synopsis: r[P2]=P4 (len=P1)                */
09056 #define OP_Variable       28 /* synopsis: r[P2]=parameter(P1,P4)           */
09057 #define OP_Move           29 /* synopsis: r[P2@P3]=r[P1@P3]                */
09058 #define OP_Copy           30 /* synopsis: r[P2@P3]=r[P1@P3]                */
09059 #define OP_SCopy          31 /* synopsis: r[P2]=r[P1]                      */
09060 #define OP_ResultRow      32 /* synopsis: output=r[P1@P2]                  */
09061 #define OP_CollSeq        33
09062 #define OP_AddImm         34 /* synopsis: r[P1]=r[P1]+P2                   */
09063 #define OP_MustBeInt      35
09064 #define OP_RealAffinity   36
09065 #define OP_Permutation    37
09066 #define OP_Compare        38
09067 #define OP_Jump           39
09068 #define OP_Once           40
09069 #define OP_If             41
09070 #define OP_IfNot          42
09071 #define OP_Column         43 /* synopsis: r[P3]=PX                         */
09072 #define OP_Affinity       44 /* synopsis: affinity(r[P1@P2])               */
09073 #define OP_MakeRecord     45 /* synopsis: r[P3]=mkrec(r[P1@P2])            */
09074 #define OP_Count          46 /* synopsis: r[P2]=count()                    */
09075 #define OP_ReadCookie     47
09076 #define OP_SetCookie      48
09077 #define OP_VerifyCookie   49
09078 #define OP_OpenRead       50 /* synopsis: root=P2 iDb=P3                   */
09079 #define OP_OpenWrite      51 /* synopsis: root=P2 iDb=P3                   */
09080 #define OP_OpenAutoindex  52 /* synopsis: nColumn=P2                       */
09081 #define OP_OpenEphemeral  53 /* synopsis: nColumn=P2                       */
09082 #define OP_SorterOpen     54
09083 #define OP_OpenPseudo     55 /* synopsis: content in r[P2@P3]              */
09084 #define OP_Close          56
09085 #define OP_SeekLt         57 /* synopsis: key=r[P3@P4]                     */
09086 #define OP_SeekLe         58 /* synopsis: key=r[P3@P4]                     */
09087 #define OP_SeekGe         59 /* synopsis: key=r[P3@P4]                     */
09088 #define OP_SeekGt         60 /* synopsis: key=r[P3@P4]                     */
09089 #define OP_Seek           61 /* synopsis: intkey=r[P2]                     */
09090 #define OP_NoConflict     62 /* synopsis: key=r[P3@P4]                     */
09091 #define OP_NotFound       63 /* synopsis: key=r[P3@P4]                     */
09092 #define OP_Found          64 /* synopsis: key=r[P3@P4]                     */
09093 #define OP_NotExists      65 /* synopsis: intkey=r[P3]                     */
09094 #define OP_Sequence       66 /* synopsis: r[P2]=rowid                      */
09095 #define OP_NewRowid       67 /* synopsis: r[P2]=rowid                      */
09096 #define OP_Insert         68 /* synopsis: intkey=r[P3] data=r[P2]          */
09097 #define OP_Or             69 /* same as TK_OR, synopsis: r[P3]=(r[P1] || r[P2]) */
09098 #define OP_And            70 /* same as TK_AND, synopsis: r[P3]=(r[P1] && r[P2]) */
09099 #define OP_InsertInt      71 /* synopsis: intkey=P3 data=r[P2]             */
09100 #define OP_Delete         72
09101 #define OP_ResetCount     73
09102 #define OP_IsNull         74 /* same as TK_ISNULL, synopsis: if r[P1]==NULL goto P2 */
09103 #define OP_NotNull        75 /* same as TK_NOTNULL, synopsis: if r[P1]!=NULL goto P2 */
09104 #define OP_Ne             76 /* same as TK_NE, synopsis: if r[P1]!=r[P3] goto P2 */
09105 #define OP_Eq             77 /* same as TK_EQ, synopsis: if r[P1]==r[P3] goto P2 */
09106 #define OP_Gt             78 /* same as TK_GT, synopsis: if r[P1]>r[P3] goto P2 */
09107 #define OP_Le             79 /* same as TK_LE, synopsis: if r[P1]<=r[P3] goto P2 */
09108 #define OP_Lt             80 /* same as TK_LT, synopsis: if r[P1]<r[P3] goto P2 */
09109 #define OP_Ge             81 /* same as TK_GE, synopsis: if r[P1]>=r[P3] goto P2 */
09110 #define OP_SorterCompare  82 /* synopsis: if key(P1)!=rtrim(r[P3],P4) goto P2 */
09111 #define OP_BitAnd         83 /* same as TK_BITAND, synopsis: r[P3]=r[P1]&r[P2] */
09112 #define OP_BitOr          84 /* same as TK_BITOR, synopsis: r[P3]=r[P1]|r[P2] */
09113 #define OP_ShiftLeft      85 /* same as TK_LSHIFT, synopsis: r[P3]=r[P2]<<r[P1] */
09114 #define OP_ShiftRight     86 /* same as TK_RSHIFT, synopsis: r[P3]=r[P2]>>r[P1] */
09115 #define OP_Add            87 /* same as TK_PLUS, synopsis: r[P3]=r[P1]+r[P2] */
09116 #define OP_Subtract       88 /* same as TK_MINUS, synopsis: r[P3]=r[P2]-r[P1] */
09117 #define OP_Multiply       89 /* same as TK_STAR, synopsis: r[P3]=r[P1]*r[P2] */
09118 #define OP_Divide         90 /* same as TK_SLASH, synopsis: r[P3]=r[P2]/r[P1] */
09119 #define OP_Remainder      91 /* same as TK_REM, synopsis: r[P3]=r[P2]%r[P1] */
09120 #define OP_Concat         92 /* same as TK_CONCAT, synopsis: r[P3]=r[P2]+r[P1] */
09121 #define OP_SorterData     93 /* synopsis: r[P2]=data                       */
09122 #define OP_BitNot         94 /* same as TK_BITNOT, synopsis: r[P1]= ~r[P1] */
09123 #define OP_String8        95 /* same as TK_STRING, synopsis: r[P2]='P4'    */
09124 #define OP_RowKey         96 /* synopsis: r[P2]=key                        */
09125 #define OP_RowData        97 /* synopsis: r[P2]=data                       */
09126 #define OP_Rowid          98 /* synopsis: r[P2]=rowid                      */
09127 #define OP_NullRow        99
09128 #define OP_Last          100
09129 #define OP_SorterSort    101
09130 #define OP_Sort          102
09131 #define OP_Rewind        103
09132 #define OP_SorterInsert  104
09133 #define OP_IdxInsert     105 /* synopsis: key=r[P2]                        */
09134 #define OP_IdxDelete     106 /* synopsis: key=r[P2@P3]                     */
09135 #define OP_IdxRowid      107 /* synopsis: r[P2]=rowid                      */
09136 #define OP_IdxLT         108 /* synopsis: key=r[P3@P4]                     */
09137 #define OP_IdxGE         109 /* synopsis: key=r[P3@P4]                     */
09138 #define OP_Destroy       110
09139 #define OP_Clear         111
09140 #define OP_CreateIndex   112 /* synopsis: r[P2]=root iDb=P1                */
09141 #define OP_CreateTable   113 /* synopsis: r[P2]=root iDb=P1                */
09142 #define OP_ParseSchema   114
09143 #define OP_LoadAnalysis  115
09144 #define OP_DropTable     116
09145 #define OP_DropIndex     117
09146 #define OP_DropTrigger   118
09147 #define OP_IntegrityCk   119
09148 #define OP_RowSetAdd     120 /* synopsis: rowset(P1)=r[P2]                 */
09149 #define OP_RowSetRead    121 /* synopsis: r[P3]=rowset(P1)                 */
09150 #define OP_RowSetTest    122 /* synopsis: if r[P3] in rowset(P1) goto P2   */
09151 #define OP_Program       123
09152 #define OP_Param         124
09153 #define OP_FkCounter     125 /* synopsis: fkctr[P1]+=P2                    */
09154 #define OP_FkIfZero      126 /* synopsis: if fkctr[P1]==0 goto P2          */
09155 #define OP_MemMax        127 /* synopsis: r[P1]=max(r[P1],r[P2])           */
09156 #define OP_IfPos         128 /* synopsis: if r[P1]>0 goto P2               */
09157 #define OP_IfNeg         129 /* synopsis: if r[P1]<0 goto P2               */
09158 #define OP_IfZero        130 /* synopsis: r[P1]+=P3, if r[P1]==0 goto P2   */
09159 #define OP_Real          131 /* same as TK_FLOAT, synopsis: r[P2]=P4       */
09160 #define OP_AggFinal      132 /* synopsis: accum=r[P1] N=P2                 */
09161 #define OP_IncrVacuum    133
09162 #define OP_Expire        134
09163 #define OP_TableLock     135 /* synopsis: iDb=P1 root=P2 write=P3          */
09164 #define OP_VBegin        136
09165 #define OP_VCreate       137
09166 #define OP_VDestroy      138
09167 #define OP_VOpen         139
09168 #define OP_VColumn       140 /* synopsis: r[P3]=vcolumn(P2)                */
09169 #define OP_VNext         141
09170 #define OP_ToText        142 /* same as TK_TO_TEXT                         */
09171 #define OP_ToBlob        143 /* same as TK_TO_BLOB                         */
09172 #define OP_ToNumeric     144 /* same as TK_TO_NUMERIC                      */
09173 #define OP_ToInt         145 /* same as TK_TO_INT                          */
09174 #define OP_ToReal        146 /* same as TK_TO_REAL                         */
09175 #define OP_VRename       147
09176 #define OP_Pagecount     148
09177 #define OP_MaxPgcnt      149
09178 #define OP_Trace         150
09179 #define OP_Noop          151
09180 #define OP_Explain       152
09181 
09182 
09183 /* Properties such as "out2" or "jump" that are specified in
09184 ** comments following the "case" for each opcode in the vdbe.c
09185 ** are encoded into bitvectors as follows:
09186 */
09187 #define OPFLG_JUMP            0x0001  /* jump:  P2 holds jmp target */
09188 #define OPFLG_OUT2_PRERELEASE 0x0002  /* out2-prerelease: */
09189 #define OPFLG_IN1             0x0004  /* in1:   P1 is an input */
09190 #define OPFLG_IN2             0x0008  /* in2:   P2 is an input */
09191 #define OPFLG_IN3             0x0010  /* in3:   P3 is an input */
09192 #define OPFLG_OUT2            0x0020  /* out2:  P2 is an output */
09193 #define OPFLG_OUT3            0x0040  /* out3:  P3 is an output */
09194 #define OPFLG_INITIALIZER {\
09195 /*   0 */ 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x01, 0x01,\
09196 /*   8 */ 0x01, 0x01, 0x00, 0x00, 0x02, 0x00, 0x01, 0x00,\
09197 /*  16 */ 0x01, 0x01, 0x04, 0x24, 0x04, 0x10, 0x00, 0x02,\
09198 /*  24 */ 0x02, 0x02, 0x02, 0x02, 0x02, 0x00, 0x00, 0x20,\
09199 /*  32 */ 0x00, 0x00, 0x04, 0x05, 0x04, 0x00, 0x00, 0x01,\
09200 /*  40 */ 0x01, 0x05, 0x05, 0x00, 0x00, 0x00, 0x02, 0x02,\
09201 /*  48 */ 0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,\
09202 /*  56 */ 0x00, 0x11, 0x11, 0x11, 0x11, 0x08, 0x11, 0x11,\
09203 /*  64 */ 0x11, 0x11, 0x02, 0x02, 0x00, 0x4c, 0x4c, 0x00,\
09204 /*  72 */ 0x00, 0x00, 0x05, 0x05, 0x15, 0x15, 0x15, 0x15,\
09205 /*  80 */ 0x15, 0x15, 0x00, 0x4c, 0x4c, 0x4c, 0x4c, 0x4c,\
09206 /*  88 */ 0x4c, 0x4c, 0x4c, 0x4c, 0x4c, 0x00, 0x24, 0x02,\
09207 /*  96 */ 0x00, 0x00, 0x02, 0x00, 0x01, 0x01, 0x01, 0x01,\
09208 /* 104 */ 0x08, 0x08, 0x00, 0x02, 0x01, 0x01, 0x02, 0x00,\
09209 /* 112 */ 0x02, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,\
09210 /* 120 */ 0x0c, 0x45, 0x15, 0x01, 0x02, 0x00, 0x01, 0x08,\
09211 /* 128 */ 0x05, 0x05, 0x05, 0x02, 0x00, 0x01, 0x00, 0x00,\
09212 /* 136 */ 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x04, 0x04,\
09213 /* 144 */ 0x04, 0x04, 0x04, 0x00, 0x02, 0x02, 0x00, 0x00,\
09214 /* 152 */ 0x00,}
09215 
09216 /************** End of opcodes.h *********************************************/
09217 /************** Continuing where we left off in vdbe.h ***********************/
09218 
09219 /*
09220 ** Prototypes for the VDBE interface.  See comments on the implementation
09221 ** for a description of what each of these routines does.
09222 */
09223 SQLITE_PRIVATE Vdbe *sqlite3VdbeCreate(sqlite3*);
09224 SQLITE_PRIVATE int sqlite3VdbeAddOp0(Vdbe*,int);
09225 SQLITE_PRIVATE int sqlite3VdbeAddOp1(Vdbe*,int,int);
09226 SQLITE_PRIVATE int sqlite3VdbeAddOp2(Vdbe*,int,int,int);
09227 SQLITE_PRIVATE int sqlite3VdbeAddOp3(Vdbe*,int,int,int,int);
09228 SQLITE_PRIVATE int sqlite3VdbeAddOp4(Vdbe*,int,int,int,int,const char *zP4,int);
09229 SQLITE_PRIVATE int sqlite3VdbeAddOp4Int(Vdbe*,int,int,int,int,int);
09230 SQLITE_PRIVATE int sqlite3VdbeAddOpList(Vdbe*, int nOp, VdbeOpList const *aOp);
09231 SQLITE_PRIVATE void sqlite3VdbeAddParseSchemaOp(Vdbe*,int,char*);
09232 SQLITE_PRIVATE void sqlite3VdbeChangeP1(Vdbe*, u32 addr, int P1);
09233 SQLITE_PRIVATE void sqlite3VdbeChangeP2(Vdbe*, u32 addr, int P2);
09234 SQLITE_PRIVATE void sqlite3VdbeChangeP3(Vdbe*, u32 addr, int P3);
09235 SQLITE_PRIVATE void sqlite3VdbeChangeP5(Vdbe*, u8 P5);
09236 SQLITE_PRIVATE void sqlite3VdbeJumpHere(Vdbe*, int addr);
09237 SQLITE_PRIVATE void sqlite3VdbeChangeToNoop(Vdbe*, int addr);
09238 SQLITE_PRIVATE void sqlite3VdbeChangeP4(Vdbe*, int addr, const char *zP4, int N);
09239 SQLITE_PRIVATE void sqlite3VdbeSetP4KeyInfo(Parse*, Index*);
09240 SQLITE_PRIVATE void sqlite3VdbeUsesBtree(Vdbe*, int);
09241 SQLITE_PRIVATE VdbeOp *sqlite3VdbeGetOp(Vdbe*, int);
09242 SQLITE_PRIVATE int sqlite3VdbeMakeLabel(Vdbe*);
09243 SQLITE_PRIVATE void sqlite3VdbeRunOnlyOnce(Vdbe*);
09244 SQLITE_PRIVATE void sqlite3VdbeDelete(Vdbe*);
09245 SQLITE_PRIVATE void sqlite3VdbeClearObject(sqlite3*,Vdbe*);
09246 SQLITE_PRIVATE void sqlite3VdbeMakeReady(Vdbe*,Parse*);
09247 SQLITE_PRIVATE int sqlite3VdbeFinalize(Vdbe*);
09248 SQLITE_PRIVATE void sqlite3VdbeResolveLabel(Vdbe*, int);
09249 SQLITE_PRIVATE int sqlite3VdbeCurrentAddr(Vdbe*);
09250 #ifdef SQLITE_DEBUG
09251 SQLITE_PRIVATE   int sqlite3VdbeAssertMayAbort(Vdbe *, int);
09252 #endif
09253 SQLITE_PRIVATE void sqlite3VdbeResetStepResult(Vdbe*);
09254 SQLITE_PRIVATE void sqlite3VdbeRewind(Vdbe*);
09255 SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe*);
09256 SQLITE_PRIVATE void sqlite3VdbeSetNumCols(Vdbe*,int);
09257 SQLITE_PRIVATE int sqlite3VdbeSetColName(Vdbe*, int, int, const char *, void(*)(void*));
09258 SQLITE_PRIVATE void sqlite3VdbeCountChanges(Vdbe*);
09259 SQLITE_PRIVATE sqlite3 *sqlite3VdbeDb(Vdbe*);
09260 SQLITE_PRIVATE void sqlite3VdbeSetSql(Vdbe*, const char *z, int n, int);
09261 SQLITE_PRIVATE void sqlite3VdbeSwap(Vdbe*,Vdbe*);
09262 SQLITE_PRIVATE VdbeOp *sqlite3VdbeTakeOpArray(Vdbe*, int*, int*);
09263 SQLITE_PRIVATE sqlite3_value *sqlite3VdbeGetBoundValue(Vdbe*, int, u8);
09264 SQLITE_PRIVATE void sqlite3VdbeSetVarmask(Vdbe*, int);
09265 #ifndef SQLITE_OMIT_TRACE
09266 SQLITE_PRIVATE   char *sqlite3VdbeExpandSql(Vdbe*, const char*);
09267 #endif
09268 
09269 SQLITE_PRIVATE void sqlite3VdbeRecordUnpack(KeyInfo*,int,const void*,UnpackedRecord*);
09270 SQLITE_PRIVATE int sqlite3VdbeRecordCompare(int,const void*,UnpackedRecord*);
09271 SQLITE_PRIVATE UnpackedRecord *sqlite3VdbeAllocUnpackedRecord(KeyInfo *, char *, int, char **);
09272 
09273 #ifndef SQLITE_OMIT_TRIGGER
09274 SQLITE_PRIVATE void sqlite3VdbeLinkSubProgram(Vdbe *, SubProgram *);
09275 #endif
09276 
09277 /* Use SQLITE_ENABLE_COMMENTS to enable generation of extra comments on
09278 ** each VDBE opcode.
09279 **
09280 ** Use the SQLITE_ENABLE_MODULE_COMMENTS macro to see some extra no-op
09281 ** comments in VDBE programs that show key decision points in the code
09282 ** generator.
09283 */
09284 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
09285 SQLITE_PRIVATE   void sqlite3VdbeComment(Vdbe*, const char*, ...);
09286 # define VdbeComment(X)  sqlite3VdbeComment X
09287 SQLITE_PRIVATE   void sqlite3VdbeNoopComment(Vdbe*, const char*, ...);
09288 # define VdbeNoopComment(X)  sqlite3VdbeNoopComment X
09289 # ifdef SQLITE_ENABLE_MODULE_COMMENTS
09290 #   define VdbeModuleComment(X)  sqlite3VdbeNoopComment X
09291 # else
09292 #   define VdbeModuleComment(X)
09293 # endif
09294 #else
09295 # define VdbeComment(X)
09296 # define VdbeNoopComment(X)
09297 # define VdbeModuleComment(X)
09298 #endif
09299 
09300 #endif
09301 
09302 /************** End of vdbe.h ************************************************/
09303 /************** Continuing where we left off in sqliteInt.h ******************/
09304 /************** Include pager.h in the middle of sqliteInt.h *****************/
09305 /************** Begin file pager.h *******************************************/
09306 /*
09307 ** 2001 September 15
09308 **
09309 ** The author disclaims copyright to this source code.  In place of
09310 ** a legal notice, here is a blessing:
09311 **
09312 **    May you do good and not evil.
09313 **    May you find forgiveness for yourself and forgive others.
09314 **    May you share freely, never taking more than you give.
09315 **
09316 *************************************************************************
09317 ** This header file defines the interface that the sqlite page cache
09318 ** subsystem.  The page cache subsystem reads and writes a file a page
09319 ** at a time and provides a journal for rollback.
09320 */
09321 
09322 #ifndef _PAGER_H_
09323 #define _PAGER_H_
09324 
09325 /*
09326 ** Default maximum size for persistent journal files. A negative 
09327 ** value means no limit. This value may be overridden using the 
09328 ** sqlite3PagerJournalSizeLimit() API. See also "PRAGMA journal_size_limit".
09329 */
09330 #ifndef SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT
09331   #define SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT -1
09332 #endif
09333 
09334 /*
09335 ** The type used to represent a page number.  The first page in a file
09336 ** is called page 1.  0 is used to represent "not a page".
09337 */
09338 typedef u32 Pgno;
09339 
09340 /*
09341 ** Each open file is managed by a separate instance of the "Pager" structure.
09342 */
09343 typedef struct Pager Pager;
09344 
09345 /*
09346 ** Handle type for pages.
09347 */
09348 typedef struct PgHdr DbPage;
09349 
09350 /*
09351 ** Page number PAGER_MJ_PGNO is never used in an SQLite database (it is
09352 ** reserved for working around a windows/posix incompatibility). It is
09353 ** used in the journal to signify that the remainder of the journal file 
09354 ** is devoted to storing a master journal name - there are no more pages to
09355 ** roll back. See comments for function writeMasterJournal() in pager.c 
09356 ** for details.
09357 */
09358 #define PAGER_MJ_PGNO(x) ((Pgno)((PENDING_BYTE/((x)->pageSize))+1))
09359 
09360 /*
09361 ** Allowed values for the flags parameter to sqlite3PagerOpen().
09362 **
09363 ** NOTE: These values must match the corresponding BTREE_ values in btree.h.
09364 */
09365 #define PAGER_OMIT_JOURNAL  0x0001    /* Do not use a rollback journal */
09366 #define PAGER_MEMORY        0x0002    /* In-memory database */
09367 
09368 /*
09369 ** Valid values for the second argument to sqlite3PagerLockingMode().
09370 */
09371 #define PAGER_LOCKINGMODE_QUERY      -1
09372 #define PAGER_LOCKINGMODE_NORMAL      0
09373 #define PAGER_LOCKINGMODE_EXCLUSIVE   1
09374 
09375 /*
09376 ** Numeric constants that encode the journalmode.  
09377 */
09378 #define PAGER_JOURNALMODE_QUERY     (-1)  /* Query the value of journalmode */
09379 #define PAGER_JOURNALMODE_DELETE      0   /* Commit by deleting journal file */
09380 #define PAGER_JOURNALMODE_PERSIST     1   /* Commit by zeroing journal header */
09381 #define PAGER_JOURNALMODE_OFF         2   /* Journal omitted.  */
09382 #define PAGER_JOURNALMODE_TRUNCATE    3   /* Commit by truncating journal */
09383 #define PAGER_JOURNALMODE_MEMORY      4   /* In-memory journal file */
09384 #define PAGER_JOURNALMODE_WAL         5   /* Use write-ahead logging */
09385 
09386 /*
09387 ** Flags that make up the mask passed to sqlite3PagerAcquire().
09388 */
09389 #define PAGER_GET_NOCONTENT     0x01  /* Do not load data from disk */
09390 #define PAGER_GET_READONLY      0x02  /* Read-only page is acceptable */
09391 
09392 /*
09393 ** Flags for sqlite3PagerSetFlags()
09394 */
09395 #define PAGER_SYNCHRONOUS_OFF       0x01  /* PRAGMA synchronous=OFF */
09396 #define PAGER_SYNCHRONOUS_NORMAL    0x02  /* PRAGMA synchronous=NORMAL */
09397 #define PAGER_SYNCHRONOUS_FULL      0x03  /* PRAGMA synchronous=FULL */
09398 #define PAGER_SYNCHRONOUS_MASK      0x03  /* Mask for three values above */
09399 #define PAGER_FULLFSYNC             0x04  /* PRAGMA fullfsync=ON */
09400 #define PAGER_CKPT_FULLFSYNC        0x08  /* PRAGMA checkpoint_fullfsync=ON */
09401 #define PAGER_CACHESPILL            0x10  /* PRAGMA cache_spill=ON */
09402 #define PAGER_FLAGS_MASK            0x1c  /* All above except SYNCHRONOUS */
09403 
09404 /*
09405 ** The remainder of this file contains the declarations of the functions
09406 ** that make up the Pager sub-system API. See source code comments for 
09407 ** a detailed description of each routine.
09408 */
09409 
09410 /* Open and close a Pager connection. */ 
09411 SQLITE_PRIVATE int sqlite3PagerOpen(
09412   sqlite3_vfs*,
09413   Pager **ppPager,
09414   const char*,
09415   int,
09416   int,
09417   int,
09418   void(*)(DbPage*)
09419 );
09420 SQLITE_PRIVATE int sqlite3PagerClose(Pager *pPager);
09421 SQLITE_PRIVATE int sqlite3PagerReadFileheader(Pager*, int, unsigned char*);
09422 
09423 /* Functions used to configure a Pager object. */
09424 SQLITE_PRIVATE void sqlite3PagerSetBusyhandler(Pager*, int(*)(void *), void *);
09425 SQLITE_PRIVATE int sqlite3PagerSetPagesize(Pager*, u32*, int);
09426 SQLITE_PRIVATE int sqlite3PagerMaxPageCount(Pager*, int);
09427 SQLITE_PRIVATE void sqlite3PagerSetCachesize(Pager*, int);
09428 SQLITE_PRIVATE void sqlite3PagerSetMmapLimit(Pager *, sqlite3_int64);
09429 SQLITE_PRIVATE void sqlite3PagerShrink(Pager*);
09430 SQLITE_PRIVATE void sqlite3PagerSetFlags(Pager*,unsigned);
09431 SQLITE_PRIVATE int sqlite3PagerLockingMode(Pager *, int);
09432 SQLITE_PRIVATE int sqlite3PagerSetJournalMode(Pager *, int);
09433 SQLITE_PRIVATE int sqlite3PagerGetJournalMode(Pager*);
09434 SQLITE_PRIVATE int sqlite3PagerOkToChangeJournalMode(Pager*);
09435 SQLITE_PRIVATE i64 sqlite3PagerJournalSizeLimit(Pager *, i64);
09436 SQLITE_PRIVATE sqlite3_backup **sqlite3PagerBackupPtr(Pager*);
09437 
09438 /* Functions used to obtain and release page references. */ 
09439 SQLITE_PRIVATE int sqlite3PagerAcquire(Pager *pPager, Pgno pgno, DbPage **ppPage, int clrFlag);
09440 #define sqlite3PagerGet(A,B,C) sqlite3PagerAcquire(A,B,C,0)
09441 SQLITE_PRIVATE DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno);
09442 SQLITE_PRIVATE void sqlite3PagerRef(DbPage*);
09443 SQLITE_PRIVATE void sqlite3PagerUnref(DbPage*);
09444 
09445 /* Operations on page references. */
09446 SQLITE_PRIVATE int sqlite3PagerWrite(DbPage*);
09447 SQLITE_PRIVATE void sqlite3PagerDontWrite(DbPage*);
09448 SQLITE_PRIVATE int sqlite3PagerMovepage(Pager*,DbPage*,Pgno,int);
09449 SQLITE_PRIVATE int sqlite3PagerPageRefcount(DbPage*);
09450 SQLITE_PRIVATE void *sqlite3PagerGetData(DbPage *); 
09451 SQLITE_PRIVATE void *sqlite3PagerGetExtra(DbPage *); 
09452 
09453 /* Functions used to manage pager transactions and savepoints. */
09454 SQLITE_PRIVATE void sqlite3PagerPagecount(Pager*, int*);
09455 SQLITE_PRIVATE int sqlite3PagerBegin(Pager*, int exFlag, int);
09456 SQLITE_PRIVATE int sqlite3PagerCommitPhaseOne(Pager*,const char *zMaster, int);
09457 SQLITE_PRIVATE int sqlite3PagerExclusiveLock(Pager*);
09458 SQLITE_PRIVATE int sqlite3PagerSync(Pager *pPager);
09459 SQLITE_PRIVATE int sqlite3PagerCommitPhaseTwo(Pager*);
09460 SQLITE_PRIVATE int sqlite3PagerRollback(Pager*);
09461 SQLITE_PRIVATE int sqlite3PagerOpenSavepoint(Pager *pPager, int n);
09462 SQLITE_PRIVATE int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint);
09463 SQLITE_PRIVATE int sqlite3PagerSharedLock(Pager *pPager);
09464 
09465 #ifndef SQLITE_OMIT_WAL
09466 SQLITE_PRIVATE   int sqlite3PagerCheckpoint(Pager *pPager, int, int*, int*);
09467 SQLITE_PRIVATE   int sqlite3PagerWalSupported(Pager *pPager);
09468 SQLITE_PRIVATE   int sqlite3PagerWalCallback(Pager *pPager);
09469 SQLITE_PRIVATE   int sqlite3PagerOpenWal(Pager *pPager, int *pisOpen);
09470 SQLITE_PRIVATE   int sqlite3PagerCloseWal(Pager *pPager);
09471 #endif
09472 
09473 #ifdef SQLITE_ENABLE_ZIPVFS
09474 SQLITE_PRIVATE   int sqlite3PagerWalFramesize(Pager *pPager);
09475 #endif
09476 
09477 /* Functions used to query pager state and configuration. */
09478 SQLITE_PRIVATE u8 sqlite3PagerIsreadonly(Pager*);
09479 SQLITE_PRIVATE int sqlite3PagerRefcount(Pager*);
09480 SQLITE_PRIVATE int sqlite3PagerMemUsed(Pager*);
09481 SQLITE_PRIVATE const char *sqlite3PagerFilename(Pager*, int);
09482 SQLITE_PRIVATE const sqlite3_vfs *sqlite3PagerVfs(Pager*);
09483 SQLITE_PRIVATE sqlite3_file *sqlite3PagerFile(Pager*);
09484 SQLITE_PRIVATE const char *sqlite3PagerJournalname(Pager*);
09485 SQLITE_PRIVATE int sqlite3PagerNosync(Pager*);
09486 SQLITE_PRIVATE void *sqlite3PagerTempSpace(Pager*);
09487 SQLITE_PRIVATE int sqlite3PagerIsMemdb(Pager*);
09488 SQLITE_PRIVATE void sqlite3PagerCacheStat(Pager *, int, int, int *);
09489 SQLITE_PRIVATE void sqlite3PagerClearCache(Pager *);
09490 SQLITE_PRIVATE int sqlite3SectorSize(sqlite3_file *);
09491 
09492 /* Functions used to truncate the database file. */
09493 SQLITE_PRIVATE void sqlite3PagerTruncateImage(Pager*,Pgno);
09494 
09495 #if defined(SQLITE_HAS_CODEC) && !defined(SQLITE_OMIT_WAL)
09496 SQLITE_PRIVATE void *sqlite3PagerCodec(DbPage *);
09497 #endif
09498 
09499 /* Functions to support testing and debugging. */
09500 #if !defined(NDEBUG) || defined(SQLITE_TEST)
09501 SQLITE_PRIVATE   Pgno sqlite3PagerPagenumber(DbPage*);
09502 SQLITE_PRIVATE   int sqlite3PagerIswriteable(DbPage*);
09503 #endif
09504 #ifdef SQLITE_TEST
09505 SQLITE_PRIVATE   int *sqlite3PagerStats(Pager*);
09506 SQLITE_PRIVATE   void sqlite3PagerRefdump(Pager*);
09507   void disable_simulated_io_errors(void);
09508   void enable_simulated_io_errors(void);
09509 #else
09510 # define disable_simulated_io_errors()
09511 # define enable_simulated_io_errors()
09512 #endif
09513 
09514 #endif /* _PAGER_H_ */
09515 
09516 /************** End of pager.h ***********************************************/
09517 /************** Continuing where we left off in sqliteInt.h ******************/
09518 /************** Include pcache.h in the middle of sqliteInt.h ****************/
09519 /************** Begin file pcache.h ******************************************/
09520 /*
09521 ** 2008 August 05
09522 **
09523 ** The author disclaims copyright to this source code.  In place of
09524 ** a legal notice, here is a blessing:
09525 **
09526 **    May you do good and not evil.
09527 **    May you find forgiveness for yourself and forgive others.
09528 **    May you share freely, never taking more than you give.
09529 **
09530 *************************************************************************
09531 ** This header file defines the interface that the sqlite page cache
09532 ** subsystem. 
09533 */
09534 
09535 #ifndef _PCACHE_H_
09536 
09537 typedef struct PgHdr PgHdr;
09538 typedef struct PCache PCache;
09539 
09540 /*
09541 ** Every page in the cache is controlled by an instance of the following
09542 ** structure.
09543 */
09544 struct PgHdr {
09545   sqlite3_pcache_page *pPage;    /* Pcache object page handle */
09546   void *pData;                   /* Page data */
09547   void *pExtra;                  /* Extra content */
09548   PgHdr *pDirty;                 /* Transient list of dirty pages */
09549   Pager *pPager;                 /* The pager this page is part of */
09550   Pgno pgno;                     /* Page number for this page */
09551 #ifdef SQLITE_CHECK_PAGES
09552   u32 pageHash;                  /* Hash of page content */
09553 #endif
09554   u16 flags;                     /* PGHDR flags defined below */
09555 
09556   /**********************************************************************
09557   ** Elements above are public.  All that follows is private to pcache.c
09558   ** and should not be accessed by other modules.
09559   */
09560   i16 nRef;                      /* Number of users of this page */
09561   PCache *pCache;                /* Cache that owns this page */
09562 
09563   PgHdr *pDirtyNext;             /* Next element in list of dirty pages */
09564   PgHdr *pDirtyPrev;             /* Previous element in list of dirty pages */
09565 };
09566 
09567 /* Bit values for PgHdr.flags */
09568 #define PGHDR_DIRTY             0x002  /* Page has changed */
09569 #define PGHDR_NEED_SYNC         0x004  /* Fsync the rollback journal before
09570                                        ** writing this page to the database */
09571 #define PGHDR_NEED_READ         0x008  /* Content is unread */
09572 #define PGHDR_REUSE_UNLIKELY    0x010  /* A hint that reuse is unlikely */
09573 #define PGHDR_DONT_WRITE        0x020  /* Do not write content to disk */
09574 
09575 #define PGHDR_MMAP              0x040  /* This is an mmap page object */
09576 
09577 /* Initialize and shutdown the page cache subsystem */
09578 SQLITE_PRIVATE int sqlite3PcacheInitialize(void);
09579 SQLITE_PRIVATE void sqlite3PcacheShutdown(void);
09580 
09581 /* Page cache buffer management:
09582 ** These routines implement SQLITE_CONFIG_PAGECACHE.
09583 */
09584 SQLITE_PRIVATE void sqlite3PCacheBufferSetup(void *, int sz, int n);
09585 
09586 /* Create a new pager cache.
09587 ** Under memory stress, invoke xStress to try to make pages clean.
09588 ** Only clean and unpinned pages can be reclaimed.
09589 */
09590 SQLITE_PRIVATE void sqlite3PcacheOpen(
09591   int szPage,                    /* Size of every page */
09592   int szExtra,                   /* Extra space associated with each page */
09593   int bPurgeable,                /* True if pages are on backing store */
09594   int (*xStress)(void*, PgHdr*), /* Call to try to make pages clean */
09595   void *pStress,                 /* Argument to xStress */
09596   PCache *pToInit                /* Preallocated space for the PCache */
09597 );
09598 
09599 /* Modify the page-size after the cache has been created. */
09600 SQLITE_PRIVATE void sqlite3PcacheSetPageSize(PCache *, int);
09601 
09602 /* Return the size in bytes of a PCache object.  Used to preallocate
09603 ** storage space.
09604 */
09605 SQLITE_PRIVATE int sqlite3PcacheSize(void);
09606 
09607 /* One release per successful fetch.  Page is pinned until released.
09608 ** Reference counted. 
09609 */
09610 SQLITE_PRIVATE int sqlite3PcacheFetch(PCache*, Pgno, int createFlag, PgHdr**);
09611 SQLITE_PRIVATE void sqlite3PcacheRelease(PgHdr*);
09612 
09613 SQLITE_PRIVATE void sqlite3PcacheDrop(PgHdr*);         /* Remove page from cache */
09614 SQLITE_PRIVATE void sqlite3PcacheMakeDirty(PgHdr*);    /* Make sure page is marked dirty */
09615 SQLITE_PRIVATE void sqlite3PcacheMakeClean(PgHdr*);    /* Mark a single page as clean */
09616 SQLITE_PRIVATE void sqlite3PcacheCleanAll(PCache*);    /* Mark all dirty list pages as clean */
09617 
09618 /* Change a page number.  Used by incr-vacuum. */
09619 SQLITE_PRIVATE void sqlite3PcacheMove(PgHdr*, Pgno);
09620 
09621 /* Remove all pages with pgno>x.  Reset the cache if x==0 */
09622 SQLITE_PRIVATE void sqlite3PcacheTruncate(PCache*, Pgno x);
09623 
09624 /* Get a list of all dirty pages in the cache, sorted by page number */
09625 SQLITE_PRIVATE PgHdr *sqlite3PcacheDirtyList(PCache*);
09626 
09627 /* Reset and close the cache object */
09628 SQLITE_PRIVATE void sqlite3PcacheClose(PCache*);
09629 
09630 /* Clear flags from pages of the page cache */
09631 SQLITE_PRIVATE void sqlite3PcacheClearSyncFlags(PCache *);
09632 
09633 /* Discard the contents of the cache */
09634 SQLITE_PRIVATE void sqlite3PcacheClear(PCache*);
09635 
09636 /* Return the total number of outstanding page references */
09637 SQLITE_PRIVATE int sqlite3PcacheRefCount(PCache*);
09638 
09639 /* Increment the reference count of an existing page */
09640 SQLITE_PRIVATE void sqlite3PcacheRef(PgHdr*);
09641 
09642 SQLITE_PRIVATE int sqlite3PcachePageRefcount(PgHdr*);
09643 
09644 /* Return the total number of pages stored in the cache */
09645 SQLITE_PRIVATE int sqlite3PcachePagecount(PCache*);
09646 
09647 #if defined(SQLITE_CHECK_PAGES) || defined(SQLITE_DEBUG)
09648 /* Iterate through all dirty pages currently stored in the cache. This
09649 ** interface is only available if SQLITE_CHECK_PAGES is defined when the 
09650 ** library is built.
09651 */
09652 SQLITE_PRIVATE void sqlite3PcacheIterateDirty(PCache *pCache, void (*xIter)(PgHdr *));
09653 #endif
09654 
09655 /* Set and get the suggested cache-size for the specified pager-cache.
09656 **
09657 ** If no global maximum is configured, then the system attempts to limit
09658 ** the total number of pages cached by purgeable pager-caches to the sum
09659 ** of the suggested cache-sizes.
09660 */
09661 SQLITE_PRIVATE void sqlite3PcacheSetCachesize(PCache *, int);
09662 #ifdef SQLITE_TEST
09663 SQLITE_PRIVATE int sqlite3PcacheGetCachesize(PCache *);
09664 #endif
09665 
09666 /* Free up as much memory as possible from the page cache */
09667 SQLITE_PRIVATE void sqlite3PcacheShrink(PCache*);
09668 
09669 #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
09670 /* Try to return memory used by the pcache module to the main memory heap */
09671 SQLITE_PRIVATE int sqlite3PcacheReleaseMemory(int);
09672 #endif
09673 
09674 #ifdef SQLITE_TEST
09675 SQLITE_PRIVATE void sqlite3PcacheStats(int*,int*,int*,int*);
09676 #endif
09677 
09678 SQLITE_PRIVATE void sqlite3PCacheSetDefault(void);
09679 
09680 #endif /* _PCACHE_H_ */
09681 
09682 /************** End of pcache.h **********************************************/
09683 /************** Continuing where we left off in sqliteInt.h ******************/
09684 
09685 /************** Include os.h in the middle of sqliteInt.h ********************/
09686 /************** Begin file os.h **********************************************/
09687 /*
09688 ** 2001 September 16
09689 **
09690 ** The author disclaims copyright to this source code.  In place of
09691 ** a legal notice, here is a blessing:
09692 **
09693 **    May you do good and not evil.
09694 **    May you find forgiveness for yourself and forgive others.
09695 **    May you share freely, never taking more than you give.
09696 **
09697 ******************************************************************************
09698 **
09699 ** This header file (together with is companion C source-code file
09700 ** "os.c") attempt to abstract the underlying operating system so that
09701 ** the SQLite library will work on both POSIX and windows systems.
09702 **
09703 ** This header file is #include-ed by sqliteInt.h and thus ends up
09704 ** being included by every source file.
09705 */
09706 #ifndef _SQLITE_OS_H_
09707 #define _SQLITE_OS_H_
09708 
09709 /*
09710 ** Figure out if we are dealing with Unix, Windows, or some other
09711 ** operating system.  After the following block of preprocess macros,
09712 ** all of SQLITE_OS_UNIX, SQLITE_OS_WIN, and SQLITE_OS_OTHER 
09713 ** will defined to either 1 or 0.  One of the four will be 1.  The other 
09714 ** three will be 0.
09715 */
09716 #if defined(SQLITE_OS_OTHER)
09717 # if SQLITE_OS_OTHER==1
09718 #   undef SQLITE_OS_UNIX
09719 #   define SQLITE_OS_UNIX 0
09720 #   undef SQLITE_OS_WIN
09721 #   define SQLITE_OS_WIN 0
09722 # else
09723 #   undef SQLITE_OS_OTHER
09724 # endif
09725 #endif
09726 #if !defined(SQLITE_OS_UNIX) && !defined(SQLITE_OS_OTHER)
09727 # define SQLITE_OS_OTHER 0
09728 # ifndef SQLITE_OS_WIN
09729 #   if defined(_WIN32) || defined(WIN32) || defined(__CYGWIN__) || defined(__MINGW32__) || defined(__BORLANDC__)
09730 #     define SQLITE_OS_WIN 1
09731 #     define SQLITE_OS_UNIX 0
09732 #   else
09733 #     define SQLITE_OS_WIN 0
09734 #     define SQLITE_OS_UNIX 1
09735 #  endif
09736 # else
09737 #  define SQLITE_OS_UNIX 0
09738 # endif
09739 #else
09740 # ifndef SQLITE_OS_WIN
09741 #  define SQLITE_OS_WIN 0
09742 # endif
09743 #endif
09744 
09745 #if SQLITE_OS_WIN
09746 # include <windows.h>
09747 #endif
09748 
09749 /*
09750 ** Determine if we are dealing with Windows NT.
09751 **
09752 ** We ought to be able to determine if we are compiling for win98 or winNT
09753 ** using the _WIN32_WINNT macro as follows:
09754 **
09755 ** #if defined(_WIN32_WINNT)
09756 ** # define SQLITE_OS_WINNT 1
09757 ** #else
09758 ** # define SQLITE_OS_WINNT 0
09759 ** #endif
09760 **
09761 ** However, vs2005 does not set _WIN32_WINNT by default, as it ought to,
09762 ** so the above test does not work.  We'll just assume that everything is
09763 ** winNT unless the programmer explicitly says otherwise by setting
09764 ** SQLITE_OS_WINNT to 0.
09765 */
09766 #if SQLITE_OS_WIN && !defined(SQLITE_OS_WINNT)
09767 # define SQLITE_OS_WINNT 1
09768 #endif
09769 
09770 /*
09771 ** Determine if we are dealing with WindowsCE - which has a much
09772 ** reduced API.
09773 */
09774 #if defined(_WIN32_WCE)
09775 # define SQLITE_OS_WINCE 1
09776 #else
09777 # define SQLITE_OS_WINCE 0
09778 #endif
09779 
09780 /*
09781 ** Determine if we are dealing with WinRT, which provides only a subset of
09782 ** the full Win32 API.
09783 */
09784 #if !defined(SQLITE_OS_WINRT)
09785 # define SQLITE_OS_WINRT 0
09786 #endif
09787 
09788 /* If the SET_FULLSYNC macro is not defined above, then make it
09789 ** a no-op
09790 */
09791 #ifndef SET_FULLSYNC
09792 # define SET_FULLSYNC(x,y)
09793 #endif
09794 
09795 /*
09796 ** The default size of a disk sector
09797 */
09798 #ifndef SQLITE_DEFAULT_SECTOR_SIZE
09799 # define SQLITE_DEFAULT_SECTOR_SIZE 4096
09800 #endif
09801 
09802 /*
09803 ** Temporary files are named starting with this prefix followed by 16 random
09804 ** alphanumeric characters, and no file extension. They are stored in the
09805 ** OS's standard temporary file directory, and are deleted prior to exit.
09806 ** If sqlite is being embedded in another program, you may wish to change the
09807 ** prefix to reflect your program's name, so that if your program exits
09808 ** prematurely, old temporary files can be easily identified. This can be done
09809 ** using -DSQLITE_TEMP_FILE_PREFIX=myprefix_ on the compiler command line.
09810 **
09811 ** 2006-10-31:  The default prefix used to be "sqlite_".  But then
09812 ** Mcafee started using SQLite in their anti-virus product and it
09813 ** started putting files with the "sqlite" name in the c:/temp folder.
09814 ** This annoyed many windows users.  Those users would then do a 
09815 ** Google search for "sqlite", find the telephone numbers of the
09816 ** developers and call to wake them up at night and complain.
09817 ** For this reason, the default name prefix is changed to be "sqlite" 
09818 ** spelled backwards.  So the temp files are still identified, but
09819 ** anybody smart enough to figure out the code is also likely smart
09820 ** enough to know that calling the developer will not help get rid
09821 ** of the file.
09822 */
09823 #ifndef SQLITE_TEMP_FILE_PREFIX
09824 # define SQLITE_TEMP_FILE_PREFIX "etilqs_"
09825 #endif
09826 
09827 /*
09828 ** The following values may be passed as the second argument to
09829 ** sqlite3OsLock(). The various locks exhibit the following semantics:
09830 **
09831 ** SHARED:    Any number of processes may hold a SHARED lock simultaneously.
09832 ** RESERVED:  A single process may hold a RESERVED lock on a file at
09833 **            any time. Other processes may hold and obtain new SHARED locks.
09834 ** PENDING:   A single process may hold a PENDING lock on a file at
09835 **            any one time. Existing SHARED locks may persist, but no new
09836 **            SHARED locks may be obtained by other processes.
09837 ** EXCLUSIVE: An EXCLUSIVE lock precludes all other locks.
09838 **
09839 ** PENDING_LOCK may not be passed directly to sqlite3OsLock(). Instead, a
09840 ** process that requests an EXCLUSIVE lock may actually obtain a PENDING
09841 ** lock. This can be upgraded to an EXCLUSIVE lock by a subsequent call to
09842 ** sqlite3OsLock().
09843 */
09844 #define NO_LOCK         0
09845 #define SHARED_LOCK     1
09846 #define RESERVED_LOCK   2
09847 #define PENDING_LOCK    3
09848 #define EXCLUSIVE_LOCK  4
09849 
09850 /*
09851 ** File Locking Notes:  (Mostly about windows but also some info for Unix)
09852 **
09853 ** We cannot use LockFileEx() or UnlockFileEx() on Win95/98/ME because
09854 ** those functions are not available.  So we use only LockFile() and
09855 ** UnlockFile().
09856 **
09857 ** LockFile() prevents not just writing but also reading by other processes.
09858 ** A SHARED_LOCK is obtained by locking a single randomly-chosen 
09859 ** byte out of a specific range of bytes. The lock byte is obtained at 
09860 ** random so two separate readers can probably access the file at the 
09861 ** same time, unless they are unlucky and choose the same lock byte.
09862 ** An EXCLUSIVE_LOCK is obtained by locking all bytes in the range.
09863 ** There can only be one writer.  A RESERVED_LOCK is obtained by locking
09864 ** a single byte of the file that is designated as the reserved lock byte.
09865 ** A PENDING_LOCK is obtained by locking a designated byte different from
09866 ** the RESERVED_LOCK byte.
09867 **
09868 ** On WinNT/2K/XP systems, LockFileEx() and UnlockFileEx() are available,
09869 ** which means we can use reader/writer locks.  When reader/writer locks
09870 ** are used, the lock is placed on the same range of bytes that is used
09871 ** for probabilistic locking in Win95/98/ME.  Hence, the locking scheme
09872 ** will support two or more Win95 readers or two or more WinNT readers.
09873 ** But a single Win95 reader will lock out all WinNT readers and a single
09874 ** WinNT reader will lock out all other Win95 readers.
09875 **
09876 ** The following #defines specify the range of bytes used for locking.
09877 ** SHARED_SIZE is the number of bytes available in the pool from which
09878 ** a random byte is selected for a shared lock.  The pool of bytes for
09879 ** shared locks begins at SHARED_FIRST. 
09880 **
09881 ** The same locking strategy and
09882 ** byte ranges are used for Unix.  This leaves open the possiblity of having
09883 ** clients on win95, winNT, and unix all talking to the same shared file
09884 ** and all locking correctly.  To do so would require that samba (or whatever
09885 ** tool is being used for file sharing) implements locks correctly between
09886 ** windows and unix.  I'm guessing that isn't likely to happen, but by
09887 ** using the same locking range we are at least open to the possibility.
09888 **
09889 ** Locking in windows is manditory.  For this reason, we cannot store
09890 ** actual data in the bytes used for locking.  The pager never allocates
09891 ** the pages involved in locking therefore.  SHARED_SIZE is selected so
09892 ** that all locks will fit on a single page even at the minimum page size.
09893 ** PENDING_BYTE defines the beginning of the locks.  By default PENDING_BYTE
09894 ** is set high so that we don't have to allocate an unused page except
09895 ** for very large databases.  But one should test the page skipping logic 
09896 ** by setting PENDING_BYTE low and running the entire regression suite.
09897 **
09898 ** Changing the value of PENDING_BYTE results in a subtly incompatible
09899 ** file format.  Depending on how it is changed, you might not notice
09900 ** the incompatibility right away, even running a full regression test.
09901 ** The default location of PENDING_BYTE is the first byte past the
09902 ** 1GB boundary.
09903 **
09904 */
09905 #ifdef SQLITE_OMIT_WSD
09906 # define PENDING_BYTE     (0x40000000)
09907 #else
09908 # define PENDING_BYTE      sqlite3PendingByte
09909 #endif
09910 #define RESERVED_BYTE     (PENDING_BYTE+1)
09911 #define SHARED_FIRST      (PENDING_BYTE+2)
09912 #define SHARED_SIZE       510
09913 
09914 /*
09915 ** Wrapper around OS specific sqlite3_os_init() function.
09916 */
09917 SQLITE_PRIVATE int sqlite3OsInit(void);
09918 
09919 /* 
09920 ** Functions for accessing sqlite3_file methods 
09921 */
09922 SQLITE_PRIVATE int sqlite3OsClose(sqlite3_file*);
09923 SQLITE_PRIVATE int sqlite3OsRead(sqlite3_file*, void*, int amt, i64 offset);
09924 SQLITE_PRIVATE int sqlite3OsWrite(sqlite3_file*, const void*, int amt, i64 offset);
09925 SQLITE_PRIVATE int sqlite3OsTruncate(sqlite3_file*, i64 size);
09926 SQLITE_PRIVATE int sqlite3OsSync(sqlite3_file*, int);
09927 SQLITE_PRIVATE int sqlite3OsFileSize(sqlite3_file*, i64 *pSize);
09928 SQLITE_PRIVATE int sqlite3OsLock(sqlite3_file*, int);
09929 SQLITE_PRIVATE int sqlite3OsUnlock(sqlite3_file*, int);
09930 SQLITE_PRIVATE int sqlite3OsCheckReservedLock(sqlite3_file *id, int *pResOut);
09931 SQLITE_PRIVATE int sqlite3OsFileControl(sqlite3_file*,int,void*);
09932 SQLITE_PRIVATE void sqlite3OsFileControlHint(sqlite3_file*,int,void*);
09933 #define SQLITE_FCNTL_DB_UNCHANGED 0xca093fa0
09934 SQLITE_PRIVATE int sqlite3OsSectorSize(sqlite3_file *id);
09935 SQLITE_PRIVATE int sqlite3OsDeviceCharacteristics(sqlite3_file *id);
09936 SQLITE_PRIVATE int sqlite3OsShmMap(sqlite3_file *,int,int,int,void volatile **);
09937 SQLITE_PRIVATE int sqlite3OsShmLock(sqlite3_file *id, int, int, int);
09938 SQLITE_PRIVATE void sqlite3OsShmBarrier(sqlite3_file *id);
09939 SQLITE_PRIVATE int sqlite3OsShmUnmap(sqlite3_file *id, int);
09940 SQLITE_PRIVATE int sqlite3OsFetch(sqlite3_file *id, i64, int, void **);
09941 SQLITE_PRIVATE int sqlite3OsUnfetch(sqlite3_file *, i64, void *);
09942 
09943 
09944 /* 
09945 ** Functions for accessing sqlite3_vfs methods 
09946 */
09947 SQLITE_PRIVATE int sqlite3OsOpen(sqlite3_vfs *, const char *, sqlite3_file*, int, int *);
09948 SQLITE_PRIVATE int sqlite3OsDelete(sqlite3_vfs *, const char *, int);
09949 SQLITE_PRIVATE int sqlite3OsAccess(sqlite3_vfs *, const char *, int, int *pResOut);
09950 SQLITE_PRIVATE int sqlite3OsFullPathname(sqlite3_vfs *, const char *, int, char *);
09951 #ifndef SQLITE_OMIT_LOAD_EXTENSION
09952 SQLITE_PRIVATE void *sqlite3OsDlOpen(sqlite3_vfs *, const char *);
09953 SQLITE_PRIVATE void sqlite3OsDlError(sqlite3_vfs *, int, char *);
09954 SQLITE_PRIVATE void (*sqlite3OsDlSym(sqlite3_vfs *, void *, const char *))(void);
09955 SQLITE_PRIVATE void sqlite3OsDlClose(sqlite3_vfs *, void *);
09956 #endif /* SQLITE_OMIT_LOAD_EXTENSION */
09957 SQLITE_PRIVATE int sqlite3OsRandomness(sqlite3_vfs *, int, char *);
09958 SQLITE_PRIVATE int sqlite3OsSleep(sqlite3_vfs *, int);
09959 SQLITE_PRIVATE int sqlite3OsCurrentTimeInt64(sqlite3_vfs *, sqlite3_int64*);
09960 
09961 /*
09962 ** Convenience functions for opening and closing files using 
09963 ** sqlite3_malloc() to obtain space for the file-handle structure.
09964 */
09965 SQLITE_PRIVATE int sqlite3OsOpenMalloc(sqlite3_vfs *, const char *, sqlite3_file **, int,int*);
09966 SQLITE_PRIVATE int sqlite3OsCloseFree(sqlite3_file *);
09967 
09968 #endif /* _SQLITE_OS_H_ */
09969 
09970 /************** End of os.h **************************************************/
09971 /************** Continuing where we left off in sqliteInt.h ******************/
09972 /************** Include mutex.h in the middle of sqliteInt.h *****************/
09973 /************** Begin file mutex.h *******************************************/
09974 /*
09975 ** 2007 August 28
09976 **
09977 ** The author disclaims copyright to this source code.  In place of
09978 ** a legal notice, here is a blessing:
09979 **
09980 **    May you do good and not evil.
09981 **    May you find forgiveness for yourself and forgive others.
09982 **    May you share freely, never taking more than you give.
09983 **
09984 *************************************************************************
09985 **
09986 ** This file contains the common header for all mutex implementations.
09987 ** The sqliteInt.h header #includes this file so that it is available
09988 ** to all source files.  We break it out in an effort to keep the code
09989 ** better organized.
09990 **
09991 ** NOTE:  source files should *not* #include this header file directly.
09992 ** Source files should #include the sqliteInt.h file and let that file
09993 ** include this one indirectly.
09994 */
09995 
09996 
09997 /*
09998 ** Figure out what version of the code to use.  The choices are
09999 **
10000 **   SQLITE_MUTEX_OMIT         No mutex logic.  Not even stubs.  The
10001 **                             mutexes implemention cannot be overridden
10002 **                             at start-time.
10003 **
10004 **   SQLITE_MUTEX_NOOP         For single-threaded applications.  No
10005 **                             mutual exclusion is provided.  But this
10006 **                             implementation can be overridden at
10007 **                             start-time.
10008 **
10009 **   SQLITE_MUTEX_PTHREADS     For multi-threaded applications on Unix.
10010 **
10011 **   SQLITE_MUTEX_W32          For multi-threaded applications on Win32.
10012 */
10013 #if !SQLITE_THREADSAFE
10014 # define SQLITE_MUTEX_OMIT
10015 #endif
10016 #if SQLITE_THREADSAFE && !defined(SQLITE_MUTEX_NOOP)
10017 #  if SQLITE_OS_UNIX
10018 #    define SQLITE_MUTEX_PTHREADS
10019 #  elif SQLITE_OS_WIN
10020 #    define SQLITE_MUTEX_W32
10021 #  else
10022 #    define SQLITE_MUTEX_NOOP
10023 #  endif
10024 #endif
10025 
10026 #ifdef SQLITE_MUTEX_OMIT
10027 /*
10028 ** If this is a no-op implementation, implement everything as macros.
10029 */
10030 #define sqlite3_mutex_alloc(X)    ((sqlite3_mutex*)8)
10031 #define sqlite3_mutex_free(X)
10032 #define sqlite3_mutex_enter(X)    
10033 #define sqlite3_mutex_try(X)      SQLITE_OK
10034 #define sqlite3_mutex_leave(X)    
10035 #define sqlite3_mutex_held(X)     ((void)(X),1)
10036 #define sqlite3_mutex_notheld(X)  ((void)(X),1)
10037 #define sqlite3MutexAlloc(X)      ((sqlite3_mutex*)8)
10038 #define sqlite3MutexInit()        SQLITE_OK
10039 #define sqlite3MutexEnd()
10040 #define MUTEX_LOGIC(X)
10041 #else
10042 #define MUTEX_LOGIC(X)            X
10043 #endif /* defined(SQLITE_MUTEX_OMIT) */
10044 
10045 /************** End of mutex.h ***********************************************/
10046 /************** Continuing where we left off in sqliteInt.h ******************/
10047 
10048 
10049 /*
10050 ** Each database file to be accessed by the system is an instance
10051 ** of the following structure.  There are normally two of these structures
10052 ** in the sqlite.aDb[] array.  aDb[0] is the main database file and
10053 ** aDb[1] is the database file used to hold temporary tables.  Additional
10054 ** databases may be attached.
10055 */
10056 struct Db {
10057   char *zName;         /* Name of this database */
10058   Btree *pBt;          /* The B*Tree structure for this database file */
10059   u8 safety_level;     /* How aggressive at syncing data to disk */
10060   Schema *pSchema;     /* Pointer to database schema (possibly shared) */
10061 };
10062 
10063 /*
10064 ** An instance of the following structure stores a database schema.
10065 **
10066 ** Most Schema objects are associated with a Btree.  The exception is
10067 ** the Schema for the TEMP databaes (sqlite3.aDb[1]) which is free-standing.
10068 ** In shared cache mode, a single Schema object can be shared by multiple
10069 ** Btrees that refer to the same underlying BtShared object.
10070 ** 
10071 ** Schema objects are automatically deallocated when the last Btree that
10072 ** references them is destroyed.   The TEMP Schema is manually freed by
10073 ** sqlite3_close().
10074 *
10075 ** A thread must be holding a mutex on the corresponding Btree in order
10076 ** to access Schema content.  This implies that the thread must also be
10077 ** holding a mutex on the sqlite3 connection pointer that owns the Btree.
10078 ** For a TEMP Schema, only the connection mutex is required.
10079 */
10080 struct Schema {
10081   int schema_cookie;   /* Database schema version number for this file */
10082   int iGeneration;     /* Generation counter.  Incremented with each change */
10083   Hash tblHash;        /* All tables indexed by name */
10084   Hash idxHash;        /* All (named) indices indexed by name */
10085   Hash trigHash;       /* All triggers indexed by name */
10086   Hash fkeyHash;       /* All foreign keys by referenced table name */
10087   Table *pSeqTab;      /* The sqlite_sequence table used by AUTOINCREMENT */
10088   u8 file_format;      /* Schema format version for this file */
10089   u8 enc;              /* Text encoding used by this database */
10090   u16 flags;           /* Flags associated with this schema */
10091   int cache_size;      /* Number of pages to use in the cache */
10092 };
10093 
10094 /*
10095 ** These macros can be used to test, set, or clear bits in the 
10096 ** Db.pSchema->flags field.
10097 */
10098 #define DbHasProperty(D,I,P)     (((D)->aDb[I].pSchema->flags&(P))==(P))
10099 #define DbHasAnyProperty(D,I,P)  (((D)->aDb[I].pSchema->flags&(P))!=0)
10100 #define DbSetProperty(D,I,P)     (D)->aDb[I].pSchema->flags|=(P)
10101 #define DbClearProperty(D,I,P)   (D)->aDb[I].pSchema->flags&=~(P)
10102 
10103 /*
10104 ** Allowed values for the DB.pSchema->flags field.
10105 **
10106 ** The DB_SchemaLoaded flag is set after the database schema has been
10107 ** read into internal hash tables.
10108 **
10109 ** DB_UnresetViews means that one or more views have column names that
10110 ** have been filled out.  If the schema changes, these column names might
10111 ** changes and so the view will need to be reset.
10112 */
10113 #define DB_SchemaLoaded    0x0001  /* The schema has been loaded */
10114 #define DB_UnresetViews    0x0002  /* Some views have defined column names */
10115 #define DB_Empty           0x0004  /* The file is empty (length 0 bytes) */
10116 
10117 /*
10118 ** The number of different kinds of things that can be limited
10119 ** using the sqlite3_limit() interface.
10120 */
10121 #define SQLITE_N_LIMIT (SQLITE_LIMIT_TRIGGER_DEPTH+1)
10122 
10123 /*
10124 ** Lookaside malloc is a set of fixed-size buffers that can be used
10125 ** to satisfy small transient memory allocation requests for objects
10126 ** associated with a particular database connection.  The use of
10127 ** lookaside malloc provides a significant performance enhancement
10128 ** (approx 10%) by avoiding numerous malloc/free requests while parsing
10129 ** SQL statements.
10130 **
10131 ** The Lookaside structure holds configuration information about the
10132 ** lookaside malloc subsystem.  Each available memory allocation in
10133 ** the lookaside subsystem is stored on a linked list of LookasideSlot
10134 ** objects.
10135 **
10136 ** Lookaside allocations are only allowed for objects that are associated
10137 ** with a particular database connection.  Hence, schema information cannot
10138 ** be stored in lookaside because in shared cache mode the schema information
10139 ** is shared by multiple database connections.  Therefore, while parsing
10140 ** schema information, the Lookaside.bEnabled flag is cleared so that
10141 ** lookaside allocations are not used to construct the schema objects.
10142 */
10143 struct Lookaside {
10144   u16 sz;                 /* Size of each buffer in bytes */
10145   u8 bEnabled;            /* False to disable new lookaside allocations */
10146   u8 bMalloced;           /* True if pStart obtained from sqlite3_malloc() */
10147   int nOut;               /* Number of buffers currently checked out */
10148   int mxOut;              /* Highwater mark for nOut */
10149   int anStat[3];          /* 0: hits.  1: size misses.  2: full misses */
10150   LookasideSlot *pFree;   /* List of available buffers */
10151   void *pStart;           /* First byte of available memory space */
10152   void *pEnd;             /* First byte past end of available space */
10153 };
10154 struct LookasideSlot {
10155   LookasideSlot *pNext;    /* Next buffer in the list of free buffers */
10156 };
10157 
10158 /*
10159 ** A hash table for function definitions.
10160 **
10161 ** Hash each FuncDef structure into one of the FuncDefHash.a[] slots.
10162 ** Collisions are on the FuncDef.pHash chain.
10163 */
10164 struct FuncDefHash {
10165   FuncDef *a[23];       /* Hash table for functions */
10166 };
10167 
10168 /*
10169 ** Each database connection is an instance of the following structure.
10170 */
10171 struct sqlite3 {
10172   sqlite3_vfs *pVfs;            /* OS Interface */
10173   struct Vdbe *pVdbe;           /* List of active virtual machines */
10174   CollSeq *pDfltColl;           /* The default collating sequence (BINARY) */
10175   sqlite3_mutex *mutex;         /* Connection mutex */
10176   Db *aDb;                      /* All backends */
10177   int nDb;                      /* Number of backends currently in use */
10178   int flags;                    /* Miscellaneous flags. See below */
10179   i64 lastRowid;                /* ROWID of most recent insert (see above) */
10180   i64 szMmap;                   /* Default mmap_size setting */
10181   unsigned int openFlags;       /* Flags passed to sqlite3_vfs.xOpen() */
10182   int errCode;                  /* Most recent error code (SQLITE_*) */
10183   int errMask;                  /* & result codes with this before returning */
10184   u16 dbOptFlags;               /* Flags to enable/disable optimizations */
10185   u8 autoCommit;                /* The auto-commit flag. */
10186   u8 temp_store;                /* 1: file 2: memory 0: default */
10187   u8 mallocFailed;              /* True if we have seen a malloc failure */
10188   u8 dfltLockMode;              /* Default locking-mode for attached dbs */
10189   signed char nextAutovac;      /* Autovac setting after VACUUM if >=0 */
10190   u8 suppressErr;               /* Do not issue error messages if true */
10191   u8 vtabOnConflict;            /* Value to return for s3_vtab_on_conflict() */
10192   u8 isTransactionSavepoint;    /* True if the outermost savepoint is a TS */
10193   int nextPagesize;             /* Pagesize after VACUUM if >0 */
10194   u32 magic;                    /* Magic number for detect library misuse */
10195   int nChange;                  /* Value returned by sqlite3_changes() */
10196   int nTotalChange;             /* Value returned by sqlite3_total_changes() */
10197   int aLimit[SQLITE_N_LIMIT];   /* Limits */
10198   struct sqlite3InitInfo {      /* Information used during initialization */
10199     int newTnum;                /* Rootpage of table being initialized */
10200     u8 iDb;                     /* Which db file is being initialized */
10201     u8 busy;                    /* TRUE if currently initializing */
10202     u8 orphanTrigger;           /* Last statement is orphaned TEMP trigger */
10203   } init;
10204   int nVdbeActive;              /* Number of VDBEs currently running */
10205   int nVdbeRead;                /* Number of active VDBEs that read or write */
10206   int nVdbeWrite;               /* Number of active VDBEs that read and write */
10207   int nVdbeExec;                /* Number of nested calls to VdbeExec() */
10208   int nExtension;               /* Number of loaded extensions */
10209   void **aExtension;            /* Array of shared library handles */
10210   void (*xTrace)(void*,const char*);        /* Trace function */
10211   void *pTraceArg;                          /* Argument to the trace function */
10212   void (*xProfile)(void*,const char*,u64);  /* Profiling function */
10213   void *pProfileArg;                        /* Argument to profile function */
10214   void *pCommitArg;                 /* Argument to xCommitCallback() */   
10215   int (*xCommitCallback)(void*);    /* Invoked at every commit. */
10216   void *pRollbackArg;               /* Argument to xRollbackCallback() */   
10217   void (*xRollbackCallback)(void*); /* Invoked at every commit. */
10218   void *pUpdateArg;
10219   void (*xUpdateCallback)(void*,int, const char*,const char*,sqlite_int64);
10220 #ifndef SQLITE_OMIT_WAL
10221   int (*xWalCallback)(void *, sqlite3 *, const char *, int);
10222   void *pWalArg;
10223 #endif
10224   void(*xCollNeeded)(void*,sqlite3*,int eTextRep,const char*);
10225   void(*xCollNeeded16)(void*,sqlite3*,int eTextRep,const void*);
10226   void *pCollNeededArg;
10227   sqlite3_value *pErr;          /* Most recent error message */
10228   union {
10229     volatile int isInterrupted; /* True if sqlite3_interrupt has been called */
10230     double notUsed1;            /* Spacer */
10231   } u1;
10232   Lookaside lookaside;          /* Lookaside malloc configuration */
10233 #ifndef SQLITE_OMIT_AUTHORIZATION
10234   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*);
10235                                 /* Access authorization function */
10236   void *pAuthArg;               /* 1st argument to the access auth function */
10237 #endif
10238 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
10239   int (*xProgress)(void *);     /* The progress callback */
10240   void *pProgressArg;           /* Argument to the progress callback */
10241   unsigned nProgressOps;        /* Number of opcodes for progress callback */
10242 #endif
10243 #ifndef SQLITE_OMIT_VIRTUALTABLE
10244   int nVTrans;                  /* Allocated size of aVTrans */
10245   Hash aModule;                 /* populated by sqlite3_create_module() */
10246   VtabCtx *pVtabCtx;            /* Context for active vtab connect/create */
10247   VTable **aVTrans;             /* Virtual tables with open transactions */
10248   VTable *pDisconnect;    /* Disconnect these in next sqlite3_prepare() */
10249 #endif
10250   FuncDefHash aFunc;            /* Hash table of connection functions */
10251   Hash aCollSeq;                /* All collating sequences */
10252   BusyHandler busyHandler;      /* Busy callback */
10253   Db aDbStatic[2];              /* Static space for the 2 default backends */
10254   Savepoint *pSavepoint;        /* List of active savepoints */
10255   int busyTimeout;              /* Busy handler timeout, in msec */
10256   int nSavepoint;               /* Number of non-transaction savepoints */
10257   int nStatement;               /* Number of nested statement-transactions  */
10258   i64 nDeferredCons;            /* Net deferred constraints this transaction. */
10259   i64 nDeferredImmCons;         /* Net deferred immediate constraints */
10260   int *pnBytesFreed;            /* If not NULL, increment this in DbFree() */
10261 
10262 #ifdef SQLITE_ENABLE_UNLOCK_NOTIFY
10263   /* The following variables are all protected by the STATIC_MASTER 
10264   ** mutex, not by sqlite3.mutex. They are used by code in notify.c. 
10265   **
10266   ** When X.pUnlockConnection==Y, that means that X is waiting for Y to
10267   ** unlock so that it can proceed.
10268   **
10269   ** When X.pBlockingConnection==Y, that means that something that X tried
10270   ** tried to do recently failed with an SQLITE_LOCKED error due to locks
10271   ** held by Y.
10272   */
10273   sqlite3 *pBlockingConnection; /* Connection that caused SQLITE_LOCKED */
10274   sqlite3 *pUnlockConnection;           /* Connection to watch for unlock */
10275   void *pUnlockArg;                     /* Argument to xUnlockNotify */
10276   void (*xUnlockNotify)(void **, int);  /* Unlock notify callback */
10277   sqlite3 *pNextBlocked;        /* Next in list of all blocked connections */
10278 #endif
10279 };
10280 
10281 /*
10282 ** A macro to discover the encoding of a database.
10283 */
10284 #define ENC(db) ((db)->aDb[0].pSchema->enc)
10285 
10286 /*
10287 ** Possible values for the sqlite3.flags.
10288 */
10289 #define SQLITE_VdbeTrace      0x00000001  /* True to trace VDBE execution */
10290 #define SQLITE_InternChanges  0x00000002  /* Uncommitted Hash table changes */
10291 #define SQLITE_FullFSync      0x00000004  /* Use full fsync on the backend */
10292 #define SQLITE_CkptFullFSync  0x00000008  /* Use full fsync for checkpoint */
10293 #define SQLITE_CacheSpill     0x00000010  /* OK to spill pager cache */
10294 #define SQLITE_FullColNames   0x00000020  /* Show full column names on SELECT */
10295 #define SQLITE_ShortColNames  0x00000040  /* Show short columns names */
10296 #define SQLITE_CountRows      0x00000080  /* Count rows changed by INSERT, */
10297                                           /*   DELETE, or UPDATE and return */
10298                                           /*   the count using a callback. */
10299 #define SQLITE_NullCallback   0x00000100  /* Invoke the callback once if the */
10300                                           /*   result set is empty */
10301 #define SQLITE_SqlTrace       0x00000200  /* Debug print SQL as it executes */
10302 #define SQLITE_VdbeListing    0x00000400  /* Debug listings of VDBE programs */
10303 #define SQLITE_WriteSchema    0x00000800  /* OK to update SQLITE_MASTER */
10304 #define SQLITE_VdbeAddopTrace 0x00001000  /* Trace sqlite3VdbeAddOp() calls */
10305 #define SQLITE_IgnoreChecks   0x00002000  /* Do not enforce check constraints */
10306 #define SQLITE_ReadUncommitted 0x0004000  /* For shared-cache mode */
10307 #define SQLITE_LegacyFileFmt  0x00008000  /* Create new databases in format 1 */
10308 #define SQLITE_RecoveryMode   0x00010000  /* Ignore schema errors */
10309 #define SQLITE_ReverseOrder   0x00020000  /* Reverse unordered SELECTs */
10310 #define SQLITE_RecTriggers    0x00040000  /* Enable recursive triggers */
10311 #define SQLITE_ForeignKeys    0x00080000  /* Enforce foreign key constraints  */
10312 #define SQLITE_AutoIndex      0x00100000  /* Enable automatic indexes */
10313 #define SQLITE_PreferBuiltin  0x00200000  /* Preference to built-in funcs */
10314 #define SQLITE_LoadExtension  0x00400000  /* Enable load_extension */
10315 #define SQLITE_EnableTrigger  0x00800000  /* True to enable triggers */
10316 #define SQLITE_DeferFKs       0x01000000  /* Defer all FK constraints */
10317 #define SQLITE_QueryOnly      0x02000000  /* Disable database changes */
10318 #define SQLITE_VdbeEQP        0x04000000  /* Debug EXPLAIN QUERY PLAN */
10319 
10320 
10321 /*
10322 ** Bits of the sqlite3.dbOptFlags field that are used by the
10323 ** sqlite3_test_control(SQLITE_TESTCTRL_OPTIMIZATIONS,...) interface to
10324 ** selectively disable various optimizations.
10325 */
10326 #define SQLITE_QueryFlattener 0x0001   /* Query flattening */
10327 #define SQLITE_ColumnCache    0x0002   /* Column cache */
10328 #define SQLITE_GroupByOrder   0x0004   /* GROUPBY cover of ORDERBY */
10329 #define SQLITE_FactorOutConst 0x0008   /* Constant factoring */
10330 #define SQLITE_IdxRealAsInt   0x0010   /* Store REAL as INT in indices */
10331 #define SQLITE_DistinctOpt    0x0020   /* DISTINCT using indexes */
10332 #define SQLITE_CoverIdxScan   0x0040   /* Covering index scans */
10333 #define SQLITE_OrderByIdxJoin 0x0080   /* ORDER BY of joins via index */
10334 #define SQLITE_SubqCoroutine  0x0100   /* Evaluate subqueries as coroutines */
10335 #define SQLITE_Transitive     0x0200   /* Transitive constraints */
10336 #define SQLITE_OmitNoopJoin   0x0400   /* Omit unused tables in joins */
10337 #define SQLITE_Stat3          0x0800   /* Use the SQLITE_STAT3 table */
10338 #define SQLITE_AdjustOutEst   0x1000   /* Adjust output estimates using WHERE */
10339 #define SQLITE_AllOpts        0xffff   /* All optimizations */
10340 
10341 /*
10342 ** Macros for testing whether or not optimizations are enabled or disabled.
10343 */
10344 #ifndef SQLITE_OMIT_BUILTIN_TEST
10345 #define OptimizationDisabled(db, mask)  (((db)->dbOptFlags&(mask))!=0)
10346 #define OptimizationEnabled(db, mask)   (((db)->dbOptFlags&(mask))==0)
10347 #else
10348 #define OptimizationDisabled(db, mask)  0
10349 #define OptimizationEnabled(db, mask)   1
10350 #endif
10351 
10352 /*
10353 ** Return true if it OK to factor constant expressions into the initialization
10354 ** code. The argument is a Parse object for the code generator.
10355 */
10356 #define ConstFactorOk(P) \
10357   ((P)->cookieGoto>0 && OptimizationEnabled((P)->db,SQLITE_FactorOutConst))
10358 
10359 /*
10360 ** Possible values for the sqlite.magic field.
10361 ** The numbers are obtained at random and have no special meaning, other
10362 ** than being distinct from one another.
10363 */
10364 #define SQLITE_MAGIC_OPEN     0xa029a697  /* Database is open */
10365 #define SQLITE_MAGIC_CLOSED   0x9f3c2d33  /* Database is closed */
10366 #define SQLITE_MAGIC_SICK     0x4b771290  /* Error and awaiting close */
10367 #define SQLITE_MAGIC_BUSY     0xf03b7906  /* Database currently in use */
10368 #define SQLITE_MAGIC_ERROR    0xb5357930  /* An SQLITE_MISUSE error occurred */
10369 #define SQLITE_MAGIC_ZOMBIE   0x64cffc7f  /* Close with last statement close */
10370 
10371 /*
10372 ** Each SQL function is defined by an instance of the following
10373 ** structure.  A pointer to this structure is stored in the sqlite.aFunc
10374 ** hash table.  When multiple functions have the same name, the hash table
10375 ** points to a linked list of these structures.
10376 */
10377 struct FuncDef {
10378   i16 nArg;            /* Number of arguments.  -1 means unlimited */
10379   u16 funcFlags;       /* Some combination of SQLITE_FUNC_* */
10380   void *pUserData;     /* User data parameter */
10381   FuncDef *pNext;      /* Next function with same name */
10382   void (*xFunc)(sqlite3_context*,int,sqlite3_value**); /* Regular function */
10383   void (*xStep)(sqlite3_context*,int,sqlite3_value**); /* Aggregate step */
10384   void (*xFinalize)(sqlite3_context*);                /* Aggregate finalizer */
10385   char *zName;         /* SQL name of the function. */
10386   FuncDef *pHash;      /* Next with a different name but the same hash */
10387   FuncDestructor *pDestructor;   /* Reference counted destructor function */
10388 };
10389 
10390 /*
10391 ** This structure encapsulates a user-function destructor callback (as
10392 ** configured using create_function_v2()) and a reference counter. When
10393 ** create_function_v2() is called to create a function with a destructor,
10394 ** a single object of this type is allocated. FuncDestructor.nRef is set to 
10395 ** the number of FuncDef objects created (either 1 or 3, depending on whether
10396 ** or not the specified encoding is SQLITE_ANY). The FuncDef.pDestructor
10397 ** member of each of the new FuncDef objects is set to point to the allocated
10398 ** FuncDestructor.
10399 **
10400 ** Thereafter, when one of the FuncDef objects is deleted, the reference
10401 ** count on this object is decremented. When it reaches 0, the destructor
10402 ** is invoked and the FuncDestructor structure freed.
10403 */
10404 struct FuncDestructor {
10405   int nRef;
10406   void (*xDestroy)(void *);
10407   void *pUserData;
10408 };
10409 
10410 /*
10411 ** Possible values for FuncDef.flags.  Note that the _LENGTH and _TYPEOF
10412 ** values must correspond to OPFLAG_LENGTHARG and OPFLAG_TYPEOFARG.  There
10413 ** are assert() statements in the code to verify this.
10414 */
10415 #define SQLITE_FUNC_ENCMASK  0x003 /* SQLITE_UTF8, SQLITE_UTF16BE or UTF16LE */
10416 #define SQLITE_FUNC_LIKE     0x004 /* Candidate for the LIKE optimization */
10417 #define SQLITE_FUNC_CASE     0x008 /* Case-sensitive LIKE-type function */
10418 #define SQLITE_FUNC_EPHEM    0x010 /* Ephemeral.  Delete with VDBE */
10419 #define SQLITE_FUNC_NEEDCOLL 0x020 /* sqlite3GetFuncCollSeq() might be called */
10420 #define SQLITE_FUNC_LENGTH   0x040 /* Built-in length() function */
10421 #define SQLITE_FUNC_TYPEOF   0x080 /* Built-in typeof() function */
10422 #define SQLITE_FUNC_COUNT    0x100 /* Built-in count(*) aggregate */
10423 #define SQLITE_FUNC_COALESCE 0x200 /* Built-in coalesce() or ifnull() */
10424 #define SQLITE_FUNC_UNLIKELY 0x400 /* Built-in unlikely() function */
10425 #define SQLITE_FUNC_CONSTANT 0x800 /* Constant inputs give a constant output */
10426 
10427 /*
10428 ** The following three macros, FUNCTION(), LIKEFUNC() and AGGREGATE() are
10429 ** used to create the initializers for the FuncDef structures.
10430 **
10431 **   FUNCTION(zName, nArg, iArg, bNC, xFunc)
10432 **     Used to create a scalar function definition of a function zName 
10433 **     implemented by C function xFunc that accepts nArg arguments. The
10434 **     value passed as iArg is cast to a (void*) and made available
10435 **     as the user-data (sqlite3_user_data()) for the function. If 
10436 **     argument bNC is true, then the SQLITE_FUNC_NEEDCOLL flag is set.
10437 **
10438 **   VFUNCTION(zName, nArg, iArg, bNC, xFunc)
10439 **     Like FUNCTION except it omits the SQLITE_FUNC_CONSTANT flag.
10440 **
10441 **   AGGREGATE(zName, nArg, iArg, bNC, xStep, xFinal)
10442 **     Used to create an aggregate function definition implemented by
10443 **     the C functions xStep and xFinal. The first four parameters
10444 **     are interpreted in the same way as the first 4 parameters to
10445 **     FUNCTION().
10446 **
10447 **   LIKEFUNC(zName, nArg, pArg, flags)
10448 **     Used to create a scalar function definition of a function zName 
10449 **     that accepts nArg arguments and is implemented by a call to C 
10450 **     function likeFunc. Argument pArg is cast to a (void *) and made
10451 **     available as the function user-data (sqlite3_user_data()). The
10452 **     FuncDef.flags variable is set to the value passed as the flags
10453 **     parameter.
10454 */
10455 #define FUNCTION(zName, nArg, iArg, bNC, xFunc) \
10456   {nArg, SQLITE_FUNC_CONSTANT|SQLITE_UTF8|(bNC*SQLITE_FUNC_NEEDCOLL), \
10457    SQLITE_INT_TO_PTR(iArg), 0, xFunc, 0, 0, #zName, 0, 0}
10458 #define VFUNCTION(zName, nArg, iArg, bNC, xFunc) \
10459   {nArg, SQLITE_UTF8|(bNC*SQLITE_FUNC_NEEDCOLL), \
10460    SQLITE_INT_TO_PTR(iArg), 0, xFunc, 0, 0, #zName, 0, 0}
10461 #define FUNCTION2(zName, nArg, iArg, bNC, xFunc, extraFlags) \
10462   {nArg,SQLITE_FUNC_CONSTANT|SQLITE_UTF8|(bNC*SQLITE_FUNC_NEEDCOLL)|extraFlags,\
10463    SQLITE_INT_TO_PTR(iArg), 0, xFunc, 0, 0, #zName, 0, 0}
10464 #define STR_FUNCTION(zName, nArg, pArg, bNC, xFunc) \
10465   {nArg, SQLITE_FUNC_CONSTANT|SQLITE_UTF8|(bNC*SQLITE_FUNC_NEEDCOLL), \
10466    pArg, 0, xFunc, 0, 0, #zName, 0, 0}
10467 #define LIKEFUNC(zName, nArg, arg, flags) \
10468   {nArg, SQLITE_FUNC_CONSTANT|SQLITE_UTF8|flags, \
10469    (void *)arg, 0, likeFunc, 0, 0, #zName, 0, 0}
10470 #define AGGREGATE(zName, nArg, arg, nc, xStep, xFinal) \
10471   {nArg, SQLITE_UTF8|(nc*SQLITE_FUNC_NEEDCOLL), \
10472    SQLITE_INT_TO_PTR(arg), 0, 0, xStep,xFinal,#zName,0,0}
10473 
10474 /*
10475 ** All current savepoints are stored in a linked list starting at
10476 ** sqlite3.pSavepoint. The first element in the list is the most recently
10477 ** opened savepoint. Savepoints are added to the list by the vdbe
10478 ** OP_Savepoint instruction.
10479 */
10480 struct Savepoint {
10481   char *zName;                        /* Savepoint name (nul-terminated) */
10482   i64 nDeferredCons;                  /* Number of deferred fk violations */
10483   i64 nDeferredImmCons;               /* Number of deferred imm fk. */
10484   Savepoint *pNext;                   /* Parent savepoint (if any) */
10485 };
10486 
10487 /*
10488 ** The following are used as the second parameter to sqlite3Savepoint(),
10489 ** and as the P1 argument to the OP_Savepoint instruction.
10490 */
10491 #define SAVEPOINT_BEGIN      0
10492 #define SAVEPOINT_RELEASE    1
10493 #define SAVEPOINT_ROLLBACK   2
10494 
10495 
10496 /*
10497 ** Each SQLite module (virtual table definition) is defined by an
10498 ** instance of the following structure, stored in the sqlite3.aModule
10499 ** hash table.
10500 */
10501 struct Module {
10502   const sqlite3_module *pModule;       /* Callback pointers */
10503   const char *zName;                   /* Name passed to create_module() */
10504   void *pAux;                          /* pAux passed to create_module() */
10505   void (*xDestroy)(void *);            /* Module destructor function */
10506 };
10507 
10508 /*
10509 ** information about each column of an SQL table is held in an instance
10510 ** of this structure.
10511 */
10512 struct Column {
10513   char *zName;     /* Name of this column */
10514   Expr *pDflt;     /* Default value of this column */
10515   char *zDflt;     /* Original text of the default value */
10516   char *zType;     /* Data type for this column */
10517   char *zColl;     /* Collating sequence.  If NULL, use the default */
10518   u8 notNull;      /* An OE_ code for handling a NOT NULL constraint */
10519   char affinity;   /* One of the SQLITE_AFF_... values */
10520   u8 szEst;        /* Estimated size of this column.  INT==1 */
10521   u8 colFlags;     /* Boolean properties.  See COLFLAG_ defines below */
10522 };
10523 
10524 /* Allowed values for Column.colFlags:
10525 */
10526 #define COLFLAG_PRIMKEY  0x0001    /* Column is part of the primary key */
10527 #define COLFLAG_HIDDEN   0x0002    /* A hidden column in a virtual table */
10528 
10529 /*
10530 ** A "Collating Sequence" is defined by an instance of the following
10531 ** structure. Conceptually, a collating sequence consists of a name and
10532 ** a comparison routine that defines the order of that sequence.
10533 **
10534 ** If CollSeq.xCmp is NULL, it means that the
10535 ** collating sequence is undefined.  Indices built on an undefined
10536 ** collating sequence may not be read or written.
10537 */
10538 struct CollSeq {
10539   char *zName;          /* Name of the collating sequence, UTF-8 encoded */
10540   u8 enc;               /* Text encoding handled by xCmp() */
10541   void *pUser;          /* First argument to xCmp() */
10542   int (*xCmp)(void*,int, const void*, int, const void*);
10543   void (*xDel)(void*);  /* Destructor for pUser */
10544 };
10545 
10546 /*
10547 ** A sort order can be either ASC or DESC.
10548 */
10549 #define SQLITE_SO_ASC       0  /* Sort in ascending order */
10550 #define SQLITE_SO_DESC      1  /* Sort in ascending order */
10551 
10552 /*
10553 ** Column affinity types.
10554 **
10555 ** These used to have mnemonic name like 'i' for SQLITE_AFF_INTEGER and
10556 ** 't' for SQLITE_AFF_TEXT.  But we can save a little space and improve
10557 ** the speed a little by numbering the values consecutively.  
10558 **
10559 ** But rather than start with 0 or 1, we begin with 'a'.  That way,
10560 ** when multiple affinity types are concatenated into a string and
10561 ** used as the P4 operand, they will be more readable.
10562 **
10563 ** Note also that the numeric types are grouped together so that testing
10564 ** for a numeric type is a single comparison.
10565 */
10566 #define SQLITE_AFF_TEXT     'a'
10567 #define SQLITE_AFF_NONE     'b'
10568 #define SQLITE_AFF_NUMERIC  'c'
10569 #define SQLITE_AFF_INTEGER  'd'
10570 #define SQLITE_AFF_REAL     'e'
10571 
10572 #define sqlite3IsNumericAffinity(X)  ((X)>=SQLITE_AFF_NUMERIC)
10573 
10574 /*
10575 ** The SQLITE_AFF_MASK values masks off the significant bits of an
10576 ** affinity value. 
10577 */
10578 #define SQLITE_AFF_MASK     0x67
10579 
10580 /*
10581 ** Additional bit values that can be ORed with an affinity without
10582 ** changing the affinity.
10583 */
10584 #define SQLITE_JUMPIFNULL   0x08  /* jumps if either operand is NULL */
10585 #define SQLITE_STOREP2      0x10  /* Store result in reg[P2] rather than jump */
10586 #define SQLITE_NULLEQ       0x80  /* NULL=NULL */
10587 
10588 /*
10589 ** An object of this type is created for each virtual table present in
10590 ** the database schema. 
10591 **
10592 ** If the database schema is shared, then there is one instance of this
10593 ** structure for each database connection (sqlite3*) that uses the shared
10594 ** schema. This is because each database connection requires its own unique
10595 ** instance of the sqlite3_vtab* handle used to access the virtual table 
10596 ** implementation. sqlite3_vtab* handles can not be shared between 
10597 ** database connections, even when the rest of the in-memory database 
10598 ** schema is shared, as the implementation often stores the database
10599 ** connection handle passed to it via the xConnect() or xCreate() method
10600 ** during initialization internally. This database connection handle may
10601 ** then be used by the virtual table implementation to access real tables 
10602 ** within the database. So that they appear as part of the callers 
10603 ** transaction, these accesses need to be made via the same database 
10604 ** connection as that used to execute SQL operations on the virtual table.
10605 **
10606 ** All VTable objects that correspond to a single table in a shared
10607 ** database schema are initially stored in a linked-list pointed to by
10608 ** the Table.pVTable member variable of the corresponding Table object.
10609 ** When an sqlite3_prepare() operation is required to access the virtual
10610 ** table, it searches the list for the VTable that corresponds to the
10611 ** database connection doing the preparing so as to use the correct
10612 ** sqlite3_vtab* handle in the compiled query.
10613 **
10614 ** When an in-memory Table object is deleted (for example when the
10615 ** schema is being reloaded for some reason), the VTable objects are not 
10616 ** deleted and the sqlite3_vtab* handles are not xDisconnect()ed 
10617 ** immediately. Instead, they are moved from the Table.pVTable list to
10618 ** another linked list headed by the sqlite3.pDisconnect member of the
10619 ** corresponding sqlite3 structure. They are then deleted/xDisconnected 
10620 ** next time a statement is prepared using said sqlite3*. This is done
10621 ** to avoid deadlock issues involving multiple sqlite3.mutex mutexes.
10622 ** Refer to comments above function sqlite3VtabUnlockList() for an
10623 ** explanation as to why it is safe to add an entry to an sqlite3.pDisconnect
10624 ** list without holding the corresponding sqlite3.mutex mutex.
10625 **
10626 ** The memory for objects of this type is always allocated by 
10627 ** sqlite3DbMalloc(), using the connection handle stored in VTable.db as 
10628 ** the first argument.
10629 */
10630 struct VTable {
10631   sqlite3 *db;              /* Database connection associated with this table */
10632   Module *pMod;             /* Pointer to module implementation */
10633   sqlite3_vtab *pVtab;      /* Pointer to vtab instance */
10634   int nRef;                 /* Number of pointers to this structure */
10635   u8 bConstraint;           /* True if constraints are supported */
10636   int iSavepoint;           /* Depth of the SAVEPOINT stack */
10637   VTable *pNext;            /* Next in linked list (see above) */
10638 };
10639 
10640 /*
10641 ** Each SQL table is represented in memory by an instance of the
10642 ** following structure.
10643 **
10644 ** Table.zName is the name of the table.  The case of the original
10645 ** CREATE TABLE statement is stored, but case is not significant for
10646 ** comparisons.
10647 **
10648 ** Table.nCol is the number of columns in this table.  Table.aCol is a
10649 ** pointer to an array of Column structures, one for each column.
10650 **
10651 ** If the table has an INTEGER PRIMARY KEY, then Table.iPKey is the index of
10652 ** the column that is that key.   Otherwise Table.iPKey is negative.  Note
10653 ** that the datatype of the PRIMARY KEY must be INTEGER for this field to
10654 ** be set.  An INTEGER PRIMARY KEY is used as the rowid for each row of
10655 ** the table.  If a table has no INTEGER PRIMARY KEY, then a random rowid
10656 ** is generated for each row of the table.  TF_HasPrimaryKey is set if
10657 ** the table has any PRIMARY KEY, INTEGER or otherwise.
10658 **
10659 ** Table.tnum is the page number for the root BTree page of the table in the
10660 ** database file.  If Table.iDb is the index of the database table backend
10661 ** in sqlite.aDb[].  0 is for the main database and 1 is for the file that
10662 ** holds temporary tables and indices.  If TF_Ephemeral is set
10663 ** then the table is stored in a file that is automatically deleted
10664 ** when the VDBE cursor to the table is closed.  In this case Table.tnum 
10665 ** refers VDBE cursor number that holds the table open, not to the root
10666 ** page number.  Transient tables are used to hold the results of a
10667 ** sub-query that appears instead of a real table name in the FROM clause 
10668 ** of a SELECT statement.
10669 */
10670 struct Table {
10671   char *zName;         /* Name of the table or view */
10672   Column *aCol;        /* Information about each column */
10673   Index *pIndex;       /* List of SQL indexes on this table. */
10674   Select *pSelect;     /* NULL for tables.  Points to definition if a view. */
10675   FKey *pFKey;         /* Linked list of all foreign keys in this table */
10676   char *zColAff;       /* String defining the affinity of each column */
10677 #ifndef SQLITE_OMIT_CHECK
10678   ExprList *pCheck;    /* All CHECK constraints */
10679 #endif
10680   tRowcnt nRowEst;     /* Estimated rows in table - from sqlite_stat1 table */
10681   int tnum;            /* Root BTree node for this table (see note above) */
10682   i16 iPKey;           /* If not negative, use aCol[iPKey] as the primary key */
10683   i16 nCol;            /* Number of columns in this table */
10684   u16 nRef;            /* Number of pointers to this Table */
10685   LogEst szTabRow;     /* Estimated size of each table row in bytes */
10686   u8 tabFlags;         /* Mask of TF_* values */
10687   u8 keyConf;          /* What to do in case of uniqueness conflict on iPKey */
10688 #ifndef SQLITE_OMIT_ALTERTABLE
10689   int addColOffset;    /* Offset in CREATE TABLE stmt to add a new column */
10690 #endif
10691 #ifndef SQLITE_OMIT_VIRTUALTABLE
10692   int nModuleArg;      /* Number of arguments to the module */
10693   char **azModuleArg;  /* Text of all module args. [0] is module name */
10694   VTable *pVTable;     /* List of VTable objects. */
10695 #endif
10696   Trigger *pTrigger;   /* List of triggers stored in pSchema */
10697   Schema *pSchema;     /* Schema that contains this table */
10698   Table *pNextZombie;  /* Next on the Parse.pZombieTab list */
10699 };
10700 
10701 /*
10702 ** Allowed values for Tabe.tabFlags.
10703 */
10704 #define TF_Readonly        0x01    /* Read-only system table */
10705 #define TF_Ephemeral       0x02    /* An ephemeral table */
10706 #define TF_HasPrimaryKey   0x04    /* Table has a primary key */
10707 #define TF_Autoincrement   0x08    /* Integer primary key is autoincrement */
10708 #define TF_Virtual         0x10    /* Is a virtual table */
10709 #define TF_WithoutRowid    0x20    /* No rowid used. PRIMARY KEY is the key */
10710 
10711 
10712 /*
10713 ** Test to see whether or not a table is a virtual table.  This is
10714 ** done as a macro so that it will be optimized out when virtual
10715 ** table support is omitted from the build.
10716 */
10717 #ifndef SQLITE_OMIT_VIRTUALTABLE
10718 #  define IsVirtual(X)      (((X)->tabFlags & TF_Virtual)!=0)
10719 #  define IsHiddenColumn(X) (((X)->colFlags & COLFLAG_HIDDEN)!=0)
10720 #else
10721 #  define IsVirtual(X)      0
10722 #  define IsHiddenColumn(X) 0
10723 #endif
10724 
10725 /* Does the table have a rowid */
10726 #define HasRowid(X)     (((X)->tabFlags & TF_WithoutRowid)==0)
10727 
10728 /*
10729 ** Each foreign key constraint is an instance of the following structure.
10730 **
10731 ** A foreign key is associated with two tables.  The "from" table is
10732 ** the table that contains the REFERENCES clause that creates the foreign
10733 ** key.  The "to" table is the table that is named in the REFERENCES clause.
10734 ** Consider this example:
10735 **
10736 **     CREATE TABLE ex1(
10737 **       a INTEGER PRIMARY KEY,
10738 **       b INTEGER CONSTRAINT fk1 REFERENCES ex2(x)
10739 **     );
10740 **
10741 ** For foreign key "fk1", the from-table is "ex1" and the to-table is "ex2".
10742 ** Equivalent names:
10743 **
10744 **     from-table == child-table
10745 **       to-table == parent-table
10746 **
10747 ** Each REFERENCES clause generates an instance of the following structure
10748 ** which is attached to the from-table.  The to-table need not exist when
10749 ** the from-table is created.  The existence of the to-table is not checked.
10750 **
10751 ** The list of all parents for child Table X is held at X.pFKey.
10752 **
10753 ** A list of all children for a table named Z (which might not even exist)
10754 ** is held in Schema.fkeyHash with a hash key of Z.
10755 */
10756 struct FKey {
10757   Table *pFrom;     /* Table containing the REFERENCES clause (aka: Child) */
10758   FKey *pNextFrom;  /* Next FKey with the same in pFrom. Next parent of pFrom */
10759   char *zTo;        /* Name of table that the key points to (aka: Parent) */
10760   FKey *pNextTo;    /* Next with the same zTo. Next child of zTo. */
10761   FKey *pPrevTo;    /* Previous with the same zTo */
10762   int nCol;         /* Number of columns in this key */
10763   /* EV: R-30323-21917 */
10764   u8 isDeferred;       /* True if constraint checking is deferred till COMMIT */
10765   u8 aAction[2];        /* ON DELETE and ON UPDATE actions, respectively */
10766   Trigger *apTrigger[2];/* Triggers for aAction[] actions */
10767   struct sColMap {      /* Mapping of columns in pFrom to columns in zTo */
10768     int iFrom;            /* Index of column in pFrom */
10769     char *zCol;           /* Name of column in zTo.  If NULL use PRIMARY KEY */
10770   } aCol[1];            /* One entry for each of nCol columns */
10771 };
10772 
10773 /*
10774 ** SQLite supports many different ways to resolve a constraint
10775 ** error.  ROLLBACK processing means that a constraint violation
10776 ** causes the operation in process to fail and for the current transaction
10777 ** to be rolled back.  ABORT processing means the operation in process
10778 ** fails and any prior changes from that one operation are backed out,
10779 ** but the transaction is not rolled back.  FAIL processing means that
10780 ** the operation in progress stops and returns an error code.  But prior
10781 ** changes due to the same operation are not backed out and no rollback
10782 ** occurs.  IGNORE means that the particular row that caused the constraint
10783 ** error is not inserted or updated.  Processing continues and no error
10784 ** is returned.  REPLACE means that preexisting database rows that caused
10785 ** a UNIQUE constraint violation are removed so that the new insert or
10786 ** update can proceed.  Processing continues and no error is reported.
10787 **
10788 ** RESTRICT, SETNULL, and CASCADE actions apply only to foreign keys.
10789 ** RESTRICT is the same as ABORT for IMMEDIATE foreign keys and the
10790 ** same as ROLLBACK for DEFERRED keys.  SETNULL means that the foreign
10791 ** key is set to NULL.  CASCADE means that a DELETE or UPDATE of the
10792 ** referenced table row is propagated into the row that holds the
10793 ** foreign key.
10794 ** 
10795 ** The following symbolic values are used to record which type
10796 ** of action to take.
10797 */
10798 #define OE_None     0   /* There is no constraint to check */
10799 #define OE_Rollback 1   /* Fail the operation and rollback the transaction */
10800 #define OE_Abort    2   /* Back out changes but do no rollback transaction */
10801 #define OE_Fail     3   /* Stop the operation but leave all prior changes */
10802 #define OE_Ignore   4   /* Ignore the error. Do not do the INSERT or UPDATE */
10803 #define OE_Replace  5   /* Delete existing record, then do INSERT or UPDATE */
10804 
10805 #define OE_Restrict 6   /* OE_Abort for IMMEDIATE, OE_Rollback for DEFERRED */
10806 #define OE_SetNull  7   /* Set the foreign key value to NULL */
10807 #define OE_SetDflt  8   /* Set the foreign key value to its default */
10808 #define OE_Cascade  9   /* Cascade the changes */
10809 
10810 #define OE_Default  10  /* Do whatever the default action is */
10811 
10812 
10813 /*
10814 ** An instance of the following structure is passed as the first
10815 ** argument to sqlite3VdbeKeyCompare and is used to control the 
10816 ** comparison of the two index keys.
10817 **
10818 ** Note that aSortOrder[] and aColl[] have nField+1 slots.  There
10819 ** are nField slots for the columns of an index then one extra slot
10820 ** for the rowid at the end.
10821 */
10822 struct KeyInfo {
10823   u32 nRef;           /* Number of references to this KeyInfo object */
10824   u8 enc;             /* Text encoding - one of the SQLITE_UTF* values */
10825   u16 nField;         /* Number of key columns in the index */
10826   u16 nXField;        /* Number of columns beyond the key columns */
10827   sqlite3 *db;        /* The database connection */
10828   u8 *aSortOrder;     /* Sort order for each column. */
10829   CollSeq *aColl[1];  /* Collating sequence for each term of the key */
10830 };
10831 
10832 /*
10833 ** An instance of the following structure holds information about a
10834 ** single index record that has already been parsed out into individual
10835 ** values.
10836 **
10837 ** A record is an object that contains one or more fields of data.
10838 ** Records are used to store the content of a table row and to store
10839 ** the key of an index.  A blob encoding of a record is created by
10840 ** the OP_MakeRecord opcode of the VDBE and is disassembled by the
10841 ** OP_Column opcode.
10842 **
10843 ** This structure holds a record that has already been disassembled
10844 ** into its constituent fields.
10845 */
10846 struct UnpackedRecord {
10847   KeyInfo *pKeyInfo;  /* Collation and sort-order information */
10848   u16 nField;         /* Number of entries in apMem[] */
10849   u8 flags;           /* Boolean settings.  UNPACKED_... below */
10850   Mem *aMem;          /* Values */
10851 };
10852 
10853 /*
10854 ** Allowed values of UnpackedRecord.flags
10855 */
10856 #define UNPACKED_INCRKEY       0x01  /* Make this key an epsilon larger */
10857 #define UNPACKED_PREFIX_MATCH  0x02  /* A prefix match is considered OK */
10858 
10859 /*
10860 ** Each SQL index is represented in memory by an
10861 ** instance of the following structure.
10862 **
10863 ** The columns of the table that are to be indexed are described
10864 ** by the aiColumn[] field of this structure.  For example, suppose
10865 ** we have the following table and index:
10866 **
10867 **     CREATE TABLE Ex1(c1 int, c2 int, c3 text);
10868 **     CREATE INDEX Ex2 ON Ex1(c3,c1);
10869 **
10870 ** In the Table structure describing Ex1, nCol==3 because there are
10871 ** three columns in the table.  In the Index structure describing
10872 ** Ex2, nColumn==2 since 2 of the 3 columns of Ex1 are indexed.
10873 ** The value of aiColumn is {2, 0}.  aiColumn[0]==2 because the 
10874 ** first column to be indexed (c3) has an index of 2 in Ex1.aCol[].
10875 ** The second column to be indexed (c1) has an index of 0 in
10876 ** Ex1.aCol[], hence Ex2.aiColumn[1]==0.
10877 **
10878 ** The Index.onError field determines whether or not the indexed columns
10879 ** must be unique and what to do if they are not.  When Index.onError=OE_None,
10880 ** it means this is not a unique index.  Otherwise it is a unique index
10881 ** and the value of Index.onError indicate the which conflict resolution 
10882 ** algorithm to employ whenever an attempt is made to insert a non-unique
10883 ** element.
10884 */
10885 struct Index {
10886   char *zName;             /* Name of this index */
10887   i16 *aiColumn;           /* Which columns are used by this index.  1st is 0 */
10888   tRowcnt *aiRowEst;       /* From ANALYZE: Est. rows selected by each column */
10889   Table *pTable;           /* The SQL table being indexed */
10890   char *zColAff;           /* String defining the affinity of each column */
10891   Index *pNext;            /* The next index associated with the same table */
10892   Schema *pSchema;         /* Schema containing this index */
10893   u8 *aSortOrder;          /* for each column: True==DESC, False==ASC */
10894   char **azColl;           /* Array of collation sequence names for index */
10895   Expr *pPartIdxWhere;     /* WHERE clause for partial indices */
10896   KeyInfo *pKeyInfo;       /* A KeyInfo object suitable for this index */
10897   int tnum;                /* DB Page containing root of this index */
10898   LogEst szIdxRow;         /* Estimated average row size in bytes */
10899   u16 nKeyCol;             /* Number of columns forming the key */
10900   u16 nColumn;             /* Number of columns stored in the index */
10901   u8 onError;              /* OE_Abort, OE_Ignore, OE_Replace, or OE_None */
10902   unsigned autoIndex:2;    /* 1==UNIQUE, 2==PRIMARY KEY, 0==CREATE INDEX */
10903   unsigned bUnordered:1;   /* Use this index for == or IN queries only */
10904   unsigned uniqNotNull:1;  /* True if UNIQUE and NOT NULL for all columns */
10905   unsigned isResized:1;    /* True if resizeIndexObject() has been called */
10906   unsigned isCovering:1;   /* True if this is a covering index */
10907 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
10908   int nSample;             /* Number of elements in aSample[] */
10909   int nSampleCol;          /* Size of IndexSample.anEq[] and so on */
10910   tRowcnt *aAvgEq;         /* Average nEq values for keys not in aSample */
10911   IndexSample *aSample;    /* Samples of the left-most key */
10912 #endif
10913 };
10914 
10915 /*
10916 ** Each sample stored in the sqlite_stat3 table is represented in memory 
10917 ** using a structure of this type.  See documentation at the top of the
10918 ** analyze.c source file for additional information.
10919 */
10920 struct IndexSample {
10921   void *p;          /* Pointer to sampled record */
10922   int n;            /* Size of record in bytes */
10923   tRowcnt *anEq;    /* Est. number of rows where the key equals this sample */
10924   tRowcnt *anLt;    /* Est. number of rows where key is less than this sample */
10925   tRowcnt *anDLt;   /* Est. number of distinct keys less than this sample */
10926 };
10927 
10928 /*
10929 ** Each token coming out of the lexer is an instance of
10930 ** this structure.  Tokens are also used as part of an expression.
10931 **
10932 ** Note if Token.z==0 then Token.dyn and Token.n are undefined and
10933 ** may contain random values.  Do not make any assumptions about Token.dyn
10934 ** and Token.n when Token.z==0.
10935 */
10936 struct Token {
10937   const char *z;     /* Text of the token.  Not NULL-terminated! */
10938   unsigned int n;    /* Number of characters in this token */
10939 };
10940 
10941 /*
10942 ** An instance of this structure contains information needed to generate
10943 ** code for a SELECT that contains aggregate functions.
10944 **
10945 ** If Expr.op==TK_AGG_COLUMN or TK_AGG_FUNCTION then Expr.pAggInfo is a
10946 ** pointer to this structure.  The Expr.iColumn field is the index in
10947 ** AggInfo.aCol[] or AggInfo.aFunc[] of information needed to generate
10948 ** code for that node.
10949 **
10950 ** AggInfo.pGroupBy and AggInfo.aFunc.pExpr point to fields within the
10951 ** original Select structure that describes the SELECT statement.  These
10952 ** fields do not need to be freed when deallocating the AggInfo structure.
10953 */
10954 struct AggInfo {
10955   u8 directMode;          /* Direct rendering mode means take data directly
10956                           ** from source tables rather than from accumulators */
10957   u8 useSortingIdx;       /* In direct mode, reference the sorting index rather
10958                           ** than the source table */
10959   int sortingIdx;         /* Cursor number of the sorting index */
10960   int sortingIdxPTab;     /* Cursor number of pseudo-table */
10961   int nSortingColumn;     /* Number of columns in the sorting index */
10962   ExprList *pGroupBy;     /* The group by clause */
10963   struct AggInfo_col {    /* For each column used in source tables */
10964     Table *pTab;             /* Source table */
10965     int iTable;              /* Cursor number of the source table */
10966     int iColumn;             /* Column number within the source table */
10967     int iSorterColumn;       /* Column number in the sorting index */
10968     int iMem;                /* Memory location that acts as accumulator */
10969     Expr *pExpr;             /* The original expression */
10970   } *aCol;
10971   int nColumn;            /* Number of used entries in aCol[] */
10972   int nAccumulator;       /* Number of columns that show through to the output.
10973                           ** Additional columns are used only as parameters to
10974                           ** aggregate functions */
10975   struct AggInfo_func {   /* For each aggregate function */
10976     Expr *pExpr;             /* Expression encoding the function */
10977     FuncDef *pFunc;          /* The aggregate function implementation */
10978     int iMem;                /* Memory location that acts as accumulator */
10979     int iDistinct;           /* Ephemeral table used to enforce DISTINCT */
10980   } *aFunc;
10981   int nFunc;              /* Number of entries in aFunc[] */
10982 };
10983 
10984 /*
10985 ** The datatype ynVar is a signed integer, either 16-bit or 32-bit.
10986 ** Usually it is 16-bits.  But if SQLITE_MAX_VARIABLE_NUMBER is greater
10987 ** than 32767 we have to make it 32-bit.  16-bit is preferred because
10988 ** it uses less memory in the Expr object, which is a big memory user
10989 ** in systems with lots of prepared statements.  And few applications
10990 ** need more than about 10 or 20 variables.  But some extreme users want
10991 ** to have prepared statements with over 32767 variables, and for them
10992 ** the option is available (at compile-time).
10993 */
10994 #if SQLITE_MAX_VARIABLE_NUMBER<=32767
10995 typedef i16 ynVar;
10996 #else
10997 typedef int ynVar;
10998 #endif
10999 
11000 /*
11001 ** Each node of an expression in the parse tree is an instance
11002 ** of this structure.
11003 **
11004 ** Expr.op is the opcode. The integer parser token codes are reused
11005 ** as opcodes here. For example, the parser defines TK_GE to be an integer
11006 ** code representing the ">=" operator. This same integer code is reused
11007 ** to represent the greater-than-or-equal-to operator in the expression
11008 ** tree.
11009 **
11010 ** If the expression is an SQL literal (TK_INTEGER, TK_FLOAT, TK_BLOB, 
11011 ** or TK_STRING), then Expr.token contains the text of the SQL literal. If
11012 ** the expression is a variable (TK_VARIABLE), then Expr.token contains the 
11013 ** variable name. Finally, if the expression is an SQL function (TK_FUNCTION),
11014 ** then Expr.token contains the name of the function.
11015 **
11016 ** Expr.pRight and Expr.pLeft are the left and right subexpressions of a
11017 ** binary operator. Either or both may be NULL.
11018 **
11019 ** Expr.x.pList is a list of arguments if the expression is an SQL function,
11020 ** a CASE expression or an IN expression of the form "<lhs> IN (<y>, <z>...)".
11021 ** Expr.x.pSelect is used if the expression is a sub-select or an expression of
11022 ** the form "<lhs> IN (SELECT ...)". If the EP_xIsSelect bit is set in the
11023 ** Expr.flags mask, then Expr.x.pSelect is valid. Otherwise, Expr.x.pList is 
11024 ** valid.
11025 **
11026 ** An expression of the form ID or ID.ID refers to a column in a table.
11027 ** For such expressions, Expr.op is set to TK_COLUMN and Expr.iTable is
11028 ** the integer cursor number of a VDBE cursor pointing to that table and
11029 ** Expr.iColumn is the column number for the specific column.  If the
11030 ** expression is used as a result in an aggregate SELECT, then the
11031 ** value is also stored in the Expr.iAgg column in the aggregate so that
11032 ** it can be accessed after all aggregates are computed.
11033 **
11034 ** If the expression is an unbound variable marker (a question mark 
11035 ** character '?' in the original SQL) then the Expr.iTable holds the index 
11036 ** number for that variable.
11037 **
11038 ** If the expression is a subquery then Expr.iColumn holds an integer
11039 ** register number containing the result of the subquery.  If the
11040 ** subquery gives a constant result, then iTable is -1.  If the subquery
11041 ** gives a different answer at different times during statement processing
11042 ** then iTable is the address of a subroutine that computes the subquery.
11043 **
11044 ** If the Expr is of type OP_Column, and the table it is selecting from
11045 ** is a disk table or the "old.*" pseudo-table, then pTab points to the
11046 ** corresponding table definition.
11047 **
11048 ** ALLOCATION NOTES:
11049 **
11050 ** Expr objects can use a lot of memory space in database schema.  To
11051 ** help reduce memory requirements, sometimes an Expr object will be
11052 ** truncated.  And to reduce the number of memory allocations, sometimes
11053 ** two or more Expr objects will be stored in a single memory allocation,
11054 ** together with Expr.zToken strings.
11055 **
11056 ** If the EP_Reduced and EP_TokenOnly flags are set when
11057 ** an Expr object is truncated.  When EP_Reduced is set, then all
11058 ** the child Expr objects in the Expr.pLeft and Expr.pRight subtrees
11059 ** are contained within the same memory allocation.  Note, however, that
11060 ** the subtrees in Expr.x.pList or Expr.x.pSelect are always separately
11061 ** allocated, regardless of whether or not EP_Reduced is set.
11062 */
11063 struct Expr {
11064   u8 op;                 /* Operation performed by this node */
11065   char affinity;         /* The affinity of the column or 0 if not a column */
11066   u32 flags;             /* Various flags.  EP_* See below */
11067   union {
11068     char *zToken;          /* Token value. Zero terminated and dequoted */
11069     int iValue;            /* Non-negative integer value if EP_IntValue */
11070   } u;
11071 
11072   /* If the EP_TokenOnly flag is set in the Expr.flags mask, then no
11073   ** space is allocated for the fields below this point. An attempt to
11074   ** access them will result in a segfault or malfunction. 
11075   *********************************************************************/
11076 
11077   Expr *pLeft;           /* Left subnode */
11078   Expr *pRight;          /* Right subnode */
11079   union {
11080     ExprList *pList;     /* op = IN, EXISTS, SELECT, CASE, FUNCTION, BETWEEN */
11081     Select *pSelect;     /* EP_xIsSelect and op = IN, EXISTS, SELECT */
11082   } x;
11083 
11084   /* If the EP_Reduced flag is set in the Expr.flags mask, then no
11085   ** space is allocated for the fields below this point. An attempt to
11086   ** access them will result in a segfault or malfunction.
11087   *********************************************************************/
11088 
11089 #if SQLITE_MAX_EXPR_DEPTH>0
11090   int nHeight;           /* Height of the tree headed by this node */
11091 #endif
11092   int iTable;            /* TK_COLUMN: cursor number of table holding column
11093                          ** TK_REGISTER: register number
11094                          ** TK_TRIGGER: 1 -> new, 0 -> old
11095                          ** EP_Unlikely:  1000 times likelihood */
11096   ynVar iColumn;         /* TK_COLUMN: column index.  -1 for rowid.
11097                          ** TK_VARIABLE: variable number (always >= 1). */
11098   i16 iAgg;              /* Which entry in pAggInfo->aCol[] or ->aFunc[] */
11099   i16 iRightJoinTable;   /* If EP_FromJoin, the right table of the join */
11100   u8 op2;                /* TK_REGISTER: original value of Expr.op
11101                          ** TK_COLUMN: the value of p5 for OP_Column
11102                          ** TK_AGG_FUNCTION: nesting depth */
11103   AggInfo *pAggInfo;     /* Used by TK_AGG_COLUMN and TK_AGG_FUNCTION */
11104   Table *pTab;           /* Table for TK_COLUMN expressions. */
11105 };
11106 
11107 /*
11108 ** The following are the meanings of bits in the Expr.flags field.
11109 */
11110 #define EP_FromJoin  0x000001 /* Originated in ON or USING clause of a join */
11111 #define EP_Agg       0x000002 /* Contains one or more aggregate functions */
11112 #define EP_Resolved  0x000004 /* IDs have been resolved to COLUMNs */
11113 #define EP_Error     0x000008 /* Expression contains one or more errors */
11114 #define EP_Distinct  0x000010 /* Aggregate function with DISTINCT keyword */
11115 #define EP_VarSelect 0x000020 /* pSelect is correlated, not constant */
11116 #define EP_DblQuoted 0x000040 /* token.z was originally in "..." */
11117 #define EP_InfixFunc 0x000080 /* True for an infix function: LIKE, GLOB, etc */
11118 #define EP_Collate   0x000100 /* Tree contains a TK_COLLATE opeartor */
11119       /* unused      0x000200 */
11120 #define EP_IntValue  0x000400 /* Integer value contained in u.iValue */
11121 #define EP_xIsSelect 0x000800 /* x.pSelect is valid (otherwise x.pList is) */
11122 #define EP_Skip      0x001000 /* COLLATE, AS, or UNLIKELY */
11123 #define EP_Reduced   0x002000 /* Expr struct EXPR_REDUCEDSIZE bytes only */
11124 #define EP_TokenOnly 0x004000 /* Expr struct EXPR_TOKENONLYSIZE bytes only */
11125 #define EP_Static    0x008000 /* Held in memory not obtained from malloc() */
11126 #define EP_MemToken  0x010000 /* Need to sqlite3DbFree() Expr.zToken */
11127 #define EP_NoReduce  0x020000 /* Cannot EXPRDUP_REDUCE this Expr */
11128 #define EP_Unlikely  0x040000 /* unlikely() or likelihood() function */
11129 #define EP_Constant  0x080000 /* Node is a constant */
11130 
11131 /*
11132 ** These macros can be used to test, set, or clear bits in the 
11133 ** Expr.flags field.
11134 */
11135 #define ExprHasProperty(E,P)     (((E)->flags&(P))!=0)
11136 #define ExprHasAllProperty(E,P)  (((E)->flags&(P))==(P))
11137 #define ExprSetProperty(E,P)     (E)->flags|=(P)
11138 #define ExprClearProperty(E,P)   (E)->flags&=~(P)
11139 
11140 /* The ExprSetVVAProperty() macro is used for Verification, Validation,
11141 ** and Accreditation only.  It works like ExprSetProperty() during VVA
11142 ** processes but is a no-op for delivery.
11143 */
11144 #ifdef SQLITE_DEBUG
11145 # define ExprSetVVAProperty(E,P)  (E)->flags|=(P)
11146 #else
11147 # define ExprSetVVAProperty(E,P)
11148 #endif
11149 
11150 /*
11151 ** Macros to determine the number of bytes required by a normal Expr 
11152 ** struct, an Expr struct with the EP_Reduced flag set in Expr.flags 
11153 ** and an Expr struct with the EP_TokenOnly flag set.
11154 */
11155 #define EXPR_FULLSIZE           sizeof(Expr)           /* Full size */
11156 #define EXPR_REDUCEDSIZE        offsetof(Expr,iTable)  /* Common features */
11157 #define EXPR_TOKENONLYSIZE      offsetof(Expr,pLeft)   /* Fewer features */
11158 
11159 /*
11160 ** Flags passed to the sqlite3ExprDup() function. See the header comment 
11161 ** above sqlite3ExprDup() for details.
11162 */
11163 #define EXPRDUP_REDUCE         0x0001  /* Used reduced-size Expr nodes */
11164 
11165 /*
11166 ** A list of expressions.  Each expression may optionally have a
11167 ** name.  An expr/name combination can be used in several ways, such
11168 ** as the list of "expr AS ID" fields following a "SELECT" or in the
11169 ** list of "ID = expr" items in an UPDATE.  A list of expressions can
11170 ** also be used as the argument to a function, in which case the a.zName
11171 ** field is not used.
11172 **
11173 ** By default the Expr.zSpan field holds a human-readable description of
11174 ** the expression that is used in the generation of error messages and
11175 ** column labels.  In this case, Expr.zSpan is typically the text of a
11176 ** column expression as it exists in a SELECT statement.  However, if
11177 ** the bSpanIsTab flag is set, then zSpan is overloaded to mean the name
11178 ** of the result column in the form: DATABASE.TABLE.COLUMN.  This later
11179 ** form is used for name resolution with nested FROM clauses.
11180 */
11181 struct ExprList {
11182   int nExpr;             /* Number of expressions on the list */
11183   int iECursor;          /* VDBE Cursor associated with this ExprList */
11184   struct ExprList_item { /* For each expression in the list */
11185     Expr *pExpr;            /* The list of expressions */
11186     char *zName;            /* Token associated with this expression */
11187     char *zSpan;            /* Original text of the expression */
11188     u8 sortOrder;           /* 1 for DESC or 0 for ASC */
11189     unsigned done :1;       /* A flag to indicate when processing is finished */
11190     unsigned bSpanIsTab :1; /* zSpan holds DB.TABLE.COLUMN */
11191     unsigned reusable :1;   /* Constant expression is reusable */
11192     union {
11193       struct {
11194         u16 iOrderByCol;      /* For ORDER BY, column number in result set */
11195         u16 iAlias;           /* Index into Parse.aAlias[] for zName */
11196       } x;
11197       int iConstExprReg;      /* Register in which Expr value is cached */
11198     } u;
11199   } *a;                  /* Alloc a power of two greater or equal to nExpr */
11200 };
11201 
11202 /*
11203 ** An instance of this structure is used by the parser to record both
11204 ** the parse tree for an expression and the span of input text for an
11205 ** expression.
11206 */
11207 struct ExprSpan {
11208   Expr *pExpr;          /* The expression parse tree */
11209   const char *zStart;   /* First character of input text */
11210   const char *zEnd;     /* One character past the end of input text */
11211 };
11212 
11213 /*
11214 ** An instance of this structure can hold a simple list of identifiers,
11215 ** such as the list "a,b,c" in the following statements:
11216 **
11217 **      INSERT INTO t(a,b,c) VALUES ...;
11218 **      CREATE INDEX idx ON t(a,b,c);
11219 **      CREATE TRIGGER trig BEFORE UPDATE ON t(a,b,c) ...;
11220 **
11221 ** The IdList.a.idx field is used when the IdList represents the list of
11222 ** column names after a table name in an INSERT statement.  In the statement
11223 **
11224 **     INSERT INTO t(a,b,c) ...
11225 **
11226 ** If "a" is the k-th column of table "t", then IdList.a[0].idx==k.
11227 */
11228 struct IdList {
11229   struct IdList_item {
11230     char *zName;      /* Name of the identifier */
11231     int idx;          /* Index in some Table.aCol[] of a column named zName */
11232   } *a;
11233   int nId;         /* Number of identifiers on the list */
11234 };
11235 
11236 /*
11237 ** The bitmask datatype defined below is used for various optimizations.
11238 **
11239 ** Changing this from a 64-bit to a 32-bit type limits the number of
11240 ** tables in a join to 32 instead of 64.  But it also reduces the size
11241 ** of the library by 738 bytes on ix86.
11242 */
11243 typedef u64 Bitmask;
11244 
11245 /*
11246 ** The number of bits in a Bitmask.  "BMS" means "BitMask Size".
11247 */
11248 #define BMS  ((int)(sizeof(Bitmask)*8))
11249 
11250 /*
11251 ** A bit in a Bitmask
11252 */
11253 #define MASKBIT(n)   (((Bitmask)1)<<(n))
11254 
11255 /*
11256 ** The following structure describes the FROM clause of a SELECT statement.
11257 ** Each table or subquery in the FROM clause is a separate element of
11258 ** the SrcList.a[] array.
11259 **
11260 ** With the addition of multiple database support, the following structure
11261 ** can also be used to describe a particular table such as the table that
11262 ** is modified by an INSERT, DELETE, or UPDATE statement.  In standard SQL,
11263 ** such a table must be a simple name: ID.  But in SQLite, the table can
11264 ** now be identified by a database name, a dot, then the table name: ID.ID.
11265 **
11266 ** The jointype starts out showing the join type between the current table
11267 ** and the next table on the list.  The parser builds the list this way.
11268 ** But sqlite3SrcListShiftJoinType() later shifts the jointypes so that each
11269 ** jointype expresses the join between the table and the previous table.
11270 **
11271 ** In the colUsed field, the high-order bit (bit 63) is set if the table
11272 ** contains more than 63 columns and the 64-th or later column is used.
11273 */
11274 struct SrcList {
11275   u8 nSrc;        /* Number of tables or subqueries in the FROM clause */
11276   u8 nAlloc;      /* Number of entries allocated in a[] below */
11277   struct SrcList_item {
11278     Schema *pSchema;  /* Schema to which this item is fixed */
11279     char *zDatabase;  /* Name of database holding this table */
11280     char *zName;      /* Name of the table */
11281     char *zAlias;     /* The "B" part of a "A AS B" phrase.  zName is the "A" */
11282     Table *pTab;      /* An SQL table corresponding to zName */
11283     Select *pSelect;  /* A SELECT statement used in place of a table name */
11284     int addrFillSub;  /* Address of subroutine to manifest a subquery */
11285     int regReturn;    /* Register holding return address of addrFillSub */
11286     u8 jointype;      /* Type of join between this able and the previous */
11287     unsigned notIndexed :1;    /* True if there is a NOT INDEXED clause */
11288     unsigned isCorrelated :1;  /* True if sub-query is correlated */
11289     unsigned viaCoroutine :1;  /* Implemented as a co-routine */
11290 #ifndef SQLITE_OMIT_EXPLAIN
11291     u8 iSelectId;     /* If pSelect!=0, the id of the sub-select in EQP */
11292 #endif
11293     int iCursor;      /* The VDBE cursor number used to access this table */
11294     Expr *pOn;        /* The ON clause of a join */
11295     IdList *pUsing;   /* The USING clause of a join */
11296     Bitmask colUsed;  /* Bit N (1<<N) set if column N of pTab is used */
11297     char *zIndex;     /* Identifier from "INDEXED BY <zIndex>" clause */
11298     Index *pIndex;    /* Index structure corresponding to zIndex, if any */
11299   } a[1];             /* One entry for each identifier on the list */
11300 };
11301 
11302 /*
11303 ** Permitted values of the SrcList.a.jointype field
11304 */
11305 #define JT_INNER     0x0001    /* Any kind of inner or cross join */
11306 #define JT_CROSS     0x0002    /* Explicit use of the CROSS keyword */
11307 #define JT_NATURAL   0x0004    /* True for a "natural" join */
11308 #define JT_LEFT      0x0008    /* Left outer join */
11309 #define JT_RIGHT     0x0010    /* Right outer join */
11310 #define JT_OUTER     0x0020    /* The "OUTER" keyword is present */
11311 #define JT_ERROR     0x0040    /* unknown or unsupported join type */
11312 
11313 
11314 /*
11315 ** Flags appropriate for the wctrlFlags parameter of sqlite3WhereBegin()
11316 ** and the WhereInfo.wctrlFlags member.
11317 */
11318 #define WHERE_ORDERBY_NORMAL   0x0000 /* No-op */
11319 #define WHERE_ORDERBY_MIN      0x0001 /* ORDER BY processing for min() func */
11320 #define WHERE_ORDERBY_MAX      0x0002 /* ORDER BY processing for max() func */
11321 #define WHERE_ONEPASS_DESIRED  0x0004 /* Want to do one-pass UPDATE/DELETE */
11322 #define WHERE_DUPLICATES_OK    0x0008 /* Ok to return a row more than once */
11323 #define WHERE_OMIT_OPEN_CLOSE  0x0010 /* Table cursors are already open */
11324 #define WHERE_FORCE_TABLE      0x0020 /* Do not use an index-only search */
11325 #define WHERE_ONETABLE_ONLY    0x0040 /* Only code the 1st table in pTabList */
11326 #define WHERE_AND_ONLY         0x0080 /* Don't use indices for OR terms */
11327 #define WHERE_GROUPBY          0x0100 /* pOrderBy is really a GROUP BY */
11328 #define WHERE_DISTINCTBY       0x0200 /* pOrderby is really a DISTINCT clause */
11329 #define WHERE_WANT_DISTINCT    0x0400 /* All output needs to be distinct */
11330 
11331 /* Allowed return values from sqlite3WhereIsDistinct()
11332 */
11333 #define WHERE_DISTINCT_NOOP      0  /* DISTINCT keyword not used */
11334 #define WHERE_DISTINCT_UNIQUE    1  /* No duplicates */
11335 #define WHERE_DISTINCT_ORDERED   2  /* All duplicates are adjacent */
11336 #define WHERE_DISTINCT_UNORDERED 3  /* Duplicates are scattered */
11337 
11338 /*
11339 ** A NameContext defines a context in which to resolve table and column
11340 ** names.  The context consists of a list of tables (the pSrcList) field and
11341 ** a list of named expression (pEList).  The named expression list may
11342 ** be NULL.  The pSrc corresponds to the FROM clause of a SELECT or
11343 ** to the table being operated on by INSERT, UPDATE, or DELETE.  The
11344 ** pEList corresponds to the result set of a SELECT and is NULL for
11345 ** other statements.
11346 **
11347 ** NameContexts can be nested.  When resolving names, the inner-most 
11348 ** context is searched first.  If no match is found, the next outer
11349 ** context is checked.  If there is still no match, the next context
11350 ** is checked.  This process continues until either a match is found
11351 ** or all contexts are check.  When a match is found, the nRef member of
11352 ** the context containing the match is incremented. 
11353 **
11354 ** Each subquery gets a new NameContext.  The pNext field points to the
11355 ** NameContext in the parent query.  Thus the process of scanning the
11356 ** NameContext list corresponds to searching through successively outer
11357 ** subqueries looking for a match.
11358 */
11359 struct NameContext {
11360   Parse *pParse;       /* The parser */
11361   SrcList *pSrcList;   /* One or more tables used to resolve names */
11362   ExprList *pEList;    /* Optional list of result-set columns */
11363   AggInfo *pAggInfo;   /* Information about aggregates at this level */
11364   NameContext *pNext;  /* Next outer name context.  NULL for outermost */
11365   int nRef;            /* Number of names resolved by this context */
11366   int nErr;            /* Number of errors encountered while resolving names */
11367   u8 ncFlags;          /* Zero or more NC_* flags defined below */
11368 };
11369 
11370 /*
11371 ** Allowed values for the NameContext, ncFlags field.
11372 */
11373 #define NC_AllowAgg  0x01    /* Aggregate functions are allowed here */
11374 #define NC_HasAgg    0x02    /* One or more aggregate functions seen */
11375 #define NC_IsCheck   0x04    /* True if resolving names in a CHECK constraint */
11376 #define NC_InAggFunc 0x08    /* True if analyzing arguments to an agg func */
11377 #define NC_PartIdx   0x10    /* True if resolving a partial index WHERE */
11378 
11379 /*
11380 ** An instance of the following structure contains all information
11381 ** needed to generate code for a single SELECT statement.
11382 **
11383 ** nLimit is set to -1 if there is no LIMIT clause.  nOffset is set to 0.
11384 ** If there is a LIMIT clause, the parser sets nLimit to the value of the
11385 ** limit and nOffset to the value of the offset (or 0 if there is not
11386 ** offset).  But later on, nLimit and nOffset become the memory locations
11387 ** in the VDBE that record the limit and offset counters.
11388 **
11389 ** addrOpenEphm[] entries contain the address of OP_OpenEphemeral opcodes.
11390 ** These addresses must be stored so that we can go back and fill in
11391 ** the P4_KEYINFO and P2 parameters later.  Neither the KeyInfo nor
11392 ** the number of columns in P2 can be computed at the same time
11393 ** as the OP_OpenEphm instruction is coded because not
11394 ** enough information about the compound query is known at that point.
11395 ** The KeyInfo for addrOpenTran[0] and [1] contains collating sequences
11396 ** for the result set.  The KeyInfo for addrOpenEphm[2] contains collating
11397 ** sequences for the ORDER BY clause.
11398 */
11399 struct Select {
11400   ExprList *pEList;      /* The fields of the result */
11401   u8 op;                 /* One of: TK_UNION TK_ALL TK_INTERSECT TK_EXCEPT */
11402   u16 selFlags;          /* Various SF_* values */
11403   int iLimit, iOffset;   /* Memory registers holding LIMIT & OFFSET counters */
11404   int addrOpenEphm[3];   /* OP_OpenEphem opcodes related to this select */
11405   u64 nSelectRow;        /* Estimated number of result rows */
11406   SrcList *pSrc;         /* The FROM clause */
11407   Expr *pWhere;          /* The WHERE clause */
11408   ExprList *pGroupBy;    /* The GROUP BY clause */
11409   Expr *pHaving;         /* The HAVING clause */
11410   ExprList *pOrderBy;    /* The ORDER BY clause */
11411   Select *pPrior;        /* Prior select in a compound select statement */
11412   Select *pNext;         /* Next select to the left in a compound */
11413   Select *pRightmost;    /* Right-most select in a compound select statement */
11414   Expr *pLimit;          /* LIMIT expression. NULL means not used. */
11415   Expr *pOffset;         /* OFFSET expression. NULL means not used. */
11416 };
11417 
11418 /*
11419 ** Allowed values for Select.selFlags.  The "SF" prefix stands for
11420 ** "Select Flag".
11421 */
11422 #define SF_Distinct        0x0001  /* Output should be DISTINCT */
11423 #define SF_Resolved        0x0002  /* Identifiers have been resolved */
11424 #define SF_Aggregate       0x0004  /* Contains aggregate functions */
11425 #define SF_UsesEphemeral   0x0008  /* Uses the OpenEphemeral opcode */
11426 #define SF_Expanded        0x0010  /* sqlite3SelectExpand() called on this */
11427 #define SF_HasTypeInfo     0x0020  /* FROM subqueries have Table metadata */
11428 #define SF_UseSorter       0x0040  /* Sort using a sorter */
11429 #define SF_Values          0x0080  /* Synthesized from VALUES clause */
11430 #define SF_Materialize     0x0100  /* Force materialization of views */
11431 #define SF_NestedFrom      0x0200  /* Part of a parenthesized FROM clause */
11432 #define SF_MaybeConvert    0x0400  /* Need convertCompoundSelectToSubquery() */
11433 
11434 
11435 /*
11436 ** The results of a select can be distributed in several ways.  The
11437 ** "SRT" prefix means "SELECT Result Type".
11438 */
11439 #define SRT_Union        1  /* Store result as keys in an index */
11440 #define SRT_Except       2  /* Remove result from a UNION index */
11441 #define SRT_Exists       3  /* Store 1 if the result is not empty */
11442 #define SRT_Discard      4  /* Do not save the results anywhere */
11443 
11444 /* The ORDER BY clause is ignored for all of the above */
11445 #define IgnorableOrderby(X) ((X->eDest)<=SRT_Discard)
11446 
11447 #define SRT_Output       5  /* Output each row of result */
11448 #define SRT_Mem          6  /* Store result in a memory cell */
11449 #define SRT_Set          7  /* Store results as keys in an index */
11450 #define SRT_Table        8  /* Store result as data with an automatic rowid */
11451 #define SRT_EphemTab     9  /* Create transient tab and store like SRT_Table */
11452 #define SRT_Coroutine   10  /* Generate a single row of result */
11453 
11454 /*
11455 ** An instance of this object describes where to put of the results of
11456 ** a SELECT statement.
11457 */
11458 struct SelectDest {
11459   u8 eDest;         /* How to dispose of the results.  On of SRT_* above. */
11460   char affSdst;     /* Affinity used when eDest==SRT_Set */
11461   int iSDParm;      /* A parameter used by the eDest disposal method */
11462   int iSdst;        /* Base register where results are written */
11463   int nSdst;        /* Number of registers allocated */
11464 };
11465 
11466 /*
11467 ** During code generation of statements that do inserts into AUTOINCREMENT 
11468 ** tables, the following information is attached to the Table.u.autoInc.p
11469 ** pointer of each autoincrement table to record some side information that
11470 ** the code generator needs.  We have to keep per-table autoincrement
11471 ** information in case inserts are down within triggers.  Triggers do not
11472 ** normally coordinate their activities, but we do need to coordinate the
11473 ** loading and saving of autoincrement information.
11474 */
11475 struct AutoincInfo {
11476   AutoincInfo *pNext;   /* Next info block in a list of them all */
11477   Table *pTab;          /* Table this info block refers to */
11478   int iDb;              /* Index in sqlite3.aDb[] of database holding pTab */
11479   int regCtr;           /* Memory register holding the rowid counter */
11480 };
11481 
11482 /*
11483 ** Size of the column cache
11484 */
11485 #ifndef SQLITE_N_COLCACHE
11486 # define SQLITE_N_COLCACHE 10
11487 #endif
11488 
11489 /*
11490 ** At least one instance of the following structure is created for each 
11491 ** trigger that may be fired while parsing an INSERT, UPDATE or DELETE
11492 ** statement. All such objects are stored in the linked list headed at
11493 ** Parse.pTriggerPrg and deleted once statement compilation has been
11494 ** completed.
11495 **
11496 ** A Vdbe sub-program that implements the body and WHEN clause of trigger
11497 ** TriggerPrg.pTrigger, assuming a default ON CONFLICT clause of
11498 ** TriggerPrg.orconf, is stored in the TriggerPrg.pProgram variable.
11499 ** The Parse.pTriggerPrg list never contains two entries with the same
11500 ** values for both pTrigger and orconf.
11501 **
11502 ** The TriggerPrg.aColmask[0] variable is set to a mask of old.* columns
11503 ** accessed (or set to 0 for triggers fired as a result of INSERT 
11504 ** statements). Similarly, the TriggerPrg.aColmask[1] variable is set to
11505 ** a mask of new.* columns used by the program.
11506 */
11507 struct TriggerPrg {
11508   Trigger *pTrigger;      /* Trigger this program was coded from */
11509   TriggerPrg *pNext;      /* Next entry in Parse.pTriggerPrg list */
11510   SubProgram *pProgram;   /* Program implementing pTrigger/orconf */
11511   int orconf;             /* Default ON CONFLICT policy */
11512   u32 aColmask[2];        /* Masks of old.*, new.* columns accessed */
11513 };
11514 
11515 /*
11516 ** The yDbMask datatype for the bitmask of all attached databases.
11517 */
11518 #if SQLITE_MAX_ATTACHED>30
11519   typedef sqlite3_uint64 yDbMask;
11520 #else
11521   typedef unsigned int yDbMask;
11522 #endif
11523 
11524 /*
11525 ** An SQL parser context.  A copy of this structure is passed through
11526 ** the parser and down into all the parser action routine in order to
11527 ** carry around information that is global to the entire parse.
11528 **
11529 ** The structure is divided into two parts.  When the parser and code
11530 ** generate call themselves recursively, the first part of the structure
11531 ** is constant but the second part is reset at the beginning and end of
11532 ** each recursion.
11533 **
11534 ** The nTableLock and aTableLock variables are only used if the shared-cache 
11535 ** feature is enabled (if sqlite3Tsd()->useSharedData is true). They are
11536 ** used to store the set of table-locks required by the statement being
11537 ** compiled. Function sqlite3TableLock() is used to add entries to the
11538 ** list.
11539 */
11540 struct Parse {
11541   sqlite3 *db;         /* The main database structure */
11542   char *zErrMsg;       /* An error message */
11543   Vdbe *pVdbe;         /* An engine for executing database bytecode */
11544   int rc;              /* Return code from execution */
11545   u8 colNamesSet;      /* TRUE after OP_ColumnName has been issued to pVdbe */
11546   u8 checkSchema;      /* Causes schema cookie check after an error */
11547   u8 nested;           /* Number of nested calls to the parser/code generator */
11548   u8 nTempReg;         /* Number of temporary registers in aTempReg[] */
11549   u8 nTempInUse;       /* Number of aTempReg[] currently checked out */
11550   u8 nColCache;        /* Number of entries in aColCache[] */
11551   u8 iColCache;        /* Next entry in aColCache[] to replace */
11552   u8 isMultiWrite;     /* True if statement may modify/insert multiple rows */
11553   u8 mayAbort;         /* True if statement may throw an ABORT exception */
11554   u8 hasCompound;      /* Need to invoke convertCompoundSelectToSubquery() */
11555   int aTempReg[8];     /* Holding area for temporary registers */
11556   int nRangeReg;       /* Size of the temporary register block */
11557   int iRangeReg;       /* First register in temporary register block */
11558   int nErr;            /* Number of errors seen */
11559   int nTab;            /* Number of previously allocated VDBE cursors */
11560   int nMem;            /* Number of memory cells used so far */
11561   int nSet;            /* Number of sets used so far */
11562   int nOnce;           /* Number of OP_Once instructions so far */
11563   int ckBase;          /* Base register of data during check constraints */
11564   int iPartIdxTab;     /* Table corresponding to a partial index */
11565   int iCacheLevel;     /* ColCache valid when aColCache[].iLevel<=iCacheLevel */
11566   int iCacheCnt;       /* Counter used to generate aColCache[].lru values */
11567   struct yColCache {
11568     int iTable;           /* Table cursor number */
11569     int iColumn;          /* Table column number */
11570     u8 tempReg;           /* iReg is a temp register that needs to be freed */
11571     int iLevel;           /* Nesting level */
11572     int iReg;             /* Reg with value of this column. 0 means none. */
11573     int lru;              /* Least recently used entry has the smallest value */
11574   } aColCache[SQLITE_N_COLCACHE];  /* One for each column cache entry */
11575   ExprList *pConstExpr;/* Constant expressions */
11576   yDbMask writeMask;   /* Start a write transaction on these databases */
11577   yDbMask cookieMask;  /* Bitmask of schema verified databases */
11578   int cookieGoto;      /* Address of OP_Goto to cookie verifier subroutine */
11579   int cookieValue[SQLITE_MAX_ATTACHED+2];  /* Values of cookies to verify */
11580   int regRowid;        /* Register holding rowid of CREATE TABLE entry */
11581   int regRoot;         /* Register holding root page number for new objects */
11582   int nMaxArg;         /* Max args passed to user function by sub-program */
11583   Token constraintName;/* Name of the constraint currently being parsed */
11584 #ifndef SQLITE_OMIT_SHARED_CACHE
11585   int nTableLock;        /* Number of locks in aTableLock */
11586   TableLock *aTableLock; /* Required table locks for shared-cache mode */
11587 #endif
11588   AutoincInfo *pAinc;  /* Information about AUTOINCREMENT counters */
11589 
11590   /* Information used while coding trigger programs. */
11591   Parse *pToplevel;    /* Parse structure for main program (or NULL) */
11592   Table *pTriggerTab;  /* Table triggers are being coded for */
11593   int addrCrTab;       /* Address of OP_CreateTable opcode on CREATE TABLE */
11594   int addrSkipPK;      /* Address of instruction to skip PRIMARY KEY index */
11595   u32 nQueryLoop;      /* Est number of iterations of a query (10*log2(N)) */
11596   u32 oldmask;         /* Mask of old.* columns referenced */
11597   u32 newmask;         /* Mask of new.* columns referenced */
11598   u8 eTriggerOp;       /* TK_UPDATE, TK_INSERT or TK_DELETE */
11599   u8 eOrconf;          /* Default ON CONFLICT policy for trigger steps */
11600   u8 disableTriggers;  /* True to disable triggers */
11601 
11602   /* Above is constant between recursions.  Below is reset before and after
11603   ** each recursion */
11604 
11605   int nVar;                 /* Number of '?' variables seen in the SQL so far */
11606   int nzVar;                /* Number of available slots in azVar[] */
11607   u8 iPkSortOrder;          /* ASC or DESC for INTEGER PRIMARY KEY */
11608   u8 explain;               /* True if the EXPLAIN flag is found on the query */
11609 #ifndef SQLITE_OMIT_VIRTUALTABLE
11610   u8 declareVtab;           /* True if inside sqlite3_declare_vtab() */
11611   int nVtabLock;            /* Number of virtual tables to lock */
11612 #endif
11613   int nAlias;               /* Number of aliased result set columns */
11614   int nHeight;              /* Expression tree height of current sub-select */
11615 #ifndef SQLITE_OMIT_EXPLAIN
11616   int iSelectId;            /* ID of current select for EXPLAIN output */
11617   int iNextSelectId;        /* Next available select ID for EXPLAIN output */
11618 #endif
11619   char **azVar;             /* Pointers to names of parameters */
11620   Vdbe *pReprepare;         /* VM being reprepared (sqlite3Reprepare()) */
11621   const char *zTail;        /* All SQL text past the last semicolon parsed */
11622   Table *pNewTable;         /* A table being constructed by CREATE TABLE */
11623   Trigger *pNewTrigger;     /* Trigger under construct by a CREATE TRIGGER */
11624   const char *zAuthContext; /* The 6th parameter to db->xAuth callbacks */
11625   Token sNameToken;         /* Token with unqualified schema object name */
11626   Token sLastToken;         /* The last token parsed */
11627 #ifndef SQLITE_OMIT_VIRTUALTABLE
11628   Token sArg;               /* Complete text of a module argument */
11629   Table **apVtabLock;       /* Pointer to virtual tables needing locking */
11630 #endif
11631   Table *pZombieTab;        /* List of Table objects to delete after code gen */
11632   TriggerPrg *pTriggerPrg;  /* Linked list of coded triggers */
11633 };
11634 
11635 /*
11636 ** Return true if currently inside an sqlite3_declare_vtab() call.
11637 */
11638 #ifdef SQLITE_OMIT_VIRTUALTABLE
11639   #define IN_DECLARE_VTAB 0
11640 #else
11641   #define IN_DECLARE_VTAB (pParse->declareVtab)
11642 #endif
11643 
11644 /*
11645 ** An instance of the following structure can be declared on a stack and used
11646 ** to save the Parse.zAuthContext value so that it can be restored later.
11647 */
11648 struct AuthContext {
11649   const char *zAuthContext;   /* Put saved Parse.zAuthContext here */
11650   Parse *pParse;              /* The Parse structure */
11651 };
11652 
11653 /*
11654 ** Bitfield flags for P5 value in various opcodes.
11655 */
11656 #define OPFLAG_NCHANGE       0x01    /* Set to update db->nChange */
11657 #define OPFLAG_LASTROWID     0x02    /* Set to update db->lastRowid */
11658 #define OPFLAG_ISUPDATE      0x04    /* This OP_Insert is an sql UPDATE */
11659 #define OPFLAG_APPEND        0x08    /* This is likely to be an append */
11660 #define OPFLAG_USESEEKRESULT 0x10    /* Try to avoid a seek in BtreeInsert() */
11661 #define OPFLAG_CLEARCACHE    0x20    /* Clear pseudo-table cache in OP_Column */
11662 #define OPFLAG_LENGTHARG     0x40    /* OP_Column only used for length() */
11663 #define OPFLAG_TYPEOFARG     0x80    /* OP_Column only used for typeof() */
11664 #define OPFLAG_BULKCSR       0x01    /* OP_Open** used to open bulk cursor */
11665 #define OPFLAG_P2ISREG       0x02    /* P2 to OP_Open** is a register number */
11666 #define OPFLAG_PERMUTE       0x01    /* OP_Compare: use the permutation */
11667 
11668 /*
11669  * Each trigger present in the database schema is stored as an instance of
11670  * struct Trigger. 
11671  *
11672  * Pointers to instances of struct Trigger are stored in two ways.
11673  * 1. In the "trigHash" hash table (part of the sqlite3* that represents the 
11674  *    database). This allows Trigger structures to be retrieved by name.
11675  * 2. All triggers associated with a single table form a linked list, using the
11676  *    pNext member of struct Trigger. A pointer to the first element of the
11677  *    linked list is stored as the "pTrigger" member of the associated
11678  *    struct Table.
11679  *
11680  * The "step_list" member points to the first element of a linked list
11681  * containing the SQL statements specified as the trigger program.
11682  */
11683 struct Trigger {
11684   char *zName;            /* The name of the trigger                        */
11685   char *table;            /* The table or view to which the trigger applies */
11686   u8 op;                  /* One of TK_DELETE, TK_UPDATE, TK_INSERT         */
11687   u8 tr_tm;               /* One of TRIGGER_BEFORE, TRIGGER_AFTER */
11688   Expr *pWhen;            /* The WHEN clause of the expression (may be NULL) */
11689   IdList *pColumns;       /* If this is an UPDATE OF <column-list> trigger,
11690                              the <column-list> is stored here */
11691   Schema *pSchema;        /* Schema containing the trigger */
11692   Schema *pTabSchema;     /* Schema containing the table */
11693   TriggerStep *step_list; /* Link list of trigger program steps             */
11694   Trigger *pNext;         /* Next trigger associated with the table */
11695 };
11696 
11697 /*
11698 ** A trigger is either a BEFORE or an AFTER trigger.  The following constants
11699 ** determine which. 
11700 **
11701 ** If there are multiple triggers, you might of some BEFORE and some AFTER.
11702 ** In that cases, the constants below can be ORed together.
11703 */
11704 #define TRIGGER_BEFORE  1
11705 #define TRIGGER_AFTER   2
11706 
11707 /*
11708  * An instance of struct TriggerStep is used to store a single SQL statement
11709  * that is a part of a trigger-program. 
11710  *
11711  * Instances of struct TriggerStep are stored in a singly linked list (linked
11712  * using the "pNext" member) referenced by the "step_list" member of the 
11713  * associated struct Trigger instance. The first element of the linked list is
11714  * the first step of the trigger-program.
11715  * 
11716  * The "op" member indicates whether this is a "DELETE", "INSERT", "UPDATE" or
11717  * "SELECT" statement. The meanings of the other members is determined by the 
11718  * value of "op" as follows:
11719  *
11720  * (op == TK_INSERT)
11721  * orconf    -> stores the ON CONFLICT algorithm
11722  * pSelect   -> If this is an INSERT INTO ... SELECT ... statement, then
11723  *              this stores a pointer to the SELECT statement. Otherwise NULL.
11724  * target    -> A token holding the quoted name of the table to insert into.
11725  * pExprList -> If this is an INSERT INTO ... VALUES ... statement, then
11726  *              this stores values to be inserted. Otherwise NULL.
11727  * pIdList   -> If this is an INSERT INTO ... (<column-names>) VALUES ... 
11728  *              statement, then this stores the column-names to be
11729  *              inserted into.
11730  *
11731  * (op == TK_DELETE)
11732  * target    -> A token holding the quoted name of the table to delete from.
11733  * pWhere    -> The WHERE clause of the DELETE statement if one is specified.
11734  *              Otherwise NULL.
11735  * 
11736  * (op == TK_UPDATE)
11737  * target    -> A token holding the quoted name of the table to update rows of.
11738  * pWhere    -> The WHERE clause of the UPDATE statement if one is specified.
11739  *              Otherwise NULL.
11740  * pExprList -> A list of the columns to update and the expressions to update
11741  *              them to. See sqlite3Update() documentation of "pChanges"
11742  *              argument.
11743  * 
11744  */
11745 struct TriggerStep {
11746   u8 op;               /* One of TK_DELETE, TK_UPDATE, TK_INSERT, TK_SELECT */
11747   u8 orconf;           /* OE_Rollback etc. */
11748   Trigger *pTrig;      /* The trigger that this step is a part of */
11749   Select *pSelect;     /* SELECT statment or RHS of INSERT INTO .. SELECT ... */
11750   Token target;        /* Target table for DELETE, UPDATE, INSERT */
11751   Expr *pWhere;        /* The WHERE clause for DELETE or UPDATE steps */
11752   ExprList *pExprList; /* SET clause for UPDATE.  VALUES clause for INSERT */
11753   IdList *pIdList;     /* Column names for INSERT */
11754   TriggerStep *pNext;  /* Next in the link-list */
11755   TriggerStep *pLast;  /* Last element in link-list. Valid for 1st elem only */
11756 };
11757 
11758 /*
11759 ** The following structure contains information used by the sqliteFix...
11760 ** routines as they walk the parse tree to make database references
11761 ** explicit.  
11762 */
11763 typedef struct DbFixer DbFixer;
11764 struct DbFixer {
11765   Parse *pParse;      /* The parsing context.  Error messages written here */
11766   Schema *pSchema;    /* Fix items to this schema */
11767   int bVarOnly;       /* Check for variable references only */
11768   const char *zDb;    /* Make sure all objects are contained in this database */
11769   const char *zType;  /* Type of the container - used for error messages */
11770   const Token *pName; /* Name of the container - used for error messages */
11771 };
11772 
11773 /*
11774 ** An objected used to accumulate the text of a string where we
11775 ** do not necessarily know how big the string will be in the end.
11776 */
11777 struct StrAccum {
11778   sqlite3 *db;         /* Optional database for lookaside.  Can be NULL */
11779   char *zBase;         /* A base allocation.  Not from malloc. */
11780   char *zText;         /* The string collected so far */
11781   int  nChar;          /* Length of the string so far */
11782   int  nAlloc;         /* Amount of space allocated in zText */
11783   int  mxAlloc;        /* Maximum allowed string length */
11784   u8   useMalloc;      /* 0: none,  1: sqlite3DbMalloc,  2: sqlite3_malloc */
11785   u8   accError;       /* STRACCUM_NOMEM or STRACCUM_TOOBIG */
11786 };
11787 #define STRACCUM_NOMEM   1
11788 #define STRACCUM_TOOBIG  2
11789 
11790 /*
11791 ** A pointer to this structure is used to communicate information
11792 ** from sqlite3Init and OP_ParseSchema into the sqlite3InitCallback.
11793 */
11794 typedef struct {
11795   sqlite3 *db;        /* The database being initialized */
11796   char **pzErrMsg;    /* Error message stored here */
11797   int iDb;            /* 0 for main database.  1 for TEMP, 2.. for ATTACHed */
11798   int rc;             /* Result code stored here */
11799 } InitData;
11800 
11801 /*
11802 ** Structure containing global configuration data for the SQLite library.
11803 **
11804 ** This structure also contains some state information.
11805 */
11806 struct Sqlite3Config {
11807   int bMemstat;                     /* True to enable memory status */
11808   int bCoreMutex;                   /* True to enable core mutexing */
11809   int bFullMutex;                   /* True to enable full mutexing */
11810   int bOpenUri;                     /* True to interpret filenames as URIs */
11811   int bUseCis;                      /* Use covering indices for full-scans */
11812   int mxStrlen;                     /* Maximum string length */
11813   int neverCorrupt;                 /* Database is always well-formed */
11814   int szLookaside;                  /* Default lookaside buffer size */
11815   int nLookaside;                   /* Default lookaside buffer count */
11816   sqlite3_mem_methods m;            /* Low-level memory allocation interface */
11817   sqlite3_mutex_methods mutex;      /* Low-level mutex interface */
11818   sqlite3_pcache_methods2 pcache2;  /* Low-level page-cache interface */
11819   void *pHeap;                      /* Heap storage space */
11820   int nHeap;                        /* Size of pHeap[] */
11821   int mnReq, mxReq;                 /* Min and max heap requests sizes */
11822   sqlite3_int64 szMmap;             /* mmap() space per open file */
11823   sqlite3_int64 mxMmap;             /* Maximum value for szMmap */
11824   void *pScratch;                   /* Scratch memory */
11825   int szScratch;                    /* Size of each scratch buffer */
11826   int nScratch;                     /* Number of scratch buffers */
11827   void *pPage;                      /* Page cache memory */
11828   int szPage;                       /* Size of each page in pPage[] */
11829   int nPage;                        /* Number of pages in pPage[] */
11830   int mxParserStack;                /* maximum depth of the parser stack */
11831   int sharedCacheEnabled;           /* true if shared-cache mode enabled */
11832   /* The above might be initialized to non-zero.  The following need to always
11833   ** initially be zero, however. */
11834   int isInit;                       /* True after initialization has finished */
11835   int inProgress;                   /* True while initialization in progress */
11836   int isMutexInit;                  /* True after mutexes are initialized */
11837   int isMallocInit;                 /* True after malloc is initialized */
11838   int isPCacheInit;                 /* True after malloc is initialized */
11839   sqlite3_mutex *pInitMutex;        /* Mutex used by sqlite3_initialize() */
11840   int nRefInitMutex;                /* Number of users of pInitMutex */
11841   void (*xLog)(void*,int,const char*); /* Function for logging */
11842   void *pLogArg;                       /* First argument to xLog() */
11843   int bLocaltimeFault;              /* True to fail localtime() calls */
11844 #ifdef SQLITE_ENABLE_SQLLOG
11845   void(*xSqllog)(void*,sqlite3*,const char*, int);
11846   void *pSqllogArg;
11847 #endif
11848 };
11849 
11850 /*
11851 ** This macro is used inside of assert() statements to indicate that
11852 ** the assert is only valid on a well-formed database.  Instead of:
11853 **
11854 **     assert( X );
11855 **
11856 ** One writes:
11857 **
11858 **     assert( X || CORRUPT_DB );
11859 **
11860 ** CORRUPT_DB is true during normal operation.  CORRUPT_DB does not indicate
11861 ** that the database is definitely corrupt, only that it might be corrupt.
11862 ** For most test cases, CORRUPT_DB is set to false using a special
11863 ** sqlite3_test_control().  This enables assert() statements to prove
11864 ** things that are always true for well-formed databases.
11865 */
11866 #define CORRUPT_DB  (sqlite3Config.neverCorrupt==0)
11867 
11868 /*
11869 ** Context pointer passed down through the tree-walk.
11870 */
11871 struct Walker {
11872   int (*xExprCallback)(Walker*, Expr*);     /* Callback for expressions */
11873   int (*xSelectCallback)(Walker*,Select*);  /* Callback for SELECTs */
11874   Parse *pParse;                            /* Parser context.  */
11875   int walkerDepth;                          /* Number of subqueries */
11876   u8 bSelectDepthFirst;                     /* Do subqueries first */
11877   union {                                   /* Extra data for callback */
11878     NameContext *pNC;                          /* Naming context */
11879     int i;                                     /* Integer value */
11880     SrcList *pSrcList;                         /* FROM clause */
11881     struct SrcCount *pSrcCount;                /* Counting column references */
11882   } u;
11883 };
11884 
11885 /* Forward declarations */
11886 SQLITE_PRIVATE int sqlite3WalkExpr(Walker*, Expr*);
11887 SQLITE_PRIVATE int sqlite3WalkExprList(Walker*, ExprList*);
11888 SQLITE_PRIVATE int sqlite3WalkSelect(Walker*, Select*);
11889 SQLITE_PRIVATE int sqlite3WalkSelectExpr(Walker*, Select*);
11890 SQLITE_PRIVATE int sqlite3WalkSelectFrom(Walker*, Select*);
11891 
11892 /*
11893 ** Return code from the parse-tree walking primitives and their
11894 ** callbacks.
11895 */
11896 #define WRC_Continue    0   /* Continue down into children */
11897 #define WRC_Prune       1   /* Omit children but continue walking siblings */
11898 #define WRC_Abort       2   /* Abandon the tree walk */
11899 
11900 /*
11901 ** Assuming zIn points to the first byte of a UTF-8 character,
11902 ** advance zIn to point to the first byte of the next UTF-8 character.
11903 */
11904 #define SQLITE_SKIP_UTF8(zIn) {                        \
11905   if( (*(zIn++))>=0xc0 ){                              \
11906     while( (*zIn & 0xc0)==0x80 ){ zIn++; }             \
11907   }                                                    \
11908 }
11909 
11910 /*
11911 ** The SQLITE_*_BKPT macros are substitutes for the error codes with
11912 ** the same name but without the _BKPT suffix.  These macros invoke
11913 ** routines that report the line-number on which the error originated
11914 ** using sqlite3_log().  The routines also provide a convenient place
11915 ** to set a debugger breakpoint.
11916 */
11917 SQLITE_PRIVATE int sqlite3CorruptError(int);
11918 SQLITE_PRIVATE int sqlite3MisuseError(int);
11919 SQLITE_PRIVATE int sqlite3CantopenError(int);
11920 #define SQLITE_CORRUPT_BKPT sqlite3CorruptError(__LINE__)
11921 #define SQLITE_MISUSE_BKPT sqlite3MisuseError(__LINE__)
11922 #define SQLITE_CANTOPEN_BKPT sqlite3CantopenError(__LINE__)
11923 
11924 
11925 /*
11926 ** FTS4 is really an extension for FTS3.  It is enabled using the
11927 ** SQLITE_ENABLE_FTS3 macro.  But to avoid confusion we also all
11928 ** the SQLITE_ENABLE_FTS4 macro to serve as an alisse for SQLITE_ENABLE_FTS3.
11929 */
11930 #if defined(SQLITE_ENABLE_FTS4) && !defined(SQLITE_ENABLE_FTS3)
11931 # define SQLITE_ENABLE_FTS3
11932 #endif
11933 
11934 /*
11935 ** The ctype.h header is needed for non-ASCII systems.  It is also
11936 ** needed by FTS3 when FTS3 is included in the amalgamation.
11937 */
11938 #if !defined(SQLITE_ASCII) || \
11939     (defined(SQLITE_ENABLE_FTS3) && defined(SQLITE_AMALGAMATION))
11940 # include <ctype.h>
11941 #endif
11942 
11943 /*
11944 ** The following macros mimic the standard library functions toupper(),
11945 ** isspace(), isalnum(), isdigit() and isxdigit(), respectively. The
11946 ** sqlite versions only work for ASCII characters, regardless of locale.
11947 */
11948 #ifdef SQLITE_ASCII
11949 # define sqlite3Toupper(x)  ((x)&~(sqlite3CtypeMap[(unsigned char)(x)]&0x20))
11950 # define sqlite3Isspace(x)   (sqlite3CtypeMap[(unsigned char)(x)]&0x01)
11951 # define sqlite3Isalnum(x)   (sqlite3CtypeMap[(unsigned char)(x)]&0x06)
11952 # define sqlite3Isalpha(x)   (sqlite3CtypeMap[(unsigned char)(x)]&0x02)
11953 # define sqlite3Isdigit(x)   (sqlite3CtypeMap[(unsigned char)(x)]&0x04)
11954 # define sqlite3Isxdigit(x)  (sqlite3CtypeMap[(unsigned char)(x)]&0x08)
11955 # define sqlite3Tolower(x)   (sqlite3UpperToLower[(unsigned char)(x)])
11956 #else
11957 # define sqlite3Toupper(x)   toupper((unsigned char)(x))
11958 # define sqlite3Isspace(x)   isspace((unsigned char)(x))
11959 # define sqlite3Isalnum(x)   isalnum((unsigned char)(x))
11960 # define sqlite3Isalpha(x)   isalpha((unsigned char)(x))
11961 # define sqlite3Isdigit(x)   isdigit((unsigned char)(x))
11962 # define sqlite3Isxdigit(x)  isxdigit((unsigned char)(x))
11963 # define sqlite3Tolower(x)   tolower((unsigned char)(x))
11964 #endif
11965 
11966 /*
11967 ** Internal function prototypes
11968 */
11969 #define sqlite3StrICmp sqlite3_stricmp
11970 SQLITE_PRIVATE int sqlite3Strlen30(const char*);
11971 #define sqlite3StrNICmp sqlite3_strnicmp
11972 
11973 SQLITE_PRIVATE int sqlite3MallocInit(void);
11974 SQLITE_PRIVATE void sqlite3MallocEnd(void);
11975 SQLITE_PRIVATE void *sqlite3Malloc(int);
11976 SQLITE_PRIVATE void *sqlite3MallocZero(int);
11977 SQLITE_PRIVATE void *sqlite3DbMallocZero(sqlite3*, int);
11978 SQLITE_PRIVATE void *sqlite3DbMallocRaw(sqlite3*, int);
11979 SQLITE_PRIVATE char *sqlite3DbStrDup(sqlite3*,const char*);
11980 SQLITE_PRIVATE char *sqlite3DbStrNDup(sqlite3*,const char*, int);
11981 SQLITE_PRIVATE void *sqlite3Realloc(void*, int);
11982 SQLITE_PRIVATE void *sqlite3DbReallocOrFree(sqlite3 *, void *, int);
11983 SQLITE_PRIVATE void *sqlite3DbRealloc(sqlite3 *, void *, int);
11984 SQLITE_PRIVATE void sqlite3DbFree(sqlite3*, void*);
11985 SQLITE_PRIVATE int sqlite3MallocSize(void*);
11986 SQLITE_PRIVATE int sqlite3DbMallocSize(sqlite3*, void*);
11987 SQLITE_PRIVATE void *sqlite3ScratchMalloc(int);
11988 SQLITE_PRIVATE void sqlite3ScratchFree(void*);
11989 SQLITE_PRIVATE void *sqlite3PageMalloc(int);
11990 SQLITE_PRIVATE void sqlite3PageFree(void*);
11991 SQLITE_PRIVATE void sqlite3MemSetDefault(void);
11992 SQLITE_PRIVATE void sqlite3BenignMallocHooks(void (*)(void), void (*)(void));
11993 SQLITE_PRIVATE int sqlite3HeapNearlyFull(void);
11994 
11995 /*
11996 ** On systems with ample stack space and that support alloca(), make
11997 ** use of alloca() to obtain space for large automatic objects.  By default,
11998 ** obtain space from malloc().
11999 **
12000 ** The alloca() routine never returns NULL.  This will cause code paths
12001 ** that deal with sqlite3StackAlloc() failures to be unreachable.
12002 */
12003 #ifdef SQLITE_USE_ALLOCA
12004 # define sqlite3StackAllocRaw(D,N)   alloca(N)
12005 # define sqlite3StackAllocZero(D,N)  memset(alloca(N), 0, N)
12006 # define sqlite3StackFree(D,P)       
12007 #else
12008 # define sqlite3StackAllocRaw(D,N)   sqlite3DbMallocRaw(D,N)
12009 # define sqlite3StackAllocZero(D,N)  sqlite3DbMallocZero(D,N)
12010 # define sqlite3StackFree(D,P)       sqlite3DbFree(D,P)
12011 #endif
12012 
12013 #ifdef SQLITE_ENABLE_MEMSYS3
12014 SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetMemsys3(void);
12015 #endif
12016 #ifdef SQLITE_ENABLE_MEMSYS5
12017 SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetMemsys5(void);
12018 #endif
12019 
12020 
12021 #ifndef SQLITE_MUTEX_OMIT
12022 SQLITE_PRIVATE   sqlite3_mutex_methods const *sqlite3DefaultMutex(void);
12023 SQLITE_PRIVATE   sqlite3_mutex_methods const *sqlite3NoopMutex(void);
12024 SQLITE_PRIVATE   sqlite3_mutex *sqlite3MutexAlloc(int);
12025 SQLITE_PRIVATE   int sqlite3MutexInit(void);
12026 SQLITE_PRIVATE   int sqlite3MutexEnd(void);
12027 #endif
12028 
12029 SQLITE_PRIVATE int sqlite3StatusValue(int);
12030 SQLITE_PRIVATE void sqlite3StatusAdd(int, int);
12031 SQLITE_PRIVATE void sqlite3StatusSet(int, int);
12032 
12033 #ifndef SQLITE_OMIT_FLOATING_POINT
12034 SQLITE_PRIVATE   int sqlite3IsNaN(double);
12035 #else
12036 # define sqlite3IsNaN(X)  0
12037 #endif
12038 
12039 SQLITE_PRIVATE void sqlite3VXPrintf(StrAccum*, int, const char*, va_list);
12040 #ifndef SQLITE_OMIT_TRACE
12041 SQLITE_PRIVATE void sqlite3XPrintf(StrAccum*, const char*, ...);
12042 #endif
12043 SQLITE_PRIVATE char *sqlite3MPrintf(sqlite3*,const char*, ...);
12044 SQLITE_PRIVATE char *sqlite3VMPrintf(sqlite3*,const char*, va_list);
12045 SQLITE_PRIVATE char *sqlite3MAppendf(sqlite3*,char*,const char*,...);
12046 #if defined(SQLITE_TEST) || defined(SQLITE_DEBUG)
12047 SQLITE_PRIVATE   void sqlite3DebugPrintf(const char*, ...);
12048 #endif
12049 #if defined(SQLITE_TEST)
12050 SQLITE_PRIVATE   void *sqlite3TestTextToPtr(const char*);
12051 #endif
12052 
12053 /* Output formatting for SQLITE_TESTCTRL_EXPLAIN */
12054 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
12055 SQLITE_PRIVATE   void sqlite3ExplainBegin(Vdbe*);
12056 SQLITE_PRIVATE   void sqlite3ExplainPrintf(Vdbe*, const char*, ...);
12057 SQLITE_PRIVATE   void sqlite3ExplainNL(Vdbe*);
12058 SQLITE_PRIVATE   void sqlite3ExplainPush(Vdbe*);
12059 SQLITE_PRIVATE   void sqlite3ExplainPop(Vdbe*);
12060 SQLITE_PRIVATE   void sqlite3ExplainFinish(Vdbe*);
12061 SQLITE_PRIVATE   void sqlite3ExplainSelect(Vdbe*, Select*);
12062 SQLITE_PRIVATE   void sqlite3ExplainExpr(Vdbe*, Expr*);
12063 SQLITE_PRIVATE   void sqlite3ExplainExprList(Vdbe*, ExprList*);
12064 SQLITE_PRIVATE   const char *sqlite3VdbeExplanation(Vdbe*);
12065 #else
12066 # define sqlite3ExplainBegin(X)
12067 # define sqlite3ExplainSelect(A,B)
12068 # define sqlite3ExplainExpr(A,B)
12069 # define sqlite3ExplainExprList(A,B)
12070 # define sqlite3ExplainFinish(X)
12071 # define sqlite3VdbeExplanation(X) 0
12072 #endif
12073 
12074 
12075 SQLITE_PRIVATE void sqlite3SetString(char **, sqlite3*, const char*, ...);
12076 SQLITE_PRIVATE void sqlite3ErrorMsg(Parse*, const char*, ...);
12077 SQLITE_PRIVATE int sqlite3Dequote(char*);
12078 SQLITE_PRIVATE int sqlite3KeywordCode(const unsigned char*, int);
12079 SQLITE_PRIVATE int sqlite3RunParser(Parse*, const char*, char **);
12080 SQLITE_PRIVATE void sqlite3FinishCoding(Parse*);
12081 SQLITE_PRIVATE int sqlite3GetTempReg(Parse*);
12082 SQLITE_PRIVATE void sqlite3ReleaseTempReg(Parse*,int);
12083 SQLITE_PRIVATE int sqlite3GetTempRange(Parse*,int);
12084 SQLITE_PRIVATE void sqlite3ReleaseTempRange(Parse*,int,int);
12085 SQLITE_PRIVATE void sqlite3ClearTempRegCache(Parse*);
12086 SQLITE_PRIVATE Expr *sqlite3ExprAlloc(sqlite3*,int,const Token*,int);
12087 SQLITE_PRIVATE Expr *sqlite3Expr(sqlite3*,int,const char*);
12088 SQLITE_PRIVATE void sqlite3ExprAttachSubtrees(sqlite3*,Expr*,Expr*,Expr*);
12089 SQLITE_PRIVATE Expr *sqlite3PExpr(Parse*, int, Expr*, Expr*, const Token*);
12090 SQLITE_PRIVATE Expr *sqlite3ExprAnd(sqlite3*,Expr*, Expr*);
12091 SQLITE_PRIVATE Expr *sqlite3ExprFunction(Parse*,ExprList*, Token*);
12092 SQLITE_PRIVATE void sqlite3ExprAssignVarNumber(Parse*, Expr*);
12093 SQLITE_PRIVATE void sqlite3ExprDelete(sqlite3*, Expr*);
12094 SQLITE_PRIVATE ExprList *sqlite3ExprListAppend(Parse*,ExprList*,Expr*);
12095 SQLITE_PRIVATE void sqlite3ExprListSetName(Parse*,ExprList*,Token*,int);
12096 SQLITE_PRIVATE void sqlite3ExprListSetSpan(Parse*,ExprList*,ExprSpan*);
12097 SQLITE_PRIVATE void sqlite3ExprListDelete(sqlite3*, ExprList*);
12098 SQLITE_PRIVATE int sqlite3Init(sqlite3*, char**);
12099 SQLITE_PRIVATE int sqlite3InitCallback(void*, int, char**, char**);
12100 SQLITE_PRIVATE void sqlite3Pragma(Parse*,Token*,Token*,Token*,int);
12101 SQLITE_PRIVATE void sqlite3ResetAllSchemasOfConnection(sqlite3*);
12102 SQLITE_PRIVATE void sqlite3ResetOneSchema(sqlite3*,int);
12103 SQLITE_PRIVATE void sqlite3CollapseDatabaseArray(sqlite3*);
12104 SQLITE_PRIVATE void sqlite3BeginParse(Parse*,int);
12105 SQLITE_PRIVATE void sqlite3CommitInternalChanges(sqlite3*);
12106 SQLITE_PRIVATE Table *sqlite3ResultSetOfSelect(Parse*,Select*);
12107 SQLITE_PRIVATE void sqlite3OpenMasterTable(Parse *, int);
12108 SQLITE_PRIVATE Index *sqlite3PrimaryKeyIndex(Table*);
12109 SQLITE_PRIVATE i16 sqlite3ColumnOfIndex(Index*, i16);
12110 SQLITE_PRIVATE void sqlite3StartTable(Parse*,Token*,Token*,int,int,int,int);
12111 SQLITE_PRIVATE void sqlite3AddColumn(Parse*,Token*);
12112 SQLITE_PRIVATE void sqlite3AddNotNull(Parse*, int);
12113 SQLITE_PRIVATE void sqlite3AddPrimaryKey(Parse*, ExprList*, int, int, int);
12114 SQLITE_PRIVATE void sqlite3AddCheckConstraint(Parse*, Expr*);
12115 SQLITE_PRIVATE void sqlite3AddColumnType(Parse*,Token*);
12116 SQLITE_PRIVATE void sqlite3AddDefaultValue(Parse*,ExprSpan*);
12117 SQLITE_PRIVATE void sqlite3AddCollateType(Parse*, Token*);
12118 SQLITE_PRIVATE void sqlite3EndTable(Parse*,Token*,Token*,u8,Select*);
12119 SQLITE_PRIVATE int sqlite3ParseUri(const char*,const char*,unsigned int*,
12120                     sqlite3_vfs**,char**,char **);
12121 SQLITE_PRIVATE Btree *sqlite3DbNameToBtree(sqlite3*,const char*);
12122 SQLITE_PRIVATE int sqlite3CodeOnce(Parse *);
12123 
12124 SQLITE_PRIVATE Bitvec *sqlite3BitvecCreate(u32);
12125 SQLITE_PRIVATE int sqlite3BitvecTest(Bitvec*, u32);
12126 SQLITE_PRIVATE int sqlite3BitvecSet(Bitvec*, u32);
12127 SQLITE_PRIVATE void sqlite3BitvecClear(Bitvec*, u32, void*);
12128 SQLITE_PRIVATE void sqlite3BitvecDestroy(Bitvec*);
12129 SQLITE_PRIVATE u32 sqlite3BitvecSize(Bitvec*);
12130 SQLITE_PRIVATE int sqlite3BitvecBuiltinTest(int,int*);
12131 
12132 SQLITE_PRIVATE RowSet *sqlite3RowSetInit(sqlite3*, void*, unsigned int);
12133 SQLITE_PRIVATE void sqlite3RowSetClear(RowSet*);
12134 SQLITE_PRIVATE void sqlite3RowSetInsert(RowSet*, i64);
12135 SQLITE_PRIVATE int sqlite3RowSetTest(RowSet*, u8 iBatch, i64);
12136 SQLITE_PRIVATE int sqlite3RowSetNext(RowSet*, i64*);
12137 
12138 SQLITE_PRIVATE void sqlite3CreateView(Parse*,Token*,Token*,Token*,Select*,int,int);
12139 
12140 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_VIRTUALTABLE)
12141 SQLITE_PRIVATE   int sqlite3ViewGetColumnNames(Parse*,Table*);
12142 #else
12143 # define sqlite3ViewGetColumnNames(A,B) 0
12144 #endif
12145 
12146 SQLITE_PRIVATE void sqlite3DropTable(Parse*, SrcList*, int, int);
12147 SQLITE_PRIVATE void sqlite3CodeDropTable(Parse*, Table*, int, int);
12148 SQLITE_PRIVATE void sqlite3DeleteTable(sqlite3*, Table*);
12149 #ifndef SQLITE_OMIT_AUTOINCREMENT
12150 SQLITE_PRIVATE   void sqlite3AutoincrementBegin(Parse *pParse);
12151 SQLITE_PRIVATE   void sqlite3AutoincrementEnd(Parse *pParse);
12152 #else
12153 # define sqlite3AutoincrementBegin(X)
12154 # define sqlite3AutoincrementEnd(X)
12155 #endif
12156 SQLITE_PRIVATE int sqlite3CodeCoroutine(Parse*, Select*, SelectDest*);
12157 SQLITE_PRIVATE void sqlite3Insert(Parse*, SrcList*, ExprList*, Select*, IdList*, int);
12158 SQLITE_PRIVATE void *sqlite3ArrayAllocate(sqlite3*,void*,int,int*,int*);
12159 SQLITE_PRIVATE IdList *sqlite3IdListAppend(sqlite3*, IdList*, Token*);
12160 SQLITE_PRIVATE int sqlite3IdListIndex(IdList*,const char*);
12161 SQLITE_PRIVATE SrcList *sqlite3SrcListEnlarge(sqlite3*, SrcList*, int, int);
12162 SQLITE_PRIVATE SrcList *sqlite3SrcListAppend(sqlite3*, SrcList*, Token*, Token*);
12163 SQLITE_PRIVATE SrcList *sqlite3SrcListAppendFromTerm(Parse*, SrcList*, Token*, Token*,
12164                                       Token*, Select*, Expr*, IdList*);
12165 SQLITE_PRIVATE void sqlite3SrcListIndexedBy(Parse *, SrcList *, Token *);
12166 SQLITE_PRIVATE int sqlite3IndexedByLookup(Parse *, struct SrcList_item *);
12167 SQLITE_PRIVATE void sqlite3SrcListShiftJoinType(SrcList*);
12168 SQLITE_PRIVATE void sqlite3SrcListAssignCursors(Parse*, SrcList*);
12169 SQLITE_PRIVATE void sqlite3IdListDelete(sqlite3*, IdList*);
12170 SQLITE_PRIVATE void sqlite3SrcListDelete(sqlite3*, SrcList*);
12171 SQLITE_PRIVATE Index *sqlite3AllocateIndexObject(sqlite3*,i16,int,char**);
12172 SQLITE_PRIVATE Index *sqlite3CreateIndex(Parse*,Token*,Token*,SrcList*,ExprList*,int,Token*,
12173                           Expr*, int, int);
12174 SQLITE_PRIVATE void sqlite3DropIndex(Parse*, SrcList*, int);
12175 SQLITE_PRIVATE int sqlite3Select(Parse*, Select*, SelectDest*);
12176 SQLITE_PRIVATE Select *sqlite3SelectNew(Parse*,ExprList*,SrcList*,Expr*,ExprList*,
12177                          Expr*,ExprList*,u16,Expr*,Expr*);
12178 SQLITE_PRIVATE void sqlite3SelectDelete(sqlite3*, Select*);
12179 SQLITE_PRIVATE Table *sqlite3SrcListLookup(Parse*, SrcList*);
12180 SQLITE_PRIVATE int sqlite3IsReadOnly(Parse*, Table*, int);
12181 SQLITE_PRIVATE void sqlite3OpenTable(Parse*, int iCur, int iDb, Table*, int);
12182 #if defined(SQLITE_ENABLE_UPDATE_DELETE_LIMIT) && !defined(SQLITE_OMIT_SUBQUERY)
12183 SQLITE_PRIVATE Expr *sqlite3LimitWhere(Parse*,SrcList*,Expr*,ExprList*,Expr*,Expr*,char*);
12184 #endif
12185 SQLITE_PRIVATE void sqlite3DeleteFrom(Parse*, SrcList*, Expr*);
12186 SQLITE_PRIVATE void sqlite3Update(Parse*, SrcList*, ExprList*, Expr*, int);
12187 SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin(Parse*,SrcList*,Expr*,ExprList*,ExprList*,u16,int);
12188 SQLITE_PRIVATE void sqlite3WhereEnd(WhereInfo*);
12189 SQLITE_PRIVATE u64 sqlite3WhereOutputRowCount(WhereInfo*);
12190 SQLITE_PRIVATE int sqlite3WhereIsDistinct(WhereInfo*);
12191 SQLITE_PRIVATE int sqlite3WhereIsOrdered(WhereInfo*);
12192 SQLITE_PRIVATE int sqlite3WhereContinueLabel(WhereInfo*);
12193 SQLITE_PRIVATE int sqlite3WhereBreakLabel(WhereInfo*);
12194 SQLITE_PRIVATE int sqlite3WhereOkOnePass(WhereInfo*, int*);
12195 SQLITE_PRIVATE int sqlite3ExprCodeGetColumn(Parse*, Table*, int, int, int, u8);
12196 SQLITE_PRIVATE void sqlite3ExprCodeGetColumnOfTable(Vdbe*, Table*, int, int, int);
12197 SQLITE_PRIVATE void sqlite3ExprCodeMove(Parse*, int, int, int);
12198 SQLITE_PRIVATE void sqlite3ExprCacheStore(Parse*, int, int, int);
12199 SQLITE_PRIVATE void sqlite3ExprCachePush(Parse*);
12200 SQLITE_PRIVATE void sqlite3ExprCachePop(Parse*, int);
12201 SQLITE_PRIVATE void sqlite3ExprCacheRemove(Parse*, int, int);
12202 SQLITE_PRIVATE void sqlite3ExprCacheClear(Parse*);
12203 SQLITE_PRIVATE void sqlite3ExprCacheAffinityChange(Parse*, int, int);
12204 SQLITE_PRIVATE int sqlite3ExprCode(Parse*, Expr*, int);
12205 SQLITE_PRIVATE void sqlite3ExprCodeAtInit(Parse*, Expr*, int, u8);
12206 SQLITE_PRIVATE int sqlite3ExprCodeTemp(Parse*, Expr*, int*);
12207 SQLITE_PRIVATE int sqlite3ExprCodeTarget(Parse*, Expr*, int);
12208 SQLITE_PRIVATE int sqlite3ExprCodeAndCache(Parse*, Expr*, int);
12209 SQLITE_PRIVATE int sqlite3ExprCodeExprList(Parse*, ExprList*, int, u8);
12210 #define SQLITE_ECEL_DUP      0x01  /* Deep, not shallow copies */
12211 #define SQLITE_ECEL_FACTOR   0x02  /* Factor out constant terms */
12212 SQLITE_PRIVATE void sqlite3ExprIfTrue(Parse*, Expr*, int, int);
12213 SQLITE_PRIVATE void sqlite3ExprIfFalse(Parse*, Expr*, int, int);
12214 SQLITE_PRIVATE Table *sqlite3FindTable(sqlite3*,const char*, const char*);
12215 SQLITE_PRIVATE Table *sqlite3LocateTable(Parse*,int isView,const char*, const char*);
12216 SQLITE_PRIVATE Table *sqlite3LocateTableItem(Parse*,int isView,struct SrcList_item *);
12217 SQLITE_PRIVATE Index *sqlite3FindIndex(sqlite3*,const char*, const char*);
12218 SQLITE_PRIVATE void sqlite3UnlinkAndDeleteTable(sqlite3*,int,const char*);
12219 SQLITE_PRIVATE void sqlite3UnlinkAndDeleteIndex(sqlite3*,int,const char*);
12220 SQLITE_PRIVATE void sqlite3Vacuum(Parse*);
12221 SQLITE_PRIVATE int sqlite3RunVacuum(char**, sqlite3*);
12222 SQLITE_PRIVATE char *sqlite3NameFromToken(sqlite3*, Token*);
12223 SQLITE_PRIVATE int sqlite3ExprCompare(Expr*, Expr*, int);
12224 SQLITE_PRIVATE int sqlite3ExprListCompare(ExprList*, ExprList*, int);
12225 SQLITE_PRIVATE int sqlite3ExprImpliesExpr(Expr*, Expr*, int);
12226 SQLITE_PRIVATE void sqlite3ExprAnalyzeAggregates(NameContext*, Expr*);
12227 SQLITE_PRIVATE void sqlite3ExprAnalyzeAggList(NameContext*,ExprList*);
12228 SQLITE_PRIVATE int sqlite3FunctionUsesThisSrc(Expr*, SrcList*);
12229 SQLITE_PRIVATE Vdbe *sqlite3GetVdbe(Parse*);
12230 SQLITE_PRIVATE void sqlite3PrngSaveState(void);
12231 SQLITE_PRIVATE void sqlite3PrngRestoreState(void);
12232 SQLITE_PRIVATE void sqlite3PrngResetState(void);
12233 SQLITE_PRIVATE void sqlite3RollbackAll(sqlite3*,int);
12234 SQLITE_PRIVATE void sqlite3CodeVerifySchema(Parse*, int);
12235 SQLITE_PRIVATE void sqlite3CodeVerifyNamedSchema(Parse*, const char *zDb);
12236 SQLITE_PRIVATE void sqlite3BeginTransaction(Parse*, int);
12237 SQLITE_PRIVATE void sqlite3CommitTransaction(Parse*);
12238 SQLITE_PRIVATE void sqlite3RollbackTransaction(Parse*);
12239 SQLITE_PRIVATE void sqlite3Savepoint(Parse*, int, Token*);
12240 SQLITE_PRIVATE void sqlite3CloseSavepoints(sqlite3 *);
12241 SQLITE_PRIVATE void sqlite3LeaveMutexAndCloseZombie(sqlite3*);
12242 SQLITE_PRIVATE int sqlite3ExprIsConstant(Expr*);
12243 SQLITE_PRIVATE int sqlite3ExprIsConstantNotJoin(Expr*);
12244 SQLITE_PRIVATE int sqlite3ExprIsConstantOrFunction(Expr*);
12245 SQLITE_PRIVATE int sqlite3ExprIsInteger(Expr*, int*);
12246 SQLITE_PRIVATE int sqlite3ExprCanBeNull(const Expr*);
12247 SQLITE_PRIVATE void sqlite3ExprCodeIsNullJump(Vdbe*, const Expr*, int, int);
12248 SQLITE_PRIVATE int sqlite3ExprNeedsNoAffinityChange(const Expr*, char);
12249 SQLITE_PRIVATE int sqlite3IsRowid(const char*);
12250 SQLITE_PRIVATE void sqlite3GenerateRowDelete(Parse*,Table*,Trigger*,int,int,int,i16,u8,u8,u8);
12251 SQLITE_PRIVATE void sqlite3GenerateRowIndexDelete(Parse*, Table*, int, int, int*);
12252 SQLITE_PRIVATE int sqlite3GenerateIndexKey(Parse*, Index*, int, int, int, int*);
12253 SQLITE_PRIVATE void sqlite3GenerateConstraintChecks(Parse*,Table*,int*,int,int,int,int,
12254                                      u8,u8,int,int*);
12255 SQLITE_PRIVATE void sqlite3CompleteInsertion(Parse*,Table*,int,int,int,int*,int,int,int);
12256 SQLITE_PRIVATE int sqlite3OpenTableAndIndices(Parse*, Table*, int, int, u8*, int*, int*);
12257 SQLITE_PRIVATE void sqlite3BeginWriteOperation(Parse*, int, int);
12258 SQLITE_PRIVATE void sqlite3MultiWrite(Parse*);
12259 SQLITE_PRIVATE void sqlite3MayAbort(Parse*);
12260 SQLITE_PRIVATE void sqlite3HaltConstraint(Parse*, int, int, char*, i8, u8);
12261 SQLITE_PRIVATE void sqlite3UniqueConstraint(Parse*, int, Index*);
12262 SQLITE_PRIVATE void sqlite3RowidConstraint(Parse*, int, Table*);
12263 SQLITE_PRIVATE Expr *sqlite3ExprDup(sqlite3*,Expr*,int);
12264 SQLITE_PRIVATE ExprList *sqlite3ExprListDup(sqlite3*,ExprList*,int);
12265 SQLITE_PRIVATE SrcList *sqlite3SrcListDup(sqlite3*,SrcList*,int);
12266 SQLITE_PRIVATE IdList *sqlite3IdListDup(sqlite3*,IdList*);
12267 SQLITE_PRIVATE Select *sqlite3SelectDup(sqlite3*,Select*,int);
12268 SQLITE_PRIVATE void sqlite3FuncDefInsert(FuncDefHash*, FuncDef*);
12269 SQLITE_PRIVATE FuncDef *sqlite3FindFunction(sqlite3*,const char*,int,int,u8,u8);
12270 SQLITE_PRIVATE void sqlite3RegisterBuiltinFunctions(sqlite3*);
12271 SQLITE_PRIVATE void sqlite3RegisterDateTimeFunctions(void);
12272 SQLITE_PRIVATE void sqlite3RegisterGlobalFunctions(void);
12273 SQLITE_PRIVATE int sqlite3SafetyCheckOk(sqlite3*);
12274 SQLITE_PRIVATE int sqlite3SafetyCheckSickOrOk(sqlite3*);
12275 SQLITE_PRIVATE void sqlite3ChangeCookie(Parse*, int);
12276 
12277 #if !defined(SQLITE_OMIT_VIEW) && !defined(SQLITE_OMIT_TRIGGER)
12278 SQLITE_PRIVATE void sqlite3MaterializeView(Parse*, Table*, Expr*, int);
12279 #endif
12280 
12281 #ifndef SQLITE_OMIT_TRIGGER
12282 SQLITE_PRIVATE   void sqlite3BeginTrigger(Parse*, Token*,Token*,int,int,IdList*,SrcList*,
12283                            Expr*,int, int);
12284 SQLITE_PRIVATE   void sqlite3FinishTrigger(Parse*, TriggerStep*, Token*);
12285 SQLITE_PRIVATE   void sqlite3DropTrigger(Parse*, SrcList*, int);
12286 SQLITE_PRIVATE   void sqlite3DropTriggerPtr(Parse*, Trigger*);
12287 SQLITE_PRIVATE   Trigger *sqlite3TriggersExist(Parse *, Table*, int, ExprList*, int *pMask);
12288 SQLITE_PRIVATE   Trigger *sqlite3TriggerList(Parse *, Table *);
12289 SQLITE_PRIVATE   void sqlite3CodeRowTrigger(Parse*, Trigger *, int, ExprList*, int, Table *,
12290                             int, int, int);
12291 SQLITE_PRIVATE   void sqlite3CodeRowTriggerDirect(Parse *, Trigger *, Table *, int, int, int);
12292   void sqliteViewTriggers(Parse*, Table*, Expr*, int, ExprList*);
12293 SQLITE_PRIVATE   void sqlite3DeleteTriggerStep(sqlite3*, TriggerStep*);
12294 SQLITE_PRIVATE   TriggerStep *sqlite3TriggerSelectStep(sqlite3*,Select*);
12295 SQLITE_PRIVATE   TriggerStep *sqlite3TriggerInsertStep(sqlite3*,Token*, IdList*,
12296                                         ExprList*,Select*,u8);
12297 SQLITE_PRIVATE   TriggerStep *sqlite3TriggerUpdateStep(sqlite3*,Token*,ExprList*, Expr*, u8);
12298 SQLITE_PRIVATE   TriggerStep *sqlite3TriggerDeleteStep(sqlite3*,Token*, Expr*);
12299 SQLITE_PRIVATE   void sqlite3DeleteTrigger(sqlite3*, Trigger*);
12300 SQLITE_PRIVATE   void sqlite3UnlinkAndDeleteTrigger(sqlite3*,int,const char*);
12301 SQLITE_PRIVATE   u32 sqlite3TriggerColmask(Parse*,Trigger*,ExprList*,int,int,Table*,int);
12302 # define sqlite3ParseToplevel(p) ((p)->pToplevel ? (p)->pToplevel : (p))
12303 #else
12304 # define sqlite3TriggersExist(B,C,D,E,F) 0
12305 # define sqlite3DeleteTrigger(A,B)
12306 # define sqlite3DropTriggerPtr(A,B)
12307 # define sqlite3UnlinkAndDeleteTrigger(A,B,C)
12308 # define sqlite3CodeRowTrigger(A,B,C,D,E,F,G,H,I)
12309 # define sqlite3CodeRowTriggerDirect(A,B,C,D,E,F)
12310 # define sqlite3TriggerList(X, Y) 0
12311 # define sqlite3ParseToplevel(p) p
12312 # define sqlite3TriggerColmask(A,B,C,D,E,F,G) 0
12313 #endif
12314 
12315 SQLITE_PRIVATE int sqlite3JoinType(Parse*, Token*, Token*, Token*);
12316 SQLITE_PRIVATE void sqlite3CreateForeignKey(Parse*, ExprList*, Token*, ExprList*, int);
12317 SQLITE_PRIVATE void sqlite3DeferForeignKey(Parse*, int);
12318 #ifndef SQLITE_OMIT_AUTHORIZATION
12319 SQLITE_PRIVATE   void sqlite3AuthRead(Parse*,Expr*,Schema*,SrcList*);
12320 SQLITE_PRIVATE   int sqlite3AuthCheck(Parse*,int, const char*, const char*, const char*);
12321 SQLITE_PRIVATE   void sqlite3AuthContextPush(Parse*, AuthContext*, const char*);
12322 SQLITE_PRIVATE   void sqlite3AuthContextPop(AuthContext*);
12323 SQLITE_PRIVATE   int sqlite3AuthReadCol(Parse*, const char *, const char *, int);
12324 #else
12325 # define sqlite3AuthRead(a,b,c,d)
12326 # define sqlite3AuthCheck(a,b,c,d,e)    SQLITE_OK
12327 # define sqlite3AuthContextPush(a,b,c)
12328 # define sqlite3AuthContextPop(a)  ((void)(a))
12329 #endif
12330 SQLITE_PRIVATE void sqlite3Attach(Parse*, Expr*, Expr*, Expr*);
12331 SQLITE_PRIVATE void sqlite3Detach(Parse*, Expr*);
12332 SQLITE_PRIVATE void sqlite3FixInit(DbFixer*, Parse*, int, const char*, const Token*);
12333 SQLITE_PRIVATE int sqlite3FixSrcList(DbFixer*, SrcList*);
12334 SQLITE_PRIVATE int sqlite3FixSelect(DbFixer*, Select*);
12335 SQLITE_PRIVATE int sqlite3FixExpr(DbFixer*, Expr*);
12336 SQLITE_PRIVATE int sqlite3FixExprList(DbFixer*, ExprList*);
12337 SQLITE_PRIVATE int sqlite3FixTriggerStep(DbFixer*, TriggerStep*);
12338 SQLITE_PRIVATE int sqlite3AtoF(const char *z, double*, int, u8);
12339 SQLITE_PRIVATE int sqlite3GetInt32(const char *, int*);
12340 SQLITE_PRIVATE int sqlite3Atoi(const char*);
12341 SQLITE_PRIVATE int sqlite3Utf16ByteLen(const void *pData, int nChar);
12342 SQLITE_PRIVATE int sqlite3Utf8CharLen(const char *pData, int nByte);
12343 SQLITE_PRIVATE u32 sqlite3Utf8Read(const u8**);
12344 SQLITE_PRIVATE LogEst sqlite3LogEst(u64);
12345 SQLITE_PRIVATE LogEst sqlite3LogEstAdd(LogEst,LogEst);
12346 #ifndef SQLITE_OMIT_VIRTUALTABLE
12347 SQLITE_PRIVATE LogEst sqlite3LogEstFromDouble(double);
12348 #endif
12349 SQLITE_PRIVATE u64 sqlite3LogEstToInt(LogEst);
12350 
12351 /*
12352 ** Routines to read and write variable-length integers.  These used to
12353 ** be defined locally, but now we use the varint routines in the util.c
12354 ** file.  Code should use the MACRO forms below, as the Varint32 versions
12355 ** are coded to assume the single byte case is already handled (which 
12356 ** the MACRO form does).
12357 */
12358 SQLITE_PRIVATE int sqlite3PutVarint(unsigned char*, u64);
12359 SQLITE_PRIVATE int sqlite3PutVarint32(unsigned char*, u32);
12360 SQLITE_PRIVATE u8 sqlite3GetVarint(const unsigned char *, u64 *);
12361 SQLITE_PRIVATE u8 sqlite3GetVarint32(const unsigned char *, u32 *);
12362 SQLITE_PRIVATE int sqlite3VarintLen(u64 v);
12363 
12364 /*
12365 ** The header of a record consists of a sequence variable-length integers.
12366 ** These integers are almost always small and are encoded as a single byte.
12367 ** The following macros take advantage this fact to provide a fast encode
12368 ** and decode of the integers in a record header.  It is faster for the common
12369 ** case where the integer is a single byte.  It is a little slower when the
12370 ** integer is two or more bytes.  But overall it is faster.
12371 **
12372 ** The following expressions are equivalent:
12373 **
12374 **     x = sqlite3GetVarint32( A, &B );
12375 **     x = sqlite3PutVarint32( A, B );
12376 **
12377 **     x = getVarint32( A, B );
12378 **     x = putVarint32( A, B );
12379 **
12380 */
12381 #define getVarint32(A,B)  \
12382   (u8)((*(A)<(u8)0x80)?((B)=(u32)*(A)),1:sqlite3GetVarint32((A),(u32 *)&(B)))
12383 #define putVarint32(A,B)  \
12384   (u8)(((u32)(B)<(u32)0x80)?(*(A)=(unsigned char)(B)),1:\
12385   sqlite3PutVarint32((A),(B)))
12386 #define getVarint    sqlite3GetVarint
12387 #define putVarint    sqlite3PutVarint
12388 
12389 
12390 SQLITE_PRIVATE const char *sqlite3IndexAffinityStr(Vdbe *, Index *);
12391 SQLITE_PRIVATE void sqlite3TableAffinityStr(Vdbe *, Table *);
12392 SQLITE_PRIVATE char sqlite3CompareAffinity(Expr *pExpr, char aff2);
12393 SQLITE_PRIVATE int sqlite3IndexAffinityOk(Expr *pExpr, char idx_affinity);
12394 SQLITE_PRIVATE char sqlite3ExprAffinity(Expr *pExpr);
12395 SQLITE_PRIVATE int sqlite3Atoi64(const char*, i64*, int, u8);
12396 SQLITE_PRIVATE void sqlite3Error(sqlite3*, int, const char*,...);
12397 SQLITE_PRIVATE void *sqlite3HexToBlob(sqlite3*, const char *z, int n);
12398 SQLITE_PRIVATE u8 sqlite3HexToInt(int h);
12399 SQLITE_PRIVATE int sqlite3TwoPartName(Parse *, Token *, Token *, Token **);
12400 
12401 #if defined(SQLITE_DEBUG) || defined(SQLITE_TEST) || \
12402     defined(SQLITE_DEBUG_OS_TRACE)
12403 SQLITE_PRIVATE const char *sqlite3ErrName(int);
12404 #endif
12405 
12406 SQLITE_PRIVATE const char *sqlite3ErrStr(int);
12407 SQLITE_PRIVATE int sqlite3ReadSchema(Parse *pParse);
12408 SQLITE_PRIVATE CollSeq *sqlite3FindCollSeq(sqlite3*,u8 enc, const char*,int);
12409 SQLITE_PRIVATE CollSeq *sqlite3LocateCollSeq(Parse *pParse, const char*zName);
12410 SQLITE_PRIVATE CollSeq *sqlite3ExprCollSeq(Parse *pParse, Expr *pExpr);
12411 SQLITE_PRIVATE Expr *sqlite3ExprAddCollateToken(Parse *pParse, Expr*, Token*);
12412 SQLITE_PRIVATE Expr *sqlite3ExprAddCollateString(Parse*,Expr*,const char*);
12413 SQLITE_PRIVATE Expr *sqlite3ExprSkipCollate(Expr*);
12414 SQLITE_PRIVATE int sqlite3CheckCollSeq(Parse *, CollSeq *);
12415 SQLITE_PRIVATE int sqlite3CheckObjectName(Parse *, const char *);
12416 SQLITE_PRIVATE void sqlite3VdbeSetChanges(sqlite3 *, int);
12417 SQLITE_PRIVATE int sqlite3AddInt64(i64*,i64);
12418 SQLITE_PRIVATE int sqlite3SubInt64(i64*,i64);
12419 SQLITE_PRIVATE int sqlite3MulInt64(i64*,i64);
12420 SQLITE_PRIVATE int sqlite3AbsInt32(int);
12421 #ifdef SQLITE_ENABLE_8_3_NAMES
12422 SQLITE_PRIVATE void sqlite3FileSuffix3(const char*, char*);
12423 #else
12424 # define sqlite3FileSuffix3(X,Y)
12425 #endif
12426 SQLITE_PRIVATE u8 sqlite3GetBoolean(const char *z,int);
12427 
12428 SQLITE_PRIVATE const void *sqlite3ValueText(sqlite3_value*, u8);
12429 SQLITE_PRIVATE int sqlite3ValueBytes(sqlite3_value*, u8);
12430 SQLITE_PRIVATE void sqlite3ValueSetStr(sqlite3_value*, int, const void *,u8, 
12431                         void(*)(void*));
12432 SQLITE_PRIVATE void sqlite3ValueFree(sqlite3_value*);
12433 SQLITE_PRIVATE sqlite3_value *sqlite3ValueNew(sqlite3 *);
12434 SQLITE_PRIVATE char *sqlite3Utf16to8(sqlite3 *, const void*, int, u8);
12435 SQLITE_PRIVATE int sqlite3ValueFromExpr(sqlite3 *, Expr *, u8, u8, sqlite3_value **);
12436 SQLITE_PRIVATE void sqlite3ValueApplyAffinity(sqlite3_value *, u8, u8);
12437 #ifndef SQLITE_AMALGAMATION
12438 SQLITE_PRIVATE const unsigned char sqlite3OpcodeProperty[];
12439 SQLITE_PRIVATE const unsigned char sqlite3UpperToLower[];
12440 SQLITE_PRIVATE const unsigned char sqlite3CtypeMap[];
12441 SQLITE_PRIVATE const Token sqlite3IntTokens[];
12442 SQLITE_PRIVATE SQLITE_WSD struct Sqlite3Config sqlite3Config;
12443 SQLITE_PRIVATE SQLITE_WSD FuncDefHash sqlite3GlobalFunctions;
12444 #ifndef SQLITE_OMIT_WSD
12445 SQLITE_PRIVATE int sqlite3PendingByte;
12446 #endif
12447 #endif
12448 SQLITE_PRIVATE void sqlite3RootPageMoved(sqlite3*, int, int, int);
12449 SQLITE_PRIVATE void sqlite3Reindex(Parse*, Token*, Token*);
12450 SQLITE_PRIVATE void sqlite3AlterFunctions(void);
12451 SQLITE_PRIVATE void sqlite3AlterRenameTable(Parse*, SrcList*, Token*);
12452 SQLITE_PRIVATE int sqlite3GetToken(const unsigned char *, int *);
12453 SQLITE_PRIVATE void sqlite3NestedParse(Parse*, const char*, ...);
12454 SQLITE_PRIVATE void sqlite3ExpirePreparedStatements(sqlite3*);
12455 SQLITE_PRIVATE int sqlite3CodeSubselect(Parse *, Expr *, int, int);
12456 SQLITE_PRIVATE void sqlite3SelectPrep(Parse*, Select*, NameContext*);
12457 SQLITE_PRIVATE int sqlite3MatchSpanName(const char*, const char*, const char*, const char*);
12458 SQLITE_PRIVATE int sqlite3ResolveExprNames(NameContext*, Expr*);
12459 SQLITE_PRIVATE void sqlite3ResolveSelectNames(Parse*, Select*, NameContext*);
12460 SQLITE_PRIVATE void sqlite3ResolveSelfReference(Parse*,Table*,int,Expr*,ExprList*);
12461 SQLITE_PRIVATE int sqlite3ResolveOrderGroupBy(Parse*, Select*, ExprList*, const char*);
12462 SQLITE_PRIVATE void sqlite3ColumnDefault(Vdbe *, Table *, int, int);
12463 SQLITE_PRIVATE void sqlite3AlterFinishAddColumn(Parse *, Token *);
12464 SQLITE_PRIVATE void sqlite3AlterBeginAddColumn(Parse *, SrcList *);
12465 SQLITE_PRIVATE CollSeq *sqlite3GetCollSeq(Parse*, u8, CollSeq *, const char*);
12466 SQLITE_PRIVATE char sqlite3AffinityType(const char*, u8*);
12467 SQLITE_PRIVATE void sqlite3Analyze(Parse*, Token*, Token*);
12468 SQLITE_PRIVATE int sqlite3InvokeBusyHandler(BusyHandler*);
12469 SQLITE_PRIVATE int sqlite3FindDb(sqlite3*, Token*);
12470 SQLITE_PRIVATE int sqlite3FindDbName(sqlite3 *, const char *);
12471 SQLITE_PRIVATE int sqlite3AnalysisLoad(sqlite3*,int iDB);
12472 SQLITE_PRIVATE void sqlite3DeleteIndexSamples(sqlite3*,Index*);
12473 SQLITE_PRIVATE void sqlite3DefaultRowEst(Index*);
12474 SQLITE_PRIVATE void sqlite3RegisterLikeFunctions(sqlite3*, int);
12475 SQLITE_PRIVATE int sqlite3IsLikeFunction(sqlite3*,Expr*,int*,char*);
12476 SQLITE_PRIVATE void sqlite3MinimumFileFormat(Parse*, int, int);
12477 SQLITE_PRIVATE void sqlite3SchemaClear(void *);
12478 SQLITE_PRIVATE Schema *sqlite3SchemaGet(sqlite3 *, Btree *);
12479 SQLITE_PRIVATE int sqlite3SchemaToIndex(sqlite3 *db, Schema *);
12480 SQLITE_PRIVATE KeyInfo *sqlite3KeyInfoAlloc(sqlite3*,int,int);
12481 SQLITE_PRIVATE void sqlite3KeyInfoUnref(KeyInfo*);
12482 SQLITE_PRIVATE KeyInfo *sqlite3KeyInfoRef(KeyInfo*);
12483 SQLITE_PRIVATE KeyInfo *sqlite3KeyInfoOfIndex(Parse*, Index*);
12484 #ifdef SQLITE_DEBUG
12485 SQLITE_PRIVATE int sqlite3KeyInfoIsWriteable(KeyInfo*);
12486 #endif
12487 SQLITE_PRIVATE int sqlite3CreateFunc(sqlite3 *, const char *, int, int, void *, 
12488   void (*)(sqlite3_context*,int,sqlite3_value **),
12489   void (*)(sqlite3_context*,int,sqlite3_value **), void (*)(sqlite3_context*),
12490   FuncDestructor *pDestructor
12491 );
12492 SQLITE_PRIVATE int sqlite3ApiExit(sqlite3 *db, int);
12493 SQLITE_PRIVATE int sqlite3OpenTempDatabase(Parse *);
12494 
12495 SQLITE_PRIVATE void sqlite3StrAccumInit(StrAccum*, char*, int, int);
12496 SQLITE_PRIVATE void sqlite3StrAccumAppend(StrAccum*,const char*,int);
12497 SQLITE_PRIVATE void sqlite3AppendSpace(StrAccum*,int);
12498 SQLITE_PRIVATE char *sqlite3StrAccumFinish(StrAccum*);
12499 SQLITE_PRIVATE void sqlite3StrAccumReset(StrAccum*);
12500 SQLITE_PRIVATE void sqlite3SelectDestInit(SelectDest*,int,int);
12501 SQLITE_PRIVATE Expr *sqlite3CreateColumnExpr(sqlite3 *, SrcList *, int, int);
12502 
12503 SQLITE_PRIVATE void sqlite3BackupRestart(sqlite3_backup *);
12504 SQLITE_PRIVATE void sqlite3BackupUpdate(sqlite3_backup *, Pgno, const u8 *);
12505 
12506 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
12507 SQLITE_PRIVATE void sqlite3AnalyzeFunctions(void);
12508 SQLITE_PRIVATE int sqlite3Stat4ProbeSetValue(Parse*,Index*,UnpackedRecord**,Expr*,u8,int,int*);
12509 SQLITE_PRIVATE void sqlite3Stat4ProbeFree(UnpackedRecord*);
12510 #endif
12511 
12512 /*
12513 ** The interface to the LEMON-generated parser
12514 */
12515 SQLITE_PRIVATE void *sqlite3ParserAlloc(void*(*)(size_t));
12516 SQLITE_PRIVATE void sqlite3ParserFree(void*, void(*)(void*));
12517 SQLITE_PRIVATE void sqlite3Parser(void*, int, Token, Parse*);
12518 #ifdef YYTRACKMAXSTACKDEPTH
12519 SQLITE_PRIVATE   int sqlite3ParserStackPeak(void*);
12520 #endif
12521 
12522 SQLITE_PRIVATE void sqlite3AutoLoadExtensions(sqlite3*);
12523 #ifndef SQLITE_OMIT_LOAD_EXTENSION
12524 SQLITE_PRIVATE   void sqlite3CloseExtensions(sqlite3*);
12525 #else
12526 # define sqlite3CloseExtensions(X)
12527 #endif
12528 
12529 #ifndef SQLITE_OMIT_SHARED_CACHE
12530 SQLITE_PRIVATE   void sqlite3TableLock(Parse *, int, int, u8, const char *);
12531 #else
12532   #define sqlite3TableLock(v,w,x,y,z)
12533 #endif
12534 
12535 #ifdef SQLITE_TEST
12536 SQLITE_PRIVATE   int sqlite3Utf8To8(unsigned char*);
12537 #endif
12538 
12539 #ifdef SQLITE_OMIT_VIRTUALTABLE
12540 #  define sqlite3VtabClear(Y)
12541 #  define sqlite3VtabSync(X,Y) SQLITE_OK
12542 #  define sqlite3VtabRollback(X)
12543 #  define sqlite3VtabCommit(X)
12544 #  define sqlite3VtabInSync(db) 0
12545 #  define sqlite3VtabLock(X) 
12546 #  define sqlite3VtabUnlock(X)
12547 #  define sqlite3VtabUnlockList(X)
12548 #  define sqlite3VtabSavepoint(X, Y, Z) SQLITE_OK
12549 #  define sqlite3GetVTable(X,Y)  ((VTable*)0)
12550 #else
12551 SQLITE_PRIVATE    void sqlite3VtabClear(sqlite3 *db, Table*);
12552 SQLITE_PRIVATE    void sqlite3VtabDisconnect(sqlite3 *db, Table *p);
12553 SQLITE_PRIVATE    int sqlite3VtabSync(sqlite3 *db, Vdbe*);
12554 SQLITE_PRIVATE    int sqlite3VtabRollback(sqlite3 *db);
12555 SQLITE_PRIVATE    int sqlite3VtabCommit(sqlite3 *db);
12556 SQLITE_PRIVATE    void sqlite3VtabLock(VTable *);
12557 SQLITE_PRIVATE    void sqlite3VtabUnlock(VTable *);
12558 SQLITE_PRIVATE    void sqlite3VtabUnlockList(sqlite3*);
12559 SQLITE_PRIVATE    int sqlite3VtabSavepoint(sqlite3 *, int, int);
12560 SQLITE_PRIVATE    void sqlite3VtabImportErrmsg(Vdbe*, sqlite3_vtab*);
12561 SQLITE_PRIVATE    VTable *sqlite3GetVTable(sqlite3*, Table*);
12562 #  define sqlite3VtabInSync(db) ((db)->nVTrans>0 && (db)->aVTrans==0)
12563 #endif
12564 SQLITE_PRIVATE void sqlite3VtabMakeWritable(Parse*,Table*);
12565 SQLITE_PRIVATE void sqlite3VtabBeginParse(Parse*, Token*, Token*, Token*, int);
12566 SQLITE_PRIVATE void sqlite3VtabFinishParse(Parse*, Token*);
12567 SQLITE_PRIVATE void sqlite3VtabArgInit(Parse*);
12568 SQLITE_PRIVATE void sqlite3VtabArgExtend(Parse*, Token*);
12569 SQLITE_PRIVATE int sqlite3VtabCallCreate(sqlite3*, int, const char *, char **);
12570 SQLITE_PRIVATE int sqlite3VtabCallConnect(Parse*, Table*);
12571 SQLITE_PRIVATE int sqlite3VtabCallDestroy(sqlite3*, int, const char *);
12572 SQLITE_PRIVATE int sqlite3VtabBegin(sqlite3 *, VTable *);
12573 SQLITE_PRIVATE FuncDef *sqlite3VtabOverloadFunction(sqlite3 *,FuncDef*, int nArg, Expr*);
12574 SQLITE_PRIVATE void sqlite3InvalidFunction(sqlite3_context*,int,sqlite3_value**);
12575 SQLITE_PRIVATE sqlite3_int64 sqlite3StmtCurrentTime(sqlite3_context*);
12576 SQLITE_PRIVATE int sqlite3VdbeParameterIndex(Vdbe*, const char*, int);
12577 SQLITE_PRIVATE int sqlite3TransferBindings(sqlite3_stmt *, sqlite3_stmt *);
12578 SQLITE_PRIVATE void sqlite3ParserReset(Parse*);
12579 SQLITE_PRIVATE int sqlite3Reprepare(Vdbe*);
12580 SQLITE_PRIVATE void sqlite3ExprListCheckLength(Parse*, ExprList*, const char*);
12581 SQLITE_PRIVATE CollSeq *sqlite3BinaryCompareCollSeq(Parse *, Expr *, Expr *);
12582 SQLITE_PRIVATE int sqlite3TempInMemory(const sqlite3*);
12583 SQLITE_PRIVATE const char *sqlite3JournalModename(int);
12584 #ifndef SQLITE_OMIT_WAL
12585 SQLITE_PRIVATE   int sqlite3Checkpoint(sqlite3*, int, int, int*, int*);
12586 SQLITE_PRIVATE   int sqlite3WalDefaultHook(void*,sqlite3*,const char*,int);
12587 #endif
12588 
12589 /* Declarations for functions in fkey.c. All of these are replaced by
12590 ** no-op macros if OMIT_FOREIGN_KEY is defined. In this case no foreign
12591 ** key functionality is available. If OMIT_TRIGGER is defined but
12592 ** OMIT_FOREIGN_KEY is not, only some of the functions are no-oped. In
12593 ** this case foreign keys are parsed, but no other functionality is 
12594 ** provided (enforcement of FK constraints requires the triggers sub-system).
12595 */
12596 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
12597 SQLITE_PRIVATE   void sqlite3FkCheck(Parse*, Table*, int, int, int*, int);
12598 SQLITE_PRIVATE   void sqlite3FkDropTable(Parse*, SrcList *, Table*);
12599 SQLITE_PRIVATE   void sqlite3FkActions(Parse*, Table*, ExprList*, int, int*, int);
12600 SQLITE_PRIVATE   int sqlite3FkRequired(Parse*, Table*, int*, int);
12601 SQLITE_PRIVATE   u32 sqlite3FkOldmask(Parse*, Table*);
12602 SQLITE_PRIVATE   FKey *sqlite3FkReferences(Table *);
12603 #else
12604   #define sqlite3FkActions(a,b,c,d,e,f)
12605   #define sqlite3FkCheck(a,b,c,d,e,f)
12606   #define sqlite3FkDropTable(a,b,c)
12607   #define sqlite3FkOldmask(a,b)         0
12608   #define sqlite3FkRequired(a,b,c,d)    0
12609 #endif
12610 #ifndef SQLITE_OMIT_FOREIGN_KEY
12611 SQLITE_PRIVATE   void sqlite3FkDelete(sqlite3 *, Table*);
12612 SQLITE_PRIVATE   int sqlite3FkLocateIndex(Parse*,Table*,FKey*,Index**,int**);
12613 #else
12614   #define sqlite3FkDelete(a,b)
12615   #define sqlite3FkLocateIndex(a,b,c,d,e)
12616 #endif
12617 
12618 
12619 /*
12620 ** Available fault injectors.  Should be numbered beginning with 0.
12621 */
12622 #define SQLITE_FAULTINJECTOR_MALLOC     0
12623 #define SQLITE_FAULTINJECTOR_COUNT      1
12624 
12625 /*
12626 ** The interface to the code in fault.c used for identifying "benign"
12627 ** malloc failures. This is only present if SQLITE_OMIT_BUILTIN_TEST
12628 ** is not defined.
12629 */
12630 #ifndef SQLITE_OMIT_BUILTIN_TEST
12631 SQLITE_PRIVATE   void sqlite3BeginBenignMalloc(void);
12632 SQLITE_PRIVATE   void sqlite3EndBenignMalloc(void);
12633 #else
12634   #define sqlite3BeginBenignMalloc()
12635   #define sqlite3EndBenignMalloc()
12636 #endif
12637 
12638 #define IN_INDEX_ROWID           1
12639 #define IN_INDEX_EPH             2
12640 #define IN_INDEX_INDEX_ASC       3
12641 #define IN_INDEX_INDEX_DESC      4
12642 SQLITE_PRIVATE int sqlite3FindInIndex(Parse *, Expr *, int*);
12643 
12644 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
12645 SQLITE_PRIVATE   int sqlite3JournalOpen(sqlite3_vfs *, const char *, sqlite3_file *, int, int);
12646 SQLITE_PRIVATE   int sqlite3JournalSize(sqlite3_vfs *);
12647 SQLITE_PRIVATE   int sqlite3JournalCreate(sqlite3_file *);
12648 SQLITE_PRIVATE   int sqlite3JournalExists(sqlite3_file *p);
12649 #else
12650   #define sqlite3JournalSize(pVfs) ((pVfs)->szOsFile)
12651   #define sqlite3JournalExists(p) 1
12652 #endif
12653 
12654 SQLITE_PRIVATE void sqlite3MemJournalOpen(sqlite3_file *);
12655 SQLITE_PRIVATE int sqlite3MemJournalSize(void);
12656 SQLITE_PRIVATE int sqlite3IsMemJournal(sqlite3_file *);
12657 
12658 #if SQLITE_MAX_EXPR_DEPTH>0
12659 SQLITE_PRIVATE   void sqlite3ExprSetHeight(Parse *pParse, Expr *p);
12660 SQLITE_PRIVATE   int sqlite3SelectExprHeight(Select *);
12661 SQLITE_PRIVATE   int sqlite3ExprCheckHeight(Parse*, int);
12662 #else
12663   #define sqlite3ExprSetHeight(x,y)
12664   #define sqlite3SelectExprHeight(x) 0
12665   #define sqlite3ExprCheckHeight(x,y)
12666 #endif
12667 
12668 SQLITE_PRIVATE u32 sqlite3Get4byte(const u8*);
12669 SQLITE_PRIVATE void sqlite3Put4byte(u8*, u32);
12670 
12671 #ifdef SQLITE_ENABLE_UNLOCK_NOTIFY
12672 SQLITE_PRIVATE   void sqlite3ConnectionBlocked(sqlite3 *, sqlite3 *);
12673 SQLITE_PRIVATE   void sqlite3ConnectionUnlocked(sqlite3 *db);
12674 SQLITE_PRIVATE   void sqlite3ConnectionClosed(sqlite3 *db);
12675 #else
12676   #define sqlite3ConnectionBlocked(x,y)
12677   #define sqlite3ConnectionUnlocked(x)
12678   #define sqlite3ConnectionClosed(x)
12679 #endif
12680 
12681 #ifdef SQLITE_DEBUG
12682 SQLITE_PRIVATE   void sqlite3ParserTrace(FILE*, char *);
12683 #endif
12684 
12685 /*
12686 ** If the SQLITE_ENABLE IOTRACE exists then the global variable
12687 ** sqlite3IoTrace is a pointer to a printf-like routine used to
12688 ** print I/O tracing messages. 
12689 */
12690 #ifdef SQLITE_ENABLE_IOTRACE
12691 # define IOTRACE(A)  if( sqlite3IoTrace ){ sqlite3IoTrace A; }
12692 SQLITE_PRIVATE   void sqlite3VdbeIOTraceSql(Vdbe*);
12693 SQLITE_PRIVATE void (*sqlite3IoTrace)(const char*,...);
12694 #else
12695 # define IOTRACE(A)
12696 # define sqlite3VdbeIOTraceSql(X)
12697 #endif
12698 
12699 /*
12700 ** These routines are available for the mem2.c debugging memory allocator
12701 ** only.  They are used to verify that different "types" of memory
12702 ** allocations are properly tracked by the system.
12703 **
12704 ** sqlite3MemdebugSetType() sets the "type" of an allocation to one of
12705 ** the MEMTYPE_* macros defined below.  The type must be a bitmask with
12706 ** a single bit set.
12707 **
12708 ** sqlite3MemdebugHasType() returns true if any of the bits in its second
12709 ** argument match the type set by the previous sqlite3MemdebugSetType().
12710 ** sqlite3MemdebugHasType() is intended for use inside assert() statements.
12711 **
12712 ** sqlite3MemdebugNoType() returns true if none of the bits in its second
12713 ** argument match the type set by the previous sqlite3MemdebugSetType().
12714 **
12715 ** Perhaps the most important point is the difference between MEMTYPE_HEAP
12716 ** and MEMTYPE_LOOKASIDE.  If an allocation is MEMTYPE_LOOKASIDE, that means
12717 ** it might have been allocated by lookaside, except the allocation was
12718 ** too large or lookaside was already full.  It is important to verify
12719 ** that allocations that might have been satisfied by lookaside are not
12720 ** passed back to non-lookaside free() routines.  Asserts such as the
12721 ** example above are placed on the non-lookaside free() routines to verify
12722 ** this constraint. 
12723 **
12724 ** All of this is no-op for a production build.  It only comes into
12725 ** play when the SQLITE_MEMDEBUG compile-time option is used.
12726 */
12727 #ifdef SQLITE_MEMDEBUG
12728 SQLITE_PRIVATE   void sqlite3MemdebugSetType(void*,u8);
12729 SQLITE_PRIVATE   int sqlite3MemdebugHasType(void*,u8);
12730 SQLITE_PRIVATE   int sqlite3MemdebugNoType(void*,u8);
12731 #else
12732 # define sqlite3MemdebugSetType(X,Y)  /* no-op */
12733 # define sqlite3MemdebugHasType(X,Y)  1
12734 # define sqlite3MemdebugNoType(X,Y)   1
12735 #endif
12736 #define MEMTYPE_HEAP       0x01  /* General heap allocations */
12737 #define MEMTYPE_LOOKASIDE  0x02  /* Might have been lookaside memory */
12738 #define MEMTYPE_SCRATCH    0x04  /* Scratch allocations */
12739 #define MEMTYPE_PCACHE     0x08  /* Page cache allocations */
12740 #define MEMTYPE_DB         0x10  /* Uses sqlite3DbMalloc, not sqlite_malloc */
12741 
12742 #endif /* _SQLITEINT_H_ */
12743 
12744 /************** End of sqliteInt.h *******************************************/
12745 /************** Begin file global.c ******************************************/
12746 /*
12747 ** 2008 June 13
12748 **
12749 ** The author disclaims copyright to this source code.  In place of
12750 ** a legal notice, here is a blessing:
12751 **
12752 **    May you do good and not evil.
12753 **    May you find forgiveness for yourself and forgive others.
12754 **    May you share freely, never taking more than you give.
12755 **
12756 *************************************************************************
12757 **
12758 ** This file contains definitions of global variables and contants.
12759 */
12760 
12761 /* An array to map all upper-case characters into their corresponding
12762 ** lower-case character. 
12763 **
12764 ** SQLite only considers US-ASCII (or EBCDIC) characters.  We do not
12765 ** handle case conversions for the UTF character set since the tables
12766 ** involved are nearly as big or bigger than SQLite itself.
12767 */
12768 SQLITE_PRIVATE const unsigned char sqlite3UpperToLower[] = {
12769 #ifdef SQLITE_ASCII
12770       0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15, 16, 17,
12771      18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35,
12772      36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53,
12773      54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 97, 98, 99,100,101,102,103,
12774     104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,
12775     122, 91, 92, 93, 94, 95, 96, 97, 98, 99,100,101,102,103,104,105,106,107,
12776     108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,
12777     126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,
12778     144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,
12779     162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,
12780     180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,
12781     198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,
12782     216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,
12783     234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,
12784     252,253,254,255
12785 #endif
12786 #ifdef SQLITE_EBCDIC
12787       0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15, /* 0x */
12788      16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, /* 1x */
12789      32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, /* 2x */
12790      48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, /* 3x */
12791      64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, /* 4x */
12792      80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, /* 5x */
12793      96, 97, 66, 67, 68, 69, 70, 71, 72, 73,106,107,108,109,110,111, /* 6x */
12794     112, 81, 82, 83, 84, 85, 86, 87, 88, 89,122,123,124,125,126,127, /* 7x */
12795     128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143, /* 8x */
12796     144,145,146,147,148,149,150,151,152,153,154,155,156,157,156,159, /* 9x */
12797     160,161,162,163,164,165,166,167,168,169,170,171,140,141,142,175, /* Ax */
12798     176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191, /* Bx */
12799     192,129,130,131,132,133,134,135,136,137,202,203,204,205,206,207, /* Cx */
12800     208,145,146,147,148,149,150,151,152,153,218,219,220,221,222,223, /* Dx */
12801     224,225,162,163,164,165,166,167,168,169,232,203,204,205,206,207, /* Ex */
12802     239,240,241,242,243,244,245,246,247,248,249,219,220,221,222,255, /* Fx */
12803 #endif
12804 };
12805 
12806 /*
12807 ** The following 256 byte lookup table is used to support SQLites built-in
12808 ** equivalents to the following standard library functions:
12809 **
12810 **   isspace()                        0x01
12811 **   isalpha()                        0x02
12812 **   isdigit()                        0x04
12813 **   isalnum()                        0x06
12814 **   isxdigit()                       0x08
12815 **   toupper()                        0x20
12816 **   SQLite identifier character      0x40
12817 **
12818 ** Bit 0x20 is set if the mapped character requires translation to upper
12819 ** case. i.e. if the character is a lower-case ASCII character.
12820 ** If x is a lower-case ASCII character, then its upper-case equivalent
12821 ** is (x - 0x20). Therefore toupper() can be implemented as:
12822 **
12823 **   (x & ~(map[x]&0x20))
12824 **
12825 ** Standard function tolower() is implemented using the sqlite3UpperToLower[]
12826 ** array. tolower() is used more often than toupper() by SQLite.
12827 **
12828 ** Bit 0x40 is set if the character non-alphanumeric and can be used in an 
12829 ** SQLite identifier.  Identifiers are alphanumerics, "_", "$", and any
12830 ** non-ASCII UTF character. Hence the test for whether or not a character is
12831 ** part of an identifier is 0x46.
12832 **
12833 ** SQLite's versions are identical to the standard versions assuming a
12834 ** locale of "C". They are implemented as macros in sqliteInt.h.
12835 */
12836 #ifdef SQLITE_ASCII
12837 SQLITE_PRIVATE const unsigned char sqlite3CtypeMap[256] = {
12838   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,  /* 00..07    ........ */
12839   0x00, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00,  /* 08..0f    ........ */
12840   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,  /* 10..17    ........ */
12841   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,  /* 18..1f    ........ */
12842   0x01, 0x00, 0x00, 0x00, 0x40, 0x00, 0x00, 0x00,  /* 20..27     !"#$%&' */
12843   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,  /* 28..2f    ()*+,-./ */
12844   0x0c, 0x0c, 0x0c, 0x0c, 0x0c, 0x0c, 0x0c, 0x0c,  /* 30..37    01234567 */
12845   0x0c, 0x0c, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,  /* 38..3f    89:;<=>? */
12846 
12847   0x00, 0x0a, 0x0a, 0x0a, 0x0a, 0x0a, 0x0a, 0x02,  /* 40..47    @ABCDEFG */
12848   0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x02,  /* 48..4f    HIJKLMNO */
12849   0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x02,  /* 50..57    PQRSTUVW */
12850   0x02, 0x02, 0x02, 0x00, 0x00, 0x00, 0x00, 0x40,  /* 58..5f    XYZ[\]^_ */
12851   0x00, 0x2a, 0x2a, 0x2a, 0x2a, 0x2a, 0x2a, 0x22,  /* 60..67    `abcdefg */
12852   0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22,  /* 68..6f    hijklmno */
12853   0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22,  /* 70..77    pqrstuvw */
12854   0x22, 0x22, 0x22, 0x00, 0x00, 0x00, 0x00, 0x00,  /* 78..7f    xyz{|}~. */
12855 
12856   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* 80..87    ........ */
12857   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* 88..8f    ........ */
12858   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* 90..97    ........ */
12859   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* 98..9f    ........ */
12860   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* a0..a7    ........ */
12861   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* a8..af    ........ */
12862   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* b0..b7    ........ */
12863   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* b8..bf    ........ */
12864 
12865   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* c0..c7    ........ */
12866   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* c8..cf    ........ */
12867   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* d0..d7    ........ */
12868   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* d8..df    ........ */
12869   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* e0..e7    ........ */
12870   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* e8..ef    ........ */
12871   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40,  /* f0..f7    ........ */
12872   0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40, 0x40   /* f8..ff    ........ */
12873 };
12874 #endif
12875 
12876 #ifndef SQLITE_USE_URI
12877 # define  SQLITE_USE_URI 0
12878 #endif
12879 
12880 #ifndef SQLITE_ALLOW_COVERING_INDEX_SCAN
12881 # define SQLITE_ALLOW_COVERING_INDEX_SCAN 1
12882 #endif
12883 
12884 /*
12885 ** The following singleton contains the global configuration for
12886 ** the SQLite library.
12887 */
12888 SQLITE_PRIVATE SQLITE_WSD struct Sqlite3Config sqlite3Config = {
12889    SQLITE_DEFAULT_MEMSTATUS,  /* bMemstat */
12890    1,                         /* bCoreMutex */
12891    SQLITE_THREADSAFE==1,      /* bFullMutex */
12892    SQLITE_USE_URI,            /* bOpenUri */
12893    SQLITE_ALLOW_COVERING_INDEX_SCAN,   /* bUseCis */
12894    0x7ffffffe,                /* mxStrlen */
12895    0,                         /* neverCorrupt */
12896    128,                       /* szLookaside */
12897    500,                       /* nLookaside */
12898    {0,0,0,0,0,0,0,0},         /* m */
12899    {0,0,0,0,0,0,0,0,0},       /* mutex */
12900    {0,0,0,0,0,0,0,0,0,0,0,0,0},/* pcache2 */
12901    (void*)0,                  /* pHeap */
12902    0,                         /* nHeap */
12903    0, 0,                      /* mnHeap, mxHeap */
12904    SQLITE_DEFAULT_MMAP_SIZE,  /* szMmap */
12905    SQLITE_MAX_MMAP_SIZE,      /* mxMmap */
12906    (void*)0,                  /* pScratch */
12907    0,                         /* szScratch */
12908    0,                         /* nScratch */
12909    (void*)0,                  /* pPage */
12910    0,                         /* szPage */
12911    0,                         /* nPage */
12912    0,                         /* mxParserStack */
12913    0,                         /* sharedCacheEnabled */
12914    /* All the rest should always be initialized to zero */
12915    0,                         /* isInit */
12916    0,                         /* inProgress */
12917    0,                         /* isMutexInit */
12918    0,                         /* isMallocInit */
12919    0,                         /* isPCacheInit */
12920    0,                         /* pInitMutex */
12921    0,                         /* nRefInitMutex */
12922    0,                         /* xLog */
12923    0,                         /* pLogArg */
12924    0,                         /* bLocaltimeFault */
12925 #ifdef SQLITE_ENABLE_SQLLOG
12926    0,                         /* xSqllog */
12927    0                          /* pSqllogArg */
12928 #endif
12929 };
12930 
12931 /*
12932 ** Hash table for global functions - functions common to all
12933 ** database connections.  After initialization, this table is
12934 ** read-only.
12935 */
12936 SQLITE_PRIVATE SQLITE_WSD FuncDefHash sqlite3GlobalFunctions;
12937 
12938 /*
12939 ** Constant tokens for values 0 and 1.
12940 */
12941 SQLITE_PRIVATE const Token sqlite3IntTokens[] = {
12942    { "0", 1 },
12943    { "1", 1 }
12944 };
12945 
12946 
12947 /*
12948 ** The value of the "pending" byte must be 0x40000000 (1 byte past the
12949 ** 1-gibabyte boundary) in a compatible database.  SQLite never uses
12950 ** the database page that contains the pending byte.  It never attempts
12951 ** to read or write that page.  The pending byte page is set assign
12952 ** for use by the VFS layers as space for managing file locks.
12953 **
12954 ** During testing, it is often desirable to move the pending byte to
12955 ** a different position in the file.  This allows code that has to
12956 ** deal with the pending byte to run on files that are much smaller
12957 ** than 1 GiB.  The sqlite3_test_control() interface can be used to
12958 ** move the pending byte.
12959 **
12960 ** IMPORTANT:  Changing the pending byte to any value other than
12961 ** 0x40000000 results in an incompatible database file format!
12962 ** Changing the pending byte during operating results in undefined
12963 ** and dileterious behavior.
12964 */
12965 #ifndef SQLITE_OMIT_WSD
12966 SQLITE_PRIVATE int sqlite3PendingByte = 0x40000000;
12967 #endif
12968 
12969 /*
12970 ** Properties of opcodes.  The OPFLG_INITIALIZER macro is
12971 ** created by mkopcodeh.awk during compilation.  Data is obtained
12972 ** from the comments following the "case OP_xxxx:" statements in
12973 ** the vdbe.c file.  
12974 */
12975 SQLITE_PRIVATE const unsigned char sqlite3OpcodeProperty[] = OPFLG_INITIALIZER;
12976 
12977 /************** End of global.c **********************************************/
12978 /************** Begin file ctime.c *******************************************/
12979 /*
12980 ** 2010 February 23
12981 **
12982 ** The author disclaims copyright to this source code.  In place of
12983 ** a legal notice, here is a blessing:
12984 **
12985 **    May you do good and not evil.
12986 **    May you find forgiveness for yourself and forgive others.
12987 **    May you share freely, never taking more than you give.
12988 **
12989 *************************************************************************
12990 **
12991 ** This file implements routines used to report what compile-time options
12992 ** SQLite was built with.
12993 */
12994 
12995 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
12996 
12997 
12998 /*
12999 ** An array of names of all compile-time options.  This array should 
13000 ** be sorted A-Z.
13001 **
13002 ** This array looks large, but in a typical installation actually uses
13003 ** only a handful of compile-time options, so most times this array is usually
13004 ** rather short and uses little memory space.
13005 */
13006 static const char * const azCompileOpt[] = {
13007 
13008 /* These macros are provided to "stringify" the value of the define
13009 ** for those options in which the value is meaningful. */
13010 #define CTIMEOPT_VAL_(opt) #opt
13011 #define CTIMEOPT_VAL(opt) CTIMEOPT_VAL_(opt)
13012 
13013 #ifdef SQLITE_32BIT_ROWID
13014   "32BIT_ROWID",
13015 #endif
13016 #ifdef SQLITE_4_BYTE_ALIGNED_MALLOC
13017   "4_BYTE_ALIGNED_MALLOC",
13018 #endif
13019 #ifdef SQLITE_CASE_SENSITIVE_LIKE
13020   "CASE_SENSITIVE_LIKE",
13021 #endif
13022 #ifdef SQLITE_CHECK_PAGES
13023   "CHECK_PAGES",
13024 #endif
13025 #ifdef SQLITE_COVERAGE_TEST
13026   "COVERAGE_TEST",
13027 #endif
13028 #ifdef SQLITE_DEBUG
13029   "DEBUG",
13030 #endif
13031 #ifdef SQLITE_DEFAULT_LOCKING_MODE
13032   "DEFAULT_LOCKING_MODE=" CTIMEOPT_VAL(SQLITE_DEFAULT_LOCKING_MODE),
13033 #endif
13034 #if defined(SQLITE_DEFAULT_MMAP_SIZE) && !defined(SQLITE_DEFAULT_MMAP_SIZE_xc)
13035   "DEFAULT_MMAP_SIZE=" CTIMEOPT_VAL(SQLITE_DEFAULT_MMAP_SIZE),
13036 #endif
13037 #ifdef SQLITE_DISABLE_DIRSYNC
13038   "DISABLE_DIRSYNC",
13039 #endif
13040 #ifdef SQLITE_DISABLE_LFS
13041   "DISABLE_LFS",
13042 #endif
13043 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
13044   "ENABLE_ATOMIC_WRITE",
13045 #endif
13046 #ifdef SQLITE_ENABLE_CEROD
13047   "ENABLE_CEROD",
13048 #endif
13049 #ifdef SQLITE_ENABLE_COLUMN_METADATA
13050   "ENABLE_COLUMN_METADATA",
13051 #endif
13052 #ifdef SQLITE_ENABLE_EXPENSIVE_ASSERT
13053   "ENABLE_EXPENSIVE_ASSERT",
13054 #endif
13055 #ifdef SQLITE_ENABLE_FTS1
13056   "ENABLE_FTS1",
13057 #endif
13058 #ifdef SQLITE_ENABLE_FTS2
13059   "ENABLE_FTS2",
13060 #endif
13061 #ifdef SQLITE_ENABLE_FTS3
13062   "ENABLE_FTS3",
13063 #endif
13064 #ifdef SQLITE_ENABLE_FTS3_PARENTHESIS
13065   "ENABLE_FTS3_PARENTHESIS",
13066 #endif
13067 #ifdef SQLITE_ENABLE_FTS4
13068   "ENABLE_FTS4",
13069 #endif
13070 #ifdef SQLITE_ENABLE_ICU
13071   "ENABLE_ICU",
13072 #endif
13073 #ifdef SQLITE_ENABLE_IOTRACE
13074   "ENABLE_IOTRACE",
13075 #endif
13076 #ifdef SQLITE_ENABLE_LOAD_EXTENSION
13077   "ENABLE_LOAD_EXTENSION",
13078 #endif
13079 #ifdef SQLITE_ENABLE_LOCKING_STYLE
13080   "ENABLE_LOCKING_STYLE=" CTIMEOPT_VAL(SQLITE_ENABLE_LOCKING_STYLE),
13081 #endif
13082 #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
13083   "ENABLE_MEMORY_MANAGEMENT",
13084 #endif
13085 #ifdef SQLITE_ENABLE_MEMSYS3
13086   "ENABLE_MEMSYS3",
13087 #endif
13088 #ifdef SQLITE_ENABLE_MEMSYS5
13089   "ENABLE_MEMSYS5",
13090 #endif
13091 #ifdef SQLITE_ENABLE_OVERSIZE_CELL_CHECK
13092   "ENABLE_OVERSIZE_CELL_CHECK",
13093 #endif
13094 #ifdef SQLITE_ENABLE_RTREE
13095   "ENABLE_RTREE",
13096 #endif
13097 #if defined(SQLITE_ENABLE_STAT4)
13098   "ENABLE_STAT4",
13099 #elif defined(SQLITE_ENABLE_STAT3)
13100   "ENABLE_STAT3",
13101 #endif
13102 #ifdef SQLITE_ENABLE_UNLOCK_NOTIFY
13103   "ENABLE_UNLOCK_NOTIFY",
13104 #endif
13105 #ifdef SQLITE_ENABLE_UPDATE_DELETE_LIMIT
13106   "ENABLE_UPDATE_DELETE_LIMIT",
13107 #endif
13108 #ifdef SQLITE_HAS_CODEC
13109   "HAS_CODEC",
13110 #endif
13111 #ifdef SQLITE_HAVE_ISNAN
13112   "HAVE_ISNAN",
13113 #endif
13114 #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
13115   "HOMEGROWN_RECURSIVE_MUTEX",
13116 #endif
13117 #ifdef SQLITE_IGNORE_AFP_LOCK_ERRORS
13118   "IGNORE_AFP_LOCK_ERRORS",
13119 #endif
13120 #ifdef SQLITE_IGNORE_FLOCK_LOCK_ERRORS
13121   "IGNORE_FLOCK_LOCK_ERRORS",
13122 #endif
13123 #ifdef SQLITE_INT64_TYPE
13124   "INT64_TYPE",
13125 #endif
13126 #ifdef SQLITE_LOCK_TRACE
13127   "LOCK_TRACE",
13128 #endif
13129 #if defined(SQLITE_MAX_MMAP_SIZE) && !defined(SQLITE_MAX_MMAP_SIZE_xc)
13130   "MAX_MMAP_SIZE=" CTIMEOPT_VAL(SQLITE_MAX_MMAP_SIZE),
13131 #endif
13132 #ifdef SQLITE_MAX_SCHEMA_RETRY
13133   "MAX_SCHEMA_RETRY=" CTIMEOPT_VAL(SQLITE_MAX_SCHEMA_RETRY),
13134 #endif
13135 #ifdef SQLITE_MEMDEBUG
13136   "MEMDEBUG",
13137 #endif
13138 #ifdef SQLITE_MIXED_ENDIAN_64BIT_FLOAT
13139   "MIXED_ENDIAN_64BIT_FLOAT",
13140 #endif
13141 #ifdef SQLITE_NO_SYNC
13142   "NO_SYNC",
13143 #endif
13144 #ifdef SQLITE_OMIT_ALTERTABLE
13145   "OMIT_ALTERTABLE",
13146 #endif
13147 #ifdef SQLITE_OMIT_ANALYZE
13148   "OMIT_ANALYZE",
13149 #endif
13150 #ifdef SQLITE_OMIT_ATTACH
13151   "OMIT_ATTACH",
13152 #endif
13153 #ifdef SQLITE_OMIT_AUTHORIZATION
13154   "OMIT_AUTHORIZATION",
13155 #endif
13156 #ifdef SQLITE_OMIT_AUTOINCREMENT
13157   "OMIT_AUTOINCREMENT",
13158 #endif
13159 #ifdef SQLITE_OMIT_AUTOINIT
13160   "OMIT_AUTOINIT",
13161 #endif
13162 #ifdef SQLITE_OMIT_AUTOMATIC_INDEX
13163   "OMIT_AUTOMATIC_INDEX",
13164 #endif
13165 #ifdef SQLITE_OMIT_AUTORESET
13166   "OMIT_AUTORESET",
13167 #endif
13168 #ifdef SQLITE_OMIT_AUTOVACUUM
13169   "OMIT_AUTOVACUUM",
13170 #endif
13171 #ifdef SQLITE_OMIT_BETWEEN_OPTIMIZATION
13172   "OMIT_BETWEEN_OPTIMIZATION",
13173 #endif
13174 #ifdef SQLITE_OMIT_BLOB_LITERAL
13175   "OMIT_BLOB_LITERAL",
13176 #endif
13177 #ifdef SQLITE_OMIT_BTREECOUNT
13178   "OMIT_BTREECOUNT",
13179 #endif
13180 #ifdef SQLITE_OMIT_BUILTIN_TEST
13181   "OMIT_BUILTIN_TEST",
13182 #endif
13183 #ifdef SQLITE_OMIT_CAST
13184   "OMIT_CAST",
13185 #endif
13186 #ifdef SQLITE_OMIT_CHECK
13187   "OMIT_CHECK",
13188 #endif
13189 #ifdef SQLITE_OMIT_COMPLETE
13190   "OMIT_COMPLETE",
13191 #endif
13192 #ifdef SQLITE_OMIT_COMPOUND_SELECT
13193   "OMIT_COMPOUND_SELECT",
13194 #endif
13195 #ifdef SQLITE_OMIT_DATETIME_FUNCS
13196   "OMIT_DATETIME_FUNCS",
13197 #endif
13198 #ifdef SQLITE_OMIT_DECLTYPE
13199   "OMIT_DECLTYPE",
13200 #endif
13201 #ifdef SQLITE_OMIT_DEPRECATED
13202   "OMIT_DEPRECATED",
13203 #endif
13204 #ifdef SQLITE_OMIT_DISKIO
13205   "OMIT_DISKIO",
13206 #endif
13207 #ifdef SQLITE_OMIT_EXPLAIN
13208   "OMIT_EXPLAIN",
13209 #endif
13210 #ifdef SQLITE_OMIT_FLAG_PRAGMAS
13211   "OMIT_FLAG_PRAGMAS",
13212 #endif
13213 #ifdef SQLITE_OMIT_FLOATING_POINT
13214   "OMIT_FLOATING_POINT",
13215 #endif
13216 #ifdef SQLITE_OMIT_FOREIGN_KEY
13217   "OMIT_FOREIGN_KEY",
13218 #endif
13219 #ifdef SQLITE_OMIT_GET_TABLE
13220   "OMIT_GET_TABLE",
13221 #endif
13222 #ifdef SQLITE_OMIT_INCRBLOB
13223   "OMIT_INCRBLOB",
13224 #endif
13225 #ifdef SQLITE_OMIT_INTEGRITY_CHECK
13226   "OMIT_INTEGRITY_CHECK",
13227 #endif
13228 #ifdef SQLITE_OMIT_LIKE_OPTIMIZATION
13229   "OMIT_LIKE_OPTIMIZATION",
13230 #endif
13231 #ifdef SQLITE_OMIT_LOAD_EXTENSION
13232   "OMIT_LOAD_EXTENSION",
13233 #endif
13234 #ifdef SQLITE_OMIT_LOCALTIME
13235   "OMIT_LOCALTIME",
13236 #endif
13237 #ifdef SQLITE_OMIT_LOOKASIDE
13238   "OMIT_LOOKASIDE",
13239 #endif
13240 #ifdef SQLITE_OMIT_MEMORYDB
13241   "OMIT_MEMORYDB",
13242 #endif
13243 #ifdef SQLITE_OMIT_OR_OPTIMIZATION
13244   "OMIT_OR_OPTIMIZATION",
13245 #endif
13246 #ifdef SQLITE_OMIT_PAGER_PRAGMAS
13247   "OMIT_PAGER_PRAGMAS",
13248 #endif
13249 #ifdef SQLITE_OMIT_PRAGMA
13250   "OMIT_PRAGMA",
13251 #endif
13252 #ifdef SQLITE_OMIT_PROGRESS_CALLBACK
13253   "OMIT_PROGRESS_CALLBACK",
13254 #endif
13255 #ifdef SQLITE_OMIT_QUICKBALANCE
13256   "OMIT_QUICKBALANCE",
13257 #endif
13258 #ifdef SQLITE_OMIT_REINDEX
13259   "OMIT_REINDEX",
13260 #endif
13261 #ifdef SQLITE_OMIT_SCHEMA_PRAGMAS
13262   "OMIT_SCHEMA_PRAGMAS",
13263 #endif
13264 #ifdef SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS
13265   "OMIT_SCHEMA_VERSION_PRAGMAS",
13266 #endif
13267 #ifdef SQLITE_OMIT_SHARED_CACHE
13268   "OMIT_SHARED_CACHE",
13269 #endif
13270 #ifdef SQLITE_OMIT_SUBQUERY
13271   "OMIT_SUBQUERY",
13272 #endif
13273 #ifdef SQLITE_OMIT_TCL_VARIABLE
13274   "OMIT_TCL_VARIABLE",
13275 #endif
13276 #ifdef SQLITE_OMIT_TEMPDB
13277   "OMIT_TEMPDB",
13278 #endif
13279 #ifdef SQLITE_OMIT_TRACE
13280   "OMIT_TRACE",
13281 #endif
13282 #ifdef SQLITE_OMIT_TRIGGER
13283   "OMIT_TRIGGER",
13284 #endif
13285 #ifdef SQLITE_OMIT_TRUNCATE_OPTIMIZATION
13286   "OMIT_TRUNCATE_OPTIMIZATION",
13287 #endif
13288 #ifdef SQLITE_OMIT_UTF16
13289   "OMIT_UTF16",
13290 #endif
13291 #ifdef SQLITE_OMIT_VACUUM
13292   "OMIT_VACUUM",
13293 #endif
13294 #ifdef SQLITE_OMIT_VIEW
13295   "OMIT_VIEW",
13296 #endif
13297 #ifdef SQLITE_OMIT_VIRTUALTABLE
13298   "OMIT_VIRTUALTABLE",
13299 #endif
13300 #ifdef SQLITE_OMIT_WAL
13301   "OMIT_WAL",
13302 #endif
13303 #ifdef SQLITE_OMIT_WSD
13304   "OMIT_WSD",
13305 #endif
13306 #ifdef SQLITE_OMIT_XFER_OPT
13307   "OMIT_XFER_OPT",
13308 #endif
13309 #ifdef SQLITE_PERFORMANCE_TRACE
13310   "PERFORMANCE_TRACE",
13311 #endif
13312 #ifdef SQLITE_PROXY_DEBUG
13313   "PROXY_DEBUG",
13314 #endif
13315 #ifdef SQLITE_RTREE_INT_ONLY
13316   "RTREE_INT_ONLY",
13317 #endif
13318 #ifdef SQLITE_SECURE_DELETE
13319   "SECURE_DELETE",
13320 #endif
13321 #ifdef SQLITE_SMALL_STACK
13322   "SMALL_STACK",
13323 #endif
13324 #ifdef SQLITE_SOUNDEX
13325   "SOUNDEX",
13326 #endif
13327 #ifdef SQLITE_SYSTEM_MALLOC
13328   "SYSTEM_MALLOC",
13329 #endif
13330 #ifdef SQLITE_TCL
13331   "TCL",
13332 #endif
13333 #if defined(SQLITE_TEMP_STORE) && !defined(SQLITE_TEMP_STORE_xc)
13334   "TEMP_STORE=" CTIMEOPT_VAL(SQLITE_TEMP_STORE),
13335 #endif
13336 #ifdef SQLITE_TEST
13337   "TEST",
13338 #endif
13339 #if defined(SQLITE_THREADSAFE)
13340   "THREADSAFE=" CTIMEOPT_VAL(SQLITE_THREADSAFE),
13341 #endif
13342 #ifdef SQLITE_USE_ALLOCA
13343   "USE_ALLOCA",
13344 #endif
13345 #ifdef SQLITE_WIN32_MALLOC
13346   "WIN32_MALLOC",
13347 #endif
13348 #ifdef SQLITE_ZERO_MALLOC
13349   "ZERO_MALLOC"
13350 #endif
13351 };
13352 
13353 /*
13354 ** Given the name of a compile-time option, return true if that option
13355 ** was used and false if not.
13356 **
13357 ** The name can optionally begin with "SQLITE_" but the "SQLITE_" prefix
13358 ** is not required for a match.
13359 */
13360 SQLITE_API int sqlite3_compileoption_used(const char *zOptName){
13361   int i, n;
13362   if( sqlite3StrNICmp(zOptName, "SQLITE_", 7)==0 ) zOptName += 7;
13363   n = sqlite3Strlen30(zOptName);
13364 
13365   /* Since ArraySize(azCompileOpt) is normally in single digits, a
13366   ** linear search is adequate.  No need for a binary search. */
13367   for(i=0; i<ArraySize(azCompileOpt); i++){
13368     if( sqlite3StrNICmp(zOptName, azCompileOpt[i], n)==0
13369      && sqlite3CtypeMap[(unsigned char)azCompileOpt[i][n]]==0
13370     ){
13371       return 1;
13372     }
13373   }
13374   return 0;
13375 }
13376 
13377 /*
13378 ** Return the N-th compile-time option string.  If N is out of range,
13379 ** return a NULL pointer.
13380 */
13381 SQLITE_API const char *sqlite3_compileoption_get(int N){
13382   if( N>=0 && N<ArraySize(azCompileOpt) ){
13383     return azCompileOpt[N];
13384   }
13385   return 0;
13386 }
13387 
13388 #endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
13389 
13390 /************** End of ctime.c ***********************************************/
13391 /************** Begin file status.c ******************************************/
13392 /*
13393 ** 2008 June 18
13394 **
13395 ** The author disclaims copyright to this source code.  In place of
13396 ** a legal notice, here is a blessing:
13397 **
13398 **    May you do good and not evil.
13399 **    May you find forgiveness for yourself and forgive others.
13400 **    May you share freely, never taking more than you give.
13401 **
13402 *************************************************************************
13403 **
13404 ** This module implements the sqlite3_status() interface and related
13405 ** functionality.
13406 */
13407 /************** Include vdbeInt.h in the middle of status.c ******************/
13408 /************** Begin file vdbeInt.h *****************************************/
13409 /*
13410 ** 2003 September 6
13411 **
13412 ** The author disclaims copyright to this source code.  In place of
13413 ** a legal notice, here is a blessing:
13414 **
13415 **    May you do good and not evil.
13416 **    May you find forgiveness for yourself and forgive others.
13417 **    May you share freely, never taking more than you give.
13418 **
13419 *************************************************************************
13420 ** This is the header file for information that is private to the
13421 ** VDBE.  This information used to all be at the top of the single
13422 ** source code file "vdbe.c".  When that file became too big (over
13423 ** 6000 lines long) it was split up into several smaller files and
13424 ** this header information was factored out.
13425 */
13426 #ifndef _VDBEINT_H_
13427 #define _VDBEINT_H_
13428 
13429 /*
13430 ** The maximum number of times that a statement will try to reparse
13431 ** itself before giving up and returning SQLITE_SCHEMA.
13432 */
13433 #ifndef SQLITE_MAX_SCHEMA_RETRY
13434 # define SQLITE_MAX_SCHEMA_RETRY 50
13435 #endif
13436 
13437 /*
13438 ** SQL is translated into a sequence of instructions to be
13439 ** executed by a virtual machine.  Each instruction is an instance
13440 ** of the following structure.
13441 */
13442 typedef struct VdbeOp Op;
13443 
13444 /*
13445 ** Boolean values
13446 */
13447 typedef unsigned Bool;
13448 
13449 /* Opaque type used by code in vdbesort.c */
13450 typedef struct VdbeSorter VdbeSorter;
13451 
13452 /* Opaque type used by the explainer */
13453 typedef struct Explain Explain;
13454 
13455 /* Elements of the linked list at Vdbe.pAuxData */
13456 typedef struct AuxData AuxData;
13457 
13458 /*
13459 ** A cursor is a pointer into a single BTree within a database file.
13460 ** The cursor can seek to a BTree entry with a particular key, or
13461 ** loop over all entries of the Btree.  You can also insert new BTree
13462 ** entries or retrieve the key or data from the entry that the cursor
13463 ** is currently pointing to.
13464 **
13465 ** Cursors can also point to virtual tables, sorters, or "pseudo-tables".
13466 ** A pseudo-table is a single-row table implemented by registers.
13467 ** 
13468 ** Every cursor that the virtual machine has open is represented by an
13469 ** instance of the following structure.
13470 */
13471 struct VdbeCursor {
13472   BtCursor *pCursor;    /* The cursor structure of the backend */
13473   Btree *pBt;           /* Separate file holding temporary table */
13474   KeyInfo *pKeyInfo;    /* Info about index keys needed by index cursors */
13475   int seekResult;       /* Result of previous sqlite3BtreeMoveto() */
13476   int pseudoTableReg;   /* Register holding pseudotable content. */
13477   i16 nField;           /* Number of fields in the header */
13478   u16 nHdrParsed;       /* Number of header fields parsed so far */
13479   i8 iDb;               /* Index of cursor database in db->aDb[] (or -1) */
13480   u8 nullRow;           /* True if pointing to a row with no data */
13481   u8 rowidIsValid;      /* True if lastRowid is valid */
13482   u8 deferredMoveto;    /* A call to sqlite3BtreeMoveto() is needed */
13483   Bool useRandomRowid:1;/* Generate new record numbers semi-randomly */
13484   Bool isTable:1;       /* True if a table requiring integer keys */
13485   Bool isOrdered:1;     /* True if the underlying table is BTREE_UNORDERED */
13486   Bool multiPseudo:1;   /* Multi-register pseudo-cursor */
13487   sqlite3_vtab_cursor *pVtabCursor;  /* The cursor for a virtual table */
13488   i64 seqCount;         /* Sequence counter */
13489   i64 movetoTarget;     /* Argument to the deferred sqlite3BtreeMoveto() */
13490   i64 lastRowid;        /* Rowid being deleted by OP_Delete */
13491   VdbeSorter *pSorter;  /* Sorter object for OP_SorterOpen cursors */
13492 
13493   /* Cached information about the header for the data record that the
13494   ** cursor is currently pointing to.  Only valid if cacheStatus matches
13495   ** Vdbe.cacheCtr.  Vdbe.cacheCtr will never take on the value of
13496   ** CACHE_STALE and so setting cacheStatus=CACHE_STALE guarantees that
13497   ** the cache is out of date.
13498   **
13499   ** aRow might point to (ephemeral) data for the current row, or it might
13500   ** be NULL.
13501   */
13502   u32 cacheStatus;      /* Cache is valid if this matches Vdbe.cacheCtr */
13503   u32 payloadSize;      /* Total number of bytes in the record */
13504   u32 szRow;            /* Byte available in aRow */
13505   u32 iHdrOffset;       /* Offset to next unparsed byte of the header */
13506   const u8 *aRow;       /* Data for the current row, if all on one page */
13507   u32 aType[1];         /* Type values for all entries in the record */
13508   /* 2*nField extra array elements allocated for aType[], beyond the one
13509   ** static element declared in the structure.  nField total array slots for
13510   ** aType[] and nField+1 array slots for aOffset[] */
13511 };
13512 typedef struct VdbeCursor VdbeCursor;
13513 
13514 /*
13515 ** When a sub-program is executed (OP_Program), a structure of this type
13516 ** is allocated to store the current value of the program counter, as
13517 ** well as the current memory cell array and various other frame specific
13518 ** values stored in the Vdbe struct. When the sub-program is finished, 
13519 ** these values are copied back to the Vdbe from the VdbeFrame structure,
13520 ** restoring the state of the VM to as it was before the sub-program
13521 ** began executing.
13522 **
13523 ** The memory for a VdbeFrame object is allocated and managed by a memory
13524 ** cell in the parent (calling) frame. When the memory cell is deleted or
13525 ** overwritten, the VdbeFrame object is not freed immediately. Instead, it
13526 ** is linked into the Vdbe.pDelFrame list. The contents of the Vdbe.pDelFrame
13527 ** list is deleted when the VM is reset in VdbeHalt(). The reason for doing
13528 ** this instead of deleting the VdbeFrame immediately is to avoid recursive
13529 ** calls to sqlite3VdbeMemRelease() when the memory cells belonging to the
13530 ** child frame are released.
13531 **
13532 ** The currently executing frame is stored in Vdbe.pFrame. Vdbe.pFrame is
13533 ** set to NULL if the currently executing frame is the main program.
13534 */
13535 typedef struct VdbeFrame VdbeFrame;
13536 struct VdbeFrame {
13537   Vdbe *v;                /* VM this frame belongs to */
13538   VdbeFrame *pParent;     /* Parent of this frame, or NULL if parent is main */
13539   Op *aOp;                /* Program instructions for parent frame */
13540   Mem *aMem;              /* Array of memory cells for parent frame */
13541   u8 *aOnceFlag;          /* Array of OP_Once flags for parent frame */
13542   VdbeCursor **apCsr;     /* Array of Vdbe cursors for parent frame */
13543   void *token;            /* Copy of SubProgram.token */
13544   i64 lastRowid;          /* Last insert rowid (sqlite3.lastRowid) */
13545   int nCursor;            /* Number of entries in apCsr */
13546   int pc;                 /* Program Counter in parent (calling) frame */
13547   int nOp;                /* Size of aOp array */
13548   int nMem;               /* Number of entries in aMem */
13549   int nOnceFlag;          /* Number of entries in aOnceFlag */
13550   int nChildMem;          /* Number of memory cells for child frame */
13551   int nChildCsr;          /* Number of cursors for child frame */
13552   int nChange;            /* Statement changes (Vdbe.nChanges)     */
13553 };
13554 
13555 #define VdbeFrameMem(p) ((Mem *)&((u8 *)p)[ROUND8(sizeof(VdbeFrame))])
13556 
13557 /*
13558 ** A value for VdbeCursor.cacheValid that means the cache is always invalid.
13559 */
13560 #define CACHE_STALE 0
13561 
13562 /*
13563 ** Internally, the vdbe manipulates nearly all SQL values as Mem
13564 ** structures. Each Mem struct may cache multiple representations (string,
13565 ** integer etc.) of the same value.
13566 */
13567 struct Mem {
13568   sqlite3 *db;        /* The associated database connection */
13569   char *z;            /* String or BLOB value */
13570   double r;           /* Real value */
13571   union {
13572     i64 i;              /* Integer value used when MEM_Int is set in flags */
13573     int nZero;          /* Used when bit MEM_Zero is set in flags */
13574     FuncDef *pDef;      /* Used only when flags==MEM_Agg */
13575     RowSet *pRowSet;    /* Used only when flags==MEM_RowSet */
13576     VdbeFrame *pFrame;  /* Used when flags==MEM_Frame */
13577   } u;
13578   int n;              /* Number of characters in string value, excluding '\0' */
13579   u16 flags;          /* Some combination of MEM_Null, MEM_Str, MEM_Dyn, etc. */
13580   u8  type;           /* One of SQLITE_NULL, SQLITE_TEXT, SQLITE_INTEGER, etc */
13581   u8  enc;            /* SQLITE_UTF8, SQLITE_UTF16BE, SQLITE_UTF16LE */
13582 #ifdef SQLITE_DEBUG
13583   Mem *pScopyFrom;    /* This Mem is a shallow copy of pScopyFrom */
13584   void *pFiller;      /* So that sizeof(Mem) is a multiple of 8 */
13585 #endif
13586   void (*xDel)(void *);  /* If not null, call this function to delete Mem.z */
13587   char *zMalloc;      /* Dynamic buffer allocated by sqlite3_malloc() */
13588 };
13589 
13590 /* One or more of the following flags are set to indicate the validOK
13591 ** representations of the value stored in the Mem struct.
13592 **
13593 ** If the MEM_Null flag is set, then the value is an SQL NULL value.
13594 ** No other flags may be set in this case.
13595 **
13596 ** If the MEM_Str flag is set then Mem.z points at a string representation.
13597 ** Usually this is encoded in the same unicode encoding as the main
13598 ** database (see below for exceptions). If the MEM_Term flag is also
13599 ** set, then the string is nul terminated. The MEM_Int and MEM_Real 
13600 ** flags may coexist with the MEM_Str flag.
13601 */
13602 #define MEM_Null      0x0001   /* Value is NULL */
13603 #define MEM_Str       0x0002   /* Value is a string */
13604 #define MEM_Int       0x0004   /* Value is an integer */
13605 #define MEM_Real      0x0008   /* Value is a real number */
13606 #define MEM_Blob      0x0010   /* Value is a BLOB */
13607 #define MEM_RowSet    0x0020   /* Value is a RowSet object */
13608 #define MEM_Frame     0x0040   /* Value is a VdbeFrame object */
13609 #define MEM_Invalid   0x0080   /* Value is undefined */
13610 #define MEM_Cleared   0x0100   /* NULL set by OP_Null, not from data */
13611 #define MEM_TypeMask  0x01ff   /* Mask of type bits */
13612 
13613 
13614 /* Whenever Mem contains a valid string or blob representation, one of
13615 ** the following flags must be set to determine the memory management
13616 ** policy for Mem.z.  The MEM_Term flag tells us whether or not the
13617 ** string is \000 or \u0000 terminated
13618 */
13619 #define MEM_Term      0x0200   /* String rep is nul terminated */
13620 #define MEM_Dyn       0x0400   /* Need to call sqliteFree() on Mem.z */
13621 #define MEM_Static    0x0800   /* Mem.z points to a static string */
13622 #define MEM_Ephem     0x1000   /* Mem.z points to an ephemeral string */
13623 #define MEM_Agg       0x2000   /* Mem.z points to an agg function context */
13624 #define MEM_Zero      0x4000   /* Mem.i contains count of 0s appended to blob */
13625 #ifdef SQLITE_OMIT_INCRBLOB
13626   #undef MEM_Zero
13627   #define MEM_Zero 0x0000
13628 #endif
13629 
13630 /*
13631 ** Clear any existing type flags from a Mem and replace them with f
13632 */
13633 #define MemSetTypeFlag(p, f) \
13634    ((p)->flags = ((p)->flags&~(MEM_TypeMask|MEM_Zero))|f)
13635 
13636 /*
13637 ** Return true if a memory cell is not marked as invalid.  This macro
13638 ** is for use inside assert() statements only.
13639 */
13640 #ifdef SQLITE_DEBUG
13641 #define memIsValid(M)  ((M)->flags & MEM_Invalid)==0
13642 #endif
13643 
13644 /*
13645 ** Each auxilliary data pointer stored by a user defined function 
13646 ** implementation calling sqlite3_set_auxdata() is stored in an instance
13647 ** of this structure. All such structures associated with a single VM
13648 ** are stored in a linked list headed at Vdbe.pAuxData. All are destroyed
13649 ** when the VM is halted (if not before).
13650 */
13651 struct AuxData {
13652   int iOp;                        /* Instruction number of OP_Function opcode */
13653   int iArg;                       /* Index of function argument. */
13654   void *pAux;                     /* Aux data pointer */
13655   void (*xDelete)(void *);        /* Destructor for the aux data */
13656   AuxData *pNext;                 /* Next element in list */
13657 };
13658 
13659 /*
13660 ** The "context" argument for a installable function.  A pointer to an
13661 ** instance of this structure is the first argument to the routines used
13662 ** implement the SQL functions.
13663 **
13664 ** There is a typedef for this structure in sqlite.h.  So all routines,
13665 ** even the public interface to SQLite, can use a pointer to this structure.
13666 ** But this file is the only place where the internal details of this
13667 ** structure are known.
13668 **
13669 ** This structure is defined inside of vdbeInt.h because it uses substructures
13670 ** (Mem) which are only defined there.
13671 */
13672 struct sqlite3_context {
13673   FuncDef *pFunc;       /* Pointer to function information.  MUST BE FIRST */
13674   Mem s;                /* The return value is stored here */
13675   Mem *pMem;            /* Memory cell used to store aggregate context */
13676   CollSeq *pColl;       /* Collating sequence */
13677   Vdbe *pVdbe;          /* The VM that owns this context */
13678   int iOp;              /* Instruction number of OP_Function */
13679   int isError;          /* Error code returned by the function. */
13680   u8 skipFlag;          /* Skip skip accumulator loading if true */
13681   u8 fErrorOrAux;       /* isError!=0 or pVdbe->pAuxData modified */
13682 };
13683 
13684 /*
13685 ** An Explain object accumulates indented output which is helpful
13686 ** in describing recursive data structures.
13687 */
13688 struct Explain {
13689   Vdbe *pVdbe;       /* Attach the explanation to this Vdbe */
13690   StrAccum str;      /* The string being accumulated */
13691   int nIndent;       /* Number of elements in aIndent */
13692   u16 aIndent[100];  /* Levels of indentation */
13693   char zBase[100];   /* Initial space */
13694 };
13695 
13696 /* A bitfield type for use inside of structures.  Always follow with :N where
13697 ** N is the number of bits.
13698 */
13699 typedef unsigned bft;  /* Bit Field Type */
13700 
13701 /*
13702 ** An instance of the virtual machine.  This structure contains the complete
13703 ** state of the virtual machine.
13704 **
13705 ** The "sqlite3_stmt" structure pointer that is returned by sqlite3_prepare()
13706 ** is really a pointer to an instance of this structure.
13707 **
13708 ** The Vdbe.inVtabMethod variable is set to non-zero for the duration of
13709 ** any virtual table method invocations made by the vdbe program. It is
13710 ** set to 2 for xDestroy method calls and 1 for all other methods. This
13711 ** variable is used for two purposes: to allow xDestroy methods to execute
13712 ** "DROP TABLE" statements and to prevent some nasty side effects of
13713 ** malloc failure when SQLite is invoked recursively by a virtual table 
13714 ** method function.
13715 */
13716 struct Vdbe {
13717   sqlite3 *db;            /* The database connection that owns this statement */
13718   Op *aOp;                /* Space to hold the virtual machine's program */
13719   Mem *aMem;              /* The memory locations */
13720   Mem **apArg;            /* Arguments to currently executing user function */
13721   Mem *aColName;          /* Column names to return */
13722   Mem *pResultSet;        /* Pointer to an array of results */
13723   int nMem;               /* Number of memory locations currently allocated */
13724   int nOp;                /* Number of instructions in the program */
13725   int nOpAlloc;           /* Number of slots allocated for aOp[] */
13726   int nLabel;             /* Number of labels used */
13727   int *aLabel;            /* Space to hold the labels */
13728   u16 nResColumn;         /* Number of columns in one row of the result set */
13729   int nCursor;            /* Number of slots in apCsr[] */
13730   u32 magic;              /* Magic number for sanity checking */
13731   char *zErrMsg;          /* Error message written here */
13732   Vdbe *pPrev,*pNext;     /* Linked list of VDBEs with the same Vdbe.db */
13733   VdbeCursor **apCsr;     /* One element of this array for each open cursor */
13734   Mem *aVar;              /* Values for the OP_Variable opcode. */
13735   char **azVar;           /* Name of variables */
13736   ynVar nVar;             /* Number of entries in aVar[] */
13737   ynVar nzVar;            /* Number of entries in azVar[] */
13738   u32 cacheCtr;           /* VdbeCursor row cache generation counter */
13739   int pc;                 /* The program counter */
13740   int rc;                 /* Value to return */
13741   u8 errorAction;         /* Recovery action to do in case of an error */
13742   u8 minWriteFileFormat;  /* Minimum file format for writable database files */
13743   bft explain:2;          /* True if EXPLAIN present on SQL command */
13744   bft inVtabMethod:2;     /* See comments above */
13745   bft changeCntOn:1;      /* True to update the change-counter */
13746   bft expired:1;          /* True if the VM needs to be recompiled */
13747   bft runOnlyOnce:1;      /* Automatically expire on reset */
13748   bft usesStmtJournal:1;  /* True if uses a statement journal */
13749   bft readOnly:1;         /* True for statements that do not write */
13750   bft bIsReader:1;        /* True for statements that read */
13751   bft isPrepareV2:1;      /* True if prepared with prepare_v2() */
13752   bft doingRerun:1;       /* True if rerunning after an auto-reprepare */
13753   int nChange;            /* Number of db changes made since last reset */
13754   yDbMask btreeMask;      /* Bitmask of db->aDb[] entries referenced */
13755   yDbMask lockMask;       /* Subset of btreeMask that requires a lock */
13756   int iStatement;         /* Statement number (or 0 if has not opened stmt) */
13757   u32 aCounter[5];        /* Counters used by sqlite3_stmt_status() */
13758 #ifndef SQLITE_OMIT_TRACE
13759   i64 startTime;          /* Time when query started - used for profiling */
13760 #endif
13761   i64 iCurrentTime;       /* Value of julianday('now') for this statement */
13762   i64 nFkConstraint;      /* Number of imm. FK constraints this VM */
13763   i64 nStmtDefCons;       /* Number of def. constraints when stmt started */
13764   i64 nStmtDefImmCons;    /* Number of def. imm constraints when stmt started */
13765   char *zSql;             /* Text of the SQL statement that generated this */
13766   void *pFree;            /* Free this when deleting the vdbe */
13767 #ifdef SQLITE_ENABLE_TREE_EXPLAIN
13768   Explain *pExplain;      /* The explainer */
13769   char *zExplain;         /* Explanation of data structures */
13770 #endif
13771   VdbeFrame *pFrame;      /* Parent frame */
13772   VdbeFrame *pDelFrame;   /* List of frame objects to free on VM reset */
13773   int nFrame;             /* Number of frames in pFrame list */
13774   u32 expmask;            /* Binding to these vars invalidates VM */
13775   SubProgram *pProgram;   /* Linked list of all sub-programs used by VM */
13776   int nOnceFlag;          /* Size of array aOnceFlag[] */
13777   u8 *aOnceFlag;          /* Flags for OP_Once */
13778   AuxData *pAuxData;      /* Linked list of auxdata allocations */
13779 };
13780 
13781 /*
13782 ** The following are allowed values for Vdbe.magic
13783 */
13784 #define VDBE_MAGIC_INIT     0x26bceaa5    /* Building a VDBE program */
13785 #define VDBE_MAGIC_RUN      0xbdf20da3    /* VDBE is ready to execute */
13786 #define VDBE_MAGIC_HALT     0x519c2973    /* VDBE has completed execution */
13787 #define VDBE_MAGIC_DEAD     0xb606c3c8    /* The VDBE has been deallocated */
13788 
13789 /*
13790 ** Function prototypes
13791 */
13792 SQLITE_PRIVATE void sqlite3VdbeFreeCursor(Vdbe *, VdbeCursor*);
13793 void sqliteVdbePopStack(Vdbe*,int);
13794 SQLITE_PRIVATE int sqlite3VdbeCursorMoveto(VdbeCursor*);
13795 #if defined(SQLITE_DEBUG) || defined(VDBE_PROFILE)
13796 SQLITE_PRIVATE void sqlite3VdbePrintOp(FILE*, int, Op*);
13797 #endif
13798 SQLITE_PRIVATE u32 sqlite3VdbeSerialTypeLen(u32);
13799 SQLITE_PRIVATE u32 sqlite3VdbeSerialType(Mem*, int);
13800 SQLITE_PRIVATE u32 sqlite3VdbeSerialPut(unsigned char*, int, Mem*, int);
13801 SQLITE_PRIVATE u32 sqlite3VdbeSerialGet(const unsigned char*, u32, Mem*);
13802 SQLITE_PRIVATE void sqlite3VdbeDeleteAuxData(Vdbe*, int, int);
13803 
13804 int sqlite2BtreeKeyCompare(BtCursor *, const void *, int, int, int *);
13805 SQLITE_PRIVATE int sqlite3VdbeIdxKeyCompare(VdbeCursor*,UnpackedRecord*,int*);
13806 SQLITE_PRIVATE int sqlite3VdbeIdxRowid(sqlite3*, BtCursor *, i64 *);
13807 SQLITE_PRIVATE int sqlite3MemCompare(const Mem*, const Mem*, const CollSeq*);
13808 SQLITE_PRIVATE int sqlite3VdbeExec(Vdbe*);
13809 SQLITE_PRIVATE int sqlite3VdbeList(Vdbe*);
13810 SQLITE_PRIVATE int sqlite3VdbeHalt(Vdbe*);
13811 SQLITE_PRIVATE int sqlite3VdbeChangeEncoding(Mem *, int);
13812 SQLITE_PRIVATE int sqlite3VdbeMemTooBig(Mem*);
13813 SQLITE_PRIVATE int sqlite3VdbeMemCopy(Mem*, const Mem*);
13814 SQLITE_PRIVATE void sqlite3VdbeMemShallowCopy(Mem*, const Mem*, int);
13815 SQLITE_PRIVATE void sqlite3VdbeMemMove(Mem*, Mem*);
13816 SQLITE_PRIVATE int sqlite3VdbeMemNulTerminate(Mem*);
13817 SQLITE_PRIVATE int sqlite3VdbeMemSetStr(Mem*, const char*, int, u8, void(*)(void*));
13818 SQLITE_PRIVATE void sqlite3VdbeMemSetInt64(Mem*, i64);
13819 #ifdef SQLITE_OMIT_FLOATING_POINT
13820 # define sqlite3VdbeMemSetDouble sqlite3VdbeMemSetInt64
13821 #else
13822 SQLITE_PRIVATE   void sqlite3VdbeMemSetDouble(Mem*, double);
13823 #endif
13824 SQLITE_PRIVATE void sqlite3VdbeMemSetNull(Mem*);
13825 SQLITE_PRIVATE void sqlite3VdbeMemSetZeroBlob(Mem*,int);
13826 SQLITE_PRIVATE void sqlite3VdbeMemSetRowSet(Mem*);
13827 SQLITE_PRIVATE int sqlite3VdbeMemMakeWriteable(Mem*);
13828 SQLITE_PRIVATE int sqlite3VdbeMemStringify(Mem*, int);
13829 SQLITE_PRIVATE i64 sqlite3VdbeIntValue(Mem*);
13830 SQLITE_PRIVATE int sqlite3VdbeMemIntegerify(Mem*);
13831 SQLITE_PRIVATE double sqlite3VdbeRealValue(Mem*);
13832 SQLITE_PRIVATE void sqlite3VdbeIntegerAffinity(Mem*);
13833 SQLITE_PRIVATE int sqlite3VdbeMemRealify(Mem*);
13834 SQLITE_PRIVATE int sqlite3VdbeMemNumerify(Mem*);
13835 SQLITE_PRIVATE int sqlite3VdbeMemFromBtree(BtCursor*,u32,u32,int,Mem*);
13836 SQLITE_PRIVATE void sqlite3VdbeMemRelease(Mem *p);
13837 SQLITE_PRIVATE void sqlite3VdbeMemReleaseExternal(Mem *p);
13838 #define VdbeMemRelease(X)  \
13839   if((X)->flags&(MEM_Agg|MEM_Dyn|MEM_RowSet|MEM_Frame)) \
13840     sqlite3VdbeMemReleaseExternal(X);
13841 SQLITE_PRIVATE int sqlite3VdbeMemFinalize(Mem*, FuncDef*);
13842 SQLITE_PRIVATE const char *sqlite3OpcodeName(int);
13843 SQLITE_PRIVATE int sqlite3VdbeMemGrow(Mem *pMem, int n, int preserve);
13844 SQLITE_PRIVATE int sqlite3VdbeCloseStatement(Vdbe *, int);
13845 SQLITE_PRIVATE void sqlite3VdbeFrameDelete(VdbeFrame*);
13846 SQLITE_PRIVATE int sqlite3VdbeFrameRestore(VdbeFrame *);
13847 SQLITE_PRIVATE void sqlite3VdbeMemStoreType(Mem *pMem);
13848 SQLITE_PRIVATE int sqlite3VdbeTransferError(Vdbe *p);
13849 
13850 SQLITE_PRIVATE int sqlite3VdbeSorterInit(sqlite3 *, VdbeCursor *);
13851 SQLITE_PRIVATE void sqlite3VdbeSorterClose(sqlite3 *, VdbeCursor *);
13852 SQLITE_PRIVATE int sqlite3VdbeSorterRowkey(const VdbeCursor *, Mem *);
13853 SQLITE_PRIVATE int sqlite3VdbeSorterNext(sqlite3 *, const VdbeCursor *, int *);
13854 SQLITE_PRIVATE int sqlite3VdbeSorterRewind(sqlite3 *, const VdbeCursor *, int *);
13855 SQLITE_PRIVATE int sqlite3VdbeSorterWrite(sqlite3 *, const VdbeCursor *, Mem *);
13856 SQLITE_PRIVATE int sqlite3VdbeSorterCompare(const VdbeCursor *, Mem *, int, int *);
13857 
13858 #if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE>0
13859 SQLITE_PRIVATE   void sqlite3VdbeEnter(Vdbe*);
13860 SQLITE_PRIVATE   void sqlite3VdbeLeave(Vdbe*);
13861 #else
13862 # define sqlite3VdbeEnter(X)
13863 # define sqlite3VdbeLeave(X)
13864 #endif
13865 
13866 #ifdef SQLITE_DEBUG
13867 SQLITE_PRIVATE void sqlite3VdbeMemAboutToChange(Vdbe*,Mem*);
13868 #endif
13869 
13870 #ifndef SQLITE_OMIT_FOREIGN_KEY
13871 SQLITE_PRIVATE int sqlite3VdbeCheckFk(Vdbe *, int);
13872 #else
13873 # define sqlite3VdbeCheckFk(p,i) 0
13874 #endif
13875 
13876 SQLITE_PRIVATE int sqlite3VdbeMemTranslate(Mem*, u8);
13877 #ifdef SQLITE_DEBUG
13878 SQLITE_PRIVATE   void sqlite3VdbePrintSql(Vdbe*);
13879 SQLITE_PRIVATE   void sqlite3VdbeMemPrettyPrint(Mem *pMem, char *zBuf);
13880 #endif
13881 SQLITE_PRIVATE int sqlite3VdbeMemHandleBom(Mem *pMem);
13882 
13883 #ifndef SQLITE_OMIT_INCRBLOB
13884 SQLITE_PRIVATE   int sqlite3VdbeMemExpandBlob(Mem *);
13885   #define ExpandBlob(P) (((P)->flags&MEM_Zero)?sqlite3VdbeMemExpandBlob(P):0)
13886 #else
13887   #define sqlite3VdbeMemExpandBlob(x) SQLITE_OK
13888   #define ExpandBlob(P) SQLITE_OK
13889 #endif
13890 
13891 #endif /* !defined(_VDBEINT_H_) */
13892 
13893 /************** End of vdbeInt.h *********************************************/
13894 /************** Continuing where we left off in status.c *********************/
13895 
13896 /*
13897 ** Variables in which to record status information.
13898 */
13899 typedef struct sqlite3StatType sqlite3StatType;
13900 static SQLITE_WSD struct sqlite3StatType {
13901   int nowValue[10];         /* Current value */
13902   int mxValue[10];          /* Maximum value */
13903 } sqlite3Stat = { {0,}, {0,} };
13904 
13905 
13906 /* The "wsdStat" macro will resolve to the status information
13907 ** state vector.  If writable static data is unsupported on the target,
13908 ** we have to locate the state vector at run-time.  In the more common
13909 ** case where writable static data is supported, wsdStat can refer directly
13910 ** to the "sqlite3Stat" state vector declared above.
13911 */
13912 #ifdef SQLITE_OMIT_WSD
13913 # define wsdStatInit  sqlite3StatType *x = &GLOBAL(sqlite3StatType,sqlite3Stat)
13914 # define wsdStat x[0]
13915 #else
13916 # define wsdStatInit
13917 # define wsdStat sqlite3Stat
13918 #endif
13919 
13920 /*
13921 ** Return the current value of a status parameter.
13922 */
13923 SQLITE_PRIVATE int sqlite3StatusValue(int op){
13924   wsdStatInit;
13925   assert( op>=0 && op<ArraySize(wsdStat.nowValue) );
13926   return wsdStat.nowValue[op];
13927 }
13928 
13929 /*
13930 ** Add N to the value of a status record.  It is assumed that the
13931 ** caller holds appropriate locks.
13932 */
13933 SQLITE_PRIVATE void sqlite3StatusAdd(int op, int N){
13934   wsdStatInit;
13935   assert( op>=0 && op<ArraySize(wsdStat.nowValue) );
13936   wsdStat.nowValue[op] += N;
13937   if( wsdStat.nowValue[op]>wsdStat.mxValue[op] ){
13938     wsdStat.mxValue[op] = wsdStat.nowValue[op];
13939   }
13940 }
13941 
13942 /*
13943 ** Set the value of a status to X.
13944 */
13945 SQLITE_PRIVATE void sqlite3StatusSet(int op, int X){
13946   wsdStatInit;
13947   assert( op>=0 && op<ArraySize(wsdStat.nowValue) );
13948   wsdStat.nowValue[op] = X;
13949   if( wsdStat.nowValue[op]>wsdStat.mxValue[op] ){
13950     wsdStat.mxValue[op] = wsdStat.nowValue[op];
13951   }
13952 }
13953 
13954 /*
13955 ** Query status information.
13956 **
13957 ** This implementation assumes that reading or writing an aligned
13958 ** 32-bit integer is an atomic operation.  If that assumption is not true,
13959 ** then this routine is not threadsafe.
13960 */
13961 SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag){
13962   wsdStatInit;
13963   if( op<0 || op>=ArraySize(wsdStat.nowValue) ){
13964     return SQLITE_MISUSE_BKPT;
13965   }
13966   *pCurrent = wsdStat.nowValue[op];
13967   *pHighwater = wsdStat.mxValue[op];
13968   if( resetFlag ){
13969     wsdStat.mxValue[op] = wsdStat.nowValue[op];
13970   }
13971   return SQLITE_OK;
13972 }
13973 
13974 /*
13975 ** Query status information for a single database connection
13976 */
13977 SQLITE_API int sqlite3_db_status(
13978   sqlite3 *db,          /* The database connection whose status is desired */
13979   int op,               /* Status verb */
13980   int *pCurrent,        /* Write current value here */
13981   int *pHighwater,      /* Write high-water mark here */
13982   int resetFlag         /* Reset high-water mark if true */
13983 ){
13984   int rc = SQLITE_OK;   /* Return code */
13985   sqlite3_mutex_enter(db->mutex);
13986   switch( op ){
13987     case SQLITE_DBSTATUS_LOOKASIDE_USED: {
13988       *pCurrent = db->lookaside.nOut;
13989       *pHighwater = db->lookaside.mxOut;
13990       if( resetFlag ){
13991         db->lookaside.mxOut = db->lookaside.nOut;
13992       }
13993       break;
13994     }
13995 
13996     case SQLITE_DBSTATUS_LOOKASIDE_HIT:
13997     case SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE:
13998     case SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL: {
13999       testcase( op==SQLITE_DBSTATUS_LOOKASIDE_HIT );
14000       testcase( op==SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE );
14001       testcase( op==SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL );
14002       assert( (op-SQLITE_DBSTATUS_LOOKASIDE_HIT)>=0 );
14003       assert( (op-SQLITE_DBSTATUS_LOOKASIDE_HIT)<3 );
14004       *pCurrent = 0;
14005       *pHighwater = db->lookaside.anStat[op - SQLITE_DBSTATUS_LOOKASIDE_HIT];
14006       if( resetFlag ){
14007         db->lookaside.anStat[op - SQLITE_DBSTATUS_LOOKASIDE_HIT] = 0;
14008       }
14009       break;
14010     }
14011 
14012     /* 
14013     ** Return an approximation for the amount of memory currently used
14014     ** by all pagers associated with the given database connection.  The
14015     ** highwater mark is meaningless and is returned as zero.
14016     */
14017     case SQLITE_DBSTATUS_CACHE_USED: {
14018       int totalUsed = 0;
14019       int i;
14020       sqlite3BtreeEnterAll(db);
14021       for(i=0; i<db->nDb; i++){
14022         Btree *pBt = db->aDb[i].pBt;
14023         if( pBt ){
14024           Pager *pPager = sqlite3BtreePager(pBt);
14025           totalUsed += sqlite3PagerMemUsed(pPager);
14026         }
14027       }
14028       sqlite3BtreeLeaveAll(db);
14029       *pCurrent = totalUsed;
14030       *pHighwater = 0;
14031       break;
14032     }
14033 
14034     /*
14035     ** *pCurrent gets an accurate estimate of the amount of memory used
14036     ** to store the schema for all databases (main, temp, and any ATTACHed
14037     ** databases.  *pHighwater is set to zero.
14038     */
14039     case SQLITE_DBSTATUS_SCHEMA_USED: {
14040       int i;                      /* Used to iterate through schemas */
14041       int nByte = 0;              /* Used to accumulate return value */
14042 
14043       sqlite3BtreeEnterAll(db);
14044       db->pnBytesFreed = &nByte;
14045       for(i=0; i<db->nDb; i++){
14046         Schema *pSchema = db->aDb[i].pSchema;
14047         if( ALWAYS(pSchema!=0) ){
14048           HashElem *p;
14049 
14050           nByte += sqlite3GlobalConfig.m.xRoundup(sizeof(HashElem)) * (
14051               pSchema->tblHash.count 
14052             + pSchema->trigHash.count
14053             + pSchema->idxHash.count
14054             + pSchema->fkeyHash.count
14055           );
14056           nByte += sqlite3MallocSize(pSchema->tblHash.ht);
14057           nByte += sqlite3MallocSize(pSchema->trigHash.ht);
14058           nByte += sqlite3MallocSize(pSchema->idxHash.ht);
14059           nByte += sqlite3MallocSize(pSchema->fkeyHash.ht);
14060 
14061           for(p=sqliteHashFirst(&pSchema->trigHash); p; p=sqliteHashNext(p)){
14062             sqlite3DeleteTrigger(db, (Trigger*)sqliteHashData(p));
14063           }
14064           for(p=sqliteHashFirst(&pSchema->tblHash); p; p=sqliteHashNext(p)){
14065             sqlite3DeleteTable(db, (Table *)sqliteHashData(p));
14066           }
14067         }
14068       }
14069       db->pnBytesFreed = 0;
14070       sqlite3BtreeLeaveAll(db);
14071 
14072       *pHighwater = 0;
14073       *pCurrent = nByte;
14074       break;
14075     }
14076 
14077     /*
14078     ** *pCurrent gets an accurate estimate of the amount of memory used
14079     ** to store all prepared statements.
14080     ** *pHighwater is set to zero.
14081     */
14082     case SQLITE_DBSTATUS_STMT_USED: {
14083       struct Vdbe *pVdbe;         /* Used to iterate through VMs */
14084       int nByte = 0;              /* Used to accumulate return value */
14085 
14086       db->pnBytesFreed = &nByte;
14087       for(pVdbe=db->pVdbe; pVdbe; pVdbe=pVdbe->pNext){
14088         sqlite3VdbeClearObject(db, pVdbe);
14089         sqlite3DbFree(db, pVdbe);
14090       }
14091       db->pnBytesFreed = 0;
14092 
14093       *pHighwater = 0;
14094       *pCurrent = nByte;
14095 
14096       break;
14097     }
14098 
14099     /*
14100     ** Set *pCurrent to the total cache hits or misses encountered by all
14101     ** pagers the database handle is connected to. *pHighwater is always set 
14102     ** to zero.
14103     */
14104     case SQLITE_DBSTATUS_CACHE_HIT:
14105     case SQLITE_DBSTATUS_CACHE_MISS:
14106     case SQLITE_DBSTATUS_CACHE_WRITE:{
14107       int i;
14108       int nRet = 0;
14109       assert( SQLITE_DBSTATUS_CACHE_MISS==SQLITE_DBSTATUS_CACHE_HIT+1 );
14110       assert( SQLITE_DBSTATUS_CACHE_WRITE==SQLITE_DBSTATUS_CACHE_HIT+2 );
14111 
14112       for(i=0; i<db->nDb; i++){
14113         if( db->aDb[i].pBt ){
14114           Pager *pPager = sqlite3BtreePager(db->aDb[i].pBt);
14115           sqlite3PagerCacheStat(pPager, op, resetFlag, &nRet);
14116         }
14117       }
14118       *pHighwater = 0;
14119       *pCurrent = nRet;
14120       break;
14121     }
14122 
14123     /* Set *pCurrent to non-zero if there are unresolved deferred foreign
14124     ** key constraints.  Set *pCurrent to zero if all foreign key constraints
14125     ** have been satisfied.  The *pHighwater is always set to zero.
14126     */
14127     case SQLITE_DBSTATUS_DEFERRED_FKS: {
14128       *pHighwater = 0;
14129       *pCurrent = db->nDeferredImmCons>0 || db->nDeferredCons>0;
14130       break;
14131     }
14132 
14133     default: {
14134       rc = SQLITE_ERROR;
14135     }
14136   }
14137   sqlite3_mutex_leave(db->mutex);
14138   return rc;
14139 }
14140 
14141 /************** End of status.c **********************************************/
14142 /************** Begin file date.c ********************************************/
14143 /*
14144 ** 2003 October 31
14145 **
14146 ** The author disclaims copyright to this source code.  In place of
14147 ** a legal notice, here is a blessing:
14148 **
14149 **    May you do good and not evil.
14150 **    May you find forgiveness for yourself and forgive others.
14151 **    May you share freely, never taking more than you give.
14152 **
14153 *************************************************************************
14154 ** This file contains the C functions that implement date and time
14155 ** functions for SQLite.  
14156 **
14157 ** There is only one exported symbol in this file - the function
14158 ** sqlite3RegisterDateTimeFunctions() found at the bottom of the file.
14159 ** All other code has file scope.
14160 **
14161 ** SQLite processes all times and dates as Julian Day numbers.  The
14162 ** dates and times are stored as the number of days since noon
14163 ** in Greenwich on November 24, 4714 B.C. according to the Gregorian
14164 ** calendar system. 
14165 **
14166 ** 1970-01-01 00:00:00 is JD 2440587.5
14167 ** 2000-01-01 00:00:00 is JD 2451544.5
14168 **
14169 ** This implemention requires years to be expressed as a 4-digit number
14170 ** which means that only dates between 0000-01-01 and 9999-12-31 can
14171 ** be represented, even though julian day numbers allow a much wider
14172 ** range of dates.
14173 **
14174 ** The Gregorian calendar system is used for all dates and times,
14175 ** even those that predate the Gregorian calendar.  Historians usually
14176 ** use the Julian calendar for dates prior to 1582-10-15 and for some
14177 ** dates afterwards, depending on locale.  Beware of this difference.
14178 **
14179 ** The conversion algorithms are implemented based on descriptions
14180 ** in the following text:
14181 **
14182 **      Jean Meeus
14183 **      Astronomical Algorithms, 2nd Edition, 1998
14184 **      ISBM 0-943396-61-1
14185 **      Willmann-Bell, Inc
14186 **      Richmond, Virginia (USA)
14187 */
14188 /* #include <stdlib.h> */
14189 /* #include <assert.h> */
14190 #include <time.h>
14191 
14192 #ifndef SQLITE_OMIT_DATETIME_FUNCS
14193 
14194 
14195 /*
14196 ** A structure for holding a single date and time.
14197 */
14198 typedef struct DateTime DateTime;
14199 struct DateTime {
14200   sqlite3_int64 iJD; /* The julian day number times 86400000 */
14201   int Y, M, D;       /* Year, month, and day */
14202   int h, m;          /* Hour and minutes */
14203   int tz;            /* Timezone offset in minutes */
14204   double s;          /* Seconds */
14205   char validYMD;     /* True (1) if Y,M,D are valid */
14206   char validHMS;     /* True (1) if h,m,s are valid */
14207   char validJD;      /* True (1) if iJD is valid */
14208   char validTZ;      /* True (1) if tz is valid */
14209 };
14210 
14211 
14212 /*
14213 ** Convert zDate into one or more integers.  Additional arguments
14214 ** come in groups of 5 as follows:
14215 **
14216 **       N       number of digits in the integer
14217 **       min     minimum allowed value of the integer
14218 **       max     maximum allowed value of the integer
14219 **       nextC   first character after the integer
14220 **       pVal    where to write the integers value.
14221 **
14222 ** Conversions continue until one with nextC==0 is encountered.
14223 ** The function returns the number of successful conversions.
14224 */
14225 static int getDigits(const char *zDate, ...){
14226   va_list ap;
14227   int val;
14228   int N;
14229   int min;
14230   int max;
14231   int nextC;
14232   int *pVal;
14233   int cnt = 0;
14234   va_start(ap, zDate);
14235   do{
14236     N = va_arg(ap, int);
14237     min = va_arg(ap, int);
14238     max = va_arg(ap, int);
14239     nextC = va_arg(ap, int);
14240     pVal = va_arg(ap, int*);
14241     val = 0;
14242     while( N-- ){
14243       if( !sqlite3Isdigit(*zDate) ){
14244         goto end_getDigits;
14245       }
14246       val = val*10 + *zDate - '0';
14247       zDate++;
14248     }
14249     if( val<min || val>max || (nextC!=0 && nextC!=*zDate) ){
14250       goto end_getDigits;
14251     }
14252     *pVal = val;
14253     zDate++;
14254     cnt++;
14255   }while( nextC );
14256 end_getDigits:
14257   va_end(ap);
14258   return cnt;
14259 }
14260 
14261 /*
14262 ** Parse a timezone extension on the end of a date-time.
14263 ** The extension is of the form:
14264 **
14265 **        (+/-)HH:MM
14266 **
14267 ** Or the "zulu" notation:
14268 **
14269 **        Z
14270 **
14271 ** If the parse is successful, write the number of minutes
14272 ** of change in p->tz and return 0.  If a parser error occurs,
14273 ** return non-zero.
14274 **
14275 ** A missing specifier is not considered an error.
14276 */
14277 static int parseTimezone(const char *zDate, DateTime *p){
14278   int sgn = 0;
14279   int nHr, nMn;
14280   int c;
14281   while( sqlite3Isspace(*zDate) ){ zDate++; }
14282   p->tz = 0;
14283   c = *zDate;
14284   if( c=='-' ){
14285     sgn = -1;
14286   }else if( c=='+' ){
14287     sgn = +1;
14288   }else if( c=='Z' || c=='z' ){
14289     zDate++;
14290     goto zulu_time;
14291   }else{
14292     return c!=0;
14293   }
14294   zDate++;
14295   if( getDigits(zDate, 2, 0, 14, ':', &nHr, 2, 0, 59, 0, &nMn)!=2 ){
14296     return 1;
14297   }
14298   zDate += 5;
14299   p->tz = sgn*(nMn + nHr*60);
14300 zulu_time:
14301   while( sqlite3Isspace(*zDate) ){ zDate++; }
14302   return *zDate!=0;
14303 }
14304 
14305 /*
14306 ** Parse times of the form HH:MM or HH:MM:SS or HH:MM:SS.FFFF.
14307 ** The HH, MM, and SS must each be exactly 2 digits.  The
14308 ** fractional seconds FFFF can be one or more digits.
14309 **
14310 ** Return 1 if there is a parsing error and 0 on success.
14311 */
14312 static int parseHhMmSs(const char *zDate, DateTime *p){
14313   int h, m, s;
14314   double ms = 0.0;
14315   if( getDigits(zDate, 2, 0, 24, ':', &h, 2, 0, 59, 0, &m)!=2 ){
14316     return 1;
14317   }
14318   zDate += 5;
14319   if( *zDate==':' ){
14320     zDate++;
14321     if( getDigits(zDate, 2, 0, 59, 0, &s)!=1 ){
14322       return 1;
14323     }
14324     zDate += 2;
14325     if( *zDate=='.' && sqlite3Isdigit(zDate[1]) ){
14326       double rScale = 1.0;
14327       zDate++;
14328       while( sqlite3Isdigit(*zDate) ){
14329         ms = ms*10.0 + *zDate - '0';
14330         rScale *= 10.0;
14331         zDate++;
14332       }
14333       ms /= rScale;
14334     }
14335   }else{
14336     s = 0;
14337   }
14338   p->validJD = 0;
14339   p->validHMS = 1;
14340   p->h = h;
14341   p->m = m;
14342   p->s = s + ms;
14343   if( parseTimezone(zDate, p) ) return 1;
14344   p->validTZ = (p->tz!=0)?1:0;
14345   return 0;
14346 }
14347 
14348 /*
14349 ** Convert from YYYY-MM-DD HH:MM:SS to julian day.  We always assume
14350 ** that the YYYY-MM-DD is according to the Gregorian calendar.
14351 **
14352 ** Reference:  Meeus page 61
14353 */
14354 static void computeJD(DateTime *p){
14355   int Y, M, D, A, B, X1, X2;
14356 
14357   if( p->validJD ) return;
14358   if( p->validYMD ){
14359     Y = p->Y;
14360     M = p->M;
14361     D = p->D;
14362   }else{
14363     Y = 2000;  /* If no YMD specified, assume 2000-Jan-01 */
14364     M = 1;
14365     D = 1;
14366   }
14367   if( M<=2 ){
14368     Y--;
14369     M += 12;
14370   }
14371   A = Y/100;
14372   B = 2 - A + (A/4);
14373   X1 = 36525*(Y+4716)/100;
14374   X2 = 306001*(M+1)/10000;
14375   p->iJD = (sqlite3_int64)((X1 + X2 + D + B - 1524.5 ) * 86400000);
14376   p->validJD = 1;
14377   if( p->validHMS ){
14378     p->iJD += p->h*3600000 + p->m*60000 + (sqlite3_int64)(p->s*1000);
14379     if( p->validTZ ){
14380       p->iJD -= p->tz*60000;
14381       p->validYMD = 0;
14382       p->validHMS = 0;
14383       p->validTZ = 0;
14384     }
14385   }
14386 }
14387 
14388 /*
14389 ** Parse dates of the form
14390 **
14391 **     YYYY-MM-DD HH:MM:SS.FFF
14392 **     YYYY-MM-DD HH:MM:SS
14393 **     YYYY-MM-DD HH:MM
14394 **     YYYY-MM-DD
14395 **
14396 ** Write the result into the DateTime structure and return 0
14397 ** on success and 1 if the input string is not a well-formed
14398 ** date.
14399 */
14400 static int parseYyyyMmDd(const char *zDate, DateTime *p){
14401   int Y, M, D, neg;
14402 
14403   if( zDate[0]=='-' ){
14404     zDate++;
14405     neg = 1;
14406   }else{
14407     neg = 0;
14408   }
14409   if( getDigits(zDate,4,0,9999,'-',&Y,2,1,12,'-',&M,2,1,31,0,&D)!=3 ){
14410     return 1;
14411   }
14412   zDate += 10;
14413   while( sqlite3Isspace(*zDate) || 'T'==*(u8*)zDate ){ zDate++; }
14414   if( parseHhMmSs(zDate, p)==0 ){
14415     /* We got the time */
14416   }else if( *zDate==0 ){
14417     p->validHMS = 0;
14418   }else{
14419     return 1;
14420   }
14421   p->validJD = 0;
14422   p->validYMD = 1;
14423   p->Y = neg ? -Y : Y;
14424   p->M = M;
14425   p->D = D;
14426   if( p->validTZ ){
14427     computeJD(p);
14428   }
14429   return 0;
14430 }
14431 
14432 /*
14433 ** Set the time to the current time reported by the VFS.
14434 **
14435 ** Return the number of errors.
14436 */
14437 static int setDateTimeToCurrent(sqlite3_context *context, DateTime *p){
14438   p->iJD = sqlite3StmtCurrentTime(context);
14439   if( p->iJD>0 ){
14440     p->validJD = 1;
14441     return 0;
14442   }else{
14443     return 1;
14444   }
14445 }
14446 
14447 /*
14448 ** Attempt to parse the given string into a Julian Day Number.  Return
14449 ** the number of errors.
14450 **
14451 ** The following are acceptable forms for the input string:
14452 **
14453 **      YYYY-MM-DD HH:MM:SS.FFF  +/-HH:MM
14454 **      DDDD.DD 
14455 **      now
14456 **
14457 ** In the first form, the +/-HH:MM is always optional.  The fractional
14458 ** seconds extension (the ".FFF") is optional.  The seconds portion
14459 ** (":SS.FFF") is option.  The year and date can be omitted as long
14460 ** as there is a time string.  The time string can be omitted as long
14461 ** as there is a year and date.
14462 */
14463 static int parseDateOrTime(
14464   sqlite3_context *context, 
14465   const char *zDate, 
14466   DateTime *p
14467 ){
14468   double r;
14469   if( parseYyyyMmDd(zDate,p)==0 ){
14470     return 0;
14471   }else if( parseHhMmSs(zDate, p)==0 ){
14472     return 0;
14473   }else if( sqlite3StrICmp(zDate,"now")==0){
14474     return setDateTimeToCurrent(context, p);
14475   }else if( sqlite3AtoF(zDate, &r, sqlite3Strlen30(zDate), SQLITE_UTF8) ){
14476     p->iJD = (sqlite3_int64)(r*86400000.0 + 0.5);
14477     p->validJD = 1;
14478     return 0;
14479   }
14480   return 1;
14481 }
14482 
14483 /*
14484 ** Compute the Year, Month, and Day from the julian day number.
14485 */
14486 static void computeYMD(DateTime *p){
14487   int Z, A, B, C, D, E, X1;
14488   if( p->validYMD ) return;
14489   if( !p->validJD ){
14490     p->Y = 2000;
14491     p->M = 1;
14492     p->D = 1;
14493   }else{
14494     Z = (int)((p->iJD + 43200000)/86400000);
14495     A = (int)((Z - 1867216.25)/36524.25);
14496     A = Z + 1 + A - (A/4);
14497     B = A + 1524;
14498     C = (int)((B - 122.1)/365.25);
14499     D = (36525*C)/100;
14500     E = (int)((B-D)/30.6001);
14501     X1 = (int)(30.6001*E);
14502     p->D = B - D - X1;
14503     p->M = E<14 ? E-1 : E-13;
14504     p->Y = p->M>2 ? C - 4716 : C - 4715;
14505   }
14506   p->validYMD = 1;
14507 }
14508 
14509 /*
14510 ** Compute the Hour, Minute, and Seconds from the julian day number.
14511 */
14512 static void computeHMS(DateTime *p){
14513   int s;
14514   if( p->validHMS ) return;
14515   computeJD(p);
14516   s = (int)((p->iJD + 43200000) % 86400000);
14517   p->s = s/1000.0;
14518   s = (int)p->s;
14519   p->s -= s;
14520   p->h = s/3600;
14521   s -= p->h*3600;
14522   p->m = s/60;
14523   p->s += s - p->m*60;
14524   p->validHMS = 1;
14525 }
14526 
14527 /*
14528 ** Compute both YMD and HMS
14529 */
14530 static void computeYMD_HMS(DateTime *p){
14531   computeYMD(p);
14532   computeHMS(p);
14533 }
14534 
14535 /*
14536 ** Clear the YMD and HMS and the TZ
14537 */
14538 static void clearYMD_HMS_TZ(DateTime *p){
14539   p->validYMD = 0;
14540   p->validHMS = 0;
14541   p->validTZ = 0;
14542 }
14543 
14544 /*
14545 ** On recent Windows platforms, the localtime_s() function is available
14546 ** as part of the "Secure CRT". It is essentially equivalent to 
14547 ** localtime_r() available under most POSIX platforms, except that the 
14548 ** order of the parameters is reversed.
14549 **
14550 ** See http://msdn.microsoft.com/en-us/library/a442x3ye(VS.80).aspx.
14551 **
14552 ** If the user has not indicated to use localtime_r() or localtime_s()
14553 ** already, check for an MSVC build environment that provides 
14554 ** localtime_s().
14555 */
14556 #if !defined(HAVE_LOCALTIME_R) && !defined(HAVE_LOCALTIME_S) && \
14557      defined(_MSC_VER) && defined(_CRT_INSECURE_DEPRECATE)
14558 #define HAVE_LOCALTIME_S 1
14559 #endif
14560 
14561 #ifndef SQLITE_OMIT_LOCALTIME
14562 /*
14563 ** The following routine implements the rough equivalent of localtime_r()
14564 ** using whatever operating-system specific localtime facility that
14565 ** is available.  This routine returns 0 on success and
14566 ** non-zero on any kind of error.
14567 **
14568 ** If the sqlite3GlobalConfig.bLocaltimeFault variable is true then this
14569 ** routine will always fail.
14570 **
14571 ** EVIDENCE-OF: R-62172-00036 In this implementation, the standard C
14572 ** library function localtime_r() is used to assist in the calculation of
14573 ** local time.
14574 */
14575 static int osLocaltime(time_t *t, struct tm *pTm){
14576   int rc;
14577 #if (!defined(HAVE_LOCALTIME_R) || !HAVE_LOCALTIME_R) \
14578       && (!defined(HAVE_LOCALTIME_S) || !HAVE_LOCALTIME_S)
14579   struct tm *pX;
14580 #if SQLITE_THREADSAFE>0
14581   sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
14582 #endif
14583   sqlite3_mutex_enter(mutex);
14584   pX = localtime(t);
14585 #ifndef SQLITE_OMIT_BUILTIN_TEST
14586   if( sqlite3GlobalConfig.bLocaltimeFault ) pX = 0;
14587 #endif
14588   if( pX ) *pTm = *pX;
14589   sqlite3_mutex_leave(mutex);
14590   rc = pX==0;
14591 #else
14592 #ifndef SQLITE_OMIT_BUILTIN_TEST
14593   if( sqlite3GlobalConfig.bLocaltimeFault ) return 1;
14594 #endif
14595 #if defined(HAVE_LOCALTIME_R) && HAVE_LOCALTIME_R
14596   rc = localtime_r(t, pTm)==0;
14597 #else
14598   rc = localtime_s(pTm, t);
14599 #endif /* HAVE_LOCALTIME_R */
14600 #endif /* HAVE_LOCALTIME_R || HAVE_LOCALTIME_S */
14601   return rc;
14602 }
14603 #endif /* SQLITE_OMIT_LOCALTIME */
14604 
14605 
14606 #ifndef SQLITE_OMIT_LOCALTIME
14607 /*
14608 ** Compute the difference (in milliseconds) between localtime and UTC
14609 ** (a.k.a. GMT) for the time value p where p is in UTC. If no error occurs,
14610 ** return this value and set *pRc to SQLITE_OK. 
14611 **
14612 ** Or, if an error does occur, set *pRc to SQLITE_ERROR. The returned value
14613 ** is undefined in this case.
14614 */
14615 static sqlite3_int64 localtimeOffset(
14616   DateTime *p,                    /* Date at which to calculate offset */
14617   sqlite3_context *pCtx,          /* Write error here if one occurs */
14618   int *pRc                        /* OUT: Error code. SQLITE_OK or ERROR */
14619 ){
14620   DateTime x, y;
14621   time_t t;
14622   struct tm sLocal;
14623 
14624   /* Initialize the contents of sLocal to avoid a compiler warning. */
14625   memset(&sLocal, 0, sizeof(sLocal));
14626 
14627   x = *p;
14628   computeYMD_HMS(&x);
14629   if( x.Y<1971 || x.Y>=2038 ){
14630     /* EVIDENCE-OF: R-55269-29598 The localtime_r() C function normally only
14631     ** works for years between 1970 and 2037. For dates outside this range,
14632     ** SQLite attempts to map the year into an equivalent year within this
14633     ** range, do the calculation, then map the year back.
14634     */
14635     x.Y = 2000;
14636     x.M = 1;
14637     x.D = 1;
14638     x.h = 0;
14639     x.m = 0;
14640     x.s = 0.0;
14641   } else {
14642     int s = (int)(x.s + 0.5);
14643     x.s = s;
14644   }
14645   x.tz = 0;
14646   x.validJD = 0;
14647   computeJD(&x);
14648   t = (time_t)(x.iJD/1000 - 21086676*(i64)10000);
14649   if( osLocaltime(&t, &sLocal) ){
14650     sqlite3_result_error(pCtx, "local time unavailable", -1);
14651     *pRc = SQLITE_ERROR;
14652     return 0;
14653   }
14654   y.Y = sLocal.tm_year + 1900;
14655   y.M = sLocal.tm_mon + 1;
14656   y.D = sLocal.tm_mday;
14657   y.h = sLocal.tm_hour;
14658   y.m = sLocal.tm_min;
14659   y.s = sLocal.tm_sec;
14660   y.validYMD = 1;
14661   y.validHMS = 1;
14662   y.validJD = 0;
14663   y.validTZ = 0;
14664   computeJD(&y);
14665   *pRc = SQLITE_OK;
14666   return y.iJD - x.iJD;
14667 }
14668 #endif /* SQLITE_OMIT_LOCALTIME */
14669 
14670 /*
14671 ** Process a modifier to a date-time stamp.  The modifiers are
14672 ** as follows:
14673 **
14674 **     NNN days
14675 **     NNN hours
14676 **     NNN minutes
14677 **     NNN.NNNN seconds
14678 **     NNN months
14679 **     NNN years
14680 **     start of month
14681 **     start of year
14682 **     start of week
14683 **     start of day
14684 **     weekday N
14685 **     unixepoch
14686 **     localtime
14687 **     utc
14688 **
14689 ** Return 0 on success and 1 if there is any kind of error. If the error
14690 ** is in a system call (i.e. localtime()), then an error message is written
14691 ** to context pCtx. If the error is an unrecognized modifier, no error is
14692 ** written to pCtx.
14693 */
14694 static int parseModifier(sqlite3_context *pCtx, const char *zMod, DateTime *p){
14695   int rc = 1;
14696   int n;
14697   double r;
14698   char *z, zBuf[30];
14699   z = zBuf;
14700   for(n=0; n<ArraySize(zBuf)-1 && zMod[n]; n++){
14701     z[n] = (char)sqlite3UpperToLower[(u8)zMod[n]];
14702   }
14703   z[n] = 0;
14704   switch( z[0] ){
14705 #ifndef SQLITE_OMIT_LOCALTIME
14706     case 'l': {
14707       /*    localtime
14708       **
14709       ** Assuming the current time value is UTC (a.k.a. GMT), shift it to
14710       ** show local time.
14711       */
14712       if( strcmp(z, "localtime")==0 ){
14713         computeJD(p);
14714         p->iJD += localtimeOffset(p, pCtx, &rc);
14715         clearYMD_HMS_TZ(p);
14716       }
14717       break;
14718     }
14719 #endif
14720     case 'u': {
14721       /*
14722       **    unixepoch
14723       **
14724       ** Treat the current value of p->iJD as the number of
14725       ** seconds since 1970.  Convert to a real julian day number.
14726       */
14727       if( strcmp(z, "unixepoch")==0 && p->validJD ){
14728         p->iJD = (p->iJD + 43200)/86400 + 21086676*(i64)10000000;
14729         clearYMD_HMS_TZ(p);
14730         rc = 0;
14731       }
14732 #ifndef SQLITE_OMIT_LOCALTIME
14733       else if( strcmp(z, "utc")==0 ){
14734         sqlite3_int64 c1;
14735         computeJD(p);
14736         c1 = localtimeOffset(p, pCtx, &rc);
14737         if( rc==SQLITE_OK ){
14738           p->iJD -= c1;
14739           clearYMD_HMS_TZ(p);
14740           p->iJD += c1 - localtimeOffset(p, pCtx, &rc);
14741         }
14742       }
14743 #endif
14744       break;
14745     }
14746     case 'w': {
14747       /*
14748       **    weekday N
14749       **
14750       ** Move the date to the same time on the next occurrence of
14751       ** weekday N where 0==Sunday, 1==Monday, and so forth.  If the
14752       ** date is already on the appropriate weekday, this is a no-op.
14753       */
14754       if( strncmp(z, "weekday ", 8)==0
14755                && sqlite3AtoF(&z[8], &r, sqlite3Strlen30(&z[8]), SQLITE_UTF8)
14756                && (n=(int)r)==r && n>=0 && r<7 ){
14757         sqlite3_int64 Z;
14758         computeYMD_HMS(p);
14759         p->validTZ = 0;
14760         p->validJD = 0;
14761         computeJD(p);
14762         Z = ((p->iJD + 129600000)/86400000) % 7;
14763         if( Z>n ) Z -= 7;
14764         p->iJD += (n - Z)*86400000;
14765         clearYMD_HMS_TZ(p);
14766         rc = 0;
14767       }
14768       break;
14769     }
14770     case 's': {
14771       /*
14772       **    start of TTTTT
14773       **
14774       ** Move the date backwards to the beginning of the current day,
14775       ** or month or year.
14776       */
14777       if( strncmp(z, "start of ", 9)!=0 ) break;
14778       z += 9;
14779       computeYMD(p);
14780       p->validHMS = 1;
14781       p->h = p->m = 0;
14782       p->s = 0.0;
14783       p->validTZ = 0;
14784       p->validJD = 0;
14785       if( strcmp(z,"month")==0 ){
14786         p->D = 1;
14787         rc = 0;
14788       }else if( strcmp(z,"year")==0 ){
14789         computeYMD(p);
14790         p->M = 1;
14791         p->D = 1;
14792         rc = 0;
14793       }else if( strcmp(z,"day")==0 ){
14794         rc = 0;
14795       }
14796       break;
14797     }
14798     case '+':
14799     case '-':
14800     case '0':
14801     case '1':
14802     case '2':
14803     case '3':
14804     case '4':
14805     case '5':
14806     case '6':
14807     case '7':
14808     case '8':
14809     case '9': {
14810       double rRounder;
14811       for(n=1; z[n] && z[n]!=':' && !sqlite3Isspace(z[n]); n++){}
14812       if( !sqlite3AtoF(z, &r, n, SQLITE_UTF8) ){
14813         rc = 1;
14814         break;
14815       }
14816       if( z[n]==':' ){
14817         /* A modifier of the form (+|-)HH:MM:SS.FFF adds (or subtracts) the
14818         ** specified number of hours, minutes, seconds, and fractional seconds
14819         ** to the time.  The ".FFF" may be omitted.  The ":SS.FFF" may be
14820         ** omitted.
14821         */
14822         const char *z2 = z;
14823         DateTime tx;
14824         sqlite3_int64 day;
14825         if( !sqlite3Isdigit(*z2) ) z2++;
14826         memset(&tx, 0, sizeof(tx));
14827         if( parseHhMmSs(z2, &tx) ) break;
14828         computeJD(&tx);
14829         tx.iJD -= 43200000;
14830         day = tx.iJD/86400000;
14831         tx.iJD -= day*86400000;
14832         if( z[0]=='-' ) tx.iJD = -tx.iJD;
14833         computeJD(p);
14834         clearYMD_HMS_TZ(p);
14835         p->iJD += tx.iJD;
14836         rc = 0;
14837         break;
14838       }
14839       z += n;
14840       while( sqlite3Isspace(*z) ) z++;
14841       n = sqlite3Strlen30(z);
14842       if( n>10 || n<3 ) break;
14843       if( z[n-1]=='s' ){ z[n-1] = 0; n--; }
14844       computeJD(p);
14845       rc = 0;
14846       rRounder = r<0 ? -0.5 : +0.5;
14847       if( n==3 && strcmp(z,"day")==0 ){
14848         p->iJD += (sqlite3_int64)(r*86400000.0 + rRounder);
14849       }else if( n==4 && strcmp(z,"hour")==0 ){
14850         p->iJD += (sqlite3_int64)(r*(86400000.0/24.0) + rRounder);
14851       }else if( n==6 && strcmp(z,"minute")==0 ){
14852         p->iJD += (sqlite3_int64)(r*(86400000.0/(24.0*60.0)) + rRounder);
14853       }else if( n==6 && strcmp(z,"second")==0 ){
14854         p->iJD += (sqlite3_int64)(r*(86400000.0/(24.0*60.0*60.0)) + rRounder);
14855       }else if( n==5 && strcmp(z,"month")==0 ){
14856         int x, y;
14857         computeYMD_HMS(p);
14858         p->M += (int)r;
14859         x = p->M>0 ? (p->M-1)/12 : (p->M-12)/12;
14860         p->Y += x;
14861         p->M -= x*12;
14862         p->validJD = 0;
14863         computeJD(p);
14864         y = (int)r;
14865         if( y!=r ){
14866           p->iJD += (sqlite3_int64)((r - y)*30.0*86400000.0 + rRounder);
14867         }
14868       }else if( n==4 && strcmp(z,"year")==0 ){
14869         int y = (int)r;
14870         computeYMD_HMS(p);
14871         p->Y += y;
14872         p->validJD = 0;
14873         computeJD(p);
14874         if( y!=r ){
14875           p->iJD += (sqlite3_int64)((r - y)*365.0*86400000.0 + rRounder);
14876         }
14877       }else{
14878         rc = 1;
14879       }
14880       clearYMD_HMS_TZ(p);
14881       break;
14882     }
14883     default: {
14884       break;
14885     }
14886   }
14887   return rc;
14888 }
14889 
14890 /*
14891 ** Process time function arguments.  argv[0] is a date-time stamp.
14892 ** argv[1] and following are modifiers.  Parse them all and write
14893 ** the resulting time into the DateTime structure p.  Return 0
14894 ** on success and 1 if there are any errors.
14895 **
14896 ** If there are zero parameters (if even argv[0] is undefined)
14897 ** then assume a default value of "now" for argv[0].
14898 */
14899 static int isDate(
14900   sqlite3_context *context, 
14901   int argc, 
14902   sqlite3_value **argv, 
14903   DateTime *p
14904 ){
14905   int i;
14906   const unsigned char *z;
14907   int eType;
14908   memset(p, 0, sizeof(*p));
14909   if( argc==0 ){
14910     return setDateTimeToCurrent(context, p);
14911   }
14912   if( (eType = sqlite3_value_type(argv[0]))==SQLITE_FLOAT
14913                    || eType==SQLITE_INTEGER ){
14914     p->iJD = (sqlite3_int64)(sqlite3_value_double(argv[0])*86400000.0 + 0.5);
14915     p->validJD = 1;
14916   }else{
14917     z = sqlite3_value_text(argv[0]);
14918     if( !z || parseDateOrTime(context, (char*)z, p) ){
14919       return 1;
14920     }
14921   }
14922   for(i=1; i<argc; i++){
14923     z = sqlite3_value_text(argv[i]);
14924     if( z==0 || parseModifier(context, (char*)z, p) ) return 1;
14925   }
14926   return 0;
14927 }
14928 
14929 
14930 /*
14931 ** The following routines implement the various date and time functions
14932 ** of SQLite.
14933 */
14934 
14935 /*
14936 **    julianday( TIMESTRING, MOD, MOD, ...)
14937 **
14938 ** Return the julian day number of the date specified in the arguments
14939 */
14940 static void juliandayFunc(
14941   sqlite3_context *context,
14942   int argc,
14943   sqlite3_value **argv
14944 ){
14945   DateTime x;
14946   if( isDate(context, argc, argv, &x)==0 ){
14947     computeJD(&x);
14948     sqlite3_result_double(context, x.iJD/86400000.0);
14949   }
14950 }
14951 
14952 /*
14953 **    datetime( TIMESTRING, MOD, MOD, ...)
14954 **
14955 ** Return YYYY-MM-DD HH:MM:SS
14956 */
14957 static void datetimeFunc(
14958   sqlite3_context *context,
14959   int argc,
14960   sqlite3_value **argv
14961 ){
14962   DateTime x;
14963   if( isDate(context, argc, argv, &x)==0 ){
14964     char zBuf[100];
14965     computeYMD_HMS(&x);
14966     sqlite3_snprintf(sizeof(zBuf), zBuf, "%04d-%02d-%02d %02d:%02d:%02d",
14967                      x.Y, x.M, x.D, x.h, x.m, (int)(x.s));
14968     sqlite3_result_text(context, zBuf, -1, SQLITE_TRANSIENT);
14969   }
14970 }
14971 
14972 /*
14973 **    time( TIMESTRING, MOD, MOD, ...)
14974 **
14975 ** Return HH:MM:SS
14976 */
14977 static void timeFunc(
14978   sqlite3_context *context,
14979   int argc,
14980   sqlite3_value **argv
14981 ){
14982   DateTime x;
14983   if( isDate(context, argc, argv, &x)==0 ){
14984     char zBuf[100];
14985     computeHMS(&x);
14986     sqlite3_snprintf(sizeof(zBuf), zBuf, "%02d:%02d:%02d", x.h, x.m, (int)x.s);
14987     sqlite3_result_text(context, zBuf, -1, SQLITE_TRANSIENT);
14988   }
14989 }
14990 
14991 /*
14992 **    date( TIMESTRING, MOD, MOD, ...)
14993 **
14994 ** Return YYYY-MM-DD
14995 */
14996 static void dateFunc(
14997   sqlite3_context *context,
14998   int argc,
14999   sqlite3_value **argv
15000 ){
15001   DateTime x;
15002   if( isDate(context, argc, argv, &x)==0 ){
15003     char zBuf[100];
15004     computeYMD(&x);
15005     sqlite3_snprintf(sizeof(zBuf), zBuf, "%04d-%02d-%02d", x.Y, x.M, x.D);
15006     sqlite3_result_text(context, zBuf, -1, SQLITE_TRANSIENT);
15007   }
15008 }
15009 
15010 /*
15011 **    strftime( FORMAT, TIMESTRING, MOD, MOD, ...)
15012 **
15013 ** Return a string described by FORMAT.  Conversions as follows:
15014 **
15015 **   %d  day of month
15016 **   %f  ** fractional seconds  SS.SSS
15017 **   %H  hour 00-24
15018 **   %j  day of year 000-366
15019 **   %J  ** Julian day number
15020 **   %m  month 01-12
15021 **   %M  minute 00-59
15022 **   %s  seconds since 1970-01-01
15023 **   %S  seconds 00-59
15024 **   %w  day of week 0-6  sunday==0
15025 **   %W  week of year 00-53
15026 **   %Y  year 0000-9999
15027 **   %%  %
15028 */
15029 static void strftimeFunc(
15030   sqlite3_context *context,
15031   int argc,
15032   sqlite3_value **argv
15033 ){
15034   DateTime x;
15035   u64 n;
15036   size_t i,j;
15037   char *z;
15038   sqlite3 *db;
15039   const char *zFmt = (const char*)sqlite3_value_text(argv[0]);
15040   char zBuf[100];
15041   if( zFmt==0 || isDate(context, argc-1, argv+1, &x) ) return;
15042   db = sqlite3_context_db_handle(context);
15043   for(i=0, n=1; zFmt[i]; i++, n++){
15044     if( zFmt[i]=='%' ){
15045       switch( zFmt[i+1] ){
15046         case 'd':
15047         case 'H':
15048         case 'm':
15049         case 'M':
15050         case 'S':
15051         case 'W':
15052           n++;
15053           /* fall thru */
15054         case 'w':
15055         case '%':
15056           break;
15057         case 'f':
15058           n += 8;
15059           break;
15060         case 'j':
15061           n += 3;
15062           break;
15063         case 'Y':
15064           n += 8;
15065           break;
15066         case 's':
15067         case 'J':
15068           n += 50;
15069           break;
15070         default:
15071           return;  /* ERROR.  return a NULL */
15072       }
15073       i++;
15074     }
15075   }
15076   testcase( n==sizeof(zBuf)-1 );
15077   testcase( n==sizeof(zBuf) );
15078   testcase( n==(u64)db->aLimit[SQLITE_LIMIT_LENGTH]+1 );
15079   testcase( n==(u64)db->aLimit[SQLITE_LIMIT_LENGTH] );
15080   if( n<sizeof(zBuf) ){
15081     z = zBuf;
15082   }else if( n>(u64)db->aLimit[SQLITE_LIMIT_LENGTH] ){
15083     sqlite3_result_error_toobig(context);
15084     return;
15085   }else{
15086     z = sqlite3DbMallocRaw(db, (int)n);
15087     if( z==0 ){
15088       sqlite3_result_error_nomem(context);
15089       return;
15090     }
15091   }
15092   computeJD(&x);
15093   computeYMD_HMS(&x);
15094   for(i=j=0; zFmt[i]; i++){
15095     if( zFmt[i]!='%' ){
15096       z[j++] = zFmt[i];
15097     }else{
15098       i++;
15099       switch( zFmt[i] ){
15100         case 'd':  sqlite3_snprintf(3, &z[j],"%02d",x.D); j+=2; break;
15101         case 'f': {
15102           double s = x.s;
15103           if( s>59.999 ) s = 59.999;
15104           sqlite3_snprintf(7, &z[j],"%06.3f", s);
15105           j += sqlite3Strlen30(&z[j]);
15106           break;
15107         }
15108         case 'H':  sqlite3_snprintf(3, &z[j],"%02d",x.h); j+=2; break;
15109         case 'W': /* Fall thru */
15110         case 'j': {
15111           int nDay;             /* Number of days since 1st day of year */
15112           DateTime y = x;
15113           y.validJD = 0;
15114           y.M = 1;
15115           y.D = 1;
15116           computeJD(&y);
15117           nDay = (int)((x.iJD-y.iJD+43200000)/86400000);
15118           if( zFmt[i]=='W' ){
15119             int wd;   /* 0=Monday, 1=Tuesday, ... 6=Sunday */
15120             wd = (int)(((x.iJD+43200000)/86400000)%7);
15121             sqlite3_snprintf(3, &z[j],"%02d",(nDay+7-wd)/7);
15122             j += 2;
15123           }else{
15124             sqlite3_snprintf(4, &z[j],"%03d",nDay+1);
15125             j += 3;
15126           }
15127           break;
15128         }
15129         case 'J': {
15130           sqlite3_snprintf(20, &z[j],"%.16g",x.iJD/86400000.0);
15131           j+=sqlite3Strlen30(&z[j]);
15132           break;
15133         }
15134         case 'm':  sqlite3_snprintf(3, &z[j],"%02d",x.M); j+=2; break;
15135         case 'M':  sqlite3_snprintf(3, &z[j],"%02d",x.m); j+=2; break;
15136         case 's': {
15137           sqlite3_snprintf(30,&z[j],"%lld",
15138                            (i64)(x.iJD/1000 - 21086676*(i64)10000));
15139           j += sqlite3Strlen30(&z[j]);
15140           break;
15141         }
15142         case 'S':  sqlite3_snprintf(3,&z[j],"%02d",(int)x.s); j+=2; break;
15143         case 'w': {
15144           z[j++] = (char)(((x.iJD+129600000)/86400000) % 7) + '0';
15145           break;
15146         }
15147         case 'Y': {
15148           sqlite3_snprintf(5,&z[j],"%04d",x.Y); j+=sqlite3Strlen30(&z[j]);
15149           break;
15150         }
15151         default:   z[j++] = '%'; break;
15152       }
15153     }
15154   }
15155   z[j] = 0;
15156   sqlite3_result_text(context, z, -1,
15157                       z==zBuf ? SQLITE_TRANSIENT : SQLITE_DYNAMIC);
15158 }
15159 
15160 /*
15161 ** current_time()
15162 **
15163 ** This function returns the same value as time('now').
15164 */
15165 static void ctimeFunc(
15166   sqlite3_context *context,
15167   int NotUsed,
15168   sqlite3_value **NotUsed2
15169 ){
15170   UNUSED_PARAMETER2(NotUsed, NotUsed2);
15171   timeFunc(context, 0, 0);
15172 }
15173 
15174 /*
15175 ** current_date()
15176 **
15177 ** This function returns the same value as date('now').
15178 */
15179 static void cdateFunc(
15180   sqlite3_context *context,
15181   int NotUsed,
15182   sqlite3_value **NotUsed2
15183 ){
15184   UNUSED_PARAMETER2(NotUsed, NotUsed2);
15185   dateFunc(context, 0, 0);
15186 }
15187 
15188 /*
15189 ** current_timestamp()
15190 **
15191 ** This function returns the same value as datetime('now').
15192 */
15193 static void ctimestampFunc(
15194   sqlite3_context *context,
15195   int NotUsed,
15196   sqlite3_value **NotUsed2
15197 ){
15198   UNUSED_PARAMETER2(NotUsed, NotUsed2);
15199   datetimeFunc(context, 0, 0);
15200 }
15201 #endif /* !defined(SQLITE_OMIT_DATETIME_FUNCS) */
15202 
15203 #ifdef SQLITE_OMIT_DATETIME_FUNCS
15204 /*
15205 ** If the library is compiled to omit the full-scale date and time
15206 ** handling (to get a smaller binary), the following minimal version
15207 ** of the functions current_time(), current_date() and current_timestamp()
15208 ** are included instead. This is to support column declarations that
15209 ** include "DEFAULT CURRENT_TIME" etc.
15210 **
15211 ** This function uses the C-library functions time(), gmtime()
15212 ** and strftime(). The format string to pass to strftime() is supplied
15213 ** as the user-data for the function.
15214 */
15215 static void currentTimeFunc(
15216   sqlite3_context *context,
15217   int argc,
15218   sqlite3_value **argv
15219 ){
15220   time_t t;
15221   char *zFormat = (char *)sqlite3_user_data(context);
15222   sqlite3 *db;
15223   sqlite3_int64 iT;
15224   struct tm *pTm;
15225   struct tm sNow;
15226   char zBuf[20];
15227 
15228   UNUSED_PARAMETER(argc);
15229   UNUSED_PARAMETER(argv);
15230 
15231   iT = sqlite3StmtCurrentTime(context);
15232   if( iT<=0 ) return;
15233   t = iT/1000 - 10000*(sqlite3_int64)21086676;
15234 #ifdef HAVE_GMTIME_R
15235   pTm = gmtime_r(&t, &sNow);
15236 #else
15237   sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
15238   pTm = gmtime(&t);
15239   if( pTm ) memcpy(&sNow, pTm, sizeof(sNow));
15240   sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
15241 #endif
15242   if( pTm ){
15243     strftime(zBuf, 20, zFormat, &sNow);
15244     sqlite3_result_text(context, zBuf, -1, SQLITE_TRANSIENT);
15245   }
15246 }
15247 #endif
15248 
15249 /*
15250 ** This function registered all of the above C functions as SQL
15251 ** functions.  This should be the only routine in this file with
15252 ** external linkage.
15253 */
15254 SQLITE_PRIVATE void sqlite3RegisterDateTimeFunctions(void){
15255   static SQLITE_WSD FuncDef aDateTimeFuncs[] = {
15256 #ifndef SQLITE_OMIT_DATETIME_FUNCS
15257     FUNCTION(julianday,        -1, 0, 0, juliandayFunc ),
15258     FUNCTION(date,             -1, 0, 0, dateFunc      ),
15259     FUNCTION(time,             -1, 0, 0, timeFunc      ),
15260     FUNCTION(datetime,         -1, 0, 0, datetimeFunc  ),
15261     FUNCTION(strftime,         -1, 0, 0, strftimeFunc  ),
15262     FUNCTION(current_time,      0, 0, 0, ctimeFunc     ),
15263     FUNCTION(current_timestamp, 0, 0, 0, ctimestampFunc),
15264     FUNCTION(current_date,      0, 0, 0, cdateFunc     ),
15265 #else
15266     STR_FUNCTION(current_time,      0, "%H:%M:%S",          0, currentTimeFunc),
15267     STR_FUNCTION(current_date,      0, "%Y-%m-%d",          0, currentTimeFunc),
15268     STR_FUNCTION(current_timestamp, 0, "%Y-%m-%d %H:%M:%S", 0, currentTimeFunc),
15269 #endif
15270   };
15271   int i;
15272   FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
15273   FuncDef *aFunc = (FuncDef*)&GLOBAL(FuncDef, aDateTimeFuncs);
15274 
15275   for(i=0; i<ArraySize(aDateTimeFuncs); i++){
15276     sqlite3FuncDefInsert(pHash, &aFunc[i]);
15277   }
15278 }
15279 
15280 /************** End of date.c ************************************************/
15281 /************** Begin file os.c **********************************************/
15282 /*
15283 ** 2005 November 29
15284 **
15285 ** The author disclaims copyright to this source code.  In place of
15286 ** a legal notice, here is a blessing:
15287 **
15288 **    May you do good and not evil.
15289 **    May you find forgiveness for yourself and forgive others.
15290 **    May you share freely, never taking more than you give.
15291 **
15292 ******************************************************************************
15293 **
15294 ** This file contains OS interface code that is common to all
15295 ** architectures.
15296 */
15297 #define _SQLITE_OS_C_ 1
15298 #undef _SQLITE_OS_C_
15299 
15300 /*
15301 ** The default SQLite sqlite3_vfs implementations do not allocate
15302 ** memory (actually, os_unix.c allocates a small amount of memory
15303 ** from within OsOpen()), but some third-party implementations may.
15304 ** So we test the effects of a malloc() failing and the sqlite3OsXXX()
15305 ** function returning SQLITE_IOERR_NOMEM using the DO_OS_MALLOC_TEST macro.
15306 **
15307 ** The following functions are instrumented for malloc() failure 
15308 ** testing:
15309 **
15310 **     sqlite3OsRead()
15311 **     sqlite3OsWrite()
15312 **     sqlite3OsSync()
15313 **     sqlite3OsFileSize()
15314 **     sqlite3OsLock()
15315 **     sqlite3OsCheckReservedLock()
15316 **     sqlite3OsFileControl()
15317 **     sqlite3OsShmMap()
15318 **     sqlite3OsOpen()
15319 **     sqlite3OsDelete()
15320 **     sqlite3OsAccess()
15321 **     sqlite3OsFullPathname()
15322 **
15323 */
15324 #if defined(SQLITE_TEST)
15325 SQLITE_API int sqlite3_memdebug_vfs_oom_test = 1;
15326   #define DO_OS_MALLOC_TEST(x)                                       \
15327   if (sqlite3_memdebug_vfs_oom_test && (!x || !sqlite3IsMemJournal(x))) {  \
15328     void *pTstAlloc = sqlite3Malloc(10);                             \
15329     if (!pTstAlloc) return SQLITE_IOERR_NOMEM;                       \
15330     sqlite3_free(pTstAlloc);                                         \
15331   }
15332 #else
15333   #define DO_OS_MALLOC_TEST(x)
15334 #endif
15335 
15336 /*
15337 ** The following routines are convenience wrappers around methods
15338 ** of the sqlite3_file object.  This is mostly just syntactic sugar. All
15339 ** of this would be completely automatic if SQLite were coded using
15340 ** C++ instead of plain old C.
15341 */
15342 SQLITE_PRIVATE int sqlite3OsClose(sqlite3_file *pId){
15343   int rc = SQLITE_OK;
15344   if( pId->pMethods ){
15345     rc = pId->pMethods->xClose(pId);
15346     pId->pMethods = 0;
15347   }
15348   return rc;
15349 }
15350 SQLITE_PRIVATE int sqlite3OsRead(sqlite3_file *id, void *pBuf, int amt, i64 offset){
15351   DO_OS_MALLOC_TEST(id);
15352   return id->pMethods->xRead(id, pBuf, amt, offset);
15353 }
15354 SQLITE_PRIVATE int sqlite3OsWrite(sqlite3_file *id, const void *pBuf, int amt, i64 offset){
15355   DO_OS_MALLOC_TEST(id);
15356   return id->pMethods->xWrite(id, pBuf, amt, offset);
15357 }
15358 SQLITE_PRIVATE int sqlite3OsTruncate(sqlite3_file *id, i64 size){
15359   return id->pMethods->xTruncate(id, size);
15360 }
15361 SQLITE_PRIVATE int sqlite3OsSync(sqlite3_file *id, int flags){
15362   DO_OS_MALLOC_TEST(id);
15363   return id->pMethods->xSync(id, flags);
15364 }
15365 SQLITE_PRIVATE int sqlite3OsFileSize(sqlite3_file *id, i64 *pSize){
15366   DO_OS_MALLOC_TEST(id);
15367   return id->pMethods->xFileSize(id, pSize);
15368 }
15369 SQLITE_PRIVATE int sqlite3OsLock(sqlite3_file *id, int lockType){
15370   DO_OS_MALLOC_TEST(id);
15371   return id->pMethods->xLock(id, lockType);
15372 }
15373 SQLITE_PRIVATE int sqlite3OsUnlock(sqlite3_file *id, int lockType){
15374   return id->pMethods->xUnlock(id, lockType);
15375 }
15376 SQLITE_PRIVATE int sqlite3OsCheckReservedLock(sqlite3_file *id, int *pResOut){
15377   DO_OS_MALLOC_TEST(id);
15378   return id->pMethods->xCheckReservedLock(id, pResOut);
15379 }
15380 
15381 /*
15382 ** Use sqlite3OsFileControl() when we are doing something that might fail
15383 ** and we need to know about the failures.  Use sqlite3OsFileControlHint()
15384 ** when simply tossing information over the wall to the VFS and we do not
15385 ** really care if the VFS receives and understands the information since it
15386 ** is only a hint and can be safely ignored.  The sqlite3OsFileControlHint()
15387 ** routine has no return value since the return value would be meaningless.
15388 */
15389 SQLITE_PRIVATE int sqlite3OsFileControl(sqlite3_file *id, int op, void *pArg){
15390   DO_OS_MALLOC_TEST(id);
15391   return id->pMethods->xFileControl(id, op, pArg);
15392 }
15393 SQLITE_PRIVATE void sqlite3OsFileControlHint(sqlite3_file *id, int op, void *pArg){
15394   (void)id->pMethods->xFileControl(id, op, pArg);
15395 }
15396 
15397 SQLITE_PRIVATE int sqlite3OsSectorSize(sqlite3_file *id){
15398   int (*xSectorSize)(sqlite3_file*) = id->pMethods->xSectorSize;
15399   return (xSectorSize ? xSectorSize(id) : SQLITE_DEFAULT_SECTOR_SIZE);
15400 }
15401 SQLITE_PRIVATE int sqlite3OsDeviceCharacteristics(sqlite3_file *id){
15402   return id->pMethods->xDeviceCharacteristics(id);
15403 }
15404 SQLITE_PRIVATE int sqlite3OsShmLock(sqlite3_file *id, int offset, int n, int flags){
15405   return id->pMethods->xShmLock(id, offset, n, flags);
15406 }
15407 SQLITE_PRIVATE void sqlite3OsShmBarrier(sqlite3_file *id){
15408   id->pMethods->xShmBarrier(id);
15409 }
15410 SQLITE_PRIVATE int sqlite3OsShmUnmap(sqlite3_file *id, int deleteFlag){
15411   return id->pMethods->xShmUnmap(id, deleteFlag);
15412 }
15413 SQLITE_PRIVATE int sqlite3OsShmMap(
15414   sqlite3_file *id,               /* Database file handle */
15415   int iPage,
15416   int pgsz,
15417   int bExtend,                    /* True to extend file if necessary */
15418   void volatile **pp              /* OUT: Pointer to mapping */
15419 ){
15420   DO_OS_MALLOC_TEST(id);
15421   return id->pMethods->xShmMap(id, iPage, pgsz, bExtend, pp);
15422 }
15423 
15424 #if SQLITE_MAX_MMAP_SIZE>0
15425 /* The real implementation of xFetch and xUnfetch */
15426 SQLITE_PRIVATE int sqlite3OsFetch(sqlite3_file *id, i64 iOff, int iAmt, void **pp){
15427   DO_OS_MALLOC_TEST(id);
15428   return id->pMethods->xFetch(id, iOff, iAmt, pp);
15429 }
15430 SQLITE_PRIVATE int sqlite3OsUnfetch(sqlite3_file *id, i64 iOff, void *p){
15431   return id->pMethods->xUnfetch(id, iOff, p);
15432 }
15433 #else
15434 /* No-op stubs to use when memory-mapped I/O is disabled */
15435 SQLITE_PRIVATE int sqlite3OsFetch(sqlite3_file *id, i64 iOff, int iAmt, void **pp){
15436   *pp = 0;
15437   return SQLITE_OK;
15438 }
15439 SQLITE_PRIVATE int sqlite3OsUnfetch(sqlite3_file *id, i64 iOff, void *p){
15440   return SQLITE_OK;
15441 }
15442 #endif
15443 
15444 /*
15445 ** The next group of routines are convenience wrappers around the
15446 ** VFS methods.
15447 */
15448 SQLITE_PRIVATE int sqlite3OsOpen(
15449   sqlite3_vfs *pVfs, 
15450   const char *zPath, 
15451   sqlite3_file *pFile, 
15452   int flags, 
15453   int *pFlagsOut
15454 ){
15455   int rc;
15456   DO_OS_MALLOC_TEST(0);
15457   /* 0x87f7f is a mask of SQLITE_OPEN_ flags that are valid to be passed
15458   ** down into the VFS layer.  Some SQLITE_OPEN_ flags (for example,
15459   ** SQLITE_OPEN_FULLMUTEX or SQLITE_OPEN_SHAREDCACHE) are blocked before
15460   ** reaching the VFS. */
15461   rc = pVfs->xOpen(pVfs, zPath, pFile, flags & 0x87f7f, pFlagsOut);
15462   assert( rc==SQLITE_OK || pFile->pMethods==0 );
15463   return rc;
15464 }
15465 SQLITE_PRIVATE int sqlite3OsDelete(sqlite3_vfs *pVfs, const char *zPath, int dirSync){
15466   DO_OS_MALLOC_TEST(0);
15467   assert( dirSync==0 || dirSync==1 );
15468   return pVfs->xDelete(pVfs, zPath, dirSync);
15469 }
15470 SQLITE_PRIVATE int sqlite3OsAccess(
15471   sqlite3_vfs *pVfs, 
15472   const char *zPath, 
15473   int flags, 
15474   int *pResOut
15475 ){
15476   DO_OS_MALLOC_TEST(0);
15477   return pVfs->xAccess(pVfs, zPath, flags, pResOut);
15478 }
15479 SQLITE_PRIVATE int sqlite3OsFullPathname(
15480   sqlite3_vfs *pVfs, 
15481   const char *zPath, 
15482   int nPathOut, 
15483   char *zPathOut
15484 ){
15485   DO_OS_MALLOC_TEST(0);
15486   zPathOut[0] = 0;
15487   return pVfs->xFullPathname(pVfs, zPath, nPathOut, zPathOut);
15488 }
15489 #ifndef SQLITE_OMIT_LOAD_EXTENSION
15490 SQLITE_PRIVATE void *sqlite3OsDlOpen(sqlite3_vfs *pVfs, const char *zPath){
15491   return pVfs->xDlOpen(pVfs, zPath);
15492 }
15493 SQLITE_PRIVATE void sqlite3OsDlError(sqlite3_vfs *pVfs, int nByte, char *zBufOut){
15494   pVfs->xDlError(pVfs, nByte, zBufOut);
15495 }
15496 SQLITE_PRIVATE void (*sqlite3OsDlSym(sqlite3_vfs *pVfs, void *pHdle, const char *zSym))(void){
15497   return pVfs->xDlSym(pVfs, pHdle, zSym);
15498 }
15499 SQLITE_PRIVATE void sqlite3OsDlClose(sqlite3_vfs *pVfs, void *pHandle){
15500   pVfs->xDlClose(pVfs, pHandle);
15501 }
15502 #endif /* SQLITE_OMIT_LOAD_EXTENSION */
15503 SQLITE_PRIVATE int sqlite3OsRandomness(sqlite3_vfs *pVfs, int nByte, char *zBufOut){
15504   return pVfs->xRandomness(pVfs, nByte, zBufOut);
15505 }
15506 SQLITE_PRIVATE int sqlite3OsSleep(sqlite3_vfs *pVfs, int nMicro){
15507   return pVfs->xSleep(pVfs, nMicro);
15508 }
15509 SQLITE_PRIVATE int sqlite3OsCurrentTimeInt64(sqlite3_vfs *pVfs, sqlite3_int64 *pTimeOut){
15510   int rc;
15511   /* IMPLEMENTATION-OF: R-49045-42493 SQLite will use the xCurrentTimeInt64()
15512   ** method to get the current date and time if that method is available
15513   ** (if iVersion is 2 or greater and the function pointer is not NULL) and
15514   ** will fall back to xCurrentTime() if xCurrentTimeInt64() is
15515   ** unavailable.
15516   */
15517   if( pVfs->iVersion>=2 && pVfs->xCurrentTimeInt64 ){
15518     rc = pVfs->xCurrentTimeInt64(pVfs, pTimeOut);
15519   }else{
15520     double r;
15521     rc = pVfs->xCurrentTime(pVfs, &r);
15522     *pTimeOut = (sqlite3_int64)(r*86400000.0);
15523   }
15524   return rc;
15525 }
15526 
15527 SQLITE_PRIVATE int sqlite3OsOpenMalloc(
15528   sqlite3_vfs *pVfs, 
15529   const char *zFile, 
15530   sqlite3_file **ppFile, 
15531   int flags,
15532   int *pOutFlags
15533 ){
15534   int rc = SQLITE_NOMEM;
15535   sqlite3_file *pFile;
15536   pFile = (sqlite3_file *)sqlite3MallocZero(pVfs->szOsFile);
15537   if( pFile ){
15538     rc = sqlite3OsOpen(pVfs, zFile, pFile, flags, pOutFlags);
15539     if( rc!=SQLITE_OK ){
15540       sqlite3_free(pFile);
15541     }else{
15542       *ppFile = pFile;
15543     }
15544   }
15545   return rc;
15546 }
15547 SQLITE_PRIVATE int sqlite3OsCloseFree(sqlite3_file *pFile){
15548   int rc = SQLITE_OK;
15549   assert( pFile );
15550   rc = sqlite3OsClose(pFile);
15551   sqlite3_free(pFile);
15552   return rc;
15553 }
15554 
15555 /*
15556 ** This function is a wrapper around the OS specific implementation of
15557 ** sqlite3_os_init(). The purpose of the wrapper is to provide the
15558 ** ability to simulate a malloc failure, so that the handling of an
15559 ** error in sqlite3_os_init() by the upper layers can be tested.
15560 */
15561 SQLITE_PRIVATE int sqlite3OsInit(void){
15562   void *p = sqlite3_malloc(10);
15563   if( p==0 ) return SQLITE_NOMEM;
15564   sqlite3_free(p);
15565   return sqlite3_os_init();
15566 }
15567 
15568 /*
15569 ** The list of all registered VFS implementations.
15570 */
15571 static sqlite3_vfs * SQLITE_WSD vfsList = 0;
15572 #define vfsList GLOBAL(sqlite3_vfs *, vfsList)
15573 
15574 /*
15575 ** Locate a VFS by name.  If no name is given, simply return the
15576 ** first VFS on the list.
15577 */
15578 SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfs){
15579   sqlite3_vfs *pVfs = 0;
15580 #if SQLITE_THREADSAFE
15581   sqlite3_mutex *mutex;
15582 #endif
15583 #ifndef SQLITE_OMIT_AUTOINIT
15584   int rc = sqlite3_initialize();
15585   if( rc ) return 0;
15586 #endif
15587 #if SQLITE_THREADSAFE
15588   mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
15589 #endif
15590   sqlite3_mutex_enter(mutex);
15591   for(pVfs = vfsList; pVfs; pVfs=pVfs->pNext){
15592     if( zVfs==0 ) break;
15593     if( strcmp(zVfs, pVfs->zName)==0 ) break;
15594   }
15595   sqlite3_mutex_leave(mutex);
15596   return pVfs;
15597 }
15598 
15599 /*
15600 ** Unlink a VFS from the linked list
15601 */
15602 static void vfsUnlink(sqlite3_vfs *pVfs){
15603   assert( sqlite3_mutex_held(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)) );
15604   if( pVfs==0 ){
15605     /* No-op */
15606   }else if( vfsList==pVfs ){
15607     vfsList = pVfs->pNext;
15608   }else if( vfsList ){
15609     sqlite3_vfs *p = vfsList;
15610     while( p->pNext && p->pNext!=pVfs ){
15611       p = p->pNext;
15612     }
15613     if( p->pNext==pVfs ){
15614       p->pNext = pVfs->pNext;
15615     }
15616   }
15617 }
15618 
15619 /*
15620 ** Register a VFS with the system.  It is harmless to register the same
15621 ** VFS multiple times.  The new VFS becomes the default if makeDflt is
15622 ** true.
15623 */
15624 SQLITE_API int sqlite3_vfs_register(sqlite3_vfs *pVfs, int makeDflt){
15625   MUTEX_LOGIC(sqlite3_mutex *mutex;)
15626 #ifndef SQLITE_OMIT_AUTOINIT
15627   int rc = sqlite3_initialize();
15628   if( rc ) return rc;
15629 #endif
15630   MUTEX_LOGIC( mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); )
15631   sqlite3_mutex_enter(mutex);
15632   vfsUnlink(pVfs);
15633   if( makeDflt || vfsList==0 ){
15634     pVfs->pNext = vfsList;
15635     vfsList = pVfs;
15636   }else{
15637     pVfs->pNext = vfsList->pNext;
15638     vfsList->pNext = pVfs;
15639   }
15640   assert(vfsList);
15641   sqlite3_mutex_leave(mutex);
15642   return SQLITE_OK;
15643 }
15644 
15645 /*
15646 ** Unregister a VFS so that it is no longer accessible.
15647 */
15648 SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs *pVfs){
15649 #if SQLITE_THREADSAFE
15650   sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
15651 #endif
15652   sqlite3_mutex_enter(mutex);
15653   vfsUnlink(pVfs);
15654   sqlite3_mutex_leave(mutex);
15655   return SQLITE_OK;
15656 }
15657 
15658 /************** End of os.c **************************************************/
15659 /************** Begin file fault.c *******************************************/
15660 /*
15661 ** 2008 Jan 22
15662 **
15663 ** The author disclaims copyright to this source code.  In place of
15664 ** a legal notice, here is a blessing:
15665 **
15666 **    May you do good and not evil.
15667 **    May you find forgiveness for yourself and forgive others.
15668 **    May you share freely, never taking more than you give.
15669 **
15670 *************************************************************************
15671 **
15672 ** This file contains code to support the concept of "benign" 
15673 ** malloc failures (when the xMalloc() or xRealloc() method of the
15674 ** sqlite3_mem_methods structure fails to allocate a block of memory
15675 ** and returns 0). 
15676 **
15677 ** Most malloc failures are non-benign. After they occur, SQLite
15678 ** abandons the current operation and returns an error code (usually
15679 ** SQLITE_NOMEM) to the user. However, sometimes a fault is not necessarily
15680 ** fatal. For example, if a malloc fails while resizing a hash table, this 
15681 ** is completely recoverable simply by not carrying out the resize. The 
15682 ** hash table will continue to function normally.  So a malloc failure 
15683 ** during a hash table resize is a benign fault.
15684 */
15685 
15686 
15687 #ifndef SQLITE_OMIT_BUILTIN_TEST
15688 
15689 /*
15690 ** Global variables.
15691 */
15692 typedef struct BenignMallocHooks BenignMallocHooks;
15693 static SQLITE_WSD struct BenignMallocHooks {
15694   void (*xBenignBegin)(void);
15695   void (*xBenignEnd)(void);
15696 } sqlite3Hooks = { 0, 0 };
15697 
15698 /* The "wsdHooks" macro will resolve to the appropriate BenignMallocHooks
15699 ** structure.  If writable static data is unsupported on the target,
15700 ** we have to locate the state vector at run-time.  In the more common
15701 ** case where writable static data is supported, wsdHooks can refer directly
15702 ** to the "sqlite3Hooks" state vector declared above.
15703 */
15704 #ifdef SQLITE_OMIT_WSD
15705 # define wsdHooksInit \
15706   BenignMallocHooks *x = &GLOBAL(BenignMallocHooks,sqlite3Hooks)
15707 # define wsdHooks x[0]
15708 #else
15709 # define wsdHooksInit
15710 # define wsdHooks sqlite3Hooks
15711 #endif
15712 
15713 
15714 /*
15715 ** Register hooks to call when sqlite3BeginBenignMalloc() and
15716 ** sqlite3EndBenignMalloc() are called, respectively.
15717 */
15718 SQLITE_PRIVATE void sqlite3BenignMallocHooks(
15719   void (*xBenignBegin)(void),
15720   void (*xBenignEnd)(void)
15721 ){
15722   wsdHooksInit;
15723   wsdHooks.xBenignBegin = xBenignBegin;
15724   wsdHooks.xBenignEnd = xBenignEnd;
15725 }
15726 
15727 /*
15728 ** This (sqlite3EndBenignMalloc()) is called by SQLite code to indicate that
15729 ** subsequent malloc failures are benign. A call to sqlite3EndBenignMalloc()
15730 ** indicates that subsequent malloc failures are non-benign.
15731 */
15732 SQLITE_PRIVATE void sqlite3BeginBenignMalloc(void){
15733   wsdHooksInit;
15734   if( wsdHooks.xBenignBegin ){
15735     wsdHooks.xBenignBegin();
15736   }
15737 }
15738 SQLITE_PRIVATE void sqlite3EndBenignMalloc(void){
15739   wsdHooksInit;
15740   if( wsdHooks.xBenignEnd ){
15741     wsdHooks.xBenignEnd();
15742   }
15743 }
15744 
15745 #endif   /* #ifndef SQLITE_OMIT_BUILTIN_TEST */
15746 
15747 /************** End of fault.c ***********************************************/
15748 /************** Begin file mem0.c ********************************************/
15749 /*
15750 ** 2008 October 28
15751 **
15752 ** The author disclaims copyright to this source code.  In place of
15753 ** a legal notice, here is a blessing:
15754 **
15755 **    May you do good and not evil.
15756 **    May you find forgiveness for yourself and forgive others.
15757 **    May you share freely, never taking more than you give.
15758 **
15759 *************************************************************************
15760 **
15761 ** This file contains a no-op memory allocation drivers for use when
15762 ** SQLITE_ZERO_MALLOC is defined.  The allocation drivers implemented
15763 ** here always fail.  SQLite will not operate with these drivers.  These
15764 ** are merely placeholders.  Real drivers must be substituted using
15765 ** sqlite3_config() before SQLite will operate.
15766 */
15767 
15768 /*
15769 ** This version of the memory allocator is the default.  It is
15770 ** used when no other memory allocator is specified using compile-time
15771 ** macros.
15772 */
15773 #ifdef SQLITE_ZERO_MALLOC
15774 
15775 /*
15776 ** No-op versions of all memory allocation routines
15777 */
15778 static void *sqlite3MemMalloc(int nByte){ return 0; }
15779 static void sqlite3MemFree(void *pPrior){ return; }
15780 static void *sqlite3MemRealloc(void *pPrior, int nByte){ return 0; }
15781 static int sqlite3MemSize(void *pPrior){ return 0; }
15782 static int sqlite3MemRoundup(int n){ return n; }
15783 static int sqlite3MemInit(void *NotUsed){ return SQLITE_OK; }
15784 static void sqlite3MemShutdown(void *NotUsed){ return; }
15785 
15786 /*
15787 ** This routine is the only routine in this file with external linkage.
15788 **
15789 ** Populate the low-level memory allocation function pointers in
15790 ** sqlite3GlobalConfig.m with pointers to the routines in this file.
15791 */
15792 SQLITE_PRIVATE void sqlite3MemSetDefault(void){
15793   static const sqlite3_mem_methods defaultMethods = {
15794      sqlite3MemMalloc,
15795      sqlite3MemFree,
15796      sqlite3MemRealloc,
15797      sqlite3MemSize,
15798      sqlite3MemRoundup,
15799      sqlite3MemInit,
15800      sqlite3MemShutdown,
15801      0
15802   };
15803   sqlite3_config(SQLITE_CONFIG_MALLOC, &defaultMethods);
15804 }
15805 
15806 #endif /* SQLITE_ZERO_MALLOC */
15807 
15808 /************** End of mem0.c ************************************************/
15809 /************** Begin file mem1.c ********************************************/
15810 /*
15811 ** 2007 August 14
15812 **
15813 ** The author disclaims copyright to this source code.  In place of
15814 ** a legal notice, here is a blessing:
15815 **
15816 **    May you do good and not evil.
15817 **    May you find forgiveness for yourself and forgive others.
15818 **    May you share freely, never taking more than you give.
15819 **
15820 *************************************************************************
15821 **
15822 ** This file contains low-level memory allocation drivers for when
15823 ** SQLite will use the standard C-library malloc/realloc/free interface
15824 ** to obtain the memory it needs.
15825 **
15826 ** This file contains implementations of the low-level memory allocation
15827 ** routines specified in the sqlite3_mem_methods object.  The content of
15828 ** this file is only used if SQLITE_SYSTEM_MALLOC is defined.  The
15829 ** SQLITE_SYSTEM_MALLOC macro is defined automatically if neither the
15830 ** SQLITE_MEMDEBUG nor the SQLITE_WIN32_MALLOC macros are defined.  The
15831 ** default configuration is to use memory allocation routines in this
15832 ** file.
15833 **
15834 ** C-preprocessor macro summary:
15835 **
15836 **    HAVE_MALLOC_USABLE_SIZE     The configure script sets this symbol if
15837 **                                the malloc_usable_size() interface exists
15838 **                                on the target platform.  Or, this symbol
15839 **                                can be set manually, if desired.
15840 **                                If an equivalent interface exists by
15841 **                                a different name, using a separate -D
15842 **                                option to rename it.
15843 **
15844 **    SQLITE_WITHOUT_ZONEMALLOC   Some older macs lack support for the zone
15845 **                                memory allocator.  Set this symbol to enable
15846 **                                building on older macs.
15847 **
15848 **    SQLITE_WITHOUT_MSIZE        Set this symbol to disable the use of
15849 **                                _msize() on windows systems.  This might
15850 **                                be necessary when compiling for Delphi,
15851 **                                for example.
15852 */
15853 
15854 /*
15855 ** This version of the memory allocator is the default.  It is
15856 ** used when no other memory allocator is specified using compile-time
15857 ** macros.
15858 */
15859 #ifdef SQLITE_SYSTEM_MALLOC
15860 #if defined(__APPLE__) && !defined(SQLITE_WITHOUT_ZONEMALLOC)
15861 
15862 /*
15863 ** Use the zone allocator available on apple products unless the
15864 ** SQLITE_WITHOUT_ZONEMALLOC symbol is defined.
15865 */
15866 #include <sys/sysctl.h>
15867 #include <malloc/malloc.h>
15868 #include <libkern/OSAtomic.h>
15869 static malloc_zone_t* _sqliteZone_;
15870 #define SQLITE_MALLOC(x) malloc_zone_malloc(_sqliteZone_, (x))
15871 #define SQLITE_FREE(x) malloc_zone_free(_sqliteZone_, (x));
15872 #define SQLITE_REALLOC(x,y) malloc_zone_realloc(_sqliteZone_, (x), (y))
15873 #define SQLITE_MALLOCSIZE(x) \
15874         (_sqliteZone_ ? _sqliteZone_->size(_sqliteZone_,x) : malloc_size(x))
15875 
15876 #else /* if not __APPLE__ */
15877 
15878 /*
15879 ** Use standard C library malloc and free on non-Apple systems.  
15880 ** Also used by Apple systems if SQLITE_WITHOUT_ZONEMALLOC is defined.
15881 */
15882 #define SQLITE_MALLOC(x)             malloc(x)
15883 #define SQLITE_FREE(x)               free(x)
15884 #define SQLITE_REALLOC(x,y)          realloc((x),(y))
15885 
15886 /*
15887 ** The malloc.h header file is needed for malloc_usable_size() function
15888 ** on some systems (e.g. Linux).
15889 */
15890 #if defined(HAVE_MALLOC_H) && defined(HAVE_MALLOC_USABLE_SIZE)
15891 #  define SQLITE_USE_MALLOC_H
15892 #  define SQLITE_USE_MALLOC_USABLE_SIZE
15893 /*
15894 ** The MSVCRT has malloc_usable_size(), but it is called _msize().  The
15895 ** use of _msize() is automatic, but can be disabled by compiling with
15896 ** -DSQLITE_WITHOUT_MSIZE.  Using the _msize() function also requires
15897 ** the malloc.h header file.
15898 */
15899 #elif defined(_MSC_VER) && !defined(SQLITE_WITHOUT_MSIZE)
15900 #  define SQLITE_USE_MALLOC_H
15901 #  define SQLITE_USE_MSIZE
15902 #endif
15903 
15904 /*
15905 ** Include the malloc.h header file, if necessary.  Also set define macro
15906 ** SQLITE_MALLOCSIZE to the appropriate function name, which is _msize()
15907 ** for MSVC and malloc_usable_size() for most other systems (e.g. Linux).
15908 ** The memory size function can always be overridden manually by defining
15909 ** the macro SQLITE_MALLOCSIZE to the desired function name.
15910 */
15911 #if defined(SQLITE_USE_MALLOC_H)
15912 #  include <malloc.h>
15913 #  if defined(SQLITE_USE_MALLOC_USABLE_SIZE)
15914 #    if !defined(SQLITE_MALLOCSIZE)
15915 #      define SQLITE_MALLOCSIZE(x)   malloc_usable_size(x)
15916 #    endif
15917 #  elif defined(SQLITE_USE_MSIZE)
15918 #    if !defined(SQLITE_MALLOCSIZE)
15919 #      define SQLITE_MALLOCSIZE      _msize
15920 #    endif
15921 #  endif
15922 #endif /* defined(SQLITE_USE_MALLOC_H) */
15923 
15924 #endif /* __APPLE__ or not __APPLE__ */
15925 
15926 /*
15927 ** Like malloc(), but remember the size of the allocation
15928 ** so that we can find it later using sqlite3MemSize().
15929 **
15930 ** For this low-level routine, we are guaranteed that nByte>0 because
15931 ** cases of nByte<=0 will be intercepted and dealt with by higher level
15932 ** routines.
15933 */
15934 static void *sqlite3MemMalloc(int nByte){
15935 #ifdef SQLITE_MALLOCSIZE
15936   void *p = SQLITE_MALLOC( nByte );
15937   if( p==0 ){
15938     testcase( sqlite3GlobalConfig.xLog!=0 );
15939     sqlite3_log(SQLITE_NOMEM, "failed to allocate %u bytes of memory", nByte);
15940   }
15941   return p;
15942 #else
15943   sqlite3_int64 *p;
15944   assert( nByte>0 );
15945   nByte = ROUND8(nByte);
15946   p = SQLITE_MALLOC( nByte+8 );
15947   if( p ){
15948     p[0] = nByte;
15949     p++;
15950   }else{
15951     testcase( sqlite3GlobalConfig.xLog!=0 );
15952     sqlite3_log(SQLITE_NOMEM, "failed to allocate %u bytes of memory", nByte);
15953   }
15954   return (void *)p;
15955 #endif
15956 }
15957 
15958 /*
15959 ** Like free() but works for allocations obtained from sqlite3MemMalloc()
15960 ** or sqlite3MemRealloc().
15961 **
15962 ** For this low-level routine, we already know that pPrior!=0 since
15963 ** cases where pPrior==0 will have been intecepted and dealt with
15964 ** by higher-level routines.
15965 */
15966 static void sqlite3MemFree(void *pPrior){
15967 #ifdef SQLITE_MALLOCSIZE
15968   SQLITE_FREE(pPrior);
15969 #else
15970   sqlite3_int64 *p = (sqlite3_int64*)pPrior;
15971   assert( pPrior!=0 );
15972   p--;
15973   SQLITE_FREE(p);
15974 #endif
15975 }
15976 
15977 /*
15978 ** Report the allocated size of a prior return from xMalloc()
15979 ** or xRealloc().
15980 */
15981 static int sqlite3MemSize(void *pPrior){
15982 #ifdef SQLITE_MALLOCSIZE
15983   return pPrior ? (int)SQLITE_MALLOCSIZE(pPrior) : 0;
15984 #else
15985   sqlite3_int64 *p;
15986   if( pPrior==0 ) return 0;
15987   p = (sqlite3_int64*)pPrior;
15988   p--;
15989   return (int)p[0];
15990 #endif
15991 }
15992 
15993 /*
15994 ** Like realloc().  Resize an allocation previously obtained from
15995 ** sqlite3MemMalloc().
15996 **
15997 ** For this low-level interface, we know that pPrior!=0.  Cases where
15998 ** pPrior==0 while have been intercepted by higher-level routine and
15999 ** redirected to xMalloc.  Similarly, we know that nByte>0 becauses
16000 ** cases where nByte<=0 will have been intercepted by higher-level
16001 ** routines and redirected to xFree.
16002 */
16003 static void *sqlite3MemRealloc(void *pPrior, int nByte){
16004 #ifdef SQLITE_MALLOCSIZE
16005   void *p = SQLITE_REALLOC(pPrior, nByte);
16006   if( p==0 ){
16007     testcase( sqlite3GlobalConfig.xLog!=0 );
16008     sqlite3_log(SQLITE_NOMEM,
16009       "failed memory resize %u to %u bytes",
16010       SQLITE_MALLOCSIZE(pPrior), nByte);
16011   }
16012   return p;
16013 #else
16014   sqlite3_int64 *p = (sqlite3_int64*)pPrior;
16015   assert( pPrior!=0 && nByte>0 );
16016   assert( nByte==ROUND8(nByte) ); /* EV: R-46199-30249 */
16017   p--;
16018   p = SQLITE_REALLOC(p, nByte+8 );
16019   if( p ){
16020     p[0] = nByte;
16021     p++;
16022   }else{
16023     testcase( sqlite3GlobalConfig.xLog!=0 );
16024     sqlite3_log(SQLITE_NOMEM,
16025       "failed memory resize %u to %u bytes",
16026       sqlite3MemSize(pPrior), nByte);
16027   }
16028   return (void*)p;
16029 #endif
16030 }
16031 
16032 /*
16033 ** Round up a request size to the next valid allocation size.
16034 */
16035 static int sqlite3MemRoundup(int n){
16036   return ROUND8(n);
16037 }
16038 
16039 /*
16040 ** Initialize this module.
16041 */
16042 static int sqlite3MemInit(void *NotUsed){
16043 #if defined(__APPLE__) && !defined(SQLITE_WITHOUT_ZONEMALLOC)
16044   int cpuCount;
16045   size_t len;
16046   if( _sqliteZone_ ){
16047     return SQLITE_OK;
16048   }
16049   len = sizeof(cpuCount);
16050   /* One usually wants to use hw.acctivecpu for MT decisions, but not here */
16051   sysctlbyname("hw.ncpu", &cpuCount, &len, NULL, 0);
16052   if( cpuCount>1 ){
16053     /* defer MT decisions to system malloc */
16054     _sqliteZone_ = malloc_default_zone();
16055   }else{
16056     /* only 1 core, use our own zone to contention over global locks, 
16057     ** e.g. we have our own dedicated locks */
16058     bool success;
16059     malloc_zone_t* newzone = malloc_create_zone(4096, 0);
16060     malloc_set_zone_name(newzone, "Sqlite_Heap");
16061     do{
16062       success = OSAtomicCompareAndSwapPtrBarrier(NULL, newzone, 
16063                                  (void * volatile *)&_sqliteZone_);
16064     }while(!_sqliteZone_);
16065     if( !success ){
16066       /* somebody registered a zone first */
16067       malloc_destroy_zone(newzone);
16068     }
16069   }
16070 #endif
16071   UNUSED_PARAMETER(NotUsed);
16072   return SQLITE_OK;
16073 }
16074 
16075 /*
16076 ** Deinitialize this module.
16077 */
16078 static void sqlite3MemShutdown(void *NotUsed){
16079   UNUSED_PARAMETER(NotUsed);
16080   return;
16081 }
16082 
16083 /*
16084 ** This routine is the only routine in this file with external linkage.
16085 **
16086 ** Populate the low-level memory allocation function pointers in
16087 ** sqlite3GlobalConfig.m with pointers to the routines in this file.
16088 */
16089 SQLITE_PRIVATE void sqlite3MemSetDefault(void){
16090   static const sqlite3_mem_methods defaultMethods = {
16091      sqlite3MemMalloc,
16092      sqlite3MemFree,
16093      sqlite3MemRealloc,
16094      sqlite3MemSize,
16095      sqlite3MemRoundup,
16096      sqlite3MemInit,
16097      sqlite3MemShutdown,
16098      0
16099   };
16100   sqlite3_config(SQLITE_CONFIG_MALLOC, &defaultMethods);
16101 }
16102 
16103 #endif /* SQLITE_SYSTEM_MALLOC */
16104 
16105 /************** End of mem1.c ************************************************/
16106 /************** Begin file mem2.c ********************************************/
16107 /*
16108 ** 2007 August 15
16109 **
16110 ** The author disclaims copyright to this source code.  In place of
16111 ** a legal notice, here is a blessing:
16112 **
16113 **    May you do good and not evil.
16114 **    May you find forgiveness for yourself and forgive others.
16115 **    May you share freely, never taking more than you give.
16116 **
16117 *************************************************************************
16118 **
16119 ** This file contains low-level memory allocation drivers for when
16120 ** SQLite will use the standard C-library malloc/realloc/free interface
16121 ** to obtain the memory it needs while adding lots of additional debugging
16122 ** information to each allocation in order to help detect and fix memory
16123 ** leaks and memory usage errors.
16124 **
16125 ** This file contains implementations of the low-level memory allocation
16126 ** routines specified in the sqlite3_mem_methods object.
16127 */
16128 
16129 /*
16130 ** This version of the memory allocator is used only if the
16131 ** SQLITE_MEMDEBUG macro is defined
16132 */
16133 #ifdef SQLITE_MEMDEBUG
16134 
16135 /*
16136 ** The backtrace functionality is only available with GLIBC
16137 */
16138 #ifdef __GLIBC__
16139   extern int backtrace(void**,int);
16140   extern void backtrace_symbols_fd(void*const*,int,int);
16141 #else
16142 # define backtrace(A,B) 1
16143 # define backtrace_symbols_fd(A,B,C)
16144 #endif
16145 /* #include <stdio.h> */
16146 
16147 /*
16148 ** Each memory allocation looks like this:
16149 **
16150 **  ------------------------------------------------------------------------
16151 **  | Title |  backtrace pointers |  MemBlockHdr |  allocation |  EndGuard |
16152 **  ------------------------------------------------------------------------
16153 **
16154 ** The application code sees only a pointer to the allocation.  We have
16155 ** to back up from the allocation pointer to find the MemBlockHdr.  The
16156 ** MemBlockHdr tells us the size of the allocation and the number of
16157 ** backtrace pointers.  There is also a guard word at the end of the
16158 ** MemBlockHdr.
16159 */
16160 struct MemBlockHdr {
16161   i64 iSize;                          /* Size of this allocation */
16162   struct MemBlockHdr *pNext, *pPrev;  /* Linked list of all unfreed memory */
16163   char nBacktrace;                    /* Number of backtraces on this alloc */
16164   char nBacktraceSlots;               /* Available backtrace slots */
16165   u8 nTitle;                          /* Bytes of title; includes '\0' */
16166   u8 eType;                           /* Allocation type code */
16167   int iForeGuard;                     /* Guard word for sanity */
16168 };
16169 
16170 /*
16171 ** Guard words
16172 */
16173 #define FOREGUARD 0x80F5E153
16174 #define REARGUARD 0xE4676B53
16175 
16176 /*
16177 ** Number of malloc size increments to track.
16178 */
16179 #define NCSIZE  1000
16180 
16181 /*
16182 ** All of the static variables used by this module are collected
16183 ** into a single structure named "mem".  This is to keep the
16184 ** static variables organized and to reduce namespace pollution
16185 ** when this module is combined with other in the amalgamation.
16186 */
16187 static struct {
16188   
16189   /*
16190   ** Mutex to control access to the memory allocation subsystem.
16191   */
16192   sqlite3_mutex *mutex;
16193 
16194   /*
16195   ** Head and tail of a linked list of all outstanding allocations
16196   */
16197   struct MemBlockHdr *pFirst;
16198   struct MemBlockHdr *pLast;
16199   
16200   /*
16201   ** The number of levels of backtrace to save in new allocations.
16202   */
16203   int nBacktrace;
16204   void (*xBacktrace)(int, int, void **);
16205 
16206   /*
16207   ** Title text to insert in front of each block
16208   */
16209   int nTitle;        /* Bytes of zTitle to save.  Includes '\0' and padding */
16210   char zTitle[100];  /* The title text */
16211 
16212   /* 
16213   ** sqlite3MallocDisallow() increments the following counter.
16214   ** sqlite3MallocAllow() decrements it.
16215   */
16216   int disallow; /* Do not allow memory allocation */
16217 
16218   /*
16219   ** Gather statistics on the sizes of memory allocations.
16220   ** nAlloc[i] is the number of allocation attempts of i*8
16221   ** bytes.  i==NCSIZE is the number of allocation attempts for
16222   ** sizes more than NCSIZE*8 bytes.
16223   */
16224   int nAlloc[NCSIZE];      /* Total number of allocations */
16225   int nCurrent[NCSIZE];    /* Current number of allocations */
16226   int mxCurrent[NCSIZE];   /* Highwater mark for nCurrent */
16227 
16228 } mem;
16229 
16230 
16231 /*
16232 ** Adjust memory usage statistics
16233 */
16234 static void adjustStats(int iSize, int increment){
16235   int i = ROUND8(iSize)/8;
16236   if( i>NCSIZE-1 ){
16237     i = NCSIZE - 1;
16238   }
16239   if( increment>0 ){
16240     mem.nAlloc[i]++;
16241     mem.nCurrent[i]++;
16242     if( mem.nCurrent[i]>mem.mxCurrent[i] ){
16243       mem.mxCurrent[i] = mem.nCurrent[i];
16244     }
16245   }else{
16246     mem.nCurrent[i]--;
16247     assert( mem.nCurrent[i]>=0 );
16248   }
16249 }
16250 
16251 /*
16252 ** Given an allocation, find the MemBlockHdr for that allocation.
16253 **
16254 ** This routine checks the guards at either end of the allocation and
16255 ** if they are incorrect it asserts.
16256 */
16257 static struct MemBlockHdr *sqlite3MemsysGetHeader(void *pAllocation){
16258   struct MemBlockHdr *p;
16259   int *pInt;
16260   u8 *pU8;
16261   int nReserve;
16262 
16263   p = (struct MemBlockHdr*)pAllocation;
16264   p--;
16265   assert( p->iForeGuard==(int)FOREGUARD );
16266   nReserve = ROUND8(p->iSize);
16267   pInt = (int*)pAllocation;
16268   pU8 = (u8*)pAllocation;
16269   assert( pInt[nReserve/sizeof(int)]==(int)REARGUARD );
16270   /* This checks any of the "extra" bytes allocated due
16271   ** to rounding up to an 8 byte boundary to ensure 
16272   ** they haven't been overwritten.
16273   */
16274   while( nReserve-- > p->iSize ) assert( pU8[nReserve]==0x65 );
16275   return p;
16276 }
16277 
16278 /*
16279 ** Return the number of bytes currently allocated at address p.
16280 */
16281 static int sqlite3MemSize(void *p){
16282   struct MemBlockHdr *pHdr;
16283   if( !p ){
16284     return 0;
16285   }
16286   pHdr = sqlite3MemsysGetHeader(p);
16287   return (int)pHdr->iSize;
16288 }
16289 
16290 /*
16291 ** Initialize the memory allocation subsystem.
16292 */
16293 static int sqlite3MemInit(void *NotUsed){
16294   UNUSED_PARAMETER(NotUsed);
16295   assert( (sizeof(struct MemBlockHdr)&7) == 0 );
16296   if( !sqlite3GlobalConfig.bMemstat ){
16297     /* If memory status is enabled, then the malloc.c wrapper will already
16298     ** hold the STATIC_MEM mutex when the routines here are invoked. */
16299     mem.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM);
16300   }
16301   return SQLITE_OK;
16302 }
16303 
16304 /*
16305 ** Deinitialize the memory allocation subsystem.
16306 */
16307 static void sqlite3MemShutdown(void *NotUsed){
16308   UNUSED_PARAMETER(NotUsed);
16309   mem.mutex = 0;
16310 }
16311 
16312 /*
16313 ** Round up a request size to the next valid allocation size.
16314 */
16315 static int sqlite3MemRoundup(int n){
16316   return ROUND8(n);
16317 }
16318 
16319 /*
16320 ** Fill a buffer with pseudo-random bytes.  This is used to preset
16321 ** the content of a new memory allocation to unpredictable values and
16322 ** to clear the content of a freed allocation to unpredictable values.
16323 */
16324 static void randomFill(char *pBuf, int nByte){
16325   unsigned int x, y, r;
16326   x = SQLITE_PTR_TO_INT(pBuf);
16327   y = nByte | 1;
16328   while( nByte >= 4 ){
16329     x = (x>>1) ^ (-(int)(x&1) & 0xd0000001);
16330     y = y*1103515245 + 12345;
16331     r = x ^ y;
16332     *(int*)pBuf = r;
16333     pBuf += 4;
16334     nByte -= 4;
16335   }
16336   while( nByte-- > 0 ){
16337     x = (x>>1) ^ (-(int)(x&1) & 0xd0000001);
16338     y = y*1103515245 + 12345;
16339     r = x ^ y;
16340     *(pBuf++) = r & 0xff;
16341   }
16342 }
16343 
16344 /*
16345 ** Allocate nByte bytes of memory.
16346 */
16347 static void *sqlite3MemMalloc(int nByte){
16348   struct MemBlockHdr *pHdr;
16349   void **pBt;
16350   char *z;
16351   int *pInt;
16352   void *p = 0;
16353   int totalSize;
16354   int nReserve;
16355   sqlite3_mutex_enter(mem.mutex);
16356   assert( mem.disallow==0 );
16357   nReserve = ROUND8(nByte);
16358   totalSize = nReserve + sizeof(*pHdr) + sizeof(int) +
16359                mem.nBacktrace*sizeof(void*) + mem.nTitle;
16360   p = malloc(totalSize);
16361   if( p ){
16362     z = p;
16363     pBt = (void**)&z[mem.nTitle];
16364     pHdr = (struct MemBlockHdr*)&pBt[mem.nBacktrace];
16365     pHdr->pNext = 0;
16366     pHdr->pPrev = mem.pLast;
16367     if( mem.pLast ){
16368       mem.pLast->pNext = pHdr;
16369     }else{
16370       mem.pFirst = pHdr;
16371     }
16372     mem.pLast = pHdr;
16373     pHdr->iForeGuard = FOREGUARD;
16374     pHdr->eType = MEMTYPE_HEAP;
16375     pHdr->nBacktraceSlots = mem.nBacktrace;
16376     pHdr->nTitle = mem.nTitle;
16377     if( mem.nBacktrace ){
16378       void *aAddr[40];
16379       pHdr->nBacktrace = backtrace(aAddr, mem.nBacktrace+1)-1;
16380       memcpy(pBt, &aAddr[1], pHdr->nBacktrace*sizeof(void*));
16381       assert(pBt[0]);
16382       if( mem.xBacktrace ){
16383         mem.xBacktrace(nByte, pHdr->nBacktrace-1, &aAddr[1]);
16384       }
16385     }else{
16386       pHdr->nBacktrace = 0;
16387     }
16388     if( mem.nTitle ){
16389       memcpy(z, mem.zTitle, mem.nTitle);
16390     }
16391     pHdr->iSize = nByte;
16392     adjustStats(nByte, +1);
16393     pInt = (int*)&pHdr[1];
16394     pInt[nReserve/sizeof(int)] = REARGUARD;
16395     randomFill((char*)pInt, nByte);
16396     memset(((char*)pInt)+nByte, 0x65, nReserve-nByte);
16397     p = (void*)pInt;
16398   }
16399   sqlite3_mutex_leave(mem.mutex);
16400   return p; 
16401 }
16402 
16403 /*
16404 ** Free memory.
16405 */
16406 static void sqlite3MemFree(void *pPrior){
16407   struct MemBlockHdr *pHdr;
16408   void **pBt;
16409   char *z;
16410   assert( sqlite3GlobalConfig.bMemstat || sqlite3GlobalConfig.bCoreMutex==0 
16411        || mem.mutex!=0 );
16412   pHdr = sqlite3MemsysGetHeader(pPrior);
16413   pBt = (void**)pHdr;
16414   pBt -= pHdr->nBacktraceSlots;
16415   sqlite3_mutex_enter(mem.mutex);
16416   if( pHdr->pPrev ){
16417     assert( pHdr->pPrev->pNext==pHdr );
16418     pHdr->pPrev->pNext = pHdr->pNext;
16419   }else{
16420     assert( mem.pFirst==pHdr );
16421     mem.pFirst = pHdr->pNext;
16422   }
16423   if( pHdr->pNext ){
16424     assert( pHdr->pNext->pPrev==pHdr );
16425     pHdr->pNext->pPrev = pHdr->pPrev;
16426   }else{
16427     assert( mem.pLast==pHdr );
16428     mem.pLast = pHdr->pPrev;
16429   }
16430   z = (char*)pBt;
16431   z -= pHdr->nTitle;
16432   adjustStats((int)pHdr->iSize, -1);
16433   randomFill(z, sizeof(void*)*pHdr->nBacktraceSlots + sizeof(*pHdr) +
16434                 (int)pHdr->iSize + sizeof(int) + pHdr->nTitle);
16435   free(z);
16436   sqlite3_mutex_leave(mem.mutex);  
16437 }
16438 
16439 /*
16440 ** Change the size of an existing memory allocation.
16441 **
16442 ** For this debugging implementation, we *always* make a copy of the
16443 ** allocation into a new place in memory.  In this way, if the 
16444 ** higher level code is using pointer to the old allocation, it is 
16445 ** much more likely to break and we are much more liking to find
16446 ** the error.
16447 */
16448 static void *sqlite3MemRealloc(void *pPrior, int nByte){
16449   struct MemBlockHdr *pOldHdr;
16450   void *pNew;
16451   assert( mem.disallow==0 );
16452   assert( (nByte & 7)==0 );     /* EV: R-46199-30249 */
16453   pOldHdr = sqlite3MemsysGetHeader(pPrior);
16454   pNew = sqlite3MemMalloc(nByte);
16455   if( pNew ){
16456     memcpy(pNew, pPrior, (int)(nByte<pOldHdr->iSize ? nByte : pOldHdr->iSize));
16457     if( nByte>pOldHdr->iSize ){
16458       randomFill(&((char*)pNew)[pOldHdr->iSize], nByte - (int)pOldHdr->iSize);
16459     }
16460     sqlite3MemFree(pPrior);
16461   }
16462   return pNew;
16463 }
16464 
16465 /*
16466 ** Populate the low-level memory allocation function pointers in
16467 ** sqlite3GlobalConfig.m with pointers to the routines in this file.
16468 */
16469 SQLITE_PRIVATE void sqlite3MemSetDefault(void){
16470   static const sqlite3_mem_methods defaultMethods = {
16471      sqlite3MemMalloc,
16472      sqlite3MemFree,
16473      sqlite3MemRealloc,
16474      sqlite3MemSize,
16475      sqlite3MemRoundup,
16476      sqlite3MemInit,
16477      sqlite3MemShutdown,
16478      0
16479   };
16480   sqlite3_config(SQLITE_CONFIG_MALLOC, &defaultMethods);
16481 }
16482 
16483 /*
16484 ** Set the "type" of an allocation.
16485 */
16486 SQLITE_PRIVATE void sqlite3MemdebugSetType(void *p, u8 eType){
16487   if( p && sqlite3GlobalConfig.m.xMalloc==sqlite3MemMalloc ){
16488     struct MemBlockHdr *pHdr;
16489     pHdr = sqlite3MemsysGetHeader(p);
16490     assert( pHdr->iForeGuard==FOREGUARD );
16491     pHdr->eType = eType;
16492   }
16493 }
16494 
16495 /*
16496 ** Return TRUE if the mask of type in eType matches the type of the
16497 ** allocation p.  Also return true if p==NULL.
16498 **
16499 ** This routine is designed for use within an assert() statement, to
16500 ** verify the type of an allocation.  For example:
16501 **
16502 **     assert( sqlite3MemdebugHasType(p, MEMTYPE_DB) );
16503 */
16504 SQLITE_PRIVATE int sqlite3MemdebugHasType(void *p, u8 eType){
16505   int rc = 1;
16506   if( p && sqlite3GlobalConfig.m.xMalloc==sqlite3MemMalloc ){
16507     struct MemBlockHdr *pHdr;
16508     pHdr = sqlite3MemsysGetHeader(p);
16509     assert( pHdr->iForeGuard==FOREGUARD );         /* Allocation is valid */
16510     if( (pHdr->eType&eType)==0 ){
16511       rc = 0;
16512     }
16513   }
16514   return rc;
16515 }
16516 
16517 /*
16518 ** Return TRUE if the mask of type in eType matches no bits of the type of the
16519 ** allocation p.  Also return true if p==NULL.
16520 **
16521 ** This routine is designed for use within an assert() statement, to
16522 ** verify the type of an allocation.  For example:
16523 **
16524 **     assert( sqlite3MemdebugNoType(p, MEMTYPE_DB) );
16525 */
16526 SQLITE_PRIVATE int sqlite3MemdebugNoType(void *p, u8 eType){
16527   int rc = 1;
16528   if( p && sqlite3GlobalConfig.m.xMalloc==sqlite3MemMalloc ){
16529     struct MemBlockHdr *pHdr;
16530     pHdr = sqlite3MemsysGetHeader(p);
16531     assert( pHdr->iForeGuard==FOREGUARD );         /* Allocation is valid */
16532     if( (pHdr->eType&eType)!=0 ){
16533       rc = 0;
16534     }
16535   }
16536   return rc;
16537 }
16538 
16539 /*
16540 ** Set the number of backtrace levels kept for each allocation.
16541 ** A value of zero turns off backtracing.  The number is always rounded
16542 ** up to a multiple of 2.
16543 */
16544 SQLITE_PRIVATE void sqlite3MemdebugBacktrace(int depth){
16545   if( depth<0 ){ depth = 0; }
16546   if( depth>20 ){ depth = 20; }
16547   depth = (depth+1)&0xfe;
16548   mem.nBacktrace = depth;
16549 }
16550 
16551 SQLITE_PRIVATE void sqlite3MemdebugBacktraceCallback(void (*xBacktrace)(int, int, void **)){
16552   mem.xBacktrace = xBacktrace;
16553 }
16554 
16555 /*
16556 ** Set the title string for subsequent allocations.
16557 */
16558 SQLITE_PRIVATE void sqlite3MemdebugSettitle(const char *zTitle){
16559   unsigned int n = sqlite3Strlen30(zTitle) + 1;
16560   sqlite3_mutex_enter(mem.mutex);
16561   if( n>=sizeof(mem.zTitle) ) n = sizeof(mem.zTitle)-1;
16562   memcpy(mem.zTitle, zTitle, n);
16563   mem.zTitle[n] = 0;
16564   mem.nTitle = ROUND8(n);
16565   sqlite3_mutex_leave(mem.mutex);
16566 }
16567 
16568 SQLITE_PRIVATE void sqlite3MemdebugSync(){
16569   struct MemBlockHdr *pHdr;
16570   for(pHdr=mem.pFirst; pHdr; pHdr=pHdr->pNext){
16571     void **pBt = (void**)pHdr;
16572     pBt -= pHdr->nBacktraceSlots;
16573     mem.xBacktrace((int)pHdr->iSize, pHdr->nBacktrace-1, &pBt[1]);
16574   }
16575 }
16576 
16577 /*
16578 ** Open the file indicated and write a log of all unfreed memory 
16579 ** allocations into that log.
16580 */
16581 SQLITE_PRIVATE void sqlite3MemdebugDump(const char *zFilename){
16582   FILE *out;
16583   struct MemBlockHdr *pHdr;
16584   void **pBt;
16585   int i;
16586   out = fopen(zFilename, "w");
16587   if( out==0 ){
16588     fprintf(stderr, "** Unable to output memory debug output log: %s **\n",
16589                     zFilename);
16590     return;
16591   }
16592   for(pHdr=mem.pFirst; pHdr; pHdr=pHdr->pNext){
16593     char *z = (char*)pHdr;
16594     z -= pHdr->nBacktraceSlots*sizeof(void*) + pHdr->nTitle;
16595     fprintf(out, "**** %lld bytes at %p from %s ****\n", 
16596             pHdr->iSize, &pHdr[1], pHdr->nTitle ? z : "???");
16597     if( pHdr->nBacktrace ){
16598       fflush(out);
16599       pBt = (void**)pHdr;
16600       pBt -= pHdr->nBacktraceSlots;
16601       backtrace_symbols_fd(pBt, pHdr->nBacktrace, fileno(out));
16602       fprintf(out, "\n");
16603     }
16604   }
16605   fprintf(out, "COUNTS:\n");
16606   for(i=0; i<NCSIZE-1; i++){
16607     if( mem.nAlloc[i] ){
16608       fprintf(out, "   %5d: %10d %10d %10d\n", 
16609             i*8, mem.nAlloc[i], mem.nCurrent[i], mem.mxCurrent[i]);
16610     }
16611   }
16612   if( mem.nAlloc[NCSIZE-1] ){
16613     fprintf(out, "   %5d: %10d %10d %10d\n",
16614              NCSIZE*8-8, mem.nAlloc[NCSIZE-1],
16615              mem.nCurrent[NCSIZE-1], mem.mxCurrent[NCSIZE-1]);
16616   }
16617   fclose(out);
16618 }
16619 
16620 /*
16621 ** Return the number of times sqlite3MemMalloc() has been called.
16622 */
16623 SQLITE_PRIVATE int sqlite3MemdebugMallocCount(){
16624   int i;
16625   int nTotal = 0;
16626   for(i=0; i<NCSIZE; i++){
16627     nTotal += mem.nAlloc[i];
16628   }
16629   return nTotal;
16630 }
16631 
16632 
16633 #endif /* SQLITE_MEMDEBUG */
16634 
16635 /************** End of mem2.c ************************************************/
16636 /************** Begin file mem3.c ********************************************/
16637 /*
16638 ** 2007 October 14
16639 **
16640 ** The author disclaims copyright to this source code.  In place of
16641 ** a legal notice, here is a blessing:
16642 **
16643 **    May you do good and not evil.
16644 **    May you find forgiveness for yourself and forgive others.
16645 **    May you share freely, never taking more than you give.
16646 **
16647 *************************************************************************
16648 ** This file contains the C functions that implement a memory
16649 ** allocation subsystem for use by SQLite. 
16650 **
16651 ** This version of the memory allocation subsystem omits all
16652 ** use of malloc(). The SQLite user supplies a block of memory
16653 ** before calling sqlite3_initialize() from which allocations
16654 ** are made and returned by the xMalloc() and xRealloc() 
16655 ** implementations. Once sqlite3_initialize() has been called,
16656 ** the amount of memory available to SQLite is fixed and cannot
16657 ** be changed.
16658 **
16659 ** This version of the memory allocation subsystem is included
16660 ** in the build only if SQLITE_ENABLE_MEMSYS3 is defined.
16661 */
16662 
16663 /*
16664 ** This version of the memory allocator is only built into the library
16665 ** SQLITE_ENABLE_MEMSYS3 is defined. Defining this symbol does not
16666 ** mean that the library will use a memory-pool by default, just that
16667 ** it is available. The mempool allocator is activated by calling
16668 ** sqlite3_config().
16669 */
16670 #ifdef SQLITE_ENABLE_MEMSYS3
16671 
16672 /*
16673 ** Maximum size (in Mem3Blocks) of a "small" chunk.
16674 */
16675 #define MX_SMALL 10
16676 
16677 
16678 /*
16679 ** Number of freelist hash slots
16680 */
16681 #define N_HASH  61
16682 
16683 /*
16684 ** A memory allocation (also called a "chunk") consists of two or 
16685 ** more blocks where each block is 8 bytes.  The first 8 bytes are 
16686 ** a header that is not returned to the user.
16687 **
16688 ** A chunk is two or more blocks that is either checked out or
16689 ** free.  The first block has format u.hdr.  u.hdr.size4x is 4 times the
16690 ** size of the allocation in blocks if the allocation is free.
16691 ** The u.hdr.size4x&1 bit is true if the chunk is checked out and
16692 ** false if the chunk is on the freelist.  The u.hdr.size4x&2 bit
16693 ** is true if the previous chunk is checked out and false if the
16694 ** previous chunk is free.  The u.hdr.prevSize field is the size of
16695 ** the previous chunk in blocks if the previous chunk is on the
16696 ** freelist. If the previous chunk is checked out, then
16697 ** u.hdr.prevSize can be part of the data for that chunk and should
16698 ** not be read or written.
16699 **
16700 ** We often identify a chunk by its index in mem3.aPool[].  When
16701 ** this is done, the chunk index refers to the second block of
16702 ** the chunk.  In this way, the first chunk has an index of 1.
16703 ** A chunk index of 0 means "no such chunk" and is the equivalent
16704 ** of a NULL pointer.
16705 **
16706 ** The second block of free chunks is of the form u.list.  The
16707 ** two fields form a double-linked list of chunks of related sizes.
16708 ** Pointers to the head of the list are stored in mem3.aiSmall[] 
16709 ** for smaller chunks and mem3.aiHash[] for larger chunks.
16710 **
16711 ** The second block of a chunk is user data if the chunk is checked 
16712 ** out.  If a chunk is checked out, the user data may extend into
16713 ** the u.hdr.prevSize value of the following chunk.
16714 */
16715 typedef struct Mem3Block Mem3Block;
16716 struct Mem3Block {
16717   union {
16718     struct {
16719       u32 prevSize;   /* Size of previous chunk in Mem3Block elements */
16720       u32 size4x;     /* 4x the size of current chunk in Mem3Block elements */
16721     } hdr;
16722     struct {
16723       u32 next;       /* Index in mem3.aPool[] of next free chunk */
16724       u32 prev;       /* Index in mem3.aPool[] of previous free chunk */
16725     } list;
16726   } u;
16727 };
16728 
16729 /*
16730 ** All of the static variables used by this module are collected
16731 ** into a single structure named "mem3".  This is to keep the
16732 ** static variables organized and to reduce namespace pollution
16733 ** when this module is combined with other in the amalgamation.
16734 */
16735 static SQLITE_WSD struct Mem3Global {
16736   /*
16737   ** Memory available for allocation. nPool is the size of the array
16738   ** (in Mem3Blocks) pointed to by aPool less 2.
16739   */
16740   u32 nPool;
16741   Mem3Block *aPool;
16742 
16743   /*
16744   ** True if we are evaluating an out-of-memory callback.
16745   */
16746   int alarmBusy;
16747   
16748   /*
16749   ** Mutex to control access to the memory allocation subsystem.
16750   */
16751   sqlite3_mutex *mutex;
16752   
16753   /*
16754   ** The minimum amount of free space that we have seen.
16755   */
16756   u32 mnMaster;
16757 
16758   /*
16759   ** iMaster is the index of the master chunk.  Most new allocations
16760   ** occur off of this chunk.  szMaster is the size (in Mem3Blocks)
16761   ** of the current master.  iMaster is 0 if there is not master chunk.
16762   ** The master chunk is not in either the aiHash[] or aiSmall[].
16763   */
16764   u32 iMaster;
16765   u32 szMaster;
16766 
16767   /*
16768   ** Array of lists of free blocks according to the block size 
16769   ** for smaller chunks, or a hash on the block size for larger
16770   ** chunks.
16771   */
16772   u32 aiSmall[MX_SMALL-1];   /* For sizes 2 through MX_SMALL, inclusive */
16773   u32 aiHash[N_HASH];        /* For sizes MX_SMALL+1 and larger */
16774 } mem3 = { 97535575 };
16775 
16776 #define mem3 GLOBAL(struct Mem3Global, mem3)
16777 
16778 /*
16779 ** Unlink the chunk at mem3.aPool[i] from list it is currently
16780 ** on.  *pRoot is the list that i is a member of.
16781 */
16782 static void memsys3UnlinkFromList(u32 i, u32 *pRoot){
16783   u32 next = mem3.aPool[i].u.list.next;
16784   u32 prev = mem3.aPool[i].u.list.prev;
16785   assert( sqlite3_mutex_held(mem3.mutex) );
16786   if( prev==0 ){
16787     *pRoot = next;
16788   }else{
16789     mem3.aPool[prev].u.list.next = next;
16790   }
16791   if( next ){
16792     mem3.aPool[next].u.list.prev = prev;
16793   }
16794   mem3.aPool[i].u.list.next = 0;
16795   mem3.aPool[i].u.list.prev = 0;
16796 }
16797 
16798 /*
16799 ** Unlink the chunk at index i from 
16800 ** whatever list is currently a member of.
16801 */
16802 static void memsys3Unlink(u32 i){
16803   u32 size, hash;
16804   assert( sqlite3_mutex_held(mem3.mutex) );
16805   assert( (mem3.aPool[i-1].u.hdr.size4x & 1)==0 );
16806   assert( i>=1 );
16807   size = mem3.aPool[i-1].u.hdr.size4x/4;
16808   assert( size==mem3.aPool[i+size-1].u.hdr.prevSize );
16809   assert( size>=2 );
16810   if( size <= MX_SMALL ){
16811     memsys3UnlinkFromList(i, &mem3.aiSmall[size-2]);
16812   }else{
16813     hash = size % N_HASH;
16814     memsys3UnlinkFromList(i, &mem3.aiHash[hash]);
16815   }
16816 }
16817 
16818 /*
16819 ** Link the chunk at mem3.aPool[i] so that is on the list rooted
16820 ** at *pRoot.
16821 */
16822 static void memsys3LinkIntoList(u32 i, u32 *pRoot){
16823   assert( sqlite3_mutex_held(mem3.mutex) );
16824   mem3.aPool[i].u.list.next = *pRoot;
16825   mem3.aPool[i].u.list.prev = 0;
16826   if( *pRoot ){
16827     mem3.aPool[*pRoot].u.list.prev = i;
16828   }
16829   *pRoot = i;
16830 }
16831 
16832 /*
16833 ** Link the chunk at index i into either the appropriate
16834 ** small chunk list, or into the large chunk hash table.
16835 */
16836 static void memsys3Link(u32 i){
16837   u32 size, hash;
16838   assert( sqlite3_mutex_held(mem3.mutex) );
16839   assert( i>=1 );
16840   assert( (mem3.aPool[i-1].u.hdr.size4x & 1)==0 );
16841   size = mem3.aPool[i-1].u.hdr.size4x/4;
16842   assert( size==mem3.aPool[i+size-1].u.hdr.prevSize );
16843   assert( size>=2 );
16844   if( size <= MX_SMALL ){
16845     memsys3LinkIntoList(i, &mem3.aiSmall[size-2]);
16846   }else{
16847     hash = size % N_HASH;
16848     memsys3LinkIntoList(i, &mem3.aiHash[hash]);
16849   }
16850 }
16851 
16852 /*
16853 ** If the STATIC_MEM mutex is not already held, obtain it now. The mutex
16854 ** will already be held (obtained by code in malloc.c) if
16855 ** sqlite3GlobalConfig.bMemStat is true.
16856 */
16857 static void memsys3Enter(void){
16858   if( sqlite3GlobalConfig.bMemstat==0 && mem3.mutex==0 ){
16859     mem3.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM);
16860   }
16861   sqlite3_mutex_enter(mem3.mutex);
16862 }
16863 static void memsys3Leave(void){
16864   sqlite3_mutex_leave(mem3.mutex);
16865 }
16866 
16867 /*
16868 ** Called when we are unable to satisfy an allocation of nBytes.
16869 */
16870 static void memsys3OutOfMemory(int nByte){
16871   if( !mem3.alarmBusy ){
16872     mem3.alarmBusy = 1;
16873     assert( sqlite3_mutex_held(mem3.mutex) );
16874     sqlite3_mutex_leave(mem3.mutex);
16875     sqlite3_release_memory(nByte);
16876     sqlite3_mutex_enter(mem3.mutex);
16877     mem3.alarmBusy = 0;
16878   }
16879 }
16880 
16881 
16882 /*
16883 ** Chunk i is a free chunk that has been unlinked.  Adjust its 
16884 ** size parameters for check-out and return a pointer to the 
16885 ** user portion of the chunk.
16886 */
16887 static void *memsys3Checkout(u32 i, u32 nBlock){
16888   u32 x;
16889   assert( sqlite3_mutex_held(mem3.mutex) );
16890   assert( i>=1 );
16891   assert( mem3.aPool[i-1].u.hdr.size4x/4==nBlock );
16892   assert( mem3.aPool[i+nBlock-1].u.hdr.prevSize==nBlock );
16893   x = mem3.aPool[i-1].u.hdr.size4x;
16894   mem3.aPool[i-1].u.hdr.size4x = nBlock*4 | 1 | (x&2);
16895   mem3.aPool[i+nBlock-1].u.hdr.prevSize = nBlock;
16896   mem3.aPool[i+nBlock-1].u.hdr.size4x |= 2;
16897   return &mem3.aPool[i];
16898 }
16899 
16900 /*
16901 ** Carve a piece off of the end of the mem3.iMaster free chunk.
16902 ** Return a pointer to the new allocation.  Or, if the master chunk
16903 ** is not large enough, return 0.
16904 */
16905 static void *memsys3FromMaster(u32 nBlock){
16906   assert( sqlite3_mutex_held(mem3.mutex) );
16907   assert( mem3.szMaster>=nBlock );
16908   if( nBlock>=mem3.szMaster-1 ){
16909     /* Use the entire master */
16910     void *p = memsys3Checkout(mem3.iMaster, mem3.szMaster);
16911     mem3.iMaster = 0;
16912     mem3.szMaster = 0;
16913     mem3.mnMaster = 0;
16914     return p;
16915   }else{
16916     /* Split the master block.  Return the tail. */
16917     u32 newi, x;
16918     newi = mem3.iMaster + mem3.szMaster - nBlock;
16919     assert( newi > mem3.iMaster+1 );
16920     mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.prevSize = nBlock;
16921     mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.size4x |= 2;
16922     mem3.aPool[newi-1].u.hdr.size4x = nBlock*4 + 1;
16923     mem3.szMaster -= nBlock;
16924     mem3.aPool[newi-1].u.hdr.prevSize = mem3.szMaster;
16925     x = mem3.aPool[mem3.iMaster-1].u.hdr.size4x & 2;
16926     mem3.aPool[mem3.iMaster-1].u.hdr.size4x = mem3.szMaster*4 | x;
16927     if( mem3.szMaster < mem3.mnMaster ){
16928       mem3.mnMaster = mem3.szMaster;
16929     }
16930     return (void*)&mem3.aPool[newi];
16931   }
16932 }
16933 
16934 /*
16935 ** *pRoot is the head of a list of free chunks of the same size
16936 ** or same size hash.  In other words, *pRoot is an entry in either
16937 ** mem3.aiSmall[] or mem3.aiHash[].  
16938 **
16939 ** This routine examines all entries on the given list and tries
16940 ** to coalesce each entries with adjacent free chunks.  
16941 **
16942 ** If it sees a chunk that is larger than mem3.iMaster, it replaces 
16943 ** the current mem3.iMaster with the new larger chunk.  In order for
16944 ** this mem3.iMaster replacement to work, the master chunk must be
16945 ** linked into the hash tables.  That is not the normal state of
16946 ** affairs, of course.  The calling routine must link the master
16947 ** chunk before invoking this routine, then must unlink the (possibly
16948 ** changed) master chunk once this routine has finished.
16949 */
16950 static void memsys3Merge(u32 *pRoot){
16951   u32 iNext, prev, size, i, x;
16952 
16953   assert( sqlite3_mutex_held(mem3.mutex) );
16954   for(i=*pRoot; i>0; i=iNext){
16955     iNext = mem3.aPool[i].u.list.next;
16956     size = mem3.aPool[i-1].u.hdr.size4x;
16957     assert( (size&1)==0 );
16958     if( (size&2)==0 ){
16959       memsys3UnlinkFromList(i, pRoot);
16960       assert( i > mem3.aPool[i-1].u.hdr.prevSize );
16961       prev = i - mem3.aPool[i-1].u.hdr.prevSize;
16962       if( prev==iNext ){
16963         iNext = mem3.aPool[prev].u.list.next;
16964       }
16965       memsys3Unlink(prev);
16966       size = i + size/4 - prev;
16967       x = mem3.aPool[prev-1].u.hdr.size4x & 2;
16968       mem3.aPool[prev-1].u.hdr.size4x = size*4 | x;
16969       mem3.aPool[prev+size-1].u.hdr.prevSize = size;
16970       memsys3Link(prev);
16971       i = prev;
16972     }else{
16973       size /= 4;
16974     }
16975     if( size>mem3.szMaster ){
16976       mem3.iMaster = i;
16977       mem3.szMaster = size;
16978     }
16979   }
16980 }
16981 
16982 /*
16983 ** Return a block of memory of at least nBytes in size.
16984 ** Return NULL if unable.
16985 **
16986 ** This function assumes that the necessary mutexes, if any, are
16987 ** already held by the caller. Hence "Unsafe".
16988 */
16989 static void *memsys3MallocUnsafe(int nByte){
16990   u32 i;
16991   u32 nBlock;
16992   u32 toFree;
16993 
16994   assert( sqlite3_mutex_held(mem3.mutex) );
16995   assert( sizeof(Mem3Block)==8 );
16996   if( nByte<=12 ){
16997     nBlock = 2;
16998   }else{
16999     nBlock = (nByte + 11)/8;
17000   }
17001   assert( nBlock>=2 );
17002 
17003   /* STEP 1:
17004   ** Look for an entry of the correct size in either the small
17005   ** chunk table or in the large chunk hash table.  This is
17006   ** successful most of the time (about 9 times out of 10).
17007   */
17008   if( nBlock <= MX_SMALL ){
17009     i = mem3.aiSmall[nBlock-2];
17010     if( i>0 ){
17011       memsys3UnlinkFromList(i, &mem3.aiSmall[nBlock-2]);
17012       return memsys3Checkout(i, nBlock);
17013     }
17014   }else{
17015     int hash = nBlock % N_HASH;
17016     for(i=mem3.aiHash[hash]; i>0; i=mem3.aPool[i].u.list.next){
17017       if( mem3.aPool[i-1].u.hdr.size4x/4==nBlock ){
17018         memsys3UnlinkFromList(i, &mem3.aiHash[hash]);
17019         return memsys3Checkout(i, nBlock);
17020       }
17021     }
17022   }
17023 
17024   /* STEP 2:
17025   ** Try to satisfy the allocation by carving a piece off of the end
17026   ** of the master chunk.  This step usually works if step 1 fails.
17027   */
17028   if( mem3.szMaster>=nBlock ){
17029     return memsys3FromMaster(nBlock);
17030   }
17031 
17032 
17033   /* STEP 3:  
17034   ** Loop through the entire memory pool.  Coalesce adjacent free
17035   ** chunks.  Recompute the master chunk as the largest free chunk.
17036   ** Then try again to satisfy the allocation by carving a piece off
17037   ** of the end of the master chunk.  This step happens very
17038   ** rarely (we hope!)
17039   */
17040   for(toFree=nBlock*16; toFree<(mem3.nPool*16); toFree *= 2){
17041     memsys3OutOfMemory(toFree);
17042     if( mem3.iMaster ){
17043       memsys3Link(mem3.iMaster);
17044       mem3.iMaster = 0;
17045       mem3.szMaster = 0;
17046     }
17047     for(i=0; i<N_HASH; i++){
17048       memsys3Merge(&mem3.aiHash[i]);
17049     }
17050     for(i=0; i<MX_SMALL-1; i++){
17051       memsys3Merge(&mem3.aiSmall[i]);
17052     }
17053     if( mem3.szMaster ){
17054       memsys3Unlink(mem3.iMaster);
17055       if( mem3.szMaster>=nBlock ){
17056         return memsys3FromMaster(nBlock);
17057       }
17058     }
17059   }
17060 
17061   /* If none of the above worked, then we fail. */
17062   return 0;
17063 }
17064 
17065 /*
17066 ** Free an outstanding memory allocation.
17067 **
17068 ** This function assumes that the necessary mutexes, if any, are
17069 ** already held by the caller. Hence "Unsafe".
17070 */
17071 static void memsys3FreeUnsafe(void *pOld){
17072   Mem3Block *p = (Mem3Block*)pOld;
17073   int i;
17074   u32 size, x;
17075   assert( sqlite3_mutex_held(mem3.mutex) );
17076   assert( p>mem3.aPool && p<&mem3.aPool[mem3.nPool] );
17077   i = p - mem3.aPool;
17078   assert( (mem3.aPool[i-1].u.hdr.size4x&1)==1 );
17079   size = mem3.aPool[i-1].u.hdr.size4x/4;
17080   assert( i+size<=mem3.nPool+1 );
17081   mem3.aPool[i-1].u.hdr.size4x &= ~1;
17082   mem3.aPool[i+size-1].u.hdr.prevSize = size;
17083   mem3.aPool[i+size-1].u.hdr.size4x &= ~2;
17084   memsys3Link(i);
17085 
17086   /* Try to expand the master using the newly freed chunk */
17087   if( mem3.iMaster ){
17088     while( (mem3.aPool[mem3.iMaster-1].u.hdr.size4x&2)==0 ){
17089       size = mem3.aPool[mem3.iMaster-1].u.hdr.prevSize;
17090       mem3.iMaster -= size;
17091       mem3.szMaster += size;
17092       memsys3Unlink(mem3.iMaster);
17093       x = mem3.aPool[mem3.iMaster-1].u.hdr.size4x & 2;
17094       mem3.aPool[mem3.iMaster-1].u.hdr.size4x = mem3.szMaster*4 | x;
17095       mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.prevSize = mem3.szMaster;
17096     }
17097     x = mem3.aPool[mem3.iMaster-1].u.hdr.size4x & 2;
17098     while( (mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.size4x&1)==0 ){
17099       memsys3Unlink(mem3.iMaster+mem3.szMaster);
17100       mem3.szMaster += mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.size4x/4;
17101       mem3.aPool[mem3.iMaster-1].u.hdr.size4x = mem3.szMaster*4 | x;
17102       mem3.aPool[mem3.iMaster+mem3.szMaster-1].u.hdr.prevSize = mem3.szMaster;
17103     }
17104   }
17105 }
17106 
17107 /*
17108 ** Return the size of an outstanding allocation, in bytes.  The
17109 ** size returned omits the 8-byte header overhead.  This only
17110 ** works for chunks that are currently checked out.
17111 */
17112 static int memsys3Size(void *p){
17113   Mem3Block *pBlock;
17114   if( p==0 ) return 0;
17115   pBlock = (Mem3Block*)p;
17116   assert( (pBlock[-1].u.hdr.size4x&1)!=0 );
17117   return (pBlock[-1].u.hdr.size4x&~3)*2 - 4;
17118 }
17119 
17120 /*
17121 ** Round up a request size to the next valid allocation size.
17122 */
17123 static int memsys3Roundup(int n){
17124   if( n<=12 ){
17125     return 12;
17126   }else{
17127     return ((n+11)&~7) - 4;
17128   }
17129 }
17130 
17131 /*
17132 ** Allocate nBytes of memory.
17133 */
17134 static void *memsys3Malloc(int nBytes){
17135   sqlite3_int64 *p;
17136   assert( nBytes>0 );          /* malloc.c filters out 0 byte requests */
17137   memsys3Enter();
17138   p = memsys3MallocUnsafe(nBytes);
17139   memsys3Leave();
17140   return (void*)p; 
17141 }
17142 
17143 /*
17144 ** Free memory.
17145 */
17146 static void memsys3Free(void *pPrior){
17147   assert( pPrior );
17148   memsys3Enter();
17149   memsys3FreeUnsafe(pPrior);
17150   memsys3Leave();
17151 }
17152 
17153 /*
17154 ** Change the size of an existing memory allocation
17155 */
17156 static void *memsys3Realloc(void *pPrior, int nBytes){
17157   int nOld;
17158   void *p;
17159   if( pPrior==0 ){
17160     return sqlite3_malloc(nBytes);
17161   }
17162   if( nBytes<=0 ){
17163     sqlite3_free(pPrior);
17164     return 0;
17165   }
17166   nOld = memsys3Size(pPrior);
17167   if( nBytes<=nOld && nBytes>=nOld-128 ){
17168     return pPrior;
17169   }
17170   memsys3Enter();
17171   p = memsys3MallocUnsafe(nBytes);
17172   if( p ){
17173     if( nOld<nBytes ){
17174       memcpy(p, pPrior, nOld);
17175     }else{
17176       memcpy(p, pPrior, nBytes);
17177     }
17178     memsys3FreeUnsafe(pPrior);
17179   }
17180   memsys3Leave();
17181   return p;
17182 }
17183 
17184 /*
17185 ** Initialize this module.
17186 */
17187 static int memsys3Init(void *NotUsed){
17188   UNUSED_PARAMETER(NotUsed);
17189   if( !sqlite3GlobalConfig.pHeap ){
17190     return SQLITE_ERROR;
17191   }
17192 
17193   /* Store a pointer to the memory block in global structure mem3. */
17194   assert( sizeof(Mem3Block)==8 );
17195   mem3.aPool = (Mem3Block *)sqlite3GlobalConfig.pHeap;
17196   mem3.nPool = (sqlite3GlobalConfig.nHeap / sizeof(Mem3Block)) - 2;
17197 
17198   /* Initialize the master block. */
17199   mem3.szMaster = mem3.nPool;
17200   mem3.mnMaster = mem3.szMaster;
17201   mem3.iMaster = 1;
17202   mem3.aPool[0].u.hdr.size4x = (mem3.szMaster<<2) + 2;
17203   mem3.aPool[mem3.nPool].u.hdr.prevSize = mem3.nPool;
17204   mem3.aPool[mem3.nPool].u.hdr.size4x = 1;
17205 
17206   return SQLITE_OK;
17207 }
17208 
17209 /*
17210 ** Deinitialize this module.
17211 */
17212 static void memsys3Shutdown(void *NotUsed){
17213   UNUSED_PARAMETER(NotUsed);
17214   mem3.mutex = 0;
17215   return;
17216 }
17217 
17218 
17219 
17220 /*
17221 ** Open the file indicated and write a log of all unfreed memory 
17222 ** allocations into that log.
17223 */
17224 SQLITE_PRIVATE void sqlite3Memsys3Dump(const char *zFilename){
17225 #ifdef SQLITE_DEBUG
17226   FILE *out;
17227   u32 i, j;
17228   u32 size;
17229   if( zFilename==0 || zFilename[0]==0 ){
17230     out = stdout;
17231   }else{
17232     out = fopen(zFilename, "w");
17233     if( out==0 ){
17234       fprintf(stderr, "** Unable to output memory debug output log: %s **\n",
17235                       zFilename);
17236       return;
17237     }
17238   }
17239   memsys3Enter();
17240   fprintf(out, "CHUNKS:\n");
17241   for(i=1; i<=mem3.nPool; i+=size/4){
17242     size = mem3.aPool[i-1].u.hdr.size4x;
17243     if( size/4<=1 ){
17244       fprintf(out, "%p size error\n", &mem3.aPool[i]);
17245       assert( 0 );
17246       break;
17247     }
17248     if( (size&1)==0 && mem3.aPool[i+size/4-1].u.hdr.prevSize!=size/4 ){
17249       fprintf(out, "%p tail size does not match\n", &mem3.aPool[i]);
17250       assert( 0 );
17251       break;
17252     }
17253     if( ((mem3.aPool[i+size/4-1].u.hdr.size4x&2)>>1)!=(size&1) ){
17254       fprintf(out, "%p tail checkout bit is incorrect\n", &mem3.aPool[i]);
17255       assert( 0 );
17256       break;
17257     }
17258     if( size&1 ){
17259       fprintf(out, "%p %6d bytes checked out\n", &mem3.aPool[i], (size/4)*8-8);
17260     }else{
17261       fprintf(out, "%p %6d bytes free%s\n", &mem3.aPool[i], (size/4)*8-8,
17262                   i==mem3.iMaster ? " **master**" : "");
17263     }
17264   }
17265   for(i=0; i<MX_SMALL-1; i++){
17266     if( mem3.aiSmall[i]==0 ) continue;
17267     fprintf(out, "small(%2d):", i);
17268     for(j = mem3.aiSmall[i]; j>0; j=mem3.aPool[j].u.list.next){
17269       fprintf(out, " %p(%d)", &mem3.aPool[j],
17270               (mem3.aPool[j-1].u.hdr.size4x/4)*8-8);
17271     }
17272     fprintf(out, "\n"); 
17273   }
17274   for(i=0; i<N_HASH; i++){
17275     if( mem3.aiHash[i]==0 ) continue;
17276     fprintf(out, "hash(%2d):", i);
17277     for(j = mem3.aiHash[i]; j>0; j=mem3.aPool[j].u.list.next){
17278       fprintf(out, " %p(%d)", &mem3.aPool[j],
17279               (mem3.aPool[j-1].u.hdr.size4x/4)*8-8);
17280     }
17281     fprintf(out, "\n"); 
17282   }
17283   fprintf(out, "master=%d\n", mem3.iMaster);
17284   fprintf(out, "nowUsed=%d\n", mem3.nPool*8 - mem3.szMaster*8);
17285   fprintf(out, "mxUsed=%d\n", mem3.nPool*8 - mem3.mnMaster*8);
17286   sqlite3_mutex_leave(mem3.mutex);
17287   if( out==stdout ){
17288     fflush(stdout);
17289   }else{
17290     fclose(out);
17291   }
17292 #else
17293   UNUSED_PARAMETER(zFilename);
17294 #endif
17295 }
17296 
17297 /*
17298 ** This routine is the only routine in this file with external 
17299 ** linkage.
17300 **
17301 ** Populate the low-level memory allocation function pointers in
17302 ** sqlite3GlobalConfig.m with pointers to the routines in this file. The
17303 ** arguments specify the block of memory to manage.
17304 **
17305 ** This routine is only called by sqlite3_config(), and therefore
17306 ** is not required to be threadsafe (it is not).
17307 */
17308 SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetMemsys3(void){
17309   static const sqlite3_mem_methods mempoolMethods = {
17310      memsys3Malloc,
17311      memsys3Free,
17312      memsys3Realloc,
17313      memsys3Size,
17314      memsys3Roundup,
17315      memsys3Init,
17316      memsys3Shutdown,
17317      0
17318   };
17319   return &mempoolMethods;
17320 }
17321 
17322 #endif /* SQLITE_ENABLE_MEMSYS3 */
17323 
17324 /************** End of mem3.c ************************************************/
17325 /************** Begin file mem5.c ********************************************/
17326 /*
17327 ** 2007 October 14
17328 **
17329 ** The author disclaims copyright to this source code.  In place of
17330 ** a legal notice, here is a blessing:
17331 **
17332 **    May you do good and not evil.
17333 **    May you find forgiveness for yourself and forgive others.
17334 **    May you share freely, never taking more than you give.
17335 **
17336 *************************************************************************
17337 ** This file contains the C functions that implement a memory
17338 ** allocation subsystem for use by SQLite. 
17339 **
17340 ** This version of the memory allocation subsystem omits all
17341 ** use of malloc(). The application gives SQLite a block of memory
17342 ** before calling sqlite3_initialize() from which allocations
17343 ** are made and returned by the xMalloc() and xRealloc() 
17344 ** implementations. Once sqlite3_initialize() has been called,
17345 ** the amount of memory available to SQLite is fixed and cannot
17346 ** be changed.
17347 **
17348 ** This version of the memory allocation subsystem is included
17349 ** in the build only if SQLITE_ENABLE_MEMSYS5 is defined.
17350 **
17351 ** This memory allocator uses the following algorithm:
17352 **
17353 **   1.  All memory allocations sizes are rounded up to a power of 2.
17354 **
17355 **   2.  If two adjacent free blocks are the halves of a larger block,
17356 **       then the two blocks are coalesed into the single larger block.
17357 **
17358 **   3.  New memory is allocated from the first available free block.
17359 **
17360 ** This algorithm is described in: J. M. Robson. "Bounds for Some Functions
17361 ** Concerning Dynamic Storage Allocation". Journal of the Association for
17362 ** Computing Machinery, Volume 21, Number 8, July 1974, pages 491-499.
17363 ** 
17364 ** Let n be the size of the largest allocation divided by the minimum
17365 ** allocation size (after rounding all sizes up to a power of 2.)  Let M
17366 ** be the maximum amount of memory ever outstanding at one time.  Let
17367 ** N be the total amount of memory available for allocation.  Robson
17368 ** proved that this memory allocator will never breakdown due to 
17369 ** fragmentation as long as the following constraint holds:
17370 **
17371 **      N >=  M*(1 + log2(n)/2) - n + 1
17372 **
17373 ** The sqlite3_status() logic tracks the maximum values of n and M so
17374 ** that an application can, at any time, verify this constraint.
17375 */
17376 
17377 /*
17378 ** This version of the memory allocator is used only when 
17379 ** SQLITE_ENABLE_MEMSYS5 is defined.
17380 */
17381 #ifdef SQLITE_ENABLE_MEMSYS5
17382 
17383 /*
17384 ** A minimum allocation is an instance of the following structure.
17385 ** Larger allocations are an array of these structures where the
17386 ** size of the array is a power of 2.
17387 **
17388 ** The size of this object must be a power of two.  That fact is
17389 ** verified in memsys5Init().
17390 */
17391 typedef struct Mem5Link Mem5Link;
17392 struct Mem5Link {
17393   int next;       /* Index of next free chunk */
17394   int prev;       /* Index of previous free chunk */
17395 };
17396 
17397 /*
17398 ** Maximum size of any allocation is ((1<<LOGMAX)*mem5.szAtom). Since
17399 ** mem5.szAtom is always at least 8 and 32-bit integers are used,
17400 ** it is not actually possible to reach this limit.
17401 */
17402 #define LOGMAX 30
17403 
17404 /*
17405 ** Masks used for mem5.aCtrl[] elements.
17406 */
17407 #define CTRL_LOGSIZE  0x1f    /* Log2 Size of this block */
17408 #define CTRL_FREE     0x20    /* True if not checked out */
17409 
17410 /*
17411 ** All of the static variables used by this module are collected
17412 ** into a single structure named "mem5".  This is to keep the
17413 ** static variables organized and to reduce namespace pollution
17414 ** when this module is combined with other in the amalgamation.
17415 */
17416 static SQLITE_WSD struct Mem5Global {
17417   /*
17418   ** Memory available for allocation
17419   */
17420   int szAtom;      /* Smallest possible allocation in bytes */
17421   int nBlock;      /* Number of szAtom sized blocks in zPool */
17422   u8 *zPool;       /* Memory available to be allocated */
17423   
17424   /*
17425   ** Mutex to control access to the memory allocation subsystem.
17426   */
17427   sqlite3_mutex *mutex;
17428 
17429   /*
17430   ** Performance statistics
17431   */
17432   u64 nAlloc;         /* Total number of calls to malloc */
17433   u64 totalAlloc;     /* Total of all malloc calls - includes internal frag */
17434   u64 totalExcess;    /* Total internal fragmentation */
17435   u32 currentOut;     /* Current checkout, including internal fragmentation */
17436   u32 currentCount;   /* Current number of distinct checkouts */
17437   u32 maxOut;         /* Maximum instantaneous currentOut */
17438   u32 maxCount;       /* Maximum instantaneous currentCount */
17439   u32 maxRequest;     /* Largest allocation (exclusive of internal frag) */
17440   
17441   /*
17442   ** Lists of free blocks.  aiFreelist[0] is a list of free blocks of
17443   ** size mem5.szAtom.  aiFreelist[1] holds blocks of size szAtom*2.
17444   ** and so forth.
17445   */
17446   int aiFreelist[LOGMAX+1];
17447 
17448   /*
17449   ** Space for tracking which blocks are checked out and the size
17450   ** of each block.  One byte per block.
17451   */
17452   u8 *aCtrl;
17453 
17454 } mem5;
17455 
17456 /*
17457 ** Access the static variable through a macro for SQLITE_OMIT_WSD.
17458 */
17459 #define mem5 GLOBAL(struct Mem5Global, mem5)
17460 
17461 /*
17462 ** Assuming mem5.zPool is divided up into an array of Mem5Link
17463 ** structures, return a pointer to the idx-th such link.
17464 */
17465 #define MEM5LINK(idx) ((Mem5Link *)(&mem5.zPool[(idx)*mem5.szAtom]))
17466 
17467 /*
17468 ** Unlink the chunk at mem5.aPool[i] from list it is currently
17469 ** on.  It should be found on mem5.aiFreelist[iLogsize].
17470 */
17471 static void memsys5Unlink(int i, int iLogsize){
17472   int next, prev;
17473   assert( i>=0 && i<mem5.nBlock );
17474   assert( iLogsize>=0 && iLogsize<=LOGMAX );
17475   assert( (mem5.aCtrl[i] & CTRL_LOGSIZE)==iLogsize );
17476 
17477   next = MEM5LINK(i)->next;
17478   prev = MEM5LINK(i)->prev;
17479   if( prev<0 ){
17480     mem5.aiFreelist[iLogsize] = next;
17481   }else{
17482     MEM5LINK(prev)->next = next;
17483   }
17484   if( next>=0 ){
17485     MEM5LINK(next)->prev = prev;
17486   }
17487 }
17488 
17489 /*
17490 ** Link the chunk at mem5.aPool[i] so that is on the iLogsize
17491 ** free list.
17492 */
17493 static void memsys5Link(int i, int iLogsize){
17494   int x;
17495   assert( sqlite3_mutex_held(mem5.mutex) );
17496   assert( i>=0 && i<mem5.nBlock );
17497   assert( iLogsize>=0 && iLogsize<=LOGMAX );
17498   assert( (mem5.aCtrl[i] & CTRL_LOGSIZE)==iLogsize );
17499 
17500   x = MEM5LINK(i)->next = mem5.aiFreelist[iLogsize];
17501   MEM5LINK(i)->prev = -1;
17502   if( x>=0 ){
17503     assert( x<mem5.nBlock );
17504     MEM5LINK(x)->prev = i;
17505   }
17506   mem5.aiFreelist[iLogsize] = i;
17507 }
17508 
17509 /*
17510 ** If the STATIC_MEM mutex is not already held, obtain it now. The mutex
17511 ** will already be held (obtained by code in malloc.c) if
17512 ** sqlite3GlobalConfig.bMemStat is true.
17513 */
17514 static void memsys5Enter(void){
17515   sqlite3_mutex_enter(mem5.mutex);
17516 }
17517 static void memsys5Leave(void){
17518   sqlite3_mutex_leave(mem5.mutex);
17519 }
17520 
17521 /*
17522 ** Return the size of an outstanding allocation, in bytes.  The
17523 ** size returned omits the 8-byte header overhead.  This only
17524 ** works for chunks that are currently checked out.
17525 */
17526 static int memsys5Size(void *p){
17527   int iSize = 0;
17528   if( p ){
17529     int i = (int)(((u8 *)p-mem5.zPool)/mem5.szAtom);
17530     assert( i>=0 && i<mem5.nBlock );
17531     iSize = mem5.szAtom * (1 << (mem5.aCtrl[i]&CTRL_LOGSIZE));
17532   }
17533   return iSize;
17534 }
17535 
17536 /*
17537 ** Return a block of memory of at least nBytes in size.
17538 ** Return NULL if unable.  Return NULL if nBytes==0.
17539 **
17540 ** The caller guarantees that nByte is positive.
17541 **
17542 ** The caller has obtained a mutex prior to invoking this
17543 ** routine so there is never any chance that two or more
17544 ** threads can be in this routine at the same time.
17545 */
17546 static void *memsys5MallocUnsafe(int nByte){
17547   int i;           /* Index of a mem5.aPool[] slot */
17548   int iBin;        /* Index into mem5.aiFreelist[] */
17549   int iFullSz;     /* Size of allocation rounded up to power of 2 */
17550   int iLogsize;    /* Log2 of iFullSz/POW2_MIN */
17551 
17552   /* nByte must be a positive */
17553   assert( nByte>0 );
17554 
17555   /* Keep track of the maximum allocation request.  Even unfulfilled
17556   ** requests are counted */
17557   if( (u32)nByte>mem5.maxRequest ){
17558     mem5.maxRequest = nByte;
17559   }
17560 
17561   /* Abort if the requested allocation size is larger than the largest
17562   ** power of two that we can represent using 32-bit signed integers.
17563   */
17564   if( nByte > 0x40000000 ){
17565     return 0;
17566   }
17567 
17568   /* Round nByte up to the next valid power of two */
17569   for(iFullSz=mem5.szAtom, iLogsize=0; iFullSz<nByte; iFullSz *= 2, iLogsize++){}
17570 
17571   /* Make sure mem5.aiFreelist[iLogsize] contains at least one free
17572   ** block.  If not, then split a block of the next larger power of
17573   ** two in order to create a new free block of size iLogsize.
17574   */
17575   for(iBin=iLogsize; mem5.aiFreelist[iBin]<0 && iBin<=LOGMAX; iBin++){}
17576   if( iBin>LOGMAX ){
17577     testcase( sqlite3GlobalConfig.xLog!=0 );
17578     sqlite3_log(SQLITE_NOMEM, "failed to allocate %u bytes", nByte);
17579     return 0;
17580   }
17581   i = mem5.aiFreelist[iBin];
17582   memsys5Unlink(i, iBin);
17583   while( iBin>iLogsize ){
17584     int newSize;
17585 
17586     iBin--;
17587     newSize = 1 << iBin;
17588     mem5.aCtrl[i+newSize] = CTRL_FREE | iBin;
17589     memsys5Link(i+newSize, iBin);
17590   }
17591   mem5.aCtrl[i] = iLogsize;
17592 
17593   /* Update allocator performance statistics. */
17594   mem5.nAlloc++;
17595   mem5.totalAlloc += iFullSz;
17596   mem5.totalExcess += iFullSz - nByte;
17597   mem5.currentCount++;
17598   mem5.currentOut += iFullSz;
17599   if( mem5.maxCount<mem5.currentCount ) mem5.maxCount = mem5.currentCount;
17600   if( mem5.maxOut<mem5.currentOut ) mem5.maxOut = mem5.currentOut;
17601 
17602   /* Return a pointer to the allocated memory. */
17603   return (void*)&mem5.zPool[i*mem5.szAtom];
17604 }
17605 
17606 /*
17607 ** Free an outstanding memory allocation.
17608 */
17609 static void memsys5FreeUnsafe(void *pOld){
17610   u32 size, iLogsize;
17611   int iBlock;
17612 
17613   /* Set iBlock to the index of the block pointed to by pOld in 
17614   ** the array of mem5.szAtom byte blocks pointed to by mem5.zPool.
17615   */
17616   iBlock = (int)(((u8 *)pOld-mem5.zPool)/mem5.szAtom);
17617 
17618   /* Check that the pointer pOld points to a valid, non-free block. */
17619   assert( iBlock>=0 && iBlock<mem5.nBlock );
17620   assert( ((u8 *)pOld-mem5.zPool)%mem5.szAtom==0 );
17621   assert( (mem5.aCtrl[iBlock] & CTRL_FREE)==0 );
17622 
17623   iLogsize = mem5.aCtrl[iBlock] & CTRL_LOGSIZE;
17624   size = 1<<iLogsize;
17625   assert( iBlock+size-1<(u32)mem5.nBlock );
17626 
17627   mem5.aCtrl[iBlock] |= CTRL_FREE;
17628   mem5.aCtrl[iBlock+size-1] |= CTRL_FREE;
17629   assert( mem5.currentCount>0 );
17630   assert( mem5.currentOut>=(size*mem5.szAtom) );
17631   mem5.currentCount--;
17632   mem5.currentOut -= size*mem5.szAtom;
17633   assert( mem5.currentOut>0 || mem5.currentCount==0 );
17634   assert( mem5.currentCount>0 || mem5.currentOut==0 );
17635 
17636   mem5.aCtrl[iBlock] = CTRL_FREE | iLogsize;
17637   while( ALWAYS(iLogsize<LOGMAX) ){
17638     int iBuddy;
17639     if( (iBlock>>iLogsize) & 1 ){
17640       iBuddy = iBlock - size;
17641     }else{
17642       iBuddy = iBlock + size;
17643     }
17644     assert( iBuddy>=0 );
17645     if( (iBuddy+(1<<iLogsize))>mem5.nBlock ) break;
17646     if( mem5.aCtrl[iBuddy]!=(CTRL_FREE | iLogsize) ) break;
17647     memsys5Unlink(iBuddy, iLogsize);
17648     iLogsize++;
17649     if( iBuddy<iBlock ){
17650       mem5.aCtrl[iBuddy] = CTRL_FREE | iLogsize;
17651       mem5.aCtrl[iBlock] = 0;
17652       iBlock = iBuddy;
17653     }else{
17654       mem5.aCtrl[iBlock] = CTRL_FREE | iLogsize;
17655       mem5.aCtrl[iBuddy] = 0;
17656     }
17657     size *= 2;
17658   }
17659   memsys5Link(iBlock, iLogsize);
17660 }
17661 
17662 /*
17663 ** Allocate nBytes of memory.
17664 */
17665 static void *memsys5Malloc(int nBytes){
17666   sqlite3_int64 *p = 0;
17667   if( nBytes>0 ){
17668     memsys5Enter();
17669     p = memsys5MallocUnsafe(nBytes);
17670     memsys5Leave();
17671   }
17672   return (void*)p; 
17673 }
17674 
17675 /*
17676 ** Free memory.
17677 **
17678 ** The outer layer memory allocator prevents this routine from
17679 ** being called with pPrior==0.
17680 */
17681 static void memsys5Free(void *pPrior){
17682   assert( pPrior!=0 );
17683   memsys5Enter();
17684   memsys5FreeUnsafe(pPrior);
17685   memsys5Leave();  
17686 }
17687 
17688 /*
17689 ** Change the size of an existing memory allocation.
17690 **
17691 ** The outer layer memory allocator prevents this routine from
17692 ** being called with pPrior==0.  
17693 **
17694 ** nBytes is always a value obtained from a prior call to
17695 ** memsys5Round().  Hence nBytes is always a non-negative power
17696 ** of two.  If nBytes==0 that means that an oversize allocation
17697 ** (an allocation larger than 0x40000000) was requested and this
17698 ** routine should return 0 without freeing pPrior.
17699 */
17700 static void *memsys5Realloc(void *pPrior, int nBytes){
17701   int nOld;
17702   void *p;
17703   assert( pPrior!=0 );
17704   assert( (nBytes&(nBytes-1))==0 );  /* EV: R-46199-30249 */
17705   assert( nBytes>=0 );
17706   if( nBytes==0 ){
17707     return 0;
17708   }
17709   nOld = memsys5Size(pPrior);
17710   if( nBytes<=nOld ){
17711     return pPrior;
17712   }
17713   memsys5Enter();
17714   p = memsys5MallocUnsafe(nBytes);
17715   if( p ){
17716     memcpy(p, pPrior, nOld);
17717     memsys5FreeUnsafe(pPrior);
17718   }
17719   memsys5Leave();
17720   return p;
17721 }
17722 
17723 /*
17724 ** Round up a request size to the next valid allocation size.  If
17725 ** the allocation is too large to be handled by this allocation system,
17726 ** return 0.
17727 **
17728 ** All allocations must be a power of two and must be expressed by a
17729 ** 32-bit signed integer.  Hence the largest allocation is 0x40000000
17730 ** or 1073741824 bytes.
17731 */
17732 static int memsys5Roundup(int n){
17733   int iFullSz;
17734   if( n > 0x40000000 ) return 0;
17735   for(iFullSz=mem5.szAtom; iFullSz<n; iFullSz *= 2);
17736   return iFullSz;
17737 }
17738 
17739 /*
17740 ** Return the ceiling of the logarithm base 2 of iValue.
17741 **
17742 ** Examples:   memsys5Log(1) -> 0
17743 **             memsys5Log(2) -> 1
17744 **             memsys5Log(4) -> 2
17745 **             memsys5Log(5) -> 3
17746 **             memsys5Log(8) -> 3
17747 **             memsys5Log(9) -> 4
17748 */
17749 static int memsys5Log(int iValue){
17750   int iLog;
17751   for(iLog=0; (iLog<(int)((sizeof(int)*8)-1)) && (1<<iLog)<iValue; iLog++);
17752   return iLog;
17753 }
17754 
17755 /*
17756 ** Initialize the memory allocator.
17757 **
17758 ** This routine is not threadsafe.  The caller must be holding a mutex
17759 ** to prevent multiple threads from entering at the same time.
17760 */
17761 static int memsys5Init(void *NotUsed){
17762   int ii;            /* Loop counter */
17763   int nByte;         /* Number of bytes of memory available to this allocator */
17764   u8 *zByte;         /* Memory usable by this allocator */
17765   int nMinLog;       /* Log base 2 of minimum allocation size in bytes */
17766   int iOffset;       /* An offset into mem5.aCtrl[] */
17767 
17768   UNUSED_PARAMETER(NotUsed);
17769 
17770   /* For the purposes of this routine, disable the mutex */
17771   mem5.mutex = 0;
17772 
17773   /* The size of a Mem5Link object must be a power of two.  Verify that
17774   ** this is case.
17775   */
17776   assert( (sizeof(Mem5Link)&(sizeof(Mem5Link)-1))==0 );
17777 
17778   nByte = sqlite3GlobalConfig.nHeap;
17779   zByte = (u8*)sqlite3GlobalConfig.pHeap;
17780   assert( zByte!=0 );  /* sqlite3_config() does not allow otherwise */
17781 
17782   /* boundaries on sqlite3GlobalConfig.mnReq are enforced in sqlite3_config() */
17783   nMinLog = memsys5Log(sqlite3GlobalConfig.mnReq);
17784   mem5.szAtom = (1<<nMinLog);
17785   while( (int)sizeof(Mem5Link)>mem5.szAtom ){
17786     mem5.szAtom = mem5.szAtom << 1;
17787   }
17788 
17789   mem5.nBlock = (nByte / (mem5.szAtom+sizeof(u8)));
17790   mem5.zPool = zByte;
17791   mem5.aCtrl = (u8 *)&mem5.zPool[mem5.nBlock*mem5.szAtom];
17792 
17793   for(ii=0; ii<=LOGMAX; ii++){
17794     mem5.aiFreelist[ii] = -1;
17795   }
17796 
17797   iOffset = 0;
17798   for(ii=LOGMAX; ii>=0; ii--){
17799     int nAlloc = (1<<ii);
17800     if( (iOffset+nAlloc)<=mem5.nBlock ){
17801       mem5.aCtrl[iOffset] = ii | CTRL_FREE;
17802       memsys5Link(iOffset, ii);
17803       iOffset += nAlloc;
17804     }
17805     assert((iOffset+nAlloc)>mem5.nBlock);
17806   }
17807 
17808   /* If a mutex is required for normal operation, allocate one */
17809   if( sqlite3GlobalConfig.bMemstat==0 ){
17810     mem5.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM);
17811   }
17812 
17813   return SQLITE_OK;
17814 }
17815 
17816 /*
17817 ** Deinitialize this module.
17818 */
17819 static void memsys5Shutdown(void *NotUsed){
17820   UNUSED_PARAMETER(NotUsed);
17821   mem5.mutex = 0;
17822   return;
17823 }
17824 
17825 #ifdef SQLITE_TEST
17826 /*
17827 ** Open the file indicated and write a log of all unfreed memory 
17828 ** allocations into that log.
17829 */
17830 SQLITE_PRIVATE void sqlite3Memsys5Dump(const char *zFilename){
17831   FILE *out;
17832   int i, j, n;
17833   int nMinLog;
17834 
17835   if( zFilename==0 || zFilename[0]==0 ){
17836     out = stdout;
17837   }else{
17838     out = fopen(zFilename, "w");
17839     if( out==0 ){
17840       fprintf(stderr, "** Unable to output memory debug output log: %s **\n",
17841                       zFilename);
17842       return;
17843     }
17844   }
17845   memsys5Enter();
17846   nMinLog = memsys5Log(mem5.szAtom);
17847   for(i=0; i<=LOGMAX && i+nMinLog<32; i++){
17848     for(n=0, j=mem5.aiFreelist[i]; j>=0; j = MEM5LINK(j)->next, n++){}
17849     fprintf(out, "freelist items of size %d: %d\n", mem5.szAtom << i, n);
17850   }
17851   fprintf(out, "mem5.nAlloc       = %llu\n", mem5.nAlloc);
17852   fprintf(out, "mem5.totalAlloc   = %llu\n", mem5.totalAlloc);
17853   fprintf(out, "mem5.totalExcess  = %llu\n", mem5.totalExcess);
17854   fprintf(out, "mem5.currentOut   = %u\n", mem5.currentOut);
17855   fprintf(out, "mem5.currentCount = %u\n", mem5.currentCount);
17856   fprintf(out, "mem5.maxOut       = %u\n", mem5.maxOut);
17857   fprintf(out, "mem5.maxCount     = %u\n", mem5.maxCount);
17858   fprintf(out, "mem5.maxRequest   = %u\n", mem5.maxRequest);
17859   memsys5Leave();
17860   if( out==stdout ){
17861     fflush(stdout);
17862   }else{
17863     fclose(out);
17864   }
17865 }
17866 #endif
17867 
17868 /*
17869 ** This routine is the only routine in this file with external 
17870 ** linkage. It returns a pointer to a static sqlite3_mem_methods
17871 ** struct populated with the memsys5 methods.
17872 */
17873 SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetMemsys5(void){
17874   static const sqlite3_mem_methods memsys5Methods = {
17875      memsys5Malloc,
17876      memsys5Free,
17877      memsys5Realloc,
17878      memsys5Size,
17879      memsys5Roundup,
17880      memsys5Init,
17881      memsys5Shutdown,
17882      0
17883   };
17884   return &memsys5Methods;
17885 }
17886 
17887 #endif /* SQLITE_ENABLE_MEMSYS5 */
17888 
17889 /************** End of mem5.c ************************************************/
17890 /************** Begin file mutex.c *******************************************/
17891 /*
17892 ** 2007 August 14
17893 **
17894 ** The author disclaims copyright to this source code.  In place of
17895 ** a legal notice, here is a blessing:
17896 **
17897 **    May you do good and not evil.
17898 **    May you find forgiveness for yourself and forgive others.
17899 **    May you share freely, never taking more than you give.
17900 **
17901 *************************************************************************
17902 ** This file contains the C functions that implement mutexes.
17903 **
17904 ** This file contains code that is common across all mutex implementations.
17905 */
17906 
17907 #if defined(SQLITE_DEBUG) && !defined(SQLITE_MUTEX_OMIT)
17908 /*
17909 ** For debugging purposes, record when the mutex subsystem is initialized
17910 ** and uninitialized so that we can assert() if there is an attempt to
17911 ** allocate a mutex while the system is uninitialized.
17912 */
17913 static SQLITE_WSD int mutexIsInit = 0;
17914 #endif /* SQLITE_DEBUG */
17915 
17916 
17917 #ifndef SQLITE_MUTEX_OMIT
17918 /*
17919 ** Initialize the mutex system.
17920 */
17921 SQLITE_PRIVATE int sqlite3MutexInit(void){ 
17922   int rc = SQLITE_OK;
17923   if( !sqlite3GlobalConfig.mutex.xMutexAlloc ){
17924     /* If the xMutexAlloc method has not been set, then the user did not
17925     ** install a mutex implementation via sqlite3_config() prior to 
17926     ** sqlite3_initialize() being called. This block copies pointers to
17927     ** the default implementation into the sqlite3GlobalConfig structure.
17928     */
17929     sqlite3_mutex_methods const *pFrom;
17930     sqlite3_mutex_methods *pTo = &sqlite3GlobalConfig.mutex;
17931 
17932     if( sqlite3GlobalConfig.bCoreMutex ){
17933       pFrom = sqlite3DefaultMutex();
17934     }else{
17935       pFrom = sqlite3NoopMutex();
17936     }
17937     memcpy(pTo, pFrom, offsetof(sqlite3_mutex_methods, xMutexAlloc));
17938     memcpy(&pTo->xMutexFree, &pFrom->xMutexFree,
17939            sizeof(*pTo) - offsetof(sqlite3_mutex_methods, xMutexFree));
17940     pTo->xMutexAlloc = pFrom->xMutexAlloc;
17941   }
17942   rc = sqlite3GlobalConfig.mutex.xMutexInit();
17943 
17944 #ifdef SQLITE_DEBUG
17945   GLOBAL(int, mutexIsInit) = 1;
17946 #endif
17947 
17948   return rc;
17949 }
17950 
17951 /*
17952 ** Shutdown the mutex system. This call frees resources allocated by
17953 ** sqlite3MutexInit().
17954 */
17955 SQLITE_PRIVATE int sqlite3MutexEnd(void){
17956   int rc = SQLITE_OK;
17957   if( sqlite3GlobalConfig.mutex.xMutexEnd ){
17958     rc = sqlite3GlobalConfig.mutex.xMutexEnd();
17959   }
17960 
17961 #ifdef SQLITE_DEBUG
17962   GLOBAL(int, mutexIsInit) = 0;
17963 #endif
17964 
17965   return rc;
17966 }
17967 
17968 /*
17969 ** Retrieve a pointer to a static mutex or allocate a new dynamic one.
17970 */
17971 SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int id){
17972 #ifndef SQLITE_OMIT_AUTOINIT
17973   if( sqlite3_initialize() ) return 0;
17974 #endif
17975   return sqlite3GlobalConfig.mutex.xMutexAlloc(id);
17976 }
17977 
17978 SQLITE_PRIVATE sqlite3_mutex *sqlite3MutexAlloc(int id){
17979   if( !sqlite3GlobalConfig.bCoreMutex ){
17980     return 0;
17981   }
17982   assert( GLOBAL(int, mutexIsInit) );
17983   return sqlite3GlobalConfig.mutex.xMutexAlloc(id);
17984 }
17985 
17986 /*
17987 ** Free a dynamic mutex.
17988 */
17989 SQLITE_API void sqlite3_mutex_free(sqlite3_mutex *p){
17990   if( p ){
17991     sqlite3GlobalConfig.mutex.xMutexFree(p);
17992   }
17993 }
17994 
17995 /*
17996 ** Obtain the mutex p. If some other thread already has the mutex, block
17997 ** until it can be obtained.
17998 */
17999 SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex *p){
18000   if( p ){
18001     sqlite3GlobalConfig.mutex.xMutexEnter(p);
18002   }
18003 }
18004 
18005 /*
18006 ** Obtain the mutex p. If successful, return SQLITE_OK. Otherwise, if another
18007 ** thread holds the mutex and it cannot be obtained, return SQLITE_BUSY.
18008 */
18009 SQLITE_API int sqlite3_mutex_try(sqlite3_mutex *p){
18010   int rc = SQLITE_OK;
18011   if( p ){
18012     return sqlite3GlobalConfig.mutex.xMutexTry(p);
18013   }
18014   return rc;
18015 }
18016 
18017 /*
18018 ** The sqlite3_mutex_leave() routine exits a mutex that was previously
18019 ** entered by the same thread.  The behavior is undefined if the mutex 
18020 ** is not currently entered. If a NULL pointer is passed as an argument
18021 ** this function is a no-op.
18022 */
18023 SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex *p){
18024   if( p ){
18025     sqlite3GlobalConfig.mutex.xMutexLeave(p);
18026   }
18027 }
18028 
18029 #ifndef NDEBUG
18030 /*
18031 ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are
18032 ** intended for use inside assert() statements.
18033 */
18034 SQLITE_API int sqlite3_mutex_held(sqlite3_mutex *p){
18035   return p==0 || sqlite3GlobalConfig.mutex.xMutexHeld(p);
18036 }
18037 SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex *p){
18038   return p==0 || sqlite3GlobalConfig.mutex.xMutexNotheld(p);
18039 }
18040 #endif
18041 
18042 #endif /* !defined(SQLITE_MUTEX_OMIT) */
18043 
18044 /************** End of mutex.c ***********************************************/
18045 /************** Begin file mutex_noop.c **************************************/
18046 /*
18047 ** 2008 October 07
18048 **
18049 ** The author disclaims copyright to this source code.  In place of
18050 ** a legal notice, here is a blessing:
18051 **
18052 **    May you do good and not evil.
18053 **    May you find forgiveness for yourself and forgive others.
18054 **    May you share freely, never taking more than you give.
18055 **
18056 *************************************************************************
18057 ** This file contains the C functions that implement mutexes.
18058 **
18059 ** This implementation in this file does not provide any mutual
18060 ** exclusion and is thus suitable for use only in applications
18061 ** that use SQLite in a single thread.  The routines defined
18062 ** here are place-holders.  Applications can substitute working
18063 ** mutex routines at start-time using the
18064 **
18065 **     sqlite3_config(SQLITE_CONFIG_MUTEX,...)
18066 **
18067 ** interface.
18068 **
18069 ** If compiled with SQLITE_DEBUG, then additional logic is inserted
18070 ** that does error checking on mutexes to make sure they are being
18071 ** called correctly.
18072 */
18073 
18074 #ifndef SQLITE_MUTEX_OMIT
18075 
18076 #ifndef SQLITE_DEBUG
18077 /*
18078 ** Stub routines for all mutex methods.
18079 **
18080 ** This routines provide no mutual exclusion or error checking.
18081 */
18082 static int noopMutexInit(void){ return SQLITE_OK; }
18083 static int noopMutexEnd(void){ return SQLITE_OK; }
18084 static sqlite3_mutex *noopMutexAlloc(int id){ 
18085   UNUSED_PARAMETER(id);
18086   return (sqlite3_mutex*)8; 
18087 }
18088 static void noopMutexFree(sqlite3_mutex *p){ UNUSED_PARAMETER(p); return; }
18089 static void noopMutexEnter(sqlite3_mutex *p){ UNUSED_PARAMETER(p); return; }
18090 static int noopMutexTry(sqlite3_mutex *p){
18091   UNUSED_PARAMETER(p);
18092   return SQLITE_OK;
18093 }
18094 static void noopMutexLeave(sqlite3_mutex *p){ UNUSED_PARAMETER(p); return; }
18095 
18096 SQLITE_PRIVATE sqlite3_mutex_methods const *sqlite3NoopMutex(void){
18097   static const sqlite3_mutex_methods sMutex = {
18098     noopMutexInit,
18099     noopMutexEnd,
18100     noopMutexAlloc,
18101     noopMutexFree,
18102     noopMutexEnter,
18103     noopMutexTry,
18104     noopMutexLeave,
18105 
18106     0,
18107     0,
18108   };
18109 
18110   return &sMutex;
18111 }
18112 #endif /* !SQLITE_DEBUG */
18113 
18114 #ifdef SQLITE_DEBUG
18115 /*
18116 ** In this implementation, error checking is provided for testing
18117 ** and debugging purposes.  The mutexes still do not provide any
18118 ** mutual exclusion.
18119 */
18120 
18121 /*
18122 ** The mutex object
18123 */
18124 typedef struct sqlite3_debug_mutex {
18125   int id;     /* The mutex type */
18126   int cnt;    /* Number of entries without a matching leave */
18127 } sqlite3_debug_mutex;
18128 
18129 /*
18130 ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are
18131 ** intended for use inside assert() statements.
18132 */
18133 static int debugMutexHeld(sqlite3_mutex *pX){
18134   sqlite3_debug_mutex *p = (sqlite3_debug_mutex*)pX;
18135   return p==0 || p->cnt>0;
18136 }
18137 static int debugMutexNotheld(sqlite3_mutex *pX){
18138   sqlite3_debug_mutex *p = (sqlite3_debug_mutex*)pX;
18139   return p==0 || p->cnt==0;
18140 }
18141 
18142 /*
18143 ** Initialize and deinitialize the mutex subsystem.
18144 */
18145 static int debugMutexInit(void){ return SQLITE_OK; }
18146 static int debugMutexEnd(void){ return SQLITE_OK; }
18147 
18148 /*
18149 ** The sqlite3_mutex_alloc() routine allocates a new
18150 ** mutex and returns a pointer to it.  If it returns NULL
18151 ** that means that a mutex could not be allocated. 
18152 */
18153 static sqlite3_mutex *debugMutexAlloc(int id){
18154   static sqlite3_debug_mutex aStatic[6];
18155   sqlite3_debug_mutex *pNew = 0;
18156   switch( id ){
18157     case SQLITE_MUTEX_FAST:
18158     case SQLITE_MUTEX_RECURSIVE: {
18159       pNew = sqlite3Malloc(sizeof(*pNew));
18160       if( pNew ){
18161         pNew->id = id;
18162         pNew->cnt = 0;
18163       }
18164       break;
18165     }
18166     default: {
18167       assert( id-2 >= 0 );
18168       assert( id-2 < (int)(sizeof(aStatic)/sizeof(aStatic[0])) );
18169       pNew = &aStatic[id-2];
18170       pNew->id = id;
18171       break;
18172     }
18173   }
18174   return (sqlite3_mutex*)pNew;
18175 }
18176 
18177 /*
18178 ** This routine deallocates a previously allocated mutex.
18179 */
18180 static void debugMutexFree(sqlite3_mutex *pX){
18181   sqlite3_debug_mutex *p = (sqlite3_debug_mutex*)pX;
18182   assert( p->cnt==0 );
18183   assert( p->id==SQLITE_MUTEX_FAST || p->id==SQLITE_MUTEX_RECURSIVE );
18184   sqlite3_free(p);
18185 }
18186 
18187 /*
18188 ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
18189 ** to enter a mutex.  If another thread is already within the mutex,
18190 ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
18191 ** SQLITE_BUSY.  The sqlite3_mutex_try() interface returns SQLITE_OK
18192 ** upon successful entry.  Mutexes created using SQLITE_MUTEX_RECURSIVE can
18193 ** be entered multiple times by the same thread.  In such cases the,
18194 ** mutex must be exited an equal number of times before another thread
18195 ** can enter.  If the same thread tries to enter any other kind of mutex
18196 ** more than once, the behavior is undefined.
18197 */
18198 static void debugMutexEnter(sqlite3_mutex *pX){
18199   sqlite3_debug_mutex *p = (sqlite3_debug_mutex*)pX;
18200   assert( p->id==SQLITE_MUTEX_RECURSIVE || debugMutexNotheld(pX) );
18201   p->cnt++;
18202 }
18203 static int debugMutexTry(sqlite3_mutex *pX){
18204   sqlite3_debug_mutex *p = (sqlite3_debug_mutex*)pX;
18205   assert( p->id==SQLITE_MUTEX_RECURSIVE || debugMutexNotheld(pX) );
18206   p->cnt++;
18207   return SQLITE_OK;
18208 }
18209 
18210 /*
18211 ** The sqlite3_mutex_leave() routine exits a mutex that was
18212 ** previously entered by the same thread.  The behavior
18213 ** is undefined if the mutex is not currently entered or
18214 ** is not currently allocated.  SQLite will never do either.
18215 */
18216 static void debugMutexLeave(sqlite3_mutex *pX){
18217   sqlite3_debug_mutex *p = (sqlite3_debug_mutex*)pX;
18218   assert( debugMutexHeld(pX) );
18219   p->cnt--;
18220   assert( p->id==SQLITE_MUTEX_RECURSIVE || debugMutexNotheld(pX) );
18221 }
18222 
18223 SQLITE_PRIVATE sqlite3_mutex_methods const *sqlite3NoopMutex(void){
18224   static const sqlite3_mutex_methods sMutex = {
18225     debugMutexInit,
18226     debugMutexEnd,
18227     debugMutexAlloc,
18228     debugMutexFree,
18229     debugMutexEnter,
18230     debugMutexTry,
18231     debugMutexLeave,
18232 
18233     debugMutexHeld,
18234     debugMutexNotheld
18235   };
18236 
18237   return &sMutex;
18238 }
18239 #endif /* SQLITE_DEBUG */
18240 
18241 /*
18242 ** If compiled with SQLITE_MUTEX_NOOP, then the no-op mutex implementation
18243 ** is used regardless of the run-time threadsafety setting.
18244 */
18245 #ifdef SQLITE_MUTEX_NOOP
18246 SQLITE_PRIVATE sqlite3_mutex_methods const *sqlite3DefaultMutex(void){
18247   return sqlite3NoopMutex();
18248 }
18249 #endif /* defined(SQLITE_MUTEX_NOOP) */
18250 #endif /* !defined(SQLITE_MUTEX_OMIT) */
18251 
18252 /************** End of mutex_noop.c ******************************************/
18253 /************** Begin file mutex_unix.c **************************************/
18254 /*
18255 ** 2007 August 28
18256 **
18257 ** The author disclaims copyright to this source code.  In place of
18258 ** a legal notice, here is a blessing:
18259 **
18260 **    May you do good and not evil.
18261 **    May you find forgiveness for yourself and forgive others.
18262 **    May you share freely, never taking more than you give.
18263 **
18264 *************************************************************************
18265 ** This file contains the C functions that implement mutexes for pthreads
18266 */
18267 
18268 /*
18269 ** The code in this file is only used if we are compiling threadsafe
18270 ** under unix with pthreads.
18271 **
18272 ** Note that this implementation requires a version of pthreads that
18273 ** supports recursive mutexes.
18274 */
18275 #ifdef SQLITE_MUTEX_PTHREADS
18276 
18277 #include <pthread.h>
18278 
18279 /*
18280 ** The sqlite3_mutex.id, sqlite3_mutex.nRef, and sqlite3_mutex.owner fields
18281 ** are necessary under two condidtions:  (1) Debug builds and (2) using
18282 ** home-grown mutexes.  Encapsulate these conditions into a single #define.
18283 */
18284 #if defined(SQLITE_DEBUG) || defined(SQLITE_HOMEGROWN_RECURSIVE_MUTEX)
18285 # define SQLITE_MUTEX_NREF 1
18286 #else
18287 # define SQLITE_MUTEX_NREF 0
18288 #endif
18289 
18290 /*
18291 ** Each recursive mutex is an instance of the following structure.
18292 */
18293 struct sqlite3_mutex {
18294   pthread_mutex_t mutex;     /* Mutex controlling the lock */
18295 #if SQLITE_MUTEX_NREF
18296   int id;                    /* Mutex type */
18297   volatile int nRef;         /* Number of entrances */
18298   volatile pthread_t owner;  /* Thread that is within this mutex */
18299   int trace;                 /* True to trace changes */
18300 #endif
18301 };
18302 #if SQLITE_MUTEX_NREF
18303 #define SQLITE3_MUTEX_INITIALIZER { PTHREAD_MUTEX_INITIALIZER, 0, 0, (pthread_t)0, 0 }
18304 #else
18305 #define SQLITE3_MUTEX_INITIALIZER { PTHREAD_MUTEX_INITIALIZER }
18306 #endif
18307 
18308 /*
18309 ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are
18310 ** intended for use only inside assert() statements.  On some platforms,
18311 ** there might be race conditions that can cause these routines to
18312 ** deliver incorrect results.  In particular, if pthread_equal() is
18313 ** not an atomic operation, then these routines might delivery
18314 ** incorrect results.  On most platforms, pthread_equal() is a 
18315 ** comparison of two integers and is therefore atomic.  But we are
18316 ** told that HPUX is not such a platform.  If so, then these routines
18317 ** will not always work correctly on HPUX.
18318 **
18319 ** On those platforms where pthread_equal() is not atomic, SQLite
18320 ** should be compiled without -DSQLITE_DEBUG and with -DNDEBUG to
18321 ** make sure no assert() statements are evaluated and hence these
18322 ** routines are never called.
18323 */
18324 #if !defined(NDEBUG) || defined(SQLITE_DEBUG)
18325 static int pthreadMutexHeld(sqlite3_mutex *p){
18326   return (p->nRef!=0 && pthread_equal(p->owner, pthread_self()));
18327 }
18328 static int pthreadMutexNotheld(sqlite3_mutex *p){
18329   return p->nRef==0 || pthread_equal(p->owner, pthread_self())==0;
18330 }
18331 #endif
18332 
18333 /*
18334 ** Initialize and deinitialize the mutex subsystem.
18335 */
18336 static int pthreadMutexInit(void){ return SQLITE_OK; }
18337 static int pthreadMutexEnd(void){ return SQLITE_OK; }
18338 
18339 /*
18340 ** The sqlite3_mutex_alloc() routine allocates a new
18341 ** mutex and returns a pointer to it.  If it returns NULL
18342 ** that means that a mutex could not be allocated.  SQLite
18343 ** will unwind its stack and return an error.  The argument
18344 ** to sqlite3_mutex_alloc() is one of these integer constants:
18345 **
18346 ** <ul>
18347 ** <li>  SQLITE_MUTEX_FAST
18348 ** <li>  SQLITE_MUTEX_RECURSIVE
18349 ** <li>  SQLITE_MUTEX_STATIC_MASTER
18350 ** <li>  SQLITE_MUTEX_STATIC_MEM
18351 ** <li>  SQLITE_MUTEX_STATIC_MEM2
18352 ** <li>  SQLITE_MUTEX_STATIC_PRNG
18353 ** <li>  SQLITE_MUTEX_STATIC_LRU
18354 ** <li>  SQLITE_MUTEX_STATIC_PMEM
18355 ** </ul>
18356 **
18357 ** The first two constants cause sqlite3_mutex_alloc() to create
18358 ** a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
18359 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
18360 ** The mutex implementation does not need to make a distinction
18361 ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
18362 ** not want to.  But SQLite will only request a recursive mutex in
18363 ** cases where it really needs one.  If a faster non-recursive mutex
18364 ** implementation is available on the host platform, the mutex subsystem
18365 ** might return such a mutex in response to SQLITE_MUTEX_FAST.
18366 **
18367 ** The other allowed parameters to sqlite3_mutex_alloc() each return
18368 ** a pointer to a static preexisting mutex.  Six static mutexes are
18369 ** used by the current version of SQLite.  Future versions of SQLite
18370 ** may add additional static mutexes.  Static mutexes are for internal
18371 ** use by SQLite only.  Applications that use SQLite mutexes should
18372 ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
18373 ** SQLITE_MUTEX_RECURSIVE.
18374 **
18375 ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
18376 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
18377 ** returns a different mutex on every call.  But for the static 
18378 ** mutex types, the same mutex is returned on every call that has
18379 ** the same type number.
18380 */
18381 static sqlite3_mutex *pthreadMutexAlloc(int iType){
18382   static sqlite3_mutex staticMutexes[] = {
18383     SQLITE3_MUTEX_INITIALIZER,
18384     SQLITE3_MUTEX_INITIALIZER,
18385     SQLITE3_MUTEX_INITIALIZER,
18386     SQLITE3_MUTEX_INITIALIZER,
18387     SQLITE3_MUTEX_INITIALIZER,
18388     SQLITE3_MUTEX_INITIALIZER
18389   };
18390   sqlite3_mutex *p;
18391   switch( iType ){
18392     case SQLITE_MUTEX_RECURSIVE: {
18393       p = sqlite3MallocZero( sizeof(*p) );
18394       if( p ){
18395 #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
18396         /* If recursive mutexes are not available, we will have to
18397         ** build our own.  See below. */
18398         pthread_mutex_init(&p->mutex, 0);
18399 #else
18400         /* Use a recursive mutex if it is available */
18401         pthread_mutexattr_t recursiveAttr;
18402         pthread_mutexattr_init(&recursiveAttr);
18403         pthread_mutexattr_settype(&recursiveAttr, PTHREAD_MUTEX_RECURSIVE);
18404         pthread_mutex_init(&p->mutex, &recursiveAttr);
18405         pthread_mutexattr_destroy(&recursiveAttr);
18406 #endif
18407 #if SQLITE_MUTEX_NREF
18408         p->id = iType;
18409 #endif
18410       }
18411       break;
18412     }
18413     case SQLITE_MUTEX_FAST: {
18414       p = sqlite3MallocZero( sizeof(*p) );
18415       if( p ){
18416 #if SQLITE_MUTEX_NREF
18417         p->id = iType;
18418 #endif
18419         pthread_mutex_init(&p->mutex, 0);
18420       }
18421       break;
18422     }
18423     default: {
18424       assert( iType-2 >= 0 );
18425       assert( iType-2 < ArraySize(staticMutexes) );
18426       p = &staticMutexes[iType-2];
18427 #if SQLITE_MUTEX_NREF
18428       p->id = iType;
18429 #endif
18430       break;
18431     }
18432   }
18433   return p;
18434 }
18435 
18436 
18437 /*
18438 ** This routine deallocates a previously
18439 ** allocated mutex.  SQLite is careful to deallocate every
18440 ** mutex that it allocates.
18441 */
18442 static void pthreadMutexFree(sqlite3_mutex *p){
18443   assert( p->nRef==0 );
18444   assert( p->id==SQLITE_MUTEX_FAST || p->id==SQLITE_MUTEX_RECURSIVE );
18445   pthread_mutex_destroy(&p->mutex);
18446   sqlite3_free(p);
18447 }
18448 
18449 /*
18450 ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
18451 ** to enter a mutex.  If another thread is already within the mutex,
18452 ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
18453 ** SQLITE_BUSY.  The sqlite3_mutex_try() interface returns SQLITE_OK
18454 ** upon successful entry.  Mutexes created using SQLITE_MUTEX_RECURSIVE can
18455 ** be entered multiple times by the same thread.  In such cases the,
18456 ** mutex must be exited an equal number of times before another thread
18457 ** can enter.  If the same thread tries to enter any other kind of mutex
18458 ** more than once, the behavior is undefined.
18459 */
18460 static void pthreadMutexEnter(sqlite3_mutex *p){
18461   assert( p->id==SQLITE_MUTEX_RECURSIVE || pthreadMutexNotheld(p) );
18462 
18463 #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
18464   /* If recursive mutexes are not available, then we have to grow
18465   ** our own.  This implementation assumes that pthread_equal()
18466   ** is atomic - that it cannot be deceived into thinking self
18467   ** and p->owner are equal if p->owner changes between two values
18468   ** that are not equal to self while the comparison is taking place.
18469   ** This implementation also assumes a coherent cache - that 
18470   ** separate processes cannot read different values from the same
18471   ** address at the same time.  If either of these two conditions
18472   ** are not met, then the mutexes will fail and problems will result.
18473   */
18474   {
18475     pthread_t self = pthread_self();
18476     if( p->nRef>0 && pthread_equal(p->owner, self) ){
18477       p->nRef++;
18478     }else{
18479       pthread_mutex_lock(&p->mutex);
18480       assert( p->nRef==0 );
18481       p->owner = self;
18482       p->nRef = 1;
18483     }
18484   }
18485 #else
18486   /* Use the built-in recursive mutexes if they are available.
18487   */
18488   pthread_mutex_lock(&p->mutex);
18489 #if SQLITE_MUTEX_NREF
18490   assert( p->nRef>0 || p->owner==0 );
18491   p->owner = pthread_self();
18492   p->nRef++;
18493 #endif
18494 #endif
18495 
18496 #ifdef SQLITE_DEBUG
18497   if( p->trace ){
18498     printf("enter mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
18499   }
18500 #endif
18501 }
18502 static int pthreadMutexTry(sqlite3_mutex *p){
18503   int rc;
18504   assert( p->id==SQLITE_MUTEX_RECURSIVE || pthreadMutexNotheld(p) );
18505 
18506 #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
18507   /* If recursive mutexes are not available, then we have to grow
18508   ** our own.  This implementation assumes that pthread_equal()
18509   ** is atomic - that it cannot be deceived into thinking self
18510   ** and p->owner are equal if p->owner changes between two values
18511   ** that are not equal to self while the comparison is taking place.
18512   ** This implementation also assumes a coherent cache - that 
18513   ** separate processes cannot read different values from the same
18514   ** address at the same time.  If either of these two conditions
18515   ** are not met, then the mutexes will fail and problems will result.
18516   */
18517   {
18518     pthread_t self = pthread_self();
18519     if( p->nRef>0 && pthread_equal(p->owner, self) ){
18520       p->nRef++;
18521       rc = SQLITE_OK;
18522     }else if( pthread_mutex_trylock(&p->mutex)==0 ){
18523       assert( p->nRef==0 );
18524       p->owner = self;
18525       p->nRef = 1;
18526       rc = SQLITE_OK;
18527     }else{
18528       rc = SQLITE_BUSY;
18529     }
18530   }
18531 #else
18532   /* Use the built-in recursive mutexes if they are available.
18533   */
18534   if( pthread_mutex_trylock(&p->mutex)==0 ){
18535 #if SQLITE_MUTEX_NREF
18536     p->owner = pthread_self();
18537     p->nRef++;
18538 #endif
18539     rc = SQLITE_OK;
18540   }else{
18541     rc = SQLITE_BUSY;
18542   }
18543 #endif
18544 
18545 #ifdef SQLITE_DEBUG
18546   if( rc==SQLITE_OK && p->trace ){
18547     printf("enter mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
18548   }
18549 #endif
18550   return rc;
18551 }
18552 
18553 /*
18554 ** The sqlite3_mutex_leave() routine exits a mutex that was
18555 ** previously entered by the same thread.  The behavior
18556 ** is undefined if the mutex is not currently entered or
18557 ** is not currently allocated.  SQLite will never do either.
18558 */
18559 static void pthreadMutexLeave(sqlite3_mutex *p){
18560   assert( pthreadMutexHeld(p) );
18561 #if SQLITE_MUTEX_NREF
18562   p->nRef--;
18563   if( p->nRef==0 ) p->owner = 0;
18564 #endif
18565   assert( p->nRef==0 || p->id==SQLITE_MUTEX_RECURSIVE );
18566 
18567 #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
18568   if( p->nRef==0 ){
18569     pthread_mutex_unlock(&p->mutex);
18570   }
18571 #else
18572   pthread_mutex_unlock(&p->mutex);
18573 #endif
18574 
18575 #ifdef SQLITE_DEBUG
18576   if( p->trace ){
18577     printf("leave mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
18578   }
18579 #endif
18580 }
18581 
18582 SQLITE_PRIVATE sqlite3_mutex_methods const *sqlite3DefaultMutex(void){
18583   static const sqlite3_mutex_methods sMutex = {
18584     pthreadMutexInit,
18585     pthreadMutexEnd,
18586     pthreadMutexAlloc,
18587     pthreadMutexFree,
18588     pthreadMutexEnter,
18589     pthreadMutexTry,
18590     pthreadMutexLeave,
18591 #ifdef SQLITE_DEBUG
18592     pthreadMutexHeld,
18593     pthreadMutexNotheld
18594 #else
18595     0,
18596     0
18597 #endif
18598   };
18599 
18600   return &sMutex;
18601 }
18602 
18603 #endif /* SQLITE_MUTEX_PTHREADS */
18604 
18605 /************** End of mutex_unix.c ******************************************/
18606 /************** Begin file mutex_w32.c ***************************************/
18607 /*
18608 ** 2007 August 14
18609 **
18610 ** The author disclaims copyright to this source code.  In place of
18611 ** a legal notice, here is a blessing:
18612 **
18613 **    May you do good and not evil.
18614 **    May you find forgiveness for yourself and forgive others.
18615 **    May you share freely, never taking more than you give.
18616 **
18617 *************************************************************************
18618 ** This file contains the C functions that implement mutexes for win32
18619 */
18620 
18621 /*
18622 ** The code in this file is only used if we are compiling multithreaded
18623 ** on a win32 system.
18624 */
18625 #ifdef SQLITE_MUTEX_W32
18626 
18627 /*
18628 ** Each recursive mutex is an instance of the following structure.
18629 */
18630 struct sqlite3_mutex {
18631   CRITICAL_SECTION mutex;    /* Mutex controlling the lock */
18632   int id;                    /* Mutex type */
18633 #ifdef SQLITE_DEBUG
18634   volatile int nRef;         /* Number of enterances */
18635   volatile DWORD owner;      /* Thread holding this mutex */
18636   int trace;                 /* True to trace changes */
18637 #endif
18638 };
18639 #define SQLITE_W32_MUTEX_INITIALIZER { 0 }
18640 #ifdef SQLITE_DEBUG
18641 #define SQLITE3_MUTEX_INITIALIZER { SQLITE_W32_MUTEX_INITIALIZER, 0, 0L, (DWORD)0, 0 }
18642 #else
18643 #define SQLITE3_MUTEX_INITIALIZER { SQLITE_W32_MUTEX_INITIALIZER, 0 }
18644 #endif
18645 
18646 /*
18647 ** Return true (non-zero) if we are running under WinNT, Win2K, WinXP,
18648 ** or WinCE.  Return false (zero) for Win95, Win98, or WinME.
18649 **
18650 ** Here is an interesting observation:  Win95, Win98, and WinME lack
18651 ** the LockFileEx() API.  But we can still statically link against that
18652 ** API as long as we don't call it win running Win95/98/ME.  A call to
18653 ** this routine is used to determine if the host is Win95/98/ME or
18654 ** WinNT/2K/XP so that we will know whether or not we can safely call
18655 ** the LockFileEx() API.
18656 **
18657 ** mutexIsNT() is only used for the TryEnterCriticalSection() API call,
18658 ** which is only available if your application was compiled with 
18659 ** _WIN32_WINNT defined to a value >= 0x0400.  Currently, the only
18660 ** call to TryEnterCriticalSection() is #ifdef'ed out, so #ifdef 
18661 ** this out as well.
18662 */
18663 #if 0
18664 #if SQLITE_OS_WINCE || SQLITE_OS_WINRT
18665 # define mutexIsNT()  (1)
18666 #else
18667   static int mutexIsNT(void){
18668     static int osType = 0;
18669     if( osType==0 ){
18670       OSVERSIONINFO sInfo;
18671       sInfo.dwOSVersionInfoSize = sizeof(sInfo);
18672       GetVersionEx(&sInfo);
18673       osType = sInfo.dwPlatformId==VER_PLATFORM_WIN32_NT ? 2 : 1;
18674     }
18675     return osType==2;
18676   }
18677 #endif /* SQLITE_OS_WINCE || SQLITE_OS_WINRT */
18678 #endif
18679 
18680 #ifdef SQLITE_DEBUG
18681 /*
18682 ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are
18683 ** intended for use only inside assert() statements.
18684 */
18685 static int winMutexHeld(sqlite3_mutex *p){
18686   return p->nRef!=0 && p->owner==GetCurrentThreadId();
18687 }
18688 static int winMutexNotheld2(sqlite3_mutex *p, DWORD tid){
18689   return p->nRef==0 || p->owner!=tid;
18690 }
18691 static int winMutexNotheld(sqlite3_mutex *p){
18692   DWORD tid = GetCurrentThreadId(); 
18693   return winMutexNotheld2(p, tid);
18694 }
18695 #endif
18696 
18697 
18698 /*
18699 ** Initialize and deinitialize the mutex subsystem.
18700 */
18701 static sqlite3_mutex winMutex_staticMutexes[6] = {
18702   SQLITE3_MUTEX_INITIALIZER,
18703   SQLITE3_MUTEX_INITIALIZER,
18704   SQLITE3_MUTEX_INITIALIZER,
18705   SQLITE3_MUTEX_INITIALIZER,
18706   SQLITE3_MUTEX_INITIALIZER,
18707   SQLITE3_MUTEX_INITIALIZER
18708 };
18709 static int winMutex_isInit = 0;
18710 /* As winMutexInit() and winMutexEnd() are called as part
18711 ** of the sqlite3_initialize and sqlite3_shutdown()
18712 ** processing, the "interlocked" magic is probably not
18713 ** strictly necessary.
18714 */
18715 static LONG winMutex_lock = 0;
18716 
18717 SQLITE_API void sqlite3_win32_sleep(DWORD milliseconds); /* os_win.c */
18718 
18719 static int winMutexInit(void){ 
18720   /* The first to increment to 1 does actual initialization */
18721   if( InterlockedCompareExchange(&winMutex_lock, 1, 0)==0 ){
18722     int i;
18723     for(i=0; i<ArraySize(winMutex_staticMutexes); i++){
18724 #if SQLITE_OS_WINRT
18725       InitializeCriticalSectionEx(&winMutex_staticMutexes[i].mutex, 0, 0);
18726 #else
18727       InitializeCriticalSection(&winMutex_staticMutexes[i].mutex);
18728 #endif
18729     }
18730     winMutex_isInit = 1;
18731   }else{
18732     /* Someone else is in the process of initing the static mutexes */
18733     while( !winMutex_isInit ){
18734       sqlite3_win32_sleep(1);
18735     }
18736   }
18737   return SQLITE_OK; 
18738 }
18739 
18740 static int winMutexEnd(void){ 
18741   /* The first to decrement to 0 does actual shutdown 
18742   ** (which should be the last to shutdown.) */
18743   if( InterlockedCompareExchange(&winMutex_lock, 0, 1)==1 ){
18744     if( winMutex_isInit==1 ){
18745       int i;
18746       for(i=0; i<ArraySize(winMutex_staticMutexes); i++){
18747         DeleteCriticalSection(&winMutex_staticMutexes[i].mutex);
18748       }
18749       winMutex_isInit = 0;
18750     }
18751   }
18752   return SQLITE_OK; 
18753 }
18754 
18755 /*
18756 ** The sqlite3_mutex_alloc() routine allocates a new
18757 ** mutex and returns a pointer to it.  If it returns NULL
18758 ** that means that a mutex could not be allocated.  SQLite
18759 ** will unwind its stack and return an error.  The argument
18760 ** to sqlite3_mutex_alloc() is one of these integer constants:
18761 **
18762 ** <ul>
18763 ** <li>  SQLITE_MUTEX_FAST
18764 ** <li>  SQLITE_MUTEX_RECURSIVE
18765 ** <li>  SQLITE_MUTEX_STATIC_MASTER
18766 ** <li>  SQLITE_MUTEX_STATIC_MEM
18767 ** <li>  SQLITE_MUTEX_STATIC_MEM2
18768 ** <li>  SQLITE_MUTEX_STATIC_PRNG
18769 ** <li>  SQLITE_MUTEX_STATIC_LRU
18770 ** <li>  SQLITE_MUTEX_STATIC_PMEM
18771 ** </ul>
18772 **
18773 ** The first two constants cause sqlite3_mutex_alloc() to create
18774 ** a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
18775 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
18776 ** The mutex implementation does not need to make a distinction
18777 ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
18778 ** not want to.  But SQLite will only request a recursive mutex in
18779 ** cases where it really needs one.  If a faster non-recursive mutex
18780 ** implementation is available on the host platform, the mutex subsystem
18781 ** might return such a mutex in response to SQLITE_MUTEX_FAST.
18782 **
18783 ** The other allowed parameters to sqlite3_mutex_alloc() each return
18784 ** a pointer to a static preexisting mutex.  Six static mutexes are
18785 ** used by the current version of SQLite.  Future versions of SQLite
18786 ** may add additional static mutexes.  Static mutexes are for internal
18787 ** use by SQLite only.  Applications that use SQLite mutexes should
18788 ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
18789 ** SQLITE_MUTEX_RECURSIVE.
18790 **
18791 ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
18792 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
18793 ** returns a different mutex on every call.  But for the static 
18794 ** mutex types, the same mutex is returned on every call that has
18795 ** the same type number.
18796 */
18797 static sqlite3_mutex *winMutexAlloc(int iType){
18798   sqlite3_mutex *p;
18799 
18800   switch( iType ){
18801     case SQLITE_MUTEX_FAST:
18802     case SQLITE_MUTEX_RECURSIVE: {
18803       p = sqlite3MallocZero( sizeof(*p) );
18804       if( p ){  
18805 #ifdef SQLITE_DEBUG
18806         p->id = iType;
18807 #endif
18808 #if SQLITE_OS_WINRT
18809         InitializeCriticalSectionEx(&p->mutex, 0, 0);
18810 #else
18811         InitializeCriticalSection(&p->mutex);
18812 #endif
18813       }
18814       break;
18815     }
18816     default: {
18817       assert( winMutex_isInit==1 );
18818       assert( iType-2 >= 0 );
18819       assert( iType-2 < ArraySize(winMutex_staticMutexes) );
18820       p = &winMutex_staticMutexes[iType-2];
18821 #ifdef SQLITE_DEBUG
18822       p->id = iType;
18823 #endif
18824       break;
18825     }
18826   }
18827   return p;
18828 }
18829 
18830 
18831 /*
18832 ** This routine deallocates a previously
18833 ** allocated mutex.  SQLite is careful to deallocate every
18834 ** mutex that it allocates.
18835 */
18836 static void winMutexFree(sqlite3_mutex *p){
18837   assert( p );
18838   assert( p->nRef==0 && p->owner==0 );
18839   assert( p->id==SQLITE_MUTEX_FAST || p->id==SQLITE_MUTEX_RECURSIVE );
18840   DeleteCriticalSection(&p->mutex);
18841   sqlite3_free(p);
18842 }
18843 
18844 /*
18845 ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
18846 ** to enter a mutex.  If another thread is already within the mutex,
18847 ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
18848 ** SQLITE_BUSY.  The sqlite3_mutex_try() interface returns SQLITE_OK
18849 ** upon successful entry.  Mutexes created using SQLITE_MUTEX_RECURSIVE can
18850 ** be entered multiple times by the same thread.  In such cases the,
18851 ** mutex must be exited an equal number of times before another thread
18852 ** can enter.  If the same thread tries to enter any other kind of mutex
18853 ** more than once, the behavior is undefined.
18854 */
18855 static void winMutexEnter(sqlite3_mutex *p){
18856 #ifdef SQLITE_DEBUG
18857   DWORD tid = GetCurrentThreadId(); 
18858   assert( p->id==SQLITE_MUTEX_RECURSIVE || winMutexNotheld2(p, tid) );
18859 #endif
18860   EnterCriticalSection(&p->mutex);
18861 #ifdef SQLITE_DEBUG
18862   assert( p->nRef>0 || p->owner==0 );
18863   p->owner = tid; 
18864   p->nRef++;
18865   if( p->trace ){
18866     printf("enter mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
18867   }
18868 #endif
18869 }
18870 static int winMutexTry(sqlite3_mutex *p){
18871 #ifndef NDEBUG
18872   DWORD tid = GetCurrentThreadId(); 
18873 #endif
18874   int rc = SQLITE_BUSY;
18875   assert( p->id==SQLITE_MUTEX_RECURSIVE || winMutexNotheld2(p, tid) );
18876   /*
18877   ** The sqlite3_mutex_try() routine is very rarely used, and when it
18878   ** is used it is merely an optimization.  So it is OK for it to always
18879   ** fail.  
18880   **
18881   ** The TryEnterCriticalSection() interface is only available on WinNT.
18882   ** And some windows compilers complain if you try to use it without
18883   ** first doing some #defines that prevent SQLite from building on Win98.
18884   ** For that reason, we will omit this optimization for now.  See
18885   ** ticket #2685.
18886   */
18887 #if 0
18888   if( mutexIsNT() && TryEnterCriticalSection(&p->mutex) ){
18889     p->owner = tid;
18890     p->nRef++;
18891     rc = SQLITE_OK;
18892   }
18893 #else
18894   UNUSED_PARAMETER(p);
18895 #endif
18896 #ifdef SQLITE_DEBUG
18897   if( rc==SQLITE_OK && p->trace ){
18898     printf("try mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
18899   }
18900 #endif
18901   return rc;
18902 }
18903 
18904 /*
18905 ** The sqlite3_mutex_leave() routine exits a mutex that was
18906 ** previously entered by the same thread.  The behavior
18907 ** is undefined if the mutex is not currently entered or
18908 ** is not currently allocated.  SQLite will never do either.
18909 */
18910 static void winMutexLeave(sqlite3_mutex *p){
18911 #ifndef NDEBUG
18912   DWORD tid = GetCurrentThreadId();
18913   assert( p->nRef>0 );
18914   assert( p->owner==tid );
18915   p->nRef--;
18916   if( p->nRef==0 ) p->owner = 0;
18917   assert( p->nRef==0 || p->id==SQLITE_MUTEX_RECURSIVE );
18918 #endif
18919   LeaveCriticalSection(&p->mutex);
18920 #ifdef SQLITE_DEBUG
18921   if( p->trace ){
18922     printf("leave mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
18923   }
18924 #endif
18925 }
18926 
18927 SQLITE_PRIVATE sqlite3_mutex_methods const *sqlite3DefaultMutex(void){
18928   static const sqlite3_mutex_methods sMutex = {
18929     winMutexInit,
18930     winMutexEnd,
18931     winMutexAlloc,
18932     winMutexFree,
18933     winMutexEnter,
18934     winMutexTry,
18935     winMutexLeave,
18936 #ifdef SQLITE_DEBUG
18937     winMutexHeld,
18938     winMutexNotheld
18939 #else
18940     0,
18941     0
18942 #endif
18943   };
18944 
18945   return &sMutex;
18946 }
18947 #endif /* SQLITE_MUTEX_W32 */
18948 
18949 /************** End of mutex_w32.c *******************************************/
18950 /************** Begin file malloc.c ******************************************/
18951 /*
18952 ** 2001 September 15
18953 **
18954 ** The author disclaims copyright to this source code.  In place of
18955 ** a legal notice, here is a blessing:
18956 **
18957 **    May you do good and not evil.
18958 **    May you find forgiveness for yourself and forgive others.
18959 **    May you share freely, never taking more than you give.
18960 **
18961 *************************************************************************
18962 **
18963 ** Memory allocation functions used throughout sqlite.
18964 */
18965 /* #include <stdarg.h> */
18966 
18967 /*
18968 ** Attempt to release up to n bytes of non-essential memory currently
18969 ** held by SQLite. An example of non-essential memory is memory used to
18970 ** cache database pages that are not currently in use.
18971 */
18972 SQLITE_API int sqlite3_release_memory(int n){
18973 #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
18974   return sqlite3PcacheReleaseMemory(n);
18975 #else
18976   /* IMPLEMENTATION-OF: R-34391-24921 The sqlite3_release_memory() routine
18977   ** is a no-op returning zero if SQLite is not compiled with
18978   ** SQLITE_ENABLE_MEMORY_MANAGEMENT. */
18979   UNUSED_PARAMETER(n);
18980   return 0;
18981 #endif
18982 }
18983 
18984 /*
18985 ** An instance of the following object records the location of
18986 ** each unused scratch buffer.
18987 */
18988 typedef struct ScratchFreeslot {
18989   struct ScratchFreeslot *pNext;   /* Next unused scratch buffer */
18990 } ScratchFreeslot;
18991 
18992 /*
18993 ** State information local to the memory allocation subsystem.
18994 */
18995 static SQLITE_WSD struct Mem0Global {
18996   sqlite3_mutex *mutex;         /* Mutex to serialize access */
18997 
18998   /*
18999   ** The alarm callback and its arguments.  The mem0.mutex lock will
19000   ** be held while the callback is running.  Recursive calls into
19001   ** the memory subsystem are allowed, but no new callbacks will be
19002   ** issued.
19003   */
19004   sqlite3_int64 alarmThreshold;
19005   void (*alarmCallback)(void*, sqlite3_int64,int);
19006   void *alarmArg;
19007 
19008   /*
19009   ** Pointers to the end of sqlite3GlobalConfig.pScratch memory
19010   ** (so that a range test can be used to determine if an allocation
19011   ** being freed came from pScratch) and a pointer to the list of
19012   ** unused scratch allocations.
19013   */
19014   void *pScratchEnd;
19015   ScratchFreeslot *pScratchFree;
19016   u32 nScratchFree;
19017 
19018   /*
19019   ** True if heap is nearly "full" where "full" is defined by the
19020   ** sqlite3_soft_heap_limit() setting.
19021   */
19022   int nearlyFull;
19023 } mem0 = { 0, 0, 0, 0, 0, 0, 0, 0 };
19024 
19025 #define mem0 GLOBAL(struct Mem0Global, mem0)
19026 
19027 /*
19028 ** This routine runs when the memory allocator sees that the
19029 ** total memory allocation is about to exceed the soft heap
19030 ** limit.
19031 */
19032 static void softHeapLimitEnforcer(
19033   void *NotUsed, 
19034   sqlite3_int64 NotUsed2,
19035   int allocSize
19036 ){
19037   UNUSED_PARAMETER2(NotUsed, NotUsed2);
19038   sqlite3_release_memory(allocSize);
19039 }
19040 
19041 /*
19042 ** Change the alarm callback
19043 */
19044 static int sqlite3MemoryAlarm(
19045   void(*xCallback)(void *pArg, sqlite3_int64 used,int N),
19046   void *pArg,
19047   sqlite3_int64 iThreshold
19048 ){
19049   int nUsed;
19050   sqlite3_mutex_enter(mem0.mutex);
19051   mem0.alarmCallback = xCallback;
19052   mem0.alarmArg = pArg;
19053   mem0.alarmThreshold = iThreshold;
19054   nUsed = sqlite3StatusValue(SQLITE_STATUS_MEMORY_USED);
19055   mem0.nearlyFull = (iThreshold>0 && iThreshold<=nUsed);
19056   sqlite3_mutex_leave(mem0.mutex);
19057   return SQLITE_OK;
19058 }
19059 
19060 #ifndef SQLITE_OMIT_DEPRECATED
19061 /*
19062 ** Deprecated external interface.  Internal/core SQLite code
19063 ** should call sqlite3MemoryAlarm.
19064 */
19065 SQLITE_API int sqlite3_memory_alarm(
19066   void(*xCallback)(void *pArg, sqlite3_int64 used,int N),
19067   void *pArg,
19068   sqlite3_int64 iThreshold
19069 ){
19070   return sqlite3MemoryAlarm(xCallback, pArg, iThreshold);
19071 }
19072 #endif
19073 
19074 /*
19075 ** Set the soft heap-size limit for the library. Passing a zero or 
19076 ** negative value indicates no limit.
19077 */
19078 SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 n){
19079   sqlite3_int64 priorLimit;
19080   sqlite3_int64 excess;
19081 #ifndef SQLITE_OMIT_AUTOINIT
19082   int rc = sqlite3_initialize();
19083   if( rc ) return -1;
19084 #endif
19085   sqlite3_mutex_enter(mem0.mutex);
19086   priorLimit = mem0.alarmThreshold;
19087   sqlite3_mutex_leave(mem0.mutex);
19088   if( n<0 ) return priorLimit;
19089   if( n>0 ){
19090     sqlite3MemoryAlarm(softHeapLimitEnforcer, 0, n);
19091   }else{
19092     sqlite3MemoryAlarm(0, 0, 0);
19093   }
19094   excess = sqlite3_memory_used() - n;
19095   if( excess>0 ) sqlite3_release_memory((int)(excess & 0x7fffffff));
19096   return priorLimit;
19097 }
19098 SQLITE_API void sqlite3_soft_heap_limit(int n){
19099   if( n<0 ) n = 0;
19100   sqlite3_soft_heap_limit64(n);
19101 }
19102 
19103 /*
19104 ** Initialize the memory allocation subsystem.
19105 */
19106 SQLITE_PRIVATE int sqlite3MallocInit(void){
19107   if( sqlite3GlobalConfig.m.xMalloc==0 ){
19108     sqlite3MemSetDefault();
19109   }
19110   memset(&mem0, 0, sizeof(mem0));
19111   if( sqlite3GlobalConfig.bCoreMutex ){
19112     mem0.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM);
19113   }
19114   if( sqlite3GlobalConfig.pScratch && sqlite3GlobalConfig.szScratch>=100
19115       && sqlite3GlobalConfig.nScratch>0 ){
19116     int i, n, sz;
19117     ScratchFreeslot *pSlot;
19118     sz = ROUNDDOWN8(sqlite3GlobalConfig.szScratch);
19119     sqlite3GlobalConfig.szScratch = sz;
19120     pSlot = (ScratchFreeslot*)sqlite3GlobalConfig.pScratch;
19121     n = sqlite3GlobalConfig.nScratch;
19122     mem0.pScratchFree = pSlot;
19123     mem0.nScratchFree = n;
19124     for(i=0; i<n-1; i++){
19125       pSlot->pNext = (ScratchFreeslot*)(sz+(char*)pSlot);
19126       pSlot = pSlot->pNext;
19127     }
19128     pSlot->pNext = 0;
19129     mem0.pScratchEnd = (void*)&pSlot[1];
19130   }else{
19131     mem0.pScratchEnd = 0;
19132     sqlite3GlobalConfig.pScratch = 0;
19133     sqlite3GlobalConfig.szScratch = 0;
19134     sqlite3GlobalConfig.nScratch = 0;
19135   }
19136   if( sqlite3GlobalConfig.pPage==0 || sqlite3GlobalConfig.szPage<512
19137       || sqlite3GlobalConfig.nPage<1 ){
19138     sqlite3GlobalConfig.pPage = 0;
19139     sqlite3GlobalConfig.szPage = 0;
19140     sqlite3GlobalConfig.nPage = 0;
19141   }
19142   return sqlite3GlobalConfig.m.xInit(sqlite3GlobalConfig.m.pAppData);
19143 }
19144 
19145 /*
19146 ** Return true if the heap is currently under memory pressure - in other
19147 ** words if the amount of heap used is close to the limit set by
19148 ** sqlite3_soft_heap_limit().
19149 */
19150 SQLITE_PRIVATE int sqlite3HeapNearlyFull(void){
19151   return mem0.nearlyFull;
19152 }
19153 
19154 /*
19155 ** Deinitialize the memory allocation subsystem.
19156 */
19157 SQLITE_PRIVATE void sqlite3MallocEnd(void){
19158   if( sqlite3GlobalConfig.m.xShutdown ){
19159     sqlite3GlobalConfig.m.xShutdown(sqlite3GlobalConfig.m.pAppData);
19160   }
19161   memset(&mem0, 0, sizeof(mem0));
19162 }
19163 
19164 /*
19165 ** Return the amount of memory currently checked out.
19166 */
19167 SQLITE_API sqlite3_int64 sqlite3_memory_used(void){
19168   int n, mx;
19169   sqlite3_int64 res;
19170   sqlite3_status(SQLITE_STATUS_MEMORY_USED, &n, &mx, 0);
19171   res = (sqlite3_int64)n;  /* Work around bug in Borland C. Ticket #3216 */
19172   return res;
19173 }
19174 
19175 /*
19176 ** Return the maximum amount of memory that has ever been
19177 ** checked out since either the beginning of this process
19178 ** or since the most recent reset.
19179 */
19180 SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag){
19181   int n, mx;
19182   sqlite3_int64 res;
19183   sqlite3_status(SQLITE_STATUS_MEMORY_USED, &n, &mx, resetFlag);
19184   res = (sqlite3_int64)mx;  /* Work around bug in Borland C. Ticket #3216 */
19185   return res;
19186 }
19187 
19188 /*
19189 ** Trigger the alarm 
19190 */
19191 static void sqlite3MallocAlarm(int nByte){
19192   void (*xCallback)(void*,sqlite3_int64,int);
19193   sqlite3_int64 nowUsed;
19194   void *pArg;
19195   if( mem0.alarmCallback==0 ) return;
19196   xCallback = mem0.alarmCallback;
19197   nowUsed = sqlite3StatusValue(SQLITE_STATUS_MEMORY_USED);
19198   pArg = mem0.alarmArg;
19199   mem0.alarmCallback = 0;
19200   sqlite3_mutex_leave(mem0.mutex);
19201   xCallback(pArg, nowUsed, nByte);
19202   sqlite3_mutex_enter(mem0.mutex);
19203   mem0.alarmCallback = xCallback;
19204   mem0.alarmArg = pArg;
19205 }
19206 
19207 /*
19208 ** Do a memory allocation with statistics and alarms.  Assume the
19209 ** lock is already held.
19210 */
19211 static int mallocWithAlarm(int n, void **pp){
19212   int nFull;
19213   void *p;
19214   assert( sqlite3_mutex_held(mem0.mutex) );
19215   nFull = sqlite3GlobalConfig.m.xRoundup(n);
19216   sqlite3StatusSet(SQLITE_STATUS_MALLOC_SIZE, n);
19217   if( mem0.alarmCallback!=0 ){
19218     int nUsed = sqlite3StatusValue(SQLITE_STATUS_MEMORY_USED);
19219     if( nUsed >= mem0.alarmThreshold - nFull ){
19220       mem0.nearlyFull = 1;
19221       sqlite3MallocAlarm(nFull);
19222     }else{
19223       mem0.nearlyFull = 0;
19224     }
19225   }
19226   p = sqlite3GlobalConfig.m.xMalloc(nFull);
19227 #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
19228   if( p==0 && mem0.alarmCallback ){
19229     sqlite3MallocAlarm(nFull);
19230     p = sqlite3GlobalConfig.m.xMalloc(nFull);
19231   }
19232 #endif
19233   if( p ){
19234     nFull = sqlite3MallocSize(p);
19235     sqlite3StatusAdd(SQLITE_STATUS_MEMORY_USED, nFull);
19236     sqlite3StatusAdd(SQLITE_STATUS_MALLOC_COUNT, 1);
19237   }
19238   *pp = p;
19239   return nFull;
19240 }
19241 
19242 /*
19243 ** Allocate memory.  This routine is like sqlite3_malloc() except that it
19244 ** assumes the memory subsystem has already been initialized.
19245 */
19246 SQLITE_PRIVATE void *sqlite3Malloc(int n){
19247   void *p;
19248   if( n<=0               /* IMP: R-65312-04917 */ 
19249    || n>=0x7fffff00
19250   ){
19251     /* A memory allocation of a number of bytes which is near the maximum
19252     ** signed integer value might cause an integer overflow inside of the
19253     ** xMalloc().  Hence we limit the maximum size to 0x7fffff00, giving
19254     ** 255 bytes of overhead.  SQLite itself will never use anything near
19255     ** this amount.  The only way to reach the limit is with sqlite3_malloc() */
19256     p = 0;
19257   }else if( sqlite3GlobalConfig.bMemstat ){
19258     sqlite3_mutex_enter(mem0.mutex);
19259     mallocWithAlarm(n, &p);
19260     sqlite3_mutex_leave(mem0.mutex);
19261   }else{
19262     p = sqlite3GlobalConfig.m.xMalloc(n);
19263   }
19264   assert( EIGHT_BYTE_ALIGNMENT(p) );  /* IMP: R-04675-44850 */
19265   return p;
19266 }
19267 
19268 /*
19269 ** This version of the memory allocation is for use by the application.
19270 ** First make sure the memory subsystem is initialized, then do the
19271 ** allocation.
19272 */
19273 SQLITE_API void *sqlite3_malloc(int n){
19274 #ifndef SQLITE_OMIT_AUTOINIT
19275   if( sqlite3_initialize() ) return 0;
19276 #endif
19277   return sqlite3Malloc(n);
19278 }
19279 
19280 /*
19281 ** Each thread may only have a single outstanding allocation from
19282 ** xScratchMalloc().  We verify this constraint in the single-threaded
19283 ** case by setting scratchAllocOut to 1 when an allocation
19284 ** is outstanding clearing it when the allocation is freed.
19285 */
19286 #if SQLITE_THREADSAFE==0 && !defined(NDEBUG)
19287 static int scratchAllocOut = 0;
19288 #endif
19289 
19290 
19291 /*
19292 ** Allocate memory that is to be used and released right away.
19293 ** This routine is similar to alloca() in that it is not intended
19294 ** for situations where the memory might be held long-term.  This
19295 ** routine is intended to get memory to old large transient data
19296 ** structures that would not normally fit on the stack of an
19297 ** embedded processor.
19298 */
19299 SQLITE_PRIVATE void *sqlite3ScratchMalloc(int n){
19300   void *p;
19301   assert( n>0 );
19302 
19303   sqlite3_mutex_enter(mem0.mutex);
19304   if( mem0.nScratchFree && sqlite3GlobalConfig.szScratch>=n ){
19305     p = mem0.pScratchFree;
19306     mem0.pScratchFree = mem0.pScratchFree->pNext;
19307     mem0.nScratchFree--;
19308     sqlite3StatusAdd(SQLITE_STATUS_SCRATCH_USED, 1);
19309     sqlite3StatusSet(SQLITE_STATUS_SCRATCH_SIZE, n);
19310     sqlite3_mutex_leave(mem0.mutex);
19311   }else{
19312     if( sqlite3GlobalConfig.bMemstat ){
19313       sqlite3StatusSet(SQLITE_STATUS_SCRATCH_SIZE, n);
19314       n = mallocWithAlarm(n, &p);
19315       if( p ) sqlite3StatusAdd(SQLITE_STATUS_SCRATCH_OVERFLOW, n);
19316       sqlite3_mutex_leave(mem0.mutex);
19317     }else{
19318       sqlite3_mutex_leave(mem0.mutex);
19319       p = sqlite3GlobalConfig.m.xMalloc(n);
19320     }
19321     sqlite3MemdebugSetType(p, MEMTYPE_SCRATCH);
19322   }
19323   assert( sqlite3_mutex_notheld(mem0.mutex) );
19324 
19325 
19326 #if SQLITE_THREADSAFE==0 && !defined(NDEBUG)
19327   /* Verify that no more than two scratch allocations per thread
19328   ** are outstanding at one time.  (This is only checked in the
19329   ** single-threaded case since checking in the multi-threaded case
19330   ** would be much more complicated.) */
19331   assert( scratchAllocOut<=1 );
19332   if( p ) scratchAllocOut++;
19333 #endif
19334 
19335   return p;
19336 }
19337 SQLITE_PRIVATE void sqlite3ScratchFree(void *p){
19338   if( p ){
19339 
19340 #if SQLITE_THREADSAFE==0 && !defined(NDEBUG)
19341     /* Verify that no more than two scratch allocation per thread
19342     ** is outstanding at one time.  (This is only checked in the
19343     ** single-threaded case since checking in the multi-threaded case
19344     ** would be much more complicated.) */
19345     assert( scratchAllocOut>=1 && scratchAllocOut<=2 );
19346     scratchAllocOut--;
19347 #endif
19348 
19349     if( p>=sqlite3GlobalConfig.pScratch && p<mem0.pScratchEnd ){
19350       /* Release memory from the SQLITE_CONFIG_SCRATCH allocation */
19351       ScratchFreeslot *pSlot;
19352       pSlot = (ScratchFreeslot*)p;
19353       sqlite3_mutex_enter(mem0.mutex);
19354       pSlot->pNext = mem0.pScratchFree;
19355       mem0.pScratchFree = pSlot;
19356       mem0.nScratchFree++;
19357       assert( mem0.nScratchFree <= (u32)sqlite3GlobalConfig.nScratch );
19358       sqlite3StatusAdd(SQLITE_STATUS_SCRATCH_USED, -1);
19359       sqlite3_mutex_leave(mem0.mutex);
19360     }else{
19361       /* Release memory back to the heap */
19362       assert( sqlite3MemdebugHasType(p, MEMTYPE_SCRATCH) );
19363       assert( sqlite3MemdebugNoType(p, ~MEMTYPE_SCRATCH) );
19364       sqlite3MemdebugSetType(p, MEMTYPE_HEAP);
19365       if( sqlite3GlobalConfig.bMemstat ){
19366         int iSize = sqlite3MallocSize(p);
19367         sqlite3_mutex_enter(mem0.mutex);
19368         sqlite3StatusAdd(SQLITE_STATUS_SCRATCH_OVERFLOW, -iSize);
19369         sqlite3StatusAdd(SQLITE_STATUS_MEMORY_USED, -iSize);
19370         sqlite3StatusAdd(SQLITE_STATUS_MALLOC_COUNT, -1);
19371         sqlite3GlobalConfig.m.xFree(p);
19372         sqlite3_mutex_leave(mem0.mutex);
19373       }else{
19374         sqlite3GlobalConfig.m.xFree(p);
19375       }
19376     }
19377   }
19378 }
19379 
19380 /*
19381 ** TRUE if p is a lookaside memory allocation from db
19382 */
19383 #ifndef SQLITE_OMIT_LOOKASIDE
19384 static int isLookaside(sqlite3 *db, void *p){
19385   return p && p>=db->lookaside.pStart && p<db->lookaside.pEnd;
19386 }
19387 #else
19388 #define isLookaside(A,B) 0
19389 #endif
19390 
19391 /*
19392 ** Return the size of a memory allocation previously obtained from
19393 ** sqlite3Malloc() or sqlite3_malloc().
19394 */
19395 SQLITE_PRIVATE int sqlite3MallocSize(void *p){
19396   assert( sqlite3MemdebugHasType(p, MEMTYPE_HEAP) );
19397   assert( sqlite3MemdebugNoType(p, MEMTYPE_DB) );
19398   return sqlite3GlobalConfig.m.xSize(p);
19399 }
19400 SQLITE_PRIVATE int sqlite3DbMallocSize(sqlite3 *db, void *p){
19401   assert( db==0 || sqlite3_mutex_held(db->mutex) );
19402   if( db && isLookaside(db, p) ){
19403     return db->lookaside.sz;
19404   }else{
19405     assert( sqlite3MemdebugHasType(p, MEMTYPE_DB) );
19406     assert( sqlite3MemdebugHasType(p, MEMTYPE_LOOKASIDE|MEMTYPE_HEAP) );
19407     assert( db!=0 || sqlite3MemdebugNoType(p, MEMTYPE_LOOKASIDE) );
19408     return sqlite3GlobalConfig.m.xSize(p);
19409   }
19410 }
19411 
19412 /*
19413 ** Free memory previously obtained from sqlite3Malloc().
19414 */
19415 SQLITE_API void sqlite3_free(void *p){
19416   if( p==0 ) return;  /* IMP: R-49053-54554 */
19417   assert( sqlite3MemdebugNoType(p, MEMTYPE_DB) );
19418   assert( sqlite3MemdebugHasType(p, MEMTYPE_HEAP) );
19419   if( sqlite3GlobalConfig.bMemstat ){
19420     sqlite3_mutex_enter(mem0.mutex);
19421     sqlite3StatusAdd(SQLITE_STATUS_MEMORY_USED, -sqlite3MallocSize(p));
19422     sqlite3StatusAdd(SQLITE_STATUS_MALLOC_COUNT, -1);
19423     sqlite3GlobalConfig.m.xFree(p);
19424     sqlite3_mutex_leave(mem0.mutex);
19425   }else{
19426     sqlite3GlobalConfig.m.xFree(p);
19427   }
19428 }
19429 
19430 /*
19431 ** Free memory that might be associated with a particular database
19432 ** connection.
19433 */
19434 SQLITE_PRIVATE void sqlite3DbFree(sqlite3 *db, void *p){
19435   assert( db==0 || sqlite3_mutex_held(db->mutex) );
19436   if( p==0 ) return;
19437   if( db ){
19438     if( db->pnBytesFreed ){
19439       *db->pnBytesFreed += sqlite3DbMallocSize(db, p);
19440       return;
19441     }
19442     if( isLookaside(db, p) ){
19443       LookasideSlot *pBuf = (LookasideSlot*)p;
19444 #if SQLITE_DEBUG
19445       /* Trash all content in the buffer being freed */
19446       memset(p, 0xaa, db->lookaside.sz);
19447 #endif
19448       pBuf->pNext = db->lookaside.pFree;
19449       db->lookaside.pFree = pBuf;
19450       db->lookaside.nOut--;
19451       return;
19452     }
19453   }
19454   assert( sqlite3MemdebugHasType(p, MEMTYPE_DB) );
19455   assert( sqlite3MemdebugHasType(p, MEMTYPE_LOOKASIDE|MEMTYPE_HEAP) );
19456   assert( db!=0 || sqlite3MemdebugNoType(p, MEMTYPE_LOOKASIDE) );
19457   sqlite3MemdebugSetType(p, MEMTYPE_HEAP);
19458   sqlite3_free(p);
19459 }
19460 
19461 /*
19462 ** Change the size of an existing memory allocation
19463 */
19464 SQLITE_PRIVATE void *sqlite3Realloc(void *pOld, int nBytes){
19465   int nOld, nNew, nDiff;
19466   void *pNew;
19467   if( pOld==0 ){
19468     return sqlite3Malloc(nBytes); /* IMP: R-28354-25769 */
19469   }
19470   if( nBytes<=0 ){
19471     sqlite3_free(pOld); /* IMP: R-31593-10574 */
19472     return 0;
19473   }
19474   if( nBytes>=0x7fffff00 ){
19475     /* The 0x7ffff00 limit term is explained in comments on sqlite3Malloc() */
19476     return 0;
19477   }
19478   nOld = sqlite3MallocSize(pOld);
19479   /* IMPLEMENTATION-OF: R-46199-30249 SQLite guarantees that the second
19480   ** argument to xRealloc is always a value returned by a prior call to
19481   ** xRoundup. */
19482   nNew = sqlite3GlobalConfig.m.xRoundup(nBytes);
19483   if( nOld==nNew ){
19484     pNew = pOld;
19485   }else if( sqlite3GlobalConfig.bMemstat ){
19486     sqlite3_mutex_enter(mem0.mutex);
19487     sqlite3StatusSet(SQLITE_STATUS_MALLOC_SIZE, nBytes);
19488     nDiff = nNew - nOld;
19489     if( sqlite3StatusValue(SQLITE_STATUS_MEMORY_USED) >= 
19490           mem0.alarmThreshold-nDiff ){
19491       sqlite3MallocAlarm(nDiff);
19492     }
19493     assert( sqlite3MemdebugHasType(pOld, MEMTYPE_HEAP) );
19494     assert( sqlite3MemdebugNoType(pOld, ~MEMTYPE_HEAP) );
19495     pNew = sqlite3GlobalConfig.m.xRealloc(pOld, nNew);
19496     if( pNew==0 && mem0.alarmCallback ){
19497       sqlite3MallocAlarm(nBytes);
19498       pNew = sqlite3GlobalConfig.m.xRealloc(pOld, nNew);
19499     }
19500     if( pNew ){
19501       nNew = sqlite3MallocSize(pNew);
19502       sqlite3StatusAdd(SQLITE_STATUS_MEMORY_USED, nNew-nOld);
19503     }
19504     sqlite3_mutex_leave(mem0.mutex);
19505   }else{
19506     pNew = sqlite3GlobalConfig.m.xRealloc(pOld, nNew);
19507   }
19508   assert( EIGHT_BYTE_ALIGNMENT(pNew) ); /* IMP: R-04675-44850 */
19509   return pNew;
19510 }
19511 
19512 /*
19513 ** The public interface to sqlite3Realloc.  Make sure that the memory
19514 ** subsystem is initialized prior to invoking sqliteRealloc.
19515 */
19516 SQLITE_API void *sqlite3_realloc(void *pOld, int n){
19517 #ifndef SQLITE_OMIT_AUTOINIT
19518   if( sqlite3_initialize() ) return 0;
19519 #endif
19520   return sqlite3Realloc(pOld, n);
19521 }
19522 
19523 
19524 /*
19525 ** Allocate and zero memory.
19526 */ 
19527 SQLITE_PRIVATE void *sqlite3MallocZero(int n){
19528   void *p = sqlite3Malloc(n);
19529   if( p ){
19530     memset(p, 0, n);
19531   }
19532   return p;
19533 }
19534 
19535 /*
19536 ** Allocate and zero memory.  If the allocation fails, make
19537 ** the mallocFailed flag in the connection pointer.
19538 */
19539 SQLITE_PRIVATE void *sqlite3DbMallocZero(sqlite3 *db, int n){
19540   void *p = sqlite3DbMallocRaw(db, n);
19541   if( p ){
19542     memset(p, 0, n);
19543   }
19544   return p;
19545 }
19546 
19547 /*
19548 ** Allocate and zero memory.  If the allocation fails, make
19549 ** the mallocFailed flag in the connection pointer.
19550 **
19551 ** If db!=0 and db->mallocFailed is true (indicating a prior malloc
19552 ** failure on the same database connection) then always return 0.
19553 ** Hence for a particular database connection, once malloc starts
19554 ** failing, it fails consistently until mallocFailed is reset.
19555 ** This is an important assumption.  There are many places in the
19556 ** code that do things like this:
19557 **
19558 **         int *a = (int*)sqlite3DbMallocRaw(db, 100);
19559 **         int *b = (int*)sqlite3DbMallocRaw(db, 200);
19560 **         if( b ) a[10] = 9;
19561 **
19562 ** In other words, if a subsequent malloc (ex: "b") worked, it is assumed
19563 ** that all prior mallocs (ex: "a") worked too.
19564 */
19565 SQLITE_PRIVATE void *sqlite3DbMallocRaw(sqlite3 *db, int n){
19566   void *p;
19567   assert( db==0 || sqlite3_mutex_held(db->mutex) );
19568   assert( db==0 || db->pnBytesFreed==0 );
19569 #ifndef SQLITE_OMIT_LOOKASIDE
19570   if( db ){
19571     LookasideSlot *pBuf;
19572     if( db->mallocFailed ){
19573       return 0;
19574     }
19575     if( db->lookaside.bEnabled ){
19576       if( n>db->lookaside.sz ){
19577         db->lookaside.anStat[1]++;
19578       }else if( (pBuf = db->lookaside.pFree)==0 ){
19579         db->lookaside.anStat[2]++;
19580       }else{
19581         db->lookaside.pFree = pBuf->pNext;
19582         db->lookaside.nOut++;
19583         db->lookaside.anStat[0]++;
19584         if( db->lookaside.nOut>db->lookaside.mxOut ){
19585           db->lookaside.mxOut = db->lookaside.nOut;
19586         }
19587         return (void*)pBuf;
19588       }
19589     }
19590   }
19591 #else
19592   if( db && db->mallocFailed ){
19593     return 0;
19594   }
19595 #endif
19596   p = sqlite3Malloc(n);
19597   if( !p && db ){
19598     db->mallocFailed = 1;
19599   }
19600   sqlite3MemdebugSetType(p, MEMTYPE_DB |
19601          ((db && db->lookaside.bEnabled) ? MEMTYPE_LOOKASIDE : MEMTYPE_HEAP));
19602   return p;
19603 }
19604 
19605 /*
19606 ** Resize the block of memory pointed to by p to n bytes. If the
19607 ** resize fails, set the mallocFailed flag in the connection object.
19608 */
19609 SQLITE_PRIVATE void *sqlite3DbRealloc(sqlite3 *db, void *p, int n){
19610   void *pNew = 0;
19611   assert( db!=0 );
19612   assert( sqlite3_mutex_held(db->mutex) );
19613   if( db->mallocFailed==0 ){
19614     if( p==0 ){
19615       return sqlite3DbMallocRaw(db, n);
19616     }
19617     if( isLookaside(db, p) ){
19618       if( n<=db->lookaside.sz ){
19619         return p;
19620       }
19621       pNew = sqlite3DbMallocRaw(db, n);
19622       if( pNew ){
19623         memcpy(pNew, p, db->lookaside.sz);
19624         sqlite3DbFree(db, p);
19625       }
19626     }else{
19627       assert( sqlite3MemdebugHasType(p, MEMTYPE_DB) );
19628       assert( sqlite3MemdebugHasType(p, MEMTYPE_LOOKASIDE|MEMTYPE_HEAP) );
19629       sqlite3MemdebugSetType(p, MEMTYPE_HEAP);
19630       pNew = sqlite3_realloc(p, n);
19631       if( !pNew ){
19632         sqlite3MemdebugSetType(p, MEMTYPE_DB|MEMTYPE_HEAP);
19633         db->mallocFailed = 1;
19634       }
19635       sqlite3MemdebugSetType(pNew, MEMTYPE_DB | 
19636             (db->lookaside.bEnabled ? MEMTYPE_LOOKASIDE : MEMTYPE_HEAP));
19637     }
19638   }
19639   return pNew;
19640 }
19641 
19642 /*
19643 ** Attempt to reallocate p.  If the reallocation fails, then free p
19644 ** and set the mallocFailed flag in the database connection.
19645 */
19646 SQLITE_PRIVATE void *sqlite3DbReallocOrFree(sqlite3 *db, void *p, int n){
19647   void *pNew;
19648   pNew = sqlite3DbRealloc(db, p, n);
19649   if( !pNew ){
19650     sqlite3DbFree(db, p);
19651   }
19652   return pNew;
19653 }
19654 
19655 /*
19656 ** Make a copy of a string in memory obtained from sqliteMalloc(). These 
19657 ** functions call sqlite3MallocRaw() directly instead of sqliteMalloc(). This
19658 ** is because when memory debugging is turned on, these two functions are 
19659 ** called via macros that record the current file and line number in the
19660 ** ThreadData structure.
19661 */
19662 SQLITE_PRIVATE char *sqlite3DbStrDup(sqlite3 *db, const char *z){
19663   char *zNew;
19664   size_t n;
19665   if( z==0 ){
19666     return 0;
19667   }
19668   n = sqlite3Strlen30(z) + 1;
19669   assert( (n&0x7fffffff)==n );
19670   zNew = sqlite3DbMallocRaw(db, (int)n);
19671   if( zNew ){
19672     memcpy(zNew, z, n);
19673   }
19674   return zNew;
19675 }
19676 SQLITE_PRIVATE char *sqlite3DbStrNDup(sqlite3 *db, const char *z, int n){
19677   char *zNew;
19678   if( z==0 ){
19679     return 0;
19680   }
19681   assert( (n&0x7fffffff)==n );
19682   zNew = sqlite3DbMallocRaw(db, n+1);
19683   if( zNew ){
19684     memcpy(zNew, z, n);
19685     zNew[n] = 0;
19686   }
19687   return zNew;
19688 }
19689 
19690 /*
19691 ** Create a string from the zFromat argument and the va_list that follows.
19692 ** Store the string in memory obtained from sqliteMalloc() and make *pz
19693 ** point to that string.
19694 */
19695 SQLITE_PRIVATE void sqlite3SetString(char **pz, sqlite3 *db, const char *zFormat, ...){
19696   va_list ap;
19697   char *z;
19698 
19699   va_start(ap, zFormat);
19700   z = sqlite3VMPrintf(db, zFormat, ap);
19701   va_end(ap);
19702   sqlite3DbFree(db, *pz);
19703   *pz = z;
19704 }
19705 
19706 
19707 /*
19708 ** This function must be called before exiting any API function (i.e. 
19709 ** returning control to the user) that has called sqlite3_malloc or
19710 ** sqlite3_realloc.
19711 **
19712 ** The returned value is normally a copy of the second argument to this
19713 ** function. However, if a malloc() failure has occurred since the previous
19714 ** invocation SQLITE_NOMEM is returned instead. 
19715 **
19716 ** If the first argument, db, is not NULL and a malloc() error has occurred,
19717 ** then the connection error-code (the value returned by sqlite3_errcode())
19718 ** is set to SQLITE_NOMEM.
19719 */
19720 SQLITE_PRIVATE int sqlite3ApiExit(sqlite3* db, int rc){
19721   /* If the db handle is not NULL, then we must hold the connection handle
19722   ** mutex here. Otherwise the read (and possible write) of db->mallocFailed 
19723   ** is unsafe, as is the call to sqlite3Error().
19724   */
19725   assert( !db || sqlite3_mutex_held(db->mutex) );
19726   if( db && (db->mallocFailed || rc==SQLITE_IOERR_NOMEM) ){
19727     sqlite3Error(db, SQLITE_NOMEM, 0);
19728     db->mallocFailed = 0;
19729     rc = SQLITE_NOMEM;
19730   }
19731   return rc & (db ? db->errMask : 0xff);
19732 }
19733 
19734 /************** End of malloc.c **********************************************/
19735 /************** Begin file printf.c ******************************************/
19736 /*
19737 ** The "printf" code that follows dates from the 1980's.  It is in
19738 ** the public domain.  The original comments are included here for
19739 ** completeness.  They are very out-of-date but might be useful as
19740 ** an historical reference.  Most of the "enhancements" have been backed
19741 ** out so that the functionality is now the same as standard printf().
19742 **
19743 **************************************************************************
19744 **
19745 ** This file contains code for a set of "printf"-like routines.  These
19746 ** routines format strings much like the printf() from the standard C
19747 ** library, though the implementation here has enhancements to support
19748 ** SQLlite.
19749 */
19750 
19751 /*
19752 ** Conversion types fall into various categories as defined by the
19753 ** following enumeration.
19754 */
19755 #define etRADIX       1 /* Integer types.  %d, %x, %o, and so forth */
19756 #define etFLOAT       2 /* Floating point.  %f */
19757 #define etEXP         3 /* Exponentional notation. %e and %E */
19758 #define etGENERIC     4 /* Floating or exponential, depending on exponent. %g */
19759 #define etSIZE        5 /* Return number of characters processed so far. %n */
19760 #define etSTRING      6 /* Strings. %s */
19761 #define etDYNSTRING   7 /* Dynamically allocated strings. %z */
19762 #define etPERCENT     8 /* Percent symbol. %% */
19763 #define etCHARX       9 /* Characters. %c */
19764 /* The rest are extensions, not normally found in printf() */
19765 #define etSQLESCAPE  10 /* Strings with '\'' doubled.  %q */
19766 #define etSQLESCAPE2 11 /* Strings with '\'' doubled and enclosed in '',
19767                           NULL pointers replaced by SQL NULL.  %Q */
19768 #define etTOKEN      12 /* a pointer to a Token structure */
19769 #define etSRCLIST    13 /* a pointer to a SrcList */
19770 #define etPOINTER    14 /* The %p conversion */
19771 #define etSQLESCAPE3 15 /* %w -> Strings with '\"' doubled */
19772 #define etORDINAL    16 /* %r -> 1st, 2nd, 3rd, 4th, etc.  English only */
19773 
19774 #define etINVALID     0 /* Any unrecognized conversion type */
19775 
19776 
19777 /*
19778 ** An "etByte" is an 8-bit unsigned value.
19779 */
19780 typedef unsigned char etByte;
19781 
19782 /*
19783 ** Each builtin conversion character (ex: the 'd' in "%d") is described
19784 ** by an instance of the following structure
19785 */
19786 typedef struct et_info {   /* Information about each format field */
19787   char fmttype;            /* The format field code letter */
19788   etByte base;             /* The base for radix conversion */
19789   etByte flags;            /* One or more of FLAG_ constants below */
19790   etByte type;             /* Conversion paradigm */
19791   etByte charset;          /* Offset into aDigits[] of the digits string */
19792   etByte prefix;           /* Offset into aPrefix[] of the prefix string */
19793 } et_info;
19794 
19795 /*
19796 ** Allowed values for et_info.flags
19797 */
19798 #define FLAG_SIGNED  1     /* True if the value to convert is signed */
19799 #define FLAG_INTERN  2     /* True if for internal use only */
19800 #define FLAG_STRING  4     /* Allow infinity precision */
19801 
19802 
19803 /*
19804 ** The following table is searched linearly, so it is good to put the
19805 ** most frequently used conversion types first.
19806 */
19807 static const char aDigits[] = "0123456789ABCDEF0123456789abcdef";
19808 static const char aPrefix[] = "-x0\000X0";
19809 static const et_info fmtinfo[] = {
19810   {  'd', 10, 1, etRADIX,      0,  0 },
19811   {  's',  0, 4, etSTRING,     0,  0 },
19812   {  'g',  0, 1, etGENERIC,    30, 0 },
19813   {  'z',  0, 4, etDYNSTRING,  0,  0 },
19814   {  'q',  0, 4, etSQLESCAPE,  0,  0 },
19815   {  'Q',  0, 4, etSQLESCAPE2, 0,  0 },
19816   {  'w',  0, 4, etSQLESCAPE3, 0,  0 },
19817   {  'c',  0, 0, etCHARX,      0,  0 },
19818   {  'o',  8, 0, etRADIX,      0,  2 },
19819   {  'u', 10, 0, etRADIX,      0,  0 },
19820   {  'x', 16, 0, etRADIX,      16, 1 },
19821   {  'X', 16, 0, etRADIX,      0,  4 },
19822 #ifndef SQLITE_OMIT_FLOATING_POINT
19823   {  'f',  0, 1, etFLOAT,      0,  0 },
19824   {  'e',  0, 1, etEXP,        30, 0 },
19825   {  'E',  0, 1, etEXP,        14, 0 },
19826   {  'G',  0, 1, etGENERIC,    14, 0 },
19827 #endif
19828   {  'i', 10, 1, etRADIX,      0,  0 },
19829   {  'n',  0, 0, etSIZE,       0,  0 },
19830   {  '%',  0, 0, etPERCENT,    0,  0 },
19831   {  'p', 16, 0, etPOINTER,    0,  1 },
19832 
19833 /* All the rest have the FLAG_INTERN bit set and are thus for internal
19834 ** use only */
19835   {  'T',  0, 2, etTOKEN,      0,  0 },
19836   {  'S',  0, 2, etSRCLIST,    0,  0 },
19837   {  'r', 10, 3, etORDINAL,    0,  0 },
19838 };
19839 
19840 /*
19841 ** If SQLITE_OMIT_FLOATING_POINT is defined, then none of the floating point
19842 ** conversions will work.
19843 */
19844 #ifndef SQLITE_OMIT_FLOATING_POINT
19845 /*
19846 ** "*val" is a double such that 0.1 <= *val < 10.0
19847 ** Return the ascii code for the leading digit of *val, then
19848 ** multiply "*val" by 10.0 to renormalize.
19849 **
19850 ** Example:
19851 **     input:     *val = 3.14159
19852 **     output:    *val = 1.4159    function return = '3'
19853 **
19854 ** The counter *cnt is incremented each time.  After counter exceeds
19855 ** 16 (the number of significant digits in a 64-bit float) '0' is
19856 ** always returned.
19857 */
19858 static char et_getdigit(LONGDOUBLE_TYPE *val, int *cnt){
19859   int digit;
19860   LONGDOUBLE_TYPE d;
19861   if( (*cnt)<=0 ) return '0';
19862   (*cnt)--;
19863   digit = (int)*val;
19864   d = digit;
19865   digit += '0';
19866   *val = (*val - d)*10.0;
19867   return (char)digit;
19868 }
19869 #endif /* SQLITE_OMIT_FLOATING_POINT */
19870 
19871 /*
19872 ** Append N space characters to the given string buffer.
19873 */
19874 SQLITE_PRIVATE void sqlite3AppendSpace(StrAccum *pAccum, int N){
19875   static const char zSpaces[] = "                             ";
19876   while( N>=(int)sizeof(zSpaces)-1 ){
19877     sqlite3StrAccumAppend(pAccum, zSpaces, sizeof(zSpaces)-1);
19878     N -= sizeof(zSpaces)-1;
19879   }
19880   if( N>0 ){
19881     sqlite3StrAccumAppend(pAccum, zSpaces, N);
19882   }
19883 }
19884 
19885 /*
19886 ** On machines with a small stack size, you can redefine the
19887 ** SQLITE_PRINT_BUF_SIZE to be something smaller, if desired.
19888 */
19889 #ifndef SQLITE_PRINT_BUF_SIZE
19890 # define SQLITE_PRINT_BUF_SIZE 70
19891 #endif
19892 #define etBUFSIZE SQLITE_PRINT_BUF_SIZE  /* Size of the output buffer */
19893 
19894 /*
19895 ** Render a string given by "fmt" into the StrAccum object.
19896 */
19897 SQLITE_PRIVATE void sqlite3VXPrintf(
19898   StrAccum *pAccum,                  /* Accumulate results here */
19899   int useExtended,                   /* Allow extended %-conversions */
19900   const char *fmt,                   /* Format string */
19901   va_list ap                         /* arguments */
19902 ){
19903   int c;                     /* Next character in the format string */
19904   char *bufpt;               /* Pointer to the conversion buffer */
19905   int precision;             /* Precision of the current field */
19906   int length;                /* Length of the field */
19907   int idx;                   /* A general purpose loop counter */
19908   int width;                 /* Width of the current field */
19909   etByte flag_leftjustify;   /* True if "-" flag is present */
19910   etByte flag_plussign;      /* True if "+" flag is present */
19911   etByte flag_blanksign;     /* True if " " flag is present */
19912   etByte flag_alternateform; /* True if "#" flag is present */
19913   etByte flag_altform2;      /* True if "!" flag is present */
19914   etByte flag_zeropad;       /* True if field width constant starts with zero */
19915   etByte flag_long;          /* True if "l" flag is present */
19916   etByte flag_longlong;      /* True if the "ll" flag is present */
19917   etByte done;               /* Loop termination flag */
19918   etByte xtype = 0;          /* Conversion paradigm */
19919   char prefix;               /* Prefix character.  "+" or "-" or " " or '\0'. */
19920   sqlite_uint64 longvalue;   /* Value for integer types */
19921   LONGDOUBLE_TYPE realvalue; /* Value for real types */
19922   const et_info *infop;      /* Pointer to the appropriate info structure */
19923   char *zOut;                /* Rendering buffer */
19924   int nOut;                  /* Size of the rendering buffer */
19925   char *zExtra;              /* Malloced memory used by some conversion */
19926 #ifndef SQLITE_OMIT_FLOATING_POINT
19927   int  exp, e2;              /* exponent of real numbers */
19928   int nsd;                   /* Number of significant digits returned */
19929   double rounder;            /* Used for rounding floating point values */
19930   etByte flag_dp;            /* True if decimal point should be shown */
19931   etByte flag_rtz;           /* True if trailing zeros should be removed */
19932 #endif
19933   char buf[etBUFSIZE];       /* Conversion buffer */
19934 
19935   bufpt = 0;
19936   for(; (c=(*fmt))!=0; ++fmt){
19937     if( c!='%' ){
19938       int amt;
19939       bufpt = (char *)fmt;
19940       amt = 1;
19941       while( (c=(*++fmt))!='%' && c!=0 ) amt++;
19942       sqlite3StrAccumAppend(pAccum, bufpt, amt);
19943       if( c==0 ) break;
19944     }
19945     if( (c=(*++fmt))==0 ){
19946       sqlite3StrAccumAppend(pAccum, "%", 1);
19947       break;
19948     }
19949     /* Find out what flags are present */
19950     flag_leftjustify = flag_plussign = flag_blanksign = 
19951      flag_alternateform = flag_altform2 = flag_zeropad = 0;
19952     done = 0;
19953     do{
19954       switch( c ){
19955         case '-':   flag_leftjustify = 1;     break;
19956         case '+':   flag_plussign = 1;        break;
19957         case ' ':   flag_blanksign = 1;       break;
19958         case '#':   flag_alternateform = 1;   break;
19959         case '!':   flag_altform2 = 1;        break;
19960         case '0':   flag_zeropad = 1;         break;
19961         default:    done = 1;                 break;
19962       }
19963     }while( !done && (c=(*++fmt))!=0 );
19964     /* Get the field width */
19965     width = 0;
19966     if( c=='*' ){
19967       width = va_arg(ap,int);
19968       if( width<0 ){
19969         flag_leftjustify = 1;
19970         width = -width;
19971       }
19972       c = *++fmt;
19973     }else{
19974       while( c>='0' && c<='9' ){
19975         width = width*10 + c - '0';
19976         c = *++fmt;
19977       }
19978     }
19979     /* Get the precision */
19980     if( c=='.' ){
19981       precision = 0;
19982       c = *++fmt;
19983       if( c=='*' ){
19984         precision = va_arg(ap,int);
19985         if( precision<0 ) precision = -precision;
19986         c = *++fmt;
19987       }else{
19988         while( c>='0' && c<='9' ){
19989           precision = precision*10 + c - '0';
19990           c = *++fmt;
19991         }
19992       }
19993     }else{
19994       precision = -1;
19995     }
19996     /* Get the conversion type modifier */
19997     if( c=='l' ){
19998       flag_long = 1;
19999       c = *++fmt;
20000       if( c=='l' ){
20001         flag_longlong = 1;
20002         c = *++fmt;
20003       }else{
20004         flag_longlong = 0;
20005       }
20006     }else{
20007       flag_long = flag_longlong = 0;
20008     }
20009     /* Fetch the info entry for the field */
20010     infop = &fmtinfo[0];
20011     xtype = etINVALID;
20012     for(idx=0; idx<ArraySize(fmtinfo); idx++){
20013       if( c==fmtinfo[idx].fmttype ){
20014         infop = &fmtinfo[idx];
20015         if( useExtended || (infop->flags & FLAG_INTERN)==0 ){
20016           xtype = infop->type;
20017         }else{
20018           return;
20019         }
20020         break;
20021       }
20022     }
20023     zExtra = 0;
20024 
20025     /*
20026     ** At this point, variables are initialized as follows:
20027     **
20028     **   flag_alternateform          TRUE if a '#' is present.
20029     **   flag_altform2               TRUE if a '!' is present.
20030     **   flag_plussign               TRUE if a '+' is present.
20031     **   flag_leftjustify            TRUE if a '-' is present or if the
20032     **                               field width was negative.
20033     **   flag_zeropad                TRUE if the width began with 0.
20034     **   flag_long                   TRUE if the letter 'l' (ell) prefixed
20035     **                               the conversion character.
20036     **   flag_longlong               TRUE if the letter 'll' (ell ell) prefixed
20037     **                               the conversion character.
20038     **   flag_blanksign              TRUE if a ' ' is present.
20039     **   width                       The specified field width.  This is
20040     **                               always non-negative.  Zero is the default.
20041     **   precision                   The specified precision.  The default
20042     **                               is -1.
20043     **   xtype                       The class of the conversion.
20044     **   infop                       Pointer to the appropriate info struct.
20045     */
20046     switch( xtype ){
20047       case etPOINTER:
20048         flag_longlong = sizeof(char*)==sizeof(i64);
20049         flag_long = sizeof(char*)==sizeof(long int);
20050         /* Fall through into the next case */
20051       case etORDINAL:
20052       case etRADIX:
20053         if( infop->flags & FLAG_SIGNED ){
20054           i64 v;
20055           if( flag_longlong ){
20056             v = va_arg(ap,i64);
20057           }else if( flag_long ){
20058             v = va_arg(ap,long int);
20059           }else{
20060             v = va_arg(ap,int);
20061           }
20062           if( v<0 ){
20063             if( v==SMALLEST_INT64 ){
20064               longvalue = ((u64)1)<<63;
20065             }else{
20066               longvalue = -v;
20067             }
20068             prefix = '-';
20069           }else{
20070             longvalue = v;
20071             if( flag_plussign )        prefix = '+';
20072             else if( flag_blanksign )  prefix = ' ';
20073             else                       prefix = 0;
20074           }
20075         }else{
20076           if( flag_longlong ){
20077             longvalue = va_arg(ap,u64);
20078           }else if( flag_long ){
20079             longvalue = va_arg(ap,unsigned long int);
20080           }else{
20081             longvalue = va_arg(ap,unsigned int);
20082           }
20083           prefix = 0;
20084         }
20085         if( longvalue==0 ) flag_alternateform = 0;
20086         if( flag_zeropad && precision<width-(prefix!=0) ){
20087           precision = width-(prefix!=0);
20088         }
20089         if( precision<etBUFSIZE-10 ){
20090           nOut = etBUFSIZE;
20091           zOut = buf;
20092         }else{
20093           nOut = precision + 10;
20094           zOut = zExtra = sqlite3Malloc( nOut );
20095           if( zOut==0 ){
20096             pAccum->accError = STRACCUM_NOMEM;
20097             return;
20098           }
20099         }
20100         bufpt = &zOut[nOut-1];
20101         if( xtype==etORDINAL ){
20102           static const char zOrd[] = "thstndrd";
20103           int x = (int)(longvalue % 10);
20104           if( x>=4 || (longvalue/10)%10==1 ){
20105             x = 0;
20106           }
20107           *(--bufpt) = zOrd[x*2+1];
20108           *(--bufpt) = zOrd[x*2];
20109         }
20110         {
20111           register const char *cset;      /* Use registers for speed */
20112           register int base;
20113           cset = &aDigits[infop->charset];
20114           base = infop->base;
20115           do{                                           /* Convert to ascii */
20116             *(--bufpt) = cset[longvalue%base];
20117             longvalue = longvalue/base;
20118           }while( longvalue>0 );
20119         }
20120         length = (int)(&zOut[nOut-1]-bufpt);
20121         for(idx=precision-length; idx>0; idx--){
20122           *(--bufpt) = '0';                             /* Zero pad */
20123         }
20124         if( prefix ) *(--bufpt) = prefix;               /* Add sign */
20125         if( flag_alternateform && infop->prefix ){      /* Add "0" or "0x" */
20126           const char *pre;
20127           char x;
20128           pre = &aPrefix[infop->prefix];
20129           for(; (x=(*pre))!=0; pre++) *(--bufpt) = x;
20130         }
20131         length = (int)(&zOut[nOut-1]-bufpt);
20132         break;
20133       case etFLOAT:
20134       case etEXP:
20135       case etGENERIC:
20136         realvalue = va_arg(ap,double);
20137 #ifdef SQLITE_OMIT_FLOATING_POINT
20138         length = 0;
20139 #else
20140         if( precision<0 ) precision = 6;         /* Set default precision */
20141         if( realvalue<0.0 ){
20142           realvalue = -realvalue;
20143           prefix = '-';
20144         }else{
20145           if( flag_plussign )          prefix = '+';
20146           else if( flag_blanksign )    prefix = ' ';
20147           else                         prefix = 0;
20148         }
20149         if( xtype==etGENERIC && precision>0 ) precision--;
20150         for(idx=precision, rounder=0.5; idx>0; idx--, rounder*=0.1){}
20151         if( xtype==etFLOAT ) realvalue += rounder;
20152         /* Normalize realvalue to within 10.0 > realvalue >= 1.0 */
20153         exp = 0;
20154         if( sqlite3IsNaN((double)realvalue) ){
20155           bufpt = "NaN";
20156           length = 3;
20157           break;
20158         }
20159         if( realvalue>0.0 ){
20160           LONGDOUBLE_TYPE scale = 1.0;
20161           while( realvalue>=1e100*scale && exp<=350 ){ scale *= 1e100;exp+=100;}
20162           while( realvalue>=1e64*scale && exp<=350 ){ scale *= 1e64; exp+=64; }
20163           while( realvalue>=1e8*scale && exp<=350 ){ scale *= 1e8; exp+=8; }
20164           while( realvalue>=10.0*scale && exp<=350 ){ scale *= 10.0; exp++; }
20165           realvalue /= scale;
20166           while( realvalue<1e-8 ){ realvalue *= 1e8; exp-=8; }
20167           while( realvalue<1.0 ){ realvalue *= 10.0; exp--; }
20168           if( exp>350 ){
20169             if( prefix=='-' ){
20170               bufpt = "-Inf";
20171             }else if( prefix=='+' ){
20172               bufpt = "+Inf";
20173             }else{
20174               bufpt = "Inf";
20175             }
20176             length = sqlite3Strlen30(bufpt);
20177             break;
20178           }
20179         }
20180         bufpt = buf;
20181         /*
20182         ** If the field type is etGENERIC, then convert to either etEXP
20183         ** or etFLOAT, as appropriate.
20184         */
20185         if( xtype!=etFLOAT ){
20186           realvalue += rounder;
20187           if( realvalue>=10.0 ){ realvalue *= 0.1; exp++; }
20188         }
20189         if( xtype==etGENERIC ){
20190           flag_rtz = !flag_alternateform;
20191           if( exp<-4 || exp>precision ){
20192             xtype = etEXP;
20193           }else{
20194             precision = precision - exp;
20195             xtype = etFLOAT;
20196           }
20197         }else{
20198           flag_rtz = flag_altform2;
20199         }
20200         if( xtype==etEXP ){
20201           e2 = 0;
20202         }else{
20203           e2 = exp;
20204         }
20205         if( MAX(e2,0)+precision+width > etBUFSIZE - 15 ){
20206           bufpt = zExtra = sqlite3Malloc( MAX(e2,0)+precision+width+15 );
20207           if( bufpt==0 ){
20208             pAccum->accError = STRACCUM_NOMEM;
20209             return;
20210           }
20211         }
20212         zOut = bufpt;
20213         nsd = 16 + flag_altform2*10;
20214         flag_dp = (precision>0 ?1:0) | flag_alternateform | flag_altform2;
20215         /* The sign in front of the number */
20216         if( prefix ){
20217           *(bufpt++) = prefix;
20218         }
20219         /* Digits prior to the decimal point */
20220         if( e2<0 ){
20221           *(bufpt++) = '0';
20222         }else{
20223           for(; e2>=0; e2--){
20224             *(bufpt++) = et_getdigit(&realvalue,&nsd);
20225           }
20226         }
20227         /* The decimal point */
20228         if( flag_dp ){
20229           *(bufpt++) = '.';
20230         }
20231         /* "0" digits after the decimal point but before the first
20232         ** significant digit of the number */
20233         for(e2++; e2<0; precision--, e2++){
20234           assert( precision>0 );
20235           *(bufpt++) = '0';
20236         }
20237         /* Significant digits after the decimal point */
20238         while( (precision--)>0 ){
20239           *(bufpt++) = et_getdigit(&realvalue,&nsd);
20240         }
20241         /* Remove trailing zeros and the "." if no digits follow the "." */
20242         if( flag_rtz && flag_dp ){
20243           while( bufpt[-1]=='0' ) *(--bufpt) = 0;
20244           assert( bufpt>zOut );
20245           if( bufpt[-1]=='.' ){
20246             if( flag_altform2 ){
20247               *(bufpt++) = '0';
20248             }else{
20249               *(--bufpt) = 0;
20250             }
20251           }
20252         }
20253         /* Add the "eNNN" suffix */
20254         if( xtype==etEXP ){
20255           *(bufpt++) = aDigits[infop->charset];
20256           if( exp<0 ){
20257             *(bufpt++) = '-'; exp = -exp;
20258           }else{
20259             *(bufpt++) = '+';
20260           }
20261           if( exp>=100 ){
20262             *(bufpt++) = (char)((exp/100)+'0');        /* 100's digit */
20263             exp %= 100;
20264           }
20265           *(bufpt++) = (char)(exp/10+'0');             /* 10's digit */
20266           *(bufpt++) = (char)(exp%10+'0');             /* 1's digit */
20267         }
20268         *bufpt = 0;
20269 
20270         /* The converted number is in buf[] and zero terminated. Output it.
20271         ** Note that the number is in the usual order, not reversed as with
20272         ** integer conversions. */
20273         length = (int)(bufpt-zOut);
20274         bufpt = zOut;
20275 
20276         /* Special case:  Add leading zeros if the flag_zeropad flag is
20277         ** set and we are not left justified */
20278         if( flag_zeropad && !flag_leftjustify && length < width){
20279           int i;
20280           int nPad = width - length;
20281           for(i=width; i>=nPad; i--){
20282             bufpt[i] = bufpt[i-nPad];
20283           }
20284           i = prefix!=0;
20285           while( nPad-- ) bufpt[i++] = '0';
20286           length = width;
20287         }
20288 #endif /* !defined(SQLITE_OMIT_FLOATING_POINT) */
20289         break;
20290       case etSIZE:
20291         *(va_arg(ap,int*)) = pAccum->nChar;
20292         length = width = 0;
20293         break;
20294       case etPERCENT:
20295         buf[0] = '%';
20296         bufpt = buf;
20297         length = 1;
20298         break;
20299       case etCHARX:
20300         c = va_arg(ap,int);
20301         buf[0] = (char)c;
20302         if( precision>=0 ){
20303           for(idx=1; idx<precision; idx++) buf[idx] = (char)c;
20304           length = precision;
20305         }else{
20306           length =1;
20307         }
20308         bufpt = buf;
20309         break;
20310       case etSTRING:
20311       case etDYNSTRING:
20312         bufpt = va_arg(ap,char*);
20313         if( bufpt==0 ){
20314           bufpt = "";
20315         }else if( xtype==etDYNSTRING ){
20316           zExtra = bufpt;
20317         }
20318         if( precision>=0 ){
20319           for(length=0; length<precision && bufpt[length]; length++){}
20320         }else{
20321           length = sqlite3Strlen30(bufpt);
20322         }
20323         break;
20324       case etSQLESCAPE:
20325       case etSQLESCAPE2:
20326       case etSQLESCAPE3: {
20327         int i, j, k, n, isnull;
20328         int needQuote;
20329         char ch;
20330         char q = ((xtype==etSQLESCAPE3)?'"':'\'');   /* Quote character */
20331         char *escarg = va_arg(ap,char*);
20332         isnull = escarg==0;
20333         if( isnull ) escarg = (xtype==etSQLESCAPE2 ? "NULL" : "(NULL)");
20334         k = precision;
20335         for(i=n=0; k!=0 && (ch=escarg[i])!=0; i++, k--){
20336           if( ch==q )  n++;
20337         }
20338         needQuote = !isnull && xtype==etSQLESCAPE2;
20339         n += i + 1 + needQuote*2;
20340         if( n>etBUFSIZE ){
20341           bufpt = zExtra = sqlite3Malloc( n );
20342           if( bufpt==0 ){
20343             pAccum->accError = STRACCUM_NOMEM;
20344             return;
20345           }
20346         }else{
20347           bufpt = buf;
20348         }
20349         j = 0;
20350         if( needQuote ) bufpt[j++] = q;
20351         k = i;
20352         for(i=0; i<k; i++){
20353           bufpt[j++] = ch = escarg[i];
20354           if( ch==q ) bufpt[j++] = ch;
20355         }
20356         if( needQuote ) bufpt[j++] = q;
20357         bufpt[j] = 0;
20358         length = j;
20359         /* The precision in %q and %Q means how many input characters to
20360         ** consume, not the length of the output...
20361         ** if( precision>=0 && precision<length ) length = precision; */
20362         break;
20363       }
20364       case etTOKEN: {
20365         Token *pToken = va_arg(ap, Token*);
20366         if( pToken ){
20367           sqlite3StrAccumAppend(pAccum, (const char*)pToken->z, pToken->n);
20368         }
20369         length = width = 0;
20370         break;
20371       }
20372       case etSRCLIST: {
20373         SrcList *pSrc = va_arg(ap, SrcList*);
20374         int k = va_arg(ap, int);
20375         struct SrcList_item *pItem = &pSrc->a[k];
20376         assert( k>=0 && k<pSrc->nSrc );
20377         if( pItem->zDatabase ){
20378           sqlite3StrAccumAppend(pAccum, pItem->zDatabase, -1);
20379           sqlite3StrAccumAppend(pAccum, ".", 1);
20380         }
20381         sqlite3StrAccumAppend(pAccum, pItem->zName, -1);
20382         length = width = 0;
20383         break;
20384       }
20385       default: {
20386         assert( xtype==etINVALID );
20387         return;
20388       }
20389     }/* End switch over the format type */
20390     /*
20391     ** The text of the conversion is pointed to by "bufpt" and is
20392     ** "length" characters long.  The field width is "width".  Do
20393     ** the output.
20394     */
20395     if( !flag_leftjustify ){
20396       register int nspace;
20397       nspace = width-length;
20398       if( nspace>0 ){
20399         sqlite3AppendSpace(pAccum, nspace);
20400       }
20401     }
20402     if( length>0 ){
20403       sqlite3StrAccumAppend(pAccum, bufpt, length);
20404     }
20405     if( flag_leftjustify ){
20406       register int nspace;
20407       nspace = width-length;
20408       if( nspace>0 ){
20409         sqlite3AppendSpace(pAccum, nspace);
20410       }
20411     }
20412     sqlite3_free(zExtra);
20413   }/* End for loop over the format string */
20414 } /* End of function */
20415 
20416 /*
20417 ** Append N bytes of text from z to the StrAccum object.
20418 */
20419 SQLITE_PRIVATE void sqlite3StrAccumAppend(StrAccum *p, const char *z, int N){
20420   assert( z!=0 || N==0 );
20421   if( p->accError ){
20422     testcase(p->accError==STRACCUM_TOOBIG);
20423     testcase(p->accError==STRACCUM_NOMEM);
20424     return;
20425   }
20426   assert( p->zText!=0 || p->nChar==0 );
20427   if( N<=0 ){
20428     if( N==0 || z[0]==0 ) return;
20429     N = sqlite3Strlen30(z);
20430   }
20431   if( p->nChar+N >= p->nAlloc ){
20432     char *zNew;
20433     if( !p->useMalloc ){
20434       p->accError = STRACCUM_TOOBIG;
20435       N = p->nAlloc - p->nChar - 1;
20436       if( N<=0 ){
20437         return;
20438       }
20439     }else{
20440       char *zOld = (p->zText==p->zBase ? 0 : p->zText);
20441       i64 szNew = p->nChar;
20442       szNew += N + 1;
20443       if( szNew > p->mxAlloc ){
20444         sqlite3StrAccumReset(p);
20445         p->accError = STRACCUM_TOOBIG;
20446         return;
20447       }else{
20448         p->nAlloc = (int)szNew;
20449       }
20450       if( p->useMalloc==1 ){
20451         zNew = sqlite3DbRealloc(p->db, zOld, p->nAlloc);
20452       }else{
20453         zNew = sqlite3_realloc(zOld, p->nAlloc);
20454       }
20455       if( zNew ){
20456         if( zOld==0 && p->nChar>0 ) memcpy(zNew, p->zText, p->nChar);
20457         p->zText = zNew;
20458       }else{
20459         p->accError = STRACCUM_NOMEM;
20460         sqlite3StrAccumReset(p);
20461         return;
20462       }
20463     }
20464   }
20465   assert( p->zText );
20466   memcpy(&p->zText[p->nChar], z, N);
20467   p->nChar += N;
20468 }
20469 
20470 /*
20471 ** Finish off a string by making sure it is zero-terminated.
20472 ** Return a pointer to the resulting string.  Return a NULL
20473 ** pointer if any kind of error was encountered.
20474 */
20475 SQLITE_PRIVATE char *sqlite3StrAccumFinish(StrAccum *p){
20476   if( p->zText ){
20477     p->zText[p->nChar] = 0;
20478     if( p->useMalloc && p->zText==p->zBase ){
20479       if( p->useMalloc==1 ){
20480         p->zText = sqlite3DbMallocRaw(p->db, p->nChar+1 );
20481       }else{
20482         p->zText = sqlite3_malloc(p->nChar+1);
20483       }
20484       if( p->zText ){
20485         memcpy(p->zText, p->zBase, p->nChar+1);
20486       }else{
20487         p->accError = STRACCUM_NOMEM;
20488       }
20489     }
20490   }
20491   return p->zText;
20492 }
20493 
20494 /*
20495 ** Reset an StrAccum string.  Reclaim all malloced memory.
20496 */
20497 SQLITE_PRIVATE void sqlite3StrAccumReset(StrAccum *p){
20498   if( p->zText!=p->zBase ){
20499     if( p->useMalloc==1 ){
20500       sqlite3DbFree(p->db, p->zText);
20501     }else{
20502       sqlite3_free(p->zText);
20503     }
20504   }
20505   p->zText = 0;
20506 }
20507 
20508 /*
20509 ** Initialize a string accumulator
20510 */
20511 SQLITE_PRIVATE void sqlite3StrAccumInit(StrAccum *p, char *zBase, int n, int mx){
20512   p->zText = p->zBase = zBase;
20513   p->db = 0;
20514   p->nChar = 0;
20515   p->nAlloc = n;
20516   p->mxAlloc = mx;
20517   p->useMalloc = 1;
20518   p->accError = 0;
20519 }
20520 
20521 /*
20522 ** Print into memory obtained from sqliteMalloc().  Use the internal
20523 ** %-conversion extensions.
20524 */
20525 SQLITE_PRIVATE char *sqlite3VMPrintf(sqlite3 *db, const char *zFormat, va_list ap){
20526   char *z;
20527   char zBase[SQLITE_PRINT_BUF_SIZE];
20528   StrAccum acc;
20529   assert( db!=0 );
20530   sqlite3StrAccumInit(&acc, zBase, sizeof(zBase),
20531                       db->aLimit[SQLITE_LIMIT_LENGTH]);
20532   acc.db = db;
20533   sqlite3VXPrintf(&acc, 1, zFormat, ap);
20534   z = sqlite3StrAccumFinish(&acc);
20535   if( acc.accError==STRACCUM_NOMEM ){
20536     db->mallocFailed = 1;
20537   }
20538   return z;
20539 }
20540 
20541 /*
20542 ** Print into memory obtained from sqliteMalloc().  Use the internal
20543 ** %-conversion extensions.
20544 */
20545 SQLITE_PRIVATE char *sqlite3MPrintf(sqlite3 *db, const char *zFormat, ...){
20546   va_list ap;
20547   char *z;
20548   va_start(ap, zFormat);
20549   z = sqlite3VMPrintf(db, zFormat, ap);
20550   va_end(ap);
20551   return z;
20552 }
20553 
20554 /*
20555 ** Like sqlite3MPrintf(), but call sqlite3DbFree() on zStr after formatting
20556 ** the string and before returnning.  This routine is intended to be used
20557 ** to modify an existing string.  For example:
20558 **
20559 **       x = sqlite3MPrintf(db, x, "prefix %s suffix", x);
20560 **
20561 */
20562 SQLITE_PRIVATE char *sqlite3MAppendf(sqlite3 *db, char *zStr, const char *zFormat, ...){
20563   va_list ap;
20564   char *z;
20565   va_start(ap, zFormat);
20566   z = sqlite3VMPrintf(db, zFormat, ap);
20567   va_end(ap);
20568   sqlite3DbFree(db, zStr);
20569   return z;
20570 }
20571 
20572 /*
20573 ** Print into memory obtained from sqlite3_malloc().  Omit the internal
20574 ** %-conversion extensions.
20575 */
20576 SQLITE_API char *sqlite3_vmprintf(const char *zFormat, va_list ap){
20577   char *z;
20578   char zBase[SQLITE_PRINT_BUF_SIZE];
20579   StrAccum acc;
20580 #ifndef SQLITE_OMIT_AUTOINIT
20581   if( sqlite3_initialize() ) return 0;
20582 #endif
20583   sqlite3StrAccumInit(&acc, zBase, sizeof(zBase), SQLITE_MAX_LENGTH);
20584   acc.useMalloc = 2;
20585   sqlite3VXPrintf(&acc, 0, zFormat, ap);
20586   z = sqlite3StrAccumFinish(&acc);
20587   return z;
20588 }
20589 
20590 /*
20591 ** Print into memory obtained from sqlite3_malloc()().  Omit the internal
20592 ** %-conversion extensions.
20593 */
20594 SQLITE_API char *sqlite3_mprintf(const char *zFormat, ...){
20595   va_list ap;
20596   char *z;
20597 #ifndef SQLITE_OMIT_AUTOINIT
20598   if( sqlite3_initialize() ) return 0;
20599 #endif
20600   va_start(ap, zFormat);
20601   z = sqlite3_vmprintf(zFormat, ap);
20602   va_end(ap);
20603   return z;
20604 }
20605 
20606 /*
20607 ** sqlite3_snprintf() works like snprintf() except that it ignores the
20608 ** current locale settings.  This is important for SQLite because we
20609 ** are not able to use a "," as the decimal point in place of "." as
20610 ** specified by some locales.
20611 **
20612 ** Oops:  The first two arguments of sqlite3_snprintf() are backwards
20613 ** from the snprintf() standard.  Unfortunately, it is too late to change
20614 ** this without breaking compatibility, so we just have to live with the
20615 ** mistake.
20616 **
20617 ** sqlite3_vsnprintf() is the varargs version.
20618 */
20619 SQLITE_API char *sqlite3_vsnprintf(int n, char *zBuf, const char *zFormat, va_list ap){
20620   StrAccum acc;
20621   if( n<=0 ) return zBuf;
20622   sqlite3StrAccumInit(&acc, zBuf, n, 0);
20623   acc.useMalloc = 0;
20624   sqlite3VXPrintf(&acc, 0, zFormat, ap);
20625   return sqlite3StrAccumFinish(&acc);
20626 }
20627 SQLITE_API char *sqlite3_snprintf(int n, char *zBuf, const char *zFormat, ...){
20628   char *z;
20629   va_list ap;
20630   va_start(ap,zFormat);
20631   z = sqlite3_vsnprintf(n, zBuf, zFormat, ap);
20632   va_end(ap);
20633   return z;
20634 }
20635 
20636 /*
20637 ** This is the routine that actually formats the sqlite3_log() message.
20638 ** We house it in a separate routine from sqlite3_log() to avoid using
20639 ** stack space on small-stack systems when logging is disabled.
20640 **
20641 ** sqlite3_log() must render into a static buffer.  It cannot dynamically
20642 ** allocate memory because it might be called while the memory allocator
20643 ** mutex is held.
20644 */
20645 static void renderLogMsg(int iErrCode, const char *zFormat, va_list ap){
20646   StrAccum acc;                          /* String accumulator */
20647   char zMsg[SQLITE_PRINT_BUF_SIZE*3];    /* Complete log message */
20648 
20649   sqlite3StrAccumInit(&acc, zMsg, sizeof(zMsg), 0);
20650   acc.useMalloc = 0;
20651   sqlite3VXPrintf(&acc, 0, zFormat, ap);
20652   sqlite3GlobalConfig.xLog(sqlite3GlobalConfig.pLogArg, iErrCode,
20653                            sqlite3StrAccumFinish(&acc));
20654 }
20655 
20656 /*
20657 ** Format and write a message to the log if logging is enabled.
20658 */
20659 SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...){
20660   va_list ap;                             /* Vararg list */
20661   if( sqlite3GlobalConfig.xLog ){
20662     va_start(ap, zFormat);
20663     renderLogMsg(iErrCode, zFormat, ap);
20664     va_end(ap);
20665   }
20666 }
20667 
20668 #if defined(SQLITE_DEBUG)
20669 /*
20670 ** A version of printf() that understands %lld.  Used for debugging.
20671 ** The printf() built into some versions of windows does not understand %lld
20672 ** and segfaults if you give it a long long int.
20673 */
20674 SQLITE_PRIVATE void sqlite3DebugPrintf(const char *zFormat, ...){
20675   va_list ap;
20676   StrAccum acc;
20677   char zBuf[500];
20678   sqlite3StrAccumInit(&acc, zBuf, sizeof(zBuf), 0);
20679   acc.useMalloc = 0;
20680   va_start(ap,zFormat);
20681   sqlite3VXPrintf(&acc, 0, zFormat, ap);
20682   va_end(ap);
20683   sqlite3StrAccumFinish(&acc);
20684   fprintf(stdout,"%s", zBuf);
20685   fflush(stdout);
20686 }
20687 #endif
20688 
20689 #ifndef SQLITE_OMIT_TRACE
20690 /*
20691 ** variable-argument wrapper around sqlite3VXPrintf().
20692 */
20693 SQLITE_PRIVATE void sqlite3XPrintf(StrAccum *p, const char *zFormat, ...){
20694   va_list ap;
20695   va_start(ap,zFormat);
20696   sqlite3VXPrintf(p, 1, zFormat, ap);
20697   va_end(ap);
20698 }
20699 #endif
20700 
20701 /************** End of printf.c **********************************************/
20702 /************** Begin file random.c ******************************************/
20703 /*
20704 ** 2001 September 15
20705 **
20706 ** The author disclaims copyright to this source code.  In place of
20707 ** a legal notice, here is a blessing:
20708 **
20709 **    May you do good and not evil.
20710 **    May you find forgiveness for yourself and forgive others.
20711 **    May you share freely, never taking more than you give.
20712 **
20713 *************************************************************************
20714 ** This file contains code to implement a pseudo-random number
20715 ** generator (PRNG) for SQLite.
20716 **
20717 ** Random numbers are used by some of the database backends in order
20718 ** to generate random integer keys for tables or random filenames.
20719 */
20720 
20721 
20722 /* All threads share a single random number generator.
20723 ** This structure is the current state of the generator.
20724 */
20725 static SQLITE_WSD struct sqlite3PrngType {
20726   unsigned char isInit;          /* True if initialized */
20727   unsigned char i, j;            /* State variables */
20728   unsigned char s[256];          /* State variables */
20729 } sqlite3Prng;
20730 
20731 /*
20732 ** Return N random bytes.
20733 */
20734 SQLITE_API void sqlite3_randomness(int N, void *pBuf){
20735   unsigned char t;
20736   unsigned char *zBuf = pBuf;
20737 
20738   /* The "wsdPrng" macro will resolve to the pseudo-random number generator
20739   ** state vector.  If writable static data is unsupported on the target,
20740   ** we have to locate the state vector at run-time.  In the more common
20741   ** case where writable static data is supported, wsdPrng can refer directly
20742   ** to the "sqlite3Prng" state vector declared above.
20743   */
20744 #ifdef SQLITE_OMIT_WSD
20745   struct sqlite3PrngType *p = &GLOBAL(struct sqlite3PrngType, sqlite3Prng);
20746 # define wsdPrng p[0]
20747 #else
20748 # define wsdPrng sqlite3Prng
20749 #endif
20750 
20751 #if SQLITE_THREADSAFE
20752   sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_PRNG);
20753   sqlite3_mutex_enter(mutex);
20754 #endif
20755 
20756   /* Initialize the state of the random number generator once,
20757   ** the first time this routine is called.  The seed value does
20758   ** not need to contain a lot of randomness since we are not
20759   ** trying to do secure encryption or anything like that...
20760   **
20761   ** Nothing in this file or anywhere else in SQLite does any kind of
20762   ** encryption.  The RC4 algorithm is being used as a PRNG (pseudo-random
20763   ** number generator) not as an encryption device.
20764   */
20765   if( !wsdPrng.isInit ){
20766     int i;
20767     char k[256];
20768     wsdPrng.j = 0;
20769     wsdPrng.i = 0;
20770     sqlite3OsRandomness(sqlite3_vfs_find(0), 256, k);
20771     for(i=0; i<256; i++){
20772       wsdPrng.s[i] = (u8)i;
20773     }
20774     for(i=0; i<256; i++){
20775       wsdPrng.j += wsdPrng.s[i] + k[i];
20776       t = wsdPrng.s[wsdPrng.j];
20777       wsdPrng.s[wsdPrng.j] = wsdPrng.s[i];
20778       wsdPrng.s[i] = t;
20779     }
20780     wsdPrng.isInit = 1;
20781   }
20782 
20783   while( N-- ){
20784     wsdPrng.i++;
20785     t = wsdPrng.s[wsdPrng.i];
20786     wsdPrng.j += t;
20787     wsdPrng.s[wsdPrng.i] = wsdPrng.s[wsdPrng.j];
20788     wsdPrng.s[wsdPrng.j] = t;
20789     t += wsdPrng.s[wsdPrng.i];
20790     *(zBuf++) = wsdPrng.s[t];
20791   }
20792   sqlite3_mutex_leave(mutex);
20793 }
20794 
20795 #ifndef SQLITE_OMIT_BUILTIN_TEST
20796 /*
20797 ** For testing purposes, we sometimes want to preserve the state of
20798 ** PRNG and restore the PRNG to its saved state at a later time, or
20799 ** to reset the PRNG to its initial state.  These routines accomplish
20800 ** those tasks.
20801 **
20802 ** The sqlite3_test_control() interface calls these routines to
20803 ** control the PRNG.
20804 */
20805 static SQLITE_WSD struct sqlite3PrngType sqlite3SavedPrng;
20806 SQLITE_PRIVATE void sqlite3PrngSaveState(void){
20807   memcpy(
20808     &GLOBAL(struct sqlite3PrngType, sqlite3SavedPrng),
20809     &GLOBAL(struct sqlite3PrngType, sqlite3Prng),
20810     sizeof(sqlite3Prng)
20811   );
20812 }
20813 SQLITE_PRIVATE void sqlite3PrngRestoreState(void){
20814   memcpy(
20815     &GLOBAL(struct sqlite3PrngType, sqlite3Prng),
20816     &GLOBAL(struct sqlite3PrngType, sqlite3SavedPrng),
20817     sizeof(sqlite3Prng)
20818   );
20819 }
20820 SQLITE_PRIVATE void sqlite3PrngResetState(void){
20821   GLOBAL(struct sqlite3PrngType, sqlite3Prng).isInit = 0;
20822 }
20823 #endif /* SQLITE_OMIT_BUILTIN_TEST */
20824 
20825 /************** End of random.c **********************************************/
20826 /************** Begin file utf.c *********************************************/
20827 /*
20828 ** 2004 April 13
20829 **
20830 ** The author disclaims copyright to this source code.  In place of
20831 ** a legal notice, here is a blessing:
20832 **
20833 **    May you do good and not evil.
20834 **    May you find forgiveness for yourself and forgive others.
20835 **    May you share freely, never taking more than you give.
20836 **
20837 *************************************************************************
20838 ** This file contains routines used to translate between UTF-8, 
20839 ** UTF-16, UTF-16BE, and UTF-16LE.
20840 **
20841 ** Notes on UTF-8:
20842 **
20843 **   Byte-0    Byte-1    Byte-2    Byte-3    Value
20844 **  0xxxxxxx                                 00000000 00000000 0xxxxxxx
20845 **  110yyyyy  10xxxxxx                       00000000 00000yyy yyxxxxxx
20846 **  1110zzzz  10yyyyyy  10xxxxxx             00000000 zzzzyyyy yyxxxxxx
20847 **  11110uuu  10uuzzzz  10yyyyyy  10xxxxxx   000uuuuu zzzzyyyy yyxxxxxx
20848 **
20849 **
20850 ** Notes on UTF-16:  (with wwww+1==uuuuu)
20851 **
20852 **      Word-0               Word-1          Value
20853 **  110110ww wwzzzzyy   110111yy yyxxxxxx    000uuuuu zzzzyyyy yyxxxxxx
20854 **  zzzzyyyy yyxxxxxx                        00000000 zzzzyyyy yyxxxxxx
20855 **
20856 **
20857 ** BOM or Byte Order Mark:
20858 **     0xff 0xfe   little-endian utf-16 follows
20859 **     0xfe 0xff   big-endian utf-16 follows
20860 **
20861 */
20862 /* #include <assert.h> */
20863 
20864 #ifndef SQLITE_AMALGAMATION
20865 /*
20866 ** The following constant value is used by the SQLITE_BIGENDIAN and
20867 ** SQLITE_LITTLEENDIAN macros.
20868 */
20869 SQLITE_PRIVATE const int sqlite3one = 1;
20870 #endif /* SQLITE_AMALGAMATION */
20871 
20872 /*
20873 ** This lookup table is used to help decode the first byte of
20874 ** a multi-byte UTF8 character.
20875 */
20876 static const unsigned char sqlite3Utf8Trans1[] = {
20877   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
20878   0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
20879   0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
20880   0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
20881   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
20882   0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
20883   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
20884   0x00, 0x01, 0x02, 0x03, 0x00, 0x01, 0x00, 0x00,
20885 };
20886 
20887 
20888 #define WRITE_UTF8(zOut, c) {                          \
20889   if( c<0x00080 ){                                     \
20890     *zOut++ = (u8)(c&0xFF);                            \
20891   }                                                    \
20892   else if( c<0x00800 ){                                \
20893     *zOut++ = 0xC0 + (u8)((c>>6)&0x1F);                \
20894     *zOut++ = 0x80 + (u8)(c & 0x3F);                   \
20895   }                                                    \
20896   else if( c<0x10000 ){                                \
20897     *zOut++ = 0xE0 + (u8)((c>>12)&0x0F);               \
20898     *zOut++ = 0x80 + (u8)((c>>6) & 0x3F);              \
20899     *zOut++ = 0x80 + (u8)(c & 0x3F);                   \
20900   }else{                                               \
20901     *zOut++ = 0xF0 + (u8)((c>>18) & 0x07);             \
20902     *zOut++ = 0x80 + (u8)((c>>12) & 0x3F);             \
20903     *zOut++ = 0x80 + (u8)((c>>6) & 0x3F);              \
20904     *zOut++ = 0x80 + (u8)(c & 0x3F);                   \
20905   }                                                    \
20906 }
20907 
20908 #define WRITE_UTF16LE(zOut, c) {                                    \
20909   if( c<=0xFFFF ){                                                  \
20910     *zOut++ = (u8)(c&0x00FF);                                       \
20911     *zOut++ = (u8)((c>>8)&0x00FF);                                  \
20912   }else{                                                            \
20913     *zOut++ = (u8)(((c>>10)&0x003F) + (((c-0x10000)>>10)&0x00C0));  \
20914     *zOut++ = (u8)(0x00D8 + (((c-0x10000)>>18)&0x03));              \
20915     *zOut++ = (u8)(c&0x00FF);                                       \
20916     *zOut++ = (u8)(0x00DC + ((c>>8)&0x03));                         \
20917   }                                                                 \
20918 }
20919 
20920 #define WRITE_UTF16BE(zOut, c) {                                    \
20921   if( c<=0xFFFF ){                                                  \
20922     *zOut++ = (u8)((c>>8)&0x00FF);                                  \
20923     *zOut++ = (u8)(c&0x00FF);                                       \
20924   }else{                                                            \
20925     *zOut++ = (u8)(0x00D8 + (((c-0x10000)>>18)&0x03));              \
20926     *zOut++ = (u8)(((c>>10)&0x003F) + (((c-0x10000)>>10)&0x00C0));  \
20927     *zOut++ = (u8)(0x00DC + ((c>>8)&0x03));                         \
20928     *zOut++ = (u8)(c&0x00FF);                                       \
20929   }                                                                 \
20930 }
20931 
20932 #define READ_UTF16LE(zIn, TERM, c){                                   \
20933   c = (*zIn++);                                                       \
20934   c += ((*zIn++)<<8);                                                 \
20935   if( c>=0xD800 && c<0xE000 && TERM ){                                \
20936     int c2 = (*zIn++);                                                \
20937     c2 += ((*zIn++)<<8);                                              \
20938     c = (c2&0x03FF) + ((c&0x003F)<<10) + (((c&0x03C0)+0x0040)<<10);   \
20939   }                                                                   \
20940 }
20941 
20942 #define READ_UTF16BE(zIn, TERM, c){                                   \
20943   c = ((*zIn++)<<8);                                                  \
20944   c += (*zIn++);                                                      \
20945   if( c>=0xD800 && c<0xE000 && TERM ){                                \
20946     int c2 = ((*zIn++)<<8);                                           \
20947     c2 += (*zIn++);                                                   \
20948     c = (c2&0x03FF) + ((c&0x003F)<<10) + (((c&0x03C0)+0x0040)<<10);   \
20949   }                                                                   \
20950 }
20951 
20952 /*
20953 ** Translate a single UTF-8 character.  Return the unicode value.
20954 **
20955 ** During translation, assume that the byte that zTerm points
20956 ** is a 0x00.
20957 **
20958 ** Write a pointer to the next unread byte back into *pzNext.
20959 **
20960 ** Notes On Invalid UTF-8:
20961 **
20962 **  *  This routine never allows a 7-bit character (0x00 through 0x7f) to
20963 **     be encoded as a multi-byte character.  Any multi-byte character that
20964 **     attempts to encode a value between 0x00 and 0x7f is rendered as 0xfffd.
20965 **
20966 **  *  This routine never allows a UTF16 surrogate value to be encoded.
20967 **     If a multi-byte character attempts to encode a value between
20968 **     0xd800 and 0xe000 then it is rendered as 0xfffd.
20969 **
20970 **  *  Bytes in the range of 0x80 through 0xbf which occur as the first
20971 **     byte of a character are interpreted as single-byte characters
20972 **     and rendered as themselves even though they are technically
20973 **     invalid characters.
20974 **
20975 **  *  This routine accepts an infinite number of different UTF8 encodings
20976 **     for unicode values 0x80 and greater.  It do not change over-length
20977 **     encodings to 0xfffd as some systems recommend.
20978 */
20979 #define READ_UTF8(zIn, zTerm, c)                           \
20980   c = *(zIn++);                                            \
20981   if( c>=0xc0 ){                                           \
20982     c = sqlite3Utf8Trans1[c-0xc0];                         \
20983     while( zIn!=zTerm && (*zIn & 0xc0)==0x80 ){            \
20984       c = (c<<6) + (0x3f & *(zIn++));                      \
20985     }                                                      \
20986     if( c<0x80                                             \
20987         || (c&0xFFFFF800)==0xD800                          \
20988         || (c&0xFFFFFFFE)==0xFFFE ){  c = 0xFFFD; }        \
20989   }
20990 SQLITE_PRIVATE u32 sqlite3Utf8Read(
20991   const unsigned char **pz    /* Pointer to string from which to read char */
20992 ){
20993   unsigned int c;
20994 
20995   /* Same as READ_UTF8() above but without the zTerm parameter.
20996   ** For this routine, we assume the UTF8 string is always zero-terminated.
20997   */
20998   c = *((*pz)++);
20999   if( c>=0xc0 ){
21000     c = sqlite3Utf8Trans1[c-0xc0];
21001     while( (*(*pz) & 0xc0)==0x80 ){
21002       c = (c<<6) + (0x3f & *((*pz)++));
21003     }
21004     if( c<0x80
21005         || (c&0xFFFFF800)==0xD800
21006         || (c&0xFFFFFFFE)==0xFFFE ){  c = 0xFFFD; }
21007   }
21008   return c;
21009 }
21010 
21011 
21012 
21013 
21014 /*
21015 ** If the TRANSLATE_TRACE macro is defined, the value of each Mem is
21016 ** printed on stderr on the way into and out of sqlite3VdbeMemTranslate().
21017 */ 
21018 /* #define TRANSLATE_TRACE 1 */
21019 
21020 #ifndef SQLITE_OMIT_UTF16
21021 /*
21022 ** This routine transforms the internal text encoding used by pMem to
21023 ** desiredEnc. It is an error if the string is already of the desired
21024 ** encoding, or if *pMem does not contain a string value.
21025 */
21026 SQLITE_PRIVATE int sqlite3VdbeMemTranslate(Mem *pMem, u8 desiredEnc){
21027   int len;                    /* Maximum length of output string in bytes */
21028   unsigned char *zOut;                  /* Output buffer */
21029   unsigned char *zIn;                   /* Input iterator */
21030   unsigned char *zTerm;                 /* End of input */
21031   unsigned char *z;                     /* Output iterator */
21032   unsigned int c;
21033 
21034   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
21035   assert( pMem->flags&MEM_Str );
21036   assert( pMem->enc!=desiredEnc );
21037   assert( pMem->enc!=0 );
21038   assert( pMem->n>=0 );
21039 
21040 #if defined(TRANSLATE_TRACE) && defined(SQLITE_DEBUG)
21041   {
21042     char zBuf[100];
21043     sqlite3VdbeMemPrettyPrint(pMem, zBuf);
21044     fprintf(stderr, "INPUT:  %s\n", zBuf);
21045   }
21046 #endif
21047 
21048   /* If the translation is between UTF-16 little and big endian, then 
21049   ** all that is required is to swap the byte order. This case is handled
21050   ** differently from the others.
21051   */
21052   if( pMem->enc!=SQLITE_UTF8 && desiredEnc!=SQLITE_UTF8 ){
21053     u8 temp;
21054     int rc;
21055     rc = sqlite3VdbeMemMakeWriteable(pMem);
21056     if( rc!=SQLITE_OK ){
21057       assert( rc==SQLITE_NOMEM );
21058       return SQLITE_NOMEM;
21059     }
21060     zIn = (u8*)pMem->z;
21061     zTerm = &zIn[pMem->n&~1];
21062     while( zIn<zTerm ){
21063       temp = *zIn;
21064       *zIn = *(zIn+1);
21065       zIn++;
21066       *zIn++ = temp;
21067     }
21068     pMem->enc = desiredEnc;
21069     goto translate_out;
21070   }
21071 
21072   /* Set len to the maximum number of bytes required in the output buffer. */
21073   if( desiredEnc==SQLITE_UTF8 ){
21074     /* When converting from UTF-16, the maximum growth results from
21075     ** translating a 2-byte character to a 4-byte UTF-8 character.
21076     ** A single byte is required for the output string
21077     ** nul-terminator.
21078     */
21079     pMem->n &= ~1;
21080     len = pMem->n * 2 + 1;
21081   }else{
21082     /* When converting from UTF-8 to UTF-16 the maximum growth is caused
21083     ** when a 1-byte UTF-8 character is translated into a 2-byte UTF-16
21084     ** character. Two bytes are required in the output buffer for the
21085     ** nul-terminator.
21086     */
21087     len = pMem->n * 2 + 2;
21088   }
21089 
21090   /* Set zIn to point at the start of the input buffer and zTerm to point 1
21091   ** byte past the end.
21092   **
21093   ** Variable zOut is set to point at the output buffer, space obtained
21094   ** from sqlite3_malloc().
21095   */
21096   zIn = (u8*)pMem->z;
21097   zTerm = &zIn[pMem->n];
21098   zOut = sqlite3DbMallocRaw(pMem->db, len);
21099   if( !zOut ){
21100     return SQLITE_NOMEM;
21101   }
21102   z = zOut;
21103 
21104   if( pMem->enc==SQLITE_UTF8 ){
21105     if( desiredEnc==SQLITE_UTF16LE ){
21106       /* UTF-8 -> UTF-16 Little-endian */
21107       while( zIn<zTerm ){
21108         READ_UTF8(zIn, zTerm, c);
21109         WRITE_UTF16LE(z, c);
21110       }
21111     }else{
21112       assert( desiredEnc==SQLITE_UTF16BE );
21113       /* UTF-8 -> UTF-16 Big-endian */
21114       while( zIn<zTerm ){
21115         READ_UTF8(zIn, zTerm, c);
21116         WRITE_UTF16BE(z, c);
21117       }
21118     }
21119     pMem->n = (int)(z - zOut);
21120     *z++ = 0;
21121   }else{
21122     assert( desiredEnc==SQLITE_UTF8 );
21123     if( pMem->enc==SQLITE_UTF16LE ){
21124       /* UTF-16 Little-endian -> UTF-8 */
21125       while( zIn<zTerm ){
21126         READ_UTF16LE(zIn, zIn<zTerm, c); 
21127         WRITE_UTF8(z, c);
21128       }
21129     }else{
21130       /* UTF-16 Big-endian -> UTF-8 */
21131       while( zIn<zTerm ){
21132         READ_UTF16BE(zIn, zIn<zTerm, c); 
21133         WRITE_UTF8(z, c);
21134       }
21135     }
21136     pMem->n = (int)(z - zOut);
21137   }
21138   *z = 0;
21139   assert( (pMem->n+(desiredEnc==SQLITE_UTF8?1:2))<=len );
21140 
21141   sqlite3VdbeMemRelease(pMem);
21142   pMem->flags &= ~(MEM_Static|MEM_Dyn|MEM_Ephem);
21143   pMem->enc = desiredEnc;
21144   pMem->flags |= (MEM_Term|MEM_Dyn);
21145   pMem->z = (char*)zOut;
21146   pMem->zMalloc = pMem->z;
21147 
21148 translate_out:
21149 #if defined(TRANSLATE_TRACE) && defined(SQLITE_DEBUG)
21150   {
21151     char zBuf[100];
21152     sqlite3VdbeMemPrettyPrint(pMem, zBuf);
21153     fprintf(stderr, "OUTPUT: %s\n", zBuf);
21154   }
21155 #endif
21156   return SQLITE_OK;
21157 }
21158 
21159 /*
21160 ** This routine checks for a byte-order mark at the beginning of the 
21161 ** UTF-16 string stored in *pMem. If one is present, it is removed and
21162 ** the encoding of the Mem adjusted. This routine does not do any
21163 ** byte-swapping, it just sets Mem.enc appropriately.
21164 **
21165 ** The allocation (static, dynamic etc.) and encoding of the Mem may be
21166 ** changed by this function.
21167 */
21168 SQLITE_PRIVATE int sqlite3VdbeMemHandleBom(Mem *pMem){
21169   int rc = SQLITE_OK;
21170   u8 bom = 0;
21171 
21172   assert( pMem->n>=0 );
21173   if( pMem->n>1 ){
21174     u8 b1 = *(u8 *)pMem->z;
21175     u8 b2 = *(((u8 *)pMem->z) + 1);
21176     if( b1==0xFE && b2==0xFF ){
21177       bom = SQLITE_UTF16BE;
21178     }
21179     if( b1==0xFF && b2==0xFE ){
21180       bom = SQLITE_UTF16LE;
21181     }
21182   }
21183   
21184   if( bom ){
21185     rc = sqlite3VdbeMemMakeWriteable(pMem);
21186     if( rc==SQLITE_OK ){
21187       pMem->n -= 2;
21188       memmove(pMem->z, &pMem->z[2], pMem->n);
21189       pMem->z[pMem->n] = '\0';
21190       pMem->z[pMem->n+1] = '\0';
21191       pMem->flags |= MEM_Term;
21192       pMem->enc = bom;
21193     }
21194   }
21195   return rc;
21196 }
21197 #endif /* SQLITE_OMIT_UTF16 */
21198 
21199 /*
21200 ** pZ is a UTF-8 encoded unicode string. If nByte is less than zero,
21201 ** return the number of unicode characters in pZ up to (but not including)
21202 ** the first 0x00 byte. If nByte is not less than zero, return the
21203 ** number of unicode characters in the first nByte of pZ (or up to 
21204 ** the first 0x00, whichever comes first).
21205 */
21206 SQLITE_PRIVATE int sqlite3Utf8CharLen(const char *zIn, int nByte){
21207   int r = 0;
21208   const u8 *z = (const u8*)zIn;
21209   const u8 *zTerm;
21210   if( nByte>=0 ){
21211     zTerm = &z[nByte];
21212   }else{
21213     zTerm = (const u8*)(-1);
21214   }
21215   assert( z<=zTerm );
21216   while( *z!=0 && z<zTerm ){
21217     SQLITE_SKIP_UTF8(z);
21218     r++;
21219   }
21220   return r;
21221 }
21222 
21223 /* This test function is not currently used by the automated test-suite. 
21224 ** Hence it is only available in debug builds.
21225 */
21226 #if defined(SQLITE_TEST) && defined(SQLITE_DEBUG)
21227 /*
21228 ** Translate UTF-8 to UTF-8.
21229 **
21230 ** This has the effect of making sure that the string is well-formed
21231 ** UTF-8.  Miscoded characters are removed.
21232 **
21233 ** The translation is done in-place and aborted if the output
21234 ** overruns the input.
21235 */
21236 SQLITE_PRIVATE int sqlite3Utf8To8(unsigned char *zIn){
21237   unsigned char *zOut = zIn;
21238   unsigned char *zStart = zIn;
21239   u32 c;
21240 
21241   while( zIn[0] && zOut<=zIn ){
21242     c = sqlite3Utf8Read((const u8**)&zIn);
21243     if( c!=0xfffd ){
21244       WRITE_UTF8(zOut, c);
21245     }
21246   }
21247   *zOut = 0;
21248   return (int)(zOut - zStart);
21249 }
21250 #endif
21251 
21252 #ifndef SQLITE_OMIT_UTF16
21253 /*
21254 ** Convert a UTF-16 string in the native encoding into a UTF-8 string.
21255 ** Memory to hold the UTF-8 string is obtained from sqlite3_malloc and must
21256 ** be freed by the calling function.
21257 **
21258 ** NULL is returned if there is an allocation error.
21259 */
21260 SQLITE_PRIVATE char *sqlite3Utf16to8(sqlite3 *db, const void *z, int nByte, u8 enc){
21261   Mem m;
21262   memset(&m, 0, sizeof(m));
21263   m.db = db;
21264   sqlite3VdbeMemSetStr(&m, z, nByte, enc, SQLITE_STATIC);
21265   sqlite3VdbeChangeEncoding(&m, SQLITE_UTF8);
21266   if( db->mallocFailed ){
21267     sqlite3VdbeMemRelease(&m);
21268     m.z = 0;
21269   }
21270   assert( (m.flags & MEM_Term)!=0 || db->mallocFailed );
21271   assert( (m.flags & MEM_Str)!=0 || db->mallocFailed );
21272   assert( (m.flags & MEM_Dyn)!=0 || db->mallocFailed );
21273   assert( m.z || db->mallocFailed );
21274   return m.z;
21275 }
21276 
21277 /*
21278 ** zIn is a UTF-16 encoded unicode string at least nChar characters long.
21279 ** Return the number of bytes in the first nChar unicode characters
21280 ** in pZ.  nChar must be non-negative.
21281 */
21282 SQLITE_PRIVATE int sqlite3Utf16ByteLen(const void *zIn, int nChar){
21283   int c;
21284   unsigned char const *z = zIn;
21285   int n = 0;
21286   
21287   if( SQLITE_UTF16NATIVE==SQLITE_UTF16BE ){
21288     while( n<nChar ){
21289       READ_UTF16BE(z, 1, c);
21290       n++;
21291     }
21292   }else{
21293     while( n<nChar ){
21294       READ_UTF16LE(z, 1, c);
21295       n++;
21296     }
21297   }
21298   return (int)(z-(unsigned char const *)zIn);
21299 }
21300 
21301 #if defined(SQLITE_TEST)
21302 /*
21303 ** This routine is called from the TCL test function "translate_selftest".
21304 ** It checks that the primitives for serializing and deserializing
21305 ** characters in each encoding are inverses of each other.
21306 */
21307 SQLITE_PRIVATE void sqlite3UtfSelfTest(void){
21308   unsigned int i, t;
21309   unsigned char zBuf[20];
21310   unsigned char *z;
21311   int n;
21312   unsigned int c;
21313 
21314   for(i=0; i<0x00110000; i++){
21315     z = zBuf;
21316     WRITE_UTF8(z, i);
21317     n = (int)(z-zBuf);
21318     assert( n>0 && n<=4 );
21319     z[0] = 0;
21320     z = zBuf;
21321     c = sqlite3Utf8Read((const u8**)&z);
21322     t = i;
21323     if( i>=0xD800 && i<=0xDFFF ) t = 0xFFFD;
21324     if( (i&0xFFFFFFFE)==0xFFFE ) t = 0xFFFD;
21325     assert( c==t );
21326     assert( (z-zBuf)==n );
21327   }
21328   for(i=0; i<0x00110000; i++){
21329     if( i>=0xD800 && i<0xE000 ) continue;
21330     z = zBuf;
21331     WRITE_UTF16LE(z, i);
21332     n = (int)(z-zBuf);
21333     assert( n>0 && n<=4 );
21334     z[0] = 0;
21335     z = zBuf;
21336     READ_UTF16LE(z, 1, c);
21337     assert( c==i );
21338     assert( (z-zBuf)==n );
21339   }
21340   for(i=0; i<0x00110000; i++){
21341     if( i>=0xD800 && i<0xE000 ) continue;
21342     z = zBuf;
21343     WRITE_UTF16BE(z, i);
21344     n = (int)(z-zBuf);
21345     assert( n>0 && n<=4 );
21346     z[0] = 0;
21347     z = zBuf;
21348     READ_UTF16BE(z, 1, c);
21349     assert( c==i );
21350     assert( (z-zBuf)==n );
21351   }
21352 }
21353 #endif /* SQLITE_TEST */
21354 #endif /* SQLITE_OMIT_UTF16 */
21355 
21356 /************** End of utf.c *************************************************/
21357 /************** Begin file util.c ********************************************/
21358 /*
21359 ** 2001 September 15
21360 **
21361 ** The author disclaims copyright to this source code.  In place of
21362 ** a legal notice, here is a blessing:
21363 **
21364 **    May you do good and not evil.
21365 **    May you find forgiveness for yourself and forgive others.
21366 **    May you share freely, never taking more than you give.
21367 **
21368 *************************************************************************
21369 ** Utility functions used throughout sqlite.
21370 **
21371 ** This file contains functions for allocating memory, comparing
21372 ** strings, and stuff like that.
21373 **
21374 */
21375 /* #include <stdarg.h> */
21376 #ifdef SQLITE_HAVE_ISNAN
21377 # include <math.h>
21378 #endif
21379 
21380 /*
21381 ** Routine needed to support the testcase() macro.
21382 */
21383 #ifdef SQLITE_COVERAGE_TEST
21384 SQLITE_PRIVATE void sqlite3Coverage(int x){
21385   static unsigned dummy = 0;
21386   dummy += (unsigned)x;
21387 }
21388 #endif
21389 
21390 #ifndef SQLITE_OMIT_FLOATING_POINT
21391 /*
21392 ** Return true if the floating point value is Not a Number (NaN).
21393 **
21394 ** Use the math library isnan() function if compiled with SQLITE_HAVE_ISNAN.
21395 ** Otherwise, we have our own implementation that works on most systems.
21396 */
21397 SQLITE_PRIVATE int sqlite3IsNaN(double x){
21398   int rc;   /* The value return */
21399 #if !defined(SQLITE_HAVE_ISNAN)
21400   /*
21401   ** Systems that support the isnan() library function should probably
21402   ** make use of it by compiling with -DSQLITE_HAVE_ISNAN.  But we have
21403   ** found that many systems do not have a working isnan() function so
21404   ** this implementation is provided as an alternative.
21405   **
21406   ** This NaN test sometimes fails if compiled on GCC with -ffast-math.
21407   ** On the other hand, the use of -ffast-math comes with the following
21408   ** warning:
21409   **
21410   **      This option [-ffast-math] should never be turned on by any
21411   **      -O option since it can result in incorrect output for programs
21412   **      which depend on an exact implementation of IEEE or ISO 
21413   **      rules/specifications for math functions.
21414   **
21415   ** Under MSVC, this NaN test may fail if compiled with a floating-
21416   ** point precision mode other than /fp:precise.  From the MSDN 
21417   ** documentation:
21418   **
21419   **      The compiler [with /fp:precise] will properly handle comparisons 
21420   **      involving NaN. For example, x != x evaluates to true if x is NaN 
21421   **      ...
21422   */
21423 #ifdef __FAST_MATH__
21424 # error SQLite will not work correctly with the -ffast-math option of GCC.
21425 #endif
21426   volatile double y = x;
21427   volatile double z = y;
21428   rc = (y!=z);
21429 #else  /* if defined(SQLITE_HAVE_ISNAN) */
21430   rc = isnan(x);
21431 #endif /* SQLITE_HAVE_ISNAN */
21432   testcase( rc );
21433   return rc;
21434 }
21435 #endif /* SQLITE_OMIT_FLOATING_POINT */
21436 
21437 /*
21438 ** Compute a string length that is limited to what can be stored in
21439 ** lower 30 bits of a 32-bit signed integer.
21440 **
21441 ** The value returned will never be negative.  Nor will it ever be greater
21442 ** than the actual length of the string.  For very long strings (greater
21443 ** than 1GiB) the value returned might be less than the true string length.
21444 */
21445 SQLITE_PRIVATE int sqlite3Strlen30(const char *z){
21446   const char *z2 = z;
21447   if( z==0 ) return 0;
21448   while( *z2 ){ z2++; }
21449   return 0x3fffffff & (int)(z2 - z);
21450 }
21451 
21452 /*
21453 ** Set the most recent error code and error string for the sqlite
21454 ** handle "db". The error code is set to "err_code".
21455 **
21456 ** If it is not NULL, string zFormat specifies the format of the
21457 ** error string in the style of the printf functions: The following
21458 ** format characters are allowed:
21459 **
21460 **      %s      Insert a string
21461 **      %z      A string that should be freed after use
21462 **      %d      Insert an integer
21463 **      %T      Insert a token
21464 **      %S      Insert the first element of a SrcList
21465 **
21466 ** zFormat and any string tokens that follow it are assumed to be
21467 ** encoded in UTF-8.
21468 **
21469 ** To clear the most recent error for sqlite handle "db", sqlite3Error
21470 ** should be called with err_code set to SQLITE_OK and zFormat set
21471 ** to NULL.
21472 */
21473 SQLITE_PRIVATE void sqlite3Error(sqlite3 *db, int err_code, const char *zFormat, ...){
21474   if( db && (db->pErr || (db->pErr = sqlite3ValueNew(db))!=0) ){
21475     db->errCode = err_code;
21476     if( zFormat ){
21477       char *z;
21478       va_list ap;
21479       va_start(ap, zFormat);
21480       z = sqlite3VMPrintf(db, zFormat, ap);
21481       va_end(ap);
21482       sqlite3ValueSetStr(db->pErr, -1, z, SQLITE_UTF8, SQLITE_DYNAMIC);
21483     }else{
21484       sqlite3ValueSetStr(db->pErr, 0, 0, SQLITE_UTF8, SQLITE_STATIC);
21485     }
21486   }
21487 }
21488 
21489 /*
21490 ** Add an error message to pParse->zErrMsg and increment pParse->nErr.
21491 ** The following formatting characters are allowed:
21492 **
21493 **      %s      Insert a string
21494 **      %z      A string that should be freed after use
21495 **      %d      Insert an integer
21496 **      %T      Insert a token
21497 **      %S      Insert the first element of a SrcList
21498 **
21499 ** This function should be used to report any error that occurs whilst
21500 ** compiling an SQL statement (i.e. within sqlite3_prepare()). The
21501 ** last thing the sqlite3_prepare() function does is copy the error
21502 ** stored by this function into the database handle using sqlite3Error().
21503 ** Function sqlite3Error() should be used during statement execution
21504 ** (sqlite3_step() etc.).
21505 */
21506 SQLITE_PRIVATE void sqlite3ErrorMsg(Parse *pParse, const char *zFormat, ...){
21507   char *zMsg;
21508   va_list ap;
21509   sqlite3 *db = pParse->db;
21510   va_start(ap, zFormat);
21511   zMsg = sqlite3VMPrintf(db, zFormat, ap);
21512   va_end(ap);
21513   if( db->suppressErr ){
21514     sqlite3DbFree(db, zMsg);
21515   }else{
21516     pParse->nErr++;
21517     sqlite3DbFree(db, pParse->zErrMsg);
21518     pParse->zErrMsg = zMsg;
21519     pParse->rc = SQLITE_ERROR;
21520   }
21521 }
21522 
21523 /*
21524 ** Convert an SQL-style quoted string into a normal string by removing
21525 ** the quote characters.  The conversion is done in-place.  If the
21526 ** input does not begin with a quote character, then this routine
21527 ** is a no-op.
21528 **
21529 ** The input string must be zero-terminated.  A new zero-terminator
21530 ** is added to the dequoted string.
21531 **
21532 ** The return value is -1 if no dequoting occurs or the length of the
21533 ** dequoted string, exclusive of the zero terminator, if dequoting does
21534 ** occur.
21535 **
21536 ** 2002-Feb-14: This routine is extended to remove MS-Access style
21537 ** brackets from around identifers.  For example:  "[a-b-c]" becomes
21538 ** "a-b-c".
21539 */
21540 SQLITE_PRIVATE int sqlite3Dequote(char *z){
21541   char quote;
21542   int i, j;
21543   if( z==0 ) return -1;
21544   quote = z[0];
21545   switch( quote ){
21546     case '\'':  break;
21547     case '"':   break;
21548     case '`':   break;                /* For MySQL compatibility */
21549     case '[':   quote = ']';  break;  /* For MS SqlServer compatibility */
21550     default:    return -1;
21551   }
21552   for(i=1, j=0;; i++){
21553     assert( z[i] );
21554     if( z[i]==quote ){
21555       if( z[i+1]==quote ){
21556         z[j++] = quote;
21557         i++;
21558       }else{
21559         break;
21560       }
21561     }else{
21562       z[j++] = z[i];
21563     }
21564   }
21565   z[j] = 0;
21566   return j;
21567 }
21568 
21569 /* Convenient short-hand */
21570 #define UpperToLower sqlite3UpperToLower
21571 
21572 /*
21573 ** Some systems have stricmp().  Others have strcasecmp().  Because
21574 ** there is no consistency, we will define our own.
21575 **
21576 ** IMPLEMENTATION-OF: R-30243-02494 The sqlite3_stricmp() and
21577 ** sqlite3_strnicmp() APIs allow applications and extensions to compare
21578 ** the contents of two buffers containing UTF-8 strings in a
21579 ** case-independent fashion, using the same definition of "case
21580 ** independence" that SQLite uses internally when comparing identifiers.
21581 */
21582 SQLITE_API int sqlite3_stricmp(const char *zLeft, const char *zRight){
21583   register unsigned char *a, *b;
21584   a = (unsigned char *)zLeft;
21585   b = (unsigned char *)zRight;
21586   while( *a!=0 && UpperToLower[*a]==UpperToLower[*b]){ a++; b++; }
21587   return UpperToLower[*a] - UpperToLower[*b];
21588 }
21589 SQLITE_API int sqlite3_strnicmp(const char *zLeft, const char *zRight, int N){
21590   register unsigned char *a, *b;
21591   a = (unsigned char *)zLeft;
21592   b = (unsigned char *)zRight;
21593   while( N-- > 0 && *a!=0 && UpperToLower[*a]==UpperToLower[*b]){ a++; b++; }
21594   return N<0 ? 0 : UpperToLower[*a] - UpperToLower[*b];
21595 }
21596 
21597 /*
21598 ** The string z[] is an text representation of a real number.
21599 ** Convert this string to a double and write it into *pResult.
21600 **
21601 ** The string z[] is length bytes in length (bytes, not characters) and
21602 ** uses the encoding enc.  The string is not necessarily zero-terminated.
21603 **
21604 ** Return TRUE if the result is a valid real number (or integer) and FALSE
21605 ** if the string is empty or contains extraneous text.  Valid numbers
21606 ** are in one of these formats:
21607 **
21608 **    [+-]digits[E[+-]digits]
21609 **    [+-]digits.[digits][E[+-]digits]
21610 **    [+-].digits[E[+-]digits]
21611 **
21612 ** Leading and trailing whitespace is ignored for the purpose of determining
21613 ** validity.
21614 **
21615 ** If some prefix of the input string is a valid number, this routine
21616 ** returns FALSE but it still converts the prefix and writes the result
21617 ** into *pResult.
21618 */
21619 SQLITE_PRIVATE int sqlite3AtoF(const char *z, double *pResult, int length, u8 enc){
21620 #ifndef SQLITE_OMIT_FLOATING_POINT
21621   int incr;
21622   const char *zEnd = z + length;
21623   /* sign * significand * (10 ^ (esign * exponent)) */
21624   int sign = 1;    /* sign of significand */
21625   i64 s = 0;       /* significand */
21626   int d = 0;       /* adjust exponent for shifting decimal point */
21627   int esign = 1;   /* sign of exponent */
21628   int e = 0;       /* exponent */
21629   int eValid = 1;  /* True exponent is either not used or is well-formed */
21630   double result;
21631   int nDigits = 0;
21632   int nonNum = 0;
21633 
21634   assert( enc==SQLITE_UTF8 || enc==SQLITE_UTF16LE || enc==SQLITE_UTF16BE );
21635   *pResult = 0.0;   /* Default return value, in case of an error */
21636 
21637   if( enc==SQLITE_UTF8 ){
21638     incr = 1;
21639   }else{
21640     int i;
21641     incr = 2;
21642     assert( SQLITE_UTF16LE==2 && SQLITE_UTF16BE==3 );
21643     for(i=3-enc; i<length && z[i]==0; i+=2){}
21644     nonNum = i<length;
21645     zEnd = z+i+enc-3;
21646     z += (enc&1);
21647   }
21648 
21649   /* skip leading spaces */
21650   while( z<zEnd && sqlite3Isspace(*z) ) z+=incr;
21651   if( z>=zEnd ) return 0;
21652 
21653   /* get sign of significand */
21654   if( *z=='-' ){
21655     sign = -1;
21656     z+=incr;
21657   }else if( *z=='+' ){
21658     z+=incr;
21659   }
21660 
21661   /* skip leading zeroes */
21662   while( z<zEnd && z[0]=='0' ) z+=incr, nDigits++;
21663 
21664   /* copy max significant digits to significand */
21665   while( z<zEnd && sqlite3Isdigit(*z) && s<((LARGEST_INT64-9)/10) ){
21666     s = s*10 + (*z - '0');
21667     z+=incr, nDigits++;
21668   }
21669 
21670   /* skip non-significant significand digits
21671   ** (increase exponent by d to shift decimal left) */
21672   while( z<zEnd && sqlite3Isdigit(*z) ) z+=incr, nDigits++, d++;
21673   if( z>=zEnd ) goto do_atof_calc;
21674 
21675   /* if decimal point is present */
21676   if( *z=='.' ){
21677     z+=incr;
21678     /* copy digits from after decimal to significand
21679     ** (decrease exponent by d to shift decimal right) */
21680     while( z<zEnd && sqlite3Isdigit(*z) && s<((LARGEST_INT64-9)/10) ){
21681       s = s*10 + (*z - '0');
21682       z+=incr, nDigits++, d--;
21683     }
21684     /* skip non-significant digits */
21685     while( z<zEnd && sqlite3Isdigit(*z) ) z+=incr, nDigits++;
21686   }
21687   if( z>=zEnd ) goto do_atof_calc;
21688 
21689   /* if exponent is present */
21690   if( *z=='e' || *z=='E' ){
21691     z+=incr;
21692     eValid = 0;
21693     if( z>=zEnd ) goto do_atof_calc;
21694     /* get sign of exponent */
21695     if( *z=='-' ){
21696       esign = -1;
21697       z+=incr;
21698     }else if( *z=='+' ){
21699       z+=incr;
21700     }
21701     /* copy digits to exponent */
21702     while( z<zEnd && sqlite3Isdigit(*z) ){
21703       e = e<10000 ? (e*10 + (*z - '0')) : 10000;
21704       z+=incr;
21705       eValid = 1;
21706     }
21707   }
21708 
21709   /* skip trailing spaces */
21710   if( nDigits && eValid ){
21711     while( z<zEnd && sqlite3Isspace(*z) ) z+=incr;
21712   }
21713 
21714 do_atof_calc:
21715   /* adjust exponent by d, and update sign */
21716   e = (e*esign) + d;
21717   if( e<0 ) {
21718     esign = -1;
21719     e *= -1;
21720   } else {
21721     esign = 1;
21722   }
21723 
21724   /* if 0 significand */
21725   if( !s ) {
21726     /* In the IEEE 754 standard, zero is signed.
21727     ** Add the sign if we've seen at least one digit */
21728     result = (sign<0 && nDigits) ? -(double)0 : (double)0;
21729   } else {
21730     /* attempt to reduce exponent */
21731     if( esign>0 ){
21732       while( s<(LARGEST_INT64/10) && e>0 ) e--,s*=10;
21733     }else{
21734       while( !(s%10) && e>0 ) e--,s/=10;
21735     }
21736 
21737     /* adjust the sign of significand */
21738     s = sign<0 ? -s : s;
21739 
21740     /* if exponent, scale significand as appropriate
21741     ** and store in result. */
21742     if( e ){
21743       LONGDOUBLE_TYPE scale = 1.0;
21744       /* attempt to handle extremely small/large numbers better */
21745       if( e>307 && e<342 ){
21746         while( e%308 ) { scale *= 1.0e+1; e -= 1; }
21747         if( esign<0 ){
21748           result = s / scale;
21749           result /= 1.0e+308;
21750         }else{
21751           result = s * scale;
21752           result *= 1.0e+308;
21753         }
21754       }else if( e>=342 ){
21755         if( esign<0 ){
21756           result = 0.0*s;
21757         }else{
21758           result = 1e308*1e308*s;  /* Infinity */
21759         }
21760       }else{
21761         /* 1.0e+22 is the largest power of 10 than can be 
21762         ** represented exactly. */
21763         while( e%22 ) { scale *= 1.0e+1; e -= 1; }
21764         while( e>0 ) { scale *= 1.0e+22; e -= 22; }
21765         if( esign<0 ){
21766           result = s / scale;
21767         }else{
21768           result = s * scale;
21769         }
21770       }
21771     } else {
21772       result = (double)s;
21773     }
21774   }
21775 
21776   /* store the result */
21777   *pResult = result;
21778 
21779   /* return true if number and no extra non-whitespace chracters after */
21780   return z>=zEnd && nDigits>0 && eValid && nonNum==0;
21781 #else
21782   return !sqlite3Atoi64(z, pResult, length, enc);
21783 #endif /* SQLITE_OMIT_FLOATING_POINT */
21784 }
21785 
21786 /*
21787 ** Compare the 19-character string zNum against the text representation
21788 ** value 2^63:  9223372036854775808.  Return negative, zero, or positive
21789 ** if zNum is less than, equal to, or greater than the string.
21790 ** Note that zNum must contain exactly 19 characters.
21791 **
21792 ** Unlike memcmp() this routine is guaranteed to return the difference
21793 ** in the values of the last digit if the only difference is in the
21794 ** last digit.  So, for example,
21795 **
21796 **      compare2pow63("9223372036854775800", 1)
21797 **
21798 ** will return -8.
21799 */
21800 static int compare2pow63(const char *zNum, int incr){
21801   int c = 0;
21802   int i;
21803                     /* 012345678901234567 */
21804   const char *pow63 = "922337203685477580";
21805   for(i=0; c==0 && i<18; i++){
21806     c = (zNum[i*incr]-pow63[i])*10;
21807   }
21808   if( c==0 ){
21809     c = zNum[18*incr] - '8';
21810     testcase( c==(-1) );
21811     testcase( c==0 );
21812     testcase( c==(+1) );
21813   }
21814   return c;
21815 }
21816 
21817 
21818 /*
21819 ** Convert zNum to a 64-bit signed integer.
21820 **
21821 ** If the zNum value is representable as a 64-bit twos-complement 
21822 ** integer, then write that value into *pNum and return 0.
21823 **
21824 ** If zNum is exactly 9223372036854775808, return 2.  This special
21825 ** case is broken out because while 9223372036854775808 cannot be a 
21826 ** signed 64-bit integer, its negative -9223372036854775808 can be.
21827 **
21828 ** If zNum is too big for a 64-bit integer and is not
21829 ** 9223372036854775808  or if zNum contains any non-numeric text,
21830 ** then return 1.
21831 **
21832 ** length is the number of bytes in the string (bytes, not characters).
21833 ** The string is not necessarily zero-terminated.  The encoding is
21834 ** given by enc.
21835 */
21836 SQLITE_PRIVATE int sqlite3Atoi64(const char *zNum, i64 *pNum, int length, u8 enc){
21837   int incr;
21838   u64 u = 0;
21839   int neg = 0; /* assume positive */
21840   int i;
21841   int c = 0;
21842   int nonNum = 0;
21843   const char *zStart;
21844   const char *zEnd = zNum + length;
21845   assert( enc==SQLITE_UTF8 || enc==SQLITE_UTF16LE || enc==SQLITE_UTF16BE );
21846   if( enc==SQLITE_UTF8 ){
21847     incr = 1;
21848   }else{
21849     incr = 2;
21850     assert( SQLITE_UTF16LE==2 && SQLITE_UTF16BE==3 );
21851     for(i=3-enc; i<length && zNum[i]==0; i+=2){}
21852     nonNum = i<length;
21853     zEnd = zNum+i+enc-3;
21854     zNum += (enc&1);
21855   }
21856   while( zNum<zEnd && sqlite3Isspace(*zNum) ) zNum+=incr;
21857   if( zNum<zEnd ){
21858     if( *zNum=='-' ){
21859       neg = 1;
21860       zNum+=incr;
21861     }else if( *zNum=='+' ){
21862       zNum+=incr;
21863     }
21864   }
21865   zStart = zNum;
21866   while( zNum<zEnd && zNum[0]=='0' ){ zNum+=incr; } /* Skip leading zeros. */
21867   for(i=0; &zNum[i]<zEnd && (c=zNum[i])>='0' && c<='9'; i+=incr){
21868     u = u*10 + c - '0';
21869   }
21870   if( u>LARGEST_INT64 ){
21871     *pNum = neg ? SMALLEST_INT64 : LARGEST_INT64;
21872   }else if( neg ){
21873     *pNum = -(i64)u;
21874   }else{
21875     *pNum = (i64)u;
21876   }
21877   testcase( i==18 );
21878   testcase( i==19 );
21879   testcase( i==20 );
21880   if( (c!=0 && &zNum[i]<zEnd) || (i==0 && zStart==zNum) || i>19*incr || nonNum ){
21881     /* zNum is empty or contains non-numeric text or is longer
21882     ** than 19 digits (thus guaranteeing that it is too large) */
21883     return 1;
21884   }else if( i<19*incr ){
21885     /* Less than 19 digits, so we know that it fits in 64 bits */
21886     assert( u<=LARGEST_INT64 );
21887     return 0;
21888   }else{
21889     /* zNum is a 19-digit numbers.  Compare it against 9223372036854775808. */
21890     c = compare2pow63(zNum, incr);
21891     if( c<0 ){
21892       /* zNum is less than 9223372036854775808 so it fits */
21893       assert( u<=LARGEST_INT64 );
21894       return 0;
21895     }else if( c>0 ){
21896       /* zNum is greater than 9223372036854775808 so it overflows */
21897       return 1;
21898     }else{
21899       /* zNum is exactly 9223372036854775808.  Fits if negative.  The
21900       ** special case 2 overflow if positive */
21901       assert( u-1==LARGEST_INT64 );
21902       return neg ? 0 : 2;
21903     }
21904   }
21905 }
21906 
21907 /*
21908 ** If zNum represents an integer that will fit in 32-bits, then set
21909 ** *pValue to that integer and return true.  Otherwise return false.
21910 **
21911 ** Any non-numeric characters that following zNum are ignored.
21912 ** This is different from sqlite3Atoi64() which requires the
21913 ** input number to be zero-terminated.
21914 */
21915 SQLITE_PRIVATE int sqlite3GetInt32(const char *zNum, int *pValue){
21916   sqlite_int64 v = 0;
21917   int i, c;
21918   int neg = 0;
21919   if( zNum[0]=='-' ){
21920     neg = 1;
21921     zNum++;
21922   }else if( zNum[0]=='+' ){
21923     zNum++;
21924   }
21925   while( zNum[0]=='0' ) zNum++;
21926   for(i=0; i<11 && (c = zNum[i] - '0')>=0 && c<=9; i++){
21927     v = v*10 + c;
21928   }
21929 
21930   /* The longest decimal representation of a 32 bit integer is 10 digits:
21931   **
21932   **             1234567890
21933   **     2^31 -> 2147483648
21934   */
21935   testcase( i==10 );
21936   if( i>10 ){
21937     return 0;
21938   }
21939   testcase( v-neg==2147483647 );
21940   if( v-neg>2147483647 ){
21941     return 0;
21942   }
21943   if( neg ){
21944     v = -v;
21945   }
21946   *pValue = (int)v;
21947   return 1;
21948 }
21949 
21950 /*
21951 ** Return a 32-bit integer value extracted from a string.  If the
21952 ** string is not an integer, just return 0.
21953 */
21954 SQLITE_PRIVATE int sqlite3Atoi(const char *z){
21955   int x = 0;
21956   if( z ) sqlite3GetInt32(z, &x);
21957   return x;
21958 }
21959 
21960 /*
21961 ** The variable-length integer encoding is as follows:
21962 **
21963 ** KEY:
21964 **         A = 0xxxxxxx    7 bits of data and one flag bit
21965 **         B = 1xxxxxxx    7 bits of data and one flag bit
21966 **         C = xxxxxxxx    8 bits of data
21967 **
21968 **  7 bits - A
21969 ** 14 bits - BA
21970 ** 21 bits - BBA
21971 ** 28 bits - BBBA
21972 ** 35 bits - BBBBA
21973 ** 42 bits - BBBBBA
21974 ** 49 bits - BBBBBBA
21975 ** 56 bits - BBBBBBBA
21976 ** 64 bits - BBBBBBBBC
21977 */
21978 
21979 /*
21980 ** Write a 64-bit variable-length integer to memory starting at p[0].
21981 ** The length of data write will be between 1 and 9 bytes.  The number
21982 ** of bytes written is returned.
21983 **
21984 ** A variable-length integer consists of the lower 7 bits of each byte
21985 ** for all bytes that have the 8th bit set and one byte with the 8th
21986 ** bit clear.  Except, if we get to the 9th byte, it stores the full
21987 ** 8 bits and is the last byte.
21988 */
21989 SQLITE_PRIVATE int sqlite3PutVarint(unsigned char *p, u64 v){
21990   int i, j, n;
21991   u8 buf[10];
21992   if( v & (((u64)0xff000000)<<32) ){
21993     p[8] = (u8)v;
21994     v >>= 8;
21995     for(i=7; i>=0; i--){
21996       p[i] = (u8)((v & 0x7f) | 0x80);
21997       v >>= 7;
21998     }
21999     return 9;
22000   }    
22001   n = 0;
22002   do{
22003     buf[n++] = (u8)((v & 0x7f) | 0x80);
22004     v >>= 7;
22005   }while( v!=0 );
22006   buf[0] &= 0x7f;
22007   assert( n<=9 );
22008   for(i=0, j=n-1; j>=0; j--, i++){
22009     p[i] = buf[j];
22010   }
22011   return n;
22012 }
22013 
22014 /*
22015 ** This routine is a faster version of sqlite3PutVarint() that only
22016 ** works for 32-bit positive integers and which is optimized for
22017 ** the common case of small integers.  A MACRO version, putVarint32,
22018 ** is provided which inlines the single-byte case.  All code should use
22019 ** the MACRO version as this function assumes the single-byte case has
22020 ** already been handled.
22021 */
22022 SQLITE_PRIVATE int sqlite3PutVarint32(unsigned char *p, u32 v){
22023 #ifndef putVarint32
22024   if( (v & ~0x7f)==0 ){
22025     p[0] = v;
22026     return 1;
22027   }
22028 #endif
22029   if( (v & ~0x3fff)==0 ){
22030     p[0] = (u8)((v>>7) | 0x80);
22031     p[1] = (u8)(v & 0x7f);
22032     return 2;
22033   }
22034   return sqlite3PutVarint(p, v);
22035 }
22036 
22037 /*
22038 ** Bitmasks used by sqlite3GetVarint().  These precomputed constants
22039 ** are defined here rather than simply putting the constant expressions
22040 ** inline in order to work around bugs in the RVT compiler.
22041 **
22042 ** SLOT_2_0     A mask for  (0x7f<<14) | 0x7f
22043 **
22044 ** SLOT_4_2_0   A mask for  (0x7f<<28) | SLOT_2_0
22045 */
22046 #define SLOT_2_0     0x001fc07f
22047 #define SLOT_4_2_0   0xf01fc07f
22048 
22049 
22050 /*
22051 ** Read a 64-bit variable-length integer from memory starting at p[0].
22052 ** Return the number of bytes read.  The value is stored in *v.
22053 */
22054 SQLITE_PRIVATE u8 sqlite3GetVarint(const unsigned char *p, u64 *v){
22055   u32 a,b,s;
22056 
22057   a = *p;
22058   /* a: p0 (unmasked) */
22059   if (!(a&0x80))
22060   {
22061     *v = a;
22062     return 1;
22063   }
22064 
22065   p++;
22066   b = *p;
22067   /* b: p1 (unmasked) */
22068   if (!(b&0x80))
22069   {
22070     a &= 0x7f;
22071     a = a<<7;
22072     a |= b;
22073     *v = a;
22074     return 2;
22075   }
22076 
22077   /* Verify that constants are precomputed correctly */
22078   assert( SLOT_2_0 == ((0x7f<<14) | (0x7f)) );
22079   assert( SLOT_4_2_0 == ((0xfU<<28) | (0x7f<<14) | (0x7f)) );
22080 
22081   p++;
22082   a = a<<14;
22083   a |= *p;
22084   /* a: p0<<14 | p2 (unmasked) */
22085   if (!(a&0x80))
22086   {
22087     a &= SLOT_2_0;
22088     b &= 0x7f;
22089     b = b<<7;
22090     a |= b;
22091     *v = a;
22092     return 3;
22093   }
22094 
22095   /* CSE1 from below */
22096   a &= SLOT_2_0;
22097   p++;
22098   b = b<<14;
22099   b |= *p;
22100   /* b: p1<<14 | p3 (unmasked) */
22101   if (!(b&0x80))
22102   {
22103     b &= SLOT_2_0;
22104     /* moved CSE1 up */
22105     /* a &= (0x7f<<14)|(0x7f); */
22106     a = a<<7;
22107     a |= b;
22108     *v = a;
22109     return 4;
22110   }
22111 
22112   /* a: p0<<14 | p2 (masked) */
22113   /* b: p1<<14 | p3 (unmasked) */
22114   /* 1:save off p0<<21 | p1<<14 | p2<<7 | p3 (masked) */
22115   /* moved CSE1 up */
22116   /* a &= (0x7f<<14)|(0x7f); */
22117   b &= SLOT_2_0;
22118   s = a;
22119   /* s: p0<<14 | p2 (masked) */
22120 
22121   p++;
22122   a = a<<14;
22123   a |= *p;
22124   /* a: p0<<28 | p2<<14 | p4 (unmasked) */
22125   if (!(a&0x80))
22126   {
22127     /* we can skip these cause they were (effectively) done above in calc'ing s */
22128     /* a &= (0x7f<<28)|(0x7f<<14)|(0x7f); */
22129     /* b &= (0x7f<<14)|(0x7f); */
22130     b = b<<7;
22131     a |= b;
22132     s = s>>18;
22133     *v = ((u64)s)<<32 | a;
22134     return 5;
22135   }
22136 
22137   /* 2:save off p0<<21 | p1<<14 | p2<<7 | p3 (masked) */
22138   s = s<<7;
22139   s |= b;
22140   /* s: p0<<21 | p1<<14 | p2<<7 | p3 (masked) */
22141 
22142   p++;
22143   b = b<<14;
22144   b |= *p;
22145   /* b: p1<<28 | p3<<14 | p5 (unmasked) */
22146   if (!(b&0x80))
22147   {
22148     /* we can skip this cause it was (effectively) done above in calc'ing s */
22149     /* b &= (0x7f<<28)|(0x7f<<14)|(0x7f); */
22150     a &= SLOT_2_0;
22151     a = a<<7;
22152     a |= b;
22153     s = s>>18;
22154     *v = ((u64)s)<<32 | a;
22155     return 6;
22156   }
22157 
22158   p++;
22159   a = a<<14;
22160   a |= *p;
22161   /* a: p2<<28 | p4<<14 | p6 (unmasked) */
22162   if (!(a&0x80))
22163   {
22164     a &= SLOT_4_2_0;
22165     b &= SLOT_2_0;
22166     b = b<<7;
22167     a |= b;
22168     s = s>>11;
22169     *v = ((u64)s)<<32 | a;
22170     return 7;
22171   }
22172 
22173   /* CSE2 from below */
22174   a &= SLOT_2_0;
22175   p++;
22176   b = b<<14;
22177   b |= *p;
22178   /* b: p3<<28 | p5<<14 | p7 (unmasked) */
22179   if (!(b&0x80))
22180   {
22181     b &= SLOT_4_2_0;
22182     /* moved CSE2 up */
22183     /* a &= (0x7f<<14)|(0x7f); */
22184     a = a<<7;
22185     a |= b;
22186     s = s>>4;
22187     *v = ((u64)s)<<32 | a;
22188     return 8;
22189   }
22190 
22191   p++;
22192   a = a<<15;
22193   a |= *p;
22194   /* a: p4<<29 | p6<<15 | p8 (unmasked) */
22195 
22196   /* moved CSE2 up */
22197   /* a &= (0x7f<<29)|(0x7f<<15)|(0xff); */
22198   b &= SLOT_2_0;
22199   b = b<<8;
22200   a |= b;
22201 
22202   s = s<<4;
22203   b = p[-4];
22204   b &= 0x7f;
22205   b = b>>3;
22206   s |= b;
22207 
22208   *v = ((u64)s)<<32 | a;
22209 
22210   return 9;
22211 }
22212 
22213 /*
22214 ** Read a 32-bit variable-length integer from memory starting at p[0].
22215 ** Return the number of bytes read.  The value is stored in *v.
22216 **
22217 ** If the varint stored in p[0] is larger than can fit in a 32-bit unsigned
22218 ** integer, then set *v to 0xffffffff.
22219 **
22220 ** A MACRO version, getVarint32, is provided which inlines the 
22221 ** single-byte case.  All code should use the MACRO version as 
22222 ** this function assumes the single-byte case has already been handled.
22223 */
22224 SQLITE_PRIVATE u8 sqlite3GetVarint32(const unsigned char *p, u32 *v){
22225   u32 a,b;
22226 
22227   /* The 1-byte case.  Overwhelmingly the most common.  Handled inline
22228   ** by the getVarin32() macro */
22229   a = *p;
22230   /* a: p0 (unmasked) */
22231 #ifndef getVarint32
22232   if (!(a&0x80))
22233   {
22234     /* Values between 0 and 127 */
22235     *v = a;
22236     return 1;
22237   }
22238 #endif
22239 
22240   /* The 2-byte case */
22241   p++;
22242   b = *p;
22243   /* b: p1 (unmasked) */
22244   if (!(b&0x80))
22245   {
22246     /* Values between 128 and 16383 */
22247     a &= 0x7f;
22248     a = a<<7;
22249     *v = a | b;
22250     return 2;
22251   }
22252 
22253   /* The 3-byte case */
22254   p++;
22255   a = a<<14;
22256   a |= *p;
22257   /* a: p0<<14 | p2 (unmasked) */
22258   if (!(a&0x80))
22259   {
22260     /* Values between 16384 and 2097151 */
22261     a &= (0x7f<<14)|(0x7f);
22262     b &= 0x7f;
22263     b = b<<7;
22264     *v = a | b;
22265     return 3;
22266   }
22267 
22268   /* A 32-bit varint is used to store size information in btrees.
22269   ** Objects are rarely larger than 2MiB limit of a 3-byte varint.
22270   ** A 3-byte varint is sufficient, for example, to record the size
22271   ** of a 1048569-byte BLOB or string.
22272   **
22273   ** We only unroll the first 1-, 2-, and 3- byte cases.  The very
22274   ** rare larger cases can be handled by the slower 64-bit varint
22275   ** routine.
22276   */
22277 #if 1
22278   {
22279     u64 v64;
22280     u8 n;
22281 
22282     p -= 2;
22283     n = sqlite3GetVarint(p, &v64);
22284     assert( n>3 && n<=9 );
22285     if( (v64 & SQLITE_MAX_U32)!=v64 ){
22286       *v = 0xffffffff;
22287     }else{
22288       *v = (u32)v64;
22289     }
22290     return n;
22291   }
22292 
22293 #else
22294   /* For following code (kept for historical record only) shows an
22295   ** unrolling for the 3- and 4-byte varint cases.  This code is
22296   ** slightly faster, but it is also larger and much harder to test.
22297   */
22298   p++;
22299   b = b<<14;
22300   b |= *p;
22301   /* b: p1<<14 | p3 (unmasked) */
22302   if (!(b&0x80))
22303   {
22304     /* Values between 2097152 and 268435455 */
22305     b &= (0x7f<<14)|(0x7f);
22306     a &= (0x7f<<14)|(0x7f);
22307     a = a<<7;
22308     *v = a | b;
22309     return 4;
22310   }
22311 
22312   p++;
22313   a = a<<14;
22314   a |= *p;
22315   /* a: p0<<28 | p2<<14 | p4 (unmasked) */
22316   if (!(a&0x80))
22317   {
22318     /* Values  between 268435456 and 34359738367 */
22319     a &= SLOT_4_2_0;
22320     b &= SLOT_4_2_0;
22321     b = b<<7;
22322     *v = a | b;
22323     return 5;
22324   }
22325 
22326   /* We can only reach this point when reading a corrupt database
22327   ** file.  In that case we are not in any hurry.  Use the (relatively
22328   ** slow) general-purpose sqlite3GetVarint() routine to extract the
22329   ** value. */
22330   {
22331     u64 v64;
22332     u8 n;
22333 
22334     p -= 4;
22335     n = sqlite3GetVarint(p, &v64);
22336     assert( n>5 && n<=9 );
22337     *v = (u32)v64;
22338     return n;
22339   }
22340 #endif
22341 }
22342 
22343 /*
22344 ** Return the number of bytes that will be needed to store the given
22345 ** 64-bit integer.
22346 */
22347 SQLITE_PRIVATE int sqlite3VarintLen(u64 v){
22348   int i = 0;
22349   do{
22350     i++;
22351     v >>= 7;
22352   }while( v!=0 && ALWAYS(i<9) );
22353   return i;
22354 }
22355 
22356 
22357 /*
22358 ** Read or write a four-byte big-endian integer value.
22359 */
22360 SQLITE_PRIVATE u32 sqlite3Get4byte(const u8 *p){
22361   return (p[0]<<24) | (p[1]<<16) | (p[2]<<8) | p[3];
22362 }
22363 SQLITE_PRIVATE void sqlite3Put4byte(unsigned char *p, u32 v){
22364   p[0] = (u8)(v>>24);
22365   p[1] = (u8)(v>>16);
22366   p[2] = (u8)(v>>8);
22367   p[3] = (u8)v;
22368 }
22369 
22370 
22371 
22372 /*
22373 ** Translate a single byte of Hex into an integer.
22374 ** This routine only works if h really is a valid hexadecimal
22375 ** character:  0..9a..fA..F
22376 */
22377 SQLITE_PRIVATE u8 sqlite3HexToInt(int h){
22378   assert( (h>='0' && h<='9') ||  (h>='a' && h<='f') ||  (h>='A' && h<='F') );
22379 #ifdef SQLITE_ASCII
22380   h += 9*(1&(h>>6));
22381 #endif
22382 #ifdef SQLITE_EBCDIC
22383   h += 9*(1&~(h>>4));
22384 #endif
22385   return (u8)(h & 0xf);
22386 }
22387 
22388 #if !defined(SQLITE_OMIT_BLOB_LITERAL) || defined(SQLITE_HAS_CODEC)
22389 /*
22390 ** Convert a BLOB literal of the form "x'hhhhhh'" into its binary
22391 ** value.  Return a pointer to its binary value.  Space to hold the
22392 ** binary value has been obtained from malloc and must be freed by
22393 ** the calling routine.
22394 */
22395 SQLITE_PRIVATE void *sqlite3HexToBlob(sqlite3 *db, const char *z, int n){
22396   char *zBlob;
22397   int i;
22398 
22399   zBlob = (char *)sqlite3DbMallocRaw(db, n/2 + 1);
22400   n--;
22401   if( zBlob ){
22402     for(i=0; i<n; i+=2){
22403       zBlob[i/2] = (sqlite3HexToInt(z[i])<<4) | sqlite3HexToInt(z[i+1]);
22404     }
22405     zBlob[i/2] = 0;
22406   }
22407   return zBlob;
22408 }
22409 #endif /* !SQLITE_OMIT_BLOB_LITERAL || SQLITE_HAS_CODEC */
22410 
22411 /*
22412 ** Log an error that is an API call on a connection pointer that should
22413 ** not have been used.  The "type" of connection pointer is given as the
22414 ** argument.  The zType is a word like "NULL" or "closed" or "invalid".
22415 */
22416 static void logBadConnection(const char *zType){
22417   sqlite3_log(SQLITE_MISUSE, 
22418      "API call with %s database connection pointer",
22419      zType
22420   );
22421 }
22422 
22423 /*
22424 ** Check to make sure we have a valid db pointer.  This test is not
22425 ** foolproof but it does provide some measure of protection against
22426 ** misuse of the interface such as passing in db pointers that are
22427 ** NULL or which have been previously closed.  If this routine returns
22428 ** 1 it means that the db pointer is valid and 0 if it should not be
22429 ** dereferenced for any reason.  The calling function should invoke
22430 ** SQLITE_MISUSE immediately.
22431 **
22432 ** sqlite3SafetyCheckOk() requires that the db pointer be valid for
22433 ** use.  sqlite3SafetyCheckSickOrOk() allows a db pointer that failed to
22434 ** open properly and is not fit for general use but which can be
22435 ** used as an argument to sqlite3_errmsg() or sqlite3_close().
22436 */
22437 SQLITE_PRIVATE int sqlite3SafetyCheckOk(sqlite3 *db){
22438   u32 magic;
22439   if( db==0 ){
22440     logBadConnection("NULL");
22441     return 0;
22442   }
22443   magic = db->magic;
22444   if( magic!=SQLITE_MAGIC_OPEN ){
22445     if( sqlite3SafetyCheckSickOrOk(db) ){
22446       testcase( sqlite3GlobalConfig.xLog!=0 );
22447       logBadConnection("unopened");
22448     }
22449     return 0;
22450   }else{
22451     return 1;
22452   }
22453 }
22454 SQLITE_PRIVATE int sqlite3SafetyCheckSickOrOk(sqlite3 *db){
22455   u32 magic;
22456   magic = db->magic;
22457   if( magic!=SQLITE_MAGIC_SICK &&
22458       magic!=SQLITE_MAGIC_OPEN &&
22459       magic!=SQLITE_MAGIC_BUSY ){
22460     testcase( sqlite3GlobalConfig.xLog!=0 );
22461     logBadConnection("invalid");
22462     return 0;
22463   }else{
22464     return 1;
22465   }
22466 }
22467 
22468 /*
22469 ** Attempt to add, substract, or multiply the 64-bit signed value iB against
22470 ** the other 64-bit signed integer at *pA and store the result in *pA.
22471 ** Return 0 on success.  Or if the operation would have resulted in an
22472 ** overflow, leave *pA unchanged and return 1.
22473 */
22474 SQLITE_PRIVATE int sqlite3AddInt64(i64 *pA, i64 iB){
22475   i64 iA = *pA;
22476   testcase( iA==0 ); testcase( iA==1 );
22477   testcase( iB==-1 ); testcase( iB==0 );
22478   if( iB>=0 ){
22479     testcase( iA>0 && LARGEST_INT64 - iA == iB );
22480     testcase( iA>0 && LARGEST_INT64 - iA == iB - 1 );
22481     if( iA>0 && LARGEST_INT64 - iA < iB ) return 1;
22482     *pA += iB;
22483   }else{
22484     testcase( iA<0 && -(iA + LARGEST_INT64) == iB + 1 );
22485     testcase( iA<0 && -(iA + LARGEST_INT64) == iB + 2 );
22486     if( iA<0 && -(iA + LARGEST_INT64) > iB + 1 ) return 1;
22487     *pA += iB;
22488   }
22489   return 0; 
22490 }
22491 SQLITE_PRIVATE int sqlite3SubInt64(i64 *pA, i64 iB){
22492   testcase( iB==SMALLEST_INT64+1 );
22493   if( iB==SMALLEST_INT64 ){
22494     testcase( (*pA)==(-1) ); testcase( (*pA)==0 );
22495     if( (*pA)>=0 ) return 1;
22496     *pA -= iB;
22497     return 0;
22498   }else{
22499     return sqlite3AddInt64(pA, -iB);
22500   }
22501 }
22502 #define TWOPOWER32 (((i64)1)<<32)
22503 #define TWOPOWER31 (((i64)1)<<31)
22504 SQLITE_PRIVATE int sqlite3MulInt64(i64 *pA, i64 iB){
22505   i64 iA = *pA;
22506   i64 iA1, iA0, iB1, iB0, r;
22507 
22508   iA1 = iA/TWOPOWER32;
22509   iA0 = iA % TWOPOWER32;
22510   iB1 = iB/TWOPOWER32;
22511   iB0 = iB % TWOPOWER32;
22512   if( iA1*iB1 != 0 ) return 1;
22513   assert( iA1*iB0==0 || iA0*iB1==0 );
22514   r = iA1*iB0 + iA0*iB1;
22515   testcase( r==(-TWOPOWER31)-1 );
22516   testcase( r==(-TWOPOWER31) );
22517   testcase( r==TWOPOWER31 );
22518   testcase( r==TWOPOWER31-1 );
22519   if( r<(-TWOPOWER31) || r>=TWOPOWER31 ) return 1;
22520   r *= TWOPOWER32;
22521   if( sqlite3AddInt64(&r, iA0*iB0) ) return 1;
22522   *pA = r;
22523   return 0;
22524 }
22525 
22526 /*
22527 ** Compute the absolute value of a 32-bit signed integer, of possible.  Or 
22528 ** if the integer has a value of -2147483648, return +2147483647
22529 */
22530 SQLITE_PRIVATE int sqlite3AbsInt32(int x){
22531   if( x>=0 ) return x;
22532   if( x==(int)0x80000000 ) return 0x7fffffff;
22533   return -x;
22534 }
22535 
22536 #ifdef SQLITE_ENABLE_8_3_NAMES
22537 /*
22538 ** If SQLITE_ENABLE_8_3_NAMES is set at compile-time and if the database
22539 ** filename in zBaseFilename is a URI with the "8_3_names=1" parameter and
22540 ** if filename in z[] has a suffix (a.k.a. "extension") that is longer than
22541 ** three characters, then shorten the suffix on z[] to be the last three
22542 ** characters of the original suffix.
22543 **
22544 ** If SQLITE_ENABLE_8_3_NAMES is set to 2 at compile-time, then always
22545 ** do the suffix shortening regardless of URI parameter.
22546 **
22547 ** Examples:
22548 **
22549 **     test.db-journal    =>   test.nal
22550 **     test.db-wal        =>   test.wal
22551 **     test.db-shm        =>   test.shm
22552 **     test.db-mj7f3319fa =>   test.9fa
22553 */
22554 SQLITE_PRIVATE void sqlite3FileSuffix3(const char *zBaseFilename, char *z){
22555 #if SQLITE_ENABLE_8_3_NAMES<2
22556   if( sqlite3_uri_boolean(zBaseFilename, "8_3_names", 0) )
22557 #endif
22558   {
22559     int i, sz;
22560     sz = sqlite3Strlen30(z);
22561     for(i=sz-1; i>0 && z[i]!='/' && z[i]!='.'; i--){}
22562     if( z[i]=='.' && ALWAYS(sz>i+4) ) memmove(&z[i+1], &z[sz-3], 4);
22563   }
22564 }
22565 #endif
22566 
22567 /* 
22568 ** Find (an approximate) sum of two LogEst values.  This computation is
22569 ** not a simple "+" operator because LogEst is stored as a logarithmic
22570 ** value.
22571 ** 
22572 */
22573 SQLITE_PRIVATE LogEst sqlite3LogEstAdd(LogEst a, LogEst b){
22574   static const unsigned char x[] = {
22575      10, 10,                         /* 0,1 */
22576       9, 9,                          /* 2,3 */
22577       8, 8,                          /* 4,5 */
22578       7, 7, 7,                       /* 6,7,8 */
22579       6, 6, 6,                       /* 9,10,11 */
22580       5, 5, 5,                       /* 12-14 */
22581       4, 4, 4, 4,                    /* 15-18 */
22582       3, 3, 3, 3, 3, 3,              /* 19-24 */
22583       2, 2, 2, 2, 2, 2, 2,           /* 25-31 */
22584   };
22585   if( a>=b ){
22586     if( a>b+49 ) return a;
22587     if( a>b+31 ) return a+1;
22588     return a+x[a-b];
22589   }else{
22590     if( b>a+49 ) return b;
22591     if( b>a+31 ) return b+1;
22592     return b+x[b-a];
22593   }
22594 }
22595 
22596 /*
22597 ** Convert an integer into a LogEst.  In other words, compute a
22598 ** good approximatation for 10*log2(x).
22599 */
22600 SQLITE_PRIVATE LogEst sqlite3LogEst(u64 x){
22601   static LogEst a[] = { 0, 2, 3, 5, 6, 7, 8, 9 };
22602   LogEst y = 40;
22603   if( x<8 ){
22604     if( x<2 ) return 0;
22605     while( x<8 ){  y -= 10; x <<= 1; }
22606   }else{
22607     while( x>255 ){ y += 40; x >>= 4; }
22608     while( x>15 ){  y += 10; x >>= 1; }
22609   }
22610   return a[x&7] + y - 10;
22611 }
22612 
22613 #ifndef SQLITE_OMIT_VIRTUALTABLE
22614 /*
22615 ** Convert a double into a LogEst
22616 ** In other words, compute an approximation for 10*log2(x).
22617 */
22618 SQLITE_PRIVATE LogEst sqlite3LogEstFromDouble(double x){
22619   u64 a;
22620   LogEst e;
22621   assert( sizeof(x)==8 && sizeof(a)==8 );
22622   if( x<=1 ) return 0;
22623   if( x<=2000000000 ) return sqlite3LogEst((u64)x);
22624   memcpy(&a, &x, 8);
22625   e = (a>>52) - 1022;
22626   return e*10;
22627 }
22628 #endif /* SQLITE_OMIT_VIRTUALTABLE */
22629 
22630 /*
22631 ** Convert a LogEst into an integer.
22632 */
22633 SQLITE_PRIVATE u64 sqlite3LogEstToInt(LogEst x){
22634   u64 n;
22635   if( x<10 ) return 1;
22636   n = x%10;
22637   x /= 10;
22638   if( n>=5 ) n -= 2;
22639   else if( n>=1 ) n -= 1;
22640   if( x>=3 ){
22641     return x>60 ? (u64)LARGEST_INT64 : (n+8)<<(x-3);
22642   }
22643   return (n+8)>>(3-x);
22644 }
22645 
22646 /************** End of util.c ************************************************/
22647 /************** Begin file hash.c ********************************************/
22648 /*
22649 ** 2001 September 22
22650 **
22651 ** The author disclaims copyright to this source code.  In place of
22652 ** a legal notice, here is a blessing:
22653 **
22654 **    May you do good and not evil.
22655 **    May you find forgiveness for yourself and forgive others.
22656 **    May you share freely, never taking more than you give.
22657 **
22658 *************************************************************************
22659 ** This is the implementation of generic hash-tables
22660 ** used in SQLite.
22661 */
22662 /* #include <assert.h> */
22663 
22664 /* Turn bulk memory into a hash table object by initializing the
22665 ** fields of the Hash structure.
22666 **
22667 ** "pNew" is a pointer to the hash table that is to be initialized.
22668 */
22669 SQLITE_PRIVATE void sqlite3HashInit(Hash *pNew){
22670   assert( pNew!=0 );
22671   pNew->first = 0;
22672   pNew->count = 0;
22673   pNew->htsize = 0;
22674   pNew->ht = 0;
22675 }
22676 
22677 /* Remove all entries from a hash table.  Reclaim all memory.
22678 ** Call this routine to delete a hash table or to reset a hash table
22679 ** to the empty state.
22680 */
22681 SQLITE_PRIVATE void sqlite3HashClear(Hash *pH){
22682   HashElem *elem;         /* For looping over all elements of the table */
22683 
22684   assert( pH!=0 );
22685   elem = pH->first;
22686   pH->first = 0;
22687   sqlite3_free(pH->ht);
22688   pH->ht = 0;
22689   pH->htsize = 0;
22690   while( elem ){
22691     HashElem *next_elem = elem->next;
22692     sqlite3_free(elem);
22693     elem = next_elem;
22694   }
22695   pH->count = 0;
22696 }
22697 
22698 /*
22699 ** The hashing function.
22700 */
22701 static unsigned int strHash(const char *z, int nKey){
22702   int h = 0;
22703   assert( nKey>=0 );
22704   while( nKey > 0  ){
22705     h = (h<<3) ^ h ^ sqlite3UpperToLower[(unsigned char)*z++];
22706     nKey--;
22707   }
22708   return h;
22709 }
22710 
22711 
22712 /* Link pNew element into the hash table pH.  If pEntry!=0 then also
22713 ** insert pNew into the pEntry hash bucket.
22714 */
22715 static void insertElement(
22716   Hash *pH,              /* The complete hash table */
22717   struct _ht *pEntry,    /* The entry into which pNew is inserted */
22718   HashElem *pNew         /* The element to be inserted */
22719 ){
22720   HashElem *pHead;       /* First element already in pEntry */
22721   if( pEntry ){
22722     pHead = pEntry->count ? pEntry->chain : 0;
22723     pEntry->count++;
22724     pEntry->chain = pNew;
22725   }else{
22726     pHead = 0;
22727   }
22728   if( pHead ){
22729     pNew->next = pHead;
22730     pNew->prev = pHead->prev;
22731     if( pHead->prev ){ pHead->prev->next = pNew; }
22732     else             { pH->first = pNew; }
22733     pHead->prev = pNew;
22734   }else{
22735     pNew->next = pH->first;
22736     if( pH->first ){ pH->first->prev = pNew; }
22737     pNew->prev = 0;
22738     pH->first = pNew;
22739   }
22740 }
22741 
22742 
22743 /* Resize the hash table so that it cantains "new_size" buckets.
22744 **
22745 ** The hash table might fail to resize if sqlite3_malloc() fails or
22746 ** if the new size is the same as the prior size.
22747 ** Return TRUE if the resize occurs and false if not.
22748 */
22749 static int rehash(Hash *pH, unsigned int new_size){
22750   struct _ht *new_ht;            /* The new hash table */
22751   HashElem *elem, *next_elem;    /* For looping over existing elements */
22752 
22753 #if SQLITE_MALLOC_SOFT_LIMIT>0
22754   if( new_size*sizeof(struct _ht)>SQLITE_MALLOC_SOFT_LIMIT ){
22755     new_size = SQLITE_MALLOC_SOFT_LIMIT/sizeof(struct _ht);
22756   }
22757   if( new_size==pH->htsize ) return 0;
22758 #endif
22759 
22760   /* The inability to allocates space for a larger hash table is
22761   ** a performance hit but it is not a fatal error.  So mark the
22762   ** allocation as a benign. Use sqlite3Malloc()/memset(0) instead of 
22763   ** sqlite3MallocZero() to make the allocation, as sqlite3MallocZero()
22764   ** only zeroes the requested number of bytes whereas this module will
22765   ** use the actual amount of space allocated for the hash table (which
22766   ** may be larger than the requested amount).
22767   */
22768   sqlite3BeginBenignMalloc();
22769   new_ht = (struct _ht *)sqlite3Malloc( new_size*sizeof(struct _ht) );
22770   sqlite3EndBenignMalloc();
22771 
22772   if( new_ht==0 ) return 0;
22773   sqlite3_free(pH->ht);
22774   pH->ht = new_ht;
22775   pH->htsize = new_size = sqlite3MallocSize(new_ht)/sizeof(struct _ht);
22776   memset(new_ht, 0, new_size*sizeof(struct _ht));
22777   for(elem=pH->first, pH->first=0; elem; elem = next_elem){
22778     unsigned int h = strHash(elem->pKey, elem->nKey) % new_size;
22779     next_elem = elem->next;
22780     insertElement(pH, &new_ht[h], elem);
22781   }
22782   return 1;
22783 }
22784 
22785 /* This function (for internal use only) locates an element in an
22786 ** hash table that matches the given key.  The hash for this key has
22787 ** already been computed and is passed as the 4th parameter.
22788 */
22789 static HashElem *findElementGivenHash(
22790   const Hash *pH,     /* The pH to be searched */
22791   const char *pKey,   /* The key we are searching for */
22792   int nKey,           /* Bytes in key (not counting zero terminator) */
22793   unsigned int h      /* The hash for this key. */
22794 ){
22795   HashElem *elem;                /* Used to loop thru the element list */
22796   int count;                     /* Number of elements left to test */
22797 
22798   if( pH->ht ){
22799     struct _ht *pEntry = &pH->ht[h];
22800     elem = pEntry->chain;
22801     count = pEntry->count;
22802   }else{
22803     elem = pH->first;
22804     count = pH->count;
22805   }
22806   while( count-- && ALWAYS(elem) ){
22807     if( elem->nKey==nKey && sqlite3StrNICmp(elem->pKey,pKey,nKey)==0 ){ 
22808       return elem;
22809     }
22810     elem = elem->next;
22811   }
22812   return 0;
22813 }
22814 
22815 /* Remove a single entry from the hash table given a pointer to that
22816 ** element and a hash on the element's key.
22817 */
22818 static void removeElementGivenHash(
22819   Hash *pH,         /* The pH containing "elem" */
22820   HashElem* elem,   /* The element to be removed from the pH */
22821   unsigned int h    /* Hash value for the element */
22822 ){
22823   struct _ht *pEntry;
22824   if( elem->prev ){
22825     elem->prev->next = elem->next; 
22826   }else{
22827     pH->first = elem->next;
22828   }
22829   if( elem->next ){
22830     elem->next->prev = elem->prev;
22831   }
22832   if( pH->ht ){
22833     pEntry = &pH->ht[h];
22834     if( pEntry->chain==elem ){
22835       pEntry->chain = elem->next;
22836     }
22837     pEntry->count--;
22838     assert( pEntry->count>=0 );
22839   }
22840   sqlite3_free( elem );
22841   pH->count--;
22842   if( pH->count==0 ){
22843     assert( pH->first==0 );
22844     assert( pH->count==0 );
22845     sqlite3HashClear(pH);
22846   }
22847 }
22848 
22849 /* Attempt to locate an element of the hash table pH with a key
22850 ** that matches pKey,nKey.  Return the data for this element if it is
22851 ** found, or NULL if there is no match.
22852 */
22853 SQLITE_PRIVATE void *sqlite3HashFind(const Hash *pH, const char *pKey, int nKey){
22854   HashElem *elem;    /* The element that matches key */
22855   unsigned int h;    /* A hash on key */
22856 
22857   assert( pH!=0 );
22858   assert( pKey!=0 );
22859   assert( nKey>=0 );
22860   if( pH->ht ){
22861     h = strHash(pKey, nKey) % pH->htsize;
22862   }else{
22863     h = 0;
22864   }
22865   elem = findElementGivenHash(pH, pKey, nKey, h);
22866   return elem ? elem->data : 0;
22867 }
22868 
22869 /* Insert an element into the hash table pH.  The key is pKey,nKey
22870 ** and the data is "data".
22871 **
22872 ** If no element exists with a matching key, then a new
22873 ** element is created and NULL is returned.
22874 **
22875 ** If another element already exists with the same key, then the
22876 ** new data replaces the old data and the old data is returned.
22877 ** The key is not copied in this instance.  If a malloc fails, then
22878 ** the new data is returned and the hash table is unchanged.
22879 **
22880 ** If the "data" parameter to this function is NULL, then the
22881 ** element corresponding to "key" is removed from the hash table.
22882 */
22883 SQLITE_PRIVATE void *sqlite3HashInsert(Hash *pH, const char *pKey, int nKey, void *data){
22884   unsigned int h;       /* the hash of the key modulo hash table size */
22885   HashElem *elem;       /* Used to loop thru the element list */
22886   HashElem *new_elem;   /* New element added to the pH */
22887 
22888   assert( pH!=0 );
22889   assert( pKey!=0 );
22890   assert( nKey>=0 );
22891   if( pH->htsize ){
22892     h = strHash(pKey, nKey) % pH->htsize;
22893   }else{
22894     h = 0;
22895   }
22896   elem = findElementGivenHash(pH,pKey,nKey,h);
22897   if( elem ){
22898     void *old_data = elem->data;
22899     if( data==0 ){
22900       removeElementGivenHash(pH,elem,h);
22901     }else{
22902       elem->data = data;
22903       elem->pKey = pKey;
22904       assert(nKey==elem->nKey);
22905     }
22906     return old_data;
22907   }
22908   if( data==0 ) return 0;
22909   new_elem = (HashElem*)sqlite3Malloc( sizeof(HashElem) );
22910   if( new_elem==0 ) return data;
22911   new_elem->pKey = pKey;
22912   new_elem->nKey = nKey;
22913   new_elem->data = data;
22914   pH->count++;
22915   if( pH->count>=10 && pH->count > 2*pH->htsize ){
22916     if( rehash(pH, pH->count*2) ){
22917       assert( pH->htsize>0 );
22918       h = strHash(pKey, nKey) % pH->htsize;
22919     }
22920   }
22921   if( pH->ht ){
22922     insertElement(pH, &pH->ht[h], new_elem);
22923   }else{
22924     insertElement(pH, 0, new_elem);
22925   }
22926   return 0;
22927 }
22928 
22929 /************** End of hash.c ************************************************/
22930 /************** Begin file opcodes.c *****************************************/
22931 /* Automatically generated.  Do not edit */
22932 /* See the mkopcodec.awk script for details. */
22933 #if !defined(SQLITE_OMIT_EXPLAIN) || defined(VDBE_PROFILE) || defined(SQLITE_DEBUG)
22934 #if defined(SQLITE_ENABLE_EXPLAIN_COMMENTS) || defined(SQLITE_DEBUG)
22935 # define OpHelp(X) "\0" X
22936 #else
22937 # define OpHelp(X)
22938 #endif
22939 SQLITE_PRIVATE const char *sqlite3OpcodeName(int i){
22940  static const char *const azName[] = { "?",
22941      /*   1 */ "Function"         OpHelp("r[P3]=func(r[P2@P5])"),
22942      /*   2 */ "Savepoint"        OpHelp(""),
22943      /*   3 */ "AutoCommit"       OpHelp(""),
22944      /*   4 */ "Transaction"      OpHelp(""),
22945      /*   5 */ "SorterNext"       OpHelp(""),
22946      /*   6 */ "PrevIfOpen"       OpHelp(""),
22947      /*   7 */ "NextIfOpen"       OpHelp(""),
22948      /*   8 */ "Prev"             OpHelp(""),
22949      /*   9 */ "Next"             OpHelp(""),
22950      /*  10 */ "AggStep"          OpHelp("accum=r[P3] step(r[P2@P5])"),
22951      /*  11 */ "Checkpoint"       OpHelp(""),
22952      /*  12 */ "JournalMode"      OpHelp(""),
22953      /*  13 */ "Vacuum"           OpHelp(""),
22954      /*  14 */ "VFilter"          OpHelp("iPlan=r[P3] zPlan='P4'"),
22955      /*  15 */ "VUpdate"          OpHelp("data=r[P3@P2]"),
22956      /*  16 */ "Goto"             OpHelp(""),
22957      /*  17 */ "Gosub"            OpHelp(""),
22958      /*  18 */ "Return"           OpHelp(""),
22959      /*  19 */ "Not"              OpHelp("r[P2]= !r[P1]"),
22960      /*  20 */ "Yield"            OpHelp(""),
22961      /*  21 */ "HaltIfNull"       OpHelp("if r[P3] null then halt"),
22962      /*  22 */ "Halt"             OpHelp(""),
22963      /*  23 */ "Integer"          OpHelp("r[P2]=P1"),
22964      /*  24 */ "Int64"            OpHelp("r[P2]=P4"),
22965      /*  25 */ "String"           OpHelp("r[P2]='P4' (len=P1)"),
22966      /*  26 */ "Null"             OpHelp("r[P2..P3]=NULL"),
22967      /*  27 */ "Blob"             OpHelp("r[P2]=P4 (len=P1)"),
22968      /*  28 */ "Variable"         OpHelp("r[P2]=parameter(P1,P4)"),
22969      /*  29 */ "Move"             OpHelp("r[P2@P3]=r[P1@P3]"),
22970      /*  30 */ "Copy"             OpHelp("r[P2@P3]=r[P1@P3]"),
22971      /*  31 */ "SCopy"            OpHelp("r[P2]=r[P1]"),
22972      /*  32 */ "ResultRow"        OpHelp("output=r[P1@P2]"),
22973      /*  33 */ "CollSeq"          OpHelp(""),
22974      /*  34 */ "AddImm"           OpHelp("r[P1]=r[P1]+P2"),
22975      /*  35 */ "MustBeInt"        OpHelp(""),
22976      /*  36 */ "RealAffinity"     OpHelp(""),
22977      /*  37 */ "Permutation"      OpHelp(""),
22978      /*  38 */ "Compare"          OpHelp(""),
22979      /*  39 */ "Jump"             OpHelp(""),
22980      /*  40 */ "Once"             OpHelp(""),
22981      /*  41 */ "If"               OpHelp(""),
22982      /*  42 */ "IfNot"            OpHelp(""),
22983      /*  43 */ "Column"           OpHelp("r[P3]=PX"),
22984      /*  44 */ "Affinity"         OpHelp("affinity(r[P1@P2])"),
22985      /*  45 */ "MakeRecord"       OpHelp("r[P3]=mkrec(r[P1@P2])"),
22986      /*  46 */ "Count"            OpHelp("r[P2]=count()"),
22987      /*  47 */ "ReadCookie"       OpHelp(""),
22988      /*  48 */ "SetCookie"        OpHelp(""),
22989      /*  49 */ "VerifyCookie"     OpHelp(""),
22990      /*  50 */ "OpenRead"         OpHelp("root=P2 iDb=P3"),
22991      /*  51 */ "OpenWrite"        OpHelp("root=P2 iDb=P3"),
22992      /*  52 */ "OpenAutoindex"    OpHelp("nColumn=P2"),
22993      /*  53 */ "OpenEphemeral"    OpHelp("nColumn=P2"),
22994      /*  54 */ "SorterOpen"       OpHelp(""),
22995      /*  55 */ "OpenPseudo"       OpHelp("content in r[P2@P3]"),
22996      /*  56 */ "Close"            OpHelp(""),
22997      /*  57 */ "SeekLt"           OpHelp("key=r[P3@P4]"),
22998      /*  58 */ "SeekLe"           OpHelp("key=r[P3@P4]"),
22999      /*  59 */ "SeekGe"           OpHelp("key=r[P3@P4]"),
23000      /*  60 */ "SeekGt"           OpHelp("key=r[P3@P4]"),
23001      /*  61 */ "Seek"             OpHelp("intkey=r[P2]"),
23002      /*  62 */ "NoConflict"       OpHelp("key=r[P3@P4]"),
23003      /*  63 */ "NotFound"         OpHelp("key=r[P3@P4]"),
23004      /*  64 */ "Found"            OpHelp("key=r[P3@P4]"),
23005      /*  65 */ "NotExists"        OpHelp("intkey=r[P3]"),
23006      /*  66 */ "Sequence"         OpHelp("r[P2]=rowid"),
23007      /*  67 */ "NewRowid"         OpHelp("r[P2]=rowid"),
23008      /*  68 */ "Insert"           OpHelp("intkey=r[P3] data=r[P2]"),
23009      /*  69 */ "Or"               OpHelp("r[P3]=(r[P1] || r[P2])"),
23010      /*  70 */ "And"              OpHelp("r[P3]=(r[P1] && r[P2])"),
23011      /*  71 */ "InsertInt"        OpHelp("intkey=P3 data=r[P2]"),
23012      /*  72 */ "Delete"           OpHelp(""),
23013      /*  73 */ "ResetCount"       OpHelp(""),
23014      /*  74 */ "IsNull"           OpHelp("if r[P1]==NULL goto P2"),
23015      /*  75 */ "NotNull"          OpHelp("if r[P1]!=NULL goto P2"),
23016      /*  76 */ "Ne"               OpHelp("if r[P1]!=r[P3] goto P2"),
23017      /*  77 */ "Eq"               OpHelp("if r[P1]==r[P3] goto P2"),
23018      /*  78 */ "Gt"               OpHelp("if r[P1]>r[P3] goto P2"),
23019      /*  79 */ "Le"               OpHelp("if r[P1]<=r[P3] goto P2"),
23020      /*  80 */ "Lt"               OpHelp("if r[P1]<r[P3] goto P2"),
23021      /*  81 */ "Ge"               OpHelp("if r[P1]>=r[P3] goto P2"),
23022      /*  82 */ "SorterCompare"    OpHelp("if key(P1)!=rtrim(r[P3],P4) goto P2"),
23023      /*  83 */ "BitAnd"           OpHelp("r[P3]=r[P1]&r[P2]"),
23024      /*  84 */ "BitOr"            OpHelp("r[P3]=r[P1]|r[P2]"),
23025      /*  85 */ "ShiftLeft"        OpHelp("r[P3]=r[P2]<<r[P1]"),
23026      /*  86 */ "ShiftRight"       OpHelp("r[P3]=r[P2]>>r[P1]"),
23027      /*  87 */ "Add"              OpHelp("r[P3]=r[P1]+r[P2]"),
23028      /*  88 */ "Subtract"         OpHelp("r[P3]=r[P2]-r[P1]"),
23029      /*  89 */ "Multiply"         OpHelp("r[P3]=r[P1]*r[P2]"),
23030      /*  90 */ "Divide"           OpHelp("r[P3]=r[P2]/r[P1]"),
23031      /*  91 */ "Remainder"        OpHelp("r[P3]=r[P2]%r[P1]"),
23032      /*  92 */ "Concat"           OpHelp("r[P3]=r[P2]+r[P1]"),
23033      /*  93 */ "SorterData"       OpHelp("r[P2]=data"),
23034      /*  94 */ "BitNot"           OpHelp("r[P1]= ~r[P1]"),
23035      /*  95 */ "String8"          OpHelp("r[P2]='P4'"),
23036      /*  96 */ "RowKey"           OpHelp("r[P2]=key"),
23037      /*  97 */ "RowData"          OpHelp("r[P2]=data"),
23038      /*  98 */ "Rowid"            OpHelp("r[P2]=rowid"),
23039      /*  99 */ "NullRow"          OpHelp(""),
23040      /* 100 */ "Last"             OpHelp(""),
23041      /* 101 */ "SorterSort"       OpHelp(""),
23042      /* 102 */ "Sort"             OpHelp(""),
23043      /* 103 */ "Rewind"           OpHelp(""),
23044      /* 104 */ "SorterInsert"     OpHelp(""),
23045      /* 105 */ "IdxInsert"        OpHelp("key=r[P2]"),
23046      /* 106 */ "IdxDelete"        OpHelp("key=r[P2@P3]"),
23047      /* 107 */ "IdxRowid"         OpHelp("r[P2]=rowid"),
23048      /* 108 */ "IdxLT"            OpHelp("key=r[P3@P4]"),
23049      /* 109 */ "IdxGE"            OpHelp("key=r[P3@P4]"),
23050      /* 110 */ "Destroy"          OpHelp(""),
23051      /* 111 */ "Clear"            OpHelp(""),
23052      /* 112 */ "CreateIndex"      OpHelp("r[P2]=root iDb=P1"),
23053      /* 113 */ "CreateTable"      OpHelp("r[P2]=root iDb=P1"),
23054      /* 114 */ "ParseSchema"      OpHelp(""),
23055      /* 115 */ "LoadAnalysis"     OpHelp(""),
23056      /* 116 */ "DropTable"        OpHelp(""),
23057      /* 117 */ "DropIndex"        OpHelp(""),
23058      /* 118 */ "DropTrigger"      OpHelp(""),
23059      /* 119 */ "IntegrityCk"      OpHelp(""),
23060      /* 120 */ "RowSetAdd"        OpHelp("rowset(P1)=r[P2]"),
23061      /* 121 */ "RowSetRead"       OpHelp("r[P3]=rowset(P1)"),
23062      /* 122 */ "RowSetTest"       OpHelp("if r[P3] in rowset(P1) goto P2"),
23063      /* 123 */ "Program"          OpHelp(""),
23064      /* 124 */ "Param"            OpHelp(""),
23065      /* 125 */ "FkCounter"        OpHelp("fkctr[P1]+=P2"),
23066      /* 126 */ "FkIfZero"         OpHelp("if fkctr[P1]==0 goto P2"),
23067      /* 127 */ "MemMax"           OpHelp("r[P1]=max(r[P1],r[P2])"),
23068      /* 128 */ "IfPos"            OpHelp("if r[P1]>0 goto P2"),
23069      /* 129 */ "IfNeg"            OpHelp("if r[P1]<0 goto P2"),
23070      /* 130 */ "IfZero"           OpHelp("r[P1]+=P3, if r[P1]==0 goto P2"),
23071      /* 131 */ "Real"             OpHelp("r[P2]=P4"),
23072      /* 132 */ "AggFinal"         OpHelp("accum=r[P1] N=P2"),
23073      /* 133 */ "IncrVacuum"       OpHelp(""),
23074      /* 134 */ "Expire"           OpHelp(""),
23075      /* 135 */ "TableLock"        OpHelp("iDb=P1 root=P2 write=P3"),
23076      /* 136 */ "VBegin"           OpHelp(""),
23077      /* 137 */ "VCreate"          OpHelp(""),
23078      /* 138 */ "VDestroy"         OpHelp(""),
23079      /* 139 */ "VOpen"            OpHelp(""),
23080      /* 140 */ "VColumn"          OpHelp("r[P3]=vcolumn(P2)"),
23081      /* 141 */ "VNext"            OpHelp(""),
23082      /* 142 */ "ToText"           OpHelp(""),
23083      /* 143 */ "ToBlob"           OpHelp(""),
23084      /* 144 */ "ToNumeric"        OpHelp(""),
23085      /* 145 */ "ToInt"            OpHelp(""),
23086      /* 146 */ "ToReal"           OpHelp(""),
23087      /* 147 */ "VRename"          OpHelp(""),
23088      /* 148 */ "Pagecount"        OpHelp(""),
23089      /* 149 */ "MaxPgcnt"         OpHelp(""),
23090      /* 150 */ "Trace"            OpHelp(""),
23091      /* 151 */ "Noop"             OpHelp(""),
23092      /* 152 */ "Explain"          OpHelp(""),
23093   };
23094   return azName[i];
23095 }
23096 #endif
23097 
23098 /************** End of opcodes.c *********************************************/
23099 /************** Begin file os_unix.c *****************************************/
23100 /*
23101 ** 2004 May 22
23102 **
23103 ** The author disclaims copyright to this source code.  In place of
23104 ** a legal notice, here is a blessing:
23105 **
23106 **    May you do good and not evil.
23107 **    May you find forgiveness for yourself and forgive others.
23108 **    May you share freely, never taking more than you give.
23109 **
23110 ******************************************************************************
23111 **
23112 ** This file contains the VFS implementation for unix-like operating systems
23113 ** include Linux, MacOSX, *BSD, QNX, VxWorks, AIX, HPUX, and others.
23114 **
23115 ** There are actually several different VFS implementations in this file.
23116 ** The differences are in the way that file locking is done.  The default
23117 ** implementation uses Posix Advisory Locks.  Alternative implementations
23118 ** use flock(), dot-files, various proprietary locking schemas, or simply
23119 ** skip locking all together.
23120 **
23121 ** This source file is organized into divisions where the logic for various
23122 ** subfunctions is contained within the appropriate division.  PLEASE
23123 ** KEEP THE STRUCTURE OF THIS FILE INTACT.  New code should be placed
23124 ** in the correct division and should be clearly labeled.
23125 **
23126 ** The layout of divisions is as follows:
23127 **
23128 **   *  General-purpose declarations and utility functions.
23129 **   *  Unique file ID logic used by VxWorks.
23130 **   *  Various locking primitive implementations (all except proxy locking):
23131 **      + for Posix Advisory Locks
23132 **      + for no-op locks
23133 **      + for dot-file locks
23134 **      + for flock() locking
23135 **      + for named semaphore locks (VxWorks only)
23136 **      + for AFP filesystem locks (MacOSX only)
23137 **   *  sqlite3_file methods not associated with locking.
23138 **   *  Definitions of sqlite3_io_methods objects for all locking
23139 **      methods plus "finder" functions for each locking method.
23140 **   *  sqlite3_vfs method implementations.
23141 **   *  Locking primitives for the proxy uber-locking-method. (MacOSX only)
23142 **   *  Definitions of sqlite3_vfs objects for all locking methods
23143 **      plus implementations of sqlite3_os_init() and sqlite3_os_end().
23144 */
23145 #if SQLITE_OS_UNIX              /* This file is used on unix only */
23146 
23147 /*
23148 ** There are various methods for file locking used for concurrency
23149 ** control:
23150 **
23151 **   1. POSIX locking (the default),
23152 **   2. No locking,
23153 **   3. Dot-file locking,
23154 **   4. flock() locking,
23155 **   5. AFP locking (OSX only),
23156 **   6. Named POSIX semaphores (VXWorks only),
23157 **   7. proxy locking. (OSX only)
23158 **
23159 ** Styles 4, 5, and 7 are only available of SQLITE_ENABLE_LOCKING_STYLE
23160 ** is defined to 1.  The SQLITE_ENABLE_LOCKING_STYLE also enables automatic
23161 ** selection of the appropriate locking style based on the filesystem
23162 ** where the database is located.  
23163 */
23164 #if !defined(SQLITE_ENABLE_LOCKING_STYLE)
23165 #  if defined(__APPLE__)
23166 #    define SQLITE_ENABLE_LOCKING_STYLE 1
23167 #  else
23168 #    define SQLITE_ENABLE_LOCKING_STYLE 0
23169 #  endif
23170 #endif
23171 
23172 /*
23173 ** Define the OS_VXWORKS pre-processor macro to 1 if building on 
23174 ** vxworks, or 0 otherwise.
23175 */
23176 #ifndef OS_VXWORKS
23177 #  if defined(__RTP__) || defined(_WRS_KERNEL)
23178 #    define OS_VXWORKS 1
23179 #  else
23180 #    define OS_VXWORKS 0
23181 #  endif
23182 #endif
23183 
23184 /*
23185 ** These #defines should enable >2GB file support on Posix if the
23186 ** underlying operating system supports it.  If the OS lacks
23187 ** large file support, these should be no-ops.
23188 **
23189 ** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch
23190 ** on the compiler command line.  This is necessary if you are compiling
23191 ** on a recent machine (ex: RedHat 7.2) but you want your code to work
23192 ** on an older machine (ex: RedHat 6.0).  If you compile on RedHat 7.2
23193 ** without this option, LFS is enable.  But LFS does not exist in the kernel
23194 ** in RedHat 6.0, so the code won't work.  Hence, for maximum binary
23195 ** portability you should omit LFS.
23196 **
23197 ** The previous paragraph was written in 2005.  (This paragraph is written
23198 ** on 2008-11-28.) These days, all Linux kernels support large files, so
23199 ** you should probably leave LFS enabled.  But some embedded platforms might
23200 ** lack LFS in which case the SQLITE_DISABLE_LFS macro might still be useful.
23201 */
23202 #ifndef SQLITE_DISABLE_LFS
23203 # define _LARGE_FILE       1
23204 # ifndef _FILE_OFFSET_BITS
23205 #   define _FILE_OFFSET_BITS 64
23206 # endif
23207 # define _LARGEFILE_SOURCE 1
23208 #endif
23209 
23210 /*
23211 ** standard include files.
23212 */
23213 #include <sys/types.h>
23214 #include <sys/stat.h>
23215 #include <fcntl.h>
23216 #include <unistd.h>
23217 /* #include <time.h> */
23218 #include <sys/time.h>
23219 #include <errno.h>
23220 #if !defined(SQLITE_OMIT_WAL) || SQLITE_MAX_MMAP_SIZE>0
23221 #include <sys/mman.h>
23222 #endif
23223 
23224 
23225 #if SQLITE_ENABLE_LOCKING_STYLE
23226 # include <sys/ioctl.h>
23227 # if OS_VXWORKS
23228 #  include <semaphore.h>
23229 #  include <limits.h>
23230 # else
23231 #  include <sys/file.h>
23232 #  include <sys/param.h>
23233 # endif
23234 #endif /* SQLITE_ENABLE_LOCKING_STYLE */
23235 
23236 #if defined(__APPLE__) || (SQLITE_ENABLE_LOCKING_STYLE && !OS_VXWORKS)
23237 # include <sys/mount.h>
23238 #endif
23239 
23240 #ifdef HAVE_UTIME
23241 # include <utime.h>
23242 #endif
23243 
23244 /*
23245 ** Allowed values of unixFile.fsFlags
23246 */
23247 #define SQLITE_FSFLAGS_IS_MSDOS     0x1
23248 
23249 /*
23250 ** If we are to be thread-safe, include the pthreads header and define
23251 ** the SQLITE_UNIX_THREADS macro.
23252 */
23253 #if SQLITE_THREADSAFE
23254 /* # include <pthread.h> */
23255 # define SQLITE_UNIX_THREADS 1
23256 #endif
23257 
23258 /*
23259 ** Default permissions when creating a new file
23260 */
23261 #ifndef SQLITE_DEFAULT_FILE_PERMISSIONS
23262 # define SQLITE_DEFAULT_FILE_PERMISSIONS 0644
23263 #endif
23264 
23265 /*
23266 ** Default permissions when creating auto proxy dir
23267 */
23268 #ifndef SQLITE_DEFAULT_PROXYDIR_PERMISSIONS
23269 # define SQLITE_DEFAULT_PROXYDIR_PERMISSIONS 0755
23270 #endif
23271 
23272 /*
23273 ** Maximum supported path-length.
23274 */
23275 #define MAX_PATHNAME 512
23276 
23277 /*
23278 ** Only set the lastErrno if the error code is a real error and not 
23279 ** a normal expected return code of SQLITE_BUSY or SQLITE_OK
23280 */
23281 #define IS_LOCK_ERROR(x)  ((x != SQLITE_OK) && (x != SQLITE_BUSY))
23282 
23283 /* Forward references */
23284 typedef struct unixShm unixShm;               /* Connection shared memory */
23285 typedef struct unixShmNode unixShmNode;       /* Shared memory instance */
23286 typedef struct unixInodeInfo unixInodeInfo;   /* An i-node */
23287 typedef struct UnixUnusedFd UnixUnusedFd;     /* An unused file descriptor */
23288 
23289 /*
23290 ** Sometimes, after a file handle is closed by SQLite, the file descriptor
23291 ** cannot be closed immediately. In these cases, instances of the following
23292 ** structure are used to store the file descriptor while waiting for an
23293 ** opportunity to either close or reuse it.
23294 */
23295 struct UnixUnusedFd {
23296   int fd;                   /* File descriptor to close */
23297   int flags;                /* Flags this file descriptor was opened with */
23298   UnixUnusedFd *pNext;      /* Next unused file descriptor on same file */
23299 };
23300 
23301 /*
23302 ** The unixFile structure is subclass of sqlite3_file specific to the unix
23303 ** VFS implementations.
23304 */
23305 typedef struct unixFile unixFile;
23306 struct unixFile {
23307   sqlite3_io_methods const *pMethod;  /* Always the first entry */
23308   sqlite3_vfs *pVfs;                  /* The VFS that created this unixFile */
23309   unixInodeInfo *pInode;              /* Info about locks on this inode */
23310   int h;                              /* The file descriptor */
23311   unsigned char eFileLock;            /* The type of lock held on this fd */
23312   unsigned short int ctrlFlags;       /* Behavioral bits.  UNIXFILE_* flags */
23313   int lastErrno;                      /* The unix errno from last I/O error */
23314   void *lockingContext;               /* Locking style specific state */
23315   UnixUnusedFd *pUnused;              /* Pre-allocated UnixUnusedFd */
23316   const char *zPath;                  /* Name of the file */
23317   unixShm *pShm;                      /* Shared memory segment information */
23318   int szChunk;                        /* Configured by FCNTL_CHUNK_SIZE */
23319 #if SQLITE_MAX_MMAP_SIZE>0
23320   int nFetchOut;                      /* Number of outstanding xFetch refs */
23321   sqlite3_int64 mmapSize;             /* Usable size of mapping at pMapRegion */
23322   sqlite3_int64 mmapSizeActual;       /* Actual size of mapping at pMapRegion */
23323   sqlite3_int64 mmapSizeMax;          /* Configured FCNTL_MMAP_SIZE value */
23324   void *pMapRegion;                   /* Memory mapped region */
23325 #endif
23326 #ifdef __QNXNTO__
23327   int sectorSize;                     /* Device sector size */
23328   int deviceCharacteristics;          /* Precomputed device characteristics */
23329 #endif
23330 #if SQLITE_ENABLE_LOCKING_STYLE
23331   int openFlags;                      /* The flags specified at open() */
23332 #endif
23333 #if SQLITE_ENABLE_LOCKING_STYLE || defined(__APPLE__)
23334   unsigned fsFlags;                   /* cached details from statfs() */
23335 #endif
23336 #if OS_VXWORKS
23337   struct vxworksFileId *pId;          /* Unique file ID */
23338 #endif
23339 #ifdef SQLITE_DEBUG
23340   /* The next group of variables are used to track whether or not the
23341   ** transaction counter in bytes 24-27 of database files are updated
23342   ** whenever any part of the database changes.  An assertion fault will
23343   ** occur if a file is updated without also updating the transaction
23344   ** counter.  This test is made to avoid new problems similar to the
23345   ** one described by ticket #3584. 
23346   */
23347   unsigned char transCntrChng;   /* True if the transaction counter changed */
23348   unsigned char dbUpdate;        /* True if any part of database file changed */
23349   unsigned char inNormalWrite;   /* True if in a normal write operation */
23350 
23351 #endif
23352 
23353 #ifdef SQLITE_TEST
23354   /* In test mode, increase the size of this structure a bit so that 
23355   ** it is larger than the struct CrashFile defined in test6.c.
23356   */
23357   char aPadding[32];
23358 #endif
23359 };
23360 
23361 /*
23362 ** Allowed values for the unixFile.ctrlFlags bitmask:
23363 */
23364 #define UNIXFILE_EXCL        0x01     /* Connections from one process only */
23365 #define UNIXFILE_RDONLY      0x02     /* Connection is read only */
23366 #define UNIXFILE_PERSIST_WAL 0x04     /* Persistent WAL mode */
23367 #ifndef SQLITE_DISABLE_DIRSYNC
23368 # define UNIXFILE_DIRSYNC    0x08     /* Directory sync needed */
23369 #else
23370 # define UNIXFILE_DIRSYNC    0x00
23371 #endif
23372 #define UNIXFILE_PSOW        0x10     /* SQLITE_IOCAP_POWERSAFE_OVERWRITE */
23373 #define UNIXFILE_DELETE      0x20     /* Delete on close */
23374 #define UNIXFILE_URI         0x40     /* Filename might have query parameters */
23375 #define UNIXFILE_NOLOCK      0x80     /* Do no file locking */
23376 #define UNIXFILE_WARNED    0x0100     /* verifyDbFile() warnings have been issued */
23377 
23378 /*
23379 ** Include code that is common to all os_*.c files
23380 */
23381 /************** Include os_common.h in the middle of os_unix.c ***************/
23382 /************** Begin file os_common.h ***************************************/
23383 /*
23384 ** 2004 May 22
23385 **
23386 ** The author disclaims copyright to this source code.  In place of
23387 ** a legal notice, here is a blessing:
23388 **
23389 **    May you do good and not evil.
23390 **    May you find forgiveness for yourself and forgive others.
23391 **    May you share freely, never taking more than you give.
23392 **
23393 ******************************************************************************
23394 **
23395 ** This file contains macros and a little bit of code that is common to
23396 ** all of the platform-specific files (os_*.c) and is #included into those
23397 ** files.
23398 **
23399 ** This file should be #included by the os_*.c files only.  It is not a
23400 ** general purpose header file.
23401 */
23402 #ifndef _OS_COMMON_H_
23403 #define _OS_COMMON_H_
23404 
23405 /*
23406 ** At least two bugs have slipped in because we changed the MEMORY_DEBUG
23407 ** macro to SQLITE_DEBUG and some older makefiles have not yet made the
23408 ** switch.  The following code should catch this problem at compile-time.
23409 */
23410 #ifdef MEMORY_DEBUG
23411 # error "The MEMORY_DEBUG macro is obsolete.  Use SQLITE_DEBUG instead."
23412 #endif
23413 
23414 #if defined(SQLITE_TEST) && defined(SQLITE_DEBUG)
23415 # ifndef SQLITE_DEBUG_OS_TRACE
23416 #   define SQLITE_DEBUG_OS_TRACE 0
23417 # endif
23418   int sqlite3OSTrace = SQLITE_DEBUG_OS_TRACE;
23419 # define OSTRACE(X)          if( sqlite3OSTrace ) sqlite3DebugPrintf X
23420 #else
23421 # define OSTRACE(X)
23422 #endif
23423 
23424 /*
23425 ** Macros for performance tracing.  Normally turned off.  Only works
23426 ** on i486 hardware.
23427 */
23428 #ifdef SQLITE_PERFORMANCE_TRACE
23429 
23430 /* 
23431 ** hwtime.h contains inline assembler code for implementing 
23432 ** high-performance timing routines.
23433 */
23434 /************** Include hwtime.h in the middle of os_common.h ****************/
23435 /************** Begin file hwtime.h ******************************************/
23436 /*
23437 ** 2008 May 27
23438 **
23439 ** The author disclaims copyright to this source code.  In place of
23440 ** a legal notice, here is a blessing:
23441 **
23442 **    May you do good and not evil.
23443 **    May you find forgiveness for yourself and forgive others.
23444 **    May you share freely, never taking more than you give.
23445 **
23446 ******************************************************************************
23447 **
23448 ** This file contains inline asm code for retrieving "high-performance"
23449 ** counters for x86 class CPUs.
23450 */
23451 #ifndef _HWTIME_H_
23452 #define _HWTIME_H_
23453 
23454 /*
23455 ** The following routine only works on pentium-class (or newer) processors.
23456 ** It uses the RDTSC opcode to read the cycle count value out of the
23457 ** processor and returns that value.  This can be used for high-res
23458 ** profiling.
23459 */
23460 #if (defined(__GNUC__) || defined(_MSC_VER)) && \
23461       (defined(i386) || defined(__i386__) || defined(_M_IX86))
23462 
23463   #if defined(__GNUC__)
23464 
23465   __inline__ sqlite_uint64 sqlite3Hwtime(void){
23466      unsigned int lo, hi;
23467      __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi));
23468      return (sqlite_uint64)hi << 32 | lo;
23469   }
23470 
23471   #elif defined(_MSC_VER)
23472 
23473   __declspec(naked) __inline sqlite_uint64 __cdecl sqlite3Hwtime(void){
23474      __asm {
23475         rdtsc
23476         ret       ; return value at EDX:EAX
23477      }
23478   }
23479 
23480   #endif
23481 
23482 #elif (defined(__GNUC__) && defined(__x86_64__))
23483 
23484   __inline__ sqlite_uint64 sqlite3Hwtime(void){
23485       unsigned long val;
23486       __asm__ __volatile__ ("rdtsc" : "=A" (val));
23487       return val;
23488   }
23489  
23490 #elif (defined(__GNUC__) && defined(__ppc__))
23491 
23492   __inline__ sqlite_uint64 sqlite3Hwtime(void){
23493       unsigned long long retval;
23494       unsigned long junk;
23495       __asm__ __volatile__ ("\n\
23496           1:      mftbu   %1\n\
23497                   mftb    %L0\n\
23498                   mftbu   %0\n\
23499                   cmpw    %0,%1\n\
23500                   bne     1b"
23501                   : "=r" (retval), "=r" (junk));
23502       return retval;
23503   }
23504 
23505 #else
23506 
23507   #error Need implementation of sqlite3Hwtime() for your platform.
23508 
23509   /*
23510   ** To compile without implementing sqlite3Hwtime() for your platform,
23511   ** you can remove the above #error and use the following
23512   ** stub function.  You will lose timing support for many
23513   ** of the debugging and testing utilities, but it should at
23514   ** least compile and run.
23515   */
23516 SQLITE_PRIVATE   sqlite_uint64 sqlite3Hwtime(void){ return ((sqlite_uint64)0); }
23517 
23518 #endif
23519 
23520 #endif /* !defined(_HWTIME_H_) */
23521 
23522 /************** End of hwtime.h **********************************************/
23523 /************** Continuing where we left off in os_common.h ******************/
23524 
23525 static sqlite_uint64 g_start;
23526 static sqlite_uint64 g_elapsed;
23527 #define TIMER_START       g_start=sqlite3Hwtime()
23528 #define TIMER_END         g_elapsed=sqlite3Hwtime()-g_start
23529 #define TIMER_ELAPSED     g_elapsed
23530 #else
23531 #define TIMER_START
23532 #define TIMER_END
23533 #define TIMER_ELAPSED     ((sqlite_uint64)0)
23534 #endif
23535 
23536 /*
23537 ** If we compile with the SQLITE_TEST macro set, then the following block
23538 ** of code will give us the ability to simulate a disk I/O error.  This
23539 ** is used for testing the I/O recovery logic.
23540 */
23541 #ifdef SQLITE_TEST
23542 SQLITE_API int sqlite3_io_error_hit = 0;            /* Total number of I/O Errors */
23543 SQLITE_API int sqlite3_io_error_hardhit = 0;        /* Number of non-benign errors */
23544 SQLITE_API int sqlite3_io_error_pending = 0;        /* Count down to first I/O error */
23545 SQLITE_API int sqlite3_io_error_persist = 0;        /* True if I/O errors persist */
23546 SQLITE_API int sqlite3_io_error_benign = 0;         /* True if errors are benign */
23547 SQLITE_API int sqlite3_diskfull_pending = 0;
23548 SQLITE_API int sqlite3_diskfull = 0;
23549 #define SimulateIOErrorBenign(X) sqlite3_io_error_benign=(X)
23550 #define SimulateIOError(CODE)  \
23551   if( (sqlite3_io_error_persist && sqlite3_io_error_hit) \
23552        || sqlite3_io_error_pending-- == 1 )  \
23553               { local_ioerr(); CODE; }
23554 static void local_ioerr(){
23555   IOTRACE(("IOERR\n"));
23556   sqlite3_io_error_hit++;
23557   if( !sqlite3_io_error_benign ) sqlite3_io_error_hardhit++;
23558 }
23559 #define SimulateDiskfullError(CODE) \
23560    if( sqlite3_diskfull_pending ){ \
23561      if( sqlite3_diskfull_pending == 1 ){ \
23562        local_ioerr(); \
23563        sqlite3_diskfull = 1; \
23564        sqlite3_io_error_hit = 1; \
23565        CODE; \
23566      }else{ \
23567        sqlite3_diskfull_pending--; \
23568      } \
23569    }
23570 #else
23571 #define SimulateIOErrorBenign(X)
23572 #define SimulateIOError(A)
23573 #define SimulateDiskfullError(A)
23574 #endif
23575 
23576 /*
23577 ** When testing, keep a count of the number of open files.
23578 */
23579 #ifdef SQLITE_TEST
23580 SQLITE_API int sqlite3_open_file_count = 0;
23581 #define OpenCounter(X)  sqlite3_open_file_count+=(X)
23582 #else
23583 #define OpenCounter(X)
23584 #endif
23585 
23586 #endif /* !defined(_OS_COMMON_H_) */
23587 
23588 /************** End of os_common.h *******************************************/
23589 /************** Continuing where we left off in os_unix.c ********************/
23590 
23591 /*
23592 ** Define various macros that are missing from some systems.
23593 */
23594 #ifndef O_LARGEFILE
23595 # define O_LARGEFILE 0
23596 #endif
23597 #ifdef SQLITE_DISABLE_LFS
23598 # undef O_LARGEFILE
23599 # define O_LARGEFILE 0
23600 #endif
23601 #ifndef O_NOFOLLOW
23602 # define O_NOFOLLOW 0
23603 #endif
23604 #ifndef O_BINARY
23605 # define O_BINARY 0
23606 #endif
23607 
23608 /*
23609 ** The threadid macro resolves to the thread-id or to 0.  Used for
23610 ** testing and debugging only.
23611 */
23612 #if SQLITE_THREADSAFE
23613 #define threadid pthread_self()
23614 #else
23615 #define threadid 0
23616 #endif
23617 
23618 /*
23619 ** HAVE_MREMAP defaults to true on Linux and false everywhere else.
23620 */
23621 #if !defined(HAVE_MREMAP)
23622 # if defined(__linux__) && defined(_GNU_SOURCE)
23623 #  define HAVE_MREMAP 1
23624 # else
23625 #  define HAVE_MREMAP 0
23626 # endif
23627 #endif
23628 
23629 /*
23630 ** Different Unix systems declare open() in different ways.  Same use
23631 ** open(const char*,int,mode_t).  Others use open(const char*,int,...).
23632 ** The difference is important when using a pointer to the function.
23633 **
23634 ** The safest way to deal with the problem is to always use this wrapper
23635 ** which always has the same well-defined interface.
23636 */
23637 static int posixOpen(const char *zFile, int flags, int mode){
23638   return open(zFile, flags, mode);
23639 }
23640 
23641 /*
23642 ** On some systems, calls to fchown() will trigger a message in a security
23643 ** log if they come from non-root processes.  So avoid calling fchown() if
23644 ** we are not running as root.
23645 */
23646 static int posixFchown(int fd, uid_t uid, gid_t gid){
23647   return geteuid() ? 0 : fchown(fd,uid,gid);
23648 }
23649 
23650 /* Forward reference */
23651 static int openDirectory(const char*, int*);
23652 
23653 /*
23654 ** Many system calls are accessed through pointer-to-functions so that
23655 ** they may be overridden at runtime to facilitate fault injection during
23656 ** testing and sandboxing.  The following array holds the names and pointers
23657 ** to all overrideable system calls.
23658 */
23659 static struct unix_syscall {
23660   const char *zName;            /* Name of the system call */
23661   sqlite3_syscall_ptr pCurrent; /* Current value of the system call */
23662   sqlite3_syscall_ptr pDefault; /* Default value */
23663 } aSyscall[] = {
23664   { "open",         (sqlite3_syscall_ptr)posixOpen,  0  },
23665 #define osOpen      ((int(*)(const char*,int,int))aSyscall[0].pCurrent)
23666 
23667   { "close",        (sqlite3_syscall_ptr)close,      0  },
23668 #define osClose     ((int(*)(int))aSyscall[1].pCurrent)
23669 
23670   { "access",       (sqlite3_syscall_ptr)access,     0  },
23671 #define osAccess    ((int(*)(const char*,int))aSyscall[2].pCurrent)
23672 
23673   { "getcwd",       (sqlite3_syscall_ptr)getcwd,     0  },
23674 #define osGetcwd    ((char*(*)(char*,size_t))aSyscall[3].pCurrent)
23675 
23676   { "stat",         (sqlite3_syscall_ptr)stat,       0  },
23677 #define osStat      ((int(*)(const char*,struct stat*))aSyscall[4].pCurrent)
23678 
23679 /*
23680 ** The DJGPP compiler environment looks mostly like Unix, but it
23681 ** lacks the fcntl() system call.  So redefine fcntl() to be something
23682 ** that always succeeds.  This means that locking does not occur under
23683 ** DJGPP.  But it is DOS - what did you expect?
23684 */
23685 #ifdef __DJGPP__
23686   { "fstat",        0,                 0  },
23687 #define osFstat(a,b,c)    0
23688 #else     
23689   { "fstat",        (sqlite3_syscall_ptr)fstat,      0  },
23690 #define osFstat     ((int(*)(int,struct stat*))aSyscall[5].pCurrent)
23691 #endif
23692 
23693   { "ftruncate",    (sqlite3_syscall_ptr)ftruncate,  0  },
23694 #define osFtruncate ((int(*)(int,off_t))aSyscall[6].pCurrent)
23695 
23696   { "fcntl",        (sqlite3_syscall_ptr)fcntl,      0  },
23697 #define osFcntl     ((int(*)(int,int,...))aSyscall[7].pCurrent)
23698 
23699   { "read",         (sqlite3_syscall_ptr)read,       0  },
23700 #define osRead      ((ssize_t(*)(int,void*,size_t))aSyscall[8].pCurrent)
23701 
23702 #if defined(USE_PREAD) || SQLITE_ENABLE_LOCKING_STYLE
23703   { "pread",        (sqlite3_syscall_ptr)pread,      0  },
23704 #else
23705   { "pread",        (sqlite3_syscall_ptr)0,          0  },
23706 #endif
23707 #define osPread     ((ssize_t(*)(int,void*,size_t,off_t))aSyscall[9].pCurrent)
23708 
23709 #if defined(USE_PREAD64)
23710   { "pread64",      (sqlite3_syscall_ptr)pread64,    0  },
23711 #else
23712   { "pread64",      (sqlite3_syscall_ptr)0,          0  },
23713 #endif
23714 #define osPread64   ((ssize_t(*)(int,void*,size_t,off_t))aSyscall[10].pCurrent)
23715 
23716   { "write",        (sqlite3_syscall_ptr)write,      0  },
23717 #define osWrite     ((ssize_t(*)(int,const void*,size_t))aSyscall[11].pCurrent)
23718 
23719 #if defined(USE_PREAD) || SQLITE_ENABLE_LOCKING_STYLE
23720   { "pwrite",       (sqlite3_syscall_ptr)pwrite,     0  },
23721 #else
23722   { "pwrite",       (sqlite3_syscall_ptr)0,          0  },
23723 #endif
23724 #define osPwrite    ((ssize_t(*)(int,const void*,size_t,off_t))\
23725                     aSyscall[12].pCurrent)
23726 
23727 #if defined(USE_PREAD64)
23728   { "pwrite64",     (sqlite3_syscall_ptr)pwrite64,   0  },
23729 #else
23730   { "pwrite64",     (sqlite3_syscall_ptr)0,          0  },
23731 #endif
23732 #define osPwrite64  ((ssize_t(*)(int,const void*,size_t,off_t))\
23733                     aSyscall[13].pCurrent)
23734 
23735   { "fchmod",       (sqlite3_syscall_ptr)fchmod,     0  },
23736 #define osFchmod    ((int(*)(int,mode_t))aSyscall[14].pCurrent)
23737 
23738 #if defined(HAVE_POSIX_FALLOCATE) && HAVE_POSIX_FALLOCATE
23739   { "fallocate",    (sqlite3_syscall_ptr)posix_fallocate,  0 },
23740 #else
23741   { "fallocate",    (sqlite3_syscall_ptr)0,                0 },
23742 #endif
23743 #define osFallocate ((int(*)(int,off_t,off_t))aSyscall[15].pCurrent)
23744 
23745   { "unlink",       (sqlite3_syscall_ptr)unlink,           0 },
23746 #define osUnlink    ((int(*)(const char*))aSyscall[16].pCurrent)
23747 
23748   { "openDirectory",    (sqlite3_syscall_ptr)openDirectory,      0 },
23749 #define osOpenDirectory ((int(*)(const char*,int*))aSyscall[17].pCurrent)
23750 
23751   { "mkdir",        (sqlite3_syscall_ptr)mkdir,           0 },
23752 #define osMkdir     ((int(*)(const char*,mode_t))aSyscall[18].pCurrent)
23753 
23754   { "rmdir",        (sqlite3_syscall_ptr)rmdir,           0 },
23755 #define osRmdir     ((int(*)(const char*))aSyscall[19].pCurrent)
23756 
23757   { "fchown",       (sqlite3_syscall_ptr)posixFchown,     0 },
23758 #define osFchown    ((int(*)(int,uid_t,gid_t))aSyscall[20].pCurrent)
23759 
23760 #if !defined(SQLITE_OMIT_WAL) || SQLITE_MAX_MMAP_SIZE>0
23761   { "mmap",       (sqlite3_syscall_ptr)mmap,     0 },
23762 #define osMmap ((void*(*)(void*,size_t,int,int,int,off_t))aSyscall[21].pCurrent)
23763 
23764   { "munmap",       (sqlite3_syscall_ptr)munmap,          0 },
23765 #define osMunmap ((void*(*)(void*,size_t))aSyscall[22].pCurrent)
23766 
23767 #if HAVE_MREMAP
23768   { "mremap",       (sqlite3_syscall_ptr)mremap,          0 },
23769 #else
23770   { "mremap",       (sqlite3_syscall_ptr)0,               0 },
23771 #endif
23772 #define osMremap ((void*(*)(void*,size_t,size_t,int,...))aSyscall[23].pCurrent)
23773 #endif
23774 
23775 }; /* End of the overrideable system calls */
23776 
23777 /*
23778 ** This is the xSetSystemCall() method of sqlite3_vfs for all of the
23779 ** "unix" VFSes.  Return SQLITE_OK opon successfully updating the
23780 ** system call pointer, or SQLITE_NOTFOUND if there is no configurable
23781 ** system call named zName.
23782 */
23783 static int unixSetSystemCall(
23784   sqlite3_vfs *pNotUsed,        /* The VFS pointer.  Not used */
23785   const char *zName,            /* Name of system call to override */
23786   sqlite3_syscall_ptr pNewFunc  /* Pointer to new system call value */
23787 ){
23788   unsigned int i;
23789   int rc = SQLITE_NOTFOUND;
23790 
23791   UNUSED_PARAMETER(pNotUsed);
23792   if( zName==0 ){
23793     /* If no zName is given, restore all system calls to their default
23794     ** settings and return NULL
23795     */
23796     rc = SQLITE_OK;
23797     for(i=0; i<sizeof(aSyscall)/sizeof(aSyscall[0]); i++){
23798       if( aSyscall[i].pDefault ){
23799         aSyscall[i].pCurrent = aSyscall[i].pDefault;
23800       }
23801     }
23802   }else{
23803     /* If zName is specified, operate on only the one system call
23804     ** specified.
23805     */
23806     for(i=0; i<sizeof(aSyscall)/sizeof(aSyscall[0]); i++){
23807       if( strcmp(zName, aSyscall[i].zName)==0 ){
23808         if( aSyscall[i].pDefault==0 ){
23809           aSyscall[i].pDefault = aSyscall[i].pCurrent;
23810         }
23811         rc = SQLITE_OK;
23812         if( pNewFunc==0 ) pNewFunc = aSyscall[i].pDefault;
23813         aSyscall[i].pCurrent = pNewFunc;
23814         break;
23815       }
23816     }
23817   }
23818   return rc;
23819 }
23820 
23821 /*
23822 ** Return the value of a system call.  Return NULL if zName is not a
23823 ** recognized system call name.  NULL is also returned if the system call
23824 ** is currently undefined.
23825 */
23826 static sqlite3_syscall_ptr unixGetSystemCall(
23827   sqlite3_vfs *pNotUsed,
23828   const char *zName
23829 ){
23830   unsigned int i;
23831 
23832   UNUSED_PARAMETER(pNotUsed);
23833   for(i=0; i<sizeof(aSyscall)/sizeof(aSyscall[0]); i++){
23834     if( strcmp(zName, aSyscall[i].zName)==0 ) return aSyscall[i].pCurrent;
23835   }
23836   return 0;
23837 }
23838 
23839 /*
23840 ** Return the name of the first system call after zName.  If zName==NULL
23841 ** then return the name of the first system call.  Return NULL if zName
23842 ** is the last system call or if zName is not the name of a valid
23843 ** system call.
23844 */
23845 static const char *unixNextSystemCall(sqlite3_vfs *p, const char *zName){
23846   int i = -1;
23847 
23848   UNUSED_PARAMETER(p);
23849   if( zName ){
23850     for(i=0; i<ArraySize(aSyscall)-1; i++){
23851       if( strcmp(zName, aSyscall[i].zName)==0 ) break;
23852     }
23853   }
23854   for(i++; i<ArraySize(aSyscall); i++){
23855     if( aSyscall[i].pCurrent!=0 ) return aSyscall[i].zName;
23856   }
23857   return 0;
23858 }
23859 
23860 /*
23861 ** Do not accept any file descriptor less than this value, in order to avoid
23862 ** opening database file using file descriptors that are commonly used for 
23863 ** standard input, output, and error.
23864 */
23865 #ifndef SQLITE_MINIMUM_FILE_DESCRIPTOR
23866 # define SQLITE_MINIMUM_FILE_DESCRIPTOR 3
23867 #endif
23868 
23869 /*
23870 ** Invoke open().  Do so multiple times, until it either succeeds or
23871 ** fails for some reason other than EINTR.
23872 **
23873 ** If the file creation mode "m" is 0 then set it to the default for
23874 ** SQLite.  The default is SQLITE_DEFAULT_FILE_PERMISSIONS (normally
23875 ** 0644) as modified by the system umask.  If m is not 0, then
23876 ** make the file creation mode be exactly m ignoring the umask.
23877 **
23878 ** The m parameter will be non-zero only when creating -wal, -journal,
23879 ** and -shm files.  We want those files to have *exactly* the same
23880 ** permissions as their original database, unadulterated by the umask.
23881 ** In that way, if a database file is -rw-rw-rw or -rw-rw-r-, and a
23882 ** transaction crashes and leaves behind hot journals, then any
23883 ** process that is able to write to the database will also be able to
23884 ** recover the hot journals.
23885 */
23886 static int robust_open(const char *z, int f, mode_t m){
23887   int fd;
23888   mode_t m2 = m ? m : SQLITE_DEFAULT_FILE_PERMISSIONS;
23889   while(1){
23890 #if defined(O_CLOEXEC)
23891     fd = osOpen(z,f|O_CLOEXEC,m2);
23892 #else
23893     fd = osOpen(z,f,m2);
23894 #endif
23895     if( fd<0 ){
23896       if( errno==EINTR ) continue;
23897       break;
23898     }
23899     if( fd>=SQLITE_MINIMUM_FILE_DESCRIPTOR ) break;
23900     osClose(fd);
23901     sqlite3_log(SQLITE_WARNING, 
23902                 "attempt to open \"%s\" as file descriptor %d", z, fd);
23903     fd = -1;
23904     if( osOpen("/dev/null", f, m)<0 ) break;
23905   }
23906   if( fd>=0 ){
23907     if( m!=0 ){
23908       struct stat statbuf;
23909       if( osFstat(fd, &statbuf)==0 
23910        && statbuf.st_size==0
23911        && (statbuf.st_mode&0777)!=m 
23912       ){
23913         osFchmod(fd, m);
23914       }
23915     }
23916 #if defined(FD_CLOEXEC) && (!defined(O_CLOEXEC) || O_CLOEXEC==0)
23917     osFcntl(fd, F_SETFD, osFcntl(fd, F_GETFD, 0) | FD_CLOEXEC);
23918 #endif
23919   }
23920   return fd;
23921 }
23922 
23923 /*
23924 ** Helper functions to obtain and relinquish the global mutex. The
23925 ** global mutex is used to protect the unixInodeInfo and
23926 ** vxworksFileId objects used by this file, all of which may be 
23927 ** shared by multiple threads.
23928 **
23929 ** Function unixMutexHeld() is used to assert() that the global mutex 
23930 ** is held when required. This function is only used as part of assert() 
23931 ** statements. e.g.
23932 **
23933 **   unixEnterMutex()
23934 **     assert( unixMutexHeld() );
23935 **   unixEnterLeave()
23936 */
23937 static void unixEnterMutex(void){
23938   sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
23939 }
23940 static void unixLeaveMutex(void){
23941   sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
23942 }
23943 #ifdef SQLITE_DEBUG
23944 static int unixMutexHeld(void) {
23945   return sqlite3_mutex_held(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
23946 }
23947 #endif
23948 
23949 
23950 #if defined(SQLITE_TEST) && defined(SQLITE_DEBUG)
23951 /*
23952 ** Helper function for printing out trace information from debugging
23953 ** binaries. This returns the string represetation of the supplied
23954 ** integer lock-type.
23955 */
23956 static const char *azFileLock(int eFileLock){
23957   switch( eFileLock ){
23958     case NO_LOCK: return "NONE";
23959     case SHARED_LOCK: return "SHARED";
23960     case RESERVED_LOCK: return "RESERVED";
23961     case PENDING_LOCK: return "PENDING";
23962     case EXCLUSIVE_LOCK: return "EXCLUSIVE";
23963   }
23964   return "ERROR";
23965 }
23966 #endif
23967 
23968 #ifdef SQLITE_LOCK_TRACE
23969 /*
23970 ** Print out information about all locking operations.
23971 **
23972 ** This routine is used for troubleshooting locks on multithreaded
23973 ** platforms.  Enable by compiling with the -DSQLITE_LOCK_TRACE
23974 ** command-line option on the compiler.  This code is normally
23975 ** turned off.
23976 */
23977 static int lockTrace(int fd, int op, struct flock *p){
23978   char *zOpName, *zType;
23979   int s;
23980   int savedErrno;
23981   if( op==F_GETLK ){
23982     zOpName = "GETLK";
23983   }else if( op==F_SETLK ){
23984     zOpName = "SETLK";
23985   }else{
23986     s = osFcntl(fd, op, p);
23987     sqlite3DebugPrintf("fcntl unknown %d %d %d\n", fd, op, s);
23988     return s;
23989   }
23990   if( p->l_type==F_RDLCK ){
23991     zType = "RDLCK";
23992   }else if( p->l_type==F_WRLCK ){
23993     zType = "WRLCK";
23994   }else if( p->l_type==F_UNLCK ){
23995     zType = "UNLCK";
23996   }else{
23997     assert( 0 );
23998   }
23999   assert( p->l_whence==SEEK_SET );
24000   s = osFcntl(fd, op, p);
24001   savedErrno = errno;
24002   sqlite3DebugPrintf("fcntl %d %d %s %s %d %d %d %d\n",
24003      threadid, fd, zOpName, zType, (int)p->l_start, (int)p->l_len,
24004      (int)p->l_pid, s);
24005   if( s==(-1) && op==F_SETLK && (p->l_type==F_RDLCK || p->l_type==F_WRLCK) ){
24006     struct flock l2;
24007     l2 = *p;
24008     osFcntl(fd, F_GETLK, &l2);
24009     if( l2.l_type==F_RDLCK ){
24010       zType = "RDLCK";
24011     }else if( l2.l_type==F_WRLCK ){
24012       zType = "WRLCK";
24013     }else if( l2.l_type==F_UNLCK ){
24014       zType = "UNLCK";
24015     }else{
24016       assert( 0 );
24017     }
24018     sqlite3DebugPrintf("fcntl-failure-reason: %s %d %d %d\n",
24019        zType, (int)l2.l_start, (int)l2.l_len, (int)l2.l_pid);
24020   }
24021   errno = savedErrno;
24022   return s;
24023 }
24024 #undef osFcntl
24025 #define osFcntl lockTrace
24026 #endif /* SQLITE_LOCK_TRACE */
24027 
24028 /*
24029 ** Retry ftruncate() calls that fail due to EINTR
24030 */
24031 static int robust_ftruncate(int h, sqlite3_int64 sz){
24032   int rc;
24033   do{ rc = osFtruncate(h,sz); }while( rc<0 && errno==EINTR );
24034   return rc;
24035 }
24036 
24037 /*
24038 ** This routine translates a standard POSIX errno code into something
24039 ** useful to the clients of the sqlite3 functions.  Specifically, it is
24040 ** intended to translate a variety of "try again" errors into SQLITE_BUSY
24041 ** and a variety of "please close the file descriptor NOW" errors into 
24042 ** SQLITE_IOERR
24043 ** 
24044 ** Errors during initialization of locks, or file system support for locks,
24045 ** should handle ENOLCK, ENOTSUP, EOPNOTSUPP separately.
24046 */
24047 static int sqliteErrorFromPosixError(int posixError, int sqliteIOErr) {
24048   switch (posixError) {
24049 #if 0
24050   /* At one point this code was not commented out. In theory, this branch
24051   ** should never be hit, as this function should only be called after
24052   ** a locking-related function (i.e. fcntl()) has returned non-zero with
24053   ** the value of errno as the first argument. Since a system call has failed,
24054   ** errno should be non-zero.
24055   **
24056   ** Despite this, if errno really is zero, we still don't want to return
24057   ** SQLITE_OK. The system call failed, and *some* SQLite error should be
24058   ** propagated back to the caller. Commenting this branch out means errno==0
24059   ** will be handled by the "default:" case below.
24060   */
24061   case 0: 
24062     return SQLITE_OK;
24063 #endif
24064 
24065   case EAGAIN:
24066   case ETIMEDOUT:
24067   case EBUSY:
24068   case EINTR:
24069   case ENOLCK:  
24070     /* random NFS retry error, unless during file system support 
24071      * introspection, in which it actually means what it says */
24072     return SQLITE_BUSY;
24073     
24074   case EACCES: 
24075     /* EACCES is like EAGAIN during locking operations, but not any other time*/
24076     if( (sqliteIOErr == SQLITE_IOERR_LOCK) || 
24077         (sqliteIOErr == SQLITE_IOERR_UNLOCK) || 
24078         (sqliteIOErr == SQLITE_IOERR_RDLOCK) ||
24079         (sqliteIOErr == SQLITE_IOERR_CHECKRESERVEDLOCK) ){
24080       return SQLITE_BUSY;
24081     }
24082     /* else fall through */
24083   case EPERM: 
24084     return SQLITE_PERM;
24085     
24086   /* EDEADLK is only possible if a call to fcntl(F_SETLKW) is made. And
24087   ** this module never makes such a call. And the code in SQLite itself 
24088   ** asserts that SQLITE_IOERR_BLOCKED is never returned. For these reasons
24089   ** this case is also commented out. If the system does set errno to EDEADLK,
24090   ** the default SQLITE_IOERR_XXX code will be returned. */
24091 #if 0
24092   case EDEADLK:
24093     return SQLITE_IOERR_BLOCKED;
24094 #endif
24095     
24096 #if EOPNOTSUPP!=ENOTSUP
24097   case EOPNOTSUPP: 
24098     /* something went terribly awry, unless during file system support 
24099      * introspection, in which it actually means what it says */
24100 #endif
24101 #ifdef ENOTSUP
24102   case ENOTSUP: 
24103     /* invalid fd, unless during file system support introspection, in which 
24104      * it actually means what it says */
24105 #endif
24106   case EIO:
24107   case EBADF:
24108   case EINVAL:
24109   case ENOTCONN:
24110   case ENODEV:
24111   case ENXIO:
24112   case ENOENT:
24113 #ifdef ESTALE                     /* ESTALE is not defined on Interix systems */
24114   case ESTALE:
24115 #endif
24116   case ENOSYS:
24117     /* these should force the client to close the file and reconnect */
24118     
24119   default: 
24120     return sqliteIOErr;
24121   }
24122 }
24123 
24124 
24125 /******************************************************************************
24126 ****************** Begin Unique File ID Utility Used By VxWorks ***************
24127 **
24128 ** On most versions of unix, we can get a unique ID for a file by concatenating
24129 ** the device number and the inode number.  But this does not work on VxWorks.
24130 ** On VxWorks, a unique file id must be based on the canonical filename.
24131 **
24132 ** A pointer to an instance of the following structure can be used as a
24133 ** unique file ID in VxWorks.  Each instance of this structure contains
24134 ** a copy of the canonical filename.  There is also a reference count.  
24135 ** The structure is reclaimed when the number of pointers to it drops to
24136 ** zero.
24137 **
24138 ** There are never very many files open at one time and lookups are not
24139 ** a performance-critical path, so it is sufficient to put these
24140 ** structures on a linked list.
24141 */
24142 struct vxworksFileId {
24143   struct vxworksFileId *pNext;  /* Next in a list of them all */
24144   int nRef;                     /* Number of references to this one */
24145   int nName;                    /* Length of the zCanonicalName[] string */
24146   char *zCanonicalName;         /* Canonical filename */
24147 };
24148 
24149 #if OS_VXWORKS
24150 /* 
24151 ** All unique filenames are held on a linked list headed by this
24152 ** variable:
24153 */
24154 static struct vxworksFileId *vxworksFileList = 0;
24155 
24156 /*
24157 ** Simplify a filename into its canonical form
24158 ** by making the following changes:
24159 **
24160 **  * removing any trailing and duplicate /
24161 **  * convert /./ into just /
24162 **  * convert /A/../ where A is any simple name into just /
24163 **
24164 ** Changes are made in-place.  Return the new name length.
24165 **
24166 ** The original filename is in z[0..n-1].  Return the number of
24167 ** characters in the simplified name.
24168 */
24169 static int vxworksSimplifyName(char *z, int n){
24170   int i, j;
24171   while( n>1 && z[n-1]=='/' ){ n--; }
24172   for(i=j=0; i<n; i++){
24173     if( z[i]=='/' ){
24174       if( z[i+1]=='/' ) continue;
24175       if( z[i+1]=='.' && i+2<n && z[i+2]=='/' ){
24176         i += 1;
24177         continue;
24178       }
24179       if( z[i+1]=='.' && i+3<n && z[i+2]=='.' && z[i+3]=='/' ){
24180         while( j>0 && z[j-1]!='/' ){ j--; }
24181         if( j>0 ){ j--; }
24182         i += 2;
24183         continue;
24184       }
24185     }
24186     z[j++] = z[i];
24187   }
24188   z[j] = 0;
24189   return j;
24190 }
24191 
24192 /*
24193 ** Find a unique file ID for the given absolute pathname.  Return
24194 ** a pointer to the vxworksFileId object.  This pointer is the unique
24195 ** file ID.
24196 **
24197 ** The nRef field of the vxworksFileId object is incremented before
24198 ** the object is returned.  A new vxworksFileId object is created
24199 ** and added to the global list if necessary.
24200 **
24201 ** If a memory allocation error occurs, return NULL.
24202 */
24203 static struct vxworksFileId *vxworksFindFileId(const char *zAbsoluteName){
24204   struct vxworksFileId *pNew;         /* search key and new file ID */
24205   struct vxworksFileId *pCandidate;   /* For looping over existing file IDs */
24206   int n;                              /* Length of zAbsoluteName string */
24207 
24208   assert( zAbsoluteName[0]=='/' );
24209   n = (int)strlen(zAbsoluteName);
24210   pNew = sqlite3_malloc( sizeof(*pNew) + (n+1) );
24211   if( pNew==0 ) return 0;
24212   pNew->zCanonicalName = (char*)&pNew[1];
24213   memcpy(pNew->zCanonicalName, zAbsoluteName, n+1);
24214   n = vxworksSimplifyName(pNew->zCanonicalName, n);
24215 
24216   /* Search for an existing entry that matching the canonical name.
24217   ** If found, increment the reference count and return a pointer to
24218   ** the existing file ID.
24219   */
24220   unixEnterMutex();
24221   for(pCandidate=vxworksFileList; pCandidate; pCandidate=pCandidate->pNext){
24222     if( pCandidate->nName==n 
24223      && memcmp(pCandidate->zCanonicalName, pNew->zCanonicalName, n)==0
24224     ){
24225        sqlite3_free(pNew);
24226        pCandidate->nRef++;
24227        unixLeaveMutex();
24228        return pCandidate;
24229     }
24230   }
24231 
24232   /* No match was found.  We will make a new file ID */
24233   pNew->nRef = 1;
24234   pNew->nName = n;
24235   pNew->pNext = vxworksFileList;
24236   vxworksFileList = pNew;
24237   unixLeaveMutex();
24238   return pNew;
24239 }
24240 
24241 /*
24242 ** Decrement the reference count on a vxworksFileId object.  Free
24243 ** the object when the reference count reaches zero.
24244 */
24245 static void vxworksReleaseFileId(struct vxworksFileId *pId){
24246   unixEnterMutex();
24247   assert( pId->nRef>0 );
24248   pId->nRef--;
24249   if( pId->nRef==0 ){
24250     struct vxworksFileId **pp;
24251     for(pp=&vxworksFileList; *pp && *pp!=pId; pp = &((*pp)->pNext)){}
24252     assert( *pp==pId );
24253     *pp = pId->pNext;
24254     sqlite3_free(pId);
24255   }
24256   unixLeaveMutex();
24257 }
24258 #endif /* OS_VXWORKS */
24259 /*************** End of Unique File ID Utility Used By VxWorks ****************
24260 ******************************************************************************/
24261 
24262 
24263 /******************************************************************************
24264 *************************** Posix Advisory Locking ****************************
24265 **
24266 ** POSIX advisory locks are broken by design.  ANSI STD 1003.1 (1996)
24267 ** section 6.5.2.2 lines 483 through 490 specify that when a process
24268 ** sets or clears a lock, that operation overrides any prior locks set
24269 ** by the same process.  It does not explicitly say so, but this implies
24270 ** that it overrides locks set by the same process using a different
24271 ** file descriptor.  Consider this test case:
24272 **
24273 **       int fd1 = open("./file1", O_RDWR|O_CREAT, 0644);
24274 **       int fd2 = open("./file2", O_RDWR|O_CREAT, 0644);
24275 **
24276 ** Suppose ./file1 and ./file2 are really the same file (because
24277 ** one is a hard or symbolic link to the other) then if you set
24278 ** an exclusive lock on fd1, then try to get an exclusive lock
24279 ** on fd2, it works.  I would have expected the second lock to
24280 ** fail since there was already a lock on the file due to fd1.
24281 ** But not so.  Since both locks came from the same process, the
24282 ** second overrides the first, even though they were on different
24283 ** file descriptors opened on different file names.
24284 **
24285 ** This means that we cannot use POSIX locks to synchronize file access
24286 ** among competing threads of the same process.  POSIX locks will work fine
24287 ** to synchronize access for threads in separate processes, but not
24288 ** threads within the same process.
24289 **
24290 ** To work around the problem, SQLite has to manage file locks internally
24291 ** on its own.  Whenever a new database is opened, we have to find the
24292 ** specific inode of the database file (the inode is determined by the
24293 ** st_dev and st_ino fields of the stat structure that fstat() fills in)
24294 ** and check for locks already existing on that inode.  When locks are
24295 ** created or removed, we have to look at our own internal record of the
24296 ** locks to see if another thread has previously set a lock on that same
24297 ** inode.
24298 **
24299 ** (Aside: The use of inode numbers as unique IDs does not work on VxWorks.
24300 ** For VxWorks, we have to use the alternative unique ID system based on
24301 ** canonical filename and implemented in the previous division.)
24302 **
24303 ** The sqlite3_file structure for POSIX is no longer just an integer file
24304 ** descriptor.  It is now a structure that holds the integer file
24305 ** descriptor and a pointer to a structure that describes the internal
24306 ** locks on the corresponding inode.  There is one locking structure
24307 ** per inode, so if the same inode is opened twice, both unixFile structures
24308 ** point to the same locking structure.  The locking structure keeps
24309 ** a reference count (so we will know when to delete it) and a "cnt"
24310 ** field that tells us its internal lock status.  cnt==0 means the
24311 ** file is unlocked.  cnt==-1 means the file has an exclusive lock.
24312 ** cnt>0 means there are cnt shared locks on the file.
24313 **
24314 ** Any attempt to lock or unlock a file first checks the locking
24315 ** structure.  The fcntl() system call is only invoked to set a 
24316 ** POSIX lock if the internal lock structure transitions between
24317 ** a locked and an unlocked state.
24318 **
24319 ** But wait:  there are yet more problems with POSIX advisory locks.
24320 **
24321 ** If you close a file descriptor that points to a file that has locks,
24322 ** all locks on that file that are owned by the current process are
24323 ** released.  To work around this problem, each unixInodeInfo object
24324 ** maintains a count of the number of pending locks on tha inode.
24325 ** When an attempt is made to close an unixFile, if there are
24326 ** other unixFile open on the same inode that are holding locks, the call
24327 ** to close() the file descriptor is deferred until all of the locks clear.
24328 ** The unixInodeInfo structure keeps a list of file descriptors that need to
24329 ** be closed and that list is walked (and cleared) when the last lock
24330 ** clears.
24331 **
24332 ** Yet another problem:  LinuxThreads do not play well with posix locks.
24333 **
24334 ** Many older versions of linux use the LinuxThreads library which is
24335 ** not posix compliant.  Under LinuxThreads, a lock created by thread
24336 ** A cannot be modified or overridden by a different thread B.
24337 ** Only thread A can modify the lock.  Locking behavior is correct
24338 ** if the appliation uses the newer Native Posix Thread Library (NPTL)
24339 ** on linux - with NPTL a lock created by thread A can override locks
24340 ** in thread B.  But there is no way to know at compile-time which
24341 ** threading library is being used.  So there is no way to know at
24342 ** compile-time whether or not thread A can override locks on thread B.
24343 ** One has to do a run-time check to discover the behavior of the
24344 ** current process.
24345 **
24346 ** SQLite used to support LinuxThreads.  But support for LinuxThreads
24347 ** was dropped beginning with version 3.7.0.  SQLite will still work with
24348 ** LinuxThreads provided that (1) there is no more than one connection 
24349 ** per database file in the same process and (2) database connections
24350 ** do not move across threads.
24351 */
24352 
24353 /*
24354 ** An instance of the following structure serves as the key used
24355 ** to locate a particular unixInodeInfo object.
24356 */
24357 struct unixFileId {
24358   dev_t dev;                  /* Device number */
24359 #if OS_VXWORKS
24360   struct vxworksFileId *pId;  /* Unique file ID for vxworks. */
24361 #else
24362   ino_t ino;                  /* Inode number */
24363 #endif
24364 };
24365 
24366 /*
24367 ** An instance of the following structure is allocated for each open
24368 ** inode.  Or, on LinuxThreads, there is one of these structures for
24369 ** each inode opened by each thread.
24370 **
24371 ** A single inode can have multiple file descriptors, so each unixFile
24372 ** structure contains a pointer to an instance of this object and this
24373 ** object keeps a count of the number of unixFile pointing to it.
24374 */
24375 struct unixInodeInfo {
24376   struct unixFileId fileId;       /* The lookup key */
24377   int nShared;                    /* Number of SHARED locks held */
24378   unsigned char eFileLock;        /* One of SHARED_LOCK, RESERVED_LOCK etc. */
24379   unsigned char bProcessLock;     /* An exclusive process lock is held */
24380   int nRef;                       /* Number of pointers to this structure */
24381   unixShmNode *pShmNode;          /* Shared memory associated with this inode */
24382   int nLock;                      /* Number of outstanding file locks */
24383   UnixUnusedFd *pUnused;          /* Unused file descriptors to close */
24384   unixInodeInfo *pNext;           /* List of all unixInodeInfo objects */
24385   unixInodeInfo *pPrev;           /*    .... doubly linked */
24386 #if SQLITE_ENABLE_LOCKING_STYLE
24387   unsigned long long sharedByte;  /* for AFP simulated shared lock */
24388 #endif
24389 #if OS_VXWORKS
24390   sem_t *pSem;                    /* Named POSIX semaphore */
24391   char aSemName[MAX_PATHNAME+2];  /* Name of that semaphore */
24392 #endif
24393 };
24394 
24395 /*
24396 ** A lists of all unixInodeInfo objects.
24397 */
24398 static unixInodeInfo *inodeList = 0;
24399 
24400 /*
24401 **
24402 ** This function - unixLogError_x(), is only ever called via the macro
24403 ** unixLogError().
24404 **
24405 ** It is invoked after an error occurs in an OS function and errno has been
24406 ** set. It logs a message using sqlite3_log() containing the current value of
24407 ** errno and, if possible, the human-readable equivalent from strerror() or
24408 ** strerror_r().
24409 **
24410 ** The first argument passed to the macro should be the error code that
24411 ** will be returned to SQLite (e.g. SQLITE_IOERR_DELETE, SQLITE_CANTOPEN). 
24412 ** The two subsequent arguments should be the name of the OS function that
24413 ** failed (e.g. "unlink", "open") and the associated file-system path,
24414 ** if any.
24415 */
24416 #define unixLogError(a,b,c)     unixLogErrorAtLine(a,b,c,__LINE__)
24417 static int unixLogErrorAtLine(
24418   int errcode,                    /* SQLite error code */
24419   const char *zFunc,              /* Name of OS function that failed */
24420   const char *zPath,              /* File path associated with error */
24421   int iLine                       /* Source line number where error occurred */
24422 ){
24423   char *zErr;                     /* Message from strerror() or equivalent */
24424   int iErrno = errno;             /* Saved syscall error number */
24425 
24426   /* If this is not a threadsafe build (SQLITE_THREADSAFE==0), then use
24427   ** the strerror() function to obtain the human-readable error message
24428   ** equivalent to errno. Otherwise, use strerror_r().
24429   */ 
24430 #if SQLITE_THREADSAFE && defined(HAVE_STRERROR_R)
24431   char aErr[80];
24432   memset(aErr, 0, sizeof(aErr));
24433   zErr = aErr;
24434 
24435   /* If STRERROR_R_CHAR_P (set by autoconf scripts) or __USE_GNU is defined,
24436   ** assume that the system provides the GNU version of strerror_r() that
24437   ** returns a pointer to a buffer containing the error message. That pointer 
24438   ** may point to aErr[], or it may point to some static storage somewhere. 
24439   ** Otherwise, assume that the system provides the POSIX version of 
24440   ** strerror_r(), which always writes an error message into aErr[].
24441   **
24442   ** If the code incorrectly assumes that it is the POSIX version that is
24443   ** available, the error message will often be an empty string. Not a
24444   ** huge problem. Incorrectly concluding that the GNU version is available 
24445   ** could lead to a segfault though.
24446   */
24447 #if defined(STRERROR_R_CHAR_P) || defined(__USE_GNU)
24448   zErr = 
24449 # endif
24450   strerror_r(iErrno, aErr, sizeof(aErr)-1);
24451 
24452 #elif SQLITE_THREADSAFE
24453   /* This is a threadsafe build, but strerror_r() is not available. */
24454   zErr = "";
24455 #else
24456   /* Non-threadsafe build, use strerror(). */
24457   zErr = strerror(iErrno);
24458 #endif
24459 
24460   if( zPath==0 ) zPath = "";
24461   sqlite3_log(errcode,
24462       "os_unix.c:%d: (%d) %s(%s) - %s",
24463       iLine, iErrno, zFunc, zPath, zErr
24464   );
24465 
24466   return errcode;
24467 }
24468 
24469 /*
24470 ** Close a file descriptor.
24471 **
24472 ** We assume that close() almost always works, since it is only in a
24473 ** very sick application or on a very sick platform that it might fail.
24474 ** If it does fail, simply leak the file descriptor, but do log the
24475 ** error.
24476 **
24477 ** Note that it is not safe to retry close() after EINTR since the
24478 ** file descriptor might have already been reused by another thread.
24479 ** So we don't even try to recover from an EINTR.  Just log the error
24480 ** and move on.
24481 */
24482 static void robust_close(unixFile *pFile, int h, int lineno){
24483   if( osClose(h) ){
24484     unixLogErrorAtLine(SQLITE_IOERR_CLOSE, "close",
24485                        pFile ? pFile->zPath : 0, lineno);
24486   }
24487 }
24488 
24489 /*
24490 ** Close all file descriptors accumuated in the unixInodeInfo->pUnused list.
24491 */ 
24492 static void closePendingFds(unixFile *pFile){
24493   unixInodeInfo *pInode = pFile->pInode;
24494   UnixUnusedFd *p;
24495   UnixUnusedFd *pNext;
24496   for(p=pInode->pUnused; p; p=pNext){
24497     pNext = p->pNext;
24498     robust_close(pFile, p->fd, __LINE__);
24499     sqlite3_free(p);
24500   }
24501   pInode->pUnused = 0;
24502 }
24503 
24504 /*
24505 ** Release a unixInodeInfo structure previously allocated by findInodeInfo().
24506 **
24507 ** The mutex entered using the unixEnterMutex() function must be held
24508 ** when this function is called.
24509 */
24510 static void releaseInodeInfo(unixFile *pFile){
24511   unixInodeInfo *pInode = pFile->pInode;
24512   assert( unixMutexHeld() );
24513   if( ALWAYS(pInode) ){
24514     pInode->nRef--;
24515     if( pInode->nRef==0 ){
24516       assert( pInode->pShmNode==0 );
24517       closePendingFds(pFile);
24518       if( pInode->pPrev ){
24519         assert( pInode->pPrev->pNext==pInode );
24520         pInode->pPrev->pNext = pInode->pNext;
24521       }else{
24522         assert( inodeList==pInode );
24523         inodeList = pInode->pNext;
24524       }
24525       if( pInode->pNext ){
24526         assert( pInode->pNext->pPrev==pInode );
24527         pInode->pNext->pPrev = pInode->pPrev;
24528       }
24529       sqlite3_free(pInode);
24530     }
24531   }
24532 }
24533 
24534 /*
24535 ** Given a file descriptor, locate the unixInodeInfo object that
24536 ** describes that file descriptor.  Create a new one if necessary.  The
24537 ** return value might be uninitialized if an error occurs.
24538 **
24539 ** The mutex entered using the unixEnterMutex() function must be held
24540 ** when this function is called.
24541 **
24542 ** Return an appropriate error code.
24543 */
24544 static int findInodeInfo(
24545   unixFile *pFile,               /* Unix file with file desc used in the key */
24546   unixInodeInfo **ppInode        /* Return the unixInodeInfo object here */
24547 ){
24548   int rc;                        /* System call return code */
24549   int fd;                        /* The file descriptor for pFile */
24550   struct unixFileId fileId;      /* Lookup key for the unixInodeInfo */
24551   struct stat statbuf;           /* Low-level file information */
24552   unixInodeInfo *pInode = 0;     /* Candidate unixInodeInfo object */
24553 
24554   assert( unixMutexHeld() );
24555 
24556   /* Get low-level information about the file that we can used to
24557   ** create a unique name for the file.
24558   */
24559   fd = pFile->h;
24560   rc = osFstat(fd, &statbuf);
24561   if( rc!=0 ){
24562     pFile->lastErrno = errno;
24563 #ifdef EOVERFLOW
24564     if( pFile->lastErrno==EOVERFLOW ) return SQLITE_NOLFS;
24565 #endif
24566     return SQLITE_IOERR;
24567   }
24568 
24569 #ifdef __APPLE__
24570   /* On OS X on an msdos filesystem, the inode number is reported
24571   ** incorrectly for zero-size files.  See ticket #3260.  To work
24572   ** around this problem (we consider it a bug in OS X, not SQLite)
24573   ** we always increase the file size to 1 by writing a single byte
24574   ** prior to accessing the inode number.  The one byte written is
24575   ** an ASCII 'S' character which also happens to be the first byte
24576   ** in the header of every SQLite database.  In this way, if there
24577   ** is a race condition such that another thread has already populated
24578   ** the first page of the database, no damage is done.
24579   */
24580   if( statbuf.st_size==0 && (pFile->fsFlags & SQLITE_FSFLAGS_IS_MSDOS)!=0 ){
24581     do{ rc = osWrite(fd, "S", 1); }while( rc<0 && errno==EINTR );
24582     if( rc!=1 ){
24583       pFile->lastErrno = errno;
24584       return SQLITE_IOERR;
24585     }
24586     rc = osFstat(fd, &statbuf);
24587     if( rc!=0 ){
24588       pFile->lastErrno = errno;
24589       return SQLITE_IOERR;
24590     }
24591   }
24592 #endif
24593 
24594   memset(&fileId, 0, sizeof(fileId));
24595   fileId.dev = statbuf.st_dev;
24596 #if OS_VXWORKS
24597   fileId.pId = pFile->pId;
24598 #else
24599   fileId.ino = statbuf.st_ino;
24600 #endif
24601   pInode = inodeList;
24602   while( pInode && memcmp(&fileId, &pInode->fileId, sizeof(fileId)) ){
24603     pInode = pInode->pNext;
24604   }
24605   if( pInode==0 ){
24606     pInode = sqlite3_malloc( sizeof(*pInode) );
24607     if( pInode==0 ){
24608       return SQLITE_NOMEM;
24609     }
24610     memset(pInode, 0, sizeof(*pInode));
24611     memcpy(&pInode->fileId, &fileId, sizeof(fileId));
24612     pInode->nRef = 1;
24613     pInode->pNext = inodeList;
24614     pInode->pPrev = 0;
24615     if( inodeList ) inodeList->pPrev = pInode;
24616     inodeList = pInode;
24617   }else{
24618     pInode->nRef++;
24619   }
24620   *ppInode = pInode;
24621   return SQLITE_OK;
24622 }
24623 
24624 
24625 /*
24626 ** Check a unixFile that is a database.  Verify the following:
24627 **
24628 ** (1) There is exactly one hard link on the file
24629 ** (2) The file is not a symbolic link
24630 ** (3) The file has not been renamed or unlinked
24631 **
24632 ** Issue sqlite3_log(SQLITE_WARNING,...) messages if anything is not right.
24633 */
24634 static void verifyDbFile(unixFile *pFile){
24635   struct stat buf;
24636   int rc;
24637   if( pFile->ctrlFlags & UNIXFILE_WARNED ){
24638     /* One or more of the following warnings have already been issued.  Do not
24639     ** repeat them so as not to clutter the error log */
24640     return;
24641   }
24642   rc = osFstat(pFile->h, &buf);
24643   if( rc!=0 ){
24644     sqlite3_log(SQLITE_WARNING, "cannot fstat db file %s", pFile->zPath);
24645     pFile->ctrlFlags |= UNIXFILE_WARNED;
24646     return;
24647   }
24648   if( buf.st_nlink==0 && (pFile->ctrlFlags & UNIXFILE_DELETE)==0 ){
24649     sqlite3_log(SQLITE_WARNING, "file unlinked while open: %s", pFile->zPath);
24650     pFile->ctrlFlags |= UNIXFILE_WARNED;
24651     return;
24652   }
24653   if( buf.st_nlink>1 ){
24654     sqlite3_log(SQLITE_WARNING, "multiple links to file: %s", pFile->zPath);
24655     pFile->ctrlFlags |= UNIXFILE_WARNED;
24656     return;
24657   }
24658   if( pFile->pInode!=0
24659    && ((rc = osStat(pFile->zPath, &buf))!=0
24660        || buf.st_ino!=pFile->pInode->fileId.ino)
24661   ){
24662     sqlite3_log(SQLITE_WARNING, "file renamed while open: %s", pFile->zPath);
24663     pFile->ctrlFlags |= UNIXFILE_WARNED;
24664     return;
24665   }
24666 }
24667 
24668 
24669 /*
24670 ** This routine checks if there is a RESERVED lock held on the specified
24671 ** file by this or any other process. If such a lock is held, set *pResOut
24672 ** to a non-zero value otherwise *pResOut is set to zero.  The return value
24673 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
24674 */
24675 static int unixCheckReservedLock(sqlite3_file *id, int *pResOut){
24676   int rc = SQLITE_OK;
24677   int reserved = 0;
24678   unixFile *pFile = (unixFile*)id;
24679 
24680   SimulateIOError( return SQLITE_IOERR_CHECKRESERVEDLOCK; );
24681 
24682   assert( pFile );
24683   unixEnterMutex(); /* Because pFile->pInode is shared across threads */
24684 
24685   /* Check if a thread in this process holds such a lock */
24686   if( pFile->pInode->eFileLock>SHARED_LOCK ){
24687     reserved = 1;
24688   }
24689 
24690   /* Otherwise see if some other process holds it.
24691   */
24692 #ifndef __DJGPP__
24693   if( !reserved && !pFile->pInode->bProcessLock ){
24694     struct flock lock;
24695     lock.l_whence = SEEK_SET;
24696     lock.l_start = RESERVED_BYTE;
24697     lock.l_len = 1;
24698     lock.l_type = F_WRLCK;
24699     if( osFcntl(pFile->h, F_GETLK, &lock) ){
24700       rc = SQLITE_IOERR_CHECKRESERVEDLOCK;
24701       pFile->lastErrno = errno;
24702     } else if( lock.l_type!=F_UNLCK ){
24703       reserved = 1;
24704     }
24705   }
24706 #endif
24707   
24708   unixLeaveMutex();
24709   OSTRACE(("TEST WR-LOCK %d %d %d (unix)\n", pFile->h, rc, reserved));
24710 
24711   *pResOut = reserved;
24712   return rc;
24713 }
24714 
24715 /*
24716 ** Attempt to set a system-lock on the file pFile.  The lock is 
24717 ** described by pLock.
24718 **
24719 ** If the pFile was opened read/write from unix-excl, then the only lock
24720 ** ever obtained is an exclusive lock, and it is obtained exactly once
24721 ** the first time any lock is attempted.  All subsequent system locking
24722 ** operations become no-ops.  Locking operations still happen internally,
24723 ** in order to coordinate access between separate database connections
24724 ** within this process, but all of that is handled in memory and the
24725 ** operating system does not participate.
24726 **
24727 ** This function is a pass-through to fcntl(F_SETLK) if pFile is using
24728 ** any VFS other than "unix-excl" or if pFile is opened on "unix-excl"
24729 ** and is read-only.
24730 **
24731 ** Zero is returned if the call completes successfully, or -1 if a call
24732 ** to fcntl() fails. In this case, errno is set appropriately (by fcntl()).
24733 */
24734 static int unixFileLock(unixFile *pFile, struct flock *pLock){
24735   int rc;
24736   unixInodeInfo *pInode = pFile->pInode;
24737   assert( unixMutexHeld() );
24738   assert( pInode!=0 );
24739   if( ((pFile->ctrlFlags & UNIXFILE_EXCL)!=0 || pInode->bProcessLock)
24740    && ((pFile->ctrlFlags & UNIXFILE_RDONLY)==0)
24741   ){
24742     if( pInode->bProcessLock==0 ){
24743       struct flock lock;
24744       assert( pInode->nLock==0 );
24745       lock.l_whence = SEEK_SET;
24746       lock.l_start = SHARED_FIRST;
24747       lock.l_len = SHARED_SIZE;
24748       lock.l_type = F_WRLCK;
24749       rc = osFcntl(pFile->h, F_SETLK, &lock);
24750       if( rc<0 ) return rc;
24751       pInode->bProcessLock = 1;
24752       pInode->nLock++;
24753     }else{
24754       rc = 0;
24755     }
24756   }else{
24757     rc = osFcntl(pFile->h, F_SETLK, pLock);
24758   }
24759   return rc;
24760 }
24761 
24762 /*
24763 ** Lock the file with the lock specified by parameter eFileLock - one
24764 ** of the following:
24765 **
24766 **     (1) SHARED_LOCK
24767 **     (2) RESERVED_LOCK
24768 **     (3) PENDING_LOCK
24769 **     (4) EXCLUSIVE_LOCK
24770 **
24771 ** Sometimes when requesting one lock state, additional lock states
24772 ** are inserted in between.  The locking might fail on one of the later
24773 ** transitions leaving the lock state different from what it started but
24774 ** still short of its goal.  The following chart shows the allowed
24775 ** transitions and the inserted intermediate states:
24776 **
24777 **    UNLOCKED -> SHARED
24778 **    SHARED -> RESERVED
24779 **    SHARED -> (PENDING) -> EXCLUSIVE
24780 **    RESERVED -> (PENDING) -> EXCLUSIVE
24781 **    PENDING -> EXCLUSIVE
24782 **
24783 ** This routine will only increase a lock.  Use the sqlite3OsUnlock()
24784 ** routine to lower a locking level.
24785 */
24786 static int unixLock(sqlite3_file *id, int eFileLock){
24787   /* The following describes the implementation of the various locks and
24788   ** lock transitions in terms of the POSIX advisory shared and exclusive
24789   ** lock primitives (called read-locks and write-locks below, to avoid
24790   ** confusion with SQLite lock names). The algorithms are complicated
24791   ** slightly in order to be compatible with windows systems simultaneously
24792   ** accessing the same database file, in case that is ever required.
24793   **
24794   ** Symbols defined in os.h indentify the 'pending byte' and the 'reserved
24795   ** byte', each single bytes at well known offsets, and the 'shared byte
24796   ** range', a range of 510 bytes at a well known offset.
24797   **
24798   ** To obtain a SHARED lock, a read-lock is obtained on the 'pending
24799   ** byte'.  If this is successful, a random byte from the 'shared byte
24800   ** range' is read-locked and the lock on the 'pending byte' released.
24801   **
24802   ** A process may only obtain a RESERVED lock after it has a SHARED lock.
24803   ** A RESERVED lock is implemented by grabbing a write-lock on the
24804   ** 'reserved byte'. 
24805   **
24806   ** A process may only obtain a PENDING lock after it has obtained a
24807   ** SHARED lock. A PENDING lock is implemented by obtaining a write-lock
24808   ** on the 'pending byte'. This ensures that no new SHARED locks can be
24809   ** obtained, but existing SHARED locks are allowed to persist. A process
24810   ** does not have to obtain a RESERVED lock on the way to a PENDING lock.
24811   ** This property is used by the algorithm for rolling back a journal file
24812   ** after a crash.
24813   **
24814   ** An EXCLUSIVE lock, obtained after a PENDING lock is held, is
24815   ** implemented by obtaining a write-lock on the entire 'shared byte
24816   ** range'. Since all other locks require a read-lock on one of the bytes
24817   ** within this range, this ensures that no other locks are held on the
24818   ** database. 
24819   **
24820   ** The reason a single byte cannot be used instead of the 'shared byte
24821   ** range' is that some versions of windows do not support read-locks. By
24822   ** locking a random byte from a range, concurrent SHARED locks may exist
24823   ** even if the locking primitive used is always a write-lock.
24824   */
24825   int rc = SQLITE_OK;
24826   unixFile *pFile = (unixFile*)id;
24827   unixInodeInfo *pInode;
24828   struct flock lock;
24829   int tErrno = 0;
24830 
24831   assert( pFile );
24832   OSTRACE(("LOCK    %d %s was %s(%s,%d) pid=%d (unix)\n", pFile->h,
24833       azFileLock(eFileLock), azFileLock(pFile->eFileLock),
24834       azFileLock(pFile->pInode->eFileLock), pFile->pInode->nShared , getpid()));
24835 
24836   /* If there is already a lock of this type or more restrictive on the
24837   ** unixFile, do nothing. Don't use the end_lock: exit path, as
24838   ** unixEnterMutex() hasn't been called yet.
24839   */
24840   if( pFile->eFileLock>=eFileLock ){
24841     OSTRACE(("LOCK    %d %s ok (already held) (unix)\n", pFile->h,
24842             azFileLock(eFileLock)));
24843     return SQLITE_OK;
24844   }
24845 
24846   /* Make sure the locking sequence is correct.
24847   **  (1) We never move from unlocked to anything higher than shared lock.
24848   **  (2) SQLite never explicitly requests a pendig lock.
24849   **  (3) A shared lock is always held when a reserve lock is requested.
24850   */
24851   assert( pFile->eFileLock!=NO_LOCK || eFileLock==SHARED_LOCK );
24852   assert( eFileLock!=PENDING_LOCK );
24853   assert( eFileLock!=RESERVED_LOCK || pFile->eFileLock==SHARED_LOCK );
24854 
24855   /* This mutex is needed because pFile->pInode is shared across threads
24856   */
24857   unixEnterMutex();
24858   pInode = pFile->pInode;
24859 
24860   /* If some thread using this PID has a lock via a different unixFile*
24861   ** handle that precludes the requested lock, return BUSY.
24862   */
24863   if( (pFile->eFileLock!=pInode->eFileLock && 
24864           (pInode->eFileLock>=PENDING_LOCK || eFileLock>SHARED_LOCK))
24865   ){
24866     rc = SQLITE_BUSY;
24867     goto end_lock;
24868   }
24869 
24870   /* If a SHARED lock is requested, and some thread using this PID already
24871   ** has a SHARED or RESERVED lock, then increment reference counts and
24872   ** return SQLITE_OK.
24873   */
24874   if( eFileLock==SHARED_LOCK && 
24875       (pInode->eFileLock==SHARED_LOCK || pInode->eFileLock==RESERVED_LOCK) ){
24876     assert( eFileLock==SHARED_LOCK );
24877     assert( pFile->eFileLock==0 );
24878     assert( pInode->nShared>0 );
24879     pFile->eFileLock = SHARED_LOCK;
24880     pInode->nShared++;
24881     pInode->nLock++;
24882     goto end_lock;
24883   }
24884 
24885 
24886   /* A PENDING lock is needed before acquiring a SHARED lock and before
24887   ** acquiring an EXCLUSIVE lock.  For the SHARED lock, the PENDING will
24888   ** be released.
24889   */
24890   lock.l_len = 1L;
24891   lock.l_whence = SEEK_SET;
24892   if( eFileLock==SHARED_LOCK 
24893       || (eFileLock==EXCLUSIVE_LOCK && pFile->eFileLock<PENDING_LOCK)
24894   ){
24895     lock.l_type = (eFileLock==SHARED_LOCK?F_RDLCK:F_WRLCK);
24896     lock.l_start = PENDING_BYTE;
24897     if( unixFileLock(pFile, &lock) ){
24898       tErrno = errno;
24899       rc = sqliteErrorFromPosixError(tErrno, SQLITE_IOERR_LOCK);
24900       if( rc!=SQLITE_BUSY ){
24901         pFile->lastErrno = tErrno;
24902       }
24903       goto end_lock;
24904     }
24905   }
24906 
24907 
24908   /* If control gets to this point, then actually go ahead and make
24909   ** operating system calls for the specified lock.
24910   */
24911   if( eFileLock==SHARED_LOCK ){
24912     assert( pInode->nShared==0 );
24913     assert( pInode->eFileLock==0 );
24914     assert( rc==SQLITE_OK );
24915 
24916     /* Now get the read-lock */
24917     lock.l_start = SHARED_FIRST;
24918     lock.l_len = SHARED_SIZE;
24919     if( unixFileLock(pFile, &lock) ){
24920       tErrno = errno;
24921       rc = sqliteErrorFromPosixError(tErrno, SQLITE_IOERR_LOCK);
24922     }
24923 
24924     /* Drop the temporary PENDING lock */
24925     lock.l_start = PENDING_BYTE;
24926     lock.l_len = 1L;
24927     lock.l_type = F_UNLCK;
24928     if( unixFileLock(pFile, &lock) && rc==SQLITE_OK ){
24929       /* This could happen with a network mount */
24930       tErrno = errno;
24931       rc = SQLITE_IOERR_UNLOCK; 
24932     }
24933 
24934     if( rc ){
24935       if( rc!=SQLITE_BUSY ){
24936         pFile->lastErrno = tErrno;
24937       }
24938       goto end_lock;
24939     }else{
24940       pFile->eFileLock = SHARED_LOCK;
24941       pInode->nLock++;
24942       pInode->nShared = 1;
24943     }
24944   }else if( eFileLock==EXCLUSIVE_LOCK && pInode->nShared>1 ){
24945     /* We are trying for an exclusive lock but another thread in this
24946     ** same process is still holding a shared lock. */
24947     rc = SQLITE_BUSY;
24948   }else{
24949     /* The request was for a RESERVED or EXCLUSIVE lock.  It is
24950     ** assumed that there is a SHARED or greater lock on the file
24951     ** already.
24952     */
24953     assert( 0!=pFile->eFileLock );
24954     lock.l_type = F_WRLCK;
24955 
24956     assert( eFileLock==RESERVED_LOCK || eFileLock==EXCLUSIVE_LOCK );
24957     if( eFileLock==RESERVED_LOCK ){
24958       lock.l_start = RESERVED_BYTE;
24959       lock.l_len = 1L;
24960     }else{
24961       lock.l_start = SHARED_FIRST;
24962       lock.l_len = SHARED_SIZE;
24963     }
24964 
24965     if( unixFileLock(pFile, &lock) ){
24966       tErrno = errno;
24967       rc = sqliteErrorFromPosixError(tErrno, SQLITE_IOERR_LOCK);
24968       if( rc!=SQLITE_BUSY ){
24969         pFile->lastErrno = tErrno;
24970       }
24971     }
24972   }
24973   
24974 
24975 #ifdef SQLITE_DEBUG
24976   /* Set up the transaction-counter change checking flags when
24977   ** transitioning from a SHARED to a RESERVED lock.  The change
24978   ** from SHARED to RESERVED marks the beginning of a normal
24979   ** write operation (not a hot journal rollback).
24980   */
24981   if( rc==SQLITE_OK
24982    && pFile->eFileLock<=SHARED_LOCK
24983    && eFileLock==RESERVED_LOCK
24984   ){
24985     pFile->transCntrChng = 0;
24986     pFile->dbUpdate = 0;
24987     pFile->inNormalWrite = 1;
24988   }
24989 #endif
24990 
24991 
24992   if( rc==SQLITE_OK ){
24993     pFile->eFileLock = eFileLock;
24994     pInode->eFileLock = eFileLock;
24995   }else if( eFileLock==EXCLUSIVE_LOCK ){
24996     pFile->eFileLock = PENDING_LOCK;
24997     pInode->eFileLock = PENDING_LOCK;
24998   }
24999 
25000 end_lock:
25001   unixLeaveMutex();
25002   OSTRACE(("LOCK    %d %s %s (unix)\n", pFile->h, azFileLock(eFileLock), 
25003       rc==SQLITE_OK ? "ok" : "failed"));
25004   return rc;
25005 }
25006 
25007 /*
25008 ** Add the file descriptor used by file handle pFile to the corresponding
25009 ** pUnused list.
25010 */
25011 static void setPendingFd(unixFile *pFile){
25012   unixInodeInfo *pInode = pFile->pInode;
25013   UnixUnusedFd *p = pFile->pUnused;
25014   p->pNext = pInode->pUnused;
25015   pInode->pUnused = p;
25016   pFile->h = -1;
25017   pFile->pUnused = 0;
25018 }
25019 
25020 /*
25021 ** Lower the locking level on file descriptor pFile to eFileLock.  eFileLock
25022 ** must be either NO_LOCK or SHARED_LOCK.
25023 **
25024 ** If the locking level of the file descriptor is already at or below
25025 ** the requested locking level, this routine is a no-op.
25026 ** 
25027 ** If handleNFSUnlock is true, then on downgrading an EXCLUSIVE_LOCK to SHARED
25028 ** the byte range is divided into 2 parts and the first part is unlocked then
25029 ** set to a read lock, then the other part is simply unlocked.  This works 
25030 ** around a bug in BSD NFS lockd (also seen on MacOSX 10.3+) that fails to 
25031 ** remove the write lock on a region when a read lock is set.
25032 */
25033 static int posixUnlock(sqlite3_file *id, int eFileLock, int handleNFSUnlock){
25034   unixFile *pFile = (unixFile*)id;
25035   unixInodeInfo *pInode;
25036   struct flock lock;
25037   int rc = SQLITE_OK;
25038 
25039   assert( pFile );
25040   OSTRACE(("UNLOCK  %d %d was %d(%d,%d) pid=%d (unix)\n", pFile->h, eFileLock,
25041       pFile->eFileLock, pFile->pInode->eFileLock, pFile->pInode->nShared,
25042       getpid()));
25043 
25044   assert( eFileLock<=SHARED_LOCK );
25045   if( pFile->eFileLock<=eFileLock ){
25046     return SQLITE_OK;
25047   }
25048   unixEnterMutex();
25049   pInode = pFile->pInode;
25050   assert( pInode->nShared!=0 );
25051   if( pFile->eFileLock>SHARED_LOCK ){
25052     assert( pInode->eFileLock==pFile->eFileLock );
25053 
25054 #ifdef SQLITE_DEBUG
25055     /* When reducing a lock such that other processes can start
25056     ** reading the database file again, make sure that the
25057     ** transaction counter was updated if any part of the database
25058     ** file changed.  If the transaction counter is not updated,
25059     ** other connections to the same file might not realize that
25060     ** the file has changed and hence might not know to flush their
25061     ** cache.  The use of a stale cache can lead to database corruption.
25062     */
25063     pFile->inNormalWrite = 0;
25064 #endif
25065 
25066     /* downgrading to a shared lock on NFS involves clearing the write lock
25067     ** before establishing the readlock - to avoid a race condition we downgrade
25068     ** the lock in 2 blocks, so that part of the range will be covered by a 
25069     ** write lock until the rest is covered by a read lock:
25070     **  1:   [WWWWW]
25071     **  2:   [....W]
25072     **  3:   [RRRRW]
25073     **  4:   [RRRR.]
25074     */
25075     if( eFileLock==SHARED_LOCK ){
25076 
25077 #if !defined(__APPLE__) || !SQLITE_ENABLE_LOCKING_STYLE
25078       (void)handleNFSUnlock;
25079       assert( handleNFSUnlock==0 );
25080 #endif
25081 #if defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE
25082       if( handleNFSUnlock ){
25083         int tErrno;               /* Error code from system call errors */
25084         off_t divSize = SHARED_SIZE - 1;
25085         
25086         lock.l_type = F_UNLCK;
25087         lock.l_whence = SEEK_SET;
25088         lock.l_start = SHARED_FIRST;
25089         lock.l_len = divSize;
25090         if( unixFileLock(pFile, &lock)==(-1) ){
25091           tErrno = errno;
25092           rc = SQLITE_IOERR_UNLOCK;
25093           if( IS_LOCK_ERROR(rc) ){
25094             pFile->lastErrno = tErrno;
25095           }
25096           goto end_unlock;
25097         }
25098         lock.l_type = F_RDLCK;
25099         lock.l_whence = SEEK_SET;
25100         lock.l_start = SHARED_FIRST;
25101         lock.l_len = divSize;
25102         if( unixFileLock(pFile, &lock)==(-1) ){
25103           tErrno = errno;
25104           rc = sqliteErrorFromPosixError(tErrno, SQLITE_IOERR_RDLOCK);
25105           if( IS_LOCK_ERROR(rc) ){
25106             pFile->lastErrno = tErrno;
25107           }
25108           goto end_unlock;
25109         }
25110         lock.l_type = F_UNLCK;
25111         lock.l_whence = SEEK_SET;
25112         lock.l_start = SHARED_FIRST+divSize;
25113         lock.l_len = SHARED_SIZE-divSize;
25114         if( unixFileLock(pFile, &lock)==(-1) ){
25115           tErrno = errno;
25116           rc = SQLITE_IOERR_UNLOCK;
25117           if( IS_LOCK_ERROR(rc) ){
25118             pFile->lastErrno = tErrno;
25119           }
25120           goto end_unlock;
25121         }
25122       }else
25123 #endif /* defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE */
25124       {
25125         lock.l_type = F_RDLCK;
25126         lock.l_whence = SEEK_SET;
25127         lock.l_start = SHARED_FIRST;
25128         lock.l_len = SHARED_SIZE;
25129         if( unixFileLock(pFile, &lock) ){
25130           /* In theory, the call to unixFileLock() cannot fail because another
25131           ** process is holding an incompatible lock. If it does, this 
25132           ** indicates that the other process is not following the locking
25133           ** protocol. If this happens, return SQLITE_IOERR_RDLOCK. Returning
25134           ** SQLITE_BUSY would confuse the upper layer (in practice it causes 
25135           ** an assert to fail). */ 
25136           rc = SQLITE_IOERR_RDLOCK;
25137           pFile->lastErrno = errno;
25138           goto end_unlock;
25139         }
25140       }
25141     }
25142     lock.l_type = F_UNLCK;
25143     lock.l_whence = SEEK_SET;
25144     lock.l_start = PENDING_BYTE;
25145     lock.l_len = 2L;  assert( PENDING_BYTE+1==RESERVED_BYTE );
25146     if( unixFileLock(pFile, &lock)==0 ){
25147       pInode->eFileLock = SHARED_LOCK;
25148     }else{
25149       rc = SQLITE_IOERR_UNLOCK;
25150       pFile->lastErrno = errno;
25151       goto end_unlock;
25152     }
25153   }
25154   if( eFileLock==NO_LOCK ){
25155     /* Decrement the shared lock counter.  Release the lock using an
25156     ** OS call only when all threads in this same process have released
25157     ** the lock.
25158     */
25159     pInode->nShared--;
25160     if( pInode->nShared==0 ){
25161       lock.l_type = F_UNLCK;
25162       lock.l_whence = SEEK_SET;
25163       lock.l_start = lock.l_len = 0L;
25164       if( unixFileLock(pFile, &lock)==0 ){
25165         pInode->eFileLock = NO_LOCK;
25166       }else{
25167         rc = SQLITE_IOERR_UNLOCK;
25168         pFile->lastErrno = errno;
25169         pInode->eFileLock = NO_LOCK;
25170         pFile->eFileLock = NO_LOCK;
25171       }
25172     }
25173 
25174     /* Decrement the count of locks against this same file.  When the
25175     ** count reaches zero, close any other file descriptors whose close
25176     ** was deferred because of outstanding locks.
25177     */
25178     pInode->nLock--;
25179     assert( pInode->nLock>=0 );
25180     if( pInode->nLock==0 ){
25181       closePendingFds(pFile);
25182     }
25183   }
25184 
25185 end_unlock:
25186   unixLeaveMutex();
25187   if( rc==SQLITE_OK ) pFile->eFileLock = eFileLock;
25188   return rc;
25189 }
25190 
25191 /*
25192 ** Lower the locking level on file descriptor pFile to eFileLock.  eFileLock
25193 ** must be either NO_LOCK or SHARED_LOCK.
25194 **
25195 ** If the locking level of the file descriptor is already at or below
25196 ** the requested locking level, this routine is a no-op.
25197 */
25198 static int unixUnlock(sqlite3_file *id, int eFileLock){
25199 #if SQLITE_MAX_MMAP_SIZE>0
25200   assert( eFileLock==SHARED_LOCK || ((unixFile *)id)->nFetchOut==0 );
25201 #endif
25202   return posixUnlock(id, eFileLock, 0);
25203 }
25204 
25205 #if SQLITE_MAX_MMAP_SIZE>0
25206 static int unixMapfile(unixFile *pFd, i64 nByte);
25207 static void unixUnmapfile(unixFile *pFd);
25208 #endif
25209 
25210 /*
25211 ** This function performs the parts of the "close file" operation 
25212 ** common to all locking schemes. It closes the directory and file
25213 ** handles, if they are valid, and sets all fields of the unixFile
25214 ** structure to 0.
25215 **
25216 ** It is *not* necessary to hold the mutex when this routine is called,
25217 ** even on VxWorks.  A mutex will be acquired on VxWorks by the
25218 ** vxworksReleaseFileId() routine.
25219 */
25220 static int closeUnixFile(sqlite3_file *id){
25221   unixFile *pFile = (unixFile*)id;
25222 #if SQLITE_MAX_MMAP_SIZE>0
25223   unixUnmapfile(pFile);
25224 #endif
25225   if( pFile->h>=0 ){
25226     robust_close(pFile, pFile->h, __LINE__);
25227     pFile->h = -1;
25228   }
25229 #if OS_VXWORKS
25230   if( pFile->pId ){
25231     if( pFile->ctrlFlags & UNIXFILE_DELETE ){
25232       osUnlink(pFile->pId->zCanonicalName);
25233     }
25234     vxworksReleaseFileId(pFile->pId);
25235     pFile->pId = 0;
25236   }
25237 #endif
25238   OSTRACE(("CLOSE   %-3d\n", pFile->h));
25239   OpenCounter(-1);
25240   sqlite3_free(pFile->pUnused);
25241   memset(pFile, 0, sizeof(unixFile));
25242   return SQLITE_OK;
25243 }
25244 
25245 /*
25246 ** Close a file.
25247 */
25248 static int unixClose(sqlite3_file *id){
25249   int rc = SQLITE_OK;
25250   unixFile *pFile = (unixFile *)id;
25251   verifyDbFile(pFile);
25252   unixUnlock(id, NO_LOCK);
25253   unixEnterMutex();
25254 
25255   /* unixFile.pInode is always valid here. Otherwise, a different close
25256   ** routine (e.g. nolockClose()) would be called instead.
25257   */
25258   assert( pFile->pInode->nLock>0 || pFile->pInode->bProcessLock==0 );
25259   if( ALWAYS(pFile->pInode) && pFile->pInode->nLock ){
25260     /* If there are outstanding locks, do not actually close the file just
25261     ** yet because that would clear those locks.  Instead, add the file
25262     ** descriptor to pInode->pUnused list.  It will be automatically closed 
25263     ** when the last lock is cleared.
25264     */
25265     setPendingFd(pFile);
25266   }
25267   releaseInodeInfo(pFile);
25268   rc = closeUnixFile(id);
25269   unixLeaveMutex();
25270   return rc;
25271 }
25272 
25273 /************** End of the posix advisory lock implementation *****************
25274 ******************************************************************************/
25275 
25276 /******************************************************************************
25277 ****************************** No-op Locking **********************************
25278 **
25279 ** Of the various locking implementations available, this is by far the
25280 ** simplest:  locking is ignored.  No attempt is made to lock the database
25281 ** file for reading or writing.
25282 **
25283 ** This locking mode is appropriate for use on read-only databases
25284 ** (ex: databases that are burned into CD-ROM, for example.)  It can
25285 ** also be used if the application employs some external mechanism to
25286 ** prevent simultaneous access of the same database by two or more
25287 ** database connections.  But there is a serious risk of database
25288 ** corruption if this locking mode is used in situations where multiple
25289 ** database connections are accessing the same database file at the same
25290 ** time and one or more of those connections are writing.
25291 */
25292 
25293 static int nolockCheckReservedLock(sqlite3_file *NotUsed, int *pResOut){
25294   UNUSED_PARAMETER(NotUsed);
25295   *pResOut = 0;
25296   return SQLITE_OK;
25297 }
25298 static int nolockLock(sqlite3_file *NotUsed, int NotUsed2){
25299   UNUSED_PARAMETER2(NotUsed, NotUsed2);
25300   return SQLITE_OK;
25301 }
25302 static int nolockUnlock(sqlite3_file *NotUsed, int NotUsed2){
25303   UNUSED_PARAMETER2(NotUsed, NotUsed2);
25304   return SQLITE_OK;
25305 }
25306 
25307 /*
25308 ** Close the file.
25309 */
25310 static int nolockClose(sqlite3_file *id) {
25311   return closeUnixFile(id);
25312 }
25313 
25314 /******************* End of the no-op lock implementation *********************
25315 ******************************************************************************/
25316 
25317 /******************************************************************************
25318 ************************* Begin dot-file Locking ******************************
25319 **
25320 ** The dotfile locking implementation uses the existence of separate lock
25321 ** files (really a directory) to control access to the database.  This works
25322 ** on just about every filesystem imaginable.  But there are serious downsides:
25323 **
25324 **    (1)  There is zero concurrency.  A single reader blocks all other
25325 **         connections from reading or writing the database.
25326 **
25327 **    (2)  An application crash or power loss can leave stale lock files
25328 **         sitting around that need to be cleared manually.
25329 **
25330 ** Nevertheless, a dotlock is an appropriate locking mode for use if no
25331 ** other locking strategy is available.
25332 **
25333 ** Dotfile locking works by creating a subdirectory in the same directory as
25334 ** the database and with the same name but with a ".lock" extension added.
25335 ** The existence of a lock directory implies an EXCLUSIVE lock.  All other
25336 ** lock types (SHARED, RESERVED, PENDING) are mapped into EXCLUSIVE.
25337 */
25338 
25339 /*
25340 ** The file suffix added to the data base filename in order to create the
25341 ** lock directory.
25342 */
25343 #define DOTLOCK_SUFFIX ".lock"
25344 
25345 /*
25346 ** This routine checks if there is a RESERVED lock held on the specified
25347 ** file by this or any other process. If such a lock is held, set *pResOut
25348 ** to a non-zero value otherwise *pResOut is set to zero.  The return value
25349 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
25350 **
25351 ** In dotfile locking, either a lock exists or it does not.  So in this
25352 ** variation of CheckReservedLock(), *pResOut is set to true if any lock
25353 ** is held on the file and false if the file is unlocked.
25354 */
25355 static int dotlockCheckReservedLock(sqlite3_file *id, int *pResOut) {
25356   int rc = SQLITE_OK;
25357   int reserved = 0;
25358   unixFile *pFile = (unixFile*)id;
25359 
25360   SimulateIOError( return SQLITE_IOERR_CHECKRESERVEDLOCK; );
25361   
25362   assert( pFile );
25363 
25364   /* Check if a thread in this process holds such a lock */
25365   if( pFile->eFileLock>SHARED_LOCK ){
25366     /* Either this connection or some other connection in the same process
25367     ** holds a lock on the file.  No need to check further. */
25368     reserved = 1;
25369   }else{
25370     /* The lock is held if and only if the lockfile exists */
25371     const char *zLockFile = (const char*)pFile->lockingContext;
25372     reserved = osAccess(zLockFile, 0)==0;
25373   }
25374   OSTRACE(("TEST WR-LOCK %d %d %d (dotlock)\n", pFile->h, rc, reserved));
25375   *pResOut = reserved;
25376   return rc;
25377 }
25378 
25379 /*
25380 ** Lock the file with the lock specified by parameter eFileLock - one
25381 ** of the following:
25382 **
25383 **     (1) SHARED_LOCK
25384 **     (2) RESERVED_LOCK
25385 **     (3) PENDING_LOCK
25386 **     (4) EXCLUSIVE_LOCK
25387 **
25388 ** Sometimes when requesting one lock state, additional lock states
25389 ** are inserted in between.  The locking might fail on one of the later
25390 ** transitions leaving the lock state different from what it started but
25391 ** still short of its goal.  The following chart shows the allowed
25392 ** transitions and the inserted intermediate states:
25393 **
25394 **    UNLOCKED -> SHARED
25395 **    SHARED -> RESERVED
25396 **    SHARED -> (PENDING) -> EXCLUSIVE
25397 **    RESERVED -> (PENDING) -> EXCLUSIVE
25398 **    PENDING -> EXCLUSIVE
25399 **
25400 ** This routine will only increase a lock.  Use the sqlite3OsUnlock()
25401 ** routine to lower a locking level.
25402 **
25403 ** With dotfile locking, we really only support state (4): EXCLUSIVE.
25404 ** But we track the other locking levels internally.
25405 */
25406 static int dotlockLock(sqlite3_file *id, int eFileLock) {
25407   unixFile *pFile = (unixFile*)id;
25408   char *zLockFile = (char *)pFile->lockingContext;
25409   int rc = SQLITE_OK;
25410 
25411 
25412   /* If we have any lock, then the lock file already exists.  All we have
25413   ** to do is adjust our internal record of the lock level.
25414   */
25415   if( pFile->eFileLock > NO_LOCK ){
25416     pFile->eFileLock = eFileLock;
25417     /* Always update the timestamp on the old file */
25418 #ifdef HAVE_UTIME
25419     utime(zLockFile, NULL);
25420 #else
25421     utimes(zLockFile, NULL);
25422 #endif
25423     return SQLITE_OK;
25424   }
25425   
25426   /* grab an exclusive lock */
25427   rc = osMkdir(zLockFile, 0777);
25428   if( rc<0 ){
25429     /* failed to open/create the lock directory */
25430     int tErrno = errno;
25431     if( EEXIST == tErrno ){
25432       rc = SQLITE_BUSY;
25433     } else {
25434       rc = sqliteErrorFromPosixError(tErrno, SQLITE_IOERR_LOCK);
25435       if( IS_LOCK_ERROR(rc) ){
25436         pFile->lastErrno = tErrno;
25437       }
25438     }
25439     return rc;
25440   } 
25441   
25442   /* got it, set the type and return ok */
25443   pFile->eFileLock = eFileLock;
25444   return rc;
25445 }
25446 
25447 /*
25448 ** Lower the locking level on file descriptor pFile to eFileLock.  eFileLock
25449 ** must be either NO_LOCK or SHARED_LOCK.
25450 **
25451 ** If the locking level of the file descriptor is already at or below
25452 ** the requested locking level, this routine is a no-op.
25453 **
25454 ** When the locking level reaches NO_LOCK, delete the lock file.
25455 */
25456 static int dotlockUnlock(sqlite3_file *id, int eFileLock) {
25457   unixFile *pFile = (unixFile*)id;
25458   char *zLockFile = (char *)pFile->lockingContext;
25459   int rc;
25460 
25461   assert( pFile );
25462   OSTRACE(("UNLOCK  %d %d was %d pid=%d (dotlock)\n", pFile->h, eFileLock,
25463            pFile->eFileLock, getpid()));
25464   assert( eFileLock<=SHARED_LOCK );
25465   
25466   /* no-op if possible */
25467   if( pFile->eFileLock==eFileLock ){
25468     return SQLITE_OK;
25469   }
25470 
25471   /* To downgrade to shared, simply update our internal notion of the
25472   ** lock state.  No need to mess with the file on disk.
25473   */
25474   if( eFileLock==SHARED_LOCK ){
25475     pFile->eFileLock = SHARED_LOCK;
25476     return SQLITE_OK;
25477   }
25478   
25479   /* To fully unlock the database, delete the lock file */
25480   assert( eFileLock==NO_LOCK );
25481   rc = osRmdir(zLockFile);
25482   if( rc<0 && errno==ENOTDIR ) rc = osUnlink(zLockFile);
25483   if( rc<0 ){
25484     int tErrno = errno;
25485     rc = 0;
25486     if( ENOENT != tErrno ){
25487       rc = SQLITE_IOERR_UNLOCK;
25488     }
25489     if( IS_LOCK_ERROR(rc) ){
25490       pFile->lastErrno = tErrno;
25491     }
25492     return rc; 
25493   }
25494   pFile->eFileLock = NO_LOCK;
25495   return SQLITE_OK;
25496 }
25497 
25498 /*
25499 ** Close a file.  Make sure the lock has been released before closing.
25500 */
25501 static int dotlockClose(sqlite3_file *id) {
25502   int rc = SQLITE_OK;
25503   if( id ){
25504     unixFile *pFile = (unixFile*)id;
25505     dotlockUnlock(id, NO_LOCK);
25506     sqlite3_free(pFile->lockingContext);
25507     rc = closeUnixFile(id);
25508   }
25509   return rc;
25510 }
25511 /****************** End of the dot-file lock implementation *******************
25512 ******************************************************************************/
25513 
25514 /******************************************************************************
25515 ************************** Begin flock Locking ********************************
25516 **
25517 ** Use the flock() system call to do file locking.
25518 **
25519 ** flock() locking is like dot-file locking in that the various
25520 ** fine-grain locking levels supported by SQLite are collapsed into
25521 ** a single exclusive lock.  In other words, SHARED, RESERVED, and
25522 ** PENDING locks are the same thing as an EXCLUSIVE lock.  SQLite
25523 ** still works when you do this, but concurrency is reduced since
25524 ** only a single process can be reading the database at a time.
25525 **
25526 ** Omit this section if SQLITE_ENABLE_LOCKING_STYLE is turned off or if
25527 ** compiling for VXWORKS.
25528 */
25529 #if SQLITE_ENABLE_LOCKING_STYLE && !OS_VXWORKS
25530 
25531 /*
25532 ** Retry flock() calls that fail with EINTR
25533 */
25534 #ifdef EINTR
25535 static int robust_flock(int fd, int op){
25536   int rc;
25537   do{ rc = flock(fd,op); }while( rc<0 && errno==EINTR );
25538   return rc;
25539 }
25540 #else
25541 # define robust_flock(a,b) flock(a,b)
25542 #endif
25543      
25544 
25545 /*
25546 ** This routine checks if there is a RESERVED lock held on the specified
25547 ** file by this or any other process. If such a lock is held, set *pResOut
25548 ** to a non-zero value otherwise *pResOut is set to zero.  The return value
25549 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
25550 */
25551 static int flockCheckReservedLock(sqlite3_file *id, int *pResOut){
25552   int rc = SQLITE_OK;
25553   int reserved = 0;
25554   unixFile *pFile = (unixFile*)id;
25555   
25556   SimulateIOError( return SQLITE_IOERR_CHECKRESERVEDLOCK; );
25557   
25558   assert( pFile );
25559   
25560   /* Check if a thread in this process holds such a lock */
25561   if( pFile->eFileLock>SHARED_LOCK ){
25562     reserved = 1;
25563   }
25564   
25565   /* Otherwise see if some other process holds it. */
25566   if( !reserved ){
25567     /* attempt to get the lock */
25568     int lrc = robust_flock(pFile->h, LOCK_EX | LOCK_NB);
25569     if( !lrc ){
25570       /* got the lock, unlock it */
25571       lrc = robust_flock(pFile->h, LOCK_UN);
25572       if ( lrc ) {
25573         int tErrno = errno;
25574         /* unlock failed with an error */
25575         lrc = SQLITE_IOERR_UNLOCK; 
25576         if( IS_LOCK_ERROR(lrc) ){
25577           pFile->lastErrno = tErrno;
25578           rc = lrc;
25579         }
25580       }
25581     } else {
25582       int tErrno = errno;
25583       reserved = 1;
25584       /* someone else might have it reserved */
25585       lrc = sqliteErrorFromPosixError(tErrno, SQLITE_IOERR_LOCK); 
25586       if( IS_LOCK_ERROR(lrc) ){
25587         pFile->lastErrno = tErrno;
25588         rc = lrc;
25589       }
25590     }
25591   }
25592   OSTRACE(("TEST WR-LOCK %d %d %d (flock)\n", pFile->h, rc, reserved));
25593 
25594 #ifdef SQLITE_IGNORE_FLOCK_LOCK_ERRORS
25595   if( (rc & SQLITE_IOERR) == SQLITE_IOERR ){
25596     rc = SQLITE_OK;
25597     reserved=1;
25598   }
25599 #endif /* SQLITE_IGNORE_FLOCK_LOCK_ERRORS */
25600   *pResOut = reserved;
25601   return rc;
25602 }
25603 
25604 /*
25605 ** Lock the file with the lock specified by parameter eFileLock - one
25606 ** of the following:
25607 **
25608 **     (1) SHARED_LOCK
25609 **     (2) RESERVED_LOCK
25610 **     (3) PENDING_LOCK
25611 **     (4) EXCLUSIVE_LOCK
25612 **
25613 ** Sometimes when requesting one lock state, additional lock states
25614 ** are inserted in between.  The locking might fail on one of the later
25615 ** transitions leaving the lock state different from what it started but
25616 ** still short of its goal.  The following chart shows the allowed
25617 ** transitions and the inserted intermediate states:
25618 **
25619 **    UNLOCKED -> SHARED
25620 **    SHARED -> RESERVED
25621 **    SHARED -> (PENDING) -> EXCLUSIVE
25622 **    RESERVED -> (PENDING) -> EXCLUSIVE
25623 **    PENDING -> EXCLUSIVE
25624 **
25625 ** flock() only really support EXCLUSIVE locks.  We track intermediate
25626 ** lock states in the sqlite3_file structure, but all locks SHARED or
25627 ** above are really EXCLUSIVE locks and exclude all other processes from
25628 ** access the file.
25629 **
25630 ** This routine will only increase a lock.  Use the sqlite3OsUnlock()
25631 ** routine to lower a locking level.
25632 */
25633 static int flockLock(sqlite3_file *id, int eFileLock) {
25634   int rc = SQLITE_OK;
25635   unixFile *pFile = (unixFile*)id;
25636 
25637   assert( pFile );
25638 
25639   /* if we already have a lock, it is exclusive.  
25640   ** Just adjust level and punt on outta here. */
25641   if (pFile->eFileLock > NO_LOCK) {
25642     pFile->eFileLock = eFileLock;
25643     return SQLITE_OK;
25644   }
25645   
25646   /* grab an exclusive lock */
25647   
25648   if (robust_flock(pFile->h, LOCK_EX | LOCK_NB)) {
25649     int tErrno = errno;
25650     /* didn't get, must be busy */
25651     rc = sqliteErrorFromPosixError(tErrno, SQLITE_IOERR_LOCK);
25652     if( IS_LOCK_ERROR(rc) ){
25653       pFile->lastErrno = tErrno;
25654     }
25655   } else {
25656     /* got it, set the type and return ok */
25657     pFile->eFileLock = eFileLock;
25658   }
25659   OSTRACE(("LOCK    %d %s %s (flock)\n", pFile->h, azFileLock(eFileLock), 
25660            rc==SQLITE_OK ? "ok" : "failed"));
25661 #ifdef SQLITE_IGNORE_FLOCK_LOCK_ERRORS
25662   if( (rc & SQLITE_IOERR) == SQLITE_IOERR ){
25663     rc = SQLITE_BUSY;
25664   }
25665 #endif /* SQLITE_IGNORE_FLOCK_LOCK_ERRORS */
25666   return rc;
25667 }
25668 
25669 
25670 /*
25671 ** Lower the locking level on file descriptor pFile to eFileLock.  eFileLock
25672 ** must be either NO_LOCK or SHARED_LOCK.
25673 **
25674 ** If the locking level of the file descriptor is already at or below
25675 ** the requested locking level, this routine is a no-op.
25676 */
25677 static int flockUnlock(sqlite3_file *id, int eFileLock) {
25678   unixFile *pFile = (unixFile*)id;
25679   
25680   assert( pFile );
25681   OSTRACE(("UNLOCK  %d %d was %d pid=%d (flock)\n", pFile->h, eFileLock,
25682            pFile->eFileLock, getpid()));
25683   assert( eFileLock<=SHARED_LOCK );
25684   
25685   /* no-op if possible */
25686   if( pFile->eFileLock==eFileLock ){
25687     return SQLITE_OK;
25688   }
25689   
25690   /* shared can just be set because we always have an exclusive */
25691   if (eFileLock==SHARED_LOCK) {
25692     pFile->eFileLock = eFileLock;
25693     return SQLITE_OK;
25694   }
25695   
25696   /* no, really, unlock. */
25697   if( robust_flock(pFile->h, LOCK_UN) ){
25698 #ifdef SQLITE_IGNORE_FLOCK_LOCK_ERRORS
25699     return SQLITE_OK;
25700 #endif /* SQLITE_IGNORE_FLOCK_LOCK_ERRORS */
25701     return SQLITE_IOERR_UNLOCK;
25702   }else{
25703     pFile->eFileLock = NO_LOCK;
25704     return SQLITE_OK;
25705   }
25706 }
25707 
25708 /*
25709 ** Close a file.
25710 */
25711 static int flockClose(sqlite3_file *id) {
25712   int rc = SQLITE_OK;
25713   if( id ){
25714     flockUnlock(id, NO_LOCK);
25715     rc = closeUnixFile(id);
25716   }
25717   return rc;
25718 }
25719 
25720 #endif /* SQLITE_ENABLE_LOCKING_STYLE && !OS_VXWORK */
25721 
25722 /******************* End of the flock lock implementation *********************
25723 ******************************************************************************/
25724 
25725 /******************************************************************************
25726 ************************ Begin Named Semaphore Locking ************************
25727 **
25728 ** Named semaphore locking is only supported on VxWorks.
25729 **
25730 ** Semaphore locking is like dot-lock and flock in that it really only
25731 ** supports EXCLUSIVE locking.  Only a single process can read or write
25732 ** the database file at a time.  This reduces potential concurrency, but
25733 ** makes the lock implementation much easier.
25734 */
25735 #if OS_VXWORKS
25736 
25737 /*
25738 ** This routine checks if there is a RESERVED lock held on the specified
25739 ** file by this or any other process. If such a lock is held, set *pResOut
25740 ** to a non-zero value otherwise *pResOut is set to zero.  The return value
25741 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
25742 */
25743 static int semCheckReservedLock(sqlite3_file *id, int *pResOut) {
25744   int rc = SQLITE_OK;
25745   int reserved = 0;
25746   unixFile *pFile = (unixFile*)id;
25747 
25748   SimulateIOError( return SQLITE_IOERR_CHECKRESERVEDLOCK; );
25749   
25750   assert( pFile );
25751 
25752   /* Check if a thread in this process holds such a lock */
25753   if( pFile->eFileLock>SHARED_LOCK ){
25754     reserved = 1;
25755   }
25756   
25757   /* Otherwise see if some other process holds it. */
25758   if( !reserved ){
25759     sem_t *pSem = pFile->pInode->pSem;
25760     struct stat statBuf;
25761 
25762     if( sem_trywait(pSem)==-1 ){
25763       int tErrno = errno;
25764       if( EAGAIN != tErrno ){
25765         rc = sqliteErrorFromPosixError(tErrno, SQLITE_IOERR_CHECKRESERVEDLOCK);
25766         pFile->lastErrno = tErrno;
25767       } else {
25768         /* someone else has the lock when we are in NO_LOCK */
25769         reserved = (pFile->eFileLock < SHARED_LOCK);
25770       }
25771     }else{
25772       /* we could have it if we want it */
25773       sem_post(pSem);
25774     }
25775   }
25776   OSTRACE(("TEST WR-LOCK %d %d %d (sem)\n", pFile->h, rc, reserved));
25777 
25778   *pResOut = reserved;
25779   return rc;
25780 }
25781 
25782 /*
25783 ** Lock the file with the lock specified by parameter eFileLock - one
25784 ** of the following:
25785 **
25786 **     (1) SHARED_LOCK
25787 **     (2) RESERVED_LOCK
25788 **     (3) PENDING_LOCK
25789 **     (4) EXCLUSIVE_LOCK
25790 **
25791 ** Sometimes when requesting one lock state, additional lock states
25792 ** are inserted in between.  The locking might fail on one of the later
25793 ** transitions leaving the lock state different from what it started but
25794 ** still short of its goal.  The following chart shows the allowed
25795 ** transitions and the inserted intermediate states:
25796 **
25797 **    UNLOCKED -> SHARED
25798 **    SHARED -> RESERVED
25799 **    SHARED -> (PENDING) -> EXCLUSIVE
25800 **    RESERVED -> (PENDING) -> EXCLUSIVE
25801 **    PENDING -> EXCLUSIVE
25802 **
25803 ** Semaphore locks only really support EXCLUSIVE locks.  We track intermediate
25804 ** lock states in the sqlite3_file structure, but all locks SHARED or
25805 ** above are really EXCLUSIVE locks and exclude all other processes from
25806 ** access the file.
25807 **
25808 ** This routine will only increase a lock.  Use the sqlite3OsUnlock()
25809 ** routine to lower a locking level.
25810 */
25811 static int semLock(sqlite3_file *id, int eFileLock) {
25812   unixFile *pFile = (unixFile*)id;
25813   int fd;
25814   sem_t *pSem = pFile->pInode->pSem;
25815   int rc = SQLITE_OK;
25816 
25817   /* if we already have a lock, it is exclusive.  
25818   ** Just adjust level and punt on outta here. */
25819   if (pFile->eFileLock > NO_LOCK) {
25820     pFile->eFileLock = eFileLock;
25821     rc = SQLITE_OK;
25822     goto sem_end_lock;
25823   }
25824   
25825   /* lock semaphore now but bail out when already locked. */
25826   if( sem_trywait(pSem)==-1 ){
25827     rc = SQLITE_BUSY;
25828     goto sem_end_lock;
25829   }
25830 
25831   /* got it, set the type and return ok */
25832   pFile->eFileLock = eFileLock;
25833 
25834  sem_end_lock:
25835   return rc;
25836 }
25837 
25838 /*
25839 ** Lower the locking level on file descriptor pFile to eFileLock.  eFileLock
25840 ** must be either NO_LOCK or SHARED_LOCK.
25841 **
25842 ** If the locking level of the file descriptor is already at or below
25843 ** the requested locking level, this routine is a no-op.
25844 */
25845 static int semUnlock(sqlite3_file *id, int eFileLock) {
25846   unixFile *pFile = (unixFile*)id;
25847   sem_t *pSem = pFile->pInode->pSem;
25848 
25849   assert( pFile );
25850   assert( pSem );
25851   OSTRACE(("UNLOCK  %d %d was %d pid=%d (sem)\n", pFile->h, eFileLock,
25852            pFile->eFileLock, getpid()));
25853   assert( eFileLock<=SHARED_LOCK );
25854   
25855   /* no-op if possible */
25856   if( pFile->eFileLock==eFileLock ){
25857     return SQLITE_OK;
25858   }
25859   
25860   /* shared can just be set because we always have an exclusive */
25861   if (eFileLock==SHARED_LOCK) {
25862     pFile->eFileLock = eFileLock;
25863     return SQLITE_OK;
25864   }
25865   
25866   /* no, really unlock. */
25867   if ( sem_post(pSem)==-1 ) {
25868     int rc, tErrno = errno;
25869     rc = sqliteErrorFromPosixError(tErrno, SQLITE_IOERR_UNLOCK);
25870     if( IS_LOCK_ERROR(rc) ){
25871       pFile->lastErrno = tErrno;
25872     }
25873     return rc; 
25874   }
25875   pFile->eFileLock = NO_LOCK;
25876   return SQLITE_OK;
25877 }
25878 
25879 /*
25880  ** Close a file.
25881  */
25882 static int semClose(sqlite3_file *id) {
25883   if( id ){
25884     unixFile *pFile = (unixFile*)id;
25885     semUnlock(id, NO_LOCK);
25886     assert( pFile );
25887     unixEnterMutex();
25888     releaseInodeInfo(pFile);
25889     unixLeaveMutex();
25890     closeUnixFile(id);
25891   }
25892   return SQLITE_OK;
25893 }
25894 
25895 #endif /* OS_VXWORKS */
25896 /*
25897 ** Named semaphore locking is only available on VxWorks.
25898 **
25899 *************** End of the named semaphore lock implementation ****************
25900 ******************************************************************************/
25901 
25902 
25903 /******************************************************************************
25904 *************************** Begin AFP Locking *********************************
25905 **
25906 ** AFP is the Apple Filing Protocol.  AFP is a network filesystem found
25907 ** on Apple Macintosh computers - both OS9 and OSX.
25908 **
25909 ** Third-party implementations of AFP are available.  But this code here
25910 ** only works on OSX.
25911 */
25912 
25913 #if defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE
25914 /*
25915 ** The afpLockingContext structure contains all afp lock specific state
25916 */
25917 typedef struct afpLockingContext afpLockingContext;
25918 struct afpLockingContext {
25919   int reserved;
25920   const char *dbPath;             /* Name of the open file */
25921 };
25922 
25923 struct ByteRangeLockPB2
25924 {
25925   unsigned long long offset;        /* offset to first byte to lock */
25926   unsigned long long length;        /* nbr of bytes to lock */
25927   unsigned long long retRangeStart; /* nbr of 1st byte locked if successful */
25928   unsigned char unLockFlag;         /* 1 = unlock, 0 = lock */
25929   unsigned char startEndFlag;       /* 1=rel to end of fork, 0=rel to start */
25930   int fd;                           /* file desc to assoc this lock with */
25931 };
25932 
25933 #define afpfsByteRangeLock2FSCTL        _IOWR('z', 23, struct ByteRangeLockPB2)
25934 
25935 /*
25936 ** This is a utility for setting or clearing a bit-range lock on an
25937 ** AFP filesystem.
25938 ** 
25939 ** Return SQLITE_OK on success, SQLITE_BUSY on failure.
25940 */
25941 static int afpSetLock(
25942   const char *path,              /* Name of the file to be locked or unlocked */
25943   unixFile *pFile,               /* Open file descriptor on path */
25944   unsigned long long offset,     /* First byte to be locked */
25945   unsigned long long length,     /* Number of bytes to lock */
25946   int setLockFlag                /* True to set lock.  False to clear lock */
25947 ){
25948   struct ByteRangeLockPB2 pb;
25949   int err;
25950   
25951   pb.unLockFlag = setLockFlag ? 0 : 1;
25952   pb.startEndFlag = 0;
25953   pb.offset = offset;
25954   pb.length = length; 
25955   pb.fd = pFile->h;
25956   
25957   OSTRACE(("AFPSETLOCK [%s] for %d%s in range %llx:%llx\n", 
25958     (setLockFlag?"ON":"OFF"), pFile->h, (pb.fd==-1?"[testval-1]":""),
25959     offset, length));
25960   err = fsctl(path, afpfsByteRangeLock2FSCTL, &pb, 0);
25961   if ( err==-1 ) {
25962     int rc;
25963     int tErrno = errno;
25964     OSTRACE(("AFPSETLOCK failed to fsctl() '%s' %d %s\n",
25965              path, tErrno, strerror(tErrno)));
25966 #ifdef SQLITE_IGNORE_AFP_LOCK_ERRORS
25967     rc = SQLITE_BUSY;
25968 #else
25969     rc = sqliteErrorFromPosixError(tErrno,
25970                     setLockFlag ? SQLITE_IOERR_LOCK : SQLITE_IOERR_UNLOCK);
25971 #endif /* SQLITE_IGNORE_AFP_LOCK_ERRORS */
25972     if( IS_LOCK_ERROR(rc) ){
25973       pFile->lastErrno = tErrno;
25974     }
25975     return rc;
25976   } else {
25977     return SQLITE_OK;
25978   }
25979 }
25980 
25981 /*
25982 ** This routine checks if there is a RESERVED lock held on the specified
25983 ** file by this or any other process. If such a lock is held, set *pResOut
25984 ** to a non-zero value otherwise *pResOut is set to zero.  The return value
25985 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
25986 */
25987 static int afpCheckReservedLock(sqlite3_file *id, int *pResOut){
25988   int rc = SQLITE_OK;
25989   int reserved = 0;
25990   unixFile *pFile = (unixFile*)id;
25991   afpLockingContext *context;
25992   
25993   SimulateIOError( return SQLITE_IOERR_CHECKRESERVEDLOCK; );
25994   
25995   assert( pFile );
25996   context = (afpLockingContext *) pFile->lockingContext;
25997   if( context->reserved ){
25998     *pResOut = 1;
25999     return SQLITE_OK;
26000   }
26001   unixEnterMutex(); /* Because pFile->pInode is shared across threads */
26002   
26003   /* Check if a thread in this process holds such a lock */
26004   if( pFile->pInode->eFileLock>SHARED_LOCK ){
26005     reserved = 1;
26006   }
26007   
26008   /* Otherwise see if some other process holds it.
26009    */
26010   if( !reserved ){
26011     /* lock the RESERVED byte */
26012     int lrc = afpSetLock(context->dbPath, pFile, RESERVED_BYTE, 1,1);  
26013     if( SQLITE_OK==lrc ){
26014       /* if we succeeded in taking the reserved lock, unlock it to restore
26015       ** the original state */
26016       lrc = afpSetLock(context->dbPath, pFile, RESERVED_BYTE, 1, 0);
26017     } else {
26018       /* if we failed to get the lock then someone else must have it */
26019       reserved = 1;
26020     }
26021     if( IS_LOCK_ERROR(lrc) ){
26022       rc=lrc;
26023     }
26024   }
26025   
26026   unixLeaveMutex();
26027   OSTRACE(("TEST WR-LOCK %d %d %d (afp)\n", pFile->h, rc, reserved));
26028   
26029   *pResOut = reserved;
26030   return rc;
26031 }
26032 
26033 /*
26034 ** Lock the file with the lock specified by parameter eFileLock - one
26035 ** of the following:
26036 **
26037 **     (1) SHARED_LOCK
26038 **     (2) RESERVED_LOCK
26039 **     (3) PENDING_LOCK
26040 **     (4) EXCLUSIVE_LOCK
26041 **
26042 ** Sometimes when requesting one lock state, additional lock states
26043 ** are inserted in between.  The locking might fail on one of the later
26044 ** transitions leaving the lock state different from what it started but
26045 ** still short of its goal.  The following chart shows the allowed
26046 ** transitions and the inserted intermediate states:
26047 **
26048 **    UNLOCKED -> SHARED
26049 **    SHARED -> RESERVED
26050 **    SHARED -> (PENDING) -> EXCLUSIVE
26051 **    RESERVED -> (PENDING) -> EXCLUSIVE
26052 **    PENDING -> EXCLUSIVE
26053 **
26054 ** This routine will only increase a lock.  Use the sqlite3OsUnlock()
26055 ** routine to lower a locking level.
26056 */
26057 static int afpLock(sqlite3_file *id, int eFileLock){
26058   int rc = SQLITE_OK;
26059   unixFile *pFile = (unixFile*)id;
26060   unixInodeInfo *pInode = pFile->pInode;
26061   afpLockingContext *context = (afpLockingContext *) pFile->lockingContext;
26062   
26063   assert( pFile );
26064   OSTRACE(("LOCK    %d %s was %s(%s,%d) pid=%d (afp)\n", pFile->h,
26065            azFileLock(eFileLock), azFileLock(pFile->eFileLock),
26066            azFileLock(pInode->eFileLock), pInode->nShared , getpid()));
26067 
26068   /* If there is already a lock of this type or more restrictive on the
26069   ** unixFile, do nothing. Don't use the afp_end_lock: exit path, as
26070   ** unixEnterMutex() hasn't been called yet.
26071   */
26072   if( pFile->eFileLock>=eFileLock ){
26073     OSTRACE(("LOCK    %d %s ok (already held) (afp)\n", pFile->h,
26074            azFileLock(eFileLock)));
26075     return SQLITE_OK;
26076   }
26077 
26078   /* Make sure the locking sequence is correct
26079   **  (1) We never move from unlocked to anything higher than shared lock.
26080   **  (2) SQLite never explicitly requests a pendig lock.
26081   **  (3) A shared lock is always held when a reserve lock is requested.
26082   */
26083   assert( pFile->eFileLock!=NO_LOCK || eFileLock==SHARED_LOCK );
26084   assert( eFileLock!=PENDING_LOCK );
26085   assert( eFileLock!=RESERVED_LOCK || pFile->eFileLock==SHARED_LOCK );
26086   
26087   /* This mutex is needed because pFile->pInode is shared across threads
26088   */
26089   unixEnterMutex();
26090   pInode = pFile->pInode;
26091 
26092   /* If some thread using this PID has a lock via a different unixFile*
26093   ** handle that precludes the requested lock, return BUSY.
26094   */
26095   if( (pFile->eFileLock!=pInode->eFileLock && 
26096        (pInode->eFileLock>=PENDING_LOCK || eFileLock>SHARED_LOCK))
26097      ){
26098     rc = SQLITE_BUSY;
26099     goto afp_end_lock;
26100   }
26101   
26102   /* If a SHARED lock is requested, and some thread using this PID already
26103   ** has a SHARED or RESERVED lock, then increment reference counts and
26104   ** return SQLITE_OK.
26105   */
26106   if( eFileLock==SHARED_LOCK && 
26107      (pInode->eFileLock==SHARED_LOCK || pInode->eFileLock==RESERVED_LOCK) ){
26108     assert( eFileLock==SHARED_LOCK );
26109     assert( pFile->eFileLock==0 );
26110     assert( pInode->nShared>0 );
26111     pFile->eFileLock = SHARED_LOCK;
26112     pInode->nShared++;
26113     pInode->nLock++;
26114     goto afp_end_lock;
26115   }
26116     
26117   /* A PENDING lock is needed before acquiring a SHARED lock and before
26118   ** acquiring an EXCLUSIVE lock.  For the SHARED lock, the PENDING will
26119   ** be released.
26120   */
26121   if( eFileLock==SHARED_LOCK 
26122       || (eFileLock==EXCLUSIVE_LOCK && pFile->eFileLock<PENDING_LOCK)
26123   ){
26124     int failed;
26125     failed = afpSetLock(context->dbPath, pFile, PENDING_BYTE, 1, 1);
26126     if (failed) {
26127       rc = failed;
26128       goto afp_end_lock;
26129     }
26130   }
26131   
26132   /* If control gets to this point, then actually go ahead and make
26133   ** operating system calls for the specified lock.
26134   */
26135   if( eFileLock==SHARED_LOCK ){
26136     int lrc1, lrc2, lrc1Errno = 0;
26137     long lk, mask;
26138     
26139     assert( pInode->nShared==0 );
26140     assert( pInode->eFileLock==0 );
26141         
26142     mask = (sizeof(long)==8) ? LARGEST_INT64 : 0x7fffffff;
26143     /* Now get the read-lock SHARED_LOCK */
26144     /* note that the quality of the randomness doesn't matter that much */
26145     lk = random(); 
26146     pInode->sharedByte = (lk & mask)%(SHARED_SIZE - 1);
26147     lrc1 = afpSetLock(context->dbPath, pFile, 
26148           SHARED_FIRST+pInode->sharedByte, 1, 1);
26149     if( IS_LOCK_ERROR(lrc1) ){
26150       lrc1Errno = pFile->lastErrno;
26151     }
26152     /* Drop the temporary PENDING lock */
26153     lrc2 = afpSetLock(context->dbPath, pFile, PENDING_BYTE, 1, 0);
26154     
26155     if( IS_LOCK_ERROR(lrc1) ) {
26156       pFile->lastErrno = lrc1Errno;
26157       rc = lrc1;
26158       goto afp_end_lock;
26159     } else if( IS_LOCK_ERROR(lrc2) ){
26160       rc = lrc2;
26161       goto afp_end_lock;
26162     } else if( lrc1 != SQLITE_OK ) {
26163       rc = lrc1;
26164     } else {
26165       pFile->eFileLock = SHARED_LOCK;
26166       pInode->nLock++;
26167       pInode->nShared = 1;
26168     }
26169   }else if( eFileLock==EXCLUSIVE_LOCK && pInode->nShared>1 ){
26170     /* We are trying for an exclusive lock but another thread in this
26171      ** same process is still holding a shared lock. */
26172     rc = SQLITE_BUSY;
26173   }else{
26174     /* The request was for a RESERVED or EXCLUSIVE lock.  It is
26175     ** assumed that there is a SHARED or greater lock on the file
26176     ** already.
26177     */
26178     int failed = 0;
26179     assert( 0!=pFile->eFileLock );
26180     if (eFileLock >= RESERVED_LOCK && pFile->eFileLock < RESERVED_LOCK) {
26181         /* Acquire a RESERVED lock */
26182         failed = afpSetLock(context->dbPath, pFile, RESERVED_BYTE, 1,1);
26183       if( !failed ){
26184         context->reserved = 1;
26185       }
26186     }
26187     if (!failed && eFileLock == EXCLUSIVE_LOCK) {
26188       /* Acquire an EXCLUSIVE lock */
26189         
26190       /* Remove the shared lock before trying the range.  we'll need to 
26191       ** reestablish the shared lock if we can't get the  afpUnlock
26192       */
26193       if( !(failed = afpSetLock(context->dbPath, pFile, SHARED_FIRST +
26194                          pInode->sharedByte, 1, 0)) ){
26195         int failed2 = SQLITE_OK;
26196         /* now attemmpt to get the exclusive lock range */
26197         failed = afpSetLock(context->dbPath, pFile, SHARED_FIRST, 
26198                                SHARED_SIZE, 1);
26199         if( failed && (failed2 = afpSetLock(context->dbPath, pFile, 
26200                        SHARED_FIRST + pInode->sharedByte, 1, 1)) ){
26201           /* Can't reestablish the shared lock.  Sqlite can't deal, this is
26202           ** a critical I/O error
26203           */
26204           rc = ((failed & SQLITE_IOERR) == SQLITE_IOERR) ? failed2 : 
26205                SQLITE_IOERR_LOCK;
26206           goto afp_end_lock;
26207         } 
26208       }else{
26209         rc = failed; 
26210       }
26211     }
26212     if( failed ){
26213       rc = failed;
26214     }
26215   }
26216   
26217   if( rc==SQLITE_OK ){
26218     pFile->eFileLock = eFileLock;
26219     pInode->eFileLock = eFileLock;
26220   }else if( eFileLock==EXCLUSIVE_LOCK ){
26221     pFile->eFileLock = PENDING_LOCK;
26222     pInode->eFileLock = PENDING_LOCK;
26223   }
26224   
26225 afp_end_lock:
26226   unixLeaveMutex();
26227   OSTRACE(("LOCK    %d %s %s (afp)\n", pFile->h, azFileLock(eFileLock), 
26228          rc==SQLITE_OK ? "ok" : "failed"));
26229   return rc;
26230 }
26231 
26232 /*
26233 ** Lower the locking level on file descriptor pFile to eFileLock.  eFileLock
26234 ** must be either NO_LOCK or SHARED_LOCK.
26235 **
26236 ** If the locking level of the file descriptor is already at or below
26237 ** the requested locking level, this routine is a no-op.
26238 */
26239 static int afpUnlock(sqlite3_file *id, int eFileLock) {
26240   int rc = SQLITE_OK;
26241   unixFile *pFile = (unixFile*)id;
26242   unixInodeInfo *pInode;
26243   afpLockingContext *context = (afpLockingContext *) pFile->lockingContext;
26244   int skipShared = 0;
26245 #ifdef SQLITE_TEST
26246   int h = pFile->h;
26247 #endif
26248 
26249   assert( pFile );
26250   OSTRACE(("UNLOCK  %d %d was %d(%d,%d) pid=%d (afp)\n", pFile->h, eFileLock,
26251            pFile->eFileLock, pFile->pInode->eFileLock, pFile->pInode->nShared,
26252            getpid()));
26253 
26254   assert( eFileLock<=SHARED_LOCK );
26255   if( pFile->eFileLock<=eFileLock ){
26256     return SQLITE_OK;
26257   }
26258   unixEnterMutex();
26259   pInode = pFile->pInode;
26260   assert( pInode->nShared!=0 );
26261   if( pFile->eFileLock>SHARED_LOCK ){
26262     assert( pInode->eFileLock==pFile->eFileLock );
26263     SimulateIOErrorBenign(1);
26264     SimulateIOError( h=(-1) )
26265     SimulateIOErrorBenign(0);
26266     
26267 #ifdef SQLITE_DEBUG
26268     /* When reducing a lock such that other processes can start
26269     ** reading the database file again, make sure that the
26270     ** transaction counter was updated if any part of the database
26271     ** file changed.  If the transaction counter is not updated,
26272     ** other connections to the same file might not realize that
26273     ** the file has changed and hence might not know to flush their
26274     ** cache.  The use of a stale cache can lead to database corruption.
26275     */
26276     assert( pFile->inNormalWrite==0
26277            || pFile->dbUpdate==0
26278            || pFile->transCntrChng==1 );
26279     pFile->inNormalWrite = 0;
26280 #endif
26281     
26282     if( pFile->eFileLock==EXCLUSIVE_LOCK ){
26283       rc = afpSetLock(context->dbPath, pFile, SHARED_FIRST, SHARED_SIZE, 0);
26284       if( rc==SQLITE_OK && (eFileLock==SHARED_LOCK || pInode->nShared>1) ){
26285         /* only re-establish the shared lock if necessary */
26286         int sharedLockByte = SHARED_FIRST+pInode->sharedByte;
26287         rc = afpSetLock(context->dbPath, pFile, sharedLockByte, 1, 1);
26288       } else {
26289         skipShared = 1;
26290       }
26291     }
26292     if( rc==SQLITE_OK && pFile->eFileLock>=PENDING_LOCK ){
26293       rc = afpSetLock(context->dbPath, pFile, PENDING_BYTE, 1, 0);
26294     } 
26295     if( rc==SQLITE_OK && pFile->eFileLock>=RESERVED_LOCK && context->reserved ){
26296       rc = afpSetLock(context->dbPath, pFile, RESERVED_BYTE, 1, 0);
26297       if( !rc ){ 
26298         context->reserved = 0; 
26299       }
26300     }
26301     if( rc==SQLITE_OK && (eFileLock==SHARED_LOCK || pInode->nShared>1)){
26302       pInode->eFileLock = SHARED_LOCK;
26303     }
26304   }
26305   if( rc==SQLITE_OK && eFileLock==NO_LOCK ){
26306 
26307     /* Decrement the shared lock counter.  Release the lock using an
26308     ** OS call only when all threads in this same process have released
26309     ** the lock.
26310     */
26311     unsigned long long sharedLockByte = SHARED_FIRST+pInode->sharedByte;
26312     pInode->nShared--;
26313     if( pInode->nShared==0 ){
26314       SimulateIOErrorBenign(1);
26315       SimulateIOError( h=(-1) )
26316       SimulateIOErrorBenign(0);
26317       if( !skipShared ){
26318         rc = afpSetLock(context->dbPath, pFile, sharedLockByte, 1, 0);
26319       }
26320       if( !rc ){
26321         pInode->eFileLock = NO_LOCK;
26322         pFile->eFileLock = NO_LOCK;
26323       }
26324     }
26325     if( rc==SQLITE_OK ){
26326       pInode->nLock--;
26327       assert( pInode->nLock>=0 );
26328       if( pInode->nLock==0 ){
26329         closePendingFds(pFile);
26330       }
26331     }
26332   }
26333   
26334   unixLeaveMutex();
26335   if( rc==SQLITE_OK ) pFile->eFileLock = eFileLock;
26336   return rc;
26337 }
26338 
26339 /*
26340 ** Close a file & cleanup AFP specific locking context 
26341 */
26342 static int afpClose(sqlite3_file *id) {
26343   int rc = SQLITE_OK;
26344   if( id ){
26345     unixFile *pFile = (unixFile*)id;
26346     afpUnlock(id, NO_LOCK);
26347     unixEnterMutex();
26348     if( pFile->pInode && pFile->pInode->nLock ){
26349       /* If there are outstanding locks, do not actually close the file just
26350       ** yet because that would clear those locks.  Instead, add the file
26351       ** descriptor to pInode->aPending.  It will be automatically closed when
26352       ** the last lock is cleared.
26353       */
26354       setPendingFd(pFile);
26355     }
26356     releaseInodeInfo(pFile);
26357     sqlite3_free(pFile->lockingContext);
26358     rc = closeUnixFile(id);
26359     unixLeaveMutex();
26360   }
26361   return rc;
26362 }
26363 
26364 #endif /* defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE */
26365 /*
26366 ** The code above is the AFP lock implementation.  The code is specific
26367 ** to MacOSX and does not work on other unix platforms.  No alternative
26368 ** is available.  If you don't compile for a mac, then the "unix-afp"
26369 ** VFS is not available.
26370 **
26371 ********************* End of the AFP lock implementation **********************
26372 ******************************************************************************/
26373 
26374 /******************************************************************************
26375 *************************** Begin NFS Locking ********************************/
26376 
26377 #if defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE
26378 /*
26379  ** Lower the locking level on file descriptor pFile to eFileLock.  eFileLock
26380  ** must be either NO_LOCK or SHARED_LOCK.
26381  **
26382  ** If the locking level of the file descriptor is already at or below
26383  ** the requested locking level, this routine is a no-op.
26384  */
26385 static int nfsUnlock(sqlite3_file *id, int eFileLock){
26386   return posixUnlock(id, eFileLock, 1);
26387 }
26388 
26389 #endif /* defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE */
26390 /*
26391 ** The code above is the NFS lock implementation.  The code is specific
26392 ** to MacOSX and does not work on other unix platforms.  No alternative
26393 ** is available.  
26394 **
26395 ********************* End of the NFS lock implementation **********************
26396 ******************************************************************************/
26397 
26398 /******************************************************************************
26399 **************** Non-locking sqlite3_file methods *****************************
26400 **
26401 ** The next division contains implementations for all methods of the 
26402 ** sqlite3_file object other than the locking methods.  The locking
26403 ** methods were defined in divisions above (one locking method per
26404 ** division).  Those methods that are common to all locking modes
26405 ** are gather together into this division.
26406 */
26407 
26408 /*
26409 ** Seek to the offset passed as the second argument, then read cnt 
26410 ** bytes into pBuf. Return the number of bytes actually read.
26411 **
26412 ** NB:  If you define USE_PREAD or USE_PREAD64, then it might also
26413 ** be necessary to define _XOPEN_SOURCE to be 500.  This varies from
26414 ** one system to another.  Since SQLite does not define USE_PREAD
26415 ** any any form by default, we will not attempt to define _XOPEN_SOURCE.
26416 ** See tickets #2741 and #2681.
26417 **
26418 ** To avoid stomping the errno value on a failed read the lastErrno value
26419 ** is set before returning.
26420 */
26421 static int seekAndRead(unixFile *id, sqlite3_int64 offset, void *pBuf, int cnt){
26422   int got;
26423   int prior = 0;
26424 #if (!defined(USE_PREAD) && !defined(USE_PREAD64))
26425   i64 newOffset;
26426 #endif
26427   TIMER_START;
26428   assert( cnt==(cnt&0x1ffff) );
26429   assert( id->h>2 );
26430   cnt &= 0x1ffff;
26431   do{
26432 #if defined(USE_PREAD)
26433     got = osPread(id->h, pBuf, cnt, offset);
26434     SimulateIOError( got = -1 );
26435 #elif defined(USE_PREAD64)
26436     got = osPread64(id->h, pBuf, cnt, offset);
26437     SimulateIOError( got = -1 );
26438 #else
26439     newOffset = lseek(id->h, offset, SEEK_SET);
26440     SimulateIOError( newOffset-- );
26441     if( newOffset!=offset ){
26442       if( newOffset == -1 ){
26443         ((unixFile*)id)->lastErrno = errno;
26444       }else{
26445         ((unixFile*)id)->lastErrno = 0;
26446       }
26447       return -1;
26448     }
26449     got = osRead(id->h, pBuf, cnt);
26450 #endif
26451     if( got==cnt ) break;
26452     if( got<0 ){
26453       if( errno==EINTR ){ got = 1; continue; }
26454       prior = 0;
26455       ((unixFile*)id)->lastErrno = errno;
26456       break;
26457     }else if( got>0 ){
26458       cnt -= got;
26459       offset += got;
26460       prior += got;
26461       pBuf = (void*)(got + (char*)pBuf);
26462     }
26463   }while( got>0 );
26464   TIMER_END;
26465   OSTRACE(("READ    %-3d %5d %7lld %llu\n",
26466             id->h, got+prior, offset-prior, TIMER_ELAPSED));
26467   return got+prior;
26468 }
26469 
26470 /*
26471 ** Read data from a file into a buffer.  Return SQLITE_OK if all
26472 ** bytes were read successfully and SQLITE_IOERR if anything goes
26473 ** wrong.
26474 */
26475 static int unixRead(
26476   sqlite3_file *id, 
26477   void *pBuf, 
26478   int amt,
26479   sqlite3_int64 offset
26480 ){
26481   unixFile *pFile = (unixFile *)id;
26482   int got;
26483   assert( id );
26484   assert( offset>=0 );
26485   assert( amt>0 );
26486 
26487   /* If this is a database file (not a journal, master-journal or temp
26488   ** file), the bytes in the locking range should never be read or written. */
26489 #if 0
26490   assert( pFile->pUnused==0
26491        || offset>=PENDING_BYTE+512
26492        || offset+amt<=PENDING_BYTE 
26493   );
26494 #endif
26495 
26496 #if SQLITE_MAX_MMAP_SIZE>0
26497   /* Deal with as much of this read request as possible by transfering
26498   ** data from the memory mapping using memcpy().  */
26499   if( offset<pFile->mmapSize ){
26500     if( offset+amt <= pFile->mmapSize ){
26501       memcpy(pBuf, &((u8 *)(pFile->pMapRegion))[offset], amt);
26502       return SQLITE_OK;
26503     }else{
26504       int nCopy = pFile->mmapSize - offset;
26505       memcpy(pBuf, &((u8 *)(pFile->pMapRegion))[offset], nCopy);
26506       pBuf = &((u8 *)pBuf)[nCopy];
26507       amt -= nCopy;
26508       offset += nCopy;
26509     }
26510   }
26511 #endif
26512 
26513   got = seekAndRead(pFile, offset, pBuf, amt);
26514   if( got==amt ){
26515     return SQLITE_OK;
26516   }else if( got<0 ){
26517     /* lastErrno set by seekAndRead */
26518     return SQLITE_IOERR_READ;
26519   }else{
26520     pFile->lastErrno = 0; /* not a system error */
26521     /* Unread parts of the buffer must be zero-filled */
26522     memset(&((char*)pBuf)[got], 0, amt-got);
26523     return SQLITE_IOERR_SHORT_READ;
26524   }
26525 }
26526 
26527 /*
26528 ** Attempt to seek the file-descriptor passed as the first argument to
26529 ** absolute offset iOff, then attempt to write nBuf bytes of data from
26530 ** pBuf to it. If an error occurs, return -1 and set *piErrno. Otherwise, 
26531 ** return the actual number of bytes written (which may be less than
26532 ** nBuf).
26533 */
26534 static int seekAndWriteFd(
26535   int fd,                         /* File descriptor to write to */
26536   i64 iOff,                       /* File offset to begin writing at */
26537   const void *pBuf,               /* Copy data from this buffer to the file */
26538   int nBuf,                       /* Size of buffer pBuf in bytes */
26539   int *piErrno                    /* OUT: Error number if error occurs */
26540 ){
26541   int rc = 0;                     /* Value returned by system call */
26542 
26543   assert( nBuf==(nBuf&0x1ffff) );
26544   assert( fd>2 );
26545   nBuf &= 0x1ffff;
26546   TIMER_START;
26547 
26548 #if defined(USE_PREAD)
26549   do{ rc = osPwrite(fd, pBuf, nBuf, iOff); }while( rc<0 && errno==EINTR );
26550 #elif defined(USE_PREAD64)
26551   do{ rc = osPwrite64(fd, pBuf, nBuf, iOff);}while( rc<0 && errno==EINTR);
26552 #else
26553   do{
26554     i64 iSeek = lseek(fd, iOff, SEEK_SET);
26555     SimulateIOError( iSeek-- );
26556 
26557     if( iSeek!=iOff ){
26558       if( piErrno ) *piErrno = (iSeek==-1 ? errno : 0);
26559       return -1;
26560     }
26561     rc = osWrite(fd, pBuf, nBuf);
26562   }while( rc<0 && errno==EINTR );
26563 #endif
26564 
26565   TIMER_END;
26566   OSTRACE(("WRITE   %-3d %5d %7lld %llu\n", fd, rc, iOff, TIMER_ELAPSED));
26567 
26568   if( rc<0 && piErrno ) *piErrno = errno;
26569   return rc;
26570 }
26571 
26572 
26573 /*
26574 ** Seek to the offset in id->offset then read cnt bytes into pBuf.
26575 ** Return the number of bytes actually read.  Update the offset.
26576 **
26577 ** To avoid stomping the errno value on a failed write the lastErrno value
26578 ** is set before returning.
26579 */
26580 static int seekAndWrite(unixFile *id, i64 offset, const void *pBuf, int cnt){
26581   return seekAndWriteFd(id->h, offset, pBuf, cnt, &id->lastErrno);
26582 }
26583 
26584 
26585 /*
26586 ** Write data from a buffer into a file.  Return SQLITE_OK on success
26587 ** or some other error code on failure.
26588 */
26589 static int unixWrite(
26590   sqlite3_file *id, 
26591   const void *pBuf, 
26592   int amt,
26593   sqlite3_int64 offset 
26594 ){
26595   unixFile *pFile = (unixFile*)id;
26596   int wrote = 0;
26597   assert( id );
26598   assert( amt>0 );
26599 
26600   /* If this is a database file (not a journal, master-journal or temp
26601   ** file), the bytes in the locking range should never be read or written. */
26602 #if 0
26603   assert( pFile->pUnused==0
26604        || offset>=PENDING_BYTE+512
26605        || offset+amt<=PENDING_BYTE 
26606   );
26607 #endif
26608 
26609 #ifdef SQLITE_DEBUG
26610   /* If we are doing a normal write to a database file (as opposed to
26611   ** doing a hot-journal rollback or a write to some file other than a
26612   ** normal database file) then record the fact that the database
26613   ** has changed.  If the transaction counter is modified, record that
26614   ** fact too.
26615   */
26616   if( pFile->inNormalWrite ){
26617     pFile->dbUpdate = 1;  /* The database has been modified */
26618     if( offset<=24 && offset+amt>=27 ){
26619       int rc;
26620       char oldCntr[4];
26621       SimulateIOErrorBenign(1);
26622       rc = seekAndRead(pFile, 24, oldCntr, 4);
26623       SimulateIOErrorBenign(0);
26624       if( rc!=4 || memcmp(oldCntr, &((char*)pBuf)[24-offset], 4)!=0 ){
26625         pFile->transCntrChng = 1;  /* The transaction counter has changed */
26626       }
26627     }
26628   }
26629 #endif
26630 
26631 #if SQLITE_MAX_MMAP_SIZE>0
26632   /* Deal with as much of this write request as possible by transfering
26633   ** data from the memory mapping using memcpy().  */
26634   if( offset<pFile->mmapSize ){
26635     if( offset+amt <= pFile->mmapSize ){
26636       memcpy(&((u8 *)(pFile->pMapRegion))[offset], pBuf, amt);
26637       return SQLITE_OK;
26638     }else{
26639       int nCopy = pFile->mmapSize - offset;
26640       memcpy(&((u8 *)(pFile->pMapRegion))[offset], pBuf, nCopy);
26641       pBuf = &((u8 *)pBuf)[nCopy];
26642       amt -= nCopy;
26643       offset += nCopy;
26644     }
26645   }
26646 #endif
26647 
26648   while( amt>0 && (wrote = seekAndWrite(pFile, offset, pBuf, amt))>0 ){
26649     amt -= wrote;
26650     offset += wrote;
26651     pBuf = &((char*)pBuf)[wrote];
26652   }
26653   SimulateIOError(( wrote=(-1), amt=1 ));
26654   SimulateDiskfullError(( wrote=0, amt=1 ));
26655 
26656   if( amt>0 ){
26657     if( wrote<0 && pFile->lastErrno!=ENOSPC ){
26658       /* lastErrno set by seekAndWrite */
26659       return SQLITE_IOERR_WRITE;
26660     }else{
26661       pFile->lastErrno = 0; /* not a system error */
26662       return SQLITE_FULL;
26663     }
26664   }
26665 
26666   return SQLITE_OK;
26667 }
26668 
26669 #ifdef SQLITE_TEST
26670 /*
26671 ** Count the number of fullsyncs and normal syncs.  This is used to test
26672 ** that syncs and fullsyncs are occurring at the right times.
26673 */
26674 SQLITE_API int sqlite3_sync_count = 0;
26675 SQLITE_API int sqlite3_fullsync_count = 0;
26676 #endif
26677 
26678 /*
26679 ** We do not trust systems to provide a working fdatasync().  Some do.
26680 ** Others do no.  To be safe, we will stick with the (slightly slower)
26681 ** fsync(). If you know that your system does support fdatasync() correctly,
26682 ** then simply compile with -Dfdatasync=fdatasync
26683 */
26684 #if !defined(fdatasync)
26685 # define fdatasync fsync
26686 #endif
26687 
26688 /*
26689 ** Define HAVE_FULLFSYNC to 0 or 1 depending on whether or not
26690 ** the F_FULLFSYNC macro is defined.  F_FULLFSYNC is currently
26691 ** only available on Mac OS X.  But that could change.
26692 */
26693 #ifdef F_FULLFSYNC
26694 # define HAVE_FULLFSYNC 1
26695 #else
26696 # define HAVE_FULLFSYNC 0
26697 #endif
26698 
26699 
26700 /*
26701 ** The fsync() system call does not work as advertised on many
26702 ** unix systems.  The following procedure is an attempt to make
26703 ** it work better.
26704 **
26705 ** The SQLITE_NO_SYNC macro disables all fsync()s.  This is useful
26706 ** for testing when we want to run through the test suite quickly.
26707 ** You are strongly advised *not* to deploy with SQLITE_NO_SYNC
26708 ** enabled, however, since with SQLITE_NO_SYNC enabled, an OS crash
26709 ** or power failure will likely corrupt the database file.
26710 **
26711 ** SQLite sets the dataOnly flag if the size of the file is unchanged.
26712 ** The idea behind dataOnly is that it should only write the file content
26713 ** to disk, not the inode.  We only set dataOnly if the file size is 
26714 ** unchanged since the file size is part of the inode.  However, 
26715 ** Ted Ts'o tells us that fdatasync() will also write the inode if the
26716 ** file size has changed.  The only real difference between fdatasync()
26717 ** and fsync(), Ted tells us, is that fdatasync() will not flush the
26718 ** inode if the mtime or owner or other inode attributes have changed.
26719 ** We only care about the file size, not the other file attributes, so
26720 ** as far as SQLite is concerned, an fdatasync() is always adequate.
26721 ** So, we always use fdatasync() if it is available, regardless of
26722 ** the value of the dataOnly flag.
26723 */
26724 static int full_fsync(int fd, int fullSync, int dataOnly){
26725   int rc;
26726 
26727   /* The following "ifdef/elif/else/" block has the same structure as
26728   ** the one below. It is replicated here solely to avoid cluttering 
26729   ** up the real code with the UNUSED_PARAMETER() macros.
26730   */
26731 #ifdef SQLITE_NO_SYNC
26732   UNUSED_PARAMETER(fd);
26733   UNUSED_PARAMETER(fullSync);
26734   UNUSED_PARAMETER(dataOnly);
26735 #elif HAVE_FULLFSYNC
26736   UNUSED_PARAMETER(dataOnly);
26737 #else
26738   UNUSED_PARAMETER(fullSync);
26739   UNUSED_PARAMETER(dataOnly);
26740 #endif
26741 
26742   /* Record the number of times that we do a normal fsync() and 
26743   ** FULLSYNC.  This is used during testing to verify that this procedure
26744   ** gets called with the correct arguments.
26745   */
26746 #ifdef SQLITE_TEST
26747   if( fullSync ) sqlite3_fullsync_count++;
26748   sqlite3_sync_count++;
26749 #endif
26750 
26751   /* If we compiled with the SQLITE_NO_SYNC flag, then syncing is a
26752   ** no-op
26753   */
26754 #ifdef SQLITE_NO_SYNC
26755   rc = SQLITE_OK;
26756 #elif HAVE_FULLFSYNC
26757   if( fullSync ){
26758     rc = osFcntl(fd, F_FULLFSYNC, 0);
26759   }else{
26760     rc = 1;
26761   }
26762   /* If the FULLFSYNC failed, fall back to attempting an fsync().
26763   ** It shouldn't be possible for fullfsync to fail on the local 
26764   ** file system (on OSX), so failure indicates that FULLFSYNC
26765   ** isn't supported for this file system. So, attempt an fsync 
26766   ** and (for now) ignore the overhead of a superfluous fcntl call.  
26767   ** It'd be better to detect fullfsync support once and avoid 
26768   ** the fcntl call every time sync is called.
26769   */
26770   if( rc ) rc = fsync(fd);
26771 
26772 #elif defined(__APPLE__)
26773   /* fdatasync() on HFS+ doesn't yet flush the file size if it changed correctly
26774   ** so currently we default to the macro that redefines fdatasync to fsync
26775   */
26776   rc = fsync(fd);
26777 #else 
26778   rc = fdatasync(fd);
26779 #if OS_VXWORKS
26780   if( rc==-1 && errno==ENOTSUP ){
26781     rc = fsync(fd);
26782   }
26783 #endif /* OS_VXWORKS */
26784 #endif /* ifdef SQLITE_NO_SYNC elif HAVE_FULLFSYNC */
26785 
26786   if( OS_VXWORKS && rc!= -1 ){
26787     rc = 0;
26788   }
26789   return rc;
26790 }
26791 
26792 /*
26793 ** Open a file descriptor to the directory containing file zFilename.
26794 ** If successful, *pFd is set to the opened file descriptor and
26795 ** SQLITE_OK is returned. If an error occurs, either SQLITE_NOMEM
26796 ** or SQLITE_CANTOPEN is returned and *pFd is set to an undefined
26797 ** value.
26798 **
26799 ** The directory file descriptor is used for only one thing - to
26800 ** fsync() a directory to make sure file creation and deletion events
26801 ** are flushed to disk.  Such fsyncs are not needed on newer
26802 ** journaling filesystems, but are required on older filesystems.
26803 **
26804 ** This routine can be overridden using the xSetSysCall interface.
26805 ** The ability to override this routine was added in support of the
26806 ** chromium sandbox.  Opening a directory is a security risk (we are
26807 ** told) so making it overrideable allows the chromium sandbox to
26808 ** replace this routine with a harmless no-op.  To make this routine
26809 ** a no-op, replace it with a stub that returns SQLITE_OK but leaves
26810 ** *pFd set to a negative number.
26811 **
26812 ** If SQLITE_OK is returned, the caller is responsible for closing
26813 ** the file descriptor *pFd using close().
26814 */
26815 static int openDirectory(const char *zFilename, int *pFd){
26816   int ii;
26817   int fd = -1;
26818   char zDirname[MAX_PATHNAME+1];
26819 
26820   sqlite3_snprintf(MAX_PATHNAME, zDirname, "%s", zFilename);
26821   for(ii=(int)strlen(zDirname); ii>1 && zDirname[ii]!='/'; ii--);
26822   if( ii>0 ){
26823     zDirname[ii] = '\0';
26824     fd = robust_open(zDirname, O_RDONLY|O_BINARY, 0);
26825     if( fd>=0 ){
26826       OSTRACE(("OPENDIR %-3d %s\n", fd, zDirname));
26827     }
26828   }
26829   *pFd = fd;
26830   return (fd>=0?SQLITE_OK:unixLogError(SQLITE_CANTOPEN_BKPT, "open", zDirname));
26831 }
26832 
26833 /*
26834 ** Make sure all writes to a particular file are committed to disk.
26835 **
26836 ** If dataOnly==0 then both the file itself and its metadata (file
26837 ** size, access time, etc) are synced.  If dataOnly!=0 then only the
26838 ** file data is synced.
26839 **
26840 ** Under Unix, also make sure that the directory entry for the file
26841 ** has been created by fsync-ing the directory that contains the file.
26842 ** If we do not do this and we encounter a power failure, the directory
26843 ** entry for the journal might not exist after we reboot.  The next
26844 ** SQLite to access the file will not know that the journal exists (because
26845 ** the directory entry for the journal was never created) and the transaction
26846 ** will not roll back - possibly leading to database corruption.
26847 */
26848 static int unixSync(sqlite3_file *id, int flags){
26849   int rc;
26850   unixFile *pFile = (unixFile*)id;
26851 
26852   int isDataOnly = (flags&SQLITE_SYNC_DATAONLY);
26853   int isFullsync = (flags&0x0F)==SQLITE_SYNC_FULL;
26854 
26855   /* Check that one of SQLITE_SYNC_NORMAL or FULL was passed */
26856   assert((flags&0x0F)==SQLITE_SYNC_NORMAL
26857       || (flags&0x0F)==SQLITE_SYNC_FULL
26858   );
26859 
26860   /* Unix cannot, but some systems may return SQLITE_FULL from here. This
26861   ** line is to test that doing so does not cause any problems.
26862   */
26863   SimulateDiskfullError( return SQLITE_FULL );
26864 
26865   assert( pFile );
26866   OSTRACE(("SYNC    %-3d\n", pFile->h));
26867   rc = full_fsync(pFile->h, isFullsync, isDataOnly);
26868   SimulateIOError( rc=1 );
26869   if( rc ){
26870     pFile->lastErrno = errno;
26871     return unixLogError(SQLITE_IOERR_FSYNC, "full_fsync", pFile->zPath);
26872   }
26873 
26874   /* Also fsync the directory containing the file if the DIRSYNC flag
26875   ** is set.  This is a one-time occurrence.  Many systems (examples: AIX)
26876   ** are unable to fsync a directory, so ignore errors on the fsync.
26877   */
26878   if( pFile->ctrlFlags & UNIXFILE_DIRSYNC ){
26879     int dirfd;
26880     OSTRACE(("DIRSYNC %s (have_fullfsync=%d fullsync=%d)\n", pFile->zPath,
26881             HAVE_FULLFSYNC, isFullsync));
26882     rc = osOpenDirectory(pFile->zPath, &dirfd);
26883     if( rc==SQLITE_OK && dirfd>=0 ){
26884       full_fsync(dirfd, 0, 0);
26885       robust_close(pFile, dirfd, __LINE__);
26886     }else if( rc==SQLITE_CANTOPEN ){
26887       rc = SQLITE_OK;
26888     }
26889     pFile->ctrlFlags &= ~UNIXFILE_DIRSYNC;
26890   }
26891   return rc;
26892 }
26893 
26894 /*
26895 ** Truncate an open file to a specified size
26896 */
26897 static int unixTruncate(sqlite3_file *id, i64 nByte){
26898   unixFile *pFile = (unixFile *)id;
26899   int rc;
26900   assert( pFile );
26901   SimulateIOError( return SQLITE_IOERR_TRUNCATE );
26902 
26903   /* If the user has configured a chunk-size for this file, truncate the
26904   ** file so that it consists of an integer number of chunks (i.e. the
26905   ** actual file size after the operation may be larger than the requested
26906   ** size).
26907   */
26908   if( pFile->szChunk>0 ){
26909     nByte = ((nByte + pFile->szChunk - 1)/pFile->szChunk) * pFile->szChunk;
26910   }
26911 
26912   rc = robust_ftruncate(pFile->h, (off_t)nByte);
26913   if( rc ){
26914     pFile->lastErrno = errno;
26915     return unixLogError(SQLITE_IOERR_TRUNCATE, "ftruncate", pFile->zPath);
26916   }else{
26917 #ifdef SQLITE_DEBUG
26918     /* If we are doing a normal write to a database file (as opposed to
26919     ** doing a hot-journal rollback or a write to some file other than a
26920     ** normal database file) and we truncate the file to zero length,
26921     ** that effectively updates the change counter.  This might happen
26922     ** when restoring a database using the backup API from a zero-length
26923     ** source.
26924     */
26925     if( pFile->inNormalWrite && nByte==0 ){
26926       pFile->transCntrChng = 1;
26927     }
26928 #endif
26929 
26930 #if SQLITE_MAX_MMAP_SIZE>0
26931     /* If the file was just truncated to a size smaller than the currently
26932     ** mapped region, reduce the effective mapping size as well. SQLite will
26933     ** use read() and write() to access data beyond this point from now on.  
26934     */
26935     if( nByte<pFile->mmapSize ){
26936       pFile->mmapSize = nByte;
26937     }
26938 #endif
26939 
26940     return SQLITE_OK;
26941   }
26942 }
26943 
26944 /*
26945 ** Determine the current size of a file in bytes
26946 */
26947 static int unixFileSize(sqlite3_file *id, i64 *pSize){
26948   int rc;
26949   struct stat buf;
26950   assert( id );
26951   rc = osFstat(((unixFile*)id)->h, &buf);
26952   SimulateIOError( rc=1 );
26953   if( rc!=0 ){
26954     ((unixFile*)id)->lastErrno = errno;
26955     return SQLITE_IOERR_FSTAT;
26956   }
26957   *pSize = buf.st_size;
26958 
26959   /* When opening a zero-size database, the findInodeInfo() procedure
26960   ** writes a single byte into that file in order to work around a bug
26961   ** in the OS-X msdos filesystem.  In order to avoid problems with upper
26962   ** layers, we need to report this file size as zero even though it is
26963   ** really 1.   Ticket #3260.
26964   */
26965   if( *pSize==1 ) *pSize = 0;
26966 
26967 
26968   return SQLITE_OK;
26969 }
26970 
26971 #if SQLITE_ENABLE_LOCKING_STYLE && defined(__APPLE__)
26972 /*
26973 ** Handler for proxy-locking file-control verbs.  Defined below in the
26974 ** proxying locking division.
26975 */
26976 static int proxyFileControl(sqlite3_file*,int,void*);
26977 #endif
26978 
26979 /* 
26980 ** This function is called to handle the SQLITE_FCNTL_SIZE_HINT 
26981 ** file-control operation.  Enlarge the database to nBytes in size
26982 ** (rounded up to the next chunk-size).  If the database is already
26983 ** nBytes or larger, this routine is a no-op.
26984 */
26985 static int fcntlSizeHint(unixFile *pFile, i64 nByte){
26986   if( pFile->szChunk>0 ){
26987     i64 nSize;                    /* Required file size */
26988     struct stat buf;              /* Used to hold return values of fstat() */
26989    
26990     if( osFstat(pFile->h, &buf) ) return SQLITE_IOERR_FSTAT;
26991 
26992     nSize = ((nByte+pFile->szChunk-1) / pFile->szChunk) * pFile->szChunk;
26993     if( nSize>(i64)buf.st_size ){
26994 
26995 #if defined(HAVE_POSIX_FALLOCATE) && HAVE_POSIX_FALLOCATE
26996       /* The code below is handling the return value of osFallocate() 
26997       ** correctly. posix_fallocate() is defined to "returns zero on success, 
26998       ** or an error number on  failure". See the manpage for details. */
26999       int err;
27000       do{
27001         err = osFallocate(pFile->h, buf.st_size, nSize-buf.st_size);
27002       }while( err==EINTR );
27003       if( err ) return SQLITE_IOERR_WRITE;
27004 #else
27005       /* If the OS does not have posix_fallocate(), fake it. First use
27006       ** ftruncate() to set the file size, then write a single byte to
27007       ** the last byte in each block within the extended region. This
27008       ** is the same technique used by glibc to implement posix_fallocate()
27009       ** on systems that do not have a real fallocate() system call.
27010       */
27011       int nBlk = buf.st_blksize;  /* File-system block size */
27012       i64 iWrite;                 /* Next offset to write to */
27013 
27014       if( robust_ftruncate(pFile->h, nSize) ){
27015         pFile->lastErrno = errno;
27016         return unixLogError(SQLITE_IOERR_TRUNCATE, "ftruncate", pFile->zPath);
27017       }
27018       iWrite = ((buf.st_size + 2*nBlk - 1)/nBlk)*nBlk-1;
27019       while( iWrite<nSize ){
27020         int nWrite = seekAndWrite(pFile, iWrite, "", 1);
27021         if( nWrite!=1 ) return SQLITE_IOERR_WRITE;
27022         iWrite += nBlk;
27023       }
27024 #endif
27025     }
27026   }
27027 
27028 #if SQLITE_MAX_MMAP_SIZE>0
27029   if( pFile->mmapSizeMax>0 && nByte>pFile->mmapSize ){
27030     int rc;
27031     if( pFile->szChunk<=0 ){
27032       if( robust_ftruncate(pFile->h, nByte) ){
27033         pFile->lastErrno = errno;
27034         return unixLogError(SQLITE_IOERR_TRUNCATE, "ftruncate", pFile->zPath);
27035       }
27036     }
27037 
27038     rc = unixMapfile(pFile, nByte);
27039     return rc;
27040   }
27041 #endif
27042 
27043   return SQLITE_OK;
27044 }
27045 
27046 /*
27047 ** If *pArg is inititially negative then this is a query.  Set *pArg to
27048 ** 1 or 0 depending on whether or not bit mask of pFile->ctrlFlags is set.
27049 **
27050 ** If *pArg is 0 or 1, then clear or set the mask bit of pFile->ctrlFlags.
27051 */
27052 static void unixModeBit(unixFile *pFile, unsigned char mask, int *pArg){
27053   if( *pArg<0 ){
27054     *pArg = (pFile->ctrlFlags & mask)!=0;
27055   }else if( (*pArg)==0 ){
27056     pFile->ctrlFlags &= ~mask;
27057   }else{
27058     pFile->ctrlFlags |= mask;
27059   }
27060 }
27061 
27062 /* Forward declaration */
27063 static int unixGetTempname(int nBuf, char *zBuf);
27064 
27065 /*
27066 ** Information and control of an open file handle.
27067 */
27068 static int unixFileControl(sqlite3_file *id, int op, void *pArg){
27069   unixFile *pFile = (unixFile*)id;
27070   switch( op ){
27071     case SQLITE_FCNTL_LOCKSTATE: {
27072       *(int*)pArg = pFile->eFileLock;
27073       return SQLITE_OK;
27074     }
27075     case SQLITE_LAST_ERRNO: {
27076       *(int*)pArg = pFile->lastErrno;
27077       return SQLITE_OK;
27078     }
27079     case SQLITE_FCNTL_CHUNK_SIZE: {
27080       pFile->szChunk = *(int *)pArg;
27081       return SQLITE_OK;
27082     }
27083     case SQLITE_FCNTL_SIZE_HINT: {
27084       int rc;
27085       SimulateIOErrorBenign(1);
27086       rc = fcntlSizeHint(pFile, *(i64 *)pArg);
27087       SimulateIOErrorBenign(0);
27088       return rc;
27089     }
27090     case SQLITE_FCNTL_PERSIST_WAL: {
27091       unixModeBit(pFile, UNIXFILE_PERSIST_WAL, (int*)pArg);
27092       return SQLITE_OK;
27093     }
27094     case SQLITE_FCNTL_POWERSAFE_OVERWRITE: {
27095       unixModeBit(pFile, UNIXFILE_PSOW, (int*)pArg);
27096       return SQLITE_OK;
27097     }
27098     case SQLITE_FCNTL_VFSNAME: {
27099       *(char**)pArg = sqlite3_mprintf("%s", pFile->pVfs->zName);
27100       return SQLITE_OK;
27101     }
27102     case SQLITE_FCNTL_TEMPFILENAME: {
27103       char *zTFile = sqlite3_malloc( pFile->pVfs->mxPathname );
27104       if( zTFile ){
27105         unixGetTempname(pFile->pVfs->mxPathname, zTFile);
27106         *(char**)pArg = zTFile;
27107       }
27108       return SQLITE_OK;
27109     }
27110 #if SQLITE_MAX_MMAP_SIZE>0
27111     case SQLITE_FCNTL_MMAP_SIZE: {
27112       i64 newLimit = *(i64*)pArg;
27113       int rc = SQLITE_OK;
27114       if( newLimit>sqlite3GlobalConfig.mxMmap ){
27115         newLimit = sqlite3GlobalConfig.mxMmap;
27116       }
27117       *(i64*)pArg = pFile->mmapSizeMax;
27118       if( newLimit>=0 && newLimit!=pFile->mmapSizeMax && pFile->nFetchOut==0 ){
27119         pFile->mmapSizeMax = newLimit;
27120         if( pFile->mmapSize>0 ){
27121           unixUnmapfile(pFile);
27122           rc = unixMapfile(pFile, -1);
27123         }
27124       }
27125       return rc;
27126     }
27127 #endif
27128 #ifdef SQLITE_DEBUG
27129     /* The pager calls this method to signal that it has done
27130     ** a rollback and that the database is therefore unchanged and
27131     ** it hence it is OK for the transaction change counter to be
27132     ** unchanged.
27133     */
27134     case SQLITE_FCNTL_DB_UNCHANGED: {
27135       ((unixFile*)id)->dbUpdate = 0;
27136       return SQLITE_OK;
27137     }
27138 #endif
27139 #if SQLITE_ENABLE_LOCKING_STYLE && defined(__APPLE__)
27140     case SQLITE_SET_LOCKPROXYFILE:
27141     case SQLITE_GET_LOCKPROXYFILE: {
27142       return proxyFileControl(id,op,pArg);
27143     }
27144 #endif /* SQLITE_ENABLE_LOCKING_STYLE && defined(__APPLE__) */
27145   }
27146   return SQLITE_NOTFOUND;
27147 }
27148 
27149 /*
27150 ** Return the sector size in bytes of the underlying block device for
27151 ** the specified file. This is almost always 512 bytes, but may be
27152 ** larger for some devices.
27153 **
27154 ** SQLite code assumes this function cannot fail. It also assumes that
27155 ** if two files are created in the same file-system directory (i.e.
27156 ** a database and its journal file) that the sector size will be the
27157 ** same for both.
27158 */
27159 #ifndef __QNXNTO__ 
27160 static int unixSectorSize(sqlite3_file *NotUsed){
27161   UNUSED_PARAMETER(NotUsed);
27162   return SQLITE_DEFAULT_SECTOR_SIZE;
27163 }
27164 #endif
27165 
27166 /*
27167 ** The following version of unixSectorSize() is optimized for QNX.
27168 */
27169 #ifdef __QNXNTO__
27170 #include <sys/dcmd_blk.h>
27171 #include <sys/statvfs.h>
27172 static int unixSectorSize(sqlite3_file *id){
27173   unixFile *pFile = (unixFile*)id;
27174   if( pFile->sectorSize == 0 ){
27175     struct statvfs fsInfo;
27176        
27177     /* Set defaults for non-supported filesystems */
27178     pFile->sectorSize = SQLITE_DEFAULT_SECTOR_SIZE;
27179     pFile->deviceCharacteristics = 0;
27180     if( fstatvfs(pFile->h, &fsInfo) == -1 ) {
27181       return pFile->sectorSize;
27182     }
27183 
27184     if( !strcmp(fsInfo.f_basetype, "tmp") ) {
27185       pFile->sectorSize = fsInfo.f_bsize;
27186       pFile->deviceCharacteristics =
27187         SQLITE_IOCAP_ATOMIC4K |       /* All ram filesystem writes are atomic */
27188         SQLITE_IOCAP_SAFE_APPEND |    /* growing the file does not occur until
27189                                       ** the write succeeds */
27190         SQLITE_IOCAP_SEQUENTIAL |     /* The ram filesystem has no write behind
27191                                       ** so it is ordered */
27192         0;
27193     }else if( strstr(fsInfo.f_basetype, "etfs") ){
27194       pFile->sectorSize = fsInfo.f_bsize;
27195       pFile->deviceCharacteristics =
27196         /* etfs cluster size writes are atomic */
27197         (pFile->sectorSize / 512 * SQLITE_IOCAP_ATOMIC512) |
27198         SQLITE_IOCAP_SAFE_APPEND |    /* growing the file does not occur until
27199                                       ** the write succeeds */
27200         SQLITE_IOCAP_SEQUENTIAL |     /* The ram filesystem has no write behind
27201                                       ** so it is ordered */
27202         0;
27203     }else if( !strcmp(fsInfo.f_basetype, "qnx6") ){
27204       pFile->sectorSize = fsInfo.f_bsize;
27205       pFile->deviceCharacteristics =
27206         SQLITE_IOCAP_ATOMIC |         /* All filesystem writes are atomic */
27207         SQLITE_IOCAP_SAFE_APPEND |    /* growing the file does not occur until
27208                                       ** the write succeeds */
27209         SQLITE_IOCAP_SEQUENTIAL |     /* The ram filesystem has no write behind
27210                                       ** so it is ordered */
27211         0;
27212     }else if( !strcmp(fsInfo.f_basetype, "qnx4") ){
27213       pFile->sectorSize = fsInfo.f_bsize;
27214       pFile->deviceCharacteristics =
27215         /* full bitset of atomics from max sector size and smaller */
27216         ((pFile->sectorSize / 512 * SQLITE_IOCAP_ATOMIC512) << 1) - 2 |
27217         SQLITE_IOCAP_SEQUENTIAL |     /* The ram filesystem has no write behind
27218                                       ** so it is ordered */
27219         0;
27220     }else if( strstr(fsInfo.f_basetype, "dos") ){
27221       pFile->sectorSize = fsInfo.f_bsize;
27222       pFile->deviceCharacteristics =
27223         /* full bitset of atomics from max sector size and smaller */
27224         ((pFile->sectorSize / 512 * SQLITE_IOCAP_ATOMIC512) << 1) - 2 |
27225         SQLITE_IOCAP_SEQUENTIAL |     /* The ram filesystem has no write behind
27226                                       ** so it is ordered */
27227         0;
27228     }else{
27229       pFile->deviceCharacteristics =
27230         SQLITE_IOCAP_ATOMIC512 |      /* blocks are atomic */
27231         SQLITE_IOCAP_SAFE_APPEND |    /* growing the file does not occur until
27232                                       ** the write succeeds */
27233         0;
27234     }
27235   }
27236   /* Last chance verification.  If the sector size isn't a multiple of 512
27237   ** then it isn't valid.*/
27238   if( pFile->sectorSize % 512 != 0 ){
27239     pFile->deviceCharacteristics = 0;
27240     pFile->sectorSize = SQLITE_DEFAULT_SECTOR_SIZE;
27241   }
27242   return pFile->sectorSize;
27243 }
27244 #endif /* __QNXNTO__ */
27245 
27246 /*
27247 ** Return the device characteristics for the file.
27248 **
27249 ** This VFS is set up to return SQLITE_IOCAP_POWERSAFE_OVERWRITE by default.
27250 ** However, that choice is contraversial since technically the underlying
27251 ** file system does not always provide powersafe overwrites.  (In other
27252 ** words, after a power-loss event, parts of the file that were never
27253 ** written might end up being altered.)  However, non-PSOW behavior is very,
27254 ** very rare.  And asserting PSOW makes a large reduction in the amount
27255 ** of required I/O for journaling, since a lot of padding is eliminated.
27256 **  Hence, while POWERSAFE_OVERWRITE is on by default, there is a file-control
27257 ** available to turn it off and URI query parameter available to turn it off.
27258 */
27259 static int unixDeviceCharacteristics(sqlite3_file *id){
27260   unixFile *p = (unixFile*)id;
27261   int rc = 0;
27262 #ifdef __QNXNTO__
27263   if( p->sectorSize==0 ) unixSectorSize(id);
27264   rc = p->deviceCharacteristics;
27265 #endif
27266   if( p->ctrlFlags & UNIXFILE_PSOW ){
27267     rc |= SQLITE_IOCAP_POWERSAFE_OVERWRITE;
27268   }
27269   return rc;
27270 }
27271 
27272 #ifndef SQLITE_OMIT_WAL
27273 
27274 
27275 /*
27276 ** Object used to represent an shared memory buffer.  
27277 **
27278 ** When multiple threads all reference the same wal-index, each thread
27279 ** has its own unixShm object, but they all point to a single instance
27280 ** of this unixShmNode object.  In other words, each wal-index is opened
27281 ** only once per process.
27282 **
27283 ** Each unixShmNode object is connected to a single unixInodeInfo object.
27284 ** We could coalesce this object into unixInodeInfo, but that would mean
27285 ** every open file that does not use shared memory (in other words, most
27286 ** open files) would have to carry around this extra information.  So
27287 ** the unixInodeInfo object contains a pointer to this unixShmNode object
27288 ** and the unixShmNode object is created only when needed.
27289 **
27290 ** unixMutexHeld() must be true when creating or destroying
27291 ** this object or while reading or writing the following fields:
27292 **
27293 **      nRef
27294 **
27295 ** The following fields are read-only after the object is created:
27296 ** 
27297 **      fid
27298 **      zFilename
27299 **
27300 ** Either unixShmNode.mutex must be held or unixShmNode.nRef==0 and
27301 ** unixMutexHeld() is true when reading or writing any other field
27302 ** in this structure.
27303 */
27304 struct unixShmNode {
27305   unixInodeInfo *pInode;     /* unixInodeInfo that owns this SHM node */
27306   sqlite3_mutex *mutex;      /* Mutex to access this object */
27307   char *zFilename;           /* Name of the mmapped file */
27308   int h;                     /* Open file descriptor */
27309   int szRegion;              /* Size of shared-memory regions */
27310   u16 nRegion;               /* Size of array apRegion */
27311   u8 isReadonly;             /* True if read-only */
27312   char **apRegion;           /* Array of mapped shared-memory regions */
27313   int nRef;                  /* Number of unixShm objects pointing to this */
27314   unixShm *pFirst;           /* All unixShm objects pointing to this */
27315 #ifdef SQLITE_DEBUG
27316   u8 exclMask;               /* Mask of exclusive locks held */
27317   u8 sharedMask;             /* Mask of shared locks held */
27318   u8 nextShmId;              /* Next available unixShm.id value */
27319 #endif
27320 };
27321 
27322 /*
27323 ** Structure used internally by this VFS to record the state of an
27324 ** open shared memory connection.
27325 **
27326 ** The following fields are initialized when this object is created and
27327 ** are read-only thereafter:
27328 **
27329 **    unixShm.pFile
27330 **    unixShm.id
27331 **
27332 ** All other fields are read/write.  The unixShm.pFile->mutex must be held
27333 ** while accessing any read/write fields.
27334 */
27335 struct unixShm {
27336   unixShmNode *pShmNode;     /* The underlying unixShmNode object */
27337   unixShm *pNext;            /* Next unixShm with the same unixShmNode */
27338   u8 hasMutex;               /* True if holding the unixShmNode mutex */
27339   u8 id;                     /* Id of this connection within its unixShmNode */
27340   u16 sharedMask;            /* Mask of shared locks held */
27341   u16 exclMask;              /* Mask of exclusive locks held */
27342 };
27343 
27344 /*
27345 ** Constants used for locking
27346 */
27347 #define UNIX_SHM_BASE   ((22+SQLITE_SHM_NLOCK)*4)         /* first lock byte */
27348 #define UNIX_SHM_DMS    (UNIX_SHM_BASE+SQLITE_SHM_NLOCK)  /* deadman switch */
27349 
27350 /*
27351 ** Apply posix advisory locks for all bytes from ofst through ofst+n-1.
27352 **
27353 ** Locks block if the mask is exactly UNIX_SHM_C and are non-blocking
27354 ** otherwise.
27355 */
27356 static int unixShmSystemLock(
27357   unixShmNode *pShmNode, /* Apply locks to this open shared-memory segment */
27358   int lockType,          /* F_UNLCK, F_RDLCK, or F_WRLCK */
27359   int ofst,              /* First byte of the locking range */
27360   int n                  /* Number of bytes to lock */
27361 ){
27362   struct flock f;       /* The posix advisory locking structure */
27363   int rc = SQLITE_OK;   /* Result code form fcntl() */
27364 
27365   /* Access to the unixShmNode object is serialized by the caller */
27366   assert( sqlite3_mutex_held(pShmNode->mutex) || pShmNode->nRef==0 );
27367 
27368   /* Shared locks never span more than one byte */
27369   assert( n==1 || lockType!=F_RDLCK );
27370 
27371   /* Locks are within range */
27372   assert( n>=1 && n<SQLITE_SHM_NLOCK );
27373 
27374   if( pShmNode->h>=0 ){
27375     /* Initialize the locking parameters */
27376     memset(&f, 0, sizeof(f));
27377     f.l_type = lockType;
27378     f.l_whence = SEEK_SET;
27379     f.l_start = ofst;
27380     f.l_len = n;
27381 
27382     rc = osFcntl(pShmNode->h, F_SETLK, &f);
27383     rc = (rc!=(-1)) ? SQLITE_OK : SQLITE_BUSY;
27384   }
27385 
27386   /* Update the global lock state and do debug tracing */
27387 #ifdef SQLITE_DEBUG
27388   { u16 mask;
27389   OSTRACE(("SHM-LOCK "));
27390   mask = ofst>31 ? 0xffffffff : (1<<(ofst+n)) - (1<<ofst);
27391   if( rc==SQLITE_OK ){
27392     if( lockType==F_UNLCK ){
27393       OSTRACE(("unlock %d ok", ofst));
27394       pShmNode->exclMask &= ~mask;
27395       pShmNode->sharedMask &= ~mask;
27396     }else if( lockType==F_RDLCK ){
27397       OSTRACE(("read-lock %d ok", ofst));
27398       pShmNode->exclMask &= ~mask;
27399       pShmNode->sharedMask |= mask;
27400     }else{
27401       assert( lockType==F_WRLCK );
27402       OSTRACE(("write-lock %d ok", ofst));
27403       pShmNode->exclMask |= mask;
27404       pShmNode->sharedMask &= ~mask;
27405     }
27406   }else{
27407     if( lockType==F_UNLCK ){
27408       OSTRACE(("unlock %d failed", ofst));
27409     }else if( lockType==F_RDLCK ){
27410       OSTRACE(("read-lock failed"));
27411     }else{
27412       assert( lockType==F_WRLCK );
27413       OSTRACE(("write-lock %d failed", ofst));
27414     }
27415   }
27416   OSTRACE((" - afterwards %03x,%03x\n",
27417            pShmNode->sharedMask, pShmNode->exclMask));
27418   }
27419 #endif
27420 
27421   return rc;        
27422 }
27423 
27424 
27425 /*
27426 ** Purge the unixShmNodeList list of all entries with unixShmNode.nRef==0.
27427 **
27428 ** This is not a VFS shared-memory method; it is a utility function called
27429 ** by VFS shared-memory methods.
27430 */
27431 static void unixShmPurge(unixFile *pFd){
27432   unixShmNode *p = pFd->pInode->pShmNode;
27433   assert( unixMutexHeld() );
27434   if( p && p->nRef==0 ){
27435     int i;
27436     assert( p->pInode==pFd->pInode );
27437     sqlite3_mutex_free(p->mutex);
27438     for(i=0; i<p->nRegion; i++){
27439       if( p->h>=0 ){
27440         osMunmap(p->apRegion[i], p->szRegion);
27441       }else{
27442         sqlite3_free(p->apRegion[i]);
27443       }
27444     }
27445     sqlite3_free(p->apRegion);
27446     if( p->h>=0 ){
27447       robust_close(pFd, p->h, __LINE__);
27448       p->h = -1;
27449     }
27450     p->pInode->pShmNode = 0;
27451     sqlite3_free(p);
27452   }
27453 }
27454 
27455 /*
27456 ** Open a shared-memory area associated with open database file pDbFd.  
27457 ** This particular implementation uses mmapped files.
27458 **
27459 ** The file used to implement shared-memory is in the same directory
27460 ** as the open database file and has the same name as the open database
27461 ** file with the "-shm" suffix added.  For example, if the database file
27462 ** is "/home/user1/config.db" then the file that is created and mmapped
27463 ** for shared memory will be called "/home/user1/config.db-shm".  
27464 **
27465 ** Another approach to is to use files in /dev/shm or /dev/tmp or an
27466 ** some other tmpfs mount. But if a file in a different directory
27467 ** from the database file is used, then differing access permissions
27468 ** or a chroot() might cause two different processes on the same
27469 ** database to end up using different files for shared memory - 
27470 ** meaning that their memory would not really be shared - resulting
27471 ** in database corruption.  Nevertheless, this tmpfs file usage
27472 ** can be enabled at compile-time using -DSQLITE_SHM_DIRECTORY="/dev/shm"
27473 ** or the equivalent.  The use of the SQLITE_SHM_DIRECTORY compile-time
27474 ** option results in an incompatible build of SQLite;  builds of SQLite
27475 ** that with differing SQLITE_SHM_DIRECTORY settings attempt to use the
27476 ** same database file at the same time, database corruption will likely
27477 ** result. The SQLITE_SHM_DIRECTORY compile-time option is considered
27478 ** "unsupported" and may go away in a future SQLite release.
27479 **
27480 ** When opening a new shared-memory file, if no other instances of that
27481 ** file are currently open, in this process or in other processes, then
27482 ** the file must be truncated to zero length or have its header cleared.
27483 **
27484 ** If the original database file (pDbFd) is using the "unix-excl" VFS
27485 ** that means that an exclusive lock is held on the database file and
27486 ** that no other processes are able to read or write the database.  In
27487 ** that case, we do not really need shared memory.  No shared memory
27488 ** file is created.  The shared memory will be simulated with heap memory.
27489 */
27490 static int unixOpenSharedMemory(unixFile *pDbFd){
27491   struct unixShm *p = 0;          /* The connection to be opened */
27492   struct unixShmNode *pShmNode;   /* The underlying mmapped file */
27493   int rc;                         /* Result code */
27494   unixInodeInfo *pInode;          /* The inode of fd */
27495   char *zShmFilename;             /* Name of the file used for SHM */
27496   int nShmFilename;               /* Size of the SHM filename in bytes */
27497 
27498   /* Allocate space for the new unixShm object. */
27499   p = sqlite3_malloc( sizeof(*p) );
27500   if( p==0 ) return SQLITE_NOMEM;
27501   memset(p, 0, sizeof(*p));
27502   assert( pDbFd->pShm==0 );
27503 
27504   /* Check to see if a unixShmNode object already exists. Reuse an existing
27505   ** one if present. Create a new one if necessary.
27506   */
27507   unixEnterMutex();
27508   pInode = pDbFd->pInode;
27509   pShmNode = pInode->pShmNode;
27510   if( pShmNode==0 ){
27511     struct stat sStat;                 /* fstat() info for database file */
27512 
27513     /* Call fstat() to figure out the permissions on the database file. If
27514     ** a new *-shm file is created, an attempt will be made to create it
27515     ** with the same permissions.
27516     */
27517     if( osFstat(pDbFd->h, &sStat) && pInode->bProcessLock==0 ){
27518       rc = SQLITE_IOERR_FSTAT;
27519       goto shm_open_err;
27520     }
27521 
27522 #ifdef SQLITE_SHM_DIRECTORY
27523     nShmFilename = sizeof(SQLITE_SHM_DIRECTORY) + 31;
27524 #else
27525     nShmFilename = 6 + (int)strlen(pDbFd->zPath);
27526 #endif
27527     pShmNode = sqlite3_malloc( sizeof(*pShmNode) + nShmFilename );
27528     if( pShmNode==0 ){
27529       rc = SQLITE_NOMEM;
27530       goto shm_open_err;
27531     }
27532     memset(pShmNode, 0, sizeof(*pShmNode)+nShmFilename);
27533     zShmFilename = pShmNode->zFilename = (char*)&pShmNode[1];
27534 #ifdef SQLITE_SHM_DIRECTORY
27535     sqlite3_snprintf(nShmFilename, zShmFilename, 
27536                      SQLITE_SHM_DIRECTORY "/sqlite-shm-%x-%x",
27537                      (u32)sStat.st_ino, (u32)sStat.st_dev);
27538 #else
27539     sqlite3_snprintf(nShmFilename, zShmFilename, "%s-shm", pDbFd->zPath);
27540     sqlite3FileSuffix3(pDbFd->zPath, zShmFilename);
27541 #endif
27542     pShmNode->h = -1;
27543     pDbFd->pInode->pShmNode = pShmNode;
27544     pShmNode->pInode = pDbFd->pInode;
27545     pShmNode->mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_FAST);
27546     if( pShmNode->mutex==0 ){
27547       rc = SQLITE_NOMEM;
27548       goto shm_open_err;
27549     }
27550 
27551     if( pInode->bProcessLock==0 ){
27552       int openFlags = O_RDWR | O_CREAT;
27553       if( sqlite3_uri_boolean(pDbFd->zPath, "readonly_shm", 0) ){
27554         openFlags = O_RDONLY;
27555         pShmNode->isReadonly = 1;
27556       }
27557       pShmNode->h = robust_open(zShmFilename, openFlags, (sStat.st_mode&0777));
27558       if( pShmNode->h<0 ){
27559         rc = unixLogError(SQLITE_CANTOPEN_BKPT, "open", zShmFilename);
27560         goto shm_open_err;
27561       }
27562 
27563       /* If this process is running as root, make sure that the SHM file
27564       ** is owned by the same user that owns the original database.  Otherwise,
27565       ** the original owner will not be able to connect.
27566       */
27567       osFchown(pShmNode->h, sStat.st_uid, sStat.st_gid);
27568   
27569       /* Check to see if another process is holding the dead-man switch.
27570       ** If not, truncate the file to zero length. 
27571       */
27572       rc = SQLITE_OK;
27573       if( unixShmSystemLock(pShmNode, F_WRLCK, UNIX_SHM_DMS, 1)==SQLITE_OK ){
27574         if( robust_ftruncate(pShmNode->h, 0) ){
27575           rc = unixLogError(SQLITE_IOERR_SHMOPEN, "ftruncate", zShmFilename);
27576         }
27577       }
27578       if( rc==SQLITE_OK ){
27579         rc = unixShmSystemLock(pShmNode, F_RDLCK, UNIX_SHM_DMS, 1);
27580       }
27581       if( rc ) goto shm_open_err;
27582     }
27583   }
27584 
27585   /* Make the new connection a child of the unixShmNode */
27586   p->pShmNode = pShmNode;
27587 #ifdef SQLITE_DEBUG
27588   p->id = pShmNode->nextShmId++;
27589 #endif
27590   pShmNode->nRef++;
27591   pDbFd->pShm = p;
27592   unixLeaveMutex();
27593 
27594   /* The reference count on pShmNode has already been incremented under
27595   ** the cover of the unixEnterMutex() mutex and the pointer from the
27596   ** new (struct unixShm) object to the pShmNode has been set. All that is
27597   ** left to do is to link the new object into the linked list starting
27598   ** at pShmNode->pFirst. This must be done while holding the pShmNode->mutex 
27599   ** mutex.
27600   */
27601   sqlite3_mutex_enter(pShmNode->mutex);
27602   p->pNext = pShmNode->pFirst;
27603   pShmNode->pFirst = p;
27604   sqlite3_mutex_leave(pShmNode->mutex);
27605   return SQLITE_OK;
27606 
27607   /* Jump here on any error */
27608 shm_open_err:
27609   unixShmPurge(pDbFd);       /* This call frees pShmNode if required */
27610   sqlite3_free(p);
27611   unixLeaveMutex();
27612   return rc;
27613 }
27614 
27615 /*
27616 ** This function is called to obtain a pointer to region iRegion of the 
27617 ** shared-memory associated with the database file fd. Shared-memory regions 
27618 ** are numbered starting from zero. Each shared-memory region is szRegion 
27619 ** bytes in size.
27620 **
27621 ** If an error occurs, an error code is returned and *pp is set to NULL.
27622 **
27623 ** Otherwise, if the bExtend parameter is 0 and the requested shared-memory
27624 ** region has not been allocated (by any client, including one running in a
27625 ** separate process), then *pp is set to NULL and SQLITE_OK returned. If 
27626 ** bExtend is non-zero and the requested shared-memory region has not yet 
27627 ** been allocated, it is allocated by this function.
27628 **
27629 ** If the shared-memory region has already been allocated or is allocated by
27630 ** this call as described above, then it is mapped into this processes 
27631 ** address space (if it is not already), *pp is set to point to the mapped 
27632 ** memory and SQLITE_OK returned.
27633 */
27634 static int unixShmMap(
27635   sqlite3_file *fd,               /* Handle open on database file */
27636   int iRegion,                    /* Region to retrieve */
27637   int szRegion,                   /* Size of regions */
27638   int bExtend,                    /* True to extend file if necessary */
27639   void volatile **pp              /* OUT: Mapped memory */
27640 ){
27641   unixFile *pDbFd = (unixFile*)fd;
27642   unixShm *p;
27643   unixShmNode *pShmNode;
27644   int rc = SQLITE_OK;
27645 
27646   /* If the shared-memory file has not yet been opened, open it now. */
27647   if( pDbFd->pShm==0 ){
27648     rc = unixOpenSharedMemory(pDbFd);
27649     if( rc!=SQLITE_OK ) return rc;
27650   }
27651 
27652   p = pDbFd->pShm;
27653   pShmNode = p->pShmNode;
27654   sqlite3_mutex_enter(pShmNode->mutex);
27655   assert( szRegion==pShmNode->szRegion || pShmNode->nRegion==0 );
27656   assert( pShmNode->pInode==pDbFd->pInode );
27657   assert( pShmNode->h>=0 || pDbFd->pInode->bProcessLock==1 );
27658   assert( pShmNode->h<0 || pDbFd->pInode->bProcessLock==0 );
27659 
27660   if( pShmNode->nRegion<=iRegion ){
27661     char **apNew;                      /* New apRegion[] array */
27662     int nByte = (iRegion+1)*szRegion;  /* Minimum required file size */
27663     struct stat sStat;                 /* Used by fstat() */
27664 
27665     pShmNode->szRegion = szRegion;
27666 
27667     if( pShmNode->h>=0 ){
27668       /* The requested region is not mapped into this processes address space.
27669       ** Check to see if it has been allocated (i.e. if the wal-index file is
27670       ** large enough to contain the requested region).
27671       */
27672       if( osFstat(pShmNode->h, &sStat) ){
27673         rc = SQLITE_IOERR_SHMSIZE;
27674         goto shmpage_out;
27675       }
27676   
27677       if( sStat.st_size<nByte ){
27678         /* The requested memory region does not exist. If bExtend is set to
27679         ** false, exit early. *pp will be set to NULL and SQLITE_OK returned.
27680         */
27681         if( !bExtend ){
27682           goto shmpage_out;
27683         }
27684 
27685         /* Alternatively, if bExtend is true, extend the file. Do this by
27686         ** writing a single byte to the end of each (OS) page being
27687         ** allocated or extended. Technically, we need only write to the
27688         ** last page in order to extend the file. But writing to all new
27689         ** pages forces the OS to allocate them immediately, which reduces
27690         ** the chances of SIGBUS while accessing the mapped region later on.
27691         */
27692         else{
27693           static const int pgsz = 4096;
27694           int iPg;
27695 
27696           /* Write to the last byte of each newly allocated or extended page */
27697           assert( (nByte % pgsz)==0 );
27698           for(iPg=(sStat.st_size/pgsz); iPg<(nByte/pgsz); iPg++){
27699             if( seekAndWriteFd(pShmNode->h, iPg*pgsz + pgsz-1, "", 1, 0)!=1 ){
27700               const char *zFile = pShmNode->zFilename;
27701               rc = unixLogError(SQLITE_IOERR_SHMSIZE, "write", zFile);
27702               goto shmpage_out;
27703             }
27704           }
27705         }
27706       }
27707     }
27708 
27709     /* Map the requested memory region into this processes address space. */
27710     apNew = (char **)sqlite3_realloc(
27711         pShmNode->apRegion, (iRegion+1)*sizeof(char *)
27712     );
27713     if( !apNew ){
27714       rc = SQLITE_IOERR_NOMEM;
27715       goto shmpage_out;
27716     }
27717     pShmNode->apRegion = apNew;
27718     while(pShmNode->nRegion<=iRegion){
27719       void *pMem;
27720       if( pShmNode->h>=0 ){
27721         pMem = osMmap(0, szRegion,
27722             pShmNode->isReadonly ? PROT_READ : PROT_READ|PROT_WRITE, 
27723             MAP_SHARED, pShmNode->h, szRegion*(i64)pShmNode->nRegion
27724         );
27725         if( pMem==MAP_FAILED ){
27726           rc = unixLogError(SQLITE_IOERR_SHMMAP, "mmap", pShmNode->zFilename);
27727           goto shmpage_out;
27728         }
27729       }else{
27730         pMem = sqlite3_malloc(szRegion);
27731         if( pMem==0 ){
27732           rc = SQLITE_NOMEM;
27733           goto shmpage_out;
27734         }
27735         memset(pMem, 0, szRegion);
27736       }
27737       pShmNode->apRegion[pShmNode->nRegion] = pMem;
27738       pShmNode->nRegion++;
27739     }
27740   }
27741 
27742 shmpage_out:
27743   if( pShmNode->nRegion>iRegion ){
27744     *pp = pShmNode->apRegion[iRegion];
27745   }else{
27746     *pp = 0;
27747   }
27748   if( pShmNode->isReadonly && rc==SQLITE_OK ) rc = SQLITE_READONLY;
27749   sqlite3_mutex_leave(pShmNode->mutex);
27750   return rc;
27751 }
27752 
27753 /*
27754 ** Change the lock state for a shared-memory segment.
27755 **
27756 ** Note that the relationship between SHAREd and EXCLUSIVE locks is a little
27757 ** different here than in posix.  In xShmLock(), one can go from unlocked
27758 ** to shared and back or from unlocked to exclusive and back.  But one may
27759 ** not go from shared to exclusive or from exclusive to shared.
27760 */
27761 static int unixShmLock(
27762   sqlite3_file *fd,          /* Database file holding the shared memory */
27763   int ofst,                  /* First lock to acquire or release */
27764   int n,                     /* Number of locks to acquire or release */
27765   int flags                  /* What to do with the lock */
27766 ){
27767   unixFile *pDbFd = (unixFile*)fd;      /* Connection holding shared memory */
27768   unixShm *p = pDbFd->pShm;             /* The shared memory being locked */
27769   unixShm *pX;                          /* For looping over all siblings */
27770   unixShmNode *pShmNode = p->pShmNode;  /* The underlying file iNode */
27771   int rc = SQLITE_OK;                   /* Result code */
27772   u16 mask;                             /* Mask of locks to take or release */
27773 
27774   assert( pShmNode==pDbFd->pInode->pShmNode );
27775   assert( pShmNode->pInode==pDbFd->pInode );
27776   assert( ofst>=0 && ofst+n<=SQLITE_SHM_NLOCK );
27777   assert( n>=1 );
27778   assert( flags==(SQLITE_SHM_LOCK | SQLITE_SHM_SHARED)
27779        || flags==(SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE)
27780        || flags==(SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED)
27781        || flags==(SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE) );
27782   assert( n==1 || (flags & SQLITE_SHM_EXCLUSIVE)!=0 );
27783   assert( pShmNode->h>=0 || pDbFd->pInode->bProcessLock==1 );
27784   assert( pShmNode->h<0 || pDbFd->pInode->bProcessLock==0 );
27785 
27786   mask = (1<<(ofst+n)) - (1<<ofst);
27787   assert( n>1 || mask==(1<<ofst) );
27788   sqlite3_mutex_enter(pShmNode->mutex);
27789   if( flags & SQLITE_SHM_UNLOCK ){
27790     u16 allMask = 0; /* Mask of locks held by siblings */
27791 
27792     /* See if any siblings hold this same lock */
27793     for(pX=pShmNode->pFirst; pX; pX=pX->pNext){
27794       if( pX==p ) continue;
27795       assert( (pX->exclMask & (p->exclMask|p->sharedMask))==0 );
27796       allMask |= pX->sharedMask;
27797     }
27798 
27799     /* Unlock the system-level locks */
27800     if( (mask & allMask)==0 ){
27801       rc = unixShmSystemLock(pShmNode, F_UNLCK, ofst+UNIX_SHM_BASE, n);
27802     }else{
27803       rc = SQLITE_OK;
27804     }
27805 
27806     /* Undo the local locks */
27807     if( rc==SQLITE_OK ){
27808       p->exclMask &= ~mask;
27809       p->sharedMask &= ~mask;
27810     } 
27811   }else if( flags & SQLITE_SHM_SHARED ){
27812     u16 allShared = 0;  /* Union of locks held by connections other than "p" */
27813 
27814     /* Find out which shared locks are already held by sibling connections.
27815     ** If any sibling already holds an exclusive lock, go ahead and return
27816     ** SQLITE_BUSY.
27817     */
27818     for(pX=pShmNode->pFirst; pX; pX=pX->pNext){
27819       if( (pX->exclMask & mask)!=0 ){
27820         rc = SQLITE_BUSY;
27821         break;
27822       }
27823       allShared |= pX->sharedMask;
27824     }
27825 
27826     /* Get shared locks at the system level, if necessary */
27827     if( rc==SQLITE_OK ){
27828       if( (allShared & mask)==0 ){
27829         rc = unixShmSystemLock(pShmNode, F_RDLCK, ofst+UNIX_SHM_BASE, n);
27830       }else{
27831         rc = SQLITE_OK;
27832       }
27833     }
27834 
27835     /* Get the local shared locks */
27836     if( rc==SQLITE_OK ){
27837       p->sharedMask |= mask;
27838     }
27839   }else{
27840     /* Make sure no sibling connections hold locks that will block this
27841     ** lock.  If any do, return SQLITE_BUSY right away.
27842     */
27843     for(pX=pShmNode->pFirst; pX; pX=pX->pNext){
27844       if( (pX->exclMask & mask)!=0 || (pX->sharedMask & mask)!=0 ){
27845         rc = SQLITE_BUSY;
27846         break;
27847       }
27848     }
27849   
27850     /* Get the exclusive locks at the system level.  Then if successful
27851     ** also mark the local connection as being locked.
27852     */
27853     if( rc==SQLITE_OK ){
27854       rc = unixShmSystemLock(pShmNode, F_WRLCK, ofst+UNIX_SHM_BASE, n);
27855       if( rc==SQLITE_OK ){
27856         assert( (p->sharedMask & mask)==0 );
27857         p->exclMask |= mask;
27858       }
27859     }
27860   }
27861   sqlite3_mutex_leave(pShmNode->mutex);
27862   OSTRACE(("SHM-LOCK shmid-%d, pid-%d got %03x,%03x\n",
27863            p->id, getpid(), p->sharedMask, p->exclMask));
27864   return rc;
27865 }
27866 
27867 /*
27868 ** Implement a memory barrier or memory fence on shared memory.  
27869 **
27870 ** All loads and stores begun before the barrier must complete before
27871 ** any load or store begun after the barrier.
27872 */
27873 static void unixShmBarrier(
27874   sqlite3_file *fd                /* Database file holding the shared memory */
27875 ){
27876   UNUSED_PARAMETER(fd);
27877   unixEnterMutex();
27878   unixLeaveMutex();
27879 }
27880 
27881 /*
27882 ** Close a connection to shared-memory.  Delete the underlying 
27883 ** storage if deleteFlag is true.
27884 **
27885 ** If there is no shared memory associated with the connection then this
27886 ** routine is a harmless no-op.
27887 */
27888 static int unixShmUnmap(
27889   sqlite3_file *fd,               /* The underlying database file */
27890   int deleteFlag                  /* Delete shared-memory if true */
27891 ){
27892   unixShm *p;                     /* The connection to be closed */
27893   unixShmNode *pShmNode;          /* The underlying shared-memory file */
27894   unixShm **pp;                   /* For looping over sibling connections */
27895   unixFile *pDbFd;                /* The underlying database file */
27896 
27897   pDbFd = (unixFile*)fd;
27898   p = pDbFd->pShm;
27899   if( p==0 ) return SQLITE_OK;
27900   pShmNode = p->pShmNode;
27901 
27902   assert( pShmNode==pDbFd->pInode->pShmNode );
27903   assert( pShmNode->pInode==pDbFd->pInode );
27904 
27905   /* Remove connection p from the set of connections associated
27906   ** with pShmNode */
27907   sqlite3_mutex_enter(pShmNode->mutex);
27908   for(pp=&pShmNode->pFirst; (*pp)!=p; pp = &(*pp)->pNext){}
27909   *pp = p->pNext;
27910 
27911   /* Free the connection p */
27912   sqlite3_free(p);
27913   pDbFd->pShm = 0;
27914   sqlite3_mutex_leave(pShmNode->mutex);
27915 
27916   /* If pShmNode->nRef has reached 0, then close the underlying
27917   ** shared-memory file, too */
27918   unixEnterMutex();
27919   assert( pShmNode->nRef>0 );
27920   pShmNode->nRef--;
27921   if( pShmNode->nRef==0 ){
27922     if( deleteFlag && pShmNode->h>=0 ) osUnlink(pShmNode->zFilename);
27923     unixShmPurge(pDbFd);
27924   }
27925   unixLeaveMutex();
27926 
27927   return SQLITE_OK;
27928 }
27929 
27930 
27931 #else
27932 # define unixShmMap     0
27933 # define unixShmLock    0
27934 # define unixShmBarrier 0
27935 # define unixShmUnmap   0
27936 #endif /* #ifndef SQLITE_OMIT_WAL */
27937 
27938 #if SQLITE_MAX_MMAP_SIZE>0
27939 /*
27940 ** If it is currently memory mapped, unmap file pFd.
27941 */
27942 static void unixUnmapfile(unixFile *pFd){
27943   assert( pFd->nFetchOut==0 );
27944   if( pFd->pMapRegion ){
27945     osMunmap(pFd->pMapRegion, pFd->mmapSizeActual);
27946     pFd->pMapRegion = 0;
27947     pFd->mmapSize = 0;
27948     pFd->mmapSizeActual = 0;
27949   }
27950 }
27951 
27952 /*
27953 ** Return the system page size.
27954 */
27955 static int unixGetPagesize(void){
27956 #if HAVE_MREMAP
27957   return 512;
27958 #elif defined(_BSD_SOURCE)
27959   return getpagesize();
27960 #else
27961   return (int)sysconf(_SC_PAGESIZE);
27962 #endif
27963 }
27964 
27965 /*
27966 ** Attempt to set the size of the memory mapping maintained by file 
27967 ** descriptor pFd to nNew bytes. Any existing mapping is discarded.
27968 **
27969 ** If successful, this function sets the following variables:
27970 **
27971 **       unixFile.pMapRegion
27972 **       unixFile.mmapSize
27973 **       unixFile.mmapSizeActual
27974 **
27975 ** If unsuccessful, an error message is logged via sqlite3_log() and
27976 ** the three variables above are zeroed. In this case SQLite should
27977 ** continue accessing the database using the xRead() and xWrite()
27978 ** methods.
27979 */
27980 static void unixRemapfile(
27981   unixFile *pFd,                  /* File descriptor object */
27982   i64 nNew                        /* Required mapping size */
27983 ){
27984   const char *zErr = "mmap";
27985   int h = pFd->h;                      /* File descriptor open on db file */
27986   u8 *pOrig = (u8 *)pFd->pMapRegion;   /* Pointer to current file mapping */
27987   i64 nOrig = pFd->mmapSizeActual;     /* Size of pOrig region in bytes */
27988   u8 *pNew = 0;                        /* Location of new mapping */
27989   int flags = PROT_READ;               /* Flags to pass to mmap() */
27990 
27991   assert( pFd->nFetchOut==0 );
27992   assert( nNew>pFd->mmapSize );
27993   assert( nNew<=pFd->mmapSizeMax );
27994   assert( nNew>0 );
27995   assert( pFd->mmapSizeActual>=pFd->mmapSize );
27996   assert( MAP_FAILED!=0 );
27997 
27998   if( (pFd->ctrlFlags & UNIXFILE_RDONLY)==0 ) flags |= PROT_WRITE;
27999 
28000   if( pOrig ){
28001     const int szSyspage = unixGetPagesize();
28002     i64 nReuse = (pFd->mmapSize & ~(szSyspage-1));
28003     u8 *pReq = &pOrig[nReuse];
28004 
28005     /* Unmap any pages of the existing mapping that cannot be reused. */
28006     if( nReuse!=nOrig ){
28007       osMunmap(pReq, nOrig-nReuse);
28008     }
28009 
28010 #if HAVE_MREMAP
28011     pNew = osMremap(pOrig, nReuse, nNew, MREMAP_MAYMOVE);
28012     zErr = "mremap";
28013 #else
28014     pNew = osMmap(pReq, nNew-nReuse, flags, MAP_SHARED, h, nReuse);
28015     if( pNew!=MAP_FAILED ){
28016       if( pNew!=pReq ){
28017         osMunmap(pNew, nNew - nReuse);
28018         pNew = 0;
28019       }else{
28020         pNew = pOrig;
28021       }
28022     }
28023 #endif
28024 
28025     /* The attempt to extend the existing mapping failed. Free it. */
28026     if( pNew==MAP_FAILED || pNew==0 ){
28027       osMunmap(pOrig, nReuse);
28028     }
28029   }
28030 
28031   /* If pNew is still NULL, try to create an entirely new mapping. */
28032   if( pNew==0 ){
28033     pNew = osMmap(0, nNew, flags, MAP_SHARED, h, 0);
28034   }
28035 
28036   if( pNew==MAP_FAILED ){
28037     pNew = 0;
28038     nNew = 0;
28039     unixLogError(SQLITE_OK, zErr, pFd->zPath);
28040 
28041     /* If the mmap() above failed, assume that all subsequent mmap() calls
28042     ** will probably fail too. Fall back to using xRead/xWrite exclusively
28043     ** in this case.  */
28044     pFd->mmapSizeMax = 0;
28045   }
28046   pFd->pMapRegion = (void *)pNew;
28047   pFd->mmapSize = pFd->mmapSizeActual = nNew;
28048 }
28049 
28050 /*
28051 ** Memory map or remap the file opened by file-descriptor pFd (if the file
28052 ** is already mapped, the existing mapping is replaced by the new). Or, if 
28053 ** there already exists a mapping for this file, and there are still 
28054 ** outstanding xFetch() references to it, this function is a no-op.
28055 **
28056 ** If parameter nByte is non-negative, then it is the requested size of 
28057 ** the mapping to create. Otherwise, if nByte is less than zero, then the 
28058 ** requested size is the size of the file on disk. The actual size of the
28059 ** created mapping is either the requested size or the value configured 
28060 ** using SQLITE_FCNTL_MMAP_LIMIT, whichever is smaller.
28061 **
28062 ** SQLITE_OK is returned if no error occurs (even if the mapping is not
28063 ** recreated as a result of outstanding references) or an SQLite error
28064 ** code otherwise.
28065 */
28066 static int unixMapfile(unixFile *pFd, i64 nByte){
28067   i64 nMap = nByte;
28068   int rc;
28069 
28070   assert( nMap>=0 || pFd->nFetchOut==0 );
28071   if( pFd->nFetchOut>0 ) return SQLITE_OK;
28072 
28073   if( nMap<0 ){
28074     struct stat statbuf;          /* Low-level file information */
28075     rc = osFstat(pFd->h, &statbuf);
28076     if( rc!=SQLITE_OK ){
28077       return SQLITE_IOERR_FSTAT;
28078     }
28079     nMap = statbuf.st_size;
28080   }
28081   if( nMap>pFd->mmapSizeMax ){
28082     nMap = pFd->mmapSizeMax;
28083   }
28084 
28085   if( nMap!=pFd->mmapSize ){
28086     if( nMap>0 ){
28087       unixRemapfile(pFd, nMap);
28088     }else{
28089       unixUnmapfile(pFd);
28090     }
28091   }
28092 
28093   return SQLITE_OK;
28094 }
28095 #endif /* SQLITE_MAX_MMAP_SIZE>0 */
28096 
28097 /*
28098 ** If possible, return a pointer to a mapping of file fd starting at offset
28099 ** iOff. The mapping must be valid for at least nAmt bytes.
28100 **
28101 ** If such a pointer can be obtained, store it in *pp and return SQLITE_OK.
28102 ** Or, if one cannot but no error occurs, set *pp to 0 and return SQLITE_OK.
28103 ** Finally, if an error does occur, return an SQLite error code. The final
28104 ** value of *pp is undefined in this case.
28105 **
28106 ** If this function does return a pointer, the caller must eventually 
28107 ** release the reference by calling unixUnfetch().
28108 */
28109 static int unixFetch(sqlite3_file *fd, i64 iOff, int nAmt, void **pp){
28110 #if SQLITE_MAX_MMAP_SIZE>0
28111   unixFile *pFd = (unixFile *)fd;   /* The underlying database file */
28112 #endif
28113   *pp = 0;
28114 
28115 #if SQLITE_MAX_MMAP_SIZE>0
28116   if( pFd->mmapSizeMax>0 ){
28117     if( pFd->pMapRegion==0 ){
28118       int rc = unixMapfile(pFd, -1);
28119       if( rc!=SQLITE_OK ) return rc;
28120     }
28121     if( pFd->mmapSize >= iOff+nAmt ){
28122       *pp = &((u8 *)pFd->pMapRegion)[iOff];
28123       pFd->nFetchOut++;
28124     }
28125   }
28126 #endif
28127   return SQLITE_OK;
28128 }
28129 
28130 /*
28131 ** If the third argument is non-NULL, then this function releases a 
28132 ** reference obtained by an earlier call to unixFetch(). The second
28133 ** argument passed to this function must be the same as the corresponding
28134 ** argument that was passed to the unixFetch() invocation. 
28135 **
28136 ** Or, if the third argument is NULL, then this function is being called 
28137 ** to inform the VFS layer that, according to POSIX, any existing mapping 
28138 ** may now be invalid and should be unmapped.
28139 */
28140 static int unixUnfetch(sqlite3_file *fd, i64 iOff, void *p){
28141   unixFile *pFd = (unixFile *)fd;   /* The underlying database file */
28142   UNUSED_PARAMETER(iOff);
28143 
28144 #if SQLITE_MAX_MMAP_SIZE>0
28145   /* If p==0 (unmap the entire file) then there must be no outstanding 
28146   ** xFetch references. Or, if p!=0 (meaning it is an xFetch reference),
28147   ** then there must be at least one outstanding.  */
28148   assert( (p==0)==(pFd->nFetchOut==0) );
28149 
28150   /* If p!=0, it must match the iOff value. */
28151   assert( p==0 || p==&((u8 *)pFd->pMapRegion)[iOff] );
28152 
28153   if( p ){
28154     pFd->nFetchOut--;
28155   }else{
28156     unixUnmapfile(pFd);
28157   }
28158 
28159   assert( pFd->nFetchOut>=0 );
28160 #endif
28161   return SQLITE_OK;
28162 }
28163 
28164 /*
28165 ** Here ends the implementation of all sqlite3_file methods.
28166 **
28167 ********************** End sqlite3_file Methods *******************************
28168 ******************************************************************************/
28169 
28170 /*
28171 ** This division contains definitions of sqlite3_io_methods objects that
28172 ** implement various file locking strategies.  It also contains definitions
28173 ** of "finder" functions.  A finder-function is used to locate the appropriate
28174 ** sqlite3_io_methods object for a particular database file.  The pAppData
28175 ** field of the sqlite3_vfs VFS objects are initialized to be pointers to
28176 ** the correct finder-function for that VFS.
28177 **
28178 ** Most finder functions return a pointer to a fixed sqlite3_io_methods
28179 ** object.  The only interesting finder-function is autolockIoFinder, which
28180 ** looks at the filesystem type and tries to guess the best locking
28181 ** strategy from that.
28182 **
28183 ** For finder-funtion F, two objects are created:
28184 **
28185 **    (1) The real finder-function named "FImpt()".
28186 **
28187 **    (2) A constant pointer to this function named just "F".
28188 **
28189 **
28190 ** A pointer to the F pointer is used as the pAppData value for VFS
28191 ** objects.  We have to do this instead of letting pAppData point
28192 ** directly at the finder-function since C90 rules prevent a void*
28193 ** from be cast into a function pointer.
28194 **
28195 **
28196 ** Each instance of this macro generates two objects:
28197 **
28198 **   *  A constant sqlite3_io_methods object call METHOD that has locking
28199 **      methods CLOSE, LOCK, UNLOCK, CKRESLOCK.
28200 **
28201 **   *  An I/O method finder function called FINDER that returns a pointer
28202 **      to the METHOD object in the previous bullet.
28203 */
28204 #define IOMETHODS(FINDER, METHOD, VERSION, CLOSE, LOCK, UNLOCK, CKLOCK)      \
28205 static const sqlite3_io_methods METHOD = {                                   \
28206    VERSION,                    /* iVersion */                                \
28207    CLOSE,                      /* xClose */                                  \
28208    unixRead,                   /* xRead */                                   \
28209    unixWrite,                  /* xWrite */                                  \
28210    unixTruncate,               /* xTruncate */                               \
28211    unixSync,                   /* xSync */                                   \
28212    unixFileSize,               /* xFileSize */                               \
28213    LOCK,                       /* xLock */                                   \
28214    UNLOCK,                     /* xUnlock */                                 \
28215    CKLOCK,                     /* xCheckReservedLock */                      \
28216    unixFileControl,            /* xFileControl */                            \
28217    unixSectorSize,             /* xSectorSize */                             \
28218    unixDeviceCharacteristics,  /* xDeviceCapabilities */                     \
28219    unixShmMap,                 /* xShmMap */                                 \
28220    unixShmLock,                /* xShmLock */                                \
28221    unixShmBarrier,             /* xShmBarrier */                             \
28222    unixShmUnmap,               /* xShmUnmap */                               \
28223    unixFetch,                  /* xFetch */                                  \
28224    unixUnfetch,                /* xUnfetch */                                \
28225 };                                                                           \
28226 static const sqlite3_io_methods *FINDER##Impl(const char *z, unixFile *p){   \
28227   UNUSED_PARAMETER(z); UNUSED_PARAMETER(p);                                  \
28228   return &METHOD;                                                            \
28229 }                                                                            \
28230 static const sqlite3_io_methods *(*const FINDER)(const char*,unixFile *p)    \
28231     = FINDER##Impl;
28232 
28233 /*
28234 ** Here are all of the sqlite3_io_methods objects for each of the
28235 ** locking strategies.  Functions that return pointers to these methods
28236 ** are also created.
28237 */
28238 IOMETHODS(
28239   posixIoFinder,            /* Finder function name */
28240   posixIoMethods,           /* sqlite3_io_methods object name */
28241   3,                        /* shared memory and mmap are enabled */
28242   unixClose,                /* xClose method */
28243   unixLock,                 /* xLock method */
28244   unixUnlock,               /* xUnlock method */
28245   unixCheckReservedLock     /* xCheckReservedLock method */
28246 )
28247 IOMETHODS(
28248   nolockIoFinder,           /* Finder function name */
28249   nolockIoMethods,          /* sqlite3_io_methods object name */
28250   1,                        /* shared memory is disabled */
28251   nolockClose,              /* xClose method */
28252   nolockLock,               /* xLock method */
28253   nolockUnlock,             /* xUnlock method */
28254   nolockCheckReservedLock   /* xCheckReservedLock method */
28255 )
28256 IOMETHODS(
28257   dotlockIoFinder,          /* Finder function name */
28258   dotlockIoMethods,         /* sqlite3_io_methods object name */
28259   1,                        /* shared memory is disabled */
28260   dotlockClose,             /* xClose method */
28261   dotlockLock,              /* xLock method */
28262   dotlockUnlock,            /* xUnlock method */
28263   dotlockCheckReservedLock  /* xCheckReservedLock method */
28264 )
28265 
28266 #if SQLITE_ENABLE_LOCKING_STYLE && !OS_VXWORKS
28267 IOMETHODS(
28268   flockIoFinder,            /* Finder function name */
28269   flockIoMethods,           /* sqlite3_io_methods object name */
28270   1,                        /* shared memory is disabled */
28271   flockClose,               /* xClose method */
28272   flockLock,                /* xLock method */
28273   flockUnlock,              /* xUnlock method */
28274   flockCheckReservedLock    /* xCheckReservedLock method */
28275 )
28276 #endif
28277 
28278 #if OS_VXWORKS
28279 IOMETHODS(
28280   semIoFinder,              /* Finder function name */
28281   semIoMethods,             /* sqlite3_io_methods object name */
28282   1,                        /* shared memory is disabled */
28283   semClose,                 /* xClose method */
28284   semLock,                  /* xLock method */
28285   semUnlock,                /* xUnlock method */
28286   semCheckReservedLock      /* xCheckReservedLock method */
28287 )
28288 #endif
28289 
28290 #if defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE
28291 IOMETHODS(
28292   afpIoFinder,              /* Finder function name */
28293   afpIoMethods,             /* sqlite3_io_methods object name */
28294   1,                        /* shared memory is disabled */
28295   afpClose,                 /* xClose method */
28296   afpLock,                  /* xLock method */
28297   afpUnlock,                /* xUnlock method */
28298   afpCheckReservedLock      /* xCheckReservedLock method */
28299 )
28300 #endif
28301 
28302 /*
28303 ** The proxy locking method is a "super-method" in the sense that it
28304 ** opens secondary file descriptors for the conch and lock files and
28305 ** it uses proxy, dot-file, AFP, and flock() locking methods on those
28306 ** secondary files.  For this reason, the division that implements
28307 ** proxy locking is located much further down in the file.  But we need
28308 ** to go ahead and define the sqlite3_io_methods and finder function
28309 ** for proxy locking here.  So we forward declare the I/O methods.
28310 */
28311 #if defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE
28312 static int proxyClose(sqlite3_file*);
28313 static int proxyLock(sqlite3_file*, int);
28314 static int proxyUnlock(sqlite3_file*, int);
28315 static int proxyCheckReservedLock(sqlite3_file*, int*);
28316 IOMETHODS(
28317   proxyIoFinder,            /* Finder function name */
28318   proxyIoMethods,           /* sqlite3_io_methods object name */
28319   1,                        /* shared memory is disabled */
28320   proxyClose,               /* xClose method */
28321   proxyLock,                /* xLock method */
28322   proxyUnlock,              /* xUnlock method */
28323   proxyCheckReservedLock    /* xCheckReservedLock method */
28324 )
28325 #endif
28326 
28327 /* nfs lockd on OSX 10.3+ doesn't clear write locks when a read lock is set */
28328 #if defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE
28329 IOMETHODS(
28330   nfsIoFinder,               /* Finder function name */
28331   nfsIoMethods,              /* sqlite3_io_methods object name */
28332   1,                         /* shared memory is disabled */
28333   unixClose,                 /* xClose method */
28334   unixLock,                  /* xLock method */
28335   nfsUnlock,                 /* xUnlock method */
28336   unixCheckReservedLock      /* xCheckReservedLock method */
28337 )
28338 #endif
28339 
28340 #if defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE
28341 /* 
28342 ** This "finder" function attempts to determine the best locking strategy 
28343 ** for the database file "filePath".  It then returns the sqlite3_io_methods
28344 ** object that implements that strategy.
28345 **
28346 ** This is for MacOSX only.
28347 */
28348 static const sqlite3_io_methods *autolockIoFinderImpl(
28349   const char *filePath,    /* name of the database file */
28350   unixFile *pNew           /* open file object for the database file */
28351 ){
28352   static const struct Mapping {
28353     const char *zFilesystem;              /* Filesystem type name */
28354     const sqlite3_io_methods *pMethods;   /* Appropriate locking method */
28355   } aMap[] = {
28356     { "hfs",    &posixIoMethods },
28357     { "ufs",    &posixIoMethods },
28358     { "afpfs",  &afpIoMethods },
28359     { "smbfs",  &afpIoMethods },
28360     { "webdav", &nolockIoMethods },
28361     { 0, 0 }
28362   };
28363   int i;
28364   struct statfs fsInfo;
28365   struct flock lockInfo;
28366 
28367   if( !filePath ){
28368     /* If filePath==NULL that means we are dealing with a transient file
28369     ** that does not need to be locked. */
28370     return &nolockIoMethods;
28371   }
28372   if( statfs(filePath, &fsInfo) != -1 ){
28373     if( fsInfo.f_flags & MNT_RDONLY ){
28374       return &nolockIoMethods;
28375     }
28376     for(i=0; aMap[i].zFilesystem; i++){
28377       if( strcmp(fsInfo.f_fstypename, aMap[i].zFilesystem)==0 ){
28378         return aMap[i].pMethods;
28379       }
28380     }
28381   }
28382 
28383   /* Default case. Handles, amongst others, "nfs".
28384   ** Test byte-range lock using fcntl(). If the call succeeds, 
28385   ** assume that the file-system supports POSIX style locks. 
28386   */
28387   lockInfo.l_len = 1;
28388   lockInfo.l_start = 0;
28389   lockInfo.l_whence = SEEK_SET;
28390   lockInfo.l_type = F_RDLCK;
28391   if( osFcntl(pNew->h, F_GETLK, &lockInfo)!=-1 ) {
28392     if( strcmp(fsInfo.f_fstypename, "nfs")==0 ){
28393       return &nfsIoMethods;
28394     } else {
28395       return &posixIoMethods;
28396     }
28397   }else{
28398     return &dotlockIoMethods;
28399   }
28400 }
28401 static const sqlite3_io_methods 
28402   *(*const autolockIoFinder)(const char*,unixFile*) = autolockIoFinderImpl;
28403 
28404 #endif /* defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE */
28405 
28406 #if OS_VXWORKS && SQLITE_ENABLE_LOCKING_STYLE
28407 /* 
28408 ** This "finder" function attempts to determine the best locking strategy 
28409 ** for the database file "filePath".  It then returns the sqlite3_io_methods
28410 ** object that implements that strategy.
28411 **
28412 ** This is for VXWorks only.
28413 */
28414 static const sqlite3_io_methods *autolockIoFinderImpl(
28415   const char *filePath,    /* name of the database file */
28416   unixFile *pNew           /* the open file object */
28417 ){
28418   struct flock lockInfo;
28419 
28420   if( !filePath ){
28421     /* If filePath==NULL that means we are dealing with a transient file
28422     ** that does not need to be locked. */
28423     return &nolockIoMethods;
28424   }
28425 
28426   /* Test if fcntl() is supported and use POSIX style locks.
28427   ** Otherwise fall back to the named semaphore method.
28428   */
28429   lockInfo.l_len = 1;
28430   lockInfo.l_start = 0;
28431   lockInfo.l_whence = SEEK_SET;
28432   lockInfo.l_type = F_RDLCK;
28433   if( osFcntl(pNew->h, F_GETLK, &lockInfo)!=-1 ) {
28434     return &posixIoMethods;
28435   }else{
28436     return &semIoMethods;
28437   }
28438 }
28439 static const sqlite3_io_methods 
28440   *(*const autolockIoFinder)(const char*,unixFile*) = autolockIoFinderImpl;
28441 
28442 #endif /* OS_VXWORKS && SQLITE_ENABLE_LOCKING_STYLE */
28443 
28444 /*
28445 ** An abstract type for a pointer to a IO method finder function:
28446 */
28447 typedef const sqlite3_io_methods *(*finder_type)(const char*,unixFile*);
28448 
28449 
28450 /****************************************************************************
28451 **************************** sqlite3_vfs methods ****************************
28452 **
28453 ** This division contains the implementation of methods on the
28454 ** sqlite3_vfs object.
28455 */
28456 
28457 /*
28458 ** Initialize the contents of the unixFile structure pointed to by pId.
28459 */
28460 static int fillInUnixFile(
28461   sqlite3_vfs *pVfs,      /* Pointer to vfs object */
28462   int h,                  /* Open file descriptor of file being opened */
28463   sqlite3_file *pId,      /* Write to the unixFile structure here */
28464   const char *zFilename,  /* Name of the file being opened */
28465   int ctrlFlags           /* Zero or more UNIXFILE_* values */
28466 ){
28467   const sqlite3_io_methods *pLockingStyle;
28468   unixFile *pNew = (unixFile *)pId;
28469   int rc = SQLITE_OK;
28470 
28471   assert( pNew->pInode==NULL );
28472 
28473   /* Usually the path zFilename should not be a relative pathname. The
28474   ** exception is when opening the proxy "conch" file in builds that
28475   ** include the special Apple locking styles.
28476   */
28477 #if defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE
28478   assert( zFilename==0 || zFilename[0]=='/' 
28479     || pVfs->pAppData==(void*)&autolockIoFinder );
28480 #else
28481   assert( zFilename==0 || zFilename[0]=='/' );
28482 #endif
28483 
28484   /* No locking occurs in temporary files */
28485   assert( zFilename!=0 || (ctrlFlags & UNIXFILE_NOLOCK)!=0 );
28486 
28487   OSTRACE(("OPEN    %-3d %s\n", h, zFilename));
28488   pNew->h = h;
28489   pNew->pVfs = pVfs;
28490   pNew->zPath = zFilename;
28491   pNew->ctrlFlags = (u8)ctrlFlags;
28492 #if SQLITE_MAX_MMAP_SIZE>0
28493   pNew->mmapSizeMax = sqlite3GlobalConfig.szMmap;
28494 #endif
28495   if( sqlite3_uri_boolean(((ctrlFlags & UNIXFILE_URI) ? zFilename : 0),
28496                            "psow", SQLITE_POWERSAFE_OVERWRITE) ){
28497     pNew->ctrlFlags |= UNIXFILE_PSOW;
28498   }
28499   if( strcmp(pVfs->zName,"unix-excl")==0 ){
28500     pNew->ctrlFlags |= UNIXFILE_EXCL;
28501   }
28502 
28503 #if OS_VXWORKS
28504   pNew->pId = vxworksFindFileId(zFilename);
28505   if( pNew->pId==0 ){
28506     ctrlFlags |= UNIXFILE_NOLOCK;
28507     rc = SQLITE_NOMEM;
28508   }
28509 #endif
28510 
28511   if( ctrlFlags & UNIXFILE_NOLOCK ){
28512     pLockingStyle = &nolockIoMethods;
28513   }else{
28514     pLockingStyle = (**(finder_type*)pVfs->pAppData)(zFilename, pNew);
28515 #if SQLITE_ENABLE_LOCKING_STYLE
28516     /* Cache zFilename in the locking context (AFP and dotlock override) for
28517     ** proxyLock activation is possible (remote proxy is based on db name)
28518     ** zFilename remains valid until file is closed, to support */
28519     pNew->lockingContext = (void*)zFilename;
28520 #endif
28521   }
28522 
28523   if( pLockingStyle == &posixIoMethods
28524 #if defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE
28525     || pLockingStyle == &nfsIoMethods
28526 #endif
28527   ){
28528     unixEnterMutex();
28529     rc = findInodeInfo(pNew, &pNew->pInode);
28530     if( rc!=SQLITE_OK ){
28531       /* If an error occurred in findInodeInfo(), close the file descriptor
28532       ** immediately, before releasing the mutex. findInodeInfo() may fail
28533       ** in two scenarios:
28534       **
28535       **   (a) A call to fstat() failed.
28536       **   (b) A malloc failed.
28537       **
28538       ** Scenario (b) may only occur if the process is holding no other
28539       ** file descriptors open on the same file. If there were other file
28540       ** descriptors on this file, then no malloc would be required by
28541       ** findInodeInfo(). If this is the case, it is quite safe to close
28542       ** handle h - as it is guaranteed that no posix locks will be released
28543       ** by doing so.
28544       **
28545       ** If scenario (a) caused the error then things are not so safe. The
28546       ** implicit assumption here is that if fstat() fails, things are in
28547       ** such bad shape that dropping a lock or two doesn't matter much.
28548       */
28549       robust_close(pNew, h, __LINE__);
28550       h = -1;
28551     }
28552     unixLeaveMutex();
28553   }
28554 
28555 #if SQLITE_ENABLE_LOCKING_STYLE && defined(__APPLE__)
28556   else if( pLockingStyle == &afpIoMethods ){
28557     /* AFP locking uses the file path so it needs to be included in
28558     ** the afpLockingContext.
28559     */
28560     afpLockingContext *pCtx;
28561     pNew->lockingContext = pCtx = sqlite3_malloc( sizeof(*pCtx) );
28562     if( pCtx==0 ){
28563       rc = SQLITE_NOMEM;
28564     }else{
28565       /* NB: zFilename exists and remains valid until the file is closed
28566       ** according to requirement F11141.  So we do not need to make a
28567       ** copy of the filename. */
28568       pCtx->dbPath = zFilename;
28569       pCtx->reserved = 0;
28570       srandomdev();
28571       unixEnterMutex();
28572       rc = findInodeInfo(pNew, &pNew->pInode);
28573       if( rc!=SQLITE_OK ){
28574         sqlite3_free(pNew->lockingContext);
28575         robust_close(pNew, h, __LINE__);
28576         h = -1;
28577       }
28578       unixLeaveMutex();        
28579     }
28580   }
28581 #endif
28582 
28583   else if( pLockingStyle == &dotlockIoMethods ){
28584     /* Dotfile locking uses the file path so it needs to be included in
28585     ** the dotlockLockingContext 
28586     */
28587     char *zLockFile;
28588     int nFilename;
28589     assert( zFilename!=0 );
28590     nFilename = (int)strlen(zFilename) + 6;
28591     zLockFile = (char *)sqlite3_malloc(nFilename);
28592     if( zLockFile==0 ){
28593       rc = SQLITE_NOMEM;
28594     }else{
28595       sqlite3_snprintf(nFilename, zLockFile, "%s" DOTLOCK_SUFFIX, zFilename);
28596     }
28597     pNew->lockingContext = zLockFile;
28598   }
28599 
28600 #if OS_VXWORKS
28601   else if( pLockingStyle == &semIoMethods ){
28602     /* Named semaphore locking uses the file path so it needs to be
28603     ** included in the semLockingContext
28604     */
28605     unixEnterMutex();
28606     rc = findInodeInfo(pNew, &pNew->pInode);
28607     if( (rc==SQLITE_OK) && (pNew->pInode->pSem==NULL) ){
28608       char *zSemName = pNew->pInode->aSemName;
28609       int n;
28610       sqlite3_snprintf(MAX_PATHNAME, zSemName, "/%s.sem",
28611                        pNew->pId->zCanonicalName);
28612       for( n=1; zSemName[n]; n++ )
28613         if( zSemName[n]=='/' ) zSemName[n] = '_';
28614       pNew->pInode->pSem = sem_open(zSemName, O_CREAT, 0666, 1);
28615       if( pNew->pInode->pSem == SEM_FAILED ){
28616         rc = SQLITE_NOMEM;
28617         pNew->pInode->aSemName[0] = '\0';
28618       }
28619     }
28620     unixLeaveMutex();
28621   }
28622 #endif
28623   
28624   pNew->lastErrno = 0;
28625 #if OS_VXWORKS
28626   if( rc!=SQLITE_OK ){
28627     if( h>=0 ) robust_close(pNew, h, __LINE__);
28628     h = -1;
28629     osUnlink(zFilename);
28630     pNew->ctrlFlags |= UNIXFILE_DELETE;
28631   }
28632 #endif
28633   if( rc!=SQLITE_OK ){
28634     if( h>=0 ) robust_close(pNew, h, __LINE__);
28635   }else{
28636     pNew->pMethod = pLockingStyle;
28637     OpenCounter(+1);
28638     verifyDbFile(pNew);
28639   }
28640   return rc;
28641 }
28642 
28643 /*
28644 ** Return the name of a directory in which to put temporary files.
28645 ** If no suitable temporary file directory can be found, return NULL.
28646 */
28647 static const char *unixTempFileDir(void){
28648   static const char *azDirs[] = {
28649      0,
28650      0,
28651      0,
28652      "/var/tmp",
28653      "/usr/tmp",
28654      "/tmp",
28655      0        /* List terminator */
28656   };
28657   unsigned int i;
28658   struct stat buf;
28659   const char *zDir = 0;
28660 
28661   azDirs[0] = sqlite3_temp_directory;
28662   if( !azDirs[1] ) azDirs[1] = getenv("SQLITE_TMPDIR");
28663   if( !azDirs[2] ) azDirs[2] = getenv("TMPDIR");
28664   for(i=0; i<sizeof(azDirs)/sizeof(azDirs[0]); zDir=azDirs[i++]){
28665     if( zDir==0 ) continue;
28666     if( osStat(zDir, &buf) ) continue;
28667     if( !S_ISDIR(buf.st_mode) ) continue;
28668     if( osAccess(zDir, 07) ) continue;
28669     break;
28670   }
28671   return zDir;
28672 }
28673 
28674 /*
28675 ** Create a temporary file name in zBuf.  zBuf must be allocated
28676 ** by the calling process and must be big enough to hold at least
28677 ** pVfs->mxPathname bytes.
28678 */
28679 static int unixGetTempname(int nBuf, char *zBuf){
28680   static const unsigned char zChars[] =
28681     "abcdefghijklmnopqrstuvwxyz"
28682     "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
28683     "0123456789";
28684   unsigned int i, j;
28685   const char *zDir;
28686 
28687   /* It's odd to simulate an io-error here, but really this is just
28688   ** using the io-error infrastructure to test that SQLite handles this
28689   ** function failing. 
28690   */
28691   SimulateIOError( return SQLITE_IOERR );
28692 
28693   zDir = unixTempFileDir();
28694   if( zDir==0 ) zDir = ".";
28695 
28696   /* Check that the output buffer is large enough for the temporary file 
28697   ** name. If it is not, return SQLITE_ERROR.
28698   */
28699   if( (strlen(zDir) + strlen(SQLITE_TEMP_FILE_PREFIX) + 18) >= (size_t)nBuf ){
28700     return SQLITE_ERROR;
28701   }
28702 
28703   do{
28704     sqlite3_snprintf(nBuf-18, zBuf, "%s/"SQLITE_TEMP_FILE_PREFIX, zDir);
28705     j = (int)strlen(zBuf);
28706     sqlite3_randomness(15, &zBuf[j]);
28707     for(i=0; i<15; i++, j++){
28708       zBuf[j] = (char)zChars[ ((unsigned char)zBuf[j])%(sizeof(zChars)-1) ];
28709     }
28710     zBuf[j] = 0;
28711     zBuf[j+1] = 0;
28712   }while( osAccess(zBuf,0)==0 );
28713   return SQLITE_OK;
28714 }
28715 
28716 #if SQLITE_ENABLE_LOCKING_STYLE && defined(__APPLE__)
28717 /*
28718 ** Routine to transform a unixFile into a proxy-locking unixFile.
28719 ** Implementation in the proxy-lock division, but used by unixOpen()
28720 ** if SQLITE_PREFER_PROXY_LOCKING is defined.
28721 */
28722 static int proxyTransformUnixFile(unixFile*, const char*);
28723 #endif
28724 
28725 /*
28726 ** Search for an unused file descriptor that was opened on the database 
28727 ** file (not a journal or master-journal file) identified by pathname
28728 ** zPath with SQLITE_OPEN_XXX flags matching those passed as the second
28729 ** argument to this function.
28730 **
28731 ** Such a file descriptor may exist if a database connection was closed
28732 ** but the associated file descriptor could not be closed because some
28733 ** other file descriptor open on the same file is holding a file-lock.
28734 ** Refer to comments in the unixClose() function and the lengthy comment
28735 ** describing "Posix Advisory Locking" at the start of this file for 
28736 ** further details. Also, ticket #4018.
28737 **
28738 ** If a suitable file descriptor is found, then it is returned. If no
28739 ** such file descriptor is located, -1 is returned.
28740 */
28741 static UnixUnusedFd *findReusableFd(const char *zPath, int flags){
28742   UnixUnusedFd *pUnused = 0;
28743 
28744   /* Do not search for an unused file descriptor on vxworks. Not because
28745   ** vxworks would not benefit from the change (it might, we're not sure),
28746   ** but because no way to test it is currently available. It is better 
28747   ** not to risk breaking vxworks support for the sake of such an obscure 
28748   ** feature.  */
28749 #if !OS_VXWORKS
28750   struct stat sStat;                   /* Results of stat() call */
28751 
28752   /* A stat() call may fail for various reasons. If this happens, it is
28753   ** almost certain that an open() call on the same path will also fail.
28754   ** For this reason, if an error occurs in the stat() call here, it is
28755   ** ignored and -1 is returned. The caller will try to open a new file
28756   ** descriptor on the same path, fail, and return an error to SQLite.
28757   **
28758   ** Even if a subsequent open() call does succeed, the consequences of
28759   ** not searching for a resusable file descriptor are not dire.  */
28760   if( 0==osStat(zPath, &sStat) ){
28761     unixInodeInfo *pInode;
28762 
28763     unixEnterMutex();
28764     pInode = inodeList;
28765     while( pInode && (pInode->fileId.dev!=sStat.st_dev
28766                      || pInode->fileId.ino!=sStat.st_ino) ){
28767        pInode = pInode->pNext;
28768     }
28769     if( pInode ){
28770       UnixUnusedFd **pp;
28771       for(pp=&pInode->pUnused; *pp && (*pp)->flags!=flags; pp=&((*pp)->pNext));
28772       pUnused = *pp;
28773       if( pUnused ){
28774         *pp = pUnused->pNext;
28775       }
28776     }
28777     unixLeaveMutex();
28778   }
28779 #endif    /* if !OS_VXWORKS */
28780   return pUnused;
28781 }
28782 
28783 /*
28784 ** This function is called by unixOpen() to determine the unix permissions
28785 ** to create new files with. If no error occurs, then SQLITE_OK is returned
28786 ** and a value suitable for passing as the third argument to open(2) is
28787 ** written to *pMode. If an IO error occurs, an SQLite error code is 
28788 ** returned and the value of *pMode is not modified.
28789 **
28790 ** In most cases cases, this routine sets *pMode to 0, which will become
28791 ** an indication to robust_open() to create the file using
28792 ** SQLITE_DEFAULT_FILE_PERMISSIONS adjusted by the umask.
28793 ** But if the file being opened is a WAL or regular journal file, then 
28794 ** this function queries the file-system for the permissions on the 
28795 ** corresponding database file and sets *pMode to this value. Whenever 
28796 ** possible, WAL and journal files are created using the same permissions 
28797 ** as the associated database file.
28798 **
28799 ** If the SQLITE_ENABLE_8_3_NAMES option is enabled, then the
28800 ** original filename is unavailable.  But 8_3_NAMES is only used for
28801 ** FAT filesystems and permissions do not matter there, so just use
28802 ** the default permissions.
28803 */
28804 static int findCreateFileMode(
28805   const char *zPath,              /* Path of file (possibly) being created */
28806   int flags,                      /* Flags passed as 4th argument to xOpen() */
28807   mode_t *pMode,                  /* OUT: Permissions to open file with */
28808   uid_t *pUid,                    /* OUT: uid to set on the file */
28809   gid_t *pGid                     /* OUT: gid to set on the file */
28810 ){
28811   int rc = SQLITE_OK;             /* Return Code */
28812   *pMode = 0;
28813   *pUid = 0;
28814   *pGid = 0;
28815   if( flags & (SQLITE_OPEN_WAL|SQLITE_OPEN_MAIN_JOURNAL) ){
28816     char zDb[MAX_PATHNAME+1];     /* Database file path */
28817     int nDb;                      /* Number of valid bytes in zDb */
28818     struct stat sStat;            /* Output of stat() on database file */
28819 
28820     /* zPath is a path to a WAL or journal file. The following block derives
28821     ** the path to the associated database file from zPath. This block handles
28822     ** the following naming conventions:
28823     **
28824     **   "<path to db>-journal"
28825     **   "<path to db>-wal"
28826     **   "<path to db>-journalNN"
28827     **   "<path to db>-walNN"
28828     **
28829     ** where NN is a decimal number. The NN naming schemes are 
28830     ** used by the test_multiplex.c module.
28831     */
28832     nDb = sqlite3Strlen30(zPath) - 1; 
28833 #ifdef SQLITE_ENABLE_8_3_NAMES
28834     while( nDb>0 && sqlite3Isalnum(zPath[nDb]) ) nDb--;
28835     if( nDb==0 || zPath[nDb]!='-' ) return SQLITE_OK;
28836 #else
28837     while( zPath[nDb]!='-' ){
28838       assert( nDb>0 );
28839       assert( zPath[nDb]!='\n' );
28840       nDb--;
28841     }
28842 #endif
28843     memcpy(zDb, zPath, nDb);
28844     zDb[nDb] = '\0';
28845 
28846     if( 0==osStat(zDb, &sStat) ){
28847       *pMode = sStat.st_mode & 0777;
28848       *pUid = sStat.st_uid;
28849       *pGid = sStat.st_gid;
28850     }else{
28851       rc = SQLITE_IOERR_FSTAT;
28852     }
28853   }else if( flags & SQLITE_OPEN_DELETEONCLOSE ){
28854     *pMode = 0600;
28855   }
28856   return rc;
28857 }
28858 
28859 /*
28860 ** Open the file zPath.
28861 ** 
28862 ** Previously, the SQLite OS layer used three functions in place of this
28863 ** one:
28864 **
28865 **     sqlite3OsOpenReadWrite();
28866 **     sqlite3OsOpenReadOnly();
28867 **     sqlite3OsOpenExclusive();
28868 **
28869 ** These calls correspond to the following combinations of flags:
28870 **
28871 **     ReadWrite() ->     (READWRITE | CREATE)
28872 **     ReadOnly()  ->     (READONLY) 
28873 **     OpenExclusive() -> (READWRITE | CREATE | EXCLUSIVE)
28874 **
28875 ** The old OpenExclusive() accepted a boolean argument - "delFlag". If
28876 ** true, the file was configured to be automatically deleted when the
28877 ** file handle closed. To achieve the same effect using this new 
28878 ** interface, add the DELETEONCLOSE flag to those specified above for 
28879 ** OpenExclusive().
28880 */
28881 static int unixOpen(
28882   sqlite3_vfs *pVfs,           /* The VFS for which this is the xOpen method */
28883   const char *zPath,           /* Pathname of file to be opened */
28884   sqlite3_file *pFile,         /* The file descriptor to be filled in */
28885   int flags,                   /* Input flags to control the opening */
28886   int *pOutFlags               /* Output flags returned to SQLite core */
28887 ){
28888   unixFile *p = (unixFile *)pFile;
28889   int fd = -1;                   /* File descriptor returned by open() */
28890   int openFlags = 0;             /* Flags to pass to open() */
28891   int eType = flags&0xFFFFFF00;  /* Type of file to open */
28892   int noLock;                    /* True to omit locking primitives */
28893   int rc = SQLITE_OK;            /* Function Return Code */
28894   int ctrlFlags = 0;             /* UNIXFILE_* flags */
28895 
28896   int isExclusive  = (flags & SQLITE_OPEN_EXCLUSIVE);
28897   int isDelete     = (flags & SQLITE_OPEN_DELETEONCLOSE);
28898   int isCreate     = (flags & SQLITE_OPEN_CREATE);
28899   int isReadonly   = (flags & SQLITE_OPEN_READONLY);
28900   int isReadWrite  = (flags & SQLITE_OPEN_READWRITE);
28901 #if SQLITE_ENABLE_LOCKING_STYLE
28902   int isAutoProxy  = (flags & SQLITE_OPEN_AUTOPROXY);
28903 #endif
28904 #if defined(__APPLE__) || SQLITE_ENABLE_LOCKING_STYLE
28905   struct statfs fsInfo;
28906 #endif
28907 
28908   /* If creating a master or main-file journal, this function will open
28909   ** a file-descriptor on the directory too. The first time unixSync()
28910   ** is called the directory file descriptor will be fsync()ed and close()d.
28911   */
28912   int syncDir = (isCreate && (
28913         eType==SQLITE_OPEN_MASTER_JOURNAL 
28914      || eType==SQLITE_OPEN_MAIN_JOURNAL 
28915      || eType==SQLITE_OPEN_WAL
28916   ));
28917 
28918   /* If argument zPath is a NULL pointer, this function is required to open
28919   ** a temporary file. Use this buffer to store the file name in.
28920   */
28921   char zTmpname[MAX_PATHNAME+2];
28922   const char *zName = zPath;
28923 
28924   /* Check the following statements are true: 
28925   **
28926   **   (a) Exactly one of the READWRITE and READONLY flags must be set, and 
28927   **   (b) if CREATE is set, then READWRITE must also be set, and
28928   **   (c) if EXCLUSIVE is set, then CREATE must also be set.
28929   **   (d) if DELETEONCLOSE is set, then CREATE must also be set.
28930   */
28931   assert((isReadonly==0 || isReadWrite==0) && (isReadWrite || isReadonly));
28932   assert(isCreate==0 || isReadWrite);
28933   assert(isExclusive==0 || isCreate);
28934   assert(isDelete==0 || isCreate);
28935 
28936   /* The main DB, main journal, WAL file and master journal are never 
28937   ** automatically deleted. Nor are they ever temporary files.  */
28938   assert( (!isDelete && zName) || eType!=SQLITE_OPEN_MAIN_DB );
28939   assert( (!isDelete && zName) || eType!=SQLITE_OPEN_MAIN_JOURNAL );
28940   assert( (!isDelete && zName) || eType!=SQLITE_OPEN_MASTER_JOURNAL );
28941   assert( (!isDelete && zName) || eType!=SQLITE_OPEN_WAL );
28942 
28943   /* Assert that the upper layer has set one of the "file-type" flags. */
28944   assert( eType==SQLITE_OPEN_MAIN_DB      || eType==SQLITE_OPEN_TEMP_DB 
28945        || eType==SQLITE_OPEN_MAIN_JOURNAL || eType==SQLITE_OPEN_TEMP_JOURNAL 
28946        || eType==SQLITE_OPEN_SUBJOURNAL   || eType==SQLITE_OPEN_MASTER_JOURNAL 
28947        || eType==SQLITE_OPEN_TRANSIENT_DB || eType==SQLITE_OPEN_WAL
28948   );
28949 
28950   memset(p, 0, sizeof(unixFile));
28951 
28952   if( eType==SQLITE_OPEN_MAIN_DB ){
28953     UnixUnusedFd *pUnused;
28954     pUnused = findReusableFd(zName, flags);
28955     if( pUnused ){
28956       fd = pUnused->fd;
28957     }else{
28958       pUnused = sqlite3_malloc(sizeof(*pUnused));
28959       if( !pUnused ){
28960         return SQLITE_NOMEM;
28961       }
28962     }
28963     p->pUnused = pUnused;
28964 
28965     /* Database filenames are double-zero terminated if they are not
28966     ** URIs with parameters.  Hence, they can always be passed into
28967     ** sqlite3_uri_parameter(). */
28968     assert( (flags & SQLITE_OPEN_URI) || zName[strlen(zName)+1]==0 );
28969 
28970   }else if( !zName ){
28971     /* If zName is NULL, the upper layer is requesting a temp file. */
28972     assert(isDelete && !syncDir);
28973     rc = unixGetTempname(MAX_PATHNAME+2, zTmpname);
28974     if( rc!=SQLITE_OK ){
28975       return rc;
28976     }
28977     zName = zTmpname;
28978 
28979     /* Generated temporary filenames are always double-zero terminated
28980     ** for use by sqlite3_uri_parameter(). */
28981     assert( zName[strlen(zName)+1]==0 );
28982   }
28983 
28984   /* Determine the value of the flags parameter passed to POSIX function
28985   ** open(). These must be calculated even if open() is not called, as
28986   ** they may be stored as part of the file handle and used by the 
28987   ** 'conch file' locking functions later on.  */
28988   if( isReadonly )  openFlags |= O_RDONLY;
28989   if( isReadWrite ) openFlags |= O_RDWR;
28990   if( isCreate )    openFlags |= O_CREAT;
28991   if( isExclusive ) openFlags |= (O_EXCL|O_NOFOLLOW);
28992   openFlags |= (O_LARGEFILE|O_BINARY);
28993 
28994   if( fd<0 ){
28995     mode_t openMode;              /* Permissions to create file with */
28996     uid_t uid;                    /* Userid for the file */
28997     gid_t gid;                    /* Groupid for the file */
28998     rc = findCreateFileMode(zName, flags, &openMode, &uid, &gid);
28999     if( rc!=SQLITE_OK ){
29000       assert( !p->pUnused );
29001       assert( eType==SQLITE_OPEN_WAL || eType==SQLITE_OPEN_MAIN_JOURNAL );
29002       return rc;
29003     }
29004     fd = robust_open(zName, openFlags, openMode);
29005     OSTRACE(("OPENX   %-3d %s 0%o\n", fd, zName, openFlags));
29006     if( fd<0 && errno!=EISDIR && isReadWrite && !isExclusive ){
29007       /* Failed to open the file for read/write access. Try read-only. */
29008       flags &= ~(SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE);
29009       openFlags &= ~(O_RDWR|O_CREAT);
29010       flags |= SQLITE_OPEN_READONLY;
29011       openFlags |= O_RDONLY;
29012       isReadonly = 1;
29013       fd = robust_open(zName, openFlags, openMode);
29014     }
29015     if( fd<0 ){
29016       rc = unixLogError(SQLITE_CANTOPEN_BKPT, "open", zName);
29017       goto open_finished;
29018     }
29019 
29020     /* If this process is running as root and if creating a new rollback
29021     ** journal or WAL file, set the ownership of the journal or WAL to be
29022     ** the same as the original database.
29023     */
29024     if( flags & (SQLITE_OPEN_WAL|SQLITE_OPEN_MAIN_JOURNAL) ){
29025       osFchown(fd, uid, gid);
29026     }
29027   }
29028   assert( fd>=0 );
29029   if( pOutFlags ){
29030     *pOutFlags = flags;
29031   }
29032 
29033   if( p->pUnused ){
29034     p->pUnused->fd = fd;
29035     p->pUnused->flags = flags;
29036   }
29037 
29038   if( isDelete ){
29039 #if OS_VXWORKS
29040     zPath = zName;
29041 #else
29042     osUnlink(zName);
29043 #endif
29044   }
29045 #if SQLITE_ENABLE_LOCKING_STYLE
29046   else{
29047     p->openFlags = openFlags;
29048   }
29049 #endif
29050 
29051   noLock = eType!=SQLITE_OPEN_MAIN_DB;
29052 
29053   
29054 #if defined(__APPLE__) || SQLITE_ENABLE_LOCKING_STYLE
29055   if( fstatfs(fd, &fsInfo) == -1 ){
29056     ((unixFile*)pFile)->lastErrno = errno;
29057     robust_close(p, fd, __LINE__);
29058     return SQLITE_IOERR_ACCESS;
29059   }
29060   if (0 == strncmp("msdos", fsInfo.f_fstypename, 5)) {
29061     ((unixFile*)pFile)->fsFlags |= SQLITE_FSFLAGS_IS_MSDOS;
29062   }
29063 #endif
29064 
29065   /* Set up appropriate ctrlFlags */
29066   if( isDelete )                ctrlFlags |= UNIXFILE_DELETE;
29067   if( isReadonly )              ctrlFlags |= UNIXFILE_RDONLY;
29068   if( noLock )                  ctrlFlags |= UNIXFILE_NOLOCK;
29069   if( syncDir )                 ctrlFlags |= UNIXFILE_DIRSYNC;
29070   if( flags & SQLITE_OPEN_URI ) ctrlFlags |= UNIXFILE_URI;
29071 
29072 #if SQLITE_ENABLE_LOCKING_STYLE
29073 #if SQLITE_PREFER_PROXY_LOCKING
29074   isAutoProxy = 1;
29075 #endif
29076   if( isAutoProxy && (zPath!=NULL) && (!noLock) && pVfs->xOpen ){
29077     char *envforce = getenv("SQLITE_FORCE_PROXY_LOCKING");
29078     int useProxy = 0;
29079 
29080     /* SQLITE_FORCE_PROXY_LOCKING==1 means force always use proxy, 0 means 
29081     ** never use proxy, NULL means use proxy for non-local files only.  */
29082     if( envforce!=NULL ){
29083       useProxy = atoi(envforce)>0;
29084     }else{
29085       if( statfs(zPath, &fsInfo) == -1 ){
29086         /* In theory, the close(fd) call is sub-optimal. If the file opened
29087         ** with fd is a database file, and there are other connections open
29088         ** on that file that are currently holding advisory locks on it,
29089         ** then the call to close() will cancel those locks. In practice,
29090         ** we're assuming that statfs() doesn't fail very often. At least
29091         ** not while other file descriptors opened by the same process on
29092         ** the same file are working.  */
29093         p->lastErrno = errno;
29094         robust_close(p, fd, __LINE__);
29095         rc = SQLITE_IOERR_ACCESS;
29096         goto open_finished;
29097       }
29098       useProxy = !(fsInfo.f_flags&MNT_LOCAL);
29099     }
29100     if( useProxy ){
29101       rc = fillInUnixFile(pVfs, fd, pFile, zPath, ctrlFlags);
29102       if( rc==SQLITE_OK ){
29103         rc = proxyTransformUnixFile((unixFile*)pFile, ":auto:");
29104         if( rc!=SQLITE_OK ){
29105           /* Use unixClose to clean up the resources added in fillInUnixFile 
29106           ** and clear all the structure's references.  Specifically, 
29107           ** pFile->pMethods will be NULL so sqlite3OsClose will be a no-op 
29108           */
29109           unixClose(pFile);
29110           return rc;
29111         }
29112       }
29113       goto open_finished;
29114     }
29115   }
29116 #endif
29117   
29118   rc = fillInUnixFile(pVfs, fd, pFile, zPath, ctrlFlags);
29119 
29120 open_finished:
29121   if( rc!=SQLITE_OK ){
29122     sqlite3_free(p->pUnused);
29123   }
29124   return rc;
29125 }
29126 
29127 
29128 /*
29129 ** Delete the file at zPath. If the dirSync argument is true, fsync()
29130 ** the directory after deleting the file.
29131 */
29132 static int unixDelete(
29133   sqlite3_vfs *NotUsed,     /* VFS containing this as the xDelete method */
29134   const char *zPath,        /* Name of file to be deleted */
29135   int dirSync               /* If true, fsync() directory after deleting file */
29136 ){
29137   int rc = SQLITE_OK;
29138   UNUSED_PARAMETER(NotUsed);
29139   SimulateIOError(return SQLITE_IOERR_DELETE);
29140   if( osUnlink(zPath)==(-1) ){
29141     if( errno==ENOENT ){
29142       rc = SQLITE_IOERR_DELETE_NOENT;
29143     }else{
29144       rc = unixLogError(SQLITE_IOERR_DELETE, "unlink", zPath);
29145     }
29146     return rc;
29147   }
29148 #ifndef SQLITE_DISABLE_DIRSYNC
29149   if( (dirSync & 1)!=0 ){
29150     int fd;
29151     rc = osOpenDirectory(zPath, &fd);
29152     if( rc==SQLITE_OK ){
29153 #if OS_VXWORKS
29154       if( fsync(fd)==-1 )
29155 #else
29156       if( fsync(fd) )
29157 #endif
29158       {
29159         rc = unixLogError(SQLITE_IOERR_DIR_FSYNC, "fsync", zPath);
29160       }
29161       robust_close(0, fd, __LINE__);
29162     }else if( rc==SQLITE_CANTOPEN ){
29163       rc = SQLITE_OK;
29164     }
29165   }
29166 #endif
29167   return rc;
29168 }
29169 
29170 /*
29171 ** Test the existence of or access permissions of file zPath. The
29172 ** test performed depends on the value of flags:
29173 **
29174 **     SQLITE_ACCESS_EXISTS: Return 1 if the file exists
29175 **     SQLITE_ACCESS_READWRITE: Return 1 if the file is read and writable.
29176 **     SQLITE_ACCESS_READONLY: Return 1 if the file is readable.
29177 **
29178 ** Otherwise return 0.
29179 */
29180 static int unixAccess(
29181   sqlite3_vfs *NotUsed,   /* The VFS containing this xAccess method */
29182   const char *zPath,      /* Path of the file to examine */
29183   int flags,              /* What do we want to learn about the zPath file? */
29184   int *pResOut            /* Write result boolean here */
29185 ){
29186   int amode = 0;
29187   UNUSED_PARAMETER(NotUsed);
29188   SimulateIOError( return SQLITE_IOERR_ACCESS; );
29189   switch( flags ){
29190     case SQLITE_ACCESS_EXISTS:
29191       amode = F_OK;
29192       break;
29193     case SQLITE_ACCESS_READWRITE:
29194       amode = W_OK|R_OK;
29195       break;
29196     case SQLITE_ACCESS_READ:
29197       amode = R_OK;
29198       break;
29199 
29200     default:
29201       assert(!"Invalid flags argument");
29202   }
29203   *pResOut = (osAccess(zPath, amode)==0);
29204   if( flags==SQLITE_ACCESS_EXISTS && *pResOut ){
29205     struct stat buf;
29206     if( 0==osStat(zPath, &buf) && buf.st_size==0 ){
29207       *pResOut = 0;
29208     }
29209   }
29210   return SQLITE_OK;
29211 }
29212 
29213 
29214 /*
29215 ** Turn a relative pathname into a full pathname. The relative path
29216 ** is stored as a nul-terminated string in the buffer pointed to by
29217 ** zPath. 
29218 **
29219 ** zOut points to a buffer of at least sqlite3_vfs.mxPathname bytes 
29220 ** (in this case, MAX_PATHNAME bytes). The full-path is written to
29221 ** this buffer before returning.
29222 */
29223 static int unixFullPathname(
29224   sqlite3_vfs *pVfs,            /* Pointer to vfs object */
29225   const char *zPath,            /* Possibly relative input path */
29226   int nOut,                     /* Size of output buffer in bytes */
29227   char *zOut                    /* Output buffer */
29228 ){
29229 
29230   /* It's odd to simulate an io-error here, but really this is just
29231   ** using the io-error infrastructure to test that SQLite handles this
29232   ** function failing. This function could fail if, for example, the
29233   ** current working directory has been unlinked.
29234   */
29235   SimulateIOError( return SQLITE_ERROR );
29236 
29237   assert( pVfs->mxPathname==MAX_PATHNAME );
29238   UNUSED_PARAMETER(pVfs);
29239 
29240   zOut[nOut-1] = '\0';
29241   if( zPath[0]=='/' ){
29242     sqlite3_snprintf(nOut, zOut, "%s", zPath);
29243   }else{
29244     int nCwd;
29245     if( osGetcwd(zOut, nOut-1)==0 ){
29246       return unixLogError(SQLITE_CANTOPEN_BKPT, "getcwd", zPath);
29247     }
29248     nCwd = (int)strlen(zOut);
29249     sqlite3_snprintf(nOut-nCwd, &zOut[nCwd], "/%s", zPath);
29250   }
29251   return SQLITE_OK;
29252 }
29253 
29254 
29255 #ifndef SQLITE_OMIT_LOAD_EXTENSION
29256 /*
29257 ** Interfaces for opening a shared library, finding entry points
29258 ** within the shared library, and closing the shared library.
29259 */
29260 #include <dlfcn.h>
29261 static void *unixDlOpen(sqlite3_vfs *NotUsed, const char *zFilename){
29262   UNUSED_PARAMETER(NotUsed);
29263   return dlopen(zFilename, RTLD_NOW | RTLD_GLOBAL);
29264 }
29265 
29266 /*
29267 ** SQLite calls this function immediately after a call to unixDlSym() or
29268 ** unixDlOpen() fails (returns a null pointer). If a more detailed error
29269 ** message is available, it is written to zBufOut. If no error message
29270 ** is available, zBufOut is left unmodified and SQLite uses a default
29271 ** error message.
29272 */
29273 static void unixDlError(sqlite3_vfs *NotUsed, int nBuf, char *zBufOut){
29274   const char *zErr;
29275   UNUSED_PARAMETER(NotUsed);
29276   unixEnterMutex();
29277   zErr = dlerror();
29278   if( zErr ){
29279     sqlite3_snprintf(nBuf, zBufOut, "%s", zErr);
29280   }
29281   unixLeaveMutex();
29282 }
29283 static void (*unixDlSym(sqlite3_vfs *NotUsed, void *p, const char*zSym))(void){
29284   /* 
29285   ** GCC with -pedantic-errors says that C90 does not allow a void* to be
29286   ** cast into a pointer to a function.  And yet the library dlsym() routine
29287   ** returns a void* which is really a pointer to a function.  So how do we
29288   ** use dlsym() with -pedantic-errors?
29289   **
29290   ** Variable x below is defined to be a pointer to a function taking
29291   ** parameters void* and const char* and returning a pointer to a function.
29292   ** We initialize x by assigning it a pointer to the dlsym() function.
29293   ** (That assignment requires a cast.)  Then we call the function that
29294   ** x points to.  
29295   **
29296   ** This work-around is unlikely to work correctly on any system where
29297   ** you really cannot cast a function pointer into void*.  But then, on the
29298   ** other hand, dlsym() will not work on such a system either, so we have
29299   ** not really lost anything.
29300   */
29301   void (*(*x)(void*,const char*))(void);
29302   UNUSED_PARAMETER(NotUsed);
29303   x = (void(*(*)(void*,const char*))(void))dlsym;
29304   return (*x)(p, zSym);
29305 }
29306 static void unixDlClose(sqlite3_vfs *NotUsed, void *pHandle){
29307   UNUSED_PARAMETER(NotUsed);
29308   dlclose(pHandle);
29309 }
29310 #else /* if SQLITE_OMIT_LOAD_EXTENSION is defined: */
29311   #define unixDlOpen  0
29312   #define unixDlError 0
29313   #define unixDlSym   0
29314   #define unixDlClose 0
29315 #endif
29316 
29317 /*
29318 ** Write nBuf bytes of random data to the supplied buffer zBuf.
29319 */
29320 static int unixRandomness(sqlite3_vfs *NotUsed, int nBuf, char *zBuf){
29321   UNUSED_PARAMETER(NotUsed);
29322   assert((size_t)nBuf>=(sizeof(time_t)+sizeof(int)));
29323 
29324   /* We have to initialize zBuf to prevent valgrind from reporting
29325   ** errors.  The reports issued by valgrind are incorrect - we would
29326   ** prefer that the randomness be increased by making use of the
29327   ** uninitialized space in zBuf - but valgrind errors tend to worry
29328   ** some users.  Rather than argue, it seems easier just to initialize
29329   ** the whole array and silence valgrind, even if that means less randomness
29330   ** in the random seed.
29331   **
29332   ** When testing, initializing zBuf[] to zero is all we do.  That means
29333   ** that we always use the same random number sequence.  This makes the
29334   ** tests repeatable.
29335   */
29336   memset(zBuf, 0, nBuf);
29337 #if !defined(SQLITE_TEST)
29338   {
29339     int pid, fd, got;
29340     fd = robust_open("/dev/urandom", O_RDONLY, 0);
29341     if( fd<0 ){
29342       time_t t;
29343       time(&t);
29344       memcpy(zBuf, &t, sizeof(t));
29345       pid = getpid();
29346       memcpy(&zBuf[sizeof(t)], &pid, sizeof(pid));
29347       assert( sizeof(t)+sizeof(pid)<=(size_t)nBuf );
29348       nBuf = sizeof(t) + sizeof(pid);
29349     }else{
29350       do{ got = osRead(fd, zBuf, nBuf); }while( got<0 && errno==EINTR );
29351       robust_close(0, fd, __LINE__);
29352     }
29353   }
29354 #endif
29355   return nBuf;
29356 }
29357 
29358 
29359 /*
29360 ** Sleep for a little while.  Return the amount of time slept.
29361 ** The argument is the number of microseconds we want to sleep.
29362 ** The return value is the number of microseconds of sleep actually
29363 ** requested from the underlying operating system, a number which
29364 ** might be greater than or equal to the argument, but not less
29365 ** than the argument.
29366 */
29367 static int unixSleep(sqlite3_vfs *NotUsed, int microseconds){
29368 #if OS_VXWORKS
29369   struct timespec sp;
29370 
29371   sp.tv_sec = microseconds / 1000000;
29372   sp.tv_nsec = (microseconds % 1000000) * 1000;
29373   nanosleep(&sp, NULL);
29374   UNUSED_PARAMETER(NotUsed);
29375   return microseconds;
29376 #elif defined(HAVE_USLEEP) && HAVE_USLEEP
29377   usleep(microseconds);
29378   UNUSED_PARAMETER(NotUsed);
29379   return microseconds;
29380 #else
29381   int seconds = (microseconds+999999)/1000000;
29382   sleep(seconds);
29383   UNUSED_PARAMETER(NotUsed);
29384   return seconds*1000000;
29385 #endif
29386 }
29387 
29388 /*
29389 ** The following variable, if set to a non-zero value, is interpreted as
29390 ** the number of seconds since 1970 and is used to set the result of
29391 ** sqlite3OsCurrentTime() during testing.
29392 */
29393 #ifdef SQLITE_TEST
29394 SQLITE_API int sqlite3_current_time = 0;  /* Fake system time in seconds since 1970. */
29395 #endif
29396 
29397 /*
29398 ** Find the current time (in Universal Coordinated Time).  Write into *piNow
29399 ** the current time and date as a Julian Day number times 86_400_000.  In
29400 ** other words, write into *piNow the number of milliseconds since the Julian
29401 ** epoch of noon in Greenwich on November 24, 4714 B.C according to the
29402 ** proleptic Gregorian calendar.
29403 **
29404 ** On success, return SQLITE_OK.  Return SQLITE_ERROR if the time and date 
29405 ** cannot be found.
29406 */
29407 static int unixCurrentTimeInt64(sqlite3_vfs *NotUsed, sqlite3_int64 *piNow){
29408   static const sqlite3_int64 unixEpoch = 24405875*(sqlite3_int64)8640000;
29409   int rc = SQLITE_OK;
29410 #if defined(NO_GETTOD)
29411   time_t t;
29412   time(&t);
29413   *piNow = ((sqlite3_int64)t)*1000 + unixEpoch;
29414 #elif OS_VXWORKS
29415   struct timespec sNow;
29416   clock_gettime(CLOCK_REALTIME, &sNow);
29417   *piNow = unixEpoch + 1000*(sqlite3_int64)sNow.tv_sec + sNow.tv_nsec/1000000;
29418 #else
29419   struct timeval sNow;
29420   if( gettimeofday(&sNow, 0)==0 ){
29421     *piNow = unixEpoch + 1000*(sqlite3_int64)sNow.tv_sec + sNow.tv_usec/1000;
29422   }else{
29423     rc = SQLITE_ERROR;
29424   }
29425 #endif
29426 
29427 #ifdef SQLITE_TEST
29428   if( sqlite3_current_time ){
29429     *piNow = 1000*(sqlite3_int64)sqlite3_current_time + unixEpoch;
29430   }
29431 #endif
29432   UNUSED_PARAMETER(NotUsed);
29433   return rc;
29434 }
29435 
29436 /*
29437 ** Find the current time (in Universal Coordinated Time).  Write the
29438 ** current time and date as a Julian Day number into *prNow and
29439 ** return 0.  Return 1 if the time and date cannot be found.
29440 */
29441 static int unixCurrentTime(sqlite3_vfs *NotUsed, double *prNow){
29442   sqlite3_int64 i = 0;
29443   int rc;
29444   UNUSED_PARAMETER(NotUsed);
29445   rc = unixCurrentTimeInt64(0, &i);
29446   *prNow = i/86400000.0;
29447   return rc;
29448 }
29449 
29450 /*
29451 ** We added the xGetLastError() method with the intention of providing
29452 ** better low-level error messages when operating-system problems come up
29453 ** during SQLite operation.  But so far, none of that has been implemented
29454 ** in the core.  So this routine is never called.  For now, it is merely
29455 ** a place-holder.
29456 */
29457 static int unixGetLastError(sqlite3_vfs *NotUsed, int NotUsed2, char *NotUsed3){
29458   UNUSED_PARAMETER(NotUsed);
29459   UNUSED_PARAMETER(NotUsed2);
29460   UNUSED_PARAMETER(NotUsed3);
29461   return 0;
29462 }
29463 
29464 
29465 /*
29466 ************************ End of sqlite3_vfs methods ***************************
29467 ******************************************************************************/
29468 
29469 /******************************************************************************
29470 ************************** Begin Proxy Locking ********************************
29471 **
29472 ** Proxy locking is a "uber-locking-method" in this sense:  It uses the
29473 ** other locking methods on secondary lock files.  Proxy locking is a
29474 ** meta-layer over top of the primitive locking implemented above.  For
29475 ** this reason, the division that implements of proxy locking is deferred
29476 ** until late in the file (here) after all of the other I/O methods have
29477 ** been defined - so that the primitive locking methods are available
29478 ** as services to help with the implementation of proxy locking.
29479 **
29480 ****
29481 **
29482 ** The default locking schemes in SQLite use byte-range locks on the
29483 ** database file to coordinate safe, concurrent access by multiple readers
29484 ** and writers [http://sqlite.org/lockingv3.html].  The five file locking
29485 ** states (UNLOCKED, PENDING, SHARED, RESERVED, EXCLUSIVE) are implemented
29486 ** as POSIX read & write locks over fixed set of locations (via fsctl),
29487 ** on AFP and SMB only exclusive byte-range locks are available via fsctl
29488 ** with _IOWR('z', 23, struct ByteRangeLockPB2) to track the same 5 states.
29489 ** To simulate a F_RDLCK on the shared range, on AFP a randomly selected
29490 ** address in the shared range is taken for a SHARED lock, the entire
29491 ** shared range is taken for an EXCLUSIVE lock):
29492 **
29493 **      PENDING_BYTE        0x40000000
29494 **      RESERVED_BYTE       0x40000001
29495 **      SHARED_RANGE        0x40000002 -> 0x40000200
29496 **
29497 ** This works well on the local file system, but shows a nearly 100x
29498 ** slowdown in read performance on AFP because the AFP client disables
29499 ** the read cache when byte-range locks are present.  Enabling the read
29500 ** cache exposes a cache coherency problem that is present on all OS X
29501 ** supported network file systems.  NFS and AFP both observe the
29502 ** close-to-open semantics for ensuring cache coherency
29503 ** [http://nfs.sourceforge.net/#faq_a8], which does not effectively
29504 ** address the requirements for concurrent database access by multiple
29505 ** readers and writers
29506 ** [http://www.nabble.com/SQLite-on-NFS-cache-coherency-td15655701.html].
29507 **
29508 ** To address the performance and cache coherency issues, proxy file locking
29509 ** changes the way database access is controlled by limiting access to a
29510 ** single host at a time and moving file locks off of the database file
29511 ** and onto a proxy file on the local file system.  
29512 **
29513 **
29514 ** Using proxy locks
29515 ** -----------------
29516 **
29517 ** C APIs
29518 **
29519 **  sqlite3_file_control(db, dbname, SQLITE_SET_LOCKPROXYFILE,
29520 **                       <proxy_path> | ":auto:");
29521 **  sqlite3_file_control(db, dbname, SQLITE_GET_LOCKPROXYFILE, &<proxy_path>);
29522 **
29523 **
29524 ** SQL pragmas
29525 **
29526 **  PRAGMA [database.]lock_proxy_file=<proxy_path> | :auto:
29527 **  PRAGMA [database.]lock_proxy_file
29528 **
29529 ** Specifying ":auto:" means that if there is a conch file with a matching
29530 ** host ID in it, the proxy path in the conch file will be used, otherwise
29531 ** a proxy path based on the user's temp dir
29532 ** (via confstr(_CS_DARWIN_USER_TEMP_DIR,...)) will be used and the
29533 ** actual proxy file name is generated from the name and path of the
29534 ** database file.  For example:
29535 **
29536 **       For database path "/Users/me/foo.db" 
29537 **       The lock path will be "<tmpdir>/sqliteplocks/_Users_me_foo.db:auto:")
29538 **
29539 ** Once a lock proxy is configured for a database connection, it can not
29540 ** be removed, however it may be switched to a different proxy path via
29541 ** the above APIs (assuming the conch file is not being held by another
29542 ** connection or process). 
29543 **
29544 **
29545 ** How proxy locking works
29546 ** -----------------------
29547 **
29548 ** Proxy file locking relies primarily on two new supporting files: 
29549 **
29550 **   *  conch file to limit access to the database file to a single host
29551 **      at a time
29552 **
29553 **   *  proxy file to act as a proxy for the advisory locks normally
29554 **      taken on the database
29555 **
29556 ** The conch file - to use a proxy file, sqlite must first "hold the conch"
29557 ** by taking an sqlite-style shared lock on the conch file, reading the
29558 ** contents and comparing the host's unique host ID (see below) and lock
29559 ** proxy path against the values stored in the conch.  The conch file is
29560 ** stored in the same directory as the database file and the file name
29561 ** is patterned after the database file name as ".<databasename>-conch".
29562 ** If the conch file does not exist, or it's contents do not match the
29563 ** host ID and/or proxy path, then the lock is escalated to an exclusive
29564 ** lock and the conch file contents is updated with the host ID and proxy
29565 ** path and the lock is downgraded to a shared lock again.  If the conch
29566 ** is held by another process (with a shared lock), the exclusive lock
29567 ** will fail and SQLITE_BUSY is returned.
29568 **
29569 ** The proxy file - a single-byte file used for all advisory file locks
29570 ** normally taken on the database file.   This allows for safe sharing
29571 ** of the database file for multiple readers and writers on the same
29572 ** host (the conch ensures that they all use the same local lock file).
29573 **
29574 ** Requesting the lock proxy does not immediately take the conch, it is
29575 ** only taken when the first request to lock database file is made.  
29576 ** This matches the semantics of the traditional locking behavior, where
29577 ** opening a connection to a database file does not take a lock on it.
29578 ** The shared lock and an open file descriptor are maintained until 
29579 ** the connection to the database is closed. 
29580 **
29581 ** The proxy file and the lock file are never deleted so they only need
29582 ** to be created the first time they are used.
29583 **
29584 ** Configuration options
29585 ** ---------------------
29586 **
29587 **  SQLITE_PREFER_PROXY_LOCKING
29588 **
29589 **       Database files accessed on non-local file systems are
29590 **       automatically configured for proxy locking, lock files are
29591 **       named automatically using the same logic as
29592 **       PRAGMA lock_proxy_file=":auto:"
29593 **    
29594 **  SQLITE_PROXY_DEBUG
29595 **
29596 **       Enables the logging of error messages during host id file
29597 **       retrieval and creation
29598 **
29599 **  LOCKPROXYDIR
29600 **
29601 **       Overrides the default directory used for lock proxy files that
29602 **       are named automatically via the ":auto:" setting
29603 **
29604 **  SQLITE_DEFAULT_PROXYDIR_PERMISSIONS
29605 **
29606 **       Permissions to use when creating a directory for storing the
29607 **       lock proxy files, only used when LOCKPROXYDIR is not set.
29608 **    
29609 **    
29610 ** As mentioned above, when compiled with SQLITE_PREFER_PROXY_LOCKING,
29611 ** setting the environment variable SQLITE_FORCE_PROXY_LOCKING to 1 will
29612 ** force proxy locking to be used for every database file opened, and 0
29613 ** will force automatic proxy locking to be disabled for all database
29614 ** files (explicity calling the SQLITE_SET_LOCKPROXYFILE pragma or
29615 ** sqlite_file_control API is not affected by SQLITE_FORCE_PROXY_LOCKING).
29616 */
29617 
29618 /*
29619 ** Proxy locking is only available on MacOSX 
29620 */
29621 #if defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE
29622 
29623 /*
29624 ** The proxyLockingContext has the path and file structures for the remote 
29625 ** and local proxy files in it
29626 */
29627 typedef struct proxyLockingContext proxyLockingContext;
29628 struct proxyLockingContext {
29629   unixFile *conchFile;         /* Open conch file */
29630   char *conchFilePath;         /* Name of the conch file */
29631   unixFile *lockProxy;         /* Open proxy lock file */
29632   char *lockProxyPath;         /* Name of the proxy lock file */
29633   char *dbPath;                /* Name of the open file */
29634   int conchHeld;               /* 1 if the conch is held, -1 if lockless */
29635   void *oldLockingContext;     /* Original lockingcontext to restore on close */
29636   sqlite3_io_methods const *pOldMethod;     /* Original I/O methods for close */
29637 };
29638 
29639 /* 
29640 ** The proxy lock file path for the database at dbPath is written into lPath, 
29641 ** which must point to valid, writable memory large enough for a maxLen length
29642 ** file path. 
29643 */
29644 static int proxyGetLockPath(const char *dbPath, char *lPath, size_t maxLen){
29645   int len;
29646   int dbLen;
29647   int i;
29648 
29649 #ifdef LOCKPROXYDIR
29650   len = strlcpy(lPath, LOCKPROXYDIR, maxLen);
29651 #else
29652 # ifdef _CS_DARWIN_USER_TEMP_DIR
29653   {
29654     if( !confstr(_CS_DARWIN_USER_TEMP_DIR, lPath, maxLen) ){
29655       OSTRACE(("GETLOCKPATH  failed %s errno=%d pid=%d\n",
29656                lPath, errno, getpid()));
29657       return SQLITE_IOERR_LOCK;
29658     }
29659     len = strlcat(lPath, "sqliteplocks", maxLen);    
29660   }
29661 # else
29662   len = strlcpy(lPath, "/tmp/", maxLen);
29663 # endif
29664 #endif
29665 
29666   if( lPath[len-1]!='/' ){
29667     len = strlcat(lPath, "/", maxLen);
29668   }
29669   
29670   /* transform the db path to a unique cache name */
29671   dbLen = (int)strlen(dbPath);
29672   for( i=0; i<dbLen && (i+len+7)<(int)maxLen; i++){
29673     char c = dbPath[i];
29674     lPath[i+len] = (c=='/')?'_':c;
29675   }
29676   lPath[i+len]='\0';
29677   strlcat(lPath, ":auto:", maxLen);
29678   OSTRACE(("GETLOCKPATH  proxy lock path=%s pid=%d\n", lPath, getpid()));
29679   return SQLITE_OK;
29680 }
29681 
29682 /* 
29683  ** Creates the lock file and any missing directories in lockPath
29684  */
29685 static int proxyCreateLockPath(const char *lockPath){
29686   int i, len;
29687   char buf[MAXPATHLEN];
29688   int start = 0;
29689   
29690   assert(lockPath!=NULL);
29691   /* try to create all the intermediate directories */
29692   len = (int)strlen(lockPath);
29693   buf[0] = lockPath[0];
29694   for( i=1; i<len; i++ ){
29695     if( lockPath[i] == '/' && (i - start > 0) ){
29696       /* only mkdir if leaf dir != "." or "/" or ".." */
29697       if( i-start>2 || (i-start==1 && buf[start] != '.' && buf[start] != '/') 
29698          || (i-start==2 && buf[start] != '.' && buf[start+1] != '.') ){
29699         buf[i]='\0';
29700         if( osMkdir(buf, SQLITE_DEFAULT_PROXYDIR_PERMISSIONS) ){
29701           int err=errno;
29702           if( err!=EEXIST ) {
29703             OSTRACE(("CREATELOCKPATH  FAILED creating %s, "
29704                      "'%s' proxy lock path=%s pid=%d\n",
29705                      buf, strerror(err), lockPath, getpid()));
29706             return err;
29707           }
29708         }
29709       }
29710       start=i+1;
29711     }
29712     buf[i] = lockPath[i];
29713   }
29714   OSTRACE(("CREATELOCKPATH  proxy lock path=%s pid=%d\n", lockPath, getpid()));
29715   return 0;
29716 }
29717 
29718 /*
29719 ** Create a new VFS file descriptor (stored in memory obtained from
29720 ** sqlite3_malloc) and open the file named "path" in the file descriptor.
29721 **
29722 ** The caller is responsible not only for closing the file descriptor
29723 ** but also for freeing the memory associated with the file descriptor.
29724 */
29725 static int proxyCreateUnixFile(
29726     const char *path,        /* path for the new unixFile */
29727     unixFile **ppFile,       /* unixFile created and returned by ref */
29728     int islockfile           /* if non zero missing dirs will be created */
29729 ) {
29730   int fd = -1;
29731   unixFile *pNew;
29732   int rc = SQLITE_OK;
29733   int openFlags = O_RDWR | O_CREAT;
29734   sqlite3_vfs dummyVfs;
29735   int terrno = 0;
29736   UnixUnusedFd *pUnused = NULL;
29737 
29738   /* 1. first try to open/create the file
29739   ** 2. if that fails, and this is a lock file (not-conch), try creating
29740   ** the parent directories and then try again.
29741   ** 3. if that fails, try to open the file read-only
29742   ** otherwise return BUSY (if lock file) or CANTOPEN for the conch file
29743   */
29744   pUnused = findReusableFd(path, openFlags);
29745   if( pUnused ){
29746     fd = pUnused->fd;
29747   }else{
29748     pUnused = sqlite3_malloc(sizeof(*pUnused));
29749     if( !pUnused ){
29750       return SQLITE_NOMEM;
29751     }
29752   }
29753   if( fd<0 ){
29754     fd = robust_open(path, openFlags, 0);
29755     terrno = errno;
29756     if( fd<0 && errno==ENOENT && islockfile ){
29757       if( proxyCreateLockPath(path) == SQLITE_OK ){
29758         fd = robust_open(path, openFlags, 0);
29759       }
29760     }
29761   }
29762   if( fd<0 ){
29763     openFlags = O_RDONLY;
29764     fd = robust_open(path, openFlags, 0);
29765     terrno = errno;
29766   }
29767   if( fd<0 ){
29768     if( islockfile ){
29769       return SQLITE_BUSY;
29770     }
29771     switch (terrno) {
29772       case EACCES:
29773         return SQLITE_PERM;
29774       case EIO: 
29775         return SQLITE_IOERR_LOCK; /* even though it is the conch */
29776       default:
29777         return SQLITE_CANTOPEN_BKPT;
29778     }
29779   }
29780   
29781   pNew = (unixFile *)sqlite3_malloc(sizeof(*pNew));
29782   if( pNew==NULL ){
29783     rc = SQLITE_NOMEM;
29784     goto end_create_proxy;
29785   }
29786   memset(pNew, 0, sizeof(unixFile));
29787   pNew->openFlags = openFlags;
29788   memset(&dummyVfs, 0, sizeof(dummyVfs));
29789   dummyVfs.pAppData = (void*)&autolockIoFinder;
29790   dummyVfs.zName = "dummy";
29791   pUnused->fd = fd;
29792   pUnused->flags = openFlags;
29793   pNew->pUnused = pUnused;
29794   
29795   rc = fillInUnixFile(&dummyVfs, fd, (sqlite3_file*)pNew, path, 0);
29796   if( rc==SQLITE_OK ){
29797     *ppFile = pNew;
29798     return SQLITE_OK;
29799   }
29800 end_create_proxy:    
29801   robust_close(pNew, fd, __LINE__);
29802   sqlite3_free(pNew);
29803   sqlite3_free(pUnused);
29804   return rc;
29805 }
29806 
29807 #ifdef SQLITE_TEST
29808 /* simulate multiple hosts by creating unique hostid file paths */
29809 SQLITE_API int sqlite3_hostid_num = 0;
29810 #endif
29811 
29812 #define PROXY_HOSTIDLEN    16  /* conch file host id length */
29813 
29814 /* Not always defined in the headers as it ought to be */
29815 extern int gethostuuid(uuid_t id, const struct timespec *wait);
29816 
29817 /* get the host ID via gethostuuid(), pHostID must point to PROXY_HOSTIDLEN 
29818 ** bytes of writable memory.
29819 */
29820 static int proxyGetHostID(unsigned char *pHostID, int *pError){
29821   assert(PROXY_HOSTIDLEN == sizeof(uuid_t));
29822   memset(pHostID, 0, PROXY_HOSTIDLEN);
29823 #if defined(__MAX_OS_X_VERSION_MIN_REQUIRED)\
29824                && __MAC_OS_X_VERSION_MIN_REQUIRED<1050
29825   {
29826     static const struct timespec timeout = {1, 0}; /* 1 sec timeout */
29827     if( gethostuuid(pHostID, &timeout) ){
29828       int err = errno;
29829       if( pError ){
29830         *pError = err;
29831       }
29832       return SQLITE_IOERR;
29833     }
29834   }
29835 #else
29836   UNUSED_PARAMETER(pError);
29837 #endif
29838 #ifdef SQLITE_TEST
29839   /* simulate multiple hosts by creating unique hostid file paths */
29840   if( sqlite3_hostid_num != 0){
29841     pHostID[0] = (char)(pHostID[0] + (char)(sqlite3_hostid_num & 0xFF));
29842   }
29843 #endif
29844   
29845   return SQLITE_OK;
29846 }
29847 
29848 /* The conch file contains the header, host id and lock file path
29849  */
29850 #define PROXY_CONCHVERSION 2   /* 1-byte header, 16-byte host id, path */
29851 #define PROXY_HEADERLEN    1   /* conch file header length */
29852 #define PROXY_PATHINDEX    (PROXY_HEADERLEN+PROXY_HOSTIDLEN)
29853 #define PROXY_MAXCONCHLEN  (PROXY_HEADERLEN+PROXY_HOSTIDLEN+MAXPATHLEN)
29854 
29855 /* 
29856 ** Takes an open conch file, copies the contents to a new path and then moves 
29857 ** it back.  The newly created file's file descriptor is assigned to the
29858 ** conch file structure and finally the original conch file descriptor is 
29859 ** closed.  Returns zero if successful.
29860 */
29861 static int proxyBreakConchLock(unixFile *pFile, uuid_t myHostID){
29862   proxyLockingContext *pCtx = (proxyLockingContext *)pFile->lockingContext; 
29863   unixFile *conchFile = pCtx->conchFile;
29864   char tPath[MAXPATHLEN];
29865   char buf[PROXY_MAXCONCHLEN];
29866   char *cPath = pCtx->conchFilePath;
29867   size_t readLen = 0;
29868   size_t pathLen = 0;
29869   char errmsg[64] = "";
29870   int fd = -1;
29871   int rc = -1;
29872   UNUSED_PARAMETER(myHostID);
29873 
29874   /* create a new path by replace the trailing '-conch' with '-break' */
29875   pathLen = strlcpy(tPath, cPath, MAXPATHLEN);
29876   if( pathLen>MAXPATHLEN || pathLen<6 || 
29877      (strlcpy(&tPath[pathLen-5], "break", 6) != 5) ){
29878     sqlite3_snprintf(sizeof(errmsg),errmsg,"path error (len %d)",(int)pathLen);
29879     goto end_breaklock;
29880   }
29881   /* read the conch content */
29882   readLen = osPread(conchFile->h, buf, PROXY_MAXCONCHLEN, 0);
29883   if( readLen<PROXY_PATHINDEX ){
29884     sqlite3_snprintf(sizeof(errmsg),errmsg,"read error (len %d)",(int)readLen);
29885     goto end_breaklock;
29886   }
29887   /* write it out to the temporary break file */
29888   fd = robust_open(tPath, (O_RDWR|O_CREAT|O_EXCL), 0);
29889   if( fd<0 ){
29890     sqlite3_snprintf(sizeof(errmsg), errmsg, "create failed (%d)", errno);
29891     goto end_breaklock;
29892   }
29893   if( osPwrite(fd, buf, readLen, 0) != (ssize_t)readLen ){
29894     sqlite3_snprintf(sizeof(errmsg), errmsg, "write failed (%d)", errno);
29895     goto end_breaklock;
29896   }
29897   if( rename(tPath, cPath) ){
29898     sqlite3_snprintf(sizeof(errmsg), errmsg, "rename failed (%d)", errno);
29899     goto end_breaklock;
29900   }
29901   rc = 0;
29902   fprintf(stderr, "broke stale lock on %s\n", cPath);
29903   robust_close(pFile, conchFile->h, __LINE__);
29904   conchFile->h = fd;
29905   conchFile->openFlags = O_RDWR | O_CREAT;
29906 
29907 end_breaklock:
29908   if( rc ){
29909     if( fd>=0 ){
29910       osUnlink(tPath);
29911       robust_close(pFile, fd, __LINE__);
29912     }
29913     fprintf(stderr, "failed to break stale lock on %s, %s\n", cPath, errmsg);
29914   }
29915   return rc;
29916 }
29917 
29918 /* Take the requested lock on the conch file and break a stale lock if the 
29919 ** host id matches.
29920 */
29921 static int proxyConchLock(unixFile *pFile, uuid_t myHostID, int lockType){
29922   proxyLockingContext *pCtx = (proxyLockingContext *)pFile->lockingContext; 
29923   unixFile *conchFile = pCtx->conchFile;
29924   int rc = SQLITE_OK;
29925   int nTries = 0;
29926   struct timespec conchModTime;
29927   
29928   memset(&conchModTime, 0, sizeof(conchModTime));
29929   do {
29930     rc = conchFile->pMethod->xLock((sqlite3_file*)conchFile, lockType);
29931     nTries ++;
29932     if( rc==SQLITE_BUSY ){
29933       /* If the lock failed (busy):
29934        * 1st try: get the mod time of the conch, wait 0.5s and try again. 
29935        * 2nd try: fail if the mod time changed or host id is different, wait 
29936        *           10 sec and try again
29937        * 3rd try: break the lock unless the mod time has changed.
29938        */
29939       struct stat buf;
29940       if( osFstat(conchFile->h, &buf) ){
29941         pFile->lastErrno = errno;
29942         return SQLITE_IOERR_LOCK;
29943       }
29944       
29945       if( nTries==1 ){
29946         conchModTime = buf.st_mtimespec;
29947         usleep(500000); /* wait 0.5 sec and try the lock again*/
29948         continue;  
29949       }
29950 
29951       assert( nTries>1 );
29952       if( conchModTime.tv_sec != buf.st_mtimespec.tv_sec || 
29953          conchModTime.tv_nsec != buf.st_mtimespec.tv_nsec ){
29954         return SQLITE_BUSY;
29955       }
29956       
29957       if( nTries==2 ){  
29958         char tBuf[PROXY_MAXCONCHLEN];
29959         int len = osPread(conchFile->h, tBuf, PROXY_MAXCONCHLEN, 0);
29960         if( len<0 ){
29961           pFile->lastErrno = errno;
29962           return SQLITE_IOERR_LOCK;
29963         }
29964         if( len>PROXY_PATHINDEX && tBuf[0]==(char)PROXY_CONCHVERSION){
29965           /* don't break the lock if the host id doesn't match */
29966           if( 0!=memcmp(&tBuf[PROXY_HEADERLEN], myHostID, PROXY_HOSTIDLEN) ){
29967             return SQLITE_BUSY;
29968           }
29969         }else{
29970           /* don't break the lock on short read or a version mismatch */
29971           return SQLITE_BUSY;
29972         }
29973         usleep(10000000); /* wait 10 sec and try the lock again */
29974         continue; 
29975       }
29976       
29977       assert( nTries==3 );
29978       if( 0==proxyBreakConchLock(pFile, myHostID) ){
29979         rc = SQLITE_OK;
29980         if( lockType==EXCLUSIVE_LOCK ){
29981           rc = conchFile->pMethod->xLock((sqlite3_file*)conchFile, SHARED_LOCK);          
29982         }
29983         if( !rc ){
29984           rc = conchFile->pMethod->xLock((sqlite3_file*)conchFile, lockType);
29985         }
29986       }
29987     }
29988   } while( rc==SQLITE_BUSY && nTries<3 );
29989   
29990   return rc;
29991 }
29992 
29993 /* Takes the conch by taking a shared lock and read the contents conch, if 
29994 ** lockPath is non-NULL, the host ID and lock file path must match.  A NULL 
29995 ** lockPath means that the lockPath in the conch file will be used if the 
29996 ** host IDs match, or a new lock path will be generated automatically 
29997 ** and written to the conch file.
29998 */
29999 static int proxyTakeConch(unixFile *pFile){
30000   proxyLockingContext *pCtx = (proxyLockingContext *)pFile->lockingContext; 
30001   
30002   if( pCtx->conchHeld!=0 ){
30003     return SQLITE_OK;
30004   }else{
30005     unixFile *conchFile = pCtx->conchFile;
30006     uuid_t myHostID;
30007     int pError = 0;
30008     char readBuf[PROXY_MAXCONCHLEN];
30009     char lockPath[MAXPATHLEN];
30010     char *tempLockPath = NULL;
30011     int rc = SQLITE_OK;
30012     int createConch = 0;
30013     int hostIdMatch = 0;
30014     int readLen = 0;
30015     int tryOldLockPath = 0;
30016     int forceNewLockPath = 0;
30017     
30018     OSTRACE(("TAKECONCH  %d for %s pid=%d\n", conchFile->h,
30019              (pCtx->lockProxyPath ? pCtx->lockProxyPath : ":auto:"), getpid()));
30020 
30021     rc = proxyGetHostID(myHostID, &pError);
30022     if( (rc&0xff)==SQLITE_IOERR ){
30023       pFile->lastErrno = pError;
30024       goto end_takeconch;
30025     }
30026     rc = proxyConchLock(pFile, myHostID, SHARED_LOCK);
30027     if( rc!=SQLITE_OK ){
30028       goto end_takeconch;
30029     }
30030     /* read the existing conch file */
30031     readLen = seekAndRead((unixFile*)conchFile, 0, readBuf, PROXY_MAXCONCHLEN);
30032     if( readLen<0 ){
30033       /* I/O error: lastErrno set by seekAndRead */
30034       pFile->lastErrno = conchFile->lastErrno;
30035       rc = SQLITE_IOERR_READ;
30036       goto end_takeconch;
30037     }else if( readLen<=(PROXY_HEADERLEN+PROXY_HOSTIDLEN) || 
30038              readBuf[0]!=(char)PROXY_CONCHVERSION ){
30039       /* a short read or version format mismatch means we need to create a new 
30040       ** conch file. 
30041       */
30042       createConch = 1;
30043     }
30044     /* if the host id matches and the lock path already exists in the conch
30045     ** we'll try to use the path there, if we can't open that path, we'll 
30046     ** retry with a new auto-generated path 
30047     */
30048     do { /* in case we need to try again for an :auto: named lock file */
30049 
30050       if( !createConch && !forceNewLockPath ){
30051         hostIdMatch = !memcmp(&readBuf[PROXY_HEADERLEN], myHostID, 
30052                                   PROXY_HOSTIDLEN);
30053         /* if the conch has data compare the contents */
30054         if( !pCtx->lockProxyPath ){
30055           /* for auto-named local lock file, just check the host ID and we'll
30056            ** use the local lock file path that's already in there
30057            */
30058           if( hostIdMatch ){
30059             size_t pathLen = (readLen - PROXY_PATHINDEX);
30060             
30061             if( pathLen>=MAXPATHLEN ){
30062               pathLen=MAXPATHLEN-1;
30063             }
30064             memcpy(lockPath, &readBuf[PROXY_PATHINDEX], pathLen);
30065             lockPath[pathLen] = 0;
30066             tempLockPath = lockPath;
30067             tryOldLockPath = 1;
30068             /* create a copy of the lock path if the conch is taken */
30069             goto end_takeconch;
30070           }
30071         }else if( hostIdMatch
30072                && !strncmp(pCtx->lockProxyPath, &readBuf[PROXY_PATHINDEX],
30073                            readLen-PROXY_PATHINDEX)
30074         ){
30075           /* conch host and lock path match */
30076           goto end_takeconch; 
30077         }
30078       }
30079       
30080       /* if the conch isn't writable and doesn't match, we can't take it */
30081       if( (conchFile->openFlags&O_RDWR) == 0 ){
30082         rc = SQLITE_BUSY;
30083         goto end_takeconch;
30084       }
30085       
30086       /* either the conch didn't match or we need to create a new one */
30087       if( !pCtx->lockProxyPath ){
30088         proxyGetLockPath(pCtx->dbPath, lockPath, MAXPATHLEN);
30089         tempLockPath = lockPath;
30090         /* create a copy of the lock path _only_ if the conch is taken */
30091       }
30092       
30093       /* update conch with host and path (this will fail if other process
30094       ** has a shared lock already), if the host id matches, use the big
30095       ** stick.
30096       */
30097       futimes(conchFile->h, NULL);
30098       if( hostIdMatch && !createConch ){
30099         if( conchFile->pInode && conchFile->pInode->nShared>1 ){
30100           /* We are trying for an exclusive lock but another thread in this
30101            ** same process is still holding a shared lock. */
30102           rc = SQLITE_BUSY;
30103         } else {          
30104           rc = proxyConchLock(pFile, myHostID, EXCLUSIVE_LOCK);
30105         }
30106       }else{
30107         rc = conchFile->pMethod->xLock((sqlite3_file*)conchFile, EXCLUSIVE_LOCK);
30108       }
30109       if( rc==SQLITE_OK ){
30110         char writeBuffer[PROXY_MAXCONCHLEN];
30111         int writeSize = 0;
30112         
30113         writeBuffer[0] = (char)PROXY_CONCHVERSION;
30114         memcpy(&writeBuffer[PROXY_HEADERLEN], myHostID, PROXY_HOSTIDLEN);
30115         if( pCtx->lockProxyPath!=NULL ){
30116           strlcpy(&writeBuffer[PROXY_PATHINDEX], pCtx->lockProxyPath, MAXPATHLEN);
30117         }else{
30118           strlcpy(&writeBuffer[PROXY_PATHINDEX], tempLockPath, MAXPATHLEN);
30119         }
30120         writeSize = PROXY_PATHINDEX + strlen(&writeBuffer[PROXY_PATHINDEX]);
30121         robust_ftruncate(conchFile->h, writeSize);
30122         rc = unixWrite((sqlite3_file *)conchFile, writeBuffer, writeSize, 0);
30123         fsync(conchFile->h);
30124         /* If we created a new conch file (not just updated the contents of a 
30125          ** valid conch file), try to match the permissions of the database 
30126          */
30127         if( rc==SQLITE_OK && createConch ){
30128           struct stat buf;
30129           int err = osFstat(pFile->h, &buf);
30130           if( err==0 ){
30131             mode_t cmode = buf.st_mode&(S_IRUSR|S_IWUSR | S_IRGRP|S_IWGRP |
30132                                         S_IROTH|S_IWOTH);
30133             /* try to match the database file R/W permissions, ignore failure */
30134 #ifndef SQLITE_PROXY_DEBUG
30135             osFchmod(conchFile->h, cmode);
30136 #else
30137             do{
30138               rc = osFchmod(conchFile->h, cmode);
30139             }while( rc==(-1) && errno==EINTR );
30140             if( rc!=0 ){
30141               int code = errno;
30142               fprintf(stderr, "fchmod %o FAILED with %d %s\n",
30143                       cmode, code, strerror(code));
30144             } else {
30145               fprintf(stderr, "fchmod %o SUCCEDED\n",cmode);
30146             }
30147           }else{
30148             int code = errno;
30149             fprintf(stderr, "STAT FAILED[%d] with %d %s\n", 
30150                     err, code, strerror(code));
30151 #endif
30152           }
30153         }
30154       }
30155       conchFile->pMethod->xUnlock((sqlite3_file*)conchFile, SHARED_LOCK);
30156       
30157     end_takeconch:
30158       OSTRACE(("TRANSPROXY: CLOSE  %d\n", pFile->h));
30159       if( rc==SQLITE_OK && pFile->openFlags ){
30160         int fd;
30161         if( pFile->h>=0 ){
30162           robust_close(pFile, pFile->h, __LINE__);
30163         }
30164         pFile->h = -1;
30165         fd = robust_open(pCtx->dbPath, pFile->openFlags, 0);
30166         OSTRACE(("TRANSPROXY: OPEN  %d\n", fd));
30167         if( fd>=0 ){
30168           pFile->h = fd;
30169         }else{
30170           rc=SQLITE_CANTOPEN_BKPT; /* SQLITE_BUSY? proxyTakeConch called
30171            during locking */
30172         }
30173       }
30174       if( rc==SQLITE_OK && !pCtx->lockProxy ){
30175         char *path = tempLockPath ? tempLockPath : pCtx->lockProxyPath;
30176         rc = proxyCreateUnixFile(path, &pCtx->lockProxy, 1);
30177         if( rc!=SQLITE_OK && rc!=SQLITE_NOMEM && tryOldLockPath ){
30178           /* we couldn't create the proxy lock file with the old lock file path
30179            ** so try again via auto-naming 
30180            */
30181           forceNewLockPath = 1;
30182           tryOldLockPath = 0;
30183           continue; /* go back to the do {} while start point, try again */
30184         }
30185       }
30186       if( rc==SQLITE_OK ){
30187         /* Need to make a copy of path if we extracted the value
30188          ** from the conch file or the path was allocated on the stack
30189          */
30190         if( tempLockPath ){
30191           pCtx->lockProxyPath = sqlite3DbStrDup(0, tempLockPath);
30192           if( !pCtx->lockProxyPath ){
30193             rc = SQLITE_NOMEM;
30194           }
30195         }
30196       }
30197       if( rc==SQLITE_OK ){
30198         pCtx->conchHeld = 1;
30199         
30200         if( pCtx->lockProxy->pMethod == &afpIoMethods ){
30201           afpLockingContext *afpCtx;
30202           afpCtx = (afpLockingContext *)pCtx->lockProxy->lockingContext;
30203           afpCtx->dbPath = pCtx->lockProxyPath;
30204         }
30205       } else {
30206         conchFile->pMethod->xUnlock((sqlite3_file*)conchFile, NO_LOCK);
30207       }
30208       OSTRACE(("TAKECONCH  %d %s\n", conchFile->h,
30209                rc==SQLITE_OK?"ok":"failed"));
30210       return rc;
30211     } while (1); /* in case we need to retry the :auto: lock file - 
30212                  ** we should never get here except via the 'continue' call. */
30213   }
30214 }
30215 
30216 /*
30217 ** If pFile holds a lock on a conch file, then release that lock.
30218 */
30219 static int proxyReleaseConch(unixFile *pFile){
30220   int rc = SQLITE_OK;         /* Subroutine return code */
30221   proxyLockingContext *pCtx;  /* The locking context for the proxy lock */
30222   unixFile *conchFile;        /* Name of the conch file */
30223 
30224   pCtx = (proxyLockingContext *)pFile->lockingContext;
30225   conchFile = pCtx->conchFile;
30226   OSTRACE(("RELEASECONCH  %d for %s pid=%d\n", conchFile->h,
30227            (pCtx->lockProxyPath ? pCtx->lockProxyPath : ":auto:"), 
30228            getpid()));
30229   if( pCtx->conchHeld>0 ){
30230     rc = conchFile->pMethod->xUnlock((sqlite3_file*)conchFile, NO_LOCK);
30231   }
30232   pCtx->conchHeld = 0;
30233   OSTRACE(("RELEASECONCH  %d %s\n", conchFile->h,
30234            (rc==SQLITE_OK ? "ok" : "failed")));
30235   return rc;
30236 }
30237 
30238 /*
30239 ** Given the name of a database file, compute the name of its conch file.
30240 ** Store the conch filename in memory obtained from sqlite3_malloc().
30241 ** Make *pConchPath point to the new name.  Return SQLITE_OK on success
30242 ** or SQLITE_NOMEM if unable to obtain memory.
30243 **
30244 ** The caller is responsible for ensuring that the allocated memory
30245 ** space is eventually freed.
30246 **
30247 ** *pConchPath is set to NULL if a memory allocation error occurs.
30248 */
30249 static int proxyCreateConchPathname(char *dbPath, char **pConchPath){
30250   int i;                        /* Loop counter */
30251   int len = (int)strlen(dbPath); /* Length of database filename - dbPath */
30252   char *conchPath;              /* buffer in which to construct conch name */
30253 
30254   /* Allocate space for the conch filename and initialize the name to
30255   ** the name of the original database file. */  
30256   *pConchPath = conchPath = (char *)sqlite3_malloc(len + 8);
30257   if( conchPath==0 ){
30258     return SQLITE_NOMEM;
30259   }
30260   memcpy(conchPath, dbPath, len+1);
30261   
30262   /* now insert a "." before the last / character */
30263   for( i=(len-1); i>=0; i-- ){
30264     if( conchPath[i]=='/' ){
30265       i++;
30266       break;
30267     }
30268   }
30269   conchPath[i]='.';
30270   while ( i<len ){
30271     conchPath[i+1]=dbPath[i];
30272     i++;
30273   }
30274 
30275   /* append the "-conch" suffix to the file */
30276   memcpy(&conchPath[i+1], "-conch", 7);
30277   assert( (int)strlen(conchPath) == len+7 );
30278 
30279   return SQLITE_OK;
30280 }
30281 
30282 
30283 /* Takes a fully configured proxy locking-style unix file and switches
30284 ** the local lock file path 
30285 */
30286 static int switchLockProxyPath(unixFile *pFile, const char *path) {
30287   proxyLockingContext *pCtx = (proxyLockingContext*)pFile->lockingContext;
30288   char *oldPath = pCtx->lockProxyPath;
30289   int rc = SQLITE_OK;
30290 
30291   if( pFile->eFileLock!=NO_LOCK ){
30292     return SQLITE_BUSY;
30293   }  
30294 
30295   /* nothing to do if the path is NULL, :auto: or matches the existing path */
30296   if( !path || path[0]=='\0' || !strcmp(path, ":auto:") ||
30297     (oldPath && !strncmp(oldPath, path, MAXPATHLEN)) ){
30298     return SQLITE_OK;
30299   }else{
30300     unixFile *lockProxy = pCtx->lockProxy;
30301     pCtx->lockProxy=NULL;
30302     pCtx->conchHeld = 0;
30303     if( lockProxy!=NULL ){
30304       rc=lockProxy->pMethod->xClose((sqlite3_file *)lockProxy);
30305       if( rc ) return rc;
30306       sqlite3_free(lockProxy);
30307     }
30308     sqlite3_free(oldPath);
30309     pCtx->lockProxyPath = sqlite3DbStrDup(0, path);
30310   }
30311   
30312   return rc;
30313 }
30314 
30315 /*
30316 ** pFile is a file that has been opened by a prior xOpen call.  dbPath
30317 ** is a string buffer at least MAXPATHLEN+1 characters in size.
30318 **
30319 ** This routine find the filename associated with pFile and writes it
30320 ** int dbPath.
30321 */
30322 static int proxyGetDbPathForUnixFile(unixFile *pFile, char *dbPath){
30323 #if defined(__APPLE__)
30324   if( pFile->pMethod == &afpIoMethods ){
30325     /* afp style keeps a reference to the db path in the filePath field 
30326     ** of the struct */
30327     assert( (int)strlen((char*)pFile->lockingContext)<=MAXPATHLEN );
30328     strlcpy(dbPath, ((afpLockingContext *)pFile->lockingContext)->dbPath, MAXPATHLEN);
30329   } else
30330 #endif
30331   if( pFile->pMethod == &dotlockIoMethods ){
30332     /* dot lock style uses the locking context to store the dot lock
30333     ** file path */
30334     int len = strlen((char *)pFile->lockingContext) - strlen(DOTLOCK_SUFFIX);
30335     memcpy(dbPath, (char *)pFile->lockingContext, len + 1);
30336   }else{
30337     /* all other styles use the locking context to store the db file path */
30338     assert( strlen((char*)pFile->lockingContext)<=MAXPATHLEN );
30339     strlcpy(dbPath, (char *)pFile->lockingContext, MAXPATHLEN);
30340   }
30341   return SQLITE_OK;
30342 }
30343 
30344 /*
30345 ** Takes an already filled in unix file and alters it so all file locking 
30346 ** will be performed on the local proxy lock file.  The following fields
30347 ** are preserved in the locking context so that they can be restored and 
30348 ** the unix structure properly cleaned up at close time:
30349 **  ->lockingContext
30350 **  ->pMethod
30351 */
30352 static int proxyTransformUnixFile(unixFile *pFile, const char *path) {
30353   proxyLockingContext *pCtx;
30354   char dbPath[MAXPATHLEN+1];       /* Name of the database file */
30355   char *lockPath=NULL;
30356   int rc = SQLITE_OK;
30357   
30358   if( pFile->eFileLock!=NO_LOCK ){
30359     return SQLITE_BUSY;
30360   }
30361   proxyGetDbPathForUnixFile(pFile, dbPath);
30362   if( !path || path[0]=='\0' || !strcmp(path, ":auto:") ){
30363     lockPath=NULL;
30364   }else{
30365     lockPath=(char *)path;
30366   }
30367   
30368   OSTRACE(("TRANSPROXY  %d for %s pid=%d\n", pFile->h,
30369            (lockPath ? lockPath : ":auto:"), getpid()));
30370 
30371   pCtx = sqlite3_malloc( sizeof(*pCtx) );
30372   if( pCtx==0 ){
30373     return SQLITE_NOMEM;
30374   }
30375   memset(pCtx, 0, sizeof(*pCtx));
30376 
30377   rc = proxyCreateConchPathname(dbPath, &pCtx->conchFilePath);
30378   if( rc==SQLITE_OK ){
30379     rc = proxyCreateUnixFile(pCtx->conchFilePath, &pCtx->conchFile, 0);
30380     if( rc==SQLITE_CANTOPEN && ((pFile->openFlags&O_RDWR) == 0) ){
30381       /* if (a) the open flags are not O_RDWR, (b) the conch isn't there, and
30382       ** (c) the file system is read-only, then enable no-locking access.
30383       ** Ugh, since O_RDONLY==0x0000 we test for !O_RDWR since unixOpen asserts
30384       ** that openFlags will have only one of O_RDONLY or O_RDWR.
30385       */
30386       struct statfs fsInfo;
30387       struct stat conchInfo;
30388       int goLockless = 0;
30389 
30390       if( osStat(pCtx->conchFilePath, &conchInfo) == -1 ) {
30391         int err = errno;
30392         if( (err==ENOENT) && (statfs(dbPath, &fsInfo) != -1) ){
30393           goLockless = (fsInfo.f_flags&MNT_RDONLY) == MNT_RDONLY;
30394         }
30395       }
30396       if( goLockless ){
30397         pCtx->conchHeld = -1; /* read only FS/ lockless */
30398         rc = SQLITE_OK;
30399       }
30400     }
30401   }  
30402   if( rc==SQLITE_OK && lockPath ){
30403     pCtx->lockProxyPath = sqlite3DbStrDup(0, lockPath);
30404   }
30405 
30406   if( rc==SQLITE_OK ){
30407     pCtx->dbPath = sqlite3DbStrDup(0, dbPath);
30408     if( pCtx->dbPath==NULL ){
30409       rc = SQLITE_NOMEM;
30410     }
30411   }
30412   if( rc==SQLITE_OK ){
30413     /* all memory is allocated, proxys are created and assigned, 
30414     ** switch the locking context and pMethod then return.
30415     */
30416     pCtx->oldLockingContext = pFile->lockingContext;
30417     pFile->lockingContext = pCtx;
30418     pCtx->pOldMethod = pFile->pMethod;
30419     pFile->pMethod = &proxyIoMethods;
30420   }else{
30421     if( pCtx->conchFile ){ 
30422       pCtx->conchFile->pMethod->xClose((sqlite3_file *)pCtx->conchFile);
30423       sqlite3_free(pCtx->conchFile);
30424     }
30425     sqlite3DbFree(0, pCtx->lockProxyPath);
30426     sqlite3_free(pCtx->conchFilePath); 
30427     sqlite3_free(pCtx);
30428   }
30429   OSTRACE(("TRANSPROXY  %d %s\n", pFile->h,
30430            (rc==SQLITE_OK ? "ok" : "failed")));
30431   return rc;
30432 }
30433 
30434 
30435 /*
30436 ** This routine handles sqlite3_file_control() calls that are specific
30437 ** to proxy locking.
30438 */
30439 static int proxyFileControl(sqlite3_file *id, int op, void *pArg){
30440   switch( op ){
30441     case SQLITE_GET_LOCKPROXYFILE: {
30442       unixFile *pFile = (unixFile*)id;
30443       if( pFile->pMethod == &proxyIoMethods ){
30444         proxyLockingContext *pCtx = (proxyLockingContext*)pFile->lockingContext;
30445         proxyTakeConch(pFile);
30446         if( pCtx->lockProxyPath ){
30447           *(const char **)pArg = pCtx->lockProxyPath;
30448         }else{
30449           *(const char **)pArg = ":auto: (not held)";
30450         }
30451       } else {
30452         *(const char **)pArg = NULL;
30453       }
30454       return SQLITE_OK;
30455     }
30456     case SQLITE_SET_LOCKPROXYFILE: {
30457       unixFile *pFile = (unixFile*)id;
30458       int rc = SQLITE_OK;
30459       int isProxyStyle = (pFile->pMethod == &proxyIoMethods);
30460       if( pArg==NULL || (const char *)pArg==0 ){
30461         if( isProxyStyle ){
30462           /* turn off proxy locking - not supported */
30463           rc = SQLITE_ERROR /*SQLITE_PROTOCOL? SQLITE_MISUSE?*/;
30464         }else{
30465           /* turn off proxy locking - already off - NOOP */
30466           rc = SQLITE_OK;
30467         }
30468       }else{
30469         const char *proxyPath = (const char *)pArg;
30470         if( isProxyStyle ){
30471           proxyLockingContext *pCtx = 
30472             (proxyLockingContext*)pFile->lockingContext;
30473           if( !strcmp(pArg, ":auto:") 
30474            || (pCtx->lockProxyPath &&
30475                !strncmp(pCtx->lockProxyPath, proxyPath, MAXPATHLEN))
30476           ){
30477             rc = SQLITE_OK;
30478           }else{
30479             rc = switchLockProxyPath(pFile, proxyPath);
30480           }
30481         }else{
30482           /* turn on proxy file locking */
30483           rc = proxyTransformUnixFile(pFile, proxyPath);
30484         }
30485       }
30486       return rc;
30487     }
30488     default: {
30489       assert( 0 );  /* The call assures that only valid opcodes are sent */
30490     }
30491   }
30492   /*NOTREACHED*/
30493   return SQLITE_ERROR;
30494 }
30495 
30496 /*
30497 ** Within this division (the proxying locking implementation) the procedures
30498 ** above this point are all utilities.  The lock-related methods of the
30499 ** proxy-locking sqlite3_io_method object follow.
30500 */
30501 
30502 
30503 /*
30504 ** This routine checks if there is a RESERVED lock held on the specified
30505 ** file by this or any other process. If such a lock is held, set *pResOut
30506 ** to a non-zero value otherwise *pResOut is set to zero.  The return value
30507 ** is set to SQLITE_OK unless an I/O error occurs during lock checking.
30508 */
30509 static int proxyCheckReservedLock(sqlite3_file *id, int *pResOut) {
30510   unixFile *pFile = (unixFile*)id;
30511   int rc = proxyTakeConch(pFile);
30512   if( rc==SQLITE_OK ){
30513     proxyLockingContext *pCtx = (proxyLockingContext *)pFile->lockingContext;
30514     if( pCtx->conchHeld>0 ){
30515       unixFile *proxy = pCtx->lockProxy;
30516       return proxy->pMethod->xCheckReservedLock((sqlite3_file*)proxy, pResOut);
30517     }else{ /* conchHeld < 0 is lockless */
30518       pResOut=0;
30519     }
30520   }
30521   return rc;
30522 }
30523 
30524 /*
30525 ** Lock the file with the lock specified by parameter eFileLock - one
30526 ** of the following:
30527 **
30528 **     (1) SHARED_LOCK
30529 **     (2) RESERVED_LOCK
30530 **     (3) PENDING_LOCK
30531 **     (4) EXCLUSIVE_LOCK
30532 **
30533 ** Sometimes when requesting one lock state, additional lock states
30534 ** are inserted in between.  The locking might fail on one of the later
30535 ** transitions leaving the lock state different from what it started but
30536 ** still short of its goal.  The following chart shows the allowed
30537 ** transitions and the inserted intermediate states:
30538 **
30539 **    UNLOCKED -> SHARED
30540 **    SHARED -> RESERVED
30541 **    SHARED -> (PENDING) -> EXCLUSIVE
30542 **    RESERVED -> (PENDING) -> EXCLUSIVE
30543 **    PENDING -> EXCLUSIVE
30544 **
30545 ** This routine will only increase a lock.  Use the sqlite3OsUnlock()
30546 ** routine to lower a locking level.
30547 */
30548 static int proxyLock(sqlite3_file *id, int eFileLock) {
30549   unixFile *pFile = (unixFile*)id;
30550   int rc = proxyTakeConch(pFile);
30551   if( rc==SQLITE_OK ){
30552     proxyLockingContext *pCtx = (proxyLockingContext *)pFile->lockingContext;
30553     if( pCtx->conchHeld>0 ){
30554       unixFile *proxy = pCtx->lockProxy;
30555       rc = proxy->pMethod->xLock((sqlite3_file*)proxy, eFileLock);
30556       pFile->eFileLock = proxy->eFileLock;
30557     }else{
30558       /* conchHeld < 0 is lockless */
30559     }
30560   }
30561   return rc;
30562 }
30563 
30564 
30565 /*
30566 ** Lower the locking level on file descriptor pFile to eFileLock.  eFileLock
30567 ** must be either NO_LOCK or SHARED_LOCK.
30568 **
30569 ** If the locking level of the file descriptor is already at or below
30570 ** the requested locking level, this routine is a no-op.
30571 */
30572 static int proxyUnlock(sqlite3_file *id, int eFileLock) {
30573   unixFile *pFile = (unixFile*)id;
30574   int rc = proxyTakeConch(pFile);
30575   if( rc==SQLITE_OK ){
30576     proxyLockingContext *pCtx = (proxyLockingContext *)pFile->lockingContext;
30577     if( pCtx->conchHeld>0 ){
30578       unixFile *proxy = pCtx->lockProxy;
30579       rc = proxy->pMethod->xUnlock((sqlite3_file*)proxy, eFileLock);
30580       pFile->eFileLock = proxy->eFileLock;
30581     }else{
30582       /* conchHeld < 0 is lockless */
30583     }
30584   }
30585   return rc;
30586 }
30587 
30588 /*
30589 ** Close a file that uses proxy locks.
30590 */
30591 static int proxyClose(sqlite3_file *id) {
30592   if( id ){
30593     unixFile *pFile = (unixFile*)id;
30594     proxyLockingContext *pCtx = (proxyLockingContext *)pFile->lockingContext;
30595     unixFile *lockProxy = pCtx->lockProxy;
30596     unixFile *conchFile = pCtx->conchFile;
30597     int rc = SQLITE_OK;
30598     
30599     if( lockProxy ){
30600       rc = lockProxy->pMethod->xUnlock((sqlite3_file*)lockProxy, NO_LOCK);
30601       if( rc ) return rc;
30602       rc = lockProxy->pMethod->xClose((sqlite3_file*)lockProxy);
30603       if( rc ) return rc;
30604       sqlite3_free(lockProxy);
30605       pCtx->lockProxy = 0;
30606     }
30607     if( conchFile ){
30608       if( pCtx->conchHeld ){
30609         rc = proxyReleaseConch(pFile);
30610         if( rc ) return rc;
30611       }
30612       rc = conchFile->pMethod->xClose((sqlite3_file*)conchFile);
30613       if( rc ) return rc;
30614       sqlite3_free(conchFile);
30615     }
30616     sqlite3DbFree(0, pCtx->lockProxyPath);
30617     sqlite3_free(pCtx->conchFilePath);
30618     sqlite3DbFree(0, pCtx->dbPath);
30619     /* restore the original locking context and pMethod then close it */
30620     pFile->lockingContext = pCtx->oldLockingContext;
30621     pFile->pMethod = pCtx->pOldMethod;
30622     sqlite3_free(pCtx);
30623     return pFile->pMethod->xClose(id);
30624   }
30625   return SQLITE_OK;
30626 }
30627 
30628 
30629 
30630 #endif /* defined(__APPLE__) && SQLITE_ENABLE_LOCKING_STYLE */
30631 /*
30632 ** The proxy locking style is intended for use with AFP filesystems.
30633 ** And since AFP is only supported on MacOSX, the proxy locking is also
30634 ** restricted to MacOSX.
30635 ** 
30636 **
30637 ******************* End of the proxy lock implementation **********************
30638 ******************************************************************************/
30639 
30640 /*
30641 ** Initialize the operating system interface.
30642 **
30643 ** This routine registers all VFS implementations for unix-like operating
30644 ** systems.  This routine, and the sqlite3_os_end() routine that follows,
30645 ** should be the only routines in this file that are visible from other
30646 ** files.
30647 **
30648 ** This routine is called once during SQLite initialization and by a
30649 ** single thread.  The memory allocation and mutex subsystems have not
30650 ** necessarily been initialized when this routine is called, and so they
30651 ** should not be used.
30652 */
30653 SQLITE_API int sqlite3_os_init(void){ 
30654   /* 
30655   ** The following macro defines an initializer for an sqlite3_vfs object.
30656   ** The name of the VFS is NAME.  The pAppData is a pointer to a pointer
30657   ** to the "finder" function.  (pAppData is a pointer to a pointer because
30658   ** silly C90 rules prohibit a void* from being cast to a function pointer
30659   ** and so we have to go through the intermediate pointer to avoid problems
30660   ** when compiling with -pedantic-errors on GCC.)
30661   **
30662   ** The FINDER parameter to this macro is the name of the pointer to the
30663   ** finder-function.  The finder-function returns a pointer to the
30664   ** sqlite_io_methods object that implements the desired locking
30665   ** behaviors.  See the division above that contains the IOMETHODS
30666   ** macro for addition information on finder-functions.
30667   **
30668   ** Most finders simply return a pointer to a fixed sqlite3_io_methods
30669   ** object.  But the "autolockIoFinder" available on MacOSX does a little
30670   ** more than that; it looks at the filesystem type that hosts the 
30671   ** database file and tries to choose an locking method appropriate for
30672   ** that filesystem time.
30673   */
30674   #define UNIXVFS(VFSNAME, FINDER) {                        \
30675     3,                    /* iVersion */                    \
30676     sizeof(unixFile),     /* szOsFile */                    \
30677     MAX_PATHNAME,         /* mxPathname */                  \
30678     0,                    /* pNext */                       \
30679     VFSNAME,              /* zName */                       \
30680     (void*)&FINDER,       /* pAppData */                    \
30681     unixOpen,             /* xOpen */                       \
30682     unixDelete,           /* xDelete */                     \
30683     unixAccess,           /* xAccess */                     \
30684     unixFullPathname,     /* xFullPathname */               \
30685     unixDlOpen,           /* xDlOpen */                     \
30686     unixDlError,          /* xDlError */                    \
30687     unixDlSym,            /* xDlSym */                      \
30688     unixDlClose,          /* xDlClose */                    \
30689     unixRandomness,       /* xRandomness */                 \
30690     unixSleep,            /* xSleep */                      \
30691     unixCurrentTime,      /* xCurrentTime */                \
30692     unixGetLastError,     /* xGetLastError */               \
30693     unixCurrentTimeInt64, /* xCurrentTimeInt64 */           \
30694     unixSetSystemCall,    /* xSetSystemCall */              \
30695     unixGetSystemCall,    /* xGetSystemCall */              \
30696     unixNextSystemCall,   /* xNextSystemCall */             \
30697   }
30698 
30699   /*
30700   ** All default VFSes for unix are contained in the following array.
30701   **
30702   ** Note that the sqlite3_vfs.pNext field of the VFS object is modified
30703   ** by the SQLite core when the VFS is registered.  So the following
30704   ** array cannot be const.
30705   */
30706   static sqlite3_vfs aVfs[] = {
30707 #if SQLITE_ENABLE_LOCKING_STYLE && (OS_VXWORKS || defined(__APPLE__))
30708     UNIXVFS("unix",          autolockIoFinder ),
30709 #else
30710     UNIXVFS("unix",          posixIoFinder ),
30711 #endif
30712     UNIXVFS("unix-none",     nolockIoFinder ),
30713     UNIXVFS("unix-dotfile",  dotlockIoFinder ),
30714     UNIXVFS("unix-excl",     posixIoFinder ),
30715 #if OS_VXWORKS
30716     UNIXVFS("unix-namedsem", semIoFinder ),
30717 #endif
30718 #if SQLITE_ENABLE_LOCKING_STYLE
30719     UNIXVFS("unix-posix",    posixIoFinder ),
30720 #if !OS_VXWORKS
30721     UNIXVFS("unix-flock",    flockIoFinder ),
30722 #endif
30723 #endif
30724 #if SQLITE_ENABLE_LOCKING_STYLE && defined(__APPLE__)
30725     UNIXVFS("unix-afp",      afpIoFinder ),
30726     UNIXVFS("unix-nfs",      nfsIoFinder ),
30727     UNIXVFS("unix-proxy",    proxyIoFinder ),
30728 #endif
30729   };
30730   unsigned int i;          /* Loop counter */
30731 
30732   /* Double-check that the aSyscall[] array has been constructed
30733   ** correctly.  See ticket [bb3a86e890c8e96ab] */
30734   assert( ArraySize(aSyscall)==24 );
30735 
30736   /* Register all VFSes defined in the aVfs[] array */
30737   for(i=0; i<(sizeof(aVfs)/sizeof(sqlite3_vfs)); i++){
30738     sqlite3_vfs_register(&aVfs[i], i==0);
30739   }
30740   return SQLITE_OK; 
30741 }
30742 
30743 /*
30744 ** Shutdown the operating system interface.
30745 **
30746 ** Some operating systems might need to do some cleanup in this routine,
30747 ** to release dynamically allocated objects.  But not on unix.
30748 ** This routine is a no-op for unix.
30749 */
30750 SQLITE_API int sqlite3_os_end(void){ 
30751   return SQLITE_OK; 
30752 }
30753  
30754 #endif /* SQLITE_OS_UNIX */
30755 
30756 /************** End of os_unix.c *********************************************/
30757 /************** Begin file os_win.c ******************************************/
30758 /*
30759 ** 2004 May 22
30760 **
30761 ** The author disclaims copyright to this source code.  In place of
30762 ** a legal notice, here is a blessing:
30763 **
30764 **    May you do good and not evil.
30765 **    May you find forgiveness for yourself and forgive others.
30766 **    May you share freely, never taking more than you give.
30767 **
30768 ******************************************************************************
30769 **
30770 ** This file contains code that is specific to Windows.
30771 */
30772 #if SQLITE_OS_WIN               /* This file is used for Windows only */
30773 
30774 #ifdef __CYGWIN__
30775 # include <sys/cygwin.h>
30776 # include <errno.h> /* amalgamator: keep */
30777 #endif
30778 
30779 /*
30780 ** Include code that is common to all os_*.c files
30781 */
30782 /************** Include os_common.h in the middle of os_win.c ****************/
30783 /************** Begin file os_common.h ***************************************/
30784 /*
30785 ** 2004 May 22
30786 **
30787 ** The author disclaims copyright to this source code.  In place of
30788 ** a legal notice, here is a blessing:
30789 **
30790 **    May you do good and not evil.
30791 **    May you find forgiveness for yourself and forgive others.
30792 **    May you share freely, never taking more than you give.
30793 **
30794 ******************************************************************************
30795 **
30796 ** This file contains macros and a little bit of code that is common to
30797 ** all of the platform-specific files (os_*.c) and is #included into those
30798 ** files.
30799 **
30800 ** This file should be #included by the os_*.c files only.  It is not a
30801 ** general purpose header file.
30802 */
30803 #ifndef _OS_COMMON_H_
30804 #define _OS_COMMON_H_
30805 
30806 /*
30807 ** At least two bugs have slipped in because we changed the MEMORY_DEBUG
30808 ** macro to SQLITE_DEBUG and some older makefiles have not yet made the
30809 ** switch.  The following code should catch this problem at compile-time.
30810 */
30811 #ifdef MEMORY_DEBUG
30812 # error "The MEMORY_DEBUG macro is obsolete.  Use SQLITE_DEBUG instead."
30813 #endif
30814 
30815 #if defined(SQLITE_TEST) && defined(SQLITE_DEBUG)
30816 # ifndef SQLITE_DEBUG_OS_TRACE
30817 #   define SQLITE_DEBUG_OS_TRACE 0
30818 # endif
30819   int sqlite3OSTrace = SQLITE_DEBUG_OS_TRACE;
30820 # define OSTRACE(X)          if( sqlite3OSTrace ) sqlite3DebugPrintf X
30821 #else
30822 # define OSTRACE(X)
30823 #endif
30824 
30825 /*
30826 ** Macros for performance tracing.  Normally turned off.  Only works
30827 ** on i486 hardware.
30828 */
30829 #ifdef SQLITE_PERFORMANCE_TRACE
30830 
30831 /* 
30832 ** hwtime.h contains inline assembler code for implementing 
30833 ** high-performance timing routines.
30834 */
30835 /************** Include hwtime.h in the middle of os_common.h ****************/
30836 /************** Begin file hwtime.h ******************************************/
30837 /*
30838 ** 2008 May 27
30839 **
30840 ** The author disclaims copyright to this source code.  In place of
30841 ** a legal notice, here is a blessing:
30842 **
30843 **    May you do good and not evil.
30844 **    May you find forgiveness for yourself and forgive others.
30845 **    May you share freely, never taking more than you give.
30846 **
30847 ******************************************************************************
30848 **
30849 ** This file contains inline asm code for retrieving "high-performance"
30850 ** counters for x86 class CPUs.
30851 */
30852 #ifndef _HWTIME_H_
30853 #define _HWTIME_H_
30854 
30855 /*
30856 ** The following routine only works on pentium-class (or newer) processors.
30857 ** It uses the RDTSC opcode to read the cycle count value out of the
30858 ** processor and returns that value.  This can be used for high-res
30859 ** profiling.
30860 */
30861 #if (defined(__GNUC__) || defined(_MSC_VER)) && \
30862       (defined(i386) || defined(__i386__) || defined(_M_IX86))
30863 
30864   #if defined(__GNUC__)
30865 
30866   __inline__ sqlite_uint64 sqlite3Hwtime(void){
30867      unsigned int lo, hi;
30868      __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi));
30869      return (sqlite_uint64)hi << 32 | lo;
30870   }
30871 
30872   #elif defined(_MSC_VER)
30873 
30874   __declspec(naked) __inline sqlite_uint64 __cdecl sqlite3Hwtime(void){
30875      __asm {
30876         rdtsc
30877         ret       ; return value at EDX:EAX
30878      }
30879   }
30880 
30881   #endif
30882 
30883 #elif (defined(__GNUC__) && defined(__x86_64__))
30884 
30885   __inline__ sqlite_uint64 sqlite3Hwtime(void){
30886       unsigned long val;
30887       __asm__ __volatile__ ("rdtsc" : "=A" (val));
30888       return val;
30889   }
30890  
30891 #elif (defined(__GNUC__) && defined(__ppc__))
30892 
30893   __inline__ sqlite_uint64 sqlite3Hwtime(void){
30894       unsigned long long retval;
30895       unsigned long junk;
30896       __asm__ __volatile__ ("\n\
30897           1:      mftbu   %1\n\
30898                   mftb    %L0\n\
30899                   mftbu   %0\n\
30900                   cmpw    %0,%1\n\
30901                   bne     1b"
30902                   : "=r" (retval), "=r" (junk));
30903       return retval;
30904   }
30905 
30906 #else
30907 
30908   #error Need implementation of sqlite3Hwtime() for your platform.
30909 
30910   /*
30911   ** To compile without implementing sqlite3Hwtime() for your platform,
30912   ** you can remove the above #error and use the following
30913   ** stub function.  You will lose timing support for many
30914   ** of the debugging and testing utilities, but it should at
30915   ** least compile and run.
30916   */
30917 SQLITE_PRIVATE   sqlite_uint64 sqlite3Hwtime(void){ return ((sqlite_uint64)0); }
30918 
30919 #endif
30920 
30921 #endif /* !defined(_HWTIME_H_) */
30922 
30923 /************** End of hwtime.h **********************************************/
30924 /************** Continuing where we left off in os_common.h ******************/
30925 
30926 static sqlite_uint64 g_start;
30927 static sqlite_uint64 g_elapsed;
30928 #define TIMER_START       g_start=sqlite3Hwtime()
30929 #define TIMER_END         g_elapsed=sqlite3Hwtime()-g_start
30930 #define TIMER_ELAPSED     g_elapsed
30931 #else
30932 #define TIMER_START
30933 #define TIMER_END
30934 #define TIMER_ELAPSED     ((sqlite_uint64)0)
30935 #endif
30936 
30937 /*
30938 ** If we compile with the SQLITE_TEST macro set, then the following block
30939 ** of code will give us the ability to simulate a disk I/O error.  This
30940 ** is used for testing the I/O recovery logic.
30941 */
30942 #ifdef SQLITE_TEST
30943 SQLITE_API int sqlite3_io_error_hit = 0;            /* Total number of I/O Errors */
30944 SQLITE_API int sqlite3_io_error_hardhit = 0;        /* Number of non-benign errors */
30945 SQLITE_API int sqlite3_io_error_pending = 0;        /* Count down to first I/O error */
30946 SQLITE_API int sqlite3_io_error_persist = 0;        /* True if I/O errors persist */
30947 SQLITE_API int sqlite3_io_error_benign = 0;         /* True if errors are benign */
30948 SQLITE_API int sqlite3_diskfull_pending = 0;
30949 SQLITE_API int sqlite3_diskfull = 0;
30950 #define SimulateIOErrorBenign(X) sqlite3_io_error_benign=(X)
30951 #define SimulateIOError(CODE)  \
30952   if( (sqlite3_io_error_persist && sqlite3_io_error_hit) \
30953        || sqlite3_io_error_pending-- == 1 )  \
30954               { local_ioerr(); CODE; }
30955 static void local_ioerr(){
30956   IOTRACE(("IOERR\n"));
30957   sqlite3_io_error_hit++;
30958   if( !sqlite3_io_error_benign ) sqlite3_io_error_hardhit++;
30959 }
30960 #define SimulateDiskfullError(CODE) \
30961    if( sqlite3_diskfull_pending ){ \
30962      if( sqlite3_diskfull_pending == 1 ){ \
30963        local_ioerr(); \
30964        sqlite3_diskfull = 1; \
30965        sqlite3_io_error_hit = 1; \
30966        CODE; \
30967      }else{ \
30968        sqlite3_diskfull_pending--; \
30969      } \
30970    }
30971 #else
30972 #define SimulateIOErrorBenign(X)
30973 #define SimulateIOError(A)
30974 #define SimulateDiskfullError(A)
30975 #endif
30976 
30977 /*
30978 ** When testing, keep a count of the number of open files.
30979 */
30980 #ifdef SQLITE_TEST
30981 SQLITE_API int sqlite3_open_file_count = 0;
30982 #define OpenCounter(X)  sqlite3_open_file_count+=(X)
30983 #else
30984 #define OpenCounter(X)
30985 #endif
30986 
30987 #endif /* !defined(_OS_COMMON_H_) */
30988 
30989 /************** End of os_common.h *******************************************/
30990 /************** Continuing where we left off in os_win.c *********************/
30991 
30992 /*
30993 ** Compiling and using WAL mode requires several APIs that are only
30994 ** available in Windows platforms based on the NT kernel.
30995 */
30996 #if !SQLITE_OS_WINNT && !defined(SQLITE_OMIT_WAL)
30997 #  error "WAL mode requires support from the Windows NT kernel, compile\
30998  with SQLITE_OMIT_WAL."
30999 #endif
31000 
31001 /*
31002 ** Are most of the Win32 ANSI APIs available (i.e. with certain exceptions
31003 ** based on the sub-platform)?
31004 */
31005 #if !SQLITE_OS_WINCE && !SQLITE_OS_WINRT && !defined(SQLITE_WIN32_NO_ANSI)
31006 #  define SQLITE_WIN32_HAS_ANSI
31007 #endif
31008 
31009 /*
31010 ** Are most of the Win32 Unicode APIs available (i.e. with certain exceptions
31011 ** based on the sub-platform)?
31012 */
31013 #if (SQLITE_OS_WINCE || SQLITE_OS_WINNT || SQLITE_OS_WINRT) && \
31014     !defined(SQLITE_WIN32_NO_WIDE)
31015 #  define SQLITE_WIN32_HAS_WIDE
31016 #endif
31017 
31018 /*
31019 ** Make sure at least one set of Win32 APIs is available.
31020 */
31021 #if !defined(SQLITE_WIN32_HAS_ANSI) && !defined(SQLITE_WIN32_HAS_WIDE)
31022 #  error "At least one of SQLITE_WIN32_HAS_ANSI and SQLITE_WIN32_HAS_WIDE\
31023  must be defined."
31024 #endif
31025 
31026 /*
31027 ** Define the required Windows SDK version constants if they are not
31028 ** already available.
31029 */
31030 #ifndef NTDDI_WIN8
31031 #  define NTDDI_WIN8                        0x06020000
31032 #endif
31033 
31034 #ifndef NTDDI_WINBLUE
31035 #  define NTDDI_WINBLUE                     0x06030000
31036 #endif
31037 
31038 /*
31039 ** Check if the GetVersionEx[AW] functions should be considered deprecated
31040 ** and avoid using them in that case.  It should be noted here that if the
31041 ** value of the SQLITE_WIN32_GETVERSIONEX pre-processor macro is zero
31042 ** (whether via this block or via being manually specified), that implies
31043 ** the underlying operating system will always be based on the Windows NT
31044 ** Kernel.
31045 */
31046 #ifndef SQLITE_WIN32_GETVERSIONEX
31047 #  if defined(NTDDI_VERSION) && NTDDI_VERSION >= NTDDI_WINBLUE
31048 #    define SQLITE_WIN32_GETVERSIONEX   0
31049 #  else
31050 #    define SQLITE_WIN32_GETVERSIONEX   1
31051 #  endif
31052 #endif
31053 
31054 /*
31055 ** This constant should already be defined (in the "WinDef.h" SDK file).
31056 */
31057 #ifndef MAX_PATH
31058 #  define MAX_PATH                      (260)
31059 #endif
31060 
31061 /*
31062 ** Maximum pathname length (in chars) for Win32.  This should normally be
31063 ** MAX_PATH.
31064 */
31065 #ifndef SQLITE_WIN32_MAX_PATH_CHARS
31066 #  define SQLITE_WIN32_MAX_PATH_CHARS   (MAX_PATH)
31067 #endif
31068 
31069 /*
31070 ** This constant should already be defined (in the "WinNT.h" SDK file).
31071 */
31072 #ifndef UNICODE_STRING_MAX_CHARS
31073 #  define UNICODE_STRING_MAX_CHARS      (32767)
31074 #endif
31075 
31076 /*
31077 ** Maximum pathname length (in chars) for WinNT.  This should normally be
31078 ** UNICODE_STRING_MAX_CHARS.
31079 */
31080 #ifndef SQLITE_WINNT_MAX_PATH_CHARS
31081 #  define SQLITE_WINNT_MAX_PATH_CHARS   (UNICODE_STRING_MAX_CHARS)
31082 #endif
31083 
31084 /*
31085 ** Maximum pathname length (in bytes) for Win32.  The MAX_PATH macro is in
31086 ** characters, so we allocate 4 bytes per character assuming worst-case of
31087 ** 4-bytes-per-character for UTF8.
31088 */
31089 #ifndef SQLITE_WIN32_MAX_PATH_BYTES
31090 #  define SQLITE_WIN32_MAX_PATH_BYTES   (SQLITE_WIN32_MAX_PATH_CHARS*4)
31091 #endif
31092 
31093 /*
31094 ** Maximum pathname length (in bytes) for WinNT.  This should normally be
31095 ** UNICODE_STRING_MAX_CHARS * sizeof(WCHAR).
31096 */
31097 #ifndef SQLITE_WINNT_MAX_PATH_BYTES
31098 #  define SQLITE_WINNT_MAX_PATH_BYTES   \
31099                             (sizeof(WCHAR) * SQLITE_WINNT_MAX_PATH_CHARS)
31100 #endif
31101 
31102 /*
31103 ** Maximum error message length (in chars) for WinRT.
31104 */
31105 #ifndef SQLITE_WIN32_MAX_ERRMSG_CHARS
31106 #  define SQLITE_WIN32_MAX_ERRMSG_CHARS (1024)
31107 #endif
31108 
31109 /*
31110 ** Returns non-zero if the character should be treated as a directory
31111 ** separator.
31112 */
31113 #ifndef winIsDirSep
31114 #  define winIsDirSep(a)                (((a) == '/') || ((a) == '\\'))
31115 #endif
31116 
31117 /*
31118 ** This macro is used when a local variable is set to a value that is
31119 ** [sometimes] not used by the code (e.g. via conditional compilation).
31120 */
31121 #ifndef UNUSED_VARIABLE_VALUE
31122 #  define UNUSED_VARIABLE_VALUE(x) (void)(x)
31123 #endif
31124 
31125 /*
31126 ** Returns the character that should be used as the directory separator.
31127 */
31128 #ifndef winGetDirSep
31129 #  define winGetDirSep()                '\\'
31130 #endif
31131 
31132 /*
31133 ** Do we need to manually define the Win32 file mapping APIs for use with WAL
31134 ** mode (e.g. these APIs are available in the Windows CE SDK; however, they
31135 ** are not present in the header file)?
31136 */
31137 #if SQLITE_WIN32_FILEMAPPING_API && !defined(SQLITE_OMIT_WAL)
31138 /*
31139 ** Two of the file mapping APIs are different under WinRT.  Figure out which
31140 ** set we need.
31141 */
31142 #if SQLITE_OS_WINRT
31143 WINBASEAPI HANDLE WINAPI CreateFileMappingFromApp(HANDLE, \
31144         LPSECURITY_ATTRIBUTES, ULONG, ULONG64, LPCWSTR);
31145 
31146 WINBASEAPI LPVOID WINAPI MapViewOfFileFromApp(HANDLE, ULONG, ULONG64, SIZE_T);
31147 #else
31148 #if defined(SQLITE_WIN32_HAS_ANSI)
31149 WINBASEAPI HANDLE WINAPI CreateFileMappingA(HANDLE, LPSECURITY_ATTRIBUTES, \
31150         DWORD, DWORD, DWORD, LPCSTR);
31151 #endif /* defined(SQLITE_WIN32_HAS_ANSI) */
31152 
31153 #if defined(SQLITE_WIN32_HAS_WIDE)
31154 WINBASEAPI HANDLE WINAPI CreateFileMappingW(HANDLE, LPSECURITY_ATTRIBUTES, \
31155         DWORD, DWORD, DWORD, LPCWSTR);
31156 #endif /* defined(SQLITE_WIN32_HAS_WIDE) */
31157 
31158 WINBASEAPI LPVOID WINAPI MapViewOfFile(HANDLE, DWORD, DWORD, DWORD, SIZE_T);
31159 #endif /* SQLITE_OS_WINRT */
31160 
31161 /*
31162 ** This file mapping API is common to both Win32 and WinRT.
31163 */
31164 WINBASEAPI BOOL WINAPI UnmapViewOfFile(LPCVOID);
31165 #endif /* SQLITE_WIN32_FILEMAPPING_API && !defined(SQLITE_OMIT_WAL) */
31166 
31167 /*
31168 ** Some Microsoft compilers lack this definition.
31169 */
31170 #ifndef INVALID_FILE_ATTRIBUTES
31171 # define INVALID_FILE_ATTRIBUTES ((DWORD)-1) 
31172 #endif
31173 
31174 #ifndef FILE_FLAG_MASK
31175 # define FILE_FLAG_MASK          (0xFF3C0000)
31176 #endif
31177 
31178 #ifndef FILE_ATTRIBUTE_MASK
31179 # define FILE_ATTRIBUTE_MASK     (0x0003FFF7)
31180 #endif
31181 
31182 #ifndef SQLITE_OMIT_WAL
31183 /* Forward references to structures used for WAL */
31184 typedef struct winShm winShm;           /* A connection to shared-memory */
31185 typedef struct winShmNode winShmNode;   /* A region of shared-memory */
31186 #endif
31187 
31188 /*
31189 ** WinCE lacks native support for file locking so we have to fake it
31190 ** with some code of our own.
31191 */
31192 #if SQLITE_OS_WINCE
31193 typedef struct winceLock {
31194   int nReaders;       /* Number of reader locks obtained */
31195   BOOL bPending;      /* Indicates a pending lock has been obtained */
31196   BOOL bReserved;     /* Indicates a reserved lock has been obtained */
31197   BOOL bExclusive;    /* Indicates an exclusive lock has been obtained */
31198 } winceLock;
31199 #endif
31200 
31201 /*
31202 ** The winFile structure is a subclass of sqlite3_file* specific to the win32
31203 ** portability layer.
31204 */
31205 typedef struct winFile winFile;
31206 struct winFile {
31207   const sqlite3_io_methods *pMethod; /*** Must be first ***/
31208   sqlite3_vfs *pVfs;      /* The VFS used to open this file */
31209   HANDLE h;               /* Handle for accessing the file */
31210   u8 locktype;            /* Type of lock currently held on this file */
31211   short sharedLockByte;   /* Randomly chosen byte used as a shared lock */
31212   u8 ctrlFlags;           /* Flags.  See WINFILE_* below */
31213   DWORD lastErrno;        /* The Windows errno from the last I/O error */
31214 #ifndef SQLITE_OMIT_WAL
31215   winShm *pShm;           /* Instance of shared memory on this file */
31216 #endif
31217   const char *zPath;      /* Full pathname of this file */
31218   int szChunk;            /* Chunk size configured by FCNTL_CHUNK_SIZE */
31219 #if SQLITE_OS_WINCE
31220   LPWSTR zDeleteOnClose;  /* Name of file to delete when closing */
31221   HANDLE hMutex;          /* Mutex used to control access to shared lock */  
31222   HANDLE hShared;         /* Shared memory segment used for locking */
31223   winceLock local;        /* Locks obtained by this instance of winFile */
31224   winceLock *shared;      /* Global shared lock memory for the file  */
31225 #endif
31226 #if SQLITE_MAX_MMAP_SIZE>0
31227   int nFetchOut;                /* Number of outstanding xFetch references */
31228   HANDLE hMap;                  /* Handle for accessing memory mapping */
31229   void *pMapRegion;             /* Area memory mapped */
31230   sqlite3_int64 mmapSize;       /* Usable size of mapped region */
31231   sqlite3_int64 mmapSizeActual; /* Actual size of mapped region */
31232   sqlite3_int64 mmapSizeMax;    /* Configured FCNTL_MMAP_SIZE value */
31233 #endif
31234 };
31235 
31236 /*
31237 ** Allowed values for winFile.ctrlFlags
31238 */
31239 #define WINFILE_RDONLY          0x02   /* Connection is read only */
31240 #define WINFILE_PERSIST_WAL     0x04   /* Persistent WAL mode */
31241 #define WINFILE_PSOW            0x10   /* SQLITE_IOCAP_POWERSAFE_OVERWRITE */
31242 
31243 /*
31244  * The size of the buffer used by sqlite3_win32_write_debug().
31245  */
31246 #ifndef SQLITE_WIN32_DBG_BUF_SIZE
31247 #  define SQLITE_WIN32_DBG_BUF_SIZE   ((int)(4096-sizeof(DWORD)))
31248 #endif
31249 
31250 /*
31251  * The value used with sqlite3_win32_set_directory() to specify that
31252  * the data directory should be changed.
31253  */
31254 #ifndef SQLITE_WIN32_DATA_DIRECTORY_TYPE
31255 #  define SQLITE_WIN32_DATA_DIRECTORY_TYPE (1)
31256 #endif
31257 
31258 /*
31259  * The value used with sqlite3_win32_set_directory() to specify that
31260  * the temporary directory should be changed.
31261  */
31262 #ifndef SQLITE_WIN32_TEMP_DIRECTORY_TYPE
31263 #  define SQLITE_WIN32_TEMP_DIRECTORY_TYPE (2)
31264 #endif
31265 
31266 /*
31267  * If compiled with SQLITE_WIN32_MALLOC on Windows, we will use the
31268  * various Win32 API heap functions instead of our own.
31269  */
31270 #ifdef SQLITE_WIN32_MALLOC
31271 
31272 /*
31273  * If this is non-zero, an isolated heap will be created by the native Win32
31274  * allocator subsystem; otherwise, the default process heap will be used.  This
31275  * setting has no effect when compiling for WinRT.  By default, this is enabled
31276  * and an isolated heap will be created to store all allocated data.
31277  *
31278  ******************************************************************************
31279  * WARNING: It is important to note that when this setting is non-zero and the
31280  *          winMemShutdown function is called (e.g. by the sqlite3_shutdown
31281  *          function), all data that was allocated using the isolated heap will
31282  *          be freed immediately and any attempt to access any of that freed
31283  *          data will almost certainly result in an immediate access violation.
31284  ******************************************************************************
31285  */
31286 #ifndef SQLITE_WIN32_HEAP_CREATE
31287 #  define SQLITE_WIN32_HEAP_CREATE    (TRUE)
31288 #endif
31289 
31290 /*
31291  * The initial size of the Win32-specific heap.  This value may be zero.
31292  */
31293 #ifndef SQLITE_WIN32_HEAP_INIT_SIZE
31294 #  define SQLITE_WIN32_HEAP_INIT_SIZE ((SQLITE_DEFAULT_CACHE_SIZE) * \
31295                                        (SQLITE_DEFAULT_PAGE_SIZE) + 4194304)
31296 #endif
31297 
31298 /*
31299  * The maximum size of the Win32-specific heap.  This value may be zero.
31300  */
31301 #ifndef SQLITE_WIN32_HEAP_MAX_SIZE
31302 #  define SQLITE_WIN32_HEAP_MAX_SIZE  (0)
31303 #endif
31304 
31305 /*
31306  * The extra flags to use in calls to the Win32 heap APIs.  This value may be
31307  * zero for the default behavior.
31308  */
31309 #ifndef SQLITE_WIN32_HEAP_FLAGS
31310 #  define SQLITE_WIN32_HEAP_FLAGS     (0)
31311 #endif
31312 
31313 
31314 /*
31315 ** The winMemData structure stores information required by the Win32-specific
31316 ** sqlite3_mem_methods implementation.
31317 */
31318 typedef struct winMemData winMemData;
31319 struct winMemData {
31320 #ifndef NDEBUG
31321   u32 magic1;   /* Magic number to detect structure corruption. */
31322 #endif
31323   HANDLE hHeap; /* The handle to our heap. */
31324   BOOL bOwned;  /* Do we own the heap (i.e. destroy it on shutdown)? */
31325 #ifndef NDEBUG
31326   u32 magic2;   /* Magic number to detect structure corruption. */
31327 #endif
31328 };
31329 
31330 #ifndef NDEBUG
31331 #define WINMEM_MAGIC1     0x42b2830b
31332 #define WINMEM_MAGIC2     0xbd4d7cf4
31333 #endif
31334 
31335 static struct winMemData win_mem_data = {
31336 #ifndef NDEBUG
31337   WINMEM_MAGIC1,
31338 #endif
31339   NULL, FALSE
31340 #ifndef NDEBUG
31341   ,WINMEM_MAGIC2
31342 #endif
31343 };
31344 
31345 #ifndef NDEBUG
31346 #define winMemAssertMagic1() assert( win_mem_data.magic1==WINMEM_MAGIC1 )
31347 #define winMemAssertMagic2() assert( win_mem_data.magic2==WINMEM_MAGIC2 )
31348 #define winMemAssertMagic()  winMemAssertMagic1(); winMemAssertMagic2();
31349 #else
31350 #define winMemAssertMagic()
31351 #endif
31352 
31353 #define winMemGetDataPtr()  &win_mem_data
31354 #define winMemGetHeap()     win_mem_data.hHeap
31355 #define winMemGetOwned()    win_mem_data.bOwned
31356 
31357 static void *winMemMalloc(int nBytes);
31358 static void winMemFree(void *pPrior);
31359 static void *winMemRealloc(void *pPrior, int nBytes);
31360 static int winMemSize(void *p);
31361 static int winMemRoundup(int n);
31362 static int winMemInit(void *pAppData);
31363 static void winMemShutdown(void *pAppData);
31364 
31365 SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetWin32(void);
31366 #endif /* SQLITE_WIN32_MALLOC */
31367 
31368 /*
31369 ** The following variable is (normally) set once and never changes
31370 ** thereafter.  It records whether the operating system is Win9x
31371 ** or WinNT.
31372 **
31373 ** 0:   Operating system unknown.
31374 ** 1:   Operating system is Win9x.
31375 ** 2:   Operating system is WinNT.
31376 **
31377 ** In order to facilitate testing on a WinNT system, the test fixture
31378 ** can manually set this value to 1 to emulate Win98 behavior.
31379 */
31380 #ifdef SQLITE_TEST
31381 SQLITE_API int sqlite3_os_type = 0;
31382 #elif !SQLITE_OS_WINCE && !SQLITE_OS_WINRT && \
31383       defined(SQLITE_WIN32_HAS_ANSI) && defined(SQLITE_WIN32_HAS_WIDE)
31384 static int sqlite3_os_type = 0;
31385 #endif
31386 
31387 #ifndef SYSCALL
31388 #  define SYSCALL sqlite3_syscall_ptr
31389 #endif
31390 
31391 /*
31392 ** This function is not available on Windows CE or WinRT.
31393  */
31394 
31395 #if SQLITE_OS_WINCE || SQLITE_OS_WINRT
31396 #  define osAreFileApisANSI()       1
31397 #endif
31398 
31399 /*
31400 ** Many system calls are accessed through pointer-to-functions so that
31401 ** they may be overridden at runtime to facilitate fault injection during
31402 ** testing and sandboxing.  The following array holds the names and pointers
31403 ** to all overrideable system calls.
31404 */
31405 static struct win_syscall {
31406   const char *zName;            /* Name of the system call */
31407   sqlite3_syscall_ptr pCurrent; /* Current value of the system call */
31408   sqlite3_syscall_ptr pDefault; /* Default value */
31409 } aSyscall[] = {
31410 #if !SQLITE_OS_WINCE && !SQLITE_OS_WINRT
31411   { "AreFileApisANSI",         (SYSCALL)AreFileApisANSI,         0 },
31412 #else
31413   { "AreFileApisANSI",         (SYSCALL)0,                       0 },
31414 #endif
31415 
31416 #ifndef osAreFileApisANSI
31417 #define osAreFileApisANSI ((BOOL(WINAPI*)(VOID))aSyscall[0].pCurrent)
31418 #endif
31419 
31420 #if SQLITE_OS_WINCE && defined(SQLITE_WIN32_HAS_WIDE)
31421   { "CharLowerW",              (SYSCALL)CharLowerW,              0 },
31422 #else
31423   { "CharLowerW",              (SYSCALL)0,                       0 },
31424 #endif
31425 
31426 #define osCharLowerW ((LPWSTR(WINAPI*)(LPWSTR))aSyscall[1].pCurrent)
31427 
31428 #if SQLITE_OS_WINCE && defined(SQLITE_WIN32_HAS_WIDE)
31429   { "CharUpperW",              (SYSCALL)CharUpperW,              0 },
31430 #else
31431   { "CharUpperW",              (SYSCALL)0,                       0 },
31432 #endif
31433 
31434 #define osCharUpperW ((LPWSTR(WINAPI*)(LPWSTR))aSyscall[2].pCurrent)
31435 
31436   { "CloseHandle",             (SYSCALL)CloseHandle,             0 },
31437 
31438 #define osCloseHandle ((BOOL(WINAPI*)(HANDLE))aSyscall[3].pCurrent)
31439 
31440 #if defined(SQLITE_WIN32_HAS_ANSI)
31441   { "CreateFileA",             (SYSCALL)CreateFileA,             0 },
31442 #else
31443   { "CreateFileA",             (SYSCALL)0,                       0 },
31444 #endif
31445 
31446 #define osCreateFileA ((HANDLE(WINAPI*)(LPCSTR,DWORD,DWORD, \
31447         LPSECURITY_ATTRIBUTES,DWORD,DWORD,HANDLE))aSyscall[4].pCurrent)
31448 
31449 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_HAS_WIDE)
31450   { "CreateFileW",             (SYSCALL)CreateFileW,             0 },
31451 #else
31452   { "CreateFileW",             (SYSCALL)0,                       0 },
31453 #endif
31454 
31455 #define osCreateFileW ((HANDLE(WINAPI*)(LPCWSTR,DWORD,DWORD, \
31456         LPSECURITY_ATTRIBUTES,DWORD,DWORD,HANDLE))aSyscall[5].pCurrent)
31457 
31458 #if (!SQLITE_OS_WINRT && defined(SQLITE_WIN32_HAS_ANSI) && \
31459         !defined(SQLITE_OMIT_WAL))
31460   { "CreateFileMappingA",      (SYSCALL)CreateFileMappingA,      0 },
31461 #else
31462   { "CreateFileMappingA",      (SYSCALL)0,                       0 },
31463 #endif
31464 
31465 #define osCreateFileMappingA ((HANDLE(WINAPI*)(HANDLE,LPSECURITY_ATTRIBUTES, \
31466         DWORD,DWORD,DWORD,LPCSTR))aSyscall[6].pCurrent)
31467 
31468 #if SQLITE_OS_WINCE || (!SQLITE_OS_WINRT && defined(SQLITE_WIN32_HAS_WIDE) && \
31469         !defined(SQLITE_OMIT_WAL))
31470   { "CreateFileMappingW",      (SYSCALL)CreateFileMappingW,      0 },
31471 #else
31472   { "CreateFileMappingW",      (SYSCALL)0,                       0 },
31473 #endif
31474 
31475 #define osCreateFileMappingW ((HANDLE(WINAPI*)(HANDLE,LPSECURITY_ATTRIBUTES, \
31476         DWORD,DWORD,DWORD,LPCWSTR))aSyscall[7].pCurrent)
31477 
31478 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_HAS_WIDE)
31479   { "CreateMutexW",            (SYSCALL)CreateMutexW,            0 },
31480 #else
31481   { "CreateMutexW",            (SYSCALL)0,                       0 },
31482 #endif
31483 
31484 #define osCreateMutexW ((HANDLE(WINAPI*)(LPSECURITY_ATTRIBUTES,BOOL, \
31485         LPCWSTR))aSyscall[8].pCurrent)
31486 
31487 #if defined(SQLITE_WIN32_HAS_ANSI)
31488   { "DeleteFileA",             (SYSCALL)DeleteFileA,             0 },
31489 #else
31490   { "DeleteFileA",             (SYSCALL)0,                       0 },
31491 #endif
31492 
31493 #define osDeleteFileA ((BOOL(WINAPI*)(LPCSTR))aSyscall[9].pCurrent)
31494 
31495 #if defined(SQLITE_WIN32_HAS_WIDE)
31496   { "DeleteFileW",             (SYSCALL)DeleteFileW,             0 },
31497 #else
31498   { "DeleteFileW",             (SYSCALL)0,                       0 },
31499 #endif
31500 
31501 #define osDeleteFileW ((BOOL(WINAPI*)(LPCWSTR))aSyscall[10].pCurrent)
31502 
31503 #if SQLITE_OS_WINCE
31504   { "FileTimeToLocalFileTime", (SYSCALL)FileTimeToLocalFileTime, 0 },
31505 #else
31506   { "FileTimeToLocalFileTime", (SYSCALL)0,                       0 },
31507 #endif
31508 
31509 #define osFileTimeToLocalFileTime ((BOOL(WINAPI*)(CONST FILETIME*, \
31510         LPFILETIME))aSyscall[11].pCurrent)
31511 
31512 #if SQLITE_OS_WINCE
31513   { "FileTimeToSystemTime",    (SYSCALL)FileTimeToSystemTime,    0 },
31514 #else
31515   { "FileTimeToSystemTime",    (SYSCALL)0,                       0 },
31516 #endif
31517 
31518 #define osFileTimeToSystemTime ((BOOL(WINAPI*)(CONST FILETIME*, \
31519         LPSYSTEMTIME))aSyscall[12].pCurrent)
31520 
31521   { "FlushFileBuffers",        (SYSCALL)FlushFileBuffers,        0 },
31522 
31523 #define osFlushFileBuffers ((BOOL(WINAPI*)(HANDLE))aSyscall[13].pCurrent)
31524 
31525 #if defined(SQLITE_WIN32_HAS_ANSI)
31526   { "FormatMessageA",          (SYSCALL)FormatMessageA,          0 },
31527 #else
31528   { "FormatMessageA",          (SYSCALL)0,                       0 },
31529 #endif
31530 
31531 #define osFormatMessageA ((DWORD(WINAPI*)(DWORD,LPCVOID,DWORD,DWORD,LPSTR, \
31532         DWORD,va_list*))aSyscall[14].pCurrent)
31533 
31534 #if defined(SQLITE_WIN32_HAS_WIDE)
31535   { "FormatMessageW",          (SYSCALL)FormatMessageW,          0 },
31536 #else
31537   { "FormatMessageW",          (SYSCALL)0,                       0 },
31538 #endif
31539 
31540 #define osFormatMessageW ((DWORD(WINAPI*)(DWORD,LPCVOID,DWORD,DWORD,LPWSTR, \
31541         DWORD,va_list*))aSyscall[15].pCurrent)
31542 
31543 #if !defined(SQLITE_OMIT_LOAD_EXTENSION)
31544   { "FreeLibrary",             (SYSCALL)FreeLibrary,             0 },
31545 #else
31546   { "FreeLibrary",             (SYSCALL)0,                       0 },
31547 #endif
31548 
31549 #define osFreeLibrary ((BOOL(WINAPI*)(HMODULE))aSyscall[16].pCurrent)
31550 
31551   { "GetCurrentProcessId",     (SYSCALL)GetCurrentProcessId,     0 },
31552 
31553 #define osGetCurrentProcessId ((DWORD(WINAPI*)(VOID))aSyscall[17].pCurrent)
31554 
31555 #if !SQLITE_OS_WINCE && defined(SQLITE_WIN32_HAS_ANSI)
31556   { "GetDiskFreeSpaceA",       (SYSCALL)GetDiskFreeSpaceA,       0 },
31557 #else
31558   { "GetDiskFreeSpaceA",       (SYSCALL)0,                       0 },
31559 #endif
31560 
31561 #define osGetDiskFreeSpaceA ((BOOL(WINAPI*)(LPCSTR,LPDWORD,LPDWORD,LPDWORD, \
31562         LPDWORD))aSyscall[18].pCurrent)
31563 
31564 #if !SQLITE_OS_WINCE && !SQLITE_OS_WINRT && defined(SQLITE_WIN32_HAS_WIDE)
31565   { "GetDiskFreeSpaceW",       (SYSCALL)GetDiskFreeSpaceW,       0 },
31566 #else
31567   { "GetDiskFreeSpaceW",       (SYSCALL)0,                       0 },
31568 #endif
31569 
31570 #define osGetDiskFreeSpaceW ((BOOL(WINAPI*)(LPCWSTR,LPDWORD,LPDWORD,LPDWORD, \
31571         LPDWORD))aSyscall[19].pCurrent)
31572 
31573 #if defined(SQLITE_WIN32_HAS_ANSI)
31574   { "GetFileAttributesA",      (SYSCALL)GetFileAttributesA,      0 },
31575 #else
31576   { "GetFileAttributesA",      (SYSCALL)0,                       0 },
31577 #endif
31578 
31579 #define osGetFileAttributesA ((DWORD(WINAPI*)(LPCSTR))aSyscall[20].pCurrent)
31580 
31581 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_HAS_WIDE)
31582   { "GetFileAttributesW",      (SYSCALL)GetFileAttributesW,      0 },
31583 #else
31584   { "GetFileAttributesW",      (SYSCALL)0,                       0 },
31585 #endif
31586 
31587 #define osGetFileAttributesW ((DWORD(WINAPI*)(LPCWSTR))aSyscall[21].pCurrent)
31588 
31589 #if defined(SQLITE_WIN32_HAS_WIDE)
31590   { "GetFileAttributesExW",    (SYSCALL)GetFileAttributesExW,    0 },
31591 #else
31592   { "GetFileAttributesExW",    (SYSCALL)0,                       0 },
31593 #endif
31594 
31595 #define osGetFileAttributesExW ((BOOL(WINAPI*)(LPCWSTR,GET_FILEEX_INFO_LEVELS, \
31596         LPVOID))aSyscall[22].pCurrent)
31597 
31598 #if !SQLITE_OS_WINRT
31599   { "GetFileSize",             (SYSCALL)GetFileSize,             0 },
31600 #else
31601   { "GetFileSize",             (SYSCALL)0,                       0 },
31602 #endif
31603 
31604 #define osGetFileSize ((DWORD(WINAPI*)(HANDLE,LPDWORD))aSyscall[23].pCurrent)
31605 
31606 #if !SQLITE_OS_WINCE && defined(SQLITE_WIN32_HAS_ANSI)
31607   { "GetFullPathNameA",        (SYSCALL)GetFullPathNameA,        0 },
31608 #else
31609   { "GetFullPathNameA",        (SYSCALL)0,                       0 },
31610 #endif
31611 
31612 #define osGetFullPathNameA ((DWORD(WINAPI*)(LPCSTR,DWORD,LPSTR, \
31613         LPSTR*))aSyscall[24].pCurrent)
31614 
31615 #if !SQLITE_OS_WINCE && !SQLITE_OS_WINRT && defined(SQLITE_WIN32_HAS_WIDE)
31616   { "GetFullPathNameW",        (SYSCALL)GetFullPathNameW,        0 },
31617 #else
31618   { "GetFullPathNameW",        (SYSCALL)0,                       0 },
31619 #endif
31620 
31621 #define osGetFullPathNameW ((DWORD(WINAPI*)(LPCWSTR,DWORD,LPWSTR, \
31622         LPWSTR*))aSyscall[25].pCurrent)
31623 
31624   { "GetLastError",            (SYSCALL)GetLastError,            0 },
31625 
31626 #define osGetLastError ((DWORD(WINAPI*)(VOID))aSyscall[26].pCurrent)
31627 
31628 #if !defined(SQLITE_OMIT_LOAD_EXTENSION)
31629 #if SQLITE_OS_WINCE
31630   /* The GetProcAddressA() routine is only available on Windows CE. */
31631   { "GetProcAddressA",         (SYSCALL)GetProcAddressA,         0 },
31632 #else
31633   /* All other Windows platforms expect GetProcAddress() to take
31634   ** an ANSI string regardless of the _UNICODE setting */
31635   { "GetProcAddressA",         (SYSCALL)GetProcAddress,          0 },
31636 #endif
31637 #else
31638   { "GetProcAddressA",         (SYSCALL)0,                       0 },
31639 #endif
31640 
31641 #define osGetProcAddressA ((FARPROC(WINAPI*)(HMODULE, \
31642         LPCSTR))aSyscall[27].pCurrent)
31643 
31644 #if !SQLITE_OS_WINRT
31645   { "GetSystemInfo",           (SYSCALL)GetSystemInfo,           0 },
31646 #else
31647   { "GetSystemInfo",           (SYSCALL)0,                       0 },
31648 #endif
31649 
31650 #define osGetSystemInfo ((VOID(WINAPI*)(LPSYSTEM_INFO))aSyscall[28].pCurrent)
31651 
31652   { "GetSystemTime",           (SYSCALL)GetSystemTime,           0 },
31653 
31654 #define osGetSystemTime ((VOID(WINAPI*)(LPSYSTEMTIME))aSyscall[29].pCurrent)
31655 
31656 #if !SQLITE_OS_WINCE
31657   { "GetSystemTimeAsFileTime", (SYSCALL)GetSystemTimeAsFileTime, 0 },
31658 #else
31659   { "GetSystemTimeAsFileTime", (SYSCALL)0,                       0 },
31660 #endif
31661 
31662 #define osGetSystemTimeAsFileTime ((VOID(WINAPI*)( \
31663         LPFILETIME))aSyscall[30].pCurrent)
31664 
31665 #if defined(SQLITE_WIN32_HAS_ANSI)
31666   { "GetTempPathA",            (SYSCALL)GetTempPathA,            0 },
31667 #else
31668   { "GetTempPathA",            (SYSCALL)0,                       0 },
31669 #endif
31670 
31671 #define osGetTempPathA ((DWORD(WINAPI*)(DWORD,LPSTR))aSyscall[31].pCurrent)
31672 
31673 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_HAS_WIDE)
31674   { "GetTempPathW",            (SYSCALL)GetTempPathW,            0 },
31675 #else
31676   { "GetTempPathW",            (SYSCALL)0,                       0 },
31677 #endif
31678 
31679 #define osGetTempPathW ((DWORD(WINAPI*)(DWORD,LPWSTR))aSyscall[32].pCurrent)
31680 
31681 #if !SQLITE_OS_WINRT
31682   { "GetTickCount",            (SYSCALL)GetTickCount,            0 },
31683 #else
31684   { "GetTickCount",            (SYSCALL)0,                       0 },
31685 #endif
31686 
31687 #define osGetTickCount ((DWORD(WINAPI*)(VOID))aSyscall[33].pCurrent)
31688 
31689 #if defined(SQLITE_WIN32_HAS_ANSI) && defined(SQLITE_WIN32_GETVERSIONEX) && \
31690         SQLITE_WIN32_GETVERSIONEX
31691   { "GetVersionExA",           (SYSCALL)GetVersionExA,           0 },
31692 #else
31693   { "GetVersionExA",           (SYSCALL)0,                       0 },
31694 #endif
31695 
31696 #define osGetVersionExA ((BOOL(WINAPI*)( \
31697         LPOSVERSIONINFOA))aSyscall[34].pCurrent)
31698 
31699 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_HAS_WIDE) && \
31700         defined(SQLITE_WIN32_GETVERSIONEX) && SQLITE_WIN32_GETVERSIONEX
31701   { "GetVersionExW",           (SYSCALL)GetVersionExW,           0 },
31702 #else
31703   { "GetVersionExW",           (SYSCALL)0,                       0 },
31704 #endif
31705 
31706 #define osGetVersionExW ((BOOL(WINAPI*)( \
31707         LPOSVERSIONINFOW))aSyscall[35].pCurrent)
31708 
31709   { "HeapAlloc",               (SYSCALL)HeapAlloc,               0 },
31710 
31711 #define osHeapAlloc ((LPVOID(WINAPI*)(HANDLE,DWORD, \
31712         SIZE_T))aSyscall[36].pCurrent)
31713 
31714 #if !SQLITE_OS_WINRT
31715   { "HeapCreate",              (SYSCALL)HeapCreate,              0 },
31716 #else
31717   { "HeapCreate",              (SYSCALL)0,                       0 },
31718 #endif
31719 
31720 #define osHeapCreate ((HANDLE(WINAPI*)(DWORD,SIZE_T, \
31721         SIZE_T))aSyscall[37].pCurrent)
31722 
31723 #if !SQLITE_OS_WINRT
31724   { "HeapDestroy",             (SYSCALL)HeapDestroy,             0 },
31725 #else
31726   { "HeapDestroy",             (SYSCALL)0,                       0 },
31727 #endif
31728 
31729 #define osHeapDestroy ((BOOL(WINAPI*)(HANDLE))aSyscall[38].pCurrent)
31730 
31731   { "HeapFree",                (SYSCALL)HeapFree,                0 },
31732 
31733 #define osHeapFree ((BOOL(WINAPI*)(HANDLE,DWORD,LPVOID))aSyscall[39].pCurrent)
31734 
31735   { "HeapReAlloc",             (SYSCALL)HeapReAlloc,             0 },
31736 
31737 #define osHeapReAlloc ((LPVOID(WINAPI*)(HANDLE,DWORD,LPVOID, \
31738         SIZE_T))aSyscall[40].pCurrent)
31739 
31740   { "HeapSize",                (SYSCALL)HeapSize,                0 },
31741 
31742 #define osHeapSize ((SIZE_T(WINAPI*)(HANDLE,DWORD, \
31743         LPCVOID))aSyscall[41].pCurrent)
31744 
31745 #if !SQLITE_OS_WINRT
31746   { "HeapValidate",            (SYSCALL)HeapValidate,            0 },
31747 #else
31748   { "HeapValidate",            (SYSCALL)0,                       0 },
31749 #endif
31750 
31751 #define osHeapValidate ((BOOL(WINAPI*)(HANDLE,DWORD, \
31752         LPCVOID))aSyscall[42].pCurrent)
31753 
31754 #if !SQLITE_OS_WINCE && !SQLITE_OS_WINRT
31755   { "HeapCompact",             (SYSCALL)HeapCompact,             0 },
31756 #else
31757   { "HeapCompact",             (SYSCALL)0,                       0 },
31758 #endif
31759 
31760 #define osHeapCompact ((UINT(WINAPI*)(HANDLE,DWORD))aSyscall[43].pCurrent)
31761 
31762 #if defined(SQLITE_WIN32_HAS_ANSI) && !defined(SQLITE_OMIT_LOAD_EXTENSION)
31763   { "LoadLibraryA",            (SYSCALL)LoadLibraryA,            0 },
31764 #else
31765   { "LoadLibraryA",            (SYSCALL)0,                       0 },
31766 #endif
31767 
31768 #define osLoadLibraryA ((HMODULE(WINAPI*)(LPCSTR))aSyscall[44].pCurrent)
31769 
31770 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_HAS_WIDE) && \
31771         !defined(SQLITE_OMIT_LOAD_EXTENSION)
31772   { "LoadLibraryW",            (SYSCALL)LoadLibraryW,            0 },
31773 #else
31774   { "LoadLibraryW",            (SYSCALL)0,                       0 },
31775 #endif
31776 
31777 #define osLoadLibraryW ((HMODULE(WINAPI*)(LPCWSTR))aSyscall[45].pCurrent)
31778 
31779 #if !SQLITE_OS_WINRT
31780   { "LocalFree",               (SYSCALL)LocalFree,               0 },
31781 #else
31782   { "LocalFree",               (SYSCALL)0,                       0 },
31783 #endif
31784 
31785 #define osLocalFree ((HLOCAL(WINAPI*)(HLOCAL))aSyscall[46].pCurrent)
31786 
31787 #if !SQLITE_OS_WINCE && !SQLITE_OS_WINRT
31788   { "LockFile",                (SYSCALL)LockFile,                0 },
31789 #else
31790   { "LockFile",                (SYSCALL)0,                       0 },
31791 #endif
31792 
31793 #ifndef osLockFile
31794 #define osLockFile ((BOOL(WINAPI*)(HANDLE,DWORD,DWORD,DWORD, \
31795         DWORD))aSyscall[47].pCurrent)
31796 #endif
31797 
31798 #if !SQLITE_OS_WINCE
31799   { "LockFileEx",              (SYSCALL)LockFileEx,              0 },
31800 #else
31801   { "LockFileEx",              (SYSCALL)0,                       0 },
31802 #endif
31803 
31804 #ifndef osLockFileEx
31805 #define osLockFileEx ((BOOL(WINAPI*)(HANDLE,DWORD,DWORD,DWORD,DWORD, \
31806         LPOVERLAPPED))aSyscall[48].pCurrent)
31807 #endif
31808 
31809 #if SQLITE_OS_WINCE || (!SQLITE_OS_WINRT && !defined(SQLITE_OMIT_WAL))
31810   { "MapViewOfFile",           (SYSCALL)MapViewOfFile,           0 },
31811 #else
31812   { "MapViewOfFile",           (SYSCALL)0,                       0 },
31813 #endif
31814 
31815 #define osMapViewOfFile ((LPVOID(WINAPI*)(HANDLE,DWORD,DWORD,DWORD, \
31816         SIZE_T))aSyscall[49].pCurrent)
31817 
31818   { "MultiByteToWideChar",     (SYSCALL)MultiByteToWideChar,     0 },
31819 
31820 #define osMultiByteToWideChar ((int(WINAPI*)(UINT,DWORD,LPCSTR,int,LPWSTR, \
31821         int))aSyscall[50].pCurrent)
31822 
31823   { "QueryPerformanceCounter", (SYSCALL)QueryPerformanceCounter, 0 },
31824 
31825 #define osQueryPerformanceCounter ((BOOL(WINAPI*)( \
31826         LARGE_INTEGER*))aSyscall[51].pCurrent)
31827 
31828   { "ReadFile",                (SYSCALL)ReadFile,                0 },
31829 
31830 #define osReadFile ((BOOL(WINAPI*)(HANDLE,LPVOID,DWORD,LPDWORD, \
31831         LPOVERLAPPED))aSyscall[52].pCurrent)
31832 
31833   { "SetEndOfFile",            (SYSCALL)SetEndOfFile,            0 },
31834 
31835 #define osSetEndOfFile ((BOOL(WINAPI*)(HANDLE))aSyscall[53].pCurrent)
31836 
31837 #if !SQLITE_OS_WINRT
31838   { "SetFilePointer",          (SYSCALL)SetFilePointer,          0 },
31839 #else
31840   { "SetFilePointer",          (SYSCALL)0,                       0 },
31841 #endif
31842 
31843 #define osSetFilePointer ((DWORD(WINAPI*)(HANDLE,LONG,PLONG, \
31844         DWORD))aSyscall[54].pCurrent)
31845 
31846 #if !SQLITE_OS_WINRT
31847   { "Sleep",                   (SYSCALL)Sleep,                   0 },
31848 #else
31849   { "Sleep",                   (SYSCALL)0,                       0 },
31850 #endif
31851 
31852 #define osSleep ((VOID(WINAPI*)(DWORD))aSyscall[55].pCurrent)
31853 
31854   { "SystemTimeToFileTime",    (SYSCALL)SystemTimeToFileTime,    0 },
31855 
31856 #define osSystemTimeToFileTime ((BOOL(WINAPI*)(CONST SYSTEMTIME*, \
31857         LPFILETIME))aSyscall[56].pCurrent)
31858 
31859 #if !SQLITE_OS_WINCE && !SQLITE_OS_WINRT
31860   { "UnlockFile",              (SYSCALL)UnlockFile,              0 },
31861 #else
31862   { "UnlockFile",              (SYSCALL)0,                       0 },
31863 #endif
31864 
31865 #ifndef osUnlockFile
31866 #define osUnlockFile ((BOOL(WINAPI*)(HANDLE,DWORD,DWORD,DWORD, \
31867         DWORD))aSyscall[57].pCurrent)
31868 #endif
31869 
31870 #if !SQLITE_OS_WINCE
31871   { "UnlockFileEx",            (SYSCALL)UnlockFileEx,            0 },
31872 #else
31873   { "UnlockFileEx",            (SYSCALL)0,                       0 },
31874 #endif
31875 
31876 #define osUnlockFileEx ((BOOL(WINAPI*)(HANDLE,DWORD,DWORD,DWORD, \
31877         LPOVERLAPPED))aSyscall[58].pCurrent)
31878 
31879 #if SQLITE_OS_WINCE || !defined(SQLITE_OMIT_WAL)
31880   { "UnmapViewOfFile",         (SYSCALL)UnmapViewOfFile,         0 },
31881 #else
31882   { "UnmapViewOfFile",         (SYSCALL)0,                       0 },
31883 #endif
31884 
31885 #define osUnmapViewOfFile ((BOOL(WINAPI*)(LPCVOID))aSyscall[59].pCurrent)
31886 
31887   { "WideCharToMultiByte",     (SYSCALL)WideCharToMultiByte,     0 },
31888 
31889 #define osWideCharToMultiByte ((int(WINAPI*)(UINT,DWORD,LPCWSTR,int,LPSTR,int, \
31890         LPCSTR,LPBOOL))aSyscall[60].pCurrent)
31891 
31892   { "WriteFile",               (SYSCALL)WriteFile,               0 },
31893 
31894 #define osWriteFile ((BOOL(WINAPI*)(HANDLE,LPCVOID,DWORD,LPDWORD, \
31895         LPOVERLAPPED))aSyscall[61].pCurrent)
31896 
31897 #if SQLITE_OS_WINRT
31898   { "CreateEventExW",          (SYSCALL)CreateEventExW,          0 },
31899 #else
31900   { "CreateEventExW",          (SYSCALL)0,                       0 },
31901 #endif
31902 
31903 #define osCreateEventExW ((HANDLE(WINAPI*)(LPSECURITY_ATTRIBUTES,LPCWSTR, \
31904         DWORD,DWORD))aSyscall[62].pCurrent)
31905 
31906 #if !SQLITE_OS_WINRT
31907   { "WaitForSingleObject",     (SYSCALL)WaitForSingleObject,     0 },
31908 #else
31909   { "WaitForSingleObject",     (SYSCALL)0,                       0 },
31910 #endif
31911 
31912 #define osWaitForSingleObject ((DWORD(WINAPI*)(HANDLE, \
31913         DWORD))aSyscall[63].pCurrent)
31914 
31915 #if SQLITE_OS_WINRT
31916   { "WaitForSingleObjectEx",   (SYSCALL)WaitForSingleObjectEx,   0 },
31917 #else
31918   { "WaitForSingleObjectEx",   (SYSCALL)0,                       0 },
31919 #endif
31920 
31921 #define osWaitForSingleObjectEx ((DWORD(WINAPI*)(HANDLE,DWORD, \
31922         BOOL))aSyscall[64].pCurrent)
31923 
31924 #if SQLITE_OS_WINRT
31925   { "SetFilePointerEx",        (SYSCALL)SetFilePointerEx,        0 },
31926 #else
31927   { "SetFilePointerEx",        (SYSCALL)0,                       0 },
31928 #endif
31929 
31930 #define osSetFilePointerEx ((BOOL(WINAPI*)(HANDLE,LARGE_INTEGER, \
31931         PLARGE_INTEGER,DWORD))aSyscall[65].pCurrent)
31932 
31933 #if SQLITE_OS_WINRT
31934   { "GetFileInformationByHandleEx", (SYSCALL)GetFileInformationByHandleEx, 0 },
31935 #else
31936   { "GetFileInformationByHandleEx", (SYSCALL)0,                  0 },
31937 #endif
31938 
31939 #define osGetFileInformationByHandleEx ((BOOL(WINAPI*)(HANDLE, \
31940         FILE_INFO_BY_HANDLE_CLASS,LPVOID,DWORD))aSyscall[66].pCurrent)
31941 
31942 #if SQLITE_OS_WINRT && !defined(SQLITE_OMIT_WAL)
31943   { "MapViewOfFileFromApp",    (SYSCALL)MapViewOfFileFromApp,    0 },
31944 #else
31945   { "MapViewOfFileFromApp",    (SYSCALL)0,                       0 },
31946 #endif
31947 
31948 #define osMapViewOfFileFromApp ((LPVOID(WINAPI*)(HANDLE,ULONG,ULONG64, \
31949         SIZE_T))aSyscall[67].pCurrent)
31950 
31951 #if SQLITE_OS_WINRT
31952   { "CreateFile2",             (SYSCALL)CreateFile2,             0 },
31953 #else
31954   { "CreateFile2",             (SYSCALL)0,                       0 },
31955 #endif
31956 
31957 #define osCreateFile2 ((HANDLE(WINAPI*)(LPCWSTR,DWORD,DWORD,DWORD, \
31958         LPCREATEFILE2_EXTENDED_PARAMETERS))aSyscall[68].pCurrent)
31959 
31960 #if SQLITE_OS_WINRT && !defined(SQLITE_OMIT_LOAD_EXTENSION)
31961   { "LoadPackagedLibrary",     (SYSCALL)LoadPackagedLibrary,     0 },
31962 #else
31963   { "LoadPackagedLibrary",     (SYSCALL)0,                       0 },
31964 #endif
31965 
31966 #define osLoadPackagedLibrary ((HMODULE(WINAPI*)(LPCWSTR, \
31967         DWORD))aSyscall[69].pCurrent)
31968 
31969 #if SQLITE_OS_WINRT
31970   { "GetTickCount64",          (SYSCALL)GetTickCount64,          0 },
31971 #else
31972   { "GetTickCount64",          (SYSCALL)0,                       0 },
31973 #endif
31974 
31975 #define osGetTickCount64 ((ULONGLONG(WINAPI*)(VOID))aSyscall[70].pCurrent)
31976 
31977 #if SQLITE_OS_WINRT
31978   { "GetNativeSystemInfo",     (SYSCALL)GetNativeSystemInfo,     0 },
31979 #else
31980   { "GetNativeSystemInfo",     (SYSCALL)0,                       0 },
31981 #endif
31982 
31983 #define osGetNativeSystemInfo ((VOID(WINAPI*)( \
31984         LPSYSTEM_INFO))aSyscall[71].pCurrent)
31985 
31986 #if defined(SQLITE_WIN32_HAS_ANSI)
31987   { "OutputDebugStringA",      (SYSCALL)OutputDebugStringA,      0 },
31988 #else
31989   { "OutputDebugStringA",      (SYSCALL)0,                       0 },
31990 #endif
31991 
31992 #define osOutputDebugStringA ((VOID(WINAPI*)(LPCSTR))aSyscall[72].pCurrent)
31993 
31994 #if defined(SQLITE_WIN32_HAS_WIDE)
31995   { "OutputDebugStringW",      (SYSCALL)OutputDebugStringW,      0 },
31996 #else
31997   { "OutputDebugStringW",      (SYSCALL)0,                       0 },
31998 #endif
31999 
32000 #define osOutputDebugStringW ((VOID(WINAPI*)(LPCWSTR))aSyscall[73].pCurrent)
32001 
32002   { "GetProcessHeap",          (SYSCALL)GetProcessHeap,          0 },
32003 
32004 #define osGetProcessHeap ((HANDLE(WINAPI*)(VOID))aSyscall[74].pCurrent)
32005 
32006 #if SQLITE_OS_WINRT && !defined(SQLITE_OMIT_WAL)
32007   { "CreateFileMappingFromApp", (SYSCALL)CreateFileMappingFromApp, 0 },
32008 #else
32009   { "CreateFileMappingFromApp", (SYSCALL)0,                      0 },
32010 #endif
32011 
32012 #define osCreateFileMappingFromApp ((HANDLE(WINAPI*)(HANDLE, \
32013         LPSECURITY_ATTRIBUTES,ULONG,ULONG64,LPCWSTR))aSyscall[75].pCurrent)
32014 
32015 }; /* End of the overrideable system calls */
32016 
32017 /*
32018 ** This is the xSetSystemCall() method of sqlite3_vfs for all of the
32019 ** "win32" VFSes.  Return SQLITE_OK opon successfully updating the
32020 ** system call pointer, or SQLITE_NOTFOUND if there is no configurable
32021 ** system call named zName.
32022 */
32023 static int winSetSystemCall(
32024   sqlite3_vfs *pNotUsed,        /* The VFS pointer.  Not used */
32025   const char *zName,            /* Name of system call to override */
32026   sqlite3_syscall_ptr pNewFunc  /* Pointer to new system call value */
32027 ){
32028   unsigned int i;
32029   int rc = SQLITE_NOTFOUND;
32030 
32031   UNUSED_PARAMETER(pNotUsed);
32032   if( zName==0 ){
32033     /* If no zName is given, restore all system calls to their default
32034     ** settings and return NULL
32035     */
32036     rc = SQLITE_OK;
32037     for(i=0; i<sizeof(aSyscall)/sizeof(aSyscall[0]); i++){
32038       if( aSyscall[i].pDefault ){
32039         aSyscall[i].pCurrent = aSyscall[i].pDefault;
32040       }
32041     }
32042   }else{
32043     /* If zName is specified, operate on only the one system call
32044     ** specified.
32045     */
32046     for(i=0; i<sizeof(aSyscall)/sizeof(aSyscall[0]); i++){
32047       if( strcmp(zName, aSyscall[i].zName)==0 ){
32048         if( aSyscall[i].pDefault==0 ){
32049           aSyscall[i].pDefault = aSyscall[i].pCurrent;
32050         }
32051         rc = SQLITE_OK;
32052         if( pNewFunc==0 ) pNewFunc = aSyscall[i].pDefault;
32053         aSyscall[i].pCurrent = pNewFunc;
32054         break;
32055       }
32056     }
32057   }
32058   return rc;
32059 }
32060 
32061 /*
32062 ** Return the value of a system call.  Return NULL if zName is not a
32063 ** recognized system call name.  NULL is also returned if the system call
32064 ** is currently undefined.
32065 */
32066 static sqlite3_syscall_ptr winGetSystemCall(
32067   sqlite3_vfs *pNotUsed,
32068   const char *zName
32069 ){
32070   unsigned int i;
32071 
32072   UNUSED_PARAMETER(pNotUsed);
32073   for(i=0; i<sizeof(aSyscall)/sizeof(aSyscall[0]); i++){
32074     if( strcmp(zName, aSyscall[i].zName)==0 ) return aSyscall[i].pCurrent;
32075   }
32076   return 0;
32077 }
32078 
32079 /*
32080 ** Return the name of the first system call after zName.  If zName==NULL
32081 ** then return the name of the first system call.  Return NULL if zName
32082 ** is the last system call or if zName is not the name of a valid
32083 ** system call.
32084 */
32085 static const char *winNextSystemCall(sqlite3_vfs *p, const char *zName){
32086   int i = -1;
32087 
32088   UNUSED_PARAMETER(p);
32089   if( zName ){
32090     for(i=0; i<ArraySize(aSyscall)-1; i++){
32091       if( strcmp(zName, aSyscall[i].zName)==0 ) break;
32092     }
32093   }
32094   for(i++; i<ArraySize(aSyscall); i++){
32095     if( aSyscall[i].pCurrent!=0 ) return aSyscall[i].zName;
32096   }
32097   return 0;
32098 }
32099 
32100 #ifdef SQLITE_WIN32_MALLOC
32101 /*
32102 ** If a Win32 native heap has been configured, this function will attempt to
32103 ** compact it.  Upon success, SQLITE_OK will be returned.  Upon failure, one
32104 ** of SQLITE_NOMEM, SQLITE_ERROR, or SQLITE_NOTFOUND will be returned.  The
32105 ** "pnLargest" argument, if non-zero, will be used to return the size of the
32106 ** largest committed free block in the heap, in bytes.
32107 */
32108 SQLITE_API int sqlite3_win32_compact_heap(LPUINT pnLargest){
32109   int rc = SQLITE_OK;
32110   UINT nLargest = 0;
32111   HANDLE hHeap;
32112 
32113   winMemAssertMagic();
32114   hHeap = winMemGetHeap();
32115   assert( hHeap!=0 );
32116   assert( hHeap!=INVALID_HANDLE_VALUE );
32117 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_MALLOC_VALIDATE)
32118   assert( osHeapValidate(hHeap, SQLITE_WIN32_HEAP_FLAGS, NULL) );
32119 #endif
32120 #if !SQLITE_OS_WINCE && !SQLITE_OS_WINRT
32121   if( (nLargest=osHeapCompact(hHeap, SQLITE_WIN32_HEAP_FLAGS))==0 ){
32122     DWORD lastErrno = osGetLastError();
32123     if( lastErrno==NO_ERROR ){
32124       sqlite3_log(SQLITE_NOMEM, "failed to HeapCompact (no space), heap=%p",
32125                   (void*)hHeap);
32126       rc = SQLITE_NOMEM;
32127     }else{
32128       sqlite3_log(SQLITE_ERROR, "failed to HeapCompact (%lu), heap=%p",
32129                   osGetLastError(), (void*)hHeap);
32130       rc = SQLITE_ERROR;
32131     }
32132   }
32133 #else
32134   sqlite3_log(SQLITE_NOTFOUND, "failed to HeapCompact, heap=%p",
32135               (void*)hHeap);
32136   rc = SQLITE_NOTFOUND;
32137 #endif
32138   if( pnLargest ) *pnLargest = nLargest;
32139   return rc;
32140 }
32141 
32142 /*
32143 ** If a Win32 native heap has been configured, this function will attempt to
32144 ** destroy and recreate it.  If the Win32 native heap is not isolated and/or
32145 ** the sqlite3_memory_used() function does not return zero, SQLITE_BUSY will
32146 ** be returned and no changes will be made to the Win32 native heap.
32147 */
32148 SQLITE_API int sqlite3_win32_reset_heap(){
32149   int rc;
32150   MUTEX_LOGIC( sqlite3_mutex *pMaster; ) /* The main static mutex */
32151   MUTEX_LOGIC( sqlite3_mutex *pMem; )    /* The memsys static mutex */
32152   MUTEX_LOGIC( pMaster = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); )
32153   MUTEX_LOGIC( pMem = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM); )
32154   sqlite3_mutex_enter(pMaster);
32155   sqlite3_mutex_enter(pMem);
32156   winMemAssertMagic();
32157   if( winMemGetHeap()!=NULL && winMemGetOwned() && sqlite3_memory_used()==0 ){
32158     /*
32159     ** At this point, there should be no outstanding memory allocations on
32160     ** the heap.  Also, since both the master and memsys locks are currently
32161     ** being held by us, no other function (i.e. from another thread) should
32162     ** be able to even access the heap.  Attempt to destroy and recreate our
32163     ** isolated Win32 native heap now.
32164     */
32165     assert( winMemGetHeap()!=NULL );
32166     assert( winMemGetOwned() );
32167     assert( sqlite3_memory_used()==0 );
32168     winMemShutdown(winMemGetDataPtr());
32169     assert( winMemGetHeap()==NULL );
32170     assert( !winMemGetOwned() );
32171     assert( sqlite3_memory_used()==0 );
32172     rc = winMemInit(winMemGetDataPtr());
32173     assert( rc!=SQLITE_OK || winMemGetHeap()!=NULL );
32174     assert( rc!=SQLITE_OK || winMemGetOwned() );
32175     assert( rc!=SQLITE_OK || sqlite3_memory_used()==0 );
32176   }else{
32177     /*
32178     ** The Win32 native heap cannot be modified because it may be in use.
32179     */
32180     rc = SQLITE_BUSY;
32181   }
32182   sqlite3_mutex_leave(pMem);
32183   sqlite3_mutex_leave(pMaster);
32184   return rc;
32185 }
32186 #endif /* SQLITE_WIN32_MALLOC */
32187 
32188 /*
32189 ** This function outputs the specified (ANSI) string to the Win32 debugger
32190 ** (if available).
32191 */
32192 
32193 SQLITE_API void sqlite3_win32_write_debug(const char *zBuf, int nBuf){
32194   char zDbgBuf[SQLITE_WIN32_DBG_BUF_SIZE];
32195   int nMin = MIN(nBuf, (SQLITE_WIN32_DBG_BUF_SIZE - 1)); /* may be negative. */
32196   if( nMin<-1 ) nMin = -1; /* all negative values become -1. */
32197   assert( nMin==-1 || nMin==0 || nMin<SQLITE_WIN32_DBG_BUF_SIZE );
32198 #if defined(SQLITE_WIN32_HAS_ANSI)
32199   if( nMin>0 ){
32200     memset(zDbgBuf, 0, SQLITE_WIN32_DBG_BUF_SIZE);
32201     memcpy(zDbgBuf, zBuf, nMin);
32202     osOutputDebugStringA(zDbgBuf);
32203   }else{
32204     osOutputDebugStringA(zBuf);
32205   }
32206 #elif defined(SQLITE_WIN32_HAS_WIDE)
32207   memset(zDbgBuf, 0, SQLITE_WIN32_DBG_BUF_SIZE);
32208   if ( osMultiByteToWideChar(
32209           osAreFileApisANSI() ? CP_ACP : CP_OEMCP, 0, zBuf,
32210           nMin, (LPWSTR)zDbgBuf, SQLITE_WIN32_DBG_BUF_SIZE/sizeof(WCHAR))<=0 ){
32211     return;
32212   }
32213   osOutputDebugStringW((LPCWSTR)zDbgBuf);
32214 #else
32215   if( nMin>0 ){
32216     memset(zDbgBuf, 0, SQLITE_WIN32_DBG_BUF_SIZE);
32217     memcpy(zDbgBuf, zBuf, nMin);
32218     fprintf(stderr, "%s", zDbgBuf);
32219   }else{
32220     fprintf(stderr, "%s", zBuf);
32221   }
32222 #endif
32223 }
32224 
32225 /*
32226 ** The following routine suspends the current thread for at least ms
32227 ** milliseconds.  This is equivalent to the Win32 Sleep() interface.
32228 */
32229 #if SQLITE_OS_WINRT
32230 static HANDLE sleepObj = NULL;
32231 #endif
32232 
32233 SQLITE_API void sqlite3_win32_sleep(DWORD milliseconds){
32234 #if SQLITE_OS_WINRT
32235   if ( sleepObj==NULL ){
32236     sleepObj = osCreateEventExW(NULL, NULL, CREATE_EVENT_MANUAL_RESET,
32237                                 SYNCHRONIZE);
32238   }
32239   assert( sleepObj!=NULL );
32240   osWaitForSingleObjectEx(sleepObj, milliseconds, FALSE);
32241 #else
32242   osSleep(milliseconds);
32243 #endif
32244 }
32245 
32246 /*
32247 ** Return true (non-zero) if we are running under WinNT, Win2K, WinXP,
32248 ** or WinCE.  Return false (zero) for Win95, Win98, or WinME.
32249 **
32250 ** Here is an interesting observation:  Win95, Win98, and WinME lack
32251 ** the LockFileEx() API.  But we can still statically link against that
32252 ** API as long as we don't call it when running Win95/98/ME.  A call to
32253 ** this routine is used to determine if the host is Win95/98/ME or
32254 ** WinNT/2K/XP so that we will know whether or not we can safely call
32255 ** the LockFileEx() API.
32256 */
32257 
32258 #if !defined(SQLITE_WIN32_GETVERSIONEX) || !SQLITE_WIN32_GETVERSIONEX
32259 # define osIsNT()  (1)
32260 #elif SQLITE_OS_WINCE || SQLITE_OS_WINRT || !defined(SQLITE_WIN32_HAS_ANSI)
32261 # define osIsNT()  (1)
32262 #elif !defined(SQLITE_WIN32_HAS_WIDE)
32263 # define osIsNT()  (0)
32264 #else
32265   static int osIsNT(void){
32266     if( sqlite3_os_type==0 ){
32267 #if defined(NTDDI_VERSION) && NTDDI_VERSION >= NTDDI_WIN8
32268       OSVERSIONINFOW sInfo;
32269       sInfo.dwOSVersionInfoSize = sizeof(sInfo);
32270       osGetVersionExW(&sInfo);
32271 #else
32272       OSVERSIONINFOA sInfo;
32273       sInfo.dwOSVersionInfoSize = sizeof(sInfo);
32274       osGetVersionExA(&sInfo);
32275 #endif
32276       sqlite3_os_type = sInfo.dwPlatformId==VER_PLATFORM_WIN32_NT ? 2 : 1;
32277     }
32278     return sqlite3_os_type==2;
32279   }
32280 #endif
32281 
32282 #ifdef SQLITE_WIN32_MALLOC
32283 /*
32284 ** Allocate nBytes of memory.
32285 */
32286 static void *winMemMalloc(int nBytes){
32287   HANDLE hHeap;
32288   void *p;
32289 
32290   winMemAssertMagic();
32291   hHeap = winMemGetHeap();
32292   assert( hHeap!=0 );
32293   assert( hHeap!=INVALID_HANDLE_VALUE );
32294 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_MALLOC_VALIDATE)
32295   assert( osHeapValidate(hHeap, SQLITE_WIN32_HEAP_FLAGS, NULL) );
32296 #endif
32297   assert( nBytes>=0 );
32298   p = osHeapAlloc(hHeap, SQLITE_WIN32_HEAP_FLAGS, (SIZE_T)nBytes);
32299   if( !p ){
32300     sqlite3_log(SQLITE_NOMEM, "failed to HeapAlloc %u bytes (%lu), heap=%p",
32301                 nBytes, osGetLastError(), (void*)hHeap);
32302   }
32303   return p;
32304 }
32305 
32306 /*
32307 ** Free memory.
32308 */
32309 static void winMemFree(void *pPrior){
32310   HANDLE hHeap;
32311 
32312   winMemAssertMagic();
32313   hHeap = winMemGetHeap();
32314   assert( hHeap!=0 );
32315   assert( hHeap!=INVALID_HANDLE_VALUE );
32316 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_MALLOC_VALIDATE)
32317   assert( osHeapValidate(hHeap, SQLITE_WIN32_HEAP_FLAGS, pPrior) );
32318 #endif
32319   if( !pPrior ) return; /* Passing NULL to HeapFree is undefined. */
32320   if( !osHeapFree(hHeap, SQLITE_WIN32_HEAP_FLAGS, pPrior) ){
32321     sqlite3_log(SQLITE_NOMEM, "failed to HeapFree block %p (%lu), heap=%p",
32322                 pPrior, osGetLastError(), (void*)hHeap);
32323   }
32324 }
32325 
32326 /*
32327 ** Change the size of an existing memory allocation
32328 */
32329 static void *winMemRealloc(void *pPrior, int nBytes){
32330   HANDLE hHeap;
32331   void *p;
32332 
32333   winMemAssertMagic();
32334   hHeap = winMemGetHeap();
32335   assert( hHeap!=0 );
32336   assert( hHeap!=INVALID_HANDLE_VALUE );
32337 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_MALLOC_VALIDATE)
32338   assert( osHeapValidate(hHeap, SQLITE_WIN32_HEAP_FLAGS, pPrior) );
32339 #endif
32340   assert( nBytes>=0 );
32341   if( !pPrior ){
32342     p = osHeapAlloc(hHeap, SQLITE_WIN32_HEAP_FLAGS, (SIZE_T)nBytes);
32343   }else{
32344     p = osHeapReAlloc(hHeap, SQLITE_WIN32_HEAP_FLAGS, pPrior, (SIZE_T)nBytes);
32345   }
32346   if( !p ){
32347     sqlite3_log(SQLITE_NOMEM, "failed to %s %u bytes (%lu), heap=%p",
32348                 pPrior ? "HeapReAlloc" : "HeapAlloc", nBytes, osGetLastError(),
32349                 (void*)hHeap);
32350   }
32351   return p;
32352 }
32353 
32354 /*
32355 ** Return the size of an outstanding allocation, in bytes.
32356 */
32357 static int winMemSize(void *p){
32358   HANDLE hHeap;
32359   SIZE_T n;
32360 
32361   winMemAssertMagic();
32362   hHeap = winMemGetHeap();
32363   assert( hHeap!=0 );
32364   assert( hHeap!=INVALID_HANDLE_VALUE );
32365 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_MALLOC_VALIDATE)
32366   assert( osHeapValidate(hHeap, SQLITE_WIN32_HEAP_FLAGS, p) );
32367 #endif
32368   if( !p ) return 0;
32369   n = osHeapSize(hHeap, SQLITE_WIN32_HEAP_FLAGS, p);
32370   if( n==(SIZE_T)-1 ){
32371     sqlite3_log(SQLITE_NOMEM, "failed to HeapSize block %p (%lu), heap=%p",
32372                 p, osGetLastError(), (void*)hHeap);
32373     return 0;
32374   }
32375   return (int)n;
32376 }
32377 
32378 /*
32379 ** Round up a request size to the next valid allocation size.
32380 */
32381 static int winMemRoundup(int n){
32382   return n;
32383 }
32384 
32385 /*
32386 ** Initialize this module.
32387 */
32388 static int winMemInit(void *pAppData){
32389   winMemData *pWinMemData = (winMemData *)pAppData;
32390 
32391   if( !pWinMemData ) return SQLITE_ERROR;
32392   assert( pWinMemData->magic1==WINMEM_MAGIC1 );
32393   assert( pWinMemData->magic2==WINMEM_MAGIC2 );
32394 
32395 #if !SQLITE_OS_WINRT && SQLITE_WIN32_HEAP_CREATE
32396   if( !pWinMemData->hHeap ){
32397     DWORD dwInitialSize = SQLITE_WIN32_HEAP_INIT_SIZE;
32398     DWORD dwMaximumSize = (DWORD)sqlite3GlobalConfig.nHeap;
32399     if( dwMaximumSize==0 ){
32400       dwMaximumSize = SQLITE_WIN32_HEAP_MAX_SIZE;
32401     }else if( dwInitialSize>dwMaximumSize ){
32402       dwInitialSize = dwMaximumSize;
32403     }
32404     pWinMemData->hHeap = osHeapCreate(SQLITE_WIN32_HEAP_FLAGS,
32405                                       dwInitialSize, dwMaximumSize);
32406     if( !pWinMemData->hHeap ){
32407       sqlite3_log(SQLITE_NOMEM,
32408           "failed to HeapCreate (%lu), flags=%u, initSize=%lu, maxSize=%lu",
32409           osGetLastError(), SQLITE_WIN32_HEAP_FLAGS, dwInitialSize,
32410           dwMaximumSize);
32411       return SQLITE_NOMEM;
32412     }
32413     pWinMemData->bOwned = TRUE;
32414     assert( pWinMemData->bOwned );
32415   }
32416 #else
32417   pWinMemData->hHeap = osGetProcessHeap();
32418   if( !pWinMemData->hHeap ){
32419     sqlite3_log(SQLITE_NOMEM,
32420         "failed to GetProcessHeap (%lu)", osGetLastError());
32421     return SQLITE_NOMEM;
32422   }
32423   pWinMemData->bOwned = FALSE;
32424   assert( !pWinMemData->bOwned );
32425 #endif
32426   assert( pWinMemData->hHeap!=0 );
32427   assert( pWinMemData->hHeap!=INVALID_HANDLE_VALUE );
32428 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_MALLOC_VALIDATE)
32429   assert( osHeapValidate(pWinMemData->hHeap, SQLITE_WIN32_HEAP_FLAGS, NULL) );
32430 #endif
32431   return SQLITE_OK;
32432 }
32433 
32434 /*
32435 ** Deinitialize this module.
32436 */
32437 static void winMemShutdown(void *pAppData){
32438   winMemData *pWinMemData = (winMemData *)pAppData;
32439 
32440   if( !pWinMemData ) return;
32441   assert( pWinMemData->magic1==WINMEM_MAGIC1 );
32442   assert( pWinMemData->magic2==WINMEM_MAGIC2 );
32443 
32444   if( pWinMemData->hHeap ){
32445     assert( pWinMemData->hHeap!=INVALID_HANDLE_VALUE );
32446 #if !SQLITE_OS_WINRT && defined(SQLITE_WIN32_MALLOC_VALIDATE)
32447     assert( osHeapValidate(pWinMemData->hHeap, SQLITE_WIN32_HEAP_FLAGS, NULL) );
32448 #endif
32449     if( pWinMemData->bOwned ){
32450       if( !osHeapDestroy(pWinMemData->hHeap) ){
32451         sqlite3_log(SQLITE_NOMEM, "failed to HeapDestroy (%lu), heap=%p",
32452                     osGetLastError(), (void*)pWinMemData->hHeap);
32453       }
32454       pWinMemData->bOwned = FALSE;
32455     }
32456     pWinMemData->hHeap = NULL;
32457   }
32458 }
32459 
32460 /*
32461 ** Populate the low-level memory allocation function pointers in
32462 ** sqlite3GlobalConfig.m with pointers to the routines in this file. The
32463 ** arguments specify the block of memory to manage.
32464 **
32465 ** This routine is only called by sqlite3_config(), and therefore
32466 ** is not required to be threadsafe (it is not).
32467 */
32468 SQLITE_PRIVATE const sqlite3_mem_methods *sqlite3MemGetWin32(void){
32469   static const sqlite3_mem_methods winMemMethods = {
32470     winMemMalloc,
32471     winMemFree,
32472     winMemRealloc,
32473     winMemSize,
32474     winMemRoundup,
32475     winMemInit,
32476     winMemShutdown,
32477     &win_mem_data
32478   };
32479   return &winMemMethods;
32480 }
32481 
32482 SQLITE_PRIVATE void sqlite3MemSetDefault(void){
32483   sqlite3_config(SQLITE_CONFIG_MALLOC, sqlite3MemGetWin32());
32484 }
32485 #endif /* SQLITE_WIN32_MALLOC */
32486 
32487 /*
32488 ** Convert a UTF-8 string to Microsoft Unicode (UTF-16?). 
32489 **
32490 ** Space to hold the returned string is obtained from malloc.
32491 */
32492 static LPWSTR winUtf8ToUnicode(const char *zFilename){
32493   int nChar;
32494   LPWSTR zWideFilename;
32495 
32496   nChar = osMultiByteToWideChar(CP_UTF8, 0, zFilename, -1, NULL, 0);
32497   if( nChar==0 ){
32498     return 0;
32499   }
32500   zWideFilename = sqlite3MallocZero( nChar*sizeof(zWideFilename[0]) );
32501   if( zWideFilename==0 ){
32502     return 0;
32503   }
32504   nChar = osMultiByteToWideChar(CP_UTF8, 0, zFilename, -1, zWideFilename,
32505                                 nChar);
32506   if( nChar==0 ){
32507     sqlite3_free(zWideFilename);
32508     zWideFilename = 0;
32509   }
32510   return zWideFilename;
32511 }
32512 
32513 /*
32514 ** Convert Microsoft Unicode to UTF-8.  Space to hold the returned string is
32515 ** obtained from sqlite3_malloc().
32516 */
32517 static char *winUnicodeToUtf8(LPCWSTR zWideFilename){
32518   int nByte;
32519   char *zFilename;
32520 
32521   nByte = osWideCharToMultiByte(CP_UTF8, 0, zWideFilename, -1, 0, 0, 0, 0);
32522   if( nByte == 0 ){
32523     return 0;
32524   }
32525   zFilename = sqlite3MallocZero( nByte );
32526   if( zFilename==0 ){
32527     return 0;
32528   }
32529   nByte = osWideCharToMultiByte(CP_UTF8, 0, zWideFilename, -1, zFilename, nByte,
32530                                 0, 0);
32531   if( nByte == 0 ){
32532     sqlite3_free(zFilename);
32533     zFilename = 0;
32534   }
32535   return zFilename;
32536 }
32537 
32538 /*
32539 ** Convert an ANSI string to Microsoft Unicode, based on the
32540 ** current codepage settings for file apis.
32541 ** 
32542 ** Space to hold the returned string is obtained
32543 ** from sqlite3_malloc.
32544 */
32545 static LPWSTR winMbcsToUnicode(const char *zFilename){
32546   int nByte;
32547   LPWSTR zMbcsFilename;
32548   int codepage = osAreFileApisANSI() ? CP_ACP : CP_OEMCP;
32549 
32550   nByte = osMultiByteToWideChar(codepage, 0, zFilename, -1, NULL,
32551                                 0)*sizeof(WCHAR);
32552   if( nByte==0 ){
32553     return 0;
32554   }
32555   zMbcsFilename = sqlite3MallocZero( nByte*sizeof(zMbcsFilename[0]) );
32556   if( zMbcsFilename==0 ){
32557     return 0;
32558   }
32559   nByte = osMultiByteToWideChar(codepage, 0, zFilename, -1, zMbcsFilename,
32560                                 nByte);
32561   if( nByte==0 ){
32562     sqlite3_free(zMbcsFilename);
32563     zMbcsFilename = 0;
32564   }
32565   return zMbcsFilename;
32566 }
32567 
32568 /*
32569 ** Convert Microsoft Unicode to multi-byte character string, based on the
32570 ** user's ANSI codepage.
32571 **
32572 ** Space to hold the returned string is obtained from
32573 ** sqlite3_malloc().
32574 */
32575 static char *winUnicodeToMbcs(LPCWSTR zWideFilename){
32576   int nByte;
32577   char *zFilename;
32578   int codepage = osAreFileApisANSI() ? CP_ACP : CP_OEMCP;
32579 
32580   nByte = osWideCharToMultiByte(codepage, 0, zWideFilename, -1, 0, 0, 0, 0);
32581   if( nByte == 0 ){
32582     return 0;
32583   }
32584   zFilename = sqlite3MallocZero( nByte );
32585   if( zFilename==0 ){
32586     return 0;
32587   }
32588   nByte = osWideCharToMultiByte(codepage, 0, zWideFilename, -1, zFilename,
32589                                 nByte, 0, 0);
32590   if( nByte == 0 ){
32591     sqlite3_free(zFilename);
32592     zFilename = 0;
32593   }
32594   return zFilename;
32595 }
32596 
32597 /*
32598 ** Convert multibyte character string to UTF-8.  Space to hold the
32599 ** returned string is obtained from sqlite3_malloc().
32600 */
32601 SQLITE_API char *sqlite3_win32_mbcs_to_utf8(const char *zFilename){
32602   char *zFilenameUtf8;
32603   LPWSTR zTmpWide;
32604 
32605   zTmpWide = winMbcsToUnicode(zFilename);
32606   if( zTmpWide==0 ){
32607     return 0;
32608   }
32609   zFilenameUtf8 = winUnicodeToUtf8(zTmpWide);
32610   sqlite3_free(zTmpWide);
32611   return zFilenameUtf8;
32612 }
32613 
32614 /*
32615 ** Convert UTF-8 to multibyte character string.  Space to hold the 
32616 ** returned string is obtained from sqlite3_malloc().
32617 */
32618 SQLITE_API char *sqlite3_win32_utf8_to_mbcs(const char *zFilename){
32619   char *zFilenameMbcs;
32620   LPWSTR zTmpWide;
32621 
32622   zTmpWide = winUtf8ToUnicode(zFilename);
32623   if( zTmpWide==0 ){
32624     return 0;
32625   }
32626   zFilenameMbcs = winUnicodeToMbcs(zTmpWide);
32627   sqlite3_free(zTmpWide);
32628   return zFilenameMbcs;
32629 }
32630 
32631 /*
32632 ** This function sets the data directory or the temporary directory based on
32633 ** the provided arguments.  The type argument must be 1 in order to set the
32634 ** data directory or 2 in order to set the temporary directory.  The zValue
32635 ** argument is the name of the directory to use.  The return value will be
32636 ** SQLITE_OK if successful.
32637 */
32638 SQLITE_API int sqlite3_win32_set_directory(DWORD type, LPCWSTR zValue){
32639   char **ppDirectory = 0;
32640 #ifndef SQLITE_OMIT_AUTOINIT
32641   int rc = sqlite3_initialize();
32642   if( rc ) return rc;
32643 #endif
32644   if( type==SQLITE_WIN32_DATA_DIRECTORY_TYPE ){
32645     ppDirectory = &sqlite3_data_directory;
32646   }else if( type==SQLITE_WIN32_TEMP_DIRECTORY_TYPE ){
32647     ppDirectory = &sqlite3_temp_directory;
32648   }
32649   assert( !ppDirectory || type==SQLITE_WIN32_DATA_DIRECTORY_TYPE
32650           || type==SQLITE_WIN32_TEMP_DIRECTORY_TYPE
32651   );
32652   assert( !ppDirectory || sqlite3MemdebugHasType(*ppDirectory, MEMTYPE_HEAP) );
32653   if( ppDirectory ){
32654     char *zValueUtf8 = 0;
32655     if( zValue && zValue[0] ){
32656       zValueUtf8 = winUnicodeToUtf8(zValue);
32657       if ( zValueUtf8==0 ){
32658         return SQLITE_NOMEM;
32659       }
32660     }
32661     sqlite3_free(*ppDirectory);
32662     *ppDirectory = zValueUtf8;
32663     return SQLITE_OK;
32664   }
32665   return SQLITE_ERROR;
32666 }
32667 
32668 /*
32669 ** The return value of winGetLastErrorMsg
32670 ** is zero if the error message fits in the buffer, or non-zero
32671 ** otherwise (if the message was truncated).
32672 */
32673 static int winGetLastErrorMsg(DWORD lastErrno, int nBuf, char *zBuf){
32674   /* FormatMessage returns 0 on failure.  Otherwise it
32675   ** returns the number of TCHARs written to the output
32676   ** buffer, excluding the terminating null char.
32677   */
32678   DWORD dwLen = 0;
32679   char *zOut = 0;
32680 
32681   if( osIsNT() ){
32682 #if SQLITE_OS_WINRT
32683     WCHAR zTempWide[SQLITE_WIN32_MAX_ERRMSG_CHARS+1];
32684     dwLen = osFormatMessageW(FORMAT_MESSAGE_FROM_SYSTEM |
32685                              FORMAT_MESSAGE_IGNORE_INSERTS,
32686                              NULL,
32687                              lastErrno,
32688                              0,
32689                              zTempWide,
32690                              SQLITE_WIN32_MAX_ERRMSG_CHARS,
32691                              0);
32692 #else
32693     LPWSTR zTempWide = NULL;
32694     dwLen = osFormatMessageW(FORMAT_MESSAGE_ALLOCATE_BUFFER |
32695                              FORMAT_MESSAGE_FROM_SYSTEM |
32696                              FORMAT_MESSAGE_IGNORE_INSERTS,
32697                              NULL,
32698                              lastErrno,
32699                              0,
32700                              (LPWSTR) &zTempWide,
32701                              0,
32702                              0);
32703 #endif
32704     if( dwLen > 0 ){
32705       /* allocate a buffer and convert to UTF8 */
32706       sqlite3BeginBenignMalloc();
32707       zOut = winUnicodeToUtf8(zTempWide);
32708       sqlite3EndBenignMalloc();
32709 #if !SQLITE_OS_WINRT
32710       /* free the system buffer allocated by FormatMessage */
32711       osLocalFree(zTempWide);
32712 #endif
32713     }
32714   }
32715 #ifdef SQLITE_WIN32_HAS_ANSI
32716   else{
32717     char *zTemp = NULL;
32718     dwLen = osFormatMessageA(FORMAT_MESSAGE_ALLOCATE_BUFFER |
32719                              FORMAT_MESSAGE_FROM_SYSTEM |
32720                              FORMAT_MESSAGE_IGNORE_INSERTS,
32721                              NULL,
32722                              lastErrno,
32723                              0,
32724                              (LPSTR) &zTemp,
32725                              0,
32726                              0);
32727     if( dwLen > 0 ){
32728       /* allocate a buffer and convert to UTF8 */
32729       sqlite3BeginBenignMalloc();
32730       zOut = sqlite3_win32_mbcs_to_utf8(zTemp);
32731       sqlite3EndBenignMalloc();
32732       /* free the system buffer allocated by FormatMessage */
32733       osLocalFree(zTemp);
32734     }
32735   }
32736 #endif
32737   if( 0 == dwLen ){
32738     sqlite3_snprintf(nBuf, zBuf, "OsError 0x%lx (%lu)", lastErrno, lastErrno);
32739   }else{
32740     /* copy a maximum of nBuf chars to output buffer */
32741     sqlite3_snprintf(nBuf, zBuf, "%s", zOut);
32742     /* free the UTF8 buffer */
32743     sqlite3_free(zOut);
32744   }
32745   return 0;
32746 }
32747 
32748 /*
32749 **
32750 ** This function - winLogErrorAtLine() - is only ever called via the macro
32751 ** winLogError().
32752 **
32753 ** This routine is invoked after an error occurs in an OS function.
32754 ** It logs a message using sqlite3_log() containing the current value of
32755 ** error code and, if possible, the human-readable equivalent from 
32756 ** FormatMessage.
32757 **
32758 ** The first argument passed to the macro should be the error code that
32759 ** will be returned to SQLite (e.g. SQLITE_IOERR_DELETE, SQLITE_CANTOPEN). 
32760 ** The two subsequent arguments should be the name of the OS function that
32761 ** failed and the associated file-system path, if any.
32762 */
32763 #define winLogError(a,b,c,d)   winLogErrorAtLine(a,b,c,d,__LINE__)
32764 static int winLogErrorAtLine(
32765   int errcode,                    /* SQLite error code */
32766   DWORD lastErrno,                /* Win32 last error */
32767   const char *zFunc,              /* Name of OS function that failed */
32768   const char *zPath,              /* File path associated with error */
32769   int iLine                       /* Source line number where error occurred */
32770 ){
32771   char zMsg[500];                 /* Human readable error text */
32772   int i;                          /* Loop counter */
32773 
32774   zMsg[0] = 0;
32775   winGetLastErrorMsg(lastErrno, sizeof(zMsg), zMsg);
32776   assert( errcode!=SQLITE_OK );
32777   if( zPath==0 ) zPath = "";
32778   for(i=0; zMsg[i] && zMsg[i]!='\r' && zMsg[i]!='\n'; i++){}
32779   zMsg[i] = 0;
32780   sqlite3_log(errcode,
32781       "os_win.c:%d: (%lu) %s(%s) - %s",
32782       iLine, lastErrno, zFunc, zPath, zMsg
32783   );
32784 
32785   return errcode;
32786 }
32787 
32788 /*
32789 ** The number of times that a ReadFile(), WriteFile(), and DeleteFile()
32790 ** will be retried following a locking error - probably caused by 
32791 ** antivirus software.  Also the initial delay before the first retry.
32792 ** The delay increases linearly with each retry.
32793 */
32794 #ifndef SQLITE_WIN32_IOERR_RETRY
32795 # define SQLITE_WIN32_IOERR_RETRY 10
32796 #endif
32797 #ifndef SQLITE_WIN32_IOERR_RETRY_DELAY
32798 # define SQLITE_WIN32_IOERR_RETRY_DELAY 25
32799 #endif
32800 static int winIoerrRetry = SQLITE_WIN32_IOERR_RETRY;
32801 static int winIoerrRetryDelay = SQLITE_WIN32_IOERR_RETRY_DELAY;
32802 
32803 /*
32804 ** If a ReadFile() or WriteFile() error occurs, invoke this routine
32805 ** to see if it should be retried.  Return TRUE to retry.  Return FALSE
32806 ** to give up with an error.
32807 */
32808 static int winRetryIoerr(int *pnRetry, DWORD *pError){
32809   DWORD e = osGetLastError();
32810   if( *pnRetry>=winIoerrRetry ){
32811     if( pError ){
32812       *pError = e;
32813     }
32814     return 0;
32815   }
32816   if( e==ERROR_ACCESS_DENIED ||
32817       e==ERROR_LOCK_VIOLATION ||
32818       e==ERROR_SHARING_VIOLATION ){
32819     sqlite3_win32_sleep(winIoerrRetryDelay*(1+*pnRetry));
32820     ++*pnRetry;
32821     return 1;
32822   }
32823   if( pError ){
32824     *pError = e;
32825   }
32826   return 0;
32827 }
32828 
32829 /*
32830 ** Log a I/O error retry episode.
32831 */
32832 static void winLogIoerr(int nRetry){
32833   if( nRetry ){
32834     sqlite3_log(SQLITE_IOERR, 
32835       "delayed %dms for lock/sharing conflict",
32836       winIoerrRetryDelay*nRetry*(nRetry+1)/2
32837     );
32838   }
32839 }
32840 
32841 #if SQLITE_OS_WINCE
32842 /*************************************************************************
32843 ** This section contains code for WinCE only.
32844 */
32845 #if !defined(SQLITE_MSVC_LOCALTIME_API) || !SQLITE_MSVC_LOCALTIME_API
32846 /*
32847 ** The MSVC CRT on Windows CE may not have a localtime() function.  So
32848 ** create a substitute.
32849 */
32850 /* #include <time.h> */
32851 struct tm *__cdecl localtime(const time_t *t)
32852 {
32853   static struct tm y;
32854   FILETIME uTm, lTm;
32855   SYSTEMTIME pTm;
32856   sqlite3_int64 t64;
32857   t64 = *t;
32858   t64 = (t64 + 11644473600)*10000000;
32859   uTm.dwLowDateTime = (DWORD)(t64 & 0xFFFFFFFF);
32860   uTm.dwHighDateTime= (DWORD)(t64 >> 32);
32861   osFileTimeToLocalFileTime(&uTm,&lTm);
32862   osFileTimeToSystemTime(&lTm,&pTm);
32863   y.tm_year = pTm.wYear - 1900;
32864   y.tm_mon = pTm.wMonth - 1;
32865   y.tm_wday = pTm.wDayOfWeek;
32866   y.tm_mday = pTm.wDay;
32867   y.tm_hour = pTm.wHour;
32868   y.tm_min = pTm.wMinute;
32869   y.tm_sec = pTm.wSecond;
32870   return &y;
32871 }
32872 #endif
32873 
32874 #define HANDLE_TO_WINFILE(a) (winFile*)&((char*)a)[-(int)offsetof(winFile,h)]
32875 
32876 /*
32877 ** Acquire a lock on the handle h
32878 */
32879 static void winceMutexAcquire(HANDLE h){
32880    DWORD dwErr;
32881    do {
32882      dwErr = osWaitForSingleObject(h, INFINITE);
32883    } while (dwErr != WAIT_OBJECT_0 && dwErr != WAIT_ABANDONED);
32884 }
32885 /*
32886 ** Release a lock acquired by winceMutexAcquire()
32887 */
32888 #define winceMutexRelease(h) ReleaseMutex(h)
32889 
32890 /*
32891 ** Create the mutex and shared memory used for locking in the file
32892 ** descriptor pFile
32893 */
32894 static int winceCreateLock(const char *zFilename, winFile *pFile){
32895   LPWSTR zTok;
32896   LPWSTR zName;
32897   DWORD lastErrno;
32898   BOOL bLogged = FALSE;
32899   BOOL bInit = TRUE;
32900 
32901   zName = winUtf8ToUnicode(zFilename);
32902   if( zName==0 ){
32903     /* out of memory */
32904     return SQLITE_IOERR_NOMEM;
32905   }
32906 
32907   /* Initialize the local lockdata */
32908   memset(&pFile->local, 0, sizeof(pFile->local));
32909 
32910   /* Replace the backslashes from the filename and lowercase it
32911   ** to derive a mutex name. */
32912   zTok = osCharLowerW(zName);
32913   for (;*zTok;zTok++){
32914     if (*zTok == '\\') *zTok = '_';
32915   }
32916 
32917   /* Create/open the named mutex */
32918   pFile->hMutex = osCreateMutexW(NULL, FALSE, zName);
32919   if (!pFile->hMutex){
32920     pFile->lastErrno = osGetLastError();
32921     sqlite3_free(zName);
32922     return winLogError(SQLITE_IOERR, pFile->lastErrno,
32923                        "winceCreateLock1", zFilename);
32924   }
32925 
32926   /* Acquire the mutex before continuing */
32927   winceMutexAcquire(pFile->hMutex);
32928   
32929   /* Since the names of named mutexes, semaphores, file mappings etc are 
32930   ** case-sensitive, take advantage of that by uppercasing the mutex name
32931   ** and using that as the shared filemapping name.
32932   */
32933   osCharUpperW(zName);
32934   pFile->hShared = osCreateFileMappingW(INVALID_HANDLE_VALUE, NULL,
32935                                         PAGE_READWRITE, 0, sizeof(winceLock),
32936                                         zName);  
32937 
32938   /* Set a flag that indicates we're the first to create the memory so it 
32939   ** must be zero-initialized */
32940   lastErrno = osGetLastError();
32941   if (lastErrno == ERROR_ALREADY_EXISTS){
32942     bInit = FALSE;
32943   }
32944 
32945   sqlite3_free(zName);
32946 
32947   /* If we succeeded in making the shared memory handle, map it. */
32948   if( pFile->hShared ){
32949     pFile->shared = (winceLock*)osMapViewOfFile(pFile->hShared, 
32950              FILE_MAP_READ|FILE_MAP_WRITE, 0, 0, sizeof(winceLock));
32951     /* If mapping failed, close the shared memory handle and erase it */
32952     if( !pFile->shared ){
32953       pFile->lastErrno = osGetLastError();
32954       winLogError(SQLITE_IOERR, pFile->lastErrno,
32955                   "winceCreateLock2", zFilename);
32956       bLogged = TRUE;
32957       osCloseHandle(pFile->hShared);
32958       pFile->hShared = NULL;
32959     }
32960   }
32961 
32962   /* If shared memory could not be created, then close the mutex and fail */
32963   if( pFile->hShared==NULL ){
32964     if( !bLogged ){
32965       pFile->lastErrno = lastErrno;
32966       winLogError(SQLITE_IOERR, pFile->lastErrno,
32967                   "winceCreateLock3", zFilename);
32968       bLogged = TRUE;
32969     }
32970     winceMutexRelease(pFile->hMutex);
32971     osCloseHandle(pFile->hMutex);
32972     pFile->hMutex = NULL;
32973     return SQLITE_IOERR;
32974   }
32975   
32976   /* Initialize the shared memory if we're supposed to */
32977   if( bInit ){
32978     memset(pFile->shared, 0, sizeof(winceLock));
32979   }
32980 
32981   winceMutexRelease(pFile->hMutex);
32982   return SQLITE_OK;
32983 }
32984 
32985 /*
32986 ** Destroy the part of winFile that deals with wince locks
32987 */
32988 static void winceDestroyLock(winFile *pFile){
32989   if (pFile->hMutex){
32990     /* Acquire the mutex */
32991     winceMutexAcquire(pFile->hMutex);
32992 
32993     /* The following blocks should probably assert in debug mode, but they
32994        are to cleanup in case any locks remained open */
32995     if (pFile->local.nReaders){
32996       pFile->shared->nReaders --;
32997     }
32998     if (pFile->local.bReserved){
32999       pFile->shared->bReserved = FALSE;
33000     }
33001     if (pFile->local.bPending){
33002       pFile->shared->bPending = FALSE;
33003     }
33004     if (pFile->local.bExclusive){
33005       pFile->shared->bExclusive = FALSE;
33006     }
33007 
33008     /* De-reference and close our copy of the shared memory handle */
33009     osUnmapViewOfFile(pFile->shared);
33010     osCloseHandle(pFile->hShared);
33011 
33012     /* Done with the mutex */
33013     winceMutexRelease(pFile->hMutex);    
33014     osCloseHandle(pFile->hMutex);
33015     pFile->hMutex = NULL;
33016   }
33017 }
33018 
33019 /* 
33020 ** An implementation of the LockFile() API of Windows for CE
33021 */
33022 static BOOL winceLockFile(
33023   LPHANDLE phFile,
33024   DWORD dwFileOffsetLow,
33025   DWORD dwFileOffsetHigh,
33026   DWORD nNumberOfBytesToLockLow,
33027   DWORD nNumberOfBytesToLockHigh
33028 ){
33029   winFile *pFile = HANDLE_TO_WINFILE(phFile);
33030   BOOL bReturn = FALSE;
33031 
33032   UNUSED_PARAMETER(dwFileOffsetHigh);
33033   UNUSED_PARAMETER(nNumberOfBytesToLockHigh);
33034 
33035   if (!pFile->hMutex) return TRUE;
33036   winceMutexAcquire(pFile->hMutex);
33037 
33038   /* Wanting an exclusive lock? */
33039   if (dwFileOffsetLow == (DWORD)SHARED_FIRST
33040        && nNumberOfBytesToLockLow == (DWORD)SHARED_SIZE){
33041     if (pFile->shared->nReaders == 0 && pFile->shared->bExclusive == 0){
33042        pFile->shared->bExclusive = TRUE;
33043        pFile->local.bExclusive = TRUE;
33044        bReturn = TRUE;
33045     }
33046   }
33047 
33048   /* Want a read-only lock? */
33049   else if (dwFileOffsetLow == (DWORD)SHARED_FIRST &&
33050            nNumberOfBytesToLockLow == 1){
33051     if (pFile->shared->bExclusive == 0){
33052       pFile->local.nReaders ++;
33053       if (pFile->local.nReaders == 1){
33054         pFile->shared->nReaders ++;
33055       }
33056       bReturn = TRUE;
33057     }
33058   }
33059 
33060   /* Want a pending lock? */
33061   else if (dwFileOffsetLow == (DWORD)PENDING_BYTE
33062            && nNumberOfBytesToLockLow == 1){
33063     /* If no pending lock has been acquired, then acquire it */
33064     if (pFile->shared->bPending == 0) {
33065       pFile->shared->bPending = TRUE;
33066       pFile->local.bPending = TRUE;
33067       bReturn = TRUE;
33068     }
33069   }
33070 
33071   /* Want a reserved lock? */
33072   else if (dwFileOffsetLow == (DWORD)RESERVED_BYTE
33073            && nNumberOfBytesToLockLow == 1){
33074     if (pFile->shared->bReserved == 0) {
33075       pFile->shared->bReserved = TRUE;
33076       pFile->local.bReserved = TRUE;
33077       bReturn = TRUE;
33078     }
33079   }
33080 
33081   winceMutexRelease(pFile->hMutex);
33082   return bReturn;
33083 }
33084 
33085 /*
33086 ** An implementation of the UnlockFile API of Windows for CE
33087 */
33088 static BOOL winceUnlockFile(
33089   LPHANDLE phFile,
33090   DWORD dwFileOffsetLow,
33091   DWORD dwFileOffsetHigh,
33092   DWORD nNumberOfBytesToUnlockLow,
33093   DWORD nNumberOfBytesToUnlockHigh
33094 ){
33095   winFile *pFile = HANDLE_TO_WINFILE(phFile);
33096   BOOL bReturn = FALSE;
33097 
33098   UNUSED_PARAMETER(dwFileOffsetHigh);
33099   UNUSED_PARAMETER(nNumberOfBytesToUnlockHigh);
33100 
33101   if (!pFile->hMutex) return TRUE;
33102   winceMutexAcquire(pFile->hMutex);
33103 
33104   /* Releasing a reader lock or an exclusive lock */
33105   if (dwFileOffsetLow == (DWORD)SHARED_FIRST){
33106     /* Did we have an exclusive lock? */
33107     if (pFile->local.bExclusive){
33108       assert(nNumberOfBytesToUnlockLow == (DWORD)SHARED_SIZE);
33109       pFile->local.bExclusive = FALSE;
33110       pFile->shared->bExclusive = FALSE;
33111       bReturn = TRUE;
33112     }
33113 
33114     /* Did we just have a reader lock? */
33115     else if (pFile->local.nReaders){
33116       assert(nNumberOfBytesToUnlockLow == (DWORD)SHARED_SIZE
33117              || nNumberOfBytesToUnlockLow == 1);
33118       pFile->local.nReaders --;
33119       if (pFile->local.nReaders == 0)
33120       {
33121         pFile->shared->nReaders --;
33122       }
33123       bReturn = TRUE;
33124     }
33125   }
33126 
33127   /* Releasing a pending lock */
33128   else if (dwFileOffsetLow == (DWORD)PENDING_BYTE
33129            && nNumberOfBytesToUnlockLow == 1){
33130     if (pFile->local.bPending){
33131       pFile->local.bPending = FALSE;
33132       pFile->shared->bPending = FALSE;
33133       bReturn = TRUE;
33134     }
33135   }
33136   /* Releasing a reserved lock */
33137   else if (dwFileOffsetLow == (DWORD)RESERVED_BYTE
33138            && nNumberOfBytesToUnlockLow == 1){
33139     if (pFile->local.bReserved) {
33140       pFile->local.bReserved = FALSE;
33141       pFile->shared->bReserved = FALSE;
33142       bReturn = TRUE;
33143     }
33144   }
33145 
33146   winceMutexRelease(pFile->hMutex);
33147   return bReturn;
33148 }
33149 /*
33150 ** End of the special code for wince
33151 *****************************************************************************/
33152 #endif /* SQLITE_OS_WINCE */
33153 
33154 /*
33155 ** Lock a file region.
33156 */
33157 static BOOL winLockFile(
33158   LPHANDLE phFile,
33159   DWORD flags,
33160   DWORD offsetLow,
33161   DWORD offsetHigh,
33162   DWORD numBytesLow,
33163   DWORD numBytesHigh
33164 ){
33165 #if SQLITE_OS_WINCE
33166   /*
33167   ** NOTE: Windows CE is handled differently here due its lack of the Win32
33168   **       API LockFile.
33169   */
33170   return winceLockFile(phFile, offsetLow, offsetHigh,
33171                        numBytesLow, numBytesHigh);
33172 #else
33173   if( osIsNT() ){
33174     OVERLAPPED ovlp;
33175     memset(&ovlp, 0, sizeof(OVERLAPPED));
33176     ovlp.Offset = offsetLow;
33177     ovlp.OffsetHigh = offsetHigh;
33178     return osLockFileEx(*phFile, flags, 0, numBytesLow, numBytesHigh, &ovlp);
33179   }else{
33180     return osLockFile(*phFile, offsetLow, offsetHigh, numBytesLow,
33181                       numBytesHigh);
33182   }
33183 #endif
33184 }
33185 
33186 /*
33187 ** Unlock a file region.
33188  */
33189 static BOOL winUnlockFile(
33190   LPHANDLE phFile,
33191   DWORD offsetLow,
33192   DWORD offsetHigh,
33193   DWORD numBytesLow,
33194   DWORD numBytesHigh
33195 ){
33196 #if SQLITE_OS_WINCE
33197   /*
33198   ** NOTE: Windows CE is handled differently here due its lack of the Win32
33199   **       API UnlockFile.
33200   */
33201   return winceUnlockFile(phFile, offsetLow, offsetHigh,
33202                          numBytesLow, numBytesHigh);
33203 #else
33204   if( osIsNT() ){
33205     OVERLAPPED ovlp;
33206     memset(&ovlp, 0, sizeof(OVERLAPPED));
33207     ovlp.Offset = offsetLow;
33208     ovlp.OffsetHigh = offsetHigh;
33209     return osUnlockFileEx(*phFile, 0, numBytesLow, numBytesHigh, &ovlp);
33210   }else{
33211     return osUnlockFile(*phFile, offsetLow, offsetHigh, numBytesLow,
33212                         numBytesHigh);
33213   }
33214 #endif
33215 }
33216 
33217 /*****************************************************************************
33218 ** The next group of routines implement the I/O methods specified
33219 ** by the sqlite3_io_methods object.
33220 ******************************************************************************/
33221 
33222 /*
33223 ** Some Microsoft compilers lack this definition.
33224 */
33225 #ifndef INVALID_SET_FILE_POINTER
33226 # define INVALID_SET_FILE_POINTER ((DWORD)-1)
33227 #endif
33228 
33229 /*
33230 ** Move the current position of the file handle passed as the first 
33231 ** argument to offset iOffset within the file. If successful, return 0. 
33232 ** Otherwise, set pFile->lastErrno and return non-zero.
33233 */
33234 static int winSeekFile(winFile *pFile, sqlite3_int64 iOffset){
33235 #if !SQLITE_OS_WINRT
33236   LONG upperBits;                 /* Most sig. 32 bits of new offset */
33237   LONG lowerBits;                 /* Least sig. 32 bits of new offset */
33238   DWORD dwRet;                    /* Value returned by SetFilePointer() */
33239   DWORD lastErrno;                /* Value returned by GetLastError() */
33240 
33241   OSTRACE(("SEEK file=%p, offset=%lld\n", pFile->h, iOffset));
33242 
33243   upperBits = (LONG)((iOffset>>32) & 0x7fffffff);
33244   lowerBits = (LONG)(iOffset & 0xffffffff);
33245 
33246   /* API oddity: If successful, SetFilePointer() returns a dword 
33247   ** containing the lower 32-bits of the new file-offset. Or, if it fails,
33248   ** it returns INVALID_SET_FILE_POINTER. However according to MSDN, 
33249   ** INVALID_SET_FILE_POINTER may also be a valid new offset. So to determine 
33250   ** whether an error has actually occurred, it is also necessary to call 
33251   ** GetLastError().
33252   */
33253   dwRet = osSetFilePointer(pFile->h, lowerBits, &upperBits, FILE_BEGIN);
33254 
33255   if( (dwRet==INVALID_SET_FILE_POINTER
33256       && ((lastErrno = osGetLastError())!=NO_ERROR)) ){
33257     pFile->lastErrno = lastErrno;
33258     winLogError(SQLITE_IOERR_SEEK, pFile->lastErrno,
33259                 "winSeekFile", pFile->zPath);
33260     OSTRACE(("SEEK file=%p, rc=SQLITE_IOERR_SEEK\n", pFile->h));
33261     return 1;
33262   }
33263 
33264   OSTRACE(("SEEK file=%p, rc=SQLITE_OK\n", pFile->h));
33265   return 0;
33266 #else
33267   /*
33268   ** Same as above, except that this implementation works for WinRT.
33269   */
33270 
33271   LARGE_INTEGER x;                /* The new offset */
33272   BOOL bRet;                      /* Value returned by SetFilePointerEx() */
33273 
33274   x.QuadPart = iOffset;
33275   bRet = osSetFilePointerEx(pFile->h, x, 0, FILE_BEGIN);
33276 
33277   if(!bRet){
33278     pFile->lastErrno = osGetLastError();
33279     winLogError(SQLITE_IOERR_SEEK, pFile->lastErrno,
33280                 "winSeekFile", pFile->zPath);
33281     OSTRACE(("SEEK file=%p, rc=SQLITE_IOERR_SEEK\n", pFile->h));
33282     return 1;
33283   }
33284 
33285   OSTRACE(("SEEK file=%p, rc=SQLITE_OK\n", pFile->h));
33286   return 0;
33287 #endif
33288 }
33289 
33290 #if SQLITE_MAX_MMAP_SIZE>0
33291 /* Forward references to VFS helper methods used for memory mapped files */
33292 static int winMapfile(winFile*, sqlite3_int64);
33293 static int winUnmapfile(winFile*);
33294 #endif
33295 
33296 /*
33297 ** Close a file.
33298 **
33299 ** It is reported that an attempt to close a handle might sometimes
33300 ** fail.  This is a very unreasonable result, but Windows is notorious
33301 ** for being unreasonable so I do not doubt that it might happen.  If
33302 ** the close fails, we pause for 100 milliseconds and try again.  As
33303 ** many as MX_CLOSE_ATTEMPT attempts to close the handle are made before
33304 ** giving up and returning an error.
33305 */
33306 #define MX_CLOSE_ATTEMPT 3
33307 static int winClose(sqlite3_file *id){
33308   int rc, cnt = 0;
33309   winFile *pFile = (winFile*)id;
33310 
33311   assert( id!=0 );
33312 #ifndef SQLITE_OMIT_WAL
33313   assert( pFile->pShm==0 );
33314 #endif
33315   assert( pFile->h!=NULL && pFile->h!=INVALID_HANDLE_VALUE );
33316   OSTRACE(("CLOSE file=%p\n", pFile->h));
33317 
33318 #if SQLITE_MAX_MMAP_SIZE>0
33319   winUnmapfile(pFile);
33320 #endif
33321 
33322   do{
33323     rc = osCloseHandle(pFile->h);
33324     /* SimulateIOError( rc=0; cnt=MX_CLOSE_ATTEMPT; ); */
33325   }while( rc==0 && ++cnt < MX_CLOSE_ATTEMPT && (sqlite3_win32_sleep(100), 1) );
33326 #if SQLITE_OS_WINCE
33327 #define WINCE_DELETION_ATTEMPTS 3
33328   winceDestroyLock(pFile);
33329   if( pFile->zDeleteOnClose ){
33330     int cnt = 0;
33331     while(
33332            osDeleteFileW(pFile->zDeleteOnClose)==0
33333         && osGetFileAttributesW(pFile->zDeleteOnClose)!=0xffffffff 
33334         && cnt++ < WINCE_DELETION_ATTEMPTS
33335     ){
33336        sqlite3_win32_sleep(100);  /* Wait a little before trying again */
33337     }
33338     sqlite3_free(pFile->zDeleteOnClose);
33339   }
33340 #endif
33341   if( rc ){
33342     pFile->h = NULL;
33343   }
33344   OpenCounter(-1);
33345   OSTRACE(("CLOSE file=%p, rc=%s\n", pFile->h, rc ? "ok" : "failed"));
33346   return rc ? SQLITE_OK
33347             : winLogError(SQLITE_IOERR_CLOSE, osGetLastError(),
33348                           "winClose", pFile->zPath);
33349 }
33350 
33351 /*
33352 ** Read data from a file into a buffer.  Return SQLITE_OK if all
33353 ** bytes were read successfully and SQLITE_IOERR if anything goes
33354 ** wrong.
33355 */
33356 static int winRead(
33357   sqlite3_file *id,          /* File to read from */
33358   void *pBuf,                /* Write content into this buffer */
33359   int amt,                   /* Number of bytes to read */
33360   sqlite3_int64 offset       /* Begin reading at this offset */
33361 ){
33362 #if !SQLITE_OS_WINCE
33363   OVERLAPPED overlapped;          /* The offset for ReadFile. */
33364 #endif
33365   winFile *pFile = (winFile*)id;  /* file handle */
33366   DWORD nRead;                    /* Number of bytes actually read from file */
33367   int nRetry = 0;                 /* Number of retrys */
33368 
33369   assert( id!=0 );
33370   assert( amt>0 );
33371   assert( offset>=0 );
33372   SimulateIOError(return SQLITE_IOERR_READ);
33373   OSTRACE(("READ file=%p, buffer=%p, amount=%d, offset=%lld, lock=%d\n",
33374            pFile->h, pBuf, amt, offset, pFile->locktype));
33375 
33376 #if SQLITE_MAX_MMAP_SIZE>0
33377   /* Deal with as much of this read request as possible by transfering
33378   ** data from the memory mapping using memcpy().  */
33379   if( offset<pFile->mmapSize ){
33380     if( offset+amt <= pFile->mmapSize ){
33381       memcpy(pBuf, &((u8 *)(pFile->pMapRegion))[offset], amt);
33382       OSTRACE(("READ-MMAP file=%p, rc=SQLITE_OK\n", pFile->h));
33383       return SQLITE_OK;
33384     }else{
33385       int nCopy = (int)(pFile->mmapSize - offset);
33386       memcpy(pBuf, &((u8 *)(pFile->pMapRegion))[offset], nCopy);
33387       pBuf = &((u8 *)pBuf)[nCopy];
33388       amt -= nCopy;
33389       offset += nCopy;
33390     }
33391   }
33392 #endif
33393 
33394 #if SQLITE_OS_WINCE
33395   if( winSeekFile(pFile, offset) ){
33396     OSTRACE(("READ file=%p, rc=SQLITE_FULL\n", pFile->h));
33397     return SQLITE_FULL;
33398   }
33399   while( !osReadFile(pFile->h, pBuf, amt, &nRead, 0) ){
33400 #else
33401   memset(&overlapped, 0, sizeof(OVERLAPPED));
33402   overlapped.Offset = (LONG)(offset & 0xffffffff);
33403   overlapped.OffsetHigh = (LONG)((offset>>32) & 0x7fffffff);
33404   while( !osReadFile(pFile->h, pBuf, amt, &nRead, &overlapped) &&
33405          osGetLastError()!=ERROR_HANDLE_EOF ){
33406 #endif
33407     DWORD lastErrno;
33408     if( winRetryIoerr(&nRetry, &lastErrno) ) continue;
33409     pFile->lastErrno = lastErrno;
33410     OSTRACE(("READ file=%p, rc=SQLITE_IOERR_READ\n", pFile->h));
33411     return winLogError(SQLITE_IOERR_READ, pFile->lastErrno,
33412                        "winRead", pFile->zPath);
33413   }
33414   winLogIoerr(nRetry);
33415   if( nRead<(DWORD)amt ){
33416     /* Unread parts of the buffer must be zero-filled */
33417     memset(&((char*)pBuf)[nRead], 0, amt-nRead);
33418     OSTRACE(("READ file=%p, rc=SQLITE_IOERR_SHORT_READ\n", pFile->h));
33419     return SQLITE_IOERR_SHORT_READ;
33420   }
33421 
33422   OSTRACE(("READ file=%p, rc=SQLITE_OK\n", pFile->h));
33423   return SQLITE_OK;
33424 }
33425 
33426 /*
33427 ** Write data from a buffer into a file.  Return SQLITE_OK on success
33428 ** or some other error code on failure.
33429 */
33430 static int winWrite(
33431   sqlite3_file *id,               /* File to write into */
33432   const void *pBuf,               /* The bytes to be written */
33433   int amt,                        /* Number of bytes to write */
33434   sqlite3_int64 offset            /* Offset into the file to begin writing at */
33435 ){
33436   int rc = 0;                     /* True if error has occurred, else false */
33437   winFile *pFile = (winFile*)id;  /* File handle */
33438   int nRetry = 0;                 /* Number of retries */
33439 
33440   assert( amt>0 );
33441   assert( pFile );
33442   SimulateIOError(return SQLITE_IOERR_WRITE);
33443   SimulateDiskfullError(return SQLITE_FULL);
33444 
33445   OSTRACE(("WRITE file=%p, buffer=%p, amount=%d, offset=%lld, lock=%d\n",
33446            pFile->h, pBuf, amt, offset, pFile->locktype));
33447 
33448 #if SQLITE_MAX_MMAP_SIZE>0
33449   /* Deal with as much of this write request as possible by transfering
33450   ** data from the memory mapping using memcpy().  */
33451   if( offset<pFile->mmapSize ){
33452     if( offset+amt <= pFile->mmapSize ){
33453       memcpy(&((u8 *)(pFile->pMapRegion))[offset], pBuf, amt);
33454       OSTRACE(("WRITE-MMAP file=%p, rc=SQLITE_OK\n", pFile->h));
33455       return SQLITE_OK;
33456     }else{
33457       int nCopy = (int)(pFile->mmapSize - offset);
33458       memcpy(&((u8 *)(pFile->pMapRegion))[offset], pBuf, nCopy);
33459       pBuf = &((u8 *)pBuf)[nCopy];
33460       amt -= nCopy;
33461       offset += nCopy;
33462     }
33463   }
33464 #endif
33465 
33466 #if SQLITE_OS_WINCE
33467   rc = winSeekFile(pFile, offset);
33468   if( rc==0 ){
33469 #else
33470   {
33471 #endif
33472 #if !SQLITE_OS_WINCE
33473     OVERLAPPED overlapped;        /* The offset for WriteFile. */
33474 #endif
33475     u8 *aRem = (u8 *)pBuf;        /* Data yet to be written */
33476     int nRem = amt;               /* Number of bytes yet to be written */
33477     DWORD nWrite;                 /* Bytes written by each WriteFile() call */
33478     DWORD lastErrno = NO_ERROR;   /* Value returned by GetLastError() */
33479 
33480 #if !SQLITE_OS_WINCE
33481     memset(&overlapped, 0, sizeof(OVERLAPPED));
33482     overlapped.Offset = (LONG)(offset & 0xffffffff);
33483     overlapped.OffsetHigh = (LONG)((offset>>32) & 0x7fffffff);
33484 #endif
33485 
33486     while( nRem>0 ){
33487 #if SQLITE_OS_WINCE
33488       if( !osWriteFile(pFile->h, aRem, nRem, &nWrite, 0) ){
33489 #else
33490       if( !osWriteFile(pFile->h, aRem, nRem, &nWrite, &overlapped) ){
33491 #endif
33492         if( winRetryIoerr(&nRetry, &lastErrno) ) continue;
33493         break;
33494       }
33495       assert( nWrite==0 || nWrite<=(DWORD)nRem );
33496       if( nWrite==0 || nWrite>(DWORD)nRem ){
33497         lastErrno = osGetLastError();
33498         break;
33499       }
33500 #if !SQLITE_OS_WINCE
33501       offset += nWrite;
33502       overlapped.Offset = (LONG)(offset & 0xffffffff);
33503       overlapped.OffsetHigh = (LONG)((offset>>32) & 0x7fffffff);
33504 #endif
33505       aRem += nWrite;
33506       nRem -= nWrite;
33507     }
33508     if( nRem>0 ){
33509       pFile->lastErrno = lastErrno;
33510       rc = 1;
33511     }
33512   }
33513 
33514   if( rc ){
33515     if(   ( pFile->lastErrno==ERROR_HANDLE_DISK_FULL )
33516        || ( pFile->lastErrno==ERROR_DISK_FULL )){
33517       OSTRACE(("WRITE file=%p, rc=SQLITE_FULL\n", pFile->h));
33518       return winLogError(SQLITE_FULL, pFile->lastErrno,
33519                          "winWrite1", pFile->zPath);
33520     }
33521     OSTRACE(("WRITE file=%p, rc=SQLITE_IOERR_WRITE\n", pFile->h));
33522     return winLogError(SQLITE_IOERR_WRITE, pFile->lastErrno,
33523                        "winWrite2", pFile->zPath);
33524   }else{
33525     winLogIoerr(nRetry);
33526   }
33527   OSTRACE(("WRITE file=%p, rc=SQLITE_OK\n", pFile->h));
33528   return SQLITE_OK;
33529 }
33530 
33531 /*
33532 ** Truncate an open file to a specified size
33533 */
33534 static int winTruncate(sqlite3_file *id, sqlite3_int64 nByte){
33535   winFile *pFile = (winFile*)id;  /* File handle object */
33536   int rc = SQLITE_OK;             /* Return code for this function */
33537   DWORD lastErrno;
33538 
33539   assert( pFile );
33540   SimulateIOError(return SQLITE_IOERR_TRUNCATE);
33541   OSTRACE(("TRUNCATE file=%p, size=%lld, lock=%d\n",
33542            pFile->h, nByte, pFile->locktype));
33543 
33544   /* If the user has configured a chunk-size for this file, truncate the
33545   ** file so that it consists of an integer number of chunks (i.e. the
33546   ** actual file size after the operation may be larger than the requested
33547   ** size).
33548   */
33549   if( pFile->szChunk>0 ){
33550     nByte = ((nByte + pFile->szChunk - 1)/pFile->szChunk) * pFile->szChunk;
33551   }
33552 
33553   /* SetEndOfFile() returns non-zero when successful, or zero when it fails. */
33554   if( winSeekFile(pFile, nByte) ){
33555     rc = winLogError(SQLITE_IOERR_TRUNCATE, pFile->lastErrno,
33556                      "winTruncate1", pFile->zPath);
33557   }else if( 0==osSetEndOfFile(pFile->h) &&
33558             ((lastErrno = osGetLastError())!=ERROR_USER_MAPPED_FILE) ){
33559     pFile->lastErrno = lastErrno;
33560     rc = winLogError(SQLITE_IOERR_TRUNCATE, pFile->lastErrno,
33561                      "winTruncate2", pFile->zPath);
33562   }
33563 
33564 #if SQLITE_MAX_MMAP_SIZE>0
33565   /* If the file was truncated to a size smaller than the currently
33566   ** mapped region, reduce the effective mapping size as well. SQLite will
33567   ** use read() and write() to access data beyond this point from now on.
33568   */
33569   if( pFile->pMapRegion && nByte<pFile->mmapSize ){
33570     pFile->mmapSize = nByte;
33571   }
33572 #endif
33573 
33574   OSTRACE(("TRUNCATE file=%p, rc=%s\n", pFile->h, sqlite3ErrName(rc)));
33575   return rc;
33576 }
33577 
33578 #ifdef SQLITE_TEST
33579 /*
33580 ** Count the number of fullsyncs and normal syncs.  This is used to test
33581 ** that syncs and fullsyncs are occuring at the right times.
33582 */
33583 SQLITE_API int sqlite3_sync_count = 0;
33584 SQLITE_API int sqlite3_fullsync_count = 0;
33585 #endif
33586 
33587 /*
33588 ** Make sure all writes to a particular file are committed to disk.
33589 */
33590 static int winSync(sqlite3_file *id, int flags){
33591 #ifndef SQLITE_NO_SYNC
33592   /*
33593   ** Used only when SQLITE_NO_SYNC is not defined.
33594    */
33595   BOOL rc;
33596 #endif
33597 #if !defined(NDEBUG) || !defined(SQLITE_NO_SYNC) || \
33598     (defined(SQLITE_TEST) && defined(SQLITE_DEBUG))
33599   /*
33600   ** Used when SQLITE_NO_SYNC is not defined and by the assert() and/or
33601   ** OSTRACE() macros.
33602    */
33603   winFile *pFile = (winFile*)id;
33604 #else
33605   UNUSED_PARAMETER(id);
33606 #endif
33607 
33608   assert( pFile );
33609   /* Check that one of SQLITE_SYNC_NORMAL or FULL was passed */
33610   assert((flags&0x0F)==SQLITE_SYNC_NORMAL
33611       || (flags&0x0F)==SQLITE_SYNC_FULL
33612   );
33613 
33614   /* Unix cannot, but some systems may return SQLITE_FULL from here. This
33615   ** line is to test that doing so does not cause any problems.
33616   */
33617   SimulateDiskfullError( return SQLITE_FULL );
33618 
33619   OSTRACE(("SYNC file=%p, flags=%x, lock=%d\n",
33620            pFile->h, flags, pFile->locktype));
33621 
33622 #ifndef SQLITE_TEST
33623   UNUSED_PARAMETER(flags);
33624 #else
33625   if( (flags&0x0F)==SQLITE_SYNC_FULL ){
33626     sqlite3_fullsync_count++;
33627   }
33628   sqlite3_sync_count++;
33629 #endif
33630 
33631   /* If we compiled with the SQLITE_NO_SYNC flag, then syncing is a
33632   ** no-op
33633   */
33634 #ifdef SQLITE_NO_SYNC
33635   OSTRACE(("SYNC-NOP file=%p, rc=SQLITE_OK\n", pFile->h));
33636   return SQLITE_OK;
33637 #else
33638   rc = osFlushFileBuffers(pFile->h);
33639   SimulateIOError( rc=FALSE );
33640   if( rc ){
33641     OSTRACE(("SYNC file=%p, rc=SQLITE_OK\n", pFile->h));
33642     return SQLITE_OK;
33643   }else{
33644     pFile->lastErrno = osGetLastError();
33645     OSTRACE(("SYNC file=%p, rc=SQLITE_IOERR_FSYNC\n", pFile->h));
33646     return winLogError(SQLITE_IOERR_FSYNC, pFile->lastErrno,
33647                        "winSync", pFile->zPath);
33648   }
33649 #endif
33650 }
33651 
33652 /*
33653 ** Determine the current size of a file in bytes
33654 */
33655 static int winFileSize(sqlite3_file *id, sqlite3_int64 *pSize){
33656   winFile *pFile = (winFile*)id;
33657   int rc = SQLITE_OK;
33658 
33659   assert( id!=0 );
33660   assert( pSize!=0 );
33661   SimulateIOError(return SQLITE_IOERR_FSTAT);
33662   OSTRACE(("SIZE file=%p, pSize=%p\n", pFile->h, pSize));
33663 
33664 #if SQLITE_OS_WINRT
33665   {
33666     FILE_STANDARD_INFO info;
33667     if( osGetFileInformationByHandleEx(pFile->h, FileStandardInfo,
33668                                      &info, sizeof(info)) ){
33669       *pSize = info.EndOfFile.QuadPart;
33670     }else{
33671       pFile->lastErrno = osGetLastError();
33672       rc = winLogError(SQLITE_IOERR_FSTAT, pFile->lastErrno,
33673                        "winFileSize", pFile->zPath);
33674     }
33675   }
33676 #else
33677   {
33678     DWORD upperBits;
33679     DWORD lowerBits;
33680     DWORD lastErrno;
33681 
33682     lowerBits = osGetFileSize(pFile->h, &upperBits);
33683     *pSize = (((sqlite3_int64)upperBits)<<32) + lowerBits;
33684     if(   (lowerBits == INVALID_FILE_SIZE)
33685        && ((lastErrno = osGetLastError())!=NO_ERROR) ){
33686       pFile->lastErrno = lastErrno;
33687       rc = winLogError(SQLITE_IOERR_FSTAT, pFile->lastErrno,
33688                        "winFileSize", pFile->zPath);
33689     }
33690   }
33691 #endif
33692   OSTRACE(("SIZE file=%p, pSize=%p, *pSize=%lld, rc=%s\n",
33693            pFile->h, pSize, *pSize, sqlite3ErrName(rc)));
33694   return rc;
33695 }
33696 
33697 /*
33698 ** LOCKFILE_FAIL_IMMEDIATELY is undefined on some Windows systems.
33699 */
33700 #ifndef LOCKFILE_FAIL_IMMEDIATELY
33701 # define LOCKFILE_FAIL_IMMEDIATELY 1
33702 #endif
33703 
33704 #ifndef LOCKFILE_EXCLUSIVE_LOCK
33705 # define LOCKFILE_EXCLUSIVE_LOCK 2
33706 #endif
33707 
33708 /*
33709 ** Historically, SQLite has used both the LockFile and LockFileEx functions.
33710 ** When the LockFile function was used, it was always expected to fail
33711 ** immediately if the lock could not be obtained.  Also, it always expected to
33712 ** obtain an exclusive lock.  These flags are used with the LockFileEx function
33713 ** and reflect those expectations; therefore, they should not be changed.
33714 */
33715 #ifndef SQLITE_LOCKFILE_FLAGS
33716 # define SQLITE_LOCKFILE_FLAGS   (LOCKFILE_FAIL_IMMEDIATELY | \
33717                                   LOCKFILE_EXCLUSIVE_LOCK)
33718 #endif
33719 
33720 /*
33721 ** Currently, SQLite never calls the LockFileEx function without wanting the
33722 ** call to fail immediately if the lock cannot be obtained.
33723 */
33724 #ifndef SQLITE_LOCKFILEEX_FLAGS
33725 # define SQLITE_LOCKFILEEX_FLAGS (LOCKFILE_FAIL_IMMEDIATELY)
33726 #endif
33727 
33728 /*
33729 ** Acquire a reader lock.
33730 ** Different API routines are called depending on whether or not this
33731 ** is Win9x or WinNT.
33732 */
33733 static int winGetReadLock(winFile *pFile){
33734   int res;
33735   OSTRACE(("READ-LOCK file=%p, lock=%d\n", pFile->h, pFile->locktype));
33736   if( osIsNT() ){
33737 #if SQLITE_OS_WINCE
33738     /*
33739     ** NOTE: Windows CE is handled differently here due its lack of the Win32
33740     **       API LockFileEx.
33741     */
33742     res = winceLockFile(&pFile->h, SHARED_FIRST, 0, 1, 0);
33743 #else
33744     res = winLockFile(&pFile->h, SQLITE_LOCKFILEEX_FLAGS, SHARED_FIRST, 0,
33745                       SHARED_SIZE, 0);
33746 #endif
33747   }
33748 #ifdef SQLITE_WIN32_HAS_ANSI
33749   else{
33750     int lk;
33751     sqlite3_randomness(sizeof(lk), &lk);
33752     pFile->sharedLockByte = (short)((lk & 0x7fffffff)%(SHARED_SIZE - 1));
33753     res = winLockFile(&pFile->h, SQLITE_LOCKFILE_FLAGS,
33754                       SHARED_FIRST+pFile->sharedLockByte, 0, 1, 0);
33755   }
33756 #endif
33757   if( res == 0 ){
33758     pFile->lastErrno = osGetLastError();
33759     /* No need to log a failure to lock */
33760   }
33761   OSTRACE(("READ-LOCK file=%p, rc=%s\n", pFile->h, sqlite3ErrName(res)));
33762   return res;
33763 }
33764 
33765 /*
33766 ** Undo a readlock
33767 */
33768 static int winUnlockReadLock(winFile *pFile){
33769   int res;
33770   DWORD lastErrno;
33771   OSTRACE(("READ-UNLOCK file=%p, lock=%d\n", pFile->h, pFile->locktype));
33772   if( osIsNT() ){
33773     res = winUnlockFile(&pFile->h, SHARED_FIRST, 0, SHARED_SIZE, 0);
33774   }
33775 #ifdef SQLITE_WIN32_HAS_ANSI
33776   else{
33777     res = winUnlockFile(&pFile->h, SHARED_FIRST+pFile->sharedLockByte, 0, 1, 0);
33778   }
33779 #endif
33780   if( res==0 && ((lastErrno = osGetLastError())!=ERROR_NOT_LOCKED) ){
33781     pFile->lastErrno = lastErrno;
33782     winLogError(SQLITE_IOERR_UNLOCK, pFile->lastErrno,
33783                 "winUnlockReadLock", pFile->zPath);
33784   }
33785   OSTRACE(("READ-UNLOCK file=%p, rc=%s\n", pFile->h, sqlite3ErrName(res)));
33786   return res;
33787 }
33788 
33789 /*
33790 ** Lock the file with the lock specified by parameter locktype - one
33791 ** of the following:
33792 **
33793 **     (1) SHARED_LOCK
33794 **     (2) RESERVED_LOCK
33795 **     (3) PENDING_LOCK
33796 **     (4) EXCLUSIVE_LOCK
33797 **
33798 ** Sometimes when requesting one lock state, additional lock states
33799 ** are inserted in between.  The locking might fail on one of the later
33800 ** transitions leaving the lock state different from what it started but
33801 ** still short of its goal.  The following chart shows the allowed
33802 ** transitions and the inserted intermediate states:
33803 **
33804 **    UNLOCKED -> SHARED
33805 **    SHARED -> RESERVED
33806 **    SHARED -> (PENDING) -> EXCLUSIVE
33807 **    RESERVED -> (PENDING) -> EXCLUSIVE
33808 **    PENDING -> EXCLUSIVE
33809 **
33810 ** This routine will only increase a lock.  The winUnlock() routine
33811 ** erases all locks at once and returns us immediately to locking level 0.
33812 ** It is not possible to lower the locking level one step at a time.  You
33813 ** must go straight to locking level 0.
33814 */
33815 static int winLock(sqlite3_file *id, int locktype){
33816   int rc = SQLITE_OK;    /* Return code from subroutines */
33817   int res = 1;           /* Result of a Windows lock call */
33818   int newLocktype;       /* Set pFile->locktype to this value before exiting */
33819   int gotPendingLock = 0;/* True if we acquired a PENDING lock this time */
33820   winFile *pFile = (winFile*)id;
33821   DWORD lastErrno = NO_ERROR;
33822 
33823   assert( id!=0 );
33824   OSTRACE(("LOCK file=%p, oldLock=%d(%d), newLock=%d\n",
33825            pFile->h, pFile->locktype, pFile->sharedLockByte, locktype));
33826 
33827   /* If there is already a lock of this type or more restrictive on the
33828   ** OsFile, do nothing. Don't use the end_lock: exit path, as
33829   ** sqlite3OsEnterMutex() hasn't been called yet.
33830   */
33831   if( pFile->locktype>=locktype ){
33832     OSTRACE(("LOCK-HELD file=%p, rc=SQLITE_OK\n", pFile->h));
33833     return SQLITE_OK;
33834   }
33835 
33836   /* Make sure the locking sequence is correct
33837   */
33838   assert( pFile->locktype!=NO_LOCK || locktype==SHARED_LOCK );
33839   assert( locktype!=PENDING_LOCK );
33840   assert( locktype!=RESERVED_LOCK || pFile->locktype==SHARED_LOCK );
33841 
33842   /* Lock the PENDING_LOCK byte if we need to acquire a PENDING lock or
33843   ** a SHARED lock.  If we are acquiring a SHARED lock, the acquisition of
33844   ** the PENDING_LOCK byte is temporary.
33845   */
33846   newLocktype = pFile->locktype;
33847   if(   (pFile->locktype==NO_LOCK)
33848      || (   (locktype==EXCLUSIVE_LOCK)
33849          && (pFile->locktype==RESERVED_LOCK))
33850   ){
33851     int cnt = 3;
33852     while( cnt-->0 && (res = winLockFile(&pFile->h, SQLITE_LOCKFILE_FLAGS,
33853                                          PENDING_BYTE, 0, 1, 0))==0 ){
33854       /* Try 3 times to get the pending lock.  This is needed to work
33855       ** around problems caused by indexing and/or anti-virus software on
33856       ** Windows systems.
33857       ** If you are using this code as a model for alternative VFSes, do not
33858       ** copy this retry logic.  It is a hack intended for Windows only.
33859       */
33860       OSTRACE(("LOCK-PENDING-FAIL file=%p, count=%d, rc=%s\n",
33861                pFile->h, cnt, sqlite3ErrName(res)));
33862       if( cnt ) sqlite3_win32_sleep(1);
33863     }
33864     gotPendingLock = res;
33865     if( !res ){
33866       lastErrno = osGetLastError();
33867     }
33868   }
33869 
33870   /* Acquire a shared lock
33871   */
33872   if( locktype==SHARED_LOCK && res ){
33873     assert( pFile->locktype==NO_LOCK );
33874     res = winGetReadLock(pFile);
33875     if( res ){
33876       newLocktype = SHARED_LOCK;
33877     }else{
33878       lastErrno = osGetLastError();
33879     }
33880   }
33881 
33882   /* Acquire a RESERVED lock
33883   */
33884   if( locktype==RESERVED_LOCK && res ){
33885     assert( pFile->locktype==SHARED_LOCK );
33886     res = winLockFile(&pFile->h, SQLITE_LOCKFILE_FLAGS, RESERVED_BYTE, 0, 1, 0);
33887     if( res ){
33888       newLocktype = RESERVED_LOCK;
33889     }else{
33890       lastErrno = osGetLastError();
33891     }
33892   }
33893 
33894   /* Acquire a PENDING lock
33895   */
33896   if( locktype==EXCLUSIVE_LOCK && res ){
33897     newLocktype = PENDING_LOCK;
33898     gotPendingLock = 0;
33899   }
33900 
33901   /* Acquire an EXCLUSIVE lock
33902   */
33903   if( locktype==EXCLUSIVE_LOCK && res ){
33904     assert( pFile->locktype>=SHARED_LOCK );
33905     res = winUnlockReadLock(pFile);
33906     res = winLockFile(&pFile->h, SQLITE_LOCKFILE_FLAGS, SHARED_FIRST, 0,
33907                       SHARED_SIZE, 0);
33908     if( res ){
33909       newLocktype = EXCLUSIVE_LOCK;
33910     }else{
33911       lastErrno = osGetLastError();
33912       winGetReadLock(pFile);
33913     }
33914   }
33915 
33916   /* If we are holding a PENDING lock that ought to be released, then
33917   ** release it now.
33918   */
33919   if( gotPendingLock && locktype==SHARED_LOCK ){
33920     winUnlockFile(&pFile->h, PENDING_BYTE, 0, 1, 0);
33921   }
33922 
33923   /* Update the state of the lock has held in the file descriptor then
33924   ** return the appropriate result code.
33925   */
33926   if( res ){
33927     rc = SQLITE_OK;
33928   }else{
33929     pFile->lastErrno = lastErrno;
33930     rc = SQLITE_BUSY;
33931     OSTRACE(("LOCK-FAIL file=%p, wanted=%d, got=%d\n",
33932              pFile->h, locktype, newLocktype));
33933   }
33934   pFile->locktype = (u8)newLocktype;
33935   OSTRACE(("LOCK file=%p, lock=%d, rc=%s\n",
33936            pFile->h, pFile->locktype, sqlite3ErrName(rc)));
33937   return rc;
33938 }
33939 
33940 /*
33941 ** This routine checks if there is a RESERVED lock held on the specified
33942 ** file by this or any other process. If such a lock is held, return
33943 ** non-zero, otherwise zero.
33944 */
33945 static int winCheckReservedLock(sqlite3_file *id, int *pResOut){
33946   int rc;
33947   winFile *pFile = (winFile*)id;
33948 
33949   SimulateIOError( return SQLITE_IOERR_CHECKRESERVEDLOCK; );
33950   OSTRACE(("TEST-WR-LOCK file=%p, pResOut=%p\n", pFile->h, pResOut));
33951 
33952   assert( id!=0 );
33953   if( pFile->locktype>=RESERVED_LOCK ){
33954     rc = 1;
33955     OSTRACE(("TEST-WR-LOCK file=%p, rc=%d (local)\n", pFile->h, rc));
33956   }else{
33957     rc = winLockFile(&pFile->h, SQLITE_LOCKFILEEX_FLAGS,RESERVED_BYTE, 0, 1, 0);
33958     if( rc ){
33959       winUnlockFile(&pFile->h, RESERVED_BYTE, 0, 1, 0);
33960     }
33961     rc = !rc;
33962     OSTRACE(("TEST-WR-LOCK file=%p, rc=%d (remote)\n", pFile->h, rc));
33963   }
33964   *pResOut = rc;
33965   OSTRACE(("TEST-WR-LOCK file=%p, pResOut=%p, *pResOut=%d, rc=SQLITE_OK\n",
33966            pFile->h, pResOut, *pResOut));
33967   return SQLITE_OK;
33968 }
33969 
33970 /*
33971 ** Lower the locking level on file descriptor id to locktype.  locktype
33972 ** must be either NO_LOCK or SHARED_LOCK.
33973 **
33974 ** If the locking level of the file descriptor is already at or below
33975 ** the requested locking level, this routine is a no-op.
33976 **
33977 ** It is not possible for this routine to fail if the second argument
33978 ** is NO_LOCK.  If the second argument is SHARED_LOCK then this routine
33979 ** might return SQLITE_IOERR;
33980 */
33981 static int winUnlock(sqlite3_file *id, int locktype){
33982   int type;
33983   winFile *pFile = (winFile*)id;
33984   int rc = SQLITE_OK;
33985   assert( pFile!=0 );
33986   assert( locktype<=SHARED_LOCK );
33987   OSTRACE(("UNLOCK file=%p, oldLock=%d(%d), newLock=%d\n",
33988            pFile->h, pFile->locktype, pFile->sharedLockByte, locktype));
33989   type = pFile->locktype;
33990   if( type>=EXCLUSIVE_LOCK ){
33991     winUnlockFile(&pFile->h, SHARED_FIRST, 0, SHARED_SIZE, 0);
33992     if( locktype==SHARED_LOCK && !winGetReadLock(pFile) ){
33993       /* This should never happen.  We should always be able to
33994       ** reacquire the read lock */
33995       rc = winLogError(SQLITE_IOERR_UNLOCK, osGetLastError(),
33996                        "winUnlock", pFile->zPath);
33997     }
33998   }
33999   if( type>=RESERVED_LOCK ){
34000     winUnlockFile(&pFile->h, RESERVED_BYTE, 0, 1, 0);
34001   }
34002   if( locktype==NO_LOCK && type>=SHARED_LOCK ){
34003     winUnlockReadLock(pFile);
34004   }
34005   if( type>=PENDING_LOCK ){
34006     winUnlockFile(&pFile->h, PENDING_BYTE, 0, 1, 0);
34007   }
34008   pFile->locktype = (u8)locktype;
34009   OSTRACE(("UNLOCK file=%p, lock=%d, rc=%s\n",
34010            pFile->h, pFile->locktype, sqlite3ErrName(rc)));
34011   return rc;
34012 }
34013 
34014 /*
34015 ** If *pArg is inititially negative then this is a query.  Set *pArg to
34016 ** 1 or 0 depending on whether or not bit mask of pFile->ctrlFlags is set.
34017 **
34018 ** If *pArg is 0 or 1, then clear or set the mask bit of pFile->ctrlFlags.
34019 */
34020 static void winModeBit(winFile *pFile, unsigned char mask, int *pArg){
34021   if( *pArg<0 ){
34022     *pArg = (pFile->ctrlFlags & mask)!=0;
34023   }else if( (*pArg)==0 ){
34024     pFile->ctrlFlags &= ~mask;
34025   }else{
34026     pFile->ctrlFlags |= mask;
34027   }
34028 }
34029 
34030 /* Forward references to VFS helper methods used for temporary files */
34031 static int winGetTempname(sqlite3_vfs *, char **);
34032 static int winIsDir(const void *);
34033 static BOOL winIsDriveLetterAndColon(const char *);
34034 
34035 /*
34036 ** Control and query of the open file handle.
34037 */
34038 static int winFileControl(sqlite3_file *id, int op, void *pArg){
34039   winFile *pFile = (winFile*)id;
34040   OSTRACE(("FCNTL file=%p, op=%d, pArg=%p\n", pFile->h, op, pArg));
34041   switch( op ){
34042     case SQLITE_FCNTL_LOCKSTATE: {
34043       *(int*)pArg = pFile->locktype;
34044       OSTRACE(("FCNTL file=%p, rc=SQLITE_OK\n", pFile->h));
34045       return SQLITE_OK;
34046     }
34047     case SQLITE_LAST_ERRNO: {
34048       *(int*)pArg = (int)pFile->lastErrno;
34049       OSTRACE(("FCNTL file=%p, rc=SQLITE_OK\n", pFile->h));
34050       return SQLITE_OK;
34051     }
34052     case SQLITE_FCNTL_CHUNK_SIZE: {
34053       pFile->szChunk = *(int *)pArg;
34054       OSTRACE(("FCNTL file=%p, rc=SQLITE_OK\n", pFile->h));
34055       return SQLITE_OK;
34056     }
34057     case SQLITE_FCNTL_SIZE_HINT: {
34058       if( pFile->szChunk>0 ){
34059         sqlite3_int64 oldSz;
34060         int rc = winFileSize(id, &oldSz);
34061         if( rc==SQLITE_OK ){
34062           sqlite3_int64 newSz = *(sqlite3_int64*)pArg;
34063           if( newSz>oldSz ){
34064             SimulateIOErrorBenign(1);
34065             rc = winTruncate(id, newSz);
34066             SimulateIOErrorBenign(0);
34067           }
34068         }
34069         OSTRACE(("FCNTL file=%p, rc=%s\n", pFile->h, sqlite3ErrName(rc)));
34070         return rc;
34071       }
34072       OSTRACE(("FCNTL file=%p, rc=SQLITE_OK\n", pFile->h));
34073       return SQLITE_OK;
34074     }
34075     case SQLITE_FCNTL_PERSIST_WAL: {
34076       winModeBit(pFile, WINFILE_PERSIST_WAL, (int*)pArg);
34077       OSTRACE(("FCNTL file=%p, rc=SQLITE_OK\n", pFile->h));
34078       return SQLITE_OK;
34079     }
34080     case SQLITE_FCNTL_POWERSAFE_OVERWRITE: {
34081       winModeBit(pFile, WINFILE_PSOW, (int*)pArg);
34082       OSTRACE(("FCNTL file=%p, rc=SQLITE_OK\n", pFile->h));
34083       return SQLITE_OK;
34084     }
34085     case SQLITE_FCNTL_VFSNAME: {
34086       *(char**)pArg = sqlite3_mprintf("win32");
34087       OSTRACE(("FCNTL file=%p, rc=SQLITE_OK\n", pFile->h));
34088       return SQLITE_OK;
34089     }
34090     case SQLITE_FCNTL_WIN32_AV_RETRY: {
34091       int *a = (int*)pArg;
34092       if( a[0]>0 ){
34093         winIoerrRetry = a[0];
34094       }else{
34095         a[0] = winIoerrRetry;
34096       }
34097       if( a[1]>0 ){
34098         winIoerrRetryDelay = a[1];
34099       }else{
34100         a[1] = winIoerrRetryDelay;
34101       }
34102       OSTRACE(("FCNTL file=%p, rc=SQLITE_OK\n", pFile->h));
34103       return SQLITE_OK;
34104     }
34105     case SQLITE_FCNTL_TEMPFILENAME: {
34106       char *zTFile = 0;
34107       int rc = winGetTempname(pFile->pVfs, &zTFile);
34108       if( rc==SQLITE_OK ){
34109         *(char**)pArg = zTFile;
34110       }
34111       OSTRACE(("FCNTL file=%p, rc=%s\n", pFile->h, sqlite3ErrName(rc)));
34112       return rc;
34113     }
34114 #if SQLITE_MAX_MMAP_SIZE>0
34115     case SQLITE_FCNTL_MMAP_SIZE: {
34116       i64 newLimit = *(i64*)pArg;
34117       int rc = SQLITE_OK;
34118       if( newLimit>sqlite3GlobalConfig.mxMmap ){
34119         newLimit = sqlite3GlobalConfig.mxMmap;
34120       }
34121       *(i64*)pArg = pFile->mmapSizeMax;
34122       if( newLimit>=0 && newLimit!=pFile->mmapSizeMax && pFile->nFetchOut==0 ){
34123         pFile->mmapSizeMax = newLimit;
34124         if( pFile->mmapSize>0 ){
34125           winUnmapfile(pFile);
34126           rc = winMapfile(pFile, -1);
34127         }
34128       }
34129       OSTRACE(("FCNTL file=%p, rc=%s\n", pFile->h, sqlite3ErrName(rc)));
34130       return rc;
34131     }
34132 #endif
34133   }
34134   OSTRACE(("FCNTL file=%p, rc=SQLITE_NOTFOUND\n", pFile->h));
34135   return SQLITE_NOTFOUND;
34136 }
34137 
34138 /*
34139 ** Return the sector size in bytes of the underlying block device for
34140 ** the specified file. This is almost always 512 bytes, but may be
34141 ** larger for some devices.
34142 **
34143 ** SQLite code assumes this function cannot fail. It also assumes that
34144 ** if two files are created in the same file-system directory (i.e.
34145 ** a database and its journal file) that the sector size will be the
34146 ** same for both.
34147 */
34148 static int winSectorSize(sqlite3_file *id){
34149   (void)id;
34150   return SQLITE_DEFAULT_SECTOR_SIZE;
34151 }
34152 
34153 /*
34154 ** Return a vector of device characteristics.
34155 */
34156 static int winDeviceCharacteristics(sqlite3_file *id){
34157   winFile *p = (winFile*)id;
34158   return SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN |
34159          ((p->ctrlFlags & WINFILE_PSOW)?SQLITE_IOCAP_POWERSAFE_OVERWRITE:0);
34160 }
34161 
34162 /* 
34163 ** Windows will only let you create file view mappings
34164 ** on allocation size granularity boundaries.
34165 ** During sqlite3_os_init() we do a GetSystemInfo()
34166 ** to get the granularity size.
34167 */
34168 SYSTEM_INFO winSysInfo;
34169 
34170 #ifndef SQLITE_OMIT_WAL
34171 
34172 /*
34173 ** Helper functions to obtain and relinquish the global mutex. The
34174 ** global mutex is used to protect the winLockInfo objects used by 
34175 ** this file, all of which may be shared by multiple threads.
34176 **
34177 ** Function winShmMutexHeld() is used to assert() that the global mutex 
34178 ** is held when required. This function is only used as part of assert() 
34179 ** statements. e.g.
34180 **
34181 **   winShmEnterMutex()
34182 **     assert( winShmMutexHeld() );
34183 **   winShmLeaveMutex()
34184 */
34185 static void winShmEnterMutex(void){
34186   sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
34187 }
34188 static void winShmLeaveMutex(void){
34189   sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
34190 }
34191 #ifdef SQLITE_DEBUG
34192 static int winShmMutexHeld(void) {
34193   return sqlite3_mutex_held(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
34194 }
34195 #endif
34196 
34197 /*
34198 ** Object used to represent a single file opened and mmapped to provide
34199 ** shared memory.  When multiple threads all reference the same
34200 ** log-summary, each thread has its own winFile object, but they all
34201 ** point to a single instance of this object.  In other words, each
34202 ** log-summary is opened only once per process.
34203 **
34204 ** winShmMutexHeld() must be true when creating or destroying
34205 ** this object or while reading or writing the following fields:
34206 **
34207 **      nRef
34208 **      pNext 
34209 **
34210 ** The following fields are read-only after the object is created:
34211 ** 
34212 **      fid
34213 **      zFilename
34214 **
34215 ** Either winShmNode.mutex must be held or winShmNode.nRef==0 and
34216 ** winShmMutexHeld() is true when reading or writing any other field
34217 ** in this structure.
34218 **
34219 */
34220 struct winShmNode {
34221   sqlite3_mutex *mutex;      /* Mutex to access this object */
34222   char *zFilename;           /* Name of the file */
34223   winFile hFile;             /* File handle from winOpen */
34224 
34225   int szRegion;              /* Size of shared-memory regions */
34226   int nRegion;               /* Size of array apRegion */
34227   struct ShmRegion {
34228     HANDLE hMap;             /* File handle from CreateFileMapping */
34229     void *pMap;
34230   } *aRegion;
34231   DWORD lastErrno;           /* The Windows errno from the last I/O error */
34232 
34233   int nRef;                  /* Number of winShm objects pointing to this */
34234   winShm *pFirst;            /* All winShm objects pointing to this */
34235   winShmNode *pNext;         /* Next in list of all winShmNode objects */
34236 #ifdef SQLITE_DEBUG
34237   u8 nextShmId;              /* Next available winShm.id value */
34238 #endif
34239 };
34240 
34241 /*
34242 ** A global array of all winShmNode objects.
34243 **
34244 ** The winShmMutexHeld() must be true while reading or writing this list.
34245 */
34246 static winShmNode *winShmNodeList = 0;
34247 
34248 /*
34249 ** Structure used internally by this VFS to record the state of an
34250 ** open shared memory connection.
34251 **
34252 ** The following fields are initialized when this object is created and
34253 ** are read-only thereafter:
34254 **
34255 **    winShm.pShmNode
34256 **    winShm.id
34257 **
34258 ** All other fields are read/write.  The winShm.pShmNode->mutex must be held
34259 ** while accessing any read/write fields.
34260 */
34261 struct winShm {
34262   winShmNode *pShmNode;      /* The underlying winShmNode object */
34263   winShm *pNext;             /* Next winShm with the same winShmNode */
34264   u8 hasMutex;               /* True if holding the winShmNode mutex */
34265   u16 sharedMask;            /* Mask of shared locks held */
34266   u16 exclMask;              /* Mask of exclusive locks held */
34267 #ifdef SQLITE_DEBUG
34268   u8 id;                     /* Id of this connection with its winShmNode */
34269 #endif
34270 };
34271 
34272 /*
34273 ** Constants used for locking
34274 */
34275 #define WIN_SHM_BASE   ((22+SQLITE_SHM_NLOCK)*4)        /* first lock byte */
34276 #define WIN_SHM_DMS    (WIN_SHM_BASE+SQLITE_SHM_NLOCK)  /* deadman switch */
34277 
34278 /*
34279 ** Apply advisory locks for all n bytes beginning at ofst.
34280 */
34281 #define _SHM_UNLCK  1
34282 #define _SHM_RDLCK  2
34283 #define _SHM_WRLCK  3
34284 static int winShmSystemLock(
34285   winShmNode *pFile,    /* Apply locks to this open shared-memory segment */
34286   int lockType,         /* _SHM_UNLCK, _SHM_RDLCK, or _SHM_WRLCK */
34287   int ofst,             /* Offset to first byte to be locked/unlocked */
34288   int nByte             /* Number of bytes to lock or unlock */
34289 ){
34290   int rc = 0;           /* Result code form Lock/UnlockFileEx() */
34291 
34292   /* Access to the winShmNode object is serialized by the caller */
34293   assert( sqlite3_mutex_held(pFile->mutex) || pFile->nRef==0 );
34294 
34295   OSTRACE(("SHM-LOCK file=%p, lock=%d, offset=%d, size=%d\n",
34296            pFile->hFile.h, lockType, ofst, nByte));
34297 
34298   /* Release/Acquire the system-level lock */
34299   if( lockType==_SHM_UNLCK ){
34300     rc = winUnlockFile(&pFile->hFile.h, ofst, 0, nByte, 0);
34301   }else{
34302     /* Initialize the locking parameters */
34303     DWORD dwFlags = LOCKFILE_FAIL_IMMEDIATELY;
34304     if( lockType == _SHM_WRLCK ) dwFlags |= LOCKFILE_EXCLUSIVE_LOCK;
34305     rc = winLockFile(&pFile->hFile.h, dwFlags, ofst, 0, nByte, 0);
34306   }
34307   
34308   if( rc!= 0 ){
34309     rc = SQLITE_OK;
34310   }else{
34311     pFile->lastErrno =  osGetLastError();
34312     rc = SQLITE_BUSY;
34313   }
34314 
34315   OSTRACE(("SHM-LOCK file=%p, func=%s, errno=%lu, rc=%s\n",
34316            pFile->hFile.h, (lockType == _SHM_UNLCK) ? "winUnlockFile" :
34317            "winLockFile", pFile->lastErrno, sqlite3ErrName(rc)));
34318 
34319   return rc;
34320 }
34321 
34322 /* Forward references to VFS methods */
34323 static int winOpen(sqlite3_vfs*,const char*,sqlite3_file*,int,int*);
34324 static int winDelete(sqlite3_vfs *,const char*,int);
34325 
34326 /*
34327 ** Purge the winShmNodeList list of all entries with winShmNode.nRef==0.
34328 **
34329 ** This is not a VFS shared-memory method; it is a utility function called
34330 ** by VFS shared-memory methods.
34331 */
34332 static void winShmPurge(sqlite3_vfs *pVfs, int deleteFlag){
34333   winShmNode **pp;
34334   winShmNode *p;
34335   assert( winShmMutexHeld() );
34336   OSTRACE(("SHM-PURGE pid=%lu, deleteFlag=%d\n",
34337            osGetCurrentProcessId(), deleteFlag));
34338   pp = &winShmNodeList;
34339   while( (p = *pp)!=0 ){
34340     if( p->nRef==0 ){
34341       int i;
34342       if( p->mutex ){ sqlite3_mutex_free(p->mutex); }
34343       for(i=0; i<p->nRegion; i++){
34344         BOOL bRc = osUnmapViewOfFile(p->aRegion[i].pMap);
34345         OSTRACE(("SHM-PURGE-UNMAP pid=%lu, region=%d, rc=%s\n",
34346                  osGetCurrentProcessId(), i, bRc ? "ok" : "failed"));
34347         UNUSED_VARIABLE_VALUE(bRc);
34348         bRc = osCloseHandle(p->aRegion[i].hMap);
34349         OSTRACE(("SHM-PURGE-CLOSE pid=%lu, region=%d, rc=%s\n",
34350                  osGetCurrentProcessId(), i, bRc ? "ok" : "failed"));
34351         UNUSED_VARIABLE_VALUE(bRc);
34352       }
34353       if( p->hFile.h!=NULL && p->hFile.h!=INVALID_HANDLE_VALUE ){
34354         SimulateIOErrorBenign(1);
34355         winClose((sqlite3_file *)&p->hFile);
34356         SimulateIOErrorBenign(0);
34357       }
34358       if( deleteFlag ){
34359         SimulateIOErrorBenign(1);
34360         sqlite3BeginBenignMalloc();
34361         winDelete(pVfs, p->zFilename, 0);
34362         sqlite3EndBenignMalloc();
34363         SimulateIOErrorBenign(0);
34364       }
34365       *pp = p->pNext;
34366       sqlite3_free(p->aRegion);
34367       sqlite3_free(p);
34368     }else{
34369       pp = &p->pNext;
34370     }
34371   }
34372 }
34373 
34374 /*
34375 ** Open the shared-memory area associated with database file pDbFd.
34376 **
34377 ** When opening a new shared-memory file, if no other instances of that
34378 ** file are currently open, in this process or in other processes, then
34379 ** the file must be truncated to zero length or have its header cleared.
34380 */
34381 static int winOpenSharedMemory(winFile *pDbFd){
34382   struct winShm *p;                  /* The connection to be opened */
34383   struct winShmNode *pShmNode = 0;   /* The underlying mmapped file */
34384   int rc;                            /* Result code */
34385   struct winShmNode *pNew;           /* Newly allocated winShmNode */
34386   int nName;                         /* Size of zName in bytes */
34387 
34388   assert( pDbFd->pShm==0 );    /* Not previously opened */
34389 
34390   /* Allocate space for the new sqlite3_shm object.  Also speculatively
34391   ** allocate space for a new winShmNode and filename.
34392   */
34393   p = sqlite3MallocZero( sizeof(*p) );
34394   if( p==0 ) return SQLITE_IOERR_NOMEM;
34395   nName = sqlite3Strlen30(pDbFd->zPath);
34396   pNew = sqlite3MallocZero( sizeof(*pShmNode) + nName + 17 );
34397   if( pNew==0 ){
34398     sqlite3_free(p);
34399     return SQLITE_IOERR_NOMEM;
34400   }
34401   pNew->zFilename = (char*)&pNew[1];
34402   sqlite3_snprintf(nName+15, pNew->zFilename, "%s-shm", pDbFd->zPath);
34403   sqlite3FileSuffix3(pDbFd->zPath, pNew->zFilename); 
34404 
34405   /* Look to see if there is an existing winShmNode that can be used.
34406   ** If no matching winShmNode currently exists, create a new one.
34407   */
34408   winShmEnterMutex();
34409   for(pShmNode = winShmNodeList; pShmNode; pShmNode=pShmNode->pNext){
34410     /* TBD need to come up with better match here.  Perhaps
34411     ** use FILE_ID_BOTH_DIR_INFO Structure.
34412     */
34413     if( sqlite3StrICmp(pShmNode->zFilename, pNew->zFilename)==0 ) break;
34414   }
34415   if( pShmNode ){
34416     sqlite3_free(pNew);
34417   }else{
34418     pShmNode = pNew;
34419     pNew = 0;
34420     ((winFile*)(&pShmNode->hFile))->h = INVALID_HANDLE_VALUE;
34421     pShmNode->pNext = winShmNodeList;
34422     winShmNodeList = pShmNode;
34423 
34424     pShmNode->mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_FAST);
34425     if( pShmNode->mutex==0 ){
34426       rc = SQLITE_IOERR_NOMEM;
34427       goto shm_open_err;
34428     }
34429 
34430     rc = winOpen(pDbFd->pVfs,
34431                  pShmNode->zFilename,             /* Name of the file (UTF-8) */
34432                  (sqlite3_file*)&pShmNode->hFile,  /* File handle here */
34433                  SQLITE_OPEN_WAL | SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE,
34434                  0);
34435     if( SQLITE_OK!=rc ){
34436       goto shm_open_err;
34437     }
34438 
34439     /* Check to see if another process is holding the dead-man switch.
34440     ** If not, truncate the file to zero length. 
34441     */
34442     if( winShmSystemLock(pShmNode, _SHM_WRLCK, WIN_SHM_DMS, 1)==SQLITE_OK ){
34443       rc = winTruncate((sqlite3_file *)&pShmNode->hFile, 0);
34444       if( rc!=SQLITE_OK ){
34445         rc = winLogError(SQLITE_IOERR_SHMOPEN, osGetLastError(),
34446                          "winOpenShm", pDbFd->zPath);
34447       }
34448     }
34449     if( rc==SQLITE_OK ){
34450       winShmSystemLock(pShmNode, _SHM_UNLCK, WIN_SHM_DMS, 1);
34451       rc = winShmSystemLock(pShmNode, _SHM_RDLCK, WIN_SHM_DMS, 1);
34452     }
34453     if( rc ) goto shm_open_err;
34454   }
34455 
34456   /* Make the new connection a child of the winShmNode */
34457   p->pShmNode = pShmNode;
34458 #ifdef SQLITE_DEBUG
34459   p->id = pShmNode->nextShmId++;
34460 #endif
34461   pShmNode->nRef++;
34462   pDbFd->pShm = p;
34463   winShmLeaveMutex();
34464 
34465   /* The reference count on pShmNode has already been incremented under
34466   ** the cover of the winShmEnterMutex() mutex and the pointer from the
34467   ** new (struct winShm) object to the pShmNode has been set. All that is
34468   ** left to do is to link the new object into the linked list starting
34469   ** at pShmNode->pFirst. This must be done while holding the pShmNode->mutex 
34470   ** mutex.
34471   */
34472   sqlite3_mutex_enter(pShmNode->mutex);
34473   p->pNext = pShmNode->pFirst;
34474   pShmNode->pFirst = p;
34475   sqlite3_mutex_leave(pShmNode->mutex);
34476   return SQLITE_OK;
34477 
34478   /* Jump here on any error */
34479 shm_open_err:
34480   winShmSystemLock(pShmNode, _SHM_UNLCK, WIN_SHM_DMS, 1);
34481   winShmPurge(pDbFd->pVfs, 0);      /* This call frees pShmNode if required */
34482   sqlite3_free(p);
34483   sqlite3_free(pNew);
34484   winShmLeaveMutex();
34485   return rc;
34486 }
34487 
34488 /*
34489 ** Close a connection to shared-memory.  Delete the underlying 
34490 ** storage if deleteFlag is true.
34491 */
34492 static int winShmUnmap(
34493   sqlite3_file *fd,          /* Database holding shared memory */
34494   int deleteFlag             /* Delete after closing if true */
34495 ){
34496   winFile *pDbFd;       /* Database holding shared-memory */
34497   winShm *p;            /* The connection to be closed */
34498   winShmNode *pShmNode; /* The underlying shared-memory file */
34499   winShm **pp;          /* For looping over sibling connections */
34500 
34501   pDbFd = (winFile*)fd;
34502   p = pDbFd->pShm;
34503   if( p==0 ) return SQLITE_OK;
34504   pShmNode = p->pShmNode;
34505 
34506   /* Remove connection p from the set of connections associated
34507   ** with pShmNode */
34508   sqlite3_mutex_enter(pShmNode->mutex);
34509   for(pp=&pShmNode->pFirst; (*pp)!=p; pp = &(*pp)->pNext){}
34510   *pp = p->pNext;
34511 
34512   /* Free the connection p */
34513   sqlite3_free(p);
34514   pDbFd->pShm = 0;
34515   sqlite3_mutex_leave(pShmNode->mutex);
34516 
34517   /* If pShmNode->nRef has reached 0, then close the underlying
34518   ** shared-memory file, too */
34519   winShmEnterMutex();
34520   assert( pShmNode->nRef>0 );
34521   pShmNode->nRef--;
34522   if( pShmNode->nRef==0 ){
34523     winShmPurge(pDbFd->pVfs, deleteFlag);
34524   }
34525   winShmLeaveMutex();
34526 
34527   return SQLITE_OK;
34528 }
34529 
34530 /*
34531 ** Change the lock state for a shared-memory segment.
34532 */
34533 static int winShmLock(
34534   sqlite3_file *fd,          /* Database file holding the shared memory */
34535   int ofst,                  /* First lock to acquire or release */
34536   int n,                     /* Number of locks to acquire or release */
34537   int flags                  /* What to do with the lock */
34538 ){
34539   winFile *pDbFd = (winFile*)fd;        /* Connection holding shared memory */
34540   winShm *p = pDbFd->pShm;              /* The shared memory being locked */
34541   winShm *pX;                           /* For looping over all siblings */
34542   winShmNode *pShmNode = p->pShmNode;
34543   int rc = SQLITE_OK;                   /* Result code */
34544   u16 mask;                             /* Mask of locks to take or release */
34545 
34546   assert( ofst>=0 && ofst+n<=SQLITE_SHM_NLOCK );
34547   assert( n>=1 );
34548   assert( flags==(SQLITE_SHM_LOCK | SQLITE_SHM_SHARED)
34549        || flags==(SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE)
34550        || flags==(SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED)
34551        || flags==(SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE) );
34552   assert( n==1 || (flags & SQLITE_SHM_EXCLUSIVE)!=0 );
34553 
34554   mask = (u16)((1U<<(ofst+n)) - (1U<<ofst));
34555   assert( n>1 || mask==(1<<ofst) );
34556   sqlite3_mutex_enter(pShmNode->mutex);
34557   if( flags & SQLITE_SHM_UNLOCK ){
34558     u16 allMask = 0; /* Mask of locks held by siblings */
34559 
34560     /* See if any siblings hold this same lock */
34561     for(pX=pShmNode->pFirst; pX; pX=pX->pNext){
34562       if( pX==p ) continue;
34563       assert( (pX->exclMask & (p->exclMask|p->sharedMask))==0 );
34564       allMask |= pX->sharedMask;
34565     }
34566 
34567     /* Unlock the system-level locks */
34568     if( (mask & allMask)==0 ){
34569       rc = winShmSystemLock(pShmNode, _SHM_UNLCK, ofst+WIN_SHM_BASE, n);
34570     }else{
34571       rc = SQLITE_OK;
34572     }
34573 
34574     /* Undo the local locks */
34575     if( rc==SQLITE_OK ){
34576       p->exclMask &= ~mask;
34577       p->sharedMask &= ~mask;
34578     } 
34579   }else if( flags & SQLITE_SHM_SHARED ){
34580     u16 allShared = 0;  /* Union of locks held by connections other than "p" */
34581 
34582     /* Find out which shared locks are already held by sibling connections.
34583     ** If any sibling already holds an exclusive lock, go ahead and return
34584     ** SQLITE_BUSY.
34585     */
34586     for(pX=pShmNode->pFirst; pX; pX=pX->pNext){
34587       if( (pX->exclMask & mask)!=0 ){
34588         rc = SQLITE_BUSY;
34589         break;
34590       }
34591       allShared |= pX->sharedMask;
34592     }
34593 
34594     /* Get shared locks at the system level, if necessary */
34595     if( rc==SQLITE_OK ){
34596       if( (allShared & mask)==0 ){
34597         rc = winShmSystemLock(pShmNode, _SHM_RDLCK, ofst+WIN_SHM_BASE, n);
34598       }else{
34599         rc = SQLITE_OK;
34600       }
34601     }
34602 
34603     /* Get the local shared locks */
34604     if( rc==SQLITE_OK ){
34605       p->sharedMask |= mask;
34606     }
34607   }else{
34608     /* Make sure no sibling connections hold locks that will block this
34609     ** lock.  If any do, return SQLITE_BUSY right away.
34610     */
34611     for(pX=pShmNode->pFirst; pX; pX=pX->pNext){
34612       if( (pX->exclMask & mask)!=0 || (pX->sharedMask & mask)!=0 ){
34613         rc = SQLITE_BUSY;
34614         break;
34615       }
34616     }
34617   
34618     /* Get the exclusive locks at the system level.  Then if successful
34619     ** also mark the local connection as being locked.
34620     */
34621     if( rc==SQLITE_OK ){
34622       rc = winShmSystemLock(pShmNode, _SHM_WRLCK, ofst+WIN_SHM_BASE, n);
34623       if( rc==SQLITE_OK ){
34624         assert( (p->sharedMask & mask)==0 );
34625         p->exclMask |= mask;
34626       }
34627     }
34628   }
34629   sqlite3_mutex_leave(pShmNode->mutex);
34630   OSTRACE(("SHM-LOCK pid=%lu, id=%d, sharedMask=%03x, exclMask=%03x, rc=%s\n",
34631            osGetCurrentProcessId(), p->id, p->sharedMask, p->exclMask,
34632            sqlite3ErrName(rc)));
34633   return rc;
34634 }
34635 
34636 /*
34637 ** Implement a memory barrier or memory fence on shared memory.  
34638 **
34639 ** All loads and stores begun before the barrier must complete before
34640 ** any load or store begun after the barrier.
34641 */
34642 static void winShmBarrier(
34643   sqlite3_file *fd          /* Database holding the shared memory */
34644 ){
34645   UNUSED_PARAMETER(fd);
34646   /* MemoryBarrier(); // does not work -- do not know why not */
34647   winShmEnterMutex();
34648   winShmLeaveMutex();
34649 }
34650 
34651 /*
34652 ** This function is called to obtain a pointer to region iRegion of the 
34653 ** shared-memory associated with the database file fd. Shared-memory regions 
34654 ** are numbered starting from zero. Each shared-memory region is szRegion 
34655 ** bytes in size.
34656 **
34657 ** If an error occurs, an error code is returned and *pp is set to NULL.
34658 **
34659 ** Otherwise, if the isWrite parameter is 0 and the requested shared-memory
34660 ** region has not been allocated (by any client, including one running in a
34661 ** separate process), then *pp is set to NULL and SQLITE_OK returned. If 
34662 ** isWrite is non-zero and the requested shared-memory region has not yet 
34663 ** been allocated, it is allocated by this function.
34664 **
34665 ** If the shared-memory region has already been allocated or is allocated by
34666 ** this call as described above, then it is mapped into this processes 
34667 ** address space (if it is not already), *pp is set to point to the mapped 
34668 ** memory and SQLITE_OK returned.
34669 */
34670 static int winShmMap(
34671   sqlite3_file *fd,               /* Handle open on database file */
34672   int iRegion,                    /* Region to retrieve */
34673   int szRegion,                   /* Size of regions */
34674   int isWrite,                    /* True to extend file if necessary */
34675   void volatile **pp              /* OUT: Mapped memory */
34676 ){
34677   winFile *pDbFd = (winFile*)fd;
34678   winShm *p = pDbFd->pShm;
34679   winShmNode *pShmNode;
34680   int rc = SQLITE_OK;
34681 
34682   if( !p ){
34683     rc = winOpenSharedMemory(pDbFd);
34684     if( rc!=SQLITE_OK ) return rc;
34685     p = pDbFd->pShm;
34686   }
34687   pShmNode = p->pShmNode;
34688 
34689   sqlite3_mutex_enter(pShmNode->mutex);
34690   assert( szRegion==pShmNode->szRegion || pShmNode->nRegion==0 );
34691 
34692   if( pShmNode->nRegion<=iRegion ){
34693     struct ShmRegion *apNew;           /* New aRegion[] array */
34694     int nByte = (iRegion+1)*szRegion;  /* Minimum required file size */
34695     sqlite3_int64 sz;                  /* Current size of wal-index file */
34696 
34697     pShmNode->szRegion = szRegion;
34698 
34699     /* The requested region is not mapped into this processes address space.
34700     ** Check to see if it has been allocated (i.e. if the wal-index file is
34701     ** large enough to contain the requested region).
34702     */
34703     rc = winFileSize((sqlite3_file *)&pShmNode->hFile, &sz);
34704     if( rc!=SQLITE_OK ){
34705       rc = winLogError(SQLITE_IOERR_SHMSIZE, osGetLastError(),
34706                        "winShmMap1", pDbFd->zPath);
34707       goto shmpage_out;
34708     }
34709 
34710     if( sz<nByte ){
34711       /* The requested memory region does not exist. If isWrite is set to
34712       ** zero, exit early. *pp will be set to NULL and SQLITE_OK returned.
34713       **
34714       ** Alternatively, if isWrite is non-zero, use ftruncate() to allocate
34715       ** the requested memory region.
34716       */
34717       if( !isWrite ) goto shmpage_out;
34718       rc = winTruncate((sqlite3_file *)&pShmNode->hFile, nByte);
34719       if( rc!=SQLITE_OK ){
34720         rc = winLogError(SQLITE_IOERR_SHMSIZE, osGetLastError(),
34721                          "winShmMap2", pDbFd->zPath);
34722         goto shmpage_out;
34723       }
34724     }
34725 
34726     /* Map the requested memory region into this processes address space. */
34727     apNew = (struct ShmRegion *)sqlite3_realloc(
34728         pShmNode->aRegion, (iRegion+1)*sizeof(apNew[0])
34729     );
34730     if( !apNew ){
34731       rc = SQLITE_IOERR_NOMEM;
34732       goto shmpage_out;
34733     }
34734     pShmNode->aRegion = apNew;
34735 
34736     while( pShmNode->nRegion<=iRegion ){
34737       HANDLE hMap = NULL;         /* file-mapping handle */
34738       void *pMap = 0;             /* Mapped memory region */
34739      
34740 #if SQLITE_OS_WINRT
34741       hMap = osCreateFileMappingFromApp(pShmNode->hFile.h,
34742           NULL, PAGE_READWRITE, nByte, NULL
34743       );
34744 #elif defined(SQLITE_WIN32_HAS_WIDE)
34745       hMap = osCreateFileMappingW(pShmNode->hFile.h, 
34746           NULL, PAGE_READWRITE, 0, nByte, NULL
34747       );
34748 #elif defined(SQLITE_WIN32_HAS_ANSI)
34749       hMap = osCreateFileMappingA(pShmNode->hFile.h, 
34750           NULL, PAGE_READWRITE, 0, nByte, NULL
34751       );
34752 #endif
34753       OSTRACE(("SHM-MAP-CREATE pid=%lu, region=%d, size=%d, rc=%s\n",
34754                osGetCurrentProcessId(), pShmNode->nRegion, nByte,
34755                hMap ? "ok" : "failed"));
34756       if( hMap ){
34757         int iOffset = pShmNode->nRegion*szRegion;
34758         int iOffsetShift = iOffset % winSysInfo.dwAllocationGranularity;
34759 #if SQLITE_OS_WINRT
34760         pMap = osMapViewOfFileFromApp(hMap, FILE_MAP_WRITE | FILE_MAP_READ,
34761             iOffset - iOffsetShift, szRegion + iOffsetShift
34762         );
34763 #else
34764         pMap = osMapViewOfFile(hMap, FILE_MAP_WRITE | FILE_MAP_READ,
34765             0, iOffset - iOffsetShift, szRegion + iOffsetShift
34766         );
34767 #endif
34768         OSTRACE(("SHM-MAP-MAP pid=%lu, region=%d, offset=%d, size=%d, rc=%s\n",
34769                  osGetCurrentProcessId(), pShmNode->nRegion, iOffset,
34770                  szRegion, pMap ? "ok" : "failed"));
34771       }
34772       if( !pMap ){
34773         pShmNode->lastErrno = osGetLastError();
34774         rc = winLogError(SQLITE_IOERR_SHMMAP, pShmNode->lastErrno,
34775                          "winShmMap3", pDbFd->zPath);
34776         if( hMap ) osCloseHandle(hMap);
34777         goto shmpage_out;
34778       }
34779 
34780       pShmNode->aRegion[pShmNode->nRegion].pMap = pMap;
34781       pShmNode->aRegion[pShmNode->nRegion].hMap = hMap;
34782       pShmNode->nRegion++;
34783     }
34784   }
34785 
34786 shmpage_out:
34787   if( pShmNode->nRegion>iRegion ){
34788     int iOffset = iRegion*szRegion;
34789     int iOffsetShift = iOffset % winSysInfo.dwAllocationGranularity;
34790     char *p = (char *)pShmNode->aRegion[iRegion].pMap;
34791     *pp = (void *)&p[iOffsetShift];
34792   }else{
34793     *pp = 0;
34794   }
34795   sqlite3_mutex_leave(pShmNode->mutex);
34796   return rc;
34797 }
34798 
34799 #else
34800 # define winShmMap     0
34801 # define winShmLock    0
34802 # define winShmBarrier 0
34803 # define winShmUnmap   0
34804 #endif /* #ifndef SQLITE_OMIT_WAL */
34805 
34806 /*
34807 ** Cleans up the mapped region of the specified file, if any.
34808 */
34809 #if SQLITE_MAX_MMAP_SIZE>0
34810 static int winUnmapfile(winFile *pFile){
34811   assert( pFile!=0 );
34812   OSTRACE(("UNMAP-FILE pid=%lu, pFile=%p, hMap=%p, pMapRegion=%p, "
34813            "mmapSize=%lld, mmapSizeActual=%lld, mmapSizeMax=%lld\n",
34814            osGetCurrentProcessId(), pFile, pFile->hMap, pFile->pMapRegion,
34815            pFile->mmapSize, pFile->mmapSizeActual, pFile->mmapSizeMax));
34816   if( pFile->pMapRegion ){
34817     if( !osUnmapViewOfFile(pFile->pMapRegion) ){
34818       pFile->lastErrno = osGetLastError();
34819       OSTRACE(("UNMAP-FILE pid=%lu, pFile=%p, pMapRegion=%p, "
34820                "rc=SQLITE_IOERR_MMAP\n", osGetCurrentProcessId(), pFile,
34821                pFile->pMapRegion));
34822       return winLogError(SQLITE_IOERR_MMAP, pFile->lastErrno,
34823                          "winUnmapfile1", pFile->zPath);
34824     }
34825     pFile->pMapRegion = 0;
34826     pFile->mmapSize = 0;
34827     pFile->mmapSizeActual = 0;
34828   }
34829   if( pFile->hMap!=NULL ){
34830     if( !osCloseHandle(pFile->hMap) ){
34831       pFile->lastErrno = osGetLastError();
34832       OSTRACE(("UNMAP-FILE pid=%lu, pFile=%p, hMap=%p, rc=SQLITE_IOERR_MMAP\n",
34833                osGetCurrentProcessId(), pFile, pFile->hMap));
34834       return winLogError(SQLITE_IOERR_MMAP, pFile->lastErrno,
34835                          "winUnmapfile2", pFile->zPath);
34836     }
34837     pFile->hMap = NULL;
34838   }
34839   OSTRACE(("UNMAP-FILE pid=%lu, pFile=%p, rc=SQLITE_OK\n",
34840            osGetCurrentProcessId(), pFile));
34841   return SQLITE_OK;
34842 }
34843 
34844 /*
34845 ** Memory map or remap the file opened by file-descriptor pFd (if the file
34846 ** is already mapped, the existing mapping is replaced by the new). Or, if 
34847 ** there already exists a mapping for this file, and there are still 
34848 ** outstanding xFetch() references to it, this function is a no-op.
34849 **
34850 ** If parameter nByte is non-negative, then it is the requested size of 
34851 ** the mapping to create. Otherwise, if nByte is less than zero, then the 
34852 ** requested size is the size of the file on disk. The actual size of the
34853 ** created mapping is either the requested size or the value configured 
34854 ** using SQLITE_FCNTL_MMAP_SIZE, whichever is smaller.
34855 **
34856 ** SQLITE_OK is returned if no error occurs (even if the mapping is not
34857 ** recreated as a result of outstanding references) or an SQLite error
34858 ** code otherwise.
34859 */
34860 static int winMapfile(winFile *pFd, sqlite3_int64 nByte){
34861   sqlite3_int64 nMap = nByte;
34862   int rc;
34863 
34864   assert( nMap>=0 || pFd->nFetchOut==0 );
34865   OSTRACE(("MAP-FILE pid=%lu, pFile=%p, size=%lld\n",
34866            osGetCurrentProcessId(), pFd, nByte));
34867 
34868   if( pFd->nFetchOut>0 ) return SQLITE_OK;
34869 
34870   if( nMap<0 ){
34871     rc = winFileSize((sqlite3_file*)pFd, &nMap);
34872     if( rc ){
34873       OSTRACE(("MAP-FILE pid=%lu, pFile=%p, rc=SQLITE_IOERR_FSTAT\n",
34874                osGetCurrentProcessId(), pFd));
34875       return SQLITE_IOERR_FSTAT;
34876     }
34877   }
34878   if( nMap>pFd->mmapSizeMax ){
34879     nMap = pFd->mmapSizeMax;
34880   }
34881   nMap &= ~(sqlite3_int64)(winSysInfo.dwPageSize - 1);
34882  
34883   if( nMap==0 && pFd->mmapSize>0 ){
34884     winUnmapfile(pFd);
34885   }
34886   if( nMap!=pFd->mmapSize ){
34887     void *pNew = 0;
34888     DWORD protect = PAGE_READONLY;
34889     DWORD flags = FILE_MAP_READ;
34890 
34891     winUnmapfile(pFd);
34892     if( (pFd->ctrlFlags & WINFILE_RDONLY)==0 ){
34893       protect = PAGE_READWRITE;
34894       flags |= FILE_MAP_WRITE;
34895     }
34896 #if SQLITE_OS_WINRT
34897     pFd->hMap = osCreateFileMappingFromApp(pFd->h, NULL, protect, nMap, NULL);
34898 #elif defined(SQLITE_WIN32_HAS_WIDE)
34899     pFd->hMap = osCreateFileMappingW(pFd->h, NULL, protect,
34900                                 (DWORD)((nMap>>32) & 0xffffffff),
34901                                 (DWORD)(nMap & 0xffffffff), NULL);
34902 #elif defined(SQLITE_WIN32_HAS_ANSI)
34903     pFd->hMap = osCreateFileMappingA(pFd->h, NULL, protect,
34904                                 (DWORD)((nMap>>32) & 0xffffffff),
34905                                 (DWORD)(nMap & 0xffffffff), NULL);
34906 #endif
34907     if( pFd->hMap==NULL ){
34908       pFd->lastErrno = osGetLastError();
34909       rc = winLogError(SQLITE_IOERR_MMAP, pFd->lastErrno,
34910                        "winMapfile1", pFd->zPath);
34911       /* Log the error, but continue normal operation using xRead/xWrite */
34912       OSTRACE(("MAP-FILE-CREATE pid=%lu, pFile=%p, rc=%s\n",
34913                osGetCurrentProcessId(), pFd, sqlite3ErrName(rc)));
34914       return SQLITE_OK;
34915     }
34916     assert( (nMap % winSysInfo.dwPageSize)==0 );
34917     assert( sizeof(SIZE_T)==sizeof(sqlite3_int64) || nMap<=0xffffffff );
34918 #if SQLITE_OS_WINRT
34919     pNew = osMapViewOfFileFromApp(pFd->hMap, flags, 0, (SIZE_T)nMap);
34920 #else
34921     pNew = osMapViewOfFile(pFd->hMap, flags, 0, 0, (SIZE_T)nMap);
34922 #endif
34923     if( pNew==NULL ){
34924       osCloseHandle(pFd->hMap);
34925       pFd->hMap = NULL;
34926       pFd->lastErrno = osGetLastError();
34927       rc = winLogError(SQLITE_IOERR_MMAP, pFd->lastErrno,
34928                        "winMapfile2", pFd->zPath);
34929       /* Log the error, but continue normal operation using xRead/xWrite */
34930       OSTRACE(("MAP-FILE-MAP pid=%lu, pFile=%p, rc=%s\n",
34931                osGetCurrentProcessId(), pFd, sqlite3ErrName(rc)));
34932       return SQLITE_OK;
34933     }
34934     pFd->pMapRegion = pNew;
34935     pFd->mmapSize = nMap;
34936     pFd->mmapSizeActual = nMap;
34937   }
34938 
34939   OSTRACE(("MAP-FILE pid=%lu, pFile=%p, rc=SQLITE_OK\n",
34940            osGetCurrentProcessId(), pFd));
34941   return SQLITE_OK;
34942 }
34943 #endif /* SQLITE_MAX_MMAP_SIZE>0 */
34944 
34945 /*
34946 ** If possible, return a pointer to a mapping of file fd starting at offset
34947 ** iOff. The mapping must be valid for at least nAmt bytes.
34948 **
34949 ** If such a pointer can be obtained, store it in *pp and return SQLITE_OK.
34950 ** Or, if one cannot but no error occurs, set *pp to 0 and return SQLITE_OK.
34951 ** Finally, if an error does occur, return an SQLite error code. The final
34952 ** value of *pp is undefined in this case.
34953 **
34954 ** If this function does return a pointer, the caller must eventually 
34955 ** release the reference by calling winUnfetch().
34956 */
34957 static int winFetch(sqlite3_file *fd, i64 iOff, int nAmt, void **pp){
34958 #if SQLITE_MAX_MMAP_SIZE>0
34959   winFile *pFd = (winFile*)fd;   /* The underlying database file */
34960 #endif
34961   *pp = 0;
34962 
34963   OSTRACE(("FETCH pid=%lu, pFile=%p, offset=%lld, amount=%d, pp=%p\n",
34964            osGetCurrentProcessId(), fd, iOff, nAmt, pp));
34965 
34966 #if SQLITE_MAX_MMAP_SIZE>0
34967   if( pFd->mmapSizeMax>0 ){
34968     if( pFd->pMapRegion==0 ){
34969       int rc = winMapfile(pFd, -1);
34970       if( rc!=SQLITE_OK ){
34971         OSTRACE(("FETCH pid=%lu, pFile=%p, rc=%s\n",
34972                  osGetCurrentProcessId(), pFd, sqlite3ErrName(rc)));
34973         return rc;
34974       }
34975     }
34976     if( pFd->mmapSize >= iOff+nAmt ){
34977       *pp = &((u8 *)pFd->pMapRegion)[iOff];
34978       pFd->nFetchOut++;
34979     }
34980   }
34981 #endif
34982 
34983   OSTRACE(("FETCH pid=%lu, pFile=%p, pp=%p, *pp=%p, rc=SQLITE_OK\n",
34984            osGetCurrentProcessId(), fd, pp, *pp));
34985   return SQLITE_OK;
34986 }
34987 
34988 /*
34989 ** If the third argument is non-NULL, then this function releases a 
34990 ** reference obtained by an earlier call to winFetch(). The second
34991 ** argument passed to this function must be the same as the corresponding
34992 ** argument that was passed to the winFetch() invocation. 
34993 **
34994 ** Or, if the third argument is NULL, then this function is being called 
34995 ** to inform the VFS layer that, according to POSIX, any existing mapping 
34996 ** may now be invalid and should be unmapped.
34997 */
34998 static int winUnfetch(sqlite3_file *fd, i64 iOff, void *p){
34999 #if SQLITE_MAX_MMAP_SIZE>0
35000   winFile *pFd = (winFile*)fd;   /* The underlying database file */
35001 
35002   /* If p==0 (unmap the entire file) then there must be no outstanding 
35003   ** xFetch references. Or, if p!=0 (meaning it is an xFetch reference),
35004   ** then there must be at least one outstanding.  */
35005   assert( (p==0)==(pFd->nFetchOut==0) );
35006 
35007   /* If p!=0, it must match the iOff value. */
35008   assert( p==0 || p==&((u8 *)pFd->pMapRegion)[iOff] );
35009 
35010   OSTRACE(("UNFETCH pid=%lu, pFile=%p, offset=%lld, p=%p\n",
35011            osGetCurrentProcessId(), pFd, iOff, p));
35012 
35013   if( p ){
35014     pFd->nFetchOut--;
35015   }else{
35016     /* FIXME:  If Windows truly always prevents truncating or deleting a
35017     ** file while a mapping is held, then the following winUnmapfile() call
35018     ** is unnecessary can can be omitted - potentially improving
35019     ** performance.  */
35020     winUnmapfile(pFd);
35021   }
35022 
35023   assert( pFd->nFetchOut>=0 );
35024 #endif
35025 
35026   OSTRACE(("UNFETCH pid=%lu, pFile=%p, rc=SQLITE_OK\n",
35027            osGetCurrentProcessId(), fd));
35028   return SQLITE_OK;
35029 }
35030 
35031 /*
35032 ** Here ends the implementation of all sqlite3_file methods.
35033 **
35034 ********************** End sqlite3_file Methods *******************************
35035 ******************************************************************************/
35036 
35037 /*
35038 ** This vector defines all the methods that can operate on an
35039 ** sqlite3_file for win32.
35040 */
35041 static const sqlite3_io_methods winIoMethod = {
35042   3,                              /* iVersion */
35043   winClose,                       /* xClose */
35044   winRead,                        /* xRead */
35045   winWrite,                       /* xWrite */
35046   winTruncate,                    /* xTruncate */
35047   winSync,                        /* xSync */
35048   winFileSize,                    /* xFileSize */
35049   winLock,                        /* xLock */
35050   winUnlock,                      /* xUnlock */
35051   winCheckReservedLock,           /* xCheckReservedLock */
35052   winFileControl,                 /* xFileControl */
35053   winSectorSize,                  /* xSectorSize */
35054   winDeviceCharacteristics,       /* xDeviceCharacteristics */
35055   winShmMap,                      /* xShmMap */
35056   winShmLock,                     /* xShmLock */
35057   winShmBarrier,                  /* xShmBarrier */
35058   winShmUnmap,                    /* xShmUnmap */
35059   winFetch,                       /* xFetch */
35060   winUnfetch                      /* xUnfetch */
35061 };
35062 
35063 /****************************************************************************
35064 **************************** sqlite3_vfs methods ****************************
35065 **
35066 ** This division contains the implementation of methods on the
35067 ** sqlite3_vfs object.
35068 */
35069 
35070 #if defined(__CYGWIN__)
35071 /*
35072 ** Convert a filename from whatever the underlying operating system
35073 ** supports for filenames into UTF-8.  Space to hold the result is
35074 ** obtained from malloc and must be freed by the calling function.
35075 */
35076 static char *winConvertToUtf8Filename(const void *zFilename){
35077   char *zConverted = 0;
35078   if( osIsNT() ){
35079     zConverted = winUnicodeToUtf8(zFilename);
35080   }
35081 #ifdef SQLITE_WIN32_HAS_ANSI
35082   else{
35083     zConverted = sqlite3_win32_mbcs_to_utf8(zFilename);
35084   }
35085 #endif
35086   /* caller will handle out of memory */
35087   return zConverted;
35088 }
35089 #endif
35090 
35091 /*
35092 ** Convert a UTF-8 filename into whatever form the underlying
35093 ** operating system wants filenames in.  Space to hold the result
35094 ** is obtained from malloc and must be freed by the calling
35095 ** function.
35096 */
35097 static void *winConvertFromUtf8Filename(const char *zFilename){
35098   void *zConverted = 0;
35099   if( osIsNT() ){
35100     zConverted = winUtf8ToUnicode(zFilename);
35101   }
35102 #ifdef SQLITE_WIN32_HAS_ANSI
35103   else{
35104     zConverted = sqlite3_win32_utf8_to_mbcs(zFilename);
35105   }
35106 #endif
35107   /* caller will handle out of memory */
35108   return zConverted;
35109 }
35110 
35111 /*
35112 ** This function returns non-zero if the specified UTF-8 string buffer
35113 ** ends with a directory separator character or one was successfully
35114 ** added to it.
35115 */
35116 static int winMakeEndInDirSep(int nBuf, char *zBuf){
35117   if( zBuf ){
35118     int nLen = sqlite3Strlen30(zBuf);
35119     if( nLen>0 ){
35120       if( winIsDirSep(zBuf[nLen-1]) ){
35121         return 1;
35122       }else if( nLen+1<nBuf ){
35123         zBuf[nLen] = winGetDirSep();
35124         zBuf[nLen+1] = '\0';
35125         return 1;
35126       }
35127     }
35128   }
35129   return 0;
35130 }
35131 
35132 /*
35133 ** Create a temporary file name and store the resulting pointer into pzBuf.
35134 ** The pointer returned in pzBuf must be freed via sqlite3_free().
35135 */
35136 static int winGetTempname(sqlite3_vfs *pVfs, char **pzBuf){
35137   static char zChars[] =
35138     "abcdefghijklmnopqrstuvwxyz"
35139     "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
35140     "0123456789";
35141   size_t i, j;
35142   int nPre = sqlite3Strlen30(SQLITE_TEMP_FILE_PREFIX);
35143   int nMax, nBuf, nDir, nLen;
35144   char *zBuf;
35145 
35146   /* It's odd to simulate an io-error here, but really this is just
35147   ** using the io-error infrastructure to test that SQLite handles this
35148   ** function failing. 
35149   */
35150   SimulateIOError( return SQLITE_IOERR );
35151 
35152   /* Allocate a temporary buffer to store the fully qualified file
35153   ** name for the temporary file.  If this fails, we cannot continue.
35154   */
35155   nMax = pVfs->mxPathname; nBuf = nMax + 2;
35156   zBuf = sqlite3MallocZero( nBuf );
35157   if( !zBuf ){
35158     OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_NOMEM\n"));
35159     return SQLITE_IOERR_NOMEM;
35160   }
35161 
35162   /* Figure out the effective temporary directory.  First, check if one
35163   ** has been explicitly set by the application; otherwise, use the one
35164   ** configured by the operating system.
35165   */
35166   nDir = nMax - (nPre + 15);
35167   assert( nDir>0 );
35168   if( sqlite3_temp_directory ){
35169     int nDirLen = sqlite3Strlen30(sqlite3_temp_directory);
35170     if( nDirLen>0 ){
35171       if( !winIsDirSep(sqlite3_temp_directory[nDirLen-1]) ){
35172         nDirLen++;
35173       }
35174       if( nDirLen>nDir ){
35175         sqlite3_free(zBuf);
35176         OSTRACE(("TEMP-FILENAME rc=SQLITE_ERROR\n"));
35177         return winLogError(SQLITE_ERROR, 0, "winGetTempname1", 0);
35178       }
35179       sqlite3_snprintf(nMax, zBuf, "%s", sqlite3_temp_directory);
35180     }
35181   }
35182 #if defined(__CYGWIN__)
35183   else{
35184     static const char *azDirs[] = {
35185        0, /* getenv("SQLITE_TMPDIR") */
35186        0, /* getenv("TMPDIR") */
35187        0, /* getenv("TMP") */
35188        0, /* getenv("TEMP") */
35189        0, /* getenv("USERPROFILE") */
35190        "/var/tmp",
35191        "/usr/tmp",
35192        "/tmp",
35193        ".",
35194        0        /* List terminator */
35195     };
35196     unsigned int i;
35197     const char *zDir = 0;
35198 
35199     if( !azDirs[0] ) azDirs[0] = getenv("SQLITE_TMPDIR");
35200     if( !azDirs[1] ) azDirs[1] = getenv("TMPDIR");
35201     if( !azDirs[2] ) azDirs[2] = getenv("TMP");
35202     if( !azDirs[3] ) azDirs[3] = getenv("TEMP");
35203     if( !azDirs[4] ) azDirs[4] = getenv("USERPROFILE");
35204     for(i=0; i<sizeof(azDirs)/sizeof(azDirs[0]); zDir=azDirs[i++]){
35205       void *zConverted;
35206       if( zDir==0 ) continue;
35207       /* If the path starts with a drive letter followed by the colon
35208       ** character, assume it is already a native Win32 path; otherwise,
35209       ** it must be converted to a native Win32 path via the Cygwin API
35210       ** prior to using it.
35211       */
35212       if( winIsDriveLetterAndColon(zDir) ){
35213         zConverted = winConvertFromUtf8Filename(zDir);
35214         if( !zConverted ){
35215           sqlite3_free(zBuf);
35216           OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_NOMEM\n"));
35217           return SQLITE_IOERR_NOMEM;
35218         }
35219         if( winIsDir(zConverted) ){
35220           sqlite3_snprintf(nMax, zBuf, "%s", zDir);
35221           sqlite3_free(zConverted);
35222           break;
35223         }
35224         sqlite3_free(zConverted);
35225       }else{
35226         zConverted = sqlite3MallocZero( nMax+1 );
35227         if( !zConverted ){
35228           sqlite3_free(zBuf);
35229           OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_NOMEM\n"));
35230           return SQLITE_IOERR_NOMEM;
35231         }
35232         if( cygwin_conv_path(
35233                 osIsNT() ? CCP_POSIX_TO_WIN_W : CCP_POSIX_TO_WIN_A, zDir,
35234                 zConverted, nMax+1)<0 ){
35235           sqlite3_free(zConverted);
35236           sqlite3_free(zBuf);
35237           OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_CONVPATH\n"));
35238           return winLogError(SQLITE_IOERR_CONVPATH, (DWORD)errno,
35239                              "winGetTempname2", zDir);
35240         }
35241         if( winIsDir(zConverted) ){
35242           /* At this point, we know the candidate directory exists and should
35243           ** be used.  However, we may need to convert the string containing
35244           ** its name into UTF-8 (i.e. if it is UTF-16 right now).
35245           */
35246           char *zUtf8 = winConvertToUtf8Filename(zConverted);
35247           if( !zUtf8 ){
35248             sqlite3_free(zConverted);
35249             sqlite3_free(zBuf);
35250             OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_NOMEM\n"));
35251             return SQLITE_IOERR_NOMEM;
35252           }
35253           sqlite3_snprintf(nMax, zBuf, "%s", zUtf8);
35254           sqlite3_free(zUtf8);
35255           sqlite3_free(zConverted);
35256           break;
35257         }
35258         sqlite3_free(zConverted);
35259       }
35260     }
35261   }
35262 #elif !SQLITE_OS_WINRT && !defined(__CYGWIN__)
35263   else if( osIsNT() ){
35264     char *zMulti;
35265     LPWSTR zWidePath = sqlite3MallocZero( nMax*sizeof(WCHAR) );
35266     if( !zWidePath ){
35267       sqlite3_free(zBuf);
35268       OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_NOMEM\n"));
35269       return SQLITE_IOERR_NOMEM;
35270     }
35271     if( osGetTempPathW(nMax, zWidePath)==0 ){
35272       sqlite3_free(zWidePath);
35273       sqlite3_free(zBuf);
35274       OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_GETTEMPPATH\n"));
35275       return winLogError(SQLITE_IOERR_GETTEMPPATH, osGetLastError(),
35276                          "winGetTempname2", 0);
35277     }
35278     zMulti = winUnicodeToUtf8(zWidePath);
35279     if( zMulti ){
35280       sqlite3_snprintf(nMax, zBuf, "%s", zMulti);
35281       sqlite3_free(zMulti);
35282       sqlite3_free(zWidePath);
35283     }else{
35284       sqlite3_free(zWidePath);
35285       sqlite3_free(zBuf);
35286       OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_NOMEM\n"));
35287       return SQLITE_IOERR_NOMEM;
35288     }
35289   }
35290 #ifdef SQLITE_WIN32_HAS_ANSI
35291   else{
35292     char *zUtf8;
35293     char *zMbcsPath = sqlite3MallocZero( nMax );
35294     if( !zMbcsPath ){
35295       sqlite3_free(zBuf);
35296       OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_NOMEM\n"));
35297       return SQLITE_IOERR_NOMEM;
35298     }
35299     if( osGetTempPathA(nMax, zMbcsPath)==0 ){
35300       sqlite3_free(zBuf);
35301       OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_GETTEMPPATH\n"));
35302       return winLogError(SQLITE_IOERR_GETTEMPPATH, osGetLastError(),
35303                          "winGetTempname3", 0);
35304     }
35305     zUtf8 = sqlite3_win32_mbcs_to_utf8(zMbcsPath);
35306     if( zUtf8 ){
35307       sqlite3_snprintf(nMax, zBuf, "%s", zUtf8);
35308       sqlite3_free(zUtf8);
35309     }else{
35310       sqlite3_free(zBuf);
35311       OSTRACE(("TEMP-FILENAME rc=SQLITE_IOERR_NOMEM\n"));
35312       return SQLITE_IOERR_NOMEM;
35313     }
35314   }
35315 #endif /* SQLITE_WIN32_HAS_ANSI */
35316 #endif /* !SQLITE_OS_WINRT */
35317 
35318   /*
35319   ** Check to make sure the temporary directory ends with an appropriate
35320   ** separator.  If it does not and there is not enough space left to add
35321   ** one, fail.
35322   */
35323   if( !winMakeEndInDirSep(nDir+1, zBuf) ){
35324     sqlite3_free(zBuf);
35325     OSTRACE(("TEMP-FILENAME rc=SQLITE_ERROR\n"));
35326     return winLogError(SQLITE_ERROR, 0, "winGetTempname4", 0);
35327   }
35328 
35329   /*
35330   ** Check that the output buffer is large enough for the temporary file 
35331   ** name in the following format:
35332   **
35333   **   "<temporary_directory>/etilqs_XXXXXXXXXXXXXXX\0\0"
35334   **
35335   ** If not, return SQLITE_ERROR.  The number 17 is used here in order to
35336   ** account for the space used by the 15 character random suffix and the
35337   ** two trailing NUL characters.  The final directory separator character
35338   ** has already added if it was not already present.
35339   */
35340   nLen = sqlite3Strlen30(zBuf);
35341   if( (nLen + nPre + 17) > nBuf ){
35342     sqlite3_free(zBuf);
35343     OSTRACE(("TEMP-FILENAME rc=SQLITE_ERROR\n"));
35344     return winLogError(SQLITE_ERROR, 0, "winGetTempname5", 0);
35345   }
35346 
35347   sqlite3_snprintf(nBuf-16-nLen, zBuf+nLen, SQLITE_TEMP_FILE_PREFIX);
35348 
35349   j = sqlite3Strlen30(zBuf);
35350   sqlite3_randomness(15, &zBuf[j]);
35351   for(i=0; i<15; i++, j++){
35352     zBuf[j] = (char)zChars[ ((unsigned char)zBuf[j])%(sizeof(zChars)-1) ];
35353   }
35354   zBuf[j] = 0;
35355   zBuf[j+1] = 0;
35356   *pzBuf = zBuf;
35357 
35358   OSTRACE(("TEMP-FILENAME name=%s, rc=SQLITE_OK\n", zBuf));
35359   return SQLITE_OK;
35360 }
35361 
35362 /*
35363 ** Return TRUE if the named file is really a directory.  Return false if
35364 ** it is something other than a directory, or if there is any kind of memory
35365 ** allocation failure.
35366 */
35367 static int winIsDir(const void *zConverted){
35368   DWORD attr;
35369   int rc = 0;
35370   DWORD lastErrno;
35371 
35372   if( osIsNT() ){
35373     int cnt = 0;
35374     WIN32_FILE_ATTRIBUTE_DATA sAttrData;
35375     memset(&sAttrData, 0, sizeof(sAttrData));
35376     while( !(rc = osGetFileAttributesExW((LPCWSTR)zConverted,
35377                              GetFileExInfoStandard,
35378                              &sAttrData)) && winRetryIoerr(&cnt, &lastErrno) ){}
35379     if( !rc ){
35380       return 0; /* Invalid name? */
35381     }
35382     attr = sAttrData.dwFileAttributes;
35383 #if SQLITE_OS_WINCE==0
35384   }else{
35385     attr = osGetFileAttributesA((char*)zConverted);
35386 #endif
35387   }
35388   return (attr!=INVALID_FILE_ATTRIBUTES) && (attr&FILE_ATTRIBUTE_DIRECTORY);
35389 }
35390 
35391 /*
35392 ** Open a file.
35393 */
35394 static int winOpen(
35395   sqlite3_vfs *pVfs,        /* Used to get maximum path name length */
35396   const char *zName,        /* Name of the file (UTF-8) */
35397   sqlite3_file *id,         /* Write the SQLite file handle here */
35398   int flags,                /* Open mode flags */
35399   int *pOutFlags            /* Status return flags */
35400 ){
35401   HANDLE h;
35402   DWORD lastErrno = 0;
35403   DWORD dwDesiredAccess;
35404   DWORD dwShareMode;
35405   DWORD dwCreationDisposition;
35406   DWORD dwFlagsAndAttributes = 0;
35407 #if SQLITE_OS_WINCE
35408   int isTemp = 0;
35409 #endif
35410   winFile *pFile = (winFile*)id;
35411   void *zConverted;              /* Filename in OS encoding */
35412   const char *zUtf8Name = zName; /* Filename in UTF-8 encoding */
35413   int cnt = 0;
35414 
35415   /* If argument zPath is a NULL pointer, this function is required to open
35416   ** a temporary file. Use this buffer to store the file name in.
35417   */
35418   char *zTmpname = 0; /* For temporary filename, if necessary. */
35419 
35420   int rc = SQLITE_OK;            /* Function Return Code */
35421 #if !defined(NDEBUG) || SQLITE_OS_WINCE
35422   int eType = flags&0xFFFFFF00;  /* Type of file to open */
35423 #endif
35424 
35425   int isExclusive  = (flags & SQLITE_OPEN_EXCLUSIVE);
35426   int isDelete     = (flags & SQLITE_OPEN_DELETEONCLOSE);
35427   int isCreate     = (flags & SQLITE_OPEN_CREATE);
35428   int isReadonly   = (flags & SQLITE_OPEN_READONLY);
35429   int isReadWrite  = (flags & SQLITE_OPEN_READWRITE);
35430 
35431 #ifndef NDEBUG
35432   int isOpenJournal = (isCreate && (
35433         eType==SQLITE_OPEN_MASTER_JOURNAL 
35434      || eType==SQLITE_OPEN_MAIN_JOURNAL 
35435      || eType==SQLITE_OPEN_WAL
35436   ));
35437 #endif
35438 
35439   OSTRACE(("OPEN name=%s, pFile=%p, flags=%x, pOutFlags=%p\n",
35440            zUtf8Name, id, flags, pOutFlags));
35441 
35442   /* Check the following statements are true: 
35443   **
35444   **   (a) Exactly one of the READWRITE and READONLY flags must be set, and 
35445   **   (b) if CREATE is set, then READWRITE must also be set, and
35446   **   (c) if EXCLUSIVE is set, then CREATE must also be set.
35447   **   (d) if DELETEONCLOSE is set, then CREATE must also be set.
35448   */
35449   assert((isReadonly==0 || isReadWrite==0) && (isReadWrite || isReadonly));
35450   assert(isCreate==0 || isReadWrite);
35451   assert(isExclusive==0 || isCreate);
35452   assert(isDelete==0 || isCreate);
35453 
35454   /* The main DB, main journal, WAL file and master journal are never 
35455   ** automatically deleted. Nor are they ever temporary files.  */
35456   assert( (!isDelete && zName) || eType!=SQLITE_OPEN_MAIN_DB );
35457   assert( (!isDelete && zName) || eType!=SQLITE_OPEN_MAIN_JOURNAL );
35458   assert( (!isDelete && zName) || eType!=SQLITE_OPEN_MASTER_JOURNAL );
35459   assert( (!isDelete && zName) || eType!=SQLITE_OPEN_WAL );
35460 
35461   /* Assert that the upper layer has set one of the "file-type" flags. */
35462   assert( eType==SQLITE_OPEN_MAIN_DB      || eType==SQLITE_OPEN_TEMP_DB 
35463        || eType==SQLITE_OPEN_MAIN_JOURNAL || eType==SQLITE_OPEN_TEMP_JOURNAL 
35464        || eType==SQLITE_OPEN_SUBJOURNAL   || eType==SQLITE_OPEN_MASTER_JOURNAL 
35465        || eType==SQLITE_OPEN_TRANSIENT_DB || eType==SQLITE_OPEN_WAL
35466   );
35467 
35468   assert( pFile!=0 );
35469   memset(pFile, 0, sizeof(winFile));
35470   pFile->h = INVALID_HANDLE_VALUE;
35471 
35472 #if SQLITE_OS_WINRT
35473   if( !zUtf8Name && !sqlite3_temp_directory ){
35474     sqlite3_log(SQLITE_ERROR,
35475         "sqlite3_temp_directory variable should be set for WinRT");
35476   }
35477 #endif
35478 
35479   /* If the second argument to this function is NULL, generate a 
35480   ** temporary file name to use 
35481   */
35482   if( !zUtf8Name ){
35483     assert( isDelete && !isOpenJournal );
35484     rc = winGetTempname(pVfs, &zTmpname);
35485     if( rc!=SQLITE_OK ){
35486       OSTRACE(("OPEN name=%s, rc=%s", zUtf8Name, sqlite3ErrName(rc)));
35487       return rc;
35488     }
35489     zUtf8Name = zTmpname;
35490   }
35491 
35492   /* Database filenames are double-zero terminated if they are not
35493   ** URIs with parameters.  Hence, they can always be passed into
35494   ** sqlite3_uri_parameter().
35495   */
35496   assert( (eType!=SQLITE_OPEN_MAIN_DB) || (flags & SQLITE_OPEN_URI) ||
35497        zUtf8Name[sqlite3Strlen30(zUtf8Name)+1]==0 );
35498 
35499   /* Convert the filename to the system encoding. */
35500   zConverted = winConvertFromUtf8Filename(zUtf8Name);
35501   if( zConverted==0 ){
35502     sqlite3_free(zTmpname);
35503     OSTRACE(("OPEN name=%s, rc=SQLITE_IOERR_NOMEM", zUtf8Name));
35504     return SQLITE_IOERR_NOMEM;
35505   }
35506 
35507   if( winIsDir(zConverted) ){
35508     sqlite3_free(zConverted);
35509     sqlite3_free(zTmpname);
35510     OSTRACE(("OPEN name=%s, rc=SQLITE_CANTOPEN_ISDIR", zUtf8Name));
35511     return SQLITE_CANTOPEN_ISDIR;
35512   }
35513 
35514   if( isReadWrite ){
35515     dwDesiredAccess = GENERIC_READ | GENERIC_WRITE;
35516   }else{
35517     dwDesiredAccess = GENERIC_READ;
35518   }
35519 
35520   /* SQLITE_OPEN_EXCLUSIVE is used to make sure that a new file is 
35521   ** created. SQLite doesn't use it to indicate "exclusive access" 
35522   ** as it is usually understood.
35523   */
35524   if( isExclusive ){
35525     /* Creates a new file, only if it does not already exist. */
35526     /* If the file exists, it fails. */
35527     dwCreationDisposition = CREATE_NEW;
35528   }else if( isCreate ){
35529     /* Open existing file, or create if it doesn't exist */
35530     dwCreationDisposition = OPEN_ALWAYS;
35531   }else{
35532     /* Opens a file, only if it exists. */
35533     dwCreationDisposition = OPEN_EXISTING;
35534   }
35535 
35536   dwShareMode = FILE_SHARE_READ | FILE_SHARE_WRITE;
35537 
35538   if( isDelete ){
35539 #if SQLITE_OS_WINCE
35540     dwFlagsAndAttributes = FILE_ATTRIBUTE_HIDDEN;
35541     isTemp = 1;
35542 #else
35543     dwFlagsAndAttributes = FILE_ATTRIBUTE_TEMPORARY
35544                                | FILE_ATTRIBUTE_HIDDEN
35545                                | FILE_FLAG_DELETE_ON_CLOSE;
35546 #endif
35547   }else{
35548     dwFlagsAndAttributes = FILE_ATTRIBUTE_NORMAL;
35549   }
35550   /* Reports from the internet are that performance is always
35551   ** better if FILE_FLAG_RANDOM_ACCESS is used.  Ticket #2699. */
35552 #if SQLITE_OS_WINCE
35553   dwFlagsAndAttributes |= FILE_FLAG_RANDOM_ACCESS;
35554 #endif
35555 
35556   if( osIsNT() ){
35557 #if SQLITE_OS_WINRT
35558     CREATEFILE2_EXTENDED_PARAMETERS extendedParameters;
35559     extendedParameters.dwSize = sizeof(CREATEFILE2_EXTENDED_PARAMETERS);
35560     extendedParameters.dwFileAttributes =
35561             dwFlagsAndAttributes & FILE_ATTRIBUTE_MASK;
35562     extendedParameters.dwFileFlags = dwFlagsAndAttributes & FILE_FLAG_MASK;
35563     extendedParameters.dwSecurityQosFlags = SECURITY_ANONYMOUS;
35564     extendedParameters.lpSecurityAttributes = NULL;
35565     extendedParameters.hTemplateFile = NULL;
35566     while( (h = osCreateFile2((LPCWSTR)zConverted,
35567                               dwDesiredAccess,
35568                               dwShareMode,
35569                               dwCreationDisposition,
35570                               &extendedParameters))==INVALID_HANDLE_VALUE &&
35571                               winRetryIoerr(&cnt, &lastErrno) ){
35572                /* Noop */
35573     }
35574 #else
35575     while( (h = osCreateFileW((LPCWSTR)zConverted,
35576                               dwDesiredAccess,
35577                               dwShareMode, NULL,
35578                               dwCreationDisposition,
35579                               dwFlagsAndAttributes,
35580                               NULL))==INVALID_HANDLE_VALUE &&
35581                               winRetryIoerr(&cnt, &lastErrno) ){
35582                /* Noop */
35583     }
35584 #endif
35585   }
35586 #ifdef SQLITE_WIN32_HAS_ANSI
35587   else{
35588     while( (h = osCreateFileA((LPCSTR)zConverted,
35589                               dwDesiredAccess,
35590                               dwShareMode, NULL,
35591                               dwCreationDisposition,
35592                               dwFlagsAndAttributes,
35593                               NULL))==INVALID_HANDLE_VALUE &&
35594                               winRetryIoerr(&cnt, &lastErrno) ){
35595                /* Noop */
35596     }
35597   }
35598 #endif
35599   winLogIoerr(cnt);
35600 
35601   OSTRACE(("OPEN file=%p, name=%s, access=%lx, rc=%s\n", h, zUtf8Name,
35602            dwDesiredAccess, (h==INVALID_HANDLE_VALUE) ? "failed" : "ok"));
35603 
35604   if( h==INVALID_HANDLE_VALUE ){
35605     pFile->lastErrno = lastErrno;
35606     winLogError(SQLITE_CANTOPEN, pFile->lastErrno, "winOpen", zUtf8Name);
35607     sqlite3_free(zConverted);
35608     sqlite3_free(zTmpname);
35609     if( isReadWrite && !isExclusive ){
35610       return winOpen(pVfs, zName, id, 
35611          ((flags|SQLITE_OPEN_READONLY) &
35612                      ~(SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE)),
35613          pOutFlags);
35614     }else{
35615       return SQLITE_CANTOPEN_BKPT;
35616     }
35617   }
35618 
35619   if( pOutFlags ){
35620     if( isReadWrite ){
35621       *pOutFlags = SQLITE_OPEN_READWRITE;
35622     }else{
35623       *pOutFlags = SQLITE_OPEN_READONLY;
35624     }
35625   }
35626 
35627   OSTRACE(("OPEN file=%p, name=%s, access=%lx, pOutFlags=%p, *pOutFlags=%d, "
35628            "rc=%s\n", h, zUtf8Name, dwDesiredAccess, pOutFlags, pOutFlags ?
35629            *pOutFlags : 0, (h==INVALID_HANDLE_VALUE) ? "failed" : "ok"));
35630 
35631 #if SQLITE_OS_WINCE
35632   if( isReadWrite && eType==SQLITE_OPEN_MAIN_DB
35633        && (rc = winceCreateLock(zName, pFile))!=SQLITE_OK
35634   ){
35635     osCloseHandle(h);
35636     sqlite3_free(zConverted);
35637     sqlite3_free(zTmpname);
35638     OSTRACE(("OPEN-CE-LOCK name=%s, rc=%s\n", zName, sqlite3ErrName(rc)));
35639     return rc;
35640   }
35641   if( isTemp ){
35642     pFile->zDeleteOnClose = zConverted;
35643   }else
35644 #endif
35645   {
35646     sqlite3_free(zConverted);
35647   }
35648 
35649   sqlite3_free(zTmpname);
35650   pFile->pMethod = &winIoMethod;
35651   pFile->pVfs = pVfs;
35652   pFile->h = h;
35653   if( isReadonly ){
35654     pFile->ctrlFlags |= WINFILE_RDONLY;
35655   }
35656   if( sqlite3_uri_boolean(zName, "psow", SQLITE_POWERSAFE_OVERWRITE) ){
35657     pFile->ctrlFlags |= WINFILE_PSOW;
35658   }
35659   pFile->lastErrno = NO_ERROR;
35660   pFile->zPath = zName;
35661 #if SQLITE_MAX_MMAP_SIZE>0
35662   pFile->hMap = NULL;
35663   pFile->pMapRegion = 0;
35664   pFile->mmapSize = 0;
35665   pFile->mmapSizeActual = 0;
35666   pFile->mmapSizeMax = sqlite3GlobalConfig.szMmap;
35667 #endif
35668 
35669   OpenCounter(+1);
35670   return rc;
35671 }
35672 
35673 /*
35674 ** Delete the named file.
35675 **
35676 ** Note that Windows does not allow a file to be deleted if some other
35677 ** process has it open.  Sometimes a virus scanner or indexing program
35678 ** will open a journal file shortly after it is created in order to do
35679 ** whatever it does.  While this other process is holding the
35680 ** file open, we will be unable to delete it.  To work around this
35681 ** problem, we delay 100 milliseconds and try to delete again.  Up
35682 ** to MX_DELETION_ATTEMPTs deletion attempts are run before giving
35683 ** up and returning an error.
35684 */
35685 static int winDelete(
35686   sqlite3_vfs *pVfs,          /* Not used on win32 */
35687   const char *zFilename,      /* Name of file to delete */
35688   int syncDir                 /* Not used on win32 */
35689 ){
35690   int cnt = 0;
35691   int rc;
35692   DWORD attr;
35693   DWORD lastErrno = 0;
35694   void *zConverted;
35695   UNUSED_PARAMETER(pVfs);
35696   UNUSED_PARAMETER(syncDir);
35697 
35698   SimulateIOError(return SQLITE_IOERR_DELETE);
35699   OSTRACE(("DELETE name=%s, syncDir=%d\n", zFilename, syncDir));
35700 
35701   zConverted = winConvertFromUtf8Filename(zFilename);
35702   if( zConverted==0 ){
35703     OSTRACE(("DELETE name=%s, rc=SQLITE_IOERR_NOMEM\n", zFilename));
35704     return SQLITE_IOERR_NOMEM;
35705   }
35706   if( osIsNT() ){
35707     do {
35708 #if SQLITE_OS_WINRT
35709       WIN32_FILE_ATTRIBUTE_DATA sAttrData;
35710       memset(&sAttrData, 0, sizeof(sAttrData));
35711       if ( osGetFileAttributesExW(zConverted, GetFileExInfoStandard,
35712                                   &sAttrData) ){
35713         attr = sAttrData.dwFileAttributes;
35714       }else{
35715         lastErrno = osGetLastError();
35716         if( lastErrno==ERROR_FILE_NOT_FOUND
35717          || lastErrno==ERROR_PATH_NOT_FOUND ){
35718           rc = SQLITE_IOERR_DELETE_NOENT; /* Already gone? */
35719         }else{
35720           rc = SQLITE_ERROR;
35721         }
35722         break;
35723       }
35724 #else
35725       attr = osGetFileAttributesW(zConverted);
35726 #endif
35727       if ( attr==INVALID_FILE_ATTRIBUTES ){
35728         lastErrno = osGetLastError();
35729         if( lastErrno==ERROR_FILE_NOT_FOUND
35730          || lastErrno==ERROR_PATH_NOT_FOUND ){
35731           rc = SQLITE_IOERR_DELETE_NOENT; /* Already gone? */
35732         }else{
35733           rc = SQLITE_ERROR;
35734         }
35735         break;
35736       }
35737       if ( attr&FILE_ATTRIBUTE_DIRECTORY ){
35738         rc = SQLITE_ERROR; /* Files only. */
35739         break;
35740       }
35741       if ( osDeleteFileW(zConverted) ){
35742         rc = SQLITE_OK; /* Deleted OK. */
35743         break;
35744       }
35745       if ( !winRetryIoerr(&cnt, &lastErrno) ){
35746         rc = SQLITE_ERROR; /* No more retries. */
35747         break;
35748       }
35749     } while(1);
35750   }
35751 #ifdef SQLITE_WIN32_HAS_ANSI
35752   else{
35753     do {
35754       attr = osGetFileAttributesA(zConverted);
35755       if ( attr==INVALID_FILE_ATTRIBUTES ){
35756         lastErrno = osGetLastError();
35757         if( lastErrno==ERROR_FILE_NOT_FOUND
35758          || lastErrno==ERROR_PATH_NOT_FOUND ){
35759           rc = SQLITE_IOERR_DELETE_NOENT; /* Already gone? */
35760         }else{
35761           rc = SQLITE_ERROR;
35762         }
35763         break;
35764       }
35765       if ( attr&FILE_ATTRIBUTE_DIRECTORY ){
35766         rc = SQLITE_ERROR; /* Files only. */
35767         break;
35768       }
35769       if ( osDeleteFileA(zConverted) ){
35770         rc = SQLITE_OK; /* Deleted OK. */
35771         break;
35772       }
35773       if ( !winRetryIoerr(&cnt, &lastErrno) ){
35774         rc = SQLITE_ERROR; /* No more retries. */
35775         break;
35776       }
35777     } while(1);
35778   }
35779 #endif
35780   if( rc && rc!=SQLITE_IOERR_DELETE_NOENT ){
35781     rc = winLogError(SQLITE_IOERR_DELETE, lastErrno, "winDelete", zFilename);
35782   }else{
35783     winLogIoerr(cnt);
35784   }
35785   sqlite3_free(zConverted);
35786   OSTRACE(("DELETE name=%s, rc=%s\n", zFilename, sqlite3ErrName(rc)));
35787   return rc;
35788 }
35789 
35790 /*
35791 ** Check the existence and status of a file.
35792 */
35793 static int winAccess(
35794   sqlite3_vfs *pVfs,         /* Not used on win32 */
35795   const char *zFilename,     /* Name of file to check */
35796   int flags,                 /* Type of test to make on this file */
35797   int *pResOut               /* OUT: Result */
35798 ){
35799   DWORD attr;
35800   int rc = 0;
35801   DWORD lastErrno = 0;
35802   void *zConverted;
35803   UNUSED_PARAMETER(pVfs);
35804 
35805   SimulateIOError( return SQLITE_IOERR_ACCESS; );
35806   OSTRACE(("ACCESS name=%s, flags=%x, pResOut=%p\n",
35807            zFilename, flags, pResOut));
35808 
35809   zConverted = winConvertFromUtf8Filename(zFilename);
35810   if( zConverted==0 ){
35811     OSTRACE(("ACCESS name=%s, rc=SQLITE_IOERR_NOMEM\n", zFilename));
35812     return SQLITE_IOERR_NOMEM;
35813   }
35814   if( osIsNT() ){
35815     int cnt = 0;
35816     WIN32_FILE_ATTRIBUTE_DATA sAttrData;
35817     memset(&sAttrData, 0, sizeof(sAttrData));
35818     while( !(rc = osGetFileAttributesExW((LPCWSTR)zConverted,
35819                              GetFileExInfoStandard, 
35820                              &sAttrData)) && winRetryIoerr(&cnt, &lastErrno) ){}
35821     if( rc ){
35822       /* For an SQLITE_ACCESS_EXISTS query, treat a zero-length file
35823       ** as if it does not exist.
35824       */
35825       if(    flags==SQLITE_ACCESS_EXISTS
35826           && sAttrData.nFileSizeHigh==0 
35827           && sAttrData.nFileSizeLow==0 ){
35828         attr = INVALID_FILE_ATTRIBUTES;
35829       }else{
35830         attr = sAttrData.dwFileAttributes;
35831       }
35832     }else{
35833       winLogIoerr(cnt);
35834       if( lastErrno!=ERROR_FILE_NOT_FOUND && lastErrno!=ERROR_PATH_NOT_FOUND ){
35835         sqlite3_free(zConverted);
35836         return winLogError(SQLITE_IOERR_ACCESS, lastErrno, "winAccess",
35837                            zFilename);
35838       }else{
35839         attr = INVALID_FILE_ATTRIBUTES;
35840       }
35841     }
35842   }
35843 #ifdef SQLITE_WIN32_HAS_ANSI
35844   else{
35845     attr = osGetFileAttributesA((char*)zConverted);
35846   }
35847 #endif
35848   sqlite3_free(zConverted);
35849   switch( flags ){
35850     case SQLITE_ACCESS_READ:
35851     case SQLITE_ACCESS_EXISTS:
35852       rc = attr!=INVALID_FILE_ATTRIBUTES;
35853       break;
35854     case SQLITE_ACCESS_READWRITE:
35855       rc = attr!=INVALID_FILE_ATTRIBUTES &&
35856              (attr & FILE_ATTRIBUTE_READONLY)==0;
35857       break;
35858     default:
35859       assert(!"Invalid flags argument");
35860   }
35861   *pResOut = rc;
35862   OSTRACE(("ACCESS name=%s, pResOut=%p, *pResOut=%d, rc=SQLITE_OK\n",
35863            zFilename, pResOut, *pResOut));
35864   return SQLITE_OK;
35865 }
35866 
35867 /*
35868 ** Returns non-zero if the specified path name starts with a drive letter
35869 ** followed by a colon character.
35870 */
35871 static BOOL winIsDriveLetterAndColon(
35872   const char *zPathname
35873 ){
35874   return ( sqlite3Isalpha(zPathname[0]) && zPathname[1]==':' );
35875 }
35876 
35877 /*
35878 ** Returns non-zero if the specified path name should be used verbatim.  If
35879 ** non-zero is returned from this function, the calling function must simply
35880 ** use the provided path name verbatim -OR- resolve it into a full path name
35881 ** using the GetFullPathName Win32 API function (if available).
35882 */
35883 static BOOL winIsVerbatimPathname(
35884   const char *zPathname
35885 ){
35886   /*
35887   ** If the path name starts with a forward slash or a backslash, it is either
35888   ** a legal UNC name, a volume relative path, or an absolute path name in the
35889   ** "Unix" format on Windows.  There is no easy way to differentiate between
35890   ** the final two cases; therefore, we return the safer return value of TRUE
35891   ** so that callers of this function will simply use it verbatim.
35892   */
35893   if ( winIsDirSep(zPathname[0]) ){
35894     return TRUE;
35895   }
35896 
35897   /*
35898   ** If the path name starts with a letter and a colon it is either a volume
35899   ** relative path or an absolute path.  Callers of this function must not
35900   ** attempt to treat it as a relative path name (i.e. they should simply use
35901   ** it verbatim).
35902   */
35903   if ( winIsDriveLetterAndColon(zPathname) ){
35904     return TRUE;
35905   }
35906 
35907   /*
35908   ** If we get to this point, the path name should almost certainly be a purely
35909   ** relative one (i.e. not a UNC name, not absolute, and not volume relative).
35910   */
35911   return FALSE;
35912 }
35913 
35914 /*
35915 ** Turn a relative pathname into a full pathname.  Write the full
35916 ** pathname into zOut[].  zOut[] will be at least pVfs->mxPathname
35917 ** bytes in size.
35918 */
35919 static int winFullPathname(
35920   sqlite3_vfs *pVfs,            /* Pointer to vfs object */
35921   const char *zRelative,        /* Possibly relative input path */
35922   int nFull,                    /* Size of output buffer in bytes */
35923   char *zFull                   /* Output buffer */
35924 ){
35925   
35926 #if defined(__CYGWIN__)
35927   SimulateIOError( return SQLITE_ERROR );
35928   UNUSED_PARAMETER(nFull);
35929   assert( nFull>=pVfs->mxPathname );
35930   if ( sqlite3_data_directory && !winIsVerbatimPathname(zRelative) ){
35931     /*
35932     ** NOTE: We are dealing with a relative path name and the data
35933     **       directory has been set.  Therefore, use it as the basis
35934     **       for converting the relative path name to an absolute
35935     **       one by prepending the data directory and a slash.
35936     */
35937     char *zOut = sqlite3MallocZero( pVfs->mxPathname+1 );
35938     if( !zOut ){
35939       return SQLITE_IOERR_NOMEM;
35940     }
35941     if( cygwin_conv_path(
35942             (osIsNT() ? CCP_POSIX_TO_WIN_W : CCP_POSIX_TO_WIN_A) |
35943             CCP_RELATIVE, zRelative, zOut, pVfs->mxPathname+1)<0 ){
35944       sqlite3_free(zOut);
35945       return winLogError(SQLITE_CANTOPEN_CONVPATH, (DWORD)errno,
35946                          "winFullPathname1", zRelative);
35947     }else{
35948       char *zUtf8 = winConvertToUtf8Filename(zOut);
35949       if( !zUtf8 ){
35950         sqlite3_free(zOut);
35951         return SQLITE_IOERR_NOMEM;
35952       }
35953       sqlite3_snprintf(MIN(nFull, pVfs->mxPathname), zFull, "%s%c%s",
35954                        sqlite3_data_directory, winGetDirSep(), zUtf8);
35955       sqlite3_free(zUtf8);
35956       sqlite3_free(zOut);
35957     }
35958   }else{
35959     char *zOut = sqlite3MallocZero( pVfs->mxPathname+1 );
35960     if( !zOut ){
35961       return SQLITE_IOERR_NOMEM;
35962     }
35963     if( cygwin_conv_path(
35964             (osIsNT() ? CCP_POSIX_TO_WIN_W : CCP_POSIX_TO_WIN_A),
35965             zRelative, zOut, pVfs->mxPathname+1)<0 ){
35966       sqlite3_free(zOut);
35967       return winLogError(SQLITE_CANTOPEN_CONVPATH, (DWORD)errno,
35968                          "winFullPathname2", zRelative);
35969     }else{
35970       char *zUtf8 = winConvertToUtf8Filename(zOut);
35971       if( !zUtf8 ){
35972         sqlite3_free(zOut);
35973         return SQLITE_IOERR_NOMEM;
35974       }
35975       sqlite3_snprintf(MIN(nFull, pVfs->mxPathname), zFull, "%s", zUtf8);
35976       sqlite3_free(zUtf8);
35977       sqlite3_free(zOut);
35978     }
35979   }
35980   return SQLITE_OK;
35981 #endif
35982 
35983 #if (SQLITE_OS_WINCE || SQLITE_OS_WINRT) && !defined(__CYGWIN__)
35984   SimulateIOError( return SQLITE_ERROR );
35985   /* WinCE has no concept of a relative pathname, or so I am told. */
35986   /* WinRT has no way to convert a relative path to an absolute one. */
35987   if ( sqlite3_data_directory && !winIsVerbatimPathname(zRelative) ){
35988     /*
35989     ** NOTE: We are dealing with a relative path name and the data
35990     **       directory has been set.  Therefore, use it as the basis
35991     **       for converting the relative path name to an absolute
35992     **       one by prepending the data directory and a backslash.
35993     */
35994     sqlite3_snprintf(MIN(nFull, pVfs->mxPathname), zFull, "%s%c%s",
35995                      sqlite3_data_directory, winGetDirSep(), zRelative);
35996   }else{
35997     sqlite3_snprintf(MIN(nFull, pVfs->mxPathname), zFull, "%s", zRelative);
35998   }
35999   return SQLITE_OK;
36000 #endif
36001 
36002 #if !SQLITE_OS_WINCE && !SQLITE_OS_WINRT && !defined(__CYGWIN__)
36003   DWORD nByte;
36004   void *zConverted;
36005   char *zOut;
36006 
36007   /* If this path name begins with "/X:", where "X" is any alphabetic
36008   ** character, discard the initial "/" from the pathname.
36009   */
36010   if( zRelative[0]=='/' && winIsDriveLetterAndColon(zRelative+1) ){
36011     zRelative++;
36012   }
36013 
36014   /* It's odd to simulate an io-error here, but really this is just
36015   ** using the io-error infrastructure to test that SQLite handles this
36016   ** function failing. This function could fail if, for example, the
36017   ** current working directory has been unlinked.
36018   */
36019   SimulateIOError( return SQLITE_ERROR );
36020   if ( sqlite3_data_directory && !winIsVerbatimPathname(zRelative) ){
36021     /*
36022     ** NOTE: We are dealing with a relative path name and the data
36023     **       directory has been set.  Therefore, use it as the basis
36024     **       for converting the relative path name to an absolute
36025     **       one by prepending the data directory and a backslash.
36026     */
36027     sqlite3_snprintf(MIN(nFull, pVfs->mxPathname), zFull, "%s%c%s",
36028                      sqlite3_data_directory, winGetDirSep(), zRelative);
36029     return SQLITE_OK;
36030   }
36031   zConverted = winConvertFromUtf8Filename(zRelative);
36032   if( zConverted==0 ){
36033     return SQLITE_IOERR_NOMEM;
36034   }
36035   if( osIsNT() ){
36036     LPWSTR zTemp;
36037     nByte = osGetFullPathNameW((LPCWSTR)zConverted, 0, 0, 0);
36038     if( nByte==0 ){
36039       sqlite3_free(zConverted);
36040       return winLogError(SQLITE_CANTOPEN_FULLPATH, osGetLastError(),
36041                          "winFullPathname1", zRelative);
36042     }
36043     nByte += 3;
36044     zTemp = sqlite3MallocZero( nByte*sizeof(zTemp[0]) );
36045     if( zTemp==0 ){
36046       sqlite3_free(zConverted);
36047       return SQLITE_IOERR_NOMEM;
36048     }
36049     nByte = osGetFullPathNameW((LPCWSTR)zConverted, nByte, zTemp, 0);
36050     if( nByte==0 ){
36051       sqlite3_free(zConverted);
36052       sqlite3_free(zTemp);
36053       return winLogError(SQLITE_CANTOPEN_FULLPATH, osGetLastError(),
36054                          "winFullPathname2", zRelative);
36055     }
36056     sqlite3_free(zConverted);
36057     zOut = winUnicodeToUtf8(zTemp);
36058     sqlite3_free(zTemp);
36059   }
36060 #ifdef SQLITE_WIN32_HAS_ANSI
36061   else{
36062     char *zTemp;
36063     nByte = osGetFullPathNameA((char*)zConverted, 0, 0, 0);
36064     if( nByte==0 ){
36065       sqlite3_free(zConverted);
36066       return winLogError(SQLITE_CANTOPEN_FULLPATH, osGetLastError(),
36067                          "winFullPathname3", zRelative);
36068     }
36069     nByte += 3;
36070     zTemp = sqlite3MallocZero( nByte*sizeof(zTemp[0]) );
36071     if( zTemp==0 ){
36072       sqlite3_free(zConverted);
36073       return SQLITE_IOERR_NOMEM;
36074     }
36075     nByte = osGetFullPathNameA((char*)zConverted, nByte, zTemp, 0);
36076     if( nByte==0 ){
36077       sqlite3_free(zConverted);
36078       sqlite3_free(zTemp);
36079       return winLogError(SQLITE_CANTOPEN_FULLPATH, osGetLastError(),
36080                          "winFullPathname4", zRelative);
36081     }
36082     sqlite3_free(zConverted);
36083     zOut = sqlite3_win32_mbcs_to_utf8(zTemp);
36084     sqlite3_free(zTemp);
36085   }
36086 #endif
36087   if( zOut ){
36088     sqlite3_snprintf(MIN(nFull, pVfs->mxPathname), zFull, "%s", zOut);
36089     sqlite3_free(zOut);
36090     return SQLITE_OK;
36091   }else{
36092     return SQLITE_IOERR_NOMEM;
36093   }
36094 #endif
36095 }
36096 
36097 #ifndef SQLITE_OMIT_LOAD_EXTENSION
36098 /*
36099 ** Interfaces for opening a shared library, finding entry points
36100 ** within the shared library, and closing the shared library.
36101 */
36102 /*
36103 ** Interfaces for opening a shared library, finding entry points
36104 ** within the shared library, and closing the shared library.
36105 */
36106 static void *winDlOpen(sqlite3_vfs *pVfs, const char *zFilename){
36107   HANDLE h;
36108   void *zConverted = winConvertFromUtf8Filename(zFilename);
36109   UNUSED_PARAMETER(pVfs);
36110   if( zConverted==0 ){
36111     return 0;
36112   }
36113   if( osIsNT() ){
36114 #if SQLITE_OS_WINRT
36115     h = osLoadPackagedLibrary((LPCWSTR)zConverted, 0);
36116 #else
36117     h = osLoadLibraryW((LPCWSTR)zConverted);
36118 #endif
36119   }
36120 #ifdef SQLITE_WIN32_HAS_ANSI
36121   else{
36122     h = osLoadLibraryA((char*)zConverted);
36123   }
36124 #endif
36125   sqlite3_free(zConverted);
36126   return (void*)h;
36127 }
36128 static void winDlError(sqlite3_vfs *pVfs, int nBuf, char *zBufOut){
36129   UNUSED_PARAMETER(pVfs);
36130   winGetLastErrorMsg(osGetLastError(), nBuf, zBufOut);
36131 }
36132 static void (*winDlSym(sqlite3_vfs *pVfs,void *pH,const char *zSym))(void){
36133   UNUSED_PARAMETER(pVfs);
36134   return (void(*)(void))osGetProcAddressA((HANDLE)pH, zSym);
36135 }
36136 static void winDlClose(sqlite3_vfs *pVfs, void *pHandle){
36137   UNUSED_PARAMETER(pVfs);
36138   osFreeLibrary((HANDLE)pHandle);
36139 }
36140 #else /* if SQLITE_OMIT_LOAD_EXTENSION is defined: */
36141   #define winDlOpen  0
36142   #define winDlError 0
36143   #define winDlSym   0
36144   #define winDlClose 0
36145 #endif
36146 
36147 
36148 /*
36149 ** Write up to nBuf bytes of randomness into zBuf.
36150 */
36151 static int winRandomness(sqlite3_vfs *pVfs, int nBuf, char *zBuf){
36152   int n = 0;
36153   UNUSED_PARAMETER(pVfs);
36154 #if defined(SQLITE_TEST)
36155   n = nBuf;
36156   memset(zBuf, 0, nBuf);
36157 #else
36158   if( sizeof(SYSTEMTIME)<=nBuf-n ){
36159     SYSTEMTIME x;
36160     osGetSystemTime(&x);
36161     memcpy(&zBuf[n], &x, sizeof(x));
36162     n += sizeof(x);
36163   }
36164   if( sizeof(DWORD)<=nBuf-n ){
36165     DWORD pid = osGetCurrentProcessId();
36166     memcpy(&zBuf[n], &pid, sizeof(pid));
36167     n += sizeof(pid);
36168   }
36169 #if SQLITE_OS_WINRT
36170   if( sizeof(ULONGLONG)<=nBuf-n ){
36171     ULONGLONG cnt = osGetTickCount64();
36172     memcpy(&zBuf[n], &cnt, sizeof(cnt));
36173     n += sizeof(cnt);
36174   }
36175 #else
36176   if( sizeof(DWORD)<=nBuf-n ){
36177     DWORD cnt = osGetTickCount();
36178     memcpy(&zBuf[n], &cnt, sizeof(cnt));
36179     n += sizeof(cnt);
36180   }
36181 #endif
36182   if( sizeof(LARGE_INTEGER)<=nBuf-n ){
36183     LARGE_INTEGER i;
36184     osQueryPerformanceCounter(&i);
36185     memcpy(&zBuf[n], &i, sizeof(i));
36186     n += sizeof(i);
36187   }
36188 #endif
36189   return n;
36190 }
36191 
36192 
36193 /*
36194 ** Sleep for a little while.  Return the amount of time slept.
36195 */
36196 static int winSleep(sqlite3_vfs *pVfs, int microsec){
36197   sqlite3_win32_sleep((microsec+999)/1000);
36198   UNUSED_PARAMETER(pVfs);
36199   return ((microsec+999)/1000)*1000;
36200 }
36201 
36202 /*
36203 ** The following variable, if set to a non-zero value, is interpreted as
36204 ** the number of seconds since 1970 and is used to set the result of
36205 ** sqlite3OsCurrentTime() during testing.
36206 */
36207 #ifdef SQLITE_TEST
36208 SQLITE_API int sqlite3_current_time = 0;  /* Fake system time in seconds since 1970. */
36209 #endif
36210 
36211 /*
36212 ** Find the current time (in Universal Coordinated Time).  Write into *piNow
36213 ** the current time and date as a Julian Day number times 86_400_000.  In
36214 ** other words, write into *piNow the number of milliseconds since the Julian
36215 ** epoch of noon in Greenwich on November 24, 4714 B.C according to the
36216 ** proleptic Gregorian calendar.
36217 **
36218 ** On success, return SQLITE_OK.  Return SQLITE_ERROR if the time and date 
36219 ** cannot be found.
36220 */
36221 static int winCurrentTimeInt64(sqlite3_vfs *pVfs, sqlite3_int64 *piNow){
36222   /* FILETIME structure is a 64-bit value representing the number of 
36223      100-nanosecond intervals since January 1, 1601 (= JD 2305813.5). 
36224   */
36225   FILETIME ft;
36226   static const sqlite3_int64 winFiletimeEpoch = 23058135*(sqlite3_int64)8640000;
36227 #ifdef SQLITE_TEST
36228   static const sqlite3_int64 unixEpoch = 24405875*(sqlite3_int64)8640000;
36229 #endif
36230   /* 2^32 - to avoid use of LL and warnings in gcc */
36231   static const sqlite3_int64 max32BitValue = 
36232       (sqlite3_int64)2000000000 + (sqlite3_int64)2000000000 +
36233       (sqlite3_int64)294967296;
36234 
36235 #if SQLITE_OS_WINCE
36236   SYSTEMTIME time;
36237   osGetSystemTime(&time);
36238   /* if SystemTimeToFileTime() fails, it returns zero. */
36239   if (!osSystemTimeToFileTime(&time,&ft)){
36240     return SQLITE_ERROR;
36241   }
36242 #else
36243   osGetSystemTimeAsFileTime( &ft );
36244 #endif
36245 
36246   *piNow = winFiletimeEpoch +
36247             ((((sqlite3_int64)ft.dwHighDateTime)*max32BitValue) + 
36248                (sqlite3_int64)ft.dwLowDateTime)/(sqlite3_int64)10000;
36249 
36250 #ifdef SQLITE_TEST
36251   if( sqlite3_current_time ){
36252     *piNow = 1000*(sqlite3_int64)sqlite3_current_time + unixEpoch;
36253   }
36254 #endif
36255   UNUSED_PARAMETER(pVfs);
36256   return SQLITE_OK;
36257 }
36258 
36259 /*
36260 ** Find the current time (in Universal Coordinated Time).  Write the
36261 ** current time and date as a Julian Day number into *prNow and
36262 ** return 0.  Return 1 if the time and date cannot be found.
36263 */
36264 static int winCurrentTime(sqlite3_vfs *pVfs, double *prNow){
36265   int rc;
36266   sqlite3_int64 i;
36267   rc = winCurrentTimeInt64(pVfs, &i);
36268   if( !rc ){
36269     *prNow = i/86400000.0;
36270   }
36271   return rc;
36272 }
36273 
36274 /*
36275 ** The idea is that this function works like a combination of
36276 ** GetLastError() and FormatMessage() on Windows (or errno and
36277 ** strerror_r() on Unix). After an error is returned by an OS
36278 ** function, SQLite calls this function with zBuf pointing to
36279 ** a buffer of nBuf bytes. The OS layer should populate the
36280 ** buffer with a nul-terminated UTF-8 encoded error message
36281 ** describing the last IO error to have occurred within the calling
36282 ** thread.
36283 **
36284 ** If the error message is too large for the supplied buffer,
36285 ** it should be truncated. The return value of xGetLastError
36286 ** is zero if the error message fits in the buffer, or non-zero
36287 ** otherwise (if the message was truncated). If non-zero is returned,
36288 ** then it is not necessary to include the nul-terminator character
36289 ** in the output buffer.
36290 **
36291 ** Not supplying an error message will have no adverse effect
36292 ** on SQLite. It is fine to have an implementation that never
36293 ** returns an error message:
36294 **
36295 **   int xGetLastError(sqlite3_vfs *pVfs, int nBuf, char *zBuf){
36296 **     assert(zBuf[0]=='\0');
36297 **     return 0;
36298 **   }
36299 **
36300 ** However if an error message is supplied, it will be incorporated
36301 ** by sqlite into the error message available to the user using
36302 ** sqlite3_errmsg(), possibly making IO errors easier to debug.
36303 */
36304 static int winGetLastError(sqlite3_vfs *pVfs, int nBuf, char *zBuf){
36305   UNUSED_PARAMETER(pVfs);
36306   return winGetLastErrorMsg(osGetLastError(), nBuf, zBuf);
36307 }
36308 
36309 /*
36310 ** Initialize and deinitialize the operating system interface.
36311 */
36312 SQLITE_API int sqlite3_os_init(void){
36313   static sqlite3_vfs winVfs = {
36314     3,                   /* iVersion */
36315     sizeof(winFile),     /* szOsFile */
36316     SQLITE_WIN32_MAX_PATH_BYTES, /* mxPathname */
36317     0,                   /* pNext */
36318     "win32",             /* zName */
36319     0,                   /* pAppData */
36320     winOpen,             /* xOpen */
36321     winDelete,           /* xDelete */
36322     winAccess,           /* xAccess */
36323     winFullPathname,     /* xFullPathname */
36324     winDlOpen,           /* xDlOpen */
36325     winDlError,          /* xDlError */
36326     winDlSym,            /* xDlSym */
36327     winDlClose,          /* xDlClose */
36328     winRandomness,       /* xRandomness */
36329     winSleep,            /* xSleep */
36330     winCurrentTime,      /* xCurrentTime */
36331     winGetLastError,     /* xGetLastError */
36332     winCurrentTimeInt64, /* xCurrentTimeInt64 */
36333     winSetSystemCall,    /* xSetSystemCall */
36334     winGetSystemCall,    /* xGetSystemCall */
36335     winNextSystemCall,   /* xNextSystemCall */
36336   };
36337 #if defined(SQLITE_WIN32_HAS_WIDE)
36338   static sqlite3_vfs winLongPathVfs = {
36339     3,                   /* iVersion */
36340     sizeof(winFile),     /* szOsFile */
36341     SQLITE_WINNT_MAX_PATH_BYTES, /* mxPathname */
36342     0,                   /* pNext */
36343     "win32-longpath",    /* zName */
36344     0,                   /* pAppData */
36345     winOpen,             /* xOpen */
36346     winDelete,           /* xDelete */
36347     winAccess,           /* xAccess */
36348     winFullPathname,     /* xFullPathname */
36349     winDlOpen,           /* xDlOpen */
36350     winDlError,          /* xDlError */
36351     winDlSym,            /* xDlSym */
36352     winDlClose,          /* xDlClose */
36353     winRandomness,       /* xRandomness */
36354     winSleep,            /* xSleep */
36355     winCurrentTime,      /* xCurrentTime */
36356     winGetLastError,     /* xGetLastError */
36357     winCurrentTimeInt64, /* xCurrentTimeInt64 */
36358     winSetSystemCall,    /* xSetSystemCall */
36359     winGetSystemCall,    /* xGetSystemCall */
36360     winNextSystemCall,   /* xNextSystemCall */
36361   };
36362 #endif
36363 
36364   /* Double-check that the aSyscall[] array has been constructed
36365   ** correctly.  See ticket [bb3a86e890c8e96ab] */
36366   assert( ArraySize(aSyscall)==76 );
36367 
36368   /* get memory map allocation granularity */
36369   memset(&winSysInfo, 0, sizeof(SYSTEM_INFO));
36370 #if SQLITE_OS_WINRT
36371   osGetNativeSystemInfo(&winSysInfo);
36372 #else
36373   osGetSystemInfo(&winSysInfo);
36374 #endif
36375   assert( winSysInfo.dwAllocationGranularity>0 );
36376   assert( winSysInfo.dwPageSize>0 );
36377 
36378   sqlite3_vfs_register(&winVfs, 1);
36379 
36380 #if defined(SQLITE_WIN32_HAS_WIDE)
36381   sqlite3_vfs_register(&winLongPathVfs, 0);
36382 #endif
36383 
36384   return SQLITE_OK; 
36385 }
36386 
36387 SQLITE_API int sqlite3_os_end(void){ 
36388 #if SQLITE_OS_WINRT
36389   if( sleepObj!=NULL ){
36390     osCloseHandle(sleepObj);
36391     sleepObj = NULL;
36392   }
36393 #endif
36394   return SQLITE_OK;
36395 }
36396 
36397 #endif /* SQLITE_OS_WIN */
36398 
36399 /************** End of os_win.c **********************************************/
36400 /************** Begin file bitvec.c ******************************************/
36401 /*
36402 ** 2008 February 16
36403 **
36404 ** The author disclaims copyright to this source code.  In place of
36405 ** a legal notice, here is a blessing:
36406 **
36407 **    May you do good and not evil.
36408 **    May you find forgiveness for yourself and forgive others.
36409 **    May you share freely, never taking more than you give.
36410 **
36411 *************************************************************************
36412 ** This file implements an object that represents a fixed-length
36413 ** bitmap.  Bits are numbered starting with 1.
36414 **
36415 ** A bitmap is used to record which pages of a database file have been
36416 ** journalled during a transaction, or which pages have the "dont-write"
36417 ** property.  Usually only a few pages are meet either condition.
36418 ** So the bitmap is usually sparse and has low cardinality.
36419 ** But sometimes (for example when during a DROP of a large table) most
36420 ** or all of the pages in a database can get journalled.  In those cases, 
36421 ** the bitmap becomes dense with high cardinality.  The algorithm needs 
36422 ** to handle both cases well.
36423 **
36424 ** The size of the bitmap is fixed when the object is created.
36425 **
36426 ** All bits are clear when the bitmap is created.  Individual bits
36427 ** may be set or cleared one at a time.
36428 **
36429 ** Test operations are about 100 times more common that set operations.
36430 ** Clear operations are exceedingly rare.  There are usually between
36431 ** 5 and 500 set operations per Bitvec object, though the number of sets can
36432 ** sometimes grow into tens of thousands or larger.  The size of the
36433 ** Bitvec object is the number of pages in the database file at the
36434 ** start of a transaction, and is thus usually less than a few thousand,
36435 ** but can be as large as 2 billion for a really big database.
36436 */
36437 
36438 /* Size of the Bitvec structure in bytes. */
36439 #define BITVEC_SZ        512
36440 
36441 /* Round the union size down to the nearest pointer boundary, since that's how 
36442 ** it will be aligned within the Bitvec struct. */
36443 #define BITVEC_USIZE     (((BITVEC_SZ-(3*sizeof(u32)))/sizeof(Bitvec*))*sizeof(Bitvec*))
36444 
36445 /* Type of the array "element" for the bitmap representation. 
36446 ** Should be a power of 2, and ideally, evenly divide into BITVEC_USIZE. 
36447 ** Setting this to the "natural word" size of your CPU may improve
36448 ** performance. */
36449 #define BITVEC_TELEM     u8
36450 /* Size, in bits, of the bitmap element. */
36451 #define BITVEC_SZELEM    8
36452 /* Number of elements in a bitmap array. */
36453 #define BITVEC_NELEM     (BITVEC_USIZE/sizeof(BITVEC_TELEM))
36454 /* Number of bits in the bitmap array. */
36455 #define BITVEC_NBIT      (BITVEC_NELEM*BITVEC_SZELEM)
36456 
36457 /* Number of u32 values in hash table. */
36458 #define BITVEC_NINT      (BITVEC_USIZE/sizeof(u32))
36459 /* Maximum number of entries in hash table before 
36460 ** sub-dividing and re-hashing. */
36461 #define BITVEC_MXHASH    (BITVEC_NINT/2)
36462 /* Hashing function for the aHash representation.
36463 ** Empirical testing showed that the *37 multiplier 
36464 ** (an arbitrary prime)in the hash function provided 
36465 ** no fewer collisions than the no-op *1. */
36466 #define BITVEC_HASH(X)   (((X)*1)%BITVEC_NINT)
36467 
36468 #define BITVEC_NPTR      (BITVEC_USIZE/sizeof(Bitvec *))
36469 
36470 
36471 /*
36472 ** A bitmap is an instance of the following structure.
36473 **
36474 ** This bitmap records the existence of zero or more bits
36475 ** with values between 1 and iSize, inclusive.
36476 **
36477 ** There are three possible representations of the bitmap.
36478 ** If iSize<=BITVEC_NBIT, then Bitvec.u.aBitmap[] is a straight
36479 ** bitmap.  The least significant bit is bit 1.
36480 **
36481 ** If iSize>BITVEC_NBIT and iDivisor==0 then Bitvec.u.aHash[] is
36482 ** a hash table that will hold up to BITVEC_MXHASH distinct values.
36483 **
36484 ** Otherwise, the value i is redirected into one of BITVEC_NPTR
36485 ** sub-bitmaps pointed to by Bitvec.u.apSub[].  Each subbitmap
36486 ** handles up to iDivisor separate values of i.  apSub[0] holds
36487 ** values between 1 and iDivisor.  apSub[1] holds values between
36488 ** iDivisor+1 and 2*iDivisor.  apSub[N] holds values between
36489 ** N*iDivisor+1 and (N+1)*iDivisor.  Each subbitmap is normalized
36490 ** to hold deal with values between 1 and iDivisor.
36491 */
36492 struct Bitvec {
36493   u32 iSize;      /* Maximum bit index.  Max iSize is 4,294,967,296. */
36494   u32 nSet;       /* Number of bits that are set - only valid for aHash
36495                   ** element.  Max is BITVEC_NINT.  For BITVEC_SZ of 512,
36496                   ** this would be 125. */
36497   u32 iDivisor;   /* Number of bits handled by each apSub[] entry. */
36498                   /* Should >=0 for apSub element. */
36499                   /* Max iDivisor is max(u32) / BITVEC_NPTR + 1.  */
36500                   /* For a BITVEC_SZ of 512, this would be 34,359,739. */
36501   union {
36502     BITVEC_TELEM aBitmap[BITVEC_NELEM];    /* Bitmap representation */
36503     u32 aHash[BITVEC_NINT];      /* Hash table representation */
36504     Bitvec *apSub[BITVEC_NPTR];  /* Recursive representation */
36505   } u;
36506 };
36507 
36508 /*
36509 ** Create a new bitmap object able to handle bits between 0 and iSize,
36510 ** inclusive.  Return a pointer to the new object.  Return NULL if 
36511 ** malloc fails.
36512 */
36513 SQLITE_PRIVATE Bitvec *sqlite3BitvecCreate(u32 iSize){
36514   Bitvec *p;
36515   assert( sizeof(*p)==BITVEC_SZ );
36516   p = sqlite3MallocZero( sizeof(*p) );
36517   if( p ){
36518     p->iSize = iSize;
36519   }
36520   return p;
36521 }
36522 
36523 /*
36524 ** Check to see if the i-th bit is set.  Return true or false.
36525 ** If p is NULL (if the bitmap has not been created) or if
36526 ** i is out of range, then return false.
36527 */
36528 SQLITE_PRIVATE int sqlite3BitvecTest(Bitvec *p, u32 i){
36529   if( p==0 ) return 0;
36530   if( i>p->iSize || i==0 ) return 0;
36531   i--;
36532   while( p->iDivisor ){
36533     u32 bin = i/p->iDivisor;
36534     i = i%p->iDivisor;
36535     p = p->u.apSub[bin];
36536     if (!p) {
36537       return 0;
36538     }
36539   }
36540   if( p->iSize<=BITVEC_NBIT ){
36541     return (p->u.aBitmap[i/BITVEC_SZELEM] & (1<<(i&(BITVEC_SZELEM-1))))!=0;
36542   } else{
36543     u32 h = BITVEC_HASH(i++);
36544     while( p->u.aHash[h] ){
36545       if( p->u.aHash[h]==i ) return 1;
36546       h = (h+1) % BITVEC_NINT;
36547     }
36548     return 0;
36549   }
36550 }
36551 
36552 /*
36553 ** Set the i-th bit.  Return 0 on success and an error code if
36554 ** anything goes wrong.
36555 **
36556 ** This routine might cause sub-bitmaps to be allocated.  Failing
36557 ** to get the memory needed to hold the sub-bitmap is the only
36558 ** that can go wrong with an insert, assuming p and i are valid.
36559 **
36560 ** The calling function must ensure that p is a valid Bitvec object
36561 ** and that the value for "i" is within range of the Bitvec object.
36562 ** Otherwise the behavior is undefined.
36563 */
36564 SQLITE_PRIVATE int sqlite3BitvecSet(Bitvec *p, u32 i){
36565   u32 h;
36566   if( p==0 ) return SQLITE_OK;
36567   assert( i>0 );
36568   assert( i<=p->iSize );
36569   i--;
36570   while((p->iSize > BITVEC_NBIT) && p->iDivisor) {
36571     u32 bin = i/p->iDivisor;
36572     i = i%p->iDivisor;
36573     if( p->u.apSub[bin]==0 ){
36574       p->u.apSub[bin] = sqlite3BitvecCreate( p->iDivisor );
36575       if( p->u.apSub[bin]==0 ) return SQLITE_NOMEM;
36576     }
36577     p = p->u.apSub[bin];
36578   }
36579   if( p->iSize<=BITVEC_NBIT ){
36580     p->u.aBitmap[i/BITVEC_SZELEM] |= 1 << (i&(BITVEC_SZELEM-1));
36581     return SQLITE_OK;
36582   }
36583   h = BITVEC_HASH(i++);
36584   /* if there wasn't a hash collision, and this doesn't */
36585   /* completely fill the hash, then just add it without */
36586   /* worring about sub-dividing and re-hashing. */
36587   if( !p->u.aHash[h] ){
36588     if (p->nSet<(BITVEC_NINT-1)) {
36589       goto bitvec_set_end;
36590     } else {
36591       goto bitvec_set_rehash;
36592     }
36593   }
36594   /* there was a collision, check to see if it's already */
36595   /* in hash, if not, try to find a spot for it */
36596   do {
36597     if( p->u.aHash[h]==i ) return SQLITE_OK;
36598     h++;
36599     if( h>=BITVEC_NINT ) h = 0;
36600   } while( p->u.aHash[h] );
36601   /* we didn't find it in the hash.  h points to the first */
36602   /* available free spot. check to see if this is going to */
36603   /* make our hash too "full".  */
36604 bitvec_set_rehash:
36605   if( p->nSet>=BITVEC_MXHASH ){
36606     unsigned int j;
36607     int rc;
36608     u32 *aiValues = sqlite3StackAllocRaw(0, sizeof(p->u.aHash));
36609     if( aiValues==0 ){
36610       return SQLITE_NOMEM;
36611     }else{
36612       memcpy(aiValues, p->u.aHash, sizeof(p->u.aHash));
36613       memset(p->u.apSub, 0, sizeof(p->u.apSub));
36614       p->iDivisor = (p->iSize + BITVEC_NPTR - 1)/BITVEC_NPTR;
36615       rc = sqlite3BitvecSet(p, i);
36616       for(j=0; j<BITVEC_NINT; j++){
36617         if( aiValues[j] ) rc |= sqlite3BitvecSet(p, aiValues[j]);
36618       }
36619       sqlite3StackFree(0, aiValues);
36620       return rc;
36621     }
36622   }
36623 bitvec_set_end:
36624   p->nSet++;
36625   p->u.aHash[h] = i;
36626   return SQLITE_OK;
36627 }
36628 
36629 /*
36630 ** Clear the i-th bit.
36631 **
36632 ** pBuf must be a pointer to at least BITVEC_SZ bytes of temporary storage
36633 ** that BitvecClear can use to rebuilt its hash table.
36634 */
36635 SQLITE_PRIVATE void sqlite3BitvecClear(Bitvec *p, u32 i, void *pBuf){
36636   if( p==0 ) return;
36637   assert( i>0 );
36638   i--;
36639   while( p->iDivisor ){
36640     u32 bin = i/p->iDivisor;
36641     i = i%p->iDivisor;
36642     p = p->u.apSub[bin];
36643     if (!p) {
36644       return;
36645     }
36646   }
36647   if( p->iSize<=BITVEC_NBIT ){
36648     p->u.aBitmap[i/BITVEC_SZELEM] &= ~(1 << (i&(BITVEC_SZELEM-1)));
36649   }else{
36650     unsigned int j;
36651     u32 *aiValues = pBuf;
36652     memcpy(aiValues, p->u.aHash, sizeof(p->u.aHash));
36653     memset(p->u.aHash, 0, sizeof(p->u.aHash));
36654     p->nSet = 0;
36655     for(j=0; j<BITVEC_NINT; j++){
36656       if( aiValues[j] && aiValues[j]!=(i+1) ){
36657         u32 h = BITVEC_HASH(aiValues[j]-1);
36658         p->nSet++;
36659         while( p->u.aHash[h] ){
36660           h++;
36661           if( h>=BITVEC_NINT ) h = 0;
36662         }
36663         p->u.aHash[h] = aiValues[j];
36664       }
36665     }
36666   }
36667 }
36668 
36669 /*
36670 ** Destroy a bitmap object.  Reclaim all memory used.
36671 */
36672 SQLITE_PRIVATE void sqlite3BitvecDestroy(Bitvec *p){
36673   if( p==0 ) return;
36674   if( p->iDivisor ){
36675     unsigned int i;
36676     for(i=0; i<BITVEC_NPTR; i++){
36677       sqlite3BitvecDestroy(p->u.apSub[i]);
36678     }
36679   }
36680   sqlite3_free(p);
36681 }
36682 
36683 /*
36684 ** Return the value of the iSize parameter specified when Bitvec *p
36685 ** was created.
36686 */
36687 SQLITE_PRIVATE u32 sqlite3BitvecSize(Bitvec *p){
36688   return p->iSize;
36689 }
36690 
36691 #ifndef SQLITE_OMIT_BUILTIN_TEST
36692 /*
36693 ** Let V[] be an array of unsigned characters sufficient to hold
36694 ** up to N bits.  Let I be an integer between 0 and N.  0<=I<N.
36695 ** Then the following macros can be used to set, clear, or test
36696 ** individual bits within V.
36697 */
36698 #define SETBIT(V,I)      V[I>>3] |= (1<<(I&7))
36699 #define CLEARBIT(V,I)    V[I>>3] &= ~(1<<(I&7))
36700 #define TESTBIT(V,I)     (V[I>>3]&(1<<(I&7)))!=0
36701 
36702 /*
36703 ** This routine runs an extensive test of the Bitvec code.
36704 **
36705 ** The input is an array of integers that acts as a program
36706 ** to test the Bitvec.  The integers are opcodes followed
36707 ** by 0, 1, or 3 operands, depending on the opcode.  Another
36708 ** opcode follows immediately after the last operand.
36709 **
36710 ** There are 6 opcodes numbered from 0 through 5.  0 is the
36711 ** "halt" opcode and causes the test to end.
36712 **
36713 **    0          Halt and return the number of errors
36714 **    1 N S X    Set N bits beginning with S and incrementing by X
36715 **    2 N S X    Clear N bits beginning with S and incrementing by X
36716 **    3 N        Set N randomly chosen bits
36717 **    4 N        Clear N randomly chosen bits
36718 **    5 N S X    Set N bits from S increment X in array only, not in bitvec
36719 **
36720 ** The opcodes 1 through 4 perform set and clear operations are performed
36721 ** on both a Bitvec object and on a linear array of bits obtained from malloc.
36722 ** Opcode 5 works on the linear array only, not on the Bitvec.
36723 ** Opcode 5 is used to deliberately induce a fault in order to
36724 ** confirm that error detection works.
36725 **
36726 ** At the conclusion of the test the linear array is compared
36727 ** against the Bitvec object.  If there are any differences,
36728 ** an error is returned.  If they are the same, zero is returned.
36729 **
36730 ** If a memory allocation error occurs, return -1.
36731 */
36732 SQLITE_PRIVATE int sqlite3BitvecBuiltinTest(int sz, int *aOp){
36733   Bitvec *pBitvec = 0;
36734   unsigned char *pV = 0;
36735   int rc = -1;
36736   int i, nx, pc, op;
36737   void *pTmpSpace;
36738 
36739   /* Allocate the Bitvec to be tested and a linear array of
36740   ** bits to act as the reference */
36741   pBitvec = sqlite3BitvecCreate( sz );
36742   pV = sqlite3MallocZero( (sz+7)/8 + 1 );
36743   pTmpSpace = sqlite3_malloc(BITVEC_SZ);
36744   if( pBitvec==0 || pV==0 || pTmpSpace==0  ) goto bitvec_end;
36745 
36746   /* NULL pBitvec tests */
36747   sqlite3BitvecSet(0, 1);
36748   sqlite3BitvecClear(0, 1, pTmpSpace);
36749 
36750   /* Run the program */
36751   pc = 0;
36752   while( (op = aOp[pc])!=0 ){
36753     switch( op ){
36754       case 1:
36755       case 2:
36756       case 5: {
36757         nx = 4;
36758         i = aOp[pc+2] - 1;
36759         aOp[pc+2] += aOp[pc+3];
36760         break;
36761       }
36762       case 3:
36763       case 4: 
36764       default: {
36765         nx = 2;
36766         sqlite3_randomness(sizeof(i), &i);
36767         break;
36768       }
36769     }
36770     if( (--aOp[pc+1]) > 0 ) nx = 0;
36771     pc += nx;
36772     i = (i & 0x7fffffff)%sz;
36773     if( (op & 1)!=0 ){
36774       SETBIT(pV, (i+1));
36775       if( op!=5 ){
36776         if( sqlite3BitvecSet(pBitvec, i+1) ) goto bitvec_end;
36777       }
36778     }else{
36779       CLEARBIT(pV, (i+1));
36780       sqlite3BitvecClear(pBitvec, i+1, pTmpSpace);
36781     }
36782   }
36783 
36784   /* Test to make sure the linear array exactly matches the
36785   ** Bitvec object.  Start with the assumption that they do
36786   ** match (rc==0).  Change rc to non-zero if a discrepancy
36787   ** is found.
36788   */
36789   rc = sqlite3BitvecTest(0,0) + sqlite3BitvecTest(pBitvec, sz+1)
36790           + sqlite3BitvecTest(pBitvec, 0)
36791           + (sqlite3BitvecSize(pBitvec) - sz);
36792   for(i=1; i<=sz; i++){
36793     if(  (TESTBIT(pV,i))!=sqlite3BitvecTest(pBitvec,i) ){
36794       rc = i;
36795       break;
36796     }
36797   }
36798 
36799   /* Free allocated structure */
36800 bitvec_end:
36801   sqlite3_free(pTmpSpace);
36802   sqlite3_free(pV);
36803   sqlite3BitvecDestroy(pBitvec);
36804   return rc;
36805 }
36806 #endif /* SQLITE_OMIT_BUILTIN_TEST */
36807 
36808 /************** End of bitvec.c **********************************************/
36809 /************** Begin file pcache.c ******************************************/
36810 /*
36811 ** 2008 August 05
36812 **
36813 ** The author disclaims copyright to this source code.  In place of
36814 ** a legal notice, here is a blessing:
36815 **
36816 **    May you do good and not evil.
36817 **    May you find forgiveness for yourself and forgive others.
36818 **    May you share freely, never taking more than you give.
36819 **
36820 *************************************************************************
36821 ** This file implements that page cache.
36822 */
36823 
36824 /*
36825 ** A complete page cache is an instance of this structure.
36826 */
36827 struct PCache {
36828   PgHdr *pDirty, *pDirtyTail;         /* List of dirty pages in LRU order */
36829   PgHdr *pSynced;                     /* Last synced page in dirty page list */
36830   int nRef;                           /* Number of referenced pages */
36831   int szCache;                        /* Configured cache size */
36832   int szPage;                         /* Size of every page in this cache */
36833   int szExtra;                        /* Size of extra space for each page */
36834   int bPurgeable;                     /* True if pages are on backing store */
36835   int (*xStress)(void*,PgHdr*);       /* Call to try make a page clean */
36836   void *pStress;                      /* Argument to xStress */
36837   sqlite3_pcache *pCache;             /* Pluggable cache module */
36838   PgHdr *pPage1;                      /* Reference to page 1 */
36839 };
36840 
36841 /*
36842 ** Some of the assert() macros in this code are too expensive to run
36843 ** even during normal debugging.  Use them only rarely on long-running
36844 ** tests.  Enable the expensive asserts using the
36845 ** -DSQLITE_ENABLE_EXPENSIVE_ASSERT=1 compile-time option.
36846 */
36847 #ifdef SQLITE_ENABLE_EXPENSIVE_ASSERT
36848 # define expensive_assert(X)  assert(X)
36849 #else
36850 # define expensive_assert(X)
36851 #endif
36852 
36853 /********************************** Linked List Management ********************/
36854 
36855 #if !defined(NDEBUG) && defined(SQLITE_ENABLE_EXPENSIVE_ASSERT)
36856 /*
36857 ** Check that the pCache->pSynced variable is set correctly. If it
36858 ** is not, either fail an assert or return zero. Otherwise, return
36859 ** non-zero. This is only used in debugging builds, as follows:
36860 **
36861 **   expensive_assert( pcacheCheckSynced(pCache) );
36862 */
36863 static int pcacheCheckSynced(PCache *pCache){
36864   PgHdr *p;
36865   for(p=pCache->pDirtyTail; p!=pCache->pSynced; p=p->pDirtyPrev){
36866     assert( p->nRef || (p->flags&PGHDR_NEED_SYNC) );
36867   }
36868   return (p==0 || p->nRef || (p->flags&PGHDR_NEED_SYNC)==0);
36869 }
36870 #endif /* !NDEBUG && SQLITE_ENABLE_EXPENSIVE_ASSERT */
36871 
36872 /*
36873 ** Remove page pPage from the list of dirty pages.
36874 */
36875 static void pcacheRemoveFromDirtyList(PgHdr *pPage){
36876   PCache *p = pPage->pCache;
36877 
36878   assert( pPage->pDirtyNext || pPage==p->pDirtyTail );
36879   assert( pPage->pDirtyPrev || pPage==p->pDirty );
36880 
36881   /* Update the PCache1.pSynced variable if necessary. */
36882   if( p->pSynced==pPage ){
36883     PgHdr *pSynced = pPage->pDirtyPrev;
36884     while( pSynced && (pSynced->flags&PGHDR_NEED_SYNC) ){
36885       pSynced = pSynced->pDirtyPrev;
36886     }
36887     p->pSynced = pSynced;
36888   }
36889 
36890   if( pPage->pDirtyNext ){
36891     pPage->pDirtyNext->pDirtyPrev = pPage->pDirtyPrev;
36892   }else{
36893     assert( pPage==p->pDirtyTail );
36894     p->pDirtyTail = pPage->pDirtyPrev;
36895   }
36896   if( pPage->pDirtyPrev ){
36897     pPage->pDirtyPrev->pDirtyNext = pPage->pDirtyNext;
36898   }else{
36899     assert( pPage==p->pDirty );
36900     p->pDirty = pPage->pDirtyNext;
36901   }
36902   pPage->pDirtyNext = 0;
36903   pPage->pDirtyPrev = 0;
36904 
36905   expensive_assert( pcacheCheckSynced(p) );
36906 }
36907 
36908 /*
36909 ** Add page pPage to the head of the dirty list (PCache1.pDirty is set to
36910 ** pPage).
36911 */
36912 static void pcacheAddToDirtyList(PgHdr *pPage){
36913   PCache *p = pPage->pCache;
36914 
36915   assert( pPage->pDirtyNext==0 && pPage->pDirtyPrev==0 && p->pDirty!=pPage );
36916 
36917   pPage->pDirtyNext = p->pDirty;
36918   if( pPage->pDirtyNext ){
36919     assert( pPage->pDirtyNext->pDirtyPrev==0 );
36920     pPage->pDirtyNext->pDirtyPrev = pPage;
36921   }
36922   p->pDirty = pPage;
36923   if( !p->pDirtyTail ){
36924     p->pDirtyTail = pPage;
36925   }
36926   if( !p->pSynced && 0==(pPage->flags&PGHDR_NEED_SYNC) ){
36927     p->pSynced = pPage;
36928   }
36929   expensive_assert( pcacheCheckSynced(p) );
36930 }
36931 
36932 /*
36933 ** Wrapper around the pluggable caches xUnpin method. If the cache is
36934 ** being used for an in-memory database, this function is a no-op.
36935 */
36936 static void pcacheUnpin(PgHdr *p){
36937   PCache *pCache = p->pCache;
36938   if( pCache->bPurgeable ){
36939     if( p->pgno==1 ){
36940       pCache->pPage1 = 0;
36941     }
36942     sqlite3GlobalConfig.pcache2.xUnpin(pCache->pCache, p->pPage, 0);
36943   }
36944 }
36945 
36946 /*************************************************** General Interfaces ******
36947 **
36948 ** Initialize and shutdown the page cache subsystem. Neither of these 
36949 ** functions are threadsafe.
36950 */
36951 SQLITE_PRIVATE int sqlite3PcacheInitialize(void){
36952   if( sqlite3GlobalConfig.pcache2.xInit==0 ){
36953     /* IMPLEMENTATION-OF: R-26801-64137 If the xInit() method is NULL, then the
36954     ** built-in default page cache is used instead of the application defined
36955     ** page cache. */
36956     sqlite3PCacheSetDefault();
36957   }
36958   return sqlite3GlobalConfig.pcache2.xInit(sqlite3GlobalConfig.pcache2.pArg);
36959 }
36960 SQLITE_PRIVATE void sqlite3PcacheShutdown(void){
36961   if( sqlite3GlobalConfig.pcache2.xShutdown ){
36962     /* IMPLEMENTATION-OF: R-26000-56589 The xShutdown() method may be NULL. */
36963     sqlite3GlobalConfig.pcache2.xShutdown(sqlite3GlobalConfig.pcache2.pArg);
36964   }
36965 }
36966 
36967 /*
36968 ** Return the size in bytes of a PCache object.
36969 */
36970 SQLITE_PRIVATE int sqlite3PcacheSize(void){ return sizeof(PCache); }
36971 
36972 /*
36973 ** Create a new PCache object. Storage space to hold the object
36974 ** has already been allocated and is passed in as the p pointer. 
36975 ** The caller discovers how much space needs to be allocated by 
36976 ** calling sqlite3PcacheSize().
36977 */
36978 SQLITE_PRIVATE void sqlite3PcacheOpen(
36979   int szPage,                  /* Size of every page */
36980   int szExtra,                 /* Extra space associated with each page */
36981   int bPurgeable,              /* True if pages are on backing store */
36982   int (*xStress)(void*,PgHdr*),/* Call to try to make pages clean */
36983   void *pStress,               /* Argument to xStress */
36984   PCache *p                    /* Preallocated space for the PCache */
36985 ){
36986   memset(p, 0, sizeof(PCache));
36987   p->szPage = szPage;
36988   p->szExtra = szExtra;
36989   p->bPurgeable = bPurgeable;
36990   p->xStress = xStress;
36991   p->pStress = pStress;
36992   p->szCache = 100;
36993 }
36994 
36995 /*
36996 ** Change the page size for PCache object. The caller must ensure that there
36997 ** are no outstanding page references when this function is called.
36998 */
36999 SQLITE_PRIVATE void sqlite3PcacheSetPageSize(PCache *pCache, int szPage){
37000   assert( pCache->nRef==0 && pCache->pDirty==0 );
37001   if( pCache->pCache ){
37002     sqlite3GlobalConfig.pcache2.xDestroy(pCache->pCache);
37003     pCache->pCache = 0;
37004     pCache->pPage1 = 0;
37005   }
37006   pCache->szPage = szPage;
37007 }
37008 
37009 /*
37010 ** Compute the number of pages of cache requested.
37011 */
37012 static int numberOfCachePages(PCache *p){
37013   if( p->szCache>=0 ){
37014     return p->szCache;
37015   }else{
37016     return (int)((-1024*(i64)p->szCache)/(p->szPage+p->szExtra));
37017   }
37018 }
37019 
37020 /*
37021 ** Try to obtain a page from the cache.
37022 */
37023 SQLITE_PRIVATE int sqlite3PcacheFetch(
37024   PCache *pCache,       /* Obtain the page from this cache */
37025   Pgno pgno,            /* Page number to obtain */
37026   int createFlag,       /* If true, create page if it does not exist already */
37027   PgHdr **ppPage        /* Write the page here */
37028 ){
37029   sqlite3_pcache_page *pPage = 0;
37030   PgHdr *pPgHdr = 0;
37031   int eCreate;
37032 
37033   assert( pCache!=0 );
37034   assert( createFlag==1 || createFlag==0 );
37035   assert( pgno>0 );
37036 
37037   /* If the pluggable cache (sqlite3_pcache*) has not been allocated,
37038   ** allocate it now.
37039   */
37040   if( !pCache->pCache && createFlag ){
37041     sqlite3_pcache *p;
37042     p = sqlite3GlobalConfig.pcache2.xCreate(
37043         pCache->szPage, pCache->szExtra + sizeof(PgHdr), pCache->bPurgeable
37044     );
37045     if( !p ){
37046       return SQLITE_NOMEM;
37047     }
37048     sqlite3GlobalConfig.pcache2.xCachesize(p, numberOfCachePages(pCache));
37049     pCache->pCache = p;
37050   }
37051 
37052   eCreate = createFlag * (1 + (!pCache->bPurgeable || !pCache->pDirty));
37053   if( pCache->pCache ){
37054     pPage = sqlite3GlobalConfig.pcache2.xFetch(pCache->pCache, pgno, eCreate);
37055   }
37056 
37057   if( !pPage && eCreate==1 ){
37058     PgHdr *pPg;
37059 
37060     /* Find a dirty page to write-out and recycle. First try to find a 
37061     ** page that does not require a journal-sync (one with PGHDR_NEED_SYNC
37062     ** cleared), but if that is not possible settle for any other 
37063     ** unreferenced dirty page.
37064     */
37065     expensive_assert( pcacheCheckSynced(pCache) );
37066     for(pPg=pCache->pSynced; 
37067         pPg && (pPg->nRef || (pPg->flags&PGHDR_NEED_SYNC)); 
37068         pPg=pPg->pDirtyPrev
37069     );
37070     pCache->pSynced = pPg;
37071     if( !pPg ){
37072       for(pPg=pCache->pDirtyTail; pPg && pPg->nRef; pPg=pPg->pDirtyPrev);
37073     }
37074     if( pPg ){
37075       int rc;
37076 #ifdef SQLITE_LOG_CACHE_SPILL
37077       sqlite3_log(SQLITE_FULL, 
37078                   "spill page %d making room for %d - cache used: %d/%d",
37079                   pPg->pgno, pgno,
37080                   sqlite3GlobalConfig.pcache.xPagecount(pCache->pCache),
37081                   numberOfCachePages(pCache));
37082 #endif
37083       rc = pCache->xStress(pCache->pStress, pPg);
37084       if( rc!=SQLITE_OK && rc!=SQLITE_BUSY ){
37085         return rc;
37086       }
37087     }
37088 
37089     pPage = sqlite3GlobalConfig.pcache2.xFetch(pCache->pCache, pgno, 2);
37090   }
37091 
37092   if( pPage ){
37093     pPgHdr = (PgHdr *)pPage->pExtra;
37094 
37095     if( !pPgHdr->pPage ){
37096       memset(pPgHdr, 0, sizeof(PgHdr));
37097       pPgHdr->pPage = pPage;
37098       pPgHdr->pData = pPage->pBuf;
37099       pPgHdr->pExtra = (void *)&pPgHdr[1];
37100       memset(pPgHdr->pExtra, 0, pCache->szExtra);
37101       pPgHdr->pCache = pCache;
37102       pPgHdr->pgno = pgno;
37103     }
37104     assert( pPgHdr->pCache==pCache );
37105     assert( pPgHdr->pgno==pgno );
37106     assert( pPgHdr->pData==pPage->pBuf );
37107     assert( pPgHdr->pExtra==(void *)&pPgHdr[1] );
37108 
37109     if( 0==pPgHdr->nRef ){
37110       pCache->nRef++;
37111     }
37112     pPgHdr->nRef++;
37113     if( pgno==1 ){
37114       pCache->pPage1 = pPgHdr;
37115     }
37116   }
37117   *ppPage = pPgHdr;
37118   return (pPgHdr==0 && eCreate) ? SQLITE_NOMEM : SQLITE_OK;
37119 }
37120 
37121 /*
37122 ** Decrement the reference count on a page. If the page is clean and the
37123 ** reference count drops to 0, then it is made elible for recycling.
37124 */
37125 SQLITE_PRIVATE void sqlite3PcacheRelease(PgHdr *p){
37126   assert( p->nRef>0 );
37127   p->nRef--;
37128   if( p->nRef==0 ){
37129     PCache *pCache = p->pCache;
37130     pCache->nRef--;
37131     if( (p->flags&PGHDR_DIRTY)==0 ){
37132       pcacheUnpin(p);
37133     }else{
37134       /* Move the page to the head of the dirty list. */
37135       pcacheRemoveFromDirtyList(p);
37136       pcacheAddToDirtyList(p);
37137     }
37138   }
37139 }
37140 
37141 /*
37142 ** Increase the reference count of a supplied page by 1.
37143 */
37144 SQLITE_PRIVATE void sqlite3PcacheRef(PgHdr *p){
37145   assert(p->nRef>0);
37146   p->nRef++;
37147 }
37148 
37149 /*
37150 ** Drop a page from the cache. There must be exactly one reference to the
37151 ** page. This function deletes that reference, so after it returns the
37152 ** page pointed to by p is invalid.
37153 */
37154 SQLITE_PRIVATE void sqlite3PcacheDrop(PgHdr *p){
37155   PCache *pCache;
37156   assert( p->nRef==1 );
37157   if( p->flags&PGHDR_DIRTY ){
37158     pcacheRemoveFromDirtyList(p);
37159   }
37160   pCache = p->pCache;
37161   pCache->nRef--;
37162   if( p->pgno==1 ){
37163     pCache->pPage1 = 0;
37164   }
37165   sqlite3GlobalConfig.pcache2.xUnpin(pCache->pCache, p->pPage, 1);
37166 }
37167 
37168 /*
37169 ** Make sure the page is marked as dirty. If it isn't dirty already,
37170 ** make it so.
37171 */
37172 SQLITE_PRIVATE void sqlite3PcacheMakeDirty(PgHdr *p){
37173   p->flags &= ~PGHDR_DONT_WRITE;
37174   assert( p->nRef>0 );
37175   if( 0==(p->flags & PGHDR_DIRTY) ){
37176     p->flags |= PGHDR_DIRTY;
37177     pcacheAddToDirtyList( p);
37178   }
37179 }
37180 
37181 /*
37182 ** Make sure the page is marked as clean. If it isn't clean already,
37183 ** make it so.
37184 */
37185 SQLITE_PRIVATE void sqlite3PcacheMakeClean(PgHdr *p){
37186   if( (p->flags & PGHDR_DIRTY) ){
37187     pcacheRemoveFromDirtyList(p);
37188     p->flags &= ~(PGHDR_DIRTY|PGHDR_NEED_SYNC);
37189     if( p->nRef==0 ){
37190       pcacheUnpin(p);
37191     }
37192   }
37193 }
37194 
37195 /*
37196 ** Make every page in the cache clean.
37197 */
37198 SQLITE_PRIVATE void sqlite3PcacheCleanAll(PCache *pCache){
37199   PgHdr *p;
37200   while( (p = pCache->pDirty)!=0 ){
37201     sqlite3PcacheMakeClean(p);
37202   }
37203 }
37204 
37205 /*
37206 ** Clear the PGHDR_NEED_SYNC flag from all dirty pages.
37207 */
37208 SQLITE_PRIVATE void sqlite3PcacheClearSyncFlags(PCache *pCache){
37209   PgHdr *p;
37210   for(p=pCache->pDirty; p; p=p->pDirtyNext){
37211     p->flags &= ~PGHDR_NEED_SYNC;
37212   }
37213   pCache->pSynced = pCache->pDirtyTail;
37214 }
37215 
37216 /*
37217 ** Change the page number of page p to newPgno. 
37218 */
37219 SQLITE_PRIVATE void sqlite3PcacheMove(PgHdr *p, Pgno newPgno){
37220   PCache *pCache = p->pCache;
37221   assert( p->nRef>0 );
37222   assert( newPgno>0 );
37223   sqlite3GlobalConfig.pcache2.xRekey(pCache->pCache, p->pPage, p->pgno,newPgno);
37224   p->pgno = newPgno;
37225   if( (p->flags&PGHDR_DIRTY) && (p->flags&PGHDR_NEED_SYNC) ){
37226     pcacheRemoveFromDirtyList(p);
37227     pcacheAddToDirtyList(p);
37228   }
37229 }
37230 
37231 /*
37232 ** Drop every cache entry whose page number is greater than "pgno". The
37233 ** caller must ensure that there are no outstanding references to any pages
37234 ** other than page 1 with a page number greater than pgno.
37235 **
37236 ** If there is a reference to page 1 and the pgno parameter passed to this
37237 ** function is 0, then the data area associated with page 1 is zeroed, but
37238 ** the page object is not dropped.
37239 */
37240 SQLITE_PRIVATE void sqlite3PcacheTruncate(PCache *pCache, Pgno pgno){
37241   if( pCache->pCache ){
37242     PgHdr *p;
37243     PgHdr *pNext;
37244     for(p=pCache->pDirty; p; p=pNext){
37245       pNext = p->pDirtyNext;
37246       /* This routine never gets call with a positive pgno except right
37247       ** after sqlite3PcacheCleanAll().  So if there are dirty pages,
37248       ** it must be that pgno==0.
37249       */
37250       assert( p->pgno>0 );
37251       if( ALWAYS(p->pgno>pgno) ){
37252         assert( p->flags&PGHDR_DIRTY );
37253         sqlite3PcacheMakeClean(p);
37254       }
37255     }
37256     if( pgno==0 && pCache->pPage1 ){
37257       memset(pCache->pPage1->pData, 0, pCache->szPage);
37258       pgno = 1;
37259     }
37260     sqlite3GlobalConfig.pcache2.xTruncate(pCache->pCache, pgno+1);
37261   }
37262 }
37263 
37264 /*
37265 ** Close a cache.
37266 */
37267 SQLITE_PRIVATE void sqlite3PcacheClose(PCache *pCache){
37268   if( pCache->pCache ){
37269     sqlite3GlobalConfig.pcache2.xDestroy(pCache->pCache);
37270   }
37271 }
37272 
37273 /* 
37274 ** Discard the contents of the cache.
37275 */
37276 SQLITE_PRIVATE void sqlite3PcacheClear(PCache *pCache){
37277   sqlite3PcacheTruncate(pCache, 0);
37278 }
37279 
37280 /*
37281 ** Merge two lists of pages connected by pDirty and in pgno order.
37282 ** Do not both fixing the pDirtyPrev pointers.
37283 */
37284 static PgHdr *pcacheMergeDirtyList(PgHdr *pA, PgHdr *pB){
37285   PgHdr result, *pTail;
37286   pTail = &result;
37287   while( pA && pB ){
37288     if( pA->pgno<pB->pgno ){
37289       pTail->pDirty = pA;
37290       pTail = pA;
37291       pA = pA->pDirty;
37292     }else{
37293       pTail->pDirty = pB;
37294       pTail = pB;
37295       pB = pB->pDirty;
37296     }
37297   }
37298   if( pA ){
37299     pTail->pDirty = pA;
37300   }else if( pB ){
37301     pTail->pDirty = pB;
37302   }else{
37303     pTail->pDirty = 0;
37304   }
37305   return result.pDirty;
37306 }
37307 
37308 /*
37309 ** Sort the list of pages in accending order by pgno.  Pages are
37310 ** connected by pDirty pointers.  The pDirtyPrev pointers are
37311 ** corrupted by this sort.
37312 **
37313 ** Since there cannot be more than 2^31 distinct pages in a database,
37314 ** there cannot be more than 31 buckets required by the merge sorter.
37315 ** One extra bucket is added to catch overflow in case something
37316 ** ever changes to make the previous sentence incorrect.
37317 */
37318 #define N_SORT_BUCKET  32
37319 static PgHdr *pcacheSortDirtyList(PgHdr *pIn){
37320   PgHdr *a[N_SORT_BUCKET], *p;
37321   int i;
37322   memset(a, 0, sizeof(a));
37323   while( pIn ){
37324     p = pIn;
37325     pIn = p->pDirty;
37326     p->pDirty = 0;
37327     for(i=0; ALWAYS(i<N_SORT_BUCKET-1); i++){
37328       if( a[i]==0 ){
37329         a[i] = p;
37330         break;
37331       }else{
37332         p = pcacheMergeDirtyList(a[i], p);
37333         a[i] = 0;
37334       }
37335     }
37336     if( NEVER(i==N_SORT_BUCKET-1) ){
37337       /* To get here, there need to be 2^(N_SORT_BUCKET) elements in
37338       ** the input list.  But that is impossible.
37339       */
37340       a[i] = pcacheMergeDirtyList(a[i], p);
37341     }
37342   }
37343   p = a[0];
37344   for(i=1; i<N_SORT_BUCKET; i++){
37345     p = pcacheMergeDirtyList(p, a[i]);
37346   }
37347   return p;
37348 }
37349 
37350 /*
37351 ** Return a list of all dirty pages in the cache, sorted by page number.
37352 */
37353 SQLITE_PRIVATE PgHdr *sqlite3PcacheDirtyList(PCache *pCache){
37354   PgHdr *p;
37355   for(p=pCache->pDirty; p; p=p->pDirtyNext){
37356     p->pDirty = p->pDirtyNext;
37357   }
37358   return pcacheSortDirtyList(pCache->pDirty);
37359 }
37360 
37361 /* 
37362 ** Return the total number of referenced pages held by the cache.
37363 */
37364 SQLITE_PRIVATE int sqlite3PcacheRefCount(PCache *pCache){
37365   return pCache->nRef;
37366 }
37367 
37368 /*
37369 ** Return the number of references to the page supplied as an argument.
37370 */
37371 SQLITE_PRIVATE int sqlite3PcachePageRefcount(PgHdr *p){
37372   return p->nRef;
37373 }
37374 
37375 /* 
37376 ** Return the total number of pages in the cache.
37377 */
37378 SQLITE_PRIVATE int sqlite3PcachePagecount(PCache *pCache){
37379   int nPage = 0;
37380   if( pCache->pCache ){
37381     nPage = sqlite3GlobalConfig.pcache2.xPagecount(pCache->pCache);
37382   }
37383   return nPage;
37384 }
37385 
37386 #ifdef SQLITE_TEST
37387 /*
37388 ** Get the suggested cache-size value.
37389 */
37390 SQLITE_PRIVATE int sqlite3PcacheGetCachesize(PCache *pCache){
37391   return numberOfCachePages(pCache);
37392 }
37393 #endif
37394 
37395 /*
37396 ** Set the suggested cache-size value.
37397 */
37398 SQLITE_PRIVATE void sqlite3PcacheSetCachesize(PCache *pCache, int mxPage){
37399   pCache->szCache = mxPage;
37400   if( pCache->pCache ){
37401     sqlite3GlobalConfig.pcache2.xCachesize(pCache->pCache,
37402                                            numberOfCachePages(pCache));
37403   }
37404 }
37405 
37406 /*
37407 ** Free up as much memory as possible from the page cache.
37408 */
37409 SQLITE_PRIVATE void sqlite3PcacheShrink(PCache *pCache){
37410   if( pCache->pCache ){
37411     sqlite3GlobalConfig.pcache2.xShrink(pCache->pCache);
37412   }
37413 }
37414 
37415 #if defined(SQLITE_CHECK_PAGES) || defined(SQLITE_DEBUG)
37416 /*
37417 ** For all dirty pages currently in the cache, invoke the specified
37418 ** callback. This is only used if the SQLITE_CHECK_PAGES macro is
37419 ** defined.
37420 */
37421 SQLITE_PRIVATE void sqlite3PcacheIterateDirty(PCache *pCache, void (*xIter)(PgHdr *)){
37422   PgHdr *pDirty;
37423   for(pDirty=pCache->pDirty; pDirty; pDirty=pDirty->pDirtyNext){
37424     xIter(pDirty);
37425   }
37426 }
37427 #endif
37428 
37429 /************** End of pcache.c **********************************************/
37430 /************** Begin file pcache1.c *****************************************/
37431 /*
37432 ** 2008 November 05
37433 **
37434 ** The author disclaims copyright to this source code.  In place of
37435 ** a legal notice, here is a blessing:
37436 **
37437 **    May you do good and not evil.
37438 **    May you find forgiveness for yourself and forgive others.
37439 **    May you share freely, never taking more than you give.
37440 **
37441 *************************************************************************
37442 **
37443 ** This file implements the default page cache implementation (the
37444 ** sqlite3_pcache interface). It also contains part of the implementation
37445 ** of the SQLITE_CONFIG_PAGECACHE and sqlite3_release_memory() features.
37446 ** If the default page cache implementation is overriden, then neither of
37447 ** these two features are available.
37448 */
37449 
37450 
37451 typedef struct PCache1 PCache1;
37452 typedef struct PgHdr1 PgHdr1;
37453 typedef struct PgFreeslot PgFreeslot;
37454 typedef struct PGroup PGroup;
37455 
37456 /* Each page cache (or PCache) belongs to a PGroup.  A PGroup is a set 
37457 ** of one or more PCaches that are able to recycle each others unpinned
37458 ** pages when they are under memory pressure.  A PGroup is an instance of
37459 ** the following object.
37460 **
37461 ** This page cache implementation works in one of two modes:
37462 **
37463 **   (1)  Every PCache is the sole member of its own PGroup.  There is
37464 **        one PGroup per PCache.
37465 **
37466 **   (2)  There is a single global PGroup that all PCaches are a member
37467 **        of.
37468 **
37469 ** Mode 1 uses more memory (since PCache instances are not able to rob
37470 ** unused pages from other PCaches) but it also operates without a mutex,
37471 ** and is therefore often faster.  Mode 2 requires a mutex in order to be
37472 ** threadsafe, but recycles pages more efficiently.
37473 **
37474 ** For mode (1), PGroup.mutex is NULL.  For mode (2) there is only a single
37475 ** PGroup which is the pcache1.grp global variable and its mutex is
37476 ** SQLITE_MUTEX_STATIC_LRU.
37477 */
37478 struct PGroup {
37479   sqlite3_mutex *mutex;          /* MUTEX_STATIC_LRU or NULL */
37480   unsigned int nMaxPage;         /* Sum of nMax for purgeable caches */
37481   unsigned int nMinPage;         /* Sum of nMin for purgeable caches */
37482   unsigned int mxPinned;         /* nMaxpage + 10 - nMinPage */
37483   unsigned int nCurrentPage;     /* Number of purgeable pages allocated */
37484   PgHdr1 *pLruHead, *pLruTail;   /* LRU list of unpinned pages */
37485 };
37486 
37487 /* Each page cache is an instance of the following object.  Every
37488 ** open database file (including each in-memory database and each
37489 ** temporary or transient database) has a single page cache which
37490 ** is an instance of this object.
37491 **
37492 ** Pointers to structures of this type are cast and returned as 
37493 ** opaque sqlite3_pcache* handles.
37494 */
37495 struct PCache1 {
37496   /* Cache configuration parameters. Page size (szPage) and the purgeable
37497   ** flag (bPurgeable) are set when the cache is created. nMax may be 
37498   ** modified at any time by a call to the pcache1Cachesize() method.
37499   ** The PGroup mutex must be held when accessing nMax.
37500   */
37501   PGroup *pGroup;                     /* PGroup this cache belongs to */
37502   int szPage;                         /* Size of allocated pages in bytes */
37503   int szExtra;                        /* Size of extra space in bytes */
37504   int bPurgeable;                     /* True if cache is purgeable */
37505   unsigned int nMin;                  /* Minimum number of pages reserved */
37506   unsigned int nMax;                  /* Configured "cache_size" value */
37507   unsigned int n90pct;                /* nMax*9/10 */
37508   unsigned int iMaxKey;               /* Largest key seen since xTruncate() */
37509 
37510   /* Hash table of all pages. The following variables may only be accessed
37511   ** when the accessor is holding the PGroup mutex.
37512   */
37513   unsigned int nRecyclable;           /* Number of pages in the LRU list */
37514   unsigned int nPage;                 /* Total number of pages in apHash */
37515   unsigned int nHash;                 /* Number of slots in apHash[] */
37516   PgHdr1 **apHash;                    /* Hash table for fast lookup by key */
37517 };
37518 
37519 /*
37520 ** Each cache entry is represented by an instance of the following 
37521 ** structure. Unless SQLITE_PCACHE_SEPARATE_HEADER is defined, a buffer of
37522 ** PgHdr1.pCache->szPage bytes is allocated directly before this structure 
37523 ** in memory.
37524 */
37525 struct PgHdr1 {
37526   sqlite3_pcache_page page;
37527   unsigned int iKey;             /* Key value (page number) */
37528   PgHdr1 *pNext;                 /* Next in hash table chain */
37529   PCache1 *pCache;               /* Cache that currently owns this page */
37530   PgHdr1 *pLruNext;              /* Next in LRU list of unpinned pages */
37531   PgHdr1 *pLruPrev;              /* Previous in LRU list of unpinned pages */
37532 };
37533 
37534 /*
37535 ** Free slots in the allocator used to divide up the buffer provided using
37536 ** the SQLITE_CONFIG_PAGECACHE mechanism.
37537 */
37538 struct PgFreeslot {
37539   PgFreeslot *pNext;  /* Next free slot */
37540 };
37541 
37542 /*
37543 ** Global data used by this cache.
37544 */
37545 static SQLITE_WSD struct PCacheGlobal {
37546   PGroup grp;                    /* The global PGroup for mode (2) */
37547 
37548   /* Variables related to SQLITE_CONFIG_PAGECACHE settings.  The
37549   ** szSlot, nSlot, pStart, pEnd, nReserve, and isInit values are all
37550   ** fixed at sqlite3_initialize() time and do not require mutex protection.
37551   ** The nFreeSlot and pFree values do require mutex protection.
37552   */
37553   int isInit;                    /* True if initialized */
37554   int szSlot;                    /* Size of each free slot */
37555   int nSlot;                     /* The number of pcache slots */
37556   int nReserve;                  /* Try to keep nFreeSlot above this */
37557   void *pStart, *pEnd;           /* Bounds of pagecache malloc range */
37558   /* Above requires no mutex.  Use mutex below for variable that follow. */
37559   sqlite3_mutex *mutex;          /* Mutex for accessing the following: */
37560   PgFreeslot *pFree;             /* Free page blocks */
37561   int nFreeSlot;                 /* Number of unused pcache slots */
37562   /* The following value requires a mutex to change.  We skip the mutex on
37563   ** reading because (1) most platforms read a 32-bit integer atomically and
37564   ** (2) even if an incorrect value is read, no great harm is done since this
37565   ** is really just an optimization. */
37566   int bUnderPressure;            /* True if low on PAGECACHE memory */
37567 } pcache1_g;
37568 
37569 /*
37570 ** All code in this file should access the global structure above via the
37571 ** alias "pcache1". This ensures that the WSD emulation is used when
37572 ** compiling for systems that do not support real WSD.
37573 */
37574 #define pcache1 (GLOBAL(struct PCacheGlobal, pcache1_g))
37575 
37576 /*
37577 ** Macros to enter and leave the PCache LRU mutex.
37578 */
37579 #define pcache1EnterMutex(X) sqlite3_mutex_enter((X)->mutex)
37580 #define pcache1LeaveMutex(X) sqlite3_mutex_leave((X)->mutex)
37581 
37582 /******************************************************************************/
37583 /******** Page Allocation/SQLITE_CONFIG_PCACHE Related Functions **************/
37584 
37585 /*
37586 ** This function is called during initialization if a static buffer is 
37587 ** supplied to use for the page-cache by passing the SQLITE_CONFIG_PAGECACHE
37588 ** verb to sqlite3_config(). Parameter pBuf points to an allocation large
37589 ** enough to contain 'n' buffers of 'sz' bytes each.
37590 **
37591 ** This routine is called from sqlite3_initialize() and so it is guaranteed
37592 ** to be serialized already.  There is no need for further mutexing.
37593 */
37594 SQLITE_PRIVATE void sqlite3PCacheBufferSetup(void *pBuf, int sz, int n){
37595   if( pcache1.isInit ){
37596     PgFreeslot *p;
37597     sz = ROUNDDOWN8(sz);
37598     pcache1.szSlot = sz;
37599     pcache1.nSlot = pcache1.nFreeSlot = n;
37600     pcache1.nReserve = n>90 ? 10 : (n/10 + 1);
37601     pcache1.pStart = pBuf;
37602     pcache1.pFree = 0;
37603     pcache1.bUnderPressure = 0;
37604     while( n-- ){
37605       p = (PgFreeslot*)pBuf;
37606       p->pNext = pcache1.pFree;
37607       pcache1.pFree = p;
37608       pBuf = (void*)&((char*)pBuf)[sz];
37609     }
37610     pcache1.pEnd = pBuf;
37611   }
37612 }
37613 
37614 /*
37615 ** Malloc function used within this file to allocate space from the buffer
37616 ** configured using sqlite3_config(SQLITE_CONFIG_PAGECACHE) option. If no 
37617 ** such buffer exists or there is no space left in it, this function falls 
37618 ** back to sqlite3Malloc().
37619 **
37620 ** Multiple threads can run this routine at the same time.  Global variables
37621 ** in pcache1 need to be protected via mutex.
37622 */
37623 static void *pcache1Alloc(int nByte){
37624   void *p = 0;
37625   assert( sqlite3_mutex_notheld(pcache1.grp.mutex) );
37626   sqlite3StatusSet(SQLITE_STATUS_PAGECACHE_SIZE, nByte);
37627   if( nByte<=pcache1.szSlot ){
37628     sqlite3_mutex_enter(pcache1.mutex);
37629     p = (PgHdr1 *)pcache1.pFree;
37630     if( p ){
37631       pcache1.pFree = pcache1.pFree->pNext;
37632       pcache1.nFreeSlot--;
37633       pcache1.bUnderPressure = pcache1.nFreeSlot<pcache1.nReserve;
37634       assert( pcache1.nFreeSlot>=0 );
37635       sqlite3StatusAdd(SQLITE_STATUS_PAGECACHE_USED, 1);
37636     }
37637     sqlite3_mutex_leave(pcache1.mutex);
37638   }
37639   if( p==0 ){
37640     /* Memory is not available in the SQLITE_CONFIG_PAGECACHE pool.  Get
37641     ** it from sqlite3Malloc instead.
37642     */
37643     p = sqlite3Malloc(nByte);
37644 #ifndef SQLITE_DISABLE_PAGECACHE_OVERFLOW_STATS
37645     if( p ){
37646       int sz = sqlite3MallocSize(p);
37647       sqlite3_mutex_enter(pcache1.mutex);
37648       sqlite3StatusAdd(SQLITE_STATUS_PAGECACHE_OVERFLOW, sz);
37649       sqlite3_mutex_leave(pcache1.mutex);
37650     }
37651 #endif
37652     sqlite3MemdebugSetType(p, MEMTYPE_PCACHE);
37653   }
37654   return p;
37655 }
37656 
37657 /*
37658 ** Free an allocated buffer obtained from pcache1Alloc().
37659 */
37660 static int pcache1Free(void *p){
37661   int nFreed = 0;
37662   if( p==0 ) return 0;
37663   if( p>=pcache1.pStart && p<pcache1.pEnd ){
37664     PgFreeslot *pSlot;
37665     sqlite3_mutex_enter(pcache1.mutex);
37666     sqlite3StatusAdd(SQLITE_STATUS_PAGECACHE_USED, -1);
37667     pSlot = (PgFreeslot*)p;
37668     pSlot->pNext = pcache1.pFree;
37669     pcache1.pFree = pSlot;
37670     pcache1.nFreeSlot++;
37671     pcache1.bUnderPressure = pcache1.nFreeSlot<pcache1.nReserve;
37672     assert( pcache1.nFreeSlot<=pcache1.nSlot );
37673     sqlite3_mutex_leave(pcache1.mutex);
37674   }else{
37675     assert( sqlite3MemdebugHasType(p, MEMTYPE_PCACHE) );
37676     sqlite3MemdebugSetType(p, MEMTYPE_HEAP);
37677     nFreed = sqlite3MallocSize(p);
37678 #ifndef SQLITE_DISABLE_PAGECACHE_OVERFLOW_STATS
37679     sqlite3_mutex_enter(pcache1.mutex);
37680     sqlite3StatusAdd(SQLITE_STATUS_PAGECACHE_OVERFLOW, -nFreed);
37681     sqlite3_mutex_leave(pcache1.mutex);
37682 #endif
37683     sqlite3_free(p);
37684   }
37685   return nFreed;
37686 }
37687 
37688 #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
37689 /*
37690 ** Return the size of a pcache allocation
37691 */
37692 static int pcache1MemSize(void *p){
37693   if( p>=pcache1.pStart && p<pcache1.pEnd ){
37694     return pcache1.szSlot;
37695   }else{
37696     int iSize;
37697     assert( sqlite3MemdebugHasType(p, MEMTYPE_PCACHE) );
37698     sqlite3MemdebugSetType(p, MEMTYPE_HEAP);
37699     iSize = sqlite3MallocSize(p);
37700     sqlite3MemdebugSetType(p, MEMTYPE_PCACHE);
37701     return iSize;
37702   }
37703 }
37704 #endif /* SQLITE_ENABLE_MEMORY_MANAGEMENT */
37705 
37706 /*
37707 ** Allocate a new page object initially associated with cache pCache.
37708 */
37709 static PgHdr1 *pcache1AllocPage(PCache1 *pCache){
37710   PgHdr1 *p = 0;
37711   void *pPg;
37712 
37713   /* The group mutex must be released before pcache1Alloc() is called. This
37714   ** is because it may call sqlite3_release_memory(), which assumes that 
37715   ** this mutex is not held. */
37716   assert( sqlite3_mutex_held(pCache->pGroup->mutex) );
37717   pcache1LeaveMutex(pCache->pGroup);
37718 #ifdef SQLITE_PCACHE_SEPARATE_HEADER
37719   pPg = pcache1Alloc(pCache->szPage);
37720   p = sqlite3Malloc(sizeof(PgHdr1) + pCache->szExtra);
37721   if( !pPg || !p ){
37722     pcache1Free(pPg);
37723     sqlite3_free(p);
37724     pPg = 0;
37725   }
37726 #else
37727   pPg = pcache1Alloc(sizeof(PgHdr1) + pCache->szPage + pCache->szExtra);
37728   p = (PgHdr1 *)&((u8 *)pPg)[pCache->szPage];
37729 #endif
37730   pcache1EnterMutex(pCache->pGroup);
37731 
37732   if( pPg ){
37733     p->page.pBuf = pPg;
37734     p->page.pExtra = &p[1];
37735     if( pCache->bPurgeable ){
37736       pCache->pGroup->nCurrentPage++;
37737     }
37738     return p;
37739   }
37740   return 0;
37741 }
37742 
37743 /*
37744 ** Free a page object allocated by pcache1AllocPage().
37745 **
37746 ** The pointer is allowed to be NULL, which is prudent.  But it turns out
37747 ** that the current implementation happens to never call this routine
37748 ** with a NULL pointer, so we mark the NULL test with ALWAYS().
37749 */
37750 static void pcache1FreePage(PgHdr1 *p){
37751   if( ALWAYS(p) ){
37752     PCache1 *pCache = p->pCache;
37753     assert( sqlite3_mutex_held(p->pCache->pGroup->mutex) );
37754     pcache1Free(p->page.pBuf);
37755 #ifdef SQLITE_PCACHE_SEPARATE_HEADER
37756     sqlite3_free(p);
37757 #endif
37758     if( pCache->bPurgeable ){
37759       pCache->pGroup->nCurrentPage--;
37760     }
37761   }
37762 }
37763 
37764 /*
37765 ** Malloc function used by SQLite to obtain space from the buffer configured
37766 ** using sqlite3_config(SQLITE_CONFIG_PAGECACHE) option. If no such buffer
37767 ** exists, this function falls back to sqlite3Malloc().
37768 */
37769 SQLITE_PRIVATE void *sqlite3PageMalloc(int sz){
37770   return pcache1Alloc(sz);
37771 }
37772 
37773 /*
37774 ** Free an allocated buffer obtained from sqlite3PageMalloc().
37775 */
37776 SQLITE_PRIVATE void sqlite3PageFree(void *p){
37777   pcache1Free(p);
37778 }
37779 
37780 
37781 /*
37782 ** Return true if it desirable to avoid allocating a new page cache
37783 ** entry.
37784 **
37785 ** If memory was allocated specifically to the page cache using
37786 ** SQLITE_CONFIG_PAGECACHE but that memory has all been used, then
37787 ** it is desirable to avoid allocating a new page cache entry because
37788 ** presumably SQLITE_CONFIG_PAGECACHE was suppose to be sufficient
37789 ** for all page cache needs and we should not need to spill the
37790 ** allocation onto the heap.
37791 **
37792 ** Or, the heap is used for all page cache memory but the heap is
37793 ** under memory pressure, then again it is desirable to avoid
37794 ** allocating a new page cache entry in order to avoid stressing
37795 ** the heap even further.
37796 */
37797 static int pcache1UnderMemoryPressure(PCache1 *pCache){
37798   if( pcache1.nSlot && (pCache->szPage+pCache->szExtra)<=pcache1.szSlot ){
37799     return pcache1.bUnderPressure;
37800   }else{
37801     return sqlite3HeapNearlyFull();
37802   }
37803 }
37804 
37805 /******************************************************************************/
37806 /******** General Implementation Functions ************************************/
37807 
37808 /*
37809 ** This function is used to resize the hash table used by the cache passed
37810 ** as the first argument.
37811 **
37812 ** The PCache mutex must be held when this function is called.
37813 */
37814 static int pcache1ResizeHash(PCache1 *p){
37815   PgHdr1 **apNew;
37816   unsigned int nNew;
37817   unsigned int i;
37818 
37819   assert( sqlite3_mutex_held(p->pGroup->mutex) );
37820 
37821   nNew = p->nHash*2;
37822   if( nNew<256 ){
37823     nNew = 256;
37824   }
37825 
37826   pcache1LeaveMutex(p->pGroup);
37827   if( p->nHash ){ sqlite3BeginBenignMalloc(); }
37828   apNew = (PgHdr1 **)sqlite3MallocZero(sizeof(PgHdr1 *)*nNew);
37829   if( p->nHash ){ sqlite3EndBenignMalloc(); }
37830   pcache1EnterMutex(p->pGroup);
37831   if( apNew ){
37832     for(i=0; i<p->nHash; i++){
37833       PgHdr1 *pPage;
37834       PgHdr1 *pNext = p->apHash[i];
37835       while( (pPage = pNext)!=0 ){
37836         unsigned int h = pPage->iKey % nNew;
37837         pNext = pPage->pNext;
37838         pPage->pNext = apNew[h];
37839         apNew[h] = pPage;
37840       }
37841     }
37842     sqlite3_free(p->apHash);
37843     p->apHash = apNew;
37844     p->nHash = nNew;
37845   }
37846 
37847   return (p->apHash ? SQLITE_OK : SQLITE_NOMEM);
37848 }
37849 
37850 /*
37851 ** This function is used internally to remove the page pPage from the 
37852 ** PGroup LRU list, if is part of it. If pPage is not part of the PGroup
37853 ** LRU list, then this function is a no-op.
37854 **
37855 ** The PGroup mutex must be held when this function is called.
37856 **
37857 ** If pPage is NULL then this routine is a no-op.
37858 */
37859 static void pcache1PinPage(PgHdr1 *pPage){
37860   PCache1 *pCache;
37861   PGroup *pGroup;
37862 
37863   if( pPage==0 ) return;
37864   pCache = pPage->pCache;
37865   pGroup = pCache->pGroup;
37866   assert( sqlite3_mutex_held(pGroup->mutex) );
37867   if( pPage->pLruNext || pPage==pGroup->pLruTail ){
37868     if( pPage->pLruPrev ){
37869       pPage->pLruPrev->pLruNext = pPage->pLruNext;
37870     }
37871     if( pPage->pLruNext ){
37872       pPage->pLruNext->pLruPrev = pPage->pLruPrev;
37873     }
37874     if( pGroup->pLruHead==pPage ){
37875       pGroup->pLruHead = pPage->pLruNext;
37876     }
37877     if( pGroup->pLruTail==pPage ){
37878       pGroup->pLruTail = pPage->pLruPrev;
37879     }
37880     pPage->pLruNext = 0;
37881     pPage->pLruPrev = 0;
37882     pPage->pCache->nRecyclable--;
37883   }
37884 }
37885 
37886 
37887 /*
37888 ** Remove the page supplied as an argument from the hash table 
37889 ** (PCache1.apHash structure) that it is currently stored in.
37890 **
37891 ** The PGroup mutex must be held when this function is called.
37892 */
37893 static void pcache1RemoveFromHash(PgHdr1 *pPage){
37894   unsigned int h;
37895   PCache1 *pCache = pPage->pCache;
37896   PgHdr1 **pp;
37897 
37898   assert( sqlite3_mutex_held(pCache->pGroup->mutex) );
37899   h = pPage->iKey % pCache->nHash;
37900   for(pp=&pCache->apHash[h]; (*pp)!=pPage; pp=&(*pp)->pNext);
37901   *pp = (*pp)->pNext;
37902 
37903   pCache->nPage--;
37904 }
37905 
37906 /*
37907 ** If there are currently more than nMaxPage pages allocated, try
37908 ** to recycle pages to reduce the number allocated to nMaxPage.
37909 */
37910 static void pcache1EnforceMaxPage(PGroup *pGroup){
37911   assert( sqlite3_mutex_held(pGroup->mutex) );
37912   while( pGroup->nCurrentPage>pGroup->nMaxPage && pGroup->pLruTail ){
37913     PgHdr1 *p = pGroup->pLruTail;
37914     assert( p->pCache->pGroup==pGroup );
37915     pcache1PinPage(p);
37916     pcache1RemoveFromHash(p);
37917     pcache1FreePage(p);
37918   }
37919 }
37920 
37921 /*
37922 ** Discard all pages from cache pCache with a page number (key value) 
37923 ** greater than or equal to iLimit. Any pinned pages that meet this 
37924 ** criteria are unpinned before they are discarded.
37925 **
37926 ** The PCache mutex must be held when this function is called.
37927 */
37928 static void pcache1TruncateUnsafe(
37929   PCache1 *pCache,             /* The cache to truncate */
37930   unsigned int iLimit          /* Drop pages with this pgno or larger */
37931 ){
37932   TESTONLY( unsigned int nPage = 0; )  /* To assert pCache->nPage is correct */
37933   unsigned int h;
37934   assert( sqlite3_mutex_held(pCache->pGroup->mutex) );
37935   for(h=0; h<pCache->nHash; h++){
37936     PgHdr1 **pp = &pCache->apHash[h]; 
37937     PgHdr1 *pPage;
37938     while( (pPage = *pp)!=0 ){
37939       if( pPage->iKey>=iLimit ){
37940         pCache->nPage--;
37941         *pp = pPage->pNext;
37942         pcache1PinPage(pPage);
37943         pcache1FreePage(pPage);
37944       }else{
37945         pp = &pPage->pNext;
37946         TESTONLY( nPage++; )
37947       }
37948     }
37949   }
37950   assert( pCache->nPage==nPage );
37951 }
37952 
37953 /******************************************************************************/
37954 /******** sqlite3_pcache Methods **********************************************/
37955 
37956 /*
37957 ** Implementation of the sqlite3_pcache.xInit method.
37958 */
37959 static int pcache1Init(void *NotUsed){
37960   UNUSED_PARAMETER(NotUsed);
37961   assert( pcache1.isInit==0 );
37962   memset(&pcache1, 0, sizeof(pcache1));
37963   if( sqlite3GlobalConfig.bCoreMutex ){
37964     pcache1.grp.mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_LRU);
37965     pcache1.mutex = sqlite3_mutex_alloc(SQLITE_MUTEX_STATIC_PMEM);
37966   }
37967   pcache1.grp.mxPinned = 10;
37968   pcache1.isInit = 1;
37969   return SQLITE_OK;
37970 }
37971 
37972 /*
37973 ** Implementation of the sqlite3_pcache.xShutdown method.
37974 ** Note that the static mutex allocated in xInit does 
37975 ** not need to be freed.
37976 */
37977 static void pcache1Shutdown(void *NotUsed){
37978   UNUSED_PARAMETER(NotUsed);
37979   assert( pcache1.isInit!=0 );
37980   memset(&pcache1, 0, sizeof(pcache1));
37981 }
37982 
37983 /*
37984 ** Implementation of the sqlite3_pcache.xCreate method.
37985 **
37986 ** Allocate a new cache.
37987 */
37988 static sqlite3_pcache *pcache1Create(int szPage, int szExtra, int bPurgeable){
37989   PCache1 *pCache;      /* The newly created page cache */
37990   PGroup *pGroup;       /* The group the new page cache will belong to */
37991   int sz;               /* Bytes of memory required to allocate the new cache */
37992 
37993   /*
37994   ** The separateCache variable is true if each PCache has its own private
37995   ** PGroup.  In other words, separateCache is true for mode (1) where no
37996   ** mutexing is required.
37997   **
37998   **   *  Always use a unified cache (mode-2) if ENABLE_MEMORY_MANAGEMENT
37999   **
38000   **   *  Always use a unified cache in single-threaded applications
38001   **
38002   **   *  Otherwise (if multi-threaded and ENABLE_MEMORY_MANAGEMENT is off)
38003   **      use separate caches (mode-1)
38004   */
38005 #if defined(SQLITE_ENABLE_MEMORY_MANAGEMENT) || SQLITE_THREADSAFE==0
38006   const int separateCache = 0;
38007 #else
38008   int separateCache = sqlite3GlobalConfig.bCoreMutex>0;
38009 #endif
38010 
38011   assert( (szPage & (szPage-1))==0 && szPage>=512 && szPage<=65536 );
38012   assert( szExtra < 300 );
38013 
38014   sz = sizeof(PCache1) + sizeof(PGroup)*separateCache;
38015   pCache = (PCache1 *)sqlite3MallocZero(sz);
38016   if( pCache ){
38017     if( separateCache ){
38018       pGroup = (PGroup*)&pCache[1];
38019       pGroup->mxPinned = 10;
38020     }else{
38021       pGroup = &pcache1.grp;
38022     }
38023     pCache->pGroup = pGroup;
38024     pCache->szPage = szPage;
38025     pCache->szExtra = szExtra;
38026     pCache->bPurgeable = (bPurgeable ? 1 : 0);
38027     if( bPurgeable ){
38028       pCache->nMin = 10;
38029       pcache1EnterMutex(pGroup);
38030       pGroup->nMinPage += pCache->nMin;
38031       pGroup->mxPinned = pGroup->nMaxPage + 10 - pGroup->nMinPage;
38032       pcache1LeaveMutex(pGroup);
38033     }
38034   }
38035   return (sqlite3_pcache *)pCache;
38036 }
38037 
38038 /*
38039 ** Implementation of the sqlite3_pcache.xCachesize method. 
38040 **
38041 ** Configure the cache_size limit for a cache.
38042 */
38043 static void pcache1Cachesize(sqlite3_pcache *p, int nMax){
38044   PCache1 *pCache = (PCache1 *)p;
38045   if( pCache->bPurgeable ){
38046     PGroup *pGroup = pCache->pGroup;
38047     pcache1EnterMutex(pGroup);
38048     pGroup->nMaxPage += (nMax - pCache->nMax);
38049     pGroup->mxPinned = pGroup->nMaxPage + 10 - pGroup->nMinPage;
38050     pCache->nMax = nMax;
38051     pCache->n90pct = pCache->nMax*9/10;
38052     pcache1EnforceMaxPage(pGroup);
38053     pcache1LeaveMutex(pGroup);
38054   }
38055 }
38056 
38057 /*
38058 ** Implementation of the sqlite3_pcache.xShrink method. 
38059 **
38060 ** Free up as much memory as possible.
38061 */
38062 static void pcache1Shrink(sqlite3_pcache *p){
38063   PCache1 *pCache = (PCache1*)p;
38064   if( pCache->bPurgeable ){
38065     PGroup *pGroup = pCache->pGroup;
38066     int savedMaxPage;
38067     pcache1EnterMutex(pGroup);
38068     savedMaxPage = pGroup->nMaxPage;
38069     pGroup->nMaxPage = 0;
38070     pcache1EnforceMaxPage(pGroup);
38071     pGroup->nMaxPage = savedMaxPage;
38072     pcache1LeaveMutex(pGroup);
38073   }
38074 }
38075 
38076 /*
38077 ** Implementation of the sqlite3_pcache.xPagecount method. 
38078 */
38079 static int pcache1Pagecount(sqlite3_pcache *p){
38080   int n;
38081   PCache1 *pCache = (PCache1*)p;
38082   pcache1EnterMutex(pCache->pGroup);
38083   n = pCache->nPage;
38084   pcache1LeaveMutex(pCache->pGroup);
38085   return n;
38086 }
38087 
38088 /*
38089 ** Implementation of the sqlite3_pcache.xFetch method. 
38090 **
38091 ** Fetch a page by key value.
38092 **
38093 ** Whether or not a new page may be allocated by this function depends on
38094 ** the value of the createFlag argument.  0 means do not allocate a new
38095 ** page.  1 means allocate a new page if space is easily available.  2 
38096 ** means to try really hard to allocate a new page.
38097 **
38098 ** For a non-purgeable cache (a cache used as the storage for an in-memory
38099 ** database) there is really no difference between createFlag 1 and 2.  So
38100 ** the calling function (pcache.c) will never have a createFlag of 1 on
38101 ** a non-purgeable cache.
38102 **
38103 ** There are three different approaches to obtaining space for a page,
38104 ** depending on the value of parameter createFlag (which may be 0, 1 or 2).
38105 **
38106 **   1. Regardless of the value of createFlag, the cache is searched for a 
38107 **      copy of the requested page. If one is found, it is returned.
38108 **
38109 **   2. If createFlag==0 and the page is not already in the cache, NULL is
38110 **      returned.
38111 **
38112 **   3. If createFlag is 1, and the page is not already in the cache, then
38113 **      return NULL (do not allocate a new page) if any of the following
38114 **      conditions are true:
38115 **
38116 **       (a) the number of pages pinned by the cache is greater than
38117 **           PCache1.nMax, or
38118 **
38119 **       (b) the number of pages pinned by the cache is greater than
38120 **           the sum of nMax for all purgeable caches, less the sum of 
38121 **           nMin for all other purgeable caches, or
38122 **
38123 **   4. If none of the first three conditions apply and the cache is marked
38124 **      as purgeable, and if one of the following is true:
38125 **
38126 **       (a) The number of pages allocated for the cache is already 
38127 **           PCache1.nMax, or
38128 **
38129 **       (b) The number of pages allocated for all purgeable caches is
38130 **           already equal to or greater than the sum of nMax for all
38131 **           purgeable caches,
38132 **
38133 **       (c) The system is under memory pressure and wants to avoid
38134 **           unnecessary pages cache entry allocations
38135 **
38136 **      then attempt to recycle a page from the LRU list. If it is the right
38137 **      size, return the recycled buffer. Otherwise, free the buffer and
38138 **      proceed to step 5. 
38139 **
38140 **   5. Otherwise, allocate and return a new page buffer.
38141 */
38142 static sqlite3_pcache_page *pcache1Fetch(
38143   sqlite3_pcache *p, 
38144   unsigned int iKey, 
38145   int createFlag
38146 ){
38147   unsigned int nPinned;
38148   PCache1 *pCache = (PCache1 *)p;
38149   PGroup *pGroup;
38150   PgHdr1 *pPage = 0;
38151 
38152   assert( pCache->bPurgeable || createFlag!=1 );
38153   assert( pCache->bPurgeable || pCache->nMin==0 );
38154   assert( pCache->bPurgeable==0 || pCache->nMin==10 );
38155   assert( pCache->nMin==0 || pCache->bPurgeable );
38156   pcache1EnterMutex(pGroup = pCache->pGroup);
38157 
38158   /* Step 1: Search the hash table for an existing entry. */
38159   if( pCache->nHash>0 ){
38160     unsigned int h = iKey % pCache->nHash;
38161     for(pPage=pCache->apHash[h]; pPage&&pPage->iKey!=iKey; pPage=pPage->pNext);
38162   }
38163 
38164   /* Step 2: Abort if no existing page is found and createFlag is 0 */
38165   if( pPage || createFlag==0 ){
38166     pcache1PinPage(pPage);
38167     goto fetch_out;
38168   }
38169 
38170   /* The pGroup local variable will normally be initialized by the
38171   ** pcache1EnterMutex() macro above.  But if SQLITE_MUTEX_OMIT is defined,
38172   ** then pcache1EnterMutex() is a no-op, so we have to initialize the
38173   ** local variable here.  Delaying the initialization of pGroup is an
38174   ** optimization:  The common case is to exit the module before reaching
38175   ** this point.
38176   */
38177 #ifdef SQLITE_MUTEX_OMIT
38178   pGroup = pCache->pGroup;
38179 #endif
38180 
38181   /* Step 3: Abort if createFlag is 1 but the cache is nearly full */
38182   assert( pCache->nPage >= pCache->nRecyclable );
38183   nPinned = pCache->nPage - pCache->nRecyclable;
38184   assert( pGroup->mxPinned == pGroup->nMaxPage + 10 - pGroup->nMinPage );
38185   assert( pCache->n90pct == pCache->nMax*9/10 );
38186   if( createFlag==1 && (
38187         nPinned>=pGroup->mxPinned
38188      || nPinned>=pCache->n90pct
38189      || pcache1UnderMemoryPressure(pCache)
38190   )){
38191     goto fetch_out;
38192   }
38193 
38194   if( pCache->nPage>=pCache->nHash && pcache1ResizeHash(pCache) ){
38195     goto fetch_out;
38196   }
38197   assert( pCache->nHash>0 && pCache->apHash );
38198 
38199   /* Step 4. Try to recycle a page. */
38200   if( pCache->bPurgeable && pGroup->pLruTail && (
38201          (pCache->nPage+1>=pCache->nMax)
38202       || pGroup->nCurrentPage>=pGroup->nMaxPage
38203       || pcache1UnderMemoryPressure(pCache)
38204   )){
38205     PCache1 *pOther;
38206     pPage = pGroup->pLruTail;
38207     pcache1RemoveFromHash(pPage);
38208     pcache1PinPage(pPage);
38209     pOther = pPage->pCache;
38210 
38211     /* We want to verify that szPage and szExtra are the same for pOther
38212     ** and pCache.  Assert that we can verify this by comparing sums. */
38213     assert( (pCache->szPage & (pCache->szPage-1))==0 && pCache->szPage>=512 );
38214     assert( pCache->szExtra<512 );
38215     assert( (pOther->szPage & (pOther->szPage-1))==0 && pOther->szPage>=512 );
38216     assert( pOther->szExtra<512 );
38217 
38218     if( pOther->szPage+pOther->szExtra != pCache->szPage+pCache->szExtra ){
38219       pcache1FreePage(pPage);
38220       pPage = 0;
38221     }else{
38222       pGroup->nCurrentPage -= (pOther->bPurgeable - pCache->bPurgeable);
38223     }
38224   }
38225 
38226   /* Step 5. If a usable page buffer has still not been found, 
38227   ** attempt to allocate a new one. 
38228   */
38229   if( !pPage ){
38230     if( createFlag==1 ) sqlite3BeginBenignMalloc();
38231     pPage = pcache1AllocPage(pCache);
38232     if( createFlag==1 ) sqlite3EndBenignMalloc();
38233   }
38234 
38235   if( pPage ){
38236     unsigned int h = iKey % pCache->nHash;
38237     pCache->nPage++;
38238     pPage->iKey = iKey;
38239     pPage->pNext = pCache->apHash[h];
38240     pPage->pCache = pCache;
38241     pPage->pLruPrev = 0;
38242     pPage->pLruNext = 0;
38243     *(void **)pPage->page.pExtra = 0;
38244     pCache->apHash[h] = pPage;
38245   }
38246 
38247 fetch_out:
38248   if( pPage && iKey>pCache->iMaxKey ){
38249     pCache->iMaxKey = iKey;
38250   }
38251   pcache1LeaveMutex(pGroup);
38252   return &pPage->page;
38253 }
38254 
38255 
38256 /*
38257 ** Implementation of the sqlite3_pcache.xUnpin method.
38258 **
38259 ** Mark a page as unpinned (eligible for asynchronous recycling).
38260 */
38261 static void pcache1Unpin(
38262   sqlite3_pcache *p, 
38263   sqlite3_pcache_page *pPg, 
38264   int reuseUnlikely
38265 ){
38266   PCache1 *pCache = (PCache1 *)p;
38267   PgHdr1 *pPage = (PgHdr1 *)pPg;
38268   PGroup *pGroup = pCache->pGroup;
38269  
38270   assert( pPage->pCache==pCache );
38271   pcache1EnterMutex(pGroup);
38272 
38273   /* It is an error to call this function if the page is already 
38274   ** part of the PGroup LRU list.
38275   */
38276   assert( pPage->pLruPrev==0 && pPage->pLruNext==0 );
38277   assert( pGroup->pLruHead!=pPage && pGroup->pLruTail!=pPage );
38278 
38279   if( reuseUnlikely || pGroup->nCurrentPage>pGroup->nMaxPage ){
38280     pcache1RemoveFromHash(pPage);
38281     pcache1FreePage(pPage);
38282   }else{
38283     /* Add the page to the PGroup LRU list. */
38284     if( pGroup->pLruHead ){
38285       pGroup->pLruHead->pLruPrev = pPage;
38286       pPage->pLruNext = pGroup->pLruHead;
38287       pGroup->pLruHead = pPage;
38288     }else{
38289       pGroup->pLruTail = pPage;
38290       pGroup->pLruHead = pPage;
38291     }
38292     pCache->nRecyclable++;
38293   }
38294 
38295   pcache1LeaveMutex(pCache->pGroup);
38296 }
38297 
38298 /*
38299 ** Implementation of the sqlite3_pcache.xRekey method. 
38300 */
38301 static void pcache1Rekey(
38302   sqlite3_pcache *p,
38303   sqlite3_pcache_page *pPg,
38304   unsigned int iOld,
38305   unsigned int iNew
38306 ){
38307   PCache1 *pCache = (PCache1 *)p;
38308   PgHdr1 *pPage = (PgHdr1 *)pPg;
38309   PgHdr1 **pp;
38310   unsigned int h; 
38311   assert( pPage->iKey==iOld );
38312   assert( pPage->pCache==pCache );
38313 
38314   pcache1EnterMutex(pCache->pGroup);
38315 
38316   h = iOld%pCache->nHash;
38317   pp = &pCache->apHash[h];
38318   while( (*pp)!=pPage ){
38319     pp = &(*pp)->pNext;
38320   }
38321   *pp = pPage->pNext;
38322 
38323   h = iNew%pCache->nHash;
38324   pPage->iKey = iNew;
38325   pPage->pNext = pCache->apHash[h];
38326   pCache->apHash[h] = pPage;
38327   if( iNew>pCache->iMaxKey ){
38328     pCache->iMaxKey = iNew;
38329   }
38330 
38331   pcache1LeaveMutex(pCache->pGroup);
38332 }
38333 
38334 /*
38335 ** Implementation of the sqlite3_pcache.xTruncate method. 
38336 **
38337 ** Discard all unpinned pages in the cache with a page number equal to
38338 ** or greater than parameter iLimit. Any pinned pages with a page number
38339 ** equal to or greater than iLimit are implicitly unpinned.
38340 */
38341 static void pcache1Truncate(sqlite3_pcache *p, unsigned int iLimit){
38342   PCache1 *pCache = (PCache1 *)p;
38343   pcache1EnterMutex(pCache->pGroup);
38344   if( iLimit<=pCache->iMaxKey ){
38345     pcache1TruncateUnsafe(pCache, iLimit);
38346     pCache->iMaxKey = iLimit-1;
38347   }
38348   pcache1LeaveMutex(pCache->pGroup);
38349 }
38350 
38351 /*
38352 ** Implementation of the sqlite3_pcache.xDestroy method. 
38353 **
38354 ** Destroy a cache allocated using pcache1Create().
38355 */
38356 static void pcache1Destroy(sqlite3_pcache *p){
38357   PCache1 *pCache = (PCache1 *)p;
38358   PGroup *pGroup = pCache->pGroup;
38359   assert( pCache->bPurgeable || (pCache->nMax==0 && pCache->nMin==0) );
38360   pcache1EnterMutex(pGroup);
38361   pcache1TruncateUnsafe(pCache, 0);
38362   assert( pGroup->nMaxPage >= pCache->nMax );
38363   pGroup->nMaxPage -= pCache->nMax;
38364   assert( pGroup->nMinPage >= pCache->nMin );
38365   pGroup->nMinPage -= pCache->nMin;
38366   pGroup->mxPinned = pGroup->nMaxPage + 10 - pGroup->nMinPage;
38367   pcache1EnforceMaxPage(pGroup);
38368   pcache1LeaveMutex(pGroup);
38369   sqlite3_free(pCache->apHash);
38370   sqlite3_free(pCache);
38371 }
38372 
38373 /*
38374 ** This function is called during initialization (sqlite3_initialize()) to
38375 ** install the default pluggable cache module, assuming the user has not
38376 ** already provided an alternative.
38377 */
38378 SQLITE_PRIVATE void sqlite3PCacheSetDefault(void){
38379   static const sqlite3_pcache_methods2 defaultMethods = {
38380     1,                       /* iVersion */
38381     0,                       /* pArg */
38382     pcache1Init,             /* xInit */
38383     pcache1Shutdown,         /* xShutdown */
38384     pcache1Create,           /* xCreate */
38385     pcache1Cachesize,        /* xCachesize */
38386     pcache1Pagecount,        /* xPagecount */
38387     pcache1Fetch,            /* xFetch */
38388     pcache1Unpin,            /* xUnpin */
38389     pcache1Rekey,            /* xRekey */
38390     pcache1Truncate,         /* xTruncate */
38391     pcache1Destroy,          /* xDestroy */
38392     pcache1Shrink            /* xShrink */
38393   };
38394   sqlite3_config(SQLITE_CONFIG_PCACHE2, &defaultMethods);
38395 }
38396 
38397 #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
38398 /*
38399 ** This function is called to free superfluous dynamically allocated memory
38400 ** held by the pager system. Memory in use by any SQLite pager allocated
38401 ** by the current thread may be sqlite3_free()ed.
38402 **
38403 ** nReq is the number of bytes of memory required. Once this much has
38404 ** been released, the function returns. The return value is the total number 
38405 ** of bytes of memory released.
38406 */
38407 SQLITE_PRIVATE int sqlite3PcacheReleaseMemory(int nReq){
38408   int nFree = 0;
38409   assert( sqlite3_mutex_notheld(pcache1.grp.mutex) );
38410   assert( sqlite3_mutex_notheld(pcache1.mutex) );
38411   if( pcache1.pStart==0 ){
38412     PgHdr1 *p;
38413     pcache1EnterMutex(&pcache1.grp);
38414     while( (nReq<0 || nFree<nReq) && ((p=pcache1.grp.pLruTail)!=0) ){
38415       nFree += pcache1MemSize(p->page.pBuf);
38416 #ifdef SQLITE_PCACHE_SEPARATE_HEADER
38417       nFree += sqlite3MemSize(p);
38418 #endif
38419       pcache1PinPage(p);
38420       pcache1RemoveFromHash(p);
38421       pcache1FreePage(p);
38422     }
38423     pcache1LeaveMutex(&pcache1.grp);
38424   }
38425   return nFree;
38426 }
38427 #endif /* SQLITE_ENABLE_MEMORY_MANAGEMENT */
38428 
38429 #ifdef SQLITE_TEST
38430 /*
38431 ** This function is used by test procedures to inspect the internal state
38432 ** of the global cache.
38433 */
38434 SQLITE_PRIVATE void sqlite3PcacheStats(
38435   int *pnCurrent,      /* OUT: Total number of pages cached */
38436   int *pnMax,          /* OUT: Global maximum cache size */
38437   int *pnMin,          /* OUT: Sum of PCache1.nMin for purgeable caches */
38438   int *pnRecyclable    /* OUT: Total number of pages available for recycling */
38439 ){
38440   PgHdr1 *p;
38441   int nRecyclable = 0;
38442   for(p=pcache1.grp.pLruHead; p; p=p->pLruNext){
38443     nRecyclable++;
38444   }
38445   *pnCurrent = pcache1.grp.nCurrentPage;
38446   *pnMax = (int)pcache1.grp.nMaxPage;
38447   *pnMin = (int)pcache1.grp.nMinPage;
38448   *pnRecyclable = nRecyclable;
38449 }
38450 #endif
38451 
38452 /************** End of pcache1.c *********************************************/
38453 /************** Begin file rowset.c ******************************************/
38454 /*
38455 ** 2008 December 3
38456 **
38457 ** The author disclaims copyright to this source code.  In place of
38458 ** a legal notice, here is a blessing:
38459 **
38460 **    May you do good and not evil.
38461 **    May you find forgiveness for yourself and forgive others.
38462 **    May you share freely, never taking more than you give.
38463 **
38464 *************************************************************************
38465 **
38466 ** This module implements an object we call a "RowSet".
38467 **
38468 ** The RowSet object is a collection of rowids.  Rowids
38469 ** are inserted into the RowSet in an arbitrary order.  Inserts
38470 ** can be intermixed with tests to see if a given rowid has been
38471 ** previously inserted into the RowSet.
38472 **
38473 ** After all inserts are finished, it is possible to extract the
38474 ** elements of the RowSet in sorted order.  Once this extraction
38475 ** process has started, no new elements may be inserted.
38476 **
38477 ** Hence, the primitive operations for a RowSet are:
38478 **
38479 **    CREATE
38480 **    INSERT
38481 **    TEST
38482 **    SMALLEST
38483 **    DESTROY
38484 **
38485 ** The CREATE and DESTROY primitives are the constructor and destructor,
38486 ** obviously.  The INSERT primitive adds a new element to the RowSet.
38487 ** TEST checks to see if an element is already in the RowSet.  SMALLEST
38488 ** extracts the least value from the RowSet.
38489 **
38490 ** The INSERT primitive might allocate additional memory.  Memory is
38491 ** allocated in chunks so most INSERTs do no allocation.  There is an 
38492 ** upper bound on the size of allocated memory.  No memory is freed
38493 ** until DESTROY.
38494 **
38495 ** The TEST primitive includes a "batch" number.  The TEST primitive
38496 ** will only see elements that were inserted before the last change
38497 ** in the batch number.  In other words, if an INSERT occurs between
38498 ** two TESTs where the TESTs have the same batch nubmer, then the
38499 ** value added by the INSERT will not be visible to the second TEST.
38500 ** The initial batch number is zero, so if the very first TEST contains
38501 ** a non-zero batch number, it will see all prior INSERTs.
38502 **
38503 ** No INSERTs may occurs after a SMALLEST.  An assertion will fail if
38504 ** that is attempted.
38505 **
38506 ** The cost of an INSERT is roughly constant.  (Sometime new memory
38507 ** has to be allocated on an INSERT.)  The cost of a TEST with a new
38508 ** batch number is O(NlogN) where N is the number of elements in the RowSet.
38509 ** The cost of a TEST using the same batch number is O(logN).  The cost
38510 ** of the first SMALLEST is O(NlogN).  Second and subsequent SMALLEST
38511 ** primitives are constant time.  The cost of DESTROY is O(N).
38512 **
38513 ** There is an added cost of O(N) when switching between TEST and
38514 ** SMALLEST primitives.
38515 */
38516 
38517 
38518 /*
38519 ** Target size for allocation chunks.
38520 */
38521 #define ROWSET_ALLOCATION_SIZE 1024
38522 
38523 /*
38524 ** The number of rowset entries per allocation chunk.
38525 */
38526 #define ROWSET_ENTRY_PER_CHUNK  \
38527                        ((ROWSET_ALLOCATION_SIZE-8)/sizeof(struct RowSetEntry))
38528 
38529 /*
38530 ** Each entry in a RowSet is an instance of the following object.
38531 **
38532 ** This same object is reused to store a linked list of trees of RowSetEntry
38533 ** objects.  In that alternative use, pRight points to the next entry
38534 ** in the list, pLeft points to the tree, and v is unused.  The
38535 ** RowSet.pForest value points to the head of this forest list.
38536 */
38537 struct RowSetEntry {            
38538   i64 v;                        /* ROWID value for this entry */
38539   struct RowSetEntry *pRight;   /* Right subtree (larger entries) or list */
38540   struct RowSetEntry *pLeft;    /* Left subtree (smaller entries) */
38541 };
38542 
38543 /*
38544 ** RowSetEntry objects are allocated in large chunks (instances of the
38545 ** following structure) to reduce memory allocation overhead.  The
38546 ** chunks are kept on a linked list so that they can be deallocated
38547 ** when the RowSet is destroyed.
38548 */
38549 struct RowSetChunk {
38550   struct RowSetChunk *pNextChunk;        /* Next chunk on list of them all */
38551   struct RowSetEntry aEntry[ROWSET_ENTRY_PER_CHUNK]; /* Allocated entries */
38552 };
38553 
38554 /*
38555 ** A RowSet in an instance of the following structure.
38556 **
38557 ** A typedef of this structure if found in sqliteInt.h.
38558 */
38559 struct RowSet {
38560   struct RowSetChunk *pChunk;    /* List of all chunk allocations */
38561   sqlite3 *db;                   /* The database connection */
38562   struct RowSetEntry *pEntry;    /* List of entries using pRight */
38563   struct RowSetEntry *pLast;     /* Last entry on the pEntry list */
38564   struct RowSetEntry *pFresh;    /* Source of new entry objects */
38565   struct RowSetEntry *pForest;   /* List of binary trees of entries */
38566   u16 nFresh;                    /* Number of objects on pFresh */
38567   u8 rsFlags;                    /* Various flags */
38568   u8 iBatch;                     /* Current insert batch */
38569 };
38570 
38571 /*
38572 ** Allowed values for RowSet.rsFlags
38573 */
38574 #define ROWSET_SORTED  0x01   /* True if RowSet.pEntry is sorted */
38575 #define ROWSET_NEXT    0x02   /* True if sqlite3RowSetNext() has been called */
38576 
38577 /*
38578 ** Turn bulk memory into a RowSet object.  N bytes of memory
38579 ** are available at pSpace.  The db pointer is used as a memory context
38580 ** for any subsequent allocations that need to occur.
38581 ** Return a pointer to the new RowSet object.
38582 **
38583 ** It must be the case that N is sufficient to make a Rowset.  If not
38584 ** an assertion fault occurs.
38585 ** 
38586 ** If N is larger than the minimum, use the surplus as an initial
38587 ** allocation of entries available to be filled.
38588 */
38589 SQLITE_PRIVATE RowSet *sqlite3RowSetInit(sqlite3 *db, void *pSpace, unsigned int N){
38590   RowSet *p;
38591   assert( N >= ROUND8(sizeof(*p)) );
38592   p = pSpace;
38593   p->pChunk = 0;
38594   p->db = db;
38595   p->pEntry = 0;
38596   p->pLast = 0;
38597   p->pForest = 0;
38598   p->pFresh = (struct RowSetEntry*)(ROUND8(sizeof(*p)) + (char*)p);
38599   p->nFresh = (u16)((N - ROUND8(sizeof(*p)))/sizeof(struct RowSetEntry));
38600   p->rsFlags = ROWSET_SORTED;
38601   p->iBatch = 0;
38602   return p;
38603 }
38604 
38605 /*
38606 ** Deallocate all chunks from a RowSet.  This frees all memory that
38607 ** the RowSet has allocated over its lifetime.  This routine is
38608 ** the destructor for the RowSet.
38609 */
38610 SQLITE_PRIVATE void sqlite3RowSetClear(RowSet *p){
38611   struct RowSetChunk *pChunk, *pNextChunk;
38612   for(pChunk=p->pChunk; pChunk; pChunk = pNextChunk){
38613     pNextChunk = pChunk->pNextChunk;
38614     sqlite3DbFree(p->db, pChunk);
38615   }
38616   p->pChunk = 0;
38617   p->nFresh = 0;
38618   p->pEntry = 0;
38619   p->pLast = 0;
38620   p->pForest = 0;
38621   p->rsFlags = ROWSET_SORTED;
38622 }
38623 
38624 /*
38625 ** Allocate a new RowSetEntry object that is associated with the
38626 ** given RowSet.  Return a pointer to the new and completely uninitialized
38627 ** objected.
38628 **
38629 ** In an OOM situation, the RowSet.db->mallocFailed flag is set and this
38630 ** routine returns NULL.
38631 */
38632 static struct RowSetEntry *rowSetEntryAlloc(RowSet *p){
38633   assert( p!=0 );
38634   if( p->nFresh==0 ){
38635     struct RowSetChunk *pNew;
38636     pNew = sqlite3DbMallocRaw(p->db, sizeof(*pNew));
38637     if( pNew==0 ){
38638       return 0;
38639     }
38640     pNew->pNextChunk = p->pChunk;
38641     p->pChunk = pNew;
38642     p->pFresh = pNew->aEntry;
38643     p->nFresh = ROWSET_ENTRY_PER_CHUNK;
38644   }
38645   p->nFresh--;
38646   return p->pFresh++;
38647 }
38648 
38649 /*
38650 ** Insert a new value into a RowSet.
38651 **
38652 ** The mallocFailed flag of the database connection is set if a
38653 ** memory allocation fails.
38654 */
38655 SQLITE_PRIVATE void sqlite3RowSetInsert(RowSet *p, i64 rowid){
38656   struct RowSetEntry *pEntry;  /* The new entry */
38657   struct RowSetEntry *pLast;   /* The last prior entry */
38658 
38659   /* This routine is never called after sqlite3RowSetNext() */
38660   assert( p!=0 && (p->rsFlags & ROWSET_NEXT)==0 );
38661 
38662   pEntry = rowSetEntryAlloc(p);
38663   if( pEntry==0 ) return;
38664   pEntry->v = rowid;
38665   pEntry->pRight = 0;
38666   pLast = p->pLast;
38667   if( pLast ){
38668     if( (p->rsFlags & ROWSET_SORTED)!=0 && rowid<=pLast->v ){
38669       p->rsFlags &= ~ROWSET_SORTED;
38670     }
38671     pLast->pRight = pEntry;
38672   }else{
38673     p->pEntry = pEntry;
38674   }
38675   p->pLast = pEntry;
38676 }
38677 
38678 /*
38679 ** Merge two lists of RowSetEntry objects.  Remove duplicates.
38680 **
38681 ** The input lists are connected via pRight pointers and are 
38682 ** assumed to each already be in sorted order.
38683 */
38684 static struct RowSetEntry *rowSetEntryMerge(
38685   struct RowSetEntry *pA,    /* First sorted list to be merged */
38686   struct RowSetEntry *pB     /* Second sorted list to be merged */
38687 ){
38688   struct RowSetEntry head;
38689   struct RowSetEntry *pTail;
38690 
38691   pTail = &head;
38692   while( pA && pB ){
38693     assert( pA->pRight==0 || pA->v<=pA->pRight->v );
38694     assert( pB->pRight==0 || pB->v<=pB->pRight->v );
38695     if( pA->v<pB->v ){
38696       pTail->pRight = pA;
38697       pA = pA->pRight;
38698       pTail = pTail->pRight;
38699     }else if( pB->v<pA->v ){
38700       pTail->pRight = pB;
38701       pB = pB->pRight;
38702       pTail = pTail->pRight;
38703     }else{
38704       pA = pA->pRight;
38705     }
38706   }
38707   if( pA ){
38708     assert( pA->pRight==0 || pA->v<=pA->pRight->v );
38709     pTail->pRight = pA;
38710   }else{
38711     assert( pB==0 || pB->pRight==0 || pB->v<=pB->pRight->v );
38712     pTail->pRight = pB;
38713   }
38714   return head.pRight;
38715 }
38716 
38717 /*
38718 ** Sort all elements on the list of RowSetEntry objects into order of
38719 ** increasing v.
38720 */ 
38721 static struct RowSetEntry *rowSetEntrySort(struct RowSetEntry *pIn){
38722   unsigned int i;
38723   struct RowSetEntry *pNext, *aBucket[40];
38724 
38725   memset(aBucket, 0, sizeof(aBucket));
38726   while( pIn ){
38727     pNext = pIn->pRight;
38728     pIn->pRight = 0;
38729     for(i=0; aBucket[i]; i++){
38730       pIn = rowSetEntryMerge(aBucket[i], pIn);
38731       aBucket[i] = 0;
38732     }
38733     aBucket[i] = pIn;
38734     pIn = pNext;
38735   }
38736   pIn = 0;
38737   for(i=0; i<sizeof(aBucket)/sizeof(aBucket[0]); i++){
38738     pIn = rowSetEntryMerge(pIn, aBucket[i]);
38739   }
38740   return pIn;
38741 }
38742 
38743 
38744 /*
38745 ** The input, pIn, is a binary tree (or subtree) of RowSetEntry objects.
38746 ** Convert this tree into a linked list connected by the pRight pointers
38747 ** and return pointers to the first and last elements of the new list.
38748 */
38749 static void rowSetTreeToList(
38750   struct RowSetEntry *pIn,         /* Root of the input tree */
38751   struct RowSetEntry **ppFirst,    /* Write head of the output list here */
38752   struct RowSetEntry **ppLast      /* Write tail of the output list here */
38753 ){
38754   assert( pIn!=0 );
38755   if( pIn->pLeft ){
38756     struct RowSetEntry *p;
38757     rowSetTreeToList(pIn->pLeft, ppFirst, &p);
38758     p->pRight = pIn;
38759   }else{
38760     *ppFirst = pIn;
38761   }
38762   if( pIn->pRight ){
38763     rowSetTreeToList(pIn->pRight, &pIn->pRight, ppLast);
38764   }else{
38765     *ppLast = pIn;
38766   }
38767   assert( (*ppLast)->pRight==0 );
38768 }
38769 
38770 
38771 /*
38772 ** Convert a sorted list of elements (connected by pRight) into a binary
38773 ** tree with depth of iDepth.  A depth of 1 means the tree contains a single
38774 ** node taken from the head of *ppList.  A depth of 2 means a tree with
38775 ** three nodes.  And so forth.
38776 **
38777 ** Use as many entries from the input list as required and update the
38778 ** *ppList to point to the unused elements of the list.  If the input
38779 ** list contains too few elements, then construct an incomplete tree
38780 ** and leave *ppList set to NULL.
38781 **
38782 ** Return a pointer to the root of the constructed binary tree.
38783 */
38784 static struct RowSetEntry *rowSetNDeepTree(
38785   struct RowSetEntry **ppList,
38786   int iDepth
38787 ){
38788   struct RowSetEntry *p;         /* Root of the new tree */
38789   struct RowSetEntry *pLeft;     /* Left subtree */
38790   if( *ppList==0 ){
38791     return 0;
38792   }
38793   if( iDepth==1 ){
38794     p = *ppList;
38795     *ppList = p->pRight;
38796     p->pLeft = p->pRight = 0;
38797     return p;
38798   }
38799   pLeft = rowSetNDeepTree(ppList, iDepth-1);
38800   p = *ppList;
38801   if( p==0 ){
38802     return pLeft;
38803   }
38804   p->pLeft = pLeft;
38805   *ppList = p->pRight;
38806   p->pRight = rowSetNDeepTree(ppList, iDepth-1);
38807   return p;
38808 }
38809 
38810 /*
38811 ** Convert a sorted list of elements into a binary tree. Make the tree
38812 ** as deep as it needs to be in order to contain the entire list.
38813 */
38814 static struct RowSetEntry *rowSetListToTree(struct RowSetEntry *pList){
38815   int iDepth;           /* Depth of the tree so far */
38816   struct RowSetEntry *p;       /* Current tree root */
38817   struct RowSetEntry *pLeft;   /* Left subtree */
38818 
38819   assert( pList!=0 );
38820   p = pList;
38821   pList = p->pRight;
38822   p->pLeft = p->pRight = 0;
38823   for(iDepth=1; pList; iDepth++){
38824     pLeft = p;
38825     p = pList;
38826     pList = p->pRight;
38827     p->pLeft = pLeft;
38828     p->pRight = rowSetNDeepTree(&pList, iDepth);
38829   }
38830   return p;
38831 }
38832 
38833 /*
38834 ** Take all the entries on p->pEntry and on the trees in p->pForest and
38835 ** sort them all together into one big ordered list on p->pEntry.
38836 **
38837 ** This routine should only be called once in the life of a RowSet.
38838 */
38839 static void rowSetToList(RowSet *p){
38840 
38841   /* This routine is called only once */
38842   assert( p!=0 && (p->rsFlags & ROWSET_NEXT)==0 );
38843 
38844   if( (p->rsFlags & ROWSET_SORTED)==0 ){
38845     p->pEntry = rowSetEntrySort(p->pEntry);
38846   }
38847 
38848   /* While this module could theoretically support it, sqlite3RowSetNext()
38849   ** is never called after sqlite3RowSetText() for the same RowSet.  So
38850   ** there is never a forest to deal with.  Should this change, simply
38851   ** remove the assert() and the #if 0. */
38852   assert( p->pForest==0 );
38853 #if 0
38854   while( p->pForest ){
38855     struct RowSetEntry *pTree = p->pForest->pLeft;
38856     if( pTree ){
38857       struct RowSetEntry *pHead, *pTail;
38858       rowSetTreeToList(pTree, &pHead, &pTail);
38859       p->pEntry = rowSetEntryMerge(p->pEntry, pHead);
38860     }
38861     p->pForest = p->pForest->pRight;
38862   }
38863 #endif
38864   p->rsFlags |= ROWSET_NEXT;  /* Verify this routine is never called again */
38865 }
38866 
38867 /*
38868 ** Extract the smallest element from the RowSet.
38869 ** Write the element into *pRowid.  Return 1 on success.  Return
38870 ** 0 if the RowSet is already empty.
38871 **
38872 ** After this routine has been called, the sqlite3RowSetInsert()
38873 ** routine may not be called again.  
38874 */
38875 SQLITE_PRIVATE int sqlite3RowSetNext(RowSet *p, i64 *pRowid){
38876   assert( p!=0 );
38877 
38878   /* Merge the forest into a single sorted list on first call */
38879   if( (p->rsFlags & ROWSET_NEXT)==0 ) rowSetToList(p);
38880 
38881   /* Return the next entry on the list */
38882   if( p->pEntry ){
38883     *pRowid = p->pEntry->v;
38884     p->pEntry = p->pEntry->pRight;
38885     if( p->pEntry==0 ){
38886       sqlite3RowSetClear(p);
38887     }
38888     return 1;
38889   }else{
38890     return 0;
38891   }
38892 }
38893 
38894 /*
38895 ** Check to see if element iRowid was inserted into the rowset as
38896 ** part of any insert batch prior to iBatch.  Return 1 or 0.
38897 **
38898 ** If this is the first test of a new batch and if there exist entires
38899 ** on pRowSet->pEntry, then sort those entires into the forest at
38900 ** pRowSet->pForest so that they can be tested.
38901 */
38902 SQLITE_PRIVATE int sqlite3RowSetTest(RowSet *pRowSet, u8 iBatch, sqlite3_int64 iRowid){
38903   struct RowSetEntry *p, *pTree;
38904 
38905   /* This routine is never called after sqlite3RowSetNext() */
38906   assert( pRowSet!=0 && (pRowSet->rsFlags & ROWSET_NEXT)==0 );
38907 
38908   /* Sort entries into the forest on the first test of a new batch 
38909   */
38910   if( iBatch!=pRowSet->iBatch ){
38911     p = pRowSet->pEntry;
38912     if( p ){
38913       struct RowSetEntry **ppPrevTree = &pRowSet->pForest;
38914       if( (pRowSet->rsFlags & ROWSET_SORTED)==0 ){
38915         p = rowSetEntrySort(p);
38916       }
38917       for(pTree = pRowSet->pForest; pTree; pTree=pTree->pRight){
38918         ppPrevTree = &pTree->pRight;
38919         if( pTree->pLeft==0 ){
38920           pTree->pLeft = rowSetListToTree(p);
38921           break;
38922         }else{
38923           struct RowSetEntry *pAux, *pTail;
38924           rowSetTreeToList(pTree->pLeft, &pAux, &pTail);
38925           pTree->pLeft = 0;
38926           p = rowSetEntryMerge(pAux, p);
38927         }
38928       }
38929       if( pTree==0 ){
38930         *ppPrevTree = pTree = rowSetEntryAlloc(pRowSet);
38931         if( pTree ){
38932           pTree->v = 0;
38933           pTree->pRight = 0;
38934           pTree->pLeft = rowSetListToTree(p);
38935         }
38936       }
38937       pRowSet->pEntry = 0;
38938       pRowSet->pLast = 0;
38939       pRowSet->rsFlags |= ROWSET_SORTED;
38940     }
38941     pRowSet->iBatch = iBatch;
38942   }
38943 
38944   /* Test to see if the iRowid value appears anywhere in the forest.
38945   ** Return 1 if it does and 0 if not.
38946   */
38947   for(pTree = pRowSet->pForest; pTree; pTree=pTree->pRight){
38948     p = pTree->pLeft;
38949     while( p ){
38950       if( p->v<iRowid ){
38951         p = p->pRight;
38952       }else if( p->v>iRowid ){
38953         p = p->pLeft;
38954       }else{
38955         return 1;
38956       }
38957     }
38958   }
38959   return 0;
38960 }
38961 
38962 /************** End of rowset.c **********************************************/
38963 /************** Begin file pager.c *******************************************/
38964 /*
38965 ** 2001 September 15
38966 **
38967 ** The author disclaims copyright to this source code.  In place of
38968 ** a legal notice, here is a blessing:
38969 **
38970 **    May you do good and not evil.
38971 **    May you find forgiveness for yourself and forgive others.
38972 **    May you share freely, never taking more than you give.
38973 **
38974 *************************************************************************
38975 ** This is the implementation of the page cache subsystem or "pager".
38976 ** 
38977 ** The pager is used to access a database disk file.  It implements
38978 ** atomic commit and rollback through the use of a journal file that
38979 ** is separate from the database file.  The pager also implements file
38980 ** locking to prevent two processes from writing the same database
38981 ** file simultaneously, or one process from reading the database while
38982 ** another is writing.
38983 */
38984 #ifndef SQLITE_OMIT_DISKIO
38985 /************** Include wal.h in the middle of pager.c ***********************/
38986 /************** Begin file wal.h *********************************************/
38987 /*
38988 ** 2010 February 1
38989 **
38990 ** The author disclaims copyright to this source code.  In place of
38991 ** a legal notice, here is a blessing:
38992 **
38993 **    May you do good and not evil.
38994 **    May you find forgiveness for yourself and forgive others.
38995 **    May you share freely, never taking more than you give.
38996 **
38997 *************************************************************************
38998 ** This header file defines the interface to the write-ahead logging 
38999 ** system. Refer to the comments below and the header comment attached to 
39000 ** the implementation of each function in log.c for further details.
39001 */
39002 
39003 #ifndef _WAL_H_
39004 #define _WAL_H_
39005 
39006 
39007 /* Additional values that can be added to the sync_flags argument of
39008 ** sqlite3WalFrames():
39009 */
39010 #define WAL_SYNC_TRANSACTIONS  0x20   /* Sync at the end of each transaction */
39011 #define SQLITE_SYNC_MASK       0x13   /* Mask off the SQLITE_SYNC_* values */
39012 
39013 #ifdef SQLITE_OMIT_WAL
39014 # define sqlite3WalOpen(x,y,z)                   0
39015 # define sqlite3WalLimit(x,y)
39016 # define sqlite3WalClose(w,x,y,z)                0
39017 # define sqlite3WalBeginReadTransaction(y,z)     0
39018 # define sqlite3WalEndReadTransaction(z)
39019 # define sqlite3WalDbsize(y)                     0
39020 # define sqlite3WalBeginWriteTransaction(y)      0
39021 # define sqlite3WalEndWriteTransaction(x)        0
39022 # define sqlite3WalUndo(x,y,z)                   0
39023 # define sqlite3WalSavepoint(y,z)
39024 # define sqlite3WalSavepointUndo(y,z)            0
39025 # define sqlite3WalFrames(u,v,w,x,y,z)           0
39026 # define sqlite3WalCheckpoint(r,s,t,u,v,w,x,y,z) 0
39027 # define sqlite3WalCallback(z)                   0
39028 # define sqlite3WalExclusiveMode(y,z)            0
39029 # define sqlite3WalHeapMemory(z)                 0
39030 # define sqlite3WalFramesize(z)                  0
39031 # define sqlite3WalFindFrame(x,y,z)              0
39032 #else
39033 
39034 #define WAL_SAVEPOINT_NDATA 4
39035 
39036 /* Connection to a write-ahead log (WAL) file. 
39037 ** There is one object of this type for each pager. 
39038 */
39039 typedef struct Wal Wal;
39040 
39041 /* Open and close a connection to a write-ahead log. */
39042 SQLITE_PRIVATE int sqlite3WalOpen(sqlite3_vfs*, sqlite3_file*, const char *, int, i64, Wal**);
39043 SQLITE_PRIVATE int sqlite3WalClose(Wal *pWal, int sync_flags, int, u8 *);
39044 
39045 /* Set the limiting size of a WAL file. */
39046 SQLITE_PRIVATE void sqlite3WalLimit(Wal*, i64);
39047 
39048 /* Used by readers to open (lock) and close (unlock) a snapshot.  A 
39049 ** snapshot is like a read-transaction.  It is the state of the database
39050 ** at an instant in time.  sqlite3WalOpenSnapshot gets a read lock and
39051 ** preserves the current state even if the other threads or processes
39052 ** write to or checkpoint the WAL.  sqlite3WalCloseSnapshot() closes the
39053 ** transaction and releases the lock.
39054 */
39055 SQLITE_PRIVATE int sqlite3WalBeginReadTransaction(Wal *pWal, int *);
39056 SQLITE_PRIVATE void sqlite3WalEndReadTransaction(Wal *pWal);
39057 
39058 /* Read a page from the write-ahead log, if it is present. */
39059 SQLITE_PRIVATE int sqlite3WalFindFrame(Wal *, Pgno, u32 *);
39060 SQLITE_PRIVATE int sqlite3WalReadFrame(Wal *, u32, int, u8 *);
39061 
39062 /* If the WAL is not empty, return the size of the database. */
39063 SQLITE_PRIVATE Pgno sqlite3WalDbsize(Wal *pWal);
39064 
39065 /* Obtain or release the WRITER lock. */
39066 SQLITE_PRIVATE int sqlite3WalBeginWriteTransaction(Wal *pWal);
39067 SQLITE_PRIVATE int sqlite3WalEndWriteTransaction(Wal *pWal);
39068 
39069 /* Undo any frames written (but not committed) to the log */
39070 SQLITE_PRIVATE int sqlite3WalUndo(Wal *pWal, int (*xUndo)(void *, Pgno), void *pUndoCtx);
39071 
39072 /* Return an integer that records the current (uncommitted) write
39073 ** position in the WAL */
39074 SQLITE_PRIVATE void sqlite3WalSavepoint(Wal *pWal, u32 *aWalData);
39075 
39076 /* Move the write position of the WAL back to iFrame.  Called in
39077 ** response to a ROLLBACK TO command. */
39078 SQLITE_PRIVATE int sqlite3WalSavepointUndo(Wal *pWal, u32 *aWalData);
39079 
39080 /* Write a frame or frames to the log. */
39081 SQLITE_PRIVATE int sqlite3WalFrames(Wal *pWal, int, PgHdr *, Pgno, int, int);
39082 
39083 /* Copy pages from the log to the database file */ 
39084 SQLITE_PRIVATE int sqlite3WalCheckpoint(
39085   Wal *pWal,                      /* Write-ahead log connection */
39086   int eMode,                      /* One of PASSIVE, FULL and RESTART */
39087   int (*xBusy)(void*),            /* Function to call when busy */
39088   void *pBusyArg,                 /* Context argument for xBusyHandler */
39089   int sync_flags,                 /* Flags to sync db file with (or 0) */
39090   int nBuf,                       /* Size of buffer nBuf */
39091   u8 *zBuf,                       /* Temporary buffer to use */
39092   int *pnLog,                     /* OUT: Number of frames in WAL */
39093   int *pnCkpt                     /* OUT: Number of backfilled frames in WAL */
39094 );
39095 
39096 /* Return the value to pass to a sqlite3_wal_hook callback, the
39097 ** number of frames in the WAL at the point of the last commit since
39098 ** sqlite3WalCallback() was called.  If no commits have occurred since
39099 ** the last call, then return 0.
39100 */
39101 SQLITE_PRIVATE int sqlite3WalCallback(Wal *pWal);
39102 
39103 /* Tell the wal layer that an EXCLUSIVE lock has been obtained (or released)
39104 ** by the pager layer on the database file.
39105 */
39106 SQLITE_PRIVATE int sqlite3WalExclusiveMode(Wal *pWal, int op);
39107 
39108 /* Return true if the argument is non-NULL and the WAL module is using
39109 ** heap-memory for the wal-index. Otherwise, if the argument is NULL or the
39110 ** WAL module is using shared-memory, return false. 
39111 */
39112 SQLITE_PRIVATE int sqlite3WalHeapMemory(Wal *pWal);
39113 
39114 #ifdef SQLITE_ENABLE_ZIPVFS
39115 /* If the WAL file is not empty, return the number of bytes of content
39116 ** stored in each frame (i.e. the db page-size when the WAL was created).
39117 */
39118 SQLITE_PRIVATE int sqlite3WalFramesize(Wal *pWal);
39119 #endif
39120 
39121 #endif /* ifndef SQLITE_OMIT_WAL */
39122 #endif /* _WAL_H_ */
39123 
39124 /************** End of wal.h *************************************************/
39125 /************** Continuing where we left off in pager.c **********************/
39126 
39127 
39128 /******************* NOTES ON THE DESIGN OF THE PAGER ************************
39129 **
39130 ** This comment block describes invariants that hold when using a rollback
39131 ** journal.  These invariants do not apply for journal_mode=WAL,
39132 ** journal_mode=MEMORY, or journal_mode=OFF.
39133 **
39134 ** Within this comment block, a page is deemed to have been synced
39135 ** automatically as soon as it is written when PRAGMA synchronous=OFF.
39136 ** Otherwise, the page is not synced until the xSync method of the VFS
39137 ** is called successfully on the file containing the page.
39138 **
39139 ** Definition:  A page of the database file is said to be "overwriteable" if
39140 ** one or more of the following are true about the page:
39141 ** 
39142 **     (a)  The original content of the page as it was at the beginning of
39143 **          the transaction has been written into the rollback journal and
39144 **          synced.
39145 ** 
39146 **     (b)  The page was a freelist leaf page at the start of the transaction.
39147 ** 
39148 **     (c)  The page number is greater than the largest page that existed in
39149 **          the database file at the start of the transaction.
39150 ** 
39151 ** (1) A page of the database file is never overwritten unless one of the
39152 **     following are true:
39153 ** 
39154 **     (a) The page and all other pages on the same sector are overwriteable.
39155 ** 
39156 **     (b) The atomic page write optimization is enabled, and the entire
39157 **         transaction other than the update of the transaction sequence
39158 **         number consists of a single page change.
39159 ** 
39160 ** (2) The content of a page written into the rollback journal exactly matches
39161 **     both the content in the database when the rollback journal was written
39162 **     and the content in the database at the beginning of the current
39163 **     transaction.
39164 ** 
39165 ** (3) Writes to the database file are an integer multiple of the page size
39166 **     in length and are aligned on a page boundary.
39167 ** 
39168 ** (4) Reads from the database file are either aligned on a page boundary and
39169 **     an integer multiple of the page size in length or are taken from the
39170 **     first 100 bytes of the database file.
39171 ** 
39172 ** (5) All writes to the database file are synced prior to the rollback journal
39173 **     being deleted, truncated, or zeroed.
39174 ** 
39175 ** (6) If a master journal file is used, then all writes to the database file
39176 **     are synced prior to the master journal being deleted.
39177 ** 
39178 ** Definition: Two databases (or the same database at two points it time)
39179 ** are said to be "logically equivalent" if they give the same answer to
39180 ** all queries.  Note in particular the content of freelist leaf
39181 ** pages can be changed arbitarily without effecting the logical equivalence
39182 ** of the database.
39183 ** 
39184 ** (7) At any time, if any subset, including the empty set and the total set,
39185 **     of the unsynced changes to a rollback journal are removed and the 
39186 **     journal is rolled back, the resulting database file will be logical
39187 **     equivalent to the database file at the beginning of the transaction.
39188 ** 
39189 ** (8) When a transaction is rolled back, the xTruncate method of the VFS
39190 **     is called to restore the database file to the same size it was at
39191 **     the beginning of the transaction.  (In some VFSes, the xTruncate
39192 **     method is a no-op, but that does not change the fact the SQLite will
39193 **     invoke it.)
39194 ** 
39195 ** (9) Whenever the database file is modified, at least one bit in the range
39196 **     of bytes from 24 through 39 inclusive will be changed prior to releasing
39197 **     the EXCLUSIVE lock, thus signaling other connections on the same
39198 **     database to flush their caches.
39199 **
39200 ** (10) The pattern of bits in bytes 24 through 39 shall not repeat in less
39201 **      than one billion transactions.
39202 **
39203 ** (11) A database file is well-formed at the beginning and at the conclusion
39204 **      of every transaction.
39205 **
39206 ** (12) An EXCLUSIVE lock is held on the database file when writing to
39207 **      the database file.
39208 **
39209 ** (13) A SHARED lock is held on the database file while reading any
39210 **      content out of the database file.
39211 **
39212 ******************************************************************************/
39213 
39214 /*
39215 ** Macros for troubleshooting.  Normally turned off
39216 */
39217 #if 0
39218 int sqlite3PagerTrace=1;  /* True to enable tracing */
39219 #define sqlite3DebugPrintf printf
39220 #define PAGERTRACE(X)     if( sqlite3PagerTrace ){ sqlite3DebugPrintf X; }
39221 #else
39222 #define PAGERTRACE(X)
39223 #endif
39224 
39225 /*
39226 ** The following two macros are used within the PAGERTRACE() macros above
39227 ** to print out file-descriptors. 
39228 **
39229 ** PAGERID() takes a pointer to a Pager struct as its argument. The
39230 ** associated file-descriptor is returned. FILEHANDLEID() takes an sqlite3_file
39231 ** struct as its argument.
39232 */
39233 #define PAGERID(p) ((int)(p->fd))
39234 #define FILEHANDLEID(fd) ((int)fd)
39235 
39236 /*
39237 ** The Pager.eState variable stores the current 'state' of a pager. A
39238 ** pager may be in any one of the seven states shown in the following
39239 ** state diagram.
39240 **
39241 **                            OPEN <------+------+
39242 **                              |         |      |
39243 **                              V         |      |
39244 **               +---------> READER-------+      |
39245 **               |              |                |
39246 **               |              V                |
39247 **               |<-------WRITER_LOCKED------> ERROR
39248 **               |              |                ^  
39249 **               |              V                |
39250 **               |<------WRITER_CACHEMOD-------->|
39251 **               |              |                |
39252 **               |              V                |
39253 **               |<-------WRITER_DBMOD---------->|
39254 **               |              |                |
39255 **               |              V                |
39256 **               +<------WRITER_FINISHED-------->+
39257 **
39258 **
39259 ** List of state transitions and the C [function] that performs each:
39260 ** 
39261 **   OPEN              -> READER              [sqlite3PagerSharedLock]
39262 **   READER            -> OPEN                [pager_unlock]
39263 **
39264 **   READER            -> WRITER_LOCKED       [sqlite3PagerBegin]
39265 **   WRITER_LOCKED     -> WRITER_CACHEMOD     [pager_open_journal]
39266 **   WRITER_CACHEMOD   -> WRITER_DBMOD        [syncJournal]
39267 **   WRITER_DBMOD      -> WRITER_FINISHED     [sqlite3PagerCommitPhaseOne]
39268 **   WRITER_***        -> READER              [pager_end_transaction]
39269 **
39270 **   WRITER_***        -> ERROR               [pager_error]
39271 **   ERROR             -> OPEN                [pager_unlock]
39272 ** 
39273 **
39274 **  OPEN:
39275 **
39276 **    The pager starts up in this state. Nothing is guaranteed in this
39277 **    state - the file may or may not be locked and the database size is
39278 **    unknown. The database may not be read or written.
39279 **
39280 **    * No read or write transaction is active.
39281 **    * Any lock, or no lock at all, may be held on the database file.
39282 **    * The dbSize, dbOrigSize and dbFileSize variables may not be trusted.
39283 **
39284 **  READER:
39285 **
39286 **    In this state all the requirements for reading the database in 
39287 **    rollback (non-WAL) mode are met. Unless the pager is (or recently
39288 **    was) in exclusive-locking mode, a user-level read transaction is 
39289 **    open. The database size is known in this state.
39290 **
39291 **    A connection running with locking_mode=normal enters this state when
39292 **    it opens a read-transaction on the database and returns to state
39293 **    OPEN after the read-transaction is completed. However a connection
39294 **    running in locking_mode=exclusive (including temp databases) remains in
39295 **    this state even after the read-transaction is closed. The only way
39296 **    a locking_mode=exclusive connection can transition from READER to OPEN
39297 **    is via the ERROR state (see below).
39298 ** 
39299 **    * A read transaction may be active (but a write-transaction cannot).
39300 **    * A SHARED or greater lock is held on the database file.
39301 **    * The dbSize variable may be trusted (even if a user-level read 
39302 **      transaction is not active). The dbOrigSize and dbFileSize variables
39303 **      may not be trusted at this point.
39304 **    * If the database is a WAL database, then the WAL connection is open.
39305 **    * Even if a read-transaction is not open, it is guaranteed that 
39306 **      there is no hot-journal in the file-system.
39307 **
39308 **  WRITER_LOCKED:
39309 **
39310 **    The pager moves to this state from READER when a write-transaction
39311 **    is first opened on the database. In WRITER_LOCKED state, all locks 
39312 **    required to start a write-transaction are held, but no actual 
39313 **    modifications to the cache or database have taken place.
39314 **
39315 **    In rollback mode, a RESERVED or (if the transaction was opened with 
39316 **    BEGIN EXCLUSIVE) EXCLUSIVE lock is obtained on the database file when
39317 **    moving to this state, but the journal file is not written to or opened 
39318 **    to in this state. If the transaction is committed or rolled back while 
39319 **    in WRITER_LOCKED state, all that is required is to unlock the database 
39320 **    file.
39321 **
39322 **    IN WAL mode, WalBeginWriteTransaction() is called to lock the log file.
39323 **    If the connection is running with locking_mode=exclusive, an attempt
39324 **    is made to obtain an EXCLUSIVE lock on the database file.
39325 **
39326 **    * A write transaction is active.
39327 **    * If the connection is open in rollback-mode, a RESERVED or greater 
39328 **      lock is held on the database file.
39329 **    * If the connection is open in WAL-mode, a WAL write transaction
39330 **      is open (i.e. sqlite3WalBeginWriteTransaction() has been successfully
39331 **      called).
39332 **    * The dbSize, dbOrigSize and dbFileSize variables are all valid.
39333 **    * The contents of the pager cache have not been modified.
39334 **    * The journal file may or may not be open.
39335 **    * Nothing (not even the first header) has been written to the journal.
39336 **
39337 **  WRITER_CACHEMOD:
39338 **
39339 **    A pager moves from WRITER_LOCKED state to this state when a page is
39340 **    first modified by the upper layer. In rollback mode the journal file
39341 **    is opened (if it is not already open) and a header written to the
39342 **    start of it. The database file on disk has not been modified.
39343 **
39344 **    * A write transaction is active.
39345 **    * A RESERVED or greater lock is held on the database file.
39346 **    * The journal file is open and the first header has been written 
39347 **      to it, but the header has not been synced to disk.
39348 **    * The contents of the page cache have been modified.
39349 **
39350 **  WRITER_DBMOD:
39351 **
39352 **    The pager transitions from WRITER_CACHEMOD into WRITER_DBMOD state
39353 **    when it modifies the contents of the database file. WAL connections
39354 **    never enter this state (since they do not modify the database file,
39355 **    just the log file).
39356 **
39357 **    * A write transaction is active.
39358 **    * An EXCLUSIVE or greater lock is held on the database file.
39359 **    * The journal file is open and the first header has been written 
39360 **      and synced to disk.
39361 **    * The contents of the page cache have been modified (and possibly
39362 **      written to disk).
39363 **
39364 **  WRITER_FINISHED:
39365 **
39366 **    It is not possible for a WAL connection to enter this state.
39367 **
39368 **    A rollback-mode pager changes to WRITER_FINISHED state from WRITER_DBMOD
39369 **    state after the entire transaction has been successfully written into the
39370 **    database file. In this state the transaction may be committed simply
39371 **    by finalizing the journal file. Once in WRITER_FINISHED state, it is 
39372 **    not possible to modify the database further. At this point, the upper 
39373 **    layer must either commit or rollback the transaction.
39374 **
39375 **    * A write transaction is active.
39376 **    * An EXCLUSIVE or greater lock is held on the database file.
39377 **    * All writing and syncing of journal and database data has finished.
39378 **      If no error occurred, all that remains is to finalize the journal to
39379 **      commit the transaction. If an error did occur, the caller will need
39380 **      to rollback the transaction. 
39381 **
39382 **  ERROR:
39383 **
39384 **    The ERROR state is entered when an IO or disk-full error (including
39385 **    SQLITE_IOERR_NOMEM) occurs at a point in the code that makes it 
39386 **    difficult to be sure that the in-memory pager state (cache contents, 
39387 **    db size etc.) are consistent with the contents of the file-system.
39388 **
39389 **    Temporary pager files may enter the ERROR state, but in-memory pagers
39390 **    cannot.
39391 **
39392 **    For example, if an IO error occurs while performing a rollback, 
39393 **    the contents of the page-cache may be left in an inconsistent state.
39394 **    At this point it would be dangerous to change back to READER state
39395 **    (as usually happens after a rollback). Any subsequent readers might
39396 **    report database corruption (due to the inconsistent cache), and if
39397 **    they upgrade to writers, they may inadvertently corrupt the database
39398 **    file. To avoid this hazard, the pager switches into the ERROR state
39399 **    instead of READER following such an error.
39400 **
39401 **    Once it has entered the ERROR state, any attempt to use the pager
39402 **    to read or write data returns an error. Eventually, once all 
39403 **    outstanding transactions have been abandoned, the pager is able to
39404 **    transition back to OPEN state, discarding the contents of the 
39405 **    page-cache and any other in-memory state at the same time. Everything
39406 **    is reloaded from disk (and, if necessary, hot-journal rollback peformed)
39407 **    when a read-transaction is next opened on the pager (transitioning
39408 **    the pager into READER state). At that point the system has recovered 
39409 **    from the error.
39410 **
39411 **    Specifically, the pager jumps into the ERROR state if:
39412 **
39413 **      1. An error occurs while attempting a rollback. This happens in
39414 **         function sqlite3PagerRollback().
39415 **
39416 **      2. An error occurs while attempting to finalize a journal file
39417 **         following a commit in function sqlite3PagerCommitPhaseTwo().
39418 **
39419 **      3. An error occurs while attempting to write to the journal or
39420 **         database file in function pagerStress() in order to free up
39421 **         memory.
39422 **
39423 **    In other cases, the error is returned to the b-tree layer. The b-tree
39424 **    layer then attempts a rollback operation. If the error condition 
39425 **    persists, the pager enters the ERROR state via condition (1) above.
39426 **
39427 **    Condition (3) is necessary because it can be triggered by a read-only
39428 **    statement executed within a transaction. In this case, if the error
39429 **    code were simply returned to the user, the b-tree layer would not
39430 **    automatically attempt a rollback, as it assumes that an error in a
39431 **    read-only statement cannot leave the pager in an internally inconsistent 
39432 **    state.
39433 **
39434 **    * The Pager.errCode variable is set to something other than SQLITE_OK.
39435 **    * There are one or more outstanding references to pages (after the
39436 **      last reference is dropped the pager should move back to OPEN state).
39437 **    * The pager is not an in-memory pager.
39438 **    
39439 **
39440 ** Notes:
39441 **
39442 **   * A pager is never in WRITER_DBMOD or WRITER_FINISHED state if the
39443 **     connection is open in WAL mode. A WAL connection is always in one
39444 **     of the first four states.
39445 **
39446 **   * Normally, a connection open in exclusive mode is never in PAGER_OPEN
39447 **     state. There are two exceptions: immediately after exclusive-mode has
39448 **     been turned on (and before any read or write transactions are 
39449 **     executed), and when the pager is leaving the "error state".
39450 **
39451 **   * See also: assert_pager_state().
39452 */
39453 #define PAGER_OPEN                  0
39454 #define PAGER_READER                1
39455 #define PAGER_WRITER_LOCKED         2
39456 #define PAGER_WRITER_CACHEMOD       3
39457 #define PAGER_WRITER_DBMOD          4
39458 #define PAGER_WRITER_FINISHED       5
39459 #define PAGER_ERROR                 6
39460 
39461 /*
39462 ** The Pager.eLock variable is almost always set to one of the 
39463 ** following locking-states, according to the lock currently held on
39464 ** the database file: NO_LOCK, SHARED_LOCK, RESERVED_LOCK or EXCLUSIVE_LOCK.
39465 ** This variable is kept up to date as locks are taken and released by
39466 ** the pagerLockDb() and pagerUnlockDb() wrappers.
39467 **
39468 ** If the VFS xLock() or xUnlock() returns an error other than SQLITE_BUSY
39469 ** (i.e. one of the SQLITE_IOERR subtypes), it is not clear whether or not
39470 ** the operation was successful. In these circumstances pagerLockDb() and
39471 ** pagerUnlockDb() take a conservative approach - eLock is always updated
39472 ** when unlocking the file, and only updated when locking the file if the
39473 ** VFS call is successful. This way, the Pager.eLock variable may be set
39474 ** to a less exclusive (lower) value than the lock that is actually held
39475 ** at the system level, but it is never set to a more exclusive value.
39476 **
39477 ** This is usually safe. If an xUnlock fails or appears to fail, there may 
39478 ** be a few redundant xLock() calls or a lock may be held for longer than
39479 ** required, but nothing really goes wrong.
39480 **
39481 ** The exception is when the database file is unlocked as the pager moves
39482 ** from ERROR to OPEN state. At this point there may be a hot-journal file 
39483 ** in the file-system that needs to be rolled back (as part of a OPEN->SHARED
39484 ** transition, by the same pager or any other). If the call to xUnlock()
39485 ** fails at this point and the pager is left holding an EXCLUSIVE lock, this
39486 ** can confuse the call to xCheckReservedLock() call made later as part
39487 ** of hot-journal detection.
39488 **
39489 ** xCheckReservedLock() is defined as returning true "if there is a RESERVED 
39490 ** lock held by this process or any others". So xCheckReservedLock may 
39491 ** return true because the caller itself is holding an EXCLUSIVE lock (but
39492 ** doesn't know it because of a previous error in xUnlock). If this happens
39493 ** a hot-journal may be mistaken for a journal being created by an active
39494 ** transaction in another process, causing SQLite to read from the database
39495 ** without rolling it back.
39496 **
39497 ** To work around this, if a call to xUnlock() fails when unlocking the
39498 ** database in the ERROR state, Pager.eLock is set to UNKNOWN_LOCK. It
39499 ** is only changed back to a real locking state after a successful call
39500 ** to xLock(EXCLUSIVE). Also, the code to do the OPEN->SHARED state transition
39501 ** omits the check for a hot-journal if Pager.eLock is set to UNKNOWN_LOCK 
39502 ** lock. Instead, it assumes a hot-journal exists and obtains an EXCLUSIVE
39503 ** lock on the database file before attempting to roll it back. See function
39504 ** PagerSharedLock() for more detail.
39505 **
39506 ** Pager.eLock may only be set to UNKNOWN_LOCK when the pager is in 
39507 ** PAGER_OPEN state.
39508 */
39509 #define UNKNOWN_LOCK                (EXCLUSIVE_LOCK+1)
39510 
39511 /*
39512 ** A macro used for invoking the codec if there is one
39513 */
39514 #ifdef SQLITE_HAS_CODEC
39515 # define CODEC1(P,D,N,X,E) \
39516     if( P->xCodec && P->xCodec(P->pCodec,D,N,X)==0 ){ E; }
39517 # define CODEC2(P,D,N,X,E,O) \
39518     if( P->xCodec==0 ){ O=(char*)D; }else \
39519     if( (O=(char*)(P->xCodec(P->pCodec,D,N,X)))==0 ){ E; }
39520 #else
39521 # define CODEC1(P,D,N,X,E)   /* NO-OP */
39522 # define CODEC2(P,D,N,X,E,O) O=(char*)D
39523 #endif
39524 
39525 /*
39526 ** The maximum allowed sector size. 64KiB. If the xSectorsize() method 
39527 ** returns a value larger than this, then MAX_SECTOR_SIZE is used instead.
39528 ** This could conceivably cause corruption following a power failure on
39529 ** such a system. This is currently an undocumented limit.
39530 */
39531 #define MAX_SECTOR_SIZE 0x10000
39532 
39533 /*
39534 ** An instance of the following structure is allocated for each active
39535 ** savepoint and statement transaction in the system. All such structures
39536 ** are stored in the Pager.aSavepoint[] array, which is allocated and
39537 ** resized using sqlite3Realloc().
39538 **
39539 ** When a savepoint is created, the PagerSavepoint.iHdrOffset field is
39540 ** set to 0. If a journal-header is written into the main journal while
39541 ** the savepoint is active, then iHdrOffset is set to the byte offset 
39542 ** immediately following the last journal record written into the main
39543 ** journal before the journal-header. This is required during savepoint
39544 ** rollback (see pagerPlaybackSavepoint()).
39545 */
39546 typedef struct PagerSavepoint PagerSavepoint;
39547 struct PagerSavepoint {
39548   i64 iOffset;                 /* Starting offset in main journal */
39549   i64 iHdrOffset;              /* See above */
39550   Bitvec *pInSavepoint;        /* Set of pages in this savepoint */
39551   Pgno nOrig;                  /* Original number of pages in file */
39552   Pgno iSubRec;                /* Index of first record in sub-journal */
39553 #ifndef SQLITE_OMIT_WAL
39554   u32 aWalData[WAL_SAVEPOINT_NDATA];        /* WAL savepoint context */
39555 #endif
39556 };
39557 
39558 /*
39559 ** Bits of the Pager.doNotSpill flag.  See further description below.
39560 */
39561 #define SPILLFLAG_OFF         0x01      /* Never spill cache.  Set via pragma */
39562 #define SPILLFLAG_ROLLBACK    0x02      /* Current rolling back, so do not spill */
39563 #define SPILLFLAG_NOSYNC      0x04      /* Spill is ok, but do not sync */
39564 
39565 /*
39566 ** A open page cache is an instance of struct Pager. A description of
39567 ** some of the more important member variables follows:
39568 **
39569 ** eState
39570 **
39571 **   The current 'state' of the pager object. See the comment and state
39572 **   diagram above for a description of the pager state.
39573 **
39574 ** eLock
39575 **
39576 **   For a real on-disk database, the current lock held on the database file -
39577 **   NO_LOCK, SHARED_LOCK, RESERVED_LOCK or EXCLUSIVE_LOCK.
39578 **
39579 **   For a temporary or in-memory database (neither of which require any
39580 **   locks), this variable is always set to EXCLUSIVE_LOCK. Since such
39581 **   databases always have Pager.exclusiveMode==1, this tricks the pager
39582 **   logic into thinking that it already has all the locks it will ever
39583 **   need (and no reason to release them).
39584 **
39585 **   In some (obscure) circumstances, this variable may also be set to
39586 **   UNKNOWN_LOCK. See the comment above the #define of UNKNOWN_LOCK for
39587 **   details.
39588 **
39589 ** changeCountDone
39590 **
39591 **   This boolean variable is used to make sure that the change-counter 
39592 **   (the 4-byte header field at byte offset 24 of the database file) is 
39593 **   not updated more often than necessary. 
39594 **
39595 **   It is set to true when the change-counter field is updated, which 
39596 **   can only happen if an exclusive lock is held on the database file.
39597 **   It is cleared (set to false) whenever an exclusive lock is 
39598 **   relinquished on the database file. Each time a transaction is committed,
39599 **   The changeCountDone flag is inspected. If it is true, the work of
39600 **   updating the change-counter is omitted for the current transaction.
39601 **
39602 **   This mechanism means that when running in exclusive mode, a connection 
39603 **   need only update the change-counter once, for the first transaction
39604 **   committed.
39605 **
39606 ** setMaster
39607 **
39608 **   When PagerCommitPhaseOne() is called to commit a transaction, it may
39609 **   (or may not) specify a master-journal name to be written into the 
39610 **   journal file before it is synced to disk.
39611 **
39612 **   Whether or not a journal file contains a master-journal pointer affects 
39613 **   the way in which the journal file is finalized after the transaction is 
39614 **   committed or rolled back when running in "journal_mode=PERSIST" mode.
39615 **   If a journal file does not contain a master-journal pointer, it is
39616 **   finalized by overwriting the first journal header with zeroes. If
39617 **   it does contain a master-journal pointer the journal file is finalized 
39618 **   by truncating it to zero bytes, just as if the connection were 
39619 **   running in "journal_mode=truncate" mode.
39620 **
39621 **   Journal files that contain master journal pointers cannot be finalized
39622 **   simply by overwriting the first journal-header with zeroes, as the
39623 **   master journal pointer could interfere with hot-journal rollback of any
39624 **   subsequently interrupted transaction that reuses the journal file.
39625 **
39626 **   The flag is cleared as soon as the journal file is finalized (either
39627 **   by PagerCommitPhaseTwo or PagerRollback). If an IO error prevents the
39628 **   journal file from being successfully finalized, the setMaster flag
39629 **   is cleared anyway (and the pager will move to ERROR state).
39630 **
39631 ** doNotSpill
39632 **
39633 **   This variables control the behavior of cache-spills  (calls made by
39634 **   the pcache module to the pagerStress() routine to write cached data
39635 **   to the file-system in order to free up memory).
39636 **
39637 **   When bits SPILLFLAG_OFF or SPILLFLAG_ROLLBACK of doNotSpill are set,
39638 **   writing to the database from pagerStress() is disabled altogether.
39639 **   The SPILLFLAG_ROLLBACK case is done in a very obscure case that
39640 **   comes up during savepoint rollback that requires the pcache module
39641 **   to allocate a new page to prevent the journal file from being written
39642 **   while it is being traversed by code in pager_playback().  The SPILLFLAG_OFF
39643 **   case is a user preference.
39644 ** 
39645 **   If the SPILLFLAG_NOSYNC bit is set, writing to the database from pagerStress()
39646 **   is permitted, but syncing the journal file is not. This flag is set
39647 **   by sqlite3PagerWrite() when the file-system sector-size is larger than
39648 **   the database page-size in order to prevent a journal sync from happening 
39649 **   in between the journalling of two pages on the same sector. 
39650 **
39651 ** subjInMemory
39652 **
39653 **   This is a boolean variable. If true, then any required sub-journal
39654 **   is opened as an in-memory journal file. If false, then in-memory
39655 **   sub-journals are only used for in-memory pager files.
39656 **
39657 **   This variable is updated by the upper layer each time a new 
39658 **   write-transaction is opened.
39659 **
39660 ** dbSize, dbOrigSize, dbFileSize
39661 **
39662 **   Variable dbSize is set to the number of pages in the database file.
39663 **   It is valid in PAGER_READER and higher states (all states except for
39664 **   OPEN and ERROR). 
39665 **
39666 **   dbSize is set based on the size of the database file, which may be 
39667 **   larger than the size of the database (the value stored at offset
39668 **   28 of the database header by the btree). If the size of the file
39669 **   is not an integer multiple of the page-size, the value stored in
39670 **   dbSize is rounded down (i.e. a 5KB file with 2K page-size has dbSize==2).
39671 **   Except, any file that is greater than 0 bytes in size is considered
39672 **   to have at least one page. (i.e. a 1KB file with 2K page-size leads
39673 **   to dbSize==1).
39674 **
39675 **   During a write-transaction, if pages with page-numbers greater than
39676 **   dbSize are modified in the cache, dbSize is updated accordingly.
39677 **   Similarly, if the database is truncated using PagerTruncateImage(), 
39678 **   dbSize is updated.
39679 **
39680 **   Variables dbOrigSize and dbFileSize are valid in states 
39681 **   PAGER_WRITER_LOCKED and higher. dbOrigSize is a copy of the dbSize
39682 **   variable at the start of the transaction. It is used during rollback,
39683 **   and to determine whether or not pages need to be journalled before
39684 **   being modified.
39685 **
39686 **   Throughout a write-transaction, dbFileSize contains the size of
39687 **   the file on disk in pages. It is set to a copy of dbSize when the
39688 **   write-transaction is first opened, and updated when VFS calls are made
39689 **   to write or truncate the database file on disk. 
39690 **
39691 **   The only reason the dbFileSize variable is required is to suppress 
39692 **   unnecessary calls to xTruncate() after committing a transaction. If, 
39693 **   when a transaction is committed, the dbFileSize variable indicates 
39694 **   that the database file is larger than the database image (Pager.dbSize), 
39695 **   pager_truncate() is called. The pager_truncate() call uses xFilesize()
39696 **   to measure the database file on disk, and then truncates it if required.
39697 **   dbFileSize is not used when rolling back a transaction. In this case
39698 **   pager_truncate() is called unconditionally (which means there may be
39699 **   a call to xFilesize() that is not strictly required). In either case,
39700 **   pager_truncate() may cause the file to become smaller or larger.
39701 **
39702 ** dbHintSize
39703 **
39704 **   The dbHintSize variable is used to limit the number of calls made to
39705 **   the VFS xFileControl(FCNTL_SIZE_HINT) method. 
39706 **
39707 **   dbHintSize is set to a copy of the dbSize variable when a
39708 **   write-transaction is opened (at the same time as dbFileSize and
39709 **   dbOrigSize). If the xFileControl(FCNTL_SIZE_HINT) method is called,
39710 **   dbHintSize is increased to the number of pages that correspond to the
39711 **   size-hint passed to the method call. See pager_write_pagelist() for 
39712 **   details.
39713 **
39714 ** errCode
39715 **
39716 **   The Pager.errCode variable is only ever used in PAGER_ERROR state. It
39717 **   is set to zero in all other states. In PAGER_ERROR state, Pager.errCode 
39718 **   is always set to SQLITE_FULL, SQLITE_IOERR or one of the SQLITE_IOERR_XXX 
39719 **   sub-codes.
39720 */
39721 struct Pager {
39722   sqlite3_vfs *pVfs;          /* OS functions to use for IO */
39723   u8 exclusiveMode;           /* Boolean. True if locking_mode==EXCLUSIVE */
39724   u8 journalMode;             /* One of the PAGER_JOURNALMODE_* values */
39725   u8 useJournal;              /* Use a rollback journal on this file */
39726   u8 noSync;                  /* Do not sync the journal if true */
39727   u8 fullSync;                /* Do extra syncs of the journal for robustness */
39728   u8 ckptSyncFlags;           /* SYNC_NORMAL or SYNC_FULL for checkpoint */
39729   u8 walSyncFlags;            /* SYNC_NORMAL or SYNC_FULL for wal writes */
39730   u8 syncFlags;               /* SYNC_NORMAL or SYNC_FULL otherwise */
39731   u8 tempFile;                /* zFilename is a temporary file */
39732   u8 readOnly;                /* True for a read-only database */
39733   u8 memDb;                   /* True to inhibit all file I/O */
39734 
39735   /**************************************************************************
39736   ** The following block contains those class members that change during
39737   ** routine opertion.  Class members not in this block are either fixed
39738   ** when the pager is first created or else only change when there is a
39739   ** significant mode change (such as changing the page_size, locking_mode,
39740   ** or the journal_mode).  From another view, these class members describe
39741   ** the "state" of the pager, while other class members describe the
39742   ** "configuration" of the pager.
39743   */
39744   u8 eState;                  /* Pager state (OPEN, READER, WRITER_LOCKED..) */
39745   u8 eLock;                   /* Current lock held on database file */
39746   u8 changeCountDone;         /* Set after incrementing the change-counter */
39747   u8 setMaster;               /* True if a m-j name has been written to jrnl */
39748   u8 doNotSpill;              /* Do not spill the cache when non-zero */
39749   u8 subjInMemory;            /* True to use in-memory sub-journals */
39750   Pgno dbSize;                /* Number of pages in the database */
39751   Pgno dbOrigSize;            /* dbSize before the current transaction */
39752   Pgno dbFileSize;            /* Number of pages in the database file */
39753   Pgno dbHintSize;            /* Value passed to FCNTL_SIZE_HINT call */
39754   int errCode;                /* One of several kinds of errors */
39755   int nRec;                   /* Pages journalled since last j-header written */
39756   u32 cksumInit;              /* Quasi-random value added to every checksum */
39757   u32 nSubRec;                /* Number of records written to sub-journal */
39758   Bitvec *pInJournal;         /* One bit for each page in the database file */
39759   sqlite3_file *fd;           /* File descriptor for database */
39760   sqlite3_file *jfd;          /* File descriptor for main journal */
39761   sqlite3_file *sjfd;         /* File descriptor for sub-journal */
39762   i64 journalOff;             /* Current write offset in the journal file */
39763   i64 journalHdr;             /* Byte offset to previous journal header */
39764   sqlite3_backup *pBackup;    /* Pointer to list of ongoing backup processes */
39765   PagerSavepoint *aSavepoint; /* Array of active savepoints */
39766   int nSavepoint;             /* Number of elements in aSavepoint[] */
39767   char dbFileVers[16];        /* Changes whenever database file changes */
39768 
39769   u8 bUseFetch;               /* True to use xFetch() */
39770   int nMmapOut;               /* Number of mmap pages currently outstanding */
39771   sqlite3_int64 szMmap;       /* Desired maximum mmap size */
39772   PgHdr *pMmapFreelist;       /* List of free mmap page headers (pDirty) */
39773   /*
39774   ** End of the routinely-changing class members
39775   ***************************************************************************/
39776 
39777   u16 nExtra;                 /* Add this many bytes to each in-memory page */
39778   i16 nReserve;               /* Number of unused bytes at end of each page */
39779   u32 vfsFlags;               /* Flags for sqlite3_vfs.xOpen() */
39780   u32 sectorSize;             /* Assumed sector size during rollback */
39781   int pageSize;               /* Number of bytes in a page */
39782   Pgno mxPgno;                /* Maximum allowed size of the database */
39783   i64 journalSizeLimit;       /* Size limit for persistent journal files */
39784   char *zFilename;            /* Name of the database file */
39785   char *zJournal;             /* Name of the journal file */
39786   int (*xBusyHandler)(void*); /* Function to call when busy */
39787   void *pBusyHandlerArg;      /* Context argument for xBusyHandler */
39788   int aStat[3];               /* Total cache hits, misses and writes */
39789 #ifdef SQLITE_TEST
39790   int nRead;                  /* Database pages read */
39791 #endif
39792   void (*xReiniter)(DbPage*); /* Call this routine when reloading pages */
39793 #ifdef SQLITE_HAS_CODEC
39794   void *(*xCodec)(void*,void*,Pgno,int); /* Routine for en/decoding data */
39795   void (*xCodecSizeChng)(void*,int,int); /* Notify of page size changes */
39796   void (*xCodecFree)(void*);             /* Destructor for the codec */
39797   void *pCodec;               /* First argument to xCodec... methods */
39798 #endif
39799   char *pTmpSpace;            /* Pager.pageSize bytes of space for tmp use */
39800   PCache *pPCache;            /* Pointer to page cache object */
39801 #ifndef SQLITE_OMIT_WAL
39802   Wal *pWal;                  /* Write-ahead log used by "journal_mode=wal" */
39803   char *zWal;                 /* File name for write-ahead log */
39804 #endif
39805 };
39806 
39807 /*
39808 ** Indexes for use with Pager.aStat[]. The Pager.aStat[] array contains
39809 ** the values accessed by passing SQLITE_DBSTATUS_CACHE_HIT, CACHE_MISS 
39810 ** or CACHE_WRITE to sqlite3_db_status().
39811 */
39812 #define PAGER_STAT_HIT   0
39813 #define PAGER_STAT_MISS  1
39814 #define PAGER_STAT_WRITE 2
39815 
39816 /*
39817 ** The following global variables hold counters used for
39818 ** testing purposes only.  These variables do not exist in
39819 ** a non-testing build.  These variables are not thread-safe.
39820 */
39821 #ifdef SQLITE_TEST
39822 SQLITE_API int sqlite3_pager_readdb_count = 0;    /* Number of full pages read from DB */
39823 SQLITE_API int sqlite3_pager_writedb_count = 0;   /* Number of full pages written to DB */
39824 SQLITE_API int sqlite3_pager_writej_count = 0;    /* Number of pages written to journal */
39825 # define PAGER_INCR(v)  v++
39826 #else
39827 # define PAGER_INCR(v)
39828 #endif
39829 
39830 
39831 
39832 /*
39833 ** Journal files begin with the following magic string.  The data
39834 ** was obtained from /dev/random.  It is used only as a sanity check.
39835 **
39836 ** Since version 2.8.0, the journal format contains additional sanity
39837 ** checking information.  If the power fails while the journal is being
39838 ** written, semi-random garbage data might appear in the journal
39839 ** file after power is restored.  If an attempt is then made
39840 ** to roll the journal back, the database could be corrupted.  The additional
39841 ** sanity checking data is an attempt to discover the garbage in the
39842 ** journal and ignore it.
39843 **
39844 ** The sanity checking information for the new journal format consists
39845 ** of a 32-bit checksum on each page of data.  The checksum covers both
39846 ** the page number and the pPager->pageSize bytes of data for the page.
39847 ** This cksum is initialized to a 32-bit random value that appears in the
39848 ** journal file right after the header.  The random initializer is important,
39849 ** because garbage data that appears at the end of a journal is likely
39850 ** data that was once in other files that have now been deleted.  If the
39851 ** garbage data came from an obsolete journal file, the checksums might
39852 ** be correct.  But by initializing the checksum to random value which
39853 ** is different for every journal, we minimize that risk.
39854 */
39855 static const unsigned char aJournalMagic[] = {
39856   0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd7,
39857 };
39858 
39859 /*
39860 ** The size of the of each page record in the journal is given by
39861 ** the following macro.
39862 */
39863 #define JOURNAL_PG_SZ(pPager)  ((pPager->pageSize) + 8)
39864 
39865 /*
39866 ** The journal header size for this pager. This is usually the same 
39867 ** size as a single disk sector. See also setSectorSize().
39868 */
39869 #define JOURNAL_HDR_SZ(pPager) (pPager->sectorSize)
39870 
39871 /*
39872 ** The macro MEMDB is true if we are dealing with an in-memory database.
39873 ** We do this as a macro so that if the SQLITE_OMIT_MEMORYDB macro is set,
39874 ** the value of MEMDB will be a constant and the compiler will optimize
39875 ** out code that would never execute.
39876 */
39877 #ifdef SQLITE_OMIT_MEMORYDB
39878 # define MEMDB 0
39879 #else
39880 # define MEMDB pPager->memDb
39881 #endif
39882 
39883 /*
39884 ** The macro USEFETCH is true if we are allowed to use the xFetch and xUnfetch
39885 ** interfaces to access the database using memory-mapped I/O.
39886 */
39887 #if SQLITE_MAX_MMAP_SIZE>0
39888 # define USEFETCH(x) ((x)->bUseFetch)
39889 #else
39890 # define USEFETCH(x) 0
39891 #endif
39892 
39893 /*
39894 ** The maximum legal page number is (2^31 - 1).
39895 */
39896 #define PAGER_MAX_PGNO 2147483647
39897 
39898 /*
39899 ** The argument to this macro is a file descriptor (type sqlite3_file*).
39900 ** Return 0 if it is not open, or non-zero (but not 1) if it is.
39901 **
39902 ** This is so that expressions can be written as:
39903 **
39904 **   if( isOpen(pPager->jfd) ){ ...
39905 **
39906 ** instead of
39907 **
39908 **   if( pPager->jfd->pMethods ){ ...
39909 */
39910 #define isOpen(pFd) ((pFd)->pMethods)
39911 
39912 /*
39913 ** Return true if this pager uses a write-ahead log instead of the usual
39914 ** rollback journal. Otherwise false.
39915 */
39916 #ifndef SQLITE_OMIT_WAL
39917 static int pagerUseWal(Pager *pPager){
39918   return (pPager->pWal!=0);
39919 }
39920 #else
39921 # define pagerUseWal(x) 0
39922 # define pagerRollbackWal(x) 0
39923 # define pagerWalFrames(v,w,x,y) 0
39924 # define pagerOpenWalIfPresent(z) SQLITE_OK
39925 # define pagerBeginReadTransaction(z) SQLITE_OK
39926 #endif
39927 
39928 #ifndef NDEBUG 
39929 /*
39930 ** Usage:
39931 **
39932 **   assert( assert_pager_state(pPager) );
39933 **
39934 ** This function runs many asserts to try to find inconsistencies in
39935 ** the internal state of the Pager object.
39936 */
39937 static int assert_pager_state(Pager *p){
39938   Pager *pPager = p;
39939 
39940   /* State must be valid. */
39941   assert( p->eState==PAGER_OPEN
39942        || p->eState==PAGER_READER
39943        || p->eState==PAGER_WRITER_LOCKED
39944        || p->eState==PAGER_WRITER_CACHEMOD
39945        || p->eState==PAGER_WRITER_DBMOD
39946        || p->eState==PAGER_WRITER_FINISHED
39947        || p->eState==PAGER_ERROR
39948   );
39949 
39950   /* Regardless of the current state, a temp-file connection always behaves
39951   ** as if it has an exclusive lock on the database file. It never updates
39952   ** the change-counter field, so the changeCountDone flag is always set.
39953   */
39954   assert( p->tempFile==0 || p->eLock==EXCLUSIVE_LOCK );
39955   assert( p->tempFile==0 || pPager->changeCountDone );
39956 
39957   /* If the useJournal flag is clear, the journal-mode must be "OFF". 
39958   ** And if the journal-mode is "OFF", the journal file must not be open.
39959   */
39960   assert( p->journalMode==PAGER_JOURNALMODE_OFF || p->useJournal );
39961   assert( p->journalMode!=PAGER_JOURNALMODE_OFF || !isOpen(p->jfd) );
39962 
39963   /* Check that MEMDB implies noSync. And an in-memory journal. Since 
39964   ** this means an in-memory pager performs no IO at all, it cannot encounter 
39965   ** either SQLITE_IOERR or SQLITE_FULL during rollback or while finalizing 
39966   ** a journal file. (although the in-memory journal implementation may 
39967   ** return SQLITE_IOERR_NOMEM while the journal file is being written). It 
39968   ** is therefore not possible for an in-memory pager to enter the ERROR 
39969   ** state.
39970   */
39971   if( MEMDB ){
39972     assert( p->noSync );
39973     assert( p->journalMode==PAGER_JOURNALMODE_OFF 
39974          || p->journalMode==PAGER_JOURNALMODE_MEMORY 
39975     );
39976     assert( p->eState!=PAGER_ERROR && p->eState!=PAGER_OPEN );
39977     assert( pagerUseWal(p)==0 );
39978   }
39979 
39980   /* If changeCountDone is set, a RESERVED lock or greater must be held
39981   ** on the file.
39982   */
39983   assert( pPager->changeCountDone==0 || pPager->eLock>=RESERVED_LOCK );
39984   assert( p->eLock!=PENDING_LOCK );
39985 
39986   switch( p->eState ){
39987     case PAGER_OPEN:
39988       assert( !MEMDB );
39989       assert( pPager->errCode==SQLITE_OK );
39990       assert( sqlite3PcacheRefCount(pPager->pPCache)==0 || pPager->tempFile );
39991       break;
39992 
39993     case PAGER_READER:
39994       assert( pPager->errCode==SQLITE_OK );
39995       assert( p->eLock!=UNKNOWN_LOCK );
39996       assert( p->eLock>=SHARED_LOCK );
39997       break;
39998 
39999     case PAGER_WRITER_LOCKED:
40000       assert( p->eLock!=UNKNOWN_LOCK );
40001       assert( pPager->errCode==SQLITE_OK );
40002       if( !pagerUseWal(pPager) ){
40003         assert( p->eLock>=RESERVED_LOCK );
40004       }
40005       assert( pPager->dbSize==pPager->dbOrigSize );
40006       assert( pPager->dbOrigSize==pPager->dbFileSize );
40007       assert( pPager->dbOrigSize==pPager->dbHintSize );
40008       assert( pPager->setMaster==0 );
40009       break;
40010 
40011     case PAGER_WRITER_CACHEMOD:
40012       assert( p->eLock!=UNKNOWN_LOCK );
40013       assert( pPager->errCode==SQLITE_OK );
40014       if( !pagerUseWal(pPager) ){
40015         /* It is possible that if journal_mode=wal here that neither the
40016         ** journal file nor the WAL file are open. This happens during
40017         ** a rollback transaction that switches from journal_mode=off
40018         ** to journal_mode=wal.
40019         */
40020         assert( p->eLock>=RESERVED_LOCK );
40021         assert( isOpen(p->jfd) 
40022              || p->journalMode==PAGER_JOURNALMODE_OFF 
40023              || p->journalMode==PAGER_JOURNALMODE_WAL 
40024         );
40025       }
40026       assert( pPager->dbOrigSize==pPager->dbFileSize );
40027       assert( pPager->dbOrigSize==pPager->dbHintSize );
40028       break;
40029 
40030     case PAGER_WRITER_DBMOD:
40031       assert( p->eLock==EXCLUSIVE_LOCK );
40032       assert( pPager->errCode==SQLITE_OK );
40033       assert( !pagerUseWal(pPager) );
40034       assert( p->eLock>=EXCLUSIVE_LOCK );
40035       assert( isOpen(p->jfd) 
40036            || p->journalMode==PAGER_JOURNALMODE_OFF 
40037            || p->journalMode==PAGER_JOURNALMODE_WAL 
40038       );
40039       assert( pPager->dbOrigSize<=pPager->dbHintSize );
40040       break;
40041 
40042     case PAGER_WRITER_FINISHED:
40043       assert( p->eLock==EXCLUSIVE_LOCK );
40044       assert( pPager->errCode==SQLITE_OK );
40045       assert( !pagerUseWal(pPager) );
40046       assert( isOpen(p->jfd) 
40047            || p->journalMode==PAGER_JOURNALMODE_OFF 
40048            || p->journalMode==PAGER_JOURNALMODE_WAL 
40049       );
40050       break;
40051 
40052     case PAGER_ERROR:
40053       /* There must be at least one outstanding reference to the pager if
40054       ** in ERROR state. Otherwise the pager should have already dropped
40055       ** back to OPEN state.
40056       */
40057       assert( pPager->errCode!=SQLITE_OK );
40058       assert( sqlite3PcacheRefCount(pPager->pPCache)>0 );
40059       break;
40060   }
40061 
40062   return 1;
40063 }
40064 #endif /* ifndef NDEBUG */
40065 
40066 #ifdef SQLITE_DEBUG 
40067 /*
40068 ** Return a pointer to a human readable string in a static buffer
40069 ** containing the state of the Pager object passed as an argument. This
40070 ** is intended to be used within debuggers. For example, as an alternative
40071 ** to "print *pPager" in gdb:
40072 **
40073 ** (gdb) printf "%s", print_pager_state(pPager)
40074 */
40075 static char *print_pager_state(Pager *p){
40076   static char zRet[1024];
40077 
40078   sqlite3_snprintf(1024, zRet,
40079       "Filename:      %s\n"
40080       "State:         %s errCode=%d\n"
40081       "Lock:          %s\n"
40082       "Locking mode:  locking_mode=%s\n"
40083       "Journal mode:  journal_mode=%s\n"
40084       "Backing store: tempFile=%d memDb=%d useJournal=%d\n"
40085       "Journal:       journalOff=%lld journalHdr=%lld\n"
40086       "Size:          dbsize=%d dbOrigSize=%d dbFileSize=%d\n"
40087       , p->zFilename
40088       , p->eState==PAGER_OPEN            ? "OPEN" :
40089         p->eState==PAGER_READER          ? "READER" :
40090         p->eState==PAGER_WRITER_LOCKED   ? "WRITER_LOCKED" :
40091         p->eState==PAGER_WRITER_CACHEMOD ? "WRITER_CACHEMOD" :
40092         p->eState==PAGER_WRITER_DBMOD    ? "WRITER_DBMOD" :
40093         p->eState==PAGER_WRITER_FINISHED ? "WRITER_FINISHED" :
40094         p->eState==PAGER_ERROR           ? "ERROR" : "?error?"
40095       , (int)p->errCode
40096       , p->eLock==NO_LOCK         ? "NO_LOCK" :
40097         p->eLock==RESERVED_LOCK   ? "RESERVED" :
40098         p->eLock==EXCLUSIVE_LOCK  ? "EXCLUSIVE" :
40099         p->eLock==SHARED_LOCK     ? "SHARED" :
40100         p->eLock==UNKNOWN_LOCK    ? "UNKNOWN" : "?error?"
40101       , p->exclusiveMode ? "exclusive" : "normal"
40102       , p->journalMode==PAGER_JOURNALMODE_MEMORY   ? "memory" :
40103         p->journalMode==PAGER_JOURNALMODE_OFF      ? "off" :
40104         p->journalMode==PAGER_JOURNALMODE_DELETE   ? "delete" :
40105         p->journalMode==PAGER_JOURNALMODE_PERSIST  ? "persist" :
40106         p->journalMode==PAGER_JOURNALMODE_TRUNCATE ? "truncate" :
40107         p->journalMode==PAGER_JOURNALMODE_WAL      ? "wal" : "?error?"
40108       , (int)p->tempFile, (int)p->memDb, (int)p->useJournal
40109       , p->journalOff, p->journalHdr
40110       , (int)p->dbSize, (int)p->dbOrigSize, (int)p->dbFileSize
40111   );
40112 
40113   return zRet;
40114 }
40115 #endif
40116 
40117 /*
40118 ** Return true if it is necessary to write page *pPg into the sub-journal.
40119 ** A page needs to be written into the sub-journal if there exists one
40120 ** or more open savepoints for which:
40121 **
40122 **   * The page-number is less than or equal to PagerSavepoint.nOrig, and
40123 **   * The bit corresponding to the page-number is not set in
40124 **     PagerSavepoint.pInSavepoint.
40125 */
40126 static int subjRequiresPage(PgHdr *pPg){
40127   Pager *pPager = pPg->pPager;
40128   PagerSavepoint *p;
40129   Pgno pgno;
40130   int i;
40131   if( pPager->nSavepoint ){
40132     pgno = pPg->pgno;
40133     for(i=0; i<pPager->nSavepoint; i++){
40134       p = &pPager->aSavepoint[i];
40135       if( p->nOrig>=pgno && 0==sqlite3BitvecTest(p->pInSavepoint, pgno) ){
40136         return 1;
40137       }
40138     }
40139   }
40140   return 0;
40141 }
40142 
40143 /*
40144 ** Return true if the page is already in the journal file.
40145 */
40146 static int pageInJournal(PgHdr *pPg){
40147   return sqlite3BitvecTest(pPg->pPager->pInJournal, pPg->pgno);
40148 }
40149 
40150 /*
40151 ** Read a 32-bit integer from the given file descriptor.  Store the integer
40152 ** that is read in *pRes.  Return SQLITE_OK if everything worked, or an
40153 ** error code is something goes wrong.
40154 **
40155 ** All values are stored on disk as big-endian.
40156 */
40157 static int read32bits(sqlite3_file *fd, i64 offset, u32 *pRes){
40158   unsigned char ac[4];
40159   int rc = sqlite3OsRead(fd, ac, sizeof(ac), offset);
40160   if( rc==SQLITE_OK ){
40161     *pRes = sqlite3Get4byte(ac);
40162   }
40163   return rc;
40164 }
40165 
40166 /*
40167 ** Write a 32-bit integer into a string buffer in big-endian byte order.
40168 */
40169 #define put32bits(A,B)  sqlite3Put4byte((u8*)A,B)
40170 
40171 
40172 /*
40173 ** Write a 32-bit integer into the given file descriptor.  Return SQLITE_OK
40174 ** on success or an error code is something goes wrong.
40175 */
40176 static int write32bits(sqlite3_file *fd, i64 offset, u32 val){
40177   char ac[4];
40178   put32bits(ac, val);
40179   return sqlite3OsWrite(fd, ac, 4, offset);
40180 }
40181 
40182 /*
40183 ** Unlock the database file to level eLock, which must be either NO_LOCK
40184 ** or SHARED_LOCK. Regardless of whether or not the call to xUnlock()
40185 ** succeeds, set the Pager.eLock variable to match the (attempted) new lock.
40186 **
40187 ** Except, if Pager.eLock is set to UNKNOWN_LOCK when this function is
40188 ** called, do not modify it. See the comment above the #define of 
40189 ** UNKNOWN_LOCK for an explanation of this.
40190 */
40191 static int pagerUnlockDb(Pager *pPager, int eLock){
40192   int rc = SQLITE_OK;
40193 
40194   assert( !pPager->exclusiveMode || pPager->eLock==eLock );
40195   assert( eLock==NO_LOCK || eLock==SHARED_LOCK );
40196   assert( eLock!=NO_LOCK || pagerUseWal(pPager)==0 );
40197   if( isOpen(pPager->fd) ){
40198     assert( pPager->eLock>=eLock );
40199     rc = sqlite3OsUnlock(pPager->fd, eLock);
40200     if( pPager->eLock!=UNKNOWN_LOCK ){
40201       pPager->eLock = (u8)eLock;
40202     }
40203     IOTRACE(("UNLOCK %p %d\n", pPager, eLock))
40204   }
40205   return rc;
40206 }
40207 
40208 /*
40209 ** Lock the database file to level eLock, which must be either SHARED_LOCK,
40210 ** RESERVED_LOCK or EXCLUSIVE_LOCK. If the caller is successful, set the
40211 ** Pager.eLock variable to the new locking state. 
40212 **
40213 ** Except, if Pager.eLock is set to UNKNOWN_LOCK when this function is 
40214 ** called, do not modify it unless the new locking state is EXCLUSIVE_LOCK. 
40215 ** See the comment above the #define of UNKNOWN_LOCK for an explanation 
40216 ** of this.
40217 */
40218 static int pagerLockDb(Pager *pPager, int eLock){
40219   int rc = SQLITE_OK;
40220 
40221   assert( eLock==SHARED_LOCK || eLock==RESERVED_LOCK || eLock==EXCLUSIVE_LOCK );
40222   if( pPager->eLock<eLock || pPager->eLock==UNKNOWN_LOCK ){
40223     rc = sqlite3OsLock(pPager->fd, eLock);
40224     if( rc==SQLITE_OK && (pPager->eLock!=UNKNOWN_LOCK||eLock==EXCLUSIVE_LOCK) ){
40225       pPager->eLock = (u8)eLock;
40226       IOTRACE(("LOCK %p %d\n", pPager, eLock))
40227     }
40228   }
40229   return rc;
40230 }
40231 
40232 /*
40233 ** This function determines whether or not the atomic-write optimization
40234 ** can be used with this pager. The optimization can be used if:
40235 **
40236 **  (a) the value returned by OsDeviceCharacteristics() indicates that
40237 **      a database page may be written atomically, and
40238 **  (b) the value returned by OsSectorSize() is less than or equal
40239 **      to the page size.
40240 **
40241 ** The optimization is also always enabled for temporary files. It is
40242 ** an error to call this function if pPager is opened on an in-memory
40243 ** database.
40244 **
40245 ** If the optimization cannot be used, 0 is returned. If it can be used,
40246 ** then the value returned is the size of the journal file when it
40247 ** contains rollback data for exactly one page.
40248 */
40249 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
40250 static int jrnlBufferSize(Pager *pPager){
40251   assert( !MEMDB );
40252   if( !pPager->tempFile ){
40253     int dc;                           /* Device characteristics */
40254     int nSector;                      /* Sector size */
40255     int szPage;                       /* Page size */
40256 
40257     assert( isOpen(pPager->fd) );
40258     dc = sqlite3OsDeviceCharacteristics(pPager->fd);
40259     nSector = pPager->sectorSize;
40260     szPage = pPager->pageSize;
40261 
40262     assert(SQLITE_IOCAP_ATOMIC512==(512>>8));
40263     assert(SQLITE_IOCAP_ATOMIC64K==(65536>>8));
40264     if( 0==(dc&(SQLITE_IOCAP_ATOMIC|(szPage>>8)) || nSector>szPage) ){
40265       return 0;
40266     }
40267   }
40268 
40269   return JOURNAL_HDR_SZ(pPager) + JOURNAL_PG_SZ(pPager);
40270 }
40271 #endif
40272 
40273 /*
40274 ** If SQLITE_CHECK_PAGES is defined then we do some sanity checking
40275 ** on the cache using a hash function.  This is used for testing
40276 ** and debugging only.
40277 */
40278 #ifdef SQLITE_CHECK_PAGES
40279 /*
40280 ** Return a 32-bit hash of the page data for pPage.
40281 */
40282 static u32 pager_datahash(int nByte, unsigned char *pData){
40283   u32 hash = 0;
40284   int i;
40285   for(i=0; i<nByte; i++){
40286     hash = (hash*1039) + pData[i];
40287   }
40288   return hash;
40289 }
40290 static u32 pager_pagehash(PgHdr *pPage){
40291   return pager_datahash(pPage->pPager->pageSize, (unsigned char *)pPage->pData);
40292 }
40293 static void pager_set_pagehash(PgHdr *pPage){
40294   pPage->pageHash = pager_pagehash(pPage);
40295 }
40296 
40297 /*
40298 ** The CHECK_PAGE macro takes a PgHdr* as an argument. If SQLITE_CHECK_PAGES
40299 ** is defined, and NDEBUG is not defined, an assert() statement checks
40300 ** that the page is either dirty or still matches the calculated page-hash.
40301 */
40302 #define CHECK_PAGE(x) checkPage(x)
40303 static void checkPage(PgHdr *pPg){
40304   Pager *pPager = pPg->pPager;
40305   assert( pPager->eState!=PAGER_ERROR );
40306   assert( (pPg->flags&PGHDR_DIRTY) || pPg->pageHash==pager_pagehash(pPg) );
40307 }
40308 
40309 #else
40310 #define pager_datahash(X,Y)  0
40311 #define pager_pagehash(X)  0
40312 #define pager_set_pagehash(X)
40313 #define CHECK_PAGE(x)
40314 #endif  /* SQLITE_CHECK_PAGES */
40315 
40316 /*
40317 ** When this is called the journal file for pager pPager must be open.
40318 ** This function attempts to read a master journal file name from the 
40319 ** end of the file and, if successful, copies it into memory supplied 
40320 ** by the caller. See comments above writeMasterJournal() for the format
40321 ** used to store a master journal file name at the end of a journal file.
40322 **
40323 ** zMaster must point to a buffer of at least nMaster bytes allocated by
40324 ** the caller. This should be sqlite3_vfs.mxPathname+1 (to ensure there is
40325 ** enough space to write the master journal name). If the master journal
40326 ** name in the journal is longer than nMaster bytes (including a
40327 ** nul-terminator), then this is handled as if no master journal name
40328 ** were present in the journal.
40329 **
40330 ** If a master journal file name is present at the end of the journal
40331 ** file, then it is copied into the buffer pointed to by zMaster. A
40332 ** nul-terminator byte is appended to the buffer following the master
40333 ** journal file name.
40334 **
40335 ** If it is determined that no master journal file name is present 
40336 ** zMaster[0] is set to 0 and SQLITE_OK returned.
40337 **
40338 ** If an error occurs while reading from the journal file, an SQLite
40339 ** error code is returned.
40340 */
40341 static int readMasterJournal(sqlite3_file *pJrnl, char *zMaster, u32 nMaster){
40342   int rc;                    /* Return code */
40343   u32 len;                   /* Length in bytes of master journal name */
40344   i64 szJ;                   /* Total size in bytes of journal file pJrnl */
40345   u32 cksum;                 /* MJ checksum value read from journal */
40346   u32 u;                     /* Unsigned loop counter */
40347   unsigned char aMagic[8];   /* A buffer to hold the magic header */
40348   zMaster[0] = '\0';
40349 
40350   if( SQLITE_OK!=(rc = sqlite3OsFileSize(pJrnl, &szJ))
40351    || szJ<16
40352    || SQLITE_OK!=(rc = read32bits(pJrnl, szJ-16, &len))
40353    || len>=nMaster 
40354    || SQLITE_OK!=(rc = read32bits(pJrnl, szJ-12, &cksum))
40355    || SQLITE_OK!=(rc = sqlite3OsRead(pJrnl, aMagic, 8, szJ-8))
40356    || memcmp(aMagic, aJournalMagic, 8)
40357    || SQLITE_OK!=(rc = sqlite3OsRead(pJrnl, zMaster, len, szJ-16-len))
40358   ){
40359     return rc;
40360   }
40361 
40362   /* See if the checksum matches the master journal name */
40363   for(u=0; u<len; u++){
40364     cksum -= zMaster[u];
40365   }
40366   if( cksum ){
40367     /* If the checksum doesn't add up, then one or more of the disk sectors
40368     ** containing the master journal filename is corrupted. This means
40369     ** definitely roll back, so just return SQLITE_OK and report a (nul)
40370     ** master-journal filename.
40371     */
40372     len = 0;
40373   }
40374   zMaster[len] = '\0';
40375    
40376   return SQLITE_OK;
40377 }
40378 
40379 /*
40380 ** Return the offset of the sector boundary at or immediately 
40381 ** following the value in pPager->journalOff, assuming a sector 
40382 ** size of pPager->sectorSize bytes.
40383 **
40384 ** i.e for a sector size of 512:
40385 **
40386 **   Pager.journalOff          Return value
40387 **   ---------------------------------------
40388 **   0                         0
40389 **   512                       512
40390 **   100                       512
40391 **   2000                      2048
40392 ** 
40393 */
40394 static i64 journalHdrOffset(Pager *pPager){
40395   i64 offset = 0;
40396   i64 c = pPager->journalOff;
40397   if( c ){
40398     offset = ((c-1)/JOURNAL_HDR_SZ(pPager) + 1) * JOURNAL_HDR_SZ(pPager);
40399   }
40400   assert( offset%JOURNAL_HDR_SZ(pPager)==0 );
40401   assert( offset>=c );
40402   assert( (offset-c)<JOURNAL_HDR_SZ(pPager) );
40403   return offset;
40404 }
40405 
40406 /*
40407 ** The journal file must be open when this function is called.
40408 **
40409 ** This function is a no-op if the journal file has not been written to
40410 ** within the current transaction (i.e. if Pager.journalOff==0).
40411 **
40412 ** If doTruncate is non-zero or the Pager.journalSizeLimit variable is
40413 ** set to 0, then truncate the journal file to zero bytes in size. Otherwise,
40414 ** zero the 28-byte header at the start of the journal file. In either case, 
40415 ** if the pager is not in no-sync mode, sync the journal file immediately 
40416 ** after writing or truncating it.
40417 **
40418 ** If Pager.journalSizeLimit is set to a positive, non-zero value, and
40419 ** following the truncation or zeroing described above the size of the 
40420 ** journal file in bytes is larger than this value, then truncate the
40421 ** journal file to Pager.journalSizeLimit bytes. The journal file does
40422 ** not need to be synced following this operation.
40423 **
40424 ** If an IO error occurs, abandon processing and return the IO error code.
40425 ** Otherwise, return SQLITE_OK.
40426 */
40427 static int zeroJournalHdr(Pager *pPager, int doTruncate){
40428   int rc = SQLITE_OK;                               /* Return code */
40429   assert( isOpen(pPager->jfd) );
40430   if( pPager->journalOff ){
40431     const i64 iLimit = pPager->journalSizeLimit;    /* Local cache of jsl */
40432 
40433     IOTRACE(("JZEROHDR %p\n", pPager))
40434     if( doTruncate || iLimit==0 ){
40435       rc = sqlite3OsTruncate(pPager->jfd, 0);
40436     }else{
40437       static const char zeroHdr[28] = {0};
40438       rc = sqlite3OsWrite(pPager->jfd, zeroHdr, sizeof(zeroHdr), 0);
40439     }
40440     if( rc==SQLITE_OK && !pPager->noSync ){
40441       rc = sqlite3OsSync(pPager->jfd, SQLITE_SYNC_DATAONLY|pPager->syncFlags);
40442     }
40443 
40444     /* At this point the transaction is committed but the write lock 
40445     ** is still held on the file. If there is a size limit configured for 
40446     ** the persistent journal and the journal file currently consumes more
40447     ** space than that limit allows for, truncate it now. There is no need
40448     ** to sync the file following this operation.
40449     */
40450     if( rc==SQLITE_OK && iLimit>0 ){
40451       i64 sz;
40452       rc = sqlite3OsFileSize(pPager->jfd, &sz);
40453       if( rc==SQLITE_OK && sz>iLimit ){
40454         rc = sqlite3OsTruncate(pPager->jfd, iLimit);
40455       }
40456     }
40457   }
40458   return rc;
40459 }
40460 
40461 /*
40462 ** The journal file must be open when this routine is called. A journal
40463 ** header (JOURNAL_HDR_SZ bytes) is written into the journal file at the
40464 ** current location.
40465 **
40466 ** The format for the journal header is as follows:
40467 ** - 8 bytes: Magic identifying journal format.
40468 ** - 4 bytes: Number of records in journal, or -1 no-sync mode is on.
40469 ** - 4 bytes: Random number used for page hash.
40470 ** - 4 bytes: Initial database page count.
40471 ** - 4 bytes: Sector size used by the process that wrote this journal.
40472 ** - 4 bytes: Database page size.
40473 ** 
40474 ** Followed by (JOURNAL_HDR_SZ - 28) bytes of unused space.
40475 */
40476 static int writeJournalHdr(Pager *pPager){
40477   int rc = SQLITE_OK;                 /* Return code */
40478   char *zHeader = pPager->pTmpSpace;  /* Temporary space used to build header */
40479   u32 nHeader = (u32)pPager->pageSize;/* Size of buffer pointed to by zHeader */
40480   u32 nWrite;                         /* Bytes of header sector written */
40481   int ii;                             /* Loop counter */
40482 
40483   assert( isOpen(pPager->jfd) );      /* Journal file must be open. */
40484 
40485   if( nHeader>JOURNAL_HDR_SZ(pPager) ){
40486     nHeader = JOURNAL_HDR_SZ(pPager);
40487   }
40488 
40489   /* If there are active savepoints and any of them were created 
40490   ** since the most recent journal header was written, update the 
40491   ** PagerSavepoint.iHdrOffset fields now.
40492   */
40493   for(ii=0; ii<pPager->nSavepoint; ii++){
40494     if( pPager->aSavepoint[ii].iHdrOffset==0 ){
40495       pPager->aSavepoint[ii].iHdrOffset = pPager->journalOff;
40496     }
40497   }
40498 
40499   pPager->journalHdr = pPager->journalOff = journalHdrOffset(pPager);
40500 
40501   /* 
40502   ** Write the nRec Field - the number of page records that follow this
40503   ** journal header. Normally, zero is written to this value at this time.
40504   ** After the records are added to the journal (and the journal synced, 
40505   ** if in full-sync mode), the zero is overwritten with the true number
40506   ** of records (see syncJournal()).
40507   **
40508   ** A faster alternative is to write 0xFFFFFFFF to the nRec field. When
40509   ** reading the journal this value tells SQLite to assume that the
40510   ** rest of the journal file contains valid page records. This assumption
40511   ** is dangerous, as if a failure occurred whilst writing to the journal
40512   ** file it may contain some garbage data. There are two scenarios
40513   ** where this risk can be ignored:
40514   **
40515   **   * When the pager is in no-sync mode. Corruption can follow a
40516   **     power failure in this case anyway.
40517   **
40518   **   * When the SQLITE_IOCAP_SAFE_APPEND flag is set. This guarantees
40519   **     that garbage data is never appended to the journal file.
40520   */
40521   assert( isOpen(pPager->fd) || pPager->noSync );
40522   if( pPager->noSync || (pPager->journalMode==PAGER_JOURNALMODE_MEMORY)
40523    || (sqlite3OsDeviceCharacteristics(pPager->fd)&SQLITE_IOCAP_SAFE_APPEND) 
40524   ){
40525     memcpy(zHeader, aJournalMagic, sizeof(aJournalMagic));
40526     put32bits(&zHeader[sizeof(aJournalMagic)], 0xffffffff);
40527   }else{
40528     memset(zHeader, 0, sizeof(aJournalMagic)+4);
40529   }
40530 
40531   /* The random check-hash initializer */ 
40532   sqlite3_randomness(sizeof(pPager->cksumInit), &pPager->cksumInit);
40533   put32bits(&zHeader[sizeof(aJournalMagic)+4], pPager->cksumInit);
40534   /* The initial database size */
40535   put32bits(&zHeader[sizeof(aJournalMagic)+8], pPager->dbOrigSize);
40536   /* The assumed sector size for this process */
40537   put32bits(&zHeader[sizeof(aJournalMagic)+12], pPager->sectorSize);
40538 
40539   /* The page size */
40540   put32bits(&zHeader[sizeof(aJournalMagic)+16], pPager->pageSize);
40541 
40542   /* Initializing the tail of the buffer is not necessary.  Everything
40543   ** works find if the following memset() is omitted.  But initializing
40544   ** the memory prevents valgrind from complaining, so we are willing to
40545   ** take the performance hit.
40546   */
40547   memset(&zHeader[sizeof(aJournalMagic)+20], 0,
40548          nHeader-(sizeof(aJournalMagic)+20));
40549 
40550   /* In theory, it is only necessary to write the 28 bytes that the 
40551   ** journal header consumes to the journal file here. Then increment the 
40552   ** Pager.journalOff variable by JOURNAL_HDR_SZ so that the next 
40553   ** record is written to the following sector (leaving a gap in the file
40554   ** that will be implicitly filled in by the OS).
40555   **
40556   ** However it has been discovered that on some systems this pattern can 
40557   ** be significantly slower than contiguously writing data to the file,
40558   ** even if that means explicitly writing data to the block of 
40559   ** (JOURNAL_HDR_SZ - 28) bytes that will not be used. So that is what
40560   ** is done. 
40561   **
40562   ** The loop is required here in case the sector-size is larger than the 
40563   ** database page size. Since the zHeader buffer is only Pager.pageSize
40564   ** bytes in size, more than one call to sqlite3OsWrite() may be required
40565   ** to populate the entire journal header sector.
40566   */ 
40567   for(nWrite=0; rc==SQLITE_OK&&nWrite<JOURNAL_HDR_SZ(pPager); nWrite+=nHeader){
40568     IOTRACE(("JHDR %p %lld %d\n", pPager, pPager->journalHdr, nHeader))
40569     rc = sqlite3OsWrite(pPager->jfd, zHeader, nHeader, pPager->journalOff);
40570     assert( pPager->journalHdr <= pPager->journalOff );
40571     pPager->journalOff += nHeader;
40572   }
40573 
40574   return rc;
40575 }
40576 
40577 /*
40578 ** The journal file must be open when this is called. A journal header file
40579 ** (JOURNAL_HDR_SZ bytes) is read from the current location in the journal
40580 ** file. The current location in the journal file is given by
40581 ** pPager->journalOff. See comments above function writeJournalHdr() for
40582 ** a description of the journal header format.
40583 **
40584 ** If the header is read successfully, *pNRec is set to the number of
40585 ** page records following this header and *pDbSize is set to the size of the
40586 ** database before the transaction began, in pages. Also, pPager->cksumInit
40587 ** is set to the value read from the journal header. SQLITE_OK is returned
40588 ** in this case.
40589 **
40590 ** If the journal header file appears to be corrupted, SQLITE_DONE is
40591 ** returned and *pNRec and *PDbSize are undefined.  If JOURNAL_HDR_SZ bytes
40592 ** cannot be read from the journal file an error code is returned.
40593 */
40594 static int readJournalHdr(
40595   Pager *pPager,               /* Pager object */
40596   int isHot,
40597   i64 journalSize,             /* Size of the open journal file in bytes */
40598   u32 *pNRec,                  /* OUT: Value read from the nRec field */
40599   u32 *pDbSize                 /* OUT: Value of original database size field */
40600 ){
40601   int rc;                      /* Return code */
40602   unsigned char aMagic[8];     /* A buffer to hold the magic header */
40603   i64 iHdrOff;                 /* Offset of journal header being read */
40604 
40605   assert( isOpen(pPager->jfd) );      /* Journal file must be open. */
40606 
40607   /* Advance Pager.journalOff to the start of the next sector. If the
40608   ** journal file is too small for there to be a header stored at this
40609   ** point, return SQLITE_DONE.
40610   */
40611   pPager->journalOff = journalHdrOffset(pPager);
40612   if( pPager->journalOff+JOURNAL_HDR_SZ(pPager) > journalSize ){
40613     return SQLITE_DONE;
40614   }
40615   iHdrOff = pPager->journalOff;
40616 
40617   /* Read in the first 8 bytes of the journal header. If they do not match
40618   ** the  magic string found at the start of each journal header, return
40619   ** SQLITE_DONE. If an IO error occurs, return an error code. Otherwise,
40620   ** proceed.
40621   */
40622   if( isHot || iHdrOff!=pPager->journalHdr ){
40623     rc = sqlite3OsRead(pPager->jfd, aMagic, sizeof(aMagic), iHdrOff);
40624     if( rc ){
40625       return rc;
40626     }
40627     if( memcmp(aMagic, aJournalMagic, sizeof(aMagic))!=0 ){
40628       return SQLITE_DONE;
40629     }
40630   }
40631 
40632   /* Read the first three 32-bit fields of the journal header: The nRec
40633   ** field, the checksum-initializer and the database size at the start
40634   ** of the transaction. Return an error code if anything goes wrong.
40635   */
40636   if( SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+8, pNRec))
40637    || SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+12, &pPager->cksumInit))
40638    || SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+16, pDbSize))
40639   ){
40640     return rc;
40641   }
40642 
40643   if( pPager->journalOff==0 ){
40644     u32 iPageSize;               /* Page-size field of journal header */
40645     u32 iSectorSize;             /* Sector-size field of journal header */
40646 
40647     /* Read the page-size and sector-size journal header fields. */
40648     if( SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+20, &iSectorSize))
40649      || SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+24, &iPageSize))
40650     ){
40651       return rc;
40652     }
40653 
40654     /* Versions of SQLite prior to 3.5.8 set the page-size field of the
40655     ** journal header to zero. In this case, assume that the Pager.pageSize
40656     ** variable is already set to the correct page size.
40657     */
40658     if( iPageSize==0 ){
40659       iPageSize = pPager->pageSize;
40660     }
40661 
40662     /* Check that the values read from the page-size and sector-size fields
40663     ** are within range. To be 'in range', both values need to be a power
40664     ** of two greater than or equal to 512 or 32, and not greater than their 
40665     ** respective compile time maximum limits.
40666     */
40667     if( iPageSize<512                  || iSectorSize<32
40668      || iPageSize>SQLITE_MAX_PAGE_SIZE || iSectorSize>MAX_SECTOR_SIZE
40669      || ((iPageSize-1)&iPageSize)!=0   || ((iSectorSize-1)&iSectorSize)!=0 
40670     ){
40671       /* If the either the page-size or sector-size in the journal-header is 
40672       ** invalid, then the process that wrote the journal-header must have 
40673       ** crashed before the header was synced. In this case stop reading 
40674       ** the journal file here.
40675       */
40676       return SQLITE_DONE;
40677     }
40678 
40679     /* Update the page-size to match the value read from the journal. 
40680     ** Use a testcase() macro to make sure that malloc failure within 
40681     ** PagerSetPagesize() is tested.
40682     */
40683     rc = sqlite3PagerSetPagesize(pPager, &iPageSize, -1);
40684     testcase( rc!=SQLITE_OK );
40685 
40686     /* Update the assumed sector-size to match the value used by 
40687     ** the process that created this journal. If this journal was
40688     ** created by a process other than this one, then this routine
40689     ** is being called from within pager_playback(). The local value
40690     ** of Pager.sectorSize is restored at the end of that routine.
40691     */
40692     pPager->sectorSize = iSectorSize;
40693   }
40694 
40695   pPager->journalOff += JOURNAL_HDR_SZ(pPager);
40696   return rc;
40697 }
40698 
40699 
40700 /*
40701 ** Write the supplied master journal name into the journal file for pager
40702 ** pPager at the current location. The master journal name must be the last
40703 ** thing written to a journal file. If the pager is in full-sync mode, the
40704 ** journal file descriptor is advanced to the next sector boundary before
40705 ** anything is written. The format is:
40706 **
40707 **   + 4 bytes: PAGER_MJ_PGNO.
40708 **   + N bytes: Master journal filename in utf-8.
40709 **   + 4 bytes: N (length of master journal name in bytes, no nul-terminator).
40710 **   + 4 bytes: Master journal name checksum.
40711 **   + 8 bytes: aJournalMagic[].
40712 **
40713 ** The master journal page checksum is the sum of the bytes in the master
40714 ** journal name, where each byte is interpreted as a signed 8-bit integer.
40715 **
40716 ** If zMaster is a NULL pointer (occurs for a single database transaction), 
40717 ** this call is a no-op.
40718 */
40719 static int writeMasterJournal(Pager *pPager, const char *zMaster){
40720   int rc;                          /* Return code */
40721   int nMaster;                     /* Length of string zMaster */
40722   i64 iHdrOff;                     /* Offset of header in journal file */
40723   i64 jrnlSize;                    /* Size of journal file on disk */
40724   u32 cksum = 0;                   /* Checksum of string zMaster */
40725 
40726   assert( pPager->setMaster==0 );
40727   assert( !pagerUseWal(pPager) );
40728 
40729   if( !zMaster 
40730    || pPager->journalMode==PAGER_JOURNALMODE_MEMORY 
40731    || pPager->journalMode==PAGER_JOURNALMODE_OFF 
40732   ){
40733     return SQLITE_OK;
40734   }
40735   pPager->setMaster = 1;
40736   assert( isOpen(pPager->jfd) );
40737   assert( pPager->journalHdr <= pPager->journalOff );
40738 
40739   /* Calculate the length in bytes and the checksum of zMaster */
40740   for(nMaster=0; zMaster[nMaster]; nMaster++){
40741     cksum += zMaster[nMaster];
40742   }
40743 
40744   /* If in full-sync mode, advance to the next disk sector before writing
40745   ** the master journal name. This is in case the previous page written to
40746   ** the journal has already been synced.
40747   */
40748   if( pPager->fullSync ){
40749     pPager->journalOff = journalHdrOffset(pPager);
40750   }
40751   iHdrOff = pPager->journalOff;
40752 
40753   /* Write the master journal data to the end of the journal file. If
40754   ** an error occurs, return the error code to the caller.
40755   */
40756   if( (0 != (rc = write32bits(pPager->jfd, iHdrOff, PAGER_MJ_PGNO(pPager))))
40757    || (0 != (rc = sqlite3OsWrite(pPager->jfd, zMaster, nMaster, iHdrOff+4)))
40758    || (0 != (rc = write32bits(pPager->jfd, iHdrOff+4+nMaster, nMaster)))
40759    || (0 != (rc = write32bits(pPager->jfd, iHdrOff+4+nMaster+4, cksum)))
40760    || (0 != (rc = sqlite3OsWrite(pPager->jfd, aJournalMagic, 8, iHdrOff+4+nMaster+8)))
40761   ){
40762     return rc;
40763   }
40764   pPager->journalOff += (nMaster+20);
40765 
40766   /* If the pager is in peristent-journal mode, then the physical 
40767   ** journal-file may extend past the end of the master-journal name
40768   ** and 8 bytes of magic data just written to the file. This is 
40769   ** dangerous because the code to rollback a hot-journal file
40770   ** will not be able to find the master-journal name to determine 
40771   ** whether or not the journal is hot. 
40772   **
40773   ** Easiest thing to do in this scenario is to truncate the journal 
40774   ** file to the required size.
40775   */ 
40776   if( SQLITE_OK==(rc = sqlite3OsFileSize(pPager->jfd, &jrnlSize))
40777    && jrnlSize>pPager->journalOff
40778   ){
40779     rc = sqlite3OsTruncate(pPager->jfd, pPager->journalOff);
40780   }
40781   return rc;
40782 }
40783 
40784 /*
40785 ** Find a page in the hash table given its page number. Return
40786 ** a pointer to the page or NULL if the requested page is not 
40787 ** already in memory.
40788 */
40789 static PgHdr *pager_lookup(Pager *pPager, Pgno pgno){
40790   PgHdr *p;                         /* Return value */
40791 
40792   /* It is not possible for a call to PcacheFetch() with createFlag==0 to
40793   ** fail, since no attempt to allocate dynamic memory will be made.
40794   */
40795   (void)sqlite3PcacheFetch(pPager->pPCache, pgno, 0, &p);
40796   return p;
40797 }
40798 
40799 /*
40800 ** Discard the entire contents of the in-memory page-cache.
40801 */
40802 static void pager_reset(Pager *pPager){
40803   sqlite3BackupRestart(pPager->pBackup);
40804   sqlite3PcacheClear(pPager->pPCache);
40805 }
40806 
40807 /*
40808 ** Free all structures in the Pager.aSavepoint[] array and set both
40809 ** Pager.aSavepoint and Pager.nSavepoint to zero. Close the sub-journal
40810 ** if it is open and the pager is not in exclusive mode.
40811 */
40812 static void releaseAllSavepoints(Pager *pPager){
40813   int ii;               /* Iterator for looping through Pager.aSavepoint */
40814   for(ii=0; ii<pPager->nSavepoint; ii++){
40815     sqlite3BitvecDestroy(pPager->aSavepoint[ii].pInSavepoint);
40816   }
40817   if( !pPager->exclusiveMode || sqlite3IsMemJournal(pPager->sjfd) ){
40818     sqlite3OsClose(pPager->sjfd);
40819   }
40820   sqlite3_free(pPager->aSavepoint);
40821   pPager->aSavepoint = 0;
40822   pPager->nSavepoint = 0;
40823   pPager->nSubRec = 0;
40824 }
40825 
40826 /*
40827 ** Set the bit number pgno in the PagerSavepoint.pInSavepoint 
40828 ** bitvecs of all open savepoints. Return SQLITE_OK if successful
40829 ** or SQLITE_NOMEM if a malloc failure occurs.
40830 */
40831 static int addToSavepointBitvecs(Pager *pPager, Pgno pgno){
40832   int ii;                   /* Loop counter */
40833   int rc = SQLITE_OK;       /* Result code */
40834 
40835   for(ii=0; ii<pPager->nSavepoint; ii++){
40836     PagerSavepoint *p = &pPager->aSavepoint[ii];
40837     if( pgno<=p->nOrig ){
40838       rc |= sqlite3BitvecSet(p->pInSavepoint, pgno);
40839       testcase( rc==SQLITE_NOMEM );
40840       assert( rc==SQLITE_OK || rc==SQLITE_NOMEM );
40841     }
40842   }
40843   return rc;
40844 }
40845 
40846 /*
40847 ** This function is a no-op if the pager is in exclusive mode and not
40848 ** in the ERROR state. Otherwise, it switches the pager to PAGER_OPEN
40849 ** state.
40850 **
40851 ** If the pager is not in exclusive-access mode, the database file is
40852 ** completely unlocked. If the file is unlocked and the file-system does
40853 ** not exhibit the UNDELETABLE_WHEN_OPEN property, the journal file is
40854 ** closed (if it is open).
40855 **
40856 ** If the pager is in ERROR state when this function is called, the 
40857 ** contents of the pager cache are discarded before switching back to 
40858 ** the OPEN state. Regardless of whether the pager is in exclusive-mode
40859 ** or not, any journal file left in the file-system will be treated
40860 ** as a hot-journal and rolled back the next time a read-transaction
40861 ** is opened (by this or by any other connection).
40862 */
40863 static void pager_unlock(Pager *pPager){
40864 
40865   assert( pPager->eState==PAGER_READER 
40866        || pPager->eState==PAGER_OPEN 
40867        || pPager->eState==PAGER_ERROR 
40868   );
40869 
40870   sqlite3BitvecDestroy(pPager->pInJournal);
40871   pPager->pInJournal = 0;
40872   releaseAllSavepoints(pPager);
40873 
40874   if( pagerUseWal(pPager) ){
40875     assert( !isOpen(pPager->jfd) );
40876     sqlite3WalEndReadTransaction(pPager->pWal);
40877     pPager->eState = PAGER_OPEN;
40878   }else if( !pPager->exclusiveMode ){
40879     int rc;                       /* Error code returned by pagerUnlockDb() */
40880     int iDc = isOpen(pPager->fd)?sqlite3OsDeviceCharacteristics(pPager->fd):0;
40881 
40882     /* If the operating system support deletion of open files, then
40883     ** close the journal file when dropping the database lock.  Otherwise
40884     ** another connection with journal_mode=delete might delete the file
40885     ** out from under us.
40886     */
40887     assert( (PAGER_JOURNALMODE_MEMORY   & 5)!=1 );
40888     assert( (PAGER_JOURNALMODE_OFF      & 5)!=1 );
40889     assert( (PAGER_JOURNALMODE_WAL      & 5)!=1 );
40890     assert( (PAGER_JOURNALMODE_DELETE   & 5)!=1 );
40891     assert( (PAGER_JOURNALMODE_TRUNCATE & 5)==1 );
40892     assert( (PAGER_JOURNALMODE_PERSIST  & 5)==1 );
40893     if( 0==(iDc & SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN)
40894      || 1!=(pPager->journalMode & 5)
40895     ){
40896       sqlite3OsClose(pPager->jfd);
40897     }
40898 
40899     /* If the pager is in the ERROR state and the call to unlock the database
40900     ** file fails, set the current lock to UNKNOWN_LOCK. See the comment
40901     ** above the #define for UNKNOWN_LOCK for an explanation of why this
40902     ** is necessary.
40903     */
40904     rc = pagerUnlockDb(pPager, NO_LOCK);
40905     if( rc!=SQLITE_OK && pPager->eState==PAGER_ERROR ){
40906       pPager->eLock = UNKNOWN_LOCK;
40907     }
40908 
40909     /* The pager state may be changed from PAGER_ERROR to PAGER_OPEN here
40910     ** without clearing the error code. This is intentional - the error
40911     ** code is cleared and the cache reset in the block below.
40912     */
40913     assert( pPager->errCode || pPager->eState!=PAGER_ERROR );
40914     pPager->changeCountDone = 0;
40915     pPager->eState = PAGER_OPEN;
40916   }
40917 
40918   /* If Pager.errCode is set, the contents of the pager cache cannot be
40919   ** trusted. Now that there are no outstanding references to the pager,
40920   ** it can safely move back to PAGER_OPEN state. This happens in both
40921   ** normal and exclusive-locking mode.
40922   */
40923   if( pPager->errCode ){
40924     assert( !MEMDB );
40925     pager_reset(pPager);
40926     pPager->changeCountDone = pPager->tempFile;
40927     pPager->eState = PAGER_OPEN;
40928     pPager->errCode = SQLITE_OK;
40929     if( USEFETCH(pPager) ) sqlite3OsUnfetch(pPager->fd, 0, 0);
40930   }
40931 
40932   pPager->journalOff = 0;
40933   pPager->journalHdr = 0;
40934   pPager->setMaster = 0;
40935 }
40936 
40937 /*
40938 ** This function is called whenever an IOERR or FULL error that requires
40939 ** the pager to transition into the ERROR state may ahve occurred.
40940 ** The first argument is a pointer to the pager structure, the second 
40941 ** the error-code about to be returned by a pager API function. The 
40942 ** value returned is a copy of the second argument to this function. 
40943 **
40944 ** If the second argument is SQLITE_FULL, SQLITE_IOERR or one of the
40945 ** IOERR sub-codes, the pager enters the ERROR state and the error code
40946 ** is stored in Pager.errCode. While the pager remains in the ERROR state,
40947 ** all major API calls on the Pager will immediately return Pager.errCode.
40948 **
40949 ** The ERROR state indicates that the contents of the pager-cache 
40950 ** cannot be trusted. This state can be cleared by completely discarding 
40951 ** the contents of the pager-cache. If a transaction was active when
40952 ** the persistent error occurred, then the rollback journal may need
40953 ** to be replayed to restore the contents of the database file (as if
40954 ** it were a hot-journal).
40955 */
40956 static int pager_error(Pager *pPager, int rc){
40957   int rc2 = rc & 0xff;
40958   assert( rc==SQLITE_OK || !MEMDB );
40959   assert(
40960        pPager->errCode==SQLITE_FULL ||
40961        pPager->errCode==SQLITE_OK ||
40962        (pPager->errCode & 0xff)==SQLITE_IOERR
40963   );
40964   if( rc2==SQLITE_FULL || rc2==SQLITE_IOERR ){
40965     pPager->errCode = rc;
40966     pPager->eState = PAGER_ERROR;
40967   }
40968   return rc;
40969 }
40970 
40971 static int pager_truncate(Pager *pPager, Pgno nPage);
40972 
40973 /*
40974 ** This routine ends a transaction. A transaction is usually ended by 
40975 ** either a COMMIT or a ROLLBACK operation. This routine may be called 
40976 ** after rollback of a hot-journal, or if an error occurs while opening
40977 ** the journal file or writing the very first journal-header of a
40978 ** database transaction.
40979 ** 
40980 ** This routine is never called in PAGER_ERROR state. If it is called
40981 ** in PAGER_NONE or PAGER_SHARED state and the lock held is less
40982 ** exclusive than a RESERVED lock, it is a no-op.
40983 **
40984 ** Otherwise, any active savepoints are released.
40985 **
40986 ** If the journal file is open, then it is "finalized". Once a journal 
40987 ** file has been finalized it is not possible to use it to roll back a 
40988 ** transaction. Nor will it be considered to be a hot-journal by this
40989 ** or any other database connection. Exactly how a journal is finalized
40990 ** depends on whether or not the pager is running in exclusive mode and
40991 ** the current journal-mode (Pager.journalMode value), as follows:
40992 **
40993 **   journalMode==MEMORY
40994 **     Journal file descriptor is simply closed. This destroys an 
40995 **     in-memory journal.
40996 **
40997 **   journalMode==TRUNCATE
40998 **     Journal file is truncated to zero bytes in size.
40999 **
41000 **   journalMode==PERSIST
41001 **     The first 28 bytes of the journal file are zeroed. This invalidates
41002 **     the first journal header in the file, and hence the entire journal
41003 **     file. An invalid journal file cannot be rolled back.
41004 **
41005 **   journalMode==DELETE
41006 **     The journal file is closed and deleted using sqlite3OsDelete().
41007 **
41008 **     If the pager is running in exclusive mode, this method of finalizing
41009 **     the journal file is never used. Instead, if the journalMode is
41010 **     DELETE and the pager is in exclusive mode, the method described under
41011 **     journalMode==PERSIST is used instead.
41012 **
41013 ** After the journal is finalized, the pager moves to PAGER_READER state.
41014 ** If running in non-exclusive rollback mode, the lock on the file is 
41015 ** downgraded to a SHARED_LOCK.
41016 **
41017 ** SQLITE_OK is returned if no error occurs. If an error occurs during
41018 ** any of the IO operations to finalize the journal file or unlock the
41019 ** database then the IO error code is returned to the user. If the 
41020 ** operation to finalize the journal file fails, then the code still
41021 ** tries to unlock the database file if not in exclusive mode. If the
41022 ** unlock operation fails as well, then the first error code related
41023 ** to the first error encountered (the journal finalization one) is
41024 ** returned.
41025 */
41026 static int pager_end_transaction(Pager *pPager, int hasMaster, int bCommit){
41027   int rc = SQLITE_OK;      /* Error code from journal finalization operation */
41028   int rc2 = SQLITE_OK;     /* Error code from db file unlock operation */
41029 
41030   /* Do nothing if the pager does not have an open write transaction
41031   ** or at least a RESERVED lock. This function may be called when there
41032   ** is no write-transaction active but a RESERVED or greater lock is
41033   ** held under two circumstances:
41034   **
41035   **   1. After a successful hot-journal rollback, it is called with
41036   **      eState==PAGER_NONE and eLock==EXCLUSIVE_LOCK.
41037   **
41038   **   2. If a connection with locking_mode=exclusive holding an EXCLUSIVE 
41039   **      lock switches back to locking_mode=normal and then executes a
41040   **      read-transaction, this function is called with eState==PAGER_READER 
41041   **      and eLock==EXCLUSIVE_LOCK when the read-transaction is closed.
41042   */
41043   assert( assert_pager_state(pPager) );
41044   assert( pPager->eState!=PAGER_ERROR );
41045   if( pPager->eState<PAGER_WRITER_LOCKED && pPager->eLock<RESERVED_LOCK ){
41046     return SQLITE_OK;
41047   }
41048 
41049   releaseAllSavepoints(pPager);
41050   assert( isOpen(pPager->jfd) || pPager->pInJournal==0 );
41051   if( isOpen(pPager->jfd) ){
41052     assert( !pagerUseWal(pPager) );
41053 
41054     /* Finalize the journal file. */
41055     if( sqlite3IsMemJournal(pPager->jfd) ){
41056       assert( pPager->journalMode==PAGER_JOURNALMODE_MEMORY );
41057       sqlite3OsClose(pPager->jfd);
41058     }else if( pPager->journalMode==PAGER_JOURNALMODE_TRUNCATE ){
41059       if( pPager->journalOff==0 ){
41060         rc = SQLITE_OK;
41061       }else{
41062         rc = sqlite3OsTruncate(pPager->jfd, 0);
41063       }
41064       pPager->journalOff = 0;
41065     }else if( pPager->journalMode==PAGER_JOURNALMODE_PERSIST
41066       || (pPager->exclusiveMode && pPager->journalMode!=PAGER_JOURNALMODE_WAL)
41067     ){
41068       rc = zeroJournalHdr(pPager, hasMaster);
41069       pPager->journalOff = 0;
41070     }else{
41071       /* This branch may be executed with Pager.journalMode==MEMORY if
41072       ** a hot-journal was just rolled back. In this case the journal
41073       ** file should be closed and deleted. If this connection writes to
41074       ** the database file, it will do so using an in-memory journal. 
41075       */
41076       int bDelete = (!pPager->tempFile && sqlite3JournalExists(pPager->jfd));
41077       assert( pPager->journalMode==PAGER_JOURNALMODE_DELETE 
41078            || pPager->journalMode==PAGER_JOURNALMODE_MEMORY 
41079            || pPager->journalMode==PAGER_JOURNALMODE_WAL 
41080       );
41081       sqlite3OsClose(pPager->jfd);
41082       if( bDelete ){
41083         rc = sqlite3OsDelete(pPager->pVfs, pPager->zJournal, 0);
41084       }
41085     }
41086   }
41087 
41088 #ifdef SQLITE_CHECK_PAGES
41089   sqlite3PcacheIterateDirty(pPager->pPCache, pager_set_pagehash);
41090   if( pPager->dbSize==0 && sqlite3PcacheRefCount(pPager->pPCache)>0 ){
41091     PgHdr *p = pager_lookup(pPager, 1);
41092     if( p ){
41093       p->pageHash = 0;
41094       sqlite3PagerUnref(p);
41095     }
41096   }
41097 #endif
41098 
41099   sqlite3BitvecDestroy(pPager->pInJournal);
41100   pPager->pInJournal = 0;
41101   pPager->nRec = 0;
41102   sqlite3PcacheCleanAll(pPager->pPCache);
41103   sqlite3PcacheTruncate(pPager->pPCache, pPager->dbSize);
41104 
41105   if( pagerUseWal(pPager) ){
41106     /* Drop the WAL write-lock, if any. Also, if the connection was in 
41107     ** locking_mode=exclusive mode but is no longer, drop the EXCLUSIVE 
41108     ** lock held on the database file.
41109     */
41110     rc2 = sqlite3WalEndWriteTransaction(pPager->pWal);
41111     assert( rc2==SQLITE_OK );
41112   }else if( rc==SQLITE_OK && bCommit && pPager->dbFileSize>pPager->dbSize ){
41113     /* This branch is taken when committing a transaction in rollback-journal
41114     ** mode if the database file on disk is larger than the database image.
41115     ** At this point the journal has been finalized and the transaction 
41116     ** successfully committed, but the EXCLUSIVE lock is still held on the
41117     ** file. So it is safe to truncate the database file to its minimum
41118     ** required size.  */
41119     assert( pPager->eLock==EXCLUSIVE_LOCK );
41120     rc = pager_truncate(pPager, pPager->dbSize);
41121   }
41122 
41123   if( !pPager->exclusiveMode 
41124    && (!pagerUseWal(pPager) || sqlite3WalExclusiveMode(pPager->pWal, 0))
41125   ){
41126     rc2 = pagerUnlockDb(pPager, SHARED_LOCK);
41127     pPager->changeCountDone = 0;
41128   }
41129   pPager->eState = PAGER_READER;
41130   pPager->setMaster = 0;
41131 
41132   return (rc==SQLITE_OK?rc2:rc);
41133 }
41134 
41135 /*
41136 ** Execute a rollback if a transaction is active and unlock the 
41137 ** database file. 
41138 **
41139 ** If the pager has already entered the ERROR state, do not attempt 
41140 ** the rollback at this time. Instead, pager_unlock() is called. The
41141 ** call to pager_unlock() will discard all in-memory pages, unlock
41142 ** the database file and move the pager back to OPEN state. If this 
41143 ** means that there is a hot-journal left in the file-system, the next 
41144 ** connection to obtain a shared lock on the pager (which may be this one) 
41145 ** will roll it back.
41146 **
41147 ** If the pager has not already entered the ERROR state, but an IO or
41148 ** malloc error occurs during a rollback, then this will itself cause 
41149 ** the pager to enter the ERROR state. Which will be cleared by the
41150 ** call to pager_unlock(), as described above.
41151 */
41152 static void pagerUnlockAndRollback(Pager *pPager){
41153   if( pPager->eState!=PAGER_ERROR && pPager->eState!=PAGER_OPEN ){
41154     assert( assert_pager_state(pPager) );
41155     if( pPager->eState>=PAGER_WRITER_LOCKED ){
41156       sqlite3BeginBenignMalloc();
41157       sqlite3PagerRollback(pPager);
41158       sqlite3EndBenignMalloc();
41159     }else if( !pPager->exclusiveMode ){
41160       assert( pPager->eState==PAGER_READER );
41161       pager_end_transaction(pPager, 0, 0);
41162     }
41163   }
41164   pager_unlock(pPager);
41165 }
41166 
41167 /*
41168 ** Parameter aData must point to a buffer of pPager->pageSize bytes
41169 ** of data. Compute and return a checksum based ont the contents of the 
41170 ** page of data and the current value of pPager->cksumInit.
41171 **
41172 ** This is not a real checksum. It is really just the sum of the 
41173 ** random initial value (pPager->cksumInit) and every 200th byte
41174 ** of the page data, starting with byte offset (pPager->pageSize%200).
41175 ** Each byte is interpreted as an 8-bit unsigned integer.
41176 **
41177 ** Changing the formula used to compute this checksum results in an
41178 ** incompatible journal file format.
41179 **
41180 ** If journal corruption occurs due to a power failure, the most likely 
41181 ** scenario is that one end or the other of the record will be changed. 
41182 ** It is much less likely that the two ends of the journal record will be
41183 ** correct and the middle be corrupt.  Thus, this "checksum" scheme,
41184 ** though fast and simple, catches the mostly likely kind of corruption.
41185 */
41186 static u32 pager_cksum(Pager *pPager, const u8 *aData){
41187   u32 cksum = pPager->cksumInit;         /* Checksum value to return */
41188   int i = pPager->pageSize-200;          /* Loop counter */
41189   while( i>0 ){
41190     cksum += aData[i];
41191     i -= 200;
41192   }
41193   return cksum;
41194 }
41195 
41196 /*
41197 ** Report the current page size and number of reserved bytes back
41198 ** to the codec.
41199 */
41200 #ifdef SQLITE_HAS_CODEC
41201 static void pagerReportSize(Pager *pPager){
41202   if( pPager->xCodecSizeChng ){
41203     pPager->xCodecSizeChng(pPager->pCodec, pPager->pageSize,
41204                            (int)pPager->nReserve);
41205   }
41206 }
41207 #else
41208 # define pagerReportSize(X)     /* No-op if we do not support a codec */
41209 #endif
41210 
41211 /*
41212 ** Read a single page from either the journal file (if isMainJrnl==1) or
41213 ** from the sub-journal (if isMainJrnl==0) and playback that page.
41214 ** The page begins at offset *pOffset into the file. The *pOffset
41215 ** value is increased to the start of the next page in the journal.
41216 **
41217 ** The main rollback journal uses checksums - the statement journal does 
41218 ** not.
41219 **
41220 ** If the page number of the page record read from the (sub-)journal file
41221 ** is greater than the current value of Pager.dbSize, then playback is
41222 ** skipped and SQLITE_OK is returned.
41223 **
41224 ** If pDone is not NULL, then it is a record of pages that have already
41225 ** been played back.  If the page at *pOffset has already been played back
41226 ** (if the corresponding pDone bit is set) then skip the playback.
41227 ** Make sure the pDone bit corresponding to the *pOffset page is set
41228 ** prior to returning.
41229 **
41230 ** If the page record is successfully read from the (sub-)journal file
41231 ** and played back, then SQLITE_OK is returned. If an IO error occurs
41232 ** while reading the record from the (sub-)journal file or while writing
41233 ** to the database file, then the IO error code is returned. If data
41234 ** is successfully read from the (sub-)journal file but appears to be
41235 ** corrupted, SQLITE_DONE is returned. Data is considered corrupted in
41236 ** two circumstances:
41237 ** 
41238 **   * If the record page-number is illegal (0 or PAGER_MJ_PGNO), or
41239 **   * If the record is being rolled back from the main journal file
41240 **     and the checksum field does not match the record content.
41241 **
41242 ** Neither of these two scenarios are possible during a savepoint rollback.
41243 **
41244 ** If this is a savepoint rollback, then memory may have to be dynamically
41245 ** allocated by this function. If this is the case and an allocation fails,
41246 ** SQLITE_NOMEM is returned.
41247 */
41248 static int pager_playback_one_page(
41249   Pager *pPager,                /* The pager being played back */
41250   i64 *pOffset,                 /* Offset of record to playback */
41251   Bitvec *pDone,                /* Bitvec of pages already played back */
41252   int isMainJrnl,               /* 1 -> main journal. 0 -> sub-journal. */
41253   int isSavepnt                 /* True for a savepoint rollback */
41254 ){
41255   int rc;
41256   PgHdr *pPg;                   /* An existing page in the cache */
41257   Pgno pgno;                    /* The page number of a page in journal */
41258   u32 cksum;                    /* Checksum used for sanity checking */
41259   char *aData;                  /* Temporary storage for the page */
41260   sqlite3_file *jfd;            /* The file descriptor for the journal file */
41261   int isSynced;                 /* True if journal page is synced */
41262 
41263   assert( (isMainJrnl&~1)==0 );      /* isMainJrnl is 0 or 1 */
41264   assert( (isSavepnt&~1)==0 );       /* isSavepnt is 0 or 1 */
41265   assert( isMainJrnl || pDone );     /* pDone always used on sub-journals */
41266   assert( isSavepnt || pDone==0 );   /* pDone never used on non-savepoint */
41267 
41268   aData = pPager->pTmpSpace;
41269   assert( aData );         /* Temp storage must have already been allocated */
41270   assert( pagerUseWal(pPager)==0 || (!isMainJrnl && isSavepnt) );
41271 
41272   /* Either the state is greater than PAGER_WRITER_CACHEMOD (a transaction 
41273   ** or savepoint rollback done at the request of the caller) or this is
41274   ** a hot-journal rollback. If it is a hot-journal rollback, the pager
41275   ** is in state OPEN and holds an EXCLUSIVE lock. Hot-journal rollback
41276   ** only reads from the main journal, not the sub-journal.
41277   */
41278   assert( pPager->eState>=PAGER_WRITER_CACHEMOD
41279        || (pPager->eState==PAGER_OPEN && pPager->eLock==EXCLUSIVE_LOCK)
41280   );
41281   assert( pPager->eState>=PAGER_WRITER_CACHEMOD || isMainJrnl );
41282 
41283   /* Read the page number and page data from the journal or sub-journal
41284   ** file. Return an error code to the caller if an IO error occurs.
41285   */
41286   jfd = isMainJrnl ? pPager->jfd : pPager->sjfd;
41287   rc = read32bits(jfd, *pOffset, &pgno);
41288   if( rc!=SQLITE_OK ) return rc;
41289   rc = sqlite3OsRead(jfd, (u8*)aData, pPager->pageSize, (*pOffset)+4);
41290   if( rc!=SQLITE_OK ) return rc;
41291   *pOffset += pPager->pageSize + 4 + isMainJrnl*4;
41292 
41293   /* Sanity checking on the page.  This is more important that I originally
41294   ** thought.  If a power failure occurs while the journal is being written,
41295   ** it could cause invalid data to be written into the journal.  We need to
41296   ** detect this invalid data (with high probability) and ignore it.
41297   */
41298   if( pgno==0 || pgno==PAGER_MJ_PGNO(pPager) ){
41299     assert( !isSavepnt );
41300     return SQLITE_DONE;
41301   }
41302   if( pgno>(Pgno)pPager->dbSize || sqlite3BitvecTest(pDone, pgno) ){
41303     return SQLITE_OK;
41304   }
41305   if( isMainJrnl ){
41306     rc = read32bits(jfd, (*pOffset)-4, &cksum);
41307     if( rc ) return rc;
41308     if( !isSavepnt && pager_cksum(pPager, (u8*)aData)!=cksum ){
41309       return SQLITE_DONE;
41310     }
41311   }
41312 
41313   /* If this page has already been played by before during the current
41314   ** rollback, then don't bother to play it back again.
41315   */
41316   if( pDone && (rc = sqlite3BitvecSet(pDone, pgno))!=SQLITE_OK ){
41317     return rc;
41318   }
41319 
41320   /* When playing back page 1, restore the nReserve setting
41321   */
41322   if( pgno==1 && pPager->nReserve!=((u8*)aData)[20] ){
41323     pPager->nReserve = ((u8*)aData)[20];
41324     pagerReportSize(pPager);
41325   }
41326 
41327   /* If the pager is in CACHEMOD state, then there must be a copy of this
41328   ** page in the pager cache. In this case just update the pager cache,
41329   ** not the database file. The page is left marked dirty in this case.
41330   **
41331   ** An exception to the above rule: If the database is in no-sync mode
41332   ** and a page is moved during an incremental vacuum then the page may
41333   ** not be in the pager cache. Later: if a malloc() or IO error occurs
41334   ** during a Movepage() call, then the page may not be in the cache
41335   ** either. So the condition described in the above paragraph is not
41336   ** assert()able.
41337   **
41338   ** If in WRITER_DBMOD, WRITER_FINISHED or OPEN state, then we update the
41339   ** pager cache if it exists and the main file. The page is then marked 
41340   ** not dirty. Since this code is only executed in PAGER_OPEN state for
41341   ** a hot-journal rollback, it is guaranteed that the page-cache is empty
41342   ** if the pager is in OPEN state.
41343   **
41344   ** Ticket #1171:  The statement journal might contain page content that is
41345   ** different from the page content at the start of the transaction.
41346   ** This occurs when a page is changed prior to the start of a statement
41347   ** then changed again within the statement.  When rolling back such a
41348   ** statement we must not write to the original database unless we know
41349   ** for certain that original page contents are synced into the main rollback
41350   ** journal.  Otherwise, a power loss might leave modified data in the
41351   ** database file without an entry in the rollback journal that can
41352   ** restore the database to its original form.  Two conditions must be
41353   ** met before writing to the database files. (1) the database must be
41354   ** locked.  (2) we know that the original page content is fully synced
41355   ** in the main journal either because the page is not in cache or else
41356   ** the page is marked as needSync==0.
41357   **
41358   ** 2008-04-14:  When attempting to vacuum a corrupt database file, it
41359   ** is possible to fail a statement on a database that does not yet exist.
41360   ** Do not attempt to write if database file has never been opened.
41361   */
41362   if( pagerUseWal(pPager) ){
41363     pPg = 0;
41364   }else{
41365     pPg = pager_lookup(pPager, pgno);
41366   }
41367   assert( pPg || !MEMDB );
41368   assert( pPager->eState!=PAGER_OPEN || pPg==0 );
41369   PAGERTRACE(("PLAYBACK %d page %d hash(%08x) %s\n",
41370            PAGERID(pPager), pgno, pager_datahash(pPager->pageSize, (u8*)aData),
41371            (isMainJrnl?"main-journal":"sub-journal")
41372   ));
41373   if( isMainJrnl ){
41374     isSynced = pPager->noSync || (*pOffset <= pPager->journalHdr);
41375   }else{
41376     isSynced = (pPg==0 || 0==(pPg->flags & PGHDR_NEED_SYNC));
41377   }
41378   if( isOpen(pPager->fd)
41379    && (pPager->eState>=PAGER_WRITER_DBMOD || pPager->eState==PAGER_OPEN)
41380    && isSynced
41381   ){
41382     i64 ofst = (pgno-1)*(i64)pPager->pageSize;
41383     testcase( !isSavepnt && pPg!=0 && (pPg->flags&PGHDR_NEED_SYNC)!=0 );
41384     assert( !pagerUseWal(pPager) );
41385     rc = sqlite3OsWrite(pPager->fd, (u8 *)aData, pPager->pageSize, ofst);
41386     if( pgno>pPager->dbFileSize ){
41387       pPager->dbFileSize = pgno;
41388     }
41389     if( pPager->pBackup ){
41390       CODEC1(pPager, aData, pgno, 3, rc=SQLITE_NOMEM);
41391       sqlite3BackupUpdate(pPager->pBackup, pgno, (u8*)aData);
41392       CODEC2(pPager, aData, pgno, 7, rc=SQLITE_NOMEM, aData);
41393     }
41394   }else if( !isMainJrnl && pPg==0 ){
41395     /* If this is a rollback of a savepoint and data was not written to
41396     ** the database and the page is not in-memory, there is a potential
41397     ** problem. When the page is next fetched by the b-tree layer, it 
41398     ** will be read from the database file, which may or may not be 
41399     ** current. 
41400     **
41401     ** There are a couple of different ways this can happen. All are quite
41402     ** obscure. When running in synchronous mode, this can only happen 
41403     ** if the page is on the free-list at the start of the transaction, then
41404     ** populated, then moved using sqlite3PagerMovepage().
41405     **
41406     ** The solution is to add an in-memory page to the cache containing
41407     ** the data just read from the sub-journal. Mark the page as dirty 
41408     ** and if the pager requires a journal-sync, then mark the page as 
41409     ** requiring a journal-sync before it is written.
41410     */
41411     assert( isSavepnt );
41412     assert( (pPager->doNotSpill & SPILLFLAG_ROLLBACK)==0 );
41413     pPager->doNotSpill |= SPILLFLAG_ROLLBACK;
41414     rc = sqlite3PagerAcquire(pPager, pgno, &pPg, 1);
41415     assert( (pPager->doNotSpill & SPILLFLAG_ROLLBACK)!=0 );
41416     pPager->doNotSpill &= ~SPILLFLAG_ROLLBACK;
41417     if( rc!=SQLITE_OK ) return rc;
41418     pPg->flags &= ~PGHDR_NEED_READ;
41419     sqlite3PcacheMakeDirty(pPg);
41420   }
41421   if( pPg ){
41422     /* No page should ever be explicitly rolled back that is in use, except
41423     ** for page 1 which is held in use in order to keep the lock on the
41424     ** database active. However such a page may be rolled back as a result
41425     ** of an internal error resulting in an automatic call to
41426     ** sqlite3PagerRollback().
41427     */
41428     void *pData;
41429     pData = pPg->pData;
41430     memcpy(pData, (u8*)aData, pPager->pageSize);
41431     pPager->xReiniter(pPg);
41432     if( isMainJrnl && (!isSavepnt || *pOffset<=pPager->journalHdr) ){
41433       /* If the contents of this page were just restored from the main 
41434       ** journal file, then its content must be as they were when the 
41435       ** transaction was first opened. In this case we can mark the page
41436       ** as clean, since there will be no need to write it out to the
41437       ** database.
41438       **
41439       ** There is one exception to this rule. If the page is being rolled
41440       ** back as part of a savepoint (or statement) rollback from an 
41441       ** unsynced portion of the main journal file, then it is not safe
41442       ** to mark the page as clean. This is because marking the page as
41443       ** clean will clear the PGHDR_NEED_SYNC flag. Since the page is
41444       ** already in the journal file (recorded in Pager.pInJournal) and
41445       ** the PGHDR_NEED_SYNC flag is cleared, if the page is written to
41446       ** again within this transaction, it will be marked as dirty but
41447       ** the PGHDR_NEED_SYNC flag will not be set. It could then potentially
41448       ** be written out into the database file before its journal file
41449       ** segment is synced. If a crash occurs during or following this,
41450       ** database corruption may ensue.
41451       */
41452       assert( !pagerUseWal(pPager) );
41453       sqlite3PcacheMakeClean(pPg);
41454     }
41455     pager_set_pagehash(pPg);
41456 
41457     /* If this was page 1, then restore the value of Pager.dbFileVers.
41458     ** Do this before any decoding. */
41459     if( pgno==1 ){
41460       memcpy(&pPager->dbFileVers, &((u8*)pData)[24],sizeof(pPager->dbFileVers));
41461     }
41462 
41463     /* Decode the page just read from disk */
41464     CODEC1(pPager, pData, pPg->pgno, 3, rc=SQLITE_NOMEM);
41465     sqlite3PcacheRelease(pPg);
41466   }
41467   return rc;
41468 }
41469 
41470 /*
41471 ** Parameter zMaster is the name of a master journal file. A single journal
41472 ** file that referred to the master journal file has just been rolled back.
41473 ** This routine checks if it is possible to delete the master journal file,
41474 ** and does so if it is.
41475 **
41476 ** Argument zMaster may point to Pager.pTmpSpace. So that buffer is not 
41477 ** available for use within this function.
41478 **
41479 ** When a master journal file is created, it is populated with the names 
41480 ** of all of its child journals, one after another, formatted as utf-8 
41481 ** encoded text. The end of each child journal file is marked with a 
41482 ** nul-terminator byte (0x00). i.e. the entire contents of a master journal
41483 ** file for a transaction involving two databases might be:
41484 **
41485 **   "/home/bill/a.db-journal\x00/home/bill/b.db-journal\x00"
41486 **
41487 ** A master journal file may only be deleted once all of its child 
41488 ** journals have been rolled back.
41489 **
41490 ** This function reads the contents of the master-journal file into 
41491 ** memory and loops through each of the child journal names. For
41492 ** each child journal, it checks if:
41493 **
41494 **   * if the child journal exists, and if so
41495 **   * if the child journal contains a reference to master journal 
41496 **     file zMaster
41497 **
41498 ** If a child journal can be found that matches both of the criteria
41499 ** above, this function returns without doing anything. Otherwise, if
41500 ** no such child journal can be found, file zMaster is deleted from
41501 ** the file-system using sqlite3OsDelete().
41502 **
41503 ** If an IO error within this function, an error code is returned. This
41504 ** function allocates memory by calling sqlite3Malloc(). If an allocation
41505 ** fails, SQLITE_NOMEM is returned. Otherwise, if no IO or malloc errors 
41506 ** occur, SQLITE_OK is returned.
41507 **
41508 ** TODO: This function allocates a single block of memory to load
41509 ** the entire contents of the master journal file. This could be
41510 ** a couple of kilobytes or so - potentially larger than the page 
41511 ** size.
41512 */
41513 static int pager_delmaster(Pager *pPager, const char *zMaster){
41514   sqlite3_vfs *pVfs = pPager->pVfs;
41515   int rc;                   /* Return code */
41516   sqlite3_file *pMaster;    /* Malloc'd master-journal file descriptor */
41517   sqlite3_file *pJournal;   /* Malloc'd child-journal file descriptor */
41518   char *zMasterJournal = 0; /* Contents of master journal file */
41519   i64 nMasterJournal;       /* Size of master journal file */
41520   char *zJournal;           /* Pointer to one journal within MJ file */
41521   char *zMasterPtr;         /* Space to hold MJ filename from a journal file */
41522   int nMasterPtr;           /* Amount of space allocated to zMasterPtr[] */
41523 
41524   /* Allocate space for both the pJournal and pMaster file descriptors.
41525   ** If successful, open the master journal file for reading.
41526   */
41527   pMaster = (sqlite3_file *)sqlite3MallocZero(pVfs->szOsFile * 2);
41528   pJournal = (sqlite3_file *)(((u8 *)pMaster) + pVfs->szOsFile);
41529   if( !pMaster ){
41530     rc = SQLITE_NOMEM;
41531   }else{
41532     const int flags = (SQLITE_OPEN_READONLY|SQLITE_OPEN_MASTER_JOURNAL);
41533     rc = sqlite3OsOpen(pVfs, zMaster, pMaster, flags, 0);
41534   }
41535   if( rc!=SQLITE_OK ) goto delmaster_out;
41536 
41537   /* Load the entire master journal file into space obtained from
41538   ** sqlite3_malloc() and pointed to by zMasterJournal.   Also obtain
41539   ** sufficient space (in zMasterPtr) to hold the names of master
41540   ** journal files extracted from regular rollback-journals.
41541   */
41542   rc = sqlite3OsFileSize(pMaster, &nMasterJournal);
41543   if( rc!=SQLITE_OK ) goto delmaster_out;
41544   nMasterPtr = pVfs->mxPathname+1;
41545   zMasterJournal = sqlite3Malloc((int)nMasterJournal + nMasterPtr + 1);
41546   if( !zMasterJournal ){
41547     rc = SQLITE_NOMEM;
41548     goto delmaster_out;
41549   }
41550   zMasterPtr = &zMasterJournal[nMasterJournal+1];
41551   rc = sqlite3OsRead(pMaster, zMasterJournal, (int)nMasterJournal, 0);
41552   if( rc!=SQLITE_OK ) goto delmaster_out;
41553   zMasterJournal[nMasterJournal] = 0;
41554 
41555   zJournal = zMasterJournal;
41556   while( (zJournal-zMasterJournal)<nMasterJournal ){
41557     int exists;
41558     rc = sqlite3OsAccess(pVfs, zJournal, SQLITE_ACCESS_EXISTS, &exists);
41559     if( rc!=SQLITE_OK ){
41560       goto delmaster_out;
41561     }
41562     if( exists ){
41563       /* One of the journals pointed to by the master journal exists.
41564       ** Open it and check if it points at the master journal. If
41565       ** so, return without deleting the master journal file.
41566       */
41567       int c;
41568       int flags = (SQLITE_OPEN_READONLY|SQLITE_OPEN_MAIN_JOURNAL);
41569       rc = sqlite3OsOpen(pVfs, zJournal, pJournal, flags, 0);
41570       if( rc!=SQLITE_OK ){
41571         goto delmaster_out;
41572       }
41573 
41574       rc = readMasterJournal(pJournal, zMasterPtr, nMasterPtr);
41575       sqlite3OsClose(pJournal);
41576       if( rc!=SQLITE_OK ){
41577         goto delmaster_out;
41578       }
41579 
41580       c = zMasterPtr[0]!=0 && strcmp(zMasterPtr, zMaster)==0;
41581       if( c ){
41582         /* We have a match. Do not delete the master journal file. */
41583         goto delmaster_out;
41584       }
41585     }
41586     zJournal += (sqlite3Strlen30(zJournal)+1);
41587   }
41588  
41589   sqlite3OsClose(pMaster);
41590   rc = sqlite3OsDelete(pVfs, zMaster, 0);
41591 
41592 delmaster_out:
41593   sqlite3_free(zMasterJournal);
41594   if( pMaster ){
41595     sqlite3OsClose(pMaster);
41596     assert( !isOpen(pJournal) );
41597     sqlite3_free(pMaster);
41598   }
41599   return rc;
41600 }
41601 
41602 
41603 /*
41604 ** This function is used to change the actual size of the database 
41605 ** file in the file-system. This only happens when committing a transaction,
41606 ** or rolling back a transaction (including rolling back a hot-journal).
41607 **
41608 ** If the main database file is not open, or the pager is not in either
41609 ** DBMOD or OPEN state, this function is a no-op. Otherwise, the size 
41610 ** of the file is changed to nPage pages (nPage*pPager->pageSize bytes). 
41611 ** If the file on disk is currently larger than nPage pages, then use the VFS
41612 ** xTruncate() method to truncate it.
41613 **
41614 ** Or, it might might be the case that the file on disk is smaller than 
41615 ** nPage pages. Some operating system implementations can get confused if 
41616 ** you try to truncate a file to some size that is larger than it 
41617 ** currently is, so detect this case and write a single zero byte to 
41618 ** the end of the new file instead.
41619 **
41620 ** If successful, return SQLITE_OK. If an IO error occurs while modifying
41621 ** the database file, return the error code to the caller.
41622 */
41623 static int pager_truncate(Pager *pPager, Pgno nPage){
41624   int rc = SQLITE_OK;
41625   assert( pPager->eState!=PAGER_ERROR );
41626   assert( pPager->eState!=PAGER_READER );
41627   
41628   if( isOpen(pPager->fd) 
41629    && (pPager->eState>=PAGER_WRITER_DBMOD || pPager->eState==PAGER_OPEN) 
41630   ){
41631     i64 currentSize, newSize;
41632     int szPage = pPager->pageSize;
41633     assert( pPager->eLock==EXCLUSIVE_LOCK );
41634     /* TODO: Is it safe to use Pager.dbFileSize here? */
41635     rc = sqlite3OsFileSize(pPager->fd, &currentSize);
41636     newSize = szPage*(i64)nPage;
41637     if( rc==SQLITE_OK && currentSize!=newSize ){
41638       if( currentSize>newSize ){
41639         rc = sqlite3OsTruncate(pPager->fd, newSize);
41640       }else if( (currentSize+szPage)<=newSize ){
41641         char *pTmp = pPager->pTmpSpace;
41642         memset(pTmp, 0, szPage);
41643         testcase( (newSize-szPage) == currentSize );
41644         testcase( (newSize-szPage) >  currentSize );
41645         rc = sqlite3OsWrite(pPager->fd, pTmp, szPage, newSize-szPage);
41646       }
41647       if( rc==SQLITE_OK ){
41648         pPager->dbFileSize = nPage;
41649       }
41650     }
41651   }
41652   return rc;
41653 }
41654 
41655 /*
41656 ** Return a sanitized version of the sector-size of OS file pFile. The
41657 ** return value is guaranteed to lie between 32 and MAX_SECTOR_SIZE.
41658 */
41659 SQLITE_PRIVATE int sqlite3SectorSize(sqlite3_file *pFile){
41660   int iRet = sqlite3OsSectorSize(pFile);
41661   if( iRet<32 ){
41662     iRet = 512;
41663   }else if( iRet>MAX_SECTOR_SIZE ){
41664     assert( MAX_SECTOR_SIZE>=512 );
41665     iRet = MAX_SECTOR_SIZE;
41666   }
41667   return iRet;
41668 }
41669 
41670 /*
41671 ** Set the value of the Pager.sectorSize variable for the given
41672 ** pager based on the value returned by the xSectorSize method
41673 ** of the open database file. The sector size will be used used 
41674 ** to determine the size and alignment of journal header and 
41675 ** master journal pointers within created journal files.
41676 **
41677 ** For temporary files the effective sector size is always 512 bytes.
41678 **
41679 ** Otherwise, for non-temporary files, the effective sector size is
41680 ** the value returned by the xSectorSize() method rounded up to 32 if
41681 ** it is less than 32, or rounded down to MAX_SECTOR_SIZE if it
41682 ** is greater than MAX_SECTOR_SIZE.
41683 **
41684 ** If the file has the SQLITE_IOCAP_POWERSAFE_OVERWRITE property, then set
41685 ** the effective sector size to its minimum value (512).  The purpose of
41686 ** pPager->sectorSize is to define the "blast radius" of bytes that
41687 ** might change if a crash occurs while writing to a single byte in
41688 ** that range.  But with POWERSAFE_OVERWRITE, the blast radius is zero
41689 ** (that is what POWERSAFE_OVERWRITE means), so we minimize the sector
41690 ** size.  For backwards compatibility of the rollback journal file format,
41691 ** we cannot reduce the effective sector size below 512.
41692 */
41693 static void setSectorSize(Pager *pPager){
41694   assert( isOpen(pPager->fd) || pPager->tempFile );
41695 
41696   if( pPager->tempFile
41697    || (sqlite3OsDeviceCharacteristics(pPager->fd) & 
41698               SQLITE_IOCAP_POWERSAFE_OVERWRITE)!=0
41699   ){
41700     /* Sector size doesn't matter for temporary files. Also, the file
41701     ** may not have been opened yet, in which case the OsSectorSize()
41702     ** call will segfault. */
41703     pPager->sectorSize = 512;
41704   }else{
41705     pPager->sectorSize = sqlite3SectorSize(pPager->fd);
41706   }
41707 }
41708 
41709 /*
41710 ** Playback the journal and thus restore the database file to
41711 ** the state it was in before we started making changes.  
41712 **
41713 ** The journal file format is as follows: 
41714 **
41715 **  (1)  8 byte prefix.  A copy of aJournalMagic[].
41716 **  (2)  4 byte big-endian integer which is the number of valid page records
41717 **       in the journal.  If this value is 0xffffffff, then compute the
41718 **       number of page records from the journal size.
41719 **  (3)  4 byte big-endian integer which is the initial value for the 
41720 **       sanity checksum.
41721 **  (4)  4 byte integer which is the number of pages to truncate the
41722 **       database to during a rollback.
41723 **  (5)  4 byte big-endian integer which is the sector size.  The header
41724 **       is this many bytes in size.
41725 **  (6)  4 byte big-endian integer which is the page size.
41726 **  (7)  zero padding out to the next sector size.
41727 **  (8)  Zero or more pages instances, each as follows:
41728 **        +  4 byte page number.
41729 **        +  pPager->pageSize bytes of data.
41730 **        +  4 byte checksum
41731 **
41732 ** When we speak of the journal header, we mean the first 7 items above.
41733 ** Each entry in the journal is an instance of the 8th item.
41734 **
41735 ** Call the value from the second bullet "nRec".  nRec is the number of
41736 ** valid page entries in the journal.  In most cases, you can compute the
41737 ** value of nRec from the size of the journal file.  But if a power
41738 ** failure occurred while the journal was being written, it could be the
41739 ** case that the size of the journal file had already been increased but
41740 ** the extra entries had not yet made it safely to disk.  In such a case,
41741 ** the value of nRec computed from the file size would be too large.  For
41742 ** that reason, we always use the nRec value in the header.
41743 **
41744 ** If the nRec value is 0xffffffff it means that nRec should be computed
41745 ** from the file size.  This value is used when the user selects the
41746 ** no-sync option for the journal.  A power failure could lead to corruption
41747 ** in this case.  But for things like temporary table (which will be
41748 ** deleted when the power is restored) we don't care.  
41749 **
41750 ** If the file opened as the journal file is not a well-formed
41751 ** journal file then all pages up to the first corrupted page are rolled
41752 ** back (or no pages if the journal header is corrupted). The journal file
41753 ** is then deleted and SQLITE_OK returned, just as if no corruption had
41754 ** been encountered.
41755 **
41756 ** If an I/O or malloc() error occurs, the journal-file is not deleted
41757 ** and an error code is returned.
41758 **
41759 ** The isHot parameter indicates that we are trying to rollback a journal
41760 ** that might be a hot journal.  Or, it could be that the journal is 
41761 ** preserved because of JOURNALMODE_PERSIST or JOURNALMODE_TRUNCATE.
41762 ** If the journal really is hot, reset the pager cache prior rolling
41763 ** back any content.  If the journal is merely persistent, no reset is
41764 ** needed.
41765 */
41766 static int pager_playback(Pager *pPager, int isHot){
41767   sqlite3_vfs *pVfs = pPager->pVfs;
41768   i64 szJ;                 /* Size of the journal file in bytes */
41769   u32 nRec;                /* Number of Records in the journal */
41770   u32 u;                   /* Unsigned loop counter */
41771   Pgno mxPg = 0;           /* Size of the original file in pages */
41772   int rc;                  /* Result code of a subroutine */
41773   int res = 1;             /* Value returned by sqlite3OsAccess() */
41774   char *zMaster = 0;       /* Name of master journal file if any */
41775   int needPagerReset;      /* True to reset page prior to first page rollback */
41776   int nPlayback = 0;       /* Total number of pages restored from journal */
41777 
41778   /* Figure out how many records are in the journal.  Abort early if
41779   ** the journal is empty.
41780   */
41781   assert( isOpen(pPager->jfd) );
41782   rc = sqlite3OsFileSize(pPager->jfd, &szJ);
41783   if( rc!=SQLITE_OK ){
41784     goto end_playback;
41785   }
41786 
41787   /* Read the master journal name from the journal, if it is present.
41788   ** If a master journal file name is specified, but the file is not
41789   ** present on disk, then the journal is not hot and does not need to be
41790   ** played back.
41791   **
41792   ** TODO: Technically the following is an error because it assumes that
41793   ** buffer Pager.pTmpSpace is (mxPathname+1) bytes or larger. i.e. that
41794   ** (pPager->pageSize >= pPager->pVfs->mxPathname+1). Using os_unix.c,
41795   **  mxPathname is 512, which is the same as the minimum allowable value
41796   ** for pageSize.
41797   */
41798   zMaster = pPager->pTmpSpace;
41799   rc = readMasterJournal(pPager->jfd, zMaster, pPager->pVfs->mxPathname+1);
41800   if( rc==SQLITE_OK && zMaster[0] ){
41801     rc = sqlite3OsAccess(pVfs, zMaster, SQLITE_ACCESS_EXISTS, &res);
41802   }
41803   zMaster = 0;
41804   if( rc!=SQLITE_OK || !res ){
41805     goto end_playback;
41806   }
41807   pPager->journalOff = 0;
41808   needPagerReset = isHot;
41809 
41810   /* This loop terminates either when a readJournalHdr() or 
41811   ** pager_playback_one_page() call returns SQLITE_DONE or an IO error 
41812   ** occurs. 
41813   */
41814   while( 1 ){
41815     /* Read the next journal header from the journal file.  If there are
41816     ** not enough bytes left in the journal file for a complete header, or
41817     ** it is corrupted, then a process must have failed while writing it.
41818     ** This indicates nothing more needs to be rolled back.
41819     */
41820     rc = readJournalHdr(pPager, isHot, szJ, &nRec, &mxPg);
41821     if( rc!=SQLITE_OK ){ 
41822       if( rc==SQLITE_DONE ){
41823         rc = SQLITE_OK;
41824       }
41825       goto end_playback;
41826     }
41827 
41828     /* If nRec is 0xffffffff, then this journal was created by a process
41829     ** working in no-sync mode. This means that the rest of the journal
41830     ** file consists of pages, there are no more journal headers. Compute
41831     ** the value of nRec based on this assumption.
41832     */
41833     if( nRec==0xffffffff ){
41834       assert( pPager->journalOff==JOURNAL_HDR_SZ(pPager) );
41835       nRec = (int)((szJ - JOURNAL_HDR_SZ(pPager))/JOURNAL_PG_SZ(pPager));
41836     }
41837 
41838     /* If nRec is 0 and this rollback is of a transaction created by this
41839     ** process and if this is the final header in the journal, then it means
41840     ** that this part of the journal was being filled but has not yet been
41841     ** synced to disk.  Compute the number of pages based on the remaining
41842     ** size of the file.
41843     **
41844     ** The third term of the test was added to fix ticket #2565.
41845     ** When rolling back a hot journal, nRec==0 always means that the next
41846     ** chunk of the journal contains zero pages to be rolled back.  But
41847     ** when doing a ROLLBACK and the nRec==0 chunk is the last chunk in
41848     ** the journal, it means that the journal might contain additional
41849     ** pages that need to be rolled back and that the number of pages 
41850     ** should be computed based on the journal file size.
41851     */
41852     if( nRec==0 && !isHot &&
41853         pPager->journalHdr+JOURNAL_HDR_SZ(pPager)==pPager->journalOff ){
41854       nRec = (int)((szJ - pPager->journalOff) / JOURNAL_PG_SZ(pPager));
41855     }
41856 
41857     /* If this is the first header read from the journal, truncate the
41858     ** database file back to its original size.
41859     */
41860     if( pPager->journalOff==JOURNAL_HDR_SZ(pPager) ){
41861       rc = pager_truncate(pPager, mxPg);
41862       if( rc!=SQLITE_OK ){
41863         goto end_playback;
41864       }
41865       pPager->dbSize = mxPg;
41866     }
41867 
41868     /* Copy original pages out of the journal and back into the 
41869     ** database file and/or page cache.
41870     */
41871     for(u=0; u<nRec; u++){
41872       if( needPagerReset ){
41873         pager_reset(pPager);
41874         needPagerReset = 0;
41875       }
41876       rc = pager_playback_one_page(pPager,&pPager->journalOff,0,1,0);
41877       if( rc==SQLITE_OK ){
41878         nPlayback++;
41879       }else{
41880         if( rc==SQLITE_DONE ){
41881           pPager->journalOff = szJ;
41882           break;
41883         }else if( rc==SQLITE_IOERR_SHORT_READ ){
41884           /* If the journal has been truncated, simply stop reading and
41885           ** processing the journal. This might happen if the journal was
41886           ** not completely written and synced prior to a crash.  In that
41887           ** case, the database should have never been written in the
41888           ** first place so it is OK to simply abandon the rollback. */
41889           rc = SQLITE_OK;
41890           goto end_playback;
41891         }else{
41892           /* If we are unable to rollback, quit and return the error
41893           ** code.  This will cause the pager to enter the error state
41894           ** so that no further harm will be done.  Perhaps the next
41895           ** process to come along will be able to rollback the database.
41896           */
41897           goto end_playback;
41898         }
41899       }
41900     }
41901   }
41902   /*NOTREACHED*/
41903   assert( 0 );
41904 
41905 end_playback:
41906   /* Following a rollback, the database file should be back in its original
41907   ** state prior to the start of the transaction, so invoke the
41908   ** SQLITE_FCNTL_DB_UNCHANGED file-control method to disable the
41909   ** assertion that the transaction counter was modified.
41910   */
41911 #ifdef SQLITE_DEBUG
41912   if( pPager->fd->pMethods ){
41913     sqlite3OsFileControlHint(pPager->fd,SQLITE_FCNTL_DB_UNCHANGED,0);
41914   }
41915 #endif
41916 
41917   /* If this playback is happening automatically as a result of an IO or 
41918   ** malloc error that occurred after the change-counter was updated but 
41919   ** before the transaction was committed, then the change-counter 
41920   ** modification may just have been reverted. If this happens in exclusive 
41921   ** mode, then subsequent transactions performed by the connection will not
41922   ** update the change-counter at all. This may lead to cache inconsistency
41923   ** problems for other processes at some point in the future. So, just
41924   ** in case this has happened, clear the changeCountDone flag now.
41925   */
41926   pPager->changeCountDone = pPager->tempFile;
41927 
41928   if( rc==SQLITE_OK ){
41929     zMaster = pPager->pTmpSpace;
41930     rc = readMasterJournal(pPager->jfd, zMaster, pPager->pVfs->mxPathname+1);
41931     testcase( rc!=SQLITE_OK );
41932   }
41933   if( rc==SQLITE_OK
41934    && (pPager->eState>=PAGER_WRITER_DBMOD || pPager->eState==PAGER_OPEN)
41935   ){
41936     rc = sqlite3PagerSync(pPager);
41937   }
41938   if( rc==SQLITE_OK ){
41939     rc = pager_end_transaction(pPager, zMaster[0]!='\0', 0);
41940     testcase( rc!=SQLITE_OK );
41941   }
41942   if( rc==SQLITE_OK && zMaster[0] && res ){
41943     /* If there was a master journal and this routine will return success,
41944     ** see if it is possible to delete the master journal.
41945     */
41946     rc = pager_delmaster(pPager, zMaster);
41947     testcase( rc!=SQLITE_OK );
41948   }
41949   if( isHot && nPlayback ){
41950     sqlite3_log(SQLITE_NOTICE_RECOVER_ROLLBACK, "recovered %d pages from %s",
41951                 nPlayback, pPager->zJournal);
41952   }
41953 
41954   /* The Pager.sectorSize variable may have been updated while rolling
41955   ** back a journal created by a process with a different sector size
41956   ** value. Reset it to the correct value for this process.
41957   */
41958   setSectorSize(pPager);
41959   return rc;
41960 }
41961 
41962 
41963 /*
41964 ** Read the content for page pPg out of the database file and into 
41965 ** pPg->pData. A shared lock or greater must be held on the database
41966 ** file before this function is called.
41967 **
41968 ** If page 1 is read, then the value of Pager.dbFileVers[] is set to
41969 ** the value read from the database file.
41970 **
41971 ** If an IO error occurs, then the IO error is returned to the caller.
41972 ** Otherwise, SQLITE_OK is returned.
41973 */
41974 static int readDbPage(PgHdr *pPg, u32 iFrame){
41975   Pager *pPager = pPg->pPager; /* Pager object associated with page pPg */
41976   Pgno pgno = pPg->pgno;       /* Page number to read */
41977   int rc = SQLITE_OK;          /* Return code */
41978   int pgsz = pPager->pageSize; /* Number of bytes to read */
41979 
41980   assert( pPager->eState>=PAGER_READER && !MEMDB );
41981   assert( isOpen(pPager->fd) );
41982 
41983 #ifndef SQLITE_OMIT_WAL
41984   if( iFrame ){
41985     /* Try to pull the page from the write-ahead log. */
41986     rc = sqlite3WalReadFrame(pPager->pWal, iFrame, pgsz, pPg->pData);
41987   }else
41988 #endif
41989   {
41990     i64 iOffset = (pgno-1)*(i64)pPager->pageSize;
41991     rc = sqlite3OsRead(pPager->fd, pPg->pData, pgsz, iOffset);
41992     if( rc==SQLITE_IOERR_SHORT_READ ){
41993       rc = SQLITE_OK;
41994     }
41995   }
41996 
41997   if( pgno==1 ){
41998     if( rc ){
41999       /* If the read is unsuccessful, set the dbFileVers[] to something
42000       ** that will never be a valid file version.  dbFileVers[] is a copy
42001       ** of bytes 24..39 of the database.  Bytes 28..31 should always be
42002       ** zero or the size of the database in page. Bytes 32..35 and 35..39
42003       ** should be page numbers which are never 0xffffffff.  So filling
42004       ** pPager->dbFileVers[] with all 0xff bytes should suffice.
42005       **
42006       ** For an encrypted database, the situation is more complex:  bytes
42007       ** 24..39 of the database are white noise.  But the probability of
42008       ** white noising equaling 16 bytes of 0xff is vanishingly small so
42009       ** we should still be ok.
42010       */
42011       memset(pPager->dbFileVers, 0xff, sizeof(pPager->dbFileVers));
42012     }else{
42013       u8 *dbFileVers = &((u8*)pPg->pData)[24];
42014       memcpy(&pPager->dbFileVers, dbFileVers, sizeof(pPager->dbFileVers));
42015     }
42016   }
42017   CODEC1(pPager, pPg->pData, pgno, 3, rc = SQLITE_NOMEM);
42018 
42019   PAGER_INCR(sqlite3_pager_readdb_count);
42020   PAGER_INCR(pPager->nRead);
42021   IOTRACE(("PGIN %p %d\n", pPager, pgno));
42022   PAGERTRACE(("FETCH %d page %d hash(%08x)\n",
42023                PAGERID(pPager), pgno, pager_pagehash(pPg)));
42024 
42025   return rc;
42026 }
42027 
42028 /*
42029 ** Update the value of the change-counter at offsets 24 and 92 in
42030 ** the header and the sqlite version number at offset 96.
42031 **
42032 ** This is an unconditional update.  See also the pager_incr_changecounter()
42033 ** routine which only updates the change-counter if the update is actually
42034 ** needed, as determined by the pPager->changeCountDone state variable.
42035 */
42036 static void pager_write_changecounter(PgHdr *pPg){
42037   u32 change_counter;
42038 
42039   /* Increment the value just read and write it back to byte 24. */
42040   change_counter = sqlite3Get4byte((u8*)pPg->pPager->dbFileVers)+1;
42041   put32bits(((char*)pPg->pData)+24, change_counter);
42042 
42043   /* Also store the SQLite version number in bytes 96..99 and in
42044   ** bytes 92..95 store the change counter for which the version number
42045   ** is valid. */
42046   put32bits(((char*)pPg->pData)+92, change_counter);
42047   put32bits(((char*)pPg->pData)+96, SQLITE_VERSION_NUMBER);
42048 }
42049 
42050 #ifndef SQLITE_OMIT_WAL
42051 /*
42052 ** This function is invoked once for each page that has already been 
42053 ** written into the log file when a WAL transaction is rolled back.
42054 ** Parameter iPg is the page number of said page. The pCtx argument 
42055 ** is actually a pointer to the Pager structure.
42056 **
42057 ** If page iPg is present in the cache, and has no outstanding references,
42058 ** it is discarded. Otherwise, if there are one or more outstanding
42059 ** references, the page content is reloaded from the database. If the
42060 ** attempt to reload content from the database is required and fails, 
42061 ** return an SQLite error code. Otherwise, SQLITE_OK.
42062 */
42063 static int pagerUndoCallback(void *pCtx, Pgno iPg){
42064   int rc = SQLITE_OK;
42065   Pager *pPager = (Pager *)pCtx;
42066   PgHdr *pPg;
42067 
42068   assert( pagerUseWal(pPager) );
42069   pPg = sqlite3PagerLookup(pPager, iPg);
42070   if( pPg ){
42071     if( sqlite3PcachePageRefcount(pPg)==1 ){
42072       sqlite3PcacheDrop(pPg);
42073     }else{
42074       u32 iFrame = 0;
42075       rc = sqlite3WalFindFrame(pPager->pWal, pPg->pgno, &iFrame);
42076       if( rc==SQLITE_OK ){
42077         rc = readDbPage(pPg, iFrame);
42078       }
42079       if( rc==SQLITE_OK ){
42080         pPager->xReiniter(pPg);
42081       }
42082       sqlite3PagerUnref(pPg);
42083     }
42084   }
42085 
42086   /* Normally, if a transaction is rolled back, any backup processes are
42087   ** updated as data is copied out of the rollback journal and into the
42088   ** database. This is not generally possible with a WAL database, as
42089   ** rollback involves simply truncating the log file. Therefore, if one
42090   ** or more frames have already been written to the log (and therefore 
42091   ** also copied into the backup databases) as part of this transaction,
42092   ** the backups must be restarted.
42093   */
42094   sqlite3BackupRestart(pPager->pBackup);
42095 
42096   return rc;
42097 }
42098 
42099 /*
42100 ** This function is called to rollback a transaction on a WAL database.
42101 */
42102 static int pagerRollbackWal(Pager *pPager){
42103   int rc;                         /* Return Code */
42104   PgHdr *pList;                   /* List of dirty pages to revert */
42105 
42106   /* For all pages in the cache that are currently dirty or have already
42107   ** been written (but not committed) to the log file, do one of the 
42108   ** following:
42109   **
42110   **   + Discard the cached page (if refcount==0), or
42111   **   + Reload page content from the database (if refcount>0).
42112   */
42113   pPager->dbSize = pPager->dbOrigSize;
42114   rc = sqlite3WalUndo(pPager->pWal, pagerUndoCallback, (void *)pPager);
42115   pList = sqlite3PcacheDirtyList(pPager->pPCache);
42116   while( pList && rc==SQLITE_OK ){
42117     PgHdr *pNext = pList->pDirty;
42118     rc = pagerUndoCallback((void *)pPager, pList->pgno);
42119     pList = pNext;
42120   }
42121 
42122   return rc;
42123 }
42124 
42125 /*
42126 ** This function is a wrapper around sqlite3WalFrames(). As well as logging
42127 ** the contents of the list of pages headed by pList (connected by pDirty),
42128 ** this function notifies any active backup processes that the pages have
42129 ** changed. 
42130 **
42131 ** The list of pages passed into this routine is always sorted by page number.
42132 ** Hence, if page 1 appears anywhere on the list, it will be the first page.
42133 */ 
42134 static int pagerWalFrames(
42135   Pager *pPager,                  /* Pager object */
42136   PgHdr *pList,                   /* List of frames to log */
42137   Pgno nTruncate,                 /* Database size after this commit */
42138   int isCommit                    /* True if this is a commit */
42139 ){
42140   int rc;                         /* Return code */
42141   int nList;                      /* Number of pages in pList */
42142 #if defined(SQLITE_DEBUG) || defined(SQLITE_CHECK_PAGES)
42143   PgHdr *p;                       /* For looping over pages */
42144 #endif
42145 
42146   assert( pPager->pWal );
42147   assert( pList );
42148 #ifdef SQLITE_DEBUG
42149   /* Verify that the page list is in accending order */
42150   for(p=pList; p && p->pDirty; p=p->pDirty){
42151     assert( p->pgno < p->pDirty->pgno );
42152   }
42153 #endif
42154 
42155   assert( pList->pDirty==0 || isCommit );
42156   if( isCommit ){
42157     /* If a WAL transaction is being committed, there is no point in writing
42158     ** any pages with page numbers greater than nTruncate into the WAL file.
42159     ** They will never be read by any client. So remove them from the pDirty
42160     ** list here. */
42161     PgHdr *p;
42162     PgHdr **ppNext = &pList;
42163     nList = 0;
42164     for(p=pList; (*ppNext = p)!=0; p=p->pDirty){
42165       if( p->pgno<=nTruncate ){
42166         ppNext = &p->pDirty;
42167         nList++;
42168       }
42169     }
42170     assert( pList );
42171   }else{
42172     nList = 1;
42173   }
42174   pPager->aStat[PAGER_STAT_WRITE] += nList;
42175 
42176   if( pList->pgno==1 ) pager_write_changecounter(pList);
42177   rc = sqlite3WalFrames(pPager->pWal, 
42178       pPager->pageSize, pList, nTruncate, isCommit, pPager->walSyncFlags
42179   );
42180   if( rc==SQLITE_OK && pPager->pBackup ){
42181     PgHdr *p;
42182     for(p=pList; p; p=p->pDirty){
42183       sqlite3BackupUpdate(pPager->pBackup, p->pgno, (u8 *)p->pData);
42184     }
42185   }
42186 
42187 #ifdef SQLITE_CHECK_PAGES
42188   pList = sqlite3PcacheDirtyList(pPager->pPCache);
42189   for(p=pList; p; p=p->pDirty){
42190     pager_set_pagehash(p);
42191   }
42192 #endif
42193 
42194   return rc;
42195 }
42196 
42197 /*
42198 ** Begin a read transaction on the WAL.
42199 **
42200 ** This routine used to be called "pagerOpenSnapshot()" because it essentially
42201 ** makes a snapshot of the database at the current point in time and preserves
42202 ** that snapshot for use by the reader in spite of concurrently changes by
42203 ** other writers or checkpointers.
42204 */
42205 static int pagerBeginReadTransaction(Pager *pPager){
42206   int rc;                         /* Return code */
42207   int changed = 0;                /* True if cache must be reset */
42208 
42209   assert( pagerUseWal(pPager) );
42210   assert( pPager->eState==PAGER_OPEN || pPager->eState==PAGER_READER );
42211 
42212   /* sqlite3WalEndReadTransaction() was not called for the previous
42213   ** transaction in locking_mode=EXCLUSIVE.  So call it now.  If we
42214   ** are in locking_mode=NORMAL and EndRead() was previously called,
42215   ** the duplicate call is harmless.
42216   */
42217   sqlite3WalEndReadTransaction(pPager->pWal);
42218 
42219   rc = sqlite3WalBeginReadTransaction(pPager->pWal, &changed);
42220   if( rc!=SQLITE_OK || changed ){
42221     pager_reset(pPager);
42222     if( USEFETCH(pPager) ) sqlite3OsUnfetch(pPager->fd, 0, 0);
42223   }
42224 
42225   return rc;
42226 }
42227 #endif
42228 
42229 /*
42230 ** This function is called as part of the transition from PAGER_OPEN
42231 ** to PAGER_READER state to determine the size of the database file
42232 ** in pages (assuming the page size currently stored in Pager.pageSize).
42233 **
42234 ** If no error occurs, SQLITE_OK is returned and the size of the database
42235 ** in pages is stored in *pnPage. Otherwise, an error code (perhaps
42236 ** SQLITE_IOERR_FSTAT) is returned and *pnPage is left unmodified.
42237 */
42238 static int pagerPagecount(Pager *pPager, Pgno *pnPage){
42239   Pgno nPage;                     /* Value to return via *pnPage */
42240 
42241   /* Query the WAL sub-system for the database size. The WalDbsize()
42242   ** function returns zero if the WAL is not open (i.e. Pager.pWal==0), or
42243   ** if the database size is not available. The database size is not
42244   ** available from the WAL sub-system if the log file is empty or
42245   ** contains no valid committed transactions.
42246   */
42247   assert( pPager->eState==PAGER_OPEN );
42248   assert( pPager->eLock>=SHARED_LOCK );
42249   nPage = sqlite3WalDbsize(pPager->pWal);
42250 
42251   /* If the database size was not available from the WAL sub-system,
42252   ** determine it based on the size of the database file. If the size
42253   ** of the database file is not an integer multiple of the page-size,
42254   ** round down to the nearest page. Except, any file larger than 0
42255   ** bytes in size is considered to contain at least one page.
42256   */
42257   if( nPage==0 ){
42258     i64 n = 0;                    /* Size of db file in bytes */
42259     assert( isOpen(pPager->fd) || pPager->tempFile );
42260     if( isOpen(pPager->fd) ){
42261       int rc = sqlite3OsFileSize(pPager->fd, &n);
42262       if( rc!=SQLITE_OK ){
42263         return rc;
42264       }
42265     }
42266     nPage = (Pgno)((n+pPager->pageSize-1) / pPager->pageSize);
42267   }
42268 
42269   /* If the current number of pages in the file is greater than the
42270   ** configured maximum pager number, increase the allowed limit so
42271   ** that the file can be read.
42272   */
42273   if( nPage>pPager->mxPgno ){
42274     pPager->mxPgno = (Pgno)nPage;
42275   }
42276 
42277   *pnPage = nPage;
42278   return SQLITE_OK;
42279 }
42280 
42281 #ifndef SQLITE_OMIT_WAL
42282 /*
42283 ** Check if the *-wal file that corresponds to the database opened by pPager
42284 ** exists if the database is not empy, or verify that the *-wal file does
42285 ** not exist (by deleting it) if the database file is empty.
42286 **
42287 ** If the database is not empty and the *-wal file exists, open the pager
42288 ** in WAL mode.  If the database is empty or if no *-wal file exists and
42289 ** if no error occurs, make sure Pager.journalMode is not set to
42290 ** PAGER_JOURNALMODE_WAL.
42291 **
42292 ** Return SQLITE_OK or an error code.
42293 **
42294 ** The caller must hold a SHARED lock on the database file to call this
42295 ** function. Because an EXCLUSIVE lock on the db file is required to delete 
42296 ** a WAL on a none-empty database, this ensures there is no race condition 
42297 ** between the xAccess() below and an xDelete() being executed by some 
42298 ** other connection.
42299 */
42300 static int pagerOpenWalIfPresent(Pager *pPager){
42301   int rc = SQLITE_OK;
42302   assert( pPager->eState==PAGER_OPEN );
42303   assert( pPager->eLock>=SHARED_LOCK );
42304 
42305   if( !pPager->tempFile ){
42306     int isWal;                    /* True if WAL file exists */
42307     Pgno nPage;                   /* Size of the database file */
42308 
42309     rc = pagerPagecount(pPager, &nPage);
42310     if( rc ) return rc;
42311     if( nPage==0 ){
42312       rc = sqlite3OsDelete(pPager->pVfs, pPager->zWal, 0);
42313       if( rc==SQLITE_IOERR_DELETE_NOENT ) rc = SQLITE_OK;
42314       isWal = 0;
42315     }else{
42316       rc = sqlite3OsAccess(
42317           pPager->pVfs, pPager->zWal, SQLITE_ACCESS_EXISTS, &isWal
42318       );
42319     }
42320     if( rc==SQLITE_OK ){
42321       if( isWal ){
42322         testcase( sqlite3PcachePagecount(pPager->pPCache)==0 );
42323         rc = sqlite3PagerOpenWal(pPager, 0);
42324       }else if( pPager->journalMode==PAGER_JOURNALMODE_WAL ){
42325         pPager->journalMode = PAGER_JOURNALMODE_DELETE;
42326       }
42327     }
42328   }
42329   return rc;
42330 }
42331 #endif
42332 
42333 /*
42334 ** Playback savepoint pSavepoint. Or, if pSavepoint==NULL, then playback
42335 ** the entire master journal file. The case pSavepoint==NULL occurs when 
42336 ** a ROLLBACK TO command is invoked on a SAVEPOINT that is a transaction 
42337 ** savepoint.
42338 **
42339 ** When pSavepoint is not NULL (meaning a non-transaction savepoint is 
42340 ** being rolled back), then the rollback consists of up to three stages,
42341 ** performed in the order specified:
42342 **
42343 **   * Pages are played back from the main journal starting at byte
42344 **     offset PagerSavepoint.iOffset and continuing to 
42345 **     PagerSavepoint.iHdrOffset, or to the end of the main journal
42346 **     file if PagerSavepoint.iHdrOffset is zero.
42347 **
42348 **   * If PagerSavepoint.iHdrOffset is not zero, then pages are played
42349 **     back starting from the journal header immediately following 
42350 **     PagerSavepoint.iHdrOffset to the end of the main journal file.
42351 **
42352 **   * Pages are then played back from the sub-journal file, starting
42353 **     with the PagerSavepoint.iSubRec and continuing to the end of
42354 **     the journal file.
42355 **
42356 ** Throughout the rollback process, each time a page is rolled back, the
42357 ** corresponding bit is set in a bitvec structure (variable pDone in the
42358 ** implementation below). This is used to ensure that a page is only
42359 ** rolled back the first time it is encountered in either journal.
42360 **
42361 ** If pSavepoint is NULL, then pages are only played back from the main
42362 ** journal file. There is no need for a bitvec in this case.
42363 **
42364 ** In either case, before playback commences the Pager.dbSize variable
42365 ** is reset to the value that it held at the start of the savepoint 
42366 ** (or transaction). No page with a page-number greater than this value
42367 ** is played back. If one is encountered it is simply skipped.
42368 */
42369 static int pagerPlaybackSavepoint(Pager *pPager, PagerSavepoint *pSavepoint){
42370   i64 szJ;                 /* Effective size of the main journal */
42371   i64 iHdrOff;             /* End of first segment of main-journal records */
42372   int rc = SQLITE_OK;      /* Return code */
42373   Bitvec *pDone = 0;       /* Bitvec to ensure pages played back only once */
42374 
42375   assert( pPager->eState!=PAGER_ERROR );
42376   assert( pPager->eState>=PAGER_WRITER_LOCKED );
42377 
42378   /* Allocate a bitvec to use to store the set of pages rolled back */
42379   if( pSavepoint ){
42380     pDone = sqlite3BitvecCreate(pSavepoint->nOrig);
42381     if( !pDone ){
42382       return SQLITE_NOMEM;
42383     }
42384   }
42385 
42386   /* Set the database size back to the value it was before the savepoint 
42387   ** being reverted was opened.
42388   */
42389   pPager->dbSize = pSavepoint ? pSavepoint->nOrig : pPager->dbOrigSize;
42390   pPager->changeCountDone = pPager->tempFile;
42391 
42392   if( !pSavepoint && pagerUseWal(pPager) ){
42393     return pagerRollbackWal(pPager);
42394   }
42395 
42396   /* Use pPager->journalOff as the effective size of the main rollback
42397   ** journal.  The actual file might be larger than this in
42398   ** PAGER_JOURNALMODE_TRUNCATE or PAGER_JOURNALMODE_PERSIST.  But anything
42399   ** past pPager->journalOff is off-limits to us.
42400   */
42401   szJ = pPager->journalOff;
42402   assert( pagerUseWal(pPager)==0 || szJ==0 );
42403 
42404   /* Begin by rolling back records from the main journal starting at
42405   ** PagerSavepoint.iOffset and continuing to the next journal header.
42406   ** There might be records in the main journal that have a page number
42407   ** greater than the current database size (pPager->dbSize) but those
42408   ** will be skipped automatically.  Pages are added to pDone as they
42409   ** are played back.
42410   */
42411   if( pSavepoint && !pagerUseWal(pPager) ){
42412     iHdrOff = pSavepoint->iHdrOffset ? pSavepoint->iHdrOffset : szJ;
42413     pPager->journalOff = pSavepoint->iOffset;
42414     while( rc==SQLITE_OK && pPager->journalOff<iHdrOff ){
42415       rc = pager_playback_one_page(pPager, &pPager->journalOff, pDone, 1, 1);
42416     }
42417     assert( rc!=SQLITE_DONE );
42418   }else{
42419     pPager->journalOff = 0;
42420   }
42421 
42422   /* Continue rolling back records out of the main journal starting at
42423   ** the first journal header seen and continuing until the effective end
42424   ** of the main journal file.  Continue to skip out-of-range pages and
42425   ** continue adding pages rolled back to pDone.
42426   */
42427   while( rc==SQLITE_OK && pPager->journalOff<szJ ){
42428     u32 ii;            /* Loop counter */
42429     u32 nJRec = 0;     /* Number of Journal Records */
42430     u32 dummy;
42431     rc = readJournalHdr(pPager, 0, szJ, &nJRec, &dummy);
42432     assert( rc!=SQLITE_DONE );
42433 
42434     /*
42435     ** The "pPager->journalHdr+JOURNAL_HDR_SZ(pPager)==pPager->journalOff"
42436     ** test is related to ticket #2565.  See the discussion in the
42437     ** pager_playback() function for additional information.
42438     */
42439     if( nJRec==0 
42440      && pPager->journalHdr+JOURNAL_HDR_SZ(pPager)==pPager->journalOff
42441     ){
42442       nJRec = (u32)((szJ - pPager->journalOff)/JOURNAL_PG_SZ(pPager));
42443     }
42444     for(ii=0; rc==SQLITE_OK && ii<nJRec && pPager->journalOff<szJ; ii++){
42445       rc = pager_playback_one_page(pPager, &pPager->journalOff, pDone, 1, 1);
42446     }
42447     assert( rc!=SQLITE_DONE );
42448   }
42449   assert( rc!=SQLITE_OK || pPager->journalOff>=szJ );
42450 
42451   /* Finally,  rollback pages from the sub-journal.  Page that were
42452   ** previously rolled back out of the main journal (and are hence in pDone)
42453   ** will be skipped.  Out-of-range pages are also skipped.
42454   */
42455   if( pSavepoint ){
42456     u32 ii;            /* Loop counter */
42457     i64 offset = (i64)pSavepoint->iSubRec*(4+pPager->pageSize);
42458 
42459     if( pagerUseWal(pPager) ){
42460       rc = sqlite3WalSavepointUndo(pPager->pWal, pSavepoint->aWalData);
42461     }
42462     for(ii=pSavepoint->iSubRec; rc==SQLITE_OK && ii<pPager->nSubRec; ii++){
42463       assert( offset==(i64)ii*(4+pPager->pageSize) );
42464       rc = pager_playback_one_page(pPager, &offset, pDone, 0, 1);
42465     }
42466     assert( rc!=SQLITE_DONE );
42467   }
42468 
42469   sqlite3BitvecDestroy(pDone);
42470   if( rc==SQLITE_OK ){
42471     pPager->journalOff = szJ;
42472   }
42473 
42474   return rc;
42475 }
42476 
42477 /*
42478 ** Change the maximum number of in-memory pages that are allowed.
42479 */
42480 SQLITE_PRIVATE void sqlite3PagerSetCachesize(Pager *pPager, int mxPage){
42481   sqlite3PcacheSetCachesize(pPager->pPCache, mxPage);
42482 }
42483 
42484 /*
42485 ** Invoke SQLITE_FCNTL_MMAP_SIZE based on the current value of szMmap.
42486 */
42487 static void pagerFixMaplimit(Pager *pPager){
42488 #if SQLITE_MAX_MMAP_SIZE>0
42489   sqlite3_file *fd = pPager->fd;
42490   if( isOpen(fd) && fd->pMethods->iVersion>=3 ){
42491     sqlite3_int64 sz;
42492     sz = pPager->szMmap;
42493     pPager->bUseFetch = (sz>0);
42494     sqlite3OsFileControlHint(pPager->fd, SQLITE_FCNTL_MMAP_SIZE, &sz);
42495   }
42496 #endif
42497 }
42498 
42499 /*
42500 ** Change the maximum size of any memory mapping made of the database file.
42501 */
42502 SQLITE_PRIVATE void sqlite3PagerSetMmapLimit(Pager *pPager, sqlite3_int64 szMmap){
42503   pPager->szMmap = szMmap;
42504   pagerFixMaplimit(pPager);
42505 }
42506 
42507 /*
42508 ** Free as much memory as possible from the pager.
42509 */
42510 SQLITE_PRIVATE void sqlite3PagerShrink(Pager *pPager){
42511   sqlite3PcacheShrink(pPager->pPCache);
42512 }
42513 
42514 /*
42515 ** Adjust settings of the pager to those specified in the pgFlags parameter.
42516 **
42517 ** The "level" in pgFlags & PAGER_SYNCHRONOUS_MASK sets the robustness
42518 ** of the database to damage due to OS crashes or power failures by
42519 ** changing the number of syncs()s when writing the journals.
42520 ** There are three levels:
42521 **
42522 **    OFF       sqlite3OsSync() is never called.  This is the default
42523 **              for temporary and transient files.
42524 **
42525 **    NORMAL    The journal is synced once before writes begin on the
42526 **              database.  This is normally adequate protection, but
42527 **              it is theoretically possible, though very unlikely,
42528 **              that an inopertune power failure could leave the journal
42529 **              in a state which would cause damage to the database
42530 **              when it is rolled back.
42531 **
42532 **    FULL      The journal is synced twice before writes begin on the
42533 **              database (with some additional information - the nRec field
42534 **              of the journal header - being written in between the two
42535 **              syncs).  If we assume that writing a
42536 **              single disk sector is atomic, then this mode provides
42537 **              assurance that the journal will not be corrupted to the
42538 **              point of causing damage to the database during rollback.
42539 **
42540 ** The above is for a rollback-journal mode.  For WAL mode, OFF continues
42541 ** to mean that no syncs ever occur.  NORMAL means that the WAL is synced
42542 ** prior to the start of checkpoint and that the database file is synced
42543 ** at the conclusion of the checkpoint if the entire content of the WAL
42544 ** was written back into the database.  But no sync operations occur for
42545 ** an ordinary commit in NORMAL mode with WAL.  FULL means that the WAL
42546 ** file is synced following each commit operation, in addition to the
42547 ** syncs associated with NORMAL.
42548 **
42549 ** Do not confuse synchronous=FULL with SQLITE_SYNC_FULL.  The
42550 ** SQLITE_SYNC_FULL macro means to use the MacOSX-style full-fsync
42551 ** using fcntl(F_FULLFSYNC).  SQLITE_SYNC_NORMAL means to do an
42552 ** ordinary fsync() call.  There is no difference between SQLITE_SYNC_FULL
42553 ** and SQLITE_SYNC_NORMAL on platforms other than MacOSX.  But the
42554 ** synchronous=FULL versus synchronous=NORMAL setting determines when
42555 ** the xSync primitive is called and is relevant to all platforms.
42556 **
42557 ** Numeric values associated with these states are OFF==1, NORMAL=2,
42558 ** and FULL=3.
42559 */
42560 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
42561 SQLITE_PRIVATE void sqlite3PagerSetFlags(
42562   Pager *pPager,        /* The pager to set safety level for */
42563   unsigned pgFlags      /* Various flags */
42564 ){
42565   unsigned level = pgFlags & PAGER_SYNCHRONOUS_MASK;
42566   assert( level>=1 && level<=3 );
42567   pPager->noSync =  (level==1 || pPager->tempFile) ?1:0;
42568   pPager->fullSync = (level==3 && !pPager->tempFile) ?1:0;
42569   if( pPager->noSync ){
42570     pPager->syncFlags = 0;
42571     pPager->ckptSyncFlags = 0;
42572   }else if( pgFlags & PAGER_FULLFSYNC ){
42573     pPager->syncFlags = SQLITE_SYNC_FULL;
42574     pPager->ckptSyncFlags = SQLITE_SYNC_FULL;
42575   }else if( pgFlags & PAGER_CKPT_FULLFSYNC ){
42576     pPager->syncFlags = SQLITE_SYNC_NORMAL;
42577     pPager->ckptSyncFlags = SQLITE_SYNC_FULL;
42578   }else{
42579     pPager->syncFlags = SQLITE_SYNC_NORMAL;
42580     pPager->ckptSyncFlags = SQLITE_SYNC_NORMAL;
42581   }
42582   pPager->walSyncFlags = pPager->syncFlags;
42583   if( pPager->fullSync ){
42584     pPager->walSyncFlags |= WAL_SYNC_TRANSACTIONS;
42585   }
42586   if( pgFlags & PAGER_CACHESPILL ){
42587     pPager->doNotSpill &= ~SPILLFLAG_OFF;
42588   }else{
42589     pPager->doNotSpill |= SPILLFLAG_OFF;
42590   }
42591 }
42592 #endif
42593 
42594 /*
42595 ** The following global variable is incremented whenever the library
42596 ** attempts to open a temporary file.  This information is used for
42597 ** testing and analysis only.  
42598 */
42599 #ifdef SQLITE_TEST
42600 SQLITE_API int sqlite3_opentemp_count = 0;
42601 #endif
42602 
42603 /*
42604 ** Open a temporary file.
42605 **
42606 ** Write the file descriptor into *pFile. Return SQLITE_OK on success 
42607 ** or some other error code if we fail. The OS will automatically 
42608 ** delete the temporary file when it is closed.
42609 **
42610 ** The flags passed to the VFS layer xOpen() call are those specified
42611 ** by parameter vfsFlags ORed with the following:
42612 **
42613 **     SQLITE_OPEN_READWRITE
42614 **     SQLITE_OPEN_CREATE
42615 **     SQLITE_OPEN_EXCLUSIVE
42616 **     SQLITE_OPEN_DELETEONCLOSE
42617 */
42618 static int pagerOpentemp(
42619   Pager *pPager,        /* The pager object */
42620   sqlite3_file *pFile,  /* Write the file descriptor here */
42621   int vfsFlags          /* Flags passed through to the VFS */
42622 ){
42623   int rc;               /* Return code */
42624 
42625 #ifdef SQLITE_TEST
42626   sqlite3_opentemp_count++;  /* Used for testing and analysis only */
42627 #endif
42628 
42629   vfsFlags |=  SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE |
42630             SQLITE_OPEN_EXCLUSIVE | SQLITE_OPEN_DELETEONCLOSE;
42631   rc = sqlite3OsOpen(pPager->pVfs, 0, pFile, vfsFlags, 0);
42632   assert( rc!=SQLITE_OK || isOpen(pFile) );
42633   return rc;
42634 }
42635 
42636 /*
42637 ** Set the busy handler function.
42638 **
42639 ** The pager invokes the busy-handler if sqlite3OsLock() returns 
42640 ** SQLITE_BUSY when trying to upgrade from no-lock to a SHARED lock,
42641 ** or when trying to upgrade from a RESERVED lock to an EXCLUSIVE 
42642 ** lock. It does *not* invoke the busy handler when upgrading from
42643 ** SHARED to RESERVED, or when upgrading from SHARED to EXCLUSIVE
42644 ** (which occurs during hot-journal rollback). Summary:
42645 **
42646 **   Transition                        | Invokes xBusyHandler
42647 **   --------------------------------------------------------
42648 **   NO_LOCK       -> SHARED_LOCK      | Yes
42649 **   SHARED_LOCK   -> RESERVED_LOCK    | No
42650 **   SHARED_LOCK   -> EXCLUSIVE_LOCK   | No
42651 **   RESERVED_LOCK -> EXCLUSIVE_LOCK   | Yes
42652 **
42653 ** If the busy-handler callback returns non-zero, the lock is 
42654 ** retried. If it returns zero, then the SQLITE_BUSY error is
42655 ** returned to the caller of the pager API function.
42656 */
42657 SQLITE_PRIVATE void sqlite3PagerSetBusyhandler(
42658   Pager *pPager,                       /* Pager object */
42659   int (*xBusyHandler)(void *),         /* Pointer to busy-handler function */
42660   void *pBusyHandlerArg                /* Argument to pass to xBusyHandler */
42661 ){
42662   pPager->xBusyHandler = xBusyHandler;
42663   pPager->pBusyHandlerArg = pBusyHandlerArg;
42664 
42665   if( isOpen(pPager->fd) ){
42666     void **ap = (void **)&pPager->xBusyHandler;
42667     assert( ((int(*)(void *))(ap[0]))==xBusyHandler );
42668     assert( ap[1]==pBusyHandlerArg );
42669     sqlite3OsFileControlHint(pPager->fd, SQLITE_FCNTL_BUSYHANDLER, (void *)ap);
42670   }
42671 }
42672 
42673 /*
42674 ** Change the page size used by the Pager object. The new page size 
42675 ** is passed in *pPageSize.
42676 **
42677 ** If the pager is in the error state when this function is called, it
42678 ** is a no-op. The value returned is the error state error code (i.e. 
42679 ** one of SQLITE_IOERR, an SQLITE_IOERR_xxx sub-code or SQLITE_FULL).
42680 **
42681 ** Otherwise, if all of the following are true:
42682 **
42683 **   * the new page size (value of *pPageSize) is valid (a power 
42684 **     of two between 512 and SQLITE_MAX_PAGE_SIZE, inclusive), and
42685 **
42686 **   * there are no outstanding page references, and
42687 **
42688 **   * the database is either not an in-memory database or it is
42689 **     an in-memory database that currently consists of zero pages.
42690 **
42691 ** then the pager object page size is set to *pPageSize.
42692 **
42693 ** If the page size is changed, then this function uses sqlite3PagerMalloc() 
42694 ** to obtain a new Pager.pTmpSpace buffer. If this allocation attempt 
42695 ** fails, SQLITE_NOMEM is returned and the page size remains unchanged. 
42696 ** In all other cases, SQLITE_OK is returned.
42697 **
42698 ** If the page size is not changed, either because one of the enumerated
42699 ** conditions above is not true, the pager was in error state when this
42700 ** function was called, or because the memory allocation attempt failed, 
42701 ** then *pPageSize is set to the old, retained page size before returning.
42702 */
42703 SQLITE_PRIVATE int sqlite3PagerSetPagesize(Pager *pPager, u32 *pPageSize, int nReserve){
42704   int rc = SQLITE_OK;
42705 
42706   /* It is not possible to do a full assert_pager_state() here, as this
42707   ** function may be called from within PagerOpen(), before the state
42708   ** of the Pager object is internally consistent.
42709   **
42710   ** At one point this function returned an error if the pager was in 
42711   ** PAGER_ERROR state. But since PAGER_ERROR state guarantees that
42712   ** there is at least one outstanding page reference, this function
42713   ** is a no-op for that case anyhow.
42714   */
42715 
42716   u32 pageSize = *pPageSize;
42717   assert( pageSize==0 || (pageSize>=512 && pageSize<=SQLITE_MAX_PAGE_SIZE) );
42718   if( (pPager->memDb==0 || pPager->dbSize==0)
42719    && sqlite3PcacheRefCount(pPager->pPCache)==0 
42720    && pageSize && pageSize!=(u32)pPager->pageSize 
42721   ){
42722     char *pNew = NULL;             /* New temp space */
42723     i64 nByte = 0;
42724 
42725     if( pPager->eState>PAGER_OPEN && isOpen(pPager->fd) ){
42726       rc = sqlite3OsFileSize(pPager->fd, &nByte);
42727     }
42728     if( rc==SQLITE_OK ){
42729       pNew = (char *)sqlite3PageMalloc(pageSize);
42730       if( !pNew ) rc = SQLITE_NOMEM;
42731     }
42732 
42733     if( rc==SQLITE_OK ){
42734       pager_reset(pPager);
42735       pPager->dbSize = (Pgno)((nByte+pageSize-1)/pageSize);
42736       pPager->pageSize = pageSize;
42737       sqlite3PageFree(pPager->pTmpSpace);
42738       pPager->pTmpSpace = pNew;
42739       sqlite3PcacheSetPageSize(pPager->pPCache, pageSize);
42740     }
42741   }
42742 
42743   *pPageSize = pPager->pageSize;
42744   if( rc==SQLITE_OK ){
42745     if( nReserve<0 ) nReserve = pPager->nReserve;
42746     assert( nReserve>=0 && nReserve<1000 );
42747     pPager->nReserve = (i16)nReserve;
42748     pagerReportSize(pPager);
42749     pagerFixMaplimit(pPager);
42750   }
42751   return rc;
42752 }
42753 
42754 /*
42755 ** Return a pointer to the "temporary page" buffer held internally
42756 ** by the pager.  This is a buffer that is big enough to hold the
42757 ** entire content of a database page.  This buffer is used internally
42758 ** during rollback and will be overwritten whenever a rollback
42759 ** occurs.  But other modules are free to use it too, as long as
42760 ** no rollbacks are happening.
42761 */
42762 SQLITE_PRIVATE void *sqlite3PagerTempSpace(Pager *pPager){
42763   return pPager->pTmpSpace;
42764 }
42765 
42766 /*
42767 ** Attempt to set the maximum database page count if mxPage is positive. 
42768 ** Make no changes if mxPage is zero or negative.  And never reduce the
42769 ** maximum page count below the current size of the database.
42770 **
42771 ** Regardless of mxPage, return the current maximum page count.
42772 */
42773 SQLITE_PRIVATE int sqlite3PagerMaxPageCount(Pager *pPager, int mxPage){
42774   if( mxPage>0 ){
42775     pPager->mxPgno = mxPage;
42776   }
42777   assert( pPager->eState!=PAGER_OPEN );      /* Called only by OP_MaxPgcnt */
42778   assert( pPager->mxPgno>=pPager->dbSize );  /* OP_MaxPgcnt enforces this */
42779   return pPager->mxPgno;
42780 }
42781 
42782 /*
42783 ** The following set of routines are used to disable the simulated
42784 ** I/O error mechanism.  These routines are used to avoid simulated
42785 ** errors in places where we do not care about errors.
42786 **
42787 ** Unless -DSQLITE_TEST=1 is used, these routines are all no-ops
42788 ** and generate no code.
42789 */
42790 #ifdef SQLITE_TEST
42791 SQLITE_API extern int sqlite3_io_error_pending;
42792 SQLITE_API extern int sqlite3_io_error_hit;
42793 static int saved_cnt;
42794 void disable_simulated_io_errors(void){
42795   saved_cnt = sqlite3_io_error_pending;
42796   sqlite3_io_error_pending = -1;
42797 }
42798 void enable_simulated_io_errors(void){
42799   sqlite3_io_error_pending = saved_cnt;
42800 }
42801 #else
42802 # define disable_simulated_io_errors()
42803 # define enable_simulated_io_errors()
42804 #endif
42805 
42806 /*
42807 ** Read the first N bytes from the beginning of the file into memory
42808 ** that pDest points to. 
42809 **
42810 ** If the pager was opened on a transient file (zFilename==""), or
42811 ** opened on a file less than N bytes in size, the output buffer is
42812 ** zeroed and SQLITE_OK returned. The rationale for this is that this 
42813 ** function is used to read database headers, and a new transient or
42814 ** zero sized database has a header than consists entirely of zeroes.
42815 **
42816 ** If any IO error apart from SQLITE_IOERR_SHORT_READ is encountered,
42817 ** the error code is returned to the caller and the contents of the
42818 ** output buffer undefined.
42819 */
42820 SQLITE_PRIVATE int sqlite3PagerReadFileheader(Pager *pPager, int N, unsigned char *pDest){
42821   int rc = SQLITE_OK;
42822   memset(pDest, 0, N);
42823   assert( isOpen(pPager->fd) || pPager->tempFile );
42824 
42825   /* This routine is only called by btree immediately after creating
42826   ** the Pager object.  There has not been an opportunity to transition
42827   ** to WAL mode yet.
42828   */
42829   assert( !pagerUseWal(pPager) );
42830 
42831   if( isOpen(pPager->fd) ){
42832     IOTRACE(("DBHDR %p 0 %d\n", pPager, N))
42833     rc = sqlite3OsRead(pPager->fd, pDest, N, 0);
42834     if( rc==SQLITE_IOERR_SHORT_READ ){
42835       rc = SQLITE_OK;
42836     }
42837   }
42838   return rc;
42839 }
42840 
42841 /*
42842 ** This function may only be called when a read-transaction is open on
42843 ** the pager. It returns the total number of pages in the database.
42844 **
42845 ** However, if the file is between 1 and <page-size> bytes in size, then 
42846 ** this is considered a 1 page file.
42847 */
42848 SQLITE_PRIVATE void sqlite3PagerPagecount(Pager *pPager, int *pnPage){
42849   assert( pPager->eState>=PAGER_READER );
42850   assert( pPager->eState!=PAGER_WRITER_FINISHED );
42851   *pnPage = (int)pPager->dbSize;
42852 }
42853 
42854 
42855 /*
42856 ** Try to obtain a lock of type locktype on the database file. If
42857 ** a similar or greater lock is already held, this function is a no-op
42858 ** (returning SQLITE_OK immediately).
42859 **
42860 ** Otherwise, attempt to obtain the lock using sqlite3OsLock(). Invoke 
42861 ** the busy callback if the lock is currently not available. Repeat 
42862 ** until the busy callback returns false or until the attempt to 
42863 ** obtain the lock succeeds.
42864 **
42865 ** Return SQLITE_OK on success and an error code if we cannot obtain
42866 ** the lock. If the lock is obtained successfully, set the Pager.state 
42867 ** variable to locktype before returning.
42868 */
42869 static int pager_wait_on_lock(Pager *pPager, int locktype){
42870   int rc;                              /* Return code */
42871 
42872   /* Check that this is either a no-op (because the requested lock is 
42873   ** already held, or one of the transistions that the busy-handler
42874   ** may be invoked during, according to the comment above
42875   ** sqlite3PagerSetBusyhandler().
42876   */
42877   assert( (pPager->eLock>=locktype)
42878        || (pPager->eLock==NO_LOCK && locktype==SHARED_LOCK)
42879        || (pPager->eLock==RESERVED_LOCK && locktype==EXCLUSIVE_LOCK)
42880   );
42881 
42882   do {
42883     rc = pagerLockDb(pPager, locktype);
42884   }while( rc==SQLITE_BUSY && pPager->xBusyHandler(pPager->pBusyHandlerArg) );
42885   return rc;
42886 }
42887 
42888 /*
42889 ** Function assertTruncateConstraint(pPager) checks that one of the 
42890 ** following is true for all dirty pages currently in the page-cache:
42891 **
42892 **   a) The page number is less than or equal to the size of the 
42893 **      current database image, in pages, OR
42894 **
42895 **   b) if the page content were written at this time, it would not
42896 **      be necessary to write the current content out to the sub-journal
42897 **      (as determined by function subjRequiresPage()).
42898 **
42899 ** If the condition asserted by this function were not true, and the
42900 ** dirty page were to be discarded from the cache via the pagerStress()
42901 ** routine, pagerStress() would not write the current page content to
42902 ** the database file. If a savepoint transaction were rolled back after
42903 ** this happened, the correct behavior would be to restore the current
42904 ** content of the page. However, since this content is not present in either
42905 ** the database file or the portion of the rollback journal and 
42906 ** sub-journal rolled back the content could not be restored and the
42907 ** database image would become corrupt. It is therefore fortunate that 
42908 ** this circumstance cannot arise.
42909 */
42910 #if defined(SQLITE_DEBUG)
42911 static void assertTruncateConstraintCb(PgHdr *pPg){
42912   assert( pPg->flags&PGHDR_DIRTY );
42913   assert( !subjRequiresPage(pPg) || pPg->pgno<=pPg->pPager->dbSize );
42914 }
42915 static void assertTruncateConstraint(Pager *pPager){
42916   sqlite3PcacheIterateDirty(pPager->pPCache, assertTruncateConstraintCb);
42917 }
42918 #else
42919 # define assertTruncateConstraint(pPager)
42920 #endif
42921 
42922 /*
42923 ** Truncate the in-memory database file image to nPage pages. This 
42924 ** function does not actually modify the database file on disk. It 
42925 ** just sets the internal state of the pager object so that the 
42926 ** truncation will be done when the current transaction is committed.
42927 **
42928 ** This function is only called right before committing a transaction.
42929 ** Once this function has been called, the transaction must either be
42930 ** rolled back or committed. It is not safe to call this function and
42931 ** then continue writing to the database.
42932 */
42933 SQLITE_PRIVATE void sqlite3PagerTruncateImage(Pager *pPager, Pgno nPage){
42934   assert( pPager->dbSize>=nPage );
42935   assert( pPager->eState>=PAGER_WRITER_CACHEMOD );
42936   pPager->dbSize = nPage;
42937 
42938   /* At one point the code here called assertTruncateConstraint() to
42939   ** ensure that all pages being truncated away by this operation are,
42940   ** if one or more savepoints are open, present in the savepoint 
42941   ** journal so that they can be restored if the savepoint is rolled
42942   ** back. This is no longer necessary as this function is now only
42943   ** called right before committing a transaction. So although the 
42944   ** Pager object may still have open savepoints (Pager.nSavepoint!=0), 
42945   ** they cannot be rolled back. So the assertTruncateConstraint() call
42946   ** is no longer correct. */
42947 }
42948 
42949 
42950 /*
42951 ** This function is called before attempting a hot-journal rollback. It
42952 ** syncs the journal file to disk, then sets pPager->journalHdr to the
42953 ** size of the journal file so that the pager_playback() routine knows
42954 ** that the entire journal file has been synced.
42955 **
42956 ** Syncing a hot-journal to disk before attempting to roll it back ensures 
42957 ** that if a power-failure occurs during the rollback, the process that
42958 ** attempts rollback following system recovery sees the same journal
42959 ** content as this process.
42960 **
42961 ** If everything goes as planned, SQLITE_OK is returned. Otherwise, 
42962 ** an SQLite error code.
42963 */
42964 static int pagerSyncHotJournal(Pager *pPager){
42965   int rc = SQLITE_OK;
42966   if( !pPager->noSync ){
42967     rc = sqlite3OsSync(pPager->jfd, SQLITE_SYNC_NORMAL);
42968   }
42969   if( rc==SQLITE_OK ){
42970     rc = sqlite3OsFileSize(pPager->jfd, &pPager->journalHdr);
42971   }
42972   return rc;
42973 }
42974 
42975 /*
42976 ** Obtain a reference to a memory mapped page object for page number pgno. 
42977 ** The new object will use the pointer pData, obtained from xFetch().
42978 ** If successful, set *ppPage to point to the new page reference
42979 ** and return SQLITE_OK. Otherwise, return an SQLite error code and set
42980 ** *ppPage to zero.
42981 **
42982 ** Page references obtained by calling this function should be released
42983 ** by calling pagerReleaseMapPage().
42984 */
42985 static int pagerAcquireMapPage(
42986   Pager *pPager,                  /* Pager object */
42987   Pgno pgno,                      /* Page number */
42988   void *pData,                    /* xFetch()'d data for this page */
42989   PgHdr **ppPage                  /* OUT: Acquired page object */
42990 ){
42991   PgHdr *p;                       /* Memory mapped page to return */
42992 
42993   if( pPager->pMmapFreelist ){
42994     *ppPage = p = pPager->pMmapFreelist;
42995     pPager->pMmapFreelist = p->pDirty;
42996     p->pDirty = 0;
42997     memset(p->pExtra, 0, pPager->nExtra);
42998   }else{
42999     *ppPage = p = (PgHdr *)sqlite3MallocZero(sizeof(PgHdr) + pPager->nExtra);
43000     if( p==0 ){
43001       sqlite3OsUnfetch(pPager->fd, (i64)(pgno-1) * pPager->pageSize, pData);
43002       return SQLITE_NOMEM;
43003     }
43004     p->pExtra = (void *)&p[1];
43005     p->flags = PGHDR_MMAP;
43006     p->nRef = 1;
43007     p->pPager = pPager;
43008   }
43009 
43010   assert( p->pExtra==(void *)&p[1] );
43011   assert( p->pPage==0 );
43012   assert( p->flags==PGHDR_MMAP );
43013   assert( p->pPager==pPager );
43014   assert( p->nRef==1 );
43015 
43016   p->pgno = pgno;
43017   p->pData = pData;
43018   pPager->nMmapOut++;
43019 
43020   return SQLITE_OK;
43021 }
43022 
43023 /*
43024 ** Release a reference to page pPg. pPg must have been returned by an 
43025 ** earlier call to pagerAcquireMapPage().
43026 */
43027 static void pagerReleaseMapPage(PgHdr *pPg){
43028   Pager *pPager = pPg->pPager;
43029   pPager->nMmapOut--;
43030   pPg->pDirty = pPager->pMmapFreelist;
43031   pPager->pMmapFreelist = pPg;
43032 
43033   assert( pPager->fd->pMethods->iVersion>=3 );
43034   sqlite3OsUnfetch(pPager->fd, (i64)(pPg->pgno-1)*pPager->pageSize, pPg->pData);
43035 }
43036 
43037 /*
43038 ** Free all PgHdr objects stored in the Pager.pMmapFreelist list.
43039 */
43040 static void pagerFreeMapHdrs(Pager *pPager){
43041   PgHdr *p;
43042   PgHdr *pNext;
43043   for(p=pPager->pMmapFreelist; p; p=pNext){
43044     pNext = p->pDirty;
43045     sqlite3_free(p);
43046   }
43047 }
43048 
43049 
43050 /*
43051 ** Shutdown the page cache.  Free all memory and close all files.
43052 **
43053 ** If a transaction was in progress when this routine is called, that
43054 ** transaction is rolled back.  All outstanding pages are invalidated
43055 ** and their memory is freed.  Any attempt to use a page associated
43056 ** with this page cache after this function returns will likely
43057 ** result in a coredump.
43058 **
43059 ** This function always succeeds. If a transaction is active an attempt
43060 ** is made to roll it back. If an error occurs during the rollback 
43061 ** a hot journal may be left in the filesystem but no error is returned
43062 ** to the caller.
43063 */
43064 SQLITE_PRIVATE int sqlite3PagerClose(Pager *pPager){
43065   u8 *pTmp = (u8 *)pPager->pTmpSpace;
43066 
43067   assert( assert_pager_state(pPager) );
43068   disable_simulated_io_errors();
43069   sqlite3BeginBenignMalloc();
43070   pagerFreeMapHdrs(pPager);
43071   /* pPager->errCode = 0; */
43072   pPager->exclusiveMode = 0;
43073 #ifndef SQLITE_OMIT_WAL
43074   sqlite3WalClose(pPager->pWal, pPager->ckptSyncFlags, pPager->pageSize, pTmp);
43075   pPager->pWal = 0;
43076 #endif
43077   pager_reset(pPager);
43078   if( MEMDB ){
43079     pager_unlock(pPager);
43080   }else{
43081     /* If it is open, sync the journal file before calling UnlockAndRollback.
43082     ** If this is not done, then an unsynced portion of the open journal 
43083     ** file may be played back into the database. If a power failure occurs 
43084     ** while this is happening, the database could become corrupt.
43085     **
43086     ** If an error occurs while trying to sync the journal, shift the pager
43087     ** into the ERROR state. This causes UnlockAndRollback to unlock the
43088     ** database and close the journal file without attempting to roll it
43089     ** back or finalize it. The next database user will have to do hot-journal
43090     ** rollback before accessing the database file.
43091     */
43092     if( isOpen(pPager->jfd) ){
43093       pager_error(pPager, pagerSyncHotJournal(pPager));
43094     }
43095     pagerUnlockAndRollback(pPager);
43096   }
43097   sqlite3EndBenignMalloc();
43098   enable_simulated_io_errors();
43099   PAGERTRACE(("CLOSE %d\n", PAGERID(pPager)));
43100   IOTRACE(("CLOSE %p\n", pPager))
43101   sqlite3OsClose(pPager->jfd);
43102   sqlite3OsClose(pPager->fd);
43103   sqlite3PageFree(pTmp);
43104   sqlite3PcacheClose(pPager->pPCache);
43105 
43106 #ifdef SQLITE_HAS_CODEC
43107   if( pPager->xCodecFree ) pPager->xCodecFree(pPager->pCodec);
43108 #endif
43109 
43110   assert( !pPager->aSavepoint && !pPager->pInJournal );
43111   assert( !isOpen(pPager->jfd) && !isOpen(pPager->sjfd) );
43112 
43113   sqlite3_free(pPager);
43114   return SQLITE_OK;
43115 }
43116 
43117 #if !defined(NDEBUG) || defined(SQLITE_TEST)
43118 /*
43119 ** Return the page number for page pPg.
43120 */
43121 SQLITE_PRIVATE Pgno sqlite3PagerPagenumber(DbPage *pPg){
43122   return pPg->pgno;
43123 }
43124 #endif
43125 
43126 /*
43127 ** Increment the reference count for page pPg.
43128 */
43129 SQLITE_PRIVATE void sqlite3PagerRef(DbPage *pPg){
43130   sqlite3PcacheRef(pPg);
43131 }
43132 
43133 /*
43134 ** Sync the journal. In other words, make sure all the pages that have
43135 ** been written to the journal have actually reached the surface of the
43136 ** disk and can be restored in the event of a hot-journal rollback.
43137 **
43138 ** If the Pager.noSync flag is set, then this function is a no-op.
43139 ** Otherwise, the actions required depend on the journal-mode and the 
43140 ** device characteristics of the file-system, as follows:
43141 **
43142 **   * If the journal file is an in-memory journal file, no action need
43143 **     be taken.
43144 **
43145 **   * Otherwise, if the device does not support the SAFE_APPEND property,
43146 **     then the nRec field of the most recently written journal header
43147 **     is updated to contain the number of journal records that have
43148 **     been written following it. If the pager is operating in full-sync
43149 **     mode, then the journal file is synced before this field is updated.
43150 **
43151 **   * If the device does not support the SEQUENTIAL property, then 
43152 **     journal file is synced.
43153 **
43154 ** Or, in pseudo-code:
43155 **
43156 **   if( NOT <in-memory journal> ){
43157 **     if( NOT SAFE_APPEND ){
43158 **       if( <full-sync mode> ) xSync(<journal file>);
43159 **       <update nRec field>
43160 **     } 
43161 **     if( NOT SEQUENTIAL ) xSync(<journal file>);
43162 **   }
43163 **
43164 ** If successful, this routine clears the PGHDR_NEED_SYNC flag of every 
43165 ** page currently held in memory before returning SQLITE_OK. If an IO
43166 ** error is encountered, then the IO error code is returned to the caller.
43167 */
43168 static int syncJournal(Pager *pPager, int newHdr){
43169   int rc;                         /* Return code */
43170 
43171   assert( pPager->eState==PAGER_WRITER_CACHEMOD
43172        || pPager->eState==PAGER_WRITER_DBMOD
43173   );
43174   assert( assert_pager_state(pPager) );
43175   assert( !pagerUseWal(pPager) );
43176 
43177   rc = sqlite3PagerExclusiveLock(pPager);
43178   if( rc!=SQLITE_OK ) return rc;
43179 
43180   if( !pPager->noSync ){
43181     assert( !pPager->tempFile );
43182     if( isOpen(pPager->jfd) && pPager->journalMode!=PAGER_JOURNALMODE_MEMORY ){
43183       const int iDc = sqlite3OsDeviceCharacteristics(pPager->fd);
43184       assert( isOpen(pPager->jfd) );
43185 
43186       if( 0==(iDc&SQLITE_IOCAP_SAFE_APPEND) ){
43187         /* This block deals with an obscure problem. If the last connection
43188         ** that wrote to this database was operating in persistent-journal
43189         ** mode, then the journal file may at this point actually be larger
43190         ** than Pager.journalOff bytes. If the next thing in the journal
43191         ** file happens to be a journal-header (written as part of the
43192         ** previous connection's transaction), and a crash or power-failure 
43193         ** occurs after nRec is updated but before this connection writes 
43194         ** anything else to the journal file (or commits/rolls back its 
43195         ** transaction), then SQLite may become confused when doing the 
43196         ** hot-journal rollback following recovery. It may roll back all
43197         ** of this connections data, then proceed to rolling back the old,
43198         ** out-of-date data that follows it. Database corruption.
43199         **
43200         ** To work around this, if the journal file does appear to contain
43201         ** a valid header following Pager.journalOff, then write a 0x00
43202         ** byte to the start of it to prevent it from being recognized.
43203         **
43204         ** Variable iNextHdrOffset is set to the offset at which this
43205         ** problematic header will occur, if it exists. aMagic is used 
43206         ** as a temporary buffer to inspect the first couple of bytes of
43207         ** the potential journal header.
43208         */
43209         i64 iNextHdrOffset;
43210         u8 aMagic[8];
43211         u8 zHeader[sizeof(aJournalMagic)+4];
43212 
43213         memcpy(zHeader, aJournalMagic, sizeof(aJournalMagic));
43214         put32bits(&zHeader[sizeof(aJournalMagic)], pPager->nRec);
43215 
43216         iNextHdrOffset = journalHdrOffset(pPager);
43217         rc = sqlite3OsRead(pPager->jfd, aMagic, 8, iNextHdrOffset);
43218         if( rc==SQLITE_OK && 0==memcmp(aMagic, aJournalMagic, 8) ){
43219           static const u8 zerobyte = 0;
43220           rc = sqlite3OsWrite(pPager->jfd, &zerobyte, 1, iNextHdrOffset);
43221         }
43222         if( rc!=SQLITE_OK && rc!=SQLITE_IOERR_SHORT_READ ){
43223           return rc;
43224         }
43225 
43226         /* Write the nRec value into the journal file header. If in
43227         ** full-synchronous mode, sync the journal first. This ensures that
43228         ** all data has really hit the disk before nRec is updated to mark
43229         ** it as a candidate for rollback.
43230         **
43231         ** This is not required if the persistent media supports the
43232         ** SAFE_APPEND property. Because in this case it is not possible 
43233         ** for garbage data to be appended to the file, the nRec field
43234         ** is populated with 0xFFFFFFFF when the journal header is written
43235         ** and never needs to be updated.
43236         */
43237         if( pPager->fullSync && 0==(iDc&SQLITE_IOCAP_SEQUENTIAL) ){
43238           PAGERTRACE(("SYNC journal of %d\n", PAGERID(pPager)));
43239           IOTRACE(("JSYNC %p\n", pPager))
43240           rc = sqlite3OsSync(pPager->jfd, pPager->syncFlags);
43241           if( rc!=SQLITE_OK ) return rc;
43242         }
43243         IOTRACE(("JHDR %p %lld\n", pPager, pPager->journalHdr));
43244         rc = sqlite3OsWrite(
43245             pPager->jfd, zHeader, sizeof(zHeader), pPager->journalHdr
43246         );
43247         if( rc!=SQLITE_OK ) return rc;
43248       }
43249       if( 0==(iDc&SQLITE_IOCAP_SEQUENTIAL) ){
43250         PAGERTRACE(("SYNC journal of %d\n", PAGERID(pPager)));
43251         IOTRACE(("JSYNC %p\n", pPager))
43252         rc = sqlite3OsSync(pPager->jfd, pPager->syncFlags| 
43253           (pPager->syncFlags==SQLITE_SYNC_FULL?SQLITE_SYNC_DATAONLY:0)
43254         );
43255         if( rc!=SQLITE_OK ) return rc;
43256       }
43257 
43258       pPager->journalHdr = pPager->journalOff;
43259       if( newHdr && 0==(iDc&SQLITE_IOCAP_SAFE_APPEND) ){
43260         pPager->nRec = 0;
43261         rc = writeJournalHdr(pPager);
43262         if( rc!=SQLITE_OK ) return rc;
43263       }
43264     }else{
43265       pPager->journalHdr = pPager->journalOff;
43266     }
43267   }
43268 
43269   /* Unless the pager is in noSync mode, the journal file was just 
43270   ** successfully synced. Either way, clear the PGHDR_NEED_SYNC flag on 
43271   ** all pages.
43272   */
43273   sqlite3PcacheClearSyncFlags(pPager->pPCache);
43274   pPager->eState = PAGER_WRITER_DBMOD;
43275   assert( assert_pager_state(pPager) );
43276   return SQLITE_OK;
43277 }
43278 
43279 /*
43280 ** The argument is the first in a linked list of dirty pages connected
43281 ** by the PgHdr.pDirty pointer. This function writes each one of the
43282 ** in-memory pages in the list to the database file. The argument may
43283 ** be NULL, representing an empty list. In this case this function is
43284 ** a no-op.
43285 **
43286 ** The pager must hold at least a RESERVED lock when this function
43287 ** is called. Before writing anything to the database file, this lock
43288 ** is upgraded to an EXCLUSIVE lock. If the lock cannot be obtained,
43289 ** SQLITE_BUSY is returned and no data is written to the database file.
43290 ** 
43291 ** If the pager is a temp-file pager and the actual file-system file
43292 ** is not yet open, it is created and opened before any data is 
43293 ** written out.
43294 **
43295 ** Once the lock has been upgraded and, if necessary, the file opened,
43296 ** the pages are written out to the database file in list order. Writing
43297 ** a page is skipped if it meets either of the following criteria:
43298 **
43299 **   * The page number is greater than Pager.dbSize, or
43300 **   * The PGHDR_DONT_WRITE flag is set on the page.
43301 **
43302 ** If writing out a page causes the database file to grow, Pager.dbFileSize
43303 ** is updated accordingly. If page 1 is written out, then the value cached
43304 ** in Pager.dbFileVers[] is updated to match the new value stored in
43305 ** the database file.
43306 **
43307 ** If everything is successful, SQLITE_OK is returned. If an IO error 
43308 ** occurs, an IO error code is returned. Or, if the EXCLUSIVE lock cannot
43309 ** be obtained, SQLITE_BUSY is returned.
43310 */
43311 static int pager_write_pagelist(Pager *pPager, PgHdr *pList){
43312   int rc = SQLITE_OK;                  /* Return code */
43313 
43314   /* This function is only called for rollback pagers in WRITER_DBMOD state. */
43315   assert( !pagerUseWal(pPager) );
43316   assert( pPager->eState==PAGER_WRITER_DBMOD );
43317   assert( pPager->eLock==EXCLUSIVE_LOCK );
43318 
43319   /* If the file is a temp-file has not yet been opened, open it now. It
43320   ** is not possible for rc to be other than SQLITE_OK if this branch
43321   ** is taken, as pager_wait_on_lock() is a no-op for temp-files.
43322   */
43323   if( !isOpen(pPager->fd) ){
43324     assert( pPager->tempFile && rc==SQLITE_OK );
43325     rc = pagerOpentemp(pPager, pPager->fd, pPager->vfsFlags);
43326   }
43327 
43328   /* Before the first write, give the VFS a hint of what the final
43329   ** file size will be.
43330   */
43331   assert( rc!=SQLITE_OK || isOpen(pPager->fd) );
43332   if( rc==SQLITE_OK 
43333    && pPager->dbHintSize<pPager->dbSize
43334    && (pList->pDirty || pList->pgno>pPager->dbHintSize)
43335   ){
43336     sqlite3_int64 szFile = pPager->pageSize * (sqlite3_int64)pPager->dbSize;
43337     sqlite3OsFileControlHint(pPager->fd, SQLITE_FCNTL_SIZE_HINT, &szFile);
43338     pPager->dbHintSize = pPager->dbSize;
43339   }
43340 
43341   while( rc==SQLITE_OK && pList ){
43342     Pgno pgno = pList->pgno;
43343 
43344     /* If there are dirty pages in the page cache with page numbers greater
43345     ** than Pager.dbSize, this means sqlite3PagerTruncateImage() was called to
43346     ** make the file smaller (presumably by auto-vacuum code). Do not write
43347     ** any such pages to the file.
43348     **
43349     ** Also, do not write out any page that has the PGHDR_DONT_WRITE flag
43350     ** set (set by sqlite3PagerDontWrite()).
43351     */
43352     if( pgno<=pPager->dbSize && 0==(pList->flags&PGHDR_DONT_WRITE) ){
43353       i64 offset = (pgno-1)*(i64)pPager->pageSize;   /* Offset to write */
43354       char *pData;                                   /* Data to write */    
43355 
43356       assert( (pList->flags&PGHDR_NEED_SYNC)==0 );
43357       if( pList->pgno==1 ) pager_write_changecounter(pList);
43358 
43359       /* Encode the database */
43360       CODEC2(pPager, pList->pData, pgno, 6, return SQLITE_NOMEM, pData);
43361 
43362       /* Write out the page data. */
43363       rc = sqlite3OsWrite(pPager->fd, pData, pPager->pageSize, offset);
43364 
43365       /* If page 1 was just written, update Pager.dbFileVers to match
43366       ** the value now stored in the database file. If writing this 
43367       ** page caused the database file to grow, update dbFileSize. 
43368       */
43369       if( pgno==1 ){
43370         memcpy(&pPager->dbFileVers, &pData[24], sizeof(pPager->dbFileVers));
43371       }
43372       if( pgno>pPager->dbFileSize ){
43373         pPager->dbFileSize = pgno;
43374       }
43375       pPager->aStat[PAGER_STAT_WRITE]++;
43376 
43377       /* Update any backup objects copying the contents of this pager. */
43378       sqlite3BackupUpdate(pPager->pBackup, pgno, (u8*)pList->pData);
43379 
43380       PAGERTRACE(("STORE %d page %d hash(%08x)\n",
43381                    PAGERID(pPager), pgno, pager_pagehash(pList)));
43382       IOTRACE(("PGOUT %p %d\n", pPager, pgno));
43383       PAGER_INCR(sqlite3_pager_writedb_count);
43384     }else{
43385       PAGERTRACE(("NOSTORE %d page %d\n", PAGERID(pPager), pgno));
43386     }
43387     pager_set_pagehash(pList);
43388     pList = pList->pDirty;
43389   }
43390 
43391   return rc;
43392 }
43393 
43394 /*
43395 ** Ensure that the sub-journal file is open. If it is already open, this 
43396 ** function is a no-op.
43397 **
43398 ** SQLITE_OK is returned if everything goes according to plan. An 
43399 ** SQLITE_IOERR_XXX error code is returned if a call to sqlite3OsOpen() 
43400 ** fails.
43401 */
43402 static int openSubJournal(Pager *pPager){
43403   int rc = SQLITE_OK;
43404   if( !isOpen(pPager->sjfd) ){
43405     if( pPager->journalMode==PAGER_JOURNALMODE_MEMORY || pPager->subjInMemory ){
43406       sqlite3MemJournalOpen(pPager->sjfd);
43407     }else{
43408       rc = pagerOpentemp(pPager, pPager->sjfd, SQLITE_OPEN_SUBJOURNAL);
43409     }
43410   }
43411   return rc;
43412 }
43413 
43414 /*
43415 ** Append a record of the current state of page pPg to the sub-journal. 
43416 ** It is the callers responsibility to use subjRequiresPage() to check 
43417 ** that it is really required before calling this function.
43418 **
43419 ** If successful, set the bit corresponding to pPg->pgno in the bitvecs
43420 ** for all open savepoints before returning.
43421 **
43422 ** This function returns SQLITE_OK if everything is successful, an IO
43423 ** error code if the attempt to write to the sub-journal fails, or 
43424 ** SQLITE_NOMEM if a malloc fails while setting a bit in a savepoint
43425 ** bitvec.
43426 */
43427 static int subjournalPage(PgHdr *pPg){
43428   int rc = SQLITE_OK;
43429   Pager *pPager = pPg->pPager;
43430   if( pPager->journalMode!=PAGER_JOURNALMODE_OFF ){
43431 
43432     /* Open the sub-journal, if it has not already been opened */
43433     assert( pPager->useJournal );
43434     assert( isOpen(pPager->jfd) || pagerUseWal(pPager) );
43435     assert( isOpen(pPager->sjfd) || pPager->nSubRec==0 );
43436     assert( pagerUseWal(pPager) 
43437          || pageInJournal(pPg) 
43438          || pPg->pgno>pPager->dbOrigSize 
43439     );
43440     rc = openSubJournal(pPager);
43441 
43442     /* If the sub-journal was opened successfully (or was already open),
43443     ** write the journal record into the file.  */
43444     if( rc==SQLITE_OK ){
43445       void *pData = pPg->pData;
43446       i64 offset = (i64)pPager->nSubRec*(4+pPager->pageSize);
43447       char *pData2;
43448   
43449       CODEC2(pPager, pData, pPg->pgno, 7, return SQLITE_NOMEM, pData2);
43450       PAGERTRACE(("STMT-JOURNAL %d page %d\n", PAGERID(pPager), pPg->pgno));
43451       rc = write32bits(pPager->sjfd, offset, pPg->pgno);
43452       if( rc==SQLITE_OK ){
43453         rc = sqlite3OsWrite(pPager->sjfd, pData2, pPager->pageSize, offset+4);
43454       }
43455     }
43456   }
43457   if( rc==SQLITE_OK ){
43458     pPager->nSubRec++;
43459     assert( pPager->nSavepoint>0 );
43460     rc = addToSavepointBitvecs(pPager, pPg->pgno);
43461   }
43462   return rc;
43463 }
43464 
43465 /*
43466 ** This function is called by the pcache layer when it has reached some
43467 ** soft memory limit. The first argument is a pointer to a Pager object
43468 ** (cast as a void*). The pager is always 'purgeable' (not an in-memory
43469 ** database). The second argument is a reference to a page that is 
43470 ** currently dirty but has no outstanding references. The page
43471 ** is always associated with the Pager object passed as the first 
43472 ** argument.
43473 **
43474 ** The job of this function is to make pPg clean by writing its contents
43475 ** out to the database file, if possible. This may involve syncing the
43476 ** journal file. 
43477 **
43478 ** If successful, sqlite3PcacheMakeClean() is called on the page and
43479 ** SQLITE_OK returned. If an IO error occurs while trying to make the
43480 ** page clean, the IO error code is returned. If the page cannot be
43481 ** made clean for some other reason, but no error occurs, then SQLITE_OK
43482 ** is returned by sqlite3PcacheMakeClean() is not called.
43483 */
43484 static int pagerStress(void *p, PgHdr *pPg){
43485   Pager *pPager = (Pager *)p;
43486   int rc = SQLITE_OK;
43487 
43488   assert( pPg->pPager==pPager );
43489   assert( pPg->flags&PGHDR_DIRTY );
43490 
43491   /* The doNotSpill NOSYNC bit is set during times when doing a sync of
43492   ** journal (and adding a new header) is not allowed.  This occurs
43493   ** during calls to sqlite3PagerWrite() while trying to journal multiple
43494   ** pages belonging to the same sector.
43495   **
43496   ** The doNotSpill ROLLBACK and OFF bits inhibits all cache spilling
43497   ** regardless of whether or not a sync is required.  This is set during
43498   ** a rollback or by user request, respectively.
43499   **
43500   ** Spilling is also prohibited when in an error state since that could
43501   ** lead to database corruption.   In the current implementaton it 
43502   ** is impossible for sqlite3PcacheFetch() to be called with createFlag==1
43503   ** while in the error state, hence it is impossible for this routine to
43504   ** be called in the error state.  Nevertheless, we include a NEVER()
43505   ** test for the error state as a safeguard against future changes.
43506   */
43507   if( NEVER(pPager->errCode) ) return SQLITE_OK;
43508   testcase( pPager->doNotSpill & SPILLFLAG_ROLLBACK );
43509   testcase( pPager->doNotSpill & SPILLFLAG_OFF );
43510   testcase( pPager->doNotSpill & SPILLFLAG_NOSYNC );
43511   if( pPager->doNotSpill
43512    && ((pPager->doNotSpill & (SPILLFLAG_ROLLBACK|SPILLFLAG_OFF))!=0
43513       || (pPg->flags & PGHDR_NEED_SYNC)!=0)
43514   ){
43515     return SQLITE_OK;
43516   }
43517 
43518   pPg->pDirty = 0;
43519   if( pagerUseWal(pPager) ){
43520     /* Write a single frame for this page to the log. */
43521     if( subjRequiresPage(pPg) ){ 
43522       rc = subjournalPage(pPg); 
43523     }
43524     if( rc==SQLITE_OK ){
43525       rc = pagerWalFrames(pPager, pPg, 0, 0);
43526     }
43527   }else{
43528   
43529     /* Sync the journal file if required. */
43530     if( pPg->flags&PGHDR_NEED_SYNC 
43531      || pPager->eState==PAGER_WRITER_CACHEMOD
43532     ){
43533       rc = syncJournal(pPager, 1);
43534     }
43535   
43536     /* If the page number of this page is larger than the current size of
43537     ** the database image, it may need to be written to the sub-journal.
43538     ** This is because the call to pager_write_pagelist() below will not
43539     ** actually write data to the file in this case.
43540     **
43541     ** Consider the following sequence of events:
43542     **
43543     **   BEGIN;
43544     **     <journal page X>
43545     **     <modify page X>
43546     **     SAVEPOINT sp;
43547     **       <shrink database file to Y pages>
43548     **       pagerStress(page X)
43549     **     ROLLBACK TO sp;
43550     **
43551     ** If (X>Y), then when pagerStress is called page X will not be written
43552     ** out to the database file, but will be dropped from the cache. Then,
43553     ** following the "ROLLBACK TO sp" statement, reading page X will read
43554     ** data from the database file. This will be the copy of page X as it
43555     ** was when the transaction started, not as it was when "SAVEPOINT sp"
43556     ** was executed.
43557     **
43558     ** The solution is to write the current data for page X into the 
43559     ** sub-journal file now (if it is not already there), so that it will
43560     ** be restored to its current value when the "ROLLBACK TO sp" is 
43561     ** executed.
43562     */
43563     if( NEVER(
43564         rc==SQLITE_OK && pPg->pgno>pPager->dbSize && subjRequiresPage(pPg)
43565     ) ){
43566       rc = subjournalPage(pPg);
43567     }
43568   
43569     /* Write the contents of the page out to the database file. */
43570     if( rc==SQLITE_OK ){
43571       assert( (pPg->flags&PGHDR_NEED_SYNC)==0 );
43572       rc = pager_write_pagelist(pPager, pPg);
43573     }
43574   }
43575 
43576   /* Mark the page as clean. */
43577   if( rc==SQLITE_OK ){
43578     PAGERTRACE(("STRESS %d page %d\n", PAGERID(pPager), pPg->pgno));
43579     sqlite3PcacheMakeClean(pPg);
43580   }
43581 
43582   return pager_error(pPager, rc); 
43583 }
43584 
43585 
43586 /*
43587 ** Allocate and initialize a new Pager object and put a pointer to it
43588 ** in *ppPager. The pager should eventually be freed by passing it
43589 ** to sqlite3PagerClose().
43590 **
43591 ** The zFilename argument is the path to the database file to open.
43592 ** If zFilename is NULL then a randomly-named temporary file is created
43593 ** and used as the file to be cached. Temporary files are be deleted
43594 ** automatically when they are closed. If zFilename is ":memory:" then 
43595 ** all information is held in cache. It is never written to disk. 
43596 ** This can be used to implement an in-memory database.
43597 **
43598 ** The nExtra parameter specifies the number of bytes of space allocated
43599 ** along with each page reference. This space is available to the user
43600 ** via the sqlite3PagerGetExtra() API.
43601 **
43602 ** The flags argument is used to specify properties that affect the
43603 ** operation of the pager. It should be passed some bitwise combination
43604 ** of the PAGER_* flags.
43605 **
43606 ** The vfsFlags parameter is a bitmask to pass to the flags parameter
43607 ** of the xOpen() method of the supplied VFS when opening files. 
43608 **
43609 ** If the pager object is allocated and the specified file opened 
43610 ** successfully, SQLITE_OK is returned and *ppPager set to point to
43611 ** the new pager object. If an error occurs, *ppPager is set to NULL
43612 ** and error code returned. This function may return SQLITE_NOMEM
43613 ** (sqlite3Malloc() is used to allocate memory), SQLITE_CANTOPEN or 
43614 ** various SQLITE_IO_XXX errors.
43615 */
43616 SQLITE_PRIVATE int sqlite3PagerOpen(
43617   sqlite3_vfs *pVfs,       /* The virtual file system to use */
43618   Pager **ppPager,         /* OUT: Return the Pager structure here */
43619   const char *zFilename,   /* Name of the database file to open */
43620   int nExtra,              /* Extra bytes append to each in-memory page */
43621   int flags,               /* flags controlling this file */
43622   int vfsFlags,            /* flags passed through to sqlite3_vfs.xOpen() */
43623   void (*xReinit)(DbPage*) /* Function to reinitialize pages */
43624 ){
43625   u8 *pPtr;
43626   Pager *pPager = 0;       /* Pager object to allocate and return */
43627   int rc = SQLITE_OK;      /* Return code */
43628   int tempFile = 0;        /* True for temp files (incl. in-memory files) */
43629   int memDb = 0;           /* True if this is an in-memory file */
43630   int readOnly = 0;        /* True if this is a read-only file */
43631   int journalFileSize;     /* Bytes to allocate for each journal fd */
43632   char *zPathname = 0;     /* Full path to database file */
43633   int nPathname = 0;       /* Number of bytes in zPathname */
43634   int useJournal = (flags & PAGER_OMIT_JOURNAL)==0; /* False to omit journal */
43635   int pcacheSize = sqlite3PcacheSize();       /* Bytes to allocate for PCache */
43636   u32 szPageDflt = SQLITE_DEFAULT_PAGE_SIZE;  /* Default page size */
43637   const char *zUri = 0;    /* URI args to copy */
43638   int nUri = 0;            /* Number of bytes of URI args at *zUri */
43639 
43640   /* Figure out how much space is required for each journal file-handle
43641   ** (there are two of them, the main journal and the sub-journal). This
43642   ** is the maximum space required for an in-memory journal file handle 
43643   ** and a regular journal file-handle. Note that a "regular journal-handle"
43644   ** may be a wrapper capable of caching the first portion of the journal
43645   ** file in memory to implement the atomic-write optimization (see 
43646   ** source file journal.c).
43647   */
43648   if( sqlite3JournalSize(pVfs)>sqlite3MemJournalSize() ){
43649     journalFileSize = ROUND8(sqlite3JournalSize(pVfs));
43650   }else{
43651     journalFileSize = ROUND8(sqlite3MemJournalSize());
43652   }
43653 
43654   /* Set the output variable to NULL in case an error occurs. */
43655   *ppPager = 0;
43656 
43657 #ifndef SQLITE_OMIT_MEMORYDB
43658   if( flags & PAGER_MEMORY ){
43659     memDb = 1;
43660     if( zFilename && zFilename[0] ){
43661       zPathname = sqlite3DbStrDup(0, zFilename);
43662       if( zPathname==0  ) return SQLITE_NOMEM;
43663       nPathname = sqlite3Strlen30(zPathname);
43664       zFilename = 0;
43665     }
43666   }
43667 #endif
43668 
43669   /* Compute and store the full pathname in an allocated buffer pointed
43670   ** to by zPathname, length nPathname. Or, if this is a temporary file,
43671   ** leave both nPathname and zPathname set to 0.
43672   */
43673   if( zFilename && zFilename[0] ){
43674     const char *z;
43675     nPathname = pVfs->mxPathname+1;
43676     zPathname = sqlite3DbMallocRaw(0, nPathname*2);
43677     if( zPathname==0 ){
43678       return SQLITE_NOMEM;
43679     }
43680     zPathname[0] = 0; /* Make sure initialized even if FullPathname() fails */
43681     rc = sqlite3OsFullPathname(pVfs, zFilename, nPathname, zPathname);
43682     nPathname = sqlite3Strlen30(zPathname);
43683     z = zUri = &zFilename[sqlite3Strlen30(zFilename)+1];
43684     while( *z ){
43685       z += sqlite3Strlen30(z)+1;
43686       z += sqlite3Strlen30(z)+1;
43687     }
43688     nUri = (int)(&z[1] - zUri);
43689     assert( nUri>=0 );
43690     if( rc==SQLITE_OK && nPathname+8>pVfs->mxPathname ){
43691       /* This branch is taken when the journal path required by
43692       ** the database being opened will be more than pVfs->mxPathname
43693       ** bytes in length. This means the database cannot be opened,
43694       ** as it will not be possible to open the journal file or even
43695       ** check for a hot-journal before reading.
43696       */
43697       rc = SQLITE_CANTOPEN_BKPT;
43698     }
43699     if( rc!=SQLITE_OK ){
43700       sqlite3DbFree(0, zPathname);
43701       return rc;
43702     }
43703   }
43704 
43705   /* Allocate memory for the Pager structure, PCache object, the
43706   ** three file descriptors, the database file name and the journal 
43707   ** file name. The layout in memory is as follows:
43708   **
43709   **     Pager object                    (sizeof(Pager) bytes)
43710   **     PCache object                   (sqlite3PcacheSize() bytes)
43711   **     Database file handle            (pVfs->szOsFile bytes)
43712   **     Sub-journal file handle         (journalFileSize bytes)
43713   **     Main journal file handle        (journalFileSize bytes)
43714   **     Database file name              (nPathname+1 bytes)
43715   **     Journal file name               (nPathname+8+1 bytes)
43716   */
43717   pPtr = (u8 *)sqlite3MallocZero(
43718     ROUND8(sizeof(*pPager)) +      /* Pager structure */
43719     ROUND8(pcacheSize) +           /* PCache object */
43720     ROUND8(pVfs->szOsFile) +       /* The main db file */
43721     journalFileSize * 2 +          /* The two journal files */ 
43722     nPathname + 1 + nUri +         /* zFilename */
43723     nPathname + 8 + 2              /* zJournal */
43724 #ifndef SQLITE_OMIT_WAL
43725     + nPathname + 4 + 2            /* zWal */
43726 #endif
43727   );
43728   assert( EIGHT_BYTE_ALIGNMENT(SQLITE_INT_TO_PTR(journalFileSize)) );
43729   if( !pPtr ){
43730     sqlite3DbFree(0, zPathname);
43731     return SQLITE_NOMEM;
43732   }
43733   pPager =              (Pager*)(pPtr);
43734   pPager->pPCache =    (PCache*)(pPtr += ROUND8(sizeof(*pPager)));
43735   pPager->fd =   (sqlite3_file*)(pPtr += ROUND8(pcacheSize));
43736   pPager->sjfd = (sqlite3_file*)(pPtr += ROUND8(pVfs->szOsFile));
43737   pPager->jfd =  (sqlite3_file*)(pPtr += journalFileSize);
43738   pPager->zFilename =    (char*)(pPtr += journalFileSize);
43739   assert( EIGHT_BYTE_ALIGNMENT(pPager->jfd) );
43740 
43741   /* Fill in the Pager.zFilename and Pager.zJournal buffers, if required. */
43742   if( zPathname ){
43743     assert( nPathname>0 );
43744     pPager->zJournal =   (char*)(pPtr += nPathname + 1 + nUri);
43745     memcpy(pPager->zFilename, zPathname, nPathname);
43746     if( nUri ) memcpy(&pPager->zFilename[nPathname+1], zUri, nUri);
43747     memcpy(pPager->zJournal, zPathname, nPathname);
43748     memcpy(&pPager->zJournal[nPathname], "-journal\000", 8+2);
43749     sqlite3FileSuffix3(pPager->zFilename, pPager->zJournal);
43750 #ifndef SQLITE_OMIT_WAL
43751     pPager->zWal = &pPager->zJournal[nPathname+8+1];
43752     memcpy(pPager->zWal, zPathname, nPathname);
43753     memcpy(&pPager->zWal[nPathname], "-wal\000", 4+1);
43754     sqlite3FileSuffix3(pPager->zFilename, pPager->zWal);
43755 #endif
43756     sqlite3DbFree(0, zPathname);
43757   }
43758   pPager->pVfs = pVfs;
43759   pPager->vfsFlags = vfsFlags;
43760 
43761   /* Open the pager file.
43762   */
43763   if( zFilename && zFilename[0] ){
43764     int fout = 0;                    /* VFS flags returned by xOpen() */
43765     rc = sqlite3OsOpen(pVfs, pPager->zFilename, pPager->fd, vfsFlags, &fout);
43766     assert( !memDb );
43767     readOnly = (fout&SQLITE_OPEN_READONLY);
43768 
43769     /* If the file was successfully opened for read/write access,
43770     ** choose a default page size in case we have to create the
43771     ** database file. The default page size is the maximum of:
43772     **
43773     **    + SQLITE_DEFAULT_PAGE_SIZE,
43774     **    + The value returned by sqlite3OsSectorSize()
43775     **    + The largest page size that can be written atomically.
43776     */
43777     if( rc==SQLITE_OK && !readOnly ){
43778       setSectorSize(pPager);
43779       assert(SQLITE_DEFAULT_PAGE_SIZE<=SQLITE_MAX_DEFAULT_PAGE_SIZE);
43780       if( szPageDflt<pPager->sectorSize ){
43781         if( pPager->sectorSize>SQLITE_MAX_DEFAULT_PAGE_SIZE ){
43782           szPageDflt = SQLITE_MAX_DEFAULT_PAGE_SIZE;
43783         }else{
43784           szPageDflt = (u32)pPager->sectorSize;
43785         }
43786       }
43787 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
43788       {
43789         int iDc = sqlite3OsDeviceCharacteristics(pPager->fd);
43790         int ii;
43791         assert(SQLITE_IOCAP_ATOMIC512==(512>>8));
43792         assert(SQLITE_IOCAP_ATOMIC64K==(65536>>8));
43793         assert(SQLITE_MAX_DEFAULT_PAGE_SIZE<=65536);
43794         for(ii=szPageDflt; ii<=SQLITE_MAX_DEFAULT_PAGE_SIZE; ii=ii*2){
43795           if( iDc&(SQLITE_IOCAP_ATOMIC|(ii>>8)) ){
43796             szPageDflt = ii;
43797           }
43798         }
43799       }
43800 #endif
43801     }
43802   }else{
43803     /* If a temporary file is requested, it is not opened immediately.
43804     ** In this case we accept the default page size and delay actually
43805     ** opening the file until the first call to OsWrite().
43806     **
43807     ** This branch is also run for an in-memory database. An in-memory
43808     ** database is the same as a temp-file that is never written out to
43809     ** disk and uses an in-memory rollback journal.
43810     */ 
43811     tempFile = 1;
43812     pPager->eState = PAGER_READER;
43813     pPager->eLock = EXCLUSIVE_LOCK;
43814     readOnly = (vfsFlags&SQLITE_OPEN_READONLY);
43815   }
43816 
43817   /* The following call to PagerSetPagesize() serves to set the value of 
43818   ** Pager.pageSize and to allocate the Pager.pTmpSpace buffer.
43819   */
43820   if( rc==SQLITE_OK ){
43821     assert( pPager->memDb==0 );
43822     rc = sqlite3PagerSetPagesize(pPager, &szPageDflt, -1);
43823     testcase( rc!=SQLITE_OK );
43824   }
43825 
43826   /* If an error occurred in either of the blocks above, free the 
43827   ** Pager structure and close the file.
43828   */
43829   if( rc!=SQLITE_OK ){
43830     assert( !pPager->pTmpSpace );
43831     sqlite3OsClose(pPager->fd);
43832     sqlite3_free(pPager);
43833     return rc;
43834   }
43835 
43836   /* Initialize the PCache object. */
43837   assert( nExtra<1000 );
43838   nExtra = ROUND8(nExtra);
43839   sqlite3PcacheOpen(szPageDflt, nExtra, !memDb,
43840                     !memDb?pagerStress:0, (void *)pPager, pPager->pPCache);
43841 
43842   PAGERTRACE(("OPEN %d %s\n", FILEHANDLEID(pPager->fd), pPager->zFilename));
43843   IOTRACE(("OPEN %p %s\n", pPager, pPager->zFilename))
43844 
43845   pPager->useJournal = (u8)useJournal;
43846   /* pPager->stmtOpen = 0; */
43847   /* pPager->stmtInUse = 0; */
43848   /* pPager->nRef = 0; */
43849   /* pPager->stmtSize = 0; */
43850   /* pPager->stmtJSize = 0; */
43851   /* pPager->nPage = 0; */
43852   pPager->mxPgno = SQLITE_MAX_PAGE_COUNT;
43853   /* pPager->state = PAGER_UNLOCK; */
43854 #if 0
43855   assert( pPager->state == (tempFile ? PAGER_EXCLUSIVE : PAGER_UNLOCK) );
43856 #endif
43857   /* pPager->errMask = 0; */
43858   pPager->tempFile = (u8)tempFile;
43859   assert( tempFile==PAGER_LOCKINGMODE_NORMAL 
43860           || tempFile==PAGER_LOCKINGMODE_EXCLUSIVE );
43861   assert( PAGER_LOCKINGMODE_EXCLUSIVE==1 );
43862   pPager->exclusiveMode = (u8)tempFile; 
43863   pPager->changeCountDone = pPager->tempFile;
43864   pPager->memDb = (u8)memDb;
43865   pPager->readOnly = (u8)readOnly;
43866   assert( useJournal || pPager->tempFile );
43867   pPager->noSync = pPager->tempFile;
43868   if( pPager->noSync ){
43869     assert( pPager->fullSync==0 );
43870     assert( pPager->syncFlags==0 );
43871     assert( pPager->walSyncFlags==0 );
43872     assert( pPager->ckptSyncFlags==0 );
43873   }else{
43874     pPager->fullSync = 1;
43875     pPager->syncFlags = SQLITE_SYNC_NORMAL;
43876     pPager->walSyncFlags = SQLITE_SYNC_NORMAL | WAL_SYNC_TRANSACTIONS;
43877     pPager->ckptSyncFlags = SQLITE_SYNC_NORMAL;
43878   }
43879   /* pPager->pFirst = 0; */
43880   /* pPager->pFirstSynced = 0; */
43881   /* pPager->pLast = 0; */
43882   pPager->nExtra = (u16)nExtra;
43883   pPager->journalSizeLimit = SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT;
43884   assert( isOpen(pPager->fd) || tempFile );
43885   setSectorSize(pPager);
43886   if( !useJournal ){
43887     pPager->journalMode = PAGER_JOURNALMODE_OFF;
43888   }else if( memDb ){
43889     pPager->journalMode = PAGER_JOURNALMODE_MEMORY;
43890   }
43891   /* pPager->xBusyHandler = 0; */
43892   /* pPager->pBusyHandlerArg = 0; */
43893   pPager->xReiniter = xReinit;
43894   /* memset(pPager->aHash, 0, sizeof(pPager->aHash)); */
43895   /* pPager->szMmap = SQLITE_DEFAULT_MMAP_SIZE // will be set by btree.c */
43896 
43897   *ppPager = pPager;
43898   return SQLITE_OK;
43899 }
43900 
43901 
43902 
43903 /*
43904 ** This function is called after transitioning from PAGER_UNLOCK to
43905 ** PAGER_SHARED state. It tests if there is a hot journal present in
43906 ** the file-system for the given pager. A hot journal is one that 
43907 ** needs to be played back. According to this function, a hot-journal
43908 ** file exists if the following criteria are met:
43909 **
43910 **   * The journal file exists in the file system, and
43911 **   * No process holds a RESERVED or greater lock on the database file, and
43912 **   * The database file itself is greater than 0 bytes in size, and
43913 **   * The first byte of the journal file exists and is not 0x00.
43914 **
43915 ** If the current size of the database file is 0 but a journal file
43916 ** exists, that is probably an old journal left over from a prior
43917 ** database with the same name. In this case the journal file is
43918 ** just deleted using OsDelete, *pExists is set to 0 and SQLITE_OK
43919 ** is returned.
43920 **
43921 ** This routine does not check if there is a master journal filename
43922 ** at the end of the file. If there is, and that master journal file
43923 ** does not exist, then the journal file is not really hot. In this
43924 ** case this routine will return a false-positive. The pager_playback()
43925 ** routine will discover that the journal file is not really hot and 
43926 ** will not roll it back. 
43927 **
43928 ** If a hot-journal file is found to exist, *pExists is set to 1 and 
43929 ** SQLITE_OK returned. If no hot-journal file is present, *pExists is
43930 ** set to 0 and SQLITE_OK returned. If an IO error occurs while trying
43931 ** to determine whether or not a hot-journal file exists, the IO error
43932 ** code is returned and the value of *pExists is undefined.
43933 */
43934 static int hasHotJournal(Pager *pPager, int *pExists){
43935   sqlite3_vfs * const pVfs = pPager->pVfs;
43936   int rc = SQLITE_OK;           /* Return code */
43937   int exists = 1;               /* True if a journal file is present */
43938   int jrnlOpen = !!isOpen(pPager->jfd);
43939 
43940   assert( pPager->useJournal );
43941   assert( isOpen(pPager->fd) );
43942   assert( pPager->eState==PAGER_OPEN );
43943 
43944   assert( jrnlOpen==0 || ( sqlite3OsDeviceCharacteristics(pPager->jfd) &
43945     SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
43946   ));
43947 
43948   *pExists = 0;
43949   if( !jrnlOpen ){
43950     rc = sqlite3OsAccess(pVfs, pPager->zJournal, SQLITE_ACCESS_EXISTS, &exists);
43951   }
43952   if( rc==SQLITE_OK && exists ){
43953     int locked = 0;             /* True if some process holds a RESERVED lock */
43954 
43955     /* Race condition here:  Another process might have been holding the
43956     ** the RESERVED lock and have a journal open at the sqlite3OsAccess() 
43957     ** call above, but then delete the journal and drop the lock before
43958     ** we get to the following sqlite3OsCheckReservedLock() call.  If that
43959     ** is the case, this routine might think there is a hot journal when
43960     ** in fact there is none.  This results in a false-positive which will
43961     ** be dealt with by the playback routine.  Ticket #3883.
43962     */
43963     rc = sqlite3OsCheckReservedLock(pPager->fd, &locked);
43964     if( rc==SQLITE_OK && !locked ){
43965       Pgno nPage;                 /* Number of pages in database file */
43966 
43967       /* Check the size of the database file. If it consists of 0 pages,
43968       ** then delete the journal file. See the header comment above for 
43969       ** the reasoning here.  Delete the obsolete journal file under
43970       ** a RESERVED lock to avoid race conditions and to avoid violating
43971       ** [H33020].
43972       */
43973       rc = pagerPagecount(pPager, &nPage);
43974       if( rc==SQLITE_OK ){
43975         if( nPage==0 ){
43976           sqlite3BeginBenignMalloc();
43977           if( pagerLockDb(pPager, RESERVED_LOCK)==SQLITE_OK ){
43978             sqlite3OsDelete(pVfs, pPager->zJournal, 0);
43979             if( !pPager->exclusiveMode ) pagerUnlockDb(pPager, SHARED_LOCK);
43980           }
43981           sqlite3EndBenignMalloc();
43982         }else{
43983           /* The journal file exists and no other connection has a reserved
43984           ** or greater lock on the database file. Now check that there is
43985           ** at least one non-zero bytes at the start of the journal file.
43986           ** If there is, then we consider this journal to be hot. If not, 
43987           ** it can be ignored.
43988           */
43989           if( !jrnlOpen ){
43990             int f = SQLITE_OPEN_READONLY|SQLITE_OPEN_MAIN_JOURNAL;
43991             rc = sqlite3OsOpen(pVfs, pPager->zJournal, pPager->jfd, f, &f);
43992           }
43993           if( rc==SQLITE_OK ){
43994             u8 first = 0;
43995             rc = sqlite3OsRead(pPager->jfd, (void *)&first, 1, 0);
43996             if( rc==SQLITE_IOERR_SHORT_READ ){
43997               rc = SQLITE_OK;
43998             }
43999             if( !jrnlOpen ){
44000               sqlite3OsClose(pPager->jfd);
44001             }
44002             *pExists = (first!=0);
44003           }else if( rc==SQLITE_CANTOPEN ){
44004             /* If we cannot open the rollback journal file in order to see if
44005             ** its has a zero header, that might be due to an I/O error, or
44006             ** it might be due to the race condition described above and in
44007             ** ticket #3883.  Either way, assume that the journal is hot.
44008             ** This might be a false positive.  But if it is, then the
44009             ** automatic journal playback and recovery mechanism will deal
44010             ** with it under an EXCLUSIVE lock where we do not need to
44011             ** worry so much with race conditions.
44012             */
44013             *pExists = 1;
44014             rc = SQLITE_OK;
44015           }
44016         }
44017       }
44018     }
44019   }
44020 
44021   return rc;
44022 }
44023 
44024 /*
44025 ** This function is called to obtain a shared lock on the database file.
44026 ** It is illegal to call sqlite3PagerAcquire() until after this function
44027 ** has been successfully called. If a shared-lock is already held when
44028 ** this function is called, it is a no-op.
44029 **
44030 ** The following operations are also performed by this function.
44031 **
44032 **   1) If the pager is currently in PAGER_OPEN state (no lock held
44033 **      on the database file), then an attempt is made to obtain a
44034 **      SHARED lock on the database file. Immediately after obtaining
44035 **      the SHARED lock, the file-system is checked for a hot-journal,
44036 **      which is played back if present. Following any hot-journal 
44037 **      rollback, the contents of the cache are validated by checking
44038 **      the 'change-counter' field of the database file header and
44039 **      discarded if they are found to be invalid.
44040 **
44041 **   2) If the pager is running in exclusive-mode, and there are currently
44042 **      no outstanding references to any pages, and is in the error state,
44043 **      then an attempt is made to clear the error state by discarding
44044 **      the contents of the page cache and rolling back any open journal
44045 **      file.
44046 **
44047 ** If everything is successful, SQLITE_OK is returned. If an IO error 
44048 ** occurs while locking the database, checking for a hot-journal file or 
44049 ** rolling back a journal file, the IO error code is returned.
44050 */
44051 SQLITE_PRIVATE int sqlite3PagerSharedLock(Pager *pPager){
44052   int rc = SQLITE_OK;                /* Return code */
44053 
44054   /* This routine is only called from b-tree and only when there are no
44055   ** outstanding pages. This implies that the pager state should either
44056   ** be OPEN or READER. READER is only possible if the pager is or was in 
44057   ** exclusive access mode.
44058   */
44059   assert( sqlite3PcacheRefCount(pPager->pPCache)==0 );
44060   assert( assert_pager_state(pPager) );
44061   assert( pPager->eState==PAGER_OPEN || pPager->eState==PAGER_READER );
44062   if( NEVER(MEMDB && pPager->errCode) ){ return pPager->errCode; }
44063 
44064   if( !pagerUseWal(pPager) && pPager->eState==PAGER_OPEN ){
44065     int bHotJournal = 1;          /* True if there exists a hot journal-file */
44066 
44067     assert( !MEMDB );
44068 
44069     rc = pager_wait_on_lock(pPager, SHARED_LOCK);
44070     if( rc!=SQLITE_OK ){
44071       assert( pPager->eLock==NO_LOCK || pPager->eLock==UNKNOWN_LOCK );
44072       goto failed;
44073     }
44074 
44075     /* If a journal file exists, and there is no RESERVED lock on the
44076     ** database file, then it either needs to be played back or deleted.
44077     */
44078     if( pPager->eLock<=SHARED_LOCK ){
44079       rc = hasHotJournal(pPager, &bHotJournal);
44080     }
44081     if( rc!=SQLITE_OK ){
44082       goto failed;
44083     }
44084     if( bHotJournal ){
44085       if( pPager->readOnly ){
44086         rc = SQLITE_READONLY_ROLLBACK;
44087         goto failed;
44088       }
44089 
44090       /* Get an EXCLUSIVE lock on the database file. At this point it is
44091       ** important that a RESERVED lock is not obtained on the way to the
44092       ** EXCLUSIVE lock. If it were, another process might open the
44093       ** database file, detect the RESERVED lock, and conclude that the
44094       ** database is safe to read while this process is still rolling the 
44095       ** hot-journal back.
44096       ** 
44097       ** Because the intermediate RESERVED lock is not requested, any
44098       ** other process attempting to access the database file will get to 
44099       ** this point in the code and fail to obtain its own EXCLUSIVE lock 
44100       ** on the database file.
44101       **
44102       ** Unless the pager is in locking_mode=exclusive mode, the lock is
44103       ** downgraded to SHARED_LOCK before this function returns.
44104       */
44105       rc = pagerLockDb(pPager, EXCLUSIVE_LOCK);
44106       if( rc!=SQLITE_OK ){
44107         goto failed;
44108       }
44109  
44110       /* If it is not already open and the file exists on disk, open the 
44111       ** journal for read/write access. Write access is required because 
44112       ** in exclusive-access mode the file descriptor will be kept open 
44113       ** and possibly used for a transaction later on. Also, write-access 
44114       ** is usually required to finalize the journal in journal_mode=persist 
44115       ** mode (and also for journal_mode=truncate on some systems).
44116       **
44117       ** If the journal does not exist, it usually means that some 
44118       ** other connection managed to get in and roll it back before 
44119       ** this connection obtained the exclusive lock above. Or, it 
44120       ** may mean that the pager was in the error-state when this
44121       ** function was called and the journal file does not exist.
44122       */
44123       if( !isOpen(pPager->jfd) ){
44124         sqlite3_vfs * const pVfs = pPager->pVfs;
44125         int bExists;              /* True if journal file exists */
44126         rc = sqlite3OsAccess(
44127             pVfs, pPager->zJournal, SQLITE_ACCESS_EXISTS, &bExists);
44128         if( rc==SQLITE_OK && bExists ){
44129           int fout = 0;
44130           int f = SQLITE_OPEN_READWRITE|SQLITE_OPEN_MAIN_JOURNAL;
44131           assert( !pPager->tempFile );
44132           rc = sqlite3OsOpen(pVfs, pPager->zJournal, pPager->jfd, f, &fout);
44133           assert( rc!=SQLITE_OK || isOpen(pPager->jfd) );
44134           if( rc==SQLITE_OK && fout&SQLITE_OPEN_READONLY ){
44135             rc = SQLITE_CANTOPEN_BKPT;
44136             sqlite3OsClose(pPager->jfd);
44137           }
44138         }
44139       }
44140  
44141       /* Playback and delete the journal.  Drop the database write
44142       ** lock and reacquire the read lock. Purge the cache before
44143       ** playing back the hot-journal so that we don't end up with
44144       ** an inconsistent cache.  Sync the hot journal before playing
44145       ** it back since the process that crashed and left the hot journal
44146       ** probably did not sync it and we are required to always sync
44147       ** the journal before playing it back.
44148       */
44149       if( isOpen(pPager->jfd) ){
44150         assert( rc==SQLITE_OK );
44151         rc = pagerSyncHotJournal(pPager);
44152         if( rc==SQLITE_OK ){
44153           rc = pager_playback(pPager, 1);
44154           pPager->eState = PAGER_OPEN;
44155         }
44156       }else if( !pPager->exclusiveMode ){
44157         pagerUnlockDb(pPager, SHARED_LOCK);
44158       }
44159 
44160       if( rc!=SQLITE_OK ){
44161         /* This branch is taken if an error occurs while trying to open
44162         ** or roll back a hot-journal while holding an EXCLUSIVE lock. The
44163         ** pager_unlock() routine will be called before returning to unlock
44164         ** the file. If the unlock attempt fails, then Pager.eLock must be
44165         ** set to UNKNOWN_LOCK (see the comment above the #define for 
44166         ** UNKNOWN_LOCK above for an explanation). 
44167         **
44168         ** In order to get pager_unlock() to do this, set Pager.eState to
44169         ** PAGER_ERROR now. This is not actually counted as a transition
44170         ** to ERROR state in the state diagram at the top of this file,
44171         ** since we know that the same call to pager_unlock() will very
44172         ** shortly transition the pager object to the OPEN state. Calling
44173         ** assert_pager_state() would fail now, as it should not be possible
44174         ** to be in ERROR state when there are zero outstanding page 
44175         ** references.
44176         */
44177         pager_error(pPager, rc);
44178         goto failed;
44179       }
44180 
44181       assert( pPager->eState==PAGER_OPEN );
44182       assert( (pPager->eLock==SHARED_LOCK)
44183            || (pPager->exclusiveMode && pPager->eLock>SHARED_LOCK)
44184       );
44185     }
44186 
44187     if( !pPager->tempFile && (
44188         pPager->pBackup 
44189      || sqlite3PcachePagecount(pPager->pPCache)>0 
44190      || USEFETCH(pPager)
44191     )){
44192       /* The shared-lock has just been acquired on the database file
44193       ** and there are already pages in the cache (from a previous
44194       ** read or write transaction).  Check to see if the database
44195       ** has been modified.  If the database has changed, flush the
44196       ** cache.
44197       **
44198       ** Database changes is detected by looking at 15 bytes beginning
44199       ** at offset 24 into the file.  The first 4 of these 16 bytes are
44200       ** a 32-bit counter that is incremented with each change.  The
44201       ** other bytes change randomly with each file change when
44202       ** a codec is in use.
44203       ** 
44204       ** There is a vanishingly small chance that a change will not be 
44205       ** detected.  The chance of an undetected change is so small that
44206       ** it can be neglected.
44207       */
44208       Pgno nPage = 0;
44209       char dbFileVers[sizeof(pPager->dbFileVers)];
44210 
44211       rc = pagerPagecount(pPager, &nPage);
44212       if( rc ) goto failed;
44213 
44214       if( nPage>0 ){
44215         IOTRACE(("CKVERS %p %d\n", pPager, sizeof(dbFileVers)));
44216         rc = sqlite3OsRead(pPager->fd, &dbFileVers, sizeof(dbFileVers), 24);
44217         if( rc!=SQLITE_OK && rc!=SQLITE_IOERR_SHORT_READ ){
44218           goto failed;
44219         }
44220       }else{
44221         memset(dbFileVers, 0, sizeof(dbFileVers));
44222       }
44223 
44224       if( memcmp(pPager->dbFileVers, dbFileVers, sizeof(dbFileVers))!=0 ){
44225         pager_reset(pPager);
44226 
44227         /* Unmap the database file. It is possible that external processes
44228         ** may have truncated the database file and then extended it back
44229         ** to its original size while this process was not holding a lock.
44230         ** In this case there may exist a Pager.pMap mapping that appears
44231         ** to be the right size but is not actually valid. Avoid this
44232         ** possibility by unmapping the db here. */
44233         if( USEFETCH(pPager) ){
44234           sqlite3OsUnfetch(pPager->fd, 0, 0);
44235         }
44236       }
44237     }
44238 
44239     /* If there is a WAL file in the file-system, open this database in WAL
44240     ** mode. Otherwise, the following function call is a no-op.
44241     */
44242     rc = pagerOpenWalIfPresent(pPager);
44243 #ifndef SQLITE_OMIT_WAL
44244     assert( pPager->pWal==0 || rc==SQLITE_OK );
44245 #endif
44246   }
44247 
44248   if( pagerUseWal(pPager) ){
44249     assert( rc==SQLITE_OK );
44250     rc = pagerBeginReadTransaction(pPager);
44251   }
44252 
44253   if( pPager->eState==PAGER_OPEN && rc==SQLITE_OK ){
44254     rc = pagerPagecount(pPager, &pPager->dbSize);
44255   }
44256 
44257  failed:
44258   if( rc!=SQLITE_OK ){
44259     assert( !MEMDB );
44260     pager_unlock(pPager);
44261     assert( pPager->eState==PAGER_OPEN );
44262   }else{
44263     pPager->eState = PAGER_READER;
44264   }
44265   return rc;
44266 }
44267 
44268 /*
44269 ** If the reference count has reached zero, rollback any active
44270 ** transaction and unlock the pager.
44271 **
44272 ** Except, in locking_mode=EXCLUSIVE when there is nothing to in
44273 ** the rollback journal, the unlock is not performed and there is
44274 ** nothing to rollback, so this routine is a no-op.
44275 */ 
44276 static void pagerUnlockIfUnused(Pager *pPager){
44277   if( pPager->nMmapOut==0 && (sqlite3PcacheRefCount(pPager->pPCache)==0) ){
44278     pagerUnlockAndRollback(pPager);
44279   }
44280 }
44281 
44282 /*
44283 ** Acquire a reference to page number pgno in pager pPager (a page
44284 ** reference has type DbPage*). If the requested reference is 
44285 ** successfully obtained, it is copied to *ppPage and SQLITE_OK returned.
44286 **
44287 ** If the requested page is already in the cache, it is returned. 
44288 ** Otherwise, a new page object is allocated and populated with data
44289 ** read from the database file. In some cases, the pcache module may
44290 ** choose not to allocate a new page object and may reuse an existing
44291 ** object with no outstanding references.
44292 **
44293 ** The extra data appended to a page is always initialized to zeros the 
44294 ** first time a page is loaded into memory. If the page requested is 
44295 ** already in the cache when this function is called, then the extra
44296 ** data is left as it was when the page object was last used.
44297 **
44298 ** If the database image is smaller than the requested page or if a 
44299 ** non-zero value is passed as the noContent parameter and the 
44300 ** requested page is not already stored in the cache, then no 
44301 ** actual disk read occurs. In this case the memory image of the 
44302 ** page is initialized to all zeros. 
44303 **
44304 ** If noContent is true, it means that we do not care about the contents
44305 ** of the page. This occurs in two scenarios:
44306 **
44307 **   a) When reading a free-list leaf page from the database, and
44308 **
44309 **   b) When a savepoint is being rolled back and we need to load
44310 **      a new page into the cache to be filled with the data read
44311 **      from the savepoint journal.
44312 **
44313 ** If noContent is true, then the data returned is zeroed instead of
44314 ** being read from the database. Additionally, the bits corresponding
44315 ** to pgno in Pager.pInJournal (bitvec of pages already written to the
44316 ** journal file) and the PagerSavepoint.pInSavepoint bitvecs of any open
44317 ** savepoints are set. This means if the page is made writable at any
44318 ** point in the future, using a call to sqlite3PagerWrite(), its contents
44319 ** will not be journaled. This saves IO.
44320 **
44321 ** The acquisition might fail for several reasons.  In all cases,
44322 ** an appropriate error code is returned and *ppPage is set to NULL.
44323 **
44324 ** See also sqlite3PagerLookup().  Both this routine and Lookup() attempt
44325 ** to find a page in the in-memory cache first.  If the page is not already
44326 ** in memory, this routine goes to disk to read it in whereas Lookup()
44327 ** just returns 0.  This routine acquires a read-lock the first time it
44328 ** has to go to disk, and could also playback an old journal if necessary.
44329 ** Since Lookup() never goes to disk, it never has to deal with locks
44330 ** or journal files.
44331 */
44332 SQLITE_PRIVATE int sqlite3PagerAcquire(
44333   Pager *pPager,      /* The pager open on the database file */
44334   Pgno pgno,          /* Page number to fetch */
44335   DbPage **ppPage,    /* Write a pointer to the page here */
44336   int flags           /* PAGER_GET_XXX flags */
44337 ){
44338   int rc = SQLITE_OK;
44339   PgHdr *pPg = 0;
44340   u32 iFrame = 0;                 /* Frame to read from WAL file */
44341   const int noContent = (flags & PAGER_GET_NOCONTENT);
44342 
44343   /* It is acceptable to use a read-only (mmap) page for any page except
44344   ** page 1 if there is no write-transaction open or the ACQUIRE_READONLY
44345   ** flag was specified by the caller. And so long as the db is not a 
44346   ** temporary or in-memory database.  */
44347   const int bMmapOk = (pgno!=1 && USEFETCH(pPager)
44348    && (pPager->eState==PAGER_READER || (flags & PAGER_GET_READONLY))
44349 #ifdef SQLITE_HAS_CODEC
44350    && pPager->xCodec==0
44351 #endif
44352   );
44353 
44354   assert( pPager->eState>=PAGER_READER );
44355   assert( assert_pager_state(pPager) );
44356   assert( noContent==0 || bMmapOk==0 );
44357 
44358   if( pgno==0 ){
44359     return SQLITE_CORRUPT_BKPT;
44360   }
44361 
44362   /* If the pager is in the error state, return an error immediately. 
44363   ** Otherwise, request the page from the PCache layer. */
44364   if( pPager->errCode!=SQLITE_OK ){
44365     rc = pPager->errCode;
44366   }else{
44367 
44368     if( bMmapOk && pagerUseWal(pPager) ){
44369       rc = sqlite3WalFindFrame(pPager->pWal, pgno, &iFrame);
44370       if( rc!=SQLITE_OK ) goto pager_acquire_err;
44371     }
44372 
44373     if( iFrame==0 && bMmapOk ){
44374       void *pData = 0;
44375 
44376       rc = sqlite3OsFetch(pPager->fd, 
44377           (i64)(pgno-1) * pPager->pageSize, pPager->pageSize, &pData
44378       );
44379 
44380       if( rc==SQLITE_OK && pData ){
44381         if( pPager->eState>PAGER_READER ){
44382           (void)sqlite3PcacheFetch(pPager->pPCache, pgno, 0, &pPg);
44383         }
44384         if( pPg==0 ){
44385           rc = pagerAcquireMapPage(pPager, pgno, pData, &pPg);
44386         }else{
44387           sqlite3OsUnfetch(pPager->fd, (i64)(pgno-1)*pPager->pageSize, pData);
44388         }
44389         if( pPg ){
44390           assert( rc==SQLITE_OK );
44391           *ppPage = pPg;
44392           return SQLITE_OK;
44393         }
44394       }
44395       if( rc!=SQLITE_OK ){
44396         goto pager_acquire_err;
44397       }
44398     }
44399 
44400     rc = sqlite3PcacheFetch(pPager->pPCache, pgno, 1, ppPage);
44401   }
44402 
44403   if( rc!=SQLITE_OK ){
44404     /* Either the call to sqlite3PcacheFetch() returned an error or the
44405     ** pager was already in the error-state when this function was called.
44406     ** Set pPg to 0 and jump to the exception handler.  */
44407     pPg = 0;
44408     goto pager_acquire_err;
44409   }
44410   assert( (*ppPage)->pgno==pgno );
44411   assert( (*ppPage)->pPager==pPager || (*ppPage)->pPager==0 );
44412 
44413   if( (*ppPage)->pPager && !noContent ){
44414     /* In this case the pcache already contains an initialized copy of
44415     ** the page. Return without further ado.  */
44416     assert( pgno<=PAGER_MAX_PGNO && pgno!=PAGER_MJ_PGNO(pPager) );
44417     pPager->aStat[PAGER_STAT_HIT]++;
44418     return SQLITE_OK;
44419 
44420   }else{
44421     /* The pager cache has created a new page. Its content needs to 
44422     ** be initialized.  */
44423 
44424     pPg = *ppPage;
44425     pPg->pPager = pPager;
44426 
44427     /* The maximum page number is 2^31. Return SQLITE_CORRUPT if a page
44428     ** number greater than this, or the unused locking-page, is requested. */
44429     if( pgno>PAGER_MAX_PGNO || pgno==PAGER_MJ_PGNO(pPager) ){
44430       rc = SQLITE_CORRUPT_BKPT;
44431       goto pager_acquire_err;
44432     }
44433 
44434     if( MEMDB || pPager->dbSize<pgno || noContent || !isOpen(pPager->fd) ){
44435       if( pgno>pPager->mxPgno ){
44436         rc = SQLITE_FULL;
44437         goto pager_acquire_err;
44438       }
44439       if( noContent ){
44440         /* Failure to set the bits in the InJournal bit-vectors is benign.
44441         ** It merely means that we might do some extra work to journal a 
44442         ** page that does not need to be journaled.  Nevertheless, be sure 
44443         ** to test the case where a malloc error occurs while trying to set 
44444         ** a bit in a bit vector.
44445         */
44446         sqlite3BeginBenignMalloc();
44447         if( pgno<=pPager->dbOrigSize ){
44448           TESTONLY( rc = ) sqlite3BitvecSet(pPager->pInJournal, pgno);
44449           testcase( rc==SQLITE_NOMEM );
44450         }
44451         TESTONLY( rc = ) addToSavepointBitvecs(pPager, pgno);
44452         testcase( rc==SQLITE_NOMEM );
44453         sqlite3EndBenignMalloc();
44454       }
44455       memset(pPg->pData, 0, pPager->pageSize);
44456       IOTRACE(("ZERO %p %d\n", pPager, pgno));
44457     }else{
44458       if( pagerUseWal(pPager) && bMmapOk==0 ){
44459         rc = sqlite3WalFindFrame(pPager->pWal, pgno, &iFrame);
44460         if( rc!=SQLITE_OK ) goto pager_acquire_err;
44461       }
44462       assert( pPg->pPager==pPager );
44463       pPager->aStat[PAGER_STAT_MISS]++;
44464       rc = readDbPage(pPg, iFrame);
44465       if( rc!=SQLITE_OK ){
44466         goto pager_acquire_err;
44467       }
44468     }
44469     pager_set_pagehash(pPg);
44470   }
44471 
44472   return SQLITE_OK;
44473 
44474 pager_acquire_err:
44475   assert( rc!=SQLITE_OK );
44476   if( pPg ){
44477     sqlite3PcacheDrop(pPg);
44478   }
44479   pagerUnlockIfUnused(pPager);
44480 
44481   *ppPage = 0;
44482   return rc;
44483 }
44484 
44485 /*
44486 ** Acquire a page if it is already in the in-memory cache.  Do
44487 ** not read the page from disk.  Return a pointer to the page,
44488 ** or 0 if the page is not in cache. 
44489 **
44490 ** See also sqlite3PagerGet().  The difference between this routine
44491 ** and sqlite3PagerGet() is that _get() will go to the disk and read
44492 ** in the page if the page is not already in cache.  This routine
44493 ** returns NULL if the page is not in cache or if a disk I/O error 
44494 ** has ever happened.
44495 */
44496 SQLITE_PRIVATE DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno){
44497   PgHdr *pPg = 0;
44498   assert( pPager!=0 );
44499   assert( pgno!=0 );
44500   assert( pPager->pPCache!=0 );
44501   assert( pPager->eState>=PAGER_READER && pPager->eState!=PAGER_ERROR );
44502   sqlite3PcacheFetch(pPager->pPCache, pgno, 0, &pPg);
44503   return pPg;
44504 }
44505 
44506 /*
44507 ** Release a page reference.
44508 **
44509 ** If the number of references to the page drop to zero, then the
44510 ** page is added to the LRU list.  When all references to all pages
44511 ** are released, a rollback occurs and the lock on the database is
44512 ** removed.
44513 */
44514 SQLITE_PRIVATE void sqlite3PagerUnref(DbPage *pPg){
44515   if( pPg ){
44516     Pager *pPager = pPg->pPager;
44517     if( pPg->flags & PGHDR_MMAP ){
44518       pagerReleaseMapPage(pPg);
44519     }else{
44520       sqlite3PcacheRelease(pPg);
44521     }
44522     pagerUnlockIfUnused(pPager);
44523   }
44524 }
44525 
44526 /*
44527 ** This function is called at the start of every write transaction.
44528 ** There must already be a RESERVED or EXCLUSIVE lock on the database 
44529 ** file when this routine is called.
44530 **
44531 ** Open the journal file for pager pPager and write a journal header
44532 ** to the start of it. If there are active savepoints, open the sub-journal
44533 ** as well. This function is only used when the journal file is being 
44534 ** opened to write a rollback log for a transaction. It is not used 
44535 ** when opening a hot journal file to roll it back.
44536 **
44537 ** If the journal file is already open (as it may be in exclusive mode),
44538 ** then this function just writes a journal header to the start of the
44539 ** already open file. 
44540 **
44541 ** Whether or not the journal file is opened by this function, the
44542 ** Pager.pInJournal bitvec structure is allocated.
44543 **
44544 ** Return SQLITE_OK if everything is successful. Otherwise, return 
44545 ** SQLITE_NOMEM if the attempt to allocate Pager.pInJournal fails, or 
44546 ** an IO error code if opening or writing the journal file fails.
44547 */
44548 static int pager_open_journal(Pager *pPager){
44549   int rc = SQLITE_OK;                        /* Return code */
44550   sqlite3_vfs * const pVfs = pPager->pVfs;   /* Local cache of vfs pointer */
44551 
44552   assert( pPager->eState==PAGER_WRITER_LOCKED );
44553   assert( assert_pager_state(pPager) );
44554   assert( pPager->pInJournal==0 );
44555   
44556   /* If already in the error state, this function is a no-op.  But on
44557   ** the other hand, this routine is never called if we are already in
44558   ** an error state. */
44559   if( NEVER(pPager->errCode) ) return pPager->errCode;
44560 
44561   if( !pagerUseWal(pPager) && pPager->journalMode!=PAGER_JOURNALMODE_OFF ){
44562     pPager->pInJournal = sqlite3BitvecCreate(pPager->dbSize);
44563     if( pPager->pInJournal==0 ){
44564       return SQLITE_NOMEM;
44565     }
44566   
44567     /* Open the journal file if it is not already open. */
44568     if( !isOpen(pPager->jfd) ){
44569       if( pPager->journalMode==PAGER_JOURNALMODE_MEMORY ){
44570         sqlite3MemJournalOpen(pPager->jfd);
44571       }else{
44572         const int flags =                   /* VFS flags to open journal file */
44573           SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE|
44574           (pPager->tempFile ? 
44575             (SQLITE_OPEN_DELETEONCLOSE|SQLITE_OPEN_TEMP_JOURNAL):
44576             (SQLITE_OPEN_MAIN_JOURNAL)
44577           );
44578   #ifdef SQLITE_ENABLE_ATOMIC_WRITE
44579         rc = sqlite3JournalOpen(
44580             pVfs, pPager->zJournal, pPager->jfd, flags, jrnlBufferSize(pPager)
44581         );
44582   #else
44583         rc = sqlite3OsOpen(pVfs, pPager->zJournal, pPager->jfd, flags, 0);
44584   #endif
44585       }
44586       assert( rc!=SQLITE_OK || isOpen(pPager->jfd) );
44587     }
44588   
44589   
44590     /* Write the first journal header to the journal file and open 
44591     ** the sub-journal if necessary.
44592     */
44593     if( rc==SQLITE_OK ){
44594       /* TODO: Check if all of these are really required. */
44595       pPager->nRec = 0;
44596       pPager->journalOff = 0;
44597       pPager->setMaster = 0;
44598       pPager->journalHdr = 0;
44599       rc = writeJournalHdr(pPager);
44600     }
44601   }
44602 
44603   if( rc!=SQLITE_OK ){
44604     sqlite3BitvecDestroy(pPager->pInJournal);
44605     pPager->pInJournal = 0;
44606   }else{
44607     assert( pPager->eState==PAGER_WRITER_LOCKED );
44608     pPager->eState = PAGER_WRITER_CACHEMOD;
44609   }
44610 
44611   return rc;
44612 }
44613 
44614 /*
44615 ** Begin a write-transaction on the specified pager object. If a 
44616 ** write-transaction has already been opened, this function is a no-op.
44617 **
44618 ** If the exFlag argument is false, then acquire at least a RESERVED
44619 ** lock on the database file. If exFlag is true, then acquire at least
44620 ** an EXCLUSIVE lock. If such a lock is already held, no locking 
44621 ** functions need be called.
44622 **
44623 ** If the subjInMemory argument is non-zero, then any sub-journal opened
44624 ** within this transaction will be opened as an in-memory file. This
44625 ** has no effect if the sub-journal is already opened (as it may be when
44626 ** running in exclusive mode) or if the transaction does not require a
44627 ** sub-journal. If the subjInMemory argument is zero, then any required
44628 ** sub-journal is implemented in-memory if pPager is an in-memory database, 
44629 ** or using a temporary file otherwise.
44630 */
44631 SQLITE_PRIVATE int sqlite3PagerBegin(Pager *pPager, int exFlag, int subjInMemory){
44632   int rc = SQLITE_OK;
44633 
44634   if( pPager->errCode ) return pPager->errCode;
44635   assert( pPager->eState>=PAGER_READER && pPager->eState<PAGER_ERROR );
44636   pPager->subjInMemory = (u8)subjInMemory;
44637 
44638   if( ALWAYS(pPager->eState==PAGER_READER) ){
44639     assert( pPager->pInJournal==0 );
44640 
44641     if( pagerUseWal(pPager) ){
44642       /* If the pager is configured to use locking_mode=exclusive, and an
44643       ** exclusive lock on the database is not already held, obtain it now.
44644       */
44645       if( pPager->exclusiveMode && sqlite3WalExclusiveMode(pPager->pWal, -1) ){
44646         rc = pagerLockDb(pPager, EXCLUSIVE_LOCK);
44647         if( rc!=SQLITE_OK ){
44648           return rc;
44649         }
44650         sqlite3WalExclusiveMode(pPager->pWal, 1);
44651       }
44652 
44653       /* Grab the write lock on the log file. If successful, upgrade to
44654       ** PAGER_RESERVED state. Otherwise, return an error code to the caller.
44655       ** The busy-handler is not invoked if another connection already
44656       ** holds the write-lock. If possible, the upper layer will call it.
44657       */
44658       rc = sqlite3WalBeginWriteTransaction(pPager->pWal);
44659     }else{
44660       /* Obtain a RESERVED lock on the database file. If the exFlag parameter
44661       ** is true, then immediately upgrade this to an EXCLUSIVE lock. The
44662       ** busy-handler callback can be used when upgrading to the EXCLUSIVE
44663       ** lock, but not when obtaining the RESERVED lock.
44664       */
44665       rc = pagerLockDb(pPager, RESERVED_LOCK);
44666       if( rc==SQLITE_OK && exFlag ){
44667         rc = pager_wait_on_lock(pPager, EXCLUSIVE_LOCK);
44668       }
44669     }
44670 
44671     if( rc==SQLITE_OK ){
44672       /* Change to WRITER_LOCKED state.
44673       **
44674       ** WAL mode sets Pager.eState to PAGER_WRITER_LOCKED or CACHEMOD
44675       ** when it has an open transaction, but never to DBMOD or FINISHED.
44676       ** This is because in those states the code to roll back savepoint 
44677       ** transactions may copy data from the sub-journal into the database 
44678       ** file as well as into the page cache. Which would be incorrect in 
44679       ** WAL mode.
44680       */
44681       pPager->eState = PAGER_WRITER_LOCKED;
44682       pPager->dbHintSize = pPager->dbSize;
44683       pPager->dbFileSize = pPager->dbSize;
44684       pPager->dbOrigSize = pPager->dbSize;
44685       pPager->journalOff = 0;
44686     }
44687 
44688     assert( rc==SQLITE_OK || pPager->eState==PAGER_READER );
44689     assert( rc!=SQLITE_OK || pPager->eState==PAGER_WRITER_LOCKED );
44690     assert( assert_pager_state(pPager) );
44691   }
44692 
44693   PAGERTRACE(("TRANSACTION %d\n", PAGERID(pPager)));
44694   return rc;
44695 }
44696 
44697 /*
44698 ** Mark a single data page as writeable. The page is written into the 
44699 ** main journal or sub-journal as required. If the page is written into
44700 ** one of the journals, the corresponding bit is set in the 
44701 ** Pager.pInJournal bitvec and the PagerSavepoint.pInSavepoint bitvecs
44702 ** of any open savepoints as appropriate.
44703 */
44704 static int pager_write(PgHdr *pPg){
44705   void *pData = pPg->pData;
44706   Pager *pPager = pPg->pPager;
44707   int rc = SQLITE_OK;
44708 
44709   /* This routine is not called unless a write-transaction has already 
44710   ** been started. The journal file may or may not be open at this point.
44711   ** It is never called in the ERROR state.
44712   */
44713   assert( pPager->eState==PAGER_WRITER_LOCKED
44714        || pPager->eState==PAGER_WRITER_CACHEMOD
44715        || pPager->eState==PAGER_WRITER_DBMOD
44716   );
44717   assert( assert_pager_state(pPager) );
44718 
44719   /* If an error has been previously detected, report the same error
44720   ** again. This should not happen, but the check provides robustness. */
44721   if( NEVER(pPager->errCode) )  return pPager->errCode;
44722 
44723   /* Higher-level routines never call this function if database is not
44724   ** writable.  But check anyway, just for robustness. */
44725   if( NEVER(pPager->readOnly) ) return SQLITE_PERM;
44726 
44727   CHECK_PAGE(pPg);
44728 
44729   /* The journal file needs to be opened. Higher level routines have already
44730   ** obtained the necessary locks to begin the write-transaction, but the
44731   ** rollback journal might not yet be open. Open it now if this is the case.
44732   **
44733   ** This is done before calling sqlite3PcacheMakeDirty() on the page. 
44734   ** Otherwise, if it were done after calling sqlite3PcacheMakeDirty(), then
44735   ** an error might occur and the pager would end up in WRITER_LOCKED state
44736   ** with pages marked as dirty in the cache.
44737   */
44738   if( pPager->eState==PAGER_WRITER_LOCKED ){
44739     rc = pager_open_journal(pPager);
44740     if( rc!=SQLITE_OK ) return rc;
44741   }
44742   assert( pPager->eState>=PAGER_WRITER_CACHEMOD );
44743   assert( assert_pager_state(pPager) );
44744 
44745   /* Mark the page as dirty.  If the page has already been written
44746   ** to the journal then we can return right away.
44747   */
44748   sqlite3PcacheMakeDirty(pPg);
44749   if( pageInJournal(pPg) && !subjRequiresPage(pPg) ){
44750     assert( !pagerUseWal(pPager) );
44751   }else{
44752   
44753     /* The transaction journal now exists and we have a RESERVED or an
44754     ** EXCLUSIVE lock on the main database file.  Write the current page to
44755     ** the transaction journal if it is not there already.
44756     */
44757     if( !pageInJournal(pPg) && !pagerUseWal(pPager) ){
44758       assert( pagerUseWal(pPager)==0 );
44759       if( pPg->pgno<=pPager->dbOrigSize && isOpen(pPager->jfd) ){
44760         u32 cksum;
44761         char *pData2;
44762         i64 iOff = pPager->journalOff;
44763 
44764         /* We should never write to the journal file the page that
44765         ** contains the database locks.  The following assert verifies
44766         ** that we do not. */
44767         assert( pPg->pgno!=PAGER_MJ_PGNO(pPager) );
44768 
44769         assert( pPager->journalHdr<=pPager->journalOff );
44770         CODEC2(pPager, pData, pPg->pgno, 7, return SQLITE_NOMEM, pData2);
44771         cksum = pager_cksum(pPager, (u8*)pData2);
44772 
44773         /* Even if an IO or diskfull error occurs while journalling the
44774         ** page in the block above, set the need-sync flag for the page.
44775         ** Otherwise, when the transaction is rolled back, the logic in
44776         ** playback_one_page() will think that the page needs to be restored
44777         ** in the database file. And if an IO error occurs while doing so,
44778         ** then corruption may follow.
44779         */
44780         pPg->flags |= PGHDR_NEED_SYNC;
44781 
44782         rc = write32bits(pPager->jfd, iOff, pPg->pgno);
44783         if( rc!=SQLITE_OK ) return rc;
44784         rc = sqlite3OsWrite(pPager->jfd, pData2, pPager->pageSize, iOff+4);
44785         if( rc!=SQLITE_OK ) return rc;
44786         rc = write32bits(pPager->jfd, iOff+pPager->pageSize+4, cksum);
44787         if( rc!=SQLITE_OK ) return rc;
44788 
44789         IOTRACE(("JOUT %p %d %lld %d\n", pPager, pPg->pgno, 
44790                  pPager->journalOff, pPager->pageSize));
44791         PAGER_INCR(sqlite3_pager_writej_count);
44792         PAGERTRACE(("JOURNAL %d page %d needSync=%d hash(%08x)\n",
44793              PAGERID(pPager), pPg->pgno, 
44794              ((pPg->flags&PGHDR_NEED_SYNC)?1:0), pager_pagehash(pPg)));
44795 
44796         pPager->journalOff += 8 + pPager->pageSize;
44797         pPager->nRec++;
44798         assert( pPager->pInJournal!=0 );
44799         rc = sqlite3BitvecSet(pPager->pInJournal, pPg->pgno);
44800         testcase( rc==SQLITE_NOMEM );
44801         assert( rc==SQLITE_OK || rc==SQLITE_NOMEM );
44802         rc |= addToSavepointBitvecs(pPager, pPg->pgno);
44803         if( rc!=SQLITE_OK ){
44804           assert( rc==SQLITE_NOMEM );
44805           return rc;
44806         }
44807       }else{
44808         if( pPager->eState!=PAGER_WRITER_DBMOD ){
44809           pPg->flags |= PGHDR_NEED_SYNC;
44810         }
44811         PAGERTRACE(("APPEND %d page %d needSync=%d\n",
44812                 PAGERID(pPager), pPg->pgno,
44813                ((pPg->flags&PGHDR_NEED_SYNC)?1:0)));
44814       }
44815     }
44816   
44817     /* If the statement journal is open and the page is not in it,
44818     ** then write the current page to the statement journal.  Note that
44819     ** the statement journal format differs from the standard journal format
44820     ** in that it omits the checksums and the header.
44821     */
44822     if( subjRequiresPage(pPg) ){
44823       rc = subjournalPage(pPg);
44824     }
44825   }
44826 
44827   /* Update the database size and return.
44828   */
44829   if( pPager->dbSize<pPg->pgno ){
44830     pPager->dbSize = pPg->pgno;
44831   }
44832   return rc;
44833 }
44834 
44835 /*
44836 ** Mark a data page as writeable. This routine must be called before 
44837 ** making changes to a page. The caller must check the return value 
44838 ** of this function and be careful not to change any page data unless 
44839 ** this routine returns SQLITE_OK.
44840 **
44841 ** The difference between this function and pager_write() is that this
44842 ** function also deals with the special case where 2 or more pages
44843 ** fit on a single disk sector. In this case all co-resident pages
44844 ** must have been written to the journal file before returning.
44845 **
44846 ** If an error occurs, SQLITE_NOMEM or an IO error code is returned
44847 ** as appropriate. Otherwise, SQLITE_OK.
44848 */
44849 SQLITE_PRIVATE int sqlite3PagerWrite(DbPage *pDbPage){
44850   int rc = SQLITE_OK;
44851 
44852   PgHdr *pPg = pDbPage;
44853   Pager *pPager = pPg->pPager;
44854   Pgno nPagePerSector = (pPager->sectorSize/pPager->pageSize);
44855 
44856   assert( (pPg->flags & PGHDR_MMAP)==0 );
44857   assert( pPager->eState>=PAGER_WRITER_LOCKED );
44858   assert( pPager->eState!=PAGER_ERROR );
44859   assert( assert_pager_state(pPager) );
44860 
44861   if( nPagePerSector>1 ){
44862     Pgno nPageCount;          /* Total number of pages in database file */
44863     Pgno pg1;                 /* First page of the sector pPg is located on. */
44864     int nPage = 0;            /* Number of pages starting at pg1 to journal */
44865     int ii;                   /* Loop counter */
44866     int needSync = 0;         /* True if any page has PGHDR_NEED_SYNC */
44867 
44868     /* Set the doNotSpill NOSYNC bit to 1. This is because we cannot allow
44869     ** a journal header to be written between the pages journaled by
44870     ** this function.
44871     */
44872     assert( !MEMDB );
44873     assert( (pPager->doNotSpill & SPILLFLAG_NOSYNC)==0 );
44874     pPager->doNotSpill |= SPILLFLAG_NOSYNC;
44875 
44876     /* This trick assumes that both the page-size and sector-size are
44877     ** an integer power of 2. It sets variable pg1 to the identifier
44878     ** of the first page of the sector pPg is located on.
44879     */
44880     pg1 = ((pPg->pgno-1) & ~(nPagePerSector-1)) + 1;
44881 
44882     nPageCount = pPager->dbSize;
44883     if( pPg->pgno>nPageCount ){
44884       nPage = (pPg->pgno - pg1)+1;
44885     }else if( (pg1+nPagePerSector-1)>nPageCount ){
44886       nPage = nPageCount+1-pg1;
44887     }else{
44888       nPage = nPagePerSector;
44889     }
44890     assert(nPage>0);
44891     assert(pg1<=pPg->pgno);
44892     assert((pg1+nPage)>pPg->pgno);
44893 
44894     for(ii=0; ii<nPage && rc==SQLITE_OK; ii++){
44895       Pgno pg = pg1+ii;
44896       PgHdr *pPage;
44897       if( pg==pPg->pgno || !sqlite3BitvecTest(pPager->pInJournal, pg) ){
44898         if( pg!=PAGER_MJ_PGNO(pPager) ){
44899           rc = sqlite3PagerGet(pPager, pg, &pPage);
44900           if( rc==SQLITE_OK ){
44901             rc = pager_write(pPage);
44902             if( pPage->flags&PGHDR_NEED_SYNC ){
44903               needSync = 1;
44904             }
44905             sqlite3PagerUnref(pPage);
44906           }
44907         }
44908       }else if( (pPage = pager_lookup(pPager, pg))!=0 ){
44909         if( pPage->flags&PGHDR_NEED_SYNC ){
44910           needSync = 1;
44911         }
44912         sqlite3PagerUnref(pPage);
44913       }
44914     }
44915 
44916     /* If the PGHDR_NEED_SYNC flag is set for any of the nPage pages 
44917     ** starting at pg1, then it needs to be set for all of them. Because
44918     ** writing to any of these nPage pages may damage the others, the
44919     ** journal file must contain sync()ed copies of all of them
44920     ** before any of them can be written out to the database file.
44921     */
44922     if( rc==SQLITE_OK && needSync ){
44923       assert( !MEMDB );
44924       for(ii=0; ii<nPage; ii++){
44925         PgHdr *pPage = pager_lookup(pPager, pg1+ii);
44926         if( pPage ){
44927           pPage->flags |= PGHDR_NEED_SYNC;
44928           sqlite3PagerUnref(pPage);
44929         }
44930       }
44931     }
44932 
44933     assert( (pPager->doNotSpill & SPILLFLAG_NOSYNC)!=0 );
44934     pPager->doNotSpill &= ~SPILLFLAG_NOSYNC;
44935   }else{
44936     rc = pager_write(pDbPage);
44937   }
44938   return rc;
44939 }
44940 
44941 /*
44942 ** Return TRUE if the page given in the argument was previously passed
44943 ** to sqlite3PagerWrite().  In other words, return TRUE if it is ok
44944 ** to change the content of the page.
44945 */
44946 #ifndef NDEBUG
44947 SQLITE_PRIVATE int sqlite3PagerIswriteable(DbPage *pPg){
44948   return pPg->flags&PGHDR_DIRTY;
44949 }
44950 #endif
44951 
44952 /*
44953 ** A call to this routine tells the pager that it is not necessary to
44954 ** write the information on page pPg back to the disk, even though
44955 ** that page might be marked as dirty.  This happens, for example, when
44956 ** the page has been added as a leaf of the freelist and so its
44957 ** content no longer matters.
44958 **
44959 ** The overlying software layer calls this routine when all of the data
44960 ** on the given page is unused. The pager marks the page as clean so
44961 ** that it does not get written to disk.
44962 **
44963 ** Tests show that this optimization can quadruple the speed of large 
44964 ** DELETE operations.
44965 */
44966 SQLITE_PRIVATE void sqlite3PagerDontWrite(PgHdr *pPg){
44967   Pager *pPager = pPg->pPager;
44968   if( (pPg->flags&PGHDR_DIRTY) && pPager->nSavepoint==0 ){
44969     PAGERTRACE(("DONT_WRITE page %d of %d\n", pPg->pgno, PAGERID(pPager)));
44970     IOTRACE(("CLEAN %p %d\n", pPager, pPg->pgno))
44971     pPg->flags |= PGHDR_DONT_WRITE;
44972     pager_set_pagehash(pPg);
44973   }
44974 }
44975 
44976 /*
44977 ** This routine is called to increment the value of the database file 
44978 ** change-counter, stored as a 4-byte big-endian integer starting at 
44979 ** byte offset 24 of the pager file.  The secondary change counter at
44980 ** 92 is also updated, as is the SQLite version number at offset 96.
44981 **
44982 ** But this only happens if the pPager->changeCountDone flag is false.
44983 ** To avoid excess churning of page 1, the update only happens once.
44984 ** See also the pager_write_changecounter() routine that does an 
44985 ** unconditional update of the change counters.
44986 **
44987 ** If the isDirectMode flag is zero, then this is done by calling 
44988 ** sqlite3PagerWrite() on page 1, then modifying the contents of the
44989 ** page data. In this case the file will be updated when the current
44990 ** transaction is committed.
44991 **
44992 ** The isDirectMode flag may only be non-zero if the library was compiled
44993 ** with the SQLITE_ENABLE_ATOMIC_WRITE macro defined. In this case,
44994 ** if isDirect is non-zero, then the database file is updated directly
44995 ** by writing an updated version of page 1 using a call to the 
44996 ** sqlite3OsWrite() function.
44997 */
44998 static int pager_incr_changecounter(Pager *pPager, int isDirectMode){
44999   int rc = SQLITE_OK;
45000 
45001   assert( pPager->eState==PAGER_WRITER_CACHEMOD
45002        || pPager->eState==PAGER_WRITER_DBMOD
45003   );
45004   assert( assert_pager_state(pPager) );
45005 
45006   /* Declare and initialize constant integer 'isDirect'. If the
45007   ** atomic-write optimization is enabled in this build, then isDirect
45008   ** is initialized to the value passed as the isDirectMode parameter
45009   ** to this function. Otherwise, it is always set to zero.
45010   **
45011   ** The idea is that if the atomic-write optimization is not
45012   ** enabled at compile time, the compiler can omit the tests of
45013   ** 'isDirect' below, as well as the block enclosed in the
45014   ** "if( isDirect )" condition.
45015   */
45016 #ifndef SQLITE_ENABLE_ATOMIC_WRITE
45017 # define DIRECT_MODE 0
45018   assert( isDirectMode==0 );
45019   UNUSED_PARAMETER(isDirectMode);
45020 #else
45021 # define DIRECT_MODE isDirectMode
45022 #endif
45023 
45024   if( !pPager->changeCountDone && ALWAYS(pPager->dbSize>0) ){
45025     PgHdr *pPgHdr;                /* Reference to page 1 */
45026 
45027     assert( !pPager->tempFile && isOpen(pPager->fd) );
45028 
45029     /* Open page 1 of the file for writing. */
45030     rc = sqlite3PagerGet(pPager, 1, &pPgHdr);
45031     assert( pPgHdr==0 || rc==SQLITE_OK );
45032 
45033     /* If page one was fetched successfully, and this function is not
45034     ** operating in direct-mode, make page 1 writable.  When not in 
45035     ** direct mode, page 1 is always held in cache and hence the PagerGet()
45036     ** above is always successful - hence the ALWAYS on rc==SQLITE_OK.
45037     */
45038     if( !DIRECT_MODE && ALWAYS(rc==SQLITE_OK) ){
45039       rc = sqlite3PagerWrite(pPgHdr);
45040     }
45041 
45042     if( rc==SQLITE_OK ){
45043       /* Actually do the update of the change counter */
45044       pager_write_changecounter(pPgHdr);
45045 
45046       /* If running in direct mode, write the contents of page 1 to the file. */
45047       if( DIRECT_MODE ){
45048         const void *zBuf;
45049         assert( pPager->dbFileSize>0 );
45050         CODEC2(pPager, pPgHdr->pData, 1, 6, rc=SQLITE_NOMEM, zBuf);
45051         if( rc==SQLITE_OK ){
45052           rc = sqlite3OsWrite(pPager->fd, zBuf, pPager->pageSize, 0);
45053           pPager->aStat[PAGER_STAT_WRITE]++;
45054         }
45055         if( rc==SQLITE_OK ){
45056           /* Update the pager's copy of the change-counter. Otherwise, the
45057           ** next time a read transaction is opened the cache will be
45058           ** flushed (as the change-counter values will not match).  */
45059           const void *pCopy = (const void *)&((const char *)zBuf)[24];
45060           memcpy(&pPager->dbFileVers, pCopy, sizeof(pPager->dbFileVers));
45061           pPager->changeCountDone = 1;
45062         }
45063       }else{
45064         pPager->changeCountDone = 1;
45065       }
45066     }
45067 
45068     /* Release the page reference. */
45069     sqlite3PagerUnref(pPgHdr);
45070   }
45071   return rc;
45072 }
45073 
45074 /*
45075 ** Sync the database file to disk. This is a no-op for in-memory databases
45076 ** or pages with the Pager.noSync flag set.
45077 **
45078 ** If successful, or if called on a pager for which it is a no-op, this
45079 ** function returns SQLITE_OK. Otherwise, an IO error code is returned.
45080 */
45081 SQLITE_PRIVATE int sqlite3PagerSync(Pager *pPager){
45082   int rc = SQLITE_OK;
45083   if( !pPager->noSync ){
45084     assert( !MEMDB );
45085     rc = sqlite3OsSync(pPager->fd, pPager->syncFlags);
45086   }else if( isOpen(pPager->fd) ){
45087     assert( !MEMDB );
45088     rc = sqlite3OsFileControl(pPager->fd, SQLITE_FCNTL_SYNC_OMITTED, 0);
45089     if( rc==SQLITE_NOTFOUND ){
45090       rc = SQLITE_OK;
45091     }
45092   }
45093   return rc;
45094 }
45095 
45096 /*
45097 ** This function may only be called while a write-transaction is active in
45098 ** rollback. If the connection is in WAL mode, this call is a no-op. 
45099 ** Otherwise, if the connection does not already have an EXCLUSIVE lock on 
45100 ** the database file, an attempt is made to obtain one.
45101 **
45102 ** If the EXCLUSIVE lock is already held or the attempt to obtain it is
45103 ** successful, or the connection is in WAL mode, SQLITE_OK is returned.
45104 ** Otherwise, either SQLITE_BUSY or an SQLITE_IOERR_XXX error code is 
45105 ** returned.
45106 */
45107 SQLITE_PRIVATE int sqlite3PagerExclusiveLock(Pager *pPager){
45108   int rc = SQLITE_OK;
45109   assert( pPager->eState==PAGER_WRITER_CACHEMOD 
45110        || pPager->eState==PAGER_WRITER_DBMOD 
45111        || pPager->eState==PAGER_WRITER_LOCKED 
45112   );
45113   assert( assert_pager_state(pPager) );
45114   if( 0==pagerUseWal(pPager) ){
45115     rc = pager_wait_on_lock(pPager, EXCLUSIVE_LOCK);
45116   }
45117   return rc;
45118 }
45119 
45120 /*
45121 ** Sync the database file for the pager pPager. zMaster points to the name
45122 ** of a master journal file that should be written into the individual
45123 ** journal file. zMaster may be NULL, which is interpreted as no master
45124 ** journal (a single database transaction).
45125 **
45126 ** This routine ensures that:
45127 **
45128 **   * The database file change-counter is updated,
45129 **   * the journal is synced (unless the atomic-write optimization is used),
45130 **   * all dirty pages are written to the database file, 
45131 **   * the database file is truncated (if required), and
45132 **   * the database file synced. 
45133 **
45134 ** The only thing that remains to commit the transaction is to finalize 
45135 ** (delete, truncate or zero the first part of) the journal file (or 
45136 ** delete the master journal file if specified).
45137 **
45138 ** Note that if zMaster==NULL, this does not overwrite a previous value
45139 ** passed to an sqlite3PagerCommitPhaseOne() call.
45140 **
45141 ** If the final parameter - noSync - is true, then the database file itself
45142 ** is not synced. The caller must call sqlite3PagerSync() directly to
45143 ** sync the database file before calling CommitPhaseTwo() to delete the
45144 ** journal file in this case.
45145 */
45146 SQLITE_PRIVATE int sqlite3PagerCommitPhaseOne(
45147   Pager *pPager,                  /* Pager object */
45148   const char *zMaster,            /* If not NULL, the master journal name */
45149   int noSync                      /* True to omit the xSync on the db file */
45150 ){
45151   int rc = SQLITE_OK;             /* Return code */
45152 
45153   assert( pPager->eState==PAGER_WRITER_LOCKED
45154        || pPager->eState==PAGER_WRITER_CACHEMOD
45155        || pPager->eState==PAGER_WRITER_DBMOD
45156        || pPager->eState==PAGER_ERROR
45157   );
45158   assert( assert_pager_state(pPager) );
45159 
45160   /* If a prior error occurred, report that error again. */
45161   if( NEVER(pPager->errCode) ) return pPager->errCode;
45162 
45163   PAGERTRACE(("DATABASE SYNC: File=%s zMaster=%s nSize=%d\n", 
45164       pPager->zFilename, zMaster, pPager->dbSize));
45165 
45166   /* If no database changes have been made, return early. */
45167   if( pPager->eState<PAGER_WRITER_CACHEMOD ) return SQLITE_OK;
45168 
45169   if( MEMDB ){
45170     /* If this is an in-memory db, or no pages have been written to, or this
45171     ** function has already been called, it is mostly a no-op.  However, any
45172     ** backup in progress needs to be restarted.
45173     */
45174     sqlite3BackupRestart(pPager->pBackup);
45175   }else{
45176     if( pagerUseWal(pPager) ){
45177       PgHdr *pList = sqlite3PcacheDirtyList(pPager->pPCache);
45178       PgHdr *pPageOne = 0;
45179       if( pList==0 ){
45180         /* Must have at least one page for the WAL commit flag.
45181         ** Ticket [2d1a5c67dfc2363e44f29d9bbd57f] 2011-05-18 */
45182         rc = sqlite3PagerGet(pPager, 1, &pPageOne);
45183         pList = pPageOne;
45184         pList->pDirty = 0;
45185       }
45186       assert( rc==SQLITE_OK );
45187       if( ALWAYS(pList) ){
45188         rc = pagerWalFrames(pPager, pList, pPager->dbSize, 1);
45189       }
45190       sqlite3PagerUnref(pPageOne);
45191       if( rc==SQLITE_OK ){
45192         sqlite3PcacheCleanAll(pPager->pPCache);
45193       }
45194     }else{
45195       /* The following block updates the change-counter. Exactly how it
45196       ** does this depends on whether or not the atomic-update optimization
45197       ** was enabled at compile time, and if this transaction meets the 
45198       ** runtime criteria to use the operation: 
45199       **
45200       **    * The file-system supports the atomic-write property for
45201       **      blocks of size page-size, and 
45202       **    * This commit is not part of a multi-file transaction, and
45203       **    * Exactly one page has been modified and store in the journal file.
45204       **
45205       ** If the optimization was not enabled at compile time, then the
45206       ** pager_incr_changecounter() function is called to update the change
45207       ** counter in 'indirect-mode'. If the optimization is compiled in but
45208       ** is not applicable to this transaction, call sqlite3JournalCreate()
45209       ** to make sure the journal file has actually been created, then call
45210       ** pager_incr_changecounter() to update the change-counter in indirect
45211       ** mode. 
45212       **
45213       ** Otherwise, if the optimization is both enabled and applicable,
45214       ** then call pager_incr_changecounter() to update the change-counter
45215       ** in 'direct' mode. In this case the journal file will never be
45216       ** created for this transaction.
45217       */
45218   #ifdef SQLITE_ENABLE_ATOMIC_WRITE
45219       PgHdr *pPg;
45220       assert( isOpen(pPager->jfd) 
45221            || pPager->journalMode==PAGER_JOURNALMODE_OFF 
45222            || pPager->journalMode==PAGER_JOURNALMODE_WAL 
45223       );
45224       if( !zMaster && isOpen(pPager->jfd) 
45225        && pPager->journalOff==jrnlBufferSize(pPager) 
45226        && pPager->dbSize>=pPager->dbOrigSize
45227        && (0==(pPg = sqlite3PcacheDirtyList(pPager->pPCache)) || 0==pPg->pDirty)
45228       ){
45229         /* Update the db file change counter via the direct-write method. The 
45230         ** following call will modify the in-memory representation of page 1 
45231         ** to include the updated change counter and then write page 1 
45232         ** directly to the database file. Because of the atomic-write 
45233         ** property of the host file-system, this is safe.
45234         */
45235         rc = pager_incr_changecounter(pPager, 1);
45236       }else{
45237         rc = sqlite3JournalCreate(pPager->jfd);
45238         if( rc==SQLITE_OK ){
45239           rc = pager_incr_changecounter(pPager, 0);
45240         }
45241       }
45242   #else
45243       rc = pager_incr_changecounter(pPager, 0);
45244   #endif
45245       if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
45246   
45247       /* Write the master journal name into the journal file. If a master 
45248       ** journal file name has already been written to the journal file, 
45249       ** or if zMaster is NULL (no master journal), then this call is a no-op.
45250       */
45251       rc = writeMasterJournal(pPager, zMaster);
45252       if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
45253   
45254       /* Sync the journal file and write all dirty pages to the database.
45255       ** If the atomic-update optimization is being used, this sync will not 
45256       ** create the journal file or perform any real IO.
45257       **
45258       ** Because the change-counter page was just modified, unless the
45259       ** atomic-update optimization is used it is almost certain that the
45260       ** journal requires a sync here. However, in locking_mode=exclusive
45261       ** on a system under memory pressure it is just possible that this is 
45262       ** not the case. In this case it is likely enough that the redundant
45263       ** xSync() call will be changed to a no-op by the OS anyhow. 
45264       */
45265       rc = syncJournal(pPager, 0);
45266       if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
45267   
45268       rc = pager_write_pagelist(pPager,sqlite3PcacheDirtyList(pPager->pPCache));
45269       if( rc!=SQLITE_OK ){
45270         assert( rc!=SQLITE_IOERR_BLOCKED );
45271         goto commit_phase_one_exit;
45272       }
45273       sqlite3PcacheCleanAll(pPager->pPCache);
45274 
45275       /* If the file on disk is smaller than the database image, use 
45276       ** pager_truncate to grow the file here. This can happen if the database
45277       ** image was extended as part of the current transaction and then the
45278       ** last page in the db image moved to the free-list. In this case the
45279       ** last page is never written out to disk, leaving the database file
45280       ** undersized. Fix this now if it is the case.  */
45281       if( pPager->dbSize>pPager->dbFileSize ){
45282         Pgno nNew = pPager->dbSize - (pPager->dbSize==PAGER_MJ_PGNO(pPager));
45283         assert( pPager->eState==PAGER_WRITER_DBMOD );
45284         rc = pager_truncate(pPager, nNew);
45285         if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
45286       }
45287   
45288       /* Finally, sync the database file. */
45289       if( !noSync ){
45290         rc = sqlite3PagerSync(pPager);
45291       }
45292       IOTRACE(("DBSYNC %p\n", pPager))
45293     }
45294   }
45295 
45296 commit_phase_one_exit:
45297   if( rc==SQLITE_OK && !pagerUseWal(pPager) ){
45298     pPager->eState = PAGER_WRITER_FINISHED;
45299   }
45300   return rc;
45301 }
45302 
45303 
45304 /*
45305 ** When this function is called, the database file has been completely
45306 ** updated to reflect the changes made by the current transaction and
45307 ** synced to disk. The journal file still exists in the file-system 
45308 ** though, and if a failure occurs at this point it will eventually
45309 ** be used as a hot-journal and the current transaction rolled back.
45310 **
45311 ** This function finalizes the journal file, either by deleting, 
45312 ** truncating or partially zeroing it, so that it cannot be used 
45313 ** for hot-journal rollback. Once this is done the transaction is
45314 ** irrevocably committed.
45315 **
45316 ** If an error occurs, an IO error code is returned and the pager
45317 ** moves into the error state. Otherwise, SQLITE_OK is returned.
45318 */
45319 SQLITE_PRIVATE int sqlite3PagerCommitPhaseTwo(Pager *pPager){
45320   int rc = SQLITE_OK;                  /* Return code */
45321 
45322   /* This routine should not be called if a prior error has occurred.
45323   ** But if (due to a coding error elsewhere in the system) it does get
45324   ** called, just return the same error code without doing anything. */
45325   if( NEVER(pPager->errCode) ) return pPager->errCode;
45326 
45327   assert( pPager->eState==PAGER_WRITER_LOCKED
45328        || pPager->eState==PAGER_WRITER_FINISHED
45329        || (pagerUseWal(pPager) && pPager->eState==PAGER_WRITER_CACHEMOD)
45330   );
45331   assert( assert_pager_state(pPager) );
45332 
45333   /* An optimization. If the database was not actually modified during
45334   ** this transaction, the pager is running in exclusive-mode and is
45335   ** using persistent journals, then this function is a no-op.
45336   **
45337   ** The start of the journal file currently contains a single journal 
45338   ** header with the nRec field set to 0. If such a journal is used as
45339   ** a hot-journal during hot-journal rollback, 0 changes will be made
45340   ** to the database file. So there is no need to zero the journal 
45341   ** header. Since the pager is in exclusive mode, there is no need
45342   ** to drop any locks either.
45343   */
45344   if( pPager->eState==PAGER_WRITER_LOCKED 
45345    && pPager->exclusiveMode 
45346    && pPager->journalMode==PAGER_JOURNALMODE_PERSIST
45347   ){
45348     assert( pPager->journalOff==JOURNAL_HDR_SZ(pPager) || !pPager->journalOff );
45349     pPager->eState = PAGER_READER;
45350     return SQLITE_OK;
45351   }
45352 
45353   PAGERTRACE(("COMMIT %d\n", PAGERID(pPager)));
45354   rc = pager_end_transaction(pPager, pPager->setMaster, 1);
45355   return pager_error(pPager, rc);
45356 }
45357 
45358 /*
45359 ** If a write transaction is open, then all changes made within the 
45360 ** transaction are reverted and the current write-transaction is closed.
45361 ** The pager falls back to PAGER_READER state if successful, or PAGER_ERROR
45362 ** state if an error occurs.
45363 **
45364 ** If the pager is already in PAGER_ERROR state when this function is called,
45365 ** it returns Pager.errCode immediately. No work is performed in this case.
45366 **
45367 ** Otherwise, in rollback mode, this function performs two functions:
45368 **
45369 **   1) It rolls back the journal file, restoring all database file and 
45370 **      in-memory cache pages to the state they were in when the transaction
45371 **      was opened, and
45372 **
45373 **   2) It finalizes the journal file, so that it is not used for hot
45374 **      rollback at any point in the future.
45375 **
45376 ** Finalization of the journal file (task 2) is only performed if the 
45377 ** rollback is successful.
45378 **
45379 ** In WAL mode, all cache-entries containing data modified within the
45380 ** current transaction are either expelled from the cache or reverted to
45381 ** their pre-transaction state by re-reading data from the database or
45382 ** WAL files. The WAL transaction is then closed.
45383 */
45384 SQLITE_PRIVATE int sqlite3PagerRollback(Pager *pPager){
45385   int rc = SQLITE_OK;                  /* Return code */
45386   PAGERTRACE(("ROLLBACK %d\n", PAGERID(pPager)));
45387 
45388   /* PagerRollback() is a no-op if called in READER or OPEN state. If
45389   ** the pager is already in the ERROR state, the rollback is not 
45390   ** attempted here. Instead, the error code is returned to the caller.
45391   */
45392   assert( assert_pager_state(pPager) );
45393   if( pPager->eState==PAGER_ERROR ) return pPager->errCode;
45394   if( pPager->eState<=PAGER_READER ) return SQLITE_OK;
45395 
45396   if( pagerUseWal(pPager) ){
45397     int rc2;
45398     rc = sqlite3PagerSavepoint(pPager, SAVEPOINT_ROLLBACK, -1);
45399     rc2 = pager_end_transaction(pPager, pPager->setMaster, 0);
45400     if( rc==SQLITE_OK ) rc = rc2;
45401   }else if( !isOpen(pPager->jfd) || pPager->eState==PAGER_WRITER_LOCKED ){
45402     int eState = pPager->eState;
45403     rc = pager_end_transaction(pPager, 0, 0);
45404     if( !MEMDB && eState>PAGER_WRITER_LOCKED ){
45405       /* This can happen using journal_mode=off. Move the pager to the error 
45406       ** state to indicate that the contents of the cache may not be trusted.
45407       ** Any active readers will get SQLITE_ABORT.
45408       */
45409       pPager->errCode = SQLITE_ABORT;
45410       pPager->eState = PAGER_ERROR;
45411       return rc;
45412     }
45413   }else{
45414     rc = pager_playback(pPager, 0);
45415   }
45416 
45417   assert( pPager->eState==PAGER_READER || rc!=SQLITE_OK );
45418   assert( rc==SQLITE_OK || rc==SQLITE_FULL || rc==SQLITE_CORRUPT
45419           || rc==SQLITE_NOMEM || (rc&0xFF)==SQLITE_IOERR );
45420 
45421   /* If an error occurs during a ROLLBACK, we can no longer trust the pager
45422   ** cache. So call pager_error() on the way out to make any error persistent.
45423   */
45424   return pager_error(pPager, rc);
45425 }
45426 
45427 /*
45428 ** Return TRUE if the database file is opened read-only.  Return FALSE
45429 ** if the database is (in theory) writable.
45430 */
45431 SQLITE_PRIVATE u8 sqlite3PagerIsreadonly(Pager *pPager){
45432   return pPager->readOnly;
45433 }
45434 
45435 /*
45436 ** Return the number of references to the pager.
45437 */
45438 SQLITE_PRIVATE int sqlite3PagerRefcount(Pager *pPager){
45439   return sqlite3PcacheRefCount(pPager->pPCache);
45440 }
45441 
45442 /*
45443 ** Return the approximate number of bytes of memory currently
45444 ** used by the pager and its associated cache.
45445 */
45446 SQLITE_PRIVATE int sqlite3PagerMemUsed(Pager *pPager){
45447   int perPageSize = pPager->pageSize + pPager->nExtra + sizeof(PgHdr)
45448                                      + 5*sizeof(void*);
45449   return perPageSize*sqlite3PcachePagecount(pPager->pPCache)
45450            + sqlite3MallocSize(pPager)
45451            + pPager->pageSize;
45452 }
45453 
45454 /*
45455 ** Return the number of references to the specified page.
45456 */
45457 SQLITE_PRIVATE int sqlite3PagerPageRefcount(DbPage *pPage){
45458   return sqlite3PcachePageRefcount(pPage);
45459 }
45460 
45461 #ifdef SQLITE_TEST
45462 /*
45463 ** This routine is used for testing and analysis only.
45464 */
45465 SQLITE_PRIVATE int *sqlite3PagerStats(Pager *pPager){
45466   static int a[11];
45467   a[0] = sqlite3PcacheRefCount(pPager->pPCache);
45468   a[1] = sqlite3PcachePagecount(pPager->pPCache);
45469   a[2] = sqlite3PcacheGetCachesize(pPager->pPCache);
45470   a[3] = pPager->eState==PAGER_OPEN ? -1 : (int) pPager->dbSize;
45471   a[4] = pPager->eState;
45472   a[5] = pPager->errCode;
45473   a[6] = pPager->aStat[PAGER_STAT_HIT];
45474   a[7] = pPager->aStat[PAGER_STAT_MISS];
45475   a[8] = 0;  /* Used to be pPager->nOvfl */
45476   a[9] = pPager->nRead;
45477   a[10] = pPager->aStat[PAGER_STAT_WRITE];
45478   return a;
45479 }
45480 #endif
45481 
45482 /*
45483 ** Parameter eStat must be either SQLITE_DBSTATUS_CACHE_HIT or
45484 ** SQLITE_DBSTATUS_CACHE_MISS. Before returning, *pnVal is incremented by the
45485 ** current cache hit or miss count, according to the value of eStat. If the 
45486 ** reset parameter is non-zero, the cache hit or miss count is zeroed before 
45487 ** returning.
45488 */
45489 SQLITE_PRIVATE void sqlite3PagerCacheStat(Pager *pPager, int eStat, int reset, int *pnVal){
45490 
45491   assert( eStat==SQLITE_DBSTATUS_CACHE_HIT
45492        || eStat==SQLITE_DBSTATUS_CACHE_MISS
45493        || eStat==SQLITE_DBSTATUS_CACHE_WRITE
45494   );
45495 
45496   assert( SQLITE_DBSTATUS_CACHE_HIT+1==SQLITE_DBSTATUS_CACHE_MISS );
45497   assert( SQLITE_DBSTATUS_CACHE_HIT+2==SQLITE_DBSTATUS_CACHE_WRITE );
45498   assert( PAGER_STAT_HIT==0 && PAGER_STAT_MISS==1 && PAGER_STAT_WRITE==2 );
45499 
45500   *pnVal += pPager->aStat[eStat - SQLITE_DBSTATUS_CACHE_HIT];
45501   if( reset ){
45502     pPager->aStat[eStat - SQLITE_DBSTATUS_CACHE_HIT] = 0;
45503   }
45504 }
45505 
45506 /*
45507 ** Return true if this is an in-memory pager.
45508 */
45509 SQLITE_PRIVATE int sqlite3PagerIsMemdb(Pager *pPager){
45510   return MEMDB;
45511 }
45512 
45513 /*
45514 ** Check that there are at least nSavepoint savepoints open. If there are
45515 ** currently less than nSavepoints open, then open one or more savepoints
45516 ** to make up the difference. If the number of savepoints is already
45517 ** equal to nSavepoint, then this function is a no-op.
45518 **
45519 ** If a memory allocation fails, SQLITE_NOMEM is returned. If an error 
45520 ** occurs while opening the sub-journal file, then an IO error code is
45521 ** returned. Otherwise, SQLITE_OK.
45522 */
45523 SQLITE_PRIVATE int sqlite3PagerOpenSavepoint(Pager *pPager, int nSavepoint){
45524   int rc = SQLITE_OK;                       /* Return code */
45525   int nCurrent = pPager->nSavepoint;        /* Current number of savepoints */
45526 
45527   assert( pPager->eState>=PAGER_WRITER_LOCKED );
45528   assert( assert_pager_state(pPager) );
45529 
45530   if( nSavepoint>nCurrent && pPager->useJournal ){
45531     int ii;                                 /* Iterator variable */
45532     PagerSavepoint *aNew;                   /* New Pager.aSavepoint array */
45533 
45534     /* Grow the Pager.aSavepoint array using realloc(). Return SQLITE_NOMEM
45535     ** if the allocation fails. Otherwise, zero the new portion in case a 
45536     ** malloc failure occurs while populating it in the for(...) loop below.
45537     */
45538     aNew = (PagerSavepoint *)sqlite3Realloc(
45539         pPager->aSavepoint, sizeof(PagerSavepoint)*nSavepoint
45540     );
45541     if( !aNew ){
45542       return SQLITE_NOMEM;
45543     }
45544     memset(&aNew[nCurrent], 0, (nSavepoint-nCurrent) * sizeof(PagerSavepoint));
45545     pPager->aSavepoint = aNew;
45546 
45547     /* Populate the PagerSavepoint structures just allocated. */
45548     for(ii=nCurrent; ii<nSavepoint; ii++){
45549       aNew[ii].nOrig = pPager->dbSize;
45550       if( isOpen(pPager->jfd) && pPager->journalOff>0 ){
45551         aNew[ii].iOffset = pPager->journalOff;
45552       }else{
45553         aNew[ii].iOffset = JOURNAL_HDR_SZ(pPager);
45554       }
45555       aNew[ii].iSubRec = pPager->nSubRec;
45556       aNew[ii].pInSavepoint = sqlite3BitvecCreate(pPager->dbSize);
45557       if( !aNew[ii].pInSavepoint ){
45558         return SQLITE_NOMEM;
45559       }
45560       if( pagerUseWal(pPager) ){
45561         sqlite3WalSavepoint(pPager->pWal, aNew[ii].aWalData);
45562       }
45563       pPager->nSavepoint = ii+1;
45564     }
45565     assert( pPager->nSavepoint==nSavepoint );
45566     assertTruncateConstraint(pPager);
45567   }
45568 
45569   return rc;
45570 }
45571 
45572 /*
45573 ** This function is called to rollback or release (commit) a savepoint.
45574 ** The savepoint to release or rollback need not be the most recently 
45575 ** created savepoint.
45576 **
45577 ** Parameter op is always either SAVEPOINT_ROLLBACK or SAVEPOINT_RELEASE.
45578 ** If it is SAVEPOINT_RELEASE, then release and destroy the savepoint with
45579 ** index iSavepoint. If it is SAVEPOINT_ROLLBACK, then rollback all changes
45580 ** that have occurred since the specified savepoint was created.
45581 **
45582 ** The savepoint to rollback or release is identified by parameter 
45583 ** iSavepoint. A value of 0 means to operate on the outermost savepoint
45584 ** (the first created). A value of (Pager.nSavepoint-1) means operate
45585 ** on the most recently created savepoint. If iSavepoint is greater than
45586 ** (Pager.nSavepoint-1), then this function is a no-op.
45587 **
45588 ** If a negative value is passed to this function, then the current
45589 ** transaction is rolled back. This is different to calling 
45590 ** sqlite3PagerRollback() because this function does not terminate
45591 ** the transaction or unlock the database, it just restores the 
45592 ** contents of the database to its original state. 
45593 **
45594 ** In any case, all savepoints with an index greater than iSavepoint 
45595 ** are destroyed. If this is a release operation (op==SAVEPOINT_RELEASE),
45596 ** then savepoint iSavepoint is also destroyed.
45597 **
45598 ** This function may return SQLITE_NOMEM if a memory allocation fails,
45599 ** or an IO error code if an IO error occurs while rolling back a 
45600 ** savepoint. If no errors occur, SQLITE_OK is returned.
45601 */ 
45602 SQLITE_PRIVATE int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint){
45603   int rc = pPager->errCode;       /* Return code */
45604 
45605   assert( op==SAVEPOINT_RELEASE || op==SAVEPOINT_ROLLBACK );
45606   assert( iSavepoint>=0 || op==SAVEPOINT_ROLLBACK );
45607 
45608   if( rc==SQLITE_OK && iSavepoint<pPager->nSavepoint ){
45609     int ii;            /* Iterator variable */
45610     int nNew;          /* Number of remaining savepoints after this op. */
45611 
45612     /* Figure out how many savepoints will still be active after this
45613     ** operation. Store this value in nNew. Then free resources associated 
45614     ** with any savepoints that are destroyed by this operation.
45615     */
45616     nNew = iSavepoint + (( op==SAVEPOINT_RELEASE ) ? 0 : 1);
45617     for(ii=nNew; ii<pPager->nSavepoint; ii++){
45618       sqlite3BitvecDestroy(pPager->aSavepoint[ii].pInSavepoint);
45619     }
45620     pPager->nSavepoint = nNew;
45621 
45622     /* If this is a release of the outermost savepoint, truncate 
45623     ** the sub-journal to zero bytes in size. */
45624     if( op==SAVEPOINT_RELEASE ){
45625       if( nNew==0 && isOpen(pPager->sjfd) ){
45626         /* Only truncate if it is an in-memory sub-journal. */
45627         if( sqlite3IsMemJournal(pPager->sjfd) ){
45628           rc = sqlite3OsTruncate(pPager->sjfd, 0);
45629           assert( rc==SQLITE_OK );
45630         }
45631         pPager->nSubRec = 0;
45632       }
45633     }
45634     /* Else this is a rollback operation, playback the specified savepoint.
45635     ** If this is a temp-file, it is possible that the journal file has
45636     ** not yet been opened. In this case there have been no changes to
45637     ** the database file, so the playback operation can be skipped.
45638     */
45639     else if( pagerUseWal(pPager) || isOpen(pPager->jfd) ){
45640       PagerSavepoint *pSavepoint = (nNew==0)?0:&pPager->aSavepoint[nNew-1];
45641       rc = pagerPlaybackSavepoint(pPager, pSavepoint);
45642       assert(rc!=SQLITE_DONE);
45643     }
45644   }
45645 
45646   return rc;
45647 }
45648 
45649 /*
45650 ** Return the full pathname of the database file.
45651 **
45652 ** Except, if the pager is in-memory only, then return an empty string if
45653 ** nullIfMemDb is true.  This routine is called with nullIfMemDb==1 when
45654 ** used to report the filename to the user, for compatibility with legacy
45655 ** behavior.  But when the Btree needs to know the filename for matching to
45656 ** shared cache, it uses nullIfMemDb==0 so that in-memory databases can
45657 ** participate in shared-cache.
45658 */
45659 SQLITE_PRIVATE const char *sqlite3PagerFilename(Pager *pPager, int nullIfMemDb){
45660   return (nullIfMemDb && pPager->memDb) ? "" : pPager->zFilename;
45661 }
45662 
45663 /*
45664 ** Return the VFS structure for the pager.
45665 */
45666 SQLITE_PRIVATE const sqlite3_vfs *sqlite3PagerVfs(Pager *pPager){
45667   return pPager->pVfs;
45668 }
45669 
45670 /*
45671 ** Return the file handle for the database file associated
45672 ** with the pager.  This might return NULL if the file has
45673 ** not yet been opened.
45674 */
45675 SQLITE_PRIVATE sqlite3_file *sqlite3PagerFile(Pager *pPager){
45676   return pPager->fd;
45677 }
45678 
45679 /*
45680 ** Return the full pathname of the journal file.
45681 */
45682 SQLITE_PRIVATE const char *sqlite3PagerJournalname(Pager *pPager){
45683   return pPager->zJournal;
45684 }
45685 
45686 /*
45687 ** Return true if fsync() calls are disabled for this pager.  Return FALSE
45688 ** if fsync()s are executed normally.
45689 */
45690 SQLITE_PRIVATE int sqlite3PagerNosync(Pager *pPager){
45691   return pPager->noSync;
45692 }
45693 
45694 #ifdef SQLITE_HAS_CODEC
45695 /*
45696 ** Set or retrieve the codec for this pager
45697 */
45698 SQLITE_PRIVATE void sqlite3PagerSetCodec(
45699   Pager *pPager,
45700   void *(*xCodec)(void*,void*,Pgno,int),
45701   void (*xCodecSizeChng)(void*,int,int),
45702   void (*xCodecFree)(void*),
45703   void *pCodec
45704 ){
45705   if( pPager->xCodecFree ) pPager->xCodecFree(pPager->pCodec);
45706   pPager->xCodec = pPager->memDb ? 0 : xCodec;
45707   pPager->xCodecSizeChng = xCodecSizeChng;
45708   pPager->xCodecFree = xCodecFree;
45709   pPager->pCodec = pCodec;
45710   pagerReportSize(pPager);
45711 }
45712 SQLITE_PRIVATE void *sqlite3PagerGetCodec(Pager *pPager){
45713   return pPager->pCodec;
45714 }
45715 
45716 /*
45717 ** This function is called by the wal module when writing page content
45718 ** into the log file.
45719 **
45720 ** This function returns a pointer to a buffer containing the encrypted
45721 ** page content. If a malloc fails, this function may return NULL.
45722 */
45723 SQLITE_PRIVATE void *sqlite3PagerCodec(PgHdr *pPg){
45724   void *aData = 0;
45725   CODEC2(pPg->pPager, pPg->pData, pPg->pgno, 6, return 0, aData);
45726   return aData;
45727 }
45728 
45729 /*
45730 ** Return the current pager state
45731 */
45732 SQLITE_PRIVATE int sqlite3PagerState(Pager *pPager){
45733   return pPager->eState;
45734 }
45735 #endif /* SQLITE_HAS_CODEC */
45736 
45737 #ifndef SQLITE_OMIT_AUTOVACUUM
45738 /*
45739 ** Move the page pPg to location pgno in the file.
45740 **
45741 ** There must be no references to the page previously located at
45742 ** pgno (which we call pPgOld) though that page is allowed to be
45743 ** in cache.  If the page previously located at pgno is not already
45744 ** in the rollback journal, it is not put there by by this routine.
45745 **
45746 ** References to the page pPg remain valid. Updating any
45747 ** meta-data associated with pPg (i.e. data stored in the nExtra bytes
45748 ** allocated along with the page) is the responsibility of the caller.
45749 **
45750 ** A transaction must be active when this routine is called. It used to be
45751 ** required that a statement transaction was not active, but this restriction
45752 ** has been removed (CREATE INDEX needs to move a page when a statement
45753 ** transaction is active).
45754 **
45755 ** If the fourth argument, isCommit, is non-zero, then this page is being
45756 ** moved as part of a database reorganization just before the transaction 
45757 ** is being committed. In this case, it is guaranteed that the database page 
45758 ** pPg refers to will not be written to again within this transaction.
45759 **
45760 ** This function may return SQLITE_NOMEM or an IO error code if an error
45761 ** occurs. Otherwise, it returns SQLITE_OK.
45762 */
45763 SQLITE_PRIVATE int sqlite3PagerMovepage(Pager *pPager, DbPage *pPg, Pgno pgno, int isCommit){
45764   PgHdr *pPgOld;               /* The page being overwritten. */
45765   Pgno needSyncPgno = 0;       /* Old value of pPg->pgno, if sync is required */
45766   int rc;                      /* Return code */
45767   Pgno origPgno;               /* The original page number */
45768 
45769   assert( pPg->nRef>0 );
45770   assert( pPager->eState==PAGER_WRITER_CACHEMOD
45771        || pPager->eState==PAGER_WRITER_DBMOD
45772   );
45773   assert( assert_pager_state(pPager) );
45774 
45775   /* In order to be able to rollback, an in-memory database must journal
45776   ** the page we are moving from.
45777   */
45778   if( MEMDB ){
45779     rc = sqlite3PagerWrite(pPg);
45780     if( rc ) return rc;
45781   }
45782 
45783   /* If the page being moved is dirty and has not been saved by the latest
45784   ** savepoint, then save the current contents of the page into the 
45785   ** sub-journal now. This is required to handle the following scenario:
45786   **
45787   **   BEGIN;
45788   **     <journal page X, then modify it in memory>
45789   **     SAVEPOINT one;
45790   **       <Move page X to location Y>
45791   **     ROLLBACK TO one;
45792   **
45793   ** If page X were not written to the sub-journal here, it would not
45794   ** be possible to restore its contents when the "ROLLBACK TO one"
45795   ** statement were is processed.
45796   **
45797   ** subjournalPage() may need to allocate space to store pPg->pgno into
45798   ** one or more savepoint bitvecs. This is the reason this function
45799   ** may return SQLITE_NOMEM.
45800   */
45801   if( pPg->flags&PGHDR_DIRTY
45802    && subjRequiresPage(pPg)
45803    && SQLITE_OK!=(rc = subjournalPage(pPg))
45804   ){
45805     return rc;
45806   }
45807 
45808   PAGERTRACE(("MOVE %d page %d (needSync=%d) moves to %d\n", 
45809       PAGERID(pPager), pPg->pgno, (pPg->flags&PGHDR_NEED_SYNC)?1:0, pgno));
45810   IOTRACE(("MOVE %p %d %d\n", pPager, pPg->pgno, pgno))
45811 
45812   /* If the journal needs to be sync()ed before page pPg->pgno can
45813   ** be written to, store pPg->pgno in local variable needSyncPgno.
45814   **
45815   ** If the isCommit flag is set, there is no need to remember that
45816   ** the journal needs to be sync()ed before database page pPg->pgno 
45817   ** can be written to. The caller has already promised not to write to it.
45818   */
45819   if( (pPg->flags&PGHDR_NEED_SYNC) && !isCommit ){
45820     needSyncPgno = pPg->pgno;
45821     assert( pPager->journalMode==PAGER_JOURNALMODE_OFF ||
45822             pageInJournal(pPg) || pPg->pgno>pPager->dbOrigSize );
45823     assert( pPg->flags&PGHDR_DIRTY );
45824   }
45825 
45826   /* If the cache contains a page with page-number pgno, remove it
45827   ** from its hash chain. Also, if the PGHDR_NEED_SYNC flag was set for 
45828   ** page pgno before the 'move' operation, it needs to be retained 
45829   ** for the page moved there.
45830   */
45831   pPg->flags &= ~PGHDR_NEED_SYNC;
45832   pPgOld = pager_lookup(pPager, pgno);
45833   assert( !pPgOld || pPgOld->nRef==1 );
45834   if( pPgOld ){
45835     pPg->flags |= (pPgOld->flags&PGHDR_NEED_SYNC);
45836     if( MEMDB ){
45837       /* Do not discard pages from an in-memory database since we might
45838       ** need to rollback later.  Just move the page out of the way. */
45839       sqlite3PcacheMove(pPgOld, pPager->dbSize+1);
45840     }else{
45841       sqlite3PcacheDrop(pPgOld);
45842     }
45843   }
45844 
45845   origPgno = pPg->pgno;
45846   sqlite3PcacheMove(pPg, pgno);
45847   sqlite3PcacheMakeDirty(pPg);
45848 
45849   /* For an in-memory database, make sure the original page continues
45850   ** to exist, in case the transaction needs to roll back.  Use pPgOld
45851   ** as the original page since it has already been allocated.
45852   */
45853   if( MEMDB ){
45854     assert( pPgOld );
45855     sqlite3PcacheMove(pPgOld, origPgno);
45856     sqlite3PagerUnref(pPgOld);
45857   }
45858 
45859   if( needSyncPgno ){
45860     /* If needSyncPgno is non-zero, then the journal file needs to be 
45861     ** sync()ed before any data is written to database file page needSyncPgno.
45862     ** Currently, no such page exists in the page-cache and the 
45863     ** "is journaled" bitvec flag has been set. This needs to be remedied by
45864     ** loading the page into the pager-cache and setting the PGHDR_NEED_SYNC
45865     ** flag.
45866     **
45867     ** If the attempt to load the page into the page-cache fails, (due
45868     ** to a malloc() or IO failure), clear the bit in the pInJournal[]
45869     ** array. Otherwise, if the page is loaded and written again in
45870     ** this transaction, it may be written to the database file before
45871     ** it is synced into the journal file. This way, it may end up in
45872     ** the journal file twice, but that is not a problem.
45873     */
45874     PgHdr *pPgHdr;
45875     rc = sqlite3PagerGet(pPager, needSyncPgno, &pPgHdr);
45876     if( rc!=SQLITE_OK ){
45877       if( needSyncPgno<=pPager->dbOrigSize ){
45878         assert( pPager->pTmpSpace!=0 );
45879         sqlite3BitvecClear(pPager->pInJournal, needSyncPgno, pPager->pTmpSpace);
45880       }
45881       return rc;
45882     }
45883     pPgHdr->flags |= PGHDR_NEED_SYNC;
45884     sqlite3PcacheMakeDirty(pPgHdr);
45885     sqlite3PagerUnref(pPgHdr);
45886   }
45887 
45888   return SQLITE_OK;
45889 }
45890 #endif
45891 
45892 /*
45893 ** Return a pointer to the data for the specified page.
45894 */
45895 SQLITE_PRIVATE void *sqlite3PagerGetData(DbPage *pPg){
45896   assert( pPg->nRef>0 || pPg->pPager->memDb );
45897   return pPg->pData;
45898 }
45899 
45900 /*
45901 ** Return a pointer to the Pager.nExtra bytes of "extra" space 
45902 ** allocated along with the specified page.
45903 */
45904 SQLITE_PRIVATE void *sqlite3PagerGetExtra(DbPage *pPg){
45905   return pPg->pExtra;
45906 }
45907 
45908 /*
45909 ** Get/set the locking-mode for this pager. Parameter eMode must be one
45910 ** of PAGER_LOCKINGMODE_QUERY, PAGER_LOCKINGMODE_NORMAL or 
45911 ** PAGER_LOCKINGMODE_EXCLUSIVE. If the parameter is not _QUERY, then
45912 ** the locking-mode is set to the value specified.
45913 **
45914 ** The returned value is either PAGER_LOCKINGMODE_NORMAL or
45915 ** PAGER_LOCKINGMODE_EXCLUSIVE, indicating the current (possibly updated)
45916 ** locking-mode.
45917 */
45918 SQLITE_PRIVATE int sqlite3PagerLockingMode(Pager *pPager, int eMode){
45919   assert( eMode==PAGER_LOCKINGMODE_QUERY
45920             || eMode==PAGER_LOCKINGMODE_NORMAL
45921             || eMode==PAGER_LOCKINGMODE_EXCLUSIVE );
45922   assert( PAGER_LOCKINGMODE_QUERY<0 );
45923   assert( PAGER_LOCKINGMODE_NORMAL>=0 && PAGER_LOCKINGMODE_EXCLUSIVE>=0 );
45924   assert( pPager->exclusiveMode || 0==sqlite3WalHeapMemory(pPager->pWal) );
45925   if( eMode>=0 && !pPager->tempFile && !sqlite3WalHeapMemory(pPager->pWal) ){
45926     pPager->exclusiveMode = (u8)eMode;
45927   }
45928   return (int)pPager->exclusiveMode;
45929 }
45930 
45931 /*
45932 ** Set the journal-mode for this pager. Parameter eMode must be one of:
45933 **
45934 **    PAGER_JOURNALMODE_DELETE
45935 **    PAGER_JOURNALMODE_TRUNCATE
45936 **    PAGER_JOURNALMODE_PERSIST
45937 **    PAGER_JOURNALMODE_OFF
45938 **    PAGER_JOURNALMODE_MEMORY
45939 **    PAGER_JOURNALMODE_WAL
45940 **
45941 ** The journalmode is set to the value specified if the change is allowed.
45942 ** The change may be disallowed for the following reasons:
45943 **
45944 **   *  An in-memory database can only have its journal_mode set to _OFF
45945 **      or _MEMORY.
45946 **
45947 **   *  Temporary databases cannot have _WAL journalmode.
45948 **
45949 ** The returned indicate the current (possibly updated) journal-mode.
45950 */
45951 SQLITE_PRIVATE int sqlite3PagerSetJournalMode(Pager *pPager, int eMode){
45952   u8 eOld = pPager->journalMode;    /* Prior journalmode */
45953 
45954 #ifdef SQLITE_DEBUG
45955   /* The print_pager_state() routine is intended to be used by the debugger
45956   ** only.  We invoke it once here to suppress a compiler warning. */
45957   print_pager_state(pPager);
45958 #endif
45959 
45960 
45961   /* The eMode parameter is always valid */
45962   assert(      eMode==PAGER_JOURNALMODE_DELETE
45963             || eMode==PAGER_JOURNALMODE_TRUNCATE
45964             || eMode==PAGER_JOURNALMODE_PERSIST
45965             || eMode==PAGER_JOURNALMODE_OFF 
45966             || eMode==PAGER_JOURNALMODE_WAL 
45967             || eMode==PAGER_JOURNALMODE_MEMORY );
45968 
45969   /* This routine is only called from the OP_JournalMode opcode, and
45970   ** the logic there will never allow a temporary file to be changed
45971   ** to WAL mode.
45972   */
45973   assert( pPager->tempFile==0 || eMode!=PAGER_JOURNALMODE_WAL );
45974 
45975   /* Do allow the journalmode of an in-memory database to be set to
45976   ** anything other than MEMORY or OFF
45977   */
45978   if( MEMDB ){
45979     assert( eOld==PAGER_JOURNALMODE_MEMORY || eOld==PAGER_JOURNALMODE_OFF );
45980     if( eMode!=PAGER_JOURNALMODE_MEMORY && eMode!=PAGER_JOURNALMODE_OFF ){
45981       eMode = eOld;
45982     }
45983   }
45984 
45985   if( eMode!=eOld ){
45986 
45987     /* Change the journal mode. */
45988     assert( pPager->eState!=PAGER_ERROR );
45989     pPager->journalMode = (u8)eMode;
45990 
45991     /* When transistioning from TRUNCATE or PERSIST to any other journal
45992     ** mode except WAL, unless the pager is in locking_mode=exclusive mode,
45993     ** delete the journal file.
45994     */
45995     assert( (PAGER_JOURNALMODE_TRUNCATE & 5)==1 );
45996     assert( (PAGER_JOURNALMODE_PERSIST & 5)==1 );
45997     assert( (PAGER_JOURNALMODE_DELETE & 5)==0 );
45998     assert( (PAGER_JOURNALMODE_MEMORY & 5)==4 );
45999     assert( (PAGER_JOURNALMODE_OFF & 5)==0 );
46000     assert( (PAGER_JOURNALMODE_WAL & 5)==5 );
46001 
46002     assert( isOpen(pPager->fd) || pPager->exclusiveMode );
46003     if( !pPager->exclusiveMode && (eOld & 5)==1 && (eMode & 1)==0 ){
46004 
46005       /* In this case we would like to delete the journal file. If it is
46006       ** not possible, then that is not a problem. Deleting the journal file
46007       ** here is an optimization only.
46008       **
46009       ** Before deleting the journal file, obtain a RESERVED lock on the
46010       ** database file. This ensures that the journal file is not deleted
46011       ** while it is in use by some other client.
46012       */
46013       sqlite3OsClose(pPager->jfd);
46014       if( pPager->eLock>=RESERVED_LOCK ){
46015         sqlite3OsDelete(pPager->pVfs, pPager->zJournal, 0);
46016       }else{
46017         int rc = SQLITE_OK;
46018         int state = pPager->eState;
46019         assert( state==PAGER_OPEN || state==PAGER_READER );
46020         if( state==PAGER_OPEN ){
46021           rc = sqlite3PagerSharedLock(pPager);
46022         }
46023         if( pPager->eState==PAGER_READER ){
46024           assert( rc==SQLITE_OK );
46025           rc = pagerLockDb(pPager, RESERVED_LOCK);
46026         }
46027         if( rc==SQLITE_OK ){
46028           sqlite3OsDelete(pPager->pVfs, pPager->zJournal, 0);
46029         }
46030         if( rc==SQLITE_OK && state==PAGER_READER ){
46031           pagerUnlockDb(pPager, SHARED_LOCK);
46032         }else if( state==PAGER_OPEN ){
46033           pager_unlock(pPager);
46034         }
46035         assert( state==pPager->eState );
46036       }
46037     }
46038   }
46039 
46040   /* Return the new journal mode */
46041   return (int)pPager->journalMode;
46042 }
46043 
46044 /*
46045 ** Return the current journal mode.
46046 */
46047 SQLITE_PRIVATE int sqlite3PagerGetJournalMode(Pager *pPager){
46048   return (int)pPager->journalMode;
46049 }
46050 
46051 /*
46052 ** Return TRUE if the pager is in a state where it is OK to change the
46053 ** journalmode.  Journalmode changes can only happen when the database
46054 ** is unmodified.
46055 */
46056 SQLITE_PRIVATE int sqlite3PagerOkToChangeJournalMode(Pager *pPager){
46057   assert( assert_pager_state(pPager) );
46058   if( pPager->eState>=PAGER_WRITER_CACHEMOD ) return 0;
46059   if( NEVER(isOpen(pPager->jfd) && pPager->journalOff>0) ) return 0;
46060   return 1;
46061 }
46062 
46063 /*
46064 ** Get/set the size-limit used for persistent journal files.
46065 **
46066 ** Setting the size limit to -1 means no limit is enforced.
46067 ** An attempt to set a limit smaller than -1 is a no-op.
46068 */
46069 SQLITE_PRIVATE i64 sqlite3PagerJournalSizeLimit(Pager *pPager, i64 iLimit){
46070   if( iLimit>=-1 ){
46071     pPager->journalSizeLimit = iLimit;
46072     sqlite3WalLimit(pPager->pWal, iLimit);
46073   }
46074   return pPager->journalSizeLimit;
46075 }
46076 
46077 /*
46078 ** Return a pointer to the pPager->pBackup variable. The backup module
46079 ** in backup.c maintains the content of this variable. This module
46080 ** uses it opaquely as an argument to sqlite3BackupRestart() and
46081 ** sqlite3BackupUpdate() only.
46082 */
46083 SQLITE_PRIVATE sqlite3_backup **sqlite3PagerBackupPtr(Pager *pPager){
46084   return &pPager->pBackup;
46085 }
46086 
46087 #ifndef SQLITE_OMIT_VACUUM
46088 /*
46089 ** Unless this is an in-memory or temporary database, clear the pager cache.
46090 */
46091 SQLITE_PRIVATE void sqlite3PagerClearCache(Pager *pPager){
46092   if( !MEMDB && pPager->tempFile==0 ) pager_reset(pPager);
46093 }
46094 #endif
46095 
46096 #ifndef SQLITE_OMIT_WAL
46097 /*
46098 ** This function is called when the user invokes "PRAGMA wal_checkpoint",
46099 ** "PRAGMA wal_blocking_checkpoint" or calls the sqlite3_wal_checkpoint()
46100 ** or wal_blocking_checkpoint() API functions.
46101 **
46102 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
46103 */
46104 SQLITE_PRIVATE int sqlite3PagerCheckpoint(Pager *pPager, int eMode, int *pnLog, int *pnCkpt){
46105   int rc = SQLITE_OK;
46106   if( pPager->pWal ){
46107     rc = sqlite3WalCheckpoint(pPager->pWal, eMode,
46108         pPager->xBusyHandler, pPager->pBusyHandlerArg,
46109         pPager->ckptSyncFlags, pPager->pageSize, (u8 *)pPager->pTmpSpace,
46110         pnLog, pnCkpt
46111     );
46112   }
46113   return rc;
46114 }
46115 
46116 SQLITE_PRIVATE int sqlite3PagerWalCallback(Pager *pPager){
46117   return sqlite3WalCallback(pPager->pWal);
46118 }
46119 
46120 /*
46121 ** Return true if the underlying VFS for the given pager supports the
46122 ** primitives necessary for write-ahead logging.
46123 */
46124 SQLITE_PRIVATE int sqlite3PagerWalSupported(Pager *pPager){
46125   const sqlite3_io_methods *pMethods = pPager->fd->pMethods;
46126   return pPager->exclusiveMode || (pMethods->iVersion>=2 && pMethods->xShmMap);
46127 }
46128 
46129 /*
46130 ** Attempt to take an exclusive lock on the database file. If a PENDING lock
46131 ** is obtained instead, immediately release it.
46132 */
46133 static int pagerExclusiveLock(Pager *pPager){
46134   int rc;                         /* Return code */
46135 
46136   assert( pPager->eLock==SHARED_LOCK || pPager->eLock==EXCLUSIVE_LOCK );
46137   rc = pagerLockDb(pPager, EXCLUSIVE_LOCK);
46138   if( rc!=SQLITE_OK ){
46139     /* If the attempt to grab the exclusive lock failed, release the 
46140     ** pending lock that may have been obtained instead.  */
46141     pagerUnlockDb(pPager, SHARED_LOCK);
46142   }
46143 
46144   return rc;
46145 }
46146 
46147 /*
46148 ** Call sqlite3WalOpen() to open the WAL handle. If the pager is in 
46149 ** exclusive-locking mode when this function is called, take an EXCLUSIVE
46150 ** lock on the database file and use heap-memory to store the wal-index
46151 ** in. Otherwise, use the normal shared-memory.
46152 */
46153 static int pagerOpenWal(Pager *pPager){
46154   int rc = SQLITE_OK;
46155 
46156   assert( pPager->pWal==0 && pPager->tempFile==0 );
46157   assert( pPager->eLock==SHARED_LOCK || pPager->eLock==EXCLUSIVE_LOCK );
46158 
46159   /* If the pager is already in exclusive-mode, the WAL module will use 
46160   ** heap-memory for the wal-index instead of the VFS shared-memory 
46161   ** implementation. Take the exclusive lock now, before opening the WAL
46162   ** file, to make sure this is safe.
46163   */
46164   if( pPager->exclusiveMode ){
46165     rc = pagerExclusiveLock(pPager);
46166   }
46167 
46168   /* Open the connection to the log file. If this operation fails, 
46169   ** (e.g. due to malloc() failure), return an error code.
46170   */
46171   if( rc==SQLITE_OK ){
46172     rc = sqlite3WalOpen(pPager->pVfs,
46173         pPager->fd, pPager->zWal, pPager->exclusiveMode,
46174         pPager->journalSizeLimit, &pPager->pWal
46175     );
46176   }
46177   pagerFixMaplimit(pPager);
46178 
46179   return rc;
46180 }
46181 
46182 
46183 /*
46184 ** The caller must be holding a SHARED lock on the database file to call
46185 ** this function.
46186 **
46187 ** If the pager passed as the first argument is open on a real database
46188 ** file (not a temp file or an in-memory database), and the WAL file
46189 ** is not already open, make an attempt to open it now. If successful,
46190 ** return SQLITE_OK. If an error occurs or the VFS used by the pager does 
46191 ** not support the xShmXXX() methods, return an error code. *pbOpen is
46192 ** not modified in either case.
46193 **
46194 ** If the pager is open on a temp-file (or in-memory database), or if
46195 ** the WAL file is already open, set *pbOpen to 1 and return SQLITE_OK
46196 ** without doing anything.
46197 */
46198 SQLITE_PRIVATE int sqlite3PagerOpenWal(
46199   Pager *pPager,                  /* Pager object */
46200   int *pbOpen                     /* OUT: Set to true if call is a no-op */
46201 ){
46202   int rc = SQLITE_OK;             /* Return code */
46203 
46204   assert( assert_pager_state(pPager) );
46205   assert( pPager->eState==PAGER_OPEN   || pbOpen );
46206   assert( pPager->eState==PAGER_READER || !pbOpen );
46207   assert( pbOpen==0 || *pbOpen==0 );
46208   assert( pbOpen!=0 || (!pPager->tempFile && !pPager->pWal) );
46209 
46210   if( !pPager->tempFile && !pPager->pWal ){
46211     if( !sqlite3PagerWalSupported(pPager) ) return SQLITE_CANTOPEN;
46212 
46213     /* Close any rollback journal previously open */
46214     sqlite3OsClose(pPager->jfd);
46215 
46216     rc = pagerOpenWal(pPager);
46217     if( rc==SQLITE_OK ){
46218       pPager->journalMode = PAGER_JOURNALMODE_WAL;
46219       pPager->eState = PAGER_OPEN;
46220     }
46221   }else{
46222     *pbOpen = 1;
46223   }
46224 
46225   return rc;
46226 }
46227 
46228 /*
46229 ** This function is called to close the connection to the log file prior
46230 ** to switching from WAL to rollback mode.
46231 **
46232 ** Before closing the log file, this function attempts to take an 
46233 ** EXCLUSIVE lock on the database file. If this cannot be obtained, an
46234 ** error (SQLITE_BUSY) is returned and the log connection is not closed.
46235 ** If successful, the EXCLUSIVE lock is not released before returning.
46236 */
46237 SQLITE_PRIVATE int sqlite3PagerCloseWal(Pager *pPager){
46238   int rc = SQLITE_OK;
46239 
46240   assert( pPager->journalMode==PAGER_JOURNALMODE_WAL );
46241 
46242   /* If the log file is not already open, but does exist in the file-system,
46243   ** it may need to be checkpointed before the connection can switch to
46244   ** rollback mode. Open it now so this can happen.
46245   */
46246   if( !pPager->pWal ){
46247     int logexists = 0;
46248     rc = pagerLockDb(pPager, SHARED_LOCK);
46249     if( rc==SQLITE_OK ){
46250       rc = sqlite3OsAccess(
46251           pPager->pVfs, pPager->zWal, SQLITE_ACCESS_EXISTS, &logexists
46252       );
46253     }
46254     if( rc==SQLITE_OK && logexists ){
46255       rc = pagerOpenWal(pPager);
46256     }
46257   }
46258     
46259   /* Checkpoint and close the log. Because an EXCLUSIVE lock is held on
46260   ** the database file, the log and log-summary files will be deleted.
46261   */
46262   if( rc==SQLITE_OK && pPager->pWal ){
46263     rc = pagerExclusiveLock(pPager);
46264     if( rc==SQLITE_OK ){
46265       rc = sqlite3WalClose(pPager->pWal, pPager->ckptSyncFlags,
46266                            pPager->pageSize, (u8*)pPager->pTmpSpace);
46267       pPager->pWal = 0;
46268       pagerFixMaplimit(pPager);
46269     }
46270   }
46271   return rc;
46272 }
46273 
46274 #endif /* !SQLITE_OMIT_WAL */
46275 
46276 #ifdef SQLITE_ENABLE_ZIPVFS
46277 /*
46278 ** A read-lock must be held on the pager when this function is called. If
46279 ** the pager is in WAL mode and the WAL file currently contains one or more
46280 ** frames, return the size in bytes of the page images stored within the
46281 ** WAL frames. Otherwise, if this is not a WAL database or the WAL file
46282 ** is empty, return 0.
46283 */
46284 SQLITE_PRIVATE int sqlite3PagerWalFramesize(Pager *pPager){
46285   assert( pPager->eState==PAGER_READER );
46286   return sqlite3WalFramesize(pPager->pWal);
46287 }
46288 #endif
46289 
46290 #endif /* SQLITE_OMIT_DISKIO */
46291 
46292 /************** End of pager.c ***********************************************/
46293 /************** Begin file wal.c *********************************************/
46294 /*
46295 ** 2010 February 1
46296 **
46297 ** The author disclaims copyright to this source code.  In place of
46298 ** a legal notice, here is a blessing:
46299 **
46300 **    May you do good and not evil.
46301 **    May you find forgiveness for yourself and forgive others.
46302 **    May you share freely, never taking more than you give.
46303 **
46304 *************************************************************************
46305 **
46306 ** This file contains the implementation of a write-ahead log (WAL) used in 
46307 ** "journal_mode=WAL" mode.
46308 **
46309 ** WRITE-AHEAD LOG (WAL) FILE FORMAT
46310 **
46311 ** A WAL file consists of a header followed by zero or more "frames".
46312 ** Each frame records the revised content of a single page from the
46313 ** database file.  All changes to the database are recorded by writing
46314 ** frames into the WAL.  Transactions commit when a frame is written that
46315 ** contains a commit marker.  A single WAL can and usually does record 
46316 ** multiple transactions.  Periodically, the content of the WAL is
46317 ** transferred back into the database file in an operation called a
46318 ** "checkpoint".
46319 **
46320 ** A single WAL file can be used multiple times.  In other words, the
46321 ** WAL can fill up with frames and then be checkpointed and then new
46322 ** frames can overwrite the old ones.  A WAL always grows from beginning
46323 ** toward the end.  Checksums and counters attached to each frame are
46324 ** used to determine which frames within the WAL are valid and which
46325 ** are leftovers from prior checkpoints.
46326 **
46327 ** The WAL header is 32 bytes in size and consists of the following eight
46328 ** big-endian 32-bit unsigned integer values:
46329 **
46330 **     0: Magic number.  0x377f0682 or 0x377f0683
46331 **     4: File format version.  Currently 3007000
46332 **     8: Database page size.  Example: 1024
46333 **    12: Checkpoint sequence number
46334 **    16: Salt-1, random integer incremented with each checkpoint
46335 **    20: Salt-2, a different random integer changing with each ckpt
46336 **    24: Checksum-1 (first part of checksum for first 24 bytes of header).
46337 **    28: Checksum-2 (second part of checksum for first 24 bytes of header).
46338 **
46339 ** Immediately following the wal-header are zero or more frames. Each
46340 ** frame consists of a 24-byte frame-header followed by a <page-size> bytes
46341 ** of page data. The frame-header is six big-endian 32-bit unsigned 
46342 ** integer values, as follows:
46343 **
46344 **     0: Page number.
46345 **     4: For commit records, the size of the database image in pages 
46346 **        after the commit. For all other records, zero.
46347 **     8: Salt-1 (copied from the header)
46348 **    12: Salt-2 (copied from the header)
46349 **    16: Checksum-1.
46350 **    20: Checksum-2.
46351 **
46352 ** A frame is considered valid if and only if the following conditions are
46353 ** true:
46354 **
46355 **    (1) The salt-1 and salt-2 values in the frame-header match
46356 **        salt values in the wal-header
46357 **
46358 **    (2) The checksum values in the final 8 bytes of the frame-header
46359 **        exactly match the checksum computed consecutively on the
46360 **        WAL header and the first 8 bytes and the content of all frames
46361 **        up to and including the current frame.
46362 **
46363 ** The checksum is computed using 32-bit big-endian integers if the
46364 ** magic number in the first 4 bytes of the WAL is 0x377f0683 and it
46365 ** is computed using little-endian if the magic number is 0x377f0682.
46366 ** The checksum values are always stored in the frame header in a
46367 ** big-endian format regardless of which byte order is used to compute
46368 ** the checksum.  The checksum is computed by interpreting the input as
46369 ** an even number of unsigned 32-bit integers: x[0] through x[N].  The
46370 ** algorithm used for the checksum is as follows:
46371 ** 
46372 **   for i from 0 to n-1 step 2:
46373 **     s0 += x[i] + s1;
46374 **     s1 += x[i+1] + s0;
46375 **   endfor
46376 **
46377 ** Note that s0 and s1 are both weighted checksums using fibonacci weights
46378 ** in reverse order (the largest fibonacci weight occurs on the first element
46379 ** of the sequence being summed.)  The s1 value spans all 32-bit 
46380 ** terms of the sequence whereas s0 omits the final term.
46381 **
46382 ** On a checkpoint, the WAL is first VFS.xSync-ed, then valid content of the
46383 ** WAL is transferred into the database, then the database is VFS.xSync-ed.
46384 ** The VFS.xSync operations serve as write barriers - all writes launched
46385 ** before the xSync must complete before any write that launches after the
46386 ** xSync begins.
46387 **
46388 ** After each checkpoint, the salt-1 value is incremented and the salt-2
46389 ** value is randomized.  This prevents old and new frames in the WAL from
46390 ** being considered valid at the same time and being checkpointing together
46391 ** following a crash.
46392 **
46393 ** READER ALGORITHM
46394 **
46395 ** To read a page from the database (call it page number P), a reader
46396 ** first checks the WAL to see if it contains page P.  If so, then the
46397 ** last valid instance of page P that is a followed by a commit frame
46398 ** or is a commit frame itself becomes the value read.  If the WAL
46399 ** contains no copies of page P that are valid and which are a commit
46400 ** frame or are followed by a commit frame, then page P is read from
46401 ** the database file.
46402 **
46403 ** To start a read transaction, the reader records the index of the last
46404 ** valid frame in the WAL.  The reader uses this recorded "mxFrame" value
46405 ** for all subsequent read operations.  New transactions can be appended
46406 ** to the WAL, but as long as the reader uses its original mxFrame value
46407 ** and ignores the newly appended content, it will see a consistent snapshot
46408 ** of the database from a single point in time.  This technique allows
46409 ** multiple concurrent readers to view different versions of the database
46410 ** content simultaneously.
46411 **
46412 ** The reader algorithm in the previous paragraphs works correctly, but 
46413 ** because frames for page P can appear anywhere within the WAL, the
46414 ** reader has to scan the entire WAL looking for page P frames.  If the
46415 ** WAL is large (multiple megabytes is typical) that scan can be slow,
46416 ** and read performance suffers.  To overcome this problem, a separate
46417 ** data structure called the wal-index is maintained to expedite the
46418 ** search for frames of a particular page.
46419 ** 
46420 ** WAL-INDEX FORMAT
46421 **
46422 ** Conceptually, the wal-index is shared memory, though VFS implementations
46423 ** might choose to implement the wal-index using a mmapped file.  Because
46424 ** the wal-index is shared memory, SQLite does not support journal_mode=WAL 
46425 ** on a network filesystem.  All users of the database must be able to
46426 ** share memory.
46427 **
46428 ** The wal-index is transient.  After a crash, the wal-index can (and should
46429 ** be) reconstructed from the original WAL file.  In fact, the VFS is required
46430 ** to either truncate or zero the header of the wal-index when the last
46431 ** connection to it closes.  Because the wal-index is transient, it can
46432 ** use an architecture-specific format; it does not have to be cross-platform.
46433 ** Hence, unlike the database and WAL file formats which store all values
46434 ** as big endian, the wal-index can store multi-byte values in the native
46435 ** byte order of the host computer.
46436 **
46437 ** The purpose of the wal-index is to answer this question quickly:  Given
46438 ** a page number P and a maximum frame index M, return the index of the 
46439 ** last frame in the wal before frame M for page P in the WAL, or return
46440 ** NULL if there are no frames for page P in the WAL prior to M.
46441 **
46442 ** The wal-index consists of a header region, followed by an one or
46443 ** more index blocks.  
46444 **
46445 ** The wal-index header contains the total number of frames within the WAL
46446 ** in the mxFrame field.
46447 **
46448 ** Each index block except for the first contains information on 
46449 ** HASHTABLE_NPAGE frames. The first index block contains information on
46450 ** HASHTABLE_NPAGE_ONE frames. The values of HASHTABLE_NPAGE_ONE and 
46451 ** HASHTABLE_NPAGE are selected so that together the wal-index header and
46452 ** first index block are the same size as all other index blocks in the
46453 ** wal-index.
46454 **
46455 ** Each index block contains two sections, a page-mapping that contains the
46456 ** database page number associated with each wal frame, and a hash-table 
46457 ** that allows readers to query an index block for a specific page number.
46458 ** The page-mapping is an array of HASHTABLE_NPAGE (or HASHTABLE_NPAGE_ONE
46459 ** for the first index block) 32-bit page numbers. The first entry in the 
46460 ** first index-block contains the database page number corresponding to the
46461 ** first frame in the WAL file. The first entry in the second index block
46462 ** in the WAL file corresponds to the (HASHTABLE_NPAGE_ONE+1)th frame in
46463 ** the log, and so on.
46464 **
46465 ** The last index block in a wal-index usually contains less than the full
46466 ** complement of HASHTABLE_NPAGE (or HASHTABLE_NPAGE_ONE) page-numbers,
46467 ** depending on the contents of the WAL file. This does not change the
46468 ** allocated size of the page-mapping array - the page-mapping array merely
46469 ** contains unused entries.
46470 **
46471 ** Even without using the hash table, the last frame for page P
46472 ** can be found by scanning the page-mapping sections of each index block
46473 ** starting with the last index block and moving toward the first, and
46474 ** within each index block, starting at the end and moving toward the
46475 ** beginning.  The first entry that equals P corresponds to the frame
46476 ** holding the content for that page.
46477 **
46478 ** The hash table consists of HASHTABLE_NSLOT 16-bit unsigned integers.
46479 ** HASHTABLE_NSLOT = 2*HASHTABLE_NPAGE, and there is one entry in the
46480 ** hash table for each page number in the mapping section, so the hash 
46481 ** table is never more than half full.  The expected number of collisions 
46482 ** prior to finding a match is 1.  Each entry of the hash table is an
46483 ** 1-based index of an entry in the mapping section of the same
46484 ** index block.   Let K be the 1-based index of the largest entry in
46485 ** the mapping section.  (For index blocks other than the last, K will
46486 ** always be exactly HASHTABLE_NPAGE (4096) and for the last index block
46487 ** K will be (mxFrame%HASHTABLE_NPAGE).)  Unused slots of the hash table
46488 ** contain a value of 0.
46489 **
46490 ** To look for page P in the hash table, first compute a hash iKey on
46491 ** P as follows:
46492 **
46493 **      iKey = (P * 383) % HASHTABLE_NSLOT
46494 **
46495 ** Then start scanning entries of the hash table, starting with iKey
46496 ** (wrapping around to the beginning when the end of the hash table is
46497 ** reached) until an unused hash slot is found. Let the first unused slot
46498 ** be at index iUnused.  (iUnused might be less than iKey if there was
46499 ** wrap-around.) Because the hash table is never more than half full,
46500 ** the search is guaranteed to eventually hit an unused entry.  Let 
46501 ** iMax be the value between iKey and iUnused, closest to iUnused,
46502 ** where aHash[iMax]==P.  If there is no iMax entry (if there exists
46503 ** no hash slot such that aHash[i]==p) then page P is not in the
46504 ** current index block.  Otherwise the iMax-th mapping entry of the
46505 ** current index block corresponds to the last entry that references 
46506 ** page P.
46507 **
46508 ** A hash search begins with the last index block and moves toward the
46509 ** first index block, looking for entries corresponding to page P.  On
46510 ** average, only two or three slots in each index block need to be
46511 ** examined in order to either find the last entry for page P, or to
46512 ** establish that no such entry exists in the block.  Each index block
46513 ** holds over 4000 entries.  So two or three index blocks are sufficient
46514 ** to cover a typical 10 megabyte WAL file, assuming 1K pages.  8 or 10
46515 ** comparisons (on average) suffice to either locate a frame in the
46516 ** WAL or to establish that the frame does not exist in the WAL.  This
46517 ** is much faster than scanning the entire 10MB WAL.
46518 **
46519 ** Note that entries are added in order of increasing K.  Hence, one
46520 ** reader might be using some value K0 and a second reader that started
46521 ** at a later time (after additional transactions were added to the WAL
46522 ** and to the wal-index) might be using a different value K1, where K1>K0.
46523 ** Both readers can use the same hash table and mapping section to get
46524 ** the correct result.  There may be entries in the hash table with
46525 ** K>K0 but to the first reader, those entries will appear to be unused
46526 ** slots in the hash table and so the first reader will get an answer as
46527 ** if no values greater than K0 had ever been inserted into the hash table
46528 ** in the first place - which is what reader one wants.  Meanwhile, the
46529 ** second reader using K1 will see additional values that were inserted
46530 ** later, which is exactly what reader two wants.  
46531 **
46532 ** When a rollback occurs, the value of K is decreased. Hash table entries
46533 ** that correspond to frames greater than the new K value are removed
46534 ** from the hash table at this point.
46535 */
46536 #ifndef SQLITE_OMIT_WAL
46537 
46538 
46539 /*
46540 ** Trace output macros
46541 */
46542 #if defined(SQLITE_TEST) && defined(SQLITE_DEBUG)
46543 SQLITE_PRIVATE int sqlite3WalTrace = 0;
46544 # define WALTRACE(X)  if(sqlite3WalTrace) sqlite3DebugPrintf X
46545 #else
46546 # define WALTRACE(X)
46547 #endif
46548 
46549 /*
46550 ** The maximum (and only) versions of the wal and wal-index formats
46551 ** that may be interpreted by this version of SQLite.
46552 **
46553 ** If a client begins recovering a WAL file and finds that (a) the checksum
46554 ** values in the wal-header are correct and (b) the version field is not
46555 ** WAL_MAX_VERSION, recovery fails and SQLite returns SQLITE_CANTOPEN.
46556 **
46557 ** Similarly, if a client successfully reads a wal-index header (i.e. the 
46558 ** checksum test is successful) and finds that the version field is not
46559 ** WALINDEX_MAX_VERSION, then no read-transaction is opened and SQLite
46560 ** returns SQLITE_CANTOPEN.
46561 */
46562 #define WAL_MAX_VERSION      3007000
46563 #define WALINDEX_MAX_VERSION 3007000
46564 
46565 /*
46566 ** Indices of various locking bytes.   WAL_NREADER is the number
46567 ** of available reader locks and should be at least 3.
46568 */
46569 #define WAL_WRITE_LOCK         0
46570 #define WAL_ALL_BUT_WRITE      1
46571 #define WAL_CKPT_LOCK          1
46572 #define WAL_RECOVER_LOCK       2
46573 #define WAL_READ_LOCK(I)       (3+(I))
46574 #define WAL_NREADER            (SQLITE_SHM_NLOCK-3)
46575 
46576 
46577 /* Object declarations */
46578 typedef struct WalIndexHdr WalIndexHdr;
46579 typedef struct WalIterator WalIterator;
46580 typedef struct WalCkptInfo WalCkptInfo;
46581 
46582 
46583 /*
46584 ** The following object holds a copy of the wal-index header content.
46585 **
46586 ** The actual header in the wal-index consists of two copies of this
46587 ** object.
46588 **
46589 ** The szPage value can be any power of 2 between 512 and 32768, inclusive.
46590 ** Or it can be 1 to represent a 65536-byte page.  The latter case was
46591 ** added in 3.7.1 when support for 64K pages was added.  
46592 */
46593 struct WalIndexHdr {
46594   u32 iVersion;                   /* Wal-index version */
46595   u32 unused;                     /* Unused (padding) field */
46596   u32 iChange;                    /* Counter incremented each transaction */
46597   u8 isInit;                      /* 1 when initialized */
46598   u8 bigEndCksum;                 /* True if checksums in WAL are big-endian */
46599   u16 szPage;                     /* Database page size in bytes. 1==64K */
46600   u32 mxFrame;                    /* Index of last valid frame in the WAL */
46601   u32 nPage;                      /* Size of database in pages */
46602   u32 aFrameCksum[2];             /* Checksum of last frame in log */
46603   u32 aSalt[2];                   /* Two salt values copied from WAL header */
46604   u32 aCksum[2];                  /* Checksum over all prior fields */
46605 };
46606 
46607 /*
46608 ** A copy of the following object occurs in the wal-index immediately
46609 ** following the second copy of the WalIndexHdr.  This object stores
46610 ** information used by checkpoint.
46611 **
46612 ** nBackfill is the number of frames in the WAL that have been written
46613 ** back into the database. (We call the act of moving content from WAL to
46614 ** database "backfilling".)  The nBackfill number is never greater than
46615 ** WalIndexHdr.mxFrame.  nBackfill can only be increased by threads
46616 ** holding the WAL_CKPT_LOCK lock (which includes a recovery thread).
46617 ** However, a WAL_WRITE_LOCK thread can move the value of nBackfill from
46618 ** mxFrame back to zero when the WAL is reset.
46619 **
46620 ** There is one entry in aReadMark[] for each reader lock.  If a reader
46621 ** holds read-lock K, then the value in aReadMark[K] is no greater than
46622 ** the mxFrame for that reader.  The value READMARK_NOT_USED (0xffffffff)
46623 ** for any aReadMark[] means that entry is unused.  aReadMark[0] is 
46624 ** a special case; its value is never used and it exists as a place-holder
46625 ** to avoid having to offset aReadMark[] indexs by one.  Readers holding
46626 ** WAL_READ_LOCK(0) always ignore the entire WAL and read all content
46627 ** directly from the database.
46628 **
46629 ** The value of aReadMark[K] may only be changed by a thread that
46630 ** is holding an exclusive lock on WAL_READ_LOCK(K).  Thus, the value of
46631 ** aReadMark[K] cannot changed while there is a reader is using that mark
46632 ** since the reader will be holding a shared lock on WAL_READ_LOCK(K).
46633 **
46634 ** The checkpointer may only transfer frames from WAL to database where
46635 ** the frame numbers are less than or equal to every aReadMark[] that is
46636 ** in use (that is, every aReadMark[j] for which there is a corresponding
46637 ** WAL_READ_LOCK(j)).  New readers (usually) pick the aReadMark[] with the
46638 ** largest value and will increase an unused aReadMark[] to mxFrame if there
46639 ** is not already an aReadMark[] equal to mxFrame.  The exception to the
46640 ** previous sentence is when nBackfill equals mxFrame (meaning that everything
46641 ** in the WAL has been backfilled into the database) then new readers
46642 ** will choose aReadMark[0] which has value 0 and hence such reader will
46643 ** get all their all content directly from the database file and ignore 
46644 ** the WAL.
46645 **
46646 ** Writers normally append new frames to the end of the WAL.  However,
46647 ** if nBackfill equals mxFrame (meaning that all WAL content has been
46648 ** written back into the database) and if no readers are using the WAL
46649 ** (in other words, if there are no WAL_READ_LOCK(i) where i>0) then
46650 ** the writer will first "reset" the WAL back to the beginning and start
46651 ** writing new content beginning at frame 1.
46652 **
46653 ** We assume that 32-bit loads are atomic and so no locks are needed in
46654 ** order to read from any aReadMark[] entries.
46655 */
46656 struct WalCkptInfo {
46657   u32 nBackfill;                  /* Number of WAL frames backfilled into DB */
46658   u32 aReadMark[WAL_NREADER];     /* Reader marks */
46659 };
46660 #define READMARK_NOT_USED  0xffffffff
46661 
46662 
46663 /* A block of WALINDEX_LOCK_RESERVED bytes beginning at
46664 ** WALINDEX_LOCK_OFFSET is reserved for locks. Since some systems
46665 ** only support mandatory file-locks, we do not read or write data
46666 ** from the region of the file on which locks are applied.
46667 */
46668 #define WALINDEX_LOCK_OFFSET   (sizeof(WalIndexHdr)*2 + sizeof(WalCkptInfo))
46669 #define WALINDEX_LOCK_RESERVED 16
46670 #define WALINDEX_HDR_SIZE      (WALINDEX_LOCK_OFFSET+WALINDEX_LOCK_RESERVED)
46671 
46672 /* Size of header before each frame in wal */
46673 #define WAL_FRAME_HDRSIZE 24
46674 
46675 /* Size of write ahead log header, including checksum. */
46676 /* #define WAL_HDRSIZE 24 */
46677 #define WAL_HDRSIZE 32
46678 
46679 /* WAL magic value. Either this value, or the same value with the least
46680 ** significant bit also set (WAL_MAGIC | 0x00000001) is stored in 32-bit
46681 ** big-endian format in the first 4 bytes of a WAL file.
46682 **
46683 ** If the LSB is set, then the checksums for each frame within the WAL
46684 ** file are calculated by treating all data as an array of 32-bit 
46685 ** big-endian words. Otherwise, they are calculated by interpreting 
46686 ** all data as 32-bit little-endian words.
46687 */
46688 #define WAL_MAGIC 0x377f0682
46689 
46690 /*
46691 ** Return the offset of frame iFrame in the write-ahead log file, 
46692 ** assuming a database page size of szPage bytes. The offset returned
46693 ** is to the start of the write-ahead log frame-header.
46694 */
46695 #define walFrameOffset(iFrame, szPage) (                               \
46696   WAL_HDRSIZE + ((iFrame)-1)*(i64)((szPage)+WAL_FRAME_HDRSIZE)         \
46697 )
46698 
46699 /*
46700 ** An open write-ahead log file is represented by an instance of the
46701 ** following object.
46702 */
46703 struct Wal {
46704   sqlite3_vfs *pVfs;         /* The VFS used to create pDbFd */
46705   sqlite3_file *pDbFd;       /* File handle for the database file */
46706   sqlite3_file *pWalFd;      /* File handle for WAL file */
46707   u32 iCallback;             /* Value to pass to log callback (or 0) */
46708   i64 mxWalSize;             /* Truncate WAL to this size upon reset */
46709   int nWiData;               /* Size of array apWiData */
46710   int szFirstBlock;          /* Size of first block written to WAL file */
46711   volatile u32 **apWiData;   /* Pointer to wal-index content in memory */
46712   u32 szPage;                /* Database page size */
46713   i16 readLock;              /* Which read lock is being held.  -1 for none */
46714   u8 syncFlags;              /* Flags to use to sync header writes */
46715   u8 exclusiveMode;          /* Non-zero if connection is in exclusive mode */
46716   u8 writeLock;              /* True if in a write transaction */
46717   u8 ckptLock;               /* True if holding a checkpoint lock */
46718   u8 readOnly;               /* WAL_RDWR, WAL_RDONLY, or WAL_SHM_RDONLY */
46719   u8 truncateOnCommit;       /* True to truncate WAL file on commit */
46720   u8 syncHeader;             /* Fsync the WAL header if true */
46721   u8 padToSectorBoundary;    /* Pad transactions out to the next sector */
46722   WalIndexHdr hdr;           /* Wal-index header for current transaction */
46723   const char *zWalName;      /* Name of WAL file */
46724   u32 nCkpt;                 /* Checkpoint sequence counter in the wal-header */
46725 #ifdef SQLITE_DEBUG
46726   u8 lockError;              /* True if a locking error has occurred */
46727 #endif
46728 };
46729 
46730 /*
46731 ** Candidate values for Wal.exclusiveMode.
46732 */
46733 #define WAL_NORMAL_MODE     0
46734 #define WAL_EXCLUSIVE_MODE  1     
46735 #define WAL_HEAPMEMORY_MODE 2
46736 
46737 /*
46738 ** Possible values for WAL.readOnly
46739 */
46740 #define WAL_RDWR        0    /* Normal read/write connection */
46741 #define WAL_RDONLY      1    /* The WAL file is readonly */
46742 #define WAL_SHM_RDONLY  2    /* The SHM file is readonly */
46743 
46744 /*
46745 ** Each page of the wal-index mapping contains a hash-table made up of
46746 ** an array of HASHTABLE_NSLOT elements of the following type.
46747 */
46748 typedef u16 ht_slot;
46749 
46750 /*
46751 ** This structure is used to implement an iterator that loops through
46752 ** all frames in the WAL in database page order. Where two or more frames
46753 ** correspond to the same database page, the iterator visits only the 
46754 ** frame most recently written to the WAL (in other words, the frame with
46755 ** the largest index).
46756 **
46757 ** The internals of this structure are only accessed by:
46758 **
46759 **   walIteratorInit() - Create a new iterator,
46760 **   walIteratorNext() - Step an iterator,
46761 **   walIteratorFree() - Free an iterator.
46762 **
46763 ** This functionality is used by the checkpoint code (see walCheckpoint()).
46764 */
46765 struct WalIterator {
46766   int iPrior;                     /* Last result returned from the iterator */
46767   int nSegment;                   /* Number of entries in aSegment[] */
46768   struct WalSegment {
46769     int iNext;                    /* Next slot in aIndex[] not yet returned */
46770     ht_slot *aIndex;              /* i0, i1, i2... such that aPgno[iN] ascend */
46771     u32 *aPgno;                   /* Array of page numbers. */
46772     int nEntry;                   /* Nr. of entries in aPgno[] and aIndex[] */
46773     int iZero;                    /* Frame number associated with aPgno[0] */
46774   } aSegment[1];                  /* One for every 32KB page in the wal-index */
46775 };
46776 
46777 /*
46778 ** Define the parameters of the hash tables in the wal-index file. There
46779 ** is a hash-table following every HASHTABLE_NPAGE page numbers in the
46780 ** wal-index.
46781 **
46782 ** Changing any of these constants will alter the wal-index format and
46783 ** create incompatibilities.
46784 */
46785 #define HASHTABLE_NPAGE      4096                 /* Must be power of 2 */
46786 #define HASHTABLE_HASH_1     383                  /* Should be prime */
46787 #define HASHTABLE_NSLOT      (HASHTABLE_NPAGE*2)  /* Must be a power of 2 */
46788 
46789 /* 
46790 ** The block of page numbers associated with the first hash-table in a
46791 ** wal-index is smaller than usual. This is so that there is a complete
46792 ** hash-table on each aligned 32KB page of the wal-index.
46793 */
46794 #define HASHTABLE_NPAGE_ONE  (HASHTABLE_NPAGE - (WALINDEX_HDR_SIZE/sizeof(u32)))
46795 
46796 /* The wal-index is divided into pages of WALINDEX_PGSZ bytes each. */
46797 #define WALINDEX_PGSZ   (                                         \
46798     sizeof(ht_slot)*HASHTABLE_NSLOT + HASHTABLE_NPAGE*sizeof(u32) \
46799 )
46800 
46801 /*
46802 ** Obtain a pointer to the iPage'th page of the wal-index. The wal-index
46803 ** is broken into pages of WALINDEX_PGSZ bytes. Wal-index pages are
46804 ** numbered from zero.
46805 **
46806 ** If this call is successful, *ppPage is set to point to the wal-index
46807 ** page and SQLITE_OK is returned. If an error (an OOM or VFS error) occurs,
46808 ** then an SQLite error code is returned and *ppPage is set to 0.
46809 */
46810 static int walIndexPage(Wal *pWal, int iPage, volatile u32 **ppPage){
46811   int rc = SQLITE_OK;
46812 
46813   /* Enlarge the pWal->apWiData[] array if required */
46814   if( pWal->nWiData<=iPage ){
46815     int nByte = sizeof(u32*)*(iPage+1);
46816     volatile u32 **apNew;
46817     apNew = (volatile u32 **)sqlite3_realloc((void *)pWal->apWiData, nByte);
46818     if( !apNew ){
46819       *ppPage = 0;
46820       return SQLITE_NOMEM;
46821     }
46822     memset((void*)&apNew[pWal->nWiData], 0,
46823            sizeof(u32*)*(iPage+1-pWal->nWiData));
46824     pWal->apWiData = apNew;
46825     pWal->nWiData = iPage+1;
46826   }
46827 
46828   /* Request a pointer to the required page from the VFS */
46829   if( pWal->apWiData[iPage]==0 ){
46830     if( pWal->exclusiveMode==WAL_HEAPMEMORY_MODE ){
46831       pWal->apWiData[iPage] = (u32 volatile *)sqlite3MallocZero(WALINDEX_PGSZ);
46832       if( !pWal->apWiData[iPage] ) rc = SQLITE_NOMEM;
46833     }else{
46834       rc = sqlite3OsShmMap(pWal->pDbFd, iPage, WALINDEX_PGSZ, 
46835           pWal->writeLock, (void volatile **)&pWal->apWiData[iPage]
46836       );
46837       if( rc==SQLITE_READONLY ){
46838         pWal->readOnly |= WAL_SHM_RDONLY;
46839         rc = SQLITE_OK;
46840       }
46841     }
46842   }
46843 
46844   *ppPage = pWal->apWiData[iPage];
46845   assert( iPage==0 || *ppPage || rc!=SQLITE_OK );
46846   return rc;
46847 }
46848 
46849 /*
46850 ** Return a pointer to the WalCkptInfo structure in the wal-index.
46851 */
46852 static volatile WalCkptInfo *walCkptInfo(Wal *pWal){
46853   assert( pWal->nWiData>0 && pWal->apWiData[0] );
46854   return (volatile WalCkptInfo*)&(pWal->apWiData[0][sizeof(WalIndexHdr)/2]);
46855 }
46856 
46857 /*
46858 ** Return a pointer to the WalIndexHdr structure in the wal-index.
46859 */
46860 static volatile WalIndexHdr *walIndexHdr(Wal *pWal){
46861   assert( pWal->nWiData>0 && pWal->apWiData[0] );
46862   return (volatile WalIndexHdr*)pWal->apWiData[0];
46863 }
46864 
46865 /*
46866 ** The argument to this macro must be of type u32. On a little-endian
46867 ** architecture, it returns the u32 value that results from interpreting
46868 ** the 4 bytes as a big-endian value. On a big-endian architecture, it
46869 ** returns the value that would be produced by intepreting the 4 bytes
46870 ** of the input value as a little-endian integer.
46871 */
46872 #define BYTESWAP32(x) ( \
46873     (((x)&0x000000FF)<<24) + (((x)&0x0000FF00)<<8)  \
46874   + (((x)&0x00FF0000)>>8)  + (((x)&0xFF000000)>>24) \
46875 )
46876 
46877 /*
46878 ** Generate or extend an 8 byte checksum based on the data in 
46879 ** array aByte[] and the initial values of aIn[0] and aIn[1] (or
46880 ** initial values of 0 and 0 if aIn==NULL).
46881 **
46882 ** The checksum is written back into aOut[] before returning.
46883 **
46884 ** nByte must be a positive multiple of 8.
46885 */
46886 static void walChecksumBytes(
46887   int nativeCksum, /* True for native byte-order, false for non-native */
46888   u8 *a,           /* Content to be checksummed */
46889   int nByte,       /* Bytes of content in a[].  Must be a multiple of 8. */
46890   const u32 *aIn,  /* Initial checksum value input */
46891   u32 *aOut        /* OUT: Final checksum value output */
46892 ){
46893   u32 s1, s2;
46894   u32 *aData = (u32 *)a;
46895   u32 *aEnd = (u32 *)&a[nByte];
46896 
46897   if( aIn ){
46898     s1 = aIn[0];
46899     s2 = aIn[1];
46900   }else{
46901     s1 = s2 = 0;
46902   }
46903 
46904   assert( nByte>=8 );
46905   assert( (nByte&0x00000007)==0 );
46906 
46907   if( nativeCksum ){
46908     do {
46909       s1 += *aData++ + s2;
46910       s2 += *aData++ + s1;
46911     }while( aData<aEnd );
46912   }else{
46913     do {
46914       s1 += BYTESWAP32(aData[0]) + s2;
46915       s2 += BYTESWAP32(aData[1]) + s1;
46916       aData += 2;
46917     }while( aData<aEnd );
46918   }
46919 
46920   aOut[0] = s1;
46921   aOut[1] = s2;
46922 }
46923 
46924 static void walShmBarrier(Wal *pWal){
46925   if( pWal->exclusiveMode!=WAL_HEAPMEMORY_MODE ){
46926     sqlite3OsShmBarrier(pWal->pDbFd);
46927   }
46928 }
46929 
46930 /*
46931 ** Write the header information in pWal->hdr into the wal-index.
46932 **
46933 ** The checksum on pWal->hdr is updated before it is written.
46934 */
46935 static void walIndexWriteHdr(Wal *pWal){
46936   volatile WalIndexHdr *aHdr = walIndexHdr(pWal);
46937   const int nCksum = offsetof(WalIndexHdr, aCksum);
46938 
46939   assert( pWal->writeLock );
46940   pWal->hdr.isInit = 1;
46941   pWal->hdr.iVersion = WALINDEX_MAX_VERSION;
46942   walChecksumBytes(1, (u8*)&pWal->hdr, nCksum, 0, pWal->hdr.aCksum);
46943   memcpy((void *)&aHdr[1], (void *)&pWal->hdr, sizeof(WalIndexHdr));
46944   walShmBarrier(pWal);
46945   memcpy((void *)&aHdr[0], (void *)&pWal->hdr, sizeof(WalIndexHdr));
46946 }
46947 
46948 /*
46949 ** This function encodes a single frame header and writes it to a buffer
46950 ** supplied by the caller. A frame-header is made up of a series of 
46951 ** 4-byte big-endian integers, as follows:
46952 **
46953 **     0: Page number.
46954 **     4: For commit records, the size of the database image in pages 
46955 **        after the commit. For all other records, zero.
46956 **     8: Salt-1 (copied from the wal-header)
46957 **    12: Salt-2 (copied from the wal-header)
46958 **    16: Checksum-1.
46959 **    20: Checksum-2.
46960 */
46961 static void walEncodeFrame(
46962   Wal *pWal,                      /* The write-ahead log */
46963   u32 iPage,                      /* Database page number for frame */
46964   u32 nTruncate,                  /* New db size (or 0 for non-commit frames) */
46965   u8 *aData,                      /* Pointer to page data */
46966   u8 *aFrame                      /* OUT: Write encoded frame here */
46967 ){
46968   int nativeCksum;                /* True for native byte-order checksums */
46969   u32 *aCksum = pWal->hdr.aFrameCksum;
46970   assert( WAL_FRAME_HDRSIZE==24 );
46971   sqlite3Put4byte(&aFrame[0], iPage);
46972   sqlite3Put4byte(&aFrame[4], nTruncate);
46973   memcpy(&aFrame[8], pWal->hdr.aSalt, 8);
46974 
46975   nativeCksum = (pWal->hdr.bigEndCksum==SQLITE_BIGENDIAN);
46976   walChecksumBytes(nativeCksum, aFrame, 8, aCksum, aCksum);
46977   walChecksumBytes(nativeCksum, aData, pWal->szPage, aCksum, aCksum);
46978 
46979   sqlite3Put4byte(&aFrame[16], aCksum[0]);
46980   sqlite3Put4byte(&aFrame[20], aCksum[1]);
46981 }
46982 
46983 /*
46984 ** Check to see if the frame with header in aFrame[] and content
46985 ** in aData[] is valid.  If it is a valid frame, fill *piPage and
46986 ** *pnTruncate and return true.  Return if the frame is not valid.
46987 */
46988 static int walDecodeFrame(
46989   Wal *pWal,                      /* The write-ahead log */
46990   u32 *piPage,                    /* OUT: Database page number for frame */
46991   u32 *pnTruncate,                /* OUT: New db size (or 0 if not commit) */
46992   u8 *aData,                      /* Pointer to page data (for checksum) */
46993   u8 *aFrame                      /* Frame data */
46994 ){
46995   int nativeCksum;                /* True for native byte-order checksums */
46996   u32 *aCksum = pWal->hdr.aFrameCksum;
46997   u32 pgno;                       /* Page number of the frame */
46998   assert( WAL_FRAME_HDRSIZE==24 );
46999 
47000   /* A frame is only valid if the salt values in the frame-header
47001   ** match the salt values in the wal-header. 
47002   */
47003   if( memcmp(&pWal->hdr.aSalt, &aFrame[8], 8)!=0 ){
47004     return 0;
47005   }
47006 
47007   /* A frame is only valid if the page number is creater than zero.
47008   */
47009   pgno = sqlite3Get4byte(&aFrame[0]);
47010   if( pgno==0 ){
47011     return 0;
47012   }
47013 
47014   /* A frame is only valid if a checksum of the WAL header,
47015   ** all prior frams, the first 16 bytes of this frame-header, 
47016   ** and the frame-data matches the checksum in the last 8 
47017   ** bytes of this frame-header.
47018   */
47019   nativeCksum = (pWal->hdr.bigEndCksum==SQLITE_BIGENDIAN);
47020   walChecksumBytes(nativeCksum, aFrame, 8, aCksum, aCksum);
47021   walChecksumBytes(nativeCksum, aData, pWal->szPage, aCksum, aCksum);
47022   if( aCksum[0]!=sqlite3Get4byte(&aFrame[16]) 
47023    || aCksum[1]!=sqlite3Get4byte(&aFrame[20]) 
47024   ){
47025     /* Checksum failed. */
47026     return 0;
47027   }
47028 
47029   /* If we reach this point, the frame is valid.  Return the page number
47030   ** and the new database size.
47031   */
47032   *piPage = pgno;
47033   *pnTruncate = sqlite3Get4byte(&aFrame[4]);
47034   return 1;
47035 }
47036 
47037 
47038 #if defined(SQLITE_TEST) && defined(SQLITE_DEBUG)
47039 /*
47040 ** Names of locks.  This routine is used to provide debugging output and is not
47041 ** a part of an ordinary build.
47042 */
47043 static const char *walLockName(int lockIdx){
47044   if( lockIdx==WAL_WRITE_LOCK ){
47045     return "WRITE-LOCK";
47046   }else if( lockIdx==WAL_CKPT_LOCK ){
47047     return "CKPT-LOCK";
47048   }else if( lockIdx==WAL_RECOVER_LOCK ){
47049     return "RECOVER-LOCK";
47050   }else{
47051     static char zName[15];
47052     sqlite3_snprintf(sizeof(zName), zName, "READ-LOCK[%d]",
47053                      lockIdx-WAL_READ_LOCK(0));
47054     return zName;
47055   }
47056 }
47057 #endif /*defined(SQLITE_TEST) || defined(SQLITE_DEBUG) */
47058     
47059 
47060 /*
47061 ** Set or release locks on the WAL.  Locks are either shared or exclusive.
47062 ** A lock cannot be moved directly between shared and exclusive - it must go
47063 ** through the unlocked state first.
47064 **
47065 ** In locking_mode=EXCLUSIVE, all of these routines become no-ops.
47066 */
47067 static int walLockShared(Wal *pWal, int lockIdx){
47068   int rc;
47069   if( pWal->exclusiveMode ) return SQLITE_OK;
47070   rc = sqlite3OsShmLock(pWal->pDbFd, lockIdx, 1,
47071                         SQLITE_SHM_LOCK | SQLITE_SHM_SHARED);
47072   WALTRACE(("WAL%p: acquire SHARED-%s %s\n", pWal,
47073             walLockName(lockIdx), rc ? "failed" : "ok"));
47074   VVA_ONLY( pWal->lockError = (u8)(rc!=SQLITE_OK && rc!=SQLITE_BUSY); )
47075   return rc;
47076 }
47077 static void walUnlockShared(Wal *pWal, int lockIdx){
47078   if( pWal->exclusiveMode ) return;
47079   (void)sqlite3OsShmLock(pWal->pDbFd, lockIdx, 1,
47080                          SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED);
47081   WALTRACE(("WAL%p: release SHARED-%s\n", pWal, walLockName(lockIdx)));
47082 }
47083 static int walLockExclusive(Wal *pWal, int lockIdx, int n){
47084   int rc;
47085   if( pWal->exclusiveMode ) return SQLITE_OK;
47086   rc = sqlite3OsShmLock(pWal->pDbFd, lockIdx, n,
47087                         SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE);
47088   WALTRACE(("WAL%p: acquire EXCLUSIVE-%s cnt=%d %s\n", pWal,
47089             walLockName(lockIdx), n, rc ? "failed" : "ok"));
47090   VVA_ONLY( pWal->lockError = (u8)(rc!=SQLITE_OK && rc!=SQLITE_BUSY); )
47091   return rc;
47092 }
47093 static void walUnlockExclusive(Wal *pWal, int lockIdx, int n){
47094   if( pWal->exclusiveMode ) return;
47095   (void)sqlite3OsShmLock(pWal->pDbFd, lockIdx, n,
47096                          SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE);
47097   WALTRACE(("WAL%p: release EXCLUSIVE-%s cnt=%d\n", pWal,
47098              walLockName(lockIdx), n));
47099 }
47100 
47101 /*
47102 ** Compute a hash on a page number.  The resulting hash value must land
47103 ** between 0 and (HASHTABLE_NSLOT-1).  The walHashNext() function advances
47104 ** the hash to the next value in the event of a collision.
47105 */
47106 static int walHash(u32 iPage){
47107   assert( iPage>0 );
47108   assert( (HASHTABLE_NSLOT & (HASHTABLE_NSLOT-1))==0 );
47109   return (iPage*HASHTABLE_HASH_1) & (HASHTABLE_NSLOT-1);
47110 }
47111 static int walNextHash(int iPriorHash){
47112   return (iPriorHash+1)&(HASHTABLE_NSLOT-1);
47113 }
47114 
47115 /* 
47116 ** Return pointers to the hash table and page number array stored on
47117 ** page iHash of the wal-index. The wal-index is broken into 32KB pages
47118 ** numbered starting from 0.
47119 **
47120 ** Set output variable *paHash to point to the start of the hash table
47121 ** in the wal-index file. Set *piZero to one less than the frame 
47122 ** number of the first frame indexed by this hash table. If a
47123 ** slot in the hash table is set to N, it refers to frame number 
47124 ** (*piZero+N) in the log.
47125 **
47126 ** Finally, set *paPgno so that *paPgno[1] is the page number of the
47127 ** first frame indexed by the hash table, frame (*piZero+1).
47128 */
47129 static int walHashGet(
47130   Wal *pWal,                      /* WAL handle */
47131   int iHash,                      /* Find the iHash'th table */
47132   volatile ht_slot **paHash,      /* OUT: Pointer to hash index */
47133   volatile u32 **paPgno,          /* OUT: Pointer to page number array */
47134   u32 *piZero                     /* OUT: Frame associated with *paPgno[0] */
47135 ){
47136   int rc;                         /* Return code */
47137   volatile u32 *aPgno;
47138 
47139   rc = walIndexPage(pWal, iHash, &aPgno);
47140   assert( rc==SQLITE_OK || iHash>0 );
47141 
47142   if( rc==SQLITE_OK ){
47143     u32 iZero;
47144     volatile ht_slot *aHash;
47145 
47146     aHash = (volatile ht_slot *)&aPgno[HASHTABLE_NPAGE];
47147     if( iHash==0 ){
47148       aPgno = &aPgno[WALINDEX_HDR_SIZE/sizeof(u32)];
47149       iZero = 0;
47150     }else{
47151       iZero = HASHTABLE_NPAGE_ONE + (iHash-1)*HASHTABLE_NPAGE;
47152     }
47153   
47154     *paPgno = &aPgno[-1];
47155     *paHash = aHash;
47156     *piZero = iZero;
47157   }
47158   return rc;
47159 }
47160 
47161 /*
47162 ** Return the number of the wal-index page that contains the hash-table
47163 ** and page-number array that contain entries corresponding to WAL frame
47164 ** iFrame. The wal-index is broken up into 32KB pages. Wal-index pages 
47165 ** are numbered starting from 0.
47166 */
47167 static int walFramePage(u32 iFrame){
47168   int iHash = (iFrame+HASHTABLE_NPAGE-HASHTABLE_NPAGE_ONE-1) / HASHTABLE_NPAGE;
47169   assert( (iHash==0 || iFrame>HASHTABLE_NPAGE_ONE)
47170        && (iHash>=1 || iFrame<=HASHTABLE_NPAGE_ONE)
47171        && (iHash<=1 || iFrame>(HASHTABLE_NPAGE_ONE+HASHTABLE_NPAGE))
47172        && (iHash>=2 || iFrame<=HASHTABLE_NPAGE_ONE+HASHTABLE_NPAGE)
47173        && (iHash<=2 || iFrame>(HASHTABLE_NPAGE_ONE+2*HASHTABLE_NPAGE))
47174   );
47175   return iHash;
47176 }
47177 
47178 /*
47179 ** Return the page number associated with frame iFrame in this WAL.
47180 */
47181 static u32 walFramePgno(Wal *pWal, u32 iFrame){
47182   int iHash = walFramePage(iFrame);
47183   if( iHash==0 ){
47184     return pWal->apWiData[0][WALINDEX_HDR_SIZE/sizeof(u32) + iFrame - 1];
47185   }
47186   return pWal->apWiData[iHash][(iFrame-1-HASHTABLE_NPAGE_ONE)%HASHTABLE_NPAGE];
47187 }
47188 
47189 /*
47190 ** Remove entries from the hash table that point to WAL slots greater
47191 ** than pWal->hdr.mxFrame.
47192 **
47193 ** This function is called whenever pWal->hdr.mxFrame is decreased due
47194 ** to a rollback or savepoint.
47195 **
47196 ** At most only the hash table containing pWal->hdr.mxFrame needs to be
47197 ** updated.  Any later hash tables will be automatically cleared when
47198 ** pWal->hdr.mxFrame advances to the point where those hash tables are
47199 ** actually needed.
47200 */
47201 static void walCleanupHash(Wal *pWal){
47202   volatile ht_slot *aHash = 0;    /* Pointer to hash table to clear */
47203   volatile u32 *aPgno = 0;        /* Page number array for hash table */
47204   u32 iZero = 0;                  /* frame == (aHash[x]+iZero) */
47205   int iLimit = 0;                 /* Zero values greater than this */
47206   int nByte;                      /* Number of bytes to zero in aPgno[] */
47207   int i;                          /* Used to iterate through aHash[] */
47208 
47209   assert( pWal->writeLock );
47210   testcase( pWal->hdr.mxFrame==HASHTABLE_NPAGE_ONE-1 );
47211   testcase( pWal->hdr.mxFrame==HASHTABLE_NPAGE_ONE );
47212   testcase( pWal->hdr.mxFrame==HASHTABLE_NPAGE_ONE+1 );
47213 
47214   if( pWal->hdr.mxFrame==0 ) return;
47215 
47216   /* Obtain pointers to the hash-table and page-number array containing 
47217   ** the entry that corresponds to frame pWal->hdr.mxFrame. It is guaranteed
47218   ** that the page said hash-table and array reside on is already mapped.
47219   */
47220   assert( pWal->nWiData>walFramePage(pWal->hdr.mxFrame) );
47221   assert( pWal->apWiData[walFramePage(pWal->hdr.mxFrame)] );
47222   walHashGet(pWal, walFramePage(pWal->hdr.mxFrame), &aHash, &aPgno, &iZero);
47223 
47224   /* Zero all hash-table entries that correspond to frame numbers greater
47225   ** than pWal->hdr.mxFrame.
47226   */
47227   iLimit = pWal->hdr.mxFrame - iZero;
47228   assert( iLimit>0 );
47229   for(i=0; i<HASHTABLE_NSLOT; i++){
47230     if( aHash[i]>iLimit ){
47231       aHash[i] = 0;
47232     }
47233   }
47234   
47235   /* Zero the entries in the aPgno array that correspond to frames with
47236   ** frame numbers greater than pWal->hdr.mxFrame. 
47237   */
47238   nByte = (int)((char *)aHash - (char *)&aPgno[iLimit+1]);
47239   memset((void *)&aPgno[iLimit+1], 0, nByte);
47240 
47241 #ifdef SQLITE_ENABLE_EXPENSIVE_ASSERT
47242   /* Verify that the every entry in the mapping region is still reachable
47243   ** via the hash table even after the cleanup.
47244   */
47245   if( iLimit ){
47246     int i;           /* Loop counter */
47247     int iKey;        /* Hash key */
47248     for(i=1; i<=iLimit; i++){
47249       for(iKey=walHash(aPgno[i]); aHash[iKey]; iKey=walNextHash(iKey)){
47250         if( aHash[iKey]==i ) break;
47251       }
47252       assert( aHash[iKey]==i );
47253     }
47254   }
47255 #endif /* SQLITE_ENABLE_EXPENSIVE_ASSERT */
47256 }
47257 
47258 
47259 /*
47260 ** Set an entry in the wal-index that will map database page number
47261 ** pPage into WAL frame iFrame.
47262 */
47263 static int walIndexAppend(Wal *pWal, u32 iFrame, u32 iPage){
47264   int rc;                         /* Return code */
47265   u32 iZero = 0;                  /* One less than frame number of aPgno[1] */
47266   volatile u32 *aPgno = 0;        /* Page number array */
47267   volatile ht_slot *aHash = 0;    /* Hash table */
47268 
47269   rc = walHashGet(pWal, walFramePage(iFrame), &aHash, &aPgno, &iZero);
47270 
47271   /* Assuming the wal-index file was successfully mapped, populate the
47272   ** page number array and hash table entry.
47273   */
47274   if( rc==SQLITE_OK ){
47275     int iKey;                     /* Hash table key */
47276     int idx;                      /* Value to write to hash-table slot */
47277     int nCollide;                 /* Number of hash collisions */
47278 
47279     idx = iFrame - iZero;
47280     assert( idx <= HASHTABLE_NSLOT/2 + 1 );
47281     
47282     /* If this is the first entry to be added to this hash-table, zero the
47283     ** entire hash table and aPgno[] array before proceding. 
47284     */
47285     if( idx==1 ){
47286       int nByte = (int)((u8 *)&aHash[HASHTABLE_NSLOT] - (u8 *)&aPgno[1]);
47287       memset((void*)&aPgno[1], 0, nByte);
47288     }
47289 
47290     /* If the entry in aPgno[] is already set, then the previous writer
47291     ** must have exited unexpectedly in the middle of a transaction (after
47292     ** writing one or more dirty pages to the WAL to free up memory). 
47293     ** Remove the remnants of that writers uncommitted transaction from 
47294     ** the hash-table before writing any new entries.
47295     */
47296     if( aPgno[idx] ){
47297       walCleanupHash(pWal);
47298       assert( !aPgno[idx] );
47299     }
47300 
47301     /* Write the aPgno[] array entry and the hash-table slot. */
47302     nCollide = idx;
47303     for(iKey=walHash(iPage); aHash[iKey]; iKey=walNextHash(iKey)){
47304       if( (nCollide--)==0 ) return SQLITE_CORRUPT_BKPT;
47305     }
47306     aPgno[idx] = iPage;
47307     aHash[iKey] = (ht_slot)idx;
47308 
47309 #ifdef SQLITE_ENABLE_EXPENSIVE_ASSERT
47310     /* Verify that the number of entries in the hash table exactly equals
47311     ** the number of entries in the mapping region.
47312     */
47313     {
47314       int i;           /* Loop counter */
47315       int nEntry = 0;  /* Number of entries in the hash table */
47316       for(i=0; i<HASHTABLE_NSLOT; i++){ if( aHash[i] ) nEntry++; }
47317       assert( nEntry==idx );
47318     }
47319 
47320     /* Verify that the every entry in the mapping region is reachable
47321     ** via the hash table.  This turns out to be a really, really expensive
47322     ** thing to check, so only do this occasionally - not on every
47323     ** iteration.
47324     */
47325     if( (idx&0x3ff)==0 ){
47326       int i;           /* Loop counter */
47327       for(i=1; i<=idx; i++){
47328         for(iKey=walHash(aPgno[i]); aHash[iKey]; iKey=walNextHash(iKey)){
47329           if( aHash[iKey]==i ) break;
47330         }
47331         assert( aHash[iKey]==i );
47332       }
47333     }
47334 #endif /* SQLITE_ENABLE_EXPENSIVE_ASSERT */
47335   }
47336 
47337 
47338   return rc;
47339 }
47340 
47341 
47342 /*
47343 ** Recover the wal-index by reading the write-ahead log file. 
47344 **
47345 ** This routine first tries to establish an exclusive lock on the
47346 ** wal-index to prevent other threads/processes from doing anything
47347 ** with the WAL or wal-index while recovery is running.  The
47348 ** WAL_RECOVER_LOCK is also held so that other threads will know
47349 ** that this thread is running recovery.  If unable to establish
47350 ** the necessary locks, this routine returns SQLITE_BUSY.
47351 */
47352 static int walIndexRecover(Wal *pWal){
47353   int rc;                         /* Return Code */
47354   i64 nSize;                      /* Size of log file */
47355   u32 aFrameCksum[2] = {0, 0};
47356   int iLock;                      /* Lock offset to lock for checkpoint */
47357   int nLock;                      /* Number of locks to hold */
47358 
47359   /* Obtain an exclusive lock on all byte in the locking range not already
47360   ** locked by the caller. The caller is guaranteed to have locked the
47361   ** WAL_WRITE_LOCK byte, and may have also locked the WAL_CKPT_LOCK byte.
47362   ** If successful, the same bytes that are locked here are unlocked before
47363   ** this function returns.
47364   */
47365   assert( pWal->ckptLock==1 || pWal->ckptLock==0 );
47366   assert( WAL_ALL_BUT_WRITE==WAL_WRITE_LOCK+1 );
47367   assert( WAL_CKPT_LOCK==WAL_ALL_BUT_WRITE );
47368   assert( pWal->writeLock );
47369   iLock = WAL_ALL_BUT_WRITE + pWal->ckptLock;
47370   nLock = SQLITE_SHM_NLOCK - iLock;
47371   rc = walLockExclusive(pWal, iLock, nLock);
47372   if( rc ){
47373     return rc;
47374   }
47375   WALTRACE(("WAL%p: recovery begin...\n", pWal));
47376 
47377   memset(&pWal->hdr, 0, sizeof(WalIndexHdr));
47378 
47379   rc = sqlite3OsFileSize(pWal->pWalFd, &nSize);
47380   if( rc!=SQLITE_OK ){
47381     goto recovery_error;
47382   }
47383 
47384   if( nSize>WAL_HDRSIZE ){
47385     u8 aBuf[WAL_HDRSIZE];         /* Buffer to load WAL header into */
47386     u8 *aFrame = 0;               /* Malloc'd buffer to load entire frame */
47387     int szFrame;                  /* Number of bytes in buffer aFrame[] */
47388     u8 *aData;                    /* Pointer to data part of aFrame buffer */
47389     int iFrame;                   /* Index of last frame read */
47390     i64 iOffset;                  /* Next offset to read from log file */
47391     int szPage;                   /* Page size according to the log */
47392     u32 magic;                    /* Magic value read from WAL header */
47393     u32 version;                  /* Magic value read from WAL header */
47394     int isValid;                  /* True if this frame is valid */
47395 
47396     /* Read in the WAL header. */
47397     rc = sqlite3OsRead(pWal->pWalFd, aBuf, WAL_HDRSIZE, 0);
47398     if( rc!=SQLITE_OK ){
47399       goto recovery_error;
47400     }
47401 
47402     /* If the database page size is not a power of two, or is greater than
47403     ** SQLITE_MAX_PAGE_SIZE, conclude that the WAL file contains no valid 
47404     ** data. Similarly, if the 'magic' value is invalid, ignore the whole
47405     ** WAL file.
47406     */
47407     magic = sqlite3Get4byte(&aBuf[0]);
47408     szPage = sqlite3Get4byte(&aBuf[8]);
47409     if( (magic&0xFFFFFFFE)!=WAL_MAGIC 
47410      || szPage&(szPage-1) 
47411      || szPage>SQLITE_MAX_PAGE_SIZE 
47412      || szPage<512 
47413     ){
47414       goto finished;
47415     }
47416     pWal->hdr.bigEndCksum = (u8)(magic&0x00000001);
47417     pWal->szPage = szPage;
47418     pWal->nCkpt = sqlite3Get4byte(&aBuf[12]);
47419     memcpy(&pWal->hdr.aSalt, &aBuf[16], 8);
47420 
47421     /* Verify that the WAL header checksum is correct */
47422     walChecksumBytes(pWal->hdr.bigEndCksum==SQLITE_BIGENDIAN, 
47423         aBuf, WAL_HDRSIZE-2*4, 0, pWal->hdr.aFrameCksum
47424     );
47425     if( pWal->hdr.aFrameCksum[0]!=sqlite3Get4byte(&aBuf[24])
47426      || pWal->hdr.aFrameCksum[1]!=sqlite3Get4byte(&aBuf[28])
47427     ){
47428       goto finished;
47429     }
47430 
47431     /* Verify that the version number on the WAL format is one that
47432     ** are able to understand */
47433     version = sqlite3Get4byte(&aBuf[4]);
47434     if( version!=WAL_MAX_VERSION ){
47435       rc = SQLITE_CANTOPEN_BKPT;
47436       goto finished;
47437     }
47438 
47439     /* Malloc a buffer to read frames into. */
47440     szFrame = szPage + WAL_FRAME_HDRSIZE;
47441     aFrame = (u8 *)sqlite3_malloc(szFrame);
47442     if( !aFrame ){
47443       rc = SQLITE_NOMEM;
47444       goto recovery_error;
47445     }
47446     aData = &aFrame[WAL_FRAME_HDRSIZE];
47447 
47448     /* Read all frames from the log file. */
47449     iFrame = 0;
47450     for(iOffset=WAL_HDRSIZE; (iOffset+szFrame)<=nSize; iOffset+=szFrame){
47451       u32 pgno;                   /* Database page number for frame */
47452       u32 nTruncate;              /* dbsize field from frame header */
47453 
47454       /* Read and decode the next log frame. */
47455       iFrame++;
47456       rc = sqlite3OsRead(pWal->pWalFd, aFrame, szFrame, iOffset);
47457       if( rc!=SQLITE_OK ) break;
47458       isValid = walDecodeFrame(pWal, &pgno, &nTruncate, aData, aFrame);
47459       if( !isValid ) break;
47460       rc = walIndexAppend(pWal, iFrame, pgno);
47461       if( rc!=SQLITE_OK ) break;
47462 
47463       /* If nTruncate is non-zero, this is a commit record. */
47464       if( nTruncate ){
47465         pWal->hdr.mxFrame = iFrame;
47466         pWal->hdr.nPage = nTruncate;
47467         pWal->hdr.szPage = (u16)((szPage&0xff00) | (szPage>>16));
47468         testcase( szPage<=32768 );
47469         testcase( szPage>=65536 );
47470         aFrameCksum[0] = pWal->hdr.aFrameCksum[0];
47471         aFrameCksum[1] = pWal->hdr.aFrameCksum[1];
47472       }
47473     }
47474 
47475     sqlite3_free(aFrame);
47476   }
47477 
47478 finished:
47479   if( rc==SQLITE_OK ){
47480     volatile WalCkptInfo *pInfo;
47481     int i;
47482     pWal->hdr.aFrameCksum[0] = aFrameCksum[0];
47483     pWal->hdr.aFrameCksum[1] = aFrameCksum[1];
47484     walIndexWriteHdr(pWal);
47485 
47486     /* Reset the checkpoint-header. This is safe because this thread is 
47487     ** currently holding locks that exclude all other readers, writers and
47488     ** checkpointers.
47489     */
47490     pInfo = walCkptInfo(pWal);
47491     pInfo->nBackfill = 0;
47492     pInfo->aReadMark[0] = 0;
47493     for(i=1; i<WAL_NREADER; i++) pInfo->aReadMark[i] = READMARK_NOT_USED;
47494     if( pWal->hdr.mxFrame ) pInfo->aReadMark[1] = pWal->hdr.mxFrame;
47495 
47496     /* If more than one frame was recovered from the log file, report an
47497     ** event via sqlite3_log(). This is to help with identifying performance
47498     ** problems caused by applications routinely shutting down without
47499     ** checkpointing the log file.
47500     */
47501     if( pWal->hdr.nPage ){
47502       sqlite3_log(SQLITE_NOTICE_RECOVER_WAL,
47503           "recovered %d frames from WAL file %s",
47504           pWal->hdr.mxFrame, pWal->zWalName
47505       );
47506     }
47507   }
47508 
47509 recovery_error:
47510   WALTRACE(("WAL%p: recovery %s\n", pWal, rc ? "failed" : "ok"));
47511   walUnlockExclusive(pWal, iLock, nLock);
47512   return rc;
47513 }
47514 
47515 /*
47516 ** Close an open wal-index.
47517 */
47518 static void walIndexClose(Wal *pWal, int isDelete){
47519   if( pWal->exclusiveMode==WAL_HEAPMEMORY_MODE ){
47520     int i;
47521     for(i=0; i<pWal->nWiData; i++){
47522       sqlite3_free((void *)pWal->apWiData[i]);
47523       pWal->apWiData[i] = 0;
47524     }
47525   }else{
47526     sqlite3OsShmUnmap(pWal->pDbFd, isDelete);
47527   }
47528 }
47529 
47530 /* 
47531 ** Open a connection to the WAL file zWalName. The database file must 
47532 ** already be opened on connection pDbFd. The buffer that zWalName points
47533 ** to must remain valid for the lifetime of the returned Wal* handle.
47534 **
47535 ** A SHARED lock should be held on the database file when this function
47536 ** is called. The purpose of this SHARED lock is to prevent any other
47537 ** client from unlinking the WAL or wal-index file. If another process
47538 ** were to do this just after this client opened one of these files, the
47539 ** system would be badly broken.
47540 **
47541 ** If the log file is successfully opened, SQLITE_OK is returned and 
47542 ** *ppWal is set to point to a new WAL handle. If an error occurs,
47543 ** an SQLite error code is returned and *ppWal is left unmodified.
47544 */
47545 SQLITE_PRIVATE int sqlite3WalOpen(
47546   sqlite3_vfs *pVfs,              /* vfs module to open wal and wal-index */
47547   sqlite3_file *pDbFd,            /* The open database file */
47548   const char *zWalName,           /* Name of the WAL file */
47549   int bNoShm,                     /* True to run in heap-memory mode */
47550   i64 mxWalSize,                  /* Truncate WAL to this size on reset */
47551   Wal **ppWal                     /* OUT: Allocated Wal handle */
47552 ){
47553   int rc;                         /* Return Code */
47554   Wal *pRet;                      /* Object to allocate and return */
47555   int flags;                      /* Flags passed to OsOpen() */
47556 
47557   assert( zWalName && zWalName[0] );
47558   assert( pDbFd );
47559 
47560   /* In the amalgamation, the os_unix.c and os_win.c source files come before
47561   ** this source file.  Verify that the #defines of the locking byte offsets
47562   ** in os_unix.c and os_win.c agree with the WALINDEX_LOCK_OFFSET value.
47563   */
47564 #ifdef WIN_SHM_BASE
47565   assert( WIN_SHM_BASE==WALINDEX_LOCK_OFFSET );
47566 #endif
47567 #ifdef UNIX_SHM_BASE
47568   assert( UNIX_SHM_BASE==WALINDEX_LOCK_OFFSET );
47569 #endif
47570 
47571 
47572   /* Allocate an instance of struct Wal to return. */
47573   *ppWal = 0;
47574   pRet = (Wal*)sqlite3MallocZero(sizeof(Wal) + pVfs->szOsFile);
47575   if( !pRet ){
47576     return SQLITE_NOMEM;
47577   }
47578 
47579   pRet->pVfs = pVfs;
47580   pRet->pWalFd = (sqlite3_file *)&pRet[1];
47581   pRet->pDbFd = pDbFd;
47582   pRet->readLock = -1;
47583   pRet->mxWalSize = mxWalSize;
47584   pRet->zWalName = zWalName;
47585   pRet->syncHeader = 1;
47586   pRet->padToSectorBoundary = 1;
47587   pRet->exclusiveMode = (bNoShm ? WAL_HEAPMEMORY_MODE: WAL_NORMAL_MODE);
47588 
47589   /* Open file handle on the write-ahead log file. */
47590   flags = (SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE|SQLITE_OPEN_WAL);
47591   rc = sqlite3OsOpen(pVfs, zWalName, pRet->pWalFd, flags, &flags);
47592   if( rc==SQLITE_OK && flags&SQLITE_OPEN_READONLY ){
47593     pRet->readOnly = WAL_RDONLY;
47594   }
47595 
47596   if( rc!=SQLITE_OK ){
47597     walIndexClose(pRet, 0);
47598     sqlite3OsClose(pRet->pWalFd);
47599     sqlite3_free(pRet);
47600   }else{
47601     int iDC = sqlite3OsDeviceCharacteristics(pRet->pWalFd);
47602     if( iDC & SQLITE_IOCAP_SEQUENTIAL ){ pRet->syncHeader = 0; }
47603     if( iDC & SQLITE_IOCAP_POWERSAFE_OVERWRITE ){
47604       pRet->padToSectorBoundary = 0;
47605     }
47606     *ppWal = pRet;
47607     WALTRACE(("WAL%d: opened\n", pRet));
47608   }
47609   return rc;
47610 }
47611 
47612 /*
47613 ** Change the size to which the WAL file is trucated on each reset.
47614 */
47615 SQLITE_PRIVATE void sqlite3WalLimit(Wal *pWal, i64 iLimit){
47616   if( pWal ) pWal->mxWalSize = iLimit;
47617 }
47618 
47619 /*
47620 ** Find the smallest page number out of all pages held in the WAL that
47621 ** has not been returned by any prior invocation of this method on the
47622 ** same WalIterator object.   Write into *piFrame the frame index where
47623 ** that page was last written into the WAL.  Write into *piPage the page
47624 ** number.
47625 **
47626 ** Return 0 on success.  If there are no pages in the WAL with a page
47627 ** number larger than *piPage, then return 1.
47628 */
47629 static int walIteratorNext(
47630   WalIterator *p,               /* Iterator */
47631   u32 *piPage,                  /* OUT: The page number of the next page */
47632   u32 *piFrame                  /* OUT: Wal frame index of next page */
47633 ){
47634   u32 iMin;                     /* Result pgno must be greater than iMin */
47635   u32 iRet = 0xFFFFFFFF;        /* 0xffffffff is never a valid page number */
47636   int i;                        /* For looping through segments */
47637 
47638   iMin = p->iPrior;
47639   assert( iMin<0xffffffff );
47640   for(i=p->nSegment-1; i>=0; i--){
47641     struct WalSegment *pSegment = &p->aSegment[i];
47642     while( pSegment->iNext<pSegment->nEntry ){
47643       u32 iPg = pSegment->aPgno[pSegment->aIndex[pSegment->iNext]];
47644       if( iPg>iMin ){
47645         if( iPg<iRet ){
47646           iRet = iPg;
47647           *piFrame = pSegment->iZero + pSegment->aIndex[pSegment->iNext];
47648         }
47649         break;
47650       }
47651       pSegment->iNext++;
47652     }
47653   }
47654 
47655   *piPage = p->iPrior = iRet;
47656   return (iRet==0xFFFFFFFF);
47657 }
47658 
47659 /*
47660 ** This function merges two sorted lists into a single sorted list.
47661 **
47662 ** aLeft[] and aRight[] are arrays of indices.  The sort key is
47663 ** aContent[aLeft[]] and aContent[aRight[]].  Upon entry, the following
47664 ** is guaranteed for all J<K:
47665 **
47666 **        aContent[aLeft[J]] < aContent[aLeft[K]]
47667 **        aContent[aRight[J]] < aContent[aRight[K]]
47668 **
47669 ** This routine overwrites aRight[] with a new (probably longer) sequence
47670 ** of indices such that the aRight[] contains every index that appears in
47671 ** either aLeft[] or the old aRight[] and such that the second condition
47672 ** above is still met.
47673 **
47674 ** The aContent[aLeft[X]] values will be unique for all X.  And the
47675 ** aContent[aRight[X]] values will be unique too.  But there might be
47676 ** one or more combinations of X and Y such that
47677 **
47678 **      aLeft[X]!=aRight[Y]  &&  aContent[aLeft[X]] == aContent[aRight[Y]]
47679 **
47680 ** When that happens, omit the aLeft[X] and use the aRight[Y] index.
47681 */
47682 static void walMerge(
47683   const u32 *aContent,            /* Pages in wal - keys for the sort */
47684   ht_slot *aLeft,                 /* IN: Left hand input list */
47685   int nLeft,                      /* IN: Elements in array *paLeft */
47686   ht_slot **paRight,              /* IN/OUT: Right hand input list */
47687   int *pnRight,                   /* IN/OUT: Elements in *paRight */
47688   ht_slot *aTmp                   /* Temporary buffer */
47689 ){
47690   int iLeft = 0;                  /* Current index in aLeft */
47691   int iRight = 0;                 /* Current index in aRight */
47692   int iOut = 0;                   /* Current index in output buffer */
47693   int nRight = *pnRight;
47694   ht_slot *aRight = *paRight;
47695 
47696   assert( nLeft>0 && nRight>0 );
47697   while( iRight<nRight || iLeft<nLeft ){
47698     ht_slot logpage;
47699     Pgno dbpage;
47700 
47701     if( (iLeft<nLeft) 
47702      && (iRight>=nRight || aContent[aLeft[iLeft]]<aContent[aRight[iRight]])
47703     ){
47704       logpage = aLeft[iLeft++];
47705     }else{
47706       logpage = aRight[iRight++];
47707     }
47708     dbpage = aContent[logpage];
47709 
47710     aTmp[iOut++] = logpage;
47711     if( iLeft<nLeft && aContent[aLeft[iLeft]]==dbpage ) iLeft++;
47712 
47713     assert( iLeft>=nLeft || aContent[aLeft[iLeft]]>dbpage );
47714     assert( iRight>=nRight || aContent[aRight[iRight]]>dbpage );
47715   }
47716 
47717   *paRight = aLeft;
47718   *pnRight = iOut;
47719   memcpy(aLeft, aTmp, sizeof(aTmp[0])*iOut);
47720 }
47721 
47722 /*
47723 ** Sort the elements in list aList using aContent[] as the sort key.
47724 ** Remove elements with duplicate keys, preferring to keep the
47725 ** larger aList[] values.
47726 **
47727 ** The aList[] entries are indices into aContent[].  The values in
47728 ** aList[] are to be sorted so that for all J<K:
47729 **
47730 **      aContent[aList[J]] < aContent[aList[K]]
47731 **
47732 ** For any X and Y such that
47733 **
47734 **      aContent[aList[X]] == aContent[aList[Y]]
47735 **
47736 ** Keep the larger of the two values aList[X] and aList[Y] and discard
47737 ** the smaller.
47738 */
47739 static void walMergesort(
47740   const u32 *aContent,            /* Pages in wal */
47741   ht_slot *aBuffer,               /* Buffer of at least *pnList items to use */
47742   ht_slot *aList,                 /* IN/OUT: List to sort */
47743   int *pnList                     /* IN/OUT: Number of elements in aList[] */
47744 ){
47745   struct Sublist {
47746     int nList;                    /* Number of elements in aList */
47747     ht_slot *aList;               /* Pointer to sub-list content */
47748   };
47749 
47750   const int nList = *pnList;      /* Size of input list */
47751   int nMerge = 0;                 /* Number of elements in list aMerge */
47752   ht_slot *aMerge = 0;            /* List to be merged */
47753   int iList;                      /* Index into input list */
47754   int iSub = 0;                   /* Index into aSub array */
47755   struct Sublist aSub[13];        /* Array of sub-lists */
47756 
47757   memset(aSub, 0, sizeof(aSub));
47758   assert( nList<=HASHTABLE_NPAGE && nList>0 );
47759   assert( HASHTABLE_NPAGE==(1<<(ArraySize(aSub)-1)) );
47760 
47761   for(iList=0; iList<nList; iList++){
47762     nMerge = 1;
47763     aMerge = &aList[iList];
47764     for(iSub=0; iList & (1<<iSub); iSub++){
47765       struct Sublist *p = &aSub[iSub];
47766       assert( p->aList && p->nList<=(1<<iSub) );
47767       assert( p->aList==&aList[iList&~((2<<iSub)-1)] );
47768       walMerge(aContent, p->aList, p->nList, &aMerge, &nMerge, aBuffer);
47769     }
47770     aSub[iSub].aList = aMerge;
47771     aSub[iSub].nList = nMerge;
47772   }
47773 
47774   for(iSub++; iSub<ArraySize(aSub); iSub++){
47775     if( nList & (1<<iSub) ){
47776       struct Sublist *p = &aSub[iSub];
47777       assert( p->nList<=(1<<iSub) );
47778       assert( p->aList==&aList[nList&~((2<<iSub)-1)] );
47779       walMerge(aContent, p->aList, p->nList, &aMerge, &nMerge, aBuffer);
47780     }
47781   }
47782   assert( aMerge==aList );
47783   *pnList = nMerge;
47784 
47785 #ifdef SQLITE_DEBUG
47786   {
47787     int i;
47788     for(i=1; i<*pnList; i++){
47789       assert( aContent[aList[i]] > aContent[aList[i-1]] );
47790     }
47791   }
47792 #endif
47793 }
47794 
47795 /* 
47796 ** Free an iterator allocated by walIteratorInit().
47797 */
47798 static void walIteratorFree(WalIterator *p){
47799   sqlite3ScratchFree(p);
47800 }
47801 
47802 /*
47803 ** Construct a WalInterator object that can be used to loop over all 
47804 ** pages in the WAL in ascending order. The caller must hold the checkpoint
47805 ** lock.
47806 **
47807 ** On success, make *pp point to the newly allocated WalInterator object
47808 ** return SQLITE_OK. Otherwise, return an error code. If this routine
47809 ** returns an error, the value of *pp is undefined.
47810 **
47811 ** The calling routine should invoke walIteratorFree() to destroy the
47812 ** WalIterator object when it has finished with it.
47813 */
47814 static int walIteratorInit(Wal *pWal, WalIterator **pp){
47815   WalIterator *p;                 /* Return value */
47816   int nSegment;                   /* Number of segments to merge */
47817   u32 iLast;                      /* Last frame in log */
47818   int nByte;                      /* Number of bytes to allocate */
47819   int i;                          /* Iterator variable */
47820   ht_slot *aTmp;                  /* Temp space used by merge-sort */
47821   int rc = SQLITE_OK;             /* Return Code */
47822 
47823   /* This routine only runs while holding the checkpoint lock. And
47824   ** it only runs if there is actually content in the log (mxFrame>0).
47825   */
47826   assert( pWal->ckptLock && pWal->hdr.mxFrame>0 );
47827   iLast = pWal->hdr.mxFrame;
47828 
47829   /* Allocate space for the WalIterator object. */
47830   nSegment = walFramePage(iLast) + 1;
47831   nByte = sizeof(WalIterator) 
47832         + (nSegment-1)*sizeof(struct WalSegment)
47833         + iLast*sizeof(ht_slot);
47834   p = (WalIterator *)sqlite3ScratchMalloc(nByte);
47835   if( !p ){
47836     return SQLITE_NOMEM;
47837   }
47838   memset(p, 0, nByte);
47839   p->nSegment = nSegment;
47840 
47841   /* Allocate temporary space used by the merge-sort routine. This block
47842   ** of memory will be freed before this function returns.
47843   */
47844   aTmp = (ht_slot *)sqlite3ScratchMalloc(
47845       sizeof(ht_slot) * (iLast>HASHTABLE_NPAGE?HASHTABLE_NPAGE:iLast)
47846   );
47847   if( !aTmp ){
47848     rc = SQLITE_NOMEM;
47849   }
47850 
47851   for(i=0; rc==SQLITE_OK && i<nSegment; i++){
47852     volatile ht_slot *aHash;
47853     u32 iZero;
47854     volatile u32 *aPgno;
47855 
47856     rc = walHashGet(pWal, i, &aHash, &aPgno, &iZero);
47857     if( rc==SQLITE_OK ){
47858       int j;                      /* Counter variable */
47859       int nEntry;                 /* Number of entries in this segment */
47860       ht_slot *aIndex;            /* Sorted index for this segment */
47861 
47862       aPgno++;
47863       if( (i+1)==nSegment ){
47864         nEntry = (int)(iLast - iZero);
47865       }else{
47866         nEntry = (int)((u32*)aHash - (u32*)aPgno);
47867       }
47868       aIndex = &((ht_slot *)&p->aSegment[p->nSegment])[iZero];
47869       iZero++;
47870   
47871       for(j=0; j<nEntry; j++){
47872         aIndex[j] = (ht_slot)j;
47873       }
47874       walMergesort((u32 *)aPgno, aTmp, aIndex, &nEntry);
47875       p->aSegment[i].iZero = iZero;
47876       p->aSegment[i].nEntry = nEntry;
47877       p->aSegment[i].aIndex = aIndex;
47878       p->aSegment[i].aPgno = (u32 *)aPgno;
47879     }
47880   }
47881   sqlite3ScratchFree(aTmp);
47882 
47883   if( rc!=SQLITE_OK ){
47884     walIteratorFree(p);
47885   }
47886   *pp = p;
47887   return rc;
47888 }
47889 
47890 /*
47891 ** Attempt to obtain the exclusive WAL lock defined by parameters lockIdx and
47892 ** n. If the attempt fails and parameter xBusy is not NULL, then it is a
47893 ** busy-handler function. Invoke it and retry the lock until either the
47894 ** lock is successfully obtained or the busy-handler returns 0.
47895 */
47896 static int walBusyLock(
47897   Wal *pWal,                      /* WAL connection */
47898   int (*xBusy)(void*),            /* Function to call when busy */
47899   void *pBusyArg,                 /* Context argument for xBusyHandler */
47900   int lockIdx,                    /* Offset of first byte to lock */
47901   int n                           /* Number of bytes to lock */
47902 ){
47903   int rc;
47904   do {
47905     rc = walLockExclusive(pWal, lockIdx, n);
47906   }while( xBusy && rc==SQLITE_BUSY && xBusy(pBusyArg) );
47907   return rc;
47908 }
47909 
47910 /*
47911 ** The cache of the wal-index header must be valid to call this function.
47912 ** Return the page-size in bytes used by the database.
47913 */
47914 static int walPagesize(Wal *pWal){
47915   return (pWal->hdr.szPage&0xfe00) + ((pWal->hdr.szPage&0x0001)<<16);
47916 }
47917 
47918 /*
47919 ** Copy as much content as we can from the WAL back into the database file
47920 ** in response to an sqlite3_wal_checkpoint() request or the equivalent.
47921 **
47922 ** The amount of information copies from WAL to database might be limited
47923 ** by active readers.  This routine will never overwrite a database page
47924 ** that a concurrent reader might be using.
47925 **
47926 ** All I/O barrier operations (a.k.a fsyncs) occur in this routine when
47927 ** SQLite is in WAL-mode in synchronous=NORMAL.  That means that if 
47928 ** checkpoints are always run by a background thread or background 
47929 ** process, foreground threads will never block on a lengthy fsync call.
47930 **
47931 ** Fsync is called on the WAL before writing content out of the WAL and
47932 ** into the database.  This ensures that if the new content is persistent
47933 ** in the WAL and can be recovered following a power-loss or hard reset.
47934 **
47935 ** Fsync is also called on the database file if (and only if) the entire
47936 ** WAL content is copied into the database file.  This second fsync makes
47937 ** it safe to delete the WAL since the new content will persist in the
47938 ** database file.
47939 **
47940 ** This routine uses and updates the nBackfill field of the wal-index header.
47941 ** This is the only routine tha will increase the value of nBackfill.  
47942 ** (A WAL reset or recovery will revert nBackfill to zero, but not increase
47943 ** its value.)
47944 **
47945 ** The caller must be holding sufficient locks to ensure that no other
47946 ** checkpoint is running (in any other thread or process) at the same
47947 ** time.
47948 */
47949 static int walCheckpoint(
47950   Wal *pWal,                      /* Wal connection */
47951   int eMode,                      /* One of PASSIVE, FULL or RESTART */
47952   int (*xBusyCall)(void*),        /* Function to call when busy */
47953   void *pBusyArg,                 /* Context argument for xBusyHandler */
47954   int sync_flags,                 /* Flags for OsSync() (or 0) */
47955   u8 *zBuf                        /* Temporary buffer to use */
47956 ){
47957   int rc;                         /* Return code */
47958   int szPage;                     /* Database page-size */
47959   WalIterator *pIter = 0;         /* Wal iterator context */
47960   u32 iDbpage = 0;                /* Next database page to write */
47961   u32 iFrame = 0;                 /* Wal frame containing data for iDbpage */
47962   u32 mxSafeFrame;                /* Max frame that can be backfilled */
47963   u32 mxPage;                     /* Max database page to write */
47964   int i;                          /* Loop counter */
47965   volatile WalCkptInfo *pInfo;    /* The checkpoint status information */
47966   int (*xBusy)(void*) = 0;        /* Function to call when waiting for locks */
47967 
47968   szPage = walPagesize(pWal);
47969   testcase( szPage<=32768 );
47970   testcase( szPage>=65536 );
47971   pInfo = walCkptInfo(pWal);
47972   if( pInfo->nBackfill>=pWal->hdr.mxFrame ) return SQLITE_OK;
47973 
47974   /* Allocate the iterator */
47975   rc = walIteratorInit(pWal, &pIter);
47976   if( rc!=SQLITE_OK ){
47977     return rc;
47978   }
47979   assert( pIter );
47980 
47981   if( eMode!=SQLITE_CHECKPOINT_PASSIVE ) xBusy = xBusyCall;
47982 
47983   /* Compute in mxSafeFrame the index of the last frame of the WAL that is
47984   ** safe to write into the database.  Frames beyond mxSafeFrame might
47985   ** overwrite database pages that are in use by active readers and thus
47986   ** cannot be backfilled from the WAL.
47987   */
47988   mxSafeFrame = pWal->hdr.mxFrame;
47989   mxPage = pWal->hdr.nPage;
47990   for(i=1; i<WAL_NREADER; i++){
47991     u32 y = pInfo->aReadMark[i];
47992     if( mxSafeFrame>y ){
47993       assert( y<=pWal->hdr.mxFrame );
47994       rc = walBusyLock(pWal, xBusy, pBusyArg, WAL_READ_LOCK(i), 1);
47995       if( rc==SQLITE_OK ){
47996         pInfo->aReadMark[i] = (i==1 ? mxSafeFrame : READMARK_NOT_USED);
47997         walUnlockExclusive(pWal, WAL_READ_LOCK(i), 1);
47998       }else if( rc==SQLITE_BUSY ){
47999         mxSafeFrame = y;
48000         xBusy = 0;
48001       }else{
48002         goto walcheckpoint_out;
48003       }
48004     }
48005   }
48006 
48007   if( pInfo->nBackfill<mxSafeFrame
48008    && (rc = walBusyLock(pWal, xBusy, pBusyArg, WAL_READ_LOCK(0), 1))==SQLITE_OK
48009   ){
48010     i64 nSize;                    /* Current size of database file */
48011     u32 nBackfill = pInfo->nBackfill;
48012 
48013     /* Sync the WAL to disk */
48014     if( sync_flags ){
48015       rc = sqlite3OsSync(pWal->pWalFd, sync_flags);
48016     }
48017 
48018     /* If the database may grow as a result of this checkpoint, hint
48019     ** about the eventual size of the db file to the VFS layer.
48020     */
48021     if( rc==SQLITE_OK ){
48022       i64 nReq = ((i64)mxPage * szPage);
48023       rc = sqlite3OsFileSize(pWal->pDbFd, &nSize);
48024       if( rc==SQLITE_OK && nSize<nReq ){
48025         sqlite3OsFileControlHint(pWal->pDbFd, SQLITE_FCNTL_SIZE_HINT, &nReq);
48026       }
48027     }
48028 
48029 
48030     /* Iterate through the contents of the WAL, copying data to the db file. */
48031     while( rc==SQLITE_OK && 0==walIteratorNext(pIter, &iDbpage, &iFrame) ){
48032       i64 iOffset;
48033       assert( walFramePgno(pWal, iFrame)==iDbpage );
48034       if( iFrame<=nBackfill || iFrame>mxSafeFrame || iDbpage>mxPage ) continue;
48035       iOffset = walFrameOffset(iFrame, szPage) + WAL_FRAME_HDRSIZE;
48036       /* testcase( IS_BIG_INT(iOffset) ); // requires a 4GiB WAL file */
48037       rc = sqlite3OsRead(pWal->pWalFd, zBuf, szPage, iOffset);
48038       if( rc!=SQLITE_OK ) break;
48039       iOffset = (iDbpage-1)*(i64)szPage;
48040       testcase( IS_BIG_INT(iOffset) );
48041       rc = sqlite3OsWrite(pWal->pDbFd, zBuf, szPage, iOffset);
48042       if( rc!=SQLITE_OK ) break;
48043     }
48044 
48045     /* If work was actually accomplished... */
48046     if( rc==SQLITE_OK ){
48047       if( mxSafeFrame==walIndexHdr(pWal)->mxFrame ){
48048         i64 szDb = pWal->hdr.nPage*(i64)szPage;
48049         testcase( IS_BIG_INT(szDb) );
48050         rc = sqlite3OsTruncate(pWal->pDbFd, szDb);
48051         if( rc==SQLITE_OK && sync_flags ){
48052           rc = sqlite3OsSync(pWal->pDbFd, sync_flags);
48053         }
48054       }
48055       if( rc==SQLITE_OK ){
48056         pInfo->nBackfill = mxSafeFrame;
48057       }
48058     }
48059 
48060     /* Release the reader lock held while backfilling */
48061     walUnlockExclusive(pWal, WAL_READ_LOCK(0), 1);
48062   }
48063 
48064   if( rc==SQLITE_BUSY ){
48065     /* Reset the return code so as not to report a checkpoint failure
48066     ** just because there are active readers.  */
48067     rc = SQLITE_OK;
48068   }
48069 
48070   /* If this is an SQLITE_CHECKPOINT_RESTART operation, and the entire wal
48071   ** file has been copied into the database file, then block until all
48072   ** readers have finished using the wal file. This ensures that the next
48073   ** process to write to the database restarts the wal file.
48074   */
48075   if( rc==SQLITE_OK && eMode!=SQLITE_CHECKPOINT_PASSIVE ){
48076     assert( pWal->writeLock );
48077     if( pInfo->nBackfill<pWal->hdr.mxFrame ){
48078       rc = SQLITE_BUSY;
48079     }else if( eMode==SQLITE_CHECKPOINT_RESTART ){
48080       assert( mxSafeFrame==pWal->hdr.mxFrame );
48081       rc = walBusyLock(pWal, xBusy, pBusyArg, WAL_READ_LOCK(1), WAL_NREADER-1);
48082       if( rc==SQLITE_OK ){
48083         walUnlockExclusive(pWal, WAL_READ_LOCK(1), WAL_NREADER-1);
48084       }
48085     }
48086   }
48087 
48088  walcheckpoint_out:
48089   walIteratorFree(pIter);
48090   return rc;
48091 }
48092 
48093 /*
48094 ** If the WAL file is currently larger than nMax bytes in size, truncate
48095 ** it to exactly nMax bytes. If an error occurs while doing so, ignore it.
48096 */
48097 static void walLimitSize(Wal *pWal, i64 nMax){
48098   i64 sz;
48099   int rx;
48100   sqlite3BeginBenignMalloc();
48101   rx = sqlite3OsFileSize(pWal->pWalFd, &sz);
48102   if( rx==SQLITE_OK && (sz > nMax ) ){
48103     rx = sqlite3OsTruncate(pWal->pWalFd, nMax);
48104   }
48105   sqlite3EndBenignMalloc();
48106   if( rx ){
48107     sqlite3_log(rx, "cannot limit WAL size: %s", pWal->zWalName);
48108   }
48109 }
48110 
48111 /*
48112 ** Close a connection to a log file.
48113 */
48114 SQLITE_PRIVATE int sqlite3WalClose(
48115   Wal *pWal,                      /* Wal to close */
48116   int sync_flags,                 /* Flags to pass to OsSync() (or 0) */
48117   int nBuf,
48118   u8 *zBuf                        /* Buffer of at least nBuf bytes */
48119 ){
48120   int rc = SQLITE_OK;
48121   if( pWal ){
48122     int isDelete = 0;             /* True to unlink wal and wal-index files */
48123 
48124     /* If an EXCLUSIVE lock can be obtained on the database file (using the
48125     ** ordinary, rollback-mode locking methods, this guarantees that the
48126     ** connection associated with this log file is the only connection to
48127     ** the database. In this case checkpoint the database and unlink both
48128     ** the wal and wal-index files.
48129     **
48130     ** The EXCLUSIVE lock is not released before returning.
48131     */
48132     rc = sqlite3OsLock(pWal->pDbFd, SQLITE_LOCK_EXCLUSIVE);
48133     if( rc==SQLITE_OK ){
48134       if( pWal->exclusiveMode==WAL_NORMAL_MODE ){
48135         pWal->exclusiveMode = WAL_EXCLUSIVE_MODE;
48136       }
48137       rc = sqlite3WalCheckpoint(
48138           pWal, SQLITE_CHECKPOINT_PASSIVE, 0, 0, sync_flags, nBuf, zBuf, 0, 0
48139       );
48140       if( rc==SQLITE_OK ){
48141         int bPersist = -1;
48142         sqlite3OsFileControlHint(
48143             pWal->pDbFd, SQLITE_FCNTL_PERSIST_WAL, &bPersist
48144         );
48145         if( bPersist!=1 ){
48146           /* Try to delete the WAL file if the checkpoint completed and
48147           ** fsyned (rc==SQLITE_OK) and if we are not in persistent-wal
48148           ** mode (!bPersist) */
48149           isDelete = 1;
48150         }else if( pWal->mxWalSize>=0 ){
48151           /* Try to truncate the WAL file to zero bytes if the checkpoint
48152           ** completed and fsynced (rc==SQLITE_OK) and we are in persistent
48153           ** WAL mode (bPersist) and if the PRAGMA journal_size_limit is a
48154           ** non-negative value (pWal->mxWalSize>=0).  Note that we truncate
48155           ** to zero bytes as truncating to the journal_size_limit might
48156           ** leave a corrupt WAL file on disk. */
48157           walLimitSize(pWal, 0);
48158         }
48159       }
48160     }
48161 
48162     walIndexClose(pWal, isDelete);
48163     sqlite3OsClose(pWal->pWalFd);
48164     if( isDelete ){
48165       sqlite3BeginBenignMalloc();
48166       sqlite3OsDelete(pWal->pVfs, pWal->zWalName, 0);
48167       sqlite3EndBenignMalloc();
48168     }
48169     WALTRACE(("WAL%p: closed\n", pWal));
48170     sqlite3_free((void *)pWal->apWiData);
48171     sqlite3_free(pWal);
48172   }
48173   return rc;
48174 }
48175 
48176 /*
48177 ** Try to read the wal-index header.  Return 0 on success and 1 if
48178 ** there is a problem.
48179 **
48180 ** The wal-index is in shared memory.  Another thread or process might
48181 ** be writing the header at the same time this procedure is trying to
48182 ** read it, which might result in inconsistency.  A dirty read is detected
48183 ** by verifying that both copies of the header are the same and also by
48184 ** a checksum on the header.
48185 **
48186 ** If and only if the read is consistent and the header is different from
48187 ** pWal->hdr, then pWal->hdr is updated to the content of the new header
48188 ** and *pChanged is set to 1.
48189 **
48190 ** If the checksum cannot be verified return non-zero. If the header
48191 ** is read successfully and the checksum verified, return zero.
48192 */
48193 static int walIndexTryHdr(Wal *pWal, int *pChanged){
48194   u32 aCksum[2];                  /* Checksum on the header content */
48195   WalIndexHdr h1, h2;             /* Two copies of the header content */
48196   WalIndexHdr volatile *aHdr;     /* Header in shared memory */
48197 
48198   /* The first page of the wal-index must be mapped at this point. */
48199   assert( pWal->nWiData>0 && pWal->apWiData[0] );
48200 
48201   /* Read the header. This might happen concurrently with a write to the
48202   ** same area of shared memory on a different CPU in a SMP,
48203   ** meaning it is possible that an inconsistent snapshot is read
48204   ** from the file. If this happens, return non-zero.
48205   **
48206   ** There are two copies of the header at the beginning of the wal-index.
48207   ** When reading, read [0] first then [1].  Writes are in the reverse order.
48208   ** Memory barriers are used to prevent the compiler or the hardware from
48209   ** reordering the reads and writes.
48210   */
48211   aHdr = walIndexHdr(pWal);
48212   memcpy(&h1, (void *)&aHdr[0], sizeof(h1));
48213   walShmBarrier(pWal);
48214   memcpy(&h2, (void *)&aHdr[1], sizeof(h2));
48215 
48216   if( memcmp(&h1, &h2, sizeof(h1))!=0 ){
48217     return 1;   /* Dirty read */
48218   }  
48219   if( h1.isInit==0 ){
48220     return 1;   /* Malformed header - probably all zeros */
48221   }
48222   walChecksumBytes(1, (u8*)&h1, sizeof(h1)-sizeof(h1.aCksum), 0, aCksum);
48223   if( aCksum[0]!=h1.aCksum[0] || aCksum[1]!=h1.aCksum[1] ){
48224     return 1;   /* Checksum does not match */
48225   }
48226 
48227   if( memcmp(&pWal->hdr, &h1, sizeof(WalIndexHdr)) ){
48228     *pChanged = 1;
48229     memcpy(&pWal->hdr, &h1, sizeof(WalIndexHdr));
48230     pWal->szPage = (pWal->hdr.szPage&0xfe00) + ((pWal->hdr.szPage&0x0001)<<16);
48231     testcase( pWal->szPage<=32768 );
48232     testcase( pWal->szPage>=65536 );
48233   }
48234 
48235   /* The header was successfully read. Return zero. */
48236   return 0;
48237 }
48238 
48239 /*
48240 ** Read the wal-index header from the wal-index and into pWal->hdr.
48241 ** If the wal-header appears to be corrupt, try to reconstruct the
48242 ** wal-index from the WAL before returning.
48243 **
48244 ** Set *pChanged to 1 if the wal-index header value in pWal->hdr is
48245 ** changed by this opertion.  If pWal->hdr is unchanged, set *pChanged
48246 ** to 0.
48247 **
48248 ** If the wal-index header is successfully read, return SQLITE_OK. 
48249 ** Otherwise an SQLite error code.
48250 */
48251 static int walIndexReadHdr(Wal *pWal, int *pChanged){
48252   int rc;                         /* Return code */
48253   int badHdr;                     /* True if a header read failed */
48254   volatile u32 *page0;            /* Chunk of wal-index containing header */
48255 
48256   /* Ensure that page 0 of the wal-index (the page that contains the 
48257   ** wal-index header) is mapped. Return early if an error occurs here.
48258   */
48259   assert( pChanged );
48260   rc = walIndexPage(pWal, 0, &page0);
48261   if( rc!=SQLITE_OK ){
48262     return rc;
48263   };
48264   assert( page0 || pWal->writeLock==0 );
48265 
48266   /* If the first page of the wal-index has been mapped, try to read the
48267   ** wal-index header immediately, without holding any lock. This usually
48268   ** works, but may fail if the wal-index header is corrupt or currently 
48269   ** being modified by another thread or process.
48270   */
48271   badHdr = (page0 ? walIndexTryHdr(pWal, pChanged) : 1);
48272 
48273   /* If the first attempt failed, it might have been due to a race
48274   ** with a writer.  So get a WRITE lock and try again.
48275   */
48276   assert( badHdr==0 || pWal->writeLock==0 );
48277   if( badHdr ){
48278     if( pWal->readOnly & WAL_SHM_RDONLY ){
48279       if( SQLITE_OK==(rc = walLockShared(pWal, WAL_WRITE_LOCK)) ){
48280         walUnlockShared(pWal, WAL_WRITE_LOCK);
48281         rc = SQLITE_READONLY_RECOVERY;
48282       }
48283     }else if( SQLITE_OK==(rc = walLockExclusive(pWal, WAL_WRITE_LOCK, 1)) ){
48284       pWal->writeLock = 1;
48285       if( SQLITE_OK==(rc = walIndexPage(pWal, 0, &page0)) ){
48286         badHdr = walIndexTryHdr(pWal, pChanged);
48287         if( badHdr ){
48288           /* If the wal-index header is still malformed even while holding
48289           ** a WRITE lock, it can only mean that the header is corrupted and
48290           ** needs to be reconstructed.  So run recovery to do exactly that.
48291           */
48292           rc = walIndexRecover(pWal);
48293           *pChanged = 1;
48294         }
48295       }
48296       pWal->writeLock = 0;
48297       walUnlockExclusive(pWal, WAL_WRITE_LOCK, 1);
48298     }
48299   }
48300 
48301   /* If the header is read successfully, check the version number to make
48302   ** sure the wal-index was not constructed with some future format that
48303   ** this version of SQLite cannot understand.
48304   */
48305   if( badHdr==0 && pWal->hdr.iVersion!=WALINDEX_MAX_VERSION ){
48306     rc = SQLITE_CANTOPEN_BKPT;
48307   }
48308 
48309   return rc;
48310 }
48311 
48312 /*
48313 ** This is the value that walTryBeginRead returns when it needs to
48314 ** be retried.
48315 */
48316 #define WAL_RETRY  (-1)
48317 
48318 /*
48319 ** Attempt to start a read transaction.  This might fail due to a race or
48320 ** other transient condition.  When that happens, it returns WAL_RETRY to
48321 ** indicate to the caller that it is safe to retry immediately.
48322 **
48323 ** On success return SQLITE_OK.  On a permanent failure (such an
48324 ** I/O error or an SQLITE_BUSY because another process is running
48325 ** recovery) return a positive error code.
48326 **
48327 ** The useWal parameter is true to force the use of the WAL and disable
48328 ** the case where the WAL is bypassed because it has been completely
48329 ** checkpointed.  If useWal==0 then this routine calls walIndexReadHdr() 
48330 ** to make a copy of the wal-index header into pWal->hdr.  If the 
48331 ** wal-index header has changed, *pChanged is set to 1 (as an indication 
48332 ** to the caller that the local paget cache is obsolete and needs to be 
48333 ** flushed.)  When useWal==1, the wal-index header is assumed to already
48334 ** be loaded and the pChanged parameter is unused.
48335 **
48336 ** The caller must set the cnt parameter to the number of prior calls to
48337 ** this routine during the current read attempt that returned WAL_RETRY.
48338 ** This routine will start taking more aggressive measures to clear the
48339 ** race conditions after multiple WAL_RETRY returns, and after an excessive
48340 ** number of errors will ultimately return SQLITE_PROTOCOL.  The
48341 ** SQLITE_PROTOCOL return indicates that some other process has gone rogue
48342 ** and is not honoring the locking protocol.  There is a vanishingly small
48343 ** chance that SQLITE_PROTOCOL could be returned because of a run of really
48344 ** bad luck when there is lots of contention for the wal-index, but that
48345 ** possibility is so small that it can be safely neglected, we believe.
48346 **
48347 ** On success, this routine obtains a read lock on 
48348 ** WAL_READ_LOCK(pWal->readLock).  The pWal->readLock integer is
48349 ** in the range 0 <= pWal->readLock < WAL_NREADER.  If pWal->readLock==(-1)
48350 ** that means the Wal does not hold any read lock.  The reader must not
48351 ** access any database page that is modified by a WAL frame up to and
48352 ** including frame number aReadMark[pWal->readLock].  The reader will
48353 ** use WAL frames up to and including pWal->hdr.mxFrame if pWal->readLock>0
48354 ** Or if pWal->readLock==0, then the reader will ignore the WAL
48355 ** completely and get all content directly from the database file.
48356 ** If the useWal parameter is 1 then the WAL will never be ignored and
48357 ** this routine will always set pWal->readLock>0 on success.
48358 ** When the read transaction is completed, the caller must release the
48359 ** lock on WAL_READ_LOCK(pWal->readLock) and set pWal->readLock to -1.
48360 **
48361 ** This routine uses the nBackfill and aReadMark[] fields of the header
48362 ** to select a particular WAL_READ_LOCK() that strives to let the
48363 ** checkpoint process do as much work as possible.  This routine might
48364 ** update values of the aReadMark[] array in the header, but if it does
48365 ** so it takes care to hold an exclusive lock on the corresponding
48366 ** WAL_READ_LOCK() while changing values.
48367 */
48368 static int walTryBeginRead(Wal *pWal, int *pChanged, int useWal, int cnt){
48369   volatile WalCkptInfo *pInfo;    /* Checkpoint information in wal-index */
48370   u32 mxReadMark;                 /* Largest aReadMark[] value */
48371   int mxI;                        /* Index of largest aReadMark[] value */
48372   int i;                          /* Loop counter */
48373   int rc = SQLITE_OK;             /* Return code  */
48374 
48375   assert( pWal->readLock<0 );     /* Not currently locked */
48376 
48377   /* Take steps to avoid spinning forever if there is a protocol error.
48378   **
48379   ** Circumstances that cause a RETRY should only last for the briefest
48380   ** instances of time.  No I/O or other system calls are done while the
48381   ** locks are held, so the locks should not be held for very long. But 
48382   ** if we are unlucky, another process that is holding a lock might get
48383   ** paged out or take a page-fault that is time-consuming to resolve, 
48384   ** during the few nanoseconds that it is holding the lock.  In that case,
48385   ** it might take longer than normal for the lock to free.
48386   **
48387   ** After 5 RETRYs, we begin calling sqlite3OsSleep().  The first few
48388   ** calls to sqlite3OsSleep() have a delay of 1 microsecond.  Really this
48389   ** is more of a scheduler yield than an actual delay.  But on the 10th
48390   ** an subsequent retries, the delays start becoming longer and longer, 
48391   ** so that on the 100th (and last) RETRY we delay for 21 milliseconds.
48392   ** The total delay time before giving up is less than 1 second.
48393   */
48394   if( cnt>5 ){
48395     int nDelay = 1;                      /* Pause time in microseconds */
48396     if( cnt>100 ){
48397       VVA_ONLY( pWal->lockError = 1; )
48398       return SQLITE_PROTOCOL;
48399     }
48400     if( cnt>=10 ) nDelay = (cnt-9)*238;  /* Max delay 21ms. Total delay 996ms */
48401     sqlite3OsSleep(pWal->pVfs, nDelay);
48402   }
48403 
48404   if( !useWal ){
48405     rc = walIndexReadHdr(pWal, pChanged);
48406     if( rc==SQLITE_BUSY ){
48407       /* If there is not a recovery running in another thread or process
48408       ** then convert BUSY errors to WAL_RETRY.  If recovery is known to
48409       ** be running, convert BUSY to BUSY_RECOVERY.  There is a race here
48410       ** which might cause WAL_RETRY to be returned even if BUSY_RECOVERY
48411       ** would be technically correct.  But the race is benign since with
48412       ** WAL_RETRY this routine will be called again and will probably be
48413       ** right on the second iteration.
48414       */
48415       if( pWal->apWiData[0]==0 ){
48416         /* This branch is taken when the xShmMap() method returns SQLITE_BUSY.
48417         ** We assume this is a transient condition, so return WAL_RETRY. The
48418         ** xShmMap() implementation used by the default unix and win32 VFS 
48419         ** modules may return SQLITE_BUSY due to a race condition in the 
48420         ** code that determines whether or not the shared-memory region 
48421         ** must be zeroed before the requested page is returned.
48422         */
48423         rc = WAL_RETRY;
48424       }else if( SQLITE_OK==(rc = walLockShared(pWal, WAL_RECOVER_LOCK)) ){
48425         walUnlockShared(pWal, WAL_RECOVER_LOCK);
48426         rc = WAL_RETRY;
48427       }else if( rc==SQLITE_BUSY ){
48428         rc = SQLITE_BUSY_RECOVERY;
48429       }
48430     }
48431     if( rc!=SQLITE_OK ){
48432       return rc;
48433     }
48434   }
48435 
48436   pInfo = walCkptInfo(pWal);
48437   if( !useWal && pInfo->nBackfill==pWal->hdr.mxFrame ){
48438     /* The WAL has been completely backfilled (or it is empty).
48439     ** and can be safely ignored.
48440     */
48441     rc = walLockShared(pWal, WAL_READ_LOCK(0));
48442     walShmBarrier(pWal);
48443     if( rc==SQLITE_OK ){
48444       if( memcmp((void *)walIndexHdr(pWal), &pWal->hdr, sizeof(WalIndexHdr)) ){
48445         /* It is not safe to allow the reader to continue here if frames
48446         ** may have been appended to the log before READ_LOCK(0) was obtained.
48447         ** When holding READ_LOCK(0), the reader ignores the entire log file,
48448         ** which implies that the database file contains a trustworthy
48449         ** snapshoT. Since holding READ_LOCK(0) prevents a checkpoint from
48450         ** happening, this is usually correct.
48451         **
48452         ** However, if frames have been appended to the log (or if the log 
48453         ** is wrapped and written for that matter) before the READ_LOCK(0)
48454         ** is obtained, that is not necessarily true. A checkpointer may
48455         ** have started to backfill the appended frames but crashed before
48456         ** it finished. Leaving a corrupt image in the database file.
48457         */
48458         walUnlockShared(pWal, WAL_READ_LOCK(0));
48459         return WAL_RETRY;
48460       }
48461       pWal->readLock = 0;
48462       return SQLITE_OK;
48463     }else if( rc!=SQLITE_BUSY ){
48464       return rc;
48465     }
48466   }
48467 
48468   /* If we get this far, it means that the reader will want to use
48469   ** the WAL to get at content from recent commits.  The job now is
48470   ** to select one of the aReadMark[] entries that is closest to
48471   ** but not exceeding pWal->hdr.mxFrame and lock that entry.
48472   */
48473   mxReadMark = 0;
48474   mxI = 0;
48475   for(i=1; i<WAL_NREADER; i++){
48476     u32 thisMark = pInfo->aReadMark[i];
48477     if( mxReadMark<=thisMark && thisMark<=pWal->hdr.mxFrame ){
48478       assert( thisMark!=READMARK_NOT_USED );
48479       mxReadMark = thisMark;
48480       mxI = i;
48481     }
48482   }
48483   /* There was once an "if" here. The extra "{" is to preserve indentation. */
48484   {
48485     if( (pWal->readOnly & WAL_SHM_RDONLY)==0
48486      && (mxReadMark<pWal->hdr.mxFrame || mxI==0)
48487     ){
48488       for(i=1; i<WAL_NREADER; i++){
48489         rc = walLockExclusive(pWal, WAL_READ_LOCK(i), 1);
48490         if( rc==SQLITE_OK ){
48491           mxReadMark = pInfo->aReadMark[i] = pWal->hdr.mxFrame;
48492           mxI = i;
48493           walUnlockExclusive(pWal, WAL_READ_LOCK(i), 1);
48494           break;
48495         }else if( rc!=SQLITE_BUSY ){
48496           return rc;
48497         }
48498       }
48499     }
48500     if( mxI==0 ){
48501       assert( rc==SQLITE_BUSY || (pWal->readOnly & WAL_SHM_RDONLY)!=0 );
48502       return rc==SQLITE_BUSY ? WAL_RETRY : SQLITE_READONLY_CANTLOCK;
48503     }
48504 
48505     rc = walLockShared(pWal, WAL_READ_LOCK(mxI));
48506     if( rc ){
48507       return rc==SQLITE_BUSY ? WAL_RETRY : rc;
48508     }
48509     /* Now that the read-lock has been obtained, check that neither the
48510     ** value in the aReadMark[] array or the contents of the wal-index
48511     ** header have changed.
48512     **
48513     ** It is necessary to check that the wal-index header did not change
48514     ** between the time it was read and when the shared-lock was obtained
48515     ** on WAL_READ_LOCK(mxI) was obtained to account for the possibility
48516     ** that the log file may have been wrapped by a writer, or that frames
48517     ** that occur later in the log than pWal->hdr.mxFrame may have been
48518     ** copied into the database by a checkpointer. If either of these things
48519     ** happened, then reading the database with the current value of
48520     ** pWal->hdr.mxFrame risks reading a corrupted snapshot. So, retry
48521     ** instead.
48522     **
48523     ** This does not guarantee that the copy of the wal-index header is up to
48524     ** date before proceeding. That would not be possible without somehow
48525     ** blocking writers. It only guarantees that a dangerous checkpoint or 
48526     ** log-wrap (either of which would require an exclusive lock on
48527     ** WAL_READ_LOCK(mxI)) has not occurred since the snapshot was valid.
48528     */
48529     walShmBarrier(pWal);
48530     if( pInfo->aReadMark[mxI]!=mxReadMark
48531      || memcmp((void *)walIndexHdr(pWal), &pWal->hdr, sizeof(WalIndexHdr))
48532     ){
48533       walUnlockShared(pWal, WAL_READ_LOCK(mxI));
48534       return WAL_RETRY;
48535     }else{
48536       assert( mxReadMark<=pWal->hdr.mxFrame );
48537       pWal->readLock = (i16)mxI;
48538     }
48539   }
48540   return rc;
48541 }
48542 
48543 /*
48544 ** Begin a read transaction on the database.
48545 **
48546 ** This routine used to be called sqlite3OpenSnapshot() and with good reason:
48547 ** it takes a snapshot of the state of the WAL and wal-index for the current
48548 ** instant in time.  The current thread will continue to use this snapshot.
48549 ** Other threads might append new content to the WAL and wal-index but
48550 ** that extra content is ignored by the current thread.
48551 **
48552 ** If the database contents have changes since the previous read
48553 ** transaction, then *pChanged is set to 1 before returning.  The
48554 ** Pager layer will use this to know that is cache is stale and
48555 ** needs to be flushed.
48556 */
48557 SQLITE_PRIVATE int sqlite3WalBeginReadTransaction(Wal *pWal, int *pChanged){
48558   int rc;                         /* Return code */
48559   int cnt = 0;                    /* Number of TryBeginRead attempts */
48560 
48561   do{
48562     rc = walTryBeginRead(pWal, pChanged, 0, ++cnt);
48563   }while( rc==WAL_RETRY );
48564   testcase( (rc&0xff)==SQLITE_BUSY );
48565   testcase( (rc&0xff)==SQLITE_IOERR );
48566   testcase( rc==SQLITE_PROTOCOL );
48567   testcase( rc==SQLITE_OK );
48568   return rc;
48569 }
48570 
48571 /*
48572 ** Finish with a read transaction.  All this does is release the
48573 ** read-lock.
48574 */
48575 SQLITE_PRIVATE void sqlite3WalEndReadTransaction(Wal *pWal){
48576   sqlite3WalEndWriteTransaction(pWal);
48577   if( pWal->readLock>=0 ){
48578     walUnlockShared(pWal, WAL_READ_LOCK(pWal->readLock));
48579     pWal->readLock = -1;
48580   }
48581 }
48582 
48583 /*
48584 ** Search the wal file for page pgno. If found, set *piRead to the frame that
48585 ** contains the page. Otherwise, if pgno is not in the wal file, set *piRead
48586 ** to zero.
48587 **
48588 ** Return SQLITE_OK if successful, or an error code if an error occurs. If an
48589 ** error does occur, the final value of *piRead is undefined.
48590 */
48591 SQLITE_PRIVATE int sqlite3WalFindFrame(
48592   Wal *pWal,                      /* WAL handle */
48593   Pgno pgno,                      /* Database page number to read data for */
48594   u32 *piRead                     /* OUT: Frame number (or zero) */
48595 ){
48596   u32 iRead = 0;                  /* If !=0, WAL frame to return data from */
48597   u32 iLast = pWal->hdr.mxFrame;  /* Last page in WAL for this reader */
48598   int iHash;                      /* Used to loop through N hash tables */
48599 
48600   /* This routine is only be called from within a read transaction. */
48601   assert( pWal->readLock>=0 || pWal->lockError );
48602 
48603   /* If the "last page" field of the wal-index header snapshot is 0, then
48604   ** no data will be read from the wal under any circumstances. Return early
48605   ** in this case as an optimization.  Likewise, if pWal->readLock==0, 
48606   ** then the WAL is ignored by the reader so return early, as if the 
48607   ** WAL were empty.
48608   */
48609   if( iLast==0 || pWal->readLock==0 ){
48610     *piRead = 0;
48611     return SQLITE_OK;
48612   }
48613 
48614   /* Search the hash table or tables for an entry matching page number
48615   ** pgno. Each iteration of the following for() loop searches one
48616   ** hash table (each hash table indexes up to HASHTABLE_NPAGE frames).
48617   **
48618   ** This code might run concurrently to the code in walIndexAppend()
48619   ** that adds entries to the wal-index (and possibly to this hash 
48620   ** table). This means the value just read from the hash 
48621   ** slot (aHash[iKey]) may have been added before or after the 
48622   ** current read transaction was opened. Values added after the
48623   ** read transaction was opened may have been written incorrectly -
48624   ** i.e. these slots may contain garbage data. However, we assume
48625   ** that any slots written before the current read transaction was
48626   ** opened remain unmodified.
48627   **
48628   ** For the reasons above, the if(...) condition featured in the inner
48629   ** loop of the following block is more stringent that would be required 
48630   ** if we had exclusive access to the hash-table:
48631   **
48632   **   (aPgno[iFrame]==pgno): 
48633   **     This condition filters out normal hash-table collisions.
48634   **
48635   **   (iFrame<=iLast): 
48636   **     This condition filters out entries that were added to the hash
48637   **     table after the current read-transaction had started.
48638   */
48639   for(iHash=walFramePage(iLast); iHash>=0 && iRead==0; iHash--){
48640     volatile ht_slot *aHash;      /* Pointer to hash table */
48641     volatile u32 *aPgno;          /* Pointer to array of page numbers */
48642     u32 iZero;                    /* Frame number corresponding to aPgno[0] */
48643     int iKey;                     /* Hash slot index */
48644     int nCollide;                 /* Number of hash collisions remaining */
48645     int rc;                       /* Error code */
48646 
48647     rc = walHashGet(pWal, iHash, &aHash, &aPgno, &iZero);
48648     if( rc!=SQLITE_OK ){
48649       return rc;
48650     }
48651     nCollide = HASHTABLE_NSLOT;
48652     for(iKey=walHash(pgno); aHash[iKey]; iKey=walNextHash(iKey)){
48653       u32 iFrame = aHash[iKey] + iZero;
48654       if( iFrame<=iLast && aPgno[aHash[iKey]]==pgno ){
48655         /* assert( iFrame>iRead ); -- not true if there is corruption */
48656         iRead = iFrame;
48657       }
48658       if( (nCollide--)==0 ){
48659         return SQLITE_CORRUPT_BKPT;
48660       }
48661     }
48662   }
48663 
48664 #ifdef SQLITE_ENABLE_EXPENSIVE_ASSERT
48665   /* If expensive assert() statements are available, do a linear search
48666   ** of the wal-index file content. Make sure the results agree with the
48667   ** result obtained using the hash indexes above.  */
48668   {
48669     u32 iRead2 = 0;
48670     u32 iTest;
48671     for(iTest=iLast; iTest>0; iTest--){
48672       if( walFramePgno(pWal, iTest)==pgno ){
48673         iRead2 = iTest;
48674         break;
48675       }
48676     }
48677     assert( iRead==iRead2 );
48678   }
48679 #endif
48680 
48681   *piRead = iRead;
48682   return SQLITE_OK;
48683 }
48684 
48685 /*
48686 ** Read the contents of frame iRead from the wal file into buffer pOut
48687 ** (which is nOut bytes in size). Return SQLITE_OK if successful, or an
48688 ** error code otherwise.
48689 */
48690 SQLITE_PRIVATE int sqlite3WalReadFrame(
48691   Wal *pWal,                      /* WAL handle */
48692   u32 iRead,                      /* Frame to read */
48693   int nOut,                       /* Size of buffer pOut in bytes */
48694   u8 *pOut                        /* Buffer to write page data to */
48695 ){
48696   int sz;
48697   i64 iOffset;
48698   sz = pWal->hdr.szPage;
48699   sz = (sz&0xfe00) + ((sz&0x0001)<<16);
48700   testcase( sz<=32768 );
48701   testcase( sz>=65536 );
48702   iOffset = walFrameOffset(iRead, sz) + WAL_FRAME_HDRSIZE;
48703   /* testcase( IS_BIG_INT(iOffset) ); // requires a 4GiB WAL */
48704   return sqlite3OsRead(pWal->pWalFd, pOut, (nOut>sz ? sz : nOut), iOffset);
48705 }
48706 
48707 /* 
48708 ** Return the size of the database in pages (or zero, if unknown).
48709 */
48710 SQLITE_PRIVATE Pgno sqlite3WalDbsize(Wal *pWal){
48711   if( pWal && ALWAYS(pWal->readLock>=0) ){
48712     return pWal->hdr.nPage;
48713   }
48714   return 0;
48715 }
48716 
48717 
48718 /* 
48719 ** This function starts a write transaction on the WAL.
48720 **
48721 ** A read transaction must have already been started by a prior call
48722 ** to sqlite3WalBeginReadTransaction().
48723 **
48724 ** If another thread or process has written into the database since
48725 ** the read transaction was started, then it is not possible for this
48726 ** thread to write as doing so would cause a fork.  So this routine
48727 ** returns SQLITE_BUSY in that case and no write transaction is started.
48728 **
48729 ** There can only be a single writer active at a time.
48730 */
48731 SQLITE_PRIVATE int sqlite3WalBeginWriteTransaction(Wal *pWal){
48732   int rc;
48733 
48734   /* Cannot start a write transaction without first holding a read
48735   ** transaction. */
48736   assert( pWal->readLock>=0 );
48737 
48738   if( pWal->readOnly ){
48739     return SQLITE_READONLY;
48740   }
48741 
48742   /* Only one writer allowed at a time.  Get the write lock.  Return
48743   ** SQLITE_BUSY if unable.
48744   */
48745   rc = walLockExclusive(pWal, WAL_WRITE_LOCK, 1);
48746   if( rc ){
48747     return rc;
48748   }
48749   pWal->writeLock = 1;
48750 
48751   /* If another connection has written to the database file since the
48752   ** time the read transaction on this connection was started, then
48753   ** the write is disallowed.
48754   */
48755   if( memcmp(&pWal->hdr, (void *)walIndexHdr(pWal), sizeof(WalIndexHdr))!=0 ){
48756     walUnlockExclusive(pWal, WAL_WRITE_LOCK, 1);
48757     pWal->writeLock = 0;
48758     rc = SQLITE_BUSY_SNAPSHOT;
48759   }
48760 
48761   return rc;
48762 }
48763 
48764 /*
48765 ** End a write transaction.  The commit has already been done.  This
48766 ** routine merely releases the lock.
48767 */
48768 SQLITE_PRIVATE int sqlite3WalEndWriteTransaction(Wal *pWal){
48769   if( pWal->writeLock ){
48770     walUnlockExclusive(pWal, WAL_WRITE_LOCK, 1);
48771     pWal->writeLock = 0;
48772     pWal->truncateOnCommit = 0;
48773   }
48774   return SQLITE_OK;
48775 }
48776 
48777 /*
48778 ** If any data has been written (but not committed) to the log file, this
48779 ** function moves the write-pointer back to the start of the transaction.
48780 **
48781 ** Additionally, the callback function is invoked for each frame written
48782 ** to the WAL since the start of the transaction. If the callback returns
48783 ** other than SQLITE_OK, it is not invoked again and the error code is
48784 ** returned to the caller.
48785 **
48786 ** Otherwise, if the callback function does not return an error, this
48787 ** function returns SQLITE_OK.
48788 */
48789 SQLITE_PRIVATE int sqlite3WalUndo(Wal *pWal, int (*xUndo)(void *, Pgno), void *pUndoCtx){
48790   int rc = SQLITE_OK;
48791   if( ALWAYS(pWal->writeLock) ){
48792     Pgno iMax = pWal->hdr.mxFrame;
48793     Pgno iFrame;
48794   
48795     /* Restore the clients cache of the wal-index header to the state it
48796     ** was in before the client began writing to the database. 
48797     */
48798     memcpy(&pWal->hdr, (void *)walIndexHdr(pWal), sizeof(WalIndexHdr));
48799 
48800     for(iFrame=pWal->hdr.mxFrame+1; 
48801         ALWAYS(rc==SQLITE_OK) && iFrame<=iMax; 
48802         iFrame++
48803     ){
48804       /* This call cannot fail. Unless the page for which the page number
48805       ** is passed as the second argument is (a) in the cache and 
48806       ** (b) has an outstanding reference, then xUndo is either a no-op
48807       ** (if (a) is false) or simply expels the page from the cache (if (b)
48808       ** is false).
48809       **
48810       ** If the upper layer is doing a rollback, it is guaranteed that there
48811       ** are no outstanding references to any page other than page 1. And
48812       ** page 1 is never written to the log until the transaction is
48813       ** committed. As a result, the call to xUndo may not fail.
48814       */
48815       assert( walFramePgno(pWal, iFrame)!=1 );
48816       rc = xUndo(pUndoCtx, walFramePgno(pWal, iFrame));
48817     }
48818     if( iMax!=pWal->hdr.mxFrame ) walCleanupHash(pWal);
48819   }
48820   assert( rc==SQLITE_OK );
48821   return rc;
48822 }
48823 
48824 /* 
48825 ** Argument aWalData must point to an array of WAL_SAVEPOINT_NDATA u32 
48826 ** values. This function populates the array with values required to 
48827 ** "rollback" the write position of the WAL handle back to the current 
48828 ** point in the event of a savepoint rollback (via WalSavepointUndo()).
48829 */
48830 SQLITE_PRIVATE void sqlite3WalSavepoint(Wal *pWal, u32 *aWalData){
48831   assert( pWal->writeLock );
48832   aWalData[0] = pWal->hdr.mxFrame;
48833   aWalData[1] = pWal->hdr.aFrameCksum[0];
48834   aWalData[2] = pWal->hdr.aFrameCksum[1];
48835   aWalData[3] = pWal->nCkpt;
48836 }
48837 
48838 /* 
48839 ** Move the write position of the WAL back to the point identified by
48840 ** the values in the aWalData[] array. aWalData must point to an array
48841 ** of WAL_SAVEPOINT_NDATA u32 values that has been previously populated
48842 ** by a call to WalSavepoint().
48843 */
48844 SQLITE_PRIVATE int sqlite3WalSavepointUndo(Wal *pWal, u32 *aWalData){
48845   int rc = SQLITE_OK;
48846 
48847   assert( pWal->writeLock );
48848   assert( aWalData[3]!=pWal->nCkpt || aWalData[0]<=pWal->hdr.mxFrame );
48849 
48850   if( aWalData[3]!=pWal->nCkpt ){
48851     /* This savepoint was opened immediately after the write-transaction
48852     ** was started. Right after that, the writer decided to wrap around
48853     ** to the start of the log. Update the savepoint values to match.
48854     */
48855     aWalData[0] = 0;
48856     aWalData[3] = pWal->nCkpt;
48857   }
48858 
48859   if( aWalData[0]<pWal->hdr.mxFrame ){
48860     pWal->hdr.mxFrame = aWalData[0];
48861     pWal->hdr.aFrameCksum[0] = aWalData[1];
48862     pWal->hdr.aFrameCksum[1] = aWalData[2];
48863     walCleanupHash(pWal);
48864   }
48865 
48866   return rc;
48867 }
48868 
48869 
48870 /*
48871 ** This function is called just before writing a set of frames to the log
48872 ** file (see sqlite3WalFrames()). It checks to see if, instead of appending
48873 ** to the current log file, it is possible to overwrite the start of the
48874 ** existing log file with the new frames (i.e. "reset" the log). If so,
48875 ** it sets pWal->hdr.mxFrame to 0. Otherwise, pWal->hdr.mxFrame is left
48876 ** unchanged.
48877 **
48878 ** SQLITE_OK is returned if no error is encountered (regardless of whether
48879 ** or not pWal->hdr.mxFrame is modified). An SQLite error code is returned
48880 ** if an error occurs.
48881 */
48882 static int walRestartLog(Wal *pWal){
48883   int rc = SQLITE_OK;
48884   int cnt;
48885 
48886   if( pWal->readLock==0 ){
48887     volatile WalCkptInfo *pInfo = walCkptInfo(pWal);
48888     assert( pInfo->nBackfill==pWal->hdr.mxFrame );
48889     if( pInfo->nBackfill>0 ){
48890       u32 salt1;
48891       sqlite3_randomness(4, &salt1);
48892       rc = walLockExclusive(pWal, WAL_READ_LOCK(1), WAL_NREADER-1);
48893       if( rc==SQLITE_OK ){
48894         /* If all readers are using WAL_READ_LOCK(0) (in other words if no
48895         ** readers are currently using the WAL), then the transactions
48896         ** frames will overwrite the start of the existing log. Update the
48897         ** wal-index header to reflect this.
48898         **
48899         ** In theory it would be Ok to update the cache of the header only
48900         ** at this point. But updating the actual wal-index header is also
48901         ** safe and means there is no special case for sqlite3WalUndo()
48902         ** to handle if this transaction is rolled back.
48903         */
48904         int i;                    /* Loop counter */
48905         u32 *aSalt = pWal->hdr.aSalt;       /* Big-endian salt values */
48906 
48907         pWal->nCkpt++;
48908         pWal->hdr.mxFrame = 0;
48909         sqlite3Put4byte((u8*)&aSalt[0], 1 + sqlite3Get4byte((u8*)&aSalt[0]));
48910         aSalt[1] = salt1;
48911         walIndexWriteHdr(pWal);
48912         pInfo->nBackfill = 0;
48913         pInfo->aReadMark[1] = 0;
48914         for(i=2; i<WAL_NREADER; i++) pInfo->aReadMark[i] = READMARK_NOT_USED;
48915         assert( pInfo->aReadMark[0]==0 );
48916         walUnlockExclusive(pWal, WAL_READ_LOCK(1), WAL_NREADER-1);
48917       }else if( rc!=SQLITE_BUSY ){
48918         return rc;
48919       }
48920     }
48921     walUnlockShared(pWal, WAL_READ_LOCK(0));
48922     pWal->readLock = -1;
48923     cnt = 0;
48924     do{
48925       int notUsed;
48926       rc = walTryBeginRead(pWal, &notUsed, 1, ++cnt);
48927     }while( rc==WAL_RETRY );
48928     assert( (rc&0xff)!=SQLITE_BUSY ); /* BUSY not possible when useWal==1 */
48929     testcase( (rc&0xff)==SQLITE_IOERR );
48930     testcase( rc==SQLITE_PROTOCOL );
48931     testcase( rc==SQLITE_OK );
48932   }
48933   return rc;
48934 }
48935 
48936 /*
48937 ** Information about the current state of the WAL file and where
48938 ** the next fsync should occur - passed from sqlite3WalFrames() into
48939 ** walWriteToLog().
48940 */
48941 typedef struct WalWriter {
48942   Wal *pWal;                   /* The complete WAL information */
48943   sqlite3_file *pFd;           /* The WAL file to which we write */
48944   sqlite3_int64 iSyncPoint;    /* Fsync at this offset */
48945   int syncFlags;               /* Flags for the fsync */
48946   int szPage;                  /* Size of one page */
48947 } WalWriter;
48948 
48949 /*
48950 ** Write iAmt bytes of content into the WAL file beginning at iOffset.
48951 ** Do a sync when crossing the p->iSyncPoint boundary.
48952 **
48953 ** In other words, if iSyncPoint is in between iOffset and iOffset+iAmt,
48954 ** first write the part before iSyncPoint, then sync, then write the
48955 ** rest.
48956 */
48957 static int walWriteToLog(
48958   WalWriter *p,              /* WAL to write to */
48959   void *pContent,            /* Content to be written */
48960   int iAmt,                  /* Number of bytes to write */
48961   sqlite3_int64 iOffset      /* Start writing at this offset */
48962 ){
48963   int rc;
48964   if( iOffset<p->iSyncPoint && iOffset+iAmt>=p->iSyncPoint ){
48965     int iFirstAmt = (int)(p->iSyncPoint - iOffset);
48966     rc = sqlite3OsWrite(p->pFd, pContent, iFirstAmt, iOffset);
48967     if( rc ) return rc;
48968     iOffset += iFirstAmt;
48969     iAmt -= iFirstAmt;
48970     pContent = (void*)(iFirstAmt + (char*)pContent);
48971     assert( p->syncFlags & (SQLITE_SYNC_NORMAL|SQLITE_SYNC_FULL) );
48972     rc = sqlite3OsSync(p->pFd, p->syncFlags);
48973     if( iAmt==0 || rc ) return rc;
48974   }
48975   rc = sqlite3OsWrite(p->pFd, pContent, iAmt, iOffset);
48976   return rc;
48977 }
48978 
48979 /*
48980 ** Write out a single frame of the WAL
48981 */
48982 static int walWriteOneFrame(
48983   WalWriter *p,               /* Where to write the frame */
48984   PgHdr *pPage,               /* The page of the frame to be written */
48985   int nTruncate,              /* The commit flag.  Usually 0.  >0 for commit */
48986   sqlite3_int64 iOffset       /* Byte offset at which to write */
48987 ){
48988   int rc;                         /* Result code from subfunctions */
48989   void *pData;                    /* Data actually written */
48990   u8 aFrame[WAL_FRAME_HDRSIZE];   /* Buffer to assemble frame-header in */
48991 #if defined(SQLITE_HAS_CODEC)
48992   if( (pData = sqlite3PagerCodec(pPage))==0 ) return SQLITE_NOMEM;
48993 #else
48994   pData = pPage->pData;
48995 #endif
48996   walEncodeFrame(p->pWal, pPage->pgno, nTruncate, pData, aFrame);
48997   rc = walWriteToLog(p, aFrame, sizeof(aFrame), iOffset);
48998   if( rc ) return rc;
48999   /* Write the page data */
49000   rc = walWriteToLog(p, pData, p->szPage, iOffset+sizeof(aFrame));
49001   return rc;
49002 }
49003 
49004 /* 
49005 ** Write a set of frames to the log. The caller must hold the write-lock
49006 ** on the log file (obtained using sqlite3WalBeginWriteTransaction()).
49007 */
49008 SQLITE_PRIVATE int sqlite3WalFrames(
49009   Wal *pWal,                      /* Wal handle to write to */
49010   int szPage,                     /* Database page-size in bytes */
49011   PgHdr *pList,                   /* List of dirty pages to write */
49012   Pgno nTruncate,                 /* Database size after this commit */
49013   int isCommit,                   /* True if this is a commit */
49014   int sync_flags                  /* Flags to pass to OsSync() (or 0) */
49015 ){
49016   int rc;                         /* Used to catch return codes */
49017   u32 iFrame;                     /* Next frame address */
49018   PgHdr *p;                       /* Iterator to run through pList with. */
49019   PgHdr *pLast = 0;               /* Last frame in list */
49020   int nExtra = 0;                 /* Number of extra copies of last page */
49021   int szFrame;                    /* The size of a single frame */
49022   i64 iOffset;                    /* Next byte to write in WAL file */
49023   WalWriter w;                    /* The writer */
49024 
49025   assert( pList );
49026   assert( pWal->writeLock );
49027 
49028   /* If this frame set completes a transaction, then nTruncate>0.  If
49029   ** nTruncate==0 then this frame set does not complete the transaction. */
49030   assert( (isCommit!=0)==(nTruncate!=0) );
49031 
49032 #if defined(SQLITE_TEST) && defined(SQLITE_DEBUG)
49033   { int cnt; for(cnt=0, p=pList; p; p=p->pDirty, cnt++){}
49034     WALTRACE(("WAL%p: frame write begin. %d frames. mxFrame=%d. %s\n",
49035               pWal, cnt, pWal->hdr.mxFrame, isCommit ? "Commit" : "Spill"));
49036   }
49037 #endif
49038 
49039   /* See if it is possible to write these frames into the start of the
49040   ** log file, instead of appending to it at pWal->hdr.mxFrame.
49041   */
49042   if( SQLITE_OK!=(rc = walRestartLog(pWal)) ){
49043     return rc;
49044   }
49045 
49046   /* If this is the first frame written into the log, write the WAL
49047   ** header to the start of the WAL file. See comments at the top of
49048   ** this source file for a description of the WAL header format.
49049   */
49050   iFrame = pWal->hdr.mxFrame;
49051   if( iFrame==0 ){
49052     u8 aWalHdr[WAL_HDRSIZE];      /* Buffer to assemble wal-header in */
49053     u32 aCksum[2];                /* Checksum for wal-header */
49054 
49055     sqlite3Put4byte(&aWalHdr[0], (WAL_MAGIC | SQLITE_BIGENDIAN));
49056     sqlite3Put4byte(&aWalHdr[4], WAL_MAX_VERSION);
49057     sqlite3Put4byte(&aWalHdr[8], szPage);
49058     sqlite3Put4byte(&aWalHdr[12], pWal->nCkpt);
49059     if( pWal->nCkpt==0 ) sqlite3_randomness(8, pWal->hdr.aSalt);
49060     memcpy(&aWalHdr[16], pWal->hdr.aSalt, 8);
49061     walChecksumBytes(1, aWalHdr, WAL_HDRSIZE-2*4, 0, aCksum);
49062     sqlite3Put4byte(&aWalHdr[24], aCksum[0]);
49063     sqlite3Put4byte(&aWalHdr[28], aCksum[1]);
49064     
49065     pWal->szPage = szPage;
49066     pWal->hdr.bigEndCksum = SQLITE_BIGENDIAN;
49067     pWal->hdr.aFrameCksum[0] = aCksum[0];
49068     pWal->hdr.aFrameCksum[1] = aCksum[1];
49069     pWal->truncateOnCommit = 1;
49070 
49071     rc = sqlite3OsWrite(pWal->pWalFd, aWalHdr, sizeof(aWalHdr), 0);
49072     WALTRACE(("WAL%p: wal-header write %s\n", pWal, rc ? "failed" : "ok"));
49073     if( rc!=SQLITE_OK ){
49074       return rc;
49075     }
49076 
49077     /* Sync the header (unless SQLITE_IOCAP_SEQUENTIAL is true or unless
49078     ** all syncing is turned off by PRAGMA synchronous=OFF).  Otherwise
49079     ** an out-of-order write following a WAL restart could result in
49080     ** database corruption.  See the ticket:
49081     **
49082     **     http://localhost:591/sqlite/info/ff5be73dee
49083     */
49084     if( pWal->syncHeader && sync_flags ){
49085       rc = sqlite3OsSync(pWal->pWalFd, sync_flags & SQLITE_SYNC_MASK);
49086       if( rc ) return rc;
49087     }
49088   }
49089   assert( (int)pWal->szPage==szPage );
49090 
49091   /* Setup information needed to write frames into the WAL */
49092   w.pWal = pWal;
49093   w.pFd = pWal->pWalFd;
49094   w.iSyncPoint = 0;
49095   w.syncFlags = sync_flags;
49096   w.szPage = szPage;
49097   iOffset = walFrameOffset(iFrame+1, szPage);
49098   szFrame = szPage + WAL_FRAME_HDRSIZE;
49099 
49100   /* Write all frames into the log file exactly once */
49101   for(p=pList; p; p=p->pDirty){
49102     int nDbSize;   /* 0 normally.  Positive == commit flag */
49103     iFrame++;
49104     assert( iOffset==walFrameOffset(iFrame, szPage) );
49105     nDbSize = (isCommit && p->pDirty==0) ? nTruncate : 0;
49106     rc = walWriteOneFrame(&w, p, nDbSize, iOffset);
49107     if( rc ) return rc;
49108     pLast = p;
49109     iOffset += szFrame;
49110   }
49111 
49112   /* If this is the end of a transaction, then we might need to pad
49113   ** the transaction and/or sync the WAL file.
49114   **
49115   ** Padding and syncing only occur if this set of frames complete a
49116   ** transaction and if PRAGMA synchronous=FULL.  If synchronous==NORMAL
49117   ** or synchonous==OFF, then no padding or syncing are needed.
49118   **
49119   ** If SQLITE_IOCAP_POWERSAFE_OVERWRITE is defined, then padding is not
49120   ** needed and only the sync is done.  If padding is needed, then the
49121   ** final frame is repeated (with its commit mark) until the next sector
49122   ** boundary is crossed.  Only the part of the WAL prior to the last
49123   ** sector boundary is synced; the part of the last frame that extends
49124   ** past the sector boundary is written after the sync.
49125   */
49126   if( isCommit && (sync_flags & WAL_SYNC_TRANSACTIONS)!=0 ){
49127     if( pWal->padToSectorBoundary ){
49128       int sectorSize = sqlite3SectorSize(pWal->pWalFd);
49129       w.iSyncPoint = ((iOffset+sectorSize-1)/sectorSize)*sectorSize;
49130       while( iOffset<w.iSyncPoint ){
49131         rc = walWriteOneFrame(&w, pLast, nTruncate, iOffset);
49132         if( rc ) return rc;
49133         iOffset += szFrame;
49134         nExtra++;
49135       }
49136     }else{
49137       rc = sqlite3OsSync(w.pFd, sync_flags & SQLITE_SYNC_MASK);
49138     }
49139   }
49140 
49141   /* If this frame set completes the first transaction in the WAL and
49142   ** if PRAGMA journal_size_limit is set, then truncate the WAL to the
49143   ** journal size limit, if possible.
49144   */
49145   if( isCommit && pWal->truncateOnCommit && pWal->mxWalSize>=0 ){
49146     i64 sz = pWal->mxWalSize;
49147     if( walFrameOffset(iFrame+nExtra+1, szPage)>pWal->mxWalSize ){
49148       sz = walFrameOffset(iFrame+nExtra+1, szPage);
49149     }
49150     walLimitSize(pWal, sz);
49151     pWal->truncateOnCommit = 0;
49152   }
49153 
49154   /* Append data to the wal-index. It is not necessary to lock the 
49155   ** wal-index to do this as the SQLITE_SHM_WRITE lock held on the wal-index
49156   ** guarantees that there are no other writers, and no data that may
49157   ** be in use by existing readers is being overwritten.
49158   */
49159   iFrame = pWal->hdr.mxFrame;
49160   for(p=pList; p && rc==SQLITE_OK; p=p->pDirty){
49161     iFrame++;
49162     rc = walIndexAppend(pWal, iFrame, p->pgno);
49163   }
49164   while( rc==SQLITE_OK && nExtra>0 ){
49165     iFrame++;
49166     nExtra--;
49167     rc = walIndexAppend(pWal, iFrame, pLast->pgno);
49168   }
49169 
49170   if( rc==SQLITE_OK ){
49171     /* Update the private copy of the header. */
49172     pWal->hdr.szPage = (u16)((szPage&0xff00) | (szPage>>16));
49173     testcase( szPage<=32768 );
49174     testcase( szPage>=65536 );
49175     pWal->hdr.mxFrame = iFrame;
49176     if( isCommit ){
49177       pWal->hdr.iChange++;
49178       pWal->hdr.nPage = nTruncate;
49179     }
49180     /* If this is a commit, update the wal-index header too. */
49181     if( isCommit ){
49182       walIndexWriteHdr(pWal);
49183       pWal->iCallback = iFrame;
49184     }
49185   }
49186 
49187   WALTRACE(("WAL%p: frame write %s\n", pWal, rc ? "failed" : "ok"));
49188   return rc;
49189 }
49190 
49191 /* 
49192 ** This routine is called to implement sqlite3_wal_checkpoint() and
49193 ** related interfaces.
49194 **
49195 ** Obtain a CHECKPOINT lock and then backfill as much information as
49196 ** we can from WAL into the database.
49197 **
49198 ** If parameter xBusy is not NULL, it is a pointer to a busy-handler
49199 ** callback. In this case this function runs a blocking checkpoint.
49200 */
49201 SQLITE_PRIVATE int sqlite3WalCheckpoint(
49202   Wal *pWal,                      /* Wal connection */
49203   int eMode,                      /* PASSIVE, FULL or RESTART */
49204   int (*xBusy)(void*),            /* Function to call when busy */
49205   void *pBusyArg,                 /* Context argument for xBusyHandler */
49206   int sync_flags,                 /* Flags to sync db file with (or 0) */
49207   int nBuf,                       /* Size of temporary buffer */
49208   u8 *zBuf,                       /* Temporary buffer to use */
49209   int *pnLog,                     /* OUT: Number of frames in WAL */
49210   int *pnCkpt                     /* OUT: Number of backfilled frames in WAL */
49211 ){
49212   int rc;                         /* Return code */
49213   int isChanged = 0;              /* True if a new wal-index header is loaded */
49214   int eMode2 = eMode;             /* Mode to pass to walCheckpoint() */
49215 
49216   assert( pWal->ckptLock==0 );
49217   assert( pWal->writeLock==0 );
49218 
49219   if( pWal->readOnly ) return SQLITE_READONLY;
49220   WALTRACE(("WAL%p: checkpoint begins\n", pWal));
49221   rc = walLockExclusive(pWal, WAL_CKPT_LOCK, 1);
49222   if( rc ){
49223     /* Usually this is SQLITE_BUSY meaning that another thread or process
49224     ** is already running a checkpoint, or maybe a recovery.  But it might
49225     ** also be SQLITE_IOERR. */
49226     return rc;
49227   }
49228   pWal->ckptLock = 1;
49229 
49230   /* If this is a blocking-checkpoint, then obtain the write-lock as well
49231   ** to prevent any writers from running while the checkpoint is underway.
49232   ** This has to be done before the call to walIndexReadHdr() below.
49233   **
49234   ** If the writer lock cannot be obtained, then a passive checkpoint is
49235   ** run instead. Since the checkpointer is not holding the writer lock,
49236   ** there is no point in blocking waiting for any readers. Assuming no 
49237   ** other error occurs, this function will return SQLITE_BUSY to the caller.
49238   */
49239   if( eMode!=SQLITE_CHECKPOINT_PASSIVE ){
49240     rc = walBusyLock(pWal, xBusy, pBusyArg, WAL_WRITE_LOCK, 1);
49241     if( rc==SQLITE_OK ){
49242       pWal->writeLock = 1;
49243     }else if( rc==SQLITE_BUSY ){
49244       eMode2 = SQLITE_CHECKPOINT_PASSIVE;
49245       rc = SQLITE_OK;
49246     }
49247   }
49248 
49249   /* Read the wal-index header. */
49250   if( rc==SQLITE_OK ){
49251     rc = walIndexReadHdr(pWal, &isChanged);
49252     if( isChanged && pWal->pDbFd->pMethods->iVersion>=3 ){
49253       sqlite3OsUnfetch(pWal->pDbFd, 0, 0);
49254     }
49255   }
49256 
49257   /* Copy data from the log to the database file. */
49258   if( rc==SQLITE_OK ){
49259     if( pWal->hdr.mxFrame && walPagesize(pWal)!=nBuf ){
49260       rc = SQLITE_CORRUPT_BKPT;
49261     }else{
49262       rc = walCheckpoint(pWal, eMode2, xBusy, pBusyArg, sync_flags, zBuf);
49263     }
49264 
49265     /* If no error occurred, set the output variables. */
49266     if( rc==SQLITE_OK || rc==SQLITE_BUSY ){
49267       if( pnLog ) *pnLog = (int)pWal->hdr.mxFrame;
49268       if( pnCkpt ) *pnCkpt = (int)(walCkptInfo(pWal)->nBackfill);
49269     }
49270   }
49271 
49272   if( isChanged ){
49273     /* If a new wal-index header was loaded before the checkpoint was 
49274     ** performed, then the pager-cache associated with pWal is now
49275     ** out of date. So zero the cached wal-index header to ensure that
49276     ** next time the pager opens a snapshot on this database it knows that
49277     ** the cache needs to be reset.
49278     */
49279     memset(&pWal->hdr, 0, sizeof(WalIndexHdr));
49280   }
49281 
49282   /* Release the locks. */
49283   sqlite3WalEndWriteTransaction(pWal);
49284   walUnlockExclusive(pWal, WAL_CKPT_LOCK, 1);
49285   pWal->ckptLock = 0;
49286   WALTRACE(("WAL%p: checkpoint %s\n", pWal, rc ? "failed" : "ok"));
49287   return (rc==SQLITE_OK && eMode!=eMode2 ? SQLITE_BUSY : rc);
49288 }
49289 
49290 /* Return the value to pass to a sqlite3_wal_hook callback, the
49291 ** number of frames in the WAL at the point of the last commit since
49292 ** sqlite3WalCallback() was called.  If no commits have occurred since
49293 ** the last call, then return 0.
49294 */
49295 SQLITE_PRIVATE int sqlite3WalCallback(Wal *pWal){
49296   u32 ret = 0;
49297   if( pWal ){
49298     ret = pWal->iCallback;
49299     pWal->iCallback = 0;
49300   }
49301   return (int)ret;
49302 }
49303 
49304 /*
49305 ** This function is called to change the WAL subsystem into or out
49306 ** of locking_mode=EXCLUSIVE.
49307 **
49308 ** If op is zero, then attempt to change from locking_mode=EXCLUSIVE
49309 ** into locking_mode=NORMAL.  This means that we must acquire a lock
49310 ** on the pWal->readLock byte.  If the WAL is already in locking_mode=NORMAL
49311 ** or if the acquisition of the lock fails, then return 0.  If the
49312 ** transition out of exclusive-mode is successful, return 1.  This
49313 ** operation must occur while the pager is still holding the exclusive
49314 ** lock on the main database file.
49315 **
49316 ** If op is one, then change from locking_mode=NORMAL into 
49317 ** locking_mode=EXCLUSIVE.  This means that the pWal->readLock must
49318 ** be released.  Return 1 if the transition is made and 0 if the
49319 ** WAL is already in exclusive-locking mode - meaning that this
49320 ** routine is a no-op.  The pager must already hold the exclusive lock
49321 ** on the main database file before invoking this operation.
49322 **
49323 ** If op is negative, then do a dry-run of the op==1 case but do
49324 ** not actually change anything. The pager uses this to see if it
49325 ** should acquire the database exclusive lock prior to invoking
49326 ** the op==1 case.
49327 */
49328 SQLITE_PRIVATE int sqlite3WalExclusiveMode(Wal *pWal, int op){
49329   int rc;
49330   assert( pWal->writeLock==0 );
49331   assert( pWal->exclusiveMode!=WAL_HEAPMEMORY_MODE || op==-1 );
49332 
49333   /* pWal->readLock is usually set, but might be -1 if there was a 
49334   ** prior error while attempting to acquire are read-lock. This cannot 
49335   ** happen if the connection is actually in exclusive mode (as no xShmLock
49336   ** locks are taken in this case). Nor should the pager attempt to
49337   ** upgrade to exclusive-mode following such an error.
49338   */
49339   assert( pWal->readLock>=0 || pWal->lockError );
49340   assert( pWal->readLock>=0 || (op<=0 && pWal->exclusiveMode==0) );
49341 
49342   if( op==0 ){
49343     if( pWal->exclusiveMode ){
49344       pWal->exclusiveMode = 0;
49345       if( walLockShared(pWal, WAL_READ_LOCK(pWal->readLock))!=SQLITE_OK ){
49346         pWal->exclusiveMode = 1;
49347       }
49348       rc = pWal->exclusiveMode==0;
49349     }else{
49350       /* Already in locking_mode=NORMAL */
49351       rc = 0;
49352     }
49353   }else if( op>0 ){
49354     assert( pWal->exclusiveMode==0 );
49355     assert( pWal->readLock>=0 );
49356     walUnlockShared(pWal, WAL_READ_LOCK(pWal->readLock));
49357     pWal->exclusiveMode = 1;
49358     rc = 1;
49359   }else{
49360     rc = pWal->exclusiveMode==0;
49361   }
49362   return rc;
49363 }
49364 
49365 /* 
49366 ** Return true if the argument is non-NULL and the WAL module is using
49367 ** heap-memory for the wal-index. Otherwise, if the argument is NULL or the
49368 ** WAL module is using shared-memory, return false. 
49369 */
49370 SQLITE_PRIVATE int sqlite3WalHeapMemory(Wal *pWal){
49371   return (pWal && pWal->exclusiveMode==WAL_HEAPMEMORY_MODE );
49372 }
49373 
49374 #ifdef SQLITE_ENABLE_ZIPVFS
49375 /*
49376 ** If the argument is not NULL, it points to a Wal object that holds a
49377 ** read-lock. This function returns the database page-size if it is known,
49378 ** or zero if it is not (or if pWal is NULL).
49379 */
49380 SQLITE_PRIVATE int sqlite3WalFramesize(Wal *pWal){
49381   assert( pWal==0 || pWal->readLock>=0 );
49382   return (pWal ? pWal->szPage : 0);
49383 }
49384 #endif
49385 
49386 #endif /* #ifndef SQLITE_OMIT_WAL */
49387 
49388 /************** End of wal.c *************************************************/
49389 /************** Begin file btmutex.c *****************************************/
49390 /*
49391 ** 2007 August 27
49392 **
49393 ** The author disclaims copyright to this source code.  In place of
49394 ** a legal notice, here is a blessing:
49395 **
49396 **    May you do good and not evil.
49397 **    May you find forgiveness for yourself and forgive others.
49398 **    May you share freely, never taking more than you give.
49399 **
49400 *************************************************************************
49401 **
49402 ** This file contains code used to implement mutexes on Btree objects.
49403 ** This code really belongs in btree.c.  But btree.c is getting too
49404 ** big and we want to break it down some.  This packaged seemed like
49405 ** a good breakout.
49406 */
49407 /************** Include btreeInt.h in the middle of btmutex.c ****************/
49408 /************** Begin file btreeInt.h ****************************************/
49409 /*
49410 ** 2004 April 6
49411 **
49412 ** The author disclaims copyright to this source code.  In place of
49413 ** a legal notice, here is a blessing:
49414 **
49415 **    May you do good and not evil.
49416 **    May you find forgiveness for yourself and forgive others.
49417 **    May you share freely, never taking more than you give.
49418 **
49419 *************************************************************************
49420 ** This file implements a external (disk-based) database using BTrees.
49421 ** For a detailed discussion of BTrees, refer to
49422 **
49423 **     Donald E. Knuth, THE ART OF COMPUTER PROGRAMMING, Volume 3:
49424 **     "Sorting And Searching", pages 473-480. Addison-Wesley
49425 **     Publishing Company, Reading, Massachusetts.
49426 **
49427 ** The basic idea is that each page of the file contains N database
49428 ** entries and N+1 pointers to subpages.
49429 **
49430 **   ----------------------------------------------------------------
49431 **   |  Ptr(0) | Key(0) | Ptr(1) | Key(1) | ... | Key(N-1) | Ptr(N) |
49432 **   ----------------------------------------------------------------
49433 **
49434 ** All of the keys on the page that Ptr(0) points to have values less
49435 ** than Key(0).  All of the keys on page Ptr(1) and its subpages have
49436 ** values greater than Key(0) and less than Key(1).  All of the keys
49437 ** on Ptr(N) and its subpages have values greater than Key(N-1).  And
49438 ** so forth.
49439 **
49440 ** Finding a particular key requires reading O(log(M)) pages from the 
49441 ** disk where M is the number of entries in the tree.
49442 **
49443 ** In this implementation, a single file can hold one or more separate 
49444 ** BTrees.  Each BTree is identified by the index of its root page.  The
49445 ** key and data for any entry are combined to form the "payload".  A
49446 ** fixed amount of payload can be carried directly on the database
49447 ** page.  If the payload is larger than the preset amount then surplus
49448 ** bytes are stored on overflow pages.  The payload for an entry
49449 ** and the preceding pointer are combined to form a "Cell".  Each 
49450 ** page has a small header which contains the Ptr(N) pointer and other
49451 ** information such as the size of key and data.
49452 **
49453 ** FORMAT DETAILS
49454 **
49455 ** The file is divided into pages.  The first page is called page 1,
49456 ** the second is page 2, and so forth.  A page number of zero indicates
49457 ** "no such page".  The page size can be any power of 2 between 512 and 65536.
49458 ** Each page can be either a btree page, a freelist page, an overflow
49459 ** page, or a pointer-map page.
49460 **
49461 ** The first page is always a btree page.  The first 100 bytes of the first
49462 ** page contain a special header (the "file header") that describes the file.
49463 ** The format of the file header is as follows:
49464 **
49465 **   OFFSET   SIZE    DESCRIPTION
49466 **      0      16     Header string: "SQLite format 3\000"
49467 **     16       2     Page size in bytes.  (1 means 65536)
49468 **     18       1     File format write version
49469 **     19       1     File format read version
49470 **     20       1     Bytes of unused space at the end of each page
49471 **     21       1     Max embedded payload fraction (must be 64)
49472 **     22       1     Min embedded payload fraction (must be 32)
49473 **     23       1     Min leaf payload fraction (must be 32)
49474 **     24       4     File change counter
49475 **     28       4     Reserved for future use
49476 **     32       4     First freelist page
49477 **     36       4     Number of freelist pages in the file
49478 **     40      60     15 4-byte meta values passed to higher layers
49479 **
49480 **     40       4     Schema cookie
49481 **     44       4     File format of schema layer
49482 **     48       4     Size of page cache
49483 **     52       4     Largest root-page (auto/incr_vacuum)
49484 **     56       4     1=UTF-8 2=UTF16le 3=UTF16be
49485 **     60       4     User version
49486 **     64       4     Incremental vacuum mode
49487 **     68       4     Application-ID
49488 **     72      20     unused
49489 **     92       4     The version-valid-for number
49490 **     96       4     SQLITE_VERSION_NUMBER
49491 **
49492 ** All of the integer values are big-endian (most significant byte first).
49493 **
49494 ** The file change counter is incremented when the database is changed
49495 ** This counter allows other processes to know when the file has changed
49496 ** and thus when they need to flush their cache.
49497 **
49498 ** The max embedded payload fraction is the amount of the total usable
49499 ** space in a page that can be consumed by a single cell for standard
49500 ** B-tree (non-LEAFDATA) tables.  A value of 255 means 100%.  The default
49501 ** is to limit the maximum cell size so that at least 4 cells will fit
49502 ** on one page.  Thus the default max embedded payload fraction is 64.
49503 **
49504 ** If the payload for a cell is larger than the max payload, then extra
49505 ** payload is spilled to overflow pages.  Once an overflow page is allocated,
49506 ** as many bytes as possible are moved into the overflow pages without letting
49507 ** the cell size drop below the min embedded payload fraction.
49508 **
49509 ** The min leaf payload fraction is like the min embedded payload fraction
49510 ** except that it applies to leaf nodes in a LEAFDATA tree.  The maximum
49511 ** payload fraction for a LEAFDATA tree is always 100% (or 255) and it
49512 ** not specified in the header.
49513 **
49514 ** Each btree pages is divided into three sections:  The header, the
49515 ** cell pointer array, and the cell content area.  Page 1 also has a 100-byte
49516 ** file header that occurs before the page header.
49517 **
49518 **      |----------------|
49519 **      | file header    |   100 bytes.  Page 1 only.
49520 **      |----------------|
49521 **      | page header    |   8 bytes for leaves.  12 bytes for interior nodes
49522 **      |----------------|
49523 **      | cell pointer   |   |  2 bytes per cell.  Sorted order.
49524 **      | array          |   |  Grows downward
49525 **      |                |   v
49526 **      |----------------|
49527 **      | unallocated    |
49528 **      | space          |
49529 **      |----------------|   ^  Grows upwards
49530 **      | cell content   |   |  Arbitrary order interspersed with freeblocks.
49531 **      | area           |   |  and free space fragments.
49532 **      |----------------|
49533 **
49534 ** The page headers looks like this:
49535 **
49536 **   OFFSET   SIZE     DESCRIPTION
49537 **      0       1      Flags. 1: intkey, 2: zerodata, 4: leafdata, 8: leaf
49538 **      1       2      byte offset to the first freeblock
49539 **      3       2      number of cells on this page
49540 **      5       2      first byte of the cell content area
49541 **      7       1      number of fragmented free bytes
49542 **      8       4      Right child (the Ptr(N) value).  Omitted on leaves.
49543 **
49544 ** The flags define the format of this btree page.  The leaf flag means that
49545 ** this page has no children.  The zerodata flag means that this page carries
49546 ** only keys and no data.  The intkey flag means that the key is a integer
49547 ** which is stored in the key size entry of the cell header rather than in
49548 ** the payload area.
49549 **
49550 ** The cell pointer array begins on the first byte after the page header.
49551 ** The cell pointer array contains zero or more 2-byte numbers which are
49552 ** offsets from the beginning of the page to the cell content in the cell
49553 ** content area.  The cell pointers occur in sorted order.  The system strives
49554 ** to keep free space after the last cell pointer so that new cells can
49555 ** be easily added without having to defragment the page.
49556 **
49557 ** Cell content is stored at the very end of the page and grows toward the
49558 ** beginning of the page.
49559 **
49560 ** Unused space within the cell content area is collected into a linked list of
49561 ** freeblocks.  Each freeblock is at least 4 bytes in size.  The byte offset
49562 ** to the first freeblock is given in the header.  Freeblocks occur in
49563 ** increasing order.  Because a freeblock must be at least 4 bytes in size,
49564 ** any group of 3 or fewer unused bytes in the cell content area cannot
49565 ** exist on the freeblock chain.  A group of 3 or fewer free bytes is called
49566 ** a fragment.  The total number of bytes in all fragments is recorded.
49567 ** in the page header at offset 7.
49568 **
49569 **    SIZE    DESCRIPTION
49570 **      2     Byte offset of the next freeblock
49571 **      2     Bytes in this freeblock
49572 **
49573 ** Cells are of variable length.  Cells are stored in the cell content area at
49574 ** the end of the page.  Pointers to the cells are in the cell pointer array
49575 ** that immediately follows the page header.  Cells is not necessarily
49576 ** contiguous or in order, but cell pointers are contiguous and in order.
49577 **
49578 ** Cell content makes use of variable length integers.  A variable
49579 ** length integer is 1 to 9 bytes where the lower 7 bits of each 
49580 ** byte are used.  The integer consists of all bytes that have bit 8 set and
49581 ** the first byte with bit 8 clear.  The most significant byte of the integer
49582 ** appears first.  A variable-length integer may not be more than 9 bytes long.
49583 ** As a special case, all 8 bytes of the 9th byte are used as data.  This
49584 ** allows a 64-bit integer to be encoded in 9 bytes.
49585 **
49586 **    0x00                      becomes  0x00000000
49587 **    0x7f                      becomes  0x0000007f
49588 **    0x81 0x00                 becomes  0x00000080
49589 **    0x82 0x00                 becomes  0x00000100
49590 **    0x80 0x7f                 becomes  0x0000007f
49591 **    0x8a 0x91 0xd1 0xac 0x78  becomes  0x12345678
49592 **    0x81 0x81 0x81 0x81 0x01  becomes  0x10204081
49593 **
49594 ** Variable length integers are used for rowids and to hold the number of
49595 ** bytes of key and data in a btree cell.
49596 **
49597 ** The content of a cell looks like this:
49598 **
49599 **    SIZE    DESCRIPTION
49600 **      4     Page number of the left child. Omitted if leaf flag is set.
49601 **     var    Number of bytes of data. Omitted if the zerodata flag is set.
49602 **     var    Number of bytes of key. Or the key itself if intkey flag is set.
49603 **      *     Payload
49604 **      4     First page of the overflow chain.  Omitted if no overflow
49605 **
49606 ** Overflow pages form a linked list.  Each page except the last is completely
49607 ** filled with data (pagesize - 4 bytes).  The last page can have as little
49608 ** as 1 byte of data.
49609 **
49610 **    SIZE    DESCRIPTION
49611 **      4     Page number of next overflow page
49612 **      *     Data
49613 **
49614 ** Freelist pages come in two subtypes: trunk pages and leaf pages.  The
49615 ** file header points to the first in a linked list of trunk page.  Each trunk
49616 ** page points to multiple leaf pages.  The content of a leaf page is
49617 ** unspecified.  A trunk page looks like this:
49618 **
49619 **    SIZE    DESCRIPTION
49620 **      4     Page number of next trunk page
49621 **      4     Number of leaf pointers on this page
49622 **      *     zero or more pages numbers of leaves
49623 */
49624 
49625 
49626 /* The following value is the maximum cell size assuming a maximum page
49627 ** size give above.
49628 */
49629 #define MX_CELL_SIZE(pBt)  ((int)(pBt->pageSize-8))
49630 
49631 /* The maximum number of cells on a single page of the database.  This
49632 ** assumes a minimum cell size of 6 bytes  (4 bytes for the cell itself
49633 ** plus 2 bytes for the index to the cell in the page header).  Such
49634 ** small cells will be rare, but they are possible.
49635 */
49636 #define MX_CELL(pBt) ((pBt->pageSize-8)/6)
49637 
49638 /* Forward declarations */
49639 typedef struct MemPage MemPage;
49640 typedef struct BtLock BtLock;
49641 
49642 /*
49643 ** This is a magic string that appears at the beginning of every
49644 ** SQLite database in order to identify the file as a real database.
49645 **
49646 ** You can change this value at compile-time by specifying a
49647 ** -DSQLITE_FILE_HEADER="..." on the compiler command-line.  The
49648 ** header must be exactly 16 bytes including the zero-terminator so
49649 ** the string itself should be 15 characters long.  If you change
49650 ** the header, then your custom library will not be able to read 
49651 ** databases generated by the standard tools and the standard tools
49652 ** will not be able to read databases created by your custom library.
49653 */
49654 #ifndef SQLITE_FILE_HEADER /* 123456789 123456 */
49655 #  define SQLITE_FILE_HEADER "SQLite format 3"
49656 #endif
49657 
49658 /*
49659 ** Page type flags.  An ORed combination of these flags appear as the
49660 ** first byte of on-disk image of every BTree page.
49661 */
49662 #define PTF_INTKEY    0x01
49663 #define PTF_ZERODATA  0x02
49664 #define PTF_LEAFDATA  0x04
49665 #define PTF_LEAF      0x08
49666 
49667 /*
49668 ** As each page of the file is loaded into memory, an instance of the following
49669 ** structure is appended and initialized to zero.  This structure stores
49670 ** information about the page that is decoded from the raw file page.
49671 **
49672 ** The pParent field points back to the parent page.  This allows us to
49673 ** walk up the BTree from any leaf to the root.  Care must be taken to
49674 ** unref() the parent page pointer when this page is no longer referenced.
49675 ** The pageDestructor() routine handles that chore.
49676 **
49677 ** Access to all fields of this structure is controlled by the mutex
49678 ** stored in MemPage.pBt->mutex.
49679 */
49680 struct MemPage {
49681   u8 isInit;           /* True if previously initialized. MUST BE FIRST! */
49682   u8 nOverflow;        /* Number of overflow cell bodies in aCell[] */
49683   u8 intKey;           /* True if intkey flag is set */
49684   u8 leaf;             /* True if leaf flag is set */
49685   u8 hasData;          /* True if this page stores data */
49686   u8 hdrOffset;        /* 100 for page 1.  0 otherwise */
49687   u8 childPtrSize;     /* 0 if leaf==1.  4 if leaf==0 */
49688   u8 max1bytePayload;  /* min(maxLocal,127) */
49689   u16 maxLocal;        /* Copy of BtShared.maxLocal or BtShared.maxLeaf */
49690   u16 minLocal;        /* Copy of BtShared.minLocal or BtShared.minLeaf */
49691   u16 cellOffset;      /* Index in aData of first cell pointer */
49692   u16 nFree;           /* Number of free bytes on the page */
49693   u16 nCell;           /* Number of cells on this page, local and ovfl */
49694   u16 maskPage;        /* Mask for page offset */
49695   u16 aiOvfl[5];       /* Insert the i-th overflow cell before the aiOvfl-th
49696                        ** non-overflow cell */
49697   u8 *apOvfl[5];       /* Pointers to the body of overflow cells */
49698   BtShared *pBt;       /* Pointer to BtShared that this page is part of */
49699   u8 *aData;           /* Pointer to disk image of the page data */
49700   u8 *aDataEnd;        /* One byte past the end of usable data */
49701   u8 *aCellIdx;        /* The cell index area */
49702   DbPage *pDbPage;     /* Pager page handle */
49703   Pgno pgno;           /* Page number for this page */
49704 };
49705 
49706 /*
49707 ** The in-memory image of a disk page has the auxiliary information appended
49708 ** to the end.  EXTRA_SIZE is the number of bytes of space needed to hold
49709 ** that extra information.
49710 */
49711 #define EXTRA_SIZE sizeof(MemPage)
49712 
49713 /*
49714 ** A linked list of the following structures is stored at BtShared.pLock.
49715 ** Locks are added (or upgraded from READ_LOCK to WRITE_LOCK) when a cursor 
49716 ** is opened on the table with root page BtShared.iTable. Locks are removed
49717 ** from this list when a transaction is committed or rolled back, or when
49718 ** a btree handle is closed.
49719 */
49720 struct BtLock {
49721   Btree *pBtree;        /* Btree handle holding this lock */
49722   Pgno iTable;          /* Root page of table */
49723   u8 eLock;             /* READ_LOCK or WRITE_LOCK */
49724   BtLock *pNext;        /* Next in BtShared.pLock list */
49725 };
49726 
49727 /* Candidate values for BtLock.eLock */
49728 #define READ_LOCK     1
49729 #define WRITE_LOCK    2
49730 
49731 /* A Btree handle
49732 **
49733 ** A database connection contains a pointer to an instance of
49734 ** this object for every database file that it has open.  This structure
49735 ** is opaque to the database connection.  The database connection cannot
49736 ** see the internals of this structure and only deals with pointers to
49737 ** this structure.
49738 **
49739 ** For some database files, the same underlying database cache might be 
49740 ** shared between multiple connections.  In that case, each connection
49741 ** has it own instance of this object.  But each instance of this object
49742 ** points to the same BtShared object.  The database cache and the
49743 ** schema associated with the database file are all contained within
49744 ** the BtShared object.
49745 **
49746 ** All fields in this structure are accessed under sqlite3.mutex.
49747 ** The pBt pointer itself may not be changed while there exists cursors 
49748 ** in the referenced BtShared that point back to this Btree since those
49749 ** cursors have to go through this Btree to find their BtShared and
49750 ** they often do so without holding sqlite3.mutex.
49751 */
49752 struct Btree {
49753   sqlite3 *db;       /* The database connection holding this btree */
49754   BtShared *pBt;     /* Sharable content of this btree */
49755   u8 inTrans;        /* TRANS_NONE, TRANS_READ or TRANS_WRITE */
49756   u8 sharable;       /* True if we can share pBt with another db */
49757   u8 locked;         /* True if db currently has pBt locked */
49758   int wantToLock;    /* Number of nested calls to sqlite3BtreeEnter() */
49759   int nBackup;       /* Number of backup operations reading this btree */
49760   Btree *pNext;      /* List of other sharable Btrees from the same db */
49761   Btree *pPrev;      /* Back pointer of the same list */
49762 #ifndef SQLITE_OMIT_SHARED_CACHE
49763   BtLock lock;       /* Object used to lock page 1 */
49764 #endif
49765 };
49766 
49767 /*
49768 ** Btree.inTrans may take one of the following values.
49769 **
49770 ** If the shared-data extension is enabled, there may be multiple users
49771 ** of the Btree structure. At most one of these may open a write transaction,
49772 ** but any number may have active read transactions.
49773 */
49774 #define TRANS_NONE  0
49775 #define TRANS_READ  1
49776 #define TRANS_WRITE 2
49777 
49778 /*
49779 ** An instance of this object represents a single database file.
49780 ** 
49781 ** A single database file can be in use at the same time by two
49782 ** or more database connections.  When two or more connections are
49783 ** sharing the same database file, each connection has it own
49784 ** private Btree object for the file and each of those Btrees points
49785 ** to this one BtShared object.  BtShared.nRef is the number of
49786 ** connections currently sharing this database file.
49787 **
49788 ** Fields in this structure are accessed under the BtShared.mutex
49789 ** mutex, except for nRef and pNext which are accessed under the
49790 ** global SQLITE_MUTEX_STATIC_MASTER mutex.  The pPager field
49791 ** may not be modified once it is initially set as long as nRef>0.
49792 ** The pSchema field may be set once under BtShared.mutex and
49793 ** thereafter is unchanged as long as nRef>0.
49794 **
49795 ** isPending:
49796 **
49797 **   If a BtShared client fails to obtain a write-lock on a database
49798 **   table (because there exists one or more read-locks on the table),
49799 **   the shared-cache enters 'pending-lock' state and isPending is
49800 **   set to true.
49801 **
49802 **   The shared-cache leaves the 'pending lock' state when either of
49803 **   the following occur:
49804 **
49805 **     1) The current writer (BtShared.pWriter) concludes its transaction, OR
49806 **     2) The number of locks held by other connections drops to zero.
49807 **
49808 **   while in the 'pending-lock' state, no connection may start a new
49809 **   transaction.
49810 **
49811 **   This feature is included to help prevent writer-starvation.
49812 */
49813 struct BtShared {
49814   Pager *pPager;        /* The page cache */
49815   sqlite3 *db;          /* Database connection currently using this Btree */
49816   BtCursor *pCursor;    /* A list of all open cursors */
49817   MemPage *pPage1;      /* First page of the database */
49818   u8 openFlags;         /* Flags to sqlite3BtreeOpen() */
49819 #ifndef SQLITE_OMIT_AUTOVACUUM
49820   u8 autoVacuum;        /* True if auto-vacuum is enabled */
49821   u8 incrVacuum;        /* True if incr-vacuum is enabled */
49822   u8 bDoTruncate;       /* True to truncate db on commit */
49823 #endif
49824   u8 inTransaction;     /* Transaction state */
49825   u8 max1bytePayload;   /* Maximum first byte of cell for a 1-byte payload */
49826   u16 btsFlags;         /* Boolean parameters.  See BTS_* macros below */
49827   u16 maxLocal;         /* Maximum local payload in non-LEAFDATA tables */
49828   u16 minLocal;         /* Minimum local payload in non-LEAFDATA tables */
49829   u16 maxLeaf;          /* Maximum local payload in a LEAFDATA table */
49830   u16 minLeaf;          /* Minimum local payload in a LEAFDATA table */
49831   u32 pageSize;         /* Total number of bytes on a page */
49832   u32 usableSize;       /* Number of usable bytes on each page */
49833   int nTransaction;     /* Number of open transactions (read + write) */
49834   u32 nPage;            /* Number of pages in the database */
49835   void *pSchema;        /* Pointer to space allocated by sqlite3BtreeSchema() */
49836   void (*xFreeSchema)(void*);  /* Destructor for BtShared.pSchema */
49837   sqlite3_mutex *mutex; /* Non-recursive mutex required to access this object */
49838   Bitvec *pHasContent;  /* Set of pages moved to free-list this transaction */
49839 #ifndef SQLITE_OMIT_SHARED_CACHE
49840   int nRef;             /* Number of references to this structure */
49841   BtShared *pNext;      /* Next on a list of sharable BtShared structs */
49842   BtLock *pLock;        /* List of locks held on this shared-btree struct */
49843   Btree *pWriter;       /* Btree with currently open write transaction */
49844 #endif
49845   u8 *pTmpSpace;        /* BtShared.pageSize bytes of space for tmp use */
49846 };
49847 
49848 /*
49849 ** Allowed values for BtShared.btsFlags
49850 */
49851 #define BTS_READ_ONLY        0x0001   /* Underlying file is readonly */
49852 #define BTS_PAGESIZE_FIXED   0x0002   /* Page size can no longer be changed */
49853 #define BTS_SECURE_DELETE    0x0004   /* PRAGMA secure_delete is enabled */
49854 #define BTS_INITIALLY_EMPTY  0x0008   /* Database was empty at trans start */
49855 #define BTS_NO_WAL           0x0010   /* Do not open write-ahead-log files */
49856 #define BTS_EXCLUSIVE        0x0020   /* pWriter has an exclusive lock */
49857 #define BTS_PENDING          0x0040   /* Waiting for read-locks to clear */
49858 
49859 /*
49860 ** An instance of the following structure is used to hold information
49861 ** about a cell.  The parseCellPtr() function fills in this structure
49862 ** based on information extract from the raw disk page.
49863 */
49864 typedef struct CellInfo CellInfo;
49865 struct CellInfo {
49866   i64 nKey;      /* The key for INTKEY tables, or number of bytes in key */
49867   u8 *pCell;     /* Pointer to the start of cell content */
49868   u32 nData;     /* Number of bytes of data */
49869   u32 nPayload;  /* Total amount of payload */
49870   u16 nHeader;   /* Size of the cell content header in bytes */
49871   u16 nLocal;    /* Amount of payload held locally */
49872   u16 iOverflow; /* Offset to overflow page number.  Zero if no overflow */
49873   u16 nSize;     /* Size of the cell content on the main b-tree page */
49874 };
49875 
49876 /*
49877 ** Maximum depth of an SQLite B-Tree structure. Any B-Tree deeper than
49878 ** this will be declared corrupt. This value is calculated based on a
49879 ** maximum database size of 2^31 pages a minimum fanout of 2 for a
49880 ** root-node and 3 for all other internal nodes.
49881 **
49882 ** If a tree that appears to be taller than this is encountered, it is
49883 ** assumed that the database is corrupt.
49884 */
49885 #define BTCURSOR_MAX_DEPTH 20
49886 
49887 /*
49888 ** A cursor is a pointer to a particular entry within a particular
49889 ** b-tree within a database file.
49890 **
49891 ** The entry is identified by its MemPage and the index in
49892 ** MemPage.aCell[] of the entry.
49893 **
49894 ** A single database file can be shared by two more database connections,
49895 ** but cursors cannot be shared.  Each cursor is associated with a
49896 ** particular database connection identified BtCursor.pBtree.db.
49897 **
49898 ** Fields in this structure are accessed under the BtShared.mutex
49899 ** found at self->pBt->mutex. 
49900 */
49901 struct BtCursor {
49902   Btree *pBtree;            /* The Btree to which this cursor belongs */
49903   BtShared *pBt;            /* The BtShared this cursor points to */
49904   BtCursor *pNext, *pPrev;  /* Forms a linked list of all cursors */
49905   struct KeyInfo *pKeyInfo; /* Argument passed to comparison function */
49906 #ifndef SQLITE_OMIT_INCRBLOB
49907   Pgno *aOverflow;          /* Cache of overflow page locations */
49908 #endif
49909   Pgno pgnoRoot;            /* The root page of this tree */
49910   sqlite3_int64 cachedRowid; /* Next rowid cache.  0 means not valid */
49911   CellInfo info;            /* A parse of the cell we are pointing at */
49912   i64 nKey;        /* Size of pKey, or last integer key */
49913   void *pKey;      /* Saved key that was cursor's last known position */
49914   int skipNext;    /* Prev() is noop if negative. Next() is noop if positive */
49915   u8 wrFlag;                /* True if writable */
49916   u8 atLast;                /* Cursor pointing to the last entry */
49917   u8 validNKey;             /* True if info.nKey is valid */
49918   u8 eState;                /* One of the CURSOR_XXX constants (see below) */
49919 #ifndef SQLITE_OMIT_INCRBLOB
49920   u8 isIncrblobHandle;      /* True if this cursor is an incr. io handle */
49921 #endif
49922   u8 hints;                             /* As configured by CursorSetHints() */
49923   i16 iPage;                            /* Index of current page in apPage */
49924   u16 aiIdx[BTCURSOR_MAX_DEPTH];        /* Current index in apPage[i] */
49925   MemPage *apPage[BTCURSOR_MAX_DEPTH];  /* Pages from root to current page */
49926 };
49927 
49928 /*
49929 ** Potential values for BtCursor.eState.
49930 **
49931 ** CURSOR_INVALID:
49932 **   Cursor does not point to a valid entry. This can happen (for example) 
49933 **   because the table is empty or because BtreeCursorFirst() has not been
49934 **   called.
49935 **
49936 ** CURSOR_VALID:
49937 **   Cursor points to a valid entry. getPayload() etc. may be called.
49938 **
49939 ** CURSOR_SKIPNEXT:
49940 **   Cursor is valid except that the Cursor.skipNext field is non-zero
49941 **   indicating that the next sqlite3BtreeNext() or sqlite3BtreePrevious()
49942 **   operation should be a no-op.
49943 **
49944 ** CURSOR_REQUIRESEEK:
49945 **   The table that this cursor was opened on still exists, but has been 
49946 **   modified since the cursor was last used. The cursor position is saved
49947 **   in variables BtCursor.pKey and BtCursor.nKey. When a cursor is in 
49948 **   this state, restoreCursorPosition() can be called to attempt to
49949 **   seek the cursor to the saved position.
49950 **
49951 ** CURSOR_FAULT:
49952 **   A unrecoverable error (an I/O error or a malloc failure) has occurred
49953 **   on a different connection that shares the BtShared cache with this
49954 **   cursor.  The error has left the cache in an inconsistent state.
49955 **   Do nothing else with this cursor.  Any attempt to use the cursor
49956 **   should return the error code stored in BtCursor.skip
49957 */
49958 #define CURSOR_INVALID           0
49959 #define CURSOR_VALID             1
49960 #define CURSOR_SKIPNEXT          2
49961 #define CURSOR_REQUIRESEEK       3
49962 #define CURSOR_FAULT             4
49963 
49964 /* 
49965 ** The database page the PENDING_BYTE occupies. This page is never used.
49966 */
49967 # define PENDING_BYTE_PAGE(pBt) PAGER_MJ_PGNO(pBt)
49968 
49969 /*
49970 ** These macros define the location of the pointer-map entry for a 
49971 ** database page. The first argument to each is the number of usable
49972 ** bytes on each page of the database (often 1024). The second is the
49973 ** page number to look up in the pointer map.
49974 **
49975 ** PTRMAP_PAGENO returns the database page number of the pointer-map
49976 ** page that stores the required pointer. PTRMAP_PTROFFSET returns
49977 ** the offset of the requested map entry.
49978 **
49979 ** If the pgno argument passed to PTRMAP_PAGENO is a pointer-map page,
49980 ** then pgno is returned. So (pgno==PTRMAP_PAGENO(pgsz, pgno)) can be
49981 ** used to test if pgno is a pointer-map page. PTRMAP_ISPAGE implements
49982 ** this test.
49983 */
49984 #define PTRMAP_PAGENO(pBt, pgno) ptrmapPageno(pBt, pgno)
49985 #define PTRMAP_PTROFFSET(pgptrmap, pgno) (5*(pgno-pgptrmap-1))
49986 #define PTRMAP_ISPAGE(pBt, pgno) (PTRMAP_PAGENO((pBt),(pgno))==(pgno))
49987 
49988 /*
49989 ** The pointer map is a lookup table that identifies the parent page for
49990 ** each child page in the database file.  The parent page is the page that
49991 ** contains a pointer to the child.  Every page in the database contains
49992 ** 0 or 1 parent pages.  (In this context 'database page' refers
49993 ** to any page that is not part of the pointer map itself.)  Each pointer map
49994 ** entry consists of a single byte 'type' and a 4 byte parent page number.
49995 ** The PTRMAP_XXX identifiers below are the valid types.
49996 **
49997 ** The purpose of the pointer map is to facility moving pages from one
49998 ** position in the file to another as part of autovacuum.  When a page
49999 ** is moved, the pointer in its parent must be updated to point to the
50000 ** new location.  The pointer map is used to locate the parent page quickly.
50001 **
50002 ** PTRMAP_ROOTPAGE: The database page is a root-page. The page-number is not
50003 **                  used in this case.
50004 **
50005 ** PTRMAP_FREEPAGE: The database page is an unused (free) page. The page-number 
50006 **                  is not used in this case.
50007 **
50008 ** PTRMAP_OVERFLOW1: The database page is the first page in a list of 
50009 **                   overflow pages. The page number identifies the page that
50010 **                   contains the cell with a pointer to this overflow page.
50011 **
50012 ** PTRMAP_OVERFLOW2: The database page is the second or later page in a list of
50013 **                   overflow pages. The page-number identifies the previous
50014 **                   page in the overflow page list.
50015 **
50016 ** PTRMAP_BTREE: The database page is a non-root btree page. The page number
50017 **               identifies the parent page in the btree.
50018 */
50019 #define PTRMAP_ROOTPAGE 1
50020 #define PTRMAP_FREEPAGE 2
50021 #define PTRMAP_OVERFLOW1 3
50022 #define PTRMAP_OVERFLOW2 4
50023 #define PTRMAP_BTREE 5
50024 
50025 /* A bunch of assert() statements to check the transaction state variables
50026 ** of handle p (type Btree*) are internally consistent.
50027 */
50028 #define btreeIntegrity(p) \
50029   assert( p->pBt->inTransaction!=TRANS_NONE || p->pBt->nTransaction==0 ); \
50030   assert( p->pBt->inTransaction>=p->inTrans ); 
50031 
50032 
50033 /*
50034 ** The ISAUTOVACUUM macro is used within balance_nonroot() to determine
50035 ** if the database supports auto-vacuum or not. Because it is used
50036 ** within an expression that is an argument to another macro 
50037 ** (sqliteMallocRaw), it is not possible to use conditional compilation.
50038 ** So, this macro is defined instead.
50039 */
50040 #ifndef SQLITE_OMIT_AUTOVACUUM
50041 #define ISAUTOVACUUM (pBt->autoVacuum)
50042 #else
50043 #define ISAUTOVACUUM 0
50044 #endif
50045 
50046 
50047 /*
50048 ** This structure is passed around through all the sanity checking routines
50049 ** in order to keep track of some global state information.
50050 **
50051 ** The aRef[] array is allocated so that there is 1 bit for each page in
50052 ** the database. As the integrity-check proceeds, for each page used in
50053 ** the database the corresponding bit is set. This allows integrity-check to 
50054 ** detect pages that are used twice and orphaned pages (both of which 
50055 ** indicate corruption).
50056 */
50057 typedef struct IntegrityCk IntegrityCk;
50058 struct IntegrityCk {
50059   BtShared *pBt;    /* The tree being checked out */
50060   Pager *pPager;    /* The associated pager.  Also accessible by pBt->pPager */
50061   u8 *aPgRef;       /* 1 bit per page in the db (see above) */
50062   Pgno nPage;       /* Number of pages in the database */
50063   int mxErr;        /* Stop accumulating errors when this reaches zero */
50064   int nErr;         /* Number of messages written to zErrMsg so far */
50065   int mallocFailed; /* A memory allocation error has occurred */
50066   StrAccum errMsg;  /* Accumulate the error message text here */
50067 };
50068 
50069 /*
50070 ** Routines to read or write a two- and four-byte big-endian integer values.
50071 */
50072 #define get2byte(x)   ((x)[0]<<8 | (x)[1])
50073 #define put2byte(p,v) ((p)[0] = (u8)((v)>>8), (p)[1] = (u8)(v))
50074 #define get4byte sqlite3Get4byte
50075 #define put4byte sqlite3Put4byte
50076 
50077 /************** End of btreeInt.h ********************************************/
50078 /************** Continuing where we left off in btmutex.c ********************/
50079 #ifndef SQLITE_OMIT_SHARED_CACHE
50080 #if SQLITE_THREADSAFE
50081 
50082 /*
50083 ** Obtain the BtShared mutex associated with B-Tree handle p. Also,
50084 ** set BtShared.db to the database handle associated with p and the
50085 ** p->locked boolean to true.
50086 */
50087 static void lockBtreeMutex(Btree *p){
50088   assert( p->locked==0 );
50089   assert( sqlite3_mutex_notheld(p->pBt->mutex) );
50090   assert( sqlite3_mutex_held(p->db->mutex) );
50091 
50092   sqlite3_mutex_enter(p->pBt->mutex);
50093   p->pBt->db = p->db;
50094   p->locked = 1;
50095 }
50096 
50097 /*
50098 ** Release the BtShared mutex associated with B-Tree handle p and
50099 ** clear the p->locked boolean.
50100 */
50101 static void unlockBtreeMutex(Btree *p){
50102   BtShared *pBt = p->pBt;
50103   assert( p->locked==1 );
50104   assert( sqlite3_mutex_held(pBt->mutex) );
50105   assert( sqlite3_mutex_held(p->db->mutex) );
50106   assert( p->db==pBt->db );
50107 
50108   sqlite3_mutex_leave(pBt->mutex);
50109   p->locked = 0;
50110 }
50111 
50112 /*
50113 ** Enter a mutex on the given BTree object.
50114 **
50115 ** If the object is not sharable, then no mutex is ever required
50116 ** and this routine is a no-op.  The underlying mutex is non-recursive.
50117 ** But we keep a reference count in Btree.wantToLock so the behavior
50118 ** of this interface is recursive.
50119 **
50120 ** To avoid deadlocks, multiple Btrees are locked in the same order
50121 ** by all database connections.  The p->pNext is a list of other
50122 ** Btrees belonging to the same database connection as the p Btree
50123 ** which need to be locked after p.  If we cannot get a lock on
50124 ** p, then first unlock all of the others on p->pNext, then wait
50125 ** for the lock to become available on p, then relock all of the
50126 ** subsequent Btrees that desire a lock.
50127 */
50128 SQLITE_PRIVATE void sqlite3BtreeEnter(Btree *p){
50129   Btree *pLater;
50130 
50131   /* Some basic sanity checking on the Btree.  The list of Btrees
50132   ** connected by pNext and pPrev should be in sorted order by
50133   ** Btree.pBt value. All elements of the list should belong to
50134   ** the same connection. Only shared Btrees are on the list. */
50135   assert( p->pNext==0 || p->pNext->pBt>p->pBt );
50136   assert( p->pPrev==0 || p->pPrev->pBt<p->pBt );
50137   assert( p->pNext==0 || p->pNext->db==p->db );
50138   assert( p->pPrev==0 || p->pPrev->db==p->db );
50139   assert( p->sharable || (p->pNext==0 && p->pPrev==0) );
50140 
50141   /* Check for locking consistency */
50142   assert( !p->locked || p->wantToLock>0 );
50143   assert( p->sharable || p->wantToLock==0 );
50144 
50145   /* We should already hold a lock on the database connection */
50146   assert( sqlite3_mutex_held(p->db->mutex) );
50147 
50148   /* Unless the database is sharable and unlocked, then BtShared.db
50149   ** should already be set correctly. */
50150   assert( (p->locked==0 && p->sharable) || p->pBt->db==p->db );
50151 
50152   if( !p->sharable ) return;
50153   p->wantToLock++;
50154   if( p->locked ) return;
50155 
50156   /* In most cases, we should be able to acquire the lock we
50157   ** want without having to go throught the ascending lock
50158   ** procedure that follows.  Just be sure not to block.
50159   */
50160   if( sqlite3_mutex_try(p->pBt->mutex)==SQLITE_OK ){
50161     p->pBt->db = p->db;
50162     p->locked = 1;
50163     return;
50164   }
50165 
50166   /* To avoid deadlock, first release all locks with a larger
50167   ** BtShared address.  Then acquire our lock.  Then reacquire
50168   ** the other BtShared locks that we used to hold in ascending
50169   ** order.
50170   */
50171   for(pLater=p->pNext; pLater; pLater=pLater->pNext){
50172     assert( pLater->sharable );
50173     assert( pLater->pNext==0 || pLater->pNext->pBt>pLater->pBt );
50174     assert( !pLater->locked || pLater->wantToLock>0 );
50175     if( pLater->locked ){
50176       unlockBtreeMutex(pLater);
50177     }
50178   }
50179   lockBtreeMutex(p);
50180   for(pLater=p->pNext; pLater; pLater=pLater->pNext){
50181     if( pLater->wantToLock ){
50182       lockBtreeMutex(pLater);
50183     }
50184   }
50185 }
50186 
50187 /*
50188 ** Exit the recursive mutex on a Btree.
50189 */
50190 SQLITE_PRIVATE void sqlite3BtreeLeave(Btree *p){
50191   if( p->sharable ){
50192     assert( p->wantToLock>0 );
50193     p->wantToLock--;
50194     if( p->wantToLock==0 ){
50195       unlockBtreeMutex(p);
50196     }
50197   }
50198 }
50199 
50200 #ifndef NDEBUG
50201 /*
50202 ** Return true if the BtShared mutex is held on the btree, or if the
50203 ** B-Tree is not marked as sharable.
50204 **
50205 ** This routine is used only from within assert() statements.
50206 */
50207 SQLITE_PRIVATE int sqlite3BtreeHoldsMutex(Btree *p){
50208   assert( p->sharable==0 || p->locked==0 || p->wantToLock>0 );
50209   assert( p->sharable==0 || p->locked==0 || p->db==p->pBt->db );
50210   assert( p->sharable==0 || p->locked==0 || sqlite3_mutex_held(p->pBt->mutex) );
50211   assert( p->sharable==0 || p->locked==0 || sqlite3_mutex_held(p->db->mutex) );
50212 
50213   return (p->sharable==0 || p->locked);
50214 }
50215 #endif
50216 
50217 
50218 #ifndef SQLITE_OMIT_INCRBLOB
50219 /*
50220 ** Enter and leave a mutex on a Btree given a cursor owned by that
50221 ** Btree.  These entry points are used by incremental I/O and can be
50222 ** omitted if that module is not used.
50223 */
50224 SQLITE_PRIVATE void sqlite3BtreeEnterCursor(BtCursor *pCur){
50225   sqlite3BtreeEnter(pCur->pBtree);
50226 }
50227 SQLITE_PRIVATE void sqlite3BtreeLeaveCursor(BtCursor *pCur){
50228   sqlite3BtreeLeave(pCur->pBtree);
50229 }
50230 #endif /* SQLITE_OMIT_INCRBLOB */
50231 
50232 
50233 /*
50234 ** Enter the mutex on every Btree associated with a database
50235 ** connection.  This is needed (for example) prior to parsing
50236 ** a statement since we will be comparing table and column names
50237 ** against all schemas and we do not want those schemas being
50238 ** reset out from under us.
50239 **
50240 ** There is a corresponding leave-all procedures.
50241 **
50242 ** Enter the mutexes in accending order by BtShared pointer address
50243 ** to avoid the possibility of deadlock when two threads with
50244 ** two or more btrees in common both try to lock all their btrees
50245 ** at the same instant.
50246 */
50247 SQLITE_PRIVATE void sqlite3BtreeEnterAll(sqlite3 *db){
50248   int i;
50249   Btree *p;
50250   assert( sqlite3_mutex_held(db->mutex) );
50251   for(i=0; i<db->nDb; i++){
50252     p = db->aDb[i].pBt;
50253     if( p ) sqlite3BtreeEnter(p);
50254   }
50255 }
50256 SQLITE_PRIVATE void sqlite3BtreeLeaveAll(sqlite3 *db){
50257   int i;
50258   Btree *p;
50259   assert( sqlite3_mutex_held(db->mutex) );
50260   for(i=0; i<db->nDb; i++){
50261     p = db->aDb[i].pBt;
50262     if( p ) sqlite3BtreeLeave(p);
50263   }
50264 }
50265 
50266 /*
50267 ** Return true if a particular Btree requires a lock.  Return FALSE if
50268 ** no lock is ever required since it is not sharable.
50269 */
50270 SQLITE_PRIVATE int sqlite3BtreeSharable(Btree *p){
50271   return p->sharable;
50272 }
50273 
50274 #ifndef NDEBUG
50275 /*
50276 ** Return true if the current thread holds the database connection
50277 ** mutex and all required BtShared mutexes.
50278 **
50279 ** This routine is used inside assert() statements only.
50280 */
50281 SQLITE_PRIVATE int sqlite3BtreeHoldsAllMutexes(sqlite3 *db){
50282   int i;
50283   if( !sqlite3_mutex_held(db->mutex) ){
50284     return 0;
50285   }
50286   for(i=0; i<db->nDb; i++){
50287     Btree *p;
50288     p = db->aDb[i].pBt;
50289     if( p && p->sharable &&
50290          (p->wantToLock==0 || !sqlite3_mutex_held(p->pBt->mutex)) ){
50291       return 0;
50292     }
50293   }
50294   return 1;
50295 }
50296 #endif /* NDEBUG */
50297 
50298 #ifndef NDEBUG
50299 /*
50300 ** Return true if the correct mutexes are held for accessing the
50301 ** db->aDb[iDb].pSchema structure.  The mutexes required for schema
50302 ** access are:
50303 **
50304 **   (1) The mutex on db
50305 **   (2) if iDb!=1, then the mutex on db->aDb[iDb].pBt.
50306 **
50307 ** If pSchema is not NULL, then iDb is computed from pSchema and
50308 ** db using sqlite3SchemaToIndex().
50309 */
50310 SQLITE_PRIVATE int sqlite3SchemaMutexHeld(sqlite3 *db, int iDb, Schema *pSchema){
50311   Btree *p;
50312   assert( db!=0 );
50313   if( pSchema ) iDb = sqlite3SchemaToIndex(db, pSchema);
50314   assert( iDb>=0 && iDb<db->nDb );
50315   if( !sqlite3_mutex_held(db->mutex) ) return 0;
50316   if( iDb==1 ) return 1;
50317   p = db->aDb[iDb].pBt;
50318   assert( p!=0 );
50319   return p->sharable==0 || p->locked==1;
50320 }
50321 #endif /* NDEBUG */
50322 
50323 #else /* SQLITE_THREADSAFE>0 above.  SQLITE_THREADSAFE==0 below */
50324 /*
50325 ** The following are special cases for mutex enter routines for use
50326 ** in single threaded applications that use shared cache.  Except for
50327 ** these two routines, all mutex operations are no-ops in that case and
50328 ** are null #defines in btree.h.
50329 **
50330 ** If shared cache is disabled, then all btree mutex routines, including
50331 ** the ones below, are no-ops and are null #defines in btree.h.
50332 */
50333 
50334 SQLITE_PRIVATE void sqlite3BtreeEnter(Btree *p){
50335   p->pBt->db = p->db;
50336 }
50337 SQLITE_PRIVATE void sqlite3BtreeEnterAll(sqlite3 *db){
50338   int i;
50339   for(i=0; i<db->nDb; i++){
50340     Btree *p = db->aDb[i].pBt;
50341     if( p ){
50342       p->pBt->db = p->db;
50343     }
50344   }
50345 }
50346 #endif /* if SQLITE_THREADSAFE */
50347 #endif /* ifndef SQLITE_OMIT_SHARED_CACHE */
50348 
50349 /************** End of btmutex.c *********************************************/
50350 /************** Begin file btree.c *******************************************/
50351 /*
50352 ** 2004 April 6
50353 **
50354 ** The author disclaims copyright to this source code.  In place of
50355 ** a legal notice, here is a blessing:
50356 **
50357 **    May you do good and not evil.
50358 **    May you find forgiveness for yourself and forgive others.
50359 **    May you share freely, never taking more than you give.
50360 **
50361 *************************************************************************
50362 ** This file implements a external (disk-based) database using BTrees.
50363 ** See the header comment on "btreeInt.h" for additional information.
50364 ** Including a description of file format and an overview of operation.
50365 */
50366 
50367 /*
50368 ** The header string that appears at the beginning of every
50369 ** SQLite database.
50370 */
50371 static const char zMagicHeader[] = SQLITE_FILE_HEADER;
50372 
50373 /*
50374 ** Set this global variable to 1 to enable tracing using the TRACE
50375 ** macro.
50376 */
50377 #if 0
50378 int sqlite3BtreeTrace=1;  /* True to enable tracing */
50379 # define TRACE(X)  if(sqlite3BtreeTrace){printf X;fflush(stdout);}
50380 #else
50381 # define TRACE(X)
50382 #endif
50383 
50384 /*
50385 ** Extract a 2-byte big-endian integer from an array of unsigned bytes.
50386 ** But if the value is zero, make it 65536.
50387 **
50388 ** This routine is used to extract the "offset to cell content area" value
50389 ** from the header of a btree page.  If the page size is 65536 and the page
50390 ** is empty, the offset should be 65536, but the 2-byte value stores zero.
50391 ** This routine makes the necessary adjustment to 65536.
50392 */
50393 #define get2byteNotZero(X)  (((((int)get2byte(X))-1)&0xffff)+1)
50394 
50395 /*
50396 ** Values passed as the 5th argument to allocateBtreePage()
50397 */
50398 #define BTALLOC_ANY   0           /* Allocate any page */
50399 #define BTALLOC_EXACT 1           /* Allocate exact page if possible */
50400 #define BTALLOC_LE    2           /* Allocate any page <= the parameter */
50401 
50402 /*
50403 ** Macro IfNotOmitAV(x) returns (x) if SQLITE_OMIT_AUTOVACUUM is not 
50404 ** defined, or 0 if it is. For example:
50405 **
50406 **   bIncrVacuum = IfNotOmitAV(pBtShared->incrVacuum);
50407 */
50408 #ifndef SQLITE_OMIT_AUTOVACUUM
50409 #define IfNotOmitAV(expr) (expr)
50410 #else
50411 #define IfNotOmitAV(expr) 0
50412 #endif
50413 
50414 #ifndef SQLITE_OMIT_SHARED_CACHE
50415 /*
50416 ** A list of BtShared objects that are eligible for participation
50417 ** in shared cache.  This variable has file scope during normal builds,
50418 ** but the test harness needs to access it so we make it global for 
50419 ** test builds.
50420 **
50421 ** Access to this variable is protected by SQLITE_MUTEX_STATIC_MASTER.
50422 */
50423 #ifdef SQLITE_TEST
50424 SQLITE_PRIVATE BtShared *SQLITE_WSD sqlite3SharedCacheList = 0;
50425 #else
50426 static BtShared *SQLITE_WSD sqlite3SharedCacheList = 0;
50427 #endif
50428 #endif /* SQLITE_OMIT_SHARED_CACHE */
50429 
50430 #ifndef SQLITE_OMIT_SHARED_CACHE
50431 /*
50432 ** Enable or disable the shared pager and schema features.
50433 **
50434 ** This routine has no effect on existing database connections.
50435 ** The shared cache setting effects only future calls to
50436 ** sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2().
50437 */
50438 SQLITE_API int sqlite3_enable_shared_cache(int enable){
50439   sqlite3GlobalConfig.sharedCacheEnabled = enable;
50440   return SQLITE_OK;
50441 }
50442 #endif
50443 
50444 
50445 
50446 #ifdef SQLITE_OMIT_SHARED_CACHE
50447   /*
50448   ** The functions querySharedCacheTableLock(), setSharedCacheTableLock(),
50449   ** and clearAllSharedCacheTableLocks()
50450   ** manipulate entries in the BtShared.pLock linked list used to store
50451   ** shared-cache table level locks. If the library is compiled with the
50452   ** shared-cache feature disabled, then there is only ever one user
50453   ** of each BtShared structure and so this locking is not necessary. 
50454   ** So define the lock related functions as no-ops.
50455   */
50456   #define querySharedCacheTableLock(a,b,c) SQLITE_OK
50457   #define setSharedCacheTableLock(a,b,c) SQLITE_OK
50458   #define clearAllSharedCacheTableLocks(a)
50459   #define downgradeAllSharedCacheTableLocks(a)
50460   #define hasSharedCacheTableLock(a,b,c,d) 1
50461   #define hasReadConflicts(a, b) 0
50462 #endif
50463 
50464 #ifndef SQLITE_OMIT_SHARED_CACHE
50465 
50466 #ifdef SQLITE_DEBUG
50467 /*
50468 **** This function is only used as part of an assert() statement. ***
50469 **
50470 ** Check to see if pBtree holds the required locks to read or write to the 
50471 ** table with root page iRoot.   Return 1 if it does and 0 if not.
50472 **
50473 ** For example, when writing to a table with root-page iRoot via 
50474 ** Btree connection pBtree:
50475 **
50476 **    assert( hasSharedCacheTableLock(pBtree, iRoot, 0, WRITE_LOCK) );
50477 **
50478 ** When writing to an index that resides in a sharable database, the 
50479 ** caller should have first obtained a lock specifying the root page of
50480 ** the corresponding table. This makes things a bit more complicated,
50481 ** as this module treats each table as a separate structure. To determine
50482 ** the table corresponding to the index being written, this
50483 ** function has to search through the database schema.
50484 **
50485 ** Instead of a lock on the table/index rooted at page iRoot, the caller may
50486 ** hold a write-lock on the schema table (root page 1). This is also
50487 ** acceptable.
50488 */
50489 static int hasSharedCacheTableLock(
50490   Btree *pBtree,         /* Handle that must hold lock */
50491   Pgno iRoot,            /* Root page of b-tree */
50492   int isIndex,           /* True if iRoot is the root of an index b-tree */
50493   int eLockType          /* Required lock type (READ_LOCK or WRITE_LOCK) */
50494 ){
50495   Schema *pSchema = (Schema *)pBtree->pBt->pSchema;
50496   Pgno iTab = 0;
50497   BtLock *pLock;
50498 
50499   /* If this database is not shareable, or if the client is reading
50500   ** and has the read-uncommitted flag set, then no lock is required. 
50501   ** Return true immediately.
50502   */
50503   if( (pBtree->sharable==0)
50504    || (eLockType==READ_LOCK && (pBtree->db->flags & SQLITE_ReadUncommitted))
50505   ){
50506     return 1;
50507   }
50508 
50509   /* If the client is reading  or writing an index and the schema is
50510   ** not loaded, then it is too difficult to actually check to see if
50511   ** the correct locks are held.  So do not bother - just return true.
50512   ** This case does not come up very often anyhow.
50513   */
50514   if( isIndex && (!pSchema || (pSchema->flags&DB_SchemaLoaded)==0) ){
50515     return 1;
50516   }
50517 
50518   /* Figure out the root-page that the lock should be held on. For table
50519   ** b-trees, this is just the root page of the b-tree being read or
50520   ** written. For index b-trees, it is the root page of the associated
50521   ** table.  */
50522   if( isIndex ){
50523     HashElem *p;
50524     for(p=sqliteHashFirst(&pSchema->idxHash); p; p=sqliteHashNext(p)){
50525       Index *pIdx = (Index *)sqliteHashData(p);
50526       if( pIdx->tnum==(int)iRoot ){
50527         iTab = pIdx->pTable->tnum;
50528       }
50529     }
50530   }else{
50531     iTab = iRoot;
50532   }
50533 
50534   /* Search for the required lock. Either a write-lock on root-page iTab, a 
50535   ** write-lock on the schema table, or (if the client is reading) a
50536   ** read-lock on iTab will suffice. Return 1 if any of these are found.  */
50537   for(pLock=pBtree->pBt->pLock; pLock; pLock=pLock->pNext){
50538     if( pLock->pBtree==pBtree 
50539      && (pLock->iTable==iTab || (pLock->eLock==WRITE_LOCK && pLock->iTable==1))
50540      && pLock->eLock>=eLockType 
50541     ){
50542       return 1;
50543     }
50544   }
50545 
50546   /* Failed to find the required lock. */
50547   return 0;
50548 }
50549 #endif /* SQLITE_DEBUG */
50550 
50551 #ifdef SQLITE_DEBUG
50552 /*
50553 **** This function may be used as part of assert() statements only. ****
50554 **
50555 ** Return true if it would be illegal for pBtree to write into the
50556 ** table or index rooted at iRoot because other shared connections are
50557 ** simultaneously reading that same table or index.
50558 **
50559 ** It is illegal for pBtree to write if some other Btree object that
50560 ** shares the same BtShared object is currently reading or writing
50561 ** the iRoot table.  Except, if the other Btree object has the
50562 ** read-uncommitted flag set, then it is OK for the other object to
50563 ** have a read cursor.
50564 **
50565 ** For example, before writing to any part of the table or index
50566 ** rooted at page iRoot, one should call:
50567 **
50568 **    assert( !hasReadConflicts(pBtree, iRoot) );
50569 */
50570 static int hasReadConflicts(Btree *pBtree, Pgno iRoot){
50571   BtCursor *p;
50572   for(p=pBtree->pBt->pCursor; p; p=p->pNext){
50573     if( p->pgnoRoot==iRoot 
50574      && p->pBtree!=pBtree
50575      && 0==(p->pBtree->db->flags & SQLITE_ReadUncommitted)
50576     ){
50577       return 1;
50578     }
50579   }
50580   return 0;
50581 }
50582 #endif    /* #ifdef SQLITE_DEBUG */
50583 
50584 /*
50585 ** Query to see if Btree handle p may obtain a lock of type eLock 
50586 ** (READ_LOCK or WRITE_LOCK) on the table with root-page iTab. Return
50587 ** SQLITE_OK if the lock may be obtained (by calling
50588 ** setSharedCacheTableLock()), or SQLITE_LOCKED if not.
50589 */
50590 static int querySharedCacheTableLock(Btree *p, Pgno iTab, u8 eLock){
50591   BtShared *pBt = p->pBt;
50592   BtLock *pIter;
50593 
50594   assert( sqlite3BtreeHoldsMutex(p) );
50595   assert( eLock==READ_LOCK || eLock==WRITE_LOCK );
50596   assert( p->db!=0 );
50597   assert( !(p->db->flags&SQLITE_ReadUncommitted)||eLock==WRITE_LOCK||iTab==1 );
50598   
50599   /* If requesting a write-lock, then the Btree must have an open write
50600   ** transaction on this file. And, obviously, for this to be so there 
50601   ** must be an open write transaction on the file itself.
50602   */
50603   assert( eLock==READ_LOCK || (p==pBt->pWriter && p->inTrans==TRANS_WRITE) );
50604   assert( eLock==READ_LOCK || pBt->inTransaction==TRANS_WRITE );
50605   
50606   /* This routine is a no-op if the shared-cache is not enabled */
50607   if( !p->sharable ){
50608     return SQLITE_OK;
50609   }
50610 
50611   /* If some other connection is holding an exclusive lock, the
50612   ** requested lock may not be obtained.
50613   */
50614   if( pBt->pWriter!=p && (pBt->btsFlags & BTS_EXCLUSIVE)!=0 ){
50615     sqlite3ConnectionBlocked(p->db, pBt->pWriter->db);
50616     return SQLITE_LOCKED_SHAREDCACHE;
50617   }
50618 
50619   for(pIter=pBt->pLock; pIter; pIter=pIter->pNext){
50620     /* The condition (pIter->eLock!=eLock) in the following if(...) 
50621     ** statement is a simplification of:
50622     **
50623     **   (eLock==WRITE_LOCK || pIter->eLock==WRITE_LOCK)
50624     **
50625     ** since we know that if eLock==WRITE_LOCK, then no other connection
50626     ** may hold a WRITE_LOCK on any table in this file (since there can
50627     ** only be a single writer).
50628     */
50629     assert( pIter->eLock==READ_LOCK || pIter->eLock==WRITE_LOCK );
50630     assert( eLock==READ_LOCK || pIter->pBtree==p || pIter->eLock==READ_LOCK);
50631     if( pIter->pBtree!=p && pIter->iTable==iTab && pIter->eLock!=eLock ){
50632       sqlite3ConnectionBlocked(p->db, pIter->pBtree->db);
50633       if( eLock==WRITE_LOCK ){
50634         assert( p==pBt->pWriter );
50635         pBt->btsFlags |= BTS_PENDING;
50636       }
50637       return SQLITE_LOCKED_SHAREDCACHE;
50638     }
50639   }
50640   return SQLITE_OK;
50641 }
50642 #endif /* !SQLITE_OMIT_SHARED_CACHE */
50643 
50644 #ifndef SQLITE_OMIT_SHARED_CACHE
50645 /*
50646 ** Add a lock on the table with root-page iTable to the shared-btree used
50647 ** by Btree handle p. Parameter eLock must be either READ_LOCK or 
50648 ** WRITE_LOCK.
50649 **
50650 ** This function assumes the following:
50651 **
50652 **   (a) The specified Btree object p is connected to a sharable
50653 **       database (one with the BtShared.sharable flag set), and
50654 **
50655 **   (b) No other Btree objects hold a lock that conflicts
50656 **       with the requested lock (i.e. querySharedCacheTableLock() has
50657 **       already been called and returned SQLITE_OK).
50658 **
50659 ** SQLITE_OK is returned if the lock is added successfully. SQLITE_NOMEM 
50660 ** is returned if a malloc attempt fails.
50661 */
50662 static int setSharedCacheTableLock(Btree *p, Pgno iTable, u8 eLock){
50663   BtShared *pBt = p->pBt;
50664   BtLock *pLock = 0;
50665   BtLock *pIter;
50666 
50667   assert( sqlite3BtreeHoldsMutex(p) );
50668   assert( eLock==READ_LOCK || eLock==WRITE_LOCK );
50669   assert( p->db!=0 );
50670 
50671   /* A connection with the read-uncommitted flag set will never try to
50672   ** obtain a read-lock using this function. The only read-lock obtained
50673   ** by a connection in read-uncommitted mode is on the sqlite_master 
50674   ** table, and that lock is obtained in BtreeBeginTrans().  */
50675   assert( 0==(p->db->flags&SQLITE_ReadUncommitted) || eLock==WRITE_LOCK );
50676 
50677   /* This function should only be called on a sharable b-tree after it 
50678   ** has been determined that no other b-tree holds a conflicting lock.  */
50679   assert( p->sharable );
50680   assert( SQLITE_OK==querySharedCacheTableLock(p, iTable, eLock) );
50681 
50682   /* First search the list for an existing lock on this table. */
50683   for(pIter=pBt->pLock; pIter; pIter=pIter->pNext){
50684     if( pIter->iTable==iTable && pIter->pBtree==p ){
50685       pLock = pIter;
50686       break;
50687     }
50688   }
50689 
50690   /* If the above search did not find a BtLock struct associating Btree p
50691   ** with table iTable, allocate one and link it into the list.
50692   */
50693   if( !pLock ){
50694     pLock = (BtLock *)sqlite3MallocZero(sizeof(BtLock));
50695     if( !pLock ){
50696       return SQLITE_NOMEM;
50697     }
50698     pLock->iTable = iTable;
50699     pLock->pBtree = p;
50700     pLock->pNext = pBt->pLock;
50701     pBt->pLock = pLock;
50702   }
50703 
50704   /* Set the BtLock.eLock variable to the maximum of the current lock
50705   ** and the requested lock. This means if a write-lock was already held
50706   ** and a read-lock requested, we don't incorrectly downgrade the lock.
50707   */
50708   assert( WRITE_LOCK>READ_LOCK );
50709   if( eLock>pLock->eLock ){
50710     pLock->eLock = eLock;
50711   }
50712 
50713   return SQLITE_OK;
50714 }
50715 #endif /* !SQLITE_OMIT_SHARED_CACHE */
50716 
50717 #ifndef SQLITE_OMIT_SHARED_CACHE
50718 /*
50719 ** Release all the table locks (locks obtained via calls to
50720 ** the setSharedCacheTableLock() procedure) held by Btree object p.
50721 **
50722 ** This function assumes that Btree p has an open read or write 
50723 ** transaction. If it does not, then the BTS_PENDING flag
50724 ** may be incorrectly cleared.
50725 */
50726 static void clearAllSharedCacheTableLocks(Btree *p){
50727   BtShared *pBt = p->pBt;
50728   BtLock **ppIter = &pBt->pLock;
50729 
50730   assert( sqlite3BtreeHoldsMutex(p) );
50731   assert( p->sharable || 0==*ppIter );
50732   assert( p->inTrans>0 );
50733 
50734   while( *ppIter ){
50735     BtLock *pLock = *ppIter;
50736     assert( (pBt->btsFlags & BTS_EXCLUSIVE)==0 || pBt->pWriter==pLock->pBtree );
50737     assert( pLock->pBtree->inTrans>=pLock->eLock );
50738     if( pLock->pBtree==p ){
50739       *ppIter = pLock->pNext;
50740       assert( pLock->iTable!=1 || pLock==&p->lock );
50741       if( pLock->iTable!=1 ){
50742         sqlite3_free(pLock);
50743       }
50744     }else{
50745       ppIter = &pLock->pNext;
50746     }
50747   }
50748 
50749   assert( (pBt->btsFlags & BTS_PENDING)==0 || pBt->pWriter );
50750   if( pBt->pWriter==p ){
50751     pBt->pWriter = 0;
50752     pBt->btsFlags &= ~(BTS_EXCLUSIVE|BTS_PENDING);
50753   }else if( pBt->nTransaction==2 ){
50754     /* This function is called when Btree p is concluding its 
50755     ** transaction. If there currently exists a writer, and p is not
50756     ** that writer, then the number of locks held by connections other
50757     ** than the writer must be about to drop to zero. In this case
50758     ** set the BTS_PENDING flag to 0.
50759     **
50760     ** If there is not currently a writer, then BTS_PENDING must
50761     ** be zero already. So this next line is harmless in that case.
50762     */
50763     pBt->btsFlags &= ~BTS_PENDING;
50764   }
50765 }
50766 
50767 /*
50768 ** This function changes all write-locks held by Btree p into read-locks.
50769 */
50770 static void downgradeAllSharedCacheTableLocks(Btree *p){
50771   BtShared *pBt = p->pBt;
50772   if( pBt->pWriter==p ){
50773     BtLock *pLock;
50774     pBt->pWriter = 0;
50775     pBt->btsFlags &= ~(BTS_EXCLUSIVE|BTS_PENDING);
50776     for(pLock=pBt->pLock; pLock; pLock=pLock->pNext){
50777       assert( pLock->eLock==READ_LOCK || pLock->pBtree==p );
50778       pLock->eLock = READ_LOCK;
50779     }
50780   }
50781 }
50782 
50783 #endif /* SQLITE_OMIT_SHARED_CACHE */
50784 
50785 static void releasePage(MemPage *pPage);  /* Forward reference */
50786 
50787 /*
50788 ***** This routine is used inside of assert() only ****
50789 **
50790 ** Verify that the cursor holds the mutex on its BtShared
50791 */
50792 #ifdef SQLITE_DEBUG
50793 static int cursorHoldsMutex(BtCursor *p){
50794   return sqlite3_mutex_held(p->pBt->mutex);
50795 }
50796 #endif
50797 
50798 
50799 #ifndef SQLITE_OMIT_INCRBLOB
50800 /*
50801 ** Invalidate the overflow page-list cache for cursor pCur, if any.
50802 */
50803 static void invalidateOverflowCache(BtCursor *pCur){
50804   assert( cursorHoldsMutex(pCur) );
50805   sqlite3_free(pCur->aOverflow);
50806   pCur->aOverflow = 0;
50807 }
50808 
50809 /*
50810 ** Invalidate the overflow page-list cache for all cursors opened
50811 ** on the shared btree structure pBt.
50812 */
50813 static void invalidateAllOverflowCache(BtShared *pBt){
50814   BtCursor *p;
50815   assert( sqlite3_mutex_held(pBt->mutex) );
50816   for(p=pBt->pCursor; p; p=p->pNext){
50817     invalidateOverflowCache(p);
50818   }
50819 }
50820 
50821 /*
50822 ** This function is called before modifying the contents of a table
50823 ** to invalidate any incrblob cursors that are open on the
50824 ** row or one of the rows being modified.
50825 **
50826 ** If argument isClearTable is true, then the entire contents of the
50827 ** table is about to be deleted. In this case invalidate all incrblob
50828 ** cursors open on any row within the table with root-page pgnoRoot.
50829 **
50830 ** Otherwise, if argument isClearTable is false, then the row with
50831 ** rowid iRow is being replaced or deleted. In this case invalidate
50832 ** only those incrblob cursors open on that specific row.
50833 */
50834 static void invalidateIncrblobCursors(
50835   Btree *pBtree,          /* The database file to check */
50836   i64 iRow,               /* The rowid that might be changing */
50837   int isClearTable        /* True if all rows are being deleted */
50838 ){
50839   BtCursor *p;
50840   BtShared *pBt = pBtree->pBt;
50841   assert( sqlite3BtreeHoldsMutex(pBtree) );
50842   for(p=pBt->pCursor; p; p=p->pNext){
50843     if( p->isIncrblobHandle && (isClearTable || p->info.nKey==iRow) ){
50844       p->eState = CURSOR_INVALID;
50845     }
50846   }
50847 }
50848 
50849 #else
50850   /* Stub functions when INCRBLOB is omitted */
50851   #define invalidateOverflowCache(x)
50852   #define invalidateAllOverflowCache(x)
50853   #define invalidateIncrblobCursors(x,y,z)
50854 #endif /* SQLITE_OMIT_INCRBLOB */
50855 
50856 /*
50857 ** Set bit pgno of the BtShared.pHasContent bitvec. This is called 
50858 ** when a page that previously contained data becomes a free-list leaf 
50859 ** page.
50860 **
50861 ** The BtShared.pHasContent bitvec exists to work around an obscure
50862 ** bug caused by the interaction of two useful IO optimizations surrounding
50863 ** free-list leaf pages:
50864 **
50865 **   1) When all data is deleted from a page and the page becomes
50866 **      a free-list leaf page, the page is not written to the database
50867 **      (as free-list leaf pages contain no meaningful data). Sometimes
50868 **      such a page is not even journalled (as it will not be modified,
50869 **      why bother journalling it?).
50870 **
50871 **   2) When a free-list leaf page is reused, its content is not read
50872 **      from the database or written to the journal file (why should it
50873 **      be, if it is not at all meaningful?).
50874 **
50875 ** By themselves, these optimizations work fine and provide a handy
50876 ** performance boost to bulk delete or insert operations. However, if
50877 ** a page is moved to the free-list and then reused within the same
50878 ** transaction, a problem comes up. If the page is not journalled when
50879 ** it is moved to the free-list and it is also not journalled when it
50880 ** is extracted from the free-list and reused, then the original data
50881 ** may be lost. In the event of a rollback, it may not be possible
50882 ** to restore the database to its original configuration.
50883 **
50884 ** The solution is the BtShared.pHasContent bitvec. Whenever a page is 
50885 ** moved to become a free-list leaf page, the corresponding bit is
50886 ** set in the bitvec. Whenever a leaf page is extracted from the free-list,
50887 ** optimization 2 above is omitted if the corresponding bit is already
50888 ** set in BtShared.pHasContent. The contents of the bitvec are cleared
50889 ** at the end of every transaction.
50890 */
50891 static int btreeSetHasContent(BtShared *pBt, Pgno pgno){
50892   int rc = SQLITE_OK;
50893   if( !pBt->pHasContent ){
50894     assert( pgno<=pBt->nPage );
50895     pBt->pHasContent = sqlite3BitvecCreate(pBt->nPage);
50896     if( !pBt->pHasContent ){
50897       rc = SQLITE_NOMEM;
50898     }
50899   }
50900   if( rc==SQLITE_OK && pgno<=sqlite3BitvecSize(pBt->pHasContent) ){
50901     rc = sqlite3BitvecSet(pBt->pHasContent, pgno);
50902   }
50903   return rc;
50904 }
50905 
50906 /*
50907 ** Query the BtShared.pHasContent vector.
50908 **
50909 ** This function is called when a free-list leaf page is removed from the
50910 ** free-list for reuse. It returns false if it is safe to retrieve the
50911 ** page from the pager layer with the 'no-content' flag set. True otherwise.
50912 */
50913 static int btreeGetHasContent(BtShared *pBt, Pgno pgno){
50914   Bitvec *p = pBt->pHasContent;
50915   return (p && (pgno>sqlite3BitvecSize(p) || sqlite3BitvecTest(p, pgno)));
50916 }
50917 
50918 /*
50919 ** Clear (destroy) the BtShared.pHasContent bitvec. This should be
50920 ** invoked at the conclusion of each write-transaction.
50921 */
50922 static void btreeClearHasContent(BtShared *pBt){
50923   sqlite3BitvecDestroy(pBt->pHasContent);
50924   pBt->pHasContent = 0;
50925 }
50926 
50927 /*
50928 ** Release all of the apPage[] pages for a cursor.
50929 */
50930 static void btreeReleaseAllCursorPages(BtCursor *pCur){
50931   int i;
50932   for(i=0; i<=pCur->iPage; i++){
50933     releasePage(pCur->apPage[i]);
50934     pCur->apPage[i] = 0;
50935   }
50936   pCur->iPage = -1;
50937 }
50938 
50939 
50940 /*
50941 ** Save the current cursor position in the variables BtCursor.nKey 
50942 ** and BtCursor.pKey. The cursor's state is set to CURSOR_REQUIRESEEK.
50943 **
50944 ** The caller must ensure that the cursor is valid (has eState==CURSOR_VALID)
50945 ** prior to calling this routine.  
50946 */
50947 static int saveCursorPosition(BtCursor *pCur){
50948   int rc;
50949 
50950   assert( CURSOR_VALID==pCur->eState );
50951   assert( 0==pCur->pKey );
50952   assert( cursorHoldsMutex(pCur) );
50953 
50954   rc = sqlite3BtreeKeySize(pCur, &pCur->nKey);
50955   assert( rc==SQLITE_OK );  /* KeySize() cannot fail */
50956 
50957   /* If this is an intKey table, then the above call to BtreeKeySize()
50958   ** stores the integer key in pCur->nKey. In this case this value is
50959   ** all that is required. Otherwise, if pCur is not open on an intKey
50960   ** table, then malloc space for and store the pCur->nKey bytes of key 
50961   ** data.
50962   */
50963   if( 0==pCur->apPage[0]->intKey ){
50964     void *pKey = sqlite3Malloc( (int)pCur->nKey );
50965     if( pKey ){
50966       rc = sqlite3BtreeKey(pCur, 0, (int)pCur->nKey, pKey);
50967       if( rc==SQLITE_OK ){
50968         pCur->pKey = pKey;
50969       }else{
50970         sqlite3_free(pKey);
50971       }
50972     }else{
50973       rc = SQLITE_NOMEM;
50974     }
50975   }
50976   assert( !pCur->apPage[0]->intKey || !pCur->pKey );
50977 
50978   if( rc==SQLITE_OK ){
50979     btreeReleaseAllCursorPages(pCur);
50980     pCur->eState = CURSOR_REQUIRESEEK;
50981   }
50982 
50983   invalidateOverflowCache(pCur);
50984   return rc;
50985 }
50986 
50987 /*
50988 ** Save the positions of all cursors (except pExcept) that are open on
50989 ** the table  with root-page iRoot. Usually, this is called just before cursor
50990 ** pExcept is used to modify the table (BtreeDelete() or BtreeInsert()).
50991 */
50992 static int saveAllCursors(BtShared *pBt, Pgno iRoot, BtCursor *pExcept){
50993   BtCursor *p;
50994   assert( sqlite3_mutex_held(pBt->mutex) );
50995   assert( pExcept==0 || pExcept->pBt==pBt );
50996   for(p=pBt->pCursor; p; p=p->pNext){
50997     if( p!=pExcept && (0==iRoot || p->pgnoRoot==iRoot) ){
50998       if( p->eState==CURSOR_VALID ){
50999         int rc = saveCursorPosition(p);
51000         if( SQLITE_OK!=rc ){
51001           return rc;
51002         }
51003       }else{
51004         testcase( p->iPage>0 );
51005         btreeReleaseAllCursorPages(p);
51006       }
51007     }
51008   }
51009   return SQLITE_OK;
51010 }
51011 
51012 /*
51013 ** Clear the current cursor position.
51014 */
51015 SQLITE_PRIVATE void sqlite3BtreeClearCursor(BtCursor *pCur){
51016   assert( cursorHoldsMutex(pCur) );
51017   sqlite3_free(pCur->pKey);
51018   pCur->pKey = 0;
51019   pCur->eState = CURSOR_INVALID;
51020 }
51021 
51022 /*
51023 ** In this version of BtreeMoveto, pKey is a packed index record
51024 ** such as is generated by the OP_MakeRecord opcode.  Unpack the
51025 ** record and then call BtreeMovetoUnpacked() to do the work.
51026 */
51027 static int btreeMoveto(
51028   BtCursor *pCur,     /* Cursor open on the btree to be searched */
51029   const void *pKey,   /* Packed key if the btree is an index */
51030   i64 nKey,           /* Integer key for tables.  Size of pKey for indices */
51031   int bias,           /* Bias search to the high end */
51032   int *pRes           /* Write search results here */
51033 ){
51034   int rc;                    /* Status code */
51035   UnpackedRecord *pIdxKey;   /* Unpacked index key */
51036   char aSpace[200];          /* Temp space for pIdxKey - to avoid a malloc */
51037   char *pFree = 0;
51038 
51039   if( pKey ){
51040     assert( nKey==(i64)(int)nKey );
51041     pIdxKey = sqlite3VdbeAllocUnpackedRecord(
51042         pCur->pKeyInfo, aSpace, sizeof(aSpace), &pFree
51043     );
51044     if( pIdxKey==0 ) return SQLITE_NOMEM;
51045     sqlite3VdbeRecordUnpack(pCur->pKeyInfo, (int)nKey, pKey, pIdxKey);
51046     if( pIdxKey->nField==0 ){
51047       sqlite3DbFree(pCur->pKeyInfo->db, pFree);
51048       return SQLITE_CORRUPT_BKPT;
51049     }
51050   }else{
51051     pIdxKey = 0;
51052   }
51053   rc = sqlite3BtreeMovetoUnpacked(pCur, pIdxKey, nKey, bias, pRes);
51054   if( pFree ){
51055     sqlite3DbFree(pCur->pKeyInfo->db, pFree);
51056   }
51057   return rc;
51058 }
51059 
51060 /*
51061 ** Restore the cursor to the position it was in (or as close to as possible)
51062 ** when saveCursorPosition() was called. Note that this call deletes the 
51063 ** saved position info stored by saveCursorPosition(), so there can be
51064 ** at most one effective restoreCursorPosition() call after each 
51065 ** saveCursorPosition().
51066 */
51067 static int btreeRestoreCursorPosition(BtCursor *pCur){
51068   int rc;
51069   assert( cursorHoldsMutex(pCur) );
51070   assert( pCur->eState>=CURSOR_REQUIRESEEK );
51071   if( pCur->eState==CURSOR_FAULT ){
51072     return pCur->skipNext;
51073   }
51074   pCur->eState = CURSOR_INVALID;
51075   rc = btreeMoveto(pCur, pCur->pKey, pCur->nKey, 0, &pCur->skipNext);
51076   if( rc==SQLITE_OK ){
51077     sqlite3_free(pCur->pKey);
51078     pCur->pKey = 0;
51079     assert( pCur->eState==CURSOR_VALID || pCur->eState==CURSOR_INVALID );
51080     if( pCur->skipNext && pCur->eState==CURSOR_VALID ){
51081       pCur->eState = CURSOR_SKIPNEXT;
51082     }
51083   }
51084   return rc;
51085 }
51086 
51087 #define restoreCursorPosition(p) \
51088   (p->eState>=CURSOR_REQUIRESEEK ? \
51089          btreeRestoreCursorPosition(p) : \
51090          SQLITE_OK)
51091 
51092 /*
51093 ** Determine whether or not a cursor has moved from the position it
51094 ** was last placed at.  Cursors can move when the row they are pointing
51095 ** at is deleted out from under them.
51096 **
51097 ** This routine returns an error code if something goes wrong.  The
51098 ** integer *pHasMoved is set to one if the cursor has moved and 0 if not.
51099 */
51100 SQLITE_PRIVATE int sqlite3BtreeCursorHasMoved(BtCursor *pCur, int *pHasMoved){
51101   int rc;
51102 
51103   rc = restoreCursorPosition(pCur);
51104   if( rc ){
51105     *pHasMoved = 1;
51106     return rc;
51107   }
51108   if( pCur->eState!=CURSOR_VALID || NEVER(pCur->skipNext!=0) ){
51109     *pHasMoved = 1;
51110   }else{
51111     *pHasMoved = 0;
51112   }
51113   return SQLITE_OK;
51114 }
51115 
51116 #ifndef SQLITE_OMIT_AUTOVACUUM
51117 /*
51118 ** Given a page number of a regular database page, return the page
51119 ** number for the pointer-map page that contains the entry for the
51120 ** input page number.
51121 **
51122 ** Return 0 (not a valid page) for pgno==1 since there is
51123 ** no pointer map associated with page 1.  The integrity_check logic
51124 ** requires that ptrmapPageno(*,1)!=1.
51125 */
51126 static Pgno ptrmapPageno(BtShared *pBt, Pgno pgno){
51127   int nPagesPerMapPage;
51128   Pgno iPtrMap, ret;
51129   assert( sqlite3_mutex_held(pBt->mutex) );
51130   if( pgno<2 ) return 0;
51131   nPagesPerMapPage = (pBt->usableSize/5)+1;
51132   iPtrMap = (pgno-2)/nPagesPerMapPage;
51133   ret = (iPtrMap*nPagesPerMapPage) + 2; 
51134   if( ret==PENDING_BYTE_PAGE(pBt) ){
51135     ret++;
51136   }
51137   return ret;
51138 }
51139 
51140 /*
51141 ** Write an entry into the pointer map.
51142 **
51143 ** This routine updates the pointer map entry for page number 'key'
51144 ** so that it maps to type 'eType' and parent page number 'pgno'.
51145 **
51146 ** If *pRC is initially non-zero (non-SQLITE_OK) then this routine is
51147 ** a no-op.  If an error occurs, the appropriate error code is written
51148 ** into *pRC.
51149 */
51150 static void ptrmapPut(BtShared *pBt, Pgno key, u8 eType, Pgno parent, int *pRC){
51151   DbPage *pDbPage;  /* The pointer map page */
51152   u8 *pPtrmap;      /* The pointer map data */
51153   Pgno iPtrmap;     /* The pointer map page number */
51154   int offset;       /* Offset in pointer map page */
51155   int rc;           /* Return code from subfunctions */
51156 
51157   if( *pRC ) return;
51158 
51159   assert( sqlite3_mutex_held(pBt->mutex) );
51160   /* The master-journal page number must never be used as a pointer map page */
51161   assert( 0==PTRMAP_ISPAGE(pBt, PENDING_BYTE_PAGE(pBt)) );
51162 
51163   assert( pBt->autoVacuum );
51164   if( key==0 ){
51165     *pRC = SQLITE_CORRUPT_BKPT;
51166     return;
51167   }
51168   iPtrmap = PTRMAP_PAGENO(pBt, key);
51169   rc = sqlite3PagerGet(pBt->pPager, iPtrmap, &pDbPage);
51170   if( rc!=SQLITE_OK ){
51171     *pRC = rc;
51172     return;
51173   }
51174   offset = PTRMAP_PTROFFSET(iPtrmap, key);
51175   if( offset<0 ){
51176     *pRC = SQLITE_CORRUPT_BKPT;
51177     goto ptrmap_exit;
51178   }
51179   assert( offset <= (int)pBt->usableSize-5 );
51180   pPtrmap = (u8 *)sqlite3PagerGetData(pDbPage);
51181 
51182   if( eType!=pPtrmap[offset] || get4byte(&pPtrmap[offset+1])!=parent ){
51183     TRACE(("PTRMAP_UPDATE: %d->(%d,%d)\n", key, eType, parent));
51184     *pRC= rc = sqlite3PagerWrite(pDbPage);
51185     if( rc==SQLITE_OK ){
51186       pPtrmap[offset] = eType;
51187       put4byte(&pPtrmap[offset+1], parent);
51188     }
51189   }
51190 
51191 ptrmap_exit:
51192   sqlite3PagerUnref(pDbPage);
51193 }
51194 
51195 /*
51196 ** Read an entry from the pointer map.
51197 **
51198 ** This routine retrieves the pointer map entry for page 'key', writing
51199 ** the type and parent page number to *pEType and *pPgno respectively.
51200 ** An error code is returned if something goes wrong, otherwise SQLITE_OK.
51201 */
51202 static int ptrmapGet(BtShared *pBt, Pgno key, u8 *pEType, Pgno *pPgno){
51203   DbPage *pDbPage;   /* The pointer map page */
51204   int iPtrmap;       /* Pointer map page index */
51205   u8 *pPtrmap;       /* Pointer map page data */
51206   int offset;        /* Offset of entry in pointer map */
51207   int rc;
51208 
51209   assert( sqlite3_mutex_held(pBt->mutex) );
51210 
51211   iPtrmap = PTRMAP_PAGENO(pBt, key);
51212   rc = sqlite3PagerGet(pBt->pPager, iPtrmap, &pDbPage);
51213   if( rc!=0 ){
51214     return rc;
51215   }
51216   pPtrmap = (u8 *)sqlite3PagerGetData(pDbPage);
51217 
51218   offset = PTRMAP_PTROFFSET(iPtrmap, key);
51219   if( offset<0 ){
51220     sqlite3PagerUnref(pDbPage);
51221     return SQLITE_CORRUPT_BKPT;
51222   }
51223   assert( offset <= (int)pBt->usableSize-5 );
51224   assert( pEType!=0 );
51225   *pEType = pPtrmap[offset];
51226   if( pPgno ) *pPgno = get4byte(&pPtrmap[offset+1]);
51227 
51228   sqlite3PagerUnref(pDbPage);
51229   if( *pEType<1 || *pEType>5 ) return SQLITE_CORRUPT_BKPT;
51230   return SQLITE_OK;
51231 }
51232 
51233 #else /* if defined SQLITE_OMIT_AUTOVACUUM */
51234   #define ptrmapPut(w,x,y,z,rc)
51235   #define ptrmapGet(w,x,y,z) SQLITE_OK
51236   #define ptrmapPutOvflPtr(x, y, rc)
51237 #endif
51238 
51239 /*
51240 ** Given a btree page and a cell index (0 means the first cell on
51241 ** the page, 1 means the second cell, and so forth) return a pointer
51242 ** to the cell content.
51243 **
51244 ** This routine works only for pages that do not contain overflow cells.
51245 */
51246 #define findCell(P,I) \
51247   ((P)->aData + ((P)->maskPage & get2byte(&(P)->aCellIdx[2*(I)])))
51248 #define findCellv2(D,M,O,I) (D+(M&get2byte(D+(O+2*(I)))))
51249 
51250 
51251 /*
51252 ** This a more complex version of findCell() that works for
51253 ** pages that do contain overflow cells.
51254 */
51255 static u8 *findOverflowCell(MemPage *pPage, int iCell){
51256   int i;
51257   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
51258   for(i=pPage->nOverflow-1; i>=0; i--){
51259     int k;
51260     k = pPage->aiOvfl[i];
51261     if( k<=iCell ){
51262       if( k==iCell ){
51263         return pPage->apOvfl[i];
51264       }
51265       iCell--;
51266     }
51267   }
51268   return findCell(pPage, iCell);
51269 }
51270 
51271 /*
51272 ** Parse a cell content block and fill in the CellInfo structure.  There
51273 ** are two versions of this function.  btreeParseCell() takes a 
51274 ** cell index as the second argument and btreeParseCellPtr() 
51275 ** takes a pointer to the body of the cell as its second argument.
51276 **
51277 ** Within this file, the parseCell() macro can be called instead of
51278 ** btreeParseCellPtr(). Using some compilers, this will be faster.
51279 */
51280 static void btreeParseCellPtr(
51281   MemPage *pPage,         /* Page containing the cell */
51282   u8 *pCell,              /* Pointer to the cell text. */
51283   CellInfo *pInfo         /* Fill in this structure */
51284 ){
51285   u16 n;                  /* Number bytes in cell content header */
51286   u32 nPayload;           /* Number of bytes of cell payload */
51287 
51288   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
51289 
51290   pInfo->pCell = pCell;
51291   assert( pPage->leaf==0 || pPage->leaf==1 );
51292   n = pPage->childPtrSize;
51293   assert( n==4-4*pPage->leaf );
51294   if( pPage->intKey ){
51295     if( pPage->hasData ){
51296       assert( n==0 );
51297       n = getVarint32(pCell, nPayload);
51298     }else{
51299       nPayload = 0;
51300     }
51301     n += getVarint(&pCell[n], (u64*)&pInfo->nKey);
51302     pInfo->nData = nPayload;
51303   }else{
51304     pInfo->nData = 0;
51305     n += getVarint32(&pCell[n], nPayload);
51306     pInfo->nKey = nPayload;
51307   }
51308   pInfo->nPayload = nPayload;
51309   pInfo->nHeader = n;
51310   testcase( nPayload==pPage->maxLocal );
51311   testcase( nPayload==pPage->maxLocal+1 );
51312   if( likely(nPayload<=pPage->maxLocal) ){
51313     /* This is the (easy) common case where the entire payload fits
51314     ** on the local page.  No overflow is required.
51315     */
51316     if( (pInfo->nSize = (u16)(n+nPayload))<4 ) pInfo->nSize = 4;
51317     pInfo->nLocal = (u16)nPayload;
51318     pInfo->iOverflow = 0;
51319   }else{
51320     /* If the payload will not fit completely on the local page, we have
51321     ** to decide how much to store locally and how much to spill onto
51322     ** overflow pages.  The strategy is to minimize the amount of unused
51323     ** space on overflow pages while keeping the amount of local storage
51324     ** in between minLocal and maxLocal.
51325     **
51326     ** Warning:  changing the way overflow payload is distributed in any
51327     ** way will result in an incompatible file format.
51328     */
51329     int minLocal;  /* Minimum amount of payload held locally */
51330     int maxLocal;  /* Maximum amount of payload held locally */
51331     int surplus;   /* Overflow payload available for local storage */
51332 
51333     minLocal = pPage->minLocal;
51334     maxLocal = pPage->maxLocal;
51335     surplus = minLocal + (nPayload - minLocal)%(pPage->pBt->usableSize - 4);
51336     testcase( surplus==maxLocal );
51337     testcase( surplus==maxLocal+1 );
51338     if( surplus <= maxLocal ){
51339       pInfo->nLocal = (u16)surplus;
51340     }else{
51341       pInfo->nLocal = (u16)minLocal;
51342     }
51343     pInfo->iOverflow = (u16)(pInfo->nLocal + n);
51344     pInfo->nSize = pInfo->iOverflow + 4;
51345   }
51346 }
51347 #define parseCell(pPage, iCell, pInfo) \
51348   btreeParseCellPtr((pPage), findCell((pPage), (iCell)), (pInfo))
51349 static void btreeParseCell(
51350   MemPage *pPage,         /* Page containing the cell */
51351   int iCell,              /* The cell index.  First cell is 0 */
51352   CellInfo *pInfo         /* Fill in this structure */
51353 ){
51354   parseCell(pPage, iCell, pInfo);
51355 }
51356 
51357 /*
51358 ** Compute the total number of bytes that a Cell needs in the cell
51359 ** data area of the btree-page.  The return number includes the cell
51360 ** data header and the local payload, but not any overflow page or
51361 ** the space used by the cell pointer.
51362 */
51363 static u16 cellSizePtr(MemPage *pPage, u8 *pCell){
51364   u8 *pIter = &pCell[pPage->childPtrSize];
51365   u32 nSize;
51366 
51367 #ifdef SQLITE_DEBUG
51368   /* The value returned by this function should always be the same as
51369   ** the (CellInfo.nSize) value found by doing a full parse of the
51370   ** cell. If SQLITE_DEBUG is defined, an assert() at the bottom of
51371   ** this function verifies that this invariant is not violated. */
51372   CellInfo debuginfo;
51373   btreeParseCellPtr(pPage, pCell, &debuginfo);
51374 #endif
51375 
51376   if( pPage->intKey ){
51377     u8 *pEnd;
51378     if( pPage->hasData ){
51379       pIter += getVarint32(pIter, nSize);
51380     }else{
51381       nSize = 0;
51382     }
51383 
51384     /* pIter now points at the 64-bit integer key value, a variable length 
51385     ** integer. The following block moves pIter to point at the first byte
51386     ** past the end of the key value. */
51387     pEnd = &pIter[9];
51388     while( (*pIter++)&0x80 && pIter<pEnd );
51389   }else{
51390     pIter += getVarint32(pIter, nSize);
51391   }
51392 
51393   testcase( nSize==pPage->maxLocal );
51394   testcase( nSize==pPage->maxLocal+1 );
51395   if( nSize>pPage->maxLocal ){
51396     int minLocal = pPage->minLocal;
51397     nSize = minLocal + (nSize - minLocal) % (pPage->pBt->usableSize - 4);
51398     testcase( nSize==pPage->maxLocal );
51399     testcase( nSize==pPage->maxLocal+1 );
51400     if( nSize>pPage->maxLocal ){
51401       nSize = minLocal;
51402     }
51403     nSize += 4;
51404   }
51405   nSize += (u32)(pIter - pCell);
51406 
51407   /* The minimum size of any cell is 4 bytes. */
51408   if( nSize<4 ){
51409     nSize = 4;
51410   }
51411 
51412   assert( nSize==debuginfo.nSize );
51413   return (u16)nSize;
51414 }
51415 
51416 #ifdef SQLITE_DEBUG
51417 /* This variation on cellSizePtr() is used inside of assert() statements
51418 ** only. */
51419 static u16 cellSize(MemPage *pPage, int iCell){
51420   return cellSizePtr(pPage, findCell(pPage, iCell));
51421 }
51422 #endif
51423 
51424 #ifndef SQLITE_OMIT_AUTOVACUUM
51425 /*
51426 ** If the cell pCell, part of page pPage contains a pointer
51427 ** to an overflow page, insert an entry into the pointer-map
51428 ** for the overflow page.
51429 */
51430 static void ptrmapPutOvflPtr(MemPage *pPage, u8 *pCell, int *pRC){
51431   CellInfo info;
51432   if( *pRC ) return;
51433   assert( pCell!=0 );
51434   btreeParseCellPtr(pPage, pCell, &info);
51435   assert( (info.nData+(pPage->intKey?0:info.nKey))==info.nPayload );
51436   if( info.iOverflow ){
51437     Pgno ovfl = get4byte(&pCell[info.iOverflow]);
51438     ptrmapPut(pPage->pBt, ovfl, PTRMAP_OVERFLOW1, pPage->pgno, pRC);
51439   }
51440 }
51441 #endif
51442 
51443 
51444 /*
51445 ** Defragment the page given.  All Cells are moved to the
51446 ** end of the page and all free space is collected into one
51447 ** big FreeBlk that occurs in between the header and cell
51448 ** pointer array and the cell content area.
51449 */
51450 static int defragmentPage(MemPage *pPage){
51451   int i;                     /* Loop counter */
51452   int pc;                    /* Address of a i-th cell */
51453   int hdr;                   /* Offset to the page header */
51454   int size;                  /* Size of a cell */
51455   int usableSize;            /* Number of usable bytes on a page */
51456   int cellOffset;            /* Offset to the cell pointer array */
51457   int cbrk;                  /* Offset to the cell content area */
51458   int nCell;                 /* Number of cells on the page */
51459   unsigned char *data;       /* The page data */
51460   unsigned char *temp;       /* Temp area for cell content */
51461   int iCellFirst;            /* First allowable cell index */
51462   int iCellLast;             /* Last possible cell index */
51463 
51464 
51465   assert( sqlite3PagerIswriteable(pPage->pDbPage) );
51466   assert( pPage->pBt!=0 );
51467   assert( pPage->pBt->usableSize <= SQLITE_MAX_PAGE_SIZE );
51468   assert( pPage->nOverflow==0 );
51469   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
51470   temp = sqlite3PagerTempSpace(pPage->pBt->pPager);
51471   data = pPage->aData;
51472   hdr = pPage->hdrOffset;
51473   cellOffset = pPage->cellOffset;
51474   nCell = pPage->nCell;
51475   assert( nCell==get2byte(&data[hdr+3]) );
51476   usableSize = pPage->pBt->usableSize;
51477   cbrk = get2byte(&data[hdr+5]);
51478   memcpy(&temp[cbrk], &data[cbrk], usableSize - cbrk);
51479   cbrk = usableSize;
51480   iCellFirst = cellOffset + 2*nCell;
51481   iCellLast = usableSize - 4;
51482   for(i=0; i<nCell; i++){
51483     u8 *pAddr;     /* The i-th cell pointer */
51484     pAddr = &data[cellOffset + i*2];
51485     pc = get2byte(pAddr);
51486     testcase( pc==iCellFirst );
51487     testcase( pc==iCellLast );
51488 #if !defined(SQLITE_ENABLE_OVERSIZE_CELL_CHECK)
51489     /* These conditions have already been verified in btreeInitPage()
51490     ** if SQLITE_ENABLE_OVERSIZE_CELL_CHECK is defined 
51491     */
51492     if( pc<iCellFirst || pc>iCellLast ){
51493       return SQLITE_CORRUPT_BKPT;
51494     }
51495 #endif
51496     assert( pc>=iCellFirst && pc<=iCellLast );
51497     size = cellSizePtr(pPage, &temp[pc]);
51498     cbrk -= size;
51499 #if defined(SQLITE_ENABLE_OVERSIZE_CELL_CHECK)
51500     if( cbrk<iCellFirst ){
51501       return SQLITE_CORRUPT_BKPT;
51502     }
51503 #else
51504     if( cbrk<iCellFirst || pc+size>usableSize ){
51505       return SQLITE_CORRUPT_BKPT;
51506     }
51507 #endif
51508     assert( cbrk+size<=usableSize && cbrk>=iCellFirst );
51509     testcase( cbrk+size==usableSize );
51510     testcase( pc+size==usableSize );
51511     memcpy(&data[cbrk], &temp[pc], size);
51512     put2byte(pAddr, cbrk);
51513   }
51514   assert( cbrk>=iCellFirst );
51515   put2byte(&data[hdr+5], cbrk);
51516   data[hdr+1] = 0;
51517   data[hdr+2] = 0;
51518   data[hdr+7] = 0;
51519   memset(&data[iCellFirst], 0, cbrk-iCellFirst);
51520   assert( sqlite3PagerIswriteable(pPage->pDbPage) );
51521   if( cbrk-iCellFirst!=pPage->nFree ){
51522     return SQLITE_CORRUPT_BKPT;
51523   }
51524   return SQLITE_OK;
51525 }
51526 
51527 /*
51528 ** Allocate nByte bytes of space from within the B-Tree page passed
51529 ** as the first argument. Write into *pIdx the index into pPage->aData[]
51530 ** of the first byte of allocated space. Return either SQLITE_OK or
51531 ** an error code (usually SQLITE_CORRUPT).
51532 **
51533 ** The caller guarantees that there is sufficient space to make the
51534 ** allocation.  This routine might need to defragment in order to bring
51535 ** all the space together, however.  This routine will avoid using
51536 ** the first two bytes past the cell pointer area since presumably this
51537 ** allocation is being made in order to insert a new cell, so we will
51538 ** also end up needing a new cell pointer.
51539 */
51540 static int allocateSpace(MemPage *pPage, int nByte, int *pIdx){
51541   const int hdr = pPage->hdrOffset;    /* Local cache of pPage->hdrOffset */
51542   u8 * const data = pPage->aData;      /* Local cache of pPage->aData */
51543   int nFrag;                           /* Number of fragmented bytes on pPage */
51544   int top;                             /* First byte of cell content area */
51545   int gap;        /* First byte of gap between cell pointers and cell content */
51546   int rc;         /* Integer return code */
51547   int usableSize; /* Usable size of the page */
51548   
51549   assert( sqlite3PagerIswriteable(pPage->pDbPage) );
51550   assert( pPage->pBt );
51551   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
51552   assert( nByte>=0 );  /* Minimum cell size is 4 */
51553   assert( pPage->nFree>=nByte );
51554   assert( pPage->nOverflow==0 );
51555   usableSize = pPage->pBt->usableSize;
51556   assert( nByte < usableSize-8 );
51557 
51558   nFrag = data[hdr+7];
51559   assert( pPage->cellOffset == hdr + 12 - 4*pPage->leaf );
51560   gap = pPage->cellOffset + 2*pPage->nCell;
51561   top = get2byteNotZero(&data[hdr+5]);
51562   if( gap>top ) return SQLITE_CORRUPT_BKPT;
51563   testcase( gap+2==top );
51564   testcase( gap+1==top );
51565   testcase( gap==top );
51566 
51567   if( nFrag>=60 ){
51568     /* Always defragment highly fragmented pages */
51569     rc = defragmentPage(pPage);
51570     if( rc ) return rc;
51571     top = get2byteNotZero(&data[hdr+5]);
51572   }else if( gap+2<=top ){
51573     /* Search the freelist looking for a free slot big enough to satisfy 
51574     ** the request. The allocation is made from the first free slot in 
51575     ** the list that is large enough to accommodate it.
51576     */
51577     int pc, addr;
51578     for(addr=hdr+1; (pc = get2byte(&data[addr]))>0; addr=pc){
51579       int size;            /* Size of the free slot */
51580       if( pc>usableSize-4 || pc<addr+4 ){
51581         return SQLITE_CORRUPT_BKPT;
51582       }
51583       size = get2byte(&data[pc+2]);
51584       if( size>=nByte ){
51585         int x = size - nByte;
51586         testcase( x==4 );
51587         testcase( x==3 );
51588         if( x<4 ){
51589           /* Remove the slot from the free-list. Update the number of
51590           ** fragmented bytes within the page. */
51591           memcpy(&data[addr], &data[pc], 2);
51592           data[hdr+7] = (u8)(nFrag + x);
51593         }else if( size+pc > usableSize ){
51594           return SQLITE_CORRUPT_BKPT;
51595         }else{
51596           /* The slot remains on the free-list. Reduce its size to account
51597           ** for the portion used by the new allocation. */
51598           put2byte(&data[pc+2], x);
51599         }
51600         *pIdx = pc + x;
51601         return SQLITE_OK;
51602       }
51603     }
51604   }
51605 
51606   /* Check to make sure there is enough space in the gap to satisfy
51607   ** the allocation.  If not, defragment.
51608   */
51609   testcase( gap+2+nByte==top );
51610   if( gap+2+nByte>top ){
51611     rc = defragmentPage(pPage);
51612     if( rc ) return rc;
51613     top = get2byteNotZero(&data[hdr+5]);
51614     assert( gap+nByte<=top );
51615   }
51616 
51617 
51618   /* Allocate memory from the gap in between the cell pointer array
51619   ** and the cell content area.  The btreeInitPage() call has already
51620   ** validated the freelist.  Given that the freelist is valid, there
51621   ** is no way that the allocation can extend off the end of the page.
51622   ** The assert() below verifies the previous sentence.
51623   */
51624   top -= nByte;
51625   put2byte(&data[hdr+5], top);
51626   assert( top+nByte <= (int)pPage->pBt->usableSize );
51627   *pIdx = top;
51628   return SQLITE_OK;
51629 }
51630 
51631 /*
51632 ** Return a section of the pPage->aData to the freelist.
51633 ** The first byte of the new free block is pPage->aDisk[start]
51634 ** and the size of the block is "size" bytes.
51635 **
51636 ** Most of the effort here is involved in coalesing adjacent
51637 ** free blocks into a single big free block.
51638 */
51639 static int freeSpace(MemPage *pPage, int start, int size){
51640   int addr, pbegin, hdr;
51641   int iLast;                        /* Largest possible freeblock offset */
51642   unsigned char *data = pPage->aData;
51643 
51644   assert( pPage->pBt!=0 );
51645   assert( sqlite3PagerIswriteable(pPage->pDbPage) );
51646   assert( start>=pPage->hdrOffset+6+pPage->childPtrSize );
51647   assert( (start + size) <= (int)pPage->pBt->usableSize );
51648   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
51649   assert( size>=0 );   /* Minimum cell size is 4 */
51650 
51651   if( pPage->pBt->btsFlags & BTS_SECURE_DELETE ){
51652     /* Overwrite deleted information with zeros when the secure_delete
51653     ** option is enabled */
51654     memset(&data[start], 0, size);
51655   }
51656 
51657   /* Add the space back into the linked list of freeblocks.  Note that
51658   ** even though the freeblock list was checked by btreeInitPage(),
51659   ** btreeInitPage() did not detect overlapping cells or
51660   ** freeblocks that overlapped cells.   Nor does it detect when the
51661   ** cell content area exceeds the value in the page header.  If these
51662   ** situations arise, then subsequent insert operations might corrupt
51663   ** the freelist.  So we do need to check for corruption while scanning
51664   ** the freelist.
51665   */
51666   hdr = pPage->hdrOffset;
51667   addr = hdr + 1;
51668   iLast = pPage->pBt->usableSize - 4;
51669   assert( start<=iLast );
51670   while( (pbegin = get2byte(&data[addr]))<start && pbegin>0 ){
51671     if( pbegin<addr+4 ){
51672       return SQLITE_CORRUPT_BKPT;
51673     }
51674     addr = pbegin;
51675   }
51676   if( pbegin>iLast ){
51677     return SQLITE_CORRUPT_BKPT;
51678   }
51679   assert( pbegin>addr || pbegin==0 );
51680   put2byte(&data[addr], start);
51681   put2byte(&data[start], pbegin);
51682   put2byte(&data[start+2], size);
51683   pPage->nFree = pPage->nFree + (u16)size;
51684 
51685   /* Coalesce adjacent free blocks */
51686   addr = hdr + 1;
51687   while( (pbegin = get2byte(&data[addr]))>0 ){
51688     int pnext, psize, x;
51689     assert( pbegin>addr );
51690     assert( pbegin <= (int)pPage->pBt->usableSize-4 );
51691     pnext = get2byte(&data[pbegin]);
51692     psize = get2byte(&data[pbegin+2]);
51693     if( pbegin + psize + 3 >= pnext && pnext>0 ){
51694       int frag = pnext - (pbegin+psize);
51695       if( (frag<0) || (frag>(int)data[hdr+7]) ){
51696         return SQLITE_CORRUPT_BKPT;
51697       }
51698       data[hdr+7] -= (u8)frag;
51699       x = get2byte(&data[pnext]);
51700       put2byte(&data[pbegin], x);
51701       x = pnext + get2byte(&data[pnext+2]) - pbegin;
51702       put2byte(&data[pbegin+2], x);
51703     }else{
51704       addr = pbegin;
51705     }
51706   }
51707 
51708   /* If the cell content area begins with a freeblock, remove it. */
51709   if( data[hdr+1]==data[hdr+5] && data[hdr+2]==data[hdr+6] ){
51710     int top;
51711     pbegin = get2byte(&data[hdr+1]);
51712     memcpy(&data[hdr+1], &data[pbegin], 2);
51713     top = get2byte(&data[hdr+5]) + get2byte(&data[pbegin+2]);
51714     put2byte(&data[hdr+5], top);
51715   }
51716   assert( sqlite3PagerIswriteable(pPage->pDbPage) );
51717   return SQLITE_OK;
51718 }
51719 
51720 /*
51721 ** Decode the flags byte (the first byte of the header) for a page
51722 ** and initialize fields of the MemPage structure accordingly.
51723 **
51724 ** Only the following combinations are supported.  Anything different
51725 ** indicates a corrupt database files:
51726 **
51727 **         PTF_ZERODATA
51728 **         PTF_ZERODATA | PTF_LEAF
51729 **         PTF_LEAFDATA | PTF_INTKEY
51730 **         PTF_LEAFDATA | PTF_INTKEY | PTF_LEAF
51731 */
51732 static int decodeFlags(MemPage *pPage, int flagByte){
51733   BtShared *pBt;     /* A copy of pPage->pBt */
51734 
51735   assert( pPage->hdrOffset==(pPage->pgno==1 ? 100 : 0) );
51736   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
51737   pPage->leaf = (u8)(flagByte>>3);  assert( PTF_LEAF == 1<<3 );
51738   flagByte &= ~PTF_LEAF;
51739   pPage->childPtrSize = 4-4*pPage->leaf;
51740   pBt = pPage->pBt;
51741   if( flagByte==(PTF_LEAFDATA | PTF_INTKEY) ){
51742     pPage->intKey = 1;
51743     pPage->hasData = pPage->leaf;
51744     pPage->maxLocal = pBt->maxLeaf;
51745     pPage->minLocal = pBt->minLeaf;
51746   }else if( flagByte==PTF_ZERODATA ){
51747     pPage->intKey = 0;
51748     pPage->hasData = 0;
51749     pPage->maxLocal = pBt->maxLocal;
51750     pPage->minLocal = pBt->minLocal;
51751   }else{
51752     return SQLITE_CORRUPT_BKPT;
51753   }
51754   pPage->max1bytePayload = pBt->max1bytePayload;
51755   return SQLITE_OK;
51756 }
51757 
51758 /*
51759 ** Initialize the auxiliary information for a disk block.
51760 **
51761 ** Return SQLITE_OK on success.  If we see that the page does
51762 ** not contain a well-formed database page, then return 
51763 ** SQLITE_CORRUPT.  Note that a return of SQLITE_OK does not
51764 ** guarantee that the page is well-formed.  It only shows that
51765 ** we failed to detect any corruption.
51766 */
51767 static int btreeInitPage(MemPage *pPage){
51768 
51769   assert( pPage->pBt!=0 );
51770   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
51771   assert( pPage->pgno==sqlite3PagerPagenumber(pPage->pDbPage) );
51772   assert( pPage == sqlite3PagerGetExtra(pPage->pDbPage) );
51773   assert( pPage->aData == sqlite3PagerGetData(pPage->pDbPage) );
51774 
51775   if( !pPage->isInit ){
51776     u16 pc;            /* Address of a freeblock within pPage->aData[] */
51777     u8 hdr;            /* Offset to beginning of page header */
51778     u8 *data;          /* Equal to pPage->aData */
51779     BtShared *pBt;        /* The main btree structure */
51780     int usableSize;    /* Amount of usable space on each page */
51781     u16 cellOffset;    /* Offset from start of page to first cell pointer */
51782     int nFree;         /* Number of unused bytes on the page */
51783     int top;           /* First byte of the cell content area */
51784     int iCellFirst;    /* First allowable cell or freeblock offset */
51785     int iCellLast;     /* Last possible cell or freeblock offset */
51786 
51787     pBt = pPage->pBt;
51788 
51789     hdr = pPage->hdrOffset;
51790     data = pPage->aData;
51791     if( decodeFlags(pPage, data[hdr]) ) return SQLITE_CORRUPT_BKPT;
51792     assert( pBt->pageSize>=512 && pBt->pageSize<=65536 );
51793     pPage->maskPage = (u16)(pBt->pageSize - 1);
51794     pPage->nOverflow = 0;
51795     usableSize = pBt->usableSize;
51796     pPage->cellOffset = cellOffset = hdr + 12 - 4*pPage->leaf;
51797     pPage->aDataEnd = &data[usableSize];
51798     pPage->aCellIdx = &data[cellOffset];
51799     top = get2byteNotZero(&data[hdr+5]);
51800     pPage->nCell = get2byte(&data[hdr+3]);
51801     if( pPage->nCell>MX_CELL(pBt) ){
51802       /* To many cells for a single page.  The page must be corrupt */
51803       return SQLITE_CORRUPT_BKPT;
51804     }
51805     testcase( pPage->nCell==MX_CELL(pBt) );
51806 
51807     /* A malformed database page might cause us to read past the end
51808     ** of page when parsing a cell.  
51809     **
51810     ** The following block of code checks early to see if a cell extends
51811     ** past the end of a page boundary and causes SQLITE_CORRUPT to be 
51812     ** returned if it does.
51813     */
51814     iCellFirst = cellOffset + 2*pPage->nCell;
51815     iCellLast = usableSize - 4;
51816 #if defined(SQLITE_ENABLE_OVERSIZE_CELL_CHECK)
51817     {
51818       int i;            /* Index into the cell pointer array */
51819       int sz;           /* Size of a cell */
51820 
51821       if( !pPage->leaf ) iCellLast--;
51822       for(i=0; i<pPage->nCell; i++){
51823         pc = get2byte(&data[cellOffset+i*2]);
51824         testcase( pc==iCellFirst );
51825         testcase( pc==iCellLast );
51826         if( pc<iCellFirst || pc>iCellLast ){
51827           return SQLITE_CORRUPT_BKPT;
51828         }
51829         sz = cellSizePtr(pPage, &data[pc]);
51830         testcase( pc+sz==usableSize );
51831         if( pc+sz>usableSize ){
51832           return SQLITE_CORRUPT_BKPT;
51833         }
51834       }
51835       if( !pPage->leaf ) iCellLast++;
51836     }  
51837 #endif
51838 
51839     /* Compute the total free space on the page */
51840     pc = get2byte(&data[hdr+1]);
51841     nFree = data[hdr+7] + top;
51842     while( pc>0 ){
51843       u16 next, size;
51844       if( pc<iCellFirst || pc>iCellLast ){
51845         /* Start of free block is off the page */
51846         return SQLITE_CORRUPT_BKPT; 
51847       }
51848       next = get2byte(&data[pc]);
51849       size = get2byte(&data[pc+2]);
51850       if( (next>0 && next<=pc+size+3) || pc+size>usableSize ){
51851         /* Free blocks must be in ascending order. And the last byte of
51852         ** the free-block must lie on the database page.  */
51853         return SQLITE_CORRUPT_BKPT; 
51854       }
51855       nFree = nFree + size;
51856       pc = next;
51857     }
51858 
51859     /* At this point, nFree contains the sum of the offset to the start
51860     ** of the cell-content area plus the number of free bytes within
51861     ** the cell-content area. If this is greater than the usable-size
51862     ** of the page, then the page must be corrupted. This check also
51863     ** serves to verify that the offset to the start of the cell-content
51864     ** area, according to the page header, lies within the page.
51865     */
51866     if( nFree>usableSize ){
51867       return SQLITE_CORRUPT_BKPT; 
51868     }
51869     pPage->nFree = (u16)(nFree - iCellFirst);
51870     pPage->isInit = 1;
51871   }
51872   return SQLITE_OK;
51873 }
51874 
51875 /*
51876 ** Set up a raw page so that it looks like a database page holding
51877 ** no entries.
51878 */
51879 static void zeroPage(MemPage *pPage, int flags){
51880   unsigned char *data = pPage->aData;
51881   BtShared *pBt = pPage->pBt;
51882   u8 hdr = pPage->hdrOffset;
51883   u16 first;
51884 
51885   assert( sqlite3PagerPagenumber(pPage->pDbPage)==pPage->pgno );
51886   assert( sqlite3PagerGetExtra(pPage->pDbPage) == (void*)pPage );
51887   assert( sqlite3PagerGetData(pPage->pDbPage) == data );
51888   assert( sqlite3PagerIswriteable(pPage->pDbPage) );
51889   assert( sqlite3_mutex_held(pBt->mutex) );
51890   if( pBt->btsFlags & BTS_SECURE_DELETE ){
51891     memset(&data[hdr], 0, pBt->usableSize - hdr);
51892   }
51893   data[hdr] = (char)flags;
51894   first = hdr + 8 + 4*((flags&PTF_LEAF)==0 ?1:0);
51895   memset(&data[hdr+1], 0, 4);
51896   data[hdr+7] = 0;
51897   put2byte(&data[hdr+5], pBt->usableSize);
51898   pPage->nFree = (u16)(pBt->usableSize - first);
51899   decodeFlags(pPage, flags);
51900   pPage->hdrOffset = hdr;
51901   pPage->cellOffset = first;
51902   pPage->aDataEnd = &data[pBt->usableSize];
51903   pPage->aCellIdx = &data[first];
51904   pPage->nOverflow = 0;
51905   assert( pBt->pageSize>=512 && pBt->pageSize<=65536 );
51906   pPage->maskPage = (u16)(pBt->pageSize - 1);
51907   pPage->nCell = 0;
51908   pPage->isInit = 1;
51909 }
51910 
51911 
51912 /*
51913 ** Convert a DbPage obtained from the pager into a MemPage used by
51914 ** the btree layer.
51915 */
51916 static MemPage *btreePageFromDbPage(DbPage *pDbPage, Pgno pgno, BtShared *pBt){
51917   MemPage *pPage = (MemPage*)sqlite3PagerGetExtra(pDbPage);
51918   pPage->aData = sqlite3PagerGetData(pDbPage);
51919   pPage->pDbPage = pDbPage;
51920   pPage->pBt = pBt;
51921   pPage->pgno = pgno;
51922   pPage->hdrOffset = pPage->pgno==1 ? 100 : 0;
51923   return pPage; 
51924 }
51925 
51926 /*
51927 ** Get a page from the pager.  Initialize the MemPage.pBt and
51928 ** MemPage.aData elements if needed.
51929 **
51930 ** If the noContent flag is set, it means that we do not care about
51931 ** the content of the page at this time.  So do not go to the disk
51932 ** to fetch the content.  Just fill in the content with zeros for now.
51933 ** If in the future we call sqlite3PagerWrite() on this page, that
51934 ** means we have started to be concerned about content and the disk
51935 ** read should occur at that point.
51936 */
51937 static int btreeGetPage(
51938   BtShared *pBt,       /* The btree */
51939   Pgno pgno,           /* Number of the page to fetch */
51940   MemPage **ppPage,    /* Return the page in this parameter */
51941   int flags            /* PAGER_GET_NOCONTENT or PAGER_GET_READONLY */
51942 ){
51943   int rc;
51944   DbPage *pDbPage;
51945 
51946   assert( flags==0 || flags==PAGER_GET_NOCONTENT || flags==PAGER_GET_READONLY );
51947   assert( sqlite3_mutex_held(pBt->mutex) );
51948   rc = sqlite3PagerAcquire(pBt->pPager, pgno, (DbPage**)&pDbPage, flags);
51949   if( rc ) return rc;
51950   *ppPage = btreePageFromDbPage(pDbPage, pgno, pBt);
51951   return SQLITE_OK;
51952 }
51953 
51954 /*
51955 ** Retrieve a page from the pager cache. If the requested page is not
51956 ** already in the pager cache return NULL. Initialize the MemPage.pBt and
51957 ** MemPage.aData elements if needed.
51958 */
51959 static MemPage *btreePageLookup(BtShared *pBt, Pgno pgno){
51960   DbPage *pDbPage;
51961   assert( sqlite3_mutex_held(pBt->mutex) );
51962   pDbPage = sqlite3PagerLookup(pBt->pPager, pgno);
51963   if( pDbPage ){
51964     return btreePageFromDbPage(pDbPage, pgno, pBt);
51965   }
51966   return 0;
51967 }
51968 
51969 /*
51970 ** Return the size of the database file in pages. If there is any kind of
51971 ** error, return ((unsigned int)-1).
51972 */
51973 static Pgno btreePagecount(BtShared *pBt){
51974   return pBt->nPage;
51975 }
51976 SQLITE_PRIVATE u32 sqlite3BtreeLastPage(Btree *p){
51977   assert( sqlite3BtreeHoldsMutex(p) );
51978   assert( ((p->pBt->nPage)&0x8000000)==0 );
51979   return (int)btreePagecount(p->pBt);
51980 }
51981 
51982 /*
51983 ** Get a page from the pager and initialize it.  This routine is just a
51984 ** convenience wrapper around separate calls to btreeGetPage() and 
51985 ** btreeInitPage().
51986 **
51987 ** If an error occurs, then the value *ppPage is set to is undefined. It
51988 ** may remain unchanged, or it may be set to an invalid value.
51989 */
51990 static int getAndInitPage(
51991   BtShared *pBt,                  /* The database file */
51992   Pgno pgno,                      /* Number of the page to get */
51993   MemPage **ppPage,               /* Write the page pointer here */
51994   int bReadonly                   /* PAGER_GET_READONLY or 0 */
51995 ){
51996   int rc;
51997   assert( sqlite3_mutex_held(pBt->mutex) );
51998   assert( bReadonly==PAGER_GET_READONLY || bReadonly==0 );
51999 
52000   if( pgno>btreePagecount(pBt) ){
52001     rc = SQLITE_CORRUPT_BKPT;
52002   }else{
52003     rc = btreeGetPage(pBt, pgno, ppPage, bReadonly);
52004     if( rc==SQLITE_OK ){
52005       rc = btreeInitPage(*ppPage);
52006       if( rc!=SQLITE_OK ){
52007         releasePage(*ppPage);
52008       }
52009     }
52010   }
52011 
52012   testcase( pgno==0 );
52013   assert( pgno!=0 || rc==SQLITE_CORRUPT );
52014   return rc;
52015 }
52016 
52017 /*
52018 ** Release a MemPage.  This should be called once for each prior
52019 ** call to btreeGetPage.
52020 */
52021 static void releasePage(MemPage *pPage){
52022   if( pPage ){
52023     assert( pPage->aData );
52024     assert( pPage->pBt );
52025     assert( sqlite3PagerGetExtra(pPage->pDbPage) == (void*)pPage );
52026     assert( sqlite3PagerGetData(pPage->pDbPage)==pPage->aData );
52027     assert( sqlite3_mutex_held(pPage->pBt->mutex) );
52028     sqlite3PagerUnref(pPage->pDbPage);
52029   }
52030 }
52031 
52032 /*
52033 ** During a rollback, when the pager reloads information into the cache
52034 ** so that the cache is restored to its original state at the start of
52035 ** the transaction, for each page restored this routine is called.
52036 **
52037 ** This routine needs to reset the extra data section at the end of the
52038 ** page to agree with the restored data.
52039 */
52040 static void pageReinit(DbPage *pData){
52041   MemPage *pPage;
52042   pPage = (MemPage *)sqlite3PagerGetExtra(pData);
52043   assert( sqlite3PagerPageRefcount(pData)>0 );
52044   if( pPage->isInit ){
52045     assert( sqlite3_mutex_held(pPage->pBt->mutex) );
52046     pPage->isInit = 0;
52047     if( sqlite3PagerPageRefcount(pData)>1 ){
52048       /* pPage might not be a btree page;  it might be an overflow page
52049       ** or ptrmap page or a free page.  In those cases, the following
52050       ** call to btreeInitPage() will likely return SQLITE_CORRUPT.
52051       ** But no harm is done by this.  And it is very important that
52052       ** btreeInitPage() be called on every btree page so we make
52053       ** the call for every page that comes in for re-initing. */
52054       btreeInitPage(pPage);
52055     }
52056   }
52057 }
52058 
52059 /*
52060 ** Invoke the busy handler for a btree.
52061 */
52062 static int btreeInvokeBusyHandler(void *pArg){
52063   BtShared *pBt = (BtShared*)pArg;
52064   assert( pBt->db );
52065   assert( sqlite3_mutex_held(pBt->db->mutex) );
52066   return sqlite3InvokeBusyHandler(&pBt->db->busyHandler);
52067 }
52068 
52069 /*
52070 ** Open a database file.
52071 ** 
52072 ** zFilename is the name of the database file.  If zFilename is NULL
52073 ** then an ephemeral database is created.  The ephemeral database might
52074 ** be exclusively in memory, or it might use a disk-based memory cache.
52075 ** Either way, the ephemeral database will be automatically deleted 
52076 ** when sqlite3BtreeClose() is called.
52077 **
52078 ** If zFilename is ":memory:" then an in-memory database is created
52079 ** that is automatically destroyed when it is closed.
52080 **
52081 ** The "flags" parameter is a bitmask that might contain bits like
52082 ** BTREE_OMIT_JOURNAL and/or BTREE_MEMORY.
52083 **
52084 ** If the database is already opened in the same database connection
52085 ** and we are in shared cache mode, then the open will fail with an
52086 ** SQLITE_CONSTRAINT error.  We cannot allow two or more BtShared
52087 ** objects in the same database connection since doing so will lead
52088 ** to problems with locking.
52089 */
52090 SQLITE_PRIVATE int sqlite3BtreeOpen(
52091   sqlite3_vfs *pVfs,      /* VFS to use for this b-tree */
52092   const char *zFilename,  /* Name of the file containing the BTree database */
52093   sqlite3 *db,            /* Associated database handle */
52094   Btree **ppBtree,        /* Pointer to new Btree object written here */
52095   int flags,              /* Options */
52096   int vfsFlags            /* Flags passed through to sqlite3_vfs.xOpen() */
52097 ){
52098   BtShared *pBt = 0;             /* Shared part of btree structure */
52099   Btree *p;                      /* Handle to return */
52100   sqlite3_mutex *mutexOpen = 0;  /* Prevents a race condition. Ticket #3537 */
52101   int rc = SQLITE_OK;            /* Result code from this function */
52102   u8 nReserve;                   /* Byte of unused space on each page */
52103   unsigned char zDbHeader[100];  /* Database header content */
52104 
52105   /* True if opening an ephemeral, temporary database */
52106   const int isTempDb = zFilename==0 || zFilename[0]==0;
52107 
52108   /* Set the variable isMemdb to true for an in-memory database, or 
52109   ** false for a file-based database.
52110   */
52111 #ifdef SQLITE_OMIT_MEMORYDB
52112   const int isMemdb = 0;
52113 #else
52114   const int isMemdb = (zFilename && strcmp(zFilename, ":memory:")==0)
52115                        || (isTempDb && sqlite3TempInMemory(db))
52116                        || (vfsFlags & SQLITE_OPEN_MEMORY)!=0;
52117 #endif
52118 
52119   assert( db!=0 );
52120   assert( pVfs!=0 );
52121   assert( sqlite3_mutex_held(db->mutex) );
52122   assert( (flags&0xff)==flags );   /* flags fit in 8 bits */
52123 
52124   /* Only a BTREE_SINGLE database can be BTREE_UNORDERED */
52125   assert( (flags & BTREE_UNORDERED)==0 || (flags & BTREE_SINGLE)!=0 );
52126 
52127   /* A BTREE_SINGLE database is always a temporary and/or ephemeral */
52128   assert( (flags & BTREE_SINGLE)==0 || isTempDb );
52129 
52130   if( isMemdb ){
52131     flags |= BTREE_MEMORY;
52132   }
52133   if( (vfsFlags & SQLITE_OPEN_MAIN_DB)!=0 && (isMemdb || isTempDb) ){
52134     vfsFlags = (vfsFlags & ~SQLITE_OPEN_MAIN_DB) | SQLITE_OPEN_TEMP_DB;
52135   }
52136   p = sqlite3MallocZero(sizeof(Btree));
52137   if( !p ){
52138     return SQLITE_NOMEM;
52139   }
52140   p->inTrans = TRANS_NONE;
52141   p->db = db;
52142 #ifndef SQLITE_OMIT_SHARED_CACHE
52143   p->lock.pBtree = p;
52144   p->lock.iTable = 1;
52145 #endif
52146 
52147 #if !defined(SQLITE_OMIT_SHARED_CACHE) && !defined(SQLITE_OMIT_DISKIO)
52148   /*
52149   ** If this Btree is a candidate for shared cache, try to find an
52150   ** existing BtShared object that we can share with
52151   */
52152   if( isTempDb==0 && (isMemdb==0 || (vfsFlags&SQLITE_OPEN_URI)!=0) ){
52153     if( vfsFlags & SQLITE_OPEN_SHAREDCACHE ){
52154       int nFullPathname = pVfs->mxPathname+1;
52155       char *zFullPathname = sqlite3Malloc(nFullPathname);
52156       MUTEX_LOGIC( sqlite3_mutex *mutexShared; )
52157       p->sharable = 1;
52158       if( !zFullPathname ){
52159         sqlite3_free(p);
52160         return SQLITE_NOMEM;
52161       }
52162       if( isMemdb ){
52163         memcpy(zFullPathname, zFilename, sqlite3Strlen30(zFilename)+1);
52164       }else{
52165         rc = sqlite3OsFullPathname(pVfs, zFilename,
52166                                    nFullPathname, zFullPathname);
52167         if( rc ){
52168           sqlite3_free(zFullPathname);
52169           sqlite3_free(p);
52170           return rc;
52171         }
52172       }
52173 #if SQLITE_THREADSAFE
52174       mutexOpen = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_OPEN);
52175       sqlite3_mutex_enter(mutexOpen);
52176       mutexShared = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
52177       sqlite3_mutex_enter(mutexShared);
52178 #endif
52179       for(pBt=GLOBAL(BtShared*,sqlite3SharedCacheList); pBt; pBt=pBt->pNext){
52180         assert( pBt->nRef>0 );
52181         if( 0==strcmp(zFullPathname, sqlite3PagerFilename(pBt->pPager, 0))
52182                  && sqlite3PagerVfs(pBt->pPager)==pVfs ){
52183           int iDb;
52184           for(iDb=db->nDb-1; iDb>=0; iDb--){
52185             Btree *pExisting = db->aDb[iDb].pBt;
52186             if( pExisting && pExisting->pBt==pBt ){
52187               sqlite3_mutex_leave(mutexShared);
52188               sqlite3_mutex_leave(mutexOpen);
52189               sqlite3_free(zFullPathname);
52190               sqlite3_free(p);
52191               return SQLITE_CONSTRAINT;
52192             }
52193           }
52194           p->pBt = pBt;
52195           pBt->nRef++;
52196           break;
52197         }
52198       }
52199       sqlite3_mutex_leave(mutexShared);
52200       sqlite3_free(zFullPathname);
52201     }
52202 #ifdef SQLITE_DEBUG
52203     else{
52204       /* In debug mode, we mark all persistent databases as sharable
52205       ** even when they are not.  This exercises the locking code and
52206       ** gives more opportunity for asserts(sqlite3_mutex_held())
52207       ** statements to find locking problems.
52208       */
52209       p->sharable = 1;
52210     }
52211 #endif
52212   }
52213 #endif
52214   if( pBt==0 ){
52215     /*
52216     ** The following asserts make sure that structures used by the btree are
52217     ** the right size.  This is to guard against size changes that result
52218     ** when compiling on a different architecture.
52219     */
52220     assert( sizeof(i64)==8 || sizeof(i64)==4 );
52221     assert( sizeof(u64)==8 || sizeof(u64)==4 );
52222     assert( sizeof(u32)==4 );
52223     assert( sizeof(u16)==2 );
52224     assert( sizeof(Pgno)==4 );
52225   
52226     pBt = sqlite3MallocZero( sizeof(*pBt) );
52227     if( pBt==0 ){
52228       rc = SQLITE_NOMEM;
52229       goto btree_open_out;
52230     }
52231     rc = sqlite3PagerOpen(pVfs, &pBt->pPager, zFilename,
52232                           EXTRA_SIZE, flags, vfsFlags, pageReinit);
52233     if( rc==SQLITE_OK ){
52234       sqlite3PagerSetMmapLimit(pBt->pPager, db->szMmap);
52235       rc = sqlite3PagerReadFileheader(pBt->pPager,sizeof(zDbHeader),zDbHeader);
52236     }
52237     if( rc!=SQLITE_OK ){
52238       goto btree_open_out;
52239     }
52240     pBt->openFlags = (u8)flags;
52241     pBt->db = db;
52242     sqlite3PagerSetBusyhandler(pBt->pPager, btreeInvokeBusyHandler, pBt);
52243     p->pBt = pBt;
52244   
52245     pBt->pCursor = 0;
52246     pBt->pPage1 = 0;
52247     if( sqlite3PagerIsreadonly(pBt->pPager) ) pBt->btsFlags |= BTS_READ_ONLY;
52248 #ifdef SQLITE_SECURE_DELETE
52249     pBt->btsFlags |= BTS_SECURE_DELETE;
52250 #endif
52251     pBt->pageSize = (zDbHeader[16]<<8) | (zDbHeader[17]<<16);
52252     if( pBt->pageSize<512 || pBt->pageSize>SQLITE_MAX_PAGE_SIZE
52253          || ((pBt->pageSize-1)&pBt->pageSize)!=0 ){
52254       pBt->pageSize = 0;
52255 #ifndef SQLITE_OMIT_AUTOVACUUM
52256       /* If the magic name ":memory:" will create an in-memory database, then
52257       ** leave the autoVacuum mode at 0 (do not auto-vacuum), even if
52258       ** SQLITE_DEFAULT_AUTOVACUUM is true. On the other hand, if
52259       ** SQLITE_OMIT_MEMORYDB has been defined, then ":memory:" is just a
52260       ** regular file-name. In this case the auto-vacuum applies as per normal.
52261       */
52262       if( zFilename && !isMemdb ){
52263         pBt->autoVacuum = (SQLITE_DEFAULT_AUTOVACUUM ? 1 : 0);
52264         pBt->incrVacuum = (SQLITE_DEFAULT_AUTOVACUUM==2 ? 1 : 0);
52265       }
52266 #endif
52267       nReserve = 0;
52268     }else{
52269       nReserve = zDbHeader[20];
52270       pBt->btsFlags |= BTS_PAGESIZE_FIXED;
52271 #ifndef SQLITE_OMIT_AUTOVACUUM
52272       pBt->autoVacuum = (get4byte(&zDbHeader[36 + 4*4])?1:0);
52273       pBt->incrVacuum = (get4byte(&zDbHeader[36 + 7*4])?1:0);
52274 #endif
52275     }
52276     rc = sqlite3PagerSetPagesize(pBt->pPager, &pBt->pageSize, nReserve);
52277     if( rc ) goto btree_open_out;
52278     pBt->usableSize = pBt->pageSize - nReserve;
52279     assert( (pBt->pageSize & 7)==0 );  /* 8-byte alignment of pageSize */
52280    
52281 #if !defined(SQLITE_OMIT_SHARED_CACHE) && !defined(SQLITE_OMIT_DISKIO)
52282     /* Add the new BtShared object to the linked list sharable BtShareds.
52283     */
52284     if( p->sharable ){
52285       MUTEX_LOGIC( sqlite3_mutex *mutexShared; )
52286       pBt->nRef = 1;
52287       MUTEX_LOGIC( mutexShared = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);)
52288       if( SQLITE_THREADSAFE && sqlite3GlobalConfig.bCoreMutex ){
52289         pBt->mutex = sqlite3MutexAlloc(SQLITE_MUTEX_FAST);
52290         if( pBt->mutex==0 ){
52291           rc = SQLITE_NOMEM;
52292           db->mallocFailed = 0;
52293           goto btree_open_out;
52294         }
52295       }
52296       sqlite3_mutex_enter(mutexShared);
52297       pBt->pNext = GLOBAL(BtShared*,sqlite3SharedCacheList);
52298       GLOBAL(BtShared*,sqlite3SharedCacheList) = pBt;
52299       sqlite3_mutex_leave(mutexShared);
52300     }
52301 #endif
52302   }
52303 
52304 #if !defined(SQLITE_OMIT_SHARED_CACHE) && !defined(SQLITE_OMIT_DISKIO)
52305   /* If the new Btree uses a sharable pBtShared, then link the new
52306   ** Btree into the list of all sharable Btrees for the same connection.
52307   ** The list is kept in ascending order by pBt address.
52308   */
52309   if( p->sharable ){
52310     int i;
52311     Btree *pSib;
52312     for(i=0; i<db->nDb; i++){
52313       if( (pSib = db->aDb[i].pBt)!=0 && pSib->sharable ){
52314         while( pSib->pPrev ){ pSib = pSib->pPrev; }
52315         if( p->pBt<pSib->pBt ){
52316           p->pNext = pSib;
52317           p->pPrev = 0;
52318           pSib->pPrev = p;
52319         }else{
52320           while( pSib->pNext && pSib->pNext->pBt<p->pBt ){
52321             pSib = pSib->pNext;
52322           }
52323           p->pNext = pSib->pNext;
52324           p->pPrev = pSib;
52325           if( p->pNext ){
52326             p->pNext->pPrev = p;
52327           }
52328           pSib->pNext = p;
52329         }
52330         break;
52331       }
52332     }
52333   }
52334 #endif
52335   *ppBtree = p;
52336 
52337 btree_open_out:
52338   if( rc!=SQLITE_OK ){
52339     if( pBt && pBt->pPager ){
52340       sqlite3PagerClose(pBt->pPager);
52341     }
52342     sqlite3_free(pBt);
52343     sqlite3_free(p);
52344     *ppBtree = 0;
52345   }else{
52346     /* If the B-Tree was successfully opened, set the pager-cache size to the
52347     ** default value. Except, when opening on an existing shared pager-cache,
52348     ** do not change the pager-cache size.
52349     */
52350     if( sqlite3BtreeSchema(p, 0, 0)==0 ){
52351       sqlite3PagerSetCachesize(p->pBt->pPager, SQLITE_DEFAULT_CACHE_SIZE);
52352     }
52353   }
52354   if( mutexOpen ){
52355     assert( sqlite3_mutex_held(mutexOpen) );
52356     sqlite3_mutex_leave(mutexOpen);
52357   }
52358   return rc;
52359 }
52360 
52361 /*
52362 ** Decrement the BtShared.nRef counter.  When it reaches zero,
52363 ** remove the BtShared structure from the sharing list.  Return
52364 ** true if the BtShared.nRef counter reaches zero and return
52365 ** false if it is still positive.
52366 */
52367 static int removeFromSharingList(BtShared *pBt){
52368 #ifndef SQLITE_OMIT_SHARED_CACHE
52369   MUTEX_LOGIC( sqlite3_mutex *pMaster; )
52370   BtShared *pList;
52371   int removed = 0;
52372 
52373   assert( sqlite3_mutex_notheld(pBt->mutex) );
52374   MUTEX_LOGIC( pMaster = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); )
52375   sqlite3_mutex_enter(pMaster);
52376   pBt->nRef--;
52377   if( pBt->nRef<=0 ){
52378     if( GLOBAL(BtShared*,sqlite3SharedCacheList)==pBt ){
52379       GLOBAL(BtShared*,sqlite3SharedCacheList) = pBt->pNext;
52380     }else{
52381       pList = GLOBAL(BtShared*,sqlite3SharedCacheList);
52382       while( ALWAYS(pList) && pList->pNext!=pBt ){
52383         pList=pList->pNext;
52384       }
52385       if( ALWAYS(pList) ){
52386         pList->pNext = pBt->pNext;
52387       }
52388     }
52389     if( SQLITE_THREADSAFE ){
52390       sqlite3_mutex_free(pBt->mutex);
52391     }
52392     removed = 1;
52393   }
52394   sqlite3_mutex_leave(pMaster);
52395   return removed;
52396 #else
52397   return 1;
52398 #endif
52399 }
52400 
52401 /*
52402 ** Make sure pBt->pTmpSpace points to an allocation of 
52403 ** MX_CELL_SIZE(pBt) bytes.
52404 */
52405 static void allocateTempSpace(BtShared *pBt){
52406   if( !pBt->pTmpSpace ){
52407     pBt->pTmpSpace = sqlite3PageMalloc( pBt->pageSize );
52408 
52409     /* One of the uses of pBt->pTmpSpace is to format cells before
52410     ** inserting them into a leaf page (function fillInCell()). If
52411     ** a cell is less than 4 bytes in size, it is rounded up to 4 bytes
52412     ** by the various routines that manipulate binary cells. Which
52413     ** can mean that fillInCell() only initializes the first 2 or 3
52414     ** bytes of pTmpSpace, but that the first 4 bytes are copied from
52415     ** it into a database page. This is not actually a problem, but it
52416     ** does cause a valgrind error when the 1 or 2 bytes of unitialized 
52417     ** data is passed to system call write(). So to avoid this error,
52418     ** zero the first 4 bytes of temp space here.  */
52419     if( pBt->pTmpSpace ) memset(pBt->pTmpSpace, 0, 4);
52420   }
52421 }
52422 
52423 /*
52424 ** Free the pBt->pTmpSpace allocation
52425 */
52426 static void freeTempSpace(BtShared *pBt){
52427   sqlite3PageFree( pBt->pTmpSpace);
52428   pBt->pTmpSpace = 0;
52429 }
52430 
52431 /*
52432 ** Close an open database and invalidate all cursors.
52433 */
52434 SQLITE_PRIVATE int sqlite3BtreeClose(Btree *p){
52435   BtShared *pBt = p->pBt;
52436   BtCursor *pCur;
52437 
52438   /* Close all cursors opened via this handle.  */
52439   assert( sqlite3_mutex_held(p->db->mutex) );
52440   sqlite3BtreeEnter(p);
52441   pCur = pBt->pCursor;
52442   while( pCur ){
52443     BtCursor *pTmp = pCur;
52444     pCur = pCur->pNext;
52445     if( pTmp->pBtree==p ){
52446       sqlite3BtreeCloseCursor(pTmp);
52447     }
52448   }
52449 
52450   /* Rollback any active transaction and free the handle structure.
52451   ** The call to sqlite3BtreeRollback() drops any table-locks held by
52452   ** this handle.
52453   */
52454   sqlite3BtreeRollback(p, SQLITE_OK);
52455   sqlite3BtreeLeave(p);
52456 
52457   /* If there are still other outstanding references to the shared-btree
52458   ** structure, return now. The remainder of this procedure cleans 
52459   ** up the shared-btree.
52460   */
52461   assert( p->wantToLock==0 && p->locked==0 );
52462   if( !p->sharable || removeFromSharingList(pBt) ){
52463     /* The pBt is no longer on the sharing list, so we can access
52464     ** it without having to hold the mutex.
52465     **
52466     ** Clean out and delete the BtShared object.
52467     */
52468     assert( !pBt->pCursor );
52469     sqlite3PagerClose(pBt->pPager);
52470     if( pBt->xFreeSchema && pBt->pSchema ){
52471       pBt->xFreeSchema(pBt->pSchema);
52472     }
52473     sqlite3DbFree(0, pBt->pSchema);
52474     freeTempSpace(pBt);
52475     sqlite3_free(pBt);
52476   }
52477 
52478 #ifndef SQLITE_OMIT_SHARED_CACHE
52479   assert( p->wantToLock==0 );
52480   assert( p->locked==0 );
52481   if( p->pPrev ) p->pPrev->pNext = p->pNext;
52482   if( p->pNext ) p->pNext->pPrev = p->pPrev;
52483 #endif
52484 
52485   sqlite3_free(p);
52486   return SQLITE_OK;
52487 }
52488 
52489 /*
52490 ** Change the limit on the number of pages allowed in the cache.
52491 **
52492 ** The maximum number of cache pages is set to the absolute
52493 ** value of mxPage.  If mxPage is negative, the pager will
52494 ** operate asynchronously - it will not stop to do fsync()s
52495 ** to insure data is written to the disk surface before
52496 ** continuing.  Transactions still work if synchronous is off,
52497 ** and the database cannot be corrupted if this program
52498 ** crashes.  But if the operating system crashes or there is
52499 ** an abrupt power failure when synchronous is off, the database
52500 ** could be left in an inconsistent and unrecoverable state.
52501 ** Synchronous is on by default so database corruption is not
52502 ** normally a worry.
52503 */
52504 SQLITE_PRIVATE int sqlite3BtreeSetCacheSize(Btree *p, int mxPage){
52505   BtShared *pBt = p->pBt;
52506   assert( sqlite3_mutex_held(p->db->mutex) );
52507   sqlite3BtreeEnter(p);
52508   sqlite3PagerSetCachesize(pBt->pPager, mxPage);
52509   sqlite3BtreeLeave(p);
52510   return SQLITE_OK;
52511 }
52512 
52513 /*
52514 ** Change the limit on the amount of the database file that may be
52515 ** memory mapped.
52516 */
52517 SQLITE_PRIVATE int sqlite3BtreeSetMmapLimit(Btree *p, sqlite3_int64 szMmap){
52518   BtShared *pBt = p->pBt;
52519   assert( sqlite3_mutex_held(p->db->mutex) );
52520   sqlite3BtreeEnter(p);
52521   sqlite3PagerSetMmapLimit(pBt->pPager, szMmap);
52522   sqlite3BtreeLeave(p);
52523   return SQLITE_OK;
52524 }
52525 
52526 /*
52527 ** Change the way data is synced to disk in order to increase or decrease
52528 ** how well the database resists damage due to OS crashes and power
52529 ** failures.  Level 1 is the same as asynchronous (no syncs() occur and
52530 ** there is a high probability of damage)  Level 2 is the default.  There
52531 ** is a very low but non-zero probability of damage.  Level 3 reduces the
52532 ** probability of damage to near zero but with a write performance reduction.
52533 */
52534 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
52535 SQLITE_PRIVATE int sqlite3BtreeSetPagerFlags(
52536   Btree *p,              /* The btree to set the safety level on */
52537   unsigned pgFlags       /* Various PAGER_* flags */
52538 ){
52539   BtShared *pBt = p->pBt;
52540   assert( sqlite3_mutex_held(p->db->mutex) );
52541   sqlite3BtreeEnter(p);
52542   sqlite3PagerSetFlags(pBt->pPager, pgFlags);
52543   sqlite3BtreeLeave(p);
52544   return SQLITE_OK;
52545 }
52546 #endif
52547 
52548 /*
52549 ** Return TRUE if the given btree is set to safety level 1.  In other
52550 ** words, return TRUE if no sync() occurs on the disk files.
52551 */
52552 SQLITE_PRIVATE int sqlite3BtreeSyncDisabled(Btree *p){
52553   BtShared *pBt = p->pBt;
52554   int rc;
52555   assert( sqlite3_mutex_held(p->db->mutex) );  
52556   sqlite3BtreeEnter(p);
52557   assert( pBt && pBt->pPager );
52558   rc = sqlite3PagerNosync(pBt->pPager);
52559   sqlite3BtreeLeave(p);
52560   return rc;
52561 }
52562 
52563 /*
52564 ** Change the default pages size and the number of reserved bytes per page.
52565 ** Or, if the page size has already been fixed, return SQLITE_READONLY 
52566 ** without changing anything.
52567 **
52568 ** The page size must be a power of 2 between 512 and 65536.  If the page
52569 ** size supplied does not meet this constraint then the page size is not
52570 ** changed.
52571 **
52572 ** Page sizes are constrained to be a power of two so that the region
52573 ** of the database file used for locking (beginning at PENDING_BYTE,
52574 ** the first byte past the 1GB boundary, 0x40000000) needs to occur
52575 ** at the beginning of a page.
52576 **
52577 ** If parameter nReserve is less than zero, then the number of reserved
52578 ** bytes per page is left unchanged.
52579 **
52580 ** If the iFix!=0 then the BTS_PAGESIZE_FIXED flag is set so that the page size
52581 ** and autovacuum mode can no longer be changed.
52582 */
52583 SQLITE_PRIVATE int sqlite3BtreeSetPageSize(Btree *p, int pageSize, int nReserve, int iFix){
52584   int rc = SQLITE_OK;
52585   BtShared *pBt = p->pBt;
52586   assert( nReserve>=-1 && nReserve<=255 );
52587   sqlite3BtreeEnter(p);
52588   if( pBt->btsFlags & BTS_PAGESIZE_FIXED ){
52589     sqlite3BtreeLeave(p);
52590     return SQLITE_READONLY;
52591   }
52592   if( nReserve<0 ){
52593     nReserve = pBt->pageSize - pBt->usableSize;
52594   }
52595   assert( nReserve>=0 && nReserve<=255 );
52596   if( pageSize>=512 && pageSize<=SQLITE_MAX_PAGE_SIZE &&
52597         ((pageSize-1)&pageSize)==0 ){
52598     assert( (pageSize & 7)==0 );
52599     assert( !pBt->pPage1 && !pBt->pCursor );
52600     pBt->pageSize = (u32)pageSize;
52601     freeTempSpace(pBt);
52602   }
52603   rc = sqlite3PagerSetPagesize(pBt->pPager, &pBt->pageSize, nReserve);
52604   pBt->usableSize = pBt->pageSize - (u16)nReserve;
52605   if( iFix ) pBt->btsFlags |= BTS_PAGESIZE_FIXED;
52606   sqlite3BtreeLeave(p);
52607   return rc;
52608 }
52609 
52610 /*
52611 ** Return the currently defined page size
52612 */
52613 SQLITE_PRIVATE int sqlite3BtreeGetPageSize(Btree *p){
52614   return p->pBt->pageSize;
52615 }
52616 
52617 #if defined(SQLITE_HAS_CODEC) || defined(SQLITE_DEBUG)
52618 /*
52619 ** This function is similar to sqlite3BtreeGetReserve(), except that it
52620 ** may only be called if it is guaranteed that the b-tree mutex is already
52621 ** held.
52622 **
52623 ** This is useful in one special case in the backup API code where it is
52624 ** known that the shared b-tree mutex is held, but the mutex on the 
52625 ** database handle that owns *p is not. In this case if sqlite3BtreeEnter()
52626 ** were to be called, it might collide with some other operation on the
52627 ** database handle that owns *p, causing undefined behavior.
52628 */
52629 SQLITE_PRIVATE int sqlite3BtreeGetReserveNoMutex(Btree *p){
52630   assert( sqlite3_mutex_held(p->pBt->mutex) );
52631   return p->pBt->pageSize - p->pBt->usableSize;
52632 }
52633 #endif /* SQLITE_HAS_CODEC || SQLITE_DEBUG */
52634 
52635 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS) || !defined(SQLITE_OMIT_VACUUM)
52636 /*
52637 ** Return the number of bytes of space at the end of every page that
52638 ** are intentually left unused.  This is the "reserved" space that is
52639 ** sometimes used by extensions.
52640 */
52641 SQLITE_PRIVATE int sqlite3BtreeGetReserve(Btree *p){
52642   int n;
52643   sqlite3BtreeEnter(p);
52644   n = p->pBt->pageSize - p->pBt->usableSize;
52645   sqlite3BtreeLeave(p);
52646   return n;
52647 }
52648 
52649 /*
52650 ** Set the maximum page count for a database if mxPage is positive.
52651 ** No changes are made if mxPage is 0 or negative.
52652 ** Regardless of the value of mxPage, return the maximum page count.
52653 */
52654 SQLITE_PRIVATE int sqlite3BtreeMaxPageCount(Btree *p, int mxPage){
52655   int n;
52656   sqlite3BtreeEnter(p);
52657   n = sqlite3PagerMaxPageCount(p->pBt->pPager, mxPage);
52658   sqlite3BtreeLeave(p);
52659   return n;
52660 }
52661 
52662 /*
52663 ** Set the BTS_SECURE_DELETE flag if newFlag is 0 or 1.  If newFlag is -1,
52664 ** then make no changes.  Always return the value of the BTS_SECURE_DELETE
52665 ** setting after the change.
52666 */
52667 SQLITE_PRIVATE int sqlite3BtreeSecureDelete(Btree *p, int newFlag){
52668   int b;
52669   if( p==0 ) return 0;
52670   sqlite3BtreeEnter(p);
52671   if( newFlag>=0 ){
52672     p->pBt->btsFlags &= ~BTS_SECURE_DELETE;
52673     if( newFlag ) p->pBt->btsFlags |= BTS_SECURE_DELETE;
52674   } 
52675   b = (p->pBt->btsFlags & BTS_SECURE_DELETE)!=0;
52676   sqlite3BtreeLeave(p);
52677   return b;
52678 }
52679 #endif /* !defined(SQLITE_OMIT_PAGER_PRAGMAS) || !defined(SQLITE_OMIT_VACUUM) */
52680 
52681 /*
52682 ** Change the 'auto-vacuum' property of the database. If the 'autoVacuum'
52683 ** parameter is non-zero, then auto-vacuum mode is enabled. If zero, it
52684 ** is disabled. The default value for the auto-vacuum property is 
52685 ** determined by the SQLITE_DEFAULT_AUTOVACUUM macro.
52686 */
52687 SQLITE_PRIVATE int sqlite3BtreeSetAutoVacuum(Btree *p, int autoVacuum){
52688 #ifdef SQLITE_OMIT_AUTOVACUUM
52689   return SQLITE_READONLY;
52690 #else
52691   BtShared *pBt = p->pBt;
52692   int rc = SQLITE_OK;
52693   u8 av = (u8)autoVacuum;
52694 
52695   sqlite3BtreeEnter(p);
52696   if( (pBt->btsFlags & BTS_PAGESIZE_FIXED)!=0 && (av ?1:0)!=pBt->autoVacuum ){
52697     rc = SQLITE_READONLY;
52698   }else{
52699     pBt->autoVacuum = av ?1:0;
52700     pBt->incrVacuum = av==2 ?1:0;
52701   }
52702   sqlite3BtreeLeave(p);
52703   return rc;
52704 #endif
52705 }
52706 
52707 /*
52708 ** Return the value of the 'auto-vacuum' property. If auto-vacuum is 
52709 ** enabled 1 is returned. Otherwise 0.
52710 */
52711 SQLITE_PRIVATE int sqlite3BtreeGetAutoVacuum(Btree *p){
52712 #ifdef SQLITE_OMIT_AUTOVACUUM
52713   return BTREE_AUTOVACUUM_NONE;
52714 #else
52715   int rc;
52716   sqlite3BtreeEnter(p);
52717   rc = (
52718     (!p->pBt->autoVacuum)?BTREE_AUTOVACUUM_NONE:
52719     (!p->pBt->incrVacuum)?BTREE_AUTOVACUUM_FULL:
52720     BTREE_AUTOVACUUM_INCR
52721   );
52722   sqlite3BtreeLeave(p);
52723   return rc;
52724 #endif
52725 }
52726 
52727 
52728 /*
52729 ** Get a reference to pPage1 of the database file.  This will
52730 ** also acquire a readlock on that file.
52731 **
52732 ** SQLITE_OK is returned on success.  If the file is not a
52733 ** well-formed database file, then SQLITE_CORRUPT is returned.
52734 ** SQLITE_BUSY is returned if the database is locked.  SQLITE_NOMEM
52735 ** is returned if we run out of memory. 
52736 */
52737 static int lockBtree(BtShared *pBt){
52738   int rc;              /* Result code from subfunctions */
52739   MemPage *pPage1;     /* Page 1 of the database file */
52740   int nPage;           /* Number of pages in the database */
52741   int nPageFile = 0;   /* Number of pages in the database file */
52742   int nPageHeader;     /* Number of pages in the database according to hdr */
52743 
52744   assert( sqlite3_mutex_held(pBt->mutex) );
52745   assert( pBt->pPage1==0 );
52746   rc = sqlite3PagerSharedLock(pBt->pPager);
52747   if( rc!=SQLITE_OK ) return rc;
52748   rc = btreeGetPage(pBt, 1, &pPage1, 0);
52749   if( rc!=SQLITE_OK ) return rc;
52750 
52751   /* Do some checking to help insure the file we opened really is
52752   ** a valid database file. 
52753   */
52754   nPage = nPageHeader = get4byte(28+(u8*)pPage1->aData);
52755   sqlite3PagerPagecount(pBt->pPager, &nPageFile);
52756   if( nPage==0 || memcmp(24+(u8*)pPage1->aData, 92+(u8*)pPage1->aData,4)!=0 ){
52757     nPage = nPageFile;
52758   }
52759   if( nPage>0 ){
52760     u32 pageSize;
52761     u32 usableSize;
52762     u8 *page1 = pPage1->aData;
52763     rc = SQLITE_NOTADB;
52764     if( memcmp(page1, zMagicHeader, 16)!=0 ){
52765       goto page1_init_failed;
52766     }
52767 
52768 #ifdef SQLITE_OMIT_WAL
52769     if( page1[18]>1 ){
52770       pBt->btsFlags |= BTS_READ_ONLY;
52771     }
52772     if( page1[19]>1 ){
52773       goto page1_init_failed;
52774     }
52775 #else
52776     if( page1[18]>2 ){
52777       pBt->btsFlags |= BTS_READ_ONLY;
52778     }
52779     if( page1[19]>2 ){
52780       goto page1_init_failed;
52781     }
52782 
52783     /* If the write version is set to 2, this database should be accessed
52784     ** in WAL mode. If the log is not already open, open it now. Then 
52785     ** return SQLITE_OK and return without populating BtShared.pPage1.
52786     ** The caller detects this and calls this function again. This is
52787     ** required as the version of page 1 currently in the page1 buffer
52788     ** may not be the latest version - there may be a newer one in the log
52789     ** file.
52790     */
52791     if( page1[19]==2 && (pBt->btsFlags & BTS_NO_WAL)==0 ){
52792       int isOpen = 0;
52793       rc = sqlite3PagerOpenWal(pBt->pPager, &isOpen);
52794       if( rc!=SQLITE_OK ){
52795         goto page1_init_failed;
52796       }else if( isOpen==0 ){
52797         releasePage(pPage1);
52798         return SQLITE_OK;
52799       }
52800       rc = SQLITE_NOTADB;
52801     }
52802 #endif
52803 
52804     /* The maximum embedded fraction must be exactly 25%.  And the minimum
52805     ** embedded fraction must be 12.5% for both leaf-data and non-leaf-data.
52806     ** The original design allowed these amounts to vary, but as of
52807     ** version 3.6.0, we require them to be fixed.
52808     */
52809     if( memcmp(&page1[21], "\100\040\040",3)!=0 ){
52810       goto page1_init_failed;
52811     }
52812     pageSize = (page1[16]<<8) | (page1[17]<<16);
52813     if( ((pageSize-1)&pageSize)!=0
52814      || pageSize>SQLITE_MAX_PAGE_SIZE 
52815      || pageSize<=256 
52816     ){
52817       goto page1_init_failed;
52818     }
52819     assert( (pageSize & 7)==0 );
52820     usableSize = pageSize - page1[20];
52821     if( (u32)pageSize!=pBt->pageSize ){
52822       /* After reading the first page of the database assuming a page size
52823       ** of BtShared.pageSize, we have discovered that the page-size is
52824       ** actually pageSize. Unlock the database, leave pBt->pPage1 at
52825       ** zero and return SQLITE_OK. The caller will call this function
52826       ** again with the correct page-size.
52827       */
52828       releasePage(pPage1);
52829       pBt->usableSize = usableSize;
52830       pBt->pageSize = pageSize;
52831       freeTempSpace(pBt);
52832       rc = sqlite3PagerSetPagesize(pBt->pPager, &pBt->pageSize,
52833                                    pageSize-usableSize);
52834       return rc;
52835     }
52836     if( (pBt->db->flags & SQLITE_RecoveryMode)==0 && nPage>nPageFile ){
52837       rc = SQLITE_CORRUPT_BKPT;
52838       goto page1_init_failed;
52839     }
52840     if( usableSize<480 ){
52841       goto page1_init_failed;
52842     }
52843     pBt->pageSize = pageSize;
52844     pBt->usableSize = usableSize;
52845 #ifndef SQLITE_OMIT_AUTOVACUUM
52846     pBt->autoVacuum = (get4byte(&page1[36 + 4*4])?1:0);
52847     pBt->incrVacuum = (get4byte(&page1[36 + 7*4])?1:0);
52848 #endif
52849   }
52850 
52851   /* maxLocal is the maximum amount of payload to store locally for
52852   ** a cell.  Make sure it is small enough so that at least minFanout
52853   ** cells can will fit on one page.  We assume a 10-byte page header.
52854   ** Besides the payload, the cell must store:
52855   **     2-byte pointer to the cell
52856   **     4-byte child pointer
52857   **     9-byte nKey value
52858   **     4-byte nData value
52859   **     4-byte overflow page pointer
52860   ** So a cell consists of a 2-byte pointer, a header which is as much as
52861   ** 17 bytes long, 0 to N bytes of payload, and an optional 4 byte overflow
52862   ** page pointer.
52863   */
52864   pBt->maxLocal = (u16)((pBt->usableSize-12)*64/255 - 23);
52865   pBt->minLocal = (u16)((pBt->usableSize-12)*32/255 - 23);
52866   pBt->maxLeaf = (u16)(pBt->usableSize - 35);
52867   pBt->minLeaf = (u16)((pBt->usableSize-12)*32/255 - 23);
52868   if( pBt->maxLocal>127 ){
52869     pBt->max1bytePayload = 127;
52870   }else{
52871     pBt->max1bytePayload = (u8)pBt->maxLocal;
52872   }
52873   assert( pBt->maxLeaf + 23 <= MX_CELL_SIZE(pBt) );
52874   pBt->pPage1 = pPage1;
52875   pBt->nPage = nPage;
52876   return SQLITE_OK;
52877 
52878 page1_init_failed:
52879   releasePage(pPage1);
52880   pBt->pPage1 = 0;
52881   return rc;
52882 }
52883 
52884 #ifndef NDEBUG
52885 /*
52886 ** Return the number of cursors open on pBt. This is for use
52887 ** in assert() expressions, so it is only compiled if NDEBUG is not
52888 ** defined.
52889 **
52890 ** Only write cursors are counted if wrOnly is true.  If wrOnly is
52891 ** false then all cursors are counted.
52892 **
52893 ** For the purposes of this routine, a cursor is any cursor that
52894 ** is capable of reading or writing to the databse.  Cursors that
52895 ** have been tripped into the CURSOR_FAULT state are not counted.
52896 */
52897 static int countValidCursors(BtShared *pBt, int wrOnly){
52898   BtCursor *pCur;
52899   int r = 0;
52900   for(pCur=pBt->pCursor; pCur; pCur=pCur->pNext){
52901     if( (wrOnly==0 || pCur->wrFlag) && pCur->eState!=CURSOR_FAULT ) r++; 
52902   }
52903   return r;
52904 }
52905 #endif
52906 
52907 /*
52908 ** If there are no outstanding cursors and we are not in the middle
52909 ** of a transaction but there is a read lock on the database, then
52910 ** this routine unrefs the first page of the database file which 
52911 ** has the effect of releasing the read lock.
52912 **
52913 ** If there is a transaction in progress, this routine is a no-op.
52914 */
52915 static void unlockBtreeIfUnused(BtShared *pBt){
52916   assert( sqlite3_mutex_held(pBt->mutex) );
52917   assert( countValidCursors(pBt,0)==0 || pBt->inTransaction>TRANS_NONE );
52918   if( pBt->inTransaction==TRANS_NONE && pBt->pPage1!=0 ){
52919     assert( pBt->pPage1->aData );
52920     assert( sqlite3PagerRefcount(pBt->pPager)==1 );
52921     assert( pBt->pPage1->aData );
52922     releasePage(pBt->pPage1);
52923     pBt->pPage1 = 0;
52924   }
52925 }
52926 
52927 /*
52928 ** If pBt points to an empty file then convert that empty file
52929 ** into a new empty database by initializing the first page of
52930 ** the database.
52931 */
52932 static int newDatabase(BtShared *pBt){
52933   MemPage *pP1;
52934   unsigned char *data;
52935   int rc;
52936 
52937   assert( sqlite3_mutex_held(pBt->mutex) );
52938   if( pBt->nPage>0 ){
52939     return SQLITE_OK;
52940   }
52941   pP1 = pBt->pPage1;
52942   assert( pP1!=0 );
52943   data = pP1->aData;
52944   rc = sqlite3PagerWrite(pP1->pDbPage);
52945   if( rc ) return rc;
52946   memcpy(data, zMagicHeader, sizeof(zMagicHeader));
52947   assert( sizeof(zMagicHeader)==16 );
52948   data[16] = (u8)((pBt->pageSize>>8)&0xff);
52949   data[17] = (u8)((pBt->pageSize>>16)&0xff);
52950   data[18] = 1;
52951   data[19] = 1;
52952   assert( pBt->usableSize<=pBt->pageSize && pBt->usableSize+255>=pBt->pageSize);
52953   data[20] = (u8)(pBt->pageSize - pBt->usableSize);
52954   data[21] = 64;
52955   data[22] = 32;
52956   data[23] = 32;
52957   memset(&data[24], 0, 100-24);
52958   zeroPage(pP1, PTF_INTKEY|PTF_LEAF|PTF_LEAFDATA );
52959   pBt->btsFlags |= BTS_PAGESIZE_FIXED;
52960 #ifndef SQLITE_OMIT_AUTOVACUUM
52961   assert( pBt->autoVacuum==1 || pBt->autoVacuum==0 );
52962   assert( pBt->incrVacuum==1 || pBt->incrVacuum==0 );
52963   put4byte(&data[36 + 4*4], pBt->autoVacuum);
52964   put4byte(&data[36 + 7*4], pBt->incrVacuum);
52965 #endif
52966   pBt->nPage = 1;
52967   data[31] = 1;
52968   return SQLITE_OK;
52969 }
52970 
52971 /*
52972 ** Initialize the first page of the database file (creating a database
52973 ** consisting of a single page and no schema objects). Return SQLITE_OK
52974 ** if successful, or an SQLite error code otherwise.
52975 */
52976 SQLITE_PRIVATE int sqlite3BtreeNewDb(Btree *p){
52977   int rc;
52978   sqlite3BtreeEnter(p);
52979   p->pBt->nPage = 0;
52980   rc = newDatabase(p->pBt);
52981   sqlite3BtreeLeave(p);
52982   return rc;
52983 }
52984 
52985 /*
52986 ** Attempt to start a new transaction. A write-transaction
52987 ** is started if the second argument is nonzero, otherwise a read-
52988 ** transaction.  If the second argument is 2 or more and exclusive
52989 ** transaction is started, meaning that no other process is allowed
52990 ** to access the database.  A preexisting transaction may not be
52991 ** upgraded to exclusive by calling this routine a second time - the
52992 ** exclusivity flag only works for a new transaction.
52993 **
52994 ** A write-transaction must be started before attempting any 
52995 ** changes to the database.  None of the following routines 
52996 ** will work unless a transaction is started first:
52997 **
52998 **      sqlite3BtreeCreateTable()
52999 **      sqlite3BtreeCreateIndex()
53000 **      sqlite3BtreeClearTable()
53001 **      sqlite3BtreeDropTable()
53002 **      sqlite3BtreeInsert()
53003 **      sqlite3BtreeDelete()
53004 **      sqlite3BtreeUpdateMeta()
53005 **
53006 ** If an initial attempt to acquire the lock fails because of lock contention
53007 ** and the database was previously unlocked, then invoke the busy handler
53008 ** if there is one.  But if there was previously a read-lock, do not
53009 ** invoke the busy handler - just return SQLITE_BUSY.  SQLITE_BUSY is 
53010 ** returned when there is already a read-lock in order to avoid a deadlock.
53011 **
53012 ** Suppose there are two processes A and B.  A has a read lock and B has
53013 ** a reserved lock.  B tries to promote to exclusive but is blocked because
53014 ** of A's read lock.  A tries to promote to reserved but is blocked by B.
53015 ** One or the other of the two processes must give way or there can be
53016 ** no progress.  By returning SQLITE_BUSY and not invoking the busy callback
53017 ** when A already has a read lock, we encourage A to give up and let B
53018 ** proceed.
53019 */
53020 SQLITE_PRIVATE int sqlite3BtreeBeginTrans(Btree *p, int wrflag){
53021   sqlite3 *pBlock = 0;
53022   BtShared *pBt = p->pBt;
53023   int rc = SQLITE_OK;
53024 
53025   sqlite3BtreeEnter(p);
53026   btreeIntegrity(p);
53027 
53028   /* If the btree is already in a write-transaction, or it
53029   ** is already in a read-transaction and a read-transaction
53030   ** is requested, this is a no-op.
53031   */
53032   if( p->inTrans==TRANS_WRITE || (p->inTrans==TRANS_READ && !wrflag) ){
53033     goto trans_begun;
53034   }
53035   assert( pBt->inTransaction==TRANS_WRITE || IfNotOmitAV(pBt->bDoTruncate)==0 );
53036 
53037   /* Write transactions are not possible on a read-only database */
53038   if( (pBt->btsFlags & BTS_READ_ONLY)!=0 && wrflag ){
53039     rc = SQLITE_READONLY;
53040     goto trans_begun;
53041   }
53042 
53043 #ifndef SQLITE_OMIT_SHARED_CACHE
53044   /* If another database handle has already opened a write transaction 
53045   ** on this shared-btree structure and a second write transaction is
53046   ** requested, return SQLITE_LOCKED.
53047   */
53048   if( (wrflag && pBt->inTransaction==TRANS_WRITE)
53049    || (pBt->btsFlags & BTS_PENDING)!=0
53050   ){
53051     pBlock = pBt->pWriter->db;
53052   }else if( wrflag>1 ){
53053     BtLock *pIter;
53054     for(pIter=pBt->pLock; pIter; pIter=pIter->pNext){
53055       if( pIter->pBtree!=p ){
53056         pBlock = pIter->pBtree->db;
53057         break;
53058       }
53059     }
53060   }
53061   if( pBlock ){
53062     sqlite3ConnectionBlocked(p->db, pBlock);
53063     rc = SQLITE_LOCKED_SHAREDCACHE;
53064     goto trans_begun;
53065   }
53066 #endif
53067 
53068   /* Any read-only or read-write transaction implies a read-lock on 
53069   ** page 1. So if some other shared-cache client already has a write-lock 
53070   ** on page 1, the transaction cannot be opened. */
53071   rc = querySharedCacheTableLock(p, MASTER_ROOT, READ_LOCK);
53072   if( SQLITE_OK!=rc ) goto trans_begun;
53073 
53074   pBt->btsFlags &= ~BTS_INITIALLY_EMPTY;
53075   if( pBt->nPage==0 ) pBt->btsFlags |= BTS_INITIALLY_EMPTY;
53076   do {
53077     /* Call lockBtree() until either pBt->pPage1 is populated or
53078     ** lockBtree() returns something other than SQLITE_OK. lockBtree()
53079     ** may return SQLITE_OK but leave pBt->pPage1 set to 0 if after
53080     ** reading page 1 it discovers that the page-size of the database 
53081     ** file is not pBt->pageSize. In this case lockBtree() will update
53082     ** pBt->pageSize to the page-size of the file on disk.
53083     */
53084     while( pBt->pPage1==0 && SQLITE_OK==(rc = lockBtree(pBt)) );
53085 
53086     if( rc==SQLITE_OK && wrflag ){
53087       if( (pBt->btsFlags & BTS_READ_ONLY)!=0 ){
53088         rc = SQLITE_READONLY;
53089       }else{
53090         rc = sqlite3PagerBegin(pBt->pPager,wrflag>1,sqlite3TempInMemory(p->db));
53091         if( rc==SQLITE_OK ){
53092           rc = newDatabase(pBt);
53093         }
53094       }
53095     }
53096   
53097     if( rc!=SQLITE_OK ){
53098       unlockBtreeIfUnused(pBt);
53099     }
53100   }while( (rc&0xFF)==SQLITE_BUSY && pBt->inTransaction==TRANS_NONE &&
53101           btreeInvokeBusyHandler(pBt) );
53102 
53103   if( rc==SQLITE_OK ){
53104     if( p->inTrans==TRANS_NONE ){
53105       pBt->nTransaction++;
53106 #ifndef SQLITE_OMIT_SHARED_CACHE
53107       if( p->sharable ){
53108         assert( p->lock.pBtree==p && p->lock.iTable==1 );
53109         p->lock.eLock = READ_LOCK;
53110         p->lock.pNext = pBt->pLock;
53111         pBt->pLock = &p->lock;
53112       }
53113 #endif
53114     }
53115     p->inTrans = (wrflag?TRANS_WRITE:TRANS_READ);
53116     if( p->inTrans>pBt->inTransaction ){
53117       pBt->inTransaction = p->inTrans;
53118     }
53119     if( wrflag ){
53120       MemPage *pPage1 = pBt->pPage1;
53121 #ifndef SQLITE_OMIT_SHARED_CACHE
53122       assert( !pBt->pWriter );
53123       pBt->pWriter = p;
53124       pBt->btsFlags &= ~BTS_EXCLUSIVE;
53125       if( wrflag>1 ) pBt->btsFlags |= BTS_EXCLUSIVE;
53126 #endif
53127 
53128       /* If the db-size header field is incorrect (as it may be if an old
53129       ** client has been writing the database file), update it now. Doing
53130       ** this sooner rather than later means the database size can safely 
53131       ** re-read the database size from page 1 if a savepoint or transaction
53132       ** rollback occurs within the transaction.
53133       */
53134       if( pBt->nPage!=get4byte(&pPage1->aData[28]) ){
53135         rc = sqlite3PagerWrite(pPage1->pDbPage);
53136         if( rc==SQLITE_OK ){
53137           put4byte(&pPage1->aData[28], pBt->nPage);
53138         }
53139       }
53140     }
53141   }
53142 
53143 
53144 trans_begun:
53145   if( rc==SQLITE_OK && wrflag ){
53146     /* This call makes sure that the pager has the correct number of
53147     ** open savepoints. If the second parameter is greater than 0 and
53148     ** the sub-journal is not already open, then it will be opened here.
53149     */
53150     rc = sqlite3PagerOpenSavepoint(pBt->pPager, p->db->nSavepoint);
53151   }
53152 
53153   btreeIntegrity(p);
53154   sqlite3BtreeLeave(p);
53155   return rc;
53156 }
53157 
53158 #ifndef SQLITE_OMIT_AUTOVACUUM
53159 
53160 /*
53161 ** Set the pointer-map entries for all children of page pPage. Also, if
53162 ** pPage contains cells that point to overflow pages, set the pointer
53163 ** map entries for the overflow pages as well.
53164 */
53165 static int setChildPtrmaps(MemPage *pPage){
53166   int i;                             /* Counter variable */
53167   int nCell;                         /* Number of cells in page pPage */
53168   int rc;                            /* Return code */
53169   BtShared *pBt = pPage->pBt;
53170   u8 isInitOrig = pPage->isInit;
53171   Pgno pgno = pPage->pgno;
53172 
53173   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
53174   rc = btreeInitPage(pPage);
53175   if( rc!=SQLITE_OK ){
53176     goto set_child_ptrmaps_out;
53177   }
53178   nCell = pPage->nCell;
53179 
53180   for(i=0; i<nCell; i++){
53181     u8 *pCell = findCell(pPage, i);
53182 
53183     ptrmapPutOvflPtr(pPage, pCell, &rc);
53184 
53185     if( !pPage->leaf ){
53186       Pgno childPgno = get4byte(pCell);
53187       ptrmapPut(pBt, childPgno, PTRMAP_BTREE, pgno, &rc);
53188     }
53189   }
53190 
53191   if( !pPage->leaf ){
53192     Pgno childPgno = get4byte(&pPage->aData[pPage->hdrOffset+8]);
53193     ptrmapPut(pBt, childPgno, PTRMAP_BTREE, pgno, &rc);
53194   }
53195 
53196 set_child_ptrmaps_out:
53197   pPage->isInit = isInitOrig;
53198   return rc;
53199 }
53200 
53201 /*
53202 ** Somewhere on pPage is a pointer to page iFrom.  Modify this pointer so
53203 ** that it points to iTo. Parameter eType describes the type of pointer to
53204 ** be modified, as  follows:
53205 **
53206 ** PTRMAP_BTREE:     pPage is a btree-page. The pointer points at a child 
53207 **                   page of pPage.
53208 **
53209 ** PTRMAP_OVERFLOW1: pPage is a btree-page. The pointer points at an overflow
53210 **                   page pointed to by one of the cells on pPage.
53211 **
53212 ** PTRMAP_OVERFLOW2: pPage is an overflow-page. The pointer points at the next
53213 **                   overflow page in the list.
53214 */
53215 static int modifyPagePointer(MemPage *pPage, Pgno iFrom, Pgno iTo, u8 eType){
53216   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
53217   assert( sqlite3PagerIswriteable(pPage->pDbPage) );
53218   if( eType==PTRMAP_OVERFLOW2 ){
53219     /* The pointer is always the first 4 bytes of the page in this case.  */
53220     if( get4byte(pPage->aData)!=iFrom ){
53221       return SQLITE_CORRUPT_BKPT;
53222     }
53223     put4byte(pPage->aData, iTo);
53224   }else{
53225     u8 isInitOrig = pPage->isInit;
53226     int i;
53227     int nCell;
53228 
53229     btreeInitPage(pPage);
53230     nCell = pPage->nCell;
53231 
53232     for(i=0; i<nCell; i++){
53233       u8 *pCell = findCell(pPage, i);
53234       if( eType==PTRMAP_OVERFLOW1 ){
53235         CellInfo info;
53236         btreeParseCellPtr(pPage, pCell, &info);
53237         if( info.iOverflow
53238          && pCell+info.iOverflow+3<=pPage->aData+pPage->maskPage
53239          && iFrom==get4byte(&pCell[info.iOverflow])
53240         ){
53241           put4byte(&pCell[info.iOverflow], iTo);
53242           break;
53243         }
53244       }else{
53245         if( get4byte(pCell)==iFrom ){
53246           put4byte(pCell, iTo);
53247           break;
53248         }
53249       }
53250     }
53251   
53252     if( i==nCell ){
53253       if( eType!=PTRMAP_BTREE || 
53254           get4byte(&pPage->aData[pPage->hdrOffset+8])!=iFrom ){
53255         return SQLITE_CORRUPT_BKPT;
53256       }
53257       put4byte(&pPage->aData[pPage->hdrOffset+8], iTo);
53258     }
53259 
53260     pPage->isInit = isInitOrig;
53261   }
53262   return SQLITE_OK;
53263 }
53264 
53265 
53266 /*
53267 ** Move the open database page pDbPage to location iFreePage in the 
53268 ** database. The pDbPage reference remains valid.
53269 **
53270 ** The isCommit flag indicates that there is no need to remember that
53271 ** the journal needs to be sync()ed before database page pDbPage->pgno 
53272 ** can be written to. The caller has already promised not to write to that
53273 ** page.
53274 */
53275 static int relocatePage(
53276   BtShared *pBt,           /* Btree */
53277   MemPage *pDbPage,        /* Open page to move */
53278   u8 eType,                /* Pointer map 'type' entry for pDbPage */
53279   Pgno iPtrPage,           /* Pointer map 'page-no' entry for pDbPage */
53280   Pgno iFreePage,          /* The location to move pDbPage to */
53281   int isCommit             /* isCommit flag passed to sqlite3PagerMovepage */
53282 ){
53283   MemPage *pPtrPage;   /* The page that contains a pointer to pDbPage */
53284   Pgno iDbPage = pDbPage->pgno;
53285   Pager *pPager = pBt->pPager;
53286   int rc;
53287 
53288   assert( eType==PTRMAP_OVERFLOW2 || eType==PTRMAP_OVERFLOW1 || 
53289       eType==PTRMAP_BTREE || eType==PTRMAP_ROOTPAGE );
53290   assert( sqlite3_mutex_held(pBt->mutex) );
53291   assert( pDbPage->pBt==pBt );
53292 
53293   /* Move page iDbPage from its current location to page number iFreePage */
53294   TRACE(("AUTOVACUUM: Moving %d to free page %d (ptr page %d type %d)\n", 
53295       iDbPage, iFreePage, iPtrPage, eType));
53296   rc = sqlite3PagerMovepage(pPager, pDbPage->pDbPage, iFreePage, isCommit);
53297   if( rc!=SQLITE_OK ){
53298     return rc;
53299   }
53300   pDbPage->pgno = iFreePage;
53301 
53302   /* If pDbPage was a btree-page, then it may have child pages and/or cells
53303   ** that point to overflow pages. The pointer map entries for all these
53304   ** pages need to be changed.
53305   **
53306   ** If pDbPage is an overflow page, then the first 4 bytes may store a
53307   ** pointer to a subsequent overflow page. If this is the case, then
53308   ** the pointer map needs to be updated for the subsequent overflow page.
53309   */
53310   if( eType==PTRMAP_BTREE || eType==PTRMAP_ROOTPAGE ){
53311     rc = setChildPtrmaps(pDbPage);
53312     if( rc!=SQLITE_OK ){
53313       return rc;
53314     }
53315   }else{
53316     Pgno nextOvfl = get4byte(pDbPage->aData);
53317     if( nextOvfl!=0 ){
53318       ptrmapPut(pBt, nextOvfl, PTRMAP_OVERFLOW2, iFreePage, &rc);
53319       if( rc!=SQLITE_OK ){
53320         return rc;
53321       }
53322     }
53323   }
53324 
53325   /* Fix the database pointer on page iPtrPage that pointed at iDbPage so
53326   ** that it points at iFreePage. Also fix the pointer map entry for
53327   ** iPtrPage.
53328   */
53329   if( eType!=PTRMAP_ROOTPAGE ){
53330     rc = btreeGetPage(pBt, iPtrPage, &pPtrPage, 0);
53331     if( rc!=SQLITE_OK ){
53332       return rc;
53333     }
53334     rc = sqlite3PagerWrite(pPtrPage->pDbPage);
53335     if( rc!=SQLITE_OK ){
53336       releasePage(pPtrPage);
53337       return rc;
53338     }
53339     rc = modifyPagePointer(pPtrPage, iDbPage, iFreePage, eType);
53340     releasePage(pPtrPage);
53341     if( rc==SQLITE_OK ){
53342       ptrmapPut(pBt, iFreePage, eType, iPtrPage, &rc);
53343     }
53344   }
53345   return rc;
53346 }
53347 
53348 /* Forward declaration required by incrVacuumStep(). */
53349 static int allocateBtreePage(BtShared *, MemPage **, Pgno *, Pgno, u8);
53350 
53351 /*
53352 ** Perform a single step of an incremental-vacuum. If successful, return
53353 ** SQLITE_OK. If there is no work to do (and therefore no point in 
53354 ** calling this function again), return SQLITE_DONE. Or, if an error 
53355 ** occurs, return some other error code.
53356 **
53357 ** More specificly, this function attempts to re-organize the database so 
53358 ** that the last page of the file currently in use is no longer in use.
53359 **
53360 ** Parameter nFin is the number of pages that this database would contain
53361 ** were this function called until it returns SQLITE_DONE.
53362 **
53363 ** If the bCommit parameter is non-zero, this function assumes that the 
53364 ** caller will keep calling incrVacuumStep() until it returns SQLITE_DONE 
53365 ** or an error. bCommit is passed true for an auto-vacuum-on-commmit 
53366 ** operation, or false for an incremental vacuum.
53367 */
53368 static int incrVacuumStep(BtShared *pBt, Pgno nFin, Pgno iLastPg, int bCommit){
53369   Pgno nFreeList;           /* Number of pages still on the free-list */
53370   int rc;
53371 
53372   assert( sqlite3_mutex_held(pBt->mutex) );
53373   assert( iLastPg>nFin );
53374 
53375   if( !PTRMAP_ISPAGE(pBt, iLastPg) && iLastPg!=PENDING_BYTE_PAGE(pBt) ){
53376     u8 eType;
53377     Pgno iPtrPage;
53378 
53379     nFreeList = get4byte(&pBt->pPage1->aData[36]);
53380     if( nFreeList==0 ){
53381       return SQLITE_DONE;
53382     }
53383 
53384     rc = ptrmapGet(pBt, iLastPg, &eType, &iPtrPage);
53385     if( rc!=SQLITE_OK ){
53386       return rc;
53387     }
53388     if( eType==PTRMAP_ROOTPAGE ){
53389       return SQLITE_CORRUPT_BKPT;
53390     }
53391 
53392     if( eType==PTRMAP_FREEPAGE ){
53393       if( bCommit==0 ){
53394         /* Remove the page from the files free-list. This is not required
53395         ** if bCommit is non-zero. In that case, the free-list will be
53396         ** truncated to zero after this function returns, so it doesn't 
53397         ** matter if it still contains some garbage entries.
53398         */
53399         Pgno iFreePg;
53400         MemPage *pFreePg;
53401         rc = allocateBtreePage(pBt, &pFreePg, &iFreePg, iLastPg, BTALLOC_EXACT);
53402         if( rc!=SQLITE_OK ){
53403           return rc;
53404         }
53405         assert( iFreePg==iLastPg );
53406         releasePage(pFreePg);
53407       }
53408     } else {
53409       Pgno iFreePg;             /* Index of free page to move pLastPg to */
53410       MemPage *pLastPg;
53411       u8 eMode = BTALLOC_ANY;   /* Mode parameter for allocateBtreePage() */
53412       Pgno iNear = 0;           /* nearby parameter for allocateBtreePage() */
53413 
53414       rc = btreeGetPage(pBt, iLastPg, &pLastPg, 0);
53415       if( rc!=SQLITE_OK ){
53416         return rc;
53417       }
53418 
53419       /* If bCommit is zero, this loop runs exactly once and page pLastPg
53420       ** is swapped with the first free page pulled off the free list.
53421       **
53422       ** On the other hand, if bCommit is greater than zero, then keep
53423       ** looping until a free-page located within the first nFin pages
53424       ** of the file is found.
53425       */
53426       if( bCommit==0 ){
53427         eMode = BTALLOC_LE;
53428         iNear = nFin;
53429       }
53430       do {
53431         MemPage *pFreePg;
53432         rc = allocateBtreePage(pBt, &pFreePg, &iFreePg, iNear, eMode);
53433         if( rc!=SQLITE_OK ){
53434           releasePage(pLastPg);
53435           return rc;
53436         }
53437         releasePage(pFreePg);
53438       }while( bCommit && iFreePg>nFin );
53439       assert( iFreePg<iLastPg );
53440       
53441       rc = relocatePage(pBt, pLastPg, eType, iPtrPage, iFreePg, bCommit);
53442       releasePage(pLastPg);
53443       if( rc!=SQLITE_OK ){
53444         return rc;
53445       }
53446     }
53447   }
53448 
53449   if( bCommit==0 ){
53450     do {
53451       iLastPg--;
53452     }while( iLastPg==PENDING_BYTE_PAGE(pBt) || PTRMAP_ISPAGE(pBt, iLastPg) );
53453     pBt->bDoTruncate = 1;
53454     pBt->nPage = iLastPg;
53455   }
53456   return SQLITE_OK;
53457 }
53458 
53459 /*
53460 ** The database opened by the first argument is an auto-vacuum database
53461 ** nOrig pages in size containing nFree free pages. Return the expected 
53462 ** size of the database in pages following an auto-vacuum operation.
53463 */
53464 static Pgno finalDbSize(BtShared *pBt, Pgno nOrig, Pgno nFree){
53465   int nEntry;                     /* Number of entries on one ptrmap page */
53466   Pgno nPtrmap;                   /* Number of PtrMap pages to be freed */
53467   Pgno nFin;                      /* Return value */
53468 
53469   nEntry = pBt->usableSize/5;
53470   nPtrmap = (nFree-nOrig+PTRMAP_PAGENO(pBt, nOrig)+nEntry)/nEntry;
53471   nFin = nOrig - nFree - nPtrmap;
53472   if( nOrig>PENDING_BYTE_PAGE(pBt) && nFin<PENDING_BYTE_PAGE(pBt) ){
53473     nFin--;
53474   }
53475   while( PTRMAP_ISPAGE(pBt, nFin) || nFin==PENDING_BYTE_PAGE(pBt) ){
53476     nFin--;
53477   }
53478 
53479   return nFin;
53480 }
53481 
53482 /*
53483 ** A write-transaction must be opened before calling this function.
53484 ** It performs a single unit of work towards an incremental vacuum.
53485 **
53486 ** If the incremental vacuum is finished after this function has run,
53487 ** SQLITE_DONE is returned. If it is not finished, but no error occurred,
53488 ** SQLITE_OK is returned. Otherwise an SQLite error code. 
53489 */
53490 SQLITE_PRIVATE int sqlite3BtreeIncrVacuum(Btree *p){
53491   int rc;
53492   BtShared *pBt = p->pBt;
53493 
53494   sqlite3BtreeEnter(p);
53495   assert( pBt->inTransaction==TRANS_WRITE && p->inTrans==TRANS_WRITE );
53496   if( !pBt->autoVacuum ){
53497     rc = SQLITE_DONE;
53498   }else{
53499     Pgno nOrig = btreePagecount(pBt);
53500     Pgno nFree = get4byte(&pBt->pPage1->aData[36]);
53501     Pgno nFin = finalDbSize(pBt, nOrig, nFree);
53502 
53503     if( nOrig<nFin ){
53504       rc = SQLITE_CORRUPT_BKPT;
53505     }else if( nFree>0 ){
53506       rc = saveAllCursors(pBt, 0, 0);
53507       if( rc==SQLITE_OK ){
53508         invalidateAllOverflowCache(pBt);
53509         rc = incrVacuumStep(pBt, nFin, nOrig, 0);
53510       }
53511       if( rc==SQLITE_OK ){
53512         rc = sqlite3PagerWrite(pBt->pPage1->pDbPage);
53513         put4byte(&pBt->pPage1->aData[28], pBt->nPage);
53514       }
53515     }else{
53516       rc = SQLITE_DONE;
53517     }
53518   }
53519   sqlite3BtreeLeave(p);
53520   return rc;
53521 }
53522 
53523 /*
53524 ** This routine is called prior to sqlite3PagerCommit when a transaction
53525 ** is committed for an auto-vacuum database.
53526 **
53527 ** If SQLITE_OK is returned, then *pnTrunc is set to the number of pages
53528 ** the database file should be truncated to during the commit process. 
53529 ** i.e. the database has been reorganized so that only the first *pnTrunc
53530 ** pages are in use.
53531 */
53532 static int autoVacuumCommit(BtShared *pBt){
53533   int rc = SQLITE_OK;
53534   Pager *pPager = pBt->pPager;
53535   VVA_ONLY( int nRef = sqlite3PagerRefcount(pPager) );
53536 
53537   assert( sqlite3_mutex_held(pBt->mutex) );
53538   invalidateAllOverflowCache(pBt);
53539   assert(pBt->autoVacuum);
53540   if( !pBt->incrVacuum ){
53541     Pgno nFin;         /* Number of pages in database after autovacuuming */
53542     Pgno nFree;        /* Number of pages on the freelist initially */
53543     Pgno iFree;        /* The next page to be freed */
53544     Pgno nOrig;        /* Database size before freeing */
53545 
53546     nOrig = btreePagecount(pBt);
53547     if( PTRMAP_ISPAGE(pBt, nOrig) || nOrig==PENDING_BYTE_PAGE(pBt) ){
53548       /* It is not possible to create a database for which the final page
53549       ** is either a pointer-map page or the pending-byte page. If one
53550       ** is encountered, this indicates corruption.
53551       */
53552       return SQLITE_CORRUPT_BKPT;
53553     }
53554 
53555     nFree = get4byte(&pBt->pPage1->aData[36]);
53556     nFin = finalDbSize(pBt, nOrig, nFree);
53557     if( nFin>nOrig ) return SQLITE_CORRUPT_BKPT;
53558     if( nFin<nOrig ){
53559       rc = saveAllCursors(pBt, 0, 0);
53560     }
53561     for(iFree=nOrig; iFree>nFin && rc==SQLITE_OK; iFree--){
53562       rc = incrVacuumStep(pBt, nFin, iFree, 1);
53563     }
53564     if( (rc==SQLITE_DONE || rc==SQLITE_OK) && nFree>0 ){
53565       rc = sqlite3PagerWrite(pBt->pPage1->pDbPage);
53566       put4byte(&pBt->pPage1->aData[32], 0);
53567       put4byte(&pBt->pPage1->aData[36], 0);
53568       put4byte(&pBt->pPage1->aData[28], nFin);
53569       pBt->bDoTruncate = 1;
53570       pBt->nPage = nFin;
53571     }
53572     if( rc!=SQLITE_OK ){
53573       sqlite3PagerRollback(pPager);
53574     }
53575   }
53576 
53577   assert( nRef>=sqlite3PagerRefcount(pPager) );
53578   return rc;
53579 }
53580 
53581 #else /* ifndef SQLITE_OMIT_AUTOVACUUM */
53582 # define setChildPtrmaps(x) SQLITE_OK
53583 #endif
53584 
53585 /*
53586 ** This routine does the first phase of a two-phase commit.  This routine
53587 ** causes a rollback journal to be created (if it does not already exist)
53588 ** and populated with enough information so that if a power loss occurs
53589 ** the database can be restored to its original state by playing back
53590 ** the journal.  Then the contents of the journal are flushed out to
53591 ** the disk.  After the journal is safely on oxide, the changes to the
53592 ** database are written into the database file and flushed to oxide.
53593 ** At the end of this call, the rollback journal still exists on the
53594 ** disk and we are still holding all locks, so the transaction has not
53595 ** committed.  See sqlite3BtreeCommitPhaseTwo() for the second phase of the
53596 ** commit process.
53597 **
53598 ** This call is a no-op if no write-transaction is currently active on pBt.
53599 **
53600 ** Otherwise, sync the database file for the btree pBt. zMaster points to
53601 ** the name of a master journal file that should be written into the
53602 ** individual journal file, or is NULL, indicating no master journal file 
53603 ** (single database transaction).
53604 **
53605 ** When this is called, the master journal should already have been
53606 ** created, populated with this journal pointer and synced to disk.
53607 **
53608 ** Once this is routine has returned, the only thing required to commit
53609 ** the write-transaction for this database file is to delete the journal.
53610 */
53611 SQLITE_PRIVATE int sqlite3BtreeCommitPhaseOne(Btree *p, const char *zMaster){
53612   int rc = SQLITE_OK;
53613   if( p->inTrans==TRANS_WRITE ){
53614     BtShared *pBt = p->pBt;
53615     sqlite3BtreeEnter(p);
53616 #ifndef SQLITE_OMIT_AUTOVACUUM
53617     if( pBt->autoVacuum ){
53618       rc = autoVacuumCommit(pBt);
53619       if( rc!=SQLITE_OK ){
53620         sqlite3BtreeLeave(p);
53621         return rc;
53622       }
53623     }
53624     if( pBt->bDoTruncate ){
53625       sqlite3PagerTruncateImage(pBt->pPager, pBt->nPage);
53626     }
53627 #endif
53628     rc = sqlite3PagerCommitPhaseOne(pBt->pPager, zMaster, 0);
53629     sqlite3BtreeLeave(p);
53630   }
53631   return rc;
53632 }
53633 
53634 /*
53635 ** This function is called from both BtreeCommitPhaseTwo() and BtreeRollback()
53636 ** at the conclusion of a transaction.
53637 */
53638 static void btreeEndTransaction(Btree *p){
53639   BtShared *pBt = p->pBt;
53640   sqlite3 *db = p->db;
53641   assert( sqlite3BtreeHoldsMutex(p) );
53642 
53643 #ifndef SQLITE_OMIT_AUTOVACUUM
53644   pBt->bDoTruncate = 0;
53645 #endif
53646   if( p->inTrans>TRANS_NONE && db->nVdbeRead>1 ){
53647     /* If there are other active statements that belong to this database
53648     ** handle, downgrade to a read-only transaction. The other statements
53649     ** may still be reading from the database.  */
53650     downgradeAllSharedCacheTableLocks(p);
53651     p->inTrans = TRANS_READ;
53652   }else{
53653     /* If the handle had any kind of transaction open, decrement the 
53654     ** transaction count of the shared btree. If the transaction count 
53655     ** reaches 0, set the shared state to TRANS_NONE. The unlockBtreeIfUnused()
53656     ** call below will unlock the pager.  */
53657     if( p->inTrans!=TRANS_NONE ){
53658       clearAllSharedCacheTableLocks(p);
53659       pBt->nTransaction--;
53660       if( 0==pBt->nTransaction ){
53661         pBt->inTransaction = TRANS_NONE;
53662       }
53663     }
53664 
53665     /* Set the current transaction state to TRANS_NONE and unlock the 
53666     ** pager if this call closed the only read or write transaction.  */
53667     p->inTrans = TRANS_NONE;
53668     unlockBtreeIfUnused(pBt);
53669   }
53670 
53671   btreeIntegrity(p);
53672 }
53673 
53674 /*
53675 ** Commit the transaction currently in progress.
53676 **
53677 ** This routine implements the second phase of a 2-phase commit.  The
53678 ** sqlite3BtreeCommitPhaseOne() routine does the first phase and should
53679 ** be invoked prior to calling this routine.  The sqlite3BtreeCommitPhaseOne()
53680 ** routine did all the work of writing information out to disk and flushing the
53681 ** contents so that they are written onto the disk platter.  All this
53682 ** routine has to do is delete or truncate or zero the header in the
53683 ** the rollback journal (which causes the transaction to commit) and
53684 ** drop locks.
53685 **
53686 ** Normally, if an error occurs while the pager layer is attempting to 
53687 ** finalize the underlying journal file, this function returns an error and
53688 ** the upper layer will attempt a rollback. However, if the second argument
53689 ** is non-zero then this b-tree transaction is part of a multi-file 
53690 ** transaction. In this case, the transaction has already been committed 
53691 ** (by deleting a master journal file) and the caller will ignore this 
53692 ** functions return code. So, even if an error occurs in the pager layer,
53693 ** reset the b-tree objects internal state to indicate that the write
53694 ** transaction has been closed. This is quite safe, as the pager will have
53695 ** transitioned to the error state.
53696 **
53697 ** This will release the write lock on the database file.  If there
53698 ** are no active cursors, it also releases the read lock.
53699 */
53700 SQLITE_PRIVATE int sqlite3BtreeCommitPhaseTwo(Btree *p, int bCleanup){
53701 
53702   if( p->inTrans==TRANS_NONE ) return SQLITE_OK;
53703   sqlite3BtreeEnter(p);
53704   btreeIntegrity(p);
53705 
53706   /* If the handle has a write-transaction open, commit the shared-btrees 
53707   ** transaction and set the shared state to TRANS_READ.
53708   */
53709   if( p->inTrans==TRANS_WRITE ){
53710     int rc;
53711     BtShared *pBt = p->pBt;
53712     assert( pBt->inTransaction==TRANS_WRITE );
53713     assert( pBt->nTransaction>0 );
53714     rc = sqlite3PagerCommitPhaseTwo(pBt->pPager);
53715     if( rc!=SQLITE_OK && bCleanup==0 ){
53716       sqlite3BtreeLeave(p);
53717       return rc;
53718     }
53719     pBt->inTransaction = TRANS_READ;
53720     btreeClearHasContent(pBt);
53721   }
53722 
53723   btreeEndTransaction(p);
53724   sqlite3BtreeLeave(p);
53725   return SQLITE_OK;
53726 }
53727 
53728 /*
53729 ** Do both phases of a commit.
53730 */
53731 SQLITE_PRIVATE int sqlite3BtreeCommit(Btree *p){
53732   int rc;
53733   sqlite3BtreeEnter(p);
53734   rc = sqlite3BtreeCommitPhaseOne(p, 0);
53735   if( rc==SQLITE_OK ){
53736     rc = sqlite3BtreeCommitPhaseTwo(p, 0);
53737   }
53738   sqlite3BtreeLeave(p);
53739   return rc;
53740 }
53741 
53742 /*
53743 ** This routine sets the state to CURSOR_FAULT and the error
53744 ** code to errCode for every cursor on BtShared that pBtree
53745 ** references.
53746 **
53747 ** Every cursor is tripped, including cursors that belong
53748 ** to other database connections that happen to be sharing
53749 ** the cache with pBtree.
53750 **
53751 ** This routine gets called when a rollback occurs.
53752 ** All cursors using the same cache must be tripped
53753 ** to prevent them from trying to use the btree after
53754 ** the rollback.  The rollback may have deleted tables
53755 ** or moved root pages, so it is not sufficient to
53756 ** save the state of the cursor.  The cursor must be
53757 ** invalidated.
53758 */
53759 SQLITE_PRIVATE void sqlite3BtreeTripAllCursors(Btree *pBtree, int errCode){
53760   BtCursor *p;
53761   if( pBtree==0 ) return;
53762   sqlite3BtreeEnter(pBtree);
53763   for(p=pBtree->pBt->pCursor; p; p=p->pNext){
53764     int i;
53765     sqlite3BtreeClearCursor(p);
53766     p->eState = CURSOR_FAULT;
53767     p->skipNext = errCode;
53768     for(i=0; i<=p->iPage; i++){
53769       releasePage(p->apPage[i]);
53770       p->apPage[i] = 0;
53771     }
53772   }
53773   sqlite3BtreeLeave(pBtree);
53774 }
53775 
53776 /*
53777 ** Rollback the transaction in progress.  All cursors will be
53778 ** invalided by this operation.  Any attempt to use a cursor
53779 ** that was open at the beginning of this operation will result
53780 ** in an error.
53781 **
53782 ** This will release the write lock on the database file.  If there
53783 ** are no active cursors, it also releases the read lock.
53784 */
53785 SQLITE_PRIVATE int sqlite3BtreeRollback(Btree *p, int tripCode){
53786   int rc;
53787   BtShared *pBt = p->pBt;
53788   MemPage *pPage1;
53789 
53790   sqlite3BtreeEnter(p);
53791   if( tripCode==SQLITE_OK ){
53792     rc = tripCode = saveAllCursors(pBt, 0, 0);
53793   }else{
53794     rc = SQLITE_OK;
53795   }
53796   if( tripCode ){
53797     sqlite3BtreeTripAllCursors(p, tripCode);
53798   }
53799   btreeIntegrity(p);
53800 
53801   if( p->inTrans==TRANS_WRITE ){
53802     int rc2;
53803 
53804     assert( TRANS_WRITE==pBt->inTransaction );
53805     rc2 = sqlite3PagerRollback(pBt->pPager);
53806     if( rc2!=SQLITE_OK ){
53807       rc = rc2;
53808     }
53809 
53810     /* The rollback may have destroyed the pPage1->aData value.  So
53811     ** call btreeGetPage() on page 1 again to make
53812     ** sure pPage1->aData is set correctly. */
53813     if( btreeGetPage(pBt, 1, &pPage1, 0)==SQLITE_OK ){
53814       int nPage = get4byte(28+(u8*)pPage1->aData);
53815       testcase( nPage==0 );
53816       if( nPage==0 ) sqlite3PagerPagecount(pBt->pPager, &nPage);
53817       testcase( pBt->nPage!=nPage );
53818       pBt->nPage = nPage;
53819       releasePage(pPage1);
53820     }
53821     assert( countValidCursors(pBt, 1)==0 );
53822     pBt->inTransaction = TRANS_READ;
53823     btreeClearHasContent(pBt);
53824   }
53825 
53826   btreeEndTransaction(p);
53827   sqlite3BtreeLeave(p);
53828   return rc;
53829 }
53830 
53831 /*
53832 ** Start a statement subtransaction. The subtransaction can can be rolled
53833 ** back independently of the main transaction. You must start a transaction 
53834 ** before starting a subtransaction. The subtransaction is ended automatically 
53835 ** if the main transaction commits or rolls back.
53836 **
53837 ** Statement subtransactions are used around individual SQL statements
53838 ** that are contained within a BEGIN...COMMIT block.  If a constraint
53839 ** error occurs within the statement, the effect of that one statement
53840 ** can be rolled back without having to rollback the entire transaction.
53841 **
53842 ** A statement sub-transaction is implemented as an anonymous savepoint. The
53843 ** value passed as the second parameter is the total number of savepoints,
53844 ** including the new anonymous savepoint, open on the B-Tree. i.e. if there
53845 ** are no active savepoints and no other statement-transactions open,
53846 ** iStatement is 1. This anonymous savepoint can be released or rolled back
53847 ** using the sqlite3BtreeSavepoint() function.
53848 */
53849 SQLITE_PRIVATE int sqlite3BtreeBeginStmt(Btree *p, int iStatement){
53850   int rc;
53851   BtShared *pBt = p->pBt;
53852   sqlite3BtreeEnter(p);
53853   assert( p->inTrans==TRANS_WRITE );
53854   assert( (pBt->btsFlags & BTS_READ_ONLY)==0 );
53855   assert( iStatement>0 );
53856   assert( iStatement>p->db->nSavepoint );
53857   assert( pBt->inTransaction==TRANS_WRITE );
53858   /* At the pager level, a statement transaction is a savepoint with
53859   ** an index greater than all savepoints created explicitly using
53860   ** SQL statements. It is illegal to open, release or rollback any
53861   ** such savepoints while the statement transaction savepoint is active.
53862   */
53863   rc = sqlite3PagerOpenSavepoint(pBt->pPager, iStatement);
53864   sqlite3BtreeLeave(p);
53865   return rc;
53866 }
53867 
53868 /*
53869 ** The second argument to this function, op, is always SAVEPOINT_ROLLBACK
53870 ** or SAVEPOINT_RELEASE. This function either releases or rolls back the
53871 ** savepoint identified by parameter iSavepoint, depending on the value 
53872 ** of op.
53873 **
53874 ** Normally, iSavepoint is greater than or equal to zero. However, if op is
53875 ** SAVEPOINT_ROLLBACK, then iSavepoint may also be -1. In this case the 
53876 ** contents of the entire transaction are rolled back. This is different
53877 ** from a normal transaction rollback, as no locks are released and the
53878 ** transaction remains open.
53879 */
53880 SQLITE_PRIVATE int sqlite3BtreeSavepoint(Btree *p, int op, int iSavepoint){
53881   int rc = SQLITE_OK;
53882   if( p && p->inTrans==TRANS_WRITE ){
53883     BtShared *pBt = p->pBt;
53884     assert( op==SAVEPOINT_RELEASE || op==SAVEPOINT_ROLLBACK );
53885     assert( iSavepoint>=0 || (iSavepoint==-1 && op==SAVEPOINT_ROLLBACK) );
53886     sqlite3BtreeEnter(p);
53887     rc = sqlite3PagerSavepoint(pBt->pPager, op, iSavepoint);
53888     if( rc==SQLITE_OK ){
53889       if( iSavepoint<0 && (pBt->btsFlags & BTS_INITIALLY_EMPTY)!=0 ){
53890         pBt->nPage = 0;
53891       }
53892       rc = newDatabase(pBt);
53893       pBt->nPage = get4byte(28 + pBt->pPage1->aData);
53894 
53895       /* The database size was written into the offset 28 of the header
53896       ** when the transaction started, so we know that the value at offset
53897       ** 28 is nonzero. */
53898       assert( pBt->nPage>0 );
53899     }
53900     sqlite3BtreeLeave(p);
53901   }
53902   return rc;
53903 }
53904 
53905 /*
53906 ** Create a new cursor for the BTree whose root is on the page
53907 ** iTable. If a read-only cursor is requested, it is assumed that
53908 ** the caller already has at least a read-only transaction open
53909 ** on the database already. If a write-cursor is requested, then
53910 ** the caller is assumed to have an open write transaction.
53911 **
53912 ** If wrFlag==0, then the cursor can only be used for reading.
53913 ** If wrFlag==1, then the cursor can be used for reading or for
53914 ** writing if other conditions for writing are also met.  These
53915 ** are the conditions that must be met in order for writing to
53916 ** be allowed:
53917 **
53918 ** 1:  The cursor must have been opened with wrFlag==1
53919 **
53920 ** 2:  Other database connections that share the same pager cache
53921 **     but which are not in the READ_UNCOMMITTED state may not have
53922 **     cursors open with wrFlag==0 on the same table.  Otherwise
53923 **     the changes made by this write cursor would be visible to
53924 **     the read cursors in the other database connection.
53925 **
53926 ** 3:  The database must be writable (not on read-only media)
53927 **
53928 ** 4:  There must be an active transaction.
53929 **
53930 ** No checking is done to make sure that page iTable really is the
53931 ** root page of a b-tree.  If it is not, then the cursor acquired
53932 ** will not work correctly.
53933 **
53934 ** It is assumed that the sqlite3BtreeCursorZero() has been called
53935 ** on pCur to initialize the memory space prior to invoking this routine.
53936 */
53937 static int btreeCursor(
53938   Btree *p,                              /* The btree */
53939   int iTable,                            /* Root page of table to open */
53940   int wrFlag,                            /* 1 to write. 0 read-only */
53941   struct KeyInfo *pKeyInfo,              /* First arg to comparison function */
53942   BtCursor *pCur                         /* Space for new cursor */
53943 ){
53944   BtShared *pBt = p->pBt;                /* Shared b-tree handle */
53945 
53946   assert( sqlite3BtreeHoldsMutex(p) );
53947   assert( wrFlag==0 || wrFlag==1 );
53948 
53949   /* The following assert statements verify that if this is a sharable 
53950   ** b-tree database, the connection is holding the required table locks, 
53951   ** and that no other connection has any open cursor that conflicts with 
53952   ** this lock.  */
53953   assert( hasSharedCacheTableLock(p, iTable, pKeyInfo!=0, wrFlag+1) );
53954   assert( wrFlag==0 || !hasReadConflicts(p, iTable) );
53955 
53956   /* Assert that the caller has opened the required transaction. */
53957   assert( p->inTrans>TRANS_NONE );
53958   assert( wrFlag==0 || p->inTrans==TRANS_WRITE );
53959   assert( pBt->pPage1 && pBt->pPage1->aData );
53960 
53961   if( NEVER(wrFlag && (pBt->btsFlags & BTS_READ_ONLY)!=0) ){
53962     return SQLITE_READONLY;
53963   }
53964   if( iTable==1 && btreePagecount(pBt)==0 ){
53965     assert( wrFlag==0 );
53966     iTable = 0;
53967   }
53968 
53969   /* Now that no other errors can occur, finish filling in the BtCursor
53970   ** variables and link the cursor into the BtShared list.  */
53971   pCur->pgnoRoot = (Pgno)iTable;
53972   pCur->iPage = -1;
53973   pCur->pKeyInfo = pKeyInfo;
53974   pCur->pBtree = p;
53975   pCur->pBt = pBt;
53976   pCur->wrFlag = (u8)wrFlag;
53977   pCur->pNext = pBt->pCursor;
53978   if( pCur->pNext ){
53979     pCur->pNext->pPrev = pCur;
53980   }
53981   pBt->pCursor = pCur;
53982   pCur->eState = CURSOR_INVALID;
53983   pCur->cachedRowid = 0;
53984   return SQLITE_OK;
53985 }
53986 SQLITE_PRIVATE int sqlite3BtreeCursor(
53987   Btree *p,                                   /* The btree */
53988   int iTable,                                 /* Root page of table to open */
53989   int wrFlag,                                 /* 1 to write. 0 read-only */
53990   struct KeyInfo *pKeyInfo,                   /* First arg to xCompare() */
53991   BtCursor *pCur                              /* Write new cursor here */
53992 ){
53993   int rc;
53994   sqlite3BtreeEnter(p);
53995   rc = btreeCursor(p, iTable, wrFlag, pKeyInfo, pCur);
53996   sqlite3BtreeLeave(p);
53997   return rc;
53998 }
53999 
54000 /*
54001 ** Return the size of a BtCursor object in bytes.
54002 **
54003 ** This interfaces is needed so that users of cursors can preallocate
54004 ** sufficient storage to hold a cursor.  The BtCursor object is opaque
54005 ** to users so they cannot do the sizeof() themselves - they must call
54006 ** this routine.
54007 */
54008 SQLITE_PRIVATE int sqlite3BtreeCursorSize(void){
54009   return ROUND8(sizeof(BtCursor));
54010 }
54011 
54012 /*
54013 ** Initialize memory that will be converted into a BtCursor object.
54014 **
54015 ** The simple approach here would be to memset() the entire object
54016 ** to zero.  But it turns out that the apPage[] and aiIdx[] arrays
54017 ** do not need to be zeroed and they are large, so we can save a lot
54018 ** of run-time by skipping the initialization of those elements.
54019 */
54020 SQLITE_PRIVATE void sqlite3BtreeCursorZero(BtCursor *p){
54021   memset(p, 0, offsetof(BtCursor, iPage));
54022 }
54023 
54024 /*
54025 ** Set the cached rowid value of every cursor in the same database file
54026 ** as pCur and having the same root page number as pCur.  The value is
54027 ** set to iRowid.
54028 **
54029 ** Only positive rowid values are considered valid for this cache.
54030 ** The cache is initialized to zero, indicating an invalid cache.
54031 ** A btree will work fine with zero or negative rowids.  We just cannot
54032 ** cache zero or negative rowids, which means tables that use zero or
54033 ** negative rowids might run a little slower.  But in practice, zero
54034 ** or negative rowids are very uncommon so this should not be a problem.
54035 */
54036 SQLITE_PRIVATE void sqlite3BtreeSetCachedRowid(BtCursor *pCur, sqlite3_int64 iRowid){
54037   BtCursor *p;
54038   for(p=pCur->pBt->pCursor; p; p=p->pNext){
54039     if( p->pgnoRoot==pCur->pgnoRoot ) p->cachedRowid = iRowid;
54040   }
54041   assert( pCur->cachedRowid==iRowid );
54042 }
54043 
54044 /*
54045 ** Return the cached rowid for the given cursor.  A negative or zero
54046 ** return value indicates that the rowid cache is invalid and should be
54047 ** ignored.  If the rowid cache has never before been set, then a
54048 ** zero is returned.
54049 */
54050 SQLITE_PRIVATE sqlite3_int64 sqlite3BtreeGetCachedRowid(BtCursor *pCur){
54051   return pCur->cachedRowid;
54052 }
54053 
54054 /*
54055 ** Close a cursor.  The read lock on the database file is released
54056 ** when the last cursor is closed.
54057 */
54058 SQLITE_PRIVATE int sqlite3BtreeCloseCursor(BtCursor *pCur){
54059   Btree *pBtree = pCur->pBtree;
54060   if( pBtree ){
54061     int i;
54062     BtShared *pBt = pCur->pBt;
54063     sqlite3BtreeEnter(pBtree);
54064     sqlite3BtreeClearCursor(pCur);
54065     if( pCur->pPrev ){
54066       pCur->pPrev->pNext = pCur->pNext;
54067     }else{
54068       pBt->pCursor = pCur->pNext;
54069     }
54070     if( pCur->pNext ){
54071       pCur->pNext->pPrev = pCur->pPrev;
54072     }
54073     for(i=0; i<=pCur->iPage; i++){
54074       releasePage(pCur->apPage[i]);
54075     }
54076     unlockBtreeIfUnused(pBt);
54077     invalidateOverflowCache(pCur);
54078     /* sqlite3_free(pCur); */
54079     sqlite3BtreeLeave(pBtree);
54080   }
54081   return SQLITE_OK;
54082 }
54083 
54084 /*
54085 ** Make sure the BtCursor* given in the argument has a valid
54086 ** BtCursor.info structure.  If it is not already valid, call
54087 ** btreeParseCell() to fill it in.
54088 **
54089 ** BtCursor.info is a cache of the information in the current cell.
54090 ** Using this cache reduces the number of calls to btreeParseCell().
54091 **
54092 ** 2007-06-25:  There is a bug in some versions of MSVC that cause the
54093 ** compiler to crash when getCellInfo() is implemented as a macro.
54094 ** But there is a measureable speed advantage to using the macro on gcc
54095 ** (when less compiler optimizations like -Os or -O0 are used and the
54096 ** compiler is not doing agressive inlining.)  So we use a real function
54097 ** for MSVC and a macro for everything else.  Ticket #2457.
54098 */
54099 #ifndef NDEBUG
54100   static void assertCellInfo(BtCursor *pCur){
54101     CellInfo info;
54102     int iPage = pCur->iPage;
54103     memset(&info, 0, sizeof(info));
54104     btreeParseCell(pCur->apPage[iPage], pCur->aiIdx[iPage], &info);
54105     assert( memcmp(&info, &pCur->info, sizeof(info))==0 );
54106   }
54107 #else
54108   #define assertCellInfo(x)
54109 #endif
54110 #ifdef _MSC_VER
54111   /* Use a real function in MSVC to work around bugs in that compiler. */
54112   static void getCellInfo(BtCursor *pCur){
54113     if( pCur->info.nSize==0 ){
54114       int iPage = pCur->iPage;
54115       btreeParseCell(pCur->apPage[iPage],pCur->aiIdx[iPage],&pCur->info);
54116       pCur->validNKey = 1;
54117     }else{
54118       assertCellInfo(pCur);
54119     }
54120   }
54121 #else /* if not _MSC_VER */
54122   /* Use a macro in all other compilers so that the function is inlined */
54123 #define getCellInfo(pCur)                                                      \
54124   if( pCur->info.nSize==0 ){                                                   \
54125     int iPage = pCur->iPage;                                                   \
54126     btreeParseCell(pCur->apPage[iPage],pCur->aiIdx[iPage],&pCur->info); \
54127     pCur->validNKey = 1;                                                       \
54128   }else{                                                                       \
54129     assertCellInfo(pCur);                                                      \
54130   }
54131 #endif /* _MSC_VER */
54132 
54133 #ifndef NDEBUG  /* The next routine used only within assert() statements */
54134 /*
54135 ** Return true if the given BtCursor is valid.  A valid cursor is one
54136 ** that is currently pointing to a row in a (non-empty) table.
54137 ** This is a verification routine is used only within assert() statements.
54138 */
54139 SQLITE_PRIVATE int sqlite3BtreeCursorIsValid(BtCursor *pCur){
54140   return pCur && pCur->eState==CURSOR_VALID;
54141 }
54142 #endif /* NDEBUG */
54143 
54144 /*
54145 ** Set *pSize to the size of the buffer needed to hold the value of
54146 ** the key for the current entry.  If the cursor is not pointing
54147 ** to a valid entry, *pSize is set to 0. 
54148 **
54149 ** For a table with the INTKEY flag set, this routine returns the key
54150 ** itself, not the number of bytes in the key.
54151 **
54152 ** The caller must position the cursor prior to invoking this routine.
54153 ** 
54154 ** This routine cannot fail.  It always returns SQLITE_OK.  
54155 */
54156 SQLITE_PRIVATE int sqlite3BtreeKeySize(BtCursor *pCur, i64 *pSize){
54157   assert( cursorHoldsMutex(pCur) );
54158   assert( pCur->eState==CURSOR_INVALID || pCur->eState==CURSOR_VALID );
54159   if( pCur->eState!=CURSOR_VALID ){
54160     *pSize = 0;
54161   }else{
54162     getCellInfo(pCur);
54163     *pSize = pCur->info.nKey;
54164   }
54165   return SQLITE_OK;
54166 }
54167 
54168 /*
54169 ** Set *pSize to the number of bytes of data in the entry the
54170 ** cursor currently points to.
54171 **
54172 ** The caller must guarantee that the cursor is pointing to a non-NULL
54173 ** valid entry.  In other words, the calling procedure must guarantee
54174 ** that the cursor has Cursor.eState==CURSOR_VALID.
54175 **
54176 ** Failure is not possible.  This function always returns SQLITE_OK.
54177 ** It might just as well be a procedure (returning void) but we continue
54178 ** to return an integer result code for historical reasons.
54179 */
54180 SQLITE_PRIVATE int sqlite3BtreeDataSize(BtCursor *pCur, u32 *pSize){
54181   assert( cursorHoldsMutex(pCur) );
54182   assert( pCur->eState==CURSOR_VALID );
54183   getCellInfo(pCur);
54184   *pSize = pCur->info.nData;
54185   return SQLITE_OK;
54186 }
54187 
54188 /*
54189 ** Given the page number of an overflow page in the database (parameter
54190 ** ovfl), this function finds the page number of the next page in the 
54191 ** linked list of overflow pages. If possible, it uses the auto-vacuum
54192 ** pointer-map data instead of reading the content of page ovfl to do so. 
54193 **
54194 ** If an error occurs an SQLite error code is returned. Otherwise:
54195 **
54196 ** The page number of the next overflow page in the linked list is 
54197 ** written to *pPgnoNext. If page ovfl is the last page in its linked 
54198 ** list, *pPgnoNext is set to zero. 
54199 **
54200 ** If ppPage is not NULL, and a reference to the MemPage object corresponding
54201 ** to page number pOvfl was obtained, then *ppPage is set to point to that
54202 ** reference. It is the responsibility of the caller to call releasePage()
54203 ** on *ppPage to free the reference. In no reference was obtained (because
54204 ** the pointer-map was used to obtain the value for *pPgnoNext), then
54205 ** *ppPage is set to zero.
54206 */
54207 static int getOverflowPage(
54208   BtShared *pBt,               /* The database file */
54209   Pgno ovfl,                   /* Current overflow page number */
54210   MemPage **ppPage,            /* OUT: MemPage handle (may be NULL) */
54211   Pgno *pPgnoNext              /* OUT: Next overflow page number */
54212 ){
54213   Pgno next = 0;
54214   MemPage *pPage = 0;
54215   int rc = SQLITE_OK;
54216 
54217   assert( sqlite3_mutex_held(pBt->mutex) );
54218   assert(pPgnoNext);
54219 
54220 #ifndef SQLITE_OMIT_AUTOVACUUM
54221   /* Try to find the next page in the overflow list using the
54222   ** autovacuum pointer-map pages. Guess that the next page in 
54223   ** the overflow list is page number (ovfl+1). If that guess turns 
54224   ** out to be wrong, fall back to loading the data of page 
54225   ** number ovfl to determine the next page number.
54226   */
54227   if( pBt->autoVacuum ){
54228     Pgno pgno;
54229     Pgno iGuess = ovfl+1;
54230     u8 eType;
54231 
54232     while( PTRMAP_ISPAGE(pBt, iGuess) || iGuess==PENDING_BYTE_PAGE(pBt) ){
54233       iGuess++;
54234     }
54235 
54236     if( iGuess<=btreePagecount(pBt) ){
54237       rc = ptrmapGet(pBt, iGuess, &eType, &pgno);
54238       if( rc==SQLITE_OK && eType==PTRMAP_OVERFLOW2 && pgno==ovfl ){
54239         next = iGuess;
54240         rc = SQLITE_DONE;
54241       }
54242     }
54243   }
54244 #endif
54245 
54246   assert( next==0 || rc==SQLITE_DONE );
54247   if( rc==SQLITE_OK ){
54248     rc = btreeGetPage(pBt, ovfl, &pPage, (ppPage==0) ? PAGER_GET_READONLY : 0);
54249     assert( rc==SQLITE_OK || pPage==0 );
54250     if( rc==SQLITE_OK ){
54251       next = get4byte(pPage->aData);
54252     }
54253   }
54254 
54255   *pPgnoNext = next;
54256   if( ppPage ){
54257     *ppPage = pPage;
54258   }else{
54259     releasePage(pPage);
54260   }
54261   return (rc==SQLITE_DONE ? SQLITE_OK : rc);
54262 }
54263 
54264 /*
54265 ** Copy data from a buffer to a page, or from a page to a buffer.
54266 **
54267 ** pPayload is a pointer to data stored on database page pDbPage.
54268 ** If argument eOp is false, then nByte bytes of data are copied
54269 ** from pPayload to the buffer pointed at by pBuf. If eOp is true,
54270 ** then sqlite3PagerWrite() is called on pDbPage and nByte bytes
54271 ** of data are copied from the buffer pBuf to pPayload.
54272 **
54273 ** SQLITE_OK is returned on success, otherwise an error code.
54274 */
54275 static int copyPayload(
54276   void *pPayload,           /* Pointer to page data */
54277   void *pBuf,               /* Pointer to buffer */
54278   int nByte,                /* Number of bytes to copy */
54279   int eOp,                  /* 0 -> copy from page, 1 -> copy to page */
54280   DbPage *pDbPage           /* Page containing pPayload */
54281 ){
54282   if( eOp ){
54283     /* Copy data from buffer to page (a write operation) */
54284     int rc = sqlite3PagerWrite(pDbPage);
54285     if( rc!=SQLITE_OK ){
54286       return rc;
54287     }
54288     memcpy(pPayload, pBuf, nByte);
54289   }else{
54290     /* Copy data from page to buffer (a read operation) */
54291     memcpy(pBuf, pPayload, nByte);
54292   }
54293   return SQLITE_OK;
54294 }
54295 
54296 /*
54297 ** This function is used to read or overwrite payload information
54298 ** for the entry that the pCur cursor is pointing to. If the eOp
54299 ** parameter is 0, this is a read operation (data copied into
54300 ** buffer pBuf). If it is non-zero, a write (data copied from
54301 ** buffer pBuf).
54302 **
54303 ** A total of "amt" bytes are read or written beginning at "offset".
54304 ** Data is read to or from the buffer pBuf.
54305 **
54306 ** The content being read or written might appear on the main page
54307 ** or be scattered out on multiple overflow pages.
54308 **
54309 ** If the BtCursor.isIncrblobHandle flag is set, and the current
54310 ** cursor entry uses one or more overflow pages, this function
54311 ** allocates space for and lazily popluates the overflow page-list 
54312 ** cache array (BtCursor.aOverflow). Subsequent calls use this
54313 ** cache to make seeking to the supplied offset more efficient.
54314 **
54315 ** Once an overflow page-list cache has been allocated, it may be
54316 ** invalidated if some other cursor writes to the same table, or if
54317 ** the cursor is moved to a different row. Additionally, in auto-vacuum
54318 ** mode, the following events may invalidate an overflow page-list cache.
54319 **
54320 **   * An incremental vacuum,
54321 **   * A commit in auto_vacuum="full" mode,
54322 **   * Creating a table (may require moving an overflow page).
54323 */
54324 static int accessPayload(
54325   BtCursor *pCur,      /* Cursor pointing to entry to read from */
54326   u32 offset,          /* Begin reading this far into payload */
54327   u32 amt,             /* Read this many bytes */
54328   unsigned char *pBuf, /* Write the bytes into this buffer */ 
54329   int eOp              /* zero to read. non-zero to write. */
54330 ){
54331   unsigned char *aPayload;
54332   int rc = SQLITE_OK;
54333   u32 nKey;
54334   int iIdx = 0;
54335   MemPage *pPage = pCur->apPage[pCur->iPage]; /* Btree page of current entry */
54336   BtShared *pBt = pCur->pBt;                  /* Btree this cursor belongs to */
54337 
54338   assert( pPage );
54339   assert( pCur->eState==CURSOR_VALID );
54340   assert( pCur->aiIdx[pCur->iPage]<pPage->nCell );
54341   assert( cursorHoldsMutex(pCur) );
54342 
54343   getCellInfo(pCur);
54344   aPayload = pCur->info.pCell + pCur->info.nHeader;
54345   nKey = (pPage->intKey ? 0 : (int)pCur->info.nKey);
54346 
54347   if( NEVER(offset+amt > nKey+pCur->info.nData) 
54348    || &aPayload[pCur->info.nLocal] > &pPage->aData[pBt->usableSize]
54349   ){
54350     /* Trying to read or write past the end of the data is an error */
54351     return SQLITE_CORRUPT_BKPT;
54352   }
54353 
54354   /* Check if data must be read/written to/from the btree page itself. */
54355   if( offset<pCur->info.nLocal ){
54356     int a = amt;
54357     if( a+offset>pCur->info.nLocal ){
54358       a = pCur->info.nLocal - offset;
54359     }
54360     rc = copyPayload(&aPayload[offset], pBuf, a, eOp, pPage->pDbPage);
54361     offset = 0;
54362     pBuf += a;
54363     amt -= a;
54364   }else{
54365     offset -= pCur->info.nLocal;
54366   }
54367 
54368   if( rc==SQLITE_OK && amt>0 ){
54369     const u32 ovflSize = pBt->usableSize - 4;  /* Bytes content per ovfl page */
54370     Pgno nextPage;
54371 
54372     nextPage = get4byte(&aPayload[pCur->info.nLocal]);
54373 
54374 #ifndef SQLITE_OMIT_INCRBLOB
54375     /* If the isIncrblobHandle flag is set and the BtCursor.aOverflow[]
54376     ** has not been allocated, allocate it now. The array is sized at
54377     ** one entry for each overflow page in the overflow chain. The
54378     ** page number of the first overflow page is stored in aOverflow[0],
54379     ** etc. A value of 0 in the aOverflow[] array means "not yet known"
54380     ** (the cache is lazily populated).
54381     */
54382     if( pCur->isIncrblobHandle && !pCur->aOverflow ){
54383       int nOvfl = (pCur->info.nPayload-pCur->info.nLocal+ovflSize-1)/ovflSize;
54384       pCur->aOverflow = (Pgno *)sqlite3MallocZero(sizeof(Pgno)*nOvfl);
54385       /* nOvfl is always positive.  If it were zero, fetchPayload would have
54386       ** been used instead of this routine. */
54387       if( ALWAYS(nOvfl) && !pCur->aOverflow ){
54388         rc = SQLITE_NOMEM;
54389       }
54390     }
54391 
54392     /* If the overflow page-list cache has been allocated and the
54393     ** entry for the first required overflow page is valid, skip
54394     ** directly to it.
54395     */
54396     if( pCur->aOverflow && pCur->aOverflow[offset/ovflSize] ){
54397       iIdx = (offset/ovflSize);
54398       nextPage = pCur->aOverflow[iIdx];
54399       offset = (offset%ovflSize);
54400     }
54401 #endif
54402 
54403     for( ; rc==SQLITE_OK && amt>0 && nextPage; iIdx++){
54404 
54405 #ifndef SQLITE_OMIT_INCRBLOB
54406       /* If required, populate the overflow page-list cache. */
54407       if( pCur->aOverflow ){
54408         assert(!pCur->aOverflow[iIdx] || pCur->aOverflow[iIdx]==nextPage);
54409         pCur->aOverflow[iIdx] = nextPage;
54410       }
54411 #endif
54412 
54413       if( offset>=ovflSize ){
54414         /* The only reason to read this page is to obtain the page
54415         ** number for the next page in the overflow chain. The page
54416         ** data is not required. So first try to lookup the overflow
54417         ** page-list cache, if any, then fall back to the getOverflowPage()
54418         ** function.
54419         */
54420 #ifndef SQLITE_OMIT_INCRBLOB
54421         if( pCur->aOverflow && pCur->aOverflow[iIdx+1] ){
54422           nextPage = pCur->aOverflow[iIdx+1];
54423         } else 
54424 #endif
54425           rc = getOverflowPage(pBt, nextPage, 0, &nextPage);
54426         offset -= ovflSize;
54427       }else{
54428         /* Need to read this page properly. It contains some of the
54429         ** range of data that is being read (eOp==0) or written (eOp!=0).
54430         */
54431 #ifdef SQLITE_DIRECT_OVERFLOW_READ
54432         sqlite3_file *fd;
54433 #endif
54434         int a = amt;
54435         if( a + offset > ovflSize ){
54436           a = ovflSize - offset;
54437         }
54438 
54439 #ifdef SQLITE_DIRECT_OVERFLOW_READ
54440         /* If all the following are true:
54441         **
54442         **   1) this is a read operation, and 
54443         **   2) data is required from the start of this overflow page, and
54444         **   3) the database is file-backed, and
54445         **   4) there is no open write-transaction, and
54446         **   5) the database is not a WAL database,
54447         **
54448         ** then data can be read directly from the database file into the
54449         ** output buffer, bypassing the page-cache altogether. This speeds
54450         ** up loading large records that span many overflow pages.
54451         */
54452         if( eOp==0                                             /* (1) */
54453          && offset==0                                          /* (2) */
54454          && pBt->inTransaction==TRANS_READ                     /* (4) */
54455          && (fd = sqlite3PagerFile(pBt->pPager))->pMethods     /* (3) */
54456          && pBt->pPage1->aData[19]==0x01                       /* (5) */
54457         ){
54458           u8 aSave[4];
54459           u8 *aWrite = &pBuf[-4];
54460           memcpy(aSave, aWrite, 4);
54461           rc = sqlite3OsRead(fd, aWrite, a+4, (i64)pBt->pageSize*(nextPage-1));
54462           nextPage = get4byte(aWrite);
54463           memcpy(aWrite, aSave, 4);
54464         }else
54465 #endif
54466 
54467         {
54468           DbPage *pDbPage;
54469           rc = sqlite3PagerAcquire(pBt->pPager, nextPage, &pDbPage,
54470               (eOp==0 ? PAGER_GET_READONLY : 0)
54471           );
54472           if( rc==SQLITE_OK ){
54473             aPayload = sqlite3PagerGetData(pDbPage);
54474             nextPage = get4byte(aPayload);
54475             rc = copyPayload(&aPayload[offset+4], pBuf, a, eOp, pDbPage);
54476             sqlite3PagerUnref(pDbPage);
54477             offset = 0;
54478           }
54479         }
54480         amt -= a;
54481         pBuf += a;
54482       }
54483     }
54484   }
54485 
54486   if( rc==SQLITE_OK && amt>0 ){
54487     return SQLITE_CORRUPT_BKPT;
54488   }
54489   return rc;
54490 }
54491 
54492 /*
54493 ** Read part of the key associated with cursor pCur.  Exactly
54494 ** "amt" bytes will be transfered into pBuf[].  The transfer
54495 ** begins at "offset".
54496 **
54497 ** The caller must ensure that pCur is pointing to a valid row
54498 ** in the table.
54499 **
54500 ** Return SQLITE_OK on success or an error code if anything goes
54501 ** wrong.  An error is returned if "offset+amt" is larger than
54502 ** the available payload.
54503 */
54504 SQLITE_PRIVATE int sqlite3BtreeKey(BtCursor *pCur, u32 offset, u32 amt, void *pBuf){
54505   assert( cursorHoldsMutex(pCur) );
54506   assert( pCur->eState==CURSOR_VALID );
54507   assert( pCur->iPage>=0 && pCur->apPage[pCur->iPage] );
54508   assert( pCur->aiIdx[pCur->iPage]<pCur->apPage[pCur->iPage]->nCell );
54509   return accessPayload(pCur, offset, amt, (unsigned char*)pBuf, 0);
54510 }
54511 
54512 /*
54513 ** Read part of the data associated with cursor pCur.  Exactly
54514 ** "amt" bytes will be transfered into pBuf[].  The transfer
54515 ** begins at "offset".
54516 **
54517 ** Return SQLITE_OK on success or an error code if anything goes
54518 ** wrong.  An error is returned if "offset+amt" is larger than
54519 ** the available payload.
54520 */
54521 SQLITE_PRIVATE int sqlite3BtreeData(BtCursor *pCur, u32 offset, u32 amt, void *pBuf){
54522   int rc;
54523 
54524 #ifndef SQLITE_OMIT_INCRBLOB
54525   if ( pCur->eState==CURSOR_INVALID ){
54526     return SQLITE_ABORT;
54527   }
54528 #endif
54529 
54530   assert( cursorHoldsMutex(pCur) );
54531   rc = restoreCursorPosition(pCur);
54532   if( rc==SQLITE_OK ){
54533     assert( pCur->eState==CURSOR_VALID );
54534     assert( pCur->iPage>=0 && pCur->apPage[pCur->iPage] );
54535     assert( pCur->aiIdx[pCur->iPage]<pCur->apPage[pCur->iPage]->nCell );
54536     rc = accessPayload(pCur, offset, amt, pBuf, 0);
54537   }
54538   return rc;
54539 }
54540 
54541 /*
54542 ** Return a pointer to payload information from the entry that the 
54543 ** pCur cursor is pointing to.  The pointer is to the beginning of
54544 ** the key if skipKey==0 and it points to the beginning of data if
54545 ** skipKey==1.  The number of bytes of available key/data is written
54546 ** into *pAmt.  If *pAmt==0, then the value returned will not be
54547 ** a valid pointer.
54548 **
54549 ** This routine is an optimization.  It is common for the entire key
54550 ** and data to fit on the local page and for there to be no overflow
54551 ** pages.  When that is so, this routine can be used to access the
54552 ** key and data without making a copy.  If the key and/or data spills
54553 ** onto overflow pages, then accessPayload() must be used to reassemble
54554 ** the key/data and copy it into a preallocated buffer.
54555 **
54556 ** The pointer returned by this routine looks directly into the cached
54557 ** page of the database.  The data might change or move the next time
54558 ** any btree routine is called.
54559 */
54560 static const unsigned char *fetchPayload(
54561   BtCursor *pCur,      /* Cursor pointing to entry to read from */
54562   u32 *pAmt,           /* Write the number of available bytes here */
54563   int skipKey          /* read beginning at data if this is true */
54564 ){
54565   unsigned char *aPayload;
54566   MemPage *pPage;
54567   u32 nKey;
54568   u32 nLocal;
54569 
54570   assert( pCur!=0 && pCur->iPage>=0 && pCur->apPage[pCur->iPage]);
54571   assert( pCur->eState==CURSOR_VALID );
54572   assert( cursorHoldsMutex(pCur) );
54573   pPage = pCur->apPage[pCur->iPage];
54574   assert( pCur->aiIdx[pCur->iPage]<pPage->nCell );
54575   if( pCur->info.nSize==0 ){
54576     btreeParseCell(pCur->apPage[pCur->iPage], pCur->aiIdx[pCur->iPage],
54577                    &pCur->info);
54578   }
54579   aPayload = pCur->info.pCell;
54580   aPayload += pCur->info.nHeader;
54581   if( pPage->intKey ){
54582     nKey = 0;
54583   }else{
54584     nKey = (int)pCur->info.nKey;
54585   }
54586   if( skipKey ){
54587     aPayload += nKey;
54588     nLocal = pCur->info.nLocal - nKey;
54589   }else{
54590     nLocal = pCur->info.nLocal;
54591     assert( nLocal<=nKey );
54592   }
54593   *pAmt = nLocal;
54594   return aPayload;
54595 }
54596 
54597 
54598 /*
54599 ** For the entry that cursor pCur is point to, return as
54600 ** many bytes of the key or data as are available on the local
54601 ** b-tree page.  Write the number of available bytes into *pAmt.
54602 **
54603 ** The pointer returned is ephemeral.  The key/data may move
54604 ** or be destroyed on the next call to any Btree routine,
54605 ** including calls from other threads against the same cache.
54606 ** Hence, a mutex on the BtShared should be held prior to calling
54607 ** this routine.
54608 **
54609 ** These routines is used to get quick access to key and data
54610 ** in the common case where no overflow pages are used.
54611 */
54612 SQLITE_PRIVATE const void *sqlite3BtreeKeyFetch(BtCursor *pCur, u32 *pAmt){
54613   const void *p = 0;
54614   assert( sqlite3_mutex_held(pCur->pBtree->db->mutex) );
54615   assert( cursorHoldsMutex(pCur) );
54616   if( ALWAYS(pCur->eState==CURSOR_VALID) ){
54617     p = (const void*)fetchPayload(pCur, pAmt, 0);
54618   }
54619   return p;
54620 }
54621 SQLITE_PRIVATE const void *sqlite3BtreeDataFetch(BtCursor *pCur, u32 *pAmt){
54622   const void *p = 0;
54623   assert( sqlite3_mutex_held(pCur->pBtree->db->mutex) );
54624   assert( cursorHoldsMutex(pCur) );
54625   if( ALWAYS(pCur->eState==CURSOR_VALID) ){
54626     p = (const void*)fetchPayload(pCur, pAmt, 1);
54627   }
54628   return p;
54629 }
54630 
54631 
54632 /*
54633 ** Move the cursor down to a new child page.  The newPgno argument is the
54634 ** page number of the child page to move to.
54635 **
54636 ** This function returns SQLITE_CORRUPT if the page-header flags field of
54637 ** the new child page does not match the flags field of the parent (i.e.
54638 ** if an intkey page appears to be the parent of a non-intkey page, or
54639 ** vice-versa).
54640 */
54641 static int moveToChild(BtCursor *pCur, u32 newPgno){
54642   int rc;
54643   int i = pCur->iPage;
54644   MemPage *pNewPage;
54645   BtShared *pBt = pCur->pBt;
54646 
54647   assert( cursorHoldsMutex(pCur) );
54648   assert( pCur->eState==CURSOR_VALID );
54649   assert( pCur->iPage<BTCURSOR_MAX_DEPTH );
54650   assert( pCur->iPage>=0 );
54651   if( pCur->iPage>=(BTCURSOR_MAX_DEPTH-1) ){
54652     return SQLITE_CORRUPT_BKPT;
54653   }
54654   rc = getAndInitPage(pBt, newPgno, &pNewPage,
54655                pCur->wrFlag==0 ? PAGER_GET_READONLY : 0);
54656   if( rc ) return rc;
54657   pCur->apPage[i+1] = pNewPage;
54658   pCur->aiIdx[i+1] = 0;
54659   pCur->iPage++;
54660 
54661   pCur->info.nSize = 0;
54662   pCur->validNKey = 0;
54663   if( pNewPage->nCell<1 || pNewPage->intKey!=pCur->apPage[i]->intKey ){
54664     return SQLITE_CORRUPT_BKPT;
54665   }
54666   return SQLITE_OK;
54667 }
54668 
54669 #if 0
54670 /*
54671 ** Page pParent is an internal (non-leaf) tree page. This function 
54672 ** asserts that page number iChild is the left-child if the iIdx'th
54673 ** cell in page pParent. Or, if iIdx is equal to the total number of
54674 ** cells in pParent, that page number iChild is the right-child of
54675 ** the page.
54676 */
54677 static void assertParentIndex(MemPage *pParent, int iIdx, Pgno iChild){
54678   assert( iIdx<=pParent->nCell );
54679   if( iIdx==pParent->nCell ){
54680     assert( get4byte(&pParent->aData[pParent->hdrOffset+8])==iChild );
54681   }else{
54682     assert( get4byte(findCell(pParent, iIdx))==iChild );
54683   }
54684 }
54685 #else
54686 #  define assertParentIndex(x,y,z) 
54687 #endif
54688 
54689 /*
54690 ** Move the cursor up to the parent page.
54691 **
54692 ** pCur->idx is set to the cell index that contains the pointer
54693 ** to the page we are coming from.  If we are coming from the
54694 ** right-most child page then pCur->idx is set to one more than
54695 ** the largest cell index.
54696 */
54697 static void moveToParent(BtCursor *pCur){
54698   assert( cursorHoldsMutex(pCur) );
54699   assert( pCur->eState==CURSOR_VALID );
54700   assert( pCur->iPage>0 );
54701   assert( pCur->apPage[pCur->iPage] );
54702 
54703   /* UPDATE: It is actually possible for the condition tested by the assert
54704   ** below to be untrue if the database file is corrupt. This can occur if
54705   ** one cursor has modified page pParent while a reference to it is held 
54706   ** by a second cursor. Which can only happen if a single page is linked
54707   ** into more than one b-tree structure in a corrupt database.  */
54708 #if 0
54709   assertParentIndex(
54710     pCur->apPage[pCur->iPage-1], 
54711     pCur->aiIdx[pCur->iPage-1], 
54712     pCur->apPage[pCur->iPage]->pgno
54713   );
54714 #endif
54715   testcase( pCur->aiIdx[pCur->iPage-1] > pCur->apPage[pCur->iPage-1]->nCell );
54716 
54717   releasePage(pCur->apPage[pCur->iPage]);
54718   pCur->iPage--;
54719   pCur->info.nSize = 0;
54720   pCur->validNKey = 0;
54721 }
54722 
54723 /*
54724 ** Move the cursor to point to the root page of its b-tree structure.
54725 **
54726 ** If the table has a virtual root page, then the cursor is moved to point
54727 ** to the virtual root page instead of the actual root page. A table has a
54728 ** virtual root page when the actual root page contains no cells and a 
54729 ** single child page. This can only happen with the table rooted at page 1.
54730 **
54731 ** If the b-tree structure is empty, the cursor state is set to 
54732 ** CURSOR_INVALID. Otherwise, the cursor is set to point to the first
54733 ** cell located on the root (or virtual root) page and the cursor state
54734 ** is set to CURSOR_VALID.
54735 **
54736 ** If this function returns successfully, it may be assumed that the
54737 ** page-header flags indicate that the [virtual] root-page is the expected 
54738 ** kind of b-tree page (i.e. if when opening the cursor the caller did not
54739 ** specify a KeyInfo structure the flags byte is set to 0x05 or 0x0D,
54740 ** indicating a table b-tree, or if the caller did specify a KeyInfo 
54741 ** structure the flags byte is set to 0x02 or 0x0A, indicating an index
54742 ** b-tree).
54743 */
54744 static int moveToRoot(BtCursor *pCur){
54745   MemPage *pRoot;
54746   int rc = SQLITE_OK;
54747   Btree *p = pCur->pBtree;
54748   BtShared *pBt = p->pBt;
54749 
54750   assert( cursorHoldsMutex(pCur) );
54751   assert( CURSOR_INVALID < CURSOR_REQUIRESEEK );
54752   assert( CURSOR_VALID   < CURSOR_REQUIRESEEK );
54753   assert( CURSOR_FAULT   > CURSOR_REQUIRESEEK );
54754   if( pCur->eState>=CURSOR_REQUIRESEEK ){
54755     if( pCur->eState==CURSOR_FAULT ){
54756       assert( pCur->skipNext!=SQLITE_OK );
54757       return pCur->skipNext;
54758     }
54759     sqlite3BtreeClearCursor(pCur);
54760   }
54761 
54762   if( pCur->iPage>=0 ){
54763     int i;
54764     for(i=1; i<=pCur->iPage; i++){
54765       releasePage(pCur->apPage[i]);
54766     }
54767     pCur->iPage = 0;
54768   }else if( pCur->pgnoRoot==0 ){
54769     pCur->eState = CURSOR_INVALID;
54770     return SQLITE_OK;
54771   }else{
54772     rc = getAndInitPage(pBt, pCur->pgnoRoot, &pCur->apPage[0],
54773                         pCur->wrFlag==0 ? PAGER_GET_READONLY : 0);
54774     if( rc!=SQLITE_OK ){
54775       pCur->eState = CURSOR_INVALID;
54776       return rc;
54777     }
54778     pCur->iPage = 0;
54779 
54780     /* If pCur->pKeyInfo is not NULL, then the caller that opened this cursor
54781     ** expected to open it on an index b-tree. Otherwise, if pKeyInfo is
54782     ** NULL, the caller expects a table b-tree. If this is not the case,
54783     ** return an SQLITE_CORRUPT error.  */
54784     assert( pCur->apPage[0]->intKey==1 || pCur->apPage[0]->intKey==0 );
54785     if( (pCur->pKeyInfo==0)!=pCur->apPage[0]->intKey ){
54786       return SQLITE_CORRUPT_BKPT;
54787     }
54788   }
54789 
54790   /* Assert that the root page is of the correct type. This must be the
54791   ** case as the call to this function that loaded the root-page (either
54792   ** this call or a previous invocation) would have detected corruption 
54793   ** if the assumption were not true, and it is not possible for the flags 
54794   ** byte to have been modified while this cursor is holding a reference
54795   ** to the page.  */
54796   pRoot = pCur->apPage[0];
54797   assert( pRoot->pgno==pCur->pgnoRoot );
54798   assert( pRoot->isInit && (pCur->pKeyInfo==0)==pRoot->intKey );
54799 
54800   pCur->aiIdx[0] = 0;
54801   pCur->info.nSize = 0;
54802   pCur->atLast = 0;
54803   pCur->validNKey = 0;
54804 
54805   if( pRoot->nCell==0 && !pRoot->leaf ){
54806     Pgno subpage;
54807     if( pRoot->pgno!=1 ) return SQLITE_CORRUPT_BKPT;
54808     subpage = get4byte(&pRoot->aData[pRoot->hdrOffset+8]);
54809     pCur->eState = CURSOR_VALID;
54810     rc = moveToChild(pCur, subpage);
54811   }else{
54812     pCur->eState = ((pRoot->nCell>0)?CURSOR_VALID:CURSOR_INVALID);
54813   }
54814   return rc;
54815 }
54816 
54817 /*
54818 ** Move the cursor down to the left-most leaf entry beneath the
54819 ** entry to which it is currently pointing.
54820 **
54821 ** The left-most leaf is the one with the smallest key - the first
54822 ** in ascending order.
54823 */
54824 static int moveToLeftmost(BtCursor *pCur){
54825   Pgno pgno;
54826   int rc = SQLITE_OK;
54827   MemPage *pPage;
54828 
54829   assert( cursorHoldsMutex(pCur) );
54830   assert( pCur->eState==CURSOR_VALID );
54831   while( rc==SQLITE_OK && !(pPage = pCur->apPage[pCur->iPage])->leaf ){
54832     assert( pCur->aiIdx[pCur->iPage]<pPage->nCell );
54833     pgno = get4byte(findCell(pPage, pCur->aiIdx[pCur->iPage]));
54834     rc = moveToChild(pCur, pgno);
54835   }
54836   return rc;
54837 }
54838 
54839 /*
54840 ** Move the cursor down to the right-most leaf entry beneath the
54841 ** page to which it is currently pointing.  Notice the difference
54842 ** between moveToLeftmost() and moveToRightmost().  moveToLeftmost()
54843 ** finds the left-most entry beneath the *entry* whereas moveToRightmost()
54844 ** finds the right-most entry beneath the *page*.
54845 **
54846 ** The right-most entry is the one with the largest key - the last
54847 ** key in ascending order.
54848 */
54849 static int moveToRightmost(BtCursor *pCur){
54850   Pgno pgno;
54851   int rc = SQLITE_OK;
54852   MemPage *pPage = 0;
54853 
54854   assert( cursorHoldsMutex(pCur) );
54855   assert( pCur->eState==CURSOR_VALID );
54856   while( rc==SQLITE_OK && !(pPage = pCur->apPage[pCur->iPage])->leaf ){
54857     pgno = get4byte(&pPage->aData[pPage->hdrOffset+8]);
54858     pCur->aiIdx[pCur->iPage] = pPage->nCell;
54859     rc = moveToChild(pCur, pgno);
54860   }
54861   if( rc==SQLITE_OK ){
54862     pCur->aiIdx[pCur->iPage] = pPage->nCell-1;
54863     pCur->info.nSize = 0;
54864     pCur->validNKey = 0;
54865   }
54866   return rc;
54867 }
54868 
54869 /* Move the cursor to the first entry in the table.  Return SQLITE_OK
54870 ** on success.  Set *pRes to 0 if the cursor actually points to something
54871 ** or set *pRes to 1 if the table is empty.
54872 */
54873 SQLITE_PRIVATE int sqlite3BtreeFirst(BtCursor *pCur, int *pRes){
54874   int rc;
54875 
54876   assert( cursorHoldsMutex(pCur) );
54877   assert( sqlite3_mutex_held(pCur->pBtree->db->mutex) );
54878   rc = moveToRoot(pCur);
54879   if( rc==SQLITE_OK ){
54880     if( pCur->eState==CURSOR_INVALID ){
54881       assert( pCur->pgnoRoot==0 || pCur->apPage[pCur->iPage]->nCell==0 );
54882       *pRes = 1;
54883     }else{
54884       assert( pCur->apPage[pCur->iPage]->nCell>0 );
54885       *pRes = 0;
54886       rc = moveToLeftmost(pCur);
54887     }
54888   }
54889   return rc;
54890 }
54891 
54892 /* Move the cursor to the last entry in the table.  Return SQLITE_OK
54893 ** on success.  Set *pRes to 0 if the cursor actually points to something
54894 ** or set *pRes to 1 if the table is empty.
54895 */
54896 SQLITE_PRIVATE int sqlite3BtreeLast(BtCursor *pCur, int *pRes){
54897   int rc;
54898  
54899   assert( cursorHoldsMutex(pCur) );
54900   assert( sqlite3_mutex_held(pCur->pBtree->db->mutex) );
54901 
54902   /* If the cursor already points to the last entry, this is a no-op. */
54903   if( CURSOR_VALID==pCur->eState && pCur->atLast ){
54904 #ifdef SQLITE_DEBUG
54905     /* This block serves to assert() that the cursor really does point 
54906     ** to the last entry in the b-tree. */
54907     int ii;
54908     for(ii=0; ii<pCur->iPage; ii++){
54909       assert( pCur->aiIdx[ii]==pCur->apPage[ii]->nCell );
54910     }
54911     assert( pCur->aiIdx[pCur->iPage]==pCur->apPage[pCur->iPage]->nCell-1 );
54912     assert( pCur->apPage[pCur->iPage]->leaf );
54913 #endif
54914     return SQLITE_OK;
54915   }
54916 
54917   rc = moveToRoot(pCur);
54918   if( rc==SQLITE_OK ){
54919     if( CURSOR_INVALID==pCur->eState ){
54920       assert( pCur->pgnoRoot==0 || pCur->apPage[pCur->iPage]->nCell==0 );
54921       *pRes = 1;
54922     }else{
54923       assert( pCur->eState==CURSOR_VALID );
54924       *pRes = 0;
54925       rc = moveToRightmost(pCur);
54926       pCur->atLast = rc==SQLITE_OK ?1:0;
54927     }
54928   }
54929   return rc;
54930 }
54931 
54932 /* Move the cursor so that it points to an entry near the key 
54933 ** specified by pIdxKey or intKey.   Return a success code.
54934 **
54935 ** For INTKEY tables, the intKey parameter is used.  pIdxKey 
54936 ** must be NULL.  For index tables, pIdxKey is used and intKey
54937 ** is ignored.
54938 **
54939 ** If an exact match is not found, then the cursor is always
54940 ** left pointing at a leaf page which would hold the entry if it
54941 ** were present.  The cursor might point to an entry that comes
54942 ** before or after the key.
54943 **
54944 ** An integer is written into *pRes which is the result of
54945 ** comparing the key with the entry to which the cursor is 
54946 ** pointing.  The meaning of the integer written into
54947 ** *pRes is as follows:
54948 **
54949 **     *pRes<0      The cursor is left pointing at an entry that
54950 **                  is smaller than intKey/pIdxKey or if the table is empty
54951 **                  and the cursor is therefore left point to nothing.
54952 **
54953 **     *pRes==0     The cursor is left pointing at an entry that
54954 **                  exactly matches intKey/pIdxKey.
54955 **
54956 **     *pRes>0      The cursor is left pointing at an entry that
54957 **                  is larger than intKey/pIdxKey.
54958 **
54959 */
54960 SQLITE_PRIVATE int sqlite3BtreeMovetoUnpacked(
54961   BtCursor *pCur,          /* The cursor to be moved */
54962   UnpackedRecord *pIdxKey, /* Unpacked index key */
54963   i64 intKey,              /* The table key */
54964   int biasRight,           /* If true, bias the search to the high end */
54965   int *pRes                /* Write search results here */
54966 ){
54967   int rc;
54968 
54969   assert( cursorHoldsMutex(pCur) );
54970   assert( sqlite3_mutex_held(pCur->pBtree->db->mutex) );
54971   assert( pRes );
54972   assert( (pIdxKey==0)==(pCur->pKeyInfo==0) );
54973 
54974   /* If the cursor is already positioned at the point we are trying
54975   ** to move to, then just return without doing any work */
54976   if( pCur->eState==CURSOR_VALID && pCur->validNKey 
54977    && pCur->apPage[0]->intKey 
54978   ){
54979     if( pCur->info.nKey==intKey ){
54980       *pRes = 0;
54981       return SQLITE_OK;
54982     }
54983     if( pCur->atLast && pCur->info.nKey<intKey ){
54984       *pRes = -1;
54985       return SQLITE_OK;
54986     }
54987   }
54988 
54989   rc = moveToRoot(pCur);
54990   if( rc ){
54991     return rc;
54992   }
54993   assert( pCur->pgnoRoot==0 || pCur->apPage[pCur->iPage] );
54994   assert( pCur->pgnoRoot==0 || pCur->apPage[pCur->iPage]->isInit );
54995   assert( pCur->eState==CURSOR_INVALID || pCur->apPage[pCur->iPage]->nCell>0 );
54996   if( pCur->eState==CURSOR_INVALID ){
54997     *pRes = -1;
54998     assert( pCur->pgnoRoot==0 || pCur->apPage[pCur->iPage]->nCell==0 );
54999     return SQLITE_OK;
55000   }
55001   assert( pCur->apPage[0]->intKey || pIdxKey );
55002   for(;;){
55003     int lwr, upr, idx, c;
55004     Pgno chldPg;
55005     MemPage *pPage = pCur->apPage[pCur->iPage];
55006     u8 *pCell;                          /* Pointer to current cell in pPage */
55007 
55008     /* pPage->nCell must be greater than zero. If this is the root-page
55009     ** the cursor would have been INVALID above and this for(;;) loop
55010     ** not run. If this is not the root-page, then the moveToChild() routine
55011     ** would have already detected db corruption. Similarly, pPage must
55012     ** be the right kind (index or table) of b-tree page. Otherwise
55013     ** a moveToChild() or moveToRoot() call would have detected corruption.  */
55014     assert( pPage->nCell>0 );
55015     assert( pPage->intKey==(pIdxKey==0) );
55016     lwr = 0;
55017     upr = pPage->nCell-1;
55018     assert( biasRight==0 || biasRight==1 );
55019     idx = upr>>(1-biasRight); /* idx = biasRight ? upr : (lwr+upr)/2; */
55020     pCur->aiIdx[pCur->iPage] = (u16)idx;
55021     if( pPage->intKey ){
55022       for(;;){
55023         i64 nCellKey;
55024         pCell = findCell(pPage, idx) + pPage->childPtrSize;
55025         if( pPage->hasData ){
55026           while( 0x80 <= *(pCell++) ){
55027             if( pCell>=pPage->aDataEnd ) return SQLITE_CORRUPT_BKPT;
55028           }
55029         }
55030         getVarint(pCell, (u64*)&nCellKey);
55031         if( nCellKey<intKey ){
55032           lwr = idx+1;
55033           if( lwr>upr ){ c = -1; break; }
55034         }else if( nCellKey>intKey ){
55035           upr = idx-1;
55036           if( lwr>upr ){ c = +1; break; }
55037         }else{
55038           assert( nCellKey==intKey );
55039           pCur->validNKey = 1;
55040           pCur->info.nKey = nCellKey;
55041           pCur->aiIdx[pCur->iPage] = (u16)idx;
55042           if( !pPage->leaf ){
55043             lwr = idx;
55044             goto moveto_next_layer;
55045           }else{
55046             *pRes = 0;
55047             rc = SQLITE_OK;
55048             goto moveto_finish;
55049           }
55050         }
55051         assert( lwr+upr>=0 );
55052         idx = (lwr+upr)>>1;  /* idx = (lwr+upr)/2; */
55053       }
55054     }else{
55055       for(;;){
55056         int nCell;
55057         pCell = findCell(pPage, idx) + pPage->childPtrSize;
55058 
55059         /* The maximum supported page-size is 65536 bytes. This means that
55060         ** the maximum number of record bytes stored on an index B-Tree
55061         ** page is less than 16384 bytes and may be stored as a 2-byte
55062         ** varint. This information is used to attempt to avoid parsing 
55063         ** the entire cell by checking for the cases where the record is 
55064         ** stored entirely within the b-tree page by inspecting the first 
55065         ** 2 bytes of the cell.
55066         */
55067         nCell = pCell[0];
55068         if( nCell<=pPage->max1bytePayload
55069          /* && (pCell+nCell)<pPage->aDataEnd */
55070         ){
55071           /* This branch runs if the record-size field of the cell is a
55072           ** single byte varint and the record fits entirely on the main
55073           ** b-tree page.  */
55074           testcase( pCell+nCell+1==pPage->aDataEnd );
55075           c = sqlite3VdbeRecordCompare(nCell, (void*)&pCell[1], pIdxKey);
55076         }else if( !(pCell[1] & 0x80) 
55077           && (nCell = ((nCell&0x7f)<<7) + pCell[1])<=pPage->maxLocal
55078           /* && (pCell+nCell+2)<=pPage->aDataEnd */
55079         ){
55080           /* The record-size field is a 2 byte varint and the record 
55081           ** fits entirely on the main b-tree page.  */
55082           testcase( pCell+nCell+2==pPage->aDataEnd );
55083           c = sqlite3VdbeRecordCompare(nCell, (void*)&pCell[2], pIdxKey);
55084         }else{
55085           /* The record flows over onto one or more overflow pages. In
55086           ** this case the whole cell needs to be parsed, a buffer allocated
55087           ** and accessPayload() used to retrieve the record into the
55088           ** buffer before VdbeRecordCompare() can be called. */
55089           void *pCellKey;
55090           u8 * const pCellBody = pCell - pPage->childPtrSize;
55091           btreeParseCellPtr(pPage, pCellBody, &pCur->info);
55092           nCell = (int)pCur->info.nKey;
55093           pCellKey = sqlite3Malloc( nCell );
55094           if( pCellKey==0 ){
55095             rc = SQLITE_NOMEM;
55096             goto moveto_finish;
55097           }
55098           pCur->aiIdx[pCur->iPage] = (u16)idx;
55099           rc = accessPayload(pCur, 0, nCell, (unsigned char*)pCellKey, 0);
55100           if( rc ){
55101             sqlite3_free(pCellKey);
55102             goto moveto_finish;
55103           }
55104           c = sqlite3VdbeRecordCompare(nCell, pCellKey, pIdxKey);
55105           sqlite3_free(pCellKey);
55106         }
55107         if( c<0 ){
55108           lwr = idx+1;
55109         }else if( c>0 ){
55110           upr = idx-1;
55111         }else{
55112           assert( c==0 );
55113           *pRes = 0;
55114           rc = SQLITE_OK;
55115           pCur->aiIdx[pCur->iPage] = (u16)idx;
55116           goto moveto_finish;
55117         }
55118         if( lwr>upr ) break;
55119         assert( lwr+upr>=0 );
55120         idx = (lwr+upr)>>1;  /* idx = (lwr+upr)/2 */
55121       }
55122     }
55123     assert( lwr==upr+1 || (pPage->intKey && !pPage->leaf) );
55124     assert( pPage->isInit );
55125     if( pPage->leaf ){
55126       assert( pCur->aiIdx[pCur->iPage]<pCur->apPage[pCur->iPage]->nCell );
55127       pCur->aiIdx[pCur->iPage] = (u16)idx;
55128       *pRes = c;
55129       rc = SQLITE_OK;
55130       goto moveto_finish;
55131     }
55132 moveto_next_layer:
55133     if( lwr>=pPage->nCell ){
55134       chldPg = get4byte(&pPage->aData[pPage->hdrOffset+8]);
55135     }else{
55136       chldPg = get4byte(findCell(pPage, lwr));
55137     }
55138     pCur->aiIdx[pCur->iPage] = (u16)lwr;
55139     rc = moveToChild(pCur, chldPg);
55140     if( rc ) break;
55141   }
55142 moveto_finish:
55143   pCur->info.nSize = 0;
55144   pCur->validNKey = 0;
55145   return rc;
55146 }
55147 
55148 
55149 /*
55150 ** Return TRUE if the cursor is not pointing at an entry of the table.
55151 **
55152 ** TRUE will be returned after a call to sqlite3BtreeNext() moves
55153 ** past the last entry in the table or sqlite3BtreePrev() moves past
55154 ** the first entry.  TRUE is also returned if the table is empty.
55155 */
55156 SQLITE_PRIVATE int sqlite3BtreeEof(BtCursor *pCur){
55157   /* TODO: What if the cursor is in CURSOR_REQUIRESEEK but all table entries
55158   ** have been deleted? This API will need to change to return an error code
55159   ** as well as the boolean result value.
55160   */
55161   return (CURSOR_VALID!=pCur->eState);
55162 }
55163 
55164 /*
55165 ** Advance the cursor to the next entry in the database.  If
55166 ** successful then set *pRes=0.  If the cursor
55167 ** was already pointing to the last entry in the database before
55168 ** this routine was called, then set *pRes=1.
55169 */
55170 SQLITE_PRIVATE int sqlite3BtreeNext(BtCursor *pCur, int *pRes){
55171   int rc;
55172   int idx;
55173   MemPage *pPage;
55174 
55175   assert( cursorHoldsMutex(pCur) );
55176   assert( pRes!=0 );
55177   assert( pCur->skipNext==0 || pCur->eState!=CURSOR_VALID );
55178   if( pCur->eState!=CURSOR_VALID ){
55179     rc = restoreCursorPosition(pCur);
55180     if( rc!=SQLITE_OK ){
55181       *pRes = 0;
55182       return rc;
55183     }
55184     if( CURSOR_INVALID==pCur->eState ){
55185       *pRes = 1;
55186       return SQLITE_OK;
55187     }
55188     if( pCur->skipNext ){
55189       assert( pCur->eState==CURSOR_VALID || pCur->eState==CURSOR_SKIPNEXT );
55190       pCur->eState = CURSOR_VALID;
55191       if( pCur->skipNext>0 ){
55192         pCur->skipNext = 0;
55193         *pRes = 0;
55194         return SQLITE_OK;
55195       }
55196       pCur->skipNext = 0;
55197     }
55198   }
55199 
55200   pPage = pCur->apPage[pCur->iPage];
55201   idx = ++pCur->aiIdx[pCur->iPage];
55202   assert( pPage->isInit );
55203 
55204   /* If the database file is corrupt, it is possible for the value of idx 
55205   ** to be invalid here. This can only occur if a second cursor modifies
55206   ** the page while cursor pCur is holding a reference to it. Which can
55207   ** only happen if the database is corrupt in such a way as to link the
55208   ** page into more than one b-tree structure. */
55209   testcase( idx>pPage->nCell );
55210 
55211   pCur->info.nSize = 0;
55212   pCur->validNKey = 0;
55213   if( idx>=pPage->nCell ){
55214     if( !pPage->leaf ){
55215       rc = moveToChild(pCur, get4byte(&pPage->aData[pPage->hdrOffset+8]));
55216       if( rc ){
55217         *pRes = 0;
55218         return rc;
55219       }
55220       rc = moveToLeftmost(pCur);
55221       *pRes = 0;
55222       return rc;
55223     }
55224     do{
55225       if( pCur->iPage==0 ){
55226         *pRes = 1;
55227         pCur->eState = CURSOR_INVALID;
55228         return SQLITE_OK;
55229       }
55230       moveToParent(pCur);
55231       pPage = pCur->apPage[pCur->iPage];
55232     }while( pCur->aiIdx[pCur->iPage]>=pPage->nCell );
55233     *pRes = 0;
55234     if( pPage->intKey ){
55235       rc = sqlite3BtreeNext(pCur, pRes);
55236     }else{
55237       rc = SQLITE_OK;
55238     }
55239     return rc;
55240   }
55241   *pRes = 0;
55242   if( pPage->leaf ){
55243     return SQLITE_OK;
55244   }
55245   rc = moveToLeftmost(pCur);
55246   return rc;
55247 }
55248 
55249 
55250 /*
55251 ** Step the cursor to the back to the previous entry in the database.  If
55252 ** successful then set *pRes=0.  If the cursor
55253 ** was already pointing to the first entry in the database before
55254 ** this routine was called, then set *pRes=1.
55255 */
55256 SQLITE_PRIVATE int sqlite3BtreePrevious(BtCursor *pCur, int *pRes){
55257   int rc;
55258   MemPage *pPage;
55259 
55260   assert( cursorHoldsMutex(pCur) );
55261   assert( pRes!=0 );
55262   assert( pCur->skipNext==0 || pCur->eState!=CURSOR_VALID );
55263   pCur->atLast = 0;
55264   if( pCur->eState!=CURSOR_VALID ){
55265     if( ALWAYS(pCur->eState>=CURSOR_REQUIRESEEK) ){
55266       rc = btreeRestoreCursorPosition(pCur);
55267       if( rc!=SQLITE_OK ){
55268         *pRes = 0;
55269         return rc;
55270       }
55271     }
55272     if( CURSOR_INVALID==pCur->eState ){
55273       *pRes = 1;
55274       return SQLITE_OK;
55275     }
55276     if( pCur->skipNext ){
55277       assert( pCur->eState==CURSOR_VALID || pCur->eState==CURSOR_SKIPNEXT );
55278       pCur->eState = CURSOR_VALID;
55279       if( pCur->skipNext<0 ){
55280         pCur->skipNext = 0;
55281         *pRes = 0;
55282         return SQLITE_OK;
55283       }
55284       pCur->skipNext = 0;
55285     }
55286   }
55287 
55288   pPage = pCur->apPage[pCur->iPage];
55289   assert( pPage->isInit );
55290   if( !pPage->leaf ){
55291     int idx = pCur->aiIdx[pCur->iPage];
55292     rc = moveToChild(pCur, get4byte(findCell(pPage, idx)));
55293     if( rc ){
55294       *pRes = 0;
55295       return rc;
55296     }
55297     rc = moveToRightmost(pCur);
55298   }else{
55299     while( pCur->aiIdx[pCur->iPage]==0 ){
55300       if( pCur->iPage==0 ){
55301         pCur->eState = CURSOR_INVALID;
55302         *pRes = 1;
55303         return SQLITE_OK;
55304       }
55305       moveToParent(pCur);
55306     }
55307     pCur->info.nSize = 0;
55308     pCur->validNKey = 0;
55309 
55310     pCur->aiIdx[pCur->iPage]--;
55311     pPage = pCur->apPage[pCur->iPage];
55312     if( pPage->intKey && !pPage->leaf ){
55313       rc = sqlite3BtreePrevious(pCur, pRes);
55314     }else{
55315       rc = SQLITE_OK;
55316     }
55317   }
55318   *pRes = 0;
55319   return rc;
55320 }
55321 
55322 /*
55323 ** Allocate a new page from the database file.
55324 **
55325 ** The new page is marked as dirty.  (In other words, sqlite3PagerWrite()
55326 ** has already been called on the new page.)  The new page has also
55327 ** been referenced and the calling routine is responsible for calling
55328 ** sqlite3PagerUnref() on the new page when it is done.
55329 **
55330 ** SQLITE_OK is returned on success.  Any other return value indicates
55331 ** an error.  *ppPage and *pPgno are undefined in the event of an error.
55332 ** Do not invoke sqlite3PagerUnref() on *ppPage if an error is returned.
55333 **
55334 ** If the "nearby" parameter is not 0, then an effort is made to 
55335 ** locate a page close to the page number "nearby".  This can be used in an
55336 ** attempt to keep related pages close to each other in the database file,
55337 ** which in turn can make database access faster.
55338 **
55339 ** If the eMode parameter is BTALLOC_EXACT and the nearby page exists
55340 ** anywhere on the free-list, then it is guaranteed to be returned.  If
55341 ** eMode is BTALLOC_LT then the page returned will be less than or equal
55342 ** to nearby if any such page exists.  If eMode is BTALLOC_ANY then there
55343 ** are no restrictions on which page is returned.
55344 */
55345 static int allocateBtreePage(
55346   BtShared *pBt,         /* The btree */
55347   MemPage **ppPage,      /* Store pointer to the allocated page here */
55348   Pgno *pPgno,           /* Store the page number here */
55349   Pgno nearby,           /* Search for a page near this one */
55350   u8 eMode               /* BTALLOC_EXACT, BTALLOC_LT, or BTALLOC_ANY */
55351 ){
55352   MemPage *pPage1;
55353   int rc;
55354   u32 n;     /* Number of pages on the freelist */
55355   u32 k;     /* Number of leaves on the trunk of the freelist */
55356   MemPage *pTrunk = 0;
55357   MemPage *pPrevTrunk = 0;
55358   Pgno mxPage;     /* Total size of the database file */
55359 
55360   assert( sqlite3_mutex_held(pBt->mutex) );
55361   assert( eMode==BTALLOC_ANY || (nearby>0 && IfNotOmitAV(pBt->autoVacuum)) );
55362   pPage1 = pBt->pPage1;
55363   mxPage = btreePagecount(pBt);
55364   n = get4byte(&pPage1->aData[36]);
55365   testcase( n==mxPage-1 );
55366   if( n>=mxPage ){
55367     return SQLITE_CORRUPT_BKPT;
55368   }
55369   if( n>0 ){
55370     /* There are pages on the freelist.  Reuse one of those pages. */
55371     Pgno iTrunk;
55372     u8 searchList = 0; /* If the free-list must be searched for 'nearby' */
55373     
55374     /* If eMode==BTALLOC_EXACT and a query of the pointer-map
55375     ** shows that the page 'nearby' is somewhere on the free-list, then
55376     ** the entire-list will be searched for that page.
55377     */
55378 #ifndef SQLITE_OMIT_AUTOVACUUM
55379     if( eMode==BTALLOC_EXACT ){
55380       if( nearby<=mxPage ){
55381         u8 eType;
55382         assert( nearby>0 );
55383         assert( pBt->autoVacuum );
55384         rc = ptrmapGet(pBt, nearby, &eType, 0);
55385         if( rc ) return rc;
55386         if( eType==PTRMAP_FREEPAGE ){
55387           searchList = 1;
55388         }
55389       }
55390     }else if( eMode==BTALLOC_LE ){
55391       searchList = 1;
55392     }
55393 #endif
55394 
55395     /* Decrement the free-list count by 1. Set iTrunk to the index of the
55396     ** first free-list trunk page. iPrevTrunk is initially 1.
55397     */
55398     rc = sqlite3PagerWrite(pPage1->pDbPage);
55399     if( rc ) return rc;
55400     put4byte(&pPage1->aData[36], n-1);
55401 
55402     /* The code within this loop is run only once if the 'searchList' variable
55403     ** is not true. Otherwise, it runs once for each trunk-page on the
55404     ** free-list until the page 'nearby' is located (eMode==BTALLOC_EXACT)
55405     ** or until a page less than 'nearby' is located (eMode==BTALLOC_LT)
55406     */
55407     do {
55408       pPrevTrunk = pTrunk;
55409       if( pPrevTrunk ){
55410         iTrunk = get4byte(&pPrevTrunk->aData[0]);
55411       }else{
55412         iTrunk = get4byte(&pPage1->aData[32]);
55413       }
55414       testcase( iTrunk==mxPage );
55415       if( iTrunk>mxPage ){
55416         rc = SQLITE_CORRUPT_BKPT;
55417       }else{
55418         rc = btreeGetPage(pBt, iTrunk, &pTrunk, 0);
55419       }
55420       if( rc ){
55421         pTrunk = 0;
55422         goto end_allocate_page;
55423       }
55424       assert( pTrunk!=0 );
55425       assert( pTrunk->aData!=0 );
55426 
55427       k = get4byte(&pTrunk->aData[4]); /* # of leaves on this trunk page */
55428       if( k==0 && !searchList ){
55429         /* The trunk has no leaves and the list is not being searched. 
55430         ** So extract the trunk page itself and use it as the newly 
55431         ** allocated page */
55432         assert( pPrevTrunk==0 );
55433         rc = sqlite3PagerWrite(pTrunk->pDbPage);
55434         if( rc ){
55435           goto end_allocate_page;
55436         }
55437         *pPgno = iTrunk;
55438         memcpy(&pPage1->aData[32], &pTrunk->aData[0], 4);
55439         *ppPage = pTrunk;
55440         pTrunk = 0;
55441         TRACE(("ALLOCATE: %d trunk - %d free pages left\n", *pPgno, n-1));
55442       }else if( k>(u32)(pBt->usableSize/4 - 2) ){
55443         /* Value of k is out of range.  Database corruption */
55444         rc = SQLITE_CORRUPT_BKPT;
55445         goto end_allocate_page;
55446 #ifndef SQLITE_OMIT_AUTOVACUUM
55447       }else if( searchList 
55448             && (nearby==iTrunk || (iTrunk<nearby && eMode==BTALLOC_LE)) 
55449       ){
55450         /* The list is being searched and this trunk page is the page
55451         ** to allocate, regardless of whether it has leaves.
55452         */
55453         *pPgno = iTrunk;
55454         *ppPage = pTrunk;
55455         searchList = 0;
55456         rc = sqlite3PagerWrite(pTrunk->pDbPage);
55457         if( rc ){
55458           goto end_allocate_page;
55459         }
55460         if( k==0 ){
55461           if( !pPrevTrunk ){
55462             memcpy(&pPage1->aData[32], &pTrunk->aData[0], 4);
55463           }else{
55464             rc = sqlite3PagerWrite(pPrevTrunk->pDbPage);
55465             if( rc!=SQLITE_OK ){
55466               goto end_allocate_page;
55467             }
55468             memcpy(&pPrevTrunk->aData[0], &pTrunk->aData[0], 4);
55469           }
55470         }else{
55471           /* The trunk page is required by the caller but it contains 
55472           ** pointers to free-list leaves. The first leaf becomes a trunk
55473           ** page in this case.
55474           */
55475           MemPage *pNewTrunk;
55476           Pgno iNewTrunk = get4byte(&pTrunk->aData[8]);
55477           if( iNewTrunk>mxPage ){ 
55478             rc = SQLITE_CORRUPT_BKPT;
55479             goto end_allocate_page;
55480           }
55481           testcase( iNewTrunk==mxPage );
55482           rc = btreeGetPage(pBt, iNewTrunk, &pNewTrunk, 0);
55483           if( rc!=SQLITE_OK ){
55484             goto end_allocate_page;
55485           }
55486           rc = sqlite3PagerWrite(pNewTrunk->pDbPage);
55487           if( rc!=SQLITE_OK ){
55488             releasePage(pNewTrunk);
55489             goto end_allocate_page;
55490           }
55491           memcpy(&pNewTrunk->aData[0], &pTrunk->aData[0], 4);
55492           put4byte(&pNewTrunk->aData[4], k-1);
55493           memcpy(&pNewTrunk->aData[8], &pTrunk->aData[12], (k-1)*4);
55494           releasePage(pNewTrunk);
55495           if( !pPrevTrunk ){
55496             assert( sqlite3PagerIswriteable(pPage1->pDbPage) );
55497             put4byte(&pPage1->aData[32], iNewTrunk);
55498           }else{
55499             rc = sqlite3PagerWrite(pPrevTrunk->pDbPage);
55500             if( rc ){
55501               goto end_allocate_page;
55502             }
55503             put4byte(&pPrevTrunk->aData[0], iNewTrunk);
55504           }
55505         }
55506         pTrunk = 0;
55507         TRACE(("ALLOCATE: %d trunk - %d free pages left\n", *pPgno, n-1));
55508 #endif
55509       }else if( k>0 ){
55510         /* Extract a leaf from the trunk */
55511         u32 closest;
55512         Pgno iPage;
55513         unsigned char *aData = pTrunk->aData;
55514         if( nearby>0 ){
55515           u32 i;
55516           closest = 0;
55517           if( eMode==BTALLOC_LE ){
55518             for(i=0; i<k; i++){
55519               iPage = get4byte(&aData[8+i*4]);
55520               if( iPage<=nearby ){
55521                 closest = i;
55522                 break;
55523               }
55524             }
55525           }else{
55526             int dist;
55527             dist = sqlite3AbsInt32(get4byte(&aData[8]) - nearby);
55528             for(i=1; i<k; i++){
55529               int d2 = sqlite3AbsInt32(get4byte(&aData[8+i*4]) - nearby);
55530               if( d2<dist ){
55531                 closest = i;
55532                 dist = d2;
55533               }
55534             }
55535           }
55536         }else{
55537           closest = 0;
55538         }
55539 
55540         iPage = get4byte(&aData[8+closest*4]);
55541         testcase( iPage==mxPage );
55542         if( iPage>mxPage ){
55543           rc = SQLITE_CORRUPT_BKPT;
55544           goto end_allocate_page;
55545         }
55546         testcase( iPage==mxPage );
55547         if( !searchList 
55548          || (iPage==nearby || (iPage<nearby && eMode==BTALLOC_LE)) 
55549         ){
55550           int noContent;
55551           *pPgno = iPage;
55552           TRACE(("ALLOCATE: %d was leaf %d of %d on trunk %d"
55553                  ": %d more free pages\n",
55554                  *pPgno, closest+1, k, pTrunk->pgno, n-1));
55555           rc = sqlite3PagerWrite(pTrunk->pDbPage);
55556           if( rc ) goto end_allocate_page;
55557           if( closest<k-1 ){
55558             memcpy(&aData[8+closest*4], &aData[4+k*4], 4);
55559           }
55560           put4byte(&aData[4], k-1);
55561           noContent = !btreeGetHasContent(pBt, *pPgno) ? PAGER_GET_NOCONTENT : 0;
55562           rc = btreeGetPage(pBt, *pPgno, ppPage, noContent);
55563           if( rc==SQLITE_OK ){
55564             rc = sqlite3PagerWrite((*ppPage)->pDbPage);
55565             if( rc!=SQLITE_OK ){
55566               releasePage(*ppPage);
55567             }
55568           }
55569           searchList = 0;
55570         }
55571       }
55572       releasePage(pPrevTrunk);
55573       pPrevTrunk = 0;
55574     }while( searchList );
55575   }else{
55576     /* There are no pages on the freelist, so append a new page to the
55577     ** database image.
55578     **
55579     ** Normally, new pages allocated by this block can be requested from the
55580     ** pager layer with the 'no-content' flag set. This prevents the pager
55581     ** from trying to read the pages content from disk. However, if the
55582     ** current transaction has already run one or more incremental-vacuum
55583     ** steps, then the page we are about to allocate may contain content
55584     ** that is required in the event of a rollback. In this case, do
55585     ** not set the no-content flag. This causes the pager to load and journal
55586     ** the current page content before overwriting it.
55587     **
55588     ** Note that the pager will not actually attempt to load or journal 
55589     ** content for any page that really does lie past the end of the database
55590     ** file on disk. So the effects of disabling the no-content optimization
55591     ** here are confined to those pages that lie between the end of the
55592     ** database image and the end of the database file.
55593     */
55594     int bNoContent = (0==IfNotOmitAV(pBt->bDoTruncate)) ? PAGER_GET_NOCONTENT : 0;
55595 
55596     rc = sqlite3PagerWrite(pBt->pPage1->pDbPage);
55597     if( rc ) return rc;
55598     pBt->nPage++;
55599     if( pBt->nPage==PENDING_BYTE_PAGE(pBt) ) pBt->nPage++;
55600 
55601 #ifndef SQLITE_OMIT_AUTOVACUUM
55602     if( pBt->autoVacuum && PTRMAP_ISPAGE(pBt, pBt->nPage) ){
55603       /* If *pPgno refers to a pointer-map page, allocate two new pages
55604       ** at the end of the file instead of one. The first allocated page
55605       ** becomes a new pointer-map page, the second is used by the caller.
55606       */
55607       MemPage *pPg = 0;
55608       TRACE(("ALLOCATE: %d from end of file (pointer-map page)\n", pBt->nPage));
55609       assert( pBt->nPage!=PENDING_BYTE_PAGE(pBt) );
55610       rc = btreeGetPage(pBt, pBt->nPage, &pPg, bNoContent);
55611       if( rc==SQLITE_OK ){
55612         rc = sqlite3PagerWrite(pPg->pDbPage);
55613         releasePage(pPg);
55614       }
55615       if( rc ) return rc;
55616       pBt->nPage++;
55617       if( pBt->nPage==PENDING_BYTE_PAGE(pBt) ){ pBt->nPage++; }
55618     }
55619 #endif
55620     put4byte(28 + (u8*)pBt->pPage1->aData, pBt->nPage);
55621     *pPgno = pBt->nPage;
55622 
55623     assert( *pPgno!=PENDING_BYTE_PAGE(pBt) );
55624     rc = btreeGetPage(pBt, *pPgno, ppPage, bNoContent);
55625     if( rc ) return rc;
55626     rc = sqlite3PagerWrite((*ppPage)->pDbPage);
55627     if( rc!=SQLITE_OK ){
55628       releasePage(*ppPage);
55629     }
55630     TRACE(("ALLOCATE: %d from end of file\n", *pPgno));
55631   }
55632 
55633   assert( *pPgno!=PENDING_BYTE_PAGE(pBt) );
55634 
55635 end_allocate_page:
55636   releasePage(pTrunk);
55637   releasePage(pPrevTrunk);
55638   if( rc==SQLITE_OK ){
55639     if( sqlite3PagerPageRefcount((*ppPage)->pDbPage)>1 ){
55640       releasePage(*ppPage);
55641       return SQLITE_CORRUPT_BKPT;
55642     }
55643     (*ppPage)->isInit = 0;
55644   }else{
55645     *ppPage = 0;
55646   }
55647   assert( rc!=SQLITE_OK || sqlite3PagerIswriteable((*ppPage)->pDbPage) );
55648   return rc;
55649 }
55650 
55651 /*
55652 ** This function is used to add page iPage to the database file free-list. 
55653 ** It is assumed that the page is not already a part of the free-list.
55654 **
55655 ** The value passed as the second argument to this function is optional.
55656 ** If the caller happens to have a pointer to the MemPage object 
55657 ** corresponding to page iPage handy, it may pass it as the second value. 
55658 ** Otherwise, it may pass NULL.
55659 **
55660 ** If a pointer to a MemPage object is passed as the second argument,
55661 ** its reference count is not altered by this function.
55662 */
55663 static int freePage2(BtShared *pBt, MemPage *pMemPage, Pgno iPage){
55664   MemPage *pTrunk = 0;                /* Free-list trunk page */
55665   Pgno iTrunk = 0;                    /* Page number of free-list trunk page */ 
55666   MemPage *pPage1 = pBt->pPage1;      /* Local reference to page 1 */
55667   MemPage *pPage;                     /* Page being freed. May be NULL. */
55668   int rc;                             /* Return Code */
55669   int nFree;                          /* Initial number of pages on free-list */
55670 
55671   assert( sqlite3_mutex_held(pBt->mutex) );
55672   assert( iPage>1 );
55673   assert( !pMemPage || pMemPage->pgno==iPage );
55674 
55675   if( pMemPage ){
55676     pPage = pMemPage;
55677     sqlite3PagerRef(pPage->pDbPage);
55678   }else{
55679     pPage = btreePageLookup(pBt, iPage);
55680   }
55681 
55682   /* Increment the free page count on pPage1 */
55683   rc = sqlite3PagerWrite(pPage1->pDbPage);
55684   if( rc ) goto freepage_out;
55685   nFree = get4byte(&pPage1->aData[36]);
55686   put4byte(&pPage1->aData[36], nFree+1);
55687 
55688   if( pBt->btsFlags & BTS_SECURE_DELETE ){
55689     /* If the secure_delete option is enabled, then
55690     ** always fully overwrite deleted information with zeros.
55691     */
55692     if( (!pPage && ((rc = btreeGetPage(pBt, iPage, &pPage, 0))!=0) )
55693      ||            ((rc = sqlite3PagerWrite(pPage->pDbPage))!=0)
55694     ){
55695       goto freepage_out;
55696     }
55697     memset(pPage->aData, 0, pPage->pBt->pageSize);
55698   }
55699 
55700   /* If the database supports auto-vacuum, write an entry in the pointer-map
55701   ** to indicate that the page is free.
55702   */
55703   if( ISAUTOVACUUM ){
55704     ptrmapPut(pBt, iPage, PTRMAP_FREEPAGE, 0, &rc);
55705     if( rc ) goto freepage_out;
55706   }
55707 
55708   /* Now manipulate the actual database free-list structure. There are two
55709   ** possibilities. If the free-list is currently empty, or if the first
55710   ** trunk page in the free-list is full, then this page will become a
55711   ** new free-list trunk page. Otherwise, it will become a leaf of the
55712   ** first trunk page in the current free-list. This block tests if it
55713   ** is possible to add the page as a new free-list leaf.
55714   */
55715   if( nFree!=0 ){
55716     u32 nLeaf;                /* Initial number of leaf cells on trunk page */
55717 
55718     iTrunk = get4byte(&pPage1->aData[32]);
55719     rc = btreeGetPage(pBt, iTrunk, &pTrunk, 0);
55720     if( rc!=SQLITE_OK ){
55721       goto freepage_out;
55722     }
55723 
55724     nLeaf = get4byte(&pTrunk->aData[4]);
55725     assert( pBt->usableSize>32 );
55726     if( nLeaf > (u32)pBt->usableSize/4 - 2 ){
55727       rc = SQLITE_CORRUPT_BKPT;
55728       goto freepage_out;
55729     }
55730     if( nLeaf < (u32)pBt->usableSize/4 - 8 ){
55731       /* In this case there is room on the trunk page to insert the page
55732       ** being freed as a new leaf.
55733       **
55734       ** Note that the trunk page is not really full until it contains
55735       ** usableSize/4 - 2 entries, not usableSize/4 - 8 entries as we have
55736       ** coded.  But due to a coding error in versions of SQLite prior to
55737       ** 3.6.0, databases with freelist trunk pages holding more than
55738       ** usableSize/4 - 8 entries will be reported as corrupt.  In order
55739       ** to maintain backwards compatibility with older versions of SQLite,
55740       ** we will continue to restrict the number of entries to usableSize/4 - 8
55741       ** for now.  At some point in the future (once everyone has upgraded
55742       ** to 3.6.0 or later) we should consider fixing the conditional above
55743       ** to read "usableSize/4-2" instead of "usableSize/4-8".
55744       */
55745       rc = sqlite3PagerWrite(pTrunk->pDbPage);
55746       if( rc==SQLITE_OK ){
55747         put4byte(&pTrunk->aData[4], nLeaf+1);
55748         put4byte(&pTrunk->aData[8+nLeaf*4], iPage);
55749         if( pPage && (pBt->btsFlags & BTS_SECURE_DELETE)==0 ){
55750           sqlite3PagerDontWrite(pPage->pDbPage);
55751         }
55752         rc = btreeSetHasContent(pBt, iPage);
55753       }
55754       TRACE(("FREE-PAGE: %d leaf on trunk page %d\n",pPage->pgno,pTrunk->pgno));
55755       goto freepage_out;
55756     }
55757   }
55758 
55759   /* If control flows to this point, then it was not possible to add the
55760   ** the page being freed as a leaf page of the first trunk in the free-list.
55761   ** Possibly because the free-list is empty, or possibly because the 
55762   ** first trunk in the free-list is full. Either way, the page being freed
55763   ** will become the new first trunk page in the free-list.
55764   */
55765   if( pPage==0 && SQLITE_OK!=(rc = btreeGetPage(pBt, iPage, &pPage, 0)) ){
55766     goto freepage_out;
55767   }
55768   rc = sqlite3PagerWrite(pPage->pDbPage);
55769   if( rc!=SQLITE_OK ){
55770     goto freepage_out;
55771   }
55772   put4byte(pPage->aData, iTrunk);
55773   put4byte(&pPage->aData[4], 0);
55774   put4byte(&pPage1->aData[32], iPage);
55775   TRACE(("FREE-PAGE: %d new trunk page replacing %d\n", pPage->pgno, iTrunk));
55776 
55777 freepage_out:
55778   if( pPage ){
55779     pPage->isInit = 0;
55780   }
55781   releasePage(pPage);
55782   releasePage(pTrunk);
55783   return rc;
55784 }
55785 static void freePage(MemPage *pPage, int *pRC){
55786   if( (*pRC)==SQLITE_OK ){
55787     *pRC = freePage2(pPage->pBt, pPage, pPage->pgno);
55788   }
55789 }
55790 
55791 /*
55792 ** Free any overflow pages associated with the given Cell.
55793 */
55794 static int clearCell(MemPage *pPage, unsigned char *pCell){
55795   BtShared *pBt = pPage->pBt;
55796   CellInfo info;
55797   Pgno ovflPgno;
55798   int rc;
55799   int nOvfl;
55800   u32 ovflPageSize;
55801 
55802   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
55803   btreeParseCellPtr(pPage, pCell, &info);
55804   if( info.iOverflow==0 ){
55805     return SQLITE_OK;  /* No overflow pages. Return without doing anything */
55806   }
55807   if( pCell+info.iOverflow+3 > pPage->aData+pPage->maskPage ){
55808     return SQLITE_CORRUPT_BKPT;  /* Cell extends past end of page */
55809   }
55810   ovflPgno = get4byte(&pCell[info.iOverflow]);
55811   assert( pBt->usableSize > 4 );
55812   ovflPageSize = pBt->usableSize - 4;
55813   nOvfl = (info.nPayload - info.nLocal + ovflPageSize - 1)/ovflPageSize;
55814   assert( ovflPgno==0 || nOvfl>0 );
55815   while( nOvfl-- ){
55816     Pgno iNext = 0;
55817     MemPage *pOvfl = 0;
55818     if( ovflPgno<2 || ovflPgno>btreePagecount(pBt) ){
55819       /* 0 is not a legal page number and page 1 cannot be an 
55820       ** overflow page. Therefore if ovflPgno<2 or past the end of the 
55821       ** file the database must be corrupt. */
55822       return SQLITE_CORRUPT_BKPT;
55823     }
55824     if( nOvfl ){
55825       rc = getOverflowPage(pBt, ovflPgno, &pOvfl, &iNext);
55826       if( rc ) return rc;
55827     }
55828 
55829     if( ( pOvfl || ((pOvfl = btreePageLookup(pBt, ovflPgno))!=0) )
55830      && sqlite3PagerPageRefcount(pOvfl->pDbPage)!=1
55831     ){
55832       /* There is no reason any cursor should have an outstanding reference 
55833       ** to an overflow page belonging to a cell that is being deleted/updated.
55834       ** So if there exists more than one reference to this page, then it 
55835       ** must not really be an overflow page and the database must be corrupt. 
55836       ** It is helpful to detect this before calling freePage2(), as 
55837       ** freePage2() may zero the page contents if secure-delete mode is
55838       ** enabled. If this 'overflow' page happens to be a page that the
55839       ** caller is iterating through or using in some other way, this
55840       ** can be problematic.
55841       */
55842       rc = SQLITE_CORRUPT_BKPT;
55843     }else{
55844       rc = freePage2(pBt, pOvfl, ovflPgno);
55845     }
55846 
55847     if( pOvfl ){
55848       sqlite3PagerUnref(pOvfl->pDbPage);
55849     }
55850     if( rc ) return rc;
55851     ovflPgno = iNext;
55852   }
55853   return SQLITE_OK;
55854 }
55855 
55856 /*
55857 ** Create the byte sequence used to represent a cell on page pPage
55858 ** and write that byte sequence into pCell[].  Overflow pages are
55859 ** allocated and filled in as necessary.  The calling procedure
55860 ** is responsible for making sure sufficient space has been allocated
55861 ** for pCell[].
55862 **
55863 ** Note that pCell does not necessary need to point to the pPage->aData
55864 ** area.  pCell might point to some temporary storage.  The cell will
55865 ** be constructed in this temporary area then copied into pPage->aData
55866 ** later.
55867 */
55868 static int fillInCell(
55869   MemPage *pPage,                /* The page that contains the cell */
55870   unsigned char *pCell,          /* Complete text of the cell */
55871   const void *pKey, i64 nKey,    /* The key */
55872   const void *pData,int nData,   /* The data */
55873   int nZero,                     /* Extra zero bytes to append to pData */
55874   int *pnSize                    /* Write cell size here */
55875 ){
55876   int nPayload;
55877   const u8 *pSrc;
55878   int nSrc, n, rc;
55879   int spaceLeft;
55880   MemPage *pOvfl = 0;
55881   MemPage *pToRelease = 0;
55882   unsigned char *pPrior;
55883   unsigned char *pPayload;
55884   BtShared *pBt = pPage->pBt;
55885   Pgno pgnoOvfl = 0;
55886   int nHeader;
55887   CellInfo info;
55888 
55889   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
55890 
55891   /* pPage is not necessarily writeable since pCell might be auxiliary
55892   ** buffer space that is separate from the pPage buffer area */
55893   assert( pCell<pPage->aData || pCell>=&pPage->aData[pBt->pageSize]
55894             || sqlite3PagerIswriteable(pPage->pDbPage) );
55895 
55896   /* Fill in the header. */
55897   nHeader = 0;
55898   if( !pPage->leaf ){
55899     nHeader += 4;
55900   }
55901   if( pPage->hasData ){
55902     nHeader += putVarint(&pCell[nHeader], nData+nZero);
55903   }else{
55904     nData = nZero = 0;
55905   }
55906   nHeader += putVarint(&pCell[nHeader], *(u64*)&nKey);
55907   btreeParseCellPtr(pPage, pCell, &info);
55908   assert( info.nHeader==nHeader );
55909   assert( info.nKey==nKey );
55910   assert( info.nData==(u32)(nData+nZero) );
55911   
55912   /* Fill in the payload */
55913   nPayload = nData + nZero;
55914   if( pPage->intKey ){
55915     pSrc = pData;
55916     nSrc = nData;
55917     nData = 0;
55918   }else{ 
55919     if( NEVER(nKey>0x7fffffff || pKey==0) ){
55920       return SQLITE_CORRUPT_BKPT;
55921     }
55922     nPayload += (int)nKey;
55923     pSrc = pKey;
55924     nSrc = (int)nKey;
55925   }
55926   *pnSize = info.nSize;
55927   spaceLeft = info.nLocal;
55928   pPayload = &pCell[nHeader];
55929   pPrior = &pCell[info.iOverflow];
55930 
55931   while( nPayload>0 ){
55932     if( spaceLeft==0 ){
55933 #ifndef SQLITE_OMIT_AUTOVACUUM
55934       Pgno pgnoPtrmap = pgnoOvfl; /* Overflow page pointer-map entry page */
55935       if( pBt->autoVacuum ){
55936         do{
55937           pgnoOvfl++;
55938         } while( 
55939           PTRMAP_ISPAGE(pBt, pgnoOvfl) || pgnoOvfl==PENDING_BYTE_PAGE(pBt) 
55940         );
55941       }
55942 #endif
55943       rc = allocateBtreePage(pBt, &pOvfl, &pgnoOvfl, pgnoOvfl, 0);
55944 #ifndef SQLITE_OMIT_AUTOVACUUM
55945       /* If the database supports auto-vacuum, and the second or subsequent
55946       ** overflow page is being allocated, add an entry to the pointer-map
55947       ** for that page now. 
55948       **
55949       ** If this is the first overflow page, then write a partial entry 
55950       ** to the pointer-map. If we write nothing to this pointer-map slot,
55951       ** then the optimistic overflow chain processing in clearCell()
55952       ** may misinterpret the uninitialized values and delete the
55953       ** wrong pages from the database.
55954       */
55955       if( pBt->autoVacuum && rc==SQLITE_OK ){
55956         u8 eType = (pgnoPtrmap?PTRMAP_OVERFLOW2:PTRMAP_OVERFLOW1);
55957         ptrmapPut(pBt, pgnoOvfl, eType, pgnoPtrmap, &rc);
55958         if( rc ){
55959           releasePage(pOvfl);
55960         }
55961       }
55962 #endif
55963       if( rc ){
55964         releasePage(pToRelease);
55965         return rc;
55966       }
55967 
55968       /* If pToRelease is not zero than pPrior points into the data area
55969       ** of pToRelease.  Make sure pToRelease is still writeable. */
55970       assert( pToRelease==0 || sqlite3PagerIswriteable(pToRelease->pDbPage) );
55971 
55972       /* If pPrior is part of the data area of pPage, then make sure pPage
55973       ** is still writeable */
55974       assert( pPrior<pPage->aData || pPrior>=&pPage->aData[pBt->pageSize]
55975             || sqlite3PagerIswriteable(pPage->pDbPage) );
55976 
55977       put4byte(pPrior, pgnoOvfl);
55978       releasePage(pToRelease);
55979       pToRelease = pOvfl;
55980       pPrior = pOvfl->aData;
55981       put4byte(pPrior, 0);
55982       pPayload = &pOvfl->aData[4];
55983       spaceLeft = pBt->usableSize - 4;
55984     }
55985     n = nPayload;
55986     if( n>spaceLeft ) n = spaceLeft;
55987 
55988     /* If pToRelease is not zero than pPayload points into the data area
55989     ** of pToRelease.  Make sure pToRelease is still writeable. */
55990     assert( pToRelease==0 || sqlite3PagerIswriteable(pToRelease->pDbPage) );
55991 
55992     /* If pPayload is part of the data area of pPage, then make sure pPage
55993     ** is still writeable */
55994     assert( pPayload<pPage->aData || pPayload>=&pPage->aData[pBt->pageSize]
55995             || sqlite3PagerIswriteable(pPage->pDbPage) );
55996 
55997     if( nSrc>0 ){
55998       if( n>nSrc ) n = nSrc;
55999       assert( pSrc );
56000       memcpy(pPayload, pSrc, n);
56001     }else{
56002       memset(pPayload, 0, n);
56003     }
56004     nPayload -= n;
56005     pPayload += n;
56006     pSrc += n;
56007     nSrc -= n;
56008     spaceLeft -= n;
56009     if( nSrc==0 ){
56010       nSrc = nData;
56011       pSrc = pData;
56012     }
56013   }
56014   releasePage(pToRelease);
56015   return SQLITE_OK;
56016 }
56017 
56018 /*
56019 ** Remove the i-th cell from pPage.  This routine effects pPage only.
56020 ** The cell content is not freed or deallocated.  It is assumed that
56021 ** the cell content has been copied someplace else.  This routine just
56022 ** removes the reference to the cell from pPage.
56023 **
56024 ** "sz" must be the number of bytes in the cell.
56025 */
56026 static void dropCell(MemPage *pPage, int idx, int sz, int *pRC){
56027   u32 pc;         /* Offset to cell content of cell being deleted */
56028   u8 *data;       /* pPage->aData */
56029   u8 *ptr;        /* Used to move bytes around within data[] */
56030   u8 *endPtr;     /* End of loop */
56031   int rc;         /* The return code */
56032   int hdr;        /* Beginning of the header.  0 most pages.  100 page 1 */
56033 
56034   if( *pRC ) return;
56035 
56036   assert( idx>=0 && idx<pPage->nCell );
56037   assert( sz==cellSize(pPage, idx) );
56038   assert( sqlite3PagerIswriteable(pPage->pDbPage) );
56039   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
56040   data = pPage->aData;
56041   ptr = &pPage->aCellIdx[2*idx];
56042   pc = get2byte(ptr);
56043   hdr = pPage->hdrOffset;
56044   testcase( pc==get2byte(&data[hdr+5]) );
56045   testcase( pc+sz==pPage->pBt->usableSize );
56046   if( pc < (u32)get2byte(&data[hdr+5]) || pc+sz > pPage->pBt->usableSize ){
56047     *pRC = SQLITE_CORRUPT_BKPT;
56048     return;
56049   }
56050   rc = freeSpace(pPage, pc, sz);
56051   if( rc ){
56052     *pRC = rc;
56053     return;
56054   }
56055   endPtr = &pPage->aCellIdx[2*pPage->nCell - 2];
56056   assert( (SQLITE_PTR_TO_INT(ptr)&1)==0 );  /* ptr is always 2-byte aligned */
56057   while( ptr<endPtr ){
56058     *(u16*)ptr = *(u16*)&ptr[2];
56059     ptr += 2;
56060   }
56061   pPage->nCell--;
56062   put2byte(&data[hdr+3], pPage->nCell);
56063   pPage->nFree += 2;
56064 }
56065 
56066 /*
56067 ** Insert a new cell on pPage at cell index "i".  pCell points to the
56068 ** content of the cell.
56069 **
56070 ** If the cell content will fit on the page, then put it there.  If it
56071 ** will not fit, then make a copy of the cell content into pTemp if
56072 ** pTemp is not null.  Regardless of pTemp, allocate a new entry
56073 ** in pPage->apOvfl[] and make it point to the cell content (either
56074 ** in pTemp or the original pCell) and also record its index. 
56075 ** Allocating a new entry in pPage->aCell[] implies that 
56076 ** pPage->nOverflow is incremented.
56077 **
56078 ** If nSkip is non-zero, then do not copy the first nSkip bytes of the
56079 ** cell. The caller will overwrite them after this function returns. If
56080 ** nSkip is non-zero, then pCell may not point to an invalid memory location 
56081 ** (but pCell+nSkip is always valid).
56082 */
56083 static void insertCell(
56084   MemPage *pPage,   /* Page into which we are copying */
56085   int i,            /* New cell becomes the i-th cell of the page */
56086   u8 *pCell,        /* Content of the new cell */
56087   int sz,           /* Bytes of content in pCell */
56088   u8 *pTemp,        /* Temp storage space for pCell, if needed */
56089   Pgno iChild,      /* If non-zero, replace first 4 bytes with this value */
56090   int *pRC          /* Read and write return code from here */
56091 ){
56092   int idx = 0;      /* Where to write new cell content in data[] */
56093   int j;            /* Loop counter */
56094   int end;          /* First byte past the last cell pointer in data[] */
56095   int ins;          /* Index in data[] where new cell pointer is inserted */
56096   int cellOffset;   /* Address of first cell pointer in data[] */
56097   u8 *data;         /* The content of the whole page */
56098   u8 *ptr;          /* Used for moving information around in data[] */
56099   u8 *endPtr;       /* End of the loop */
56100 
56101   int nSkip = (iChild ? 4 : 0);
56102 
56103   if( *pRC ) return;
56104 
56105   assert( i>=0 && i<=pPage->nCell+pPage->nOverflow );
56106   assert( pPage->nCell<=MX_CELL(pPage->pBt) && MX_CELL(pPage->pBt)<=10921 );
56107   assert( pPage->nOverflow<=ArraySize(pPage->apOvfl) );
56108   assert( ArraySize(pPage->apOvfl)==ArraySize(pPage->aiOvfl) );
56109   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
56110   /* The cell should normally be sized correctly.  However, when moving a
56111   ** malformed cell from a leaf page to an interior page, if the cell size
56112   ** wanted to be less than 4 but got rounded up to 4 on the leaf, then size
56113   ** might be less than 8 (leaf-size + pointer) on the interior node.  Hence
56114   ** the term after the || in the following assert(). */
56115   assert( sz==cellSizePtr(pPage, pCell) || (sz==8 && iChild>0) );
56116   if( pPage->nOverflow || sz+2>pPage->nFree ){
56117     if( pTemp ){
56118       memcpy(pTemp+nSkip, pCell+nSkip, sz-nSkip);
56119       pCell = pTemp;
56120     }
56121     if( iChild ){
56122       put4byte(pCell, iChild);
56123     }
56124     j = pPage->nOverflow++;
56125     assert( j<(int)(sizeof(pPage->apOvfl)/sizeof(pPage->apOvfl[0])) );
56126     pPage->apOvfl[j] = pCell;
56127     pPage->aiOvfl[j] = (u16)i;
56128   }else{
56129     int rc = sqlite3PagerWrite(pPage->pDbPage);
56130     if( rc!=SQLITE_OK ){
56131       *pRC = rc;
56132       return;
56133     }
56134     assert( sqlite3PagerIswriteable(pPage->pDbPage) );
56135     data = pPage->aData;
56136     cellOffset = pPage->cellOffset;
56137     end = cellOffset + 2*pPage->nCell;
56138     ins = cellOffset + 2*i;
56139     rc = allocateSpace(pPage, sz, &idx);
56140     if( rc ){ *pRC = rc; return; }
56141     /* The allocateSpace() routine guarantees the following two properties
56142     ** if it returns success */
56143     assert( idx >= end+2 );
56144     assert( idx+sz <= (int)pPage->pBt->usableSize );
56145     pPage->nCell++;
56146     pPage->nFree -= (u16)(2 + sz);
56147     memcpy(&data[idx+nSkip], pCell+nSkip, sz-nSkip);
56148     if( iChild ){
56149       put4byte(&data[idx], iChild);
56150     }
56151     ptr = &data[end];
56152     endPtr = &data[ins];
56153     assert( (SQLITE_PTR_TO_INT(ptr)&1)==0 );  /* ptr is always 2-byte aligned */
56154     while( ptr>endPtr ){
56155       *(u16*)ptr = *(u16*)&ptr[-2];
56156       ptr -= 2;
56157     }
56158     put2byte(&data[ins], idx);
56159     put2byte(&data[pPage->hdrOffset+3], pPage->nCell);
56160 #ifndef SQLITE_OMIT_AUTOVACUUM
56161     if( pPage->pBt->autoVacuum ){
56162       /* The cell may contain a pointer to an overflow page. If so, write
56163       ** the entry for the overflow page into the pointer map.
56164       */
56165       ptrmapPutOvflPtr(pPage, pCell, pRC);
56166     }
56167 #endif
56168   }
56169 }
56170 
56171 /*
56172 ** Add a list of cells to a page.  The page should be initially empty.
56173 ** The cells are guaranteed to fit on the page.
56174 */
56175 static void assemblePage(
56176   MemPage *pPage,   /* The page to be assemblied */
56177   int nCell,        /* The number of cells to add to this page */
56178   u8 **apCell,      /* Pointers to cell bodies */
56179   u16 *aSize        /* Sizes of the cells */
56180 ){
56181   int i;            /* Loop counter */
56182   u8 *pCellptr;     /* Address of next cell pointer */
56183   int cellbody;     /* Address of next cell body */
56184   u8 * const data = pPage->aData;             /* Pointer to data for pPage */
56185   const int hdr = pPage->hdrOffset;           /* Offset of header on pPage */
56186   const int nUsable = pPage->pBt->usableSize; /* Usable size of page */
56187 
56188   assert( pPage->nOverflow==0 );
56189   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
56190   assert( nCell>=0 && nCell<=(int)MX_CELL(pPage->pBt)
56191             && (int)MX_CELL(pPage->pBt)<=10921);
56192   assert( sqlite3PagerIswriteable(pPage->pDbPage) );
56193 
56194   /* Check that the page has just been zeroed by zeroPage() */
56195   assert( pPage->nCell==0 );
56196   assert( get2byteNotZero(&data[hdr+5])==nUsable );
56197 
56198   pCellptr = &pPage->aCellIdx[nCell*2];
56199   cellbody = nUsable;
56200   for(i=nCell-1; i>=0; i--){
56201     u16 sz = aSize[i];
56202     pCellptr -= 2;
56203     cellbody -= sz;
56204     put2byte(pCellptr, cellbody);
56205     memcpy(&data[cellbody], apCell[i], sz);
56206   }
56207   put2byte(&data[hdr+3], nCell);
56208   put2byte(&data[hdr+5], cellbody);
56209   pPage->nFree -= (nCell*2 + nUsable - cellbody);
56210   pPage->nCell = (u16)nCell;
56211 }
56212 
56213 /*
56214 ** The following parameters determine how many adjacent pages get involved
56215 ** in a balancing operation.  NN is the number of neighbors on either side
56216 ** of the page that participate in the balancing operation.  NB is the
56217 ** total number of pages that participate, including the target page and
56218 ** NN neighbors on either side.
56219 **
56220 ** The minimum value of NN is 1 (of course).  Increasing NN above 1
56221 ** (to 2 or 3) gives a modest improvement in SELECT and DELETE performance
56222 ** in exchange for a larger degradation in INSERT and UPDATE performance.
56223 ** The value of NN appears to give the best results overall.
56224 */
56225 #define NN 1             /* Number of neighbors on either side of pPage */
56226 #define NB (NN*2+1)      /* Total pages involved in the balance */
56227 
56228 
56229 #ifndef SQLITE_OMIT_QUICKBALANCE
56230 /*
56231 ** This version of balance() handles the common special case where
56232 ** a new entry is being inserted on the extreme right-end of the
56233 ** tree, in other words, when the new entry will become the largest
56234 ** entry in the tree.
56235 **
56236 ** Instead of trying to balance the 3 right-most leaf pages, just add
56237 ** a new page to the right-hand side and put the one new entry in
56238 ** that page.  This leaves the right side of the tree somewhat
56239 ** unbalanced.  But odds are that we will be inserting new entries
56240 ** at the end soon afterwards so the nearly empty page will quickly
56241 ** fill up.  On average.
56242 **
56243 ** pPage is the leaf page which is the right-most page in the tree.
56244 ** pParent is its parent.  pPage must have a single overflow entry
56245 ** which is also the right-most entry on the page.
56246 **
56247 ** The pSpace buffer is used to store a temporary copy of the divider
56248 ** cell that will be inserted into pParent. Such a cell consists of a 4
56249 ** byte page number followed by a variable length integer. In other
56250 ** words, at most 13 bytes. Hence the pSpace buffer must be at
56251 ** least 13 bytes in size.
56252 */
56253 static int balance_quick(MemPage *pParent, MemPage *pPage, u8 *pSpace){
56254   BtShared *const pBt = pPage->pBt;    /* B-Tree Database */
56255   MemPage *pNew;                       /* Newly allocated page */
56256   int rc;                              /* Return Code */
56257   Pgno pgnoNew;                        /* Page number of pNew */
56258 
56259   assert( sqlite3_mutex_held(pPage->pBt->mutex) );
56260   assert( sqlite3PagerIswriteable(pParent->pDbPage) );
56261   assert( pPage->nOverflow==1 );
56262 
56263   /* This error condition is now caught prior to reaching this function */
56264   if( pPage->nCell==0 ) return SQLITE_CORRUPT_BKPT;
56265 
56266   /* Allocate a new page. This page will become the right-sibling of 
56267   ** pPage. Make the parent page writable, so that the new divider cell
56268   ** may be inserted. If both these operations are successful, proceed.
56269   */
56270   rc = allocateBtreePage(pBt, &pNew, &pgnoNew, 0, 0);
56271 
56272   if( rc==SQLITE_OK ){
56273 
56274     u8 *pOut = &pSpace[4];
56275     u8 *pCell = pPage->apOvfl[0];
56276     u16 szCell = cellSizePtr(pPage, pCell);
56277     u8 *pStop;
56278 
56279     assert( sqlite3PagerIswriteable(pNew->pDbPage) );
56280     assert( pPage->aData[0]==(PTF_INTKEY|PTF_LEAFDATA|PTF_LEAF) );
56281     zeroPage(pNew, PTF_INTKEY|PTF_LEAFDATA|PTF_LEAF);
56282     assemblePage(pNew, 1, &pCell, &szCell);
56283 
56284     /* If this is an auto-vacuum database, update the pointer map
56285     ** with entries for the new page, and any pointer from the 
56286     ** cell on the page to an overflow page. If either of these
56287     ** operations fails, the return code is set, but the contents
56288     ** of the parent page are still manipulated by thh code below.
56289     ** That is Ok, at this point the parent page is guaranteed to
56290     ** be marked as dirty. Returning an error code will cause a
56291     ** rollback, undoing any changes made to the parent page.
56292     */
56293     if( ISAUTOVACUUM ){
56294       ptrmapPut(pBt, pgnoNew, PTRMAP_BTREE, pParent->pgno, &rc);
56295       if( szCell>pNew->minLocal ){
56296         ptrmapPutOvflPtr(pNew, pCell, &rc);
56297       }
56298     }
56299   
56300     /* Create a divider cell to insert into pParent. The divider cell
56301     ** consists of a 4-byte page number (the page number of pPage) and
56302     ** a variable length key value (which must be the same value as the
56303     ** largest key on pPage).
56304     **
56305     ** To find the largest key value on pPage, first find the right-most 
56306     ** cell on pPage. The first two fields of this cell are the 
56307     ** record-length (a variable length integer at most 32-bits in size)
56308     ** and the key value (a variable length integer, may have any value).
56309     ** The first of the while(...) loops below skips over the record-length
56310     ** field. The second while(...) loop copies the key value from the
56311     ** cell on pPage into the pSpace buffer.
56312     */
56313     pCell = findCell(pPage, pPage->nCell-1);
56314     pStop = &pCell[9];
56315     while( (*(pCell++)&0x80) && pCell<pStop );
56316     pStop = &pCell[9];
56317     while( ((*(pOut++) = *(pCell++))&0x80) && pCell<pStop );
56318 
56319     /* Insert the new divider cell into pParent. */
56320     insertCell(pParent, pParent->nCell, pSpace, (int)(pOut-pSpace),
56321                0, pPage->pgno, &rc);
56322 
56323     /* Set the right-child pointer of pParent to point to the new page. */
56324     put4byte(&pParent->aData[pParent->hdrOffset+8], pgnoNew);
56325   
56326     /* Release the reference to the new page. */
56327     releasePage(pNew);
56328   }
56329 
56330   return rc;
56331 }
56332 #endif /* SQLITE_OMIT_QUICKBALANCE */
56333 
56334 #if 0
56335 /*
56336 ** This function does not contribute anything to the operation of SQLite.
56337 ** it is sometimes activated temporarily while debugging code responsible 
56338 ** for setting pointer-map entries.
56339 */
56340 static int ptrmapCheckPages(MemPage **apPage, int nPage){
56341   int i, j;
56342   for(i=0; i<nPage; i++){
56343     Pgno n;
56344     u8 e;
56345     MemPage *pPage = apPage[i];
56346     BtShared *pBt = pPage->pBt;
56347     assert( pPage->isInit );
56348 
56349     for(j=0; j<pPage->nCell; j++){
56350       CellInfo info;
56351       u8 *z;
56352      
56353       z = findCell(pPage, j);
56354       btreeParseCellPtr(pPage, z, &info);
56355       if( info.iOverflow ){
56356         Pgno ovfl = get4byte(&z[info.iOverflow]);
56357         ptrmapGet(pBt, ovfl, &e, &n);
56358         assert( n==pPage->pgno && e==PTRMAP_OVERFLOW1 );
56359       }
56360       if( !pPage->leaf ){
56361         Pgno child = get4byte(z);
56362         ptrmapGet(pBt, child, &e, &n);
56363         assert( n==pPage->pgno && e==PTRMAP_BTREE );
56364       }
56365     }
56366     if( !pPage->leaf ){
56367       Pgno child = get4byte(&pPage->aData[pPage->hdrOffset+8]);
56368       ptrmapGet(pBt, child, &e, &n);
56369       assert( n==pPage->pgno && e==PTRMAP_BTREE );
56370     }
56371   }
56372   return 1;
56373 }
56374 #endif
56375 
56376 /*
56377 ** This function is used to copy the contents of the b-tree node stored 
56378 ** on page pFrom to page pTo. If page pFrom was not a leaf page, then
56379 ** the pointer-map entries for each child page are updated so that the
56380 ** parent page stored in the pointer map is page pTo. If pFrom contained
56381 ** any cells with overflow page pointers, then the corresponding pointer
56382 ** map entries are also updated so that the parent page is page pTo.
56383 **
56384 ** If pFrom is currently carrying any overflow cells (entries in the
56385 ** MemPage.apOvfl[] array), they are not copied to pTo. 
56386 **
56387 ** Before returning, page pTo is reinitialized using btreeInitPage().
56388 **
56389 ** The performance of this function is not critical. It is only used by 
56390 ** the balance_shallower() and balance_deeper() procedures, neither of
56391 ** which are called often under normal circumstances.
56392 */
56393 static void copyNodeContent(MemPage *pFrom, MemPage *pTo, int *pRC){
56394   if( (*pRC)==SQLITE_OK ){
56395     BtShared * const pBt = pFrom->pBt;
56396     u8 * const aFrom = pFrom->aData;
56397     u8 * const aTo = pTo->aData;
56398     int const iFromHdr = pFrom->hdrOffset;
56399     int const iToHdr = ((pTo->pgno==1) ? 100 : 0);
56400     int rc;
56401     int iData;
56402   
56403   
56404     assert( pFrom->isInit );
56405     assert( pFrom->nFree>=iToHdr );
56406     assert( get2byte(&aFrom[iFromHdr+5]) <= (int)pBt->usableSize );
56407   
56408     /* Copy the b-tree node content from page pFrom to page pTo. */
56409     iData = get2byte(&aFrom[iFromHdr+5]);
56410     memcpy(&aTo[iData], &aFrom[iData], pBt->usableSize-iData);
56411     memcpy(&aTo[iToHdr], &aFrom[iFromHdr], pFrom->cellOffset + 2*pFrom->nCell);
56412   
56413     /* Reinitialize page pTo so that the contents of the MemPage structure
56414     ** match the new data. The initialization of pTo can actually fail under
56415     ** fairly obscure circumstances, even though it is a copy of initialized 
56416     ** page pFrom.
56417     */
56418     pTo->isInit = 0;
56419     rc = btreeInitPage(pTo);
56420     if( rc!=SQLITE_OK ){
56421       *pRC = rc;
56422       return;
56423     }
56424   
56425     /* If this is an auto-vacuum database, update the pointer-map entries
56426     ** for any b-tree or overflow pages that pTo now contains the pointers to.
56427     */
56428     if( ISAUTOVACUUM ){
56429       *pRC = setChildPtrmaps(pTo);
56430     }
56431   }
56432 }
56433 
56434 /*
56435 ** This routine redistributes cells on the iParentIdx'th child of pParent
56436 ** (hereafter "the page") and up to 2 siblings so that all pages have about the
56437 ** same amount of free space. Usually a single sibling on either side of the
56438 ** page are used in the balancing, though both siblings might come from one
56439 ** side if the page is the first or last child of its parent. If the page 
56440 ** has fewer than 2 siblings (something which can only happen if the page
56441 ** is a root page or a child of a root page) then all available siblings
56442 ** participate in the balancing.
56443 **
56444 ** The number of siblings of the page might be increased or decreased by 
56445 ** one or two in an effort to keep pages nearly full but not over full. 
56446 **
56447 ** Note that when this routine is called, some of the cells on the page
56448 ** might not actually be stored in MemPage.aData[]. This can happen
56449 ** if the page is overfull. This routine ensures that all cells allocated
56450 ** to the page and its siblings fit into MemPage.aData[] before returning.
56451 **
56452 ** In the course of balancing the page and its siblings, cells may be
56453 ** inserted into or removed from the parent page (pParent). Doing so
56454 ** may cause the parent page to become overfull or underfull. If this
56455 ** happens, it is the responsibility of the caller to invoke the correct
56456 ** balancing routine to fix this problem (see the balance() routine). 
56457 **
56458 ** If this routine fails for any reason, it might leave the database
56459 ** in a corrupted state. So if this routine fails, the database should
56460 ** be rolled back.
56461 **
56462 ** The third argument to this function, aOvflSpace, is a pointer to a
56463 ** buffer big enough to hold one page. If while inserting cells into the parent
56464 ** page (pParent) the parent page becomes overfull, this buffer is
56465 ** used to store the parent's overflow cells. Because this function inserts
56466 ** a maximum of four divider cells into the parent page, and the maximum
56467 ** size of a cell stored within an internal node is always less than 1/4
56468 ** of the page-size, the aOvflSpace[] buffer is guaranteed to be large
56469 ** enough for all overflow cells.
56470 **
56471 ** If aOvflSpace is set to a null pointer, this function returns 
56472 ** SQLITE_NOMEM.
56473 */
56474 #if defined(_MSC_VER) && _MSC_VER >= 1700 && defined(_M_ARM)
56475 #pragma optimize("", off)
56476 #endif
56477 static int balance_nonroot(
56478   MemPage *pParent,               /* Parent page of siblings being balanced */
56479   int iParentIdx,                 /* Index of "the page" in pParent */
56480   u8 *aOvflSpace,                 /* page-size bytes of space for parent ovfl */
56481   int isRoot,                     /* True if pParent is a root-page */
56482   int bBulk                       /* True if this call is part of a bulk load */
56483 ){
56484   BtShared *pBt;               /* The whole database */
56485   int nCell = 0;               /* Number of cells in apCell[] */
56486   int nMaxCells = 0;           /* Allocated size of apCell, szCell, aFrom. */
56487   int nNew = 0;                /* Number of pages in apNew[] */
56488   int nOld;                    /* Number of pages in apOld[] */
56489   int i, j, k;                 /* Loop counters */
56490   int nxDiv;                   /* Next divider slot in pParent->aCell[] */
56491   int rc = SQLITE_OK;          /* The return code */
56492   u16 leafCorrection;          /* 4 if pPage is a leaf.  0 if not */
56493   int leafData;                /* True if pPage is a leaf of a LEAFDATA tree */
56494   int usableSpace;             /* Bytes in pPage beyond the header */
56495   int pageFlags;               /* Value of pPage->aData[0] */
56496   int subtotal;                /* Subtotal of bytes in cells on one page */
56497   int iSpace1 = 0;             /* First unused byte of aSpace1[] */
56498   int iOvflSpace = 0;          /* First unused byte of aOvflSpace[] */
56499   int szScratch;               /* Size of scratch memory requested */
56500   MemPage *apOld[NB];          /* pPage and up to two siblings */
56501   MemPage *apCopy[NB];         /* Private copies of apOld[] pages */
56502   MemPage *apNew[NB+2];        /* pPage and up to NB siblings after balancing */
56503   u8 *pRight;                  /* Location in parent of right-sibling pointer */
56504   u8 *apDiv[NB-1];             /* Divider cells in pParent */
56505   int cntNew[NB+2];            /* Index in aCell[] of cell after i-th page */
56506   int szNew[NB+2];             /* Combined size of cells place on i-th page */
56507   u8 **apCell = 0;             /* All cells begin balanced */
56508   u16 *szCell;                 /* Local size of all cells in apCell[] */
56509   u8 *aSpace1;                 /* Space for copies of dividers cells */
56510   Pgno pgno;                   /* Temp var to store a page number in */
56511 
56512   pBt = pParent->pBt;
56513   assert( sqlite3_mutex_held(pBt->mutex) );
56514   assert( sqlite3PagerIswriteable(pParent->pDbPage) );
56515 
56516 #if 0
56517   TRACE(("BALANCE: begin page %d child of %d\n", pPage->pgno, pParent->pgno));
56518 #endif
56519 
56520   /* At this point pParent may have at most one overflow cell. And if
56521   ** this overflow cell is present, it must be the cell with 
56522   ** index iParentIdx. This scenario comes about when this function
56523   ** is called (indirectly) from sqlite3BtreeDelete().
56524   */
56525   assert( pParent->nOverflow==0 || pParent->nOverflow==1 );
56526   assert( pParent->nOverflow==0 || pParent->aiOvfl[0]==iParentIdx );
56527 
56528   if( !aOvflSpace ){
56529     return SQLITE_NOMEM;
56530   }
56531 
56532   /* Find the sibling pages to balance. Also locate the cells in pParent 
56533   ** that divide the siblings. An attempt is made to find NN siblings on 
56534   ** either side of pPage. More siblings are taken from one side, however, 
56535   ** if there are fewer than NN siblings on the other side. If pParent
56536   ** has NB or fewer children then all children of pParent are taken.  
56537   **
56538   ** This loop also drops the divider cells from the parent page. This
56539   ** way, the remainder of the function does not have to deal with any
56540   ** overflow cells in the parent page, since if any existed they will
56541   ** have already been removed.
56542   */
56543   i = pParent->nOverflow + pParent->nCell;
56544   if( i<2 ){
56545     nxDiv = 0;
56546   }else{
56547     assert( bBulk==0 || bBulk==1 );
56548     if( iParentIdx==0 ){                 
56549       nxDiv = 0;
56550     }else if( iParentIdx==i ){
56551       nxDiv = i-2+bBulk;
56552     }else{
56553       assert( bBulk==0 );
56554       nxDiv = iParentIdx-1;
56555     }
56556     i = 2-bBulk;
56557   }
56558   nOld = i+1;
56559   if( (i+nxDiv-pParent->nOverflow)==pParent->nCell ){
56560     pRight = &pParent->aData[pParent->hdrOffset+8];
56561   }else{
56562     pRight = findCell(pParent, i+nxDiv-pParent->nOverflow);
56563   }
56564   pgno = get4byte(pRight);
56565   while( 1 ){
56566     rc = getAndInitPage(pBt, pgno, &apOld[i], 0);
56567     if( rc ){
56568       memset(apOld, 0, (i+1)*sizeof(MemPage*));
56569       goto balance_cleanup;
56570     }
56571     nMaxCells += 1+apOld[i]->nCell+apOld[i]->nOverflow;
56572     if( (i--)==0 ) break;
56573 
56574     if( i+nxDiv==pParent->aiOvfl[0] && pParent->nOverflow ){
56575       apDiv[i] = pParent->apOvfl[0];
56576       pgno = get4byte(apDiv[i]);
56577       szNew[i] = cellSizePtr(pParent, apDiv[i]);
56578       pParent->nOverflow = 0;
56579     }else{
56580       apDiv[i] = findCell(pParent, i+nxDiv-pParent->nOverflow);
56581       pgno = get4byte(apDiv[i]);
56582       szNew[i] = cellSizePtr(pParent, apDiv[i]);
56583 
56584       /* Drop the cell from the parent page. apDiv[i] still points to
56585       ** the cell within the parent, even though it has been dropped.
56586       ** This is safe because dropping a cell only overwrites the first
56587       ** four bytes of it, and this function does not need the first
56588       ** four bytes of the divider cell. So the pointer is safe to use
56589       ** later on.  
56590       **
56591       ** But not if we are in secure-delete mode. In secure-delete mode,
56592       ** the dropCell() routine will overwrite the entire cell with zeroes.
56593       ** In this case, temporarily copy the cell into the aOvflSpace[]
56594       ** buffer. It will be copied out again as soon as the aSpace[] buffer
56595       ** is allocated.  */
56596       if( pBt->btsFlags & BTS_SECURE_DELETE ){
56597         int iOff;
56598 
56599         iOff = SQLITE_PTR_TO_INT(apDiv[i]) - SQLITE_PTR_TO_INT(pParent->aData);
56600         if( (iOff+szNew[i])>(int)pBt->usableSize ){
56601           rc = SQLITE_CORRUPT_BKPT;
56602           memset(apOld, 0, (i+1)*sizeof(MemPage*));
56603           goto balance_cleanup;
56604         }else{
56605           memcpy(&aOvflSpace[iOff], apDiv[i], szNew[i]);
56606           apDiv[i] = &aOvflSpace[apDiv[i]-pParent->aData];
56607         }
56608       }
56609       dropCell(pParent, i+nxDiv-pParent->nOverflow, szNew[i], &rc);
56610     }
56611   }
56612 
56613   /* Make nMaxCells a multiple of 4 in order to preserve 8-byte
56614   ** alignment */
56615   nMaxCells = (nMaxCells + 3)&~3;
56616 
56617   /*
56618   ** Allocate space for memory structures
56619   */
56620   k = pBt->pageSize + ROUND8(sizeof(MemPage));
56621   szScratch =
56622        nMaxCells*sizeof(u8*)                       /* apCell */
56623      + nMaxCells*sizeof(u16)                       /* szCell */
56624      + pBt->pageSize                               /* aSpace1 */
56625      + k*nOld;                                     /* Page copies (apCopy) */
56626   apCell = sqlite3ScratchMalloc( szScratch ); 
56627   if( apCell==0 ){
56628     rc = SQLITE_NOMEM;
56629     goto balance_cleanup;
56630   }
56631   szCell = (u16*)&apCell[nMaxCells];
56632   aSpace1 = (u8*)&szCell[nMaxCells];
56633   assert( EIGHT_BYTE_ALIGNMENT(aSpace1) );
56634 
56635   /*
56636   ** Load pointers to all cells on sibling pages and the divider cells
56637   ** into the local apCell[] array.  Make copies of the divider cells
56638   ** into space obtained from aSpace1[] and remove the divider cells
56639   ** from pParent.
56640   **
56641   ** If the siblings are on leaf pages, then the child pointers of the
56642   ** divider cells are stripped from the cells before they are copied
56643   ** into aSpace1[].  In this way, all cells in apCell[] are without
56644   ** child pointers.  If siblings are not leaves, then all cell in
56645   ** apCell[] include child pointers.  Either way, all cells in apCell[]
56646   ** are alike.
56647   **
56648   ** leafCorrection:  4 if pPage is a leaf.  0 if pPage is not a leaf.
56649   **       leafData:  1 if pPage holds key+data and pParent holds only keys.
56650   */
56651   leafCorrection = apOld[0]->leaf*4;
56652   leafData = apOld[0]->hasData;
56653   for(i=0; i<nOld; i++){
56654     int limit;
56655     
56656     /* Before doing anything else, take a copy of the i'th original sibling
56657     ** The rest of this function will use data from the copies rather
56658     ** that the original pages since the original pages will be in the
56659     ** process of being overwritten.  */
56660     MemPage *pOld = apCopy[i] = (MemPage*)&aSpace1[pBt->pageSize + k*i];
56661     memcpy(pOld, apOld[i], sizeof(MemPage));
56662     pOld->aData = (void*)&pOld[1];
56663     memcpy(pOld->aData, apOld[i]->aData, pBt->pageSize);
56664 
56665     limit = pOld->nCell+pOld->nOverflow;
56666     if( pOld->nOverflow>0 ){
56667       for(j=0; j<limit; j++){
56668         assert( nCell<nMaxCells );
56669         apCell[nCell] = findOverflowCell(pOld, j);
56670         szCell[nCell] = cellSizePtr(pOld, apCell[nCell]);
56671         nCell++;
56672       }
56673     }else{
56674       u8 *aData = pOld->aData;
56675       u16 maskPage = pOld->maskPage;
56676       u16 cellOffset = pOld->cellOffset;
56677       for(j=0; j<limit; j++){
56678         assert( nCell<nMaxCells );
56679         apCell[nCell] = findCellv2(aData, maskPage, cellOffset, j);
56680         szCell[nCell] = cellSizePtr(pOld, apCell[nCell]);
56681         nCell++;
56682       }
56683     }       
56684     if( i<nOld-1 && !leafData){
56685       u16 sz = (u16)szNew[i];
56686       u8 *pTemp;
56687       assert( nCell<nMaxCells );
56688       szCell[nCell] = sz;
56689       pTemp = &aSpace1[iSpace1];
56690       iSpace1 += sz;
56691       assert( sz<=pBt->maxLocal+23 );
56692       assert( iSpace1 <= (int)pBt->pageSize );
56693       memcpy(pTemp, apDiv[i], sz);
56694       apCell[nCell] = pTemp+leafCorrection;
56695       assert( leafCorrection==0 || leafCorrection==4 );
56696       szCell[nCell] = szCell[nCell] - leafCorrection;
56697       if( !pOld->leaf ){
56698         assert( leafCorrection==0 );
56699         assert( pOld->hdrOffset==0 );
56700         /* The right pointer of the child page pOld becomes the left
56701         ** pointer of the divider cell */
56702         memcpy(apCell[nCell], &pOld->aData[8], 4);
56703       }else{
56704         assert( leafCorrection==4 );
56705         if( szCell[nCell]<4 ){
56706           /* Do not allow any cells smaller than 4 bytes. */
56707           szCell[nCell] = 4;
56708         }
56709       }
56710       nCell++;
56711     }
56712   }
56713 
56714   /*
56715   ** Figure out the number of pages needed to hold all nCell cells.
56716   ** Store this number in "k".  Also compute szNew[] which is the total
56717   ** size of all cells on the i-th page and cntNew[] which is the index
56718   ** in apCell[] of the cell that divides page i from page i+1.  
56719   ** cntNew[k] should equal nCell.
56720   **
56721   ** Values computed by this block:
56722   **
56723   **           k: The total number of sibling pages
56724   **    szNew[i]: Spaced used on the i-th sibling page.
56725   **   cntNew[i]: Index in apCell[] and szCell[] for the first cell to
56726   **              the right of the i-th sibling page.
56727   ** usableSpace: Number of bytes of space available on each sibling.
56728   ** 
56729   */
56730   usableSpace = pBt->usableSize - 12 + leafCorrection;
56731   for(subtotal=k=i=0; i<nCell; i++){
56732     assert( i<nMaxCells );
56733     subtotal += szCell[i] + 2;
56734     if( subtotal > usableSpace ){
56735       szNew[k] = subtotal - szCell[i];
56736       cntNew[k] = i;
56737       if( leafData ){ i--; }
56738       subtotal = 0;
56739       k++;
56740       if( k>NB+1 ){ rc = SQLITE_CORRUPT_BKPT; goto balance_cleanup; }
56741     }
56742   }
56743   szNew[k] = subtotal;
56744   cntNew[k] = nCell;
56745   k++;
56746 
56747   /*
56748   ** The packing computed by the previous block is biased toward the siblings
56749   ** on the left side.  The left siblings are always nearly full, while the
56750   ** right-most sibling might be nearly empty.  This block of code attempts
56751   ** to adjust the packing of siblings to get a better balance.
56752   **
56753   ** This adjustment is more than an optimization.  The packing above might
56754   ** be so out of balance as to be illegal.  For example, the right-most
56755   ** sibling might be completely empty.  This adjustment is not optional.
56756   */
56757   for(i=k-1; i>0; i--){
56758     int szRight = szNew[i];  /* Size of sibling on the right */
56759     int szLeft = szNew[i-1]; /* Size of sibling on the left */
56760     int r;              /* Index of right-most cell in left sibling */
56761     int d;              /* Index of first cell to the left of right sibling */
56762 
56763     r = cntNew[i-1] - 1;
56764     d = r + 1 - leafData;
56765     assert( d<nMaxCells );
56766     assert( r<nMaxCells );
56767     while( szRight==0 
56768        || (!bBulk && szRight+szCell[d]+2<=szLeft-(szCell[r]+2)) 
56769     ){
56770       szRight += szCell[d] + 2;
56771       szLeft -= szCell[r] + 2;
56772       cntNew[i-1]--;
56773       r = cntNew[i-1] - 1;
56774       d = r + 1 - leafData;
56775     }
56776     szNew[i] = szRight;
56777     szNew[i-1] = szLeft;
56778   }
56779 
56780   /* Either we found one or more cells (cntnew[0])>0) or pPage is
56781   ** a virtual root page.  A virtual root page is when the real root
56782   ** page is page 1 and we are the only child of that page.
56783   **
56784   ** UPDATE:  The assert() below is not necessarily true if the database
56785   ** file is corrupt.  The corruption will be detected and reported later
56786   ** in this procedure so there is no need to act upon it now.
56787   */
56788 #if 0
56789   assert( cntNew[0]>0 || (pParent->pgno==1 && pParent->nCell==0) );
56790 #endif
56791 
56792   TRACE(("BALANCE: old: %d %d %d  ",
56793     apOld[0]->pgno, 
56794     nOld>=2 ? apOld[1]->pgno : 0,
56795     nOld>=3 ? apOld[2]->pgno : 0
56796   ));
56797 
56798   /*
56799   ** Allocate k new pages.  Reuse old pages where possible.
56800   */
56801   if( apOld[0]->pgno<=1 ){
56802     rc = SQLITE_CORRUPT_BKPT;
56803     goto balance_cleanup;
56804   }
56805   pageFlags = apOld[0]->aData[0];
56806   for(i=0; i<k; i++){
56807     MemPage *pNew;
56808     if( i<nOld ){
56809       pNew = apNew[i] = apOld[i];
56810       apOld[i] = 0;
56811       rc = sqlite3PagerWrite(pNew->pDbPage);
56812       nNew++;
56813       if( rc ) goto balance_cleanup;
56814     }else{
56815       assert( i>0 );
56816       rc = allocateBtreePage(pBt, &pNew, &pgno, (bBulk ? 1 : pgno), 0);
56817       if( rc ) goto balance_cleanup;
56818       apNew[i] = pNew;
56819       nNew++;
56820 
56821       /* Set the pointer-map entry for the new sibling page. */
56822       if( ISAUTOVACUUM ){
56823         ptrmapPut(pBt, pNew->pgno, PTRMAP_BTREE, pParent->pgno, &rc);
56824         if( rc!=SQLITE_OK ){
56825           goto balance_cleanup;
56826         }
56827       }
56828     }
56829   }
56830 
56831   /* Free any old pages that were not reused as new pages.
56832   */
56833   while( i<nOld ){
56834     freePage(apOld[i], &rc);
56835     if( rc ) goto balance_cleanup;
56836     releasePage(apOld[i]);
56837     apOld[i] = 0;
56838     i++;
56839   }
56840 
56841   /*
56842   ** Put the new pages in accending order.  This helps to
56843   ** keep entries in the disk file in order so that a scan
56844   ** of the table is a linear scan through the file.  That
56845   ** in turn helps the operating system to deliver pages
56846   ** from the disk more rapidly.
56847   **
56848   ** An O(n^2) insertion sort algorithm is used, but since
56849   ** n is never more than NB (a small constant), that should
56850   ** not be a problem.
56851   **
56852   ** When NB==3, this one optimization makes the database
56853   ** about 25% faster for large insertions and deletions.
56854   */
56855   for(i=0; i<k-1; i++){
56856     int minV = apNew[i]->pgno;
56857     int minI = i;
56858     for(j=i+1; j<k; j++){
56859       if( apNew[j]->pgno<(unsigned)minV ){
56860         minI = j;
56861         minV = apNew[j]->pgno;
56862       }
56863     }
56864     if( minI>i ){
56865       MemPage *pT;
56866       pT = apNew[i];
56867       apNew[i] = apNew[minI];
56868       apNew[minI] = pT;
56869     }
56870   }
56871   TRACE(("new: %d(%d) %d(%d) %d(%d) %d(%d) %d(%d)\n",
56872     apNew[0]->pgno, szNew[0],
56873     nNew>=2 ? apNew[1]->pgno : 0, nNew>=2 ? szNew[1] : 0,
56874     nNew>=3 ? apNew[2]->pgno : 0, nNew>=3 ? szNew[2] : 0,
56875     nNew>=4 ? apNew[3]->pgno : 0, nNew>=4 ? szNew[3] : 0,
56876     nNew>=5 ? apNew[4]->pgno : 0, nNew>=5 ? szNew[4] : 0));
56877 
56878   assert( sqlite3PagerIswriteable(pParent->pDbPage) );
56879   put4byte(pRight, apNew[nNew-1]->pgno);
56880 
56881   /*
56882   ** Evenly distribute the data in apCell[] across the new pages.
56883   ** Insert divider cells into pParent as necessary.
56884   */
56885   j = 0;
56886   for(i=0; i<nNew; i++){
56887     /* Assemble the new sibling page. */
56888     MemPage *pNew = apNew[i];
56889     assert( j<nMaxCells );
56890     zeroPage(pNew, pageFlags);
56891     assemblePage(pNew, cntNew[i]-j, &apCell[j], &szCell[j]);
56892     assert( pNew->nCell>0 || (nNew==1 && cntNew[0]==0) );
56893     assert( pNew->nOverflow==0 );
56894 
56895     j = cntNew[i];
56896 
56897     /* If the sibling page assembled above was not the right-most sibling,
56898     ** insert a divider cell into the parent page.
56899     */
56900     assert( i<nNew-1 || j==nCell );
56901     if( j<nCell ){
56902       u8 *pCell;
56903       u8 *pTemp;
56904       int sz;
56905 
56906       assert( j<nMaxCells );
56907       pCell = apCell[j];
56908       sz = szCell[j] + leafCorrection;
56909       pTemp = &aOvflSpace[iOvflSpace];
56910       if( !pNew->leaf ){
56911         memcpy(&pNew->aData[8], pCell, 4);
56912       }else if( leafData ){
56913         /* If the tree is a leaf-data tree, and the siblings are leaves, 
56914         ** then there is no divider cell in apCell[]. Instead, the divider 
56915         ** cell consists of the integer key for the right-most cell of 
56916         ** the sibling-page assembled above only.
56917         */
56918         CellInfo info;
56919         j--;
56920         btreeParseCellPtr(pNew, apCell[j], &info);
56921         pCell = pTemp;
56922         sz = 4 + putVarint(&pCell[4], info.nKey);
56923         pTemp = 0;
56924       }else{
56925         pCell -= 4;
56926         /* Obscure case for non-leaf-data trees: If the cell at pCell was
56927         ** previously stored on a leaf node, and its reported size was 4
56928         ** bytes, then it may actually be smaller than this 
56929         ** (see btreeParseCellPtr(), 4 bytes is the minimum size of
56930         ** any cell). But it is important to pass the correct size to 
56931         ** insertCell(), so reparse the cell now.
56932         **
56933         ** Note that this can never happen in an SQLite data file, as all
56934         ** cells are at least 4 bytes. It only happens in b-trees used
56935         ** to evaluate "IN (SELECT ...)" and similar clauses.
56936         */
56937         if( szCell[j]==4 ){
56938           assert(leafCorrection==4);
56939           sz = cellSizePtr(pParent, pCell);
56940         }
56941       }
56942       iOvflSpace += sz;
56943       assert( sz<=pBt->maxLocal+23 );
56944       assert( iOvflSpace <= (int)pBt->pageSize );
56945       insertCell(pParent, nxDiv, pCell, sz, pTemp, pNew->pgno, &rc);
56946       if( rc!=SQLITE_OK ) goto balance_cleanup;
56947       assert( sqlite3PagerIswriteable(pParent->pDbPage) );
56948 
56949       j++;
56950       nxDiv++;
56951     }
56952   }
56953   assert( j==nCell );
56954   assert( nOld>0 );
56955   assert( nNew>0 );
56956   if( (pageFlags & PTF_LEAF)==0 ){
56957     u8 *zChild = &apCopy[nOld-1]->aData[8];
56958     memcpy(&apNew[nNew-1]->aData[8], zChild, 4);
56959   }
56960 
56961   if( isRoot && pParent->nCell==0 && pParent->hdrOffset<=apNew[0]->nFree ){
56962     /* The root page of the b-tree now contains no cells. The only sibling
56963     ** page is the right-child of the parent. Copy the contents of the
56964     ** child page into the parent, decreasing the overall height of the
56965     ** b-tree structure by one. This is described as the "balance-shallower"
56966     ** sub-algorithm in some documentation.
56967     **
56968     ** If this is an auto-vacuum database, the call to copyNodeContent() 
56969     ** sets all pointer-map entries corresponding to database image pages 
56970     ** for which the pointer is stored within the content being copied.
56971     **
56972     ** The second assert below verifies that the child page is defragmented
56973     ** (it must be, as it was just reconstructed using assemblePage()). This
56974     ** is important if the parent page happens to be page 1 of the database
56975     ** image.  */
56976     assert( nNew==1 );
56977     assert( apNew[0]->nFree == 
56978         (get2byte(&apNew[0]->aData[5])-apNew[0]->cellOffset-apNew[0]->nCell*2) 
56979     );
56980     copyNodeContent(apNew[0], pParent, &rc);
56981     freePage(apNew[0], &rc);
56982   }else if( ISAUTOVACUUM ){
56983     /* Fix the pointer-map entries for all the cells that were shifted around. 
56984     ** There are several different types of pointer-map entries that need to
56985     ** be dealt with by this routine. Some of these have been set already, but
56986     ** many have not. The following is a summary:
56987     **
56988     **   1) The entries associated with new sibling pages that were not
56989     **      siblings when this function was called. These have already
56990     **      been set. We don't need to worry about old siblings that were
56991     **      moved to the free-list - the freePage() code has taken care
56992     **      of those.
56993     **
56994     **   2) The pointer-map entries associated with the first overflow
56995     **      page in any overflow chains used by new divider cells. These 
56996     **      have also already been taken care of by the insertCell() code.
56997     **
56998     **   3) If the sibling pages are not leaves, then the child pages of
56999     **      cells stored on the sibling pages may need to be updated.
57000     **
57001     **   4) If the sibling pages are not internal intkey nodes, then any
57002     **      overflow pages used by these cells may need to be updated
57003     **      (internal intkey nodes never contain pointers to overflow pages).
57004     **
57005     **   5) If the sibling pages are not leaves, then the pointer-map
57006     **      entries for the right-child pages of each sibling may need
57007     **      to be updated.
57008     **
57009     ** Cases 1 and 2 are dealt with above by other code. The next
57010     ** block deals with cases 3 and 4 and the one after that, case 5. Since
57011     ** setting a pointer map entry is a relatively expensive operation, this
57012     ** code only sets pointer map entries for child or overflow pages that have
57013     ** actually moved between pages.  */
57014     MemPage *pNew = apNew[0];
57015     MemPage *pOld = apCopy[0];
57016     int nOverflow = pOld->nOverflow;
57017     int iNextOld = pOld->nCell + nOverflow;
57018     int iOverflow = (nOverflow ? pOld->aiOvfl[0] : -1);
57019     j = 0;                             /* Current 'old' sibling page */
57020     k = 0;                             /* Current 'new' sibling page */
57021     for(i=0; i<nCell; i++){
57022       int isDivider = 0;
57023       while( i==iNextOld ){
57024         /* Cell i is the cell immediately following the last cell on old
57025         ** sibling page j. If the siblings are not leaf pages of an
57026         ** intkey b-tree, then cell i was a divider cell. */
57027         assert( j+1 < ArraySize(apCopy) );
57028         assert( j+1 < nOld );
57029         pOld = apCopy[++j];
57030         iNextOld = i + !leafData + pOld->nCell + pOld->nOverflow;
57031         if( pOld->nOverflow ){
57032           nOverflow = pOld->nOverflow;
57033           iOverflow = i + !leafData + pOld->aiOvfl[0];
57034         }
57035         isDivider = !leafData;  
57036       }
57037 
57038       assert(nOverflow>0 || iOverflow<i );
57039       assert(nOverflow<2 || pOld->aiOvfl[0]==pOld->aiOvfl[1]-1);
57040       assert(nOverflow<3 || pOld->aiOvfl[1]==pOld->aiOvfl[2]-1);
57041       if( i==iOverflow ){
57042         isDivider = 1;
57043         if( (--nOverflow)>0 ){
57044           iOverflow++;
57045         }
57046       }
57047 
57048       if( i==cntNew[k] ){
57049         /* Cell i is the cell immediately following the last cell on new
57050         ** sibling page k. If the siblings are not leaf pages of an
57051         ** intkey b-tree, then cell i is a divider cell.  */
57052         pNew = apNew[++k];
57053         if( !leafData ) continue;
57054       }
57055       assert( j<nOld );
57056       assert( k<nNew );
57057 
57058       /* If the cell was originally divider cell (and is not now) or
57059       ** an overflow cell, or if the cell was located on a different sibling
57060       ** page before the balancing, then the pointer map entries associated
57061       ** with any child or overflow pages need to be updated.  */
57062       if( isDivider || pOld->pgno!=pNew->pgno ){
57063         if( !leafCorrection ){
57064           ptrmapPut(pBt, get4byte(apCell[i]), PTRMAP_BTREE, pNew->pgno, &rc);
57065         }
57066         if( szCell[i]>pNew->minLocal ){
57067           ptrmapPutOvflPtr(pNew, apCell[i], &rc);
57068         }
57069       }
57070     }
57071 
57072     if( !leafCorrection ){
57073       for(i=0; i<nNew; i++){
57074         u32 key = get4byte(&apNew[i]->aData[8]);
57075         ptrmapPut(pBt, key, PTRMAP_BTREE, apNew[i]->pgno, &rc);
57076       }
57077     }
57078 
57079 #if 0
57080     /* The ptrmapCheckPages() contains assert() statements that verify that
57081     ** all pointer map pages are set correctly. This is helpful while 
57082     ** debugging. This is usually disabled because a corrupt database may
57083     ** cause an assert() statement to fail.  */
57084     ptrmapCheckPages(apNew, nNew);
57085     ptrmapCheckPages(&pParent, 1);
57086 #endif
57087   }
57088 
57089   assert( pParent->isInit );
57090   TRACE(("BALANCE: finished: old=%d new=%d cells=%d\n",
57091           nOld, nNew, nCell));
57092 
57093   /*
57094   ** Cleanup before returning.
57095   */
57096 balance_cleanup:
57097   sqlite3ScratchFree(apCell);
57098   for(i=0; i<nOld; i++){
57099     releasePage(apOld[i]);
57100   }
57101   for(i=0; i<nNew; i++){
57102     releasePage(apNew[i]);
57103   }
57104 
57105   return rc;
57106 }
57107 #if defined(_MSC_VER) && _MSC_VER >= 1700 && defined(_M_ARM)
57108 #pragma optimize("", on)
57109 #endif
57110 
57111 
57112 /*
57113 ** This function is called when the root page of a b-tree structure is
57114 ** overfull (has one or more overflow pages).
57115 **
57116 ** A new child page is allocated and the contents of the current root
57117 ** page, including overflow cells, are copied into the child. The root
57118 ** page is then overwritten to make it an empty page with the right-child 
57119 ** pointer pointing to the new page.
57120 **
57121 ** Before returning, all pointer-map entries corresponding to pages 
57122 ** that the new child-page now contains pointers to are updated. The
57123 ** entry corresponding to the new right-child pointer of the root
57124 ** page is also updated.
57125 **
57126 ** If successful, *ppChild is set to contain a reference to the child 
57127 ** page and SQLITE_OK is returned. In this case the caller is required
57128 ** to call releasePage() on *ppChild exactly once. If an error occurs,
57129 ** an error code is returned and *ppChild is set to 0.
57130 */
57131 static int balance_deeper(MemPage *pRoot, MemPage **ppChild){
57132   int rc;                        /* Return value from subprocedures */
57133   MemPage *pChild = 0;           /* Pointer to a new child page */
57134   Pgno pgnoChild = 0;            /* Page number of the new child page */
57135   BtShared *pBt = pRoot->pBt;    /* The BTree */
57136 
57137   assert( pRoot->nOverflow>0 );
57138   assert( sqlite3_mutex_held(pBt->mutex) );
57139 
57140   /* Make pRoot, the root page of the b-tree, writable. Allocate a new 
57141   ** page that will become the new right-child of pPage. Copy the contents
57142   ** of the node stored on pRoot into the new child page.
57143   */
57144   rc = sqlite3PagerWrite(pRoot->pDbPage);
57145   if( rc==SQLITE_OK ){
57146     rc = allocateBtreePage(pBt,&pChild,&pgnoChild,pRoot->pgno,0);
57147     copyNodeContent(pRoot, pChild, &rc);
57148     if( ISAUTOVACUUM ){
57149       ptrmapPut(pBt, pgnoChild, PTRMAP_BTREE, pRoot->pgno, &rc);
57150     }
57151   }
57152   if( rc ){
57153     *ppChild = 0;
57154     releasePage(pChild);
57155     return rc;
57156   }
57157   assert( sqlite3PagerIswriteable(pChild->pDbPage) );
57158   assert( sqlite3PagerIswriteable(pRoot->pDbPage) );
57159   assert( pChild->nCell==pRoot->nCell );
57160 
57161   TRACE(("BALANCE: copy root %d into %d\n", pRoot->pgno, pChild->pgno));
57162 
57163   /* Copy the overflow cells from pRoot to pChild */
57164   memcpy(pChild->aiOvfl, pRoot->aiOvfl,
57165          pRoot->nOverflow*sizeof(pRoot->aiOvfl[0]));
57166   memcpy(pChild->apOvfl, pRoot->apOvfl,
57167          pRoot->nOverflow*sizeof(pRoot->apOvfl[0]));
57168   pChild->nOverflow = pRoot->nOverflow;
57169 
57170   /* Zero the contents of pRoot. Then install pChild as the right-child. */
57171   zeroPage(pRoot, pChild->aData[0] & ~PTF_LEAF);
57172   put4byte(&pRoot->aData[pRoot->hdrOffset+8], pgnoChild);
57173 
57174   *ppChild = pChild;
57175   return SQLITE_OK;
57176 }
57177 
57178 /*
57179 ** The page that pCur currently points to has just been modified in
57180 ** some way. This function figures out if this modification means the
57181 ** tree needs to be balanced, and if so calls the appropriate balancing 
57182 ** routine. Balancing routines are:
57183 **
57184 **   balance_quick()
57185 **   balance_deeper()
57186 **   balance_nonroot()
57187 */
57188 static int balance(BtCursor *pCur){
57189   int rc = SQLITE_OK;
57190   const int nMin = pCur->pBt->usableSize * 2 / 3;
57191   u8 aBalanceQuickSpace[13];
57192   u8 *pFree = 0;
57193 
57194   TESTONLY( int balance_quick_called = 0 );
57195   TESTONLY( int balance_deeper_called = 0 );
57196 
57197   do {
57198     int iPage = pCur->iPage;
57199     MemPage *pPage = pCur->apPage[iPage];
57200 
57201     if( iPage==0 ){
57202       if( pPage->nOverflow ){
57203         /* The root page of the b-tree is overfull. In this case call the
57204         ** balance_deeper() function to create a new child for the root-page
57205         ** and copy the current contents of the root-page to it. The
57206         ** next iteration of the do-loop will balance the child page.
57207         */ 
57208         assert( (balance_deeper_called++)==0 );
57209         rc = balance_deeper(pPage, &pCur->apPage[1]);
57210         if( rc==SQLITE_OK ){
57211           pCur->iPage = 1;
57212           pCur->aiIdx[0] = 0;
57213           pCur->aiIdx[1] = 0;
57214           assert( pCur->apPage[1]->nOverflow );
57215         }
57216       }else{
57217         break;
57218       }
57219     }else if( pPage->nOverflow==0 && pPage->nFree<=nMin ){
57220       break;
57221     }else{
57222       MemPage * const pParent = pCur->apPage[iPage-1];
57223       int const iIdx = pCur->aiIdx[iPage-1];
57224 
57225       rc = sqlite3PagerWrite(pParent->pDbPage);
57226       if( rc==SQLITE_OK ){
57227 #ifndef SQLITE_OMIT_QUICKBALANCE
57228         if( pPage->hasData
57229          && pPage->nOverflow==1
57230          && pPage->aiOvfl[0]==pPage->nCell
57231          && pParent->pgno!=1
57232          && pParent->nCell==iIdx
57233         ){
57234           /* Call balance_quick() to create a new sibling of pPage on which
57235           ** to store the overflow cell. balance_quick() inserts a new cell
57236           ** into pParent, which may cause pParent overflow. If this
57237           ** happens, the next interation of the do-loop will balance pParent 
57238           ** use either balance_nonroot() or balance_deeper(). Until this
57239           ** happens, the overflow cell is stored in the aBalanceQuickSpace[]
57240           ** buffer. 
57241           **
57242           ** The purpose of the following assert() is to check that only a
57243           ** single call to balance_quick() is made for each call to this
57244           ** function. If this were not verified, a subtle bug involving reuse
57245           ** of the aBalanceQuickSpace[] might sneak in.
57246           */
57247           assert( (balance_quick_called++)==0 );
57248           rc = balance_quick(pParent, pPage, aBalanceQuickSpace);
57249         }else
57250 #endif
57251         {
57252           /* In this case, call balance_nonroot() to redistribute cells
57253           ** between pPage and up to 2 of its sibling pages. This involves
57254           ** modifying the contents of pParent, which may cause pParent to
57255           ** become overfull or underfull. The next iteration of the do-loop
57256           ** will balance the parent page to correct this.
57257           ** 
57258           ** If the parent page becomes overfull, the overflow cell or cells
57259           ** are stored in the pSpace buffer allocated immediately below. 
57260           ** A subsequent iteration of the do-loop will deal with this by
57261           ** calling balance_nonroot() (balance_deeper() may be called first,
57262           ** but it doesn't deal with overflow cells - just moves them to a
57263           ** different page). Once this subsequent call to balance_nonroot() 
57264           ** has completed, it is safe to release the pSpace buffer used by
57265           ** the previous call, as the overflow cell data will have been 
57266           ** copied either into the body of a database page or into the new
57267           ** pSpace buffer passed to the latter call to balance_nonroot().
57268           */
57269           u8 *pSpace = sqlite3PageMalloc(pCur->pBt->pageSize);
57270           rc = balance_nonroot(pParent, iIdx, pSpace, iPage==1, pCur->hints);
57271           if( pFree ){
57272             /* If pFree is not NULL, it points to the pSpace buffer used 
57273             ** by a previous call to balance_nonroot(). Its contents are
57274             ** now stored either on real database pages or within the 
57275             ** new pSpace buffer, so it may be safely freed here. */
57276             sqlite3PageFree(pFree);
57277           }
57278 
57279           /* The pSpace buffer will be freed after the next call to
57280           ** balance_nonroot(), or just before this function returns, whichever
57281           ** comes first. */
57282           pFree = pSpace;
57283         }
57284       }
57285 
57286       pPage->nOverflow = 0;
57287 
57288       /* The next iteration of the do-loop balances the parent page. */
57289       releasePage(pPage);
57290       pCur->iPage--;
57291     }
57292   }while( rc==SQLITE_OK );
57293 
57294   if( pFree ){
57295     sqlite3PageFree(pFree);
57296   }
57297   return rc;
57298 }
57299 
57300 
57301 /*
57302 ** Insert a new record into the BTree.  The key is given by (pKey,nKey)
57303 ** and the data is given by (pData,nData).  The cursor is used only to
57304 ** define what table the record should be inserted into.  The cursor
57305 ** is left pointing at a random location.
57306 **
57307 ** For an INTKEY table, only the nKey value of the key is used.  pKey is
57308 ** ignored.  For a ZERODATA table, the pData and nData are both ignored.
57309 **
57310 ** If the seekResult parameter is non-zero, then a successful call to
57311 ** MovetoUnpacked() to seek cursor pCur to (pKey, nKey) has already
57312 ** been performed. seekResult is the search result returned (a negative
57313 ** number if pCur points at an entry that is smaller than (pKey, nKey), or
57314 ** a positive value if pCur points at an etry that is larger than 
57315 ** (pKey, nKey)). 
57316 **
57317 ** If the seekResult parameter is non-zero, then the caller guarantees that
57318 ** cursor pCur is pointing at the existing copy of a row that is to be
57319 ** overwritten.  If the seekResult parameter is 0, then cursor pCur may
57320 ** point to any entry or to no entry at all and so this function has to seek
57321 ** the cursor before the new key can be inserted.
57322 */
57323 SQLITE_PRIVATE int sqlite3BtreeInsert(
57324   BtCursor *pCur,                /* Insert data into the table of this cursor */
57325   const void *pKey, i64 nKey,    /* The key of the new record */
57326   const void *pData, int nData,  /* The data of the new record */
57327   int nZero,                     /* Number of extra 0 bytes to append to data */
57328   int appendBias,                /* True if this is likely an append */
57329   int seekResult                 /* Result of prior MovetoUnpacked() call */
57330 ){
57331   int rc;
57332   int loc = seekResult;          /* -1: before desired location  +1: after */
57333   int szNew = 0;
57334   int idx;
57335   MemPage *pPage;
57336   Btree *p = pCur->pBtree;
57337   BtShared *pBt = p->pBt;
57338   unsigned char *oldCell;
57339   unsigned char *newCell = 0;
57340 
57341   if( pCur->eState==CURSOR_FAULT ){
57342     assert( pCur->skipNext!=SQLITE_OK );
57343     return pCur->skipNext;
57344   }
57345 
57346   assert( cursorHoldsMutex(pCur) );
57347   assert( pCur->wrFlag && pBt->inTransaction==TRANS_WRITE
57348               && (pBt->btsFlags & BTS_READ_ONLY)==0 );
57349   assert( hasSharedCacheTableLock(p, pCur->pgnoRoot, pCur->pKeyInfo!=0, 2) );
57350 
57351   /* Assert that the caller has been consistent. If this cursor was opened
57352   ** expecting an index b-tree, then the caller should be inserting blob
57353   ** keys with no associated data. If the cursor was opened expecting an
57354   ** intkey table, the caller should be inserting integer keys with a
57355   ** blob of associated data.  */
57356   assert( (pKey==0)==(pCur->pKeyInfo==0) );
57357 
57358   /* Save the positions of any other cursors open on this table.
57359   **
57360   ** In some cases, the call to btreeMoveto() below is a no-op. For
57361   ** example, when inserting data into a table with auto-generated integer
57362   ** keys, the VDBE layer invokes sqlite3BtreeLast() to figure out the 
57363   ** integer key to use. It then calls this function to actually insert the 
57364   ** data into the intkey B-Tree. In this case btreeMoveto() recognizes
57365   ** that the cursor is already where it needs to be and returns without
57366   ** doing any work. To avoid thwarting these optimizations, it is important
57367   ** not to clear the cursor here.
57368   */
57369   rc = saveAllCursors(pBt, pCur->pgnoRoot, pCur);
57370   if( rc ) return rc;
57371 
57372   /* If this is an insert into a table b-tree, invalidate any incrblob 
57373   ** cursors open on the row being replaced (assuming this is a replace
57374   ** operation - if it is not, the following is a no-op).  */
57375   if( pCur->pKeyInfo==0 ){
57376     invalidateIncrblobCursors(p, nKey, 0);
57377   }
57378 
57379   if( !loc ){
57380     rc = btreeMoveto(pCur, pKey, nKey, appendBias, &loc);
57381     if( rc ) return rc;
57382   }
57383   assert( pCur->eState==CURSOR_VALID || (pCur->eState==CURSOR_INVALID && loc) );
57384 
57385   pPage = pCur->apPage[pCur->iPage];
57386   assert( pPage->intKey || nKey>=0 );
57387   assert( pPage->leaf || !pPage->intKey );
57388 
57389   TRACE(("INSERT: table=%d nkey=%lld ndata=%d page=%d %s\n",
57390           pCur->pgnoRoot, nKey, nData, pPage->pgno,
57391           loc==0 ? "overwrite" : "new entry"));
57392   assert( pPage->isInit );
57393   allocateTempSpace(pBt);
57394   newCell = pBt->pTmpSpace;
57395   if( newCell==0 ) return SQLITE_NOMEM;
57396   rc = fillInCell(pPage, newCell, pKey, nKey, pData, nData, nZero, &szNew);
57397   if( rc ) goto end_insert;
57398   assert( szNew==cellSizePtr(pPage, newCell) );
57399   assert( szNew <= MX_CELL_SIZE(pBt) );
57400   idx = pCur->aiIdx[pCur->iPage];
57401   if( loc==0 ){
57402     u16 szOld;
57403     assert( idx<pPage->nCell );
57404     rc = sqlite3PagerWrite(pPage->pDbPage);
57405     if( rc ){
57406       goto end_insert;
57407     }
57408     oldCell = findCell(pPage, idx);
57409     if( !pPage->leaf ){
57410       memcpy(newCell, oldCell, 4);
57411     }
57412     szOld = cellSizePtr(pPage, oldCell);
57413     rc = clearCell(pPage, oldCell);
57414     dropCell(pPage, idx, szOld, &rc);
57415     if( rc ) goto end_insert;
57416   }else if( loc<0 && pPage->nCell>0 ){
57417     assert( pPage->leaf );
57418     idx = ++pCur->aiIdx[pCur->iPage];
57419   }else{
57420     assert( pPage->leaf );
57421   }
57422   insertCell(pPage, idx, newCell, szNew, 0, 0, &rc);
57423   assert( rc!=SQLITE_OK || pPage->nCell>0 || pPage->nOverflow>0 );
57424 
57425   /* If no error has occurred and pPage has an overflow cell, call balance() 
57426   ** to redistribute the cells within the tree. Since balance() may move
57427   ** the cursor, zero the BtCursor.info.nSize and BtCursor.validNKey
57428   ** variables.
57429   **
57430   ** Previous versions of SQLite called moveToRoot() to move the cursor
57431   ** back to the root page as balance() used to invalidate the contents
57432   ** of BtCursor.apPage[] and BtCursor.aiIdx[]. Instead of doing that,
57433   ** set the cursor state to "invalid". This makes common insert operations
57434   ** slightly faster.
57435   **
57436   ** There is a subtle but important optimization here too. When inserting
57437   ** multiple records into an intkey b-tree using a single cursor (as can
57438   ** happen while processing an "INSERT INTO ... SELECT" statement), it
57439   ** is advantageous to leave the cursor pointing to the last entry in
57440   ** the b-tree if possible. If the cursor is left pointing to the last
57441   ** entry in the table, and the next row inserted has an integer key
57442   ** larger than the largest existing key, it is possible to insert the
57443   ** row without seeking the cursor. This can be a big performance boost.
57444   */
57445   pCur->info.nSize = 0;
57446   pCur->validNKey = 0;
57447   if( rc==SQLITE_OK && pPage->nOverflow ){
57448     rc = balance(pCur);
57449 
57450     /* Must make sure nOverflow is reset to zero even if the balance()
57451     ** fails. Internal data structure corruption will result otherwise. 
57452     ** Also, set the cursor state to invalid. This stops saveCursorPosition()
57453     ** from trying to save the current position of the cursor.  */
57454     pCur->apPage[pCur->iPage]->nOverflow = 0;
57455     pCur->eState = CURSOR_INVALID;
57456   }
57457   assert( pCur->apPage[pCur->iPage]->nOverflow==0 );
57458 
57459 end_insert:
57460   return rc;
57461 }
57462 
57463 /*
57464 ** Delete the entry that the cursor is pointing to.  The cursor
57465 ** is left pointing at a arbitrary location.
57466 */
57467 SQLITE_PRIVATE int sqlite3BtreeDelete(BtCursor *pCur){
57468   Btree *p = pCur->pBtree;
57469   BtShared *pBt = p->pBt;              
57470   int rc;                              /* Return code */
57471   MemPage *pPage;                      /* Page to delete cell from */
57472   unsigned char *pCell;                /* Pointer to cell to delete */
57473   int iCellIdx;                        /* Index of cell to delete */
57474   int iCellDepth;                      /* Depth of node containing pCell */ 
57475 
57476   assert( cursorHoldsMutex(pCur) );
57477   assert( pBt->inTransaction==TRANS_WRITE );
57478   assert( (pBt->btsFlags & BTS_READ_ONLY)==0 );
57479   assert( pCur->wrFlag );
57480   assert( hasSharedCacheTableLock(p, pCur->pgnoRoot, pCur->pKeyInfo!=0, 2) );
57481   assert( !hasReadConflicts(p, pCur->pgnoRoot) );
57482 
57483   if( NEVER(pCur->aiIdx[pCur->iPage]>=pCur->apPage[pCur->iPage]->nCell) 
57484    || NEVER(pCur->eState!=CURSOR_VALID)
57485   ){
57486     return SQLITE_ERROR;  /* Something has gone awry. */
57487   }
57488 
57489   iCellDepth = pCur->iPage;
57490   iCellIdx = pCur->aiIdx[iCellDepth];
57491   pPage = pCur->apPage[iCellDepth];
57492   pCell = findCell(pPage, iCellIdx);
57493 
57494   /* If the page containing the entry to delete is not a leaf page, move
57495   ** the cursor to the largest entry in the tree that is smaller than
57496   ** the entry being deleted. This cell will replace the cell being deleted
57497   ** from the internal node. The 'previous' entry is used for this instead
57498   ** of the 'next' entry, as the previous entry is always a part of the
57499   ** sub-tree headed by the child page of the cell being deleted. This makes
57500   ** balancing the tree following the delete operation easier.  */
57501   if( !pPage->leaf ){
57502     int notUsed;
57503     rc = sqlite3BtreePrevious(pCur, &notUsed);
57504     if( rc ) return rc;
57505   }
57506 
57507   /* Save the positions of any other cursors open on this table before
57508   ** making any modifications. Make the page containing the entry to be 
57509   ** deleted writable. Then free any overflow pages associated with the 
57510   ** entry and finally remove the cell itself from within the page.  
57511   */
57512   rc = saveAllCursors(pBt, pCur->pgnoRoot, pCur);
57513   if( rc ) return rc;
57514 
57515   /* If this is a delete operation to remove a row from a table b-tree,
57516   ** invalidate any incrblob cursors open on the row being deleted.  */
57517   if( pCur->pKeyInfo==0 ){
57518     invalidateIncrblobCursors(p, pCur->info.nKey, 0);
57519   }
57520 
57521   rc = sqlite3PagerWrite(pPage->pDbPage);
57522   if( rc ) return rc;
57523   rc = clearCell(pPage, pCell);
57524   dropCell(pPage, iCellIdx, cellSizePtr(pPage, pCell), &rc);
57525   if( rc ) return rc;
57526 
57527   /* If the cell deleted was not located on a leaf page, then the cursor
57528   ** is currently pointing to the largest entry in the sub-tree headed
57529   ** by the child-page of the cell that was just deleted from an internal
57530   ** node. The cell from the leaf node needs to be moved to the internal
57531   ** node to replace the deleted cell.  */
57532   if( !pPage->leaf ){
57533     MemPage *pLeaf = pCur->apPage[pCur->iPage];
57534     int nCell;
57535     Pgno n = pCur->apPage[iCellDepth+1]->pgno;
57536     unsigned char *pTmp;
57537 
57538     pCell = findCell(pLeaf, pLeaf->nCell-1);
57539     nCell = cellSizePtr(pLeaf, pCell);
57540     assert( MX_CELL_SIZE(pBt) >= nCell );
57541 
57542     allocateTempSpace(pBt);
57543     pTmp = pBt->pTmpSpace;
57544 
57545     rc = sqlite3PagerWrite(pLeaf->pDbPage);
57546     insertCell(pPage, iCellIdx, pCell-4, nCell+4, pTmp, n, &rc);
57547     dropCell(pLeaf, pLeaf->nCell-1, nCell, &rc);
57548     if( rc ) return rc;
57549   }
57550 
57551   /* Balance the tree. If the entry deleted was located on a leaf page,
57552   ** then the cursor still points to that page. In this case the first
57553   ** call to balance() repairs the tree, and the if(...) condition is
57554   ** never true.
57555   **
57556   ** Otherwise, if the entry deleted was on an internal node page, then
57557   ** pCur is pointing to the leaf page from which a cell was removed to
57558   ** replace the cell deleted from the internal node. This is slightly
57559   ** tricky as the leaf node may be underfull, and the internal node may
57560   ** be either under or overfull. In this case run the balancing algorithm
57561   ** on the leaf node first. If the balance proceeds far enough up the
57562   ** tree that we can be sure that any problem in the internal node has
57563   ** been corrected, so be it. Otherwise, after balancing the leaf node,
57564   ** walk the cursor up the tree to the internal node and balance it as 
57565   ** well.  */
57566   rc = balance(pCur);
57567   if( rc==SQLITE_OK && pCur->iPage>iCellDepth ){
57568     while( pCur->iPage>iCellDepth ){
57569       releasePage(pCur->apPage[pCur->iPage--]);
57570     }
57571     rc = balance(pCur);
57572   }
57573 
57574   if( rc==SQLITE_OK ){
57575     moveToRoot(pCur);
57576   }
57577   return rc;
57578 }
57579 
57580 /*
57581 ** Create a new BTree table.  Write into *piTable the page
57582 ** number for the root page of the new table.
57583 **
57584 ** The type of type is determined by the flags parameter.  Only the
57585 ** following values of flags are currently in use.  Other values for
57586 ** flags might not work:
57587 **
57588 **     BTREE_INTKEY|BTREE_LEAFDATA     Used for SQL tables with rowid keys
57589 **     BTREE_ZERODATA                  Used for SQL indices
57590 */
57591 static int btreeCreateTable(Btree *p, int *piTable, int createTabFlags){
57592   BtShared *pBt = p->pBt;
57593   MemPage *pRoot;
57594   Pgno pgnoRoot;
57595   int rc;
57596   int ptfFlags;          /* Page-type flage for the root page of new table */
57597 
57598   assert( sqlite3BtreeHoldsMutex(p) );
57599   assert( pBt->inTransaction==TRANS_WRITE );
57600   assert( (pBt->btsFlags & BTS_READ_ONLY)==0 );
57601 
57602 #ifdef SQLITE_OMIT_AUTOVACUUM
57603   rc = allocateBtreePage(pBt, &pRoot, &pgnoRoot, 1, 0);
57604   if( rc ){
57605     return rc;
57606   }
57607 #else
57608   if( pBt->autoVacuum ){
57609     Pgno pgnoMove;      /* Move a page here to make room for the root-page */
57610     MemPage *pPageMove; /* The page to move to. */
57611 
57612     /* Creating a new table may probably require moving an existing database
57613     ** to make room for the new tables root page. In case this page turns
57614     ** out to be an overflow page, delete all overflow page-map caches
57615     ** held by open cursors.
57616     */
57617     invalidateAllOverflowCache(pBt);
57618 
57619     /* Read the value of meta[3] from the database to determine where the
57620     ** root page of the new table should go. meta[3] is the largest root-page
57621     ** created so far, so the new root-page is (meta[3]+1).
57622     */
57623     sqlite3BtreeGetMeta(p, BTREE_LARGEST_ROOT_PAGE, &pgnoRoot);
57624     pgnoRoot++;
57625 
57626     /* The new root-page may not be allocated on a pointer-map page, or the
57627     ** PENDING_BYTE page.
57628     */
57629     while( pgnoRoot==PTRMAP_PAGENO(pBt, pgnoRoot) ||
57630         pgnoRoot==PENDING_BYTE_PAGE(pBt) ){
57631       pgnoRoot++;
57632     }
57633     assert( pgnoRoot>=3 );
57634 
57635     /* Allocate a page. The page that currently resides at pgnoRoot will
57636     ** be moved to the allocated page (unless the allocated page happens
57637     ** to reside at pgnoRoot).
57638     */
57639     rc = allocateBtreePage(pBt, &pPageMove, &pgnoMove, pgnoRoot, BTALLOC_EXACT);
57640     if( rc!=SQLITE_OK ){
57641       return rc;
57642     }
57643 
57644     if( pgnoMove!=pgnoRoot ){
57645       /* pgnoRoot is the page that will be used for the root-page of
57646       ** the new table (assuming an error did not occur). But we were
57647       ** allocated pgnoMove. If required (i.e. if it was not allocated
57648       ** by extending the file), the current page at position pgnoMove
57649       ** is already journaled.
57650       */
57651       u8 eType = 0;
57652       Pgno iPtrPage = 0;
57653 
57654       /* Save the positions of any open cursors. This is required in
57655       ** case they are holding a reference to an xFetch reference
57656       ** corresponding to page pgnoRoot.  */
57657       rc = saveAllCursors(pBt, 0, 0);
57658       releasePage(pPageMove);
57659       if( rc!=SQLITE_OK ){
57660         return rc;
57661       }
57662 
57663       /* Move the page currently at pgnoRoot to pgnoMove. */
57664       rc = btreeGetPage(pBt, pgnoRoot, &pRoot, 0);
57665       if( rc!=SQLITE_OK ){
57666         return rc;
57667       }
57668       rc = ptrmapGet(pBt, pgnoRoot, &eType, &iPtrPage);
57669       if( eType==PTRMAP_ROOTPAGE || eType==PTRMAP_FREEPAGE ){
57670         rc = SQLITE_CORRUPT_BKPT;
57671       }
57672       if( rc!=SQLITE_OK ){
57673         releasePage(pRoot);
57674         return rc;
57675       }
57676       assert( eType!=PTRMAP_ROOTPAGE );
57677       assert( eType!=PTRMAP_FREEPAGE );
57678       rc = relocatePage(pBt, pRoot, eType, iPtrPage, pgnoMove, 0);
57679       releasePage(pRoot);
57680 
57681       /* Obtain the page at pgnoRoot */
57682       if( rc!=SQLITE_OK ){
57683         return rc;
57684       }
57685       rc = btreeGetPage(pBt, pgnoRoot, &pRoot, 0);
57686       if( rc!=SQLITE_OK ){
57687         return rc;
57688       }
57689       rc = sqlite3PagerWrite(pRoot->pDbPage);
57690       if( rc!=SQLITE_OK ){
57691         releasePage(pRoot);
57692         return rc;
57693       }
57694     }else{
57695       pRoot = pPageMove;
57696     } 
57697 
57698     /* Update the pointer-map and meta-data with the new root-page number. */
57699     ptrmapPut(pBt, pgnoRoot, PTRMAP_ROOTPAGE, 0, &rc);
57700     if( rc ){
57701       releasePage(pRoot);
57702       return rc;
57703     }
57704 
57705     /* When the new root page was allocated, page 1 was made writable in
57706     ** order either to increase the database filesize, or to decrement the
57707     ** freelist count.  Hence, the sqlite3BtreeUpdateMeta() call cannot fail.
57708     */
57709     assert( sqlite3PagerIswriteable(pBt->pPage1->pDbPage) );
57710     rc = sqlite3BtreeUpdateMeta(p, 4, pgnoRoot);
57711     if( NEVER(rc) ){
57712       releasePage(pRoot);
57713       return rc;
57714     }
57715 
57716   }else{
57717     rc = allocateBtreePage(pBt, &pRoot, &pgnoRoot, 1, 0);
57718     if( rc ) return rc;
57719   }
57720 #endif
57721   assert( sqlite3PagerIswriteable(pRoot->pDbPage) );
57722   if( createTabFlags & BTREE_INTKEY ){
57723     ptfFlags = PTF_INTKEY | PTF_LEAFDATA | PTF_LEAF;
57724   }else{
57725     ptfFlags = PTF_ZERODATA | PTF_LEAF;
57726   }
57727   zeroPage(pRoot, ptfFlags);
57728   sqlite3PagerUnref(pRoot->pDbPage);
57729   assert( (pBt->openFlags & BTREE_SINGLE)==0 || pgnoRoot==2 );
57730   *piTable = (int)pgnoRoot;
57731   return SQLITE_OK;
57732 }
57733 SQLITE_PRIVATE int sqlite3BtreeCreateTable(Btree *p, int *piTable, int flags){
57734   int rc;
57735   sqlite3BtreeEnter(p);
57736   rc = btreeCreateTable(p, piTable, flags);
57737   sqlite3BtreeLeave(p);
57738   return rc;
57739 }
57740 
57741 /*
57742 ** Erase the given database page and all its children.  Return
57743 ** the page to the freelist.
57744 */
57745 static int clearDatabasePage(
57746   BtShared *pBt,           /* The BTree that contains the table */
57747   Pgno pgno,               /* Page number to clear */
57748   int freePageFlag,        /* Deallocate page if true */
57749   int *pnChange            /* Add number of Cells freed to this counter */
57750 ){
57751   MemPage *pPage;
57752   int rc;
57753   unsigned char *pCell;
57754   int i;
57755 
57756   assert( sqlite3_mutex_held(pBt->mutex) );
57757   if( pgno>btreePagecount(pBt) ){
57758     return SQLITE_CORRUPT_BKPT;
57759   }
57760 
57761   rc = getAndInitPage(pBt, pgno, &pPage, 0);
57762   if( rc ) return rc;
57763   for(i=0; i<pPage->nCell; i++){
57764     pCell = findCell(pPage, i);
57765     if( !pPage->leaf ){
57766       rc = clearDatabasePage(pBt, get4byte(pCell), 1, pnChange);
57767       if( rc ) goto cleardatabasepage_out;
57768     }
57769     rc = clearCell(pPage, pCell);
57770     if( rc ) goto cleardatabasepage_out;
57771   }
57772   if( !pPage->leaf ){
57773     rc = clearDatabasePage(pBt, get4byte(&pPage->aData[8]), 1, pnChange);
57774     if( rc ) goto cleardatabasepage_out;
57775   }else if( pnChange ){
57776     assert( pPage->intKey );
57777     *pnChange += pPage->nCell;
57778   }
57779   if( freePageFlag ){
57780     freePage(pPage, &rc);
57781   }else if( (rc = sqlite3PagerWrite(pPage->pDbPage))==0 ){
57782     zeroPage(pPage, pPage->aData[0] | PTF_LEAF);
57783   }
57784 
57785 cleardatabasepage_out:
57786   releasePage(pPage);
57787   return rc;
57788 }
57789 
57790 /*
57791 ** Delete all information from a single table in the database.  iTable is
57792 ** the page number of the root of the table.  After this routine returns,
57793 ** the root page is empty, but still exists.
57794 **
57795 ** This routine will fail with SQLITE_LOCKED if there are any open
57796 ** read cursors on the table.  Open write cursors are moved to the
57797 ** root of the table.
57798 **
57799 ** If pnChange is not NULL, then table iTable must be an intkey table. The
57800 ** integer value pointed to by pnChange is incremented by the number of
57801 ** entries in the table.
57802 */
57803 SQLITE_PRIVATE int sqlite3BtreeClearTable(Btree *p, int iTable, int *pnChange){
57804   int rc;
57805   BtShared *pBt = p->pBt;
57806   sqlite3BtreeEnter(p);
57807   assert( p->inTrans==TRANS_WRITE );
57808 
57809   rc = saveAllCursors(pBt, (Pgno)iTable, 0);
57810 
57811   if( SQLITE_OK==rc ){
57812     /* Invalidate all incrblob cursors open on table iTable (assuming iTable
57813     ** is the root of a table b-tree - if it is not, the following call is
57814     ** a no-op).  */
57815     invalidateIncrblobCursors(p, 0, 1);
57816     rc = clearDatabasePage(pBt, (Pgno)iTable, 0, pnChange);
57817   }
57818   sqlite3BtreeLeave(p);
57819   return rc;
57820 }
57821 
57822 /*
57823 ** Erase all information in a table and add the root of the table to
57824 ** the freelist.  Except, the root of the principle table (the one on
57825 ** page 1) is never added to the freelist.
57826 **
57827 ** This routine will fail with SQLITE_LOCKED if there are any open
57828 ** cursors on the table.
57829 **
57830 ** If AUTOVACUUM is enabled and the page at iTable is not the last
57831 ** root page in the database file, then the last root page 
57832 ** in the database file is moved into the slot formerly occupied by
57833 ** iTable and that last slot formerly occupied by the last root page
57834 ** is added to the freelist instead of iTable.  In this say, all
57835 ** root pages are kept at the beginning of the database file, which
57836 ** is necessary for AUTOVACUUM to work right.  *piMoved is set to the 
57837 ** page number that used to be the last root page in the file before
57838 ** the move.  If no page gets moved, *piMoved is set to 0.
57839 ** The last root page is recorded in meta[3] and the value of
57840 ** meta[3] is updated by this procedure.
57841 */
57842 static int btreeDropTable(Btree *p, Pgno iTable, int *piMoved){
57843   int rc;
57844   MemPage *pPage = 0;
57845   BtShared *pBt = p->pBt;
57846 
57847   assert( sqlite3BtreeHoldsMutex(p) );
57848   assert( p->inTrans==TRANS_WRITE );
57849 
57850   /* It is illegal to drop a table if any cursors are open on the
57851   ** database. This is because in auto-vacuum mode the backend may
57852   ** need to move another root-page to fill a gap left by the deleted
57853   ** root page. If an open cursor was using this page a problem would 
57854   ** occur.
57855   **
57856   ** This error is caught long before control reaches this point.
57857   */
57858   if( NEVER(pBt->pCursor) ){
57859     sqlite3ConnectionBlocked(p->db, pBt->pCursor->pBtree->db);
57860     return SQLITE_LOCKED_SHAREDCACHE;
57861   }
57862 
57863   rc = btreeGetPage(pBt, (Pgno)iTable, &pPage, 0);
57864   if( rc ) return rc;
57865   rc = sqlite3BtreeClearTable(p, iTable, 0);
57866   if( rc ){
57867     releasePage(pPage);
57868     return rc;
57869   }
57870 
57871   *piMoved = 0;
57872 
57873   if( iTable>1 ){
57874 #ifdef SQLITE_OMIT_AUTOVACUUM
57875     freePage(pPage, &rc);
57876     releasePage(pPage);
57877 #else
57878     if( pBt->autoVacuum ){
57879       Pgno maxRootPgno;
57880       sqlite3BtreeGetMeta(p, BTREE_LARGEST_ROOT_PAGE, &maxRootPgno);
57881 
57882       if( iTable==maxRootPgno ){
57883         /* If the table being dropped is the table with the largest root-page
57884         ** number in the database, put the root page on the free list. 
57885         */
57886         freePage(pPage, &rc);
57887         releasePage(pPage);
57888         if( rc!=SQLITE_OK ){
57889           return rc;
57890         }
57891       }else{
57892         /* The table being dropped does not have the largest root-page
57893         ** number in the database. So move the page that does into the 
57894         ** gap left by the deleted root-page.
57895         */
57896         MemPage *pMove;
57897         releasePage(pPage);
57898         rc = btreeGetPage(pBt, maxRootPgno, &pMove, 0);
57899         if( rc!=SQLITE_OK ){
57900           return rc;
57901         }
57902         rc = relocatePage(pBt, pMove, PTRMAP_ROOTPAGE, 0, iTable, 0);
57903         releasePage(pMove);
57904         if( rc!=SQLITE_OK ){
57905           return rc;
57906         }
57907         pMove = 0;
57908         rc = btreeGetPage(pBt, maxRootPgno, &pMove, 0);
57909         freePage(pMove, &rc);
57910         releasePage(pMove);
57911         if( rc!=SQLITE_OK ){
57912           return rc;
57913         }
57914         *piMoved = maxRootPgno;
57915       }
57916 
57917       /* Set the new 'max-root-page' value in the database header. This
57918       ** is the old value less one, less one more if that happens to
57919       ** be a root-page number, less one again if that is the
57920       ** PENDING_BYTE_PAGE.
57921       */
57922       maxRootPgno--;
57923       while( maxRootPgno==PENDING_BYTE_PAGE(pBt)
57924              || PTRMAP_ISPAGE(pBt, maxRootPgno) ){
57925         maxRootPgno--;
57926       }
57927       assert( maxRootPgno!=PENDING_BYTE_PAGE(pBt) );
57928 
57929       rc = sqlite3BtreeUpdateMeta(p, 4, maxRootPgno);
57930     }else{
57931       freePage(pPage, &rc);
57932       releasePage(pPage);
57933     }
57934 #endif
57935   }else{
57936     /* If sqlite3BtreeDropTable was called on page 1.
57937     ** This really never should happen except in a corrupt
57938     ** database. 
57939     */
57940     zeroPage(pPage, PTF_INTKEY|PTF_LEAF );
57941     releasePage(pPage);
57942   }
57943   return rc;  
57944 }
57945 SQLITE_PRIVATE int sqlite3BtreeDropTable(Btree *p, int iTable, int *piMoved){
57946   int rc;
57947   sqlite3BtreeEnter(p);
57948   rc = btreeDropTable(p, iTable, piMoved);
57949   sqlite3BtreeLeave(p);
57950   return rc;
57951 }
57952 
57953 
57954 /*
57955 ** This function may only be called if the b-tree connection already
57956 ** has a read or write transaction open on the database.
57957 **
57958 ** Read the meta-information out of a database file.  Meta[0]
57959 ** is the number of free pages currently in the database.  Meta[1]
57960 ** through meta[15] are available for use by higher layers.  Meta[0]
57961 ** is read-only, the others are read/write.
57962 ** 
57963 ** The schema layer numbers meta values differently.  At the schema
57964 ** layer (and the SetCookie and ReadCookie opcodes) the number of
57965 ** free pages is not visible.  So Cookie[0] is the same as Meta[1].
57966 */
57967 SQLITE_PRIVATE void sqlite3BtreeGetMeta(Btree *p, int idx, u32 *pMeta){
57968   BtShared *pBt = p->pBt;
57969 
57970   sqlite3BtreeEnter(p);
57971   assert( p->inTrans>TRANS_NONE );
57972   assert( SQLITE_OK==querySharedCacheTableLock(p, MASTER_ROOT, READ_LOCK) );
57973   assert( pBt->pPage1 );
57974   assert( idx>=0 && idx<=15 );
57975 
57976   *pMeta = get4byte(&pBt->pPage1->aData[36 + idx*4]);
57977 
57978   /* If auto-vacuum is disabled in this build and this is an auto-vacuum
57979   ** database, mark the database as read-only.  */
57980 #ifdef SQLITE_OMIT_AUTOVACUUM
57981   if( idx==BTREE_LARGEST_ROOT_PAGE && *pMeta>0 ){
57982     pBt->btsFlags |= BTS_READ_ONLY;
57983   }
57984 #endif
57985 
57986   sqlite3BtreeLeave(p);
57987 }
57988 
57989 /*
57990 ** Write meta-information back into the database.  Meta[0] is
57991 ** read-only and may not be written.
57992 */
57993 SQLITE_PRIVATE int sqlite3BtreeUpdateMeta(Btree *p, int idx, u32 iMeta){
57994   BtShared *pBt = p->pBt;
57995   unsigned char *pP1;
57996   int rc;
57997   assert( idx>=1 && idx<=15 );
57998   sqlite3BtreeEnter(p);
57999   assert( p->inTrans==TRANS_WRITE );
58000   assert( pBt->pPage1!=0 );
58001   pP1 = pBt->pPage1->aData;
58002   rc = sqlite3PagerWrite(pBt->pPage1->pDbPage);
58003   if( rc==SQLITE_OK ){
58004     put4byte(&pP1[36 + idx*4], iMeta);
58005 #ifndef SQLITE_OMIT_AUTOVACUUM
58006     if( idx==BTREE_INCR_VACUUM ){
58007       assert( pBt->autoVacuum || iMeta==0 );
58008       assert( iMeta==0 || iMeta==1 );
58009       pBt->incrVacuum = (u8)iMeta;
58010     }
58011 #endif
58012   }
58013   sqlite3BtreeLeave(p);
58014   return rc;
58015 }
58016 
58017 #ifndef SQLITE_OMIT_BTREECOUNT
58018 /*
58019 ** The first argument, pCur, is a cursor opened on some b-tree. Count the
58020 ** number of entries in the b-tree and write the result to *pnEntry.
58021 **
58022 ** SQLITE_OK is returned if the operation is successfully executed. 
58023 ** Otherwise, if an error is encountered (i.e. an IO error or database
58024 ** corruption) an SQLite error code is returned.
58025 */
58026 SQLITE_PRIVATE int sqlite3BtreeCount(BtCursor *pCur, i64 *pnEntry){
58027   i64 nEntry = 0;                      /* Value to return in *pnEntry */
58028   int rc;                              /* Return code */
58029 
58030   if( pCur->pgnoRoot==0 ){
58031     *pnEntry = 0;
58032     return SQLITE_OK;
58033   }
58034   rc = moveToRoot(pCur);
58035 
58036   /* Unless an error occurs, the following loop runs one iteration for each
58037   ** page in the B-Tree structure (not including overflow pages). 
58038   */
58039   while( rc==SQLITE_OK ){
58040     int iIdx;                          /* Index of child node in parent */
58041     MemPage *pPage;                    /* Current page of the b-tree */
58042 
58043     /* If this is a leaf page or the tree is not an int-key tree, then 
58044     ** this page contains countable entries. Increment the entry counter
58045     ** accordingly.
58046     */
58047     pPage = pCur->apPage[pCur->iPage];
58048     if( pPage->leaf || !pPage->intKey ){
58049       nEntry += pPage->nCell;
58050     }
58051 
58052     /* pPage is a leaf node. This loop navigates the cursor so that it 
58053     ** points to the first interior cell that it points to the parent of
58054     ** the next page in the tree that has not yet been visited. The
58055     ** pCur->aiIdx[pCur->iPage] value is set to the index of the parent cell
58056     ** of the page, or to the number of cells in the page if the next page
58057     ** to visit is the right-child of its parent.
58058     **
58059     ** If all pages in the tree have been visited, return SQLITE_OK to the
58060     ** caller.
58061     */
58062     if( pPage->leaf ){
58063       do {
58064         if( pCur->iPage==0 ){
58065           /* All pages of the b-tree have been visited. Return successfully. */
58066           *pnEntry = nEntry;
58067           return SQLITE_OK;
58068         }
58069         moveToParent(pCur);
58070       }while ( pCur->aiIdx[pCur->iPage]>=pCur->apPage[pCur->iPage]->nCell );
58071 
58072       pCur->aiIdx[pCur->iPage]++;
58073       pPage = pCur->apPage[pCur->iPage];
58074     }
58075 
58076     /* Descend to the child node of the cell that the cursor currently 
58077     ** points at. This is the right-child if (iIdx==pPage->nCell).
58078     */
58079     iIdx = pCur->aiIdx[pCur->iPage];
58080     if( iIdx==pPage->nCell ){
58081       rc = moveToChild(pCur, get4byte(&pPage->aData[pPage->hdrOffset+8]));
58082     }else{
58083       rc = moveToChild(pCur, get4byte(findCell(pPage, iIdx)));
58084     }
58085   }
58086 
58087   /* An error has occurred. Return an error code. */
58088   return rc;
58089 }
58090 #endif
58091 
58092 /*
58093 ** Return the pager associated with a BTree.  This routine is used for
58094 ** testing and debugging only.
58095 */
58096 SQLITE_PRIVATE Pager *sqlite3BtreePager(Btree *p){
58097   return p->pBt->pPager;
58098 }
58099 
58100 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
58101 /*
58102 ** Append a message to the error message string.
58103 */
58104 static void checkAppendMsg(
58105   IntegrityCk *pCheck,
58106   char *zMsg1,
58107   const char *zFormat,
58108   ...
58109 ){
58110   va_list ap;
58111   if( !pCheck->mxErr ) return;
58112   pCheck->mxErr--;
58113   pCheck->nErr++;
58114   va_start(ap, zFormat);
58115   if( pCheck->errMsg.nChar ){
58116     sqlite3StrAccumAppend(&pCheck->errMsg, "\n", 1);
58117   }
58118   if( zMsg1 ){
58119     sqlite3StrAccumAppend(&pCheck->errMsg, zMsg1, -1);
58120   }
58121   sqlite3VXPrintf(&pCheck->errMsg, 1, zFormat, ap);
58122   va_end(ap);
58123   if( pCheck->errMsg.accError==STRACCUM_NOMEM ){
58124     pCheck->mallocFailed = 1;
58125   }
58126 }
58127 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
58128 
58129 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
58130 
58131 /*
58132 ** Return non-zero if the bit in the IntegrityCk.aPgRef[] array that
58133 ** corresponds to page iPg is already set.
58134 */
58135 static int getPageReferenced(IntegrityCk *pCheck, Pgno iPg){
58136   assert( iPg<=pCheck->nPage && sizeof(pCheck->aPgRef[0])==1 );
58137   return (pCheck->aPgRef[iPg/8] & (1 << (iPg & 0x07)));
58138 }
58139 
58140 /*
58141 ** Set the bit in the IntegrityCk.aPgRef[] array that corresponds to page iPg.
58142 */
58143 static void setPageReferenced(IntegrityCk *pCheck, Pgno iPg){
58144   assert( iPg<=pCheck->nPage && sizeof(pCheck->aPgRef[0])==1 );
58145   pCheck->aPgRef[iPg/8] |= (1 << (iPg & 0x07));
58146 }
58147 
58148 
58149 /*
58150 ** Add 1 to the reference count for page iPage.  If this is the second
58151 ** reference to the page, add an error message to pCheck->zErrMsg.
58152 ** Return 1 if there are 2 ore more references to the page and 0 if
58153 ** if this is the first reference to the page.
58154 **
58155 ** Also check that the page number is in bounds.
58156 */
58157 static int checkRef(IntegrityCk *pCheck, Pgno iPage, char *zContext){
58158   if( iPage==0 ) return 1;
58159   if( iPage>pCheck->nPage ){
58160     checkAppendMsg(pCheck, zContext, "invalid page number %d", iPage);
58161     return 1;
58162   }
58163   if( getPageReferenced(pCheck, iPage) ){
58164     checkAppendMsg(pCheck, zContext, "2nd reference to page %d", iPage);
58165     return 1;
58166   }
58167   setPageReferenced(pCheck, iPage);
58168   return 0;
58169 }
58170 
58171 #ifndef SQLITE_OMIT_AUTOVACUUM
58172 /*
58173 ** Check that the entry in the pointer-map for page iChild maps to 
58174 ** page iParent, pointer type ptrType. If not, append an error message
58175 ** to pCheck.
58176 */
58177 static void checkPtrmap(
58178   IntegrityCk *pCheck,   /* Integrity check context */
58179   Pgno iChild,           /* Child page number */
58180   u8 eType,              /* Expected pointer map type */
58181   Pgno iParent,          /* Expected pointer map parent page number */
58182   char *zContext         /* Context description (used for error msg) */
58183 ){
58184   int rc;
58185   u8 ePtrmapType;
58186   Pgno iPtrmapParent;
58187 
58188   rc = ptrmapGet(pCheck->pBt, iChild, &ePtrmapType, &iPtrmapParent);
58189   if( rc!=SQLITE_OK ){
58190     if( rc==SQLITE_NOMEM || rc==SQLITE_IOERR_NOMEM ) pCheck->mallocFailed = 1;
58191     checkAppendMsg(pCheck, zContext, "Failed to read ptrmap key=%d", iChild);
58192     return;
58193   }
58194 
58195   if( ePtrmapType!=eType || iPtrmapParent!=iParent ){
58196     checkAppendMsg(pCheck, zContext, 
58197       "Bad ptr map entry key=%d expected=(%d,%d) got=(%d,%d)", 
58198       iChild, eType, iParent, ePtrmapType, iPtrmapParent);
58199   }
58200 }
58201 #endif
58202 
58203 /*
58204 ** Check the integrity of the freelist or of an overflow page list.
58205 ** Verify that the number of pages on the list is N.
58206 */
58207 static void checkList(
58208   IntegrityCk *pCheck,  /* Integrity checking context */
58209   int isFreeList,       /* True for a freelist.  False for overflow page list */
58210   int iPage,            /* Page number for first page in the list */
58211   int N,                /* Expected number of pages in the list */
58212   char *zContext        /* Context for error messages */
58213 ){
58214   int i;
58215   int expected = N;
58216   int iFirst = iPage;
58217   while( N-- > 0 && pCheck->mxErr ){
58218     DbPage *pOvflPage;
58219     unsigned char *pOvflData;
58220     if( iPage<1 ){
58221       checkAppendMsg(pCheck, zContext,
58222          "%d of %d pages missing from overflow list starting at %d",
58223           N+1, expected, iFirst);
58224       break;
58225     }
58226     if( checkRef(pCheck, iPage, zContext) ) break;
58227     if( sqlite3PagerGet(pCheck->pPager, (Pgno)iPage, &pOvflPage) ){
58228       checkAppendMsg(pCheck, zContext, "failed to get page %d", iPage);
58229       break;
58230     }
58231     pOvflData = (unsigned char *)sqlite3PagerGetData(pOvflPage);
58232     if( isFreeList ){
58233       int n = get4byte(&pOvflData[4]);
58234 #ifndef SQLITE_OMIT_AUTOVACUUM
58235       if( pCheck->pBt->autoVacuum ){
58236         checkPtrmap(pCheck, iPage, PTRMAP_FREEPAGE, 0, zContext);
58237       }
58238 #endif
58239       if( n>(int)pCheck->pBt->usableSize/4-2 ){
58240         checkAppendMsg(pCheck, zContext,
58241            "freelist leaf count too big on page %d", iPage);
58242         N--;
58243       }else{
58244         for(i=0; i<n; i++){
58245           Pgno iFreePage = get4byte(&pOvflData[8+i*4]);
58246 #ifndef SQLITE_OMIT_AUTOVACUUM
58247           if( pCheck->pBt->autoVacuum ){
58248             checkPtrmap(pCheck, iFreePage, PTRMAP_FREEPAGE, 0, zContext);
58249           }
58250 #endif
58251           checkRef(pCheck, iFreePage, zContext);
58252         }
58253         N -= n;
58254       }
58255     }
58256 #ifndef SQLITE_OMIT_AUTOVACUUM
58257     else{
58258       /* If this database supports auto-vacuum and iPage is not the last
58259       ** page in this overflow list, check that the pointer-map entry for
58260       ** the following page matches iPage.
58261       */
58262       if( pCheck->pBt->autoVacuum && N>0 ){
58263         i = get4byte(pOvflData);
58264         checkPtrmap(pCheck, i, PTRMAP_OVERFLOW2, iPage, zContext);
58265       }
58266     }
58267 #endif
58268     iPage = get4byte(pOvflData);
58269     sqlite3PagerUnref(pOvflPage);
58270   }
58271 }
58272 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
58273 
58274 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
58275 /*
58276 ** Do various sanity checks on a single page of a tree.  Return
58277 ** the tree depth.  Root pages return 0.  Parents of root pages
58278 ** return 1, and so forth.
58279 ** 
58280 ** These checks are done:
58281 **
58282 **      1.  Make sure that cells and freeblocks do not overlap
58283 **          but combine to completely cover the page.
58284 **  NO  2.  Make sure cell keys are in order.
58285 **  NO  3.  Make sure no key is less than or equal to zLowerBound.
58286 **  NO  4.  Make sure no key is greater than or equal to zUpperBound.
58287 **      5.  Check the integrity of overflow pages.
58288 **      6.  Recursively call checkTreePage on all children.
58289 **      7.  Verify that the depth of all children is the same.
58290 **      8.  Make sure this page is at least 33% full or else it is
58291 **          the root of the tree.
58292 */
58293 static int checkTreePage(
58294   IntegrityCk *pCheck,  /* Context for the sanity check */
58295   int iPage,            /* Page number of the page to check */
58296   char *zParentContext, /* Parent context */
58297   i64 *pnParentMinKey, 
58298   i64 *pnParentMaxKey
58299 ){
58300   MemPage *pPage;
58301   int i, rc, depth, d2, pgno, cnt;
58302   int hdr, cellStart;
58303   int nCell;
58304   u8 *data;
58305   BtShared *pBt;
58306   int usableSize;
58307   char zContext[100];
58308   char *hit = 0;
58309   i64 nMinKey = 0;
58310   i64 nMaxKey = 0;
58311 
58312   sqlite3_snprintf(sizeof(zContext), zContext, "Page %d: ", iPage);
58313 
58314   /* Check that the page exists
58315   */
58316   pBt = pCheck->pBt;
58317   usableSize = pBt->usableSize;
58318   if( iPage==0 ) return 0;
58319   if( checkRef(pCheck, iPage, zParentContext) ) return 0;
58320   if( (rc = btreeGetPage(pBt, (Pgno)iPage, &pPage, 0))!=0 ){
58321     checkAppendMsg(pCheck, zContext,
58322        "unable to get the page. error code=%d", rc);
58323     return 0;
58324   }
58325 
58326   /* Clear MemPage.isInit to make sure the corruption detection code in
58327   ** btreeInitPage() is executed.  */
58328   pPage->isInit = 0;
58329   if( (rc = btreeInitPage(pPage))!=0 ){
58330     assert( rc==SQLITE_CORRUPT );  /* The only possible error from InitPage */
58331     checkAppendMsg(pCheck, zContext, 
58332                    "btreeInitPage() returns error code %d", rc);
58333     releasePage(pPage);
58334     return 0;
58335   }
58336 
58337   /* Check out all the cells.
58338   */
58339   depth = 0;
58340   for(i=0; i<pPage->nCell && pCheck->mxErr; i++){
58341     u8 *pCell;
58342     u32 sz;
58343     CellInfo info;
58344 
58345     /* Check payload overflow pages
58346     */
58347     sqlite3_snprintf(sizeof(zContext), zContext,
58348              "On tree page %d cell %d: ", iPage, i);
58349     pCell = findCell(pPage,i);
58350     btreeParseCellPtr(pPage, pCell, &info);
58351     sz = info.nData;
58352     if( !pPage->intKey ) sz += (int)info.nKey;
58353     /* For intKey pages, check that the keys are in order.
58354     */
58355     else if( i==0 ) nMinKey = nMaxKey = info.nKey;
58356     else{
58357       if( info.nKey <= nMaxKey ){
58358         checkAppendMsg(pCheck, zContext, 
58359             "Rowid %lld out of order (previous was %lld)", info.nKey, nMaxKey);
58360       }
58361       nMaxKey = info.nKey;
58362     }
58363     assert( sz==info.nPayload );
58364     if( (sz>info.nLocal) 
58365      && (&pCell[info.iOverflow]<=&pPage->aData[pBt->usableSize])
58366     ){
58367       int nPage = (sz - info.nLocal + usableSize - 5)/(usableSize - 4);
58368       Pgno pgnoOvfl = get4byte(&pCell[info.iOverflow]);
58369 #ifndef SQLITE_OMIT_AUTOVACUUM
58370       if( pBt->autoVacuum ){
58371         checkPtrmap(pCheck, pgnoOvfl, PTRMAP_OVERFLOW1, iPage, zContext);
58372       }
58373 #endif
58374       checkList(pCheck, 0, pgnoOvfl, nPage, zContext);
58375     }
58376 
58377     /* Check sanity of left child page.
58378     */
58379     if( !pPage->leaf ){
58380       pgno = get4byte(pCell);
58381 #ifndef SQLITE_OMIT_AUTOVACUUM
58382       if( pBt->autoVacuum ){
58383         checkPtrmap(pCheck, pgno, PTRMAP_BTREE, iPage, zContext);
58384       }
58385 #endif
58386       d2 = checkTreePage(pCheck, pgno, zContext, &nMinKey, i==0 ? NULL : &nMaxKey);
58387       if( i>0 && d2!=depth ){
58388         checkAppendMsg(pCheck, zContext, "Child page depth differs");
58389       }
58390       depth = d2;
58391     }
58392   }
58393 
58394   if( !pPage->leaf ){
58395     pgno = get4byte(&pPage->aData[pPage->hdrOffset+8]);
58396     sqlite3_snprintf(sizeof(zContext), zContext, 
58397                      "On page %d at right child: ", iPage);
58398 #ifndef SQLITE_OMIT_AUTOVACUUM
58399     if( pBt->autoVacuum ){
58400       checkPtrmap(pCheck, pgno, PTRMAP_BTREE, iPage, zContext);
58401     }
58402 #endif
58403     checkTreePage(pCheck, pgno, zContext, NULL, !pPage->nCell ? NULL : &nMaxKey);
58404   }
58405  
58406   /* For intKey leaf pages, check that the min/max keys are in order
58407   ** with any left/parent/right pages.
58408   */
58409   if( pPage->leaf && pPage->intKey ){
58410     /* if we are a left child page */
58411     if( pnParentMinKey ){
58412       /* if we are the left most child page */
58413       if( !pnParentMaxKey ){
58414         if( nMaxKey > *pnParentMinKey ){
58415           checkAppendMsg(pCheck, zContext, 
58416               "Rowid %lld out of order (max larger than parent min of %lld)",
58417               nMaxKey, *pnParentMinKey);
58418         }
58419       }else{
58420         if( nMinKey <= *pnParentMinKey ){
58421           checkAppendMsg(pCheck, zContext, 
58422               "Rowid %lld out of order (min less than parent min of %lld)",
58423               nMinKey, *pnParentMinKey);
58424         }
58425         if( nMaxKey > *pnParentMaxKey ){
58426           checkAppendMsg(pCheck, zContext, 
58427               "Rowid %lld out of order (max larger than parent max of %lld)",
58428               nMaxKey, *pnParentMaxKey);
58429         }
58430         *pnParentMinKey = nMaxKey;
58431       }
58432     /* else if we're a right child page */
58433     } else if( pnParentMaxKey ){
58434       if( nMinKey <= *pnParentMaxKey ){
58435         checkAppendMsg(pCheck, zContext, 
58436             "Rowid %lld out of order (min less than parent max of %lld)",
58437             nMinKey, *pnParentMaxKey);
58438       }
58439     }
58440   }
58441 
58442   /* Check for complete coverage of the page
58443   */
58444   data = pPage->aData;
58445   hdr = pPage->hdrOffset;
58446   hit = sqlite3PageMalloc( pBt->pageSize );
58447   if( hit==0 ){
58448     pCheck->mallocFailed = 1;
58449   }else{
58450     int contentOffset = get2byteNotZero(&data[hdr+5]);
58451     assert( contentOffset<=usableSize );  /* Enforced by btreeInitPage() */
58452     memset(hit+contentOffset, 0, usableSize-contentOffset);
58453     memset(hit, 1, contentOffset);
58454     nCell = get2byte(&data[hdr+3]);
58455     cellStart = hdr + 12 - 4*pPage->leaf;
58456     for(i=0; i<nCell; i++){
58457       int pc = get2byte(&data[cellStart+i*2]);
58458       u32 size = 65536;
58459       int j;
58460       if( pc<=usableSize-4 ){
58461         size = cellSizePtr(pPage, &data[pc]);
58462       }
58463       if( (int)(pc+size-1)>=usableSize ){
58464         checkAppendMsg(pCheck, 0, 
58465             "Corruption detected in cell %d on page %d",i,iPage);
58466       }else{
58467         for(j=pc+size-1; j>=pc; j--) hit[j]++;
58468       }
58469     }
58470     i = get2byte(&data[hdr+1]);
58471     while( i>0 ){
58472       int size, j;
58473       assert( i<=usableSize-4 );     /* Enforced by btreeInitPage() */
58474       size = get2byte(&data[i+2]);
58475       assert( i+size<=usableSize );  /* Enforced by btreeInitPage() */
58476       for(j=i+size-1; j>=i; j--) hit[j]++;
58477       j = get2byte(&data[i]);
58478       assert( j==0 || j>i+size );  /* Enforced by btreeInitPage() */
58479       assert( j<=usableSize-4 );   /* Enforced by btreeInitPage() */
58480       i = j;
58481     }
58482     for(i=cnt=0; i<usableSize; i++){
58483       if( hit[i]==0 ){
58484         cnt++;
58485       }else if( hit[i]>1 ){
58486         checkAppendMsg(pCheck, 0,
58487           "Multiple uses for byte %d of page %d", i, iPage);
58488         break;
58489       }
58490     }
58491     if( cnt!=data[hdr+7] ){
58492       checkAppendMsg(pCheck, 0, 
58493           "Fragmentation of %d bytes reported as %d on page %d",
58494           cnt, data[hdr+7], iPage);
58495     }
58496   }
58497   sqlite3PageFree(hit);
58498   releasePage(pPage);
58499   return depth+1;
58500 }
58501 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
58502 
58503 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
58504 /*
58505 ** This routine does a complete check of the given BTree file.  aRoot[] is
58506 ** an array of pages numbers were each page number is the root page of
58507 ** a table.  nRoot is the number of entries in aRoot.
58508 **
58509 ** A read-only or read-write transaction must be opened before calling
58510 ** this function.
58511 **
58512 ** Write the number of error seen in *pnErr.  Except for some memory
58513 ** allocation errors,  an error message held in memory obtained from
58514 ** malloc is returned if *pnErr is non-zero.  If *pnErr==0 then NULL is
58515 ** returned.  If a memory allocation error occurs, NULL is returned.
58516 */
58517 SQLITE_PRIVATE char *sqlite3BtreeIntegrityCheck(
58518   Btree *p,     /* The btree to be checked */
58519   int *aRoot,   /* An array of root pages numbers for individual trees */
58520   int nRoot,    /* Number of entries in aRoot[] */
58521   int mxErr,    /* Stop reporting errors after this many */
58522   int *pnErr    /* Write number of errors seen to this variable */
58523 ){
58524   Pgno i;
58525   int nRef;
58526   IntegrityCk sCheck;
58527   BtShared *pBt = p->pBt;
58528   char zErr[100];
58529 
58530   sqlite3BtreeEnter(p);
58531   assert( p->inTrans>TRANS_NONE && pBt->inTransaction>TRANS_NONE );
58532   nRef = sqlite3PagerRefcount(pBt->pPager);
58533   sCheck.pBt = pBt;
58534   sCheck.pPager = pBt->pPager;
58535   sCheck.nPage = btreePagecount(sCheck.pBt);
58536   sCheck.mxErr = mxErr;
58537   sCheck.nErr = 0;
58538   sCheck.mallocFailed = 0;
58539   *pnErr = 0;
58540   if( sCheck.nPage==0 ){
58541     sqlite3BtreeLeave(p);
58542     return 0;
58543   }
58544 
58545   sCheck.aPgRef = sqlite3MallocZero((sCheck.nPage / 8)+ 1);
58546   if( !sCheck.aPgRef ){
58547     *pnErr = 1;
58548     sqlite3BtreeLeave(p);
58549     return 0;
58550   }
58551   i = PENDING_BYTE_PAGE(pBt);
58552   if( i<=sCheck.nPage ) setPageReferenced(&sCheck, i);
58553   sqlite3StrAccumInit(&sCheck.errMsg, zErr, sizeof(zErr), SQLITE_MAX_LENGTH);
58554   sCheck.errMsg.useMalloc = 2;
58555 
58556   /* Check the integrity of the freelist
58557   */
58558   checkList(&sCheck, 1, get4byte(&pBt->pPage1->aData[32]),
58559             get4byte(&pBt->pPage1->aData[36]), "Main freelist: ");
58560 
58561   /* Check all the tables.
58562   */
58563   for(i=0; (int)i<nRoot && sCheck.mxErr; i++){
58564     if( aRoot[i]==0 ) continue;
58565 #ifndef SQLITE_OMIT_AUTOVACUUM
58566     if( pBt->autoVacuum && aRoot[i]>1 ){
58567       checkPtrmap(&sCheck, aRoot[i], PTRMAP_ROOTPAGE, 0, 0);
58568     }
58569 #endif
58570     checkTreePage(&sCheck, aRoot[i], "List of tree roots: ", NULL, NULL);
58571   }
58572 
58573   /* Make sure every page in the file is referenced
58574   */
58575   for(i=1; i<=sCheck.nPage && sCheck.mxErr; i++){
58576 #ifdef SQLITE_OMIT_AUTOVACUUM
58577     if( getPageReferenced(&sCheck, i)==0 ){
58578       checkAppendMsg(&sCheck, 0, "Page %d is never used", i);
58579     }
58580 #else
58581     /* If the database supports auto-vacuum, make sure no tables contain
58582     ** references to pointer-map pages.
58583     */
58584     if( getPageReferenced(&sCheck, i)==0 && 
58585        (PTRMAP_PAGENO(pBt, i)!=i || !pBt->autoVacuum) ){
58586       checkAppendMsg(&sCheck, 0, "Page %d is never used", i);
58587     }
58588     if( getPageReferenced(&sCheck, i)!=0 && 
58589        (PTRMAP_PAGENO(pBt, i)==i && pBt->autoVacuum) ){
58590       checkAppendMsg(&sCheck, 0, "Pointer map page %d is referenced", i);
58591     }
58592 #endif
58593   }
58594 
58595   /* Make sure this analysis did not leave any unref() pages.
58596   ** This is an internal consistency check; an integrity check
58597   ** of the integrity check.
58598   */
58599   if( NEVER(nRef != sqlite3PagerRefcount(pBt->pPager)) ){
58600     checkAppendMsg(&sCheck, 0, 
58601       "Outstanding page count goes from %d to %d during this analysis",
58602       nRef, sqlite3PagerRefcount(pBt->pPager)
58603     );
58604   }
58605 
58606   /* Clean  up and report errors.
58607   */
58608   sqlite3BtreeLeave(p);
58609   sqlite3_free(sCheck.aPgRef);
58610   if( sCheck.mallocFailed ){
58611     sqlite3StrAccumReset(&sCheck.errMsg);
58612     *pnErr = sCheck.nErr+1;
58613     return 0;
58614   }
58615   *pnErr = sCheck.nErr;
58616   if( sCheck.nErr==0 ) sqlite3StrAccumReset(&sCheck.errMsg);
58617   return sqlite3StrAccumFinish(&sCheck.errMsg);
58618 }
58619 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
58620 
58621 /*
58622 ** Return the full pathname of the underlying database file.  Return
58623 ** an empty string if the database is in-memory or a TEMP database.
58624 **
58625 ** The pager filename is invariant as long as the pager is
58626 ** open so it is safe to access without the BtShared mutex.
58627 */
58628 SQLITE_PRIVATE const char *sqlite3BtreeGetFilename(Btree *p){
58629   assert( p->pBt->pPager!=0 );
58630   return sqlite3PagerFilename(p->pBt->pPager, 1);
58631 }
58632 
58633 /*
58634 ** Return the pathname of the journal file for this database. The return
58635 ** value of this routine is the same regardless of whether the journal file
58636 ** has been created or not.
58637 **
58638 ** The pager journal filename is invariant as long as the pager is
58639 ** open so it is safe to access without the BtShared mutex.
58640 */
58641 SQLITE_PRIVATE const char *sqlite3BtreeGetJournalname(Btree *p){
58642   assert( p->pBt->pPager!=0 );
58643   return sqlite3PagerJournalname(p->pBt->pPager);
58644 }
58645 
58646 /*
58647 ** Return non-zero if a transaction is active.
58648 */
58649 SQLITE_PRIVATE int sqlite3BtreeIsInTrans(Btree *p){
58650   assert( p==0 || sqlite3_mutex_held(p->db->mutex) );
58651   return (p && (p->inTrans==TRANS_WRITE));
58652 }
58653 
58654 #ifndef SQLITE_OMIT_WAL
58655 /*
58656 ** Run a checkpoint on the Btree passed as the first argument.
58657 **
58658 ** Return SQLITE_LOCKED if this or any other connection has an open 
58659 ** transaction on the shared-cache the argument Btree is connected to.
58660 **
58661 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
58662 */
58663 SQLITE_PRIVATE int sqlite3BtreeCheckpoint(Btree *p, int eMode, int *pnLog, int *pnCkpt){
58664   int rc = SQLITE_OK;
58665   if( p ){
58666     BtShared *pBt = p->pBt;
58667     sqlite3BtreeEnter(p);
58668     if( pBt->inTransaction!=TRANS_NONE ){
58669       rc = SQLITE_LOCKED;
58670     }else{
58671       rc = sqlite3PagerCheckpoint(pBt->pPager, eMode, pnLog, pnCkpt);
58672     }
58673     sqlite3BtreeLeave(p);
58674   }
58675   return rc;
58676 }
58677 #endif
58678 
58679 /*
58680 ** Return non-zero if a read (or write) transaction is active.
58681 */
58682 SQLITE_PRIVATE int sqlite3BtreeIsInReadTrans(Btree *p){
58683   assert( p );
58684   assert( sqlite3_mutex_held(p->db->mutex) );
58685   return p->inTrans!=TRANS_NONE;
58686 }
58687 
58688 SQLITE_PRIVATE int sqlite3BtreeIsInBackup(Btree *p){
58689   assert( p );
58690   assert( sqlite3_mutex_held(p->db->mutex) );
58691   return p->nBackup!=0;
58692 }
58693 
58694 /*
58695 ** This function returns a pointer to a blob of memory associated with
58696 ** a single shared-btree. The memory is used by client code for its own
58697 ** purposes (for example, to store a high-level schema associated with 
58698 ** the shared-btree). The btree layer manages reference counting issues.
58699 **
58700 ** The first time this is called on a shared-btree, nBytes bytes of memory
58701 ** are allocated, zeroed, and returned to the caller. For each subsequent 
58702 ** call the nBytes parameter is ignored and a pointer to the same blob
58703 ** of memory returned. 
58704 **
58705 ** If the nBytes parameter is 0 and the blob of memory has not yet been
58706 ** allocated, a null pointer is returned. If the blob has already been
58707 ** allocated, it is returned as normal.
58708 **
58709 ** Just before the shared-btree is closed, the function passed as the 
58710 ** xFree argument when the memory allocation was made is invoked on the 
58711 ** blob of allocated memory. The xFree function should not call sqlite3_free()
58712 ** on the memory, the btree layer does that.
58713 */
58714 SQLITE_PRIVATE void *sqlite3BtreeSchema(Btree *p, int nBytes, void(*xFree)(void *)){
58715   BtShared *pBt = p->pBt;
58716   sqlite3BtreeEnter(p);
58717   if( !pBt->pSchema && nBytes ){
58718     pBt->pSchema = sqlite3DbMallocZero(0, nBytes);
58719     pBt->xFreeSchema = xFree;
58720   }
58721   sqlite3BtreeLeave(p);
58722   return pBt->pSchema;
58723 }
58724 
58725 /*
58726 ** Return SQLITE_LOCKED_SHAREDCACHE if another user of the same shared 
58727 ** btree as the argument handle holds an exclusive lock on the 
58728 ** sqlite_master table. Otherwise SQLITE_OK.
58729 */
58730 SQLITE_PRIVATE int sqlite3BtreeSchemaLocked(Btree *p){
58731   int rc;
58732   assert( sqlite3_mutex_held(p->db->mutex) );
58733   sqlite3BtreeEnter(p);
58734   rc = querySharedCacheTableLock(p, MASTER_ROOT, READ_LOCK);
58735   assert( rc==SQLITE_OK || rc==SQLITE_LOCKED_SHAREDCACHE );
58736   sqlite3BtreeLeave(p);
58737   return rc;
58738 }
58739 
58740 
58741 #ifndef SQLITE_OMIT_SHARED_CACHE
58742 /*
58743 ** Obtain a lock on the table whose root page is iTab.  The
58744 ** lock is a write lock if isWritelock is true or a read lock
58745 ** if it is false.
58746 */
58747 SQLITE_PRIVATE int sqlite3BtreeLockTable(Btree *p, int iTab, u8 isWriteLock){
58748   int rc = SQLITE_OK;
58749   assert( p->inTrans!=TRANS_NONE );
58750   if( p->sharable ){
58751     u8 lockType = READ_LOCK + isWriteLock;
58752     assert( READ_LOCK+1==WRITE_LOCK );
58753     assert( isWriteLock==0 || isWriteLock==1 );
58754 
58755     sqlite3BtreeEnter(p);
58756     rc = querySharedCacheTableLock(p, iTab, lockType);
58757     if( rc==SQLITE_OK ){
58758       rc = setSharedCacheTableLock(p, iTab, lockType);
58759     }
58760     sqlite3BtreeLeave(p);
58761   }
58762   return rc;
58763 }
58764 #endif
58765 
58766 #ifndef SQLITE_OMIT_INCRBLOB
58767 /*
58768 ** Argument pCsr must be a cursor opened for writing on an 
58769 ** INTKEY table currently pointing at a valid table entry. 
58770 ** This function modifies the data stored as part of that entry.
58771 **
58772 ** Only the data content may only be modified, it is not possible to 
58773 ** change the length of the data stored. If this function is called with
58774 ** parameters that attempt to write past the end of the existing data,
58775 ** no modifications are made and SQLITE_CORRUPT is returned.
58776 */
58777 SQLITE_PRIVATE int sqlite3BtreePutData(BtCursor *pCsr, u32 offset, u32 amt, void *z){
58778   int rc;
58779   assert( cursorHoldsMutex(pCsr) );
58780   assert( sqlite3_mutex_held(pCsr->pBtree->db->mutex) );
58781   assert( pCsr->isIncrblobHandle );
58782 
58783   rc = restoreCursorPosition(pCsr);
58784   if( rc!=SQLITE_OK ){
58785     return rc;
58786   }
58787   assert( pCsr->eState!=CURSOR_REQUIRESEEK );
58788   if( pCsr->eState!=CURSOR_VALID ){
58789     return SQLITE_ABORT;
58790   }
58791 
58792   /* Save the positions of all other cursors open on this table. This is
58793   ** required in case any of them are holding references to an xFetch
58794   ** version of the b-tree page modified by the accessPayload call below.
58795   **
58796   ** Note that pCsr must be open on a BTREE_INTKEY table and saveCursorPosition()
58797   ** and hence saveAllCursors() cannot fail on a BTREE_INTKEY table, hence
58798   ** saveAllCursors can only return SQLITE_OK.
58799   */
58800   VVA_ONLY(rc =) saveAllCursors(pCsr->pBt, pCsr->pgnoRoot, pCsr);
58801   assert( rc==SQLITE_OK );
58802 
58803   /* Check some assumptions: 
58804   **   (a) the cursor is open for writing,
58805   **   (b) there is a read/write transaction open,
58806   **   (c) the connection holds a write-lock on the table (if required),
58807   **   (d) there are no conflicting read-locks, and
58808   **   (e) the cursor points at a valid row of an intKey table.
58809   */
58810   if( !pCsr->wrFlag ){
58811     return SQLITE_READONLY;
58812   }
58813   assert( (pCsr->pBt->btsFlags & BTS_READ_ONLY)==0
58814               && pCsr->pBt->inTransaction==TRANS_WRITE );
58815   assert( hasSharedCacheTableLock(pCsr->pBtree, pCsr->pgnoRoot, 0, 2) );
58816   assert( !hasReadConflicts(pCsr->pBtree, pCsr->pgnoRoot) );
58817   assert( pCsr->apPage[pCsr->iPage]->intKey );
58818 
58819   return accessPayload(pCsr, offset, amt, (unsigned char *)z, 1);
58820 }
58821 
58822 /* 
58823 ** Set a flag on this cursor to cache the locations of pages from the 
58824 ** overflow list for the current row. This is used by cursors opened
58825 ** for incremental blob IO only.
58826 **
58827 ** This function sets a flag only. The actual page location cache
58828 ** (stored in BtCursor.aOverflow[]) is allocated and used by function
58829 ** accessPayload() (the worker function for sqlite3BtreeData() and
58830 ** sqlite3BtreePutData()).
58831 */
58832 SQLITE_PRIVATE void sqlite3BtreeCacheOverflow(BtCursor *pCur){
58833   assert( cursorHoldsMutex(pCur) );
58834   assert( sqlite3_mutex_held(pCur->pBtree->db->mutex) );
58835   invalidateOverflowCache(pCur);
58836   pCur->isIncrblobHandle = 1;
58837 }
58838 #endif
58839 
58840 /*
58841 ** Set both the "read version" (single byte at byte offset 18) and 
58842 ** "write version" (single byte at byte offset 19) fields in the database
58843 ** header to iVersion.
58844 */
58845 SQLITE_PRIVATE int sqlite3BtreeSetVersion(Btree *pBtree, int iVersion){
58846   BtShared *pBt = pBtree->pBt;
58847   int rc;                         /* Return code */
58848  
58849   assert( iVersion==1 || iVersion==2 );
58850 
58851   /* If setting the version fields to 1, do not automatically open the
58852   ** WAL connection, even if the version fields are currently set to 2.
58853   */
58854   pBt->btsFlags &= ~BTS_NO_WAL;
58855   if( iVersion==1 ) pBt->btsFlags |= BTS_NO_WAL;
58856 
58857   rc = sqlite3BtreeBeginTrans(pBtree, 0);
58858   if( rc==SQLITE_OK ){
58859     u8 *aData = pBt->pPage1->aData;
58860     if( aData[18]!=(u8)iVersion || aData[19]!=(u8)iVersion ){
58861       rc = sqlite3BtreeBeginTrans(pBtree, 2);
58862       if( rc==SQLITE_OK ){
58863         rc = sqlite3PagerWrite(pBt->pPage1->pDbPage);
58864         if( rc==SQLITE_OK ){
58865           aData[18] = (u8)iVersion;
58866           aData[19] = (u8)iVersion;
58867         }
58868       }
58869     }
58870   }
58871 
58872   pBt->btsFlags &= ~BTS_NO_WAL;
58873   return rc;
58874 }
58875 
58876 /*
58877 ** set the mask of hint flags for cursor pCsr. Currently the only valid
58878 ** values are 0 and BTREE_BULKLOAD.
58879 */
58880 SQLITE_PRIVATE void sqlite3BtreeCursorHints(BtCursor *pCsr, unsigned int mask){
58881   assert( mask==BTREE_BULKLOAD || mask==0 );
58882   pCsr->hints = mask;
58883 }
58884 
58885 /************** End of btree.c ***********************************************/
58886 /************** Begin file backup.c ******************************************/
58887 /*
58888 ** 2009 January 28
58889 **
58890 ** The author disclaims copyright to this source code.  In place of
58891 ** a legal notice, here is a blessing:
58892 **
58893 **    May you do good and not evil.
58894 **    May you find forgiveness for yourself and forgive others.
58895 **    May you share freely, never taking more than you give.
58896 **
58897 *************************************************************************
58898 ** This file contains the implementation of the sqlite3_backup_XXX() 
58899 ** API functions and the related features.
58900 */
58901 
58902 /*
58903 ** Structure allocated for each backup operation.
58904 */
58905 struct sqlite3_backup {
58906   sqlite3* pDestDb;        /* Destination database handle */
58907   Btree *pDest;            /* Destination b-tree file */
58908   u32 iDestSchema;         /* Original schema cookie in destination */
58909   int bDestLocked;         /* True once a write-transaction is open on pDest */
58910 
58911   Pgno iNext;              /* Page number of the next source page to copy */
58912   sqlite3* pSrcDb;         /* Source database handle */
58913   Btree *pSrc;             /* Source b-tree file */
58914 
58915   int rc;                  /* Backup process error code */
58916 
58917   /* These two variables are set by every call to backup_step(). They are
58918   ** read by calls to backup_remaining() and backup_pagecount().
58919   */
58920   Pgno nRemaining;         /* Number of pages left to copy */
58921   Pgno nPagecount;         /* Total number of pages to copy */
58922 
58923   int isAttached;          /* True once backup has been registered with pager */
58924   sqlite3_backup *pNext;   /* Next backup associated with source pager */
58925 };
58926 
58927 /*
58928 ** THREAD SAFETY NOTES:
58929 **
58930 **   Once it has been created using backup_init(), a single sqlite3_backup
58931 **   structure may be accessed via two groups of thread-safe entry points:
58932 **
58933 **     * Via the sqlite3_backup_XXX() API function backup_step() and 
58934 **       backup_finish(). Both these functions obtain the source database
58935 **       handle mutex and the mutex associated with the source BtShared 
58936 **       structure, in that order.
58937 **
58938 **     * Via the BackupUpdate() and BackupRestart() functions, which are
58939 **       invoked by the pager layer to report various state changes in
58940 **       the page cache associated with the source database. The mutex
58941 **       associated with the source database BtShared structure will always 
58942 **       be held when either of these functions are invoked.
58943 **
58944 **   The other sqlite3_backup_XXX() API functions, backup_remaining() and
58945 **   backup_pagecount() are not thread-safe functions. If they are called
58946 **   while some other thread is calling backup_step() or backup_finish(),
58947 **   the values returned may be invalid. There is no way for a call to
58948 **   BackupUpdate() or BackupRestart() to interfere with backup_remaining()
58949 **   or backup_pagecount().
58950 **
58951 **   Depending on the SQLite configuration, the database handles and/or
58952 **   the Btree objects may have their own mutexes that require locking.
58953 **   Non-sharable Btrees (in-memory databases for example), do not have
58954 **   associated mutexes.
58955 */
58956 
58957 /*
58958 ** Return a pointer corresponding to database zDb (i.e. "main", "temp")
58959 ** in connection handle pDb. If such a database cannot be found, return
58960 ** a NULL pointer and write an error message to pErrorDb.
58961 **
58962 ** If the "temp" database is requested, it may need to be opened by this 
58963 ** function. If an error occurs while doing so, return 0 and write an 
58964 ** error message to pErrorDb.
58965 */
58966 static Btree *findBtree(sqlite3 *pErrorDb, sqlite3 *pDb, const char *zDb){
58967   int i = sqlite3FindDbName(pDb, zDb);
58968 
58969   if( i==1 ){
58970     Parse *pParse;
58971     int rc = 0;
58972     pParse = sqlite3StackAllocZero(pErrorDb, sizeof(*pParse));
58973     if( pParse==0 ){
58974       sqlite3Error(pErrorDb, SQLITE_NOMEM, "out of memory");
58975       rc = SQLITE_NOMEM;
58976     }else{
58977       pParse->db = pDb;
58978       if( sqlite3OpenTempDatabase(pParse) ){
58979         sqlite3Error(pErrorDb, pParse->rc, "%s", pParse->zErrMsg);
58980         rc = SQLITE_ERROR;
58981       }
58982       sqlite3DbFree(pErrorDb, pParse->zErrMsg);
58983       sqlite3ParserReset(pParse);
58984       sqlite3StackFree(pErrorDb, pParse);
58985     }
58986     if( rc ){
58987       return 0;
58988     }
58989   }
58990 
58991   if( i<0 ){
58992     sqlite3Error(pErrorDb, SQLITE_ERROR, "unknown database %s", zDb);
58993     return 0;
58994   }
58995 
58996   return pDb->aDb[i].pBt;
58997 }
58998 
58999 /*
59000 ** Attempt to set the page size of the destination to match the page size
59001 ** of the source.
59002 */
59003 static int setDestPgsz(sqlite3_backup *p){
59004   int rc;
59005   rc = sqlite3BtreeSetPageSize(p->pDest,sqlite3BtreeGetPageSize(p->pSrc),-1,0);
59006   return rc;
59007 }
59008 
59009 /*
59010 ** Create an sqlite3_backup process to copy the contents of zSrcDb from
59011 ** connection handle pSrcDb to zDestDb in pDestDb. If successful, return
59012 ** a pointer to the new sqlite3_backup object.
59013 **
59014 ** If an error occurs, NULL is returned and an error code and error message
59015 ** stored in database handle pDestDb.
59016 */
59017 SQLITE_API sqlite3_backup *sqlite3_backup_init(
59018   sqlite3* pDestDb,                     /* Database to write to */
59019   const char *zDestDb,                  /* Name of database within pDestDb */
59020   sqlite3* pSrcDb,                      /* Database connection to read from */
59021   const char *zSrcDb                    /* Name of database within pSrcDb */
59022 ){
59023   sqlite3_backup *p;                    /* Value to return */
59024 
59025   /* Lock the source database handle. The destination database
59026   ** handle is not locked in this routine, but it is locked in
59027   ** sqlite3_backup_step(). The user is required to ensure that no
59028   ** other thread accesses the destination handle for the duration
59029   ** of the backup operation.  Any attempt to use the destination
59030   ** database connection while a backup is in progress may cause
59031   ** a malfunction or a deadlock.
59032   */
59033   sqlite3_mutex_enter(pSrcDb->mutex);
59034   sqlite3_mutex_enter(pDestDb->mutex);
59035 
59036   if( pSrcDb==pDestDb ){
59037     sqlite3Error(
59038         pDestDb, SQLITE_ERROR, "source and destination must be distinct"
59039     );
59040     p = 0;
59041   }else {
59042     /* Allocate space for a new sqlite3_backup object...
59043     ** EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
59044     ** call to sqlite3_backup_init() and is destroyed by a call to
59045     ** sqlite3_backup_finish(). */
59046     p = (sqlite3_backup *)sqlite3MallocZero(sizeof(sqlite3_backup));
59047     if( !p ){
59048       sqlite3Error(pDestDb, SQLITE_NOMEM, 0);
59049     }
59050   }
59051 
59052   /* If the allocation succeeded, populate the new object. */
59053   if( p ){
59054     p->pSrc = findBtree(pDestDb, pSrcDb, zSrcDb);
59055     p->pDest = findBtree(pDestDb, pDestDb, zDestDb);
59056     p->pDestDb = pDestDb;
59057     p->pSrcDb = pSrcDb;
59058     p->iNext = 1;
59059     p->isAttached = 0;
59060 
59061     if( 0==p->pSrc || 0==p->pDest || setDestPgsz(p)==SQLITE_NOMEM ){
59062       /* One (or both) of the named databases did not exist or an OOM
59063       ** error was hit.  The error has already been written into the
59064       ** pDestDb handle.  All that is left to do here is free the
59065       ** sqlite3_backup structure.
59066       */
59067       sqlite3_free(p);
59068       p = 0;
59069     }
59070   }
59071   if( p ){
59072     p->pSrc->nBackup++;
59073   }
59074 
59075   sqlite3_mutex_leave(pDestDb->mutex);
59076   sqlite3_mutex_leave(pSrcDb->mutex);
59077   return p;
59078 }
59079 
59080 /*
59081 ** Argument rc is an SQLite error code. Return true if this error is 
59082 ** considered fatal if encountered during a backup operation. All errors
59083 ** are considered fatal except for SQLITE_BUSY and SQLITE_LOCKED.
59084 */
59085 static int isFatalError(int rc){
59086   return (rc!=SQLITE_OK && rc!=SQLITE_BUSY && ALWAYS(rc!=SQLITE_LOCKED));
59087 }
59088 
59089 /*
59090 ** Parameter zSrcData points to a buffer containing the data for 
59091 ** page iSrcPg from the source database. Copy this data into the 
59092 ** destination database.
59093 */
59094 static int backupOnePage(
59095   sqlite3_backup *p,              /* Backup handle */
59096   Pgno iSrcPg,                    /* Source database page to backup */
59097   const u8 *zSrcData,             /* Source database page data */
59098   int bUpdate                     /* True for an update, false otherwise */
59099 ){
59100   Pager * const pDestPager = sqlite3BtreePager(p->pDest);
59101   const int nSrcPgsz = sqlite3BtreeGetPageSize(p->pSrc);
59102   int nDestPgsz = sqlite3BtreeGetPageSize(p->pDest);
59103   const int nCopy = MIN(nSrcPgsz, nDestPgsz);
59104   const i64 iEnd = (i64)iSrcPg*(i64)nSrcPgsz;
59105 #ifdef SQLITE_HAS_CODEC
59106   /* Use BtreeGetReserveNoMutex() for the source b-tree, as although it is
59107   ** guaranteed that the shared-mutex is held by this thread, handle
59108   ** p->pSrc may not actually be the owner.  */
59109   int nSrcReserve = sqlite3BtreeGetReserveNoMutex(p->pSrc);
59110   int nDestReserve = sqlite3BtreeGetReserve(p->pDest);
59111 #endif
59112   int rc = SQLITE_OK;
59113   i64 iOff;
59114 
59115   assert( sqlite3BtreeGetReserveNoMutex(p->pSrc)>=0 );
59116   assert( p->bDestLocked );
59117   assert( !isFatalError(p->rc) );
59118   assert( iSrcPg!=PENDING_BYTE_PAGE(p->pSrc->pBt) );
59119   assert( zSrcData );
59120 
59121   /* Catch the case where the destination is an in-memory database and the
59122   ** page sizes of the source and destination differ. 
59123   */
59124   if( nSrcPgsz!=nDestPgsz && sqlite3PagerIsMemdb(pDestPager) ){
59125     rc = SQLITE_READONLY;
59126   }
59127 
59128 #ifdef SQLITE_HAS_CODEC
59129   /* Backup is not possible if the page size of the destination is changing
59130   ** and a codec is in use.
59131   */
59132   if( nSrcPgsz!=nDestPgsz && sqlite3PagerGetCodec(pDestPager)!=0 ){
59133     rc = SQLITE_READONLY;
59134   }
59135 
59136   /* Backup is not possible if the number of bytes of reserve space differ
59137   ** between source and destination.  If there is a difference, try to
59138   ** fix the destination to agree with the source.  If that is not possible,
59139   ** then the backup cannot proceed.
59140   */
59141   if( nSrcReserve!=nDestReserve ){
59142     u32 newPgsz = nSrcPgsz;
59143     rc = sqlite3PagerSetPagesize(pDestPager, &newPgsz, nSrcReserve);
59144     if( rc==SQLITE_OK && newPgsz!=nSrcPgsz ) rc = SQLITE_READONLY;
59145   }
59146 #endif
59147 
59148   /* This loop runs once for each destination page spanned by the source 
59149   ** page. For each iteration, variable iOff is set to the byte offset
59150   ** of the destination page.
59151   */
59152   for(iOff=iEnd-(i64)nSrcPgsz; rc==SQLITE_OK && iOff<iEnd; iOff+=nDestPgsz){
59153     DbPage *pDestPg = 0;
59154     Pgno iDest = (Pgno)(iOff/nDestPgsz)+1;
59155     if( iDest==PENDING_BYTE_PAGE(p->pDest->pBt) ) continue;
59156     if( SQLITE_OK==(rc = sqlite3PagerGet(pDestPager, iDest, &pDestPg))
59157      && SQLITE_OK==(rc = sqlite3PagerWrite(pDestPg))
59158     ){
59159       const u8 *zIn = &zSrcData[iOff%nSrcPgsz];
59160       u8 *zDestData = sqlite3PagerGetData(pDestPg);
59161       u8 *zOut = &zDestData[iOff%nDestPgsz];
59162 
59163       /* Copy the data from the source page into the destination page.
59164       ** Then clear the Btree layer MemPage.isInit flag. Both this module
59165       ** and the pager code use this trick (clearing the first byte
59166       ** of the page 'extra' space to invalidate the Btree layers
59167       ** cached parse of the page). MemPage.isInit is marked 
59168       ** "MUST BE FIRST" for this purpose.
59169       */
59170       memcpy(zOut, zIn, nCopy);
59171       ((u8 *)sqlite3PagerGetExtra(pDestPg))[0] = 0;
59172       if( iOff==0 && bUpdate==0 ){
59173         sqlite3Put4byte(&zOut[28], sqlite3BtreeLastPage(p->pSrc));
59174       }
59175     }
59176     sqlite3PagerUnref(pDestPg);
59177   }
59178 
59179   return rc;
59180 }
59181 
59182 /*
59183 ** If pFile is currently larger than iSize bytes, then truncate it to
59184 ** exactly iSize bytes. If pFile is not larger than iSize bytes, then
59185 ** this function is a no-op.
59186 **
59187 ** Return SQLITE_OK if everything is successful, or an SQLite error 
59188 ** code if an error occurs.
59189 */
59190 static int backupTruncateFile(sqlite3_file *pFile, i64 iSize){
59191   i64 iCurrent;
59192   int rc = sqlite3OsFileSize(pFile, &iCurrent);
59193   if( rc==SQLITE_OK && iCurrent>iSize ){
59194     rc = sqlite3OsTruncate(pFile, iSize);
59195   }
59196   return rc;
59197 }
59198 
59199 /*
59200 ** Register this backup object with the associated source pager for
59201 ** callbacks when pages are changed or the cache invalidated.
59202 */
59203 static void attachBackupObject(sqlite3_backup *p){
59204   sqlite3_backup **pp;
59205   assert( sqlite3BtreeHoldsMutex(p->pSrc) );
59206   pp = sqlite3PagerBackupPtr(sqlite3BtreePager(p->pSrc));
59207   p->pNext = *pp;
59208   *pp = p;
59209   p->isAttached = 1;
59210 }
59211 
59212 /*
59213 ** Copy nPage pages from the source b-tree to the destination.
59214 */
59215 SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage){
59216   int rc;
59217   int destMode;       /* Destination journal mode */
59218   int pgszSrc = 0;    /* Source page size */
59219   int pgszDest = 0;   /* Destination page size */
59220 
59221   sqlite3_mutex_enter(p->pSrcDb->mutex);
59222   sqlite3BtreeEnter(p->pSrc);
59223   if( p->pDestDb ){
59224     sqlite3_mutex_enter(p->pDestDb->mutex);
59225   }
59226 
59227   rc = p->rc;
59228   if( !isFatalError(rc) ){
59229     Pager * const pSrcPager = sqlite3BtreePager(p->pSrc);     /* Source pager */
59230     Pager * const pDestPager = sqlite3BtreePager(p->pDest);   /* Dest pager */
59231     int ii;                            /* Iterator variable */
59232     int nSrcPage = -1;                 /* Size of source db in pages */
59233     int bCloseTrans = 0;               /* True if src db requires unlocking */
59234 
59235     /* If the source pager is currently in a write-transaction, return
59236     ** SQLITE_BUSY immediately.
59237     */
59238     if( p->pDestDb && p->pSrc->pBt->inTransaction==TRANS_WRITE ){
59239       rc = SQLITE_BUSY;
59240     }else{
59241       rc = SQLITE_OK;
59242     }
59243 
59244     /* Lock the destination database, if it is not locked already. */
59245     if( SQLITE_OK==rc && p->bDestLocked==0
59246      && SQLITE_OK==(rc = sqlite3BtreeBeginTrans(p->pDest, 2)) 
59247     ){
59248       p->bDestLocked = 1;
59249       sqlite3BtreeGetMeta(p->pDest, BTREE_SCHEMA_VERSION, &p->iDestSchema);
59250     }
59251 
59252     /* If there is no open read-transaction on the source database, open
59253     ** one now. If a transaction is opened here, then it will be closed
59254     ** before this function exits.
59255     */
59256     if( rc==SQLITE_OK && 0==sqlite3BtreeIsInReadTrans(p->pSrc) ){
59257       rc = sqlite3BtreeBeginTrans(p->pSrc, 0);
59258       bCloseTrans = 1;
59259     }
59260 
59261     /* Do not allow backup if the destination database is in WAL mode
59262     ** and the page sizes are different between source and destination */
59263     pgszSrc = sqlite3BtreeGetPageSize(p->pSrc);
59264     pgszDest = sqlite3BtreeGetPageSize(p->pDest);
59265     destMode = sqlite3PagerGetJournalMode(sqlite3BtreePager(p->pDest));
59266     if( SQLITE_OK==rc && destMode==PAGER_JOURNALMODE_WAL && pgszSrc!=pgszDest ){
59267       rc = SQLITE_READONLY;
59268     }
59269   
59270     /* Now that there is a read-lock on the source database, query the
59271     ** source pager for the number of pages in the database.
59272     */
59273     nSrcPage = (int)sqlite3BtreeLastPage(p->pSrc);
59274     assert( nSrcPage>=0 );
59275     for(ii=0; (nPage<0 || ii<nPage) && p->iNext<=(Pgno)nSrcPage && !rc; ii++){
59276       const Pgno iSrcPg = p->iNext;                 /* Source page number */
59277       if( iSrcPg!=PENDING_BYTE_PAGE(p->pSrc->pBt) ){
59278         DbPage *pSrcPg;                             /* Source page object */
59279         rc = sqlite3PagerAcquire(pSrcPager, iSrcPg, &pSrcPg,
59280                                  PAGER_GET_READONLY);
59281         if( rc==SQLITE_OK ){
59282           rc = backupOnePage(p, iSrcPg, sqlite3PagerGetData(pSrcPg), 0);
59283           sqlite3PagerUnref(pSrcPg);
59284         }
59285       }
59286       p->iNext++;
59287     }
59288     if( rc==SQLITE_OK ){
59289       p->nPagecount = nSrcPage;
59290       p->nRemaining = nSrcPage+1-p->iNext;
59291       if( p->iNext>(Pgno)nSrcPage ){
59292         rc = SQLITE_DONE;
59293       }else if( !p->isAttached ){
59294         attachBackupObject(p);
59295       }
59296     }
59297   
59298     /* Update the schema version field in the destination database. This
59299     ** is to make sure that the schema-version really does change in
59300     ** the case where the source and destination databases have the
59301     ** same schema version.
59302     */
59303     if( rc==SQLITE_DONE ){
59304       if( nSrcPage==0 ){
59305         rc = sqlite3BtreeNewDb(p->pDest);
59306         nSrcPage = 1;
59307       }
59308       if( rc==SQLITE_OK || rc==SQLITE_DONE ){
59309         rc = sqlite3BtreeUpdateMeta(p->pDest,1,p->iDestSchema+1);
59310       }
59311       if( rc==SQLITE_OK ){
59312         if( p->pDestDb ){
59313           sqlite3ResetAllSchemasOfConnection(p->pDestDb);
59314         }
59315         if( destMode==PAGER_JOURNALMODE_WAL ){
59316           rc = sqlite3BtreeSetVersion(p->pDest, 2);
59317         }
59318       }
59319       if( rc==SQLITE_OK ){
59320         int nDestTruncate;
59321         /* Set nDestTruncate to the final number of pages in the destination
59322         ** database. The complication here is that the destination page
59323         ** size may be different to the source page size. 
59324         **
59325         ** If the source page size is smaller than the destination page size, 
59326         ** round up. In this case the call to sqlite3OsTruncate() below will
59327         ** fix the size of the file. However it is important to call
59328         ** sqlite3PagerTruncateImage() here so that any pages in the 
59329         ** destination file that lie beyond the nDestTruncate page mark are
59330         ** journalled by PagerCommitPhaseOne() before they are destroyed
59331         ** by the file truncation.
59332         */
59333         assert( pgszSrc==sqlite3BtreeGetPageSize(p->pSrc) );
59334         assert( pgszDest==sqlite3BtreeGetPageSize(p->pDest) );
59335         if( pgszSrc<pgszDest ){
59336           int ratio = pgszDest/pgszSrc;
59337           nDestTruncate = (nSrcPage+ratio-1)/ratio;
59338           if( nDestTruncate==(int)PENDING_BYTE_PAGE(p->pDest->pBt) ){
59339             nDestTruncate--;
59340           }
59341         }else{
59342           nDestTruncate = nSrcPage * (pgszSrc/pgszDest);
59343         }
59344         assert( nDestTruncate>0 );
59345 
59346         if( pgszSrc<pgszDest ){
59347           /* If the source page-size is smaller than the destination page-size,
59348           ** two extra things may need to happen:
59349           **
59350           **   * The destination may need to be truncated, and
59351           **
59352           **   * Data stored on the pages immediately following the 
59353           **     pending-byte page in the source database may need to be
59354           **     copied into the destination database.
59355           */
59356           const i64 iSize = (i64)pgszSrc * (i64)nSrcPage;
59357           sqlite3_file * const pFile = sqlite3PagerFile(pDestPager);
59358           Pgno iPg;
59359           int nDstPage;
59360           i64 iOff;
59361           i64 iEnd;
59362 
59363           assert( pFile );
59364           assert( nDestTruncate==0 
59365               || (i64)nDestTruncate*(i64)pgszDest >= iSize || (
59366                 nDestTruncate==(int)(PENDING_BYTE_PAGE(p->pDest->pBt)-1)
59367              && iSize>=PENDING_BYTE && iSize<=PENDING_BYTE+pgszDest
59368           ));
59369 
59370           /* This block ensures that all data required to recreate the original
59371           ** database has been stored in the journal for pDestPager and the
59372           ** journal synced to disk. So at this point we may safely modify
59373           ** the database file in any way, knowing that if a power failure
59374           ** occurs, the original database will be reconstructed from the 
59375           ** journal file.  */
59376           sqlite3PagerPagecount(pDestPager, &nDstPage);
59377           for(iPg=nDestTruncate; rc==SQLITE_OK && iPg<=(Pgno)nDstPage; iPg++){
59378             if( iPg!=PENDING_BYTE_PAGE(p->pDest->pBt) ){
59379               DbPage *pPg;
59380               rc = sqlite3PagerGet(pDestPager, iPg, &pPg);
59381               if( rc==SQLITE_OK ){
59382                 rc = sqlite3PagerWrite(pPg);
59383                 sqlite3PagerUnref(pPg);
59384               }
59385             }
59386           }
59387           if( rc==SQLITE_OK ){
59388             rc = sqlite3PagerCommitPhaseOne(pDestPager, 0, 1);
59389           }
59390 
59391           /* Write the extra pages and truncate the database file as required */
59392           iEnd = MIN(PENDING_BYTE + pgszDest, iSize);
59393           for(
59394             iOff=PENDING_BYTE+pgszSrc; 
59395             rc==SQLITE_OK && iOff<iEnd; 
59396             iOff+=pgszSrc
59397           ){
59398             PgHdr *pSrcPg = 0;
59399             const Pgno iSrcPg = (Pgno)((iOff/pgszSrc)+1);
59400             rc = sqlite3PagerGet(pSrcPager, iSrcPg, &pSrcPg);
59401             if( rc==SQLITE_OK ){
59402               u8 *zData = sqlite3PagerGetData(pSrcPg);
59403               rc = sqlite3OsWrite(pFile, zData, pgszSrc, iOff);
59404             }
59405             sqlite3PagerUnref(pSrcPg);
59406           }
59407           if( rc==SQLITE_OK ){
59408             rc = backupTruncateFile(pFile, iSize);
59409           }
59410 
59411           /* Sync the database file to disk. */
59412           if( rc==SQLITE_OK ){
59413             rc = sqlite3PagerSync(pDestPager);
59414           }
59415         }else{
59416           sqlite3PagerTruncateImage(pDestPager, nDestTruncate);
59417           rc = sqlite3PagerCommitPhaseOne(pDestPager, 0, 0);
59418         }
59419     
59420         /* Finish committing the transaction to the destination database. */
59421         if( SQLITE_OK==rc
59422          && SQLITE_OK==(rc = sqlite3BtreeCommitPhaseTwo(p->pDest, 0))
59423         ){
59424           rc = SQLITE_DONE;
59425         }
59426       }
59427     }
59428   
59429     /* If bCloseTrans is true, then this function opened a read transaction
59430     ** on the source database. Close the read transaction here. There is
59431     ** no need to check the return values of the btree methods here, as
59432     ** "committing" a read-only transaction cannot fail.
59433     */
59434     if( bCloseTrans ){
59435       TESTONLY( int rc2 );
59436       TESTONLY( rc2  = ) sqlite3BtreeCommitPhaseOne(p->pSrc, 0);
59437       TESTONLY( rc2 |= ) sqlite3BtreeCommitPhaseTwo(p->pSrc, 0);
59438       assert( rc2==SQLITE_OK );
59439     }
59440   
59441     if( rc==SQLITE_IOERR_NOMEM ){
59442       rc = SQLITE_NOMEM;
59443     }
59444     p->rc = rc;
59445   }
59446   if( p->pDestDb ){
59447     sqlite3_mutex_leave(p->pDestDb->mutex);
59448   }
59449   sqlite3BtreeLeave(p->pSrc);
59450   sqlite3_mutex_leave(p->pSrcDb->mutex);
59451   return rc;
59452 }
59453 
59454 /*
59455 ** Release all resources associated with an sqlite3_backup* handle.
59456 */
59457 SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p){
59458   sqlite3_backup **pp;                 /* Ptr to head of pagers backup list */
59459   sqlite3 *pSrcDb;                     /* Source database connection */
59460   int rc;                              /* Value to return */
59461 
59462   /* Enter the mutexes */
59463   if( p==0 ) return SQLITE_OK;
59464   pSrcDb = p->pSrcDb;
59465   sqlite3_mutex_enter(pSrcDb->mutex);
59466   sqlite3BtreeEnter(p->pSrc);
59467   if( p->pDestDb ){
59468     sqlite3_mutex_enter(p->pDestDb->mutex);
59469   }
59470 
59471   /* Detach this backup from the source pager. */
59472   if( p->pDestDb ){
59473     p->pSrc->nBackup--;
59474   }
59475   if( p->isAttached ){
59476     pp = sqlite3PagerBackupPtr(sqlite3BtreePager(p->pSrc));
59477     while( *pp!=p ){
59478       pp = &(*pp)->pNext;
59479     }
59480     *pp = p->pNext;
59481   }
59482 
59483   /* If a transaction is still open on the Btree, roll it back. */
59484   sqlite3BtreeRollback(p->pDest, SQLITE_OK);
59485 
59486   /* Set the error code of the destination database handle. */
59487   rc = (p->rc==SQLITE_DONE) ? SQLITE_OK : p->rc;
59488   sqlite3Error(p->pDestDb, rc, 0);
59489 
59490   /* Exit the mutexes and free the backup context structure. */
59491   if( p->pDestDb ){
59492     sqlite3LeaveMutexAndCloseZombie(p->pDestDb);
59493   }
59494   sqlite3BtreeLeave(p->pSrc);
59495   if( p->pDestDb ){
59496     /* EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
59497     ** call to sqlite3_backup_init() and is destroyed by a call to
59498     ** sqlite3_backup_finish(). */
59499     sqlite3_free(p);
59500   }
59501   sqlite3LeaveMutexAndCloseZombie(pSrcDb);
59502   return rc;
59503 }
59504 
59505 /*
59506 ** Return the number of pages still to be backed up as of the most recent
59507 ** call to sqlite3_backup_step().
59508 */
59509 SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p){
59510   return p->nRemaining;
59511 }
59512 
59513 /*
59514 ** Return the total number of pages in the source database as of the most 
59515 ** recent call to sqlite3_backup_step().
59516 */
59517 SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p){
59518   return p->nPagecount;
59519 }
59520 
59521 /*
59522 ** This function is called after the contents of page iPage of the
59523 ** source database have been modified. If page iPage has already been 
59524 ** copied into the destination database, then the data written to the
59525 ** destination is now invalidated. The destination copy of iPage needs
59526 ** to be updated with the new data before the backup operation is
59527 ** complete.
59528 **
59529 ** It is assumed that the mutex associated with the BtShared object
59530 ** corresponding to the source database is held when this function is
59531 ** called.
59532 */
59533 SQLITE_PRIVATE void sqlite3BackupUpdate(sqlite3_backup *pBackup, Pgno iPage, const u8 *aData){
59534   sqlite3_backup *p;                   /* Iterator variable */
59535   for(p=pBackup; p; p=p->pNext){
59536     assert( sqlite3_mutex_held(p->pSrc->pBt->mutex) );
59537     if( !isFatalError(p->rc) && iPage<p->iNext ){
59538       /* The backup process p has already copied page iPage. But now it
59539       ** has been modified by a transaction on the source pager. Copy
59540       ** the new data into the backup.
59541       */
59542       int rc;
59543       assert( p->pDestDb );
59544       sqlite3_mutex_enter(p->pDestDb->mutex);
59545       rc = backupOnePage(p, iPage, aData, 1);
59546       sqlite3_mutex_leave(p->pDestDb->mutex);
59547       assert( rc!=SQLITE_BUSY && rc!=SQLITE_LOCKED );
59548       if( rc!=SQLITE_OK ){
59549         p->rc = rc;
59550       }
59551     }
59552   }
59553 }
59554 
59555 /*
59556 ** Restart the backup process. This is called when the pager layer
59557 ** detects that the database has been modified by an external database
59558 ** connection. In this case there is no way of knowing which of the
59559 ** pages that have been copied into the destination database are still 
59560 ** valid and which are not, so the entire process needs to be restarted.
59561 **
59562 ** It is assumed that the mutex associated with the BtShared object
59563 ** corresponding to the source database is held when this function is
59564 ** called.
59565 */
59566 SQLITE_PRIVATE void sqlite3BackupRestart(sqlite3_backup *pBackup){
59567   sqlite3_backup *p;                   /* Iterator variable */
59568   for(p=pBackup; p; p=p->pNext){
59569     assert( sqlite3_mutex_held(p->pSrc->pBt->mutex) );
59570     p->iNext = 1;
59571   }
59572 }
59573 
59574 #ifndef SQLITE_OMIT_VACUUM
59575 /*
59576 ** Copy the complete content of pBtFrom into pBtTo.  A transaction
59577 ** must be active for both files.
59578 **
59579 ** The size of file pTo may be reduced by this operation. If anything 
59580 ** goes wrong, the transaction on pTo is rolled back. If successful, the 
59581 ** transaction is committed before returning.
59582 */
59583 SQLITE_PRIVATE int sqlite3BtreeCopyFile(Btree *pTo, Btree *pFrom){
59584   int rc;
59585   sqlite3_file *pFd;              /* File descriptor for database pTo */
59586   sqlite3_backup b;
59587   sqlite3BtreeEnter(pTo);
59588   sqlite3BtreeEnter(pFrom);
59589 
59590   assert( sqlite3BtreeIsInTrans(pTo) );
59591   pFd = sqlite3PagerFile(sqlite3BtreePager(pTo));
59592   if( pFd->pMethods ){
59593     i64 nByte = sqlite3BtreeGetPageSize(pFrom)*(i64)sqlite3BtreeLastPage(pFrom);
59594     rc = sqlite3OsFileControl(pFd, SQLITE_FCNTL_OVERWRITE, &nByte);
59595     if( rc==SQLITE_NOTFOUND ) rc = SQLITE_OK;
59596     if( rc ) goto copy_finished;
59597   }
59598 
59599   /* Set up an sqlite3_backup object. sqlite3_backup.pDestDb must be set
59600   ** to 0. This is used by the implementations of sqlite3_backup_step()
59601   ** and sqlite3_backup_finish() to detect that they are being called
59602   ** from this function, not directly by the user.
59603   */
59604   memset(&b, 0, sizeof(b));
59605   b.pSrcDb = pFrom->db;
59606   b.pSrc = pFrom;
59607   b.pDest = pTo;
59608   b.iNext = 1;
59609 
59610   /* 0x7FFFFFFF is the hard limit for the number of pages in a database
59611   ** file. By passing this as the number of pages to copy to
59612   ** sqlite3_backup_step(), we can guarantee that the copy finishes 
59613   ** within a single call (unless an error occurs). The assert() statement
59614   ** checks this assumption - (p->rc) should be set to either SQLITE_DONE 
59615   ** or an error code.
59616   */
59617   sqlite3_backup_step(&b, 0x7FFFFFFF);
59618   assert( b.rc!=SQLITE_OK );
59619   rc = sqlite3_backup_finish(&b);
59620   if( rc==SQLITE_OK ){
59621     pTo->pBt->btsFlags &= ~BTS_PAGESIZE_FIXED;
59622   }else{
59623     sqlite3PagerClearCache(sqlite3BtreePager(b.pDest));
59624   }
59625 
59626   assert( sqlite3BtreeIsInTrans(pTo)==0 );
59627 copy_finished:
59628   sqlite3BtreeLeave(pFrom);
59629   sqlite3BtreeLeave(pTo);
59630   return rc;
59631 }
59632 #endif /* SQLITE_OMIT_VACUUM */
59633 
59634 /************** End of backup.c **********************************************/
59635 /************** Begin file vdbemem.c *****************************************/
59636 /*
59637 ** 2004 May 26
59638 **
59639 ** The author disclaims copyright to this source code.  In place of
59640 ** a legal notice, here is a blessing:
59641 **
59642 **    May you do good and not evil.
59643 **    May you find forgiveness for yourself and forgive others.
59644 **    May you share freely, never taking more than you give.
59645 **
59646 *************************************************************************
59647 **
59648 ** This file contains code use to manipulate "Mem" structure.  A "Mem"
59649 ** stores a single value in the VDBE.  Mem is an opaque structure visible
59650 ** only within the VDBE.  Interface routines refer to a Mem using the
59651 ** name sqlite_value
59652 */
59653 
59654 /*
59655 ** If pMem is an object with a valid string representation, this routine
59656 ** ensures the internal encoding for the string representation is
59657 ** 'desiredEnc', one of SQLITE_UTF8, SQLITE_UTF16LE or SQLITE_UTF16BE.
59658 **
59659 ** If pMem is not a string object, or the encoding of the string
59660 ** representation is already stored using the requested encoding, then this
59661 ** routine is a no-op.
59662 **
59663 ** SQLITE_OK is returned if the conversion is successful (or not required).
59664 ** SQLITE_NOMEM may be returned if a malloc() fails during conversion
59665 ** between formats.
59666 */
59667 SQLITE_PRIVATE int sqlite3VdbeChangeEncoding(Mem *pMem, int desiredEnc){
59668 #ifndef SQLITE_OMIT_UTF16
59669   int rc;
59670 #endif
59671   assert( (pMem->flags&MEM_RowSet)==0 );
59672   assert( desiredEnc==SQLITE_UTF8 || desiredEnc==SQLITE_UTF16LE
59673            || desiredEnc==SQLITE_UTF16BE );
59674   if( !(pMem->flags&MEM_Str) || pMem->enc==desiredEnc ){
59675     return SQLITE_OK;
59676   }
59677   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59678 #ifdef SQLITE_OMIT_UTF16
59679   return SQLITE_ERROR;
59680 #else
59681 
59682   /* MemTranslate() may return SQLITE_OK or SQLITE_NOMEM. If NOMEM is returned,
59683   ** then the encoding of the value may not have changed.
59684   */
59685   rc = sqlite3VdbeMemTranslate(pMem, (u8)desiredEnc);
59686   assert(rc==SQLITE_OK    || rc==SQLITE_NOMEM);
59687   assert(rc==SQLITE_OK    || pMem->enc!=desiredEnc);
59688   assert(rc==SQLITE_NOMEM || pMem->enc==desiredEnc);
59689   return rc;
59690 #endif
59691 }
59692 
59693 /*
59694 ** Make sure pMem->z points to a writable allocation of at least 
59695 ** n bytes.
59696 **
59697 ** If the third argument passed to this function is true, then memory
59698 ** cell pMem must contain a string or blob. In this case the content is
59699 ** preserved. Otherwise, if the third parameter to this function is false,
59700 ** any current string or blob value may be discarded.
59701 **
59702 ** This function sets the MEM_Dyn flag and clears any xDel callback.
59703 ** It also clears MEM_Ephem and MEM_Static. If the preserve flag is 
59704 ** not set, Mem.n is zeroed.
59705 */
59706 SQLITE_PRIVATE int sqlite3VdbeMemGrow(Mem *pMem, int n, int preserve){
59707   assert( 1 >=
59708     ((pMem->zMalloc && pMem->zMalloc==pMem->z) ? 1 : 0) +
59709     (((pMem->flags&MEM_Dyn)&&pMem->xDel) ? 1 : 0) + 
59710     ((pMem->flags&MEM_Ephem) ? 1 : 0) + 
59711     ((pMem->flags&MEM_Static) ? 1 : 0)
59712   );
59713   assert( (pMem->flags&MEM_RowSet)==0 );
59714 
59715   /* If the preserve flag is set to true, then the memory cell must already
59716   ** contain a valid string or blob value.  */
59717   assert( preserve==0 || pMem->flags&(MEM_Blob|MEM_Str) );
59718 
59719   if( n<32 ) n = 32;
59720   if( sqlite3DbMallocSize(pMem->db, pMem->zMalloc)<n ){
59721     if( preserve && pMem->z==pMem->zMalloc ){
59722       pMem->z = pMem->zMalloc = sqlite3DbReallocOrFree(pMem->db, pMem->z, n);
59723       preserve = 0;
59724     }else{
59725       sqlite3DbFree(pMem->db, pMem->zMalloc);
59726       pMem->zMalloc = sqlite3DbMallocRaw(pMem->db, n);
59727     }
59728   }
59729 
59730   if( pMem->z && preserve && pMem->zMalloc && pMem->z!=pMem->zMalloc ){
59731     memcpy(pMem->zMalloc, pMem->z, pMem->n);
59732   }
59733   if( pMem->flags&MEM_Dyn && pMem->xDel ){
59734     assert( pMem->xDel!=SQLITE_DYNAMIC );
59735     pMem->xDel((void *)(pMem->z));
59736   }
59737 
59738   pMem->z = pMem->zMalloc;
59739   if( pMem->z==0 ){
59740     pMem->flags = MEM_Null;
59741   }else{
59742     pMem->flags &= ~(MEM_Ephem|MEM_Static);
59743   }
59744   pMem->xDel = 0;
59745   return (pMem->z ? SQLITE_OK : SQLITE_NOMEM);
59746 }
59747 
59748 /*
59749 ** Make the given Mem object MEM_Dyn.  In other words, make it so
59750 ** that any TEXT or BLOB content is stored in memory obtained from
59751 ** malloc().  In this way, we know that the memory is safe to be
59752 ** overwritten or altered.
59753 **
59754 ** Return SQLITE_OK on success or SQLITE_NOMEM if malloc fails.
59755 */
59756 SQLITE_PRIVATE int sqlite3VdbeMemMakeWriteable(Mem *pMem){
59757   int f;
59758   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59759   assert( (pMem->flags&MEM_RowSet)==0 );
59760   ExpandBlob(pMem);
59761   f = pMem->flags;
59762   if( (f&(MEM_Str|MEM_Blob)) && pMem->z!=pMem->zMalloc ){
59763     if( sqlite3VdbeMemGrow(pMem, pMem->n + 2, 1) ){
59764       return SQLITE_NOMEM;
59765     }
59766     pMem->z[pMem->n] = 0;
59767     pMem->z[pMem->n+1] = 0;
59768     pMem->flags |= MEM_Term;
59769 #ifdef SQLITE_DEBUG
59770     pMem->pScopyFrom = 0;
59771 #endif
59772   }
59773 
59774   return SQLITE_OK;
59775 }
59776 
59777 /*
59778 ** If the given Mem* has a zero-filled tail, turn it into an ordinary
59779 ** blob stored in dynamically allocated space.
59780 */
59781 #ifndef SQLITE_OMIT_INCRBLOB
59782 SQLITE_PRIVATE int sqlite3VdbeMemExpandBlob(Mem *pMem){
59783   if( pMem->flags & MEM_Zero ){
59784     int nByte;
59785     assert( pMem->flags&MEM_Blob );
59786     assert( (pMem->flags&MEM_RowSet)==0 );
59787     assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59788 
59789     /* Set nByte to the number of bytes required to store the expanded blob. */
59790     nByte = pMem->n + pMem->u.nZero;
59791     if( nByte<=0 ){
59792       nByte = 1;
59793     }
59794     if( sqlite3VdbeMemGrow(pMem, nByte, 1) ){
59795       return SQLITE_NOMEM;
59796     }
59797 
59798     memset(&pMem->z[pMem->n], 0, pMem->u.nZero);
59799     pMem->n += pMem->u.nZero;
59800     pMem->flags &= ~(MEM_Zero|MEM_Term);
59801   }
59802   return SQLITE_OK;
59803 }
59804 #endif
59805 
59806 
59807 /*
59808 ** Make sure the given Mem is \u0000 terminated.
59809 */
59810 SQLITE_PRIVATE int sqlite3VdbeMemNulTerminate(Mem *pMem){
59811   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59812   if( (pMem->flags & MEM_Term)!=0 || (pMem->flags & MEM_Str)==0 ){
59813     return SQLITE_OK;   /* Nothing to do */
59814   }
59815   if( sqlite3VdbeMemGrow(pMem, pMem->n+2, 1) ){
59816     return SQLITE_NOMEM;
59817   }
59818   pMem->z[pMem->n] = 0;
59819   pMem->z[pMem->n+1] = 0;
59820   pMem->flags |= MEM_Term;
59821   return SQLITE_OK;
59822 }
59823 
59824 /*
59825 ** Add MEM_Str to the set of representations for the given Mem.  Numbers
59826 ** are converted using sqlite3_snprintf().  Converting a BLOB to a string
59827 ** is a no-op.
59828 **
59829 ** Existing representations MEM_Int and MEM_Real are *not* invalidated.
59830 **
59831 ** A MEM_Null value will never be passed to this function. This function is
59832 ** used for converting values to text for returning to the user (i.e. via
59833 ** sqlite3_value_text()), or for ensuring that values to be used as btree
59834 ** keys are strings. In the former case a NULL pointer is returned the
59835 ** user and the later is an internal programming error.
59836 */
59837 SQLITE_PRIVATE int sqlite3VdbeMemStringify(Mem *pMem, int enc){
59838   int rc = SQLITE_OK;
59839   int fg = pMem->flags;
59840   const int nByte = 32;
59841 
59842   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59843   assert( !(fg&MEM_Zero) );
59844   assert( !(fg&(MEM_Str|MEM_Blob)) );
59845   assert( fg&(MEM_Int|MEM_Real) );
59846   assert( (pMem->flags&MEM_RowSet)==0 );
59847   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
59848 
59849 
59850   if( sqlite3VdbeMemGrow(pMem, nByte, 0) ){
59851     return SQLITE_NOMEM;
59852   }
59853 
59854   /* For a Real or Integer, use sqlite3_mprintf() to produce the UTF-8
59855   ** string representation of the value. Then, if the required encoding
59856   ** is UTF-16le or UTF-16be do a translation.
59857   ** 
59858   ** FIX ME: It would be better if sqlite3_snprintf() could do UTF-16.
59859   */
59860   if( fg & MEM_Int ){
59861     sqlite3_snprintf(nByte, pMem->z, "%lld", pMem->u.i);
59862   }else{
59863     assert( fg & MEM_Real );
59864     sqlite3_snprintf(nByte, pMem->z, "%!.15g", pMem->r);
59865   }
59866   pMem->n = sqlite3Strlen30(pMem->z);
59867   pMem->enc = SQLITE_UTF8;
59868   pMem->flags |= MEM_Str|MEM_Term;
59869   sqlite3VdbeChangeEncoding(pMem, enc);
59870   return rc;
59871 }
59872 
59873 /*
59874 ** Memory cell pMem contains the context of an aggregate function.
59875 ** This routine calls the finalize method for that function.  The
59876 ** result of the aggregate is stored back into pMem.
59877 **
59878 ** Return SQLITE_ERROR if the finalizer reports an error.  SQLITE_OK
59879 ** otherwise.
59880 */
59881 SQLITE_PRIVATE int sqlite3VdbeMemFinalize(Mem *pMem, FuncDef *pFunc){
59882   int rc = SQLITE_OK;
59883   if( ALWAYS(pFunc && pFunc->xFinalize) ){
59884     sqlite3_context ctx;
59885     assert( (pMem->flags & MEM_Null)!=0 || pFunc==pMem->u.pDef );
59886     assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59887     memset(&ctx, 0, sizeof(ctx));
59888     ctx.s.flags = MEM_Null;
59889     ctx.s.db = pMem->db;
59890     ctx.pMem = pMem;
59891     ctx.pFunc = pFunc;
59892     pFunc->xFinalize(&ctx); /* IMP: R-24505-23230 */
59893     assert( 0==(pMem->flags&MEM_Dyn) && !pMem->xDel );
59894     sqlite3DbFree(pMem->db, pMem->zMalloc);
59895     memcpy(pMem, &ctx.s, sizeof(ctx.s));
59896     rc = ctx.isError;
59897   }
59898   return rc;
59899 }
59900 
59901 /*
59902 ** If the memory cell contains a string value that must be freed by
59903 ** invoking an external callback, free it now. Calling this function
59904 ** does not free any Mem.zMalloc buffer.
59905 */
59906 SQLITE_PRIVATE void sqlite3VdbeMemReleaseExternal(Mem *p){
59907   assert( p->db==0 || sqlite3_mutex_held(p->db->mutex) );
59908   if( p->flags&MEM_Agg ){
59909     sqlite3VdbeMemFinalize(p, p->u.pDef);
59910     assert( (p->flags & MEM_Agg)==0 );
59911     sqlite3VdbeMemRelease(p);
59912   }else if( p->flags&MEM_Dyn && p->xDel ){
59913     assert( (p->flags&MEM_RowSet)==0 );
59914     assert( p->xDel!=SQLITE_DYNAMIC );
59915     p->xDel((void *)p->z);
59916     p->xDel = 0;
59917   }else if( p->flags&MEM_RowSet ){
59918     sqlite3RowSetClear(p->u.pRowSet);
59919   }else if( p->flags&MEM_Frame ){
59920     sqlite3VdbeMemSetNull(p);
59921   }
59922 }
59923 
59924 /*
59925 ** Release any memory held by the Mem. This may leave the Mem in an
59926 ** inconsistent state, for example with (Mem.z==0) and
59927 ** (Mem.type==SQLITE_TEXT).
59928 */
59929 SQLITE_PRIVATE void sqlite3VdbeMemRelease(Mem *p){
59930   VdbeMemRelease(p);
59931   sqlite3DbFree(p->db, p->zMalloc);
59932   p->z = 0;
59933   p->zMalloc = 0;
59934   p->xDel = 0;
59935 }
59936 
59937 /*
59938 ** Convert a 64-bit IEEE double into a 64-bit signed integer.
59939 ** If the double is out of range of a 64-bit signed integer then
59940 ** return the closest available 64-bit signed integer.
59941 */
59942 static i64 doubleToInt64(double r){
59943 #ifdef SQLITE_OMIT_FLOATING_POINT
59944   /* When floating-point is omitted, double and int64 are the same thing */
59945   return r;
59946 #else
59947   /*
59948   ** Many compilers we encounter do not define constants for the
59949   ** minimum and maximum 64-bit integers, or they define them
59950   ** inconsistently.  And many do not understand the "LL" notation.
59951   ** So we define our own static constants here using nothing
59952   ** larger than a 32-bit integer constant.
59953   */
59954   static const i64 maxInt = LARGEST_INT64;
59955   static const i64 minInt = SMALLEST_INT64;
59956 
59957   if( r<=(double)minInt ){
59958     return minInt;
59959   }else if( r>=(double)maxInt ){
59960     return maxInt;
59961   }else{
59962     return (i64)r;
59963   }
59964 #endif
59965 }
59966 
59967 /*
59968 ** Return some kind of integer value which is the best we can do
59969 ** at representing the value that *pMem describes as an integer.
59970 ** If pMem is an integer, then the value is exact.  If pMem is
59971 ** a floating-point then the value returned is the integer part.
59972 ** If pMem is a string or blob, then we make an attempt to convert
59973 ** it into a integer and return that.  If pMem represents an
59974 ** an SQL-NULL value, return 0.
59975 **
59976 ** If pMem represents a string value, its encoding might be changed.
59977 */
59978 SQLITE_PRIVATE i64 sqlite3VdbeIntValue(Mem *pMem){
59979   int flags;
59980   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59981   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
59982   flags = pMem->flags;
59983   if( flags & MEM_Int ){
59984     return pMem->u.i;
59985   }else if( flags & MEM_Real ){
59986     return doubleToInt64(pMem->r);
59987   }else if( flags & (MEM_Str|MEM_Blob) ){
59988     i64 value = 0;
59989     assert( pMem->z || pMem->n==0 );
59990     testcase( pMem->z==0 );
59991     sqlite3Atoi64(pMem->z, &value, pMem->n, pMem->enc);
59992     return value;
59993   }else{
59994     return 0;
59995   }
59996 }
59997 
59998 /*
59999 ** Return the best representation of pMem that we can get into a
60000 ** double.  If pMem is already a double or an integer, return its
60001 ** value.  If it is a string or blob, try to convert it to a double.
60002 ** If it is a NULL, return 0.0.
60003 */
60004 SQLITE_PRIVATE double sqlite3VdbeRealValue(Mem *pMem){
60005   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60006   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
60007   if( pMem->flags & MEM_Real ){
60008     return pMem->r;
60009   }else if( pMem->flags & MEM_Int ){
60010     return (double)pMem->u.i;
60011   }else if( pMem->flags & (MEM_Str|MEM_Blob) ){
60012     /* (double)0 In case of SQLITE_OMIT_FLOATING_POINT... */
60013     double val = (double)0;
60014     sqlite3AtoF(pMem->z, &val, pMem->n, pMem->enc);
60015     return val;
60016   }else{
60017     /* (double)0 In case of SQLITE_OMIT_FLOATING_POINT... */
60018     return (double)0;
60019   }
60020 }
60021 
60022 /*
60023 ** The MEM structure is already a MEM_Real.  Try to also make it a
60024 ** MEM_Int if we can.
60025 */
60026 SQLITE_PRIVATE void sqlite3VdbeIntegerAffinity(Mem *pMem){
60027   assert( pMem->flags & MEM_Real );
60028   assert( (pMem->flags & MEM_RowSet)==0 );
60029   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60030   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
60031 
60032   pMem->u.i = doubleToInt64(pMem->r);
60033 
60034   /* Only mark the value as an integer if
60035   **
60036   **    (1) the round-trip conversion real->int->real is a no-op, and
60037   **    (2) The integer is neither the largest nor the smallest
60038   **        possible integer (ticket #3922)
60039   **
60040   ** The second and third terms in the following conditional enforces
60041   ** the second condition under the assumption that addition overflow causes
60042   ** values to wrap around.
60043   */
60044   if( pMem->r==(double)pMem->u.i
60045    && pMem->u.i>SMALLEST_INT64
60046    && pMem->u.i<LARGEST_INT64
60047   ){
60048     pMem->flags |= MEM_Int;
60049   }
60050 }
60051 
60052 /*
60053 ** Convert pMem to type integer.  Invalidate any prior representations.
60054 */
60055 SQLITE_PRIVATE int sqlite3VdbeMemIntegerify(Mem *pMem){
60056   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60057   assert( (pMem->flags & MEM_RowSet)==0 );
60058   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
60059 
60060   pMem->u.i = sqlite3VdbeIntValue(pMem);
60061   MemSetTypeFlag(pMem, MEM_Int);
60062   return SQLITE_OK;
60063 }
60064 
60065 /*
60066 ** Convert pMem so that it is of type MEM_Real.
60067 ** Invalidate any prior representations.
60068 */
60069 SQLITE_PRIVATE int sqlite3VdbeMemRealify(Mem *pMem){
60070   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60071   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
60072 
60073   pMem->r = sqlite3VdbeRealValue(pMem);
60074   MemSetTypeFlag(pMem, MEM_Real);
60075   return SQLITE_OK;
60076 }
60077 
60078 /*
60079 ** Convert pMem so that it has types MEM_Real or MEM_Int or both.
60080 ** Invalidate any prior representations.
60081 **
60082 ** Every effort is made to force the conversion, even if the input
60083 ** is a string that does not look completely like a number.  Convert
60084 ** as much of the string as we can and ignore the rest.
60085 */
60086 SQLITE_PRIVATE int sqlite3VdbeMemNumerify(Mem *pMem){
60087   if( (pMem->flags & (MEM_Int|MEM_Real|MEM_Null))==0 ){
60088     assert( (pMem->flags & (MEM_Blob|MEM_Str))!=0 );
60089     assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60090     if( 0==sqlite3Atoi64(pMem->z, &pMem->u.i, pMem->n, pMem->enc) ){
60091       MemSetTypeFlag(pMem, MEM_Int);
60092     }else{
60093       pMem->r = sqlite3VdbeRealValue(pMem);
60094       MemSetTypeFlag(pMem, MEM_Real);
60095       sqlite3VdbeIntegerAffinity(pMem);
60096     }
60097   }
60098   assert( (pMem->flags & (MEM_Int|MEM_Real|MEM_Null))!=0 );
60099   pMem->flags &= ~(MEM_Str|MEM_Blob);
60100   return SQLITE_OK;
60101 }
60102 
60103 /*
60104 ** Delete any previous value and set the value stored in *pMem to NULL.
60105 */
60106 SQLITE_PRIVATE void sqlite3VdbeMemSetNull(Mem *pMem){
60107   if( pMem->flags & MEM_Frame ){
60108     VdbeFrame *pFrame = pMem->u.pFrame;
60109     pFrame->pParent = pFrame->v->pDelFrame;
60110     pFrame->v->pDelFrame = pFrame;
60111   }
60112   if( pMem->flags & MEM_RowSet ){
60113     sqlite3RowSetClear(pMem->u.pRowSet);
60114   }
60115   MemSetTypeFlag(pMem, MEM_Null);
60116   pMem->type = SQLITE_NULL;
60117 }
60118 
60119 /*
60120 ** Delete any previous value and set the value to be a BLOB of length
60121 ** n containing all zeros.
60122 */
60123 SQLITE_PRIVATE void sqlite3VdbeMemSetZeroBlob(Mem *pMem, int n){
60124   sqlite3VdbeMemRelease(pMem);
60125   pMem->flags = MEM_Blob|MEM_Zero;
60126   pMem->type = SQLITE_BLOB;
60127   pMem->n = 0;
60128   if( n<0 ) n = 0;
60129   pMem->u.nZero = n;
60130   pMem->enc = SQLITE_UTF8;
60131 
60132 #ifdef SQLITE_OMIT_INCRBLOB
60133   sqlite3VdbeMemGrow(pMem, n, 0);
60134   if( pMem->z ){
60135     pMem->n = n;
60136     memset(pMem->z, 0, n);
60137   }
60138 #endif
60139 }
60140 
60141 /*
60142 ** Delete any previous value and set the value stored in *pMem to val,
60143 ** manifest type INTEGER.
60144 */
60145 SQLITE_PRIVATE void sqlite3VdbeMemSetInt64(Mem *pMem, i64 val){
60146   sqlite3VdbeMemRelease(pMem);
60147   pMem->u.i = val;
60148   pMem->flags = MEM_Int;
60149   pMem->type = SQLITE_INTEGER;
60150 }
60151 
60152 #ifndef SQLITE_OMIT_FLOATING_POINT
60153 /*
60154 ** Delete any previous value and set the value stored in *pMem to val,
60155 ** manifest type REAL.
60156 */
60157 SQLITE_PRIVATE void sqlite3VdbeMemSetDouble(Mem *pMem, double val){
60158   if( sqlite3IsNaN(val) ){
60159     sqlite3VdbeMemSetNull(pMem);
60160   }else{
60161     sqlite3VdbeMemRelease(pMem);
60162     pMem->r = val;
60163     pMem->flags = MEM_Real;
60164     pMem->type = SQLITE_FLOAT;
60165   }
60166 }
60167 #endif
60168 
60169 /*
60170 ** Delete any previous value and set the value of pMem to be an
60171 ** empty boolean index.
60172 */
60173 SQLITE_PRIVATE void sqlite3VdbeMemSetRowSet(Mem *pMem){
60174   sqlite3 *db = pMem->db;
60175   assert( db!=0 );
60176   assert( (pMem->flags & MEM_RowSet)==0 );
60177   sqlite3VdbeMemRelease(pMem);
60178   pMem->zMalloc = sqlite3DbMallocRaw(db, 64);
60179   if( db->mallocFailed ){
60180     pMem->flags = MEM_Null;
60181   }else{
60182     assert( pMem->zMalloc );
60183     pMem->u.pRowSet = sqlite3RowSetInit(db, pMem->zMalloc, 
60184                                        sqlite3DbMallocSize(db, pMem->zMalloc));
60185     assert( pMem->u.pRowSet!=0 );
60186     pMem->flags = MEM_RowSet;
60187   }
60188 }
60189 
60190 /*
60191 ** Return true if the Mem object contains a TEXT or BLOB that is
60192 ** too large - whose size exceeds SQLITE_MAX_LENGTH.
60193 */
60194 SQLITE_PRIVATE int sqlite3VdbeMemTooBig(Mem *p){
60195   assert( p->db!=0 );
60196   if( p->flags & (MEM_Str|MEM_Blob) ){
60197     int n = p->n;
60198     if( p->flags & MEM_Zero ){
60199       n += p->u.nZero;
60200     }
60201     return n>p->db->aLimit[SQLITE_LIMIT_LENGTH];
60202   }
60203   return 0; 
60204 }
60205 
60206 #ifdef SQLITE_DEBUG
60207 /*
60208 ** This routine prepares a memory cell for modication by breaking
60209 ** its link to a shallow copy and by marking any current shallow
60210 ** copies of this cell as invalid.
60211 **
60212 ** This is used for testing and debugging only - to make sure shallow
60213 ** copies are not misused.
60214 */
60215 SQLITE_PRIVATE void sqlite3VdbeMemAboutToChange(Vdbe *pVdbe, Mem *pMem){
60216   int i;
60217   Mem *pX;
60218   for(i=1, pX=&pVdbe->aMem[1]; i<=pVdbe->nMem; i++, pX++){
60219     if( pX->pScopyFrom==pMem ){
60220       pX->flags |= MEM_Invalid;
60221       pX->pScopyFrom = 0;
60222     }
60223   }
60224   pMem->pScopyFrom = 0;
60225 }
60226 #endif /* SQLITE_DEBUG */
60227 
60228 /*
60229 ** Size of struct Mem not including the Mem.zMalloc member.
60230 */
60231 #define MEMCELLSIZE (size_t)(&(((Mem *)0)->zMalloc))
60232 
60233 /*
60234 ** Make an shallow copy of pFrom into pTo.  Prior contents of
60235 ** pTo are freed.  The pFrom->z field is not duplicated.  If
60236 ** pFrom->z is used, then pTo->z points to the same thing as pFrom->z
60237 ** and flags gets srcType (either MEM_Ephem or MEM_Static).
60238 */
60239 SQLITE_PRIVATE void sqlite3VdbeMemShallowCopy(Mem *pTo, const Mem *pFrom, int srcType){
60240   assert( (pFrom->flags & MEM_RowSet)==0 );
60241   VdbeMemRelease(pTo);
60242   memcpy(pTo, pFrom, MEMCELLSIZE);
60243   pTo->xDel = 0;
60244   if( (pFrom->flags&MEM_Static)==0 ){
60245     pTo->flags &= ~(MEM_Dyn|MEM_Static|MEM_Ephem);
60246     assert( srcType==MEM_Ephem || srcType==MEM_Static );
60247     pTo->flags |= srcType;
60248   }
60249 }
60250 
60251 /*
60252 ** Make a full copy of pFrom into pTo.  Prior contents of pTo are
60253 ** freed before the copy is made.
60254 */
60255 SQLITE_PRIVATE int sqlite3VdbeMemCopy(Mem *pTo, const Mem *pFrom){
60256   int rc = SQLITE_OK;
60257 
60258   assert( (pFrom->flags & MEM_RowSet)==0 );
60259   VdbeMemRelease(pTo);
60260   memcpy(pTo, pFrom, MEMCELLSIZE);
60261   pTo->flags &= ~MEM_Dyn;
60262 
60263   if( pTo->flags&(MEM_Str|MEM_Blob) ){
60264     if( 0==(pFrom->flags&MEM_Static) ){
60265       pTo->flags |= MEM_Ephem;
60266       rc = sqlite3VdbeMemMakeWriteable(pTo);
60267     }
60268   }
60269 
60270   return rc;
60271 }
60272 
60273 /*
60274 ** Transfer the contents of pFrom to pTo. Any existing value in pTo is
60275 ** freed. If pFrom contains ephemeral data, a copy is made.
60276 **
60277 ** pFrom contains an SQL NULL when this routine returns.
60278 */
60279 SQLITE_PRIVATE void sqlite3VdbeMemMove(Mem *pTo, Mem *pFrom){
60280   assert( pFrom->db==0 || sqlite3_mutex_held(pFrom->db->mutex) );
60281   assert( pTo->db==0 || sqlite3_mutex_held(pTo->db->mutex) );
60282   assert( pFrom->db==0 || pTo->db==0 || pFrom->db==pTo->db );
60283 
60284   sqlite3VdbeMemRelease(pTo);
60285   memcpy(pTo, pFrom, sizeof(Mem));
60286   pFrom->flags = MEM_Null;
60287   pFrom->xDel = 0;
60288   pFrom->zMalloc = 0;
60289 }
60290 
60291 /*
60292 ** Change the value of a Mem to be a string or a BLOB.
60293 **
60294 ** The memory management strategy depends on the value of the xDel
60295 ** parameter. If the value passed is SQLITE_TRANSIENT, then the 
60296 ** string is copied into a (possibly existing) buffer managed by the 
60297 ** Mem structure. Otherwise, any existing buffer is freed and the
60298 ** pointer copied.
60299 **
60300 ** If the string is too large (if it exceeds the SQLITE_LIMIT_LENGTH
60301 ** size limit) then no memory allocation occurs.  If the string can be
60302 ** stored without allocating memory, then it is.  If a memory allocation
60303 ** is required to store the string, then value of pMem is unchanged.  In
60304 ** either case, SQLITE_TOOBIG is returned.
60305 */
60306 SQLITE_PRIVATE int sqlite3VdbeMemSetStr(
60307   Mem *pMem,          /* Memory cell to set to string value */
60308   const char *z,      /* String pointer */
60309   int n,              /* Bytes in string, or negative */
60310   u8 enc,             /* Encoding of z.  0 for BLOBs */
60311   void (*xDel)(void*) /* Destructor function */
60312 ){
60313   int nByte = n;      /* New value for pMem->n */
60314   int iLimit;         /* Maximum allowed string or blob size */
60315   u16 flags = 0;      /* New value for pMem->flags */
60316 
60317   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60318   assert( (pMem->flags & MEM_RowSet)==0 );
60319 
60320   /* If z is a NULL pointer, set pMem to contain an SQL NULL. */
60321   if( !z ){
60322     sqlite3VdbeMemSetNull(pMem);
60323     return SQLITE_OK;
60324   }
60325 
60326   if( pMem->db ){
60327     iLimit = pMem->db->aLimit[SQLITE_LIMIT_LENGTH];
60328   }else{
60329     iLimit = SQLITE_MAX_LENGTH;
60330   }
60331   flags = (enc==0?MEM_Blob:MEM_Str);
60332   if( nByte<0 ){
60333     assert( enc!=0 );
60334     if( enc==SQLITE_UTF8 ){
60335       for(nByte=0; nByte<=iLimit && z[nByte]; nByte++){}
60336     }else{
60337       for(nByte=0; nByte<=iLimit && (z[nByte] | z[nByte+1]); nByte+=2){}
60338     }
60339     flags |= MEM_Term;
60340   }
60341 
60342   /* The following block sets the new values of Mem.z and Mem.xDel. It
60343   ** also sets a flag in local variable "flags" to indicate the memory
60344   ** management (one of MEM_Dyn or MEM_Static).
60345   */
60346   if( xDel==SQLITE_TRANSIENT ){
60347     int nAlloc = nByte;
60348     if( flags&MEM_Term ){
60349       nAlloc += (enc==SQLITE_UTF8?1:2);
60350     }
60351     if( nByte>iLimit ){
60352       return SQLITE_TOOBIG;
60353     }
60354     if( sqlite3VdbeMemGrow(pMem, nAlloc, 0) ){
60355       return SQLITE_NOMEM;
60356     }
60357     memcpy(pMem->z, z, nAlloc);
60358   }else if( xDel==SQLITE_DYNAMIC ){
60359     sqlite3VdbeMemRelease(pMem);
60360     pMem->zMalloc = pMem->z = (char *)z;
60361     pMem->xDel = 0;
60362   }else{
60363     sqlite3VdbeMemRelease(pMem);
60364     pMem->z = (char *)z;
60365     pMem->xDel = xDel;
60366     flags |= ((xDel==SQLITE_STATIC)?MEM_Static:MEM_Dyn);
60367   }
60368 
60369   pMem->n = nByte;
60370   pMem->flags = flags;
60371   pMem->enc = (enc==0 ? SQLITE_UTF8 : enc);
60372   pMem->type = (enc==0 ? SQLITE_BLOB : SQLITE_TEXT);
60373 
60374 #ifndef SQLITE_OMIT_UTF16
60375   if( pMem->enc!=SQLITE_UTF8 && sqlite3VdbeMemHandleBom(pMem) ){
60376     return SQLITE_NOMEM;
60377   }
60378 #endif
60379 
60380   if( nByte>iLimit ){
60381     return SQLITE_TOOBIG;
60382   }
60383 
60384   return SQLITE_OK;
60385 }
60386 
60387 /*
60388 ** Compare the values contained by the two memory cells, returning
60389 ** negative, zero or positive if pMem1 is less than, equal to, or greater
60390 ** than pMem2. Sorting order is NULL's first, followed by numbers (integers
60391 ** and reals) sorted numerically, followed by text ordered by the collating
60392 ** sequence pColl and finally blob's ordered by memcmp().
60393 **
60394 ** Two NULL values are considered equal by this function.
60395 */
60396 SQLITE_PRIVATE int sqlite3MemCompare(const Mem *pMem1, const Mem *pMem2, const CollSeq *pColl){
60397   int rc;
60398   int f1, f2;
60399   int combined_flags;
60400 
60401   f1 = pMem1->flags;
60402   f2 = pMem2->flags;
60403   combined_flags = f1|f2;
60404   assert( (combined_flags & MEM_RowSet)==0 );
60405  
60406   /* If one value is NULL, it is less than the other. If both values
60407   ** are NULL, return 0.
60408   */
60409   if( combined_flags&MEM_Null ){
60410     return (f2&MEM_Null) - (f1&MEM_Null);
60411   }
60412 
60413   /* If one value is a number and the other is not, the number is less.
60414   ** If both are numbers, compare as reals if one is a real, or as integers
60415   ** if both values are integers.
60416   */
60417   if( combined_flags&(MEM_Int|MEM_Real) ){
60418     double r1, r2;
60419     if( (f1 & f2 & MEM_Int)!=0 ){
60420       if( pMem1->u.i < pMem2->u.i ) return -1;
60421       if( pMem1->u.i > pMem2->u.i ) return 1;
60422       return 0;
60423     }
60424     if( (f1&MEM_Real)!=0 ){
60425       r1 = pMem1->r;
60426     }else if( (f1&MEM_Int)!=0 ){
60427       r1 = (double)pMem1->u.i;
60428     }else{
60429       return 1;
60430     }
60431     if( (f2&MEM_Real)!=0 ){
60432       r2 = pMem2->r;
60433     }else if( (f2&MEM_Int)!=0 ){
60434       r2 = (double)pMem2->u.i;
60435     }else{
60436       return -1;
60437     }
60438     if( r1<r2 ) return -1;
60439     if( r1>r2 ) return 1;
60440     return 0;
60441   }
60442 
60443   /* If one value is a string and the other is a blob, the string is less.
60444   ** If both are strings, compare using the collating functions.
60445   */
60446   if( combined_flags&MEM_Str ){
60447     if( (f1 & MEM_Str)==0 ){
60448       return 1;
60449     }
60450     if( (f2 & MEM_Str)==0 ){
60451       return -1;
60452     }
60453 
60454     assert( pMem1->enc==pMem2->enc );
60455     assert( pMem1->enc==SQLITE_UTF8 || 
60456             pMem1->enc==SQLITE_UTF16LE || pMem1->enc==SQLITE_UTF16BE );
60457 
60458     /* The collation sequence must be defined at this point, even if
60459     ** the user deletes the collation sequence after the vdbe program is
60460     ** compiled (this was not always the case).
60461     */
60462     assert( !pColl || pColl->xCmp );
60463 
60464     if( pColl ){
60465       if( pMem1->enc==pColl->enc ){
60466         /* The strings are already in the correct encoding.  Call the
60467         ** comparison function directly */
60468         return pColl->xCmp(pColl->pUser,pMem1->n,pMem1->z,pMem2->n,pMem2->z);
60469       }else{
60470         const void *v1, *v2;
60471         int n1, n2;
60472         Mem c1;
60473         Mem c2;
60474         memset(&c1, 0, sizeof(c1));
60475         memset(&c2, 0, sizeof(c2));
60476         sqlite3VdbeMemShallowCopy(&c1, pMem1, MEM_Ephem);
60477         sqlite3VdbeMemShallowCopy(&c2, pMem2, MEM_Ephem);
60478         v1 = sqlite3ValueText((sqlite3_value*)&c1, pColl->enc);
60479         n1 = v1==0 ? 0 : c1.n;
60480         v2 = sqlite3ValueText((sqlite3_value*)&c2, pColl->enc);
60481         n2 = v2==0 ? 0 : c2.n;
60482         rc = pColl->xCmp(pColl->pUser, n1, v1, n2, v2);
60483         sqlite3VdbeMemRelease(&c1);
60484         sqlite3VdbeMemRelease(&c2);
60485         return rc;
60486       }
60487     }
60488     /* If a NULL pointer was passed as the collate function, fall through
60489     ** to the blob case and use memcmp().  */
60490   }
60491  
60492   /* Both values must be blobs.  Compare using memcmp().  */
60493   rc = memcmp(pMem1->z, pMem2->z, (pMem1->n>pMem2->n)?pMem2->n:pMem1->n);
60494   if( rc==0 ){
60495     rc = pMem1->n - pMem2->n;
60496   }
60497   return rc;
60498 }
60499 
60500 /*
60501 ** Move data out of a btree key or data field and into a Mem structure.
60502 ** The data or key is taken from the entry that pCur is currently pointing
60503 ** to.  offset and amt determine what portion of the data or key to retrieve.
60504 ** key is true to get the key or false to get data.  The result is written
60505 ** into the pMem element.
60506 **
60507 ** The pMem structure is assumed to be uninitialized.  Any prior content
60508 ** is overwritten without being freed.
60509 **
60510 ** If this routine fails for any reason (malloc returns NULL or unable
60511 ** to read from the disk) then the pMem is left in an inconsistent state.
60512 */
60513 SQLITE_PRIVATE int sqlite3VdbeMemFromBtree(
60514   BtCursor *pCur,   /* Cursor pointing at record to retrieve. */
60515   u32 offset,       /* Offset from the start of data to return bytes from. */
60516   u32 amt,          /* Number of bytes to return. */
60517   int key,          /* If true, retrieve from the btree key, not data. */
60518   Mem *pMem         /* OUT: Return data in this Mem structure. */
60519 ){
60520   char *zData;        /* Data from the btree layer */
60521   u32 available = 0;  /* Number of bytes available on the local btree page */
60522   int rc = SQLITE_OK; /* Return code */
60523 
60524   assert( sqlite3BtreeCursorIsValid(pCur) );
60525 
60526   /* Note: the calls to BtreeKeyFetch() and DataFetch() below assert() 
60527   ** that both the BtShared and database handle mutexes are held. */
60528   assert( (pMem->flags & MEM_RowSet)==0 );
60529   if( key ){
60530     zData = (char *)sqlite3BtreeKeyFetch(pCur, &available);
60531   }else{
60532     zData = (char *)sqlite3BtreeDataFetch(pCur, &available);
60533   }
60534   assert( zData!=0 );
60535 
60536   if( offset+amt<=available ){
60537     sqlite3VdbeMemRelease(pMem);
60538     pMem->z = &zData[offset];
60539     pMem->flags = MEM_Blob|MEM_Ephem;
60540   }else if( SQLITE_OK==(rc = sqlite3VdbeMemGrow(pMem, amt+2, 0)) ){
60541     pMem->flags = MEM_Blob|MEM_Dyn|MEM_Term;
60542     pMem->enc = 0;
60543     pMem->type = SQLITE_BLOB;
60544     if( key ){
60545       rc = sqlite3BtreeKey(pCur, offset, amt, pMem->z);
60546     }else{
60547       rc = sqlite3BtreeData(pCur, offset, amt, pMem->z);
60548     }
60549     pMem->z[amt] = 0;
60550     pMem->z[amt+1] = 0;
60551     if( rc!=SQLITE_OK ){
60552       sqlite3VdbeMemRelease(pMem);
60553     }
60554   }
60555   pMem->n = (int)amt;
60556 
60557   return rc;
60558 }
60559 
60560 /* This function is only available internally, it is not part of the
60561 ** external API. It works in a similar way to sqlite3_value_text(),
60562 ** except the data returned is in the encoding specified by the second
60563 ** parameter, which must be one of SQLITE_UTF16BE, SQLITE_UTF16LE or
60564 ** SQLITE_UTF8.
60565 **
60566 ** (2006-02-16:)  The enc value can be or-ed with SQLITE_UTF16_ALIGNED.
60567 ** If that is the case, then the result must be aligned on an even byte
60568 ** boundary.
60569 */
60570 SQLITE_PRIVATE const void *sqlite3ValueText(sqlite3_value* pVal, u8 enc){
60571   if( !pVal ) return 0;
60572 
60573   assert( pVal->db==0 || sqlite3_mutex_held(pVal->db->mutex) );
60574   assert( (enc&3)==(enc&~SQLITE_UTF16_ALIGNED) );
60575   assert( (pVal->flags & MEM_RowSet)==0 );
60576 
60577   if( pVal->flags&MEM_Null ){
60578     return 0;
60579   }
60580   assert( (MEM_Blob>>3) == MEM_Str );
60581   pVal->flags |= (pVal->flags & MEM_Blob)>>3;
60582   ExpandBlob(pVal);
60583   if( pVal->flags&MEM_Str ){
60584     sqlite3VdbeChangeEncoding(pVal, enc & ~SQLITE_UTF16_ALIGNED);
60585     if( (enc & SQLITE_UTF16_ALIGNED)!=0 && 1==(1&SQLITE_PTR_TO_INT(pVal->z)) ){
60586       assert( (pVal->flags & (MEM_Ephem|MEM_Static))!=0 );
60587       if( sqlite3VdbeMemMakeWriteable(pVal)!=SQLITE_OK ){
60588         return 0;
60589       }
60590     }
60591     sqlite3VdbeMemNulTerminate(pVal); /* IMP: R-31275-44060 */
60592   }else{
60593     assert( (pVal->flags&MEM_Blob)==0 );
60594     sqlite3VdbeMemStringify(pVal, enc);
60595     assert( 0==(1&SQLITE_PTR_TO_INT(pVal->z)) );
60596   }
60597   assert(pVal->enc==(enc & ~SQLITE_UTF16_ALIGNED) || pVal->db==0
60598               || pVal->db->mallocFailed );
60599   if( pVal->enc==(enc & ~SQLITE_UTF16_ALIGNED) ){
60600     return pVal->z;
60601   }else{
60602     return 0;
60603   }
60604 }
60605 
60606 /*
60607 ** Create a new sqlite3_value object.
60608 */
60609 SQLITE_PRIVATE sqlite3_value *sqlite3ValueNew(sqlite3 *db){
60610   Mem *p = sqlite3DbMallocZero(db, sizeof(*p));
60611   if( p ){
60612     p->flags = MEM_Null;
60613     p->type = SQLITE_NULL;
60614     p->db = db;
60615   }
60616   return p;
60617 }
60618 
60619 /*
60620 ** Context object passed by sqlite3Stat4ProbeSetValue() through to 
60621 ** valueNew(). See comments above valueNew() for details.
60622 */
60623 struct ValueNewStat4Ctx {
60624   Parse *pParse;
60625   Index *pIdx;
60626   UnpackedRecord **ppRec;
60627   int iVal;
60628 };
60629 
60630 /*
60631 ** Allocate and return a pointer to a new sqlite3_value object. If
60632 ** the second argument to this function is NULL, the object is allocated
60633 ** by calling sqlite3ValueNew().
60634 **
60635 ** Otherwise, if the second argument is non-zero, then this function is 
60636 ** being called indirectly by sqlite3Stat4ProbeSetValue(). If it has not
60637 ** already been allocated, allocate the UnpackedRecord structure that 
60638 ** that function will return to its caller here. Then return a pointer 
60639 ** an sqlite3_value within the UnpackedRecord.a[] array.
60640 */
60641 static sqlite3_value *valueNew(sqlite3 *db, struct ValueNewStat4Ctx *p){
60642 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
60643   if( p ){
60644     UnpackedRecord *pRec = p->ppRec[0];
60645 
60646     if( pRec==0 ){
60647       Index *pIdx = p->pIdx;      /* Index being probed */
60648       int nByte;                  /* Bytes of space to allocate */
60649       int i;                      /* Counter variable */
60650       int nCol = pIdx->nColumn;   /* Number of index columns including rowid */
60651   
60652       nByte = sizeof(Mem) * nCol + ROUND8(sizeof(UnpackedRecord));
60653       pRec = (UnpackedRecord*)sqlite3DbMallocZero(db, nByte);
60654       if( pRec ){
60655         pRec->pKeyInfo = sqlite3KeyInfoOfIndex(p->pParse, pIdx);
60656         if( pRec->pKeyInfo ){
60657           assert( pRec->pKeyInfo->nField+pRec->pKeyInfo->nXField==nCol );
60658           assert( pRec->pKeyInfo->enc==ENC(db) );
60659           pRec->flags = UNPACKED_PREFIX_MATCH;
60660           pRec->aMem = (Mem *)((u8*)pRec + ROUND8(sizeof(UnpackedRecord)));
60661           for(i=0; i<nCol; i++){
60662             pRec->aMem[i].flags = MEM_Null;
60663             pRec->aMem[i].type = SQLITE_NULL;
60664             pRec->aMem[i].db = db;
60665           }
60666         }else{
60667           sqlite3DbFree(db, pRec);
60668           pRec = 0;
60669         }
60670       }
60671       if( pRec==0 ) return 0;
60672       p->ppRec[0] = pRec;
60673     }
60674   
60675     pRec->nField = p->iVal+1;
60676     return &pRec->aMem[p->iVal];
60677   }
60678 #else
60679   UNUSED_PARAMETER(p);
60680 #endif /* defined(SQLITE_ENABLE_STAT3_OR_STAT4) */
60681   return sqlite3ValueNew(db);
60682 }
60683 
60684 /*
60685 ** Extract a value from the supplied expression in the manner described
60686 ** above sqlite3ValueFromExpr(). Allocate the sqlite3_value object
60687 ** using valueNew().
60688 **
60689 ** If pCtx is NULL and an error occurs after the sqlite3_value object
60690 ** has been allocated, it is freed before returning. Or, if pCtx is not
60691 ** NULL, it is assumed that the caller will free any allocated object
60692 ** in all cases.
60693 */
60694 static int valueFromExpr(
60695   sqlite3 *db,                    /* The database connection */
60696   Expr *pExpr,                    /* The expression to evaluate */
60697   u8 enc,                         /* Encoding to use */
60698   u8 affinity,                    /* Affinity to use */
60699   sqlite3_value **ppVal,          /* Write the new value here */
60700   struct ValueNewStat4Ctx *pCtx   /* Second argument for valueNew() */
60701 ){
60702   int op;
60703   char *zVal = 0;
60704   sqlite3_value *pVal = 0;
60705   int negInt = 1;
60706   const char *zNeg = "";
60707   int rc = SQLITE_OK;
60708 
60709   if( !pExpr ){
60710     *ppVal = 0;
60711     return SQLITE_OK;
60712   }
60713   op = pExpr->op;
60714   if( NEVER(op==TK_REGISTER) ) op = pExpr->op2;
60715 
60716   /* Handle negative integers in a single step.  This is needed in the
60717   ** case when the value is -9223372036854775808.
60718   */
60719   if( op==TK_UMINUS
60720    && (pExpr->pLeft->op==TK_INTEGER || pExpr->pLeft->op==TK_FLOAT) ){
60721     pExpr = pExpr->pLeft;
60722     op = pExpr->op;
60723     negInt = -1;
60724     zNeg = "-";
60725   }
60726 
60727   if( op==TK_STRING || op==TK_FLOAT || op==TK_INTEGER ){
60728     pVal = valueNew(db, pCtx);
60729     if( pVal==0 ) goto no_mem;
60730     if( ExprHasProperty(pExpr, EP_IntValue) ){
60731       sqlite3VdbeMemSetInt64(pVal, (i64)pExpr->u.iValue*negInt);
60732     }else{
60733       zVal = sqlite3MPrintf(db, "%s%s", zNeg, pExpr->u.zToken);
60734       if( zVal==0 ) goto no_mem;
60735       sqlite3ValueSetStr(pVal, -1, zVal, SQLITE_UTF8, SQLITE_DYNAMIC);
60736       if( op==TK_FLOAT ) pVal->type = SQLITE_FLOAT;
60737     }
60738     if( (op==TK_INTEGER || op==TK_FLOAT ) && affinity==SQLITE_AFF_NONE ){
60739       sqlite3ValueApplyAffinity(pVal, SQLITE_AFF_NUMERIC, SQLITE_UTF8);
60740     }else{
60741       sqlite3ValueApplyAffinity(pVal, affinity, SQLITE_UTF8);
60742     }
60743     if( pVal->flags & (MEM_Int|MEM_Real) ) pVal->flags &= ~MEM_Str;
60744     if( enc!=SQLITE_UTF8 ){
60745       rc = sqlite3VdbeChangeEncoding(pVal, enc);
60746     }
60747   }else if( op==TK_UMINUS ) {
60748     /* This branch happens for multiple negative signs.  Ex: -(-5) */
60749     if( SQLITE_OK==sqlite3ValueFromExpr(db,pExpr->pLeft,enc,affinity,&pVal) 
60750      && pVal!=0
60751     ){
60752       sqlite3VdbeMemNumerify(pVal);
60753       if( pVal->u.i==SMALLEST_INT64 ){
60754         pVal->flags &= MEM_Int;
60755         pVal->flags |= MEM_Real;
60756         pVal->r = (double)LARGEST_INT64;
60757       }else{
60758         pVal->u.i = -pVal->u.i;
60759       }
60760       pVal->r = -pVal->r;
60761       sqlite3ValueApplyAffinity(pVal, affinity, enc);
60762     }
60763   }else if( op==TK_NULL ){
60764     pVal = valueNew(db, pCtx);
60765     if( pVal==0 ) goto no_mem;
60766   }
60767 #ifndef SQLITE_OMIT_BLOB_LITERAL
60768   else if( op==TK_BLOB ){
60769     int nVal;
60770     assert( pExpr->u.zToken[0]=='x' || pExpr->u.zToken[0]=='X' );
60771     assert( pExpr->u.zToken[1]=='\'' );
60772     pVal = valueNew(db, pCtx);
60773     if( !pVal ) goto no_mem;
60774     zVal = &pExpr->u.zToken[2];
60775     nVal = sqlite3Strlen30(zVal)-1;
60776     assert( zVal[nVal]=='\'' );
60777     sqlite3VdbeMemSetStr(pVal, sqlite3HexToBlob(db, zVal, nVal), nVal/2,
60778                          0, SQLITE_DYNAMIC);
60779   }
60780 #endif
60781 
60782   if( pVal ){
60783     sqlite3VdbeMemStoreType(pVal);
60784   }
60785   *ppVal = pVal;
60786   return rc;
60787 
60788 no_mem:
60789   db->mallocFailed = 1;
60790   sqlite3DbFree(db, zVal);
60791   assert( *ppVal==0 );
60792 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
60793   if( pCtx==0 ) sqlite3ValueFree(pVal);
60794 #else
60795   assert( pCtx==0 ); sqlite3ValueFree(pVal);
60796 #endif
60797   return SQLITE_NOMEM;
60798 }
60799 
60800 /*
60801 ** Create a new sqlite3_value object, containing the value of pExpr.
60802 **
60803 ** This only works for very simple expressions that consist of one constant
60804 ** token (i.e. "5", "5.1", "'a string'"). If the expression can
60805 ** be converted directly into a value, then the value is allocated and
60806 ** a pointer written to *ppVal. The caller is responsible for deallocating
60807 ** the value by passing it to sqlite3ValueFree() later on. If the expression
60808 ** cannot be converted to a value, then *ppVal is set to NULL.
60809 */
60810 SQLITE_PRIVATE int sqlite3ValueFromExpr(
60811   sqlite3 *db,              /* The database connection */
60812   Expr *pExpr,              /* The expression to evaluate */
60813   u8 enc,                   /* Encoding to use */
60814   u8 affinity,              /* Affinity to use */
60815   sqlite3_value **ppVal     /* Write the new value here */
60816 ){
60817   return valueFromExpr(db, pExpr, enc, affinity, ppVal, 0);
60818 }
60819 
60820 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
60821 /*
60822 ** The implementation of the sqlite_record() function. This function accepts
60823 ** a single argument of any type. The return value is a formatted database 
60824 ** record (a blob) containing the argument value.
60825 **
60826 ** This is used to convert the value stored in the 'sample' column of the
60827 ** sqlite_stat3 table to the record format SQLite uses internally.
60828 */
60829 static void recordFunc(
60830   sqlite3_context *context,
60831   int argc,
60832   sqlite3_value **argv
60833 ){
60834   const int file_format = 1;
60835   int iSerial;                    /* Serial type */
60836   int nSerial;                    /* Bytes of space for iSerial as varint */
60837   int nVal;                       /* Bytes of space required for argv[0] */
60838   int nRet;
60839   sqlite3 *db;
60840   u8 *aRet;
60841 
60842   UNUSED_PARAMETER( argc );
60843   iSerial = sqlite3VdbeSerialType(argv[0], file_format);
60844   nSerial = sqlite3VarintLen(iSerial);
60845   nVal = sqlite3VdbeSerialTypeLen(iSerial);
60846   db = sqlite3_context_db_handle(context);
60847 
60848   nRet = 1 + nSerial + nVal;
60849   aRet = sqlite3DbMallocRaw(db, nRet);
60850   if( aRet==0 ){
60851     sqlite3_result_error_nomem(context);
60852   }else{
60853     aRet[0] = nSerial+1;
60854     sqlite3PutVarint(&aRet[1], iSerial);
60855     sqlite3VdbeSerialPut(&aRet[1+nSerial], nVal, argv[0], file_format);
60856     sqlite3_result_blob(context, aRet, nRet, SQLITE_TRANSIENT);
60857     sqlite3DbFree(db, aRet);
60858   }
60859 }
60860 
60861 /*
60862 ** Register built-in functions used to help read ANALYZE data.
60863 */
60864 SQLITE_PRIVATE void sqlite3AnalyzeFunctions(void){
60865   static SQLITE_WSD FuncDef aAnalyzeTableFuncs[] = {
60866     FUNCTION(sqlite_record,   1, 0, 0, recordFunc),
60867   };
60868   int i;
60869   FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
60870   FuncDef *aFunc = (FuncDef*)&GLOBAL(FuncDef, aAnalyzeTableFuncs);
60871   for(i=0; i<ArraySize(aAnalyzeTableFuncs); i++){
60872     sqlite3FuncDefInsert(pHash, &aFunc[i]);
60873   }
60874 }
60875 
60876 /*
60877 ** This function is used to allocate and populate UnpackedRecord 
60878 ** structures intended to be compared against sample index keys stored 
60879 ** in the sqlite_stat4 table.
60880 **
60881 ** A single call to this function attempts to populates field iVal (leftmost 
60882 ** is 0 etc.) of the unpacked record with a value extracted from expression
60883 ** pExpr. Extraction of values is possible if:
60884 **
60885 **  * (pExpr==0). In this case the value is assumed to be an SQL NULL,
60886 **
60887 **  * The expression is a bound variable, and this is a reprepare, or
60888 **
60889 **  * The sqlite3ValueFromExpr() function is able to extract a value 
60890 **    from the expression (i.e. the expression is a literal value).
60891 **
60892 ** If a value can be extracted, the affinity passed as the 5th argument
60893 ** is applied to it before it is copied into the UnpackedRecord. Output
60894 ** parameter *pbOk is set to true if a value is extracted, or false 
60895 ** otherwise.
60896 **
60897 ** When this function is called, *ppRec must either point to an object
60898 ** allocated by an earlier call to this function, or must be NULL. If it
60899 ** is NULL and a value can be successfully extracted, a new UnpackedRecord
60900 ** is allocated (and *ppRec set to point to it) before returning.
60901 **
60902 ** Unless an error is encountered, SQLITE_OK is returned. It is not an
60903 ** error if a value cannot be extracted from pExpr. If an error does
60904 ** occur, an SQLite error code is returned.
60905 */
60906 SQLITE_PRIVATE int sqlite3Stat4ProbeSetValue(
60907   Parse *pParse,                  /* Parse context */
60908   Index *pIdx,                    /* Index being probed */
60909   UnpackedRecord **ppRec,         /* IN/OUT: Probe record */
60910   Expr *pExpr,                    /* The expression to extract a value from */
60911   u8 affinity,                    /* Affinity to use */
60912   int iVal,                       /* Array element to populate */
60913   int *pbOk                       /* OUT: True if value was extracted */
60914 ){
60915   int rc = SQLITE_OK;
60916   sqlite3_value *pVal = 0;
60917   sqlite3 *db = pParse->db;
60918 
60919 
60920   struct ValueNewStat4Ctx alloc;
60921   alloc.pParse = pParse;
60922   alloc.pIdx = pIdx;
60923   alloc.ppRec = ppRec;
60924   alloc.iVal = iVal;
60925 
60926   /* Skip over any TK_COLLATE nodes */
60927   pExpr = sqlite3ExprSkipCollate(pExpr);
60928 
60929   if( !pExpr ){
60930     pVal = valueNew(db, &alloc);
60931     if( pVal ){
60932       sqlite3VdbeMemSetNull((Mem*)pVal);
60933     }
60934   }else if( pExpr->op==TK_VARIABLE
60935         || NEVER(pExpr->op==TK_REGISTER && pExpr->op2==TK_VARIABLE)
60936   ){
60937     Vdbe *v;
60938     int iBindVar = pExpr->iColumn;
60939     sqlite3VdbeSetVarmask(pParse->pVdbe, iBindVar);
60940     if( (v = pParse->pReprepare)!=0 ){
60941       pVal = valueNew(db, &alloc);
60942       if( pVal ){
60943         rc = sqlite3VdbeMemCopy((Mem*)pVal, &v->aVar[iBindVar-1]);
60944         if( rc==SQLITE_OK ){
60945           sqlite3ValueApplyAffinity(pVal, affinity, ENC(db));
60946         }
60947         pVal->db = pParse->db;
60948         sqlite3VdbeMemStoreType((Mem*)pVal);
60949       }
60950     }
60951   }else{
60952     rc = valueFromExpr(db, pExpr, ENC(db), affinity, &pVal, &alloc);
60953   }
60954   *pbOk = (pVal!=0);
60955 
60956   assert( pVal==0 || pVal->db==db );
60957   return rc;
60958 }
60959 
60960 /*
60961 ** Unless it is NULL, the argument must be an UnpackedRecord object returned
60962 ** by an earlier call to sqlite3Stat4ProbeSetValue(). This call deletes
60963 ** the object.
60964 */
60965 SQLITE_PRIVATE void sqlite3Stat4ProbeFree(UnpackedRecord *pRec){
60966   if( pRec ){
60967     int i;
60968     int nCol = pRec->pKeyInfo->nField+pRec->pKeyInfo->nXField;
60969     Mem *aMem = pRec->aMem;
60970     sqlite3 *db = aMem[0].db;
60971     for(i=0; i<nCol; i++){
60972       sqlite3DbFree(db, aMem[i].zMalloc);
60973     }
60974     sqlite3KeyInfoUnref(pRec->pKeyInfo);
60975     sqlite3DbFree(db, pRec);
60976   }
60977 }
60978 #endif /* ifdef SQLITE_ENABLE_STAT4 */
60979 
60980 /*
60981 ** Change the string value of an sqlite3_value object
60982 */
60983 SQLITE_PRIVATE void sqlite3ValueSetStr(
60984   sqlite3_value *v,     /* Value to be set */
60985   int n,                /* Length of string z */
60986   const void *z,        /* Text of the new string */
60987   u8 enc,               /* Encoding to use */
60988   void (*xDel)(void*)   /* Destructor for the string */
60989 ){
60990   if( v ) sqlite3VdbeMemSetStr((Mem *)v, z, n, enc, xDel);
60991 }
60992 
60993 /*
60994 ** Free an sqlite3_value object
60995 */
60996 SQLITE_PRIVATE void sqlite3ValueFree(sqlite3_value *v){
60997   if( !v ) return;
60998   sqlite3VdbeMemRelease((Mem *)v);
60999   sqlite3DbFree(((Mem*)v)->db, v);
61000 }
61001 
61002 /*
61003 ** Return the number of bytes in the sqlite3_value object assuming
61004 ** that it uses the encoding "enc"
61005 */
61006 SQLITE_PRIVATE int sqlite3ValueBytes(sqlite3_value *pVal, u8 enc){
61007   Mem *p = (Mem*)pVal;
61008   if( (p->flags & MEM_Blob)!=0 || sqlite3ValueText(pVal, enc) ){
61009     if( p->flags & MEM_Zero ){
61010       return p->n + p->u.nZero;
61011     }else{
61012       return p->n;
61013     }
61014   }
61015   return 0;
61016 }
61017 
61018 /************** End of vdbemem.c *********************************************/
61019 /************** Begin file vdbeaux.c *****************************************/
61020 /*
61021 ** 2003 September 6
61022 **
61023 ** The author disclaims copyright to this source code.  In place of
61024 ** a legal notice, here is a blessing:
61025 **
61026 **    May you do good and not evil.
61027 **    May you find forgiveness for yourself and forgive others.
61028 **    May you share freely, never taking more than you give.
61029 **
61030 *************************************************************************
61031 ** This file contains code used for creating, destroying, and populating
61032 ** a VDBE (or an "sqlite3_stmt" as it is known to the outside world.)  Prior
61033 ** to version 2.8.7, all this code was combined into the vdbe.c source file.
61034 ** But that file was getting too big so this subroutines were split out.
61035 */
61036 
61037 /*
61038 ** Create a new virtual database engine.
61039 */
61040 SQLITE_PRIVATE Vdbe *sqlite3VdbeCreate(sqlite3 *db){
61041   Vdbe *p;
61042   p = sqlite3DbMallocZero(db, sizeof(Vdbe) );
61043   if( p==0 ) return 0;
61044   p->db = db;
61045   if( db->pVdbe ){
61046     db->pVdbe->pPrev = p;
61047   }
61048   p->pNext = db->pVdbe;
61049   p->pPrev = 0;
61050   db->pVdbe = p;
61051   p->magic = VDBE_MAGIC_INIT;
61052   return p;
61053 }
61054 
61055 /*
61056 ** Remember the SQL string for a prepared statement.
61057 */
61058 SQLITE_PRIVATE void sqlite3VdbeSetSql(Vdbe *p, const char *z, int n, int isPrepareV2){
61059   assert( isPrepareV2==1 || isPrepareV2==0 );
61060   if( p==0 ) return;
61061 #if defined(SQLITE_OMIT_TRACE) && !defined(SQLITE_ENABLE_SQLLOG)
61062   if( !isPrepareV2 ) return;
61063 #endif
61064   assert( p->zSql==0 );
61065   p->zSql = sqlite3DbStrNDup(p->db, z, n);
61066   p->isPrepareV2 = (u8)isPrepareV2;
61067 }
61068 
61069 /*
61070 ** Return the SQL associated with a prepared statement
61071 */
61072 SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt){
61073   Vdbe *p = (Vdbe *)pStmt;
61074   return (p && p->isPrepareV2) ? p->zSql : 0;
61075 }
61076 
61077 /*
61078 ** Swap all content between two VDBE structures.
61079 */
61080 SQLITE_PRIVATE void sqlite3VdbeSwap(Vdbe *pA, Vdbe *pB){
61081   Vdbe tmp, *pTmp;
61082   char *zTmp;
61083   tmp = *pA;
61084   *pA = *pB;
61085   *pB = tmp;
61086   pTmp = pA->pNext;
61087   pA->pNext = pB->pNext;
61088   pB->pNext = pTmp;
61089   pTmp = pA->pPrev;
61090   pA->pPrev = pB->pPrev;
61091   pB->pPrev = pTmp;
61092   zTmp = pA->zSql;
61093   pA->zSql = pB->zSql;
61094   pB->zSql = zTmp;
61095   pB->isPrepareV2 = pA->isPrepareV2;
61096 }
61097 
61098 /*
61099 ** Resize the Vdbe.aOp array so that it is at least one op larger than 
61100 ** it was.
61101 **
61102 ** If an out-of-memory error occurs while resizing the array, return
61103 ** SQLITE_NOMEM. In this case Vdbe.aOp and Vdbe.nOpAlloc remain 
61104 ** unchanged (this is so that any opcodes already allocated can be 
61105 ** correctly deallocated along with the rest of the Vdbe).
61106 */
61107 static int growOpArray(Vdbe *p){
61108   VdbeOp *pNew;
61109   int nNew = (p->nOpAlloc ? p->nOpAlloc*2 : (int)(1024/sizeof(Op)));
61110   pNew = sqlite3DbRealloc(p->db, p->aOp, nNew*sizeof(Op));
61111   if( pNew ){
61112     p->nOpAlloc = sqlite3DbMallocSize(p->db, pNew)/sizeof(Op);
61113     p->aOp = pNew;
61114   }
61115   return (pNew ? SQLITE_OK : SQLITE_NOMEM);
61116 }
61117 
61118 #ifdef SQLITE_DEBUG
61119 /* This routine is just a convenient place to set a breakpoint that will
61120 ** fire after each opcode is inserted and displayed using
61121 ** "PRAGMA vdbe_addoptrace=on".
61122 */
61123 static void test_addop_breakpoint(void){
61124   static int n = 0;
61125   n++;
61126 }
61127 #endif
61128 
61129 /*
61130 ** Add a new instruction to the list of instructions current in the
61131 ** VDBE.  Return the address of the new instruction.
61132 **
61133 ** Parameters:
61134 **
61135 **    p               Pointer to the VDBE
61136 **
61137 **    op              The opcode for this instruction
61138 **
61139 **    p1, p2, p3      Operands
61140 **
61141 ** Use the sqlite3VdbeResolveLabel() function to fix an address and
61142 ** the sqlite3VdbeChangeP4() function to change the value of the P4
61143 ** operand.
61144 */
61145 SQLITE_PRIVATE int sqlite3VdbeAddOp3(Vdbe *p, int op, int p1, int p2, int p3){
61146   int i;
61147   VdbeOp *pOp;
61148 
61149   i = p->nOp;
61150   assert( p->magic==VDBE_MAGIC_INIT );
61151   assert( op>0 && op<0xff );
61152   if( p->nOpAlloc<=i ){
61153     if( growOpArray(p) ){
61154       return 1;
61155     }
61156   }
61157   p->nOp++;
61158   pOp = &p->aOp[i];
61159   pOp->opcode = (u8)op;
61160   pOp->p5 = 0;
61161   pOp->p1 = p1;
61162   pOp->p2 = p2;
61163   pOp->p3 = p3;
61164   pOp->p4.p = 0;
61165   pOp->p4type = P4_NOTUSED;
61166 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
61167   pOp->zComment = 0;
61168 #endif
61169 #ifdef SQLITE_DEBUG
61170   if( p->db->flags & SQLITE_VdbeAddopTrace ){
61171     sqlite3VdbePrintOp(0, i, &p->aOp[i]);
61172     test_addop_breakpoint();
61173   }
61174 #endif
61175 #ifdef VDBE_PROFILE
61176   pOp->cycles = 0;
61177   pOp->cnt = 0;
61178 #endif
61179   return i;
61180 }
61181 SQLITE_PRIVATE int sqlite3VdbeAddOp0(Vdbe *p, int op){
61182   return sqlite3VdbeAddOp3(p, op, 0, 0, 0);
61183 }
61184 SQLITE_PRIVATE int sqlite3VdbeAddOp1(Vdbe *p, int op, int p1){
61185   return sqlite3VdbeAddOp3(p, op, p1, 0, 0);
61186 }
61187 SQLITE_PRIVATE int sqlite3VdbeAddOp2(Vdbe *p, int op, int p1, int p2){
61188   return sqlite3VdbeAddOp3(p, op, p1, p2, 0);
61189 }
61190 
61191 
61192 /*
61193 ** Add an opcode that includes the p4 value as a pointer.
61194 */
61195 SQLITE_PRIVATE int sqlite3VdbeAddOp4(
61196   Vdbe *p,            /* Add the opcode to this VM */
61197   int op,             /* The new opcode */
61198   int p1,             /* The P1 operand */
61199   int p2,             /* The P2 operand */
61200   int p3,             /* The P3 operand */
61201   const char *zP4,    /* The P4 operand */
61202   int p4type          /* P4 operand type */
61203 ){
61204   int addr = sqlite3VdbeAddOp3(p, op, p1, p2, p3);
61205   sqlite3VdbeChangeP4(p, addr, zP4, p4type);
61206   return addr;
61207 }
61208 
61209 /*
61210 ** Add an OP_ParseSchema opcode.  This routine is broken out from
61211 ** sqlite3VdbeAddOp4() since it needs to also needs to mark all btrees
61212 ** as having been used.
61213 **
61214 ** The zWhere string must have been obtained from sqlite3_malloc().
61215 ** This routine will take ownership of the allocated memory.
61216 */
61217 SQLITE_PRIVATE void sqlite3VdbeAddParseSchemaOp(Vdbe *p, int iDb, char *zWhere){
61218   int j;
61219   int addr = sqlite3VdbeAddOp3(p, OP_ParseSchema, iDb, 0, 0);
61220   sqlite3VdbeChangeP4(p, addr, zWhere, P4_DYNAMIC);
61221   for(j=0; j<p->db->nDb; j++) sqlite3VdbeUsesBtree(p, j);
61222 }
61223 
61224 /*
61225 ** Add an opcode that includes the p4 value as an integer.
61226 */
61227 SQLITE_PRIVATE int sqlite3VdbeAddOp4Int(
61228   Vdbe *p,            /* Add the opcode to this VM */
61229   int op,             /* The new opcode */
61230   int p1,             /* The P1 operand */
61231   int p2,             /* The P2 operand */
61232   int p3,             /* The P3 operand */
61233   int p4              /* The P4 operand as an integer */
61234 ){
61235   int addr = sqlite3VdbeAddOp3(p, op, p1, p2, p3);
61236   sqlite3VdbeChangeP4(p, addr, SQLITE_INT_TO_PTR(p4), P4_INT32);
61237   return addr;
61238 }
61239 
61240 /*
61241 ** Create a new symbolic label for an instruction that has yet to be
61242 ** coded.  The symbolic label is really just a negative number.  The
61243 ** label can be used as the P2 value of an operation.  Later, when
61244 ** the label is resolved to a specific address, the VDBE will scan
61245 ** through its operation list and change all values of P2 which match
61246 ** the label into the resolved address.
61247 **
61248 ** The VDBE knows that a P2 value is a label because labels are
61249 ** always negative and P2 values are suppose to be non-negative.
61250 ** Hence, a negative P2 value is a label that has yet to be resolved.
61251 **
61252 ** Zero is returned if a malloc() fails.
61253 */
61254 SQLITE_PRIVATE int sqlite3VdbeMakeLabel(Vdbe *p){
61255   int i = p->nLabel++;
61256   assert( p->magic==VDBE_MAGIC_INIT );
61257   if( (i & (i-1))==0 ){
61258     p->aLabel = sqlite3DbReallocOrFree(p->db, p->aLabel, 
61259                                        (i*2+1)*sizeof(p->aLabel[0]));
61260   }
61261   if( p->aLabel ){
61262     p->aLabel[i] = -1;
61263   }
61264   return -1-i;
61265 }
61266 
61267 /*
61268 ** Resolve label "x" to be the address of the next instruction to
61269 ** be inserted.  The parameter "x" must have been obtained from
61270 ** a prior call to sqlite3VdbeMakeLabel().
61271 */
61272 SQLITE_PRIVATE void sqlite3VdbeResolveLabel(Vdbe *p, int x){
61273   int j = -1-x;
61274   assert( p->magic==VDBE_MAGIC_INIT );
61275   assert( j<p->nLabel );
61276   if( j>=0 && p->aLabel ){
61277     p->aLabel[j] = p->nOp;
61278   }
61279 }
61280 
61281 /*
61282 ** Mark the VDBE as one that can only be run one time.
61283 */
61284 SQLITE_PRIVATE void sqlite3VdbeRunOnlyOnce(Vdbe *p){
61285   p->runOnlyOnce = 1;
61286 }
61287 
61288 #ifdef SQLITE_DEBUG /* sqlite3AssertMayAbort() logic */
61289 
61290 /*
61291 ** The following type and function are used to iterate through all opcodes
61292 ** in a Vdbe main program and each of the sub-programs (triggers) it may 
61293 ** invoke directly or indirectly. It should be used as follows:
61294 **
61295 **   Op *pOp;
61296 **   VdbeOpIter sIter;
61297 **
61298 **   memset(&sIter, 0, sizeof(sIter));
61299 **   sIter.v = v;                            // v is of type Vdbe* 
61300 **   while( (pOp = opIterNext(&sIter)) ){
61301 **     // Do something with pOp
61302 **   }
61303 **   sqlite3DbFree(v->db, sIter.apSub);
61304 ** 
61305 */
61306 typedef struct VdbeOpIter VdbeOpIter;
61307 struct VdbeOpIter {
61308   Vdbe *v;                   /* Vdbe to iterate through the opcodes of */
61309   SubProgram **apSub;        /* Array of subprograms */
61310   int nSub;                  /* Number of entries in apSub */
61311   int iAddr;                 /* Address of next instruction to return */
61312   int iSub;                  /* 0 = main program, 1 = first sub-program etc. */
61313 };
61314 static Op *opIterNext(VdbeOpIter *p){
61315   Vdbe *v = p->v;
61316   Op *pRet = 0;
61317   Op *aOp;
61318   int nOp;
61319 
61320   if( p->iSub<=p->nSub ){
61321 
61322     if( p->iSub==0 ){
61323       aOp = v->aOp;
61324       nOp = v->nOp;
61325     }else{
61326       aOp = p->apSub[p->iSub-1]->aOp;
61327       nOp = p->apSub[p->iSub-1]->nOp;
61328     }
61329     assert( p->iAddr<nOp );
61330 
61331     pRet = &aOp[p->iAddr];
61332     p->iAddr++;
61333     if( p->iAddr==nOp ){
61334       p->iSub++;
61335       p->iAddr = 0;
61336     }
61337   
61338     if( pRet->p4type==P4_SUBPROGRAM ){
61339       int nByte = (p->nSub+1)*sizeof(SubProgram*);
61340       int j;
61341       for(j=0; j<p->nSub; j++){
61342         if( p->apSub[j]==pRet->p4.pProgram ) break;
61343       }
61344       if( j==p->nSub ){
61345         p->apSub = sqlite3DbReallocOrFree(v->db, p->apSub, nByte);
61346         if( !p->apSub ){
61347           pRet = 0;
61348         }else{
61349           p->apSub[p->nSub++] = pRet->p4.pProgram;
61350         }
61351       }
61352     }
61353   }
61354 
61355   return pRet;
61356 }
61357 
61358 /*
61359 ** Check if the program stored in the VM associated with pParse may
61360 ** throw an ABORT exception (causing the statement, but not entire transaction
61361 ** to be rolled back). This condition is true if the main program or any
61362 ** sub-programs contains any of the following:
61363 **
61364 **   *  OP_Halt with P1=SQLITE_CONSTRAINT and P2=OE_Abort.
61365 **   *  OP_HaltIfNull with P1=SQLITE_CONSTRAINT and P2=OE_Abort.
61366 **   *  OP_Destroy
61367 **   *  OP_VUpdate
61368 **   *  OP_VRename
61369 **   *  OP_FkCounter with P2==0 (immediate foreign key constraint)
61370 **
61371 ** Then check that the value of Parse.mayAbort is true if an
61372 ** ABORT may be thrown, or false otherwise. Return true if it does
61373 ** match, or false otherwise. This function is intended to be used as
61374 ** part of an assert statement in the compiler. Similar to:
61375 **
61376 **   assert( sqlite3VdbeAssertMayAbort(pParse->pVdbe, pParse->mayAbort) );
61377 */
61378 SQLITE_PRIVATE int sqlite3VdbeAssertMayAbort(Vdbe *v, int mayAbort){
61379   int hasAbort = 0;
61380   Op *pOp;
61381   VdbeOpIter sIter;
61382   memset(&sIter, 0, sizeof(sIter));
61383   sIter.v = v;
61384 
61385   while( (pOp = opIterNext(&sIter))!=0 ){
61386     int opcode = pOp->opcode;
61387     if( opcode==OP_Destroy || opcode==OP_VUpdate || opcode==OP_VRename 
61388 #ifndef SQLITE_OMIT_FOREIGN_KEY
61389      || (opcode==OP_FkCounter && pOp->p1==0 && pOp->p2==1) 
61390 #endif
61391      || ((opcode==OP_Halt || opcode==OP_HaltIfNull) 
61392       && ((pOp->p1&0xff)==SQLITE_CONSTRAINT && pOp->p2==OE_Abort))
61393     ){
61394       hasAbort = 1;
61395       break;
61396     }
61397   }
61398   sqlite3DbFree(v->db, sIter.apSub);
61399 
61400   /* Return true if hasAbort==mayAbort. Or if a malloc failure occurred.
61401   ** If malloc failed, then the while() loop above may not have iterated
61402   ** through all opcodes and hasAbort may be set incorrectly. Return
61403   ** true for this case to prevent the assert() in the callers frame
61404   ** from failing.  */
61405   return ( v->db->mallocFailed || hasAbort==mayAbort );
61406 }
61407 #endif /* SQLITE_DEBUG - the sqlite3AssertMayAbort() function */
61408 
61409 /*
61410 ** Loop through the program looking for P2 values that are negative
61411 ** on jump instructions.  Each such value is a label.  Resolve the
61412 ** label by setting the P2 value to its correct non-zero value.
61413 **
61414 ** This routine is called once after all opcodes have been inserted.
61415 **
61416 ** Variable *pMaxFuncArgs is set to the maximum value of any P2 argument 
61417 ** to an OP_Function, OP_AggStep or OP_VFilter opcode. This is used by 
61418 ** sqlite3VdbeMakeReady() to size the Vdbe.apArg[] array.
61419 **
61420 ** The Op.opflags field is set on all opcodes.
61421 */
61422 static void resolveP2Values(Vdbe *p, int *pMaxFuncArgs){
61423   int i;
61424   int nMaxArgs = *pMaxFuncArgs;
61425   Op *pOp;
61426   int *aLabel = p->aLabel;
61427   p->readOnly = 1;
61428   p->bIsReader = 0;
61429   for(pOp=p->aOp, i=p->nOp-1; i>=0; i--, pOp++){
61430     u8 opcode = pOp->opcode;
61431 
61432     /* NOTE: Be sure to update mkopcodeh.awk when adding or removing
61433     ** cases from this switch! */
61434     switch( opcode ){
61435       case OP_Function:
61436       case OP_AggStep: {
61437         if( pOp->p5>nMaxArgs ) nMaxArgs = pOp->p5;
61438         break;
61439       }
61440       case OP_Transaction: {
61441         if( pOp->p2!=0 ) p->readOnly = 0;
61442         /* fall thru */
61443       }
61444       case OP_AutoCommit:
61445       case OP_Savepoint: {
61446         p->bIsReader = 1;
61447         break;
61448       }
61449 #ifndef SQLITE_OMIT_WAL
61450       case OP_Checkpoint:
61451 #endif
61452       case OP_Vacuum:
61453       case OP_JournalMode: {
61454         p->readOnly = 0;
61455         p->bIsReader = 1;
61456         break;
61457       }
61458 #ifndef SQLITE_OMIT_VIRTUALTABLE
61459       case OP_VUpdate: {
61460         if( pOp->p2>nMaxArgs ) nMaxArgs = pOp->p2;
61461         break;
61462       }
61463       case OP_VFilter: {
61464         int n;
61465         assert( p->nOp - i >= 3 );
61466         assert( pOp[-1].opcode==OP_Integer );
61467         n = pOp[-1].p1;
61468         if( n>nMaxArgs ) nMaxArgs = n;
61469         break;
61470       }
61471 #endif
61472       case OP_Next:
61473       case OP_NextIfOpen:
61474       case OP_SorterNext: {
61475         pOp->p4.xAdvance = sqlite3BtreeNext;
61476         pOp->p4type = P4_ADVANCE;
61477         break;
61478       }
61479       case OP_Prev:
61480       case OP_PrevIfOpen: {
61481         pOp->p4.xAdvance = sqlite3BtreePrevious;
61482         pOp->p4type = P4_ADVANCE;
61483         break;
61484       }
61485     }
61486 
61487     pOp->opflags = sqlite3OpcodeProperty[opcode];
61488     if( (pOp->opflags & OPFLG_JUMP)!=0 && pOp->p2<0 ){
61489       assert( -1-pOp->p2<p->nLabel );
61490       pOp->p2 = aLabel[-1-pOp->p2];
61491     }
61492   }
61493   sqlite3DbFree(p->db, p->aLabel);
61494   p->aLabel = 0;
61495   *pMaxFuncArgs = nMaxArgs;
61496   assert( p->bIsReader!=0 || p->btreeMask==0 );
61497 }
61498 
61499 /*
61500 ** Return the address of the next instruction to be inserted.
61501 */
61502 SQLITE_PRIVATE int sqlite3VdbeCurrentAddr(Vdbe *p){
61503   assert( p->magic==VDBE_MAGIC_INIT );
61504   return p->nOp;
61505 }
61506 
61507 /*
61508 ** This function returns a pointer to the array of opcodes associated with
61509 ** the Vdbe passed as the first argument. It is the callers responsibility
61510 ** to arrange for the returned array to be eventually freed using the 
61511 ** vdbeFreeOpArray() function.
61512 **
61513 ** Before returning, *pnOp is set to the number of entries in the returned
61514 ** array. Also, *pnMaxArg is set to the larger of its current value and 
61515 ** the number of entries in the Vdbe.apArg[] array required to execute the 
61516 ** returned program.
61517 */
61518 SQLITE_PRIVATE VdbeOp *sqlite3VdbeTakeOpArray(Vdbe *p, int *pnOp, int *pnMaxArg){
61519   VdbeOp *aOp = p->aOp;
61520   assert( aOp && !p->db->mallocFailed );
61521 
61522   /* Check that sqlite3VdbeUsesBtree() was not called on this VM */
61523   assert( p->btreeMask==0 );
61524 
61525   resolveP2Values(p, pnMaxArg);
61526   *pnOp = p->nOp;
61527   p->aOp = 0;
61528   return aOp;
61529 }
61530 
61531 /*
61532 ** Add a whole list of operations to the operation stack.  Return the
61533 ** address of the first operation added.
61534 */
61535 SQLITE_PRIVATE int sqlite3VdbeAddOpList(Vdbe *p, int nOp, VdbeOpList const *aOp){
61536   int addr;
61537   assert( p->magic==VDBE_MAGIC_INIT );
61538   if( p->nOp + nOp > p->nOpAlloc && growOpArray(p) ){
61539     return 0;
61540   }
61541   addr = p->nOp;
61542   if( ALWAYS(nOp>0) ){
61543     int i;
61544     VdbeOpList const *pIn = aOp;
61545     for(i=0; i<nOp; i++, pIn++){
61546       int p2 = pIn->p2;
61547       VdbeOp *pOut = &p->aOp[i+addr];
61548       pOut->opcode = pIn->opcode;
61549       pOut->p1 = pIn->p1;
61550       if( p2<0 ){
61551         assert( sqlite3OpcodeProperty[pOut->opcode] & OPFLG_JUMP );
61552         pOut->p2 = addr + ADDR(p2);
61553       }else{
61554         pOut->p2 = p2;
61555       }
61556       pOut->p3 = pIn->p3;
61557       pOut->p4type = P4_NOTUSED;
61558       pOut->p4.p = 0;
61559       pOut->p5 = 0;
61560 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
61561       pOut->zComment = 0;
61562 #endif
61563 #ifdef SQLITE_DEBUG
61564       if( p->db->flags & SQLITE_VdbeAddopTrace ){
61565         sqlite3VdbePrintOp(0, i+addr, &p->aOp[i+addr]);
61566       }
61567 #endif
61568     }
61569     p->nOp += nOp;
61570   }
61571   return addr;
61572 }
61573 
61574 /*
61575 ** Change the value of the P1 operand for a specific instruction.
61576 ** This routine is useful when a large program is loaded from a
61577 ** static array using sqlite3VdbeAddOpList but we want to make a
61578 ** few minor changes to the program.
61579 */
61580 SQLITE_PRIVATE void sqlite3VdbeChangeP1(Vdbe *p, u32 addr, int val){
61581   assert( p!=0 );
61582   if( ((u32)p->nOp)>addr ){
61583     p->aOp[addr].p1 = val;
61584   }
61585 }
61586 
61587 /*
61588 ** Change the value of the P2 operand for a specific instruction.
61589 ** This routine is useful for setting a jump destination.
61590 */
61591 SQLITE_PRIVATE void sqlite3VdbeChangeP2(Vdbe *p, u32 addr, int val){
61592   assert( p!=0 );
61593   if( ((u32)p->nOp)>addr ){
61594     p->aOp[addr].p2 = val;
61595   }
61596 }
61597 
61598 /*
61599 ** Change the value of the P3 operand for a specific instruction.
61600 */
61601 SQLITE_PRIVATE void sqlite3VdbeChangeP3(Vdbe *p, u32 addr, int val){
61602   assert( p!=0 );
61603   if( ((u32)p->nOp)>addr ){
61604     p->aOp[addr].p3 = val;
61605   }
61606 }
61607 
61608 /*
61609 ** Change the value of the P5 operand for the most recently
61610 ** added operation.
61611 */
61612 SQLITE_PRIVATE void sqlite3VdbeChangeP5(Vdbe *p, u8 val){
61613   assert( p!=0 );
61614   if( p->aOp ){
61615     assert( p->nOp>0 );
61616     p->aOp[p->nOp-1].p5 = val;
61617   }
61618 }
61619 
61620 /*
61621 ** Change the P2 operand of instruction addr so that it points to
61622 ** the address of the next instruction to be coded.
61623 */
61624 SQLITE_PRIVATE void sqlite3VdbeJumpHere(Vdbe *p, int addr){
61625   if( ALWAYS(addr>=0) ) sqlite3VdbeChangeP2(p, addr, p->nOp);
61626 }
61627 
61628 
61629 /*
61630 ** If the input FuncDef structure is ephemeral, then free it.  If
61631 ** the FuncDef is not ephermal, then do nothing.
61632 */
61633 static void freeEphemeralFunction(sqlite3 *db, FuncDef *pDef){
61634   if( ALWAYS(pDef) && (pDef->funcFlags & SQLITE_FUNC_EPHEM)!=0 ){
61635     sqlite3DbFree(db, pDef);
61636   }
61637 }
61638 
61639 static void vdbeFreeOpArray(sqlite3 *, Op *, int);
61640 
61641 /*
61642 ** Delete a P4 value if necessary.
61643 */
61644 static void freeP4(sqlite3 *db, int p4type, void *p4){
61645   if( p4 ){
61646     assert( db );
61647     switch( p4type ){
61648       case P4_REAL:
61649       case P4_INT64:
61650       case P4_DYNAMIC:
61651       case P4_INTARRAY: {
61652         sqlite3DbFree(db, p4);
61653         break;
61654       }
61655       case P4_KEYINFO: {
61656         if( db->pnBytesFreed==0 ) sqlite3KeyInfoUnref((KeyInfo*)p4);
61657         break;
61658       }
61659       case P4_MPRINTF: {
61660         if( db->pnBytesFreed==0 ) sqlite3_free(p4);
61661         break;
61662       }
61663       case P4_FUNCDEF: {
61664         freeEphemeralFunction(db, (FuncDef*)p4);
61665         break;
61666       }
61667       case P4_MEM: {
61668         if( db->pnBytesFreed==0 ){
61669           sqlite3ValueFree((sqlite3_value*)p4);
61670         }else{
61671           Mem *p = (Mem*)p4;
61672           sqlite3DbFree(db, p->zMalloc);
61673           sqlite3DbFree(db, p);
61674         }
61675         break;
61676       }
61677       case P4_VTAB : {
61678         if( db->pnBytesFreed==0 ) sqlite3VtabUnlock((VTable *)p4);
61679         break;
61680       }
61681     }
61682   }
61683 }
61684 
61685 /*
61686 ** Free the space allocated for aOp and any p4 values allocated for the
61687 ** opcodes contained within. If aOp is not NULL it is assumed to contain 
61688 ** nOp entries. 
61689 */
61690 static void vdbeFreeOpArray(sqlite3 *db, Op *aOp, int nOp){
61691   if( aOp ){
61692     Op *pOp;
61693     for(pOp=aOp; pOp<&aOp[nOp]; pOp++){
61694       freeP4(db, pOp->p4type, pOp->p4.p);
61695 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
61696       sqlite3DbFree(db, pOp->zComment);
61697 #endif     
61698     }
61699   }
61700   sqlite3DbFree(db, aOp);
61701 }
61702 
61703 /*
61704 ** Link the SubProgram object passed as the second argument into the linked
61705 ** list at Vdbe.pSubProgram. This list is used to delete all sub-program
61706 ** objects when the VM is no longer required.
61707 */
61708 SQLITE_PRIVATE void sqlite3VdbeLinkSubProgram(Vdbe *pVdbe, SubProgram *p){
61709   p->pNext = pVdbe->pProgram;
61710   pVdbe->pProgram = p;
61711 }
61712 
61713 /*
61714 ** Change the opcode at addr into OP_Noop
61715 */
61716 SQLITE_PRIVATE void sqlite3VdbeChangeToNoop(Vdbe *p, int addr){
61717   if( p->aOp ){
61718     VdbeOp *pOp = &p->aOp[addr];
61719     sqlite3 *db = p->db;
61720     freeP4(db, pOp->p4type, pOp->p4.p);
61721     memset(pOp, 0, sizeof(pOp[0]));
61722     pOp->opcode = OP_Noop;
61723     if( addr==p->nOp-1 ) p->nOp--;
61724   }
61725 }
61726 
61727 /*
61728 ** Change the value of the P4 operand for a specific instruction.
61729 ** This routine is useful when a large program is loaded from a
61730 ** static array using sqlite3VdbeAddOpList but we want to make a
61731 ** few minor changes to the program.
61732 **
61733 ** If n>=0 then the P4 operand is dynamic, meaning that a copy of
61734 ** the string is made into memory obtained from sqlite3_malloc().
61735 ** A value of n==0 means copy bytes of zP4 up to and including the
61736 ** first null byte.  If n>0 then copy n+1 bytes of zP4.
61737 ** 
61738 ** Other values of n (P4_STATIC, P4_COLLSEQ etc.) indicate that zP4 points
61739 ** to a string or structure that is guaranteed to exist for the lifetime of
61740 ** the Vdbe. In these cases we can just copy the pointer.
61741 **
61742 ** If addr<0 then change P4 on the most recently inserted instruction.
61743 */
61744 SQLITE_PRIVATE void sqlite3VdbeChangeP4(Vdbe *p, int addr, const char *zP4, int n){
61745   Op *pOp;
61746   sqlite3 *db;
61747   assert( p!=0 );
61748   db = p->db;
61749   assert( p->magic==VDBE_MAGIC_INIT );
61750   if( p->aOp==0 || db->mallocFailed ){
61751     if( n!=P4_VTAB ){
61752       freeP4(db, n, (void*)*(char**)&zP4);
61753     }
61754     return;
61755   }
61756   assert( p->nOp>0 );
61757   assert( addr<p->nOp );
61758   if( addr<0 ){
61759     addr = p->nOp - 1;
61760   }
61761   pOp = &p->aOp[addr];
61762   assert( pOp->p4type==P4_NOTUSED || pOp->p4type==P4_INT32 );
61763   freeP4(db, pOp->p4type, pOp->p4.p);
61764   pOp->p4.p = 0;
61765   if( n==P4_INT32 ){
61766     /* Note: this cast is safe, because the origin data point was an int
61767     ** that was cast to a (const char *). */
61768     pOp->p4.i = SQLITE_PTR_TO_INT(zP4);
61769     pOp->p4type = P4_INT32;
61770   }else if( zP4==0 ){
61771     pOp->p4.p = 0;
61772     pOp->p4type = P4_NOTUSED;
61773   }else if( n==P4_KEYINFO ){
61774     pOp->p4.p = (void*)zP4;
61775     pOp->p4type = P4_KEYINFO;
61776   }else if( n==P4_VTAB ){
61777     pOp->p4.p = (void*)zP4;
61778     pOp->p4type = P4_VTAB;
61779     sqlite3VtabLock((VTable *)zP4);
61780     assert( ((VTable *)zP4)->db==p->db );
61781   }else if( n<0 ){
61782     pOp->p4.p = (void*)zP4;
61783     pOp->p4type = (signed char)n;
61784   }else{
61785     if( n==0 ) n = sqlite3Strlen30(zP4);
61786     pOp->p4.z = sqlite3DbStrNDup(p->db, zP4, n);
61787     pOp->p4type = P4_DYNAMIC;
61788   }
61789 }
61790 
61791 /*
61792 ** Set the P4 on the most recently added opcode to the KeyInfo for the
61793 ** index given.
61794 */
61795 SQLITE_PRIVATE void sqlite3VdbeSetP4KeyInfo(Parse *pParse, Index *pIdx){
61796   Vdbe *v = pParse->pVdbe;
61797   assert( v!=0 );
61798   assert( pIdx!=0 );
61799   sqlite3VdbeChangeP4(v, -1, (char*)sqlite3KeyInfoOfIndex(pParse, pIdx),
61800                       P4_KEYINFO);
61801 }
61802 
61803 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
61804 /*
61805 ** Change the comment on the most recently coded instruction.  Or
61806 ** insert a No-op and add the comment to that new instruction.  This
61807 ** makes the code easier to read during debugging.  None of this happens
61808 ** in a production build.
61809 */
61810 static void vdbeVComment(Vdbe *p, const char *zFormat, va_list ap){
61811   assert( p->nOp>0 || p->aOp==0 );
61812   assert( p->aOp==0 || p->aOp[p->nOp-1].zComment==0 || p->db->mallocFailed );
61813   if( p->nOp ){
61814     assert( p->aOp );
61815     sqlite3DbFree(p->db, p->aOp[p->nOp-1].zComment);
61816     p->aOp[p->nOp-1].zComment = sqlite3VMPrintf(p->db, zFormat, ap);
61817   }
61818 }
61819 SQLITE_PRIVATE void sqlite3VdbeComment(Vdbe *p, const char *zFormat, ...){
61820   va_list ap;
61821   if( p ){
61822     va_start(ap, zFormat);
61823     vdbeVComment(p, zFormat, ap);
61824     va_end(ap);
61825   }
61826 }
61827 SQLITE_PRIVATE void sqlite3VdbeNoopComment(Vdbe *p, const char *zFormat, ...){
61828   va_list ap;
61829   if( p ){
61830     sqlite3VdbeAddOp0(p, OP_Noop);
61831     va_start(ap, zFormat);
61832     vdbeVComment(p, zFormat, ap);
61833     va_end(ap);
61834   }
61835 }
61836 #endif  /* NDEBUG */
61837 
61838 /*
61839 ** Return the opcode for a given address.  If the address is -1, then
61840 ** return the most recently inserted opcode.
61841 **
61842 ** If a memory allocation error has occurred prior to the calling of this
61843 ** routine, then a pointer to a dummy VdbeOp will be returned.  That opcode
61844 ** is readable but not writable, though it is cast to a writable value.
61845 ** The return of a dummy opcode allows the call to continue functioning
61846 ** after a OOM fault without having to check to see if the return from 
61847 ** this routine is a valid pointer.  But because the dummy.opcode is 0,
61848 ** dummy will never be written to.  This is verified by code inspection and
61849 ** by running with Valgrind.
61850 **
61851 ** About the #ifdef SQLITE_OMIT_TRACE:  Normally, this routine is never called
61852 ** unless p->nOp>0.  This is because in the absense of SQLITE_OMIT_TRACE,
61853 ** an OP_Trace instruction is always inserted by sqlite3VdbeGet() as soon as
61854 ** a new VDBE is created.  So we are free to set addr to p->nOp-1 without
61855 ** having to double-check to make sure that the result is non-negative. But
61856 ** if SQLITE_OMIT_TRACE is defined, the OP_Trace is omitted and we do need to
61857 ** check the value of p->nOp-1 before continuing.
61858 */
61859 SQLITE_PRIVATE VdbeOp *sqlite3VdbeGetOp(Vdbe *p, int addr){
61860   /* C89 specifies that the constant "dummy" will be initialized to all
61861   ** zeros, which is correct.  MSVC generates a warning, nevertheless. */
61862   static VdbeOp dummy;  /* Ignore the MSVC warning about no initializer */
61863   assert( p->magic==VDBE_MAGIC_INIT );
61864   if( addr<0 ){
61865 #ifdef SQLITE_OMIT_TRACE
61866     if( p->nOp==0 ) return (VdbeOp*)&dummy;
61867 #endif
61868     addr = p->nOp - 1;
61869   }
61870   assert( (addr>=0 && addr<p->nOp) || p->db->mallocFailed );
61871   if( p->db->mallocFailed ){
61872     return (VdbeOp*)&dummy;
61873   }else{
61874     return &p->aOp[addr];
61875   }
61876 }
61877 
61878 #if defined(SQLITE_ENABLE_EXPLAIN_COMMENTS)
61879 /*
61880 ** Return an integer value for one of the parameters to the opcode pOp
61881 ** determined by character c.
61882 */
61883 static int translateP(char c, const Op *pOp){
61884   if( c=='1' ) return pOp->p1;
61885   if( c=='2' ) return pOp->p2;
61886   if( c=='3' ) return pOp->p3;
61887   if( c=='4' ) return pOp->p4.i;
61888   return pOp->p5;
61889 }
61890 
61891 /*
61892 ** Compute a string for the "comment" field of a VDBE opcode listing
61893 */
61894 static int displayComment(
61895   const Op *pOp,     /* The opcode to be commented */
61896   const char *zP4,   /* Previously obtained value for P4 */
61897   char *zTemp,       /* Write result here */
61898   int nTemp          /* Space available in zTemp[] */
61899 ){
61900   const char *zOpName;
61901   const char *zSynopsis;
61902   int nOpName;
61903   int ii, jj;
61904   zOpName = sqlite3OpcodeName(pOp->opcode);
61905   nOpName = sqlite3Strlen30(zOpName);
61906   if( zOpName[nOpName+1] ){
61907     int seenCom = 0;
61908     char c;
61909     zSynopsis = zOpName += nOpName + 1;
61910     for(ii=jj=0; jj<nTemp-1 && (c = zSynopsis[ii])!=0; ii++){
61911       if( c=='P' ){
61912         c = zSynopsis[++ii];
61913         if( c=='4' ){
61914           sqlite3_snprintf(nTemp-jj, zTemp+jj, "%s", zP4);
61915         }else if( c=='X' ){
61916           sqlite3_snprintf(nTemp-jj, zTemp+jj, "%s", pOp->zComment);
61917           seenCom = 1;
61918         }else{
61919           int v1 = translateP(c, pOp);
61920           int v2;
61921           sqlite3_snprintf(nTemp-jj, zTemp+jj, "%d", v1);
61922           if( strncmp(zSynopsis+ii+1, "@P", 2)==0 ){
61923             ii += 3;
61924             jj += sqlite3Strlen30(zTemp+jj);
61925             v2 = translateP(zSynopsis[ii], pOp);
61926             if( v2>1 ) sqlite3_snprintf(nTemp-jj, zTemp+jj, "..%d", v1+v2-1);
61927           }else if( strncmp(zSynopsis+ii+1, "..P3", 4)==0 && pOp->p3==0 ){
61928             ii += 4;
61929           }
61930         }
61931         jj += sqlite3Strlen30(zTemp+jj);
61932       }else{
61933         zTemp[jj++] = c;
61934       }
61935     }
61936     if( !seenCom && jj<nTemp-5 && pOp->zComment ){
61937       sqlite3_snprintf(nTemp-jj, zTemp+jj, "; %s", pOp->zComment);
61938       jj += sqlite3Strlen30(zTemp+jj);
61939     }
61940     if( jj<nTemp ) zTemp[jj] = 0;
61941   }else if( pOp->zComment ){
61942     sqlite3_snprintf(nTemp, zTemp, "%s", pOp->zComment);
61943     jj = sqlite3Strlen30(zTemp);
61944   }else{
61945     zTemp[0] = 0;
61946     jj = 0;
61947   }
61948   return jj;
61949 }
61950 #endif /* SQLITE_DEBUG */
61951 
61952 
61953 #if !defined(SQLITE_OMIT_EXPLAIN) || !defined(NDEBUG) \
61954      || defined(VDBE_PROFILE) || defined(SQLITE_DEBUG)
61955 /*
61956 ** Compute a string that describes the P4 parameter for an opcode.
61957 ** Use zTemp for any required temporary buffer space.
61958 */
61959 static char *displayP4(Op *pOp, char *zTemp, int nTemp){
61960   char *zP4 = zTemp;
61961   assert( nTemp>=20 );
61962   switch( pOp->p4type ){
61963     case P4_KEYINFO: {
61964       int i, j;
61965       KeyInfo *pKeyInfo = pOp->p4.pKeyInfo;
61966       assert( pKeyInfo->aSortOrder!=0 );
61967       sqlite3_snprintf(nTemp, zTemp, "k(%d", pKeyInfo->nField);
61968       i = sqlite3Strlen30(zTemp);
61969       for(j=0; j<pKeyInfo->nField; j++){
61970         CollSeq *pColl = pKeyInfo->aColl[j];
61971         const char *zColl = pColl ? pColl->zName : "nil";
61972         int n = sqlite3Strlen30(zColl);
61973         if( n==6 && memcmp(zColl,"BINARY",6)==0 ){
61974           zColl = "B";
61975           n = 1;
61976         }
61977         if( i+n>nTemp-6 ){
61978           memcpy(&zTemp[i],",...",4);
61979           break;
61980         }
61981         zTemp[i++] = ',';
61982         if( pKeyInfo->aSortOrder[j] ){
61983           zTemp[i++] = '-';
61984         }
61985         memcpy(&zTemp[i], zColl, n+1);
61986         i += n;
61987       }
61988       zTemp[i++] = ')';
61989       zTemp[i] = 0;
61990       assert( i<nTemp );
61991       break;
61992     }
61993     case P4_COLLSEQ: {
61994       CollSeq *pColl = pOp->p4.pColl;
61995       sqlite3_snprintf(nTemp, zTemp, "(%.20s)", pColl->zName);
61996       break;
61997     }
61998     case P4_FUNCDEF: {
61999       FuncDef *pDef = pOp->p4.pFunc;
62000       sqlite3_snprintf(nTemp, zTemp, "%s(%d)", pDef->zName, pDef->nArg);
62001       break;
62002     }
62003     case P4_INT64: {
62004       sqlite3_snprintf(nTemp, zTemp, "%lld", *pOp->p4.pI64);
62005       break;
62006     }
62007     case P4_INT32: {
62008       sqlite3_snprintf(nTemp, zTemp, "%d", pOp->p4.i);
62009       break;
62010     }
62011     case P4_REAL: {
62012       sqlite3_snprintf(nTemp, zTemp, "%.16g", *pOp->p4.pReal);
62013       break;
62014     }
62015     case P4_MEM: {
62016       Mem *pMem = pOp->p4.pMem;
62017       if( pMem->flags & MEM_Str ){
62018         zP4 = pMem->z;
62019       }else if( pMem->flags & MEM_Int ){
62020         sqlite3_snprintf(nTemp, zTemp, "%lld", pMem->u.i);
62021       }else if( pMem->flags & MEM_Real ){
62022         sqlite3_snprintf(nTemp, zTemp, "%.16g", pMem->r);
62023       }else if( pMem->flags & MEM_Null ){
62024         sqlite3_snprintf(nTemp, zTemp, "NULL");
62025       }else{
62026         assert( pMem->flags & MEM_Blob );
62027         zP4 = "(blob)";
62028       }
62029       break;
62030     }
62031 #ifndef SQLITE_OMIT_VIRTUALTABLE
62032     case P4_VTAB: {
62033       sqlite3_vtab *pVtab = pOp->p4.pVtab->pVtab;
62034       sqlite3_snprintf(nTemp, zTemp, "vtab:%p:%p", pVtab, pVtab->pModule);
62035       break;
62036     }
62037 #endif
62038     case P4_INTARRAY: {
62039       sqlite3_snprintf(nTemp, zTemp, "intarray");
62040       break;
62041     }
62042     case P4_SUBPROGRAM: {
62043       sqlite3_snprintf(nTemp, zTemp, "program");
62044       break;
62045     }
62046     case P4_ADVANCE: {
62047       zTemp[0] = 0;
62048       break;
62049     }
62050     default: {
62051       zP4 = pOp->p4.z;
62052       if( zP4==0 ){
62053         zP4 = zTemp;
62054         zTemp[0] = 0;
62055       }
62056     }
62057   }
62058   assert( zP4!=0 );
62059   return zP4;
62060 }
62061 #endif
62062 
62063 /*
62064 ** Declare to the Vdbe that the BTree object at db->aDb[i] is used.
62065 **
62066 ** The prepared statements need to know in advance the complete set of
62067 ** attached databases that will be use.  A mask of these databases
62068 ** is maintained in p->btreeMask.  The p->lockMask value is the subset of
62069 ** p->btreeMask of databases that will require a lock.
62070 */
62071 SQLITE_PRIVATE void sqlite3VdbeUsesBtree(Vdbe *p, int i){
62072   assert( i>=0 && i<p->db->nDb && i<(int)sizeof(yDbMask)*8 );
62073   assert( i<(int)sizeof(p->btreeMask)*8 );
62074   p->btreeMask |= ((yDbMask)1)<<i;
62075   if( i!=1 && sqlite3BtreeSharable(p->db->aDb[i].pBt) ){
62076     p->lockMask |= ((yDbMask)1)<<i;
62077   }
62078 }
62079 
62080 #if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE>0
62081 /*
62082 ** If SQLite is compiled to support shared-cache mode and to be threadsafe,
62083 ** this routine obtains the mutex associated with each BtShared structure
62084 ** that may be accessed by the VM passed as an argument. In doing so it also
62085 ** sets the BtShared.db member of each of the BtShared structures, ensuring
62086 ** that the correct busy-handler callback is invoked if required.
62087 **
62088 ** If SQLite is not threadsafe but does support shared-cache mode, then
62089 ** sqlite3BtreeEnter() is invoked to set the BtShared.db variables
62090 ** of all of BtShared structures accessible via the database handle 
62091 ** associated with the VM.
62092 **
62093 ** If SQLite is not threadsafe and does not support shared-cache mode, this
62094 ** function is a no-op.
62095 **
62096 ** The p->btreeMask field is a bitmask of all btrees that the prepared 
62097 ** statement p will ever use.  Let N be the number of bits in p->btreeMask
62098 ** corresponding to btrees that use shared cache.  Then the runtime of
62099 ** this routine is N*N.  But as N is rarely more than 1, this should not
62100 ** be a problem.
62101 */
62102 SQLITE_PRIVATE void sqlite3VdbeEnter(Vdbe *p){
62103   int i;
62104   yDbMask mask;
62105   sqlite3 *db;
62106   Db *aDb;
62107   int nDb;
62108   if( p->lockMask==0 ) return;  /* The common case */
62109   db = p->db;
62110   aDb = db->aDb;
62111   nDb = db->nDb;
62112   for(i=0, mask=1; i<nDb; i++, mask += mask){
62113     if( i!=1 && (mask & p->lockMask)!=0 && ALWAYS(aDb[i].pBt!=0) ){
62114       sqlite3BtreeEnter(aDb[i].pBt);
62115     }
62116   }
62117 }
62118 #endif
62119 
62120 #if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE>0
62121 /*
62122 ** Unlock all of the btrees previously locked by a call to sqlite3VdbeEnter().
62123 */
62124 SQLITE_PRIVATE void sqlite3VdbeLeave(Vdbe *p){
62125   int i;
62126   yDbMask mask;
62127   sqlite3 *db;
62128   Db *aDb;
62129   int nDb;
62130   if( p->lockMask==0 ) return;  /* The common case */
62131   db = p->db;
62132   aDb = db->aDb;
62133   nDb = db->nDb;
62134   for(i=0, mask=1; i<nDb; i++, mask += mask){
62135     if( i!=1 && (mask & p->lockMask)!=0 && ALWAYS(aDb[i].pBt!=0) ){
62136       sqlite3BtreeLeave(aDb[i].pBt);
62137     }
62138   }
62139 }
62140 #endif
62141 
62142 #if defined(VDBE_PROFILE) || defined(SQLITE_DEBUG)
62143 /*
62144 ** Print a single opcode.  This routine is used for debugging only.
62145 */
62146 SQLITE_PRIVATE void sqlite3VdbePrintOp(FILE *pOut, int pc, Op *pOp){
62147   char *zP4;
62148   char zPtr[50];
62149   char zCom[100];
62150   static const char *zFormat1 = "%4d %-13s %4d %4d %4d %-13s %.2X %s\n";
62151   if( pOut==0 ) pOut = stdout;
62152   zP4 = displayP4(pOp, zPtr, sizeof(zPtr));
62153 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
62154   displayComment(pOp, zP4, zCom, sizeof(zCom));
62155 #else
62156   zCom[0] = 0
62157 #endif
62158   fprintf(pOut, zFormat1, pc, 
62159       sqlite3OpcodeName(pOp->opcode), pOp->p1, pOp->p2, pOp->p3, zP4, pOp->p5,
62160       zCom
62161   );
62162   fflush(pOut);
62163 }
62164 #endif
62165 
62166 /*
62167 ** Release an array of N Mem elements
62168 */
62169 static void releaseMemArray(Mem *p, int N){
62170   if( p && N ){
62171     Mem *pEnd;
62172     sqlite3 *db = p->db;
62173     u8 malloc_failed = db->mallocFailed;
62174     if( db->pnBytesFreed ){
62175       for(pEnd=&p[N]; p<pEnd; p++){
62176         sqlite3DbFree(db, p->zMalloc);
62177       }
62178       return;
62179     }
62180     for(pEnd=&p[N]; p<pEnd; p++){
62181       assert( (&p[1])==pEnd || p[0].db==p[1].db );
62182 
62183       /* This block is really an inlined version of sqlite3VdbeMemRelease()
62184       ** that takes advantage of the fact that the memory cell value is 
62185       ** being set to NULL after releasing any dynamic resources.
62186       **
62187       ** The justification for duplicating code is that according to 
62188       ** callgrind, this causes a certain test case to hit the CPU 4.7 
62189       ** percent less (x86 linux, gcc version 4.1.2, -O6) than if 
62190       ** sqlite3MemRelease() were called from here. With -O2, this jumps
62191       ** to 6.6 percent. The test case is inserting 1000 rows into a table 
62192       ** with no indexes using a single prepared INSERT statement, bind() 
62193       ** and reset(). Inserts are grouped into a transaction.
62194       */
62195       if( p->flags&(MEM_Agg|MEM_Dyn|MEM_Frame|MEM_RowSet) ){
62196         sqlite3VdbeMemRelease(p);
62197       }else if( p->zMalloc ){
62198         sqlite3DbFree(db, p->zMalloc);
62199         p->zMalloc = 0;
62200       }
62201 
62202       p->flags = MEM_Invalid;
62203     }
62204     db->mallocFailed = malloc_failed;
62205   }
62206 }
62207 
62208 /*
62209 ** Delete a VdbeFrame object and its contents. VdbeFrame objects are
62210 ** allocated by the OP_Program opcode in sqlite3VdbeExec().
62211 */
62212 SQLITE_PRIVATE void sqlite3VdbeFrameDelete(VdbeFrame *p){
62213   int i;
62214   Mem *aMem = VdbeFrameMem(p);
62215   VdbeCursor **apCsr = (VdbeCursor **)&aMem[p->nChildMem];
62216   for(i=0; i<p->nChildCsr; i++){
62217     sqlite3VdbeFreeCursor(p->v, apCsr[i]);
62218   }
62219   releaseMemArray(aMem, p->nChildMem);
62220   sqlite3DbFree(p->v->db, p);
62221 }
62222 
62223 #ifndef SQLITE_OMIT_EXPLAIN
62224 /*
62225 ** Give a listing of the program in the virtual machine.
62226 **
62227 ** The interface is the same as sqlite3VdbeExec().  But instead of
62228 ** running the code, it invokes the callback once for each instruction.
62229 ** This feature is used to implement "EXPLAIN".
62230 **
62231 ** When p->explain==1, each instruction is listed.  When
62232 ** p->explain==2, only OP_Explain instructions are listed and these
62233 ** are shown in a different format.  p->explain==2 is used to implement
62234 ** EXPLAIN QUERY PLAN.
62235 **
62236 ** When p->explain==1, first the main program is listed, then each of
62237 ** the trigger subprograms are listed one by one.
62238 */
62239 SQLITE_PRIVATE int sqlite3VdbeList(
62240   Vdbe *p                   /* The VDBE */
62241 ){
62242   int nRow;                            /* Stop when row count reaches this */
62243   int nSub = 0;                        /* Number of sub-vdbes seen so far */
62244   SubProgram **apSub = 0;              /* Array of sub-vdbes */
62245   Mem *pSub = 0;                       /* Memory cell hold array of subprogs */
62246   sqlite3 *db = p->db;                 /* The database connection */
62247   int i;                               /* Loop counter */
62248   int rc = SQLITE_OK;                  /* Return code */
62249   Mem *pMem = &p->aMem[1];             /* First Mem of result set */
62250 
62251   assert( p->explain );
62252   assert( p->magic==VDBE_MAGIC_RUN );
62253   assert( p->rc==SQLITE_OK || p->rc==SQLITE_BUSY || p->rc==SQLITE_NOMEM );
62254 
62255   /* Even though this opcode does not use dynamic strings for
62256   ** the result, result columns may become dynamic if the user calls
62257   ** sqlite3_column_text16(), causing a translation to UTF-16 encoding.
62258   */
62259   releaseMemArray(pMem, 8);
62260   p->pResultSet = 0;
62261 
62262   if( p->rc==SQLITE_NOMEM ){
62263     /* This happens if a malloc() inside a call to sqlite3_column_text() or
62264     ** sqlite3_column_text16() failed.  */
62265     db->mallocFailed = 1;
62266     return SQLITE_ERROR;
62267   }
62268 
62269   /* When the number of output rows reaches nRow, that means the
62270   ** listing has finished and sqlite3_step() should return SQLITE_DONE.
62271   ** nRow is the sum of the number of rows in the main program, plus
62272   ** the sum of the number of rows in all trigger subprograms encountered
62273   ** so far.  The nRow value will increase as new trigger subprograms are
62274   ** encountered, but p->pc will eventually catch up to nRow.
62275   */
62276   nRow = p->nOp;
62277   if( p->explain==1 ){
62278     /* The first 8 memory cells are used for the result set.  So we will
62279     ** commandeer the 9th cell to use as storage for an array of pointers
62280     ** to trigger subprograms.  The VDBE is guaranteed to have at least 9
62281     ** cells.  */
62282     assert( p->nMem>9 );
62283     pSub = &p->aMem[9];
62284     if( pSub->flags&MEM_Blob ){
62285       /* On the first call to sqlite3_step(), pSub will hold a NULL.  It is
62286       ** initialized to a BLOB by the P4_SUBPROGRAM processing logic below */
62287       nSub = pSub->n/sizeof(Vdbe*);
62288       apSub = (SubProgram **)pSub->z;
62289     }
62290     for(i=0; i<nSub; i++){
62291       nRow += apSub[i]->nOp;
62292     }
62293   }
62294 
62295   do{
62296     i = p->pc++;
62297   }while( i<nRow && p->explain==2 && p->aOp[i].opcode!=OP_Explain );
62298   if( i>=nRow ){
62299     p->rc = SQLITE_OK;
62300     rc = SQLITE_DONE;
62301   }else if( db->u1.isInterrupted ){
62302     p->rc = SQLITE_INTERRUPT;
62303     rc = SQLITE_ERROR;
62304     sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3ErrStr(p->rc));
62305   }else{
62306     char *zP4;
62307     Op *pOp;
62308     if( i<p->nOp ){
62309       /* The output line number is small enough that we are still in the
62310       ** main program. */
62311       pOp = &p->aOp[i];
62312     }else{
62313       /* We are currently listing subprograms.  Figure out which one and
62314       ** pick up the appropriate opcode. */
62315       int j;
62316       i -= p->nOp;
62317       for(j=0; i>=apSub[j]->nOp; j++){
62318         i -= apSub[j]->nOp;
62319       }
62320       pOp = &apSub[j]->aOp[i];
62321     }
62322     if( p->explain==1 ){
62323       pMem->flags = MEM_Int;
62324       pMem->type = SQLITE_INTEGER;
62325       pMem->u.i = i;                                /* Program counter */
62326       pMem++;
62327   
62328       pMem->flags = MEM_Static|MEM_Str|MEM_Term;
62329       pMem->z = (char*)sqlite3OpcodeName(pOp->opcode); /* Opcode */
62330       assert( pMem->z!=0 );
62331       pMem->n = sqlite3Strlen30(pMem->z);
62332       pMem->type = SQLITE_TEXT;
62333       pMem->enc = SQLITE_UTF8;
62334       pMem++;
62335 
62336       /* When an OP_Program opcode is encounter (the only opcode that has
62337       ** a P4_SUBPROGRAM argument), expand the size of the array of subprograms
62338       ** kept in p->aMem[9].z to hold the new program - assuming this subprogram
62339       ** has not already been seen.
62340       */
62341       if( pOp->p4type==P4_SUBPROGRAM ){
62342         int nByte = (nSub+1)*sizeof(SubProgram*);
62343         int j;
62344         for(j=0; j<nSub; j++){
62345           if( apSub[j]==pOp->p4.pProgram ) break;
62346         }
62347         if( j==nSub && SQLITE_OK==sqlite3VdbeMemGrow(pSub, nByte, nSub!=0) ){
62348           apSub = (SubProgram **)pSub->z;
62349           apSub[nSub++] = pOp->p4.pProgram;
62350           pSub->flags |= MEM_Blob;
62351           pSub->n = nSub*sizeof(SubProgram*);
62352         }
62353       }
62354     }
62355 
62356     pMem->flags = MEM_Int;
62357     pMem->u.i = pOp->p1;                          /* P1 */
62358     pMem->type = SQLITE_INTEGER;
62359     pMem++;
62360 
62361     pMem->flags = MEM_Int;
62362     pMem->u.i = pOp->p2;                          /* P2 */
62363     pMem->type = SQLITE_INTEGER;
62364     pMem++;
62365 
62366     pMem->flags = MEM_Int;
62367     pMem->u.i = pOp->p3;                          /* P3 */
62368     pMem->type = SQLITE_INTEGER;
62369     pMem++;
62370 
62371     if( sqlite3VdbeMemGrow(pMem, 32, 0) ){            /* P4 */
62372       assert( p->db->mallocFailed );
62373       return SQLITE_ERROR;
62374     }
62375     pMem->flags = MEM_Dyn|MEM_Str|MEM_Term;
62376     zP4 = displayP4(pOp, pMem->z, 32);
62377     if( zP4!=pMem->z ){
62378       sqlite3VdbeMemSetStr(pMem, zP4, -1, SQLITE_UTF8, 0);
62379     }else{
62380       assert( pMem->z!=0 );
62381       pMem->n = sqlite3Strlen30(pMem->z);
62382       pMem->enc = SQLITE_UTF8;
62383     }
62384     pMem->type = SQLITE_TEXT;
62385     pMem++;
62386 
62387     if( p->explain==1 ){
62388       if( sqlite3VdbeMemGrow(pMem, 4, 0) ){
62389         assert( p->db->mallocFailed );
62390         return SQLITE_ERROR;
62391       }
62392       pMem->flags = MEM_Dyn|MEM_Str|MEM_Term;
62393       pMem->n = 2;
62394       sqlite3_snprintf(3, pMem->z, "%.2x", pOp->p5);   /* P5 */
62395       pMem->type = SQLITE_TEXT;
62396       pMem->enc = SQLITE_UTF8;
62397       pMem++;
62398   
62399 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
62400       if( sqlite3VdbeMemGrow(pMem, 500, 0) ){
62401         assert( p->db->mallocFailed );
62402         return SQLITE_ERROR;
62403       }
62404       pMem->flags = MEM_Dyn|MEM_Str|MEM_Term;
62405       pMem->n = displayComment(pOp, zP4, pMem->z, 500);
62406       pMem->type = SQLITE_TEXT;
62407       pMem->enc = SQLITE_UTF8;
62408 #else
62409       pMem->flags = MEM_Null;                       /* Comment */
62410       pMem->type = SQLITE_NULL;
62411 #endif
62412     }
62413 
62414     p->nResColumn = 8 - 4*(p->explain-1);
62415     p->pResultSet = &p->aMem[1];
62416     p->rc = SQLITE_OK;
62417     rc = SQLITE_ROW;
62418   }
62419   return rc;
62420 }
62421 #endif /* SQLITE_OMIT_EXPLAIN */
62422 
62423 #ifdef SQLITE_DEBUG
62424 /*
62425 ** Print the SQL that was used to generate a VDBE program.
62426 */
62427 SQLITE_PRIVATE void sqlite3VdbePrintSql(Vdbe *p){
62428   const char *z = 0;
62429   if( p->zSql ){
62430     z = p->zSql;
62431   }else if( p->nOp>=1 ){
62432     const VdbeOp *pOp = &p->aOp[0];
62433     if( pOp->opcode==OP_Trace && pOp->p4.z!=0 ){
62434       z = pOp->p4.z;
62435       while( sqlite3Isspace(*z) ) z++;
62436     }
62437   }
62438   if( z ) printf("SQL: [%s]\n", z);
62439 }
62440 #endif
62441 
62442 #if !defined(SQLITE_OMIT_TRACE) && defined(SQLITE_ENABLE_IOTRACE)
62443 /*
62444 ** Print an IOTRACE message showing SQL content.
62445 */
62446 SQLITE_PRIVATE void sqlite3VdbeIOTraceSql(Vdbe *p){
62447   int nOp = p->nOp;
62448   VdbeOp *pOp;
62449   if( sqlite3IoTrace==0 ) return;
62450   if( nOp<1 ) return;
62451   pOp = &p->aOp[0];
62452   if( pOp->opcode==OP_Trace && pOp->p4.z!=0 ){
62453     int i, j;
62454     char z[1000];
62455     sqlite3_snprintf(sizeof(z), z, "%s", pOp->p4.z);
62456     for(i=0; sqlite3Isspace(z[i]); i++){}
62457     for(j=0; z[i]; i++){
62458       if( sqlite3Isspace(z[i]) ){
62459         if( z[i-1]!=' ' ){
62460           z[j++] = ' ';
62461         }
62462       }else{
62463         z[j++] = z[i];
62464       }
62465     }
62466     z[j] = 0;
62467     sqlite3IoTrace("SQL %s\n", z);
62468   }
62469 }
62470 #endif /* !SQLITE_OMIT_TRACE && SQLITE_ENABLE_IOTRACE */
62471 
62472 /*
62473 ** Allocate space from a fixed size buffer and return a pointer to
62474 ** that space.  If insufficient space is available, return NULL.
62475 **
62476 ** The pBuf parameter is the initial value of a pointer which will
62477 ** receive the new memory.  pBuf is normally NULL.  If pBuf is not
62478 ** NULL, it means that memory space has already been allocated and that
62479 ** this routine should not allocate any new memory.  When pBuf is not
62480 ** NULL simply return pBuf.  Only allocate new memory space when pBuf
62481 ** is NULL.
62482 **
62483 ** nByte is the number of bytes of space needed.
62484 **
62485 ** *ppFrom points to available space and pEnd points to the end of the
62486 ** available space.  When space is allocated, *ppFrom is advanced past
62487 ** the end of the allocated space.
62488 **
62489 ** *pnByte is a counter of the number of bytes of space that have failed
62490 ** to allocate.  If there is insufficient space in *ppFrom to satisfy the
62491 ** request, then increment *pnByte by the amount of the request.
62492 */
62493 static void *allocSpace(
62494   void *pBuf,          /* Where return pointer will be stored */
62495   int nByte,           /* Number of bytes to allocate */
62496   u8 **ppFrom,         /* IN/OUT: Allocate from *ppFrom */
62497   u8 *pEnd,            /* Pointer to 1 byte past the end of *ppFrom buffer */
62498   int *pnByte          /* If allocation cannot be made, increment *pnByte */
62499 ){
62500   assert( EIGHT_BYTE_ALIGNMENT(*ppFrom) );
62501   if( pBuf ) return pBuf;
62502   nByte = ROUND8(nByte);
62503   if( &(*ppFrom)[nByte] <= pEnd ){
62504     pBuf = (void*)*ppFrom;
62505     *ppFrom += nByte;
62506   }else{
62507     *pnByte += nByte;
62508   }
62509   return pBuf;
62510 }
62511 
62512 /*
62513 ** Rewind the VDBE back to the beginning in preparation for
62514 ** running it.
62515 */
62516 SQLITE_PRIVATE void sqlite3VdbeRewind(Vdbe *p){
62517 #if defined(SQLITE_DEBUG) || defined(VDBE_PROFILE)
62518   int i;
62519 #endif
62520   assert( p!=0 );
62521   assert( p->magic==VDBE_MAGIC_INIT );
62522 
62523   /* There should be at least one opcode.
62524   */
62525   assert( p->nOp>0 );
62526 
62527   /* Set the magic to VDBE_MAGIC_RUN sooner rather than later. */
62528   p->magic = VDBE_MAGIC_RUN;
62529 
62530 #ifdef SQLITE_DEBUG
62531   for(i=1; i<p->nMem; i++){
62532     assert( p->aMem[i].db==p->db );
62533   }
62534 #endif
62535   p->pc = -1;
62536   p->rc = SQLITE_OK;
62537   p->errorAction = OE_Abort;
62538   p->magic = VDBE_MAGIC_RUN;
62539   p->nChange = 0;
62540   p->cacheCtr = 1;
62541   p->minWriteFileFormat = 255;
62542   p->iStatement = 0;
62543   p->nFkConstraint = 0;
62544 #ifdef VDBE_PROFILE
62545   for(i=0; i<p->nOp; i++){
62546     p->aOp[i].cnt = 0;
62547     p->aOp[i].cycles = 0;
62548   }
62549 #endif
62550 }
62551 
62552 /*
62553 ** Prepare a virtual machine for execution for the first time after
62554 ** creating the virtual machine.  This involves things such
62555 ** as allocating stack space and initializing the program counter.
62556 ** After the VDBE has be prepped, it can be executed by one or more
62557 ** calls to sqlite3VdbeExec().  
62558 **
62559 ** This function may be called exact once on a each virtual machine.
62560 ** After this routine is called the VM has been "packaged" and is ready
62561 ** to run.  After this routine is called, futher calls to 
62562 ** sqlite3VdbeAddOp() functions are prohibited.  This routine disconnects
62563 ** the Vdbe from the Parse object that helped generate it so that the
62564 ** the Vdbe becomes an independent entity and the Parse object can be
62565 ** destroyed.
62566 **
62567 ** Use the sqlite3VdbeRewind() procedure to restore a virtual machine back
62568 ** to its initial state after it has been run.
62569 */
62570 SQLITE_PRIVATE void sqlite3VdbeMakeReady(
62571   Vdbe *p,                       /* The VDBE */
62572   Parse *pParse                  /* Parsing context */
62573 ){
62574   sqlite3 *db;                   /* The database connection */
62575   int nVar;                      /* Number of parameters */
62576   int nMem;                      /* Number of VM memory registers */
62577   int nCursor;                   /* Number of cursors required */
62578   int nArg;                      /* Number of arguments in subprograms */
62579   int nOnce;                     /* Number of OP_Once instructions */
62580   int n;                         /* Loop counter */
62581   u8 *zCsr;                      /* Memory available for allocation */
62582   u8 *zEnd;                      /* First byte past allocated memory */
62583   int nByte;                     /* How much extra memory is needed */
62584 
62585   assert( p!=0 );
62586   assert( p->nOp>0 );
62587   assert( pParse!=0 );
62588   assert( p->magic==VDBE_MAGIC_INIT );
62589   db = p->db;
62590   assert( db->mallocFailed==0 );
62591   nVar = pParse->nVar;
62592   nMem = pParse->nMem;
62593   nCursor = pParse->nTab;
62594   nArg = pParse->nMaxArg;
62595   nOnce = pParse->nOnce;
62596   if( nOnce==0 ) nOnce = 1; /* Ensure at least one byte in p->aOnceFlag[] */
62597   
62598   /* For each cursor required, also allocate a memory cell. Memory
62599   ** cells (nMem+1-nCursor)..nMem, inclusive, will never be used by
62600   ** the vdbe program. Instead they are used to allocate space for
62601   ** VdbeCursor/BtCursor structures. The blob of memory associated with 
62602   ** cursor 0 is stored in memory cell nMem. Memory cell (nMem-1)
62603   ** stores the blob of memory associated with cursor 1, etc.
62604   **
62605   ** See also: allocateCursor().
62606   */
62607   nMem += nCursor;
62608 
62609   /* Allocate space for memory registers, SQL variables, VDBE cursors and 
62610   ** an array to marshal SQL function arguments in.
62611   */
62612   zCsr = (u8*)&p->aOp[p->nOp];       /* Memory avaliable for allocation */
62613   zEnd = (u8*)&p->aOp[p->nOpAlloc];  /* First byte past end of zCsr[] */
62614 
62615   resolveP2Values(p, &nArg);
62616   p->usesStmtJournal = (u8)(pParse->isMultiWrite && pParse->mayAbort);
62617   if( pParse->explain && nMem<10 ){
62618     nMem = 10;
62619   }
62620   memset(zCsr, 0, zEnd-zCsr);
62621   zCsr += (zCsr - (u8*)0)&7;
62622   assert( EIGHT_BYTE_ALIGNMENT(zCsr) );
62623   p->expired = 0;
62624 
62625   /* Memory for registers, parameters, cursor, etc, is allocated in two
62626   ** passes.  On the first pass, we try to reuse unused space at the 
62627   ** end of the opcode array.  If we are unable to satisfy all memory
62628   ** requirements by reusing the opcode array tail, then the second
62629   ** pass will fill in the rest using a fresh allocation.  
62630   **
62631   ** This two-pass approach that reuses as much memory as possible from
62632   ** the leftover space at the end of the opcode array can significantly
62633   ** reduce the amount of memory held by a prepared statement.
62634   */
62635   do {
62636     nByte = 0;
62637     p->aMem = allocSpace(p->aMem, nMem*sizeof(Mem), &zCsr, zEnd, &nByte);
62638     p->aVar = allocSpace(p->aVar, nVar*sizeof(Mem), &zCsr, zEnd, &nByte);
62639     p->apArg = allocSpace(p->apArg, nArg*sizeof(Mem*), &zCsr, zEnd, &nByte);
62640     p->azVar = allocSpace(p->azVar, nVar*sizeof(char*), &zCsr, zEnd, &nByte);
62641     p->apCsr = allocSpace(p->apCsr, nCursor*sizeof(VdbeCursor*),
62642                           &zCsr, zEnd, &nByte);
62643     p->aOnceFlag = allocSpace(p->aOnceFlag, nOnce, &zCsr, zEnd, &nByte);
62644     if( nByte ){
62645       p->pFree = sqlite3DbMallocZero(db, nByte);
62646     }
62647     zCsr = p->pFree;
62648     zEnd = &zCsr[nByte];
62649   }while( nByte && !db->mallocFailed );
62650 
62651   p->nCursor = nCursor;
62652   p->nOnceFlag = nOnce;
62653   if( p->aVar ){
62654     p->nVar = (ynVar)nVar;
62655     for(n=0; n<nVar; n++){
62656       p->aVar[n].flags = MEM_Null;
62657       p->aVar[n].db = db;
62658     }
62659   }
62660   if( p->azVar ){
62661     p->nzVar = pParse->nzVar;
62662     memcpy(p->azVar, pParse->azVar, p->nzVar*sizeof(p->azVar[0]));
62663     memset(pParse->azVar, 0, pParse->nzVar*sizeof(pParse->azVar[0]));
62664   }
62665   if( p->aMem ){
62666     p->aMem--;                      /* aMem[] goes from 1..nMem */
62667     p->nMem = nMem;                 /*       not from 0..nMem-1 */
62668     for(n=1; n<=nMem; n++){
62669       p->aMem[n].flags = MEM_Invalid;
62670       p->aMem[n].db = db;
62671     }
62672   }
62673   p->explain = pParse->explain;
62674   sqlite3VdbeRewind(p);
62675 }
62676 
62677 /*
62678 ** Close a VDBE cursor and release all the resources that cursor 
62679 ** happens to hold.
62680 */
62681 SQLITE_PRIVATE void sqlite3VdbeFreeCursor(Vdbe *p, VdbeCursor *pCx){
62682   if( pCx==0 ){
62683     return;
62684   }
62685   sqlite3VdbeSorterClose(p->db, pCx);
62686   if( pCx->pBt ){
62687     sqlite3BtreeClose(pCx->pBt);
62688     /* The pCx->pCursor will be close automatically, if it exists, by
62689     ** the call above. */
62690   }else if( pCx->pCursor ){
62691     sqlite3BtreeCloseCursor(pCx->pCursor);
62692   }
62693 #ifndef SQLITE_OMIT_VIRTUALTABLE
62694   if( pCx->pVtabCursor ){
62695     sqlite3_vtab_cursor *pVtabCursor = pCx->pVtabCursor;
62696     const sqlite3_module *pModule = pVtabCursor->pVtab->pModule;
62697     p->inVtabMethod = 1;
62698     pModule->xClose(pVtabCursor);
62699     p->inVtabMethod = 0;
62700   }
62701 #endif
62702 }
62703 
62704 /*
62705 ** Copy the values stored in the VdbeFrame structure to its Vdbe. This
62706 ** is used, for example, when a trigger sub-program is halted to restore
62707 ** control to the main program.
62708 */
62709 SQLITE_PRIVATE int sqlite3VdbeFrameRestore(VdbeFrame *pFrame){
62710   Vdbe *v = pFrame->v;
62711   v->aOnceFlag = pFrame->aOnceFlag;
62712   v->nOnceFlag = pFrame->nOnceFlag;
62713   v->aOp = pFrame->aOp;
62714   v->nOp = pFrame->nOp;
62715   v->aMem = pFrame->aMem;
62716   v->nMem = pFrame->nMem;
62717   v->apCsr = pFrame->apCsr;
62718   v->nCursor = pFrame->nCursor;
62719   v->db->lastRowid = pFrame->lastRowid;
62720   v->nChange = pFrame->nChange;
62721   return pFrame->pc;
62722 }
62723 
62724 /*
62725 ** Close all cursors.
62726 **
62727 ** Also release any dynamic memory held by the VM in the Vdbe.aMem memory 
62728 ** cell array. This is necessary as the memory cell array may contain
62729 ** pointers to VdbeFrame objects, which may in turn contain pointers to
62730 ** open cursors.
62731 */
62732 static void closeAllCursors(Vdbe *p){
62733   if( p->pFrame ){
62734     VdbeFrame *pFrame;
62735     for(pFrame=p->pFrame; pFrame->pParent; pFrame=pFrame->pParent);
62736     sqlite3VdbeFrameRestore(pFrame);
62737   }
62738   p->pFrame = 0;
62739   p->nFrame = 0;
62740 
62741   if( p->apCsr ){
62742     int i;
62743     for(i=0; i<p->nCursor; i++){
62744       VdbeCursor *pC = p->apCsr[i];
62745       if( pC ){
62746         sqlite3VdbeFreeCursor(p, pC);
62747         p->apCsr[i] = 0;
62748       }
62749     }
62750   }
62751   if( p->aMem ){
62752     releaseMemArray(&p->aMem[1], p->nMem);
62753   }
62754   while( p->pDelFrame ){
62755     VdbeFrame *pDel = p->pDelFrame;
62756     p->pDelFrame = pDel->pParent;
62757     sqlite3VdbeFrameDelete(pDel);
62758   }
62759 
62760   /* Delete any auxdata allocations made by the VM */
62761   sqlite3VdbeDeleteAuxData(p, -1, 0);
62762   assert( p->pAuxData==0 );
62763 }
62764 
62765 /*
62766 ** Clean up the VM after execution.
62767 **
62768 ** This routine will automatically close any cursors, lists, and/or
62769 ** sorters that were left open.  It also deletes the values of
62770 ** variables in the aVar[] array.
62771 */
62772 static void Cleanup(Vdbe *p){
62773   sqlite3 *db = p->db;
62774 
62775 #ifdef SQLITE_DEBUG
62776   /* Execute assert() statements to ensure that the Vdbe.apCsr[] and 
62777   ** Vdbe.aMem[] arrays have already been cleaned up.  */
62778   int i;
62779   if( p->apCsr ) for(i=0; i<p->nCursor; i++) assert( p->apCsr[i]==0 );
62780   if( p->aMem ){
62781     for(i=1; i<=p->nMem; i++) assert( p->aMem[i].flags==MEM_Invalid );
62782   }
62783 #endif
62784 
62785   sqlite3DbFree(db, p->zErrMsg);
62786   p->zErrMsg = 0;
62787   p->pResultSet = 0;
62788 }
62789 
62790 /*
62791 ** Set the number of result columns that will be returned by this SQL
62792 ** statement. This is now set at compile time, rather than during
62793 ** execution of the vdbe program so that sqlite3_column_count() can
62794 ** be called on an SQL statement before sqlite3_step().
62795 */
62796 SQLITE_PRIVATE void sqlite3VdbeSetNumCols(Vdbe *p, int nResColumn){
62797   Mem *pColName;
62798   int n;
62799   sqlite3 *db = p->db;
62800 
62801   releaseMemArray(p->aColName, p->nResColumn*COLNAME_N);
62802   sqlite3DbFree(db, p->aColName);
62803   n = nResColumn*COLNAME_N;
62804   p->nResColumn = (u16)nResColumn;
62805   p->aColName = pColName = (Mem*)sqlite3DbMallocZero(db, sizeof(Mem)*n );
62806   if( p->aColName==0 ) return;
62807   while( n-- > 0 ){
62808     pColName->flags = MEM_Null;
62809     pColName->db = p->db;
62810     pColName++;
62811   }
62812 }
62813 
62814 /*
62815 ** Set the name of the idx'th column to be returned by the SQL statement.
62816 ** zName must be a pointer to a nul terminated string.
62817 **
62818 ** This call must be made after a call to sqlite3VdbeSetNumCols().
62819 **
62820 ** The final parameter, xDel, must be one of SQLITE_DYNAMIC, SQLITE_STATIC
62821 ** or SQLITE_TRANSIENT. If it is SQLITE_DYNAMIC, then the buffer pointed
62822 ** to by zName will be freed by sqlite3DbFree() when the vdbe is destroyed.
62823 */
62824 SQLITE_PRIVATE int sqlite3VdbeSetColName(
62825   Vdbe *p,                         /* Vdbe being configured */
62826   int idx,                         /* Index of column zName applies to */
62827   int var,                         /* One of the COLNAME_* constants */
62828   const char *zName,               /* Pointer to buffer containing name */
62829   void (*xDel)(void*)              /* Memory management strategy for zName */
62830 ){
62831   int rc;
62832   Mem *pColName;
62833   assert( idx<p->nResColumn );
62834   assert( var<COLNAME_N );
62835   if( p->db->mallocFailed ){
62836     assert( !zName || xDel!=SQLITE_DYNAMIC );
62837     return SQLITE_NOMEM;
62838   }
62839   assert( p->aColName!=0 );
62840   pColName = &(p->aColName[idx+var*p->nResColumn]);
62841   rc = sqlite3VdbeMemSetStr(pColName, zName, -1, SQLITE_UTF8, xDel);
62842   assert( rc!=0 || !zName || (pColName->flags&MEM_Term)!=0 );
62843   return rc;
62844 }
62845 
62846 /*
62847 ** A read or write transaction may or may not be active on database handle
62848 ** db. If a transaction is active, commit it. If there is a
62849 ** write-transaction spanning more than one database file, this routine
62850 ** takes care of the master journal trickery.
62851 */
62852 static int vdbeCommit(sqlite3 *db, Vdbe *p){
62853   int i;
62854   int nTrans = 0;  /* Number of databases with an active write-transaction */
62855   int rc = SQLITE_OK;
62856   int needXcommit = 0;
62857 
62858 #ifdef SQLITE_OMIT_VIRTUALTABLE
62859   /* With this option, sqlite3VtabSync() is defined to be simply 
62860   ** SQLITE_OK so p is not used. 
62861   */
62862   UNUSED_PARAMETER(p);
62863 #endif
62864 
62865   /* Before doing anything else, call the xSync() callback for any
62866   ** virtual module tables written in this transaction. This has to
62867   ** be done before determining whether a master journal file is 
62868   ** required, as an xSync() callback may add an attached database
62869   ** to the transaction.
62870   */
62871   rc = sqlite3VtabSync(db, p);
62872 
62873   /* This loop determines (a) if the commit hook should be invoked and
62874   ** (b) how many database files have open write transactions, not 
62875   ** including the temp database. (b) is important because if more than 
62876   ** one database file has an open write transaction, a master journal
62877   ** file is required for an atomic commit.
62878   */ 
62879   for(i=0; rc==SQLITE_OK && i<db->nDb; i++){ 
62880     Btree *pBt = db->aDb[i].pBt;
62881     if( sqlite3BtreeIsInTrans(pBt) ){
62882       needXcommit = 1;
62883       if( i!=1 ) nTrans++;
62884       sqlite3BtreeEnter(pBt);
62885       rc = sqlite3PagerExclusiveLock(sqlite3BtreePager(pBt));
62886       sqlite3BtreeLeave(pBt);
62887     }
62888   }
62889   if( rc!=SQLITE_OK ){
62890     return rc;
62891   }
62892 
62893   /* If there are any write-transactions at all, invoke the commit hook */
62894   if( needXcommit && db->xCommitCallback ){
62895     rc = db->xCommitCallback(db->pCommitArg);
62896     if( rc ){
62897       return SQLITE_CONSTRAINT_COMMITHOOK;
62898     }
62899   }
62900 
62901   /* The simple case - no more than one database file (not counting the
62902   ** TEMP database) has a transaction active.   There is no need for the
62903   ** master-journal.
62904   **
62905   ** If the return value of sqlite3BtreeGetFilename() is a zero length
62906   ** string, it means the main database is :memory: or a temp file.  In 
62907   ** that case we do not support atomic multi-file commits, so use the 
62908   ** simple case then too.
62909   */
62910   if( 0==sqlite3Strlen30(sqlite3BtreeGetFilename(db->aDb[0].pBt))
62911    || nTrans<=1
62912   ){
62913     for(i=0; rc==SQLITE_OK && i<db->nDb; i++){
62914       Btree *pBt = db->aDb[i].pBt;
62915       if( pBt ){
62916         rc = sqlite3BtreeCommitPhaseOne(pBt, 0);
62917       }
62918     }
62919 
62920     /* Do the commit only if all databases successfully complete phase 1. 
62921     ** If one of the BtreeCommitPhaseOne() calls fails, this indicates an
62922     ** IO error while deleting or truncating a journal file. It is unlikely,
62923     ** but could happen. In this case abandon processing and return the error.
62924     */
62925     for(i=0; rc==SQLITE_OK && i<db->nDb; i++){
62926       Btree *pBt = db->aDb[i].pBt;
62927       if( pBt ){
62928         rc = sqlite3BtreeCommitPhaseTwo(pBt, 0);
62929       }
62930     }
62931     if( rc==SQLITE_OK ){
62932       sqlite3VtabCommit(db);
62933     }
62934   }
62935 
62936   /* The complex case - There is a multi-file write-transaction active.
62937   ** This requires a master journal file to ensure the transaction is
62938   ** committed atomicly.
62939   */
62940 #ifndef SQLITE_OMIT_DISKIO
62941   else{
62942     sqlite3_vfs *pVfs = db->pVfs;
62943     int needSync = 0;
62944     char *zMaster = 0;   /* File-name for the master journal */
62945     char const *zMainFile = sqlite3BtreeGetFilename(db->aDb[0].pBt);
62946     sqlite3_file *pMaster = 0;
62947     i64 offset = 0;
62948     int res;
62949     int retryCount = 0;
62950     int nMainFile;
62951 
62952     /* Select a master journal file name */
62953     nMainFile = sqlite3Strlen30(zMainFile);
62954     zMaster = sqlite3MPrintf(db, "%s-mjXXXXXX9XXz", zMainFile);
62955     if( zMaster==0 ) return SQLITE_NOMEM;
62956     do {
62957       u32 iRandom;
62958       if( retryCount ){
62959         if( retryCount>100 ){
62960           sqlite3_log(SQLITE_FULL, "MJ delete: %s", zMaster);
62961           sqlite3OsDelete(pVfs, zMaster, 0);
62962           break;
62963         }else if( retryCount==1 ){
62964           sqlite3_log(SQLITE_FULL, "MJ collide: %s", zMaster);
62965         }
62966       }
62967       retryCount++;
62968       sqlite3_randomness(sizeof(iRandom), &iRandom);
62969       sqlite3_snprintf(13, &zMaster[nMainFile], "-mj%06X9%02X",
62970                                (iRandom>>8)&0xffffff, iRandom&0xff);
62971       /* The antipenultimate character of the master journal name must
62972       ** be "9" to avoid name collisions when using 8+3 filenames. */
62973       assert( zMaster[sqlite3Strlen30(zMaster)-3]=='9' );
62974       sqlite3FileSuffix3(zMainFile, zMaster);
62975       rc = sqlite3OsAccess(pVfs, zMaster, SQLITE_ACCESS_EXISTS, &res);
62976     }while( rc==SQLITE_OK && res );
62977     if( rc==SQLITE_OK ){
62978       /* Open the master journal. */
62979       rc = sqlite3OsOpenMalloc(pVfs, zMaster, &pMaster, 
62980           SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE|
62981           SQLITE_OPEN_EXCLUSIVE|SQLITE_OPEN_MASTER_JOURNAL, 0
62982       );
62983     }
62984     if( rc!=SQLITE_OK ){
62985       sqlite3DbFree(db, zMaster);
62986       return rc;
62987     }
62988  
62989     /* Write the name of each database file in the transaction into the new
62990     ** master journal file. If an error occurs at this point close
62991     ** and delete the master journal file. All the individual journal files
62992     ** still have 'null' as the master journal pointer, so they will roll
62993     ** back independently if a failure occurs.
62994     */
62995     for(i=0; i<db->nDb; i++){
62996       Btree *pBt = db->aDb[i].pBt;
62997       if( sqlite3BtreeIsInTrans(pBt) ){
62998         char const *zFile = sqlite3BtreeGetJournalname(pBt);
62999         if( zFile==0 ){
63000           continue;  /* Ignore TEMP and :memory: databases */
63001         }
63002         assert( zFile[0]!=0 );
63003         if( !needSync && !sqlite3BtreeSyncDisabled(pBt) ){
63004           needSync = 1;
63005         }
63006         rc = sqlite3OsWrite(pMaster, zFile, sqlite3Strlen30(zFile)+1, offset);
63007         offset += sqlite3Strlen30(zFile)+1;
63008         if( rc!=SQLITE_OK ){
63009           sqlite3OsCloseFree(pMaster);
63010           sqlite3OsDelete(pVfs, zMaster, 0);
63011           sqlite3DbFree(db, zMaster);
63012           return rc;
63013         }
63014       }
63015     }
63016 
63017     /* Sync the master journal file. If the IOCAP_SEQUENTIAL device
63018     ** flag is set this is not required.
63019     */
63020     if( needSync 
63021      && 0==(sqlite3OsDeviceCharacteristics(pMaster)&SQLITE_IOCAP_SEQUENTIAL)
63022      && SQLITE_OK!=(rc = sqlite3OsSync(pMaster, SQLITE_SYNC_NORMAL))
63023     ){
63024       sqlite3OsCloseFree(pMaster);
63025       sqlite3OsDelete(pVfs, zMaster, 0);
63026       sqlite3DbFree(db, zMaster);
63027       return rc;
63028     }
63029 
63030     /* Sync all the db files involved in the transaction. The same call
63031     ** sets the master journal pointer in each individual journal. If
63032     ** an error occurs here, do not delete the master journal file.
63033     **
63034     ** If the error occurs during the first call to
63035     ** sqlite3BtreeCommitPhaseOne(), then there is a chance that the
63036     ** master journal file will be orphaned. But we cannot delete it,
63037     ** in case the master journal file name was written into the journal
63038     ** file before the failure occurred.
63039     */
63040     for(i=0; rc==SQLITE_OK && i<db->nDb; i++){ 
63041       Btree *pBt = db->aDb[i].pBt;
63042       if( pBt ){
63043         rc = sqlite3BtreeCommitPhaseOne(pBt, zMaster);
63044       }
63045     }
63046     sqlite3OsCloseFree(pMaster);
63047     assert( rc!=SQLITE_BUSY );
63048     if( rc!=SQLITE_OK ){
63049       sqlite3DbFree(db, zMaster);
63050       return rc;
63051     }
63052 
63053     /* Delete the master journal file. This commits the transaction. After
63054     ** doing this the directory is synced again before any individual
63055     ** transaction files are deleted.
63056     */
63057     rc = sqlite3OsDelete(pVfs, zMaster, 1);
63058     sqlite3DbFree(db, zMaster);
63059     zMaster = 0;
63060     if( rc ){
63061       return rc;
63062     }
63063 
63064     /* All files and directories have already been synced, so the following
63065     ** calls to sqlite3BtreeCommitPhaseTwo() are only closing files and
63066     ** deleting or truncating journals. If something goes wrong while
63067     ** this is happening we don't really care. The integrity of the
63068     ** transaction is already guaranteed, but some stray 'cold' journals
63069     ** may be lying around. Returning an error code won't help matters.
63070     */
63071     disable_simulated_io_errors();
63072     sqlite3BeginBenignMalloc();
63073     for(i=0; i<db->nDb; i++){ 
63074       Btree *pBt = db->aDb[i].pBt;
63075       if( pBt ){
63076         sqlite3BtreeCommitPhaseTwo(pBt, 1);
63077       }
63078     }
63079     sqlite3EndBenignMalloc();
63080     enable_simulated_io_errors();
63081 
63082     sqlite3VtabCommit(db);
63083   }
63084 #endif
63085 
63086   return rc;
63087 }
63088 
63089 /* 
63090 ** This routine checks that the sqlite3.nVdbeActive count variable
63091 ** matches the number of vdbe's in the list sqlite3.pVdbe that are
63092 ** currently active. An assertion fails if the two counts do not match.
63093 ** This is an internal self-check only - it is not an essential processing
63094 ** step.
63095 **
63096 ** This is a no-op if NDEBUG is defined.
63097 */
63098 #ifndef NDEBUG
63099 static void checkActiveVdbeCnt(sqlite3 *db){
63100   Vdbe *p;
63101   int cnt = 0;
63102   int nWrite = 0;
63103   int nRead = 0;
63104   p = db->pVdbe;
63105   while( p ){
63106     if( p->magic==VDBE_MAGIC_RUN && p->pc>=0 ){
63107       cnt++;
63108       if( p->readOnly==0 ) nWrite++;
63109       if( p->bIsReader ) nRead++;
63110     }
63111     p = p->pNext;
63112   }
63113   assert( cnt==db->nVdbeActive );
63114   assert( nWrite==db->nVdbeWrite );
63115   assert( nRead==db->nVdbeRead );
63116 }
63117 #else
63118 #define checkActiveVdbeCnt(x)
63119 #endif
63120 
63121 /*
63122 ** If the Vdbe passed as the first argument opened a statement-transaction,
63123 ** close it now. Argument eOp must be either SAVEPOINT_ROLLBACK or
63124 ** SAVEPOINT_RELEASE. If it is SAVEPOINT_ROLLBACK, then the statement
63125 ** transaction is rolled back. If eOp is SAVEPOINT_RELEASE, then the 
63126 ** statement transaction is committed.
63127 **
63128 ** If an IO error occurs, an SQLITE_IOERR_XXX error code is returned. 
63129 ** Otherwise SQLITE_OK.
63130 */
63131 SQLITE_PRIVATE int sqlite3VdbeCloseStatement(Vdbe *p, int eOp){
63132   sqlite3 *const db = p->db;
63133   int rc = SQLITE_OK;
63134 
63135   /* If p->iStatement is greater than zero, then this Vdbe opened a 
63136   ** statement transaction that should be closed here. The only exception
63137   ** is that an IO error may have occurred, causing an emergency rollback.
63138   ** In this case (db->nStatement==0), and there is nothing to do.
63139   */
63140   if( db->nStatement && p->iStatement ){
63141     int i;
63142     const int iSavepoint = p->iStatement-1;
63143 
63144     assert( eOp==SAVEPOINT_ROLLBACK || eOp==SAVEPOINT_RELEASE);
63145     assert( db->nStatement>0 );
63146     assert( p->iStatement==(db->nStatement+db->nSavepoint) );
63147 
63148     for(i=0; i<db->nDb; i++){ 
63149       int rc2 = SQLITE_OK;
63150       Btree *pBt = db->aDb[i].pBt;
63151       if( pBt ){
63152         if( eOp==SAVEPOINT_ROLLBACK ){
63153           rc2 = sqlite3BtreeSavepoint(pBt, SAVEPOINT_ROLLBACK, iSavepoint);
63154         }
63155         if( rc2==SQLITE_OK ){
63156           rc2 = sqlite3BtreeSavepoint(pBt, SAVEPOINT_RELEASE, iSavepoint);
63157         }
63158         if( rc==SQLITE_OK ){
63159           rc = rc2;
63160         }
63161       }
63162     }
63163     db->nStatement--;
63164     p->iStatement = 0;
63165 
63166     if( rc==SQLITE_OK ){
63167       if( eOp==SAVEPOINT_ROLLBACK ){
63168         rc = sqlite3VtabSavepoint(db, SAVEPOINT_ROLLBACK, iSavepoint);
63169       }
63170       if( rc==SQLITE_OK ){
63171         rc = sqlite3VtabSavepoint(db, SAVEPOINT_RELEASE, iSavepoint);
63172       }
63173     }
63174 
63175     /* If the statement transaction is being rolled back, also restore the 
63176     ** database handles deferred constraint counter to the value it had when 
63177     ** the statement transaction was opened.  */
63178     if( eOp==SAVEPOINT_ROLLBACK ){
63179       db->nDeferredCons = p->nStmtDefCons;
63180       db->nDeferredImmCons = p->nStmtDefImmCons;
63181     }
63182   }
63183   return rc;
63184 }
63185 
63186 /*
63187 ** This function is called when a transaction opened by the database 
63188 ** handle associated with the VM passed as an argument is about to be 
63189 ** committed. If there are outstanding deferred foreign key constraint
63190 ** violations, return SQLITE_ERROR. Otherwise, SQLITE_OK.
63191 **
63192 ** If there are outstanding FK violations and this function returns 
63193 ** SQLITE_ERROR, set the result of the VM to SQLITE_CONSTRAINT_FOREIGNKEY
63194 ** and write an error message to it. Then return SQLITE_ERROR.
63195 */
63196 #ifndef SQLITE_OMIT_FOREIGN_KEY
63197 SQLITE_PRIVATE int sqlite3VdbeCheckFk(Vdbe *p, int deferred){
63198   sqlite3 *db = p->db;
63199   if( (deferred && (db->nDeferredCons+db->nDeferredImmCons)>0) 
63200    || (!deferred && p->nFkConstraint>0) 
63201   ){
63202     p->rc = SQLITE_CONSTRAINT_FOREIGNKEY;
63203     p->errorAction = OE_Abort;
63204     sqlite3SetString(&p->zErrMsg, db, "FOREIGN KEY constraint failed");
63205     return SQLITE_ERROR;
63206   }
63207   return SQLITE_OK;
63208 }
63209 #endif
63210 
63211 /*
63212 ** This routine is called the when a VDBE tries to halt.  If the VDBE
63213 ** has made changes and is in autocommit mode, then commit those
63214 ** changes.  If a rollback is needed, then do the rollback.
63215 **
63216 ** This routine is the only way to move the state of a VM from
63217 ** SQLITE_MAGIC_RUN to SQLITE_MAGIC_HALT.  It is harmless to
63218 ** call this on a VM that is in the SQLITE_MAGIC_HALT state.
63219 **
63220 ** Return an error code.  If the commit could not complete because of
63221 ** lock contention, return SQLITE_BUSY.  If SQLITE_BUSY is returned, it
63222 ** means the close did not happen and needs to be repeated.
63223 */
63224 SQLITE_PRIVATE int sqlite3VdbeHalt(Vdbe *p){
63225   int rc;                         /* Used to store transient return codes */
63226   sqlite3 *db = p->db;
63227 
63228   /* This function contains the logic that determines if a statement or
63229   ** transaction will be committed or rolled back as a result of the
63230   ** execution of this virtual machine. 
63231   **
63232   ** If any of the following errors occur:
63233   **
63234   **     SQLITE_NOMEM
63235   **     SQLITE_IOERR
63236   **     SQLITE_FULL
63237   **     SQLITE_INTERRUPT
63238   **
63239   ** Then the internal cache might have been left in an inconsistent
63240   ** state.  We need to rollback the statement transaction, if there is
63241   ** one, or the complete transaction if there is no statement transaction.
63242   */
63243 
63244   if( p->db->mallocFailed ){
63245     p->rc = SQLITE_NOMEM;
63246   }
63247   if( p->aOnceFlag ) memset(p->aOnceFlag, 0, p->nOnceFlag);
63248   closeAllCursors(p);
63249   if( p->magic!=VDBE_MAGIC_RUN ){
63250     return SQLITE_OK;
63251   }
63252   checkActiveVdbeCnt(db);
63253 
63254   /* No commit or rollback needed if the program never started or if the
63255   ** SQL statement does not read or write a database file.  */
63256   if( p->pc>=0 && p->bIsReader ){
63257     int mrc;   /* Primary error code from p->rc */
63258     int eStatementOp = 0;
63259     int isSpecialError;            /* Set to true if a 'special' error */
63260 
63261     /* Lock all btrees used by the statement */
63262     sqlite3VdbeEnter(p);
63263 
63264     /* Check for one of the special errors */
63265     mrc = p->rc & 0xff;
63266     assert( p->rc!=SQLITE_IOERR_BLOCKED );  /* This error no longer exists */
63267     isSpecialError = mrc==SQLITE_NOMEM || mrc==SQLITE_IOERR
63268                      || mrc==SQLITE_INTERRUPT || mrc==SQLITE_FULL;
63269     if( isSpecialError ){
63270       /* If the query was read-only and the error code is SQLITE_INTERRUPT, 
63271       ** no rollback is necessary. Otherwise, at least a savepoint 
63272       ** transaction must be rolled back to restore the database to a 
63273       ** consistent state.
63274       **
63275       ** Even if the statement is read-only, it is important to perform
63276       ** a statement or transaction rollback operation. If the error 
63277       ** occurred while writing to the journal, sub-journal or database
63278       ** file as part of an effort to free up cache space (see function
63279       ** pagerStress() in pager.c), the rollback is required to restore 
63280       ** the pager to a consistent state.
63281       */
63282       if( !p->readOnly || mrc!=SQLITE_INTERRUPT ){
63283         if( (mrc==SQLITE_NOMEM || mrc==SQLITE_FULL) && p->usesStmtJournal ){
63284           eStatementOp = SAVEPOINT_ROLLBACK;
63285         }else{
63286           /* We are forced to roll back the active transaction. Before doing
63287           ** so, abort any other statements this handle currently has active.
63288           */
63289           sqlite3RollbackAll(db, SQLITE_ABORT_ROLLBACK);
63290           sqlite3CloseSavepoints(db);
63291           db->autoCommit = 1;
63292         }
63293       }
63294     }
63295 
63296     /* Check for immediate foreign key violations. */
63297     if( p->rc==SQLITE_OK ){
63298       sqlite3VdbeCheckFk(p, 0);
63299     }
63300   
63301     /* If the auto-commit flag is set and this is the only active writer 
63302     ** VM, then we do either a commit or rollback of the current transaction. 
63303     **
63304     ** Note: This block also runs if one of the special errors handled 
63305     ** above has occurred. 
63306     */
63307     if( !sqlite3VtabInSync(db) 
63308      && db->autoCommit 
63309      && db->nVdbeWrite==(p->readOnly==0) 
63310     ){
63311       if( p->rc==SQLITE_OK || (p->errorAction==OE_Fail && !isSpecialError) ){
63312         rc = sqlite3VdbeCheckFk(p, 1);
63313         if( rc!=SQLITE_OK ){
63314           if( NEVER(p->readOnly) ){
63315             sqlite3VdbeLeave(p);
63316             return SQLITE_ERROR;
63317           }
63318           rc = SQLITE_CONSTRAINT_FOREIGNKEY;
63319         }else{ 
63320           /* The auto-commit flag is true, the vdbe program was successful 
63321           ** or hit an 'OR FAIL' constraint and there are no deferred foreign
63322           ** key constraints to hold up the transaction. This means a commit 
63323           ** is required. */
63324           rc = vdbeCommit(db, p);
63325         }
63326         if( rc==SQLITE_BUSY && p->readOnly ){
63327           sqlite3VdbeLeave(p);
63328           return SQLITE_BUSY;
63329         }else if( rc!=SQLITE_OK ){
63330           p->rc = rc;
63331           sqlite3RollbackAll(db, SQLITE_OK);
63332         }else{
63333           db->nDeferredCons = 0;
63334           db->nDeferredImmCons = 0;
63335           db->flags &= ~SQLITE_DeferFKs;
63336           sqlite3CommitInternalChanges(db);
63337         }
63338       }else{
63339         sqlite3RollbackAll(db, SQLITE_OK);
63340       }
63341       db->nStatement = 0;
63342     }else if( eStatementOp==0 ){
63343       if( p->rc==SQLITE_OK || p->errorAction==OE_Fail ){
63344         eStatementOp = SAVEPOINT_RELEASE;
63345       }else if( p->errorAction==OE_Abort ){
63346         eStatementOp = SAVEPOINT_ROLLBACK;
63347       }else{
63348         sqlite3RollbackAll(db, SQLITE_ABORT_ROLLBACK);
63349         sqlite3CloseSavepoints(db);
63350         db->autoCommit = 1;
63351       }
63352     }
63353   
63354     /* If eStatementOp is non-zero, then a statement transaction needs to
63355     ** be committed or rolled back. Call sqlite3VdbeCloseStatement() to
63356     ** do so. If this operation returns an error, and the current statement
63357     ** error code is SQLITE_OK or SQLITE_CONSTRAINT, then promote the
63358     ** current statement error code.
63359     */
63360     if( eStatementOp ){
63361       rc = sqlite3VdbeCloseStatement(p, eStatementOp);
63362       if( rc ){
63363         if( p->rc==SQLITE_OK || (p->rc&0xff)==SQLITE_CONSTRAINT ){
63364           p->rc = rc;
63365           sqlite3DbFree(db, p->zErrMsg);
63366           p->zErrMsg = 0;
63367         }
63368         sqlite3RollbackAll(db, SQLITE_ABORT_ROLLBACK);
63369         sqlite3CloseSavepoints(db);
63370         db->autoCommit = 1;
63371       }
63372     }
63373   
63374     /* If this was an INSERT, UPDATE or DELETE and no statement transaction
63375     ** has been rolled back, update the database connection change-counter. 
63376     */
63377     if( p->changeCntOn ){
63378       if( eStatementOp!=SAVEPOINT_ROLLBACK ){
63379         sqlite3VdbeSetChanges(db, p->nChange);
63380       }else{
63381         sqlite3VdbeSetChanges(db, 0);
63382       }
63383       p->nChange = 0;
63384     }
63385 
63386     /* Release the locks */
63387     sqlite3VdbeLeave(p);
63388   }
63389 
63390   /* We have successfully halted and closed the VM.  Record this fact. */
63391   if( p->pc>=0 ){
63392     db->nVdbeActive--;
63393     if( !p->readOnly ) db->nVdbeWrite--;
63394     if( p->bIsReader ) db->nVdbeRead--;
63395     assert( db->nVdbeActive>=db->nVdbeRead );
63396     assert( db->nVdbeRead>=db->nVdbeWrite );
63397     assert( db->nVdbeWrite>=0 );
63398   }
63399   p->magic = VDBE_MAGIC_HALT;
63400   checkActiveVdbeCnt(db);
63401   if( p->db->mallocFailed ){
63402     p->rc = SQLITE_NOMEM;
63403   }
63404 
63405   /* If the auto-commit flag is set to true, then any locks that were held
63406   ** by connection db have now been released. Call sqlite3ConnectionUnlocked() 
63407   ** to invoke any required unlock-notify callbacks.
63408   */
63409   if( db->autoCommit ){
63410     sqlite3ConnectionUnlocked(db);
63411   }
63412 
63413   assert( db->nVdbeActive>0 || db->autoCommit==0 || db->nStatement==0 );
63414   return (p->rc==SQLITE_BUSY ? SQLITE_BUSY : SQLITE_OK);
63415 }
63416 
63417 
63418 /*
63419 ** Each VDBE holds the result of the most recent sqlite3_step() call
63420 ** in p->rc.  This routine sets that result back to SQLITE_OK.
63421 */
63422 SQLITE_PRIVATE void sqlite3VdbeResetStepResult(Vdbe *p){
63423   p->rc = SQLITE_OK;
63424 }
63425 
63426 /*
63427 ** Copy the error code and error message belonging to the VDBE passed
63428 ** as the first argument to its database handle (so that they will be 
63429 ** returned by calls to sqlite3_errcode() and sqlite3_errmsg()).
63430 **
63431 ** This function does not clear the VDBE error code or message, just
63432 ** copies them to the database handle.
63433 */
63434 SQLITE_PRIVATE int sqlite3VdbeTransferError(Vdbe *p){
63435   sqlite3 *db = p->db;
63436   int rc = p->rc;
63437   if( p->zErrMsg ){
63438     u8 mallocFailed = db->mallocFailed;
63439     sqlite3BeginBenignMalloc();
63440     sqlite3ValueSetStr(db->pErr, -1, p->zErrMsg, SQLITE_UTF8, SQLITE_TRANSIENT);
63441     sqlite3EndBenignMalloc();
63442     db->mallocFailed = mallocFailed;
63443     db->errCode = rc;
63444   }else{
63445     sqlite3Error(db, rc, 0);
63446   }
63447   return rc;
63448 }
63449 
63450 #ifdef SQLITE_ENABLE_SQLLOG
63451 /*
63452 ** If an SQLITE_CONFIG_SQLLOG hook is registered and the VM has been run, 
63453 ** invoke it.
63454 */
63455 static void vdbeInvokeSqllog(Vdbe *v){
63456   if( sqlite3GlobalConfig.xSqllog && v->rc==SQLITE_OK && v->zSql && v->pc>=0 ){
63457     char *zExpanded = sqlite3VdbeExpandSql(v, v->zSql);
63458     assert( v->db->init.busy==0 );
63459     if( zExpanded ){
63460       sqlite3GlobalConfig.xSqllog(
63461           sqlite3GlobalConfig.pSqllogArg, v->db, zExpanded, 1
63462       );
63463       sqlite3DbFree(v->db, zExpanded);
63464     }
63465   }
63466 }
63467 #else
63468 # define vdbeInvokeSqllog(x)
63469 #endif
63470 
63471 /*
63472 ** Clean up a VDBE after execution but do not delete the VDBE just yet.
63473 ** Write any error messages into *pzErrMsg.  Return the result code.
63474 **
63475 ** After this routine is run, the VDBE should be ready to be executed
63476 ** again.
63477 **
63478 ** To look at it another way, this routine resets the state of the
63479 ** virtual machine from VDBE_MAGIC_RUN or VDBE_MAGIC_HALT back to
63480 ** VDBE_MAGIC_INIT.
63481 */
63482 SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe *p){
63483   sqlite3 *db;
63484   db = p->db;
63485 
63486   /* If the VM did not run to completion or if it encountered an
63487   ** error, then it might not have been halted properly.  So halt
63488   ** it now.
63489   */
63490   sqlite3VdbeHalt(p);
63491 
63492   /* If the VDBE has be run even partially, then transfer the error code
63493   ** and error message from the VDBE into the main database structure.  But
63494   ** if the VDBE has just been set to run but has not actually executed any
63495   ** instructions yet, leave the main database error information unchanged.
63496   */
63497   if( p->pc>=0 ){
63498     vdbeInvokeSqllog(p);
63499     sqlite3VdbeTransferError(p);
63500     sqlite3DbFree(db, p->zErrMsg);
63501     p->zErrMsg = 0;
63502     if( p->runOnlyOnce ) p->expired = 1;
63503   }else if( p->rc && p->expired ){
63504     /* The expired flag was set on the VDBE before the first call
63505     ** to sqlite3_step(). For consistency (since sqlite3_step() was
63506     ** called), set the database error in this case as well.
63507     */
63508     sqlite3Error(db, p->rc, 0);
63509     sqlite3ValueSetStr(db->pErr, -1, p->zErrMsg, SQLITE_UTF8, SQLITE_TRANSIENT);
63510     sqlite3DbFree(db, p->zErrMsg);
63511     p->zErrMsg = 0;
63512   }
63513 
63514   /* Reclaim all memory used by the VDBE
63515   */
63516   Cleanup(p);
63517 
63518   /* Save profiling information from this VDBE run.
63519   */
63520 #ifdef VDBE_PROFILE
63521   {
63522     FILE *out = fopen("vdbe_profile.out", "a");
63523     if( out ){
63524       int i;
63525       fprintf(out, "---- ");
63526       for(i=0; i<p->nOp; i++){
63527         fprintf(out, "%02x", p->aOp[i].opcode);
63528       }
63529       fprintf(out, "\n");
63530       for(i=0; i<p->nOp; i++){
63531         fprintf(out, "%6d %10lld %8lld ",
63532            p->aOp[i].cnt,
63533            p->aOp[i].cycles,
63534            p->aOp[i].cnt>0 ? p->aOp[i].cycles/p->aOp[i].cnt : 0
63535         );
63536         sqlite3VdbePrintOp(out, i, &p->aOp[i]);
63537       }
63538       fclose(out);
63539     }
63540   }
63541 #endif
63542   p->iCurrentTime = 0;
63543   p->magic = VDBE_MAGIC_INIT;
63544   return p->rc & db->errMask;
63545 }
63546  
63547 /*
63548 ** Clean up and delete a VDBE after execution.  Return an integer which is
63549 ** the result code.  Write any error message text into *pzErrMsg.
63550 */
63551 SQLITE_PRIVATE int sqlite3VdbeFinalize(Vdbe *p){
63552   int rc = SQLITE_OK;
63553   if( p->magic==VDBE_MAGIC_RUN || p->magic==VDBE_MAGIC_HALT ){
63554     rc = sqlite3VdbeReset(p);
63555     assert( (rc & p->db->errMask)==rc );
63556   }
63557   sqlite3VdbeDelete(p);
63558   return rc;
63559 }
63560 
63561 /*
63562 ** If parameter iOp is less than zero, then invoke the destructor for
63563 ** all auxiliary data pointers currently cached by the VM passed as
63564 ** the first argument.
63565 **
63566 ** Or, if iOp is greater than or equal to zero, then the destructor is
63567 ** only invoked for those auxiliary data pointers created by the user 
63568 ** function invoked by the OP_Function opcode at instruction iOp of 
63569 ** VM pVdbe, and only then if:
63570 **
63571 **    * the associated function parameter is the 32nd or later (counting
63572 **      from left to right), or
63573 **
63574 **    * the corresponding bit in argument mask is clear (where the first
63575 **      function parameter corrsponds to bit 0 etc.).
63576 */
63577 SQLITE_PRIVATE void sqlite3VdbeDeleteAuxData(Vdbe *pVdbe, int iOp, int mask){
63578   AuxData **pp = &pVdbe->pAuxData;
63579   while( *pp ){
63580     AuxData *pAux = *pp;
63581     if( (iOp<0)
63582      || (pAux->iOp==iOp && (pAux->iArg>31 || !(mask & ((u32)1<<pAux->iArg))))
63583     ){
63584       if( pAux->xDelete ){
63585         pAux->xDelete(pAux->pAux);
63586       }
63587       *pp = pAux->pNext;
63588       sqlite3DbFree(pVdbe->db, pAux);
63589     }else{
63590       pp= &pAux->pNext;
63591     }
63592   }
63593 }
63594 
63595 /*
63596 ** Free all memory associated with the Vdbe passed as the second argument,
63597 ** except for object itself, which is preserved.
63598 **
63599 ** The difference between this function and sqlite3VdbeDelete() is that
63600 ** VdbeDelete() also unlinks the Vdbe from the list of VMs associated with
63601 ** the database connection and frees the object itself.
63602 */
63603 SQLITE_PRIVATE void sqlite3VdbeClearObject(sqlite3 *db, Vdbe *p){
63604   SubProgram *pSub, *pNext;
63605   int i;
63606   assert( p->db==0 || p->db==db );
63607   releaseMemArray(p->aVar, p->nVar);
63608   releaseMemArray(p->aColName, p->nResColumn*COLNAME_N);
63609   for(pSub=p->pProgram; pSub; pSub=pNext){
63610     pNext = pSub->pNext;
63611     vdbeFreeOpArray(db, pSub->aOp, pSub->nOp);
63612     sqlite3DbFree(db, pSub);
63613   }
63614   for(i=p->nzVar-1; i>=0; i--) sqlite3DbFree(db, p->azVar[i]);
63615   vdbeFreeOpArray(db, p->aOp, p->nOp);
63616   sqlite3DbFree(db, p->aLabel);
63617   sqlite3DbFree(db, p->aColName);
63618   sqlite3DbFree(db, p->zSql);
63619   sqlite3DbFree(db, p->pFree);
63620 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
63621   sqlite3DbFree(db, p->zExplain);
63622   sqlite3DbFree(db, p->pExplain);
63623 #endif
63624 }
63625 
63626 /*
63627 ** Delete an entire VDBE.
63628 */
63629 SQLITE_PRIVATE void sqlite3VdbeDelete(Vdbe *p){
63630   sqlite3 *db;
63631 
63632   if( NEVER(p==0) ) return;
63633   db = p->db;
63634   assert( sqlite3_mutex_held(db->mutex) );
63635   sqlite3VdbeClearObject(db, p);
63636   if( p->pPrev ){
63637     p->pPrev->pNext = p->pNext;
63638   }else{
63639     assert( db->pVdbe==p );
63640     db->pVdbe = p->pNext;
63641   }
63642   if( p->pNext ){
63643     p->pNext->pPrev = p->pPrev;
63644   }
63645   p->magic = VDBE_MAGIC_DEAD;
63646   p->db = 0;
63647   sqlite3DbFree(db, p);
63648 }
63649 
63650 /*
63651 ** Make sure the cursor p is ready to read or write the row to which it
63652 ** was last positioned.  Return an error code if an OOM fault or I/O error
63653 ** prevents us from positioning the cursor to its correct position.
63654 **
63655 ** If a MoveTo operation is pending on the given cursor, then do that
63656 ** MoveTo now.  If no move is pending, check to see if the row has been
63657 ** deleted out from under the cursor and if it has, mark the row as
63658 ** a NULL row.
63659 **
63660 ** If the cursor is already pointing to the correct row and that row has
63661 ** not been deleted out from under the cursor, then this routine is a no-op.
63662 */
63663 SQLITE_PRIVATE int sqlite3VdbeCursorMoveto(VdbeCursor *p){
63664   if( p->deferredMoveto ){
63665     int res, rc;
63666 #ifdef SQLITE_TEST
63667     extern int sqlite3_search_count;
63668 #endif
63669     assert( p->isTable );
63670     rc = sqlite3BtreeMovetoUnpacked(p->pCursor, 0, p->movetoTarget, 0, &res);
63671     if( rc ) return rc;
63672     p->lastRowid = p->movetoTarget;
63673     if( res!=0 ) return SQLITE_CORRUPT_BKPT;
63674     p->rowidIsValid = 1;
63675 #ifdef SQLITE_TEST
63676     sqlite3_search_count++;
63677 #endif
63678     p->deferredMoveto = 0;
63679     p->cacheStatus = CACHE_STALE;
63680   }else if( p->pCursor ){
63681     int hasMoved;
63682     int rc = sqlite3BtreeCursorHasMoved(p->pCursor, &hasMoved);
63683     if( rc ) return rc;
63684     if( hasMoved ){
63685       p->cacheStatus = CACHE_STALE;
63686       p->nullRow = 1;
63687     }
63688   }
63689   return SQLITE_OK;
63690 }
63691 
63692 /*
63693 ** The following functions:
63694 **
63695 ** sqlite3VdbeSerialType()
63696 ** sqlite3VdbeSerialTypeLen()
63697 ** sqlite3VdbeSerialLen()
63698 ** sqlite3VdbeSerialPut()
63699 ** sqlite3VdbeSerialGet()
63700 **
63701 ** encapsulate the code that serializes values for storage in SQLite
63702 ** data and index records. Each serialized value consists of a
63703 ** 'serial-type' and a blob of data. The serial type is an 8-byte unsigned
63704 ** integer, stored as a varint.
63705 **
63706 ** In an SQLite index record, the serial type is stored directly before
63707 ** the blob of data that it corresponds to. In a table record, all serial
63708 ** types are stored at the start of the record, and the blobs of data at
63709 ** the end. Hence these functions allow the caller to handle the
63710 ** serial-type and data blob separately.
63711 **
63712 ** The following table describes the various storage classes for data:
63713 **
63714 **   serial type        bytes of data      type
63715 **   --------------     ---------------    ---------------
63716 **      0                     0            NULL
63717 **      1                     1            signed integer
63718 **      2                     2            signed integer
63719 **      3                     3            signed integer
63720 **      4                     4            signed integer
63721 **      5                     6            signed integer
63722 **      6                     8            signed integer
63723 **      7                     8            IEEE float
63724 **      8                     0            Integer constant 0
63725 **      9                     0            Integer constant 1
63726 **     10,11                               reserved for expansion
63727 **    N>=12 and even       (N-12)/2        BLOB
63728 **    N>=13 and odd        (N-13)/2        text
63729 **
63730 ** The 8 and 9 types were added in 3.3.0, file format 4.  Prior versions
63731 ** of SQLite will not understand those serial types.
63732 */
63733 
63734 /*
63735 ** Return the serial-type for the value stored in pMem.
63736 */
63737 SQLITE_PRIVATE u32 sqlite3VdbeSerialType(Mem *pMem, int file_format){
63738   int flags = pMem->flags;
63739   int n;
63740 
63741   if( flags&MEM_Null ){
63742     return 0;
63743   }
63744   if( flags&MEM_Int ){
63745     /* Figure out whether to use 1, 2, 4, 6 or 8 bytes. */
63746 #   define MAX_6BYTE ((((i64)0x00008000)<<32)-1)
63747     i64 i = pMem->u.i;
63748     u64 u;
63749     if( i<0 ){
63750       if( i<(-MAX_6BYTE) ) return 6;
63751       /* Previous test prevents:  u = -(-9223372036854775808) */
63752       u = -i;
63753     }else{
63754       u = i;
63755     }
63756     if( u<=127 ){
63757       return ((i&1)==i && file_format>=4) ? 8+(u32)u : 1;
63758     }
63759     if( u<=32767 ) return 2;
63760     if( u<=8388607 ) return 3;
63761     if( u<=2147483647 ) return 4;
63762     if( u<=MAX_6BYTE ) return 5;
63763     return 6;
63764   }
63765   if( flags&MEM_Real ){
63766     return 7;
63767   }
63768   assert( pMem->db->mallocFailed || flags&(MEM_Str|MEM_Blob) );
63769   n = pMem->n;
63770   if( flags & MEM_Zero ){
63771     n += pMem->u.nZero;
63772   }
63773   assert( n>=0 );
63774   return ((n*2) + 12 + ((flags&MEM_Str)!=0));
63775 }
63776 
63777 /*
63778 ** Return the length of the data corresponding to the supplied serial-type.
63779 */
63780 SQLITE_PRIVATE u32 sqlite3VdbeSerialTypeLen(u32 serial_type){
63781   if( serial_type>=12 ){
63782     return (serial_type-12)/2;
63783   }else{
63784     static const u8 aSize[] = { 0, 1, 2, 3, 4, 6, 8, 8, 0, 0, 0, 0 };
63785     return aSize[serial_type];
63786   }
63787 }
63788 
63789 /*
63790 ** If we are on an architecture with mixed-endian floating 
63791 ** points (ex: ARM7) then swap the lower 4 bytes with the 
63792 ** upper 4 bytes.  Return the result.
63793 **
63794 ** For most architectures, this is a no-op.
63795 **
63796 ** (later):  It is reported to me that the mixed-endian problem
63797 ** on ARM7 is an issue with GCC, not with the ARM7 chip.  It seems
63798 ** that early versions of GCC stored the two words of a 64-bit
63799 ** float in the wrong order.  And that error has been propagated
63800 ** ever since.  The blame is not necessarily with GCC, though.
63801 ** GCC might have just copying the problem from a prior compiler.
63802 ** I am also told that newer versions of GCC that follow a different
63803 ** ABI get the byte order right.
63804 **
63805 ** Developers using SQLite on an ARM7 should compile and run their
63806 ** application using -DSQLITE_DEBUG=1 at least once.  With DEBUG
63807 ** enabled, some asserts below will ensure that the byte order of
63808 ** floating point values is correct.
63809 **
63810 ** (2007-08-30)  Frank van Vugt has studied this problem closely
63811 ** and has send his findings to the SQLite developers.  Frank
63812 ** writes that some Linux kernels offer floating point hardware
63813 ** emulation that uses only 32-bit mantissas instead of a full 
63814 ** 48-bits as required by the IEEE standard.  (This is the
63815 ** CONFIG_FPE_FASTFPE option.)  On such systems, floating point
63816 ** byte swapping becomes very complicated.  To avoid problems,
63817 ** the necessary byte swapping is carried out using a 64-bit integer
63818 ** rather than a 64-bit float.  Frank assures us that the code here
63819 ** works for him.  We, the developers, have no way to independently
63820 ** verify this, but Frank seems to know what he is talking about
63821 ** so we trust him.
63822 */
63823 #ifdef SQLITE_MIXED_ENDIAN_64BIT_FLOAT
63824 static u64 floatSwap(u64 in){
63825   union {
63826     u64 r;
63827     u32 i[2];
63828   } u;
63829   u32 t;
63830 
63831   u.r = in;
63832   t = u.i[0];
63833   u.i[0] = u.i[1];
63834   u.i[1] = t;
63835   return u.r;
63836 }
63837 # define swapMixedEndianFloat(X)  X = floatSwap(X)
63838 #else
63839 # define swapMixedEndianFloat(X)
63840 #endif
63841 
63842 /*
63843 ** Write the serialized data blob for the value stored in pMem into 
63844 ** buf. It is assumed that the caller has allocated sufficient space.
63845 ** Return the number of bytes written.
63846 **
63847 ** nBuf is the amount of space left in buf[].  nBuf must always be
63848 ** large enough to hold the entire field.  Except, if the field is
63849 ** a blob with a zero-filled tail, then buf[] might be just the right
63850 ** size to hold everything except for the zero-filled tail.  If buf[]
63851 ** is only big enough to hold the non-zero prefix, then only write that
63852 ** prefix into buf[].  But if buf[] is large enough to hold both the
63853 ** prefix and the tail then write the prefix and set the tail to all
63854 ** zeros.
63855 **
63856 ** Return the number of bytes actually written into buf[].  The number
63857 ** of bytes in the zero-filled tail is included in the return value only
63858 ** if those bytes were zeroed in buf[].
63859 */ 
63860 SQLITE_PRIVATE u32 sqlite3VdbeSerialPut(u8 *buf, int nBuf, Mem *pMem, int file_format){
63861   u32 serial_type = sqlite3VdbeSerialType(pMem, file_format);
63862   u32 len;
63863 
63864   /* Integer and Real */
63865   if( serial_type<=7 && serial_type>0 ){
63866     u64 v;
63867     u32 i;
63868     if( serial_type==7 ){
63869       assert( sizeof(v)==sizeof(pMem->r) );
63870       memcpy(&v, &pMem->r, sizeof(v));
63871       swapMixedEndianFloat(v);
63872     }else{
63873       v = pMem->u.i;
63874     }
63875     len = i = sqlite3VdbeSerialTypeLen(serial_type);
63876     assert( len<=(u32)nBuf );
63877     while( i-- ){
63878       buf[i] = (u8)(v&0xFF);
63879       v >>= 8;
63880     }
63881     return len;
63882   }
63883 
63884   /* String or blob */
63885   if( serial_type>=12 ){
63886     assert( pMem->n + ((pMem->flags & MEM_Zero)?pMem->u.nZero:0)
63887              == (int)sqlite3VdbeSerialTypeLen(serial_type) );
63888     assert( pMem->n<=nBuf );
63889     len = pMem->n;
63890     memcpy(buf, pMem->z, len);
63891     if( pMem->flags & MEM_Zero ){
63892       len += pMem->u.nZero;
63893       assert( nBuf>=0 );
63894       if( len > (u32)nBuf ){
63895         len = (u32)nBuf;
63896       }
63897       memset(&buf[pMem->n], 0, len-pMem->n);
63898     }
63899     return len;
63900   }
63901 
63902   /* NULL or constants 0 or 1 */
63903   return 0;
63904 }
63905 
63906 /*
63907 ** Deserialize the data blob pointed to by buf as serial type serial_type
63908 ** and store the result in pMem.  Return the number of bytes read.
63909 */ 
63910 SQLITE_PRIVATE u32 sqlite3VdbeSerialGet(
63911   const unsigned char *buf,     /* Buffer to deserialize from */
63912   u32 serial_type,              /* Serial type to deserialize */
63913   Mem *pMem                     /* Memory cell to write value into */
63914 ){
63915   switch( serial_type ){
63916     case 10:   /* Reserved for future use */
63917     case 11:   /* Reserved for future use */
63918     case 0: {  /* NULL */
63919       pMem->flags = MEM_Null;
63920       break;
63921     }
63922     case 1: { /* 1-byte signed integer */
63923       pMem->u.i = (signed char)buf[0];
63924       pMem->flags = MEM_Int;
63925       return 1;
63926     }
63927     case 2: { /* 2-byte signed integer */
63928       pMem->u.i = (((signed char)buf[0])<<8) | buf[1];
63929       pMem->flags = MEM_Int;
63930       return 2;
63931     }
63932     case 3: { /* 3-byte signed integer */
63933       pMem->u.i = (((signed char)buf[0])<<16) | (buf[1]<<8) | buf[2];
63934       pMem->flags = MEM_Int;
63935       return 3;
63936     }
63937     case 4: { /* 4-byte signed integer */
63938       pMem->u.i = (buf[0]<<24) | (buf[1]<<16) | (buf[2]<<8) | buf[3];
63939       pMem->flags = MEM_Int;
63940       return 4;
63941     }
63942     case 5: { /* 6-byte signed integer */
63943       u64 x = (((signed char)buf[0])<<8) | buf[1];
63944       u32 y = (buf[2]<<24) | (buf[3]<<16) | (buf[4]<<8) | buf[5];
63945       x = (x<<32) | y;
63946       pMem->u.i = *(i64*)&x;
63947       pMem->flags = MEM_Int;
63948       return 6;
63949     }
63950     case 6:   /* 8-byte signed integer */
63951     case 7: { /* IEEE floating point */
63952       u64 x;
63953       u32 y;
63954 #if !defined(NDEBUG) && !defined(SQLITE_OMIT_FLOATING_POINT)
63955       /* Verify that integers and floating point values use the same
63956       ** byte order.  Or, that if SQLITE_MIXED_ENDIAN_64BIT_FLOAT is
63957       ** defined that 64-bit floating point values really are mixed
63958       ** endian.
63959       */
63960       static const u64 t1 = ((u64)0x3ff00000)<<32;
63961       static const double r1 = 1.0;
63962       u64 t2 = t1;
63963       swapMixedEndianFloat(t2);
63964       assert( sizeof(r1)==sizeof(t2) && memcmp(&r1, &t2, sizeof(r1))==0 );
63965 #endif
63966 
63967       x = (buf[0]<<24) | (buf[1]<<16) | (buf[2]<<8) | buf[3];
63968       y = (buf[4]<<24) | (buf[5]<<16) | (buf[6]<<8) | buf[7];
63969       x = (x<<32) | y;
63970       if( serial_type==6 ){
63971         pMem->u.i = *(i64*)&x;
63972         pMem->flags = MEM_Int;
63973       }else{
63974         assert( sizeof(x)==8 && sizeof(pMem->r)==8 );
63975         swapMixedEndianFloat(x);
63976         memcpy(&pMem->r, &x, sizeof(x));
63977         pMem->flags = sqlite3IsNaN(pMem->r) ? MEM_Null : MEM_Real;
63978       }
63979       return 8;
63980     }
63981     case 8:    /* Integer 0 */
63982     case 9: {  /* Integer 1 */
63983       pMem->u.i = serial_type-8;
63984       pMem->flags = MEM_Int;
63985       return 0;
63986     }
63987     default: {
63988       static const u16 aFlag[] = { MEM_Blob|MEM_Ephem, MEM_Str|MEM_Ephem };
63989       u32 len = (serial_type-12)/2;
63990       pMem->z = (char *)buf;
63991       pMem->n = len;
63992       pMem->xDel = 0;
63993       pMem->flags = aFlag[serial_type&1];
63994       return len;
63995     }
63996   }
63997   return 0;
63998 }
63999 
64000 /*
64001 ** This routine is used to allocate sufficient space for an UnpackedRecord
64002 ** structure large enough to be used with sqlite3VdbeRecordUnpack() if
64003 ** the first argument is a pointer to KeyInfo structure pKeyInfo.
64004 **
64005 ** The space is either allocated using sqlite3DbMallocRaw() or from within
64006 ** the unaligned buffer passed via the second and third arguments (presumably
64007 ** stack space). If the former, then *ppFree is set to a pointer that should
64008 ** be eventually freed by the caller using sqlite3DbFree(). Or, if the 
64009 ** allocation comes from the pSpace/szSpace buffer, *ppFree is set to NULL
64010 ** before returning.
64011 **
64012 ** If an OOM error occurs, NULL is returned.
64013 */
64014 SQLITE_PRIVATE UnpackedRecord *sqlite3VdbeAllocUnpackedRecord(
64015   KeyInfo *pKeyInfo,              /* Description of the record */
64016   char *pSpace,                   /* Unaligned space available */
64017   int szSpace,                    /* Size of pSpace[] in bytes */
64018   char **ppFree                   /* OUT: Caller should free this pointer */
64019 ){
64020   UnpackedRecord *p;              /* Unpacked record to return */
64021   int nOff;                       /* Increment pSpace by nOff to align it */
64022   int nByte;                      /* Number of bytes required for *p */
64023 
64024   /* We want to shift the pointer pSpace up such that it is 8-byte aligned.
64025   ** Thus, we need to calculate a value, nOff, between 0 and 7, to shift 
64026   ** it by.  If pSpace is already 8-byte aligned, nOff should be zero.
64027   */
64028   nOff = (8 - (SQLITE_PTR_TO_INT(pSpace) & 7)) & 7;
64029   nByte = ROUND8(sizeof(UnpackedRecord)) + sizeof(Mem)*(pKeyInfo->nField+1);
64030   if( nByte>szSpace+nOff ){
64031     p = (UnpackedRecord *)sqlite3DbMallocRaw(pKeyInfo->db, nByte);
64032     *ppFree = (char *)p;
64033     if( !p ) return 0;
64034   }else{
64035     p = (UnpackedRecord*)&pSpace[nOff];
64036     *ppFree = 0;
64037   }
64038 
64039   p->aMem = (Mem*)&((char*)p)[ROUND8(sizeof(UnpackedRecord))];
64040   assert( pKeyInfo->aSortOrder!=0 );
64041   p->pKeyInfo = pKeyInfo;
64042   p->nField = pKeyInfo->nField + 1;
64043   return p;
64044 }
64045 
64046 /*
64047 ** Given the nKey-byte encoding of a record in pKey[], populate the 
64048 ** UnpackedRecord structure indicated by the fourth argument with the
64049 ** contents of the decoded record.
64050 */ 
64051 SQLITE_PRIVATE void sqlite3VdbeRecordUnpack(
64052   KeyInfo *pKeyInfo,     /* Information about the record format */
64053   int nKey,              /* Size of the binary record */
64054   const void *pKey,      /* The binary record */
64055   UnpackedRecord *p      /* Populate this structure before returning. */
64056 ){
64057   const unsigned char *aKey = (const unsigned char *)pKey;
64058   int d; 
64059   u32 idx;                        /* Offset in aKey[] to read from */
64060   u16 u;                          /* Unsigned loop counter */
64061   u32 szHdr;
64062   Mem *pMem = p->aMem;
64063 
64064   p->flags = 0;
64065   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
64066   idx = getVarint32(aKey, szHdr);
64067   d = szHdr;
64068   u = 0;
64069   while( idx<szHdr && u<p->nField && d<=nKey ){
64070     u32 serial_type;
64071 
64072     idx += getVarint32(&aKey[idx], serial_type);
64073     pMem->enc = pKeyInfo->enc;
64074     pMem->db = pKeyInfo->db;
64075     /* pMem->flags = 0; // sqlite3VdbeSerialGet() will set this for us */
64076     pMem->zMalloc = 0;
64077     d += sqlite3VdbeSerialGet(&aKey[d], serial_type, pMem);
64078     pMem++;
64079     u++;
64080   }
64081   assert( u<=pKeyInfo->nField + 1 );
64082   p->nField = u;
64083 }
64084 
64085 /*
64086 ** This function compares the two table rows or index records
64087 ** specified by {nKey1, pKey1} and pPKey2.  It returns a negative, zero
64088 ** or positive integer if key1 is less than, equal to or 
64089 ** greater than key2.  The {nKey1, pKey1} key must be a blob
64090 ** created by th OP_MakeRecord opcode of the VDBE.  The pPKey2
64091 ** key must be a parsed key such as obtained from
64092 ** sqlite3VdbeParseRecord.
64093 **
64094 ** Key1 and Key2 do not have to contain the same number of fields.
64095 ** The key with fewer fields is usually compares less than the 
64096 ** longer key.  However if the UNPACKED_INCRKEY flags in pPKey2 is set
64097 ** and the common prefixes are equal, then key1 is less than key2.
64098 ** Or if the UNPACKED_MATCH_PREFIX flag is set and the prefixes are
64099 ** equal, then the keys are considered to be equal and
64100 ** the parts beyond the common prefix are ignored.
64101 */
64102 SQLITE_PRIVATE int sqlite3VdbeRecordCompare(
64103   int nKey1, const void *pKey1, /* Left key */
64104   UnpackedRecord *pPKey2        /* Right key */
64105 ){
64106   u32 d1;            /* Offset into aKey[] of next data element */
64107   u32 idx1;          /* Offset into aKey[] of next header element */
64108   u32 szHdr1;        /* Number of bytes in header */
64109   int i = 0;
64110   int rc = 0;
64111   const unsigned char *aKey1 = (const unsigned char *)pKey1;
64112   KeyInfo *pKeyInfo;
64113   Mem mem1;
64114 
64115   pKeyInfo = pPKey2->pKeyInfo;
64116   mem1.enc = pKeyInfo->enc;
64117   mem1.db = pKeyInfo->db;
64118   /* mem1.flags = 0;  // Will be initialized by sqlite3VdbeSerialGet() */
64119   VVA_ONLY( mem1.zMalloc = 0; ) /* Only needed by assert() statements */
64120 
64121   /* Compilers may complain that mem1.u.i is potentially uninitialized.
64122   ** We could initialize it, as shown here, to silence those complaints.
64123   ** But in fact, mem1.u.i will never actually be used uninitialized, and doing 
64124   ** the unnecessary initialization has a measurable negative performance
64125   ** impact, since this routine is a very high runner.  And so, we choose
64126   ** to ignore the compiler warnings and leave this variable uninitialized.
64127   */
64128   /*  mem1.u.i = 0;  // not needed, here to silence compiler warning */
64129   
64130   idx1 = getVarint32(aKey1, szHdr1);
64131   d1 = szHdr1;
64132   assert( pKeyInfo->nField+pKeyInfo->nXField>=pPKey2->nField || CORRUPT_DB );
64133   assert( pKeyInfo->aSortOrder!=0 );
64134   assert( pKeyInfo->nField>0 );
64135   assert( idx1<=szHdr1 || CORRUPT_DB );
64136   do{
64137     u32 serial_type1;
64138 
64139     /* Read the serial types for the next element in each key. */
64140     idx1 += getVarint32( aKey1+idx1, serial_type1 );
64141 
64142     /* Verify that there is enough key space remaining to avoid
64143     ** a buffer overread.  The "d1+serial_type1+2" subexpression will
64144     ** always be greater than or equal to the amount of required key space.
64145     ** Use that approximation to avoid the more expensive call to
64146     ** sqlite3VdbeSerialTypeLen() in the common case.
64147     */
64148     if( d1+serial_type1+2>(u32)nKey1
64149      && d1+sqlite3VdbeSerialTypeLen(serial_type1)>(u32)nKey1 
64150     ){
64151       break;
64152     }
64153 
64154     /* Extract the values to be compared.
64155     */
64156     d1 += sqlite3VdbeSerialGet(&aKey1[d1], serial_type1, &mem1);
64157 
64158     /* Do the comparison
64159     */
64160     rc = sqlite3MemCompare(&mem1, &pPKey2->aMem[i], pKeyInfo->aColl[i]);
64161     if( rc!=0 ){
64162       assert( mem1.zMalloc==0 );  /* See comment below */
64163       if( pKeyInfo->aSortOrder[i] ){
64164         rc = -rc;  /* Invert the result for DESC sort order. */
64165       }
64166       return rc;
64167     }
64168     i++;
64169   }while( idx1<szHdr1 && i<pPKey2->nField );
64170 
64171   /* No memory allocation is ever used on mem1.  Prove this using
64172   ** the following assert().  If the assert() fails, it indicates a
64173   ** memory leak and a need to call sqlite3VdbeMemRelease(&mem1).
64174   */
64175   assert( mem1.zMalloc==0 );
64176 
64177   /* rc==0 here means that one of the keys ran out of fields and
64178   ** all the fields up to that point were equal. If the UNPACKED_INCRKEY
64179   ** flag is set, then break the tie by treating key2 as larger.
64180   ** If the UPACKED_PREFIX_MATCH flag is set, then keys with common prefixes
64181   ** are considered to be equal.  Otherwise, the longer key is the 
64182   ** larger.  As it happens, the pPKey2 will always be the longer
64183   ** if there is a difference.
64184   */
64185   assert( rc==0 );
64186   if( pPKey2->flags & UNPACKED_INCRKEY ){
64187     rc = -1;
64188   }else if( pPKey2->flags & UNPACKED_PREFIX_MATCH ){
64189     /* Leave rc==0 */
64190   }else if( idx1<szHdr1 ){
64191     rc = 1;
64192   }
64193   return rc;
64194 }
64195  
64196 
64197 /*
64198 ** pCur points at an index entry created using the OP_MakeRecord opcode.
64199 ** Read the rowid (the last field in the record) and store it in *rowid.
64200 ** Return SQLITE_OK if everything works, or an error code otherwise.
64201 **
64202 ** pCur might be pointing to text obtained from a corrupt database file.
64203 ** So the content cannot be trusted.  Do appropriate checks on the content.
64204 */
64205 SQLITE_PRIVATE int sqlite3VdbeIdxRowid(sqlite3 *db, BtCursor *pCur, i64 *rowid){
64206   i64 nCellKey = 0;
64207   int rc;
64208   u32 szHdr;        /* Size of the header */
64209   u32 typeRowid;    /* Serial type of the rowid */
64210   u32 lenRowid;     /* Size of the rowid */
64211   Mem m, v;
64212 
64213   UNUSED_PARAMETER(db);
64214 
64215   /* Get the size of the index entry.  Only indices entries of less
64216   ** than 2GiB are support - anything large must be database corruption.
64217   ** Any corruption is detected in sqlite3BtreeParseCellPtr(), though, so
64218   ** this code can safely assume that nCellKey is 32-bits  
64219   */
64220   assert( sqlite3BtreeCursorIsValid(pCur) );
64221   VVA_ONLY(rc =) sqlite3BtreeKeySize(pCur, &nCellKey);
64222   assert( rc==SQLITE_OK );     /* pCur is always valid so KeySize cannot fail */
64223   assert( (nCellKey & SQLITE_MAX_U32)==(u64)nCellKey );
64224 
64225   /* Read in the complete content of the index entry */
64226   memset(&m, 0, sizeof(m));
64227   rc = sqlite3VdbeMemFromBtree(pCur, 0, (u32)nCellKey, 1, &m);
64228   if( rc ){
64229     return rc;
64230   }
64231 
64232   /* The index entry must begin with a header size */
64233   (void)getVarint32((u8*)m.z, szHdr);
64234   testcase( szHdr==3 );
64235   testcase( szHdr==m.n );
64236   if( unlikely(szHdr<3 || (int)szHdr>m.n) ){
64237     goto idx_rowid_corruption;
64238   }
64239 
64240   /* The last field of the index should be an integer - the ROWID.
64241   ** Verify that the last entry really is an integer. */
64242   (void)getVarint32((u8*)&m.z[szHdr-1], typeRowid);
64243   testcase( typeRowid==1 );
64244   testcase( typeRowid==2 );
64245   testcase( typeRowid==3 );
64246   testcase( typeRowid==4 );
64247   testcase( typeRowid==5 );
64248   testcase( typeRowid==6 );
64249   testcase( typeRowid==8 );
64250   testcase( typeRowid==9 );
64251   if( unlikely(typeRowid<1 || typeRowid>9 || typeRowid==7) ){
64252     goto idx_rowid_corruption;
64253   }
64254   lenRowid = sqlite3VdbeSerialTypeLen(typeRowid);
64255   testcase( (u32)m.n==szHdr+lenRowid );
64256   if( unlikely((u32)m.n<szHdr+lenRowid) ){
64257     goto idx_rowid_corruption;
64258   }
64259 
64260   /* Fetch the integer off the end of the index record */
64261   sqlite3VdbeSerialGet((u8*)&m.z[m.n-lenRowid], typeRowid, &v);
64262   *rowid = v.u.i;
64263   sqlite3VdbeMemRelease(&m);
64264   return SQLITE_OK;
64265 
64266   /* Jump here if database corruption is detected after m has been
64267   ** allocated.  Free the m object and return SQLITE_CORRUPT. */
64268 idx_rowid_corruption:
64269   testcase( m.zMalloc!=0 );
64270   sqlite3VdbeMemRelease(&m);
64271   return SQLITE_CORRUPT_BKPT;
64272 }
64273 
64274 /*
64275 ** Compare the key of the index entry that cursor pC is pointing to against
64276 ** the key string in pUnpacked.  Write into *pRes a number
64277 ** that is negative, zero, or positive if pC is less than, equal to,
64278 ** or greater than pUnpacked.  Return SQLITE_OK on success.
64279 **
64280 ** pUnpacked is either created without a rowid or is truncated so that it
64281 ** omits the rowid at the end.  The rowid at the end of the index entry
64282 ** is ignored as well.  Hence, this routine only compares the prefixes 
64283 ** of the keys prior to the final rowid, not the entire key.
64284 */
64285 SQLITE_PRIVATE int sqlite3VdbeIdxKeyCompare(
64286   VdbeCursor *pC,             /* The cursor to compare against */
64287   UnpackedRecord *pUnpacked,  /* Unpacked version of key to compare against */
64288   int *res                    /* Write the comparison result here */
64289 ){
64290   i64 nCellKey = 0;
64291   int rc;
64292   BtCursor *pCur = pC->pCursor;
64293   Mem m;
64294 
64295   assert( sqlite3BtreeCursorIsValid(pCur) );
64296   VVA_ONLY(rc =) sqlite3BtreeKeySize(pCur, &nCellKey);
64297   assert( rc==SQLITE_OK );    /* pCur is always valid so KeySize cannot fail */
64298   /* nCellKey will always be between 0 and 0xffffffff because of the say
64299   ** that btreeParseCellPtr() and sqlite3GetVarint32() are implemented */
64300   if( nCellKey<=0 || nCellKey>0x7fffffff ){
64301     *res = 0;
64302     return SQLITE_CORRUPT_BKPT;
64303   }
64304   memset(&m, 0, sizeof(m));
64305   rc = sqlite3VdbeMemFromBtree(pC->pCursor, 0, (u32)nCellKey, 1, &m);
64306   if( rc ){
64307     return rc;
64308   }
64309   assert( pUnpacked->flags & UNPACKED_PREFIX_MATCH );
64310   *res = sqlite3VdbeRecordCompare(m.n, m.z, pUnpacked);
64311   sqlite3VdbeMemRelease(&m);
64312   return SQLITE_OK;
64313 }
64314 
64315 /*
64316 ** This routine sets the value to be returned by subsequent calls to
64317 ** sqlite3_changes() on the database handle 'db'. 
64318 */
64319 SQLITE_PRIVATE void sqlite3VdbeSetChanges(sqlite3 *db, int nChange){
64320   assert( sqlite3_mutex_held(db->mutex) );
64321   db->nChange = nChange;
64322   db->nTotalChange += nChange;
64323 }
64324 
64325 /*
64326 ** Set a flag in the vdbe to update the change counter when it is finalised
64327 ** or reset.
64328 */
64329 SQLITE_PRIVATE void sqlite3VdbeCountChanges(Vdbe *v){
64330   v->changeCntOn = 1;
64331 }
64332 
64333 /*
64334 ** Mark every prepared statement associated with a database connection
64335 ** as expired.
64336 **
64337 ** An expired statement means that recompilation of the statement is
64338 ** recommend.  Statements expire when things happen that make their
64339 ** programs obsolete.  Removing user-defined functions or collating
64340 ** sequences, or changing an authorization function are the types of
64341 ** things that make prepared statements obsolete.
64342 */
64343 SQLITE_PRIVATE void sqlite3ExpirePreparedStatements(sqlite3 *db){
64344   Vdbe *p;
64345   for(p = db->pVdbe; p; p=p->pNext){
64346     p->expired = 1;
64347   }
64348 }
64349 
64350 /*
64351 ** Return the database associated with the Vdbe.
64352 */
64353 SQLITE_PRIVATE sqlite3 *sqlite3VdbeDb(Vdbe *v){
64354   return v->db;
64355 }
64356 
64357 /*
64358 ** Return a pointer to an sqlite3_value structure containing the value bound
64359 ** parameter iVar of VM v. Except, if the value is an SQL NULL, return 
64360 ** 0 instead. Unless it is NULL, apply affinity aff (one of the SQLITE_AFF_*
64361 ** constants) to the value before returning it.
64362 **
64363 ** The returned value must be freed by the caller using sqlite3ValueFree().
64364 */
64365 SQLITE_PRIVATE sqlite3_value *sqlite3VdbeGetBoundValue(Vdbe *v, int iVar, u8 aff){
64366   assert( iVar>0 );
64367   if( v ){
64368     Mem *pMem = &v->aVar[iVar-1];
64369     if( 0==(pMem->flags & MEM_Null) ){
64370       sqlite3_value *pRet = sqlite3ValueNew(v->db);
64371       if( pRet ){
64372         sqlite3VdbeMemCopy((Mem *)pRet, pMem);
64373         sqlite3ValueApplyAffinity(pRet, aff, SQLITE_UTF8);
64374         sqlite3VdbeMemStoreType((Mem *)pRet);
64375       }
64376       return pRet;
64377     }
64378   }
64379   return 0;
64380 }
64381 
64382 /*
64383 ** Configure SQL variable iVar so that binding a new value to it signals
64384 ** to sqlite3_reoptimize() that re-preparing the statement may result
64385 ** in a better query plan.
64386 */
64387 SQLITE_PRIVATE void sqlite3VdbeSetVarmask(Vdbe *v, int iVar){
64388   assert( iVar>0 );
64389   if( iVar>32 ){
64390     v->expmask = 0xffffffff;
64391   }else{
64392     v->expmask |= ((u32)1 << (iVar-1));
64393   }
64394 }
64395 
64396 #ifndef SQLITE_OMIT_VIRTUALTABLE
64397 /*
64398 ** Transfer error message text from an sqlite3_vtab.zErrMsg (text stored
64399 ** in memory obtained from sqlite3_malloc) into a Vdbe.zErrMsg (text stored
64400 ** in memory obtained from sqlite3DbMalloc).
64401 */
64402 SQLITE_PRIVATE void sqlite3VtabImportErrmsg(Vdbe *p, sqlite3_vtab *pVtab){
64403   sqlite3 *db = p->db;
64404   sqlite3DbFree(db, p->zErrMsg);
64405   p->zErrMsg = sqlite3DbStrDup(db, pVtab->zErrMsg);
64406   sqlite3_free(pVtab->zErrMsg);
64407   pVtab->zErrMsg = 0;
64408 }
64409 #endif /* SQLITE_OMIT_VIRTUALTABLE */
64410 
64411 /************** End of vdbeaux.c *********************************************/
64412 /************** Begin file vdbeapi.c *****************************************/
64413 /*
64414 ** 2004 May 26
64415 **
64416 ** The author disclaims copyright to this source code.  In place of
64417 ** a legal notice, here is a blessing:
64418 **
64419 **    May you do good and not evil.
64420 **    May you find forgiveness for yourself and forgive others.
64421 **    May you share freely, never taking more than you give.
64422 **
64423 *************************************************************************
64424 **
64425 ** This file contains code use to implement APIs that are part of the
64426 ** VDBE.
64427 */
64428 
64429 #ifndef SQLITE_OMIT_DEPRECATED
64430 /*
64431 ** Return TRUE (non-zero) of the statement supplied as an argument needs
64432 ** to be recompiled.  A statement needs to be recompiled whenever the
64433 ** execution environment changes in a way that would alter the program
64434 ** that sqlite3_prepare() generates.  For example, if new functions or
64435 ** collating sequences are registered or if an authorizer function is
64436 ** added or changed.
64437 */
64438 SQLITE_API int sqlite3_expired(sqlite3_stmt *pStmt){
64439   Vdbe *p = (Vdbe*)pStmt;
64440   return p==0 || p->expired;
64441 }
64442 #endif
64443 
64444 /*
64445 ** Check on a Vdbe to make sure it has not been finalized.  Log
64446 ** an error and return true if it has been finalized (or is otherwise
64447 ** invalid).  Return false if it is ok.
64448 */
64449 static int vdbeSafety(Vdbe *p){
64450   if( p->db==0 ){
64451     sqlite3_log(SQLITE_MISUSE, "API called with finalized prepared statement");
64452     return 1;
64453   }else{
64454     return 0;
64455   }
64456 }
64457 static int vdbeSafetyNotNull(Vdbe *p){
64458   if( p==0 ){
64459     sqlite3_log(SQLITE_MISUSE, "API called with NULL prepared statement");
64460     return 1;
64461   }else{
64462     return vdbeSafety(p);
64463   }
64464 }
64465 
64466 /*
64467 ** The following routine destroys a virtual machine that is created by
64468 ** the sqlite3_compile() routine. The integer returned is an SQLITE_
64469 ** success/failure code that describes the result of executing the virtual
64470 ** machine.
64471 **
64472 ** This routine sets the error code and string returned by
64473 ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16().
64474 */
64475 SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt){
64476   int rc;
64477   if( pStmt==0 ){
64478     /* IMPLEMENTATION-OF: R-57228-12904 Invoking sqlite3_finalize() on a NULL
64479     ** pointer is a harmless no-op. */
64480     rc = SQLITE_OK;
64481   }else{
64482     Vdbe *v = (Vdbe*)pStmt;
64483     sqlite3 *db = v->db;
64484     if( vdbeSafety(v) ) return SQLITE_MISUSE_BKPT;
64485     sqlite3_mutex_enter(db->mutex);
64486     rc = sqlite3VdbeFinalize(v);
64487     rc = sqlite3ApiExit(db, rc);
64488     sqlite3LeaveMutexAndCloseZombie(db);
64489   }
64490   return rc;
64491 }
64492 
64493 /*
64494 ** Terminate the current execution of an SQL statement and reset it
64495 ** back to its starting state so that it can be reused. A success code from
64496 ** the prior execution is returned.
64497 **
64498 ** This routine sets the error code and string returned by
64499 ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16().
64500 */
64501 SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt){
64502   int rc;
64503   if( pStmt==0 ){
64504     rc = SQLITE_OK;
64505   }else{
64506     Vdbe *v = (Vdbe*)pStmt;
64507     sqlite3_mutex_enter(v->db->mutex);
64508     rc = sqlite3VdbeReset(v);
64509     sqlite3VdbeRewind(v);
64510     assert( (rc & (v->db->errMask))==rc );
64511     rc = sqlite3ApiExit(v->db, rc);
64512     sqlite3_mutex_leave(v->db->mutex);
64513   }
64514   return rc;
64515 }
64516 
64517 /*
64518 ** Set all the parameters in the compiled SQL statement to NULL.
64519 */
64520 SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt *pStmt){
64521   int i;
64522   int rc = SQLITE_OK;
64523   Vdbe *p = (Vdbe*)pStmt;
64524 #if SQLITE_THREADSAFE
64525   sqlite3_mutex *mutex = ((Vdbe*)pStmt)->db->mutex;
64526 #endif
64527   sqlite3_mutex_enter(mutex);
64528   for(i=0; i<p->nVar; i++){
64529     sqlite3VdbeMemRelease(&p->aVar[i]);
64530     p->aVar[i].flags = MEM_Null;
64531   }
64532   if( p->isPrepareV2 && p->expmask ){
64533     p->expired = 1;
64534   }
64535   sqlite3_mutex_leave(mutex);
64536   return rc;
64537 }
64538 
64539 
64540 /**************************** sqlite3_value_  *******************************
64541 ** The following routines extract information from a Mem or sqlite3_value
64542 ** structure.
64543 */
64544 SQLITE_API const void *sqlite3_value_blob(sqlite3_value *pVal){
64545   Mem *p = (Mem*)pVal;
64546   if( p->flags & (MEM_Blob|MEM_Str) ){
64547     sqlite3VdbeMemExpandBlob(p);
64548     p->flags &= ~MEM_Str;
64549     p->flags |= MEM_Blob;
64550     return p->n ? p->z : 0;
64551   }else{
64552     return sqlite3_value_text(pVal);
64553   }
64554 }
64555 SQLITE_API int sqlite3_value_bytes(sqlite3_value *pVal){
64556   return sqlite3ValueBytes(pVal, SQLITE_UTF8);
64557 }
64558 SQLITE_API int sqlite3_value_bytes16(sqlite3_value *pVal){
64559   return sqlite3ValueBytes(pVal, SQLITE_UTF16NATIVE);
64560 }
64561 SQLITE_API double sqlite3_value_double(sqlite3_value *pVal){
64562   return sqlite3VdbeRealValue((Mem*)pVal);
64563 }
64564 SQLITE_API int sqlite3_value_int(sqlite3_value *pVal){
64565   return (int)sqlite3VdbeIntValue((Mem*)pVal);
64566 }
64567 SQLITE_API sqlite_int64 sqlite3_value_int64(sqlite3_value *pVal){
64568   return sqlite3VdbeIntValue((Mem*)pVal);
64569 }
64570 SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value *pVal){
64571   return (const unsigned char *)sqlite3ValueText(pVal, SQLITE_UTF8);
64572 }
64573 #ifndef SQLITE_OMIT_UTF16
64574 SQLITE_API const void *sqlite3_value_text16(sqlite3_value* pVal){
64575   return sqlite3ValueText(pVal, SQLITE_UTF16NATIVE);
64576 }
64577 SQLITE_API const void *sqlite3_value_text16be(sqlite3_value *pVal){
64578   return sqlite3ValueText(pVal, SQLITE_UTF16BE);
64579 }
64580 SQLITE_API const void *sqlite3_value_text16le(sqlite3_value *pVal){
64581   return sqlite3ValueText(pVal, SQLITE_UTF16LE);
64582 }
64583 #endif /* SQLITE_OMIT_UTF16 */
64584 SQLITE_API int sqlite3_value_type(sqlite3_value* pVal){
64585   return pVal->type;
64586 }
64587 
64588 /**************************** sqlite3_result_  *******************************
64589 ** The following routines are used by user-defined functions to specify
64590 ** the function result.
64591 **
64592 ** The setStrOrError() funtion calls sqlite3VdbeMemSetStr() to store the
64593 ** result as a string or blob but if the string or blob is too large, it
64594 ** then sets the error code to SQLITE_TOOBIG
64595 */
64596 static void setResultStrOrError(
64597   sqlite3_context *pCtx,  /* Function context */
64598   const char *z,          /* String pointer */
64599   int n,                  /* Bytes in string, or negative */
64600   u8 enc,                 /* Encoding of z.  0 for BLOBs */
64601   void (*xDel)(void*)     /* Destructor function */
64602 ){
64603   if( sqlite3VdbeMemSetStr(&pCtx->s, z, n, enc, xDel)==SQLITE_TOOBIG ){
64604     sqlite3_result_error_toobig(pCtx);
64605   }
64606 }
64607 SQLITE_API void sqlite3_result_blob(
64608   sqlite3_context *pCtx, 
64609   const void *z, 
64610   int n, 
64611   void (*xDel)(void *)
64612 ){
64613   assert( n>=0 );
64614   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64615   setResultStrOrError(pCtx, z, n, 0, xDel);
64616 }
64617 SQLITE_API void sqlite3_result_double(sqlite3_context *pCtx, double rVal){
64618   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64619   sqlite3VdbeMemSetDouble(&pCtx->s, rVal);
64620 }
64621 SQLITE_API void sqlite3_result_error(sqlite3_context *pCtx, const char *z, int n){
64622   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64623   pCtx->isError = SQLITE_ERROR;
64624   pCtx->fErrorOrAux = 1;
64625   sqlite3VdbeMemSetStr(&pCtx->s, z, n, SQLITE_UTF8, SQLITE_TRANSIENT);
64626 }
64627 #ifndef SQLITE_OMIT_UTF16
64628 SQLITE_API void sqlite3_result_error16(sqlite3_context *pCtx, const void *z, int n){
64629   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64630   pCtx->isError = SQLITE_ERROR;
64631   pCtx->fErrorOrAux = 1;
64632   sqlite3VdbeMemSetStr(&pCtx->s, z, n, SQLITE_UTF16NATIVE, SQLITE_TRANSIENT);
64633 }
64634 #endif
64635 SQLITE_API void sqlite3_result_int(sqlite3_context *pCtx, int iVal){
64636   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64637   sqlite3VdbeMemSetInt64(&pCtx->s, (i64)iVal);
64638 }
64639 SQLITE_API void sqlite3_result_int64(sqlite3_context *pCtx, i64 iVal){
64640   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64641   sqlite3VdbeMemSetInt64(&pCtx->s, iVal);
64642 }
64643 SQLITE_API void sqlite3_result_null(sqlite3_context *pCtx){
64644   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64645   sqlite3VdbeMemSetNull(&pCtx->s);
64646 }
64647 SQLITE_API void sqlite3_result_text(
64648   sqlite3_context *pCtx, 
64649   const char *z, 
64650   int n,
64651   void (*xDel)(void *)
64652 ){
64653   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64654   setResultStrOrError(pCtx, z, n, SQLITE_UTF8, xDel);
64655 }
64656 #ifndef SQLITE_OMIT_UTF16
64657 SQLITE_API void sqlite3_result_text16(
64658   sqlite3_context *pCtx, 
64659   const void *z, 
64660   int n, 
64661   void (*xDel)(void *)
64662 ){
64663   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64664   setResultStrOrError(pCtx, z, n, SQLITE_UTF16NATIVE, xDel);
64665 }
64666 SQLITE_API void sqlite3_result_text16be(
64667   sqlite3_context *pCtx, 
64668   const void *z, 
64669   int n, 
64670   void (*xDel)(void *)
64671 ){
64672   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64673   setResultStrOrError(pCtx, z, n, SQLITE_UTF16BE, xDel);
64674 }
64675 SQLITE_API void sqlite3_result_text16le(
64676   sqlite3_context *pCtx, 
64677   const void *z, 
64678   int n, 
64679   void (*xDel)(void *)
64680 ){
64681   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64682   setResultStrOrError(pCtx, z, n, SQLITE_UTF16LE, xDel);
64683 }
64684 #endif /* SQLITE_OMIT_UTF16 */
64685 SQLITE_API void sqlite3_result_value(sqlite3_context *pCtx, sqlite3_value *pValue){
64686   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64687   sqlite3VdbeMemCopy(&pCtx->s, pValue);
64688 }
64689 SQLITE_API void sqlite3_result_zeroblob(sqlite3_context *pCtx, int n){
64690   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64691   sqlite3VdbeMemSetZeroBlob(&pCtx->s, n);
64692 }
64693 SQLITE_API void sqlite3_result_error_code(sqlite3_context *pCtx, int errCode){
64694   pCtx->isError = errCode;
64695   pCtx->fErrorOrAux = 1;
64696   if( pCtx->s.flags & MEM_Null ){
64697     sqlite3VdbeMemSetStr(&pCtx->s, sqlite3ErrStr(errCode), -1, 
64698                          SQLITE_UTF8, SQLITE_STATIC);
64699   }
64700 }
64701 
64702 /* Force an SQLITE_TOOBIG error. */
64703 SQLITE_API void sqlite3_result_error_toobig(sqlite3_context *pCtx){
64704   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64705   pCtx->isError = SQLITE_TOOBIG;
64706   pCtx->fErrorOrAux = 1;
64707   sqlite3VdbeMemSetStr(&pCtx->s, "string or blob too big", -1, 
64708                        SQLITE_UTF8, SQLITE_STATIC);
64709 }
64710 
64711 /* An SQLITE_NOMEM error. */
64712 SQLITE_API void sqlite3_result_error_nomem(sqlite3_context *pCtx){
64713   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64714   sqlite3VdbeMemSetNull(&pCtx->s);
64715   pCtx->isError = SQLITE_NOMEM;
64716   pCtx->fErrorOrAux = 1;
64717   pCtx->s.db->mallocFailed = 1;
64718 }
64719 
64720 /*
64721 ** This function is called after a transaction has been committed. It 
64722 ** invokes callbacks registered with sqlite3_wal_hook() as required.
64723 */
64724 static int doWalCallbacks(sqlite3 *db){
64725   int rc = SQLITE_OK;
64726 #ifndef SQLITE_OMIT_WAL
64727   int i;
64728   for(i=0; i<db->nDb; i++){
64729     Btree *pBt = db->aDb[i].pBt;
64730     if( pBt ){
64731       int nEntry = sqlite3PagerWalCallback(sqlite3BtreePager(pBt));
64732       if( db->xWalCallback && nEntry>0 && rc==SQLITE_OK ){
64733         rc = db->xWalCallback(db->pWalArg, db, db->aDb[i].zName, nEntry);
64734       }
64735     }
64736   }
64737 #endif
64738   return rc;
64739 }
64740 
64741 /*
64742 ** Execute the statement pStmt, either until a row of data is ready, the
64743 ** statement is completely executed or an error occurs.
64744 **
64745 ** This routine implements the bulk of the logic behind the sqlite_step()
64746 ** API.  The only thing omitted is the automatic recompile if a 
64747 ** schema change has occurred.  That detail is handled by the
64748 ** outer sqlite3_step() wrapper procedure.
64749 */
64750 static int sqlite3Step(Vdbe *p){
64751   sqlite3 *db;
64752   int rc;
64753 
64754   assert(p);
64755   if( p->magic!=VDBE_MAGIC_RUN ){
64756     /* We used to require that sqlite3_reset() be called before retrying
64757     ** sqlite3_step() after any error or after SQLITE_DONE.  But beginning
64758     ** with version 3.7.0, we changed this so that sqlite3_reset() would
64759     ** be called automatically instead of throwing the SQLITE_MISUSE error.
64760     ** This "automatic-reset" change is not technically an incompatibility, 
64761     ** since any application that receives an SQLITE_MISUSE is broken by
64762     ** definition.
64763     **
64764     ** Nevertheless, some published applications that were originally written
64765     ** for version 3.6.23 or earlier do in fact depend on SQLITE_MISUSE 
64766     ** returns, and those were broken by the automatic-reset change.  As a
64767     ** a work-around, the SQLITE_OMIT_AUTORESET compile-time restores the
64768     ** legacy behavior of returning SQLITE_MISUSE for cases where the 
64769     ** previous sqlite3_step() returned something other than a SQLITE_LOCKED
64770     ** or SQLITE_BUSY error.
64771     */
64772 #ifdef SQLITE_OMIT_AUTORESET
64773     if( p->rc==SQLITE_BUSY || p->rc==SQLITE_LOCKED ){
64774       sqlite3_reset((sqlite3_stmt*)p);
64775     }else{
64776       return SQLITE_MISUSE_BKPT;
64777     }
64778 #else
64779     sqlite3_reset((sqlite3_stmt*)p);
64780 #endif
64781   }
64782 
64783   /* Check that malloc() has not failed. If it has, return early. */
64784   db = p->db;
64785   if( db->mallocFailed ){
64786     p->rc = SQLITE_NOMEM;
64787     return SQLITE_NOMEM;
64788   }
64789 
64790   if( p->pc<=0 && p->expired ){
64791     p->rc = SQLITE_SCHEMA;
64792     rc = SQLITE_ERROR;
64793     goto end_of_step;
64794   }
64795   if( p->pc<0 ){
64796     /* If there are no other statements currently running, then
64797     ** reset the interrupt flag.  This prevents a call to sqlite3_interrupt
64798     ** from interrupting a statement that has not yet started.
64799     */
64800     if( db->nVdbeActive==0 ){
64801       db->u1.isInterrupted = 0;
64802     }
64803 
64804     assert( db->nVdbeWrite>0 || db->autoCommit==0 
64805         || (db->nDeferredCons==0 && db->nDeferredImmCons==0)
64806     );
64807 
64808 #ifndef SQLITE_OMIT_TRACE
64809     if( db->xProfile && !db->init.busy ){
64810       sqlite3OsCurrentTimeInt64(db->pVfs, &p->startTime);
64811     }
64812 #endif
64813 
64814     db->nVdbeActive++;
64815     if( p->readOnly==0 ) db->nVdbeWrite++;
64816     if( p->bIsReader ) db->nVdbeRead++;
64817     p->pc = 0;
64818   }
64819 #ifndef SQLITE_OMIT_EXPLAIN
64820   if( p->explain ){
64821     rc = sqlite3VdbeList(p);
64822   }else
64823 #endif /* SQLITE_OMIT_EXPLAIN */
64824   {
64825     db->nVdbeExec++;
64826     rc = sqlite3VdbeExec(p);
64827     db->nVdbeExec--;
64828   }
64829 
64830 #ifndef SQLITE_OMIT_TRACE
64831   /* Invoke the profile callback if there is one
64832   */
64833   if( rc!=SQLITE_ROW && db->xProfile && !db->init.busy && p->zSql ){
64834     sqlite3_int64 iNow;
64835     sqlite3OsCurrentTimeInt64(db->pVfs, &iNow);
64836     db->xProfile(db->pProfileArg, p->zSql, (iNow - p->startTime)*1000000);
64837   }
64838 #endif
64839 
64840   if( rc==SQLITE_DONE ){
64841     assert( p->rc==SQLITE_OK );
64842     p->rc = doWalCallbacks(db);
64843     if( p->rc!=SQLITE_OK ){
64844       rc = SQLITE_ERROR;
64845     }
64846   }
64847 
64848   db->errCode = rc;
64849   if( SQLITE_NOMEM==sqlite3ApiExit(p->db, p->rc) ){
64850     p->rc = SQLITE_NOMEM;
64851   }
64852 end_of_step:
64853   /* At this point local variable rc holds the value that should be 
64854   ** returned if this statement was compiled using the legacy 
64855   ** sqlite3_prepare() interface. According to the docs, this can only
64856   ** be one of the values in the first assert() below. Variable p->rc 
64857   ** contains the value that would be returned if sqlite3_finalize() 
64858   ** were called on statement p.
64859   */
64860   assert( rc==SQLITE_ROW  || rc==SQLITE_DONE   || rc==SQLITE_ERROR 
64861        || rc==SQLITE_BUSY || rc==SQLITE_MISUSE
64862   );
64863   assert( p->rc!=SQLITE_ROW && p->rc!=SQLITE_DONE );
64864   if( p->isPrepareV2 && rc!=SQLITE_ROW && rc!=SQLITE_DONE ){
64865     /* If this statement was prepared using sqlite3_prepare_v2(), and an
64866     ** error has occurred, then return the error code in p->rc to the
64867     ** caller. Set the error code in the database handle to the same value.
64868     */ 
64869     rc = sqlite3VdbeTransferError(p);
64870   }
64871   return (rc&db->errMask);
64872 }
64873 
64874 /*
64875 ** This is the top-level implementation of sqlite3_step().  Call
64876 ** sqlite3Step() to do most of the work.  If a schema error occurs,
64877 ** call sqlite3Reprepare() and try again.
64878 */
64879 SQLITE_API int sqlite3_step(sqlite3_stmt *pStmt){
64880   int rc = SQLITE_OK;      /* Result from sqlite3Step() */
64881   int rc2 = SQLITE_OK;     /* Result from sqlite3Reprepare() */
64882   Vdbe *v = (Vdbe*)pStmt;  /* the prepared statement */
64883   int cnt = 0;             /* Counter to prevent infinite loop of reprepares */
64884   sqlite3 *db;             /* The database connection */
64885 
64886   if( vdbeSafetyNotNull(v) ){
64887     return SQLITE_MISUSE_BKPT;
64888   }
64889   db = v->db;
64890   sqlite3_mutex_enter(db->mutex);
64891   v->doingRerun = 0;
64892   while( (rc = sqlite3Step(v))==SQLITE_SCHEMA
64893          && cnt++ < SQLITE_MAX_SCHEMA_RETRY
64894          && (rc2 = rc = sqlite3Reprepare(v))==SQLITE_OK ){
64895     sqlite3_reset(pStmt);
64896     v->doingRerun = 1;
64897     assert( v->expired==0 );
64898   }
64899   if( rc2!=SQLITE_OK && ALWAYS(v->isPrepareV2) && ALWAYS(db->pErr) ){
64900     /* This case occurs after failing to recompile an sql statement. 
64901     ** The error message from the SQL compiler has already been loaded 
64902     ** into the database handle. This block copies the error message 
64903     ** from the database handle into the statement and sets the statement
64904     ** program counter to 0 to ensure that when the statement is 
64905     ** finalized or reset the parser error message is available via
64906     ** sqlite3_errmsg() and sqlite3_errcode().
64907     */
64908     const char *zErr = (const char *)sqlite3_value_text(db->pErr); 
64909     sqlite3DbFree(db, v->zErrMsg);
64910     if( !db->mallocFailed ){
64911       v->zErrMsg = sqlite3DbStrDup(db, zErr);
64912       v->rc = rc2;
64913     } else {
64914       v->zErrMsg = 0;
64915       v->rc = rc = SQLITE_NOMEM;
64916     }
64917   }
64918   rc = sqlite3ApiExit(db, rc);
64919   sqlite3_mutex_leave(db->mutex);
64920   return rc;
64921 }
64922 
64923 
64924 /*
64925 ** Extract the user data from a sqlite3_context structure and return a
64926 ** pointer to it.
64927 */
64928 SQLITE_API void *sqlite3_user_data(sqlite3_context *p){
64929   assert( p && p->pFunc );
64930   return p->pFunc->pUserData;
64931 }
64932 
64933 /*
64934 ** Extract the user data from a sqlite3_context structure and return a
64935 ** pointer to it.
64936 **
64937 ** IMPLEMENTATION-OF: R-46798-50301 The sqlite3_context_db_handle() interface
64938 ** returns a copy of the pointer to the database connection (the 1st
64939 ** parameter) of the sqlite3_create_function() and
64940 ** sqlite3_create_function16() routines that originally registered the
64941 ** application defined function.
64942 */
64943 SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context *p){
64944   assert( p && p->pFunc );
64945   return p->s.db;
64946 }
64947 
64948 /*
64949 ** Return the current time for a statement
64950 */
64951 SQLITE_PRIVATE sqlite3_int64 sqlite3StmtCurrentTime(sqlite3_context *p){
64952   Vdbe *v = p->pVdbe;
64953   int rc;
64954   if( v->iCurrentTime==0 ){
64955     rc = sqlite3OsCurrentTimeInt64(p->s.db->pVfs, &v->iCurrentTime);
64956     if( rc ) v->iCurrentTime = 0;
64957   }
64958   return v->iCurrentTime;
64959 }
64960 
64961 /*
64962 ** The following is the implementation of an SQL function that always
64963 ** fails with an error message stating that the function is used in the
64964 ** wrong context.  The sqlite3_overload_function() API might construct
64965 ** SQL function that use this routine so that the functions will exist
64966 ** for name resolution but are actually overloaded by the xFindFunction
64967 ** method of virtual tables.
64968 */
64969 SQLITE_PRIVATE void sqlite3InvalidFunction(
64970   sqlite3_context *context,  /* The function calling context */
64971   int NotUsed,               /* Number of arguments to the function */
64972   sqlite3_value **NotUsed2   /* Value of each argument */
64973 ){
64974   const char *zName = context->pFunc->zName;
64975   char *zErr;
64976   UNUSED_PARAMETER2(NotUsed, NotUsed2);
64977   zErr = sqlite3_mprintf(
64978       "unable to use function %s in the requested context", zName);
64979   sqlite3_result_error(context, zErr, -1);
64980   sqlite3_free(zErr);
64981 }
64982 
64983 /*
64984 ** Allocate or return the aggregate context for a user function.  A new
64985 ** context is allocated on the first call.  Subsequent calls return the
64986 ** same context that was returned on prior calls.
64987 */
64988 SQLITE_API void *sqlite3_aggregate_context(sqlite3_context *p, int nByte){
64989   Mem *pMem;
64990   assert( p && p->pFunc && p->pFunc->xStep );
64991   assert( sqlite3_mutex_held(p->s.db->mutex) );
64992   pMem = p->pMem;
64993   testcase( nByte<0 );
64994   if( (pMem->flags & MEM_Agg)==0 ){
64995     if( nByte<=0 ){
64996       sqlite3VdbeMemReleaseExternal(pMem);
64997       pMem->flags = MEM_Null;
64998       pMem->z = 0;
64999     }else{
65000       sqlite3VdbeMemGrow(pMem, nByte, 0);
65001       pMem->flags = MEM_Agg;
65002       pMem->u.pDef = p->pFunc;
65003       if( pMem->z ){
65004         memset(pMem->z, 0, nByte);
65005       }
65006     }
65007   }
65008   return (void*)pMem->z;
65009 }
65010 
65011 /*
65012 ** Return the auxilary data pointer, if any, for the iArg'th argument to
65013 ** the user-function defined by pCtx.
65014 */
65015 SQLITE_API void *sqlite3_get_auxdata(sqlite3_context *pCtx, int iArg){
65016   AuxData *pAuxData;
65017 
65018   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
65019   for(pAuxData=pCtx->pVdbe->pAuxData; pAuxData; pAuxData=pAuxData->pNext){
65020     if( pAuxData->iOp==pCtx->iOp && pAuxData->iArg==iArg ) break;
65021   }
65022 
65023   return (pAuxData ? pAuxData->pAux : 0);
65024 }
65025 
65026 /*
65027 ** Set the auxilary data pointer and delete function, for the iArg'th
65028 ** argument to the user-function defined by pCtx. Any previous value is
65029 ** deleted by calling the delete function specified when it was set.
65030 */
65031 SQLITE_API void sqlite3_set_auxdata(
65032   sqlite3_context *pCtx, 
65033   int iArg, 
65034   void *pAux, 
65035   void (*xDelete)(void*)
65036 ){
65037   AuxData *pAuxData;
65038   Vdbe *pVdbe = pCtx->pVdbe;
65039 
65040   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
65041   if( iArg<0 ) goto failed;
65042 
65043   for(pAuxData=pVdbe->pAuxData; pAuxData; pAuxData=pAuxData->pNext){
65044     if( pAuxData->iOp==pCtx->iOp && pAuxData->iArg==iArg ) break;
65045   }
65046   if( pAuxData==0 ){
65047     pAuxData = sqlite3DbMallocZero(pVdbe->db, sizeof(AuxData));
65048     if( !pAuxData ) goto failed;
65049     pAuxData->iOp = pCtx->iOp;
65050     pAuxData->iArg = iArg;
65051     pAuxData->pNext = pVdbe->pAuxData;
65052     pVdbe->pAuxData = pAuxData;
65053     if( pCtx->fErrorOrAux==0 ){
65054       pCtx->isError = 0;
65055       pCtx->fErrorOrAux = 1;
65056     }
65057   }else if( pAuxData->xDelete ){
65058     pAuxData->xDelete(pAuxData->pAux);
65059   }
65060 
65061   pAuxData->pAux = pAux;
65062   pAuxData->xDelete = xDelete;
65063   return;
65064 
65065 failed:
65066   if( xDelete ){
65067     xDelete(pAux);
65068   }
65069 }
65070 
65071 #ifndef SQLITE_OMIT_DEPRECATED
65072 /*
65073 ** Return the number of times the Step function of a aggregate has been 
65074 ** called.
65075 **
65076 ** This function is deprecated.  Do not use it for new code.  It is
65077 ** provide only to avoid breaking legacy code.  New aggregate function
65078 ** implementations should keep their own counts within their aggregate
65079 ** context.
65080 */
65081 SQLITE_API int sqlite3_aggregate_count(sqlite3_context *p){
65082   assert( p && p->pMem && p->pFunc && p->pFunc->xStep );
65083   return p->pMem->n;
65084 }
65085 #endif
65086 
65087 /*
65088 ** Return the number of columns in the result set for the statement pStmt.
65089 */
65090 SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt){
65091   Vdbe *pVm = (Vdbe *)pStmt;
65092   return pVm ? pVm->nResColumn : 0;
65093 }
65094 
65095 /*
65096 ** Return the number of values available from the current row of the
65097 ** currently executing statement pStmt.
65098 */
65099 SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt){
65100   Vdbe *pVm = (Vdbe *)pStmt;
65101   if( pVm==0 || pVm->pResultSet==0 ) return 0;
65102   return pVm->nResColumn;
65103 }
65104 
65105 
65106 /*
65107 ** Check to see if column iCol of the given statement is valid.  If
65108 ** it is, return a pointer to the Mem for the value of that column.
65109 ** If iCol is not valid, return a pointer to a Mem which has a value
65110 ** of NULL.
65111 */
65112 static Mem *columnMem(sqlite3_stmt *pStmt, int i){
65113   Vdbe *pVm;
65114   Mem *pOut;
65115 
65116   pVm = (Vdbe *)pStmt;
65117   if( pVm && pVm->pResultSet!=0 && i<pVm->nResColumn && i>=0 ){
65118     sqlite3_mutex_enter(pVm->db->mutex);
65119     pOut = &pVm->pResultSet[i];
65120   }else{
65121     /* If the value passed as the second argument is out of range, return
65122     ** a pointer to the following static Mem object which contains the
65123     ** value SQL NULL. Even though the Mem structure contains an element
65124     ** of type i64, on certain architectures (x86) with certain compiler
65125     ** switches (-Os), gcc may align this Mem object on a 4-byte boundary
65126     ** instead of an 8-byte one. This all works fine, except that when
65127     ** running with SQLITE_DEBUG defined the SQLite code sometimes assert()s
65128     ** that a Mem structure is located on an 8-byte boundary. To prevent
65129     ** these assert()s from failing, when building with SQLITE_DEBUG defined
65130     ** using gcc, we force nullMem to be 8-byte aligned using the magical
65131     ** __attribute__((aligned(8))) macro.  */
65132     static const Mem nullMem 
65133 #if defined(SQLITE_DEBUG) && defined(__GNUC__)
65134       __attribute__((aligned(8))) 
65135 #endif
65136       = {0, "", (double)0, {0}, 0, MEM_Null, SQLITE_NULL, 0,
65137 #ifdef SQLITE_DEBUG
65138          0, 0,  /* pScopyFrom, pFiller */
65139 #endif
65140          0, 0 };
65141 
65142     if( pVm && ALWAYS(pVm->db) ){
65143       sqlite3_mutex_enter(pVm->db->mutex);
65144       sqlite3Error(pVm->db, SQLITE_RANGE, 0);
65145     }
65146     pOut = (Mem*)&nullMem;
65147   }
65148   return pOut;
65149 }
65150 
65151 /*
65152 ** This function is called after invoking an sqlite3_value_XXX function on a 
65153 ** column value (i.e. a value returned by evaluating an SQL expression in the
65154 ** select list of a SELECT statement) that may cause a malloc() failure. If 
65155 ** malloc() has failed, the threads mallocFailed flag is cleared and the result
65156 ** code of statement pStmt set to SQLITE_NOMEM.
65157 **
65158 ** Specifically, this is called from within:
65159 **
65160 **     sqlite3_column_int()
65161 **     sqlite3_column_int64()
65162 **     sqlite3_column_text()
65163 **     sqlite3_column_text16()
65164 **     sqlite3_column_real()
65165 **     sqlite3_column_bytes()
65166 **     sqlite3_column_bytes16()
65167 **     sqiite3_column_blob()
65168 */
65169 static void columnMallocFailure(sqlite3_stmt *pStmt)
65170 {
65171   /* If malloc() failed during an encoding conversion within an
65172   ** sqlite3_column_XXX API, then set the return code of the statement to
65173   ** SQLITE_NOMEM. The next call to _step() (if any) will return SQLITE_ERROR
65174   ** and _finalize() will return NOMEM.
65175   */
65176   Vdbe *p = (Vdbe *)pStmt;
65177   if( p ){
65178     p->rc = sqlite3ApiExit(p->db, p->rc);
65179     sqlite3_mutex_leave(p->db->mutex);
65180   }
65181 }
65182 
65183 /**************************** sqlite3_column_  *******************************
65184 ** The following routines are used to access elements of the current row
65185 ** in the result set.
65186 */
65187 SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt *pStmt, int i){
65188   const void *val;
65189   val = sqlite3_value_blob( columnMem(pStmt,i) );
65190   /* Even though there is no encoding conversion, value_blob() might
65191   ** need to call malloc() to expand the result of a zeroblob() 
65192   ** expression. 
65193   */
65194   columnMallocFailure(pStmt);
65195   return val;
65196 }
65197 SQLITE_API int sqlite3_column_bytes(sqlite3_stmt *pStmt, int i){
65198   int val = sqlite3_value_bytes( columnMem(pStmt,i) );
65199   columnMallocFailure(pStmt);
65200   return val;
65201 }
65202 SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt *pStmt, int i){
65203   int val = sqlite3_value_bytes16( columnMem(pStmt,i) );
65204   columnMallocFailure(pStmt);
65205   return val;
65206 }
65207 SQLITE_API double sqlite3_column_double(sqlite3_stmt *pStmt, int i){
65208   double val = sqlite3_value_double( columnMem(pStmt,i) );
65209   columnMallocFailure(pStmt);
65210   return val;
65211 }
65212 SQLITE_API int sqlite3_column_int(sqlite3_stmt *pStmt, int i){
65213   int val = sqlite3_value_int( columnMem(pStmt,i) );
65214   columnMallocFailure(pStmt);
65215   return val;
65216 }
65217 SQLITE_API sqlite_int64 sqlite3_column_int64(sqlite3_stmt *pStmt, int i){
65218   sqlite_int64 val = sqlite3_value_int64( columnMem(pStmt,i) );
65219   columnMallocFailure(pStmt);
65220   return val;
65221 }
65222 SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt *pStmt, int i){
65223   const unsigned char *val = sqlite3_value_text( columnMem(pStmt,i) );
65224   columnMallocFailure(pStmt);
65225   return val;
65226 }
65227 SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt *pStmt, int i){
65228   Mem *pOut = columnMem(pStmt, i);
65229   if( pOut->flags&MEM_Static ){
65230     pOut->flags &= ~MEM_Static;
65231     pOut->flags |= MEM_Ephem;
65232   }
65233   columnMallocFailure(pStmt);
65234   return (sqlite3_value *)pOut;
65235 }
65236 #ifndef SQLITE_OMIT_UTF16
65237 SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt *pStmt, int i){
65238   const void *val = sqlite3_value_text16( columnMem(pStmt,i) );
65239   columnMallocFailure(pStmt);
65240   return val;
65241 }
65242 #endif /* SQLITE_OMIT_UTF16 */
65243 SQLITE_API int sqlite3_column_type(sqlite3_stmt *pStmt, int i){
65244   int iType = sqlite3_value_type( columnMem(pStmt,i) );
65245   columnMallocFailure(pStmt);
65246   return iType;
65247 }
65248 
65249 /*
65250 ** Convert the N-th element of pStmt->pColName[] into a string using
65251 ** xFunc() then return that string.  If N is out of range, return 0.
65252 **
65253 ** There are up to 5 names for each column.  useType determines which
65254 ** name is returned.  Here are the names:
65255 **
65256 **    0      The column name as it should be displayed for output
65257 **    1      The datatype name for the column
65258 **    2      The name of the database that the column derives from
65259 **    3      The name of the table that the column derives from
65260 **    4      The name of the table column that the result column derives from
65261 **
65262 ** If the result is not a simple column reference (if it is an expression
65263 ** or a constant) then useTypes 2, 3, and 4 return NULL.
65264 */
65265 static const void *columnName(
65266   sqlite3_stmt *pStmt,
65267   int N,
65268   const void *(*xFunc)(Mem*),
65269   int useType
65270 ){
65271   const void *ret = 0;
65272   Vdbe *p = (Vdbe *)pStmt;
65273   int n;
65274   sqlite3 *db = p->db;
65275   
65276   assert( db!=0 );
65277   n = sqlite3_column_count(pStmt);
65278   if( N<n && N>=0 ){
65279     N += useType*n;
65280     sqlite3_mutex_enter(db->mutex);
65281     assert( db->mallocFailed==0 );
65282     ret = xFunc(&p->aColName[N]);
65283      /* A malloc may have failed inside of the xFunc() call. If this
65284     ** is the case, clear the mallocFailed flag and return NULL.
65285     */
65286     if( db->mallocFailed ){
65287       db->mallocFailed = 0;
65288       ret = 0;
65289     }
65290     sqlite3_mutex_leave(db->mutex);
65291   }
65292   return ret;
65293 }
65294 
65295 /*
65296 ** Return the name of the Nth column of the result set returned by SQL
65297 ** statement pStmt.
65298 */
65299 SQLITE_API const char *sqlite3_column_name(sqlite3_stmt *pStmt, int N){
65300   return columnName(
65301       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_NAME);
65302 }
65303 #ifndef SQLITE_OMIT_UTF16
65304 SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt *pStmt, int N){
65305   return columnName(
65306       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_NAME);
65307 }
65308 #endif
65309 
65310 /*
65311 ** Constraint:  If you have ENABLE_COLUMN_METADATA then you must
65312 ** not define OMIT_DECLTYPE.
65313 */
65314 #if defined(SQLITE_OMIT_DECLTYPE) && defined(SQLITE_ENABLE_COLUMN_METADATA)
65315 # error "Must not define both SQLITE_OMIT_DECLTYPE \
65316          and SQLITE_ENABLE_COLUMN_METADATA"
65317 #endif
65318 
65319 #ifndef SQLITE_OMIT_DECLTYPE
65320 /*
65321 ** Return the column declaration type (if applicable) of the 'i'th column
65322 ** of the result set of SQL statement pStmt.
65323 */
65324 SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt *pStmt, int N){
65325   return columnName(
65326       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_DECLTYPE);
65327 }
65328 #ifndef SQLITE_OMIT_UTF16
65329 SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt *pStmt, int N){
65330   return columnName(
65331       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_DECLTYPE);
65332 }
65333 #endif /* SQLITE_OMIT_UTF16 */
65334 #endif /* SQLITE_OMIT_DECLTYPE */
65335 
65336 #ifdef SQLITE_ENABLE_COLUMN_METADATA
65337 /*
65338 ** Return the name of the database from which a result column derives.
65339 ** NULL is returned if the result column is an expression or constant or
65340 ** anything else which is not an unabiguous reference to a database column.
65341 */
65342 SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N){
65343   return columnName(
65344       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_DATABASE);
65345 }
65346 #ifndef SQLITE_OMIT_UTF16
65347 SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N){
65348   return columnName(
65349       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_DATABASE);
65350 }
65351 #endif /* SQLITE_OMIT_UTF16 */
65352 
65353 /*
65354 ** Return the name of the table from which a result column derives.
65355 ** NULL is returned if the result column is an expression or constant or
65356 ** anything else which is not an unabiguous reference to a database column.
65357 */
65358 SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N){
65359   return columnName(
65360       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_TABLE);
65361 }
65362 #ifndef SQLITE_OMIT_UTF16
65363 SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N){
65364   return columnName(
65365       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_TABLE);
65366 }
65367 #endif /* SQLITE_OMIT_UTF16 */
65368 
65369 /*
65370 ** Return the name of the table column from which a result column derives.
65371 ** NULL is returned if the result column is an expression or constant or
65372 ** anything else which is not an unabiguous reference to a database column.
65373 */
65374 SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N){
65375   return columnName(
65376       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_COLUMN);
65377 }
65378 #ifndef SQLITE_OMIT_UTF16
65379 SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N){
65380   return columnName(
65381       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_COLUMN);
65382 }
65383 #endif /* SQLITE_OMIT_UTF16 */
65384 #endif /* SQLITE_ENABLE_COLUMN_METADATA */
65385 
65386 
65387 /******************************* sqlite3_bind_  ***************************
65388 ** 
65389 ** Routines used to attach values to wildcards in a compiled SQL statement.
65390 */
65391 /*
65392 ** Unbind the value bound to variable i in virtual machine p. This is the 
65393 ** the same as binding a NULL value to the column. If the "i" parameter is
65394 ** out of range, then SQLITE_RANGE is returned. Othewise SQLITE_OK.
65395 **
65396 ** A successful evaluation of this routine acquires the mutex on p.
65397 ** the mutex is released if any kind of error occurs.
65398 **
65399 ** The error code stored in database p->db is overwritten with the return
65400 ** value in any case.
65401 */
65402 static int vdbeUnbind(Vdbe *p, int i){
65403   Mem *pVar;
65404   if( vdbeSafetyNotNull(p) ){
65405     return SQLITE_MISUSE_BKPT;
65406   }
65407   sqlite3_mutex_enter(p->db->mutex);
65408   if( p->magic!=VDBE_MAGIC_RUN || p->pc>=0 ){
65409     sqlite3Error(p->db, SQLITE_MISUSE, 0);
65410     sqlite3_mutex_leave(p->db->mutex);
65411     sqlite3_log(SQLITE_MISUSE, 
65412         "bind on a busy prepared statement: [%s]", p->zSql);
65413     return SQLITE_MISUSE_BKPT;
65414   }
65415   if( i<1 || i>p->nVar ){
65416     sqlite3Error(p->db, SQLITE_RANGE, 0);
65417     sqlite3_mutex_leave(p->db->mutex);
65418     return SQLITE_RANGE;
65419   }
65420   i--;
65421   pVar = &p->aVar[i];
65422   sqlite3VdbeMemRelease(pVar);
65423   pVar->flags = MEM_Null;
65424   sqlite3Error(p->db, SQLITE_OK, 0);
65425 
65426   /* If the bit corresponding to this variable in Vdbe.expmask is set, then 
65427   ** binding a new value to this variable invalidates the current query plan.
65428   **
65429   ** IMPLEMENTATION-OF: R-48440-37595 If the specific value bound to host
65430   ** parameter in the WHERE clause might influence the choice of query plan
65431   ** for a statement, then the statement will be automatically recompiled,
65432   ** as if there had been a schema change, on the first sqlite3_step() call
65433   ** following any change to the bindings of that parameter.
65434   */
65435   if( p->isPrepareV2 &&
65436      ((i<32 && p->expmask & ((u32)1 << i)) || p->expmask==0xffffffff)
65437   ){
65438     p->expired = 1;
65439   }
65440   return SQLITE_OK;
65441 }
65442 
65443 /*
65444 ** Bind a text or BLOB value.
65445 */
65446 static int bindText(
65447   sqlite3_stmt *pStmt,   /* The statement to bind against */
65448   int i,                 /* Index of the parameter to bind */
65449   const void *zData,     /* Pointer to the data to be bound */
65450   int nData,             /* Number of bytes of data to be bound */
65451   void (*xDel)(void*),   /* Destructor for the data */
65452   u8 encoding            /* Encoding for the data */
65453 ){
65454   Vdbe *p = (Vdbe *)pStmt;
65455   Mem *pVar;
65456   int rc;
65457 
65458   rc = vdbeUnbind(p, i);
65459   if( rc==SQLITE_OK ){
65460     if( zData!=0 ){
65461       pVar = &p->aVar[i-1];
65462       rc = sqlite3VdbeMemSetStr(pVar, zData, nData, encoding, xDel);
65463       if( rc==SQLITE_OK && encoding!=0 ){
65464         rc = sqlite3VdbeChangeEncoding(pVar, ENC(p->db));
65465       }
65466       sqlite3Error(p->db, rc, 0);
65467       rc = sqlite3ApiExit(p->db, rc);
65468     }
65469     sqlite3_mutex_leave(p->db->mutex);
65470   }else if( xDel!=SQLITE_STATIC && xDel!=SQLITE_TRANSIENT ){
65471     xDel((void*)zData);
65472   }
65473   return rc;
65474 }
65475 
65476 
65477 /*
65478 ** Bind a blob value to an SQL statement variable.
65479 */
65480 SQLITE_API int sqlite3_bind_blob(
65481   sqlite3_stmt *pStmt, 
65482   int i, 
65483   const void *zData, 
65484   int nData, 
65485   void (*xDel)(void*)
65486 ){
65487   return bindText(pStmt, i, zData, nData, xDel, 0);
65488 }
65489 SQLITE_API int sqlite3_bind_double(sqlite3_stmt *pStmt, int i, double rValue){
65490   int rc;
65491   Vdbe *p = (Vdbe *)pStmt;
65492   rc = vdbeUnbind(p, i);
65493   if( rc==SQLITE_OK ){
65494     sqlite3VdbeMemSetDouble(&p->aVar[i-1], rValue);
65495     sqlite3_mutex_leave(p->db->mutex);
65496   }
65497   return rc;
65498 }
65499 SQLITE_API int sqlite3_bind_int(sqlite3_stmt *p, int i, int iValue){
65500   return sqlite3_bind_int64(p, i, (i64)iValue);
65501 }
65502 SQLITE_API int sqlite3_bind_int64(sqlite3_stmt *pStmt, int i, sqlite_int64 iValue){
65503   int rc;
65504   Vdbe *p = (Vdbe *)pStmt;
65505   rc = vdbeUnbind(p, i);
65506   if( rc==SQLITE_OK ){
65507     sqlite3VdbeMemSetInt64(&p->aVar[i-1], iValue);
65508     sqlite3_mutex_leave(p->db->mutex);
65509   }
65510   return rc;
65511 }
65512 SQLITE_API int sqlite3_bind_null(sqlite3_stmt *pStmt, int i){
65513   int rc;
65514   Vdbe *p = (Vdbe*)pStmt;
65515   rc = vdbeUnbind(p, i);
65516   if( rc==SQLITE_OK ){
65517     sqlite3_mutex_leave(p->db->mutex);
65518   }
65519   return rc;
65520 }
65521 SQLITE_API int sqlite3_bind_text( 
65522   sqlite3_stmt *pStmt, 
65523   int i, 
65524   const char *zData, 
65525   int nData, 
65526   void (*xDel)(void*)
65527 ){
65528   return bindText(pStmt, i, zData, nData, xDel, SQLITE_UTF8);
65529 }
65530 #ifndef SQLITE_OMIT_UTF16
65531 SQLITE_API int sqlite3_bind_text16(
65532   sqlite3_stmt *pStmt, 
65533   int i, 
65534   const void *zData, 
65535   int nData, 
65536   void (*xDel)(void*)
65537 ){
65538   return bindText(pStmt, i, zData, nData, xDel, SQLITE_UTF16NATIVE);
65539 }
65540 #endif /* SQLITE_OMIT_UTF16 */
65541 SQLITE_API int sqlite3_bind_value(sqlite3_stmt *pStmt, int i, const sqlite3_value *pValue){
65542   int rc;
65543   switch( pValue->type ){
65544     case SQLITE_INTEGER: {
65545       rc = sqlite3_bind_int64(pStmt, i, pValue->u.i);
65546       break;
65547     }
65548     case SQLITE_FLOAT: {
65549       rc = sqlite3_bind_double(pStmt, i, pValue->r);
65550       break;
65551     }
65552     case SQLITE_BLOB: {
65553       if( pValue->flags & MEM_Zero ){
65554         rc = sqlite3_bind_zeroblob(pStmt, i, pValue->u.nZero);
65555       }else{
65556         rc = sqlite3_bind_blob(pStmt, i, pValue->z, pValue->n,SQLITE_TRANSIENT);
65557       }
65558       break;
65559     }
65560     case SQLITE_TEXT: {
65561       rc = bindText(pStmt,i,  pValue->z, pValue->n, SQLITE_TRANSIENT,
65562                               pValue->enc);
65563       break;
65564     }
65565     default: {
65566       rc = sqlite3_bind_null(pStmt, i);
65567       break;
65568     }
65569   }
65570   return rc;
65571 }
65572 SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt *pStmt, int i, int n){
65573   int rc;
65574   Vdbe *p = (Vdbe *)pStmt;
65575   rc = vdbeUnbind(p, i);
65576   if( rc==SQLITE_OK ){
65577     sqlite3VdbeMemSetZeroBlob(&p->aVar[i-1], n);
65578     sqlite3_mutex_leave(p->db->mutex);
65579   }
65580   return rc;
65581 }
65582 
65583 /*
65584 ** Return the number of wildcards that can be potentially bound to.
65585 ** This routine is added to support DBD::SQLite.  
65586 */
65587 SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt *pStmt){
65588   Vdbe *p = (Vdbe*)pStmt;
65589   return p ? p->nVar : 0;
65590 }
65591 
65592 /*
65593 ** Return the name of a wildcard parameter.  Return NULL if the index
65594 ** is out of range or if the wildcard is unnamed.
65595 **
65596 ** The result is always UTF-8.
65597 */
65598 SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt *pStmt, int i){
65599   Vdbe *p = (Vdbe*)pStmt;
65600   if( p==0 || i<1 || i>p->nzVar ){
65601     return 0;
65602   }
65603   return p->azVar[i-1];
65604 }
65605 
65606 /*
65607 ** Given a wildcard parameter name, return the index of the variable
65608 ** with that name.  If there is no variable with the given name,
65609 ** return 0.
65610 */
65611 SQLITE_PRIVATE int sqlite3VdbeParameterIndex(Vdbe *p, const char *zName, int nName){
65612   int i;
65613   if( p==0 ){
65614     return 0;
65615   }
65616   if( zName ){
65617     for(i=0; i<p->nzVar; i++){
65618       const char *z = p->azVar[i];
65619       if( z && strncmp(z,zName,nName)==0 && z[nName]==0 ){
65620         return i+1;
65621       }
65622     }
65623   }
65624   return 0;
65625 }
65626 SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt *pStmt, const char *zName){
65627   return sqlite3VdbeParameterIndex((Vdbe*)pStmt, zName, sqlite3Strlen30(zName));
65628 }
65629 
65630 /*
65631 ** Transfer all bindings from the first statement over to the second.
65632 */
65633 SQLITE_PRIVATE int sqlite3TransferBindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
65634   Vdbe *pFrom = (Vdbe*)pFromStmt;
65635   Vdbe *pTo = (Vdbe*)pToStmt;
65636   int i;
65637   assert( pTo->db==pFrom->db );
65638   assert( pTo->nVar==pFrom->nVar );
65639   sqlite3_mutex_enter(pTo->db->mutex);
65640   for(i=0; i<pFrom->nVar; i++){
65641     sqlite3VdbeMemMove(&pTo->aVar[i], &pFrom->aVar[i]);
65642   }
65643   sqlite3_mutex_leave(pTo->db->mutex);
65644   return SQLITE_OK;
65645 }
65646 
65647 #ifndef SQLITE_OMIT_DEPRECATED
65648 /*
65649 ** Deprecated external interface.  Internal/core SQLite code
65650 ** should call sqlite3TransferBindings.
65651 **
65652 ** Is is misuse to call this routine with statements from different
65653 ** database connections.  But as this is a deprecated interface, we
65654 ** will not bother to check for that condition.
65655 **
65656 ** If the two statements contain a different number of bindings, then
65657 ** an SQLITE_ERROR is returned.  Nothing else can go wrong, so otherwise
65658 ** SQLITE_OK is returned.
65659 */
65660 SQLITE_API int sqlite3_transfer_bindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
65661   Vdbe *pFrom = (Vdbe*)pFromStmt;
65662   Vdbe *pTo = (Vdbe*)pToStmt;
65663   if( pFrom->nVar!=pTo->nVar ){
65664     return SQLITE_ERROR;
65665   }
65666   if( pTo->isPrepareV2 && pTo->expmask ){
65667     pTo->expired = 1;
65668   }
65669   if( pFrom->isPrepareV2 && pFrom->expmask ){
65670     pFrom->expired = 1;
65671   }
65672   return sqlite3TransferBindings(pFromStmt, pToStmt);
65673 }
65674 #endif
65675 
65676 /*
65677 ** Return the sqlite3* database handle to which the prepared statement given
65678 ** in the argument belongs.  This is the same database handle that was
65679 ** the first argument to the sqlite3_prepare() that was used to create
65680 ** the statement in the first place.
65681 */
65682 SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt *pStmt){
65683   return pStmt ? ((Vdbe*)pStmt)->db : 0;
65684 }
65685 
65686 /*
65687 ** Return true if the prepared statement is guaranteed to not modify the
65688 ** database.
65689 */
65690 SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt){
65691   return pStmt ? ((Vdbe*)pStmt)->readOnly : 1;
65692 }
65693 
65694 /*
65695 ** Return true if the prepared statement is in need of being reset.
65696 */
65697 SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt *pStmt){
65698   Vdbe *v = (Vdbe*)pStmt;
65699   return v!=0 && v->pc>0 && v->magic==VDBE_MAGIC_RUN;
65700 }
65701 
65702 /*
65703 ** Return a pointer to the next prepared statement after pStmt associated
65704 ** with database connection pDb.  If pStmt is NULL, return the first
65705 ** prepared statement for the database connection.  Return NULL if there
65706 ** are no more.
65707 */
65708 SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt){
65709   sqlite3_stmt *pNext;
65710   sqlite3_mutex_enter(pDb->mutex);
65711   if( pStmt==0 ){
65712     pNext = (sqlite3_stmt*)pDb->pVdbe;
65713   }else{
65714     pNext = (sqlite3_stmt*)((Vdbe*)pStmt)->pNext;
65715   }
65716   sqlite3_mutex_leave(pDb->mutex);
65717   return pNext;
65718 }
65719 
65720 /*
65721 ** Return the value of a status counter for a prepared statement
65722 */
65723 SQLITE_API int sqlite3_stmt_status(sqlite3_stmt *pStmt, int op, int resetFlag){
65724   Vdbe *pVdbe = (Vdbe*)pStmt;
65725   u32 v = pVdbe->aCounter[op];
65726   if( resetFlag ) pVdbe->aCounter[op] = 0;
65727   return (int)v;
65728 }
65729 
65730 /************** End of vdbeapi.c *********************************************/
65731 /************** Begin file vdbetrace.c ***************************************/
65732 /*
65733 ** 2009 November 25
65734 **
65735 ** The author disclaims copyright to this source code.  In place of
65736 ** a legal notice, here is a blessing:
65737 **
65738 **    May you do good and not evil.
65739 **    May you find forgiveness for yourself and forgive others.
65740 **    May you share freely, never taking more than you give.
65741 **
65742 *************************************************************************
65743 **
65744 ** This file contains code used to insert the values of host parameters
65745 ** (aka "wildcards") into the SQL text output by sqlite3_trace().
65746 **
65747 ** The Vdbe parse-tree explainer is also found here.
65748 */
65749 
65750 #ifndef SQLITE_OMIT_TRACE
65751 
65752 /*
65753 ** zSql is a zero-terminated string of UTF-8 SQL text.  Return the number of
65754 ** bytes in this text up to but excluding the first character in
65755 ** a host parameter.  If the text contains no host parameters, return
65756 ** the total number of bytes in the text.
65757 */
65758 static int findNextHostParameter(const char *zSql, int *pnToken){
65759   int tokenType;
65760   int nTotal = 0;
65761   int n;
65762 
65763   *pnToken = 0;
65764   while( zSql[0] ){
65765     n = sqlite3GetToken((u8*)zSql, &tokenType);
65766     assert( n>0 && tokenType!=TK_ILLEGAL );
65767     if( tokenType==TK_VARIABLE ){
65768       *pnToken = n;
65769       break;
65770     }
65771     nTotal += n;
65772     zSql += n;
65773   }
65774   return nTotal;
65775 }
65776 
65777 /*
65778 ** This function returns a pointer to a nul-terminated string in memory
65779 ** obtained from sqlite3DbMalloc(). If sqlite3.nVdbeExec is 1, then the
65780 ** string contains a copy of zRawSql but with host parameters expanded to 
65781 ** their current bindings. Or, if sqlite3.nVdbeExec is greater than 1, 
65782 ** then the returned string holds a copy of zRawSql with "-- " prepended
65783 ** to each line of text.
65784 **
65785 ** If the SQLITE_TRACE_SIZE_LIMIT macro is defined to an integer, then
65786 ** then long strings and blobs are truncated to that many bytes.  This
65787 ** can be used to prevent unreasonably large trace strings when dealing
65788 ** with large (multi-megabyte) strings and blobs.
65789 **
65790 ** The calling function is responsible for making sure the memory returned
65791 ** is eventually freed.
65792 **
65793 ** ALGORITHM:  Scan the input string looking for host parameters in any of
65794 ** these forms:  ?, ?N, $A, @A, :A.  Take care to avoid text within
65795 ** string literals, quoted identifier names, and comments.  For text forms,
65796 ** the host parameter index is found by scanning the perpared
65797 ** statement for the corresponding OP_Variable opcode.  Once the host
65798 ** parameter index is known, locate the value in p->aVar[].  Then render
65799 ** the value as a literal in place of the host parameter name.
65800 */
65801 SQLITE_PRIVATE char *sqlite3VdbeExpandSql(
65802   Vdbe *p,                 /* The prepared statement being evaluated */
65803   const char *zRawSql      /* Raw text of the SQL statement */
65804 ){
65805   sqlite3 *db;             /* The database connection */
65806   int idx = 0;             /* Index of a host parameter */
65807   int nextIndex = 1;       /* Index of next ? host parameter */
65808   int n;                   /* Length of a token prefix */
65809   int nToken;              /* Length of the parameter token */
65810   int i;                   /* Loop counter */
65811   Mem *pVar;               /* Value of a host parameter */
65812   StrAccum out;            /* Accumulate the output here */
65813   char zBase[100];         /* Initial working space */
65814 
65815   db = p->db;
65816   sqlite3StrAccumInit(&out, zBase, sizeof(zBase), 
65817                       db->aLimit[SQLITE_LIMIT_LENGTH]);
65818   out.db = db;
65819   if( db->nVdbeExec>1 ){
65820     while( *zRawSql ){
65821       const char *zStart = zRawSql;
65822       while( *(zRawSql++)!='\n' && *zRawSql );
65823       sqlite3StrAccumAppend(&out, "-- ", 3);
65824       sqlite3StrAccumAppend(&out, zStart, (int)(zRawSql-zStart));
65825     }
65826   }else{
65827     while( zRawSql[0] ){
65828       n = findNextHostParameter(zRawSql, &nToken);
65829       assert( n>0 );
65830       sqlite3StrAccumAppend(&out, zRawSql, n);
65831       zRawSql += n;
65832       assert( zRawSql[0] || nToken==0 );
65833       if( nToken==0 ) break;
65834       if( zRawSql[0]=='?' ){
65835         if( nToken>1 ){
65836           assert( sqlite3Isdigit(zRawSql[1]) );
65837           sqlite3GetInt32(&zRawSql[1], &idx);
65838         }else{
65839           idx = nextIndex;
65840         }
65841       }else{
65842         assert( zRawSql[0]==':' || zRawSql[0]=='$' || zRawSql[0]=='@' );
65843         testcase( zRawSql[0]==':' );
65844         testcase( zRawSql[0]=='$' );
65845         testcase( zRawSql[0]=='@' );
65846         idx = sqlite3VdbeParameterIndex(p, zRawSql, nToken);
65847         assert( idx>0 );
65848       }
65849       zRawSql += nToken;
65850       nextIndex = idx + 1;
65851       assert( idx>0 && idx<=p->nVar );
65852       pVar = &p->aVar[idx-1];
65853       if( pVar->flags & MEM_Null ){
65854         sqlite3StrAccumAppend(&out, "NULL", 4);
65855       }else if( pVar->flags & MEM_Int ){
65856         sqlite3XPrintf(&out, "%lld", pVar->u.i);
65857       }else if( pVar->flags & MEM_Real ){
65858         sqlite3XPrintf(&out, "%!.15g", pVar->r);
65859       }else if( pVar->flags & MEM_Str ){
65860         int nOut;  /* Number of bytes of the string text to include in output */
65861 #ifndef SQLITE_OMIT_UTF16
65862         u8 enc = ENC(db);
65863         Mem utf8;
65864         if( enc!=SQLITE_UTF8 ){
65865           memset(&utf8, 0, sizeof(utf8));
65866           utf8.db = db;
65867           sqlite3VdbeMemSetStr(&utf8, pVar->z, pVar->n, enc, SQLITE_STATIC);
65868           sqlite3VdbeChangeEncoding(&utf8, SQLITE_UTF8);
65869           pVar = &utf8;
65870         }
65871 #endif
65872         nOut = pVar->n;
65873 #ifdef SQLITE_TRACE_SIZE_LIMIT
65874         if( nOut>SQLITE_TRACE_SIZE_LIMIT ){
65875           nOut = SQLITE_TRACE_SIZE_LIMIT;
65876           while( nOut<pVar->n && (pVar->z[nOut]&0xc0)==0x80 ){ nOut++; }
65877         }
65878 #endif    
65879         sqlite3XPrintf(&out, "'%.*q'", nOut, pVar->z);
65880 #ifdef SQLITE_TRACE_SIZE_LIMIT
65881         if( nOut<pVar->n ) sqlite3XPrintf(&out, "/*+%d bytes*/", pVar->n-nOut);
65882 #endif
65883 #ifndef SQLITE_OMIT_UTF16
65884         if( enc!=SQLITE_UTF8 ) sqlite3VdbeMemRelease(&utf8);
65885 #endif
65886       }else if( pVar->flags & MEM_Zero ){
65887         sqlite3XPrintf(&out, "zeroblob(%d)", pVar->u.nZero);
65888       }else{
65889         int nOut;  /* Number of bytes of the blob to include in output */
65890         assert( pVar->flags & MEM_Blob );
65891         sqlite3StrAccumAppend(&out, "x'", 2);
65892         nOut = pVar->n;
65893 #ifdef SQLITE_TRACE_SIZE_LIMIT
65894         if( nOut>SQLITE_TRACE_SIZE_LIMIT ) nOut = SQLITE_TRACE_SIZE_LIMIT;
65895 #endif
65896         for(i=0; i<nOut; i++){
65897           sqlite3XPrintf(&out, "%02x", pVar->z[i]&0xff);
65898         }
65899         sqlite3StrAccumAppend(&out, "'", 1);
65900 #ifdef SQLITE_TRACE_SIZE_LIMIT
65901         if( nOut<pVar->n ) sqlite3XPrintf(&out, "/*+%d bytes*/", pVar->n-nOut);
65902 #endif
65903       }
65904     }
65905   }
65906   return sqlite3StrAccumFinish(&out);
65907 }
65908 
65909 #endif /* #ifndef SQLITE_OMIT_TRACE */
65910 
65911 /*****************************************************************************
65912 ** The following code implements the data-structure explaining logic
65913 ** for the Vdbe.
65914 */
65915 
65916 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
65917 
65918 /*
65919 ** Allocate a new Explain object
65920 */
65921 SQLITE_PRIVATE void sqlite3ExplainBegin(Vdbe *pVdbe){
65922   if( pVdbe ){
65923     Explain *p;
65924     sqlite3BeginBenignMalloc();
65925     p = (Explain *)sqlite3MallocZero( sizeof(Explain) );
65926     if( p ){
65927       p->pVdbe = pVdbe;
65928       sqlite3_free(pVdbe->pExplain);
65929       pVdbe->pExplain = p;
65930       sqlite3StrAccumInit(&p->str, p->zBase, sizeof(p->zBase),
65931                           SQLITE_MAX_LENGTH);
65932       p->str.useMalloc = 2;
65933     }else{
65934       sqlite3EndBenignMalloc();
65935     }
65936   }
65937 }
65938 
65939 /*
65940 ** Return true if the Explain ends with a new-line.
65941 */
65942 static int endsWithNL(Explain *p){
65943   return p && p->str.zText && p->str.nChar
65944            && p->str.zText[p->str.nChar-1]=='\n';
65945 }
65946     
65947 /*
65948 ** Append text to the indentation
65949 */
65950 SQLITE_PRIVATE void sqlite3ExplainPrintf(Vdbe *pVdbe, const char *zFormat, ...){
65951   Explain *p;
65952   if( pVdbe && (p = pVdbe->pExplain)!=0 ){
65953     va_list ap;
65954     if( p->nIndent && endsWithNL(p) ){
65955       int n = p->nIndent;
65956       if( n>ArraySize(p->aIndent) ) n = ArraySize(p->aIndent);
65957       sqlite3AppendSpace(&p->str, p->aIndent[n-1]);
65958     }   
65959     va_start(ap, zFormat);
65960     sqlite3VXPrintf(&p->str, 1, zFormat, ap);
65961     va_end(ap);
65962   }
65963 }
65964 
65965 /*
65966 ** Append a '\n' if there is not already one.
65967 */
65968 SQLITE_PRIVATE void sqlite3ExplainNL(Vdbe *pVdbe){
65969   Explain *p;
65970   if( pVdbe && (p = pVdbe->pExplain)!=0 && !endsWithNL(p) ){
65971     sqlite3StrAccumAppend(&p->str, "\n", 1);
65972   }
65973 }
65974 
65975 /*
65976 ** Push a new indentation level.  Subsequent lines will be indented
65977 ** so that they begin at the current cursor position.
65978 */
65979 SQLITE_PRIVATE void sqlite3ExplainPush(Vdbe *pVdbe){
65980   Explain *p;
65981   if( pVdbe && (p = pVdbe->pExplain)!=0 ){
65982     if( p->str.zText && p->nIndent<ArraySize(p->aIndent) ){
65983       const char *z = p->str.zText;
65984       int i = p->str.nChar-1;
65985       int x;
65986       while( i>=0 && z[i]!='\n' ){ i--; }
65987       x = (p->str.nChar - 1) - i;
65988       if( p->nIndent && x<p->aIndent[p->nIndent-1] ){
65989         x = p->aIndent[p->nIndent-1];
65990       }
65991       p->aIndent[p->nIndent] = x;
65992     }
65993     p->nIndent++;
65994   }
65995 }
65996 
65997 /*
65998 ** Pop the indentation stack by one level.
65999 */
66000 SQLITE_PRIVATE void sqlite3ExplainPop(Vdbe *p){
66001   if( p && p->pExplain ) p->pExplain->nIndent--;
66002 }
66003 
66004 /*
66005 ** Free the indentation structure
66006 */
66007 SQLITE_PRIVATE void sqlite3ExplainFinish(Vdbe *pVdbe){
66008   if( pVdbe && pVdbe->pExplain ){
66009     sqlite3_free(pVdbe->zExplain);
66010     sqlite3ExplainNL(pVdbe);
66011     pVdbe->zExplain = sqlite3StrAccumFinish(&pVdbe->pExplain->str);
66012     sqlite3_free(pVdbe->pExplain);
66013     pVdbe->pExplain = 0;
66014     sqlite3EndBenignMalloc();
66015   }
66016 }
66017 
66018 /*
66019 ** Return the explanation of a virtual machine.
66020 */
66021 SQLITE_PRIVATE const char *sqlite3VdbeExplanation(Vdbe *pVdbe){
66022   return (pVdbe && pVdbe->zExplain) ? pVdbe->zExplain : 0;
66023 }
66024 #endif /* defined(SQLITE_DEBUG) */
66025 
66026 /************** End of vdbetrace.c *******************************************/
66027 /************** Begin file vdbe.c ********************************************/
66028 /*
66029 ** 2001 September 15
66030 **
66031 ** The author disclaims copyright to this source code.  In place of
66032 ** a legal notice, here is a blessing:
66033 **
66034 **    May you do good and not evil.
66035 **    May you find forgiveness for yourself and forgive others.
66036 **    May you share freely, never taking more than you give.
66037 **
66038 *************************************************************************
66039 ** The code in this file implements execution method of the 
66040 ** Virtual Database Engine (VDBE).  A separate file ("vdbeaux.c")
66041 ** handles housekeeping details such as creating and deleting
66042 ** VDBE instances.  This file is solely interested in executing
66043 ** the VDBE program.
66044 **
66045 ** In the external interface, an "sqlite3_stmt*" is an opaque pointer
66046 ** to a VDBE.
66047 **
66048 ** The SQL parser generates a program which is then executed by
66049 ** the VDBE to do the work of the SQL statement.  VDBE programs are 
66050 ** similar in form to assembly language.  The program consists of
66051 ** a linear sequence of operations.  Each operation has an opcode 
66052 ** and 5 operands.  Operands P1, P2, and P3 are integers.  Operand P4 
66053 ** is a null-terminated string.  Operand P5 is an unsigned character.
66054 ** Few opcodes use all 5 operands.
66055 **
66056 ** Computation results are stored on a set of registers numbered beginning
66057 ** with 1 and going up to Vdbe.nMem.  Each register can store
66058 ** either an integer, a null-terminated string, a floating point
66059 ** number, or the SQL "NULL" value.  An implicit conversion from one
66060 ** type to the other occurs as necessary.
66061 ** 
66062 ** Most of the code in this file is taken up by the sqlite3VdbeExec()
66063 ** function which does the work of interpreting a VDBE program.
66064 ** But other routines are also provided to help in building up
66065 ** a program instruction by instruction.
66066 **
66067 ** Various scripts scan this source file in order to generate HTML
66068 ** documentation, headers files, or other derived files.  The formatting
66069 ** of the code in this file is, therefore, important.  See other comments
66070 ** in this file for details.  If in doubt, do not deviate from existing
66071 ** commenting and indentation practices when changing or adding code.
66072 */
66073 
66074 /*
66075 ** Invoke this macro on memory cells just prior to changing the
66076 ** value of the cell.  This macro verifies that shallow copies are
66077 ** not misused.
66078 */
66079 #ifdef SQLITE_DEBUG
66080 # define memAboutToChange(P,M) sqlite3VdbeMemAboutToChange(P,M)
66081 #else
66082 # define memAboutToChange(P,M)
66083 #endif
66084 
66085 /*
66086 ** The following global variable is incremented every time a cursor
66087 ** moves, either by the OP_SeekXX, OP_Next, or OP_Prev opcodes.  The test
66088 ** procedures use this information to make sure that indices are
66089 ** working correctly.  This variable has no function other than to
66090 ** help verify the correct operation of the library.
66091 */
66092 #ifdef SQLITE_TEST
66093 SQLITE_API int sqlite3_search_count = 0;
66094 #endif
66095 
66096 /*
66097 ** When this global variable is positive, it gets decremented once before
66098 ** each instruction in the VDBE.  When it reaches zero, the u1.isInterrupted
66099 ** field of the sqlite3 structure is set in order to simulate an interrupt.
66100 **
66101 ** This facility is used for testing purposes only.  It does not function
66102 ** in an ordinary build.
66103 */
66104 #ifdef SQLITE_TEST
66105 SQLITE_API int sqlite3_interrupt_count = 0;
66106 #endif
66107 
66108 /*
66109 ** The next global variable is incremented each type the OP_Sort opcode
66110 ** is executed.  The test procedures use this information to make sure that
66111 ** sorting is occurring or not occurring at appropriate times.   This variable
66112 ** has no function other than to help verify the correct operation of the
66113 ** library.
66114 */
66115 #ifdef SQLITE_TEST
66116 SQLITE_API int sqlite3_sort_count = 0;
66117 #endif
66118 
66119 /*
66120 ** The next global variable records the size of the largest MEM_Blob
66121 ** or MEM_Str that has been used by a VDBE opcode.  The test procedures
66122 ** use this information to make sure that the zero-blob functionality
66123 ** is working correctly.   This variable has no function other than to
66124 ** help verify the correct operation of the library.
66125 */
66126 #ifdef SQLITE_TEST
66127 SQLITE_API int sqlite3_max_blobsize = 0;
66128 static void updateMaxBlobsize(Mem *p){
66129   if( (p->flags & (MEM_Str|MEM_Blob))!=0 && p->n>sqlite3_max_blobsize ){
66130     sqlite3_max_blobsize = p->n;
66131   }
66132 }
66133 #endif
66134 
66135 /*
66136 ** The next global variable is incremented each type the OP_Found opcode
66137 ** is executed. This is used to test whether or not the foreign key
66138 ** operation implemented using OP_FkIsZero is working. This variable
66139 ** has no function other than to help verify the correct operation of the
66140 ** library.
66141 */
66142 #ifdef SQLITE_TEST
66143 SQLITE_API int sqlite3_found_count = 0;
66144 #endif
66145 
66146 /*
66147 ** Test a register to see if it exceeds the current maximum blob size.
66148 ** If it does, record the new maximum blob size.
66149 */
66150 #if defined(SQLITE_TEST) && !defined(SQLITE_OMIT_BUILTIN_TEST)
66151 # define UPDATE_MAX_BLOBSIZE(P)  updateMaxBlobsize(P)
66152 #else
66153 # define UPDATE_MAX_BLOBSIZE(P)
66154 #endif
66155 
66156 /*
66157 ** Convert the given register into a string if it isn't one
66158 ** already. Return non-zero if a malloc() fails.
66159 */
66160 #define Stringify(P, enc) \
66161    if(((P)->flags&(MEM_Str|MEM_Blob))==0 && sqlite3VdbeMemStringify(P,enc)) \
66162      { goto no_mem; }
66163 
66164 /*
66165 ** An ephemeral string value (signified by the MEM_Ephem flag) contains
66166 ** a pointer to a dynamically allocated string where some other entity
66167 ** is responsible for deallocating that string.  Because the register
66168 ** does not control the string, it might be deleted without the register
66169 ** knowing it.
66170 **
66171 ** This routine converts an ephemeral string into a dynamically allocated
66172 ** string that the register itself controls.  In other words, it
66173 ** converts an MEM_Ephem string into an MEM_Dyn string.
66174 */
66175 #define Deephemeralize(P) \
66176    if( ((P)->flags&MEM_Ephem)!=0 \
66177        && sqlite3VdbeMemMakeWriteable(P) ){ goto no_mem;}
66178 
66179 /* Return true if the cursor was opened using the OP_OpenSorter opcode. */
66180 # define isSorter(x) ((x)->pSorter!=0)
66181 
66182 /*
66183 ** Argument pMem points at a register that will be passed to a
66184 ** user-defined function or returned to the user as the result of a query.
66185 ** This routine sets the pMem->type variable used by the sqlite3_value_*() 
66186 ** routines.
66187 */
66188 SQLITE_PRIVATE void sqlite3VdbeMemStoreType(Mem *pMem){
66189   int flags = pMem->flags;
66190   if( flags & MEM_Null ){
66191     pMem->type = SQLITE_NULL;
66192   }
66193   else if( flags & MEM_Int ){
66194     pMem->type = SQLITE_INTEGER;
66195   }
66196   else if( flags & MEM_Real ){
66197     pMem->type = SQLITE_FLOAT;
66198   }
66199   else if( flags & MEM_Str ){
66200     pMem->type = SQLITE_TEXT;
66201   }else{
66202     pMem->type = SQLITE_BLOB;
66203   }
66204 }
66205 
66206 /*
66207 ** Allocate VdbeCursor number iCur.  Return a pointer to it.  Return NULL
66208 ** if we run out of memory.
66209 */
66210 static VdbeCursor *allocateCursor(
66211   Vdbe *p,              /* The virtual machine */
66212   int iCur,             /* Index of the new VdbeCursor */
66213   int nField,           /* Number of fields in the table or index */
66214   int iDb,              /* Database the cursor belongs to, or -1 */
66215   int isBtreeCursor     /* True for B-Tree.  False for pseudo-table or vtab */
66216 ){
66217   /* Find the memory cell that will be used to store the blob of memory
66218   ** required for this VdbeCursor structure. It is convenient to use a 
66219   ** vdbe memory cell to manage the memory allocation required for a
66220   ** VdbeCursor structure for the following reasons:
66221   **
66222   **   * Sometimes cursor numbers are used for a couple of different
66223   **     purposes in a vdbe program. The different uses might require
66224   **     different sized allocations. Memory cells provide growable
66225   **     allocations.
66226   **
66227   **   * When using ENABLE_MEMORY_MANAGEMENT, memory cell buffers can
66228   **     be freed lazily via the sqlite3_release_memory() API. This
66229   **     minimizes the number of malloc calls made by the system.
66230   **
66231   ** Memory cells for cursors are allocated at the top of the address
66232   ** space. Memory cell (p->nMem) corresponds to cursor 0. Space for
66233   ** cursor 1 is managed by memory cell (p->nMem-1), etc.
66234   */
66235   Mem *pMem = &p->aMem[p->nMem-iCur];
66236 
66237   int nByte;
66238   VdbeCursor *pCx = 0;
66239   nByte = 
66240       ROUND8(sizeof(VdbeCursor)) + 2*sizeof(u32)*nField + 
66241       (isBtreeCursor?sqlite3BtreeCursorSize():0);
66242 
66243   assert( iCur<p->nCursor );
66244   if( p->apCsr[iCur] ){
66245     sqlite3VdbeFreeCursor(p, p->apCsr[iCur]);
66246     p->apCsr[iCur] = 0;
66247   }
66248   if( SQLITE_OK==sqlite3VdbeMemGrow(pMem, nByte, 0) ){
66249     p->apCsr[iCur] = pCx = (VdbeCursor*)pMem->z;
66250     memset(pCx, 0, sizeof(VdbeCursor));
66251     pCx->iDb = iDb;
66252     pCx->nField = nField;
66253     if( isBtreeCursor ){
66254       pCx->pCursor = (BtCursor*)
66255           &pMem->z[ROUND8(sizeof(VdbeCursor))+2*sizeof(u32)*nField];
66256       sqlite3BtreeCursorZero(pCx->pCursor);
66257     }
66258   }
66259   return pCx;
66260 }
66261 
66262 /*
66263 ** Try to convert a value into a numeric representation if we can
66264 ** do so without loss of information.  In other words, if the string
66265 ** looks like a number, convert it into a number.  If it does not
66266 ** look like a number, leave it alone.
66267 */
66268 static void applyNumericAffinity(Mem *pRec){
66269   if( (pRec->flags & (MEM_Real|MEM_Int))==0 ){
66270     double rValue;
66271     i64 iValue;
66272     u8 enc = pRec->enc;
66273     if( (pRec->flags&MEM_Str)==0 ) return;
66274     if( sqlite3AtoF(pRec->z, &rValue, pRec->n, enc)==0 ) return;
66275     if( 0==sqlite3Atoi64(pRec->z, &iValue, pRec->n, enc) ){
66276       pRec->u.i = iValue;
66277       pRec->flags |= MEM_Int;
66278     }else{
66279       pRec->r = rValue;
66280       pRec->flags |= MEM_Real;
66281     }
66282   }
66283 }
66284 
66285 /*
66286 ** Processing is determine by the affinity parameter:
66287 **
66288 ** SQLITE_AFF_INTEGER:
66289 ** SQLITE_AFF_REAL:
66290 ** SQLITE_AFF_NUMERIC:
66291 **    Try to convert pRec to an integer representation or a 
66292 **    floating-point representation if an integer representation
66293 **    is not possible.  Note that the integer representation is
66294 **    always preferred, even if the affinity is REAL, because
66295 **    an integer representation is more space efficient on disk.
66296 **
66297 ** SQLITE_AFF_TEXT:
66298 **    Convert pRec to a text representation.
66299 **
66300 ** SQLITE_AFF_NONE:
66301 **    No-op.  pRec is unchanged.
66302 */
66303 static void applyAffinity(
66304   Mem *pRec,          /* The value to apply affinity to */
66305   char affinity,      /* The affinity to be applied */
66306   u8 enc              /* Use this text encoding */
66307 ){
66308   if( affinity==SQLITE_AFF_TEXT ){
66309     /* Only attempt the conversion to TEXT if there is an integer or real
66310     ** representation (blob and NULL do not get converted) but no string
66311     ** representation.
66312     */
66313     if( 0==(pRec->flags&MEM_Str) && (pRec->flags&(MEM_Real|MEM_Int)) ){
66314       sqlite3VdbeMemStringify(pRec, enc);
66315     }
66316     pRec->flags &= ~(MEM_Real|MEM_Int);
66317   }else if( affinity!=SQLITE_AFF_NONE ){
66318     assert( affinity==SQLITE_AFF_INTEGER || affinity==SQLITE_AFF_REAL
66319              || affinity==SQLITE_AFF_NUMERIC );
66320     applyNumericAffinity(pRec);
66321     if( pRec->flags & MEM_Real ){
66322       sqlite3VdbeIntegerAffinity(pRec);
66323     }
66324   }
66325 }
66326 
66327 /*
66328 ** Try to convert the type of a function argument or a result column
66329 ** into a numeric representation.  Use either INTEGER or REAL whichever
66330 ** is appropriate.  But only do the conversion if it is possible without
66331 ** loss of information and return the revised type of the argument.
66332 */
66333 SQLITE_API int sqlite3_value_numeric_type(sqlite3_value *pVal){
66334   Mem *pMem = (Mem*)pVal;
66335   if( pMem->type==SQLITE_TEXT ){
66336     applyNumericAffinity(pMem);
66337     sqlite3VdbeMemStoreType(pMem);
66338   }
66339   return pMem->type;
66340 }
66341 
66342 /*
66343 ** Exported version of applyAffinity(). This one works on sqlite3_value*, 
66344 ** not the internal Mem* type.
66345 */
66346 SQLITE_PRIVATE void sqlite3ValueApplyAffinity(
66347   sqlite3_value *pVal, 
66348   u8 affinity, 
66349   u8 enc
66350 ){
66351   applyAffinity((Mem *)pVal, affinity, enc);
66352 }
66353 
66354 #ifdef SQLITE_DEBUG
66355 /*
66356 ** Write a nice string representation of the contents of cell pMem
66357 ** into buffer zBuf, length nBuf.
66358 */
66359 SQLITE_PRIVATE void sqlite3VdbeMemPrettyPrint(Mem *pMem, char *zBuf){
66360   char *zCsr = zBuf;
66361   int f = pMem->flags;
66362 
66363   static const char *const encnames[] = {"(X)", "(8)", "(16LE)", "(16BE)"};
66364 
66365   if( f&MEM_Blob ){
66366     int i;
66367     char c;
66368     if( f & MEM_Dyn ){
66369       c = 'z';
66370       assert( (f & (MEM_Static|MEM_Ephem))==0 );
66371     }else if( f & MEM_Static ){
66372       c = 't';
66373       assert( (f & (MEM_Dyn|MEM_Ephem))==0 );
66374     }else if( f & MEM_Ephem ){
66375       c = 'e';
66376       assert( (f & (MEM_Static|MEM_Dyn))==0 );
66377     }else{
66378       c = 's';
66379     }
66380 
66381     sqlite3_snprintf(100, zCsr, "%c", c);
66382     zCsr += sqlite3Strlen30(zCsr);
66383     sqlite3_snprintf(100, zCsr, "%d[", pMem->n);
66384     zCsr += sqlite3Strlen30(zCsr);
66385     for(i=0; i<16 && i<pMem->n; i++){
66386       sqlite3_snprintf(100, zCsr, "%02X", ((int)pMem->z[i] & 0xFF));
66387       zCsr += sqlite3Strlen30(zCsr);
66388     }
66389     for(i=0; i<16 && i<pMem->n; i++){
66390       char z = pMem->z[i];
66391       if( z<32 || z>126 ) *zCsr++ = '.';
66392       else *zCsr++ = z;
66393     }
66394 
66395     sqlite3_snprintf(100, zCsr, "]%s", encnames[pMem->enc]);
66396     zCsr += sqlite3Strlen30(zCsr);
66397     if( f & MEM_Zero ){
66398       sqlite3_snprintf(100, zCsr,"+%dz",pMem->u.nZero);
66399       zCsr += sqlite3Strlen30(zCsr);
66400     }
66401     *zCsr = '\0';
66402   }else if( f & MEM_Str ){
66403     int j, k;
66404     zBuf[0] = ' ';
66405     if( f & MEM_Dyn ){
66406       zBuf[1] = 'z';
66407       assert( (f & (MEM_Static|MEM_Ephem))==0 );
66408     }else if( f & MEM_Static ){
66409       zBuf[1] = 't';
66410       assert( (f & (MEM_Dyn|MEM_Ephem))==0 );
66411     }else if( f & MEM_Ephem ){
66412       zBuf[1] = 'e';
66413       assert( (f & (MEM_Static|MEM_Dyn))==0 );
66414     }else{
66415       zBuf[1] = 's';
66416     }
66417     k = 2;
66418     sqlite3_snprintf(100, &zBuf[k], "%d", pMem->n);
66419     k += sqlite3Strlen30(&zBuf[k]);
66420     zBuf[k++] = '[';
66421     for(j=0; j<15 && j<pMem->n; j++){
66422       u8 c = pMem->z[j];
66423       if( c>=0x20 && c<0x7f ){
66424         zBuf[k++] = c;
66425       }else{
66426         zBuf[k++] = '.';
66427       }
66428     }
66429     zBuf[k++] = ']';
66430     sqlite3_snprintf(100,&zBuf[k], encnames[pMem->enc]);
66431     k += sqlite3Strlen30(&zBuf[k]);
66432     zBuf[k++] = 0;
66433   }
66434 }
66435 #endif
66436 
66437 #ifdef SQLITE_DEBUG
66438 /*
66439 ** Print the value of a register for tracing purposes:
66440 */
66441 static void memTracePrint(Mem *p){
66442   if( p->flags & MEM_Invalid ){
66443     printf(" undefined");
66444   }else if( p->flags & MEM_Null ){
66445     printf(" NULL");
66446   }else if( (p->flags & (MEM_Int|MEM_Str))==(MEM_Int|MEM_Str) ){
66447     printf(" si:%lld", p->u.i);
66448   }else if( p->flags & MEM_Int ){
66449     printf(" i:%lld", p->u.i);
66450 #ifndef SQLITE_OMIT_FLOATING_POINT
66451   }else if( p->flags & MEM_Real ){
66452     printf(" r:%g", p->r);
66453 #endif
66454   }else if( p->flags & MEM_RowSet ){
66455     printf(" (rowset)");
66456   }else{
66457     char zBuf[200];
66458     sqlite3VdbeMemPrettyPrint(p, zBuf);
66459     printf(" %s", zBuf);
66460   }
66461 }
66462 static void registerTrace(int iReg, Mem *p){
66463   printf("REG[%d] = ", iReg);
66464   memTracePrint(p);
66465   printf("\n");
66466 }
66467 #endif
66468 
66469 #ifdef SQLITE_DEBUG
66470 #  define REGISTER_TRACE(R,M) if(db->flags&SQLITE_VdbeTrace)registerTrace(R,M)
66471 #else
66472 #  define REGISTER_TRACE(R,M)
66473 #endif
66474 
66475 
66476 #ifdef VDBE_PROFILE
66477 
66478 /* 
66479 ** hwtime.h contains inline assembler code for implementing 
66480 ** high-performance timing routines.
66481 */
66482 /************** Include hwtime.h in the middle of vdbe.c *********************/
66483 /************** Begin file hwtime.h ******************************************/
66484 /*
66485 ** 2008 May 27
66486 **
66487 ** The author disclaims copyright to this source code.  In place of
66488 ** a legal notice, here is a blessing:
66489 **
66490 **    May you do good and not evil.
66491 **    May you find forgiveness for yourself and forgive others.
66492 **    May you share freely, never taking more than you give.
66493 **
66494 ******************************************************************************
66495 **
66496 ** This file contains inline asm code for retrieving "high-performance"
66497 ** counters for x86 class CPUs.
66498 */
66499 #ifndef _HWTIME_H_
66500 #define _HWTIME_H_
66501 
66502 /*
66503 ** The following routine only works on pentium-class (or newer) processors.
66504 ** It uses the RDTSC opcode to read the cycle count value out of the
66505 ** processor and returns that value.  This can be used for high-res
66506 ** profiling.
66507 */
66508 #if (defined(__GNUC__) || defined(_MSC_VER)) && \
66509       (defined(i386) || defined(__i386__) || defined(_M_IX86))
66510 
66511   #if defined(__GNUC__)
66512 
66513   __inline__ sqlite_uint64 sqlite3Hwtime(void){
66514      unsigned int lo, hi;
66515      __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi));
66516      return (sqlite_uint64)hi << 32 | lo;
66517   }
66518 
66519   #elif defined(_MSC_VER)
66520 
66521   __declspec(naked) __inline sqlite_uint64 __cdecl sqlite3Hwtime(void){
66522      __asm {
66523         rdtsc
66524         ret       ; return value at EDX:EAX
66525      }
66526   }
66527 
66528   #endif
66529 
66530 #elif (defined(__GNUC__) && defined(__x86_64__))
66531 
66532   __inline__ sqlite_uint64 sqlite3Hwtime(void){
66533       unsigned long val;
66534       __asm__ __volatile__ ("rdtsc" : "=A" (val));
66535       return val;
66536   }
66537  
66538 #elif (defined(__GNUC__) && defined(__ppc__))
66539 
66540   __inline__ sqlite_uint64 sqlite3Hwtime(void){
66541       unsigned long long retval;
66542       unsigned long junk;
66543       __asm__ __volatile__ ("\n\
66544           1:      mftbu   %1\n\
66545                   mftb    %L0\n\
66546                   mftbu   %0\n\
66547                   cmpw    %0,%1\n\
66548                   bne     1b"
66549                   : "=r" (retval), "=r" (junk));
66550       return retval;
66551   }
66552 
66553 #else
66554 
66555   #error Need implementation of sqlite3Hwtime() for your platform.
66556 
66557   /*
66558   ** To compile without implementing sqlite3Hwtime() for your platform,
66559   ** you can remove the above #error and use the following
66560   ** stub function.  You will lose timing support for many
66561   ** of the debugging and testing utilities, but it should at
66562   ** least compile and run.
66563   */
66564 SQLITE_PRIVATE   sqlite_uint64 sqlite3Hwtime(void){ return ((sqlite_uint64)0); }
66565 
66566 #endif
66567 
66568 #endif /* !defined(_HWTIME_H_) */
66569 
66570 /************** End of hwtime.h **********************************************/
66571 /************** Continuing where we left off in vdbe.c ***********************/
66572 
66573 #endif
66574 
66575 /*
66576 ** The CHECK_FOR_INTERRUPT macro defined here looks to see if the
66577 ** sqlite3_interrupt() routine has been called.  If it has been, then
66578 ** processing of the VDBE program is interrupted.
66579 **
66580 ** This macro added to every instruction that does a jump in order to
66581 ** implement a loop.  This test used to be on every single instruction,
66582 ** but that meant we more testing than we needed.  By only testing the
66583 ** flag on jump instructions, we get a (small) speed improvement.
66584 */
66585 #define CHECK_FOR_INTERRUPT \
66586    if( db->u1.isInterrupted ) goto abort_due_to_interrupt;
66587 
66588 
66589 #ifndef NDEBUG
66590 /*
66591 ** This function is only called from within an assert() expression. It
66592 ** checks that the sqlite3.nTransaction variable is correctly set to
66593 ** the number of non-transaction savepoints currently in the 
66594 ** linked list starting at sqlite3.pSavepoint.
66595 ** 
66596 ** Usage:
66597 **
66598 **     assert( checkSavepointCount(db) );
66599 */
66600 static int checkSavepointCount(sqlite3 *db){
66601   int n = 0;
66602   Savepoint *p;
66603   for(p=db->pSavepoint; p; p=p->pNext) n++;
66604   assert( n==(db->nSavepoint + db->isTransactionSavepoint) );
66605   return 1;
66606 }
66607 #endif
66608 
66609 
66610 /*
66611 ** Execute as much of a VDBE program as we can then return.
66612 **
66613 ** sqlite3VdbeMakeReady() must be called before this routine in order to
66614 ** close the program with a final OP_Halt and to set up the callbacks
66615 ** and the error message pointer.
66616 **
66617 ** Whenever a row or result data is available, this routine will either
66618 ** invoke the result callback (if there is one) or return with
66619 ** SQLITE_ROW.
66620 **
66621 ** If an attempt is made to open a locked database, then this routine
66622 ** will either invoke the busy callback (if there is one) or it will
66623 ** return SQLITE_BUSY.
66624 **
66625 ** If an error occurs, an error message is written to memory obtained
66626 ** from sqlite3_malloc() and p->zErrMsg is made to point to that memory.
66627 ** The error code is stored in p->rc and this routine returns SQLITE_ERROR.
66628 **
66629 ** If the callback ever returns non-zero, then the program exits
66630 ** immediately.  There will be no error message but the p->rc field is
66631 ** set to SQLITE_ABORT and this routine will return SQLITE_ERROR.
66632 **
66633 ** A memory allocation error causes p->rc to be set to SQLITE_NOMEM and this
66634 ** routine to return SQLITE_ERROR.
66635 **
66636 ** Other fatal errors return SQLITE_ERROR.
66637 **
66638 ** After this routine has finished, sqlite3VdbeFinalize() should be
66639 ** used to clean up the mess that was left behind.
66640 */
66641 SQLITE_PRIVATE int sqlite3VdbeExec(
66642   Vdbe *p                    /* The VDBE */
66643 ){
66644   int pc=0;                  /* The program counter */
66645   Op *aOp = p->aOp;          /* Copy of p->aOp */
66646   Op *pOp;                   /* Current operation */
66647   int rc = SQLITE_OK;        /* Value to return */
66648   sqlite3 *db = p->db;       /* The database */
66649   u8 resetSchemaOnFault = 0; /* Reset schema after an error if positive */
66650   u8 encoding = ENC(db);     /* The database encoding */
66651   int iCompare = 0;          /* Result of last OP_Compare operation */
66652   unsigned nVmStep = 0;      /* Number of virtual machine steps */
66653 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
66654   unsigned nProgressLimit = 0;/* Invoke xProgress() when nVmStep reaches this */
66655 #endif
66656   Mem *aMem = p->aMem;       /* Copy of p->aMem */
66657   Mem *pIn1 = 0;             /* 1st input operand */
66658   Mem *pIn2 = 0;             /* 2nd input operand */
66659   Mem *pIn3 = 0;             /* 3rd input operand */
66660   Mem *pOut = 0;             /* Output operand */
66661   int *aPermute = 0;         /* Permutation of columns for OP_Compare */
66662   i64 lastRowid = db->lastRowid;  /* Saved value of the last insert ROWID */
66663 #ifdef VDBE_PROFILE
66664   u64 start;                 /* CPU clock count at start of opcode */
66665   int origPc;                /* Program counter at start of opcode */
66666 #endif
66667   /********************************************************************
66668   ** Automatically generated code
66669   **
66670   ** The following union is automatically generated by the
66671   ** vdbe-compress.tcl script.  The purpose of this union is to
66672   ** reduce the amount of stack space required by this function.
66673   ** See comments in the vdbe-compress.tcl script for details.
66674   */
66675   union vdbeExecUnion {
66676     struct OP_Yield_stack_vars {
66677       int pcDest;
66678     } aa;
66679     struct OP_Halt_stack_vars {
66680       const char *zType;
66681       const char *zLogFmt;
66682     } ab;
66683     struct OP_Null_stack_vars {
66684       int cnt;
66685       u16 nullFlag;
66686     } ac;
66687     struct OP_Variable_stack_vars {
66688       Mem *pVar;       /* Value being transferred */
66689     } ad;
66690     struct OP_Move_stack_vars {
66691       char *zMalloc;   /* Holding variable for allocated memory */
66692       int n;           /* Number of registers left to copy */
66693       int p1;          /* Register to copy from */
66694       int p2;          /* Register to copy to */
66695     } ae;
66696     struct OP_Copy_stack_vars {
66697       int n;
66698     } af;
66699     struct OP_ResultRow_stack_vars {
66700       Mem *pMem;
66701       int i;
66702     } ag;
66703     struct OP_Concat_stack_vars {
66704       i64 nByte;
66705     } ah;
66706     struct OP_Remainder_stack_vars {
66707       char bIntint;   /* Started out as two integer operands */
66708       int flags;      /* Combined MEM_* flags from both inputs */
66709       i64 iA;         /* Integer value of left operand */
66710       i64 iB;         /* Integer value of right operand */
66711       double rA;      /* Real value of left operand */
66712       double rB;      /* Real value of right operand */
66713     } ai;
66714     struct OP_Function_stack_vars {
66715       int i;
66716       Mem *pArg;
66717       sqlite3_context ctx;
66718       sqlite3_value **apVal;
66719       int n;
66720     } aj;
66721     struct OP_ShiftRight_stack_vars {
66722       i64 iA;
66723       u64 uA;
66724       i64 iB;
66725       u8 op;
66726     } ak;
66727     struct OP_Ge_stack_vars {
66728       int res;            /* Result of the comparison of pIn1 against pIn3 */
66729       char affinity;      /* Affinity to use for comparison */
66730       u16 flags1;         /* Copy of initial value of pIn1->flags */
66731       u16 flags3;         /* Copy of initial value of pIn3->flags */
66732     } al;
66733     struct OP_Compare_stack_vars {
66734       int n;
66735       int i;
66736       int p1;
66737       int p2;
66738       const KeyInfo *pKeyInfo;
66739       int idx;
66740       CollSeq *pColl;    /* Collating sequence to use on this term */
66741       int bRev;          /* True for DESCENDING sort order */
66742     } am;
66743     struct OP_Or_stack_vars {
66744       int v1;    /* Left operand:  0==FALSE, 1==TRUE, 2==UNKNOWN or NULL */
66745       int v2;    /* Right operand: 0==FALSE, 1==TRUE, 2==UNKNOWN or NULL */
66746     } an;
66747     struct OP_IfNot_stack_vars {
66748       int c;
66749     } ao;
66750     struct OP_Column_stack_vars {
66751       i64 payloadSize64; /* Number of bytes in the record */
66752       int p2;            /* column number to retrieve */
66753       VdbeCursor *pC;    /* The VDBE cursor */
66754       BtCursor *pCrsr;   /* The BTree cursor */
66755       u32 *aType;        /* aType[i] holds the numeric type of the i-th column */
66756       u32 *aOffset;      /* aOffset[i] is offset to start of data for i-th column */
66757       int len;           /* The length of the serialized data for the column */
66758       int i;             /* Loop counter */
66759       Mem *pDest;        /* Where to write the extracted value */
66760       Mem sMem;          /* For storing the record being decoded */
66761       const u8 *zData;   /* Part of the record being decoded */
66762       const u8 *zHdr;    /* Next unparsed byte of the header */
66763       const u8 *zEndHdr; /* Pointer to first byte after the header */
66764       u32 offset;        /* Offset into the data */
66765       u32 szField;       /* Number of bytes in the content of a field */
66766       u32 avail;         /* Number of bytes of available data */
66767       u32 t;             /* A type code from the record header */
66768       Mem *pReg;         /* PseudoTable input register */
66769     } ap;
66770     struct OP_Affinity_stack_vars {
66771       const char *zAffinity;   /* The affinity to be applied */
66772       char cAff;               /* A single character of affinity */
66773     } aq;
66774     struct OP_MakeRecord_stack_vars {
66775       u8 *zNewRecord;        /* A buffer to hold the data for the new record */
66776       Mem *pRec;             /* The new record */
66777       u64 nData;             /* Number of bytes of data space */
66778       int nHdr;              /* Number of bytes of header space */
66779       i64 nByte;             /* Data space required for this record */
66780       int nZero;             /* Number of zero bytes at the end of the record */
66781       int nVarint;           /* Number of bytes in a varint */
66782       u32 serial_type;       /* Type field */
66783       Mem *pData0;           /* First field to be combined into the record */
66784       Mem *pLast;            /* Last field of the record */
66785       int nField;            /* Number of fields in the record */
66786       char *zAffinity;       /* The affinity string for the record */
66787       int file_format;       /* File format to use for encoding */
66788       int i;                 /* Space used in zNewRecord[] */
66789       int len;               /* Length of a field */
66790     } ar;
66791     struct OP_Count_stack_vars {
66792       i64 nEntry;
66793       BtCursor *pCrsr;
66794     } as;
66795     struct OP_Savepoint_stack_vars {
66796       int p1;                         /* Value of P1 operand */
66797       char *zName;                    /* Name of savepoint */
66798       int nName;
66799       Savepoint *pNew;
66800       Savepoint *pSavepoint;
66801       Savepoint *pTmp;
66802       int iSavepoint;
66803       int ii;
66804     } at;
66805     struct OP_AutoCommit_stack_vars {
66806       int desiredAutoCommit;
66807       int iRollback;
66808       int turnOnAC;
66809     } au;
66810     struct OP_Transaction_stack_vars {
66811       Btree *pBt;
66812     } av;
66813     struct OP_ReadCookie_stack_vars {
66814       int iMeta;
66815       int iDb;
66816       int iCookie;
66817     } aw;
66818     struct OP_SetCookie_stack_vars {
66819       Db *pDb;
66820     } ax;
66821     struct OP_VerifyCookie_stack_vars {
66822       int iMeta;
66823       int iGen;
66824       Btree *pBt;
66825     } ay;
66826     struct OP_OpenWrite_stack_vars {
66827       int nField;
66828       KeyInfo *pKeyInfo;
66829       int p2;
66830       int iDb;
66831       int wrFlag;
66832       Btree *pX;
66833       VdbeCursor *pCur;
66834       Db *pDb;
66835     } az;
66836     struct OP_OpenEphemeral_stack_vars {
66837       VdbeCursor *pCx;
66838       KeyInfo *pKeyInfo;
66839     } ba;
66840     struct OP_SorterOpen_stack_vars {
66841       VdbeCursor *pCx;
66842     } bb;
66843     struct OP_OpenPseudo_stack_vars {
66844       VdbeCursor *pCx;
66845     } bc;
66846     struct OP_SeekGt_stack_vars {
66847       int res;
66848       int oc;
66849       VdbeCursor *pC;
66850       UnpackedRecord r;
66851       int nField;
66852       i64 iKey;      /* The rowid we are to seek to */
66853     } bd;
66854     struct OP_Seek_stack_vars {
66855       VdbeCursor *pC;
66856     } be;
66857     struct OP_Found_stack_vars {
66858       int alreadyExists;
66859       int ii;
66860       VdbeCursor *pC;
66861       int res;
66862       char *pFree;
66863       UnpackedRecord *pIdxKey;
66864       UnpackedRecord r;
66865       char aTempRec[ROUND8(sizeof(UnpackedRecord)) + sizeof(Mem)*4 + 7];
66866     } bf;
66867     struct OP_NotExists_stack_vars {
66868       VdbeCursor *pC;
66869       BtCursor *pCrsr;
66870       int res;
66871       u64 iKey;
66872     } bg;
66873     struct OP_NewRowid_stack_vars {
66874       i64 v;                 /* The new rowid */
66875       VdbeCursor *pC;        /* Cursor of table to get the new rowid */
66876       int res;               /* Result of an sqlite3BtreeLast() */
66877       int cnt;               /* Counter to limit the number of searches */
66878       Mem *pMem;             /* Register holding largest rowid for AUTOINCREMENT */
66879       VdbeFrame *pFrame;     /* Root frame of VDBE */
66880     } bh;
66881     struct OP_InsertInt_stack_vars {
66882       Mem *pData;       /* MEM cell holding data for the record to be inserted */
66883       Mem *pKey;        /* MEM cell holding key  for the record */
66884       i64 iKey;         /* The integer ROWID or key for the record to be inserted */
66885       VdbeCursor *pC;   /* Cursor to table into which insert is written */
66886       int nZero;        /* Number of zero-bytes to append */
66887       int seekResult;   /* Result of prior seek or 0 if no USESEEKRESULT flag */
66888       const char *zDb;  /* database name - used by the update hook */
66889       const char *zTbl; /* Table name - used by the opdate hook */
66890       int op;           /* Opcode for update hook: SQLITE_UPDATE or SQLITE_INSERT */
66891     } bi;
66892     struct OP_Delete_stack_vars {
66893       i64 iKey;
66894       VdbeCursor *pC;
66895     } bj;
66896     struct OP_SorterCompare_stack_vars {
66897       VdbeCursor *pC;
66898       int res;
66899       int nIgnore;
66900     } bk;
66901     struct OP_SorterData_stack_vars {
66902       VdbeCursor *pC;
66903     } bl;
66904     struct OP_RowData_stack_vars {
66905       VdbeCursor *pC;
66906       BtCursor *pCrsr;
66907       u32 n;
66908       i64 n64;
66909     } bm;
66910     struct OP_Rowid_stack_vars {
66911       VdbeCursor *pC;
66912       i64 v;
66913       sqlite3_vtab *pVtab;
66914       const sqlite3_module *pModule;
66915     } bn;
66916     struct OP_NullRow_stack_vars {
66917       VdbeCursor *pC;
66918     } bo;
66919     struct OP_Last_stack_vars {
66920       VdbeCursor *pC;
66921       BtCursor *pCrsr;
66922       int res;
66923     } bp;
66924     struct OP_Rewind_stack_vars {
66925       VdbeCursor *pC;
66926       BtCursor *pCrsr;
66927       int res;
66928     } bq;
66929     struct OP_SorterNext_stack_vars {
66930       VdbeCursor *pC;
66931       int res;
66932     } br;
66933     struct OP_IdxInsert_stack_vars {
66934       VdbeCursor *pC;
66935       BtCursor *pCrsr;
66936       int nKey;
66937       const char *zKey;
66938     } bs;
66939     struct OP_IdxDelete_stack_vars {
66940       VdbeCursor *pC;
66941       BtCursor *pCrsr;
66942       int res;
66943       UnpackedRecord r;
66944     } bt;
66945     struct OP_IdxRowid_stack_vars {
66946       BtCursor *pCrsr;
66947       VdbeCursor *pC;
66948       i64 rowid;
66949     } bu;
66950     struct OP_IdxGE_stack_vars {
66951       VdbeCursor *pC;
66952       int res;
66953       UnpackedRecord r;
66954     } bv;
66955     struct OP_Destroy_stack_vars {
66956       int iMoved;
66957       int iCnt;
66958       Vdbe *pVdbe;
66959       int iDb;
66960     } bw;
66961     struct OP_Clear_stack_vars {
66962       int nChange;
66963     } bx;
66964     struct OP_CreateTable_stack_vars {
66965       int pgno;
66966       int flags;
66967       Db *pDb;
66968     } by;
66969     struct OP_ParseSchema_stack_vars {
66970       int iDb;
66971       const char *zMaster;
66972       char *zSql;
66973       InitData initData;
66974     } bz;
66975     struct OP_IntegrityCk_stack_vars {
66976       int nRoot;      /* Number of tables to check.  (Number of root pages.) */
66977       int *aRoot;     /* Array of rootpage numbers for tables to be checked */
66978       int j;          /* Loop counter */
66979       int nErr;       /* Number of errors reported */
66980       char *z;        /* Text of the error report */
66981       Mem *pnErr;     /* Register keeping track of errors remaining */
66982     } ca;
66983     struct OP_RowSetRead_stack_vars {
66984       i64 val;
66985     } cb;
66986     struct OP_RowSetTest_stack_vars {
66987       int iSet;
66988       int exists;
66989     } cc;
66990     struct OP_Program_stack_vars {
66991       int nMem;               /* Number of memory registers for sub-program */
66992       int nByte;              /* Bytes of runtime space required for sub-program */
66993       Mem *pRt;               /* Register to allocate runtime space */
66994       Mem *pMem;              /* Used to iterate through memory cells */
66995       Mem *pEnd;              /* Last memory cell in new array */
66996       VdbeFrame *pFrame;      /* New vdbe frame to execute in */
66997       SubProgram *pProgram;   /* Sub-program to execute */
66998       void *t;                /* Token identifying trigger */
66999     } cd;
67000     struct OP_Param_stack_vars {
67001       VdbeFrame *pFrame;
67002       Mem *pIn;
67003     } ce;
67004     struct OP_MemMax_stack_vars {
67005       Mem *pIn1;
67006       VdbeFrame *pFrame;
67007     } cf;
67008     struct OP_AggStep_stack_vars {
67009       int n;
67010       int i;
67011       Mem *pMem;
67012       Mem *pRec;
67013       sqlite3_context ctx;
67014       sqlite3_value **apVal;
67015     } cg;
67016     struct OP_AggFinal_stack_vars {
67017       Mem *pMem;
67018     } ch;
67019     struct OP_Checkpoint_stack_vars {
67020       int i;                          /* Loop counter */
67021       int aRes[3];                    /* Results */
67022       Mem *pMem;                      /* Write results here */
67023     } ci;
67024     struct OP_JournalMode_stack_vars {
67025       Btree *pBt;                     /* Btree to change journal mode of */
67026       Pager *pPager;                  /* Pager associated with pBt */
67027       int eNew;                       /* New journal mode */
67028       int eOld;                       /* The old journal mode */
67029 #ifndef SQLITE_OMIT_WAL
67030       const char *zFilename;          /* Name of database file for pPager */
67031 #endif
67032     } cj;
67033     struct OP_IncrVacuum_stack_vars {
67034       Btree *pBt;
67035     } ck;
67036     struct OP_VBegin_stack_vars {
67037       VTable *pVTab;
67038     } cl;
67039     struct OP_VOpen_stack_vars {
67040       VdbeCursor *pCur;
67041       sqlite3_vtab_cursor *pVtabCursor;
67042       sqlite3_vtab *pVtab;
67043       sqlite3_module *pModule;
67044     } cm;
67045     struct OP_VFilter_stack_vars {
67046       int nArg;
67047       int iQuery;
67048       const sqlite3_module *pModule;
67049       Mem *pQuery;
67050       Mem *pArgc;
67051       sqlite3_vtab_cursor *pVtabCursor;
67052       sqlite3_vtab *pVtab;
67053       VdbeCursor *pCur;
67054       int res;
67055       int i;
67056       Mem **apArg;
67057     } cn;
67058     struct OP_VColumn_stack_vars {
67059       sqlite3_vtab *pVtab;
67060       const sqlite3_module *pModule;
67061       Mem *pDest;
67062       sqlite3_context sContext;
67063     } co;
67064     struct OP_VNext_stack_vars {
67065       sqlite3_vtab *pVtab;
67066       const sqlite3_module *pModule;
67067       int res;
67068       VdbeCursor *pCur;
67069     } cp;
67070     struct OP_VRename_stack_vars {
67071       sqlite3_vtab *pVtab;
67072       Mem *pName;
67073     } cq;
67074     struct OP_VUpdate_stack_vars {
67075       sqlite3_vtab *pVtab;
67076       sqlite3_module *pModule;
67077       int nArg;
67078       int i;
67079       sqlite_int64 rowid;
67080       Mem **apArg;
67081       Mem *pX;
67082     } cr;
67083     struct OP_Trace_stack_vars {
67084       char *zTrace;
67085       char *z;
67086     } cs;
67087   } u;
67088   /* End automatically generated code
67089   ********************************************************************/
67090 
67091   assert( p->magic==VDBE_MAGIC_RUN );  /* sqlite3_step() verifies this */
67092   sqlite3VdbeEnter(p);
67093   if( p->rc==SQLITE_NOMEM ){
67094     /* This happens if a malloc() inside a call to sqlite3_column_text() or
67095     ** sqlite3_column_text16() failed.  */
67096     goto no_mem;
67097   }
67098   assert( p->rc==SQLITE_OK || p->rc==SQLITE_BUSY );
67099   assert( p->bIsReader || p->readOnly!=0 );
67100   p->rc = SQLITE_OK;
67101   p->iCurrentTime = 0;
67102   assert( p->explain==0 );
67103   p->pResultSet = 0;
67104   db->busyHandler.nBusy = 0;
67105   CHECK_FOR_INTERRUPT;
67106   sqlite3VdbeIOTraceSql(p);
67107 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
67108   if( db->xProgress ){
67109     assert( 0 < db->nProgressOps );
67110     nProgressLimit = (unsigned)p->aCounter[SQLITE_STMTSTATUS_VM_STEP];
67111     if( nProgressLimit==0 ){
67112       nProgressLimit = db->nProgressOps;
67113     }else{
67114       nProgressLimit %= (unsigned)db->nProgressOps;
67115     }
67116   }
67117 #endif
67118 #ifdef SQLITE_DEBUG
67119   sqlite3BeginBenignMalloc();
67120   if( p->pc==0
67121    && (p->db->flags & (SQLITE_VdbeListing|SQLITE_VdbeEQP|SQLITE_VdbeTrace))!=0
67122   ){
67123     int i;
67124     int once = 1;
67125     sqlite3VdbePrintSql(p);
67126     if( p->db->flags & SQLITE_VdbeListing ){
67127       printf("VDBE Program Listing:\n");
67128       for(i=0; i<p->nOp; i++){
67129         sqlite3VdbePrintOp(stdout, i, &aOp[i]);
67130       }
67131     }
67132     if( p->db->flags & SQLITE_VdbeEQP ){
67133       for(i=0; i<p->nOp; i++){
67134         if( aOp[i].opcode==OP_Explain ){
67135           if( once ) printf("VDBE Query Plan:\n");
67136           printf("%s\n", aOp[i].p4.z);
67137           once = 0;
67138         }
67139       }
67140     }
67141     if( p->db->flags & SQLITE_VdbeTrace )  printf("VDBE Trace:\n");
67142   }
67143   sqlite3EndBenignMalloc();
67144 #endif
67145   for(pc=p->pc; rc==SQLITE_OK; pc++){
67146     assert( pc>=0 && pc<p->nOp );
67147     if( db->mallocFailed ) goto no_mem;
67148 #ifdef VDBE_PROFILE
67149     origPc = pc;
67150     start = sqlite3Hwtime();
67151 #endif
67152     nVmStep++;
67153     pOp = &aOp[pc];
67154 
67155     /* Only allow tracing if SQLITE_DEBUG is defined.
67156     */
67157 #ifdef SQLITE_DEBUG
67158     if( db->flags & SQLITE_VdbeTrace ){
67159       sqlite3VdbePrintOp(stdout, pc, pOp);
67160     }
67161 #endif
67162       
67163 
67164     /* Check to see if we need to simulate an interrupt.  This only happens
67165     ** if we have a special test build.
67166     */
67167 #ifdef SQLITE_TEST
67168     if( sqlite3_interrupt_count>0 ){
67169       sqlite3_interrupt_count--;
67170       if( sqlite3_interrupt_count==0 ){
67171         sqlite3_interrupt(db);
67172       }
67173     }
67174 #endif
67175 
67176     /* On any opcode with the "out2-prerelease" tag, free any
67177     ** external allocations out of mem[p2] and set mem[p2] to be
67178     ** an undefined integer.  Opcodes will either fill in the integer
67179     ** value or convert mem[p2] to a different type.
67180     */
67181     assert( pOp->opflags==sqlite3OpcodeProperty[pOp->opcode] );
67182     if( pOp->opflags & OPFLG_OUT2_PRERELEASE ){
67183       assert( pOp->p2>0 );
67184       assert( pOp->p2<=(p->nMem-p->nCursor) );
67185       pOut = &aMem[pOp->p2];
67186       memAboutToChange(p, pOut);
67187       VdbeMemRelease(pOut);
67188       pOut->flags = MEM_Int;
67189     }
67190 
67191     /* Sanity checking on other operands */
67192 #ifdef SQLITE_DEBUG
67193     if( (pOp->opflags & OPFLG_IN1)!=0 ){
67194       assert( pOp->p1>0 );
67195       assert( pOp->p1<=(p->nMem-p->nCursor) );
67196       assert( memIsValid(&aMem[pOp->p1]) );
67197       REGISTER_TRACE(pOp->p1, &aMem[pOp->p1]);
67198     }
67199     if( (pOp->opflags & OPFLG_IN2)!=0 ){
67200       assert( pOp->p2>0 );
67201       assert( pOp->p2<=(p->nMem-p->nCursor) );
67202       assert( memIsValid(&aMem[pOp->p2]) );
67203       REGISTER_TRACE(pOp->p2, &aMem[pOp->p2]);
67204     }
67205     if( (pOp->opflags & OPFLG_IN3)!=0 ){
67206       assert( pOp->p3>0 );
67207       assert( pOp->p3<=(p->nMem-p->nCursor) );
67208       assert( memIsValid(&aMem[pOp->p3]) );
67209       REGISTER_TRACE(pOp->p3, &aMem[pOp->p3]);
67210     }
67211     if( (pOp->opflags & OPFLG_OUT2)!=0 ){
67212       assert( pOp->p2>0 );
67213       assert( pOp->p2<=(p->nMem-p->nCursor) );
67214       memAboutToChange(p, &aMem[pOp->p2]);
67215     }
67216     if( (pOp->opflags & OPFLG_OUT3)!=0 ){
67217       assert( pOp->p3>0 );
67218       assert( pOp->p3<=(p->nMem-p->nCursor) );
67219       memAboutToChange(p, &aMem[pOp->p3]);
67220     }
67221 #endif
67222   
67223     switch( pOp->opcode ){
67224 
67225 /*****************************************************************************
67226 ** What follows is a massive switch statement where each case implements a
67227 ** separate instruction in the virtual machine.  If we follow the usual
67228 ** indentation conventions, each case should be indented by 6 spaces.  But
67229 ** that is a lot of wasted space on the left margin.  So the code within
67230 ** the switch statement will break with convention and be flush-left. Another
67231 ** big comment (similar to this one) will mark the point in the code where
67232 ** we transition back to normal indentation.
67233 **
67234 ** The formatting of each case is important.  The makefile for SQLite
67235 ** generates two C files "opcodes.h" and "opcodes.c" by scanning this
67236 ** file looking for lines that begin with "case OP_".  The opcodes.h files
67237 ** will be filled with #defines that give unique integer values to each
67238 ** opcode and the opcodes.c file is filled with an array of strings where
67239 ** each string is the symbolic name for the corresponding opcode.  If the
67240 ** case statement is followed by a comment of the form "/# same as ... #/"
67241 ** that comment is used to determine the particular value of the opcode.
67242 **
67243 ** Other keywords in the comment that follows each case are used to
67244 ** construct the OPFLG_INITIALIZER value that initializes opcodeProperty[].
67245 ** Keywords include: in1, in2, in3, out2_prerelease, out2, out3.  See
67246 ** the mkopcodeh.awk script for additional information.
67247 **
67248 ** Documentation about VDBE opcodes is generated by scanning this file
67249 ** for lines of that contain "Opcode:".  That line and all subsequent
67250 ** comment lines are used in the generation of the opcode.html documentation
67251 ** file.
67252 **
67253 ** SUMMARY:
67254 **
67255 **     Formatting is important to scripts that scan this file.
67256 **     Do not deviate from the formatting style currently in use.
67257 **
67258 *****************************************************************************/
67259 
67260 /* Opcode:  Goto * P2 * * *
67261 **
67262 ** An unconditional jump to address P2.
67263 ** The next instruction executed will be 
67264 ** the one at index P2 from the beginning of
67265 ** the program.
67266 */
67267 case OP_Goto: {             /* jump */
67268   pc = pOp->p2 - 1;
67269 
67270   /* Opcodes that are used as the bottom of a loop (OP_Next, OP_Prev,
67271   ** OP_VNext, OP_RowSetNext, or OP_SorterNext) all jump here upon
67272   ** completion.  Check to see if sqlite3_interrupt() has been called
67273   ** or if the progress callback needs to be invoked. 
67274   **
67275   ** This code uses unstructured "goto" statements and does not look clean.
67276   ** But that is not due to sloppy coding habits. The code is written this
67277   ** way for performance, to avoid having to run the interrupt and progress
67278   ** checks on every opcode.  This helps sqlite3_step() to run about 1.5%
67279   ** faster according to "valgrind --tool=cachegrind" */
67280 check_for_interrupt:
67281   CHECK_FOR_INTERRUPT;
67282 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
67283   /* Call the progress callback if it is configured and the required number
67284   ** of VDBE ops have been executed (either since this invocation of
67285   ** sqlite3VdbeExec() or since last time the progress callback was called).
67286   ** If the progress callback returns non-zero, exit the virtual machine with
67287   ** a return code SQLITE_ABORT.
67288   */
67289   if( db->xProgress!=0 && nVmStep>=nProgressLimit ){
67290     assert( db->nProgressOps!=0 );
67291     nProgressLimit = nVmStep + db->nProgressOps - (nVmStep%db->nProgressOps);
67292     if( db->xProgress(db->pProgressArg) ){
67293       rc = SQLITE_INTERRUPT;
67294       goto vdbe_error_halt;
67295     }
67296   }
67297 #endif
67298   
67299   break;
67300 }
67301 
67302 /* Opcode:  Gosub P1 P2 * * *
67303 **
67304 ** Write the current address onto register P1
67305 ** and then jump to address P2.
67306 */
67307 case OP_Gosub: {            /* jump */
67308   assert( pOp->p1>0 && pOp->p1<=(p->nMem-p->nCursor) );
67309   pIn1 = &aMem[pOp->p1];
67310   assert( (pIn1->flags & MEM_Dyn)==0 );
67311   memAboutToChange(p, pIn1);
67312   pIn1->flags = MEM_Int;
67313   pIn1->u.i = pc;
67314   REGISTER_TRACE(pOp->p1, pIn1);
67315   pc = pOp->p2 - 1;
67316   break;
67317 }
67318 
67319 /* Opcode:  Return P1 * * * *
67320 **
67321 ** Jump to the next instruction after the address in register P1.
67322 */
67323 case OP_Return: {           /* in1 */
67324   pIn1 = &aMem[pOp->p1];
67325   assert( pIn1->flags & MEM_Int );
67326   pc = (int)pIn1->u.i;
67327   break;
67328 }
67329 
67330 /* Opcode:  Yield P1 * * * *
67331 **
67332 ** Swap the program counter with the value in register P1.
67333 */
67334 case OP_Yield: {            /* in1 */
67335 #if 0  /* local variables moved into u.aa */
67336   int pcDest;
67337 #endif /* local variables moved into u.aa */
67338   pIn1 = &aMem[pOp->p1];
67339   assert( (pIn1->flags & MEM_Dyn)==0 );
67340   pIn1->flags = MEM_Int;
67341   u.aa.pcDest = (int)pIn1->u.i;
67342   pIn1->u.i = pc;
67343   REGISTER_TRACE(pOp->p1, pIn1);
67344   pc = u.aa.pcDest;
67345   break;
67346 }
67347 
67348 /* Opcode:  HaltIfNull  P1 P2 P3 P4 P5
67349 ** Synopsis:  if r[P3] null then halt
67350 **
67351 ** Check the value in register P3.  If it is NULL then Halt using
67352 ** parameter P1, P2, and P4 as if this were a Halt instruction.  If the
67353 ** value in register P3 is not NULL, then this routine is a no-op.
67354 ** The P5 parameter should be 1.
67355 */
67356 case OP_HaltIfNull: {      /* in3 */
67357   pIn3 = &aMem[pOp->p3];
67358   if( (pIn3->flags & MEM_Null)==0 ) break;
67359   /* Fall through into OP_Halt */
67360 }
67361 
67362 /* Opcode:  Halt P1 P2 * P4 P5
67363 **
67364 ** Exit immediately.  All open cursors, etc are closed
67365 ** automatically.
67366 **
67367 ** P1 is the result code returned by sqlite3_exec(), sqlite3_reset(),
67368 ** or sqlite3_finalize().  For a normal halt, this should be SQLITE_OK (0).
67369 ** For errors, it can be some other value.  If P1!=0 then P2 will determine
67370 ** whether or not to rollback the current transaction.  Do not rollback
67371 ** if P2==OE_Fail. Do the rollback if P2==OE_Rollback.  If P2==OE_Abort,
67372 ** then back out all changes that have occurred during this execution of the
67373 ** VDBE, but do not rollback the transaction. 
67374 **
67375 ** If P4 is not null then it is an error message string.
67376 **
67377 ** P5 is a value between 0 and 4, inclusive, that modifies the P4 string.
67378 **
67379 **    0:  (no change)
67380 **    1:  NOT NULL contraint failed: P4
67381 **    2:  UNIQUE constraint failed: P4
67382 **    3:  CHECK constraint failed: P4
67383 **    4:  FOREIGN KEY constraint failed: P4
67384 **
67385 ** If P5 is not zero and P4 is NULL, then everything after the ":" is
67386 ** omitted.
67387 **
67388 ** There is an implied "Halt 0 0 0" instruction inserted at the very end of
67389 ** every program.  So a jump past the last instruction of the program
67390 ** is the same as executing Halt.
67391 */
67392 case OP_Halt: {
67393 #if 0  /* local variables moved into u.ab */
67394   const char *zType;
67395   const char *zLogFmt;
67396 #endif /* local variables moved into u.ab */
67397 
67398   if( pOp->p1==SQLITE_OK && p->pFrame ){
67399     /* Halt the sub-program. Return control to the parent frame. */
67400     VdbeFrame *pFrame = p->pFrame;
67401     p->pFrame = pFrame->pParent;
67402     p->nFrame--;
67403     sqlite3VdbeSetChanges(db, p->nChange);
67404     pc = sqlite3VdbeFrameRestore(pFrame);
67405     lastRowid = db->lastRowid;
67406     if( pOp->p2==OE_Ignore ){
67407       /* Instruction pc is the OP_Program that invoked the sub-program
67408       ** currently being halted. If the p2 instruction of this OP_Halt
67409       ** instruction is set to OE_Ignore, then the sub-program is throwing
67410       ** an IGNORE exception. In this case jump to the address specified
67411       ** as the p2 of the calling OP_Program.  */
67412       pc = p->aOp[pc].p2-1;
67413     }
67414     aOp = p->aOp;
67415     aMem = p->aMem;
67416     break;
67417   }
67418   p->rc = pOp->p1;
67419   p->errorAction = (u8)pOp->p2;
67420   p->pc = pc;
67421   if( p->rc ){
67422     if( pOp->p5 ){
67423       static const char * const azType[] = { "NOT NULL", "UNIQUE", "CHECK",
67424                                              "FOREIGN KEY" };
67425       assert( pOp->p5>=1 && pOp->p5<=4 );
67426       testcase( pOp->p5==1 );
67427       testcase( pOp->p5==2 );
67428       testcase( pOp->p5==3 );
67429       testcase( pOp->p5==4 );
67430       u.ab.zType = azType[pOp->p5-1];
67431     }else{
67432       u.ab.zType = 0;
67433     }
67434     assert( u.ab.zType!=0 || pOp->p4.z!=0 );
67435     u.ab.zLogFmt = "abort at %d in [%s]: %s";
67436     if( u.ab.zType && pOp->p4.z ){
67437       sqlite3SetString(&p->zErrMsg, db, "%s constraint failed: %s",
67438                        u.ab.zType, pOp->p4.z);
67439     }else if( pOp->p4.z ){
67440       sqlite3SetString(&p->zErrMsg, db, "%s", pOp->p4.z);
67441     }else{
67442       sqlite3SetString(&p->zErrMsg, db, "%s constraint failed", u.ab.zType);
67443     }
67444     sqlite3_log(pOp->p1, u.ab.zLogFmt, pc, p->zSql, p->zErrMsg);
67445   }
67446   rc = sqlite3VdbeHalt(p);
67447   assert( rc==SQLITE_BUSY || rc==SQLITE_OK || rc==SQLITE_ERROR );
67448   if( rc==SQLITE_BUSY ){
67449     p->rc = rc = SQLITE_BUSY;
67450   }else{
67451     assert( rc==SQLITE_OK || (p->rc&0xff)==SQLITE_CONSTRAINT );
67452     assert( rc==SQLITE_OK || db->nDeferredCons>0 || db->nDeferredImmCons>0 );
67453     rc = p->rc ? SQLITE_ERROR : SQLITE_DONE;
67454   }
67455   goto vdbe_return;
67456 }
67457 
67458 /* Opcode: Integer P1 P2 * * *
67459 ** Synopsis: r[P2]=P1
67460 **
67461 ** The 32-bit integer value P1 is written into register P2.
67462 */
67463 case OP_Integer: {         /* out2-prerelease */
67464   pOut->u.i = pOp->p1;
67465   break;
67466 }
67467 
67468 /* Opcode: Int64 * P2 * P4 *
67469 ** Synopsis: r[P2]=P4
67470 **
67471 ** P4 is a pointer to a 64-bit integer value.
67472 ** Write that value into register P2.
67473 */
67474 case OP_Int64: {           /* out2-prerelease */
67475   assert( pOp->p4.pI64!=0 );
67476   pOut->u.i = *pOp->p4.pI64;
67477   break;
67478 }
67479 
67480 #ifndef SQLITE_OMIT_FLOATING_POINT
67481 /* Opcode: Real * P2 * P4 *
67482 ** Synopsis: r[P2]=P4
67483 **
67484 ** P4 is a pointer to a 64-bit floating point value.
67485 ** Write that value into register P2.
67486 */
67487 case OP_Real: {            /* same as TK_FLOAT, out2-prerelease */
67488   pOut->flags = MEM_Real;
67489   assert( !sqlite3IsNaN(*pOp->p4.pReal) );
67490   pOut->r = *pOp->p4.pReal;
67491   break;
67492 }
67493 #endif
67494 
67495 /* Opcode: String8 * P2 * P4 *
67496 ** Synopsis: r[P2]='P4'
67497 **
67498 ** P4 points to a nul terminated UTF-8 string. This opcode is transformed 
67499 ** into an OP_String before it is executed for the first time.
67500 */
67501 case OP_String8: {         /* same as TK_STRING, out2-prerelease */
67502   assert( pOp->p4.z!=0 );
67503   pOp->opcode = OP_String;
67504   pOp->p1 = sqlite3Strlen30(pOp->p4.z);
67505 
67506 #ifndef SQLITE_OMIT_UTF16
67507   if( encoding!=SQLITE_UTF8 ){
67508     rc = sqlite3VdbeMemSetStr(pOut, pOp->p4.z, -1, SQLITE_UTF8, SQLITE_STATIC);
67509     if( rc==SQLITE_TOOBIG ) goto too_big;
67510     if( SQLITE_OK!=sqlite3VdbeChangeEncoding(pOut, encoding) ) goto no_mem;
67511     assert( pOut->zMalloc==pOut->z );
67512     assert( pOut->flags & MEM_Dyn );
67513     pOut->zMalloc = 0;
67514     pOut->flags |= MEM_Static;
67515     pOut->flags &= ~MEM_Dyn;
67516     if( pOp->p4type==P4_DYNAMIC ){
67517       sqlite3DbFree(db, pOp->p4.z);
67518     }
67519     pOp->p4type = P4_DYNAMIC;
67520     pOp->p4.z = pOut->z;
67521     pOp->p1 = pOut->n;
67522   }
67523 #endif
67524   if( pOp->p1>db->aLimit[SQLITE_LIMIT_LENGTH] ){
67525     goto too_big;
67526   }
67527   /* Fall through to the next case, OP_String */
67528 }
67529   
67530 /* Opcode: String P1 P2 * P4 *
67531 ** Synopsis: r[P2]='P4' (len=P1)
67532 **
67533 ** The string value P4 of length P1 (bytes) is stored in register P2.
67534 */
67535 case OP_String: {          /* out2-prerelease */
67536   assert( pOp->p4.z!=0 );
67537   pOut->flags = MEM_Str|MEM_Static|MEM_Term;
67538   pOut->z = pOp->p4.z;
67539   pOut->n = pOp->p1;
67540   pOut->enc = encoding;
67541   UPDATE_MAX_BLOBSIZE(pOut);
67542   break;
67543 }
67544 
67545 /* Opcode: Null P1 P2 P3 * *
67546 ** Synopsis:  r[P2..P3]=NULL
67547 **
67548 ** Write a NULL into registers P2.  If P3 greater than P2, then also write
67549 ** NULL into register P3 and every register in between P2 and P3.  If P3
67550 ** is less than P2 (typically P3 is zero) then only register P2 is
67551 ** set to NULL.
67552 **
67553 ** If the P1 value is non-zero, then also set the MEM_Cleared flag so that
67554 ** NULL values will not compare equal even if SQLITE_NULLEQ is set on
67555 ** OP_Ne or OP_Eq.
67556 */
67557 case OP_Null: {           /* out2-prerelease */
67558 #if 0  /* local variables moved into u.ac */
67559   int cnt;
67560   u16 nullFlag;
67561 #endif /* local variables moved into u.ac */
67562   u.ac.cnt = pOp->p3-pOp->p2;
67563   assert( pOp->p3<=(p->nMem-p->nCursor) );
67564   pOut->flags = u.ac.nullFlag = pOp->p1 ? (MEM_Null|MEM_Cleared) : MEM_Null;
67565   while( u.ac.cnt>0 ){
67566     pOut++;
67567     memAboutToChange(p, pOut);
67568     VdbeMemRelease(pOut);
67569     pOut->flags = u.ac.nullFlag;
67570     u.ac.cnt--;
67571   }
67572   break;
67573 }
67574 
67575 
67576 /* Opcode: Blob P1 P2 * P4
67577 ** Synopsis: r[P2]=P4 (len=P1)
67578 **
67579 ** P4 points to a blob of data P1 bytes long.  Store this
67580 ** blob in register P2.
67581 */
67582 case OP_Blob: {                /* out2-prerelease */
67583   assert( pOp->p1 <= SQLITE_MAX_LENGTH );
67584   sqlite3VdbeMemSetStr(pOut, pOp->p4.z, pOp->p1, 0, 0);
67585   pOut->enc = encoding;
67586   UPDATE_MAX_BLOBSIZE(pOut);
67587   break;
67588 }
67589 
67590 /* Opcode: Variable P1 P2 * P4 *
67591 ** Synopsis: r[P2]=parameter(P1,P4)
67592 **
67593 ** Transfer the values of bound parameter P1 into register P2
67594 **
67595 ** If the parameter is named, then its name appears in P4 and P3==1.
67596 ** The P4 value is used by sqlite3_bind_parameter_name().
67597 */
67598 case OP_Variable: {            /* out2-prerelease */
67599 #if 0  /* local variables moved into u.ad */
67600   Mem *pVar;       /* Value being transferred */
67601 #endif /* local variables moved into u.ad */
67602 
67603   assert( pOp->p1>0 && pOp->p1<=p->nVar );
67604   assert( pOp->p4.z==0 || pOp->p4.z==p->azVar[pOp->p1-1] );
67605   u.ad.pVar = &p->aVar[pOp->p1 - 1];
67606   if( sqlite3VdbeMemTooBig(u.ad.pVar) ){
67607     goto too_big;
67608   }
67609   sqlite3VdbeMemShallowCopy(pOut, u.ad.pVar, MEM_Static);
67610   UPDATE_MAX_BLOBSIZE(pOut);
67611   break;
67612 }
67613 
67614 /* Opcode: Move P1 P2 P3 * *
67615 ** Synopsis:  r[P2@P3]=r[P1@P3]
67616 **
67617 ** Move the values in register P1..P1+P3 over into
67618 ** registers P2..P2+P3.  Registers P1..P1+P3 are
67619 ** left holding a NULL.  It is an error for register ranges
67620 ** P1..P1+P3 and P2..P2+P3 to overlap.
67621 */
67622 case OP_Move: {
67623 #if 0  /* local variables moved into u.ae */
67624   char *zMalloc;   /* Holding variable for allocated memory */
67625   int n;           /* Number of registers left to copy */
67626   int p1;          /* Register to copy from */
67627   int p2;          /* Register to copy to */
67628 #endif /* local variables moved into u.ae */
67629 
67630   u.ae.n = pOp->p3;
67631   u.ae.p1 = pOp->p1;
67632   u.ae.p2 = pOp->p2;
67633   assert( u.ae.n>=0 && u.ae.p1>0 && u.ae.p2>0 );
67634   assert( u.ae.p1+u.ae.n<=u.ae.p2 || u.ae.p2+u.ae.n<=u.ae.p1 );
67635 
67636   pIn1 = &aMem[u.ae.p1];
67637   pOut = &aMem[u.ae.p2];
67638   do{
67639     assert( pOut<=&aMem[(p->nMem-p->nCursor)] );
67640     assert( pIn1<=&aMem[(p->nMem-p->nCursor)] );
67641     assert( memIsValid(pIn1) );
67642     memAboutToChange(p, pOut);
67643     u.ae.zMalloc = pOut->zMalloc;
67644     pOut->zMalloc = 0;
67645     sqlite3VdbeMemMove(pOut, pIn1);
67646 #ifdef SQLITE_DEBUG
67647     if( pOut->pScopyFrom>=&aMem[u.ae.p1] && pOut->pScopyFrom<&aMem[u.ae.p1+pOp->p3] ){
67648       pOut->pScopyFrom += u.ae.p1 - pOp->p2;
67649     }
67650 #endif
67651     pIn1->zMalloc = u.ae.zMalloc;
67652     REGISTER_TRACE(u.ae.p2++, pOut);
67653     pIn1++;
67654     pOut++;
67655   }while( u.ae.n-- );
67656   break;
67657 }
67658 
67659 /* Opcode: Copy P1 P2 P3 * *
67660 ** Synopsis: r[P2@P3]=r[P1@P3]
67661 **
67662 ** Make a copy of registers P1..P1+P3 into registers P2..P2+P3.
67663 **
67664 ** This instruction makes a deep copy of the value.  A duplicate
67665 ** is made of any string or blob constant.  See also OP_SCopy.
67666 */
67667 case OP_Copy: {
67668 #if 0  /* local variables moved into u.af */
67669   int n;
67670 #endif /* local variables moved into u.af */
67671 
67672   u.af.n = pOp->p3;
67673   pIn1 = &aMem[pOp->p1];
67674   pOut = &aMem[pOp->p2];
67675   assert( pOut!=pIn1 );
67676   while( 1 ){
67677     sqlite3VdbeMemShallowCopy(pOut, pIn1, MEM_Ephem);
67678     Deephemeralize(pOut);
67679 #ifdef SQLITE_DEBUG
67680     pOut->pScopyFrom = 0;
67681 #endif
67682     REGISTER_TRACE(pOp->p2+pOp->p3-u.af.n, pOut);
67683     if( (u.af.n--)==0 ) break;
67684     pOut++;
67685     pIn1++;
67686   }
67687   break;
67688 }
67689 
67690 /* Opcode: SCopy P1 P2 * * *
67691 ** Synopsis: r[P2]=r[P1]
67692 **
67693 ** Make a shallow copy of register P1 into register P2.
67694 **
67695 ** This instruction makes a shallow copy of the value.  If the value
67696 ** is a string or blob, then the copy is only a pointer to the
67697 ** original and hence if the original changes so will the copy.
67698 ** Worse, if the original is deallocated, the copy becomes invalid.
67699 ** Thus the program must guarantee that the original will not change
67700 ** during the lifetime of the copy.  Use OP_Copy to make a complete
67701 ** copy.
67702 */
67703 case OP_SCopy: {            /* out2 */
67704   pIn1 = &aMem[pOp->p1];
67705   pOut = &aMem[pOp->p2];
67706   assert( pOut!=pIn1 );
67707   sqlite3VdbeMemShallowCopy(pOut, pIn1, MEM_Ephem);
67708 #ifdef SQLITE_DEBUG
67709   if( pOut->pScopyFrom==0 ) pOut->pScopyFrom = pIn1;
67710 #endif
67711   break;
67712 }
67713 
67714 /* Opcode: ResultRow P1 P2 * * *
67715 ** Synopsis:  output=r[P1@P2]
67716 **
67717 ** The registers P1 through P1+P2-1 contain a single row of
67718 ** results. This opcode causes the sqlite3_step() call to terminate
67719 ** with an SQLITE_ROW return code and it sets up the sqlite3_stmt
67720 ** structure to provide access to the top P1 values as the result
67721 ** row.
67722 */
67723 case OP_ResultRow: {
67724 #if 0  /* local variables moved into u.ag */
67725   Mem *pMem;
67726   int i;
67727 #endif /* local variables moved into u.ag */
67728   assert( p->nResColumn==pOp->p2 );
67729   assert( pOp->p1>0 );
67730   assert( pOp->p1+pOp->p2<=(p->nMem-p->nCursor)+1 );
67731 
67732 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
67733   /* Run the progress counter just before returning.
67734   */
67735   if( db->xProgress!=0
67736    && nVmStep>=nProgressLimit
67737    && db->xProgress(db->pProgressArg)!=0
67738   ){
67739     rc = SQLITE_INTERRUPT;
67740     goto vdbe_error_halt;
67741   }
67742 #endif
67743 
67744   /* If this statement has violated immediate foreign key constraints, do
67745   ** not return the number of rows modified. And do not RELEASE the statement
67746   ** transaction. It needs to be rolled back.  */
67747   if( SQLITE_OK!=(rc = sqlite3VdbeCheckFk(p, 0)) ){
67748     assert( db->flags&SQLITE_CountRows );
67749     assert( p->usesStmtJournal );
67750     break;
67751   }
67752 
67753   /* If the SQLITE_CountRows flag is set in sqlite3.flags mask, then
67754   ** DML statements invoke this opcode to return the number of rows
67755   ** modified to the user. This is the only way that a VM that
67756   ** opens a statement transaction may invoke this opcode.
67757   **
67758   ** In case this is such a statement, close any statement transaction
67759   ** opened by this VM before returning control to the user. This is to
67760   ** ensure that statement-transactions are always nested, not overlapping.
67761   ** If the open statement-transaction is not closed here, then the user
67762   ** may step another VM that opens its own statement transaction. This
67763   ** may lead to overlapping statement transactions.
67764   **
67765   ** The statement transaction is never a top-level transaction.  Hence
67766   ** the RELEASE call below can never fail.
67767   */
67768   assert( p->iStatement==0 || db->flags&SQLITE_CountRows );
67769   rc = sqlite3VdbeCloseStatement(p, SAVEPOINT_RELEASE);
67770   if( NEVER(rc!=SQLITE_OK) ){
67771     break;
67772   }
67773 
67774   /* Invalidate all ephemeral cursor row caches */
67775   p->cacheCtr = (p->cacheCtr + 2)|1;
67776 
67777   /* Make sure the results of the current row are \000 terminated
67778   ** and have an assigned type.  The results are de-ephemeralized as
67779   ** a side effect.
67780   */
67781   u.ag.pMem = p->pResultSet = &aMem[pOp->p1];
67782   for(u.ag.i=0; u.ag.i<pOp->p2; u.ag.i++){
67783     assert( memIsValid(&u.ag.pMem[u.ag.i]) );
67784     Deephemeralize(&u.ag.pMem[u.ag.i]);
67785     assert( (u.ag.pMem[u.ag.i].flags & MEM_Ephem)==0
67786             || (u.ag.pMem[u.ag.i].flags & (MEM_Str|MEM_Blob))==0 );
67787     sqlite3VdbeMemNulTerminate(&u.ag.pMem[u.ag.i]);
67788     sqlite3VdbeMemStoreType(&u.ag.pMem[u.ag.i]);
67789     REGISTER_TRACE(pOp->p1+u.ag.i, &u.ag.pMem[u.ag.i]);
67790   }
67791   if( db->mallocFailed ) goto no_mem;
67792 
67793   /* Return SQLITE_ROW
67794   */
67795   p->pc = pc + 1;
67796   rc = SQLITE_ROW;
67797   goto vdbe_return;
67798 }
67799 
67800 /* Opcode: Concat P1 P2 P3 * *
67801 ** Synopsis: r[P3]=r[P2]+r[P1]
67802 **
67803 ** Add the text in register P1 onto the end of the text in
67804 ** register P2 and store the result in register P3.
67805 ** If either the P1 or P2 text are NULL then store NULL in P3.
67806 **
67807 **   P3 = P2 || P1
67808 **
67809 ** It is illegal for P1 and P3 to be the same register. Sometimes,
67810 ** if P3 is the same register as P2, the implementation is able
67811 ** to avoid a memcpy().
67812 */
67813 case OP_Concat: {           /* same as TK_CONCAT, in1, in2, out3 */
67814 #if 0  /* local variables moved into u.ah */
67815   i64 nByte;
67816 #endif /* local variables moved into u.ah */
67817 
67818   pIn1 = &aMem[pOp->p1];
67819   pIn2 = &aMem[pOp->p2];
67820   pOut = &aMem[pOp->p3];
67821   assert( pIn1!=pOut );
67822   if( (pIn1->flags | pIn2->flags) & MEM_Null ){
67823     sqlite3VdbeMemSetNull(pOut);
67824     break;
67825   }
67826   if( ExpandBlob(pIn1) || ExpandBlob(pIn2) ) goto no_mem;
67827   Stringify(pIn1, encoding);
67828   Stringify(pIn2, encoding);
67829   u.ah.nByte = pIn1->n + pIn2->n;
67830   if( u.ah.nByte>db->aLimit[SQLITE_LIMIT_LENGTH] ){
67831     goto too_big;
67832   }
67833   MemSetTypeFlag(pOut, MEM_Str);
67834   if( sqlite3VdbeMemGrow(pOut, (int)u.ah.nByte+2, pOut==pIn2) ){
67835     goto no_mem;
67836   }
67837   if( pOut!=pIn2 ){
67838     memcpy(pOut->z, pIn2->z, pIn2->n);
67839   }
67840   memcpy(&pOut->z[pIn2->n], pIn1->z, pIn1->n);
67841   pOut->z[u.ah.nByte]=0;
67842   pOut->z[u.ah.nByte+1] = 0;
67843   pOut->flags |= MEM_Term;
67844   pOut->n = (int)u.ah.nByte;
67845   pOut->enc = encoding;
67846   UPDATE_MAX_BLOBSIZE(pOut);
67847   break;
67848 }
67849 
67850 /* Opcode: Add P1 P2 P3 * *
67851 ** Synopsis:  r[P3]=r[P1]+r[P2]
67852 **
67853 ** Add the value in register P1 to the value in register P2
67854 ** and store the result in register P3.
67855 ** If either input is NULL, the result is NULL.
67856 */
67857 /* Opcode: Multiply P1 P2 P3 * *
67858 ** Synopsis:  r[P3]=r[P1]*r[P2]
67859 **
67860 **
67861 ** Multiply the value in register P1 by the value in register P2
67862 ** and store the result in register P3.
67863 ** If either input is NULL, the result is NULL.
67864 */
67865 /* Opcode: Subtract P1 P2 P3 * *
67866 ** Synopsis:  r[P3]=r[P2]-r[P1]
67867 **
67868 ** Subtract the value in register P1 from the value in register P2
67869 ** and store the result in register P3.
67870 ** If either input is NULL, the result is NULL.
67871 */
67872 /* Opcode: Divide P1 P2 P3 * *
67873 ** Synopsis:  r[P3]=r[P2]/r[P1]
67874 **
67875 ** Divide the value in register P1 by the value in register P2
67876 ** and store the result in register P3 (P3=P2/P1). If the value in 
67877 ** register P1 is zero, then the result is NULL. If either input is 
67878 ** NULL, the result is NULL.
67879 */
67880 /* Opcode: Remainder P1 P2 P3 * *
67881 ** Synopsis:  r[P3]=r[P2]%r[P1]
67882 **
67883 ** Compute the remainder after integer register P2 is divided by 
67884 ** register P1 and store the result in register P3. 
67885 ** If the value in register P1 is zero the result is NULL.
67886 ** If either operand is NULL, the result is NULL.
67887 */
67888 case OP_Add:                   /* same as TK_PLUS, in1, in2, out3 */
67889 case OP_Subtract:              /* same as TK_MINUS, in1, in2, out3 */
67890 case OP_Multiply:              /* same as TK_STAR, in1, in2, out3 */
67891 case OP_Divide:                /* same as TK_SLASH, in1, in2, out3 */
67892 case OP_Remainder: {           /* same as TK_REM, in1, in2, out3 */
67893 #if 0  /* local variables moved into u.ai */
67894   char bIntint;   /* Started out as two integer operands */
67895   int flags;      /* Combined MEM_* flags from both inputs */
67896   i64 iA;         /* Integer value of left operand */
67897   i64 iB;         /* Integer value of right operand */
67898   double rA;      /* Real value of left operand */
67899   double rB;      /* Real value of right operand */
67900 #endif /* local variables moved into u.ai */
67901 
67902   pIn1 = &aMem[pOp->p1];
67903   applyNumericAffinity(pIn1);
67904   pIn2 = &aMem[pOp->p2];
67905   applyNumericAffinity(pIn2);
67906   pOut = &aMem[pOp->p3];
67907   u.ai.flags = pIn1->flags | pIn2->flags;
67908   if( (u.ai.flags & MEM_Null)!=0 ) goto arithmetic_result_is_null;
67909   if( (pIn1->flags & pIn2->flags & MEM_Int)==MEM_Int ){
67910     u.ai.iA = pIn1->u.i;
67911     u.ai.iB = pIn2->u.i;
67912     u.ai.bIntint = 1;
67913     switch( pOp->opcode ){
67914       case OP_Add:       if( sqlite3AddInt64(&u.ai.iB,u.ai.iA) ) goto fp_math;  break;
67915       case OP_Subtract:  if( sqlite3SubInt64(&u.ai.iB,u.ai.iA) ) goto fp_math;  break;
67916       case OP_Multiply:  if( sqlite3MulInt64(&u.ai.iB,u.ai.iA) ) goto fp_math;  break;
67917       case OP_Divide: {
67918         if( u.ai.iA==0 ) goto arithmetic_result_is_null;
67919         if( u.ai.iA==-1 && u.ai.iB==SMALLEST_INT64 ) goto fp_math;
67920         u.ai.iB /= u.ai.iA;
67921         break;
67922       }
67923       default: {
67924         if( u.ai.iA==0 ) goto arithmetic_result_is_null;
67925         if( u.ai.iA==-1 ) u.ai.iA = 1;
67926         u.ai.iB %= u.ai.iA;
67927         break;
67928       }
67929     }
67930     pOut->u.i = u.ai.iB;
67931     MemSetTypeFlag(pOut, MEM_Int);
67932   }else{
67933     u.ai.bIntint = 0;
67934 fp_math:
67935     u.ai.rA = sqlite3VdbeRealValue(pIn1);
67936     u.ai.rB = sqlite3VdbeRealValue(pIn2);
67937     switch( pOp->opcode ){
67938       case OP_Add:         u.ai.rB += u.ai.rA;       break;
67939       case OP_Subtract:    u.ai.rB -= u.ai.rA;       break;
67940       case OP_Multiply:    u.ai.rB *= u.ai.rA;       break;
67941       case OP_Divide: {
67942         /* (double)0 In case of SQLITE_OMIT_FLOATING_POINT... */
67943         if( u.ai.rA==(double)0 ) goto arithmetic_result_is_null;
67944         u.ai.rB /= u.ai.rA;
67945         break;
67946       }
67947       default: {
67948         u.ai.iA = (i64)u.ai.rA;
67949         u.ai.iB = (i64)u.ai.rB;
67950         if( u.ai.iA==0 ) goto arithmetic_result_is_null;
67951         if( u.ai.iA==-1 ) u.ai.iA = 1;
67952         u.ai.rB = (double)(u.ai.iB % u.ai.iA);
67953         break;
67954       }
67955     }
67956 #ifdef SQLITE_OMIT_FLOATING_POINT
67957     pOut->u.i = u.ai.rB;
67958     MemSetTypeFlag(pOut, MEM_Int);
67959 #else
67960     if( sqlite3IsNaN(u.ai.rB) ){
67961       goto arithmetic_result_is_null;
67962     }
67963     pOut->r = u.ai.rB;
67964     MemSetTypeFlag(pOut, MEM_Real);
67965     if( (u.ai.flags & MEM_Real)==0 && !u.ai.bIntint ){
67966       sqlite3VdbeIntegerAffinity(pOut);
67967     }
67968 #endif
67969   }
67970   break;
67971 
67972 arithmetic_result_is_null:
67973   sqlite3VdbeMemSetNull(pOut);
67974   break;
67975 }
67976 
67977 /* Opcode: CollSeq P1 * * P4
67978 **
67979 ** P4 is a pointer to a CollSeq struct. If the next call to a user function
67980 ** or aggregate calls sqlite3GetFuncCollSeq(), this collation sequence will
67981 ** be returned. This is used by the built-in min(), max() and nullif()
67982 ** functions.
67983 **
67984 ** If P1 is not zero, then it is a register that a subsequent min() or
67985 ** max() aggregate will set to 1 if the current row is not the minimum or
67986 ** maximum.  The P1 register is initialized to 0 by this instruction.
67987 **
67988 ** The interface used by the implementation of the aforementioned functions
67989 ** to retrieve the collation sequence set by this opcode is not available
67990 ** publicly, only to user functions defined in func.c.
67991 */
67992 case OP_CollSeq: {
67993   assert( pOp->p4type==P4_COLLSEQ );
67994   if( pOp->p1 ){
67995     sqlite3VdbeMemSetInt64(&aMem[pOp->p1], 0);
67996   }
67997   break;
67998 }
67999 
68000 /* Opcode: Function P1 P2 P3 P4 P5
68001 ** Synopsis: r[P3]=func(r[P2@P5])
68002 **
68003 ** Invoke a user function (P4 is a pointer to a Function structure that
68004 ** defines the function) with P5 arguments taken from register P2 and
68005 ** successors.  The result of the function is stored in register P3.
68006 ** Register P3 must not be one of the function inputs.
68007 **
68008 ** P1 is a 32-bit bitmask indicating whether or not each argument to the 
68009 ** function was determined to be constant at compile time. If the first
68010 ** argument was constant then bit 0 of P1 is set. This is used to determine
68011 ** whether meta data associated with a user function argument using the
68012 ** sqlite3_set_auxdata() API may be safely retained until the next
68013 ** invocation of this opcode.
68014 **
68015 ** See also: AggStep and AggFinal
68016 */
68017 case OP_Function: {
68018 #if 0  /* local variables moved into u.aj */
68019   int i;
68020   Mem *pArg;
68021   sqlite3_context ctx;
68022   sqlite3_value **apVal;
68023   int n;
68024 #endif /* local variables moved into u.aj */
68025 
68026   u.aj.n = pOp->p5;
68027   u.aj.apVal = p->apArg;
68028   assert( u.aj.apVal || u.aj.n==0 );
68029   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
68030   pOut = &aMem[pOp->p3];
68031   memAboutToChange(p, pOut);
68032 
68033   assert( u.aj.n==0 || (pOp->p2>0 && pOp->p2+u.aj.n<=(p->nMem-p->nCursor)+1) );
68034   assert( pOp->p3<pOp->p2 || pOp->p3>=pOp->p2+u.aj.n );
68035   u.aj.pArg = &aMem[pOp->p2];
68036   for(u.aj.i=0; u.aj.i<u.aj.n; u.aj.i++, u.aj.pArg++){
68037     assert( memIsValid(u.aj.pArg) );
68038     u.aj.apVal[u.aj.i] = u.aj.pArg;
68039     Deephemeralize(u.aj.pArg);
68040     sqlite3VdbeMemStoreType(u.aj.pArg);
68041     REGISTER_TRACE(pOp->p2+u.aj.i, u.aj.pArg);
68042   }
68043 
68044   assert( pOp->p4type==P4_FUNCDEF );
68045   u.aj.ctx.pFunc = pOp->p4.pFunc;
68046   u.aj.ctx.iOp = pc;
68047   u.aj.ctx.pVdbe = p;
68048 
68049   /* The output cell may already have a buffer allocated. Move
68050   ** the pointer to u.aj.ctx.s so in case the user-function can use
68051   ** the already allocated buffer instead of allocating a new one.
68052   */
68053   memcpy(&u.aj.ctx.s, pOut, sizeof(Mem));
68054   pOut->flags = MEM_Null;
68055   pOut->xDel = 0;
68056   pOut->zMalloc = 0;
68057   MemSetTypeFlag(&u.aj.ctx.s, MEM_Null);
68058 
68059   u.aj.ctx.fErrorOrAux = 0;
68060   if( u.aj.ctx.pFunc->funcFlags & SQLITE_FUNC_NEEDCOLL ){
68061     assert( pOp>aOp );
68062     assert( pOp[-1].p4type==P4_COLLSEQ );
68063     assert( pOp[-1].opcode==OP_CollSeq );
68064     u.aj.ctx.pColl = pOp[-1].p4.pColl;
68065   }
68066   db->lastRowid = lastRowid;
68067   (*u.aj.ctx.pFunc->xFunc)(&u.aj.ctx, u.aj.n, u.aj.apVal); /* IMP: R-24505-23230 */
68068   lastRowid = db->lastRowid;
68069 
68070   if( db->mallocFailed ){
68071     /* Even though a malloc() has failed, the implementation of the
68072     ** user function may have called an sqlite3_result_XXX() function
68073     ** to return a value. The following call releases any resources
68074     ** associated with such a value.
68075     */
68076     sqlite3VdbeMemRelease(&u.aj.ctx.s);
68077     goto no_mem;
68078   }
68079 
68080   /* If the function returned an error, throw an exception */
68081   if( u.aj.ctx.fErrorOrAux ){
68082     if( u.aj.ctx.isError ){
68083       sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3_value_text(&u.aj.ctx.s));
68084       rc = u.aj.ctx.isError;
68085     }
68086     sqlite3VdbeDeleteAuxData(p, pc, pOp->p1);
68087   }
68088 
68089   /* Copy the result of the function into register P3 */
68090   sqlite3VdbeChangeEncoding(&u.aj.ctx.s, encoding);
68091   assert( pOut->flags==MEM_Null );
68092   memcpy(pOut, &u.aj.ctx.s, sizeof(Mem));
68093   if( sqlite3VdbeMemTooBig(pOut) ){
68094     goto too_big;
68095   }
68096 
68097 #if 0
68098   /* The app-defined function has done something that as caused this
68099   ** statement to expire.  (Perhaps the function called sqlite3_exec()
68100   ** with a CREATE TABLE statement.)
68101   */
68102   if( p->expired ) rc = SQLITE_ABORT;
68103 #endif
68104 
68105   REGISTER_TRACE(pOp->p3, pOut);
68106   UPDATE_MAX_BLOBSIZE(pOut);
68107   break;
68108 }
68109 
68110 /* Opcode: BitAnd P1 P2 P3 * *
68111 ** Synopsis:  r[P3]=r[P1]&r[P2]
68112 **
68113 ** Take the bit-wise AND of the values in register P1 and P2 and
68114 ** store the result in register P3.
68115 ** If either input is NULL, the result is NULL.
68116 */
68117 /* Opcode: BitOr P1 P2 P3 * *
68118 ** Synopsis:  r[P3]=r[P1]|r[P2]
68119 **
68120 ** Take the bit-wise OR of the values in register P1 and P2 and
68121 ** store the result in register P3.
68122 ** If either input is NULL, the result is NULL.
68123 */
68124 /* Opcode: ShiftLeft P1 P2 P3 * *
68125 ** Synopsis:  r[P3]=r[P2]<<r[P1]
68126 **
68127 ** Shift the integer value in register P2 to the left by the
68128 ** number of bits specified by the integer in register P1.
68129 ** Store the result in register P3.
68130 ** If either input is NULL, the result is NULL.
68131 */
68132 /* Opcode: ShiftRight P1 P2 P3 * *
68133 ** Synopsis:  r[P3]=r[P2]>>r[P1]
68134 **
68135 ** Shift the integer value in register P2 to the right by the
68136 ** number of bits specified by the integer in register P1.
68137 ** Store the result in register P3.
68138 ** If either input is NULL, the result is NULL.
68139 */
68140 case OP_BitAnd:                 /* same as TK_BITAND, in1, in2, out3 */
68141 case OP_BitOr:                  /* same as TK_BITOR, in1, in2, out3 */
68142 case OP_ShiftLeft:              /* same as TK_LSHIFT, in1, in2, out3 */
68143 case OP_ShiftRight: {           /* same as TK_RSHIFT, in1, in2, out3 */
68144 #if 0  /* local variables moved into u.ak */
68145   i64 iA;
68146   u64 uA;
68147   i64 iB;
68148   u8 op;
68149 #endif /* local variables moved into u.ak */
68150 
68151   pIn1 = &aMem[pOp->p1];
68152   pIn2 = &aMem[pOp->p2];
68153   pOut = &aMem[pOp->p3];
68154   if( (pIn1->flags | pIn2->flags) & MEM_Null ){
68155     sqlite3VdbeMemSetNull(pOut);
68156     break;
68157   }
68158   u.ak.iA = sqlite3VdbeIntValue(pIn2);
68159   u.ak.iB = sqlite3VdbeIntValue(pIn1);
68160   u.ak.op = pOp->opcode;
68161   if( u.ak.op==OP_BitAnd ){
68162     u.ak.iA &= u.ak.iB;
68163   }else if( u.ak.op==OP_BitOr ){
68164     u.ak.iA |= u.ak.iB;
68165   }else if( u.ak.iB!=0 ){
68166     assert( u.ak.op==OP_ShiftRight || u.ak.op==OP_ShiftLeft );
68167 
68168     /* If shifting by a negative amount, shift in the other direction */
68169     if( u.ak.iB<0 ){
68170       assert( OP_ShiftRight==OP_ShiftLeft+1 );
68171       u.ak.op = 2*OP_ShiftLeft + 1 - u.ak.op;
68172       u.ak.iB = u.ak.iB>(-64) ? -u.ak.iB : 64;
68173     }
68174 
68175     if( u.ak.iB>=64 ){
68176       u.ak.iA = (u.ak.iA>=0 || u.ak.op==OP_ShiftLeft) ? 0 : -1;
68177     }else{
68178       memcpy(&u.ak.uA, &u.ak.iA, sizeof(u.ak.uA));
68179       if( u.ak.op==OP_ShiftLeft ){
68180         u.ak.uA <<= u.ak.iB;
68181       }else{
68182         u.ak.uA >>= u.ak.iB;
68183         /* Sign-extend on a right shift of a negative number */
68184         if( u.ak.iA<0 ) u.ak.uA |= ((((u64)0xffffffff)<<32)|0xffffffff) << (64-u.ak.iB);
68185       }
68186       memcpy(&u.ak.iA, &u.ak.uA, sizeof(u.ak.iA));
68187     }
68188   }
68189   pOut->u.i = u.ak.iA;
68190   MemSetTypeFlag(pOut, MEM_Int);
68191   break;
68192 }
68193 
68194 /* Opcode: AddImm  P1 P2 * * *
68195 ** Synopsis:  r[P1]=r[P1]+P2
68196 ** 
68197 ** Add the constant P2 to the value in register P1.
68198 ** The result is always an integer.
68199 **
68200 ** To force any register to be an integer, just add 0.
68201 */
68202 case OP_AddImm: {            /* in1 */
68203   pIn1 = &aMem[pOp->p1];
68204   memAboutToChange(p, pIn1);
68205   sqlite3VdbeMemIntegerify(pIn1);
68206   pIn1->u.i += pOp->p2;
68207   break;
68208 }
68209 
68210 /* Opcode: MustBeInt P1 P2 * * *
68211 ** 
68212 ** Force the value in register P1 to be an integer.  If the value
68213 ** in P1 is not an integer and cannot be converted into an integer
68214 ** without data loss, then jump immediately to P2, or if P2==0
68215 ** raise an SQLITE_MISMATCH exception.
68216 */
68217 case OP_MustBeInt: {            /* jump, in1 */
68218   pIn1 = &aMem[pOp->p1];
68219   if( (pIn1->flags & MEM_Int)==0 ){
68220     applyAffinity(pIn1, SQLITE_AFF_NUMERIC, encoding);
68221     if( (pIn1->flags & MEM_Int)==0 ){
68222       if( pOp->p2==0 ){
68223         rc = SQLITE_MISMATCH;
68224         goto abort_due_to_error;
68225       }else{
68226         pc = pOp->p2 - 1;
68227         break;
68228       }
68229     }
68230   }
68231   MemSetTypeFlag(pIn1, MEM_Int);
68232   break;
68233 }
68234 
68235 #ifndef SQLITE_OMIT_FLOATING_POINT
68236 /* Opcode: RealAffinity P1 * * * *
68237 **
68238 ** If register P1 holds an integer convert it to a real value.
68239 **
68240 ** This opcode is used when extracting information from a column that
68241 ** has REAL affinity.  Such column values may still be stored as
68242 ** integers, for space efficiency, but after extraction we want them
68243 ** to have only a real value.
68244 */
68245 case OP_RealAffinity: {                  /* in1 */
68246   pIn1 = &aMem[pOp->p1];
68247   if( pIn1->flags & MEM_Int ){
68248     sqlite3VdbeMemRealify(pIn1);
68249   }
68250   break;
68251 }
68252 #endif
68253 
68254 #ifndef SQLITE_OMIT_CAST
68255 /* Opcode: ToText P1 * * * *
68256 **
68257 ** Force the value in register P1 to be text.
68258 ** If the value is numeric, convert it to a string using the
68259 ** equivalent of printf().  Blob values are unchanged and
68260 ** are afterwards simply interpreted as text.
68261 **
68262 ** A NULL value is not changed by this routine.  It remains NULL.
68263 */
68264 case OP_ToText: {                  /* same as TK_TO_TEXT, in1 */
68265   pIn1 = &aMem[pOp->p1];
68266   memAboutToChange(p, pIn1);
68267   if( pIn1->flags & MEM_Null ) break;
68268   assert( MEM_Str==(MEM_Blob>>3) );
68269   pIn1->flags |= (pIn1->flags&MEM_Blob)>>3;
68270   applyAffinity(pIn1, SQLITE_AFF_TEXT, encoding);
68271   rc = ExpandBlob(pIn1);
68272   assert( pIn1->flags & MEM_Str || db->mallocFailed );
68273   pIn1->flags &= ~(MEM_Int|MEM_Real|MEM_Blob|MEM_Zero);
68274   UPDATE_MAX_BLOBSIZE(pIn1);
68275   break;
68276 }
68277 
68278 /* Opcode: ToBlob P1 * * * *
68279 **
68280 ** Force the value in register P1 to be a BLOB.
68281 ** If the value is numeric, convert it to a string first.
68282 ** Strings are simply reinterpreted as blobs with no change
68283 ** to the underlying data.
68284 **
68285 ** A NULL value is not changed by this routine.  It remains NULL.
68286 */
68287 case OP_ToBlob: {                  /* same as TK_TO_BLOB, in1 */
68288   pIn1 = &aMem[pOp->p1];
68289   if( pIn1->flags & MEM_Null ) break;
68290   if( (pIn1->flags & MEM_Blob)==0 ){
68291     applyAffinity(pIn1, SQLITE_AFF_TEXT, encoding);
68292     assert( pIn1->flags & MEM_Str || db->mallocFailed );
68293     MemSetTypeFlag(pIn1, MEM_Blob);
68294   }else{
68295     pIn1->flags &= ~(MEM_TypeMask&~MEM_Blob);
68296   }
68297   UPDATE_MAX_BLOBSIZE(pIn1);
68298   break;
68299 }
68300 
68301 /* Opcode: ToNumeric P1 * * * *
68302 **
68303 ** Force the value in register P1 to be numeric (either an
68304 ** integer or a floating-point number.)
68305 ** If the value is text or blob, try to convert it to an using the
68306 ** equivalent of atoi() or atof() and store 0 if no such conversion 
68307 ** is possible.
68308 **
68309 ** A NULL value is not changed by this routine.  It remains NULL.
68310 */
68311 case OP_ToNumeric: {                  /* same as TK_TO_NUMERIC, in1 */
68312   pIn1 = &aMem[pOp->p1];
68313   sqlite3VdbeMemNumerify(pIn1);
68314   break;
68315 }
68316 #endif /* SQLITE_OMIT_CAST */
68317 
68318 /* Opcode: ToInt P1 * * * *
68319 **
68320 ** Force the value in register P1 to be an integer.  If
68321 ** The value is currently a real number, drop its fractional part.
68322 ** If the value is text or blob, try to convert it to an integer using the
68323 ** equivalent of atoi() and store 0 if no such conversion is possible.
68324 **
68325 ** A NULL value is not changed by this routine.  It remains NULL.
68326 */
68327 case OP_ToInt: {                  /* same as TK_TO_INT, in1 */
68328   pIn1 = &aMem[pOp->p1];
68329   if( (pIn1->flags & MEM_Null)==0 ){
68330     sqlite3VdbeMemIntegerify(pIn1);
68331   }
68332   break;
68333 }
68334 
68335 #if !defined(SQLITE_OMIT_CAST) && !defined(SQLITE_OMIT_FLOATING_POINT)
68336 /* Opcode: ToReal P1 * * * *
68337 **
68338 ** Force the value in register P1 to be a floating point number.
68339 ** If The value is currently an integer, convert it.
68340 ** If the value is text or blob, try to convert it to an integer using the
68341 ** equivalent of atoi() and store 0.0 if no such conversion is possible.
68342 **
68343 ** A NULL value is not changed by this routine.  It remains NULL.
68344 */
68345 case OP_ToReal: {                  /* same as TK_TO_REAL, in1 */
68346   pIn1 = &aMem[pOp->p1];
68347   memAboutToChange(p, pIn1);
68348   if( (pIn1->flags & MEM_Null)==0 ){
68349     sqlite3VdbeMemRealify(pIn1);
68350   }
68351   break;
68352 }
68353 #endif /* !defined(SQLITE_OMIT_CAST) && !defined(SQLITE_OMIT_FLOATING_POINT) */
68354 
68355 /* Opcode: Lt P1 P2 P3 P4 P5
68356 ** Synopsis: if r[P1]<r[P3] goto P2
68357 **
68358 ** Compare the values in register P1 and P3.  If reg(P3)<reg(P1) then
68359 ** jump to address P2.  
68360 **
68361 ** If the SQLITE_JUMPIFNULL bit of P5 is set and either reg(P1) or
68362 ** reg(P3) is NULL then take the jump.  If the SQLITE_JUMPIFNULL 
68363 ** bit is clear then fall through if either operand is NULL.
68364 **
68365 ** The SQLITE_AFF_MASK portion of P5 must be an affinity character -
68366 ** SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made 
68367 ** to coerce both inputs according to this affinity before the
68368 ** comparison is made. If the SQLITE_AFF_MASK is 0x00, then numeric
68369 ** affinity is used. Note that the affinity conversions are stored
68370 ** back into the input registers P1 and P3.  So this opcode can cause
68371 ** persistent changes to registers P1 and P3.
68372 **
68373 ** Once any conversions have taken place, and neither value is NULL, 
68374 ** the values are compared. If both values are blobs then memcmp() is
68375 ** used to determine the results of the comparison.  If both values
68376 ** are text, then the appropriate collating function specified in
68377 ** P4 is  used to do the comparison.  If P4 is not specified then
68378 ** memcmp() is used to compare text string.  If both values are
68379 ** numeric, then a numeric comparison is used. If the two values
68380 ** are of different types, then numbers are considered less than
68381 ** strings and strings are considered less than blobs.
68382 **
68383 ** If the SQLITE_STOREP2 bit of P5 is set, then do not jump.  Instead,
68384 ** store a boolean result (either 0, or 1, or NULL) in register P2.
68385 **
68386 ** If the SQLITE_NULLEQ bit is set in P5, then NULL values are considered
68387 ** equal to one another, provided that they do not have their MEM_Cleared
68388 ** bit set.
68389 */
68390 /* Opcode: Ne P1 P2 P3 P4 P5
68391 ** Synopsis: if r[P1]!=r[P3] goto P2
68392 **
68393 ** This works just like the Lt opcode except that the jump is taken if
68394 ** the operands in registers P1 and P3 are not equal.  See the Lt opcode for
68395 ** additional information.
68396 **
68397 ** If SQLITE_NULLEQ is set in P5 then the result of comparison is always either
68398 ** true or false and is never NULL.  If both operands are NULL then the result
68399 ** of comparison is false.  If either operand is NULL then the result is true.
68400 ** If neither operand is NULL the result is the same as it would be if
68401 ** the SQLITE_NULLEQ flag were omitted from P5.
68402 */
68403 /* Opcode: Eq P1 P2 P3 P4 P5
68404 ** Synopsis: if r[P1]==r[P3] goto P2
68405 **
68406 ** This works just like the Lt opcode except that the jump is taken if
68407 ** the operands in registers P1 and P3 are equal.
68408 ** See the Lt opcode for additional information.
68409 **
68410 ** If SQLITE_NULLEQ is set in P5 then the result of comparison is always either
68411 ** true or false and is never NULL.  If both operands are NULL then the result
68412 ** of comparison is true.  If either operand is NULL then the result is false.
68413 ** If neither operand is NULL the result is the same as it would be if
68414 ** the SQLITE_NULLEQ flag were omitted from P5.
68415 */
68416 /* Opcode: Le P1 P2 P3 P4 P5
68417 ** Synopsis: if r[P1]<=r[P3] goto P2
68418 **
68419 ** This works just like the Lt opcode except that the jump is taken if
68420 ** the content of register P3 is less than or equal to the content of
68421 ** register P1.  See the Lt opcode for additional information.
68422 */
68423 /* Opcode: Gt P1 P2 P3 P4 P5
68424 ** Synopsis: if r[P1]>r[P3] goto P2
68425 **
68426 ** This works just like the Lt opcode except that the jump is taken if
68427 ** the content of register P3 is greater than the content of
68428 ** register P1.  See the Lt opcode for additional information.
68429 */
68430 /* Opcode: Ge P1 P2 P3 P4 P5
68431 ** Synopsis: if r[P1]>=r[P3] goto P2
68432 **
68433 ** This works just like the Lt opcode except that the jump is taken if
68434 ** the content of register P3 is greater than or equal to the content of
68435 ** register P1.  See the Lt opcode for additional information.
68436 */
68437 case OP_Eq:               /* same as TK_EQ, jump, in1, in3 */
68438 case OP_Ne:               /* same as TK_NE, jump, in1, in3 */
68439 case OP_Lt:               /* same as TK_LT, jump, in1, in3 */
68440 case OP_Le:               /* same as TK_LE, jump, in1, in3 */
68441 case OP_Gt:               /* same as TK_GT, jump, in1, in3 */
68442 case OP_Ge: {             /* same as TK_GE, jump, in1, in3 */
68443 #if 0  /* local variables moved into u.al */
68444   int res;            /* Result of the comparison of pIn1 against pIn3 */
68445   char affinity;      /* Affinity to use for comparison */
68446   u16 flags1;         /* Copy of initial value of pIn1->flags */
68447   u16 flags3;         /* Copy of initial value of pIn3->flags */
68448 #endif /* local variables moved into u.al */
68449 
68450   pIn1 = &aMem[pOp->p1];
68451   pIn3 = &aMem[pOp->p3];
68452   u.al.flags1 = pIn1->flags;
68453   u.al.flags3 = pIn3->flags;
68454   if( (u.al.flags1 | u.al.flags3)&MEM_Null ){
68455     /* One or both operands are NULL */
68456     if( pOp->p5 & SQLITE_NULLEQ ){
68457       /* If SQLITE_NULLEQ is set (which will only happen if the operator is
68458       ** OP_Eq or OP_Ne) then take the jump or not depending on whether
68459       ** or not both operands are null.
68460       */
68461       assert( pOp->opcode==OP_Eq || pOp->opcode==OP_Ne );
68462       assert( (u.al.flags1 & MEM_Cleared)==0 );
68463       if( (u.al.flags1&MEM_Null)!=0
68464        && (u.al.flags3&MEM_Null)!=0
68465        && (u.al.flags3&MEM_Cleared)==0
68466       ){
68467         u.al.res = 0;  /* Results are equal */
68468       }else{
68469         u.al.res = 1;  /* Results are not equal */
68470       }
68471     }else{
68472       /* SQLITE_NULLEQ is clear and at least one operand is NULL,
68473       ** then the result is always NULL.
68474       ** The jump is taken if the SQLITE_JUMPIFNULL bit is set.
68475       */
68476       if( pOp->p5 & SQLITE_JUMPIFNULL ){
68477         pc = pOp->p2-1;
68478       }else if( pOp->p5 & SQLITE_STOREP2 ){
68479         pOut = &aMem[pOp->p2];
68480         MemSetTypeFlag(pOut, MEM_Null);
68481         REGISTER_TRACE(pOp->p2, pOut);
68482       }
68483       break;
68484     }
68485   }else{
68486     /* Neither operand is NULL.  Do a comparison. */
68487     u.al.affinity = pOp->p5 & SQLITE_AFF_MASK;
68488     if( u.al.affinity ){
68489       applyAffinity(pIn1, u.al.affinity, encoding);
68490       applyAffinity(pIn3, u.al.affinity, encoding);
68491       if( db->mallocFailed ) goto no_mem;
68492     }
68493 
68494     assert( pOp->p4type==P4_COLLSEQ || pOp->p4.pColl==0 );
68495     ExpandBlob(pIn1);
68496     ExpandBlob(pIn3);
68497     u.al.res = sqlite3MemCompare(pIn3, pIn1, pOp->p4.pColl);
68498   }
68499   switch( pOp->opcode ){
68500     case OP_Eq:    u.al.res = u.al.res==0;     break;
68501     case OP_Ne:    u.al.res = u.al.res!=0;     break;
68502     case OP_Lt:    u.al.res = u.al.res<0;      break;
68503     case OP_Le:    u.al.res = u.al.res<=0;     break;
68504     case OP_Gt:    u.al.res = u.al.res>0;      break;
68505     default:       u.al.res = u.al.res>=0;     break;
68506   }
68507 
68508   if( pOp->p5 & SQLITE_STOREP2 ){
68509     pOut = &aMem[pOp->p2];
68510     memAboutToChange(p, pOut);
68511     MemSetTypeFlag(pOut, MEM_Int);
68512     pOut->u.i = u.al.res;
68513     REGISTER_TRACE(pOp->p2, pOut);
68514   }else if( u.al.res ){
68515     pc = pOp->p2-1;
68516   }
68517 
68518   /* Undo any changes made by applyAffinity() to the input registers. */
68519   pIn1->flags = (pIn1->flags&~MEM_TypeMask) | (u.al.flags1&MEM_TypeMask);
68520   pIn3->flags = (pIn3->flags&~MEM_TypeMask) | (u.al.flags3&MEM_TypeMask);
68521   break;
68522 }
68523 
68524 /* Opcode: Permutation * * * P4 *
68525 **
68526 ** Set the permutation used by the OP_Compare operator to be the array
68527 ** of integers in P4.
68528 **
68529 ** The permutation is only valid until the next OP_Compare that has
68530 ** the OPFLAG_PERMUTE bit set in P5. Typically the OP_Permutation should 
68531 ** occur immediately prior to the OP_Compare.
68532 */
68533 case OP_Permutation: {
68534   assert( pOp->p4type==P4_INTARRAY );
68535   assert( pOp->p4.ai );
68536   aPermute = pOp->p4.ai;
68537   break;
68538 }
68539 
68540 /* Opcode: Compare P1 P2 P3 P4 P5
68541 **
68542 ** Compare two vectors of registers in reg(P1)..reg(P1+P3-1) (call this
68543 ** vector "A") and in reg(P2)..reg(P2+P3-1) ("B").  Save the result of
68544 ** the comparison for use by the next OP_Jump instruct.
68545 **
68546 ** If P5 has the OPFLAG_PERMUTE bit set, then the order of comparison is
68547 ** determined by the most recent OP_Permutation operator.  If the
68548 ** OPFLAG_PERMUTE bit is clear, then register are compared in sequential
68549 ** order.
68550 **
68551 ** P4 is a KeyInfo structure that defines collating sequences and sort
68552 ** orders for the comparison.  The permutation applies to registers
68553 ** only.  The KeyInfo elements are used sequentially.
68554 **
68555 ** The comparison is a sort comparison, so NULLs compare equal,
68556 ** NULLs are less than numbers, numbers are less than strings,
68557 ** and strings are less than blobs.
68558 */
68559 case OP_Compare: {
68560 #if 0  /* local variables moved into u.am */
68561   int n;
68562   int i;
68563   int p1;
68564   int p2;
68565   const KeyInfo *pKeyInfo;
68566   int idx;
68567   CollSeq *pColl;    /* Collating sequence to use on this term */
68568   int bRev;          /* True for DESCENDING sort order */
68569 #endif /* local variables moved into u.am */
68570 
68571   if( (pOp->p5 & OPFLAG_PERMUTE)==0 ) aPermute = 0;
68572   u.am.n = pOp->p3;
68573   u.am.pKeyInfo = pOp->p4.pKeyInfo;
68574   assert( u.am.n>0 );
68575   assert( u.am.pKeyInfo!=0 );
68576   u.am.p1 = pOp->p1;
68577   u.am.p2 = pOp->p2;
68578 #if SQLITE_DEBUG
68579   if( aPermute ){
68580     int k, mx = 0;
68581     for(k=0; k<u.am.n; k++) if( aPermute[k]>mx ) mx = aPermute[k];
68582     assert( u.am.p1>0 && u.am.p1+mx<=(p->nMem-p->nCursor)+1 );
68583     assert( u.am.p2>0 && u.am.p2+mx<=(p->nMem-p->nCursor)+1 );
68584   }else{
68585     assert( u.am.p1>0 && u.am.p1+u.am.n<=(p->nMem-p->nCursor)+1 );
68586     assert( u.am.p2>0 && u.am.p2+u.am.n<=(p->nMem-p->nCursor)+1 );
68587   }
68588 #endif /* SQLITE_DEBUG */
68589   for(u.am.i=0; u.am.i<u.am.n; u.am.i++){
68590     u.am.idx = aPermute ? aPermute[u.am.i] : u.am.i;
68591     assert( memIsValid(&aMem[u.am.p1+u.am.idx]) );
68592     assert( memIsValid(&aMem[u.am.p2+u.am.idx]) );
68593     REGISTER_TRACE(u.am.p1+u.am.idx, &aMem[u.am.p1+u.am.idx]);
68594     REGISTER_TRACE(u.am.p2+u.am.idx, &aMem[u.am.p2+u.am.idx]);
68595     assert( u.am.i<u.am.pKeyInfo->nField );
68596     u.am.pColl = u.am.pKeyInfo->aColl[u.am.i];
68597     u.am.bRev = u.am.pKeyInfo->aSortOrder[u.am.i];
68598     iCompare = sqlite3MemCompare(&aMem[u.am.p1+u.am.idx], &aMem[u.am.p2+u.am.idx], u.am.pColl);
68599     if( iCompare ){
68600       if( u.am.bRev ) iCompare = -iCompare;
68601       break;
68602     }
68603   }
68604   aPermute = 0;
68605   break;
68606 }
68607 
68608 /* Opcode: Jump P1 P2 P3 * *
68609 **
68610 ** Jump to the instruction at address P1, P2, or P3 depending on whether
68611 ** in the most recent OP_Compare instruction the P1 vector was less than
68612 ** equal to, or greater than the P2 vector, respectively.
68613 */
68614 case OP_Jump: {             /* jump */
68615   if( iCompare<0 ){
68616     pc = pOp->p1 - 1;
68617   }else if( iCompare==0 ){
68618     pc = pOp->p2 - 1;
68619   }else{
68620     pc = pOp->p3 - 1;
68621   }
68622   break;
68623 }
68624 
68625 /* Opcode: And P1 P2 P3 * *
68626 ** Synopsis: r[P3]=(r[P1] && r[P2])
68627 **
68628 ** Take the logical AND of the values in registers P1 and P2 and
68629 ** write the result into register P3.
68630 **
68631 ** If either P1 or P2 is 0 (false) then the result is 0 even if
68632 ** the other input is NULL.  A NULL and true or two NULLs give
68633 ** a NULL output.
68634 */
68635 /* Opcode: Or P1 P2 P3 * *
68636 ** Synopsis: r[P3]=(r[P1] || r[P2])
68637 **
68638 ** Take the logical OR of the values in register P1 and P2 and
68639 ** store the answer in register P3.
68640 **
68641 ** If either P1 or P2 is nonzero (true) then the result is 1 (true)
68642 ** even if the other input is NULL.  A NULL and false or two NULLs
68643 ** give a NULL output.
68644 */
68645 case OP_And:              /* same as TK_AND, in1, in2, out3 */
68646 case OP_Or: {             /* same as TK_OR, in1, in2, out3 */
68647 #if 0  /* local variables moved into u.an */
68648   int v1;    /* Left operand:  0==FALSE, 1==TRUE, 2==UNKNOWN or NULL */
68649   int v2;    /* Right operand: 0==FALSE, 1==TRUE, 2==UNKNOWN or NULL */
68650 #endif /* local variables moved into u.an */
68651 
68652   pIn1 = &aMem[pOp->p1];
68653   if( pIn1->flags & MEM_Null ){
68654     u.an.v1 = 2;
68655   }else{
68656     u.an.v1 = sqlite3VdbeIntValue(pIn1)!=0;
68657   }
68658   pIn2 = &aMem[pOp->p2];
68659   if( pIn2->flags & MEM_Null ){
68660     u.an.v2 = 2;
68661   }else{
68662     u.an.v2 = sqlite3VdbeIntValue(pIn2)!=0;
68663   }
68664   if( pOp->opcode==OP_And ){
68665     static const unsigned char and_logic[] = { 0, 0, 0, 0, 1, 2, 0, 2, 2 };
68666     u.an.v1 = and_logic[u.an.v1*3+u.an.v2];
68667   }else{
68668     static const unsigned char or_logic[] = { 0, 1, 2, 1, 1, 1, 2, 1, 2 };
68669     u.an.v1 = or_logic[u.an.v1*3+u.an.v2];
68670   }
68671   pOut = &aMem[pOp->p3];
68672   if( u.an.v1==2 ){
68673     MemSetTypeFlag(pOut, MEM_Null);
68674   }else{
68675     pOut->u.i = u.an.v1;
68676     MemSetTypeFlag(pOut, MEM_Int);
68677   }
68678   break;
68679 }
68680 
68681 /* Opcode: Not P1 P2 * * *
68682 ** Synopsis: r[P2]= !r[P1]
68683 **
68684 ** Interpret the value in register P1 as a boolean value.  Store the
68685 ** boolean complement in register P2.  If the value in register P1 is 
68686 ** NULL, then a NULL is stored in P2.
68687 */
68688 case OP_Not: {                /* same as TK_NOT, in1, out2 */
68689   pIn1 = &aMem[pOp->p1];
68690   pOut = &aMem[pOp->p2];
68691   if( pIn1->flags & MEM_Null ){
68692     sqlite3VdbeMemSetNull(pOut);
68693   }else{
68694     sqlite3VdbeMemSetInt64(pOut, !sqlite3VdbeIntValue(pIn1));
68695   }
68696   break;
68697 }
68698 
68699 /* Opcode: BitNot P1 P2 * * *
68700 ** Synopsis: r[P1]= ~r[P1]
68701 **
68702 ** Interpret the content of register P1 as an integer.  Store the
68703 ** ones-complement of the P1 value into register P2.  If P1 holds
68704 ** a NULL then store a NULL in P2.
68705 */
68706 case OP_BitNot: {             /* same as TK_BITNOT, in1, out2 */
68707   pIn1 = &aMem[pOp->p1];
68708   pOut = &aMem[pOp->p2];
68709   if( pIn1->flags & MEM_Null ){
68710     sqlite3VdbeMemSetNull(pOut);
68711   }else{
68712     sqlite3VdbeMemSetInt64(pOut, ~sqlite3VdbeIntValue(pIn1));
68713   }
68714   break;
68715 }
68716 
68717 /* Opcode: Once P1 P2 * * *
68718 **
68719 ** Check if OP_Once flag P1 is set. If so, jump to instruction P2. Otherwise,
68720 ** set the flag and fall through to the next instruction.
68721 */
68722 case OP_Once: {             /* jump */
68723   assert( pOp->p1<p->nOnceFlag );
68724   if( p->aOnceFlag[pOp->p1] ){
68725     pc = pOp->p2-1;
68726   }else{
68727     p->aOnceFlag[pOp->p1] = 1;
68728   }
68729   break;
68730 }
68731 
68732 /* Opcode: If P1 P2 P3 * *
68733 **
68734 ** Jump to P2 if the value in register P1 is true.  The value
68735 ** is considered true if it is numeric and non-zero.  If the value
68736 ** in P1 is NULL then take the jump if P3 is non-zero.
68737 */
68738 /* Opcode: IfNot P1 P2 P3 * *
68739 **
68740 ** Jump to P2 if the value in register P1 is False.  The value
68741 ** is considered false if it has a numeric value of zero.  If the value
68742 ** in P1 is NULL then take the jump if P3 is zero.
68743 */
68744 case OP_If:                 /* jump, in1 */
68745 case OP_IfNot: {            /* jump, in1 */
68746 #if 0  /* local variables moved into u.ao */
68747   int c;
68748 #endif /* local variables moved into u.ao */
68749   pIn1 = &aMem[pOp->p1];
68750   if( pIn1->flags & MEM_Null ){
68751     u.ao.c = pOp->p3;
68752   }else{
68753 #ifdef SQLITE_OMIT_FLOATING_POINT
68754     u.ao.c = sqlite3VdbeIntValue(pIn1)!=0;
68755 #else
68756     u.ao.c = sqlite3VdbeRealValue(pIn1)!=0.0;
68757 #endif
68758     if( pOp->opcode==OP_IfNot ) u.ao.c = !u.ao.c;
68759   }
68760   if( u.ao.c ){
68761     pc = pOp->p2-1;
68762   }
68763   break;
68764 }
68765 
68766 /* Opcode: IsNull P1 P2 * * *
68767 ** Synopsis:  if r[P1]==NULL goto P2
68768 **
68769 ** Jump to P2 if the value in register P1 is NULL.
68770 */
68771 case OP_IsNull: {            /* same as TK_ISNULL, jump, in1 */
68772   pIn1 = &aMem[pOp->p1];
68773   if( (pIn1->flags & MEM_Null)!=0 ){
68774     pc = pOp->p2 - 1;
68775   }
68776   break;
68777 }
68778 
68779 /* Opcode: NotNull P1 P2 * * *
68780 ** Synopsis: if r[P1]!=NULL goto P2
68781 **
68782 ** Jump to P2 if the value in register P1 is not NULL.  
68783 */
68784 case OP_NotNull: {            /* same as TK_NOTNULL, jump, in1 */
68785   pIn1 = &aMem[pOp->p1];
68786   if( (pIn1->flags & MEM_Null)==0 ){
68787     pc = pOp->p2 - 1;
68788   }
68789   break;
68790 }
68791 
68792 /* Opcode: Column P1 P2 P3 P4 P5
68793 ** Synopsis:  r[P3]=PX
68794 **
68795 ** Interpret the data that cursor P1 points to as a structure built using
68796 ** the MakeRecord instruction.  (See the MakeRecord opcode for additional
68797 ** information about the format of the data.)  Extract the P2-th column
68798 ** from this record.  If there are less that (P2+1) 
68799 ** values in the record, extract a NULL.
68800 **
68801 ** The value extracted is stored in register P3.
68802 **
68803 ** If the column contains fewer than P2 fields, then extract a NULL.  Or,
68804 ** if the P4 argument is a P4_MEM use the value of the P4 argument as
68805 ** the result.
68806 **
68807 ** If the OPFLAG_CLEARCACHE bit is set on P5 and P1 is a pseudo-table cursor,
68808 ** then the cache of the cursor is reset prior to extracting the column.
68809 ** The first OP_Column against a pseudo-table after the value of the content
68810 ** register has changed should have this bit set.
68811 **
68812 ** If the OPFLAG_LENGTHARG and OPFLAG_TYPEOFARG bits are set on P5 when
68813 ** the result is guaranteed to only be used as the argument of a length()
68814 ** or typeof() function, respectively.  The loading of large blobs can be
68815 ** skipped for length() and all content loading can be skipped for typeof().
68816 */
68817 case OP_Column: {
68818 #if 0  /* local variables moved into u.ap */
68819   i64 payloadSize64; /* Number of bytes in the record */
68820   int p2;            /* column number to retrieve */
68821   VdbeCursor *pC;    /* The VDBE cursor */
68822   BtCursor *pCrsr;   /* The BTree cursor */
68823   u32 *aType;        /* aType[i] holds the numeric type of the i-th column */
68824   u32 *aOffset;      /* aOffset[i] is offset to start of data for i-th column */
68825   int len;           /* The length of the serialized data for the column */
68826   int i;             /* Loop counter */
68827   Mem *pDest;        /* Where to write the extracted value */
68828   Mem sMem;          /* For storing the record being decoded */
68829   const u8 *zData;   /* Part of the record being decoded */
68830   const u8 *zHdr;    /* Next unparsed byte of the header */
68831   const u8 *zEndHdr; /* Pointer to first byte after the header */
68832   u32 offset;        /* Offset into the data */
68833   u32 szField;       /* Number of bytes in the content of a field */
68834   u32 avail;         /* Number of bytes of available data */
68835   u32 t;             /* A type code from the record header */
68836   Mem *pReg;         /* PseudoTable input register */
68837 #endif /* local variables moved into u.ap */
68838 
68839   u.ap.p2 = pOp->p2;
68840   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
68841   u.ap.pDest = &aMem[pOp->p3];
68842   memAboutToChange(p, u.ap.pDest);
68843   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
68844   u.ap.pC = p->apCsr[pOp->p1];
68845   assert( u.ap.pC!=0 );
68846   assert( u.ap.p2<u.ap.pC->nField );
68847   u.ap.aType = u.ap.pC->aType;
68848   u.ap.aOffset = u.ap.aType + u.ap.pC->nField;
68849 #ifndef SQLITE_OMIT_VIRTUALTABLE
68850   assert( u.ap.pC->pVtabCursor==0 ); /* OP_Column never called on virtual table */
68851 #endif
68852   u.ap.pCrsr = u.ap.pC->pCursor;
68853   assert( u.ap.pCrsr!=0 || u.ap.pC->pseudoTableReg>0 ); /* u.ap.pCrsr NULL on PseudoTables */
68854   assert( u.ap.pCrsr!=0 || u.ap.pC->nullRow );          /* u.ap.pC->nullRow on PseudoTables */
68855 
68856   /* If the cursor cache is stale, bring it up-to-date */
68857   rc = sqlite3VdbeCursorMoveto(u.ap.pC);
68858   if( rc ) goto abort_due_to_error;
68859   if( u.ap.pC->cacheStatus!=p->cacheCtr || (pOp->p5&OPFLAG_CLEARCACHE)!=0 ){
68860     if( u.ap.pC->nullRow ){
68861       if( u.ap.pCrsr==0 ){
68862         assert( u.ap.pC->pseudoTableReg>0 );
68863         u.ap.pReg = &aMem[u.ap.pC->pseudoTableReg];
68864         if( u.ap.pC->multiPseudo ){
68865           sqlite3VdbeMemShallowCopy(u.ap.pDest, u.ap.pReg+u.ap.p2, MEM_Ephem);
68866           Deephemeralize(u.ap.pDest);
68867           goto op_column_out;
68868         }
68869         assert( u.ap.pReg->flags & MEM_Blob );
68870         assert( memIsValid(u.ap.pReg) );
68871         u.ap.pC->payloadSize = u.ap.pC->szRow = u.ap.avail = u.ap.pReg->n;
68872         u.ap.pC->aRow = (u8*)u.ap.pReg->z;
68873       }else{
68874         MemSetTypeFlag(u.ap.pDest, MEM_Null);
68875         goto op_column_out;
68876       }
68877     }else{
68878       assert( u.ap.pCrsr );
68879       if( u.ap.pC->isTable==0 ){
68880         assert( sqlite3BtreeCursorIsValid(u.ap.pCrsr) );
68881         VVA_ONLY(rc =) sqlite3BtreeKeySize(u.ap.pCrsr, &u.ap.payloadSize64);
68882         assert( rc==SQLITE_OK ); /* True because of CursorMoveto() call above */
68883         /* sqlite3BtreeParseCellPtr() uses getVarint32() to extract the
68884         ** payload size, so it is impossible for u.ap.payloadSize64 to be
68885         ** larger than 32 bits. */
68886         assert( (u.ap.payloadSize64 & SQLITE_MAX_U32)==(u64)u.ap.payloadSize64 );
68887         u.ap.pC->aRow = sqlite3BtreeKeyFetch(u.ap.pCrsr, &u.ap.avail);
68888         u.ap.pC->payloadSize = (u32)u.ap.payloadSize64;
68889       }else{
68890         assert( sqlite3BtreeCursorIsValid(u.ap.pCrsr) );
68891         VVA_ONLY(rc =) sqlite3BtreeDataSize(u.ap.pCrsr, &u.ap.pC->payloadSize);
68892         assert( rc==SQLITE_OK );   /* DataSize() cannot fail */
68893         u.ap.pC->aRow = sqlite3BtreeDataFetch(u.ap.pCrsr, &u.ap.avail);
68894       }
68895       assert( u.ap.avail<=65536 );  /* Maximum page size is 64KiB */
68896       if( u.ap.pC->payloadSize <= (u32)u.ap.avail ){
68897         u.ap.pC->szRow = u.ap.pC->payloadSize;
68898       }else{
68899         u.ap.pC->szRow = u.ap.avail;
68900       }
68901       if( u.ap.pC->payloadSize > (u32)db->aLimit[SQLITE_LIMIT_LENGTH] ){
68902         goto too_big;
68903       }
68904     }
68905     u.ap.pC->cacheStatus = p->cacheCtr;
68906     u.ap.pC->iHdrOffset = getVarint32(u.ap.pC->aRow, u.ap.offset);
68907     u.ap.pC->nHdrParsed = 0;
68908     u.ap.aOffset[0] = u.ap.offset;
68909     if( u.ap.avail<u.ap.offset ){
68910       /* u.ap.pC->aRow does not have to hold the entire row, but it does at least
68911       ** need to cover the header of the record.  If u.ap.pC->aRow does not contain
68912       ** the complete header, then set it to zero, forcing the header to be
68913       ** dynamically allocated. */
68914       u.ap.pC->aRow = 0;
68915       u.ap.pC->szRow = 0;
68916     }
68917 
68918     /* Make sure a corrupt database has not given us an oversize header.
68919     ** Do this now to avoid an oversize memory allocation.
68920     **
68921     ** Type entries can be between 1 and 5 bytes each.  But 4 and 5 byte
68922     ** types use so much data space that there can only be 4096 and 32 of
68923     ** them, respectively.  So the maximum header length results from a
68924     ** 3-byte type for each of the maximum of 32768 columns plus three
68925     ** extra bytes for the header length itself.  32768*3 + 3 = 98307.
68926     */
68927     if( u.ap.offset > 98307 || u.ap.offset > u.ap.pC->payloadSize ){
68928       rc = SQLITE_CORRUPT_BKPT;
68929       goto op_column_error;
68930     }
68931   }
68932 
68933   /* Make sure at least the first u.ap.p2+1 entries of the header have been
68934   ** parsed and valid information is in u.ap.aOffset[] and u.ap.aType[].
68935   */
68936   if( u.ap.pC->nHdrParsed<=u.ap.p2 ){
68937     /* If there is more header available for parsing in the record, try
68938     ** to extract additional fields up through the u.ap.p2+1-th field
68939     */
68940     if( u.ap.pC->iHdrOffset<u.ap.aOffset[0] ){
68941       /* Make sure u.ap.zData points to enough of the record to cover the header. */
68942       if( u.ap.pC->aRow==0 ){
68943         memset(&u.ap.sMem, 0, sizeof(u.ap.sMem));
68944         rc = sqlite3VdbeMemFromBtree(u.ap.pCrsr, 0, u.ap.aOffset[0],
68945                                      !u.ap.pC->isTable, &u.ap.sMem);
68946         if( rc!=SQLITE_OK ){
68947           goto op_column_error;
68948         }
68949         u.ap.zData = (u8*)u.ap.sMem.z;
68950       }else{
68951         u.ap.zData = u.ap.pC->aRow;
68952       }
68953 
68954       /* Fill in u.ap.aType[u.ap.i] and u.ap.aOffset[u.ap.i] values through the u.ap.p2-th field. */
68955       u.ap.i = u.ap.pC->nHdrParsed;
68956       u.ap.offset = u.ap.aOffset[u.ap.i];
68957       u.ap.zHdr = u.ap.zData + u.ap.pC->iHdrOffset;
68958       u.ap.zEndHdr = u.ap.zData + u.ap.aOffset[0];
68959       assert( u.ap.i<=u.ap.p2 && u.ap.zHdr<u.ap.zEndHdr );
68960       do{
68961         if( u.ap.zHdr[0]<0x80 ){
68962           u.ap.t = u.ap.zHdr[0];
68963           u.ap.zHdr++;
68964         }else{
68965           u.ap.zHdr += sqlite3GetVarint32(u.ap.zHdr, &u.ap.t);
68966         }
68967         u.ap.aType[u.ap.i] = u.ap.t;
68968         u.ap.szField = sqlite3VdbeSerialTypeLen(u.ap.t);
68969         u.ap.offset += u.ap.szField;
68970         if( u.ap.offset<u.ap.szField ){  /* True if u.ap.offset overflows */
68971           u.ap.zHdr = &u.ap.zEndHdr[1];  /* Forces SQLITE_CORRUPT return below */
68972           break;
68973         }
68974         u.ap.i++;
68975         u.ap.aOffset[u.ap.i] = u.ap.offset;
68976       }while( u.ap.i<=u.ap.p2 && u.ap.zHdr<u.ap.zEndHdr );
68977       u.ap.pC->nHdrParsed = u.ap.i;
68978       u.ap.pC->iHdrOffset = (u32)(u.ap.zHdr - u.ap.zData);
68979       if( u.ap.pC->aRow==0 ){
68980         sqlite3VdbeMemRelease(&u.ap.sMem);
68981         u.ap.sMem.flags = MEM_Null;
68982       }
68983 
68984       /* If we have read more header data than was contained in the header,
68985       ** or if the end of the last field appears to be past the end of the
68986       ** record, or if the end of the last field appears to be before the end
68987       ** of the record (when all fields present), then we must be dealing
68988       ** with a corrupt database.
68989       */
68990       if( (u.ap.zHdr > u.ap.zEndHdr)
68991        || (u.ap.offset > u.ap.pC->payloadSize)
68992        || (u.ap.zHdr==u.ap.zEndHdr && u.ap.offset!=u.ap.pC->payloadSize)
68993       ){
68994         rc = SQLITE_CORRUPT_BKPT;
68995         goto op_column_error;
68996       }
68997     }
68998 
68999     /* If after trying to extra new entries from the header, nHdrParsed is
69000     ** still not up to u.ap.p2, that means that the record has fewer than u.ap.p2
69001     ** columns.  So the result will be either the default value or a NULL.
69002     */
69003     if( u.ap.pC->nHdrParsed<=u.ap.p2 ){
69004       if( pOp->p4type==P4_MEM ){
69005         sqlite3VdbeMemShallowCopy(u.ap.pDest, pOp->p4.pMem, MEM_Static);
69006       }else{
69007         MemSetTypeFlag(u.ap.pDest, MEM_Null);
69008       }
69009       goto op_column_out;
69010     }
69011   }
69012 
69013   /* Extract the content for the u.ap.p2+1-th column.  Control can only
69014   ** reach this point if u.ap.aOffset[u.ap.p2], u.ap.aOffset[u.ap.p2+1], and u.ap.aType[u.ap.p2] are
69015   ** all valid.
69016   */
69017   assert( u.ap.p2<u.ap.pC->nHdrParsed );
69018   assert( rc==SQLITE_OK );
69019   if( u.ap.pC->szRow>=u.ap.aOffset[u.ap.p2+1] ){
69020     /* This is the common case where the desired content fits on the original
69021     ** page - where the content is not on an overflow page */
69022     VdbeMemRelease(u.ap.pDest);
69023     sqlite3VdbeSerialGet(u.ap.pC->aRow+u.ap.aOffset[u.ap.p2], u.ap.aType[u.ap.p2], u.ap.pDest);
69024   }else{
69025     /* This branch happens only when content is on overflow pages */
69026     u.ap.t = u.ap.aType[u.ap.p2];
69027     if( ((pOp->p5 & (OPFLAG_LENGTHARG|OPFLAG_TYPEOFARG))!=0
69028           && ((u.ap.t>=12 && (u.ap.t&1)==0) || (pOp->p5 & OPFLAG_TYPEOFARG)!=0))
69029      || (u.ap.len = sqlite3VdbeSerialTypeLen(u.ap.t))==0
69030     ){
69031       /* Content is irrelevant for the typeof() function and for
69032       ** the length(X) function if X is a blob.  So we might as well use
69033       ** bogus content rather than reading content from disk.  NULL works
69034       ** for text and blob and whatever is in the u.ap.payloadSize64 variable
69035       ** will work for everything else.  Content is also irrelevant if
69036       ** the content length is 0. */
69037       u.ap.zData = u.ap.t<=13 ? (u8*)&u.ap.payloadSize64 : 0;
69038       u.ap.sMem.zMalloc = 0;
69039     }else{
69040       memset(&u.ap.sMem, 0, sizeof(u.ap.sMem));
69041       sqlite3VdbeMemMove(&u.ap.sMem, u.ap.pDest);
69042       rc = sqlite3VdbeMemFromBtree(u.ap.pCrsr, u.ap.aOffset[u.ap.p2], u.ap.len, !u.ap.pC->isTable,
69043                                    &u.ap.sMem);
69044       if( rc!=SQLITE_OK ){
69045         goto op_column_error;
69046       }
69047       u.ap.zData = (u8*)u.ap.sMem.z;
69048     }
69049     sqlite3VdbeSerialGet(u.ap.zData, u.ap.t, u.ap.pDest);
69050     /* If we dynamically allocated space to hold the data (in the
69051     ** sqlite3VdbeMemFromBtree() call above) then transfer control of that
69052     ** dynamically allocated space over to the u.ap.pDest structure.
69053     ** This prevents a memory copy. */
69054     if( u.ap.sMem.zMalloc ){
69055       assert( u.ap.sMem.z==u.ap.sMem.zMalloc );
69056       assert( !(u.ap.pDest->flags & MEM_Dyn) );
69057       assert( !(u.ap.pDest->flags & (MEM_Blob|MEM_Str)) || u.ap.pDest->z==u.ap.sMem.z );
69058       u.ap.pDest->flags &= ~(MEM_Ephem|MEM_Static);
69059       u.ap.pDest->flags |= MEM_Term;
69060       u.ap.pDest->z = u.ap.sMem.z;
69061       u.ap.pDest->zMalloc = u.ap.sMem.zMalloc;
69062     }
69063   }
69064   u.ap.pDest->enc = encoding;
69065 
69066 op_column_out:
69067   rc = sqlite3VdbeMemMakeWriteable(u.ap.pDest);
69068 op_column_error:
69069   UPDATE_MAX_BLOBSIZE(u.ap.pDest);
69070   REGISTER_TRACE(pOp->p3, u.ap.pDest);
69071   break;
69072 }
69073 
69074 /* Opcode: Affinity P1 P2 * P4 *
69075 ** Synopsis: affinity(r[P1@P2])
69076 **
69077 ** Apply affinities to a range of P2 registers starting with P1.
69078 **
69079 ** P4 is a string that is P2 characters long. The nth character of the
69080 ** string indicates the column affinity that should be used for the nth
69081 ** memory cell in the range.
69082 */
69083 case OP_Affinity: {
69084 #if 0  /* local variables moved into u.aq */
69085   const char *zAffinity;   /* The affinity to be applied */
69086   char cAff;               /* A single character of affinity */
69087 #endif /* local variables moved into u.aq */
69088 
69089   u.aq.zAffinity = pOp->p4.z;
69090   assert( u.aq.zAffinity!=0 );
69091   assert( u.aq.zAffinity[pOp->p2]==0 );
69092   pIn1 = &aMem[pOp->p1];
69093   while( (u.aq.cAff = *(u.aq.zAffinity++))!=0 ){
69094     assert( pIn1 <= &p->aMem[(p->nMem-p->nCursor)] );
69095     assert( memIsValid(pIn1) );
69096     ExpandBlob(pIn1);
69097     applyAffinity(pIn1, u.aq.cAff, encoding);
69098     pIn1++;
69099   }
69100   break;
69101 }
69102 
69103 /* Opcode: MakeRecord P1 P2 P3 P4 *
69104 ** Synopsis: r[P3]=mkrec(r[P1@P2])
69105 **
69106 ** Convert P2 registers beginning with P1 into the [record format]
69107 ** use as a data record in a database table or as a key
69108 ** in an index.  The OP_Column opcode can decode the record later.
69109 **
69110 ** P4 may be a string that is P2 characters long.  The nth character of the
69111 ** string indicates the column affinity that should be used for the nth
69112 ** field of the index key.
69113 **
69114 ** The mapping from character to affinity is given by the SQLITE_AFF_
69115 ** macros defined in sqliteInt.h.
69116 **
69117 ** If P4 is NULL then all index fields have the affinity NONE.
69118 */
69119 case OP_MakeRecord: {
69120 #if 0  /* local variables moved into u.ar */
69121   u8 *zNewRecord;        /* A buffer to hold the data for the new record */
69122   Mem *pRec;             /* The new record */
69123   u64 nData;             /* Number of bytes of data space */
69124   int nHdr;              /* Number of bytes of header space */
69125   i64 nByte;             /* Data space required for this record */
69126   int nZero;             /* Number of zero bytes at the end of the record */
69127   int nVarint;           /* Number of bytes in a varint */
69128   u32 serial_type;       /* Type field */
69129   Mem *pData0;           /* First field to be combined into the record */
69130   Mem *pLast;            /* Last field of the record */
69131   int nField;            /* Number of fields in the record */
69132   char *zAffinity;       /* The affinity string for the record */
69133   int file_format;       /* File format to use for encoding */
69134   int i;                 /* Space used in zNewRecord[] */
69135   int len;               /* Length of a field */
69136 #endif /* local variables moved into u.ar */
69137 
69138   /* Assuming the record contains N fields, the record format looks
69139   ** like this:
69140   **
69141   ** ------------------------------------------------------------------------
69142   ** | hdr-size | type 0 | type 1 | ... | type N-1 | data0 | ... | data N-1 |
69143   ** ------------------------------------------------------------------------
69144   **
69145   ** Data(0) is taken from register P1.  Data(1) comes from register P1+1
69146   ** and so froth.
69147   **
69148   ** Each type field is a varint representing the serial type of the
69149   ** corresponding data element (see sqlite3VdbeSerialType()). The
69150   ** hdr-size field is also a varint which is the offset from the beginning
69151   ** of the record to data0.
69152   */
69153   u.ar.nData = 0;         /* Number of bytes of data space */
69154   u.ar.nHdr = 0;          /* Number of bytes of header space */
69155   u.ar.nZero = 0;         /* Number of zero bytes at the end of the record */
69156   u.ar.nField = pOp->p1;
69157   u.ar.zAffinity = pOp->p4.z;
69158   assert( u.ar.nField>0 && pOp->p2>0 && pOp->p2+u.ar.nField<=(p->nMem-p->nCursor)+1 );
69159   u.ar.pData0 = &aMem[u.ar.nField];
69160   u.ar.nField = pOp->p2;
69161   u.ar.pLast = &u.ar.pData0[u.ar.nField-1];
69162   u.ar.file_format = p->minWriteFileFormat;
69163 
69164   /* Identify the output register */
69165   assert( pOp->p3<pOp->p1 || pOp->p3>=pOp->p1+pOp->p2 );
69166   pOut = &aMem[pOp->p3];
69167   memAboutToChange(p, pOut);
69168 
69169   /* Loop through the elements that will make up the record to figure
69170   ** out how much space is required for the new record.
69171   */
69172   for(u.ar.pRec=u.ar.pData0; u.ar.pRec<=u.ar.pLast; u.ar.pRec++){
69173     assert( memIsValid(u.ar.pRec) );
69174     if( u.ar.zAffinity ){
69175       applyAffinity(u.ar.pRec, u.ar.zAffinity[u.ar.pRec-u.ar.pData0], encoding);
69176     }
69177     if( u.ar.pRec->flags&MEM_Zero && u.ar.pRec->n>0 ){
69178       sqlite3VdbeMemExpandBlob(u.ar.pRec);
69179     }
69180     u.ar.serial_type = sqlite3VdbeSerialType(u.ar.pRec, u.ar.file_format);
69181     u.ar.len = sqlite3VdbeSerialTypeLen(u.ar.serial_type);
69182     u.ar.nData += u.ar.len;
69183     u.ar.nHdr += sqlite3VarintLen(u.ar.serial_type);
69184     if( u.ar.pRec->flags & MEM_Zero ){
69185       /* Only pure zero-filled BLOBs can be input to this Opcode.
69186       ** We do not allow blobs with a prefix and a zero-filled tail. */
69187       u.ar.nZero += u.ar.pRec->u.nZero;
69188     }else if( u.ar.len ){
69189       u.ar.nZero = 0;
69190     }
69191   }
69192 
69193   /* Add the initial header varint and total the size */
69194   u.ar.nHdr += u.ar.nVarint = sqlite3VarintLen(u.ar.nHdr);
69195   if( u.ar.nVarint<sqlite3VarintLen(u.ar.nHdr) ){
69196     u.ar.nHdr++;
69197   }
69198   u.ar.nByte = u.ar.nHdr+u.ar.nData-u.ar.nZero;
69199   if( u.ar.nByte>db->aLimit[SQLITE_LIMIT_LENGTH] ){
69200     goto too_big;
69201   }
69202 
69203   /* Make sure the output register has a buffer large enough to store
69204   ** the new record. The output register (pOp->p3) is not allowed to
69205   ** be one of the input registers (because the following call to
69206   ** sqlite3VdbeMemGrow() could clobber the value before it is used).
69207   */
69208   if( sqlite3VdbeMemGrow(pOut, (int)u.ar.nByte, 0) ){
69209     goto no_mem;
69210   }
69211   u.ar.zNewRecord = (u8 *)pOut->z;
69212 
69213   /* Write the record */
69214   u.ar.i = putVarint32(u.ar.zNewRecord, u.ar.nHdr);
69215   for(u.ar.pRec=u.ar.pData0; u.ar.pRec<=u.ar.pLast; u.ar.pRec++){
69216     u.ar.serial_type = sqlite3VdbeSerialType(u.ar.pRec, u.ar.file_format);
69217     u.ar.i += putVarint32(&u.ar.zNewRecord[u.ar.i], u.ar.serial_type);      /* serial type */
69218   }
69219   for(u.ar.pRec=u.ar.pData0; u.ar.pRec<=u.ar.pLast; u.ar.pRec++){  /* serial data */
69220     u.ar.i += sqlite3VdbeSerialPut(&u.ar.zNewRecord[u.ar.i], (int)(u.ar.nByte-u.ar.i), u.ar.pRec,u.ar.file_format);
69221   }
69222   assert( u.ar.i==u.ar.nByte );
69223 
69224   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
69225   pOut->n = (int)u.ar.nByte;
69226   pOut->flags = MEM_Blob | MEM_Dyn;
69227   pOut->xDel = 0;
69228   if( u.ar.nZero ){
69229     pOut->u.nZero = u.ar.nZero;
69230     pOut->flags |= MEM_Zero;
69231   }
69232   pOut->enc = SQLITE_UTF8;  /* In case the blob is ever converted to text */
69233   REGISTER_TRACE(pOp->p3, pOut);
69234   UPDATE_MAX_BLOBSIZE(pOut);
69235   break;
69236 }
69237 
69238 /* Opcode: Count P1 P2 * * *
69239 ** Synopsis: r[P2]=count()
69240 **
69241 ** Store the number of entries (an integer value) in the table or index 
69242 ** opened by cursor P1 in register P2
69243 */
69244 #ifndef SQLITE_OMIT_BTREECOUNT
69245 case OP_Count: {         /* out2-prerelease */
69246 #if 0  /* local variables moved into u.as */
69247   i64 nEntry;
69248   BtCursor *pCrsr;
69249 #endif /* local variables moved into u.as */
69250 
69251   u.as.pCrsr = p->apCsr[pOp->p1]->pCursor;
69252   assert( u.as.pCrsr );
69253   rc = sqlite3BtreeCount(u.as.pCrsr, &u.as.nEntry);
69254   pOut->u.i = u.as.nEntry;
69255   break;
69256 }
69257 #endif
69258 
69259 /* Opcode: Savepoint P1 * * P4 *
69260 **
69261 ** Open, release or rollback the savepoint named by parameter P4, depending
69262 ** on the value of P1. To open a new savepoint, P1==0. To release (commit) an
69263 ** existing savepoint, P1==1, or to rollback an existing savepoint P1==2.
69264 */
69265 case OP_Savepoint: {
69266 #if 0  /* local variables moved into u.at */
69267   int p1;                         /* Value of P1 operand */
69268   char *zName;                    /* Name of savepoint */
69269   int nName;
69270   Savepoint *pNew;
69271   Savepoint *pSavepoint;
69272   Savepoint *pTmp;
69273   int iSavepoint;
69274   int ii;
69275 #endif /* local variables moved into u.at */
69276 
69277   u.at.p1 = pOp->p1;
69278   u.at.zName = pOp->p4.z;
69279 
69280   /* Assert that the u.at.p1 parameter is valid. Also that if there is no open
69281   ** transaction, then there cannot be any savepoints.
69282   */
69283   assert( db->pSavepoint==0 || db->autoCommit==0 );
69284   assert( u.at.p1==SAVEPOINT_BEGIN||u.at.p1==SAVEPOINT_RELEASE||u.at.p1==SAVEPOINT_ROLLBACK );
69285   assert( db->pSavepoint || db->isTransactionSavepoint==0 );
69286   assert( checkSavepointCount(db) );
69287   assert( p->bIsReader );
69288 
69289   if( u.at.p1==SAVEPOINT_BEGIN ){
69290     if( db->nVdbeWrite>0 ){
69291       /* A new savepoint cannot be created if there are active write
69292       ** statements (i.e. open read/write incremental blob handles).
69293       */
69294       sqlite3SetString(&p->zErrMsg, db, "cannot open savepoint - "
69295         "SQL statements in progress");
69296       rc = SQLITE_BUSY;
69297     }else{
69298       u.at.nName = sqlite3Strlen30(u.at.zName);
69299 
69300 #ifndef SQLITE_OMIT_VIRTUALTABLE
69301       /* This call is Ok even if this savepoint is actually a transaction
69302       ** savepoint (and therefore should not prompt xSavepoint()) callbacks.
69303       ** If this is a transaction savepoint being opened, it is guaranteed
69304       ** that the db->aVTrans[] array is empty.  */
69305       assert( db->autoCommit==0 || db->nVTrans==0 );
69306       rc = sqlite3VtabSavepoint(db, SAVEPOINT_BEGIN,
69307                                 db->nStatement+db->nSavepoint);
69308       if( rc!=SQLITE_OK ) goto abort_due_to_error;
69309 #endif
69310 
69311       /* Create a new savepoint structure. */
69312       u.at.pNew = sqlite3DbMallocRaw(db, sizeof(Savepoint)+u.at.nName+1);
69313       if( u.at.pNew ){
69314         u.at.pNew->zName = (char *)&u.at.pNew[1];
69315         memcpy(u.at.pNew->zName, u.at.zName, u.at.nName+1);
69316 
69317         /* If there is no open transaction, then mark this as a special
69318         ** "transaction savepoint". */
69319         if( db->autoCommit ){
69320           db->autoCommit = 0;
69321           db->isTransactionSavepoint = 1;
69322         }else{
69323           db->nSavepoint++;
69324         }
69325 
69326         /* Link the new savepoint into the database handle's list. */
69327         u.at.pNew->pNext = db->pSavepoint;
69328         db->pSavepoint = u.at.pNew;
69329         u.at.pNew->nDeferredCons = db->nDeferredCons;
69330         u.at.pNew->nDeferredImmCons = db->nDeferredImmCons;
69331       }
69332     }
69333   }else{
69334     u.at.iSavepoint = 0;
69335 
69336     /* Find the named savepoint. If there is no such savepoint, then an
69337     ** an error is returned to the user.  */
69338     for(
69339       u.at.pSavepoint = db->pSavepoint;
69340       u.at.pSavepoint && sqlite3StrICmp(u.at.pSavepoint->zName, u.at.zName);
69341       u.at.pSavepoint = u.at.pSavepoint->pNext
69342     ){
69343       u.at.iSavepoint++;
69344     }
69345     if( !u.at.pSavepoint ){
69346       sqlite3SetString(&p->zErrMsg, db, "no such savepoint: %s", u.at.zName);
69347       rc = SQLITE_ERROR;
69348     }else if( db->nVdbeWrite>0 && u.at.p1==SAVEPOINT_RELEASE ){
69349       /* It is not possible to release (commit) a savepoint if there are
69350       ** active write statements.
69351       */
69352       sqlite3SetString(&p->zErrMsg, db,
69353         "cannot release savepoint - SQL statements in progress"
69354       );
69355       rc = SQLITE_BUSY;
69356     }else{
69357 
69358       /* Determine whether or not this is a transaction savepoint. If so,
69359       ** and this is a RELEASE command, then the current transaction
69360       ** is committed.
69361       */
69362       int isTransaction = u.at.pSavepoint->pNext==0 && db->isTransactionSavepoint;
69363       if( isTransaction && u.at.p1==SAVEPOINT_RELEASE ){
69364         if( (rc = sqlite3VdbeCheckFk(p, 1))!=SQLITE_OK ){
69365           goto vdbe_return;
69366         }
69367         db->autoCommit = 1;
69368         if( sqlite3VdbeHalt(p)==SQLITE_BUSY ){
69369           p->pc = pc;
69370           db->autoCommit = 0;
69371           p->rc = rc = SQLITE_BUSY;
69372           goto vdbe_return;
69373         }
69374         db->isTransactionSavepoint = 0;
69375         rc = p->rc;
69376       }else{
69377         u.at.iSavepoint = db->nSavepoint - u.at.iSavepoint - 1;
69378         if( u.at.p1==SAVEPOINT_ROLLBACK ){
69379           for(u.at.ii=0; u.at.ii<db->nDb; u.at.ii++){
69380             sqlite3BtreeTripAllCursors(db->aDb[u.at.ii].pBt, SQLITE_ABORT);
69381           }
69382         }
69383         for(u.at.ii=0; u.at.ii<db->nDb; u.at.ii++){
69384           rc = sqlite3BtreeSavepoint(db->aDb[u.at.ii].pBt, u.at.p1, u.at.iSavepoint);
69385           if( rc!=SQLITE_OK ){
69386             goto abort_due_to_error;
69387           }
69388         }
69389         if( u.at.p1==SAVEPOINT_ROLLBACK && (db->flags&SQLITE_InternChanges)!=0 ){
69390           sqlite3ExpirePreparedStatements(db);
69391           sqlite3ResetAllSchemasOfConnection(db);
69392           db->flags = (db->flags | SQLITE_InternChanges);
69393         }
69394       }
69395 
69396       /* Regardless of whether this is a RELEASE or ROLLBACK, destroy all
69397       ** savepoints nested inside of the savepoint being operated on. */
69398       while( db->pSavepoint!=u.at.pSavepoint ){
69399         u.at.pTmp = db->pSavepoint;
69400         db->pSavepoint = u.at.pTmp->pNext;
69401         sqlite3DbFree(db, u.at.pTmp);
69402         db->nSavepoint--;
69403       }
69404 
69405       /* If it is a RELEASE, then destroy the savepoint being operated on
69406       ** too. If it is a ROLLBACK TO, then set the number of deferred
69407       ** constraint violations present in the database to the value stored
69408       ** when the savepoint was created.  */
69409       if( u.at.p1==SAVEPOINT_RELEASE ){
69410         assert( u.at.pSavepoint==db->pSavepoint );
69411         db->pSavepoint = u.at.pSavepoint->pNext;
69412         sqlite3DbFree(db, u.at.pSavepoint);
69413         if( !isTransaction ){
69414           db->nSavepoint--;
69415         }
69416       }else{
69417         db->nDeferredCons = u.at.pSavepoint->nDeferredCons;
69418         db->nDeferredImmCons = u.at.pSavepoint->nDeferredImmCons;
69419       }
69420 
69421       if( !isTransaction ){
69422         rc = sqlite3VtabSavepoint(db, u.at.p1, u.at.iSavepoint);
69423         if( rc!=SQLITE_OK ) goto abort_due_to_error;
69424       }
69425     }
69426   }
69427 
69428   break;
69429 }
69430 
69431 /* Opcode: AutoCommit P1 P2 * * *
69432 **
69433 ** Set the database auto-commit flag to P1 (1 or 0). If P2 is true, roll
69434 ** back any currently active btree transactions. If there are any active
69435 ** VMs (apart from this one), then a ROLLBACK fails.  A COMMIT fails if
69436 ** there are active writing VMs or active VMs that use shared cache.
69437 **
69438 ** This instruction causes the VM to halt.
69439 */
69440 case OP_AutoCommit: {
69441 #if 0  /* local variables moved into u.au */
69442   int desiredAutoCommit;
69443   int iRollback;
69444   int turnOnAC;
69445 #endif /* local variables moved into u.au */
69446 
69447   u.au.desiredAutoCommit = pOp->p1;
69448   u.au.iRollback = pOp->p2;
69449   u.au.turnOnAC = u.au.desiredAutoCommit && !db->autoCommit;
69450   assert( u.au.desiredAutoCommit==1 || u.au.desiredAutoCommit==0 );
69451   assert( u.au.desiredAutoCommit==1 || u.au.iRollback==0 );
69452   assert( db->nVdbeActive>0 );  /* At least this one VM is active */
69453   assert( p->bIsReader );
69454 
69455 #if 0
69456   if( u.au.turnOnAC && u.au.iRollback && db->nVdbeActive>1 ){
69457     /* If this instruction implements a ROLLBACK and other VMs are
69458     ** still running, and a transaction is active, return an error indicating
69459     ** that the other VMs must complete first.
69460     */
69461     sqlite3SetString(&p->zErrMsg, db, "cannot rollback transaction - "
69462         "SQL statements in progress");
69463     rc = SQLITE_BUSY;
69464   }else
69465 #endif
69466   if( u.au.turnOnAC && !u.au.iRollback && db->nVdbeWrite>0 ){
69467     /* If this instruction implements a COMMIT and other VMs are writing
69468     ** return an error indicating that the other VMs must complete first.
69469     */
69470     sqlite3SetString(&p->zErrMsg, db, "cannot commit transaction - "
69471         "SQL statements in progress");
69472     rc = SQLITE_BUSY;
69473   }else if( u.au.desiredAutoCommit!=db->autoCommit ){
69474     if( u.au.iRollback ){
69475       assert( u.au.desiredAutoCommit==1 );
69476       sqlite3RollbackAll(db, SQLITE_ABORT_ROLLBACK);
69477       db->autoCommit = 1;
69478     }else if( (rc = sqlite3VdbeCheckFk(p, 1))!=SQLITE_OK ){
69479       goto vdbe_return;
69480     }else{
69481       db->autoCommit = (u8)u.au.desiredAutoCommit;
69482       if( sqlite3VdbeHalt(p)==SQLITE_BUSY ){
69483         p->pc = pc;
69484         db->autoCommit = (u8)(1-u.au.desiredAutoCommit);
69485         p->rc = rc = SQLITE_BUSY;
69486         goto vdbe_return;
69487       }
69488     }
69489     assert( db->nStatement==0 );
69490     sqlite3CloseSavepoints(db);
69491     if( p->rc==SQLITE_OK ){
69492       rc = SQLITE_DONE;
69493     }else{
69494       rc = SQLITE_ERROR;
69495     }
69496     goto vdbe_return;
69497   }else{
69498     sqlite3SetString(&p->zErrMsg, db,
69499         (!u.au.desiredAutoCommit)?"cannot start a transaction within a transaction":(
69500         (u.au.iRollback)?"cannot rollback - no transaction is active":
69501                    "cannot commit - no transaction is active"));
69502 
69503     rc = SQLITE_ERROR;
69504   }
69505   break;
69506 }
69507 
69508 /* Opcode: Transaction P1 P2 * * *
69509 **
69510 ** Begin a transaction.  The transaction ends when a Commit or Rollback
69511 ** opcode is encountered.  Depending on the ON CONFLICT setting, the
69512 ** transaction might also be rolled back if an error is encountered.
69513 **
69514 ** P1 is the index of the database file on which the transaction is
69515 ** started.  Index 0 is the main database file and index 1 is the
69516 ** file used for temporary tables.  Indices of 2 or more are used for
69517 ** attached databases.
69518 **
69519 ** If P2 is non-zero, then a write-transaction is started.  A RESERVED lock is
69520 ** obtained on the database file when a write-transaction is started.  No
69521 ** other process can start another write transaction while this transaction is
69522 ** underway.  Starting a write transaction also creates a rollback journal. A
69523 ** write transaction must be started before any changes can be made to the
69524 ** database.  If P2 is greater than or equal to 2 then an EXCLUSIVE lock is
69525 ** also obtained on the file.
69526 **
69527 ** If a write-transaction is started and the Vdbe.usesStmtJournal flag is
69528 ** true (this flag is set if the Vdbe may modify more than one row and may
69529 ** throw an ABORT exception), a statement transaction may also be opened.
69530 ** More specifically, a statement transaction is opened iff the database
69531 ** connection is currently not in autocommit mode, or if there are other
69532 ** active statements. A statement transaction allows the changes made by this
69533 ** VDBE to be rolled back after an error without having to roll back the
69534 ** entire transaction. If no error is encountered, the statement transaction
69535 ** will automatically commit when the VDBE halts.
69536 **
69537 ** If P2 is zero, then a read-lock is obtained on the database file.
69538 */
69539 case OP_Transaction: {
69540 #if 0  /* local variables moved into u.av */
69541   Btree *pBt;
69542 #endif /* local variables moved into u.av */
69543 
69544   assert( p->bIsReader );
69545   assert( p->readOnly==0 || pOp->p2==0 );
69546   assert( pOp->p1>=0 && pOp->p1<db->nDb );
69547   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p1))!=0 );
69548   if( pOp->p2 && (db->flags & SQLITE_QueryOnly)!=0 ){
69549     rc = SQLITE_READONLY;
69550     goto abort_due_to_error;
69551   }
69552   u.av.pBt = db->aDb[pOp->p1].pBt;
69553 
69554   if( u.av.pBt ){
69555     rc = sqlite3BtreeBeginTrans(u.av.pBt, pOp->p2);
69556     if( rc==SQLITE_BUSY ){
69557       p->pc = pc;
69558       p->rc = rc = SQLITE_BUSY;
69559       goto vdbe_return;
69560     }
69561     if( rc!=SQLITE_OK ){
69562       goto abort_due_to_error;
69563     }
69564 
69565     if( pOp->p2 && p->usesStmtJournal
69566      && (db->autoCommit==0 || db->nVdbeRead>1)
69567     ){
69568       assert( sqlite3BtreeIsInTrans(u.av.pBt) );
69569       if( p->iStatement==0 ){
69570         assert( db->nStatement>=0 && db->nSavepoint>=0 );
69571         db->nStatement++;
69572         p->iStatement = db->nSavepoint + db->nStatement;
69573       }
69574 
69575       rc = sqlite3VtabSavepoint(db, SAVEPOINT_BEGIN, p->iStatement-1);
69576       if( rc==SQLITE_OK ){
69577         rc = sqlite3BtreeBeginStmt(u.av.pBt, p->iStatement);
69578       }
69579 
69580       /* Store the current value of the database handles deferred constraint
69581       ** counter. If the statement transaction needs to be rolled back,
69582       ** the value of this counter needs to be restored too.  */
69583       p->nStmtDefCons = db->nDeferredCons;
69584       p->nStmtDefImmCons = db->nDeferredImmCons;
69585     }
69586   }
69587   break;
69588 }
69589 
69590 /* Opcode: ReadCookie P1 P2 P3 * *
69591 **
69592 ** Read cookie number P3 from database P1 and write it into register P2.
69593 ** P3==1 is the schema version.  P3==2 is the database format.
69594 ** P3==3 is the recommended pager cache size, and so forth.  P1==0 is
69595 ** the main database file and P1==1 is the database file used to store
69596 ** temporary tables.
69597 **
69598 ** There must be a read-lock on the database (either a transaction
69599 ** must be started or there must be an open cursor) before
69600 ** executing this instruction.
69601 */
69602 case OP_ReadCookie: {               /* out2-prerelease */
69603 #if 0  /* local variables moved into u.aw */
69604   int iMeta;
69605   int iDb;
69606   int iCookie;
69607 #endif /* local variables moved into u.aw */
69608 
69609   assert( p->bIsReader );
69610   u.aw.iDb = pOp->p1;
69611   u.aw.iCookie = pOp->p3;
69612   assert( pOp->p3<SQLITE_N_BTREE_META );
69613   assert( u.aw.iDb>=0 && u.aw.iDb<db->nDb );
69614   assert( db->aDb[u.aw.iDb].pBt!=0 );
69615   assert( (p->btreeMask & (((yDbMask)1)<<u.aw.iDb))!=0 );
69616 
69617   sqlite3BtreeGetMeta(db->aDb[u.aw.iDb].pBt, u.aw.iCookie, (u32 *)&u.aw.iMeta);
69618   pOut->u.i = u.aw.iMeta;
69619   break;
69620 }
69621 
69622 /* Opcode: SetCookie P1 P2 P3 * *
69623 **
69624 ** Write the content of register P3 (interpreted as an integer)
69625 ** into cookie number P2 of database P1.  P2==1 is the schema version.  
69626 ** P2==2 is the database format. P2==3 is the recommended pager cache 
69627 ** size, and so forth.  P1==0 is the main database file and P1==1 is the 
69628 ** database file used to store temporary tables.
69629 **
69630 ** A transaction must be started before executing this opcode.
69631 */
69632 case OP_SetCookie: {       /* in3 */
69633 #if 0  /* local variables moved into u.ax */
69634   Db *pDb;
69635 #endif /* local variables moved into u.ax */
69636   assert( pOp->p2<SQLITE_N_BTREE_META );
69637   assert( pOp->p1>=0 && pOp->p1<db->nDb );
69638   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p1))!=0 );
69639   assert( p->readOnly==0 );
69640   u.ax.pDb = &db->aDb[pOp->p1];
69641   assert( u.ax.pDb->pBt!=0 );
69642   assert( sqlite3SchemaMutexHeld(db, pOp->p1, 0) );
69643   pIn3 = &aMem[pOp->p3];
69644   sqlite3VdbeMemIntegerify(pIn3);
69645   /* See note about index shifting on OP_ReadCookie */
69646   rc = sqlite3BtreeUpdateMeta(u.ax.pDb->pBt, pOp->p2, (int)pIn3->u.i);
69647   if( pOp->p2==BTREE_SCHEMA_VERSION ){
69648     /* When the schema cookie changes, record the new cookie internally */
69649     u.ax.pDb->pSchema->schema_cookie = (int)pIn3->u.i;
69650     db->flags |= SQLITE_InternChanges;
69651   }else if( pOp->p2==BTREE_FILE_FORMAT ){
69652     /* Record changes in the file format */
69653     u.ax.pDb->pSchema->file_format = (u8)pIn3->u.i;
69654   }
69655   if( pOp->p1==1 ){
69656     /* Invalidate all prepared statements whenever the TEMP database
69657     ** schema is changed.  Ticket #1644 */
69658     sqlite3ExpirePreparedStatements(db);
69659     p->expired = 0;
69660   }
69661   break;
69662 }
69663 
69664 /* Opcode: VerifyCookie P1 P2 P3 * *
69665 **
69666 ** Check the value of global database parameter number 0 (the
69667 ** schema version) and make sure it is equal to P2 and that the
69668 ** generation counter on the local schema parse equals P3.
69669 **
69670 ** P1 is the database number which is 0 for the main database file
69671 ** and 1 for the file holding temporary tables and some higher number
69672 ** for auxiliary databases.
69673 **
69674 ** The cookie changes its value whenever the database schema changes.
69675 ** This operation is used to detect when that the cookie has changed
69676 ** and that the current process needs to reread the schema.
69677 **
69678 ** Either a transaction needs to have been started or an OP_Open needs
69679 ** to be executed (to establish a read lock) before this opcode is
69680 ** invoked.
69681 */
69682 case OP_VerifyCookie: {
69683 #if 0  /* local variables moved into u.ay */
69684   int iMeta;
69685   int iGen;
69686   Btree *pBt;
69687 #endif /* local variables moved into u.ay */
69688 
69689   assert( pOp->p1>=0 && pOp->p1<db->nDb );
69690   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p1))!=0 );
69691   assert( sqlite3SchemaMutexHeld(db, pOp->p1, 0) );
69692   assert( p->bIsReader );
69693   u.ay.pBt = db->aDb[pOp->p1].pBt;
69694   if( u.ay.pBt ){
69695     sqlite3BtreeGetMeta(u.ay.pBt, BTREE_SCHEMA_VERSION, (u32 *)&u.ay.iMeta);
69696     u.ay.iGen = db->aDb[pOp->p1].pSchema->iGeneration;
69697   }else{
69698     u.ay.iGen = u.ay.iMeta = 0;
69699   }
69700   if( u.ay.iMeta!=pOp->p2 || u.ay.iGen!=pOp->p3 ){
69701     sqlite3DbFree(db, p->zErrMsg);
69702     p->zErrMsg = sqlite3DbStrDup(db, "database schema has changed");
69703     /* If the schema-cookie from the database file matches the cookie
69704     ** stored with the in-memory representation of the schema, do
69705     ** not reload the schema from the database file.
69706     **
69707     ** If virtual-tables are in use, this is not just an optimization.
69708     ** Often, v-tables store their data in other SQLite tables, which
69709     ** are queried from within xNext() and other v-table methods using
69710     ** prepared queries. If such a query is out-of-date, we do not want to
69711     ** discard the database schema, as the user code implementing the
69712     ** v-table would have to be ready for the sqlite3_vtab structure itself
69713     ** to be invalidated whenever sqlite3_step() is called from within
69714     ** a v-table method.
69715     */
69716     if( db->aDb[pOp->p1].pSchema->schema_cookie!=u.ay.iMeta ){
69717       sqlite3ResetOneSchema(db, pOp->p1);
69718     }
69719 
69720     p->expired = 1;
69721     rc = SQLITE_SCHEMA;
69722   }
69723   break;
69724 }
69725 
69726 /* Opcode: OpenRead P1 P2 P3 P4 P5
69727 ** Synopsis: root=P2 iDb=P3
69728 **
69729 ** Open a read-only cursor for the database table whose root page is
69730 ** P2 in a database file.  The database file is determined by P3. 
69731 ** P3==0 means the main database, P3==1 means the database used for 
69732 ** temporary tables, and P3>1 means used the corresponding attached
69733 ** database.  Give the new cursor an identifier of P1.  The P1
69734 ** values need not be contiguous but all P1 values should be small integers.
69735 ** It is an error for P1 to be negative.
69736 **
69737 ** If P5!=0 then use the content of register P2 as the root page, not
69738 ** the value of P2 itself.
69739 **
69740 ** There will be a read lock on the database whenever there is an
69741 ** open cursor.  If the database was unlocked prior to this instruction
69742 ** then a read lock is acquired as part of this instruction.  A read
69743 ** lock allows other processes to read the database but prohibits
69744 ** any other process from modifying the database.  The read lock is
69745 ** released when all cursors are closed.  If this instruction attempts
69746 ** to get a read lock but fails, the script terminates with an
69747 ** SQLITE_BUSY error code.
69748 **
69749 ** The P4 value may be either an integer (P4_INT32) or a pointer to
69750 ** a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo 
69751 ** structure, then said structure defines the content and collating 
69752 ** sequence of the index being opened. Otherwise, if P4 is an integer 
69753 ** value, it is set to the number of columns in the table.
69754 **
69755 ** See also OpenWrite.
69756 */
69757 /* Opcode: OpenWrite P1 P2 P3 P4 P5
69758 ** Synopsis: root=P2 iDb=P3
69759 **
69760 ** Open a read/write cursor named P1 on the table or index whose root
69761 ** page is P2.  Or if P5!=0 use the content of register P2 to find the
69762 ** root page.
69763 **
69764 ** The P4 value may be either an integer (P4_INT32) or a pointer to
69765 ** a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo 
69766 ** structure, then said structure defines the content and collating 
69767 ** sequence of the index being opened. Otherwise, if P4 is an integer 
69768 ** value, it is set to the number of columns in the table, or to the
69769 ** largest index of any column of the table that is actually used.
69770 **
69771 ** This instruction works just like OpenRead except that it opens the cursor
69772 ** in read/write mode.  For a given table, there can be one or more read-only
69773 ** cursors or a single read/write cursor but not both.
69774 **
69775 ** See also OpenRead.
69776 */
69777 case OP_OpenRead:
69778 case OP_OpenWrite: {
69779 #if 0  /* local variables moved into u.az */
69780   int nField;
69781   KeyInfo *pKeyInfo;
69782   int p2;
69783   int iDb;
69784   int wrFlag;
69785   Btree *pX;
69786   VdbeCursor *pCur;
69787   Db *pDb;
69788 #endif /* local variables moved into u.az */
69789 
69790   assert( (pOp->p5&(OPFLAG_P2ISREG|OPFLAG_BULKCSR))==pOp->p5 );
69791   assert( pOp->opcode==OP_OpenWrite || pOp->p5==0 );
69792   assert( p->bIsReader );
69793   assert( pOp->opcode==OP_OpenRead || p->readOnly==0 );
69794 
69795   if( p->expired ){
69796     rc = SQLITE_ABORT;
69797     break;
69798   }
69799 
69800   u.az.nField = 0;
69801   u.az.pKeyInfo = 0;
69802   u.az.p2 = pOp->p2;
69803   u.az.iDb = pOp->p3;
69804   assert( u.az.iDb>=0 && u.az.iDb<db->nDb );
69805   assert( (p->btreeMask & (((yDbMask)1)<<u.az.iDb))!=0 );
69806   u.az.pDb = &db->aDb[u.az.iDb];
69807   u.az.pX = u.az.pDb->pBt;
69808   assert( u.az.pX!=0 );
69809   if( pOp->opcode==OP_OpenWrite ){
69810     u.az.wrFlag = 1;
69811     assert( sqlite3SchemaMutexHeld(db, u.az.iDb, 0) );
69812     if( u.az.pDb->pSchema->file_format < p->minWriteFileFormat ){
69813       p->minWriteFileFormat = u.az.pDb->pSchema->file_format;
69814     }
69815   }else{
69816     u.az.wrFlag = 0;
69817   }
69818   if( pOp->p5 & OPFLAG_P2ISREG ){
69819     assert( u.az.p2>0 );
69820     assert( u.az.p2<=(p->nMem-p->nCursor) );
69821     pIn2 = &aMem[u.az.p2];
69822     assert( memIsValid(pIn2) );
69823     assert( (pIn2->flags & MEM_Int)!=0 );
69824     sqlite3VdbeMemIntegerify(pIn2);
69825     u.az.p2 = (int)pIn2->u.i;
69826     /* The u.az.p2 value always comes from a prior OP_CreateTable opcode and
69827     ** that opcode will always set the u.az.p2 value to 2 or more or else fail.
69828     ** If there were a failure, the prepared statement would have halted
69829     ** before reaching this instruction. */
69830     if( NEVER(u.az.p2<2) ) {
69831       rc = SQLITE_CORRUPT_BKPT;
69832       goto abort_due_to_error;
69833     }
69834   }
69835   if( pOp->p4type==P4_KEYINFO ){
69836     u.az.pKeyInfo = pOp->p4.pKeyInfo;
69837     assert( u.az.pKeyInfo->enc==ENC(db) );
69838     assert( u.az.pKeyInfo->db==db );
69839     u.az.nField = u.az.pKeyInfo->nField+u.az.pKeyInfo->nXField;
69840   }else if( pOp->p4type==P4_INT32 ){
69841     u.az.nField = pOp->p4.i;
69842   }
69843   assert( pOp->p1>=0 );
69844   assert( u.az.nField>=0 );
69845   testcase( u.az.nField==0 );  /* Table with INTEGER PRIMARY KEY and nothing else */
69846   u.az.pCur = allocateCursor(p, pOp->p1, u.az.nField, u.az.iDb, 1);
69847   if( u.az.pCur==0 ) goto no_mem;
69848   u.az.pCur->nullRow = 1;
69849   u.az.pCur->isOrdered = 1;
69850   rc = sqlite3BtreeCursor(u.az.pX, u.az.p2, u.az.wrFlag, u.az.pKeyInfo, u.az.pCur->pCursor);
69851   u.az.pCur->pKeyInfo = u.az.pKeyInfo;
69852   assert( OPFLAG_BULKCSR==BTREE_BULKLOAD );
69853   sqlite3BtreeCursorHints(u.az.pCur->pCursor, (pOp->p5 & OPFLAG_BULKCSR));
69854 
69855   /* Since it performs no memory allocation or IO, the only value that
69856   ** sqlite3BtreeCursor() may return is SQLITE_OK. */
69857   assert( rc==SQLITE_OK );
69858 
69859   /* Set the VdbeCursor.isTable variable. Previous versions of
69860   ** SQLite used to check if the root-page flags were sane at this point
69861   ** and report database corruption if they were not, but this check has
69862   ** since moved into the btree layer.  */
69863   u.az.pCur->isTable = pOp->p4type!=P4_KEYINFO;
69864   break;
69865 }
69866 
69867 /* Opcode: OpenEphemeral P1 P2 * P4 P5
69868 ** Synopsis: nColumn=P2
69869 **
69870 ** Open a new cursor P1 to a transient table.
69871 ** The cursor is always opened read/write even if 
69872 ** the main database is read-only.  The ephemeral
69873 ** table is deleted automatically when the cursor is closed.
69874 **
69875 ** P2 is the number of columns in the ephemeral table.
69876 ** The cursor points to a BTree table if P4==0 and to a BTree index
69877 ** if P4 is not 0.  If P4 is not NULL, it points to a KeyInfo structure
69878 ** that defines the format of keys in the index.
69879 **
69880 ** The P5 parameter can be a mask of the BTREE_* flags defined
69881 ** in btree.h.  These flags control aspects of the operation of
69882 ** the btree.  The BTREE_OMIT_JOURNAL and BTREE_SINGLE flags are
69883 ** added automatically.
69884 */
69885 /* Opcode: OpenAutoindex P1 P2 * P4 *
69886 ** Synopsis: nColumn=P2
69887 **
69888 ** This opcode works the same as OP_OpenEphemeral.  It has a
69889 ** different name to distinguish its use.  Tables created using
69890 ** by this opcode will be used for automatically created transient
69891 ** indices in joins.
69892 */
69893 case OP_OpenAutoindex: 
69894 case OP_OpenEphemeral: {
69895 #if 0  /* local variables moved into u.ba */
69896   VdbeCursor *pCx;
69897   KeyInfo *pKeyInfo;
69898 #endif /* local variables moved into u.ba */
69899 
69900   static const int vfsFlags =
69901       SQLITE_OPEN_READWRITE |
69902       SQLITE_OPEN_CREATE |
69903       SQLITE_OPEN_EXCLUSIVE |
69904       SQLITE_OPEN_DELETEONCLOSE |
69905       SQLITE_OPEN_TRANSIENT_DB;
69906   assert( pOp->p1>=0 );
69907   assert( pOp->p2>=0 );
69908   u.ba.pCx = allocateCursor(p, pOp->p1, pOp->p2, -1, 1);
69909   if( u.ba.pCx==0 ) goto no_mem;
69910   u.ba.pCx->nullRow = 1;
69911   rc = sqlite3BtreeOpen(db->pVfs, 0, db, &u.ba.pCx->pBt,
69912                         BTREE_OMIT_JOURNAL | BTREE_SINGLE | pOp->p5, vfsFlags);
69913   if( rc==SQLITE_OK ){
69914     rc = sqlite3BtreeBeginTrans(u.ba.pCx->pBt, 1);
69915   }
69916   if( rc==SQLITE_OK ){
69917     /* If a transient index is required, create it by calling
69918     ** sqlite3BtreeCreateTable() with the BTREE_BLOBKEY flag before
69919     ** opening it. If a transient table is required, just use the
69920     ** automatically created table with root-page 1 (an BLOB_INTKEY table).
69921     */
69922     if( (u.ba.pKeyInfo = pOp->p4.pKeyInfo)!=0 ){
69923       int pgno;
69924       assert( pOp->p4type==P4_KEYINFO );
69925       rc = sqlite3BtreeCreateTable(u.ba.pCx->pBt, &pgno, BTREE_BLOBKEY | pOp->p5);
69926       if( rc==SQLITE_OK ){
69927         assert( pgno==MASTER_ROOT+1 );
69928         assert( u.ba.pKeyInfo->db==db );
69929         assert( u.ba.pKeyInfo->enc==ENC(db) );
69930         u.ba.pCx->pKeyInfo = u.ba.pKeyInfo;
69931         rc = sqlite3BtreeCursor(u.ba.pCx->pBt, pgno, 1, u.ba.pKeyInfo, u.ba.pCx->pCursor);
69932       }
69933       u.ba.pCx->isTable = 0;
69934     }else{
69935       rc = sqlite3BtreeCursor(u.ba.pCx->pBt, MASTER_ROOT, 1, 0, u.ba.pCx->pCursor);
69936       u.ba.pCx->isTable = 1;
69937     }
69938   }
69939   u.ba.pCx->isOrdered = (pOp->p5!=BTREE_UNORDERED);
69940   break;
69941 }
69942 
69943 /* Opcode: SorterOpen P1 * * P4 *
69944 **
69945 ** This opcode works like OP_OpenEphemeral except that it opens
69946 ** a transient index that is specifically designed to sort large
69947 ** tables using an external merge-sort algorithm.
69948 */
69949 case OP_SorterOpen: {
69950 #if 0  /* local variables moved into u.bb */
69951   VdbeCursor *pCx;
69952 #endif /* local variables moved into u.bb */
69953 
69954   assert( pOp->p1>=0 );
69955   assert( pOp->p2>=0 );
69956   u.bb.pCx = allocateCursor(p, pOp->p1, pOp->p2, -1, 1);
69957   if( u.bb.pCx==0 ) goto no_mem;
69958   u.bb.pCx->pKeyInfo = pOp->p4.pKeyInfo;
69959   assert( u.bb.pCx->pKeyInfo->db==db );
69960   assert( u.bb.pCx->pKeyInfo->enc==ENC(db) );
69961   rc = sqlite3VdbeSorterInit(db, u.bb.pCx);
69962   break;
69963 }
69964 
69965 /* Opcode: OpenPseudo P1 P2 P3 * P5
69966 ** Synopsis: content in r[P2@P3]
69967 **
69968 ** Open a new cursor that points to a fake table that contains a single
69969 ** row of data.  The content of that one row in the content of memory
69970 ** register P2 when P5==0.  In other words, cursor P1 becomes an alias for the 
69971 ** MEM_Blob content contained in register P2.  When P5==1, then the
69972 ** row is represented by P3 consecutive registers beginning with P2.
69973 **
69974 ** A pseudo-table created by this opcode is used to hold a single
69975 ** row output from the sorter so that the row can be decomposed into
69976 ** individual columns using the OP_Column opcode.  The OP_Column opcode
69977 ** is the only cursor opcode that works with a pseudo-table.
69978 **
69979 ** P3 is the number of fields in the records that will be stored by
69980 ** the pseudo-table.
69981 */
69982 case OP_OpenPseudo: {
69983 #if 0  /* local variables moved into u.bc */
69984   VdbeCursor *pCx;
69985 #endif /* local variables moved into u.bc */
69986 
69987   assert( pOp->p1>=0 );
69988   assert( pOp->p3>=0 );
69989   u.bc.pCx = allocateCursor(p, pOp->p1, pOp->p3, -1, 0);
69990   if( u.bc.pCx==0 ) goto no_mem;
69991   u.bc.pCx->nullRow = 1;
69992   u.bc.pCx->pseudoTableReg = pOp->p2;
69993   u.bc.pCx->isTable = 1;
69994   u.bc.pCx->multiPseudo = pOp->p5;
69995   break;
69996 }
69997 
69998 /* Opcode: Close P1 * * * *
69999 **
70000 ** Close a cursor previously opened as P1.  If P1 is not
70001 ** currently open, this instruction is a no-op.
70002 */
70003 case OP_Close: {
70004   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70005   sqlite3VdbeFreeCursor(p, p->apCsr[pOp->p1]);
70006   p->apCsr[pOp->p1] = 0;
70007   break;
70008 }
70009 
70010 /* Opcode: SeekGe P1 P2 P3 P4 *
70011 ** Synopsis: key=r[P3@P4]
70012 **
70013 ** If cursor P1 refers to an SQL table (B-Tree that uses integer keys), 
70014 ** use the value in register P3 as the key.  If cursor P1 refers 
70015 ** to an SQL index, then P3 is the first in an array of P4 registers 
70016 ** that are used as an unpacked index key. 
70017 **
70018 ** Reposition cursor P1 so that  it points to the smallest entry that 
70019 ** is greater than or equal to the key value. If there are no records 
70020 ** greater than or equal to the key and P2 is not zero, then jump to P2.
70021 **
70022 ** See also: Found, NotFound, Distinct, SeekLt, SeekGt, SeekLe
70023 */
70024 /* Opcode: SeekGt P1 P2 P3 P4 *
70025 ** Synopsis: key=r[P3@P4]
70026 **
70027 ** If cursor P1 refers to an SQL table (B-Tree that uses integer keys), 
70028 ** use the value in register P3 as a key. If cursor P1 refers 
70029 ** to an SQL index, then P3 is the first in an array of P4 registers 
70030 ** that are used as an unpacked index key. 
70031 **
70032 ** Reposition cursor P1 so that  it points to the smallest entry that 
70033 ** is greater than the key value. If there are no records greater than 
70034 ** the key and P2 is not zero, then jump to P2.
70035 **
70036 ** See also: Found, NotFound, Distinct, SeekLt, SeekGe, SeekLe
70037 */
70038 /* Opcode: SeekLt P1 P2 P3 P4 * 
70039 ** Synopsis: key=r[P3@P4]
70040 **
70041 ** If cursor P1 refers to an SQL table (B-Tree that uses integer keys), 
70042 ** use the value in register P3 as a key. If cursor P1 refers 
70043 ** to an SQL index, then P3 is the first in an array of P4 registers 
70044 ** that are used as an unpacked index key. 
70045 **
70046 ** Reposition cursor P1 so that  it points to the largest entry that 
70047 ** is less than the key value. If there are no records less than 
70048 ** the key and P2 is not zero, then jump to P2.
70049 **
70050 ** See also: Found, NotFound, Distinct, SeekGt, SeekGe, SeekLe
70051 */
70052 /* Opcode: SeekLe P1 P2 P3 P4 *
70053 ** Synopsis: key=r[P3@P4]
70054 **
70055 ** If cursor P1 refers to an SQL table (B-Tree that uses integer keys), 
70056 ** use the value in register P3 as a key. If cursor P1 refers 
70057 ** to an SQL index, then P3 is the first in an array of P4 registers 
70058 ** that are used as an unpacked index key. 
70059 **
70060 ** Reposition cursor P1 so that it points to the largest entry that 
70061 ** is less than or equal to the key value. If there are no records 
70062 ** less than or equal to the key and P2 is not zero, then jump to P2.
70063 **
70064 ** See also: Found, NotFound, Distinct, SeekGt, SeekGe, SeekLt
70065 */
70066 case OP_SeekLt:         /* jump, in3 */
70067 case OP_SeekLe:         /* jump, in3 */
70068 case OP_SeekGe:         /* jump, in3 */
70069 case OP_SeekGt: {       /* jump, in3 */
70070 #if 0  /* local variables moved into u.bd */
70071   int res;
70072   int oc;
70073   VdbeCursor *pC;
70074   UnpackedRecord r;
70075   int nField;
70076   i64 iKey;      /* The rowid we are to seek to */
70077 #endif /* local variables moved into u.bd */
70078 
70079   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70080   assert( pOp->p2!=0 );
70081   u.bd.pC = p->apCsr[pOp->p1];
70082   assert( u.bd.pC!=0 );
70083   assert( u.bd.pC->pseudoTableReg==0 );
70084   assert( OP_SeekLe == OP_SeekLt+1 );
70085   assert( OP_SeekGe == OP_SeekLt+2 );
70086   assert( OP_SeekGt == OP_SeekLt+3 );
70087   assert( u.bd.pC->isOrdered );
70088   assert( u.bd.pC->pCursor!=0 );
70089   u.bd.oc = pOp->opcode;
70090   u.bd.pC->nullRow = 0;
70091   if( u.bd.pC->isTable ){
70092     /* The input value in P3 might be of any type: integer, real, string,
70093     ** blob, or NULL.  But it needs to be an integer before we can do
70094     ** the seek, so covert it. */
70095     pIn3 = &aMem[pOp->p3];
70096     applyNumericAffinity(pIn3);
70097     u.bd.iKey = sqlite3VdbeIntValue(pIn3);
70098     u.bd.pC->rowidIsValid = 0;
70099 
70100     /* If the P3 value could not be converted into an integer without
70101     ** loss of information, then special processing is required... */
70102     if( (pIn3->flags & MEM_Int)==0 ){
70103       if( (pIn3->flags & MEM_Real)==0 ){
70104         /* If the P3 value cannot be converted into any kind of a number,
70105         ** then the seek is not possible, so jump to P2 */
70106         pc = pOp->p2 - 1;
70107         break;
70108       }
70109 
70110       /* If the approximation u.bd.iKey is larger than the actual real search
70111       ** term, substitute >= for > and < for <=. e.g. if the search term
70112       ** is 4.9 and the integer approximation 5:
70113       **
70114       **        (x >  4.9)    ->     (x >= 5)
70115       **        (x <= 4.9)    ->     (x <  5)
70116       */
70117       if( pIn3->r<(double)u.bd.iKey ){
70118         assert( OP_SeekGe==(OP_SeekGt-1) );
70119         assert( OP_SeekLt==(OP_SeekLe-1) );
70120         assert( (OP_SeekLe & 0x0001)==(OP_SeekGt & 0x0001) );
70121         if( (u.bd.oc & 0x0001)==(OP_SeekGt & 0x0001) ) u.bd.oc--;
70122       }
70123 
70124       /* If the approximation u.bd.iKey is smaller than the actual real search
70125       ** term, substitute <= for < and > for >=.  */
70126       else if( pIn3->r>(double)u.bd.iKey ){
70127         assert( OP_SeekLe==(OP_SeekLt+1) );
70128         assert( OP_SeekGt==(OP_SeekGe+1) );
70129         assert( (OP_SeekLt & 0x0001)==(OP_SeekGe & 0x0001) );
70130         if( (u.bd.oc & 0x0001)==(OP_SeekLt & 0x0001) ) u.bd.oc++;
70131       }
70132     }
70133     rc = sqlite3BtreeMovetoUnpacked(u.bd.pC->pCursor, 0, (u64)u.bd.iKey, 0, &u.bd.res);
70134     if( rc!=SQLITE_OK ){
70135       goto abort_due_to_error;
70136     }
70137     if( u.bd.res==0 ){
70138       u.bd.pC->rowidIsValid = 1;
70139       u.bd.pC->lastRowid = u.bd.iKey;
70140     }
70141   }else{
70142     u.bd.nField = pOp->p4.i;
70143     assert( pOp->p4type==P4_INT32 );
70144     assert( u.bd.nField>0 );
70145     u.bd.r.pKeyInfo = u.bd.pC->pKeyInfo;
70146     u.bd.r.nField = (u16)u.bd.nField;
70147 
70148     /* The next line of code computes as follows, only faster:
70149     **   if( u.bd.oc==OP_SeekGt || u.bd.oc==OP_SeekLe ){
70150     **     u.bd.r.flags = UNPACKED_INCRKEY;
70151     **   }else{
70152     **     u.bd.r.flags = 0;
70153     **   }
70154     */
70155     u.bd.r.flags = (u8)(UNPACKED_INCRKEY * (1 & (u.bd.oc - OP_SeekLt)));
70156     assert( u.bd.oc!=OP_SeekGt || u.bd.r.flags==UNPACKED_INCRKEY );
70157     assert( u.bd.oc!=OP_SeekLe || u.bd.r.flags==UNPACKED_INCRKEY );
70158     assert( u.bd.oc!=OP_SeekGe || u.bd.r.flags==0 );
70159     assert( u.bd.oc!=OP_SeekLt || u.bd.r.flags==0 );
70160 
70161     u.bd.r.aMem = &aMem[pOp->p3];
70162 #ifdef SQLITE_DEBUG
70163     { int i; for(i=0; i<u.bd.r.nField; i++) assert( memIsValid(&u.bd.r.aMem[i]) ); }
70164 #endif
70165     ExpandBlob(u.bd.r.aMem);
70166     rc = sqlite3BtreeMovetoUnpacked(u.bd.pC->pCursor, &u.bd.r, 0, 0, &u.bd.res);
70167     if( rc!=SQLITE_OK ){
70168       goto abort_due_to_error;
70169     }
70170     u.bd.pC->rowidIsValid = 0;
70171   }
70172   u.bd.pC->deferredMoveto = 0;
70173   u.bd.pC->cacheStatus = CACHE_STALE;
70174 #ifdef SQLITE_TEST
70175   sqlite3_search_count++;
70176 #endif
70177   if( u.bd.oc>=OP_SeekGe ){  assert( u.bd.oc==OP_SeekGe || u.bd.oc==OP_SeekGt );
70178     if( u.bd.res<0 || (u.bd.res==0 && u.bd.oc==OP_SeekGt) ){
70179       rc = sqlite3BtreeNext(u.bd.pC->pCursor, &u.bd.res);
70180       if( rc!=SQLITE_OK ) goto abort_due_to_error;
70181       u.bd.pC->rowidIsValid = 0;
70182     }else{
70183       u.bd.res = 0;
70184     }
70185   }else{
70186     assert( u.bd.oc==OP_SeekLt || u.bd.oc==OP_SeekLe );
70187     if( u.bd.res>0 || (u.bd.res==0 && u.bd.oc==OP_SeekLt) ){
70188       rc = sqlite3BtreePrevious(u.bd.pC->pCursor, &u.bd.res);
70189       if( rc!=SQLITE_OK ) goto abort_due_to_error;
70190       u.bd.pC->rowidIsValid = 0;
70191     }else{
70192       /* u.bd.res might be negative because the table is empty.  Check to
70193       ** see if this is the case.
70194       */
70195       u.bd.res = sqlite3BtreeEof(u.bd.pC->pCursor);
70196     }
70197   }
70198   assert( pOp->p2>0 );
70199   if( u.bd.res ){
70200     pc = pOp->p2 - 1;
70201   }
70202   break;
70203 }
70204 
70205 /* Opcode: Seek P1 P2 * * *
70206 ** Synopsis:  intkey=r[P2]
70207 **
70208 ** P1 is an open table cursor and P2 is a rowid integer.  Arrange
70209 ** for P1 to move so that it points to the rowid given by P2.
70210 **
70211 ** This is actually a deferred seek.  Nothing actually happens until
70212 ** the cursor is used to read a record.  That way, if no reads
70213 ** occur, no unnecessary I/O happens.
70214 */
70215 case OP_Seek: {    /* in2 */
70216 #if 0  /* local variables moved into u.be */
70217   VdbeCursor *pC;
70218 #endif /* local variables moved into u.be */
70219 
70220   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70221   u.be.pC = p->apCsr[pOp->p1];
70222   assert( u.be.pC!=0 );
70223   assert( u.be.pC->pCursor!=0 );
70224   assert( u.be.pC->isTable );
70225   u.be.pC->nullRow = 0;
70226   pIn2 = &aMem[pOp->p2];
70227   u.be.pC->movetoTarget = sqlite3VdbeIntValue(pIn2);
70228   u.be.pC->rowidIsValid = 0;
70229   u.be.pC->deferredMoveto = 1;
70230   break;
70231 }
70232   
70233 
70234 /* Opcode: Found P1 P2 P3 P4 *
70235 ** Synopsis: key=r[P3@P4]
70236 **
70237 ** If P4==0 then register P3 holds a blob constructed by MakeRecord.  If
70238 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
70239 ** record.
70240 **
70241 ** Cursor P1 is on an index btree.  If the record identified by P3 and P4
70242 ** is a prefix of any entry in P1 then a jump is made to P2 and
70243 ** P1 is left pointing at the matching entry.
70244 **
70245 ** See also: NotFound, NoConflict, NotExists. SeekGe
70246 */
70247 /* Opcode: NotFound P1 P2 P3 P4 *
70248 ** Synopsis: key=r[P3@P4]
70249 **
70250 ** If P4==0 then register P3 holds a blob constructed by MakeRecord.  If
70251 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
70252 ** record.
70253 ** 
70254 ** Cursor P1 is on an index btree.  If the record identified by P3 and P4
70255 ** is not the prefix of any entry in P1 then a jump is made to P2.  If P1 
70256 ** does contain an entry whose prefix matches the P3/P4 record then control
70257 ** falls through to the next instruction and P1 is left pointing at the
70258 ** matching entry.
70259 **
70260 ** See also: Found, NotExists, NoConflict
70261 */
70262 /* Opcode: NoConflict P1 P2 P3 P4 *
70263 ** Synopsis: key=r[P3@P4]
70264 **
70265 ** If P4==0 then register P3 holds a blob constructed by MakeRecord.  If
70266 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
70267 ** record.
70268 ** 
70269 ** Cursor P1 is on an index btree.  If the record identified by P3 and P4
70270 ** contains any NULL value, jump immediately to P2.  If all terms of the
70271 ** record are not-NULL then a check is done to determine if any row in the
70272 ** P1 index btree has a matching key prefix.  If there are no matches, jump
70273 ** immediately to P2.  If there is a match, fall through and leave the P1
70274 ** cursor pointing to the matching row.
70275 **
70276 ** This opcode is similar to OP_NotFound with the exceptions that the
70277 ** branch is always taken if any part of the search key input is NULL.
70278 **
70279 ** See also: NotFound, Found, NotExists
70280 */
70281 case OP_NoConflict:     /* jump, in3 */
70282 case OP_NotFound:       /* jump, in3 */
70283 case OP_Found: {        /* jump, in3 */
70284 #if 0  /* local variables moved into u.bf */
70285   int alreadyExists;
70286   int ii;
70287   VdbeCursor *pC;
70288   int res;
70289   char *pFree;
70290   UnpackedRecord *pIdxKey;
70291   UnpackedRecord r;
70292   char aTempRec[ROUND8(sizeof(UnpackedRecord)) + sizeof(Mem)*4 + 7];
70293 #endif /* local variables moved into u.bf */
70294 
70295 #ifdef SQLITE_TEST
70296   if( pOp->opcode!=OP_NoConflict ) sqlite3_found_count++;
70297 #endif
70298 
70299   u.bf.alreadyExists = 0;
70300   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70301   assert( pOp->p4type==P4_INT32 );
70302   u.bf.pC = p->apCsr[pOp->p1];
70303   assert( u.bf.pC!=0 );
70304   pIn3 = &aMem[pOp->p3];
70305   assert( u.bf.pC->pCursor!=0 );
70306   assert( u.bf.pC->isTable==0 );
70307   if( pOp->p4.i>0 ){
70308     u.bf.r.pKeyInfo = u.bf.pC->pKeyInfo;
70309     u.bf.r.nField = (u16)pOp->p4.i;
70310     u.bf.r.aMem = pIn3;
70311 #ifdef SQLITE_DEBUG
70312     {
70313       int i;
70314       for(i=0; i<u.bf.r.nField; i++){
70315         assert( memIsValid(&u.bf.r.aMem[i]) );
70316         if( i ) REGISTER_TRACE(pOp->p3+i, &u.bf.r.aMem[i]);
70317       }
70318     }
70319 #endif
70320     u.bf.r.flags = UNPACKED_PREFIX_MATCH;
70321     u.bf.pIdxKey = &u.bf.r;
70322   }else{
70323     u.bf.pIdxKey = sqlite3VdbeAllocUnpackedRecord(
70324         u.bf.pC->pKeyInfo, u.bf.aTempRec, sizeof(u.bf.aTempRec), &u.bf.pFree
70325     );
70326     if( u.bf.pIdxKey==0 ) goto no_mem;
70327     assert( pIn3->flags & MEM_Blob );
70328     assert( (pIn3->flags & MEM_Zero)==0 );  /* zeroblobs already expanded */
70329     sqlite3VdbeRecordUnpack(u.bf.pC->pKeyInfo, pIn3->n, pIn3->z, u.bf.pIdxKey);
70330     u.bf.pIdxKey->flags |= UNPACKED_PREFIX_MATCH;
70331   }
70332   if( pOp->opcode==OP_NoConflict ){
70333     /* For the OP_NoConflict opcode, take the jump if any of the
70334     ** input fields are NULL, since any key with a NULL will not
70335     ** conflict */
70336     for(u.bf.ii=0; u.bf.ii<u.bf.r.nField; u.bf.ii++){
70337       if( u.bf.r.aMem[u.bf.ii].flags & MEM_Null ){
70338         pc = pOp->p2 - 1;
70339         break;
70340       }
70341     }
70342   }
70343   rc = sqlite3BtreeMovetoUnpacked(u.bf.pC->pCursor, u.bf.pIdxKey, 0, 0, &u.bf.res);
70344   if( pOp->p4.i==0 ){
70345     sqlite3DbFree(db, u.bf.pFree);
70346   }
70347   if( rc!=SQLITE_OK ){
70348     break;
70349   }
70350   u.bf.pC->seekResult = u.bf.res;
70351   u.bf.alreadyExists = (u.bf.res==0);
70352   u.bf.pC->nullRow = 1-u.bf.alreadyExists;
70353   u.bf.pC->deferredMoveto = 0;
70354   u.bf.pC->cacheStatus = CACHE_STALE;
70355   if( pOp->opcode==OP_Found ){
70356     if( u.bf.alreadyExists ) pc = pOp->p2 - 1;
70357   }else{
70358     if( !u.bf.alreadyExists ) pc = pOp->p2 - 1;
70359   }
70360   break;
70361 }
70362 
70363 /* Opcode: NotExists P1 P2 P3 * *
70364 ** Synopsis: intkey=r[P3]
70365 **
70366 ** P1 is the index of a cursor open on an SQL table btree (with integer
70367 ** keys).  P3 is an integer rowid.  If P1 does not contain a record with
70368 ** rowid P3 then jump immediately to P2.  If P1 does contain a record
70369 ** with rowid P3 then leave the cursor pointing at that record and fall
70370 ** through to the next instruction.
70371 **
70372 ** The OP_NotFound opcode performs the same operation on index btrees
70373 ** (with arbitrary multi-value keys).
70374 **
70375 ** See also: Found, NotFound, NoConflict
70376 */
70377 case OP_NotExists: {        /* jump, in3 */
70378 #if 0  /* local variables moved into u.bg */
70379   VdbeCursor *pC;
70380   BtCursor *pCrsr;
70381   int res;
70382   u64 iKey;
70383 #endif /* local variables moved into u.bg */
70384 
70385   pIn3 = &aMem[pOp->p3];
70386   assert( pIn3->flags & MEM_Int );
70387   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70388   u.bg.pC = p->apCsr[pOp->p1];
70389   assert( u.bg.pC!=0 );
70390   assert( u.bg.pC->isTable );
70391   assert( u.bg.pC->pseudoTableReg==0 );
70392   u.bg.pCrsr = u.bg.pC->pCursor;
70393   assert( u.bg.pCrsr!=0 );
70394   u.bg.res = 0;
70395   u.bg.iKey = pIn3->u.i;
70396   rc = sqlite3BtreeMovetoUnpacked(u.bg.pCrsr, 0, u.bg.iKey, 0, &u.bg.res);
70397   u.bg.pC->lastRowid = pIn3->u.i;
70398   u.bg.pC->rowidIsValid = u.bg.res==0 ?1:0;
70399   u.bg.pC->nullRow = 0;
70400   u.bg.pC->cacheStatus = CACHE_STALE;
70401   u.bg.pC->deferredMoveto = 0;
70402   if( u.bg.res!=0 ){
70403     pc = pOp->p2 - 1;
70404     assert( u.bg.pC->rowidIsValid==0 );
70405   }
70406   u.bg.pC->seekResult = u.bg.res;
70407   break;
70408 }
70409 
70410 /* Opcode: Sequence P1 P2 * * *
70411 ** Synopsis: r[P2]=rowid
70412 **
70413 ** Find the next available sequence number for cursor P1.
70414 ** Write the sequence number into register P2.
70415 ** The sequence number on the cursor is incremented after this
70416 ** instruction.  
70417 */
70418 case OP_Sequence: {           /* out2-prerelease */
70419   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70420   assert( p->apCsr[pOp->p1]!=0 );
70421   pOut->u.i = p->apCsr[pOp->p1]->seqCount++;
70422   break;
70423 }
70424 
70425 
70426 /* Opcode: NewRowid P1 P2 P3 * *
70427 ** Synopsis: r[P2]=rowid
70428 **
70429 ** Get a new integer record number (a.k.a "rowid") used as the key to a table.
70430 ** The record number is not previously used as a key in the database
70431 ** table that cursor P1 points to.  The new record number is written
70432 ** written to register P2.
70433 **
70434 ** If P3>0 then P3 is a register in the root frame of this VDBE that holds 
70435 ** the largest previously generated record number. No new record numbers are
70436 ** allowed to be less than this value. When this value reaches its maximum, 
70437 ** an SQLITE_FULL error is generated. The P3 register is updated with the '
70438 ** generated record number. This P3 mechanism is used to help implement the
70439 ** AUTOINCREMENT feature.
70440 */
70441 case OP_NewRowid: {           /* out2-prerelease */
70442 #if 0  /* local variables moved into u.bh */
70443   i64 v;                 /* The new rowid */
70444   VdbeCursor *pC;        /* Cursor of table to get the new rowid */
70445   int res;               /* Result of an sqlite3BtreeLast() */
70446   int cnt;               /* Counter to limit the number of searches */
70447   Mem *pMem;             /* Register holding largest rowid for AUTOINCREMENT */
70448   VdbeFrame *pFrame;     /* Root frame of VDBE */
70449 #endif /* local variables moved into u.bh */
70450 
70451   u.bh.v = 0;
70452   u.bh.res = 0;
70453   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70454   u.bh.pC = p->apCsr[pOp->p1];
70455   assert( u.bh.pC!=0 );
70456   if( NEVER(u.bh.pC->pCursor==0) ){
70457     /* The zero initialization above is all that is needed */
70458   }else{
70459     /* The next rowid or record number (different terms for the same
70460     ** thing) is obtained in a two-step algorithm.
70461     **
70462     ** First we attempt to find the largest existing rowid and add one
70463     ** to that.  But if the largest existing rowid is already the maximum
70464     ** positive integer, we have to fall through to the second
70465     ** probabilistic algorithm
70466     **
70467     ** The second algorithm is to select a rowid at random and see if
70468     ** it already exists in the table.  If it does not exist, we have
70469     ** succeeded.  If the random rowid does exist, we select a new one
70470     ** and try again, up to 100 times.
70471     */
70472     assert( u.bh.pC->isTable );
70473 
70474 #ifdef SQLITE_32BIT_ROWID
70475 #   define MAX_ROWID 0x7fffffff
70476 #else
70477     /* Some compilers complain about constants of the form 0x7fffffffffffffff.
70478     ** Others complain about 0x7ffffffffffffffffLL.  The following macro seems
70479     ** to provide the constant while making all compilers happy.
70480     */
70481 #   define MAX_ROWID  (i64)( (((u64)0x7fffffff)<<32) | (u64)0xffffffff )
70482 #endif
70483 
70484     if( !u.bh.pC->useRandomRowid ){
70485       u.bh.v = sqlite3BtreeGetCachedRowid(u.bh.pC->pCursor);
70486       if( u.bh.v==0 ){
70487         rc = sqlite3BtreeLast(u.bh.pC->pCursor, &u.bh.res);
70488         if( rc!=SQLITE_OK ){
70489           goto abort_due_to_error;
70490         }
70491         if( u.bh.res ){
70492           u.bh.v = 1;   /* IMP: R-61914-48074 */
70493         }else{
70494           assert( sqlite3BtreeCursorIsValid(u.bh.pC->pCursor) );
70495           rc = sqlite3BtreeKeySize(u.bh.pC->pCursor, &u.bh.v);
70496           assert( rc==SQLITE_OK );   /* Cannot fail following BtreeLast() */
70497           if( u.bh.v>=MAX_ROWID ){
70498             u.bh.pC->useRandomRowid = 1;
70499           }else{
70500             u.bh.v++;   /* IMP: R-29538-34987 */
70501           }
70502         }
70503       }
70504 
70505 #ifndef SQLITE_OMIT_AUTOINCREMENT
70506       if( pOp->p3 ){
70507         /* Assert that P3 is a valid memory cell. */
70508         assert( pOp->p3>0 );
70509         if( p->pFrame ){
70510           for(u.bh.pFrame=p->pFrame; u.bh.pFrame->pParent; u.bh.pFrame=u.bh.pFrame->pParent);
70511           /* Assert that P3 is a valid memory cell. */
70512           assert( pOp->p3<=u.bh.pFrame->nMem );
70513           u.bh.pMem = &u.bh.pFrame->aMem[pOp->p3];
70514         }else{
70515           /* Assert that P3 is a valid memory cell. */
70516           assert( pOp->p3<=(p->nMem-p->nCursor) );
70517           u.bh.pMem = &aMem[pOp->p3];
70518           memAboutToChange(p, u.bh.pMem);
70519         }
70520         assert( memIsValid(u.bh.pMem) );
70521 
70522         REGISTER_TRACE(pOp->p3, u.bh.pMem);
70523         sqlite3VdbeMemIntegerify(u.bh.pMem);
70524         assert( (u.bh.pMem->flags & MEM_Int)!=0 );  /* mem(P3) holds an integer */
70525         if( u.bh.pMem->u.i==MAX_ROWID || u.bh.pC->useRandomRowid ){
70526           rc = SQLITE_FULL;   /* IMP: R-12275-61338 */
70527           goto abort_due_to_error;
70528         }
70529         if( u.bh.v<u.bh.pMem->u.i+1 ){
70530           u.bh.v = u.bh.pMem->u.i + 1;
70531         }
70532         u.bh.pMem->u.i = u.bh.v;
70533       }
70534 #endif
70535 
70536       sqlite3BtreeSetCachedRowid(u.bh.pC->pCursor, u.bh.v<MAX_ROWID ? u.bh.v+1 : 0);
70537     }
70538     if( u.bh.pC->useRandomRowid ){
70539       /* IMPLEMENTATION-OF: R-07677-41881 If the largest ROWID is equal to the
70540       ** largest possible integer (9223372036854775807) then the database
70541       ** engine starts picking positive candidate ROWIDs at random until
70542       ** it finds one that is not previously used. */
70543       assert( pOp->p3==0 );  /* We cannot be in random rowid mode if this is
70544                              ** an AUTOINCREMENT table. */
70545       /* on the first attempt, simply do one more than previous */
70546       u.bh.v = lastRowid;
70547       u.bh.v &= (MAX_ROWID>>1); /* ensure doesn't go negative */
70548       u.bh.v++; /* ensure non-zero */
70549       u.bh.cnt = 0;
70550       while(   ((rc = sqlite3BtreeMovetoUnpacked(u.bh.pC->pCursor, 0, (u64)u.bh.v,
70551                                                  0, &u.bh.res))==SQLITE_OK)
70552             && (u.bh.res==0)
70553             && (++u.bh.cnt<100)){
70554         /* collision - try another random rowid */
70555         sqlite3_randomness(sizeof(u.bh.v), &u.bh.v);
70556         if( u.bh.cnt<5 ){
70557           /* try "small" random rowids for the initial attempts */
70558           u.bh.v &= 0xffffff;
70559         }else{
70560           u.bh.v &= (MAX_ROWID>>1); /* ensure doesn't go negative */
70561         }
70562         u.bh.v++; /* ensure non-zero */
70563       }
70564       if( rc==SQLITE_OK && u.bh.res==0 ){
70565         rc = SQLITE_FULL;   /* IMP: R-38219-53002 */
70566         goto abort_due_to_error;
70567       }
70568       assert( u.bh.v>0 );  /* EV: R-40812-03570 */
70569     }
70570     u.bh.pC->rowidIsValid = 0;
70571     u.bh.pC->deferredMoveto = 0;
70572     u.bh.pC->cacheStatus = CACHE_STALE;
70573   }
70574   pOut->u.i = u.bh.v;
70575   break;
70576 }
70577 
70578 /* Opcode: Insert P1 P2 P3 P4 P5
70579 ** Synopsis: intkey=r[P3] data=r[P2]
70580 **
70581 ** Write an entry into the table of cursor P1.  A new entry is
70582 ** created if it doesn't already exist or the data for an existing
70583 ** entry is overwritten.  The data is the value MEM_Blob stored in register
70584 ** number P2. The key is stored in register P3. The key must
70585 ** be a MEM_Int.
70586 **
70587 ** If the OPFLAG_NCHANGE flag of P5 is set, then the row change count is
70588 ** incremented (otherwise not).  If the OPFLAG_LASTROWID flag of P5 is set,
70589 ** then rowid is stored for subsequent return by the
70590 ** sqlite3_last_insert_rowid() function (otherwise it is unmodified).
70591 **
70592 ** If the OPFLAG_USESEEKRESULT flag of P5 is set and if the result of
70593 ** the last seek operation (OP_NotExists) was a success, then this
70594 ** operation will not attempt to find the appropriate row before doing
70595 ** the insert but will instead overwrite the row that the cursor is
70596 ** currently pointing to.  Presumably, the prior OP_NotExists opcode
70597 ** has already positioned the cursor correctly.  This is an optimization
70598 ** that boosts performance by avoiding redundant seeks.
70599 **
70600 ** If the OPFLAG_ISUPDATE flag is set, then this opcode is part of an
70601 ** UPDATE operation.  Otherwise (if the flag is clear) then this opcode
70602 ** is part of an INSERT operation.  The difference is only important to
70603 ** the update hook.
70604 **
70605 ** Parameter P4 may point to a string containing the table-name, or
70606 ** may be NULL. If it is not NULL, then the update-hook 
70607 ** (sqlite3.xUpdateCallback) is invoked following a successful insert.
70608 **
70609 ** (WARNING/TODO: If P1 is a pseudo-cursor and P2 is dynamically
70610 ** allocated, then ownership of P2 is transferred to the pseudo-cursor
70611 ** and register P2 becomes ephemeral.  If the cursor is changed, the
70612 ** value of register P2 will then change.  Make sure this does not
70613 ** cause any problems.)
70614 **
70615 ** This instruction only works on tables.  The equivalent instruction
70616 ** for indices is OP_IdxInsert.
70617 */
70618 /* Opcode: InsertInt P1 P2 P3 P4 P5
70619 ** Synopsis:  intkey=P3 data=r[P2]
70620 **
70621 ** This works exactly like OP_Insert except that the key is the
70622 ** integer value P3, not the value of the integer stored in register P3.
70623 */
70624 case OP_Insert: 
70625 case OP_InsertInt: {
70626 #if 0  /* local variables moved into u.bi */
70627   Mem *pData;       /* MEM cell holding data for the record to be inserted */
70628   Mem *pKey;        /* MEM cell holding key  for the record */
70629   i64 iKey;         /* The integer ROWID or key for the record to be inserted */
70630   VdbeCursor *pC;   /* Cursor to table into which insert is written */
70631   int nZero;        /* Number of zero-bytes to append */
70632   int seekResult;   /* Result of prior seek or 0 if no USESEEKRESULT flag */
70633   const char *zDb;  /* database name - used by the update hook */
70634   const char *zTbl; /* Table name - used by the opdate hook */
70635   int op;           /* Opcode for update hook: SQLITE_UPDATE or SQLITE_INSERT */
70636 #endif /* local variables moved into u.bi */
70637 
70638   u.bi.pData = &aMem[pOp->p2];
70639   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70640   assert( memIsValid(u.bi.pData) );
70641   u.bi.pC = p->apCsr[pOp->p1];
70642   assert( u.bi.pC!=0 );
70643   assert( u.bi.pC->pCursor!=0 );
70644   assert( u.bi.pC->pseudoTableReg==0 );
70645   assert( u.bi.pC->isTable );
70646   REGISTER_TRACE(pOp->p2, u.bi.pData);
70647 
70648   if( pOp->opcode==OP_Insert ){
70649     u.bi.pKey = &aMem[pOp->p3];
70650     assert( u.bi.pKey->flags & MEM_Int );
70651     assert( memIsValid(u.bi.pKey) );
70652     REGISTER_TRACE(pOp->p3, u.bi.pKey);
70653     u.bi.iKey = u.bi.pKey->u.i;
70654   }else{
70655     assert( pOp->opcode==OP_InsertInt );
70656     u.bi.iKey = pOp->p3;
70657   }
70658 
70659   if( pOp->p5 & OPFLAG_NCHANGE ) p->nChange++;
70660   if( pOp->p5 & OPFLAG_LASTROWID ) db->lastRowid = lastRowid = u.bi.iKey;
70661   if( u.bi.pData->flags & MEM_Null ){
70662     u.bi.pData->z = 0;
70663     u.bi.pData->n = 0;
70664   }else{
70665     assert( u.bi.pData->flags & (MEM_Blob|MEM_Str) );
70666   }
70667   u.bi.seekResult = ((pOp->p5 & OPFLAG_USESEEKRESULT) ? u.bi.pC->seekResult : 0);
70668   if( u.bi.pData->flags & MEM_Zero ){
70669     u.bi.nZero = u.bi.pData->u.nZero;
70670   }else{
70671     u.bi.nZero = 0;
70672   }
70673   sqlite3BtreeSetCachedRowid(u.bi.pC->pCursor, 0);
70674   rc = sqlite3BtreeInsert(u.bi.pC->pCursor, 0, u.bi.iKey,
70675                           u.bi.pData->z, u.bi.pData->n, u.bi.nZero,
70676                           (pOp->p5 & OPFLAG_APPEND)!=0, u.bi.seekResult
70677   );
70678   u.bi.pC->rowidIsValid = 0;
70679   u.bi.pC->deferredMoveto = 0;
70680   u.bi.pC->cacheStatus = CACHE_STALE;
70681 
70682   /* Invoke the update-hook if required. */
70683   if( rc==SQLITE_OK && db->xUpdateCallback && pOp->p4.z ){
70684     u.bi.zDb = db->aDb[u.bi.pC->iDb].zName;
70685     u.bi.zTbl = pOp->p4.z;
70686     u.bi.op = ((pOp->p5 & OPFLAG_ISUPDATE) ? SQLITE_UPDATE : SQLITE_INSERT);
70687     assert( u.bi.pC->isTable );
70688     db->xUpdateCallback(db->pUpdateArg, u.bi.op, u.bi.zDb, u.bi.zTbl, u.bi.iKey);
70689     assert( u.bi.pC->iDb>=0 );
70690   }
70691   break;
70692 }
70693 
70694 /* Opcode: Delete P1 P2 * P4 *
70695 **
70696 ** Delete the record at which the P1 cursor is currently pointing.
70697 **
70698 ** The cursor will be left pointing at either the next or the previous
70699 ** record in the table. If it is left pointing at the next record, then
70700 ** the next Next instruction will be a no-op.  Hence it is OK to delete
70701 ** a record from within an Next loop.
70702 **
70703 ** If the OPFLAG_NCHANGE flag of P2 is set, then the row change count is
70704 ** incremented (otherwise not).
70705 **
70706 ** P1 must not be pseudo-table.  It has to be a real table with
70707 ** multiple rows.
70708 **
70709 ** If P4 is not NULL, then it is the name of the table that P1 is
70710 ** pointing to.  The update hook will be invoked, if it exists.
70711 ** If P4 is not NULL then the P1 cursor must have been positioned
70712 ** using OP_NotFound prior to invoking this opcode.
70713 */
70714 case OP_Delete: {
70715 #if 0  /* local variables moved into u.bj */
70716   i64 iKey;
70717   VdbeCursor *pC;
70718 #endif /* local variables moved into u.bj */
70719 
70720   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70721   u.bj.pC = p->apCsr[pOp->p1];
70722   assert( u.bj.pC!=0 );
70723   assert( u.bj.pC->pCursor!=0 );  /* Only valid for real tables, no pseudotables */
70724   u.bj.iKey = u.bj.pC->lastRowid;      /* Only used for the update hook */
70725 
70726   /* The OP_Delete opcode always follows an OP_NotExists or OP_Last or
70727   ** OP_Column on the same table without any intervening operations that
70728   ** might move or invalidate the cursor.  Hence cursor u.bj.pC is always pointing
70729   ** to the row to be deleted and the sqlite3VdbeCursorMoveto() operation
70730   ** below is always a no-op and cannot fail.  We will run it anyhow, though,
70731   ** to guard against future changes to the code generator.
70732   **/
70733   assert( u.bj.pC->deferredMoveto==0 );
70734   rc = sqlite3VdbeCursorMoveto(u.bj.pC);
70735   if( NEVER(rc!=SQLITE_OK) ) goto abort_due_to_error;
70736 
70737   sqlite3BtreeSetCachedRowid(u.bj.pC->pCursor, 0);
70738   rc = sqlite3BtreeDelete(u.bj.pC->pCursor);
70739   u.bj.pC->cacheStatus = CACHE_STALE;
70740 
70741   /* Invoke the update-hook if required. */
70742   if( rc==SQLITE_OK && db->xUpdateCallback && pOp->p4.z && u.bj.pC->isTable ){
70743     db->xUpdateCallback(db->pUpdateArg, SQLITE_DELETE,
70744                         db->aDb[u.bj.pC->iDb].zName, pOp->p4.z, u.bj.iKey);
70745     assert( u.bj.pC->iDb>=0 );
70746   }
70747   if( pOp->p2 & OPFLAG_NCHANGE ) p->nChange++;
70748   break;
70749 }
70750 /* Opcode: ResetCount * * * * *
70751 **
70752 ** The value of the change counter is copied to the database handle
70753 ** change counter (returned by subsequent calls to sqlite3_changes()).
70754 ** Then the VMs internal change counter resets to 0.
70755 ** This is used by trigger programs.
70756 */
70757 case OP_ResetCount: {
70758   sqlite3VdbeSetChanges(db, p->nChange);
70759   p->nChange = 0;
70760   break;
70761 }
70762 
70763 /* Opcode: SorterCompare P1 P2 P3 P4
70764 ** Synopsis:  if key(P1)!=rtrim(r[P3],P4) goto P2
70765 **
70766 ** P1 is a sorter cursor. This instruction compares a prefix of the
70767 ** the record blob in register P3 against a prefix of the entry that 
70768 ** the sorter cursor currently points to.  The final P4 fields of both
70769 ** the P3 and sorter record are ignored.
70770 **
70771 ** If either P3 or the sorter contains a NULL in one of their significant
70772 ** fields (not counting the P4 fields at the end which are ignored) then
70773 ** the comparison is assumed to be equal.
70774 **
70775 ** Fall through to next instruction if the two records compare equal to
70776 ** each other.  Jump to P2 if they are different.
70777 */
70778 case OP_SorterCompare: {
70779 #if 0  /* local variables moved into u.bk */
70780   VdbeCursor *pC;
70781   int res;
70782   int nIgnore;
70783 #endif /* local variables moved into u.bk */
70784 
70785   u.bk.pC = p->apCsr[pOp->p1];
70786   assert( isSorter(u.bk.pC) );
70787   assert( pOp->p4type==P4_INT32 );
70788   pIn3 = &aMem[pOp->p3];
70789   u.bk.nIgnore = pOp->p4.i;
70790   rc = sqlite3VdbeSorterCompare(u.bk.pC, pIn3, u.bk.nIgnore, &u.bk.res);
70791   if( u.bk.res ){
70792     pc = pOp->p2-1;
70793   }
70794   break;
70795 };
70796 
70797 /* Opcode: SorterData P1 P2 * * *
70798 ** Synopsis: r[P2]=data
70799 **
70800 ** Write into register P2 the current sorter data for sorter cursor P1.
70801 */
70802 case OP_SorterData: {
70803 #if 0  /* local variables moved into u.bl */
70804   VdbeCursor *pC;
70805 #endif /* local variables moved into u.bl */
70806 
70807   pOut = &aMem[pOp->p2];
70808   u.bl.pC = p->apCsr[pOp->p1];
70809   assert( isSorter(u.bl.pC) );
70810   rc = sqlite3VdbeSorterRowkey(u.bl.pC, pOut);
70811   break;
70812 }
70813 
70814 /* Opcode: RowData P1 P2 * * *
70815 ** Synopsis: r[P2]=data
70816 **
70817 ** Write into register P2 the complete row data for cursor P1.
70818 ** There is no interpretation of the data.  
70819 ** It is just copied onto the P2 register exactly as 
70820 ** it is found in the database file.
70821 **
70822 ** If the P1 cursor must be pointing to a valid row (not a NULL row)
70823 ** of a real table, not a pseudo-table.
70824 */
70825 /* Opcode: RowKey P1 P2 * * *
70826 ** Synopsis: r[P2]=key
70827 **
70828 ** Write into register P2 the complete row key for cursor P1.
70829 ** There is no interpretation of the data.  
70830 ** The key is copied onto the P3 register exactly as 
70831 ** it is found in the database file.
70832 **
70833 ** If the P1 cursor must be pointing to a valid row (not a NULL row)
70834 ** of a real table, not a pseudo-table.
70835 */
70836 case OP_RowKey:
70837 case OP_RowData: {
70838 #if 0  /* local variables moved into u.bm */
70839   VdbeCursor *pC;
70840   BtCursor *pCrsr;
70841   u32 n;
70842   i64 n64;
70843 #endif /* local variables moved into u.bm */
70844 
70845   pOut = &aMem[pOp->p2];
70846   memAboutToChange(p, pOut);
70847 
70848   /* Note that RowKey and RowData are really exactly the same instruction */
70849   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70850   u.bm.pC = p->apCsr[pOp->p1];
70851   assert( isSorter(u.bm.pC)==0 );
70852   assert( u.bm.pC->isTable || pOp->opcode!=OP_RowData );
70853   assert( u.bm.pC->isTable==0 || pOp->opcode==OP_RowData );
70854   assert( u.bm.pC!=0 );
70855   assert( u.bm.pC->nullRow==0 );
70856   assert( u.bm.pC->pseudoTableReg==0 );
70857   assert( u.bm.pC->pCursor!=0 );
70858   u.bm.pCrsr = u.bm.pC->pCursor;
70859   assert( sqlite3BtreeCursorIsValid(u.bm.pCrsr) );
70860 
70861   /* The OP_RowKey and OP_RowData opcodes always follow OP_NotExists or
70862   ** OP_Rewind/Op_Next with no intervening instructions that might invalidate
70863   ** the cursor.  Hence the following sqlite3VdbeCursorMoveto() call is always
70864   ** a no-op and can never fail.  But we leave it in place as a safety.
70865   */
70866   assert( u.bm.pC->deferredMoveto==0 );
70867   rc = sqlite3VdbeCursorMoveto(u.bm.pC);
70868   if( NEVER(rc!=SQLITE_OK) ) goto abort_due_to_error;
70869 
70870   if( u.bm.pC->isTable==0 ){
70871     assert( !u.bm.pC->isTable );
70872     VVA_ONLY(rc =) sqlite3BtreeKeySize(u.bm.pCrsr, &u.bm.n64);
70873     assert( rc==SQLITE_OK );    /* True because of CursorMoveto() call above */
70874     if( u.bm.n64>db->aLimit[SQLITE_LIMIT_LENGTH] ){
70875       goto too_big;
70876     }
70877     u.bm.n = (u32)u.bm.n64;
70878   }else{
70879     VVA_ONLY(rc =) sqlite3BtreeDataSize(u.bm.pCrsr, &u.bm.n);
70880     assert( rc==SQLITE_OK );    /* DataSize() cannot fail */
70881     if( u.bm.n>(u32)db->aLimit[SQLITE_LIMIT_LENGTH] ){
70882       goto too_big;
70883     }
70884   }
70885   if( sqlite3VdbeMemGrow(pOut, u.bm.n, 0) ){
70886     goto no_mem;
70887   }
70888   pOut->n = u.bm.n;
70889   MemSetTypeFlag(pOut, MEM_Blob);
70890   if( u.bm.pC->isTable==0 ){
70891     rc = sqlite3BtreeKey(u.bm.pCrsr, 0, u.bm.n, pOut->z);
70892   }else{
70893     rc = sqlite3BtreeData(u.bm.pCrsr, 0, u.bm.n, pOut->z);
70894   }
70895   pOut->enc = SQLITE_UTF8;  /* In case the blob is ever cast to text */
70896   UPDATE_MAX_BLOBSIZE(pOut);
70897   REGISTER_TRACE(pOp->p2, pOut);
70898   break;
70899 }
70900 
70901 /* Opcode: Rowid P1 P2 * * *
70902 ** Synopsis: r[P2]=rowid
70903 **
70904 ** Store in register P2 an integer which is the key of the table entry that
70905 ** P1 is currently point to.
70906 **
70907 ** P1 can be either an ordinary table or a virtual table.  There used to
70908 ** be a separate OP_VRowid opcode for use with virtual tables, but this
70909 ** one opcode now works for both table types.
70910 */
70911 case OP_Rowid: {                 /* out2-prerelease */
70912 #if 0  /* local variables moved into u.bn */
70913   VdbeCursor *pC;
70914   i64 v;
70915   sqlite3_vtab *pVtab;
70916   const sqlite3_module *pModule;
70917 #endif /* local variables moved into u.bn */
70918 
70919   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70920   u.bn.pC = p->apCsr[pOp->p1];
70921   assert( u.bn.pC!=0 );
70922   assert( u.bn.pC->pseudoTableReg==0 || u.bn.pC->nullRow );
70923   if( u.bn.pC->nullRow ){
70924     pOut->flags = MEM_Null;
70925     break;
70926   }else if( u.bn.pC->deferredMoveto ){
70927     u.bn.v = u.bn.pC->movetoTarget;
70928 #ifndef SQLITE_OMIT_VIRTUALTABLE
70929   }else if( u.bn.pC->pVtabCursor ){
70930     u.bn.pVtab = u.bn.pC->pVtabCursor->pVtab;
70931     u.bn.pModule = u.bn.pVtab->pModule;
70932     assert( u.bn.pModule->xRowid );
70933     rc = u.bn.pModule->xRowid(u.bn.pC->pVtabCursor, &u.bn.v);
70934     sqlite3VtabImportErrmsg(p, u.bn.pVtab);
70935 #endif /* SQLITE_OMIT_VIRTUALTABLE */
70936   }else{
70937     assert( u.bn.pC->pCursor!=0 );
70938     rc = sqlite3VdbeCursorMoveto(u.bn.pC);
70939     if( rc ) goto abort_due_to_error;
70940     if( u.bn.pC->rowidIsValid ){
70941       u.bn.v = u.bn.pC->lastRowid;
70942     }else{
70943       rc = sqlite3BtreeKeySize(u.bn.pC->pCursor, &u.bn.v);
70944       assert( rc==SQLITE_OK );  /* Always so because of CursorMoveto() above */
70945     }
70946   }
70947   pOut->u.i = u.bn.v;
70948   break;
70949 }
70950 
70951 /* Opcode: NullRow P1 * * * *
70952 **
70953 ** Move the cursor P1 to a null row.  Any OP_Column operations
70954 ** that occur while the cursor is on the null row will always
70955 ** write a NULL.
70956 */
70957 case OP_NullRow: {
70958 #if 0  /* local variables moved into u.bo */
70959   VdbeCursor *pC;
70960 #endif /* local variables moved into u.bo */
70961 
70962   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70963   u.bo.pC = p->apCsr[pOp->p1];
70964   assert( u.bo.pC!=0 );
70965   u.bo.pC->nullRow = 1;
70966   u.bo.pC->rowidIsValid = 0;
70967   u.bo.pC->cacheStatus = CACHE_STALE;
70968   assert( u.bo.pC->pCursor || u.bo.pC->pVtabCursor );
70969   if( u.bo.pC->pCursor ){
70970     sqlite3BtreeClearCursor(u.bo.pC->pCursor);
70971   }
70972   break;
70973 }
70974 
70975 /* Opcode: Last P1 P2 * * *
70976 **
70977 ** The next use of the Rowid or Column or Next instruction for P1 
70978 ** will refer to the last entry in the database table or index.
70979 ** If the table or index is empty and P2>0, then jump immediately to P2.
70980 ** If P2 is 0 or if the table or index is not empty, fall through
70981 ** to the following instruction.
70982 */
70983 case OP_Last: {        /* jump */
70984 #if 0  /* local variables moved into u.bp */
70985   VdbeCursor *pC;
70986   BtCursor *pCrsr;
70987   int res;
70988 #endif /* local variables moved into u.bp */
70989 
70990   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70991   u.bp.pC = p->apCsr[pOp->p1];
70992   assert( u.bp.pC!=0 );
70993   u.bp.pCrsr = u.bp.pC->pCursor;
70994   u.bp.res = 0;
70995   assert( u.bp.pCrsr!=0 );
70996   rc = sqlite3BtreeLast(u.bp.pCrsr, &u.bp.res);
70997   u.bp.pC->nullRow = (u8)u.bp.res;
70998   u.bp.pC->deferredMoveto = 0;
70999   u.bp.pC->rowidIsValid = 0;
71000   u.bp.pC->cacheStatus = CACHE_STALE;
71001   if( pOp->p2>0 && u.bp.res ){
71002     pc = pOp->p2 - 1;
71003   }
71004   break;
71005 }
71006 
71007 
71008 /* Opcode: Sort P1 P2 * * *
71009 **
71010 ** This opcode does exactly the same thing as OP_Rewind except that
71011 ** it increments an undocumented global variable used for testing.
71012 **
71013 ** Sorting is accomplished by writing records into a sorting index,
71014 ** then rewinding that index and playing it back from beginning to
71015 ** end.  We use the OP_Sort opcode instead of OP_Rewind to do the
71016 ** rewinding so that the global variable will be incremented and
71017 ** regression tests can determine whether or not the optimizer is
71018 ** correctly optimizing out sorts.
71019 */
71020 case OP_SorterSort:    /* jump */
71021 case OP_Sort: {        /* jump */
71022 #ifdef SQLITE_TEST
71023   sqlite3_sort_count++;
71024   sqlite3_search_count--;
71025 #endif
71026   p->aCounter[SQLITE_STMTSTATUS_SORT]++;
71027   /* Fall through into OP_Rewind */
71028 }
71029 /* Opcode: Rewind P1 P2 * * *
71030 **
71031 ** The next use of the Rowid or Column or Next instruction for P1 
71032 ** will refer to the first entry in the database table or index.
71033 ** If the table or index is empty and P2>0, then jump immediately to P2.
71034 ** If P2 is 0 or if the table or index is not empty, fall through
71035 ** to the following instruction.
71036 */
71037 case OP_Rewind: {        /* jump */
71038 #if 0  /* local variables moved into u.bq */
71039   VdbeCursor *pC;
71040   BtCursor *pCrsr;
71041   int res;
71042 #endif /* local variables moved into u.bq */
71043 
71044   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71045   u.bq.pC = p->apCsr[pOp->p1];
71046   assert( u.bq.pC!=0 );
71047   assert( isSorter(u.bq.pC)==(pOp->opcode==OP_SorterSort) );
71048   u.bq.res = 1;
71049   if( isSorter(u.bq.pC) ){
71050     rc = sqlite3VdbeSorterRewind(db, u.bq.pC, &u.bq.res);
71051   }else{
71052     u.bq.pCrsr = u.bq.pC->pCursor;
71053     assert( u.bq.pCrsr );
71054     rc = sqlite3BtreeFirst(u.bq.pCrsr, &u.bq.res);
71055     u.bq.pC->deferredMoveto = 0;
71056     u.bq.pC->cacheStatus = CACHE_STALE;
71057     u.bq.pC->rowidIsValid = 0;
71058   }
71059   u.bq.pC->nullRow = (u8)u.bq.res;
71060   assert( pOp->p2>0 && pOp->p2<p->nOp );
71061   if( u.bq.res ){
71062     pc = pOp->p2 - 1;
71063   }
71064   break;
71065 }
71066 
71067 /* Opcode: Next P1 P2 * * P5
71068 **
71069 ** Advance cursor P1 so that it points to the next key/data pair in its
71070 ** table or index.  If there are no more key/value pairs then fall through
71071 ** to the following instruction.  But if the cursor advance was successful,
71072 ** jump immediately to P2.
71073 **
71074 ** The P1 cursor must be for a real table, not a pseudo-table.  P1 must have
71075 ** been opened prior to this opcode or the program will segfault.
71076 **
71077 ** P4 is always of type P4_ADVANCE. The function pointer points to
71078 ** sqlite3BtreeNext().
71079 **
71080 ** If P5 is positive and the jump is taken, then event counter
71081 ** number P5-1 in the prepared statement is incremented.
71082 **
71083 ** See also: Prev, NextIfOpen
71084 */
71085 /* Opcode: NextIfOpen P1 P2 * * P5
71086 **
71087 ** This opcode works just like OP_Next except that if cursor P1 is not
71088 ** open it behaves a no-op.
71089 */
71090 /* Opcode: Prev P1 P2 * * P5
71091 **
71092 ** Back up cursor P1 so that it points to the previous key/data pair in its
71093 ** table or index.  If there is no previous key/value pairs then fall through
71094 ** to the following instruction.  But if the cursor backup was successful,
71095 ** jump immediately to P2.
71096 **
71097 ** The P1 cursor must be for a real table, not a pseudo-table.  If P1 is
71098 ** not open then the behavior is undefined.
71099 **
71100 ** P4 is always of type P4_ADVANCE. The function pointer points to
71101 ** sqlite3BtreePrevious().
71102 **
71103 ** If P5 is positive and the jump is taken, then event counter
71104 ** number P5-1 in the prepared statement is incremented.
71105 */
71106 /* Opcode: PrevIfOpen P1 P2 * * P5
71107 **
71108 ** This opcode works just like OP_Prev except that if cursor P1 is not
71109 ** open it behaves a no-op.
71110 */
71111 case OP_SorterNext: {  /* jump */
71112 #if 0  /* local variables moved into u.br */
71113   VdbeCursor *pC;
71114   int res;
71115 #endif /* local variables moved into u.br */
71116 
71117   u.br.pC = p->apCsr[pOp->p1];
71118   assert( isSorter(u.br.pC) );
71119   rc = sqlite3VdbeSorterNext(db, u.br.pC, &u.br.res);
71120   goto next_tail;
71121 case OP_PrevIfOpen:    /* jump */
71122 case OP_NextIfOpen:    /* jump */
71123   if( p->apCsr[pOp->p1]==0 ) break;
71124   /* Fall through */
71125 case OP_Prev:          /* jump */
71126 case OP_Next:          /* jump */
71127   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71128   assert( pOp->p5<ArraySize(p->aCounter) );
71129   u.br.pC = p->apCsr[pOp->p1];
71130   assert( u.br.pC!=0 );
71131   assert( u.br.pC->deferredMoveto==0 );
71132   assert( u.br.pC->pCursor );
71133   assert( pOp->opcode!=OP_Next || pOp->p4.xAdvance==sqlite3BtreeNext );
71134   assert( pOp->opcode!=OP_Prev || pOp->p4.xAdvance==sqlite3BtreePrevious );
71135   assert( pOp->opcode!=OP_NextIfOpen || pOp->p4.xAdvance==sqlite3BtreeNext );
71136   assert( pOp->opcode!=OP_PrevIfOpen || pOp->p4.xAdvance==sqlite3BtreePrevious);
71137   rc = pOp->p4.xAdvance(u.br.pC->pCursor, &u.br.res);
71138 next_tail:
71139   u.br.pC->cacheStatus = CACHE_STALE;
71140   if( u.br.res==0 ){
71141     u.br.pC->nullRow = 0;
71142     pc = pOp->p2 - 1;
71143     p->aCounter[pOp->p5]++;
71144 #ifdef SQLITE_TEST
71145     sqlite3_search_count++;
71146 #endif
71147   }else{
71148     u.br.pC->nullRow = 1;
71149   }
71150   u.br.pC->rowidIsValid = 0;
71151   goto check_for_interrupt;
71152 }
71153 
71154 /* Opcode: IdxInsert P1 P2 P3 * P5
71155 ** Synopsis: key=r[P2]
71156 **
71157 ** Register P2 holds an SQL index key made using the
71158 ** MakeRecord instructions.  This opcode writes that key
71159 ** into the index P1.  Data for the entry is nil.
71160 **
71161 ** P3 is a flag that provides a hint to the b-tree layer that this
71162 ** insert is likely to be an append.
71163 **
71164 ** This instruction only works for indices.  The equivalent instruction
71165 ** for tables is OP_Insert.
71166 */
71167 case OP_SorterInsert:       /* in2 */
71168 case OP_IdxInsert: {        /* in2 */
71169 #if 0  /* local variables moved into u.bs */
71170   VdbeCursor *pC;
71171   BtCursor *pCrsr;
71172   int nKey;
71173   const char *zKey;
71174 #endif /* local variables moved into u.bs */
71175 
71176   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71177   u.bs.pC = p->apCsr[pOp->p1];
71178   assert( u.bs.pC!=0 );
71179   assert( isSorter(u.bs.pC)==(pOp->opcode==OP_SorterInsert) );
71180   pIn2 = &aMem[pOp->p2];
71181   assert( pIn2->flags & MEM_Blob );
71182   u.bs.pCrsr = u.bs.pC->pCursor;
71183   if( pOp->p5 & OPFLAG_NCHANGE ) p->nChange++;
71184   assert( u.bs.pCrsr!=0 );
71185   assert( u.bs.pC->isTable==0 );
71186   rc = ExpandBlob(pIn2);
71187   if( rc==SQLITE_OK ){
71188     if( isSorter(u.bs.pC) ){
71189       rc = sqlite3VdbeSorterWrite(db, u.bs.pC, pIn2);
71190     }else{
71191       u.bs.nKey = pIn2->n;
71192       u.bs.zKey = pIn2->z;
71193       rc = sqlite3BtreeInsert(u.bs.pCrsr, u.bs.zKey, u.bs.nKey, "", 0, 0, pOp->p3,
71194           ((pOp->p5 & OPFLAG_USESEEKRESULT) ? u.bs.pC->seekResult : 0)
71195           );
71196       assert( u.bs.pC->deferredMoveto==0 );
71197       u.bs.pC->cacheStatus = CACHE_STALE;
71198     }
71199   }
71200   break;
71201 }
71202 
71203 /* Opcode: IdxDelete P1 P2 P3 * *
71204 ** Synopsis: key=r[P2@P3]
71205 **
71206 ** The content of P3 registers starting at register P2 form
71207 ** an unpacked index key. This opcode removes that entry from the 
71208 ** index opened by cursor P1.
71209 */
71210 case OP_IdxDelete: {
71211 #if 0  /* local variables moved into u.bt */
71212   VdbeCursor *pC;
71213   BtCursor *pCrsr;
71214   int res;
71215   UnpackedRecord r;
71216 #endif /* local variables moved into u.bt */
71217 
71218   assert( pOp->p3>0 );
71219   assert( pOp->p2>0 && pOp->p2+pOp->p3<=(p->nMem-p->nCursor)+1 );
71220   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71221   u.bt.pC = p->apCsr[pOp->p1];
71222   assert( u.bt.pC!=0 );
71223   u.bt.pCrsr = u.bt.pC->pCursor;
71224   assert( u.bt.pCrsr!=0 );
71225   assert( pOp->p5==0 );
71226   u.bt.r.pKeyInfo = u.bt.pC->pKeyInfo;
71227   u.bt.r.nField = (u16)pOp->p3;
71228   u.bt.r.flags = UNPACKED_PREFIX_MATCH;
71229   u.bt.r.aMem = &aMem[pOp->p2];
71230 #ifdef SQLITE_DEBUG
71231   { int i; for(i=0; i<u.bt.r.nField; i++) assert( memIsValid(&u.bt.r.aMem[i]) ); }
71232 #endif
71233   rc = sqlite3BtreeMovetoUnpacked(u.bt.pCrsr, &u.bt.r, 0, 0, &u.bt.res);
71234   if( rc==SQLITE_OK && u.bt.res==0 ){
71235     rc = sqlite3BtreeDelete(u.bt.pCrsr);
71236   }
71237   assert( u.bt.pC->deferredMoveto==0 );
71238   u.bt.pC->cacheStatus = CACHE_STALE;
71239   break;
71240 }
71241 
71242 /* Opcode: IdxRowid P1 P2 * * *
71243 ** Synopsis: r[P2]=rowid
71244 **
71245 ** Write into register P2 an integer which is the last entry in the record at
71246 ** the end of the index key pointed to by cursor P1.  This integer should be
71247 ** the rowid of the table entry to which this index entry points.
71248 **
71249 ** See also: Rowid, MakeRecord.
71250 */
71251 case OP_IdxRowid: {              /* out2-prerelease */
71252 #if 0  /* local variables moved into u.bu */
71253   BtCursor *pCrsr;
71254   VdbeCursor *pC;
71255   i64 rowid;
71256 #endif /* local variables moved into u.bu */
71257 
71258   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71259   u.bu.pC = p->apCsr[pOp->p1];
71260   assert( u.bu.pC!=0 );
71261   u.bu.pCrsr = u.bu.pC->pCursor;
71262   assert( u.bu.pCrsr!=0 );
71263   pOut->flags = MEM_Null;
71264   rc = sqlite3VdbeCursorMoveto(u.bu.pC);
71265   if( NEVER(rc) ) goto abort_due_to_error;
71266   assert( u.bu.pC->deferredMoveto==0 );
71267   assert( u.bu.pC->isTable==0 );
71268   if( !u.bu.pC->nullRow ){
71269     rc = sqlite3VdbeIdxRowid(db, u.bu.pCrsr, &u.bu.rowid);
71270     if( rc!=SQLITE_OK ){
71271       goto abort_due_to_error;
71272     }
71273     pOut->u.i = u.bu.rowid;
71274     pOut->flags = MEM_Int;
71275   }
71276   break;
71277 }
71278 
71279 /* Opcode: IdxGE P1 P2 P3 P4 P5
71280 ** Synopsis: key=r[P3@P4]
71281 **
71282 ** The P4 register values beginning with P3 form an unpacked index 
71283 ** key that omits the ROWID.  Compare this key value against the index 
71284 ** that P1 is currently pointing to, ignoring the ROWID on the P1 index.
71285 **
71286 ** If the P1 index entry is greater than or equal to the key value
71287 ** then jump to P2.  Otherwise fall through to the next instruction.
71288 **
71289 ** If P5 is non-zero then the key value is increased by an epsilon 
71290 ** prior to the comparison.  This make the opcode work like IdxGT except
71291 ** that if the key from register P3 is a prefix of the key in the cursor,
71292 ** the result is false whereas it would be true with IdxGT.
71293 */
71294 /* Opcode: IdxLT P1 P2 P3 P4 P5
71295 ** Synopsis: key=r[P3@P4]
71296 **
71297 ** The P4 register values beginning with P3 form an unpacked index 
71298 ** key that omits the ROWID.  Compare this key value against the index 
71299 ** that P1 is currently pointing to, ignoring the ROWID on the P1 index.
71300 **
71301 ** If the P1 index entry is less than the key value then jump to P2.
71302 ** Otherwise fall through to the next instruction.
71303 **
71304 ** If P5 is non-zero then the key value is increased by an epsilon prior 
71305 ** to the comparison.  This makes the opcode work like IdxLE.
71306 */
71307 case OP_IdxLT:          /* jump */
71308 case OP_IdxGE: {        /* jump */
71309 #if 0  /* local variables moved into u.bv */
71310   VdbeCursor *pC;
71311   int res;
71312   UnpackedRecord r;
71313 #endif /* local variables moved into u.bv */
71314 
71315   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71316   u.bv.pC = p->apCsr[pOp->p1];
71317   assert( u.bv.pC!=0 );
71318   assert( u.bv.pC->isOrdered );
71319   assert( u.bv.pC->pCursor!=0);
71320   assert( u.bv.pC->deferredMoveto==0 );
71321   assert( pOp->p5==0 || pOp->p5==1 );
71322   assert( pOp->p4type==P4_INT32 );
71323   u.bv.r.pKeyInfo = u.bv.pC->pKeyInfo;
71324   u.bv.r.nField = (u16)pOp->p4.i;
71325   if( pOp->p5 ){
71326     u.bv.r.flags = UNPACKED_INCRKEY | UNPACKED_PREFIX_MATCH;
71327   }else{
71328     u.bv.r.flags = UNPACKED_PREFIX_MATCH;
71329   }
71330   u.bv.r.aMem = &aMem[pOp->p3];
71331 #ifdef SQLITE_DEBUG
71332   { int i; for(i=0; i<u.bv.r.nField; i++) assert( memIsValid(&u.bv.r.aMem[i]) ); }
71333 #endif
71334   rc = sqlite3VdbeIdxKeyCompare(u.bv.pC, &u.bv.r, &u.bv.res);
71335   if( pOp->opcode==OP_IdxLT ){
71336     u.bv.res = -u.bv.res;
71337   }else{
71338     assert( pOp->opcode==OP_IdxGE );
71339     u.bv.res++;
71340   }
71341   if( u.bv.res>0 ){
71342     pc = pOp->p2 - 1 ;
71343   }
71344   break;
71345 }
71346 
71347 /* Opcode: Destroy P1 P2 P3 * *
71348 **
71349 ** Delete an entire database table or index whose root page in the database
71350 ** file is given by P1.
71351 **
71352 ** The table being destroyed is in the main database file if P3==0.  If
71353 ** P3==1 then the table to be clear is in the auxiliary database file
71354 ** that is used to store tables create using CREATE TEMPORARY TABLE.
71355 **
71356 ** If AUTOVACUUM is enabled then it is possible that another root page
71357 ** might be moved into the newly deleted root page in order to keep all
71358 ** root pages contiguous at the beginning of the database.  The former
71359 ** value of the root page that moved - its value before the move occurred -
71360 ** is stored in register P2.  If no page 
71361 ** movement was required (because the table being dropped was already 
71362 ** the last one in the database) then a zero is stored in register P2.
71363 ** If AUTOVACUUM is disabled then a zero is stored in register P2.
71364 **
71365 ** See also: Clear
71366 */
71367 case OP_Destroy: {     /* out2-prerelease */
71368 #if 0  /* local variables moved into u.bw */
71369   int iMoved;
71370   int iCnt;
71371   Vdbe *pVdbe;
71372   int iDb;
71373 #endif /* local variables moved into u.bw */
71374 
71375   assert( p->readOnly==0 );
71376 #ifndef SQLITE_OMIT_VIRTUALTABLE
71377   u.bw.iCnt = 0;
71378   for(u.bw.pVdbe=db->pVdbe; u.bw.pVdbe; u.bw.pVdbe = u.bw.pVdbe->pNext){
71379     if( u.bw.pVdbe->magic==VDBE_MAGIC_RUN && u.bw.pVdbe->bIsReader
71380      && u.bw.pVdbe->inVtabMethod<2 && u.bw.pVdbe->pc>=0
71381     ){
71382       u.bw.iCnt++;
71383     }
71384   }
71385 #else
71386   u.bw.iCnt = db->nVdbeRead;
71387 #endif
71388   pOut->flags = MEM_Null;
71389   if( u.bw.iCnt>1 ){
71390     rc = SQLITE_LOCKED;
71391     p->errorAction = OE_Abort;
71392   }else{
71393     u.bw.iDb = pOp->p3;
71394     assert( u.bw.iCnt==1 );
71395     assert( (p->btreeMask & (((yDbMask)1)<<u.bw.iDb))!=0 );
71396     rc = sqlite3BtreeDropTable(db->aDb[u.bw.iDb].pBt, pOp->p1, &u.bw.iMoved);
71397     pOut->flags = MEM_Int;
71398     pOut->u.i = u.bw.iMoved;
71399 #ifndef SQLITE_OMIT_AUTOVACUUM
71400     if( rc==SQLITE_OK && u.bw.iMoved!=0 ){
71401       sqlite3RootPageMoved(db, u.bw.iDb, u.bw.iMoved, pOp->p1);
71402       /* All OP_Destroy operations occur on the same btree */
71403       assert( resetSchemaOnFault==0 || resetSchemaOnFault==u.bw.iDb+1 );
71404       resetSchemaOnFault = u.bw.iDb+1;
71405     }
71406 #endif
71407   }
71408   break;
71409 }
71410 
71411 /* Opcode: Clear P1 P2 P3
71412 **
71413 ** Delete all contents of the database table or index whose root page
71414 ** in the database file is given by P1.  But, unlike Destroy, do not
71415 ** remove the table or index from the database file.
71416 **
71417 ** The table being clear is in the main database file if P2==0.  If
71418 ** P2==1 then the table to be clear is in the auxiliary database file
71419 ** that is used to store tables create using CREATE TEMPORARY TABLE.
71420 **
71421 ** If the P3 value is non-zero, then the table referred to must be an
71422 ** intkey table (an SQL table, not an index). In this case the row change 
71423 ** count is incremented by the number of rows in the table being cleared. 
71424 ** If P3 is greater than zero, then the value stored in register P3 is
71425 ** also incremented by the number of rows in the table being cleared.
71426 **
71427 ** See also: Destroy
71428 */
71429 case OP_Clear: {
71430 #if 0  /* local variables moved into u.bx */
71431   int nChange;
71432 #endif /* local variables moved into u.bx */
71433 
71434   u.bx.nChange = 0;
71435   assert( p->readOnly==0 );
71436   assert( pOp->p1!=1 );
71437   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p2))!=0 );
71438   rc = sqlite3BtreeClearTable(
71439       db->aDb[pOp->p2].pBt, pOp->p1, (pOp->p3 ? &u.bx.nChange : 0)
71440   );
71441   if( pOp->p3 ){
71442     p->nChange += u.bx.nChange;
71443     if( pOp->p3>0 ){
71444       assert( memIsValid(&aMem[pOp->p3]) );
71445       memAboutToChange(p, &aMem[pOp->p3]);
71446       aMem[pOp->p3].u.i += u.bx.nChange;
71447     }
71448   }
71449   break;
71450 }
71451 
71452 /* Opcode: CreateTable P1 P2 * * *
71453 ** Synopsis: r[P2]=root iDb=P1
71454 **
71455 ** Allocate a new table in the main database file if P1==0 or in the
71456 ** auxiliary database file if P1==1 or in an attached database if
71457 ** P1>1.  Write the root page number of the new table into
71458 ** register P2
71459 **
71460 ** The difference between a table and an index is this:  A table must
71461 ** have a 4-byte integer key and can have arbitrary data.  An index
71462 ** has an arbitrary key but no data.
71463 **
71464 ** See also: CreateIndex
71465 */
71466 /* Opcode: CreateIndex P1 P2 * * *
71467 ** Synopsis: r[P2]=root iDb=P1
71468 **
71469 ** Allocate a new index in the main database file if P1==0 or in the
71470 ** auxiliary database file if P1==1 or in an attached database if
71471 ** P1>1.  Write the root page number of the new table into
71472 ** register P2.
71473 **
71474 ** See documentation on OP_CreateTable for additional information.
71475 */
71476 case OP_CreateIndex:            /* out2-prerelease */
71477 case OP_CreateTable: {          /* out2-prerelease */
71478 #if 0  /* local variables moved into u.by */
71479   int pgno;
71480   int flags;
71481   Db *pDb;
71482 #endif /* local variables moved into u.by */
71483 
71484   u.by.pgno = 0;
71485   assert( pOp->p1>=0 && pOp->p1<db->nDb );
71486   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p1))!=0 );
71487   assert( p->readOnly==0 );
71488   u.by.pDb = &db->aDb[pOp->p1];
71489   assert( u.by.pDb->pBt!=0 );
71490   if( pOp->opcode==OP_CreateTable ){
71491     /* u.by.flags = BTREE_INTKEY; */
71492     u.by.flags = BTREE_INTKEY;
71493   }else{
71494     u.by.flags = BTREE_BLOBKEY;
71495   }
71496   rc = sqlite3BtreeCreateTable(u.by.pDb->pBt, &u.by.pgno, u.by.flags);
71497   pOut->u.i = u.by.pgno;
71498   break;
71499 }
71500 
71501 /* Opcode: ParseSchema P1 * * P4 *
71502 **
71503 ** Read and parse all entries from the SQLITE_MASTER table of database P1
71504 ** that match the WHERE clause P4. 
71505 **
71506 ** This opcode invokes the parser to create a new virtual machine,
71507 ** then runs the new virtual machine.  It is thus a re-entrant opcode.
71508 */
71509 case OP_ParseSchema: {
71510 #if 0  /* local variables moved into u.bz */
71511   int iDb;
71512   const char *zMaster;
71513   char *zSql;
71514   InitData initData;
71515 #endif /* local variables moved into u.bz */
71516 
71517   /* Any prepared statement that invokes this opcode will hold mutexes
71518   ** on every btree.  This is a prerequisite for invoking
71519   ** sqlite3InitCallback().
71520   */
71521 #ifdef SQLITE_DEBUG
71522   for(u.bz.iDb=0; u.bz.iDb<db->nDb; u.bz.iDb++){
71523     assert( u.bz.iDb==1 || sqlite3BtreeHoldsMutex(db->aDb[u.bz.iDb].pBt) );
71524   }
71525 #endif
71526 
71527   u.bz.iDb = pOp->p1;
71528   assert( u.bz.iDb>=0 && u.bz.iDb<db->nDb );
71529   assert( DbHasProperty(db, u.bz.iDb, DB_SchemaLoaded) );
71530   /* Used to be a conditional */ {
71531     u.bz.zMaster = SCHEMA_TABLE(u.bz.iDb);
71532     u.bz.initData.db = db;
71533     u.bz.initData.iDb = pOp->p1;
71534     u.bz.initData.pzErrMsg = &p->zErrMsg;
71535     u.bz.zSql = sqlite3MPrintf(db,
71536        "SELECT name, rootpage, sql FROM '%q'.%s WHERE %s ORDER BY rowid",
71537        db->aDb[u.bz.iDb].zName, u.bz.zMaster, pOp->p4.z);
71538     if( u.bz.zSql==0 ){
71539       rc = SQLITE_NOMEM;
71540     }else{
71541       assert( db->init.busy==0 );
71542       db->init.busy = 1;
71543       u.bz.initData.rc = SQLITE_OK;
71544       assert( !db->mallocFailed );
71545       rc = sqlite3_exec(db, u.bz.zSql, sqlite3InitCallback, &u.bz.initData, 0);
71546       if( rc==SQLITE_OK ) rc = u.bz.initData.rc;
71547       sqlite3DbFree(db, u.bz.zSql);
71548       db->init.busy = 0;
71549     }
71550   }
71551   if( rc ) sqlite3ResetAllSchemasOfConnection(db);
71552   if( rc==SQLITE_NOMEM ){
71553     goto no_mem;
71554   }
71555   break;
71556 }
71557 
71558 #if !defined(SQLITE_OMIT_ANALYZE)
71559 /* Opcode: LoadAnalysis P1 * * * *
71560 **
71561 ** Read the sqlite_stat1 table for database P1 and load the content
71562 ** of that table into the internal index hash table.  This will cause
71563 ** the analysis to be used when preparing all subsequent queries.
71564 */
71565 case OP_LoadAnalysis: {
71566   assert( pOp->p1>=0 && pOp->p1<db->nDb );
71567   rc = sqlite3AnalysisLoad(db, pOp->p1);
71568   break;  
71569 }
71570 #endif /* !defined(SQLITE_OMIT_ANALYZE) */
71571 
71572 /* Opcode: DropTable P1 * * P4 *
71573 **
71574 ** Remove the internal (in-memory) data structures that describe
71575 ** the table named P4 in database P1.  This is called after a table
71576 ** is dropped in order to keep the internal representation of the
71577 ** schema consistent with what is on disk.
71578 */
71579 case OP_DropTable: {
71580   sqlite3UnlinkAndDeleteTable(db, pOp->p1, pOp->p4.z);
71581   break;
71582 }
71583 
71584 /* Opcode: DropIndex P1 * * P4 *
71585 **
71586 ** Remove the internal (in-memory) data structures that describe
71587 ** the index named P4 in database P1.  This is called after an index
71588 ** is dropped in order to keep the internal representation of the
71589 ** schema consistent with what is on disk.
71590 */
71591 case OP_DropIndex: {
71592   sqlite3UnlinkAndDeleteIndex(db, pOp->p1, pOp->p4.z);
71593   break;
71594 }
71595 
71596 /* Opcode: DropTrigger P1 * * P4 *
71597 **
71598 ** Remove the internal (in-memory) data structures that describe
71599 ** the trigger named P4 in database P1.  This is called after a trigger
71600 ** is dropped in order to keep the internal representation of the
71601 ** schema consistent with what is on disk.
71602 */
71603 case OP_DropTrigger: {
71604   sqlite3UnlinkAndDeleteTrigger(db, pOp->p1, pOp->p4.z);
71605   break;
71606 }
71607 
71608 
71609 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
71610 /* Opcode: IntegrityCk P1 P2 P3 * P5
71611 **
71612 ** Do an analysis of the currently open database.  Store in
71613 ** register P1 the text of an error message describing any problems.
71614 ** If no problems are found, store a NULL in register P1.
71615 **
71616 ** The register P3 contains the maximum number of allowed errors.
71617 ** At most reg(P3) errors will be reported.
71618 ** In other words, the analysis stops as soon as reg(P1) errors are 
71619 ** seen.  Reg(P1) is updated with the number of errors remaining.
71620 **
71621 ** The root page numbers of all tables in the database are integer
71622 ** stored in reg(P1), reg(P1+1), reg(P1+2), ....  There are P2 tables
71623 ** total.
71624 **
71625 ** If P5 is not zero, the check is done on the auxiliary database
71626 ** file, not the main database file.
71627 **
71628 ** This opcode is used to implement the integrity_check pragma.
71629 */
71630 case OP_IntegrityCk: {
71631 #if 0  /* local variables moved into u.ca */
71632   int nRoot;      /* Number of tables to check.  (Number of root pages.) */
71633   int *aRoot;     /* Array of rootpage numbers for tables to be checked */
71634   int j;          /* Loop counter */
71635   int nErr;       /* Number of errors reported */
71636   char *z;        /* Text of the error report */
71637   Mem *pnErr;     /* Register keeping track of errors remaining */
71638 #endif /* local variables moved into u.ca */
71639 
71640   assert( p->bIsReader );
71641   u.ca.nRoot = pOp->p2;
71642   assert( u.ca.nRoot>0 );
71643   u.ca.aRoot = sqlite3DbMallocRaw(db, sizeof(int)*(u.ca.nRoot+1) );
71644   if( u.ca.aRoot==0 ) goto no_mem;
71645   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
71646   u.ca.pnErr = &aMem[pOp->p3];
71647   assert( (u.ca.pnErr->flags & MEM_Int)!=0 );
71648   assert( (u.ca.pnErr->flags & (MEM_Str|MEM_Blob))==0 );
71649   pIn1 = &aMem[pOp->p1];
71650   for(u.ca.j=0; u.ca.j<u.ca.nRoot; u.ca.j++){
71651     u.ca.aRoot[u.ca.j] = (int)sqlite3VdbeIntValue(&pIn1[u.ca.j]);
71652   }
71653   u.ca.aRoot[u.ca.j] = 0;
71654   assert( pOp->p5<db->nDb );
71655   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p5))!=0 );
71656   u.ca.z = sqlite3BtreeIntegrityCheck(db->aDb[pOp->p5].pBt, u.ca.aRoot, u.ca.nRoot,
71657                                  (int)u.ca.pnErr->u.i, &u.ca.nErr);
71658   sqlite3DbFree(db, u.ca.aRoot);
71659   u.ca.pnErr->u.i -= u.ca.nErr;
71660   sqlite3VdbeMemSetNull(pIn1);
71661   if( u.ca.nErr==0 ){
71662     assert( u.ca.z==0 );
71663   }else if( u.ca.z==0 ){
71664     goto no_mem;
71665   }else{
71666     sqlite3VdbeMemSetStr(pIn1, u.ca.z, -1, SQLITE_UTF8, sqlite3_free);
71667   }
71668   UPDATE_MAX_BLOBSIZE(pIn1);
71669   sqlite3VdbeChangeEncoding(pIn1, encoding);
71670   break;
71671 }
71672 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
71673 
71674 /* Opcode: RowSetAdd P1 P2 * * *
71675 ** Synopsis:  rowset(P1)=r[P2]
71676 **
71677 ** Insert the integer value held by register P2 into a boolean index
71678 ** held in register P1.
71679 **
71680 ** An assertion fails if P2 is not an integer.
71681 */
71682 case OP_RowSetAdd: {       /* in1, in2 */
71683   pIn1 = &aMem[pOp->p1];
71684   pIn2 = &aMem[pOp->p2];
71685   assert( (pIn2->flags & MEM_Int)!=0 );
71686   if( (pIn1->flags & MEM_RowSet)==0 ){
71687     sqlite3VdbeMemSetRowSet(pIn1);
71688     if( (pIn1->flags & MEM_RowSet)==0 ) goto no_mem;
71689   }
71690   sqlite3RowSetInsert(pIn1->u.pRowSet, pIn2->u.i);
71691   break;
71692 }
71693 
71694 /* Opcode: RowSetRead P1 P2 P3 * *
71695 ** Synopsis:  r[P3]=rowset(P1)
71696 **
71697 ** Extract the smallest value from boolean index P1 and put that value into
71698 ** register P3.  Or, if boolean index P1 is initially empty, leave P3
71699 ** unchanged and jump to instruction P2.
71700 */
71701 case OP_RowSetRead: {       /* jump, in1, out3 */
71702 #if 0  /* local variables moved into u.cb */
71703   i64 val;
71704 #endif /* local variables moved into u.cb */
71705 
71706   pIn1 = &aMem[pOp->p1];
71707   if( (pIn1->flags & MEM_RowSet)==0
71708    || sqlite3RowSetNext(pIn1->u.pRowSet, &u.cb.val)==0
71709   ){
71710     /* The boolean index is empty */
71711     sqlite3VdbeMemSetNull(pIn1);
71712     pc = pOp->p2 - 1;
71713   }else{
71714     /* A value was pulled from the index */
71715     sqlite3VdbeMemSetInt64(&aMem[pOp->p3], u.cb.val);
71716   }
71717   goto check_for_interrupt;
71718 }
71719 
71720 /* Opcode: RowSetTest P1 P2 P3 P4
71721 ** Synopsis: if r[P3] in rowset(P1) goto P2
71722 **
71723 ** Register P3 is assumed to hold a 64-bit integer value. If register P1
71724 ** contains a RowSet object and that RowSet object contains
71725 ** the value held in P3, jump to register P2. Otherwise, insert the
71726 ** integer in P3 into the RowSet and continue on to the
71727 ** next opcode.
71728 **
71729 ** The RowSet object is optimized for the case where successive sets
71730 ** of integers, where each set contains no duplicates. Each set
71731 ** of values is identified by a unique P4 value. The first set
71732 ** must have P4==0, the final set P4=-1.  P4 must be either -1 or
71733 ** non-negative.  For non-negative values of P4 only the lower 4
71734 ** bits are significant.
71735 **
71736 ** This allows optimizations: (a) when P4==0 there is no need to test
71737 ** the rowset object for P3, as it is guaranteed not to contain it,
71738 ** (b) when P4==-1 there is no need to insert the value, as it will
71739 ** never be tested for, and (c) when a value that is part of set X is
71740 ** inserted, there is no need to search to see if the same value was
71741 ** previously inserted as part of set X (only if it was previously
71742 ** inserted as part of some other set).
71743 */
71744 case OP_RowSetTest: {                     /* jump, in1, in3 */
71745 #if 0  /* local variables moved into u.cc */
71746   int iSet;
71747   int exists;
71748 #endif /* local variables moved into u.cc */
71749 
71750   pIn1 = &aMem[pOp->p1];
71751   pIn3 = &aMem[pOp->p3];
71752   u.cc.iSet = pOp->p4.i;
71753   assert( pIn3->flags&MEM_Int );
71754 
71755   /* If there is anything other than a rowset object in memory cell P1,
71756   ** delete it now and initialize P1 with an empty rowset
71757   */
71758   if( (pIn1->flags & MEM_RowSet)==0 ){
71759     sqlite3VdbeMemSetRowSet(pIn1);
71760     if( (pIn1->flags & MEM_RowSet)==0 ) goto no_mem;
71761   }
71762 
71763   assert( pOp->p4type==P4_INT32 );
71764   assert( u.cc.iSet==-1 || u.cc.iSet>=0 );
71765   if( u.cc.iSet ){
71766     u.cc.exists = sqlite3RowSetTest(pIn1->u.pRowSet,
71767                                (u8)(u.cc.iSet>=0 ? u.cc.iSet & 0xf : 0xff),
71768                                pIn3->u.i);
71769     if( u.cc.exists ){
71770       pc = pOp->p2 - 1;
71771       break;
71772     }
71773   }
71774   if( u.cc.iSet>=0 ){
71775     sqlite3RowSetInsert(pIn1->u.pRowSet, pIn3->u.i);
71776   }
71777   break;
71778 }
71779 
71780 
71781 #ifndef SQLITE_OMIT_TRIGGER
71782 
71783 /* Opcode: Program P1 P2 P3 P4 *
71784 **
71785 ** Execute the trigger program passed as P4 (type P4_SUBPROGRAM). 
71786 **
71787 ** P1 contains the address of the memory cell that contains the first memory 
71788 ** cell in an array of values used as arguments to the sub-program. P2 
71789 ** contains the address to jump to if the sub-program throws an IGNORE 
71790 ** exception using the RAISE() function. Register P3 contains the address 
71791 ** of a memory cell in this (the parent) VM that is used to allocate the 
71792 ** memory required by the sub-vdbe at runtime.
71793 **
71794 ** P4 is a pointer to the VM containing the trigger program.
71795 */
71796 case OP_Program: {        /* jump */
71797 #if 0  /* local variables moved into u.cd */
71798   int nMem;               /* Number of memory registers for sub-program */
71799   int nByte;              /* Bytes of runtime space required for sub-program */
71800   Mem *pRt;               /* Register to allocate runtime space */
71801   Mem *pMem;              /* Used to iterate through memory cells */
71802   Mem *pEnd;              /* Last memory cell in new array */
71803   VdbeFrame *pFrame;      /* New vdbe frame to execute in */
71804   SubProgram *pProgram;   /* Sub-program to execute */
71805   void *t;                /* Token identifying trigger */
71806 #endif /* local variables moved into u.cd */
71807 
71808   u.cd.pProgram = pOp->p4.pProgram;
71809   u.cd.pRt = &aMem[pOp->p3];
71810   assert( u.cd.pProgram->nOp>0 );
71811 
71812   /* If the p5 flag is clear, then recursive invocation of triggers is
71813   ** disabled for backwards compatibility (p5 is set if this sub-program
71814   ** is really a trigger, not a foreign key action, and the flag set
71815   ** and cleared by the "PRAGMA recursive_triggers" command is clear).
71816   **
71817   ** It is recursive invocation of triggers, at the SQL level, that is
71818   ** disabled. In some cases a single trigger may generate more than one
71819   ** SubProgram (if the trigger may be executed with more than one different
71820   ** ON CONFLICT algorithm). SubProgram structures associated with a
71821   ** single trigger all have the same value for the SubProgram.token
71822   ** variable.  */
71823   if( pOp->p5 ){
71824     u.cd.t = u.cd.pProgram->token;
71825     for(u.cd.pFrame=p->pFrame; u.cd.pFrame && u.cd.pFrame->token!=u.cd.t; u.cd.pFrame=u.cd.pFrame->pParent);
71826     if( u.cd.pFrame ) break;
71827   }
71828 
71829   if( p->nFrame>=db->aLimit[SQLITE_LIMIT_TRIGGER_DEPTH] ){
71830     rc = SQLITE_ERROR;
71831     sqlite3SetString(&p->zErrMsg, db, "too many levels of trigger recursion");
71832     break;
71833   }
71834 
71835   /* Register u.cd.pRt is used to store the memory required to save the state
71836   ** of the current program, and the memory required at runtime to execute
71837   ** the trigger program. If this trigger has been fired before, then u.cd.pRt
71838   ** is already allocated. Otherwise, it must be initialized.  */
71839   if( (u.cd.pRt->flags&MEM_Frame)==0 ){
71840     /* SubProgram.nMem is set to the number of memory cells used by the
71841     ** program stored in SubProgram.aOp. As well as these, one memory
71842     ** cell is required for each cursor used by the program. Set local
71843     ** variable u.cd.nMem (and later, VdbeFrame.nChildMem) to this value.
71844     */
71845     u.cd.nMem = u.cd.pProgram->nMem + u.cd.pProgram->nCsr;
71846     u.cd.nByte = ROUND8(sizeof(VdbeFrame))
71847               + u.cd.nMem * sizeof(Mem)
71848               + u.cd.pProgram->nCsr * sizeof(VdbeCursor *)
71849               + u.cd.pProgram->nOnce * sizeof(u8);
71850     u.cd.pFrame = sqlite3DbMallocZero(db, u.cd.nByte);
71851     if( !u.cd.pFrame ){
71852       goto no_mem;
71853     }
71854     sqlite3VdbeMemRelease(u.cd.pRt);
71855     u.cd.pRt->flags = MEM_Frame;
71856     u.cd.pRt->u.pFrame = u.cd.pFrame;
71857 
71858     u.cd.pFrame->v = p;
71859     u.cd.pFrame->nChildMem = u.cd.nMem;
71860     u.cd.pFrame->nChildCsr = u.cd.pProgram->nCsr;
71861     u.cd.pFrame->pc = pc;
71862     u.cd.pFrame->aMem = p->aMem;
71863     u.cd.pFrame->nMem = p->nMem;
71864     u.cd.pFrame->apCsr = p->apCsr;
71865     u.cd.pFrame->nCursor = p->nCursor;
71866     u.cd.pFrame->aOp = p->aOp;
71867     u.cd.pFrame->nOp = p->nOp;
71868     u.cd.pFrame->token = u.cd.pProgram->token;
71869     u.cd.pFrame->aOnceFlag = p->aOnceFlag;
71870     u.cd.pFrame->nOnceFlag = p->nOnceFlag;
71871 
71872     u.cd.pEnd = &VdbeFrameMem(u.cd.pFrame)[u.cd.pFrame->nChildMem];
71873     for(u.cd.pMem=VdbeFrameMem(u.cd.pFrame); u.cd.pMem!=u.cd.pEnd; u.cd.pMem++){
71874       u.cd.pMem->flags = MEM_Invalid;
71875       u.cd.pMem->db = db;
71876     }
71877   }else{
71878     u.cd.pFrame = u.cd.pRt->u.pFrame;
71879     assert( u.cd.pProgram->nMem+u.cd.pProgram->nCsr==u.cd.pFrame->nChildMem );
71880     assert( u.cd.pProgram->nCsr==u.cd.pFrame->nChildCsr );
71881     assert( pc==u.cd.pFrame->pc );
71882   }
71883 
71884   p->nFrame++;
71885   u.cd.pFrame->pParent = p->pFrame;
71886   u.cd.pFrame->lastRowid = lastRowid;
71887   u.cd.pFrame->nChange = p->nChange;
71888   p->nChange = 0;
71889   p->pFrame = u.cd.pFrame;
71890   p->aMem = aMem = &VdbeFrameMem(u.cd.pFrame)[-1];
71891   p->nMem = u.cd.pFrame->nChildMem;
71892   p->nCursor = (u16)u.cd.pFrame->nChildCsr;
71893   p->apCsr = (VdbeCursor **)&aMem[p->nMem+1];
71894   p->aOp = aOp = u.cd.pProgram->aOp;
71895   p->nOp = u.cd.pProgram->nOp;
71896   p->aOnceFlag = (u8 *)&p->apCsr[p->nCursor];
71897   p->nOnceFlag = u.cd.pProgram->nOnce;
71898   pc = -1;
71899   memset(p->aOnceFlag, 0, p->nOnceFlag);
71900 
71901   break;
71902 }
71903 
71904 /* Opcode: Param P1 P2 * * *
71905 **
71906 ** This opcode is only ever present in sub-programs called via the 
71907 ** OP_Program instruction. Copy a value currently stored in a memory 
71908 ** cell of the calling (parent) frame to cell P2 in the current frames 
71909 ** address space. This is used by trigger programs to access the new.* 
71910 ** and old.* values.
71911 **
71912 ** The address of the cell in the parent frame is determined by adding
71913 ** the value of the P1 argument to the value of the P1 argument to the
71914 ** calling OP_Program instruction.
71915 */
71916 case OP_Param: {           /* out2-prerelease */
71917 #if 0  /* local variables moved into u.ce */
71918   VdbeFrame *pFrame;
71919   Mem *pIn;
71920 #endif /* local variables moved into u.ce */
71921   u.ce.pFrame = p->pFrame;
71922   u.ce.pIn = &u.ce.pFrame->aMem[pOp->p1 + u.ce.pFrame->aOp[u.ce.pFrame->pc].p1];
71923   sqlite3VdbeMemShallowCopy(pOut, u.ce.pIn, MEM_Ephem);
71924   break;
71925 }
71926 
71927 #endif /* #ifndef SQLITE_OMIT_TRIGGER */
71928 
71929 #ifndef SQLITE_OMIT_FOREIGN_KEY
71930 /* Opcode: FkCounter P1 P2 * * *
71931 ** Synopsis: fkctr[P1]+=P2
71932 **
71933 ** Increment a "constraint counter" by P2 (P2 may be negative or positive).
71934 ** If P1 is non-zero, the database constraint counter is incremented 
71935 ** (deferred foreign key constraints). Otherwise, if P1 is zero, the 
71936 ** statement counter is incremented (immediate foreign key constraints).
71937 */
71938 case OP_FkCounter: {
71939   if( db->flags & SQLITE_DeferFKs ){
71940     db->nDeferredImmCons += pOp->p2;
71941   }else if( pOp->p1 ){
71942     db->nDeferredCons += pOp->p2;
71943   }else{
71944     p->nFkConstraint += pOp->p2;
71945   }
71946   break;
71947 }
71948 
71949 /* Opcode: FkIfZero P1 P2 * * *
71950 ** Synopsis: if fkctr[P1]==0 goto P2
71951 **
71952 ** This opcode tests if a foreign key constraint-counter is currently zero.
71953 ** If so, jump to instruction P2. Otherwise, fall through to the next 
71954 ** instruction.
71955 **
71956 ** If P1 is non-zero, then the jump is taken if the database constraint-counter
71957 ** is zero (the one that counts deferred constraint violations). If P1 is
71958 ** zero, the jump is taken if the statement constraint-counter is zero
71959 ** (immediate foreign key constraint violations).
71960 */
71961 case OP_FkIfZero: {         /* jump */
71962   if( pOp->p1 ){
71963     if( db->nDeferredCons==0 && db->nDeferredImmCons==0 ) pc = pOp->p2-1;
71964   }else{
71965     if( p->nFkConstraint==0 && db->nDeferredImmCons==0 ) pc = pOp->p2-1;
71966   }
71967   break;
71968 }
71969 #endif /* #ifndef SQLITE_OMIT_FOREIGN_KEY */
71970 
71971 #ifndef SQLITE_OMIT_AUTOINCREMENT
71972 /* Opcode: MemMax P1 P2 * * *
71973 ** Synopsis: r[P1]=max(r[P1],r[P2])
71974 **
71975 ** P1 is a register in the root frame of this VM (the root frame is
71976 ** different from the current frame if this instruction is being executed
71977 ** within a sub-program). Set the value of register P1 to the maximum of 
71978 ** its current value and the value in register P2.
71979 **
71980 ** This instruction throws an error if the memory cell is not initially
71981 ** an integer.
71982 */
71983 case OP_MemMax: {        /* in2 */
71984 #if 0  /* local variables moved into u.cf */
71985   Mem *pIn1;
71986   VdbeFrame *pFrame;
71987 #endif /* local variables moved into u.cf */
71988   if( p->pFrame ){
71989     for(u.cf.pFrame=p->pFrame; u.cf.pFrame->pParent; u.cf.pFrame=u.cf.pFrame->pParent);
71990     u.cf.pIn1 = &u.cf.pFrame->aMem[pOp->p1];
71991   }else{
71992     u.cf.pIn1 = &aMem[pOp->p1];
71993   }
71994   assert( memIsValid(u.cf.pIn1) );
71995   sqlite3VdbeMemIntegerify(u.cf.pIn1);
71996   pIn2 = &aMem[pOp->p2];
71997   sqlite3VdbeMemIntegerify(pIn2);
71998   if( u.cf.pIn1->u.i<pIn2->u.i){
71999     u.cf.pIn1->u.i = pIn2->u.i;
72000   }
72001   break;
72002 }
72003 #endif /* SQLITE_OMIT_AUTOINCREMENT */
72004 
72005 /* Opcode: IfPos P1 P2 * * *
72006 ** Synopsis: if r[P1]>0 goto P2
72007 **
72008 ** If the value of register P1 is 1 or greater, jump to P2.
72009 **
72010 ** It is illegal to use this instruction on a register that does
72011 ** not contain an integer.  An assertion fault will result if you try.
72012 */
72013 case OP_IfPos: {        /* jump, in1 */
72014   pIn1 = &aMem[pOp->p1];
72015   assert( pIn1->flags&MEM_Int );
72016   if( pIn1->u.i>0 ){
72017      pc = pOp->p2 - 1;
72018   }
72019   break;
72020 }
72021 
72022 /* Opcode: IfNeg P1 P2 * * *
72023 ** Synopsis: if r[P1]<0 goto P2
72024 **
72025 ** If the value of register P1 is less than zero, jump to P2. 
72026 **
72027 ** It is illegal to use this instruction on a register that does
72028 ** not contain an integer.  An assertion fault will result if you try.
72029 */
72030 case OP_IfNeg: {        /* jump, in1 */
72031   pIn1 = &aMem[pOp->p1];
72032   assert( pIn1->flags&MEM_Int );
72033   if( pIn1->u.i<0 ){
72034      pc = pOp->p2 - 1;
72035   }
72036   break;
72037 }
72038 
72039 /* Opcode: IfZero P1 P2 P3 * *
72040 ** Synopsis: r[P1]+=P3, if r[P1]==0 goto P2
72041 **
72042 ** The register P1 must contain an integer.  Add literal P3 to the
72043 ** value in register P1.  If the result is exactly 0, jump to P2. 
72044 **
72045 ** It is illegal to use this instruction on a register that does
72046 ** not contain an integer.  An assertion fault will result if you try.
72047 */
72048 case OP_IfZero: {        /* jump, in1 */
72049   pIn1 = &aMem[pOp->p1];
72050   assert( pIn1->flags&MEM_Int );
72051   pIn1->u.i += pOp->p3;
72052   if( pIn1->u.i==0 ){
72053      pc = pOp->p2 - 1;
72054   }
72055   break;
72056 }
72057 
72058 /* Opcode: AggStep * P2 P3 P4 P5
72059 ** Synopsis: accum=r[P3] step(r[P2@P5])
72060 **
72061 ** Execute the step function for an aggregate.  The
72062 ** function has P5 arguments.   P4 is a pointer to the FuncDef
72063 ** structure that specifies the function.  Use register
72064 ** P3 as the accumulator.
72065 **
72066 ** The P5 arguments are taken from register P2 and its
72067 ** successors.
72068 */
72069 case OP_AggStep: {
72070 #if 0  /* local variables moved into u.cg */
72071   int n;
72072   int i;
72073   Mem *pMem;
72074   Mem *pRec;
72075   sqlite3_context ctx;
72076   sqlite3_value **apVal;
72077 #endif /* local variables moved into u.cg */
72078 
72079   u.cg.n = pOp->p5;
72080   assert( u.cg.n>=0 );
72081   u.cg.pRec = &aMem[pOp->p2];
72082   u.cg.apVal = p->apArg;
72083   assert( u.cg.apVal || u.cg.n==0 );
72084   for(u.cg.i=0; u.cg.i<u.cg.n; u.cg.i++, u.cg.pRec++){
72085     assert( memIsValid(u.cg.pRec) );
72086     u.cg.apVal[u.cg.i] = u.cg.pRec;
72087     memAboutToChange(p, u.cg.pRec);
72088     sqlite3VdbeMemStoreType(u.cg.pRec);
72089   }
72090   u.cg.ctx.pFunc = pOp->p4.pFunc;
72091   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
72092   u.cg.ctx.pMem = u.cg.pMem = &aMem[pOp->p3];
72093   u.cg.pMem->n++;
72094   u.cg.ctx.s.flags = MEM_Null;
72095   u.cg.ctx.s.z = 0;
72096   u.cg.ctx.s.zMalloc = 0;
72097   u.cg.ctx.s.xDel = 0;
72098   u.cg.ctx.s.db = db;
72099   u.cg.ctx.isError = 0;
72100   u.cg.ctx.pColl = 0;
72101   u.cg.ctx.skipFlag = 0;
72102   if( u.cg.ctx.pFunc->funcFlags & SQLITE_FUNC_NEEDCOLL ){
72103     assert( pOp>p->aOp );
72104     assert( pOp[-1].p4type==P4_COLLSEQ );
72105     assert( pOp[-1].opcode==OP_CollSeq );
72106     u.cg.ctx.pColl = pOp[-1].p4.pColl;
72107   }
72108   (u.cg.ctx.pFunc->xStep)(&u.cg.ctx, u.cg.n, u.cg.apVal); /* IMP: R-24505-23230 */
72109   if( u.cg.ctx.isError ){
72110     sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3_value_text(&u.cg.ctx.s));
72111     rc = u.cg.ctx.isError;
72112   }
72113   if( u.cg.ctx.skipFlag ){
72114     assert( pOp[-1].opcode==OP_CollSeq );
72115     u.cg.i = pOp[-1].p1;
72116     if( u.cg.i ) sqlite3VdbeMemSetInt64(&aMem[u.cg.i], 1);
72117   }
72118 
72119   sqlite3VdbeMemRelease(&u.cg.ctx.s);
72120 
72121   break;
72122 }
72123 
72124 /* Opcode: AggFinal P1 P2 * P4 *
72125 ** Synopsis: accum=r[P1] N=P2
72126 **
72127 ** Execute the finalizer function for an aggregate.  P1 is
72128 ** the memory location that is the accumulator for the aggregate.
72129 **
72130 ** P2 is the number of arguments that the step function takes and
72131 ** P4 is a pointer to the FuncDef for this function.  The P2
72132 ** argument is not used by this opcode.  It is only there to disambiguate
72133 ** functions that can take varying numbers of arguments.  The
72134 ** P4 argument is only needed for the degenerate case where
72135 ** the step function was not previously called.
72136 */
72137 case OP_AggFinal: {
72138 #if 0  /* local variables moved into u.ch */
72139   Mem *pMem;
72140 #endif /* local variables moved into u.ch */
72141   assert( pOp->p1>0 && pOp->p1<=(p->nMem-p->nCursor) );
72142   u.ch.pMem = &aMem[pOp->p1];
72143   assert( (u.ch.pMem->flags & ~(MEM_Null|MEM_Agg))==0 );
72144   rc = sqlite3VdbeMemFinalize(u.ch.pMem, pOp->p4.pFunc);
72145   if( rc ){
72146     sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3_value_text(u.ch.pMem));
72147   }
72148   sqlite3VdbeChangeEncoding(u.ch.pMem, encoding);
72149   UPDATE_MAX_BLOBSIZE(u.ch.pMem);
72150   if( sqlite3VdbeMemTooBig(u.ch.pMem) ){
72151     goto too_big;
72152   }
72153   break;
72154 }
72155 
72156 #ifndef SQLITE_OMIT_WAL
72157 /* Opcode: Checkpoint P1 P2 P3 * *
72158 **
72159 ** Checkpoint database P1. This is a no-op if P1 is not currently in
72160 ** WAL mode. Parameter P2 is one of SQLITE_CHECKPOINT_PASSIVE, FULL
72161 ** or RESTART.  Write 1 or 0 into mem[P3] if the checkpoint returns
72162 ** SQLITE_BUSY or not, respectively.  Write the number of pages in the
72163 ** WAL after the checkpoint into mem[P3+1] and the number of pages
72164 ** in the WAL that have been checkpointed after the checkpoint
72165 ** completes into mem[P3+2].  However on an error, mem[P3+1] and
72166 ** mem[P3+2] are initialized to -1.
72167 */
72168 case OP_Checkpoint: {
72169 #if 0  /* local variables moved into u.ci */
72170   int i;                          /* Loop counter */
72171   int aRes[3];                    /* Results */
72172   Mem *pMem;                      /* Write results here */
72173 #endif /* local variables moved into u.ci */
72174 
72175   assert( p->readOnly==0 );
72176   u.ci.aRes[0] = 0;
72177   u.ci.aRes[1] = u.ci.aRes[2] = -1;
72178   assert( pOp->p2==SQLITE_CHECKPOINT_PASSIVE
72179        || pOp->p2==SQLITE_CHECKPOINT_FULL
72180        || pOp->p2==SQLITE_CHECKPOINT_RESTART
72181   );
72182   rc = sqlite3Checkpoint(db, pOp->p1, pOp->p2, &u.ci.aRes[1], &u.ci.aRes[2]);
72183   if( rc==SQLITE_BUSY ){
72184     rc = SQLITE_OK;
72185     u.ci.aRes[0] = 1;
72186   }
72187   for(u.ci.i=0, u.ci.pMem = &aMem[pOp->p3]; u.ci.i<3; u.ci.i++, u.ci.pMem++){
72188     sqlite3VdbeMemSetInt64(u.ci.pMem, (i64)u.ci.aRes[u.ci.i]);
72189   }
72190   break;
72191 };  
72192 #endif
72193 
72194 #ifndef SQLITE_OMIT_PRAGMA
72195 /* Opcode: JournalMode P1 P2 P3 * P5
72196 **
72197 ** Change the journal mode of database P1 to P3. P3 must be one of the
72198 ** PAGER_JOURNALMODE_XXX values. If changing between the various rollback
72199 ** modes (delete, truncate, persist, off and memory), this is a simple
72200 ** operation. No IO is required.
72201 **
72202 ** If changing into or out of WAL mode the procedure is more complicated.
72203 **
72204 ** Write a string containing the final journal-mode to register P2.
72205 */
72206 case OP_JournalMode: {    /* out2-prerelease */
72207 #if 0  /* local variables moved into u.cj */
72208   Btree *pBt;                     /* Btree to change journal mode of */
72209   Pager *pPager;                  /* Pager associated with pBt */
72210   int eNew;                       /* New journal mode */
72211   int eOld;                       /* The old journal mode */
72212 #ifndef SQLITE_OMIT_WAL
72213   const char *zFilename;          /* Name of database file for pPager */
72214 #endif
72215 #endif /* local variables moved into u.cj */
72216 
72217   u.cj.eNew = pOp->p3;
72218   assert( u.cj.eNew==PAGER_JOURNALMODE_DELETE
72219        || u.cj.eNew==PAGER_JOURNALMODE_TRUNCATE
72220        || u.cj.eNew==PAGER_JOURNALMODE_PERSIST
72221        || u.cj.eNew==PAGER_JOURNALMODE_OFF
72222        || u.cj.eNew==PAGER_JOURNALMODE_MEMORY
72223        || u.cj.eNew==PAGER_JOURNALMODE_WAL
72224        || u.cj.eNew==PAGER_JOURNALMODE_QUERY
72225   );
72226   assert( pOp->p1>=0 && pOp->p1<db->nDb );
72227   assert( p->readOnly==0 );
72228 
72229   u.cj.pBt = db->aDb[pOp->p1].pBt;
72230   u.cj.pPager = sqlite3BtreePager(u.cj.pBt);
72231   u.cj.eOld = sqlite3PagerGetJournalMode(u.cj.pPager);
72232   if( u.cj.eNew==PAGER_JOURNALMODE_QUERY ) u.cj.eNew = u.cj.eOld;
72233   if( !sqlite3PagerOkToChangeJournalMode(u.cj.pPager) ) u.cj.eNew = u.cj.eOld;
72234 
72235 #ifndef SQLITE_OMIT_WAL
72236   u.cj.zFilename = sqlite3PagerFilename(u.cj.pPager, 1);
72237 
72238   /* Do not allow a transition to journal_mode=WAL for a database
72239   ** in temporary storage or if the VFS does not support shared memory
72240   */
72241   if( u.cj.eNew==PAGER_JOURNALMODE_WAL
72242    && (sqlite3Strlen30(u.cj.zFilename)==0           /* Temp file */
72243        || !sqlite3PagerWalSupported(u.cj.pPager))   /* No shared-memory support */
72244   ){
72245     u.cj.eNew = u.cj.eOld;
72246   }
72247 
72248   if( (u.cj.eNew!=u.cj.eOld)
72249    && (u.cj.eOld==PAGER_JOURNALMODE_WAL || u.cj.eNew==PAGER_JOURNALMODE_WAL)
72250   ){
72251     if( !db->autoCommit || db->nVdbeRead>1 ){
72252       rc = SQLITE_ERROR;
72253       sqlite3SetString(&p->zErrMsg, db,
72254           "cannot change %s wal mode from within a transaction",
72255           (u.cj.eNew==PAGER_JOURNALMODE_WAL ? "into" : "out of")
72256       );
72257       break;
72258     }else{
72259 
72260       if( u.cj.eOld==PAGER_JOURNALMODE_WAL ){
72261         /* If leaving WAL mode, close the log file. If successful, the call
72262         ** to PagerCloseWal() checkpoints and deletes the write-ahead-log
72263         ** file. An EXCLUSIVE lock may still be held on the database file
72264         ** after a successful return.
72265         */
72266         rc = sqlite3PagerCloseWal(u.cj.pPager);
72267         if( rc==SQLITE_OK ){
72268           sqlite3PagerSetJournalMode(u.cj.pPager, u.cj.eNew);
72269         }
72270       }else if( u.cj.eOld==PAGER_JOURNALMODE_MEMORY ){
72271         /* Cannot transition directly from MEMORY to WAL.  Use mode OFF
72272         ** as an intermediate */
72273         sqlite3PagerSetJournalMode(u.cj.pPager, PAGER_JOURNALMODE_OFF);
72274       }
72275 
72276       /* Open a transaction on the database file. Regardless of the journal
72277       ** mode, this transaction always uses a rollback journal.
72278       */
72279       assert( sqlite3BtreeIsInTrans(u.cj.pBt)==0 );
72280       if( rc==SQLITE_OK ){
72281         rc = sqlite3BtreeSetVersion(u.cj.pBt, (u.cj.eNew==PAGER_JOURNALMODE_WAL ? 2 : 1));
72282       }
72283     }
72284   }
72285 #endif /* ifndef SQLITE_OMIT_WAL */
72286 
72287   if( rc ){
72288     u.cj.eNew = u.cj.eOld;
72289   }
72290   u.cj.eNew = sqlite3PagerSetJournalMode(u.cj.pPager, u.cj.eNew);
72291 
72292   pOut = &aMem[pOp->p2];
72293   pOut->flags = MEM_Str|MEM_Static|MEM_Term;
72294   pOut->z = (char *)sqlite3JournalModename(u.cj.eNew);
72295   pOut->n = sqlite3Strlen30(pOut->z);
72296   pOut->enc = SQLITE_UTF8;
72297   sqlite3VdbeChangeEncoding(pOut, encoding);
72298   break;
72299 };
72300 #endif /* SQLITE_OMIT_PRAGMA */
72301 
72302 #if !defined(SQLITE_OMIT_VACUUM) && !defined(SQLITE_OMIT_ATTACH)
72303 /* Opcode: Vacuum * * * * *
72304 **
72305 ** Vacuum the entire database.  This opcode will cause other virtual
72306 ** machines to be created and run.  It may not be called from within
72307 ** a transaction.
72308 */
72309 case OP_Vacuum: {
72310   assert( p->readOnly==0 );
72311   rc = sqlite3RunVacuum(&p->zErrMsg, db);
72312   break;
72313 }
72314 #endif
72315 
72316 #if !defined(SQLITE_OMIT_AUTOVACUUM)
72317 /* Opcode: IncrVacuum P1 P2 * * *
72318 **
72319 ** Perform a single step of the incremental vacuum procedure on
72320 ** the P1 database. If the vacuum has finished, jump to instruction
72321 ** P2. Otherwise, fall through to the next instruction.
72322 */
72323 case OP_IncrVacuum: {        /* jump */
72324 #if 0  /* local variables moved into u.ck */
72325   Btree *pBt;
72326 #endif /* local variables moved into u.ck */
72327 
72328   assert( pOp->p1>=0 && pOp->p1<db->nDb );
72329   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p1))!=0 );
72330   assert( p->readOnly==0 );
72331   u.ck.pBt = db->aDb[pOp->p1].pBt;
72332   rc = sqlite3BtreeIncrVacuum(u.ck.pBt);
72333   if( rc==SQLITE_DONE ){
72334     pc = pOp->p2 - 1;
72335     rc = SQLITE_OK;
72336   }
72337   break;
72338 }
72339 #endif
72340 
72341 /* Opcode: Expire P1 * * * *
72342 **
72343 ** Cause precompiled statements to become expired. An expired statement
72344 ** fails with an error code of SQLITE_SCHEMA if it is ever executed 
72345 ** (via sqlite3_step()).
72346 ** 
72347 ** If P1 is 0, then all SQL statements become expired. If P1 is non-zero,
72348 ** then only the currently executing statement is affected. 
72349 */
72350 case OP_Expire: {
72351   if( !pOp->p1 ){
72352     sqlite3ExpirePreparedStatements(db);
72353   }else{
72354     p->expired = 1;
72355   }
72356   break;
72357 }
72358 
72359 #ifndef SQLITE_OMIT_SHARED_CACHE
72360 /* Opcode: TableLock P1 P2 P3 P4 *
72361 ** Synopsis: iDb=P1 root=P2 write=P3
72362 **
72363 ** Obtain a lock on a particular table. This instruction is only used when
72364 ** the shared-cache feature is enabled. 
72365 **
72366 ** P1 is the index of the database in sqlite3.aDb[] of the database
72367 ** on which the lock is acquired.  A readlock is obtained if P3==0 or
72368 ** a write lock if P3==1.
72369 **
72370 ** P2 contains the root-page of the table to lock.
72371 **
72372 ** P4 contains a pointer to the name of the table being locked. This is only
72373 ** used to generate an error message if the lock cannot be obtained.
72374 */
72375 case OP_TableLock: {
72376   u8 isWriteLock = (u8)pOp->p3;
72377   if( isWriteLock || 0==(db->flags&SQLITE_ReadUncommitted) ){
72378     int p1 = pOp->p1; 
72379     assert( p1>=0 && p1<db->nDb );
72380     assert( (p->btreeMask & (((yDbMask)1)<<p1))!=0 );
72381     assert( isWriteLock==0 || isWriteLock==1 );
72382     rc = sqlite3BtreeLockTable(db->aDb[p1].pBt, pOp->p2, isWriteLock);
72383     if( (rc&0xFF)==SQLITE_LOCKED ){
72384       const char *z = pOp->p4.z;
72385       sqlite3SetString(&p->zErrMsg, db, "database table is locked: %s", z);
72386     }
72387   }
72388   break;
72389 }
72390 #endif /* SQLITE_OMIT_SHARED_CACHE */
72391 
72392 #ifndef SQLITE_OMIT_VIRTUALTABLE
72393 /* Opcode: VBegin * * * P4 *
72394 **
72395 ** P4 may be a pointer to an sqlite3_vtab structure. If so, call the 
72396 ** xBegin method for that table.
72397 **
72398 ** Also, whether or not P4 is set, check that this is not being called from
72399 ** within a callback to a virtual table xSync() method. If it is, the error
72400 ** code will be set to SQLITE_LOCKED.
72401 */
72402 case OP_VBegin: {
72403 #if 0  /* local variables moved into u.cl */
72404   VTable *pVTab;
72405 #endif /* local variables moved into u.cl */
72406   u.cl.pVTab = pOp->p4.pVtab;
72407   rc = sqlite3VtabBegin(db, u.cl.pVTab);
72408   if( u.cl.pVTab ) sqlite3VtabImportErrmsg(p, u.cl.pVTab->pVtab);
72409   break;
72410 }
72411 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72412 
72413 #ifndef SQLITE_OMIT_VIRTUALTABLE
72414 /* Opcode: VCreate P1 * * P4 *
72415 **
72416 ** P4 is the name of a virtual table in database P1. Call the xCreate method
72417 ** for that table.
72418 */
72419 case OP_VCreate: {
72420   rc = sqlite3VtabCallCreate(db, pOp->p1, pOp->p4.z, &p->zErrMsg);
72421   break;
72422 }
72423 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72424 
72425 #ifndef SQLITE_OMIT_VIRTUALTABLE
72426 /* Opcode: VDestroy P1 * * P4 *
72427 **
72428 ** P4 is the name of a virtual table in database P1.  Call the xDestroy method
72429 ** of that table.
72430 */
72431 case OP_VDestroy: {
72432   p->inVtabMethod = 2;
72433   rc = sqlite3VtabCallDestroy(db, pOp->p1, pOp->p4.z);
72434   p->inVtabMethod = 0;
72435   break;
72436 }
72437 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72438 
72439 #ifndef SQLITE_OMIT_VIRTUALTABLE
72440 /* Opcode: VOpen P1 * * P4 *
72441 **
72442 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
72443 ** P1 is a cursor number.  This opcode opens a cursor to the virtual
72444 ** table and stores that cursor in P1.
72445 */
72446 case OP_VOpen: {
72447 #if 0  /* local variables moved into u.cm */
72448   VdbeCursor *pCur;
72449   sqlite3_vtab_cursor *pVtabCursor;
72450   sqlite3_vtab *pVtab;
72451   sqlite3_module *pModule;
72452 #endif /* local variables moved into u.cm */
72453 
72454   assert( p->bIsReader );
72455   u.cm.pCur = 0;
72456   u.cm.pVtabCursor = 0;
72457   u.cm.pVtab = pOp->p4.pVtab->pVtab;
72458   u.cm.pModule = (sqlite3_module *)u.cm.pVtab->pModule;
72459   assert(u.cm.pVtab && u.cm.pModule);
72460   rc = u.cm.pModule->xOpen(u.cm.pVtab, &u.cm.pVtabCursor);
72461   sqlite3VtabImportErrmsg(p, u.cm.pVtab);
72462   if( SQLITE_OK==rc ){
72463     /* Initialize sqlite3_vtab_cursor base class */
72464     u.cm.pVtabCursor->pVtab = u.cm.pVtab;
72465 
72466     /* Initialize vdbe cursor object */
72467     u.cm.pCur = allocateCursor(p, pOp->p1, 0, -1, 0);
72468     if( u.cm.pCur ){
72469       u.cm.pCur->pVtabCursor = u.cm.pVtabCursor;
72470     }else{
72471       db->mallocFailed = 1;
72472       u.cm.pModule->xClose(u.cm.pVtabCursor);
72473     }
72474   }
72475   break;
72476 }
72477 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72478 
72479 #ifndef SQLITE_OMIT_VIRTUALTABLE
72480 /* Opcode: VFilter P1 P2 P3 P4 *
72481 ** Synopsis: iPlan=r[P3] zPlan='P4'
72482 **
72483 ** P1 is a cursor opened using VOpen.  P2 is an address to jump to if
72484 ** the filtered result set is empty.
72485 **
72486 ** P4 is either NULL or a string that was generated by the xBestIndex
72487 ** method of the module.  The interpretation of the P4 string is left
72488 ** to the module implementation.
72489 **
72490 ** This opcode invokes the xFilter method on the virtual table specified
72491 ** by P1.  The integer query plan parameter to xFilter is stored in register
72492 ** P3. Register P3+1 stores the argc parameter to be passed to the
72493 ** xFilter method. Registers P3+2..P3+1+argc are the argc
72494 ** additional parameters which are passed to
72495 ** xFilter as argv. Register P3+2 becomes argv[0] when passed to xFilter.
72496 **
72497 ** A jump is made to P2 if the result set after filtering would be empty.
72498 */
72499 case OP_VFilter: {   /* jump */
72500 #if 0  /* local variables moved into u.cn */
72501   int nArg;
72502   int iQuery;
72503   const sqlite3_module *pModule;
72504   Mem *pQuery;
72505   Mem *pArgc;
72506   sqlite3_vtab_cursor *pVtabCursor;
72507   sqlite3_vtab *pVtab;
72508   VdbeCursor *pCur;
72509   int res;
72510   int i;
72511   Mem **apArg;
72512 #endif /* local variables moved into u.cn */
72513 
72514   u.cn.pQuery = &aMem[pOp->p3];
72515   u.cn.pArgc = &u.cn.pQuery[1];
72516   u.cn.pCur = p->apCsr[pOp->p1];
72517   assert( memIsValid(u.cn.pQuery) );
72518   REGISTER_TRACE(pOp->p3, u.cn.pQuery);
72519   assert( u.cn.pCur->pVtabCursor );
72520   u.cn.pVtabCursor = u.cn.pCur->pVtabCursor;
72521   u.cn.pVtab = u.cn.pVtabCursor->pVtab;
72522   u.cn.pModule = u.cn.pVtab->pModule;
72523 
72524   /* Grab the index number and argc parameters */
72525   assert( (u.cn.pQuery->flags&MEM_Int)!=0 && u.cn.pArgc->flags==MEM_Int );
72526   u.cn.nArg = (int)u.cn.pArgc->u.i;
72527   u.cn.iQuery = (int)u.cn.pQuery->u.i;
72528 
72529   /* Invoke the xFilter method */
72530   {
72531     u.cn.res = 0;
72532     u.cn.apArg = p->apArg;
72533     for(u.cn.i = 0; u.cn.i<u.cn.nArg; u.cn.i++){
72534       u.cn.apArg[u.cn.i] = &u.cn.pArgc[u.cn.i+1];
72535       sqlite3VdbeMemStoreType(u.cn.apArg[u.cn.i]);
72536     }
72537 
72538     p->inVtabMethod = 1;
72539     rc = u.cn.pModule->xFilter(u.cn.pVtabCursor, u.cn.iQuery, pOp->p4.z, u.cn.nArg, u.cn.apArg);
72540     p->inVtabMethod = 0;
72541     sqlite3VtabImportErrmsg(p, u.cn.pVtab);
72542     if( rc==SQLITE_OK ){
72543       u.cn.res = u.cn.pModule->xEof(u.cn.pVtabCursor);
72544     }
72545 
72546     if( u.cn.res ){
72547       pc = pOp->p2 - 1;
72548     }
72549   }
72550   u.cn.pCur->nullRow = 0;
72551 
72552   break;
72553 }
72554 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72555 
72556 #ifndef SQLITE_OMIT_VIRTUALTABLE
72557 /* Opcode: VColumn P1 P2 P3 * *
72558 ** Synopsis: r[P3]=vcolumn(P2)
72559 **
72560 ** Store the value of the P2-th column of
72561 ** the row of the virtual-table that the 
72562 ** P1 cursor is pointing to into register P3.
72563 */
72564 case OP_VColumn: {
72565 #if 0  /* local variables moved into u.co */
72566   sqlite3_vtab *pVtab;
72567   const sqlite3_module *pModule;
72568   Mem *pDest;
72569   sqlite3_context sContext;
72570 #endif /* local variables moved into u.co */
72571 
72572   VdbeCursor *pCur = p->apCsr[pOp->p1];
72573   assert( pCur->pVtabCursor );
72574   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
72575   u.co.pDest = &aMem[pOp->p3];
72576   memAboutToChange(p, u.co.pDest);
72577   if( pCur->nullRow ){
72578     sqlite3VdbeMemSetNull(u.co.pDest);
72579     break;
72580   }
72581   u.co.pVtab = pCur->pVtabCursor->pVtab;
72582   u.co.pModule = u.co.pVtab->pModule;
72583   assert( u.co.pModule->xColumn );
72584   memset(&u.co.sContext, 0, sizeof(u.co.sContext));
72585 
72586   /* The output cell may already have a buffer allocated. Move
72587   ** the current contents to u.co.sContext.s so in case the user-function
72588   ** can use the already allocated buffer instead of allocating a
72589   ** new one.
72590   */
72591   sqlite3VdbeMemMove(&u.co.sContext.s, u.co.pDest);
72592   MemSetTypeFlag(&u.co.sContext.s, MEM_Null);
72593 
72594   rc = u.co.pModule->xColumn(pCur->pVtabCursor, &u.co.sContext, pOp->p2);
72595   sqlite3VtabImportErrmsg(p, u.co.pVtab);
72596   if( u.co.sContext.isError ){
72597     rc = u.co.sContext.isError;
72598   }
72599 
72600   /* Copy the result of the function to the P3 register. We
72601   ** do this regardless of whether or not an error occurred to ensure any
72602   ** dynamic allocation in u.co.sContext.s (a Mem struct) is  released.
72603   */
72604   sqlite3VdbeChangeEncoding(&u.co.sContext.s, encoding);
72605   sqlite3VdbeMemMove(u.co.pDest, &u.co.sContext.s);
72606   REGISTER_TRACE(pOp->p3, u.co.pDest);
72607   UPDATE_MAX_BLOBSIZE(u.co.pDest);
72608 
72609   if( sqlite3VdbeMemTooBig(u.co.pDest) ){
72610     goto too_big;
72611   }
72612   break;
72613 }
72614 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72615 
72616 #ifndef SQLITE_OMIT_VIRTUALTABLE
72617 /* Opcode: VNext P1 P2 * * *
72618 **
72619 ** Advance virtual table P1 to the next row in its result set and
72620 ** jump to instruction P2.  Or, if the virtual table has reached
72621 ** the end of its result set, then fall through to the next instruction.
72622 */
72623 case OP_VNext: {   /* jump */
72624 #if 0  /* local variables moved into u.cp */
72625   sqlite3_vtab *pVtab;
72626   const sqlite3_module *pModule;
72627   int res;
72628   VdbeCursor *pCur;
72629 #endif /* local variables moved into u.cp */
72630 
72631   u.cp.res = 0;
72632   u.cp.pCur = p->apCsr[pOp->p1];
72633   assert( u.cp.pCur->pVtabCursor );
72634   if( u.cp.pCur->nullRow ){
72635     break;
72636   }
72637   u.cp.pVtab = u.cp.pCur->pVtabCursor->pVtab;
72638   u.cp.pModule = u.cp.pVtab->pModule;
72639   assert( u.cp.pModule->xNext );
72640 
72641   /* Invoke the xNext() method of the module. There is no way for the
72642   ** underlying implementation to return an error if one occurs during
72643   ** xNext(). Instead, if an error occurs, true is returned (indicating that
72644   ** data is available) and the error code returned when xColumn or
72645   ** some other method is next invoked on the save virtual table cursor.
72646   */
72647   p->inVtabMethod = 1;
72648   rc = u.cp.pModule->xNext(u.cp.pCur->pVtabCursor);
72649   p->inVtabMethod = 0;
72650   sqlite3VtabImportErrmsg(p, u.cp.pVtab);
72651   if( rc==SQLITE_OK ){
72652     u.cp.res = u.cp.pModule->xEof(u.cp.pCur->pVtabCursor);
72653   }
72654 
72655   if( !u.cp.res ){
72656     /* If there is data, jump to P2 */
72657     pc = pOp->p2 - 1;
72658   }
72659   goto check_for_interrupt;
72660 }
72661 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72662 
72663 #ifndef SQLITE_OMIT_VIRTUALTABLE
72664 /* Opcode: VRename P1 * * P4 *
72665 **
72666 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
72667 ** This opcode invokes the corresponding xRename method. The value
72668 ** in register P1 is passed as the zName argument to the xRename method.
72669 */
72670 case OP_VRename: {
72671 #if 0  /* local variables moved into u.cq */
72672   sqlite3_vtab *pVtab;
72673   Mem *pName;
72674 #endif /* local variables moved into u.cq */
72675 
72676   u.cq.pVtab = pOp->p4.pVtab->pVtab;
72677   u.cq.pName = &aMem[pOp->p1];
72678   assert( u.cq.pVtab->pModule->xRename );
72679   assert( memIsValid(u.cq.pName) );
72680   assert( p->readOnly==0 );
72681   REGISTER_TRACE(pOp->p1, u.cq.pName);
72682   assert( u.cq.pName->flags & MEM_Str );
72683   testcase( u.cq.pName->enc==SQLITE_UTF8 );
72684   testcase( u.cq.pName->enc==SQLITE_UTF16BE );
72685   testcase( u.cq.pName->enc==SQLITE_UTF16LE );
72686   rc = sqlite3VdbeChangeEncoding(u.cq.pName, SQLITE_UTF8);
72687   if( rc==SQLITE_OK ){
72688     rc = u.cq.pVtab->pModule->xRename(u.cq.pVtab, u.cq.pName->z);
72689     sqlite3VtabImportErrmsg(p, u.cq.pVtab);
72690     p->expired = 0;
72691   }
72692   break;
72693 }
72694 #endif
72695 
72696 #ifndef SQLITE_OMIT_VIRTUALTABLE
72697 /* Opcode: VUpdate P1 P2 P3 P4 *
72698 ** Synopsis: data=r[P3@P2]
72699 **
72700 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
72701 ** This opcode invokes the corresponding xUpdate method. P2 values
72702 ** are contiguous memory cells starting at P3 to pass to the xUpdate 
72703 ** invocation. The value in register (P3+P2-1) corresponds to the 
72704 ** p2th element of the argv array passed to xUpdate.
72705 **
72706 ** The xUpdate method will do a DELETE or an INSERT or both.
72707 ** The argv[0] element (which corresponds to memory cell P3)
72708 ** is the rowid of a row to delete.  If argv[0] is NULL then no 
72709 ** deletion occurs.  The argv[1] element is the rowid of the new 
72710 ** row.  This can be NULL to have the virtual table select the new 
72711 ** rowid for itself.  The subsequent elements in the array are 
72712 ** the values of columns in the new row.
72713 **
72714 ** If P2==1 then no insert is performed.  argv[0] is the rowid of
72715 ** a row to delete.
72716 **
72717 ** P1 is a boolean flag. If it is set to true and the xUpdate call
72718 ** is successful, then the value returned by sqlite3_last_insert_rowid() 
72719 ** is set to the value of the rowid for the row just inserted.
72720 */
72721 case OP_VUpdate: {
72722 #if 0  /* local variables moved into u.cr */
72723   sqlite3_vtab *pVtab;
72724   sqlite3_module *pModule;
72725   int nArg;
72726   int i;
72727   sqlite_int64 rowid;
72728   Mem **apArg;
72729   Mem *pX;
72730 #endif /* local variables moved into u.cr */
72731 
72732   assert( pOp->p2==1        || pOp->p5==OE_Fail   || pOp->p5==OE_Rollback
72733        || pOp->p5==OE_Abort || pOp->p5==OE_Ignore || pOp->p5==OE_Replace
72734   );
72735   assert( p->readOnly==0 );
72736   u.cr.pVtab = pOp->p4.pVtab->pVtab;
72737   u.cr.pModule = (sqlite3_module *)u.cr.pVtab->pModule;
72738   u.cr.nArg = pOp->p2;
72739   assert( pOp->p4type==P4_VTAB );
72740   if( ALWAYS(u.cr.pModule->xUpdate) ){
72741     u8 vtabOnConflict = db->vtabOnConflict;
72742     u.cr.apArg = p->apArg;
72743     u.cr.pX = &aMem[pOp->p3];
72744     for(u.cr.i=0; u.cr.i<u.cr.nArg; u.cr.i++){
72745       assert( memIsValid(u.cr.pX) );
72746       memAboutToChange(p, u.cr.pX);
72747       sqlite3VdbeMemStoreType(u.cr.pX);
72748       u.cr.apArg[u.cr.i] = u.cr.pX;
72749       u.cr.pX++;
72750     }
72751     db->vtabOnConflict = pOp->p5;
72752     rc = u.cr.pModule->xUpdate(u.cr.pVtab, u.cr.nArg, u.cr.apArg, &u.cr.rowid);
72753     db->vtabOnConflict = vtabOnConflict;
72754     sqlite3VtabImportErrmsg(p, u.cr.pVtab);
72755     if( rc==SQLITE_OK && pOp->p1 ){
72756       assert( u.cr.nArg>1 && u.cr.apArg[0] && (u.cr.apArg[0]->flags&MEM_Null) );
72757       db->lastRowid = lastRowid = u.cr.rowid;
72758     }
72759     if( (rc&0xff)==SQLITE_CONSTRAINT && pOp->p4.pVtab->bConstraint ){
72760       if( pOp->p5==OE_Ignore ){
72761         rc = SQLITE_OK;
72762       }else{
72763         p->errorAction = ((pOp->p5==OE_Replace) ? OE_Abort : pOp->p5);
72764       }
72765     }else{
72766       p->nChange++;
72767     }
72768   }
72769   break;
72770 }
72771 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72772 
72773 #ifndef  SQLITE_OMIT_PAGER_PRAGMAS
72774 /* Opcode: Pagecount P1 P2 * * *
72775 **
72776 ** Write the current number of pages in database P1 to memory cell P2.
72777 */
72778 case OP_Pagecount: {            /* out2-prerelease */
72779   pOut->u.i = sqlite3BtreeLastPage(db->aDb[pOp->p1].pBt);
72780   break;
72781 }
72782 #endif
72783 
72784 
72785 #ifndef  SQLITE_OMIT_PAGER_PRAGMAS
72786 /* Opcode: MaxPgcnt P1 P2 P3 * *
72787 **
72788 ** Try to set the maximum page count for database P1 to the value in P3.
72789 ** Do not let the maximum page count fall below the current page count and
72790 ** do not change the maximum page count value if P3==0.
72791 **
72792 ** Store the maximum page count after the change in register P2.
72793 */
72794 case OP_MaxPgcnt: {            /* out2-prerelease */
72795   unsigned int newMax;
72796   Btree *pBt;
72797 
72798   pBt = db->aDb[pOp->p1].pBt;
72799   newMax = 0;
72800   if( pOp->p3 ){
72801     newMax = sqlite3BtreeLastPage(pBt);
72802     if( newMax < (unsigned)pOp->p3 ) newMax = (unsigned)pOp->p3;
72803   }
72804   pOut->u.i = sqlite3BtreeMaxPageCount(pBt, newMax);
72805   break;
72806 }
72807 #endif
72808 
72809 
72810 #ifndef SQLITE_OMIT_TRACE
72811 /* Opcode: Trace * * * P4 *
72812 **
72813 ** If tracing is enabled (by the sqlite3_trace()) interface, then
72814 ** the UTF-8 string contained in P4 is emitted on the trace callback.
72815 */
72816 case OP_Trace: {
72817 #if 0  /* local variables moved into u.cs */
72818   char *zTrace;
72819   char *z;
72820 #endif /* local variables moved into u.cs */
72821 
72822   if( db->xTrace
72823    && !p->doingRerun
72824    && (u.cs.zTrace = (pOp->p4.z ? pOp->p4.z : p->zSql))!=0
72825   ){
72826     u.cs.z = sqlite3VdbeExpandSql(p, u.cs.zTrace);
72827     db->xTrace(db->pTraceArg, u.cs.z);
72828     sqlite3DbFree(db, u.cs.z);
72829   }
72830 #ifdef SQLITE_USE_FCNTL_TRACE
72831   u.cs.zTrace = (pOp->p4.z ? pOp->p4.z : p->zSql);
72832   if( u.cs.zTrace ){
72833     int i;
72834     for(i=0; i<db->nDb; i++){
72835       if( ((1<<i) & p->btreeMask)==0 ) continue;
72836       sqlite3_file_control(db, db->aDb[i].zName, SQLITE_FCNTL_TRACE, u.cs.zTrace);
72837     }
72838   }
72839 #endif /* SQLITE_USE_FCNTL_TRACE */
72840 #ifdef SQLITE_DEBUG
72841   if( (db->flags & SQLITE_SqlTrace)!=0
72842    && (u.cs.zTrace = (pOp->p4.z ? pOp->p4.z : p->zSql))!=0
72843   ){
72844     sqlite3DebugPrintf("SQL-trace: %s\n", u.cs.zTrace);
72845   }
72846 #endif /* SQLITE_DEBUG */
72847   break;
72848 }
72849 #endif
72850 
72851 
72852 /* Opcode: Noop * * * * *
72853 **
72854 ** Do nothing.  This instruction is often useful as a jump
72855 ** destination.
72856 */
72857 /*
72858 ** The magic Explain opcode are only inserted when explain==2 (which
72859 ** is to say when the EXPLAIN QUERY PLAN syntax is used.)
72860 ** This opcode records information from the optimizer.  It is the
72861 ** the same as a no-op.  This opcodesnever appears in a real VM program.
72862 */
72863 default: {          /* This is really OP_Noop and OP_Explain */
72864   assert( pOp->opcode==OP_Noop || pOp->opcode==OP_Explain );
72865   break;
72866 }
72867 
72868 /*****************************************************************************
72869 ** The cases of the switch statement above this line should all be indented
72870 ** by 6 spaces.  But the left-most 6 spaces have been removed to improve the
72871 ** readability.  From this point on down, the normal indentation rules are
72872 ** restored.
72873 *****************************************************************************/
72874     }
72875 
72876 #ifdef VDBE_PROFILE
72877     {
72878       u64 elapsed = sqlite3Hwtime() - start;
72879       pOp->cycles += elapsed;
72880       pOp->cnt++;
72881 #if 0
72882         fprintf(stdout, "%10llu ", elapsed);
72883         sqlite3VdbePrintOp(stdout, origPc, &aOp[origPc]);
72884 #endif
72885     }
72886 #endif
72887 
72888     /* The following code adds nothing to the actual functionality
72889     ** of the program.  It is only here for testing and debugging.
72890     ** On the other hand, it does burn CPU cycles every time through
72891     ** the evaluator loop.  So we can leave it out when NDEBUG is defined.
72892     */
72893 #ifndef NDEBUG
72894     assert( pc>=-1 && pc<p->nOp );
72895 
72896 #ifdef SQLITE_DEBUG
72897     if( db->flags & SQLITE_VdbeTrace ){
72898       if( rc!=0 ) printf("rc=%d\n",rc);
72899       if( pOp->opflags & (OPFLG_OUT2_PRERELEASE|OPFLG_OUT2) ){
72900         registerTrace(pOp->p2, &aMem[pOp->p2]);
72901       }
72902       if( pOp->opflags & OPFLG_OUT3 ){
72903         registerTrace(pOp->p3, &aMem[pOp->p3]);
72904       }
72905     }
72906 #endif  /* SQLITE_DEBUG */
72907 #endif  /* NDEBUG */
72908   }  /* The end of the for(;;) loop the loops through opcodes */
72909 
72910   /* If we reach this point, it means that execution is finished with
72911   ** an error of some kind.
72912   */
72913 vdbe_error_halt:
72914   assert( rc );
72915   p->rc = rc;
72916   testcase( sqlite3GlobalConfig.xLog!=0 );
72917   sqlite3_log(rc, "statement aborts at %d: [%s] %s", 
72918                    pc, p->zSql, p->zErrMsg);
72919   sqlite3VdbeHalt(p);
72920   if( rc==SQLITE_IOERR_NOMEM ) db->mallocFailed = 1;
72921   rc = SQLITE_ERROR;
72922   if( resetSchemaOnFault>0 ){
72923     sqlite3ResetOneSchema(db, resetSchemaOnFault-1);
72924   }
72925 
72926   /* This is the only way out of this procedure.  We have to
72927   ** release the mutexes on btrees that were acquired at the
72928   ** top. */
72929 vdbe_return:
72930   db->lastRowid = lastRowid;
72931   testcase( nVmStep>0 );
72932   p->aCounter[SQLITE_STMTSTATUS_VM_STEP] += (int)nVmStep;
72933   sqlite3VdbeLeave(p);
72934   return rc;
72935 
72936   /* Jump to here if a string or blob larger than SQLITE_MAX_LENGTH
72937   ** is encountered.
72938   */
72939 too_big:
72940   sqlite3SetString(&p->zErrMsg, db, "string or blob too big");
72941   rc = SQLITE_TOOBIG;
72942   goto vdbe_error_halt;
72943 
72944   /* Jump to here if a malloc() fails.
72945   */
72946 no_mem:
72947   db->mallocFailed = 1;
72948   sqlite3SetString(&p->zErrMsg, db, "out of memory");
72949   rc = SQLITE_NOMEM;
72950   goto vdbe_error_halt;
72951 
72952   /* Jump to here for any other kind of fatal error.  The "rc" variable
72953   ** should hold the error number.
72954   */
72955 abort_due_to_error:
72956   assert( p->zErrMsg==0 );
72957   if( db->mallocFailed ) rc = SQLITE_NOMEM;
72958   if( rc!=SQLITE_IOERR_NOMEM ){
72959     sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3ErrStr(rc));
72960   }
72961   goto vdbe_error_halt;
72962 
72963   /* Jump to here if the sqlite3_interrupt() API sets the interrupt
72964   ** flag.
72965   */
72966 abort_due_to_interrupt:
72967   assert( db->u1.isInterrupted );
72968   rc = SQLITE_INTERRUPT;
72969   p->rc = rc;
72970   sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3ErrStr(rc));
72971   goto vdbe_error_halt;
72972 }
72973 
72974 /************** End of vdbe.c ************************************************/
72975 /************** Begin file vdbeblob.c ****************************************/
72976 /*
72977 ** 2007 May 1
72978 **
72979 ** The author disclaims copyright to this source code.  In place of
72980 ** a legal notice, here is a blessing:
72981 **
72982 **    May you do good and not evil.
72983 **    May you find forgiveness for yourself and forgive others.
72984 **    May you share freely, never taking more than you give.
72985 **
72986 *************************************************************************
72987 **
72988 ** This file contains code used to implement incremental BLOB I/O.
72989 */
72990 
72991 
72992 #ifndef SQLITE_OMIT_INCRBLOB
72993 
72994 /*
72995 ** Valid sqlite3_blob* handles point to Incrblob structures.
72996 */
72997 typedef struct Incrblob Incrblob;
72998 struct Incrblob {
72999   int flags;              /* Copy of "flags" passed to sqlite3_blob_open() */
73000   int nByte;              /* Size of open blob, in bytes */
73001   int iOffset;            /* Byte offset of blob in cursor data */
73002   int iCol;               /* Table column this handle is open on */
73003   BtCursor *pCsr;         /* Cursor pointing at blob row */
73004   sqlite3_stmt *pStmt;    /* Statement holding cursor open */
73005   sqlite3 *db;            /* The associated database */
73006 };
73007 
73008 
73009 /*
73010 ** This function is used by both blob_open() and blob_reopen(). It seeks
73011 ** the b-tree cursor associated with blob handle p to point to row iRow.
73012 ** If successful, SQLITE_OK is returned and subsequent calls to
73013 ** sqlite3_blob_read() or sqlite3_blob_write() access the specified row.
73014 **
73015 ** If an error occurs, or if the specified row does not exist or does not
73016 ** contain a value of type TEXT or BLOB in the column nominated when the
73017 ** blob handle was opened, then an error code is returned and *pzErr may
73018 ** be set to point to a buffer containing an error message. It is the
73019 ** responsibility of the caller to free the error message buffer using
73020 ** sqlite3DbFree().
73021 **
73022 ** If an error does occur, then the b-tree cursor is closed. All subsequent
73023 ** calls to sqlite3_blob_read(), blob_write() or blob_reopen() will 
73024 ** immediately return SQLITE_ABORT.
73025 */
73026 static int blobSeekToRow(Incrblob *p, sqlite3_int64 iRow, char **pzErr){
73027   int rc;                         /* Error code */
73028   char *zErr = 0;                 /* Error message */
73029   Vdbe *v = (Vdbe *)p->pStmt;
73030 
73031   /* Set the value of the SQL statements only variable to integer iRow. 
73032   ** This is done directly instead of using sqlite3_bind_int64() to avoid 
73033   ** triggering asserts related to mutexes.
73034   */
73035   assert( v->aVar[0].flags&MEM_Int );
73036   v->aVar[0].u.i = iRow;
73037 
73038   rc = sqlite3_step(p->pStmt);
73039   if( rc==SQLITE_ROW ){
73040     VdbeCursor *pC = v->apCsr[0];
73041     u32 type = pC->aType[p->iCol];
73042     if( type<12 ){
73043       zErr = sqlite3MPrintf(p->db, "cannot open value of type %s",
73044           type==0?"null": type==7?"real": "integer"
73045       );
73046       rc = SQLITE_ERROR;
73047       sqlite3_finalize(p->pStmt);
73048       p->pStmt = 0;
73049     }else{
73050       p->iOffset = pC->aType[p->iCol + pC->nField];
73051       p->nByte = sqlite3VdbeSerialTypeLen(type);
73052       p->pCsr =  pC->pCursor;
73053       sqlite3BtreeEnterCursor(p->pCsr);
73054       sqlite3BtreeCacheOverflow(p->pCsr);
73055       sqlite3BtreeLeaveCursor(p->pCsr);
73056     }
73057   }
73058 
73059   if( rc==SQLITE_ROW ){
73060     rc = SQLITE_OK;
73061   }else if( p->pStmt ){
73062     rc = sqlite3_finalize(p->pStmt);
73063     p->pStmt = 0;
73064     if( rc==SQLITE_OK ){
73065       zErr = sqlite3MPrintf(p->db, "no such rowid: %lld", iRow);
73066       rc = SQLITE_ERROR;
73067     }else{
73068       zErr = sqlite3MPrintf(p->db, "%s", sqlite3_errmsg(p->db));
73069     }
73070   }
73071 
73072   assert( rc!=SQLITE_OK || zErr==0 );
73073   assert( rc!=SQLITE_ROW && rc!=SQLITE_DONE );
73074 
73075   *pzErr = zErr;
73076   return rc;
73077 }
73078 
73079 /*
73080 ** Open a blob handle.
73081 */
73082 SQLITE_API int sqlite3_blob_open(
73083   sqlite3* db,            /* The database connection */
73084   const char *zDb,        /* The attached database containing the blob */
73085   const char *zTable,     /* The table containing the blob */
73086   const char *zColumn,    /* The column containing the blob */
73087   sqlite_int64 iRow,      /* The row containing the glob */
73088   int flags,              /* True -> read/write access, false -> read-only */
73089   sqlite3_blob **ppBlob   /* Handle for accessing the blob returned here */
73090 ){
73091   int nAttempt = 0;
73092   int iCol;               /* Index of zColumn in row-record */
73093 
73094   /* This VDBE program seeks a btree cursor to the identified 
73095   ** db/table/row entry. The reason for using a vdbe program instead
73096   ** of writing code to use the b-tree layer directly is that the
73097   ** vdbe program will take advantage of the various transaction,
73098   ** locking and error handling infrastructure built into the vdbe.
73099   **
73100   ** After seeking the cursor, the vdbe executes an OP_ResultRow.
73101   ** Code external to the Vdbe then "borrows" the b-tree cursor and
73102   ** uses it to implement the blob_read(), blob_write() and 
73103   ** blob_bytes() functions.
73104   **
73105   ** The sqlite3_blob_close() function finalizes the vdbe program,
73106   ** which closes the b-tree cursor and (possibly) commits the 
73107   ** transaction.
73108   */
73109   static const VdbeOpList openBlob[] = {
73110     {OP_Transaction, 0, 0, 0},     /* 0: Start a transaction */
73111     {OP_VerifyCookie, 0, 0, 0},    /* 1: Check the schema cookie */
73112     {OP_TableLock, 0, 0, 0},       /* 2: Acquire a read or write lock */
73113 
73114     /* One of the following two instructions is replaced by an OP_Noop. */
73115     {OP_OpenRead, 0, 0, 0},        /* 3: Open cursor 0 for reading */
73116     {OP_OpenWrite, 0, 0, 0},       /* 4: Open cursor 0 for read/write */
73117 
73118     {OP_Variable, 1, 1, 1},        /* 5: Push the rowid to the stack */
73119     {OP_NotExists, 0, 10, 1},      /* 6: Seek the cursor */
73120     {OP_Column, 0, 0, 1},          /* 7  */
73121     {OP_ResultRow, 1, 0, 0},       /* 8  */
73122     {OP_Goto, 0, 5, 0},            /* 9  */
73123     {OP_Close, 0, 0, 0},           /* 10 */
73124     {OP_Halt, 0, 0, 0},            /* 11 */
73125   };
73126 
73127   int rc = SQLITE_OK;
73128   char *zErr = 0;
73129   Table *pTab;
73130   Parse *pParse = 0;
73131   Incrblob *pBlob = 0;
73132 
73133   flags = !!flags;                /* flags = (flags ? 1 : 0); */
73134   *ppBlob = 0;
73135 
73136   sqlite3_mutex_enter(db->mutex);
73137 
73138   pBlob = (Incrblob *)sqlite3DbMallocZero(db, sizeof(Incrblob));
73139   if( !pBlob ) goto blob_open_out;
73140   pParse = sqlite3StackAllocRaw(db, sizeof(*pParse));
73141   if( !pParse ) goto blob_open_out;
73142 
73143   do {
73144     memset(pParse, 0, sizeof(Parse));
73145     pParse->db = db;
73146     sqlite3DbFree(db, zErr);
73147     zErr = 0;
73148 
73149     sqlite3BtreeEnterAll(db);
73150     pTab = sqlite3LocateTable(pParse, 0, zTable, zDb);
73151     if( pTab && IsVirtual(pTab) ){
73152       pTab = 0;
73153       sqlite3ErrorMsg(pParse, "cannot open virtual table: %s", zTable);
73154     }
73155     if( pTab && !HasRowid(pTab) ){
73156       pTab = 0;
73157       sqlite3ErrorMsg(pParse, "cannot open table without rowid: %s", zTable);
73158     }
73159 #ifndef SQLITE_OMIT_VIEW
73160     if( pTab && pTab->pSelect ){
73161       pTab = 0;
73162       sqlite3ErrorMsg(pParse, "cannot open view: %s", zTable);
73163     }
73164 #endif
73165     if( !pTab ){
73166       if( pParse->zErrMsg ){
73167         sqlite3DbFree(db, zErr);
73168         zErr = pParse->zErrMsg;
73169         pParse->zErrMsg = 0;
73170       }
73171       rc = SQLITE_ERROR;
73172       sqlite3BtreeLeaveAll(db);
73173       goto blob_open_out;
73174     }
73175 
73176     /* Now search pTab for the exact column. */
73177     for(iCol=0; iCol<pTab->nCol; iCol++) {
73178       if( sqlite3StrICmp(pTab->aCol[iCol].zName, zColumn)==0 ){
73179         break;
73180       }
73181     }
73182     if( iCol==pTab->nCol ){
73183       sqlite3DbFree(db, zErr);
73184       zErr = sqlite3MPrintf(db, "no such column: \"%s\"", zColumn);
73185       rc = SQLITE_ERROR;
73186       sqlite3BtreeLeaveAll(db);
73187       goto blob_open_out;
73188     }
73189 
73190     /* If the value is being opened for writing, check that the
73191     ** column is not indexed, and that it is not part of a foreign key. 
73192     ** It is against the rules to open a column to which either of these
73193     ** descriptions applies for writing.  */
73194     if( flags ){
73195       const char *zFault = 0;
73196       Index *pIdx;
73197 #ifndef SQLITE_OMIT_FOREIGN_KEY
73198       if( db->flags&SQLITE_ForeignKeys ){
73199         /* Check that the column is not part of an FK child key definition. It
73200         ** is not necessary to check if it is part of a parent key, as parent
73201         ** key columns must be indexed. The check below will pick up this 
73202         ** case.  */
73203         FKey *pFKey;
73204         for(pFKey=pTab->pFKey; pFKey; pFKey=pFKey->pNextFrom){
73205           int j;
73206           for(j=0; j<pFKey->nCol; j++){
73207             if( pFKey->aCol[j].iFrom==iCol ){
73208               zFault = "foreign key";
73209             }
73210           }
73211         }
73212       }
73213 #endif
73214       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
73215         int j;
73216         for(j=0; j<pIdx->nKeyCol; j++){
73217           if( pIdx->aiColumn[j]==iCol ){
73218             zFault = "indexed";
73219           }
73220         }
73221       }
73222       if( zFault ){
73223         sqlite3DbFree(db, zErr);
73224         zErr = sqlite3MPrintf(db, "cannot open %s column for writing", zFault);
73225         rc = SQLITE_ERROR;
73226         sqlite3BtreeLeaveAll(db);
73227         goto blob_open_out;
73228       }
73229     }
73230 
73231     pBlob->pStmt = (sqlite3_stmt *)sqlite3VdbeCreate(db);
73232     assert( pBlob->pStmt || db->mallocFailed );
73233     if( pBlob->pStmt ){
73234       Vdbe *v = (Vdbe *)pBlob->pStmt;
73235       int iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
73236 
73237       sqlite3VdbeAddOpList(v, sizeof(openBlob)/sizeof(VdbeOpList), openBlob);
73238 
73239 
73240       /* Configure the OP_Transaction */
73241       sqlite3VdbeChangeP1(v, 0, iDb);
73242       sqlite3VdbeChangeP2(v, 0, flags);
73243 
73244       /* Configure the OP_VerifyCookie */
73245       sqlite3VdbeChangeP1(v, 1, iDb);
73246       sqlite3VdbeChangeP2(v, 1, pTab->pSchema->schema_cookie);
73247       sqlite3VdbeChangeP3(v, 1, pTab->pSchema->iGeneration);
73248 
73249       /* Make sure a mutex is held on the table to be accessed */
73250       sqlite3VdbeUsesBtree(v, iDb); 
73251 
73252       /* Configure the OP_TableLock instruction */
73253 #ifdef SQLITE_OMIT_SHARED_CACHE
73254       sqlite3VdbeChangeToNoop(v, 2);
73255 #else
73256       sqlite3VdbeChangeP1(v, 2, iDb);
73257       sqlite3VdbeChangeP2(v, 2, pTab->tnum);
73258       sqlite3VdbeChangeP3(v, 2, flags);
73259       sqlite3VdbeChangeP4(v, 2, pTab->zName, P4_TRANSIENT);
73260 #endif
73261 
73262       /* Remove either the OP_OpenWrite or OpenRead. Set the P2 
73263       ** parameter of the other to pTab->tnum.  */
73264       sqlite3VdbeChangeToNoop(v, 4 - flags);
73265       sqlite3VdbeChangeP2(v, 3 + flags, pTab->tnum);
73266       sqlite3VdbeChangeP3(v, 3 + flags, iDb);
73267 
73268       /* Configure the number of columns. Configure the cursor to
73269       ** think that the table has one more column than it really
73270       ** does. An OP_Column to retrieve this imaginary column will
73271       ** always return an SQL NULL. This is useful because it means
73272       ** we can invoke OP_Column to fill in the vdbe cursors type 
73273       ** and offset cache without causing any IO.
73274       */
73275       sqlite3VdbeChangeP4(v, 3+flags, SQLITE_INT_TO_PTR(pTab->nCol+1),P4_INT32);
73276       sqlite3VdbeChangeP2(v, 7, pTab->nCol);
73277       if( !db->mallocFailed ){
73278         pParse->nVar = 1;
73279         pParse->nMem = 1;
73280         pParse->nTab = 1;
73281         sqlite3VdbeMakeReady(v, pParse);
73282       }
73283     }
73284    
73285     pBlob->flags = flags;
73286     pBlob->iCol = iCol;
73287     pBlob->db = db;
73288     sqlite3BtreeLeaveAll(db);
73289     if( db->mallocFailed ){
73290       goto blob_open_out;
73291     }
73292     sqlite3_bind_int64(pBlob->pStmt, 1, iRow);
73293     rc = blobSeekToRow(pBlob, iRow, &zErr);
73294   } while( (++nAttempt)<SQLITE_MAX_SCHEMA_RETRY && rc==SQLITE_SCHEMA );
73295 
73296 blob_open_out:
73297   if( rc==SQLITE_OK && db->mallocFailed==0 ){
73298     *ppBlob = (sqlite3_blob *)pBlob;
73299   }else{
73300     if( pBlob && pBlob->pStmt ) sqlite3VdbeFinalize((Vdbe *)pBlob->pStmt);
73301     sqlite3DbFree(db, pBlob);
73302   }
73303   sqlite3Error(db, rc, (zErr ? "%s" : 0), zErr);
73304   sqlite3DbFree(db, zErr);
73305   sqlite3ParserReset(pParse);
73306   sqlite3StackFree(db, pParse);
73307   rc = sqlite3ApiExit(db, rc);
73308   sqlite3_mutex_leave(db->mutex);
73309   return rc;
73310 }
73311 
73312 /*
73313 ** Close a blob handle that was previously created using
73314 ** sqlite3_blob_open().
73315 */
73316 SQLITE_API int sqlite3_blob_close(sqlite3_blob *pBlob){
73317   Incrblob *p = (Incrblob *)pBlob;
73318   int rc;
73319   sqlite3 *db;
73320 
73321   if( p ){
73322     db = p->db;
73323     sqlite3_mutex_enter(db->mutex);
73324     rc = sqlite3_finalize(p->pStmt);
73325     sqlite3DbFree(db, p);
73326     sqlite3_mutex_leave(db->mutex);
73327   }else{
73328     rc = SQLITE_OK;
73329   }
73330   return rc;
73331 }
73332 
73333 /*
73334 ** Perform a read or write operation on a blob
73335 */
73336 static int blobReadWrite(
73337   sqlite3_blob *pBlob, 
73338   void *z, 
73339   int n, 
73340   int iOffset, 
73341   int (*xCall)(BtCursor*, u32, u32, void*)
73342 ){
73343   int rc;
73344   Incrblob *p = (Incrblob *)pBlob;
73345   Vdbe *v;
73346   sqlite3 *db;
73347 
73348   if( p==0 ) return SQLITE_MISUSE_BKPT;
73349   db = p->db;
73350   sqlite3_mutex_enter(db->mutex);
73351   v = (Vdbe*)p->pStmt;
73352 
73353   if( n<0 || iOffset<0 || (iOffset+n)>p->nByte ){
73354     /* Request is out of range. Return a transient error. */
73355     rc = SQLITE_ERROR;
73356     sqlite3Error(db, SQLITE_ERROR, 0);
73357   }else if( v==0 ){
73358     /* If there is no statement handle, then the blob-handle has
73359     ** already been invalidated. Return SQLITE_ABORT in this case.
73360     */
73361     rc = SQLITE_ABORT;
73362   }else{
73363     /* Call either BtreeData() or BtreePutData(). If SQLITE_ABORT is
73364     ** returned, clean-up the statement handle.
73365     */
73366     assert( db == v->db );
73367     sqlite3BtreeEnterCursor(p->pCsr);
73368     rc = xCall(p->pCsr, iOffset+p->iOffset, n, z);
73369     sqlite3BtreeLeaveCursor(p->pCsr);
73370     if( rc==SQLITE_ABORT ){
73371       sqlite3VdbeFinalize(v);
73372       p->pStmt = 0;
73373     }else{
73374       db->errCode = rc;
73375       v->rc = rc;
73376     }
73377   }
73378   rc = sqlite3ApiExit(db, rc);
73379   sqlite3_mutex_leave(db->mutex);
73380   return rc;
73381 }
73382 
73383 /*
73384 ** Read data from a blob handle.
73385 */
73386 SQLITE_API int sqlite3_blob_read(sqlite3_blob *pBlob, void *z, int n, int iOffset){
73387   return blobReadWrite(pBlob, z, n, iOffset, sqlite3BtreeData);
73388 }
73389 
73390 /*
73391 ** Write data to a blob handle.
73392 */
73393 SQLITE_API int sqlite3_blob_write(sqlite3_blob *pBlob, const void *z, int n, int iOffset){
73394   return blobReadWrite(pBlob, (void *)z, n, iOffset, sqlite3BtreePutData);
73395 }
73396 
73397 /*
73398 ** Query a blob handle for the size of the data.
73399 **
73400 ** The Incrblob.nByte field is fixed for the lifetime of the Incrblob
73401 ** so no mutex is required for access.
73402 */
73403 SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *pBlob){
73404   Incrblob *p = (Incrblob *)pBlob;
73405   return (p && p->pStmt) ? p->nByte : 0;
73406 }
73407 
73408 /*
73409 ** Move an existing blob handle to point to a different row of the same
73410 ** database table.
73411 **
73412 ** If an error occurs, or if the specified row does not exist or does not
73413 ** contain a blob or text value, then an error code is returned and the
73414 ** database handle error code and message set. If this happens, then all 
73415 ** subsequent calls to sqlite3_blob_xxx() functions (except blob_close()) 
73416 ** immediately return SQLITE_ABORT.
73417 */
73418 SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *pBlob, sqlite3_int64 iRow){
73419   int rc;
73420   Incrblob *p = (Incrblob *)pBlob;
73421   sqlite3 *db;
73422 
73423   if( p==0 ) return SQLITE_MISUSE_BKPT;
73424   db = p->db;
73425   sqlite3_mutex_enter(db->mutex);
73426 
73427   if( p->pStmt==0 ){
73428     /* If there is no statement handle, then the blob-handle has
73429     ** already been invalidated. Return SQLITE_ABORT in this case.
73430     */
73431     rc = SQLITE_ABORT;
73432   }else{
73433     char *zErr;
73434     rc = blobSeekToRow(p, iRow, &zErr);
73435     if( rc!=SQLITE_OK ){
73436       sqlite3Error(db, rc, (zErr ? "%s" : 0), zErr);
73437       sqlite3DbFree(db, zErr);
73438     }
73439     assert( rc!=SQLITE_SCHEMA );
73440   }
73441 
73442   rc = sqlite3ApiExit(db, rc);
73443   assert( rc==SQLITE_OK || p->pStmt==0 );
73444   sqlite3_mutex_leave(db->mutex);
73445   return rc;
73446 }
73447 
73448 #endif /* #ifndef SQLITE_OMIT_INCRBLOB */
73449 
73450 /************** End of vdbeblob.c ********************************************/
73451 /************** Begin file vdbesort.c ****************************************/
73452 /*
73453 ** 2011 July 9
73454 **
73455 ** The author disclaims copyright to this source code.  In place of
73456 ** a legal notice, here is a blessing:
73457 **
73458 **    May you do good and not evil.
73459 **    May you find forgiveness for yourself and forgive others.
73460 **    May you share freely, never taking more than you give.
73461 **
73462 *************************************************************************
73463 ** This file contains code for the VdbeSorter object, used in concert with
73464 ** a VdbeCursor to sort large numbers of keys (as may be required, for
73465 ** example, by CREATE INDEX statements on tables too large to fit in main
73466 ** memory).
73467 */
73468 
73469 
73470 
73471 typedef struct VdbeSorterIter VdbeSorterIter;
73472 typedef struct SorterRecord SorterRecord;
73473 typedef struct FileWriter FileWriter;
73474 
73475 /*
73476 ** NOTES ON DATA STRUCTURE USED FOR N-WAY MERGES:
73477 **
73478 ** As keys are added to the sorter, they are written to disk in a series
73479 ** of sorted packed-memory-arrays (PMAs). The size of each PMA is roughly
73480 ** the same as the cache-size allowed for temporary databases. In order
73481 ** to allow the caller to extract keys from the sorter in sorted order,
73482 ** all PMAs currently stored on disk must be merged together. This comment
73483 ** describes the data structure used to do so. The structure supports 
73484 ** merging any number of arrays in a single pass with no redundant comparison 
73485 ** operations.
73486 **
73487 ** The aIter[] array contains an iterator for each of the PMAs being merged.
73488 ** An aIter[] iterator either points to a valid key or else is at EOF. For 
73489 ** the purposes of the paragraphs below, we assume that the array is actually 
73490 ** N elements in size, where N is the smallest power of 2 greater to or equal 
73491 ** to the number of iterators being merged. The extra aIter[] elements are 
73492 ** treated as if they are empty (always at EOF).
73493 **
73494 ** The aTree[] array is also N elements in size. The value of N is stored in
73495 ** the VdbeSorter.nTree variable.
73496 **
73497 ** The final (N/2) elements of aTree[] contain the results of comparing
73498 ** pairs of iterator keys together. Element i contains the result of 
73499 ** comparing aIter[2*i-N] and aIter[2*i-N+1]. Whichever key is smaller, the
73500 ** aTree element is set to the index of it. 
73501 **
73502 ** For the purposes of this comparison, EOF is considered greater than any
73503 ** other key value. If the keys are equal (only possible with two EOF
73504 ** values), it doesn't matter which index is stored.
73505 **
73506 ** The (N/4) elements of aTree[] that precede the final (N/2) described 
73507 ** above contains the index of the smallest of each block of 4 iterators.
73508 ** And so on. So that aTree[1] contains the index of the iterator that 
73509 ** currently points to the smallest key value. aTree[0] is unused.
73510 **
73511 ** Example:
73512 **
73513 **     aIter[0] -> Banana
73514 **     aIter[1] -> Feijoa
73515 **     aIter[2] -> Elderberry
73516 **     aIter[3] -> Currant
73517 **     aIter[4] -> Grapefruit
73518 **     aIter[5] -> Apple
73519 **     aIter[6] -> Durian
73520 **     aIter[7] -> EOF
73521 **
73522 **     aTree[] = { X, 5   0, 5    0, 3, 5, 6 }
73523 **
73524 ** The current element is "Apple" (the value of the key indicated by 
73525 ** iterator 5). When the Next() operation is invoked, iterator 5 will
73526 ** be advanced to the next key in its segment. Say the next key is
73527 ** "Eggplant":
73528 **
73529 **     aIter[5] -> Eggplant
73530 **
73531 ** The contents of aTree[] are updated first by comparing the new iterator
73532 ** 5 key to the current key of iterator 4 (still "Grapefruit"). The iterator
73533 ** 5 value is still smaller, so aTree[6] is set to 5. And so on up the tree.
73534 ** The value of iterator 6 - "Durian" - is now smaller than that of iterator
73535 ** 5, so aTree[3] is set to 6. Key 0 is smaller than key 6 (Banana<Durian),
73536 ** so the value written into element 1 of the array is 0. As follows:
73537 **
73538 **     aTree[] = { X, 0   0, 6    0, 3, 5, 6 }
73539 **
73540 ** In other words, each time we advance to the next sorter element, log2(N)
73541 ** key comparison operations are required, where N is the number of segments
73542 ** being merged (rounded up to the next power of 2).
73543 */
73544 struct VdbeSorter {
73545   i64 iWriteOff;                  /* Current write offset within file pTemp1 */
73546   i64 iReadOff;                   /* Current read offset within file pTemp1 */
73547   int nInMemory;                  /* Current size of pRecord list as PMA */
73548   int nTree;                      /* Used size of aTree/aIter (power of 2) */
73549   int nPMA;                       /* Number of PMAs stored in pTemp1 */
73550   int mnPmaSize;                  /* Minimum PMA size, in bytes */
73551   int mxPmaSize;                  /* Maximum PMA size, in bytes.  0==no limit */
73552   VdbeSorterIter *aIter;          /* Array of iterators to merge */
73553   int *aTree;                     /* Current state of incremental merge */
73554   sqlite3_file *pTemp1;           /* PMA file 1 */
73555   SorterRecord *pRecord;          /* Head of in-memory record list */
73556   UnpackedRecord *pUnpacked;      /* Used to unpack keys */
73557 };
73558 
73559 /*
73560 ** The following type is an iterator for a PMA. It caches the current key in 
73561 ** variables nKey/aKey. If the iterator is at EOF, pFile==0.
73562 */
73563 struct VdbeSorterIter {
73564   i64 iReadOff;                   /* Current read offset */
73565   i64 iEof;                       /* 1 byte past EOF for this iterator */
73566   int nAlloc;                     /* Bytes of space at aAlloc */
73567   int nKey;                       /* Number of bytes in key */
73568   sqlite3_file *pFile;            /* File iterator is reading from */
73569   u8 *aAlloc;                     /* Allocated space */
73570   u8 *aKey;                       /* Pointer to current key */
73571   u8 *aBuffer;                    /* Current read buffer */
73572   int nBuffer;                    /* Size of read buffer in bytes */
73573 };
73574 
73575 /*
73576 ** An instance of this structure is used to organize the stream of records
73577 ** being written to files by the merge-sort code into aligned, page-sized
73578 ** blocks.  Doing all I/O in aligned page-sized blocks helps I/O to go
73579 ** faster on many operating systems.
73580 */
73581 struct FileWriter {
73582   int eFWErr;                     /* Non-zero if in an error state */
73583   u8 *aBuffer;                    /* Pointer to write buffer */
73584   int nBuffer;                    /* Size of write buffer in bytes */
73585   int iBufStart;                  /* First byte of buffer to write */
73586   int iBufEnd;                    /* Last byte of buffer to write */
73587   i64 iWriteOff;                  /* Offset of start of buffer in file */
73588   sqlite3_file *pFile;            /* File to write to */
73589 };
73590 
73591 /*
73592 ** A structure to store a single record. All in-memory records are connected
73593 ** together into a linked list headed at VdbeSorter.pRecord using the 
73594 ** SorterRecord.pNext pointer.
73595 */
73596 struct SorterRecord {
73597   void *pVal;
73598   int nVal;
73599   SorterRecord *pNext;
73600 };
73601 
73602 /* Minimum allowable value for the VdbeSorter.nWorking variable */
73603 #define SORTER_MIN_WORKING 10
73604 
73605 /* Maximum number of segments to merge in a single pass. */
73606 #define SORTER_MAX_MERGE_COUNT 16
73607 
73608 /*
73609 ** Free all memory belonging to the VdbeSorterIter object passed as the second
73610 ** argument. All structure fields are set to zero before returning.
73611 */
73612 static void vdbeSorterIterZero(sqlite3 *db, VdbeSorterIter *pIter){
73613   sqlite3DbFree(db, pIter->aAlloc);
73614   sqlite3DbFree(db, pIter->aBuffer);
73615   memset(pIter, 0, sizeof(VdbeSorterIter));
73616 }
73617 
73618 /*
73619 ** Read nByte bytes of data from the stream of data iterated by object p.
73620 ** If successful, set *ppOut to point to a buffer containing the data
73621 ** and return SQLITE_OK. Otherwise, if an error occurs, return an SQLite
73622 ** error code.
73623 **
73624 ** The buffer indicated by *ppOut may only be considered valid until the
73625 ** next call to this function.
73626 */
73627 static int vdbeSorterIterRead(
73628   sqlite3 *db,                    /* Database handle (for malloc) */
73629   VdbeSorterIter *p,              /* Iterator */
73630   int nByte,                      /* Bytes of data to read */
73631   u8 **ppOut                      /* OUT: Pointer to buffer containing data */
73632 ){
73633   int iBuf;                       /* Offset within buffer to read from */
73634   int nAvail;                     /* Bytes of data available in buffer */
73635   assert( p->aBuffer );
73636 
73637   /* If there is no more data to be read from the buffer, read the next 
73638   ** p->nBuffer bytes of data from the file into it. Or, if there are less
73639   ** than p->nBuffer bytes remaining in the PMA, read all remaining data.  */
73640   iBuf = p->iReadOff % p->nBuffer;
73641   if( iBuf==0 ){
73642     int nRead;                    /* Bytes to read from disk */
73643     int rc;                       /* sqlite3OsRead() return code */
73644 
73645     /* Determine how many bytes of data to read. */
73646     if( (p->iEof - p->iReadOff) > (i64)p->nBuffer ){
73647       nRead = p->nBuffer;
73648     }else{
73649       nRead = (int)(p->iEof - p->iReadOff);
73650     }
73651     assert( nRead>0 );
73652 
73653     /* Read data from the file. Return early if an error occurs. */
73654     rc = sqlite3OsRead(p->pFile, p->aBuffer, nRead, p->iReadOff);
73655     assert( rc!=SQLITE_IOERR_SHORT_READ );
73656     if( rc!=SQLITE_OK ) return rc;
73657   }
73658   nAvail = p->nBuffer - iBuf; 
73659 
73660   if( nByte<=nAvail ){
73661     /* The requested data is available in the in-memory buffer. In this
73662     ** case there is no need to make a copy of the data, just return a 
73663     ** pointer into the buffer to the caller.  */
73664     *ppOut = &p->aBuffer[iBuf];
73665     p->iReadOff += nByte;
73666   }else{
73667     /* The requested data is not all available in the in-memory buffer.
73668     ** In this case, allocate space at p->aAlloc[] to copy the requested
73669     ** range into. Then return a copy of pointer p->aAlloc to the caller.  */
73670     int nRem;                     /* Bytes remaining to copy */
73671 
73672     /* Extend the p->aAlloc[] allocation if required. */
73673     if( p->nAlloc<nByte ){
73674       int nNew = p->nAlloc*2;
73675       while( nByte>nNew ) nNew = nNew*2;
73676       p->aAlloc = sqlite3DbReallocOrFree(db, p->aAlloc, nNew);
73677       if( !p->aAlloc ) return SQLITE_NOMEM;
73678       p->nAlloc = nNew;
73679     }
73680 
73681     /* Copy as much data as is available in the buffer into the start of
73682     ** p->aAlloc[].  */
73683     memcpy(p->aAlloc, &p->aBuffer[iBuf], nAvail);
73684     p->iReadOff += nAvail;
73685     nRem = nByte - nAvail;
73686 
73687     /* The following loop copies up to p->nBuffer bytes per iteration into
73688     ** the p->aAlloc[] buffer.  */
73689     while( nRem>0 ){
73690       int rc;                     /* vdbeSorterIterRead() return code */
73691       int nCopy;                  /* Number of bytes to copy */
73692       u8 *aNext;                  /* Pointer to buffer to copy data from */
73693 
73694       nCopy = nRem;
73695       if( nRem>p->nBuffer ) nCopy = p->nBuffer;
73696       rc = vdbeSorterIterRead(db, p, nCopy, &aNext);
73697       if( rc!=SQLITE_OK ) return rc;
73698       assert( aNext!=p->aAlloc );
73699       memcpy(&p->aAlloc[nByte - nRem], aNext, nCopy);
73700       nRem -= nCopy;
73701     }
73702 
73703     *ppOut = p->aAlloc;
73704   }
73705 
73706   return SQLITE_OK;
73707 }
73708 
73709 /*
73710 ** Read a varint from the stream of data accessed by p. Set *pnOut to
73711 ** the value read.
73712 */
73713 static int vdbeSorterIterVarint(sqlite3 *db, VdbeSorterIter *p, u64 *pnOut){
73714   int iBuf;
73715 
73716   iBuf = p->iReadOff % p->nBuffer;
73717   if( iBuf && (p->nBuffer-iBuf)>=9 ){
73718     p->iReadOff += sqlite3GetVarint(&p->aBuffer[iBuf], pnOut);
73719   }else{
73720     u8 aVarint[16], *a;
73721     int i = 0, rc;
73722     do{
73723       rc = vdbeSorterIterRead(db, p, 1, &a);
73724       if( rc ) return rc;
73725       aVarint[(i++)&0xf] = a[0];
73726     }while( (a[0]&0x80)!=0 );
73727     sqlite3GetVarint(aVarint, pnOut);
73728   }
73729 
73730   return SQLITE_OK;
73731 }
73732 
73733 
73734 /*
73735 ** Advance iterator pIter to the next key in its PMA. Return SQLITE_OK if
73736 ** no error occurs, or an SQLite error code if one does.
73737 */
73738 static int vdbeSorterIterNext(
73739   sqlite3 *db,                    /* Database handle (for sqlite3DbMalloc() ) */
73740   VdbeSorterIter *pIter           /* Iterator to advance */
73741 ){
73742   int rc;                         /* Return Code */
73743   u64 nRec = 0;                   /* Size of record in bytes */
73744 
73745   if( pIter->iReadOff>=pIter->iEof ){
73746     /* This is an EOF condition */
73747     vdbeSorterIterZero(db, pIter);
73748     return SQLITE_OK;
73749   }
73750 
73751   rc = vdbeSorterIterVarint(db, pIter, &nRec);
73752   if( rc==SQLITE_OK ){
73753     pIter->nKey = (int)nRec;
73754     rc = vdbeSorterIterRead(db, pIter, (int)nRec, &pIter->aKey);
73755   }
73756 
73757   return rc;
73758 }
73759 
73760 /*
73761 ** Initialize iterator pIter to scan through the PMA stored in file pFile
73762 ** starting at offset iStart and ending at offset iEof-1. This function 
73763 ** leaves the iterator pointing to the first key in the PMA (or EOF if the 
73764 ** PMA is empty).
73765 */
73766 static int vdbeSorterIterInit(
73767   sqlite3 *db,                    /* Database handle */
73768   const VdbeSorter *pSorter,      /* Sorter object */
73769   i64 iStart,                     /* Start offset in pFile */
73770   VdbeSorterIter *pIter,          /* Iterator to populate */
73771   i64 *pnByte                     /* IN/OUT: Increment this value by PMA size */
73772 ){
73773   int rc = SQLITE_OK;
73774   int nBuf;
73775 
73776   nBuf = sqlite3BtreeGetPageSize(db->aDb[0].pBt);
73777 
73778   assert( pSorter->iWriteOff>iStart );
73779   assert( pIter->aAlloc==0 );
73780   assert( pIter->aBuffer==0 );
73781   pIter->pFile = pSorter->pTemp1;
73782   pIter->iReadOff = iStart;
73783   pIter->nAlloc = 128;
73784   pIter->aAlloc = (u8 *)sqlite3DbMallocRaw(db, pIter->nAlloc);
73785   pIter->nBuffer = nBuf;
73786   pIter->aBuffer = (u8 *)sqlite3DbMallocRaw(db, nBuf);
73787 
73788   if( !pIter->aBuffer ){
73789     rc = SQLITE_NOMEM;
73790   }else{
73791     int iBuf;
73792 
73793     iBuf = iStart % nBuf;
73794     if( iBuf ){
73795       int nRead = nBuf - iBuf;
73796       if( (iStart + nRead) > pSorter->iWriteOff ){
73797         nRead = (int)(pSorter->iWriteOff - iStart);
73798       }
73799       rc = sqlite3OsRead(
73800           pSorter->pTemp1, &pIter->aBuffer[iBuf], nRead, iStart
73801       );
73802       assert( rc!=SQLITE_IOERR_SHORT_READ );
73803     }
73804 
73805     if( rc==SQLITE_OK ){
73806       u64 nByte;                       /* Size of PMA in bytes */
73807       pIter->iEof = pSorter->iWriteOff;
73808       rc = vdbeSorterIterVarint(db, pIter, &nByte);
73809       pIter->iEof = pIter->iReadOff + nByte;
73810       *pnByte += nByte;
73811     }
73812   }
73813 
73814   if( rc==SQLITE_OK ){
73815     rc = vdbeSorterIterNext(db, pIter);
73816   }
73817   return rc;
73818 }
73819 
73820 
73821 /*
73822 ** Compare key1 (buffer pKey1, size nKey1 bytes) with key2 (buffer pKey2, 
73823 ** size nKey2 bytes).  Argument pKeyInfo supplies the collation functions
73824 ** used by the comparison. If an error occurs, return an SQLite error code.
73825 ** Otherwise, return SQLITE_OK and set *pRes to a negative, zero or positive
73826 ** value, depending on whether key1 is smaller, equal to or larger than key2.
73827 **
73828 ** If the bOmitRowid argument is non-zero, assume both keys end in a rowid
73829 ** field. For the purposes of the comparison, ignore it. Also, if bOmitRowid
73830 ** is true and key1 contains even a single NULL value, it is considered to
73831 ** be less than key2. Even if key2 also contains NULL values.
73832 **
73833 ** If pKey2 is passed a NULL pointer, then it is assumed that the pCsr->aSpace
73834 ** has been allocated and contains an unpacked record that is used as key2.
73835 */
73836 static void vdbeSorterCompare(
73837   const VdbeCursor *pCsr,         /* Cursor object (for pKeyInfo) */
73838   int nIgnore,                    /* Ignore the last nIgnore fields */
73839   const void *pKey1, int nKey1,   /* Left side of comparison */
73840   const void *pKey2, int nKey2,   /* Right side of comparison */
73841   int *pRes                       /* OUT: Result of comparison */
73842 ){
73843   KeyInfo *pKeyInfo = pCsr->pKeyInfo;
73844   VdbeSorter *pSorter = pCsr->pSorter;
73845   UnpackedRecord *r2 = pSorter->pUnpacked;
73846   int i;
73847 
73848   if( pKey2 ){
73849     sqlite3VdbeRecordUnpack(pKeyInfo, nKey2, pKey2, r2);
73850   }
73851 
73852   if( nIgnore ){
73853     r2->nField = pKeyInfo->nField - nIgnore;
73854     assert( r2->nField>0 );
73855     for(i=0; i<r2->nField; i++){
73856       if( r2->aMem[i].flags & MEM_Null ){
73857         *pRes = -1;
73858         return;
73859       }
73860     }
73861     r2->flags |= UNPACKED_PREFIX_MATCH;
73862   }
73863 
73864   *pRes = sqlite3VdbeRecordCompare(nKey1, pKey1, r2);
73865 }
73866 
73867 /*
73868 ** This function is called to compare two iterator keys when merging 
73869 ** multiple b-tree segments. Parameter iOut is the index of the aTree[] 
73870 ** value to recalculate.
73871 */
73872 static int vdbeSorterDoCompare(const VdbeCursor *pCsr, int iOut){
73873   VdbeSorter *pSorter = pCsr->pSorter;
73874   int i1;
73875   int i2;
73876   int iRes;
73877   VdbeSorterIter *p1;
73878   VdbeSorterIter *p2;
73879 
73880   assert( iOut<pSorter->nTree && iOut>0 );
73881 
73882   if( iOut>=(pSorter->nTree/2) ){
73883     i1 = (iOut - pSorter->nTree/2) * 2;
73884     i2 = i1 + 1;
73885   }else{
73886     i1 = pSorter->aTree[iOut*2];
73887     i2 = pSorter->aTree[iOut*2+1];
73888   }
73889 
73890   p1 = &pSorter->aIter[i1];
73891   p2 = &pSorter->aIter[i2];
73892 
73893   if( p1->pFile==0 ){
73894     iRes = i2;
73895   }else if( p2->pFile==0 ){
73896     iRes = i1;
73897   }else{
73898     int res;
73899     assert( pCsr->pSorter->pUnpacked!=0 );  /* allocated in vdbeSorterMerge() */
73900     vdbeSorterCompare(
73901         pCsr, 0, p1->aKey, p1->nKey, p2->aKey, p2->nKey, &res
73902     );
73903     if( res<=0 ){
73904       iRes = i1;
73905     }else{
73906       iRes = i2;
73907     }
73908   }
73909 
73910   pSorter->aTree[iOut] = iRes;
73911   return SQLITE_OK;
73912 }
73913 
73914 /*
73915 ** Initialize the temporary index cursor just opened as a sorter cursor.
73916 */
73917 SQLITE_PRIVATE int sqlite3VdbeSorterInit(sqlite3 *db, VdbeCursor *pCsr){
73918   int pgsz;                       /* Page size of main database */
73919   int mxCache;                    /* Cache size */
73920   VdbeSorter *pSorter;            /* The new sorter */
73921   char *d;                        /* Dummy */
73922 
73923   assert( pCsr->pKeyInfo && pCsr->pBt==0 );
73924   pCsr->pSorter = pSorter = sqlite3DbMallocZero(db, sizeof(VdbeSorter));
73925   if( pSorter==0 ){
73926     return SQLITE_NOMEM;
73927   }
73928   
73929   pSorter->pUnpacked = sqlite3VdbeAllocUnpackedRecord(pCsr->pKeyInfo, 0, 0, &d);
73930   if( pSorter->pUnpacked==0 ) return SQLITE_NOMEM;
73931   assert( pSorter->pUnpacked==(UnpackedRecord *)d );
73932 
73933   if( !sqlite3TempInMemory(db) ){
73934     pgsz = sqlite3BtreeGetPageSize(db->aDb[0].pBt);
73935     pSorter->mnPmaSize = SORTER_MIN_WORKING * pgsz;
73936     mxCache = db->aDb[0].pSchema->cache_size;
73937     if( mxCache<SORTER_MIN_WORKING ) mxCache = SORTER_MIN_WORKING;
73938     pSorter->mxPmaSize = mxCache * pgsz;
73939   }
73940 
73941   return SQLITE_OK;
73942 }
73943 
73944 /*
73945 ** Free the list of sorted records starting at pRecord.
73946 */
73947 static void vdbeSorterRecordFree(sqlite3 *db, SorterRecord *pRecord){
73948   SorterRecord *p;
73949   SorterRecord *pNext;
73950   for(p=pRecord; p; p=pNext){
73951     pNext = p->pNext;
73952     sqlite3DbFree(db, p);
73953   }
73954 }
73955 
73956 /*
73957 ** Free any cursor components allocated by sqlite3VdbeSorterXXX routines.
73958 */
73959 SQLITE_PRIVATE void sqlite3VdbeSorterClose(sqlite3 *db, VdbeCursor *pCsr){
73960   VdbeSorter *pSorter = pCsr->pSorter;
73961   if( pSorter ){
73962     if( pSorter->aIter ){
73963       int i;
73964       for(i=0; i<pSorter->nTree; i++){
73965         vdbeSorterIterZero(db, &pSorter->aIter[i]);
73966       }
73967       sqlite3DbFree(db, pSorter->aIter);
73968     }
73969     if( pSorter->pTemp1 ){
73970       sqlite3OsCloseFree(pSorter->pTemp1);
73971     }
73972     vdbeSorterRecordFree(db, pSorter->pRecord);
73973     sqlite3DbFree(db, pSorter->pUnpacked);
73974     sqlite3DbFree(db, pSorter);
73975     pCsr->pSorter = 0;
73976   }
73977 }
73978 
73979 /*
73980 ** Allocate space for a file-handle and open a temporary file. If successful,
73981 ** set *ppFile to point to the malloc'd file-handle and return SQLITE_OK.
73982 ** Otherwise, set *ppFile to 0 and return an SQLite error code.
73983 */
73984 static int vdbeSorterOpenTempFile(sqlite3 *db, sqlite3_file **ppFile){
73985   int dummy;
73986   return sqlite3OsOpenMalloc(db->pVfs, 0, ppFile,
73987       SQLITE_OPEN_TEMP_JOURNAL |
73988       SQLITE_OPEN_READWRITE    | SQLITE_OPEN_CREATE |
73989       SQLITE_OPEN_EXCLUSIVE    | SQLITE_OPEN_DELETEONCLOSE, &dummy
73990   );
73991 }
73992 
73993 /*
73994 ** Merge the two sorted lists p1 and p2 into a single list.
73995 ** Set *ppOut to the head of the new list.
73996 */
73997 static void vdbeSorterMerge(
73998   const VdbeCursor *pCsr,         /* For pKeyInfo */
73999   SorterRecord *p1,               /* First list to merge */
74000   SorterRecord *p2,               /* Second list to merge */
74001   SorterRecord **ppOut            /* OUT: Head of merged list */
74002 ){
74003   SorterRecord *pFinal = 0;
74004   SorterRecord **pp = &pFinal;
74005   void *pVal2 = p2 ? p2->pVal : 0;
74006 
74007   while( p1 && p2 ){
74008     int res;
74009     vdbeSorterCompare(pCsr, 0, p1->pVal, p1->nVal, pVal2, p2->nVal, &res);
74010     if( res<=0 ){
74011       *pp = p1;
74012       pp = &p1->pNext;
74013       p1 = p1->pNext;
74014       pVal2 = 0;
74015     }else{
74016       *pp = p2;
74017        pp = &p2->pNext;
74018       p2 = p2->pNext;
74019       if( p2==0 ) break;
74020       pVal2 = p2->pVal;
74021     }
74022   }
74023   *pp = p1 ? p1 : p2;
74024   *ppOut = pFinal;
74025 }
74026 
74027 /*
74028 ** Sort the linked list of records headed at pCsr->pRecord. Return SQLITE_OK
74029 ** if successful, or an SQLite error code (i.e. SQLITE_NOMEM) if an error
74030 ** occurs.
74031 */
74032 static int vdbeSorterSort(const VdbeCursor *pCsr){
74033   int i;
74034   SorterRecord **aSlot;
74035   SorterRecord *p;
74036   VdbeSorter *pSorter = pCsr->pSorter;
74037 
74038   aSlot = (SorterRecord **)sqlite3MallocZero(64 * sizeof(SorterRecord *));
74039   if( !aSlot ){
74040     return SQLITE_NOMEM;
74041   }
74042 
74043   p = pSorter->pRecord;
74044   while( p ){
74045     SorterRecord *pNext = p->pNext;
74046     p->pNext = 0;
74047     for(i=0; aSlot[i]; i++){
74048       vdbeSorterMerge(pCsr, p, aSlot[i], &p);
74049       aSlot[i] = 0;
74050     }
74051     aSlot[i] = p;
74052     p = pNext;
74053   }
74054 
74055   p = 0;
74056   for(i=0; i<64; i++){
74057     vdbeSorterMerge(pCsr, p, aSlot[i], &p);
74058   }
74059   pSorter->pRecord = p;
74060 
74061   sqlite3_free(aSlot);
74062   return SQLITE_OK;
74063 }
74064 
74065 /*
74066 ** Initialize a file-writer object.
74067 */
74068 static void fileWriterInit(
74069   sqlite3 *db,                    /* Database (for malloc) */
74070   sqlite3_file *pFile,            /* File to write to */
74071   FileWriter *p,                  /* Object to populate */
74072   i64 iStart                      /* Offset of pFile to begin writing at */
74073 ){
74074   int nBuf = sqlite3BtreeGetPageSize(db->aDb[0].pBt);
74075 
74076   memset(p, 0, sizeof(FileWriter));
74077   p->aBuffer = (u8 *)sqlite3DbMallocRaw(db, nBuf);
74078   if( !p->aBuffer ){
74079     p->eFWErr = SQLITE_NOMEM;
74080   }else{
74081     p->iBufEnd = p->iBufStart = (iStart % nBuf);
74082     p->iWriteOff = iStart - p->iBufStart;
74083     p->nBuffer = nBuf;
74084     p->pFile = pFile;
74085   }
74086 }
74087 
74088 /*
74089 ** Write nData bytes of data to the file-write object. Return SQLITE_OK
74090 ** if successful, or an SQLite error code if an error occurs.
74091 */
74092 static void fileWriterWrite(FileWriter *p, u8 *pData, int nData){
74093   int nRem = nData;
74094   while( nRem>0 && p->eFWErr==0 ){
74095     int nCopy = nRem;
74096     if( nCopy>(p->nBuffer - p->iBufEnd) ){
74097       nCopy = p->nBuffer - p->iBufEnd;
74098     }
74099 
74100     memcpy(&p->aBuffer[p->iBufEnd], &pData[nData-nRem], nCopy);
74101     p->iBufEnd += nCopy;
74102     if( p->iBufEnd==p->nBuffer ){
74103       p->eFWErr = sqlite3OsWrite(p->pFile, 
74104           &p->aBuffer[p->iBufStart], p->iBufEnd - p->iBufStart, 
74105           p->iWriteOff + p->iBufStart
74106       );
74107       p->iBufStart = p->iBufEnd = 0;
74108       p->iWriteOff += p->nBuffer;
74109     }
74110     assert( p->iBufEnd<p->nBuffer );
74111 
74112     nRem -= nCopy;
74113   }
74114 }
74115 
74116 /*
74117 ** Flush any buffered data to disk and clean up the file-writer object.
74118 ** The results of using the file-writer after this call are undefined.
74119 ** Return SQLITE_OK if flushing the buffered data succeeds or is not 
74120 ** required. Otherwise, return an SQLite error code.
74121 **
74122 ** Before returning, set *piEof to the offset immediately following the
74123 ** last byte written to the file.
74124 */
74125 static int fileWriterFinish(sqlite3 *db, FileWriter *p, i64 *piEof){
74126   int rc;
74127   if( p->eFWErr==0 && ALWAYS(p->aBuffer) && p->iBufEnd>p->iBufStart ){
74128     p->eFWErr = sqlite3OsWrite(p->pFile, 
74129         &p->aBuffer[p->iBufStart], p->iBufEnd - p->iBufStart, 
74130         p->iWriteOff + p->iBufStart
74131     );
74132   }
74133   *piEof = (p->iWriteOff + p->iBufEnd);
74134   sqlite3DbFree(db, p->aBuffer);
74135   rc = p->eFWErr;
74136   memset(p, 0, sizeof(FileWriter));
74137   return rc;
74138 }
74139 
74140 /*
74141 ** Write value iVal encoded as a varint to the file-write object. Return 
74142 ** SQLITE_OK if successful, or an SQLite error code if an error occurs.
74143 */
74144 static void fileWriterWriteVarint(FileWriter *p, u64 iVal){
74145   int nByte; 
74146   u8 aByte[10];
74147   nByte = sqlite3PutVarint(aByte, iVal);
74148   fileWriterWrite(p, aByte, nByte);
74149 }
74150 
74151 /*
74152 ** Write the current contents of the in-memory linked-list to a PMA. Return
74153 ** SQLITE_OK if successful, or an SQLite error code otherwise.
74154 **
74155 ** The format of a PMA is:
74156 **
74157 **     * A varint. This varint contains the total number of bytes of content
74158 **       in the PMA (not including the varint itself).
74159 **
74160 **     * One or more records packed end-to-end in order of ascending keys. 
74161 **       Each record consists of a varint followed by a blob of data (the 
74162 **       key). The varint is the number of bytes in the blob of data.
74163 */
74164 static int vdbeSorterListToPMA(sqlite3 *db, const VdbeCursor *pCsr){
74165   int rc = SQLITE_OK;             /* Return code */
74166   VdbeSorter *pSorter = pCsr->pSorter;
74167   FileWriter writer;
74168 
74169   memset(&writer, 0, sizeof(FileWriter));
74170 
74171   if( pSorter->nInMemory==0 ){
74172     assert( pSorter->pRecord==0 );
74173     return rc;
74174   }
74175 
74176   rc = vdbeSorterSort(pCsr);
74177 
74178   /* If the first temporary PMA file has not been opened, open it now. */
74179   if( rc==SQLITE_OK && pSorter->pTemp1==0 ){
74180     rc = vdbeSorterOpenTempFile(db, &pSorter->pTemp1);
74181     assert( rc!=SQLITE_OK || pSorter->pTemp1 );
74182     assert( pSorter->iWriteOff==0 );
74183     assert( pSorter->nPMA==0 );
74184   }
74185 
74186   if( rc==SQLITE_OK ){
74187     SorterRecord *p;
74188     SorterRecord *pNext = 0;
74189 
74190     fileWriterInit(db, pSorter->pTemp1, &writer, pSorter->iWriteOff);
74191     pSorter->nPMA++;
74192     fileWriterWriteVarint(&writer, pSorter->nInMemory);
74193     for(p=pSorter->pRecord; p; p=pNext){
74194       pNext = p->pNext;
74195       fileWriterWriteVarint(&writer, p->nVal);
74196       fileWriterWrite(&writer, p->pVal, p->nVal);
74197       sqlite3DbFree(db, p);
74198     }
74199     pSorter->pRecord = p;
74200     rc = fileWriterFinish(db, &writer, &pSorter->iWriteOff);
74201   }
74202 
74203   return rc;
74204 }
74205 
74206 /*
74207 ** Add a record to the sorter.
74208 */
74209 SQLITE_PRIVATE int sqlite3VdbeSorterWrite(
74210   sqlite3 *db,                    /* Database handle */
74211   const VdbeCursor *pCsr,               /* Sorter cursor */
74212   Mem *pVal                       /* Memory cell containing record */
74213 ){
74214   VdbeSorter *pSorter = pCsr->pSorter;
74215   int rc = SQLITE_OK;             /* Return Code */
74216   SorterRecord *pNew;             /* New list element */
74217 
74218   assert( pSorter );
74219   pSorter->nInMemory += sqlite3VarintLen(pVal->n) + pVal->n;
74220 
74221   pNew = (SorterRecord *)sqlite3DbMallocRaw(db, pVal->n + sizeof(SorterRecord));
74222   if( pNew==0 ){
74223     rc = SQLITE_NOMEM;
74224   }else{
74225     pNew->pVal = (void *)&pNew[1];
74226     memcpy(pNew->pVal, pVal->z, pVal->n);
74227     pNew->nVal = pVal->n;
74228     pNew->pNext = pSorter->pRecord;
74229     pSorter->pRecord = pNew;
74230   }
74231 
74232   /* See if the contents of the sorter should now be written out. They
74233   ** are written out when either of the following are true:
74234   **
74235   **   * The total memory allocated for the in-memory list is greater 
74236   **     than (page-size * cache-size), or
74237   **
74238   **   * The total memory allocated for the in-memory list is greater 
74239   **     than (page-size * 10) and sqlite3HeapNearlyFull() returns true.
74240   */
74241   if( rc==SQLITE_OK && pSorter->mxPmaSize>0 && (
74242         (pSorter->nInMemory>pSorter->mxPmaSize)
74243      || (pSorter->nInMemory>pSorter->mnPmaSize && sqlite3HeapNearlyFull())
74244   )){
74245 #ifdef SQLITE_DEBUG
74246     i64 nExpect = pSorter->iWriteOff
74247                 + sqlite3VarintLen(pSorter->nInMemory)
74248                 + pSorter->nInMemory;
74249 #endif
74250     rc = vdbeSorterListToPMA(db, pCsr);
74251     pSorter->nInMemory = 0;
74252     assert( rc!=SQLITE_OK || (nExpect==pSorter->iWriteOff) );
74253   }
74254 
74255   return rc;
74256 }
74257 
74258 /*
74259 ** Helper function for sqlite3VdbeSorterRewind(). 
74260 */
74261 static int vdbeSorterInitMerge(
74262   sqlite3 *db,                    /* Database handle */
74263   const VdbeCursor *pCsr,         /* Cursor handle for this sorter */
74264   i64 *pnByte                     /* Sum of bytes in all opened PMAs */
74265 ){
74266   VdbeSorter *pSorter = pCsr->pSorter;
74267   int rc = SQLITE_OK;             /* Return code */
74268   int i;                          /* Used to iterator through aIter[] */
74269   i64 nByte = 0;                  /* Total bytes in all opened PMAs */
74270 
74271   /* Initialize the iterators. */
74272   for(i=0; i<SORTER_MAX_MERGE_COUNT; i++){
74273     VdbeSorterIter *pIter = &pSorter->aIter[i];
74274     rc = vdbeSorterIterInit(db, pSorter, pSorter->iReadOff, pIter, &nByte);
74275     pSorter->iReadOff = pIter->iEof;
74276     assert( rc!=SQLITE_OK || pSorter->iReadOff<=pSorter->iWriteOff );
74277     if( rc!=SQLITE_OK || pSorter->iReadOff>=pSorter->iWriteOff ) break;
74278   }
74279 
74280   /* Initialize the aTree[] array. */
74281   for(i=pSorter->nTree-1; rc==SQLITE_OK && i>0; i--){
74282     rc = vdbeSorterDoCompare(pCsr, i);
74283   }
74284 
74285   *pnByte = nByte;
74286   return rc;
74287 }
74288 
74289 /*
74290 ** Once the sorter has been populated, this function is called to prepare
74291 ** for iterating through its contents in sorted order.
74292 */
74293 SQLITE_PRIVATE int sqlite3VdbeSorterRewind(sqlite3 *db, const VdbeCursor *pCsr, int *pbEof){
74294   VdbeSorter *pSorter = pCsr->pSorter;
74295   int rc;                         /* Return code */
74296   sqlite3_file *pTemp2 = 0;       /* Second temp file to use */
74297   i64 iWrite2 = 0;                /* Write offset for pTemp2 */
74298   int nIter;                      /* Number of iterators used */
74299   int nByte;                      /* Bytes of space required for aIter/aTree */
74300   int N = 2;                      /* Power of 2 >= nIter */
74301 
74302   assert( pSorter );
74303 
74304   /* If no data has been written to disk, then do not do so now. Instead,
74305   ** sort the VdbeSorter.pRecord list. The vdbe layer will read data directly
74306   ** from the in-memory list.  */
74307   if( pSorter->nPMA==0 ){
74308     *pbEof = !pSorter->pRecord;
74309     assert( pSorter->aTree==0 );
74310     return vdbeSorterSort(pCsr);
74311   }
74312 
74313   /* Write the current in-memory list to a PMA. */
74314   rc = vdbeSorterListToPMA(db, pCsr);
74315   if( rc!=SQLITE_OK ) return rc;
74316 
74317   /* Allocate space for aIter[] and aTree[]. */
74318   nIter = pSorter->nPMA;
74319   if( nIter>SORTER_MAX_MERGE_COUNT ) nIter = SORTER_MAX_MERGE_COUNT;
74320   assert( nIter>0 );
74321   while( N<nIter ) N += N;
74322   nByte = N * (sizeof(int) + sizeof(VdbeSorterIter));
74323   pSorter->aIter = (VdbeSorterIter *)sqlite3DbMallocZero(db, nByte);
74324   if( !pSorter->aIter ) return SQLITE_NOMEM;
74325   pSorter->aTree = (int *)&pSorter->aIter[N];
74326   pSorter->nTree = N;
74327 
74328   do {
74329     int iNew;                     /* Index of new, merged, PMA */
74330 
74331     for(iNew=0; 
74332         rc==SQLITE_OK && iNew*SORTER_MAX_MERGE_COUNT<pSorter->nPMA; 
74333         iNew++
74334     ){
74335       int rc2;                    /* Return code from fileWriterFinish() */
74336       FileWriter writer;          /* Object used to write to disk */
74337       i64 nWrite;                 /* Number of bytes in new PMA */
74338 
74339       memset(&writer, 0, sizeof(FileWriter));
74340 
74341       /* If there are SORTER_MAX_MERGE_COUNT or less PMAs in file pTemp1,
74342       ** initialize an iterator for each of them and break out of the loop.
74343       ** These iterators will be incrementally merged as the VDBE layer calls
74344       ** sqlite3VdbeSorterNext().
74345       **
74346       ** Otherwise, if pTemp1 contains more than SORTER_MAX_MERGE_COUNT PMAs,
74347       ** initialize interators for SORTER_MAX_MERGE_COUNT of them. These PMAs
74348       ** are merged into a single PMA that is written to file pTemp2.
74349       */
74350       rc = vdbeSorterInitMerge(db, pCsr, &nWrite);
74351       assert( rc!=SQLITE_OK || pSorter->aIter[ pSorter->aTree[1] ].pFile );
74352       if( rc!=SQLITE_OK || pSorter->nPMA<=SORTER_MAX_MERGE_COUNT ){
74353         break;
74354       }
74355 
74356       /* Open the second temp file, if it is not already open. */
74357       if( pTemp2==0 ){
74358         assert( iWrite2==0 );
74359         rc = vdbeSorterOpenTempFile(db, &pTemp2);
74360       }
74361 
74362       if( rc==SQLITE_OK ){
74363         int bEof = 0;
74364         fileWriterInit(db, pTemp2, &writer, iWrite2);
74365         fileWriterWriteVarint(&writer, nWrite);
74366         while( rc==SQLITE_OK && bEof==0 ){
74367           VdbeSorterIter *pIter = &pSorter->aIter[ pSorter->aTree[1] ];
74368           assert( pIter->pFile );
74369 
74370           fileWriterWriteVarint(&writer, pIter->nKey);
74371           fileWriterWrite(&writer, pIter->aKey, pIter->nKey);
74372           rc = sqlite3VdbeSorterNext(db, pCsr, &bEof);
74373         }
74374         rc2 = fileWriterFinish(db, &writer, &iWrite2);
74375         if( rc==SQLITE_OK ) rc = rc2;
74376       }
74377     }
74378 
74379     if( pSorter->nPMA<=SORTER_MAX_MERGE_COUNT ){
74380       break;
74381     }else{
74382       sqlite3_file *pTmp = pSorter->pTemp1;
74383       pSorter->nPMA = iNew;
74384       pSorter->pTemp1 = pTemp2;
74385       pTemp2 = pTmp;
74386       pSorter->iWriteOff = iWrite2;
74387       pSorter->iReadOff = 0;
74388       iWrite2 = 0;
74389     }
74390   }while( rc==SQLITE_OK );
74391 
74392   if( pTemp2 ){
74393     sqlite3OsCloseFree(pTemp2);
74394   }
74395   *pbEof = (pSorter->aIter[pSorter->aTree[1]].pFile==0);
74396   return rc;
74397 }
74398 
74399 /*
74400 ** Advance to the next element in the sorter.
74401 */
74402 SQLITE_PRIVATE int sqlite3VdbeSorterNext(sqlite3 *db, const VdbeCursor *pCsr, int *pbEof){
74403   VdbeSorter *pSorter = pCsr->pSorter;
74404   int rc;                         /* Return code */
74405 
74406   if( pSorter->aTree ){
74407     int iPrev = pSorter->aTree[1];/* Index of iterator to advance */
74408     int i;                        /* Index of aTree[] to recalculate */
74409 
74410     rc = vdbeSorterIterNext(db, &pSorter->aIter[iPrev]);
74411     for(i=(pSorter->nTree+iPrev)/2; rc==SQLITE_OK && i>0; i=i/2){
74412       rc = vdbeSorterDoCompare(pCsr, i);
74413     }
74414 
74415     *pbEof = (pSorter->aIter[pSorter->aTree[1]].pFile==0);
74416   }else{
74417     SorterRecord *pFree = pSorter->pRecord;
74418     pSorter->pRecord = pFree->pNext;
74419     pFree->pNext = 0;
74420     vdbeSorterRecordFree(db, pFree);
74421     *pbEof = !pSorter->pRecord;
74422     rc = SQLITE_OK;
74423   }
74424   return rc;
74425 }
74426 
74427 /*
74428 ** Return a pointer to a buffer owned by the sorter that contains the 
74429 ** current key.
74430 */
74431 static void *vdbeSorterRowkey(
74432   const VdbeSorter *pSorter,      /* Sorter object */
74433   int *pnKey                      /* OUT: Size of current key in bytes */
74434 ){
74435   void *pKey;
74436   if( pSorter->aTree ){
74437     VdbeSorterIter *pIter;
74438     pIter = &pSorter->aIter[ pSorter->aTree[1] ];
74439     *pnKey = pIter->nKey;
74440     pKey = pIter->aKey;
74441   }else{
74442     *pnKey = pSorter->pRecord->nVal;
74443     pKey = pSorter->pRecord->pVal;
74444   }
74445   return pKey;
74446 }
74447 
74448 /*
74449 ** Copy the current sorter key into the memory cell pOut.
74450 */
74451 SQLITE_PRIVATE int sqlite3VdbeSorterRowkey(const VdbeCursor *pCsr, Mem *pOut){
74452   VdbeSorter *pSorter = pCsr->pSorter;
74453   void *pKey; int nKey;           /* Sorter key to copy into pOut */
74454 
74455   pKey = vdbeSorterRowkey(pSorter, &nKey);
74456   if( sqlite3VdbeMemGrow(pOut, nKey, 0) ){
74457     return SQLITE_NOMEM;
74458   }
74459   pOut->n = nKey;
74460   MemSetTypeFlag(pOut, MEM_Blob);
74461   memcpy(pOut->z, pKey, nKey);
74462 
74463   return SQLITE_OK;
74464 }
74465 
74466 /*
74467 ** Compare the key in memory cell pVal with the key that the sorter cursor
74468 ** passed as the first argument currently points to. For the purposes of
74469 ** the comparison, ignore the rowid field at the end of each record.
74470 **
74471 ** If an error occurs, return an SQLite error code (i.e. SQLITE_NOMEM).
74472 ** Otherwise, set *pRes to a negative, zero or positive value if the
74473 ** key in pVal is smaller than, equal to or larger than the current sorter
74474 ** key.
74475 */
74476 SQLITE_PRIVATE int sqlite3VdbeSorterCompare(
74477   const VdbeCursor *pCsr,         /* Sorter cursor */
74478   Mem *pVal,                      /* Value to compare to current sorter key */
74479   int nIgnore,                    /* Ignore this many fields at the end */
74480   int *pRes                       /* OUT: Result of comparison */
74481 ){
74482   VdbeSorter *pSorter = pCsr->pSorter;
74483   void *pKey; int nKey;           /* Sorter key to compare pVal with */
74484 
74485   pKey = vdbeSorterRowkey(pSorter, &nKey);
74486   vdbeSorterCompare(pCsr, nIgnore, pVal->z, pVal->n, pKey, nKey, pRes);
74487   return SQLITE_OK;
74488 }
74489 
74490 /************** End of vdbesort.c ********************************************/
74491 /************** Begin file journal.c *****************************************/
74492 /*
74493 ** 2007 August 22
74494 **
74495 ** The author disclaims copyright to this source code.  In place of
74496 ** a legal notice, here is a blessing:
74497 **
74498 **    May you do good and not evil.
74499 **    May you find forgiveness for yourself and forgive others.
74500 **    May you share freely, never taking more than you give.
74501 **
74502 *************************************************************************
74503 **
74504 ** This file implements a special kind of sqlite3_file object used
74505 ** by SQLite to create journal files if the atomic-write optimization
74506 ** is enabled.
74507 **
74508 ** The distinctive characteristic of this sqlite3_file is that the
74509 ** actual on disk file is created lazily. When the file is created,
74510 ** the caller specifies a buffer size for an in-memory buffer to
74511 ** be used to service read() and write() requests. The actual file
74512 ** on disk is not created or populated until either:
74513 **
74514 **   1) The in-memory representation grows too large for the allocated 
74515 **      buffer, or
74516 **   2) The sqlite3JournalCreate() function is called.
74517 */
74518 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
74519 
74520 
74521 /*
74522 ** A JournalFile object is a subclass of sqlite3_file used by
74523 ** as an open file handle for journal files.
74524 */
74525 struct JournalFile {
74526   sqlite3_io_methods *pMethod;    /* I/O methods on journal files */
74527   int nBuf;                       /* Size of zBuf[] in bytes */
74528   char *zBuf;                     /* Space to buffer journal writes */
74529   int iSize;                      /* Amount of zBuf[] currently used */
74530   int flags;                      /* xOpen flags */
74531   sqlite3_vfs *pVfs;              /* The "real" underlying VFS */
74532   sqlite3_file *pReal;            /* The "real" underlying file descriptor */
74533   const char *zJournal;           /* Name of the journal file */
74534 };
74535 typedef struct JournalFile JournalFile;
74536 
74537 /*
74538 ** If it does not already exists, create and populate the on-disk file 
74539 ** for JournalFile p.
74540 */
74541 static int createFile(JournalFile *p){
74542   int rc = SQLITE_OK;
74543   if( !p->pReal ){
74544     sqlite3_file *pReal = (sqlite3_file *)&p[1];
74545     rc = sqlite3OsOpen(p->pVfs, p->zJournal, pReal, p->flags, 0);
74546     if( rc==SQLITE_OK ){
74547       p->pReal = pReal;
74548       if( p->iSize>0 ){
74549         assert(p->iSize<=p->nBuf);
74550         rc = sqlite3OsWrite(p->pReal, p->zBuf, p->iSize, 0);
74551       }
74552       if( rc!=SQLITE_OK ){
74553         /* If an error occurred while writing to the file, close it before
74554         ** returning. This way, SQLite uses the in-memory journal data to 
74555         ** roll back changes made to the internal page-cache before this
74556         ** function was called.  */
74557         sqlite3OsClose(pReal);
74558         p->pReal = 0;
74559       }
74560     }
74561   }
74562   return rc;
74563 }
74564 
74565 /*
74566 ** Close the file.
74567 */
74568 static int jrnlClose(sqlite3_file *pJfd){
74569   JournalFile *p = (JournalFile *)pJfd;
74570   if( p->pReal ){
74571     sqlite3OsClose(p->pReal);
74572   }
74573   sqlite3_free(p->zBuf);
74574   return SQLITE_OK;
74575 }
74576 
74577 /*
74578 ** Read data from the file.
74579 */
74580 static int jrnlRead(
74581   sqlite3_file *pJfd,    /* The journal file from which to read */
74582   void *zBuf,            /* Put the results here */
74583   int iAmt,              /* Number of bytes to read */
74584   sqlite_int64 iOfst     /* Begin reading at this offset */
74585 ){
74586   int rc = SQLITE_OK;
74587   JournalFile *p = (JournalFile *)pJfd;
74588   if( p->pReal ){
74589     rc = sqlite3OsRead(p->pReal, zBuf, iAmt, iOfst);
74590   }else if( (iAmt+iOfst)>p->iSize ){
74591     rc = SQLITE_IOERR_SHORT_READ;
74592   }else{
74593     memcpy(zBuf, &p->zBuf[iOfst], iAmt);
74594   }
74595   return rc;
74596 }
74597 
74598 /*
74599 ** Write data to the file.
74600 */
74601 static int jrnlWrite(
74602   sqlite3_file *pJfd,    /* The journal file into which to write */
74603   const void *zBuf,      /* Take data to be written from here */
74604   int iAmt,              /* Number of bytes to write */
74605   sqlite_int64 iOfst     /* Begin writing at this offset into the file */
74606 ){
74607   int rc = SQLITE_OK;
74608   JournalFile *p = (JournalFile *)pJfd;
74609   if( !p->pReal && (iOfst+iAmt)>p->nBuf ){
74610     rc = createFile(p);
74611   }
74612   if( rc==SQLITE_OK ){
74613     if( p->pReal ){
74614       rc = sqlite3OsWrite(p->pReal, zBuf, iAmt, iOfst);
74615     }else{
74616       memcpy(&p->zBuf[iOfst], zBuf, iAmt);
74617       if( p->iSize<(iOfst+iAmt) ){
74618         p->iSize = (iOfst+iAmt);
74619       }
74620     }
74621   }
74622   return rc;
74623 }
74624 
74625 /*
74626 ** Truncate the file.
74627 */
74628 static int jrnlTruncate(sqlite3_file *pJfd, sqlite_int64 size){
74629   int rc = SQLITE_OK;
74630   JournalFile *p = (JournalFile *)pJfd;
74631   if( p->pReal ){
74632     rc = sqlite3OsTruncate(p->pReal, size);
74633   }else if( size<p->iSize ){
74634     p->iSize = size;
74635   }
74636   return rc;
74637 }
74638 
74639 /*
74640 ** Sync the file.
74641 */
74642 static int jrnlSync(sqlite3_file *pJfd, int flags){
74643   int rc;
74644   JournalFile *p = (JournalFile *)pJfd;
74645   if( p->pReal ){
74646     rc = sqlite3OsSync(p->pReal, flags);
74647   }else{
74648     rc = SQLITE_OK;
74649   }
74650   return rc;
74651 }
74652 
74653 /*
74654 ** Query the size of the file in bytes.
74655 */
74656 static int jrnlFileSize(sqlite3_file *pJfd, sqlite_int64 *pSize){
74657   int rc = SQLITE_OK;
74658   JournalFile *p = (JournalFile *)pJfd;
74659   if( p->pReal ){
74660     rc = sqlite3OsFileSize(p->pReal, pSize);
74661   }else{
74662     *pSize = (sqlite_int64) p->iSize;
74663   }
74664   return rc;
74665 }
74666 
74667 /*
74668 ** Table of methods for JournalFile sqlite3_file object.
74669 */
74670 static struct sqlite3_io_methods JournalFileMethods = {
74671   1,             /* iVersion */
74672   jrnlClose,     /* xClose */
74673   jrnlRead,      /* xRead */
74674   jrnlWrite,     /* xWrite */
74675   jrnlTruncate,  /* xTruncate */
74676   jrnlSync,      /* xSync */
74677   jrnlFileSize,  /* xFileSize */
74678   0,             /* xLock */
74679   0,             /* xUnlock */
74680   0,             /* xCheckReservedLock */
74681   0,             /* xFileControl */
74682   0,             /* xSectorSize */
74683   0,             /* xDeviceCharacteristics */
74684   0,             /* xShmMap */
74685   0,             /* xShmLock */
74686   0,             /* xShmBarrier */
74687   0              /* xShmUnmap */
74688 };
74689 
74690 /* 
74691 ** Open a journal file.
74692 */
74693 SQLITE_PRIVATE int sqlite3JournalOpen(
74694   sqlite3_vfs *pVfs,         /* The VFS to use for actual file I/O */
74695   const char *zName,         /* Name of the journal file */
74696   sqlite3_file *pJfd,        /* Preallocated, blank file handle */
74697   int flags,                 /* Opening flags */
74698   int nBuf                   /* Bytes buffered before opening the file */
74699 ){
74700   JournalFile *p = (JournalFile *)pJfd;
74701   memset(p, 0, sqlite3JournalSize(pVfs));
74702   if( nBuf>0 ){
74703     p->zBuf = sqlite3MallocZero(nBuf);
74704     if( !p->zBuf ){
74705       return SQLITE_NOMEM;
74706     }
74707   }else{
74708     return sqlite3OsOpen(pVfs, zName, pJfd, flags, 0);
74709   }
74710   p->pMethod = &JournalFileMethods;
74711   p->nBuf = nBuf;
74712   p->flags = flags;
74713   p->zJournal = zName;
74714   p->pVfs = pVfs;
74715   return SQLITE_OK;
74716 }
74717 
74718 /*
74719 ** If the argument p points to a JournalFile structure, and the underlying
74720 ** file has not yet been created, create it now.
74721 */
74722 SQLITE_PRIVATE int sqlite3JournalCreate(sqlite3_file *p){
74723   if( p->pMethods!=&JournalFileMethods ){
74724     return SQLITE_OK;
74725   }
74726   return createFile((JournalFile *)p);
74727 }
74728 
74729 /*
74730 ** The file-handle passed as the only argument is guaranteed to be an open
74731 ** file. It may or may not be of class JournalFile. If the file is a
74732 ** JournalFile, and the underlying file on disk has not yet been opened,
74733 ** return 0. Otherwise, return 1.
74734 */
74735 SQLITE_PRIVATE int sqlite3JournalExists(sqlite3_file *p){
74736   return (p->pMethods!=&JournalFileMethods || ((JournalFile *)p)->pReal!=0);
74737 }
74738 
74739 /* 
74740 ** Return the number of bytes required to store a JournalFile that uses vfs
74741 ** pVfs to create the underlying on-disk files.
74742 */
74743 SQLITE_PRIVATE int sqlite3JournalSize(sqlite3_vfs *pVfs){
74744   return (pVfs->szOsFile+sizeof(JournalFile));
74745 }
74746 #endif
74747 
74748 /************** End of journal.c *********************************************/
74749 /************** Begin file memjournal.c **************************************/
74750 /*
74751 ** 2008 October 7
74752 **
74753 ** The author disclaims copyright to this source code.  In place of
74754 ** a legal notice, here is a blessing:
74755 **
74756 **    May you do good and not evil.
74757 **    May you find forgiveness for yourself and forgive others.
74758 **    May you share freely, never taking more than you give.
74759 **
74760 *************************************************************************
74761 **
74762 ** This file contains code use to implement an in-memory rollback journal.
74763 ** The in-memory rollback journal is used to journal transactions for
74764 ** ":memory:" databases and when the journal_mode=MEMORY pragma is used.
74765 */
74766 
74767 /* Forward references to internal structures */
74768 typedef struct MemJournal MemJournal;
74769 typedef struct FilePoint FilePoint;
74770 typedef struct FileChunk FileChunk;
74771 
74772 /* Space to hold the rollback journal is allocated in increments of
74773 ** this many bytes.
74774 **
74775 ** The size chosen is a little less than a power of two.  That way,
74776 ** the FileChunk object will have a size that almost exactly fills
74777 ** a power-of-two allocation.  This mimimizes wasted space in power-of-two
74778 ** memory allocators.
74779 */
74780 #define JOURNAL_CHUNKSIZE ((int)(1024-sizeof(FileChunk*)))
74781 
74782 /*
74783 ** The rollback journal is composed of a linked list of these structures.
74784 */
74785 struct FileChunk {
74786   FileChunk *pNext;               /* Next chunk in the journal */
74787   u8 zChunk[JOURNAL_CHUNKSIZE];   /* Content of this chunk */
74788 };
74789 
74790 /*
74791 ** An instance of this object serves as a cursor into the rollback journal.
74792 ** The cursor can be either for reading or writing.
74793 */
74794 struct FilePoint {
74795   sqlite3_int64 iOffset;          /* Offset from the beginning of the file */
74796   FileChunk *pChunk;              /* Specific chunk into which cursor points */
74797 };
74798 
74799 /*
74800 ** This subclass is a subclass of sqlite3_file.  Each open memory-journal
74801 ** is an instance of this class.
74802 */
74803 struct MemJournal {
74804   sqlite3_io_methods *pMethod;    /* Parent class. MUST BE FIRST */
74805   FileChunk *pFirst;              /* Head of in-memory chunk-list */
74806   FilePoint endpoint;             /* Pointer to the end of the file */
74807   FilePoint readpoint;            /* Pointer to the end of the last xRead() */
74808 };
74809 
74810 /*
74811 ** Read data from the in-memory journal file.  This is the implementation
74812 ** of the sqlite3_vfs.xRead method.
74813 */
74814 static int memjrnlRead(
74815   sqlite3_file *pJfd,    /* The journal file from which to read */
74816   void *zBuf,            /* Put the results here */
74817   int iAmt,              /* Number of bytes to read */
74818   sqlite_int64 iOfst     /* Begin reading at this offset */
74819 ){
74820   MemJournal *p = (MemJournal *)pJfd;
74821   u8 *zOut = zBuf;
74822   int nRead = iAmt;
74823   int iChunkOffset;
74824   FileChunk *pChunk;
74825 
74826   /* SQLite never tries to read past the end of a rollback journal file */
74827   assert( iOfst+iAmt<=p->endpoint.iOffset );
74828 
74829   if( p->readpoint.iOffset!=iOfst || iOfst==0 ){
74830     sqlite3_int64 iOff = 0;
74831     for(pChunk=p->pFirst; 
74832         ALWAYS(pChunk) && (iOff+JOURNAL_CHUNKSIZE)<=iOfst;
74833         pChunk=pChunk->pNext
74834     ){
74835       iOff += JOURNAL_CHUNKSIZE;
74836     }
74837   }else{
74838     pChunk = p->readpoint.pChunk;
74839   }
74840 
74841   iChunkOffset = (int)(iOfst%JOURNAL_CHUNKSIZE);
74842   do {
74843     int iSpace = JOURNAL_CHUNKSIZE - iChunkOffset;
74844     int nCopy = MIN(nRead, (JOURNAL_CHUNKSIZE - iChunkOffset));
74845     memcpy(zOut, &pChunk->zChunk[iChunkOffset], nCopy);
74846     zOut += nCopy;
74847     nRead -= iSpace;
74848     iChunkOffset = 0;
74849   } while( nRead>=0 && (pChunk=pChunk->pNext)!=0 && nRead>0 );
74850   p->readpoint.iOffset = iOfst+iAmt;
74851   p->readpoint.pChunk = pChunk;
74852 
74853   return SQLITE_OK;
74854 }
74855 
74856 /*
74857 ** Write data to the file.
74858 */
74859 static int memjrnlWrite(
74860   sqlite3_file *pJfd,    /* The journal file into which to write */
74861   const void *zBuf,      /* Take data to be written from here */
74862   int iAmt,              /* Number of bytes to write */
74863   sqlite_int64 iOfst     /* Begin writing at this offset into the file */
74864 ){
74865   MemJournal *p = (MemJournal *)pJfd;
74866   int nWrite = iAmt;
74867   u8 *zWrite = (u8 *)zBuf;
74868 
74869   /* An in-memory journal file should only ever be appended to. Random
74870   ** access writes are not required by sqlite.
74871   */
74872   assert( iOfst==p->endpoint.iOffset );
74873   UNUSED_PARAMETER(iOfst);
74874 
74875   while( nWrite>0 ){
74876     FileChunk *pChunk = p->endpoint.pChunk;
74877     int iChunkOffset = (int)(p->endpoint.iOffset%JOURNAL_CHUNKSIZE);
74878     int iSpace = MIN(nWrite, JOURNAL_CHUNKSIZE - iChunkOffset);
74879 
74880     if( iChunkOffset==0 ){
74881       /* New chunk is required to extend the file. */
74882       FileChunk *pNew = sqlite3_malloc(sizeof(FileChunk));
74883       if( !pNew ){
74884         return SQLITE_IOERR_NOMEM;
74885       }
74886       pNew->pNext = 0;
74887       if( pChunk ){
74888         assert( p->pFirst );
74889         pChunk->pNext = pNew;
74890       }else{
74891         assert( !p->pFirst );
74892         p->pFirst = pNew;
74893       }
74894       p->endpoint.pChunk = pNew;
74895     }
74896 
74897     memcpy(&p->endpoint.pChunk->zChunk[iChunkOffset], zWrite, iSpace);
74898     zWrite += iSpace;
74899     nWrite -= iSpace;
74900     p->endpoint.iOffset += iSpace;
74901   }
74902 
74903   return SQLITE_OK;
74904 }
74905 
74906 /*
74907 ** Truncate the file.
74908 */
74909 static int memjrnlTruncate(sqlite3_file *pJfd, sqlite_int64 size){
74910   MemJournal *p = (MemJournal *)pJfd;
74911   FileChunk *pChunk;
74912   assert(size==0);
74913   UNUSED_PARAMETER(size);
74914   pChunk = p->pFirst;
74915   while( pChunk ){
74916     FileChunk *pTmp = pChunk;
74917     pChunk = pChunk->pNext;
74918     sqlite3_free(pTmp);
74919   }
74920   sqlite3MemJournalOpen(pJfd);
74921   return SQLITE_OK;
74922 }
74923 
74924 /*
74925 ** Close the file.
74926 */
74927 static int memjrnlClose(sqlite3_file *pJfd){
74928   memjrnlTruncate(pJfd, 0);
74929   return SQLITE_OK;
74930 }
74931 
74932 
74933 /*
74934 ** Sync the file.
74935 **
74936 ** Syncing an in-memory journal is a no-op.  And, in fact, this routine
74937 ** is never called in a working implementation.  This implementation
74938 ** exists purely as a contingency, in case some malfunction in some other
74939 ** part of SQLite causes Sync to be called by mistake.
74940 */
74941 static int memjrnlSync(sqlite3_file *NotUsed, int NotUsed2){
74942   UNUSED_PARAMETER2(NotUsed, NotUsed2);
74943   return SQLITE_OK;
74944 }
74945 
74946 /*
74947 ** Query the size of the file in bytes.
74948 */
74949 static int memjrnlFileSize(sqlite3_file *pJfd, sqlite_int64 *pSize){
74950   MemJournal *p = (MemJournal *)pJfd;
74951   *pSize = (sqlite_int64) p->endpoint.iOffset;
74952   return SQLITE_OK;
74953 }
74954 
74955 /*
74956 ** Table of methods for MemJournal sqlite3_file object.
74957 */
74958 static const struct sqlite3_io_methods MemJournalMethods = {
74959   1,                /* iVersion */
74960   memjrnlClose,     /* xClose */
74961   memjrnlRead,      /* xRead */
74962   memjrnlWrite,     /* xWrite */
74963   memjrnlTruncate,  /* xTruncate */
74964   memjrnlSync,      /* xSync */
74965   memjrnlFileSize,  /* xFileSize */
74966   0,                /* xLock */
74967   0,                /* xUnlock */
74968   0,                /* xCheckReservedLock */
74969   0,                /* xFileControl */
74970   0,                /* xSectorSize */
74971   0,                /* xDeviceCharacteristics */
74972   0,                /* xShmMap */
74973   0,                /* xShmLock */
74974   0,                /* xShmBarrier */
74975   0,                /* xShmUnmap */
74976   0,                /* xFetch */
74977   0                 /* xUnfetch */
74978 };
74979 
74980 /* 
74981 ** Open a journal file.
74982 */
74983 SQLITE_PRIVATE void sqlite3MemJournalOpen(sqlite3_file *pJfd){
74984   MemJournal *p = (MemJournal *)pJfd;
74985   assert( EIGHT_BYTE_ALIGNMENT(p) );
74986   memset(p, 0, sqlite3MemJournalSize());
74987   p->pMethod = (sqlite3_io_methods*)&MemJournalMethods;
74988 }
74989 
74990 /*
74991 ** Return true if the file-handle passed as an argument is 
74992 ** an in-memory journal 
74993 */
74994 SQLITE_PRIVATE int sqlite3IsMemJournal(sqlite3_file *pJfd){
74995   return pJfd->pMethods==&MemJournalMethods;
74996 }
74997 
74998 /* 
74999 ** Return the number of bytes required to store a MemJournal file descriptor.
75000 */
75001 SQLITE_PRIVATE int sqlite3MemJournalSize(void){
75002   return sizeof(MemJournal);
75003 }
75004 
75005 /************** End of memjournal.c ******************************************/
75006 /************** Begin file walker.c ******************************************/
75007 /*
75008 ** 2008 August 16
75009 **
75010 ** The author disclaims copyright to this source code.  In place of
75011 ** a legal notice, here is a blessing:
75012 **
75013 **    May you do good and not evil.
75014 **    May you find forgiveness for yourself and forgive others.
75015 **    May you share freely, never taking more than you give.
75016 **
75017 *************************************************************************
75018 ** This file contains routines used for walking the parser tree for
75019 ** an SQL statement.
75020 */
75021 /* #include <stdlib.h> */
75022 /* #include <string.h> */
75023 
75024 
75025 /*
75026 ** Walk an expression tree.  Invoke the callback once for each node
75027 ** of the expression, while decending.  (In other words, the callback
75028 ** is invoked before visiting children.)
75029 **
75030 ** The return value from the callback should be one of the WRC_*
75031 ** constants to specify how to proceed with the walk.
75032 **
75033 **    WRC_Continue      Continue descending down the tree.
75034 **
75035 **    WRC_Prune         Do not descend into child nodes.  But allow
75036 **                      the walk to continue with sibling nodes.
75037 **
75038 **    WRC_Abort         Do no more callbacks.  Unwind the stack and
75039 **                      return the top-level walk call.
75040 **
75041 ** The return value from this routine is WRC_Abort to abandon the tree walk
75042 ** and WRC_Continue to continue.
75043 */
75044 SQLITE_PRIVATE int sqlite3WalkExpr(Walker *pWalker, Expr *pExpr){
75045   int rc;
75046   if( pExpr==0 ) return WRC_Continue;
75047   testcase( ExprHasProperty(pExpr, EP_TokenOnly) );
75048   testcase( ExprHasProperty(pExpr, EP_Reduced) );
75049   rc = pWalker->xExprCallback(pWalker, pExpr);
75050   if( rc==WRC_Continue
75051               && !ExprHasProperty(pExpr,EP_TokenOnly) ){
75052     if( sqlite3WalkExpr(pWalker, pExpr->pLeft) ) return WRC_Abort;
75053     if( sqlite3WalkExpr(pWalker, pExpr->pRight) ) return WRC_Abort;
75054     if( ExprHasProperty(pExpr, EP_xIsSelect) ){
75055       if( sqlite3WalkSelect(pWalker, pExpr->x.pSelect) ) return WRC_Abort;
75056     }else{
75057       if( sqlite3WalkExprList(pWalker, pExpr->x.pList) ) return WRC_Abort;
75058     }
75059   }
75060   return rc & WRC_Abort;
75061 }
75062 
75063 /*
75064 ** Call sqlite3WalkExpr() for every expression in list p or until
75065 ** an abort request is seen.
75066 */
75067 SQLITE_PRIVATE int sqlite3WalkExprList(Walker *pWalker, ExprList *p){
75068   int i;
75069   struct ExprList_item *pItem;
75070   if( p ){
75071     for(i=p->nExpr, pItem=p->a; i>0; i--, pItem++){
75072       if( sqlite3WalkExpr(pWalker, pItem->pExpr) ) return WRC_Abort;
75073     }
75074   }
75075   return WRC_Continue;
75076 }
75077 
75078 /*
75079 ** Walk all expressions associated with SELECT statement p.  Do
75080 ** not invoke the SELECT callback on p, but do (of course) invoke
75081 ** any expr callbacks and SELECT callbacks that come from subqueries.
75082 ** Return WRC_Abort or WRC_Continue.
75083 */
75084 SQLITE_PRIVATE int sqlite3WalkSelectExpr(Walker *pWalker, Select *p){
75085   if( sqlite3WalkExprList(pWalker, p->pEList) ) return WRC_Abort;
75086   if( sqlite3WalkExpr(pWalker, p->pWhere) ) return WRC_Abort;
75087   if( sqlite3WalkExprList(pWalker, p->pGroupBy) ) return WRC_Abort;
75088   if( sqlite3WalkExpr(pWalker, p->pHaving) ) return WRC_Abort;
75089   if( sqlite3WalkExprList(pWalker, p->pOrderBy) ) return WRC_Abort;
75090   if( sqlite3WalkExpr(pWalker, p->pLimit) ) return WRC_Abort;
75091   if( sqlite3WalkExpr(pWalker, p->pOffset) ) return WRC_Abort;
75092   return WRC_Continue;
75093 }
75094 
75095 /*
75096 ** Walk the parse trees associated with all subqueries in the
75097 ** FROM clause of SELECT statement p.  Do not invoke the select
75098 ** callback on p, but do invoke it on each FROM clause subquery
75099 ** and on any subqueries further down in the tree.  Return 
75100 ** WRC_Abort or WRC_Continue;
75101 */
75102 SQLITE_PRIVATE int sqlite3WalkSelectFrom(Walker *pWalker, Select *p){
75103   SrcList *pSrc;
75104   int i;
75105   struct SrcList_item *pItem;
75106 
75107   pSrc = p->pSrc;
75108   if( ALWAYS(pSrc) ){
75109     for(i=pSrc->nSrc, pItem=pSrc->a; i>0; i--, pItem++){
75110       if( sqlite3WalkSelect(pWalker, pItem->pSelect) ){
75111         return WRC_Abort;
75112       }
75113     }
75114   }
75115   return WRC_Continue;
75116 } 
75117 
75118 /*
75119 ** Call sqlite3WalkExpr() for every expression in Select statement p.
75120 ** Invoke sqlite3WalkSelect() for subqueries in the FROM clause and
75121 ** on the compound select chain, p->pPrior.  Invoke the xSelectCallback()
75122 ** either before or after the walk of expressions and FROM clause, depending
75123 ** on whether pWalker->bSelectDepthFirst is false or true, respectively.
75124 **
75125 ** Return WRC_Continue under normal conditions.  Return WRC_Abort if
75126 ** there is an abort request.
75127 **
75128 ** If the Walker does not have an xSelectCallback() then this routine
75129 ** is a no-op returning WRC_Continue.
75130 */
75131 SQLITE_PRIVATE int sqlite3WalkSelect(Walker *pWalker, Select *p){
75132   int rc;
75133   if( p==0 || pWalker->xSelectCallback==0 ) return WRC_Continue;
75134   rc = WRC_Continue;
75135   pWalker->walkerDepth++;
75136   while( p ){
75137     if( !pWalker->bSelectDepthFirst ){
75138        rc = pWalker->xSelectCallback(pWalker, p);
75139        if( rc ) break;
75140     }
75141     if( sqlite3WalkSelectExpr(pWalker, p)
75142      || sqlite3WalkSelectFrom(pWalker, p)
75143     ){
75144       pWalker->walkerDepth--;
75145       return WRC_Abort;
75146     }
75147     if( pWalker->bSelectDepthFirst ){
75148       rc = pWalker->xSelectCallback(pWalker, p);
75149       /* Depth-first search is currently only used for
75150       ** selectAddSubqueryTypeInfo() and that routine always returns
75151       ** WRC_Continue (0).  So the following branch is never taken. */
75152       if( NEVER(rc) ) break;
75153     }
75154     p = p->pPrior;
75155   }
75156   pWalker->walkerDepth--;
75157   return rc & WRC_Abort;
75158 }
75159 
75160 /************** End of walker.c **********************************************/
75161 /************** Begin file resolve.c *****************************************/
75162 /*
75163 ** 2008 August 18
75164 **
75165 ** The author disclaims copyright to this source code.  In place of
75166 ** a legal notice, here is a blessing:
75167 **
75168 **    May you do good and not evil.
75169 **    May you find forgiveness for yourself and forgive others.
75170 **    May you share freely, never taking more than you give.
75171 **
75172 *************************************************************************
75173 **
75174 ** This file contains routines used for walking the parser tree and
75175 ** resolve all identifiers by associating them with a particular
75176 ** table and column.
75177 */
75178 /* #include <stdlib.h> */
75179 /* #include <string.h> */
75180 
75181 /*
75182 ** Walk the expression tree pExpr and increase the aggregate function
75183 ** depth (the Expr.op2 field) by N on every TK_AGG_FUNCTION node.
75184 ** This needs to occur when copying a TK_AGG_FUNCTION node from an
75185 ** outer query into an inner subquery.
75186 **
75187 ** incrAggFunctionDepth(pExpr,n) is the main routine.  incrAggDepth(..)
75188 ** is a helper function - a callback for the tree walker.
75189 */
75190 static int incrAggDepth(Walker *pWalker, Expr *pExpr){
75191   if( pExpr->op==TK_AGG_FUNCTION ) pExpr->op2 += pWalker->u.i;
75192   return WRC_Continue;
75193 }
75194 static void incrAggFunctionDepth(Expr *pExpr, int N){
75195   if( N>0 ){
75196     Walker w;
75197     memset(&w, 0, sizeof(w));
75198     w.xExprCallback = incrAggDepth;
75199     w.u.i = N;
75200     sqlite3WalkExpr(&w, pExpr);
75201   }
75202 }
75203 
75204 /*
75205 ** Turn the pExpr expression into an alias for the iCol-th column of the
75206 ** result set in pEList.
75207 **
75208 ** If the result set column is a simple column reference, then this routine
75209 ** makes an exact copy.  But for any other kind of expression, this
75210 ** routine make a copy of the result set column as the argument to the
75211 ** TK_AS operator.  The TK_AS operator causes the expression to be
75212 ** evaluated just once and then reused for each alias.
75213 **
75214 ** The reason for suppressing the TK_AS term when the expression is a simple
75215 ** column reference is so that the column reference will be recognized as
75216 ** usable by indices within the WHERE clause processing logic. 
75217 **
75218 ** The TK_AS operator is inhibited if zType[0]=='G'.  This means
75219 ** that in a GROUP BY clause, the expression is evaluated twice.  Hence:
75220 **
75221 **     SELECT random()%5 AS x, count(*) FROM tab GROUP BY x
75222 **
75223 ** Is equivalent to:
75224 **
75225 **     SELECT random()%5 AS x, count(*) FROM tab GROUP BY random()%5
75226 **
75227 ** The result of random()%5 in the GROUP BY clause is probably different
75228 ** from the result in the result-set.  On the other hand Standard SQL does
75229 ** not allow the GROUP BY clause to contain references to result-set columns.
75230 ** So this should never come up in well-formed queries.
75231 **
75232 ** If the reference is followed by a COLLATE operator, then make sure
75233 ** the COLLATE operator is preserved.  For example:
75234 **
75235 **     SELECT a+b, c+d FROM t1 ORDER BY 1 COLLATE nocase;
75236 **
75237 ** Should be transformed into:
75238 **
75239 **     SELECT a+b, c+d FROM t1 ORDER BY (a+b) COLLATE nocase;
75240 **
75241 ** The nSubquery parameter specifies how many levels of subquery the
75242 ** alias is removed from the original expression.  The usually value is
75243 ** zero but it might be more if the alias is contained within a subquery
75244 ** of the original expression.  The Expr.op2 field of TK_AGG_FUNCTION
75245 ** structures must be increased by the nSubquery amount.
75246 */
75247 static void resolveAlias(
75248   Parse *pParse,         /* Parsing context */
75249   ExprList *pEList,      /* A result set */
75250   int iCol,              /* A column in the result set.  0..pEList->nExpr-1 */
75251   Expr *pExpr,           /* Transform this into an alias to the result set */
75252   const char *zType,     /* "GROUP" or "ORDER" or "" */
75253   int nSubquery          /* Number of subqueries that the label is moving */
75254 ){
75255   Expr *pOrig;           /* The iCol-th column of the result set */
75256   Expr *pDup;            /* Copy of pOrig */
75257   sqlite3 *db;           /* The database connection */
75258 
75259   assert( iCol>=0 && iCol<pEList->nExpr );
75260   pOrig = pEList->a[iCol].pExpr;
75261   assert( pOrig!=0 );
75262   assert( pOrig->flags & EP_Resolved );
75263   db = pParse->db;
75264   pDup = sqlite3ExprDup(db, pOrig, 0);
75265   if( pDup==0 ) return;
75266   if( pOrig->op!=TK_COLUMN && zType[0]!='G' ){
75267     incrAggFunctionDepth(pDup, nSubquery);
75268     pDup = sqlite3PExpr(pParse, TK_AS, pDup, 0, 0);
75269     if( pDup==0 ) return;
75270     ExprSetProperty(pDup, EP_Skip);
75271     if( pEList->a[iCol].u.x.iAlias==0 ){
75272       pEList->a[iCol].u.x.iAlias = (u16)(++pParse->nAlias);
75273     }
75274     pDup->iTable = pEList->a[iCol].u.x.iAlias;
75275   }
75276   if( pExpr->op==TK_COLLATE ){
75277     pDup = sqlite3ExprAddCollateString(pParse, pDup, pExpr->u.zToken);
75278   }
75279 
75280   /* Before calling sqlite3ExprDelete(), set the EP_Static flag. This 
75281   ** prevents ExprDelete() from deleting the Expr structure itself,
75282   ** allowing it to be repopulated by the memcpy() on the following line.
75283   ** The pExpr->u.zToken might point into memory that will be freed by the
75284   ** sqlite3DbFree(db, pDup) on the last line of this block, so be sure to
75285   ** make a copy of the token before doing the sqlite3DbFree().
75286   */
75287   ExprSetProperty(pExpr, EP_Static);
75288   sqlite3ExprDelete(db, pExpr);
75289   memcpy(pExpr, pDup, sizeof(*pExpr));
75290   if( !ExprHasProperty(pExpr, EP_IntValue) && pExpr->u.zToken!=0 ){
75291     assert( (pExpr->flags & (EP_Reduced|EP_TokenOnly))==0 );
75292     pExpr->u.zToken = sqlite3DbStrDup(db, pExpr->u.zToken);
75293     pExpr->flags |= EP_MemToken;
75294   }
75295   sqlite3DbFree(db, pDup);
75296 }
75297 
75298 
75299 /*
75300 ** Return TRUE if the name zCol occurs anywhere in the USING clause.
75301 **
75302 ** Return FALSE if the USING clause is NULL or if it does not contain
75303 ** zCol.
75304 */
75305 static int nameInUsingClause(IdList *pUsing, const char *zCol){
75306   if( pUsing ){
75307     int k;
75308     for(k=0; k<pUsing->nId; k++){
75309       if( sqlite3StrICmp(pUsing->a[k].zName, zCol)==0 ) return 1;
75310     }
75311   }
75312   return 0;
75313 }
75314 
75315 /*
75316 ** Subqueries stores the original database, table and column names for their
75317 ** result sets in ExprList.a[].zSpan, in the form "DATABASE.TABLE.COLUMN".
75318 ** Check to see if the zSpan given to this routine matches the zDb, zTab,
75319 ** and zCol.  If any of zDb, zTab, and zCol are NULL then those fields will
75320 ** match anything.
75321 */
75322 SQLITE_PRIVATE int sqlite3MatchSpanName(
75323   const char *zSpan,
75324   const char *zCol,
75325   const char *zTab,
75326   const char *zDb
75327 ){
75328   int n;
75329   for(n=0; ALWAYS(zSpan[n]) && zSpan[n]!='.'; n++){}
75330   if( zDb && (sqlite3StrNICmp(zSpan, zDb, n)!=0 || zDb[n]!=0) ){
75331     return 0;
75332   }
75333   zSpan += n+1;
75334   for(n=0; ALWAYS(zSpan[n]) && zSpan[n]!='.'; n++){}
75335   if( zTab && (sqlite3StrNICmp(zSpan, zTab, n)!=0 || zTab[n]!=0) ){
75336     return 0;
75337   }
75338   zSpan += n+1;
75339   if( zCol && sqlite3StrICmp(zSpan, zCol)!=0 ){
75340     return 0;
75341   }
75342   return 1;
75343 }
75344 
75345 /*
75346 ** Given the name of a column of the form X.Y.Z or Y.Z or just Z, look up
75347 ** that name in the set of source tables in pSrcList and make the pExpr 
75348 ** expression node refer back to that source column.  The following changes
75349 ** are made to pExpr:
75350 **
75351 **    pExpr->iDb           Set the index in db->aDb[] of the database X
75352 **                         (even if X is implied).
75353 **    pExpr->iTable        Set to the cursor number for the table obtained
75354 **                         from pSrcList.
75355 **    pExpr->pTab          Points to the Table structure of X.Y (even if
75356 **                         X and/or Y are implied.)
75357 **    pExpr->iColumn       Set to the column number within the table.
75358 **    pExpr->op            Set to TK_COLUMN.
75359 **    pExpr->pLeft         Any expression this points to is deleted
75360 **    pExpr->pRight        Any expression this points to is deleted.
75361 **
75362 ** The zDb variable is the name of the database (the "X").  This value may be
75363 ** NULL meaning that name is of the form Y.Z or Z.  Any available database
75364 ** can be used.  The zTable variable is the name of the table (the "Y").  This
75365 ** value can be NULL if zDb is also NULL.  If zTable is NULL it
75366 ** means that the form of the name is Z and that columns from any table
75367 ** can be used.
75368 **
75369 ** If the name cannot be resolved unambiguously, leave an error message
75370 ** in pParse and return WRC_Abort.  Return WRC_Prune on success.
75371 */
75372 static int lookupName(
75373   Parse *pParse,       /* The parsing context */
75374   const char *zDb,     /* Name of the database containing table, or NULL */
75375   const char *zTab,    /* Name of table containing column, or NULL */
75376   const char *zCol,    /* Name of the column. */
75377   NameContext *pNC,    /* The name context used to resolve the name */
75378   Expr *pExpr          /* Make this EXPR node point to the selected column */
75379 ){
75380   int i, j;                         /* Loop counters */
75381   int cnt = 0;                      /* Number of matching column names */
75382   int cntTab = 0;                   /* Number of matching table names */
75383   int nSubquery = 0;                /* How many levels of subquery */
75384   sqlite3 *db = pParse->db;         /* The database connection */
75385   struct SrcList_item *pItem;       /* Use for looping over pSrcList items */
75386   struct SrcList_item *pMatch = 0;  /* The matching pSrcList item */
75387   NameContext *pTopNC = pNC;        /* First namecontext in the list */
75388   Schema *pSchema = 0;              /* Schema of the expression */
75389   int isTrigger = 0;                /* True if resolved to a trigger column */
75390   Table *pTab = 0;                  /* Table hold the row */
75391   Column *pCol;                     /* A column of pTab */
75392 
75393   assert( pNC );     /* the name context cannot be NULL. */
75394   assert( zCol );    /* The Z in X.Y.Z cannot be NULL */
75395   assert( !ExprHasProperty(pExpr, EP_TokenOnly|EP_Reduced) );
75396 
75397   /* Initialize the node to no-match */
75398   pExpr->iTable = -1;
75399   pExpr->pTab = 0;
75400   ExprSetVVAProperty(pExpr, EP_NoReduce);
75401 
75402   /* Translate the schema name in zDb into a pointer to the corresponding
75403   ** schema.  If not found, pSchema will remain NULL and nothing will match
75404   ** resulting in an appropriate error message toward the end of this routine
75405   */
75406   if( zDb ){
75407     testcase( pNC->ncFlags & NC_PartIdx );
75408     testcase( pNC->ncFlags & NC_IsCheck );
75409     if( (pNC->ncFlags & (NC_PartIdx|NC_IsCheck))!=0 ){
75410       /* Silently ignore database qualifiers inside CHECK constraints and partial
75411       ** indices.  Do not raise errors because that might break legacy and
75412       ** because it does not hurt anything to just ignore the database name. */
75413       zDb = 0;
75414     }else{
75415       for(i=0; i<db->nDb; i++){
75416         assert( db->aDb[i].zName );
75417         if( sqlite3StrICmp(db->aDb[i].zName,zDb)==0 ){
75418           pSchema = db->aDb[i].pSchema;
75419           break;
75420         }
75421       }
75422     }
75423   }
75424 
75425   /* Start at the inner-most context and move outward until a match is found */
75426   while( pNC && cnt==0 ){
75427     ExprList *pEList;
75428     SrcList *pSrcList = pNC->pSrcList;
75429 
75430     if( pSrcList ){
75431       for(i=0, pItem=pSrcList->a; i<pSrcList->nSrc; i++, pItem++){
75432         pTab = pItem->pTab;
75433         assert( pTab!=0 && pTab->zName!=0 );
75434         assert( pTab->nCol>0 );
75435         if( pItem->pSelect && (pItem->pSelect->selFlags & SF_NestedFrom)!=0 ){
75436           int hit = 0;
75437           pEList = pItem->pSelect->pEList;
75438           for(j=0; j<pEList->nExpr; j++){
75439             if( sqlite3MatchSpanName(pEList->a[j].zSpan, zCol, zTab, zDb) ){
75440               cnt++;
75441               cntTab = 2;
75442               pMatch = pItem;
75443               pExpr->iColumn = j;
75444               hit = 1;
75445             }
75446           }
75447           if( hit || zTab==0 ) continue;
75448         }
75449         if( zDb && pTab->pSchema!=pSchema ){
75450           continue;
75451         }
75452         if( zTab ){
75453           const char *zTabName = pItem->zAlias ? pItem->zAlias : pTab->zName;
75454           assert( zTabName!=0 );
75455           if( sqlite3StrICmp(zTabName, zTab)!=0 ){
75456             continue;
75457           }
75458         }
75459         if( 0==(cntTab++) ){
75460           pMatch = pItem;
75461         }
75462         for(j=0, pCol=pTab->aCol; j<pTab->nCol; j++, pCol++){
75463           if( sqlite3StrICmp(pCol->zName, zCol)==0 ){
75464             /* If there has been exactly one prior match and this match
75465             ** is for the right-hand table of a NATURAL JOIN or is in a 
75466             ** USING clause, then skip this match.
75467             */
75468             if( cnt==1 ){
75469               if( pItem->jointype & JT_NATURAL ) continue;
75470               if( nameInUsingClause(pItem->pUsing, zCol) ) continue;
75471             }
75472             cnt++;
75473             pMatch = pItem;
75474             /* Substitute the rowid (column -1) for the INTEGER PRIMARY KEY */
75475             pExpr->iColumn = j==pTab->iPKey ? -1 : (i16)j;
75476             break;
75477           }
75478         }
75479       }
75480       if( pMatch ){
75481         pExpr->iTable = pMatch->iCursor;
75482         pExpr->pTab = pMatch->pTab;
75483         pSchema = pExpr->pTab->pSchema;
75484       }
75485     } /* if( pSrcList ) */
75486 
75487 #ifndef SQLITE_OMIT_TRIGGER
75488     /* If we have not already resolved the name, then maybe 
75489     ** it is a new.* or old.* trigger argument reference
75490     */
75491     if( zDb==0 && zTab!=0 && cntTab==0 && pParse->pTriggerTab!=0 ){
75492       int op = pParse->eTriggerOp;
75493       assert( op==TK_DELETE || op==TK_UPDATE || op==TK_INSERT );
75494       if( op!=TK_DELETE && sqlite3StrICmp("new",zTab) == 0 ){
75495         pExpr->iTable = 1;
75496         pTab = pParse->pTriggerTab;
75497       }else if( op!=TK_INSERT && sqlite3StrICmp("old",zTab)==0 ){
75498         pExpr->iTable = 0;
75499         pTab = pParse->pTriggerTab;
75500       }
75501 
75502       if( pTab ){ 
75503         int iCol;
75504         pSchema = pTab->pSchema;
75505         cntTab++;
75506         for(iCol=0, pCol=pTab->aCol; iCol<pTab->nCol; iCol++, pCol++){
75507           if( sqlite3StrICmp(pCol->zName, zCol)==0 ){
75508             if( iCol==pTab->iPKey ){
75509               iCol = -1;
75510             }
75511             break;
75512           }
75513         }
75514         if( iCol>=pTab->nCol && sqlite3IsRowid(zCol) && HasRowid(pTab) ){
75515           /* IMP: R-24309-18625 */
75516           /* IMP: R-44911-55124 */
75517           iCol = -1;
75518         }
75519         if( iCol<pTab->nCol ){
75520           cnt++;
75521           if( iCol<0 ){
75522             pExpr->affinity = SQLITE_AFF_INTEGER;
75523           }else if( pExpr->iTable==0 ){
75524             testcase( iCol==31 );
75525             testcase( iCol==32 );
75526             pParse->oldmask |= (iCol>=32 ? 0xffffffff : (((u32)1)<<iCol));
75527           }else{
75528             testcase( iCol==31 );
75529             testcase( iCol==32 );
75530             pParse->newmask |= (iCol>=32 ? 0xffffffff : (((u32)1)<<iCol));
75531           }
75532           pExpr->iColumn = (i16)iCol;
75533           pExpr->pTab = pTab;
75534           isTrigger = 1;
75535         }
75536       }
75537     }
75538 #endif /* !defined(SQLITE_OMIT_TRIGGER) */
75539 
75540     /*
75541     ** Perhaps the name is a reference to the ROWID
75542     */
75543     assert( pTab!=0 || cntTab==0 );
75544     if( cnt==0 && cntTab==1 && sqlite3IsRowid(zCol) && HasRowid(pTab) ){
75545       cnt = 1;
75546       pExpr->iColumn = -1;     /* IMP: R-44911-55124 */
75547       pExpr->affinity = SQLITE_AFF_INTEGER;
75548     }
75549 
75550     /*
75551     ** If the input is of the form Z (not Y.Z or X.Y.Z) then the name Z
75552     ** might refer to an result-set alias.  This happens, for example, when
75553     ** we are resolving names in the WHERE clause of the following command:
75554     **
75555     **     SELECT a+b AS x FROM table WHERE x<10;
75556     **
75557     ** In cases like this, replace pExpr with a copy of the expression that
75558     ** forms the result set entry ("a+b" in the example) and return immediately.
75559     ** Note that the expression in the result set should have already been
75560     ** resolved by the time the WHERE clause is resolved.
75561     **
75562     ** The ability to use an output result-set column in the WHERE, GROUP BY,
75563     ** or HAVING clauses, or as part of a larger expression in the ORDRE BY
75564     ** clause is not standard SQL.  This is a (goofy) SQLite extension, that
75565     ** is supported for backwards compatibility only.  TO DO: Issue a warning
75566     ** on sqlite3_log() whenever the capability is used.
75567     */
75568     if( (pEList = pNC->pEList)!=0
75569      && zTab==0
75570      && cnt==0
75571     ){
75572       for(j=0; j<pEList->nExpr; j++){
75573         char *zAs = pEList->a[j].zName;
75574         if( zAs!=0 && sqlite3StrICmp(zAs, zCol)==0 ){
75575           Expr *pOrig;
75576           assert( pExpr->pLeft==0 && pExpr->pRight==0 );
75577           assert( pExpr->x.pList==0 );
75578           assert( pExpr->x.pSelect==0 );
75579           pOrig = pEList->a[j].pExpr;
75580           if( (pNC->ncFlags&NC_AllowAgg)==0 && ExprHasProperty(pOrig, EP_Agg) ){
75581             sqlite3ErrorMsg(pParse, "misuse of aliased aggregate %s", zAs);
75582             return WRC_Abort;
75583           }
75584           resolveAlias(pParse, pEList, j, pExpr, "", nSubquery);
75585           cnt = 1;
75586           pMatch = 0;
75587           assert( zTab==0 && zDb==0 );
75588           goto lookupname_end;
75589         }
75590       } 
75591     }
75592 
75593     /* Advance to the next name context.  The loop will exit when either
75594     ** we have a match (cnt>0) or when we run out of name contexts.
75595     */
75596     if( cnt==0 ){
75597       pNC = pNC->pNext;
75598       nSubquery++;
75599     }
75600   }
75601 
75602   /*
75603   ** If X and Y are NULL (in other words if only the column name Z is
75604   ** supplied) and the value of Z is enclosed in double-quotes, then
75605   ** Z is a string literal if it doesn't match any column names.  In that
75606   ** case, we need to return right away and not make any changes to
75607   ** pExpr.
75608   **
75609   ** Because no reference was made to outer contexts, the pNC->nRef
75610   ** fields are not changed in any context.
75611   */
75612   if( cnt==0 && zTab==0 && ExprHasProperty(pExpr,EP_DblQuoted) ){
75613     pExpr->op = TK_STRING;
75614     pExpr->pTab = 0;
75615     return WRC_Prune;
75616   }
75617 
75618   /*
75619   ** cnt==0 means there was not match.  cnt>1 means there were two or
75620   ** more matches.  Either way, we have an error.
75621   */
75622   if( cnt!=1 ){
75623     const char *zErr;
75624     zErr = cnt==0 ? "no such column" : "ambiguous column name";
75625     if( zDb ){
75626       sqlite3ErrorMsg(pParse, "%s: %s.%s.%s", zErr, zDb, zTab, zCol);
75627     }else if( zTab ){
75628       sqlite3ErrorMsg(pParse, "%s: %s.%s", zErr, zTab, zCol);
75629     }else{
75630       sqlite3ErrorMsg(pParse, "%s: %s", zErr, zCol);
75631     }
75632     pParse->checkSchema = 1;
75633     pTopNC->nErr++;
75634   }
75635 
75636   /* If a column from a table in pSrcList is referenced, then record
75637   ** this fact in the pSrcList.a[].colUsed bitmask.  Column 0 causes
75638   ** bit 0 to be set.  Column 1 sets bit 1.  And so forth.  If the
75639   ** column number is greater than the number of bits in the bitmask
75640   ** then set the high-order bit of the bitmask.
75641   */
75642   if( pExpr->iColumn>=0 && pMatch!=0 ){
75643     int n = pExpr->iColumn;
75644     testcase( n==BMS-1 );
75645     if( n>=BMS ){
75646       n = BMS-1;
75647     }
75648     assert( pMatch->iCursor==pExpr->iTable );
75649     pMatch->colUsed |= ((Bitmask)1)<<n;
75650   }
75651 
75652   /* Clean up and return
75653   */
75654   sqlite3ExprDelete(db, pExpr->pLeft);
75655   pExpr->pLeft = 0;
75656   sqlite3ExprDelete(db, pExpr->pRight);
75657   pExpr->pRight = 0;
75658   pExpr->op = (isTrigger ? TK_TRIGGER : TK_COLUMN);
75659 lookupname_end:
75660   if( cnt==1 ){
75661     assert( pNC!=0 );
75662     if( pExpr->op!=TK_AS ){
75663       sqlite3AuthRead(pParse, pExpr, pSchema, pNC->pSrcList);
75664     }
75665     /* Increment the nRef value on all name contexts from TopNC up to
75666     ** the point where the name matched. */
75667     for(;;){
75668       assert( pTopNC!=0 );
75669       pTopNC->nRef++;
75670       if( pTopNC==pNC ) break;
75671       pTopNC = pTopNC->pNext;
75672     }
75673     return WRC_Prune;
75674   } else {
75675     return WRC_Abort;
75676   }
75677 }
75678 
75679 /*
75680 ** Allocate and return a pointer to an expression to load the column iCol
75681 ** from datasource iSrc in SrcList pSrc.
75682 */
75683 SQLITE_PRIVATE Expr *sqlite3CreateColumnExpr(sqlite3 *db, SrcList *pSrc, int iSrc, int iCol){
75684   Expr *p = sqlite3ExprAlloc(db, TK_COLUMN, 0, 0);
75685   if( p ){
75686     struct SrcList_item *pItem = &pSrc->a[iSrc];
75687     p->pTab = pItem->pTab;
75688     p->iTable = pItem->iCursor;
75689     if( p->pTab->iPKey==iCol ){
75690       p->iColumn = -1;
75691     }else{
75692       p->iColumn = (ynVar)iCol;
75693       testcase( iCol==BMS );
75694       testcase( iCol==BMS-1 );
75695       pItem->colUsed |= ((Bitmask)1)<<(iCol>=BMS ? BMS-1 : iCol);
75696     }
75697     ExprSetProperty(p, EP_Resolved);
75698   }
75699   return p;
75700 }
75701 
75702 /*
75703 ** Report an error that an expression is not valid for a partial index WHERE
75704 ** clause.
75705 */
75706 static void notValidPartIdxWhere(
75707   Parse *pParse,       /* Leave error message here */
75708   NameContext *pNC,    /* The name context */
75709   const char *zMsg     /* Type of error */
75710 ){
75711   if( (pNC->ncFlags & NC_PartIdx)!=0 ){
75712     sqlite3ErrorMsg(pParse, "%s prohibited in partial index WHERE clauses",
75713                     zMsg);
75714   }
75715 }
75716 
75717 #ifndef SQLITE_OMIT_CHECK
75718 /*
75719 ** Report an error that an expression is not valid for a CHECK constraint.
75720 */
75721 static void notValidCheckConstraint(
75722   Parse *pParse,       /* Leave error message here */
75723   NameContext *pNC,    /* The name context */
75724   const char *zMsg     /* Type of error */
75725 ){
75726   if( (pNC->ncFlags & NC_IsCheck)!=0 ){
75727     sqlite3ErrorMsg(pParse,"%s prohibited in CHECK constraints", zMsg);
75728   }
75729 }
75730 #else
75731 # define notValidCheckConstraint(P,N,M)
75732 #endif
75733 
75734 /*
75735 ** Expression p should encode a floating point value between 1.0 and 0.0.
75736 ** Return 1024 times this value.  Or return -1 if p is not a floating point
75737 ** value between 1.0 and 0.0.
75738 */
75739 static int exprProbability(Expr *p){
75740   double r = -1.0;
75741   if( p->op!=TK_FLOAT ) return -1;
75742   sqlite3AtoF(p->u.zToken, &r, sqlite3Strlen30(p->u.zToken), SQLITE_UTF8);
75743   assert( r>=0.0 );
75744   if( r>1.0 ) return -1;
75745   return (int)(r*1000.0);
75746 }
75747 
75748 /*
75749 ** This routine is callback for sqlite3WalkExpr().
75750 **
75751 ** Resolve symbolic names into TK_COLUMN operators for the current
75752 ** node in the expression tree.  Return 0 to continue the search down
75753 ** the tree or 2 to abort the tree walk.
75754 **
75755 ** This routine also does error checking and name resolution for
75756 ** function names.  The operator for aggregate functions is changed
75757 ** to TK_AGG_FUNCTION.
75758 */
75759 static int resolveExprStep(Walker *pWalker, Expr *pExpr){
75760   NameContext *pNC;
75761   Parse *pParse;
75762 
75763   pNC = pWalker->u.pNC;
75764   assert( pNC!=0 );
75765   pParse = pNC->pParse;
75766   assert( pParse==pWalker->pParse );
75767 
75768   if( ExprHasProperty(pExpr, EP_Resolved) ) return WRC_Prune;
75769   ExprSetProperty(pExpr, EP_Resolved);
75770 #ifndef NDEBUG
75771   if( pNC->pSrcList && pNC->pSrcList->nAlloc>0 ){
75772     SrcList *pSrcList = pNC->pSrcList;
75773     int i;
75774     for(i=0; i<pNC->pSrcList->nSrc; i++){
75775       assert( pSrcList->a[i].iCursor>=0 && pSrcList->a[i].iCursor<pParse->nTab);
75776     }
75777   }
75778 #endif
75779   switch( pExpr->op ){
75780 
75781 #if defined(SQLITE_ENABLE_UPDATE_DELETE_LIMIT) && !defined(SQLITE_OMIT_SUBQUERY)
75782     /* The special operator TK_ROW means use the rowid for the first
75783     ** column in the FROM clause.  This is used by the LIMIT and ORDER BY
75784     ** clause processing on UPDATE and DELETE statements.
75785     */
75786     case TK_ROW: {
75787       SrcList *pSrcList = pNC->pSrcList;
75788       struct SrcList_item *pItem;
75789       assert( pSrcList && pSrcList->nSrc==1 );
75790       pItem = pSrcList->a; 
75791       pExpr->op = TK_COLUMN;
75792       pExpr->pTab = pItem->pTab;
75793       pExpr->iTable = pItem->iCursor;
75794       pExpr->iColumn = -1;
75795       pExpr->affinity = SQLITE_AFF_INTEGER;
75796       break;
75797     }
75798 #endif /* defined(SQLITE_ENABLE_UPDATE_DELETE_LIMIT) && !defined(SQLITE_OMIT_SUBQUERY) */
75799 
75800     /* A lone identifier is the name of a column.
75801     */
75802     case TK_ID: {
75803       return lookupName(pParse, 0, 0, pExpr->u.zToken, pNC, pExpr);
75804     }
75805   
75806     /* A table name and column name:     ID.ID
75807     ** Or a database, table and column:  ID.ID.ID
75808     */
75809     case TK_DOT: {
75810       const char *zColumn;
75811       const char *zTable;
75812       const char *zDb;
75813       Expr *pRight;
75814 
75815       /* if( pSrcList==0 ) break; */
75816       pRight = pExpr->pRight;
75817       if( pRight->op==TK_ID ){
75818         zDb = 0;
75819         zTable = pExpr->pLeft->u.zToken;
75820         zColumn = pRight->u.zToken;
75821       }else{
75822         assert( pRight->op==TK_DOT );
75823         zDb = pExpr->pLeft->u.zToken;
75824         zTable = pRight->pLeft->u.zToken;
75825         zColumn = pRight->pRight->u.zToken;
75826       }
75827       return lookupName(pParse, zDb, zTable, zColumn, pNC, pExpr);
75828     }
75829 
75830     /* Resolve function names
75831     */
75832     case TK_FUNCTION: {
75833       ExprList *pList = pExpr->x.pList;    /* The argument list */
75834       int n = pList ? pList->nExpr : 0;    /* Number of arguments */
75835       int no_such_func = 0;       /* True if no such function exists */
75836       int wrong_num_args = 0;     /* True if wrong number of arguments */
75837       int is_agg = 0;             /* True if is an aggregate function */
75838       int auth;                   /* Authorization to use the function */
75839       int nId;                    /* Number of characters in function name */
75840       const char *zId;            /* The function name. */
75841       FuncDef *pDef;              /* Information about the function */
75842       u8 enc = ENC(pParse->db);   /* The database encoding */
75843 
75844       assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
75845       notValidPartIdxWhere(pParse, pNC, "functions");
75846       zId = pExpr->u.zToken;
75847       nId = sqlite3Strlen30(zId);
75848       pDef = sqlite3FindFunction(pParse->db, zId, nId, n, enc, 0);
75849       if( pDef==0 ){
75850         pDef = sqlite3FindFunction(pParse->db, zId, nId, -2, enc, 0);
75851         if( pDef==0 ){
75852           no_such_func = 1;
75853         }else{
75854           wrong_num_args = 1;
75855         }
75856       }else{
75857         is_agg = pDef->xFunc==0;
75858         if( pDef->funcFlags & SQLITE_FUNC_UNLIKELY ){
75859           ExprSetProperty(pExpr, EP_Unlikely|EP_Skip);
75860           if( n==2 ){
75861             pExpr->iTable = exprProbability(pList->a[1].pExpr);
75862             if( pExpr->iTable<0 ){
75863               sqlite3ErrorMsg(pParse, "second argument to likelihood() must be a "
75864                                       "constant between 0.0 and 1.0");
75865               pNC->nErr++;
75866             }
75867           }else{
75868             /* EVIDENCE-OF: R-61304-29449 The unlikely(X) function is equivalent to
75869             ** likelihood(X, 0.0625).
75870             ** EVIDENCE-OF: R-01283-11636 The unlikely(X) function is short-hand for
75871             ** likelihood(X,0.0625). */
75872             pExpr->iTable = 62;  /* TUNING:  Default 2nd arg to unlikely() is 0.0625 */
75873           }             
75874         }
75875       }
75876 #ifndef SQLITE_OMIT_AUTHORIZATION
75877       if( pDef ){
75878         auth = sqlite3AuthCheck(pParse, SQLITE_FUNCTION, 0, pDef->zName, 0);
75879         if( auth!=SQLITE_OK ){
75880           if( auth==SQLITE_DENY ){
75881             sqlite3ErrorMsg(pParse, "not authorized to use function: %s",
75882                                     pDef->zName);
75883             pNC->nErr++;
75884           }
75885           pExpr->op = TK_NULL;
75886           return WRC_Prune;
75887         }
75888         if( pDef->funcFlags & SQLITE_FUNC_CONSTANT ) ExprSetProperty(pExpr,EP_Constant);
75889       }
75890 #endif
75891       if( is_agg && (pNC->ncFlags & NC_AllowAgg)==0 ){
75892         sqlite3ErrorMsg(pParse, "misuse of aggregate function %.*s()", nId,zId);
75893         pNC->nErr++;
75894         is_agg = 0;
75895       }else if( no_such_func && pParse->db->init.busy==0 ){
75896         sqlite3ErrorMsg(pParse, "no such function: %.*s", nId, zId);
75897         pNC->nErr++;
75898       }else if( wrong_num_args ){
75899         sqlite3ErrorMsg(pParse,"wrong number of arguments to function %.*s()",
75900              nId, zId);
75901         pNC->nErr++;
75902       }
75903       if( is_agg ) pNC->ncFlags &= ~NC_AllowAgg;
75904       sqlite3WalkExprList(pWalker, pList);
75905       if( is_agg ){
75906         NameContext *pNC2 = pNC;
75907         pExpr->op = TK_AGG_FUNCTION;
75908         pExpr->op2 = 0;
75909         while( pNC2 && !sqlite3FunctionUsesThisSrc(pExpr, pNC2->pSrcList) ){
75910           pExpr->op2++;
75911           pNC2 = pNC2->pNext;
75912         }
75913         if( pNC2 ) pNC2->ncFlags |= NC_HasAgg;
75914         pNC->ncFlags |= NC_AllowAgg;
75915       }
75916       /* FIX ME:  Compute pExpr->affinity based on the expected return
75917       ** type of the function 
75918       */
75919       return WRC_Prune;
75920     }
75921 #ifndef SQLITE_OMIT_SUBQUERY
75922     case TK_SELECT:
75923     case TK_EXISTS:  testcase( pExpr->op==TK_EXISTS );
75924 #endif
75925     case TK_IN: {
75926       testcase( pExpr->op==TK_IN );
75927       if( ExprHasProperty(pExpr, EP_xIsSelect) ){
75928         int nRef = pNC->nRef;
75929         notValidCheckConstraint(pParse, pNC, "subqueries");
75930         notValidPartIdxWhere(pParse, pNC, "subqueries");
75931         sqlite3WalkSelect(pWalker, pExpr->x.pSelect);
75932         assert( pNC->nRef>=nRef );
75933         if( nRef!=pNC->nRef ){
75934           ExprSetProperty(pExpr, EP_VarSelect);
75935         }
75936       }
75937       break;
75938     }
75939     case TK_VARIABLE: {
75940       notValidCheckConstraint(pParse, pNC, "parameters");
75941       notValidPartIdxWhere(pParse, pNC, "parameters");
75942       break;
75943     }
75944   }
75945   return (pParse->nErr || pParse->db->mallocFailed) ? WRC_Abort : WRC_Continue;
75946 }
75947 
75948 /*
75949 ** pEList is a list of expressions which are really the result set of the
75950 ** a SELECT statement.  pE is a term in an ORDER BY or GROUP BY clause.
75951 ** This routine checks to see if pE is a simple identifier which corresponds
75952 ** to the AS-name of one of the terms of the expression list.  If it is,
75953 ** this routine return an integer between 1 and N where N is the number of
75954 ** elements in pEList, corresponding to the matching entry.  If there is
75955 ** no match, or if pE is not a simple identifier, then this routine
75956 ** return 0.
75957 **
75958 ** pEList has been resolved.  pE has not.
75959 */
75960 static int resolveAsName(
75961   Parse *pParse,     /* Parsing context for error messages */
75962   ExprList *pEList,  /* List of expressions to scan */
75963   Expr *pE           /* Expression we are trying to match */
75964 ){
75965   int i;             /* Loop counter */
75966 
75967   UNUSED_PARAMETER(pParse);
75968 
75969   if( pE->op==TK_ID ){
75970     char *zCol = pE->u.zToken;
75971     for(i=0; i<pEList->nExpr; i++){
75972       char *zAs = pEList->a[i].zName;
75973       if( zAs!=0 && sqlite3StrICmp(zAs, zCol)==0 ){
75974         return i+1;
75975       }
75976     }
75977   }
75978   return 0;
75979 }
75980 
75981 /*
75982 ** pE is a pointer to an expression which is a single term in the
75983 ** ORDER BY of a compound SELECT.  The expression has not been
75984 ** name resolved.
75985 **
75986 ** At the point this routine is called, we already know that the
75987 ** ORDER BY term is not an integer index into the result set.  That
75988 ** case is handled by the calling routine.
75989 **
75990 ** Attempt to match pE against result set columns in the left-most
75991 ** SELECT statement.  Return the index i of the matching column,
75992 ** as an indication to the caller that it should sort by the i-th column.
75993 ** The left-most column is 1.  In other words, the value returned is the
75994 ** same integer value that would be used in the SQL statement to indicate
75995 ** the column.
75996 **
75997 ** If there is no match, return 0.  Return -1 if an error occurs.
75998 */
75999 static int resolveOrderByTermToExprList(
76000   Parse *pParse,     /* Parsing context for error messages */
76001   Select *pSelect,   /* The SELECT statement with the ORDER BY clause */
76002   Expr *pE           /* The specific ORDER BY term */
76003 ){
76004   int i;             /* Loop counter */
76005   ExprList *pEList;  /* The columns of the result set */
76006   NameContext nc;    /* Name context for resolving pE */
76007   sqlite3 *db;       /* Database connection */
76008   int rc;            /* Return code from subprocedures */
76009   u8 savedSuppErr;   /* Saved value of db->suppressErr */
76010 
76011   assert( sqlite3ExprIsInteger(pE, &i)==0 );
76012   pEList = pSelect->pEList;
76013 
76014   /* Resolve all names in the ORDER BY term expression
76015   */
76016   memset(&nc, 0, sizeof(nc));
76017   nc.pParse = pParse;
76018   nc.pSrcList = pSelect->pSrc;
76019   nc.pEList = pEList;
76020   nc.ncFlags = NC_AllowAgg;
76021   nc.nErr = 0;
76022   db = pParse->db;
76023   savedSuppErr = db->suppressErr;
76024   db->suppressErr = 1;
76025   rc = sqlite3ResolveExprNames(&nc, pE);
76026   db->suppressErr = savedSuppErr;
76027   if( rc ) return 0;
76028 
76029   /* Try to match the ORDER BY expression against an expression
76030   ** in the result set.  Return an 1-based index of the matching
76031   ** result-set entry.
76032   */
76033   for(i=0; i<pEList->nExpr; i++){
76034     if( sqlite3ExprCompare(pEList->a[i].pExpr, pE, -1)<2 ){
76035       return i+1;
76036     }
76037   }
76038 
76039   /* If no match, return 0. */
76040   return 0;
76041 }
76042 
76043 /*
76044 ** Generate an ORDER BY or GROUP BY term out-of-range error.
76045 */
76046 static void resolveOutOfRangeError(
76047   Parse *pParse,         /* The error context into which to write the error */
76048   const char *zType,     /* "ORDER" or "GROUP" */
76049   int i,                 /* The index (1-based) of the term out of range */
76050   int mx                 /* Largest permissible value of i */
76051 ){
76052   sqlite3ErrorMsg(pParse, 
76053     "%r %s BY term out of range - should be "
76054     "between 1 and %d", i, zType, mx);
76055 }
76056 
76057 /*
76058 ** Analyze the ORDER BY clause in a compound SELECT statement.   Modify
76059 ** each term of the ORDER BY clause is a constant integer between 1
76060 ** and N where N is the number of columns in the compound SELECT.
76061 **
76062 ** ORDER BY terms that are already an integer between 1 and N are
76063 ** unmodified.  ORDER BY terms that are integers outside the range of
76064 ** 1 through N generate an error.  ORDER BY terms that are expressions
76065 ** are matched against result set expressions of compound SELECT
76066 ** beginning with the left-most SELECT and working toward the right.
76067 ** At the first match, the ORDER BY expression is transformed into
76068 ** the integer column number.
76069 **
76070 ** Return the number of errors seen.
76071 */
76072 static int resolveCompoundOrderBy(
76073   Parse *pParse,        /* Parsing context.  Leave error messages here */
76074   Select *pSelect       /* The SELECT statement containing the ORDER BY */
76075 ){
76076   int i;
76077   ExprList *pOrderBy;
76078   ExprList *pEList;
76079   sqlite3 *db;
76080   int moreToDo = 1;
76081 
76082   pOrderBy = pSelect->pOrderBy;
76083   if( pOrderBy==0 ) return 0;
76084   db = pParse->db;
76085 #if SQLITE_MAX_COLUMN
76086   if( pOrderBy->nExpr>db->aLimit[SQLITE_LIMIT_COLUMN] ){
76087     sqlite3ErrorMsg(pParse, "too many terms in ORDER BY clause");
76088     return 1;
76089   }
76090 #endif
76091   for(i=0; i<pOrderBy->nExpr; i++){
76092     pOrderBy->a[i].done = 0;
76093   }
76094   pSelect->pNext = 0;
76095   while( pSelect->pPrior ){
76096     pSelect->pPrior->pNext = pSelect;
76097     pSelect = pSelect->pPrior;
76098   }
76099   while( pSelect && moreToDo ){
76100     struct ExprList_item *pItem;
76101     moreToDo = 0;
76102     pEList = pSelect->pEList;
76103     assert( pEList!=0 );
76104     for(i=0, pItem=pOrderBy->a; i<pOrderBy->nExpr; i++, pItem++){
76105       int iCol = -1;
76106       Expr *pE, *pDup;
76107       if( pItem->done ) continue;
76108       pE = sqlite3ExprSkipCollate(pItem->pExpr);
76109       if( sqlite3ExprIsInteger(pE, &iCol) ){
76110         if( iCol<=0 || iCol>pEList->nExpr ){
76111           resolveOutOfRangeError(pParse, "ORDER", i+1, pEList->nExpr);
76112           return 1;
76113         }
76114       }else{
76115         iCol = resolveAsName(pParse, pEList, pE);
76116         if( iCol==0 ){
76117           pDup = sqlite3ExprDup(db, pE, 0);
76118           if( !db->mallocFailed ){
76119             assert(pDup);
76120             iCol = resolveOrderByTermToExprList(pParse, pSelect, pDup);
76121           }
76122           sqlite3ExprDelete(db, pDup);
76123         }
76124       }
76125       if( iCol>0 ){
76126         /* Convert the ORDER BY term into an integer column number iCol,
76127         ** taking care to preserve the COLLATE clause if it exists */
76128         Expr *pNew = sqlite3Expr(db, TK_INTEGER, 0);
76129         if( pNew==0 ) return 1;
76130         pNew->flags |= EP_IntValue;
76131         pNew->u.iValue = iCol;
76132         if( pItem->pExpr==pE ){
76133           pItem->pExpr = pNew;
76134         }else{
76135           assert( pItem->pExpr->op==TK_COLLATE );
76136           assert( pItem->pExpr->pLeft==pE );
76137           pItem->pExpr->pLeft = pNew;
76138         }
76139         sqlite3ExprDelete(db, pE);
76140         pItem->u.x.iOrderByCol = (u16)iCol;
76141         pItem->done = 1;
76142       }else{
76143         moreToDo = 1;
76144       }
76145     }
76146     pSelect = pSelect->pNext;
76147   }
76148   for(i=0; i<pOrderBy->nExpr; i++){
76149     if( pOrderBy->a[i].done==0 ){
76150       sqlite3ErrorMsg(pParse, "%r ORDER BY term does not match any "
76151             "column in the result set", i+1);
76152       return 1;
76153     }
76154   }
76155   return 0;
76156 }
76157 
76158 /*
76159 ** Check every term in the ORDER BY or GROUP BY clause pOrderBy of
76160 ** the SELECT statement pSelect.  If any term is reference to a
76161 ** result set expression (as determined by the ExprList.a.u.x.iOrderByCol
76162 ** field) then convert that term into a copy of the corresponding result set
76163 ** column.
76164 **
76165 ** If any errors are detected, add an error message to pParse and
76166 ** return non-zero.  Return zero if no errors are seen.
76167 */
76168 SQLITE_PRIVATE int sqlite3ResolveOrderGroupBy(
76169   Parse *pParse,        /* Parsing context.  Leave error messages here */
76170   Select *pSelect,      /* The SELECT statement containing the clause */
76171   ExprList *pOrderBy,   /* The ORDER BY or GROUP BY clause to be processed */
76172   const char *zType     /* "ORDER" or "GROUP" */
76173 ){
76174   int i;
76175   sqlite3 *db = pParse->db;
76176   ExprList *pEList;
76177   struct ExprList_item *pItem;
76178 
76179   if( pOrderBy==0 || pParse->db->mallocFailed ) return 0;
76180 #if SQLITE_MAX_COLUMN
76181   if( pOrderBy->nExpr>db->aLimit[SQLITE_LIMIT_COLUMN] ){
76182     sqlite3ErrorMsg(pParse, "too many terms in %s BY clause", zType);
76183     return 1;
76184   }
76185 #endif
76186   pEList = pSelect->pEList;
76187   assert( pEList!=0 );  /* sqlite3SelectNew() guarantees this */
76188   for(i=0, pItem=pOrderBy->a; i<pOrderBy->nExpr; i++, pItem++){
76189     if( pItem->u.x.iOrderByCol ){
76190       if( pItem->u.x.iOrderByCol>pEList->nExpr ){
76191         resolveOutOfRangeError(pParse, zType, i+1, pEList->nExpr);
76192         return 1;
76193       }
76194       resolveAlias(pParse, pEList, pItem->u.x.iOrderByCol-1, pItem->pExpr, zType,0);
76195     }
76196   }
76197   return 0;
76198 }
76199 
76200 /*
76201 ** pOrderBy is an ORDER BY or GROUP BY clause in SELECT statement pSelect.
76202 ** The Name context of the SELECT statement is pNC.  zType is either
76203 ** "ORDER" or "GROUP" depending on which type of clause pOrderBy is.
76204 **
76205 ** This routine resolves each term of the clause into an expression.
76206 ** If the order-by term is an integer I between 1 and N (where N is the
76207 ** number of columns in the result set of the SELECT) then the expression
76208 ** in the resolution is a copy of the I-th result-set expression.  If
76209 ** the order-by term is an identifier that corresponds to the AS-name of
76210 ** a result-set expression, then the term resolves to a copy of the
76211 ** result-set expression.  Otherwise, the expression is resolved in
76212 ** the usual way - using sqlite3ResolveExprNames().
76213 **
76214 ** This routine returns the number of errors.  If errors occur, then
76215 ** an appropriate error message might be left in pParse.  (OOM errors
76216 ** excepted.)
76217 */
76218 static int resolveOrderGroupBy(
76219   NameContext *pNC,     /* The name context of the SELECT statement */
76220   Select *pSelect,      /* The SELECT statement holding pOrderBy */
76221   ExprList *pOrderBy,   /* An ORDER BY or GROUP BY clause to resolve */
76222   const char *zType     /* Either "ORDER" or "GROUP", as appropriate */
76223 ){
76224   int i, j;                      /* Loop counters */
76225   int iCol;                      /* Column number */
76226   struct ExprList_item *pItem;   /* A term of the ORDER BY clause */
76227   Parse *pParse;                 /* Parsing context */
76228   int nResult;                   /* Number of terms in the result set */
76229 
76230   if( pOrderBy==0 ) return 0;
76231   nResult = pSelect->pEList->nExpr;
76232   pParse = pNC->pParse;
76233   for(i=0, pItem=pOrderBy->a; i<pOrderBy->nExpr; i++, pItem++){
76234     Expr *pE = pItem->pExpr;
76235     Expr *pE2 = sqlite3ExprSkipCollate(pE);
76236     if( zType[0]!='G' ){
76237       iCol = resolveAsName(pParse, pSelect->pEList, pE2);
76238       if( iCol>0 ){
76239         /* If an AS-name match is found, mark this ORDER BY column as being
76240         ** a copy of the iCol-th result-set column.  The subsequent call to
76241         ** sqlite3ResolveOrderGroupBy() will convert the expression to a
76242         ** copy of the iCol-th result-set expression. */
76243         pItem->u.x.iOrderByCol = (u16)iCol;
76244         continue;
76245       }
76246     }
76247     if( sqlite3ExprIsInteger(pE2, &iCol) ){
76248       /* The ORDER BY term is an integer constant.  Again, set the column
76249       ** number so that sqlite3ResolveOrderGroupBy() will convert the
76250       ** order-by term to a copy of the result-set expression */
76251       if( iCol<1 || iCol>0xffff ){
76252         resolveOutOfRangeError(pParse, zType, i+1, nResult);
76253         return 1;
76254       }
76255       pItem->u.x.iOrderByCol = (u16)iCol;
76256       continue;
76257     }
76258 
76259     /* Otherwise, treat the ORDER BY term as an ordinary expression */
76260     pItem->u.x.iOrderByCol = 0;
76261     if( sqlite3ResolveExprNames(pNC, pE) ){
76262       return 1;
76263     }
76264     for(j=0; j<pSelect->pEList->nExpr; j++){
76265       if( sqlite3ExprCompare(pE, pSelect->pEList->a[j].pExpr, -1)==0 ){
76266         pItem->u.x.iOrderByCol = j+1;
76267       }
76268     }
76269   }
76270   return sqlite3ResolveOrderGroupBy(pParse, pSelect, pOrderBy, zType);
76271 }
76272 
76273 /*
76274 ** Resolve names in the SELECT statement p and all of its descendents.
76275 */
76276 static int resolveSelectStep(Walker *pWalker, Select *p){
76277   NameContext *pOuterNC;  /* Context that contains this SELECT */
76278   NameContext sNC;        /* Name context of this SELECT */
76279   int isCompound;         /* True if p is a compound select */
76280   int nCompound;          /* Number of compound terms processed so far */
76281   Parse *pParse;          /* Parsing context */
76282   ExprList *pEList;       /* Result set expression list */
76283   int i;                  /* Loop counter */
76284   ExprList *pGroupBy;     /* The GROUP BY clause */
76285   Select *pLeftmost;      /* Left-most of SELECT of a compound */
76286   sqlite3 *db;            /* Database connection */
76287   
76288 
76289   assert( p!=0 );
76290   if( p->selFlags & SF_Resolved ){
76291     return WRC_Prune;
76292   }
76293   pOuterNC = pWalker->u.pNC;
76294   pParse = pWalker->pParse;
76295   db = pParse->db;
76296 
76297   /* Normally sqlite3SelectExpand() will be called first and will have
76298   ** already expanded this SELECT.  However, if this is a subquery within
76299   ** an expression, sqlite3ResolveExprNames() will be called without a
76300   ** prior call to sqlite3SelectExpand().  When that happens, let
76301   ** sqlite3SelectPrep() do all of the processing for this SELECT.
76302   ** sqlite3SelectPrep() will invoke both sqlite3SelectExpand() and
76303   ** this routine in the correct order.
76304   */
76305   if( (p->selFlags & SF_Expanded)==0 ){
76306     sqlite3SelectPrep(pParse, p, pOuterNC);
76307     return (pParse->nErr || db->mallocFailed) ? WRC_Abort : WRC_Prune;
76308   }
76309 
76310   isCompound = p->pPrior!=0;
76311   nCompound = 0;
76312   pLeftmost = p;
76313   while( p ){
76314     assert( (p->selFlags & SF_Expanded)!=0 );
76315     assert( (p->selFlags & SF_Resolved)==0 );
76316     p->selFlags |= SF_Resolved;
76317 
76318     /* Resolve the expressions in the LIMIT and OFFSET clauses. These
76319     ** are not allowed to refer to any names, so pass an empty NameContext.
76320     */
76321     memset(&sNC, 0, sizeof(sNC));
76322     sNC.pParse = pParse;
76323     if( sqlite3ResolveExprNames(&sNC, p->pLimit) ||
76324         sqlite3ResolveExprNames(&sNC, p->pOffset) ){
76325       return WRC_Abort;
76326     }
76327   
76328     /* Recursively resolve names in all subqueries
76329     */
76330     for(i=0; i<p->pSrc->nSrc; i++){
76331       struct SrcList_item *pItem = &p->pSrc->a[i];
76332       if( pItem->pSelect ){
76333         NameContext *pNC;         /* Used to iterate name contexts */
76334         int nRef = 0;             /* Refcount for pOuterNC and outer contexts */
76335         const char *zSavedContext = pParse->zAuthContext;
76336 
76337         /* Count the total number of references to pOuterNC and all of its
76338         ** parent contexts. After resolving references to expressions in
76339         ** pItem->pSelect, check if this value has changed. If so, then
76340         ** SELECT statement pItem->pSelect must be correlated. Set the
76341         ** pItem->isCorrelated flag if this is the case. */
76342         for(pNC=pOuterNC; pNC; pNC=pNC->pNext) nRef += pNC->nRef;
76343 
76344         if( pItem->zName ) pParse->zAuthContext = pItem->zName;
76345         sqlite3ResolveSelectNames(pParse, pItem->pSelect, pOuterNC);
76346         pParse->zAuthContext = zSavedContext;
76347         if( pParse->nErr || db->mallocFailed ) return WRC_Abort;
76348 
76349         for(pNC=pOuterNC; pNC; pNC=pNC->pNext) nRef -= pNC->nRef;
76350         assert( pItem->isCorrelated==0 && nRef<=0 );
76351         pItem->isCorrelated = (nRef!=0);
76352       }
76353     }
76354   
76355     /* Set up the local name-context to pass to sqlite3ResolveExprNames() to
76356     ** resolve the result-set expression list.
76357     */
76358     sNC.ncFlags = NC_AllowAgg;
76359     sNC.pSrcList = p->pSrc;
76360     sNC.pNext = pOuterNC;
76361   
76362     /* Resolve names in the result set. */
76363     pEList = p->pEList;
76364     assert( pEList!=0 );
76365     for(i=0; i<pEList->nExpr; i++){
76366       Expr *pX = pEList->a[i].pExpr;
76367       if( sqlite3ResolveExprNames(&sNC, pX) ){
76368         return WRC_Abort;
76369       }
76370     }
76371   
76372     /* If there are no aggregate functions in the result-set, and no GROUP BY 
76373     ** expression, do not allow aggregates in any of the other expressions.
76374     */
76375     assert( (p->selFlags & SF_Aggregate)==0 );
76376     pGroupBy = p->pGroupBy;
76377     if( pGroupBy || (sNC.ncFlags & NC_HasAgg)!=0 ){
76378       p->selFlags |= SF_Aggregate;
76379     }else{
76380       sNC.ncFlags &= ~NC_AllowAgg;
76381     }
76382   
76383     /* If a HAVING clause is present, then there must be a GROUP BY clause.
76384     */
76385     if( p->pHaving && !pGroupBy ){
76386       sqlite3ErrorMsg(pParse, "a GROUP BY clause is required before HAVING");
76387       return WRC_Abort;
76388     }
76389   
76390     /* Add the output column list to the name-context before parsing the
76391     ** other expressions in the SELECT statement. This is so that
76392     ** expressions in the WHERE clause (etc.) can refer to expressions by
76393     ** aliases in the result set.
76394     **
76395     ** Minor point: If this is the case, then the expression will be
76396     ** re-evaluated for each reference to it.
76397     */
76398     sNC.pEList = p->pEList;
76399     if( sqlite3ResolveExprNames(&sNC, p->pHaving) ) return WRC_Abort;
76400     if( sqlite3ResolveExprNames(&sNC, p->pWhere) ) return WRC_Abort;
76401 
76402     /* The ORDER BY and GROUP BY clauses may not refer to terms in
76403     ** outer queries 
76404     */
76405     sNC.pNext = 0;
76406     sNC.ncFlags |= NC_AllowAgg;
76407 
76408     /* Process the ORDER BY clause for singleton SELECT statements.
76409     ** The ORDER BY clause for compounds SELECT statements is handled
76410     ** below, after all of the result-sets for all of the elements of
76411     ** the compound have been resolved.
76412     */
76413     if( !isCompound && resolveOrderGroupBy(&sNC, p, p->pOrderBy, "ORDER") ){
76414       return WRC_Abort;
76415     }
76416     if( db->mallocFailed ){
76417       return WRC_Abort;
76418     }
76419   
76420     /* Resolve the GROUP BY clause.  At the same time, make sure 
76421     ** the GROUP BY clause does not contain aggregate functions.
76422     */
76423     if( pGroupBy ){
76424       struct ExprList_item *pItem;
76425     
76426       if( resolveOrderGroupBy(&sNC, p, pGroupBy, "GROUP") || db->mallocFailed ){
76427         return WRC_Abort;
76428       }
76429       for(i=0, pItem=pGroupBy->a; i<pGroupBy->nExpr; i++, pItem++){
76430         if( ExprHasProperty(pItem->pExpr, EP_Agg) ){
76431           sqlite3ErrorMsg(pParse, "aggregate functions are not allowed in "
76432               "the GROUP BY clause");
76433           return WRC_Abort;
76434         }
76435       }
76436     }
76437 
76438     /* Advance to the next term of the compound
76439     */
76440     p = p->pPrior;
76441     nCompound++;
76442   }
76443 
76444   /* Resolve the ORDER BY on a compound SELECT after all terms of
76445   ** the compound have been resolved.
76446   */
76447   if( isCompound && resolveCompoundOrderBy(pParse, pLeftmost) ){
76448     return WRC_Abort;
76449   }
76450 
76451   return WRC_Prune;
76452 }
76453 
76454 /*
76455 ** This routine walks an expression tree and resolves references to
76456 ** table columns and result-set columns.  At the same time, do error
76457 ** checking on function usage and set a flag if any aggregate functions
76458 ** are seen.
76459 **
76460 ** To resolve table columns references we look for nodes (or subtrees) of the 
76461 ** form X.Y.Z or Y.Z or just Z where
76462 **
76463 **      X:   The name of a database.  Ex:  "main" or "temp" or
76464 **           the symbolic name assigned to an ATTACH-ed database.
76465 **
76466 **      Y:   The name of a table in a FROM clause.  Or in a trigger
76467 **           one of the special names "old" or "new".
76468 **
76469 **      Z:   The name of a column in table Y.
76470 **
76471 ** The node at the root of the subtree is modified as follows:
76472 **
76473 **    Expr.op        Changed to TK_COLUMN
76474 **    Expr.pTab      Points to the Table object for X.Y
76475 **    Expr.iColumn   The column index in X.Y.  -1 for the rowid.
76476 **    Expr.iTable    The VDBE cursor number for X.Y
76477 **
76478 **
76479 ** To resolve result-set references, look for expression nodes of the
76480 ** form Z (with no X and Y prefix) where the Z matches the right-hand
76481 ** size of an AS clause in the result-set of a SELECT.  The Z expression
76482 ** is replaced by a copy of the left-hand side of the result-set expression.
76483 ** Table-name and function resolution occurs on the substituted expression
76484 ** tree.  For example, in:
76485 **
76486 **      SELECT a+b AS x, c+d AS y FROM t1 ORDER BY x;
76487 **
76488 ** The "x" term of the order by is replaced by "a+b" to render:
76489 **
76490 **      SELECT a+b AS x, c+d AS y FROM t1 ORDER BY a+b;
76491 **
76492 ** Function calls are checked to make sure that the function is 
76493 ** defined and that the correct number of arguments are specified.
76494 ** If the function is an aggregate function, then the NC_HasAgg flag is
76495 ** set and the opcode is changed from TK_FUNCTION to TK_AGG_FUNCTION.
76496 ** If an expression contains aggregate functions then the EP_Agg
76497 ** property on the expression is set.
76498 **
76499 ** An error message is left in pParse if anything is amiss.  The number
76500 ** if errors is returned.
76501 */
76502 SQLITE_PRIVATE int sqlite3ResolveExprNames( 
76503   NameContext *pNC,       /* Namespace to resolve expressions in. */
76504   Expr *pExpr             /* The expression to be analyzed. */
76505 ){
76506   u8 savedHasAgg;
76507   Walker w;
76508 
76509   if( pExpr==0 ) return 0;
76510 #if SQLITE_MAX_EXPR_DEPTH>0
76511   {
76512     Parse *pParse = pNC->pParse;
76513     if( sqlite3ExprCheckHeight(pParse, pExpr->nHeight+pNC->pParse->nHeight) ){
76514       return 1;
76515     }
76516     pParse->nHeight += pExpr->nHeight;
76517   }
76518 #endif
76519   savedHasAgg = pNC->ncFlags & NC_HasAgg;
76520   pNC->ncFlags &= ~NC_HasAgg;
76521   memset(&w, 0, sizeof(w));
76522   w.xExprCallback = resolveExprStep;
76523   w.xSelectCallback = resolveSelectStep;
76524   w.pParse = pNC->pParse;
76525   w.u.pNC = pNC;
76526   sqlite3WalkExpr(&w, pExpr);
76527 #if SQLITE_MAX_EXPR_DEPTH>0
76528   pNC->pParse->nHeight -= pExpr->nHeight;
76529 #endif
76530   if( pNC->nErr>0 || w.pParse->nErr>0 ){
76531     ExprSetProperty(pExpr, EP_Error);
76532   }
76533   if( pNC->ncFlags & NC_HasAgg ){
76534     ExprSetProperty(pExpr, EP_Agg);
76535   }else if( savedHasAgg ){
76536     pNC->ncFlags |= NC_HasAgg;
76537   }
76538   return ExprHasProperty(pExpr, EP_Error);
76539 }
76540 
76541 
76542 /*
76543 ** Resolve all names in all expressions of a SELECT and in all
76544 ** decendents of the SELECT, including compounds off of p->pPrior,
76545 ** subqueries in expressions, and subqueries used as FROM clause
76546 ** terms.
76547 **
76548 ** See sqlite3ResolveExprNames() for a description of the kinds of
76549 ** transformations that occur.
76550 **
76551 ** All SELECT statements should have been expanded using
76552 ** sqlite3SelectExpand() prior to invoking this routine.
76553 */
76554 SQLITE_PRIVATE void sqlite3ResolveSelectNames(
76555   Parse *pParse,         /* The parser context */
76556   Select *p,             /* The SELECT statement being coded. */
76557   NameContext *pOuterNC  /* Name context for parent SELECT statement */
76558 ){
76559   Walker w;
76560 
76561   assert( p!=0 );
76562   memset(&w, 0, sizeof(w));
76563   w.xExprCallback = resolveExprStep;
76564   w.xSelectCallback = resolveSelectStep;
76565   w.pParse = pParse;
76566   w.u.pNC = pOuterNC;
76567   sqlite3WalkSelect(&w, p);
76568 }
76569 
76570 /*
76571 ** Resolve names in expressions that can only reference a single table:
76572 **
76573 **    *   CHECK constraints
76574 **    *   WHERE clauses on partial indices
76575 **
76576 ** The Expr.iTable value for Expr.op==TK_COLUMN nodes of the expression
76577 ** is set to -1 and the Expr.iColumn value is set to the column number.
76578 **
76579 ** Any errors cause an error message to be set in pParse.
76580 */
76581 SQLITE_PRIVATE void sqlite3ResolveSelfReference(
76582   Parse *pParse,      /* Parsing context */
76583   Table *pTab,        /* The table being referenced */
76584   int type,           /* NC_IsCheck or NC_PartIdx */
76585   Expr *pExpr,        /* Expression to resolve.  May be NULL. */
76586   ExprList *pList     /* Expression list to resolve.  May be NUL. */
76587 ){
76588   SrcList sSrc;                   /* Fake SrcList for pParse->pNewTable */
76589   NameContext sNC;                /* Name context for pParse->pNewTable */
76590   int i;                          /* Loop counter */
76591 
76592   assert( type==NC_IsCheck || type==NC_PartIdx );
76593   memset(&sNC, 0, sizeof(sNC));
76594   memset(&sSrc, 0, sizeof(sSrc));
76595   sSrc.nSrc = 1;
76596   sSrc.a[0].zName = pTab->zName;
76597   sSrc.a[0].pTab = pTab;
76598   sSrc.a[0].iCursor = -1;
76599   sNC.pParse = pParse;
76600   sNC.pSrcList = &sSrc;
76601   sNC.ncFlags = type;
76602   if( sqlite3ResolveExprNames(&sNC, pExpr) ) return;
76603   if( pList ){
76604     for(i=0; i<pList->nExpr; i++){
76605       if( sqlite3ResolveExprNames(&sNC, pList->a[i].pExpr) ){
76606         return;
76607       }
76608     }
76609   }
76610 }
76611 
76612 /************** End of resolve.c *********************************************/
76613 /************** Begin file expr.c ********************************************/
76614 /*
76615 ** 2001 September 15
76616 **
76617 ** The author disclaims copyright to this source code.  In place of
76618 ** a legal notice, here is a blessing:
76619 **
76620 **    May you do good and not evil.
76621 **    May you find forgiveness for yourself and forgive others.
76622 **    May you share freely, never taking more than you give.
76623 **
76624 *************************************************************************
76625 ** This file contains routines used for analyzing expressions and
76626 ** for generating VDBE code that evaluates expressions in SQLite.
76627 */
76628 
76629 /*
76630 ** Return the 'affinity' of the expression pExpr if any.
76631 **
76632 ** If pExpr is a column, a reference to a column via an 'AS' alias,
76633 ** or a sub-select with a column as the return value, then the 
76634 ** affinity of that column is returned. Otherwise, 0x00 is returned,
76635 ** indicating no affinity for the expression.
76636 **
76637 ** i.e. the WHERE clause expresssions in the following statements all
76638 ** have an affinity:
76639 **
76640 ** CREATE TABLE t1(a);
76641 ** SELECT * FROM t1 WHERE a;
76642 ** SELECT a AS b FROM t1 WHERE b;
76643 ** SELECT * FROM t1 WHERE (select a from t1);
76644 */
76645 SQLITE_PRIVATE char sqlite3ExprAffinity(Expr *pExpr){
76646   int op;
76647   pExpr = sqlite3ExprSkipCollate(pExpr);
76648   op = pExpr->op;
76649   if( op==TK_SELECT ){
76650     assert( pExpr->flags&EP_xIsSelect );
76651     return sqlite3ExprAffinity(pExpr->x.pSelect->pEList->a[0].pExpr);
76652   }
76653 #ifndef SQLITE_OMIT_CAST
76654   if( op==TK_CAST ){
76655     assert( !ExprHasProperty(pExpr, EP_IntValue) );
76656     return sqlite3AffinityType(pExpr->u.zToken, 0);
76657   }
76658 #endif
76659   if( (op==TK_AGG_COLUMN || op==TK_COLUMN || op==TK_REGISTER) 
76660    && pExpr->pTab!=0
76661   ){
76662     /* op==TK_REGISTER && pExpr->pTab!=0 happens when pExpr was originally
76663     ** a TK_COLUMN but was previously evaluated and cached in a register */
76664     int j = pExpr->iColumn;
76665     if( j<0 ) return SQLITE_AFF_INTEGER;
76666     assert( pExpr->pTab && j<pExpr->pTab->nCol );
76667     return pExpr->pTab->aCol[j].affinity;
76668   }
76669   return pExpr->affinity;
76670 }
76671 
76672 /*
76673 ** Set the collating sequence for expression pExpr to be the collating
76674 ** sequence named by pToken.   Return a pointer to a new Expr node that
76675 ** implements the COLLATE operator.
76676 **
76677 ** If a memory allocation error occurs, that fact is recorded in pParse->db
76678 ** and the pExpr parameter is returned unchanged.
76679 */
76680 SQLITE_PRIVATE Expr *sqlite3ExprAddCollateToken(Parse *pParse, Expr *pExpr, Token *pCollName){
76681   if( pCollName->n>0 ){
76682     Expr *pNew = sqlite3ExprAlloc(pParse->db, TK_COLLATE, pCollName, 1);
76683     if( pNew ){
76684       pNew->pLeft = pExpr;
76685       pNew->flags |= EP_Collate|EP_Skip;
76686       pExpr = pNew;
76687     }
76688   }
76689   return pExpr;
76690 }
76691 SQLITE_PRIVATE Expr *sqlite3ExprAddCollateString(Parse *pParse, Expr *pExpr, const char *zC){
76692   Token s;
76693   assert( zC!=0 );
76694   s.z = zC;
76695   s.n = sqlite3Strlen30(s.z);
76696   return sqlite3ExprAddCollateToken(pParse, pExpr, &s);
76697 }
76698 
76699 /*
76700 ** Skip over any TK_COLLATE or TK_AS operators and any unlikely()
76701 ** or likelihood() function at the root of an expression.
76702 */
76703 SQLITE_PRIVATE Expr *sqlite3ExprSkipCollate(Expr *pExpr){
76704   while( pExpr && ExprHasProperty(pExpr, EP_Skip) ){
76705     if( ExprHasProperty(pExpr, EP_Unlikely) ){
76706       assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
76707       assert( pExpr->x.pList->nExpr>0 );
76708       assert( pExpr->op==TK_FUNCTION );
76709       pExpr = pExpr->x.pList->a[0].pExpr;
76710     }else{
76711       assert( pExpr->op==TK_COLLATE || pExpr->op==TK_AS );
76712       pExpr = pExpr->pLeft;
76713     }
76714   }   
76715   return pExpr;
76716 }
76717 
76718 /*
76719 ** Return the collation sequence for the expression pExpr. If
76720 ** there is no defined collating sequence, return NULL.
76721 **
76722 ** The collating sequence might be determined by a COLLATE operator
76723 ** or by the presence of a column with a defined collating sequence.
76724 ** COLLATE operators take first precedence.  Left operands take
76725 ** precedence over right operands.
76726 */
76727 SQLITE_PRIVATE CollSeq *sqlite3ExprCollSeq(Parse *pParse, Expr *pExpr){
76728   sqlite3 *db = pParse->db;
76729   CollSeq *pColl = 0;
76730   Expr *p = pExpr;
76731   while( p ){
76732     int op = p->op;
76733     if( op==TK_CAST || op==TK_UPLUS ){
76734       p = p->pLeft;
76735       continue;
76736     }
76737     if( op==TK_COLLATE || (op==TK_REGISTER && p->op2==TK_COLLATE) ){
76738       pColl = sqlite3GetCollSeq(pParse, ENC(db), 0, p->u.zToken);
76739       break;
76740     }
76741     if( p->pTab!=0
76742      && (op==TK_AGG_COLUMN || op==TK_COLUMN
76743           || op==TK_REGISTER || op==TK_TRIGGER)
76744     ){
76745       /* op==TK_REGISTER && p->pTab!=0 happens when pExpr was originally
76746       ** a TK_COLUMN but was previously evaluated and cached in a register */
76747       int j = p->iColumn;
76748       if( j>=0 ){
76749         const char *zColl = p->pTab->aCol[j].zColl;
76750         pColl = sqlite3FindCollSeq(db, ENC(db), zColl, 0);
76751       }
76752       break;
76753     }
76754     if( p->flags & EP_Collate ){
76755       if( ALWAYS(p->pLeft) && (p->pLeft->flags & EP_Collate)!=0 ){
76756         p = p->pLeft;
76757       }else{
76758         p = p->pRight;
76759       }
76760     }else{
76761       break;
76762     }
76763   }
76764   if( sqlite3CheckCollSeq(pParse, pColl) ){ 
76765     pColl = 0;
76766   }
76767   return pColl;
76768 }
76769 
76770 /*
76771 ** pExpr is an operand of a comparison operator.  aff2 is the
76772 ** type affinity of the other operand.  This routine returns the
76773 ** type affinity that should be used for the comparison operator.
76774 */
76775 SQLITE_PRIVATE char sqlite3CompareAffinity(Expr *pExpr, char aff2){
76776   char aff1 = sqlite3ExprAffinity(pExpr);
76777   if( aff1 && aff2 ){
76778     /* Both sides of the comparison are columns. If one has numeric
76779     ** affinity, use that. Otherwise use no affinity.
76780     */
76781     if( sqlite3IsNumericAffinity(aff1) || sqlite3IsNumericAffinity(aff2) ){
76782       return SQLITE_AFF_NUMERIC;
76783     }else{
76784       return SQLITE_AFF_NONE;
76785     }
76786   }else if( !aff1 && !aff2 ){
76787     /* Neither side of the comparison is a column.  Compare the
76788     ** results directly.
76789     */
76790     return SQLITE_AFF_NONE;
76791   }else{
76792     /* One side is a column, the other is not. Use the columns affinity. */
76793     assert( aff1==0 || aff2==0 );
76794     return (aff1 + aff2);
76795   }
76796 }
76797 
76798 /*
76799 ** pExpr is a comparison operator.  Return the type affinity that should
76800 ** be applied to both operands prior to doing the comparison.
76801 */
76802 static char comparisonAffinity(Expr *pExpr){
76803   char aff;
76804   assert( pExpr->op==TK_EQ || pExpr->op==TK_IN || pExpr->op==TK_LT ||
76805           pExpr->op==TK_GT || pExpr->op==TK_GE || pExpr->op==TK_LE ||
76806           pExpr->op==TK_NE || pExpr->op==TK_IS || pExpr->op==TK_ISNOT );
76807   assert( pExpr->pLeft );
76808   aff = sqlite3ExprAffinity(pExpr->pLeft);
76809   if( pExpr->pRight ){
76810     aff = sqlite3CompareAffinity(pExpr->pRight, aff);
76811   }else if( ExprHasProperty(pExpr, EP_xIsSelect) ){
76812     aff = sqlite3CompareAffinity(pExpr->x.pSelect->pEList->a[0].pExpr, aff);
76813   }else if( !aff ){
76814     aff = SQLITE_AFF_NONE;
76815   }
76816   return aff;
76817 }
76818 
76819 /*
76820 ** pExpr is a comparison expression, eg. '=', '<', IN(...) etc.
76821 ** idx_affinity is the affinity of an indexed column. Return true
76822 ** if the index with affinity idx_affinity may be used to implement
76823 ** the comparison in pExpr.
76824 */
76825 SQLITE_PRIVATE int sqlite3IndexAffinityOk(Expr *pExpr, char idx_affinity){
76826   char aff = comparisonAffinity(pExpr);
76827   switch( aff ){
76828     case SQLITE_AFF_NONE:
76829       return 1;
76830     case SQLITE_AFF_TEXT:
76831       return idx_affinity==SQLITE_AFF_TEXT;
76832     default:
76833       return sqlite3IsNumericAffinity(idx_affinity);
76834   }
76835 }
76836 
76837 /*
76838 ** Return the P5 value that should be used for a binary comparison
76839 ** opcode (OP_Eq, OP_Ge etc.) used to compare pExpr1 and pExpr2.
76840 */
76841 static u8 binaryCompareP5(Expr *pExpr1, Expr *pExpr2, int jumpIfNull){
76842   u8 aff = (char)sqlite3ExprAffinity(pExpr2);
76843   aff = (u8)sqlite3CompareAffinity(pExpr1, aff) | (u8)jumpIfNull;
76844   return aff;
76845 }
76846 
76847 /*
76848 ** Return a pointer to the collation sequence that should be used by
76849 ** a binary comparison operator comparing pLeft and pRight.
76850 **
76851 ** If the left hand expression has a collating sequence type, then it is
76852 ** used. Otherwise the collation sequence for the right hand expression
76853 ** is used, or the default (BINARY) if neither expression has a collating
76854 ** type.
76855 **
76856 ** Argument pRight (but not pLeft) may be a null pointer. In this case,
76857 ** it is not considered.
76858 */
76859 SQLITE_PRIVATE CollSeq *sqlite3BinaryCompareCollSeq(
76860   Parse *pParse, 
76861   Expr *pLeft, 
76862   Expr *pRight
76863 ){
76864   CollSeq *pColl;
76865   assert( pLeft );
76866   if( pLeft->flags & EP_Collate ){
76867     pColl = sqlite3ExprCollSeq(pParse, pLeft);
76868   }else if( pRight && (pRight->flags & EP_Collate)!=0 ){
76869     pColl = sqlite3ExprCollSeq(pParse, pRight);
76870   }else{
76871     pColl = sqlite3ExprCollSeq(pParse, pLeft);
76872     if( !pColl ){
76873       pColl = sqlite3ExprCollSeq(pParse, pRight);
76874     }
76875   }
76876   return pColl;
76877 }
76878 
76879 /*
76880 ** Generate code for a comparison operator.
76881 */
76882 static int codeCompare(
76883   Parse *pParse,    /* The parsing (and code generating) context */
76884   Expr *pLeft,      /* The left operand */
76885   Expr *pRight,     /* The right operand */
76886   int opcode,       /* The comparison opcode */
76887   int in1, int in2, /* Register holding operands */
76888   int dest,         /* Jump here if true.  */
76889   int jumpIfNull    /* If true, jump if either operand is NULL */
76890 ){
76891   int p5;
76892   int addr;
76893   CollSeq *p4;
76894 
76895   p4 = sqlite3BinaryCompareCollSeq(pParse, pLeft, pRight);
76896   p5 = binaryCompareP5(pLeft, pRight, jumpIfNull);
76897   addr = sqlite3VdbeAddOp4(pParse->pVdbe, opcode, in2, dest, in1,
76898                            (void*)p4, P4_COLLSEQ);
76899   sqlite3VdbeChangeP5(pParse->pVdbe, (u8)p5);
76900   return addr;
76901 }
76902 
76903 #if SQLITE_MAX_EXPR_DEPTH>0
76904 /*
76905 ** Check that argument nHeight is less than or equal to the maximum
76906 ** expression depth allowed. If it is not, leave an error message in
76907 ** pParse.
76908 */
76909 SQLITE_PRIVATE int sqlite3ExprCheckHeight(Parse *pParse, int nHeight){
76910   int rc = SQLITE_OK;
76911   int mxHeight = pParse->db->aLimit[SQLITE_LIMIT_EXPR_DEPTH];
76912   if( nHeight>mxHeight ){
76913     sqlite3ErrorMsg(pParse, 
76914        "Expression tree is too large (maximum depth %d)", mxHeight
76915     );
76916     rc = SQLITE_ERROR;
76917   }
76918   return rc;
76919 }
76920 
76921 /* The following three functions, heightOfExpr(), heightOfExprList()
76922 ** and heightOfSelect(), are used to determine the maximum height
76923 ** of any expression tree referenced by the structure passed as the
76924 ** first argument.
76925 **
76926 ** If this maximum height is greater than the current value pointed
76927 ** to by pnHeight, the second parameter, then set *pnHeight to that
76928 ** value.
76929 */
76930 static void heightOfExpr(Expr *p, int *pnHeight){
76931   if( p ){
76932     if( p->nHeight>*pnHeight ){
76933       *pnHeight = p->nHeight;
76934     }
76935   }
76936 }
76937 static void heightOfExprList(ExprList *p, int *pnHeight){
76938   if( p ){
76939     int i;
76940     for(i=0; i<p->nExpr; i++){
76941       heightOfExpr(p->a[i].pExpr, pnHeight);
76942     }
76943   }
76944 }
76945 static void heightOfSelect(Select *p, int *pnHeight){
76946   if( p ){
76947     heightOfExpr(p->pWhere, pnHeight);
76948     heightOfExpr(p->pHaving, pnHeight);
76949     heightOfExpr(p->pLimit, pnHeight);
76950     heightOfExpr(p->pOffset, pnHeight);
76951     heightOfExprList(p->pEList, pnHeight);
76952     heightOfExprList(p->pGroupBy, pnHeight);
76953     heightOfExprList(p->pOrderBy, pnHeight);
76954     heightOfSelect(p->pPrior, pnHeight);
76955   }
76956 }
76957 
76958 /*
76959 ** Set the Expr.nHeight variable in the structure passed as an 
76960 ** argument. An expression with no children, Expr.pList or 
76961 ** Expr.pSelect member has a height of 1. Any other expression
76962 ** has a height equal to the maximum height of any other 
76963 ** referenced Expr plus one.
76964 */
76965 static void exprSetHeight(Expr *p){
76966   int nHeight = 0;
76967   heightOfExpr(p->pLeft, &nHeight);
76968   heightOfExpr(p->pRight, &nHeight);
76969   if( ExprHasProperty(p, EP_xIsSelect) ){
76970     heightOfSelect(p->x.pSelect, &nHeight);
76971   }else{
76972     heightOfExprList(p->x.pList, &nHeight);
76973   }
76974   p->nHeight = nHeight + 1;
76975 }
76976 
76977 /*
76978 ** Set the Expr.nHeight variable using the exprSetHeight() function. If
76979 ** the height is greater than the maximum allowed expression depth,
76980 ** leave an error in pParse.
76981 */
76982 SQLITE_PRIVATE void sqlite3ExprSetHeight(Parse *pParse, Expr *p){
76983   exprSetHeight(p);
76984   sqlite3ExprCheckHeight(pParse, p->nHeight);
76985 }
76986 
76987 /*
76988 ** Return the maximum height of any expression tree referenced
76989 ** by the select statement passed as an argument.
76990 */
76991 SQLITE_PRIVATE int sqlite3SelectExprHeight(Select *p){
76992   int nHeight = 0;
76993   heightOfSelect(p, &nHeight);
76994   return nHeight;
76995 }
76996 #else
76997   #define exprSetHeight(y)
76998 #endif /* SQLITE_MAX_EXPR_DEPTH>0 */
76999 
77000 /*
77001 ** This routine is the core allocator for Expr nodes.
77002 **
77003 ** Construct a new expression node and return a pointer to it.  Memory
77004 ** for this node and for the pToken argument is a single allocation
77005 ** obtained from sqlite3DbMalloc().  The calling function
77006 ** is responsible for making sure the node eventually gets freed.
77007 **
77008 ** If dequote is true, then the token (if it exists) is dequoted.
77009 ** If dequote is false, no dequoting is performance.  The deQuote
77010 ** parameter is ignored if pToken is NULL or if the token does not
77011 ** appear to be quoted.  If the quotes were of the form "..." (double-quotes)
77012 ** then the EP_DblQuoted flag is set on the expression node.
77013 **
77014 ** Special case:  If op==TK_INTEGER and pToken points to a string that
77015 ** can be translated into a 32-bit integer, then the token is not
77016 ** stored in u.zToken.  Instead, the integer values is written
77017 ** into u.iValue and the EP_IntValue flag is set.  No extra storage
77018 ** is allocated to hold the integer text and the dequote flag is ignored.
77019 */
77020 SQLITE_PRIVATE Expr *sqlite3ExprAlloc(
77021   sqlite3 *db,            /* Handle for sqlite3DbMallocZero() (may be null) */
77022   int op,                 /* Expression opcode */
77023   const Token *pToken,    /* Token argument.  Might be NULL */
77024   int dequote             /* True to dequote */
77025 ){
77026   Expr *pNew;
77027   int nExtra = 0;
77028   int iValue = 0;
77029 
77030   if( pToken ){
77031     if( op!=TK_INTEGER || pToken->z==0
77032           || sqlite3GetInt32(pToken->z, &iValue)==0 ){
77033       nExtra = pToken->n+1;
77034       assert( iValue>=0 );
77035     }
77036   }
77037   pNew = sqlite3DbMallocZero(db, sizeof(Expr)+nExtra);
77038   if( pNew ){
77039     pNew->op = (u8)op;
77040     pNew->iAgg = -1;
77041     if( pToken ){
77042       if( nExtra==0 ){
77043         pNew->flags |= EP_IntValue;
77044         pNew->u.iValue = iValue;
77045       }else{
77046         int c;
77047         pNew->u.zToken = (char*)&pNew[1];
77048         assert( pToken->z!=0 || pToken->n==0 );
77049         if( pToken->n ) memcpy(pNew->u.zToken, pToken->z, pToken->n);
77050         pNew->u.zToken[pToken->n] = 0;
77051         if( dequote && nExtra>=3 
77052              && ((c = pToken->z[0])=='\'' || c=='"' || c=='[' || c=='`') ){
77053           sqlite3Dequote(pNew->u.zToken);
77054           if( c=='"' ) pNew->flags |= EP_DblQuoted;
77055         }
77056       }
77057     }
77058 #if SQLITE_MAX_EXPR_DEPTH>0
77059     pNew->nHeight = 1;
77060 #endif  
77061   }
77062   return pNew;
77063 }
77064 
77065 /*
77066 ** Allocate a new expression node from a zero-terminated token that has
77067 ** already been dequoted.
77068 */
77069 SQLITE_PRIVATE Expr *sqlite3Expr(
77070   sqlite3 *db,            /* Handle for sqlite3DbMallocZero() (may be null) */
77071   int op,                 /* Expression opcode */
77072   const char *zToken      /* Token argument.  Might be NULL */
77073 ){
77074   Token x;
77075   x.z = zToken;
77076   x.n = zToken ? sqlite3Strlen30(zToken) : 0;
77077   return sqlite3ExprAlloc(db, op, &x, 0);
77078 }
77079 
77080 /*
77081 ** Attach subtrees pLeft and pRight to the Expr node pRoot.
77082 **
77083 ** If pRoot==NULL that means that a memory allocation error has occurred.
77084 ** In that case, delete the subtrees pLeft and pRight.
77085 */
77086 SQLITE_PRIVATE void sqlite3ExprAttachSubtrees(
77087   sqlite3 *db,
77088   Expr *pRoot,
77089   Expr *pLeft,
77090   Expr *pRight
77091 ){
77092   if( pRoot==0 ){
77093     assert( db->mallocFailed );
77094     sqlite3ExprDelete(db, pLeft);
77095     sqlite3ExprDelete(db, pRight);
77096   }else{
77097     if( pRight ){
77098       pRoot->pRight = pRight;
77099       pRoot->flags |= EP_Collate & pRight->flags;
77100     }
77101     if( pLeft ){
77102       pRoot->pLeft = pLeft;
77103       pRoot->flags |= EP_Collate & pLeft->flags;
77104     }
77105     exprSetHeight(pRoot);
77106   }
77107 }
77108 
77109 /*
77110 ** Allocate a Expr node which joins as many as two subtrees.
77111 **
77112 ** One or both of the subtrees can be NULL.  Return a pointer to the new
77113 ** Expr node.  Or, if an OOM error occurs, set pParse->db->mallocFailed,
77114 ** free the subtrees and return NULL.
77115 */
77116 SQLITE_PRIVATE Expr *sqlite3PExpr(
77117   Parse *pParse,          /* Parsing context */
77118   int op,                 /* Expression opcode */
77119   Expr *pLeft,            /* Left operand */
77120   Expr *pRight,           /* Right operand */
77121   const Token *pToken     /* Argument token */
77122 ){
77123   Expr *p;
77124   if( op==TK_AND && pLeft && pRight ){
77125     /* Take advantage of short-circuit false optimization for AND */
77126     p = sqlite3ExprAnd(pParse->db, pLeft, pRight);
77127   }else{
77128     p = sqlite3ExprAlloc(pParse->db, op, pToken, 1);
77129     sqlite3ExprAttachSubtrees(pParse->db, p, pLeft, pRight);
77130   }
77131   if( p ) {
77132     sqlite3ExprCheckHeight(pParse, p->nHeight);
77133   }
77134   return p;
77135 }
77136 
77137 /*
77138 ** Return 1 if an expression must be FALSE in all cases and 0 if the
77139 ** expression might be true.  This is an optimization.  If is OK to
77140 ** return 0 here even if the expression really is always false (a 
77141 ** false negative).  But it is a bug to return 1 if the expression
77142 ** might be true in some rare circumstances (a false positive.)
77143 **
77144 ** Note that if the expression is part of conditional for a
77145 ** LEFT JOIN, then we cannot determine at compile-time whether or not
77146 ** is it true or false, so always return 0.
77147 */
77148 static int exprAlwaysFalse(Expr *p){
77149   int v = 0;
77150   if( ExprHasProperty(p, EP_FromJoin) ) return 0;
77151   if( !sqlite3ExprIsInteger(p, &v) ) return 0;
77152   return v==0;
77153 }
77154 
77155 /*
77156 ** Join two expressions using an AND operator.  If either expression is
77157 ** NULL, then just return the other expression.
77158 **
77159 ** If one side or the other of the AND is known to be false, then instead
77160 ** of returning an AND expression, just return a constant expression with
77161 ** a value of false.
77162 */
77163 SQLITE_PRIVATE Expr *sqlite3ExprAnd(sqlite3 *db, Expr *pLeft, Expr *pRight){
77164   if( pLeft==0 ){
77165     return pRight;
77166   }else if( pRight==0 ){
77167     return pLeft;
77168   }else if( exprAlwaysFalse(pLeft) || exprAlwaysFalse(pRight) ){
77169     sqlite3ExprDelete(db, pLeft);
77170     sqlite3ExprDelete(db, pRight);
77171     return sqlite3ExprAlloc(db, TK_INTEGER, &sqlite3IntTokens[0], 0);
77172   }else{
77173     Expr *pNew = sqlite3ExprAlloc(db, TK_AND, 0, 0);
77174     sqlite3ExprAttachSubtrees(db, pNew, pLeft, pRight);
77175     return pNew;
77176   }
77177 }
77178 
77179 /*
77180 ** Construct a new expression node for a function with multiple
77181 ** arguments.
77182 */
77183 SQLITE_PRIVATE Expr *sqlite3ExprFunction(Parse *pParse, ExprList *pList, Token *pToken){
77184   Expr *pNew;
77185   sqlite3 *db = pParse->db;
77186   assert( pToken );
77187   pNew = sqlite3ExprAlloc(db, TK_FUNCTION, pToken, 1);
77188   if( pNew==0 ){
77189     sqlite3ExprListDelete(db, pList); /* Avoid memory leak when malloc fails */
77190     return 0;
77191   }
77192   pNew->x.pList = pList;
77193   assert( !ExprHasProperty(pNew, EP_xIsSelect) );
77194   sqlite3ExprSetHeight(pParse, pNew);
77195   return pNew;
77196 }
77197 
77198 /*
77199 ** Assign a variable number to an expression that encodes a wildcard
77200 ** in the original SQL statement.  
77201 **
77202 ** Wildcards consisting of a single "?" are assigned the next sequential
77203 ** variable number.
77204 **
77205 ** Wildcards of the form "?nnn" are assigned the number "nnn".  We make
77206 ** sure "nnn" is not too be to avoid a denial of service attack when
77207 ** the SQL statement comes from an external source.
77208 **
77209 ** Wildcards of the form ":aaa", "@aaa", or "$aaa" are assigned the same number
77210 ** as the previous instance of the same wildcard.  Or if this is the first
77211 ** instance of the wildcard, the next sequenial variable number is
77212 ** assigned.
77213 */
77214 SQLITE_PRIVATE void sqlite3ExprAssignVarNumber(Parse *pParse, Expr *pExpr){
77215   sqlite3 *db = pParse->db;
77216   const char *z;
77217 
77218   if( pExpr==0 ) return;
77219   assert( !ExprHasProperty(pExpr, EP_IntValue|EP_Reduced|EP_TokenOnly) );
77220   z = pExpr->u.zToken;
77221   assert( z!=0 );
77222   assert( z[0]!=0 );
77223   if( z[1]==0 ){
77224     /* Wildcard of the form "?".  Assign the next variable number */
77225     assert( z[0]=='?' );
77226     pExpr->iColumn = (ynVar)(++pParse->nVar);
77227   }else{
77228     ynVar x = 0;
77229     u32 n = sqlite3Strlen30(z);
77230     if( z[0]=='?' ){
77231       /* Wildcard of the form "?nnn".  Convert "nnn" to an integer and
77232       ** use it as the variable number */
77233       i64 i;
77234       int bOk = 0==sqlite3Atoi64(&z[1], &i, n-1, SQLITE_UTF8);
77235       pExpr->iColumn = x = (ynVar)i;
77236       testcase( i==0 );
77237       testcase( i==1 );
77238       testcase( i==db->aLimit[SQLITE_LIMIT_VARIABLE_NUMBER]-1 );
77239       testcase( i==db->aLimit[SQLITE_LIMIT_VARIABLE_NUMBER] );
77240       if( bOk==0 || i<1 || i>db->aLimit[SQLITE_LIMIT_VARIABLE_NUMBER] ){
77241         sqlite3ErrorMsg(pParse, "variable number must be between ?1 and ?%d",
77242             db->aLimit[SQLITE_LIMIT_VARIABLE_NUMBER]);
77243         x = 0;
77244       }
77245       if( i>pParse->nVar ){
77246         pParse->nVar = (int)i;
77247       }
77248     }else{
77249       /* Wildcards like ":aaa", "$aaa" or "@aaa".  Reuse the same variable
77250       ** number as the prior appearance of the same name, or if the name
77251       ** has never appeared before, reuse the same variable number
77252       */
77253       ynVar i;
77254       for(i=0; i<pParse->nzVar; i++){
77255         if( pParse->azVar[i] && strcmp(pParse->azVar[i],z)==0 ){
77256           pExpr->iColumn = x = (ynVar)i+1;
77257           break;
77258         }
77259       }
77260       if( x==0 ) x = pExpr->iColumn = (ynVar)(++pParse->nVar);
77261     }
77262     if( x>0 ){
77263       if( x>pParse->nzVar ){
77264         char **a;
77265         a = sqlite3DbRealloc(db, pParse->azVar, x*sizeof(a[0]));
77266         if( a==0 ) return;  /* Error reported through db->mallocFailed */
77267         pParse->azVar = a;
77268         memset(&a[pParse->nzVar], 0, (x-pParse->nzVar)*sizeof(a[0]));
77269         pParse->nzVar = x;
77270       }
77271       if( z[0]!='?' || pParse->azVar[x-1]==0 ){
77272         sqlite3DbFree(db, pParse->azVar[x-1]);
77273         pParse->azVar[x-1] = sqlite3DbStrNDup(db, z, n);
77274       }
77275     }
77276   } 
77277   if( !pParse->nErr && pParse->nVar>db->aLimit[SQLITE_LIMIT_VARIABLE_NUMBER] ){
77278     sqlite3ErrorMsg(pParse, "too many SQL variables");
77279   }
77280 }
77281 
77282 /*
77283 ** Recursively delete an expression tree.
77284 */
77285 SQLITE_PRIVATE void sqlite3ExprDelete(sqlite3 *db, Expr *p){
77286   if( p==0 ) return;
77287   /* Sanity check: Assert that the IntValue is non-negative if it exists */
77288   assert( !ExprHasProperty(p, EP_IntValue) || p->u.iValue>=0 );
77289   if( !ExprHasProperty(p, EP_TokenOnly) ){
77290     /* The Expr.x union is never used at the same time as Expr.pRight */
77291     assert( p->x.pList==0 || p->pRight==0 );
77292     sqlite3ExprDelete(db, p->pLeft);
77293     sqlite3ExprDelete(db, p->pRight);
77294     if( ExprHasProperty(p, EP_MemToken) ) sqlite3DbFree(db, p->u.zToken);
77295     if( ExprHasProperty(p, EP_xIsSelect) ){
77296       sqlite3SelectDelete(db, p->x.pSelect);
77297     }else{
77298       sqlite3ExprListDelete(db, p->x.pList);
77299     }
77300   }
77301   if( !ExprHasProperty(p, EP_Static) ){
77302     sqlite3DbFree(db, p);
77303   }
77304 }
77305 
77306 /*
77307 ** Return the number of bytes allocated for the expression structure 
77308 ** passed as the first argument. This is always one of EXPR_FULLSIZE,
77309 ** EXPR_REDUCEDSIZE or EXPR_TOKENONLYSIZE.
77310 */
77311 static int exprStructSize(Expr *p){
77312   if( ExprHasProperty(p, EP_TokenOnly) ) return EXPR_TOKENONLYSIZE;
77313   if( ExprHasProperty(p, EP_Reduced) ) return EXPR_REDUCEDSIZE;
77314   return EXPR_FULLSIZE;
77315 }
77316 
77317 /*
77318 ** The dupedExpr*Size() routines each return the number of bytes required
77319 ** to store a copy of an expression or expression tree.  They differ in
77320 ** how much of the tree is measured.
77321 **
77322 **     dupedExprStructSize()     Size of only the Expr structure 
77323 **     dupedExprNodeSize()       Size of Expr + space for token
77324 **     dupedExprSize()           Expr + token + subtree components
77325 **
77326 ***************************************************************************
77327 **
77328 ** The dupedExprStructSize() function returns two values OR-ed together:  
77329 ** (1) the space required for a copy of the Expr structure only and 
77330 ** (2) the EP_xxx flags that indicate what the structure size should be.
77331 ** The return values is always one of:
77332 **
77333 **      EXPR_FULLSIZE
77334 **      EXPR_REDUCEDSIZE   | EP_Reduced
77335 **      EXPR_TOKENONLYSIZE | EP_TokenOnly
77336 **
77337 ** The size of the structure can be found by masking the return value
77338 ** of this routine with 0xfff.  The flags can be found by masking the
77339 ** return value with EP_Reduced|EP_TokenOnly.
77340 **
77341 ** Note that with flags==EXPRDUP_REDUCE, this routines works on full-size
77342 ** (unreduced) Expr objects as they or originally constructed by the parser.
77343 ** During expression analysis, extra information is computed and moved into
77344 ** later parts of teh Expr object and that extra information might get chopped
77345 ** off if the expression is reduced.  Note also that it does not work to
77346 ** make a EXPRDUP_REDUCE copy of a reduced expression.  It is only legal
77347 ** to reduce a pristine expression tree from the parser.  The implementation
77348 ** of dupedExprStructSize() contain multiple assert() statements that attempt
77349 ** to enforce this constraint.
77350 */
77351 static int dupedExprStructSize(Expr *p, int flags){
77352   int nSize;
77353   assert( flags==EXPRDUP_REDUCE || flags==0 ); /* Only one flag value allowed */
77354   assert( EXPR_FULLSIZE<=0xfff );
77355   assert( (0xfff & (EP_Reduced|EP_TokenOnly))==0 );
77356   if( 0==(flags&EXPRDUP_REDUCE) ){
77357     nSize = EXPR_FULLSIZE;
77358   }else{
77359     assert( !ExprHasProperty(p, EP_TokenOnly|EP_Reduced) );
77360     assert( !ExprHasProperty(p, EP_FromJoin) ); 
77361     assert( !ExprHasProperty(p, EP_MemToken) );
77362     assert( !ExprHasProperty(p, EP_NoReduce) );
77363     if( p->pLeft || p->x.pList ){
77364       nSize = EXPR_REDUCEDSIZE | EP_Reduced;
77365     }else{
77366       assert( p->pRight==0 );
77367       nSize = EXPR_TOKENONLYSIZE | EP_TokenOnly;
77368     }
77369   }
77370   return nSize;
77371 }
77372 
77373 /*
77374 ** This function returns the space in bytes required to store the copy 
77375 ** of the Expr structure and a copy of the Expr.u.zToken string (if that
77376 ** string is defined.)
77377 */
77378 static int dupedExprNodeSize(Expr *p, int flags){
77379   int nByte = dupedExprStructSize(p, flags) & 0xfff;
77380   if( !ExprHasProperty(p, EP_IntValue) && p->u.zToken ){
77381     nByte += sqlite3Strlen30(p->u.zToken)+1;
77382   }
77383   return ROUND8(nByte);
77384 }
77385 
77386 /*
77387 ** Return the number of bytes required to create a duplicate of the 
77388 ** expression passed as the first argument. The second argument is a
77389 ** mask containing EXPRDUP_XXX flags.
77390 **
77391 ** The value returned includes space to create a copy of the Expr struct
77392 ** itself and the buffer referred to by Expr.u.zToken, if any.
77393 **
77394 ** If the EXPRDUP_REDUCE flag is set, then the return value includes 
77395 ** space to duplicate all Expr nodes in the tree formed by Expr.pLeft 
77396 ** and Expr.pRight variables (but not for any structures pointed to or 
77397 ** descended from the Expr.x.pList or Expr.x.pSelect variables).
77398 */
77399 static int dupedExprSize(Expr *p, int flags){
77400   int nByte = 0;
77401   if( p ){
77402     nByte = dupedExprNodeSize(p, flags);
77403     if( flags&EXPRDUP_REDUCE ){
77404       nByte += dupedExprSize(p->pLeft, flags) + dupedExprSize(p->pRight, flags);
77405     }
77406   }
77407   return nByte;
77408 }
77409 
77410 /*
77411 ** This function is similar to sqlite3ExprDup(), except that if pzBuffer 
77412 ** is not NULL then *pzBuffer is assumed to point to a buffer large enough 
77413 ** to store the copy of expression p, the copies of p->u.zToken
77414 ** (if applicable), and the copies of the p->pLeft and p->pRight expressions,
77415 ** if any. Before returning, *pzBuffer is set to the first byte passed the
77416 ** portion of the buffer copied into by this function.
77417 */
77418 static Expr *exprDup(sqlite3 *db, Expr *p, int flags, u8 **pzBuffer){
77419   Expr *pNew = 0;                      /* Value to return */
77420   if( p ){
77421     const int isReduced = (flags&EXPRDUP_REDUCE);
77422     u8 *zAlloc;
77423     u32 staticFlag = 0;
77424 
77425     assert( pzBuffer==0 || isReduced );
77426 
77427     /* Figure out where to write the new Expr structure. */
77428     if( pzBuffer ){
77429       zAlloc = *pzBuffer;
77430       staticFlag = EP_Static;
77431     }else{
77432       zAlloc = sqlite3DbMallocRaw(db, dupedExprSize(p, flags));
77433     }
77434     pNew = (Expr *)zAlloc;
77435 
77436     if( pNew ){
77437       /* Set nNewSize to the size allocated for the structure pointed to
77438       ** by pNew. This is either EXPR_FULLSIZE, EXPR_REDUCEDSIZE or
77439       ** EXPR_TOKENONLYSIZE. nToken is set to the number of bytes consumed
77440       ** by the copy of the p->u.zToken string (if any).
77441       */
77442       const unsigned nStructSize = dupedExprStructSize(p, flags);
77443       const int nNewSize = nStructSize & 0xfff;
77444       int nToken;
77445       if( !ExprHasProperty(p, EP_IntValue) && p->u.zToken ){
77446         nToken = sqlite3Strlen30(p->u.zToken) + 1;
77447       }else{
77448         nToken = 0;
77449       }
77450       if( isReduced ){
77451         assert( ExprHasProperty(p, EP_Reduced)==0 );
77452         memcpy(zAlloc, p, nNewSize);
77453       }else{
77454         int nSize = exprStructSize(p);
77455         memcpy(zAlloc, p, nSize);
77456         memset(&zAlloc[nSize], 0, EXPR_FULLSIZE-nSize);
77457       }
77458 
77459       /* Set the EP_Reduced, EP_TokenOnly, and EP_Static flags appropriately. */
77460       pNew->flags &= ~(EP_Reduced|EP_TokenOnly|EP_Static|EP_MemToken);
77461       pNew->flags |= nStructSize & (EP_Reduced|EP_TokenOnly);
77462       pNew->flags |= staticFlag;
77463 
77464       /* Copy the p->u.zToken string, if any. */
77465       if( nToken ){
77466         char *zToken = pNew->u.zToken = (char*)&zAlloc[nNewSize];
77467         memcpy(zToken, p->u.zToken, nToken);
77468       }
77469 
77470       if( 0==((p->flags|pNew->flags) & EP_TokenOnly) ){
77471         /* Fill in the pNew->x.pSelect or pNew->x.pList member. */
77472         if( ExprHasProperty(p, EP_xIsSelect) ){
77473           pNew->x.pSelect = sqlite3SelectDup(db, p->x.pSelect, isReduced);
77474         }else{
77475           pNew->x.pList = sqlite3ExprListDup(db, p->x.pList, isReduced);
77476         }
77477       }
77478 
77479       /* Fill in pNew->pLeft and pNew->pRight. */
77480       if( ExprHasProperty(pNew, EP_Reduced|EP_TokenOnly) ){
77481         zAlloc += dupedExprNodeSize(p, flags);
77482         if( ExprHasProperty(pNew, EP_Reduced) ){
77483           pNew->pLeft = exprDup(db, p->pLeft, EXPRDUP_REDUCE, &zAlloc);
77484           pNew->pRight = exprDup(db, p->pRight, EXPRDUP_REDUCE, &zAlloc);
77485         }
77486         if( pzBuffer ){
77487           *pzBuffer = zAlloc;
77488         }
77489       }else{
77490         if( !ExprHasProperty(p, EP_TokenOnly) ){
77491           pNew->pLeft = sqlite3ExprDup(db, p->pLeft, 0);
77492           pNew->pRight = sqlite3ExprDup(db, p->pRight, 0);
77493         }
77494       }
77495 
77496     }
77497   }
77498   return pNew;
77499 }
77500 
77501 /*
77502 ** The following group of routines make deep copies of expressions,
77503 ** expression lists, ID lists, and select statements.  The copies can
77504 ** be deleted (by being passed to their respective ...Delete() routines)
77505 ** without effecting the originals.
77506 **
77507 ** The expression list, ID, and source lists return by sqlite3ExprListDup(),
77508 ** sqlite3IdListDup(), and sqlite3SrcListDup() can not be further expanded 
77509 ** by subsequent calls to sqlite*ListAppend() routines.
77510 **
77511 ** Any tables that the SrcList might point to are not duplicated.
77512 **
77513 ** The flags parameter contains a combination of the EXPRDUP_XXX flags.
77514 ** If the EXPRDUP_REDUCE flag is set, then the structure returned is a
77515 ** truncated version of the usual Expr structure that will be stored as
77516 ** part of the in-memory representation of the database schema.
77517 */
77518 SQLITE_PRIVATE Expr *sqlite3ExprDup(sqlite3 *db, Expr *p, int flags){
77519   return exprDup(db, p, flags, 0);
77520 }
77521 SQLITE_PRIVATE ExprList *sqlite3ExprListDup(sqlite3 *db, ExprList *p, int flags){
77522   ExprList *pNew;
77523   struct ExprList_item *pItem, *pOldItem;
77524   int i;
77525   if( p==0 ) return 0;
77526   pNew = sqlite3DbMallocRaw(db, sizeof(*pNew) );
77527   if( pNew==0 ) return 0;
77528   pNew->iECursor = 0;
77529   pNew->nExpr = i = p->nExpr;
77530   if( (flags & EXPRDUP_REDUCE)==0 ) for(i=1; i<p->nExpr; i+=i){}
77531   pNew->a = pItem = sqlite3DbMallocRaw(db,  i*sizeof(p->a[0]) );
77532   if( pItem==0 ){
77533     sqlite3DbFree(db, pNew);
77534     return 0;
77535   } 
77536   pOldItem = p->a;
77537   for(i=0; i<p->nExpr; i++, pItem++, pOldItem++){
77538     Expr *pOldExpr = pOldItem->pExpr;
77539     pItem->pExpr = sqlite3ExprDup(db, pOldExpr, flags);
77540     pItem->zName = sqlite3DbStrDup(db, pOldItem->zName);
77541     pItem->zSpan = sqlite3DbStrDup(db, pOldItem->zSpan);
77542     pItem->sortOrder = pOldItem->sortOrder;
77543     pItem->done = 0;
77544     pItem->bSpanIsTab = pOldItem->bSpanIsTab;
77545     pItem->u = pOldItem->u;
77546   }
77547   return pNew;
77548 }
77549 
77550 /*
77551 ** If cursors, triggers, views and subqueries are all omitted from
77552 ** the build, then none of the following routines, except for 
77553 ** sqlite3SelectDup(), can be called. sqlite3SelectDup() is sometimes
77554 ** called with a NULL argument.
77555 */
77556 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_TRIGGER) \
77557  || !defined(SQLITE_OMIT_SUBQUERY)
77558 SQLITE_PRIVATE SrcList *sqlite3SrcListDup(sqlite3 *db, SrcList *p, int flags){
77559   SrcList *pNew;
77560   int i;
77561   int nByte;
77562   if( p==0 ) return 0;
77563   nByte = sizeof(*p) + (p->nSrc>0 ? sizeof(p->a[0]) * (p->nSrc-1) : 0);
77564   pNew = sqlite3DbMallocRaw(db, nByte );
77565   if( pNew==0 ) return 0;
77566   pNew->nSrc = pNew->nAlloc = p->nSrc;
77567   for(i=0; i<p->nSrc; i++){
77568     struct SrcList_item *pNewItem = &pNew->a[i];
77569     struct SrcList_item *pOldItem = &p->a[i];
77570     Table *pTab;
77571     pNewItem->pSchema = pOldItem->pSchema;
77572     pNewItem->zDatabase = sqlite3DbStrDup(db, pOldItem->zDatabase);
77573     pNewItem->zName = sqlite3DbStrDup(db, pOldItem->zName);
77574     pNewItem->zAlias = sqlite3DbStrDup(db, pOldItem->zAlias);
77575     pNewItem->jointype = pOldItem->jointype;
77576     pNewItem->iCursor = pOldItem->iCursor;
77577     pNewItem->addrFillSub = pOldItem->addrFillSub;
77578     pNewItem->regReturn = pOldItem->regReturn;
77579     pNewItem->isCorrelated = pOldItem->isCorrelated;
77580     pNewItem->viaCoroutine = pOldItem->viaCoroutine;
77581     pNewItem->zIndex = sqlite3DbStrDup(db, pOldItem->zIndex);
77582     pNewItem->notIndexed = pOldItem->notIndexed;
77583     pNewItem->pIndex = pOldItem->pIndex;
77584     pTab = pNewItem->pTab = pOldItem->pTab;
77585     if( pTab ){
77586       pTab->nRef++;
77587     }
77588     pNewItem->pSelect = sqlite3SelectDup(db, pOldItem->pSelect, flags);
77589     pNewItem->pOn = sqlite3ExprDup(db, pOldItem->pOn, flags);
77590     pNewItem->pUsing = sqlite3IdListDup(db, pOldItem->pUsing);
77591     pNewItem->colUsed = pOldItem->colUsed;
77592   }
77593   return pNew;
77594 }
77595 SQLITE_PRIVATE IdList *sqlite3IdListDup(sqlite3 *db, IdList *p){
77596   IdList *pNew;
77597   int i;
77598   if( p==0 ) return 0;
77599   pNew = sqlite3DbMallocRaw(db, sizeof(*pNew) );
77600   if( pNew==0 ) return 0;
77601   pNew->nId = p->nId;
77602   pNew->a = sqlite3DbMallocRaw(db, p->nId*sizeof(p->a[0]) );
77603   if( pNew->a==0 ){
77604     sqlite3DbFree(db, pNew);
77605     return 0;
77606   }
77607   /* Note that because the size of the allocation for p->a[] is not
77608   ** necessarily a power of two, sqlite3IdListAppend() may not be called
77609   ** on the duplicate created by this function. */
77610   for(i=0; i<p->nId; i++){
77611     struct IdList_item *pNewItem = &pNew->a[i];
77612     struct IdList_item *pOldItem = &p->a[i];
77613     pNewItem->zName = sqlite3DbStrDup(db, pOldItem->zName);
77614     pNewItem->idx = pOldItem->idx;
77615   }
77616   return pNew;
77617 }
77618 SQLITE_PRIVATE Select *sqlite3SelectDup(sqlite3 *db, Select *p, int flags){
77619   Select *pNew, *pPrior;
77620   if( p==0 ) return 0;
77621   pNew = sqlite3DbMallocRaw(db, sizeof(*p) );
77622   if( pNew==0 ) return 0;
77623   pNew->pEList = sqlite3ExprListDup(db, p->pEList, flags);
77624   pNew->pSrc = sqlite3SrcListDup(db, p->pSrc, flags);
77625   pNew->pWhere = sqlite3ExprDup(db, p->pWhere, flags);
77626   pNew->pGroupBy = sqlite3ExprListDup(db, p->pGroupBy, flags);
77627   pNew->pHaving = sqlite3ExprDup(db, p->pHaving, flags);
77628   pNew->pOrderBy = sqlite3ExprListDup(db, p->pOrderBy, flags);
77629   pNew->op = p->op;
77630   pNew->pPrior = pPrior = sqlite3SelectDup(db, p->pPrior, flags);
77631   if( pPrior ) pPrior->pNext = pNew;
77632   pNew->pNext = 0;
77633   pNew->pLimit = sqlite3ExprDup(db, p->pLimit, flags);
77634   pNew->pOffset = sqlite3ExprDup(db, p->pOffset, flags);
77635   pNew->iLimit = 0;
77636   pNew->iOffset = 0;
77637   pNew->selFlags = p->selFlags & ~SF_UsesEphemeral;
77638   pNew->pRightmost = 0;
77639   pNew->addrOpenEphm[0] = -1;
77640   pNew->addrOpenEphm[1] = -1;
77641   pNew->addrOpenEphm[2] = -1;
77642   return pNew;
77643 }
77644 #else
77645 SQLITE_PRIVATE Select *sqlite3SelectDup(sqlite3 *db, Select *p, int flags){
77646   assert( p==0 );
77647   return 0;
77648 }
77649 #endif
77650 
77651 
77652 /*
77653 ** Add a new element to the end of an expression list.  If pList is
77654 ** initially NULL, then create a new expression list.
77655 **
77656 ** If a memory allocation error occurs, the entire list is freed and
77657 ** NULL is returned.  If non-NULL is returned, then it is guaranteed
77658 ** that the new entry was successfully appended.
77659 */
77660 SQLITE_PRIVATE ExprList *sqlite3ExprListAppend(
77661   Parse *pParse,          /* Parsing context */
77662   ExprList *pList,        /* List to which to append. Might be NULL */
77663   Expr *pExpr             /* Expression to be appended. Might be NULL */
77664 ){
77665   sqlite3 *db = pParse->db;
77666   if( pList==0 ){
77667     pList = sqlite3DbMallocZero(db, sizeof(ExprList) );
77668     if( pList==0 ){
77669       goto no_mem;
77670     }
77671     pList->a = sqlite3DbMallocRaw(db, sizeof(pList->a[0]));
77672     if( pList->a==0 ) goto no_mem;
77673   }else if( (pList->nExpr & (pList->nExpr-1))==0 ){
77674     struct ExprList_item *a;
77675     assert( pList->nExpr>0 );
77676     a = sqlite3DbRealloc(db, pList->a, pList->nExpr*2*sizeof(pList->a[0]));
77677     if( a==0 ){
77678       goto no_mem;
77679     }
77680     pList->a = a;
77681   }
77682   assert( pList->a!=0 );
77683   if( 1 ){
77684     struct ExprList_item *pItem = &pList->a[pList->nExpr++];
77685     memset(pItem, 0, sizeof(*pItem));
77686     pItem->pExpr = pExpr;
77687   }
77688   return pList;
77689 
77690 no_mem:     
77691   /* Avoid leaking memory if malloc has failed. */
77692   sqlite3ExprDelete(db, pExpr);
77693   sqlite3ExprListDelete(db, pList);
77694   return 0;
77695 }
77696 
77697 /*
77698 ** Set the ExprList.a[].zName element of the most recently added item
77699 ** on the expression list.
77700 **
77701 ** pList might be NULL following an OOM error.  But pName should never be
77702 ** NULL.  If a memory allocation fails, the pParse->db->mallocFailed flag
77703 ** is set.
77704 */
77705 SQLITE_PRIVATE void sqlite3ExprListSetName(
77706   Parse *pParse,          /* Parsing context */
77707   ExprList *pList,        /* List to which to add the span. */
77708   Token *pName,           /* Name to be added */
77709   int dequote             /* True to cause the name to be dequoted */
77710 ){
77711   assert( pList!=0 || pParse->db->mallocFailed!=0 );
77712   if( pList ){
77713     struct ExprList_item *pItem;
77714     assert( pList->nExpr>0 );
77715     pItem = &pList->a[pList->nExpr-1];
77716     assert( pItem->zName==0 );
77717     pItem->zName = sqlite3DbStrNDup(pParse->db, pName->z, pName->n);
77718     if( dequote && pItem->zName ) sqlite3Dequote(pItem->zName);
77719   }
77720 }
77721 
77722 /*
77723 ** Set the ExprList.a[].zSpan element of the most recently added item
77724 ** on the expression list.
77725 **
77726 ** pList might be NULL following an OOM error.  But pSpan should never be
77727 ** NULL.  If a memory allocation fails, the pParse->db->mallocFailed flag
77728 ** is set.
77729 */
77730 SQLITE_PRIVATE void sqlite3ExprListSetSpan(
77731   Parse *pParse,          /* Parsing context */
77732   ExprList *pList,        /* List to which to add the span. */
77733   ExprSpan *pSpan         /* The span to be added */
77734 ){
77735   sqlite3 *db = pParse->db;
77736   assert( pList!=0 || db->mallocFailed!=0 );
77737   if( pList ){
77738     struct ExprList_item *pItem = &pList->a[pList->nExpr-1];
77739     assert( pList->nExpr>0 );
77740     assert( db->mallocFailed || pItem->pExpr==pSpan->pExpr );
77741     sqlite3DbFree(db, pItem->zSpan);
77742     pItem->zSpan = sqlite3DbStrNDup(db, (char*)pSpan->zStart,
77743                                     (int)(pSpan->zEnd - pSpan->zStart));
77744   }
77745 }
77746 
77747 /*
77748 ** If the expression list pEList contains more than iLimit elements,
77749 ** leave an error message in pParse.
77750 */
77751 SQLITE_PRIVATE void sqlite3ExprListCheckLength(
77752   Parse *pParse,
77753   ExprList *pEList,
77754   const char *zObject
77755 ){
77756   int mx = pParse->db->aLimit[SQLITE_LIMIT_COLUMN];
77757   testcase( pEList && pEList->nExpr==mx );
77758   testcase( pEList && pEList->nExpr==mx+1 );
77759   if( pEList && pEList->nExpr>mx ){
77760     sqlite3ErrorMsg(pParse, "too many columns in %s", zObject);
77761   }
77762 }
77763 
77764 /*
77765 ** Delete an entire expression list.
77766 */
77767 SQLITE_PRIVATE void sqlite3ExprListDelete(sqlite3 *db, ExprList *pList){
77768   int i;
77769   struct ExprList_item *pItem;
77770   if( pList==0 ) return;
77771   assert( pList->a!=0 || pList->nExpr==0 );
77772   for(pItem=pList->a, i=0; i<pList->nExpr; i++, pItem++){
77773     sqlite3ExprDelete(db, pItem->pExpr);
77774     sqlite3DbFree(db, pItem->zName);
77775     sqlite3DbFree(db, pItem->zSpan);
77776   }
77777   sqlite3DbFree(db, pList->a);
77778   sqlite3DbFree(db, pList);
77779 }
77780 
77781 /*
77782 ** These routines are Walker callbacks.  Walker.u.pi is a pointer
77783 ** to an integer.  These routines are checking an expression to see
77784 ** if it is a constant.  Set *Walker.u.pi to 0 if the expression is
77785 ** not constant.
77786 **
77787 ** These callback routines are used to implement the following:
77788 **
77789 **     sqlite3ExprIsConstant()
77790 **     sqlite3ExprIsConstantNotJoin()
77791 **     sqlite3ExprIsConstantOrFunction()
77792 **
77793 */
77794 static int exprNodeIsConstant(Walker *pWalker, Expr *pExpr){
77795 
77796   /* If pWalker->u.i is 3 then any term of the expression that comes from
77797   ** the ON or USING clauses of a join disqualifies the expression
77798   ** from being considered constant. */
77799   if( pWalker->u.i==3 && ExprHasProperty(pExpr, EP_FromJoin) ){
77800     pWalker->u.i = 0;
77801     return WRC_Abort;
77802   }
77803 
77804   switch( pExpr->op ){
77805     /* Consider functions to be constant if all their arguments are constant
77806     ** and either pWalker->u.i==2 or the function as the SQLITE_FUNC_CONST
77807     ** flag. */
77808     case TK_FUNCTION:
77809       if( pWalker->u.i==2 || ExprHasProperty(pExpr,EP_Constant) ){
77810         return WRC_Continue;
77811       }
77812       /* Fall through */
77813     case TK_ID:
77814     case TK_COLUMN:
77815     case TK_AGG_FUNCTION:
77816     case TK_AGG_COLUMN:
77817       testcase( pExpr->op==TK_ID );
77818       testcase( pExpr->op==TK_COLUMN );
77819       testcase( pExpr->op==TK_AGG_FUNCTION );
77820       testcase( pExpr->op==TK_AGG_COLUMN );
77821       pWalker->u.i = 0;
77822       return WRC_Abort;
77823     default:
77824       testcase( pExpr->op==TK_SELECT ); /* selectNodeIsConstant will disallow */
77825       testcase( pExpr->op==TK_EXISTS ); /* selectNodeIsConstant will disallow */
77826       return WRC_Continue;
77827   }
77828 }
77829 static int selectNodeIsConstant(Walker *pWalker, Select *NotUsed){
77830   UNUSED_PARAMETER(NotUsed);
77831   pWalker->u.i = 0;
77832   return WRC_Abort;
77833 }
77834 static int exprIsConst(Expr *p, int initFlag){
77835   Walker w;
77836   memset(&w, 0, sizeof(w));
77837   w.u.i = initFlag;
77838   w.xExprCallback = exprNodeIsConstant;
77839   w.xSelectCallback = selectNodeIsConstant;
77840   sqlite3WalkExpr(&w, p);
77841   return w.u.i;
77842 }
77843 
77844 /*
77845 ** Walk an expression tree.  Return 1 if the expression is constant
77846 ** and 0 if it involves variables or function calls.
77847 **
77848 ** For the purposes of this function, a double-quoted string (ex: "abc")
77849 ** is considered a variable but a single-quoted string (ex: 'abc') is
77850 ** a constant.
77851 */
77852 SQLITE_PRIVATE int sqlite3ExprIsConstant(Expr *p){
77853   return exprIsConst(p, 1);
77854 }
77855 
77856 /*
77857 ** Walk an expression tree.  Return 1 if the expression is constant
77858 ** that does no originate from the ON or USING clauses of a join.
77859 ** Return 0 if it involves variables or function calls or terms from
77860 ** an ON or USING clause.
77861 */
77862 SQLITE_PRIVATE int sqlite3ExprIsConstantNotJoin(Expr *p){
77863   return exprIsConst(p, 3);
77864 }
77865 
77866 /*
77867 ** Walk an expression tree.  Return 1 if the expression is constant
77868 ** or a function call with constant arguments.  Return and 0 if there
77869 ** are any variables.
77870 **
77871 ** For the purposes of this function, a double-quoted string (ex: "abc")
77872 ** is considered a variable but a single-quoted string (ex: 'abc') is
77873 ** a constant.
77874 */
77875 SQLITE_PRIVATE int sqlite3ExprIsConstantOrFunction(Expr *p){
77876   return exprIsConst(p, 2);
77877 }
77878 
77879 /*
77880 ** If the expression p codes a constant integer that is small enough
77881 ** to fit in a 32-bit integer, return 1 and put the value of the integer
77882 ** in *pValue.  If the expression is not an integer or if it is too big
77883 ** to fit in a signed 32-bit integer, return 0 and leave *pValue unchanged.
77884 */
77885 SQLITE_PRIVATE int sqlite3ExprIsInteger(Expr *p, int *pValue){
77886   int rc = 0;
77887 
77888   /* If an expression is an integer literal that fits in a signed 32-bit
77889   ** integer, then the EP_IntValue flag will have already been set */
77890   assert( p->op!=TK_INTEGER || (p->flags & EP_IntValue)!=0
77891            || sqlite3GetInt32(p->u.zToken, &rc)==0 );
77892 
77893   if( p->flags & EP_IntValue ){
77894     *pValue = p->u.iValue;
77895     return 1;
77896   }
77897   switch( p->op ){
77898     case TK_UPLUS: {
77899       rc = sqlite3ExprIsInteger(p->pLeft, pValue);
77900       break;
77901     }
77902     case TK_UMINUS: {
77903       int v;
77904       if( sqlite3ExprIsInteger(p->pLeft, &v) ){
77905         assert( v!=(-2147483647-1) );
77906         *pValue = -v;
77907         rc = 1;
77908       }
77909       break;
77910     }
77911     default: break;
77912   }
77913   return rc;
77914 }
77915 
77916 /*
77917 ** Return FALSE if there is no chance that the expression can be NULL.
77918 **
77919 ** If the expression might be NULL or if the expression is too complex
77920 ** to tell return TRUE.  
77921 **
77922 ** This routine is used as an optimization, to skip OP_IsNull opcodes
77923 ** when we know that a value cannot be NULL.  Hence, a false positive
77924 ** (returning TRUE when in fact the expression can never be NULL) might
77925 ** be a small performance hit but is otherwise harmless.  On the other
77926 ** hand, a false negative (returning FALSE when the result could be NULL)
77927 ** will likely result in an incorrect answer.  So when in doubt, return
77928 ** TRUE.
77929 */
77930 SQLITE_PRIVATE int sqlite3ExprCanBeNull(const Expr *p){
77931   u8 op;
77932   while( p->op==TK_UPLUS || p->op==TK_UMINUS ){ p = p->pLeft; }
77933   op = p->op;
77934   if( op==TK_REGISTER ) op = p->op2;
77935   switch( op ){
77936     case TK_INTEGER:
77937     case TK_STRING:
77938     case TK_FLOAT:
77939     case TK_BLOB:
77940       return 0;
77941     default:
77942       return 1;
77943   }
77944 }
77945 
77946 /*
77947 ** Generate an OP_IsNull instruction that tests register iReg and jumps
77948 ** to location iDest if the value in iReg is NULL.  The value in iReg 
77949 ** was computed by pExpr.  If we can look at pExpr at compile-time and
77950 ** determine that it can never generate a NULL, then the OP_IsNull operation
77951 ** can be omitted.
77952 */
77953 SQLITE_PRIVATE void sqlite3ExprCodeIsNullJump(
77954   Vdbe *v,            /* The VDBE under construction */
77955   const Expr *pExpr,  /* Only generate OP_IsNull if this expr can be NULL */
77956   int iReg,           /* Test the value in this register for NULL */
77957   int iDest           /* Jump here if the value is null */
77958 ){
77959   if( sqlite3ExprCanBeNull(pExpr) ){
77960     sqlite3VdbeAddOp2(v, OP_IsNull, iReg, iDest);
77961   }
77962 }
77963 
77964 /*
77965 ** Return TRUE if the given expression is a constant which would be
77966 ** unchanged by OP_Affinity with the affinity given in the second
77967 ** argument.
77968 **
77969 ** This routine is used to determine if the OP_Affinity operation
77970 ** can be omitted.  When in doubt return FALSE.  A false negative
77971 ** is harmless.  A false positive, however, can result in the wrong
77972 ** answer.
77973 */
77974 SQLITE_PRIVATE int sqlite3ExprNeedsNoAffinityChange(const Expr *p, char aff){
77975   u8 op;
77976   if( aff==SQLITE_AFF_NONE ) return 1;
77977   while( p->op==TK_UPLUS || p->op==TK_UMINUS ){ p = p->pLeft; }
77978   op = p->op;
77979   if( op==TK_REGISTER ) op = p->op2;
77980   switch( op ){
77981     case TK_INTEGER: {
77982       return aff==SQLITE_AFF_INTEGER || aff==SQLITE_AFF_NUMERIC;
77983     }
77984     case TK_FLOAT: {
77985       return aff==SQLITE_AFF_REAL || aff==SQLITE_AFF_NUMERIC;
77986     }
77987     case TK_STRING: {
77988       return aff==SQLITE_AFF_TEXT;
77989     }
77990     case TK_BLOB: {
77991       return 1;
77992     }
77993     case TK_COLUMN: {
77994       assert( p->iTable>=0 );  /* p cannot be part of a CHECK constraint */
77995       return p->iColumn<0
77996           && (aff==SQLITE_AFF_INTEGER || aff==SQLITE_AFF_NUMERIC);
77997     }
77998     default: {
77999       return 0;
78000     }
78001   }
78002 }
78003 
78004 /*
78005 ** Return TRUE if the given string is a row-id column name.
78006 */
78007 SQLITE_PRIVATE int sqlite3IsRowid(const char *z){
78008   if( sqlite3StrICmp(z, "_ROWID_")==0 ) return 1;
78009   if( sqlite3StrICmp(z, "ROWID")==0 ) return 1;
78010   if( sqlite3StrICmp(z, "OID")==0 ) return 1;
78011   return 0;
78012 }
78013 
78014 /*
78015 ** Return true if we are able to the IN operator optimization on a
78016 ** query of the form
78017 **
78018 **       x IN (SELECT ...)
78019 **
78020 ** Where the SELECT... clause is as specified by the parameter to this
78021 ** routine.
78022 **
78023 ** The Select object passed in has already been preprocessed and no
78024 ** errors have been found.
78025 */
78026 #ifndef SQLITE_OMIT_SUBQUERY
78027 static int isCandidateForInOpt(Select *p){
78028   SrcList *pSrc;
78029   ExprList *pEList;
78030   Table *pTab;
78031   if( p==0 ) return 0;                   /* right-hand side of IN is SELECT */
78032   if( p->pPrior ) return 0;              /* Not a compound SELECT */
78033   if( p->selFlags & (SF_Distinct|SF_Aggregate) ){
78034     testcase( (p->selFlags & (SF_Distinct|SF_Aggregate))==SF_Distinct );
78035     testcase( (p->selFlags & (SF_Distinct|SF_Aggregate))==SF_Aggregate );
78036     return 0; /* No DISTINCT keyword and no aggregate functions */
78037   }
78038   assert( p->pGroupBy==0 );              /* Has no GROUP BY clause */
78039   if( p->pLimit ) return 0;              /* Has no LIMIT clause */
78040   assert( p->pOffset==0 );               /* No LIMIT means no OFFSET */
78041   if( p->pWhere ) return 0;              /* Has no WHERE clause */
78042   pSrc = p->pSrc;
78043   assert( pSrc!=0 );
78044   if( pSrc->nSrc!=1 ) return 0;          /* Single term in FROM clause */
78045   if( pSrc->a[0].pSelect ) return 0;     /* FROM is not a subquery or view */
78046   pTab = pSrc->a[0].pTab;
78047   if( NEVER(pTab==0) ) return 0;
78048   assert( pTab->pSelect==0 );            /* FROM clause is not a view */
78049   if( IsVirtual(pTab) ) return 0;        /* FROM clause not a virtual table */
78050   pEList = p->pEList;
78051   if( pEList->nExpr!=1 ) return 0;       /* One column in the result set */
78052   if( pEList->a[0].pExpr->op!=TK_COLUMN ) return 0; /* Result is a column */
78053   return 1;
78054 }
78055 #endif /* SQLITE_OMIT_SUBQUERY */
78056 
78057 /*
78058 ** Code an OP_Once instruction and allocate space for its flag. Return the 
78059 ** address of the new instruction.
78060 */
78061 SQLITE_PRIVATE int sqlite3CodeOnce(Parse *pParse){
78062   Vdbe *v = sqlite3GetVdbe(pParse);      /* Virtual machine being coded */
78063   return sqlite3VdbeAddOp1(v, OP_Once, pParse->nOnce++);
78064 }
78065 
78066 /*
78067 ** This function is used by the implementation of the IN (...) operator.
78068 ** The pX parameter is the expression on the RHS of the IN operator, which
78069 ** might be either a list of expressions or a subquery.
78070 **
78071 ** The job of this routine is to find or create a b-tree object that can
78072 ** be used either to test for membership in the RHS set or to iterate through
78073 ** all members of the RHS set, skipping duplicates.
78074 **
78075 ** A cursor is opened on the b-tree object that the RHS of the IN operator
78076 ** and pX->iTable is set to the index of that cursor.
78077 **
78078 ** The returned value of this function indicates the b-tree type, as follows:
78079 **
78080 **   IN_INDEX_ROWID      - The cursor was opened on a database table.
78081 **   IN_INDEX_INDEX_ASC  - The cursor was opened on an ascending index.
78082 **   IN_INDEX_INDEX_DESC - The cursor was opened on a descending index.
78083 **   IN_INDEX_EPH        - The cursor was opened on a specially created and
78084 **                         populated epheremal table.
78085 **
78086 ** An existing b-tree might be used if the RHS expression pX is a simple
78087 ** subquery such as:
78088 **
78089 **     SELECT <column> FROM <table>
78090 **
78091 ** If the RHS of the IN operator is a list or a more complex subquery, then
78092 ** an ephemeral table might need to be generated from the RHS and then
78093 ** pX->iTable made to point to the ephermeral table instead of an
78094 ** existing table.  
78095 **
78096 ** If the prNotFound parameter is 0, then the b-tree will be used to iterate
78097 ** through the set members, skipping any duplicates. In this case an
78098 ** epheremal table must be used unless the selected <column> is guaranteed
78099 ** to be unique - either because it is an INTEGER PRIMARY KEY or it
78100 ** has a UNIQUE constraint or UNIQUE index.
78101 **
78102 ** If the prNotFound parameter is not 0, then the b-tree will be used 
78103 ** for fast set membership tests. In this case an epheremal table must 
78104 ** be used unless <column> is an INTEGER PRIMARY KEY or an index can 
78105 ** be found with <column> as its left-most column.
78106 **
78107 ** When the b-tree is being used for membership tests, the calling function
78108 ** needs to know whether or not the structure contains an SQL NULL 
78109 ** value in order to correctly evaluate expressions like "X IN (Y, Z)".
78110 ** If there is any chance that the (...) might contain a NULL value at
78111 ** runtime, then a register is allocated and the register number written
78112 ** to *prNotFound. If there is no chance that the (...) contains a
78113 ** NULL value, then *prNotFound is left unchanged.
78114 **
78115 ** If a register is allocated and its location stored in *prNotFound, then
78116 ** its initial value is NULL.  If the (...) does not remain constant
78117 ** for the duration of the query (i.e. the SELECT within the (...)
78118 ** is a correlated subquery) then the value of the allocated register is
78119 ** reset to NULL each time the subquery is rerun. This allows the
78120 ** caller to use vdbe code equivalent to the following:
78121 **
78122 **   if( register==NULL ){
78123 **     has_null = <test if data structure contains null>
78124 **     register = 1
78125 **   }
78126 **
78127 ** in order to avoid running the <test if data structure contains null>
78128 ** test more often than is necessary.
78129 */
78130 #ifndef SQLITE_OMIT_SUBQUERY
78131 SQLITE_PRIVATE int sqlite3FindInIndex(Parse *pParse, Expr *pX, int *prNotFound){
78132   Select *p;                            /* SELECT to the right of IN operator */
78133   int eType = 0;                        /* Type of RHS table. IN_INDEX_* */
78134   int iTab = pParse->nTab++;            /* Cursor of the RHS table */
78135   int mustBeUnique = (prNotFound==0);   /* True if RHS must be unique */
78136   Vdbe *v = sqlite3GetVdbe(pParse);     /* Virtual machine being coded */
78137 
78138   assert( pX->op==TK_IN );
78139 
78140   /* Check to see if an existing table or index can be used to
78141   ** satisfy the query.  This is preferable to generating a new 
78142   ** ephemeral table.
78143   */
78144   p = (ExprHasProperty(pX, EP_xIsSelect) ? pX->x.pSelect : 0);
78145   if( ALWAYS(pParse->nErr==0) && isCandidateForInOpt(p) ){
78146     sqlite3 *db = pParse->db;              /* Database connection */
78147     Table *pTab;                           /* Table <table>. */
78148     Expr *pExpr;                           /* Expression <column> */
78149     i16 iCol;                              /* Index of column <column> */
78150     i16 iDb;                               /* Database idx for pTab */
78151 
78152     assert( p );                        /* Because of isCandidateForInOpt(p) */
78153     assert( p->pEList!=0 );             /* Because of isCandidateForInOpt(p) */
78154     assert( p->pEList->a[0].pExpr!=0 ); /* Because of isCandidateForInOpt(p) */
78155     assert( p->pSrc!=0 );               /* Because of isCandidateForInOpt(p) */
78156     pTab = p->pSrc->a[0].pTab;
78157     pExpr = p->pEList->a[0].pExpr;
78158     iCol = (i16)pExpr->iColumn;
78159    
78160     /* Code an OP_VerifyCookie and OP_TableLock for <table>. */
78161     iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
78162     sqlite3CodeVerifySchema(pParse, iDb);
78163     sqlite3TableLock(pParse, iDb, pTab->tnum, 0, pTab->zName);
78164 
78165     /* This function is only called from two places. In both cases the vdbe
78166     ** has already been allocated. So assume sqlite3GetVdbe() is always
78167     ** successful here.
78168     */
78169     assert(v);
78170     if( iCol<0 ){
78171       int iAddr;
78172 
78173       iAddr = sqlite3CodeOnce(pParse);
78174 
78175       sqlite3OpenTable(pParse, iTab, iDb, pTab, OP_OpenRead);
78176       eType = IN_INDEX_ROWID;
78177 
78178       sqlite3VdbeJumpHere(v, iAddr);
78179     }else{
78180       Index *pIdx;                         /* Iterator variable */
78181 
78182       /* The collation sequence used by the comparison. If an index is to
78183       ** be used in place of a temp-table, it must be ordered according
78184       ** to this collation sequence.  */
78185       CollSeq *pReq = sqlite3BinaryCompareCollSeq(pParse, pX->pLeft, pExpr);
78186 
78187       /* Check that the affinity that will be used to perform the 
78188       ** comparison is the same as the affinity of the column. If
78189       ** it is not, it is not possible to use any index.
78190       */
78191       int affinity_ok = sqlite3IndexAffinityOk(pX, pTab->aCol[iCol].affinity);
78192 
78193       for(pIdx=pTab->pIndex; pIdx && eType==0 && affinity_ok; pIdx=pIdx->pNext){
78194         if( (pIdx->aiColumn[0]==iCol)
78195          && sqlite3FindCollSeq(db, ENC(db), pIdx->azColl[0], 0)==pReq
78196          && (!mustBeUnique || (pIdx->nKeyCol==1 && pIdx->onError!=OE_None))
78197         ){
78198           int iAddr = sqlite3CodeOnce(pParse);
78199           sqlite3VdbeAddOp3(v, OP_OpenRead, iTab, pIdx->tnum, iDb);
78200           sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
78201           VdbeComment((v, "%s", pIdx->zName));
78202           assert( IN_INDEX_INDEX_DESC == IN_INDEX_INDEX_ASC+1 );
78203           eType = IN_INDEX_INDEX_ASC + pIdx->aSortOrder[0];
78204 
78205           sqlite3VdbeJumpHere(v, iAddr);
78206           if( prNotFound && !pTab->aCol[iCol].notNull ){
78207             *prNotFound = ++pParse->nMem;
78208             sqlite3VdbeAddOp2(v, OP_Null, 0, *prNotFound);
78209           }
78210         }
78211       }
78212     }
78213   }
78214 
78215   if( eType==0 ){
78216     /* Could not found an existing table or index to use as the RHS b-tree.
78217     ** We will have to generate an ephemeral table to do the job.
78218     */
78219     u32 savedNQueryLoop = pParse->nQueryLoop;
78220     int rMayHaveNull = 0;
78221     eType = IN_INDEX_EPH;
78222     if( prNotFound ){
78223       *prNotFound = rMayHaveNull = ++pParse->nMem;
78224       sqlite3VdbeAddOp2(v, OP_Null, 0, *prNotFound);
78225     }else{
78226       testcase( pParse->nQueryLoop>0 );
78227       pParse->nQueryLoop = 0;
78228       if( pX->pLeft->iColumn<0 && !ExprHasProperty(pX, EP_xIsSelect) ){
78229         eType = IN_INDEX_ROWID;
78230       }
78231     }
78232     sqlite3CodeSubselect(pParse, pX, rMayHaveNull, eType==IN_INDEX_ROWID);
78233     pParse->nQueryLoop = savedNQueryLoop;
78234   }else{
78235     pX->iTable = iTab;
78236   }
78237   return eType;
78238 }
78239 #endif
78240 
78241 /*
78242 ** Generate code for scalar subqueries used as a subquery expression, EXISTS,
78243 ** or IN operators.  Examples:
78244 **
78245 **     (SELECT a FROM b)          -- subquery
78246 **     EXISTS (SELECT a FROM b)   -- EXISTS subquery
78247 **     x IN (4,5,11)              -- IN operator with list on right-hand side
78248 **     x IN (SELECT a FROM b)     -- IN operator with subquery on the right
78249 **
78250 ** The pExpr parameter describes the expression that contains the IN
78251 ** operator or subquery.
78252 **
78253 ** If parameter isRowid is non-zero, then expression pExpr is guaranteed
78254 ** to be of the form "<rowid> IN (?, ?, ?)", where <rowid> is a reference
78255 ** to some integer key column of a table B-Tree. In this case, use an
78256 ** intkey B-Tree to store the set of IN(...) values instead of the usual
78257 ** (slower) variable length keys B-Tree.
78258 **
78259 ** If rMayHaveNull is non-zero, that means that the operation is an IN
78260 ** (not a SELECT or EXISTS) and that the RHS might contains NULLs.
78261 ** Furthermore, the IN is in a WHERE clause and that we really want
78262 ** to iterate over the RHS of the IN operator in order to quickly locate
78263 ** all corresponding LHS elements.  All this routine does is initialize
78264 ** the register given by rMayHaveNull to NULL.  Calling routines will take
78265 ** care of changing this register value to non-NULL if the RHS is NULL-free.
78266 **
78267 ** If rMayHaveNull is zero, that means that the subquery is being used
78268 ** for membership testing only.  There is no need to initialize any
78269 ** registers to indicate the presence or absence of NULLs on the RHS.
78270 **
78271 ** For a SELECT or EXISTS operator, return the register that holds the
78272 ** result.  For IN operators or if an error occurs, the return value is 0.
78273 */
78274 #ifndef SQLITE_OMIT_SUBQUERY
78275 SQLITE_PRIVATE int sqlite3CodeSubselect(
78276   Parse *pParse,          /* Parsing context */
78277   Expr *pExpr,            /* The IN, SELECT, or EXISTS operator */
78278   int rMayHaveNull,       /* Register that records whether NULLs exist in RHS */
78279   int isRowid             /* If true, LHS of IN operator is a rowid */
78280 ){
78281   int testAddr = -1;                      /* One-time test address */
78282   int rReg = 0;                           /* Register storing resulting */
78283   Vdbe *v = sqlite3GetVdbe(pParse);
78284   if( NEVER(v==0) ) return 0;
78285   sqlite3ExprCachePush(pParse);
78286 
78287   /* This code must be run in its entirety every time it is encountered
78288   ** if any of the following is true:
78289   **
78290   **    *  The right-hand side is a correlated subquery
78291   **    *  The right-hand side is an expression list containing variables
78292   **    *  We are inside a trigger
78293   **
78294   ** If all of the above are false, then we can run this code just once
78295   ** save the results, and reuse the same result on subsequent invocations.
78296   */
78297   if( !ExprHasProperty(pExpr, EP_VarSelect) ){
78298     testAddr = sqlite3CodeOnce(pParse);
78299   }
78300 
78301 #ifndef SQLITE_OMIT_EXPLAIN
78302   if( pParse->explain==2 ){
78303     char *zMsg = sqlite3MPrintf(
78304         pParse->db, "EXECUTE %s%s SUBQUERY %d", testAddr>=0?"":"CORRELATED ",
78305         pExpr->op==TK_IN?"LIST":"SCALAR", pParse->iNextSelectId
78306     );
78307     sqlite3VdbeAddOp4(v, OP_Explain, pParse->iSelectId, 0, 0, zMsg, P4_DYNAMIC);
78308   }
78309 #endif
78310 
78311   switch( pExpr->op ){
78312     case TK_IN: {
78313       char affinity;              /* Affinity of the LHS of the IN */
78314       int addr;                   /* Address of OP_OpenEphemeral instruction */
78315       Expr *pLeft = pExpr->pLeft; /* the LHS of the IN operator */
78316       KeyInfo *pKeyInfo = 0;      /* Key information */
78317 
78318       if( rMayHaveNull ){
78319         sqlite3VdbeAddOp2(v, OP_Null, 0, rMayHaveNull);
78320       }
78321 
78322       affinity = sqlite3ExprAffinity(pLeft);
78323 
78324       /* Whether this is an 'x IN(SELECT...)' or an 'x IN(<exprlist>)'
78325       ** expression it is handled the same way.  An ephemeral table is 
78326       ** filled with single-field index keys representing the results
78327       ** from the SELECT or the <exprlist>.
78328       **
78329       ** If the 'x' expression is a column value, or the SELECT...
78330       ** statement returns a column value, then the affinity of that
78331       ** column is used to build the index keys. If both 'x' and the
78332       ** SELECT... statement are columns, then numeric affinity is used
78333       ** if either column has NUMERIC or INTEGER affinity. If neither
78334       ** 'x' nor the SELECT... statement are columns, then numeric affinity
78335       ** is used.
78336       */
78337       pExpr->iTable = pParse->nTab++;
78338       addr = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, pExpr->iTable, !isRowid);
78339       if( rMayHaveNull==0 ) sqlite3VdbeChangeP5(v, BTREE_UNORDERED);
78340       pKeyInfo = isRowid ? 0 : sqlite3KeyInfoAlloc(pParse->db, 1, 1);
78341 
78342       if( ExprHasProperty(pExpr, EP_xIsSelect) ){
78343         /* Case 1:     expr IN (SELECT ...)
78344         **
78345         ** Generate code to write the results of the select into the temporary
78346         ** table allocated and opened above.
78347         */
78348         SelectDest dest;
78349         ExprList *pEList;
78350 
78351         assert( !isRowid );
78352         sqlite3SelectDestInit(&dest, SRT_Set, pExpr->iTable);
78353         dest.affSdst = (u8)affinity;
78354         assert( (pExpr->iTable&0x0000FFFF)==pExpr->iTable );
78355         pExpr->x.pSelect->iLimit = 0;
78356         testcase( pKeyInfo==0 ); /* Caused by OOM in sqlite3KeyInfoAlloc() */
78357         if( sqlite3Select(pParse, pExpr->x.pSelect, &dest) ){
78358           sqlite3KeyInfoUnref(pKeyInfo);
78359           return 0;
78360         }
78361         pEList = pExpr->x.pSelect->pEList;
78362         assert( pKeyInfo!=0 ); /* OOM will cause exit after sqlite3Select() */
78363         assert( pEList!=0 );
78364         assert( pEList->nExpr>0 );
78365         assert( sqlite3KeyInfoIsWriteable(pKeyInfo) );
78366         pKeyInfo->aColl[0] = sqlite3BinaryCompareCollSeq(pParse, pExpr->pLeft,
78367                                                          pEList->a[0].pExpr);
78368       }else if( ALWAYS(pExpr->x.pList!=0) ){
78369         /* Case 2:     expr IN (exprlist)
78370         **
78371         ** For each expression, build an index key from the evaluation and
78372         ** store it in the temporary table. If <expr> is a column, then use
78373         ** that columns affinity when building index keys. If <expr> is not
78374         ** a column, use numeric affinity.
78375         */
78376         int i;
78377         ExprList *pList = pExpr->x.pList;
78378         struct ExprList_item *pItem;
78379         int r1, r2, r3;
78380 
78381         if( !affinity ){
78382           affinity = SQLITE_AFF_NONE;
78383         }
78384         if( pKeyInfo ){
78385           assert( sqlite3KeyInfoIsWriteable(pKeyInfo) );
78386           pKeyInfo->aColl[0] = sqlite3ExprCollSeq(pParse, pExpr->pLeft);
78387         }
78388 
78389         /* Loop through each expression in <exprlist>. */
78390         r1 = sqlite3GetTempReg(pParse);
78391         r2 = sqlite3GetTempReg(pParse);
78392         sqlite3VdbeAddOp2(v, OP_Null, 0, r2);
78393         for(i=pList->nExpr, pItem=pList->a; i>0; i--, pItem++){
78394           Expr *pE2 = pItem->pExpr;
78395           int iValToIns;
78396 
78397           /* If the expression is not constant then we will need to
78398           ** disable the test that was generated above that makes sure
78399           ** this code only executes once.  Because for a non-constant
78400           ** expression we need to rerun this code each time.
78401           */
78402           if( testAddr>=0 && !sqlite3ExprIsConstant(pE2) ){
78403             sqlite3VdbeChangeToNoop(v, testAddr);
78404             testAddr = -1;
78405           }
78406 
78407           /* Evaluate the expression and insert it into the temp table */
78408           if( isRowid && sqlite3ExprIsInteger(pE2, &iValToIns) ){
78409             sqlite3VdbeAddOp3(v, OP_InsertInt, pExpr->iTable, r2, iValToIns);
78410           }else{
78411             r3 = sqlite3ExprCodeTarget(pParse, pE2, r1);
78412             if( isRowid ){
78413               sqlite3VdbeAddOp2(v, OP_MustBeInt, r3,
78414                                 sqlite3VdbeCurrentAddr(v)+2);
78415               sqlite3VdbeAddOp3(v, OP_Insert, pExpr->iTable, r2, r3);
78416             }else{
78417               sqlite3VdbeAddOp4(v, OP_MakeRecord, r3, 1, r2, &affinity, 1);
78418               sqlite3ExprCacheAffinityChange(pParse, r3, 1);
78419               sqlite3VdbeAddOp2(v, OP_IdxInsert, pExpr->iTable, r2);
78420             }
78421           }
78422         }
78423         sqlite3ReleaseTempReg(pParse, r1);
78424         sqlite3ReleaseTempReg(pParse, r2);
78425       }
78426       if( pKeyInfo ){
78427         sqlite3VdbeChangeP4(v, addr, (void *)pKeyInfo, P4_KEYINFO);
78428       }
78429       break;
78430     }
78431 
78432     case TK_EXISTS:
78433     case TK_SELECT:
78434     default: {
78435       /* If this has to be a scalar SELECT.  Generate code to put the
78436       ** value of this select in a memory cell and record the number
78437       ** of the memory cell in iColumn.  If this is an EXISTS, write
78438       ** an integer 0 (not exists) or 1 (exists) into a memory cell
78439       ** and record that memory cell in iColumn.
78440       */
78441       Select *pSel;                         /* SELECT statement to encode */
78442       SelectDest dest;                      /* How to deal with SELECt result */
78443 
78444       testcase( pExpr->op==TK_EXISTS );
78445       testcase( pExpr->op==TK_SELECT );
78446       assert( pExpr->op==TK_EXISTS || pExpr->op==TK_SELECT );
78447 
78448       assert( ExprHasProperty(pExpr, EP_xIsSelect) );
78449       pSel = pExpr->x.pSelect;
78450       sqlite3SelectDestInit(&dest, 0, ++pParse->nMem);
78451       if( pExpr->op==TK_SELECT ){
78452         dest.eDest = SRT_Mem;
78453         sqlite3VdbeAddOp2(v, OP_Null, 0, dest.iSDParm);
78454         VdbeComment((v, "Init subquery result"));
78455       }else{
78456         dest.eDest = SRT_Exists;
78457         sqlite3VdbeAddOp2(v, OP_Integer, 0, dest.iSDParm);
78458         VdbeComment((v, "Init EXISTS result"));
78459       }
78460       sqlite3ExprDelete(pParse->db, pSel->pLimit);
78461       pSel->pLimit = sqlite3PExpr(pParse, TK_INTEGER, 0, 0,
78462                                   &sqlite3IntTokens[1]);
78463       pSel->iLimit = 0;
78464       if( sqlite3Select(pParse, pSel, &dest) ){
78465         return 0;
78466       }
78467       rReg = dest.iSDParm;
78468       ExprSetVVAProperty(pExpr, EP_NoReduce);
78469       break;
78470     }
78471   }
78472 
78473   if( testAddr>=0 ){
78474     sqlite3VdbeJumpHere(v, testAddr);
78475   }
78476   sqlite3ExprCachePop(pParse, 1);
78477 
78478   return rReg;
78479 }
78480 #endif /* SQLITE_OMIT_SUBQUERY */
78481 
78482 #ifndef SQLITE_OMIT_SUBQUERY
78483 /*
78484 ** Generate code for an IN expression.
78485 **
78486 **      x IN (SELECT ...)
78487 **      x IN (value, value, ...)
78488 **
78489 ** The left-hand side (LHS) is a scalar expression.  The right-hand side (RHS)
78490 ** is an array of zero or more values.  The expression is true if the LHS is
78491 ** contained within the RHS.  The value of the expression is unknown (NULL)
78492 ** if the LHS is NULL or if the LHS is not contained within the RHS and the
78493 ** RHS contains one or more NULL values.
78494 **
78495 ** This routine generates code will jump to destIfFalse if the LHS is not 
78496 ** contained within the RHS.  If due to NULLs we cannot determine if the LHS
78497 ** is contained in the RHS then jump to destIfNull.  If the LHS is contained
78498 ** within the RHS then fall through.
78499 */
78500 static void sqlite3ExprCodeIN(
78501   Parse *pParse,        /* Parsing and code generating context */
78502   Expr *pExpr,          /* The IN expression */
78503   int destIfFalse,      /* Jump here if LHS is not contained in the RHS */
78504   int destIfNull        /* Jump here if the results are unknown due to NULLs */
78505 ){
78506   int rRhsHasNull = 0;  /* Register that is true if RHS contains NULL values */
78507   char affinity;        /* Comparison affinity to use */
78508   int eType;            /* Type of the RHS */
78509   int r1;               /* Temporary use register */
78510   Vdbe *v;              /* Statement under construction */
78511 
78512   /* Compute the RHS.   After this step, the table with cursor
78513   ** pExpr->iTable will contains the values that make up the RHS.
78514   */
78515   v = pParse->pVdbe;
78516   assert( v!=0 );       /* OOM detected prior to this routine */
78517   VdbeNoopComment((v, "begin IN expr"));
78518   eType = sqlite3FindInIndex(pParse, pExpr, &rRhsHasNull);
78519 
78520   /* Figure out the affinity to use to create a key from the results
78521   ** of the expression. affinityStr stores a static string suitable for
78522   ** P4 of OP_MakeRecord.
78523   */
78524   affinity = comparisonAffinity(pExpr);
78525 
78526   /* Code the LHS, the <expr> from "<expr> IN (...)".
78527   */
78528   sqlite3ExprCachePush(pParse);
78529   r1 = sqlite3GetTempReg(pParse);
78530   sqlite3ExprCode(pParse, pExpr->pLeft, r1);
78531 
78532   /* If the LHS is NULL, then the result is either false or NULL depending
78533   ** on whether the RHS is empty or not, respectively.
78534   */
78535   if( destIfNull==destIfFalse ){
78536     /* Shortcut for the common case where the false and NULL outcomes are
78537     ** the same. */
78538     sqlite3VdbeAddOp2(v, OP_IsNull, r1, destIfNull);
78539   }else{
78540     int addr1 = sqlite3VdbeAddOp1(v, OP_NotNull, r1);
78541     sqlite3VdbeAddOp2(v, OP_Rewind, pExpr->iTable, destIfFalse);
78542     sqlite3VdbeAddOp2(v, OP_Goto, 0, destIfNull);
78543     sqlite3VdbeJumpHere(v, addr1);
78544   }
78545 
78546   if( eType==IN_INDEX_ROWID ){
78547     /* In this case, the RHS is the ROWID of table b-tree
78548     */
78549     sqlite3VdbeAddOp2(v, OP_MustBeInt, r1, destIfFalse);
78550     sqlite3VdbeAddOp3(v, OP_NotExists, pExpr->iTable, destIfFalse, r1);
78551   }else{
78552     /* In this case, the RHS is an index b-tree.
78553     */
78554     sqlite3VdbeAddOp4(v, OP_Affinity, r1, 1, 0, &affinity, 1);
78555 
78556     /* If the set membership test fails, then the result of the 
78557     ** "x IN (...)" expression must be either 0 or NULL. If the set
78558     ** contains no NULL values, then the result is 0. If the set 
78559     ** contains one or more NULL values, then the result of the
78560     ** expression is also NULL.
78561     */
78562     if( rRhsHasNull==0 || destIfFalse==destIfNull ){
78563       /* This branch runs if it is known at compile time that the RHS
78564       ** cannot contain NULL values. This happens as the result
78565       ** of a "NOT NULL" constraint in the database schema.
78566       **
78567       ** Also run this branch if NULL is equivalent to FALSE
78568       ** for this particular IN operator.
78569       */
78570       sqlite3VdbeAddOp4Int(v, OP_NotFound, pExpr->iTable, destIfFalse, r1, 1);
78571 
78572     }else{
78573       /* In this branch, the RHS of the IN might contain a NULL and
78574       ** the presence of a NULL on the RHS makes a difference in the
78575       ** outcome.
78576       */
78577       int j1, j2, j3;
78578 
78579       /* First check to see if the LHS is contained in the RHS.  If so,
78580       ** then the presence of NULLs in the RHS does not matter, so jump
78581       ** over all of the code that follows.
78582       */
78583       j1 = sqlite3VdbeAddOp4Int(v, OP_Found, pExpr->iTable, 0, r1, 1);
78584 
78585       /* Here we begin generating code that runs if the LHS is not
78586       ** contained within the RHS.  Generate additional code that
78587       ** tests the RHS for NULLs.  If the RHS contains a NULL then
78588       ** jump to destIfNull.  If there are no NULLs in the RHS then
78589       ** jump to destIfFalse.
78590       */
78591       j2 = sqlite3VdbeAddOp1(v, OP_NotNull, rRhsHasNull);
78592       j3 = sqlite3VdbeAddOp4Int(v, OP_Found, pExpr->iTable, 0, rRhsHasNull, 1);
78593       sqlite3VdbeAddOp2(v, OP_Integer, -1, rRhsHasNull);
78594       sqlite3VdbeJumpHere(v, j3);
78595       sqlite3VdbeAddOp2(v, OP_AddImm, rRhsHasNull, 1);
78596       sqlite3VdbeJumpHere(v, j2);
78597 
78598       /* Jump to the appropriate target depending on whether or not
78599       ** the RHS contains a NULL
78600       */
78601       sqlite3VdbeAddOp2(v, OP_If, rRhsHasNull, destIfNull);
78602       sqlite3VdbeAddOp2(v, OP_Goto, 0, destIfFalse);
78603 
78604       /* The OP_Found at the top of this branch jumps here when true, 
78605       ** causing the overall IN expression evaluation to fall through.
78606       */
78607       sqlite3VdbeJumpHere(v, j1);
78608     }
78609   }
78610   sqlite3ReleaseTempReg(pParse, r1);
78611   sqlite3ExprCachePop(pParse, 1);
78612   VdbeComment((v, "end IN expr"));
78613 }
78614 #endif /* SQLITE_OMIT_SUBQUERY */
78615 
78616 /*
78617 ** Duplicate an 8-byte value
78618 */
78619 static char *dup8bytes(Vdbe *v, const char *in){
78620   char *out = sqlite3DbMallocRaw(sqlite3VdbeDb(v), 8);
78621   if( out ){
78622     memcpy(out, in, 8);
78623   }
78624   return out;
78625 }
78626 
78627 #ifndef SQLITE_OMIT_FLOATING_POINT
78628 /*
78629 ** Generate an instruction that will put the floating point
78630 ** value described by z[0..n-1] into register iMem.
78631 **
78632 ** The z[] string will probably not be zero-terminated.  But the 
78633 ** z[n] character is guaranteed to be something that does not look
78634 ** like the continuation of the number.
78635 */
78636 static void codeReal(Vdbe *v, const char *z, int negateFlag, int iMem){
78637   if( ALWAYS(z!=0) ){
78638     double value;
78639     char *zV;
78640     sqlite3AtoF(z, &value, sqlite3Strlen30(z), SQLITE_UTF8);
78641     assert( !sqlite3IsNaN(value) ); /* The new AtoF never returns NaN */
78642     if( negateFlag ) value = -value;
78643     zV = dup8bytes(v, (char*)&value);
78644     sqlite3VdbeAddOp4(v, OP_Real, 0, iMem, 0, zV, P4_REAL);
78645   }
78646 }
78647 #endif
78648 
78649 
78650 /*
78651 ** Generate an instruction that will put the integer describe by
78652 ** text z[0..n-1] into register iMem.
78653 **
78654 ** Expr.u.zToken is always UTF8 and zero-terminated.
78655 */
78656 static void codeInteger(Parse *pParse, Expr *pExpr, int negFlag, int iMem){
78657   Vdbe *v = pParse->pVdbe;
78658   if( pExpr->flags & EP_IntValue ){
78659     int i = pExpr->u.iValue;
78660     assert( i>=0 );
78661     if( negFlag ) i = -i;
78662     sqlite3VdbeAddOp2(v, OP_Integer, i, iMem);
78663   }else{
78664     int c;
78665     i64 value;
78666     const char *z = pExpr->u.zToken;
78667     assert( z!=0 );
78668     c = sqlite3Atoi64(z, &value, sqlite3Strlen30(z), SQLITE_UTF8);
78669     if( c==0 || (c==2 && negFlag) ){
78670       char *zV;
78671       if( negFlag ){ value = c==2 ? SMALLEST_INT64 : -value; }
78672       zV = dup8bytes(v, (char*)&value);
78673       sqlite3VdbeAddOp4(v, OP_Int64, 0, iMem, 0, zV, P4_INT64);
78674     }else{
78675 #ifdef SQLITE_OMIT_FLOATING_POINT
78676       sqlite3ErrorMsg(pParse, "oversized integer: %s%s", negFlag ? "-" : "", z);
78677 #else
78678       codeReal(v, z, negFlag, iMem);
78679 #endif
78680     }
78681   }
78682 }
78683 
78684 /*
78685 ** Clear a cache entry.
78686 */
78687 static void cacheEntryClear(Parse *pParse, struct yColCache *p){
78688   if( p->tempReg ){
78689     if( pParse->nTempReg<ArraySize(pParse->aTempReg) ){
78690       pParse->aTempReg[pParse->nTempReg++] = p->iReg;
78691     }
78692     p->tempReg = 0;
78693   }
78694 }
78695 
78696 
78697 /*
78698 ** Record in the column cache that a particular column from a
78699 ** particular table is stored in a particular register.
78700 */
78701 SQLITE_PRIVATE void sqlite3ExprCacheStore(Parse *pParse, int iTab, int iCol, int iReg){
78702   int i;
78703   int minLru;
78704   int idxLru;
78705   struct yColCache *p;
78706 
78707   assert( iReg>0 );  /* Register numbers are always positive */
78708   assert( iCol>=-1 && iCol<32768 );  /* Finite column numbers */
78709 
78710   /* The SQLITE_ColumnCache flag disables the column cache.  This is used
78711   ** for testing only - to verify that SQLite always gets the same answer
78712   ** with and without the column cache.
78713   */
78714   if( OptimizationDisabled(pParse->db, SQLITE_ColumnCache) ) return;
78715 
78716   /* First replace any existing entry.
78717   **
78718   ** Actually, the way the column cache is currently used, we are guaranteed
78719   ** that the object will never already be in cache.  Verify this guarantee.
78720   */
78721 #ifndef NDEBUG
78722   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78723     assert( p->iReg==0 || p->iTable!=iTab || p->iColumn!=iCol );
78724   }
78725 #endif
78726 
78727   /* Find an empty slot and replace it */
78728   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78729     if( p->iReg==0 ){
78730       p->iLevel = pParse->iCacheLevel;
78731       p->iTable = iTab;
78732       p->iColumn = iCol;
78733       p->iReg = iReg;
78734       p->tempReg = 0;
78735       p->lru = pParse->iCacheCnt++;
78736       return;
78737     }
78738   }
78739 
78740   /* Replace the last recently used */
78741   minLru = 0x7fffffff;
78742   idxLru = -1;
78743   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78744     if( p->lru<minLru ){
78745       idxLru = i;
78746       minLru = p->lru;
78747     }
78748   }
78749   if( ALWAYS(idxLru>=0) ){
78750     p = &pParse->aColCache[idxLru];
78751     p->iLevel = pParse->iCacheLevel;
78752     p->iTable = iTab;
78753     p->iColumn = iCol;
78754     p->iReg = iReg;
78755     p->tempReg = 0;
78756     p->lru = pParse->iCacheCnt++;
78757     return;
78758   }
78759 }
78760 
78761 /*
78762 ** Indicate that registers between iReg..iReg+nReg-1 are being overwritten.
78763 ** Purge the range of registers from the column cache.
78764 */
78765 SQLITE_PRIVATE void sqlite3ExprCacheRemove(Parse *pParse, int iReg, int nReg){
78766   int i;
78767   int iLast = iReg + nReg - 1;
78768   struct yColCache *p;
78769   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78770     int r = p->iReg;
78771     if( r>=iReg && r<=iLast ){
78772       cacheEntryClear(pParse, p);
78773       p->iReg = 0;
78774     }
78775   }
78776 }
78777 
78778 /*
78779 ** Remember the current column cache context.  Any new entries added
78780 ** added to the column cache after this call are removed when the
78781 ** corresponding pop occurs.
78782 */
78783 SQLITE_PRIVATE void sqlite3ExprCachePush(Parse *pParse){
78784   pParse->iCacheLevel++;
78785 }
78786 
78787 /*
78788 ** Remove from the column cache any entries that were added since the
78789 ** the previous N Push operations.  In other words, restore the cache
78790 ** to the state it was in N Pushes ago.
78791 */
78792 SQLITE_PRIVATE void sqlite3ExprCachePop(Parse *pParse, int N){
78793   int i;
78794   struct yColCache *p;
78795   assert( N>0 );
78796   assert( pParse->iCacheLevel>=N );
78797   pParse->iCacheLevel -= N;
78798   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78799     if( p->iReg && p->iLevel>pParse->iCacheLevel ){
78800       cacheEntryClear(pParse, p);
78801       p->iReg = 0;
78802     }
78803   }
78804 }
78805 
78806 /*
78807 ** When a cached column is reused, make sure that its register is
78808 ** no longer available as a temp register.  ticket #3879:  that same
78809 ** register might be in the cache in multiple places, so be sure to
78810 ** get them all.
78811 */
78812 static void sqlite3ExprCachePinRegister(Parse *pParse, int iReg){
78813   int i;
78814   struct yColCache *p;
78815   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78816     if( p->iReg==iReg ){
78817       p->tempReg = 0;
78818     }
78819   }
78820 }
78821 
78822 /*
78823 ** Generate code to extract the value of the iCol-th column of a table.
78824 */
78825 SQLITE_PRIVATE void sqlite3ExprCodeGetColumnOfTable(
78826   Vdbe *v,        /* The VDBE under construction */
78827   Table *pTab,    /* The table containing the value */
78828   int iTabCur,    /* The table cursor.  Or the PK cursor for WITHOUT ROWID */
78829   int iCol,       /* Index of the column to extract */
78830   int regOut      /* Extract the value into this register */
78831 ){
78832   if( iCol<0 || iCol==pTab->iPKey ){
78833     sqlite3VdbeAddOp2(v, OP_Rowid, iTabCur, regOut);
78834   }else{
78835     int op = IsVirtual(pTab) ? OP_VColumn : OP_Column;
78836     int x = iCol;
78837     if( !HasRowid(pTab) ){
78838       x = sqlite3ColumnOfIndex(sqlite3PrimaryKeyIndex(pTab), iCol);
78839     }
78840     sqlite3VdbeAddOp3(v, op, iTabCur, x, regOut);
78841   }
78842   if( iCol>=0 ){
78843     sqlite3ColumnDefault(v, pTab, iCol, regOut);
78844   }
78845 }
78846 
78847 /*
78848 ** Generate code that will extract the iColumn-th column from
78849 ** table pTab and store the column value in a register.  An effort
78850 ** is made to store the column value in register iReg, but this is
78851 ** not guaranteed.  The location of the column value is returned.
78852 **
78853 ** There must be an open cursor to pTab in iTable when this routine
78854 ** is called.  If iColumn<0 then code is generated that extracts the rowid.
78855 */
78856 SQLITE_PRIVATE int sqlite3ExprCodeGetColumn(
78857   Parse *pParse,   /* Parsing and code generating context */
78858   Table *pTab,     /* Description of the table we are reading from */
78859   int iColumn,     /* Index of the table column */
78860   int iTable,      /* The cursor pointing to the table */
78861   int iReg,        /* Store results here */
78862   u8 p5            /* P5 value for OP_Column */
78863 ){
78864   Vdbe *v = pParse->pVdbe;
78865   int i;
78866   struct yColCache *p;
78867 
78868   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78869     if( p->iReg>0 && p->iTable==iTable && p->iColumn==iColumn ){
78870       p->lru = pParse->iCacheCnt++;
78871       sqlite3ExprCachePinRegister(pParse, p->iReg);
78872       return p->iReg;
78873     }
78874   }  
78875   assert( v!=0 );
78876   sqlite3ExprCodeGetColumnOfTable(v, pTab, iTable, iColumn, iReg);
78877   if( p5 ){
78878     sqlite3VdbeChangeP5(v, p5);
78879   }else{   
78880     sqlite3ExprCacheStore(pParse, iTable, iColumn, iReg);
78881   }
78882   return iReg;
78883 }
78884 
78885 /*
78886 ** Clear all column cache entries.
78887 */
78888 SQLITE_PRIVATE void sqlite3ExprCacheClear(Parse *pParse){
78889   int i;
78890   struct yColCache *p;
78891 
78892   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78893     if( p->iReg ){
78894       cacheEntryClear(pParse, p);
78895       p->iReg = 0;
78896     }
78897   }
78898 }
78899 
78900 /*
78901 ** Record the fact that an affinity change has occurred on iCount
78902 ** registers starting with iStart.
78903 */
78904 SQLITE_PRIVATE void sqlite3ExprCacheAffinityChange(Parse *pParse, int iStart, int iCount){
78905   sqlite3ExprCacheRemove(pParse, iStart, iCount);
78906 }
78907 
78908 /*
78909 ** Generate code to move content from registers iFrom...iFrom+nReg-1
78910 ** over to iTo..iTo+nReg-1. Keep the column cache up-to-date.
78911 */
78912 SQLITE_PRIVATE void sqlite3ExprCodeMove(Parse *pParse, int iFrom, int iTo, int nReg){
78913   int i;
78914   struct yColCache *p;
78915   assert( iFrom>=iTo+nReg || iFrom+nReg<=iTo );
78916   sqlite3VdbeAddOp3(pParse->pVdbe, OP_Move, iFrom, iTo, nReg-1);
78917   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78918     int x = p->iReg;
78919     if( x>=iFrom && x<iFrom+nReg ){
78920       p->iReg += iTo-iFrom;
78921     }
78922   }
78923 }
78924 
78925 #if defined(SQLITE_DEBUG) || defined(SQLITE_COVERAGE_TEST)
78926 /*
78927 ** Return true if any register in the range iFrom..iTo (inclusive)
78928 ** is used as part of the column cache.
78929 **
78930 ** This routine is used within assert() and testcase() macros only
78931 ** and does not appear in a normal build.
78932 */
78933 static int usedAsColumnCache(Parse *pParse, int iFrom, int iTo){
78934   int i;
78935   struct yColCache *p;
78936   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78937     int r = p->iReg;
78938     if( r>=iFrom && r<=iTo ) return 1;    /*NO_TEST*/
78939   }
78940   return 0;
78941 }
78942 #endif /* SQLITE_DEBUG || SQLITE_COVERAGE_TEST */
78943 
78944 /*
78945 ** Convert an expression node to a TK_REGISTER
78946 */
78947 static void exprToRegister(Expr *p, int iReg){
78948   p->op2 = p->op;
78949   p->op = TK_REGISTER;
78950   p->iTable = iReg;
78951   ExprClearProperty(p, EP_Skip);
78952 }
78953 
78954 /*
78955 ** Generate code into the current Vdbe to evaluate the given
78956 ** expression.  Attempt to store the results in register "target".
78957 ** Return the register where results are stored.
78958 **
78959 ** With this routine, there is no guarantee that results will
78960 ** be stored in target.  The result might be stored in some other
78961 ** register if it is convenient to do so.  The calling function
78962 ** must check the return code and move the results to the desired
78963 ** register.
78964 */
78965 SQLITE_PRIVATE int sqlite3ExprCodeTarget(Parse *pParse, Expr *pExpr, int target){
78966   Vdbe *v = pParse->pVdbe;  /* The VM under construction */
78967   int op;                   /* The opcode being coded */
78968   int inReg = target;       /* Results stored in register inReg */
78969   int regFree1 = 0;         /* If non-zero free this temporary register */
78970   int regFree2 = 0;         /* If non-zero free this temporary register */
78971   int r1, r2, r3, r4;       /* Various register numbers */
78972   sqlite3 *db = pParse->db; /* The database connection */
78973   Expr tempX;               /* Temporary expression node */
78974 
78975   assert( target>0 && target<=pParse->nMem );
78976   if( v==0 ){
78977     assert( pParse->db->mallocFailed );
78978     return 0;
78979   }
78980 
78981   if( pExpr==0 ){
78982     op = TK_NULL;
78983   }else{
78984     op = pExpr->op;
78985   }
78986   switch( op ){
78987     case TK_AGG_COLUMN: {
78988       AggInfo *pAggInfo = pExpr->pAggInfo;
78989       struct AggInfo_col *pCol = &pAggInfo->aCol[pExpr->iAgg];
78990       if( !pAggInfo->directMode ){
78991         assert( pCol->iMem>0 );
78992         inReg = pCol->iMem;
78993         break;
78994       }else if( pAggInfo->useSortingIdx ){
78995         sqlite3VdbeAddOp3(v, OP_Column, pAggInfo->sortingIdxPTab,
78996                               pCol->iSorterColumn, target);
78997         break;
78998       }
78999       /* Otherwise, fall thru into the TK_COLUMN case */
79000     }
79001     case TK_COLUMN: {
79002       int iTab = pExpr->iTable;
79003       if( iTab<0 ){
79004         if( pParse->ckBase>0 ){
79005           /* Generating CHECK constraints or inserting into partial index */
79006           inReg = pExpr->iColumn + pParse->ckBase;
79007           break;
79008         }else{
79009           /* Deleting from a partial index */
79010           iTab = pParse->iPartIdxTab;
79011         }
79012       }
79013       inReg = sqlite3ExprCodeGetColumn(pParse, pExpr->pTab,
79014                                pExpr->iColumn, iTab, target,
79015                                pExpr->op2);
79016       break;
79017     }
79018     case TK_INTEGER: {
79019       codeInteger(pParse, pExpr, 0, target);
79020       break;
79021     }
79022 #ifndef SQLITE_OMIT_FLOATING_POINT
79023     case TK_FLOAT: {
79024       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79025       codeReal(v, pExpr->u.zToken, 0, target);
79026       break;
79027     }
79028 #endif
79029     case TK_STRING: {
79030       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79031       sqlite3VdbeAddOp4(v, OP_String8, 0, target, 0, pExpr->u.zToken, 0);
79032       break;
79033     }
79034     case TK_NULL: {
79035       sqlite3VdbeAddOp2(v, OP_Null, 0, target);
79036       break;
79037     }
79038 #ifndef SQLITE_OMIT_BLOB_LITERAL
79039     case TK_BLOB: {
79040       int n;
79041       const char *z;
79042       char *zBlob;
79043       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79044       assert( pExpr->u.zToken[0]=='x' || pExpr->u.zToken[0]=='X' );
79045       assert( pExpr->u.zToken[1]=='\'' );
79046       z = &pExpr->u.zToken[2];
79047       n = sqlite3Strlen30(z) - 1;
79048       assert( z[n]=='\'' );
79049       zBlob = sqlite3HexToBlob(sqlite3VdbeDb(v), z, n);
79050       sqlite3VdbeAddOp4(v, OP_Blob, n/2, target, 0, zBlob, P4_DYNAMIC);
79051       break;
79052     }
79053 #endif
79054     case TK_VARIABLE: {
79055       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79056       assert( pExpr->u.zToken!=0 );
79057       assert( pExpr->u.zToken[0]!=0 );
79058       sqlite3VdbeAddOp2(v, OP_Variable, pExpr->iColumn, target);
79059       if( pExpr->u.zToken[1]!=0 ){
79060         assert( pExpr->u.zToken[0]=='?' 
79061              || strcmp(pExpr->u.zToken, pParse->azVar[pExpr->iColumn-1])==0 );
79062         sqlite3VdbeChangeP4(v, -1, pParse->azVar[pExpr->iColumn-1], P4_STATIC);
79063       }
79064       break;
79065     }
79066     case TK_REGISTER: {
79067       inReg = pExpr->iTable;
79068       break;
79069     }
79070     case TK_AS: {
79071       inReg = sqlite3ExprCodeTarget(pParse, pExpr->pLeft, target);
79072       break;
79073     }
79074 #ifndef SQLITE_OMIT_CAST
79075     case TK_CAST: {
79076       /* Expressions of the form:   CAST(pLeft AS token) */
79077       int aff, to_op;
79078       inReg = sqlite3ExprCodeTarget(pParse, pExpr->pLeft, target);
79079       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79080       aff = sqlite3AffinityType(pExpr->u.zToken, 0);
79081       to_op = aff - SQLITE_AFF_TEXT + OP_ToText;
79082       assert( to_op==OP_ToText    || aff!=SQLITE_AFF_TEXT    );
79083       assert( to_op==OP_ToBlob    || aff!=SQLITE_AFF_NONE    );
79084       assert( to_op==OP_ToNumeric || aff!=SQLITE_AFF_NUMERIC );
79085       assert( to_op==OP_ToInt     || aff!=SQLITE_AFF_INTEGER );
79086       assert( to_op==OP_ToReal    || aff!=SQLITE_AFF_REAL    );
79087       testcase( to_op==OP_ToText );
79088       testcase( to_op==OP_ToBlob );
79089       testcase( to_op==OP_ToNumeric );
79090       testcase( to_op==OP_ToInt );
79091       testcase( to_op==OP_ToReal );
79092       if( inReg!=target ){
79093         sqlite3VdbeAddOp2(v, OP_SCopy, inReg, target);
79094         inReg = target;
79095       }
79096       sqlite3VdbeAddOp1(v, to_op, inReg);
79097       testcase( usedAsColumnCache(pParse, inReg, inReg) );
79098       sqlite3ExprCacheAffinityChange(pParse, inReg, 1);
79099       break;
79100     }
79101 #endif /* SQLITE_OMIT_CAST */
79102     case TK_LT:
79103     case TK_LE:
79104     case TK_GT:
79105     case TK_GE:
79106     case TK_NE:
79107     case TK_EQ: {
79108       assert( TK_LT==OP_Lt );
79109       assert( TK_LE==OP_Le );
79110       assert( TK_GT==OP_Gt );
79111       assert( TK_GE==OP_Ge );
79112       assert( TK_EQ==OP_Eq );
79113       assert( TK_NE==OP_Ne );
79114       testcase( op==TK_LT );
79115       testcase( op==TK_LE );
79116       testcase( op==TK_GT );
79117       testcase( op==TK_GE );
79118       testcase( op==TK_EQ );
79119       testcase( op==TK_NE );
79120       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
79121       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
79122       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
79123                   r1, r2, inReg, SQLITE_STOREP2);
79124       testcase( regFree1==0 );
79125       testcase( regFree2==0 );
79126       break;
79127     }
79128     case TK_IS:
79129     case TK_ISNOT: {
79130       testcase( op==TK_IS );
79131       testcase( op==TK_ISNOT );
79132       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
79133       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
79134       op = (op==TK_IS) ? TK_EQ : TK_NE;
79135       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
79136                   r1, r2, inReg, SQLITE_STOREP2 | SQLITE_NULLEQ);
79137       testcase( regFree1==0 );
79138       testcase( regFree2==0 );
79139       break;
79140     }
79141     case TK_AND:
79142     case TK_OR:
79143     case TK_PLUS:
79144     case TK_STAR:
79145     case TK_MINUS:
79146     case TK_REM:
79147     case TK_BITAND:
79148     case TK_BITOR:
79149     case TK_SLASH:
79150     case TK_LSHIFT:
79151     case TK_RSHIFT: 
79152     case TK_CONCAT: {
79153       assert( TK_AND==OP_And );
79154       assert( TK_OR==OP_Or );
79155       assert( TK_PLUS==OP_Add );
79156       assert( TK_MINUS==OP_Subtract );
79157       assert( TK_REM==OP_Remainder );
79158       assert( TK_BITAND==OP_BitAnd );
79159       assert( TK_BITOR==OP_BitOr );
79160       assert( TK_SLASH==OP_Divide );
79161       assert( TK_LSHIFT==OP_ShiftLeft );
79162       assert( TK_RSHIFT==OP_ShiftRight );
79163       assert( TK_CONCAT==OP_Concat );
79164       testcase( op==TK_AND );
79165       testcase( op==TK_OR );
79166       testcase( op==TK_PLUS );
79167       testcase( op==TK_MINUS );
79168       testcase( op==TK_REM );
79169       testcase( op==TK_BITAND );
79170       testcase( op==TK_BITOR );
79171       testcase( op==TK_SLASH );
79172       testcase( op==TK_LSHIFT );
79173       testcase( op==TK_RSHIFT );
79174       testcase( op==TK_CONCAT );
79175       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
79176       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
79177       sqlite3VdbeAddOp3(v, op, r2, r1, target);
79178       testcase( regFree1==0 );
79179       testcase( regFree2==0 );
79180       break;
79181     }
79182     case TK_UMINUS: {
79183       Expr *pLeft = pExpr->pLeft;
79184       assert( pLeft );
79185       if( pLeft->op==TK_INTEGER ){
79186         codeInteger(pParse, pLeft, 1, target);
79187 #ifndef SQLITE_OMIT_FLOATING_POINT
79188       }else if( pLeft->op==TK_FLOAT ){
79189         assert( !ExprHasProperty(pExpr, EP_IntValue) );
79190         codeReal(v, pLeft->u.zToken, 1, target);
79191 #endif
79192       }else{
79193         tempX.op = TK_INTEGER;
79194         tempX.flags = EP_IntValue|EP_TokenOnly;
79195         tempX.u.iValue = 0;
79196         r1 = sqlite3ExprCodeTemp(pParse, &tempX, &regFree1);
79197         r2 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree2);
79198         sqlite3VdbeAddOp3(v, OP_Subtract, r2, r1, target);
79199         testcase( regFree2==0 );
79200       }
79201       inReg = target;
79202       break;
79203     }
79204     case TK_BITNOT:
79205     case TK_NOT: {
79206       assert( TK_BITNOT==OP_BitNot );
79207       assert( TK_NOT==OP_Not );
79208       testcase( op==TK_BITNOT );
79209       testcase( op==TK_NOT );
79210       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
79211       testcase( regFree1==0 );
79212       inReg = target;
79213       sqlite3VdbeAddOp2(v, op, r1, inReg);
79214       break;
79215     }
79216     case TK_ISNULL:
79217     case TK_NOTNULL: {
79218       int addr;
79219       assert( TK_ISNULL==OP_IsNull );
79220       assert( TK_NOTNULL==OP_NotNull );
79221       testcase( op==TK_ISNULL );
79222       testcase( op==TK_NOTNULL );
79223       sqlite3VdbeAddOp2(v, OP_Integer, 1, target);
79224       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
79225       testcase( regFree1==0 );
79226       addr = sqlite3VdbeAddOp1(v, op, r1);
79227       sqlite3VdbeAddOp2(v, OP_AddImm, target, -1);
79228       sqlite3VdbeJumpHere(v, addr);
79229       break;
79230     }
79231     case TK_AGG_FUNCTION: {
79232       AggInfo *pInfo = pExpr->pAggInfo;
79233       if( pInfo==0 ){
79234         assert( !ExprHasProperty(pExpr, EP_IntValue) );
79235         sqlite3ErrorMsg(pParse, "misuse of aggregate: %s()", pExpr->u.zToken);
79236       }else{
79237         inReg = pInfo->aFunc[pExpr->iAgg].iMem;
79238       }
79239       break;
79240     }
79241     case TK_FUNCTION: {
79242       ExprList *pFarg;       /* List of function arguments */
79243       int nFarg;             /* Number of function arguments */
79244       FuncDef *pDef;         /* The function definition object */
79245       int nId;               /* Length of the function name in bytes */
79246       const char *zId;       /* The function name */
79247       int constMask = 0;     /* Mask of function arguments that are constant */
79248       int i;                 /* Loop counter */
79249       u8 enc = ENC(db);      /* The text encoding used by this database */
79250       CollSeq *pColl = 0;    /* A collating sequence */
79251 
79252       assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
79253       if( ExprHasProperty(pExpr, EP_TokenOnly) ){
79254         pFarg = 0;
79255       }else{
79256         pFarg = pExpr->x.pList;
79257       }
79258       nFarg = pFarg ? pFarg->nExpr : 0;
79259       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79260       zId = pExpr->u.zToken;
79261       nId = sqlite3Strlen30(zId);
79262       pDef = sqlite3FindFunction(db, zId, nId, nFarg, enc, 0);
79263       if( pDef==0 ){
79264         sqlite3ErrorMsg(pParse, "unknown function: %.*s()", nId, zId);
79265         break;
79266       }
79267 
79268       /* Attempt a direct implementation of the built-in COALESCE() and
79269       ** IFNULL() functions.  This avoids unnecessary evalation of
79270       ** arguments past the first non-NULL argument.
79271       */
79272       if( pDef->funcFlags & SQLITE_FUNC_COALESCE ){
79273         int endCoalesce = sqlite3VdbeMakeLabel(v);
79274         assert( nFarg>=2 );
79275         sqlite3ExprCode(pParse, pFarg->a[0].pExpr, target);
79276         for(i=1; i<nFarg; i++){
79277           sqlite3VdbeAddOp2(v, OP_NotNull, target, endCoalesce);
79278           sqlite3ExprCacheRemove(pParse, target, 1);
79279           sqlite3ExprCachePush(pParse);
79280           sqlite3ExprCode(pParse, pFarg->a[i].pExpr, target);
79281           sqlite3ExprCachePop(pParse, 1);
79282         }
79283         sqlite3VdbeResolveLabel(v, endCoalesce);
79284         break;
79285       }
79286 
79287       /* The UNLIKELY() function is a no-op.  The result is the value
79288       ** of the first argument.
79289       */
79290       if( pDef->funcFlags & SQLITE_FUNC_UNLIKELY ){
79291         assert( nFarg>=1 );
79292         sqlite3ExprCode(pParse, pFarg->a[0].pExpr, target);
79293         break;
79294       }
79295 
79296       for(i=0; i<nFarg; i++){
79297         if( i<32 && sqlite3ExprIsConstant(pFarg->a[i].pExpr) ){
79298           constMask |= (1<<i);
79299         }
79300         if( (pDef->funcFlags & SQLITE_FUNC_NEEDCOLL)!=0 && !pColl ){
79301           pColl = sqlite3ExprCollSeq(pParse, pFarg->a[i].pExpr);
79302         }
79303       }
79304       if( pFarg ){
79305         if( constMask ){
79306           r1 = pParse->nMem+1;
79307           pParse->nMem += nFarg;
79308         }else{
79309           r1 = sqlite3GetTempRange(pParse, nFarg);
79310         }
79311 
79312         /* For length() and typeof() functions with a column argument,
79313         ** set the P5 parameter to the OP_Column opcode to OPFLAG_LENGTHARG
79314         ** or OPFLAG_TYPEOFARG respectively, to avoid unnecessary data
79315         ** loading.
79316         */
79317         if( (pDef->funcFlags & (SQLITE_FUNC_LENGTH|SQLITE_FUNC_TYPEOF))!=0 ){
79318           u8 exprOp;
79319           assert( nFarg==1 );
79320           assert( pFarg->a[0].pExpr!=0 );
79321           exprOp = pFarg->a[0].pExpr->op;
79322           if( exprOp==TK_COLUMN || exprOp==TK_AGG_COLUMN ){
79323             assert( SQLITE_FUNC_LENGTH==OPFLAG_LENGTHARG );
79324             assert( SQLITE_FUNC_TYPEOF==OPFLAG_TYPEOFARG );
79325             testcase( pDef->funcFlags & OPFLAG_LENGTHARG );
79326             pFarg->a[0].pExpr->op2 = 
79327                   pDef->funcFlags & (OPFLAG_LENGTHARG|OPFLAG_TYPEOFARG);
79328           }
79329         }
79330 
79331         sqlite3ExprCachePush(pParse);     /* Ticket 2ea2425d34be */
79332         sqlite3ExprCodeExprList(pParse, pFarg, r1, 
79333                                 SQLITE_ECEL_DUP|SQLITE_ECEL_FACTOR);
79334         sqlite3ExprCachePop(pParse, 1);   /* Ticket 2ea2425d34be */
79335       }else{
79336         r1 = 0;
79337       }
79338 #ifndef SQLITE_OMIT_VIRTUALTABLE
79339       /* Possibly overload the function if the first argument is
79340       ** a virtual table column.
79341       **
79342       ** For infix functions (LIKE, GLOB, REGEXP, and MATCH) use the
79343       ** second argument, not the first, as the argument to test to
79344       ** see if it is a column in a virtual table.  This is done because
79345       ** the left operand of infix functions (the operand we want to
79346       ** control overloading) ends up as the second argument to the
79347       ** function.  The expression "A glob B" is equivalent to 
79348       ** "glob(B,A).  We want to use the A in "A glob B" to test
79349       ** for function overloading.  But we use the B term in "glob(B,A)".
79350       */
79351       if( nFarg>=2 && (pExpr->flags & EP_InfixFunc) ){
79352         pDef = sqlite3VtabOverloadFunction(db, pDef, nFarg, pFarg->a[1].pExpr);
79353       }else if( nFarg>0 ){
79354         pDef = sqlite3VtabOverloadFunction(db, pDef, nFarg, pFarg->a[0].pExpr);
79355       }
79356 #endif
79357       if( pDef->funcFlags & SQLITE_FUNC_NEEDCOLL ){
79358         if( !pColl ) pColl = db->pDfltColl; 
79359         sqlite3VdbeAddOp4(v, OP_CollSeq, 0, 0, 0, (char *)pColl, P4_COLLSEQ);
79360       }
79361       sqlite3VdbeAddOp4(v, OP_Function, constMask, r1, target,
79362                         (char*)pDef, P4_FUNCDEF);
79363       sqlite3VdbeChangeP5(v, (u8)nFarg);
79364       if( nFarg && constMask==0 ){
79365         sqlite3ReleaseTempRange(pParse, r1, nFarg);
79366       }
79367       break;
79368     }
79369 #ifndef SQLITE_OMIT_SUBQUERY
79370     case TK_EXISTS:
79371     case TK_SELECT: {
79372       testcase( op==TK_EXISTS );
79373       testcase( op==TK_SELECT );
79374       inReg = sqlite3CodeSubselect(pParse, pExpr, 0, 0);
79375       break;
79376     }
79377     case TK_IN: {
79378       int destIfFalse = sqlite3VdbeMakeLabel(v);
79379       int destIfNull = sqlite3VdbeMakeLabel(v);
79380       sqlite3VdbeAddOp2(v, OP_Null, 0, target);
79381       sqlite3ExprCodeIN(pParse, pExpr, destIfFalse, destIfNull);
79382       sqlite3VdbeAddOp2(v, OP_Integer, 1, target);
79383       sqlite3VdbeResolveLabel(v, destIfFalse);
79384       sqlite3VdbeAddOp2(v, OP_AddImm, target, 0);
79385       sqlite3VdbeResolveLabel(v, destIfNull);
79386       break;
79387     }
79388 #endif /* SQLITE_OMIT_SUBQUERY */
79389 
79390 
79391     /*
79392     **    x BETWEEN y AND z
79393     **
79394     ** This is equivalent to
79395     **
79396     **    x>=y AND x<=z
79397     **
79398     ** X is stored in pExpr->pLeft.
79399     ** Y is stored in pExpr->pList->a[0].pExpr.
79400     ** Z is stored in pExpr->pList->a[1].pExpr.
79401     */
79402     case TK_BETWEEN: {
79403       Expr *pLeft = pExpr->pLeft;
79404       struct ExprList_item *pLItem = pExpr->x.pList->a;
79405       Expr *pRight = pLItem->pExpr;
79406 
79407       r1 = sqlite3ExprCodeTemp(pParse, pLeft, &regFree1);
79408       r2 = sqlite3ExprCodeTemp(pParse, pRight, &regFree2);
79409       testcase( regFree1==0 );
79410       testcase( regFree2==0 );
79411       r3 = sqlite3GetTempReg(pParse);
79412       r4 = sqlite3GetTempReg(pParse);
79413       codeCompare(pParse, pLeft, pRight, OP_Ge,
79414                   r1, r2, r3, SQLITE_STOREP2);
79415       pLItem++;
79416       pRight = pLItem->pExpr;
79417       sqlite3ReleaseTempReg(pParse, regFree2);
79418       r2 = sqlite3ExprCodeTemp(pParse, pRight, &regFree2);
79419       testcase( regFree2==0 );
79420       codeCompare(pParse, pLeft, pRight, OP_Le, r1, r2, r4, SQLITE_STOREP2);
79421       sqlite3VdbeAddOp3(v, OP_And, r3, r4, target);
79422       sqlite3ReleaseTempReg(pParse, r3);
79423       sqlite3ReleaseTempReg(pParse, r4);
79424       break;
79425     }
79426     case TK_COLLATE: 
79427     case TK_UPLUS: {
79428       inReg = sqlite3ExprCodeTarget(pParse, pExpr->pLeft, target);
79429       break;
79430     }
79431 
79432     case TK_TRIGGER: {
79433       /* If the opcode is TK_TRIGGER, then the expression is a reference
79434       ** to a column in the new.* or old.* pseudo-tables available to
79435       ** trigger programs. In this case Expr.iTable is set to 1 for the
79436       ** new.* pseudo-table, or 0 for the old.* pseudo-table. Expr.iColumn
79437       ** is set to the column of the pseudo-table to read, or to -1 to
79438       ** read the rowid field.
79439       **
79440       ** The expression is implemented using an OP_Param opcode. The p1
79441       ** parameter is set to 0 for an old.rowid reference, or to (i+1)
79442       ** to reference another column of the old.* pseudo-table, where 
79443       ** i is the index of the column. For a new.rowid reference, p1 is
79444       ** set to (n+1), where n is the number of columns in each pseudo-table.
79445       ** For a reference to any other column in the new.* pseudo-table, p1
79446       ** is set to (n+2+i), where n and i are as defined previously. For
79447       ** example, if the table on which triggers are being fired is
79448       ** declared as:
79449       **
79450       **   CREATE TABLE t1(a, b);
79451       **
79452       ** Then p1 is interpreted as follows:
79453       **
79454       **   p1==0   ->    old.rowid     p1==3   ->    new.rowid
79455       **   p1==1   ->    old.a         p1==4   ->    new.a
79456       **   p1==2   ->    old.b         p1==5   ->    new.b       
79457       */
79458       Table *pTab = pExpr->pTab;
79459       int p1 = pExpr->iTable * (pTab->nCol+1) + 1 + pExpr->iColumn;
79460 
79461       assert( pExpr->iTable==0 || pExpr->iTable==1 );
79462       assert( pExpr->iColumn>=-1 && pExpr->iColumn<pTab->nCol );
79463       assert( pTab->iPKey<0 || pExpr->iColumn!=pTab->iPKey );
79464       assert( p1>=0 && p1<(pTab->nCol*2+2) );
79465 
79466       sqlite3VdbeAddOp2(v, OP_Param, p1, target);
79467       VdbeComment((v, "%s.%s -> $%d",
79468         (pExpr->iTable ? "new" : "old"),
79469         (pExpr->iColumn<0 ? "rowid" : pExpr->pTab->aCol[pExpr->iColumn].zName),
79470         target
79471       ));
79472 
79473 #ifndef SQLITE_OMIT_FLOATING_POINT
79474       /* If the column has REAL affinity, it may currently be stored as an
79475       ** integer. Use OP_RealAffinity to make sure it is really real.  */
79476       if( pExpr->iColumn>=0 
79477        && pTab->aCol[pExpr->iColumn].affinity==SQLITE_AFF_REAL
79478       ){
79479         sqlite3VdbeAddOp1(v, OP_RealAffinity, target);
79480       }
79481 #endif
79482       break;
79483     }
79484 
79485 
79486     /*
79487     ** Form A:
79488     **   CASE x WHEN e1 THEN r1 WHEN e2 THEN r2 ... WHEN eN THEN rN ELSE y END
79489     **
79490     ** Form B:
79491     **   CASE WHEN e1 THEN r1 WHEN e2 THEN r2 ... WHEN eN THEN rN ELSE y END
79492     **
79493     ** Form A is can be transformed into the equivalent form B as follows:
79494     **   CASE WHEN x=e1 THEN r1 WHEN x=e2 THEN r2 ...
79495     **        WHEN x=eN THEN rN ELSE y END
79496     **
79497     ** X (if it exists) is in pExpr->pLeft.
79498     ** Y is in the last element of pExpr->x.pList if pExpr->x.pList->nExpr is
79499     ** odd.  The Y is also optional.  If the number of elements in x.pList
79500     ** is even, then Y is omitted and the "otherwise" result is NULL.
79501     ** Ei is in pExpr->pList->a[i*2] and Ri is pExpr->pList->a[i*2+1].
79502     **
79503     ** The result of the expression is the Ri for the first matching Ei,
79504     ** or if there is no matching Ei, the ELSE term Y, or if there is
79505     ** no ELSE term, NULL.
79506     */
79507     default: assert( op==TK_CASE ); {
79508       int endLabel;                     /* GOTO label for end of CASE stmt */
79509       int nextCase;                     /* GOTO label for next WHEN clause */
79510       int nExpr;                        /* 2x number of WHEN terms */
79511       int i;                            /* Loop counter */
79512       ExprList *pEList;                 /* List of WHEN terms */
79513       struct ExprList_item *aListelem;  /* Array of WHEN terms */
79514       Expr opCompare;                   /* The X==Ei expression */
79515       Expr *pX;                         /* The X expression */
79516       Expr *pTest = 0;                  /* X==Ei (form A) or just Ei (form B) */
79517       VVA_ONLY( int iCacheLevel = pParse->iCacheLevel; )
79518 
79519       assert( !ExprHasProperty(pExpr, EP_xIsSelect) && pExpr->x.pList );
79520       assert(pExpr->x.pList->nExpr > 0);
79521       pEList = pExpr->x.pList;
79522       aListelem = pEList->a;
79523       nExpr = pEList->nExpr;
79524       endLabel = sqlite3VdbeMakeLabel(v);
79525       if( (pX = pExpr->pLeft)!=0 ){
79526         tempX = *pX;
79527         testcase( pX->op==TK_COLUMN );
79528         exprToRegister(&tempX, sqlite3ExprCodeTemp(pParse, pX, &regFree1));
79529         testcase( regFree1==0 );
79530         opCompare.op = TK_EQ;
79531         opCompare.pLeft = &tempX;
79532         pTest = &opCompare;
79533         /* Ticket b351d95f9cd5ef17e9d9dbae18f5ca8611190001:
79534         ** The value in regFree1 might get SCopy-ed into the file result.
79535         ** So make sure that the regFree1 register is not reused for other
79536         ** purposes and possibly overwritten.  */
79537         regFree1 = 0;
79538       }
79539       for(i=0; i<nExpr-1; i=i+2){
79540         sqlite3ExprCachePush(pParse);
79541         if( pX ){
79542           assert( pTest!=0 );
79543           opCompare.pRight = aListelem[i].pExpr;
79544         }else{
79545           pTest = aListelem[i].pExpr;
79546         }
79547         nextCase = sqlite3VdbeMakeLabel(v);
79548         testcase( pTest->op==TK_COLUMN );
79549         sqlite3ExprIfFalse(pParse, pTest, nextCase, SQLITE_JUMPIFNULL);
79550         testcase( aListelem[i+1].pExpr->op==TK_COLUMN );
79551         sqlite3ExprCode(pParse, aListelem[i+1].pExpr, target);
79552         sqlite3VdbeAddOp2(v, OP_Goto, 0, endLabel);
79553         sqlite3ExprCachePop(pParse, 1);
79554         sqlite3VdbeResolveLabel(v, nextCase);
79555       }
79556       if( (nExpr&1)!=0 ){
79557         sqlite3ExprCachePush(pParse);
79558         sqlite3ExprCode(pParse, pEList->a[nExpr-1].pExpr, target);
79559         sqlite3ExprCachePop(pParse, 1);
79560       }else{
79561         sqlite3VdbeAddOp2(v, OP_Null, 0, target);
79562       }
79563       assert( db->mallocFailed || pParse->nErr>0 
79564            || pParse->iCacheLevel==iCacheLevel );
79565       sqlite3VdbeResolveLabel(v, endLabel);
79566       break;
79567     }
79568 #ifndef SQLITE_OMIT_TRIGGER
79569     case TK_RAISE: {
79570       assert( pExpr->affinity==OE_Rollback 
79571            || pExpr->affinity==OE_Abort
79572            || pExpr->affinity==OE_Fail
79573            || pExpr->affinity==OE_Ignore
79574       );
79575       if( !pParse->pTriggerTab ){
79576         sqlite3ErrorMsg(pParse,
79577                        "RAISE() may only be used within a trigger-program");
79578         return 0;
79579       }
79580       if( pExpr->affinity==OE_Abort ){
79581         sqlite3MayAbort(pParse);
79582       }
79583       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79584       if( pExpr->affinity==OE_Ignore ){
79585         sqlite3VdbeAddOp4(
79586             v, OP_Halt, SQLITE_OK, OE_Ignore, 0, pExpr->u.zToken,0);
79587       }else{
79588         sqlite3HaltConstraint(pParse, SQLITE_CONSTRAINT_TRIGGER,
79589                               pExpr->affinity, pExpr->u.zToken, 0, 0);
79590       }
79591 
79592       break;
79593     }
79594 #endif
79595   }
79596   sqlite3ReleaseTempReg(pParse, regFree1);
79597   sqlite3ReleaseTempReg(pParse, regFree2);
79598   return inReg;
79599 }
79600 
79601 /*
79602 ** Factor out the code of the given expression to initialization time.
79603 */
79604 SQLITE_PRIVATE void sqlite3ExprCodeAtInit(
79605   Parse *pParse,    /* Parsing context */
79606   Expr *pExpr,      /* The expression to code when the VDBE initializes */
79607   int regDest,      /* Store the value in this register */
79608   u8 reusable       /* True if this expression is reusable */
79609 ){
79610   ExprList *p;
79611   assert( ConstFactorOk(pParse) );
79612   p = pParse->pConstExpr;
79613   pExpr = sqlite3ExprDup(pParse->db, pExpr, 0);
79614   p = sqlite3ExprListAppend(pParse, p, pExpr);
79615   if( p ){
79616      struct ExprList_item *pItem = &p->a[p->nExpr-1];
79617      pItem->u.iConstExprReg = regDest;
79618      pItem->reusable = reusable;
79619   }
79620   pParse->pConstExpr = p;
79621 }
79622 
79623 /*
79624 ** Generate code to evaluate an expression and store the results
79625 ** into a register.  Return the register number where the results
79626 ** are stored.
79627 **
79628 ** If the register is a temporary register that can be deallocated,
79629 ** then write its number into *pReg.  If the result register is not
79630 ** a temporary, then set *pReg to zero.
79631 **
79632 ** If pExpr is a constant, then this routine might generate this
79633 ** code to fill the register in the initialization section of the
79634 ** VDBE program, in order to factor it out of the evaluation loop.
79635 */
79636 SQLITE_PRIVATE int sqlite3ExprCodeTemp(Parse *pParse, Expr *pExpr, int *pReg){
79637   int r2;
79638   pExpr = sqlite3ExprSkipCollate(pExpr);
79639   if( ConstFactorOk(pParse)
79640    && pExpr->op!=TK_REGISTER
79641    && sqlite3ExprIsConstantNotJoin(pExpr)
79642   ){
79643     ExprList *p = pParse->pConstExpr;
79644     int i;
79645     *pReg  = 0;
79646     if( p ){
79647       struct ExprList_item *pItem;
79648       for(pItem=p->a, i=p->nExpr; i>0; pItem++, i--){
79649         if( pItem->reusable && sqlite3ExprCompare(pItem->pExpr,pExpr,-1)==0 ){
79650           return pItem->u.iConstExprReg;
79651         }
79652       }
79653     }
79654     r2 = ++pParse->nMem;
79655     sqlite3ExprCodeAtInit(pParse, pExpr, r2, 1);
79656   }else{
79657     int r1 = sqlite3GetTempReg(pParse);
79658     r2 = sqlite3ExprCodeTarget(pParse, pExpr, r1);
79659     if( r2==r1 ){
79660       *pReg = r1;
79661     }else{
79662       sqlite3ReleaseTempReg(pParse, r1);
79663       *pReg = 0;
79664     }
79665   }
79666   return r2;
79667 }
79668 
79669 /*
79670 ** Generate code that will evaluate expression pExpr and store the
79671 ** results in register target.  The results are guaranteed to appear
79672 ** in register target.
79673 */
79674 SQLITE_PRIVATE int sqlite3ExprCode(Parse *pParse, Expr *pExpr, int target){
79675   int inReg;
79676 
79677   assert( target>0 && target<=pParse->nMem );
79678   if( pExpr && pExpr->op==TK_REGISTER ){
79679     sqlite3VdbeAddOp2(pParse->pVdbe, OP_Copy, pExpr->iTable, target);
79680   }else{
79681     inReg = sqlite3ExprCodeTarget(pParse, pExpr, target);
79682     assert( pParse->pVdbe || pParse->db->mallocFailed );
79683     if( inReg!=target && pParse->pVdbe ){
79684       sqlite3VdbeAddOp2(pParse->pVdbe, OP_SCopy, inReg, target);
79685     }
79686   }
79687   return target;
79688 }
79689 
79690 /*
79691 ** Generate code that evalutes the given expression and puts the result
79692 ** in register target.
79693 **
79694 ** Also make a copy of the expression results into another "cache" register
79695 ** and modify the expression so that the next time it is evaluated,
79696 ** the result is a copy of the cache register.
79697 **
79698 ** This routine is used for expressions that are used multiple 
79699 ** times.  They are evaluated once and the results of the expression
79700 ** are reused.
79701 */
79702 SQLITE_PRIVATE int sqlite3ExprCodeAndCache(Parse *pParse, Expr *pExpr, int target){
79703   Vdbe *v = pParse->pVdbe;
79704   int inReg;
79705   inReg = sqlite3ExprCode(pParse, pExpr, target);
79706   assert( target>0 );
79707   /* The only place, other than this routine, where expressions can be
79708   ** converted to TK_REGISTER is internal subexpressions in BETWEEN and
79709   ** CASE operators.  Neither ever calls this routine.  And this routine
79710   ** is never called twice on the same expression.  Hence it is impossible
79711   ** for the input to this routine to already be a register.  Nevertheless,
79712   ** it seems prudent to keep the ALWAYS() in case the conditions above
79713   ** change with future modifications or enhancements. */
79714   if( ALWAYS(pExpr->op!=TK_REGISTER) ){  
79715     int iMem;
79716     iMem = ++pParse->nMem;
79717     sqlite3VdbeAddOp2(v, OP_Copy, inReg, iMem);
79718     exprToRegister(pExpr, iMem);
79719   }
79720   return inReg;
79721 }
79722 
79723 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
79724 /*
79725 ** Generate a human-readable explanation of an expression tree.
79726 */
79727 SQLITE_PRIVATE void sqlite3ExplainExpr(Vdbe *pOut, Expr *pExpr){
79728   int op;                   /* The opcode being coded */
79729   const char *zBinOp = 0;   /* Binary operator */
79730   const char *zUniOp = 0;   /* Unary operator */
79731   if( pExpr==0 ){
79732     op = TK_NULL;
79733   }else{
79734     op = pExpr->op;
79735   }
79736   switch( op ){
79737     case TK_AGG_COLUMN: {
79738       sqlite3ExplainPrintf(pOut, "AGG{%d:%d}",
79739             pExpr->iTable, pExpr->iColumn);
79740       break;
79741     }
79742     case TK_COLUMN: {
79743       if( pExpr->iTable<0 ){
79744         /* This only happens when coding check constraints */
79745         sqlite3ExplainPrintf(pOut, "COLUMN(%d)", pExpr->iColumn);
79746       }else{
79747         sqlite3ExplainPrintf(pOut, "{%d:%d}",
79748                              pExpr->iTable, pExpr->iColumn);
79749       }
79750       break;
79751     }
79752     case TK_INTEGER: {
79753       if( pExpr->flags & EP_IntValue ){
79754         sqlite3ExplainPrintf(pOut, "%d", pExpr->u.iValue);
79755       }else{
79756         sqlite3ExplainPrintf(pOut, "%s", pExpr->u.zToken);
79757       }
79758       break;
79759     }
79760 #ifndef SQLITE_OMIT_FLOATING_POINT
79761     case TK_FLOAT: {
79762       sqlite3ExplainPrintf(pOut,"%s", pExpr->u.zToken);
79763       break;
79764     }
79765 #endif
79766     case TK_STRING: {
79767       sqlite3ExplainPrintf(pOut,"%Q", pExpr->u.zToken);
79768       break;
79769     }
79770     case TK_NULL: {
79771       sqlite3ExplainPrintf(pOut,"NULL");
79772       break;
79773     }
79774 #ifndef SQLITE_OMIT_BLOB_LITERAL
79775     case TK_BLOB: {
79776       sqlite3ExplainPrintf(pOut,"%s", pExpr->u.zToken);
79777       break;
79778     }
79779 #endif
79780     case TK_VARIABLE: {
79781       sqlite3ExplainPrintf(pOut,"VARIABLE(%s,%d)",
79782                            pExpr->u.zToken, pExpr->iColumn);
79783       break;
79784     }
79785     case TK_REGISTER: {
79786       sqlite3ExplainPrintf(pOut,"REGISTER(%d)", pExpr->iTable);
79787       break;
79788     }
79789     case TK_AS: {
79790       sqlite3ExplainExpr(pOut, pExpr->pLeft);
79791       break;
79792     }
79793 #ifndef SQLITE_OMIT_CAST
79794     case TK_CAST: {
79795       /* Expressions of the form:   CAST(pLeft AS token) */
79796       const char *zAff = "unk";
79797       switch( sqlite3AffinityType(pExpr->u.zToken, 0) ){
79798         case SQLITE_AFF_TEXT:    zAff = "TEXT";     break;
79799         case SQLITE_AFF_NONE:    zAff = "NONE";     break;
79800         case SQLITE_AFF_NUMERIC: zAff = "NUMERIC";  break;
79801         case SQLITE_AFF_INTEGER: zAff = "INTEGER";  break;
79802         case SQLITE_AFF_REAL:    zAff = "REAL";     break;
79803       }
79804       sqlite3ExplainPrintf(pOut, "CAST-%s(", zAff);
79805       sqlite3ExplainExpr(pOut, pExpr->pLeft);
79806       sqlite3ExplainPrintf(pOut, ")");
79807       break;
79808     }
79809 #endif /* SQLITE_OMIT_CAST */
79810     case TK_LT:      zBinOp = "LT";     break;
79811     case TK_LE:      zBinOp = "LE";     break;
79812     case TK_GT:      zBinOp = "GT";     break;
79813     case TK_GE:      zBinOp = "GE";     break;
79814     case TK_NE:      zBinOp = "NE";     break;
79815     case TK_EQ:      zBinOp = "EQ";     break;
79816     case TK_IS:      zBinOp = "IS";     break;
79817     case TK_ISNOT:   zBinOp = "ISNOT";  break;
79818     case TK_AND:     zBinOp = "AND";    break;
79819     case TK_OR:      zBinOp = "OR";     break;
79820     case TK_PLUS:    zBinOp = "ADD";    break;
79821     case TK_STAR:    zBinOp = "MUL";    break;
79822     case TK_MINUS:   zBinOp = "SUB";    break;
79823     case TK_REM:     zBinOp = "REM";    break;
79824     case TK_BITAND:  zBinOp = "BITAND"; break;
79825     case TK_BITOR:   zBinOp = "BITOR";  break;
79826     case TK_SLASH:   zBinOp = "DIV";    break;
79827     case TK_LSHIFT:  zBinOp = "LSHIFT"; break;
79828     case TK_RSHIFT:  zBinOp = "RSHIFT"; break;
79829     case TK_CONCAT:  zBinOp = "CONCAT"; break;
79830 
79831     case TK_UMINUS:  zUniOp = "UMINUS"; break;
79832     case TK_UPLUS:   zUniOp = "UPLUS";  break;
79833     case TK_BITNOT:  zUniOp = "BITNOT"; break;
79834     case TK_NOT:     zUniOp = "NOT";    break;
79835     case TK_ISNULL:  zUniOp = "ISNULL"; break;
79836     case TK_NOTNULL: zUniOp = "NOTNULL"; break;
79837 
79838     case TK_COLLATE: {
79839       sqlite3ExplainExpr(pOut, pExpr->pLeft);
79840       sqlite3ExplainPrintf(pOut,".COLLATE(%s)",pExpr->u.zToken);
79841       break;
79842     }
79843 
79844     case TK_AGG_FUNCTION:
79845     case TK_FUNCTION: {
79846       ExprList *pFarg;       /* List of function arguments */
79847       if( ExprHasProperty(pExpr, EP_TokenOnly) ){
79848         pFarg = 0;
79849       }else{
79850         pFarg = pExpr->x.pList;
79851       }
79852       if( op==TK_AGG_FUNCTION ){
79853         sqlite3ExplainPrintf(pOut, "AGG_FUNCTION%d:%s(",
79854                              pExpr->op2, pExpr->u.zToken);
79855       }else{
79856         sqlite3ExplainPrintf(pOut, "FUNCTION:%s(", pExpr->u.zToken);
79857       }
79858       if( pFarg ){
79859         sqlite3ExplainExprList(pOut, pFarg);
79860       }
79861       sqlite3ExplainPrintf(pOut, ")");
79862       break;
79863     }
79864 #ifndef SQLITE_OMIT_SUBQUERY
79865     case TK_EXISTS: {
79866       sqlite3ExplainPrintf(pOut, "EXISTS(");
79867       sqlite3ExplainSelect(pOut, pExpr->x.pSelect);
79868       sqlite3ExplainPrintf(pOut,")");
79869       break;
79870     }
79871     case TK_SELECT: {
79872       sqlite3ExplainPrintf(pOut, "(");
79873       sqlite3ExplainSelect(pOut, pExpr->x.pSelect);
79874       sqlite3ExplainPrintf(pOut, ")");
79875       break;
79876     }
79877     case TK_IN: {
79878       sqlite3ExplainPrintf(pOut, "IN(");
79879       sqlite3ExplainExpr(pOut, pExpr->pLeft);
79880       sqlite3ExplainPrintf(pOut, ",");
79881       if( ExprHasProperty(pExpr, EP_xIsSelect) ){
79882         sqlite3ExplainSelect(pOut, pExpr->x.pSelect);
79883       }else{
79884         sqlite3ExplainExprList(pOut, pExpr->x.pList);
79885       }
79886       sqlite3ExplainPrintf(pOut, ")");
79887       break;
79888     }
79889 #endif /* SQLITE_OMIT_SUBQUERY */
79890 
79891     /*
79892     **    x BETWEEN y AND z
79893     **
79894     ** This is equivalent to
79895     **
79896     **    x>=y AND x<=z
79897     **
79898     ** X is stored in pExpr->pLeft.
79899     ** Y is stored in pExpr->pList->a[0].pExpr.
79900     ** Z is stored in pExpr->pList->a[1].pExpr.
79901     */
79902     case TK_BETWEEN: {
79903       Expr *pX = pExpr->pLeft;
79904       Expr *pY = pExpr->x.pList->a[0].pExpr;
79905       Expr *pZ = pExpr->x.pList->a[1].pExpr;
79906       sqlite3ExplainPrintf(pOut, "BETWEEN(");
79907       sqlite3ExplainExpr(pOut, pX);
79908       sqlite3ExplainPrintf(pOut, ",");
79909       sqlite3ExplainExpr(pOut, pY);
79910       sqlite3ExplainPrintf(pOut, ",");
79911       sqlite3ExplainExpr(pOut, pZ);
79912       sqlite3ExplainPrintf(pOut, ")");
79913       break;
79914     }
79915     case TK_TRIGGER: {
79916       /* If the opcode is TK_TRIGGER, then the expression is a reference
79917       ** to a column in the new.* or old.* pseudo-tables available to
79918       ** trigger programs. In this case Expr.iTable is set to 1 for the
79919       ** new.* pseudo-table, or 0 for the old.* pseudo-table. Expr.iColumn
79920       ** is set to the column of the pseudo-table to read, or to -1 to
79921       ** read the rowid field.
79922       */
79923       sqlite3ExplainPrintf(pOut, "%s(%d)", 
79924           pExpr->iTable ? "NEW" : "OLD", pExpr->iColumn);
79925       break;
79926     }
79927     case TK_CASE: {
79928       sqlite3ExplainPrintf(pOut, "CASE(");
79929       sqlite3ExplainExpr(pOut, pExpr->pLeft);
79930       sqlite3ExplainPrintf(pOut, ",");
79931       sqlite3ExplainExprList(pOut, pExpr->x.pList);
79932       break;
79933     }
79934 #ifndef SQLITE_OMIT_TRIGGER
79935     case TK_RAISE: {
79936       const char *zType = "unk";
79937       switch( pExpr->affinity ){
79938         case OE_Rollback:   zType = "rollback";  break;
79939         case OE_Abort:      zType = "abort";     break;
79940         case OE_Fail:       zType = "fail";      break;
79941         case OE_Ignore:     zType = "ignore";    break;
79942       }
79943       sqlite3ExplainPrintf(pOut, "RAISE-%s(%s)", zType, pExpr->u.zToken);
79944       break;
79945     }
79946 #endif
79947   }
79948   if( zBinOp ){
79949     sqlite3ExplainPrintf(pOut,"%s(", zBinOp);
79950     sqlite3ExplainExpr(pOut, pExpr->pLeft);
79951     sqlite3ExplainPrintf(pOut,",");
79952     sqlite3ExplainExpr(pOut, pExpr->pRight);
79953     sqlite3ExplainPrintf(pOut,")");
79954   }else if( zUniOp ){
79955     sqlite3ExplainPrintf(pOut,"%s(", zUniOp);
79956     sqlite3ExplainExpr(pOut, pExpr->pLeft);
79957     sqlite3ExplainPrintf(pOut,")");
79958   }
79959 }
79960 #endif /* defined(SQLITE_ENABLE_TREE_EXPLAIN) */
79961 
79962 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
79963 /*
79964 ** Generate a human-readable explanation of an expression list.
79965 */
79966 SQLITE_PRIVATE void sqlite3ExplainExprList(Vdbe *pOut, ExprList *pList){
79967   int i;
79968   if( pList==0 || pList->nExpr==0 ){
79969     sqlite3ExplainPrintf(pOut, "(empty-list)");
79970     return;
79971   }else if( pList->nExpr==1 ){
79972     sqlite3ExplainExpr(pOut, pList->a[0].pExpr);
79973   }else{
79974     sqlite3ExplainPush(pOut);
79975     for(i=0; i<pList->nExpr; i++){
79976       sqlite3ExplainPrintf(pOut, "item[%d] = ", i);
79977       sqlite3ExplainPush(pOut);
79978       sqlite3ExplainExpr(pOut, pList->a[i].pExpr);
79979       sqlite3ExplainPop(pOut);
79980       if( pList->a[i].zName ){
79981         sqlite3ExplainPrintf(pOut, " AS %s", pList->a[i].zName);
79982       }
79983       if( pList->a[i].bSpanIsTab ){
79984         sqlite3ExplainPrintf(pOut, " (%s)", pList->a[i].zSpan);
79985       }
79986       if( i<pList->nExpr-1 ){
79987         sqlite3ExplainNL(pOut);
79988       }
79989     }
79990     sqlite3ExplainPop(pOut);
79991   }
79992 }
79993 #endif /* SQLITE_DEBUG */
79994 
79995 /*
79996 ** Generate code that pushes the value of every element of the given
79997 ** expression list into a sequence of registers beginning at target.
79998 **
79999 ** Return the number of elements evaluated.
80000 **
80001 ** The SQLITE_ECEL_DUP flag prevents the arguments from being
80002 ** filled using OP_SCopy.  OP_Copy must be used instead.
80003 **
80004 ** The SQLITE_ECEL_FACTOR argument allows constant arguments to be
80005 ** factored out into initialization code.
80006 */
80007 SQLITE_PRIVATE int sqlite3ExprCodeExprList(
80008   Parse *pParse,     /* Parsing context */
80009   ExprList *pList,   /* The expression list to be coded */
80010   int target,        /* Where to write results */
80011   u8 flags           /* SQLITE_ECEL_* flags */
80012 ){
80013   struct ExprList_item *pItem;
80014   int i, n;
80015   u8 copyOp = (flags & SQLITE_ECEL_DUP) ? OP_Copy : OP_SCopy;
80016   assert( pList!=0 );
80017   assert( target>0 );
80018   assert( pParse->pVdbe!=0 );  /* Never gets this far otherwise */
80019   n = pList->nExpr;
80020   if( !ConstFactorOk(pParse) ) flags &= ~SQLITE_ECEL_FACTOR;
80021   for(pItem=pList->a, i=0; i<n; i++, pItem++){
80022     Expr *pExpr = pItem->pExpr;
80023     if( (flags & SQLITE_ECEL_FACTOR)!=0 && sqlite3ExprIsConstant(pExpr) ){
80024       sqlite3ExprCodeAtInit(pParse, pExpr, target+i, 0);
80025     }else{
80026       int inReg = sqlite3ExprCodeTarget(pParse, pExpr, target+i);
80027       if( inReg!=target+i ){
80028         sqlite3VdbeAddOp2(pParse->pVdbe, copyOp, inReg, target+i);
80029       }
80030     }
80031   }
80032   return n;
80033 }
80034 
80035 /*
80036 ** Generate code for a BETWEEN operator.
80037 **
80038 **    x BETWEEN y AND z
80039 **
80040 ** The above is equivalent to 
80041 **
80042 **    x>=y AND x<=z
80043 **
80044 ** Code it as such, taking care to do the common subexpression
80045 ** elementation of x.
80046 */
80047 static void exprCodeBetween(
80048   Parse *pParse,    /* Parsing and code generating context */
80049   Expr *pExpr,      /* The BETWEEN expression */
80050   int dest,         /* Jump here if the jump is taken */
80051   int jumpIfTrue,   /* Take the jump if the BETWEEN is true */
80052   int jumpIfNull    /* Take the jump if the BETWEEN is NULL */
80053 ){
80054   Expr exprAnd;     /* The AND operator in  x>=y AND x<=z  */
80055   Expr compLeft;    /* The  x>=y  term */
80056   Expr compRight;   /* The  x<=z  term */
80057   Expr exprX;       /* The  x  subexpression */
80058   int regFree1 = 0; /* Temporary use register */
80059 
80060   assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
80061   exprX = *pExpr->pLeft;
80062   exprAnd.op = TK_AND;
80063   exprAnd.pLeft = &compLeft;
80064   exprAnd.pRight = &compRight;
80065   compLeft.op = TK_GE;
80066   compLeft.pLeft = &exprX;
80067   compLeft.pRight = pExpr->x.pList->a[0].pExpr;
80068   compRight.op = TK_LE;
80069   compRight.pLeft = &exprX;
80070   compRight.pRight = pExpr->x.pList->a[1].pExpr;
80071   exprToRegister(&exprX, sqlite3ExprCodeTemp(pParse, &exprX, &regFree1));
80072   if( jumpIfTrue ){
80073     sqlite3ExprIfTrue(pParse, &exprAnd, dest, jumpIfNull);
80074   }else{
80075     sqlite3ExprIfFalse(pParse, &exprAnd, dest, jumpIfNull);
80076   }
80077   sqlite3ReleaseTempReg(pParse, regFree1);
80078 
80079   /* Ensure adequate test coverage */
80080   testcase( jumpIfTrue==0 && jumpIfNull==0 && regFree1==0 );
80081   testcase( jumpIfTrue==0 && jumpIfNull==0 && regFree1!=0 );
80082   testcase( jumpIfTrue==0 && jumpIfNull!=0 && regFree1==0 );
80083   testcase( jumpIfTrue==0 && jumpIfNull!=0 && regFree1!=0 );
80084   testcase( jumpIfTrue!=0 && jumpIfNull==0 && regFree1==0 );
80085   testcase( jumpIfTrue!=0 && jumpIfNull==0 && regFree1!=0 );
80086   testcase( jumpIfTrue!=0 && jumpIfNull!=0 && regFree1==0 );
80087   testcase( jumpIfTrue!=0 && jumpIfNull!=0 && regFree1!=0 );
80088 }
80089 
80090 /*
80091 ** Generate code for a boolean expression such that a jump is made
80092 ** to the label "dest" if the expression is true but execution
80093 ** continues straight thru if the expression is false.
80094 **
80095 ** If the expression evaluates to NULL (neither true nor false), then
80096 ** take the jump if the jumpIfNull flag is SQLITE_JUMPIFNULL.
80097 **
80098 ** This code depends on the fact that certain token values (ex: TK_EQ)
80099 ** are the same as opcode values (ex: OP_Eq) that implement the corresponding
80100 ** operation.  Special comments in vdbe.c and the mkopcodeh.awk script in
80101 ** the make process cause these values to align.  Assert()s in the code
80102 ** below verify that the numbers are aligned correctly.
80103 */
80104 SQLITE_PRIVATE void sqlite3ExprIfTrue(Parse *pParse, Expr *pExpr, int dest, int jumpIfNull){
80105   Vdbe *v = pParse->pVdbe;
80106   int op = 0;
80107   int regFree1 = 0;
80108   int regFree2 = 0;
80109   int r1, r2;
80110 
80111   assert( jumpIfNull==SQLITE_JUMPIFNULL || jumpIfNull==0 );
80112   if( NEVER(v==0) )     return;  /* Existence of VDBE checked by caller */
80113   if( NEVER(pExpr==0) ) return;  /* No way this can happen */
80114   op = pExpr->op;
80115   switch( op ){
80116     case TK_AND: {
80117       int d2 = sqlite3VdbeMakeLabel(v);
80118       testcase( jumpIfNull==0 );
80119       sqlite3ExprCachePush(pParse);
80120       sqlite3ExprIfFalse(pParse, pExpr->pLeft, d2,jumpIfNull^SQLITE_JUMPIFNULL);
80121       sqlite3ExprIfTrue(pParse, pExpr->pRight, dest, jumpIfNull);
80122       sqlite3VdbeResolveLabel(v, d2);
80123       sqlite3ExprCachePop(pParse, 1);
80124       break;
80125     }
80126     case TK_OR: {
80127       testcase( jumpIfNull==0 );
80128       sqlite3ExprIfTrue(pParse, pExpr->pLeft, dest, jumpIfNull);
80129       sqlite3ExprIfTrue(pParse, pExpr->pRight, dest, jumpIfNull);
80130       break;
80131     }
80132     case TK_NOT: {
80133       testcase( jumpIfNull==0 );
80134       sqlite3ExprIfFalse(pParse, pExpr->pLeft, dest, jumpIfNull);
80135       break;
80136     }
80137     case TK_LT:
80138     case TK_LE:
80139     case TK_GT:
80140     case TK_GE:
80141     case TK_NE:
80142     case TK_EQ: {
80143       assert( TK_LT==OP_Lt );
80144       assert( TK_LE==OP_Le );
80145       assert( TK_GT==OP_Gt );
80146       assert( TK_GE==OP_Ge );
80147       assert( TK_EQ==OP_Eq );
80148       assert( TK_NE==OP_Ne );
80149       testcase( op==TK_LT );
80150       testcase( op==TK_LE );
80151       testcase( op==TK_GT );
80152       testcase( op==TK_GE );
80153       testcase( op==TK_EQ );
80154       testcase( op==TK_NE );
80155       testcase( jumpIfNull==0 );
80156       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80157       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
80158       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
80159                   r1, r2, dest, jumpIfNull);
80160       testcase( regFree1==0 );
80161       testcase( regFree2==0 );
80162       break;
80163     }
80164     case TK_IS:
80165     case TK_ISNOT: {
80166       testcase( op==TK_IS );
80167       testcase( op==TK_ISNOT );
80168       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80169       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
80170       op = (op==TK_IS) ? TK_EQ : TK_NE;
80171       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
80172                   r1, r2, dest, SQLITE_NULLEQ);
80173       testcase( regFree1==0 );
80174       testcase( regFree2==0 );
80175       break;
80176     }
80177     case TK_ISNULL:
80178     case TK_NOTNULL: {
80179       assert( TK_ISNULL==OP_IsNull );
80180       assert( TK_NOTNULL==OP_NotNull );
80181       testcase( op==TK_ISNULL );
80182       testcase( op==TK_NOTNULL );
80183       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80184       sqlite3VdbeAddOp2(v, op, r1, dest);
80185       testcase( regFree1==0 );
80186       break;
80187     }
80188     case TK_BETWEEN: {
80189       testcase( jumpIfNull==0 );
80190       exprCodeBetween(pParse, pExpr, dest, 1, jumpIfNull);
80191       break;
80192     }
80193 #ifndef SQLITE_OMIT_SUBQUERY
80194     case TK_IN: {
80195       int destIfFalse = sqlite3VdbeMakeLabel(v);
80196       int destIfNull = jumpIfNull ? dest : destIfFalse;
80197       sqlite3ExprCodeIN(pParse, pExpr, destIfFalse, destIfNull);
80198       sqlite3VdbeAddOp2(v, OP_Goto, 0, dest);
80199       sqlite3VdbeResolveLabel(v, destIfFalse);
80200       break;
80201     }
80202 #endif
80203     default: {
80204       r1 = sqlite3ExprCodeTemp(pParse, pExpr, &regFree1);
80205       sqlite3VdbeAddOp3(v, OP_If, r1, dest, jumpIfNull!=0);
80206       testcase( regFree1==0 );
80207       testcase( jumpIfNull==0 );
80208       break;
80209     }
80210   }
80211   sqlite3ReleaseTempReg(pParse, regFree1);
80212   sqlite3ReleaseTempReg(pParse, regFree2);  
80213 }
80214 
80215 /*
80216 ** Generate code for a boolean expression such that a jump is made
80217 ** to the label "dest" if the expression is false but execution
80218 ** continues straight thru if the expression is true.
80219 **
80220 ** If the expression evaluates to NULL (neither true nor false) then
80221 ** jump if jumpIfNull is SQLITE_JUMPIFNULL or fall through if jumpIfNull
80222 ** is 0.
80223 */
80224 SQLITE_PRIVATE void sqlite3ExprIfFalse(Parse *pParse, Expr *pExpr, int dest, int jumpIfNull){
80225   Vdbe *v = pParse->pVdbe;
80226   int op = 0;
80227   int regFree1 = 0;
80228   int regFree2 = 0;
80229   int r1, r2;
80230 
80231   assert( jumpIfNull==SQLITE_JUMPIFNULL || jumpIfNull==0 );
80232   if( NEVER(v==0) ) return; /* Existence of VDBE checked by caller */
80233   if( pExpr==0 )    return;
80234 
80235   /* The value of pExpr->op and op are related as follows:
80236   **
80237   **       pExpr->op            op
80238   **       ---------          ----------
80239   **       TK_ISNULL          OP_NotNull
80240   **       TK_NOTNULL         OP_IsNull
80241   **       TK_NE              OP_Eq
80242   **       TK_EQ              OP_Ne
80243   **       TK_GT              OP_Le
80244   **       TK_LE              OP_Gt
80245   **       TK_GE              OP_Lt
80246   **       TK_LT              OP_Ge
80247   **
80248   ** For other values of pExpr->op, op is undefined and unused.
80249   ** The value of TK_ and OP_ constants are arranged such that we
80250   ** can compute the mapping above using the following expression.
80251   ** Assert()s verify that the computation is correct.
80252   */
80253   op = ((pExpr->op+(TK_ISNULL&1))^1)-(TK_ISNULL&1);
80254 
80255   /* Verify correct alignment of TK_ and OP_ constants
80256   */
80257   assert( pExpr->op!=TK_ISNULL || op==OP_NotNull );
80258   assert( pExpr->op!=TK_NOTNULL || op==OP_IsNull );
80259   assert( pExpr->op!=TK_NE || op==OP_Eq );
80260   assert( pExpr->op!=TK_EQ || op==OP_Ne );
80261   assert( pExpr->op!=TK_LT || op==OP_Ge );
80262   assert( pExpr->op!=TK_LE || op==OP_Gt );
80263   assert( pExpr->op!=TK_GT || op==OP_Le );
80264   assert( pExpr->op!=TK_GE || op==OP_Lt );
80265 
80266   switch( pExpr->op ){
80267     case TK_AND: {
80268       testcase( jumpIfNull==0 );
80269       sqlite3ExprIfFalse(pParse, pExpr->pLeft, dest, jumpIfNull);
80270       sqlite3ExprIfFalse(pParse, pExpr->pRight, dest, jumpIfNull);
80271       break;
80272     }
80273     case TK_OR: {
80274       int d2 = sqlite3VdbeMakeLabel(v);
80275       testcase( jumpIfNull==0 );
80276       sqlite3ExprCachePush(pParse);
80277       sqlite3ExprIfTrue(pParse, pExpr->pLeft, d2, jumpIfNull^SQLITE_JUMPIFNULL);
80278       sqlite3ExprIfFalse(pParse, pExpr->pRight, dest, jumpIfNull);
80279       sqlite3VdbeResolveLabel(v, d2);
80280       sqlite3ExprCachePop(pParse, 1);
80281       break;
80282     }
80283     case TK_NOT: {
80284       testcase( jumpIfNull==0 );
80285       sqlite3ExprIfTrue(pParse, pExpr->pLeft, dest, jumpIfNull);
80286       break;
80287     }
80288     case TK_LT:
80289     case TK_LE:
80290     case TK_GT:
80291     case TK_GE:
80292     case TK_NE:
80293     case TK_EQ: {
80294       testcase( op==TK_LT );
80295       testcase( op==TK_LE );
80296       testcase( op==TK_GT );
80297       testcase( op==TK_GE );
80298       testcase( op==TK_EQ );
80299       testcase( op==TK_NE );
80300       testcase( jumpIfNull==0 );
80301       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80302       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
80303       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
80304                   r1, r2, dest, jumpIfNull);
80305       testcase( regFree1==0 );
80306       testcase( regFree2==0 );
80307       break;
80308     }
80309     case TK_IS:
80310     case TK_ISNOT: {
80311       testcase( pExpr->op==TK_IS );
80312       testcase( pExpr->op==TK_ISNOT );
80313       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80314       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
80315       op = (pExpr->op==TK_IS) ? TK_NE : TK_EQ;
80316       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
80317                   r1, r2, dest, SQLITE_NULLEQ);
80318       testcase( regFree1==0 );
80319       testcase( regFree2==0 );
80320       break;
80321     }
80322     case TK_ISNULL:
80323     case TK_NOTNULL: {
80324       testcase( op==TK_ISNULL );
80325       testcase( op==TK_NOTNULL );
80326       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80327       sqlite3VdbeAddOp2(v, op, r1, dest);
80328       testcase( regFree1==0 );
80329       break;
80330     }
80331     case TK_BETWEEN: {
80332       testcase( jumpIfNull==0 );
80333       exprCodeBetween(pParse, pExpr, dest, 0, jumpIfNull);
80334       break;
80335     }
80336 #ifndef SQLITE_OMIT_SUBQUERY
80337     case TK_IN: {
80338       if( jumpIfNull ){
80339         sqlite3ExprCodeIN(pParse, pExpr, dest, dest);
80340       }else{
80341         int destIfNull = sqlite3VdbeMakeLabel(v);
80342         sqlite3ExprCodeIN(pParse, pExpr, dest, destIfNull);
80343         sqlite3VdbeResolveLabel(v, destIfNull);
80344       }
80345       break;
80346     }
80347 #endif
80348     default: {
80349       r1 = sqlite3ExprCodeTemp(pParse, pExpr, &regFree1);
80350       sqlite3VdbeAddOp3(v, OP_IfNot, r1, dest, jumpIfNull!=0);
80351       testcase( regFree1==0 );
80352       testcase( jumpIfNull==0 );
80353       break;
80354     }
80355   }
80356   sqlite3ReleaseTempReg(pParse, regFree1);
80357   sqlite3ReleaseTempReg(pParse, regFree2);
80358 }
80359 
80360 /*
80361 ** Do a deep comparison of two expression trees.  Return 0 if the two
80362 ** expressions are completely identical.  Return 1 if they differ only
80363 ** by a COLLATE operator at the top level.  Return 2 if there are differences
80364 ** other than the top-level COLLATE operator.
80365 **
80366 ** If any subelement of pB has Expr.iTable==(-1) then it is allowed
80367 ** to compare equal to an equivalent element in pA with Expr.iTable==iTab.
80368 **
80369 ** The pA side might be using TK_REGISTER.  If that is the case and pB is
80370 ** not using TK_REGISTER but is otherwise equivalent, then still return 0.
80371 **
80372 ** Sometimes this routine will return 2 even if the two expressions
80373 ** really are equivalent.  If we cannot prove that the expressions are
80374 ** identical, we return 2 just to be safe.  So if this routine
80375 ** returns 2, then you do not really know for certain if the two
80376 ** expressions are the same.  But if you get a 0 or 1 return, then you
80377 ** can be sure the expressions are the same.  In the places where
80378 ** this routine is used, it does not hurt to get an extra 2 - that
80379 ** just might result in some slightly slower code.  But returning
80380 ** an incorrect 0 or 1 could lead to a malfunction.
80381 */
80382 SQLITE_PRIVATE int sqlite3ExprCompare(Expr *pA, Expr *pB, int iTab){
80383   u32 combinedFlags;
80384   if( pA==0 || pB==0 ){
80385     return pB==pA ? 0 : 2;
80386   }
80387   combinedFlags = pA->flags | pB->flags;
80388   if( combinedFlags & EP_IntValue ){
80389     if( (pA->flags&pB->flags&EP_IntValue)!=0 && pA->u.iValue==pB->u.iValue ){
80390       return 0;
80391     }
80392     return 2;
80393   }
80394   if( pA->op!=pB->op ){
80395     if( pA->op==TK_COLLATE && sqlite3ExprCompare(pA->pLeft, pB, iTab)<2 ){
80396       return 1;
80397     }
80398     if( pB->op==TK_COLLATE && sqlite3ExprCompare(pA, pB->pLeft, iTab)<2 ){
80399       return 1;
80400     }
80401     return 2;
80402   }
80403   if( pA->op!=TK_COLUMN && ALWAYS(pA->op!=TK_AGG_COLUMN) && pA->u.zToken ){
80404     if( strcmp(pA->u.zToken,pB->u.zToken)!=0 ){
80405       return pA->op==TK_COLLATE ? 1 : 2;
80406     }
80407   }
80408   if( (pA->flags & EP_Distinct)!=(pB->flags & EP_Distinct) ) return 2;
80409   if( ALWAYS((combinedFlags & EP_TokenOnly)==0) ){
80410     if( combinedFlags & EP_xIsSelect ) return 2;
80411     if( sqlite3ExprCompare(pA->pLeft, pB->pLeft, iTab) ) return 2;
80412     if( sqlite3ExprCompare(pA->pRight, pB->pRight, iTab) ) return 2;
80413     if( sqlite3ExprListCompare(pA->x.pList, pB->x.pList, iTab) ) return 2;
80414     if( ALWAYS((combinedFlags & EP_Reduced)==0) ){
80415       if( pA->iColumn!=pB->iColumn ) return 2;
80416       if( pA->iTable!=pB->iTable 
80417        && (pA->iTable!=iTab || NEVER(pB->iTable>=0)) ) return 2;
80418     }
80419   }
80420   return 0;
80421 }
80422 
80423 /*
80424 ** Compare two ExprList objects.  Return 0 if they are identical and 
80425 ** non-zero if they differ in any way.
80426 **
80427 ** If any subelement of pB has Expr.iTable==(-1) then it is allowed
80428 ** to compare equal to an equivalent element in pA with Expr.iTable==iTab.
80429 **
80430 ** This routine might return non-zero for equivalent ExprLists.  The
80431 ** only consequence will be disabled optimizations.  But this routine
80432 ** must never return 0 if the two ExprList objects are different, or
80433 ** a malfunction will result.
80434 **
80435 ** Two NULL pointers are considered to be the same.  But a NULL pointer
80436 ** always differs from a non-NULL pointer.
80437 */
80438 SQLITE_PRIVATE int sqlite3ExprListCompare(ExprList *pA, ExprList *pB, int iTab){
80439   int i;
80440   if( pA==0 && pB==0 ) return 0;
80441   if( pA==0 || pB==0 ) return 1;
80442   if( pA->nExpr!=pB->nExpr ) return 1;
80443   for(i=0; i<pA->nExpr; i++){
80444     Expr *pExprA = pA->a[i].pExpr;
80445     Expr *pExprB = pB->a[i].pExpr;
80446     if( pA->a[i].sortOrder!=pB->a[i].sortOrder ) return 1;
80447     if( sqlite3ExprCompare(pExprA, pExprB, iTab) ) return 1;
80448   }
80449   return 0;
80450 }
80451 
80452 /*
80453 ** Return true if we can prove the pE2 will always be true if pE1 is
80454 ** true.  Return false if we cannot complete the proof or if pE2 might
80455 ** be false.  Examples:
80456 **
80457 **     pE1: x==5       pE2: x==5             Result: true
80458 **     pE1: x>0        pE2: x==5             Result: false
80459 **     pE1: x=21       pE2: x=21 OR y=43     Result: true
80460 **     pE1: x!=123     pE2: x IS NOT NULL    Result: true
80461 **     pE1: x!=?1      pE2: x IS NOT NULL    Result: true
80462 **     pE1: x IS NULL  pE2: x IS NOT NULL    Result: false
80463 **     pE1: x IS ?2    pE2: x IS NOT NULL    Reuslt: false
80464 **
80465 ** When comparing TK_COLUMN nodes between pE1 and pE2, if pE2 has
80466 ** Expr.iTable<0 then assume a table number given by iTab.
80467 **
80468 ** When in doubt, return false.  Returning true might give a performance
80469 ** improvement.  Returning false might cause a performance reduction, but
80470 ** it will always give the correct answer and is hence always safe.
80471 */
80472 SQLITE_PRIVATE int sqlite3ExprImpliesExpr(Expr *pE1, Expr *pE2, int iTab){
80473   if( sqlite3ExprCompare(pE1, pE2, iTab)==0 ){
80474     return 1;
80475   }
80476   if( pE2->op==TK_OR
80477    && (sqlite3ExprImpliesExpr(pE1, pE2->pLeft, iTab)
80478              || sqlite3ExprImpliesExpr(pE1, pE2->pRight, iTab) )
80479   ){
80480     return 1;
80481   }
80482   if( pE2->op==TK_NOTNULL
80483    && sqlite3ExprCompare(pE1->pLeft, pE2->pLeft, iTab)==0
80484    && (pE1->op!=TK_ISNULL && pE1->op!=TK_IS)
80485   ){
80486     return 1;
80487   }
80488   return 0;
80489 }
80490 
80491 /*
80492 ** An instance of the following structure is used by the tree walker
80493 ** to count references to table columns in the arguments of an 
80494 ** aggregate function, in order to implement the
80495 ** sqlite3FunctionThisSrc() routine.
80496 */
80497 struct SrcCount {
80498   SrcList *pSrc;   /* One particular FROM clause in a nested query */
80499   int nThis;       /* Number of references to columns in pSrcList */
80500   int nOther;      /* Number of references to columns in other FROM clauses */
80501 };
80502 
80503 /*
80504 ** Count the number of references to columns.
80505 */
80506 static int exprSrcCount(Walker *pWalker, Expr *pExpr){
80507   /* The NEVER() on the second term is because sqlite3FunctionUsesThisSrc()
80508   ** is always called before sqlite3ExprAnalyzeAggregates() and so the
80509   ** TK_COLUMNs have not yet been converted into TK_AGG_COLUMN.  If
80510   ** sqlite3FunctionUsesThisSrc() is used differently in the future, the
80511   ** NEVER() will need to be removed. */
80512   if( pExpr->op==TK_COLUMN || NEVER(pExpr->op==TK_AGG_COLUMN) ){
80513     int i;
80514     struct SrcCount *p = pWalker->u.pSrcCount;
80515     SrcList *pSrc = p->pSrc;
80516     for(i=0; i<pSrc->nSrc; i++){
80517       if( pExpr->iTable==pSrc->a[i].iCursor ) break;
80518     }
80519     if( i<pSrc->nSrc ){
80520       p->nThis++;
80521     }else{
80522       p->nOther++;
80523     }
80524   }
80525   return WRC_Continue;
80526 }
80527 
80528 /*
80529 ** Determine if any of the arguments to the pExpr Function reference
80530 ** pSrcList.  Return true if they do.  Also return true if the function
80531 ** has no arguments or has only constant arguments.  Return false if pExpr
80532 ** references columns but not columns of tables found in pSrcList.
80533 */
80534 SQLITE_PRIVATE int sqlite3FunctionUsesThisSrc(Expr *pExpr, SrcList *pSrcList){
80535   Walker w;
80536   struct SrcCount cnt;
80537   assert( pExpr->op==TK_AGG_FUNCTION );
80538   memset(&w, 0, sizeof(w));
80539   w.xExprCallback = exprSrcCount;
80540   w.u.pSrcCount = &cnt;
80541   cnt.pSrc = pSrcList;
80542   cnt.nThis = 0;
80543   cnt.nOther = 0;
80544   sqlite3WalkExprList(&w, pExpr->x.pList);
80545   return cnt.nThis>0 || cnt.nOther==0;
80546 }
80547 
80548 /*
80549 ** Add a new element to the pAggInfo->aCol[] array.  Return the index of
80550 ** the new element.  Return a negative number if malloc fails.
80551 */
80552 static int addAggInfoColumn(sqlite3 *db, AggInfo *pInfo){
80553   int i;
80554   pInfo->aCol = sqlite3ArrayAllocate(
80555        db,
80556        pInfo->aCol,
80557        sizeof(pInfo->aCol[0]),
80558        &pInfo->nColumn,
80559        &i
80560   );
80561   return i;
80562 }    
80563 
80564 /*
80565 ** Add a new element to the pAggInfo->aFunc[] array.  Return the index of
80566 ** the new element.  Return a negative number if malloc fails.
80567 */
80568 static int addAggInfoFunc(sqlite3 *db, AggInfo *pInfo){
80569   int i;
80570   pInfo->aFunc = sqlite3ArrayAllocate(
80571        db, 
80572        pInfo->aFunc,
80573        sizeof(pInfo->aFunc[0]),
80574        &pInfo->nFunc,
80575        &i
80576   );
80577   return i;
80578 }    
80579 
80580 /*
80581 ** This is the xExprCallback for a tree walker.  It is used to
80582 ** implement sqlite3ExprAnalyzeAggregates().  See sqlite3ExprAnalyzeAggregates
80583 ** for additional information.
80584 */
80585 static int analyzeAggregate(Walker *pWalker, Expr *pExpr){
80586   int i;
80587   NameContext *pNC = pWalker->u.pNC;
80588   Parse *pParse = pNC->pParse;
80589   SrcList *pSrcList = pNC->pSrcList;
80590   AggInfo *pAggInfo = pNC->pAggInfo;
80591 
80592   switch( pExpr->op ){
80593     case TK_AGG_COLUMN:
80594     case TK_COLUMN: {
80595       testcase( pExpr->op==TK_AGG_COLUMN );
80596       testcase( pExpr->op==TK_COLUMN );
80597       /* Check to see if the column is in one of the tables in the FROM
80598       ** clause of the aggregate query */
80599       if( ALWAYS(pSrcList!=0) ){
80600         struct SrcList_item *pItem = pSrcList->a;
80601         for(i=0; i<pSrcList->nSrc; i++, pItem++){
80602           struct AggInfo_col *pCol;
80603           assert( !ExprHasProperty(pExpr, EP_TokenOnly|EP_Reduced) );
80604           if( pExpr->iTable==pItem->iCursor ){
80605             /* If we reach this point, it means that pExpr refers to a table
80606             ** that is in the FROM clause of the aggregate query.  
80607             **
80608             ** Make an entry for the column in pAggInfo->aCol[] if there
80609             ** is not an entry there already.
80610             */
80611             int k;
80612             pCol = pAggInfo->aCol;
80613             for(k=0; k<pAggInfo->nColumn; k++, pCol++){
80614               if( pCol->iTable==pExpr->iTable &&
80615                   pCol->iColumn==pExpr->iColumn ){
80616                 break;
80617               }
80618             }
80619             if( (k>=pAggInfo->nColumn)
80620              && (k = addAggInfoColumn(pParse->db, pAggInfo))>=0 
80621             ){
80622               pCol = &pAggInfo->aCol[k];
80623               pCol->pTab = pExpr->pTab;
80624               pCol->iTable = pExpr->iTable;
80625               pCol->iColumn = pExpr->iColumn;
80626               pCol->iMem = ++pParse->nMem;
80627               pCol->iSorterColumn = -1;
80628               pCol->pExpr = pExpr;
80629               if( pAggInfo->pGroupBy ){
80630                 int j, n;
80631                 ExprList *pGB = pAggInfo->pGroupBy;
80632                 struct ExprList_item *pTerm = pGB->a;
80633                 n = pGB->nExpr;
80634                 for(j=0; j<n; j++, pTerm++){
80635                   Expr *pE = pTerm->pExpr;
80636                   if( pE->op==TK_COLUMN && pE->iTable==pExpr->iTable &&
80637                       pE->iColumn==pExpr->iColumn ){
80638                     pCol->iSorterColumn = j;
80639                     break;
80640                   }
80641                 }
80642               }
80643               if( pCol->iSorterColumn<0 ){
80644                 pCol->iSorterColumn = pAggInfo->nSortingColumn++;
80645               }
80646             }
80647             /* There is now an entry for pExpr in pAggInfo->aCol[] (either
80648             ** because it was there before or because we just created it).
80649             ** Convert the pExpr to be a TK_AGG_COLUMN referring to that
80650             ** pAggInfo->aCol[] entry.
80651             */
80652             ExprSetVVAProperty(pExpr, EP_NoReduce);
80653             pExpr->pAggInfo = pAggInfo;
80654             pExpr->op = TK_AGG_COLUMN;
80655             pExpr->iAgg = (i16)k;
80656             break;
80657           } /* endif pExpr->iTable==pItem->iCursor */
80658         } /* end loop over pSrcList */
80659       }
80660       return WRC_Prune;
80661     }
80662     case TK_AGG_FUNCTION: {
80663       if( (pNC->ncFlags & NC_InAggFunc)==0
80664        && pWalker->walkerDepth==pExpr->op2
80665       ){
80666         /* Check to see if pExpr is a duplicate of another aggregate 
80667         ** function that is already in the pAggInfo structure
80668         */
80669         struct AggInfo_func *pItem = pAggInfo->aFunc;
80670         for(i=0; i<pAggInfo->nFunc; i++, pItem++){
80671           if( sqlite3ExprCompare(pItem->pExpr, pExpr, -1)==0 ){
80672             break;
80673           }
80674         }
80675         if( i>=pAggInfo->nFunc ){
80676           /* pExpr is original.  Make a new entry in pAggInfo->aFunc[]
80677           */
80678           u8 enc = ENC(pParse->db);
80679           i = addAggInfoFunc(pParse->db, pAggInfo);
80680           if( i>=0 ){
80681             assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
80682             pItem = &pAggInfo->aFunc[i];
80683             pItem->pExpr = pExpr;
80684             pItem->iMem = ++pParse->nMem;
80685             assert( !ExprHasProperty(pExpr, EP_IntValue) );
80686             pItem->pFunc = sqlite3FindFunction(pParse->db,
80687                    pExpr->u.zToken, sqlite3Strlen30(pExpr->u.zToken),
80688                    pExpr->x.pList ? pExpr->x.pList->nExpr : 0, enc, 0);
80689             if( pExpr->flags & EP_Distinct ){
80690               pItem->iDistinct = pParse->nTab++;
80691             }else{
80692               pItem->iDistinct = -1;
80693             }
80694           }
80695         }
80696         /* Make pExpr point to the appropriate pAggInfo->aFunc[] entry
80697         */
80698         assert( !ExprHasProperty(pExpr, EP_TokenOnly|EP_Reduced) );
80699         ExprSetVVAProperty(pExpr, EP_NoReduce);
80700         pExpr->iAgg = (i16)i;
80701         pExpr->pAggInfo = pAggInfo;
80702         return WRC_Prune;
80703       }else{
80704         return WRC_Continue;
80705       }
80706     }
80707   }
80708   return WRC_Continue;
80709 }
80710 static int analyzeAggregatesInSelect(Walker *pWalker, Select *pSelect){
80711   UNUSED_PARAMETER(pWalker);
80712   UNUSED_PARAMETER(pSelect);
80713   return WRC_Continue;
80714 }
80715 
80716 /*
80717 ** Analyze the pExpr expression looking for aggregate functions and
80718 ** for variables that need to be added to AggInfo object that pNC->pAggInfo
80719 ** points to.  Additional entries are made on the AggInfo object as
80720 ** necessary.
80721 **
80722 ** This routine should only be called after the expression has been
80723 ** analyzed by sqlite3ResolveExprNames().
80724 */
80725 SQLITE_PRIVATE void sqlite3ExprAnalyzeAggregates(NameContext *pNC, Expr *pExpr){
80726   Walker w;
80727   memset(&w, 0, sizeof(w));
80728   w.xExprCallback = analyzeAggregate;
80729   w.xSelectCallback = analyzeAggregatesInSelect;
80730   w.u.pNC = pNC;
80731   assert( pNC->pSrcList!=0 );
80732   sqlite3WalkExpr(&w, pExpr);
80733 }
80734 
80735 /*
80736 ** Call sqlite3ExprAnalyzeAggregates() for every expression in an
80737 ** expression list.  Return the number of errors.
80738 **
80739 ** If an error is found, the analysis is cut short.
80740 */
80741 SQLITE_PRIVATE void sqlite3ExprAnalyzeAggList(NameContext *pNC, ExprList *pList){
80742   struct ExprList_item *pItem;
80743   int i;
80744   if( pList ){
80745     for(pItem=pList->a, i=0; i<pList->nExpr; i++, pItem++){
80746       sqlite3ExprAnalyzeAggregates(pNC, pItem->pExpr);
80747     }
80748   }
80749 }
80750 
80751 /*
80752 ** Allocate a single new register for use to hold some intermediate result.
80753 */
80754 SQLITE_PRIVATE int sqlite3GetTempReg(Parse *pParse){
80755   if( pParse->nTempReg==0 ){
80756     return ++pParse->nMem;
80757   }
80758   return pParse->aTempReg[--pParse->nTempReg];
80759 }
80760 
80761 /*
80762 ** Deallocate a register, making available for reuse for some other
80763 ** purpose.
80764 **
80765 ** If a register is currently being used by the column cache, then
80766 ** the dallocation is deferred until the column cache line that uses
80767 ** the register becomes stale.
80768 */
80769 SQLITE_PRIVATE void sqlite3ReleaseTempReg(Parse *pParse, int iReg){
80770   if( iReg && pParse->nTempReg<ArraySize(pParse->aTempReg) ){
80771     int i;
80772     struct yColCache *p;
80773     for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
80774       if( p->iReg==iReg ){
80775         p->tempReg = 1;
80776         return;
80777       }
80778     }
80779     pParse->aTempReg[pParse->nTempReg++] = iReg;
80780   }
80781 }
80782 
80783 /*
80784 ** Allocate or deallocate a block of nReg consecutive registers
80785 */
80786 SQLITE_PRIVATE int sqlite3GetTempRange(Parse *pParse, int nReg){
80787   int i, n;
80788   i = pParse->iRangeReg;
80789   n = pParse->nRangeReg;
80790   if( nReg<=n ){
80791     assert( !usedAsColumnCache(pParse, i, i+n-1) );
80792     pParse->iRangeReg += nReg;
80793     pParse->nRangeReg -= nReg;
80794   }else{
80795     i = pParse->nMem+1;
80796     pParse->nMem += nReg;
80797   }
80798   return i;
80799 }
80800 SQLITE_PRIVATE void sqlite3ReleaseTempRange(Parse *pParse, int iReg, int nReg){
80801   sqlite3ExprCacheRemove(pParse, iReg, nReg);
80802   if( nReg>pParse->nRangeReg ){
80803     pParse->nRangeReg = nReg;
80804     pParse->iRangeReg = iReg;
80805   }
80806 }
80807 
80808 /*
80809 ** Mark all temporary registers as being unavailable for reuse.
80810 */
80811 SQLITE_PRIVATE void sqlite3ClearTempRegCache(Parse *pParse){
80812   pParse->nTempReg = 0;
80813   pParse->nRangeReg = 0;
80814 }
80815 
80816 /************** End of expr.c ************************************************/
80817 /************** Begin file alter.c *******************************************/
80818 /*
80819 ** 2005 February 15
80820 **
80821 ** The author disclaims copyright to this source code.  In place of
80822 ** a legal notice, here is a blessing:
80823 **
80824 **    May you do good and not evil.
80825 **    May you find forgiveness for yourself and forgive others.
80826 **    May you share freely, never taking more than you give.
80827 **
80828 *************************************************************************
80829 ** This file contains C code routines that used to generate VDBE code
80830 ** that implements the ALTER TABLE command.
80831 */
80832 
80833 /*
80834 ** The code in this file only exists if we are not omitting the
80835 ** ALTER TABLE logic from the build.
80836 */
80837 #ifndef SQLITE_OMIT_ALTERTABLE
80838 
80839 
80840 /*
80841 ** This function is used by SQL generated to implement the 
80842 ** ALTER TABLE command. The first argument is the text of a CREATE TABLE or
80843 ** CREATE INDEX command. The second is a table name. The table name in 
80844 ** the CREATE TABLE or CREATE INDEX statement is replaced with the third
80845 ** argument and the result returned. Examples:
80846 **
80847 ** sqlite_rename_table('CREATE TABLE abc(a, b, c)', 'def')
80848 **     -> 'CREATE TABLE def(a, b, c)'
80849 **
80850 ** sqlite_rename_table('CREATE INDEX i ON abc(a)', 'def')
80851 **     -> 'CREATE INDEX i ON def(a, b, c)'
80852 */
80853 static void renameTableFunc(
80854   sqlite3_context *context,
80855   int NotUsed,
80856   sqlite3_value **argv
80857 ){
80858   unsigned char const *zSql = sqlite3_value_text(argv[0]);
80859   unsigned char const *zTableName = sqlite3_value_text(argv[1]);
80860 
80861   int token;
80862   Token tname;
80863   unsigned char const *zCsr = zSql;
80864   int len = 0;
80865   char *zRet;
80866 
80867   sqlite3 *db = sqlite3_context_db_handle(context);
80868 
80869   UNUSED_PARAMETER(NotUsed);
80870 
80871   /* The principle used to locate the table name in the CREATE TABLE 
80872   ** statement is that the table name is the first non-space token that
80873   ** is immediately followed by a TK_LP or TK_USING token.
80874   */
80875   if( zSql ){
80876     do {
80877       if( !*zCsr ){
80878         /* Ran out of input before finding an opening bracket. Return NULL. */
80879         return;
80880       }
80881 
80882       /* Store the token that zCsr points to in tname. */
80883       tname.z = (char*)zCsr;
80884       tname.n = len;
80885 
80886       /* Advance zCsr to the next token. Store that token type in 'token',
80887       ** and its length in 'len' (to be used next iteration of this loop).
80888       */
80889       do {
80890         zCsr += len;
80891         len = sqlite3GetToken(zCsr, &token);
80892       } while( token==TK_SPACE );
80893       assert( len>0 );
80894     } while( token!=TK_LP && token!=TK_USING );
80895 
80896     zRet = sqlite3MPrintf(db, "%.*s\"%w\"%s", ((u8*)tname.z) - zSql, zSql, 
80897        zTableName, tname.z+tname.n);
80898     sqlite3_result_text(context, zRet, -1, SQLITE_DYNAMIC);
80899   }
80900 }
80901 
80902 /*
80903 ** This C function implements an SQL user function that is used by SQL code
80904 ** generated by the ALTER TABLE ... RENAME command to modify the definition
80905 ** of any foreign key constraints that use the table being renamed as the 
80906 ** parent table. It is passed three arguments:
80907 **
80908 **   1) The complete text of the CREATE TABLE statement being modified,
80909 **   2) The old name of the table being renamed, and
80910 **   3) The new name of the table being renamed.
80911 **
80912 ** It returns the new CREATE TABLE statement. For example:
80913 **
80914 **   sqlite_rename_parent('CREATE TABLE t1(a REFERENCES t2)', 't2', 't3')
80915 **       -> 'CREATE TABLE t1(a REFERENCES t3)'
80916 */
80917 #ifndef SQLITE_OMIT_FOREIGN_KEY
80918 static void renameParentFunc(
80919   sqlite3_context *context,
80920   int NotUsed,
80921   sqlite3_value **argv
80922 ){
80923   sqlite3 *db = sqlite3_context_db_handle(context);
80924   char *zOutput = 0;
80925   char *zResult;
80926   unsigned char const *zInput = sqlite3_value_text(argv[0]);
80927   unsigned char const *zOld = sqlite3_value_text(argv[1]);
80928   unsigned char const *zNew = sqlite3_value_text(argv[2]);
80929 
80930   unsigned const char *z;         /* Pointer to token */
80931   int n;                          /* Length of token z */
80932   int token;                      /* Type of token */
80933 
80934   UNUSED_PARAMETER(NotUsed);
80935   for(z=zInput; *z; z=z+n){
80936     n = sqlite3GetToken(z, &token);
80937     if( token==TK_REFERENCES ){
80938       char *zParent;
80939       do {
80940         z += n;
80941         n = sqlite3GetToken(z, &token);
80942       }while( token==TK_SPACE );
80943 
80944       zParent = sqlite3DbStrNDup(db, (const char *)z, n);
80945       if( zParent==0 ) break;
80946       sqlite3Dequote(zParent);
80947       if( 0==sqlite3StrICmp((const char *)zOld, zParent) ){
80948         char *zOut = sqlite3MPrintf(db, "%s%.*s\"%w\"", 
80949             (zOutput?zOutput:""), z-zInput, zInput, (const char *)zNew
80950         );
80951         sqlite3DbFree(db, zOutput);
80952         zOutput = zOut;
80953         zInput = &z[n];
80954       }
80955       sqlite3DbFree(db, zParent);
80956     }
80957   }
80958 
80959   zResult = sqlite3MPrintf(db, "%s%s", (zOutput?zOutput:""), zInput), 
80960   sqlite3_result_text(context, zResult, -1, SQLITE_DYNAMIC);
80961   sqlite3DbFree(db, zOutput);
80962 }
80963 #endif
80964 
80965 #ifndef SQLITE_OMIT_TRIGGER
80966 /* This function is used by SQL generated to implement the
80967 ** ALTER TABLE command. The first argument is the text of a CREATE TRIGGER 
80968 ** statement. The second is a table name. The table name in the CREATE 
80969 ** TRIGGER statement is replaced with the third argument and the result 
80970 ** returned. This is analagous to renameTableFunc() above, except for CREATE
80971 ** TRIGGER, not CREATE INDEX and CREATE TABLE.
80972 */
80973 static void renameTriggerFunc(
80974   sqlite3_context *context,
80975   int NotUsed,
80976   sqlite3_value **argv
80977 ){
80978   unsigned char const *zSql = sqlite3_value_text(argv[0]);
80979   unsigned char const *zTableName = sqlite3_value_text(argv[1]);
80980 
80981   int token;
80982   Token tname;
80983   int dist = 3;
80984   unsigned char const *zCsr = zSql;
80985   int len = 0;
80986   char *zRet;
80987   sqlite3 *db = sqlite3_context_db_handle(context);
80988 
80989   UNUSED_PARAMETER(NotUsed);
80990 
80991   /* The principle used to locate the table name in the CREATE TRIGGER 
80992   ** statement is that the table name is the first token that is immediatedly
80993   ** preceded by either TK_ON or TK_DOT and immediatedly followed by one
80994   ** of TK_WHEN, TK_BEGIN or TK_FOR.
80995   */
80996   if( zSql ){
80997     do {
80998 
80999       if( !*zCsr ){
81000         /* Ran out of input before finding the table name. Return NULL. */
81001         return;
81002       }
81003 
81004       /* Store the token that zCsr points to in tname. */
81005       tname.z = (char*)zCsr;
81006       tname.n = len;
81007 
81008       /* Advance zCsr to the next token. Store that token type in 'token',
81009       ** and its length in 'len' (to be used next iteration of this loop).
81010       */
81011       do {
81012         zCsr += len;
81013         len = sqlite3GetToken(zCsr, &token);
81014       }while( token==TK_SPACE );
81015       assert( len>0 );
81016 
81017       /* Variable 'dist' stores the number of tokens read since the most
81018       ** recent TK_DOT or TK_ON. This means that when a WHEN, FOR or BEGIN 
81019       ** token is read and 'dist' equals 2, the condition stated above
81020       ** to be met.
81021       **
81022       ** Note that ON cannot be a database, table or column name, so
81023       ** there is no need to worry about syntax like 
81024       ** "CREATE TRIGGER ... ON ON.ON BEGIN ..." etc.
81025       */
81026       dist++;
81027       if( token==TK_DOT || token==TK_ON ){
81028         dist = 0;
81029       }
81030     } while( dist!=2 || (token!=TK_WHEN && token!=TK_FOR && token!=TK_BEGIN) );
81031 
81032     /* Variable tname now contains the token that is the old table-name
81033     ** in the CREATE TRIGGER statement.
81034     */
81035     zRet = sqlite3MPrintf(db, "%.*s\"%w\"%s", ((u8*)tname.z) - zSql, zSql, 
81036        zTableName, tname.z+tname.n);
81037     sqlite3_result_text(context, zRet, -1, SQLITE_DYNAMIC);
81038   }
81039 }
81040 #endif   /* !SQLITE_OMIT_TRIGGER */
81041 
81042 /*
81043 ** Register built-in functions used to help implement ALTER TABLE
81044 */
81045 SQLITE_PRIVATE void sqlite3AlterFunctions(void){
81046   static SQLITE_WSD FuncDef aAlterTableFuncs[] = {
81047     FUNCTION(sqlite_rename_table,   2, 0, 0, renameTableFunc),
81048 #ifndef SQLITE_OMIT_TRIGGER
81049     FUNCTION(sqlite_rename_trigger, 2, 0, 0, renameTriggerFunc),
81050 #endif
81051 #ifndef SQLITE_OMIT_FOREIGN_KEY
81052     FUNCTION(sqlite_rename_parent,  3, 0, 0, renameParentFunc),
81053 #endif
81054   };
81055   int i;
81056   FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
81057   FuncDef *aFunc = (FuncDef*)&GLOBAL(FuncDef, aAlterTableFuncs);
81058 
81059   for(i=0; i<ArraySize(aAlterTableFuncs); i++){
81060     sqlite3FuncDefInsert(pHash, &aFunc[i]);
81061   }
81062 }
81063 
81064 /*
81065 ** This function is used to create the text of expressions of the form:
81066 **
81067 **   name=<constant1> OR name=<constant2> OR ...
81068 **
81069 ** If argument zWhere is NULL, then a pointer string containing the text 
81070 ** "name=<constant>" is returned, where <constant> is the quoted version
81071 ** of the string passed as argument zConstant. The returned buffer is
81072 ** allocated using sqlite3DbMalloc(). It is the responsibility of the
81073 ** caller to ensure that it is eventually freed.
81074 **
81075 ** If argument zWhere is not NULL, then the string returned is 
81076 ** "<where> OR name=<constant>", where <where> is the contents of zWhere.
81077 ** In this case zWhere is passed to sqlite3DbFree() before returning.
81078 ** 
81079 */
81080 static char *whereOrName(sqlite3 *db, char *zWhere, char *zConstant){
81081   char *zNew;
81082   if( !zWhere ){
81083     zNew = sqlite3MPrintf(db, "name=%Q", zConstant);
81084   }else{
81085     zNew = sqlite3MPrintf(db, "%s OR name=%Q", zWhere, zConstant);
81086     sqlite3DbFree(db, zWhere);
81087   }
81088   return zNew;
81089 }
81090 
81091 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
81092 /*
81093 ** Generate the text of a WHERE expression which can be used to select all
81094 ** tables that have foreign key constraints that refer to table pTab (i.e.
81095 ** constraints for which pTab is the parent table) from the sqlite_master
81096 ** table.
81097 */
81098 static char *whereForeignKeys(Parse *pParse, Table *pTab){
81099   FKey *p;
81100   char *zWhere = 0;
81101   for(p=sqlite3FkReferences(pTab); p; p=p->pNextTo){
81102     zWhere = whereOrName(pParse->db, zWhere, p->pFrom->zName);
81103   }
81104   return zWhere;
81105 }
81106 #endif
81107 
81108 /*
81109 ** Generate the text of a WHERE expression which can be used to select all
81110 ** temporary triggers on table pTab from the sqlite_temp_master table. If
81111 ** table pTab has no temporary triggers, or is itself stored in the 
81112 ** temporary database, NULL is returned.
81113 */
81114 static char *whereTempTriggers(Parse *pParse, Table *pTab){
81115   Trigger *pTrig;
81116   char *zWhere = 0;
81117   const Schema *pTempSchema = pParse->db->aDb[1].pSchema; /* Temp db schema */
81118 
81119   /* If the table is not located in the temp-db (in which case NULL is 
81120   ** returned, loop through the tables list of triggers. For each trigger
81121   ** that is not part of the temp-db schema, add a clause to the WHERE 
81122   ** expression being built up in zWhere.
81123   */
81124   if( pTab->pSchema!=pTempSchema ){
81125     sqlite3 *db = pParse->db;
81126     for(pTrig=sqlite3TriggerList(pParse, pTab); pTrig; pTrig=pTrig->pNext){
81127       if( pTrig->pSchema==pTempSchema ){
81128         zWhere = whereOrName(db, zWhere, pTrig->zName);
81129       }
81130     }
81131   }
81132   if( zWhere ){
81133     char *zNew = sqlite3MPrintf(pParse->db, "type='trigger' AND (%s)", zWhere);
81134     sqlite3DbFree(pParse->db, zWhere);
81135     zWhere = zNew;
81136   }
81137   return zWhere;
81138 }
81139 
81140 /*
81141 ** Generate code to drop and reload the internal representation of table
81142 ** pTab from the database, including triggers and temporary triggers.
81143 ** Argument zName is the name of the table in the database schema at
81144 ** the time the generated code is executed. This can be different from
81145 ** pTab->zName if this function is being called to code part of an 
81146 ** "ALTER TABLE RENAME TO" statement.
81147 */
81148 static void reloadTableSchema(Parse *pParse, Table *pTab, const char *zName){
81149   Vdbe *v;
81150   char *zWhere;
81151   int iDb;                   /* Index of database containing pTab */
81152 #ifndef SQLITE_OMIT_TRIGGER
81153   Trigger *pTrig;
81154 #endif
81155 
81156   v = sqlite3GetVdbe(pParse);
81157   if( NEVER(v==0) ) return;
81158   assert( sqlite3BtreeHoldsAllMutexes(pParse->db) );
81159   iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
81160   assert( iDb>=0 );
81161 
81162 #ifndef SQLITE_OMIT_TRIGGER
81163   /* Drop any table triggers from the internal schema. */
81164   for(pTrig=sqlite3TriggerList(pParse, pTab); pTrig; pTrig=pTrig->pNext){
81165     int iTrigDb = sqlite3SchemaToIndex(pParse->db, pTrig->pSchema);
81166     assert( iTrigDb==iDb || iTrigDb==1 );
81167     sqlite3VdbeAddOp4(v, OP_DropTrigger, iTrigDb, 0, 0, pTrig->zName, 0);
81168   }
81169 #endif
81170 
81171   /* Drop the table and index from the internal schema.  */
81172   sqlite3VdbeAddOp4(v, OP_DropTable, iDb, 0, 0, pTab->zName, 0);
81173 
81174   /* Reload the table, index and permanent trigger schemas. */
81175   zWhere = sqlite3MPrintf(pParse->db, "tbl_name=%Q", zName);
81176   if( !zWhere ) return;
81177   sqlite3VdbeAddParseSchemaOp(v, iDb, zWhere);
81178 
81179 #ifndef SQLITE_OMIT_TRIGGER
81180   /* Now, if the table is not stored in the temp database, reload any temp 
81181   ** triggers. Don't use IN(...) in case SQLITE_OMIT_SUBQUERY is defined. 
81182   */
81183   if( (zWhere=whereTempTriggers(pParse, pTab))!=0 ){
81184     sqlite3VdbeAddParseSchemaOp(v, 1, zWhere);
81185   }
81186 #endif
81187 }
81188 
81189 /*
81190 ** Parameter zName is the name of a table that is about to be altered
81191 ** (either with ALTER TABLE ... RENAME TO or ALTER TABLE ... ADD COLUMN).
81192 ** If the table is a system table, this function leaves an error message
81193 ** in pParse->zErr (system tables may not be altered) and returns non-zero.
81194 **
81195 ** Or, if zName is not a system table, zero is returned.
81196 */
81197 static int isSystemTable(Parse *pParse, const char *zName){
81198   if( sqlite3Strlen30(zName)>6 && 0==sqlite3StrNICmp(zName, "sqlite_", 7) ){
81199     sqlite3ErrorMsg(pParse, "table %s may not be altered", zName);
81200     return 1;
81201   }
81202   return 0;
81203 }
81204 
81205 /*
81206 ** Generate code to implement the "ALTER TABLE xxx RENAME TO yyy" 
81207 ** command. 
81208 */
81209 SQLITE_PRIVATE void sqlite3AlterRenameTable(
81210   Parse *pParse,            /* Parser context. */
81211   SrcList *pSrc,            /* The table to rename. */
81212   Token *pName              /* The new table name. */
81213 ){
81214   int iDb;                  /* Database that contains the table */
81215   char *zDb;                /* Name of database iDb */
81216   Table *pTab;              /* Table being renamed */
81217   char *zName = 0;          /* NULL-terminated version of pName */ 
81218   sqlite3 *db = pParse->db; /* Database connection */
81219   int nTabName;             /* Number of UTF-8 characters in zTabName */
81220   const char *zTabName;     /* Original name of the table */
81221   Vdbe *v;
81222 #ifndef SQLITE_OMIT_TRIGGER
81223   char *zWhere = 0;         /* Where clause to locate temp triggers */
81224 #endif
81225   VTable *pVTab = 0;        /* Non-zero if this is a v-tab with an xRename() */
81226   int savedDbFlags;         /* Saved value of db->flags */
81227 
81228   savedDbFlags = db->flags;  
81229   if( NEVER(db->mallocFailed) ) goto exit_rename_table;
81230   assert( pSrc->nSrc==1 );
81231   assert( sqlite3BtreeHoldsAllMutexes(pParse->db) );
81232 
81233   pTab = sqlite3LocateTableItem(pParse, 0, &pSrc->a[0]);
81234   if( !pTab ) goto exit_rename_table;
81235   iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
81236   zDb = db->aDb[iDb].zName;
81237   db->flags |= SQLITE_PreferBuiltin;
81238 
81239   /* Get a NULL terminated version of the new table name. */
81240   zName = sqlite3NameFromToken(db, pName);
81241   if( !zName ) goto exit_rename_table;
81242 
81243   /* Check that a table or index named 'zName' does not already exist
81244   ** in database iDb. If so, this is an error.
81245   */
81246   if( sqlite3FindTable(db, zName, zDb) || sqlite3FindIndex(db, zName, zDb) ){
81247     sqlite3ErrorMsg(pParse, 
81248         "there is already another table or index with this name: %s", zName);
81249     goto exit_rename_table;
81250   }
81251 
81252   /* Make sure it is not a system table being altered, or a reserved name
81253   ** that the table is being renamed to.
81254   */
81255   if( SQLITE_OK!=isSystemTable(pParse, pTab->zName) ){
81256     goto exit_rename_table;
81257   }
81258   if( SQLITE_OK!=sqlite3CheckObjectName(pParse, zName) ){ goto
81259     exit_rename_table;
81260   }
81261 
81262 #ifndef SQLITE_OMIT_VIEW
81263   if( pTab->pSelect ){
81264     sqlite3ErrorMsg(pParse, "view %s may not be altered", pTab->zName);
81265     goto exit_rename_table;
81266   }
81267 #endif
81268 
81269 #ifndef SQLITE_OMIT_AUTHORIZATION
81270   /* Invoke the authorization callback. */
81271   if( sqlite3AuthCheck(pParse, SQLITE_ALTER_TABLE, zDb, pTab->zName, 0) ){
81272     goto exit_rename_table;
81273   }
81274 #endif
81275 
81276 #ifndef SQLITE_OMIT_VIRTUALTABLE
81277   if( sqlite3ViewGetColumnNames(pParse, pTab) ){
81278     goto exit_rename_table;
81279   }
81280   if( IsVirtual(pTab) ){
81281     pVTab = sqlite3GetVTable(db, pTab);
81282     if( pVTab->pVtab->pModule->xRename==0 ){
81283       pVTab = 0;
81284     }
81285   }
81286 #endif
81287 
81288   /* Begin a transaction and code the VerifyCookie for database iDb. 
81289   ** Then modify the schema cookie (since the ALTER TABLE modifies the
81290   ** schema). Open a statement transaction if the table is a virtual
81291   ** table.
81292   */
81293   v = sqlite3GetVdbe(pParse);
81294   if( v==0 ){
81295     goto exit_rename_table;
81296   }
81297   sqlite3BeginWriteOperation(pParse, pVTab!=0, iDb);
81298   sqlite3ChangeCookie(pParse, iDb);
81299 
81300   /* If this is a virtual table, invoke the xRename() function if
81301   ** one is defined. The xRename() callback will modify the names
81302   ** of any resources used by the v-table implementation (including other
81303   ** SQLite tables) that are identified by the name of the virtual table.
81304   */
81305 #ifndef SQLITE_OMIT_VIRTUALTABLE
81306   if( pVTab ){
81307     int i = ++pParse->nMem;
81308     sqlite3VdbeAddOp4(v, OP_String8, 0, i, 0, zName, 0);
81309     sqlite3VdbeAddOp4(v, OP_VRename, i, 0, 0,(const char*)pVTab, P4_VTAB);
81310     sqlite3MayAbort(pParse);
81311   }
81312 #endif
81313 
81314   /* figure out how many UTF-8 characters are in zName */
81315   zTabName = pTab->zName;
81316   nTabName = sqlite3Utf8CharLen(zTabName, -1);
81317 
81318 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
81319   if( db->flags&SQLITE_ForeignKeys ){
81320     /* If foreign-key support is enabled, rewrite the CREATE TABLE 
81321     ** statements corresponding to all child tables of foreign key constraints
81322     ** for which the renamed table is the parent table.  */
81323     if( (zWhere=whereForeignKeys(pParse, pTab))!=0 ){
81324       sqlite3NestedParse(pParse, 
81325           "UPDATE \"%w\".%s SET "
81326               "sql = sqlite_rename_parent(sql, %Q, %Q) "
81327               "WHERE %s;", zDb, SCHEMA_TABLE(iDb), zTabName, zName, zWhere);
81328       sqlite3DbFree(db, zWhere);
81329     }
81330   }
81331 #endif
81332 
81333   /* Modify the sqlite_master table to use the new table name. */
81334   sqlite3NestedParse(pParse,
81335       "UPDATE %Q.%s SET "
81336 #ifdef SQLITE_OMIT_TRIGGER
81337           "sql = sqlite_rename_table(sql, %Q), "
81338 #else
81339           "sql = CASE "
81340             "WHEN type = 'trigger' THEN sqlite_rename_trigger(sql, %Q)"
81341             "ELSE sqlite_rename_table(sql, %Q) END, "
81342 #endif
81343           "tbl_name = %Q, "
81344           "name = CASE "
81345             "WHEN type='table' THEN %Q "
81346             "WHEN name LIKE 'sqlite_autoindex%%' AND type='index' THEN "
81347              "'sqlite_autoindex_' || %Q || substr(name,%d+18) "
81348             "ELSE name END "
81349       "WHERE tbl_name=%Q COLLATE nocase AND "
81350           "(type='table' OR type='index' OR type='trigger');", 
81351       zDb, SCHEMA_TABLE(iDb), zName, zName, zName, 
81352 #ifndef SQLITE_OMIT_TRIGGER
81353       zName,
81354 #endif
81355       zName, nTabName, zTabName
81356   );
81357 
81358 #ifndef SQLITE_OMIT_AUTOINCREMENT
81359   /* If the sqlite_sequence table exists in this database, then update 
81360   ** it with the new table name.
81361   */
81362   if( sqlite3FindTable(db, "sqlite_sequence", zDb) ){
81363     sqlite3NestedParse(pParse,
81364         "UPDATE \"%w\".sqlite_sequence set name = %Q WHERE name = %Q",
81365         zDb, zName, pTab->zName);
81366   }
81367 #endif
81368 
81369 #ifndef SQLITE_OMIT_TRIGGER
81370   /* If there are TEMP triggers on this table, modify the sqlite_temp_master
81371   ** table. Don't do this if the table being ALTERed is itself located in
81372   ** the temp database.
81373   */
81374   if( (zWhere=whereTempTriggers(pParse, pTab))!=0 ){
81375     sqlite3NestedParse(pParse, 
81376         "UPDATE sqlite_temp_master SET "
81377             "sql = sqlite_rename_trigger(sql, %Q), "
81378             "tbl_name = %Q "
81379             "WHERE %s;", zName, zName, zWhere);
81380     sqlite3DbFree(db, zWhere);
81381   }
81382 #endif
81383 
81384 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
81385   if( db->flags&SQLITE_ForeignKeys ){
81386     FKey *p;
81387     for(p=sqlite3FkReferences(pTab); p; p=p->pNextTo){
81388       Table *pFrom = p->pFrom;
81389       if( pFrom!=pTab ){
81390         reloadTableSchema(pParse, p->pFrom, pFrom->zName);
81391       }
81392     }
81393   }
81394 #endif
81395 
81396   /* Drop and reload the internal table schema. */
81397   reloadTableSchema(pParse, pTab, zName);
81398 
81399 exit_rename_table:
81400   sqlite3SrcListDelete(db, pSrc);
81401   sqlite3DbFree(db, zName);
81402   db->flags = savedDbFlags;
81403 }
81404 
81405 
81406 /*
81407 ** Generate code to make sure the file format number is at least minFormat.
81408 ** The generated code will increase the file format number if necessary.
81409 */
81410 SQLITE_PRIVATE void sqlite3MinimumFileFormat(Parse *pParse, int iDb, int minFormat){
81411   Vdbe *v;
81412   v = sqlite3GetVdbe(pParse);
81413   /* The VDBE should have been allocated before this routine is called.
81414   ** If that allocation failed, we would have quit before reaching this
81415   ** point */
81416   if( ALWAYS(v) ){
81417     int r1 = sqlite3GetTempReg(pParse);
81418     int r2 = sqlite3GetTempReg(pParse);
81419     int j1;
81420     sqlite3VdbeAddOp3(v, OP_ReadCookie, iDb, r1, BTREE_FILE_FORMAT);
81421     sqlite3VdbeUsesBtree(v, iDb);
81422     sqlite3VdbeAddOp2(v, OP_Integer, minFormat, r2);
81423     j1 = sqlite3VdbeAddOp3(v, OP_Ge, r2, 0, r1);
81424     sqlite3VdbeAddOp3(v, OP_SetCookie, iDb, BTREE_FILE_FORMAT, r2);
81425     sqlite3VdbeJumpHere(v, j1);
81426     sqlite3ReleaseTempReg(pParse, r1);
81427     sqlite3ReleaseTempReg(pParse, r2);
81428   }
81429 }
81430 
81431 /*
81432 ** This function is called after an "ALTER TABLE ... ADD" statement
81433 ** has been parsed. Argument pColDef contains the text of the new
81434 ** column definition.
81435 **
81436 ** The Table structure pParse->pNewTable was extended to include
81437 ** the new column during parsing.
81438 */
81439 SQLITE_PRIVATE void sqlite3AlterFinishAddColumn(Parse *pParse, Token *pColDef){
81440   Table *pNew;              /* Copy of pParse->pNewTable */
81441   Table *pTab;              /* Table being altered */
81442   int iDb;                  /* Database number */
81443   const char *zDb;          /* Database name */
81444   const char *zTab;         /* Table name */
81445   char *zCol;               /* Null-terminated column definition */
81446   Column *pCol;             /* The new column */
81447   Expr *pDflt;              /* Default value for the new column */
81448   sqlite3 *db;              /* The database connection; */
81449 
81450   db = pParse->db;
81451   if( pParse->nErr || db->mallocFailed ) return;
81452   pNew = pParse->pNewTable;
81453   assert( pNew );
81454 
81455   assert( sqlite3BtreeHoldsAllMutexes(db) );
81456   iDb = sqlite3SchemaToIndex(db, pNew->pSchema);
81457   zDb = db->aDb[iDb].zName;
81458   zTab = &pNew->zName[16];  /* Skip the "sqlite_altertab_" prefix on the name */
81459   pCol = &pNew->aCol[pNew->nCol-1];
81460   pDflt = pCol->pDflt;
81461   pTab = sqlite3FindTable(db, zTab, zDb);
81462   assert( pTab );
81463 
81464 #ifndef SQLITE_OMIT_AUTHORIZATION
81465   /* Invoke the authorization callback. */
81466   if( sqlite3AuthCheck(pParse, SQLITE_ALTER_TABLE, zDb, pTab->zName, 0) ){
81467     return;
81468   }
81469 #endif
81470 
81471   /* If the default value for the new column was specified with a 
81472   ** literal NULL, then set pDflt to 0. This simplifies checking
81473   ** for an SQL NULL default below.
81474   */
81475   if( pDflt && pDflt->op==TK_NULL ){
81476     pDflt = 0;
81477   }
81478 
81479   /* Check that the new column is not specified as PRIMARY KEY or UNIQUE.
81480   ** If there is a NOT NULL constraint, then the default value for the
81481   ** column must not be NULL.
81482   */
81483   if( pCol->colFlags & COLFLAG_PRIMKEY ){
81484     sqlite3ErrorMsg(pParse, "Cannot add a PRIMARY KEY column");
81485     return;
81486   }
81487   if( pNew->pIndex ){
81488     sqlite3ErrorMsg(pParse, "Cannot add a UNIQUE column");
81489     return;
81490   }
81491   if( (db->flags&SQLITE_ForeignKeys) && pNew->pFKey && pDflt ){
81492     sqlite3ErrorMsg(pParse, 
81493         "Cannot add a REFERENCES column with non-NULL default value");
81494     return;
81495   }
81496   if( pCol->notNull && !pDflt ){
81497     sqlite3ErrorMsg(pParse, 
81498         "Cannot add a NOT NULL column with default value NULL");
81499     return;
81500   }
81501 
81502   /* Ensure the default expression is something that sqlite3ValueFromExpr()
81503   ** can handle (i.e. not CURRENT_TIME etc.)
81504   */
81505   if( pDflt ){
81506     sqlite3_value *pVal = 0;
81507     if( sqlite3ValueFromExpr(db, pDflt, SQLITE_UTF8, SQLITE_AFF_NONE, &pVal) ){
81508       db->mallocFailed = 1;
81509       return;
81510     }
81511     if( !pVal ){
81512       sqlite3ErrorMsg(pParse, "Cannot add a column with non-constant default");
81513       return;
81514     }
81515     sqlite3ValueFree(pVal);
81516   }
81517 
81518   /* Modify the CREATE TABLE statement. */
81519   zCol = sqlite3DbStrNDup(db, (char*)pColDef->z, pColDef->n);
81520   if( zCol ){
81521     char *zEnd = &zCol[pColDef->n-1];
81522     int savedDbFlags = db->flags;
81523     while( zEnd>zCol && (*zEnd==';' || sqlite3Isspace(*zEnd)) ){
81524       *zEnd-- = '\0';
81525     }
81526     db->flags |= SQLITE_PreferBuiltin;
81527     sqlite3NestedParse(pParse, 
81528         "UPDATE \"%w\".%s SET "
81529           "sql = substr(sql,1,%d) || ', ' || %Q || substr(sql,%d) "
81530         "WHERE type = 'table' AND name = %Q", 
81531       zDb, SCHEMA_TABLE(iDb), pNew->addColOffset, zCol, pNew->addColOffset+1,
81532       zTab
81533     );
81534     sqlite3DbFree(db, zCol);
81535     db->flags = savedDbFlags;
81536   }
81537 
81538   /* If the default value of the new column is NULL, then set the file
81539   ** format to 2. If the default value of the new column is not NULL,
81540   ** the file format becomes 3.
81541   */
81542   sqlite3MinimumFileFormat(pParse, iDb, pDflt ? 3 : 2);
81543 
81544   /* Reload the schema of the modified table. */
81545   reloadTableSchema(pParse, pTab, pTab->zName);
81546 }
81547 
81548 /*
81549 ** This function is called by the parser after the table-name in
81550 ** an "ALTER TABLE <table-name> ADD" statement is parsed. Argument 
81551 ** pSrc is the full-name of the table being altered.
81552 **
81553 ** This routine makes a (partial) copy of the Table structure
81554 ** for the table being altered and sets Parse.pNewTable to point
81555 ** to it. Routines called by the parser as the column definition
81556 ** is parsed (i.e. sqlite3AddColumn()) add the new Column data to 
81557 ** the copy. The copy of the Table structure is deleted by tokenize.c 
81558 ** after parsing is finished.
81559 **
81560 ** Routine sqlite3AlterFinishAddColumn() will be called to complete
81561 ** coding the "ALTER TABLE ... ADD" statement.
81562 */
81563 SQLITE_PRIVATE void sqlite3AlterBeginAddColumn(Parse *pParse, SrcList *pSrc){
81564   Table *pNew;
81565   Table *pTab;
81566   Vdbe *v;
81567   int iDb;
81568   int i;
81569   int nAlloc;
81570   sqlite3 *db = pParse->db;
81571 
81572   /* Look up the table being altered. */
81573   assert( pParse->pNewTable==0 );
81574   assert( sqlite3BtreeHoldsAllMutexes(db) );
81575   if( db->mallocFailed ) goto exit_begin_add_column;
81576   pTab = sqlite3LocateTableItem(pParse, 0, &pSrc->a[0]);
81577   if( !pTab ) goto exit_begin_add_column;
81578 
81579 #ifndef SQLITE_OMIT_VIRTUALTABLE
81580   if( IsVirtual(pTab) ){
81581     sqlite3ErrorMsg(pParse, "virtual tables may not be altered");
81582     goto exit_begin_add_column;
81583   }
81584 #endif
81585 
81586   /* Make sure this is not an attempt to ALTER a view. */
81587   if( pTab->pSelect ){
81588     sqlite3ErrorMsg(pParse, "Cannot add a column to a view");
81589     goto exit_begin_add_column;
81590   }
81591   if( SQLITE_OK!=isSystemTable(pParse, pTab->zName) ){
81592     goto exit_begin_add_column;
81593   }
81594 
81595   assert( pTab->addColOffset>0 );
81596   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
81597 
81598   /* Put a copy of the Table struct in Parse.pNewTable for the
81599   ** sqlite3AddColumn() function and friends to modify.  But modify
81600   ** the name by adding an "sqlite_altertab_" prefix.  By adding this
81601   ** prefix, we insure that the name will not collide with an existing
81602   ** table because user table are not allowed to have the "sqlite_"
81603   ** prefix on their name.
81604   */
81605   pNew = (Table*)sqlite3DbMallocZero(db, sizeof(Table));
81606   if( !pNew ) goto exit_begin_add_column;
81607   pParse->pNewTable = pNew;
81608   pNew->nRef = 1;
81609   pNew->nCol = pTab->nCol;
81610   assert( pNew->nCol>0 );
81611   nAlloc = (((pNew->nCol-1)/8)*8)+8;
81612   assert( nAlloc>=pNew->nCol && nAlloc%8==0 && nAlloc-pNew->nCol<8 );
81613   pNew->aCol = (Column*)sqlite3DbMallocZero(db, sizeof(Column)*nAlloc);
81614   pNew->zName = sqlite3MPrintf(db, "sqlite_altertab_%s", pTab->zName);
81615   if( !pNew->aCol || !pNew->zName ){
81616     db->mallocFailed = 1;
81617     goto exit_begin_add_column;
81618   }
81619   memcpy(pNew->aCol, pTab->aCol, sizeof(Column)*pNew->nCol);
81620   for(i=0; i<pNew->nCol; i++){
81621     Column *pCol = &pNew->aCol[i];
81622     pCol->zName = sqlite3DbStrDup(db, pCol->zName);
81623     pCol->zColl = 0;
81624     pCol->zType = 0;
81625     pCol->pDflt = 0;
81626     pCol->zDflt = 0;
81627   }
81628   pNew->pSchema = db->aDb[iDb].pSchema;
81629   pNew->addColOffset = pTab->addColOffset;
81630   pNew->nRef = 1;
81631 
81632   /* Begin a transaction and increment the schema cookie.  */
81633   sqlite3BeginWriteOperation(pParse, 0, iDb);
81634   v = sqlite3GetVdbe(pParse);
81635   if( !v ) goto exit_begin_add_column;
81636   sqlite3ChangeCookie(pParse, iDb);
81637 
81638 exit_begin_add_column:
81639   sqlite3SrcListDelete(db, pSrc);
81640   return;
81641 }
81642 #endif  /* SQLITE_ALTER_TABLE */
81643 
81644 /************** End of alter.c ***********************************************/
81645 /************** Begin file analyze.c *****************************************/
81646 /*
81647 ** 2005-07-08
81648 **
81649 ** The author disclaims copyright to this source code.  In place of
81650 ** a legal notice, here is a blessing:
81651 **
81652 **    May you do good and not evil.
81653 **    May you find forgiveness for yourself and forgive others.
81654 **    May you share freely, never taking more than you give.
81655 **
81656 *************************************************************************
81657 ** This file contains code associated with the ANALYZE command.
81658 **
81659 ** The ANALYZE command gather statistics about the content of tables
81660 ** and indices.  These statistics are made available to the query planner
81661 ** to help it make better decisions about how to perform queries.
81662 **
81663 ** The following system tables are or have been supported:
81664 **
81665 **    CREATE TABLE sqlite_stat1(tbl, idx, stat);
81666 **    CREATE TABLE sqlite_stat2(tbl, idx, sampleno, sample);
81667 **    CREATE TABLE sqlite_stat3(tbl, idx, nEq, nLt, nDLt, sample);
81668 **    CREATE TABLE sqlite_stat4(tbl, idx, nEq, nLt, nDLt, sample);
81669 **
81670 ** Additional tables might be added in future releases of SQLite.
81671 ** The sqlite_stat2 table is not created or used unless the SQLite version
81672 ** is between 3.6.18 and 3.7.8, inclusive, and unless SQLite is compiled
81673 ** with SQLITE_ENABLE_STAT2.  The sqlite_stat2 table is deprecated.
81674 ** The sqlite_stat2 table is superseded by sqlite_stat3, which is only
81675 ** created and used by SQLite versions 3.7.9 and later and with
81676 ** SQLITE_ENABLE_STAT3 defined.  The functionality of sqlite_stat3
81677 ** is a superset of sqlite_stat2.  The sqlite_stat4 is an enhanced
81678 ** version of sqlite_stat3 and is only available when compiled with
81679 ** SQLITE_ENABLE_STAT4 and in SQLite versions 3.8.1 and later.  It is
81680 ** not possible to enable both STAT3 and STAT4 at the same time.  If they
81681 ** are both enabled, then STAT4 takes precedence.
81682 **
81683 ** For most applications, sqlite_stat1 provides all the statisics required
81684 ** for the query planner to make good choices.
81685 **
81686 ** Format of sqlite_stat1:
81687 **
81688 ** There is normally one row per index, with the index identified by the
81689 ** name in the idx column.  The tbl column is the name of the table to
81690 ** which the index belongs.  In each such row, the stat column will be
81691 ** a string consisting of a list of integers.  The first integer in this
81692 ** list is the number of rows in the index.  (This is the same as the
81693 ** number of rows in the table, except for partial indices.)  The second
81694 ** integer is the average number of rows in the index that have the same
81695 ** value in the first column of the index.  The third integer is the average
81696 ** number of rows in the index that have the same value for the first two
81697 ** columns.  The N-th integer (for N>1) is the average number of rows in 
81698 ** the index which have the same value for the first N-1 columns.  For
81699 ** a K-column index, there will be K+1 integers in the stat column.  If
81700 ** the index is unique, then the last integer will be 1.
81701 **
81702 ** The list of integers in the stat column can optionally be followed
81703 ** by the keyword "unordered".  The "unordered" keyword, if it is present,
81704 ** must be separated from the last integer by a single space.  If the
81705 ** "unordered" keyword is present, then the query planner assumes that
81706 ** the index is unordered and will not use the index for a range query.
81707 ** 
81708 ** If the sqlite_stat1.idx column is NULL, then the sqlite_stat1.stat
81709 ** column contains a single integer which is the (estimated) number of
81710 ** rows in the table identified by sqlite_stat1.tbl.
81711 **
81712 ** Format of sqlite_stat2:
81713 **
81714 ** The sqlite_stat2 is only created and is only used if SQLite is compiled
81715 ** with SQLITE_ENABLE_STAT2 and if the SQLite version number is between
81716 ** 3.6.18 and 3.7.8.  The "stat2" table contains additional information
81717 ** about the distribution of keys within an index.  The index is identified by
81718 ** the "idx" column and the "tbl" column is the name of the table to which
81719 ** the index belongs.  There are usually 10 rows in the sqlite_stat2
81720 ** table for each index.
81721 **
81722 ** The sqlite_stat2 entries for an index that have sampleno between 0 and 9
81723 ** inclusive are samples of the left-most key value in the index taken at
81724 ** evenly spaced points along the index.  Let the number of samples be S
81725 ** (10 in the standard build) and let C be the number of rows in the index.
81726 ** Then the sampled rows are given by:
81727 **
81728 **     rownumber = (i*C*2 + C)/(S*2)
81729 **
81730 ** For i between 0 and S-1.  Conceptually, the index space is divided into
81731 ** S uniform buckets and the samples are the middle row from each bucket.
81732 **
81733 ** The format for sqlite_stat2 is recorded here for legacy reference.  This
81734 ** version of SQLite does not support sqlite_stat2.  It neither reads nor
81735 ** writes the sqlite_stat2 table.  This version of SQLite only supports
81736 ** sqlite_stat3.
81737 **
81738 ** Format for sqlite_stat3:
81739 **
81740 ** The sqlite_stat3 format is a subset of sqlite_stat4.  Hence, the
81741 ** sqlite_stat4 format will be described first.  Further information
81742 ** about sqlite_stat3 follows the sqlite_stat4 description.
81743 **
81744 ** Format for sqlite_stat4:
81745 **
81746 ** As with sqlite_stat2, the sqlite_stat4 table contains histogram data
81747 ** to aid the query planner in choosing good indices based on the values
81748 ** that indexed columns are compared against in the WHERE clauses of
81749 ** queries.
81750 **
81751 ** The sqlite_stat4 table contains multiple entries for each index.
81752 ** The idx column names the index and the tbl column is the table of the
81753 ** index.  If the idx and tbl columns are the same, then the sample is
81754 ** of the INTEGER PRIMARY KEY.  The sample column is a blob which is the
81755 ** binary encoding of a key from the index.  The nEq column is a
81756 ** list of integers.  The first integer is the approximate number
81757 ** of entries in the index whose left-most column exactly matches
81758 ** the left-most column of the sample.  The second integer in nEq
81759 ** is the approximate number of entries in the index where the
81760 ** first two columns match the first two columns of the sample.
81761 ** And so forth.  nLt is another list of integers that show the approximate
81762 ** number of entries that are strictly less than the sample.  The first
81763 ** integer in nLt contains the number of entries in the index where the
81764 ** left-most column is less than the left-most column of the sample.
81765 ** The K-th integer in the nLt entry is the number of index entries 
81766 ** where the first K columns are less than the first K columns of the
81767 ** sample.  The nDLt column is like nLt except that it contains the 
81768 ** number of distinct entries in the index that are less than the
81769 ** sample.
81770 **
81771 ** There can be an arbitrary number of sqlite_stat4 entries per index.
81772 ** The ANALYZE command will typically generate sqlite_stat4 tables
81773 ** that contain between 10 and 40 samples which are distributed across
81774 ** the key space, though not uniformly, and which include samples with
81775 ** large nEq values.
81776 **
81777 ** Format for sqlite_stat3 redux:
81778 **
81779 ** The sqlite_stat3 table is like sqlite_stat4 except that it only
81780 ** looks at the left-most column of the index.  The sqlite_stat3.sample
81781 ** column contains the actual value of the left-most column instead
81782 ** of a blob encoding of the complete index key as is found in
81783 ** sqlite_stat4.sample.  The nEq, nLt, and nDLt entries of sqlite_stat3
81784 ** all contain just a single integer which is the same as the first
81785 ** integer in the equivalent columns in sqlite_stat4.
81786 */
81787 #ifndef SQLITE_OMIT_ANALYZE
81788 
81789 #if defined(SQLITE_ENABLE_STAT4)
81790 # define IsStat4     1
81791 # define IsStat3     0
81792 #elif defined(SQLITE_ENABLE_STAT3)
81793 # define IsStat4     0
81794 # define IsStat3     1
81795 #else
81796 # define IsStat4     0
81797 # define IsStat3     0
81798 # undef SQLITE_STAT4_SAMPLES
81799 # define SQLITE_STAT4_SAMPLES 1
81800 #endif
81801 #define IsStat34    (IsStat3+IsStat4)  /* 1 for STAT3 or STAT4. 0 otherwise */
81802 
81803 /*
81804 ** This routine generates code that opens the sqlite_statN tables.
81805 ** The sqlite_stat1 table is always relevant.  sqlite_stat2 is now
81806 ** obsolete.  sqlite_stat3 and sqlite_stat4 are only opened when
81807 ** appropriate compile-time options are provided.
81808 **
81809 ** If the sqlite_statN tables do not previously exist, it is created.
81810 **
81811 ** Argument zWhere may be a pointer to a buffer containing a table name,
81812 ** or it may be a NULL pointer. If it is not NULL, then all entries in
81813 ** the sqlite_statN tables associated with the named table are deleted.
81814 ** If zWhere==0, then code is generated to delete all stat table entries.
81815 */
81816 static void openStatTable(
81817   Parse *pParse,          /* Parsing context */
81818   int iDb,                /* The database we are looking in */
81819   int iStatCur,           /* Open the sqlite_stat1 table on this cursor */
81820   const char *zWhere,     /* Delete entries for this table or index */
81821   const char *zWhereType  /* Either "tbl" or "idx" */
81822 ){
81823   static const struct {
81824     const char *zName;
81825     const char *zCols;
81826   } aTable[] = {
81827     { "sqlite_stat1", "tbl,idx,stat" },
81828 #if defined(SQLITE_ENABLE_STAT4)
81829     { "sqlite_stat4", "tbl,idx,neq,nlt,ndlt,sample" },
81830     { "sqlite_stat3", 0 },
81831 #elif defined(SQLITE_ENABLE_STAT3)
81832     { "sqlite_stat3", "tbl,idx,neq,nlt,ndlt,sample" },
81833     { "sqlite_stat4", 0 },
81834 #else
81835     { "sqlite_stat3", 0 },
81836     { "sqlite_stat4", 0 },
81837 #endif
81838   };
81839   int i;
81840   sqlite3 *db = pParse->db;
81841   Db *pDb;
81842   Vdbe *v = sqlite3GetVdbe(pParse);
81843   int aRoot[ArraySize(aTable)];
81844   u8 aCreateTbl[ArraySize(aTable)];
81845 
81846   if( v==0 ) return;
81847   assert( sqlite3BtreeHoldsAllMutexes(db) );
81848   assert( sqlite3VdbeDb(v)==db );
81849   pDb = &db->aDb[iDb];
81850 
81851   /* Create new statistic tables if they do not exist, or clear them
81852   ** if they do already exist.
81853   */
81854   for(i=0; i<ArraySize(aTable); i++){
81855     const char *zTab = aTable[i].zName;
81856     Table *pStat;
81857     if( (pStat = sqlite3FindTable(db, zTab, pDb->zName))==0 ){
81858       if( aTable[i].zCols ){
81859         /* The sqlite_statN table does not exist. Create it. Note that a 
81860         ** side-effect of the CREATE TABLE statement is to leave the rootpage 
81861         ** of the new table in register pParse->regRoot. This is important 
81862         ** because the OpenWrite opcode below will be needing it. */
81863         sqlite3NestedParse(pParse,
81864             "CREATE TABLE %Q.%s(%s)", pDb->zName, zTab, aTable[i].zCols
81865         );
81866         aRoot[i] = pParse->regRoot;
81867         aCreateTbl[i] = OPFLAG_P2ISREG;
81868       }
81869     }else{
81870       /* The table already exists. If zWhere is not NULL, delete all entries 
81871       ** associated with the table zWhere. If zWhere is NULL, delete the
81872       ** entire contents of the table. */
81873       aRoot[i] = pStat->tnum;
81874       aCreateTbl[i] = 0;
81875       sqlite3TableLock(pParse, iDb, aRoot[i], 1, zTab);
81876       if( zWhere ){
81877         sqlite3NestedParse(pParse,
81878            "DELETE FROM %Q.%s WHERE %s=%Q",
81879            pDb->zName, zTab, zWhereType, zWhere
81880         );
81881       }else{
81882         /* The sqlite_stat[134] table already exists.  Delete all rows. */
81883         sqlite3VdbeAddOp2(v, OP_Clear, aRoot[i], iDb);
81884       }
81885     }
81886   }
81887 
81888   /* Open the sqlite_stat[134] tables for writing. */
81889   for(i=0; aTable[i].zCols; i++){
81890     assert( i<ArraySize(aTable) );
81891     sqlite3VdbeAddOp4Int(v, OP_OpenWrite, iStatCur+i, aRoot[i], iDb, 3);
81892     sqlite3VdbeChangeP5(v, aCreateTbl[i]);
81893   }
81894 }
81895 
81896 /*
81897 ** Recommended number of samples for sqlite_stat4
81898 */
81899 #ifndef SQLITE_STAT4_SAMPLES
81900 # define SQLITE_STAT4_SAMPLES 24
81901 #endif
81902 
81903 /*
81904 ** Three SQL functions - stat_init(), stat_push(), and stat_get() -
81905 ** share an instance of the following structure to hold their state
81906 ** information.
81907 */
81908 typedef struct Stat4Accum Stat4Accum;
81909 typedef struct Stat4Sample Stat4Sample;
81910 struct Stat4Sample {
81911   tRowcnt *anEq;                  /* sqlite_stat4.nEq */
81912   tRowcnt *anDLt;                 /* sqlite_stat4.nDLt */
81913 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
81914   tRowcnt *anLt;                  /* sqlite_stat4.nLt */
81915   union {
81916     i64 iRowid;                     /* Rowid in main table of the key */
81917     u8 *aRowid;                     /* Key for WITHOUT ROWID tables */
81918   } u;
81919   u32 nRowid;                     /* Sizeof aRowid[] */
81920   u8 isPSample;                   /* True if a periodic sample */
81921   int iCol;                       /* If !isPSample, the reason for inclusion */
81922   u32 iHash;                      /* Tiebreaker hash */
81923 #endif
81924 };                                                    
81925 struct Stat4Accum {
81926   tRowcnt nRow;             /* Number of rows in the entire table */
81927   tRowcnt nPSample;         /* How often to do a periodic sample */
81928   int nCol;                 /* Number of columns in index + rowid */
81929   int mxSample;             /* Maximum number of samples to accumulate */
81930   Stat4Sample current;      /* Current row as a Stat4Sample */
81931   u32 iPrn;                 /* Pseudo-random number used for sampling */
81932   Stat4Sample *aBest;       /* Array of nCol best samples */
81933   int iMin;                 /* Index in a[] of entry with minimum score */
81934   int nSample;              /* Current number of samples */
81935   int iGet;                 /* Index of current sample accessed by stat_get() */
81936   Stat4Sample *a;           /* Array of mxSample Stat4Sample objects */
81937   sqlite3 *db;              /* Database connection, for malloc() */
81938 };
81939 
81940 /* Reclaim memory used by a Stat4Sample
81941 */
81942 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
81943 static void sampleClear(sqlite3 *db, Stat4Sample *p){
81944   assert( db!=0 );
81945   if( p->nRowid ){
81946     sqlite3DbFree(db, p->u.aRowid);
81947     p->nRowid = 0;
81948   }
81949 }
81950 #endif
81951 
81952 /* Initialize the BLOB value of a ROWID
81953 */
81954 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
81955 static void sampleSetRowid(sqlite3 *db, Stat4Sample *p, int n, const u8 *pData){
81956   assert( db!=0 );
81957   if( p->nRowid ) sqlite3DbFree(db, p->u.aRowid);
81958   p->u.aRowid = sqlite3DbMallocRaw(db, n);
81959   if( p->u.aRowid ){
81960     p->nRowid = n;
81961     memcpy(p->u.aRowid, pData, n);
81962   }else{
81963     p->nRowid = 0;
81964   }
81965 }
81966 #endif
81967 
81968 /* Initialize the INTEGER value of a ROWID.
81969 */
81970 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
81971 static void sampleSetRowidInt64(sqlite3 *db, Stat4Sample *p, i64 iRowid){
81972   assert( db!=0 );
81973   if( p->nRowid ) sqlite3DbFree(db, p->u.aRowid);
81974   p->nRowid = 0;
81975   p->u.iRowid = iRowid;
81976 }
81977 #endif
81978 
81979 
81980 /*
81981 ** Copy the contents of object (*pFrom) into (*pTo).
81982 */
81983 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
81984 static void sampleCopy(Stat4Accum *p, Stat4Sample *pTo, Stat4Sample *pFrom){
81985   pTo->isPSample = pFrom->isPSample;
81986   pTo->iCol = pFrom->iCol;
81987   pTo->iHash = pFrom->iHash;
81988   memcpy(pTo->anEq, pFrom->anEq, sizeof(tRowcnt)*p->nCol);
81989   memcpy(pTo->anLt, pFrom->anLt, sizeof(tRowcnt)*p->nCol);
81990   memcpy(pTo->anDLt, pFrom->anDLt, sizeof(tRowcnt)*p->nCol);
81991   if( pFrom->nRowid ){
81992     sampleSetRowid(p->db, pTo, pFrom->nRowid, pFrom->u.aRowid);
81993   }else{
81994     sampleSetRowidInt64(p->db, pTo, pFrom->u.iRowid);
81995   }
81996 }
81997 #endif
81998 
81999 /*
82000 ** Reclaim all memory of a Stat4Accum structure.
82001 */
82002 static void stat4Destructor(void *pOld){
82003   Stat4Accum *p = (Stat4Accum*)pOld;
82004 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82005   int i;
82006   for(i=0; i<p->nCol; i++) sampleClear(p->db, p->aBest+i);
82007   for(i=0; i<p->mxSample; i++) sampleClear(p->db, p->a+i);
82008   sampleClear(p->db, &p->current);
82009 #endif
82010   sqlite3DbFree(p->db, p);
82011 }
82012 
82013 /*
82014 ** Implementation of the stat_init(N,C) SQL function. The two parameters
82015 ** are the number of rows in the table or index (C) and the number of columns
82016 ** in the index (N).  The second argument (C) is only used for STAT3 and STAT4.
82017 **
82018 ** This routine allocates the Stat4Accum object in heap memory. The return 
82019 ** value is a pointer to the the Stat4Accum object encoded as a blob (i.e. 
82020 ** the size of the blob is sizeof(void*) bytes). 
82021 */
82022 static void statInit(
82023   sqlite3_context *context,
82024   int argc,
82025   sqlite3_value **argv
82026 ){
82027   Stat4Accum *p;
82028   int nCol;                       /* Number of columns in index being sampled */
82029   int nColUp;                     /* nCol rounded up for alignment */
82030   int n;                          /* Bytes of space to allocate */
82031   sqlite3 *db;                    /* Database connection */
82032 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82033   int mxSample = SQLITE_STAT4_SAMPLES;
82034 #endif
82035 
82036   /* Decode the three function arguments */
82037   UNUSED_PARAMETER(argc);
82038   nCol = sqlite3_value_int(argv[0]);
82039   assert( nCol>1 );               /* >1 because it includes the rowid column */
82040   nColUp = sizeof(tRowcnt)<8 ? (nCol+1)&~1 : nCol;
82041 
82042   /* Allocate the space required for the Stat4Accum object */
82043   n = sizeof(*p) 
82044     + sizeof(tRowcnt)*nColUp                  /* Stat4Accum.anEq */
82045     + sizeof(tRowcnt)*nColUp                  /* Stat4Accum.anDLt */
82046 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82047     + sizeof(tRowcnt)*nColUp                  /* Stat4Accum.anLt */
82048     + sizeof(Stat4Sample)*(nCol+mxSample)     /* Stat4Accum.aBest[], a[] */
82049     + sizeof(tRowcnt)*3*nColUp*(nCol+mxSample)
82050 #endif
82051   ;
82052   db = sqlite3_context_db_handle(context);
82053   p = sqlite3DbMallocZero(db, n);
82054   if( p==0 ){
82055     sqlite3_result_error_nomem(context);
82056     return;
82057   }
82058 
82059   p->db = db;
82060   p->nRow = 0;
82061   p->nCol = nCol;
82062   p->current.anDLt = (tRowcnt*)&p[1];
82063   p->current.anEq = &p->current.anDLt[nColUp];
82064 
82065 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82066   {
82067     u8 *pSpace;                     /* Allocated space not yet assigned */
82068     int i;                          /* Used to iterate through p->aSample[] */
82069 
82070     p->iGet = -1;
82071     p->mxSample = mxSample;
82072     p->nPSample = (tRowcnt)(sqlite3_value_int64(argv[1])/(mxSample/3+1) + 1);
82073     p->current.anLt = &p->current.anEq[nColUp];
82074     p->iPrn = nCol*0x689e962d ^ sqlite3_value_int(argv[1])*0xd0944565;
82075   
82076     /* Set up the Stat4Accum.a[] and aBest[] arrays */
82077     p->a = (struct Stat4Sample*)&p->current.anLt[nColUp];
82078     p->aBest = &p->a[mxSample];
82079     pSpace = (u8*)(&p->a[mxSample+nCol]);
82080     for(i=0; i<(mxSample+nCol); i++){
82081       p->a[i].anEq = (tRowcnt *)pSpace; pSpace += (sizeof(tRowcnt) * nColUp);
82082       p->a[i].anLt = (tRowcnt *)pSpace; pSpace += (sizeof(tRowcnt) * nColUp);
82083       p->a[i].anDLt = (tRowcnt *)pSpace; pSpace += (sizeof(tRowcnt) * nColUp);
82084     }
82085     assert( (pSpace - (u8*)p)==n );
82086   
82087     for(i=0; i<nCol; i++){
82088       p->aBest[i].iCol = i;
82089     }
82090   }
82091 #endif
82092 
82093   /* Return a pointer to the allocated object to the caller */
82094   sqlite3_result_blob(context, p, sizeof(p), stat4Destructor);
82095 }
82096 static const FuncDef statInitFuncdef = {
82097   1+IsStat34,      /* nArg */
82098   SQLITE_UTF8,     /* funcFlags */
82099   0,               /* pUserData */
82100   0,               /* pNext */
82101   statInit,        /* xFunc */
82102   0,               /* xStep */
82103   0,               /* xFinalize */
82104   "stat_init",     /* zName */
82105   0,               /* pHash */
82106   0                /* pDestructor */
82107 };
82108 
82109 #ifdef SQLITE_ENABLE_STAT4
82110 /*
82111 ** pNew and pOld are both candidate non-periodic samples selected for 
82112 ** the same column (pNew->iCol==pOld->iCol). Ignoring this column and 
82113 ** considering only any trailing columns and the sample hash value, this
82114 ** function returns true if sample pNew is to be preferred over pOld.
82115 ** In other words, if we assume that the cardinalities of the selected
82116 ** column for pNew and pOld are equal, is pNew to be preferred over pOld.
82117 **
82118 ** This function assumes that for each argument sample, the contents of
82119 ** the anEq[] array from pSample->anEq[pSample->iCol+1] onwards are valid. 
82120 */
82121 static int sampleIsBetterPost(
82122   Stat4Accum *pAccum, 
82123   Stat4Sample *pNew, 
82124   Stat4Sample *pOld
82125 ){
82126   int nCol = pAccum->nCol;
82127   int i;
82128   assert( pNew->iCol==pOld->iCol );
82129   for(i=pNew->iCol+1; i<nCol; i++){
82130     if( pNew->anEq[i]>pOld->anEq[i] ) return 1;
82131     if( pNew->anEq[i]<pOld->anEq[i] ) return 0;
82132   }
82133   if( pNew->iHash>pOld->iHash ) return 1;
82134   return 0;
82135 }
82136 #endif
82137 
82138 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82139 /*
82140 ** Return true if pNew is to be preferred over pOld.
82141 **
82142 ** This function assumes that for each argument sample, the contents of
82143 ** the anEq[] array from pSample->anEq[pSample->iCol] onwards are valid. 
82144 */
82145 static int sampleIsBetter(
82146   Stat4Accum *pAccum, 
82147   Stat4Sample *pNew, 
82148   Stat4Sample *pOld
82149 ){
82150   tRowcnt nEqNew = pNew->anEq[pNew->iCol];
82151   tRowcnt nEqOld = pOld->anEq[pOld->iCol];
82152 
82153   assert( pOld->isPSample==0 && pNew->isPSample==0 );
82154   assert( IsStat4 || (pNew->iCol==0 && pOld->iCol==0) );
82155 
82156   if( (nEqNew>nEqOld) ) return 1;
82157 #ifdef SQLITE_ENABLE_STAT4
82158   if( nEqNew==nEqOld ){
82159     if( pNew->iCol<pOld->iCol ) return 1;
82160     return (pNew->iCol==pOld->iCol && sampleIsBetterPost(pAccum, pNew, pOld));
82161   }
82162   return 0;
82163 #else
82164   return (nEqNew==nEqOld && pNew->iHash>pOld->iHash);
82165 #endif
82166 }
82167 
82168 /*
82169 ** Copy the contents of sample *pNew into the p->a[] array. If necessary,
82170 ** remove the least desirable sample from p->a[] to make room.
82171 */
82172 static void sampleInsert(Stat4Accum *p, Stat4Sample *pNew, int nEqZero){
82173   Stat4Sample *pSample = 0;
82174   int i;
82175 
82176   assert( IsStat4 || nEqZero==0 );
82177 
82178 #ifdef SQLITE_ENABLE_STAT4
82179   if( pNew->isPSample==0 ){
82180     Stat4Sample *pUpgrade = 0;
82181     assert( pNew->anEq[pNew->iCol]>0 );
82182 
82183     /* This sample is being added because the prefix that ends in column 
82184     ** iCol occurs many times in the table. However, if we have already
82185     ** added a sample that shares this prefix, there is no need to add
82186     ** this one. Instead, upgrade the priority of the highest priority
82187     ** existing sample that shares this prefix.  */
82188     for(i=p->nSample-1; i>=0; i--){
82189       Stat4Sample *pOld = &p->a[i];
82190       if( pOld->anEq[pNew->iCol]==0 ){
82191         if( pOld->isPSample ) return;
82192         assert( pOld->iCol>pNew->iCol );
82193         assert( sampleIsBetter(p, pNew, pOld) );
82194         if( pUpgrade==0 || sampleIsBetter(p, pOld, pUpgrade) ){
82195           pUpgrade = pOld;
82196         }
82197       }
82198     }
82199     if( pUpgrade ){
82200       pUpgrade->iCol = pNew->iCol;
82201       pUpgrade->anEq[pUpgrade->iCol] = pNew->anEq[pUpgrade->iCol];
82202       goto find_new_min;
82203     }
82204   }
82205 #endif
82206 
82207   /* If necessary, remove sample iMin to make room for the new sample. */
82208   if( p->nSample>=p->mxSample ){
82209     Stat4Sample *pMin = &p->a[p->iMin];
82210     tRowcnt *anEq = pMin->anEq;
82211     tRowcnt *anLt = pMin->anLt;
82212     tRowcnt *anDLt = pMin->anDLt;
82213     sampleClear(p->db, pMin);
82214     memmove(pMin, &pMin[1], sizeof(p->a[0])*(p->nSample-p->iMin-1));
82215     pSample = &p->a[p->nSample-1];
82216     pSample->nRowid = 0;
82217     pSample->anEq = anEq;
82218     pSample->anDLt = anDLt;
82219     pSample->anLt = anLt;
82220     p->nSample = p->mxSample-1;
82221   }
82222 
82223   /* The "rows less-than" for the rowid column must be greater than that
82224   ** for the last sample in the p->a[] array. Otherwise, the samples would
82225   ** be out of order. */
82226 #ifdef SQLITE_ENABLE_STAT4
82227   assert( p->nSample==0 
82228        || pNew->anLt[p->nCol-1] > p->a[p->nSample-1].anLt[p->nCol-1] );
82229 #endif
82230 
82231   /* Insert the new sample */
82232   pSample = &p->a[p->nSample];
82233   sampleCopy(p, pSample, pNew);
82234   p->nSample++;
82235 
82236   /* Zero the first nEqZero entries in the anEq[] array. */
82237   memset(pSample->anEq, 0, sizeof(tRowcnt)*nEqZero);
82238 
82239 #ifdef SQLITE_ENABLE_STAT4
82240  find_new_min:
82241 #endif
82242   if( p->nSample>=p->mxSample ){
82243     int iMin = -1;
82244     for(i=0; i<p->mxSample; i++){
82245       if( p->a[i].isPSample ) continue;
82246       if( iMin<0 || sampleIsBetter(p, &p->a[iMin], &p->a[i]) ){
82247         iMin = i;
82248       }
82249     }
82250     assert( iMin>=0 );
82251     p->iMin = iMin;
82252   }
82253 }
82254 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
82255 
82256 /*
82257 ** Field iChng of the index being scanned has changed. So at this point
82258 ** p->current contains a sample that reflects the previous row of the
82259 ** index. The value of anEq[iChng] and subsequent anEq[] elements are
82260 ** correct at this point.
82261 */
82262 static void samplePushPrevious(Stat4Accum *p, int iChng){
82263 #ifdef SQLITE_ENABLE_STAT4
82264   int i;
82265 
82266   /* Check if any samples from the aBest[] array should be pushed
82267   ** into IndexSample.a[] at this point.  */
82268   for(i=(p->nCol-2); i>=iChng; i--){
82269     Stat4Sample *pBest = &p->aBest[i];
82270     pBest->anEq[i] = p->current.anEq[i];
82271     if( p->nSample<p->mxSample || sampleIsBetter(p, pBest, &p->a[p->iMin]) ){
82272       sampleInsert(p, pBest, i);
82273     }
82274   }
82275 
82276   /* Update the anEq[] fields of any samples already collected. */
82277   for(i=p->nSample-1; i>=0; i--){
82278     int j;
82279     for(j=iChng; j<p->nCol; j++){
82280       if( p->a[i].anEq[j]==0 ) p->a[i].anEq[j] = p->current.anEq[j];
82281     }
82282   }
82283 #endif
82284 
82285 #if defined(SQLITE_ENABLE_STAT3) && !defined(SQLITE_ENABLE_STAT4)
82286   if( iChng==0 ){
82287     tRowcnt nLt = p->current.anLt[0];
82288     tRowcnt nEq = p->current.anEq[0];
82289 
82290     /* Check if this is to be a periodic sample. If so, add it. */
82291     if( (nLt/p->nPSample)!=(nLt+nEq)/p->nPSample ){
82292       p->current.isPSample = 1;
82293       sampleInsert(p, &p->current, 0);
82294       p->current.isPSample = 0;
82295     }else 
82296 
82297     /* Or if it is a non-periodic sample. Add it in this case too. */
82298     if( p->nSample<p->mxSample 
82299      || sampleIsBetter(p, &p->current, &p->a[p->iMin]) 
82300     ){
82301       sampleInsert(p, &p->current, 0);
82302     }
82303   }
82304 #endif
82305 
82306 #ifndef SQLITE_ENABLE_STAT3_OR_STAT4
82307   UNUSED_PARAMETER( p );
82308   UNUSED_PARAMETER( iChng );
82309 #endif
82310 }
82311 
82312 /*
82313 ** Implementation of the stat_push SQL function:  stat_push(P,C,R)
82314 ** Arguments:
82315 **
82316 **    P     Pointer to the Stat4Accum object created by stat_init()
82317 **    C     Index of left-most column to differ from previous row
82318 **    R     Rowid for the current row.  Might be a key record for
82319 **          WITHOUT ROWID tables.
82320 **
82321 ** The SQL function always returns NULL.
82322 **
82323 ** The R parameter is only used for STAT3 and STAT4
82324 */
82325 static void statPush(
82326   sqlite3_context *context,
82327   int argc,
82328   sqlite3_value **argv
82329 ){
82330   int i;
82331 
82332   /* The three function arguments */
82333   Stat4Accum *p = (Stat4Accum*)sqlite3_value_blob(argv[0]);
82334   int iChng = sqlite3_value_int(argv[1]);
82335 
82336   UNUSED_PARAMETER( argc );
82337   UNUSED_PARAMETER( context );
82338   assert( p->nCol>1 );        /* Includes rowid field */
82339   assert( iChng<p->nCol );
82340 
82341   if( p->nRow==0 ){
82342     /* This is the first call to this function. Do initialization. */
82343     for(i=0; i<p->nCol; i++) p->current.anEq[i] = 1;
82344   }else{
82345     /* Second and subsequent calls get processed here */
82346     samplePushPrevious(p, iChng);
82347 
82348     /* Update anDLt[], anLt[] and anEq[] to reflect the values that apply
82349     ** to the current row of the index. */
82350     for(i=0; i<iChng; i++){
82351       p->current.anEq[i]++;
82352     }
82353     for(i=iChng; i<p->nCol; i++){
82354       p->current.anDLt[i]++;
82355 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82356       p->current.anLt[i] += p->current.anEq[i];
82357 #endif
82358       p->current.anEq[i] = 1;
82359     }
82360   }
82361   p->nRow++;
82362 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82363   if( sqlite3_value_type(argv[2])==SQLITE_INTEGER ){
82364     sampleSetRowidInt64(p->db, &p->current, sqlite3_value_int64(argv[2]));
82365   }else{
82366     sampleSetRowid(p->db, &p->current, sqlite3_value_bytes(argv[2]),
82367                                        sqlite3_value_blob(argv[2]));
82368   }
82369   p->current.iHash = p->iPrn = p->iPrn*1103515245 + 12345;
82370 #endif
82371 
82372 #ifdef SQLITE_ENABLE_STAT4
82373   {
82374     tRowcnt nLt = p->current.anLt[p->nCol-1];
82375 
82376     /* Check if this is to be a periodic sample. If so, add it. */
82377     if( (nLt/p->nPSample)!=(nLt+1)/p->nPSample ){
82378       p->current.isPSample = 1;
82379       p->current.iCol = 0;
82380       sampleInsert(p, &p->current, p->nCol-1);
82381       p->current.isPSample = 0;
82382     }
82383 
82384     /* Update the aBest[] array. */
82385     for(i=0; i<(p->nCol-1); i++){
82386       p->current.iCol = i;
82387       if( i>=iChng || sampleIsBetterPost(p, &p->current, &p->aBest[i]) ){
82388         sampleCopy(p, &p->aBest[i], &p->current);
82389       }
82390     }
82391   }
82392 #endif
82393 }
82394 static const FuncDef statPushFuncdef = {
82395   2+IsStat34,      /* nArg */
82396   SQLITE_UTF8,     /* funcFlags */
82397   0,               /* pUserData */
82398   0,               /* pNext */
82399   statPush,        /* xFunc */
82400   0,               /* xStep */
82401   0,               /* xFinalize */
82402   "stat_push",     /* zName */
82403   0,               /* pHash */
82404   0                /* pDestructor */
82405 };
82406 
82407 #define STAT_GET_STAT1 0          /* "stat" column of stat1 table */
82408 #define STAT_GET_ROWID 1          /* "rowid" column of stat[34] entry */
82409 #define STAT_GET_NEQ   2          /* "neq" column of stat[34] entry */
82410 #define STAT_GET_NLT   3          /* "nlt" column of stat[34] entry */
82411 #define STAT_GET_NDLT  4          /* "ndlt" column of stat[34] entry */
82412 
82413 /*
82414 ** Implementation of the stat_get(P,J) SQL function.  This routine is
82415 ** used to query the results.  Content is returned for parameter J
82416 ** which is one of the STAT_GET_xxxx values defined above.
82417 **
82418 ** If neither STAT3 nor STAT4 are enabled, then J is always
82419 ** STAT_GET_STAT1 and is hence omitted and this routine becomes
82420 ** a one-parameter function, stat_get(P), that always returns the
82421 ** stat1 table entry information.
82422 */
82423 static void statGet(
82424   sqlite3_context *context,
82425   int argc,
82426   sqlite3_value **argv
82427 ){
82428   Stat4Accum *p = (Stat4Accum*)sqlite3_value_blob(argv[0]);
82429 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82430   /* STAT3 and STAT4 have a parameter on this routine. */
82431   int eCall = sqlite3_value_int(argv[1]);
82432   assert( argc==2 );
82433   assert( eCall==STAT_GET_STAT1 || eCall==STAT_GET_NEQ 
82434        || eCall==STAT_GET_ROWID || eCall==STAT_GET_NLT
82435        || eCall==STAT_GET_NDLT 
82436   );
82437   if( eCall==STAT_GET_STAT1 )
82438 #else
82439   assert( argc==1 );
82440 #endif
82441   {
82442     /* Return the value to store in the "stat" column of the sqlite_stat1
82443     ** table for this index.
82444     **
82445     ** The value is a string composed of a list of integers describing 
82446     ** the index. The first integer in the list is the total number of 
82447     ** entries in the index. There is one additional integer in the list 
82448     ** for each indexed column. This additional integer is an estimate of
82449     ** the number of rows matched by a stabbing query on the index using
82450     ** a key with the corresponding number of fields. In other words,
82451     ** if the index is on columns (a,b) and the sqlite_stat1 value is 
82452     ** "100 10 2", then SQLite estimates that:
82453     **
82454     **   * the index contains 100 rows,
82455     **   * "WHERE a=?" matches 10 rows, and
82456     **   * "WHERE a=? AND b=?" matches 2 rows.
82457     **
82458     ** If D is the count of distinct values and K is the total number of 
82459     ** rows, then each estimate is computed as:
82460     **
82461     **        I = (K+D-1)/D
82462     */
82463     char *z;
82464     int i;
82465 
82466     char *zRet = sqlite3MallocZero(p->nCol * 25);
82467     if( zRet==0 ){
82468       sqlite3_result_error_nomem(context);
82469       return;
82470     }
82471 
82472     sqlite3_snprintf(24, zRet, "%llu", (u64)p->nRow);
82473     z = zRet + sqlite3Strlen30(zRet);
82474     for(i=0; i<(p->nCol-1); i++){
82475       u64 nDistinct = p->current.anDLt[i] + 1;
82476       u64 iVal = (p->nRow + nDistinct - 1) / nDistinct;
82477       sqlite3_snprintf(24, z, " %llu", iVal);
82478       z += sqlite3Strlen30(z);
82479       assert( p->current.anEq[i] );
82480     }
82481     assert( z[0]=='\0' && z>zRet );
82482 
82483     sqlite3_result_text(context, zRet, -1, sqlite3_free);
82484   }
82485 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82486   else if( eCall==STAT_GET_ROWID ){
82487     if( p->iGet<0 ){
82488       samplePushPrevious(p, 0);
82489       p->iGet = 0;
82490     }
82491     if( p->iGet<p->nSample ){
82492       Stat4Sample *pS = p->a + p->iGet;
82493       if( pS->nRowid==0 ){
82494         sqlite3_result_int64(context, pS->u.iRowid);
82495       }else{
82496         sqlite3_result_blob(context, pS->u.aRowid, pS->nRowid,
82497                             SQLITE_TRANSIENT);
82498       }
82499     }
82500   }else{
82501     tRowcnt *aCnt = 0;
82502 
82503     assert( p->iGet<p->nSample );
82504     switch( eCall ){
82505       case STAT_GET_NEQ:  aCnt = p->a[p->iGet].anEq; break;
82506       case STAT_GET_NLT:  aCnt = p->a[p->iGet].anLt; break;
82507       default: {
82508         aCnt = p->a[p->iGet].anDLt; 
82509         p->iGet++;
82510         break;
82511       }
82512     }
82513 
82514     if( IsStat3 ){
82515       sqlite3_result_int64(context, (i64)aCnt[0]);
82516     }else{
82517       char *zRet = sqlite3MallocZero(p->nCol * 25);
82518       if( zRet==0 ){
82519         sqlite3_result_error_nomem(context);
82520       }else{
82521         int i;
82522         char *z = zRet;
82523         for(i=0; i<p->nCol; i++){
82524           sqlite3_snprintf(24, z, "%llu ", (u64)aCnt[i]);
82525           z += sqlite3Strlen30(z);
82526         }
82527         assert( z[0]=='\0' && z>zRet );
82528         z[-1] = '\0';
82529         sqlite3_result_text(context, zRet, -1, sqlite3_free);
82530       }
82531     }
82532   }
82533 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
82534 #ifndef SQLITE_DEBUG
82535   UNUSED_PARAMETER( argc );
82536 #endif
82537 }
82538 static const FuncDef statGetFuncdef = {
82539   1+IsStat34,      /* nArg */
82540   SQLITE_UTF8,     /* funcFlags */
82541   0,               /* pUserData */
82542   0,               /* pNext */
82543   statGet,         /* xFunc */
82544   0,               /* xStep */
82545   0,               /* xFinalize */
82546   "stat_get",      /* zName */
82547   0,               /* pHash */
82548   0                /* pDestructor */
82549 };
82550 
82551 static void callStatGet(Vdbe *v, int regStat4, int iParam, int regOut){
82552   assert( regOut!=regStat4 && regOut!=regStat4+1 );
82553 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82554   sqlite3VdbeAddOp2(v, OP_Integer, iParam, regStat4+1);
82555 #elif SQLITE_DEBUG
82556   assert( iParam==STAT_GET_STAT1 );
82557 #else
82558   UNUSED_PARAMETER( iParam );
82559 #endif
82560   sqlite3VdbeAddOp3(v, OP_Function, 0, regStat4, regOut);
82561   sqlite3VdbeChangeP4(v, -1, (char*)&statGetFuncdef, P4_FUNCDEF);
82562   sqlite3VdbeChangeP5(v, 1 + IsStat34);
82563 }
82564 
82565 /*
82566 ** Generate code to do an analysis of all indices associated with
82567 ** a single table.
82568 */
82569 static void analyzeOneTable(
82570   Parse *pParse,   /* Parser context */
82571   Table *pTab,     /* Table whose indices are to be analyzed */
82572   Index *pOnlyIdx, /* If not NULL, only analyze this one index */
82573   int iStatCur,    /* Index of VdbeCursor that writes the sqlite_stat1 table */
82574   int iMem,        /* Available memory locations begin here */
82575   int iTab         /* Next available cursor */
82576 ){
82577   sqlite3 *db = pParse->db;    /* Database handle */
82578   Index *pIdx;                 /* An index to being analyzed */
82579   int iIdxCur;                 /* Cursor open on index being analyzed */
82580   int iTabCur;                 /* Table cursor */
82581   Vdbe *v;                     /* The virtual machine being built up */
82582   int i;                       /* Loop counter */
82583   int jZeroRows = -1;          /* Jump from here if number of rows is zero */
82584   int iDb;                     /* Index of database containing pTab */
82585   u8 needTableCnt = 1;         /* True to count the table */
82586   int regNewRowid = iMem++;    /* Rowid for the inserted record */
82587   int regStat4 = iMem++;       /* Register to hold Stat4Accum object */
82588   int regChng = iMem++;        /* Index of changed index field */
82589 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82590   int regRowid = iMem++;       /* Rowid argument passed to stat_push() */
82591 #endif
82592   int regTemp = iMem++;        /* Temporary use register */
82593   int regTabname = iMem++;     /* Register containing table name */
82594   int regIdxname = iMem++;     /* Register containing index name */
82595   int regStat1 = iMem++;       /* Value for the stat column of sqlite_stat1 */
82596   int regPrev = iMem;          /* MUST BE LAST (see below) */
82597 
82598   pParse->nMem = MAX(pParse->nMem, iMem);
82599   v = sqlite3GetVdbe(pParse);
82600   if( v==0 || NEVER(pTab==0) ){
82601     return;
82602   }
82603   if( pTab->tnum==0 ){
82604     /* Do not gather statistics on views or virtual tables */
82605     return;
82606   }
82607   if( sqlite3_strnicmp(pTab->zName, "sqlite_", 7)==0 ){
82608     /* Do not gather statistics on system tables */
82609     return;
82610   }
82611   assert( sqlite3BtreeHoldsAllMutexes(db) );
82612   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
82613   assert( iDb>=0 );
82614   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
82615 #ifndef SQLITE_OMIT_AUTHORIZATION
82616   if( sqlite3AuthCheck(pParse, SQLITE_ANALYZE, pTab->zName, 0,
82617       db->aDb[iDb].zName ) ){
82618     return;
82619   }
82620 #endif
82621 
82622   /* Establish a read-lock on the table at the shared-cache level. 
82623   ** Open a read-only cursor on the table. Also allocate a cursor number
82624   ** to use for scanning indexes (iIdxCur). No index cursor is opened at
82625   ** this time though.  */
82626   sqlite3TableLock(pParse, iDb, pTab->tnum, 0, pTab->zName);
82627   iTabCur = iTab++;
82628   iIdxCur = iTab++;
82629   pParse->nTab = MAX(pParse->nTab, iTab);
82630   sqlite3OpenTable(pParse, iTabCur, iDb, pTab, OP_OpenRead);
82631   sqlite3VdbeAddOp4(v, OP_String8, 0, regTabname, 0, pTab->zName, 0);
82632 
82633   for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
82634     int nCol;                     /* Number of columns indexed by pIdx */
82635     int *aGotoChng;               /* Array of jump instruction addresses */
82636     int addrRewind;               /* Address of "OP_Rewind iIdxCur" */
82637     int addrGotoChng0;            /* Address of "Goto addr_chng_0" */
82638     int addrNextRow;              /* Address of "next_row:" */
82639     const char *zIdxName;         /* Name of the index */
82640 
82641     if( pOnlyIdx && pOnlyIdx!=pIdx ) continue;
82642     if( pIdx->pPartIdxWhere==0 ) needTableCnt = 0;
82643     VdbeNoopComment((v, "Begin analysis of %s", pIdx->zName));
82644     nCol = pIdx->nKeyCol;
82645     aGotoChng = sqlite3DbMallocRaw(db, sizeof(int)*(nCol+1));
82646     if( aGotoChng==0 ) continue;
82647 
82648     /* Populate the register containing the index name. */
82649     if( pIdx->autoIndex==2 && !HasRowid(pTab) ){
82650       zIdxName = pTab->zName;
82651     }else{
82652       zIdxName = pIdx->zName;
82653     }
82654     sqlite3VdbeAddOp4(v, OP_String8, 0, regIdxname, 0, zIdxName, 0);
82655 
82656     /*
82657     ** Pseudo-code for loop that calls stat_push():
82658     **
82659     **   Rewind csr
82660     **   if eof(csr) goto end_of_scan;
82661     **   regChng = 0
82662     **   goto chng_addr_0;
82663     **
82664     **  next_row:
82665     **   regChng = 0
82666     **   if( idx(0) != regPrev(0) ) goto chng_addr_0
82667     **   regChng = 1
82668     **   if( idx(1) != regPrev(1) ) goto chng_addr_1
82669     **   ...
82670     **   regChng = N
82671     **   goto chng_addr_N
82672     **
82673     **  chng_addr_0:
82674     **   regPrev(0) = idx(0)
82675     **  chng_addr_1:
82676     **   regPrev(1) = idx(1)
82677     **  ...
82678     **
82679     **  chng_addr_N:
82680     **   regRowid = idx(rowid)
82681     **   stat_push(P, regChng, regRowid)
82682     **   Next csr
82683     **   if !eof(csr) goto next_row;
82684     **
82685     **  end_of_scan:
82686     */
82687 
82688     /* Make sure there are enough memory cells allocated to accommodate 
82689     ** the regPrev array and a trailing rowid (the rowid slot is required
82690     ** when building a record to insert into the sample column of 
82691     ** the sqlite_stat4 table.  */
82692     pParse->nMem = MAX(pParse->nMem, regPrev+nCol);
82693 
82694     /* Open a read-only cursor on the index being analyzed. */
82695     assert( iDb==sqlite3SchemaToIndex(db, pIdx->pSchema) );
82696     sqlite3VdbeAddOp3(v, OP_OpenRead, iIdxCur, pIdx->tnum, iDb);
82697     sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
82698     VdbeComment((v, "%s", pIdx->zName));
82699 
82700     /* Invoke the stat_init() function. The arguments are:
82701     ** 
82702     **    (1) the number of columns in the index including the rowid,
82703     **    (2) the number of rows in the index,
82704     **
82705     ** The second argument is only used for STAT3 and STAT4
82706     */
82707 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82708     sqlite3VdbeAddOp2(v, OP_Count, iIdxCur, regStat4+2);
82709 #endif
82710     sqlite3VdbeAddOp2(v, OP_Integer, nCol+1, regStat4+1);
82711     sqlite3VdbeAddOp3(v, OP_Function, 0, regStat4+1, regStat4);
82712     sqlite3VdbeChangeP4(v, -1, (char*)&statInitFuncdef, P4_FUNCDEF);
82713     sqlite3VdbeChangeP5(v, 1+IsStat34);
82714 
82715     /* Implementation of the following:
82716     **
82717     **   Rewind csr
82718     **   if eof(csr) goto end_of_scan;
82719     **   regChng = 0
82720     **   goto next_push_0;
82721     **
82722     */
82723     addrRewind = sqlite3VdbeAddOp1(v, OP_Rewind, iIdxCur);
82724     sqlite3VdbeAddOp2(v, OP_Integer, 0, regChng);
82725     addrGotoChng0 = sqlite3VdbeAddOp0(v, OP_Goto);
82726 
82727     /*
82728     **  next_row:
82729     **   regChng = 0
82730     **   if( idx(0) != regPrev(0) ) goto chng_addr_0
82731     **   regChng = 1
82732     **   if( idx(1) != regPrev(1) ) goto chng_addr_1
82733     **   ...
82734     **   regChng = N
82735     **   goto chng_addr_N
82736     */
82737     addrNextRow = sqlite3VdbeCurrentAddr(v);
82738     for(i=0; i<nCol; i++){
82739       char *pColl = (char*)sqlite3LocateCollSeq(pParse, pIdx->azColl[i]);
82740       sqlite3VdbeAddOp2(v, OP_Integer, i, regChng);
82741       sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, i, regTemp);
82742       aGotoChng[i] = 
82743       sqlite3VdbeAddOp4(v, OP_Ne, regTemp, 0, regPrev+i, pColl, P4_COLLSEQ);
82744       sqlite3VdbeChangeP5(v, SQLITE_NULLEQ);
82745     }
82746     sqlite3VdbeAddOp2(v, OP_Integer, nCol, regChng);
82747     aGotoChng[nCol] = sqlite3VdbeAddOp0(v, OP_Goto);
82748 
82749     /*
82750     **  chng_addr_0:
82751     **   regPrev(0) = idx(0)
82752     **  chng_addr_1:
82753     **   regPrev(1) = idx(1)
82754     **  ...
82755     */
82756     sqlite3VdbeJumpHere(v, addrGotoChng0);
82757     for(i=0; i<nCol; i++){
82758       sqlite3VdbeJumpHere(v, aGotoChng[i]);
82759       sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, i, regPrev+i);
82760     }
82761 
82762     /*
82763     **  chng_addr_N:
82764     **   regRowid = idx(rowid)            // STAT34 only
82765     **   stat_push(P, regChng, regRowid)  // 3rd parameter STAT34 only
82766     **   Next csr
82767     **   if !eof(csr) goto next_row;
82768     */
82769     sqlite3VdbeJumpHere(v, aGotoChng[nCol]);
82770 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82771     assert( regRowid==(regStat4+2) );
82772     if( HasRowid(pTab) ){
82773       sqlite3VdbeAddOp2(v, OP_IdxRowid, iIdxCur, regRowid);
82774     }else{
82775       Index *pPk = sqlite3PrimaryKeyIndex(pIdx->pTable);
82776       int j, k, regKey;
82777       regKey = sqlite3GetTempRange(pParse, pPk->nKeyCol);
82778       for(j=0; j<pPk->nKeyCol; j++){
82779         k = sqlite3ColumnOfIndex(pIdx, pPk->aiColumn[j]);
82780         sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, k, regKey+j);
82781         VdbeComment((v, "%s", pTab->aCol[pPk->aiColumn[j]].zName));
82782       }
82783       sqlite3VdbeAddOp3(v, OP_MakeRecord, regKey, pPk->nKeyCol, regRowid);
82784       sqlite3ReleaseTempRange(pParse, regKey, pPk->nKeyCol);
82785     }
82786 #endif
82787     assert( regChng==(regStat4+1) );
82788     sqlite3VdbeAddOp3(v, OP_Function, 1, regStat4, regTemp);
82789     sqlite3VdbeChangeP4(v, -1, (char*)&statPushFuncdef, P4_FUNCDEF);
82790     sqlite3VdbeChangeP5(v, 2+IsStat34);
82791     sqlite3VdbeAddOp2(v, OP_Next, iIdxCur, addrNextRow);
82792 
82793     /* Add the entry to the stat1 table. */
82794     callStatGet(v, regStat4, STAT_GET_STAT1, regStat1);
82795     sqlite3VdbeAddOp4(v, OP_MakeRecord, regTabname, 3, regTemp, "aaa", 0);
82796     sqlite3VdbeAddOp2(v, OP_NewRowid, iStatCur, regNewRowid);
82797     sqlite3VdbeAddOp3(v, OP_Insert, iStatCur, regTemp, regNewRowid);
82798     sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
82799 
82800     /* Add the entries to the stat3 or stat4 table. */
82801 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82802     {
82803       int regEq = regStat1;
82804       int regLt = regStat1+1;
82805       int regDLt = regStat1+2;
82806       int regSample = regStat1+3;
82807       int regCol = regStat1+4;
82808       int regSampleRowid = regCol + nCol;
82809       int addrNext;
82810       int addrIsNull;
82811       u8 seekOp = HasRowid(pTab) ? OP_NotExists : OP_NotFound;
82812 
82813       pParse->nMem = MAX(pParse->nMem, regCol+nCol+1);
82814 
82815       addrNext = sqlite3VdbeCurrentAddr(v);
82816       callStatGet(v, regStat4, STAT_GET_ROWID, regSampleRowid);
82817       addrIsNull = sqlite3VdbeAddOp1(v, OP_IsNull, regSampleRowid);
82818       callStatGet(v, regStat4, STAT_GET_NEQ, regEq);
82819       callStatGet(v, regStat4, STAT_GET_NLT, regLt);
82820       callStatGet(v, regStat4, STAT_GET_NDLT, regDLt);
82821       sqlite3VdbeAddOp4Int(v, seekOp, iTabCur, addrNext, regSampleRowid, 0);
82822 #ifdef SQLITE_ENABLE_STAT3
82823       sqlite3ExprCodeGetColumnOfTable(v, pTab, iTabCur, 
82824                                       pIdx->aiColumn[0], regSample);
82825 #else
82826       for(i=0; i<nCol; i++){
82827         i16 iCol = pIdx->aiColumn[i];
82828         sqlite3ExprCodeGetColumnOfTable(v, pTab, iTabCur, iCol, regCol+i);
82829       }
82830       sqlite3VdbeAddOp3(v, OP_MakeRecord, regCol, nCol+1, regSample);
82831 #endif
82832       sqlite3VdbeAddOp4(v, OP_MakeRecord, regTabname, 6, regTemp, "bbbbbb", 0);
82833       sqlite3VdbeAddOp2(v, OP_NewRowid, iStatCur+1, regNewRowid);
82834       sqlite3VdbeAddOp3(v, OP_Insert, iStatCur+1, regTemp, regNewRowid);
82835       sqlite3VdbeAddOp2(v, OP_Goto, 0, addrNext);
82836       sqlite3VdbeJumpHere(v, addrIsNull);
82837     }
82838 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
82839 
82840     /* End of analysis */
82841     sqlite3VdbeJumpHere(v, addrRewind);
82842     sqlite3DbFree(db, aGotoChng);
82843   }
82844 
82845 
82846   /* Create a single sqlite_stat1 entry containing NULL as the index
82847   ** name and the row count as the content.
82848   */
82849   if( pOnlyIdx==0 && needTableCnt ){
82850     VdbeComment((v, "%s", pTab->zName));
82851     sqlite3VdbeAddOp2(v, OP_Count, iTabCur, regStat1);
82852     jZeroRows = sqlite3VdbeAddOp1(v, OP_IfNot, regStat1);
82853     sqlite3VdbeAddOp2(v, OP_Null, 0, regIdxname);
82854     sqlite3VdbeAddOp4(v, OP_MakeRecord, regTabname, 3, regTemp, "aaa", 0);
82855     sqlite3VdbeAddOp2(v, OP_NewRowid, iStatCur, regNewRowid);
82856     sqlite3VdbeAddOp3(v, OP_Insert, iStatCur, regTemp, regNewRowid);
82857     sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
82858     sqlite3VdbeJumpHere(v, jZeroRows);
82859   }
82860 }
82861 
82862 
82863 /*
82864 ** Generate code that will cause the most recent index analysis to
82865 ** be loaded into internal hash tables where is can be used.
82866 */
82867 static void loadAnalysis(Parse *pParse, int iDb){
82868   Vdbe *v = sqlite3GetVdbe(pParse);
82869   if( v ){
82870     sqlite3VdbeAddOp1(v, OP_LoadAnalysis, iDb);
82871   }
82872 }
82873 
82874 /*
82875 ** Generate code that will do an analysis of an entire database
82876 */
82877 static void analyzeDatabase(Parse *pParse, int iDb){
82878   sqlite3 *db = pParse->db;
82879   Schema *pSchema = db->aDb[iDb].pSchema;    /* Schema of database iDb */
82880   HashElem *k;
82881   int iStatCur;
82882   int iMem;
82883   int iTab;
82884 
82885   sqlite3BeginWriteOperation(pParse, 0, iDb);
82886   iStatCur = pParse->nTab;
82887   pParse->nTab += 3;
82888   openStatTable(pParse, iDb, iStatCur, 0, 0);
82889   iMem = pParse->nMem+1;
82890   iTab = pParse->nTab;
82891   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
82892   for(k=sqliteHashFirst(&pSchema->tblHash); k; k=sqliteHashNext(k)){
82893     Table *pTab = (Table*)sqliteHashData(k);
82894     analyzeOneTable(pParse, pTab, 0, iStatCur, iMem, iTab);
82895   }
82896   loadAnalysis(pParse, iDb);
82897 }
82898 
82899 /*
82900 ** Generate code that will do an analysis of a single table in
82901 ** a database.  If pOnlyIdx is not NULL then it is a single index
82902 ** in pTab that should be analyzed.
82903 */
82904 static void analyzeTable(Parse *pParse, Table *pTab, Index *pOnlyIdx){
82905   int iDb;
82906   int iStatCur;
82907 
82908   assert( pTab!=0 );
82909   assert( sqlite3BtreeHoldsAllMutexes(pParse->db) );
82910   iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
82911   sqlite3BeginWriteOperation(pParse, 0, iDb);
82912   iStatCur = pParse->nTab;
82913   pParse->nTab += 3;
82914   if( pOnlyIdx ){
82915     openStatTable(pParse, iDb, iStatCur, pOnlyIdx->zName, "idx");
82916   }else{
82917     openStatTable(pParse, iDb, iStatCur, pTab->zName, "tbl");
82918   }
82919   analyzeOneTable(pParse, pTab, pOnlyIdx, iStatCur,pParse->nMem+1,pParse->nTab);
82920   loadAnalysis(pParse, iDb);
82921 }
82922 
82923 /*
82924 ** Generate code for the ANALYZE command.  The parser calls this routine
82925 ** when it recognizes an ANALYZE command.
82926 **
82927 **        ANALYZE                            -- 1
82928 **        ANALYZE  <database>                -- 2
82929 **        ANALYZE  ?<database>.?<tablename>  -- 3
82930 **
82931 ** Form 1 causes all indices in all attached databases to be analyzed.
82932 ** Form 2 analyzes all indices the single database named.
82933 ** Form 3 analyzes all indices associated with the named table.
82934 */
82935 SQLITE_PRIVATE void sqlite3Analyze(Parse *pParse, Token *pName1, Token *pName2){
82936   sqlite3 *db = pParse->db;
82937   int iDb;
82938   int i;
82939   char *z, *zDb;
82940   Table *pTab;
82941   Index *pIdx;
82942   Token *pTableName;
82943 
82944   /* Read the database schema. If an error occurs, leave an error message
82945   ** and code in pParse and return NULL. */
82946   assert( sqlite3BtreeHoldsAllMutexes(pParse->db) );
82947   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
82948     return;
82949   }
82950 
82951   assert( pName2!=0 || pName1==0 );
82952   if( pName1==0 ){
82953     /* Form 1:  Analyze everything */
82954     for(i=0; i<db->nDb; i++){
82955       if( i==1 ) continue;  /* Do not analyze the TEMP database */
82956       analyzeDatabase(pParse, i);
82957     }
82958   }else if( pName2->n==0 ){
82959     /* Form 2:  Analyze the database or table named */
82960     iDb = sqlite3FindDb(db, pName1);
82961     if( iDb>=0 ){
82962       analyzeDatabase(pParse, iDb);
82963     }else{
82964       z = sqlite3NameFromToken(db, pName1);
82965       if( z ){
82966         if( (pIdx = sqlite3FindIndex(db, z, 0))!=0 ){
82967           analyzeTable(pParse, pIdx->pTable, pIdx);
82968         }else if( (pTab = sqlite3LocateTable(pParse, 0, z, 0))!=0 ){
82969           analyzeTable(pParse, pTab, 0);
82970         }
82971         sqlite3DbFree(db, z);
82972       }
82973     }
82974   }else{
82975     /* Form 3: Analyze the fully qualified table name */
82976     iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pTableName);
82977     if( iDb>=0 ){
82978       zDb = db->aDb[iDb].zName;
82979       z = sqlite3NameFromToken(db, pTableName);
82980       if( z ){
82981         if( (pIdx = sqlite3FindIndex(db, z, zDb))!=0 ){
82982           analyzeTable(pParse, pIdx->pTable, pIdx);
82983         }else if( (pTab = sqlite3LocateTable(pParse, 0, z, zDb))!=0 ){
82984           analyzeTable(pParse, pTab, 0);
82985         }
82986         sqlite3DbFree(db, z);
82987       }
82988     }   
82989   }
82990 }
82991 
82992 /*
82993 ** Used to pass information from the analyzer reader through to the
82994 ** callback routine.
82995 */
82996 typedef struct analysisInfo analysisInfo;
82997 struct analysisInfo {
82998   sqlite3 *db;
82999   const char *zDatabase;
83000 };
83001 
83002 /*
83003 ** The first argument points to a nul-terminated string containing a
83004 ** list of space separated integers. Read the first nOut of these into
83005 ** the array aOut[].
83006 */
83007 static void decodeIntArray(
83008   char *zIntArray,       /* String containing int array to decode */
83009   int nOut,              /* Number of slots in aOut[] */
83010   tRowcnt *aOut,         /* Store integers here */
83011   Index *pIndex          /* Handle extra flags for this index, if not NULL */
83012 ){
83013   char *z = zIntArray;
83014   int c;
83015   int i;
83016   tRowcnt v;
83017 
83018 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
83019   if( z==0 ) z = "";
83020 #else
83021   if( NEVER(z==0) ) z = "";
83022 #endif
83023   for(i=0; *z && i<nOut; i++){
83024     v = 0;
83025     while( (c=z[0])>='0' && c<='9' ){
83026       v = v*10 + c - '0';
83027       z++;
83028     }
83029     aOut[i] = v;
83030     if( *z==' ' ) z++;
83031   }
83032 #ifndef SQLITE_ENABLE_STAT3_OR_STAT4
83033   assert( pIndex!=0 );
83034 #else
83035   if( pIndex )
83036 #endif
83037   {
83038     if( strcmp(z, "unordered")==0 ){
83039       pIndex->bUnordered = 1;
83040     }else if( sqlite3_strglob("sz=[0-9]*", z)==0 ){
83041       int v32 = 0;
83042       sqlite3GetInt32(z+3, &v32);
83043       pIndex->szIdxRow = sqlite3LogEst(v32);
83044     }
83045   }
83046 }
83047 
83048 /*
83049 ** This callback is invoked once for each index when reading the
83050 ** sqlite_stat1 table.  
83051 **
83052 **     argv[0] = name of the table
83053 **     argv[1] = name of the index (might be NULL)
83054 **     argv[2] = results of analysis - on integer for each column
83055 **
83056 ** Entries for which argv[1]==NULL simply record the number of rows in
83057 ** the table.
83058 */
83059 static int analysisLoader(void *pData, int argc, char **argv, char **NotUsed){
83060   analysisInfo *pInfo = (analysisInfo*)pData;
83061   Index *pIndex;
83062   Table *pTable;
83063   const char *z;
83064 
83065   assert( argc==3 );
83066   UNUSED_PARAMETER2(NotUsed, argc);
83067 
83068   if( argv==0 || argv[0]==0 || argv[2]==0 ){
83069     return 0;
83070   }
83071   pTable = sqlite3FindTable(pInfo->db, argv[0], pInfo->zDatabase);
83072   if( pTable==0 ){
83073     return 0;
83074   }
83075   if( argv[1]==0 ){
83076     pIndex = 0;
83077   }else if( sqlite3_stricmp(argv[0],argv[1])==0 ){
83078     pIndex = sqlite3PrimaryKeyIndex(pTable);
83079   }else{
83080     pIndex = sqlite3FindIndex(pInfo->db, argv[1], pInfo->zDatabase);
83081   }
83082   z = argv[2];
83083 
83084   if( pIndex ){
83085     decodeIntArray((char*)z, pIndex->nKeyCol+1, pIndex->aiRowEst, pIndex);
83086     if( pIndex->pPartIdxWhere==0 ) pTable->nRowEst = pIndex->aiRowEst[0];
83087   }else{
83088     Index fakeIdx;
83089     fakeIdx.szIdxRow = pTable->szTabRow;
83090     decodeIntArray((char*)z, 1, &pTable->nRowEst, &fakeIdx);
83091     pTable->szTabRow = fakeIdx.szIdxRow;
83092   }
83093 
83094   return 0;
83095 }
83096 
83097 /*
83098 ** If the Index.aSample variable is not NULL, delete the aSample[] array
83099 ** and its contents.
83100 */
83101 SQLITE_PRIVATE void sqlite3DeleteIndexSamples(sqlite3 *db, Index *pIdx){
83102 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
83103   if( pIdx->aSample ){
83104     int j;
83105     for(j=0; j<pIdx->nSample; j++){
83106       IndexSample *p = &pIdx->aSample[j];
83107       sqlite3DbFree(db, p->p);
83108     }
83109     sqlite3DbFree(db, pIdx->aSample);
83110   }
83111   if( db && db->pnBytesFreed==0 ){
83112     pIdx->nSample = 0;
83113     pIdx->aSample = 0;
83114   }
83115 #else
83116   UNUSED_PARAMETER(db);
83117   UNUSED_PARAMETER(pIdx);
83118 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
83119 }
83120 
83121 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
83122 /*
83123 ** Populate the pIdx->aAvgEq[] array based on the samples currently
83124 ** stored in pIdx->aSample[]. 
83125 */
83126 static void initAvgEq(Index *pIdx){
83127   if( pIdx ){
83128     IndexSample *aSample = pIdx->aSample;
83129     IndexSample *pFinal = &aSample[pIdx->nSample-1];
83130     int iCol;
83131     for(iCol=0; iCol<pIdx->nKeyCol; iCol++){
83132       int i;                    /* Used to iterate through samples */
83133       tRowcnt sumEq = 0;        /* Sum of the nEq values */
83134       tRowcnt nSum = 0;         /* Number of terms contributing to sumEq */
83135       tRowcnt avgEq = 0;
83136       tRowcnt nDLt = pFinal->anDLt[iCol];
83137 
83138       /* Set nSum to the number of distinct (iCol+1) field prefixes that
83139       ** occur in the stat4 table for this index before pFinal. Set
83140       ** sumEq to the sum of the nEq values for column iCol for the same
83141       ** set (adding the value only once where there exist dupicate 
83142       ** prefixes).  */
83143       for(i=0; i<(pIdx->nSample-1); i++){
83144         if( aSample[i].anDLt[iCol]!=aSample[i+1].anDLt[iCol] ){
83145           sumEq += aSample[i].anEq[iCol];
83146           nSum++;
83147         }
83148       }
83149       if( nDLt>nSum ){
83150         avgEq = (pFinal->anLt[iCol] - sumEq)/(nDLt - nSum);
83151       }
83152       if( avgEq==0 ) avgEq = 1;
83153       pIdx->aAvgEq[iCol] = avgEq;
83154       if( pIdx->nSampleCol==1 ) break;
83155     }
83156   }
83157 }
83158 
83159 /*
83160 ** Look up an index by name.  Or, if the name of a WITHOUT ROWID table
83161 ** is supplied instead, find the PRIMARY KEY index for that table.
83162 */
83163 static Index *findIndexOrPrimaryKey(
83164   sqlite3 *db,
83165   const char *zName,
83166   const char *zDb
83167 ){
83168   Index *pIdx = sqlite3FindIndex(db, zName, zDb);
83169   if( pIdx==0 ){
83170     Table *pTab = sqlite3FindTable(db, zName, zDb);
83171     if( pTab && !HasRowid(pTab) ) pIdx = sqlite3PrimaryKeyIndex(pTab);
83172   }
83173   return pIdx;
83174 }
83175 
83176 /*
83177 ** Load the content from either the sqlite_stat4 or sqlite_stat3 table 
83178 ** into the relevant Index.aSample[] arrays.
83179 **
83180 ** Arguments zSql1 and zSql2 must point to SQL statements that return
83181 ** data equivalent to the following (statements are different for stat3,
83182 ** see the caller of this function for details):
83183 **
83184 **    zSql1: SELECT idx,count(*) FROM %Q.sqlite_stat4 GROUP BY idx
83185 **    zSql2: SELECT idx,neq,nlt,ndlt,sample FROM %Q.sqlite_stat4
83186 **
83187 ** where %Q is replaced with the database name before the SQL is executed.
83188 */
83189 static int loadStatTbl(
83190   sqlite3 *db,                  /* Database handle */
83191   int bStat3,                   /* Assume single column records only */
83192   const char *zSql1,            /* SQL statement 1 (see above) */
83193   const char *zSql2,            /* SQL statement 2 (see above) */
83194   const char *zDb               /* Database name (e.g. "main") */
83195 ){
83196   int rc;                       /* Result codes from subroutines */
83197   sqlite3_stmt *pStmt = 0;      /* An SQL statement being run */
83198   char *zSql;                   /* Text of the SQL statement */
83199   Index *pPrevIdx = 0;          /* Previous index in the loop */
83200   IndexSample *pSample;         /* A slot in pIdx->aSample[] */
83201 
83202   assert( db->lookaside.bEnabled==0 );
83203   zSql = sqlite3MPrintf(db, zSql1, zDb);
83204   if( !zSql ){
83205     return SQLITE_NOMEM;
83206   }
83207   rc = sqlite3_prepare(db, zSql, -1, &pStmt, 0);
83208   sqlite3DbFree(db, zSql);
83209   if( rc ) return rc;
83210 
83211   while( sqlite3_step(pStmt)==SQLITE_ROW ){
83212     int nIdxCol = 1;              /* Number of columns in stat4 records */
83213     int nAvgCol = 1;              /* Number of entries in Index.aAvgEq */
83214 
83215     char *zIndex;   /* Index name */
83216     Index *pIdx;    /* Pointer to the index object */
83217     int nSample;    /* Number of samples */
83218     int nByte;      /* Bytes of space required */
83219     int i;          /* Bytes of space required */
83220     tRowcnt *pSpace;
83221 
83222     zIndex = (char *)sqlite3_column_text(pStmt, 0);
83223     if( zIndex==0 ) continue;
83224     nSample = sqlite3_column_int(pStmt, 1);
83225     pIdx = findIndexOrPrimaryKey(db, zIndex, zDb);
83226     assert( pIdx==0 || bStat3 || pIdx->nSample==0 );
83227     /* Index.nSample is non-zero at this point if data has already been
83228     ** loaded from the stat4 table. In this case ignore stat3 data.  */
83229     if( pIdx==0 || pIdx->nSample ) continue;
83230     if( bStat3==0 ){
83231       nIdxCol = pIdx->nKeyCol+1;
83232       nAvgCol = pIdx->nKeyCol;
83233     }
83234     pIdx->nSampleCol = nIdxCol;
83235     nByte = sizeof(IndexSample) * nSample;
83236     nByte += sizeof(tRowcnt) * nIdxCol * 3 * nSample;
83237     nByte += nAvgCol * sizeof(tRowcnt);     /* Space for Index.aAvgEq[] */
83238 
83239     pIdx->aSample = sqlite3DbMallocZero(db, nByte);
83240     if( pIdx->aSample==0 ){
83241       sqlite3_finalize(pStmt);
83242       return SQLITE_NOMEM;
83243     }
83244     pSpace = (tRowcnt*)&pIdx->aSample[nSample];
83245     pIdx->aAvgEq = pSpace; pSpace += nAvgCol;
83246     for(i=0; i<nSample; i++){
83247       pIdx->aSample[i].anEq = pSpace; pSpace += nIdxCol;
83248       pIdx->aSample[i].anLt = pSpace; pSpace += nIdxCol;
83249       pIdx->aSample[i].anDLt = pSpace; pSpace += nIdxCol;
83250     }
83251     assert( ((u8*)pSpace)-nByte==(u8*)(pIdx->aSample) );
83252   }
83253   rc = sqlite3_finalize(pStmt);
83254   if( rc ) return rc;
83255 
83256   zSql = sqlite3MPrintf(db, zSql2, zDb);
83257   if( !zSql ){
83258     return SQLITE_NOMEM;
83259   }
83260   rc = sqlite3_prepare(db, zSql, -1, &pStmt, 0);
83261   sqlite3DbFree(db, zSql);
83262   if( rc ) return rc;
83263 
83264   while( sqlite3_step(pStmt)==SQLITE_ROW ){
83265     char *zIndex;                 /* Index name */
83266     Index *pIdx;                  /* Pointer to the index object */
83267     int nCol = 1;                 /* Number of columns in index */
83268 
83269     zIndex = (char *)sqlite3_column_text(pStmt, 0);
83270     if( zIndex==0 ) continue;
83271     pIdx = findIndexOrPrimaryKey(db, zIndex, zDb);
83272     if( pIdx==0 ) continue;
83273     /* This next condition is true if data has already been loaded from 
83274     ** the sqlite_stat4 table. In this case ignore stat3 data.  */
83275     nCol = pIdx->nSampleCol;
83276     if( bStat3 && nCol>1 ) continue;
83277     if( pIdx!=pPrevIdx ){
83278       initAvgEq(pPrevIdx);
83279       pPrevIdx = pIdx;
83280     }
83281     pSample = &pIdx->aSample[pIdx->nSample];
83282     decodeIntArray((char*)sqlite3_column_text(pStmt,1), nCol, pSample->anEq, 0);
83283     decodeIntArray((char*)sqlite3_column_text(pStmt,2), nCol, pSample->anLt, 0);
83284     decodeIntArray((char*)sqlite3_column_text(pStmt,3), nCol, pSample->anDLt,0);
83285 
83286     /* Take a copy of the sample. Add two 0x00 bytes the end of the buffer.
83287     ** This is in case the sample record is corrupted. In that case, the
83288     ** sqlite3VdbeRecordCompare() may read up to two varints past the
83289     ** end of the allocated buffer before it realizes it is dealing with
83290     ** a corrupt record. Adding the two 0x00 bytes prevents this from causing
83291     ** a buffer overread.  */
83292     pSample->n = sqlite3_column_bytes(pStmt, 4);
83293     pSample->p = sqlite3DbMallocZero(db, pSample->n + 2);
83294     if( pSample->p==0 ){
83295       sqlite3_finalize(pStmt);
83296       return SQLITE_NOMEM;
83297     }
83298     memcpy(pSample->p, sqlite3_column_blob(pStmt, 4), pSample->n);
83299     pIdx->nSample++;
83300   }
83301   rc = sqlite3_finalize(pStmt);
83302   if( rc==SQLITE_OK ) initAvgEq(pPrevIdx);
83303   return rc;
83304 }
83305 
83306 /*
83307 ** Load content from the sqlite_stat4 and sqlite_stat3 tables into 
83308 ** the Index.aSample[] arrays of all indices.
83309 */
83310 static int loadStat4(sqlite3 *db, const char *zDb){
83311   int rc = SQLITE_OK;             /* Result codes from subroutines */
83312 
83313   assert( db->lookaside.bEnabled==0 );
83314   if( sqlite3FindTable(db, "sqlite_stat4", zDb) ){
83315     rc = loadStatTbl(db, 0,
83316       "SELECT idx,count(*) FROM %Q.sqlite_stat4 GROUP BY idx", 
83317       "SELECT idx,neq,nlt,ndlt,sample FROM %Q.sqlite_stat4",
83318       zDb
83319     );
83320   }
83321 
83322   if( rc==SQLITE_OK && sqlite3FindTable(db, "sqlite_stat3", zDb) ){
83323     rc = loadStatTbl(db, 1,
83324       "SELECT idx,count(*) FROM %Q.sqlite_stat3 GROUP BY idx", 
83325       "SELECT idx,neq,nlt,ndlt,sqlite_record(sample) FROM %Q.sqlite_stat3",
83326       zDb
83327     );
83328   }
83329 
83330   return rc;
83331 }
83332 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
83333 
83334 /*
83335 ** Load the content of the sqlite_stat1 and sqlite_stat3/4 tables. The
83336 ** contents of sqlite_stat1 are used to populate the Index.aiRowEst[]
83337 ** arrays. The contents of sqlite_stat3/4 are used to populate the
83338 ** Index.aSample[] arrays.
83339 **
83340 ** If the sqlite_stat1 table is not present in the database, SQLITE_ERROR
83341 ** is returned. In this case, even if SQLITE_ENABLE_STAT3/4 was defined 
83342 ** during compilation and the sqlite_stat3/4 table is present, no data is 
83343 ** read from it.
83344 **
83345 ** If SQLITE_ENABLE_STAT3/4 was defined during compilation and the 
83346 ** sqlite_stat4 table is not present in the database, SQLITE_ERROR is
83347 ** returned. However, in this case, data is read from the sqlite_stat1
83348 ** table (if it is present) before returning.
83349 **
83350 ** If an OOM error occurs, this function always sets db->mallocFailed.
83351 ** This means if the caller does not care about other errors, the return
83352 ** code may be ignored.
83353 */
83354 SQLITE_PRIVATE int sqlite3AnalysisLoad(sqlite3 *db, int iDb){
83355   analysisInfo sInfo;
83356   HashElem *i;
83357   char *zSql;
83358   int rc;
83359 
83360   assert( iDb>=0 && iDb<db->nDb );
83361   assert( db->aDb[iDb].pBt!=0 );
83362 
83363   /* Clear any prior statistics */
83364   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
83365   for(i=sqliteHashFirst(&db->aDb[iDb].pSchema->idxHash);i;i=sqliteHashNext(i)){
83366     Index *pIdx = sqliteHashData(i);
83367     sqlite3DefaultRowEst(pIdx);
83368 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
83369     sqlite3DeleteIndexSamples(db, pIdx);
83370     pIdx->aSample = 0;
83371 #endif
83372   }
83373 
83374   /* Check to make sure the sqlite_stat1 table exists */
83375   sInfo.db = db;
83376   sInfo.zDatabase = db->aDb[iDb].zName;
83377   if( sqlite3FindTable(db, "sqlite_stat1", sInfo.zDatabase)==0 ){
83378     return SQLITE_ERROR;
83379   }
83380 
83381   /* Load new statistics out of the sqlite_stat1 table */
83382   zSql = sqlite3MPrintf(db, 
83383       "SELECT tbl,idx,stat FROM %Q.sqlite_stat1", sInfo.zDatabase);
83384   if( zSql==0 ){
83385     rc = SQLITE_NOMEM;
83386   }else{
83387     rc = sqlite3_exec(db, zSql, analysisLoader, &sInfo, 0);
83388     sqlite3DbFree(db, zSql);
83389   }
83390 
83391 
83392   /* Load the statistics from the sqlite_stat4 table. */
83393 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
83394   if( rc==SQLITE_OK ){
83395     int lookasideEnabled = db->lookaside.bEnabled;
83396     db->lookaside.bEnabled = 0;
83397     rc = loadStat4(db, sInfo.zDatabase);
83398     db->lookaside.bEnabled = lookasideEnabled;
83399   }
83400 #endif
83401 
83402   if( rc==SQLITE_NOMEM ){
83403     db->mallocFailed = 1;
83404   }
83405   return rc;
83406 }
83407 
83408 
83409 #endif /* SQLITE_OMIT_ANALYZE */
83410 
83411 /************** End of analyze.c *********************************************/
83412 /************** Begin file attach.c ******************************************/
83413 /*
83414 ** 2003 April 6
83415 **
83416 ** The author disclaims copyright to this source code.  In place of
83417 ** a legal notice, here is a blessing:
83418 **
83419 **    May you do good and not evil.
83420 **    May you find forgiveness for yourself and forgive others.
83421 **    May you share freely, never taking more than you give.
83422 **
83423 *************************************************************************
83424 ** This file contains code used to implement the ATTACH and DETACH commands.
83425 */
83426 
83427 #ifndef SQLITE_OMIT_ATTACH
83428 /*
83429 ** Resolve an expression that was part of an ATTACH or DETACH statement. This
83430 ** is slightly different from resolving a normal SQL expression, because simple
83431 ** identifiers are treated as strings, not possible column names or aliases.
83432 **
83433 ** i.e. if the parser sees:
83434 **
83435 **     ATTACH DATABASE abc AS def
83436 **
83437 ** it treats the two expressions as literal strings 'abc' and 'def' instead of
83438 ** looking for columns of the same name.
83439 **
83440 ** This only applies to the root node of pExpr, so the statement:
83441 **
83442 **     ATTACH DATABASE abc||def AS 'db2'
83443 **
83444 ** will fail because neither abc or def can be resolved.
83445 */
83446 static int resolveAttachExpr(NameContext *pName, Expr *pExpr)
83447 {
83448   int rc = SQLITE_OK;
83449   if( pExpr ){
83450     if( pExpr->op!=TK_ID ){
83451       rc = sqlite3ResolveExprNames(pName, pExpr);
83452       if( rc==SQLITE_OK && !sqlite3ExprIsConstant(pExpr) ){
83453         sqlite3ErrorMsg(pName->pParse, "invalid name: \"%s\"", pExpr->u.zToken);
83454         return SQLITE_ERROR;
83455       }
83456     }else{
83457       pExpr->op = TK_STRING;
83458     }
83459   }
83460   return rc;
83461 }
83462 
83463 /*
83464 ** An SQL user-function registered to do the work of an ATTACH statement. The
83465 ** three arguments to the function come directly from an attach statement:
83466 **
83467 **     ATTACH DATABASE x AS y KEY z
83468 **
83469 **     SELECT sqlite_attach(x, y, z)
83470 **
83471 ** If the optional "KEY z" syntax is omitted, an SQL NULL is passed as the
83472 ** third argument.
83473 */
83474 static void attachFunc(
83475   sqlite3_context *context,
83476   int NotUsed,
83477   sqlite3_value **argv
83478 ){
83479   int i;
83480   int rc = 0;
83481   sqlite3 *db = sqlite3_context_db_handle(context);
83482   const char *zName;
83483   const char *zFile;
83484   char *zPath = 0;
83485   char *zErr = 0;
83486   unsigned int flags;
83487   Db *aNew;
83488   char *zErrDyn = 0;
83489   sqlite3_vfs *pVfs;
83490 
83491   UNUSED_PARAMETER(NotUsed);
83492 
83493   zFile = (const char *)sqlite3_value_text(argv[0]);
83494   zName = (const char *)sqlite3_value_text(argv[1]);
83495   if( zFile==0 ) zFile = "";
83496   if( zName==0 ) zName = "";
83497 
83498   /* Check for the following errors:
83499   **
83500   **     * Too many attached databases,
83501   **     * Transaction currently open
83502   **     * Specified database name already being used.
83503   */
83504   if( db->nDb>=db->aLimit[SQLITE_LIMIT_ATTACHED]+2 ){
83505     zErrDyn = sqlite3MPrintf(db, "too many attached databases - max %d", 
83506       db->aLimit[SQLITE_LIMIT_ATTACHED]
83507     );
83508     goto attach_error;
83509   }
83510   if( !db->autoCommit ){
83511     zErrDyn = sqlite3MPrintf(db, "cannot ATTACH database within transaction");
83512     goto attach_error;
83513   }
83514   for(i=0; i<db->nDb; i++){
83515     char *z = db->aDb[i].zName;
83516     assert( z && zName );
83517     if( sqlite3StrICmp(z, zName)==0 ){
83518       zErrDyn = sqlite3MPrintf(db, "database %s is already in use", zName);
83519       goto attach_error;
83520     }
83521   }
83522 
83523   /* Allocate the new entry in the db->aDb[] array and initialize the schema
83524   ** hash tables.
83525   */
83526   if( db->aDb==db->aDbStatic ){
83527     aNew = sqlite3DbMallocRaw(db, sizeof(db->aDb[0])*3 );
83528     if( aNew==0 ) return;
83529     memcpy(aNew, db->aDb, sizeof(db->aDb[0])*2);
83530   }else{
83531     aNew = sqlite3DbRealloc(db, db->aDb, sizeof(db->aDb[0])*(db->nDb+1) );
83532     if( aNew==0 ) return;
83533   }
83534   db->aDb = aNew;
83535   aNew = &db->aDb[db->nDb];
83536   memset(aNew, 0, sizeof(*aNew));
83537 
83538   /* Open the database file. If the btree is successfully opened, use
83539   ** it to obtain the database schema. At this point the schema may
83540   ** or may not be initialized.
83541   */
83542   flags = db->openFlags;
83543   rc = sqlite3ParseUri(db->pVfs->zName, zFile, &flags, &pVfs, &zPath, &zErr);
83544   if( rc!=SQLITE_OK ){
83545     if( rc==SQLITE_NOMEM ) db->mallocFailed = 1;
83546     sqlite3_result_error(context, zErr, -1);
83547     sqlite3_free(zErr);
83548     return;
83549   }
83550   assert( pVfs );
83551   flags |= SQLITE_OPEN_MAIN_DB;
83552   rc = sqlite3BtreeOpen(pVfs, zPath, db, &aNew->pBt, 0, flags);
83553   sqlite3_free( zPath );
83554   db->nDb++;
83555   if( rc==SQLITE_CONSTRAINT ){
83556     rc = SQLITE_ERROR;
83557     zErrDyn = sqlite3MPrintf(db, "database is already attached");
83558   }else if( rc==SQLITE_OK ){
83559     Pager *pPager;
83560     aNew->pSchema = sqlite3SchemaGet(db, aNew->pBt);
83561     if( !aNew->pSchema ){
83562       rc = SQLITE_NOMEM;
83563     }else if( aNew->pSchema->file_format && aNew->pSchema->enc!=ENC(db) ){
83564       zErrDyn = sqlite3MPrintf(db, 
83565         "attached databases must use the same text encoding as main database");
83566       rc = SQLITE_ERROR;
83567     }
83568     pPager = sqlite3BtreePager(aNew->pBt);
83569     sqlite3PagerLockingMode(pPager, db->dfltLockMode);
83570     sqlite3BtreeSecureDelete(aNew->pBt,
83571                              sqlite3BtreeSecureDelete(db->aDb[0].pBt,-1) );
83572 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
83573     sqlite3BtreeSetPagerFlags(aNew->pBt, 3 | (db->flags & PAGER_FLAGS_MASK));
83574 #endif
83575   }
83576   aNew->safety_level = 3;
83577   aNew->zName = sqlite3DbStrDup(db, zName);
83578   if( rc==SQLITE_OK && aNew->zName==0 ){
83579     rc = SQLITE_NOMEM;
83580   }
83581 
83582 
83583 #ifdef SQLITE_HAS_CODEC
83584   if( rc==SQLITE_OK ){
83585     extern int sqlite3CodecAttach(sqlite3*, int, const void*, int);
83586     extern void sqlite3CodecGetKey(sqlite3*, int, void**, int*);
83587     int nKey;
83588     char *zKey;
83589     int t = sqlite3_value_type(argv[2]);
83590     switch( t ){
83591       case SQLITE_INTEGER:
83592       case SQLITE_FLOAT:
83593         zErrDyn = sqlite3DbStrDup(db, "Invalid key value");
83594         rc = SQLITE_ERROR;
83595         break;
83596         
83597       case SQLITE_TEXT:
83598       case SQLITE_BLOB:
83599         nKey = sqlite3_value_bytes(argv[2]);
83600         zKey = (char *)sqlite3_value_blob(argv[2]);
83601         rc = sqlite3CodecAttach(db, db->nDb-1, zKey, nKey);
83602         break;
83603 
83604       case SQLITE_NULL:
83605         /* No key specified.  Use the key from the main database */
83606         sqlite3CodecGetKey(db, 0, (void**)&zKey, &nKey);
83607         if( nKey>0 || sqlite3BtreeGetReserve(db->aDb[0].pBt)>0 ){
83608           rc = sqlite3CodecAttach(db, db->nDb-1, zKey, nKey);
83609         }
83610         break;
83611     }
83612   }
83613 #endif
83614 
83615   /* If the file was opened successfully, read the schema for the new database.
83616   ** If this fails, or if opening the file failed, then close the file and 
83617   ** remove the entry from the db->aDb[] array. i.e. put everything back the way
83618   ** we found it.
83619   */
83620   if( rc==SQLITE_OK ){
83621     sqlite3BtreeEnterAll(db);
83622     rc = sqlite3Init(db, &zErrDyn);
83623     sqlite3BtreeLeaveAll(db);
83624   }
83625   if( rc ){
83626     int iDb = db->nDb - 1;
83627     assert( iDb>=2 );
83628     if( db->aDb[iDb].pBt ){
83629       sqlite3BtreeClose(db->aDb[iDb].pBt);
83630       db->aDb[iDb].pBt = 0;
83631       db->aDb[iDb].pSchema = 0;
83632     }
83633     sqlite3ResetAllSchemasOfConnection(db);
83634     db->nDb = iDb;
83635     if( rc==SQLITE_NOMEM || rc==SQLITE_IOERR_NOMEM ){
83636       db->mallocFailed = 1;
83637       sqlite3DbFree(db, zErrDyn);
83638       zErrDyn = sqlite3MPrintf(db, "out of memory");
83639     }else if( zErrDyn==0 ){
83640       zErrDyn = sqlite3MPrintf(db, "unable to open database: %s", zFile);
83641     }
83642     goto attach_error;
83643   }
83644   
83645   return;
83646 
83647 attach_error:
83648   /* Return an error if we get here */
83649   if( zErrDyn ){
83650     sqlite3_result_error(context, zErrDyn, -1);
83651     sqlite3DbFree(db, zErrDyn);
83652   }
83653   if( rc ) sqlite3_result_error_code(context, rc);
83654 }
83655 
83656 /*
83657 ** An SQL user-function registered to do the work of an DETACH statement. The
83658 ** three arguments to the function come directly from a detach statement:
83659 **
83660 **     DETACH DATABASE x
83661 **
83662 **     SELECT sqlite_detach(x)
83663 */
83664 static void detachFunc(
83665   sqlite3_context *context,
83666   int NotUsed,
83667   sqlite3_value **argv
83668 ){
83669   const char *zName = (const char *)sqlite3_value_text(argv[0]);
83670   sqlite3 *db = sqlite3_context_db_handle(context);
83671   int i;
83672   Db *pDb = 0;
83673   char zErr[128];
83674 
83675   UNUSED_PARAMETER(NotUsed);
83676 
83677   if( zName==0 ) zName = "";
83678   for(i=0; i<db->nDb; i++){
83679     pDb = &db->aDb[i];
83680     if( pDb->pBt==0 ) continue;
83681     if( sqlite3StrICmp(pDb->zName, zName)==0 ) break;
83682   }
83683 
83684   if( i>=db->nDb ){
83685     sqlite3_snprintf(sizeof(zErr),zErr, "no such database: %s", zName);
83686     goto detach_error;
83687   }
83688   if( i<2 ){
83689     sqlite3_snprintf(sizeof(zErr),zErr, "cannot detach database %s", zName);
83690     goto detach_error;
83691   }
83692   if( !db->autoCommit ){
83693     sqlite3_snprintf(sizeof(zErr), zErr,
83694                      "cannot DETACH database within transaction");
83695     goto detach_error;
83696   }
83697   if( sqlite3BtreeIsInReadTrans(pDb->pBt) || sqlite3BtreeIsInBackup(pDb->pBt) ){
83698     sqlite3_snprintf(sizeof(zErr),zErr, "database %s is locked", zName);
83699     goto detach_error;
83700   }
83701 
83702   sqlite3BtreeClose(pDb->pBt);
83703   pDb->pBt = 0;
83704   pDb->pSchema = 0;
83705   sqlite3ResetAllSchemasOfConnection(db);
83706   return;
83707 
83708 detach_error:
83709   sqlite3_result_error(context, zErr, -1);
83710 }
83711 
83712 /*
83713 ** This procedure generates VDBE code for a single invocation of either the
83714 ** sqlite_detach() or sqlite_attach() SQL user functions.
83715 */
83716 static void codeAttach(
83717   Parse *pParse,       /* The parser context */
83718   int type,            /* Either SQLITE_ATTACH or SQLITE_DETACH */
83719   FuncDef const *pFunc,/* FuncDef wrapper for detachFunc() or attachFunc() */
83720   Expr *pAuthArg,      /* Expression to pass to authorization callback */
83721   Expr *pFilename,     /* Name of database file */
83722   Expr *pDbname,       /* Name of the database to use internally */
83723   Expr *pKey           /* Database key for encryption extension */
83724 ){
83725   int rc;
83726   NameContext sName;
83727   Vdbe *v;
83728   sqlite3* db = pParse->db;
83729   int regArgs;
83730 
83731   memset(&sName, 0, sizeof(NameContext));
83732   sName.pParse = pParse;
83733 
83734   if( 
83735       SQLITE_OK!=(rc = resolveAttachExpr(&sName, pFilename)) ||
83736       SQLITE_OK!=(rc = resolveAttachExpr(&sName, pDbname)) ||
83737       SQLITE_OK!=(rc = resolveAttachExpr(&sName, pKey))
83738   ){
83739     pParse->nErr++;
83740     goto attach_end;
83741   }
83742 
83743 #ifndef SQLITE_OMIT_AUTHORIZATION
83744   if( pAuthArg ){
83745     char *zAuthArg;
83746     if( pAuthArg->op==TK_STRING ){
83747       zAuthArg = pAuthArg->u.zToken;
83748     }else{
83749       zAuthArg = 0;
83750     }
83751     rc = sqlite3AuthCheck(pParse, type, zAuthArg, 0, 0);
83752     if(rc!=SQLITE_OK ){
83753       goto attach_end;
83754     }
83755   }
83756 #endif /* SQLITE_OMIT_AUTHORIZATION */
83757 
83758 
83759   v = sqlite3GetVdbe(pParse);
83760   regArgs = sqlite3GetTempRange(pParse, 4);
83761   sqlite3ExprCode(pParse, pFilename, regArgs);
83762   sqlite3ExprCode(pParse, pDbname, regArgs+1);
83763   sqlite3ExprCode(pParse, pKey, regArgs+2);
83764 
83765   assert( v || db->mallocFailed );
83766   if( v ){
83767     sqlite3VdbeAddOp3(v, OP_Function, 0, regArgs+3-pFunc->nArg, regArgs+3);
83768     assert( pFunc->nArg==-1 || (pFunc->nArg&0xff)==pFunc->nArg );
83769     sqlite3VdbeChangeP5(v, (u8)(pFunc->nArg));
83770     sqlite3VdbeChangeP4(v, -1, (char *)pFunc, P4_FUNCDEF);
83771 
83772     /* Code an OP_Expire. For an ATTACH statement, set P1 to true (expire this
83773     ** statement only). For DETACH, set it to false (expire all existing
83774     ** statements).
83775     */
83776     sqlite3VdbeAddOp1(v, OP_Expire, (type==SQLITE_ATTACH));
83777   }
83778   
83779 attach_end:
83780   sqlite3ExprDelete(db, pFilename);
83781   sqlite3ExprDelete(db, pDbname);
83782   sqlite3ExprDelete(db, pKey);
83783 }
83784 
83785 /*
83786 ** Called by the parser to compile a DETACH statement.
83787 **
83788 **     DETACH pDbname
83789 */
83790 SQLITE_PRIVATE void sqlite3Detach(Parse *pParse, Expr *pDbname){
83791   static const FuncDef detach_func = {
83792     1,                /* nArg */
83793     SQLITE_UTF8,      /* funcFlags */
83794     0,                /* pUserData */
83795     0,                /* pNext */
83796     detachFunc,       /* xFunc */
83797     0,                /* xStep */
83798     0,                /* xFinalize */
83799     "sqlite_detach",  /* zName */
83800     0,                /* pHash */
83801     0                 /* pDestructor */
83802   };
83803   codeAttach(pParse, SQLITE_DETACH, &detach_func, pDbname, 0, 0, pDbname);
83804 }
83805 
83806 /*
83807 ** Called by the parser to compile an ATTACH statement.
83808 **
83809 **     ATTACH p AS pDbname KEY pKey
83810 */
83811 SQLITE_PRIVATE void sqlite3Attach(Parse *pParse, Expr *p, Expr *pDbname, Expr *pKey){
83812   static const FuncDef attach_func = {
83813     3,                /* nArg */
83814     SQLITE_UTF8,      /* funcFlags */
83815     0,                /* pUserData */
83816     0,                /* pNext */
83817     attachFunc,       /* xFunc */
83818     0,                /* xStep */
83819     0,                /* xFinalize */
83820     "sqlite_attach",  /* zName */
83821     0,                /* pHash */
83822     0                 /* pDestructor */
83823   };
83824   codeAttach(pParse, SQLITE_ATTACH, &attach_func, p, p, pDbname, pKey);
83825 }
83826 #endif /* SQLITE_OMIT_ATTACH */
83827 
83828 /*
83829 ** Initialize a DbFixer structure.  This routine must be called prior
83830 ** to passing the structure to one of the sqliteFixAAAA() routines below.
83831 */
83832 SQLITE_PRIVATE void sqlite3FixInit(
83833   DbFixer *pFix,      /* The fixer to be initialized */
83834   Parse *pParse,      /* Error messages will be written here */
83835   int iDb,            /* This is the database that must be used */
83836   const char *zType,  /* "view", "trigger", or "index" */
83837   const Token *pName  /* Name of the view, trigger, or index */
83838 ){
83839   sqlite3 *db;
83840 
83841   db = pParse->db;
83842   assert( db->nDb>iDb );
83843   pFix->pParse = pParse;
83844   pFix->zDb = db->aDb[iDb].zName;
83845   pFix->pSchema = db->aDb[iDb].pSchema;
83846   pFix->zType = zType;
83847   pFix->pName = pName;
83848   pFix->bVarOnly = (iDb==1);
83849 }
83850 
83851 /*
83852 ** The following set of routines walk through the parse tree and assign
83853 ** a specific database to all table references where the database name
83854 ** was left unspecified in the original SQL statement.  The pFix structure
83855 ** must have been initialized by a prior call to sqlite3FixInit().
83856 **
83857 ** These routines are used to make sure that an index, trigger, or
83858 ** view in one database does not refer to objects in a different database.
83859 ** (Exception: indices, triggers, and views in the TEMP database are
83860 ** allowed to refer to anything.)  If a reference is explicitly made
83861 ** to an object in a different database, an error message is added to
83862 ** pParse->zErrMsg and these routines return non-zero.  If everything
83863 ** checks out, these routines return 0.
83864 */
83865 SQLITE_PRIVATE int sqlite3FixSrcList(
83866   DbFixer *pFix,       /* Context of the fixation */
83867   SrcList *pList       /* The Source list to check and modify */
83868 ){
83869   int i;
83870   const char *zDb;
83871   struct SrcList_item *pItem;
83872 
83873   if( NEVER(pList==0) ) return 0;
83874   zDb = pFix->zDb;
83875   for(i=0, pItem=pList->a; i<pList->nSrc; i++, pItem++){
83876     if( pFix->bVarOnly==0 ){
83877       if( pItem->zDatabase && sqlite3StrICmp(pItem->zDatabase, zDb) ){
83878         sqlite3ErrorMsg(pFix->pParse,
83879             "%s %T cannot reference objects in database %s",
83880             pFix->zType, pFix->pName, pItem->zDatabase);
83881         return 1;
83882       }
83883       sqlite3DbFree(pFix->pParse->db, pItem->zDatabase);
83884       pItem->zDatabase = 0;
83885       pItem->pSchema = pFix->pSchema;
83886     }
83887 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_TRIGGER)
83888     if( sqlite3FixSelect(pFix, pItem->pSelect) ) return 1;
83889     if( sqlite3FixExpr(pFix, pItem->pOn) ) return 1;
83890 #endif
83891   }
83892   return 0;
83893 }
83894 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_TRIGGER)
83895 SQLITE_PRIVATE int sqlite3FixSelect(
83896   DbFixer *pFix,       /* Context of the fixation */
83897   Select *pSelect      /* The SELECT statement to be fixed to one database */
83898 ){
83899   while( pSelect ){
83900     if( sqlite3FixExprList(pFix, pSelect->pEList) ){
83901       return 1;
83902     }
83903     if( sqlite3FixSrcList(pFix, pSelect->pSrc) ){
83904       return 1;
83905     }
83906     if( sqlite3FixExpr(pFix, pSelect->pWhere) ){
83907       return 1;
83908     }
83909     if( sqlite3FixExprList(pFix, pSelect->pGroupBy) ){
83910       return 1;
83911     }
83912     if( sqlite3FixExpr(pFix, pSelect->pHaving) ){
83913       return 1;
83914     }
83915     if( sqlite3FixExprList(pFix, pSelect->pOrderBy) ){
83916       return 1;
83917     }
83918     if( sqlite3FixExpr(pFix, pSelect->pLimit) ){
83919       return 1;
83920     }
83921     if( sqlite3FixExpr(pFix, pSelect->pOffset) ){
83922       return 1;
83923     }
83924     pSelect = pSelect->pPrior;
83925   }
83926   return 0;
83927 }
83928 SQLITE_PRIVATE int sqlite3FixExpr(
83929   DbFixer *pFix,     /* Context of the fixation */
83930   Expr *pExpr        /* The expression to be fixed to one database */
83931 ){
83932   while( pExpr ){
83933     if( pExpr->op==TK_VARIABLE ){
83934       if( pFix->pParse->db->init.busy ){
83935         pExpr->op = TK_NULL;
83936       }else{
83937         sqlite3ErrorMsg(pFix->pParse, "%s cannot use variables", pFix->zType);
83938         return 1;
83939       }
83940     }
83941     if( ExprHasProperty(pExpr, EP_TokenOnly) ) break;
83942     if( ExprHasProperty(pExpr, EP_xIsSelect) ){
83943       if( sqlite3FixSelect(pFix, pExpr->x.pSelect) ) return 1;
83944     }else{
83945       if( sqlite3FixExprList(pFix, pExpr->x.pList) ) return 1;
83946     }
83947     if( sqlite3FixExpr(pFix, pExpr->pRight) ){
83948       return 1;
83949     }
83950     pExpr = pExpr->pLeft;
83951   }
83952   return 0;
83953 }
83954 SQLITE_PRIVATE int sqlite3FixExprList(
83955   DbFixer *pFix,     /* Context of the fixation */
83956   ExprList *pList    /* The expression to be fixed to one database */
83957 ){
83958   int i;
83959   struct ExprList_item *pItem;
83960   if( pList==0 ) return 0;
83961   for(i=0, pItem=pList->a; i<pList->nExpr; i++, pItem++){
83962     if( sqlite3FixExpr(pFix, pItem->pExpr) ){
83963       return 1;
83964     }
83965   }
83966   return 0;
83967 }
83968 #endif
83969 
83970 #ifndef SQLITE_OMIT_TRIGGER
83971 SQLITE_PRIVATE int sqlite3FixTriggerStep(
83972   DbFixer *pFix,     /* Context of the fixation */
83973   TriggerStep *pStep /* The trigger step be fixed to one database */
83974 ){
83975   while( pStep ){
83976     if( sqlite3FixSelect(pFix, pStep->pSelect) ){
83977       return 1;
83978     }
83979     if( sqlite3FixExpr(pFix, pStep->pWhere) ){
83980       return 1;
83981     }
83982     if( sqlite3FixExprList(pFix, pStep->pExprList) ){
83983       return 1;
83984     }
83985     pStep = pStep->pNext;
83986   }
83987   return 0;
83988 }
83989 #endif
83990 
83991 /************** End of attach.c **********************************************/
83992 /************** Begin file auth.c ********************************************/
83993 /*
83994 ** 2003 January 11
83995 **
83996 ** The author disclaims copyright to this source code.  In place of
83997 ** a legal notice, here is a blessing:
83998 **
83999 **    May you do good and not evil.
84000 **    May you find forgiveness for yourself and forgive others.
84001 **    May you share freely, never taking more than you give.
84002 **
84003 *************************************************************************
84004 ** This file contains code used to implement the sqlite3_set_authorizer()
84005 ** API.  This facility is an optional feature of the library.  Embedded
84006 ** systems that do not need this facility may omit it by recompiling
84007 ** the library with -DSQLITE_OMIT_AUTHORIZATION=1
84008 */
84009 
84010 /*
84011 ** All of the code in this file may be omitted by defining a single
84012 ** macro.
84013 */
84014 #ifndef SQLITE_OMIT_AUTHORIZATION
84015 
84016 /*
84017 ** Set or clear the access authorization function.
84018 **
84019 ** The access authorization function is be called during the compilation
84020 ** phase to verify that the user has read and/or write access permission on
84021 ** various fields of the database.  The first argument to the auth function
84022 ** is a copy of the 3rd argument to this routine.  The second argument
84023 ** to the auth function is one of these constants:
84024 **
84025 **       SQLITE_CREATE_INDEX
84026 **       SQLITE_CREATE_TABLE
84027 **       SQLITE_CREATE_TEMP_INDEX
84028 **       SQLITE_CREATE_TEMP_TABLE
84029 **       SQLITE_CREATE_TEMP_TRIGGER
84030 **       SQLITE_CREATE_TEMP_VIEW
84031 **       SQLITE_CREATE_TRIGGER
84032 **       SQLITE_CREATE_VIEW
84033 **       SQLITE_DELETE
84034 **       SQLITE_DROP_INDEX
84035 **       SQLITE_DROP_TABLE
84036 **       SQLITE_DROP_TEMP_INDEX
84037 **       SQLITE_DROP_TEMP_TABLE
84038 **       SQLITE_DROP_TEMP_TRIGGER
84039 **       SQLITE_DROP_TEMP_VIEW
84040 **       SQLITE_DROP_TRIGGER
84041 **       SQLITE_DROP_VIEW
84042 **       SQLITE_INSERT
84043 **       SQLITE_PRAGMA
84044 **       SQLITE_READ
84045 **       SQLITE_SELECT
84046 **       SQLITE_TRANSACTION
84047 **       SQLITE_UPDATE
84048 **
84049 ** The third and fourth arguments to the auth function are the name of
84050 ** the table and the column that are being accessed.  The auth function
84051 ** should return either SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE.  If
84052 ** SQLITE_OK is returned, it means that access is allowed.  SQLITE_DENY
84053 ** means that the SQL statement will never-run - the sqlite3_exec() call
84054 ** will return with an error.  SQLITE_IGNORE means that the SQL statement
84055 ** should run but attempts to read the specified column will return NULL
84056 ** and attempts to write the column will be ignored.
84057 **
84058 ** Setting the auth function to NULL disables this hook.  The default
84059 ** setting of the auth function is NULL.
84060 */
84061 SQLITE_API int sqlite3_set_authorizer(
84062   sqlite3 *db,
84063   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
84064   void *pArg
84065 ){
84066   sqlite3_mutex_enter(db->mutex);
84067   db->xAuth = xAuth;
84068   db->pAuthArg = pArg;
84069   sqlite3ExpirePreparedStatements(db);
84070   sqlite3_mutex_leave(db->mutex);
84071   return SQLITE_OK;
84072 }
84073 
84074 /*
84075 ** Write an error message into pParse->zErrMsg that explains that the
84076 ** user-supplied authorization function returned an illegal value.
84077 */
84078 static void sqliteAuthBadReturnCode(Parse *pParse){
84079   sqlite3ErrorMsg(pParse, "authorizer malfunction");
84080   pParse->rc = SQLITE_ERROR;
84081 }
84082 
84083 /*
84084 ** Invoke the authorization callback for permission to read column zCol from
84085 ** table zTab in database zDb. This function assumes that an authorization
84086 ** callback has been registered (i.e. that sqlite3.xAuth is not NULL).
84087 **
84088 ** If SQLITE_IGNORE is returned and pExpr is not NULL, then pExpr is changed
84089 ** to an SQL NULL expression. Otherwise, if pExpr is NULL, then SQLITE_IGNORE
84090 ** is treated as SQLITE_DENY. In this case an error is left in pParse.
84091 */
84092 SQLITE_PRIVATE int sqlite3AuthReadCol(
84093   Parse *pParse,                  /* The parser context */
84094   const char *zTab,               /* Table name */
84095   const char *zCol,               /* Column name */
84096   int iDb                         /* Index of containing database. */
84097 ){
84098   sqlite3 *db = pParse->db;       /* Database handle */
84099   char *zDb = db->aDb[iDb].zName; /* Name of attached database */
84100   int rc;                         /* Auth callback return code */
84101 
84102   rc = db->xAuth(db->pAuthArg, SQLITE_READ, zTab,zCol,zDb,pParse->zAuthContext);
84103   if( rc==SQLITE_DENY ){
84104     if( db->nDb>2 || iDb!=0 ){
84105       sqlite3ErrorMsg(pParse, "access to %s.%s.%s is prohibited",zDb,zTab,zCol);
84106     }else{
84107       sqlite3ErrorMsg(pParse, "access to %s.%s is prohibited", zTab, zCol);
84108     }
84109     pParse->rc = SQLITE_AUTH;
84110   }else if( rc!=SQLITE_IGNORE && rc!=SQLITE_OK ){
84111     sqliteAuthBadReturnCode(pParse);
84112   }
84113   return rc;
84114 }
84115 
84116 /*
84117 ** The pExpr should be a TK_COLUMN expression.  The table referred to
84118 ** is in pTabList or else it is the NEW or OLD table of a trigger.  
84119 ** Check to see if it is OK to read this particular column.
84120 **
84121 ** If the auth function returns SQLITE_IGNORE, change the TK_COLUMN 
84122 ** instruction into a TK_NULL.  If the auth function returns SQLITE_DENY,
84123 ** then generate an error.
84124 */
84125 SQLITE_PRIVATE void sqlite3AuthRead(
84126   Parse *pParse,        /* The parser context */
84127   Expr *pExpr,          /* The expression to check authorization on */
84128   Schema *pSchema,      /* The schema of the expression */
84129   SrcList *pTabList     /* All table that pExpr might refer to */
84130 ){
84131   sqlite3 *db = pParse->db;
84132   Table *pTab = 0;      /* The table being read */
84133   const char *zCol;     /* Name of the column of the table */
84134   int iSrc;             /* Index in pTabList->a[] of table being read */
84135   int iDb;              /* The index of the database the expression refers to */
84136   int iCol;             /* Index of column in table */
84137 
84138   if( db->xAuth==0 ) return;
84139   iDb = sqlite3SchemaToIndex(pParse->db, pSchema);
84140   if( iDb<0 ){
84141     /* An attempt to read a column out of a subquery or other
84142     ** temporary table. */
84143     return;
84144   }
84145 
84146   assert( pExpr->op==TK_COLUMN || pExpr->op==TK_TRIGGER );
84147   if( pExpr->op==TK_TRIGGER ){
84148     pTab = pParse->pTriggerTab;
84149   }else{
84150     assert( pTabList );
84151     for(iSrc=0; ALWAYS(iSrc<pTabList->nSrc); iSrc++){
84152       if( pExpr->iTable==pTabList->a[iSrc].iCursor ){
84153         pTab = pTabList->a[iSrc].pTab;
84154         break;
84155       }
84156     }
84157   }
84158   iCol = pExpr->iColumn;
84159   if( NEVER(pTab==0) ) return;
84160 
84161   if( iCol>=0 ){
84162     assert( iCol<pTab->nCol );
84163     zCol = pTab->aCol[iCol].zName;
84164   }else if( pTab->iPKey>=0 ){
84165     assert( pTab->iPKey<pTab->nCol );
84166     zCol = pTab->aCol[pTab->iPKey].zName;
84167   }else{
84168     zCol = "ROWID";
84169   }
84170   assert( iDb>=0 && iDb<db->nDb );
84171   if( SQLITE_IGNORE==sqlite3AuthReadCol(pParse, pTab->zName, zCol, iDb) ){
84172     pExpr->op = TK_NULL;
84173   }
84174 }
84175 
84176 /*
84177 ** Do an authorization check using the code and arguments given.  Return
84178 ** either SQLITE_OK (zero) or SQLITE_IGNORE or SQLITE_DENY.  If SQLITE_DENY
84179 ** is returned, then the error count and error message in pParse are
84180 ** modified appropriately.
84181 */
84182 SQLITE_PRIVATE int sqlite3AuthCheck(
84183   Parse *pParse,
84184   int code,
84185   const char *zArg1,
84186   const char *zArg2,
84187   const char *zArg3
84188 ){
84189   sqlite3 *db = pParse->db;
84190   int rc;
84191 
84192   /* Don't do any authorization checks if the database is initialising
84193   ** or if the parser is being invoked from within sqlite3_declare_vtab.
84194   */
84195   if( db->init.busy || IN_DECLARE_VTAB ){
84196     return SQLITE_OK;
84197   }
84198 
84199   if( db->xAuth==0 ){
84200     return SQLITE_OK;
84201   }
84202   rc = db->xAuth(db->pAuthArg, code, zArg1, zArg2, zArg3, pParse->zAuthContext);
84203   if( rc==SQLITE_DENY ){
84204     sqlite3ErrorMsg(pParse, "not authorized");
84205     pParse->rc = SQLITE_AUTH;
84206   }else if( rc!=SQLITE_OK && rc!=SQLITE_IGNORE ){
84207     rc = SQLITE_DENY;
84208     sqliteAuthBadReturnCode(pParse);
84209   }
84210   return rc;
84211 }
84212 
84213 /*
84214 ** Push an authorization context.  After this routine is called, the
84215 ** zArg3 argument to authorization callbacks will be zContext until
84216 ** popped.  Or if pParse==0, this routine is a no-op.
84217 */
84218 SQLITE_PRIVATE void sqlite3AuthContextPush(
84219   Parse *pParse,
84220   AuthContext *pContext, 
84221   const char *zContext
84222 ){
84223   assert( pParse );
84224   pContext->pParse = pParse;
84225   pContext->zAuthContext = pParse->zAuthContext;
84226   pParse->zAuthContext = zContext;
84227 }
84228 
84229 /*
84230 ** Pop an authorization context that was previously pushed
84231 ** by sqlite3AuthContextPush
84232 */
84233 SQLITE_PRIVATE void sqlite3AuthContextPop(AuthContext *pContext){
84234   if( pContext->pParse ){
84235     pContext->pParse->zAuthContext = pContext->zAuthContext;
84236     pContext->pParse = 0;
84237   }
84238 }
84239 
84240 #endif /* SQLITE_OMIT_AUTHORIZATION */
84241 
84242 /************** End of auth.c ************************************************/
84243 /************** Begin file build.c *******************************************/
84244 /*
84245 ** 2001 September 15
84246 **
84247 ** The author disclaims copyright to this source code.  In place of
84248 ** a legal notice, here is a blessing:
84249 **
84250 **    May you do good and not evil.
84251 **    May you find forgiveness for yourself and forgive others.
84252 **    May you share freely, never taking more than you give.
84253 **
84254 *************************************************************************
84255 ** This file contains C code routines that are called by the SQLite parser
84256 ** when syntax rules are reduced.  The routines in this file handle the
84257 ** following kinds of SQL syntax:
84258 **
84259 **     CREATE TABLE
84260 **     DROP TABLE
84261 **     CREATE INDEX
84262 **     DROP INDEX
84263 **     creating ID lists
84264 **     BEGIN TRANSACTION
84265 **     COMMIT
84266 **     ROLLBACK
84267 */
84268 
84269 /*
84270 ** This routine is called when a new SQL statement is beginning to
84271 ** be parsed.  Initialize the pParse structure as needed.
84272 */
84273 SQLITE_PRIVATE void sqlite3BeginParse(Parse *pParse, int explainFlag){
84274   pParse->explain = (u8)explainFlag;
84275   pParse->nVar = 0;
84276 }
84277 
84278 #ifndef SQLITE_OMIT_SHARED_CACHE
84279 /*
84280 ** The TableLock structure is only used by the sqlite3TableLock() and
84281 ** codeTableLocks() functions.
84282 */
84283 struct TableLock {
84284   int iDb;             /* The database containing the table to be locked */
84285   int iTab;            /* The root page of the table to be locked */
84286   u8 isWriteLock;      /* True for write lock.  False for a read lock */
84287   const char *zName;   /* Name of the table */
84288 };
84289 
84290 /*
84291 ** Record the fact that we want to lock a table at run-time.  
84292 **
84293 ** The table to be locked has root page iTab and is found in database iDb.
84294 ** A read or a write lock can be taken depending on isWritelock.
84295 **
84296 ** This routine just records the fact that the lock is desired.  The
84297 ** code to make the lock occur is generated by a later call to
84298 ** codeTableLocks() which occurs during sqlite3FinishCoding().
84299 */
84300 SQLITE_PRIVATE void sqlite3TableLock(
84301   Parse *pParse,     /* Parsing context */
84302   int iDb,           /* Index of the database containing the table to lock */
84303   int iTab,          /* Root page number of the table to be locked */
84304   u8 isWriteLock,    /* True for a write lock */
84305   const char *zName  /* Name of the table to be locked */
84306 ){
84307   Parse *pToplevel = sqlite3ParseToplevel(pParse);
84308   int i;
84309   int nBytes;
84310   TableLock *p;
84311   assert( iDb>=0 );
84312 
84313   for(i=0; i<pToplevel->nTableLock; i++){
84314     p = &pToplevel->aTableLock[i];
84315     if( p->iDb==iDb && p->iTab==iTab ){
84316       p->isWriteLock = (p->isWriteLock || isWriteLock);
84317       return;
84318     }
84319   }
84320 
84321   nBytes = sizeof(TableLock) * (pToplevel->nTableLock+1);
84322   pToplevel->aTableLock =
84323       sqlite3DbReallocOrFree(pToplevel->db, pToplevel->aTableLock, nBytes);
84324   if( pToplevel->aTableLock ){
84325     p = &pToplevel->aTableLock[pToplevel->nTableLock++];
84326     p->iDb = iDb;
84327     p->iTab = iTab;
84328     p->isWriteLock = isWriteLock;
84329     p->zName = zName;
84330   }else{
84331     pToplevel->nTableLock = 0;
84332     pToplevel->db->mallocFailed = 1;
84333   }
84334 }
84335 
84336 /*
84337 ** Code an OP_TableLock instruction for each table locked by the
84338 ** statement (configured by calls to sqlite3TableLock()).
84339 */
84340 static void codeTableLocks(Parse *pParse){
84341   int i;
84342   Vdbe *pVdbe; 
84343 
84344   pVdbe = sqlite3GetVdbe(pParse);
84345   assert( pVdbe!=0 ); /* sqlite3GetVdbe cannot fail: VDBE already allocated */
84346 
84347   for(i=0; i<pParse->nTableLock; i++){
84348     TableLock *p = &pParse->aTableLock[i];
84349     int p1 = p->iDb;
84350     sqlite3VdbeAddOp4(pVdbe, OP_TableLock, p1, p->iTab, p->isWriteLock,
84351                       p->zName, P4_STATIC);
84352   }
84353 }
84354 #else
84355   #define codeTableLocks(x)
84356 #endif
84357 
84358 /*
84359 ** This routine is called after a single SQL statement has been
84360 ** parsed and a VDBE program to execute that statement has been
84361 ** prepared.  This routine puts the finishing touches on the
84362 ** VDBE program and resets the pParse structure for the next
84363 ** parse.
84364 **
84365 ** Note that if an error occurred, it might be the case that
84366 ** no VDBE code was generated.
84367 */
84368 SQLITE_PRIVATE void sqlite3FinishCoding(Parse *pParse){
84369   sqlite3 *db;
84370   Vdbe *v;
84371 
84372   assert( pParse->pToplevel==0 );
84373   db = pParse->db;
84374   if( db->mallocFailed ) return;
84375   if( pParse->nested ) return;
84376   if( pParse->nErr ) return;
84377 
84378   /* Begin by generating some termination code at the end of the
84379   ** vdbe program
84380   */
84381   v = sqlite3GetVdbe(pParse);
84382   assert( !pParse->isMultiWrite 
84383        || sqlite3VdbeAssertMayAbort(v, pParse->mayAbort));
84384   if( v ){
84385     sqlite3VdbeAddOp0(v, OP_Halt);
84386 
84387     /* The cookie mask contains one bit for each database file open.
84388     ** (Bit 0 is for main, bit 1 is for temp, and so forth.)  Bits are
84389     ** set for each database that is used.  Generate code to start a
84390     ** transaction on each used database and to verify the schema cookie
84391     ** on each used database.
84392     */
84393     if( pParse->cookieGoto>0 ){
84394       yDbMask mask;
84395       int iDb, i, addr;
84396       sqlite3VdbeJumpHere(v, pParse->cookieGoto-1);
84397       for(iDb=0, mask=1; iDb<db->nDb; mask<<=1, iDb++){
84398         if( (mask & pParse->cookieMask)==0 ) continue;
84399         sqlite3VdbeUsesBtree(v, iDb);
84400         sqlite3VdbeAddOp2(v,OP_Transaction, iDb, (mask & pParse->writeMask)!=0);
84401         if( db->init.busy==0 ){
84402           assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
84403           sqlite3VdbeAddOp3(v, OP_VerifyCookie,
84404                             iDb, pParse->cookieValue[iDb],
84405                             db->aDb[iDb].pSchema->iGeneration);
84406         }
84407       }
84408 #ifndef SQLITE_OMIT_VIRTUALTABLE
84409       for(i=0; i<pParse->nVtabLock; i++){
84410         char *vtab = (char *)sqlite3GetVTable(db, pParse->apVtabLock[i]);
84411         sqlite3VdbeAddOp4(v, OP_VBegin, 0, 0, 0, vtab, P4_VTAB);
84412       }
84413       pParse->nVtabLock = 0;
84414 #endif
84415 
84416       /* Once all the cookies have been verified and transactions opened, 
84417       ** obtain the required table-locks. This is a no-op unless the 
84418       ** shared-cache feature is enabled.
84419       */
84420       codeTableLocks(pParse);
84421 
84422       /* Initialize any AUTOINCREMENT data structures required.
84423       */
84424       sqlite3AutoincrementBegin(pParse);
84425 
84426       /* Code constant expressions that where factored out of inner loops */
84427       addr = pParse->cookieGoto;
84428       if( pParse->pConstExpr ){
84429         ExprList *pEL = pParse->pConstExpr;
84430         pParse->cookieGoto = 0;
84431         for(i=0; i<pEL->nExpr; i++){
84432           sqlite3ExprCode(pParse, pEL->a[i].pExpr, pEL->a[i].u.iConstExprReg);
84433         }
84434       }
84435 
84436       /* Finally, jump back to the beginning of the executable code. */
84437       sqlite3VdbeAddOp2(v, OP_Goto, 0, addr);
84438     }
84439   }
84440 
84441 
84442   /* Get the VDBE program ready for execution
84443   */
84444   if( v && ALWAYS(pParse->nErr==0) && !db->mallocFailed ){
84445     assert( pParse->iCacheLevel==0 );  /* Disables and re-enables match */
84446     /* A minimum of one cursor is required if autoincrement is used
84447     *  See ticket [a696379c1f08866] */
84448     if( pParse->pAinc!=0 && pParse->nTab==0 ) pParse->nTab = 1;
84449     sqlite3VdbeMakeReady(v, pParse);
84450     pParse->rc = SQLITE_DONE;
84451     pParse->colNamesSet = 0;
84452   }else{
84453     pParse->rc = SQLITE_ERROR;
84454   }
84455   pParse->nTab = 0;
84456   pParse->nMem = 0;
84457   pParse->nSet = 0;
84458   pParse->nVar = 0;
84459   pParse->cookieMask = 0;
84460   pParse->cookieGoto = 0;
84461 }
84462 
84463 /*
84464 ** Run the parser and code generator recursively in order to generate
84465 ** code for the SQL statement given onto the end of the pParse context
84466 ** currently under construction.  When the parser is run recursively
84467 ** this way, the final OP_Halt is not appended and other initialization
84468 ** and finalization steps are omitted because those are handling by the
84469 ** outermost parser.
84470 **
84471 ** Not everything is nestable.  This facility is designed to permit
84472 ** INSERT, UPDATE, and DELETE operations against SQLITE_MASTER.  Use
84473 ** care if you decide to try to use this routine for some other purposes.
84474 */
84475 SQLITE_PRIVATE void sqlite3NestedParse(Parse *pParse, const char *zFormat, ...){
84476   va_list ap;
84477   char *zSql;
84478   char *zErrMsg = 0;
84479   sqlite3 *db = pParse->db;
84480 # define SAVE_SZ  (sizeof(Parse) - offsetof(Parse,nVar))
84481   char saveBuf[SAVE_SZ];
84482 
84483   if( pParse->nErr ) return;
84484   assert( pParse->nested<10 );  /* Nesting should only be of limited depth */
84485   va_start(ap, zFormat);
84486   zSql = sqlite3VMPrintf(db, zFormat, ap);
84487   va_end(ap);
84488   if( zSql==0 ){
84489     return;   /* A malloc must have failed */
84490   }
84491   pParse->nested++;
84492   memcpy(saveBuf, &pParse->nVar, SAVE_SZ);
84493   memset(&pParse->nVar, 0, SAVE_SZ);
84494   sqlite3RunParser(pParse, zSql, &zErrMsg);
84495   sqlite3DbFree(db, zErrMsg);
84496   sqlite3DbFree(db, zSql);
84497   memcpy(&pParse->nVar, saveBuf, SAVE_SZ);
84498   pParse->nested--;
84499 }
84500 
84501 /*
84502 ** Locate the in-memory structure that describes a particular database
84503 ** table given the name of that table and (optionally) the name of the
84504 ** database containing the table.  Return NULL if not found.
84505 **
84506 ** If zDatabase is 0, all databases are searched for the table and the
84507 ** first matching table is returned.  (No checking for duplicate table
84508 ** names is done.)  The search order is TEMP first, then MAIN, then any
84509 ** auxiliary databases added using the ATTACH command.
84510 **
84511 ** See also sqlite3LocateTable().
84512 */
84513 SQLITE_PRIVATE Table *sqlite3FindTable(sqlite3 *db, const char *zName, const char *zDatabase){
84514   Table *p = 0;
84515   int i;
84516   int nName;
84517   assert( zName!=0 );
84518   nName = sqlite3Strlen30(zName);
84519   /* All mutexes are required for schema access.  Make sure we hold them. */
84520   assert( zDatabase!=0 || sqlite3BtreeHoldsAllMutexes(db) );
84521   for(i=OMIT_TEMPDB; i<db->nDb; i++){
84522     int j = (i<2) ? i^1 : i;   /* Search TEMP before MAIN */
84523     if( zDatabase!=0 && sqlite3StrICmp(zDatabase, db->aDb[j].zName) ) continue;
84524     assert( sqlite3SchemaMutexHeld(db, j, 0) );
84525     p = sqlite3HashFind(&db->aDb[j].pSchema->tblHash, zName, nName);
84526     if( p ) break;
84527   }
84528   return p;
84529 }
84530 
84531 /*
84532 ** Locate the in-memory structure that describes a particular database
84533 ** table given the name of that table and (optionally) the name of the
84534 ** database containing the table.  Return NULL if not found.  Also leave an
84535 ** error message in pParse->zErrMsg.
84536 **
84537 ** The difference between this routine and sqlite3FindTable() is that this
84538 ** routine leaves an error message in pParse->zErrMsg where
84539 ** sqlite3FindTable() does not.
84540 */
84541 SQLITE_PRIVATE Table *sqlite3LocateTable(
84542   Parse *pParse,         /* context in which to report errors */
84543   int isView,            /* True if looking for a VIEW rather than a TABLE */
84544   const char *zName,     /* Name of the table we are looking for */
84545   const char *zDbase     /* Name of the database.  Might be NULL */
84546 ){
84547   Table *p;
84548 
84549   /* Read the database schema. If an error occurs, leave an error message
84550   ** and code in pParse and return NULL. */
84551   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
84552     return 0;
84553   }
84554 
84555   p = sqlite3FindTable(pParse->db, zName, zDbase);
84556   if( p==0 ){
84557     const char *zMsg = isView ? "no such view" : "no such table";
84558     if( zDbase ){
84559       sqlite3ErrorMsg(pParse, "%s: %s.%s", zMsg, zDbase, zName);
84560     }else{
84561       sqlite3ErrorMsg(pParse, "%s: %s", zMsg, zName);
84562     }
84563     pParse->checkSchema = 1;
84564   }
84565   return p;
84566 }
84567 
84568 /*
84569 ** Locate the table identified by *p.
84570 **
84571 ** This is a wrapper around sqlite3LocateTable(). The difference between
84572 ** sqlite3LocateTable() and this function is that this function restricts
84573 ** the search to schema (p->pSchema) if it is not NULL. p->pSchema may be
84574 ** non-NULL if it is part of a view or trigger program definition. See
84575 ** sqlite3FixSrcList() for details.
84576 */
84577 SQLITE_PRIVATE Table *sqlite3LocateTableItem(
84578   Parse *pParse, 
84579   int isView, 
84580   struct SrcList_item *p
84581 ){
84582   const char *zDb;
84583   assert( p->pSchema==0 || p->zDatabase==0 );
84584   if( p->pSchema ){
84585     int iDb = sqlite3SchemaToIndex(pParse->db, p->pSchema);
84586     zDb = pParse->db->aDb[iDb].zName;
84587   }else{
84588     zDb = p->zDatabase;
84589   }
84590   return sqlite3LocateTable(pParse, isView, p->zName, zDb);
84591 }
84592 
84593 /*
84594 ** Locate the in-memory structure that describes 
84595 ** a particular index given the name of that index
84596 ** and the name of the database that contains the index.
84597 ** Return NULL if not found.
84598 **
84599 ** If zDatabase is 0, all databases are searched for the
84600 ** table and the first matching index is returned.  (No checking
84601 ** for duplicate index names is done.)  The search order is
84602 ** TEMP first, then MAIN, then any auxiliary databases added
84603 ** using the ATTACH command.
84604 */
84605 SQLITE_PRIVATE Index *sqlite3FindIndex(sqlite3 *db, const char *zName, const char *zDb){
84606   Index *p = 0;
84607   int i;
84608   int nName = sqlite3Strlen30(zName);
84609   /* All mutexes are required for schema access.  Make sure we hold them. */
84610   assert( zDb!=0 || sqlite3BtreeHoldsAllMutexes(db) );
84611   for(i=OMIT_TEMPDB; i<db->nDb; i++){
84612     int j = (i<2) ? i^1 : i;  /* Search TEMP before MAIN */
84613     Schema *pSchema = db->aDb[j].pSchema;
84614     assert( pSchema );
84615     if( zDb && sqlite3StrICmp(zDb, db->aDb[j].zName) ) continue;
84616     assert( sqlite3SchemaMutexHeld(db, j, 0) );
84617     p = sqlite3HashFind(&pSchema->idxHash, zName, nName);
84618     if( p ) break;
84619   }
84620   return p;
84621 }
84622 
84623 /*
84624 ** Reclaim the memory used by an index
84625 */
84626 static void freeIndex(sqlite3 *db, Index *p){
84627 #ifndef SQLITE_OMIT_ANALYZE
84628   sqlite3DeleteIndexSamples(db, p);
84629 #endif
84630   if( db==0 || db->pnBytesFreed==0 ) sqlite3KeyInfoUnref(p->pKeyInfo);
84631   sqlite3ExprDelete(db, p->pPartIdxWhere);
84632   sqlite3DbFree(db, p->zColAff);
84633   if( p->isResized ) sqlite3DbFree(db, p->azColl);
84634   sqlite3DbFree(db, p);
84635 }
84636 
84637 /*
84638 ** For the index called zIdxName which is found in the database iDb,
84639 ** unlike that index from its Table then remove the index from
84640 ** the index hash table and free all memory structures associated
84641 ** with the index.
84642 */
84643 SQLITE_PRIVATE void sqlite3UnlinkAndDeleteIndex(sqlite3 *db, int iDb, const char *zIdxName){
84644   Index *pIndex;
84645   int len;
84646   Hash *pHash;
84647 
84648   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
84649   pHash = &db->aDb[iDb].pSchema->idxHash;
84650   len = sqlite3Strlen30(zIdxName);
84651   pIndex = sqlite3HashInsert(pHash, zIdxName, len, 0);
84652   if( ALWAYS(pIndex) ){
84653     if( pIndex->pTable->pIndex==pIndex ){
84654       pIndex->pTable->pIndex = pIndex->pNext;
84655     }else{
84656       Index *p;
84657       /* Justification of ALWAYS();  The index must be on the list of
84658       ** indices. */
84659       p = pIndex->pTable->pIndex;
84660       while( ALWAYS(p) && p->pNext!=pIndex ){ p = p->pNext; }
84661       if( ALWAYS(p && p->pNext==pIndex) ){
84662         p->pNext = pIndex->pNext;
84663       }
84664     }
84665     freeIndex(db, pIndex);
84666   }
84667   db->flags |= SQLITE_InternChanges;
84668 }
84669 
84670 /*
84671 ** Look through the list of open database files in db->aDb[] and if
84672 ** any have been closed, remove them from the list.  Reallocate the
84673 ** db->aDb[] structure to a smaller size, if possible.
84674 **
84675 ** Entry 0 (the "main" database) and entry 1 (the "temp" database)
84676 ** are never candidates for being collapsed.
84677 */
84678 SQLITE_PRIVATE void sqlite3CollapseDatabaseArray(sqlite3 *db){
84679   int i, j;
84680   for(i=j=2; i<db->nDb; i++){
84681     struct Db *pDb = &db->aDb[i];
84682     if( pDb->pBt==0 ){
84683       sqlite3DbFree(db, pDb->zName);
84684       pDb->zName = 0;
84685       continue;
84686     }
84687     if( j<i ){
84688       db->aDb[j] = db->aDb[i];
84689     }
84690     j++;
84691   }
84692   memset(&db->aDb[j], 0, (db->nDb-j)*sizeof(db->aDb[j]));
84693   db->nDb = j;
84694   if( db->nDb<=2 && db->aDb!=db->aDbStatic ){
84695     memcpy(db->aDbStatic, db->aDb, 2*sizeof(db->aDb[0]));
84696     sqlite3DbFree(db, db->aDb);
84697     db->aDb = db->aDbStatic;
84698   }
84699 }
84700 
84701 /*
84702 ** Reset the schema for the database at index iDb.  Also reset the
84703 ** TEMP schema.
84704 */
84705 SQLITE_PRIVATE void sqlite3ResetOneSchema(sqlite3 *db, int iDb){
84706   Db *pDb;
84707   assert( iDb<db->nDb );
84708 
84709   /* Case 1:  Reset the single schema identified by iDb */
84710   pDb = &db->aDb[iDb];
84711   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
84712   assert( pDb->pSchema!=0 );
84713   sqlite3SchemaClear(pDb->pSchema);
84714 
84715   /* If any database other than TEMP is reset, then also reset TEMP
84716   ** since TEMP might be holding triggers that reference tables in the
84717   ** other database.
84718   */
84719   if( iDb!=1 ){
84720     pDb = &db->aDb[1];
84721     assert( pDb->pSchema!=0 );
84722     sqlite3SchemaClear(pDb->pSchema);
84723   }
84724   return;
84725 }
84726 
84727 /*
84728 ** Erase all schema information from all attached databases (including
84729 ** "main" and "temp") for a single database connection.
84730 */
84731 SQLITE_PRIVATE void sqlite3ResetAllSchemasOfConnection(sqlite3 *db){
84732   int i;
84733   sqlite3BtreeEnterAll(db);
84734   for(i=0; i<db->nDb; i++){
84735     Db *pDb = &db->aDb[i];
84736     if( pDb->pSchema ){
84737       sqlite3SchemaClear(pDb->pSchema);
84738     }
84739   }
84740   db->flags &= ~SQLITE_InternChanges;
84741   sqlite3VtabUnlockList(db);
84742   sqlite3BtreeLeaveAll(db);
84743   sqlite3CollapseDatabaseArray(db);
84744 }
84745 
84746 /*
84747 ** This routine is called when a commit occurs.
84748 */
84749 SQLITE_PRIVATE void sqlite3CommitInternalChanges(sqlite3 *db){
84750   db->flags &= ~SQLITE_InternChanges;
84751 }
84752 
84753 /*
84754 ** Delete memory allocated for the column names of a table or view (the
84755 ** Table.aCol[] array).
84756 */
84757 static void sqliteDeleteColumnNames(sqlite3 *db, Table *pTable){
84758   int i;
84759   Column *pCol;
84760   assert( pTable!=0 );
84761   if( (pCol = pTable->aCol)!=0 ){
84762     for(i=0; i<pTable->nCol; i++, pCol++){
84763       sqlite3DbFree(db, pCol->zName);
84764       sqlite3ExprDelete(db, pCol->pDflt);
84765       sqlite3DbFree(db, pCol->zDflt);
84766       sqlite3DbFree(db, pCol->zType);
84767       sqlite3DbFree(db, pCol->zColl);
84768     }
84769     sqlite3DbFree(db, pTable->aCol);
84770   }
84771 }
84772 
84773 /*
84774 ** Remove the memory data structures associated with the given
84775 ** Table.  No changes are made to disk by this routine.
84776 **
84777 ** This routine just deletes the data structure.  It does not unlink
84778 ** the table data structure from the hash table.  But it does destroy
84779 ** memory structures of the indices and foreign keys associated with 
84780 ** the table.
84781 **
84782 ** The db parameter is optional.  It is needed if the Table object 
84783 ** contains lookaside memory.  (Table objects in the schema do not use
84784 ** lookaside memory, but some ephemeral Table objects do.)  Or the
84785 ** db parameter can be used with db->pnBytesFreed to measure the memory
84786 ** used by the Table object.
84787 */
84788 SQLITE_PRIVATE void sqlite3DeleteTable(sqlite3 *db, Table *pTable){
84789   Index *pIndex, *pNext;
84790   TESTONLY( int nLookaside; ) /* Used to verify lookaside not used for schema */
84791 
84792   assert( !pTable || pTable->nRef>0 );
84793 
84794   /* Do not delete the table until the reference count reaches zero. */
84795   if( !pTable ) return;
84796   if( ((!db || db->pnBytesFreed==0) && (--pTable->nRef)>0) ) return;
84797 
84798   /* Record the number of outstanding lookaside allocations in schema Tables
84799   ** prior to doing any free() operations.  Since schema Tables do not use
84800   ** lookaside, this number should not change. */
84801   TESTONLY( nLookaside = (db && (pTable->tabFlags & TF_Ephemeral)==0) ?
84802                          db->lookaside.nOut : 0 );
84803 
84804   /* Delete all indices associated with this table. */
84805   for(pIndex = pTable->pIndex; pIndex; pIndex=pNext){
84806     pNext = pIndex->pNext;
84807     assert( pIndex->pSchema==pTable->pSchema );
84808     if( !db || db->pnBytesFreed==0 ){
84809       char *zName = pIndex->zName; 
84810       TESTONLY ( Index *pOld = ) sqlite3HashInsert(
84811          &pIndex->pSchema->idxHash, zName, sqlite3Strlen30(zName), 0
84812       );
84813       assert( db==0 || sqlite3SchemaMutexHeld(db, 0, pIndex->pSchema) );
84814       assert( pOld==pIndex || pOld==0 );
84815     }
84816     freeIndex(db, pIndex);
84817   }
84818 
84819   /* Delete any foreign keys attached to this table. */
84820   sqlite3FkDelete(db, pTable);
84821 
84822   /* Delete the Table structure itself.
84823   */
84824   sqliteDeleteColumnNames(db, pTable);
84825   sqlite3DbFree(db, pTable->zName);
84826   sqlite3DbFree(db, pTable->zColAff);
84827   sqlite3SelectDelete(db, pTable->pSelect);
84828 #ifndef SQLITE_OMIT_CHECK
84829   sqlite3ExprListDelete(db, pTable->pCheck);
84830 #endif
84831 #ifndef SQLITE_OMIT_VIRTUALTABLE
84832   sqlite3VtabClear(db, pTable);
84833 #endif
84834   sqlite3DbFree(db, pTable);
84835 
84836   /* Verify that no lookaside memory was used by schema tables */
84837   assert( nLookaside==0 || nLookaside==db->lookaside.nOut );
84838 }
84839 
84840 /*
84841 ** Unlink the given table from the hash tables and the delete the
84842 ** table structure with all its indices and foreign keys.
84843 */
84844 SQLITE_PRIVATE void sqlite3UnlinkAndDeleteTable(sqlite3 *db, int iDb, const char *zTabName){
84845   Table *p;
84846   Db *pDb;
84847 
84848   assert( db!=0 );
84849   assert( iDb>=0 && iDb<db->nDb );
84850   assert( zTabName );
84851   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
84852   testcase( zTabName[0]==0 );  /* Zero-length table names are allowed */
84853   pDb = &db->aDb[iDb];
84854   p = sqlite3HashInsert(&pDb->pSchema->tblHash, zTabName,
84855                         sqlite3Strlen30(zTabName),0);
84856   sqlite3DeleteTable(db, p);
84857   db->flags |= SQLITE_InternChanges;
84858 }
84859 
84860 /*
84861 ** Given a token, return a string that consists of the text of that
84862 ** token.  Space to hold the returned string
84863 ** is obtained from sqliteMalloc() and must be freed by the calling
84864 ** function.
84865 **
84866 ** Any quotation marks (ex:  "name", 'name', [name], or `name`) that
84867 ** surround the body of the token are removed.
84868 **
84869 ** Tokens are often just pointers into the original SQL text and so
84870 ** are not \000 terminated and are not persistent.  The returned string
84871 ** is \000 terminated and is persistent.
84872 */
84873 SQLITE_PRIVATE char *sqlite3NameFromToken(sqlite3 *db, Token *pName){
84874   char *zName;
84875   if( pName ){
84876     zName = sqlite3DbStrNDup(db, (char*)pName->z, pName->n);
84877     sqlite3Dequote(zName);
84878   }else{
84879     zName = 0;
84880   }
84881   return zName;
84882 }
84883 
84884 /*
84885 ** Open the sqlite_master table stored in database number iDb for
84886 ** writing. The table is opened using cursor 0.
84887 */
84888 SQLITE_PRIVATE void sqlite3OpenMasterTable(Parse *p, int iDb){
84889   Vdbe *v = sqlite3GetVdbe(p);
84890   sqlite3TableLock(p, iDb, MASTER_ROOT, 1, SCHEMA_TABLE(iDb));
84891   sqlite3VdbeAddOp4Int(v, OP_OpenWrite, 0, MASTER_ROOT, iDb, 5);
84892   if( p->nTab==0 ){
84893     p->nTab = 1;
84894   }
84895 }
84896 
84897 /*
84898 ** Parameter zName points to a nul-terminated buffer containing the name
84899 ** of a database ("main", "temp" or the name of an attached db). This
84900 ** function returns the index of the named database in db->aDb[], or
84901 ** -1 if the named db cannot be found.
84902 */
84903 SQLITE_PRIVATE int sqlite3FindDbName(sqlite3 *db, const char *zName){
84904   int i = -1;         /* Database number */
84905   if( zName ){
84906     Db *pDb;
84907     int n = sqlite3Strlen30(zName);
84908     for(i=(db->nDb-1), pDb=&db->aDb[i]; i>=0; i--, pDb--){
84909       if( (!OMIT_TEMPDB || i!=1 ) && n==sqlite3Strlen30(pDb->zName) && 
84910           0==sqlite3StrICmp(pDb->zName, zName) ){
84911         break;
84912       }
84913     }
84914   }
84915   return i;
84916 }
84917 
84918 /*
84919 ** The token *pName contains the name of a database (either "main" or
84920 ** "temp" or the name of an attached db). This routine returns the
84921 ** index of the named database in db->aDb[], or -1 if the named db 
84922 ** does not exist.
84923 */
84924 SQLITE_PRIVATE int sqlite3FindDb(sqlite3 *db, Token *pName){
84925   int i;                               /* Database number */
84926   char *zName;                         /* Name we are searching for */
84927   zName = sqlite3NameFromToken(db, pName);
84928   i = sqlite3FindDbName(db, zName);
84929   sqlite3DbFree(db, zName);
84930   return i;
84931 }
84932 
84933 /* The table or view or trigger name is passed to this routine via tokens
84934 ** pName1 and pName2. If the table name was fully qualified, for example:
84935 **
84936 ** CREATE TABLE xxx.yyy (...);
84937 ** 
84938 ** Then pName1 is set to "xxx" and pName2 "yyy". On the other hand if
84939 ** the table name is not fully qualified, i.e.:
84940 **
84941 ** CREATE TABLE yyy(...);
84942 **
84943 ** Then pName1 is set to "yyy" and pName2 is "".
84944 **
84945 ** This routine sets the *ppUnqual pointer to point at the token (pName1 or
84946 ** pName2) that stores the unqualified table name.  The index of the
84947 ** database "xxx" is returned.
84948 */
84949 SQLITE_PRIVATE int sqlite3TwoPartName(
84950   Parse *pParse,      /* Parsing and code generating context */
84951   Token *pName1,      /* The "xxx" in the name "xxx.yyy" or "xxx" */
84952   Token *pName2,      /* The "yyy" in the name "xxx.yyy" */
84953   Token **pUnqual     /* Write the unqualified object name here */
84954 ){
84955   int iDb;                    /* Database holding the object */
84956   sqlite3 *db = pParse->db;
84957 
84958   if( ALWAYS(pName2!=0) && pName2->n>0 ){
84959     if( db->init.busy ) {
84960       sqlite3ErrorMsg(pParse, "corrupt database");
84961       pParse->nErr++;
84962       return -1;
84963     }
84964     *pUnqual = pName2;
84965     iDb = sqlite3FindDb(db, pName1);
84966     if( iDb<0 ){
84967       sqlite3ErrorMsg(pParse, "unknown database %T", pName1);
84968       pParse->nErr++;
84969       return -1;
84970     }
84971   }else{
84972     assert( db->init.iDb==0 || db->init.busy );
84973     iDb = db->init.iDb;
84974     *pUnqual = pName1;
84975   }
84976   return iDb;
84977 }
84978 
84979 /*
84980 ** This routine is used to check if the UTF-8 string zName is a legal
84981 ** unqualified name for a new schema object (table, index, view or
84982 ** trigger). All names are legal except those that begin with the string
84983 ** "sqlite_" (in upper, lower or mixed case). This portion of the namespace
84984 ** is reserved for internal use.
84985 */
84986 SQLITE_PRIVATE int sqlite3CheckObjectName(Parse *pParse, const char *zName){
84987   if( !pParse->db->init.busy && pParse->nested==0 
84988           && (pParse->db->flags & SQLITE_WriteSchema)==0
84989           && 0==sqlite3StrNICmp(zName, "sqlite_", 7) ){
84990     sqlite3ErrorMsg(pParse, "object name reserved for internal use: %s", zName);
84991     return SQLITE_ERROR;
84992   }
84993   return SQLITE_OK;
84994 }
84995 
84996 /*
84997 ** Return the PRIMARY KEY index of a table
84998 */
84999 SQLITE_PRIVATE Index *sqlite3PrimaryKeyIndex(Table *pTab){
85000   Index *p;
85001   for(p=pTab->pIndex; p && p->autoIndex!=2; p=p->pNext){}
85002   return p;
85003 }
85004 
85005 /*
85006 ** Return the column of index pIdx that corresponds to table
85007 ** column iCol.  Return -1 if not found.
85008 */
85009 SQLITE_PRIVATE i16 sqlite3ColumnOfIndex(Index *pIdx, i16 iCol){
85010   int i;
85011   for(i=0; i<pIdx->nColumn; i++){
85012     if( iCol==pIdx->aiColumn[i] ) return i;
85013   }
85014   return -1;
85015 }
85016 
85017 /*
85018 ** Begin constructing a new table representation in memory.  This is
85019 ** the first of several action routines that get called in response
85020 ** to a CREATE TABLE statement.  In particular, this routine is called
85021 ** after seeing tokens "CREATE" and "TABLE" and the table name. The isTemp
85022 ** flag is true if the table should be stored in the auxiliary database
85023 ** file instead of in the main database file.  This is normally the case
85024 ** when the "TEMP" or "TEMPORARY" keyword occurs in between
85025 ** CREATE and TABLE.
85026 **
85027 ** The new table record is initialized and put in pParse->pNewTable.
85028 ** As more of the CREATE TABLE statement is parsed, additional action
85029 ** routines will be called to add more information to this record.
85030 ** At the end of the CREATE TABLE statement, the sqlite3EndTable() routine
85031 ** is called to complete the construction of the new table record.
85032 */
85033 SQLITE_PRIVATE void sqlite3StartTable(
85034   Parse *pParse,   /* Parser context */
85035   Token *pName1,   /* First part of the name of the table or view */
85036   Token *pName2,   /* Second part of the name of the table or view */
85037   int isTemp,      /* True if this is a TEMP table */
85038   int isView,      /* True if this is a VIEW */
85039   int isVirtual,   /* True if this is a VIRTUAL table */
85040   int noErr        /* Do nothing if table already exists */
85041 ){
85042   Table *pTable;
85043   char *zName = 0; /* The name of the new table */
85044   sqlite3 *db = pParse->db;
85045   Vdbe *v;
85046   int iDb;         /* Database number to create the table in */
85047   Token *pName;    /* Unqualified name of the table to create */
85048 
85049   /* The table or view name to create is passed to this routine via tokens
85050   ** pName1 and pName2. If the table name was fully qualified, for example:
85051   **
85052   ** CREATE TABLE xxx.yyy (...);
85053   ** 
85054   ** Then pName1 is set to "xxx" and pName2 "yyy". On the other hand if
85055   ** the table name is not fully qualified, i.e.:
85056   **
85057   ** CREATE TABLE yyy(...);
85058   **
85059   ** Then pName1 is set to "yyy" and pName2 is "".
85060   **
85061   ** The call below sets the pName pointer to point at the token (pName1 or
85062   ** pName2) that stores the unqualified table name. The variable iDb is
85063   ** set to the index of the database that the table or view is to be
85064   ** created in.
85065   */
85066   iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pName);
85067   if( iDb<0 ) return;
85068   if( !OMIT_TEMPDB && isTemp && pName2->n>0 && iDb!=1 ){
85069     /* If creating a temp table, the name may not be qualified. Unless 
85070     ** the database name is "temp" anyway.  */
85071     sqlite3ErrorMsg(pParse, "temporary table name must be unqualified");
85072     return;
85073   }
85074   if( !OMIT_TEMPDB && isTemp ) iDb = 1;
85075 
85076   pParse->sNameToken = *pName;
85077   zName = sqlite3NameFromToken(db, pName);
85078   if( zName==0 ) return;
85079   if( SQLITE_OK!=sqlite3CheckObjectName(pParse, zName) ){
85080     goto begin_table_error;
85081   }
85082   if( db->init.iDb==1 ) isTemp = 1;
85083 #ifndef SQLITE_OMIT_AUTHORIZATION
85084   assert( (isTemp & 1)==isTemp );
85085   {
85086     int code;
85087     char *zDb = db->aDb[iDb].zName;
85088     if( sqlite3AuthCheck(pParse, SQLITE_INSERT, SCHEMA_TABLE(isTemp), 0, zDb) ){
85089       goto begin_table_error;
85090     }
85091     if( isView ){
85092       if( !OMIT_TEMPDB && isTemp ){
85093         code = SQLITE_CREATE_TEMP_VIEW;
85094       }else{
85095         code = SQLITE_CREATE_VIEW;
85096       }
85097     }else{
85098       if( !OMIT_TEMPDB && isTemp ){
85099         code = SQLITE_CREATE_TEMP_TABLE;
85100       }else{
85101         code = SQLITE_CREATE_TABLE;
85102       }
85103     }
85104     if( !isVirtual && sqlite3AuthCheck(pParse, code, zName, 0, zDb) ){
85105       goto begin_table_error;
85106     }
85107   }
85108 #endif
85109 
85110   /* Make sure the new table name does not collide with an existing
85111   ** index or table name in the same database.  Issue an error message if
85112   ** it does. The exception is if the statement being parsed was passed
85113   ** to an sqlite3_declare_vtab() call. In that case only the column names
85114   ** and types will be used, so there is no need to test for namespace
85115   ** collisions.
85116   */
85117   if( !IN_DECLARE_VTAB ){
85118     char *zDb = db->aDb[iDb].zName;
85119     if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
85120       goto begin_table_error;
85121     }
85122     pTable = sqlite3FindTable(db, zName, zDb);
85123     if( pTable ){
85124       if( !noErr ){
85125         sqlite3ErrorMsg(pParse, "table %T already exists", pName);
85126       }else{
85127         assert( !db->init.busy );
85128         sqlite3CodeVerifySchema(pParse, iDb);
85129       }
85130       goto begin_table_error;
85131     }
85132     if( sqlite3FindIndex(db, zName, zDb)!=0 ){
85133       sqlite3ErrorMsg(pParse, "there is already an index named %s", zName);
85134       goto begin_table_error;
85135     }
85136   }
85137 
85138   pTable = sqlite3DbMallocZero(db, sizeof(Table));
85139   if( pTable==0 ){
85140     db->mallocFailed = 1;
85141     pParse->rc = SQLITE_NOMEM;
85142     pParse->nErr++;
85143     goto begin_table_error;
85144   }
85145   pTable->zName = zName;
85146   pTable->iPKey = -1;
85147   pTable->pSchema = db->aDb[iDb].pSchema;
85148   pTable->nRef = 1;
85149   pTable->nRowEst = 1048576;
85150   assert( pParse->pNewTable==0 );
85151   pParse->pNewTable = pTable;
85152 
85153   /* If this is the magic sqlite_sequence table used by autoincrement,
85154   ** then record a pointer to this table in the main database structure
85155   ** so that INSERT can find the table easily.
85156   */
85157 #ifndef SQLITE_OMIT_AUTOINCREMENT
85158   if( !pParse->nested && strcmp(zName, "sqlite_sequence")==0 ){
85159     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
85160     pTable->pSchema->pSeqTab = pTable;
85161   }
85162 #endif
85163 
85164   /* Begin generating the code that will insert the table record into
85165   ** the SQLITE_MASTER table.  Note in particular that we must go ahead
85166   ** and allocate the record number for the table entry now.  Before any
85167   ** PRIMARY KEY or UNIQUE keywords are parsed.  Those keywords will cause
85168   ** indices to be created and the table record must come before the 
85169   ** indices.  Hence, the record number for the table must be allocated
85170   ** now.
85171   */
85172   if( !db->init.busy && (v = sqlite3GetVdbe(pParse))!=0 ){
85173     int j1;
85174     int fileFormat;
85175     int reg1, reg2, reg3;
85176     sqlite3BeginWriteOperation(pParse, 0, iDb);
85177 
85178 #ifndef SQLITE_OMIT_VIRTUALTABLE
85179     if( isVirtual ){
85180       sqlite3VdbeAddOp0(v, OP_VBegin);
85181     }
85182 #endif
85183 
85184     /* If the file format and encoding in the database have not been set, 
85185     ** set them now.
85186     */
85187     reg1 = pParse->regRowid = ++pParse->nMem;
85188     reg2 = pParse->regRoot = ++pParse->nMem;
85189     reg3 = ++pParse->nMem;
85190     sqlite3VdbeAddOp3(v, OP_ReadCookie, iDb, reg3, BTREE_FILE_FORMAT);
85191     sqlite3VdbeUsesBtree(v, iDb);
85192     j1 = sqlite3VdbeAddOp1(v, OP_If, reg3);
85193     fileFormat = (db->flags & SQLITE_LegacyFileFmt)!=0 ?
85194                   1 : SQLITE_MAX_FILE_FORMAT;
85195     sqlite3VdbeAddOp2(v, OP_Integer, fileFormat, reg3);
85196     sqlite3VdbeAddOp3(v, OP_SetCookie, iDb, BTREE_FILE_FORMAT, reg3);
85197     sqlite3VdbeAddOp2(v, OP_Integer, ENC(db), reg3);
85198     sqlite3VdbeAddOp3(v, OP_SetCookie, iDb, BTREE_TEXT_ENCODING, reg3);
85199     sqlite3VdbeJumpHere(v, j1);
85200 
85201     /* This just creates a place-holder record in the sqlite_master table.
85202     ** The record created does not contain anything yet.  It will be replaced
85203     ** by the real entry in code generated at sqlite3EndTable().
85204     **
85205     ** The rowid for the new entry is left in register pParse->regRowid.
85206     ** The root page number of the new table is left in reg pParse->regRoot.
85207     ** The rowid and root page number values are needed by the code that
85208     ** sqlite3EndTable will generate.
85209     */
85210 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_VIRTUALTABLE)
85211     if( isView || isVirtual ){
85212       sqlite3VdbeAddOp2(v, OP_Integer, 0, reg2);
85213     }else
85214 #endif
85215     {
85216       pParse->addrCrTab = sqlite3VdbeAddOp2(v, OP_CreateTable, iDb, reg2);
85217     }
85218     sqlite3OpenMasterTable(pParse, iDb);
85219     sqlite3VdbeAddOp2(v, OP_NewRowid, 0, reg1);
85220     sqlite3VdbeAddOp2(v, OP_Null, 0, reg3);
85221     sqlite3VdbeAddOp3(v, OP_Insert, 0, reg3, reg1);
85222     sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
85223     sqlite3VdbeAddOp0(v, OP_Close);
85224   }
85225 
85226   /* Normal (non-error) return. */
85227   return;
85228 
85229   /* If an error occurs, we jump here */
85230 begin_table_error:
85231   sqlite3DbFree(db, zName);
85232   return;
85233 }
85234 
85235 /*
85236 ** This macro is used to compare two strings in a case-insensitive manner.
85237 ** It is slightly faster than calling sqlite3StrICmp() directly, but
85238 ** produces larger code.
85239 **
85240 ** WARNING: This macro is not compatible with the strcmp() family. It
85241 ** returns true if the two strings are equal, otherwise false.
85242 */
85243 #define STRICMP(x, y) (\
85244 sqlite3UpperToLower[*(unsigned char *)(x)]==   \
85245 sqlite3UpperToLower[*(unsigned char *)(y)]     \
85246 && sqlite3StrICmp((x)+1,(y)+1)==0 )
85247 
85248 /*
85249 ** Add a new column to the table currently being constructed.
85250 **
85251 ** The parser calls this routine once for each column declaration
85252 ** in a CREATE TABLE statement.  sqlite3StartTable() gets called
85253 ** first to get things going.  Then this routine is called for each
85254 ** column.
85255 */
85256 SQLITE_PRIVATE void sqlite3AddColumn(Parse *pParse, Token *pName){
85257   Table *p;
85258   int i;
85259   char *z;
85260   Column *pCol;
85261   sqlite3 *db = pParse->db;
85262   if( (p = pParse->pNewTable)==0 ) return;
85263 #if SQLITE_MAX_COLUMN
85264   if( p->nCol+1>db->aLimit[SQLITE_LIMIT_COLUMN] ){
85265     sqlite3ErrorMsg(pParse, "too many columns on %s", p->zName);
85266     return;
85267   }
85268 #endif
85269   z = sqlite3NameFromToken(db, pName);
85270   if( z==0 ) return;
85271   for(i=0; i<p->nCol; i++){
85272     if( STRICMP(z, p->aCol[i].zName) ){
85273       sqlite3ErrorMsg(pParse, "duplicate column name: %s", z);
85274       sqlite3DbFree(db, z);
85275       return;
85276     }
85277   }
85278   if( (p->nCol & 0x7)==0 ){
85279     Column *aNew;
85280     aNew = sqlite3DbRealloc(db,p->aCol,(p->nCol+8)*sizeof(p->aCol[0]));
85281     if( aNew==0 ){
85282       sqlite3DbFree(db, z);
85283       return;
85284     }
85285     p->aCol = aNew;
85286   }
85287   pCol = &p->aCol[p->nCol];
85288   memset(pCol, 0, sizeof(p->aCol[0]));
85289   pCol->zName = z;
85290  
85291   /* If there is no type specified, columns have the default affinity
85292   ** 'NONE'. If there is a type specified, then sqlite3AddColumnType() will
85293   ** be called next to set pCol->affinity correctly.
85294   */
85295   pCol->affinity = SQLITE_AFF_NONE;
85296   pCol->szEst = 1;
85297   p->nCol++;
85298 }
85299 
85300 /*
85301 ** This routine is called by the parser while in the middle of
85302 ** parsing a CREATE TABLE statement.  A "NOT NULL" constraint has
85303 ** been seen on a column.  This routine sets the notNull flag on
85304 ** the column currently under construction.
85305 */
85306 SQLITE_PRIVATE void sqlite3AddNotNull(Parse *pParse, int onError){
85307   Table *p;
85308   p = pParse->pNewTable;
85309   if( p==0 || NEVER(p->nCol<1) ) return;
85310   p->aCol[p->nCol-1].notNull = (u8)onError;
85311 }
85312 
85313 /*
85314 ** Scan the column type name zType (length nType) and return the
85315 ** associated affinity type.
85316 **
85317 ** This routine does a case-independent search of zType for the 
85318 ** substrings in the following table. If one of the substrings is
85319 ** found, the corresponding affinity is returned. If zType contains
85320 ** more than one of the substrings, entries toward the top of 
85321 ** the table take priority. For example, if zType is 'BLOBINT', 
85322 ** SQLITE_AFF_INTEGER is returned.
85323 **
85324 ** Substring     | Affinity
85325 ** --------------------------------
85326 ** 'INT'         | SQLITE_AFF_INTEGER
85327 ** 'CHAR'        | SQLITE_AFF_TEXT
85328 ** 'CLOB'        | SQLITE_AFF_TEXT
85329 ** 'TEXT'        | SQLITE_AFF_TEXT
85330 ** 'BLOB'        | SQLITE_AFF_NONE
85331 ** 'REAL'        | SQLITE_AFF_REAL
85332 ** 'FLOA'        | SQLITE_AFF_REAL
85333 ** 'DOUB'        | SQLITE_AFF_REAL
85334 **
85335 ** If none of the substrings in the above table are found,
85336 ** SQLITE_AFF_NUMERIC is returned.
85337 */
85338 SQLITE_PRIVATE char sqlite3AffinityType(const char *zIn, u8 *pszEst){
85339   u32 h = 0;
85340   char aff = SQLITE_AFF_NUMERIC;
85341   const char *zChar = 0;
85342 
85343   if( zIn==0 ) return aff;
85344   while( zIn[0] ){
85345     h = (h<<8) + sqlite3UpperToLower[(*zIn)&0xff];
85346     zIn++;
85347     if( h==(('c'<<24)+('h'<<16)+('a'<<8)+'r') ){             /* CHAR */
85348       aff = SQLITE_AFF_TEXT;
85349       zChar = zIn;
85350     }else if( h==(('c'<<24)+('l'<<16)+('o'<<8)+'b') ){       /* CLOB */
85351       aff = SQLITE_AFF_TEXT;
85352     }else if( h==(('t'<<24)+('e'<<16)+('x'<<8)+'t') ){       /* TEXT */
85353       aff = SQLITE_AFF_TEXT;
85354     }else if( h==(('b'<<24)+('l'<<16)+('o'<<8)+'b')          /* BLOB */
85355         && (aff==SQLITE_AFF_NUMERIC || aff==SQLITE_AFF_REAL) ){
85356       aff = SQLITE_AFF_NONE;
85357       if( zIn[0]=='(' ) zChar = zIn;
85358 #ifndef SQLITE_OMIT_FLOATING_POINT
85359     }else if( h==(('r'<<24)+('e'<<16)+('a'<<8)+'l')          /* REAL */
85360         && aff==SQLITE_AFF_NUMERIC ){
85361       aff = SQLITE_AFF_REAL;
85362     }else if( h==(('f'<<24)+('l'<<16)+('o'<<8)+'a')          /* FLOA */
85363         && aff==SQLITE_AFF_NUMERIC ){
85364       aff = SQLITE_AFF_REAL;
85365     }else if( h==(('d'<<24)+('o'<<16)+('u'<<8)+'b')          /* DOUB */
85366         && aff==SQLITE_AFF_NUMERIC ){
85367       aff = SQLITE_AFF_REAL;
85368 #endif
85369     }else if( (h&0x00FFFFFF)==(('i'<<16)+('n'<<8)+'t') ){    /* INT */
85370       aff = SQLITE_AFF_INTEGER;
85371       break;
85372     }
85373   }
85374 
85375   /* If pszEst is not NULL, store an estimate of the field size.  The
85376   ** estimate is scaled so that the size of an integer is 1.  */
85377   if( pszEst ){
85378     *pszEst = 1;   /* default size is approx 4 bytes */
85379     if( aff<=SQLITE_AFF_NONE ){
85380       if( zChar ){
85381         while( zChar[0] ){
85382           if( sqlite3Isdigit(zChar[0]) ){
85383             int v = 0;
85384             sqlite3GetInt32(zChar, &v);
85385             v = v/4 + 1;
85386             if( v>255 ) v = 255;
85387             *pszEst = v; /* BLOB(k), VARCHAR(k), CHAR(k) -> r=(k/4+1) */
85388             break;
85389           }
85390           zChar++;
85391         }
85392       }else{
85393         *pszEst = 5;   /* BLOB, TEXT, CLOB -> r=5  (approx 20 bytes)*/
85394       }
85395     }
85396   }
85397   return aff;
85398 }
85399 
85400 /*
85401 ** This routine is called by the parser while in the middle of
85402 ** parsing a CREATE TABLE statement.  The pFirst token is the first
85403 ** token in the sequence of tokens that describe the type of the
85404 ** column currently under construction.   pLast is the last token
85405 ** in the sequence.  Use this information to construct a string
85406 ** that contains the typename of the column and store that string
85407 ** in zType.
85408 */ 
85409 SQLITE_PRIVATE void sqlite3AddColumnType(Parse *pParse, Token *pType){
85410   Table *p;
85411   Column *pCol;
85412 
85413   p = pParse->pNewTable;
85414   if( p==0 || NEVER(p->nCol<1) ) return;
85415   pCol = &p->aCol[p->nCol-1];
85416   assert( pCol->zType==0 );
85417   pCol->zType = sqlite3NameFromToken(pParse->db, pType);
85418   pCol->affinity = sqlite3AffinityType(pCol->zType, &pCol->szEst);
85419 }
85420 
85421 /*
85422 ** The expression is the default value for the most recently added column
85423 ** of the table currently under construction.
85424 **
85425 ** Default value expressions must be constant.  Raise an exception if this
85426 ** is not the case.
85427 **
85428 ** This routine is called by the parser while in the middle of
85429 ** parsing a CREATE TABLE statement.
85430 */
85431 SQLITE_PRIVATE void sqlite3AddDefaultValue(Parse *pParse, ExprSpan *pSpan){
85432   Table *p;
85433   Column *pCol;
85434   sqlite3 *db = pParse->db;
85435   p = pParse->pNewTable;
85436   if( p!=0 ){
85437     pCol = &(p->aCol[p->nCol-1]);
85438     if( !sqlite3ExprIsConstantOrFunction(pSpan->pExpr) ){
85439       sqlite3ErrorMsg(pParse, "default value of column [%s] is not constant",
85440           pCol->zName);
85441     }else{
85442       /* A copy of pExpr is used instead of the original, as pExpr contains
85443       ** tokens that point to volatile memory. The 'span' of the expression
85444       ** is required by pragma table_info.
85445       */
85446       sqlite3ExprDelete(db, pCol->pDflt);
85447       pCol->pDflt = sqlite3ExprDup(db, pSpan->pExpr, EXPRDUP_REDUCE);
85448       sqlite3DbFree(db, pCol->zDflt);
85449       pCol->zDflt = sqlite3DbStrNDup(db, (char*)pSpan->zStart,
85450                                      (int)(pSpan->zEnd - pSpan->zStart));
85451     }
85452   }
85453   sqlite3ExprDelete(db, pSpan->pExpr);
85454 }
85455 
85456 /*
85457 ** Designate the PRIMARY KEY for the table.  pList is a list of names 
85458 ** of columns that form the primary key.  If pList is NULL, then the
85459 ** most recently added column of the table is the primary key.
85460 **
85461 ** A table can have at most one primary key.  If the table already has
85462 ** a primary key (and this is the second primary key) then create an
85463 ** error.
85464 **
85465 ** If the PRIMARY KEY is on a single column whose datatype is INTEGER,
85466 ** then we will try to use that column as the rowid.  Set the Table.iPKey
85467 ** field of the table under construction to be the index of the
85468 ** INTEGER PRIMARY KEY column.  Table.iPKey is set to -1 if there is
85469 ** no INTEGER PRIMARY KEY.
85470 **
85471 ** If the key is not an INTEGER PRIMARY KEY, then create a unique
85472 ** index for the key.  No index is created for INTEGER PRIMARY KEYs.
85473 */
85474 SQLITE_PRIVATE void sqlite3AddPrimaryKey(
85475   Parse *pParse,    /* Parsing context */
85476   ExprList *pList,  /* List of field names to be indexed */
85477   int onError,      /* What to do with a uniqueness conflict */
85478   int autoInc,      /* True if the AUTOINCREMENT keyword is present */
85479   int sortOrder     /* SQLITE_SO_ASC or SQLITE_SO_DESC */
85480 ){
85481   Table *pTab = pParse->pNewTable;
85482   char *zType = 0;
85483   int iCol = -1, i;
85484   int nTerm;
85485   if( pTab==0 || IN_DECLARE_VTAB ) goto primary_key_exit;
85486   if( pTab->tabFlags & TF_HasPrimaryKey ){
85487     sqlite3ErrorMsg(pParse, 
85488       "table \"%s\" has more than one primary key", pTab->zName);
85489     goto primary_key_exit;
85490   }
85491   pTab->tabFlags |= TF_HasPrimaryKey;
85492   if( pList==0 ){
85493     iCol = pTab->nCol - 1;
85494     pTab->aCol[iCol].colFlags |= COLFLAG_PRIMKEY;
85495     zType = pTab->aCol[iCol].zType;
85496     nTerm = 1;
85497   }else{
85498     nTerm = pList->nExpr;
85499     for(i=0; i<nTerm; i++){
85500       for(iCol=0; iCol<pTab->nCol; iCol++){
85501         if( sqlite3StrICmp(pList->a[i].zName, pTab->aCol[iCol].zName)==0 ){
85502           pTab->aCol[iCol].colFlags |= COLFLAG_PRIMKEY;
85503           zType = pTab->aCol[iCol].zType;
85504           break;
85505         }
85506       }
85507     }
85508   }
85509   if( nTerm==1
85510    && zType && sqlite3StrICmp(zType, "INTEGER")==0
85511    && sortOrder==SQLITE_SO_ASC
85512   ){
85513     pTab->iPKey = iCol;
85514     pTab->keyConf = (u8)onError;
85515     assert( autoInc==0 || autoInc==1 );
85516     pTab->tabFlags |= autoInc*TF_Autoincrement;
85517     if( pList ) pParse->iPkSortOrder = pList->a[0].sortOrder;
85518   }else if( autoInc ){
85519 #ifndef SQLITE_OMIT_AUTOINCREMENT
85520     sqlite3ErrorMsg(pParse, "AUTOINCREMENT is only allowed on an "
85521        "INTEGER PRIMARY KEY");
85522 #endif
85523   }else{
85524     Vdbe *v = pParse->pVdbe;
85525     Index *p;
85526     if( v ) pParse->addrSkipPK = sqlite3VdbeAddOp0(v, OP_Noop);
85527     p = sqlite3CreateIndex(pParse, 0, 0, 0, pList, onError, 0,
85528                            0, sortOrder, 0);
85529     if( p ){
85530       p->autoIndex = 2;
85531       if( v ) sqlite3VdbeJumpHere(v, pParse->addrSkipPK);
85532     }
85533     pList = 0;
85534   }
85535 
85536 primary_key_exit:
85537   sqlite3ExprListDelete(pParse->db, pList);
85538   return;
85539 }
85540 
85541 /*
85542 ** Add a new CHECK constraint to the table currently under construction.
85543 */
85544 SQLITE_PRIVATE void sqlite3AddCheckConstraint(
85545   Parse *pParse,    /* Parsing context */
85546   Expr *pCheckExpr  /* The check expression */
85547 ){
85548 #ifndef SQLITE_OMIT_CHECK
85549   Table *pTab = pParse->pNewTable;
85550   if( pTab && !IN_DECLARE_VTAB ){
85551     pTab->pCheck = sqlite3ExprListAppend(pParse, pTab->pCheck, pCheckExpr);
85552     if( pParse->constraintName.n ){
85553       sqlite3ExprListSetName(pParse, pTab->pCheck, &pParse->constraintName, 1);
85554     }
85555   }else
85556 #endif
85557   {
85558     sqlite3ExprDelete(pParse->db, pCheckExpr);
85559   }
85560 }
85561 
85562 /*
85563 ** Set the collation function of the most recently parsed table column
85564 ** to the CollSeq given.
85565 */
85566 SQLITE_PRIVATE void sqlite3AddCollateType(Parse *pParse, Token *pToken){
85567   Table *p;
85568   int i;
85569   char *zColl;              /* Dequoted name of collation sequence */
85570   sqlite3 *db;
85571 
85572   if( (p = pParse->pNewTable)==0 ) return;
85573   i = p->nCol-1;
85574   db = pParse->db;
85575   zColl = sqlite3NameFromToken(db, pToken);
85576   if( !zColl ) return;
85577 
85578   if( sqlite3LocateCollSeq(pParse, zColl) ){
85579     Index *pIdx;
85580     sqlite3DbFree(db, p->aCol[i].zColl);
85581     p->aCol[i].zColl = zColl;
85582   
85583     /* If the column is declared as "<name> PRIMARY KEY COLLATE <type>",
85584     ** then an index may have been created on this column before the
85585     ** collation type was added. Correct this if it is the case.
85586     */
85587     for(pIdx=p->pIndex; pIdx; pIdx=pIdx->pNext){
85588       assert( pIdx->nKeyCol==1 );
85589       if( pIdx->aiColumn[0]==i ){
85590         pIdx->azColl[0] = p->aCol[i].zColl;
85591       }
85592     }
85593   }else{
85594     sqlite3DbFree(db, zColl);
85595   }
85596 }
85597 
85598 /*
85599 ** This function returns the collation sequence for database native text
85600 ** encoding identified by the string zName, length nName.
85601 **
85602 ** If the requested collation sequence is not available, or not available
85603 ** in the database native encoding, the collation factory is invoked to
85604 ** request it. If the collation factory does not supply such a sequence,
85605 ** and the sequence is available in another text encoding, then that is
85606 ** returned instead.
85607 **
85608 ** If no versions of the requested collations sequence are available, or
85609 ** another error occurs, NULL is returned and an error message written into
85610 ** pParse.
85611 **
85612 ** This routine is a wrapper around sqlite3FindCollSeq().  This routine
85613 ** invokes the collation factory if the named collation cannot be found
85614 ** and generates an error message.
85615 **
85616 ** See also: sqlite3FindCollSeq(), sqlite3GetCollSeq()
85617 */
85618 SQLITE_PRIVATE CollSeq *sqlite3LocateCollSeq(Parse *pParse, const char *zName){
85619   sqlite3 *db = pParse->db;
85620   u8 enc = ENC(db);
85621   u8 initbusy = db->init.busy;
85622   CollSeq *pColl;
85623 
85624   pColl = sqlite3FindCollSeq(db, enc, zName, initbusy);
85625   if( !initbusy && (!pColl || !pColl->xCmp) ){
85626     pColl = sqlite3GetCollSeq(pParse, enc, pColl, zName);
85627   }
85628 
85629   return pColl;
85630 }
85631 
85632 
85633 /*
85634 ** Generate code that will increment the schema cookie.
85635 **
85636 ** The schema cookie is used to determine when the schema for the
85637 ** database changes.  After each schema change, the cookie value
85638 ** changes.  When a process first reads the schema it records the
85639 ** cookie.  Thereafter, whenever it goes to access the database,
85640 ** it checks the cookie to make sure the schema has not changed
85641 ** since it was last read.
85642 **
85643 ** This plan is not completely bullet-proof.  It is possible for
85644 ** the schema to change multiple times and for the cookie to be
85645 ** set back to prior value.  But schema changes are infrequent
85646 ** and the probability of hitting the same cookie value is only
85647 ** 1 chance in 2^32.  So we're safe enough.
85648 */
85649 SQLITE_PRIVATE void sqlite3ChangeCookie(Parse *pParse, int iDb){
85650   int r1 = sqlite3GetTempReg(pParse);
85651   sqlite3 *db = pParse->db;
85652   Vdbe *v = pParse->pVdbe;
85653   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
85654   sqlite3VdbeAddOp2(v, OP_Integer, db->aDb[iDb].pSchema->schema_cookie+1, r1);
85655   sqlite3VdbeAddOp3(v, OP_SetCookie, iDb, BTREE_SCHEMA_VERSION, r1);
85656   sqlite3ReleaseTempReg(pParse, r1);
85657 }
85658 
85659 /*
85660 ** Measure the number of characters needed to output the given
85661 ** identifier.  The number returned includes any quotes used
85662 ** but does not include the null terminator.
85663 **
85664 ** The estimate is conservative.  It might be larger that what is
85665 ** really needed.
85666 */
85667 static int identLength(const char *z){
85668   int n;
85669   for(n=0; *z; n++, z++){
85670     if( *z=='"' ){ n++; }
85671   }
85672   return n + 2;
85673 }
85674 
85675 /*
85676 ** The first parameter is a pointer to an output buffer. The second 
85677 ** parameter is a pointer to an integer that contains the offset at
85678 ** which to write into the output buffer. This function copies the
85679 ** nul-terminated string pointed to by the third parameter, zSignedIdent,
85680 ** to the specified offset in the buffer and updates *pIdx to refer
85681 ** to the first byte after the last byte written before returning.
85682 ** 
85683 ** If the string zSignedIdent consists entirely of alpha-numeric
85684 ** characters, does not begin with a digit and is not an SQL keyword,
85685 ** then it is copied to the output buffer exactly as it is. Otherwise,
85686 ** it is quoted using double-quotes.
85687 */
85688 static void identPut(char *z, int *pIdx, char *zSignedIdent){
85689   unsigned char *zIdent = (unsigned char*)zSignedIdent;
85690   int i, j, needQuote;
85691   i = *pIdx;
85692 
85693   for(j=0; zIdent[j]; j++){
85694     if( !sqlite3Isalnum(zIdent[j]) && zIdent[j]!='_' ) break;
85695   }
85696   needQuote = sqlite3Isdigit(zIdent[0]) || sqlite3KeywordCode(zIdent, j)!=TK_ID;
85697   if( !needQuote ){
85698     needQuote = zIdent[j];
85699   }
85700 
85701   if( needQuote ) z[i++] = '"';
85702   for(j=0; zIdent[j]; j++){
85703     z[i++] = zIdent[j];
85704     if( zIdent[j]=='"' ) z[i++] = '"';
85705   }
85706   if( needQuote ) z[i++] = '"';
85707   z[i] = 0;
85708   *pIdx = i;
85709 }
85710 
85711 /*
85712 ** Generate a CREATE TABLE statement appropriate for the given
85713 ** table.  Memory to hold the text of the statement is obtained
85714 ** from sqliteMalloc() and must be freed by the calling function.
85715 */
85716 static char *createTableStmt(sqlite3 *db, Table *p){
85717   int i, k, n;
85718   char *zStmt;
85719   char *zSep, *zSep2, *zEnd;
85720   Column *pCol;
85721   n = 0;
85722   for(pCol = p->aCol, i=0; i<p->nCol; i++, pCol++){
85723     n += identLength(pCol->zName) + 5;
85724   }
85725   n += identLength(p->zName);
85726   if( n<50 ){ 
85727     zSep = "";
85728     zSep2 = ",";
85729     zEnd = ")";
85730   }else{
85731     zSep = "\n  ";
85732     zSep2 = ",\n  ";
85733     zEnd = "\n)";
85734   }
85735   n += 35 + 6*p->nCol;
85736   zStmt = sqlite3DbMallocRaw(0, n);
85737   if( zStmt==0 ){
85738     db->mallocFailed = 1;
85739     return 0;
85740   }
85741   sqlite3_snprintf(n, zStmt, "CREATE TABLE ");
85742   k = sqlite3Strlen30(zStmt);
85743   identPut(zStmt, &k, p->zName);
85744   zStmt[k++] = '(';
85745   for(pCol=p->aCol, i=0; i<p->nCol; i++, pCol++){
85746     static const char * const azType[] = {
85747         /* SQLITE_AFF_TEXT    */ " TEXT",
85748         /* SQLITE_AFF_NONE    */ "",
85749         /* SQLITE_AFF_NUMERIC */ " NUM",
85750         /* SQLITE_AFF_INTEGER */ " INT",
85751         /* SQLITE_AFF_REAL    */ " REAL"
85752     };
85753     int len;
85754     const char *zType;
85755 
85756     sqlite3_snprintf(n-k, &zStmt[k], zSep);
85757     k += sqlite3Strlen30(&zStmt[k]);
85758     zSep = zSep2;
85759     identPut(zStmt, &k, pCol->zName);
85760     assert( pCol->affinity-SQLITE_AFF_TEXT >= 0 );
85761     assert( pCol->affinity-SQLITE_AFF_TEXT < ArraySize(azType) );
85762     testcase( pCol->affinity==SQLITE_AFF_TEXT );
85763     testcase( pCol->affinity==SQLITE_AFF_NONE );
85764     testcase( pCol->affinity==SQLITE_AFF_NUMERIC );
85765     testcase( pCol->affinity==SQLITE_AFF_INTEGER );
85766     testcase( pCol->affinity==SQLITE_AFF_REAL );
85767     
85768     zType = azType[pCol->affinity - SQLITE_AFF_TEXT];
85769     len = sqlite3Strlen30(zType);
85770     assert( pCol->affinity==SQLITE_AFF_NONE 
85771             || pCol->affinity==sqlite3AffinityType(zType, 0) );
85772     memcpy(&zStmt[k], zType, len);
85773     k += len;
85774     assert( k<=n );
85775   }
85776   sqlite3_snprintf(n-k, &zStmt[k], "%s", zEnd);
85777   return zStmt;
85778 }
85779 
85780 /*
85781 ** Resize an Index object to hold N columns total.  Return SQLITE_OK
85782 ** on success and SQLITE_NOMEM on an OOM error.
85783 */
85784 static int resizeIndexObject(sqlite3 *db, Index *pIdx, int N){
85785   char *zExtra;
85786   int nByte;
85787   if( pIdx->nColumn>=N ) return SQLITE_OK;
85788   assert( pIdx->isResized==0 );
85789   nByte = (sizeof(char*) + sizeof(i16) + 1)*N;
85790   zExtra = sqlite3DbMallocZero(db, nByte);
85791   if( zExtra==0 ) return SQLITE_NOMEM;
85792   memcpy(zExtra, pIdx->azColl, sizeof(char*)*pIdx->nColumn);
85793   pIdx->azColl = (char**)zExtra;
85794   zExtra += sizeof(char*)*N;
85795   memcpy(zExtra, pIdx->aiColumn, sizeof(i16)*pIdx->nColumn);
85796   pIdx->aiColumn = (i16*)zExtra;
85797   zExtra += sizeof(i16)*N;
85798   memcpy(zExtra, pIdx->aSortOrder, pIdx->nColumn);
85799   pIdx->aSortOrder = (u8*)zExtra;
85800   pIdx->nColumn = N;
85801   pIdx->isResized = 1;
85802   return SQLITE_OK;
85803 }
85804 
85805 /*
85806 ** Estimate the total row width for a table.
85807 */
85808 static void estimateTableWidth(Table *pTab){
85809   unsigned wTable = 0;
85810   const Column *pTabCol;
85811   int i;
85812   for(i=pTab->nCol, pTabCol=pTab->aCol; i>0; i--, pTabCol++){
85813     wTable += pTabCol->szEst;
85814   }
85815   if( pTab->iPKey<0 ) wTable++;
85816   pTab->szTabRow = sqlite3LogEst(wTable*4);
85817 }
85818 
85819 /*
85820 ** Estimate the average size of a row for an index.
85821 */
85822 static void estimateIndexWidth(Index *pIdx){
85823   unsigned wIndex = 0;
85824   int i;
85825   const Column *aCol = pIdx->pTable->aCol;
85826   for(i=0; i<pIdx->nColumn; i++){
85827     i16 x = pIdx->aiColumn[i];
85828     assert( x<pIdx->pTable->nCol );
85829     wIndex += x<0 ? 1 : aCol[pIdx->aiColumn[i]].szEst;
85830   }
85831   pIdx->szIdxRow = sqlite3LogEst(wIndex*4);
85832 }
85833 
85834 /* Return true if value x is found any of the first nCol entries of aiCol[]
85835 */
85836 static int hasColumn(const i16 *aiCol, int nCol, int x){
85837   while( nCol-- > 0 ) if( x==*(aiCol++) ) return 1;
85838   return 0;
85839 }
85840 
85841 /*
85842 ** This routine runs at the end of parsing a CREATE TABLE statement that
85843 ** has a WITHOUT ROWID clause.  The job of this routine is to convert both
85844 ** internal schema data structures and the generated VDBE code so that they
85845 ** are appropriate for a WITHOUT ROWID table instead of a rowid table.
85846 ** Changes include:
85847 **
85848 **     (1)  Convert the OP_CreateTable into an OP_CreateIndex.  There is
85849 **          no rowid btree for a WITHOUT ROWID.  Instead, the canonical
85850 **          data storage is a covering index btree.
85851 **     (2)  Bypass the creation of the sqlite_master table entry
85852 **          for the PRIMARY KEY as the the primary key index is now
85853 **          identified by the sqlite_master table entry of the table itself.
85854 **     (3)  Set the Index.tnum of the PRIMARY KEY Index object in the
85855 **          schema to the rootpage from the main table.
85856 **     (4)  Set all columns of the PRIMARY KEY schema object to be NOT NULL.
85857 **     (5)  Add all table columns to the PRIMARY KEY Index object
85858 **          so that the PRIMARY KEY is a covering index.  The surplus
85859 **          columns are part of KeyInfo.nXField and are not used for
85860 **          sorting or lookup or uniqueness checks.
85861 **     (6)  Replace the rowid tail on all automatically generated UNIQUE
85862 **          indices with the PRIMARY KEY columns.
85863 */
85864 static void convertToWithoutRowidTable(Parse *pParse, Table *pTab){
85865   Index *pIdx;
85866   Index *pPk;
85867   int nPk;
85868   int i, j;
85869   sqlite3 *db = pParse->db;
85870   Vdbe *v = pParse->pVdbe;
85871 
85872   /* Convert the OP_CreateTable opcode that would normally create the
85873   ** root-page for the table into a OP_CreateIndex opcode.  The index
85874   ** created will become the PRIMARY KEY index.
85875   */
85876   if( pParse->addrCrTab ){
85877     assert( v );
85878     sqlite3VdbeGetOp(v, pParse->addrCrTab)->opcode = OP_CreateIndex;
85879   }
85880 
85881   /* Bypass the creation of the PRIMARY KEY btree and the sqlite_master
85882   ** table entry.
85883   */
85884   if( pParse->addrSkipPK ){
85885     assert( v );
85886     sqlite3VdbeGetOp(v, pParse->addrSkipPK)->opcode = OP_Goto;
85887   }
85888 
85889   /* Locate the PRIMARY KEY index.  Or, if this table was originally
85890   ** an INTEGER PRIMARY KEY table, create a new PRIMARY KEY index. 
85891   */
85892   if( pTab->iPKey>=0 ){
85893     ExprList *pList;
85894     pList = sqlite3ExprListAppend(pParse, 0, 0);
85895     if( pList==0 ) return;
85896     pList->a[0].zName = sqlite3DbStrDup(pParse->db,
85897                                         pTab->aCol[pTab->iPKey].zName);
85898     pList->a[0].sortOrder = pParse->iPkSortOrder;
85899     assert( pParse->pNewTable==pTab );
85900     pPk = sqlite3CreateIndex(pParse, 0, 0, 0, pList, pTab->keyConf, 0, 0, 0, 0);
85901     if( pPk==0 ) return;
85902     pPk->autoIndex = 2;
85903     pTab->iPKey = -1;
85904   }else{
85905     pPk = sqlite3PrimaryKeyIndex(pTab);
85906   }
85907   pPk->isCovering = 1;
85908   assert( pPk!=0 );
85909   nPk = pPk->nKeyCol;
85910 
85911   /* Make sure every column of the PRIMARY KEY is NOT NULL */
85912   for(i=0; i<nPk; i++){
85913     pTab->aCol[pPk->aiColumn[i]].notNull = 1;
85914   }
85915   pPk->uniqNotNull = 1;
85916 
85917   /* The root page of the PRIMARY KEY is the table root page */
85918   pPk->tnum = pTab->tnum;
85919 
85920   /* Update the in-memory representation of all UNIQUE indices by converting
85921   ** the final rowid column into one or more columns of the PRIMARY KEY.
85922   */
85923   for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
85924     int n;
85925     if( pIdx->autoIndex==2 ) continue;
85926     for(i=n=0; i<nPk; i++){
85927       if( !hasColumn(pIdx->aiColumn, pIdx->nKeyCol, pPk->aiColumn[i]) ) n++;
85928     }
85929     if( n==0 ){
85930       /* This index is a superset of the primary key */
85931       pIdx->nColumn = pIdx->nKeyCol;
85932       continue;
85933     }
85934     if( resizeIndexObject(db, pIdx, pIdx->nKeyCol+n) ) return;
85935     for(i=0, j=pIdx->nKeyCol; i<nPk; i++){
85936       if( !hasColumn(pIdx->aiColumn, pIdx->nKeyCol, pPk->aiColumn[i]) ){
85937         pIdx->aiColumn[j] = pPk->aiColumn[i];
85938         pIdx->azColl[j] = pPk->azColl[i];
85939         j++;
85940       }
85941     }
85942     assert( pIdx->nColumn>=pIdx->nKeyCol+n );
85943     assert( pIdx->nColumn>=j );
85944   }
85945 
85946   /* Add all table columns to the PRIMARY KEY index
85947   */
85948   if( nPk<pTab->nCol ){
85949     if( resizeIndexObject(db, pPk, pTab->nCol) ) return;
85950     for(i=0, j=nPk; i<pTab->nCol; i++){
85951       if( !hasColumn(pPk->aiColumn, j, i) ){
85952         assert( j<pPk->nColumn );
85953         pPk->aiColumn[j] = i;
85954         pPk->azColl[j] = "BINARY";
85955         j++;
85956       }
85957     }
85958     assert( pPk->nColumn==j );
85959     assert( pTab->nCol==j );
85960   }else{
85961     pPk->nColumn = pTab->nCol;
85962   }
85963 }
85964 
85965 /*
85966 ** This routine is called to report the final ")" that terminates
85967 ** a CREATE TABLE statement.
85968 **
85969 ** The table structure that other action routines have been building
85970 ** is added to the internal hash tables, assuming no errors have
85971 ** occurred.
85972 **
85973 ** An entry for the table is made in the master table on disk, unless
85974 ** this is a temporary table or db->init.busy==1.  When db->init.busy==1
85975 ** it means we are reading the sqlite_master table because we just
85976 ** connected to the database or because the sqlite_master table has
85977 ** recently changed, so the entry for this table already exists in
85978 ** the sqlite_master table.  We do not want to create it again.
85979 **
85980 ** If the pSelect argument is not NULL, it means that this routine
85981 ** was called to create a table generated from a 
85982 ** "CREATE TABLE ... AS SELECT ..." statement.  The column names of
85983 ** the new table will match the result set of the SELECT.
85984 */
85985 SQLITE_PRIVATE void sqlite3EndTable(
85986   Parse *pParse,          /* Parse context */
85987   Token *pCons,           /* The ',' token after the last column defn. */
85988   Token *pEnd,            /* The ')' before options in the CREATE TABLE */
85989   u8 tabOpts,             /* Extra table options. Usually 0. */
85990   Select *pSelect         /* Select from a "CREATE ... AS SELECT" */
85991 ){
85992   Table *p;                 /* The new table */
85993   sqlite3 *db = pParse->db; /* The database connection */
85994   int iDb;                  /* Database in which the table lives */
85995   Index *pIdx;              /* An implied index of the table */
85996 
85997   if( (pEnd==0 && pSelect==0) || db->mallocFailed ){
85998     return;
85999   }
86000   p = pParse->pNewTable;
86001   if( p==0 ) return;
86002 
86003   assert( !db->init.busy || !pSelect );
86004 
86005   /* If the db->init.busy is 1 it means we are reading the SQL off the
86006   ** "sqlite_master" or "sqlite_temp_master" table on the disk.
86007   ** So do not write to the disk again.  Extract the root page number
86008   ** for the table from the db->init.newTnum field.  (The page number
86009   ** should have been put there by the sqliteOpenCb routine.)
86010   */
86011   if( db->init.busy ){
86012     p->tnum = db->init.newTnum;
86013   }
86014 
86015   /* Special processing for WITHOUT ROWID Tables */
86016   if( tabOpts & TF_WithoutRowid ){
86017     if( (p->tabFlags & TF_Autoincrement) ){
86018       sqlite3ErrorMsg(pParse,
86019           "AUTOINCREMENT not allowed on WITHOUT ROWID tables");
86020       return;
86021     }
86022     if( (p->tabFlags & TF_HasPrimaryKey)==0 ){
86023       sqlite3ErrorMsg(pParse, "PRIMARY KEY missing on table %s", p->zName);
86024     }else{
86025       p->tabFlags |= TF_WithoutRowid;
86026       convertToWithoutRowidTable(pParse, p);
86027     }
86028   }
86029 
86030   iDb = sqlite3SchemaToIndex(db, p->pSchema);
86031 
86032 #ifndef SQLITE_OMIT_CHECK
86033   /* Resolve names in all CHECK constraint expressions.
86034   */
86035   if( p->pCheck ){
86036     sqlite3ResolveSelfReference(pParse, p, NC_IsCheck, 0, p->pCheck);
86037   }
86038 #endif /* !defined(SQLITE_OMIT_CHECK) */
86039 
86040   /* Estimate the average row size for the table and for all implied indices */
86041   estimateTableWidth(p);
86042   for(pIdx=p->pIndex; pIdx; pIdx=pIdx->pNext){
86043     estimateIndexWidth(pIdx);
86044   }
86045 
86046   /* If not initializing, then create a record for the new table
86047   ** in the SQLITE_MASTER table of the database.
86048   **
86049   ** If this is a TEMPORARY table, write the entry into the auxiliary
86050   ** file instead of into the main database file.
86051   */
86052   if( !db->init.busy ){
86053     int n;
86054     Vdbe *v;
86055     char *zType;    /* "view" or "table" */
86056     char *zType2;   /* "VIEW" or "TABLE" */
86057     char *zStmt;    /* Text of the CREATE TABLE or CREATE VIEW statement */
86058 
86059     v = sqlite3GetVdbe(pParse);
86060     if( NEVER(v==0) ) return;
86061 
86062     sqlite3VdbeAddOp1(v, OP_Close, 0);
86063 
86064     /* 
86065     ** Initialize zType for the new view or table.
86066     */
86067     if( p->pSelect==0 ){
86068       /* A regular table */
86069       zType = "table";
86070       zType2 = "TABLE";
86071 #ifndef SQLITE_OMIT_VIEW
86072     }else{
86073       /* A view */
86074       zType = "view";
86075       zType2 = "VIEW";
86076 #endif
86077     }
86078 
86079     /* If this is a CREATE TABLE xx AS SELECT ..., execute the SELECT
86080     ** statement to populate the new table. The root-page number for the
86081     ** new table is in register pParse->regRoot.
86082     **
86083     ** Once the SELECT has been coded by sqlite3Select(), it is in a
86084     ** suitable state to query for the column names and types to be used
86085     ** by the new table.
86086     **
86087     ** A shared-cache write-lock is not required to write to the new table,
86088     ** as a schema-lock must have already been obtained to create it. Since
86089     ** a schema-lock excludes all other database users, the write-lock would
86090     ** be redundant.
86091     */
86092     if( pSelect ){
86093       SelectDest dest;
86094       Table *pSelTab;
86095 
86096       assert(pParse->nTab==1);
86097       sqlite3VdbeAddOp3(v, OP_OpenWrite, 1, pParse->regRoot, iDb);
86098       sqlite3VdbeChangeP5(v, OPFLAG_P2ISREG);
86099       pParse->nTab = 2;
86100       sqlite3SelectDestInit(&dest, SRT_Table, 1);
86101       sqlite3Select(pParse, pSelect, &dest);
86102       sqlite3VdbeAddOp1(v, OP_Close, 1);
86103       if( pParse->nErr==0 ){
86104         pSelTab = sqlite3ResultSetOfSelect(pParse, pSelect);
86105         if( pSelTab==0 ) return;
86106         assert( p->aCol==0 );
86107         p->nCol = pSelTab->nCol;
86108         p->aCol = pSelTab->aCol;
86109         pSelTab->nCol = 0;
86110         pSelTab->aCol = 0;
86111         sqlite3DeleteTable(db, pSelTab);
86112       }
86113     }
86114 
86115     /* Compute the complete text of the CREATE statement */
86116     if( pSelect ){
86117       zStmt = createTableStmt(db, p);
86118     }else{
86119       Token *pEnd2 = tabOpts ? &pParse->sLastToken : pEnd;
86120       n = (int)(pEnd2->z - pParse->sNameToken.z);
86121       if( pEnd2->z[0]!=';' ) n += pEnd2->n;
86122       zStmt = sqlite3MPrintf(db, 
86123           "CREATE %s %.*s", zType2, n, pParse->sNameToken.z
86124       );
86125     }
86126 
86127     /* A slot for the record has already been allocated in the 
86128     ** SQLITE_MASTER table.  We just need to update that slot with all
86129     ** the information we've collected.
86130     */
86131     sqlite3NestedParse(pParse,
86132       "UPDATE %Q.%s "
86133          "SET type='%s', name=%Q, tbl_name=%Q, rootpage=#%d, sql=%Q "
86134        "WHERE rowid=#%d",
86135       db->aDb[iDb].zName, SCHEMA_TABLE(iDb),
86136       zType,
86137       p->zName,
86138       p->zName,
86139       pParse->regRoot,
86140       zStmt,
86141       pParse->regRowid
86142     );
86143     sqlite3DbFree(db, zStmt);
86144     sqlite3ChangeCookie(pParse, iDb);
86145 
86146 #ifndef SQLITE_OMIT_AUTOINCREMENT
86147     /* Check to see if we need to create an sqlite_sequence table for
86148     ** keeping track of autoincrement keys.
86149     */
86150     if( p->tabFlags & TF_Autoincrement ){
86151       Db *pDb = &db->aDb[iDb];
86152       assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
86153       if( pDb->pSchema->pSeqTab==0 ){
86154         sqlite3NestedParse(pParse,
86155           "CREATE TABLE %Q.sqlite_sequence(name,seq)",
86156           pDb->zName
86157         );
86158       }
86159     }
86160 #endif
86161 
86162     /* Reparse everything to update our internal data structures */
86163     sqlite3VdbeAddParseSchemaOp(v, iDb,
86164            sqlite3MPrintf(db, "tbl_name='%q' AND type!='trigger'", p->zName));
86165   }
86166 
86167 
86168   /* Add the table to the in-memory representation of the database.
86169   */
86170   if( db->init.busy ){
86171     Table *pOld;
86172     Schema *pSchema = p->pSchema;
86173     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
86174     pOld = sqlite3HashInsert(&pSchema->tblHash, p->zName,
86175                              sqlite3Strlen30(p->zName),p);
86176     if( pOld ){
86177       assert( p==pOld );  /* Malloc must have failed inside HashInsert() */
86178       db->mallocFailed = 1;
86179       return;
86180     }
86181     pParse->pNewTable = 0;
86182     db->flags |= SQLITE_InternChanges;
86183 
86184 #ifndef SQLITE_OMIT_ALTERTABLE
86185     if( !p->pSelect ){
86186       const char *zName = (const char *)pParse->sNameToken.z;
86187       int nName;
86188       assert( !pSelect && pCons && pEnd );
86189       if( pCons->z==0 ){
86190         pCons = pEnd;
86191       }
86192       nName = (int)((const char *)pCons->z - zName);
86193       p->addColOffset = 13 + sqlite3Utf8CharLen(zName, nName);
86194     }
86195 #endif
86196   }
86197 }
86198 
86199 #ifndef SQLITE_OMIT_VIEW
86200 /*
86201 ** The parser calls this routine in order to create a new VIEW
86202 */
86203 SQLITE_PRIVATE void sqlite3CreateView(
86204   Parse *pParse,     /* The parsing context */
86205   Token *pBegin,     /* The CREATE token that begins the statement */
86206   Token *pName1,     /* The token that holds the name of the view */
86207   Token *pName2,     /* The token that holds the name of the view */
86208   Select *pSelect,   /* A SELECT statement that will become the new view */
86209   int isTemp,        /* TRUE for a TEMPORARY view */
86210   int noErr          /* Suppress error messages if VIEW already exists */
86211 ){
86212   Table *p;
86213   int n;
86214   const char *z;
86215   Token sEnd;
86216   DbFixer sFix;
86217   Token *pName = 0;
86218   int iDb;
86219   sqlite3 *db = pParse->db;
86220 
86221   if( pParse->nVar>0 ){
86222     sqlite3ErrorMsg(pParse, "parameters are not allowed in views");
86223     sqlite3SelectDelete(db, pSelect);
86224     return;
86225   }
86226   sqlite3StartTable(pParse, pName1, pName2, isTemp, 1, 0, noErr);
86227   p = pParse->pNewTable;
86228   if( p==0 || pParse->nErr ){
86229     sqlite3SelectDelete(db, pSelect);
86230     return;
86231   }
86232   sqlite3TwoPartName(pParse, pName1, pName2, &pName);
86233   iDb = sqlite3SchemaToIndex(db, p->pSchema);
86234   sqlite3FixInit(&sFix, pParse, iDb, "view", pName);
86235   if( sqlite3FixSelect(&sFix, pSelect) ){
86236     sqlite3SelectDelete(db, pSelect);
86237     return;
86238   }
86239 
86240   /* Make a copy of the entire SELECT statement that defines the view.
86241   ** This will force all the Expr.token.z values to be dynamically
86242   ** allocated rather than point to the input string - which means that
86243   ** they will persist after the current sqlite3_exec() call returns.
86244   */
86245   p->pSelect = sqlite3SelectDup(db, pSelect, EXPRDUP_REDUCE);
86246   sqlite3SelectDelete(db, pSelect);
86247   if( db->mallocFailed ){
86248     return;
86249   }
86250   if( !db->init.busy ){
86251     sqlite3ViewGetColumnNames(pParse, p);
86252   }
86253 
86254   /* Locate the end of the CREATE VIEW statement.  Make sEnd point to
86255   ** the end.
86256   */
86257   sEnd = pParse->sLastToken;
86258   if( ALWAYS(sEnd.z[0]!=0) && sEnd.z[0]!=';' ){
86259     sEnd.z += sEnd.n;
86260   }
86261   sEnd.n = 0;
86262   n = (int)(sEnd.z - pBegin->z);
86263   z = pBegin->z;
86264   while( ALWAYS(n>0) && sqlite3Isspace(z[n-1]) ){ n--; }
86265   sEnd.z = &z[n-1];
86266   sEnd.n = 1;
86267 
86268   /* Use sqlite3EndTable() to add the view to the SQLITE_MASTER table */
86269   sqlite3EndTable(pParse, 0, &sEnd, 0, 0);
86270   return;
86271 }
86272 #endif /* SQLITE_OMIT_VIEW */
86273 
86274 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_VIRTUALTABLE)
86275 /*
86276 ** The Table structure pTable is really a VIEW.  Fill in the names of
86277 ** the columns of the view in the pTable structure.  Return the number
86278 ** of errors.  If an error is seen leave an error message in pParse->zErrMsg.
86279 */
86280 SQLITE_PRIVATE int sqlite3ViewGetColumnNames(Parse *pParse, Table *pTable){
86281   Table *pSelTab;   /* A fake table from which we get the result set */
86282   Select *pSel;     /* Copy of the SELECT that implements the view */
86283   int nErr = 0;     /* Number of errors encountered */
86284   int n;            /* Temporarily holds the number of cursors assigned */
86285   sqlite3 *db = pParse->db;  /* Database connection for malloc errors */
86286   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*);
86287 
86288   assert( pTable );
86289 
86290 #ifndef SQLITE_OMIT_VIRTUALTABLE
86291   if( sqlite3VtabCallConnect(pParse, pTable) ){
86292     return SQLITE_ERROR;
86293   }
86294   if( IsVirtual(pTable) ) return 0;
86295 #endif
86296 
86297 #ifndef SQLITE_OMIT_VIEW
86298   /* A positive nCol means the columns names for this view are
86299   ** already known.
86300   */
86301   if( pTable->nCol>0 ) return 0;
86302 
86303   /* A negative nCol is a special marker meaning that we are currently
86304   ** trying to compute the column names.  If we enter this routine with
86305   ** a negative nCol, it means two or more views form a loop, like this:
86306   **
86307   **     CREATE VIEW one AS SELECT * FROM two;
86308   **     CREATE VIEW two AS SELECT * FROM one;
86309   **
86310   ** Actually, the error above is now caught prior to reaching this point.
86311   ** But the following test is still important as it does come up
86312   ** in the following:
86313   ** 
86314   **     CREATE TABLE main.ex1(a);
86315   **     CREATE TEMP VIEW ex1 AS SELECT a FROM ex1;
86316   **     SELECT * FROM temp.ex1;
86317   */
86318   if( pTable->nCol<0 ){
86319     sqlite3ErrorMsg(pParse, "view %s is circularly defined", pTable->zName);
86320     return 1;
86321   }
86322   assert( pTable->nCol>=0 );
86323 
86324   /* If we get this far, it means we need to compute the table names.
86325   ** Note that the call to sqlite3ResultSetOfSelect() will expand any
86326   ** "*" elements in the results set of the view and will assign cursors
86327   ** to the elements of the FROM clause.  But we do not want these changes
86328   ** to be permanent.  So the computation is done on a copy of the SELECT
86329   ** statement that defines the view.
86330   */
86331   assert( pTable->pSelect );
86332   pSel = sqlite3SelectDup(db, pTable->pSelect, 0);
86333   if( pSel ){
86334     u8 enableLookaside = db->lookaside.bEnabled;
86335     n = pParse->nTab;
86336     sqlite3SrcListAssignCursors(pParse, pSel->pSrc);
86337     pTable->nCol = -1;
86338     db->lookaside.bEnabled = 0;
86339 #ifndef SQLITE_OMIT_AUTHORIZATION
86340     xAuth = db->xAuth;
86341     db->xAuth = 0;
86342     pSelTab = sqlite3ResultSetOfSelect(pParse, pSel);
86343     db->xAuth = xAuth;
86344 #else
86345     pSelTab = sqlite3ResultSetOfSelect(pParse, pSel);
86346 #endif
86347     db->lookaside.bEnabled = enableLookaside;
86348     pParse->nTab = n;
86349     if( pSelTab ){
86350       assert( pTable->aCol==0 );
86351       pTable->nCol = pSelTab->nCol;
86352       pTable->aCol = pSelTab->aCol;
86353       pSelTab->nCol = 0;
86354       pSelTab->aCol = 0;
86355       sqlite3DeleteTable(db, pSelTab);
86356       assert( sqlite3SchemaMutexHeld(db, 0, pTable->pSchema) );
86357       pTable->pSchema->flags |= DB_UnresetViews;
86358     }else{
86359       pTable->nCol = 0;
86360       nErr++;
86361     }
86362     sqlite3SelectDelete(db, pSel);
86363   } else {
86364     nErr++;
86365   }
86366 #endif /* SQLITE_OMIT_VIEW */
86367   return nErr;  
86368 }
86369 #endif /* !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_VIRTUALTABLE) */
86370 
86371 #ifndef SQLITE_OMIT_VIEW
86372 /*
86373 ** Clear the column names from every VIEW in database idx.
86374 */
86375 static void sqliteViewResetAll(sqlite3 *db, int idx){
86376   HashElem *i;
86377   assert( sqlite3SchemaMutexHeld(db, idx, 0) );
86378   if( !DbHasProperty(db, idx, DB_UnresetViews) ) return;
86379   for(i=sqliteHashFirst(&db->aDb[idx].pSchema->tblHash); i;i=sqliteHashNext(i)){
86380     Table *pTab = sqliteHashData(i);
86381     if( pTab->pSelect ){
86382       sqliteDeleteColumnNames(db, pTab);
86383       pTab->aCol = 0;
86384       pTab->nCol = 0;
86385     }
86386   }
86387   DbClearProperty(db, idx, DB_UnresetViews);
86388 }
86389 #else
86390 # define sqliteViewResetAll(A,B)
86391 #endif /* SQLITE_OMIT_VIEW */
86392 
86393 /*
86394 ** This function is called by the VDBE to adjust the internal schema
86395 ** used by SQLite when the btree layer moves a table root page. The
86396 ** root-page of a table or index in database iDb has changed from iFrom
86397 ** to iTo.
86398 **
86399 ** Ticket #1728:  The symbol table might still contain information
86400 ** on tables and/or indices that are the process of being deleted.
86401 ** If you are unlucky, one of those deleted indices or tables might
86402 ** have the same rootpage number as the real table or index that is
86403 ** being moved.  So we cannot stop searching after the first match 
86404 ** because the first match might be for one of the deleted indices
86405 ** or tables and not the table/index that is actually being moved.
86406 ** We must continue looping until all tables and indices with
86407 ** rootpage==iFrom have been converted to have a rootpage of iTo
86408 ** in order to be certain that we got the right one.
86409 */
86410 #ifndef SQLITE_OMIT_AUTOVACUUM
86411 SQLITE_PRIVATE void sqlite3RootPageMoved(sqlite3 *db, int iDb, int iFrom, int iTo){
86412   HashElem *pElem;
86413   Hash *pHash;
86414   Db *pDb;
86415 
86416   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
86417   pDb = &db->aDb[iDb];
86418   pHash = &pDb->pSchema->tblHash;
86419   for(pElem=sqliteHashFirst(pHash); pElem; pElem=sqliteHashNext(pElem)){
86420     Table *pTab = sqliteHashData(pElem);
86421     if( pTab->tnum==iFrom ){
86422       pTab->tnum = iTo;
86423     }
86424   }
86425   pHash = &pDb->pSchema->idxHash;
86426   for(pElem=sqliteHashFirst(pHash); pElem; pElem=sqliteHashNext(pElem)){
86427     Index *pIdx = sqliteHashData(pElem);
86428     if( pIdx->tnum==iFrom ){
86429       pIdx->tnum = iTo;
86430     }
86431   }
86432 }
86433 #endif
86434 
86435 /*
86436 ** Write code to erase the table with root-page iTable from database iDb.
86437 ** Also write code to modify the sqlite_master table and internal schema
86438 ** if a root-page of another table is moved by the btree-layer whilst
86439 ** erasing iTable (this can happen with an auto-vacuum database).
86440 */ 
86441 static void destroyRootPage(Parse *pParse, int iTable, int iDb){
86442   Vdbe *v = sqlite3GetVdbe(pParse);
86443   int r1 = sqlite3GetTempReg(pParse);
86444   sqlite3VdbeAddOp3(v, OP_Destroy, iTable, r1, iDb);
86445   sqlite3MayAbort(pParse);
86446 #ifndef SQLITE_OMIT_AUTOVACUUM
86447   /* OP_Destroy stores an in integer r1. If this integer
86448   ** is non-zero, then it is the root page number of a table moved to
86449   ** location iTable. The following code modifies the sqlite_master table to
86450   ** reflect this.
86451   **
86452   ** The "#NNN" in the SQL is a special constant that means whatever value
86453   ** is in register NNN.  See grammar rules associated with the TK_REGISTER
86454   ** token for additional information.
86455   */
86456   sqlite3NestedParse(pParse, 
86457      "UPDATE %Q.%s SET rootpage=%d WHERE #%d AND rootpage=#%d",
86458      pParse->db->aDb[iDb].zName, SCHEMA_TABLE(iDb), iTable, r1, r1);
86459 #endif
86460   sqlite3ReleaseTempReg(pParse, r1);
86461 }
86462 
86463 /*
86464 ** Write VDBE code to erase table pTab and all associated indices on disk.
86465 ** Code to update the sqlite_master tables and internal schema definitions
86466 ** in case a root-page belonging to another table is moved by the btree layer
86467 ** is also added (this can happen with an auto-vacuum database).
86468 */
86469 static void destroyTable(Parse *pParse, Table *pTab){
86470 #ifdef SQLITE_OMIT_AUTOVACUUM
86471   Index *pIdx;
86472   int iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
86473   destroyRootPage(pParse, pTab->tnum, iDb);
86474   for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
86475     destroyRootPage(pParse, pIdx->tnum, iDb);
86476   }
86477 #else
86478   /* If the database may be auto-vacuum capable (if SQLITE_OMIT_AUTOVACUUM
86479   ** is not defined), then it is important to call OP_Destroy on the
86480   ** table and index root-pages in order, starting with the numerically 
86481   ** largest root-page number. This guarantees that none of the root-pages
86482   ** to be destroyed is relocated by an earlier OP_Destroy. i.e. if the
86483   ** following were coded:
86484   **
86485   ** OP_Destroy 4 0
86486   ** ...
86487   ** OP_Destroy 5 0
86488   **
86489   ** and root page 5 happened to be the largest root-page number in the
86490   ** database, then root page 5 would be moved to page 4 by the 
86491   ** "OP_Destroy 4 0" opcode. The subsequent "OP_Destroy 5 0" would hit
86492   ** a free-list page.
86493   */
86494   int iTab = pTab->tnum;
86495   int iDestroyed = 0;
86496 
86497   while( 1 ){
86498     Index *pIdx;
86499     int iLargest = 0;
86500 
86501     if( iDestroyed==0 || iTab<iDestroyed ){
86502       iLargest = iTab;
86503     }
86504     for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
86505       int iIdx = pIdx->tnum;
86506       assert( pIdx->pSchema==pTab->pSchema );
86507       if( (iDestroyed==0 || (iIdx<iDestroyed)) && iIdx>iLargest ){
86508         iLargest = iIdx;
86509       }
86510     }
86511     if( iLargest==0 ){
86512       return;
86513     }else{
86514       int iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
86515       assert( iDb>=0 && iDb<pParse->db->nDb );
86516       destroyRootPage(pParse, iLargest, iDb);
86517       iDestroyed = iLargest;
86518     }
86519   }
86520 #endif
86521 }
86522 
86523 /*
86524 ** Remove entries from the sqlite_statN tables (for N in (1,2,3))
86525 ** after a DROP INDEX or DROP TABLE command.
86526 */
86527 static void sqlite3ClearStatTables(
86528   Parse *pParse,         /* The parsing context */
86529   int iDb,               /* The database number */
86530   const char *zType,     /* "idx" or "tbl" */
86531   const char *zName      /* Name of index or table */
86532 ){
86533   int i;
86534   const char *zDbName = pParse->db->aDb[iDb].zName;
86535   for(i=1; i<=4; i++){
86536     char zTab[24];
86537     sqlite3_snprintf(sizeof(zTab),zTab,"sqlite_stat%d",i);
86538     if( sqlite3FindTable(pParse->db, zTab, zDbName) ){
86539       sqlite3NestedParse(pParse,
86540         "DELETE FROM %Q.%s WHERE %s=%Q",
86541         zDbName, zTab, zType, zName
86542       );
86543     }
86544   }
86545 }
86546 
86547 /*
86548 ** Generate code to drop a table.
86549 */
86550 SQLITE_PRIVATE void sqlite3CodeDropTable(Parse *pParse, Table *pTab, int iDb, int isView){
86551   Vdbe *v;
86552   sqlite3 *db = pParse->db;
86553   Trigger *pTrigger;
86554   Db *pDb = &db->aDb[iDb];
86555 
86556   v = sqlite3GetVdbe(pParse);
86557   assert( v!=0 );
86558   sqlite3BeginWriteOperation(pParse, 1, iDb);
86559 
86560 #ifndef SQLITE_OMIT_VIRTUALTABLE
86561   if( IsVirtual(pTab) ){
86562     sqlite3VdbeAddOp0(v, OP_VBegin);
86563   }
86564 #endif
86565 
86566   /* Drop all triggers associated with the table being dropped. Code
86567   ** is generated to remove entries from sqlite_master and/or
86568   ** sqlite_temp_master if required.
86569   */
86570   pTrigger = sqlite3TriggerList(pParse, pTab);
86571   while( pTrigger ){
86572     assert( pTrigger->pSchema==pTab->pSchema || 
86573         pTrigger->pSchema==db->aDb[1].pSchema );
86574     sqlite3DropTriggerPtr(pParse, pTrigger);
86575     pTrigger = pTrigger->pNext;
86576   }
86577 
86578 #ifndef SQLITE_OMIT_AUTOINCREMENT
86579   /* Remove any entries of the sqlite_sequence table associated with
86580   ** the table being dropped. This is done before the table is dropped
86581   ** at the btree level, in case the sqlite_sequence table needs to
86582   ** move as a result of the drop (can happen in auto-vacuum mode).
86583   */
86584   if( pTab->tabFlags & TF_Autoincrement ){
86585     sqlite3NestedParse(pParse,
86586       "DELETE FROM %Q.sqlite_sequence WHERE name=%Q",
86587       pDb->zName, pTab->zName
86588     );
86589   }
86590 #endif
86591 
86592   /* Drop all SQLITE_MASTER table and index entries that refer to the
86593   ** table. The program name loops through the master table and deletes
86594   ** every row that refers to a table of the same name as the one being
86595   ** dropped. Triggers are handled separately because a trigger can be
86596   ** created in the temp database that refers to a table in another
86597   ** database.
86598   */
86599   sqlite3NestedParse(pParse, 
86600       "DELETE FROM %Q.%s WHERE tbl_name=%Q and type!='trigger'",
86601       pDb->zName, SCHEMA_TABLE(iDb), pTab->zName);
86602   if( !isView && !IsVirtual(pTab) ){
86603     destroyTable(pParse, pTab);
86604   }
86605 
86606   /* Remove the table entry from SQLite's internal schema and modify
86607   ** the schema cookie.
86608   */
86609   if( IsVirtual(pTab) ){
86610     sqlite3VdbeAddOp4(v, OP_VDestroy, iDb, 0, 0, pTab->zName, 0);
86611   }
86612   sqlite3VdbeAddOp4(v, OP_DropTable, iDb, 0, 0, pTab->zName, 0);
86613   sqlite3ChangeCookie(pParse, iDb);
86614   sqliteViewResetAll(db, iDb);
86615 }
86616 
86617 /*
86618 ** This routine is called to do the work of a DROP TABLE statement.
86619 ** pName is the name of the table to be dropped.
86620 */
86621 SQLITE_PRIVATE void sqlite3DropTable(Parse *pParse, SrcList *pName, int isView, int noErr){
86622   Table *pTab;
86623   Vdbe *v;
86624   sqlite3 *db = pParse->db;
86625   int iDb;
86626 
86627   if( db->mallocFailed ){
86628     goto exit_drop_table;
86629   }
86630   assert( pParse->nErr==0 );
86631   assert( pName->nSrc==1 );
86632   if( noErr ) db->suppressErr++;
86633   pTab = sqlite3LocateTableItem(pParse, isView, &pName->a[0]);
86634   if( noErr ) db->suppressErr--;
86635 
86636   if( pTab==0 ){
86637     if( noErr ) sqlite3CodeVerifyNamedSchema(pParse, pName->a[0].zDatabase);
86638     goto exit_drop_table;
86639   }
86640   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
86641   assert( iDb>=0 && iDb<db->nDb );
86642 
86643   /* If pTab is a virtual table, call ViewGetColumnNames() to ensure
86644   ** it is initialized.
86645   */
86646   if( IsVirtual(pTab) && sqlite3ViewGetColumnNames(pParse, pTab) ){
86647     goto exit_drop_table;
86648   }
86649 #ifndef SQLITE_OMIT_AUTHORIZATION
86650   {
86651     int code;
86652     const char *zTab = SCHEMA_TABLE(iDb);
86653     const char *zDb = db->aDb[iDb].zName;
86654     const char *zArg2 = 0;
86655     if( sqlite3AuthCheck(pParse, SQLITE_DELETE, zTab, 0, zDb)){
86656       goto exit_drop_table;
86657     }
86658     if( isView ){
86659       if( !OMIT_TEMPDB && iDb==1 ){
86660         code = SQLITE_DROP_TEMP_VIEW;
86661       }else{
86662         code = SQLITE_DROP_VIEW;
86663       }
86664 #ifndef SQLITE_OMIT_VIRTUALTABLE
86665     }else if( IsVirtual(pTab) ){
86666       code = SQLITE_DROP_VTABLE;
86667       zArg2 = sqlite3GetVTable(db, pTab)->pMod->zName;
86668 #endif
86669     }else{
86670       if( !OMIT_TEMPDB && iDb==1 ){
86671         code = SQLITE_DROP_TEMP_TABLE;
86672       }else{
86673         code = SQLITE_DROP_TABLE;
86674       }
86675     }
86676     if( sqlite3AuthCheck(pParse, code, pTab->zName, zArg2, zDb) ){
86677       goto exit_drop_table;
86678     }
86679     if( sqlite3AuthCheck(pParse, SQLITE_DELETE, pTab->zName, 0, zDb) ){
86680       goto exit_drop_table;
86681     }
86682   }
86683 #endif
86684   if( sqlite3StrNICmp(pTab->zName, "sqlite_", 7)==0 
86685     && sqlite3StrNICmp(pTab->zName, "sqlite_stat", 11)!=0 ){
86686     sqlite3ErrorMsg(pParse, "table %s may not be dropped", pTab->zName);
86687     goto exit_drop_table;
86688   }
86689 
86690 #ifndef SQLITE_OMIT_VIEW
86691   /* Ensure DROP TABLE is not used on a view, and DROP VIEW is not used
86692   ** on a table.
86693   */
86694   if( isView && pTab->pSelect==0 ){
86695     sqlite3ErrorMsg(pParse, "use DROP TABLE to delete table %s", pTab->zName);
86696     goto exit_drop_table;
86697   }
86698   if( !isView && pTab->pSelect ){
86699     sqlite3ErrorMsg(pParse, "use DROP VIEW to delete view %s", pTab->zName);
86700     goto exit_drop_table;
86701   }
86702 #endif
86703 
86704   /* Generate code to remove the table from the master table
86705   ** on disk.
86706   */
86707   v = sqlite3GetVdbe(pParse);
86708   if( v ){
86709     sqlite3BeginWriteOperation(pParse, 1, iDb);
86710     sqlite3ClearStatTables(pParse, iDb, "tbl", pTab->zName);
86711     sqlite3FkDropTable(pParse, pName, pTab);
86712     sqlite3CodeDropTable(pParse, pTab, iDb, isView);
86713   }
86714 
86715 exit_drop_table:
86716   sqlite3SrcListDelete(db, pName);
86717 }
86718 
86719 /*
86720 ** This routine is called to create a new foreign key on the table
86721 ** currently under construction.  pFromCol determines which columns
86722 ** in the current table point to the foreign key.  If pFromCol==0 then
86723 ** connect the key to the last column inserted.  pTo is the name of
86724 ** the table referred to (a.k.a the "parent" table).  pToCol is a list
86725 ** of tables in the parent pTo table.  flags contains all
86726 ** information about the conflict resolution algorithms specified
86727 ** in the ON DELETE, ON UPDATE and ON INSERT clauses.
86728 **
86729 ** An FKey structure is created and added to the table currently
86730 ** under construction in the pParse->pNewTable field.
86731 **
86732 ** The foreign key is set for IMMEDIATE processing.  A subsequent call
86733 ** to sqlite3DeferForeignKey() might change this to DEFERRED.
86734 */
86735 SQLITE_PRIVATE void sqlite3CreateForeignKey(
86736   Parse *pParse,       /* Parsing context */
86737   ExprList *pFromCol,  /* Columns in this table that point to other table */
86738   Token *pTo,          /* Name of the other table */
86739   ExprList *pToCol,    /* Columns in the other table */
86740   int flags            /* Conflict resolution algorithms. */
86741 ){
86742   sqlite3 *db = pParse->db;
86743 #ifndef SQLITE_OMIT_FOREIGN_KEY
86744   FKey *pFKey = 0;
86745   FKey *pNextTo;
86746   Table *p = pParse->pNewTable;
86747   int nByte;
86748   int i;
86749   int nCol;
86750   char *z;
86751 
86752   assert( pTo!=0 );
86753   if( p==0 || IN_DECLARE_VTAB ) goto fk_end;
86754   if( pFromCol==0 ){
86755     int iCol = p->nCol-1;
86756     if( NEVER(iCol<0) ) goto fk_end;
86757     if( pToCol && pToCol->nExpr!=1 ){
86758       sqlite3ErrorMsg(pParse, "foreign key on %s"
86759          " should reference only one column of table %T",
86760          p->aCol[iCol].zName, pTo);
86761       goto fk_end;
86762     }
86763     nCol = 1;
86764   }else if( pToCol && pToCol->nExpr!=pFromCol->nExpr ){
86765     sqlite3ErrorMsg(pParse,
86766         "number of columns in foreign key does not match the number of "
86767         "columns in the referenced table");
86768     goto fk_end;
86769   }else{
86770     nCol = pFromCol->nExpr;
86771   }
86772   nByte = sizeof(*pFKey) + (nCol-1)*sizeof(pFKey->aCol[0]) + pTo->n + 1;
86773   if( pToCol ){
86774     for(i=0; i<pToCol->nExpr; i++){
86775       nByte += sqlite3Strlen30(pToCol->a[i].zName) + 1;
86776     }
86777   }
86778   pFKey = sqlite3DbMallocZero(db, nByte );
86779   if( pFKey==0 ){
86780     goto fk_end;
86781   }
86782   pFKey->pFrom = p;
86783   pFKey->pNextFrom = p->pFKey;
86784   z = (char*)&pFKey->aCol[nCol];
86785   pFKey->zTo = z;
86786   memcpy(z, pTo->z, pTo->n);
86787   z[pTo->n] = 0;
86788   sqlite3Dequote(z);
86789   z += pTo->n+1;
86790   pFKey->nCol = nCol;
86791   if( pFromCol==0 ){
86792     pFKey->aCol[0].iFrom = p->nCol-1;
86793   }else{
86794     for(i=0; i<nCol; i++){
86795       int j;
86796       for(j=0; j<p->nCol; j++){
86797         if( sqlite3StrICmp(p->aCol[j].zName, pFromCol->a[i].zName)==0 ){
86798           pFKey->aCol[i].iFrom = j;
86799           break;
86800         }
86801       }
86802       if( j>=p->nCol ){
86803         sqlite3ErrorMsg(pParse, 
86804           "unknown column \"%s\" in foreign key definition", 
86805           pFromCol->a[i].zName);
86806         goto fk_end;
86807       }
86808     }
86809   }
86810   if( pToCol ){
86811     for(i=0; i<nCol; i++){
86812       int n = sqlite3Strlen30(pToCol->a[i].zName);
86813       pFKey->aCol[i].zCol = z;
86814       memcpy(z, pToCol->a[i].zName, n);
86815       z[n] = 0;
86816       z += n+1;
86817     }
86818   }
86819   pFKey->isDeferred = 0;
86820   pFKey->aAction[0] = (u8)(flags & 0xff);            /* ON DELETE action */
86821   pFKey->aAction[1] = (u8)((flags >> 8 ) & 0xff);    /* ON UPDATE action */
86822 
86823   assert( sqlite3SchemaMutexHeld(db, 0, p->pSchema) );
86824   pNextTo = (FKey *)sqlite3HashInsert(&p->pSchema->fkeyHash, 
86825       pFKey->zTo, sqlite3Strlen30(pFKey->zTo), (void *)pFKey
86826   );
86827   if( pNextTo==pFKey ){
86828     db->mallocFailed = 1;
86829     goto fk_end;
86830   }
86831   if( pNextTo ){
86832     assert( pNextTo->pPrevTo==0 );
86833     pFKey->pNextTo = pNextTo;
86834     pNextTo->pPrevTo = pFKey;
86835   }
86836 
86837   /* Link the foreign key to the table as the last step.
86838   */
86839   p->pFKey = pFKey;
86840   pFKey = 0;
86841 
86842 fk_end:
86843   sqlite3DbFree(db, pFKey);
86844 #endif /* !defined(SQLITE_OMIT_FOREIGN_KEY) */
86845   sqlite3ExprListDelete(db, pFromCol);
86846   sqlite3ExprListDelete(db, pToCol);
86847 }
86848 
86849 /*
86850 ** This routine is called when an INITIALLY IMMEDIATE or INITIALLY DEFERRED
86851 ** clause is seen as part of a foreign key definition.  The isDeferred
86852 ** parameter is 1 for INITIALLY DEFERRED and 0 for INITIALLY IMMEDIATE.
86853 ** The behavior of the most recently created foreign key is adjusted
86854 ** accordingly.
86855 */
86856 SQLITE_PRIVATE void sqlite3DeferForeignKey(Parse *pParse, int isDeferred){
86857 #ifndef SQLITE_OMIT_FOREIGN_KEY
86858   Table *pTab;
86859   FKey *pFKey;
86860   if( (pTab = pParse->pNewTable)==0 || (pFKey = pTab->pFKey)==0 ) return;
86861   assert( isDeferred==0 || isDeferred==1 ); /* EV: R-30323-21917 */
86862   pFKey->isDeferred = (u8)isDeferred;
86863 #endif
86864 }
86865 
86866 /*
86867 ** Generate code that will erase and refill index *pIdx.  This is
86868 ** used to initialize a newly created index or to recompute the
86869 ** content of an index in response to a REINDEX command.
86870 **
86871 ** if memRootPage is not negative, it means that the index is newly
86872 ** created.  The register specified by memRootPage contains the
86873 ** root page number of the index.  If memRootPage is negative, then
86874 ** the index already exists and must be cleared before being refilled and
86875 ** the root page number of the index is taken from pIndex->tnum.
86876 */
86877 static void sqlite3RefillIndex(Parse *pParse, Index *pIndex, int memRootPage){
86878   Table *pTab = pIndex->pTable;  /* The table that is indexed */
86879   int iTab = pParse->nTab++;     /* Btree cursor used for pTab */
86880   int iIdx = pParse->nTab++;     /* Btree cursor used for pIndex */
86881   int iSorter;                   /* Cursor opened by OpenSorter (if in use) */
86882   int addr1;                     /* Address of top of loop */
86883   int addr2;                     /* Address to jump to for next iteration */
86884   int tnum;                      /* Root page of index */
86885   int iPartIdxLabel;             /* Jump to this label to skip a row */
86886   Vdbe *v;                       /* Generate code into this virtual machine */
86887   KeyInfo *pKey;                 /* KeyInfo for index */
86888   int regRecord;                 /* Register holding assemblied index record */
86889   sqlite3 *db = pParse->db;      /* The database connection */
86890   int iDb = sqlite3SchemaToIndex(db, pIndex->pSchema);
86891 
86892 #ifndef SQLITE_OMIT_AUTHORIZATION
86893   if( sqlite3AuthCheck(pParse, SQLITE_REINDEX, pIndex->zName, 0,
86894       db->aDb[iDb].zName ) ){
86895     return;
86896   }
86897 #endif
86898 
86899   /* Require a write-lock on the table to perform this operation */
86900   sqlite3TableLock(pParse, iDb, pTab->tnum, 1, pTab->zName);
86901 
86902   v = sqlite3GetVdbe(pParse);
86903   if( v==0 ) return;
86904   if( memRootPage>=0 ){
86905     tnum = memRootPage;
86906   }else{
86907     tnum = pIndex->tnum;
86908   }
86909   pKey = sqlite3KeyInfoOfIndex(pParse, pIndex);
86910 
86911   /* Open the sorter cursor if we are to use one. */
86912   iSorter = pParse->nTab++;
86913   sqlite3VdbeAddOp4(v, OP_SorterOpen, iSorter, 0, 0, (char*)
86914                     sqlite3KeyInfoRef(pKey), P4_KEYINFO);
86915 
86916   /* Open the table. Loop through all rows of the table, inserting index
86917   ** records into the sorter. */
86918   sqlite3OpenTable(pParse, iTab, iDb, pTab, OP_OpenRead);
86919   addr1 = sqlite3VdbeAddOp2(v, OP_Rewind, iTab, 0);
86920   regRecord = sqlite3GetTempReg(pParse);
86921 
86922   sqlite3GenerateIndexKey(pParse, pIndex, iTab, regRecord, 0, &iPartIdxLabel);
86923   sqlite3VdbeAddOp2(v, OP_SorterInsert, iSorter, regRecord);
86924   sqlite3VdbeResolveLabel(v, iPartIdxLabel);
86925   sqlite3VdbeAddOp2(v, OP_Next, iTab, addr1+1);
86926   sqlite3VdbeJumpHere(v, addr1);
86927   if( memRootPage<0 ) sqlite3VdbeAddOp2(v, OP_Clear, tnum, iDb);
86928   sqlite3VdbeAddOp4(v, OP_OpenWrite, iIdx, tnum, iDb, 
86929                     (char *)pKey, P4_KEYINFO);
86930   sqlite3VdbeChangeP5(v, OPFLAG_BULKCSR|((memRootPage>=0)?OPFLAG_P2ISREG:0));
86931 
86932   addr1 = sqlite3VdbeAddOp2(v, OP_SorterSort, iSorter, 0);
86933   assert( pKey!=0 || db->mallocFailed || pParse->nErr );
86934   if( pIndex->onError!=OE_None && pKey!=0 ){
86935     int j2 = sqlite3VdbeCurrentAddr(v) + 3;
86936     sqlite3VdbeAddOp2(v, OP_Goto, 0, j2);
86937     addr2 = sqlite3VdbeCurrentAddr(v);
86938     sqlite3VdbeAddOp4Int(v, OP_SorterCompare, iSorter, j2, regRecord,
86939                          pKey->nField - pIndex->nKeyCol);
86940     sqlite3UniqueConstraint(pParse, OE_Abort, pIndex);
86941   }else{
86942     addr2 = sqlite3VdbeCurrentAddr(v);
86943   }
86944   sqlite3VdbeAddOp2(v, OP_SorterData, iSorter, regRecord);
86945   sqlite3VdbeAddOp3(v, OP_IdxInsert, iIdx, regRecord, 1);
86946   sqlite3VdbeChangeP5(v, OPFLAG_USESEEKRESULT);
86947   sqlite3ReleaseTempReg(pParse, regRecord);
86948   sqlite3VdbeAddOp2(v, OP_SorterNext, iSorter, addr2);
86949   sqlite3VdbeJumpHere(v, addr1);
86950 
86951   sqlite3VdbeAddOp1(v, OP_Close, iTab);
86952   sqlite3VdbeAddOp1(v, OP_Close, iIdx);
86953   sqlite3VdbeAddOp1(v, OP_Close, iSorter);
86954 }
86955 
86956 /*
86957 ** Allocate heap space to hold an Index object with nCol columns.
86958 **
86959 ** Increase the allocation size to provide an extra nExtra bytes
86960 ** of 8-byte aligned space after the Index object and return a
86961 ** pointer to this extra space in *ppExtra.
86962 */
86963 SQLITE_PRIVATE Index *sqlite3AllocateIndexObject(
86964   sqlite3 *db,         /* Database connection */
86965   i16 nCol,            /* Total number of columns in the index */
86966   int nExtra,          /* Number of bytes of extra space to alloc */
86967   char **ppExtra       /* Pointer to the "extra" space */
86968 ){
86969   Index *p;            /* Allocated index object */
86970   int nByte;           /* Bytes of space for Index object + arrays */
86971 
86972   nByte = ROUND8(sizeof(Index)) +              /* Index structure  */
86973           ROUND8(sizeof(char*)*nCol) +         /* Index.azColl     */
86974           ROUND8(sizeof(tRowcnt)*(nCol+1) +    /* Index.aiRowEst   */
86975                  sizeof(i16)*nCol +            /* Index.aiColumn   */
86976                  sizeof(u8)*nCol);             /* Index.aSortOrder */
86977   p = sqlite3DbMallocZero(db, nByte + nExtra);
86978   if( p ){
86979     char *pExtra = ((char*)p)+ROUND8(sizeof(Index));
86980     p->azColl = (char**)pExtra;      pExtra += ROUND8(sizeof(char*)*nCol);
86981     p->aiRowEst = (tRowcnt*)pExtra;  pExtra += sizeof(tRowcnt)*(nCol+1);
86982     p->aiColumn = (i16*)pExtra;      pExtra += sizeof(i16)*nCol;
86983     p->aSortOrder = (u8*)pExtra;
86984     p->nColumn = nCol;
86985     p->nKeyCol = nCol - 1;
86986     *ppExtra = ((char*)p) + nByte;
86987   }
86988   return p;
86989 }
86990 
86991 /*
86992 ** Create a new index for an SQL table.  pName1.pName2 is the name of the index 
86993 ** and pTblList is the name of the table that is to be indexed.  Both will 
86994 ** be NULL for a primary key or an index that is created to satisfy a
86995 ** UNIQUE constraint.  If pTable and pIndex are NULL, use pParse->pNewTable
86996 ** as the table to be indexed.  pParse->pNewTable is a table that is
86997 ** currently being constructed by a CREATE TABLE statement.
86998 **
86999 ** pList is a list of columns to be indexed.  pList will be NULL if this
87000 ** is a primary key or unique-constraint on the most recent column added
87001 ** to the table currently under construction.  
87002 **
87003 ** If the index is created successfully, return a pointer to the new Index
87004 ** structure. This is used by sqlite3AddPrimaryKey() to mark the index
87005 ** as the tables primary key (Index.autoIndex==2).
87006 */
87007 SQLITE_PRIVATE Index *sqlite3CreateIndex(
87008   Parse *pParse,     /* All information about this parse */
87009   Token *pName1,     /* First part of index name. May be NULL */
87010   Token *pName2,     /* Second part of index name. May be NULL */
87011   SrcList *pTblName, /* Table to index. Use pParse->pNewTable if 0 */
87012   ExprList *pList,   /* A list of columns to be indexed */
87013   int onError,       /* OE_Abort, OE_Ignore, OE_Replace, or OE_None */
87014   Token *pStart,     /* The CREATE token that begins this statement */
87015   Expr *pPIWhere,    /* WHERE clause for partial indices */
87016   int sortOrder,     /* Sort order of primary key when pList==NULL */
87017   int ifNotExist     /* Omit error if index already exists */
87018 ){
87019   Index *pRet = 0;     /* Pointer to return */
87020   Table *pTab = 0;     /* Table to be indexed */
87021   Index *pIndex = 0;   /* The index to be created */
87022   char *zName = 0;     /* Name of the index */
87023   int nName;           /* Number of characters in zName */
87024   int i, j;
87025   DbFixer sFix;        /* For assigning database names to pTable */
87026   int sortOrderMask;   /* 1 to honor DESC in index.  0 to ignore. */
87027   sqlite3 *db = pParse->db;
87028   Db *pDb;             /* The specific table containing the indexed database */
87029   int iDb;             /* Index of the database that is being written */
87030   Token *pName = 0;    /* Unqualified name of the index to create */
87031   struct ExprList_item *pListItem; /* For looping over pList */
87032   const Column *pTabCol;           /* A column in the table */
87033   int nExtra = 0;                  /* Space allocated for zExtra[] */
87034   int nExtraCol;                   /* Number of extra columns needed */
87035   char *zExtra = 0;                /* Extra space after the Index object */
87036   Index *pPk = 0;      /* PRIMARY KEY index for WITHOUT ROWID tables */
87037 
87038   assert( pParse->nErr==0 );      /* Never called with prior errors */
87039   if( db->mallocFailed || IN_DECLARE_VTAB ){
87040     goto exit_create_index;
87041   }
87042   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
87043     goto exit_create_index;
87044   }
87045 
87046   /*
87047   ** Find the table that is to be indexed.  Return early if not found.
87048   */
87049   if( pTblName!=0 ){
87050 
87051     /* Use the two-part index name to determine the database 
87052     ** to search for the table. 'Fix' the table name to this db
87053     ** before looking up the table.
87054     */
87055     assert( pName1 && pName2 );
87056     iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pName);
87057     if( iDb<0 ) goto exit_create_index;
87058     assert( pName && pName->z );
87059 
87060 #ifndef SQLITE_OMIT_TEMPDB
87061     /* If the index name was unqualified, check if the table
87062     ** is a temp table. If so, set the database to 1. Do not do this
87063     ** if initialising a database schema.
87064     */
87065     if( !db->init.busy ){
87066       pTab = sqlite3SrcListLookup(pParse, pTblName);
87067       if( pName2->n==0 && pTab && pTab->pSchema==db->aDb[1].pSchema ){
87068         iDb = 1;
87069       }
87070     }
87071 #endif
87072 
87073     sqlite3FixInit(&sFix, pParse, iDb, "index", pName);
87074     if( sqlite3FixSrcList(&sFix, pTblName) ){
87075       /* Because the parser constructs pTblName from a single identifier,
87076       ** sqlite3FixSrcList can never fail. */
87077       assert(0);
87078     }
87079     pTab = sqlite3LocateTableItem(pParse, 0, &pTblName->a[0]);
87080     assert( db->mallocFailed==0 || pTab==0 );
87081     if( pTab==0 ) goto exit_create_index;
87082     if( iDb==1 && db->aDb[iDb].pSchema!=pTab->pSchema ){
87083       sqlite3ErrorMsg(pParse, 
87084            "cannot create a TEMP index on non-TEMP table \"%s\"",
87085            pTab->zName);
87086       goto exit_create_index;
87087     }
87088     if( !HasRowid(pTab) ) pPk = sqlite3PrimaryKeyIndex(pTab);
87089   }else{
87090     assert( pName==0 );
87091     assert( pStart==0 );
87092     pTab = pParse->pNewTable;
87093     if( !pTab ) goto exit_create_index;
87094     iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
87095   }
87096   pDb = &db->aDb[iDb];
87097 
87098   assert( pTab!=0 );
87099   assert( pParse->nErr==0 );
87100   if( sqlite3StrNICmp(pTab->zName, "sqlite_", 7)==0 
87101        && sqlite3StrNICmp(&pTab->zName[7],"altertab_",9)!=0 ){
87102     sqlite3ErrorMsg(pParse, "table %s may not be indexed", pTab->zName);
87103     goto exit_create_index;
87104   }
87105 #ifndef SQLITE_OMIT_VIEW
87106   if( pTab->pSelect ){
87107     sqlite3ErrorMsg(pParse, "views may not be indexed");
87108     goto exit_create_index;
87109   }
87110 #endif
87111 #ifndef SQLITE_OMIT_VIRTUALTABLE
87112   if( IsVirtual(pTab) ){
87113     sqlite3ErrorMsg(pParse, "virtual tables may not be indexed");
87114     goto exit_create_index;
87115   }
87116 #endif
87117 
87118   /*
87119   ** Find the name of the index.  Make sure there is not already another
87120   ** index or table with the same name.  
87121   **
87122   ** Exception:  If we are reading the names of permanent indices from the
87123   ** sqlite_master table (because some other process changed the schema) and
87124   ** one of the index names collides with the name of a temporary table or
87125   ** index, then we will continue to process this index.
87126   **
87127   ** If pName==0 it means that we are
87128   ** dealing with a primary key or UNIQUE constraint.  We have to invent our
87129   ** own name.
87130   */
87131   if( pName ){
87132     zName = sqlite3NameFromToken(db, pName);
87133     if( zName==0 ) goto exit_create_index;
87134     assert( pName->z!=0 );
87135     if( SQLITE_OK!=sqlite3CheckObjectName(pParse, zName) ){
87136       goto exit_create_index;
87137     }
87138     if( !db->init.busy ){
87139       if( sqlite3FindTable(db, zName, 0)!=0 ){
87140         sqlite3ErrorMsg(pParse, "there is already a table named %s", zName);
87141         goto exit_create_index;
87142       }
87143     }
87144     if( sqlite3FindIndex(db, zName, pDb->zName)!=0 ){
87145       if( !ifNotExist ){
87146         sqlite3ErrorMsg(pParse, "index %s already exists", zName);
87147       }else{
87148         assert( !db->init.busy );
87149         sqlite3CodeVerifySchema(pParse, iDb);
87150       }
87151       goto exit_create_index;
87152     }
87153   }else{
87154     int n;
87155     Index *pLoop;
87156     for(pLoop=pTab->pIndex, n=1; pLoop; pLoop=pLoop->pNext, n++){}
87157     zName = sqlite3MPrintf(db, "sqlite_autoindex_%s_%d", pTab->zName, n);
87158     if( zName==0 ){
87159       goto exit_create_index;
87160     }
87161   }
87162 
87163   /* Check for authorization to create an index.
87164   */
87165 #ifndef SQLITE_OMIT_AUTHORIZATION
87166   {
87167     const char *zDb = pDb->zName;
87168     if( sqlite3AuthCheck(pParse, SQLITE_INSERT, SCHEMA_TABLE(iDb), 0, zDb) ){
87169       goto exit_create_index;
87170     }
87171     i = SQLITE_CREATE_INDEX;
87172     if( !OMIT_TEMPDB && iDb==1 ) i = SQLITE_CREATE_TEMP_INDEX;
87173     if( sqlite3AuthCheck(pParse, i, zName, pTab->zName, zDb) ){
87174       goto exit_create_index;
87175     }
87176   }
87177 #endif
87178 
87179   /* If pList==0, it means this routine was called to make a primary
87180   ** key out of the last column added to the table under construction.
87181   ** So create a fake list to simulate this.
87182   */
87183   if( pList==0 ){
87184     pList = sqlite3ExprListAppend(pParse, 0, 0);
87185     if( pList==0 ) goto exit_create_index;
87186     pList->a[0].zName = sqlite3DbStrDup(pParse->db,
87187                                         pTab->aCol[pTab->nCol-1].zName);
87188     pList->a[0].sortOrder = (u8)sortOrder;
87189   }
87190 
87191   /* Figure out how many bytes of space are required to store explicitly
87192   ** specified collation sequence names.
87193   */
87194   for(i=0; i<pList->nExpr; i++){
87195     Expr *pExpr = pList->a[i].pExpr;
87196     if( pExpr ){
87197       assert( pExpr->op==TK_COLLATE );
87198       nExtra += (1 + sqlite3Strlen30(pExpr->u.zToken));
87199     }
87200   }
87201 
87202   /* 
87203   ** Allocate the index structure. 
87204   */
87205   nName = sqlite3Strlen30(zName);
87206   nExtraCol = pPk ? pPk->nKeyCol : 1;
87207   pIndex = sqlite3AllocateIndexObject(db, pList->nExpr + nExtraCol,
87208                                       nName + nExtra + 1, &zExtra);
87209   if( db->mallocFailed ){
87210     goto exit_create_index;
87211   }
87212   assert( EIGHT_BYTE_ALIGNMENT(pIndex->aiRowEst) );
87213   assert( EIGHT_BYTE_ALIGNMENT(pIndex->azColl) );
87214   pIndex->zName = zExtra;
87215   zExtra += nName + 1;
87216   memcpy(pIndex->zName, zName, nName+1);
87217   pIndex->pTable = pTab;
87218   pIndex->onError = (u8)onError;
87219   pIndex->uniqNotNull = onError!=OE_None;
87220   pIndex->autoIndex = (u8)(pName==0);
87221   pIndex->pSchema = db->aDb[iDb].pSchema;
87222   pIndex->nKeyCol = pList->nExpr;
87223   if( pPIWhere ){
87224     sqlite3ResolveSelfReference(pParse, pTab, NC_PartIdx, pPIWhere, 0);
87225     pIndex->pPartIdxWhere = pPIWhere;
87226     pPIWhere = 0;
87227   }
87228   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
87229 
87230   /* Check to see if we should honor DESC requests on index columns
87231   */
87232   if( pDb->pSchema->file_format>=4 ){
87233     sortOrderMask = -1;   /* Honor DESC */
87234   }else{
87235     sortOrderMask = 0;    /* Ignore DESC */
87236   }
87237 
87238   /* Scan the names of the columns of the table to be indexed and
87239   ** load the column indices into the Index structure.  Report an error
87240   ** if any column is not found.
87241   **
87242   ** TODO:  Add a test to make sure that the same column is not named
87243   ** more than once within the same index.  Only the first instance of
87244   ** the column will ever be used by the optimizer.  Note that using the
87245   ** same column more than once cannot be an error because that would 
87246   ** break backwards compatibility - it needs to be a warning.
87247   */
87248   for(i=0, pListItem=pList->a; i<pList->nExpr; i++, pListItem++){
87249     const char *zColName = pListItem->zName;
87250     int requestedSortOrder;
87251     char *zColl;                   /* Collation sequence name */
87252 
87253     for(j=0, pTabCol=pTab->aCol; j<pTab->nCol; j++, pTabCol++){
87254       if( sqlite3StrICmp(zColName, pTabCol->zName)==0 ) break;
87255     }
87256     if( j>=pTab->nCol ){
87257       sqlite3ErrorMsg(pParse, "table %s has no column named %s",
87258         pTab->zName, zColName);
87259       pParse->checkSchema = 1;
87260       goto exit_create_index;
87261     }
87262     assert( pTab->nCol<=0x7fff && j<=0x7fff );
87263     pIndex->aiColumn[i] = (i16)j;
87264     if( pListItem->pExpr ){
87265       int nColl;
87266       assert( pListItem->pExpr->op==TK_COLLATE );
87267       zColl = pListItem->pExpr->u.zToken;
87268       nColl = sqlite3Strlen30(zColl) + 1;
87269       assert( nExtra>=nColl );
87270       memcpy(zExtra, zColl, nColl);
87271       zColl = zExtra;
87272       zExtra += nColl;
87273       nExtra -= nColl;
87274     }else{
87275       zColl = pTab->aCol[j].zColl;
87276       if( !zColl ) zColl = "BINARY";
87277     }
87278     if( !db->init.busy && !sqlite3LocateCollSeq(pParse, zColl) ){
87279       goto exit_create_index;
87280     }
87281     pIndex->azColl[i] = zColl;
87282     requestedSortOrder = pListItem->sortOrder & sortOrderMask;
87283     pIndex->aSortOrder[i] = (u8)requestedSortOrder;
87284     if( pTab->aCol[j].notNull==0 ) pIndex->uniqNotNull = 0;
87285   }
87286   if( pPk ){
87287     for(j=0; j<pPk->nKeyCol; j++){
87288       int x = pPk->aiColumn[j];
87289       if( hasColumn(pIndex->aiColumn, pIndex->nKeyCol, x) ){
87290         pIndex->nColumn--; 
87291       }else{
87292         pIndex->aiColumn[i] = x;
87293         pIndex->azColl[i] = pPk->azColl[j];
87294         pIndex->aSortOrder[i] = pPk->aSortOrder[j];
87295         i++;
87296       }
87297     }
87298     assert( i==pIndex->nColumn );
87299   }else{
87300     pIndex->aiColumn[i] = -1;
87301     pIndex->azColl[i] = "BINARY";
87302   }
87303   sqlite3DefaultRowEst(pIndex);
87304   if( pParse->pNewTable==0 ) estimateIndexWidth(pIndex);
87305 
87306   if( pTab==pParse->pNewTable ){
87307     /* This routine has been called to create an automatic index as a
87308     ** result of a PRIMARY KEY or UNIQUE clause on a column definition, or
87309     ** a PRIMARY KEY or UNIQUE clause following the column definitions.
87310     ** i.e. one of:
87311     **
87312     ** CREATE TABLE t(x PRIMARY KEY, y);
87313     ** CREATE TABLE t(x, y, UNIQUE(x, y));
87314     **
87315     ** Either way, check to see if the table already has such an index. If
87316     ** so, don't bother creating this one. This only applies to
87317     ** automatically created indices. Users can do as they wish with
87318     ** explicit indices.
87319     **
87320     ** Two UNIQUE or PRIMARY KEY constraints are considered equivalent
87321     ** (and thus suppressing the second one) even if they have different
87322     ** sort orders.
87323     **
87324     ** If there are different collating sequences or if the columns of
87325     ** the constraint occur in different orders, then the constraints are
87326     ** considered distinct and both result in separate indices.
87327     */
87328     Index *pIdx;
87329     for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
87330       int k;
87331       assert( pIdx->onError!=OE_None );
87332       assert( pIdx->autoIndex );
87333       assert( pIndex->onError!=OE_None );
87334 
87335       if( pIdx->nKeyCol!=pIndex->nKeyCol ) continue;
87336       for(k=0; k<pIdx->nKeyCol; k++){
87337         const char *z1;
87338         const char *z2;
87339         if( pIdx->aiColumn[k]!=pIndex->aiColumn[k] ) break;
87340         z1 = pIdx->azColl[k];
87341         z2 = pIndex->azColl[k];
87342         if( z1!=z2 && sqlite3StrICmp(z1, z2) ) break;
87343       }
87344       if( k==pIdx->nKeyCol ){
87345         if( pIdx->onError!=pIndex->onError ){
87346           /* This constraint creates the same index as a previous
87347           ** constraint specified somewhere in the CREATE TABLE statement.
87348           ** However the ON CONFLICT clauses are different. If both this 
87349           ** constraint and the previous equivalent constraint have explicit
87350           ** ON CONFLICT clauses this is an error. Otherwise, use the
87351           ** explicitly specified behavior for the index.
87352           */
87353           if( !(pIdx->onError==OE_Default || pIndex->onError==OE_Default) ){
87354             sqlite3ErrorMsg(pParse, 
87355                 "conflicting ON CONFLICT clauses specified", 0);
87356           }
87357           if( pIdx->onError==OE_Default ){
87358             pIdx->onError = pIndex->onError;
87359           }
87360         }
87361         goto exit_create_index;
87362       }
87363     }
87364   }
87365 
87366   /* Link the new Index structure to its table and to the other
87367   ** in-memory database structures. 
87368   */
87369   if( db->init.busy ){
87370     Index *p;
87371     assert( sqlite3SchemaMutexHeld(db, 0, pIndex->pSchema) );
87372     p = sqlite3HashInsert(&pIndex->pSchema->idxHash, 
87373                           pIndex->zName, sqlite3Strlen30(pIndex->zName),
87374                           pIndex);
87375     if( p ){
87376       assert( p==pIndex );  /* Malloc must have failed */
87377       db->mallocFailed = 1;
87378       goto exit_create_index;
87379     }
87380     db->flags |= SQLITE_InternChanges;
87381     if( pTblName!=0 ){
87382       pIndex->tnum = db->init.newTnum;
87383     }
87384   }
87385 
87386   /* If this is the initial CREATE INDEX statement (or CREATE TABLE if the
87387   ** index is an implied index for a UNIQUE or PRIMARY KEY constraint) then
87388   ** emit code to allocate the index rootpage on disk and make an entry for
87389   ** the index in the sqlite_master table and populate the index with
87390   ** content.  But, do not do this if we are simply reading the sqlite_master
87391   ** table to parse the schema, or if this index is the PRIMARY KEY index
87392   ** of a WITHOUT ROWID table.
87393   **
87394   ** If pTblName==0 it means this index is generated as an implied PRIMARY KEY
87395   ** or UNIQUE index in a CREATE TABLE statement.  Since the table
87396   ** has just been created, it contains no data and the index initialization
87397   ** step can be skipped.
87398   */
87399   else if( pParse->nErr==0 && (HasRowid(pTab) || pTblName!=0) ){
87400     Vdbe *v;
87401     char *zStmt;
87402     int iMem = ++pParse->nMem;
87403 
87404     v = sqlite3GetVdbe(pParse);
87405     if( v==0 ) goto exit_create_index;
87406 
87407 
87408     /* Create the rootpage for the index
87409     */
87410     sqlite3BeginWriteOperation(pParse, 1, iDb);
87411     sqlite3VdbeAddOp2(v, OP_CreateIndex, iDb, iMem);
87412 
87413     /* Gather the complete text of the CREATE INDEX statement into
87414     ** the zStmt variable
87415     */
87416     if( pStart ){
87417       int n = (int)(pParse->sLastToken.z - pName->z) + pParse->sLastToken.n;
87418       if( pName->z[n-1]==';' ) n--;
87419       /* A named index with an explicit CREATE INDEX statement */
87420       zStmt = sqlite3MPrintf(db, "CREATE%s INDEX %.*s",
87421         onError==OE_None ? "" : " UNIQUE", n, pName->z);
87422     }else{
87423       /* An automatic index created by a PRIMARY KEY or UNIQUE constraint */
87424       /* zStmt = sqlite3MPrintf(""); */
87425       zStmt = 0;
87426     }
87427 
87428     /* Add an entry in sqlite_master for this index
87429     */
87430     sqlite3NestedParse(pParse, 
87431         "INSERT INTO %Q.%s VALUES('index',%Q,%Q,#%d,%Q);",
87432         db->aDb[iDb].zName, SCHEMA_TABLE(iDb),
87433         pIndex->zName,
87434         pTab->zName,
87435         iMem,
87436         zStmt
87437     );
87438     sqlite3DbFree(db, zStmt);
87439 
87440     /* Fill the index with data and reparse the schema. Code an OP_Expire
87441     ** to invalidate all pre-compiled statements.
87442     */
87443     if( pTblName ){
87444       sqlite3RefillIndex(pParse, pIndex, iMem);
87445       sqlite3ChangeCookie(pParse, iDb);
87446       sqlite3VdbeAddParseSchemaOp(v, iDb,
87447          sqlite3MPrintf(db, "name='%q' AND type='index'", pIndex->zName));
87448       sqlite3VdbeAddOp1(v, OP_Expire, 0);
87449     }
87450   }
87451 
87452   /* When adding an index to the list of indices for a table, make
87453   ** sure all indices labeled OE_Replace come after all those labeled
87454   ** OE_Ignore.  This is necessary for the correct constraint check
87455   ** processing (in sqlite3GenerateConstraintChecks()) as part of
87456   ** UPDATE and INSERT statements.  
87457   */
87458   if( db->init.busy || pTblName==0 ){
87459     if( onError!=OE_Replace || pTab->pIndex==0
87460          || pTab->pIndex->onError==OE_Replace){
87461       pIndex->pNext = pTab->pIndex;
87462       pTab->pIndex = pIndex;
87463     }else{
87464       Index *pOther = pTab->pIndex;
87465       while( pOther->pNext && pOther->pNext->onError!=OE_Replace ){
87466         pOther = pOther->pNext;
87467       }
87468       pIndex->pNext = pOther->pNext;
87469       pOther->pNext = pIndex;
87470     }
87471     pRet = pIndex;
87472     pIndex = 0;
87473   }
87474 
87475   /* Clean up before exiting */
87476 exit_create_index:
87477   if( pIndex ) freeIndex(db, pIndex);
87478   sqlite3ExprDelete(db, pPIWhere);
87479   sqlite3ExprListDelete(db, pList);
87480   sqlite3SrcListDelete(db, pTblName);
87481   sqlite3DbFree(db, zName);
87482   return pRet;
87483 }
87484 
87485 /*
87486 ** Fill the Index.aiRowEst[] array with default information - information
87487 ** to be used when we have not run the ANALYZE command.
87488 **
87489 ** aiRowEst[0] is suppose to contain the number of elements in the index.
87490 ** Since we do not know, guess 1 million.  aiRowEst[1] is an estimate of the
87491 ** number of rows in the table that match any particular value of the
87492 ** first column of the index.  aiRowEst[2] is an estimate of the number
87493 ** of rows that match any particular combiniation of the first 2 columns
87494 ** of the index.  And so forth.  It must always be the case that
87495 *
87496 **           aiRowEst[N]<=aiRowEst[N-1]
87497 **           aiRowEst[N]>=1
87498 **
87499 ** Apart from that, we have little to go on besides intuition as to
87500 ** how aiRowEst[] should be initialized.  The numbers generated here
87501 ** are based on typical values found in actual indices.
87502 */
87503 SQLITE_PRIVATE void sqlite3DefaultRowEst(Index *pIdx){
87504   tRowcnt *a = pIdx->aiRowEst;
87505   int i;
87506   tRowcnt n;
87507   assert( a!=0 );
87508   a[0] = pIdx->pTable->nRowEst;
87509   if( a[0]<10 ) a[0] = 10;
87510   n = 10;
87511   for(i=1; i<=pIdx->nKeyCol; i++){
87512     a[i] = n;
87513     if( n>5 ) n--;
87514   }
87515   if( pIdx->onError!=OE_None ){
87516     a[pIdx->nKeyCol] = 1;
87517   }
87518 }
87519 
87520 /*
87521 ** This routine will drop an existing named index.  This routine
87522 ** implements the DROP INDEX statement.
87523 */
87524 SQLITE_PRIVATE void sqlite3DropIndex(Parse *pParse, SrcList *pName, int ifExists){
87525   Index *pIndex;
87526   Vdbe *v;
87527   sqlite3 *db = pParse->db;
87528   int iDb;
87529 
87530   assert( pParse->nErr==0 );   /* Never called with prior errors */
87531   if( db->mallocFailed ){
87532     goto exit_drop_index;
87533   }
87534   assert( pName->nSrc==1 );
87535   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
87536     goto exit_drop_index;
87537   }
87538   pIndex = sqlite3FindIndex(db, pName->a[0].zName, pName->a[0].zDatabase);
87539   if( pIndex==0 ){
87540     if( !ifExists ){
87541       sqlite3ErrorMsg(pParse, "no such index: %S", pName, 0);
87542     }else{
87543       sqlite3CodeVerifyNamedSchema(pParse, pName->a[0].zDatabase);
87544     }
87545     pParse->checkSchema = 1;
87546     goto exit_drop_index;
87547   }
87548   if( pIndex->autoIndex ){
87549     sqlite3ErrorMsg(pParse, "index associated with UNIQUE "
87550       "or PRIMARY KEY constraint cannot be dropped", 0);
87551     goto exit_drop_index;
87552   }
87553   iDb = sqlite3SchemaToIndex(db, pIndex->pSchema);
87554 #ifndef SQLITE_OMIT_AUTHORIZATION
87555   {
87556     int code = SQLITE_DROP_INDEX;
87557     Table *pTab = pIndex->pTable;
87558     const char *zDb = db->aDb[iDb].zName;
87559     const char *zTab = SCHEMA_TABLE(iDb);
87560     if( sqlite3AuthCheck(pParse, SQLITE_DELETE, zTab, 0, zDb) ){
87561       goto exit_drop_index;
87562     }
87563     if( !OMIT_TEMPDB && iDb ) code = SQLITE_DROP_TEMP_INDEX;
87564     if( sqlite3AuthCheck(pParse, code, pIndex->zName, pTab->zName, zDb) ){
87565       goto exit_drop_index;
87566     }
87567   }
87568 #endif
87569 
87570   /* Generate code to remove the index and from the master table */
87571   v = sqlite3GetVdbe(pParse);
87572   if( v ){
87573     sqlite3BeginWriteOperation(pParse, 1, iDb);
87574     sqlite3NestedParse(pParse,
87575        "DELETE FROM %Q.%s WHERE name=%Q AND type='index'",
87576        db->aDb[iDb].zName, SCHEMA_TABLE(iDb), pIndex->zName
87577     );
87578     sqlite3ClearStatTables(pParse, iDb, "idx", pIndex->zName);
87579     sqlite3ChangeCookie(pParse, iDb);
87580     destroyRootPage(pParse, pIndex->tnum, iDb);
87581     sqlite3VdbeAddOp4(v, OP_DropIndex, iDb, 0, 0, pIndex->zName, 0);
87582   }
87583 
87584 exit_drop_index:
87585   sqlite3SrcListDelete(db, pName);
87586 }
87587 
87588 /*
87589 ** pArray is a pointer to an array of objects. Each object in the
87590 ** array is szEntry bytes in size. This routine uses sqlite3DbRealloc()
87591 ** to extend the array so that there is space for a new object at the end.
87592 **
87593 ** When this function is called, *pnEntry contains the current size of
87594 ** the array (in entries - so the allocation is ((*pnEntry) * szEntry) bytes
87595 ** in total).
87596 **
87597 ** If the realloc() is successful (i.e. if no OOM condition occurs), the
87598 ** space allocated for the new object is zeroed, *pnEntry updated to
87599 ** reflect the new size of the array and a pointer to the new allocation
87600 ** returned. *pIdx is set to the index of the new array entry in this case.
87601 **
87602 ** Otherwise, if the realloc() fails, *pIdx is set to -1, *pnEntry remains
87603 ** unchanged and a copy of pArray returned.
87604 */
87605 SQLITE_PRIVATE void *sqlite3ArrayAllocate(
87606   sqlite3 *db,      /* Connection to notify of malloc failures */
87607   void *pArray,     /* Array of objects.  Might be reallocated */
87608   int szEntry,      /* Size of each object in the array */
87609   int *pnEntry,     /* Number of objects currently in use */
87610   int *pIdx         /* Write the index of a new slot here */
87611 ){
87612   char *z;
87613   int n = *pnEntry;
87614   if( (n & (n-1))==0 ){
87615     int sz = (n==0) ? 1 : 2*n;
87616     void *pNew = sqlite3DbRealloc(db, pArray, sz*szEntry);
87617     if( pNew==0 ){
87618       *pIdx = -1;
87619       return pArray;
87620     }
87621     pArray = pNew;
87622   }
87623   z = (char*)pArray;
87624   memset(&z[n * szEntry], 0, szEntry);
87625   *pIdx = n;
87626   ++*pnEntry;
87627   return pArray;
87628 }
87629 
87630 /*
87631 ** Append a new element to the given IdList.  Create a new IdList if
87632 ** need be.
87633 **
87634 ** A new IdList is returned, or NULL if malloc() fails.
87635 */
87636 SQLITE_PRIVATE IdList *sqlite3IdListAppend(sqlite3 *db, IdList *pList, Token *pToken){
87637   int i;
87638   if( pList==0 ){
87639     pList = sqlite3DbMallocZero(db, sizeof(IdList) );
87640     if( pList==0 ) return 0;
87641   }
87642   pList->a = sqlite3ArrayAllocate(
87643       db,
87644       pList->a,
87645       sizeof(pList->a[0]),
87646       &pList->nId,
87647       &i
87648   );
87649   if( i<0 ){
87650     sqlite3IdListDelete(db, pList);
87651     return 0;
87652   }
87653   pList->a[i].zName = sqlite3NameFromToken(db, pToken);
87654   return pList;
87655 }
87656 
87657 /*
87658 ** Delete an IdList.
87659 */
87660 SQLITE_PRIVATE void sqlite3IdListDelete(sqlite3 *db, IdList *pList){
87661   int i;
87662   if( pList==0 ) return;
87663   for(i=0; i<pList->nId; i++){
87664     sqlite3DbFree(db, pList->a[i].zName);
87665   }
87666   sqlite3DbFree(db, pList->a);
87667   sqlite3DbFree(db, pList);
87668 }
87669 
87670 /*
87671 ** Return the index in pList of the identifier named zId.  Return -1
87672 ** if not found.
87673 */
87674 SQLITE_PRIVATE int sqlite3IdListIndex(IdList *pList, const char *zName){
87675   int i;
87676   if( pList==0 ) return -1;
87677   for(i=0; i<pList->nId; i++){
87678     if( sqlite3StrICmp(pList->a[i].zName, zName)==0 ) return i;
87679   }
87680   return -1;
87681 }
87682 
87683 /*
87684 ** Expand the space allocated for the given SrcList object by
87685 ** creating nExtra new slots beginning at iStart.  iStart is zero based.
87686 ** New slots are zeroed.
87687 **
87688 ** For example, suppose a SrcList initially contains two entries: A,B.
87689 ** To append 3 new entries onto the end, do this:
87690 **
87691 **    sqlite3SrcListEnlarge(db, pSrclist, 3, 2);
87692 **
87693 ** After the call above it would contain:  A, B, nil, nil, nil.
87694 ** If the iStart argument had been 1 instead of 2, then the result
87695 ** would have been:  A, nil, nil, nil, B.  To prepend the new slots,
87696 ** the iStart value would be 0.  The result then would
87697 ** be: nil, nil, nil, A, B.
87698 **
87699 ** If a memory allocation fails the SrcList is unchanged.  The
87700 ** db->mallocFailed flag will be set to true.
87701 */
87702 SQLITE_PRIVATE SrcList *sqlite3SrcListEnlarge(
87703   sqlite3 *db,       /* Database connection to notify of OOM errors */
87704   SrcList *pSrc,     /* The SrcList to be enlarged */
87705   int nExtra,        /* Number of new slots to add to pSrc->a[] */
87706   int iStart         /* Index in pSrc->a[] of first new slot */
87707 ){
87708   int i;
87709 
87710   /* Sanity checking on calling parameters */
87711   assert( iStart>=0 );
87712   assert( nExtra>=1 );
87713   assert( pSrc!=0 );
87714   assert( iStart<=pSrc->nSrc );
87715 
87716   /* Allocate additional space if needed */
87717   if( pSrc->nSrc+nExtra>pSrc->nAlloc ){
87718     SrcList *pNew;
87719     int nAlloc = pSrc->nSrc+nExtra;
87720     int nGot;
87721     pNew = sqlite3DbRealloc(db, pSrc,
87722                sizeof(*pSrc) + (nAlloc-1)*sizeof(pSrc->a[0]) );
87723     if( pNew==0 ){
87724       assert( db->mallocFailed );
87725       return pSrc;
87726     }
87727     pSrc = pNew;
87728     nGot = (sqlite3DbMallocSize(db, pNew) - sizeof(*pSrc))/sizeof(pSrc->a[0])+1;
87729     pSrc->nAlloc = (u8)nGot;
87730   }
87731 
87732   /* Move existing slots that come after the newly inserted slots
87733   ** out of the way */
87734   for(i=pSrc->nSrc-1; i>=iStart; i--){
87735     pSrc->a[i+nExtra] = pSrc->a[i];
87736   }
87737   pSrc->nSrc += (i8)nExtra;
87738 
87739   /* Zero the newly allocated slots */
87740   memset(&pSrc->a[iStart], 0, sizeof(pSrc->a[0])*nExtra);
87741   for(i=iStart; i<iStart+nExtra; i++){
87742     pSrc->a[i].iCursor = -1;
87743   }
87744 
87745   /* Return a pointer to the enlarged SrcList */
87746   return pSrc;
87747 }
87748 
87749 
87750 /*
87751 ** Append a new table name to the given SrcList.  Create a new SrcList if
87752 ** need be.  A new entry is created in the SrcList even if pTable is NULL.
87753 **
87754 ** A SrcList is returned, or NULL if there is an OOM error.  The returned
87755 ** SrcList might be the same as the SrcList that was input or it might be
87756 ** a new one.  If an OOM error does occurs, then the prior value of pList
87757 ** that is input to this routine is automatically freed.
87758 **
87759 ** If pDatabase is not null, it means that the table has an optional
87760 ** database name prefix.  Like this:  "database.table".  The pDatabase
87761 ** points to the table name and the pTable points to the database name.
87762 ** The SrcList.a[].zName field is filled with the table name which might
87763 ** come from pTable (if pDatabase is NULL) or from pDatabase.  
87764 ** SrcList.a[].zDatabase is filled with the database name from pTable,
87765 ** or with NULL if no database is specified.
87766 **
87767 ** In other words, if call like this:
87768 **
87769 **         sqlite3SrcListAppend(D,A,B,0);
87770 **
87771 ** Then B is a table name and the database name is unspecified.  If called
87772 ** like this:
87773 **
87774 **         sqlite3SrcListAppend(D,A,B,C);
87775 **
87776 ** Then C is the table name and B is the database name.  If C is defined
87777 ** then so is B.  In other words, we never have a case where:
87778 **
87779 **         sqlite3SrcListAppend(D,A,0,C);
87780 **
87781 ** Both pTable and pDatabase are assumed to be quoted.  They are dequoted
87782 ** before being added to the SrcList.
87783 */
87784 SQLITE_PRIVATE SrcList *sqlite3SrcListAppend(
87785   sqlite3 *db,        /* Connection to notify of malloc failures */
87786   SrcList *pList,     /* Append to this SrcList. NULL creates a new SrcList */
87787   Token *pTable,      /* Table to append */
87788   Token *pDatabase    /* Database of the table */
87789 ){
87790   struct SrcList_item *pItem;
87791   assert( pDatabase==0 || pTable!=0 );  /* Cannot have C without B */
87792   if( pList==0 ){
87793     pList = sqlite3DbMallocZero(db, sizeof(SrcList) );
87794     if( pList==0 ) return 0;
87795     pList->nAlloc = 1;
87796   }
87797   pList = sqlite3SrcListEnlarge(db, pList, 1, pList->nSrc);
87798   if( db->mallocFailed ){
87799     sqlite3SrcListDelete(db, pList);
87800     return 0;
87801   }
87802   pItem = &pList->a[pList->nSrc-1];
87803   if( pDatabase && pDatabase->z==0 ){
87804     pDatabase = 0;
87805   }
87806   if( pDatabase ){
87807     Token *pTemp = pDatabase;
87808     pDatabase = pTable;
87809     pTable = pTemp;
87810   }
87811   pItem->zName = sqlite3NameFromToken(db, pTable);
87812   pItem->zDatabase = sqlite3NameFromToken(db, pDatabase);
87813   return pList;
87814 }
87815 
87816 /*
87817 ** Assign VdbeCursor index numbers to all tables in a SrcList
87818 */
87819 SQLITE_PRIVATE void sqlite3SrcListAssignCursors(Parse *pParse, SrcList *pList){
87820   int i;
87821   struct SrcList_item *pItem;
87822   assert(pList || pParse->db->mallocFailed );
87823   if( pList ){
87824     for(i=0, pItem=pList->a; i<pList->nSrc; i++, pItem++){
87825       if( pItem->iCursor>=0 ) break;
87826       pItem->iCursor = pParse->nTab++;
87827       if( pItem->pSelect ){
87828         sqlite3SrcListAssignCursors(pParse, pItem->pSelect->pSrc);
87829       }
87830     }
87831   }
87832 }
87833 
87834 /*
87835 ** Delete an entire SrcList including all its substructure.
87836 */
87837 SQLITE_PRIVATE void sqlite3SrcListDelete(sqlite3 *db, SrcList *pList){
87838   int i;
87839   struct SrcList_item *pItem;
87840   if( pList==0 ) return;
87841   for(pItem=pList->a, i=0; i<pList->nSrc; i++, pItem++){
87842     sqlite3DbFree(db, pItem->zDatabase);
87843     sqlite3DbFree(db, pItem->zName);
87844     sqlite3DbFree(db, pItem->zAlias);
87845     sqlite3DbFree(db, pItem->zIndex);
87846     sqlite3DeleteTable(db, pItem->pTab);
87847     sqlite3SelectDelete(db, pItem->pSelect);
87848     sqlite3ExprDelete(db, pItem->pOn);
87849     sqlite3IdListDelete(db, pItem->pUsing);
87850   }
87851   sqlite3DbFree(db, pList);
87852 }
87853 
87854 /*
87855 ** This routine is called by the parser to add a new term to the
87856 ** end of a growing FROM clause.  The "p" parameter is the part of
87857 ** the FROM clause that has already been constructed.  "p" is NULL
87858 ** if this is the first term of the FROM clause.  pTable and pDatabase
87859 ** are the name of the table and database named in the FROM clause term.
87860 ** pDatabase is NULL if the database name qualifier is missing - the
87861 ** usual case.  If the term has a alias, then pAlias points to the
87862 ** alias token.  If the term is a subquery, then pSubquery is the
87863 ** SELECT statement that the subquery encodes.  The pTable and
87864 ** pDatabase parameters are NULL for subqueries.  The pOn and pUsing
87865 ** parameters are the content of the ON and USING clauses.
87866 **
87867 ** Return a new SrcList which encodes is the FROM with the new
87868 ** term added.
87869 */
87870 SQLITE_PRIVATE SrcList *sqlite3SrcListAppendFromTerm(
87871   Parse *pParse,          /* Parsing context */
87872   SrcList *p,             /* The left part of the FROM clause already seen */
87873   Token *pTable,          /* Name of the table to add to the FROM clause */
87874   Token *pDatabase,       /* Name of the database containing pTable */
87875   Token *pAlias,          /* The right-hand side of the AS subexpression */
87876   Select *pSubquery,      /* A subquery used in place of a table name */
87877   Expr *pOn,              /* The ON clause of a join */
87878   IdList *pUsing          /* The USING clause of a join */
87879 ){
87880   struct SrcList_item *pItem;
87881   sqlite3 *db = pParse->db;
87882   if( !p && (pOn || pUsing) ){
87883     sqlite3ErrorMsg(pParse, "a JOIN clause is required before %s", 
87884       (pOn ? "ON" : "USING")
87885     );
87886     goto append_from_error;
87887   }
87888   p = sqlite3SrcListAppend(db, p, pTable, pDatabase);
87889   if( p==0 || NEVER(p->nSrc==0) ){
87890     goto append_from_error;
87891   }
87892   pItem = &p->a[p->nSrc-1];
87893   assert( pAlias!=0 );
87894   if( pAlias->n ){
87895     pItem->zAlias = sqlite3NameFromToken(db, pAlias);
87896   }
87897   pItem->pSelect = pSubquery;
87898   pItem->pOn = pOn;
87899   pItem->pUsing = pUsing;
87900   return p;
87901 
87902  append_from_error:
87903   assert( p==0 );
87904   sqlite3ExprDelete(db, pOn);
87905   sqlite3IdListDelete(db, pUsing);
87906   sqlite3SelectDelete(db, pSubquery);
87907   return 0;
87908 }
87909 
87910 /*
87911 ** Add an INDEXED BY or NOT INDEXED clause to the most recently added 
87912 ** element of the source-list passed as the second argument.
87913 */
87914 SQLITE_PRIVATE void sqlite3SrcListIndexedBy(Parse *pParse, SrcList *p, Token *pIndexedBy){
87915   assert( pIndexedBy!=0 );
87916   if( p && ALWAYS(p->nSrc>0) ){
87917     struct SrcList_item *pItem = &p->a[p->nSrc-1];
87918     assert( pItem->notIndexed==0 && pItem->zIndex==0 );
87919     if( pIndexedBy->n==1 && !pIndexedBy->z ){
87920       /* A "NOT INDEXED" clause was supplied. See parse.y 
87921       ** construct "indexed_opt" for details. */
87922       pItem->notIndexed = 1;
87923     }else{
87924       pItem->zIndex = sqlite3NameFromToken(pParse->db, pIndexedBy);
87925     }
87926   }
87927 }
87928 
87929 /*
87930 ** When building up a FROM clause in the parser, the join operator
87931 ** is initially attached to the left operand.  But the code generator
87932 ** expects the join operator to be on the right operand.  This routine
87933 ** Shifts all join operators from left to right for an entire FROM
87934 ** clause.
87935 **
87936 ** Example: Suppose the join is like this:
87937 **
87938 **           A natural cross join B
87939 **
87940 ** The operator is "natural cross join".  The A and B operands are stored
87941 ** in p->a[0] and p->a[1], respectively.  The parser initially stores the
87942 ** operator with A.  This routine shifts that operator over to B.
87943 */
87944 SQLITE_PRIVATE void sqlite3SrcListShiftJoinType(SrcList *p){
87945   if( p ){
87946     int i;
87947     assert( p->a || p->nSrc==0 );
87948     for(i=p->nSrc-1; i>0; i--){
87949       p->a[i].jointype = p->a[i-1].jointype;
87950     }
87951     p->a[0].jointype = 0;
87952   }
87953 }
87954 
87955 /*
87956 ** Begin a transaction
87957 */
87958 SQLITE_PRIVATE void sqlite3BeginTransaction(Parse *pParse, int type){
87959   sqlite3 *db;
87960   Vdbe *v;
87961   int i;
87962 
87963   assert( pParse!=0 );
87964   db = pParse->db;
87965   assert( db!=0 );
87966 /*  if( db->aDb[0].pBt==0 ) return; */
87967   if( sqlite3AuthCheck(pParse, SQLITE_TRANSACTION, "BEGIN", 0, 0) ){
87968     return;
87969   }
87970   v = sqlite3GetVdbe(pParse);
87971   if( !v ) return;
87972   if( type!=TK_DEFERRED ){
87973     for(i=0; i<db->nDb; i++){
87974       sqlite3VdbeAddOp2(v, OP_Transaction, i, (type==TK_EXCLUSIVE)+1);
87975       sqlite3VdbeUsesBtree(v, i);
87976     }
87977   }
87978   sqlite3VdbeAddOp2(v, OP_AutoCommit, 0, 0);
87979 }
87980 
87981 /*
87982 ** Commit a transaction
87983 */
87984 SQLITE_PRIVATE void sqlite3CommitTransaction(Parse *pParse){
87985   Vdbe *v;
87986 
87987   assert( pParse!=0 );
87988   assert( pParse->db!=0 );
87989   if( sqlite3AuthCheck(pParse, SQLITE_TRANSACTION, "COMMIT", 0, 0) ){
87990     return;
87991   }
87992   v = sqlite3GetVdbe(pParse);
87993   if( v ){
87994     sqlite3VdbeAddOp2(v, OP_AutoCommit, 1, 0);
87995   }
87996 }
87997 
87998 /*
87999 ** Rollback a transaction
88000 */
88001 SQLITE_PRIVATE void sqlite3RollbackTransaction(Parse *pParse){
88002   Vdbe *v;
88003 
88004   assert( pParse!=0 );
88005   assert( pParse->db!=0 );
88006   if( sqlite3AuthCheck(pParse, SQLITE_TRANSACTION, "ROLLBACK", 0, 0) ){
88007     return;
88008   }
88009   v = sqlite3GetVdbe(pParse);
88010   if( v ){
88011     sqlite3VdbeAddOp2(v, OP_AutoCommit, 1, 1);
88012   }
88013 }
88014 
88015 /*
88016 ** This function is called by the parser when it parses a command to create,
88017 ** release or rollback an SQL savepoint. 
88018 */
88019 SQLITE_PRIVATE void sqlite3Savepoint(Parse *pParse, int op, Token *pName){
88020   char *zName = sqlite3NameFromToken(pParse->db, pName);
88021   if( zName ){
88022     Vdbe *v = sqlite3GetVdbe(pParse);
88023 #ifndef SQLITE_OMIT_AUTHORIZATION
88024     static const char * const az[] = { "BEGIN", "RELEASE", "ROLLBACK" };
88025     assert( !SAVEPOINT_BEGIN && SAVEPOINT_RELEASE==1 && SAVEPOINT_ROLLBACK==2 );
88026 #endif
88027     if( !v || sqlite3AuthCheck(pParse, SQLITE_SAVEPOINT, az[op], zName, 0) ){
88028       sqlite3DbFree(pParse->db, zName);
88029       return;
88030     }
88031     sqlite3VdbeAddOp4(v, OP_Savepoint, op, 0, 0, zName, P4_DYNAMIC);
88032   }
88033 }
88034 
88035 /*
88036 ** Make sure the TEMP database is open and available for use.  Return
88037 ** the number of errors.  Leave any error messages in the pParse structure.
88038 */
88039 SQLITE_PRIVATE int sqlite3OpenTempDatabase(Parse *pParse){
88040   sqlite3 *db = pParse->db;
88041   if( db->aDb[1].pBt==0 && !pParse->explain ){
88042     int rc;
88043     Btree *pBt;
88044     static const int flags = 
88045           SQLITE_OPEN_READWRITE |
88046           SQLITE_OPEN_CREATE |
88047           SQLITE_OPEN_EXCLUSIVE |
88048           SQLITE_OPEN_DELETEONCLOSE |
88049           SQLITE_OPEN_TEMP_DB;
88050 
88051     rc = sqlite3BtreeOpen(db->pVfs, 0, db, &pBt, 0, flags);
88052     if( rc!=SQLITE_OK ){
88053       sqlite3ErrorMsg(pParse, "unable to open a temporary database "
88054         "file for storing temporary tables");
88055       pParse->rc = rc;
88056       return 1;
88057     }
88058     db->aDb[1].pBt = pBt;
88059     assert( db->aDb[1].pSchema );
88060     if( SQLITE_NOMEM==sqlite3BtreeSetPageSize(pBt, db->nextPagesize, -1, 0) ){
88061       db->mallocFailed = 1;
88062       return 1;
88063     }
88064   }
88065   return 0;
88066 }
88067 
88068 /*
88069 ** Generate VDBE code that will verify the schema cookie and start
88070 ** a read-transaction for all named database files.
88071 **
88072 ** It is important that all schema cookies be verified and all
88073 ** read transactions be started before anything else happens in
88074 ** the VDBE program.  But this routine can be called after much other
88075 ** code has been generated.  So here is what we do:
88076 **
88077 ** The first time this routine is called, we code an OP_Goto that
88078 ** will jump to a subroutine at the end of the program.  Then we
88079 ** record every database that needs its schema verified in the
88080 ** pParse->cookieMask field.  Later, after all other code has been
88081 ** generated, the subroutine that does the cookie verifications and
88082 ** starts the transactions will be coded and the OP_Goto P2 value
88083 ** will be made to point to that subroutine.  The generation of the
88084 ** cookie verification subroutine code happens in sqlite3FinishCoding().
88085 **
88086 ** If iDb<0 then code the OP_Goto only - don't set flag to verify the
88087 ** schema on any databases.  This can be used to position the OP_Goto
88088 ** early in the code, before we know if any database tables will be used.
88089 */
88090 SQLITE_PRIVATE void sqlite3CodeVerifySchema(Parse *pParse, int iDb){
88091   Parse *pToplevel = sqlite3ParseToplevel(pParse);
88092 
88093 #ifndef SQLITE_OMIT_TRIGGER
88094   if( pToplevel!=pParse ){
88095     /* This branch is taken if a trigger is currently being coded. In this
88096     ** case, set cookieGoto to a non-zero value to show that this function
88097     ** has been called. This is used by the sqlite3ExprCodeConstants()
88098     ** function. */
88099     pParse->cookieGoto = -1;
88100   }
88101 #endif
88102   if( pToplevel->cookieGoto==0 ){
88103     Vdbe *v = sqlite3GetVdbe(pToplevel);
88104     if( v==0 ) return;  /* This only happens if there was a prior error */
88105     pToplevel->cookieGoto = sqlite3VdbeAddOp2(v, OP_Goto, 0, 0)+1;
88106   }
88107   if( iDb>=0 ){
88108     sqlite3 *db = pToplevel->db;
88109     yDbMask mask;
88110 
88111     assert( iDb<db->nDb );
88112     assert( db->aDb[iDb].pBt!=0 || iDb==1 );
88113     assert( iDb<SQLITE_MAX_ATTACHED+2 );
88114     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
88115     mask = ((yDbMask)1)<<iDb;
88116     if( (pToplevel->cookieMask & mask)==0 ){
88117       pToplevel->cookieMask |= mask;
88118       pToplevel->cookieValue[iDb] = db->aDb[iDb].pSchema->schema_cookie;
88119       if( !OMIT_TEMPDB && iDb==1 ){
88120         sqlite3OpenTempDatabase(pToplevel);
88121       }
88122     }
88123   }
88124 }
88125 
88126 /*
88127 ** If argument zDb is NULL, then call sqlite3CodeVerifySchema() for each 
88128 ** attached database. Otherwise, invoke it for the database named zDb only.
88129 */
88130 SQLITE_PRIVATE void sqlite3CodeVerifyNamedSchema(Parse *pParse, const char *zDb){
88131   sqlite3 *db = pParse->db;
88132   int i;
88133   for(i=0; i<db->nDb; i++){
88134     Db *pDb = &db->aDb[i];
88135     if( pDb->pBt && (!zDb || 0==sqlite3StrICmp(zDb, pDb->zName)) ){
88136       sqlite3CodeVerifySchema(pParse, i);
88137     }
88138   }
88139 }
88140 
88141 /*
88142 ** Generate VDBE code that prepares for doing an operation that
88143 ** might change the database.
88144 **
88145 ** This routine starts a new transaction if we are not already within
88146 ** a transaction.  If we are already within a transaction, then a checkpoint
88147 ** is set if the setStatement parameter is true.  A checkpoint should
88148 ** be set for operations that might fail (due to a constraint) part of
88149 ** the way through and which will need to undo some writes without having to
88150 ** rollback the whole transaction.  For operations where all constraints
88151 ** can be checked before any changes are made to the database, it is never
88152 ** necessary to undo a write and the checkpoint should not be set.
88153 */
88154 SQLITE_PRIVATE void sqlite3BeginWriteOperation(Parse *pParse, int setStatement, int iDb){
88155   Parse *pToplevel = sqlite3ParseToplevel(pParse);
88156   sqlite3CodeVerifySchema(pParse, iDb);
88157   pToplevel->writeMask |= ((yDbMask)1)<<iDb;
88158   pToplevel->isMultiWrite |= setStatement;
88159 }
88160 
88161 /*
88162 ** Indicate that the statement currently under construction might write
88163 ** more than one entry (example: deleting one row then inserting another,
88164 ** inserting multiple rows in a table, or inserting a row and index entries.)
88165 ** If an abort occurs after some of these writes have completed, then it will
88166 ** be necessary to undo the completed writes.
88167 */
88168 SQLITE_PRIVATE void sqlite3MultiWrite(Parse *pParse){
88169   Parse *pToplevel = sqlite3ParseToplevel(pParse);
88170   pToplevel->isMultiWrite = 1;
88171 }
88172 
88173 /* 
88174 ** The code generator calls this routine if is discovers that it is
88175 ** possible to abort a statement prior to completion.  In order to 
88176 ** perform this abort without corrupting the database, we need to make
88177 ** sure that the statement is protected by a statement transaction.
88178 **
88179 ** Technically, we only need to set the mayAbort flag if the
88180 ** isMultiWrite flag was previously set.  There is a time dependency
88181 ** such that the abort must occur after the multiwrite.  This makes
88182 ** some statements involving the REPLACE conflict resolution algorithm
88183 ** go a little faster.  But taking advantage of this time dependency
88184 ** makes it more difficult to prove that the code is correct (in 
88185 ** particular, it prevents us from writing an effective
88186 ** implementation of sqlite3AssertMayAbort()) and so we have chosen
88187 ** to take the safe route and skip the optimization.
88188 */
88189 SQLITE_PRIVATE void sqlite3MayAbort(Parse *pParse){
88190   Parse *pToplevel = sqlite3ParseToplevel(pParse);
88191   pToplevel->mayAbort = 1;
88192 }
88193 
88194 /*
88195 ** Code an OP_Halt that causes the vdbe to return an SQLITE_CONSTRAINT
88196 ** error. The onError parameter determines which (if any) of the statement
88197 ** and/or current transaction is rolled back.
88198 */
88199 SQLITE_PRIVATE void sqlite3HaltConstraint(
88200   Parse *pParse,    /* Parsing context */
88201   int errCode,      /* extended error code */
88202   int onError,      /* Constraint type */
88203   char *p4,         /* Error message */
88204   i8 p4type,        /* P4_STATIC or P4_TRANSIENT */
88205   u8 p5Errmsg       /* P5_ErrMsg type */
88206 ){
88207   Vdbe *v = sqlite3GetVdbe(pParse);
88208   assert( (errCode&0xff)==SQLITE_CONSTRAINT );
88209   if( onError==OE_Abort ){
88210     sqlite3MayAbort(pParse);
88211   }
88212   sqlite3VdbeAddOp4(v, OP_Halt, errCode, onError, 0, p4, p4type);
88213   if( p5Errmsg ) sqlite3VdbeChangeP5(v, p5Errmsg);
88214 }
88215 
88216 /*
88217 ** Code an OP_Halt due to UNIQUE or PRIMARY KEY constraint violation.
88218 */
88219 SQLITE_PRIVATE void sqlite3UniqueConstraint(
88220   Parse *pParse,    /* Parsing context */
88221   int onError,      /* Constraint type */
88222   Index *pIdx       /* The index that triggers the constraint */
88223 ){
88224   char *zErr;
88225   int j;
88226   StrAccum errMsg;
88227   Table *pTab = pIdx->pTable;
88228 
88229   sqlite3StrAccumInit(&errMsg, 0, 0, 200);
88230   errMsg.db = pParse->db;
88231   for(j=0; j<pIdx->nKeyCol; j++){
88232     char *zCol = pTab->aCol[pIdx->aiColumn[j]].zName;
88233     if( j ) sqlite3StrAccumAppend(&errMsg, ", ", 2);
88234     sqlite3StrAccumAppend(&errMsg, pTab->zName, -1);
88235     sqlite3StrAccumAppend(&errMsg, ".", 1);
88236     sqlite3StrAccumAppend(&errMsg, zCol, -1);
88237   }
88238   zErr = sqlite3StrAccumFinish(&errMsg);
88239   sqlite3HaltConstraint(pParse, 
88240     (pIdx->autoIndex==2)?SQLITE_CONSTRAINT_PRIMARYKEY:SQLITE_CONSTRAINT_UNIQUE,
88241     onError, zErr, P4_DYNAMIC, P5_ConstraintUnique);
88242 }
88243 
88244 
88245 /*
88246 ** Code an OP_Halt due to non-unique rowid.
88247 */
88248 SQLITE_PRIVATE void sqlite3RowidConstraint(
88249   Parse *pParse,    /* Parsing context */
88250   int onError,      /* Conflict resolution algorithm */
88251   Table *pTab       /* The table with the non-unique rowid */ 
88252 ){
88253   char *zMsg;
88254   int rc;
88255   if( pTab->iPKey>=0 ){
88256     zMsg = sqlite3MPrintf(pParse->db, "%s.%s", pTab->zName,
88257                           pTab->aCol[pTab->iPKey].zName);
88258     rc = SQLITE_CONSTRAINT_PRIMARYKEY;
88259   }else{
88260     zMsg = sqlite3MPrintf(pParse->db, "%s.rowid", pTab->zName);
88261     rc = SQLITE_CONSTRAINT_ROWID;
88262   }
88263   sqlite3HaltConstraint(pParse, rc, onError, zMsg, P4_DYNAMIC,
88264                         P5_ConstraintUnique);
88265 }
88266 
88267 /*
88268 ** Check to see if pIndex uses the collating sequence pColl.  Return
88269 ** true if it does and false if it does not.
88270 */
88271 #ifndef SQLITE_OMIT_REINDEX
88272 static int collationMatch(const char *zColl, Index *pIndex){
88273   int i;
88274   assert( zColl!=0 );
88275   for(i=0; i<pIndex->nColumn; i++){
88276     const char *z = pIndex->azColl[i];
88277     assert( z!=0 || pIndex->aiColumn[i]<0 );
88278     if( pIndex->aiColumn[i]>=0 && 0==sqlite3StrICmp(z, zColl) ){
88279       return 1;
88280     }
88281   }
88282   return 0;
88283 }
88284 #endif
88285 
88286 /*
88287 ** Recompute all indices of pTab that use the collating sequence pColl.
88288 ** If pColl==0 then recompute all indices of pTab.
88289 */
88290 #ifndef SQLITE_OMIT_REINDEX
88291 static void reindexTable(Parse *pParse, Table *pTab, char const *zColl){
88292   Index *pIndex;              /* An index associated with pTab */
88293 
88294   for(pIndex=pTab->pIndex; pIndex; pIndex=pIndex->pNext){
88295     if( zColl==0 || collationMatch(zColl, pIndex) ){
88296       int iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
88297       sqlite3BeginWriteOperation(pParse, 0, iDb);
88298       sqlite3RefillIndex(pParse, pIndex, -1);
88299     }
88300   }
88301 }
88302 #endif
88303 
88304 /*
88305 ** Recompute all indices of all tables in all databases where the
88306 ** indices use the collating sequence pColl.  If pColl==0 then recompute
88307 ** all indices everywhere.
88308 */
88309 #ifndef SQLITE_OMIT_REINDEX
88310 static void reindexDatabases(Parse *pParse, char const *zColl){
88311   Db *pDb;                    /* A single database */
88312   int iDb;                    /* The database index number */
88313   sqlite3 *db = pParse->db;   /* The database connection */
88314   HashElem *k;                /* For looping over tables in pDb */
88315   Table *pTab;                /* A table in the database */
88316 
88317   assert( sqlite3BtreeHoldsAllMutexes(db) );  /* Needed for schema access */
88318   for(iDb=0, pDb=db->aDb; iDb<db->nDb; iDb++, pDb++){
88319     assert( pDb!=0 );
88320     for(k=sqliteHashFirst(&pDb->pSchema->tblHash);  k; k=sqliteHashNext(k)){
88321       pTab = (Table*)sqliteHashData(k);
88322       reindexTable(pParse, pTab, zColl);
88323     }
88324   }
88325 }
88326 #endif
88327 
88328 /*
88329 ** Generate code for the REINDEX command.
88330 **
88331 **        REINDEX                            -- 1
88332 **        REINDEX  <collation>               -- 2
88333 **        REINDEX  ?<database>.?<tablename>  -- 3
88334 **        REINDEX  ?<database>.?<indexname>  -- 4
88335 **
88336 ** Form 1 causes all indices in all attached databases to be rebuilt.
88337 ** Form 2 rebuilds all indices in all databases that use the named
88338 ** collating function.  Forms 3 and 4 rebuild the named index or all
88339 ** indices associated with the named table.
88340 */
88341 #ifndef SQLITE_OMIT_REINDEX
88342 SQLITE_PRIVATE void sqlite3Reindex(Parse *pParse, Token *pName1, Token *pName2){
88343   CollSeq *pColl;             /* Collating sequence to be reindexed, or NULL */
88344   char *z;                    /* Name of a table or index */
88345   const char *zDb;            /* Name of the database */
88346   Table *pTab;                /* A table in the database */
88347   Index *pIndex;              /* An index associated with pTab */
88348   int iDb;                    /* The database index number */
88349   sqlite3 *db = pParse->db;   /* The database connection */
88350   Token *pObjName;            /* Name of the table or index to be reindexed */
88351 
88352   /* Read the database schema. If an error occurs, leave an error message
88353   ** and code in pParse and return NULL. */
88354   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
88355     return;
88356   }
88357 
88358   if( pName1==0 ){
88359     reindexDatabases(pParse, 0);
88360     return;
88361   }else if( NEVER(pName2==0) || pName2->z==0 ){
88362     char *zColl;
88363     assert( pName1->z );
88364     zColl = sqlite3NameFromToken(pParse->db, pName1);
88365     if( !zColl ) return;
88366     pColl = sqlite3FindCollSeq(db, ENC(db), zColl, 0);
88367     if( pColl ){
88368       reindexDatabases(pParse, zColl);
88369       sqlite3DbFree(db, zColl);
88370       return;
88371     }
88372     sqlite3DbFree(db, zColl);
88373   }
88374   iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pObjName);
88375   if( iDb<0 ) return;
88376   z = sqlite3NameFromToken(db, pObjName);
88377   if( z==0 ) return;
88378   zDb = db->aDb[iDb].zName;
88379   pTab = sqlite3FindTable(db, z, zDb);
88380   if( pTab ){
88381     reindexTable(pParse, pTab, 0);
88382     sqlite3DbFree(db, z);
88383     return;
88384   }
88385   pIndex = sqlite3FindIndex(db, z, zDb);
88386   sqlite3DbFree(db, z);
88387   if( pIndex ){
88388     sqlite3BeginWriteOperation(pParse, 0, iDb);
88389     sqlite3RefillIndex(pParse, pIndex, -1);
88390     return;
88391   }
88392   sqlite3ErrorMsg(pParse, "unable to identify the object to be reindexed");
88393 }
88394 #endif
88395 
88396 /*
88397 ** Return a KeyInfo structure that is appropriate for the given Index.
88398 **
88399 ** The KeyInfo structure for an index is cached in the Index object.
88400 ** So there might be multiple references to the returned pointer.  The
88401 ** caller should not try to modify the KeyInfo object.
88402 **
88403 ** The caller should invoke sqlite3KeyInfoUnref() on the returned object
88404 ** when it has finished using it.
88405 */
88406 SQLITE_PRIVATE KeyInfo *sqlite3KeyInfoOfIndex(Parse *pParse, Index *pIdx){
88407   if( pParse->nErr ) return 0;
88408 #ifndef SQLITE_OMIT_SHARED_CACHE
88409   if( pIdx->pKeyInfo && pIdx->pKeyInfo->db!=pParse->db ){
88410     sqlite3KeyInfoUnref(pIdx->pKeyInfo);
88411     pIdx->pKeyInfo = 0;
88412   }
88413 #endif
88414   if( pIdx->pKeyInfo==0 ){
88415     int i;
88416     int nCol = pIdx->nColumn;
88417     int nKey = pIdx->nKeyCol;
88418     KeyInfo *pKey;
88419     if( pIdx->uniqNotNull ){
88420       pKey = sqlite3KeyInfoAlloc(pParse->db, nKey, nCol-nKey);
88421     }else{
88422       pKey = sqlite3KeyInfoAlloc(pParse->db, nCol, 0);
88423     }
88424     if( pKey ){
88425       assert( sqlite3KeyInfoIsWriteable(pKey) );
88426       for(i=0; i<nCol; i++){
88427         char *zColl = pIdx->azColl[i];
88428         if( NEVER(zColl==0) ) zColl = "BINARY";
88429         pKey->aColl[i] = sqlite3LocateCollSeq(pParse, zColl);
88430         pKey->aSortOrder[i] = pIdx->aSortOrder[i];
88431       }
88432       if( pParse->nErr ){
88433         sqlite3KeyInfoUnref(pKey);
88434       }else{
88435         pIdx->pKeyInfo = pKey;
88436       }
88437     }
88438   }
88439   return sqlite3KeyInfoRef(pIdx->pKeyInfo);
88440 }
88441 
88442 /************** End of build.c ***********************************************/
88443 /************** Begin file callback.c ****************************************/
88444 /*
88445 ** 2005 May 23 
88446 **
88447 ** The author disclaims copyright to this source code.  In place of
88448 ** a legal notice, here is a blessing:
88449 **
88450 **    May you do good and not evil.
88451 **    May you find forgiveness for yourself and forgive others.
88452 **    May you share freely, never taking more than you give.
88453 **
88454 *************************************************************************
88455 **
88456 ** This file contains functions used to access the internal hash tables
88457 ** of user defined functions and collation sequences.
88458 */
88459 
88460 
88461 /*
88462 ** Invoke the 'collation needed' callback to request a collation sequence
88463 ** in the encoding enc of name zName, length nName.
88464 */
88465 static void callCollNeeded(sqlite3 *db, int enc, const char *zName){
88466   assert( !db->xCollNeeded || !db->xCollNeeded16 );
88467   if( db->xCollNeeded ){
88468     char *zExternal = sqlite3DbStrDup(db, zName);
88469     if( !zExternal ) return;
88470     db->xCollNeeded(db->pCollNeededArg, db, enc, zExternal);
88471     sqlite3DbFree(db, zExternal);
88472   }
88473 #ifndef SQLITE_OMIT_UTF16
88474   if( db->xCollNeeded16 ){
88475     char const *zExternal;
88476     sqlite3_value *pTmp = sqlite3ValueNew(db);
88477     sqlite3ValueSetStr(pTmp, -1, zName, SQLITE_UTF8, SQLITE_STATIC);
88478     zExternal = sqlite3ValueText(pTmp, SQLITE_UTF16NATIVE);
88479     if( zExternal ){
88480       db->xCollNeeded16(db->pCollNeededArg, db, (int)ENC(db), zExternal);
88481     }
88482     sqlite3ValueFree(pTmp);
88483   }
88484 #endif
88485 }
88486 
88487 /*
88488 ** This routine is called if the collation factory fails to deliver a
88489 ** collation function in the best encoding but there may be other versions
88490 ** of this collation function (for other text encodings) available. Use one
88491 ** of these instead if they exist. Avoid a UTF-8 <-> UTF-16 conversion if
88492 ** possible.
88493 */
88494 static int synthCollSeq(sqlite3 *db, CollSeq *pColl){
88495   CollSeq *pColl2;
88496   char *z = pColl->zName;
88497   int i;
88498   static const u8 aEnc[] = { SQLITE_UTF16BE, SQLITE_UTF16LE, SQLITE_UTF8 };
88499   for(i=0; i<3; i++){
88500     pColl2 = sqlite3FindCollSeq(db, aEnc[i], z, 0);
88501     if( pColl2->xCmp!=0 ){
88502       memcpy(pColl, pColl2, sizeof(CollSeq));
88503       pColl->xDel = 0;         /* Do not copy the destructor */
88504       return SQLITE_OK;
88505     }
88506   }
88507   return SQLITE_ERROR;
88508 }
88509 
88510 /*
88511 ** This function is responsible for invoking the collation factory callback
88512 ** or substituting a collation sequence of a different encoding when the
88513 ** requested collation sequence is not available in the desired encoding.
88514 ** 
88515 ** If it is not NULL, then pColl must point to the database native encoding 
88516 ** collation sequence with name zName, length nName.
88517 **
88518 ** The return value is either the collation sequence to be used in database
88519 ** db for collation type name zName, length nName, or NULL, if no collation
88520 ** sequence can be found.  If no collation is found, leave an error message.
88521 **
88522 ** See also: sqlite3LocateCollSeq(), sqlite3FindCollSeq()
88523 */
88524 SQLITE_PRIVATE CollSeq *sqlite3GetCollSeq(
88525   Parse *pParse,        /* Parsing context */
88526   u8 enc,               /* The desired encoding for the collating sequence */
88527   CollSeq *pColl,       /* Collating sequence with native encoding, or NULL */
88528   const char *zName     /* Collating sequence name */
88529 ){
88530   CollSeq *p;
88531   sqlite3 *db = pParse->db;
88532 
88533   p = pColl;
88534   if( !p ){
88535     p = sqlite3FindCollSeq(db, enc, zName, 0);
88536   }
88537   if( !p || !p->xCmp ){
88538     /* No collation sequence of this type for this encoding is registered.
88539     ** Call the collation factory to see if it can supply us with one.
88540     */
88541     callCollNeeded(db, enc, zName);
88542     p = sqlite3FindCollSeq(db, enc, zName, 0);
88543   }
88544   if( p && !p->xCmp && synthCollSeq(db, p) ){
88545     p = 0;
88546   }
88547   assert( !p || p->xCmp );
88548   if( p==0 ){
88549     sqlite3ErrorMsg(pParse, "no such collation sequence: %s", zName);
88550   }
88551   return p;
88552 }
88553 
88554 /*
88555 ** This routine is called on a collation sequence before it is used to
88556 ** check that it is defined. An undefined collation sequence exists when
88557 ** a database is loaded that contains references to collation sequences
88558 ** that have not been defined by sqlite3_create_collation() etc.
88559 **
88560 ** If required, this routine calls the 'collation needed' callback to
88561 ** request a definition of the collating sequence. If this doesn't work, 
88562 ** an equivalent collating sequence that uses a text encoding different
88563 ** from the main database is substituted, if one is available.
88564 */
88565 SQLITE_PRIVATE int sqlite3CheckCollSeq(Parse *pParse, CollSeq *pColl){
88566   if( pColl ){
88567     const char *zName = pColl->zName;
88568     sqlite3 *db = pParse->db;
88569     CollSeq *p = sqlite3GetCollSeq(pParse, ENC(db), pColl, zName);
88570     if( !p ){
88571       return SQLITE_ERROR;
88572     }
88573     assert( p==pColl );
88574   }
88575   return SQLITE_OK;
88576 }
88577 
88578 
88579 
88580 /*
88581 ** Locate and return an entry from the db.aCollSeq hash table. If the entry
88582 ** specified by zName and nName is not found and parameter 'create' is
88583 ** true, then create a new entry. Otherwise return NULL.
88584 **
88585 ** Each pointer stored in the sqlite3.aCollSeq hash table contains an
88586 ** array of three CollSeq structures. The first is the collation sequence
88587 ** prefferred for UTF-8, the second UTF-16le, and the third UTF-16be.
88588 **
88589 ** Stored immediately after the three collation sequences is a copy of
88590 ** the collation sequence name. A pointer to this string is stored in
88591 ** each collation sequence structure.
88592 */
88593 static CollSeq *findCollSeqEntry(
88594   sqlite3 *db,          /* Database connection */
88595   const char *zName,    /* Name of the collating sequence */
88596   int create            /* Create a new entry if true */
88597 ){
88598   CollSeq *pColl;
88599   int nName = sqlite3Strlen30(zName);
88600   pColl = sqlite3HashFind(&db->aCollSeq, zName, nName);
88601 
88602   if( 0==pColl && create ){
88603     pColl = sqlite3DbMallocZero(db, 3*sizeof(*pColl) + nName + 1 );
88604     if( pColl ){
88605       CollSeq *pDel = 0;
88606       pColl[0].zName = (char*)&pColl[3];
88607       pColl[0].enc = SQLITE_UTF8;
88608       pColl[1].zName = (char*)&pColl[3];
88609       pColl[1].enc = SQLITE_UTF16LE;
88610       pColl[2].zName = (char*)&pColl[3];
88611       pColl[2].enc = SQLITE_UTF16BE;
88612       memcpy(pColl[0].zName, zName, nName);
88613       pColl[0].zName[nName] = 0;
88614       pDel = sqlite3HashInsert(&db->aCollSeq, pColl[0].zName, nName, pColl);
88615 
88616       /* If a malloc() failure occurred in sqlite3HashInsert(), it will 
88617       ** return the pColl pointer to be deleted (because it wasn't added
88618       ** to the hash table).
88619       */
88620       assert( pDel==0 || pDel==pColl );
88621       if( pDel!=0 ){
88622         db->mallocFailed = 1;
88623         sqlite3DbFree(db, pDel);
88624         pColl = 0;
88625       }
88626     }
88627   }
88628   return pColl;
88629 }
88630 
88631 /*
88632 ** Parameter zName points to a UTF-8 encoded string nName bytes long.
88633 ** Return the CollSeq* pointer for the collation sequence named zName
88634 ** for the encoding 'enc' from the database 'db'.
88635 **
88636 ** If the entry specified is not found and 'create' is true, then create a
88637 ** new entry.  Otherwise return NULL.
88638 **
88639 ** A separate function sqlite3LocateCollSeq() is a wrapper around
88640 ** this routine.  sqlite3LocateCollSeq() invokes the collation factory
88641 ** if necessary and generates an error message if the collating sequence
88642 ** cannot be found.
88643 **
88644 ** See also: sqlite3LocateCollSeq(), sqlite3GetCollSeq()
88645 */
88646 SQLITE_PRIVATE CollSeq *sqlite3FindCollSeq(
88647   sqlite3 *db,
88648   u8 enc,
88649   const char *zName,
88650   int create
88651 ){
88652   CollSeq *pColl;
88653   if( zName ){
88654     pColl = findCollSeqEntry(db, zName, create);
88655   }else{
88656     pColl = db->pDfltColl;
88657   }
88658   assert( SQLITE_UTF8==1 && SQLITE_UTF16LE==2 && SQLITE_UTF16BE==3 );
88659   assert( enc>=SQLITE_UTF8 && enc<=SQLITE_UTF16BE );
88660   if( pColl ) pColl += enc-1;
88661   return pColl;
88662 }
88663 
88664 /* During the search for the best function definition, this procedure
88665 ** is called to test how well the function passed as the first argument
88666 ** matches the request for a function with nArg arguments in a system
88667 ** that uses encoding enc. The value returned indicates how well the
88668 ** request is matched. A higher value indicates a better match.
88669 **
88670 ** If nArg is -1 that means to only return a match (non-zero) if p->nArg
88671 ** is also -1.  In other words, we are searching for a function that
88672 ** takes a variable number of arguments.
88673 **
88674 ** If nArg is -2 that means that we are searching for any function 
88675 ** regardless of the number of arguments it uses, so return a positive
88676 ** match score for any
88677 **
88678 ** The returned value is always between 0 and 6, as follows:
88679 **
88680 ** 0: Not a match.
88681 ** 1: UTF8/16 conversion required and function takes any number of arguments.
88682 ** 2: UTF16 byte order change required and function takes any number of args.
88683 ** 3: encoding matches and function takes any number of arguments
88684 ** 4: UTF8/16 conversion required - argument count matches exactly
88685 ** 5: UTF16 byte order conversion required - argument count matches exactly
88686 ** 6: Perfect match:  encoding and argument count match exactly.
88687 **
88688 ** If nArg==(-2) then any function with a non-null xStep or xFunc is
88689 ** a perfect match and any function with both xStep and xFunc NULL is
88690 ** a non-match.
88691 */
88692 #define FUNC_PERFECT_MATCH 6  /* The score for a perfect match */
88693 static int matchQuality(
88694   FuncDef *p,     /* The function we are evaluating for match quality */
88695   int nArg,       /* Desired number of arguments.  (-1)==any */
88696   u8 enc          /* Desired text encoding */
88697 ){
88698   int match;
88699 
88700   /* nArg of -2 is a special case */
88701   if( nArg==(-2) ) return (p->xFunc==0 && p->xStep==0) ? 0 : FUNC_PERFECT_MATCH;
88702 
88703   /* Wrong number of arguments means "no match" */
88704   if( p->nArg!=nArg && p->nArg>=0 ) return 0;
88705 
88706   /* Give a better score to a function with a specific number of arguments
88707   ** than to function that accepts any number of arguments. */
88708   if( p->nArg==nArg ){
88709     match = 4;
88710   }else{
88711     match = 1;
88712   }
88713 
88714   /* Bonus points if the text encoding matches */
88715   if( enc==(p->funcFlags & SQLITE_FUNC_ENCMASK) ){
88716     match += 2;  /* Exact encoding match */
88717   }else if( (enc & p->funcFlags & 2)!=0 ){
88718     match += 1;  /* Both are UTF16, but with different byte orders */
88719   }
88720 
88721   return match;
88722 }
88723 
88724 /*
88725 ** Search a FuncDefHash for a function with the given name.  Return
88726 ** a pointer to the matching FuncDef if found, or 0 if there is no match.
88727 */
88728 static FuncDef *functionSearch(
88729   FuncDefHash *pHash,  /* Hash table to search */
88730   int h,               /* Hash of the name */
88731   const char *zFunc,   /* Name of function */
88732   int nFunc            /* Number of bytes in zFunc */
88733 ){
88734   FuncDef *p;
88735   for(p=pHash->a[h]; p; p=p->pHash){
88736     if( sqlite3StrNICmp(p->zName, zFunc, nFunc)==0 && p->zName[nFunc]==0 ){
88737       return p;
88738     }
88739   }
88740   return 0;
88741 }
88742 
88743 /*
88744 ** Insert a new FuncDef into a FuncDefHash hash table.
88745 */
88746 SQLITE_PRIVATE void sqlite3FuncDefInsert(
88747   FuncDefHash *pHash,  /* The hash table into which to insert */
88748   FuncDef *pDef        /* The function definition to insert */
88749 ){
88750   FuncDef *pOther;
88751   int nName = sqlite3Strlen30(pDef->zName);
88752   u8 c1 = (u8)pDef->zName[0];
88753   int h = (sqlite3UpperToLower[c1] + nName) % ArraySize(pHash->a);
88754   pOther = functionSearch(pHash, h, pDef->zName, nName);
88755   if( pOther ){
88756     assert( pOther!=pDef && pOther->pNext!=pDef );
88757     pDef->pNext = pOther->pNext;
88758     pOther->pNext = pDef;
88759   }else{
88760     pDef->pNext = 0;
88761     pDef->pHash = pHash->a[h];
88762     pHash->a[h] = pDef;
88763   }
88764 }
88765   
88766   
88767 
88768 /*
88769 ** Locate a user function given a name, a number of arguments and a flag
88770 ** indicating whether the function prefers UTF-16 over UTF-8.  Return a
88771 ** pointer to the FuncDef structure that defines that function, or return
88772 ** NULL if the function does not exist.
88773 **
88774 ** If the createFlag argument is true, then a new (blank) FuncDef
88775 ** structure is created and liked into the "db" structure if a
88776 ** no matching function previously existed.
88777 **
88778 ** If nArg is -2, then the first valid function found is returned.  A
88779 ** function is valid if either xFunc or xStep is non-zero.  The nArg==(-2)
88780 ** case is used to see if zName is a valid function name for some number
88781 ** of arguments.  If nArg is -2, then createFlag must be 0.
88782 **
88783 ** If createFlag is false, then a function with the required name and
88784 ** number of arguments may be returned even if the eTextRep flag does not
88785 ** match that requested.
88786 */
88787 SQLITE_PRIVATE FuncDef *sqlite3FindFunction(
88788   sqlite3 *db,       /* An open database */
88789   const char *zName, /* Name of the function.  Not null-terminated */
88790   int nName,         /* Number of characters in the name */
88791   int nArg,          /* Number of arguments.  -1 means any number */
88792   u8 enc,            /* Preferred text encoding */
88793   u8 createFlag      /* Create new entry if true and does not otherwise exist */
88794 ){
88795   FuncDef *p;         /* Iterator variable */
88796   FuncDef *pBest = 0; /* Best match found so far */
88797   int bestScore = 0;  /* Score of best match */
88798   int h;              /* Hash value */
88799 
88800   assert( nArg>=(-2) );
88801   assert( nArg>=(-1) || createFlag==0 );
88802   assert( enc==SQLITE_UTF8 || enc==SQLITE_UTF16LE || enc==SQLITE_UTF16BE );
88803   h = (sqlite3UpperToLower[(u8)zName[0]] + nName) % ArraySize(db->aFunc.a);
88804 
88805   /* First search for a match amongst the application-defined functions.
88806   */
88807   p = functionSearch(&db->aFunc, h, zName, nName);
88808   while( p ){
88809     int score = matchQuality(p, nArg, enc);
88810     if( score>bestScore ){
88811       pBest = p;
88812       bestScore = score;
88813     }
88814     p = p->pNext;
88815   }
88816 
88817   /* If no match is found, search the built-in functions.
88818   **
88819   ** If the SQLITE_PreferBuiltin flag is set, then search the built-in
88820   ** functions even if a prior app-defined function was found.  And give
88821   ** priority to built-in functions.
88822   **
88823   ** Except, if createFlag is true, that means that we are trying to
88824   ** install a new function.  Whatever FuncDef structure is returned it will
88825   ** have fields overwritten with new information appropriate for the
88826   ** new function.  But the FuncDefs for built-in functions are read-only.
88827   ** So we must not search for built-ins when creating a new function.
88828   */ 
88829   if( !createFlag && (pBest==0 || (db->flags & SQLITE_PreferBuiltin)!=0) ){
88830     FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
88831     bestScore = 0;
88832     p = functionSearch(pHash, h, zName, nName);
88833     while( p ){
88834       int score = matchQuality(p, nArg, enc);
88835       if( score>bestScore ){
88836         pBest = p;
88837         bestScore = score;
88838       }
88839       p = p->pNext;
88840     }
88841   }
88842 
88843   /* If the createFlag parameter is true and the search did not reveal an
88844   ** exact match for the name, number of arguments and encoding, then add a
88845   ** new entry to the hash table and return it.
88846   */
88847   if( createFlag && bestScore<FUNC_PERFECT_MATCH && 
88848       (pBest = sqlite3DbMallocZero(db, sizeof(*pBest)+nName+1))!=0 ){
88849     pBest->zName = (char *)&pBest[1];
88850     pBest->nArg = (u16)nArg;
88851     pBest->funcFlags = enc;
88852     memcpy(pBest->zName, zName, nName);
88853     pBest->zName[nName] = 0;
88854     sqlite3FuncDefInsert(&db->aFunc, pBest);
88855   }
88856 
88857   if( pBest && (pBest->xStep || pBest->xFunc || createFlag) ){
88858     return pBest;
88859   }
88860   return 0;
88861 }
88862 
88863 /*
88864 ** Free all resources held by the schema structure. The void* argument points
88865 ** at a Schema struct. This function does not call sqlite3DbFree(db, ) on the 
88866 ** pointer itself, it just cleans up subsidiary resources (i.e. the contents
88867 ** of the schema hash tables).
88868 **
88869 ** The Schema.cache_size variable is not cleared.
88870 */
88871 SQLITE_PRIVATE void sqlite3SchemaClear(void *p){
88872   Hash temp1;
88873   Hash temp2;
88874   HashElem *pElem;
88875   Schema *pSchema = (Schema *)p;
88876 
88877   temp1 = pSchema->tblHash;
88878   temp2 = pSchema->trigHash;
88879   sqlite3HashInit(&pSchema->trigHash);
88880   sqlite3HashClear(&pSchema->idxHash);
88881   for(pElem=sqliteHashFirst(&temp2); pElem; pElem=sqliteHashNext(pElem)){
88882     sqlite3DeleteTrigger(0, (Trigger*)sqliteHashData(pElem));
88883   }
88884   sqlite3HashClear(&temp2);
88885   sqlite3HashInit(&pSchema->tblHash);
88886   for(pElem=sqliteHashFirst(&temp1); pElem; pElem=sqliteHashNext(pElem)){
88887     Table *pTab = sqliteHashData(pElem);
88888     sqlite3DeleteTable(0, pTab);
88889   }
88890   sqlite3HashClear(&temp1);
88891   sqlite3HashClear(&pSchema->fkeyHash);
88892   pSchema->pSeqTab = 0;
88893   if( pSchema->flags & DB_SchemaLoaded ){
88894     pSchema->iGeneration++;
88895     pSchema->flags &= ~DB_SchemaLoaded;
88896   }
88897 }
88898 
88899 /*
88900 ** Find and return the schema associated with a BTree.  Create
88901 ** a new one if necessary.
88902 */
88903 SQLITE_PRIVATE Schema *sqlite3SchemaGet(sqlite3 *db, Btree *pBt){
88904   Schema * p;
88905   if( pBt ){
88906     p = (Schema *)sqlite3BtreeSchema(pBt, sizeof(Schema), sqlite3SchemaClear);
88907   }else{
88908     p = (Schema *)sqlite3DbMallocZero(0, sizeof(Schema));
88909   }
88910   if( !p ){
88911     db->mallocFailed = 1;
88912   }else if ( 0==p->file_format ){
88913     sqlite3HashInit(&p->tblHash);
88914     sqlite3HashInit(&p->idxHash);
88915     sqlite3HashInit(&p->trigHash);
88916     sqlite3HashInit(&p->fkeyHash);
88917     p->enc = SQLITE_UTF8;
88918   }
88919   return p;
88920 }
88921 
88922 /************** End of callback.c ********************************************/
88923 /************** Begin file delete.c ******************************************/
88924 /*
88925 ** 2001 September 15
88926 **
88927 ** The author disclaims copyright to this source code.  In place of
88928 ** a legal notice, here is a blessing:
88929 **
88930 **    May you do good and not evil.
88931 **    May you find forgiveness for yourself and forgive others.
88932 **    May you share freely, never taking more than you give.
88933 **
88934 *************************************************************************
88935 ** This file contains C code routines that are called by the parser
88936 ** in order to generate code for DELETE FROM statements.
88937 */
88938 
88939 /*
88940 ** While a SrcList can in general represent multiple tables and subqueries
88941 ** (as in the FROM clause of a SELECT statement) in this case it contains
88942 ** the name of a single table, as one might find in an INSERT, DELETE,
88943 ** or UPDATE statement.  Look up that table in the symbol table and
88944 ** return a pointer.  Set an error message and return NULL if the table 
88945 ** name is not found or if any other error occurs.
88946 **
88947 ** The following fields are initialized appropriate in pSrc:
88948 **
88949 **    pSrc->a[0].pTab       Pointer to the Table object
88950 **    pSrc->a[0].pIndex     Pointer to the INDEXED BY index, if there is one
88951 **
88952 */
88953 SQLITE_PRIVATE Table *sqlite3SrcListLookup(Parse *pParse, SrcList *pSrc){
88954   struct SrcList_item *pItem = pSrc->a;
88955   Table *pTab;
88956   assert( pItem && pSrc->nSrc==1 );
88957   pTab = sqlite3LocateTableItem(pParse, 0, pItem);
88958   sqlite3DeleteTable(pParse->db, pItem->pTab);
88959   pItem->pTab = pTab;
88960   if( pTab ){
88961     pTab->nRef++;
88962   }
88963   if( sqlite3IndexedByLookup(pParse, pItem) ){
88964     pTab = 0;
88965   }
88966   return pTab;
88967 }
88968 
88969 /*
88970 ** Check to make sure the given table is writable.  If it is not
88971 ** writable, generate an error message and return 1.  If it is
88972 ** writable return 0;
88973 */
88974 SQLITE_PRIVATE int sqlite3IsReadOnly(Parse *pParse, Table *pTab, int viewOk){
88975   /* A table is not writable under the following circumstances:
88976   **
88977   **   1) It is a virtual table and no implementation of the xUpdate method
88978   **      has been provided, or
88979   **   2) It is a system table (i.e. sqlite_master), this call is not
88980   **      part of a nested parse and writable_schema pragma has not 
88981   **      been specified.
88982   **
88983   ** In either case leave an error message in pParse and return non-zero.
88984   */
88985   if( ( IsVirtual(pTab) 
88986      && sqlite3GetVTable(pParse->db, pTab)->pMod->pModule->xUpdate==0 )
88987    || ( (pTab->tabFlags & TF_Readonly)!=0
88988      && (pParse->db->flags & SQLITE_WriteSchema)==0
88989      && pParse->nested==0 )
88990   ){
88991     sqlite3ErrorMsg(pParse, "table %s may not be modified", pTab->zName);
88992     return 1;
88993   }
88994 
88995 #ifndef SQLITE_OMIT_VIEW
88996   if( !viewOk && pTab->pSelect ){
88997     sqlite3ErrorMsg(pParse,"cannot modify %s because it is a view",pTab->zName);
88998     return 1;
88999   }
89000 #endif
89001   return 0;
89002 }
89003 
89004 
89005 #if !defined(SQLITE_OMIT_VIEW) && !defined(SQLITE_OMIT_TRIGGER)
89006 /*
89007 ** Evaluate a view and store its result in an ephemeral table.  The
89008 ** pWhere argument is an optional WHERE clause that restricts the
89009 ** set of rows in the view that are to be added to the ephemeral table.
89010 */
89011 SQLITE_PRIVATE void sqlite3MaterializeView(
89012   Parse *pParse,       /* Parsing context */
89013   Table *pView,        /* View definition */
89014   Expr *pWhere,        /* Optional WHERE clause to be added */
89015   int iCur             /* Cursor number for ephemerial table */
89016 ){
89017   SelectDest dest;
89018   Select *pSel;
89019   SrcList *pFrom;
89020   sqlite3 *db = pParse->db;
89021   int iDb = sqlite3SchemaToIndex(db, pView->pSchema);
89022 
89023   pWhere = sqlite3ExprDup(db, pWhere, 0);
89024   pFrom = sqlite3SrcListAppend(db, 0, 0, 0);
89025 
89026   if( pFrom ){
89027     assert( pFrom->nSrc==1 );
89028     pFrom->a[0].zName = sqlite3DbStrDup(db, pView->zName);
89029     pFrom->a[0].zDatabase = sqlite3DbStrDup(db, db->aDb[iDb].zName);
89030     assert( pFrom->a[0].pOn==0 );
89031     assert( pFrom->a[0].pUsing==0 );
89032   }
89033 
89034   pSel = sqlite3SelectNew(pParse, 0, pFrom, pWhere, 0, 0, 0, 0, 0, 0);
89035   if( pSel ) pSel->selFlags |= SF_Materialize;
89036 
89037   sqlite3SelectDestInit(&dest, SRT_EphemTab, iCur);
89038   sqlite3Select(pParse, pSel, &dest);
89039   sqlite3SelectDelete(db, pSel);
89040 }
89041 #endif /* !defined(SQLITE_OMIT_VIEW) && !defined(SQLITE_OMIT_TRIGGER) */
89042 
89043 #if defined(SQLITE_ENABLE_UPDATE_DELETE_LIMIT) && !defined(SQLITE_OMIT_SUBQUERY)
89044 /*
89045 ** Generate an expression tree to implement the WHERE, ORDER BY,
89046 ** and LIMIT/OFFSET portion of DELETE and UPDATE statements.
89047 **
89048 **     DELETE FROM table_wxyz WHERE a<5 ORDER BY a LIMIT 1;
89049 **                            \__________________________/
89050 **                               pLimitWhere (pInClause)
89051 */
89052 SQLITE_PRIVATE Expr *sqlite3LimitWhere(
89053   Parse *pParse,               /* The parser context */
89054   SrcList *pSrc,               /* the FROM clause -- which tables to scan */
89055   Expr *pWhere,                /* The WHERE clause.  May be null */
89056   ExprList *pOrderBy,          /* The ORDER BY clause.  May be null */
89057   Expr *pLimit,                /* The LIMIT clause.  May be null */
89058   Expr *pOffset,               /* The OFFSET clause.  May be null */
89059   char *zStmtType              /* Either DELETE or UPDATE.  For err msgs. */
89060 ){
89061   Expr *pWhereRowid = NULL;    /* WHERE rowid .. */
89062   Expr *pInClause = NULL;      /* WHERE rowid IN ( select ) */
89063   Expr *pSelectRowid = NULL;   /* SELECT rowid ... */
89064   ExprList *pEList = NULL;     /* Expression list contaning only pSelectRowid */
89065   SrcList *pSelectSrc = NULL;  /* SELECT rowid FROM x ... (dup of pSrc) */
89066   Select *pSelect = NULL;      /* Complete SELECT tree */
89067 
89068   /* Check that there isn't an ORDER BY without a LIMIT clause.
89069   */
89070   if( pOrderBy && (pLimit == 0) ) {
89071     sqlite3ErrorMsg(pParse, "ORDER BY without LIMIT on %s", zStmtType);
89072     goto limit_where_cleanup_2;
89073   }
89074 
89075   /* We only need to generate a select expression if there
89076   ** is a limit/offset term to enforce.
89077   */
89078   if( pLimit == 0 ) {
89079     /* if pLimit is null, pOffset will always be null as well. */
89080     assert( pOffset == 0 );
89081     return pWhere;
89082   }
89083 
89084   /* Generate a select expression tree to enforce the limit/offset 
89085   ** term for the DELETE or UPDATE statement.  For example:
89086   **   DELETE FROM table_a WHERE col1=1 ORDER BY col2 LIMIT 1 OFFSET 1
89087   ** becomes:
89088   **   DELETE FROM table_a WHERE rowid IN ( 
89089   **     SELECT rowid FROM table_a WHERE col1=1 ORDER BY col2 LIMIT 1 OFFSET 1
89090   **   );
89091   */
89092 
89093   pSelectRowid = sqlite3PExpr(pParse, TK_ROW, 0, 0, 0);
89094   if( pSelectRowid == 0 ) goto limit_where_cleanup_2;
89095   pEList = sqlite3ExprListAppend(pParse, 0, pSelectRowid);
89096   if( pEList == 0 ) goto limit_where_cleanup_2;
89097 
89098   /* duplicate the FROM clause as it is needed by both the DELETE/UPDATE tree
89099   ** and the SELECT subtree. */
89100   pSelectSrc = sqlite3SrcListDup(pParse->db, pSrc, 0);
89101   if( pSelectSrc == 0 ) {
89102     sqlite3ExprListDelete(pParse->db, pEList);
89103     goto limit_where_cleanup_2;
89104   }
89105 
89106   /* generate the SELECT expression tree. */
89107   pSelect = sqlite3SelectNew(pParse,pEList,pSelectSrc,pWhere,0,0,
89108                              pOrderBy,0,pLimit,pOffset);
89109   if( pSelect == 0 ) return 0;
89110 
89111   /* now generate the new WHERE rowid IN clause for the DELETE/UDPATE */
89112   pWhereRowid = sqlite3PExpr(pParse, TK_ROW, 0, 0, 0);
89113   if( pWhereRowid == 0 ) goto limit_where_cleanup_1;
89114   pInClause = sqlite3PExpr(pParse, TK_IN, pWhereRowid, 0, 0);
89115   if( pInClause == 0 ) goto limit_where_cleanup_1;
89116 
89117   pInClause->x.pSelect = pSelect;
89118   pInClause->flags |= EP_xIsSelect;
89119   sqlite3ExprSetHeight(pParse, pInClause);
89120   return pInClause;
89121 
89122   /* something went wrong. clean up anything allocated. */
89123 limit_where_cleanup_1:
89124   sqlite3SelectDelete(pParse->db, pSelect);
89125   return 0;
89126 
89127 limit_where_cleanup_2:
89128   sqlite3ExprDelete(pParse->db, pWhere);
89129   sqlite3ExprListDelete(pParse->db, pOrderBy);
89130   sqlite3ExprDelete(pParse->db, pLimit);
89131   sqlite3ExprDelete(pParse->db, pOffset);
89132   return 0;
89133 }
89134 #endif /* defined(SQLITE_ENABLE_UPDATE_DELETE_LIMIT) */
89135        /*      && !defined(SQLITE_OMIT_SUBQUERY) */
89136 
89137 /*
89138 ** Generate code for a DELETE FROM statement.
89139 **
89140 **     DELETE FROM table_wxyz WHERE a<5 AND b NOT NULL;
89141 **                 \________/       \________________/
89142 **                  pTabList              pWhere
89143 */
89144 SQLITE_PRIVATE void sqlite3DeleteFrom(
89145   Parse *pParse,         /* The parser context */
89146   SrcList *pTabList,     /* The table from which we should delete things */
89147   Expr *pWhere           /* The WHERE clause.  May be null */
89148 ){
89149   Vdbe *v;               /* The virtual database engine */
89150   Table *pTab;           /* The table from which records will be deleted */
89151   const char *zDb;       /* Name of database holding pTab */
89152   int i;                 /* Loop counter */
89153   WhereInfo *pWInfo;     /* Information about the WHERE clause */
89154   Index *pIdx;           /* For looping over indices of the table */
89155   int iTabCur;           /* Cursor number for the table */
89156   int iDataCur;          /* VDBE cursor for the canonical data source */
89157   int iIdxCur;           /* Cursor number of the first index */
89158   int nIdx;              /* Number of indices */
89159   sqlite3 *db;           /* Main database structure */
89160   AuthContext sContext;  /* Authorization context */
89161   NameContext sNC;       /* Name context to resolve expressions in */
89162   int iDb;               /* Database number */
89163   int memCnt = -1;       /* Memory cell used for change counting */
89164   int rcauth;            /* Value returned by authorization callback */
89165   int okOnePass;         /* True for one-pass algorithm without the FIFO */
89166   int aiCurOnePass[2];   /* The write cursors opened by WHERE_ONEPASS */
89167   u8 *aToOpen = 0;       /* Open cursor iTabCur+j if aToOpen[j] is true */
89168   Index *pPk;            /* The PRIMARY KEY index on the table */
89169   int iPk = 0;           /* First of nPk registers holding PRIMARY KEY value */
89170   i16 nPk = 1;           /* Number of columns in the PRIMARY KEY */
89171   int iKey;              /* Memory cell holding key of row to be deleted */
89172   i16 nKey;              /* Number of memory cells in the row key */
89173   int iEphCur = 0;       /* Ephemeral table holding all primary key values */
89174   int iRowSet = 0;       /* Register for rowset of rows to delete */
89175   int addrBypass = 0;    /* Address of jump over the delete logic */
89176   int addrLoop = 0;      /* Top of the delete loop */
89177   int addrDelete = 0;    /* Jump directly to the delete logic */
89178   int addrEphOpen = 0;   /* Instruction to open the Ephermeral table */
89179  
89180 #ifndef SQLITE_OMIT_TRIGGER
89181   int isView;                  /* True if attempting to delete from a view */
89182   Trigger *pTrigger;           /* List of table triggers, if required */
89183 #endif
89184 
89185   memset(&sContext, 0, sizeof(sContext));
89186   db = pParse->db;
89187   if( pParse->nErr || db->mallocFailed ){
89188     goto delete_from_cleanup;
89189   }
89190   assert( pTabList->nSrc==1 );
89191 
89192   /* Locate the table which we want to delete.  This table has to be
89193   ** put in an SrcList structure because some of the subroutines we
89194   ** will be calling are designed to work with multiple tables and expect
89195   ** an SrcList* parameter instead of just a Table* parameter.
89196   */
89197   pTab = sqlite3SrcListLookup(pParse, pTabList);
89198   if( pTab==0 )  goto delete_from_cleanup;
89199 
89200   /* Figure out if we have any triggers and if the table being
89201   ** deleted from is a view
89202   */
89203 #ifndef SQLITE_OMIT_TRIGGER
89204   pTrigger = sqlite3TriggersExist(pParse, pTab, TK_DELETE, 0, 0);
89205   isView = pTab->pSelect!=0;
89206 #else
89207 # define pTrigger 0
89208 # define isView 0
89209 #endif
89210 #ifdef SQLITE_OMIT_VIEW
89211 # undef isView
89212 # define isView 0
89213 #endif
89214 
89215   /* If pTab is really a view, make sure it has been initialized.
89216   */
89217   if( sqlite3ViewGetColumnNames(pParse, pTab) ){
89218     goto delete_from_cleanup;
89219   }
89220 
89221   if( sqlite3IsReadOnly(pParse, pTab, (pTrigger?1:0)) ){
89222     goto delete_from_cleanup;
89223   }
89224   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
89225   assert( iDb<db->nDb );
89226   zDb = db->aDb[iDb].zName;
89227   rcauth = sqlite3AuthCheck(pParse, SQLITE_DELETE, pTab->zName, 0, zDb);
89228   assert( rcauth==SQLITE_OK || rcauth==SQLITE_DENY || rcauth==SQLITE_IGNORE );
89229   if( rcauth==SQLITE_DENY ){
89230     goto delete_from_cleanup;
89231   }
89232   assert(!isView || pTrigger);
89233 
89234   /* Assign cursor numbers to the table and all its indices.
89235   */
89236   assert( pTabList->nSrc==1 );
89237   iTabCur = pTabList->a[0].iCursor = pParse->nTab++;
89238   for(nIdx=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, nIdx++){
89239     pParse->nTab++;
89240   }
89241 
89242   /* Start the view context
89243   */
89244   if( isView ){
89245     sqlite3AuthContextPush(pParse, &sContext, pTab->zName);
89246   }
89247 
89248   /* Begin generating code.
89249   */
89250   v = sqlite3GetVdbe(pParse);
89251   if( v==0 ){
89252     goto delete_from_cleanup;
89253   }
89254   if( pParse->nested==0 ) sqlite3VdbeCountChanges(v);
89255   sqlite3BeginWriteOperation(pParse, 1, iDb);
89256 
89257   /* If we are trying to delete from a view, realize that view into
89258   ** a ephemeral table.
89259   */
89260 #if !defined(SQLITE_OMIT_VIEW) && !defined(SQLITE_OMIT_TRIGGER)
89261   if( isView ){
89262     sqlite3MaterializeView(pParse, pTab, pWhere, iTabCur);
89263     iDataCur = iIdxCur = iTabCur;
89264   }
89265 #endif
89266 
89267   /* Resolve the column names in the WHERE clause.
89268   */
89269   memset(&sNC, 0, sizeof(sNC));
89270   sNC.pParse = pParse;
89271   sNC.pSrcList = pTabList;
89272   if( sqlite3ResolveExprNames(&sNC, pWhere) ){
89273     goto delete_from_cleanup;
89274   }
89275 
89276   /* Initialize the counter of the number of rows deleted, if
89277   ** we are counting rows.
89278   */
89279   if( db->flags & SQLITE_CountRows ){
89280     memCnt = ++pParse->nMem;
89281     sqlite3VdbeAddOp2(v, OP_Integer, 0, memCnt);
89282   }
89283 
89284 #ifndef SQLITE_OMIT_TRUNCATE_OPTIMIZATION
89285   /* Special case: A DELETE without a WHERE clause deletes everything.
89286   ** It is easier just to erase the whole table. Prior to version 3.6.5,
89287   ** this optimization caused the row change count (the value returned by 
89288   ** API function sqlite3_count_changes) to be set incorrectly.  */
89289   if( rcauth==SQLITE_OK && pWhere==0 && !pTrigger && !IsVirtual(pTab) 
89290    && 0==sqlite3FkRequired(pParse, pTab, 0, 0)
89291   ){
89292     assert( !isView );
89293     sqlite3TableLock(pParse, iDb, pTab->tnum, 1, pTab->zName);
89294     if( HasRowid(pTab) ){
89295       sqlite3VdbeAddOp4(v, OP_Clear, pTab->tnum, iDb, memCnt,
89296                         pTab->zName, P4_STATIC);
89297     }
89298     for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
89299       assert( pIdx->pSchema==pTab->pSchema );
89300       sqlite3VdbeAddOp2(v, OP_Clear, pIdx->tnum, iDb);
89301     }
89302   }else
89303 #endif /* SQLITE_OMIT_TRUNCATE_OPTIMIZATION */
89304   {
89305     if( HasRowid(pTab) ){
89306       /* For a rowid table, initialize the RowSet to an empty set */
89307       pPk = 0;
89308       nPk = 1;
89309       iRowSet = ++pParse->nMem;
89310       sqlite3VdbeAddOp2(v, OP_Null, 0, iRowSet);
89311     }else{
89312       /* For a WITHOUT ROWID table, create an ephermeral table used to
89313       ** hold all primary keys for rows to be deleted. */
89314       pPk = sqlite3PrimaryKeyIndex(pTab);
89315       assert( pPk!=0 );
89316       nPk = pPk->nKeyCol;
89317       iPk = pParse->nMem+1;
89318       pParse->nMem += nPk;
89319       iEphCur = pParse->nTab++;
89320       addrEphOpen = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, iEphCur, nPk);
89321       sqlite3VdbeSetP4KeyInfo(pParse, pPk);
89322     }
89323   
89324     /* Construct a query to find the rowid or primary key for every row
89325     ** to be deleted, based on the WHERE clause.
89326     */
89327     pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, 0, 0, 
89328                                WHERE_ONEPASS_DESIRED|WHERE_DUPLICATES_OK,
89329                                iTabCur+1);
89330     if( pWInfo==0 ) goto delete_from_cleanup;
89331     okOnePass = sqlite3WhereOkOnePass(pWInfo, aiCurOnePass);
89332   
89333     /* Keep track of the number of rows to be deleted */
89334     if( db->flags & SQLITE_CountRows ){
89335       sqlite3VdbeAddOp2(v, OP_AddImm, memCnt, 1);
89336     }
89337   
89338     /* Extract the rowid or primary key for the current row */
89339     if( pPk ){
89340       for(i=0; i<nPk; i++){
89341         sqlite3ExprCodeGetColumnOfTable(v, pTab, iTabCur,
89342                                         pPk->aiColumn[i], iPk+i);
89343       }
89344       iKey = iPk;
89345     }else{
89346       iKey = pParse->nMem + 1;
89347       iKey = sqlite3ExprCodeGetColumn(pParse, pTab, -1, iTabCur, iKey, 0);
89348       if( iKey>pParse->nMem ) pParse->nMem = iKey;
89349     }
89350   
89351     if( okOnePass ){
89352       /* For ONEPASS, no need to store the rowid/primary-key.  There is only
89353       ** one, so just keep it in its register(s) and fall through to the
89354       ** delete code.
89355       */
89356       nKey = nPk; /* OP_Found will use an unpacked key */
89357       aToOpen = sqlite3DbMallocRaw(db, nIdx+2);
89358       if( aToOpen==0 ){
89359         sqlite3WhereEnd(pWInfo);
89360         goto delete_from_cleanup;
89361       }
89362       memset(aToOpen, 1, nIdx+1);
89363       aToOpen[nIdx+1] = 0;
89364       if( aiCurOnePass[0]>=0 ) aToOpen[aiCurOnePass[0]-iTabCur] = 0;
89365       if( aiCurOnePass[1]>=0 ) aToOpen[aiCurOnePass[1]-iTabCur] = 0;
89366       if( addrEphOpen ) sqlite3VdbeChangeToNoop(v, addrEphOpen);
89367       addrDelete = sqlite3VdbeAddOp0(v, OP_Goto); /* Jump to DELETE logic */
89368     }else if( pPk ){
89369       /* Construct a composite key for the row to be deleted and remember it */
89370       iKey = ++pParse->nMem;
89371       nKey = 0;   /* Zero tells OP_Found to use a composite key */
89372       sqlite3VdbeAddOp4(v, OP_MakeRecord, iPk, nPk, iKey,
89373                         sqlite3IndexAffinityStr(v, pPk), P4_TRANSIENT);
89374       sqlite3VdbeAddOp2(v, OP_IdxInsert, iEphCur, iKey);
89375     }else{
89376       /* Get the rowid of the row to be deleted and remember it in the RowSet */
89377       nKey = 1;  /* OP_Seek always uses a single rowid */
89378       sqlite3VdbeAddOp2(v, OP_RowSetAdd, iRowSet, iKey);
89379     }
89380   
89381     /* End of the WHERE loop */
89382     sqlite3WhereEnd(pWInfo);
89383     if( okOnePass ){
89384       /* Bypass the delete logic below if the WHERE loop found zero rows */
89385       addrBypass = sqlite3VdbeMakeLabel(v);
89386       sqlite3VdbeAddOp2(v, OP_Goto, 0, addrBypass);
89387       sqlite3VdbeJumpHere(v, addrDelete);
89388     }
89389   
89390     /* Unless this is a view, open cursors for the table we are 
89391     ** deleting from and all its indices. If this is a view, then the
89392     ** only effect this statement has is to fire the INSTEAD OF 
89393     ** triggers.
89394     */
89395     if( !isView ){
89396       sqlite3OpenTableAndIndices(pParse, pTab, OP_OpenWrite, iTabCur, aToOpen,
89397                                  &iDataCur, &iIdxCur);
89398       assert( pPk || iDataCur==iTabCur );
89399       assert( pPk || iIdxCur==iDataCur+1 );
89400     }
89401   
89402     /* Set up a loop over the rowids/primary-keys that were found in the
89403     ** where-clause loop above.
89404     */
89405     if( okOnePass ){
89406       /* Just one row.  Hence the top-of-loop is a no-op */
89407       assert( nKey==nPk ); /* OP_Found will use an unpacked key */
89408       if( aToOpen[iDataCur-iTabCur] ){
89409         assert( pPk!=0 );
89410         sqlite3VdbeAddOp4Int(v, OP_NotFound, iDataCur, addrBypass, iKey, nKey);
89411       }
89412     }else if( pPk ){
89413       addrLoop = sqlite3VdbeAddOp1(v, OP_Rewind, iEphCur);
89414       sqlite3VdbeAddOp2(v, OP_RowKey, iEphCur, iKey);
89415       assert( nKey==0 );  /* OP_Found will use a composite key */
89416     }else{
89417       addrLoop = sqlite3VdbeAddOp3(v, OP_RowSetRead, iRowSet, 0, iKey);
89418       assert( nKey==1 );
89419     }  
89420   
89421     /* Delete the row */
89422 #ifndef SQLITE_OMIT_VIRTUALTABLE
89423     if( IsVirtual(pTab) ){
89424       const char *pVTab = (const char *)sqlite3GetVTable(db, pTab);
89425       sqlite3VtabMakeWritable(pParse, pTab);
89426       sqlite3VdbeAddOp4(v, OP_VUpdate, 0, 1, iKey, pVTab, P4_VTAB);
89427       sqlite3VdbeChangeP5(v, OE_Abort);
89428       sqlite3MayAbort(pParse);
89429     }else
89430 #endif
89431     {
89432       int count = (pParse->nested==0);    /* True to count changes */
89433       sqlite3GenerateRowDelete(pParse, pTab, pTrigger, iDataCur, iIdxCur,
89434                                iKey, nKey, count, OE_Default, okOnePass);
89435     }
89436   
89437     /* End of the loop over all rowids/primary-keys. */
89438     if( okOnePass ){
89439       sqlite3VdbeResolveLabel(v, addrBypass);
89440     }else if( pPk ){
89441       sqlite3VdbeAddOp2(v, OP_Next, iEphCur, addrLoop+1);
89442       sqlite3VdbeJumpHere(v, addrLoop);
89443     }else{
89444       sqlite3VdbeAddOp2(v, OP_Goto, 0, addrLoop);
89445       sqlite3VdbeJumpHere(v, addrLoop);
89446     }     
89447   
89448     /* Close the cursors open on the table and its indexes. */
89449     if( !isView && !IsVirtual(pTab) ){
89450       if( !pPk ) sqlite3VdbeAddOp1(v, OP_Close, iDataCur);
89451       for(i=0, pIdx=pTab->pIndex; pIdx; i++, pIdx=pIdx->pNext){
89452         sqlite3VdbeAddOp1(v, OP_Close, iIdxCur + i);
89453       }
89454     }
89455   } /* End non-truncate path */
89456 
89457   /* Update the sqlite_sequence table by storing the content of the
89458   ** maximum rowid counter values recorded while inserting into
89459   ** autoincrement tables.
89460   */
89461   if( pParse->nested==0 && pParse->pTriggerTab==0 ){
89462     sqlite3AutoincrementEnd(pParse);
89463   }
89464 
89465   /* Return the number of rows that were deleted. If this routine is 
89466   ** generating code because of a call to sqlite3NestedParse(), do not
89467   ** invoke the callback function.
89468   */
89469   if( (db->flags&SQLITE_CountRows) && !pParse->nested && !pParse->pTriggerTab ){
89470     sqlite3VdbeAddOp2(v, OP_ResultRow, memCnt, 1);
89471     sqlite3VdbeSetNumCols(v, 1);
89472     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "rows deleted", SQLITE_STATIC);
89473   }
89474 
89475 delete_from_cleanup:
89476   sqlite3AuthContextPop(&sContext);
89477   sqlite3SrcListDelete(db, pTabList);
89478   sqlite3ExprDelete(db, pWhere);
89479   sqlite3DbFree(db, aToOpen);
89480   return;
89481 }
89482 /* Make sure "isView" and other macros defined above are undefined. Otherwise
89483 ** thely may interfere with compilation of other functions in this file
89484 ** (or in another file, if this file becomes part of the amalgamation).  */
89485 #ifdef isView
89486  #undef isView
89487 #endif
89488 #ifdef pTrigger
89489  #undef pTrigger
89490 #endif
89491 
89492 /*
89493 ** This routine generates VDBE code that causes a single row of a
89494 ** single table to be deleted.  Both the original table entry and
89495 ** all indices are removed.
89496 **
89497 ** Preconditions:
89498 **
89499 **   1.  iDataCur is an open cursor on the btree that is the canonical data
89500 **       store for the table.  (This will be either the table itself,
89501 **       in the case of a rowid table, or the PRIMARY KEY index in the case
89502 **       of a WITHOUT ROWID table.)
89503 **
89504 **   2.  Read/write cursors for all indices of pTab must be open as
89505 **       cursor number iIdxCur+i for the i-th index.
89506 **
89507 **   3.  The primary key for the row to be deleted must be stored in a
89508 **       sequence of nPk memory cells starting at iPk.  If nPk==0 that means
89509 **       that a search record formed from OP_MakeRecord is contained in the
89510 **       single memory location iPk.
89511 */
89512 SQLITE_PRIVATE void sqlite3GenerateRowDelete(
89513   Parse *pParse,     /* Parsing context */
89514   Table *pTab,       /* Table containing the row to be deleted */
89515   Trigger *pTrigger, /* List of triggers to (potentially) fire */
89516   int iDataCur,      /* Cursor from which column data is extracted */
89517   int iIdxCur,       /* First index cursor */
89518   int iPk,           /* First memory cell containing the PRIMARY KEY */
89519   i16 nPk,           /* Number of PRIMARY KEY memory cells */
89520   u8 count,          /* If non-zero, increment the row change counter */
89521   u8 onconf,         /* Default ON CONFLICT policy for triggers */
89522   u8 bNoSeek         /* iDataCur is already pointing to the row to delete */
89523 ){
89524   Vdbe *v = pParse->pVdbe;        /* Vdbe */
89525   int iOld = 0;                   /* First register in OLD.* array */
89526   int iLabel;                     /* Label resolved to end of generated code */
89527   u8 opSeek;                      /* Seek opcode */
89528 
89529   /* Vdbe is guaranteed to have been allocated by this stage. */
89530   assert( v );
89531   VdbeModuleComment((v, "BEGIN: GenRowDel(%d,%d,%d,%d)",
89532                          iDataCur, iIdxCur, iPk, (int)nPk));
89533 
89534   /* Seek cursor iCur to the row to delete. If this row no longer exists 
89535   ** (this can happen if a trigger program has already deleted it), do
89536   ** not attempt to delete it or fire any DELETE triggers.  */
89537   iLabel = sqlite3VdbeMakeLabel(v);
89538   opSeek = HasRowid(pTab) ? OP_NotExists : OP_NotFound;
89539   if( !bNoSeek ) sqlite3VdbeAddOp4Int(v, opSeek, iDataCur, iLabel, iPk, nPk);
89540  
89541   /* If there are any triggers to fire, allocate a range of registers to
89542   ** use for the old.* references in the triggers.  */
89543   if( sqlite3FkRequired(pParse, pTab, 0, 0) || pTrigger ){
89544     u32 mask;                     /* Mask of OLD.* columns in use */
89545     int iCol;                     /* Iterator used while populating OLD.* */
89546     int addrStart;                /* Start of BEFORE trigger programs */
89547 
89548     /* TODO: Could use temporary registers here. Also could attempt to
89549     ** avoid copying the contents of the rowid register.  */
89550     mask = sqlite3TriggerColmask(
89551         pParse, pTrigger, 0, 0, TRIGGER_BEFORE|TRIGGER_AFTER, pTab, onconf
89552     );
89553     mask |= sqlite3FkOldmask(pParse, pTab);
89554     iOld = pParse->nMem+1;
89555     pParse->nMem += (1 + pTab->nCol);
89556 
89557     /* Populate the OLD.* pseudo-table register array. These values will be 
89558     ** used by any BEFORE and AFTER triggers that exist.  */
89559     sqlite3VdbeAddOp2(v, OP_Copy, iPk, iOld);
89560     for(iCol=0; iCol<pTab->nCol; iCol++){
89561       if( mask==0xffffffff || mask&(1<<iCol) ){
89562         sqlite3ExprCodeGetColumnOfTable(v, pTab, iDataCur, iCol, iOld+iCol+1);
89563       }
89564     }
89565 
89566     /* Invoke BEFORE DELETE trigger programs. */
89567     addrStart = sqlite3VdbeCurrentAddr(v);
89568     sqlite3CodeRowTrigger(pParse, pTrigger, 
89569         TK_DELETE, 0, TRIGGER_BEFORE, pTab, iOld, onconf, iLabel
89570     );
89571 
89572     /* If any BEFORE triggers were coded, then seek the cursor to the 
89573     ** row to be deleted again. It may be that the BEFORE triggers moved
89574     ** the cursor or of already deleted the row that the cursor was
89575     ** pointing to.
89576     */
89577     if( addrStart<sqlite3VdbeCurrentAddr(v) ){
89578       sqlite3VdbeAddOp4Int(v, opSeek, iDataCur, iLabel, iPk, nPk);
89579     }
89580 
89581     /* Do FK processing. This call checks that any FK constraints that
89582     ** refer to this table (i.e. constraints attached to other tables) 
89583     ** are not violated by deleting this row.  */
89584     sqlite3FkCheck(pParse, pTab, iOld, 0, 0, 0);
89585   }
89586 
89587   /* Delete the index and table entries. Skip this step if pTab is really
89588   ** a view (in which case the only effect of the DELETE statement is to
89589   ** fire the INSTEAD OF triggers).  */ 
89590   if( pTab->pSelect==0 ){
89591     sqlite3GenerateRowIndexDelete(pParse, pTab, iDataCur, iIdxCur, 0);
89592     sqlite3VdbeAddOp2(v, OP_Delete, iDataCur, (count?OPFLAG_NCHANGE:0));
89593     if( count ){
89594       sqlite3VdbeChangeP4(v, -1, pTab->zName, P4_TRANSIENT);
89595     }
89596   }
89597 
89598   /* Do any ON CASCADE, SET NULL or SET DEFAULT operations required to
89599   ** handle rows (possibly in other tables) that refer via a foreign key
89600   ** to the row just deleted. */ 
89601   sqlite3FkActions(pParse, pTab, 0, iOld, 0, 0);
89602 
89603   /* Invoke AFTER DELETE trigger programs. */
89604   sqlite3CodeRowTrigger(pParse, pTrigger, 
89605       TK_DELETE, 0, TRIGGER_AFTER, pTab, iOld, onconf, iLabel
89606   );
89607 
89608   /* Jump here if the row had already been deleted before any BEFORE
89609   ** trigger programs were invoked. Or if a trigger program throws a 
89610   ** RAISE(IGNORE) exception.  */
89611   sqlite3VdbeResolveLabel(v, iLabel);
89612   VdbeModuleComment((v, "END: GenRowDel()"));
89613 }
89614 
89615 /*
89616 ** This routine generates VDBE code that causes the deletion of all
89617 ** index entries associated with a single row of a single table, pTab
89618 **
89619 ** Preconditions:
89620 **
89621 **   1.  A read/write cursor "iDataCur" must be open on the canonical storage
89622 **       btree for the table pTab.  (This will be either the table itself
89623 **       for rowid tables or to the primary key index for WITHOUT ROWID
89624 **       tables.)
89625 **
89626 **   2.  Read/write cursors for all indices of pTab must be open as
89627 **       cursor number iIdxCur+i for the i-th index.  (The pTab->pIndex
89628 **       index is the 0-th index.)
89629 **
89630 **   3.  The "iDataCur" cursor must be already be positioned on the row
89631 **       that is to be deleted.
89632 */
89633 SQLITE_PRIVATE void sqlite3GenerateRowIndexDelete(
89634   Parse *pParse,     /* Parsing and code generating context */
89635   Table *pTab,       /* Table containing the row to be deleted */
89636   int iDataCur,      /* Cursor of table holding data. */
89637   int iIdxCur,       /* First index cursor */
89638   int *aRegIdx       /* Only delete if aRegIdx!=0 && aRegIdx[i]>0 */
89639 ){
89640   int i;             /* Index loop counter */
89641   int r1;            /* Register holding an index key */
89642   int iPartIdxLabel; /* Jump destination for skipping partial index entries */
89643   Index *pIdx;       /* Current index */
89644   Vdbe *v;           /* The prepared statement under construction */
89645   Index *pPk;        /* PRIMARY KEY index, or NULL for rowid tables */
89646 
89647   v = pParse->pVdbe;
89648   pPk = HasRowid(pTab) ? 0 : sqlite3PrimaryKeyIndex(pTab);
89649   for(i=0, pIdx=pTab->pIndex; pIdx; i++, pIdx=pIdx->pNext){
89650     assert( iIdxCur+i!=iDataCur || pPk==pIdx );
89651     if( aRegIdx!=0 && aRegIdx[i]==0 ) continue;
89652     if( pIdx==pPk ) continue;
89653     VdbeModuleComment((v, "GenRowIdxDel for %s", pIdx->zName));
89654     r1 = sqlite3GenerateIndexKey(pParse, pIdx, iDataCur, 0, 1, &iPartIdxLabel);
89655     sqlite3VdbeAddOp3(v, OP_IdxDelete, iIdxCur+i, r1,
89656                       pIdx->uniqNotNull ? pIdx->nKeyCol : pIdx->nColumn);
89657     sqlite3VdbeResolveLabel(v, iPartIdxLabel);
89658   }
89659 }
89660 
89661 /*
89662 ** Generate code that will assemble an index key and stores it in register
89663 ** regOut.  The key with be for index pIdx which is an index on pTab.
89664 ** iCur is the index of a cursor open on the pTab table and pointing to
89665 ** the entry that needs indexing.  If pTab is a WITHOUT ROWID table, then
89666 ** iCur must be the cursor of the PRIMARY KEY index.
89667 **
89668 ** Return a register number which is the first in a block of
89669 ** registers that holds the elements of the index key.  The
89670 ** block of registers has already been deallocated by the time
89671 ** this routine returns.
89672 **
89673 ** If *piPartIdxLabel is not NULL, fill it in with a label and jump
89674 ** to that label if pIdx is a partial index that should be skipped.
89675 ** A partial index should be skipped if its WHERE clause evaluates
89676 ** to false or null.  If pIdx is not a partial index, *piPartIdxLabel
89677 ** will be set to zero which is an empty label that is ignored by
89678 ** sqlite3VdbeResolveLabel().
89679 */
89680 SQLITE_PRIVATE int sqlite3GenerateIndexKey(
89681   Parse *pParse,       /* Parsing context */
89682   Index *pIdx,         /* The index for which to generate a key */
89683   int iDataCur,        /* Cursor number from which to take column data */
89684   int regOut,          /* Put the new key into this register if not 0 */
89685   int prefixOnly,      /* Compute only a unique prefix of the key */
89686   int *piPartIdxLabel  /* OUT: Jump to this label to skip partial index */
89687 ){
89688   Vdbe *v = pParse->pVdbe;
89689   int j;
89690   Table *pTab = pIdx->pTable;
89691   int regBase;
89692   int nCol;
89693   Index *pPk;
89694 
89695   if( piPartIdxLabel ){
89696     if( pIdx->pPartIdxWhere ){
89697       *piPartIdxLabel = sqlite3VdbeMakeLabel(v);
89698       pParse->iPartIdxTab = iDataCur;
89699       sqlite3ExprIfFalse(pParse, pIdx->pPartIdxWhere, *piPartIdxLabel, 
89700                          SQLITE_JUMPIFNULL);
89701     }else{
89702       *piPartIdxLabel = 0;
89703     }
89704   }
89705   nCol = (prefixOnly && pIdx->uniqNotNull) ? pIdx->nKeyCol : pIdx->nColumn;
89706   regBase = sqlite3GetTempRange(pParse, nCol);
89707   pPk = HasRowid(pTab) ? 0 : sqlite3PrimaryKeyIndex(pTab);
89708   for(j=0; j<nCol; j++){
89709     i16 idx = pIdx->aiColumn[j];
89710     if( pPk ) idx = sqlite3ColumnOfIndex(pPk, idx);
89711     if( idx<0 || idx==pTab->iPKey ){
89712       sqlite3VdbeAddOp2(v, OP_Rowid, iDataCur, regBase+j);
89713     }else{
89714       sqlite3VdbeAddOp3(v, OP_Column, iDataCur, idx, regBase+j);
89715       sqlite3ColumnDefault(v, pTab, pIdx->aiColumn[j], -1);
89716     }
89717   }
89718   if( regOut ){
89719     const char *zAff;
89720     if( pTab->pSelect
89721      || OptimizationDisabled(pParse->db, SQLITE_IdxRealAsInt)
89722     ){
89723       zAff = 0;
89724     }else{
89725       zAff = sqlite3IndexAffinityStr(v, pIdx);
89726     }
89727     sqlite3VdbeAddOp3(v, OP_MakeRecord, regBase, nCol, regOut);
89728     sqlite3VdbeChangeP4(v, -1, zAff, P4_TRANSIENT);
89729   }
89730   sqlite3ReleaseTempRange(pParse, regBase, nCol);
89731   return regBase;
89732 }
89733 
89734 /************** End of delete.c **********************************************/
89735 /************** Begin file func.c ********************************************/
89736 /*
89737 ** 2002 February 23
89738 **
89739 ** The author disclaims copyright to this source code.  In place of
89740 ** a legal notice, here is a blessing:
89741 **
89742 **    May you do good and not evil.
89743 **    May you find forgiveness for yourself and forgive others.
89744 **    May you share freely, never taking more than you give.
89745 **
89746 *************************************************************************
89747 ** This file contains the C functions that implement various SQL
89748 ** functions of SQLite.  
89749 **
89750 ** There is only one exported symbol in this file - the function
89751 ** sqliteRegisterBuildinFunctions() found at the bottom of the file.
89752 ** All other code has file scope.
89753 */
89754 /* #include <stdlib.h> */
89755 /* #include <assert.h> */
89756 
89757 /*
89758 ** Return the collating function associated with a function.
89759 */
89760 static CollSeq *sqlite3GetFuncCollSeq(sqlite3_context *context){
89761   return context->pColl;
89762 }
89763 
89764 /*
89765 ** Indicate that the accumulator load should be skipped on this
89766 ** iteration of the aggregate loop.
89767 */
89768 static void sqlite3SkipAccumulatorLoad(sqlite3_context *context){
89769   context->skipFlag = 1;
89770 }
89771 
89772 /*
89773 ** Implementation of the non-aggregate min() and max() functions
89774 */
89775 static void minmaxFunc(
89776   sqlite3_context *context,
89777   int argc,
89778   sqlite3_value **argv
89779 ){
89780   int i;
89781   int mask;    /* 0 for min() or 0xffffffff for max() */
89782   int iBest;
89783   CollSeq *pColl;
89784 
89785   assert( argc>1 );
89786   mask = sqlite3_user_data(context)==0 ? 0 : -1;
89787   pColl = sqlite3GetFuncCollSeq(context);
89788   assert( pColl );
89789   assert( mask==-1 || mask==0 );
89790   iBest = 0;
89791   if( sqlite3_value_type(argv[0])==SQLITE_NULL ) return;
89792   for(i=1; i<argc; i++){
89793     if( sqlite3_value_type(argv[i])==SQLITE_NULL ) return;
89794     if( (sqlite3MemCompare(argv[iBest], argv[i], pColl)^mask)>=0 ){
89795       testcase( mask==0 );
89796       iBest = i;
89797     }
89798   }
89799   sqlite3_result_value(context, argv[iBest]);
89800 }
89801 
89802 /*
89803 ** Return the type of the argument.
89804 */
89805 static void typeofFunc(
89806   sqlite3_context *context,
89807   int NotUsed,
89808   sqlite3_value **argv
89809 ){
89810   const char *z = 0;
89811   UNUSED_PARAMETER(NotUsed);
89812   switch( sqlite3_value_type(argv[0]) ){
89813     case SQLITE_INTEGER: z = "integer"; break;
89814     case SQLITE_TEXT:    z = "text";    break;
89815     case SQLITE_FLOAT:   z = "real";    break;
89816     case SQLITE_BLOB:    z = "blob";    break;
89817     default:             z = "null";    break;
89818   }
89819   sqlite3_result_text(context, z, -1, SQLITE_STATIC);
89820 }
89821 
89822 
89823 /*
89824 ** Implementation of the length() function
89825 */
89826 static void lengthFunc(
89827   sqlite3_context *context,
89828   int argc,
89829   sqlite3_value **argv
89830 ){
89831   int len;
89832 
89833   assert( argc==1 );
89834   UNUSED_PARAMETER(argc);
89835   switch( sqlite3_value_type(argv[0]) ){
89836     case SQLITE_BLOB:
89837     case SQLITE_INTEGER:
89838     case SQLITE_FLOAT: {
89839       sqlite3_result_int(context, sqlite3_value_bytes(argv[0]));
89840       break;
89841     }
89842     case SQLITE_TEXT: {
89843       const unsigned char *z = sqlite3_value_text(argv[0]);
89844       if( z==0 ) return;
89845       len = 0;
89846       while( *z ){
89847         len++;
89848         SQLITE_SKIP_UTF8(z);
89849       }
89850       sqlite3_result_int(context, len);
89851       break;
89852     }
89853     default: {
89854       sqlite3_result_null(context);
89855       break;
89856     }
89857   }
89858 }
89859 
89860 /*
89861 ** Implementation of the abs() function.
89862 **
89863 ** IMP: R-23979-26855 The abs(X) function returns the absolute value of
89864 ** the numeric argument X. 
89865 */
89866 static void absFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
89867   assert( argc==1 );
89868   UNUSED_PARAMETER(argc);
89869   switch( sqlite3_value_type(argv[0]) ){
89870     case SQLITE_INTEGER: {
89871       i64 iVal = sqlite3_value_int64(argv[0]);
89872       if( iVal<0 ){
89873         if( (iVal<<1)==0 ){
89874           /* IMP: R-31676-45509 If X is the integer -9223372036854775808
89875           ** then abs(X) throws an integer overflow error since there is no
89876           ** equivalent positive 64-bit two complement value. */
89877           sqlite3_result_error(context, "integer overflow", -1);
89878           return;
89879         }
89880         iVal = -iVal;
89881       } 
89882       sqlite3_result_int64(context, iVal);
89883       break;
89884     }
89885     case SQLITE_NULL: {
89886       /* IMP: R-37434-19929 Abs(X) returns NULL if X is NULL. */
89887       sqlite3_result_null(context);
89888       break;
89889     }
89890     default: {
89891       /* Because sqlite3_value_double() returns 0.0 if the argument is not
89892       ** something that can be converted into a number, we have:
89893       ** IMP: R-57326-31541 Abs(X) return 0.0 if X is a string or blob that
89894       ** cannot be converted to a numeric value. 
89895       */
89896       double rVal = sqlite3_value_double(argv[0]);
89897       if( rVal<0 ) rVal = -rVal;
89898       sqlite3_result_double(context, rVal);
89899       break;
89900     }
89901   }
89902 }
89903 
89904 /*
89905 ** Implementation of the instr() function.
89906 **
89907 ** instr(haystack,needle) finds the first occurrence of needle
89908 ** in haystack and returns the number of previous characters plus 1,
89909 ** or 0 if needle does not occur within haystack.
89910 **
89911 ** If both haystack and needle are BLOBs, then the result is one more than
89912 ** the number of bytes in haystack prior to the first occurrence of needle,
89913 ** or 0 if needle never occurs in haystack.
89914 */
89915 static void instrFunc(
89916   sqlite3_context *context,
89917   int argc,
89918   sqlite3_value **argv
89919 ){
89920   const unsigned char *zHaystack;
89921   const unsigned char *zNeedle;
89922   int nHaystack;
89923   int nNeedle;
89924   int typeHaystack, typeNeedle;
89925   int N = 1;
89926   int isText;
89927 
89928   UNUSED_PARAMETER(argc);
89929   typeHaystack = sqlite3_value_type(argv[0]);
89930   typeNeedle = sqlite3_value_type(argv[1]);
89931   if( typeHaystack==SQLITE_NULL || typeNeedle==SQLITE_NULL ) return;
89932   nHaystack = sqlite3_value_bytes(argv[0]);
89933   nNeedle = sqlite3_value_bytes(argv[1]);
89934   if( typeHaystack==SQLITE_BLOB && typeNeedle==SQLITE_BLOB ){
89935     zHaystack = sqlite3_value_blob(argv[0]);
89936     zNeedle = sqlite3_value_blob(argv[1]);
89937     isText = 0;
89938   }else{
89939     zHaystack = sqlite3_value_text(argv[0]);
89940     zNeedle = sqlite3_value_text(argv[1]);
89941     isText = 1;
89942   }
89943   while( nNeedle<=nHaystack && memcmp(zHaystack, zNeedle, nNeedle)!=0 ){
89944     N++;
89945     do{
89946       nHaystack--;
89947       zHaystack++;
89948     }while( isText && (zHaystack[0]&0xc0)==0x80 );
89949   }
89950   if( nNeedle>nHaystack ) N = 0;
89951   sqlite3_result_int(context, N);
89952 }
89953 
89954 /*
89955 ** Implementation of the substr() function.
89956 **
89957 ** substr(x,p1,p2)  returns p2 characters of x[] beginning with p1.
89958 ** p1 is 1-indexed.  So substr(x,1,1) returns the first character
89959 ** of x.  If x is text, then we actually count UTF-8 characters.
89960 ** If x is a blob, then we count bytes.
89961 **
89962 ** If p1 is negative, then we begin abs(p1) from the end of x[].
89963 **
89964 ** If p2 is negative, return the p2 characters preceding p1.
89965 */
89966 static void substrFunc(
89967   sqlite3_context *context,
89968   int argc,
89969   sqlite3_value **argv
89970 ){
89971   const unsigned char *z;
89972   const unsigned char *z2;
89973   int len;
89974   int p0type;
89975   i64 p1, p2;
89976   int negP2 = 0;
89977 
89978   assert( argc==3 || argc==2 );
89979   if( sqlite3_value_type(argv[1])==SQLITE_NULL
89980    || (argc==3 && sqlite3_value_type(argv[2])==SQLITE_NULL)
89981   ){
89982     return;
89983   }
89984   p0type = sqlite3_value_type(argv[0]);
89985   p1 = sqlite3_value_int(argv[1]);
89986   if( p0type==SQLITE_BLOB ){
89987     len = sqlite3_value_bytes(argv[0]);
89988     z = sqlite3_value_blob(argv[0]);
89989     if( z==0 ) return;
89990     assert( len==sqlite3_value_bytes(argv[0]) );
89991   }else{
89992     z = sqlite3_value_text(argv[0]);
89993     if( z==0 ) return;
89994     len = 0;
89995     if( p1<0 ){
89996       for(z2=z; *z2; len++){
89997         SQLITE_SKIP_UTF8(z2);
89998       }
89999     }
90000   }
90001   if( argc==3 ){
90002     p2 = sqlite3_value_int(argv[2]);
90003     if( p2<0 ){
90004       p2 = -p2;
90005       negP2 = 1;
90006     }
90007   }else{
90008     p2 = sqlite3_context_db_handle(context)->aLimit[SQLITE_LIMIT_LENGTH];
90009   }
90010   if( p1<0 ){
90011     p1 += len;
90012     if( p1<0 ){
90013       p2 += p1;
90014       if( p2<0 ) p2 = 0;
90015       p1 = 0;
90016     }
90017   }else if( p1>0 ){
90018     p1--;
90019   }else if( p2>0 ){
90020     p2--;
90021   }
90022   if( negP2 ){
90023     p1 -= p2;
90024     if( p1<0 ){
90025       p2 += p1;
90026       p1 = 0;
90027     }
90028   }
90029   assert( p1>=0 && p2>=0 );
90030   if( p0type!=SQLITE_BLOB ){
90031     while( *z && p1 ){
90032       SQLITE_SKIP_UTF8(z);
90033       p1--;
90034     }
90035     for(z2=z; *z2 && p2; p2--){
90036       SQLITE_SKIP_UTF8(z2);
90037     }
90038     sqlite3_result_text(context, (char*)z, (int)(z2-z), SQLITE_TRANSIENT);
90039   }else{
90040     if( p1+p2>len ){
90041       p2 = len-p1;
90042       if( p2<0 ) p2 = 0;
90043     }
90044     sqlite3_result_blob(context, (char*)&z[p1], (int)p2, SQLITE_TRANSIENT);
90045   }
90046 }
90047 
90048 /*
90049 ** Implementation of the round() function
90050 */
90051 #ifndef SQLITE_OMIT_FLOATING_POINT
90052 static void roundFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
90053   int n = 0;
90054   double r;
90055   char *zBuf;
90056   assert( argc==1 || argc==2 );
90057   if( argc==2 ){
90058     if( SQLITE_NULL==sqlite3_value_type(argv[1]) ) return;
90059     n = sqlite3_value_int(argv[1]);
90060     if( n>30 ) n = 30;
90061     if( n<0 ) n = 0;
90062   }
90063   if( sqlite3_value_type(argv[0])==SQLITE_NULL ) return;
90064   r = sqlite3_value_double(argv[0]);
90065   /* If Y==0 and X will fit in a 64-bit int,
90066   ** handle the rounding directly,
90067   ** otherwise use printf.
90068   */
90069   if( n==0 && r>=0 && r<LARGEST_INT64-1 ){
90070     r = (double)((sqlite_int64)(r+0.5));
90071   }else if( n==0 && r<0 && (-r)<LARGEST_INT64-1 ){
90072     r = -(double)((sqlite_int64)((-r)+0.5));
90073   }else{
90074     zBuf = sqlite3_mprintf("%.*f",n,r);
90075     if( zBuf==0 ){
90076       sqlite3_result_error_nomem(context);
90077       return;
90078     }
90079     sqlite3AtoF(zBuf, &r, sqlite3Strlen30(zBuf), SQLITE_UTF8);
90080     sqlite3_free(zBuf);
90081   }
90082   sqlite3_result_double(context, r);
90083 }
90084 #endif
90085 
90086 /*
90087 ** Allocate nByte bytes of space using sqlite3_malloc(). If the
90088 ** allocation fails, call sqlite3_result_error_nomem() to notify
90089 ** the database handle that malloc() has failed and return NULL.
90090 ** If nByte is larger than the maximum string or blob length, then
90091 ** raise an SQLITE_TOOBIG exception and return NULL.
90092 */
90093 static void *contextMalloc(sqlite3_context *context, i64 nByte){
90094   char *z;
90095   sqlite3 *db = sqlite3_context_db_handle(context);
90096   assert( nByte>0 );
90097   testcase( nByte==db->aLimit[SQLITE_LIMIT_LENGTH] );
90098   testcase( nByte==db->aLimit[SQLITE_LIMIT_LENGTH]+1 );
90099   if( nByte>db->aLimit[SQLITE_LIMIT_LENGTH] ){
90100     sqlite3_result_error_toobig(context);
90101     z = 0;
90102   }else{
90103     z = sqlite3Malloc((int)nByte);
90104     if( !z ){
90105       sqlite3_result_error_nomem(context);
90106     }
90107   }
90108   return z;
90109 }
90110 
90111 /*
90112 ** Implementation of the upper() and lower() SQL functions.
90113 */
90114 static void upperFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
90115   char *z1;
90116   const char *z2;
90117   int i, n;
90118   UNUSED_PARAMETER(argc);
90119   z2 = (char*)sqlite3_value_text(argv[0]);
90120   n = sqlite3_value_bytes(argv[0]);
90121   /* Verify that the call to _bytes() does not invalidate the _text() pointer */
90122   assert( z2==(char*)sqlite3_value_text(argv[0]) );
90123   if( z2 ){
90124     z1 = contextMalloc(context, ((i64)n)+1);
90125     if( z1 ){
90126       for(i=0; i<n; i++){
90127         z1[i] = (char)sqlite3Toupper(z2[i]);
90128       }
90129       sqlite3_result_text(context, z1, n, sqlite3_free);
90130     }
90131   }
90132 }
90133 static void lowerFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
90134   char *z1;
90135   const char *z2;
90136   int i, n;
90137   UNUSED_PARAMETER(argc);
90138   z2 = (char*)sqlite3_value_text(argv[0]);
90139   n = sqlite3_value_bytes(argv[0]);
90140   /* Verify that the call to _bytes() does not invalidate the _text() pointer */
90141   assert( z2==(char*)sqlite3_value_text(argv[0]) );
90142   if( z2 ){
90143     z1 = contextMalloc(context, ((i64)n)+1);
90144     if( z1 ){
90145       for(i=0; i<n; i++){
90146         z1[i] = sqlite3Tolower(z2[i]);
90147       }
90148       sqlite3_result_text(context, z1, n, sqlite3_free);
90149     }
90150   }
90151 }
90152 
90153 /*
90154 ** Some functions like COALESCE() and IFNULL() and UNLIKELY() are implemented
90155 ** as VDBE code so that unused argument values do not have to be computed.
90156 ** However, we still need some kind of function implementation for this
90157 ** routines in the function table.  The noopFunc macro provides this.
90158 ** noopFunc will never be called so it doesn't matter what the implementation
90159 ** is.  We might as well use the "version()" function as a substitute.
90160 */
90161 #define noopFunc versionFunc   /* Substitute function - never called */
90162 
90163 /*
90164 ** Implementation of random().  Return a random integer.  
90165 */
90166 static void randomFunc(
90167   sqlite3_context *context,
90168   int NotUsed,
90169   sqlite3_value **NotUsed2
90170 ){
90171   sqlite_int64 r;
90172   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90173   sqlite3_randomness(sizeof(r), &r);
90174   if( r<0 ){
90175     /* We need to prevent a random number of 0x8000000000000000 
90176     ** (or -9223372036854775808) since when you do abs() of that
90177     ** number of you get the same value back again.  To do this
90178     ** in a way that is testable, mask the sign bit off of negative
90179     ** values, resulting in a positive value.  Then take the 
90180     ** 2s complement of that positive value.  The end result can
90181     ** therefore be no less than -9223372036854775807.
90182     */
90183     r = -(r & LARGEST_INT64);
90184   }
90185   sqlite3_result_int64(context, r);
90186 }
90187 
90188 /*
90189 ** Implementation of randomblob(N).  Return a random blob
90190 ** that is N bytes long.
90191 */
90192 static void randomBlob(
90193   sqlite3_context *context,
90194   int argc,
90195   sqlite3_value **argv
90196 ){
90197   int n;
90198   unsigned char *p;
90199   assert( argc==1 );
90200   UNUSED_PARAMETER(argc);
90201   n = sqlite3_value_int(argv[0]);
90202   if( n<1 ){
90203     n = 1;
90204   }
90205   p = contextMalloc(context, n);
90206   if( p ){
90207     sqlite3_randomness(n, p);
90208     sqlite3_result_blob(context, (char*)p, n, sqlite3_free);
90209   }
90210 }
90211 
90212 /*
90213 ** Implementation of the last_insert_rowid() SQL function.  The return
90214 ** value is the same as the sqlite3_last_insert_rowid() API function.
90215 */
90216 static void last_insert_rowid(
90217   sqlite3_context *context, 
90218   int NotUsed, 
90219   sqlite3_value **NotUsed2
90220 ){
90221   sqlite3 *db = sqlite3_context_db_handle(context);
90222   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90223   /* IMP: R-51513-12026 The last_insert_rowid() SQL function is a
90224   ** wrapper around the sqlite3_last_insert_rowid() C/C++ interface
90225   ** function. */
90226   sqlite3_result_int64(context, sqlite3_last_insert_rowid(db));
90227 }
90228 
90229 /*
90230 ** Implementation of the changes() SQL function.
90231 **
90232 ** IMP: R-62073-11209 The changes() SQL function is a wrapper
90233 ** around the sqlite3_changes() C/C++ function and hence follows the same
90234 ** rules for counting changes.
90235 */
90236 static void changes(
90237   sqlite3_context *context,
90238   int NotUsed,
90239   sqlite3_value **NotUsed2
90240 ){
90241   sqlite3 *db = sqlite3_context_db_handle(context);
90242   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90243   sqlite3_result_int(context, sqlite3_changes(db));
90244 }
90245 
90246 /*
90247 ** Implementation of the total_changes() SQL function.  The return value is
90248 ** the same as the sqlite3_total_changes() API function.
90249 */
90250 static void total_changes(
90251   sqlite3_context *context,
90252   int NotUsed,
90253   sqlite3_value **NotUsed2
90254 ){
90255   sqlite3 *db = sqlite3_context_db_handle(context);
90256   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90257   /* IMP: R-52756-41993 This function is a wrapper around the
90258   ** sqlite3_total_changes() C/C++ interface. */
90259   sqlite3_result_int(context, sqlite3_total_changes(db));
90260 }
90261 
90262 /*
90263 ** A structure defining how to do GLOB-style comparisons.
90264 */
90265 struct compareInfo {
90266   u8 matchAll;
90267   u8 matchOne;
90268   u8 matchSet;
90269   u8 noCase;
90270 };
90271 
90272 /*
90273 ** For LIKE and GLOB matching on EBCDIC machines, assume that every
90274 ** character is exactly one byte in size.  Also, all characters are
90275 ** able to participate in upper-case-to-lower-case mappings in EBCDIC
90276 ** whereas only characters less than 0x80 do in ASCII.
90277 */
90278 #if defined(SQLITE_EBCDIC)
90279 # define sqlite3Utf8Read(A)    (*((*A)++))
90280 # define GlobUpperToLower(A)   A = sqlite3UpperToLower[A]
90281 #else
90282 # define GlobUpperToLower(A)   if( !((A)&~0x7f) ){ A = sqlite3UpperToLower[A]; }
90283 #endif
90284 
90285 static const struct compareInfo globInfo = { '*', '?', '[', 0 };
90286 /* The correct SQL-92 behavior is for the LIKE operator to ignore
90287 ** case.  Thus  'a' LIKE 'A' would be true. */
90288 static const struct compareInfo likeInfoNorm = { '%', '_',   0, 1 };
90289 /* If SQLITE_CASE_SENSITIVE_LIKE is defined, then the LIKE operator
90290 ** is case sensitive causing 'a' LIKE 'A' to be false */
90291 static const struct compareInfo likeInfoAlt = { '%', '_',   0, 0 };
90292 
90293 /*
90294 ** Compare two UTF-8 strings for equality where the first string can
90295 ** potentially be a "glob" expression.  Return true (1) if they
90296 ** are the same and false (0) if they are different.
90297 **
90298 ** Globbing rules:
90299 **
90300 **      '*'       Matches any sequence of zero or more characters.
90301 **
90302 **      '?'       Matches exactly one character.
90303 **
90304 **     [...]      Matches one character from the enclosed list of
90305 **                characters.
90306 **
90307 **     [^...]     Matches one character not in the enclosed list.
90308 **
90309 ** With the [...] and [^...] matching, a ']' character can be included
90310 ** in the list by making it the first character after '[' or '^'.  A
90311 ** range of characters can be specified using '-'.  Example:
90312 ** "[a-z]" matches any single lower-case letter.  To match a '-', make
90313 ** it the last character in the list.
90314 **
90315 ** This routine is usually quick, but can be N**2 in the worst case.
90316 **
90317 ** Hints: to match '*' or '?', put them in "[]".  Like this:
90318 **
90319 **         abc[*]xyz        Matches "abc*xyz" only
90320 */
90321 static int patternCompare(
90322   const u8 *zPattern,              /* The glob pattern */
90323   const u8 *zString,               /* The string to compare against the glob */
90324   const struct compareInfo *pInfo, /* Information about how to do the compare */
90325   u32 esc                          /* The escape character */
90326 ){
90327   u32 c, c2;
90328   int invert;
90329   int seen;
90330   u8 matchOne = pInfo->matchOne;
90331   u8 matchAll = pInfo->matchAll;
90332   u8 matchSet = pInfo->matchSet;
90333   u8 noCase = pInfo->noCase; 
90334   int prevEscape = 0;     /* True if the previous character was 'escape' */
90335 
90336   while( (c = sqlite3Utf8Read(&zPattern))!=0 ){
90337     if( c==matchAll && !prevEscape ){
90338       while( (c=sqlite3Utf8Read(&zPattern)) == matchAll
90339                || c == matchOne ){
90340         if( c==matchOne && sqlite3Utf8Read(&zString)==0 ){
90341           return 0;
90342         }
90343       }
90344       if( c==0 ){
90345         return 1;
90346       }else if( c==esc ){
90347         c = sqlite3Utf8Read(&zPattern);
90348         if( c==0 ){
90349           return 0;
90350         }
90351       }else if( c==matchSet ){
90352         assert( esc==0 );         /* This is GLOB, not LIKE */
90353         assert( matchSet<0x80 );  /* '[' is a single-byte character */
90354         while( *zString && patternCompare(&zPattern[-1],zString,pInfo,esc)==0 ){
90355           SQLITE_SKIP_UTF8(zString);
90356         }
90357         return *zString!=0;
90358       }
90359       while( (c2 = sqlite3Utf8Read(&zString))!=0 ){
90360         if( noCase ){
90361           GlobUpperToLower(c2);
90362           GlobUpperToLower(c);
90363           while( c2 != 0 && c2 != c ){
90364             c2 = sqlite3Utf8Read(&zString);
90365             GlobUpperToLower(c2);
90366           }
90367         }else{
90368           while( c2 != 0 && c2 != c ){
90369             c2 = sqlite3Utf8Read(&zString);
90370           }
90371         }
90372         if( c2==0 ) return 0;
90373         if( patternCompare(zPattern,zString,pInfo,esc) ) return 1;
90374       }
90375       return 0;
90376     }else if( c==matchOne && !prevEscape ){
90377       if( sqlite3Utf8Read(&zString)==0 ){
90378         return 0;
90379       }
90380     }else if( c==matchSet ){
90381       u32 prior_c = 0;
90382       assert( esc==0 );    /* This only occurs for GLOB, not LIKE */
90383       seen = 0;
90384       invert = 0;
90385       c = sqlite3Utf8Read(&zString);
90386       if( c==0 ) return 0;
90387       c2 = sqlite3Utf8Read(&zPattern);
90388       if( c2=='^' ){
90389         invert = 1;
90390         c2 = sqlite3Utf8Read(&zPattern);
90391       }
90392       if( c2==']' ){
90393         if( c==']' ) seen = 1;
90394         c2 = sqlite3Utf8Read(&zPattern);
90395       }
90396       while( c2 && c2!=']' ){
90397         if( c2=='-' && zPattern[0]!=']' && zPattern[0]!=0 && prior_c>0 ){
90398           c2 = sqlite3Utf8Read(&zPattern);
90399           if( c>=prior_c && c<=c2 ) seen = 1;
90400           prior_c = 0;
90401         }else{
90402           if( c==c2 ){
90403             seen = 1;
90404           }
90405           prior_c = c2;
90406         }
90407         c2 = sqlite3Utf8Read(&zPattern);
90408       }
90409       if( c2==0 || (seen ^ invert)==0 ){
90410         return 0;
90411       }
90412     }else if( esc==c && !prevEscape ){
90413       prevEscape = 1;
90414     }else{
90415       c2 = sqlite3Utf8Read(&zString);
90416       if( noCase ){
90417         GlobUpperToLower(c);
90418         GlobUpperToLower(c2);
90419       }
90420       if( c!=c2 ){
90421         return 0;
90422       }
90423       prevEscape = 0;
90424     }
90425   }
90426   return *zString==0;
90427 }
90428 
90429 /*
90430 ** The sqlite3_strglob() interface.
90431 */
90432 SQLITE_API int sqlite3_strglob(const char *zGlobPattern, const char *zString){
90433   return patternCompare((u8*)zGlobPattern, (u8*)zString, &globInfo, 0)==0;
90434 }
90435 
90436 /*
90437 ** Count the number of times that the LIKE operator (or GLOB which is
90438 ** just a variation of LIKE) gets called.  This is used for testing
90439 ** only.
90440 */
90441 #ifdef SQLITE_TEST
90442 SQLITE_API int sqlite3_like_count = 0;
90443 #endif
90444 
90445 
90446 /*
90447 ** Implementation of the like() SQL function.  This function implements
90448 ** the build-in LIKE operator.  The first argument to the function is the
90449 ** pattern and the second argument is the string.  So, the SQL statements:
90450 **
90451 **       A LIKE B
90452 **
90453 ** is implemented as like(B,A).
90454 **
90455 ** This same function (with a different compareInfo structure) computes
90456 ** the GLOB operator.
90457 */
90458 static void likeFunc(
90459   sqlite3_context *context, 
90460   int argc, 
90461   sqlite3_value **argv
90462 ){
90463   const unsigned char *zA, *zB;
90464   u32 escape = 0;
90465   int nPat;
90466   sqlite3 *db = sqlite3_context_db_handle(context);
90467 
90468   zB = sqlite3_value_text(argv[0]);
90469   zA = sqlite3_value_text(argv[1]);
90470 
90471   /* Limit the length of the LIKE or GLOB pattern to avoid problems
90472   ** of deep recursion and N*N behavior in patternCompare().
90473   */
90474   nPat = sqlite3_value_bytes(argv[0]);
90475   testcase( nPat==db->aLimit[SQLITE_LIMIT_LIKE_PATTERN_LENGTH] );
90476   testcase( nPat==db->aLimit[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]+1 );
90477   if( nPat > db->aLimit[SQLITE_LIMIT_LIKE_PATTERN_LENGTH] ){
90478     sqlite3_result_error(context, "LIKE or GLOB pattern too complex", -1);
90479     return;
90480   }
90481   assert( zB==sqlite3_value_text(argv[0]) );  /* Encoding did not change */
90482 
90483   if( argc==3 ){
90484     /* The escape character string must consist of a single UTF-8 character.
90485     ** Otherwise, return an error.
90486     */
90487     const unsigned char *zEsc = sqlite3_value_text(argv[2]);
90488     if( zEsc==0 ) return;
90489     if( sqlite3Utf8CharLen((char*)zEsc, -1)!=1 ){
90490       sqlite3_result_error(context, 
90491           "ESCAPE expression must be a single character", -1);
90492       return;
90493     }
90494     escape = sqlite3Utf8Read(&zEsc);
90495   }
90496   if( zA && zB ){
90497     struct compareInfo *pInfo = sqlite3_user_data(context);
90498 #ifdef SQLITE_TEST
90499     sqlite3_like_count++;
90500 #endif
90501     
90502     sqlite3_result_int(context, patternCompare(zB, zA, pInfo, escape));
90503   }
90504 }
90505 
90506 /*
90507 ** Implementation of the NULLIF(x,y) function.  The result is the first
90508 ** argument if the arguments are different.  The result is NULL if the
90509 ** arguments are equal to each other.
90510 */
90511 static void nullifFunc(
90512   sqlite3_context *context,
90513   int NotUsed,
90514   sqlite3_value **argv
90515 ){
90516   CollSeq *pColl = sqlite3GetFuncCollSeq(context);
90517   UNUSED_PARAMETER(NotUsed);
90518   if( sqlite3MemCompare(argv[0], argv[1], pColl)!=0 ){
90519     sqlite3_result_value(context, argv[0]);
90520   }
90521 }
90522 
90523 /*
90524 ** Implementation of the sqlite_version() function.  The result is the version
90525 ** of the SQLite library that is running.
90526 */
90527 static void versionFunc(
90528   sqlite3_context *context,
90529   int NotUsed,
90530   sqlite3_value **NotUsed2
90531 ){
90532   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90533   /* IMP: R-48699-48617 This function is an SQL wrapper around the
90534   ** sqlite3_libversion() C-interface. */
90535   sqlite3_result_text(context, sqlite3_libversion(), -1, SQLITE_STATIC);
90536 }
90537 
90538 /*
90539 ** Implementation of the sqlite_source_id() function. The result is a string
90540 ** that identifies the particular version of the source code used to build
90541 ** SQLite.
90542 */
90543 static void sourceidFunc(
90544   sqlite3_context *context,
90545   int NotUsed,
90546   sqlite3_value **NotUsed2
90547 ){
90548   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90549   /* IMP: R-24470-31136 This function is an SQL wrapper around the
90550   ** sqlite3_sourceid() C interface. */
90551   sqlite3_result_text(context, sqlite3_sourceid(), -1, SQLITE_STATIC);
90552 }
90553 
90554 /*
90555 ** Implementation of the sqlite_log() function.  This is a wrapper around
90556 ** sqlite3_log().  The return value is NULL.  The function exists purely for
90557 ** its side-effects.
90558 */
90559 static void errlogFunc(
90560   sqlite3_context *context,
90561   int argc,
90562   sqlite3_value **argv
90563 ){
90564   UNUSED_PARAMETER(argc);
90565   UNUSED_PARAMETER(context);
90566   sqlite3_log(sqlite3_value_int(argv[0]), "%s", sqlite3_value_text(argv[1]));
90567 }
90568 
90569 /*
90570 ** Implementation of the sqlite_compileoption_used() function.
90571 ** The result is an integer that identifies if the compiler option
90572 ** was used to build SQLite.
90573 */
90574 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
90575 static void compileoptionusedFunc(
90576   sqlite3_context *context,
90577   int argc,
90578   sqlite3_value **argv
90579 ){
90580   const char *zOptName;
90581   assert( argc==1 );
90582   UNUSED_PARAMETER(argc);
90583   /* IMP: R-39564-36305 The sqlite_compileoption_used() SQL
90584   ** function is a wrapper around the sqlite3_compileoption_used() C/C++
90585   ** function.
90586   */
90587   if( (zOptName = (const char*)sqlite3_value_text(argv[0]))!=0 ){
90588     sqlite3_result_int(context, sqlite3_compileoption_used(zOptName));
90589   }
90590 }
90591 #endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
90592 
90593 /*
90594 ** Implementation of the sqlite_compileoption_get() function. 
90595 ** The result is a string that identifies the compiler options 
90596 ** used to build SQLite.
90597 */
90598 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
90599 static void compileoptiongetFunc(
90600   sqlite3_context *context,
90601   int argc,
90602   sqlite3_value **argv
90603 ){
90604   int n;
90605   assert( argc==1 );
90606   UNUSED_PARAMETER(argc);
90607   /* IMP: R-04922-24076 The sqlite_compileoption_get() SQL function
90608   ** is a wrapper around the sqlite3_compileoption_get() C/C++ function.
90609   */
90610   n = sqlite3_value_int(argv[0]);
90611   sqlite3_result_text(context, sqlite3_compileoption_get(n), -1, SQLITE_STATIC);
90612 }
90613 #endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
90614 
90615 /* Array for converting from half-bytes (nybbles) into ASCII hex
90616 ** digits. */
90617 static const char hexdigits[] = {
90618   '0', '1', '2', '3', '4', '5', '6', '7',
90619   '8', '9', 'A', 'B', 'C', 'D', 'E', 'F' 
90620 };
90621 
90622 /*
90623 ** Implementation of the QUOTE() function.  This function takes a single
90624 ** argument.  If the argument is numeric, the return value is the same as
90625 ** the argument.  If the argument is NULL, the return value is the string
90626 ** "NULL".  Otherwise, the argument is enclosed in single quotes with
90627 ** single-quote escapes.
90628 */
90629 static void quoteFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
90630   assert( argc==1 );
90631   UNUSED_PARAMETER(argc);
90632   switch( sqlite3_value_type(argv[0]) ){
90633     case SQLITE_FLOAT: {
90634       double r1, r2;
90635       char zBuf[50];
90636       r1 = sqlite3_value_double(argv[0]);
90637       sqlite3_snprintf(sizeof(zBuf), zBuf, "%!.15g", r1);
90638       sqlite3AtoF(zBuf, &r2, 20, SQLITE_UTF8);
90639       if( r1!=r2 ){
90640         sqlite3_snprintf(sizeof(zBuf), zBuf, "%!.20e", r1);
90641       }
90642       sqlite3_result_text(context, zBuf, -1, SQLITE_TRANSIENT);
90643       break;
90644     }
90645     case SQLITE_INTEGER: {
90646       sqlite3_result_value(context, argv[0]);
90647       break;
90648     }
90649     case SQLITE_BLOB: {
90650       char *zText = 0;
90651       char const *zBlob = sqlite3_value_blob(argv[0]);
90652       int nBlob = sqlite3_value_bytes(argv[0]);
90653       assert( zBlob==sqlite3_value_blob(argv[0]) ); /* No encoding change */
90654       zText = (char *)contextMalloc(context, (2*(i64)nBlob)+4); 
90655       if( zText ){
90656         int i;
90657         for(i=0; i<nBlob; i++){
90658           zText[(i*2)+2] = hexdigits[(zBlob[i]>>4)&0x0F];
90659           zText[(i*2)+3] = hexdigits[(zBlob[i])&0x0F];
90660         }
90661         zText[(nBlob*2)+2] = '\'';
90662         zText[(nBlob*2)+3] = '\0';
90663         zText[0] = 'X';
90664         zText[1] = '\'';
90665         sqlite3_result_text(context, zText, -1, SQLITE_TRANSIENT);
90666         sqlite3_free(zText);
90667       }
90668       break;
90669     }
90670     case SQLITE_TEXT: {
90671       int i,j;
90672       u64 n;
90673       const unsigned char *zArg = sqlite3_value_text(argv[0]);
90674       char *z;
90675 
90676       if( zArg==0 ) return;
90677       for(i=0, n=0; zArg[i]; i++){ if( zArg[i]=='\'' ) n++; }
90678       z = contextMalloc(context, ((i64)i)+((i64)n)+3);
90679       if( z ){
90680         z[0] = '\'';
90681         for(i=0, j=1; zArg[i]; i++){
90682           z[j++] = zArg[i];
90683           if( zArg[i]=='\'' ){
90684             z[j++] = '\'';
90685           }
90686         }
90687         z[j++] = '\'';
90688         z[j] = 0;
90689         sqlite3_result_text(context, z, j, sqlite3_free);
90690       }
90691       break;
90692     }
90693     default: {
90694       assert( sqlite3_value_type(argv[0])==SQLITE_NULL );
90695       sqlite3_result_text(context, "NULL", 4, SQLITE_STATIC);
90696       break;
90697     }
90698   }
90699 }
90700 
90701 /*
90702 ** The unicode() function.  Return the integer unicode code-point value
90703 ** for the first character of the input string. 
90704 */
90705 static void unicodeFunc(
90706   sqlite3_context *context,
90707   int argc,
90708   sqlite3_value **argv
90709 ){
90710   const unsigned char *z = sqlite3_value_text(argv[0]);
90711   (void)argc;
90712   if( z && z[0] ) sqlite3_result_int(context, sqlite3Utf8Read(&z));
90713 }
90714 
90715 /*
90716 ** The char() function takes zero or more arguments, each of which is
90717 ** an integer.  It constructs a string where each character of the string
90718 ** is the unicode character for the corresponding integer argument.
90719 */
90720 static void charFunc(
90721   sqlite3_context *context,
90722   int argc,
90723   sqlite3_value **argv
90724 ){
90725   unsigned char *z, *zOut;
90726   int i;
90727   zOut = z = sqlite3_malloc( argc*4 );
90728   if( z==0 ){
90729     sqlite3_result_error_nomem(context);
90730     return;
90731   }
90732   for(i=0; i<argc; i++){
90733     sqlite3_int64 x;
90734     unsigned c;
90735     x = sqlite3_value_int64(argv[i]);
90736     if( x<0 || x>0x10ffff ) x = 0xfffd;
90737     c = (unsigned)(x & 0x1fffff);
90738     if( c<0x00080 ){
90739       *zOut++ = (u8)(c&0xFF);
90740     }else if( c<0x00800 ){
90741       *zOut++ = 0xC0 + (u8)((c>>6)&0x1F);
90742       *zOut++ = 0x80 + (u8)(c & 0x3F);
90743     }else if( c<0x10000 ){
90744       *zOut++ = 0xE0 + (u8)((c>>12)&0x0F);
90745       *zOut++ = 0x80 + (u8)((c>>6) & 0x3F);
90746       *zOut++ = 0x80 + (u8)(c & 0x3F);
90747     }else{
90748       *zOut++ = 0xF0 + (u8)((c>>18) & 0x07);
90749       *zOut++ = 0x80 + (u8)((c>>12) & 0x3F);
90750       *zOut++ = 0x80 + (u8)((c>>6) & 0x3F);
90751       *zOut++ = 0x80 + (u8)(c & 0x3F);
90752     }                                                    \
90753   }
90754   sqlite3_result_text(context, (char*)z, (int)(zOut-z), sqlite3_free);
90755 }
90756 
90757 /*
90758 ** The hex() function.  Interpret the argument as a blob.  Return
90759 ** a hexadecimal rendering as text.
90760 */
90761 static void hexFunc(
90762   sqlite3_context *context,
90763   int argc,
90764   sqlite3_value **argv
90765 ){
90766   int i, n;
90767   const unsigned char *pBlob;
90768   char *zHex, *z;
90769   assert( argc==1 );
90770   UNUSED_PARAMETER(argc);
90771   pBlob = sqlite3_value_blob(argv[0]);
90772   n = sqlite3_value_bytes(argv[0]);
90773   assert( pBlob==sqlite3_value_blob(argv[0]) );  /* No encoding change */
90774   z = zHex = contextMalloc(context, ((i64)n)*2 + 1);
90775   if( zHex ){
90776     for(i=0; i<n; i++, pBlob++){
90777       unsigned char c = *pBlob;
90778       *(z++) = hexdigits[(c>>4)&0xf];
90779       *(z++) = hexdigits[c&0xf];
90780     }
90781     *z = 0;
90782     sqlite3_result_text(context, zHex, n*2, sqlite3_free);
90783   }
90784 }
90785 
90786 /*
90787 ** The zeroblob(N) function returns a zero-filled blob of size N bytes.
90788 */
90789 static void zeroblobFunc(
90790   sqlite3_context *context,
90791   int argc,
90792   sqlite3_value **argv
90793 ){
90794   i64 n;
90795   sqlite3 *db = sqlite3_context_db_handle(context);
90796   assert( argc==1 );
90797   UNUSED_PARAMETER(argc);
90798   n = sqlite3_value_int64(argv[0]);
90799   testcase( n==db->aLimit[SQLITE_LIMIT_LENGTH] );
90800   testcase( n==db->aLimit[SQLITE_LIMIT_LENGTH]+1 );
90801   if( n>db->aLimit[SQLITE_LIMIT_LENGTH] ){
90802     sqlite3_result_error_toobig(context);
90803   }else{
90804     sqlite3_result_zeroblob(context, (int)n); /* IMP: R-00293-64994 */
90805   }
90806 }
90807 
90808 /*
90809 ** The replace() function.  Three arguments are all strings: call
90810 ** them A, B, and C. The result is also a string which is derived
90811 ** from A by replacing every occurrence of B with C.  The match
90812 ** must be exact.  Collating sequences are not used.
90813 */
90814 static void replaceFunc(
90815   sqlite3_context *context,
90816   int argc,
90817   sqlite3_value **argv
90818 ){
90819   const unsigned char *zStr;        /* The input string A */
90820   const unsigned char *zPattern;    /* The pattern string B */
90821   const unsigned char *zRep;        /* The replacement string C */
90822   unsigned char *zOut;              /* The output */
90823   int nStr;                /* Size of zStr */
90824   int nPattern;            /* Size of zPattern */
90825   int nRep;                /* Size of zRep */
90826   i64 nOut;                /* Maximum size of zOut */
90827   int loopLimit;           /* Last zStr[] that might match zPattern[] */
90828   int i, j;                /* Loop counters */
90829 
90830   assert( argc==3 );
90831   UNUSED_PARAMETER(argc);
90832   zStr = sqlite3_value_text(argv[0]);
90833   if( zStr==0 ) return;
90834   nStr = sqlite3_value_bytes(argv[0]);
90835   assert( zStr==sqlite3_value_text(argv[0]) );  /* No encoding change */
90836   zPattern = sqlite3_value_text(argv[1]);
90837   if( zPattern==0 ){
90838     assert( sqlite3_value_type(argv[1])==SQLITE_NULL
90839             || sqlite3_context_db_handle(context)->mallocFailed );
90840     return;
90841   }
90842   if( zPattern[0]==0 ){
90843     assert( sqlite3_value_type(argv[1])!=SQLITE_NULL );
90844     sqlite3_result_value(context, argv[0]);
90845     return;
90846   }
90847   nPattern = sqlite3_value_bytes(argv[1]);
90848   assert( zPattern==sqlite3_value_text(argv[1]) );  /* No encoding change */
90849   zRep = sqlite3_value_text(argv[2]);
90850   if( zRep==0 ) return;
90851   nRep = sqlite3_value_bytes(argv[2]);
90852   assert( zRep==sqlite3_value_text(argv[2]) );
90853   nOut = nStr + 1;
90854   assert( nOut<SQLITE_MAX_LENGTH );
90855   zOut = contextMalloc(context, (i64)nOut);
90856   if( zOut==0 ){
90857     return;
90858   }
90859   loopLimit = nStr - nPattern;  
90860   for(i=j=0; i<=loopLimit; i++){
90861     if( zStr[i]!=zPattern[0] || memcmp(&zStr[i], zPattern, nPattern) ){
90862       zOut[j++] = zStr[i];
90863     }else{
90864       u8 *zOld;
90865       sqlite3 *db = sqlite3_context_db_handle(context);
90866       nOut += nRep - nPattern;
90867       testcase( nOut-1==db->aLimit[SQLITE_LIMIT_LENGTH] );
90868       testcase( nOut-2==db->aLimit[SQLITE_LIMIT_LENGTH] );
90869       if( nOut-1>db->aLimit[SQLITE_LIMIT_LENGTH] ){
90870         sqlite3_result_error_toobig(context);
90871         sqlite3_free(zOut);
90872         return;
90873       }
90874       zOld = zOut;
90875       zOut = sqlite3_realloc(zOut, (int)nOut);
90876       if( zOut==0 ){
90877         sqlite3_result_error_nomem(context);
90878         sqlite3_free(zOld);
90879         return;
90880       }
90881       memcpy(&zOut[j], zRep, nRep);
90882       j += nRep;
90883       i += nPattern-1;
90884     }
90885   }
90886   assert( j+nStr-i+1==nOut );
90887   memcpy(&zOut[j], &zStr[i], nStr-i);
90888   j += nStr - i;
90889   assert( j<=nOut );
90890   zOut[j] = 0;
90891   sqlite3_result_text(context, (char*)zOut, j, sqlite3_free);
90892 }
90893 
90894 /*
90895 ** Implementation of the TRIM(), LTRIM(), and RTRIM() functions.
90896 ** The userdata is 0x1 for left trim, 0x2 for right trim, 0x3 for both.
90897 */
90898 static void trimFunc(
90899   sqlite3_context *context,
90900   int argc,
90901   sqlite3_value **argv
90902 ){
90903   const unsigned char *zIn;         /* Input string */
90904   const unsigned char *zCharSet;    /* Set of characters to trim */
90905   int nIn;                          /* Number of bytes in input */
90906   int flags;                        /* 1: trimleft  2: trimright  3: trim */
90907   int i;                            /* Loop counter */
90908   unsigned char *aLen = 0;          /* Length of each character in zCharSet */
90909   unsigned char **azChar = 0;       /* Individual characters in zCharSet */
90910   int nChar;                        /* Number of characters in zCharSet */
90911 
90912   if( sqlite3_value_type(argv[0])==SQLITE_NULL ){
90913     return;
90914   }
90915   zIn = sqlite3_value_text(argv[0]);
90916   if( zIn==0 ) return;
90917   nIn = sqlite3_value_bytes(argv[0]);
90918   assert( zIn==sqlite3_value_text(argv[0]) );
90919   if( argc==1 ){
90920     static const unsigned char lenOne[] = { 1 };
90921     static unsigned char * const azOne[] = { (u8*)" " };
90922     nChar = 1;
90923     aLen = (u8*)lenOne;
90924     azChar = (unsigned char **)azOne;
90925     zCharSet = 0;
90926   }else if( (zCharSet = sqlite3_value_text(argv[1]))==0 ){
90927     return;
90928   }else{
90929     const unsigned char *z;
90930     for(z=zCharSet, nChar=0; *z; nChar++){
90931       SQLITE_SKIP_UTF8(z);
90932     }
90933     if( nChar>0 ){
90934       azChar = contextMalloc(context, ((i64)nChar)*(sizeof(char*)+1));
90935       if( azChar==0 ){
90936         return;
90937       }
90938       aLen = (unsigned char*)&azChar[nChar];
90939       for(z=zCharSet, nChar=0; *z; nChar++){
90940         azChar[nChar] = (unsigned char *)z;
90941         SQLITE_SKIP_UTF8(z);
90942         aLen[nChar] = (u8)(z - azChar[nChar]);
90943       }
90944     }
90945   }
90946   if( nChar>0 ){
90947     flags = SQLITE_PTR_TO_INT(sqlite3_user_data(context));
90948     if( flags & 1 ){
90949       while( nIn>0 ){
90950         int len = 0;
90951         for(i=0; i<nChar; i++){
90952           len = aLen[i];
90953           if( len<=nIn && memcmp(zIn, azChar[i], len)==0 ) break;
90954         }
90955         if( i>=nChar ) break;
90956         zIn += len;
90957         nIn -= len;
90958       }
90959     }
90960     if( flags & 2 ){
90961       while( nIn>0 ){
90962         int len = 0;
90963         for(i=0; i<nChar; i++){
90964           len = aLen[i];
90965           if( len<=nIn && memcmp(&zIn[nIn-len],azChar[i],len)==0 ) break;
90966         }
90967         if( i>=nChar ) break;
90968         nIn -= len;
90969       }
90970     }
90971     if( zCharSet ){
90972       sqlite3_free(azChar);
90973     }
90974   }
90975   sqlite3_result_text(context, (char*)zIn, nIn, SQLITE_TRANSIENT);
90976 }
90977 
90978 
90979 /* IMP: R-25361-16150 This function is omitted from SQLite by default. It
90980 ** is only available if the SQLITE_SOUNDEX compile-time option is used
90981 ** when SQLite is built.
90982 */
90983 #ifdef SQLITE_SOUNDEX
90984 /*
90985 ** Compute the soundex encoding of a word.
90986 **
90987 ** IMP: R-59782-00072 The soundex(X) function returns a string that is the
90988 ** soundex encoding of the string X. 
90989 */
90990 static void soundexFunc(
90991   sqlite3_context *context,
90992   int argc,
90993   sqlite3_value **argv
90994 ){
90995   char zResult[8];
90996   const u8 *zIn;
90997   int i, j;
90998   static const unsigned char iCode[] = {
90999     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
91000     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
91001     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
91002     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
91003     0, 0, 1, 2, 3, 0, 1, 2, 0, 0, 2, 2, 4, 5, 5, 0,
91004     1, 2, 6, 2, 3, 0, 1, 0, 2, 0, 2, 0, 0, 0, 0, 0,
91005     0, 0, 1, 2, 3, 0, 1, 2, 0, 0, 2, 2, 4, 5, 5, 0,
91006     1, 2, 6, 2, 3, 0, 1, 0, 2, 0, 2, 0, 0, 0, 0, 0,
91007   };
91008   assert( argc==1 );
91009   zIn = (u8*)sqlite3_value_text(argv[0]);
91010   if( zIn==0 ) zIn = (u8*)"";
91011   for(i=0; zIn[i] && !sqlite3Isalpha(zIn[i]); i++){}
91012   if( zIn[i] ){
91013     u8 prevcode = iCode[zIn[i]&0x7f];
91014     zResult[0] = sqlite3Toupper(zIn[i]);
91015     for(j=1; j<4 && zIn[i]; i++){
91016       int code = iCode[zIn[i]&0x7f];
91017       if( code>0 ){
91018         if( code!=prevcode ){
91019           prevcode = code;
91020           zResult[j++] = code + '0';
91021         }
91022       }else{
91023         prevcode = 0;
91024       }
91025     }
91026     while( j<4 ){
91027       zResult[j++] = '0';
91028     }
91029     zResult[j] = 0;
91030     sqlite3_result_text(context, zResult, 4, SQLITE_TRANSIENT);
91031   }else{
91032     /* IMP: R-64894-50321 The string "?000" is returned if the argument
91033     ** is NULL or contains no ASCII alphabetic characters. */
91034     sqlite3_result_text(context, "?000", 4, SQLITE_STATIC);
91035   }
91036 }
91037 #endif /* SQLITE_SOUNDEX */
91038 
91039 #ifndef SQLITE_OMIT_LOAD_EXTENSION
91040 /*
91041 ** A function that loads a shared-library extension then returns NULL.
91042 */
91043 static void loadExt(sqlite3_context *context, int argc, sqlite3_value **argv){
91044   const char *zFile = (const char *)sqlite3_value_text(argv[0]);
91045   const char *zProc;
91046   sqlite3 *db = sqlite3_context_db_handle(context);
91047   char *zErrMsg = 0;
91048 
91049   if( argc==2 ){
91050     zProc = (const char *)sqlite3_value_text(argv[1]);
91051   }else{
91052     zProc = 0;
91053   }
91054   if( zFile && sqlite3_load_extension(db, zFile, zProc, &zErrMsg) ){
91055     sqlite3_result_error(context, zErrMsg, -1);
91056     sqlite3_free(zErrMsg);
91057   }
91058 }
91059 #endif
91060 
91061 
91062 /*
91063 ** An instance of the following structure holds the context of a
91064 ** sum() or avg() aggregate computation.
91065 */
91066 typedef struct SumCtx SumCtx;
91067 struct SumCtx {
91068   double rSum;      /* Floating point sum */
91069   i64 iSum;         /* Integer sum */   
91070   i64 cnt;          /* Number of elements summed */
91071   u8 overflow;      /* True if integer overflow seen */
91072   u8 approx;        /* True if non-integer value was input to the sum */
91073 };
91074 
91075 /*
91076 ** Routines used to compute the sum, average, and total.
91077 **
91078 ** The SUM() function follows the (broken) SQL standard which means
91079 ** that it returns NULL if it sums over no inputs.  TOTAL returns
91080 ** 0.0 in that case.  In addition, TOTAL always returns a float where
91081 ** SUM might return an integer if it never encounters a floating point
91082 ** value.  TOTAL never fails, but SUM might through an exception if
91083 ** it overflows an integer.
91084 */
91085 static void sumStep(sqlite3_context *context, int argc, sqlite3_value **argv){
91086   SumCtx *p;
91087   int type;
91088   assert( argc==1 );
91089   UNUSED_PARAMETER(argc);
91090   p = sqlite3_aggregate_context(context, sizeof(*p));
91091   type = sqlite3_value_numeric_type(argv[0]);
91092   if( p && type!=SQLITE_NULL ){
91093     p->cnt++;
91094     if( type==SQLITE_INTEGER ){
91095       i64 v = sqlite3_value_int64(argv[0]);
91096       p->rSum += v;
91097       if( (p->approx|p->overflow)==0 && sqlite3AddInt64(&p->iSum, v) ){
91098         p->overflow = 1;
91099       }
91100     }else{
91101       p->rSum += sqlite3_value_double(argv[0]);
91102       p->approx = 1;
91103     }
91104   }
91105 }
91106 static void sumFinalize(sqlite3_context *context){
91107   SumCtx *p;
91108   p = sqlite3_aggregate_context(context, 0);
91109   if( p && p->cnt>0 ){
91110     if( p->overflow ){
91111       sqlite3_result_error(context,"integer overflow",-1);
91112     }else if( p->approx ){
91113       sqlite3_result_double(context, p->rSum);
91114     }else{
91115       sqlite3_result_int64(context, p->iSum);
91116     }
91117   }
91118 }
91119 static void avgFinalize(sqlite3_context *context){
91120   SumCtx *p;
91121   p = sqlite3_aggregate_context(context, 0);
91122   if( p && p->cnt>0 ){
91123     sqlite3_result_double(context, p->rSum/(double)p->cnt);
91124   }
91125 }
91126 static void totalFinalize(sqlite3_context *context){
91127   SumCtx *p;
91128   p = sqlite3_aggregate_context(context, 0);
91129   /* (double)0 In case of SQLITE_OMIT_FLOATING_POINT... */
91130   sqlite3_result_double(context, p ? p->rSum : (double)0);
91131 }
91132 
91133 /*
91134 ** The following structure keeps track of state information for the
91135 ** count() aggregate function.
91136 */
91137 typedef struct CountCtx CountCtx;
91138 struct CountCtx {
91139   i64 n;
91140 };
91141 
91142 /*
91143 ** Routines to implement the count() aggregate function.
91144 */
91145 static void countStep(sqlite3_context *context, int argc, sqlite3_value **argv){
91146   CountCtx *p;
91147   p = sqlite3_aggregate_context(context, sizeof(*p));
91148   if( (argc==0 || SQLITE_NULL!=sqlite3_value_type(argv[0])) && p ){
91149     p->n++;
91150   }
91151 
91152 #ifndef SQLITE_OMIT_DEPRECATED
91153   /* The sqlite3_aggregate_count() function is deprecated.  But just to make
91154   ** sure it still operates correctly, verify that its count agrees with our 
91155   ** internal count when using count(*) and when the total count can be
91156   ** expressed as a 32-bit integer. */
91157   assert( argc==1 || p==0 || p->n>0x7fffffff
91158           || p->n==sqlite3_aggregate_count(context) );
91159 #endif
91160 }   
91161 static void countFinalize(sqlite3_context *context){
91162   CountCtx *p;
91163   p = sqlite3_aggregate_context(context, 0);
91164   sqlite3_result_int64(context, p ? p->n : 0);
91165 }
91166 
91167 /*
91168 ** Routines to implement min() and max() aggregate functions.
91169 */
91170 static void minmaxStep(
91171   sqlite3_context *context, 
91172   int NotUsed, 
91173   sqlite3_value **argv
91174 ){
91175   Mem *pArg  = (Mem *)argv[0];
91176   Mem *pBest;
91177   UNUSED_PARAMETER(NotUsed);
91178 
91179   pBest = (Mem *)sqlite3_aggregate_context(context, sizeof(*pBest));
91180   if( !pBest ) return;
91181 
91182   if( sqlite3_value_type(argv[0])==SQLITE_NULL ){
91183     if( pBest->flags ) sqlite3SkipAccumulatorLoad(context);
91184   }else if( pBest->flags ){
91185     int max;
91186     int cmp;
91187     CollSeq *pColl = sqlite3GetFuncCollSeq(context);
91188     /* This step function is used for both the min() and max() aggregates,
91189     ** the only difference between the two being that the sense of the
91190     ** comparison is inverted. For the max() aggregate, the
91191     ** sqlite3_user_data() function returns (void *)-1. For min() it
91192     ** returns (void *)db, where db is the sqlite3* database pointer.
91193     ** Therefore the next statement sets variable 'max' to 1 for the max()
91194     ** aggregate, or 0 for min().
91195     */
91196     max = sqlite3_user_data(context)!=0;
91197     cmp = sqlite3MemCompare(pBest, pArg, pColl);
91198     if( (max && cmp<0) || (!max && cmp>0) ){
91199       sqlite3VdbeMemCopy(pBest, pArg);
91200     }else{
91201       sqlite3SkipAccumulatorLoad(context);
91202     }
91203   }else{
91204     sqlite3VdbeMemCopy(pBest, pArg);
91205   }
91206 }
91207 static void minMaxFinalize(sqlite3_context *context){
91208   sqlite3_value *pRes;
91209   pRes = (sqlite3_value *)sqlite3_aggregate_context(context, 0);
91210   if( pRes ){
91211     if( pRes->flags ){
91212       sqlite3_result_value(context, pRes);
91213     }
91214     sqlite3VdbeMemRelease(pRes);
91215   }
91216 }
91217 
91218 /*
91219 ** group_concat(EXPR, ?SEPARATOR?)
91220 */
91221 static void groupConcatStep(
91222   sqlite3_context *context,
91223   int argc,
91224   sqlite3_value **argv
91225 ){
91226   const char *zVal;
91227   StrAccum *pAccum;
91228   const char *zSep;
91229   int nVal, nSep;
91230   assert( argc==1 || argc==2 );
91231   if( sqlite3_value_type(argv[0])==SQLITE_NULL ) return;
91232   pAccum = (StrAccum*)sqlite3_aggregate_context(context, sizeof(*pAccum));
91233 
91234   if( pAccum ){
91235     sqlite3 *db = sqlite3_context_db_handle(context);
91236     int firstTerm = pAccum->useMalloc==0;
91237     pAccum->useMalloc = 2;
91238     pAccum->mxAlloc = db->aLimit[SQLITE_LIMIT_LENGTH];
91239     if( !firstTerm ){
91240       if( argc==2 ){
91241         zSep = (char*)sqlite3_value_text(argv[1]);
91242         nSep = sqlite3_value_bytes(argv[1]);
91243       }else{
91244         zSep = ",";
91245         nSep = 1;
91246       }
91247       sqlite3StrAccumAppend(pAccum, zSep, nSep);
91248     }
91249     zVal = (char*)sqlite3_value_text(argv[0]);
91250     nVal = sqlite3_value_bytes(argv[0]);
91251     sqlite3StrAccumAppend(pAccum, zVal, nVal);
91252   }
91253 }
91254 static void groupConcatFinalize(sqlite3_context *context){
91255   StrAccum *pAccum;
91256   pAccum = sqlite3_aggregate_context(context, 0);
91257   if( pAccum ){
91258     if( pAccum->accError==STRACCUM_TOOBIG ){
91259       sqlite3_result_error_toobig(context);
91260     }else if( pAccum->accError==STRACCUM_NOMEM ){
91261       sqlite3_result_error_nomem(context);
91262     }else{    
91263       sqlite3_result_text(context, sqlite3StrAccumFinish(pAccum), -1, 
91264                           sqlite3_free);
91265     }
91266   }
91267 }
91268 
91269 /*
91270 ** This routine does per-connection function registration.  Most
91271 ** of the built-in functions above are part of the global function set.
91272 ** This routine only deals with those that are not global.
91273 */
91274 SQLITE_PRIVATE void sqlite3RegisterBuiltinFunctions(sqlite3 *db){
91275   int rc = sqlite3_overload_function(db, "MATCH", 2);
91276   assert( rc==SQLITE_NOMEM || rc==SQLITE_OK );
91277   if( rc==SQLITE_NOMEM ){
91278     db->mallocFailed = 1;
91279   }
91280 }
91281 
91282 /*
91283 ** Set the LIKEOPT flag on the 2-argument function with the given name.
91284 */
91285 static void setLikeOptFlag(sqlite3 *db, const char *zName, u8 flagVal){
91286   FuncDef *pDef;
91287   pDef = sqlite3FindFunction(db, zName, sqlite3Strlen30(zName),
91288                              2, SQLITE_UTF8, 0);
91289   if( ALWAYS(pDef) ){
91290     pDef->funcFlags |= flagVal;
91291   }
91292 }
91293 
91294 /*
91295 ** Register the built-in LIKE and GLOB functions.  The caseSensitive
91296 ** parameter determines whether or not the LIKE operator is case
91297 ** sensitive.  GLOB is always case sensitive.
91298 */
91299 SQLITE_PRIVATE void sqlite3RegisterLikeFunctions(sqlite3 *db, int caseSensitive){
91300   struct compareInfo *pInfo;
91301   if( caseSensitive ){
91302     pInfo = (struct compareInfo*)&likeInfoAlt;
91303   }else{
91304     pInfo = (struct compareInfo*)&likeInfoNorm;
91305   }
91306   sqlite3CreateFunc(db, "like", 2, SQLITE_UTF8, pInfo, likeFunc, 0, 0, 0);
91307   sqlite3CreateFunc(db, "like", 3, SQLITE_UTF8, pInfo, likeFunc, 0, 0, 0);
91308   sqlite3CreateFunc(db, "glob", 2, SQLITE_UTF8, 
91309       (struct compareInfo*)&globInfo, likeFunc, 0, 0, 0);
91310   setLikeOptFlag(db, "glob", SQLITE_FUNC_LIKE | SQLITE_FUNC_CASE);
91311   setLikeOptFlag(db, "like", 
91312       caseSensitive ? (SQLITE_FUNC_LIKE | SQLITE_FUNC_CASE) : SQLITE_FUNC_LIKE);
91313 }
91314 
91315 /*
91316 ** pExpr points to an expression which implements a function.  If
91317 ** it is appropriate to apply the LIKE optimization to that function
91318 ** then set aWc[0] through aWc[2] to the wildcard characters and
91319 ** return TRUE.  If the function is not a LIKE-style function then
91320 ** return FALSE.
91321 */
91322 SQLITE_PRIVATE int sqlite3IsLikeFunction(sqlite3 *db, Expr *pExpr, int *pIsNocase, char *aWc){
91323   FuncDef *pDef;
91324   if( pExpr->op!=TK_FUNCTION 
91325    || !pExpr->x.pList 
91326    || pExpr->x.pList->nExpr!=2
91327   ){
91328     return 0;
91329   }
91330   assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
91331   pDef = sqlite3FindFunction(db, pExpr->u.zToken, 
91332                              sqlite3Strlen30(pExpr->u.zToken),
91333                              2, SQLITE_UTF8, 0);
91334   if( NEVER(pDef==0) || (pDef->funcFlags & SQLITE_FUNC_LIKE)==0 ){
91335     return 0;
91336   }
91337 
91338   /* The memcpy() statement assumes that the wildcard characters are
91339   ** the first three statements in the compareInfo structure.  The
91340   ** asserts() that follow verify that assumption
91341   */
91342   memcpy(aWc, pDef->pUserData, 3);
91343   assert( (char*)&likeInfoAlt == (char*)&likeInfoAlt.matchAll );
91344   assert( &((char*)&likeInfoAlt)[1] == (char*)&likeInfoAlt.matchOne );
91345   assert( &((char*)&likeInfoAlt)[2] == (char*)&likeInfoAlt.matchSet );
91346   *pIsNocase = (pDef->funcFlags & SQLITE_FUNC_CASE)==0;
91347   return 1;
91348 }
91349 
91350 /*
91351 ** All all of the FuncDef structures in the aBuiltinFunc[] array above
91352 ** to the global function hash table.  This occurs at start-time (as
91353 ** a consequence of calling sqlite3_initialize()).
91354 **
91355 ** After this routine runs
91356 */
91357 SQLITE_PRIVATE void sqlite3RegisterGlobalFunctions(void){
91358   /*
91359   ** The following array holds FuncDef structures for all of the functions
91360   ** defined in this file.
91361   **
91362   ** The array cannot be constant since changes are made to the
91363   ** FuncDef.pHash elements at start-time.  The elements of this array
91364   ** are read-only after initialization is complete.
91365   */
91366   static SQLITE_WSD FuncDef aBuiltinFunc[] = {
91367     FUNCTION(ltrim,              1, 1, 0, trimFunc         ),
91368     FUNCTION(ltrim,              2, 1, 0, trimFunc         ),
91369     FUNCTION(rtrim,              1, 2, 0, trimFunc         ),
91370     FUNCTION(rtrim,              2, 2, 0, trimFunc         ),
91371     FUNCTION(trim,               1, 3, 0, trimFunc         ),
91372     FUNCTION(trim,               2, 3, 0, trimFunc         ),
91373     FUNCTION(min,               -1, 0, 1, minmaxFunc       ),
91374     FUNCTION(min,                0, 0, 1, 0                ),
91375     AGGREGATE(min,               1, 0, 1, minmaxStep,      minMaxFinalize ),
91376     FUNCTION(max,               -1, 1, 1, minmaxFunc       ),
91377     FUNCTION(max,                0, 1, 1, 0                ),
91378     AGGREGATE(max,               1, 1, 1, minmaxStep,      minMaxFinalize ),
91379     FUNCTION2(typeof,            1, 0, 0, typeofFunc,  SQLITE_FUNC_TYPEOF),
91380     FUNCTION2(length,            1, 0, 0, lengthFunc,  SQLITE_FUNC_LENGTH),
91381     FUNCTION(instr,              2, 0, 0, instrFunc        ),
91382     FUNCTION(substr,             2, 0, 0, substrFunc       ),
91383     FUNCTION(substr,             3, 0, 0, substrFunc       ),
91384     FUNCTION(unicode,            1, 0, 0, unicodeFunc      ),
91385     FUNCTION(char,              -1, 0, 0, charFunc         ),
91386     FUNCTION(abs,                1, 0, 0, absFunc          ),
91387 #ifndef SQLITE_OMIT_FLOATING_POINT
91388     FUNCTION(round,              1, 0, 0, roundFunc        ),
91389     FUNCTION(round,              2, 0, 0, roundFunc        ),
91390 #endif
91391     FUNCTION(upper,              1, 0, 0, upperFunc        ),
91392     FUNCTION(lower,              1, 0, 0, lowerFunc        ),
91393     FUNCTION(coalesce,           1, 0, 0, 0                ),
91394     FUNCTION(coalesce,           0, 0, 0, 0                ),
91395     FUNCTION2(coalesce,         -1, 0, 0, noopFunc,  SQLITE_FUNC_COALESCE),
91396     FUNCTION(hex,                1, 0, 0, hexFunc          ),
91397     FUNCTION2(ifnull,            2, 0, 0, noopFunc,  SQLITE_FUNC_COALESCE),
91398     FUNCTION2(unlikely,          1, 0, 0, noopFunc,  SQLITE_FUNC_UNLIKELY),
91399     FUNCTION2(likelihood,        2, 0, 0, noopFunc,  SQLITE_FUNC_UNLIKELY),
91400     VFUNCTION(random,            0, 0, 0, randomFunc       ),
91401     VFUNCTION(randomblob,        1, 0, 0, randomBlob       ),
91402     FUNCTION(nullif,             2, 0, 1, nullifFunc       ),
91403     FUNCTION(sqlite_version,     0, 0, 0, versionFunc      ),
91404     FUNCTION(sqlite_source_id,   0, 0, 0, sourceidFunc     ),
91405     FUNCTION(sqlite_log,         2, 0, 0, errlogFunc       ),
91406 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
91407     FUNCTION(sqlite_compileoption_used,1, 0, 0, compileoptionusedFunc  ),
91408     FUNCTION(sqlite_compileoption_get, 1, 0, 0, compileoptiongetFunc  ),
91409 #endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
91410     FUNCTION(quote,              1, 0, 0, quoteFunc        ),
91411     VFUNCTION(last_insert_rowid, 0, 0, 0, last_insert_rowid),
91412     VFUNCTION(changes,           0, 0, 0, changes          ),
91413     VFUNCTION(total_changes,     0, 0, 0, total_changes    ),
91414     FUNCTION(replace,            3, 0, 0, replaceFunc      ),
91415     FUNCTION(zeroblob,           1, 0, 0, zeroblobFunc     ),
91416   #ifdef SQLITE_SOUNDEX
91417     FUNCTION(soundex,            1, 0, 0, soundexFunc      ),
91418   #endif
91419   #ifndef SQLITE_OMIT_LOAD_EXTENSION
91420     FUNCTION(load_extension,     1, 0, 0, loadExt          ),
91421     FUNCTION(load_extension,     2, 0, 0, loadExt          ),
91422   #endif
91423     AGGREGATE(sum,               1, 0, 0, sumStep,         sumFinalize    ),
91424     AGGREGATE(total,             1, 0, 0, sumStep,         totalFinalize    ),
91425     AGGREGATE(avg,               1, 0, 0, sumStep,         avgFinalize    ),
91426  /* AGGREGATE(count,             0, 0, 0, countStep,       countFinalize  ), */
91427     {0,SQLITE_UTF8|SQLITE_FUNC_COUNT,0,0,0,countStep,countFinalize,"count",0,0},
91428     AGGREGATE(count,             1, 0, 0, countStep,       countFinalize  ),
91429     AGGREGATE(group_concat,      1, 0, 0, groupConcatStep, groupConcatFinalize),
91430     AGGREGATE(group_concat,      2, 0, 0, groupConcatStep, groupConcatFinalize),
91431   
91432     LIKEFUNC(glob, 2, &globInfo, SQLITE_FUNC_LIKE|SQLITE_FUNC_CASE),
91433   #ifdef SQLITE_CASE_SENSITIVE_LIKE
91434     LIKEFUNC(like, 2, &likeInfoAlt, SQLITE_FUNC_LIKE|SQLITE_FUNC_CASE),
91435     LIKEFUNC(like, 3, &likeInfoAlt, SQLITE_FUNC_LIKE|SQLITE_FUNC_CASE),
91436   #else
91437     LIKEFUNC(like, 2, &likeInfoNorm, SQLITE_FUNC_LIKE),
91438     LIKEFUNC(like, 3, &likeInfoNorm, SQLITE_FUNC_LIKE),
91439   #endif
91440   };
91441 
91442   int i;
91443   FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
91444   FuncDef *aFunc = (FuncDef*)&GLOBAL(FuncDef, aBuiltinFunc);
91445 
91446   for(i=0; i<ArraySize(aBuiltinFunc); i++){
91447     sqlite3FuncDefInsert(pHash, &aFunc[i]);
91448   }
91449   sqlite3RegisterDateTimeFunctions();
91450 #ifndef SQLITE_OMIT_ALTERTABLE
91451   sqlite3AlterFunctions();
91452 #endif
91453 #if defined(SQLITE_ENABLE_STAT3) || defined(SQLITE_ENABLE_STAT4)
91454   sqlite3AnalyzeFunctions();
91455 #endif
91456 }
91457 
91458 /************** End of func.c ************************************************/
91459 /************** Begin file fkey.c ********************************************/
91460 /*
91461 **
91462 ** The author disclaims copyright to this source code.  In place of
91463 ** a legal notice, here is a blessing:
91464 **
91465 **    May you do good and not evil.
91466 **    May you find forgiveness for yourself and forgive others.
91467 **    May you share freely, never taking more than you give.
91468 **
91469 *************************************************************************
91470 ** This file contains code used by the compiler to add foreign key
91471 ** support to compiled SQL statements.
91472 */
91473 
91474 #ifndef SQLITE_OMIT_FOREIGN_KEY
91475 #ifndef SQLITE_OMIT_TRIGGER
91476 
91477 /*
91478 ** Deferred and Immediate FKs
91479 ** --------------------------
91480 **
91481 ** Foreign keys in SQLite come in two flavours: deferred and immediate.
91482 ** If an immediate foreign key constraint is violated,
91483 ** SQLITE_CONSTRAINT_FOREIGNKEY is returned and the current
91484 ** statement transaction rolled back. If a 
91485 ** deferred foreign key constraint is violated, no action is taken 
91486 ** immediately. However if the application attempts to commit the 
91487 ** transaction before fixing the constraint violation, the attempt fails.
91488 **
91489 ** Deferred constraints are implemented using a simple counter associated
91490 ** with the database handle. The counter is set to zero each time a 
91491 ** database transaction is opened. Each time a statement is executed 
91492 ** that causes a foreign key violation, the counter is incremented. Each
91493 ** time a statement is executed that removes an existing violation from
91494 ** the database, the counter is decremented. When the transaction is
91495 ** committed, the commit fails if the current value of the counter is
91496 ** greater than zero. This scheme has two big drawbacks:
91497 **
91498 **   * When a commit fails due to a deferred foreign key constraint, 
91499 **     there is no way to tell which foreign constraint is not satisfied,
91500 **     or which row it is not satisfied for.
91501 **
91502 **   * If the database contains foreign key violations when the 
91503 **     transaction is opened, this may cause the mechanism to malfunction.
91504 **
91505 ** Despite these problems, this approach is adopted as it seems simpler
91506 ** than the alternatives.
91507 **
91508 ** INSERT operations:
91509 **
91510 **   I.1) For each FK for which the table is the child table, search
91511 **        the parent table for a match. If none is found increment the
91512 **        constraint counter.
91513 **
91514 **   I.2) For each FK for which the table is the parent table, 
91515 **        search the child table for rows that correspond to the new
91516 **        row in the parent table. Decrement the counter for each row
91517 **        found (as the constraint is now satisfied).
91518 **
91519 ** DELETE operations:
91520 **
91521 **   D.1) For each FK for which the table is the child table, 
91522 **        search the parent table for a row that corresponds to the 
91523 **        deleted row in the child table. If such a row is not found, 
91524 **        decrement the counter.
91525 **
91526 **   D.2) For each FK for which the table is the parent table, search 
91527 **        the child table for rows that correspond to the deleted row 
91528 **        in the parent table. For each found increment the counter.
91529 **
91530 ** UPDATE operations:
91531 **
91532 **   An UPDATE command requires that all 4 steps above are taken, but only
91533 **   for FK constraints for which the affected columns are actually 
91534 **   modified (values must be compared at runtime).
91535 **
91536 ** Note that I.1 and D.1 are very similar operations, as are I.2 and D.2.
91537 ** This simplifies the implementation a bit.
91538 **
91539 ** For the purposes of immediate FK constraints, the OR REPLACE conflict
91540 ** resolution is considered to delete rows before the new row is inserted.
91541 ** If a delete caused by OR REPLACE violates an FK constraint, an exception
91542 ** is thrown, even if the FK constraint would be satisfied after the new 
91543 ** row is inserted.
91544 **
91545 ** Immediate constraints are usually handled similarly. The only difference 
91546 ** is that the counter used is stored as part of each individual statement
91547 ** object (struct Vdbe). If, after the statement has run, its immediate
91548 ** constraint counter is greater than zero,
91549 ** it returns SQLITE_CONSTRAINT_FOREIGNKEY
91550 ** and the statement transaction is rolled back. An exception is an INSERT
91551 ** statement that inserts a single row only (no triggers). In this case,
91552 ** instead of using a counter, an exception is thrown immediately if the
91553 ** INSERT violates a foreign key constraint. This is necessary as such
91554 ** an INSERT does not open a statement transaction.
91555 **
91556 ** TODO: How should dropping a table be handled? How should renaming a 
91557 ** table be handled?
91558 **
91559 **
91560 ** Query API Notes
91561 ** ---------------
91562 **
91563 ** Before coding an UPDATE or DELETE row operation, the code-generator
91564 ** for those two operations needs to know whether or not the operation
91565 ** requires any FK processing and, if so, which columns of the original
91566 ** row are required by the FK processing VDBE code (i.e. if FKs were
91567 ** implemented using triggers, which of the old.* columns would be 
91568 ** accessed). No information is required by the code-generator before
91569 ** coding an INSERT operation. The functions used by the UPDATE/DELETE
91570 ** generation code to query for this information are:
91571 **
91572 **   sqlite3FkRequired() - Test to see if FK processing is required.
91573 **   sqlite3FkOldmask()  - Query for the set of required old.* columns.
91574 **
91575 **
91576 ** Externally accessible module functions
91577 ** --------------------------------------
91578 **
91579 **   sqlite3FkCheck()    - Check for foreign key violations.
91580 **   sqlite3FkActions()  - Code triggers for ON UPDATE/ON DELETE actions.
91581 **   sqlite3FkDelete()   - Delete an FKey structure.
91582 */
91583 
91584 /*
91585 ** VDBE Calling Convention
91586 ** -----------------------
91587 **
91588 ** Example:
91589 **
91590 **   For the following INSERT statement:
91591 **
91592 **     CREATE TABLE t1(a, b INTEGER PRIMARY KEY, c);
91593 **     INSERT INTO t1 VALUES(1, 2, 3.1);
91594 **
91595 **   Register (x):        2    (type integer)
91596 **   Register (x+1):      1    (type integer)
91597 **   Register (x+2):      NULL (type NULL)
91598 **   Register (x+3):      3.1  (type real)
91599 */
91600 
91601 /*
91602 ** A foreign key constraint requires that the key columns in the parent
91603 ** table are collectively subject to a UNIQUE or PRIMARY KEY constraint.
91604 ** Given that pParent is the parent table for foreign key constraint pFKey, 
91605 ** search the schema for a unique index on the parent key columns. 
91606 **
91607 ** If successful, zero is returned. If the parent key is an INTEGER PRIMARY 
91608 ** KEY column, then output variable *ppIdx is set to NULL. Otherwise, *ppIdx 
91609 ** is set to point to the unique index. 
91610 ** 
91611 ** If the parent key consists of a single column (the foreign key constraint
91612 ** is not a composite foreign key), output variable *paiCol is set to NULL.
91613 ** Otherwise, it is set to point to an allocated array of size N, where
91614 ** N is the number of columns in the parent key. The first element of the
91615 ** array is the index of the child table column that is mapped by the FK
91616 ** constraint to the parent table column stored in the left-most column
91617 ** of index *ppIdx. The second element of the array is the index of the
91618 ** child table column that corresponds to the second left-most column of
91619 ** *ppIdx, and so on.
91620 **
91621 ** If the required index cannot be found, either because:
91622 **
91623 **   1) The named parent key columns do not exist, or
91624 **
91625 **   2) The named parent key columns do exist, but are not subject to a
91626 **      UNIQUE or PRIMARY KEY constraint, or
91627 **
91628 **   3) No parent key columns were provided explicitly as part of the
91629 **      foreign key definition, and the parent table does not have a
91630 **      PRIMARY KEY, or
91631 **
91632 **   4) No parent key columns were provided explicitly as part of the
91633 **      foreign key definition, and the PRIMARY KEY of the parent table 
91634 **      consists of a a different number of columns to the child key in 
91635 **      the child table.
91636 **
91637 ** then non-zero is returned, and a "foreign key mismatch" error loaded
91638 ** into pParse. If an OOM error occurs, non-zero is returned and the
91639 ** pParse->db->mallocFailed flag is set.
91640 */
91641 SQLITE_PRIVATE int sqlite3FkLocateIndex(
91642   Parse *pParse,                  /* Parse context to store any error in */
91643   Table *pParent,                 /* Parent table of FK constraint pFKey */
91644   FKey *pFKey,                    /* Foreign key to find index for */
91645   Index **ppIdx,                  /* OUT: Unique index on parent table */
91646   int **paiCol                    /* OUT: Map of index columns in pFKey */
91647 ){
91648   Index *pIdx = 0;                    /* Value to return via *ppIdx */
91649   int *aiCol = 0;                     /* Value to return via *paiCol */
91650   int nCol = pFKey->nCol;             /* Number of columns in parent key */
91651   char *zKey = pFKey->aCol[0].zCol;   /* Name of left-most parent key column */
91652 
91653   /* The caller is responsible for zeroing output parameters. */
91654   assert( ppIdx && *ppIdx==0 );
91655   assert( !paiCol || *paiCol==0 );
91656   assert( pParse );
91657 
91658   /* If this is a non-composite (single column) foreign key, check if it 
91659   ** maps to the INTEGER PRIMARY KEY of table pParent. If so, leave *ppIdx 
91660   ** and *paiCol set to zero and return early. 
91661   **
91662   ** Otherwise, for a composite foreign key (more than one column), allocate
91663   ** space for the aiCol array (returned via output parameter *paiCol).
91664   ** Non-composite foreign keys do not require the aiCol array.
91665   */
91666   if( nCol==1 ){
91667     /* The FK maps to the IPK if any of the following are true:
91668     **
91669     **   1) There is an INTEGER PRIMARY KEY column and the FK is implicitly 
91670     **      mapped to the primary key of table pParent, or
91671     **   2) The FK is explicitly mapped to a column declared as INTEGER
91672     **      PRIMARY KEY.
91673     */
91674     if( pParent->iPKey>=0 ){
91675       if( !zKey ) return 0;
91676       if( !sqlite3StrICmp(pParent->aCol[pParent->iPKey].zName, zKey) ) return 0;
91677     }
91678   }else if( paiCol ){
91679     assert( nCol>1 );
91680     aiCol = (int *)sqlite3DbMallocRaw(pParse->db, nCol*sizeof(int));
91681     if( !aiCol ) return 1;
91682     *paiCol = aiCol;
91683   }
91684 
91685   for(pIdx=pParent->pIndex; pIdx; pIdx=pIdx->pNext){
91686     if( pIdx->nKeyCol==nCol && pIdx->onError!=OE_None ){ 
91687       /* pIdx is a UNIQUE index (or a PRIMARY KEY) and has the right number
91688       ** of columns. If each indexed column corresponds to a foreign key
91689       ** column of pFKey, then this index is a winner.  */
91690 
91691       if( zKey==0 ){
91692         /* If zKey is NULL, then this foreign key is implicitly mapped to 
91693         ** the PRIMARY KEY of table pParent. The PRIMARY KEY index may be 
91694         ** identified by the test (Index.autoIndex==2).  */
91695         if( pIdx->autoIndex==2 ){
91696           if( aiCol ){
91697             int i;
91698             for(i=0; i<nCol; i++) aiCol[i] = pFKey->aCol[i].iFrom;
91699           }
91700           break;
91701         }
91702       }else{
91703         /* If zKey is non-NULL, then this foreign key was declared to
91704         ** map to an explicit list of columns in table pParent. Check if this
91705         ** index matches those columns. Also, check that the index uses
91706         ** the default collation sequences for each column. */
91707         int i, j;
91708         for(i=0; i<nCol; i++){
91709           i16 iCol = pIdx->aiColumn[i];     /* Index of column in parent tbl */
91710           char *zDfltColl;                  /* Def. collation for column */
91711           char *zIdxCol;                    /* Name of indexed column */
91712 
91713           /* If the index uses a collation sequence that is different from
91714           ** the default collation sequence for the column, this index is
91715           ** unusable. Bail out early in this case.  */
91716           zDfltColl = pParent->aCol[iCol].zColl;
91717           if( !zDfltColl ){
91718             zDfltColl = "BINARY";
91719           }
91720           if( sqlite3StrICmp(pIdx->azColl[i], zDfltColl) ) break;
91721 
91722           zIdxCol = pParent->aCol[iCol].zName;
91723           for(j=0; j<nCol; j++){
91724             if( sqlite3StrICmp(pFKey->aCol[j].zCol, zIdxCol)==0 ){
91725               if( aiCol ) aiCol[i] = pFKey->aCol[j].iFrom;
91726               break;
91727             }
91728           }
91729           if( j==nCol ) break;
91730         }
91731         if( i==nCol ) break;      /* pIdx is usable */
91732       }
91733     }
91734   }
91735 
91736   if( !pIdx ){
91737     if( !pParse->disableTriggers ){
91738       sqlite3ErrorMsg(pParse,
91739            "foreign key mismatch - \"%w\" referencing \"%w\"",
91740            pFKey->pFrom->zName, pFKey->zTo);
91741     }
91742     sqlite3DbFree(pParse->db, aiCol);
91743     return 1;
91744   }
91745 
91746   *ppIdx = pIdx;
91747   return 0;
91748 }
91749 
91750 /*
91751 ** This function is called when a row is inserted into or deleted from the 
91752 ** child table of foreign key constraint pFKey. If an SQL UPDATE is executed 
91753 ** on the child table of pFKey, this function is invoked twice for each row
91754 ** affected - once to "delete" the old row, and then again to "insert" the
91755 ** new row.
91756 **
91757 ** Each time it is called, this function generates VDBE code to locate the
91758 ** row in the parent table that corresponds to the row being inserted into 
91759 ** or deleted from the child table. If the parent row can be found, no 
91760 ** special action is taken. Otherwise, if the parent row can *not* be
91761 ** found in the parent table:
91762 **
91763 **   Operation | FK type   | Action taken
91764 **   --------------------------------------------------------------------------
91765 **   INSERT      immediate   Increment the "immediate constraint counter".
91766 **
91767 **   DELETE      immediate   Decrement the "immediate constraint counter".
91768 **
91769 **   INSERT      deferred    Increment the "deferred constraint counter".
91770 **
91771 **   DELETE      deferred    Decrement the "deferred constraint counter".
91772 **
91773 ** These operations are identified in the comment at the top of this file 
91774 ** (fkey.c) as "I.1" and "D.1".
91775 */
91776 static void fkLookupParent(
91777   Parse *pParse,        /* Parse context */
91778   int iDb,              /* Index of database housing pTab */
91779   Table *pTab,          /* Parent table of FK pFKey */
91780   Index *pIdx,          /* Unique index on parent key columns in pTab */
91781   FKey *pFKey,          /* Foreign key constraint */
91782   int *aiCol,           /* Map from parent key columns to child table columns */
91783   int regData,          /* Address of array containing child table row */
91784   int nIncr,            /* Increment constraint counter by this */
91785   int isIgnore          /* If true, pretend pTab contains all NULL values */
91786 ){
91787   int i;                                    /* Iterator variable */
91788   Vdbe *v = sqlite3GetVdbe(pParse);         /* Vdbe to add code to */
91789   int iCur = pParse->nTab - 1;              /* Cursor number to use */
91790   int iOk = sqlite3VdbeMakeLabel(v);        /* jump here if parent key found */
91791 
91792   /* If nIncr is less than zero, then check at runtime if there are any
91793   ** outstanding constraints to resolve. If there are not, there is no need
91794   ** to check if deleting this row resolves any outstanding violations.
91795   **
91796   ** Check if any of the key columns in the child table row are NULL. If 
91797   ** any are, then the constraint is considered satisfied. No need to 
91798   ** search for a matching row in the parent table.  */
91799   if( nIncr<0 ){
91800     sqlite3VdbeAddOp2(v, OP_FkIfZero, pFKey->isDeferred, iOk);
91801   }
91802   for(i=0; i<pFKey->nCol; i++){
91803     int iReg = aiCol[i] + regData + 1;
91804     sqlite3VdbeAddOp2(v, OP_IsNull, iReg, iOk);
91805   }
91806 
91807   if( isIgnore==0 ){
91808     if( pIdx==0 ){
91809       /* If pIdx is NULL, then the parent key is the INTEGER PRIMARY KEY
91810       ** column of the parent table (table pTab).  */
91811       int iMustBeInt;               /* Address of MustBeInt instruction */
91812       int regTemp = sqlite3GetTempReg(pParse);
91813   
91814       /* Invoke MustBeInt to coerce the child key value to an integer (i.e. 
91815       ** apply the affinity of the parent key). If this fails, then there
91816       ** is no matching parent key. Before using MustBeInt, make a copy of
91817       ** the value. Otherwise, the value inserted into the child key column
91818       ** will have INTEGER affinity applied to it, which may not be correct.  */
91819       sqlite3VdbeAddOp2(v, OP_SCopy, aiCol[0]+1+regData, regTemp);
91820       iMustBeInt = sqlite3VdbeAddOp2(v, OP_MustBeInt, regTemp, 0);
91821   
91822       /* If the parent table is the same as the child table, and we are about
91823       ** to increment the constraint-counter (i.e. this is an INSERT operation),
91824       ** then check if the row being inserted matches itself. If so, do not
91825       ** increment the constraint-counter.  */
91826       if( pTab==pFKey->pFrom && nIncr==1 ){
91827         sqlite3VdbeAddOp3(v, OP_Eq, regData, iOk, regTemp);
91828       }
91829   
91830       sqlite3OpenTable(pParse, iCur, iDb, pTab, OP_OpenRead);
91831       sqlite3VdbeAddOp3(v, OP_NotExists, iCur, 0, regTemp);
91832       sqlite3VdbeAddOp2(v, OP_Goto, 0, iOk);
91833       sqlite3VdbeJumpHere(v, sqlite3VdbeCurrentAddr(v)-2);
91834       sqlite3VdbeJumpHere(v, iMustBeInt);
91835       sqlite3ReleaseTempReg(pParse, regTemp);
91836     }else{
91837       int nCol = pFKey->nCol;
91838       int regTemp = sqlite3GetTempRange(pParse, nCol);
91839       int regRec = sqlite3GetTempReg(pParse);
91840   
91841       sqlite3VdbeAddOp3(v, OP_OpenRead, iCur, pIdx->tnum, iDb);
91842       sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
91843       for(i=0; i<nCol; i++){
91844         sqlite3VdbeAddOp2(v, OP_Copy, aiCol[i]+1+regData, regTemp+i);
91845       }
91846   
91847       /* If the parent table is the same as the child table, and we are about
91848       ** to increment the constraint-counter (i.e. this is an INSERT operation),
91849       ** then check if the row being inserted matches itself. If so, do not
91850       ** increment the constraint-counter. 
91851       **
91852       ** If any of the parent-key values are NULL, then the row cannot match 
91853       ** itself. So set JUMPIFNULL to make sure we do the OP_Found if any
91854       ** of the parent-key values are NULL (at this point it is known that
91855       ** none of the child key values are).
91856       */
91857       if( pTab==pFKey->pFrom && nIncr==1 ){
91858         int iJump = sqlite3VdbeCurrentAddr(v) + nCol + 1;
91859         for(i=0; i<nCol; i++){
91860           int iChild = aiCol[i]+1+regData;
91861           int iParent = pIdx->aiColumn[i]+1+regData;
91862           assert( aiCol[i]!=pTab->iPKey );
91863           if( pIdx->aiColumn[i]==pTab->iPKey ){
91864             /* The parent key is a composite key that includes the IPK column */
91865             iParent = regData;
91866           }
91867           sqlite3VdbeAddOp3(v, OP_Ne, iChild, iJump, iParent);
91868           sqlite3VdbeChangeP5(v, SQLITE_JUMPIFNULL);
91869         }
91870         sqlite3VdbeAddOp2(v, OP_Goto, 0, iOk);
91871       }
91872   
91873       sqlite3VdbeAddOp3(v, OP_MakeRecord, regTemp, nCol, regRec);
91874       sqlite3VdbeChangeP4(v, -1, sqlite3IndexAffinityStr(v,pIdx), P4_TRANSIENT);
91875       sqlite3VdbeAddOp4Int(v, OP_Found, iCur, iOk, regRec, 0);
91876   
91877       sqlite3ReleaseTempReg(pParse, regRec);
91878       sqlite3ReleaseTempRange(pParse, regTemp, nCol);
91879     }
91880   }
91881 
91882   if( !pFKey->isDeferred && !(pParse->db->flags & SQLITE_DeferFKs)
91883    && !pParse->pToplevel 
91884    && !pParse->isMultiWrite 
91885   ){
91886     /* Special case: If this is an INSERT statement that will insert exactly
91887     ** one row into the table, raise a constraint immediately instead of
91888     ** incrementing a counter. This is necessary as the VM code is being
91889     ** generated for will not open a statement transaction.  */
91890     assert( nIncr==1 );
91891     sqlite3HaltConstraint(pParse, SQLITE_CONSTRAINT_FOREIGNKEY,
91892         OE_Abort, 0, P4_STATIC, P5_ConstraintFK);
91893   }else{
91894     if( nIncr>0 && pFKey->isDeferred==0 ){
91895       sqlite3ParseToplevel(pParse)->mayAbort = 1;
91896     }
91897     sqlite3VdbeAddOp2(v, OP_FkCounter, pFKey->isDeferred, nIncr);
91898   }
91899 
91900   sqlite3VdbeResolveLabel(v, iOk);
91901   sqlite3VdbeAddOp1(v, OP_Close, iCur);
91902 }
91903 
91904 
91905 /*
91906 ** Return an Expr object that refers to a memory register corresponding
91907 ** to column iCol of table pTab.
91908 **
91909 ** regBase is the first of an array of register that contains the data
91910 ** for pTab.  regBase itself holds the rowid.  regBase+1 holds the first
91911 ** column.  regBase+2 holds the second column, and so forth.
91912 */
91913 static Expr *exprTableRegister(
91914   Parse *pParse,     /* Parsing and code generating context */
91915   Table *pTab,       /* The table whose content is at r[regBase]... */
91916   int regBase,       /* Contents of table pTab */
91917   i16 iCol           /* Which column of pTab is desired */
91918 ){
91919   Expr *pExpr;
91920   Column *pCol;
91921   const char *zColl;
91922   sqlite3 *db = pParse->db;
91923 
91924   pExpr = sqlite3Expr(db, TK_REGISTER, 0);
91925   if( pExpr ){
91926     if( iCol>=0 && iCol!=pTab->iPKey ){
91927       pCol = &pTab->aCol[iCol];
91928       pExpr->iTable = regBase + iCol + 1;
91929       pExpr->affinity = pCol->affinity;
91930       zColl = pCol->zColl;
91931       if( zColl==0 ) zColl = db->pDfltColl->zName;
91932       pExpr = sqlite3ExprAddCollateString(pParse, pExpr, zColl);
91933     }else{
91934       pExpr->iTable = regBase;
91935       pExpr->affinity = SQLITE_AFF_INTEGER;
91936     }
91937   }
91938   return pExpr;
91939 }
91940 
91941 /*
91942 ** Return an Expr object that refers to column iCol of table pTab which
91943 ** has cursor iCur.
91944 */
91945 static Expr *exprTableColumn(
91946   sqlite3 *db,      /* The database connection */
91947   Table *pTab,      /* The table whose column is desired */
91948   int iCursor,      /* The open cursor on the table */
91949   i16 iCol          /* The column that is wanted */
91950 ){
91951   Expr *pExpr = sqlite3Expr(db, TK_COLUMN, 0);
91952   if( pExpr ){
91953     pExpr->pTab = pTab;
91954     pExpr->iTable = iCursor;
91955     pExpr->iColumn = iCol;
91956   }
91957   return pExpr;
91958 }
91959 
91960 /*
91961 ** This function is called to generate code executed when a row is deleted
91962 ** from the parent table of foreign key constraint pFKey and, if pFKey is 
91963 ** deferred, when a row is inserted into the same table. When generating
91964 ** code for an SQL UPDATE operation, this function may be called twice -
91965 ** once to "delete" the old row and once to "insert" the new row.
91966 **
91967 ** The code generated by this function scans through the rows in the child
91968 ** table that correspond to the parent table row being deleted or inserted.
91969 ** For each child row found, one of the following actions is taken:
91970 **
91971 **   Operation | FK type   | Action taken
91972 **   --------------------------------------------------------------------------
91973 **   DELETE      immediate   Increment the "immediate constraint counter".
91974 **                           Or, if the ON (UPDATE|DELETE) action is RESTRICT,
91975 **                           throw a "FOREIGN KEY constraint failed" exception.
91976 **
91977 **   INSERT      immediate   Decrement the "immediate constraint counter".
91978 **
91979 **   DELETE      deferred    Increment the "deferred constraint counter".
91980 **                           Or, if the ON (UPDATE|DELETE) action is RESTRICT,
91981 **                           throw a "FOREIGN KEY constraint failed" exception.
91982 **
91983 **   INSERT      deferred    Decrement the "deferred constraint counter".
91984 **
91985 ** These operations are identified in the comment at the top of this file 
91986 ** (fkey.c) as "I.2" and "D.2".
91987 */
91988 static void fkScanChildren(
91989   Parse *pParse,                  /* Parse context */
91990   SrcList *pSrc,                  /* The child table to be scanned */
91991   Table *pTab,                    /* The parent table */
91992   Index *pIdx,                    /* Index on parent covering the foreign key */
91993   FKey *pFKey,                    /* The foreign key linking pSrc to pTab */
91994   int *aiCol,                     /* Map from pIdx cols to child table cols */
91995   int regData,                    /* Parent row data starts here */
91996   int nIncr                       /* Amount to increment deferred counter by */
91997 ){
91998   sqlite3 *db = pParse->db;       /* Database handle */
91999   int i;                          /* Iterator variable */
92000   Expr *pWhere = 0;               /* WHERE clause to scan with */
92001   NameContext sNameContext;       /* Context used to resolve WHERE clause */
92002   WhereInfo *pWInfo;              /* Context used by sqlite3WhereXXX() */
92003   int iFkIfZero = 0;              /* Address of OP_FkIfZero */
92004   Vdbe *v = sqlite3GetVdbe(pParse);
92005 
92006   assert( pIdx==0 || pIdx->pTable==pTab );
92007   assert( pIdx==0 || pIdx->nKeyCol==pFKey->nCol );
92008   assert( pIdx!=0 || pFKey->nCol==1 );
92009   assert( pIdx!=0 || HasRowid(pTab) );
92010 
92011   if( nIncr<0 ){
92012     iFkIfZero = sqlite3VdbeAddOp2(v, OP_FkIfZero, pFKey->isDeferred, 0);
92013   }
92014 
92015   /* Create an Expr object representing an SQL expression like:
92016   **
92017   **   <parent-key1> = <child-key1> AND <parent-key2> = <child-key2> ...
92018   **
92019   ** The collation sequence used for the comparison should be that of
92020   ** the parent key columns. The affinity of the parent key column should
92021   ** be applied to each child key value before the comparison takes place.
92022   */
92023   for(i=0; i<pFKey->nCol; i++){
92024     Expr *pLeft;                  /* Value from parent table row */
92025     Expr *pRight;                 /* Column ref to child table */
92026     Expr *pEq;                    /* Expression (pLeft = pRight) */
92027     i16 iCol;                     /* Index of column in child table */ 
92028     const char *zCol;             /* Name of column in child table */
92029 
92030     iCol = pIdx ? pIdx->aiColumn[i] : -1;
92031     pLeft = exprTableRegister(pParse, pTab, regData, iCol);
92032     iCol = aiCol ? aiCol[i] : pFKey->aCol[0].iFrom;
92033     assert( iCol>=0 );
92034     zCol = pFKey->pFrom->aCol[iCol].zName;
92035     pRight = sqlite3Expr(db, TK_ID, zCol);
92036     pEq = sqlite3PExpr(pParse, TK_EQ, pLeft, pRight, 0);
92037     pWhere = sqlite3ExprAnd(db, pWhere, pEq);
92038   }
92039 
92040   /* If the child table is the same as the parent table, then add terms
92041   ** to the WHERE clause that prevent this entry from being scanned.
92042   ** The added WHERE clause terms are like this:
92043   **
92044   **     $current_rowid!=rowid
92045   **     NOT( $current_a==a AND $current_b==b AND ... )
92046   **
92047   ** The first form is used for rowid tables.  The second form is used
92048   ** for WITHOUT ROWID tables.  In the second form, the primary key is
92049   ** (a,b,...)
92050   */
92051   if( pTab==pFKey->pFrom && nIncr>0 ){
92052     Expr *pNe;                    /* Expression (pLeft != pRight) */
92053     Expr *pLeft;                  /* Value from parent table row */
92054     Expr *pRight;                 /* Column ref to child table */
92055     if( HasRowid(pTab) ){
92056       pLeft = exprTableRegister(pParse, pTab, regData, -1);
92057       pRight = exprTableColumn(db, pTab, pSrc->a[0].iCursor, -1);
92058       pNe = sqlite3PExpr(pParse, TK_NE, pLeft, pRight, 0);
92059     }else{
92060       Expr *pEq, *pAll = 0;
92061       Index *pPk = sqlite3PrimaryKeyIndex(pTab);
92062       assert( pIdx!=0 );
92063       for(i=0; i<pPk->nKeyCol; i++){
92064         i16 iCol = pIdx->aiColumn[i];
92065         pLeft = exprTableRegister(pParse, pTab, regData, iCol);
92066         pRight = exprTableColumn(db, pTab, pSrc->a[0].iCursor, iCol);
92067         pEq = sqlite3PExpr(pParse, TK_EQ, pLeft, pRight, 0);
92068         pAll = sqlite3ExprAnd(db, pAll, pEq);
92069       }
92070       pNe = sqlite3PExpr(pParse, TK_NOT, pAll, 0, 0);
92071     }
92072     pWhere = sqlite3ExprAnd(db, pWhere, pNe);
92073   }
92074 
92075   /* Resolve the references in the WHERE clause. */
92076   memset(&sNameContext, 0, sizeof(NameContext));
92077   sNameContext.pSrcList = pSrc;
92078   sNameContext.pParse = pParse;
92079   sqlite3ResolveExprNames(&sNameContext, pWhere);
92080 
92081   /* Create VDBE to loop through the entries in pSrc that match the WHERE
92082   ** clause. If the constraint is not deferred, throw an exception for
92083   ** each row found. Otherwise, for deferred constraints, increment the
92084   ** deferred constraint counter by nIncr for each row selected.  */
92085   pWInfo = sqlite3WhereBegin(pParse, pSrc, pWhere, 0, 0, 0, 0);
92086   if( nIncr>0 && pFKey->isDeferred==0 ){
92087     sqlite3ParseToplevel(pParse)->mayAbort = 1;
92088   }
92089   sqlite3VdbeAddOp2(v, OP_FkCounter, pFKey->isDeferred, nIncr);
92090   if( pWInfo ){
92091     sqlite3WhereEnd(pWInfo);
92092   }
92093 
92094   /* Clean up the WHERE clause constructed above. */
92095   sqlite3ExprDelete(db, pWhere);
92096   if( iFkIfZero ){
92097     sqlite3VdbeJumpHere(v, iFkIfZero);
92098   }
92099 }
92100 
92101 /*
92102 ** This function returns a linked list of FKey objects (connected by
92103 ** FKey.pNextTo) holding all children of table pTab.  For example,
92104 ** given the following schema:
92105 **
92106 **   CREATE TABLE t1(a PRIMARY KEY);
92107 **   CREATE TABLE t2(b REFERENCES t1(a);
92108 **
92109 ** Calling this function with table "t1" as an argument returns a pointer
92110 ** to the FKey structure representing the foreign key constraint on table
92111 ** "t2". Calling this function with "t2" as the argument would return a
92112 ** NULL pointer (as there are no FK constraints for which t2 is the parent
92113 ** table).
92114 */
92115 SQLITE_PRIVATE FKey *sqlite3FkReferences(Table *pTab){
92116   int nName = sqlite3Strlen30(pTab->zName);
92117   return (FKey *)sqlite3HashFind(&pTab->pSchema->fkeyHash, pTab->zName, nName);
92118 }
92119 
92120 /*
92121 ** The second argument is a Trigger structure allocated by the 
92122 ** fkActionTrigger() routine. This function deletes the Trigger structure
92123 ** and all of its sub-components.
92124 **
92125 ** The Trigger structure or any of its sub-components may be allocated from
92126 ** the lookaside buffer belonging to database handle dbMem.
92127 */
92128 static void fkTriggerDelete(sqlite3 *dbMem, Trigger *p){
92129   if( p ){
92130     TriggerStep *pStep = p->step_list;
92131     sqlite3ExprDelete(dbMem, pStep->pWhere);
92132     sqlite3ExprListDelete(dbMem, pStep->pExprList);
92133     sqlite3SelectDelete(dbMem, pStep->pSelect);
92134     sqlite3ExprDelete(dbMem, p->pWhen);
92135     sqlite3DbFree(dbMem, p);
92136   }
92137 }
92138 
92139 /*
92140 ** This function is called to generate code that runs when table pTab is
92141 ** being dropped from the database. The SrcList passed as the second argument
92142 ** to this function contains a single entry guaranteed to resolve to
92143 ** table pTab.
92144 **
92145 ** Normally, no code is required. However, if either
92146 **
92147 **   (a) The table is the parent table of a FK constraint, or
92148 **   (b) The table is the child table of a deferred FK constraint and it is
92149 **       determined at runtime that there are outstanding deferred FK 
92150 **       constraint violations in the database,
92151 **
92152 ** then the equivalent of "DELETE FROM <tbl>" is executed before dropping
92153 ** the table from the database. Triggers are disabled while running this
92154 ** DELETE, but foreign key actions are not.
92155 */
92156 SQLITE_PRIVATE void sqlite3FkDropTable(Parse *pParse, SrcList *pName, Table *pTab){
92157   sqlite3 *db = pParse->db;
92158   if( (db->flags&SQLITE_ForeignKeys) && !IsVirtual(pTab) && !pTab->pSelect ){
92159     int iSkip = 0;
92160     Vdbe *v = sqlite3GetVdbe(pParse);
92161 
92162     assert( v );                  /* VDBE has already been allocated */
92163     if( sqlite3FkReferences(pTab)==0 ){
92164       /* Search for a deferred foreign key constraint for which this table
92165       ** is the child table. If one cannot be found, return without 
92166       ** generating any VDBE code. If one can be found, then jump over
92167       ** the entire DELETE if there are no outstanding deferred constraints
92168       ** when this statement is run.  */
92169       FKey *p;
92170       for(p=pTab->pFKey; p; p=p->pNextFrom){
92171         if( p->isDeferred || (db->flags & SQLITE_DeferFKs) ) break;
92172       }
92173       if( !p ) return;
92174       iSkip = sqlite3VdbeMakeLabel(v);
92175       sqlite3VdbeAddOp2(v, OP_FkIfZero, 1, iSkip);
92176     }
92177 
92178     pParse->disableTriggers = 1;
92179     sqlite3DeleteFrom(pParse, sqlite3SrcListDup(db, pName, 0), 0);
92180     pParse->disableTriggers = 0;
92181 
92182     /* If the DELETE has generated immediate foreign key constraint 
92183     ** violations, halt the VDBE and return an error at this point, before
92184     ** any modifications to the schema are made. This is because statement
92185     ** transactions are not able to rollback schema changes.  
92186     **
92187     ** If the SQLITE_DeferFKs flag is set, then this is not required, as
92188     ** the statement transaction will not be rolled back even if FK
92189     ** constraints are violated.
92190     */
92191     if( (db->flags & SQLITE_DeferFKs)==0 ){
92192       sqlite3VdbeAddOp2(v, OP_FkIfZero, 0, sqlite3VdbeCurrentAddr(v)+2);
92193       sqlite3HaltConstraint(pParse, SQLITE_CONSTRAINT_FOREIGNKEY,
92194           OE_Abort, 0, P4_STATIC, P5_ConstraintFK);
92195     }
92196 
92197     if( iSkip ){
92198       sqlite3VdbeResolveLabel(v, iSkip);
92199     }
92200   }
92201 }
92202 
92203 
92204 /*
92205 ** The second argument points to an FKey object representing a foreign key
92206 ** for which pTab is the child table. An UPDATE statement against pTab
92207 ** is currently being processed. For each column of the table that is 
92208 ** actually updated, the corresponding element in the aChange[] array
92209 ** is zero or greater (if a column is unmodified the corresponding element
92210 ** is set to -1). If the rowid column is modified by the UPDATE statement
92211 ** the bChngRowid argument is non-zero.
92212 **
92213 ** This function returns true if any of the columns that are part of the
92214 ** child key for FK constraint *p are modified.
92215 */
92216 static int fkChildIsModified(
92217   Table *pTab,                    /* Table being updated */
92218   FKey *p,                        /* Foreign key for which pTab is the child */
92219   int *aChange,                   /* Array indicating modified columns */
92220   int bChngRowid                  /* True if rowid is modified by this update */
92221 ){
92222   int i;
92223   for(i=0; i<p->nCol; i++){
92224     int iChildKey = p->aCol[i].iFrom;
92225     if( aChange[iChildKey]>=0 ) return 1;
92226     if( iChildKey==pTab->iPKey && bChngRowid ) return 1;
92227   }
92228   return 0;
92229 }
92230 
92231 /*
92232 ** The second argument points to an FKey object representing a foreign key
92233 ** for which pTab is the parent table. An UPDATE statement against pTab
92234 ** is currently being processed. For each column of the table that is 
92235 ** actually updated, the corresponding element in the aChange[] array
92236 ** is zero or greater (if a column is unmodified the corresponding element
92237 ** is set to -1). If the rowid column is modified by the UPDATE statement
92238 ** the bChngRowid argument is non-zero.
92239 **
92240 ** This function returns true if any of the columns that are part of the
92241 ** parent key for FK constraint *p are modified.
92242 */
92243 static int fkParentIsModified(
92244   Table *pTab, 
92245   FKey *p, 
92246   int *aChange, 
92247   int bChngRowid
92248 ){
92249   int i;
92250   for(i=0; i<p->nCol; i++){
92251     char *zKey = p->aCol[i].zCol;
92252     int iKey;
92253     for(iKey=0; iKey<pTab->nCol; iKey++){
92254       if( aChange[iKey]>=0 || (iKey==pTab->iPKey && bChngRowid) ){
92255         Column *pCol = &pTab->aCol[iKey];
92256         if( zKey ){
92257           if( 0==sqlite3StrICmp(pCol->zName, zKey) ) return 1;
92258         }else if( pCol->colFlags & COLFLAG_PRIMKEY ){
92259           return 1;
92260         }
92261       }
92262     }
92263   }
92264   return 0;
92265 }
92266 
92267 /*
92268 ** This function is called when inserting, deleting or updating a row of
92269 ** table pTab to generate VDBE code to perform foreign key constraint 
92270 ** processing for the operation.
92271 **
92272 ** For a DELETE operation, parameter regOld is passed the index of the
92273 ** first register in an array of (pTab->nCol+1) registers containing the
92274 ** rowid of the row being deleted, followed by each of the column values
92275 ** of the row being deleted, from left to right. Parameter regNew is passed
92276 ** zero in this case.
92277 **
92278 ** For an INSERT operation, regOld is passed zero and regNew is passed the
92279 ** first register of an array of (pTab->nCol+1) registers containing the new
92280 ** row data.
92281 **
92282 ** For an UPDATE operation, this function is called twice. Once before
92283 ** the original record is deleted from the table using the calling convention
92284 ** described for DELETE. Then again after the original record is deleted
92285 ** but before the new record is inserted using the INSERT convention. 
92286 */
92287 SQLITE_PRIVATE void sqlite3FkCheck(
92288   Parse *pParse,                  /* Parse context */
92289   Table *pTab,                    /* Row is being deleted from this table */ 
92290   int regOld,                     /* Previous row data is stored here */
92291   int regNew,                     /* New row data is stored here */
92292   int *aChange,                   /* Array indicating UPDATEd columns (or 0) */
92293   int bChngRowid                  /* True if rowid is UPDATEd */
92294 ){
92295   sqlite3 *db = pParse->db;       /* Database handle */
92296   FKey *pFKey;                    /* Used to iterate through FKs */
92297   int iDb;                        /* Index of database containing pTab */
92298   const char *zDb;                /* Name of database containing pTab */
92299   int isIgnoreErrors = pParse->disableTriggers;
92300 
92301   /* Exactly one of regOld and regNew should be non-zero. */
92302   assert( (regOld==0)!=(regNew==0) );
92303 
92304   /* If foreign-keys are disabled, this function is a no-op. */
92305   if( (db->flags&SQLITE_ForeignKeys)==0 ) return;
92306 
92307   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
92308   zDb = db->aDb[iDb].zName;
92309 
92310   /* Loop through all the foreign key constraints for which pTab is the
92311   ** child table (the table that the foreign key definition is part of).  */
92312   for(pFKey=pTab->pFKey; pFKey; pFKey=pFKey->pNextFrom){
92313     Table *pTo;                   /* Parent table of foreign key pFKey */
92314     Index *pIdx = 0;              /* Index on key columns in pTo */
92315     int *aiFree = 0;
92316     int *aiCol;
92317     int iCol;
92318     int i;
92319     int isIgnore = 0;
92320 
92321     if( aChange 
92322      && sqlite3_stricmp(pTab->zName, pFKey->zTo)!=0
92323      && fkChildIsModified(pTab, pFKey, aChange, bChngRowid)==0 
92324     ){
92325       continue;
92326     }
92327 
92328     /* Find the parent table of this foreign key. Also find a unique index 
92329     ** on the parent key columns in the parent table. If either of these 
92330     ** schema items cannot be located, set an error in pParse and return 
92331     ** early.  */
92332     if( pParse->disableTriggers ){
92333       pTo = sqlite3FindTable(db, pFKey->zTo, zDb);
92334     }else{
92335       pTo = sqlite3LocateTable(pParse, 0, pFKey->zTo, zDb);
92336     }
92337     if( !pTo || sqlite3FkLocateIndex(pParse, pTo, pFKey, &pIdx, &aiFree) ){
92338       assert( isIgnoreErrors==0 || (regOld!=0 && regNew==0) );
92339       if( !isIgnoreErrors || db->mallocFailed ) return;
92340       if( pTo==0 ){
92341         /* If isIgnoreErrors is true, then a table is being dropped. In this
92342         ** case SQLite runs a "DELETE FROM xxx" on the table being dropped
92343         ** before actually dropping it in order to check FK constraints.
92344         ** If the parent table of an FK constraint on the current table is
92345         ** missing, behave as if it is empty. i.e. decrement the relevant
92346         ** FK counter for each row of the current table with non-NULL keys.
92347         */
92348         Vdbe *v = sqlite3GetVdbe(pParse);
92349         int iJump = sqlite3VdbeCurrentAddr(v) + pFKey->nCol + 1;
92350         for(i=0; i<pFKey->nCol; i++){
92351           int iReg = pFKey->aCol[i].iFrom + regOld + 1;
92352           sqlite3VdbeAddOp2(v, OP_IsNull, iReg, iJump);
92353         }
92354         sqlite3VdbeAddOp2(v, OP_FkCounter, pFKey->isDeferred, -1);
92355       }
92356       continue;
92357     }
92358     assert( pFKey->nCol==1 || (aiFree && pIdx) );
92359 
92360     if( aiFree ){
92361       aiCol = aiFree;
92362     }else{
92363       iCol = pFKey->aCol[0].iFrom;
92364       aiCol = &iCol;
92365     }
92366     for(i=0; i<pFKey->nCol; i++){
92367       if( aiCol[i]==pTab->iPKey ){
92368         aiCol[i] = -1;
92369       }
92370 #ifndef SQLITE_OMIT_AUTHORIZATION
92371       /* Request permission to read the parent key columns. If the 
92372       ** authorization callback returns SQLITE_IGNORE, behave as if any
92373       ** values read from the parent table are NULL. */
92374       if( db->xAuth ){
92375         int rcauth;
92376         char *zCol = pTo->aCol[pIdx ? pIdx->aiColumn[i] : pTo->iPKey].zName;
92377         rcauth = sqlite3AuthReadCol(pParse, pTo->zName, zCol, iDb);
92378         isIgnore = (rcauth==SQLITE_IGNORE);
92379       }
92380 #endif
92381     }
92382 
92383     /* Take a shared-cache advisory read-lock on the parent table. Allocate 
92384     ** a cursor to use to search the unique index on the parent key columns 
92385     ** in the parent table.  */
92386     sqlite3TableLock(pParse, iDb, pTo->tnum, 0, pTo->zName);
92387     pParse->nTab++;
92388 
92389     if( regOld!=0 ){
92390       /* A row is being removed from the child table. Search for the parent.
92391       ** If the parent does not exist, removing the child row resolves an 
92392       ** outstanding foreign key constraint violation. */
92393       fkLookupParent(pParse, iDb, pTo, pIdx, pFKey, aiCol, regOld, -1,isIgnore);
92394     }
92395     if( regNew!=0 ){
92396       /* A row is being added to the child table. If a parent row cannot
92397       ** be found, adding the child row has violated the FK constraint. */ 
92398       fkLookupParent(pParse, iDb, pTo, pIdx, pFKey, aiCol, regNew, +1,isIgnore);
92399     }
92400 
92401     sqlite3DbFree(db, aiFree);
92402   }
92403 
92404   /* Loop through all the foreign key constraints that refer to this table.
92405   ** (the "child" constraints) */
92406   for(pFKey = sqlite3FkReferences(pTab); pFKey; pFKey=pFKey->pNextTo){
92407     Index *pIdx = 0;              /* Foreign key index for pFKey */
92408     SrcList *pSrc;
92409     int *aiCol = 0;
92410 
92411     if( aChange && fkParentIsModified(pTab, pFKey, aChange, bChngRowid)==0 ){
92412       continue;
92413     }
92414 
92415     if( !pFKey->isDeferred && !(db->flags & SQLITE_DeferFKs) 
92416      && !pParse->pToplevel && !pParse->isMultiWrite 
92417     ){
92418       assert( regOld==0 && regNew!=0 );
92419       /* Inserting a single row into a parent table cannot cause an immediate
92420       ** foreign key violation. So do nothing in this case.  */
92421       continue;
92422     }
92423 
92424     if( sqlite3FkLocateIndex(pParse, pTab, pFKey, &pIdx, &aiCol) ){
92425       if( !isIgnoreErrors || db->mallocFailed ) return;
92426       continue;
92427     }
92428     assert( aiCol || pFKey->nCol==1 );
92429 
92430     /* Create a SrcList structure containing the child table.  We need the
92431     ** child table as a SrcList for sqlite3WhereBegin() */
92432     pSrc = sqlite3SrcListAppend(db, 0, 0, 0);
92433     if( pSrc ){
92434       struct SrcList_item *pItem = pSrc->a;
92435       pItem->pTab = pFKey->pFrom;
92436       pItem->zName = pFKey->pFrom->zName;
92437       pItem->pTab->nRef++;
92438       pItem->iCursor = pParse->nTab++;
92439   
92440       if( regNew!=0 ){
92441         fkScanChildren(pParse, pSrc, pTab, pIdx, pFKey, aiCol, regNew, -1);
92442       }
92443       if( regOld!=0 ){
92444         /* If there is a RESTRICT action configured for the current operation
92445         ** on the parent table of this FK, then throw an exception 
92446         ** immediately if the FK constraint is violated, even if this is a
92447         ** deferred trigger. That's what RESTRICT means. To defer checking
92448         ** the constraint, the FK should specify NO ACTION (represented
92449         ** using OE_None). NO ACTION is the default.  */
92450         fkScanChildren(pParse, pSrc, pTab, pIdx, pFKey, aiCol, regOld, 1);
92451       }
92452       pItem->zName = 0;
92453       sqlite3SrcListDelete(db, pSrc);
92454     }
92455     sqlite3DbFree(db, aiCol);
92456   }
92457 }
92458 
92459 #define COLUMN_MASK(x) (((x)>31) ? 0xffffffff : ((u32)1<<(x)))
92460 
92461 /*
92462 ** This function is called before generating code to update or delete a 
92463 ** row contained in table pTab.
92464 */
92465 SQLITE_PRIVATE u32 sqlite3FkOldmask(
92466   Parse *pParse,                  /* Parse context */
92467   Table *pTab                     /* Table being modified */
92468 ){
92469   u32 mask = 0;
92470   if( pParse->db->flags&SQLITE_ForeignKeys ){
92471     FKey *p;
92472     int i;
92473     for(p=pTab->pFKey; p; p=p->pNextFrom){
92474       for(i=0; i<p->nCol; i++) mask |= COLUMN_MASK(p->aCol[i].iFrom);
92475     }
92476     for(p=sqlite3FkReferences(pTab); p; p=p->pNextTo){
92477       Index *pIdx = 0;
92478       sqlite3FkLocateIndex(pParse, pTab, p, &pIdx, 0);
92479       if( pIdx ){
92480         for(i=0; i<pIdx->nKeyCol; i++) mask |= COLUMN_MASK(pIdx->aiColumn[i]);
92481       }
92482     }
92483   }
92484   return mask;
92485 }
92486 
92487 
92488 /*
92489 ** This function is called before generating code to update or delete a 
92490 ** row contained in table pTab. If the operation is a DELETE, then
92491 ** parameter aChange is passed a NULL value. For an UPDATE, aChange points
92492 ** to an array of size N, where N is the number of columns in table pTab.
92493 ** If the i'th column is not modified by the UPDATE, then the corresponding 
92494 ** entry in the aChange[] array is set to -1. If the column is modified,
92495 ** the value is 0 or greater. Parameter chngRowid is set to true if the
92496 ** UPDATE statement modifies the rowid fields of the table.
92497 **
92498 ** If any foreign key processing will be required, this function returns
92499 ** true. If there is no foreign key related processing, this function 
92500 ** returns false.
92501 */
92502 SQLITE_PRIVATE int sqlite3FkRequired(
92503   Parse *pParse,                  /* Parse context */
92504   Table *pTab,                    /* Table being modified */
92505   int *aChange,                   /* Non-NULL for UPDATE operations */
92506   int chngRowid                   /* True for UPDATE that affects rowid */
92507 ){
92508   if( pParse->db->flags&SQLITE_ForeignKeys ){
92509     if( !aChange ){
92510       /* A DELETE operation. Foreign key processing is required if the 
92511       ** table in question is either the child or parent table for any 
92512       ** foreign key constraint.  */
92513       return (sqlite3FkReferences(pTab) || pTab->pFKey);
92514     }else{
92515       /* This is an UPDATE. Foreign key processing is only required if the
92516       ** operation modifies one or more child or parent key columns. */
92517       FKey *p;
92518 
92519       /* Check if any child key columns are being modified. */
92520       for(p=pTab->pFKey; p; p=p->pNextFrom){
92521         if( fkChildIsModified(pTab, p, aChange, chngRowid) ) return 1;
92522       }
92523 
92524       /* Check if any parent key columns are being modified. */
92525       for(p=sqlite3FkReferences(pTab); p; p=p->pNextTo){
92526         if( fkParentIsModified(pTab, p, aChange, chngRowid) ) return 1;
92527       }
92528     }
92529   }
92530   return 0;
92531 }
92532 
92533 /*
92534 ** This function is called when an UPDATE or DELETE operation is being 
92535 ** compiled on table pTab, which is the parent table of foreign-key pFKey.
92536 ** If the current operation is an UPDATE, then the pChanges parameter is
92537 ** passed a pointer to the list of columns being modified. If it is a
92538 ** DELETE, pChanges is passed a NULL pointer.
92539 **
92540 ** It returns a pointer to a Trigger structure containing a trigger
92541 ** equivalent to the ON UPDATE or ON DELETE action specified by pFKey.
92542 ** If the action is "NO ACTION" or "RESTRICT", then a NULL pointer is
92543 ** returned (these actions require no special handling by the triggers
92544 ** sub-system, code for them is created by fkScanChildren()).
92545 **
92546 ** For example, if pFKey is the foreign key and pTab is table "p" in 
92547 ** the following schema:
92548 **
92549 **   CREATE TABLE p(pk PRIMARY KEY);
92550 **   CREATE TABLE c(ck REFERENCES p ON DELETE CASCADE);
92551 **
92552 ** then the returned trigger structure is equivalent to:
92553 **
92554 **   CREATE TRIGGER ... DELETE ON p BEGIN
92555 **     DELETE FROM c WHERE ck = old.pk;
92556 **   END;
92557 **
92558 ** The returned pointer is cached as part of the foreign key object. It
92559 ** is eventually freed along with the rest of the foreign key object by 
92560 ** sqlite3FkDelete().
92561 */
92562 static Trigger *fkActionTrigger(
92563   Parse *pParse,                  /* Parse context */
92564   Table *pTab,                    /* Table being updated or deleted from */
92565   FKey *pFKey,                    /* Foreign key to get action for */
92566   ExprList *pChanges              /* Change-list for UPDATE, NULL for DELETE */
92567 ){
92568   sqlite3 *db = pParse->db;       /* Database handle */
92569   int action;                     /* One of OE_None, OE_Cascade etc. */
92570   Trigger *pTrigger;              /* Trigger definition to return */
92571   int iAction = (pChanges!=0);    /* 1 for UPDATE, 0 for DELETE */
92572 
92573   action = pFKey->aAction[iAction];
92574   pTrigger = pFKey->apTrigger[iAction];
92575 
92576   if( action!=OE_None && !pTrigger ){
92577     u8 enableLookaside;           /* Copy of db->lookaside.bEnabled */
92578     char const *zFrom;            /* Name of child table */
92579     int nFrom;                    /* Length in bytes of zFrom */
92580     Index *pIdx = 0;              /* Parent key index for this FK */
92581     int *aiCol = 0;               /* child table cols -> parent key cols */
92582     TriggerStep *pStep = 0;        /* First (only) step of trigger program */
92583     Expr *pWhere = 0;             /* WHERE clause of trigger step */
92584     ExprList *pList = 0;          /* Changes list if ON UPDATE CASCADE */
92585     Select *pSelect = 0;          /* If RESTRICT, "SELECT RAISE(...)" */
92586     int i;                        /* Iterator variable */
92587     Expr *pWhen = 0;              /* WHEN clause for the trigger */
92588 
92589     if( sqlite3FkLocateIndex(pParse, pTab, pFKey, &pIdx, &aiCol) ) return 0;
92590     assert( aiCol || pFKey->nCol==1 );
92591 
92592     for(i=0; i<pFKey->nCol; i++){
92593       Token tOld = { "old", 3 };  /* Literal "old" token */
92594       Token tNew = { "new", 3 };  /* Literal "new" token */
92595       Token tFromCol;             /* Name of column in child table */
92596       Token tToCol;               /* Name of column in parent table */
92597       int iFromCol;               /* Idx of column in child table */
92598       Expr *pEq;                  /* tFromCol = OLD.tToCol */
92599 
92600       iFromCol = aiCol ? aiCol[i] : pFKey->aCol[0].iFrom;
92601       assert( iFromCol>=0 );
92602       tToCol.z = pIdx ? pTab->aCol[pIdx->aiColumn[i]].zName : "oid";
92603       tFromCol.z = pFKey->pFrom->aCol[iFromCol].zName;
92604 
92605       tToCol.n = sqlite3Strlen30(tToCol.z);
92606       tFromCol.n = sqlite3Strlen30(tFromCol.z);
92607 
92608       /* Create the expression "OLD.zToCol = zFromCol". It is important
92609       ** that the "OLD.zToCol" term is on the LHS of the = operator, so
92610       ** that the affinity and collation sequence associated with the
92611       ** parent table are used for the comparison. */
92612       pEq = sqlite3PExpr(pParse, TK_EQ,
92613           sqlite3PExpr(pParse, TK_DOT, 
92614             sqlite3PExpr(pParse, TK_ID, 0, 0, &tOld),
92615             sqlite3PExpr(pParse, TK_ID, 0, 0, &tToCol)
92616           , 0),
92617           sqlite3PExpr(pParse, TK_ID, 0, 0, &tFromCol)
92618       , 0);
92619       pWhere = sqlite3ExprAnd(db, pWhere, pEq);
92620 
92621       /* For ON UPDATE, construct the next term of the WHEN clause.
92622       ** The final WHEN clause will be like this:
92623       **
92624       **    WHEN NOT(old.col1 IS new.col1 AND ... AND old.colN IS new.colN)
92625       */
92626       if( pChanges ){
92627         pEq = sqlite3PExpr(pParse, TK_IS,
92628             sqlite3PExpr(pParse, TK_DOT, 
92629               sqlite3PExpr(pParse, TK_ID, 0, 0, &tOld),
92630               sqlite3PExpr(pParse, TK_ID, 0, 0, &tToCol),
92631               0),
92632             sqlite3PExpr(pParse, TK_DOT, 
92633               sqlite3PExpr(pParse, TK_ID, 0, 0, &tNew),
92634               sqlite3PExpr(pParse, TK_ID, 0, 0, &tToCol),
92635               0),
92636             0);
92637         pWhen = sqlite3ExprAnd(db, pWhen, pEq);
92638       }
92639   
92640       if( action!=OE_Restrict && (action!=OE_Cascade || pChanges) ){
92641         Expr *pNew;
92642         if( action==OE_Cascade ){
92643           pNew = sqlite3PExpr(pParse, TK_DOT, 
92644             sqlite3PExpr(pParse, TK_ID, 0, 0, &tNew),
92645             sqlite3PExpr(pParse, TK_ID, 0, 0, &tToCol)
92646           , 0);
92647         }else if( action==OE_SetDflt ){
92648           Expr *pDflt = pFKey->pFrom->aCol[iFromCol].pDflt;
92649           if( pDflt ){
92650             pNew = sqlite3ExprDup(db, pDflt, 0);
92651           }else{
92652             pNew = sqlite3PExpr(pParse, TK_NULL, 0, 0, 0);
92653           }
92654         }else{
92655           pNew = sqlite3PExpr(pParse, TK_NULL, 0, 0, 0);
92656         }
92657         pList = sqlite3ExprListAppend(pParse, pList, pNew);
92658         sqlite3ExprListSetName(pParse, pList, &tFromCol, 0);
92659       }
92660     }
92661     sqlite3DbFree(db, aiCol);
92662 
92663     zFrom = pFKey->pFrom->zName;
92664     nFrom = sqlite3Strlen30(zFrom);
92665 
92666     if( action==OE_Restrict ){
92667       Token tFrom;
92668       Expr *pRaise; 
92669 
92670       tFrom.z = zFrom;
92671       tFrom.n = nFrom;
92672       pRaise = sqlite3Expr(db, TK_RAISE, "FOREIGN KEY constraint failed");
92673       if( pRaise ){
92674         pRaise->affinity = OE_Abort;
92675       }
92676       pSelect = sqlite3SelectNew(pParse, 
92677           sqlite3ExprListAppend(pParse, 0, pRaise),
92678           sqlite3SrcListAppend(db, 0, &tFrom, 0),
92679           pWhere,
92680           0, 0, 0, 0, 0, 0
92681       );
92682       pWhere = 0;
92683     }
92684 
92685     /* Disable lookaside memory allocation */
92686     enableLookaside = db->lookaside.bEnabled;
92687     db->lookaside.bEnabled = 0;
92688 
92689     pTrigger = (Trigger *)sqlite3DbMallocZero(db, 
92690         sizeof(Trigger) +         /* struct Trigger */
92691         sizeof(TriggerStep) +     /* Single step in trigger program */
92692         nFrom + 1                 /* Space for pStep->target.z */
92693     );
92694     if( pTrigger ){
92695       pStep = pTrigger->step_list = (TriggerStep *)&pTrigger[1];
92696       pStep->target.z = (char *)&pStep[1];
92697       pStep->target.n = nFrom;
92698       memcpy((char *)pStep->target.z, zFrom, nFrom);
92699   
92700       pStep->pWhere = sqlite3ExprDup(db, pWhere, EXPRDUP_REDUCE);
92701       pStep->pExprList = sqlite3ExprListDup(db, pList, EXPRDUP_REDUCE);
92702       pStep->pSelect = sqlite3SelectDup(db, pSelect, EXPRDUP_REDUCE);
92703       if( pWhen ){
92704         pWhen = sqlite3PExpr(pParse, TK_NOT, pWhen, 0, 0);
92705         pTrigger->pWhen = sqlite3ExprDup(db, pWhen, EXPRDUP_REDUCE);
92706       }
92707     }
92708 
92709     /* Re-enable the lookaside buffer, if it was disabled earlier. */
92710     db->lookaside.bEnabled = enableLookaside;
92711 
92712     sqlite3ExprDelete(db, pWhere);
92713     sqlite3ExprDelete(db, pWhen);
92714     sqlite3ExprListDelete(db, pList);
92715     sqlite3SelectDelete(db, pSelect);
92716     if( db->mallocFailed==1 ){
92717       fkTriggerDelete(db, pTrigger);
92718       return 0;
92719     }
92720     assert( pStep!=0 );
92721 
92722     switch( action ){
92723       case OE_Restrict:
92724         pStep->op = TK_SELECT; 
92725         break;
92726       case OE_Cascade: 
92727         if( !pChanges ){ 
92728           pStep->op = TK_DELETE; 
92729           break; 
92730         }
92731       default:
92732         pStep->op = TK_UPDATE;
92733     }
92734     pStep->pTrig = pTrigger;
92735     pTrigger->pSchema = pTab->pSchema;
92736     pTrigger->pTabSchema = pTab->pSchema;
92737     pFKey->apTrigger[iAction] = pTrigger;
92738     pTrigger->op = (pChanges ? TK_UPDATE : TK_DELETE);
92739   }
92740 
92741   return pTrigger;
92742 }
92743 
92744 /*
92745 ** This function is called when deleting or updating a row to implement
92746 ** any required CASCADE, SET NULL or SET DEFAULT actions.
92747 */
92748 SQLITE_PRIVATE void sqlite3FkActions(
92749   Parse *pParse,                  /* Parse context */
92750   Table *pTab,                    /* Table being updated or deleted from */
92751   ExprList *pChanges,             /* Change-list for UPDATE, NULL for DELETE */
92752   int regOld,                     /* Address of array containing old row */
92753   int *aChange,                   /* Array indicating UPDATEd columns (or 0) */
92754   int bChngRowid                  /* True if rowid is UPDATEd */
92755 ){
92756   /* If foreign-key support is enabled, iterate through all FKs that 
92757   ** refer to table pTab. If there is an action associated with the FK 
92758   ** for this operation (either update or delete), invoke the associated 
92759   ** trigger sub-program.  */
92760   if( pParse->db->flags&SQLITE_ForeignKeys ){
92761     FKey *pFKey;                  /* Iterator variable */
92762     for(pFKey = sqlite3FkReferences(pTab); pFKey; pFKey=pFKey->pNextTo){
92763       if( aChange==0 || fkParentIsModified(pTab, pFKey, aChange, bChngRowid) ){
92764         Trigger *pAct = fkActionTrigger(pParse, pTab, pFKey, pChanges);
92765         if( pAct ){
92766           sqlite3CodeRowTriggerDirect(pParse, pAct, pTab, regOld, OE_Abort, 0);
92767         }
92768       }
92769     }
92770   }
92771 }
92772 
92773 #endif /* ifndef SQLITE_OMIT_TRIGGER */
92774 
92775 /*
92776 ** Free all memory associated with foreign key definitions attached to
92777 ** table pTab. Remove the deleted foreign keys from the Schema.fkeyHash
92778 ** hash table.
92779 */
92780 SQLITE_PRIVATE void sqlite3FkDelete(sqlite3 *db, Table *pTab){
92781   FKey *pFKey;                    /* Iterator variable */
92782   FKey *pNext;                    /* Copy of pFKey->pNextFrom */
92783 
92784   assert( db==0 || sqlite3SchemaMutexHeld(db, 0, pTab->pSchema) );
92785   for(pFKey=pTab->pFKey; pFKey; pFKey=pNext){
92786 
92787     /* Remove the FK from the fkeyHash hash table. */
92788     if( !db || db->pnBytesFreed==0 ){
92789       if( pFKey->pPrevTo ){
92790         pFKey->pPrevTo->pNextTo = pFKey->pNextTo;
92791       }else{
92792         void *p = (void *)pFKey->pNextTo;
92793         const char *z = (p ? pFKey->pNextTo->zTo : pFKey->zTo);
92794         sqlite3HashInsert(&pTab->pSchema->fkeyHash, z, sqlite3Strlen30(z), p);
92795       }
92796       if( pFKey->pNextTo ){
92797         pFKey->pNextTo->pPrevTo = pFKey->pPrevTo;
92798       }
92799     }
92800 
92801     /* EV: R-30323-21917 Each foreign key constraint in SQLite is
92802     ** classified as either immediate or deferred.
92803     */
92804     assert( pFKey->isDeferred==0 || pFKey->isDeferred==1 );
92805 
92806     /* Delete any triggers created to implement actions for this FK. */
92807 #ifndef SQLITE_OMIT_TRIGGER
92808     fkTriggerDelete(db, pFKey->apTrigger[0]);
92809     fkTriggerDelete(db, pFKey->apTrigger[1]);
92810 #endif
92811 
92812     pNext = pFKey->pNextFrom;
92813     sqlite3DbFree(db, pFKey);
92814   }
92815 }
92816 #endif /* ifndef SQLITE_OMIT_FOREIGN_KEY */
92817 
92818 /************** End of fkey.c ************************************************/
92819 /************** Begin file insert.c ******************************************/
92820 /*
92821 ** 2001 September 15
92822 **
92823 ** The author disclaims copyright to this source code.  In place of
92824 ** a legal notice, here is a blessing:
92825 **
92826 **    May you do good and not evil.
92827 **    May you find forgiveness for yourself and forgive others.
92828 **    May you share freely, never taking more than you give.
92829 **
92830 *************************************************************************
92831 ** This file contains C code routines that are called by the parser
92832 ** to handle INSERT statements in SQLite.
92833 */
92834 
92835 /*
92836 ** Generate code that will 
92837 **
92838 **   (1) acquire a lock for table pTab then
92839 **   (2) open pTab as cursor iCur.
92840 **
92841 ** If pTab is a WITHOUT ROWID table, then it is the PRIMARY KEY index
92842 ** for that table that is actually opened.
92843 */
92844 SQLITE_PRIVATE void sqlite3OpenTable(
92845   Parse *pParse,  /* Generate code into this VDBE */
92846   int iCur,       /* The cursor number of the table */
92847   int iDb,        /* The database index in sqlite3.aDb[] */
92848   Table *pTab,    /* The table to be opened */
92849   int opcode      /* OP_OpenRead or OP_OpenWrite */
92850 ){
92851   Vdbe *v;
92852   assert( !IsVirtual(pTab) );
92853   v = sqlite3GetVdbe(pParse);
92854   assert( opcode==OP_OpenWrite || opcode==OP_OpenRead );
92855   sqlite3TableLock(pParse, iDb, pTab->tnum, 
92856                    (opcode==OP_OpenWrite)?1:0, pTab->zName);
92857   if( HasRowid(pTab) ){
92858     sqlite3VdbeAddOp4Int(v, opcode, iCur, pTab->tnum, iDb, pTab->nCol);
92859     VdbeComment((v, "%s", pTab->zName));
92860   }else{
92861     Index *pPk = sqlite3PrimaryKeyIndex(pTab);
92862     assert( pPk!=0 );
92863     assert( pPk->tnum=pTab->tnum );
92864     sqlite3VdbeAddOp3(v, opcode, iCur, pPk->tnum, iDb);
92865     sqlite3VdbeSetP4KeyInfo(pParse, pPk);
92866     VdbeComment((v, "%s", pTab->zName));
92867   }
92868 }
92869 
92870 /*
92871 ** Return a pointer to the column affinity string associated with index
92872 ** pIdx. A column affinity string has one character for each column in 
92873 ** the table, according to the affinity of the column:
92874 **
92875 **  Character      Column affinity
92876 **  ------------------------------
92877 **  'a'            TEXT
92878 **  'b'            NONE
92879 **  'c'            NUMERIC
92880 **  'd'            INTEGER
92881 **  'e'            REAL
92882 **
92883 ** An extra 'd' is appended to the end of the string to cover the
92884 ** rowid that appears as the last column in every index.
92885 **
92886 ** Memory for the buffer containing the column index affinity string
92887 ** is managed along with the rest of the Index structure. It will be
92888 ** released when sqlite3DeleteIndex() is called.
92889 */
92890 SQLITE_PRIVATE const char *sqlite3IndexAffinityStr(Vdbe *v, Index *pIdx){
92891   if( !pIdx->zColAff ){
92892     /* The first time a column affinity string for a particular index is
92893     ** required, it is allocated and populated here. It is then stored as
92894     ** a member of the Index structure for subsequent use.
92895     **
92896     ** The column affinity string will eventually be deleted by
92897     ** sqliteDeleteIndex() when the Index structure itself is cleaned
92898     ** up.
92899     */
92900     int n;
92901     Table *pTab = pIdx->pTable;
92902     sqlite3 *db = sqlite3VdbeDb(v);
92903     pIdx->zColAff = (char *)sqlite3DbMallocRaw(0, pIdx->nColumn+1);
92904     if( !pIdx->zColAff ){
92905       db->mallocFailed = 1;
92906       return 0;
92907     }
92908     for(n=0; n<pIdx->nColumn; n++){
92909       i16 x = pIdx->aiColumn[n];
92910       pIdx->zColAff[n] = x<0 ? SQLITE_AFF_INTEGER : pTab->aCol[x].affinity;
92911     }
92912     pIdx->zColAff[n] = 0;
92913   }
92914  
92915   return pIdx->zColAff;
92916 }
92917 
92918 /*
92919 ** Set P4 of the most recently inserted opcode to a column affinity
92920 ** string for table pTab. A column affinity string has one character
92921 ** for each column indexed by the index, according to the affinity of the
92922 ** column:
92923 **
92924 **  Character      Column affinity
92925 **  ------------------------------
92926 **  'a'            TEXT
92927 **  'b'            NONE
92928 **  'c'            NUMERIC
92929 **  'd'            INTEGER
92930 **  'e'            REAL
92931 */
92932 SQLITE_PRIVATE void sqlite3TableAffinityStr(Vdbe *v, Table *pTab){
92933   /* The first time a column affinity string for a particular table
92934   ** is required, it is allocated and populated here. It is then 
92935   ** stored as a member of the Table structure for subsequent use.
92936   **
92937   ** The column affinity string will eventually be deleted by
92938   ** sqlite3DeleteTable() when the Table structure itself is cleaned up.
92939   */
92940   if( !pTab->zColAff ){
92941     char *zColAff;
92942     int i;
92943     sqlite3 *db = sqlite3VdbeDb(v);
92944 
92945     zColAff = (char *)sqlite3DbMallocRaw(0, pTab->nCol+1);
92946     if( !zColAff ){
92947       db->mallocFailed = 1;
92948       return;
92949     }
92950 
92951     for(i=0; i<pTab->nCol; i++){
92952       zColAff[i] = pTab->aCol[i].affinity;
92953     }
92954     zColAff[pTab->nCol] = '\0';
92955 
92956     pTab->zColAff = zColAff;
92957   }
92958 
92959   sqlite3VdbeChangeP4(v, -1, pTab->zColAff, P4_TRANSIENT);
92960 }
92961 
92962 /*
92963 ** Return non-zero if the table pTab in database iDb or any of its indices
92964 ** have been opened at any point in the VDBE program beginning at location
92965 ** iStartAddr throught the end of the program.  This is used to see if 
92966 ** a statement of the form  "INSERT INTO <iDb, pTab> SELECT ..." can 
92967 ** run without using temporary table for the results of the SELECT. 
92968 */
92969 static int readsTable(Parse *p, int iStartAddr, int iDb, Table *pTab){
92970   Vdbe *v = sqlite3GetVdbe(p);
92971   int i;
92972   int iEnd = sqlite3VdbeCurrentAddr(v);
92973 #ifndef SQLITE_OMIT_VIRTUALTABLE
92974   VTable *pVTab = IsVirtual(pTab) ? sqlite3GetVTable(p->db, pTab) : 0;
92975 #endif
92976 
92977   for(i=iStartAddr; i<iEnd; i++){
92978     VdbeOp *pOp = sqlite3VdbeGetOp(v, i);
92979     assert( pOp!=0 );
92980     if( pOp->opcode==OP_OpenRead && pOp->p3==iDb ){
92981       Index *pIndex;
92982       int tnum = pOp->p2;
92983       if( tnum==pTab->tnum ){
92984         return 1;
92985       }
92986       for(pIndex=pTab->pIndex; pIndex; pIndex=pIndex->pNext){
92987         if( tnum==pIndex->tnum ){
92988           return 1;
92989         }
92990       }
92991     }
92992 #ifndef SQLITE_OMIT_VIRTUALTABLE
92993     if( pOp->opcode==OP_VOpen && pOp->p4.pVtab==pVTab ){
92994       assert( pOp->p4.pVtab!=0 );
92995       assert( pOp->p4type==P4_VTAB );
92996       return 1;
92997     }
92998 #endif
92999   }
93000   return 0;
93001 }
93002 
93003 #ifndef SQLITE_OMIT_AUTOINCREMENT
93004 /*
93005 ** Locate or create an AutoincInfo structure associated with table pTab
93006 ** which is in database iDb.  Return the register number for the register
93007 ** that holds the maximum rowid.
93008 **
93009 ** There is at most one AutoincInfo structure per table even if the
93010 ** same table is autoincremented multiple times due to inserts within
93011 ** triggers.  A new AutoincInfo structure is created if this is the
93012 ** first use of table pTab.  On 2nd and subsequent uses, the original
93013 ** AutoincInfo structure is used.
93014 **
93015 ** Three memory locations are allocated:
93016 **
93017 **   (1)  Register to hold the name of the pTab table.
93018 **   (2)  Register to hold the maximum ROWID of pTab.
93019 **   (3)  Register to hold the rowid in sqlite_sequence of pTab
93020 **
93021 ** The 2nd register is the one that is returned.  That is all the
93022 ** insert routine needs to know about.
93023 */
93024 static int autoIncBegin(
93025   Parse *pParse,      /* Parsing context */
93026   int iDb,            /* Index of the database holding pTab */
93027   Table *pTab         /* The table we are writing to */
93028 ){
93029   int memId = 0;      /* Register holding maximum rowid */
93030   if( pTab->tabFlags & TF_Autoincrement ){
93031     Parse *pToplevel = sqlite3ParseToplevel(pParse);
93032     AutoincInfo *pInfo;
93033 
93034     pInfo = pToplevel->pAinc;
93035     while( pInfo && pInfo->pTab!=pTab ){ pInfo = pInfo->pNext; }
93036     if( pInfo==0 ){
93037       pInfo = sqlite3DbMallocRaw(pParse->db, sizeof(*pInfo));
93038       if( pInfo==0 ) return 0;
93039       pInfo->pNext = pToplevel->pAinc;
93040       pToplevel->pAinc = pInfo;
93041       pInfo->pTab = pTab;
93042       pInfo->iDb = iDb;
93043       pToplevel->nMem++;                  /* Register to hold name of table */
93044       pInfo->regCtr = ++pToplevel->nMem;  /* Max rowid register */
93045       pToplevel->nMem++;                  /* Rowid in sqlite_sequence */
93046     }
93047     memId = pInfo->regCtr;
93048   }
93049   return memId;
93050 }
93051 
93052 /*
93053 ** This routine generates code that will initialize all of the
93054 ** register used by the autoincrement tracker.  
93055 */
93056 SQLITE_PRIVATE void sqlite3AutoincrementBegin(Parse *pParse){
93057   AutoincInfo *p;            /* Information about an AUTOINCREMENT */
93058   sqlite3 *db = pParse->db;  /* The database connection */
93059   Db *pDb;                   /* Database only autoinc table */
93060   int memId;                 /* Register holding max rowid */
93061   int addr;                  /* A VDBE address */
93062   Vdbe *v = pParse->pVdbe;   /* VDBE under construction */
93063 
93064   /* This routine is never called during trigger-generation.  It is
93065   ** only called from the top-level */
93066   assert( pParse->pTriggerTab==0 );
93067   assert( pParse==sqlite3ParseToplevel(pParse) );
93068 
93069   assert( v );   /* We failed long ago if this is not so */
93070   for(p = pParse->pAinc; p; p = p->pNext){
93071     pDb = &db->aDb[p->iDb];
93072     memId = p->regCtr;
93073     assert( sqlite3SchemaMutexHeld(db, 0, pDb->pSchema) );
93074     sqlite3OpenTable(pParse, 0, p->iDb, pDb->pSchema->pSeqTab, OP_OpenRead);
93075     sqlite3VdbeAddOp3(v, OP_Null, 0, memId, memId+1);
93076     addr = sqlite3VdbeCurrentAddr(v);
93077     sqlite3VdbeAddOp4(v, OP_String8, 0, memId-1, 0, p->pTab->zName, 0);
93078     sqlite3VdbeAddOp2(v, OP_Rewind, 0, addr+9);
93079     sqlite3VdbeAddOp3(v, OP_Column, 0, 0, memId);
93080     sqlite3VdbeAddOp3(v, OP_Ne, memId-1, addr+7, memId);
93081     sqlite3VdbeChangeP5(v, SQLITE_JUMPIFNULL);
93082     sqlite3VdbeAddOp2(v, OP_Rowid, 0, memId+1);
93083     sqlite3VdbeAddOp3(v, OP_Column, 0, 1, memId);
93084     sqlite3VdbeAddOp2(v, OP_Goto, 0, addr+9);
93085     sqlite3VdbeAddOp2(v, OP_Next, 0, addr+2);
93086     sqlite3VdbeAddOp2(v, OP_Integer, 0, memId);
93087     sqlite3VdbeAddOp0(v, OP_Close);
93088   }
93089 }
93090 
93091 /*
93092 ** Update the maximum rowid for an autoincrement calculation.
93093 **
93094 ** This routine should be called when the top of the stack holds a
93095 ** new rowid that is about to be inserted.  If that new rowid is
93096 ** larger than the maximum rowid in the memId memory cell, then the
93097 ** memory cell is updated.  The stack is unchanged.
93098 */
93099 static void autoIncStep(Parse *pParse, int memId, int regRowid){
93100   if( memId>0 ){
93101     sqlite3VdbeAddOp2(pParse->pVdbe, OP_MemMax, memId, regRowid);
93102   }
93103 }
93104 
93105 /*
93106 ** This routine generates the code needed to write autoincrement
93107 ** maximum rowid values back into the sqlite_sequence register.
93108 ** Every statement that might do an INSERT into an autoincrement
93109 ** table (either directly or through triggers) needs to call this
93110 ** routine just before the "exit" code.
93111 */
93112 SQLITE_PRIVATE void sqlite3AutoincrementEnd(Parse *pParse){
93113   AutoincInfo *p;
93114   Vdbe *v = pParse->pVdbe;
93115   sqlite3 *db = pParse->db;
93116 
93117   assert( v );
93118   for(p = pParse->pAinc; p; p = p->pNext){
93119     Db *pDb = &db->aDb[p->iDb];
93120     int j1, j2, j3, j4, j5;
93121     int iRec;
93122     int memId = p->regCtr;
93123 
93124     iRec = sqlite3GetTempReg(pParse);
93125     assert( sqlite3SchemaMutexHeld(db, 0, pDb->pSchema) );
93126     sqlite3OpenTable(pParse, 0, p->iDb, pDb->pSchema->pSeqTab, OP_OpenWrite);
93127     j1 = sqlite3VdbeAddOp1(v, OP_NotNull, memId+1);
93128     j2 = sqlite3VdbeAddOp0(v, OP_Rewind);
93129     j3 = sqlite3VdbeAddOp3(v, OP_Column, 0, 0, iRec);
93130     j4 = sqlite3VdbeAddOp3(v, OP_Eq, memId-1, 0, iRec);
93131     sqlite3VdbeAddOp2(v, OP_Next, 0, j3);
93132     sqlite3VdbeJumpHere(v, j2);
93133     sqlite3VdbeAddOp2(v, OP_NewRowid, 0, memId+1);
93134     j5 = sqlite3VdbeAddOp0(v, OP_Goto);
93135     sqlite3VdbeJumpHere(v, j4);
93136     sqlite3VdbeAddOp2(v, OP_Rowid, 0, memId+1);
93137     sqlite3VdbeJumpHere(v, j1);
93138     sqlite3VdbeJumpHere(v, j5);
93139     sqlite3VdbeAddOp3(v, OP_MakeRecord, memId-1, 2, iRec);
93140     sqlite3VdbeAddOp3(v, OP_Insert, 0, iRec, memId+1);
93141     sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
93142     sqlite3VdbeAddOp0(v, OP_Close);
93143     sqlite3ReleaseTempReg(pParse, iRec);
93144   }
93145 }
93146 #else
93147 /*
93148 ** If SQLITE_OMIT_AUTOINCREMENT is defined, then the three routines
93149 ** above are all no-ops
93150 */
93151 # define autoIncBegin(A,B,C) (0)
93152 # define autoIncStep(A,B,C)
93153 #endif /* SQLITE_OMIT_AUTOINCREMENT */
93154 
93155 
93156 /*
93157 ** Generate code for a co-routine that will evaluate a subquery one
93158 ** row at a time.
93159 **
93160 ** The pSelect parameter is the subquery that the co-routine will evaluation.
93161 ** Information about the location of co-routine and the registers it will use
93162 ** is returned by filling in the pDest object.
93163 **
93164 ** Registers are allocated as follows:
93165 **
93166 **   pDest->iSDParm      The register holding the next entry-point of the
93167 **                       co-routine.  Run the co-routine to its next breakpoint
93168 **                       by calling "OP_Yield $X" where $X is pDest->iSDParm.
93169 **
93170 **   pDest->iSDParm+1    The register holding the "completed" flag for the
93171 **                       co-routine. This register is 0 if the previous Yield
93172 **                       generated a new result row, or 1 if the subquery
93173 **                       has completed.  If the Yield is called again
93174 **                       after this register becomes 1, then the VDBE will
93175 **                       halt with an SQLITE_INTERNAL error.
93176 **
93177 **   pDest->iSdst        First result register.
93178 **
93179 **   pDest->nSdst        Number of result registers.
93180 **
93181 ** This routine handles all of the register allocation and fills in the
93182 ** pDest structure appropriately.
93183 **
93184 ** Here is a schematic of the generated code assuming that X is the 
93185 ** co-routine entry-point register reg[pDest->iSDParm], that EOF is the
93186 ** completed flag reg[pDest->iSDParm+1], and R and S are the range of
93187 ** registers that hold the result set, reg[pDest->iSdst] through
93188 ** reg[pDest->iSdst+pDest->nSdst-1]:
93189 **
93190 **         X <- A
93191 **         EOF <- 0
93192 **         goto B
93193 **      A: setup for the SELECT
93194 **         loop rows in the SELECT
93195 **           load results into registers R..S
93196 **           yield X
93197 **         end loop
93198 **         cleanup after the SELECT
93199 **         EOF <- 1
93200 **         yield X
93201 **         halt-error
93202 **      B:
93203 **
93204 ** To use this subroutine, the caller generates code as follows:
93205 **
93206 **         [ Co-routine generated by this subroutine, shown above ]
93207 **      S: yield X
93208 **         if EOF goto E
93209 **         if skip this row, goto C
93210 **         if terminate loop, goto E
93211 **         deal with this row
93212 **      C: goto S
93213 **      E:
93214 */
93215 SQLITE_PRIVATE int sqlite3CodeCoroutine(Parse *pParse, Select *pSelect, SelectDest *pDest){
93216   int regYield;       /* Register holding co-routine entry-point */
93217   int regEof;         /* Register holding co-routine completion flag */
93218   int addrTop;        /* Top of the co-routine */
93219   int j1;             /* Jump instruction */
93220   int rc;             /* Result code */
93221   Vdbe *v;            /* VDBE under construction */
93222 
93223   regYield = ++pParse->nMem;
93224   regEof = ++pParse->nMem;
93225   v = sqlite3GetVdbe(pParse);
93226   addrTop = sqlite3VdbeCurrentAddr(v);
93227   sqlite3VdbeAddOp2(v, OP_Integer, addrTop+2, regYield); /* X <- A */
93228   VdbeComment((v, "Co-routine entry point"));
93229   sqlite3VdbeAddOp2(v, OP_Integer, 0, regEof);           /* EOF <- 0 */
93230   VdbeComment((v, "Co-routine completion flag"));
93231   sqlite3SelectDestInit(pDest, SRT_Coroutine, regYield);
93232   j1 = sqlite3VdbeAddOp2(v, OP_Goto, 0, 0);
93233   rc = sqlite3Select(pParse, pSelect, pDest);
93234   assert( pParse->nErr==0 || rc );
93235   if( pParse->db->mallocFailed && rc==SQLITE_OK ) rc = SQLITE_NOMEM;
93236   if( rc ) return rc;
93237   sqlite3VdbeAddOp2(v, OP_Integer, 1, regEof);            /* EOF <- 1 */
93238   sqlite3VdbeAddOp1(v, OP_Yield, regYield);   /* yield X */
93239   sqlite3VdbeAddOp2(v, OP_Halt, SQLITE_INTERNAL, OE_Abort);
93240   VdbeComment((v, "End of coroutine"));
93241   sqlite3VdbeJumpHere(v, j1);                             /* label B: */
93242   return rc;
93243 }
93244 
93245 
93246 
93247 /* Forward declaration */
93248 static int xferOptimization(
93249   Parse *pParse,        /* Parser context */
93250   Table *pDest,         /* The table we are inserting into */
93251   Select *pSelect,      /* A SELECT statement to use as the data source */
93252   int onError,          /* How to handle constraint errors */
93253   int iDbDest           /* The database of pDest */
93254 );
93255 
93256 /*
93257 ** This routine is called to handle SQL of the following forms:
93258 **
93259 **    insert into TABLE (IDLIST) values(EXPRLIST)
93260 **    insert into TABLE (IDLIST) select
93261 **
93262 ** The IDLIST following the table name is always optional.  If omitted,
93263 ** then a list of all columns for the table is substituted.  The IDLIST
93264 ** appears in the pColumn parameter.  pColumn is NULL if IDLIST is omitted.
93265 **
93266 ** The pList parameter holds EXPRLIST in the first form of the INSERT
93267 ** statement above, and pSelect is NULL.  For the second form, pList is
93268 ** NULL and pSelect is a pointer to the select statement used to generate
93269 ** data for the insert.
93270 **
93271 ** The code generated follows one of four templates.  For a simple
93272 ** insert with data coming from a VALUES clause, the code executes
93273 ** once straight down through.  Pseudo-code follows (we call this
93274 ** the "1st template"):
93275 **
93276 **         open write cursor to <table> and its indices
93277 **         put VALUES clause expressions into registers
93278 **         write the resulting record into <table>
93279 **         cleanup
93280 **
93281 ** The three remaining templates assume the statement is of the form
93282 **
93283 **   INSERT INTO <table> SELECT ...
93284 **
93285 ** If the SELECT clause is of the restricted form "SELECT * FROM <table2>" -
93286 ** in other words if the SELECT pulls all columns from a single table
93287 ** and there is no WHERE or LIMIT or GROUP BY or ORDER BY clauses, and
93288 ** if <table2> and <table1> are distinct tables but have identical
93289 ** schemas, including all the same indices, then a special optimization
93290 ** is invoked that copies raw records from <table2> over to <table1>.
93291 ** See the xferOptimization() function for the implementation of this
93292 ** template.  This is the 2nd template.
93293 **
93294 **         open a write cursor to <table>
93295 **         open read cursor on <table2>
93296 **         transfer all records in <table2> over to <table>
93297 **         close cursors
93298 **         foreach index on <table>
93299 **           open a write cursor on the <table> index
93300 **           open a read cursor on the corresponding <table2> index
93301 **           transfer all records from the read to the write cursors
93302 **           close cursors
93303 **         end foreach
93304 **
93305 ** The 3rd template is for when the second template does not apply
93306 ** and the SELECT clause does not read from <table> at any time.
93307 ** The generated code follows this template:
93308 **
93309 **         EOF <- 0
93310 **         X <- A
93311 **         goto B
93312 **      A: setup for the SELECT
93313 **         loop over the rows in the SELECT
93314 **           load values into registers R..R+n
93315 **           yield X
93316 **         end loop
93317 **         cleanup after the SELECT
93318 **         EOF <- 1
93319 **         yield X
93320 **         goto A
93321 **      B: open write cursor to <table> and its indices
93322 **      C: yield X
93323 **         if EOF goto D
93324 **         insert the select result into <table> from R..R+n
93325 **         goto C
93326 **      D: cleanup
93327 **
93328 ** The 4th template is used if the insert statement takes its
93329 ** values from a SELECT but the data is being inserted into a table
93330 ** that is also read as part of the SELECT.  In the third form,
93331 ** we have to use a intermediate table to store the results of
93332 ** the select.  The template is like this:
93333 **
93334 **         EOF <- 0
93335 **         X <- A
93336 **         goto B
93337 **      A: setup for the SELECT
93338 **         loop over the tables in the SELECT
93339 **           load value into register R..R+n
93340 **           yield X
93341 **         end loop
93342 **         cleanup after the SELECT
93343 **         EOF <- 1
93344 **         yield X
93345 **         halt-error
93346 **      B: open temp table
93347 **      L: yield X
93348 **         if EOF goto M
93349 **         insert row from R..R+n into temp table
93350 **         goto L
93351 **      M: open write cursor to <table> and its indices
93352 **         rewind temp table
93353 **      C: loop over rows of intermediate table
93354 **           transfer values form intermediate table into <table>
93355 **         end loop
93356 **      D: cleanup
93357 */
93358 SQLITE_PRIVATE void sqlite3Insert(
93359   Parse *pParse,        /* Parser context */
93360   SrcList *pTabList,    /* Name of table into which we are inserting */
93361   ExprList *pList,      /* List of values to be inserted */
93362   Select *pSelect,      /* A SELECT statement to use as the data source */
93363   IdList *pColumn,      /* Column names corresponding to IDLIST. */
93364   int onError           /* How to handle constraint errors */
93365 ){
93366   sqlite3 *db;          /* The main database structure */
93367   Table *pTab;          /* The table to insert into.  aka TABLE */
93368   char *zTab;           /* Name of the table into which we are inserting */
93369   const char *zDb;      /* Name of the database holding this table */
93370   int i, j, idx;        /* Loop counters */
93371   Vdbe *v;              /* Generate code into this virtual machine */
93372   Index *pIdx;          /* For looping over indices of the table */
93373   int nColumn;          /* Number of columns in the data */
93374   int nHidden = 0;      /* Number of hidden columns if TABLE is virtual */
93375   int iDataCur = 0;     /* VDBE cursor that is the main data repository */
93376   int iIdxCur = 0;      /* First index cursor */
93377   int ipkColumn = -1;   /* Column that is the INTEGER PRIMARY KEY */
93378   int endOfLoop;        /* Label for the end of the insertion loop */
93379   int useTempTable = 0; /* Store SELECT results in intermediate table */
93380   int srcTab = 0;       /* Data comes from this temporary cursor if >=0 */
93381   int addrInsTop = 0;   /* Jump to label "D" */
93382   int addrCont = 0;     /* Top of insert loop. Label "C" in templates 3 and 4 */
93383   int addrSelect = 0;   /* Address of coroutine that implements the SELECT */
93384   SelectDest dest;      /* Destination for SELECT on rhs of INSERT */
93385   int iDb;              /* Index of database holding TABLE */
93386   Db *pDb;              /* The database containing table being inserted into */
93387   int appendFlag = 0;   /* True if the insert is likely to be an append */
93388   int withoutRowid;     /* 0 for normal table.  1 for WITHOUT ROWID table */
93389 
93390   /* Register allocations */
93391   int regFromSelect = 0;/* Base register for data coming from SELECT */
93392   int regAutoinc = 0;   /* Register holding the AUTOINCREMENT counter */
93393   int regRowCount = 0;  /* Memory cell used for the row counter */
93394   int regIns;           /* Block of regs holding rowid+data being inserted */
93395   int regRowid;         /* registers holding insert rowid */
93396   int regData;          /* register holding first column to insert */
93397   int regEof = 0;       /* Register recording end of SELECT data */
93398   int *aRegIdx = 0;     /* One register allocated to each index */
93399 
93400 #ifndef SQLITE_OMIT_TRIGGER
93401   int isView;                 /* True if attempting to insert into a view */
93402   Trigger *pTrigger;          /* List of triggers on pTab, if required */
93403   int tmask;                  /* Mask of trigger times */
93404 #endif
93405 
93406   db = pParse->db;
93407   memset(&dest, 0, sizeof(dest));
93408   if( pParse->nErr || db->mallocFailed ){
93409     goto insert_cleanup;
93410   }
93411 
93412   /* Locate the table into which we will be inserting new information.
93413   */
93414   assert( pTabList->nSrc==1 );
93415   zTab = pTabList->a[0].zName;
93416   if( NEVER(zTab==0) ) goto insert_cleanup;
93417   pTab = sqlite3SrcListLookup(pParse, pTabList);
93418   if( pTab==0 ){
93419     goto insert_cleanup;
93420   }
93421   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
93422   assert( iDb<db->nDb );
93423   pDb = &db->aDb[iDb];
93424   zDb = pDb->zName;
93425   if( sqlite3AuthCheck(pParse, SQLITE_INSERT, pTab->zName, 0, zDb) ){
93426     goto insert_cleanup;
93427   }
93428   withoutRowid = !HasRowid(pTab);
93429 
93430   /* Figure out if we have any triggers and if the table being
93431   ** inserted into is a view
93432   */
93433 #ifndef SQLITE_OMIT_TRIGGER
93434   pTrigger = sqlite3TriggersExist(pParse, pTab, TK_INSERT, 0, &tmask);
93435   isView = pTab->pSelect!=0;
93436 #else
93437 # define pTrigger 0
93438 # define tmask 0
93439 # define isView 0
93440 #endif
93441 #ifdef SQLITE_OMIT_VIEW
93442 # undef isView
93443 # define isView 0
93444 #endif
93445   assert( (pTrigger && tmask) || (pTrigger==0 && tmask==0) );
93446 
93447   /* If pTab is really a view, make sure it has been initialized.
93448   ** ViewGetColumnNames() is a no-op if pTab is not a view.
93449   */
93450   if( sqlite3ViewGetColumnNames(pParse, pTab) ){
93451     goto insert_cleanup;
93452   }
93453 
93454   /* Cannot insert into a read-only table.
93455   */
93456   if( sqlite3IsReadOnly(pParse, pTab, tmask) ){
93457     goto insert_cleanup;
93458   }
93459 
93460   /* Allocate a VDBE
93461   */
93462   v = sqlite3GetVdbe(pParse);
93463   if( v==0 ) goto insert_cleanup;
93464   if( pParse->nested==0 ) sqlite3VdbeCountChanges(v);
93465   sqlite3BeginWriteOperation(pParse, pSelect || pTrigger, iDb);
93466 
93467 #ifndef SQLITE_OMIT_XFER_OPT
93468   /* If the statement is of the form
93469   **
93470   **       INSERT INTO <table1> SELECT * FROM <table2>;
93471   **
93472   ** Then special optimizations can be applied that make the transfer
93473   ** very fast and which reduce fragmentation of indices.
93474   **
93475   ** This is the 2nd template.
93476   */
93477   if( pColumn==0 && xferOptimization(pParse, pTab, pSelect, onError, iDb) ){
93478     assert( !pTrigger );
93479     assert( pList==0 );
93480     goto insert_end;
93481   }
93482 #endif /* SQLITE_OMIT_XFER_OPT */
93483 
93484   /* If this is an AUTOINCREMENT table, look up the sequence number in the
93485   ** sqlite_sequence table and store it in memory cell regAutoinc.
93486   */
93487   regAutoinc = autoIncBegin(pParse, iDb, pTab);
93488 
93489   /* Figure out how many columns of data are supplied.  If the data
93490   ** is coming from a SELECT statement, then generate a co-routine that
93491   ** produces a single row of the SELECT on each invocation.  The
93492   ** co-routine is the common header to the 3rd and 4th templates.
93493   */
93494   if( pSelect ){
93495     /* Data is coming from a SELECT.  Generate a co-routine to run the SELECT */
93496     int rc = sqlite3CodeCoroutine(pParse, pSelect, &dest);
93497     if( rc ) goto insert_cleanup;
93498 
93499     regEof = dest.iSDParm + 1;
93500     regFromSelect = dest.iSdst;
93501     assert( pSelect->pEList );
93502     nColumn = pSelect->pEList->nExpr;
93503     assert( dest.nSdst==nColumn );
93504 
93505     /* Set useTempTable to TRUE if the result of the SELECT statement
93506     ** should be written into a temporary table (template 4).  Set to
93507     ** FALSE if each output row of the SELECT can be written directly into
93508     ** the destination table (template 3).
93509     **
93510     ** A temp table must be used if the table being updated is also one
93511     ** of the tables being read by the SELECT statement.  Also use a 
93512     ** temp table in the case of row triggers.
93513     */
93514     if( pTrigger || readsTable(pParse, addrSelect, iDb, pTab) ){
93515       useTempTable = 1;
93516     }
93517 
93518     if( useTempTable ){
93519       /* Invoke the coroutine to extract information from the SELECT
93520       ** and add it to a transient table srcTab.  The code generated
93521       ** here is from the 4th template:
93522       **
93523       **      B: open temp table
93524       **      L: yield X
93525       **         if EOF goto M
93526       **         insert row from R..R+n into temp table
93527       **         goto L
93528       **      M: ...
93529       */
93530       int regRec;          /* Register to hold packed record */
93531       int regTempRowid;    /* Register to hold temp table ROWID */
93532       int addrTop;         /* Label "L" */
93533       int addrIf;          /* Address of jump to M */
93534 
93535       srcTab = pParse->nTab++;
93536       regRec = sqlite3GetTempReg(pParse);
93537       regTempRowid = sqlite3GetTempReg(pParse);
93538       sqlite3VdbeAddOp2(v, OP_OpenEphemeral, srcTab, nColumn);
93539       addrTop = sqlite3VdbeAddOp1(v, OP_Yield, dest.iSDParm);
93540       addrIf = sqlite3VdbeAddOp1(v, OP_If, regEof);
93541       sqlite3VdbeAddOp3(v, OP_MakeRecord, regFromSelect, nColumn, regRec);
93542       sqlite3VdbeAddOp2(v, OP_NewRowid, srcTab, regTempRowid);
93543       sqlite3VdbeAddOp3(v, OP_Insert, srcTab, regRec, regTempRowid);
93544       sqlite3VdbeAddOp2(v, OP_Goto, 0, addrTop);
93545       sqlite3VdbeJumpHere(v, addrIf);
93546       sqlite3ReleaseTempReg(pParse, regRec);
93547       sqlite3ReleaseTempReg(pParse, regTempRowid);
93548     }
93549   }else{
93550     /* This is the case if the data for the INSERT is coming from a VALUES
93551     ** clause
93552     */
93553     NameContext sNC;
93554     memset(&sNC, 0, sizeof(sNC));
93555     sNC.pParse = pParse;
93556     srcTab = -1;
93557     assert( useTempTable==0 );
93558     nColumn = pList ? pList->nExpr : 0;
93559     for(i=0; i<nColumn; i++){
93560       if( sqlite3ResolveExprNames(&sNC, pList->a[i].pExpr) ){
93561         goto insert_cleanup;
93562       }
93563     }
93564   }
93565 
93566   /* Make sure the number of columns in the source data matches the number
93567   ** of columns to be inserted into the table.
93568   */
93569   if( IsVirtual(pTab) ){
93570     for(i=0; i<pTab->nCol; i++){
93571       nHidden += (IsHiddenColumn(&pTab->aCol[i]) ? 1 : 0);
93572     }
93573   }
93574   if( pColumn==0 && nColumn && nColumn!=(pTab->nCol-nHidden) ){
93575     sqlite3ErrorMsg(pParse, 
93576        "table %S has %d columns but %d values were supplied",
93577        pTabList, 0, pTab->nCol-nHidden, nColumn);
93578     goto insert_cleanup;
93579   }
93580   if( pColumn!=0 && nColumn!=pColumn->nId ){
93581     sqlite3ErrorMsg(pParse, "%d values for %d columns", nColumn, pColumn->nId);
93582     goto insert_cleanup;
93583   }
93584 
93585   /* If the INSERT statement included an IDLIST term, then make sure
93586   ** all elements of the IDLIST really are columns of the table and 
93587   ** remember the column indices.
93588   **
93589   ** If the table has an INTEGER PRIMARY KEY column and that column
93590   ** is named in the IDLIST, then record in the ipkColumn variable
93591   ** the index into IDLIST of the primary key column.  ipkColumn is
93592   ** the index of the primary key as it appears in IDLIST, not as
93593   ** is appears in the original table.  (The index of the INTEGER
93594   ** PRIMARY KEY in the original table is pTab->iPKey.)
93595   */
93596   if( pColumn ){
93597     for(i=0; i<pColumn->nId; i++){
93598       pColumn->a[i].idx = -1;
93599     }
93600     for(i=0; i<pColumn->nId; i++){
93601       for(j=0; j<pTab->nCol; j++){
93602         if( sqlite3StrICmp(pColumn->a[i].zName, pTab->aCol[j].zName)==0 ){
93603           pColumn->a[i].idx = j;
93604           if( j==pTab->iPKey ){
93605             ipkColumn = i;  assert( !withoutRowid );
93606           }
93607           break;
93608         }
93609       }
93610       if( j>=pTab->nCol ){
93611         if( sqlite3IsRowid(pColumn->a[i].zName) && !withoutRowid ){
93612           ipkColumn = i;
93613         }else{
93614           sqlite3ErrorMsg(pParse, "table %S has no column named %s",
93615               pTabList, 0, pColumn->a[i].zName);
93616           pParse->checkSchema = 1;
93617           goto insert_cleanup;
93618         }
93619       }
93620     }
93621   }
93622 
93623   /* If there is no IDLIST term but the table has an integer primary
93624   ** key, the set the ipkColumn variable to the integer primary key 
93625   ** column index in the original table definition.
93626   */
93627   if( pColumn==0 && nColumn>0 ){
93628     ipkColumn = pTab->iPKey;
93629   }
93630     
93631   /* Initialize the count of rows to be inserted
93632   */
93633   if( db->flags & SQLITE_CountRows ){
93634     regRowCount = ++pParse->nMem;
93635     sqlite3VdbeAddOp2(v, OP_Integer, 0, regRowCount);
93636   }
93637 
93638   /* If this is not a view, open the table and and all indices */
93639   if( !isView ){
93640     int nIdx;
93641     nIdx = sqlite3OpenTableAndIndices(pParse, pTab, OP_OpenWrite, -1, 0,
93642                                       &iDataCur, &iIdxCur);
93643     aRegIdx = sqlite3DbMallocRaw(db, sizeof(int)*(nIdx+1));
93644     if( aRegIdx==0 ){
93645       goto insert_cleanup;
93646     }
93647     for(i=0; i<nIdx; i++){
93648       aRegIdx[i] = ++pParse->nMem;
93649     }
93650   }
93651 
93652   /* This is the top of the main insertion loop */
93653   if( useTempTable ){
93654     /* This block codes the top of loop only.  The complete loop is the
93655     ** following pseudocode (template 4):
93656     **
93657     **         rewind temp table
93658     **      C: loop over rows of intermediate table
93659     **           transfer values form intermediate table into <table>
93660     **         end loop
93661     **      D: ...
93662     */
93663     addrInsTop = sqlite3VdbeAddOp1(v, OP_Rewind, srcTab);
93664     addrCont = sqlite3VdbeCurrentAddr(v);
93665   }else if( pSelect ){
93666     /* This block codes the top of loop only.  The complete loop is the
93667     ** following pseudocode (template 3):
93668     **
93669     **      C: yield X
93670     **         if EOF goto D
93671     **         insert the select result into <table> from R..R+n
93672     **         goto C
93673     **      D: ...
93674     */
93675     addrCont = sqlite3VdbeAddOp1(v, OP_Yield, dest.iSDParm);
93676     addrInsTop = sqlite3VdbeAddOp1(v, OP_If, regEof);
93677   }
93678 
93679   /* Allocate registers for holding the rowid of the new row,
93680   ** the content of the new row, and the assemblied row record.
93681   */
93682   regRowid = regIns = pParse->nMem+1;
93683   pParse->nMem += pTab->nCol + 1;
93684   if( IsVirtual(pTab) ){
93685     regRowid++;
93686     pParse->nMem++;
93687   }
93688   regData = regRowid+1;
93689 
93690   /* Run the BEFORE and INSTEAD OF triggers, if there are any
93691   */
93692   endOfLoop = sqlite3VdbeMakeLabel(v);
93693   if( tmask & TRIGGER_BEFORE ){
93694     int regCols = sqlite3GetTempRange(pParse, pTab->nCol+1);
93695 
93696     /* build the NEW.* reference row.  Note that if there is an INTEGER
93697     ** PRIMARY KEY into which a NULL is being inserted, that NULL will be
93698     ** translated into a unique ID for the row.  But on a BEFORE trigger,
93699     ** we do not know what the unique ID will be (because the insert has
93700     ** not happened yet) so we substitute a rowid of -1
93701     */
93702     if( ipkColumn<0 ){
93703       sqlite3VdbeAddOp2(v, OP_Integer, -1, regCols);
93704     }else{
93705       int j1;
93706       assert( !withoutRowid );
93707       if( useTempTable ){
93708         sqlite3VdbeAddOp3(v, OP_Column, srcTab, ipkColumn, regCols);
93709       }else{
93710         assert( pSelect==0 );  /* Otherwise useTempTable is true */
93711         sqlite3ExprCode(pParse, pList->a[ipkColumn].pExpr, regCols);
93712       }
93713       j1 = sqlite3VdbeAddOp1(v, OP_NotNull, regCols);
93714       sqlite3VdbeAddOp2(v, OP_Integer, -1, regCols);
93715       sqlite3VdbeJumpHere(v, j1);
93716       sqlite3VdbeAddOp1(v, OP_MustBeInt, regCols);
93717     }
93718 
93719     /* Cannot have triggers on a virtual table. If it were possible,
93720     ** this block would have to account for hidden column.
93721     */
93722     assert( !IsVirtual(pTab) );
93723 
93724     /* Create the new column data
93725     */
93726     for(i=0; i<pTab->nCol; i++){
93727       if( pColumn==0 ){
93728         j = i;
93729       }else{
93730         for(j=0; j<pColumn->nId; j++){
93731           if( pColumn->a[j].idx==i ) break;
93732         }
93733       }
93734       if( (!useTempTable && !pList) || (pColumn && j>=pColumn->nId) ){
93735         sqlite3ExprCode(pParse, pTab->aCol[i].pDflt, regCols+i+1);
93736       }else if( useTempTable ){
93737         sqlite3VdbeAddOp3(v, OP_Column, srcTab, j, regCols+i+1); 
93738       }else{
93739         assert( pSelect==0 ); /* Otherwise useTempTable is true */
93740         sqlite3ExprCodeAndCache(pParse, pList->a[j].pExpr, regCols+i+1);
93741       }
93742     }
93743 
93744     /* If this is an INSERT on a view with an INSTEAD OF INSERT trigger,
93745     ** do not attempt any conversions before assembling the record.
93746     ** If this is a real table, attempt conversions as required by the
93747     ** table column affinities.
93748     */
93749     if( !isView ){
93750       sqlite3VdbeAddOp2(v, OP_Affinity, regCols+1, pTab->nCol);
93751       sqlite3TableAffinityStr(v, pTab);
93752     }
93753 
93754     /* Fire BEFORE or INSTEAD OF triggers */
93755     sqlite3CodeRowTrigger(pParse, pTrigger, TK_INSERT, 0, TRIGGER_BEFORE, 
93756         pTab, regCols-pTab->nCol-1, onError, endOfLoop);
93757 
93758     sqlite3ReleaseTempRange(pParse, regCols, pTab->nCol+1);
93759   }
93760 
93761   /* Compute the content of the next row to insert into a range of
93762   ** registers beginning at regIns.
93763   */
93764   if( !isView ){
93765     if( IsVirtual(pTab) ){
93766       /* The row that the VUpdate opcode will delete: none */
93767       sqlite3VdbeAddOp2(v, OP_Null, 0, regIns);
93768     }
93769     if( ipkColumn>=0 ){
93770       if( useTempTable ){
93771         sqlite3VdbeAddOp3(v, OP_Column, srcTab, ipkColumn, regRowid);
93772       }else if( pSelect ){
93773         sqlite3VdbeAddOp2(v, OP_SCopy, regFromSelect+ipkColumn, regRowid);
93774       }else{
93775         VdbeOp *pOp;
93776         sqlite3ExprCode(pParse, pList->a[ipkColumn].pExpr, regRowid);
93777         pOp = sqlite3VdbeGetOp(v, -1);
93778         if( ALWAYS(pOp) && pOp->opcode==OP_Null && !IsVirtual(pTab) ){
93779           appendFlag = 1;
93780           pOp->opcode = OP_NewRowid;
93781           pOp->p1 = iDataCur;
93782           pOp->p2 = regRowid;
93783           pOp->p3 = regAutoinc;
93784         }
93785       }
93786       /* If the PRIMARY KEY expression is NULL, then use OP_NewRowid
93787       ** to generate a unique primary key value.
93788       */
93789       if( !appendFlag ){
93790         int j1;
93791         if( !IsVirtual(pTab) ){
93792           j1 = sqlite3VdbeAddOp1(v, OP_NotNull, regRowid);
93793           sqlite3VdbeAddOp3(v, OP_NewRowid, iDataCur, regRowid, regAutoinc);
93794           sqlite3VdbeJumpHere(v, j1);
93795         }else{
93796           j1 = sqlite3VdbeCurrentAddr(v);
93797           sqlite3VdbeAddOp2(v, OP_IsNull, regRowid, j1+2);
93798         }
93799         sqlite3VdbeAddOp1(v, OP_MustBeInt, regRowid);
93800       }
93801     }else if( IsVirtual(pTab) || withoutRowid ){
93802       sqlite3VdbeAddOp2(v, OP_Null, 0, regRowid);
93803     }else{
93804       sqlite3VdbeAddOp3(v, OP_NewRowid, iDataCur, regRowid, regAutoinc);
93805       appendFlag = 1;
93806     }
93807     autoIncStep(pParse, regAutoinc, regRowid);
93808 
93809     /* Compute data for all columns of the new entry, beginning
93810     ** with the first column.
93811     */
93812     nHidden = 0;
93813     for(i=0; i<pTab->nCol; i++){
93814       int iRegStore = regRowid+1+i;
93815       if( i==pTab->iPKey ){
93816         /* The value of the INTEGER PRIMARY KEY column is always a NULL.
93817         ** Whenever this column is read, the rowid will be substituted
93818         ** in its place.  Hence, fill this column with a NULL to avoid
93819         ** taking up data space with information that will never be used. */
93820         sqlite3VdbeAddOp2(v, OP_Null, 0, iRegStore);
93821         continue;
93822       }
93823       if( pColumn==0 ){
93824         if( IsHiddenColumn(&pTab->aCol[i]) ){
93825           assert( IsVirtual(pTab) );
93826           j = -1;
93827           nHidden++;
93828         }else{
93829           j = i - nHidden;
93830         }
93831       }else{
93832         for(j=0; j<pColumn->nId; j++){
93833           if( pColumn->a[j].idx==i ) break;
93834         }
93835       }
93836       if( j<0 || nColumn==0 || (pColumn && j>=pColumn->nId) ){
93837         sqlite3ExprCode(pParse, pTab->aCol[i].pDflt, iRegStore);
93838       }else if( useTempTable ){
93839         sqlite3VdbeAddOp3(v, OP_Column, srcTab, j, iRegStore); 
93840       }else if( pSelect ){
93841         sqlite3VdbeAddOp2(v, OP_SCopy, regFromSelect+j, iRegStore);
93842       }else{
93843         sqlite3ExprCode(pParse, pList->a[j].pExpr, iRegStore);
93844       }
93845     }
93846 
93847     /* Generate code to check constraints and generate index keys and
93848     ** do the insertion.
93849     */
93850 #ifndef SQLITE_OMIT_VIRTUALTABLE
93851     if( IsVirtual(pTab) ){
93852       const char *pVTab = (const char *)sqlite3GetVTable(db, pTab);
93853       sqlite3VtabMakeWritable(pParse, pTab);
93854       sqlite3VdbeAddOp4(v, OP_VUpdate, 1, pTab->nCol+2, regIns, pVTab, P4_VTAB);
93855       sqlite3VdbeChangeP5(v, onError==OE_Default ? OE_Abort : onError);
93856       sqlite3MayAbort(pParse);
93857     }else
93858 #endif
93859     {
93860       int isReplace;    /* Set to true if constraints may cause a replace */
93861       sqlite3GenerateConstraintChecks(pParse, pTab, aRegIdx, iDataCur, iIdxCur,
93862           regIns, 0, ipkColumn>=0, onError, endOfLoop, &isReplace
93863       );
93864       sqlite3FkCheck(pParse, pTab, 0, regIns, 0, 0);
93865       sqlite3CompleteInsertion(pParse, pTab, iDataCur, iIdxCur,
93866                                regIns, aRegIdx, 0, appendFlag, isReplace==0);
93867     }
93868   }
93869 
93870   /* Update the count of rows that are inserted
93871   */
93872   if( (db->flags & SQLITE_CountRows)!=0 ){
93873     sqlite3VdbeAddOp2(v, OP_AddImm, regRowCount, 1);
93874   }
93875 
93876   if( pTrigger ){
93877     /* Code AFTER triggers */
93878     sqlite3CodeRowTrigger(pParse, pTrigger, TK_INSERT, 0, TRIGGER_AFTER, 
93879         pTab, regData-2-pTab->nCol, onError, endOfLoop);
93880   }
93881 
93882   /* The bottom of the main insertion loop, if the data source
93883   ** is a SELECT statement.
93884   */
93885   sqlite3VdbeResolveLabel(v, endOfLoop);
93886   if( useTempTable ){
93887     sqlite3VdbeAddOp2(v, OP_Next, srcTab, addrCont);
93888     sqlite3VdbeJumpHere(v, addrInsTop);
93889     sqlite3VdbeAddOp1(v, OP_Close, srcTab);
93890   }else if( pSelect ){
93891     sqlite3VdbeAddOp2(v, OP_Goto, 0, addrCont);
93892     sqlite3VdbeJumpHere(v, addrInsTop);
93893   }
93894 
93895   if( !IsVirtual(pTab) && !isView ){
93896     /* Close all tables opened */
93897     if( iDataCur<iIdxCur ) sqlite3VdbeAddOp1(v, OP_Close, iDataCur);
93898     for(idx=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, idx++){
93899       sqlite3VdbeAddOp1(v, OP_Close, idx+iIdxCur);
93900     }
93901   }
93902 
93903 insert_end:
93904   /* Update the sqlite_sequence table by storing the content of the
93905   ** maximum rowid counter values recorded while inserting into
93906   ** autoincrement tables.
93907   */
93908   if( pParse->nested==0 && pParse->pTriggerTab==0 ){
93909     sqlite3AutoincrementEnd(pParse);
93910   }
93911 
93912   /*
93913   ** Return the number of rows inserted. If this routine is 
93914   ** generating code because of a call to sqlite3NestedParse(), do not
93915   ** invoke the callback function.
93916   */
93917   if( (db->flags&SQLITE_CountRows) && !pParse->nested && !pParse->pTriggerTab ){
93918     sqlite3VdbeAddOp2(v, OP_ResultRow, regRowCount, 1);
93919     sqlite3VdbeSetNumCols(v, 1);
93920     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "rows inserted", SQLITE_STATIC);
93921   }
93922 
93923 insert_cleanup:
93924   sqlite3SrcListDelete(db, pTabList);
93925   sqlite3ExprListDelete(db, pList);
93926   sqlite3SelectDelete(db, pSelect);
93927   sqlite3IdListDelete(db, pColumn);
93928   sqlite3DbFree(db, aRegIdx);
93929 }
93930 
93931 /* Make sure "isView" and other macros defined above are undefined. Otherwise
93932 ** thely may interfere with compilation of other functions in this file
93933 ** (or in another file, if this file becomes part of the amalgamation).  */
93934 #ifdef isView
93935  #undef isView
93936 #endif
93937 #ifdef pTrigger
93938  #undef pTrigger
93939 #endif
93940 #ifdef tmask
93941  #undef tmask
93942 #endif
93943 
93944 /*
93945 ** Generate code to do constraint checks prior to an INSERT or an UPDATE
93946 ** on table pTab.
93947 **
93948 ** The regNewData parameter is the first register in a range that contains
93949 ** the data to be inserted or the data after the update.  There will be
93950 ** pTab->nCol+1 registers in this range.  The first register (the one
93951 ** that regNewData points to) will contain the new rowid, or NULL in the
93952 ** case of a WITHOUT ROWID table.  The second register in the range will
93953 ** contain the content of the first table column.  The third register will
93954 ** contain the content of the second table column.  And so forth.
93955 **
93956 ** The regOldData parameter is similar to regNewData except that it contains
93957 ** the data prior to an UPDATE rather than afterwards.  regOldData is zero
93958 ** for an INSERT.  This routine can distinguish between UPDATE and INSERT by
93959 ** checking regOldData for zero.
93960 **
93961 ** For an UPDATE, the pkChng boolean is true if the true primary key (the
93962 ** rowid for a normal table or the PRIMARY KEY for a WITHOUT ROWID table)
93963 ** might be modified by the UPDATE.  If pkChng is false, then the key of
93964 ** the iDataCur content table is guaranteed to be unchanged by the UPDATE.
93965 **
93966 ** For an INSERT, the pkChng boolean indicates whether or not the rowid
93967 ** was explicitly specified as part of the INSERT statement.  If pkChng
93968 ** is zero, it means that the either rowid is computed automatically or
93969 ** that the table is a WITHOUT ROWID table and has no rowid.  On an INSERT,
93970 ** pkChng will only be true if the INSERT statement provides an integer
93971 ** value for either the rowid column or its INTEGER PRIMARY KEY alias.
93972 **
93973 ** The code generated by this routine will store new index entries into
93974 ** registers identified by aRegIdx[].  No index entry is created for
93975 ** indices where aRegIdx[i]==0.  The order of indices in aRegIdx[] is
93976 ** the same as the order of indices on the linked list of indices
93977 ** at pTab->pIndex.
93978 **
93979 ** The caller must have already opened writeable cursors on the main
93980 ** table and all applicable indices (that is to say, all indices for which
93981 ** aRegIdx[] is not zero).  iDataCur is the cursor for the main table when
93982 ** inserting or updating a rowid table, or the cursor for the PRIMARY KEY
93983 ** index when operating on a WITHOUT ROWID table.  iIdxCur is the cursor
93984 ** for the first index in the pTab->pIndex list.  Cursors for other indices
93985 ** are at iIdxCur+N for the N-th element of the pTab->pIndex list.
93986 **
93987 ** This routine also generates code to check constraints.  NOT NULL,
93988 ** CHECK, and UNIQUE constraints are all checked.  If a constraint fails,
93989 ** then the appropriate action is performed.  There are five possible
93990 ** actions: ROLLBACK, ABORT, FAIL, REPLACE, and IGNORE.
93991 **
93992 **  Constraint type  Action       What Happens
93993 **  ---------------  ----------   ----------------------------------------
93994 **  any              ROLLBACK     The current transaction is rolled back and
93995 **                                sqlite3_step() returns immediately with a
93996 **                                return code of SQLITE_CONSTRAINT.
93997 **
93998 **  any              ABORT        Back out changes from the current command
93999 **                                only (do not do a complete rollback) then
94000 **                                cause sqlite3_step() to return immediately
94001 **                                with SQLITE_CONSTRAINT.
94002 **
94003 **  any              FAIL         Sqlite3_step() returns immediately with a
94004 **                                return code of SQLITE_CONSTRAINT.  The
94005 **                                transaction is not rolled back and any
94006 **                                changes to prior rows are retained.
94007 **
94008 **  any              IGNORE       The attempt in insert or update the current
94009 **                                row is skipped, without throwing an error.
94010 **                                Processing continues with the next row.
94011 **                                (There is an immediate jump to ignoreDest.)
94012 **
94013 **  NOT NULL         REPLACE      The NULL value is replace by the default
94014 **                                value for that column.  If the default value
94015 **                                is NULL, the action is the same as ABORT.
94016 **
94017 **  UNIQUE           REPLACE      The other row that conflicts with the row
94018 **                                being inserted is removed.
94019 **
94020 **  CHECK            REPLACE      Illegal.  The results in an exception.
94021 **
94022 ** Which action to take is determined by the overrideError parameter.
94023 ** Or if overrideError==OE_Default, then the pParse->onError parameter
94024 ** is used.  Or if pParse->onError==OE_Default then the onError value
94025 ** for the constraint is used.
94026 */
94027 SQLITE_PRIVATE void sqlite3GenerateConstraintChecks(
94028   Parse *pParse,       /* The parser context */
94029   Table *pTab,         /* The table being inserted or updated */
94030   int *aRegIdx,        /* Use register aRegIdx[i] for index i.  0 for unused */
94031   int iDataCur,        /* Canonical data cursor (main table or PK index) */
94032   int iIdxCur,         /* First index cursor */
94033   int regNewData,      /* First register in a range holding values to insert */
94034   int regOldData,      /* Previous content.  0 for INSERTs */
94035   u8 pkChng,           /* Non-zero if the rowid or PRIMARY KEY changed */
94036   u8 overrideError,    /* Override onError to this if not OE_Default */
94037   int ignoreDest,      /* Jump to this label on an OE_Ignore resolution */
94038   int *pbMayReplace    /* OUT: Set to true if constraint may cause a replace */
94039 ){
94040   Vdbe *v;             /* VDBE under constrution */
94041   Index *pIdx;         /* Pointer to one of the indices */
94042   Index *pPk = 0;      /* The PRIMARY KEY index */
94043   sqlite3 *db;         /* Database connection */
94044   int i;               /* loop counter */
94045   int ix;              /* Index loop counter */
94046   int nCol;            /* Number of columns */
94047   int onError;         /* Conflict resolution strategy */
94048   int j1;              /* Addresss of jump instruction */
94049   int seenReplace = 0; /* True if REPLACE is used to resolve INT PK conflict */
94050   int nPkField;        /* Number of fields in PRIMARY KEY. 1 for ROWID tables */
94051   int ipkTop = 0;      /* Top of the rowid change constraint check */
94052   int ipkBottom = 0;   /* Bottom of the rowid change constraint check */
94053   u8 isUpdate;         /* True if this is an UPDATE operation */
94054 
94055   isUpdate = regOldData!=0;
94056   db = pParse->db;
94057   v = sqlite3GetVdbe(pParse);
94058   assert( v!=0 );
94059   assert( pTab->pSelect==0 );  /* This table is not a VIEW */
94060   nCol = pTab->nCol;
94061   
94062   /* pPk is the PRIMARY KEY index for WITHOUT ROWID tables and NULL for
94063   ** normal rowid tables.  nPkField is the number of key fields in the 
94064   ** pPk index or 1 for a rowid table.  In other words, nPkField is the
94065   ** number of fields in the true primary key of the table. */
94066   if( HasRowid(pTab) ){
94067     pPk = 0;
94068     nPkField = 1;
94069   }else{
94070     pPk = sqlite3PrimaryKeyIndex(pTab);
94071     nPkField = pPk->nKeyCol;
94072   }
94073 
94074   /* Record that this module has started */
94075   VdbeModuleComment((v, "BEGIN: GenCnstCks(%d,%d,%d,%d,%d)",
94076                      iDataCur, iIdxCur, regNewData, regOldData, pkChng));
94077 
94078   /* Test all NOT NULL constraints.
94079   */
94080   for(i=0; i<nCol; i++){
94081     if( i==pTab->iPKey ){
94082       continue;
94083     }
94084     onError = pTab->aCol[i].notNull;
94085     if( onError==OE_None ) continue;
94086     if( overrideError!=OE_Default ){
94087       onError = overrideError;
94088     }else if( onError==OE_Default ){
94089       onError = OE_Abort;
94090     }
94091     if( onError==OE_Replace && pTab->aCol[i].pDflt==0 ){
94092       onError = OE_Abort;
94093     }
94094     assert( onError==OE_Rollback || onError==OE_Abort || onError==OE_Fail
94095         || onError==OE_Ignore || onError==OE_Replace );
94096     switch( onError ){
94097       case OE_Abort:
94098         sqlite3MayAbort(pParse);
94099         /* Fall through */
94100       case OE_Rollback:
94101       case OE_Fail: {
94102         char *zMsg = sqlite3MPrintf(db, "%s.%s", pTab->zName,
94103                                     pTab->aCol[i].zName);
94104         sqlite3VdbeAddOp4(v, OP_HaltIfNull, SQLITE_CONSTRAINT_NOTNULL, onError,
94105                           regNewData+1+i, zMsg, P4_DYNAMIC);
94106         sqlite3VdbeChangeP5(v, P5_ConstraintNotNull);
94107         break;
94108       }
94109       case OE_Ignore: {
94110         sqlite3VdbeAddOp2(v, OP_IsNull, regNewData+1+i, ignoreDest);
94111         break;
94112       }
94113       default: {
94114         assert( onError==OE_Replace );
94115         j1 = sqlite3VdbeAddOp1(v, OP_NotNull, regNewData+1+i);
94116         sqlite3ExprCode(pParse, pTab->aCol[i].pDflt, regNewData+1+i);
94117         sqlite3VdbeJumpHere(v, j1);
94118         break;
94119       }
94120     }
94121   }
94122 
94123   /* Test all CHECK constraints
94124   */
94125 #ifndef SQLITE_OMIT_CHECK
94126   if( pTab->pCheck && (db->flags & SQLITE_IgnoreChecks)==0 ){
94127     ExprList *pCheck = pTab->pCheck;
94128     pParse->ckBase = regNewData+1;
94129     onError = overrideError!=OE_Default ? overrideError : OE_Abort;
94130     for(i=0; i<pCheck->nExpr; i++){
94131       int allOk = sqlite3VdbeMakeLabel(v);
94132       sqlite3ExprIfTrue(pParse, pCheck->a[i].pExpr, allOk, SQLITE_JUMPIFNULL);
94133       if( onError==OE_Ignore ){
94134         sqlite3VdbeAddOp2(v, OP_Goto, 0, ignoreDest);
94135       }else{
94136         char *zName = pCheck->a[i].zName;
94137         if( zName==0 ) zName = pTab->zName;
94138         if( onError==OE_Replace ) onError = OE_Abort; /* IMP: R-15569-63625 */
94139         sqlite3HaltConstraint(pParse, SQLITE_CONSTRAINT_CHECK,
94140                               onError, zName, P4_TRANSIENT,
94141                               P5_ConstraintCheck);
94142       }
94143       sqlite3VdbeResolveLabel(v, allOk);
94144     }
94145   }
94146 #endif /* !defined(SQLITE_OMIT_CHECK) */
94147 
94148   /* If rowid is changing, make sure the new rowid does not previously
94149   ** exist in the table.
94150   */
94151   if( pkChng && pPk==0 ){
94152     int addrRowidOk = sqlite3VdbeMakeLabel(v);
94153 
94154     /* Figure out what action to take in case of a rowid collision */
94155     onError = pTab->keyConf;
94156     if( overrideError!=OE_Default ){
94157       onError = overrideError;
94158     }else if( onError==OE_Default ){
94159       onError = OE_Abort;
94160     }
94161 
94162     if( isUpdate ){
94163       /* pkChng!=0 does not mean that the rowid has change, only that
94164       ** it might have changed.  Skip the conflict logic below if the rowid
94165       ** is unchanged. */
94166       sqlite3VdbeAddOp3(v, OP_Eq, regNewData, addrRowidOk, regOldData);
94167     }
94168 
94169     /* If the response to a rowid conflict is REPLACE but the response
94170     ** to some other UNIQUE constraint is FAIL or IGNORE, then we need
94171     ** to defer the running of the rowid conflict checking until after
94172     ** the UNIQUE constraints have run.
94173     */
94174     if( onError==OE_Replace && overrideError!=OE_Replace ){
94175       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
94176         if( pIdx->onError==OE_Ignore || pIdx->onError==OE_Fail ){
94177           ipkTop = sqlite3VdbeAddOp0(v, OP_Goto);
94178           break;
94179         }
94180       }
94181     }
94182 
94183     /* Check to see if the new rowid already exists in the table.  Skip
94184     ** the following conflict logic if it does not. */
94185     sqlite3VdbeAddOp3(v, OP_NotExists, iDataCur, addrRowidOk, regNewData);
94186 
94187     /* Generate code that deals with a rowid collision */
94188     switch( onError ){
94189       default: {
94190         onError = OE_Abort;
94191         /* Fall thru into the next case */
94192       }
94193       case OE_Rollback:
94194       case OE_Abort:
94195       case OE_Fail: {
94196         sqlite3RowidConstraint(pParse, onError, pTab);
94197         break;
94198       }
94199       case OE_Replace: {
94200         /* If there are DELETE triggers on this table and the
94201         ** recursive-triggers flag is set, call GenerateRowDelete() to
94202         ** remove the conflicting row from the table. This will fire
94203         ** the triggers and remove both the table and index b-tree entries.
94204         **
94205         ** Otherwise, if there are no triggers or the recursive-triggers
94206         ** flag is not set, but the table has one or more indexes, call 
94207         ** GenerateRowIndexDelete(). This removes the index b-tree entries 
94208         ** only. The table b-tree entry will be replaced by the new entry 
94209         ** when it is inserted.  
94210         **
94211         ** If either GenerateRowDelete() or GenerateRowIndexDelete() is called,
94212         ** also invoke MultiWrite() to indicate that this VDBE may require
94213         ** statement rollback (if the statement is aborted after the delete
94214         ** takes place). Earlier versions called sqlite3MultiWrite() regardless,
94215         ** but being more selective here allows statements like:
94216         **
94217         **   REPLACE INTO t(rowid) VALUES($newrowid)
94218         **
94219         ** to run without a statement journal if there are no indexes on the
94220         ** table.
94221         */
94222         Trigger *pTrigger = 0;
94223         if( db->flags&SQLITE_RecTriggers ){
94224           pTrigger = sqlite3TriggersExist(pParse, pTab, TK_DELETE, 0, 0);
94225         }
94226         if( pTrigger || sqlite3FkRequired(pParse, pTab, 0, 0) ){
94227           sqlite3MultiWrite(pParse);
94228           sqlite3GenerateRowDelete(pParse, pTab, pTrigger, iDataCur, iIdxCur,
94229                                    regNewData, 1, 0, OE_Replace, 1);
94230         }else if( pTab->pIndex ){
94231           sqlite3MultiWrite(pParse);
94232           sqlite3GenerateRowIndexDelete(pParse, pTab, iDataCur, iIdxCur, 0);
94233         }
94234         seenReplace = 1;
94235         break;
94236       }
94237       case OE_Ignore: {
94238         /*assert( seenReplace==0 );*/
94239         sqlite3VdbeAddOp2(v, OP_Goto, 0, ignoreDest);
94240         break;
94241       }
94242     }
94243     sqlite3VdbeResolveLabel(v, addrRowidOk);
94244     if( ipkTop ){
94245       ipkBottom = sqlite3VdbeAddOp0(v, OP_Goto);
94246       sqlite3VdbeJumpHere(v, ipkTop);
94247     }
94248   }
94249 
94250   /* Test all UNIQUE constraints by creating entries for each UNIQUE
94251   ** index and making sure that duplicate entries do not already exist.
94252   ** Compute the revised record entries for indices as we go.
94253   **
94254   ** This loop also handles the case of the PRIMARY KEY index for a
94255   ** WITHOUT ROWID table.
94256   */
94257   for(ix=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, ix++){
94258     int regIdx;          /* Range of registers hold conent for pIdx */
94259     int regR;            /* Range of registers holding conflicting PK */
94260     int iThisCur;        /* Cursor for this UNIQUE index */
94261     int addrUniqueOk;    /* Jump here if the UNIQUE constraint is satisfied */
94262 
94263     if( aRegIdx[ix]==0 ) continue;  /* Skip indices that do not change */
94264     iThisCur = iIdxCur+ix;
94265     addrUniqueOk = sqlite3VdbeMakeLabel(v);
94266 
94267     /* Skip partial indices for which the WHERE clause is not true */
94268     if( pIdx->pPartIdxWhere ){
94269       sqlite3VdbeAddOp2(v, OP_Null, 0, aRegIdx[ix]);
94270       pParse->ckBase = regNewData+1;
94271       sqlite3ExprIfFalse(pParse, pIdx->pPartIdxWhere, addrUniqueOk,
94272                          SQLITE_JUMPIFNULL);
94273       pParse->ckBase = 0;
94274     }
94275 
94276     /* Create a record for this index entry as it should appear after
94277     ** the insert or update.  Store that record in the aRegIdx[ix] register
94278     */
94279     regIdx = sqlite3GetTempRange(pParse, pIdx->nColumn);
94280     for(i=0; i<pIdx->nColumn; i++){
94281       int iField = pIdx->aiColumn[i];
94282       int x;
94283       if( iField<0 || iField==pTab->iPKey ){
94284         x = regNewData;
94285       }else{
94286         x = iField + regNewData + 1;
94287       }
94288       sqlite3VdbeAddOp2(v, OP_SCopy, x, regIdx+i);
94289       VdbeComment((v, "%s", iField<0 ? "rowid" : pTab->aCol[iField].zName));
94290     }
94291     sqlite3VdbeAddOp3(v, OP_MakeRecord, regIdx, pIdx->nColumn, aRegIdx[ix]);
94292     sqlite3VdbeChangeP4(v, -1, sqlite3IndexAffinityStr(v, pIdx), P4_TRANSIENT);
94293     VdbeComment((v, "for %s", pIdx->zName));
94294     sqlite3ExprCacheAffinityChange(pParse, regIdx, pIdx->nColumn);
94295 
94296     /* In an UPDATE operation, if this index is the PRIMARY KEY index 
94297     ** of a WITHOUT ROWID table and there has been no change the
94298     ** primary key, then no collision is possible.  The collision detection
94299     ** logic below can all be skipped. */
94300     if( isUpdate && pPk==pIdx && pkChng==0 ){
94301       sqlite3VdbeResolveLabel(v, addrUniqueOk);
94302       continue;
94303     }
94304 
94305     /* Find out what action to take in case there is a uniqueness conflict */
94306     onError = pIdx->onError;
94307     if( onError==OE_None ){ 
94308       sqlite3ReleaseTempRange(pParse, regIdx, pIdx->nColumn);
94309       sqlite3VdbeResolveLabel(v, addrUniqueOk);
94310       continue;  /* pIdx is not a UNIQUE index */
94311     }
94312     if( overrideError!=OE_Default ){
94313       onError = overrideError;
94314     }else if( onError==OE_Default ){
94315       onError = OE_Abort;
94316     }
94317     
94318     /* Check to see if the new index entry will be unique */
94319     sqlite3VdbeAddOp4Int(v, OP_NoConflict, iThisCur, addrUniqueOk,
94320                          regIdx, pIdx->nKeyCol);
94321 
94322     /* Generate code to handle collisions */
94323     regR = (pIdx==pPk) ? regIdx : sqlite3GetTempRange(pParse, nPkField);
94324     if( HasRowid(pTab) ){
94325       sqlite3VdbeAddOp2(v, OP_IdxRowid, iThisCur, regR);
94326       /* Conflict only if the rowid of the existing index entry
94327       ** is different from old-rowid */
94328       if( isUpdate ){
94329         sqlite3VdbeAddOp3(v, OP_Eq, regR, addrUniqueOk, regOldData);
94330       }
94331     }else{
94332       int x;
94333       /* Extract the PRIMARY KEY from the end of the index entry and
94334       ** store it in registers regR..regR+nPk-1 */
94335       if( (isUpdate || onError==OE_Replace) && pIdx!=pPk ){
94336         for(i=0; i<pPk->nKeyCol; i++){
94337           x = sqlite3ColumnOfIndex(pIdx, pPk->aiColumn[i]);
94338           sqlite3VdbeAddOp3(v, OP_Column, iThisCur, x, regR+i);
94339           VdbeComment((v, "%s.%s", pTab->zName,
94340                        pTab->aCol[pPk->aiColumn[i]].zName));
94341         }
94342       }
94343       if( isUpdate ){
94344         /* If currently processing the PRIMARY KEY of a WITHOUT ROWID 
94345         ** table, only conflict if the new PRIMARY KEY values are actually
94346         ** different from the old.
94347         **
94348         ** For a UNIQUE index, only conflict if the PRIMARY KEY values
94349         ** of the matched index row are different from the original PRIMARY
94350         ** KEY values of this row before the update.  */
94351         int addrJump = sqlite3VdbeCurrentAddr(v)+pPk->nKeyCol;
94352         int op = OP_Ne;
94353         int regCmp = (pIdx->autoIndex==2 ? regIdx : regR);
94354 
94355         for(i=0; i<pPk->nKeyCol; i++){
94356           char *p4 = (char*)sqlite3LocateCollSeq(pParse, pPk->azColl[i]);
94357           x = pPk->aiColumn[i];
94358           if( i==(pPk->nKeyCol-1) ){
94359             addrJump = addrUniqueOk;
94360             op = OP_Eq;
94361           }
94362           sqlite3VdbeAddOp4(v, op, 
94363               regOldData+1+x, addrJump, regCmp+i, p4, P4_COLLSEQ
94364           );
94365         }
94366       }
94367     }
94368 
94369     /* Generate code that executes if the new index entry is not unique */
94370     assert( onError==OE_Rollback || onError==OE_Abort || onError==OE_Fail
94371         || onError==OE_Ignore || onError==OE_Replace );
94372     switch( onError ){
94373       case OE_Rollback:
94374       case OE_Abort:
94375       case OE_Fail: {
94376         sqlite3UniqueConstraint(pParse, onError, pIdx);
94377         break;
94378       }
94379       case OE_Ignore: {
94380         sqlite3VdbeAddOp2(v, OP_Goto, 0, ignoreDest);
94381         break;
94382       }
94383       default: {
94384         Trigger *pTrigger = 0;
94385         assert( onError==OE_Replace );
94386         sqlite3MultiWrite(pParse);
94387         if( db->flags&SQLITE_RecTriggers ){
94388           pTrigger = sqlite3TriggersExist(pParse, pTab, TK_DELETE, 0, 0);
94389         }
94390         sqlite3GenerateRowDelete(pParse, pTab, pTrigger, iDataCur, iIdxCur,
94391                                  regR, nPkField, 0, OE_Replace, pIdx==pPk);
94392         seenReplace = 1;
94393         break;
94394       }
94395     }
94396     sqlite3VdbeResolveLabel(v, addrUniqueOk);
94397     sqlite3ReleaseTempRange(pParse, regIdx, pIdx->nColumn);
94398     if( regR!=regIdx ) sqlite3ReleaseTempRange(pParse, regR, nPkField);
94399   }
94400   if( ipkTop ){
94401     sqlite3VdbeAddOp2(v, OP_Goto, 0, ipkTop+1);
94402     sqlite3VdbeJumpHere(v, ipkBottom);
94403   }
94404   
94405   *pbMayReplace = seenReplace;
94406   VdbeModuleComment((v, "END: GenCnstCks(%d)", seenReplace));
94407 }
94408 
94409 /*
94410 ** This routine generates code to finish the INSERT or UPDATE operation
94411 ** that was started by a prior call to sqlite3GenerateConstraintChecks.
94412 ** A consecutive range of registers starting at regNewData contains the
94413 ** rowid and the content to be inserted.
94414 **
94415 ** The arguments to this routine should be the same as the first six
94416 ** arguments to sqlite3GenerateConstraintChecks.
94417 */
94418 SQLITE_PRIVATE void sqlite3CompleteInsertion(
94419   Parse *pParse,      /* The parser context */
94420   Table *pTab,        /* the table into which we are inserting */
94421   int iDataCur,       /* Cursor of the canonical data source */
94422   int iIdxCur,        /* First index cursor */
94423   int regNewData,     /* Range of content */
94424   int *aRegIdx,       /* Register used by each index.  0 for unused indices */
94425   int isUpdate,       /* True for UPDATE, False for INSERT */
94426   int appendBias,     /* True if this is likely to be an append */
94427   int useSeekResult   /* True to set the USESEEKRESULT flag on OP_[Idx]Insert */
94428 ){
94429   Vdbe *v;            /* Prepared statements under construction */
94430   Index *pIdx;        /* An index being inserted or updated */
94431   u8 pik_flags;       /* flag values passed to the btree insert */
94432   int regData;        /* Content registers (after the rowid) */
94433   int regRec;         /* Register holding assemblied record for the table */
94434   int i;              /* Loop counter */
94435 
94436   v = sqlite3GetVdbe(pParse);
94437   assert( v!=0 );
94438   assert( pTab->pSelect==0 );  /* This table is not a VIEW */
94439   for(i=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, i++){
94440     if( aRegIdx[i]==0 ) continue;
94441     if( pIdx->pPartIdxWhere ){
94442       sqlite3VdbeAddOp2(v, OP_IsNull, aRegIdx[i], sqlite3VdbeCurrentAddr(v)+2);
94443     }
94444     sqlite3VdbeAddOp2(v, OP_IdxInsert, iIdxCur+i, aRegIdx[i]);
94445     pik_flags = 0;
94446     if( useSeekResult ) pik_flags = OPFLAG_USESEEKRESULT;
94447     if( pIdx->autoIndex==2 && !HasRowid(pTab) ){
94448       assert( pParse->nested==0 );
94449       pik_flags |= OPFLAG_NCHANGE;
94450     }
94451     if( pik_flags )  sqlite3VdbeChangeP5(v, pik_flags);
94452   }
94453   if( !HasRowid(pTab) ) return;
94454   regData = regNewData + 1;
94455   regRec = sqlite3GetTempReg(pParse);
94456   sqlite3VdbeAddOp3(v, OP_MakeRecord, regData, pTab->nCol, regRec);
94457   sqlite3TableAffinityStr(v, pTab);
94458   sqlite3ExprCacheAffinityChange(pParse, regData, pTab->nCol);
94459   if( pParse->nested ){
94460     pik_flags = 0;
94461   }else{
94462     pik_flags = OPFLAG_NCHANGE;
94463     pik_flags |= (isUpdate?OPFLAG_ISUPDATE:OPFLAG_LASTROWID);
94464   }
94465   if( appendBias ){
94466     pik_flags |= OPFLAG_APPEND;
94467   }
94468   if( useSeekResult ){
94469     pik_flags |= OPFLAG_USESEEKRESULT;
94470   }
94471   sqlite3VdbeAddOp3(v, OP_Insert, iDataCur, regRec, regNewData);
94472   if( !pParse->nested ){
94473     sqlite3VdbeChangeP4(v, -1, pTab->zName, P4_TRANSIENT);
94474   }
94475   sqlite3VdbeChangeP5(v, pik_flags);
94476 }
94477 
94478 /*
94479 ** Allocate cursors for the pTab table and all its indices and generate
94480 ** code to open and initialized those cursors.
94481 **
94482 ** The cursor for the object that contains the complete data (normally
94483 ** the table itself, but the PRIMARY KEY index in the case of a WITHOUT
94484 ** ROWID table) is returned in *piDataCur.  The first index cursor is
94485 ** returned in *piIdxCur.  The number of indices is returned.
94486 **
94487 ** Use iBase as the first cursor (either the *piDataCur for rowid tables
94488 ** or the first index for WITHOUT ROWID tables) if it is non-negative.
94489 ** If iBase is negative, then allocate the next available cursor.
94490 **
94491 ** For a rowid table, *piDataCur will be exactly one less than *piIdxCur.
94492 ** For a WITHOUT ROWID table, *piDataCur will be somewhere in the range
94493 ** of *piIdxCurs, depending on where the PRIMARY KEY index appears on the
94494 ** pTab->pIndex list.
94495 */
94496 SQLITE_PRIVATE int sqlite3OpenTableAndIndices(
94497   Parse *pParse,   /* Parsing context */
94498   Table *pTab,     /* Table to be opened */
94499   int op,          /* OP_OpenRead or OP_OpenWrite */
94500   int iBase,       /* Use this for the table cursor, if there is one */
94501   u8 *aToOpen,     /* If not NULL: boolean for each table and index */
94502   int *piDataCur,  /* Write the database source cursor number here */
94503   int *piIdxCur    /* Write the first index cursor number here */
94504 ){
94505   int i;
94506   int iDb;
94507   int iDataCur;
94508   Index *pIdx;
94509   Vdbe *v;
94510 
94511   assert( op==OP_OpenRead || op==OP_OpenWrite );
94512   if( IsVirtual(pTab) ){
94513     assert( aToOpen==0 );
94514     *piDataCur = 0;
94515     *piIdxCur = 1;
94516     return 0;
94517   }
94518   iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
94519   v = sqlite3GetVdbe(pParse);
94520   assert( v!=0 );
94521   if( iBase<0 ) iBase = pParse->nTab;
94522   iDataCur = iBase++;
94523   if( piDataCur ) *piDataCur = iDataCur;
94524   if( HasRowid(pTab) && (aToOpen==0 || aToOpen[0]) ){
94525     sqlite3OpenTable(pParse, iDataCur, iDb, pTab, op);
94526   }else{
94527     sqlite3TableLock(pParse, iDb, pTab->tnum, op==OP_OpenWrite, pTab->zName);
94528   }
94529   if( piIdxCur ) *piIdxCur = iBase;
94530   for(i=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, i++){
94531     int iIdxCur = iBase++;
94532     assert( pIdx->pSchema==pTab->pSchema );
94533     if( pIdx->autoIndex==2 && !HasRowid(pTab) && piDataCur ){
94534       *piDataCur = iIdxCur;
94535     }
94536     if( aToOpen==0 || aToOpen[i+1] ){
94537       sqlite3VdbeAddOp3(v, op, iIdxCur, pIdx->tnum, iDb);
94538       sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
94539       VdbeComment((v, "%s", pIdx->zName));
94540     }
94541   }
94542   if( iBase>pParse->nTab ) pParse->nTab = iBase;
94543   return i;
94544 }
94545 
94546 
94547 #ifdef SQLITE_TEST
94548 /*
94549 ** The following global variable is incremented whenever the
94550 ** transfer optimization is used.  This is used for testing
94551 ** purposes only - to make sure the transfer optimization really
94552 ** is happening when it is suppose to.
94553 */
94554 SQLITE_API int sqlite3_xferopt_count;
94555 #endif /* SQLITE_TEST */
94556 
94557 
94558 #ifndef SQLITE_OMIT_XFER_OPT
94559 /*
94560 ** Check to collation names to see if they are compatible.
94561 */
94562 static int xferCompatibleCollation(const char *z1, const char *z2){
94563   if( z1==0 ){
94564     return z2==0;
94565   }
94566   if( z2==0 ){
94567     return 0;
94568   }
94569   return sqlite3StrICmp(z1, z2)==0;
94570 }
94571 
94572 
94573 /*
94574 ** Check to see if index pSrc is compatible as a source of data
94575 ** for index pDest in an insert transfer optimization.  The rules
94576 ** for a compatible index:
94577 **
94578 **    *   The index is over the same set of columns
94579 **    *   The same DESC and ASC markings occurs on all columns
94580 **    *   The same onError processing (OE_Abort, OE_Ignore, etc)
94581 **    *   The same collating sequence on each column
94582 **    *   The index has the exact same WHERE clause
94583 */
94584 static int xferCompatibleIndex(Index *pDest, Index *pSrc){
94585   int i;
94586   assert( pDest && pSrc );
94587   assert( pDest->pTable!=pSrc->pTable );
94588   if( pDest->nKeyCol!=pSrc->nKeyCol ){
94589     return 0;   /* Different number of columns */
94590   }
94591   if( pDest->onError!=pSrc->onError ){
94592     return 0;   /* Different conflict resolution strategies */
94593   }
94594   for(i=0; i<pSrc->nKeyCol; i++){
94595     if( pSrc->aiColumn[i]!=pDest->aiColumn[i] ){
94596       return 0;   /* Different columns indexed */
94597     }
94598     if( pSrc->aSortOrder[i]!=pDest->aSortOrder[i] ){
94599       return 0;   /* Different sort orders */
94600     }
94601     if( !xferCompatibleCollation(pSrc->azColl[i],pDest->azColl[i]) ){
94602       return 0;   /* Different collating sequences */
94603     }
94604   }
94605   if( sqlite3ExprCompare(pSrc->pPartIdxWhere, pDest->pPartIdxWhere, -1) ){
94606     return 0;     /* Different WHERE clauses */
94607   }
94608 
94609   /* If no test above fails then the indices must be compatible */
94610   return 1;
94611 }
94612 
94613 /*
94614 ** Attempt the transfer optimization on INSERTs of the form
94615 **
94616 **     INSERT INTO tab1 SELECT * FROM tab2;
94617 **
94618 ** The xfer optimization transfers raw records from tab2 over to tab1.  
94619 ** Columns are not decoded and reassemblied, which greatly improves
94620 ** performance.  Raw index records are transferred in the same way.
94621 **
94622 ** The xfer optimization is only attempted if tab1 and tab2 are compatible.
94623 ** There are lots of rules for determining compatibility - see comments
94624 ** embedded in the code for details.
94625 **
94626 ** This routine returns TRUE if the optimization is guaranteed to be used.
94627 ** Sometimes the xfer optimization will only work if the destination table
94628 ** is empty - a factor that can only be determined at run-time.  In that
94629 ** case, this routine generates code for the xfer optimization but also
94630 ** does a test to see if the destination table is empty and jumps over the
94631 ** xfer optimization code if the test fails.  In that case, this routine
94632 ** returns FALSE so that the caller will know to go ahead and generate
94633 ** an unoptimized transfer.  This routine also returns FALSE if there
94634 ** is no chance that the xfer optimization can be applied.
94635 **
94636 ** This optimization is particularly useful at making VACUUM run faster.
94637 */
94638 static int xferOptimization(
94639   Parse *pParse,        /* Parser context */
94640   Table *pDest,         /* The table we are inserting into */
94641   Select *pSelect,      /* A SELECT statement to use as the data source */
94642   int onError,          /* How to handle constraint errors */
94643   int iDbDest           /* The database of pDest */
94644 ){
94645   ExprList *pEList;                /* The result set of the SELECT */
94646   Table *pSrc;                     /* The table in the FROM clause of SELECT */
94647   Index *pSrcIdx, *pDestIdx;       /* Source and destination indices */
94648   struct SrcList_item *pItem;      /* An element of pSelect->pSrc */
94649   int i;                           /* Loop counter */
94650   int iDbSrc;                      /* The database of pSrc */
94651   int iSrc, iDest;                 /* Cursors from source and destination */
94652   int addr1, addr2;                /* Loop addresses */
94653   int emptyDestTest = 0;           /* Address of test for empty pDest */
94654   int emptySrcTest = 0;            /* Address of test for empty pSrc */
94655   Vdbe *v;                         /* The VDBE we are building */
94656   int regAutoinc;                  /* Memory register used by AUTOINC */
94657   int destHasUniqueIdx = 0;        /* True if pDest has a UNIQUE index */
94658   int regData, regRowid;           /* Registers holding data and rowid */
94659 
94660   if( pSelect==0 ){
94661     return 0;   /* Must be of the form  INSERT INTO ... SELECT ... */
94662   }
94663   if( sqlite3TriggerList(pParse, pDest) ){
94664     return 0;   /* tab1 must not have triggers */
94665   }
94666 #ifndef SQLITE_OMIT_VIRTUALTABLE
94667   if( pDest->tabFlags & TF_Virtual ){
94668     return 0;   /* tab1 must not be a virtual table */
94669   }
94670 #endif
94671   if( onError==OE_Default ){
94672     if( pDest->iPKey>=0 ) onError = pDest->keyConf;
94673     if( onError==OE_Default ) onError = OE_Abort;
94674   }
94675   assert(pSelect->pSrc);   /* allocated even if there is no FROM clause */
94676   if( pSelect->pSrc->nSrc!=1 ){
94677     return 0;   /* FROM clause must have exactly one term */
94678   }
94679   if( pSelect->pSrc->a[0].pSelect ){
94680     return 0;   /* FROM clause cannot contain a subquery */
94681   }
94682   if( pSelect->pWhere ){
94683     return 0;   /* SELECT may not have a WHERE clause */
94684   }
94685   if( pSelect->pOrderBy ){
94686     return 0;   /* SELECT may not have an ORDER BY clause */
94687   }
94688   /* Do not need to test for a HAVING clause.  If HAVING is present but
94689   ** there is no ORDER BY, we will get an error. */
94690   if( pSelect->pGroupBy ){
94691     return 0;   /* SELECT may not have a GROUP BY clause */
94692   }
94693   if( pSelect->pLimit ){
94694     return 0;   /* SELECT may not have a LIMIT clause */
94695   }
94696   assert( pSelect->pOffset==0 );  /* Must be so if pLimit==0 */
94697   if( pSelect->pPrior ){
94698     return 0;   /* SELECT may not be a compound query */
94699   }
94700   if( pSelect->selFlags & SF_Distinct ){
94701     return 0;   /* SELECT may not be DISTINCT */
94702   }
94703   pEList = pSelect->pEList;
94704   assert( pEList!=0 );
94705   if( pEList->nExpr!=1 ){
94706     return 0;   /* The result set must have exactly one column */
94707   }
94708   assert( pEList->a[0].pExpr );
94709   if( pEList->a[0].pExpr->op!=TK_ALL ){
94710     return 0;   /* The result set must be the special operator "*" */
94711   }
94712 
94713   /* At this point we have established that the statement is of the
94714   ** correct syntactic form to participate in this optimization.  Now
94715   ** we have to check the semantics.
94716   */
94717   pItem = pSelect->pSrc->a;
94718   pSrc = sqlite3LocateTableItem(pParse, 0, pItem);
94719   if( pSrc==0 ){
94720     return 0;   /* FROM clause does not contain a real table */
94721   }
94722   if( pSrc==pDest ){
94723     return 0;   /* tab1 and tab2 may not be the same table */
94724   }
94725   if( HasRowid(pDest)!=HasRowid(pSrc) ){
94726     return 0;   /* source and destination must both be WITHOUT ROWID or not */
94727   }
94728 #ifndef SQLITE_OMIT_VIRTUALTABLE
94729   if( pSrc->tabFlags & TF_Virtual ){
94730     return 0;   /* tab2 must not be a virtual table */
94731   }
94732 #endif
94733   if( pSrc->pSelect ){
94734     return 0;   /* tab2 may not be a view */
94735   }
94736   if( pDest->nCol!=pSrc->nCol ){
94737     return 0;   /* Number of columns must be the same in tab1 and tab2 */
94738   }
94739   if( pDest->iPKey!=pSrc->iPKey ){
94740     return 0;   /* Both tables must have the same INTEGER PRIMARY KEY */
94741   }
94742   for(i=0; i<pDest->nCol; i++){
94743     if( pDest->aCol[i].affinity!=pSrc->aCol[i].affinity ){
94744       return 0;    /* Affinity must be the same on all columns */
94745     }
94746     if( !xferCompatibleCollation(pDest->aCol[i].zColl, pSrc->aCol[i].zColl) ){
94747       return 0;    /* Collating sequence must be the same on all columns */
94748     }
94749     if( pDest->aCol[i].notNull && !pSrc->aCol[i].notNull ){
94750       return 0;    /* tab2 must be NOT NULL if tab1 is */
94751     }
94752   }
94753   for(pDestIdx=pDest->pIndex; pDestIdx; pDestIdx=pDestIdx->pNext){
94754     if( pDestIdx->onError!=OE_None ){
94755       destHasUniqueIdx = 1;
94756     }
94757     for(pSrcIdx=pSrc->pIndex; pSrcIdx; pSrcIdx=pSrcIdx->pNext){
94758       if( xferCompatibleIndex(pDestIdx, pSrcIdx) ) break;
94759     }
94760     if( pSrcIdx==0 ){
94761       return 0;    /* pDestIdx has no corresponding index in pSrc */
94762     }
94763   }
94764 #ifndef SQLITE_OMIT_CHECK
94765   if( pDest->pCheck && sqlite3ExprListCompare(pSrc->pCheck,pDest->pCheck,-1) ){
94766     return 0;   /* Tables have different CHECK constraints.  Ticket #2252 */
94767   }
94768 #endif
94769 #ifndef SQLITE_OMIT_FOREIGN_KEY
94770   /* Disallow the transfer optimization if the destination table constains
94771   ** any foreign key constraints.  This is more restrictive than necessary.
94772   ** But the main beneficiary of the transfer optimization is the VACUUM 
94773   ** command, and the VACUUM command disables foreign key constraints.  So
94774   ** the extra complication to make this rule less restrictive is probably
94775   ** not worth the effort.  Ticket [6284df89debdfa61db8073e062908af0c9b6118e]
94776   */
94777   if( (pParse->db->flags & SQLITE_ForeignKeys)!=0 && pDest->pFKey!=0 ){
94778     return 0;
94779   }
94780 #endif
94781   if( (pParse->db->flags & SQLITE_CountRows)!=0 ){
94782     return 0;  /* xfer opt does not play well with PRAGMA count_changes */
94783   }
94784 
94785   /* If we get this far, it means that the xfer optimization is at
94786   ** least a possibility, though it might only work if the destination
94787   ** table (tab1) is initially empty.
94788   */
94789 #ifdef SQLITE_TEST
94790   sqlite3_xferopt_count++;
94791 #endif
94792   iDbSrc = sqlite3SchemaToIndex(pParse->db, pSrc->pSchema);
94793   v = sqlite3GetVdbe(pParse);
94794   sqlite3CodeVerifySchema(pParse, iDbSrc);
94795   iSrc = pParse->nTab++;
94796   iDest = pParse->nTab++;
94797   regAutoinc = autoIncBegin(pParse, iDbDest, pDest);
94798   regData = sqlite3GetTempReg(pParse);
94799   regRowid = sqlite3GetTempReg(pParse);
94800   sqlite3OpenTable(pParse, iDest, iDbDest, pDest, OP_OpenWrite);
94801   assert( HasRowid(pDest) || destHasUniqueIdx );
94802   if( (pDest->iPKey<0 && pDest->pIndex!=0)          /* (1) */
94803    || destHasUniqueIdx                              /* (2) */
94804    || (onError!=OE_Abort && onError!=OE_Rollback)   /* (3) */
94805   ){
94806     /* In some circumstances, we are able to run the xfer optimization
94807     ** only if the destination table is initially empty.  This code makes
94808     ** that determination.  Conditions under which the destination must
94809     ** be empty:
94810     **
94811     ** (1) There is no INTEGER PRIMARY KEY but there are indices.
94812     **     (If the destination is not initially empty, the rowid fields
94813     **     of index entries might need to change.)
94814     **
94815     ** (2) The destination has a unique index.  (The xfer optimization 
94816     **     is unable to test uniqueness.)
94817     **
94818     ** (3) onError is something other than OE_Abort and OE_Rollback.
94819     */
94820     addr1 = sqlite3VdbeAddOp2(v, OP_Rewind, iDest, 0);
94821     emptyDestTest = sqlite3VdbeAddOp2(v, OP_Goto, 0, 0);
94822     sqlite3VdbeJumpHere(v, addr1);
94823   }
94824   if( HasRowid(pSrc) ){
94825     sqlite3OpenTable(pParse, iSrc, iDbSrc, pSrc, OP_OpenRead);
94826     emptySrcTest = sqlite3VdbeAddOp2(v, OP_Rewind, iSrc, 0);
94827     if( pDest->iPKey>=0 ){
94828       addr1 = sqlite3VdbeAddOp2(v, OP_Rowid, iSrc, regRowid);
94829       addr2 = sqlite3VdbeAddOp3(v, OP_NotExists, iDest, 0, regRowid);
94830       sqlite3RowidConstraint(pParse, onError, pDest);
94831       sqlite3VdbeJumpHere(v, addr2);
94832       autoIncStep(pParse, regAutoinc, regRowid);
94833     }else if( pDest->pIndex==0 ){
94834       addr1 = sqlite3VdbeAddOp2(v, OP_NewRowid, iDest, regRowid);
94835     }else{
94836       addr1 = sqlite3VdbeAddOp2(v, OP_Rowid, iSrc, regRowid);
94837       assert( (pDest->tabFlags & TF_Autoincrement)==0 );
94838     }
94839     sqlite3VdbeAddOp2(v, OP_RowData, iSrc, regData);
94840     sqlite3VdbeAddOp3(v, OP_Insert, iDest, regData, regRowid);
94841     sqlite3VdbeChangeP5(v, OPFLAG_NCHANGE|OPFLAG_LASTROWID|OPFLAG_APPEND);
94842     sqlite3VdbeChangeP4(v, -1, pDest->zName, 0);
94843     sqlite3VdbeAddOp2(v, OP_Next, iSrc, addr1);
94844     sqlite3VdbeAddOp2(v, OP_Close, iSrc, 0);
94845     sqlite3VdbeAddOp2(v, OP_Close, iDest, 0);
94846   }else{
94847     sqlite3TableLock(pParse, iDbDest, pDest->tnum, 1, pDest->zName);
94848     sqlite3TableLock(pParse, iDbSrc, pSrc->tnum, 0, pSrc->zName);
94849   }
94850   for(pDestIdx=pDest->pIndex; pDestIdx; pDestIdx=pDestIdx->pNext){
94851     for(pSrcIdx=pSrc->pIndex; ALWAYS(pSrcIdx); pSrcIdx=pSrcIdx->pNext){
94852       if( xferCompatibleIndex(pDestIdx, pSrcIdx) ) break;
94853     }
94854     assert( pSrcIdx );
94855     sqlite3VdbeAddOp3(v, OP_OpenRead, iSrc, pSrcIdx->tnum, iDbSrc);
94856     sqlite3VdbeSetP4KeyInfo(pParse, pSrcIdx);
94857     VdbeComment((v, "%s", pSrcIdx->zName));
94858     sqlite3VdbeAddOp3(v, OP_OpenWrite, iDest, pDestIdx->tnum, iDbDest);
94859     sqlite3VdbeSetP4KeyInfo(pParse, pDestIdx);
94860     sqlite3VdbeChangeP5(v, OPFLAG_BULKCSR);
94861     VdbeComment((v, "%s", pDestIdx->zName));
94862     addr1 = sqlite3VdbeAddOp2(v, OP_Rewind, iSrc, 0);
94863     sqlite3VdbeAddOp2(v, OP_RowKey, iSrc, regData);
94864     sqlite3VdbeAddOp3(v, OP_IdxInsert, iDest, regData, 1);
94865     sqlite3VdbeAddOp2(v, OP_Next, iSrc, addr1+1);
94866     sqlite3VdbeJumpHere(v, addr1);
94867     sqlite3VdbeAddOp2(v, OP_Close, iSrc, 0);
94868     sqlite3VdbeAddOp2(v, OP_Close, iDest, 0);
94869   }
94870   sqlite3VdbeJumpHere(v, emptySrcTest);
94871   sqlite3ReleaseTempReg(pParse, regRowid);
94872   sqlite3ReleaseTempReg(pParse, regData);
94873   if( emptyDestTest ){
94874     sqlite3VdbeAddOp2(v, OP_Halt, SQLITE_OK, 0);
94875     sqlite3VdbeJumpHere(v, emptyDestTest);
94876     sqlite3VdbeAddOp2(v, OP_Close, iDest, 0);
94877     return 0;
94878   }else{
94879     return 1;
94880   }
94881 }
94882 #endif /* SQLITE_OMIT_XFER_OPT */
94883 
94884 /************** End of insert.c **********************************************/
94885 /************** Begin file legacy.c ******************************************/
94886 /*
94887 ** 2001 September 15
94888 **
94889 ** The author disclaims copyright to this source code.  In place of
94890 ** a legal notice, here is a blessing:
94891 **
94892 **    May you do good and not evil.
94893 **    May you find forgiveness for yourself and forgive others.
94894 **    May you share freely, never taking more than you give.
94895 **
94896 *************************************************************************
94897 ** Main file for the SQLite library.  The routines in this file
94898 ** implement the programmer interface to the library.  Routines in
94899 ** other files are for internal use by SQLite and should not be
94900 ** accessed by users of the library.
94901 */
94902 
94903 
94904 /*
94905 ** Execute SQL code.  Return one of the SQLITE_ success/failure
94906 ** codes.  Also write an error message into memory obtained from
94907 ** malloc() and make *pzErrMsg point to that message.
94908 **
94909 ** If the SQL is a query, then for each row in the query result
94910 ** the xCallback() function is called.  pArg becomes the first
94911 ** argument to xCallback().  If xCallback=NULL then no callback
94912 ** is invoked, even for queries.
94913 */
94914 SQLITE_API int sqlite3_exec(
94915   sqlite3 *db,                /* The database on which the SQL executes */
94916   const char *zSql,           /* The SQL to be executed */
94917   sqlite3_callback xCallback, /* Invoke this callback routine */
94918   void *pArg,                 /* First argument to xCallback() */
94919   char **pzErrMsg             /* Write error messages here */
94920 ){
94921   int rc = SQLITE_OK;         /* Return code */
94922   const char *zLeftover;      /* Tail of unprocessed SQL */
94923   sqlite3_stmt *pStmt = 0;    /* The current SQL statement */
94924   char **azCols = 0;          /* Names of result columns */
94925   int callbackIsInit;         /* True if callback data is initialized */
94926 
94927   if( !sqlite3SafetyCheckOk(db) ) return SQLITE_MISUSE_BKPT;
94928   if( zSql==0 ) zSql = "";
94929 
94930   sqlite3_mutex_enter(db->mutex);
94931   sqlite3Error(db, SQLITE_OK, 0);
94932   while( rc==SQLITE_OK && zSql[0] ){
94933     int nCol;
94934     char **azVals = 0;
94935 
94936     pStmt = 0;
94937     rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, &zLeftover);
94938     assert( rc==SQLITE_OK || pStmt==0 );
94939     if( rc!=SQLITE_OK ){
94940       continue;
94941     }
94942     if( !pStmt ){
94943       /* this happens for a comment or white-space */
94944       zSql = zLeftover;
94945       continue;
94946     }
94947 
94948     callbackIsInit = 0;
94949     nCol = sqlite3_column_count(pStmt);
94950 
94951     while( 1 ){
94952       int i;
94953       rc = sqlite3_step(pStmt);
94954 
94955       /* Invoke the callback function if required */
94956       if( xCallback && (SQLITE_ROW==rc || 
94957           (SQLITE_DONE==rc && !callbackIsInit
94958                            && db->flags&SQLITE_NullCallback)) ){
94959         if( !callbackIsInit ){
94960           azCols = sqlite3DbMallocZero(db, 2*nCol*sizeof(const char*) + 1);
94961           if( azCols==0 ){
94962             goto exec_out;
94963           }
94964           for(i=0; i<nCol; i++){
94965             azCols[i] = (char *)sqlite3_column_name(pStmt, i);
94966             /* sqlite3VdbeSetColName() installs column names as UTF8
94967             ** strings so there is no way for sqlite3_column_name() to fail. */
94968             assert( azCols[i]!=0 );
94969           }
94970           callbackIsInit = 1;
94971         }
94972         if( rc==SQLITE_ROW ){
94973           azVals = &azCols[nCol];
94974           for(i=0; i<nCol; i++){
94975             azVals[i] = (char *)sqlite3_column_text(pStmt, i);
94976             if( !azVals[i] && sqlite3_column_type(pStmt, i)!=SQLITE_NULL ){
94977               db->mallocFailed = 1;
94978               goto exec_out;
94979             }
94980           }
94981         }
94982         if( xCallback(pArg, nCol, azVals, azCols) ){
94983           rc = SQLITE_ABORT;
94984           sqlite3VdbeFinalize((Vdbe *)pStmt);
94985           pStmt = 0;
94986           sqlite3Error(db, SQLITE_ABORT, 0);
94987           goto exec_out;
94988         }
94989       }
94990 
94991       if( rc!=SQLITE_ROW ){
94992         rc = sqlite3VdbeFinalize((Vdbe *)pStmt);
94993         pStmt = 0;
94994         zSql = zLeftover;
94995         while( sqlite3Isspace(zSql[0]) ) zSql++;
94996         break;
94997       }
94998     }
94999 
95000     sqlite3DbFree(db, azCols);
95001     azCols = 0;
95002   }
95003 
95004 exec_out:
95005   if( pStmt ) sqlite3VdbeFinalize((Vdbe *)pStmt);
95006   sqlite3DbFree(db, azCols);
95007 
95008   rc = sqlite3ApiExit(db, rc);
95009   if( rc!=SQLITE_OK && ALWAYS(rc==sqlite3_errcode(db)) && pzErrMsg ){
95010     int nErrMsg = 1 + sqlite3Strlen30(sqlite3_errmsg(db));
95011     *pzErrMsg = sqlite3Malloc(nErrMsg);
95012     if( *pzErrMsg ){
95013       memcpy(*pzErrMsg, sqlite3_errmsg(db), nErrMsg);
95014     }else{
95015       rc = SQLITE_NOMEM;
95016       sqlite3Error(db, SQLITE_NOMEM, 0);
95017     }
95018   }else if( pzErrMsg ){
95019     *pzErrMsg = 0;
95020   }
95021 
95022   assert( (rc&db->errMask)==rc );
95023   sqlite3_mutex_leave(db->mutex);
95024   return rc;
95025 }
95026 
95027 /************** End of legacy.c **********************************************/
95028 /************** Begin file loadext.c *****************************************/
95029 /*
95030 ** 2006 June 7
95031 **
95032 ** The author disclaims copyright to this source code.  In place of
95033 ** a legal notice, here is a blessing:
95034 **
95035 **    May you do good and not evil.
95036 **    May you find forgiveness for yourself and forgive others.
95037 **    May you share freely, never taking more than you give.
95038 **
95039 *************************************************************************
95040 ** This file contains code used to dynamically load extensions into
95041 ** the SQLite library.
95042 */
95043 
95044 #ifndef SQLITE_CORE
95045   #define SQLITE_CORE 1  /* Disable the API redefinition in sqlite3ext.h */
95046 #endif
95047 /************** Include sqlite3ext.h in the middle of loadext.c **************/
95048 /************** Begin file sqlite3ext.h **************************************/
95049 /*
95050 ** 2006 June 7
95051 **
95052 ** The author disclaims copyright to this source code.  In place of
95053 ** a legal notice, here is a blessing:
95054 **
95055 **    May you do good and not evil.
95056 **    May you find forgiveness for yourself and forgive others.
95057 **    May you share freely, never taking more than you give.
95058 **
95059 *************************************************************************
95060 ** This header file defines the SQLite interface for use by
95061 ** shared libraries that want to be imported as extensions into
95062 ** an SQLite instance.  Shared libraries that intend to be loaded
95063 ** as extensions by SQLite should #include this file instead of 
95064 ** sqlite3.h.
95065 */
95066 #ifndef _SQLITE3EXT_H_
95067 #define _SQLITE3EXT_H_
95068 
95069 typedef struct sqlite3_api_routines sqlite3_api_routines;
95070 
95071 /*
95072 ** The following structure holds pointers to all of the SQLite API
95073 ** routines.
95074 **
95075 ** WARNING:  In order to maintain backwards compatibility, add new
95076 ** interfaces to the end of this structure only.  If you insert new
95077 ** interfaces in the middle of this structure, then older different
95078 ** versions of SQLite will not be able to load each others' shared
95079 ** libraries!
95080 */
95081 struct sqlite3_api_routines {
95082   void * (*aggregate_context)(sqlite3_context*,int nBytes);
95083   int  (*aggregate_count)(sqlite3_context*);
95084   int  (*bind_blob)(sqlite3_stmt*,int,const void*,int n,void(*)(void*));
95085   int  (*bind_double)(sqlite3_stmt*,int,double);
95086   int  (*bind_int)(sqlite3_stmt*,int,int);
95087   int  (*bind_int64)(sqlite3_stmt*,int,sqlite_int64);
95088   int  (*bind_null)(sqlite3_stmt*,int);
95089   int  (*bind_parameter_count)(sqlite3_stmt*);
95090   int  (*bind_parameter_index)(sqlite3_stmt*,const char*zName);
95091   const char * (*bind_parameter_name)(sqlite3_stmt*,int);
95092   int  (*bind_text)(sqlite3_stmt*,int,const char*,int n,void(*)(void*));
95093   int  (*bind_text16)(sqlite3_stmt*,int,const void*,int,void(*)(void*));
95094   int  (*bind_value)(sqlite3_stmt*,int,const sqlite3_value*);
95095   int  (*busy_handler)(sqlite3*,int(*)(void*,int),void*);
95096   int  (*busy_timeout)(sqlite3*,int ms);
95097   int  (*changes)(sqlite3*);
95098   int  (*close)(sqlite3*);
95099   int  (*collation_needed)(sqlite3*,void*,void(*)(void*,sqlite3*,
95100                            int eTextRep,const char*));
95101   int  (*collation_needed16)(sqlite3*,void*,void(*)(void*,sqlite3*,
95102                              int eTextRep,const void*));
95103   const void * (*column_blob)(sqlite3_stmt*,int iCol);
95104   int  (*column_bytes)(sqlite3_stmt*,int iCol);
95105   int  (*column_bytes16)(sqlite3_stmt*,int iCol);
95106   int  (*column_count)(sqlite3_stmt*pStmt);
95107   const char * (*column_database_name)(sqlite3_stmt*,int);
95108   const void * (*column_database_name16)(sqlite3_stmt*,int);
95109   const char * (*column_decltype)(sqlite3_stmt*,int i);
95110   const void * (*column_decltype16)(sqlite3_stmt*,int);
95111   double  (*column_double)(sqlite3_stmt*,int iCol);
95112   int  (*column_int)(sqlite3_stmt*,int iCol);
95113   sqlite_int64  (*column_int64)(sqlite3_stmt*,int iCol);
95114   const char * (*column_name)(sqlite3_stmt*,int);
95115   const void * (*column_name16)(sqlite3_stmt*,int);
95116   const char * (*column_origin_name)(sqlite3_stmt*,int);
95117   const void * (*column_origin_name16)(sqlite3_stmt*,int);
95118   const char * (*column_table_name)(sqlite3_stmt*,int);
95119   const void * (*column_table_name16)(sqlite3_stmt*,int);
95120   const unsigned char * (*column_text)(sqlite3_stmt*,int iCol);
95121   const void * (*column_text16)(sqlite3_stmt*,int iCol);
95122   int  (*column_type)(sqlite3_stmt*,int iCol);
95123   sqlite3_value* (*column_value)(sqlite3_stmt*,int iCol);
95124   void * (*commit_hook)(sqlite3*,int(*)(void*),void*);
95125   int  (*complete)(const char*sql);
95126   int  (*complete16)(const void*sql);
95127   int  (*create_collation)(sqlite3*,const char*,int,void*,
95128                            int(*)(void*,int,const void*,int,const void*));
95129   int  (*create_collation16)(sqlite3*,const void*,int,void*,
95130                              int(*)(void*,int,const void*,int,const void*));
95131   int  (*create_function)(sqlite3*,const char*,int,int,void*,
95132                           void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
95133                           void (*xStep)(sqlite3_context*,int,sqlite3_value**),
95134                           void (*xFinal)(sqlite3_context*));
95135   int  (*create_function16)(sqlite3*,const void*,int,int,void*,
95136                             void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
95137                             void (*xStep)(sqlite3_context*,int,sqlite3_value**),
95138                             void (*xFinal)(sqlite3_context*));
95139   int (*create_module)(sqlite3*,const char*,const sqlite3_module*,void*);
95140   int  (*data_count)(sqlite3_stmt*pStmt);
95141   sqlite3 * (*db_handle)(sqlite3_stmt*);
95142   int (*declare_vtab)(sqlite3*,const char*);
95143   int  (*enable_shared_cache)(int);
95144   int  (*errcode)(sqlite3*db);
95145   const char * (*errmsg)(sqlite3*);
95146   const void * (*errmsg16)(sqlite3*);
95147   int  (*exec)(sqlite3*,const char*,sqlite3_callback,void*,char**);
95148   int  (*expired)(sqlite3_stmt*);
95149   int  (*finalize)(sqlite3_stmt*pStmt);
95150   void  (*free)(void*);
95151   void  (*free_table)(char**result);
95152   int  (*get_autocommit)(sqlite3*);
95153   void * (*get_auxdata)(sqlite3_context*,int);
95154   int  (*get_table)(sqlite3*,const char*,char***,int*,int*,char**);
95155   int  (*global_recover)(void);
95156   void  (*interruptx)(sqlite3*);
95157   sqlite_int64  (*last_insert_rowid)(sqlite3*);
95158   const char * (*libversion)(void);
95159   int  (*libversion_number)(void);
95160   void *(*malloc)(int);
95161   char * (*mprintf)(const char*,...);
95162   int  (*open)(const char*,sqlite3**);
95163   int  (*open16)(const void*,sqlite3**);
95164   int  (*prepare)(sqlite3*,const char*,int,sqlite3_stmt**,const char**);
95165   int  (*prepare16)(sqlite3*,const void*,int,sqlite3_stmt**,const void**);
95166   void * (*profile)(sqlite3*,void(*)(void*,const char*,sqlite_uint64),void*);
95167   void  (*progress_handler)(sqlite3*,int,int(*)(void*),void*);
95168   void *(*realloc)(void*,int);
95169   int  (*reset)(sqlite3_stmt*pStmt);
95170   void  (*result_blob)(sqlite3_context*,const void*,int,void(*)(void*));
95171   void  (*result_double)(sqlite3_context*,double);
95172   void  (*result_error)(sqlite3_context*,const char*,int);
95173   void  (*result_error16)(sqlite3_context*,const void*,int);
95174   void  (*result_int)(sqlite3_context*,int);
95175   void  (*result_int64)(sqlite3_context*,sqlite_int64);
95176   void  (*result_null)(sqlite3_context*);
95177   void  (*result_text)(sqlite3_context*,const char*,int,void(*)(void*));
95178   void  (*result_text16)(sqlite3_context*,const void*,int,void(*)(void*));
95179   void  (*result_text16be)(sqlite3_context*,const void*,int,void(*)(void*));
95180   void  (*result_text16le)(sqlite3_context*,const void*,int,void(*)(void*));
95181   void  (*result_value)(sqlite3_context*,sqlite3_value*);
95182   void * (*rollback_hook)(sqlite3*,void(*)(void*),void*);
95183   int  (*set_authorizer)(sqlite3*,int(*)(void*,int,const char*,const char*,
95184                          const char*,const char*),void*);
95185   void  (*set_auxdata)(sqlite3_context*,int,void*,void (*)(void*));
95186   char * (*snprintf)(int,char*,const char*,...);
95187   int  (*step)(sqlite3_stmt*);
95188   int  (*table_column_metadata)(sqlite3*,const char*,const char*,const char*,
95189                                 char const**,char const**,int*,int*,int*);
95190   void  (*thread_cleanup)(void);
95191   int  (*total_changes)(sqlite3*);
95192   void * (*trace)(sqlite3*,void(*xTrace)(void*,const char*),void*);
95193   int  (*transfer_bindings)(sqlite3_stmt*,sqlite3_stmt*);
95194   void * (*update_hook)(sqlite3*,void(*)(void*,int ,char const*,char const*,
95195                                          sqlite_int64),void*);
95196   void * (*user_data)(sqlite3_context*);
95197   const void * (*value_blob)(sqlite3_value*);
95198   int  (*value_bytes)(sqlite3_value*);
95199   int  (*value_bytes16)(sqlite3_value*);
95200   double  (*value_double)(sqlite3_value*);
95201   int  (*value_int)(sqlite3_value*);
95202   sqlite_int64  (*value_int64)(sqlite3_value*);
95203   int  (*value_numeric_type)(sqlite3_value*);
95204   const unsigned char * (*value_text)(sqlite3_value*);
95205   const void * (*value_text16)(sqlite3_value*);
95206   const void * (*value_text16be)(sqlite3_value*);
95207   const void * (*value_text16le)(sqlite3_value*);
95208   int  (*value_type)(sqlite3_value*);
95209   char *(*vmprintf)(const char*,va_list);
95210   /* Added ??? */
95211   int (*overload_function)(sqlite3*, const char *zFuncName, int nArg);
95212   /* Added by 3.3.13 */
95213   int (*prepare_v2)(sqlite3*,const char*,int,sqlite3_stmt**,const char**);
95214   int (*prepare16_v2)(sqlite3*,const void*,int,sqlite3_stmt**,const void**);
95215   int (*clear_bindings)(sqlite3_stmt*);
95216   /* Added by 3.4.1 */
95217   int (*create_module_v2)(sqlite3*,const char*,const sqlite3_module*,void*,
95218                           void (*xDestroy)(void *));
95219   /* Added by 3.5.0 */
95220   int (*bind_zeroblob)(sqlite3_stmt*,int,int);
95221   int (*blob_bytes)(sqlite3_blob*);
95222   int (*blob_close)(sqlite3_blob*);
95223   int (*blob_open)(sqlite3*,const char*,const char*,const char*,sqlite3_int64,
95224                    int,sqlite3_blob**);
95225   int (*blob_read)(sqlite3_blob*,void*,int,int);
95226   int (*blob_write)(sqlite3_blob*,const void*,int,int);
95227   int (*create_collation_v2)(sqlite3*,const char*,int,void*,
95228                              int(*)(void*,int,const void*,int,const void*),
95229                              void(*)(void*));
95230   int (*file_control)(sqlite3*,const char*,int,void*);
95231   sqlite3_int64 (*memory_highwater)(int);
95232   sqlite3_int64 (*memory_used)(void);
95233   sqlite3_mutex *(*mutex_alloc)(int);
95234   void (*mutex_enter)(sqlite3_mutex*);
95235   void (*mutex_free)(sqlite3_mutex*);
95236   void (*mutex_leave)(sqlite3_mutex*);
95237   int (*mutex_try)(sqlite3_mutex*);
95238   int (*open_v2)(const char*,sqlite3**,int,const char*);
95239   int (*release_memory)(int);
95240   void (*result_error_nomem)(sqlite3_context*);
95241   void (*result_error_toobig)(sqlite3_context*);
95242   int (*sleep)(int);
95243   void (*soft_heap_limit)(int);
95244   sqlite3_vfs *(*vfs_find)(const char*);
95245   int (*vfs_register)(sqlite3_vfs*,int);
95246   int (*vfs_unregister)(sqlite3_vfs*);
95247   int (*xthreadsafe)(void);
95248   void (*result_zeroblob)(sqlite3_context*,int);
95249   void (*result_error_code)(sqlite3_context*,int);
95250   int (*test_control)(int, ...);
95251   void (*randomness)(int,void*);
95252   sqlite3 *(*context_db_handle)(sqlite3_context*);
95253   int (*extended_result_codes)(sqlite3*,int);
95254   int (*limit)(sqlite3*,int,int);
95255   sqlite3_stmt *(*next_stmt)(sqlite3*,sqlite3_stmt*);
95256   const char *(*sql)(sqlite3_stmt*);
95257   int (*status)(int,int*,int*,int);
95258   int (*backup_finish)(sqlite3_backup*);
95259   sqlite3_backup *(*backup_init)(sqlite3*,const char*,sqlite3*,const char*);
95260   int (*backup_pagecount)(sqlite3_backup*);
95261   int (*backup_remaining)(sqlite3_backup*);
95262   int (*backup_step)(sqlite3_backup*,int);
95263   const char *(*compileoption_get)(int);
95264   int (*compileoption_used)(const char*);
95265   int (*create_function_v2)(sqlite3*,const char*,int,int,void*,
95266                             void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
95267                             void (*xStep)(sqlite3_context*,int,sqlite3_value**),
95268                             void (*xFinal)(sqlite3_context*),
95269                             void(*xDestroy)(void*));
95270   int (*db_config)(sqlite3*,int,...);
95271   sqlite3_mutex *(*db_mutex)(sqlite3*);
95272   int (*db_status)(sqlite3*,int,int*,int*,int);
95273   int (*extended_errcode)(sqlite3*);
95274   void (*log)(int,const char*,...);
95275   sqlite3_int64 (*soft_heap_limit64)(sqlite3_int64);
95276   const char *(*sourceid)(void);
95277   int (*stmt_status)(sqlite3_stmt*,int,int);
95278   int (*strnicmp)(const char*,const char*,int);
95279   int (*unlock_notify)(sqlite3*,void(*)(void**,int),void*);
95280   int (*wal_autocheckpoint)(sqlite3*,int);
95281   int (*wal_checkpoint)(sqlite3*,const char*);
95282   void *(*wal_hook)(sqlite3*,int(*)(void*,sqlite3*,const char*,int),void*);
95283   int (*blob_reopen)(sqlite3_blob*,sqlite3_int64);
95284   int (*vtab_config)(sqlite3*,int op,...);
95285   int (*vtab_on_conflict)(sqlite3*);
95286   /* Version 3.7.16 and later */
95287   int (*close_v2)(sqlite3*);
95288   const char *(*db_filename)(sqlite3*,const char*);
95289   int (*db_readonly)(sqlite3*,const char*);
95290   int (*db_release_memory)(sqlite3*);
95291   const char *(*errstr)(int);
95292   int (*stmt_busy)(sqlite3_stmt*);
95293   int (*stmt_readonly)(sqlite3_stmt*);
95294   int (*stricmp)(const char*,const char*);
95295   int (*uri_boolean)(const char*,const char*,int);
95296   sqlite3_int64 (*uri_int64)(const char*,const char*,sqlite3_int64);
95297   const char *(*uri_parameter)(const char*,const char*);
95298   char *(*vsnprintf)(int,char*,const char*,va_list);
95299   int (*wal_checkpoint_v2)(sqlite3*,const char*,int,int*,int*);
95300 };
95301 
95302 /*
95303 ** The following macros redefine the API routines so that they are
95304 ** redirected throught the global sqlite3_api structure.
95305 **
95306 ** This header file is also used by the loadext.c source file
95307 ** (part of the main SQLite library - not an extension) so that
95308 ** it can get access to the sqlite3_api_routines structure
95309 ** definition.  But the main library does not want to redefine
95310 ** the API.  So the redefinition macros are only valid if the
95311 ** SQLITE_CORE macros is undefined.
95312 */
95313 #ifndef SQLITE_CORE
95314 #define sqlite3_aggregate_context      sqlite3_api->aggregate_context
95315 #ifndef SQLITE_OMIT_DEPRECATED
95316 #define sqlite3_aggregate_count        sqlite3_api->aggregate_count
95317 #endif
95318 #define sqlite3_bind_blob              sqlite3_api->bind_blob
95319 #define sqlite3_bind_double            sqlite3_api->bind_double
95320 #define sqlite3_bind_int               sqlite3_api->bind_int
95321 #define sqlite3_bind_int64             sqlite3_api->bind_int64
95322 #define sqlite3_bind_null              sqlite3_api->bind_null
95323 #define sqlite3_bind_parameter_count   sqlite3_api->bind_parameter_count
95324 #define sqlite3_bind_parameter_index   sqlite3_api->bind_parameter_index
95325 #define sqlite3_bind_parameter_name    sqlite3_api->bind_parameter_name
95326 #define sqlite3_bind_text              sqlite3_api->bind_text
95327 #define sqlite3_bind_text16            sqlite3_api->bind_text16
95328 #define sqlite3_bind_value             sqlite3_api->bind_value
95329 #define sqlite3_busy_handler           sqlite3_api->busy_handler
95330 #define sqlite3_busy_timeout           sqlite3_api->busy_timeout
95331 #define sqlite3_changes                sqlite3_api->changes
95332 #define sqlite3_close                  sqlite3_api->close
95333 #define sqlite3_collation_needed       sqlite3_api->collation_needed
95334 #define sqlite3_collation_needed16     sqlite3_api->collation_needed16
95335 #define sqlite3_column_blob            sqlite3_api->column_blob
95336 #define sqlite3_column_bytes           sqlite3_api->column_bytes
95337 #define sqlite3_column_bytes16         sqlite3_api->column_bytes16
95338 #define sqlite3_column_count           sqlite3_api->column_count
95339 #define sqlite3_column_database_name   sqlite3_api->column_database_name
95340 #define sqlite3_column_database_name16 sqlite3_api->column_database_name16
95341 #define sqlite3_column_decltype        sqlite3_api->column_decltype
95342 #define sqlite3_column_decltype16      sqlite3_api->column_decltype16
95343 #define sqlite3_column_double          sqlite3_api->column_double
95344 #define sqlite3_column_int             sqlite3_api->column_int
95345 #define sqlite3_column_int64           sqlite3_api->column_int64
95346 #define sqlite3_column_name            sqlite3_api->column_name
95347 #define sqlite3_column_name16          sqlite3_api->column_name16
95348 #define sqlite3_column_origin_name     sqlite3_api->column_origin_name
95349 #define sqlite3_column_origin_name16   sqlite3_api->column_origin_name16
95350 #define sqlite3_column_table_name      sqlite3_api->column_table_name
95351 #define sqlite3_column_table_name16    sqlite3_api->column_table_name16
95352 #define sqlite3_column_text            sqlite3_api->column_text
95353 #define sqlite3_column_text16          sqlite3_api->column_text16
95354 #define sqlite3_column_type            sqlite3_api->column_type
95355 #define sqlite3_column_value           sqlite3_api->column_value
95356 #define sqlite3_commit_hook            sqlite3_api->commit_hook
95357 #define sqlite3_complete               sqlite3_api->complete
95358 #define sqlite3_complete16             sqlite3_api->complete16
95359 #define sqlite3_create_collation       sqlite3_api->create_collation
95360 #define sqlite3_create_collation16     sqlite3_api->create_collation16
95361 #define sqlite3_create_function        sqlite3_api->create_function
95362 #define sqlite3_create_function16      sqlite3_api->create_function16
95363 #define sqlite3_create_module          sqlite3_api->create_module
95364 #define sqlite3_create_module_v2       sqlite3_api->create_module_v2
95365 #define sqlite3_data_count             sqlite3_api->data_count
95366 #define sqlite3_db_handle              sqlite3_api->db_handle
95367 #define sqlite3_declare_vtab           sqlite3_api->declare_vtab
95368 #define sqlite3_enable_shared_cache    sqlite3_api->enable_shared_cache
95369 #define sqlite3_errcode                sqlite3_api->errcode
95370 #define sqlite3_errmsg                 sqlite3_api->errmsg
95371 #define sqlite3_errmsg16               sqlite3_api->errmsg16
95372 #define sqlite3_exec                   sqlite3_api->exec
95373 #ifndef SQLITE_OMIT_DEPRECATED
95374 #define sqlite3_expired                sqlite3_api->expired
95375 #endif
95376 #define sqlite3_finalize               sqlite3_api->finalize
95377 #define sqlite3_free                   sqlite3_api->free
95378 #define sqlite3_free_table             sqlite3_api->free_table
95379 #define sqlite3_get_autocommit         sqlite3_api->get_autocommit
95380 #define sqlite3_get_auxdata            sqlite3_api->get_auxdata
95381 #define sqlite3_get_table              sqlite3_api->get_table
95382 #ifndef SQLITE_OMIT_DEPRECATED
95383 #define sqlite3_global_recover         sqlite3_api->global_recover
95384 #endif
95385 #define sqlite3_interrupt              sqlite3_api->interruptx
95386 #define sqlite3_last_insert_rowid      sqlite3_api->last_insert_rowid
95387 #define sqlite3_libversion             sqlite3_api->libversion
95388 #define sqlite3_libversion_number      sqlite3_api->libversion_number
95389 #define sqlite3_malloc                 sqlite3_api->malloc
95390 #define sqlite3_mprintf                sqlite3_api->mprintf
95391 #define sqlite3_open                   sqlite3_api->open
95392 #define sqlite3_open16                 sqlite3_api->open16
95393 #define sqlite3_prepare                sqlite3_api->prepare
95394 #define sqlite3_prepare16              sqlite3_api->prepare16
95395 #define sqlite3_prepare_v2             sqlite3_api->prepare_v2
95396 #define sqlite3_prepare16_v2           sqlite3_api->prepare16_v2
95397 #define sqlite3_profile                sqlite3_api->profile
95398 #define sqlite3_progress_handler       sqlite3_api->progress_handler
95399 #define sqlite3_realloc                sqlite3_api->realloc
95400 #define sqlite3_reset                  sqlite3_api->reset
95401 #define sqlite3_result_blob            sqlite3_api->result_blob
95402 #define sqlite3_result_double          sqlite3_api->result_double
95403 #define sqlite3_result_error           sqlite3_api->result_error
95404 #define sqlite3_result_error16         sqlite3_api->result_error16
95405 #define sqlite3_result_int             sqlite3_api->result_int
95406 #define sqlite3_result_int64           sqlite3_api->result_int64
95407 #define sqlite3_result_null            sqlite3_api->result_null
95408 #define sqlite3_result_text            sqlite3_api->result_text
95409 #define sqlite3_result_text16          sqlite3_api->result_text16
95410 #define sqlite3_result_text16be        sqlite3_api->result_text16be
95411 #define sqlite3_result_text16le        sqlite3_api->result_text16le
95412 #define sqlite3_result_value           sqlite3_api->result_value
95413 #define sqlite3_rollback_hook          sqlite3_api->rollback_hook
95414 #define sqlite3_set_authorizer         sqlite3_api->set_authorizer
95415 #define sqlite3_set_auxdata            sqlite3_api->set_auxdata
95416 #define sqlite3_snprintf               sqlite3_api->snprintf
95417 #define sqlite3_step                   sqlite3_api->step
95418 #define sqlite3_table_column_metadata  sqlite3_api->table_column_metadata
95419 #define sqlite3_thread_cleanup         sqlite3_api->thread_cleanup
95420 #define sqlite3_total_changes          sqlite3_api->total_changes
95421 #define sqlite3_trace                  sqlite3_api->trace
95422 #ifndef SQLITE_OMIT_DEPRECATED
95423 #define sqlite3_transfer_bindings      sqlite3_api->transfer_bindings
95424 #endif
95425 #define sqlite3_update_hook            sqlite3_api->update_hook
95426 #define sqlite3_user_data              sqlite3_api->user_data
95427 #define sqlite3_value_blob             sqlite3_api->value_blob
95428 #define sqlite3_value_bytes            sqlite3_api->value_bytes
95429 #define sqlite3_value_bytes16          sqlite3_api->value_bytes16
95430 #define sqlite3_value_double           sqlite3_api->value_double
95431 #define sqlite3_value_int              sqlite3_api->value_int
95432 #define sqlite3_value_int64            sqlite3_api->value_int64
95433 #define sqlite3_value_numeric_type     sqlite3_api->value_numeric_type
95434 #define sqlite3_value_text             sqlite3_api->value_text
95435 #define sqlite3_value_text16           sqlite3_api->value_text16
95436 #define sqlite3_value_text16be         sqlite3_api->value_text16be
95437 #define sqlite3_value_text16le         sqlite3_api->value_text16le
95438 #define sqlite3_value_type             sqlite3_api->value_type
95439 #define sqlite3_vmprintf               sqlite3_api->vmprintf
95440 #define sqlite3_overload_function      sqlite3_api->overload_function
95441 #define sqlite3_prepare_v2             sqlite3_api->prepare_v2
95442 #define sqlite3_prepare16_v2           sqlite3_api->prepare16_v2
95443 #define sqlite3_clear_bindings         sqlite3_api->clear_bindings
95444 #define sqlite3_bind_zeroblob          sqlite3_api->bind_zeroblob
95445 #define sqlite3_blob_bytes             sqlite3_api->blob_bytes
95446 #define sqlite3_blob_close             sqlite3_api->blob_close
95447 #define sqlite3_blob_open              sqlite3_api->blob_open
95448 #define sqlite3_blob_read              sqlite3_api->blob_read
95449 #define sqlite3_blob_write             sqlite3_api->blob_write
95450 #define sqlite3_create_collation_v2    sqlite3_api->create_collation_v2
95451 #define sqlite3_file_control           sqlite3_api->file_control
95452 #define sqlite3_memory_highwater       sqlite3_api->memory_highwater
95453 #define sqlite3_memory_used            sqlite3_api->memory_used
95454 #define sqlite3_mutex_alloc            sqlite3_api->mutex_alloc
95455 #define sqlite3_mutex_enter            sqlite3_api->mutex_enter
95456 #define sqlite3_mutex_free             sqlite3_api->mutex_free
95457 #define sqlite3_mutex_leave            sqlite3_api->mutex_leave
95458 #define sqlite3_mutex_try              sqlite3_api->mutex_try
95459 #define sqlite3_open_v2                sqlite3_api->open_v2
95460 #define sqlite3_release_memory         sqlite3_api->release_memory
95461 #define sqlite3_result_error_nomem     sqlite3_api->result_error_nomem
95462 #define sqlite3_result_error_toobig    sqlite3_api->result_error_toobig
95463 #define sqlite3_sleep                  sqlite3_api->sleep
95464 #define sqlite3_soft_heap_limit        sqlite3_api->soft_heap_limit
95465 #define sqlite3_vfs_find               sqlite3_api->vfs_find
95466 #define sqlite3_vfs_register           sqlite3_api->vfs_register
95467 #define sqlite3_vfs_unregister         sqlite3_api->vfs_unregister
95468 #define sqlite3_threadsafe             sqlite3_api->xthreadsafe
95469 #define sqlite3_result_zeroblob        sqlite3_api->result_zeroblob
95470 #define sqlite3_result_error_code      sqlite3_api->result_error_code
95471 #define sqlite3_test_control           sqlite3_api->test_control
95472 #define sqlite3_randomness             sqlite3_api->randomness
95473 #define sqlite3_context_db_handle      sqlite3_api->context_db_handle
95474 #define sqlite3_extended_result_codes  sqlite3_api->extended_result_codes
95475 #define sqlite3_limit                  sqlite3_api->limit
95476 #define sqlite3_next_stmt              sqlite3_api->next_stmt
95477 #define sqlite3_sql                    sqlite3_api->sql
95478 #define sqlite3_status                 sqlite3_api->status
95479 #define sqlite3_backup_finish          sqlite3_api->backup_finish
95480 #define sqlite3_backup_init            sqlite3_api->backup_init
95481 #define sqlite3_backup_pagecount       sqlite3_api->backup_pagecount
95482 #define sqlite3_backup_remaining       sqlite3_api->backup_remaining
95483 #define sqlite3_backup_step            sqlite3_api->backup_step
95484 #define sqlite3_compileoption_get      sqlite3_api->compileoption_get
95485 #define sqlite3_compileoption_used     sqlite3_api->compileoption_used
95486 #define sqlite3_create_function_v2     sqlite3_api->create_function_v2
95487 #define sqlite3_db_config              sqlite3_api->db_config
95488 #define sqlite3_db_mutex               sqlite3_api->db_mutex
95489 #define sqlite3_db_status              sqlite3_api->db_status
95490 #define sqlite3_extended_errcode       sqlite3_api->extended_errcode
95491 #define sqlite3_log                    sqlite3_api->log
95492 #define sqlite3_soft_heap_limit64      sqlite3_api->soft_heap_limit64
95493 #define sqlite3_sourceid               sqlite3_api->sourceid
95494 #define sqlite3_stmt_status            sqlite3_api->stmt_status
95495 #define sqlite3_strnicmp               sqlite3_api->strnicmp
95496 #define sqlite3_unlock_notify          sqlite3_api->unlock_notify
95497 #define sqlite3_wal_autocheckpoint     sqlite3_api->wal_autocheckpoint
95498 #define sqlite3_wal_checkpoint         sqlite3_api->wal_checkpoint
95499 #define sqlite3_wal_hook               sqlite3_api->wal_hook
95500 #define sqlite3_blob_reopen            sqlite3_api->blob_reopen
95501 #define sqlite3_vtab_config            sqlite3_api->vtab_config
95502 #define sqlite3_vtab_on_conflict       sqlite3_api->vtab_on_conflict
95503 /* Version 3.7.16 and later */
95504 #define sqlite3_close_v2               sqlite3_api->close_v2
95505 #define sqlite3_db_filename            sqlite3_api->db_filename
95506 #define sqlite3_db_readonly            sqlite3_api->db_readonly
95507 #define sqlite3_db_release_memory      sqlite3_api->db_release_memory
95508 #define sqlite3_errstr                 sqlite3_api->errstr
95509 #define sqlite3_stmt_busy              sqlite3_api->stmt_busy
95510 #define sqlite3_stmt_readonly          sqlite3_api->stmt_readonly
95511 #define sqlite3_stricmp                sqlite3_api->stricmp
95512 #define sqlite3_uri_boolean            sqlite3_api->uri_boolean
95513 #define sqlite3_uri_int64              sqlite3_api->uri_int64
95514 #define sqlite3_uri_parameter          sqlite3_api->uri_parameter
95515 #define sqlite3_uri_vsnprintf          sqlite3_api->vsnprintf
95516 #define sqlite3_wal_checkpoint_v2      sqlite3_api->wal_checkpoint_v2
95517 #endif /* SQLITE_CORE */
95518 
95519 #ifndef SQLITE_CORE
95520   /* This case when the file really is being compiled as a loadable 
95521   ** extension */
95522 # define SQLITE_EXTENSION_INIT1     const sqlite3_api_routines *sqlite3_api=0;
95523 # define SQLITE_EXTENSION_INIT2(v)  sqlite3_api=v;
95524 # define SQLITE_EXTENSION_INIT3     \
95525     extern const sqlite3_api_routines *sqlite3_api;
95526 #else
95527   /* This case when the file is being statically linked into the 
95528   ** application */
95529 # define SQLITE_EXTENSION_INIT1     /*no-op*/
95530 # define SQLITE_EXTENSION_INIT2(v)  (void)v; /* unused parameter */
95531 # define SQLITE_EXTENSION_INIT3     /*no-op*/
95532 #endif
95533 
95534 #endif /* _SQLITE3EXT_H_ */
95535 
95536 /************** End of sqlite3ext.h ******************************************/
95537 /************** Continuing where we left off in loadext.c ********************/
95538 /* #include <string.h> */
95539 
95540 #ifndef SQLITE_OMIT_LOAD_EXTENSION
95541 
95542 /*
95543 ** Some API routines are omitted when various features are
95544 ** excluded from a build of SQLite.  Substitute a NULL pointer
95545 ** for any missing APIs.
95546 */
95547 #ifndef SQLITE_ENABLE_COLUMN_METADATA
95548 # define sqlite3_column_database_name   0
95549 # define sqlite3_column_database_name16 0
95550 # define sqlite3_column_table_name      0
95551 # define sqlite3_column_table_name16    0
95552 # define sqlite3_column_origin_name     0
95553 # define sqlite3_column_origin_name16   0
95554 # define sqlite3_table_column_metadata  0
95555 #endif
95556 
95557 #ifdef SQLITE_OMIT_AUTHORIZATION
95558 # define sqlite3_set_authorizer         0
95559 #endif
95560 
95561 #ifdef SQLITE_OMIT_UTF16
95562 # define sqlite3_bind_text16            0
95563 # define sqlite3_collation_needed16     0
95564 # define sqlite3_column_decltype16      0
95565 # define sqlite3_column_name16          0
95566 # define sqlite3_column_text16          0
95567 # define sqlite3_complete16             0
95568 # define sqlite3_create_collation16     0
95569 # define sqlite3_create_function16      0
95570 # define sqlite3_errmsg16               0
95571 # define sqlite3_open16                 0
95572 # define sqlite3_prepare16              0
95573 # define sqlite3_prepare16_v2           0
95574 # define sqlite3_result_error16         0
95575 # define sqlite3_result_text16          0
95576 # define sqlite3_result_text16be        0
95577 # define sqlite3_result_text16le        0
95578 # define sqlite3_value_text16           0
95579 # define sqlite3_value_text16be         0
95580 # define sqlite3_value_text16le         0
95581 # define sqlite3_column_database_name16 0
95582 # define sqlite3_column_table_name16    0
95583 # define sqlite3_column_origin_name16   0
95584 #endif
95585 
95586 #ifdef SQLITE_OMIT_COMPLETE
95587 # define sqlite3_complete 0
95588 # define sqlite3_complete16 0
95589 #endif
95590 
95591 #ifdef SQLITE_OMIT_DECLTYPE
95592 # define sqlite3_column_decltype16      0
95593 # define sqlite3_column_decltype        0
95594 #endif
95595 
95596 #ifdef SQLITE_OMIT_PROGRESS_CALLBACK
95597 # define sqlite3_progress_handler 0
95598 #endif
95599 
95600 #ifdef SQLITE_OMIT_VIRTUALTABLE
95601 # define sqlite3_create_module 0
95602 # define sqlite3_create_module_v2 0
95603 # define sqlite3_declare_vtab 0
95604 # define sqlite3_vtab_config 0
95605 # define sqlite3_vtab_on_conflict 0
95606 #endif
95607 
95608 #ifdef SQLITE_OMIT_SHARED_CACHE
95609 # define sqlite3_enable_shared_cache 0
95610 #endif
95611 
95612 #ifdef SQLITE_OMIT_TRACE
95613 # define sqlite3_profile       0
95614 # define sqlite3_trace         0
95615 #endif
95616 
95617 #ifdef SQLITE_OMIT_GET_TABLE
95618 # define sqlite3_free_table    0
95619 # define sqlite3_get_table     0
95620 #endif
95621 
95622 #ifdef SQLITE_OMIT_INCRBLOB
95623 #define sqlite3_bind_zeroblob  0
95624 #define sqlite3_blob_bytes     0
95625 #define sqlite3_blob_close     0
95626 #define sqlite3_blob_open      0
95627 #define sqlite3_blob_read      0
95628 #define sqlite3_blob_write     0
95629 #define sqlite3_blob_reopen    0
95630 #endif
95631 
95632 /*
95633 ** The following structure contains pointers to all SQLite API routines.
95634 ** A pointer to this structure is passed into extensions when they are
95635 ** loaded so that the extension can make calls back into the SQLite
95636 ** library.
95637 **
95638 ** When adding new APIs, add them to the bottom of this structure
95639 ** in order to preserve backwards compatibility.
95640 **
95641 ** Extensions that use newer APIs should first call the
95642 ** sqlite3_libversion_number() to make sure that the API they
95643 ** intend to use is supported by the library.  Extensions should
95644 ** also check to make sure that the pointer to the function is
95645 ** not NULL before calling it.
95646 */
95647 static const sqlite3_api_routines sqlite3Apis = {
95648   sqlite3_aggregate_context,
95649 #ifndef SQLITE_OMIT_DEPRECATED
95650   sqlite3_aggregate_count,
95651 #else
95652   0,
95653 #endif
95654   sqlite3_bind_blob,
95655   sqlite3_bind_double,
95656   sqlite3_bind_int,
95657   sqlite3_bind_int64,
95658   sqlite3_bind_null,
95659   sqlite3_bind_parameter_count,
95660   sqlite3_bind_parameter_index,
95661   sqlite3_bind_parameter_name,
95662   sqlite3_bind_text,
95663   sqlite3_bind_text16,
95664   sqlite3_bind_value,
95665   sqlite3_busy_handler,
95666   sqlite3_busy_timeout,
95667   sqlite3_changes,
95668   sqlite3_close,
95669   sqlite3_collation_needed,
95670   sqlite3_collation_needed16,
95671   sqlite3_column_blob,
95672   sqlite3_column_bytes,
95673   sqlite3_column_bytes16,
95674   sqlite3_column_count,
95675   sqlite3_column_database_name,
95676   sqlite3_column_database_name16,
95677   sqlite3_column_decltype,
95678   sqlite3_column_decltype16,
95679   sqlite3_column_double,
95680   sqlite3_column_int,
95681   sqlite3_column_int64,
95682   sqlite3_column_name,
95683   sqlite3_column_name16,
95684   sqlite3_column_origin_name,
95685   sqlite3_column_origin_name16,
95686   sqlite3_column_table_name,
95687   sqlite3_column_table_name16,
95688   sqlite3_column_text,
95689   sqlite3_column_text16,
95690   sqlite3_column_type,
95691   sqlite3_column_value,
95692   sqlite3_commit_hook,
95693   sqlite3_complete,
95694   sqlite3_complete16,
95695   sqlite3_create_collation,
95696   sqlite3_create_collation16,
95697   sqlite3_create_function,
95698   sqlite3_create_function16,
95699   sqlite3_create_module,
95700   sqlite3_data_count,
95701   sqlite3_db_handle,
95702   sqlite3_declare_vtab,
95703   sqlite3_enable_shared_cache,
95704   sqlite3_errcode,
95705   sqlite3_errmsg,
95706   sqlite3_errmsg16,
95707   sqlite3_exec,
95708 #ifndef SQLITE_OMIT_DEPRECATED
95709   sqlite3_expired,
95710 #else
95711   0,
95712 #endif
95713   sqlite3_finalize,
95714   sqlite3_free,
95715   sqlite3_free_table,
95716   sqlite3_get_autocommit,
95717   sqlite3_get_auxdata,
95718   sqlite3_get_table,
95719   0,     /* Was sqlite3_global_recover(), but that function is deprecated */
95720   sqlite3_interrupt,
95721   sqlite3_last_insert_rowid,
95722   sqlite3_libversion,
95723   sqlite3_libversion_number,
95724   sqlite3_malloc,
95725   sqlite3_mprintf,
95726   sqlite3_open,
95727   sqlite3_open16,
95728   sqlite3_prepare,
95729   sqlite3_prepare16,
95730   sqlite3_profile,
95731   sqlite3_progress_handler,
95732   sqlite3_realloc,
95733   sqlite3_reset,
95734   sqlite3_result_blob,
95735   sqlite3_result_double,
95736   sqlite3_result_error,
95737   sqlite3_result_error16,
95738   sqlite3_result_int,
95739   sqlite3_result_int64,
95740   sqlite3_result_null,
95741   sqlite3_result_text,
95742   sqlite3_result_text16,
95743   sqlite3_result_text16be,
95744   sqlite3_result_text16le,
95745   sqlite3_result_value,
95746   sqlite3_rollback_hook,
95747   sqlite3_set_authorizer,
95748   sqlite3_set_auxdata,
95749   sqlite3_snprintf,
95750   sqlite3_step,
95751   sqlite3_table_column_metadata,
95752 #ifndef SQLITE_OMIT_DEPRECATED
95753   sqlite3_thread_cleanup,
95754 #else
95755   0,
95756 #endif
95757   sqlite3_total_changes,
95758   sqlite3_trace,
95759 #ifndef SQLITE_OMIT_DEPRECATED
95760   sqlite3_transfer_bindings,
95761 #else
95762   0,
95763 #endif
95764   sqlite3_update_hook,
95765   sqlite3_user_data,
95766   sqlite3_value_blob,
95767   sqlite3_value_bytes,
95768   sqlite3_value_bytes16,
95769   sqlite3_value_double,
95770   sqlite3_value_int,
95771   sqlite3_value_int64,
95772   sqlite3_value_numeric_type,
95773   sqlite3_value_text,
95774   sqlite3_value_text16,
95775   sqlite3_value_text16be,
95776   sqlite3_value_text16le,
95777   sqlite3_value_type,
95778   sqlite3_vmprintf,
95779   /*
95780   ** The original API set ends here.  All extensions can call any
95781   ** of the APIs above provided that the pointer is not NULL.  But
95782   ** before calling APIs that follow, extension should check the
95783   ** sqlite3_libversion_number() to make sure they are dealing with
95784   ** a library that is new enough to support that API.
95785   *************************************************************************
95786   */
95787   sqlite3_overload_function,
95788 
95789   /*
95790   ** Added after 3.3.13
95791   */
95792   sqlite3_prepare_v2,
95793   sqlite3_prepare16_v2,
95794   sqlite3_clear_bindings,
95795 
95796   /*
95797   ** Added for 3.4.1
95798   */
95799   sqlite3_create_module_v2,
95800 
95801   /*
95802   ** Added for 3.5.0
95803   */
95804   sqlite3_bind_zeroblob,
95805   sqlite3_blob_bytes,
95806   sqlite3_blob_close,
95807   sqlite3_blob_open,
95808   sqlite3_blob_read,
95809   sqlite3_blob_write,
95810   sqlite3_create_collation_v2,
95811   sqlite3_file_control,
95812   sqlite3_memory_highwater,
95813   sqlite3_memory_used,
95814 #ifdef SQLITE_MUTEX_OMIT
95815   0, 
95816   0, 
95817   0,
95818   0,
95819   0,
95820 #else
95821   sqlite3_mutex_alloc,
95822   sqlite3_mutex_enter,
95823   sqlite3_mutex_free,
95824   sqlite3_mutex_leave,
95825   sqlite3_mutex_try,
95826 #endif
95827   sqlite3_open_v2,
95828   sqlite3_release_memory,
95829   sqlite3_result_error_nomem,
95830   sqlite3_result_error_toobig,
95831   sqlite3_sleep,
95832   sqlite3_soft_heap_limit,
95833   sqlite3_vfs_find,
95834   sqlite3_vfs_register,
95835   sqlite3_vfs_unregister,
95836 
95837   /*
95838   ** Added for 3.5.8
95839   */
95840   sqlite3_threadsafe,
95841   sqlite3_result_zeroblob,
95842   sqlite3_result_error_code,
95843   sqlite3_test_control,
95844   sqlite3_randomness,
95845   sqlite3_context_db_handle,
95846 
95847   /*
95848   ** Added for 3.6.0
95849   */
95850   sqlite3_extended_result_codes,
95851   sqlite3_limit,
95852   sqlite3_next_stmt,
95853   sqlite3_sql,
95854   sqlite3_status,
95855 
95856   /*
95857   ** Added for 3.7.4
95858   */
95859   sqlite3_backup_finish,
95860   sqlite3_backup_init,
95861   sqlite3_backup_pagecount,
95862   sqlite3_backup_remaining,
95863   sqlite3_backup_step,
95864 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
95865   sqlite3_compileoption_get,
95866   sqlite3_compileoption_used,
95867 #else
95868   0,
95869   0,
95870 #endif
95871   sqlite3_create_function_v2,
95872   sqlite3_db_config,
95873   sqlite3_db_mutex,
95874   sqlite3_db_status,
95875   sqlite3_extended_errcode,
95876   sqlite3_log,
95877   sqlite3_soft_heap_limit64,
95878   sqlite3_sourceid,
95879   sqlite3_stmt_status,
95880   sqlite3_strnicmp,
95881 #ifdef SQLITE_ENABLE_UNLOCK_NOTIFY
95882   sqlite3_unlock_notify,
95883 #else
95884   0,
95885 #endif
95886 #ifndef SQLITE_OMIT_WAL
95887   sqlite3_wal_autocheckpoint,
95888   sqlite3_wal_checkpoint,
95889   sqlite3_wal_hook,
95890 #else
95891   0,
95892   0,
95893   0,
95894 #endif
95895   sqlite3_blob_reopen,
95896   sqlite3_vtab_config,
95897   sqlite3_vtab_on_conflict,
95898   sqlite3_close_v2,
95899   sqlite3_db_filename,
95900   sqlite3_db_readonly,
95901   sqlite3_db_release_memory,
95902   sqlite3_errstr,
95903   sqlite3_stmt_busy,
95904   sqlite3_stmt_readonly,
95905   sqlite3_stricmp,
95906   sqlite3_uri_boolean,
95907   sqlite3_uri_int64,
95908   sqlite3_uri_parameter,
95909   sqlite3_vsnprintf,
95910   sqlite3_wal_checkpoint_v2
95911 };
95912 
95913 /*
95914 ** Attempt to load an SQLite extension library contained in the file
95915 ** zFile.  The entry point is zProc.  zProc may be 0 in which case a
95916 ** default entry point name (sqlite3_extension_init) is used.  Use
95917 ** of the default name is recommended.
95918 **
95919 ** Return SQLITE_OK on success and SQLITE_ERROR if something goes wrong.
95920 **
95921 ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with 
95922 ** error message text.  The calling function should free this memory
95923 ** by calling sqlite3DbFree(db, ).
95924 */
95925 static int sqlite3LoadExtension(
95926   sqlite3 *db,          /* Load the extension into this database connection */
95927   const char *zFile,    /* Name of the shared library containing extension */
95928   const char *zProc,    /* Entry point.  Use "sqlite3_extension_init" if 0 */
95929   char **pzErrMsg       /* Put error message here if not 0 */
95930 ){
95931   sqlite3_vfs *pVfs = db->pVfs;
95932   void *handle;
95933   int (*xInit)(sqlite3*,char**,const sqlite3_api_routines*);
95934   char *zErrmsg = 0;
95935   const char *zEntry;
95936   char *zAltEntry = 0;
95937   void **aHandle;
95938   int nMsg = 300 + sqlite3Strlen30(zFile);
95939   int ii;
95940 
95941   /* Shared library endings to try if zFile cannot be loaded as written */
95942   static const char *azEndings[] = {
95943 #if SQLITE_OS_WIN
95944      "dll"   
95945 #elif defined(__APPLE__)
95946      "dylib"
95947 #else
95948      "so"
95949 #endif
95950   };
95951 
95952 
95953   if( pzErrMsg ) *pzErrMsg = 0;
95954 
95955   /* Ticket #1863.  To avoid a creating security problems for older
95956   ** applications that relink against newer versions of SQLite, the
95957   ** ability to run load_extension is turned off by default.  One
95958   ** must call sqlite3_enable_load_extension() to turn on extension
95959   ** loading.  Otherwise you get the following error.
95960   */
95961   if( (db->flags & SQLITE_LoadExtension)==0 ){
95962     if( pzErrMsg ){
95963       *pzErrMsg = sqlite3_mprintf("not authorized");
95964     }
95965     return SQLITE_ERROR;
95966   }
95967 
95968   zEntry = zProc ? zProc : "sqlite3_extension_init";
95969 
95970   handle = sqlite3OsDlOpen(pVfs, zFile);
95971 #if SQLITE_OS_UNIX || SQLITE_OS_WIN
95972   for(ii=0; ii<ArraySize(azEndings) && handle==0; ii++){
95973     char *zAltFile = sqlite3_mprintf("%s.%s", zFile, azEndings[ii]);
95974     if( zAltFile==0 ) return SQLITE_NOMEM;
95975     handle = sqlite3OsDlOpen(pVfs, zAltFile);
95976     sqlite3_free(zAltFile);
95977   }
95978 #endif
95979   if( handle==0 ){
95980     if( pzErrMsg ){
95981       *pzErrMsg = zErrmsg = sqlite3_malloc(nMsg);
95982       if( zErrmsg ){
95983         sqlite3_snprintf(nMsg, zErrmsg, 
95984             "unable to open shared library [%s]", zFile);
95985         sqlite3OsDlError(pVfs, nMsg-1, zErrmsg);
95986       }
95987     }
95988     return SQLITE_ERROR;
95989   }
95990   xInit = (int(*)(sqlite3*,char**,const sqlite3_api_routines*))
95991                    sqlite3OsDlSym(pVfs, handle, zEntry);
95992 
95993   /* If no entry point was specified and the default legacy
95994   ** entry point name "sqlite3_extension_init" was not found, then
95995   ** construct an entry point name "sqlite3_X_init" where the X is
95996   ** replaced by the lowercase value of every ASCII alphabetic 
95997   ** character in the filename after the last "/" upto the first ".",
95998   ** and eliding the first three characters if they are "lib".  
95999   ** Examples:
96000   **
96001   **    /usr/local/lib/libExample5.4.3.so ==>  sqlite3_example_init
96002   **    C:/lib/mathfuncs.dll              ==>  sqlite3_mathfuncs_init
96003   */
96004   if( xInit==0 && zProc==0 ){
96005     int iFile, iEntry, c;
96006     int ncFile = sqlite3Strlen30(zFile);
96007     zAltEntry = sqlite3_malloc(ncFile+30);
96008     if( zAltEntry==0 ){
96009       sqlite3OsDlClose(pVfs, handle);
96010       return SQLITE_NOMEM;
96011     }
96012     memcpy(zAltEntry, "sqlite3_", 8);
96013     for(iFile=ncFile-1; iFile>=0 && zFile[iFile]!='/'; iFile--){}
96014     iFile++;
96015     if( sqlite3_strnicmp(zFile+iFile, "lib", 3)==0 ) iFile += 3;
96016     for(iEntry=8; (c = zFile[iFile])!=0 && c!='.'; iFile++){
96017       if( sqlite3Isalpha(c) ){
96018         zAltEntry[iEntry++] = (char)sqlite3UpperToLower[(unsigned)c];
96019       }
96020     }
96021     memcpy(zAltEntry+iEntry, "_init", 6);
96022     zEntry = zAltEntry;
96023     xInit = (int(*)(sqlite3*,char**,const sqlite3_api_routines*))
96024                      sqlite3OsDlSym(pVfs, handle, zEntry);
96025   }
96026   if( xInit==0 ){
96027     if( pzErrMsg ){
96028       nMsg += sqlite3Strlen30(zEntry);
96029       *pzErrMsg = zErrmsg = sqlite3_malloc(nMsg);
96030       if( zErrmsg ){
96031         sqlite3_snprintf(nMsg, zErrmsg,
96032             "no entry point [%s] in shared library [%s]", zEntry, zFile);
96033         sqlite3OsDlError(pVfs, nMsg-1, zErrmsg);
96034       }
96035     }
96036     sqlite3OsDlClose(pVfs, handle);
96037     sqlite3_free(zAltEntry);
96038     return SQLITE_ERROR;
96039   }
96040   sqlite3_free(zAltEntry);
96041   if( xInit(db, &zErrmsg, &sqlite3Apis) ){
96042     if( pzErrMsg ){
96043       *pzErrMsg = sqlite3_mprintf("error during initialization: %s", zErrmsg);
96044     }
96045     sqlite3_free(zErrmsg);
96046     sqlite3OsDlClose(pVfs, handle);
96047     return SQLITE_ERROR;
96048   }
96049 
96050   /* Append the new shared library handle to the db->aExtension array. */
96051   aHandle = sqlite3DbMallocZero(db, sizeof(handle)*(db->nExtension+1));
96052   if( aHandle==0 ){
96053     return SQLITE_NOMEM;
96054   }
96055   if( db->nExtension>0 ){
96056     memcpy(aHandle, db->aExtension, sizeof(handle)*db->nExtension);
96057   }
96058   sqlite3DbFree(db, db->aExtension);
96059   db->aExtension = aHandle;
96060 
96061   db->aExtension[db->nExtension++] = handle;
96062   return SQLITE_OK;
96063 }
96064 SQLITE_API int sqlite3_load_extension(
96065   sqlite3 *db,          /* Load the extension into this database connection */
96066   const char *zFile,    /* Name of the shared library containing extension */
96067   const char *zProc,    /* Entry point.  Use "sqlite3_extension_init" if 0 */
96068   char **pzErrMsg       /* Put error message here if not 0 */
96069 ){
96070   int rc;
96071   sqlite3_mutex_enter(db->mutex);
96072   rc = sqlite3LoadExtension(db, zFile, zProc, pzErrMsg);
96073   rc = sqlite3ApiExit(db, rc);
96074   sqlite3_mutex_leave(db->mutex);
96075   return rc;
96076 }
96077 
96078 /*
96079 ** Call this routine when the database connection is closing in order
96080 ** to clean up loaded extensions
96081 */
96082 SQLITE_PRIVATE void sqlite3CloseExtensions(sqlite3 *db){
96083   int i;
96084   assert( sqlite3_mutex_held(db->mutex) );
96085   for(i=0; i<db->nExtension; i++){
96086     sqlite3OsDlClose(db->pVfs, db->aExtension[i]);
96087   }
96088   sqlite3DbFree(db, db->aExtension);
96089 }
96090 
96091 /*
96092 ** Enable or disable extension loading.  Extension loading is disabled by
96093 ** default so as not to open security holes in older applications.
96094 */
96095 SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff){
96096   sqlite3_mutex_enter(db->mutex);
96097   if( onoff ){
96098     db->flags |= SQLITE_LoadExtension;
96099   }else{
96100     db->flags &= ~SQLITE_LoadExtension;
96101   }
96102   sqlite3_mutex_leave(db->mutex);
96103   return SQLITE_OK;
96104 }
96105 
96106 #endif /* SQLITE_OMIT_LOAD_EXTENSION */
96107 
96108 /*
96109 ** The auto-extension code added regardless of whether or not extension
96110 ** loading is supported.  We need a dummy sqlite3Apis pointer for that
96111 ** code if regular extension loading is not available.  This is that
96112 ** dummy pointer.
96113 */
96114 #ifdef SQLITE_OMIT_LOAD_EXTENSION
96115 static const sqlite3_api_routines sqlite3Apis = { 0 };
96116 #endif
96117 
96118 
96119 /*
96120 ** The following object holds the list of automatically loaded
96121 ** extensions.
96122 **
96123 ** This list is shared across threads.  The SQLITE_MUTEX_STATIC_MASTER
96124 ** mutex must be held while accessing this list.
96125 */
96126 typedef struct sqlite3AutoExtList sqlite3AutoExtList;
96127 static SQLITE_WSD struct sqlite3AutoExtList {
96128   int nExt;              /* Number of entries in aExt[] */          
96129   void (**aExt)(void);   /* Pointers to the extension init functions */
96130 } sqlite3Autoext = { 0, 0 };
96131 
96132 /* The "wsdAutoext" macro will resolve to the autoextension
96133 ** state vector.  If writable static data is unsupported on the target,
96134 ** we have to locate the state vector at run-time.  In the more common
96135 ** case where writable static data is supported, wsdStat can refer directly
96136 ** to the "sqlite3Autoext" state vector declared above.
96137 */
96138 #ifdef SQLITE_OMIT_WSD
96139 # define wsdAutoextInit \
96140   sqlite3AutoExtList *x = &GLOBAL(sqlite3AutoExtList,sqlite3Autoext)
96141 # define wsdAutoext x[0]
96142 #else
96143 # define wsdAutoextInit
96144 # define wsdAutoext sqlite3Autoext
96145 #endif
96146 
96147 
96148 /*
96149 ** Register a statically linked extension that is automatically
96150 ** loaded by every new database connection.
96151 */
96152 SQLITE_API int sqlite3_auto_extension(void (*xInit)(void)){
96153   int rc = SQLITE_OK;
96154 #ifndef SQLITE_OMIT_AUTOINIT
96155   rc = sqlite3_initialize();
96156   if( rc ){
96157     return rc;
96158   }else
96159 #endif
96160   {
96161     int i;
96162 #if SQLITE_THREADSAFE
96163     sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
96164 #endif
96165     wsdAutoextInit;
96166     sqlite3_mutex_enter(mutex);
96167     for(i=0; i<wsdAutoext.nExt; i++){
96168       if( wsdAutoext.aExt[i]==xInit ) break;
96169     }
96170     if( i==wsdAutoext.nExt ){
96171       int nByte = (wsdAutoext.nExt+1)*sizeof(wsdAutoext.aExt[0]);
96172       void (**aNew)(void);
96173       aNew = sqlite3_realloc(wsdAutoext.aExt, nByte);
96174       if( aNew==0 ){
96175         rc = SQLITE_NOMEM;
96176       }else{
96177         wsdAutoext.aExt = aNew;
96178         wsdAutoext.aExt[wsdAutoext.nExt] = xInit;
96179         wsdAutoext.nExt++;
96180       }
96181     }
96182     sqlite3_mutex_leave(mutex);
96183     assert( (rc&0xff)==rc );
96184     return rc;
96185   }
96186 }
96187 
96188 /*
96189 ** Cancel a prior call to sqlite3_auto_extension.  Remove xInit from the
96190 ** set of routines that is invoked for each new database connection, if it
96191 ** is currently on the list.  If xInit is not on the list, then this
96192 ** routine is a no-op.
96193 **
96194 ** Return 1 if xInit was found on the list and removed.  Return 0 if xInit
96195 ** was not on the list.
96196 */
96197 SQLITE_API int sqlite3_cancel_auto_extension(void (*xInit)(void)){
96198 #if SQLITE_THREADSAFE
96199   sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
96200 #endif
96201   int i;
96202   int n = 0;
96203   wsdAutoextInit;
96204   sqlite3_mutex_enter(mutex);
96205   for(i=wsdAutoext.nExt-1; i>=0; i--){
96206     if( wsdAutoext.aExt[i]==xInit ){
96207       wsdAutoext.nExt--;
96208       wsdAutoext.aExt[i] = wsdAutoext.aExt[wsdAutoext.nExt];
96209       n++;
96210       break;
96211     }
96212   }
96213   sqlite3_mutex_leave(mutex);
96214   return n;
96215 }
96216 
96217 /*
96218 ** Reset the automatic extension loading mechanism.
96219 */
96220 SQLITE_API void sqlite3_reset_auto_extension(void){
96221 #ifndef SQLITE_OMIT_AUTOINIT
96222   if( sqlite3_initialize()==SQLITE_OK )
96223 #endif
96224   {
96225 #if SQLITE_THREADSAFE
96226     sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
96227 #endif
96228     wsdAutoextInit;
96229     sqlite3_mutex_enter(mutex);
96230     sqlite3_free(wsdAutoext.aExt);
96231     wsdAutoext.aExt = 0;
96232     wsdAutoext.nExt = 0;
96233     sqlite3_mutex_leave(mutex);
96234   }
96235 }
96236 
96237 /*
96238 ** Load all automatic extensions.
96239 **
96240 ** If anything goes wrong, set an error in the database connection.
96241 */
96242 SQLITE_PRIVATE void sqlite3AutoLoadExtensions(sqlite3 *db){
96243   int i;
96244   int go = 1;
96245   int rc;
96246   int (*xInit)(sqlite3*,char**,const sqlite3_api_routines*);
96247 
96248   wsdAutoextInit;
96249   if( wsdAutoext.nExt==0 ){
96250     /* Common case: early out without every having to acquire a mutex */
96251     return;
96252   }
96253   for(i=0; go; i++){
96254     char *zErrmsg;
96255 #if SQLITE_THREADSAFE
96256     sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
96257 #endif
96258     sqlite3_mutex_enter(mutex);
96259     if( i>=wsdAutoext.nExt ){
96260       xInit = 0;
96261       go = 0;
96262     }else{
96263       xInit = (int(*)(sqlite3*,char**,const sqlite3_api_routines*))
96264               wsdAutoext.aExt[i];
96265     }
96266     sqlite3_mutex_leave(mutex);
96267     zErrmsg = 0;
96268     if( xInit && (rc = xInit(db, &zErrmsg, &sqlite3Apis))!=0 ){
96269       sqlite3Error(db, rc,
96270             "automatic extension loading failed: %s", zErrmsg);
96271       go = 0;
96272     }
96273     sqlite3_free(zErrmsg);
96274   }
96275 }
96276 
96277 /************** End of loadext.c *********************************************/
96278 /************** Begin file pragma.c ******************************************/
96279 /*
96280 ** 2003 April 6
96281 **
96282 ** The author disclaims copyright to this source code.  In place of
96283 ** a legal notice, here is a blessing:
96284 **
96285 **    May you do good and not evil.
96286 **    May you find forgiveness for yourself and forgive others.
96287 **    May you share freely, never taking more than you give.
96288 **
96289 *************************************************************************
96290 ** This file contains code used to implement the PRAGMA command.
96291 */
96292 
96293 #if !defined(SQLITE_ENABLE_LOCKING_STYLE)
96294 #  if defined(__APPLE__)
96295 #    define SQLITE_ENABLE_LOCKING_STYLE 1
96296 #  else
96297 #    define SQLITE_ENABLE_LOCKING_STYLE 0
96298 #  endif
96299 #endif
96300 
96301 /***************************************************************************
96302 ** The next block of code, including the PragTyp_XXXX macro definitions and
96303 ** the aPragmaName[] object is composed of generated code. DO NOT EDIT.
96304 **
96305 ** To add new pragmas, edit the code in ../tool/mkpragmatab.tcl and rerun
96306 ** that script.  Then copy/paste the output in place of the following:
96307 */
96308 #define PragTyp_HEADER_VALUE                   0
96309 #define PragTyp_AUTO_VACUUM                    1
96310 #define PragTyp_FLAG                           2
96311 #define PragTyp_BUSY_TIMEOUT                   3
96312 #define PragTyp_CACHE_SIZE                     4
96313 #define PragTyp_CASE_SENSITIVE_LIKE            5
96314 #define PragTyp_COLLATION_LIST                 6
96315 #define PragTyp_COMPILE_OPTIONS                7
96316 #define PragTyp_DATA_STORE_DIRECTORY           8
96317 #define PragTyp_DATABASE_LIST                  9
96318 #define PragTyp_DEFAULT_CACHE_SIZE            10
96319 #define PragTyp_ENCODING                      11
96320 #define PragTyp_FOREIGN_KEY_CHECK             12
96321 #define PragTyp_FOREIGN_KEY_LIST              13
96322 #define PragTyp_INCREMENTAL_VACUUM            14
96323 #define PragTyp_INDEX_INFO                    15
96324 #define PragTyp_INDEX_LIST                    16
96325 #define PragTyp_INTEGRITY_CHECK               17
96326 #define PragTyp_JOURNAL_MODE                  18
96327 #define PragTyp_JOURNAL_SIZE_LIMIT            19
96328 #define PragTyp_LOCK_PROXY_FILE               20
96329 #define PragTyp_LOCKING_MODE                  21
96330 #define PragTyp_PAGE_COUNT                    22
96331 #define PragTyp_MMAP_SIZE                     23
96332 #define PragTyp_PAGE_SIZE                     24
96333 #define PragTyp_SECURE_DELETE                 25
96334 #define PragTyp_SHRINK_MEMORY                 26
96335 #define PragTyp_SOFT_HEAP_LIMIT               27
96336 #define PragTyp_STATS                         28
96337 #define PragTyp_SYNCHRONOUS                   29
96338 #define PragTyp_TABLE_INFO                    30
96339 #define PragTyp_TEMP_STORE                    31
96340 #define PragTyp_TEMP_STORE_DIRECTORY          32
96341 #define PragTyp_WAL_AUTOCHECKPOINT            33
96342 #define PragTyp_WAL_CHECKPOINT                34
96343 #define PragTyp_ACTIVATE_EXTENSIONS           35
96344 #define PragTyp_HEXKEY                        36
96345 #define PragTyp_KEY                           37
96346 #define PragTyp_REKEY                         38
96347 #define PragTyp_LOCK_STATUS                   39
96348 #define PragTyp_PARSER_TRACE                  40
96349 #define PragFlag_NeedSchema           0x01
96350 static const struct sPragmaNames {
96351   const char *const zName;  /* Name of pragma */
96352   u8 ePragTyp;              /* PragTyp_XXX value */
96353   u8 mPragFlag;             /* Zero or more PragFlag_XXX values */
96354   u32 iArg;                 /* Extra argument */
96355 } aPragmaNames[] = {
96356 #if defined(SQLITE_HAS_CODEC) || defined(SQLITE_ENABLE_CEROD)
96357   { /* zName:     */ "activate_extensions",
96358     /* ePragTyp:  */ PragTyp_ACTIVATE_EXTENSIONS,
96359     /* ePragFlag: */ 0,
96360     /* iArg:      */ 0 },
96361 #endif
96362 #if !defined(SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS)
96363   { /* zName:     */ "application_id",
96364     /* ePragTyp:  */ PragTyp_HEADER_VALUE,
96365     /* ePragFlag: */ 0,
96366     /* iArg:      */ 0 },
96367 #endif
96368 #if !defined(SQLITE_OMIT_AUTOVACUUM)
96369   { /* zName:     */ "auto_vacuum",
96370     /* ePragTyp:  */ PragTyp_AUTO_VACUUM,
96371     /* ePragFlag: */ PragFlag_NeedSchema,
96372     /* iArg:      */ 0 },
96373 #endif
96374 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96375 #if !defined(SQLITE_OMIT_AUTOMATIC_INDEX)
96376   { /* zName:     */ "automatic_index",
96377     /* ePragTyp:  */ PragTyp_FLAG,
96378     /* ePragFlag: */ 0,
96379     /* iArg:      */ SQLITE_AutoIndex },
96380 #endif
96381 #endif
96382   { /* zName:     */ "busy_timeout",
96383     /* ePragTyp:  */ PragTyp_BUSY_TIMEOUT,
96384     /* ePragFlag: */ 0,
96385     /* iArg:      */ 0 },
96386 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96387   { /* zName:     */ "cache_size",
96388     /* ePragTyp:  */ PragTyp_CACHE_SIZE,
96389     /* ePragFlag: */ PragFlag_NeedSchema,
96390     /* iArg:      */ 0 },
96391 #endif
96392 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96393   { /* zName:     */ "cache_spill",
96394     /* ePragTyp:  */ PragTyp_FLAG,
96395     /* ePragFlag: */ 0,
96396     /* iArg:      */ SQLITE_CacheSpill },
96397 #endif
96398   { /* zName:     */ "case_sensitive_like",
96399     /* ePragTyp:  */ PragTyp_CASE_SENSITIVE_LIKE,
96400     /* ePragFlag: */ 0,
96401     /* iArg:      */ 0 },
96402 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96403   { /* zName:     */ "checkpoint_fullfsync",
96404     /* ePragTyp:  */ PragTyp_FLAG,
96405     /* ePragFlag: */ 0,
96406     /* iArg:      */ SQLITE_CkptFullFSync },
96407 #endif
96408 #if !defined(SQLITE_OMIT_SCHEMA_PRAGMAS)
96409   { /* zName:     */ "collation_list",
96410     /* ePragTyp:  */ PragTyp_COLLATION_LIST,
96411     /* ePragFlag: */ 0,
96412     /* iArg:      */ 0 },
96413 #endif
96414 #if !defined(SQLITE_OMIT_COMPILEOPTION_DIAGS)
96415   { /* zName:     */ "compile_options",
96416     /* ePragTyp:  */ PragTyp_COMPILE_OPTIONS,
96417     /* ePragFlag: */ 0,
96418     /* iArg:      */ 0 },
96419 #endif
96420 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96421   { /* zName:     */ "count_changes",
96422     /* ePragTyp:  */ PragTyp_FLAG,
96423     /* ePragFlag: */ 0,
96424     /* iArg:      */ SQLITE_CountRows },
96425 #endif
96426 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS) && SQLITE_OS_WIN
96427   { /* zName:     */ "data_store_directory",
96428     /* ePragTyp:  */ PragTyp_DATA_STORE_DIRECTORY,
96429     /* ePragFlag: */ 0,
96430     /* iArg:      */ 0 },
96431 #endif
96432 #if !defined(SQLITE_OMIT_SCHEMA_PRAGMAS)
96433   { /* zName:     */ "database_list",
96434     /* ePragTyp:  */ PragTyp_DATABASE_LIST,
96435     /* ePragFlag: */ PragFlag_NeedSchema,
96436     /* iArg:      */ 0 },
96437 #endif
96438 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS) && !defined(SQLITE_OMIT_DEPRECATED)
96439   { /* zName:     */ "default_cache_size",
96440     /* ePragTyp:  */ PragTyp_DEFAULT_CACHE_SIZE,
96441     /* ePragFlag: */ PragFlag_NeedSchema,
96442     /* iArg:      */ 0 },
96443 #endif
96444 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96445 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
96446   { /* zName:     */ "defer_foreign_keys",
96447     /* ePragTyp:  */ PragTyp_FLAG,
96448     /* ePragFlag: */ 0,
96449     /* iArg:      */ SQLITE_DeferFKs },
96450 #endif
96451 #endif
96452 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96453   { /* zName:     */ "empty_result_callbacks",
96454     /* ePragTyp:  */ PragTyp_FLAG,
96455     /* ePragFlag: */ 0,
96456     /* iArg:      */ SQLITE_NullCallback },
96457 #endif
96458 #if !defined(SQLITE_OMIT_UTF16)
96459   { /* zName:     */ "encoding",
96460     /* ePragTyp:  */ PragTyp_ENCODING,
96461     /* ePragFlag: */ 0,
96462     /* iArg:      */ 0 },
96463 #endif
96464 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
96465   { /* zName:     */ "foreign_key_check",
96466     /* ePragTyp:  */ PragTyp_FOREIGN_KEY_CHECK,
96467     /* ePragFlag: */ PragFlag_NeedSchema,
96468     /* iArg:      */ 0 },
96469 #endif
96470 #if !defined(SQLITE_OMIT_FOREIGN_KEY)
96471   { /* zName:     */ "foreign_key_list",
96472     /* ePragTyp:  */ PragTyp_FOREIGN_KEY_LIST,
96473     /* ePragFlag: */ PragFlag_NeedSchema,
96474     /* iArg:      */ 0 },
96475 #endif
96476 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96477 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
96478   { /* zName:     */ "foreign_keys",
96479     /* ePragTyp:  */ PragTyp_FLAG,
96480     /* ePragFlag: */ 0,
96481     /* iArg:      */ SQLITE_ForeignKeys },
96482 #endif
96483 #endif
96484 #if !defined(SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS)
96485   { /* zName:     */ "freelist_count",
96486     /* ePragTyp:  */ PragTyp_HEADER_VALUE,
96487     /* ePragFlag: */ 0,
96488     /* iArg:      */ 0 },
96489 #endif
96490 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96491   { /* zName:     */ "full_column_names",
96492     /* ePragTyp:  */ PragTyp_FLAG,
96493     /* ePragFlag: */ 0,
96494     /* iArg:      */ SQLITE_FullColNames },
96495   { /* zName:     */ "fullfsync",
96496     /* ePragTyp:  */ PragTyp_FLAG,
96497     /* ePragFlag: */ 0,
96498     /* iArg:      */ SQLITE_FullFSync },
96499 #endif
96500 #if defined(SQLITE_HAS_CODEC)
96501   { /* zName:     */ "hexkey",
96502     /* ePragTyp:  */ PragTyp_HEXKEY,
96503     /* ePragFlag: */ 0,
96504     /* iArg:      */ 0 },
96505   { /* zName:     */ "hexrekey",
96506     /* ePragTyp:  */ PragTyp_HEXKEY,
96507     /* ePragFlag: */ 0,
96508     /* iArg:      */ 0 },
96509 #endif
96510 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96511 #if !defined(SQLITE_OMIT_CHECK)
96512   { /* zName:     */ "ignore_check_constraints",
96513     /* ePragTyp:  */ PragTyp_FLAG,
96514     /* ePragFlag: */ 0,
96515     /* iArg:      */ SQLITE_IgnoreChecks },
96516 #endif
96517 #endif
96518 #if !defined(SQLITE_OMIT_AUTOVACUUM)
96519   { /* zName:     */ "incremental_vacuum",
96520     /* ePragTyp:  */ PragTyp_INCREMENTAL_VACUUM,
96521     /* ePragFlag: */ PragFlag_NeedSchema,
96522     /* iArg:      */ 0 },
96523 #endif
96524 #if !defined(SQLITE_OMIT_SCHEMA_PRAGMAS)
96525   { /* zName:     */ "index_info",
96526     /* ePragTyp:  */ PragTyp_INDEX_INFO,
96527     /* ePragFlag: */ PragFlag_NeedSchema,
96528     /* iArg:      */ 0 },
96529   { /* zName:     */ "index_list",
96530     /* ePragTyp:  */ PragTyp_INDEX_LIST,
96531     /* ePragFlag: */ PragFlag_NeedSchema,
96532     /* iArg:      */ 0 },
96533 #endif
96534 #if !defined(SQLITE_OMIT_INTEGRITY_CHECK)
96535   { /* zName:     */ "integrity_check",
96536     /* ePragTyp:  */ PragTyp_INTEGRITY_CHECK,
96537     /* ePragFlag: */ PragFlag_NeedSchema,
96538     /* iArg:      */ 0 },
96539 #endif
96540 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96541   { /* zName:     */ "journal_mode",
96542     /* ePragTyp:  */ PragTyp_JOURNAL_MODE,
96543     /* ePragFlag: */ PragFlag_NeedSchema,
96544     /* iArg:      */ 0 },
96545   { /* zName:     */ "journal_size_limit",
96546     /* ePragTyp:  */ PragTyp_JOURNAL_SIZE_LIMIT,
96547     /* ePragFlag: */ 0,
96548     /* iArg:      */ 0 },
96549 #endif
96550 #if defined(SQLITE_HAS_CODEC)
96551   { /* zName:     */ "key",
96552     /* ePragTyp:  */ PragTyp_KEY,
96553     /* ePragFlag: */ 0,
96554     /* iArg:      */ 0 },
96555 #endif
96556 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96557   { /* zName:     */ "legacy_file_format",
96558     /* ePragTyp:  */ PragTyp_FLAG,
96559     /* ePragFlag: */ 0,
96560     /* iArg:      */ SQLITE_LegacyFileFmt },
96561 #endif
96562 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS) && SQLITE_ENABLE_LOCKING_STYLE
96563   { /* zName:     */ "lock_proxy_file",
96564     /* ePragTyp:  */ PragTyp_LOCK_PROXY_FILE,
96565     /* ePragFlag: */ 0,
96566     /* iArg:      */ 0 },
96567 #endif
96568 #if defined(SQLITE_DEBUG) || defined(SQLITE_TEST)
96569   { /* zName:     */ "lock_status",
96570     /* ePragTyp:  */ PragTyp_LOCK_STATUS,
96571     /* ePragFlag: */ 0,
96572     /* iArg:      */ 0 },
96573 #endif
96574 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96575   { /* zName:     */ "locking_mode",
96576     /* ePragTyp:  */ PragTyp_LOCKING_MODE,
96577     /* ePragFlag: */ 0,
96578     /* iArg:      */ 0 },
96579   { /* zName:     */ "max_page_count",
96580     /* ePragTyp:  */ PragTyp_PAGE_COUNT,
96581     /* ePragFlag: */ PragFlag_NeedSchema,
96582     /* iArg:      */ 0 },
96583   { /* zName:     */ "mmap_size",
96584     /* ePragTyp:  */ PragTyp_MMAP_SIZE,
96585     /* ePragFlag: */ 0,
96586     /* iArg:      */ 0 },
96587   { /* zName:     */ "page_count",
96588     /* ePragTyp:  */ PragTyp_PAGE_COUNT,
96589     /* ePragFlag: */ PragFlag_NeedSchema,
96590     /* iArg:      */ 0 },
96591   { /* zName:     */ "page_size",
96592     /* ePragTyp:  */ PragTyp_PAGE_SIZE,
96593     /* ePragFlag: */ 0,
96594     /* iArg:      */ 0 },
96595 #endif
96596 #if defined(SQLITE_DEBUG)
96597   { /* zName:     */ "parser_trace",
96598     /* ePragTyp:  */ PragTyp_PARSER_TRACE,
96599     /* ePragFlag: */ 0,
96600     /* iArg:      */ 0 },
96601 #endif
96602 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96603   { /* zName:     */ "query_only",
96604     /* ePragTyp:  */ PragTyp_FLAG,
96605     /* ePragFlag: */ 0,
96606     /* iArg:      */ SQLITE_QueryOnly },
96607 #endif
96608 #if !defined(SQLITE_OMIT_INTEGRITY_CHECK)
96609   { /* zName:     */ "quick_check",
96610     /* ePragTyp:  */ PragTyp_INTEGRITY_CHECK,
96611     /* ePragFlag: */ PragFlag_NeedSchema,
96612     /* iArg:      */ 0 },
96613 #endif
96614 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96615   { /* zName:     */ "read_uncommitted",
96616     /* ePragTyp:  */ PragTyp_FLAG,
96617     /* ePragFlag: */ 0,
96618     /* iArg:      */ SQLITE_ReadUncommitted },
96619   { /* zName:     */ "recursive_triggers",
96620     /* ePragTyp:  */ PragTyp_FLAG,
96621     /* ePragFlag: */ 0,
96622     /* iArg:      */ SQLITE_RecTriggers },
96623 #endif
96624 #if defined(SQLITE_HAS_CODEC)
96625   { /* zName:     */ "rekey",
96626     /* ePragTyp:  */ PragTyp_REKEY,
96627     /* ePragFlag: */ 0,
96628     /* iArg:      */ 0 },
96629 #endif
96630 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96631   { /* zName:     */ "reverse_unordered_selects",
96632     /* ePragTyp:  */ PragTyp_FLAG,
96633     /* ePragFlag: */ 0,
96634     /* iArg:      */ SQLITE_ReverseOrder },
96635 #endif
96636 #if !defined(SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS)
96637   { /* zName:     */ "schema_version",
96638     /* ePragTyp:  */ PragTyp_HEADER_VALUE,
96639     /* ePragFlag: */ 0,
96640     /* iArg:      */ 0 },
96641 #endif
96642 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96643   { /* zName:     */ "secure_delete",
96644     /* ePragTyp:  */ PragTyp_SECURE_DELETE,
96645     /* ePragFlag: */ 0,
96646     /* iArg:      */ 0 },
96647 #endif
96648 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96649   { /* zName:     */ "short_column_names",
96650     /* ePragTyp:  */ PragTyp_FLAG,
96651     /* ePragFlag: */ 0,
96652     /* iArg:      */ SQLITE_ShortColNames },
96653 #endif
96654   { /* zName:     */ "shrink_memory",
96655     /* ePragTyp:  */ PragTyp_SHRINK_MEMORY,
96656     /* ePragFlag: */ 0,
96657     /* iArg:      */ 0 },
96658   { /* zName:     */ "soft_heap_limit",
96659     /* ePragTyp:  */ PragTyp_SOFT_HEAP_LIMIT,
96660     /* ePragFlag: */ 0,
96661     /* iArg:      */ 0 },
96662 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96663 #if defined(SQLITE_DEBUG)
96664   { /* zName:     */ "sql_trace",
96665     /* ePragTyp:  */ PragTyp_FLAG,
96666     /* ePragFlag: */ 0,
96667     /* iArg:      */ SQLITE_SqlTrace },
96668 #endif
96669 #endif
96670 #if !defined(SQLITE_OMIT_SCHEMA_PRAGMAS)
96671   { /* zName:     */ "stats",
96672     /* ePragTyp:  */ PragTyp_STATS,
96673     /* ePragFlag: */ PragFlag_NeedSchema,
96674     /* iArg:      */ 0 },
96675 #endif
96676 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96677   { /* zName:     */ "synchronous",
96678     /* ePragTyp:  */ PragTyp_SYNCHRONOUS,
96679     /* ePragFlag: */ PragFlag_NeedSchema,
96680     /* iArg:      */ 0 },
96681 #endif
96682 #if !defined(SQLITE_OMIT_SCHEMA_PRAGMAS)
96683   { /* zName:     */ "table_info",
96684     /* ePragTyp:  */ PragTyp_TABLE_INFO,
96685     /* ePragFlag: */ PragFlag_NeedSchema,
96686     /* iArg:      */ 0 },
96687 #endif
96688 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96689   { /* zName:     */ "temp_store",
96690     /* ePragTyp:  */ PragTyp_TEMP_STORE,
96691     /* ePragFlag: */ 0,
96692     /* iArg:      */ 0 },
96693   { /* zName:     */ "temp_store_directory",
96694     /* ePragTyp:  */ PragTyp_TEMP_STORE_DIRECTORY,
96695     /* ePragFlag: */ 0,
96696     /* iArg:      */ 0 },
96697 #endif
96698 #if !defined(SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS)
96699   { /* zName:     */ "user_version",
96700     /* ePragTyp:  */ PragTyp_HEADER_VALUE,
96701     /* ePragFlag: */ 0,
96702     /* iArg:      */ 0 },
96703 #endif
96704 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96705 #if defined(SQLITE_DEBUG)
96706   { /* zName:     */ "vdbe_addoptrace",
96707     /* ePragTyp:  */ PragTyp_FLAG,
96708     /* ePragFlag: */ 0,
96709     /* iArg:      */ SQLITE_VdbeAddopTrace },
96710   { /* zName:     */ "vdbe_debug",
96711     /* ePragTyp:  */ PragTyp_FLAG,
96712     /* ePragFlag: */ 0,
96713     /* iArg:      */ SQLITE_SqlTrace|SQLITE_VdbeListing|SQLITE_VdbeTrace },
96714   { /* zName:     */ "vdbe_eqp",
96715     /* ePragTyp:  */ PragTyp_FLAG,
96716     /* ePragFlag: */ 0,
96717     /* iArg:      */ SQLITE_VdbeEQP },
96718   { /* zName:     */ "vdbe_listing",
96719     /* ePragTyp:  */ PragTyp_FLAG,
96720     /* ePragFlag: */ 0,
96721     /* iArg:      */ SQLITE_VdbeListing },
96722   { /* zName:     */ "vdbe_trace",
96723     /* ePragTyp:  */ PragTyp_FLAG,
96724     /* ePragFlag: */ 0,
96725     /* iArg:      */ SQLITE_VdbeTrace },
96726 #endif
96727 #endif
96728 #if !defined(SQLITE_OMIT_WAL)
96729   { /* zName:     */ "wal_autocheckpoint",
96730     /* ePragTyp:  */ PragTyp_WAL_AUTOCHECKPOINT,
96731     /* ePragFlag: */ 0,
96732     /* iArg:      */ 0 },
96733   { /* zName:     */ "wal_checkpoint",
96734     /* ePragTyp:  */ PragTyp_WAL_CHECKPOINT,
96735     /* ePragFlag: */ PragFlag_NeedSchema,
96736     /* iArg:      */ 0 },
96737 #endif
96738 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96739   { /* zName:     */ "writable_schema",
96740     /* ePragTyp:  */ PragTyp_FLAG,
96741     /* ePragFlag: */ 0,
96742     /* iArg:      */ SQLITE_WriteSchema|SQLITE_RecoveryMode },
96743 #endif
96744 };
96745 /* Number of pragmas: 56 on by default, 69 total. */
96746 /* End of the automatically generated pragma table.
96747 ***************************************************************************/
96748 
96749 /*
96750 ** Interpret the given string as a safety level.  Return 0 for OFF,
96751 ** 1 for ON or NORMAL and 2 for FULL.  Return 1 for an empty or 
96752 ** unrecognized string argument.  The FULL option is disallowed
96753 ** if the omitFull parameter it 1.
96754 **
96755 ** Note that the values returned are one less that the values that
96756 ** should be passed into sqlite3BtreeSetSafetyLevel().  The is done
96757 ** to support legacy SQL code.  The safety level used to be boolean
96758 ** and older scripts may have used numbers 0 for OFF and 1 for ON.
96759 */
96760 static u8 getSafetyLevel(const char *z, int omitFull, int dflt){
96761                              /* 123456789 123456789 */
96762   static const char zText[] = "onoffalseyestruefull";
96763   static const u8 iOffset[] = {0, 1, 2, 4, 9, 12, 16};
96764   static const u8 iLength[] = {2, 2, 3, 5, 3, 4, 4};
96765   static const u8 iValue[] =  {1, 0, 0, 0, 1, 1, 2};
96766   int i, n;
96767   if( sqlite3Isdigit(*z) ){
96768     return (u8)sqlite3Atoi(z);
96769   }
96770   n = sqlite3Strlen30(z);
96771   for(i=0; i<ArraySize(iLength)-omitFull; i++){
96772     if( iLength[i]==n && sqlite3StrNICmp(&zText[iOffset[i]],z,n)==0 ){
96773       return iValue[i];
96774     }
96775   }
96776   return dflt;
96777 }
96778 
96779 /*
96780 ** Interpret the given string as a boolean value.
96781 */
96782 SQLITE_PRIVATE u8 sqlite3GetBoolean(const char *z, int dflt){
96783   return getSafetyLevel(z,1,dflt)!=0;
96784 }
96785 
96786 /* The sqlite3GetBoolean() function is used by other modules but the
96787 ** remainder of this file is specific to PRAGMA processing.  So omit
96788 ** the rest of the file if PRAGMAs are omitted from the build.
96789 */
96790 #if !defined(SQLITE_OMIT_PRAGMA)
96791 
96792 /*
96793 ** Interpret the given string as a locking mode value.
96794 */
96795 static int getLockingMode(const char *z){
96796   if( z ){
96797     if( 0==sqlite3StrICmp(z, "exclusive") ) return PAGER_LOCKINGMODE_EXCLUSIVE;
96798     if( 0==sqlite3StrICmp(z, "normal") ) return PAGER_LOCKINGMODE_NORMAL;
96799   }
96800   return PAGER_LOCKINGMODE_QUERY;
96801 }
96802 
96803 #ifndef SQLITE_OMIT_AUTOVACUUM
96804 /*
96805 ** Interpret the given string as an auto-vacuum mode value.
96806 **
96807 ** The following strings, "none", "full" and "incremental" are 
96808 ** acceptable, as are their numeric equivalents: 0, 1 and 2 respectively.
96809 */
96810 static int getAutoVacuum(const char *z){
96811   int i;
96812   if( 0==sqlite3StrICmp(z, "none") ) return BTREE_AUTOVACUUM_NONE;
96813   if( 0==sqlite3StrICmp(z, "full") ) return BTREE_AUTOVACUUM_FULL;
96814   if( 0==sqlite3StrICmp(z, "incremental") ) return BTREE_AUTOVACUUM_INCR;
96815   i = sqlite3Atoi(z);
96816   return (u8)((i>=0&&i<=2)?i:0);
96817 }
96818 #endif /* ifndef SQLITE_OMIT_AUTOVACUUM */
96819 
96820 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
96821 /*
96822 ** Interpret the given string as a temp db location. Return 1 for file
96823 ** backed temporary databases, 2 for the Red-Black tree in memory database
96824 ** and 0 to use the compile-time default.
96825 */
96826 static int getTempStore(const char *z){
96827   if( z[0]>='0' && z[0]<='2' ){
96828     return z[0] - '0';
96829   }else if( sqlite3StrICmp(z, "file")==0 ){
96830     return 1;
96831   }else if( sqlite3StrICmp(z, "memory")==0 ){
96832     return 2;
96833   }else{
96834     return 0;
96835   }
96836 }
96837 #endif /* SQLITE_PAGER_PRAGMAS */
96838 
96839 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
96840 /*
96841 ** Invalidate temp storage, either when the temp storage is changed
96842 ** from default, or when 'file' and the temp_store_directory has changed
96843 */
96844 static int invalidateTempStorage(Parse *pParse){
96845   sqlite3 *db = pParse->db;
96846   if( db->aDb[1].pBt!=0 ){
96847     if( !db->autoCommit || sqlite3BtreeIsInReadTrans(db->aDb[1].pBt) ){
96848       sqlite3ErrorMsg(pParse, "temporary storage cannot be changed "
96849         "from within a transaction");
96850       return SQLITE_ERROR;
96851     }
96852     sqlite3BtreeClose(db->aDb[1].pBt);
96853     db->aDb[1].pBt = 0;
96854     sqlite3ResetAllSchemasOfConnection(db);
96855   }
96856   return SQLITE_OK;
96857 }
96858 #endif /* SQLITE_PAGER_PRAGMAS */
96859 
96860 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
96861 /*
96862 ** If the TEMP database is open, close it and mark the database schema
96863 ** as needing reloading.  This must be done when using the SQLITE_TEMP_STORE
96864 ** or DEFAULT_TEMP_STORE pragmas.
96865 */
96866 static int changeTempStorage(Parse *pParse, const char *zStorageType){
96867   int ts = getTempStore(zStorageType);
96868   sqlite3 *db = pParse->db;
96869   if( db->temp_store==ts ) return SQLITE_OK;
96870   if( invalidateTempStorage( pParse ) != SQLITE_OK ){
96871     return SQLITE_ERROR;
96872   }
96873   db->temp_store = (u8)ts;
96874   return SQLITE_OK;
96875 }
96876 #endif /* SQLITE_PAGER_PRAGMAS */
96877 
96878 /*
96879 ** Generate code to return a single integer value.
96880 */
96881 static void returnSingleInt(Parse *pParse, const char *zLabel, i64 value){
96882   Vdbe *v = sqlite3GetVdbe(pParse);
96883   int mem = ++pParse->nMem;
96884   i64 *pI64 = sqlite3DbMallocRaw(pParse->db, sizeof(value));
96885   if( pI64 ){
96886     memcpy(pI64, &value, sizeof(value));
96887   }
96888   sqlite3VdbeAddOp4(v, OP_Int64, 0, mem, 0, (char*)pI64, P4_INT64);
96889   sqlite3VdbeSetNumCols(v, 1);
96890   sqlite3VdbeSetColName(v, 0, COLNAME_NAME, zLabel, SQLITE_STATIC);
96891   sqlite3VdbeAddOp2(v, OP_ResultRow, mem, 1);
96892 }
96893 
96894 
96895 /*
96896 ** Set the safety_level and pager flags for pager iDb.  Or if iDb<0
96897 ** set these values for all pagers.
96898 */
96899 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
96900 static void setAllPagerFlags(sqlite3 *db){
96901   if( db->autoCommit ){
96902     Db *pDb = db->aDb;
96903     int n = db->nDb;
96904     assert( SQLITE_FullFSync==PAGER_FULLFSYNC );
96905     assert( SQLITE_CkptFullFSync==PAGER_CKPT_FULLFSYNC );
96906     assert( SQLITE_CacheSpill==PAGER_CACHESPILL );
96907     assert( (PAGER_FULLFSYNC | PAGER_CKPT_FULLFSYNC | PAGER_CACHESPILL)
96908              ==  PAGER_FLAGS_MASK );
96909     assert( (pDb->safety_level & PAGER_SYNCHRONOUS_MASK)==pDb->safety_level );
96910     while( (n--) > 0 ){
96911       if( pDb->pBt ){
96912         sqlite3BtreeSetPagerFlags(pDb->pBt,
96913                  pDb->safety_level | (db->flags & PAGER_FLAGS_MASK) );
96914       }
96915       pDb++;
96916     }
96917   }
96918 }
96919 #else
96920 # define setAllPagerFlags(X)  /* no-op */
96921 #endif
96922 
96923 
96924 /*
96925 ** Return a human-readable name for a constraint resolution action.
96926 */
96927 #ifndef SQLITE_OMIT_FOREIGN_KEY
96928 static const char *actionName(u8 action){
96929   const char *zName;
96930   switch( action ){
96931     case OE_SetNull:  zName = "SET NULL";        break;
96932     case OE_SetDflt:  zName = "SET DEFAULT";     break;
96933     case OE_Cascade:  zName = "CASCADE";         break;
96934     case OE_Restrict: zName = "RESTRICT";        break;
96935     default:          zName = "NO ACTION";  
96936                       assert( action==OE_None ); break;
96937   }
96938   return zName;
96939 }
96940 #endif
96941 
96942 
96943 /*
96944 ** Parameter eMode must be one of the PAGER_JOURNALMODE_XXX constants
96945 ** defined in pager.h. This function returns the associated lowercase
96946 ** journal-mode name.
96947 */
96948 SQLITE_PRIVATE const char *sqlite3JournalModename(int eMode){
96949   static char * const azModeName[] = {
96950     "delete", "persist", "off", "truncate", "memory"
96951 #ifndef SQLITE_OMIT_WAL
96952      , "wal"
96953 #endif
96954   };
96955   assert( PAGER_JOURNALMODE_DELETE==0 );
96956   assert( PAGER_JOURNALMODE_PERSIST==1 );
96957   assert( PAGER_JOURNALMODE_OFF==2 );
96958   assert( PAGER_JOURNALMODE_TRUNCATE==3 );
96959   assert( PAGER_JOURNALMODE_MEMORY==4 );
96960   assert( PAGER_JOURNALMODE_WAL==5 );
96961   assert( eMode>=0 && eMode<=ArraySize(azModeName) );
96962 
96963   if( eMode==ArraySize(azModeName) ) return 0;
96964   return azModeName[eMode];
96965 }
96966 
96967 /*
96968 ** Process a pragma statement.  
96969 **
96970 ** Pragmas are of this form:
96971 **
96972 **      PRAGMA [database.]id [= value]
96973 **
96974 ** The identifier might also be a string.  The value is a string, and
96975 ** identifier, or a number.  If minusFlag is true, then the value is
96976 ** a number that was preceded by a minus sign.
96977 **
96978 ** If the left side is "database.id" then pId1 is the database name
96979 ** and pId2 is the id.  If the left side is just "id" then pId1 is the
96980 ** id and pId2 is any empty string.
96981 */
96982 SQLITE_PRIVATE void sqlite3Pragma(
96983   Parse *pParse, 
96984   Token *pId1,        /* First part of [database.]id field */
96985   Token *pId2,        /* Second part of [database.]id field, or NULL */
96986   Token *pValue,      /* Token for <value>, or NULL */
96987   int minusFlag       /* True if a '-' sign preceded <value> */
96988 ){
96989   char *zLeft = 0;       /* Nul-terminated UTF-8 string <id> */
96990   char *zRight = 0;      /* Nul-terminated UTF-8 string <value>, or NULL */
96991   const char *zDb = 0;   /* The database name */
96992   Token *pId;            /* Pointer to <id> token */
96993   char *aFcntl[4];       /* Argument to SQLITE_FCNTL_PRAGMA */
96994   int iDb;               /* Database index for <database> */
96995   int lwr, upr, mid;           /* Binary search bounds */
96996   int rc;                      /* return value form SQLITE_FCNTL_PRAGMA */
96997   sqlite3 *db = pParse->db;    /* The database connection */
96998   Db *pDb;                     /* The specific database being pragmaed */
96999   Vdbe *v = sqlite3GetVdbe(pParse);  /* Prepared statement */
97000 
97001   if( v==0 ) return;
97002   sqlite3VdbeRunOnlyOnce(v);
97003   pParse->nMem = 2;
97004 
97005   /* Interpret the [database.] part of the pragma statement. iDb is the
97006   ** index of the database this pragma is being applied to in db.aDb[]. */
97007   iDb = sqlite3TwoPartName(pParse, pId1, pId2, &pId);
97008   if( iDb<0 ) return;
97009   pDb = &db->aDb[iDb];
97010 
97011   /* If the temp database has been explicitly named as part of the 
97012   ** pragma, make sure it is open. 
97013   */
97014   if( iDb==1 && sqlite3OpenTempDatabase(pParse) ){
97015     return;
97016   }
97017 
97018   zLeft = sqlite3NameFromToken(db, pId);
97019   if( !zLeft ) return;
97020   if( minusFlag ){
97021     zRight = sqlite3MPrintf(db, "-%T", pValue);
97022   }else{
97023     zRight = sqlite3NameFromToken(db, pValue);
97024   }
97025 
97026   assert( pId2 );
97027   zDb = pId2->n>0 ? pDb->zName : 0;
97028   if( sqlite3AuthCheck(pParse, SQLITE_PRAGMA, zLeft, zRight, zDb) ){
97029     goto pragma_out;
97030   }
97031 
97032   /* Send an SQLITE_FCNTL_PRAGMA file-control to the underlying VFS
97033   ** connection.  If it returns SQLITE_OK, then assume that the VFS
97034   ** handled the pragma and generate a no-op prepared statement.
97035   */
97036   aFcntl[0] = 0;
97037   aFcntl[1] = zLeft;
97038   aFcntl[2] = zRight;
97039   aFcntl[3] = 0;
97040   db->busyHandler.nBusy = 0;
97041   rc = sqlite3_file_control(db, zDb, SQLITE_FCNTL_PRAGMA, (void*)aFcntl);
97042   if( rc==SQLITE_OK ){
97043     if( aFcntl[0] ){
97044       int mem = ++pParse->nMem;
97045       sqlite3VdbeAddOp4(v, OP_String8, 0, mem, 0, aFcntl[0], 0);
97046       sqlite3VdbeSetNumCols(v, 1);
97047       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "result", SQLITE_STATIC);
97048       sqlite3VdbeAddOp2(v, OP_ResultRow, mem, 1);
97049       sqlite3_free(aFcntl[0]);
97050     }
97051     goto pragma_out;
97052   }
97053   if( rc!=SQLITE_NOTFOUND ){
97054     if( aFcntl[0] ){
97055       sqlite3ErrorMsg(pParse, "%s", aFcntl[0]);
97056       sqlite3_free(aFcntl[0]);
97057     }
97058     pParse->nErr++;
97059     pParse->rc = rc;
97060     goto pragma_out;
97061   }
97062 
97063   /* Locate the pragma in the lookup table */
97064   lwr = 0;
97065   upr = ArraySize(aPragmaNames)-1;
97066   while( lwr<=upr ){
97067     mid = (lwr+upr)/2;
97068     rc = sqlite3_stricmp(zLeft, aPragmaNames[mid].zName);
97069     if( rc==0 ) break;
97070     if( rc<0 ){
97071       upr = mid - 1;
97072     }else{
97073       lwr = mid + 1;
97074     }
97075   }
97076   if( lwr>upr ) goto pragma_out;
97077 
97078   /* Make sure the database schema is loaded if the pragma requires that */
97079   if( (aPragmaNames[mid].mPragFlag & PragFlag_NeedSchema)!=0 ){
97080     if( sqlite3ReadSchema(pParse) ) goto pragma_out;
97081   }
97082 
97083   /* Jump to the appropriate pragma handler */
97084   switch( aPragmaNames[mid].ePragTyp ){
97085   
97086 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS) && !defined(SQLITE_OMIT_DEPRECATED)
97087   /*
97088   **  PRAGMA [database.]default_cache_size
97089   **  PRAGMA [database.]default_cache_size=N
97090   **
97091   ** The first form reports the current persistent setting for the
97092   ** page cache size.  The value returned is the maximum number of
97093   ** pages in the page cache.  The second form sets both the current
97094   ** page cache size value and the persistent page cache size value
97095   ** stored in the database file.
97096   **
97097   ** Older versions of SQLite would set the default cache size to a
97098   ** negative number to indicate synchronous=OFF.  These days, synchronous
97099   ** is always on by default regardless of the sign of the default cache
97100   ** size.  But continue to take the absolute value of the default cache
97101   ** size of historical compatibility.
97102   */
97103   case PragTyp_DEFAULT_CACHE_SIZE: {
97104     static const VdbeOpList getCacheSize[] = {
97105       { OP_Transaction, 0, 0,        0},                         /* 0 */
97106       { OP_ReadCookie,  0, 1,        BTREE_DEFAULT_CACHE_SIZE},  /* 1 */
97107       { OP_IfPos,       1, 8,        0},
97108       { OP_Integer,     0, 2,        0},
97109       { OP_Subtract,    1, 2,        1},
97110       { OP_IfPos,       1, 8,        0},
97111       { OP_Integer,     0, 1,        0},                         /* 6 */
97112       { OP_Noop,        0, 0,        0},
97113       { OP_ResultRow,   1, 1,        0},
97114     };
97115     int addr;
97116     sqlite3VdbeUsesBtree(v, iDb);
97117     if( !zRight ){
97118       sqlite3VdbeSetNumCols(v, 1);
97119       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "cache_size", SQLITE_STATIC);
97120       pParse->nMem += 2;
97121       addr = sqlite3VdbeAddOpList(v, ArraySize(getCacheSize), getCacheSize);
97122       sqlite3VdbeChangeP1(v, addr, iDb);
97123       sqlite3VdbeChangeP1(v, addr+1, iDb);
97124       sqlite3VdbeChangeP1(v, addr+6, SQLITE_DEFAULT_CACHE_SIZE);
97125     }else{
97126       int size = sqlite3AbsInt32(sqlite3Atoi(zRight));
97127       sqlite3BeginWriteOperation(pParse, 0, iDb);
97128       sqlite3VdbeAddOp2(v, OP_Integer, size, 1);
97129       sqlite3VdbeAddOp3(v, OP_SetCookie, iDb, BTREE_DEFAULT_CACHE_SIZE, 1);
97130       assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
97131       pDb->pSchema->cache_size = size;
97132       sqlite3BtreeSetCacheSize(pDb->pBt, pDb->pSchema->cache_size);
97133     }
97134     break;
97135   }
97136 #endif /* !SQLITE_OMIT_PAGER_PRAGMAS && !SQLITE_OMIT_DEPRECATED */
97137 
97138 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
97139   /*
97140   **  PRAGMA [database.]page_size
97141   **  PRAGMA [database.]page_size=N
97142   **
97143   ** The first form reports the current setting for the
97144   ** database page size in bytes.  The second form sets the
97145   ** database page size value.  The value can only be set if
97146   ** the database has not yet been created.
97147   */
97148   case PragTyp_PAGE_SIZE: {
97149     Btree *pBt = pDb->pBt;
97150     assert( pBt!=0 );
97151     if( !zRight ){
97152       int size = ALWAYS(pBt) ? sqlite3BtreeGetPageSize(pBt) : 0;
97153       returnSingleInt(pParse, "page_size", size);
97154     }else{
97155       /* Malloc may fail when setting the page-size, as there is an internal
97156       ** buffer that the pager module resizes using sqlite3_realloc().
97157       */
97158       db->nextPagesize = sqlite3Atoi(zRight);
97159       if( SQLITE_NOMEM==sqlite3BtreeSetPageSize(pBt, db->nextPagesize,-1,0) ){
97160         db->mallocFailed = 1;
97161       }
97162     }
97163     break;
97164   }
97165 
97166   /*
97167   **  PRAGMA [database.]secure_delete
97168   **  PRAGMA [database.]secure_delete=ON/OFF
97169   **
97170   ** The first form reports the current setting for the
97171   ** secure_delete flag.  The second form changes the secure_delete
97172   ** flag setting and reports thenew value.
97173   */
97174   case PragTyp_SECURE_DELETE: {
97175     Btree *pBt = pDb->pBt;
97176     int b = -1;
97177     assert( pBt!=0 );
97178     if( zRight ){
97179       b = sqlite3GetBoolean(zRight, 0);
97180     }
97181     if( pId2->n==0 && b>=0 ){
97182       int ii;
97183       for(ii=0; ii<db->nDb; ii++){
97184         sqlite3BtreeSecureDelete(db->aDb[ii].pBt, b);
97185       }
97186     }
97187     b = sqlite3BtreeSecureDelete(pBt, b);
97188     returnSingleInt(pParse, "secure_delete", b);
97189     break;
97190   }
97191 
97192   /*
97193   **  PRAGMA [database.]max_page_count
97194   **  PRAGMA [database.]max_page_count=N
97195   **
97196   ** The first form reports the current setting for the
97197   ** maximum number of pages in the database file.  The 
97198   ** second form attempts to change this setting.  Both
97199   ** forms return the current setting.
97200   **
97201   ** The absolute value of N is used.  This is undocumented and might
97202   ** change.  The only purpose is to provide an easy way to test
97203   ** the sqlite3AbsInt32() function.
97204   **
97205   **  PRAGMA [database.]page_count
97206   **
97207   ** Return the number of pages in the specified database.
97208   */
97209   case PragTyp_PAGE_COUNT: {
97210     int iReg;
97211     sqlite3CodeVerifySchema(pParse, iDb);
97212     iReg = ++pParse->nMem;
97213     if( sqlite3Tolower(zLeft[0])=='p' ){
97214       sqlite3VdbeAddOp2(v, OP_Pagecount, iDb, iReg);
97215     }else{
97216       sqlite3VdbeAddOp3(v, OP_MaxPgcnt, iDb, iReg, 
97217                         sqlite3AbsInt32(sqlite3Atoi(zRight)));
97218     }
97219     sqlite3VdbeAddOp2(v, OP_ResultRow, iReg, 1);
97220     sqlite3VdbeSetNumCols(v, 1);
97221     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, zLeft, SQLITE_TRANSIENT);
97222     break;
97223   }
97224 
97225   /*
97226   **  PRAGMA [database.]locking_mode
97227   **  PRAGMA [database.]locking_mode = (normal|exclusive)
97228   */
97229   case PragTyp_LOCKING_MODE: {
97230     const char *zRet = "normal";
97231     int eMode = getLockingMode(zRight);
97232 
97233     if( pId2->n==0 && eMode==PAGER_LOCKINGMODE_QUERY ){
97234       /* Simple "PRAGMA locking_mode;" statement. This is a query for
97235       ** the current default locking mode (which may be different to
97236       ** the locking-mode of the main database).
97237       */
97238       eMode = db->dfltLockMode;
97239     }else{
97240       Pager *pPager;
97241       if( pId2->n==0 ){
97242         /* This indicates that no database name was specified as part
97243         ** of the PRAGMA command. In this case the locking-mode must be
97244         ** set on all attached databases, as well as the main db file.
97245         **
97246         ** Also, the sqlite3.dfltLockMode variable is set so that
97247         ** any subsequently attached databases also use the specified
97248         ** locking mode.
97249         */
97250         int ii;
97251         assert(pDb==&db->aDb[0]);
97252         for(ii=2; ii<db->nDb; ii++){
97253           pPager = sqlite3BtreePager(db->aDb[ii].pBt);
97254           sqlite3PagerLockingMode(pPager, eMode);
97255         }
97256         db->dfltLockMode = (u8)eMode;
97257       }
97258       pPager = sqlite3BtreePager(pDb->pBt);
97259       eMode = sqlite3PagerLockingMode(pPager, eMode);
97260     }
97261 
97262     assert( eMode==PAGER_LOCKINGMODE_NORMAL
97263             || eMode==PAGER_LOCKINGMODE_EXCLUSIVE );
97264     if( eMode==PAGER_LOCKINGMODE_EXCLUSIVE ){
97265       zRet = "exclusive";
97266     }
97267     sqlite3VdbeSetNumCols(v, 1);
97268     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "locking_mode", SQLITE_STATIC);
97269     sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, zRet, 0);
97270     sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
97271     break;
97272   }
97273 
97274   /*
97275   **  PRAGMA [database.]journal_mode
97276   **  PRAGMA [database.]journal_mode =
97277   **                      (delete|persist|off|truncate|memory|wal|off)
97278   */
97279   case PragTyp_JOURNAL_MODE: {
97280     int eMode;        /* One of the PAGER_JOURNALMODE_XXX symbols */
97281     int ii;           /* Loop counter */
97282 
97283     sqlite3VdbeSetNumCols(v, 1);
97284     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "journal_mode", SQLITE_STATIC);
97285 
97286     if( zRight==0 ){
97287       /* If there is no "=MODE" part of the pragma, do a query for the
97288       ** current mode */
97289       eMode = PAGER_JOURNALMODE_QUERY;
97290     }else{
97291       const char *zMode;
97292       int n = sqlite3Strlen30(zRight);
97293       for(eMode=0; (zMode = sqlite3JournalModename(eMode))!=0; eMode++){
97294         if( sqlite3StrNICmp(zRight, zMode, n)==0 ) break;
97295       }
97296       if( !zMode ){
97297         /* If the "=MODE" part does not match any known journal mode,
97298         ** then do a query */
97299         eMode = PAGER_JOURNALMODE_QUERY;
97300       }
97301     }
97302     if( eMode==PAGER_JOURNALMODE_QUERY && pId2->n==0 ){
97303       /* Convert "PRAGMA journal_mode" into "PRAGMA main.journal_mode" */
97304       iDb = 0;
97305       pId2->n = 1;
97306     }
97307     for(ii=db->nDb-1; ii>=0; ii--){
97308       if( db->aDb[ii].pBt && (ii==iDb || pId2->n==0) ){
97309         sqlite3VdbeUsesBtree(v, ii);
97310         sqlite3VdbeAddOp3(v, OP_JournalMode, ii, 1, eMode);
97311       }
97312     }
97313     sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
97314     break;
97315   }
97316 
97317   /*
97318   **  PRAGMA [database.]journal_size_limit
97319   **  PRAGMA [database.]journal_size_limit=N
97320   **
97321   ** Get or set the size limit on rollback journal files.
97322   */
97323   case PragTyp_JOURNAL_SIZE_LIMIT: {
97324     Pager *pPager = sqlite3BtreePager(pDb->pBt);
97325     i64 iLimit = -2;
97326     if( zRight ){
97327       sqlite3Atoi64(zRight, &iLimit, sqlite3Strlen30(zRight), SQLITE_UTF8);
97328       if( iLimit<-1 ) iLimit = -1;
97329     }
97330     iLimit = sqlite3PagerJournalSizeLimit(pPager, iLimit);
97331     returnSingleInt(pParse, "journal_size_limit", iLimit);
97332     break;
97333   }
97334 
97335 #endif /* SQLITE_OMIT_PAGER_PRAGMAS */
97336 
97337   /*
97338   **  PRAGMA [database.]auto_vacuum
97339   **  PRAGMA [database.]auto_vacuum=N
97340   **
97341   ** Get or set the value of the database 'auto-vacuum' parameter.
97342   ** The value is one of:  0 NONE 1 FULL 2 INCREMENTAL
97343   */
97344 #ifndef SQLITE_OMIT_AUTOVACUUM
97345   case PragTyp_AUTO_VACUUM: {
97346     Btree *pBt = pDb->pBt;
97347     assert( pBt!=0 );
97348     if( !zRight ){
97349       returnSingleInt(pParse, "auto_vacuum", sqlite3BtreeGetAutoVacuum(pBt));
97350     }else{
97351       int eAuto = getAutoVacuum(zRight);
97352       assert( eAuto>=0 && eAuto<=2 );
97353       db->nextAutovac = (u8)eAuto;
97354       /* Call SetAutoVacuum() to set initialize the internal auto and
97355       ** incr-vacuum flags. This is required in case this connection
97356       ** creates the database file. It is important that it is created
97357       ** as an auto-vacuum capable db.
97358       */
97359       rc = sqlite3BtreeSetAutoVacuum(pBt, eAuto);
97360       if( rc==SQLITE_OK && (eAuto==1 || eAuto==2) ){
97361         /* When setting the auto_vacuum mode to either "full" or 
97362         ** "incremental", write the value of meta[6] in the database
97363         ** file. Before writing to meta[6], check that meta[3] indicates
97364         ** that this really is an auto-vacuum capable database.
97365         */
97366         static const VdbeOpList setMeta6[] = {
97367           { OP_Transaction,    0,         1,                 0},    /* 0 */
97368           { OP_ReadCookie,     0,         1,         BTREE_LARGEST_ROOT_PAGE},
97369           { OP_If,             1,         0,                 0},    /* 2 */
97370           { OP_Halt,           SQLITE_OK, OE_Abort,          0},    /* 3 */
97371           { OP_Integer,        0,         1,                 0},    /* 4 */
97372           { OP_SetCookie,      0,         BTREE_INCR_VACUUM, 1},    /* 5 */
97373         };
97374         int iAddr;
97375         iAddr = sqlite3VdbeAddOpList(v, ArraySize(setMeta6), setMeta6);
97376         sqlite3VdbeChangeP1(v, iAddr, iDb);
97377         sqlite3VdbeChangeP1(v, iAddr+1, iDb);
97378         sqlite3VdbeChangeP2(v, iAddr+2, iAddr+4);
97379         sqlite3VdbeChangeP1(v, iAddr+4, eAuto-1);
97380         sqlite3VdbeChangeP1(v, iAddr+5, iDb);
97381         sqlite3VdbeUsesBtree(v, iDb);
97382       }
97383     }
97384     break;
97385   }
97386 #endif
97387 
97388   /*
97389   **  PRAGMA [database.]incremental_vacuum(N)
97390   **
97391   ** Do N steps of incremental vacuuming on a database.
97392   */
97393 #ifndef SQLITE_OMIT_AUTOVACUUM
97394   case PragTyp_INCREMENTAL_VACUUM: {
97395     int iLimit, addr;
97396     if( zRight==0 || !sqlite3GetInt32(zRight, &iLimit) || iLimit<=0 ){
97397       iLimit = 0x7fffffff;
97398     }
97399     sqlite3BeginWriteOperation(pParse, 0, iDb);
97400     sqlite3VdbeAddOp2(v, OP_Integer, iLimit, 1);
97401     addr = sqlite3VdbeAddOp1(v, OP_IncrVacuum, iDb);
97402     sqlite3VdbeAddOp1(v, OP_ResultRow, 1);
97403     sqlite3VdbeAddOp2(v, OP_AddImm, 1, -1);
97404     sqlite3VdbeAddOp2(v, OP_IfPos, 1, addr);
97405     sqlite3VdbeJumpHere(v, addr);
97406     break;
97407   }
97408 #endif
97409 
97410 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
97411   /*
97412   **  PRAGMA [database.]cache_size
97413   **  PRAGMA [database.]cache_size=N
97414   **
97415   ** The first form reports the current local setting for the
97416   ** page cache size. The second form sets the local
97417   ** page cache size value.  If N is positive then that is the
97418   ** number of pages in the cache.  If N is negative, then the
97419   ** number of pages is adjusted so that the cache uses -N kibibytes
97420   ** of memory.
97421   */
97422   case PragTyp_CACHE_SIZE: {
97423     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
97424     if( !zRight ){
97425       returnSingleInt(pParse, "cache_size", pDb->pSchema->cache_size);
97426     }else{
97427       int size = sqlite3Atoi(zRight);
97428       pDb->pSchema->cache_size = size;
97429       sqlite3BtreeSetCacheSize(pDb->pBt, pDb->pSchema->cache_size);
97430     }
97431     break;
97432   }
97433 
97434   /*
97435   **  PRAGMA [database.]mmap_size(N)
97436   **
97437   ** Used to set mapping size limit. The mapping size limit is
97438   ** used to limit the aggregate size of all memory mapped regions of the
97439   ** database file. If this parameter is set to zero, then memory mapping
97440   ** is not used at all.  If N is negative, then the default memory map
97441   ** limit determined by sqlite3_config(SQLITE_CONFIG_MMAP_SIZE) is set.
97442   ** The parameter N is measured in bytes.
97443   **
97444   ** This value is advisory.  The underlying VFS is free to memory map
97445   ** as little or as much as it wants.  Except, if N is set to 0 then the
97446   ** upper layers will never invoke the xFetch interfaces to the VFS.
97447   */
97448   case PragTyp_MMAP_SIZE: {
97449     sqlite3_int64 sz;
97450 #if SQLITE_MAX_MMAP_SIZE>0
97451     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
97452     if( zRight ){
97453       int ii;
97454       sqlite3Atoi64(zRight, &sz, sqlite3Strlen30(zRight), SQLITE_UTF8);
97455       if( sz<0 ) sz = sqlite3GlobalConfig.szMmap;
97456       if( pId2->n==0 ) db->szMmap = sz;
97457       for(ii=db->nDb-1; ii>=0; ii--){
97458         if( db->aDb[ii].pBt && (ii==iDb || pId2->n==0) ){
97459           sqlite3BtreeSetMmapLimit(db->aDb[ii].pBt, sz);
97460         }
97461       }
97462     }
97463     sz = -1;
97464     rc = sqlite3_file_control(db, zDb, SQLITE_FCNTL_MMAP_SIZE, &sz);
97465 #else
97466     sz = 0;
97467     rc = SQLITE_OK;
97468 #endif
97469     if( rc==SQLITE_OK ){
97470       returnSingleInt(pParse, "mmap_size", sz);
97471     }else if( rc!=SQLITE_NOTFOUND ){
97472       pParse->nErr++;
97473       pParse->rc = rc;
97474     }
97475     break;
97476   }
97477 
97478   /*
97479   **   PRAGMA temp_store
97480   **   PRAGMA temp_store = "default"|"memory"|"file"
97481   **
97482   ** Return or set the local value of the temp_store flag.  Changing
97483   ** the local value does not make changes to the disk file and the default
97484   ** value will be restored the next time the database is opened.
97485   **
97486   ** Note that it is possible for the library compile-time options to
97487   ** override this setting
97488   */
97489   case PragTyp_TEMP_STORE: {
97490     if( !zRight ){
97491       returnSingleInt(pParse, "temp_store", db->temp_store);
97492     }else{
97493       changeTempStorage(pParse, zRight);
97494     }
97495     break;
97496   }
97497 
97498   /*
97499   **   PRAGMA temp_store_directory
97500   **   PRAGMA temp_store_directory = ""|"directory_name"
97501   **
97502   ** Return or set the local value of the temp_store_directory flag.  Changing
97503   ** the value sets a specific directory to be used for temporary files.
97504   ** Setting to a null string reverts to the default temporary directory search.
97505   ** If temporary directory is changed, then invalidateTempStorage.
97506   **
97507   */
97508   case PragTyp_TEMP_STORE_DIRECTORY: {
97509     if( !zRight ){
97510       if( sqlite3_temp_directory ){
97511         sqlite3VdbeSetNumCols(v, 1);
97512         sqlite3VdbeSetColName(v, 0, COLNAME_NAME, 
97513             "temp_store_directory", SQLITE_STATIC);
97514         sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, sqlite3_temp_directory, 0);
97515         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
97516       }
97517     }else{
97518 #ifndef SQLITE_OMIT_WSD
97519       if( zRight[0] ){
97520         int res;
97521         rc = sqlite3OsAccess(db->pVfs, zRight, SQLITE_ACCESS_READWRITE, &res);
97522         if( rc!=SQLITE_OK || res==0 ){
97523           sqlite3ErrorMsg(pParse, "not a writable directory");
97524           goto pragma_out;
97525         }
97526       }
97527       if( SQLITE_TEMP_STORE==0
97528        || (SQLITE_TEMP_STORE==1 && db->temp_store<=1)
97529        || (SQLITE_TEMP_STORE==2 && db->temp_store==1)
97530       ){
97531         invalidateTempStorage(pParse);
97532       }
97533       sqlite3_free(sqlite3_temp_directory);
97534       if( zRight[0] ){
97535         sqlite3_temp_directory = sqlite3_mprintf("%s", zRight);
97536       }else{
97537         sqlite3_temp_directory = 0;
97538       }
97539 #endif /* SQLITE_OMIT_WSD */
97540     }
97541     break;
97542   }
97543 
97544 #if SQLITE_OS_WIN
97545   /*
97546   **   PRAGMA data_store_directory
97547   **   PRAGMA data_store_directory = ""|"directory_name"
97548   **
97549   ** Return or set the local value of the data_store_directory flag.  Changing
97550   ** the value sets a specific directory to be used for database files that
97551   ** were specified with a relative pathname.  Setting to a null string reverts
97552   ** to the default database directory, which for database files specified with
97553   ** a relative path will probably be based on the current directory for the
97554   ** process.  Database file specified with an absolute path are not impacted
97555   ** by this setting, regardless of its value.
97556   **
97557   */
97558   case PragTyp_DATA_STORE_DIRECTORY: {
97559     if( !zRight ){
97560       if( sqlite3_data_directory ){
97561         sqlite3VdbeSetNumCols(v, 1);
97562         sqlite3VdbeSetColName(v, 0, COLNAME_NAME, 
97563             "data_store_directory", SQLITE_STATIC);
97564         sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, sqlite3_data_directory, 0);
97565         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
97566       }
97567     }else{
97568 #ifndef SQLITE_OMIT_WSD
97569       if( zRight[0] ){
97570         int res;
97571         rc = sqlite3OsAccess(db->pVfs, zRight, SQLITE_ACCESS_READWRITE, &res);
97572         if( rc!=SQLITE_OK || res==0 ){
97573           sqlite3ErrorMsg(pParse, "not a writable directory");
97574           goto pragma_out;
97575         }
97576       }
97577       sqlite3_free(sqlite3_data_directory);
97578       if( zRight[0] ){
97579         sqlite3_data_directory = sqlite3_mprintf("%s", zRight);
97580       }else{
97581         sqlite3_data_directory = 0;
97582       }
97583 #endif /* SQLITE_OMIT_WSD */
97584     }
97585     break;
97586   }
97587 #endif
97588 
97589 #if SQLITE_ENABLE_LOCKING_STYLE
97590   /*
97591   **   PRAGMA [database.]lock_proxy_file
97592   **   PRAGMA [database.]lock_proxy_file = ":auto:"|"lock_file_path"
97593   **
97594   ** Return or set the value of the lock_proxy_file flag.  Changing
97595   ** the value sets a specific file to be used for database access locks.
97596   **
97597   */
97598   case PragTyp_LOCK_PROXY_FILE: {
97599     if( !zRight ){
97600       Pager *pPager = sqlite3BtreePager(pDb->pBt);
97601       char *proxy_file_path = NULL;
97602       sqlite3_file *pFile = sqlite3PagerFile(pPager);
97603       sqlite3OsFileControlHint(pFile, SQLITE_GET_LOCKPROXYFILE, 
97604                            &proxy_file_path);
97605       
97606       if( proxy_file_path ){
97607         sqlite3VdbeSetNumCols(v, 1);
97608         sqlite3VdbeSetColName(v, 0, COLNAME_NAME, 
97609                               "lock_proxy_file", SQLITE_STATIC);
97610         sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, proxy_file_path, 0);
97611         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
97612       }
97613     }else{
97614       Pager *pPager = sqlite3BtreePager(pDb->pBt);
97615       sqlite3_file *pFile = sqlite3PagerFile(pPager);
97616       int res;
97617       if( zRight[0] ){
97618         res=sqlite3OsFileControl(pFile, SQLITE_SET_LOCKPROXYFILE, 
97619                                      zRight);
97620       } else {
97621         res=sqlite3OsFileControl(pFile, SQLITE_SET_LOCKPROXYFILE, 
97622                                      NULL);
97623       }
97624       if( res!=SQLITE_OK ){
97625         sqlite3ErrorMsg(pParse, "failed to set lock proxy file");
97626         goto pragma_out;
97627       }
97628     }
97629     break;
97630   }
97631 #endif /* SQLITE_ENABLE_LOCKING_STYLE */      
97632     
97633   /*
97634   **   PRAGMA [database.]synchronous
97635   **   PRAGMA [database.]synchronous=OFF|ON|NORMAL|FULL
97636   **
97637   ** Return or set the local value of the synchronous flag.  Changing
97638   ** the local value does not make changes to the disk file and the
97639   ** default value will be restored the next time the database is
97640   ** opened.
97641   */
97642   case PragTyp_SYNCHRONOUS: {
97643     if( !zRight ){
97644       returnSingleInt(pParse, "synchronous", pDb->safety_level-1);
97645     }else{
97646       if( !db->autoCommit ){
97647         sqlite3ErrorMsg(pParse, 
97648             "Safety level may not be changed inside a transaction");
97649       }else{
97650         pDb->safety_level = getSafetyLevel(zRight,0,1)+1;
97651         setAllPagerFlags(db);
97652       }
97653     }
97654     break;
97655   }
97656 #endif /* SQLITE_OMIT_PAGER_PRAGMAS */
97657 
97658 #ifndef SQLITE_OMIT_FLAG_PRAGMAS
97659   case PragTyp_FLAG: {
97660     if( zRight==0 ){
97661       returnSingleInt(pParse, aPragmaNames[mid].zName,
97662                      (db->flags & aPragmaNames[mid].iArg)!=0 );
97663     }else{
97664       int mask = aPragmaNames[mid].iArg;    /* Mask of bits to set or clear. */
97665       if( db->autoCommit==0 ){
97666         /* Foreign key support may not be enabled or disabled while not
97667         ** in auto-commit mode.  */
97668         mask &= ~(SQLITE_ForeignKeys);
97669       }
97670 
97671       if( sqlite3GetBoolean(zRight, 0) ){
97672         db->flags |= mask;
97673       }else{
97674         db->flags &= ~mask;
97675         if( mask==SQLITE_DeferFKs ) db->nDeferredImmCons = 0;
97676       }
97677 
97678       /* Many of the flag-pragmas modify the code generated by the SQL 
97679       ** compiler (eg. count_changes). So add an opcode to expire all
97680       ** compiled SQL statements after modifying a pragma value.
97681       */
97682       sqlite3VdbeAddOp2(v, OP_Expire, 0, 0);
97683       setAllPagerFlags(db);
97684     }
97685     break;
97686   }
97687 #endif /* SQLITE_OMIT_FLAG_PRAGMAS */
97688 
97689 #ifndef SQLITE_OMIT_SCHEMA_PRAGMAS
97690   /*
97691   **   PRAGMA table_info(<table>)
97692   **
97693   ** Return a single row for each column of the named table. The columns of
97694   ** the returned data set are:
97695   **
97696   ** cid:        Column id (numbered from left to right, starting at 0)
97697   ** name:       Column name
97698   ** type:       Column declaration type.
97699   ** notnull:    True if 'NOT NULL' is part of column declaration
97700   ** dflt_value: The default value for the column, if any.
97701   */
97702   case PragTyp_TABLE_INFO: if( zRight ){
97703     Table *pTab;
97704     pTab = sqlite3FindTable(db, zRight, zDb);
97705     if( pTab ){
97706       int i, k;
97707       int nHidden = 0;
97708       Column *pCol;
97709       Index *pPk = sqlite3PrimaryKeyIndex(pTab);
97710       sqlite3VdbeSetNumCols(v, 6);
97711       pParse->nMem = 6;
97712       sqlite3CodeVerifySchema(pParse, iDb);
97713       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "cid", SQLITE_STATIC);
97714       sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "name", SQLITE_STATIC);
97715       sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "type", SQLITE_STATIC);
97716       sqlite3VdbeSetColName(v, 3, COLNAME_NAME, "notnull", SQLITE_STATIC);
97717       sqlite3VdbeSetColName(v, 4, COLNAME_NAME, "dflt_value", SQLITE_STATIC);
97718       sqlite3VdbeSetColName(v, 5, COLNAME_NAME, "pk", SQLITE_STATIC);
97719       sqlite3ViewGetColumnNames(pParse, pTab);
97720       for(i=0, pCol=pTab->aCol; i<pTab->nCol; i++, pCol++){
97721         if( IsHiddenColumn(pCol) ){
97722           nHidden++;
97723           continue;
97724         }
97725         sqlite3VdbeAddOp2(v, OP_Integer, i-nHidden, 1);
97726         sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, pCol->zName, 0);
97727         sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0,
97728            pCol->zType ? pCol->zType : "", 0);
97729         sqlite3VdbeAddOp2(v, OP_Integer, (pCol->notNull ? 1 : 0), 4);
97730         if( pCol->zDflt ){
97731           sqlite3VdbeAddOp4(v, OP_String8, 0, 5, 0, (char*)pCol->zDflt, 0);
97732         }else{
97733           sqlite3VdbeAddOp2(v, OP_Null, 0, 5);
97734         }
97735         if( (pCol->colFlags & COLFLAG_PRIMKEY)==0 ){
97736           k = 0;
97737         }else if( pPk==0 ){
97738           k = 1;
97739         }else{
97740           for(k=1; ALWAYS(k<=pTab->nCol) && pPk->aiColumn[k-1]!=i; k++){}
97741         }
97742         sqlite3VdbeAddOp2(v, OP_Integer, k, 6);
97743         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 6);
97744       }
97745     }
97746   }
97747   break;
97748 
97749   case PragTyp_STATS: {
97750     Index *pIdx;
97751     HashElem *i;
97752     v = sqlite3GetVdbe(pParse);
97753     sqlite3VdbeSetNumCols(v, 4);
97754     pParse->nMem = 4;
97755     sqlite3CodeVerifySchema(pParse, iDb);
97756     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "table", SQLITE_STATIC);
97757     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "index", SQLITE_STATIC);
97758     sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "width", SQLITE_STATIC);
97759     sqlite3VdbeSetColName(v, 3, COLNAME_NAME, "height", SQLITE_STATIC);
97760     for(i=sqliteHashFirst(&pDb->pSchema->tblHash); i; i=sqliteHashNext(i)){
97761       Table *pTab = sqliteHashData(i);
97762       sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, pTab->zName, 0);
97763       sqlite3VdbeAddOp2(v, OP_Null, 0, 2);
97764       sqlite3VdbeAddOp2(v, OP_Integer,
97765                            (int)sqlite3LogEstToInt(pTab->szTabRow), 3);
97766       sqlite3VdbeAddOp2(v, OP_Integer, (int)pTab->nRowEst, 4);
97767       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 4);
97768       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
97769         sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, pIdx->zName, 0);
97770         sqlite3VdbeAddOp2(v, OP_Integer,
97771                              (int)sqlite3LogEstToInt(pIdx->szIdxRow), 3);
97772         sqlite3VdbeAddOp2(v, OP_Integer, (int)pIdx->aiRowEst[0], 4);
97773         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 4);
97774       }
97775     }
97776   }
97777   break;
97778 
97779   case PragTyp_INDEX_INFO: if( zRight ){
97780     Index *pIdx;
97781     Table *pTab;
97782     pIdx = sqlite3FindIndex(db, zRight, zDb);
97783     if( pIdx ){
97784       int i;
97785       pTab = pIdx->pTable;
97786       sqlite3VdbeSetNumCols(v, 3);
97787       pParse->nMem = 3;
97788       sqlite3CodeVerifySchema(pParse, iDb);
97789       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "seqno", SQLITE_STATIC);
97790       sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "cid", SQLITE_STATIC);
97791       sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "name", SQLITE_STATIC);
97792       for(i=0; i<pIdx->nKeyCol; i++){
97793         i16 cnum = pIdx->aiColumn[i];
97794         sqlite3VdbeAddOp2(v, OP_Integer, i, 1);
97795         sqlite3VdbeAddOp2(v, OP_Integer, cnum, 2);
97796         assert( pTab->nCol>cnum );
97797         sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0, pTab->aCol[cnum].zName, 0);
97798         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 3);
97799       }
97800     }
97801   }
97802   break;
97803 
97804   case PragTyp_INDEX_LIST: if( zRight ){
97805     Index *pIdx;
97806     Table *pTab;
97807     int i;
97808     pTab = sqlite3FindTable(db, zRight, zDb);
97809     if( pTab ){
97810       v = sqlite3GetVdbe(pParse);
97811       sqlite3VdbeSetNumCols(v, 3);
97812       pParse->nMem = 3;
97813       sqlite3CodeVerifySchema(pParse, iDb);
97814       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "seq", SQLITE_STATIC);
97815       sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "name", SQLITE_STATIC);
97816       sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "unique", SQLITE_STATIC);
97817       for(pIdx=pTab->pIndex, i=0; pIdx; pIdx=pIdx->pNext, i++){
97818         sqlite3VdbeAddOp2(v, OP_Integer, i, 1);
97819         sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, pIdx->zName, 0);
97820         sqlite3VdbeAddOp2(v, OP_Integer, pIdx->onError!=OE_None, 3);
97821         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 3);
97822       }
97823     }
97824   }
97825   break;
97826 
97827   case PragTyp_DATABASE_LIST: {
97828     int i;
97829     sqlite3VdbeSetNumCols(v, 3);
97830     pParse->nMem = 3;
97831     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "seq", SQLITE_STATIC);
97832     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "name", SQLITE_STATIC);
97833     sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "file", SQLITE_STATIC);
97834     for(i=0; i<db->nDb; i++){
97835       if( db->aDb[i].pBt==0 ) continue;
97836       assert( db->aDb[i].zName!=0 );
97837       sqlite3VdbeAddOp2(v, OP_Integer, i, 1);
97838       sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, db->aDb[i].zName, 0);
97839       sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0,
97840            sqlite3BtreeGetFilename(db->aDb[i].pBt), 0);
97841       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 3);
97842     }
97843   }
97844   break;
97845 
97846   case PragTyp_COLLATION_LIST: {
97847     int i = 0;
97848     HashElem *p;
97849     sqlite3VdbeSetNumCols(v, 2);
97850     pParse->nMem = 2;
97851     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "seq", SQLITE_STATIC);
97852     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "name", SQLITE_STATIC);
97853     for(p=sqliteHashFirst(&db->aCollSeq); p; p=sqliteHashNext(p)){
97854       CollSeq *pColl = (CollSeq *)sqliteHashData(p);
97855       sqlite3VdbeAddOp2(v, OP_Integer, i++, 1);
97856       sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, pColl->zName, 0);
97857       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 2);
97858     }
97859   }
97860   break;
97861 #endif /* SQLITE_OMIT_SCHEMA_PRAGMAS */
97862 
97863 #ifndef SQLITE_OMIT_FOREIGN_KEY
97864   case PragTyp_FOREIGN_KEY_LIST: if( zRight ){
97865     FKey *pFK;
97866     Table *pTab;
97867     pTab = sqlite3FindTable(db, zRight, zDb);
97868     if( pTab ){
97869       v = sqlite3GetVdbe(pParse);
97870       pFK = pTab->pFKey;
97871       if( pFK ){
97872         int i = 0; 
97873         sqlite3VdbeSetNumCols(v, 8);
97874         pParse->nMem = 8;
97875         sqlite3CodeVerifySchema(pParse, iDb);
97876         sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "id", SQLITE_STATIC);
97877         sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "seq", SQLITE_STATIC);
97878         sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "table", SQLITE_STATIC);
97879         sqlite3VdbeSetColName(v, 3, COLNAME_NAME, "from", SQLITE_STATIC);
97880         sqlite3VdbeSetColName(v, 4, COLNAME_NAME, "to", SQLITE_STATIC);
97881         sqlite3VdbeSetColName(v, 5, COLNAME_NAME, "on_update", SQLITE_STATIC);
97882         sqlite3VdbeSetColName(v, 6, COLNAME_NAME, "on_delete", SQLITE_STATIC);
97883         sqlite3VdbeSetColName(v, 7, COLNAME_NAME, "match", SQLITE_STATIC);
97884         while(pFK){
97885           int j;
97886           for(j=0; j<pFK->nCol; j++){
97887             char *zCol = pFK->aCol[j].zCol;
97888             char *zOnDelete = (char *)actionName(pFK->aAction[0]);
97889             char *zOnUpdate = (char *)actionName(pFK->aAction[1]);
97890             sqlite3VdbeAddOp2(v, OP_Integer, i, 1);
97891             sqlite3VdbeAddOp2(v, OP_Integer, j, 2);
97892             sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0, pFK->zTo, 0);
97893             sqlite3VdbeAddOp4(v, OP_String8, 0, 4, 0,
97894                               pTab->aCol[pFK->aCol[j].iFrom].zName, 0);
97895             sqlite3VdbeAddOp4(v, zCol ? OP_String8 : OP_Null, 0, 5, 0, zCol, 0);
97896             sqlite3VdbeAddOp4(v, OP_String8, 0, 6, 0, zOnUpdate, 0);
97897             sqlite3VdbeAddOp4(v, OP_String8, 0, 7, 0, zOnDelete, 0);
97898             sqlite3VdbeAddOp4(v, OP_String8, 0, 8, 0, "NONE", 0);
97899             sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 8);
97900           }
97901           ++i;
97902           pFK = pFK->pNextFrom;
97903         }
97904       }
97905     }
97906   }
97907   break;
97908 #endif /* !defined(SQLITE_OMIT_FOREIGN_KEY) */
97909 
97910 #ifndef SQLITE_OMIT_FOREIGN_KEY
97911 #ifndef SQLITE_OMIT_TRIGGER
97912   case PragTyp_FOREIGN_KEY_CHECK: {
97913     FKey *pFK;             /* A foreign key constraint */
97914     Table *pTab;           /* Child table contain "REFERENCES" keyword */
97915     Table *pParent;        /* Parent table that child points to */
97916     Index *pIdx;           /* Index in the parent table */
97917     int i;                 /* Loop counter:  Foreign key number for pTab */
97918     int j;                 /* Loop counter:  Field of the foreign key */
97919     HashElem *k;           /* Loop counter:  Next table in schema */
97920     int x;                 /* result variable */
97921     int regResult;         /* 3 registers to hold a result row */
97922     int regKey;            /* Register to hold key for checking the FK */
97923     int regRow;            /* Registers to hold a row from pTab */
97924     int addrTop;           /* Top of a loop checking foreign keys */
97925     int addrOk;            /* Jump here if the key is OK */
97926     int *aiCols;           /* child to parent column mapping */
97927 
97928     regResult = pParse->nMem+1;
97929     pParse->nMem += 4;
97930     regKey = ++pParse->nMem;
97931     regRow = ++pParse->nMem;
97932     v = sqlite3GetVdbe(pParse);
97933     sqlite3VdbeSetNumCols(v, 4);
97934     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "table", SQLITE_STATIC);
97935     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "rowid", SQLITE_STATIC);
97936     sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "parent", SQLITE_STATIC);
97937     sqlite3VdbeSetColName(v, 3, COLNAME_NAME, "fkid", SQLITE_STATIC);
97938     sqlite3CodeVerifySchema(pParse, iDb);
97939     k = sqliteHashFirst(&db->aDb[iDb].pSchema->tblHash);
97940     while( k ){
97941       if( zRight ){
97942         pTab = sqlite3LocateTable(pParse, 0, zRight, zDb);
97943         k = 0;
97944       }else{
97945         pTab = (Table*)sqliteHashData(k);
97946         k = sqliteHashNext(k);
97947       }
97948       if( pTab==0 || pTab->pFKey==0 ) continue;
97949       sqlite3TableLock(pParse, iDb, pTab->tnum, 0, pTab->zName);
97950       if( pTab->nCol+regRow>pParse->nMem ) pParse->nMem = pTab->nCol + regRow;
97951       sqlite3OpenTable(pParse, 0, iDb, pTab, OP_OpenRead);
97952       sqlite3VdbeAddOp4(v, OP_String8, 0, regResult, 0, pTab->zName,
97953                         P4_TRANSIENT);
97954       for(i=1, pFK=pTab->pFKey; pFK; i++, pFK=pFK->pNextFrom){
97955         pParent = sqlite3FindTable(db, pFK->zTo, zDb);
97956         if( pParent==0 ) continue;
97957         pIdx = 0;
97958         sqlite3TableLock(pParse, iDb, pParent->tnum, 0, pParent->zName);
97959         x = sqlite3FkLocateIndex(pParse, pParent, pFK, &pIdx, 0);
97960         if( x==0 ){
97961           if( pIdx==0 ){
97962             sqlite3OpenTable(pParse, i, iDb, pParent, OP_OpenRead);
97963           }else{
97964             sqlite3VdbeAddOp3(v, OP_OpenRead, i, pIdx->tnum, iDb);
97965             sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
97966           }
97967         }else{
97968           k = 0;
97969           break;
97970         }
97971       }
97972       assert( pParse->nErr>0 || pFK==0 );
97973       if( pFK ) break;
97974       if( pParse->nTab<i ) pParse->nTab = i;
97975       addrTop = sqlite3VdbeAddOp1(v, OP_Rewind, 0);
97976       for(i=1, pFK=pTab->pFKey; pFK; i++, pFK=pFK->pNextFrom){
97977         pParent = sqlite3FindTable(db, pFK->zTo, zDb);
97978         pIdx = 0;
97979         aiCols = 0;
97980         if( pParent ){
97981           x = sqlite3FkLocateIndex(pParse, pParent, pFK, &pIdx, &aiCols);
97982           assert( x==0 );
97983         }
97984         addrOk = sqlite3VdbeMakeLabel(v);
97985         if( pParent && pIdx==0 ){
97986           int iKey = pFK->aCol[0].iFrom;
97987           assert( iKey>=0 && iKey<pTab->nCol );
97988           if( iKey!=pTab->iPKey ){
97989             sqlite3VdbeAddOp3(v, OP_Column, 0, iKey, regRow);
97990             sqlite3ColumnDefault(v, pTab, iKey, regRow);
97991             sqlite3VdbeAddOp2(v, OP_IsNull, regRow, addrOk);
97992             sqlite3VdbeAddOp2(v, OP_MustBeInt, regRow,
97993                sqlite3VdbeCurrentAddr(v)+3);
97994           }else{
97995             sqlite3VdbeAddOp2(v, OP_Rowid, 0, regRow);
97996           }
97997           sqlite3VdbeAddOp3(v, OP_NotExists, i, 0, regRow);
97998           sqlite3VdbeAddOp2(v, OP_Goto, 0, addrOk);
97999           sqlite3VdbeJumpHere(v, sqlite3VdbeCurrentAddr(v)-2);
98000         }else{
98001           for(j=0; j<pFK->nCol; j++){
98002             sqlite3ExprCodeGetColumnOfTable(v, pTab, 0,
98003                             aiCols ? aiCols[j] : pFK->aCol[j].iFrom, regRow+j);
98004             sqlite3VdbeAddOp2(v, OP_IsNull, regRow+j, addrOk);
98005           }
98006           if( pParent ){
98007             sqlite3VdbeAddOp3(v, OP_MakeRecord, regRow, pFK->nCol, regKey);
98008             sqlite3VdbeChangeP4(v, -1,
98009                      sqlite3IndexAffinityStr(v,pIdx), P4_TRANSIENT);
98010             sqlite3VdbeAddOp4Int(v, OP_Found, i, addrOk, regKey, 0);
98011           }
98012         }
98013         sqlite3VdbeAddOp2(v, OP_Rowid, 0, regResult+1);
98014         sqlite3VdbeAddOp4(v, OP_String8, 0, regResult+2, 0, 
98015                           pFK->zTo, P4_TRANSIENT);
98016         sqlite3VdbeAddOp2(v, OP_Integer, i-1, regResult+3);
98017         sqlite3VdbeAddOp2(v, OP_ResultRow, regResult, 4);
98018         sqlite3VdbeResolveLabel(v, addrOk);
98019         sqlite3DbFree(db, aiCols);
98020       }
98021       sqlite3VdbeAddOp2(v, OP_Next, 0, addrTop+1);
98022       sqlite3VdbeJumpHere(v, addrTop);
98023     }
98024   }
98025   break;
98026 #endif /* !defined(SQLITE_OMIT_TRIGGER) */
98027 #endif /* !defined(SQLITE_OMIT_FOREIGN_KEY) */
98028 
98029 #ifndef NDEBUG
98030   case PragTyp_PARSER_TRACE: {
98031     if( zRight ){
98032       if( sqlite3GetBoolean(zRight, 0) ){
98033         sqlite3ParserTrace(stderr, "parser: ");
98034       }else{
98035         sqlite3ParserTrace(0, 0);
98036       }
98037     }
98038   }
98039   break;
98040 #endif
98041 
98042   /* Reinstall the LIKE and GLOB functions.  The variant of LIKE
98043   ** used will be case sensitive or not depending on the RHS.
98044   */
98045   case PragTyp_CASE_SENSITIVE_LIKE: {
98046     if( zRight ){
98047       sqlite3RegisterLikeFunctions(db, sqlite3GetBoolean(zRight, 0));
98048     }
98049   }
98050   break;
98051 
98052 #ifndef SQLITE_INTEGRITY_CHECK_ERROR_MAX
98053 # define SQLITE_INTEGRITY_CHECK_ERROR_MAX 100
98054 #endif
98055 
98056 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
98057   /* Pragma "quick_check" is reduced version of 
98058   ** integrity_check designed to detect most database corruption
98059   ** without most of the overhead of a full integrity-check.
98060   */
98061   case PragTyp_INTEGRITY_CHECK: {
98062     int i, j, addr, mxErr;
98063 
98064     /* Code that appears at the end of the integrity check.  If no error
98065     ** messages have been generated, output OK.  Otherwise output the
98066     ** error message
98067     */
98068     static const VdbeOpList endCode[] = {
98069       { OP_AddImm,      1, 0,        0},    /* 0 */
98070       { OP_IfNeg,       1, 0,        0},    /* 1 */
98071       { OP_String8,     0, 3,        0},    /* 2 */
98072       { OP_ResultRow,   3, 1,        0},
98073     };
98074 
98075     int isQuick = (sqlite3Tolower(zLeft[0])=='q');
98076 
98077     /* If the PRAGMA command was of the form "PRAGMA <db>.integrity_check",
98078     ** then iDb is set to the index of the database identified by <db>.
98079     ** In this case, the integrity of database iDb only is verified by
98080     ** the VDBE created below.
98081     **
98082     ** Otherwise, if the command was simply "PRAGMA integrity_check" (or
98083     ** "PRAGMA quick_check"), then iDb is set to 0. In this case, set iDb
98084     ** to -1 here, to indicate that the VDBE should verify the integrity
98085     ** of all attached databases.  */
98086     assert( iDb>=0 );
98087     assert( iDb==0 || pId2->z );
98088     if( pId2->z==0 ) iDb = -1;
98089 
98090     /* Initialize the VDBE program */
98091     pParse->nMem = 6;
98092     sqlite3VdbeSetNumCols(v, 1);
98093     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "integrity_check", SQLITE_STATIC);
98094 
98095     /* Set the maximum error count */
98096     mxErr = SQLITE_INTEGRITY_CHECK_ERROR_MAX;
98097     if( zRight ){
98098       sqlite3GetInt32(zRight, &mxErr);
98099       if( mxErr<=0 ){
98100         mxErr = SQLITE_INTEGRITY_CHECK_ERROR_MAX;
98101       }
98102     }
98103     sqlite3VdbeAddOp2(v, OP_Integer, mxErr, 1);  /* reg[1] holds errors left */
98104 
98105     /* Do an integrity check on each database file */
98106     for(i=0; i<db->nDb; i++){
98107       HashElem *x;
98108       Hash *pTbls;
98109       int cnt = 0;
98110 
98111       if( OMIT_TEMPDB && i==1 ) continue;
98112       if( iDb>=0 && i!=iDb ) continue;
98113 
98114       sqlite3CodeVerifySchema(pParse, i);
98115       addr = sqlite3VdbeAddOp1(v, OP_IfPos, 1); /* Halt if out of errors */
98116       sqlite3VdbeAddOp2(v, OP_Halt, 0, 0);
98117       sqlite3VdbeJumpHere(v, addr);
98118 
98119       /* Do an integrity check of the B-Tree
98120       **
98121       ** Begin by filling registers 2, 3, ... with the root pages numbers
98122       ** for all tables and indices in the database.
98123       */
98124       assert( sqlite3SchemaMutexHeld(db, i, 0) );
98125       pTbls = &db->aDb[i].pSchema->tblHash;
98126       for(x=sqliteHashFirst(pTbls); x; x=sqliteHashNext(x)){
98127         Table *pTab = sqliteHashData(x);
98128         Index *pIdx;
98129         if( HasRowid(pTab) ){
98130           sqlite3VdbeAddOp2(v, OP_Integer, pTab->tnum, 2+cnt);
98131           VdbeComment((v, "%s", pTab->zName));
98132           cnt++;
98133         }
98134         for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
98135           sqlite3VdbeAddOp2(v, OP_Integer, pIdx->tnum, 2+cnt);
98136           VdbeComment((v, "%s", pIdx->zName));
98137           cnt++;
98138         }
98139       }
98140 
98141       /* Make sure sufficient number of registers have been allocated */
98142       pParse->nMem = MAX( pParse->nMem, cnt+8 );
98143 
98144       /* Do the b-tree integrity checks */
98145       sqlite3VdbeAddOp3(v, OP_IntegrityCk, 2, cnt, 1);
98146       sqlite3VdbeChangeP5(v, (u8)i);
98147       addr = sqlite3VdbeAddOp1(v, OP_IsNull, 2);
98148       sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0,
98149          sqlite3MPrintf(db, "*** in database %s ***\n", db->aDb[i].zName),
98150          P4_DYNAMIC);
98151       sqlite3VdbeAddOp2(v, OP_Move, 2, 4);
98152       sqlite3VdbeAddOp3(v, OP_Concat, 4, 3, 2);
98153       sqlite3VdbeAddOp2(v, OP_ResultRow, 2, 1);
98154       sqlite3VdbeJumpHere(v, addr);
98155 
98156       /* Make sure all the indices are constructed correctly.
98157       */
98158       for(x=sqliteHashFirst(pTbls); x && !isQuick; x=sqliteHashNext(x)){
98159         Table *pTab = sqliteHashData(x);
98160         Index *pIdx, *pPk;
98161         int loopTop;
98162         int iDataCur, iIdxCur;
98163 
98164         if( pTab->pIndex==0 ) continue;
98165         pPk = HasRowid(pTab) ? 0 : sqlite3PrimaryKeyIndex(pTab);
98166         addr = sqlite3VdbeAddOp1(v, OP_IfPos, 1);  /* Stop if out of errors */
98167         sqlite3VdbeAddOp2(v, OP_Halt, 0, 0);
98168         sqlite3VdbeJumpHere(v, addr);
98169         sqlite3ExprCacheClear(pParse);
98170         sqlite3OpenTableAndIndices(pParse, pTab, OP_OpenRead,
98171                                    1, 0, &iDataCur, &iIdxCur);
98172         sqlite3VdbeAddOp2(v, OP_Integer, 0, 7);
98173         for(j=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, j++){
98174           sqlite3VdbeAddOp2(v, OP_Integer, 0, 8+j); /* index entries counter */
98175         }
98176         pParse->nMem = MAX(pParse->nMem, 8+j);
98177         sqlite3VdbeAddOp2(v, OP_Rewind, iDataCur, 0);
98178         loopTop = sqlite3VdbeAddOp2(v, OP_AddImm, 7, 1);
98179         for(j=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, j++){
98180           int jmp2, jmp3, jmp4;
98181           int r1;
98182           if( pPk==pIdx ) continue;
98183           r1 = sqlite3GenerateIndexKey(pParse, pIdx, iDataCur, 0, 0, &jmp3);
98184           sqlite3VdbeAddOp2(v, OP_AddImm, 8+j, 1);  /* increment entry count */
98185           jmp2 = sqlite3VdbeAddOp4Int(v, OP_Found, iIdxCur+j, 0, r1,
98186                                       pIdx->nColumn);
98187           sqlite3VdbeAddOp2(v, OP_AddImm, 1, -1); /* Decrement error limit */
98188           sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0, "row ", P4_STATIC);
98189           sqlite3VdbeAddOp3(v, OP_Concat, 7, 3, 3);
98190           sqlite3VdbeAddOp4(v, OP_String8, 0, 4, 0, " missing from index ",
98191                             P4_STATIC);
98192           sqlite3VdbeAddOp3(v, OP_Concat, 4, 3, 3);
98193           sqlite3VdbeAddOp4(v, OP_String8, 0, 4, 0, pIdx->zName, P4_TRANSIENT);
98194           sqlite3VdbeAddOp3(v, OP_Concat, 4, 3, 3);
98195           sqlite3VdbeAddOp2(v, OP_ResultRow, 3, 1);
98196           jmp4 = sqlite3VdbeAddOp1(v, OP_IfPos, 1);
98197           sqlite3VdbeAddOp0(v, OP_Halt);
98198           sqlite3VdbeJumpHere(v, jmp4);
98199           sqlite3VdbeJumpHere(v, jmp2);
98200           sqlite3VdbeResolveLabel(v, jmp3);
98201         }
98202         sqlite3VdbeAddOp2(v, OP_Next, iDataCur, loopTop);
98203         sqlite3VdbeJumpHere(v, loopTop-1);
98204 #ifndef SQLITE_OMIT_BTREECOUNT
98205         sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, 
98206                      "wrong # of entries in index ", P4_STATIC);
98207         for(j=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, j++){
98208           if( pPk==pIdx ) continue;
98209           addr = sqlite3VdbeCurrentAddr(v);
98210           sqlite3VdbeAddOp2(v, OP_IfPos, 1, addr+2);
98211           sqlite3VdbeAddOp2(v, OP_Halt, 0, 0);
98212           sqlite3VdbeAddOp2(v, OP_Count, iIdxCur+j, 3);
98213           sqlite3VdbeAddOp3(v, OP_Eq, 8+j, addr+8, 3);
98214           sqlite3VdbeAddOp2(v, OP_AddImm, 1, -1);
98215           sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0, pIdx->zName, P4_TRANSIENT);
98216           sqlite3VdbeAddOp3(v, OP_Concat, 3, 2, 7);
98217           sqlite3VdbeAddOp2(v, OP_ResultRow, 7, 1);
98218         }
98219 #endif /* SQLITE_OMIT_BTREECOUNT */
98220       } 
98221     }
98222     addr = sqlite3VdbeAddOpList(v, ArraySize(endCode), endCode);
98223     sqlite3VdbeChangeP2(v, addr, -mxErr);
98224     sqlite3VdbeJumpHere(v, addr+1);
98225     sqlite3VdbeChangeP4(v, addr+2, "ok", P4_STATIC);
98226   }
98227   break;
98228 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
98229 
98230 #ifndef SQLITE_OMIT_UTF16
98231   /*
98232   **   PRAGMA encoding
98233   **   PRAGMA encoding = "utf-8"|"utf-16"|"utf-16le"|"utf-16be"
98234   **
98235   ** In its first form, this pragma returns the encoding of the main
98236   ** database. If the database is not initialized, it is initialized now.
98237   **
98238   ** The second form of this pragma is a no-op if the main database file
98239   ** has not already been initialized. In this case it sets the default
98240   ** encoding that will be used for the main database file if a new file
98241   ** is created. If an existing main database file is opened, then the
98242   ** default text encoding for the existing database is used.
98243   ** 
98244   ** In all cases new databases created using the ATTACH command are
98245   ** created to use the same default text encoding as the main database. If
98246   ** the main database has not been initialized and/or created when ATTACH
98247   ** is executed, this is done before the ATTACH operation.
98248   **
98249   ** In the second form this pragma sets the text encoding to be used in
98250   ** new database files created using this database handle. It is only
98251   ** useful if invoked immediately after the main database i
98252   */
98253   case PragTyp_ENCODING: {
98254     static const struct EncName {
98255       char *zName;
98256       u8 enc;
98257     } encnames[] = {
98258       { "UTF8",     SQLITE_UTF8        },
98259       { "UTF-8",    SQLITE_UTF8        },  /* Must be element [1] */
98260       { "UTF-16le", SQLITE_UTF16LE     },  /* Must be element [2] */
98261       { "UTF-16be", SQLITE_UTF16BE     },  /* Must be element [3] */
98262       { "UTF16le",  SQLITE_UTF16LE     },
98263       { "UTF16be",  SQLITE_UTF16BE     },
98264       { "UTF-16",   0                  }, /* SQLITE_UTF16NATIVE */
98265       { "UTF16",    0                  }, /* SQLITE_UTF16NATIVE */
98266       { 0, 0 }
98267     };
98268     const struct EncName *pEnc;
98269     if( !zRight ){    /* "PRAGMA encoding" */
98270       if( sqlite3ReadSchema(pParse) ) goto pragma_out;
98271       sqlite3VdbeSetNumCols(v, 1);
98272       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "encoding", SQLITE_STATIC);
98273       sqlite3VdbeAddOp2(v, OP_String8, 0, 1);
98274       assert( encnames[SQLITE_UTF8].enc==SQLITE_UTF8 );
98275       assert( encnames[SQLITE_UTF16LE].enc==SQLITE_UTF16LE );
98276       assert( encnames[SQLITE_UTF16BE].enc==SQLITE_UTF16BE );
98277       sqlite3VdbeChangeP4(v, -1, encnames[ENC(pParse->db)].zName, P4_STATIC);
98278       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
98279     }else{                        /* "PRAGMA encoding = XXX" */
98280       /* Only change the value of sqlite.enc if the database handle is not
98281       ** initialized. If the main database exists, the new sqlite.enc value
98282       ** will be overwritten when the schema is next loaded. If it does not
98283       ** already exists, it will be created to use the new encoding value.
98284       */
98285       if( 
98286         !(DbHasProperty(db, 0, DB_SchemaLoaded)) || 
98287         DbHasProperty(db, 0, DB_Empty) 
98288       ){
98289         for(pEnc=&encnames[0]; pEnc->zName; pEnc++){
98290           if( 0==sqlite3StrICmp(zRight, pEnc->zName) ){
98291             ENC(pParse->db) = pEnc->enc ? pEnc->enc : SQLITE_UTF16NATIVE;
98292             break;
98293           }
98294         }
98295         if( !pEnc->zName ){
98296           sqlite3ErrorMsg(pParse, "unsupported encoding: %s", zRight);
98297         }
98298       }
98299     }
98300   }
98301   break;
98302 #endif /* SQLITE_OMIT_UTF16 */
98303 
98304 #ifndef SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS
98305   /*
98306   **   PRAGMA [database.]schema_version
98307   **   PRAGMA [database.]schema_version = <integer>
98308   **
98309   **   PRAGMA [database.]user_version
98310   **   PRAGMA [database.]user_version = <integer>
98311   **
98312   **   PRAGMA [database.]freelist_count = <integer>
98313   **
98314   **   PRAGMA [database.]application_id
98315   **   PRAGMA [database.]application_id = <integer>
98316   **
98317   ** The pragma's schema_version and user_version are used to set or get
98318   ** the value of the schema-version and user-version, respectively. Both
98319   ** the schema-version and the user-version are 32-bit signed integers
98320   ** stored in the database header.
98321   **
98322   ** The schema-cookie is usually only manipulated internally by SQLite. It
98323   ** is incremented by SQLite whenever the database schema is modified (by
98324   ** creating or dropping a table or index). The schema version is used by
98325   ** SQLite each time a query is executed to ensure that the internal cache
98326   ** of the schema used when compiling the SQL query matches the schema of
98327   ** the database against which the compiled query is actually executed.
98328   ** Subverting this mechanism by using "PRAGMA schema_version" to modify
98329   ** the schema-version is potentially dangerous and may lead to program
98330   ** crashes or database corruption. Use with caution!
98331   **
98332   ** The user-version is not used internally by SQLite. It may be used by
98333   ** applications for any purpose.
98334   */
98335   case PragTyp_HEADER_VALUE: {
98336     int iCookie;   /* Cookie index. 1 for schema-cookie, 6 for user-cookie. */
98337     sqlite3VdbeUsesBtree(v, iDb);
98338     switch( zLeft[0] ){
98339       case 'a': case 'A':
98340         iCookie = BTREE_APPLICATION_ID;
98341         break;
98342       case 'f': case 'F':
98343         iCookie = BTREE_FREE_PAGE_COUNT;
98344         break;
98345       case 's': case 'S':
98346         iCookie = BTREE_SCHEMA_VERSION;
98347         break;
98348       default:
98349         iCookie = BTREE_USER_VERSION;
98350         break;
98351     }
98352 
98353     if( zRight && iCookie!=BTREE_FREE_PAGE_COUNT ){
98354       /* Write the specified cookie value */
98355       static const VdbeOpList setCookie[] = {
98356         { OP_Transaction,    0,  1,  0},    /* 0 */
98357         { OP_Integer,        0,  1,  0},    /* 1 */
98358         { OP_SetCookie,      0,  0,  1},    /* 2 */
98359       };
98360       int addr = sqlite3VdbeAddOpList(v, ArraySize(setCookie), setCookie);
98361       sqlite3VdbeChangeP1(v, addr, iDb);
98362       sqlite3VdbeChangeP1(v, addr+1, sqlite3Atoi(zRight));
98363       sqlite3VdbeChangeP1(v, addr+2, iDb);
98364       sqlite3VdbeChangeP2(v, addr+2, iCookie);
98365     }else{
98366       /* Read the specified cookie value */
98367       static const VdbeOpList readCookie[] = {
98368         { OP_Transaction,     0,  0,  0},    /* 0 */
98369         { OP_ReadCookie,      0,  1,  0},    /* 1 */
98370         { OP_ResultRow,       1,  1,  0}
98371       };
98372       int addr = sqlite3VdbeAddOpList(v, ArraySize(readCookie), readCookie);
98373       sqlite3VdbeChangeP1(v, addr, iDb);
98374       sqlite3VdbeChangeP1(v, addr+1, iDb);
98375       sqlite3VdbeChangeP3(v, addr+1, iCookie);
98376       sqlite3VdbeSetNumCols(v, 1);
98377       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, zLeft, SQLITE_TRANSIENT);
98378     }
98379   }
98380   break;
98381 #endif /* SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS */
98382 
98383 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
98384   /*
98385   **   PRAGMA compile_options
98386   **
98387   ** Return the names of all compile-time options used in this build,
98388   ** one option per row.
98389   */
98390   case PragTyp_COMPILE_OPTIONS: {
98391     int i = 0;
98392     const char *zOpt;
98393     sqlite3VdbeSetNumCols(v, 1);
98394     pParse->nMem = 1;
98395     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "compile_option", SQLITE_STATIC);
98396     while( (zOpt = sqlite3_compileoption_get(i++))!=0 ){
98397       sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, zOpt, 0);
98398       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
98399     }
98400   }
98401   break;
98402 #endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
98403 
98404 #ifndef SQLITE_OMIT_WAL
98405   /*
98406   **   PRAGMA [database.]wal_checkpoint = passive|full|restart
98407   **
98408   ** Checkpoint the database.
98409   */
98410   case PragTyp_WAL_CHECKPOINT: {
98411     int iBt = (pId2->z?iDb:SQLITE_MAX_ATTACHED);
98412     int eMode = SQLITE_CHECKPOINT_PASSIVE;
98413     if( zRight ){
98414       if( sqlite3StrICmp(zRight, "full")==0 ){
98415         eMode = SQLITE_CHECKPOINT_FULL;
98416       }else if( sqlite3StrICmp(zRight, "restart")==0 ){
98417         eMode = SQLITE_CHECKPOINT_RESTART;
98418       }
98419     }
98420     sqlite3VdbeSetNumCols(v, 3);
98421     pParse->nMem = 3;
98422     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "busy", SQLITE_STATIC);
98423     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "log", SQLITE_STATIC);
98424     sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "checkpointed", SQLITE_STATIC);
98425 
98426     sqlite3VdbeAddOp3(v, OP_Checkpoint, iBt, eMode, 1);
98427     sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 3);
98428   }
98429   break;
98430 
98431   /*
98432   **   PRAGMA wal_autocheckpoint
98433   **   PRAGMA wal_autocheckpoint = N
98434   **
98435   ** Configure a database connection to automatically checkpoint a database
98436   ** after accumulating N frames in the log. Or query for the current value
98437   ** of N.
98438   */
98439   case PragTyp_WAL_AUTOCHECKPOINT: {
98440     if( zRight ){
98441       sqlite3_wal_autocheckpoint(db, sqlite3Atoi(zRight));
98442     }
98443     returnSingleInt(pParse, "wal_autocheckpoint", 
98444        db->xWalCallback==sqlite3WalDefaultHook ? 
98445            SQLITE_PTR_TO_INT(db->pWalArg) : 0);
98446   }
98447   break;
98448 #endif
98449 
98450   /*
98451   **  PRAGMA shrink_memory
98452   **
98453   ** This pragma attempts to free as much memory as possible from the
98454   ** current database connection.
98455   */
98456   case PragTyp_SHRINK_MEMORY: {
98457     sqlite3_db_release_memory(db);
98458     break;
98459   }
98460 
98461   /*
98462   **   PRAGMA busy_timeout
98463   **   PRAGMA busy_timeout = N
98464   **
98465   ** Call sqlite3_busy_timeout(db, N).  Return the current timeout value
98466   ** if one is set.  If no busy handler or a different busy handler is set
98467   ** then 0 is returned.  Setting the busy_timeout to 0 or negative
98468   ** disables the timeout.
98469   */
98470   /*case PragTyp_BUSY_TIMEOUT*/ default: {
98471     assert( aPragmaNames[mid].ePragTyp==PragTyp_BUSY_TIMEOUT );
98472     if( zRight ){
98473       sqlite3_busy_timeout(db, sqlite3Atoi(zRight));
98474     }
98475     returnSingleInt(pParse, "timeout",  db->busyTimeout);
98476     break;
98477   }
98478 
98479   /*
98480   **   PRAGMA soft_heap_limit
98481   **   PRAGMA soft_heap_limit = N
98482   **
98483   ** Call sqlite3_soft_heap_limit64(N).  Return the result.  If N is omitted,
98484   ** use -1.
98485   */
98486   case PragTyp_SOFT_HEAP_LIMIT: {
98487     sqlite3_int64 N;
98488     if( zRight && sqlite3Atoi64(zRight, &N, 1000000, SQLITE_UTF8)==SQLITE_OK ){
98489       sqlite3_soft_heap_limit64(N);
98490     }
98491     returnSingleInt(pParse, "soft_heap_limit",  sqlite3_soft_heap_limit64(-1));
98492     break;
98493   }
98494 
98495 #if defined(SQLITE_DEBUG) || defined(SQLITE_TEST)
98496   /*
98497   ** Report the current state of file logs for all databases
98498   */
98499   case PragTyp_LOCK_STATUS: {
98500     static const char *const azLockName[] = {
98501       "unlocked", "shared", "reserved", "pending", "exclusive"
98502     };
98503     int i;
98504     sqlite3VdbeSetNumCols(v, 2);
98505     pParse->nMem = 2;
98506     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "database", SQLITE_STATIC);
98507     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "status", SQLITE_STATIC);
98508     for(i=0; i<db->nDb; i++){
98509       Btree *pBt;
98510       const char *zState = "unknown";
98511       int j;
98512       if( db->aDb[i].zName==0 ) continue;
98513       sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, db->aDb[i].zName, P4_STATIC);
98514       pBt = db->aDb[i].pBt;
98515       if( pBt==0 || sqlite3BtreePager(pBt)==0 ){
98516         zState = "closed";
98517       }else if( sqlite3_file_control(db, i ? db->aDb[i].zName : 0, 
98518                                      SQLITE_FCNTL_LOCKSTATE, &j)==SQLITE_OK ){
98519          zState = azLockName[j];
98520       }
98521       sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, zState, P4_STATIC);
98522       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 2);
98523     }
98524     break;
98525   }
98526 #endif
98527 
98528 #ifdef SQLITE_HAS_CODEC
98529   case PragTyp_KEY: {
98530     if( zRight ) sqlite3_key_v2(db, zDb, zRight, sqlite3Strlen30(zRight));
98531     break;
98532   }
98533   case PragTyp_REKEY: {
98534     if( zRight ) sqlite3_rekey_v2(db, zDb, zRight, sqlite3Strlen30(zRight));
98535     break;
98536   }
98537   case PragTyp_HEXKEY: {
98538     if( zRight ){
98539       u8 iByte;
98540       int i;
98541       char zKey[40];
98542       for(i=0, iByte=0; i<sizeof(zKey)*2 && sqlite3Isxdigit(zRight[i]); i++){
98543         iByte = (iByte<<4) + sqlite3HexToInt(zRight[i]);
98544         if( (i&1)!=0 ) zKey[i/2] = iByte;
98545       }
98546       if( (zLeft[3] & 0xf)==0xb ){
98547         sqlite3_key_v2(db, zDb, zKey, i/2);
98548       }else{
98549         sqlite3_rekey_v2(db, zDb, zKey, i/2);
98550       }
98551     }
98552     break;
98553   }
98554 #endif
98555 #if defined(SQLITE_HAS_CODEC) || defined(SQLITE_ENABLE_CEROD)
98556   case PragTyp_ACTIVATE_EXTENSIONS: if( zRight ){
98557 #ifdef SQLITE_HAS_CODEC
98558     if( sqlite3StrNICmp(zRight, "see-", 4)==0 ){
98559       sqlite3_activate_see(&zRight[4]);
98560     }
98561 #endif
98562 #ifdef SQLITE_ENABLE_CEROD
98563     if( sqlite3StrNICmp(zRight, "cerod-", 6)==0 ){
98564       sqlite3_activate_cerod(&zRight[6]);
98565     }
98566 #endif
98567   }
98568   break;
98569 #endif
98570 
98571   } /* End of the PRAGMA switch */
98572 
98573 pragma_out:
98574   sqlite3DbFree(db, zLeft);
98575   sqlite3DbFree(db, zRight);
98576 }
98577 
98578 #endif /* SQLITE_OMIT_PRAGMA */
98579 
98580 /************** End of pragma.c **********************************************/
98581 /************** Begin file prepare.c *****************************************/
98582 /*
98583 ** 2005 May 25
98584 **
98585 ** The author disclaims copyright to this source code.  In place of
98586 ** a legal notice, here is a blessing:
98587 **
98588 **    May you do good and not evil.
98589 **    May you find forgiveness for yourself and forgive others.
98590 **    May you share freely, never taking more than you give.
98591 **
98592 *************************************************************************
98593 ** This file contains the implementation of the sqlite3_prepare()
98594 ** interface, and routines that contribute to loading the database schema
98595 ** from disk.
98596 */
98597 
98598 /*
98599 ** Fill the InitData structure with an error message that indicates
98600 ** that the database is corrupt.
98601 */
98602 static void corruptSchema(
98603   InitData *pData,     /* Initialization context */
98604   const char *zObj,    /* Object being parsed at the point of error */
98605   const char *zExtra   /* Error information */
98606 ){
98607   sqlite3 *db = pData->db;
98608   if( !db->mallocFailed && (db->flags & SQLITE_RecoveryMode)==0 ){
98609     if( zObj==0 ) zObj = "?";
98610     sqlite3SetString(pData->pzErrMsg, db,
98611       "malformed database schema (%s)", zObj);
98612     if( zExtra ){
98613       *pData->pzErrMsg = sqlite3MAppendf(db, *pData->pzErrMsg, 
98614                                  "%s - %s", *pData->pzErrMsg, zExtra);
98615     }
98616   }
98617   pData->rc = db->mallocFailed ? SQLITE_NOMEM : SQLITE_CORRUPT_BKPT;
98618 }
98619 
98620 /*
98621 ** This is the callback routine for the code that initializes the
98622 ** database.  See sqlite3Init() below for additional information.
98623 ** This routine is also called from the OP_ParseSchema opcode of the VDBE.
98624 **
98625 ** Each callback contains the following information:
98626 **
98627 **     argv[0] = name of thing being created
98628 **     argv[1] = root page number for table or index. 0 for trigger or view.
98629 **     argv[2] = SQL text for the CREATE statement.
98630 **
98631 */
98632 SQLITE_PRIVATE int sqlite3InitCallback(void *pInit, int argc, char **argv, char **NotUsed){
98633   InitData *pData = (InitData*)pInit;
98634   sqlite3 *db = pData->db;
98635   int iDb = pData->iDb;
98636 
98637   assert( argc==3 );
98638   UNUSED_PARAMETER2(NotUsed, argc);
98639   assert( sqlite3_mutex_held(db->mutex) );
98640   DbClearProperty(db, iDb, DB_Empty);
98641   if( db->mallocFailed ){
98642     corruptSchema(pData, argv[0], 0);
98643     return 1;
98644   }
98645 
98646   assert( iDb>=0 && iDb<db->nDb );
98647   if( argv==0 ) return 0;   /* Might happen if EMPTY_RESULT_CALLBACKS are on */
98648   if( argv[1]==0 ){
98649     corruptSchema(pData, argv[0], 0);
98650   }else if( argv[2] && argv[2][0] ){
98651     /* Call the parser to process a CREATE TABLE, INDEX or VIEW.
98652     ** But because db->init.busy is set to 1, no VDBE code is generated
98653     ** or executed.  All the parser does is build the internal data
98654     ** structures that describe the table, index, or view.
98655     */
98656     int rc;
98657     sqlite3_stmt *pStmt;
98658     TESTONLY(int rcp);            /* Return code from sqlite3_prepare() */
98659 
98660     assert( db->init.busy );
98661     db->init.iDb = iDb;
98662     db->init.newTnum = sqlite3Atoi(argv[1]);
98663     db->init.orphanTrigger = 0;
98664     TESTONLY(rcp = ) sqlite3_prepare(db, argv[2], -1, &pStmt, 0);
98665     rc = db->errCode;
98666     assert( (rc&0xFF)==(rcp&0xFF) );
98667     db->init.iDb = 0;
98668     if( SQLITE_OK!=rc ){
98669       if( db->init.orphanTrigger ){
98670         assert( iDb==1 );
98671       }else{
98672         pData->rc = rc;
98673         if( rc==SQLITE_NOMEM ){
98674           db->mallocFailed = 1;
98675         }else if( rc!=SQLITE_INTERRUPT && (rc&0xFF)!=SQLITE_LOCKED ){
98676           corruptSchema(pData, argv[0], sqlite3_errmsg(db));
98677         }
98678       }
98679     }
98680     sqlite3_finalize(pStmt);
98681   }else if( argv[0]==0 ){
98682     corruptSchema(pData, 0, 0);
98683   }else{
98684     /* If the SQL column is blank it means this is an index that
98685     ** was created to be the PRIMARY KEY or to fulfill a UNIQUE
98686     ** constraint for a CREATE TABLE.  The index should have already
98687     ** been created when we processed the CREATE TABLE.  All we have
98688     ** to do here is record the root page number for that index.
98689     */
98690     Index *pIndex;
98691     pIndex = sqlite3FindIndex(db, argv[0], db->aDb[iDb].zName);
98692     if( pIndex==0 ){
98693       /* This can occur if there exists an index on a TEMP table which
98694       ** has the same name as another index on a permanent index.  Since
98695       ** the permanent table is hidden by the TEMP table, we can also
98696       ** safely ignore the index on the permanent table.
98697       */
98698       /* Do Nothing */;
98699     }else if( sqlite3GetInt32(argv[1], &pIndex->tnum)==0 ){
98700       corruptSchema(pData, argv[0], "invalid rootpage");
98701     }
98702   }
98703   return 0;
98704 }
98705 
98706 /*
98707 ** Attempt to read the database schema and initialize internal
98708 ** data structures for a single database file.  The index of the
98709 ** database file is given by iDb.  iDb==0 is used for the main
98710 ** database.  iDb==1 should never be used.  iDb>=2 is used for
98711 ** auxiliary databases.  Return one of the SQLITE_ error codes to
98712 ** indicate success or failure.
98713 */
98714 static int sqlite3InitOne(sqlite3 *db, int iDb, char **pzErrMsg){
98715   int rc;
98716   int i;
98717 #ifndef SQLITE_OMIT_DEPRECATED
98718   int size;
98719 #endif
98720   Table *pTab;
98721   Db *pDb;
98722   char const *azArg[4];
98723   int meta[5];
98724   InitData initData;
98725   char const *zMasterSchema;
98726   char const *zMasterName;
98727   int openedTransaction = 0;
98728 
98729   /*
98730   ** The master database table has a structure like this
98731   */
98732   static const char master_schema[] = 
98733      "CREATE TABLE sqlite_master(\n"
98734      "  type text,\n"
98735      "  name text,\n"
98736      "  tbl_name text,\n"
98737      "  rootpage integer,\n"
98738      "  sql text\n"
98739      ")"
98740   ;
98741 #ifndef SQLITE_OMIT_TEMPDB
98742   static const char temp_master_schema[] = 
98743      "CREATE TEMP TABLE sqlite_temp_master(\n"
98744      "  type text,\n"
98745      "  name text,\n"
98746      "  tbl_name text,\n"
98747      "  rootpage integer,\n"
98748      "  sql text\n"
98749      ")"
98750   ;
98751 #else
98752   #define temp_master_schema 0
98753 #endif
98754 
98755   assert( iDb>=0 && iDb<db->nDb );
98756   assert( db->aDb[iDb].pSchema );
98757   assert( sqlite3_mutex_held(db->mutex) );
98758   assert( iDb==1 || sqlite3BtreeHoldsMutex(db->aDb[iDb].pBt) );
98759 
98760   /* zMasterSchema and zInitScript are set to point at the master schema
98761   ** and initialisation script appropriate for the database being
98762   ** initialized. zMasterName is the name of the master table.
98763   */
98764   if( !OMIT_TEMPDB && iDb==1 ){
98765     zMasterSchema = temp_master_schema;
98766   }else{
98767     zMasterSchema = master_schema;
98768   }
98769   zMasterName = SCHEMA_TABLE(iDb);
98770 
98771   /* Construct the schema tables.  */
98772   azArg[0] = zMasterName;
98773   azArg[1] = "1";
98774   azArg[2] = zMasterSchema;
98775   azArg[3] = 0;
98776   initData.db = db;
98777   initData.iDb = iDb;
98778   initData.rc = SQLITE_OK;
98779   initData.pzErrMsg = pzErrMsg;
98780   sqlite3InitCallback(&initData, 3, (char **)azArg, 0);
98781   if( initData.rc ){
98782     rc = initData.rc;
98783     goto error_out;
98784   }
98785   pTab = sqlite3FindTable(db, zMasterName, db->aDb[iDb].zName);
98786   if( ALWAYS(pTab) ){
98787     pTab->tabFlags |= TF_Readonly;
98788   }
98789 
98790   /* Create a cursor to hold the database open
98791   */
98792   pDb = &db->aDb[iDb];
98793   if( pDb->pBt==0 ){
98794     if( !OMIT_TEMPDB && ALWAYS(iDb==1) ){
98795       DbSetProperty(db, 1, DB_SchemaLoaded);
98796     }
98797     return SQLITE_OK;
98798   }
98799 
98800   /* If there is not already a read-only (or read-write) transaction opened
98801   ** on the b-tree database, open one now. If a transaction is opened, it 
98802   ** will be closed before this function returns.  */
98803   sqlite3BtreeEnter(pDb->pBt);
98804   if( !sqlite3BtreeIsInReadTrans(pDb->pBt) ){
98805     rc = sqlite3BtreeBeginTrans(pDb->pBt, 0);
98806     if( rc!=SQLITE_OK ){
98807       sqlite3SetString(pzErrMsg, db, "%s", sqlite3ErrStr(rc));
98808       goto initone_error_out;
98809     }
98810     openedTransaction = 1;
98811   }
98812 
98813   /* Get the database meta information.
98814   **
98815   ** Meta values are as follows:
98816   **    meta[0]   Schema cookie.  Changes with each schema change.
98817   **    meta[1]   File format of schema layer.
98818   **    meta[2]   Size of the page cache.
98819   **    meta[3]   Largest rootpage (auto/incr_vacuum mode)
98820   **    meta[4]   Db text encoding. 1:UTF-8 2:UTF-16LE 3:UTF-16BE
98821   **    meta[5]   User version
98822   **    meta[6]   Incremental vacuum mode
98823   **    meta[7]   unused
98824   **    meta[8]   unused
98825   **    meta[9]   unused
98826   **
98827   ** Note: The #defined SQLITE_UTF* symbols in sqliteInt.h correspond to
98828   ** the possible values of meta[4].
98829   */
98830   for(i=0; i<ArraySize(meta); i++){
98831     sqlite3BtreeGetMeta(pDb->pBt, i+1, (u32 *)&meta[i]);
98832   }
98833   pDb->pSchema->schema_cookie = meta[BTREE_SCHEMA_VERSION-1];
98834 
98835   /* If opening a non-empty database, check the text encoding. For the
98836   ** main database, set sqlite3.enc to the encoding of the main database.
98837   ** For an attached db, it is an error if the encoding is not the same
98838   ** as sqlite3.enc.
98839   */
98840   if( meta[BTREE_TEXT_ENCODING-1] ){  /* text encoding */
98841     if( iDb==0 ){
98842 #ifndef SQLITE_OMIT_UTF16
98843       u8 encoding;
98844       /* If opening the main database, set ENC(db). */
98845       encoding = (u8)meta[BTREE_TEXT_ENCODING-1] & 3;
98846       if( encoding==0 ) encoding = SQLITE_UTF8;
98847       ENC(db) = encoding;
98848 #else
98849       ENC(db) = SQLITE_UTF8;
98850 #endif
98851     }else{
98852       /* If opening an attached database, the encoding much match ENC(db) */
98853       if( meta[BTREE_TEXT_ENCODING-1]!=ENC(db) ){
98854         sqlite3SetString(pzErrMsg, db, "attached databases must use the same"
98855             " text encoding as main database");
98856         rc = SQLITE_ERROR;
98857         goto initone_error_out;
98858       }
98859     }
98860   }else{
98861     DbSetProperty(db, iDb, DB_Empty);
98862   }
98863   pDb->pSchema->enc = ENC(db);
98864 
98865   if( pDb->pSchema->cache_size==0 ){
98866 #ifndef SQLITE_OMIT_DEPRECATED
98867     size = sqlite3AbsInt32(meta[BTREE_DEFAULT_CACHE_SIZE-1]);
98868     if( size==0 ){ size = SQLITE_DEFAULT_CACHE_SIZE; }
98869     pDb->pSchema->cache_size = size;
98870 #else
98871     pDb->pSchema->cache_size = SQLITE_DEFAULT_CACHE_SIZE;
98872 #endif
98873     sqlite3BtreeSetCacheSize(pDb->pBt, pDb->pSchema->cache_size);
98874   }
98875 
98876   /*
98877   ** file_format==1    Version 3.0.0.
98878   ** file_format==2    Version 3.1.3.  // ALTER TABLE ADD COLUMN
98879   ** file_format==3    Version 3.1.4.  // ditto but with non-NULL defaults
98880   ** file_format==4    Version 3.3.0.  // DESC indices.  Boolean constants
98881   */
98882   pDb->pSchema->file_format = (u8)meta[BTREE_FILE_FORMAT-1];
98883   if( pDb->pSchema->file_format==0 ){
98884     pDb->pSchema->file_format = 1;
98885   }
98886   if( pDb->pSchema->file_format>SQLITE_MAX_FILE_FORMAT ){
98887     sqlite3SetString(pzErrMsg, db, "unsupported file format");
98888     rc = SQLITE_ERROR;
98889     goto initone_error_out;
98890   }
98891 
98892   /* Ticket #2804:  When we open a database in the newer file format,
98893   ** clear the legacy_file_format pragma flag so that a VACUUM will
98894   ** not downgrade the database and thus invalidate any descending
98895   ** indices that the user might have created.
98896   */
98897   if( iDb==0 && meta[BTREE_FILE_FORMAT-1]>=4 ){
98898     db->flags &= ~SQLITE_LegacyFileFmt;
98899   }
98900 
98901   /* Read the schema information out of the schema tables
98902   */
98903   assert( db->init.busy );
98904   {
98905     char *zSql;
98906     zSql = sqlite3MPrintf(db, 
98907         "SELECT name, rootpage, sql FROM '%q'.%s ORDER BY rowid",
98908         db->aDb[iDb].zName, zMasterName);
98909 #ifndef SQLITE_OMIT_AUTHORIZATION
98910     {
98911       int (*xAuth)(void*,int,const char*,const char*,const char*,const char*);
98912       xAuth = db->xAuth;
98913       db->xAuth = 0;
98914 #endif
98915       rc = sqlite3_exec(db, zSql, sqlite3InitCallback, &initData, 0);
98916 #ifndef SQLITE_OMIT_AUTHORIZATION
98917       db->xAuth = xAuth;
98918     }
98919 #endif
98920     if( rc==SQLITE_OK ) rc = initData.rc;
98921     sqlite3DbFree(db, zSql);
98922 #ifndef SQLITE_OMIT_ANALYZE
98923     if( rc==SQLITE_OK ){
98924       sqlite3AnalysisLoad(db, iDb);
98925     }
98926 #endif
98927   }
98928   if( db->mallocFailed ){
98929     rc = SQLITE_NOMEM;
98930     sqlite3ResetAllSchemasOfConnection(db);
98931   }
98932   if( rc==SQLITE_OK || (db->flags&SQLITE_RecoveryMode)){
98933     /* Black magic: If the SQLITE_RecoveryMode flag is set, then consider
98934     ** the schema loaded, even if errors occurred. In this situation the 
98935     ** current sqlite3_prepare() operation will fail, but the following one
98936     ** will attempt to compile the supplied statement against whatever subset
98937     ** of the schema was loaded before the error occurred. The primary
98938     ** purpose of this is to allow access to the sqlite_master table
98939     ** even when its contents have been corrupted.
98940     */
98941     DbSetProperty(db, iDb, DB_SchemaLoaded);
98942     rc = SQLITE_OK;
98943   }
98944 
98945   /* Jump here for an error that occurs after successfully allocating
98946   ** curMain and calling sqlite3BtreeEnter(). For an error that occurs
98947   ** before that point, jump to error_out.
98948   */
98949 initone_error_out:
98950   if( openedTransaction ){
98951     sqlite3BtreeCommit(pDb->pBt);
98952   }
98953   sqlite3BtreeLeave(pDb->pBt);
98954 
98955 error_out:
98956   if( rc==SQLITE_NOMEM || rc==SQLITE_IOERR_NOMEM ){
98957     db->mallocFailed = 1;
98958   }
98959   return rc;
98960 }
98961 
98962 /*
98963 ** Initialize all database files - the main database file, the file
98964 ** used to store temporary tables, and any additional database files
98965 ** created using ATTACH statements.  Return a success code.  If an
98966 ** error occurs, write an error message into *pzErrMsg.
98967 **
98968 ** After a database is initialized, the DB_SchemaLoaded bit is set
98969 ** bit is set in the flags field of the Db structure. If the database
98970 ** file was of zero-length, then the DB_Empty flag is also set.
98971 */
98972 SQLITE_PRIVATE int sqlite3Init(sqlite3 *db, char **pzErrMsg){
98973   int i, rc;
98974   int commit_internal = !(db->flags&SQLITE_InternChanges);
98975   
98976   assert( sqlite3_mutex_held(db->mutex) );
98977   rc = SQLITE_OK;
98978   db->init.busy = 1;
98979   for(i=0; rc==SQLITE_OK && i<db->nDb; i++){
98980     if( DbHasProperty(db, i, DB_SchemaLoaded) || i==1 ) continue;
98981     rc = sqlite3InitOne(db, i, pzErrMsg);
98982     if( rc ){
98983       sqlite3ResetOneSchema(db, i);
98984     }
98985   }
98986 
98987   /* Once all the other databases have been initialized, load the schema
98988   ** for the TEMP database. This is loaded last, as the TEMP database
98989   ** schema may contain references to objects in other databases.
98990   */
98991 #ifndef SQLITE_OMIT_TEMPDB
98992   if( rc==SQLITE_OK && ALWAYS(db->nDb>1)
98993                     && !DbHasProperty(db, 1, DB_SchemaLoaded) ){
98994     rc = sqlite3InitOne(db, 1, pzErrMsg);
98995     if( rc ){
98996       sqlite3ResetOneSchema(db, 1);
98997     }
98998   }
98999 #endif
99000 
99001   db->init.busy = 0;
99002   if( rc==SQLITE_OK && commit_internal ){
99003     sqlite3CommitInternalChanges(db);
99004   }
99005 
99006   return rc; 
99007 }
99008 
99009 /*
99010 ** This routine is a no-op if the database schema is already initialized.
99011 ** Otherwise, the schema is loaded. An error code is returned.
99012 */
99013 SQLITE_PRIVATE int sqlite3ReadSchema(Parse *pParse){
99014   int rc = SQLITE_OK;
99015   sqlite3 *db = pParse->db;
99016   assert( sqlite3_mutex_held(db->mutex) );
99017   if( !db->init.busy ){
99018     rc = sqlite3Init(db, &pParse->zErrMsg);
99019   }
99020   if( rc!=SQLITE_OK ){
99021     pParse->rc = rc;
99022     pParse->nErr++;
99023   }
99024   return rc;
99025 }
99026 
99027 
99028 /*
99029 ** Check schema cookies in all databases.  If any cookie is out
99030 ** of date set pParse->rc to SQLITE_SCHEMA.  If all schema cookies
99031 ** make no changes to pParse->rc.
99032 */
99033 static void schemaIsValid(Parse *pParse){
99034   sqlite3 *db = pParse->db;
99035   int iDb;
99036   int rc;
99037   int cookie;
99038 
99039   assert( pParse->checkSchema );
99040   assert( sqlite3_mutex_held(db->mutex) );
99041   for(iDb=0; iDb<db->nDb; iDb++){
99042     int openedTransaction = 0;         /* True if a transaction is opened */
99043     Btree *pBt = db->aDb[iDb].pBt;     /* Btree database to read cookie from */
99044     if( pBt==0 ) continue;
99045 
99046     /* If there is not already a read-only (or read-write) transaction opened
99047     ** on the b-tree database, open one now. If a transaction is opened, it 
99048     ** will be closed immediately after reading the meta-value. */
99049     if( !sqlite3BtreeIsInReadTrans(pBt) ){
99050       rc = sqlite3BtreeBeginTrans(pBt, 0);
99051       if( rc==SQLITE_NOMEM || rc==SQLITE_IOERR_NOMEM ){
99052         db->mallocFailed = 1;
99053       }
99054       if( rc!=SQLITE_OK ) return;
99055       openedTransaction = 1;
99056     }
99057 
99058     /* Read the schema cookie from the database. If it does not match the 
99059     ** value stored as part of the in-memory schema representation,
99060     ** set Parse.rc to SQLITE_SCHEMA. */
99061     sqlite3BtreeGetMeta(pBt, BTREE_SCHEMA_VERSION, (u32 *)&cookie);
99062     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
99063     if( cookie!=db->aDb[iDb].pSchema->schema_cookie ){
99064       sqlite3ResetOneSchema(db, iDb);
99065       pParse->rc = SQLITE_SCHEMA;
99066     }
99067 
99068     /* Close the transaction, if one was opened. */
99069     if( openedTransaction ){
99070       sqlite3BtreeCommit(pBt);
99071     }
99072   }
99073 }
99074 
99075 /*
99076 ** Convert a schema pointer into the iDb index that indicates
99077 ** which database file in db->aDb[] the schema refers to.
99078 **
99079 ** If the same database is attached more than once, the first
99080 ** attached database is returned.
99081 */
99082 SQLITE_PRIVATE int sqlite3SchemaToIndex(sqlite3 *db, Schema *pSchema){
99083   int i = -1000000;
99084 
99085   /* If pSchema is NULL, then return -1000000. This happens when code in 
99086   ** expr.c is trying to resolve a reference to a transient table (i.e. one
99087   ** created by a sub-select). In this case the return value of this 
99088   ** function should never be used.
99089   **
99090   ** We return -1000000 instead of the more usual -1 simply because using
99091   ** -1000000 as the incorrect index into db->aDb[] is much 
99092   ** more likely to cause a segfault than -1 (of course there are assert()
99093   ** statements too, but it never hurts to play the odds).
99094   */
99095   assert( sqlite3_mutex_held(db->mutex) );
99096   if( pSchema ){
99097     for(i=0; ALWAYS(i<db->nDb); i++){
99098       if( db->aDb[i].pSchema==pSchema ){
99099         break;
99100       }
99101     }
99102     assert( i>=0 && i<db->nDb );
99103   }
99104   return i;
99105 }
99106 
99107 /*
99108 ** Free all memory allocations in the pParse object
99109 */
99110 SQLITE_PRIVATE void sqlite3ParserReset(Parse *pParse){
99111   if( pParse ) sqlite3ExprListDelete(pParse->db, pParse->pConstExpr);
99112 }
99113 
99114 /*
99115 ** Compile the UTF-8 encoded SQL statement zSql into a statement handle.
99116 */
99117 static int sqlite3Prepare(
99118   sqlite3 *db,              /* Database handle. */
99119   const char *zSql,         /* UTF-8 encoded SQL statement. */
99120   int nBytes,               /* Length of zSql in bytes. */
99121   int saveSqlFlag,          /* True to copy SQL text into the sqlite3_stmt */
99122   Vdbe *pReprepare,         /* VM being reprepared */
99123   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99124   const char **pzTail       /* OUT: End of parsed string */
99125 ){
99126   Parse *pParse;            /* Parsing context */
99127   char *zErrMsg = 0;        /* Error message */
99128   int rc = SQLITE_OK;       /* Result code */
99129   int i;                    /* Loop counter */
99130 
99131   /* Allocate the parsing context */
99132   pParse = sqlite3StackAllocZero(db, sizeof(*pParse));
99133   if( pParse==0 ){
99134     rc = SQLITE_NOMEM;
99135     goto end_prepare;
99136   }
99137   pParse->pReprepare = pReprepare;
99138   assert( ppStmt && *ppStmt==0 );
99139   assert( !db->mallocFailed );
99140   assert( sqlite3_mutex_held(db->mutex) );
99141 
99142   /* Check to verify that it is possible to get a read lock on all
99143   ** database schemas.  The inability to get a read lock indicates that
99144   ** some other database connection is holding a write-lock, which in
99145   ** turn means that the other connection has made uncommitted changes
99146   ** to the schema.
99147   **
99148   ** Were we to proceed and prepare the statement against the uncommitted
99149   ** schema changes and if those schema changes are subsequently rolled
99150   ** back and different changes are made in their place, then when this
99151   ** prepared statement goes to run the schema cookie would fail to detect
99152   ** the schema change.  Disaster would follow.
99153   **
99154   ** This thread is currently holding mutexes on all Btrees (because
99155   ** of the sqlite3BtreeEnterAll() in sqlite3LockAndPrepare()) so it
99156   ** is not possible for another thread to start a new schema change
99157   ** while this routine is running.  Hence, we do not need to hold 
99158   ** locks on the schema, we just need to make sure nobody else is 
99159   ** holding them.
99160   **
99161   ** Note that setting READ_UNCOMMITTED overrides most lock detection,
99162   ** but it does *not* override schema lock detection, so this all still
99163   ** works even if READ_UNCOMMITTED is set.
99164   */
99165   for(i=0; i<db->nDb; i++) {
99166     Btree *pBt = db->aDb[i].pBt;
99167     if( pBt ){
99168       assert( sqlite3BtreeHoldsMutex(pBt) );
99169       rc = sqlite3BtreeSchemaLocked(pBt);
99170       if( rc ){
99171         const char *zDb = db->aDb[i].zName;
99172         sqlite3Error(db, rc, "database schema is locked: %s", zDb);
99173         testcase( db->flags & SQLITE_ReadUncommitted );
99174         goto end_prepare;
99175       }
99176     }
99177   }
99178 
99179   sqlite3VtabUnlockList(db);
99180 
99181   pParse->db = db;
99182   pParse->nQueryLoop = 0;  /* Logarithmic, so 0 really means 1 */
99183   if( nBytes>=0 && (nBytes==0 || zSql[nBytes-1]!=0) ){
99184     char *zSqlCopy;
99185     int mxLen = db->aLimit[SQLITE_LIMIT_SQL_LENGTH];
99186     testcase( nBytes==mxLen );
99187     testcase( nBytes==mxLen+1 );
99188     if( nBytes>mxLen ){
99189       sqlite3Error(db, SQLITE_TOOBIG, "statement too long");
99190       rc = sqlite3ApiExit(db, SQLITE_TOOBIG);
99191       goto end_prepare;
99192     }
99193     zSqlCopy = sqlite3DbStrNDup(db, zSql, nBytes);
99194     if( zSqlCopy ){
99195       sqlite3RunParser(pParse, zSqlCopy, &zErrMsg);
99196       sqlite3DbFree(db, zSqlCopy);
99197       pParse->zTail = &zSql[pParse->zTail-zSqlCopy];
99198     }else{
99199       pParse->zTail = &zSql[nBytes];
99200     }
99201   }else{
99202     sqlite3RunParser(pParse, zSql, &zErrMsg);
99203   }
99204   assert( 0==pParse->nQueryLoop );
99205 
99206   if( db->mallocFailed ){
99207     pParse->rc = SQLITE_NOMEM;
99208   }
99209   if( pParse->rc==SQLITE_DONE ) pParse->rc = SQLITE_OK;
99210   if( pParse->checkSchema ){
99211     schemaIsValid(pParse);
99212   }
99213   if( db->mallocFailed ){
99214     pParse->rc = SQLITE_NOMEM;
99215   }
99216   if( pzTail ){
99217     *pzTail = pParse->zTail;
99218   }
99219   rc = pParse->rc;
99220 
99221 #ifndef SQLITE_OMIT_EXPLAIN
99222   if( rc==SQLITE_OK && pParse->pVdbe && pParse->explain ){
99223     static const char * const azColName[] = {
99224        "addr", "opcode", "p1", "p2", "p3", "p4", "p5", "comment",
99225        "selectid", "order", "from", "detail"
99226     };
99227     int iFirst, mx;
99228     if( pParse->explain==2 ){
99229       sqlite3VdbeSetNumCols(pParse->pVdbe, 4);
99230       iFirst = 8;
99231       mx = 12;
99232     }else{
99233       sqlite3VdbeSetNumCols(pParse->pVdbe, 8);
99234       iFirst = 0;
99235       mx = 8;
99236     }
99237     for(i=iFirst; i<mx; i++){
99238       sqlite3VdbeSetColName(pParse->pVdbe, i-iFirst, COLNAME_NAME,
99239                             azColName[i], SQLITE_STATIC);
99240     }
99241   }
99242 #endif
99243 
99244   if( db->init.busy==0 ){
99245     Vdbe *pVdbe = pParse->pVdbe;
99246     sqlite3VdbeSetSql(pVdbe, zSql, (int)(pParse->zTail-zSql), saveSqlFlag);
99247   }
99248   if( pParse->pVdbe && (rc!=SQLITE_OK || db->mallocFailed) ){
99249     sqlite3VdbeFinalize(pParse->pVdbe);
99250     assert(!(*ppStmt));
99251   }else{
99252     *ppStmt = (sqlite3_stmt*)pParse->pVdbe;
99253   }
99254 
99255   if( zErrMsg ){
99256     sqlite3Error(db, rc, "%s", zErrMsg);
99257     sqlite3DbFree(db, zErrMsg);
99258   }else{
99259     sqlite3Error(db, rc, 0);
99260   }
99261 
99262   /* Delete any TriggerPrg structures allocated while parsing this statement. */
99263   while( pParse->pTriggerPrg ){
99264     TriggerPrg *pT = pParse->pTriggerPrg;
99265     pParse->pTriggerPrg = pT->pNext;
99266     sqlite3DbFree(db, pT);
99267   }
99268 
99269 end_prepare:
99270 
99271   sqlite3ParserReset(pParse);
99272   sqlite3StackFree(db, pParse);
99273   rc = sqlite3ApiExit(db, rc);
99274   assert( (rc&db->errMask)==rc );
99275   return rc;
99276 }
99277 static int sqlite3LockAndPrepare(
99278   sqlite3 *db,              /* Database handle. */
99279   const char *zSql,         /* UTF-8 encoded SQL statement. */
99280   int nBytes,               /* Length of zSql in bytes. */
99281   int saveSqlFlag,          /* True to copy SQL text into the sqlite3_stmt */
99282   Vdbe *pOld,               /* VM being reprepared */
99283   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99284   const char **pzTail       /* OUT: End of parsed string */
99285 ){
99286   int rc;
99287   assert( ppStmt!=0 );
99288   *ppStmt = 0;
99289   if( !sqlite3SafetyCheckOk(db) ){
99290     return SQLITE_MISUSE_BKPT;
99291   }
99292   sqlite3_mutex_enter(db->mutex);
99293   sqlite3BtreeEnterAll(db);
99294   rc = sqlite3Prepare(db, zSql, nBytes, saveSqlFlag, pOld, ppStmt, pzTail);
99295   if( rc==SQLITE_SCHEMA ){
99296     sqlite3_finalize(*ppStmt);
99297     rc = sqlite3Prepare(db, zSql, nBytes, saveSqlFlag, pOld, ppStmt, pzTail);
99298   }
99299   sqlite3BtreeLeaveAll(db);
99300   sqlite3_mutex_leave(db->mutex);
99301   assert( rc==SQLITE_OK || *ppStmt==0 );
99302   return rc;
99303 }
99304 
99305 /*
99306 ** Rerun the compilation of a statement after a schema change.
99307 **
99308 ** If the statement is successfully recompiled, return SQLITE_OK. Otherwise,
99309 ** if the statement cannot be recompiled because another connection has
99310 ** locked the sqlite3_master table, return SQLITE_LOCKED. If any other error
99311 ** occurs, return SQLITE_SCHEMA.
99312 */
99313 SQLITE_PRIVATE int sqlite3Reprepare(Vdbe *p){
99314   int rc;
99315   sqlite3_stmt *pNew;
99316   const char *zSql;
99317   sqlite3 *db;
99318 
99319   assert( sqlite3_mutex_held(sqlite3VdbeDb(p)->mutex) );
99320   zSql = sqlite3_sql((sqlite3_stmt *)p);
99321   assert( zSql!=0 );  /* Reprepare only called for prepare_v2() statements */
99322   db = sqlite3VdbeDb(p);
99323   assert( sqlite3_mutex_held(db->mutex) );
99324   rc = sqlite3LockAndPrepare(db, zSql, -1, 0, p, &pNew, 0);
99325   if( rc ){
99326     if( rc==SQLITE_NOMEM ){
99327       db->mallocFailed = 1;
99328     }
99329     assert( pNew==0 );
99330     return rc;
99331   }else{
99332     assert( pNew!=0 );
99333   }
99334   sqlite3VdbeSwap((Vdbe*)pNew, p);
99335   sqlite3TransferBindings(pNew, (sqlite3_stmt*)p);
99336   sqlite3VdbeResetStepResult((Vdbe*)pNew);
99337   sqlite3VdbeFinalize((Vdbe*)pNew);
99338   return SQLITE_OK;
99339 }
99340 
99341 
99342 /*
99343 ** Two versions of the official API.  Legacy and new use.  In the legacy
99344 ** version, the original SQL text is not saved in the prepared statement
99345 ** and so if a schema change occurs, SQLITE_SCHEMA is returned by
99346 ** sqlite3_step().  In the new version, the original SQL text is retained
99347 ** and the statement is automatically recompiled if an schema change
99348 ** occurs.
99349 */
99350 SQLITE_API int sqlite3_prepare(
99351   sqlite3 *db,              /* Database handle. */
99352   const char *zSql,         /* UTF-8 encoded SQL statement. */
99353   int nBytes,               /* Length of zSql in bytes. */
99354   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99355   const char **pzTail       /* OUT: End of parsed string */
99356 ){
99357   int rc;
99358   rc = sqlite3LockAndPrepare(db,zSql,nBytes,0,0,ppStmt,pzTail);
99359   assert( rc==SQLITE_OK || ppStmt==0 || *ppStmt==0 );  /* VERIFY: F13021 */
99360   return rc;
99361 }
99362 SQLITE_API int sqlite3_prepare_v2(
99363   sqlite3 *db,              /* Database handle. */
99364   const char *zSql,         /* UTF-8 encoded SQL statement. */
99365   int nBytes,               /* Length of zSql in bytes. */
99366   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99367   const char **pzTail       /* OUT: End of parsed string */
99368 ){
99369   int rc;
99370   rc = sqlite3LockAndPrepare(db,zSql,nBytes,1,0,ppStmt,pzTail);
99371   assert( rc==SQLITE_OK || ppStmt==0 || *ppStmt==0 );  /* VERIFY: F13021 */
99372   return rc;
99373 }
99374 
99375 
99376 #ifndef SQLITE_OMIT_UTF16
99377 /*
99378 ** Compile the UTF-16 encoded SQL statement zSql into a statement handle.
99379 */
99380 static int sqlite3Prepare16(
99381   sqlite3 *db,              /* Database handle. */ 
99382   const void *zSql,         /* UTF-16 encoded SQL statement. */
99383   int nBytes,               /* Length of zSql in bytes. */
99384   int saveSqlFlag,          /* True to save SQL text into the sqlite3_stmt */
99385   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99386   const void **pzTail       /* OUT: End of parsed string */
99387 ){
99388   /* This function currently works by first transforming the UTF-16
99389   ** encoded string to UTF-8, then invoking sqlite3_prepare(). The
99390   ** tricky bit is figuring out the pointer to return in *pzTail.
99391   */
99392   char *zSql8;
99393   const char *zTail8 = 0;
99394   int rc = SQLITE_OK;
99395 
99396   assert( ppStmt );
99397   *ppStmt = 0;
99398   if( !sqlite3SafetyCheckOk(db) ){
99399     return SQLITE_MISUSE_BKPT;
99400   }
99401   if( nBytes>=0 ){
99402     int sz;
99403     const char *z = (const char*)zSql;
99404     for(sz=0; sz<nBytes && (z[sz]!=0 || z[sz+1]!=0); sz += 2){}
99405     nBytes = sz;
99406   }
99407   sqlite3_mutex_enter(db->mutex);
99408   zSql8 = sqlite3Utf16to8(db, zSql, nBytes, SQLITE_UTF16NATIVE);
99409   if( zSql8 ){
99410     rc = sqlite3LockAndPrepare(db, zSql8, -1, saveSqlFlag, 0, ppStmt, &zTail8);
99411   }
99412 
99413   if( zTail8 && pzTail ){
99414     /* If sqlite3_prepare returns a tail pointer, we calculate the
99415     ** equivalent pointer into the UTF-16 string by counting the unicode
99416     ** characters between zSql8 and zTail8, and then returning a pointer
99417     ** the same number of characters into the UTF-16 string.
99418     */
99419     int chars_parsed = sqlite3Utf8CharLen(zSql8, (int)(zTail8-zSql8));
99420     *pzTail = (u8 *)zSql + sqlite3Utf16ByteLen(zSql, chars_parsed);
99421   }
99422   sqlite3DbFree(db, zSql8); 
99423   rc = sqlite3ApiExit(db, rc);
99424   sqlite3_mutex_leave(db->mutex);
99425   return rc;
99426 }
99427 
99428 /*
99429 ** Two versions of the official API.  Legacy and new use.  In the legacy
99430 ** version, the original SQL text is not saved in the prepared statement
99431 ** and so if a schema change occurs, SQLITE_SCHEMA is returned by
99432 ** sqlite3_step().  In the new version, the original SQL text is retained
99433 ** and the statement is automatically recompiled if an schema change
99434 ** occurs.
99435 */
99436 SQLITE_API int sqlite3_prepare16(
99437   sqlite3 *db,              /* Database handle. */ 
99438   const void *zSql,         /* UTF-16 encoded SQL statement. */
99439   int nBytes,               /* Length of zSql in bytes. */
99440   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99441   const void **pzTail       /* OUT: End of parsed string */
99442 ){
99443   int rc;
99444   rc = sqlite3Prepare16(db,zSql,nBytes,0,ppStmt,pzTail);
99445   assert( rc==SQLITE_OK || ppStmt==0 || *ppStmt==0 );  /* VERIFY: F13021 */
99446   return rc;
99447 }
99448 SQLITE_API int sqlite3_prepare16_v2(
99449   sqlite3 *db,              /* Database handle. */ 
99450   const void *zSql,         /* UTF-16 encoded SQL statement. */
99451   int nBytes,               /* Length of zSql in bytes. */
99452   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99453   const void **pzTail       /* OUT: End of parsed string */
99454 ){
99455   int rc;
99456   rc = sqlite3Prepare16(db,zSql,nBytes,1,ppStmt,pzTail);
99457   assert( rc==SQLITE_OK || ppStmt==0 || *ppStmt==0 );  /* VERIFY: F13021 */
99458   return rc;
99459 }
99460 
99461 #endif /* SQLITE_OMIT_UTF16 */
99462 
99463 /************** End of prepare.c *********************************************/
99464 /************** Begin file select.c ******************************************/
99465 /*
99466 ** 2001 September 15
99467 **
99468 ** The author disclaims copyright to this source code.  In place of
99469 ** a legal notice, here is a blessing:
99470 **
99471 **    May you do good and not evil.
99472 **    May you find forgiveness for yourself and forgive others.
99473 **    May you share freely, never taking more than you give.
99474 **
99475 *************************************************************************
99476 ** This file contains C code routines that are called by the parser
99477 ** to handle SELECT statements in SQLite.
99478 */
99479 
99480 
99481 /*
99482 ** Delete all the content of a Select structure but do not deallocate
99483 ** the select structure itself.
99484 */
99485 static void clearSelect(sqlite3 *db, Select *p){
99486   sqlite3ExprListDelete(db, p->pEList);
99487   sqlite3SrcListDelete(db, p->pSrc);
99488   sqlite3ExprDelete(db, p->pWhere);
99489   sqlite3ExprListDelete(db, p->pGroupBy);
99490   sqlite3ExprDelete(db, p->pHaving);
99491   sqlite3ExprListDelete(db, p->pOrderBy);
99492   sqlite3SelectDelete(db, p->pPrior);
99493   sqlite3ExprDelete(db, p->pLimit);
99494   sqlite3ExprDelete(db, p->pOffset);
99495 }
99496 
99497 /*
99498 ** Initialize a SelectDest structure.
99499 */
99500 SQLITE_PRIVATE void sqlite3SelectDestInit(SelectDest *pDest, int eDest, int iParm){
99501   pDest->eDest = (u8)eDest;
99502   pDest->iSDParm = iParm;
99503   pDest->affSdst = 0;
99504   pDest->iSdst = 0;
99505   pDest->nSdst = 0;
99506 }
99507 
99508 
99509 /*
99510 ** Allocate a new Select structure and return a pointer to that
99511 ** structure.
99512 */
99513 SQLITE_PRIVATE Select *sqlite3SelectNew(
99514   Parse *pParse,        /* Parsing context */
99515   ExprList *pEList,     /* which columns to include in the result */
99516   SrcList *pSrc,        /* the FROM clause -- which tables to scan */
99517   Expr *pWhere,         /* the WHERE clause */
99518   ExprList *pGroupBy,   /* the GROUP BY clause */
99519   Expr *pHaving,        /* the HAVING clause */
99520   ExprList *pOrderBy,   /* the ORDER BY clause */
99521   u16 selFlags,         /* Flag parameters, such as SF_Distinct */
99522   Expr *pLimit,         /* LIMIT value.  NULL means not used */
99523   Expr *pOffset         /* OFFSET value.  NULL means no offset */
99524 ){
99525   Select *pNew;
99526   Select standin;
99527   sqlite3 *db = pParse->db;
99528   pNew = sqlite3DbMallocZero(db, sizeof(*pNew) );
99529   assert( db->mallocFailed || !pOffset || pLimit ); /* OFFSET implies LIMIT */
99530   if( pNew==0 ){
99531     assert( db->mallocFailed );
99532     pNew = &standin;
99533     memset(pNew, 0, sizeof(*pNew));
99534   }
99535   if( pEList==0 ){
99536     pEList = sqlite3ExprListAppend(pParse, 0, sqlite3Expr(db,TK_ALL,0));
99537   }
99538   pNew->pEList = pEList;
99539   if( pSrc==0 ) pSrc = sqlite3DbMallocZero(db, sizeof(*pSrc));
99540   pNew->pSrc = pSrc;
99541   pNew->pWhere = pWhere;
99542   pNew->pGroupBy = pGroupBy;
99543   pNew->pHaving = pHaving;
99544   pNew->pOrderBy = pOrderBy;
99545   pNew->selFlags = selFlags;
99546   pNew->op = TK_SELECT;
99547   pNew->pLimit = pLimit;
99548   pNew->pOffset = pOffset;
99549   assert( pOffset==0 || pLimit!=0 );
99550   pNew->addrOpenEphm[0] = -1;
99551   pNew->addrOpenEphm[1] = -1;
99552   pNew->addrOpenEphm[2] = -1;
99553   if( db->mallocFailed ) {
99554     clearSelect(db, pNew);
99555     if( pNew!=&standin ) sqlite3DbFree(db, pNew);
99556     pNew = 0;
99557   }else{
99558     assert( pNew->pSrc!=0 || pParse->nErr>0 );
99559   }
99560   assert( pNew!=&standin );
99561   return pNew;
99562 }
99563 
99564 /*
99565 ** Delete the given Select structure and all of its substructures.
99566 */
99567 SQLITE_PRIVATE void sqlite3SelectDelete(sqlite3 *db, Select *p){
99568   if( p ){
99569     clearSelect(db, p);
99570     sqlite3DbFree(db, p);
99571   }
99572 }
99573 
99574 /*
99575 ** Given 1 to 3 identifiers preceding the JOIN keyword, determine the
99576 ** type of join.  Return an integer constant that expresses that type
99577 ** in terms of the following bit values:
99578 **
99579 **     JT_INNER
99580 **     JT_CROSS
99581 **     JT_OUTER
99582 **     JT_NATURAL
99583 **     JT_LEFT
99584 **     JT_RIGHT
99585 **
99586 ** A full outer join is the combination of JT_LEFT and JT_RIGHT.
99587 **
99588 ** If an illegal or unsupported join type is seen, then still return
99589 ** a join type, but put an error in the pParse structure.
99590 */
99591 SQLITE_PRIVATE int sqlite3JoinType(Parse *pParse, Token *pA, Token *pB, Token *pC){
99592   int jointype = 0;
99593   Token *apAll[3];
99594   Token *p;
99595                              /*   0123456789 123456789 123456789 123 */
99596   static const char zKeyText[] = "naturaleftouterightfullinnercross";
99597   static const struct {
99598     u8 i;        /* Beginning of keyword text in zKeyText[] */
99599     u8 nChar;    /* Length of the keyword in characters */
99600     u8 code;     /* Join type mask */
99601   } aKeyword[] = {
99602     /* natural */ { 0,  7, JT_NATURAL                },
99603     /* left    */ { 6,  4, JT_LEFT|JT_OUTER          },
99604     /* outer   */ { 10, 5, JT_OUTER                  },
99605     /* right   */ { 14, 5, JT_RIGHT|JT_OUTER         },
99606     /* full    */ { 19, 4, JT_LEFT|JT_RIGHT|JT_OUTER },
99607     /* inner   */ { 23, 5, JT_INNER                  },
99608     /* cross   */ { 28, 5, JT_INNER|JT_CROSS         },
99609   };
99610   int i, j;
99611   apAll[0] = pA;
99612   apAll[1] = pB;
99613   apAll[2] = pC;
99614   for(i=0; i<3 && apAll[i]; i++){
99615     p = apAll[i];
99616     for(j=0; j<ArraySize(aKeyword); j++){
99617       if( p->n==aKeyword[j].nChar 
99618           && sqlite3StrNICmp((char*)p->z, &zKeyText[aKeyword[j].i], p->n)==0 ){
99619         jointype |= aKeyword[j].code;
99620         break;
99621       }
99622     }
99623     testcase( j==0 || j==1 || j==2 || j==3 || j==4 || j==5 || j==6 );
99624     if( j>=ArraySize(aKeyword) ){
99625       jointype |= JT_ERROR;
99626       break;
99627     }
99628   }
99629   if(
99630      (jointype & (JT_INNER|JT_OUTER))==(JT_INNER|JT_OUTER) ||
99631      (jointype & JT_ERROR)!=0
99632   ){
99633     const char *zSp = " ";
99634     assert( pB!=0 );
99635     if( pC==0 ){ zSp++; }
99636     sqlite3ErrorMsg(pParse, "unknown or unsupported join type: "
99637        "%T %T%s%T", pA, pB, zSp, pC);
99638     jointype = JT_INNER;
99639   }else if( (jointype & JT_OUTER)!=0 
99640          && (jointype & (JT_LEFT|JT_RIGHT))!=JT_LEFT ){
99641     sqlite3ErrorMsg(pParse, 
99642       "RIGHT and FULL OUTER JOINs are not currently supported");
99643     jointype = JT_INNER;
99644   }
99645   return jointype;
99646 }
99647 
99648 /*
99649 ** Return the index of a column in a table.  Return -1 if the column
99650 ** is not contained in the table.
99651 */
99652 static int columnIndex(Table *pTab, const char *zCol){
99653   int i;
99654   for(i=0; i<pTab->nCol; i++){
99655     if( sqlite3StrICmp(pTab->aCol[i].zName, zCol)==0 ) return i;
99656   }
99657   return -1;
99658 }
99659 
99660 /*
99661 ** Search the first N tables in pSrc, from left to right, looking for a
99662 ** table that has a column named zCol.  
99663 **
99664 ** When found, set *piTab and *piCol to the table index and column index
99665 ** of the matching column and return TRUE.
99666 **
99667 ** If not found, return FALSE.
99668 */
99669 static int tableAndColumnIndex(
99670   SrcList *pSrc,       /* Array of tables to search */
99671   int N,               /* Number of tables in pSrc->a[] to search */
99672   const char *zCol,    /* Name of the column we are looking for */
99673   int *piTab,          /* Write index of pSrc->a[] here */
99674   int *piCol           /* Write index of pSrc->a[*piTab].pTab->aCol[] here */
99675 ){
99676   int i;               /* For looping over tables in pSrc */
99677   int iCol;            /* Index of column matching zCol */
99678 
99679   assert( (piTab==0)==(piCol==0) );  /* Both or neither are NULL */
99680   for(i=0; i<N; i++){
99681     iCol = columnIndex(pSrc->a[i].pTab, zCol);
99682     if( iCol>=0 ){
99683       if( piTab ){
99684         *piTab = i;
99685         *piCol = iCol;
99686       }
99687       return 1;
99688     }
99689   }
99690   return 0;
99691 }
99692 
99693 /*
99694 ** This function is used to add terms implied by JOIN syntax to the
99695 ** WHERE clause expression of a SELECT statement. The new term, which
99696 ** is ANDed with the existing WHERE clause, is of the form:
99697 **
99698 **    (tab1.col1 = tab2.col2)
99699 **
99700 ** where tab1 is the iSrc'th table in SrcList pSrc and tab2 is the 
99701 ** (iSrc+1)'th. Column col1 is column iColLeft of tab1, and col2 is
99702 ** column iColRight of tab2.
99703 */
99704 static void addWhereTerm(
99705   Parse *pParse,                  /* Parsing context */
99706   SrcList *pSrc,                  /* List of tables in FROM clause */
99707   int iLeft,                      /* Index of first table to join in pSrc */
99708   int iColLeft,                   /* Index of column in first table */
99709   int iRight,                     /* Index of second table in pSrc */
99710   int iColRight,                  /* Index of column in second table */
99711   int isOuterJoin,                /* True if this is an OUTER join */
99712   Expr **ppWhere                  /* IN/OUT: The WHERE clause to add to */
99713 ){
99714   sqlite3 *db = pParse->db;
99715   Expr *pE1;
99716   Expr *pE2;
99717   Expr *pEq;
99718 
99719   assert( iLeft<iRight );
99720   assert( pSrc->nSrc>iRight );
99721   assert( pSrc->a[iLeft].pTab );
99722   assert( pSrc->a[iRight].pTab );
99723 
99724   pE1 = sqlite3CreateColumnExpr(db, pSrc, iLeft, iColLeft);
99725   pE2 = sqlite3CreateColumnExpr(db, pSrc, iRight, iColRight);
99726 
99727   pEq = sqlite3PExpr(pParse, TK_EQ, pE1, pE2, 0);
99728   if( pEq && isOuterJoin ){
99729     ExprSetProperty(pEq, EP_FromJoin);
99730     assert( !ExprHasProperty(pEq, EP_TokenOnly|EP_Reduced) );
99731     ExprSetVVAProperty(pEq, EP_NoReduce);
99732     pEq->iRightJoinTable = (i16)pE2->iTable;
99733   }
99734   *ppWhere = sqlite3ExprAnd(db, *ppWhere, pEq);
99735 }
99736 
99737 /*
99738 ** Set the EP_FromJoin property on all terms of the given expression.
99739 ** And set the Expr.iRightJoinTable to iTable for every term in the
99740 ** expression.
99741 **
99742 ** The EP_FromJoin property is used on terms of an expression to tell
99743 ** the LEFT OUTER JOIN processing logic that this term is part of the
99744 ** join restriction specified in the ON or USING clause and not a part
99745 ** of the more general WHERE clause.  These terms are moved over to the
99746 ** WHERE clause during join processing but we need to remember that they
99747 ** originated in the ON or USING clause.
99748 **
99749 ** The Expr.iRightJoinTable tells the WHERE clause processing that the
99750 ** expression depends on table iRightJoinTable even if that table is not
99751 ** explicitly mentioned in the expression.  That information is needed
99752 ** for cases like this:
99753 **
99754 **    SELECT * FROM t1 LEFT JOIN t2 ON t1.a=t2.b AND t1.x=5
99755 **
99756 ** The where clause needs to defer the handling of the t1.x=5
99757 ** term until after the t2 loop of the join.  In that way, a
99758 ** NULL t2 row will be inserted whenever t1.x!=5.  If we do not
99759 ** defer the handling of t1.x=5, it will be processed immediately
99760 ** after the t1 loop and rows with t1.x!=5 will never appear in
99761 ** the output, which is incorrect.
99762 */
99763 static void setJoinExpr(Expr *p, int iTable){
99764   while( p ){
99765     ExprSetProperty(p, EP_FromJoin);
99766     assert( !ExprHasProperty(p, EP_TokenOnly|EP_Reduced) );
99767     ExprSetVVAProperty(p, EP_NoReduce);
99768     p->iRightJoinTable = (i16)iTable;
99769     setJoinExpr(p->pLeft, iTable);
99770     p = p->pRight;
99771   } 
99772 }
99773 
99774 /*
99775 ** This routine processes the join information for a SELECT statement.
99776 ** ON and USING clauses are converted into extra terms of the WHERE clause.
99777 ** NATURAL joins also create extra WHERE clause terms.
99778 **
99779 ** The terms of a FROM clause are contained in the Select.pSrc structure.
99780 ** The left most table is the first entry in Select.pSrc.  The right-most
99781 ** table is the last entry.  The join operator is held in the entry to
99782 ** the left.  Thus entry 0 contains the join operator for the join between
99783 ** entries 0 and 1.  Any ON or USING clauses associated with the join are
99784 ** also attached to the left entry.
99785 **
99786 ** This routine returns the number of errors encountered.
99787 */
99788 static int sqliteProcessJoin(Parse *pParse, Select *p){
99789   SrcList *pSrc;                  /* All tables in the FROM clause */
99790   int i, j;                       /* Loop counters */
99791   struct SrcList_item *pLeft;     /* Left table being joined */
99792   struct SrcList_item *pRight;    /* Right table being joined */
99793 
99794   pSrc = p->pSrc;
99795   pLeft = &pSrc->a[0];
99796   pRight = &pLeft[1];
99797   for(i=0; i<pSrc->nSrc-1; i++, pRight++, pLeft++){
99798     Table *pLeftTab = pLeft->pTab;
99799     Table *pRightTab = pRight->pTab;
99800     int isOuter;
99801 
99802     if( NEVER(pLeftTab==0 || pRightTab==0) ) continue;
99803     isOuter = (pRight->jointype & JT_OUTER)!=0;
99804 
99805     /* When the NATURAL keyword is present, add WHERE clause terms for
99806     ** every column that the two tables have in common.
99807     */
99808     if( pRight->jointype & JT_NATURAL ){
99809       if( pRight->pOn || pRight->pUsing ){
99810         sqlite3ErrorMsg(pParse, "a NATURAL join may not have "
99811            "an ON or USING clause", 0);
99812         return 1;
99813       }
99814       for(j=0; j<pRightTab->nCol; j++){
99815         char *zName;   /* Name of column in the right table */
99816         int iLeft;     /* Matching left table */
99817         int iLeftCol;  /* Matching column in the left table */
99818 
99819         zName = pRightTab->aCol[j].zName;
99820         if( tableAndColumnIndex(pSrc, i+1, zName, &iLeft, &iLeftCol) ){
99821           addWhereTerm(pParse, pSrc, iLeft, iLeftCol, i+1, j,
99822                        isOuter, &p->pWhere);
99823         }
99824       }
99825     }
99826 
99827     /* Disallow both ON and USING clauses in the same join
99828     */
99829     if( pRight->pOn && pRight->pUsing ){
99830       sqlite3ErrorMsg(pParse, "cannot have both ON and USING "
99831         "clauses in the same join");
99832       return 1;
99833     }
99834 
99835     /* Add the ON clause to the end of the WHERE clause, connected by
99836     ** an AND operator.
99837     */
99838     if( pRight->pOn ){
99839       if( isOuter ) setJoinExpr(pRight->pOn, pRight->iCursor);
99840       p->pWhere = sqlite3ExprAnd(pParse->db, p->pWhere, pRight->pOn);
99841       pRight->pOn = 0;
99842     }
99843 
99844     /* Create extra terms on the WHERE clause for each column named
99845     ** in the USING clause.  Example: If the two tables to be joined are 
99846     ** A and B and the USING clause names X, Y, and Z, then add this
99847     ** to the WHERE clause:    A.X=B.X AND A.Y=B.Y AND A.Z=B.Z
99848     ** Report an error if any column mentioned in the USING clause is
99849     ** not contained in both tables to be joined.
99850     */
99851     if( pRight->pUsing ){
99852       IdList *pList = pRight->pUsing;
99853       for(j=0; j<pList->nId; j++){
99854         char *zName;     /* Name of the term in the USING clause */
99855         int iLeft;       /* Table on the left with matching column name */
99856         int iLeftCol;    /* Column number of matching column on the left */
99857         int iRightCol;   /* Column number of matching column on the right */
99858 
99859         zName = pList->a[j].zName;
99860         iRightCol = columnIndex(pRightTab, zName);
99861         if( iRightCol<0
99862          || !tableAndColumnIndex(pSrc, i+1, zName, &iLeft, &iLeftCol)
99863         ){
99864           sqlite3ErrorMsg(pParse, "cannot join using column %s - column "
99865             "not present in both tables", zName);
99866           return 1;
99867         }
99868         addWhereTerm(pParse, pSrc, iLeft, iLeftCol, i+1, iRightCol,
99869                      isOuter, &p->pWhere);
99870       }
99871     }
99872   }
99873   return 0;
99874 }
99875 
99876 /*
99877 ** Insert code into "v" that will push the record on the top of the
99878 ** stack into the sorter.
99879 */
99880 static void pushOntoSorter(
99881   Parse *pParse,         /* Parser context */
99882   ExprList *pOrderBy,    /* The ORDER BY clause */
99883   Select *pSelect,       /* The whole SELECT statement */
99884   int regData            /* Register holding data to be sorted */
99885 ){
99886   Vdbe *v = pParse->pVdbe;
99887   int nExpr = pOrderBy->nExpr;
99888   int regBase = sqlite3GetTempRange(pParse, nExpr+2);
99889   int regRecord = sqlite3GetTempReg(pParse);
99890   int op;
99891   sqlite3ExprCacheClear(pParse);
99892   sqlite3ExprCodeExprList(pParse, pOrderBy, regBase, 0);
99893   sqlite3VdbeAddOp2(v, OP_Sequence, pOrderBy->iECursor, regBase+nExpr);
99894   sqlite3ExprCodeMove(pParse, regData, regBase+nExpr+1, 1);
99895   sqlite3VdbeAddOp3(v, OP_MakeRecord, regBase, nExpr + 2, regRecord);
99896   if( pSelect->selFlags & SF_UseSorter ){
99897     op = OP_SorterInsert;
99898   }else{
99899     op = OP_IdxInsert;
99900   }
99901   sqlite3VdbeAddOp2(v, op, pOrderBy->iECursor, regRecord);
99902   sqlite3ReleaseTempReg(pParse, regRecord);
99903   sqlite3ReleaseTempRange(pParse, regBase, nExpr+2);
99904   if( pSelect->iLimit ){
99905     int addr1, addr2;
99906     int iLimit;
99907     if( pSelect->iOffset ){
99908       iLimit = pSelect->iOffset+1;
99909     }else{
99910       iLimit = pSelect->iLimit;
99911     }
99912     addr1 = sqlite3VdbeAddOp1(v, OP_IfZero, iLimit);
99913     sqlite3VdbeAddOp2(v, OP_AddImm, iLimit, -1);
99914     addr2 = sqlite3VdbeAddOp0(v, OP_Goto);
99915     sqlite3VdbeJumpHere(v, addr1);
99916     sqlite3VdbeAddOp1(v, OP_Last, pOrderBy->iECursor);
99917     sqlite3VdbeAddOp1(v, OP_Delete, pOrderBy->iECursor);
99918     sqlite3VdbeJumpHere(v, addr2);
99919   }
99920 }
99921 
99922 /*
99923 ** Add code to implement the OFFSET
99924 */
99925 static void codeOffset(
99926   Vdbe *v,          /* Generate code into this VM */
99927   Select *p,        /* The SELECT statement being coded */
99928   int iContinue     /* Jump here to skip the current record */
99929 ){
99930   if( p->iOffset && iContinue!=0 ){
99931     int addr;
99932     sqlite3VdbeAddOp2(v, OP_AddImm, p->iOffset, -1);
99933     addr = sqlite3VdbeAddOp1(v, OP_IfNeg, p->iOffset);
99934     sqlite3VdbeAddOp2(v, OP_Goto, 0, iContinue);
99935     VdbeComment((v, "skip OFFSET records"));
99936     sqlite3VdbeJumpHere(v, addr);
99937   }
99938 }
99939 
99940 /*
99941 ** Add code that will check to make sure the N registers starting at iMem
99942 ** form a distinct entry.  iTab is a sorting index that holds previously
99943 ** seen combinations of the N values.  A new entry is made in iTab
99944 ** if the current N values are new.
99945 **
99946 ** A jump to addrRepeat is made and the N+1 values are popped from the
99947 ** stack if the top N elements are not distinct.
99948 */
99949 static void codeDistinct(
99950   Parse *pParse,     /* Parsing and code generating context */
99951   int iTab,          /* A sorting index used to test for distinctness */
99952   int addrRepeat,    /* Jump to here if not distinct */
99953   int N,             /* Number of elements */
99954   int iMem           /* First element */
99955 ){
99956   Vdbe *v;
99957   int r1;
99958 
99959   v = pParse->pVdbe;
99960   r1 = sqlite3GetTempReg(pParse);
99961   sqlite3VdbeAddOp4Int(v, OP_Found, iTab, addrRepeat, iMem, N);
99962   sqlite3VdbeAddOp3(v, OP_MakeRecord, iMem, N, r1);
99963   sqlite3VdbeAddOp2(v, OP_IdxInsert, iTab, r1);
99964   sqlite3ReleaseTempReg(pParse, r1);
99965 }
99966 
99967 #ifndef SQLITE_OMIT_SUBQUERY
99968 /*
99969 ** Generate an error message when a SELECT is used within a subexpression
99970 ** (example:  "a IN (SELECT * FROM table)") but it has more than 1 result
99971 ** column.  We do this in a subroutine because the error used to occur
99972 ** in multiple places.  (The error only occurs in one place now, but we
99973 ** retain the subroutine to minimize code disruption.)
99974 */
99975 static int checkForMultiColumnSelectError(
99976   Parse *pParse,       /* Parse context. */
99977   SelectDest *pDest,   /* Destination of SELECT results */
99978   int nExpr            /* Number of result columns returned by SELECT */
99979 ){
99980   int eDest = pDest->eDest;
99981   if( nExpr>1 && (eDest==SRT_Mem || eDest==SRT_Set) ){
99982     sqlite3ErrorMsg(pParse, "only a single result allowed for "
99983        "a SELECT that is part of an expression");
99984     return 1;
99985   }else{
99986     return 0;
99987   }
99988 }
99989 #endif
99990 
99991 /*
99992 ** An instance of the following object is used to record information about
99993 ** how to process the DISTINCT keyword, to simplify passing that information
99994 ** into the selectInnerLoop() routine.
99995 */
99996 typedef struct DistinctCtx DistinctCtx;
99997 struct DistinctCtx {
99998   u8 isTnct;      /* True if the DISTINCT keyword is present */
99999   u8 eTnctType;   /* One of the WHERE_DISTINCT_* operators */
100000   int tabTnct;    /* Ephemeral table used for DISTINCT processing */
100001   int addrTnct;   /* Address of OP_OpenEphemeral opcode for tabTnct */
100002 };
100003 
100004 /*
100005 ** This routine generates the code for the inside of the inner loop
100006 ** of a SELECT.
100007 **
100008 ** If srcTab and nColumn are both zero, then the pEList expressions
100009 ** are evaluated in order to get the data for this row.  If nColumn>0
100010 ** then data is pulled from srcTab and pEList is used only to get the
100011 ** datatypes for each column.
100012 */
100013 static void selectInnerLoop(
100014   Parse *pParse,          /* The parser context */
100015   Select *p,              /* The complete select statement being coded */
100016   ExprList *pEList,       /* List of values being extracted */
100017   int srcTab,             /* Pull data from this table */
100018   int nColumn,            /* Number of columns in the source table */
100019   ExprList *pOrderBy,     /* If not NULL, sort results using this key */
100020   DistinctCtx *pDistinct, /* If not NULL, info on how to process DISTINCT */
100021   SelectDest *pDest,      /* How to dispose of the results */
100022   int iContinue,          /* Jump here to continue with next row */
100023   int iBreak              /* Jump here to break out of the inner loop */
100024 ){
100025   Vdbe *v = pParse->pVdbe;
100026   int i;
100027   int hasDistinct;        /* True if the DISTINCT keyword is present */
100028   int regResult;              /* Start of memory holding result set */
100029   int eDest = pDest->eDest;   /* How to dispose of results */
100030   int iParm = pDest->iSDParm; /* First argument to disposal method */
100031   int nResultCol;             /* Number of result columns */
100032 
100033   assert( v );
100034   if( NEVER(v==0) ) return;
100035   assert( pEList!=0 );
100036   hasDistinct = pDistinct ? pDistinct->eTnctType : WHERE_DISTINCT_NOOP;
100037   if( pOrderBy==0 && !hasDistinct ){
100038     codeOffset(v, p, iContinue);
100039   }
100040 
100041   /* Pull the requested columns.
100042   */
100043   if( nColumn>0 ){
100044     nResultCol = nColumn;
100045   }else{
100046     nResultCol = pEList->nExpr;
100047   }
100048   if( pDest->iSdst==0 ){
100049     pDest->iSdst = pParse->nMem+1;
100050     pDest->nSdst = nResultCol;
100051     pParse->nMem += nResultCol;
100052   }else{ 
100053     assert( pDest->nSdst==nResultCol );
100054   }
100055   regResult = pDest->iSdst;
100056   if( nColumn>0 ){
100057     for(i=0; i<nColumn; i++){
100058       sqlite3VdbeAddOp3(v, OP_Column, srcTab, i, regResult+i);
100059     }
100060   }else if( eDest!=SRT_Exists ){
100061     /* If the destination is an EXISTS(...) expression, the actual
100062     ** values returned by the SELECT are not required.
100063     */
100064     sqlite3ExprCacheClear(pParse);
100065     sqlite3ExprCodeExprList(pParse, pEList, regResult,
100066                             (eDest==SRT_Output)?SQLITE_ECEL_DUP:0);
100067   }
100068   nColumn = nResultCol;
100069 
100070   /* If the DISTINCT keyword was present on the SELECT statement
100071   ** and this row has been seen before, then do not make this row
100072   ** part of the result.
100073   */
100074   if( hasDistinct ){
100075     assert( pEList!=0 );
100076     assert( pEList->nExpr==nColumn );
100077     switch( pDistinct->eTnctType ){
100078       case WHERE_DISTINCT_ORDERED: {
100079         VdbeOp *pOp;            /* No longer required OpenEphemeral instr. */
100080         int iJump;              /* Jump destination */
100081         int regPrev;            /* Previous row content */
100082 
100083         /* Allocate space for the previous row */
100084         regPrev = pParse->nMem+1;
100085         pParse->nMem += nColumn;
100086 
100087         /* Change the OP_OpenEphemeral coded earlier to an OP_Null
100088         ** sets the MEM_Cleared bit on the first register of the
100089         ** previous value.  This will cause the OP_Ne below to always
100090         ** fail on the first iteration of the loop even if the first
100091         ** row is all NULLs.
100092         */
100093         sqlite3VdbeChangeToNoop(v, pDistinct->addrTnct);
100094         pOp = sqlite3VdbeGetOp(v, pDistinct->addrTnct);
100095         pOp->opcode = OP_Null;
100096         pOp->p1 = 1;
100097         pOp->p2 = regPrev;
100098 
100099         iJump = sqlite3VdbeCurrentAddr(v) + nColumn;
100100         for(i=0; i<nColumn; i++){
100101           CollSeq *pColl = sqlite3ExprCollSeq(pParse, pEList->a[i].pExpr);
100102           if( i<nColumn-1 ){
100103             sqlite3VdbeAddOp3(v, OP_Ne, regResult+i, iJump, regPrev+i);
100104           }else{
100105             sqlite3VdbeAddOp3(v, OP_Eq, regResult+i, iContinue, regPrev+i);
100106           }
100107           sqlite3VdbeChangeP4(v, -1, (const char *)pColl, P4_COLLSEQ);
100108           sqlite3VdbeChangeP5(v, SQLITE_NULLEQ);
100109         }
100110         assert( sqlite3VdbeCurrentAddr(v)==iJump );
100111         sqlite3VdbeAddOp3(v, OP_Copy, regResult, regPrev, nColumn-1);
100112         break;
100113       }
100114 
100115       case WHERE_DISTINCT_UNIQUE: {
100116         sqlite3VdbeChangeToNoop(v, pDistinct->addrTnct);
100117         break;
100118       }
100119 
100120       default: {
100121         assert( pDistinct->eTnctType==WHERE_DISTINCT_UNORDERED );
100122         codeDistinct(pParse, pDistinct->tabTnct, iContinue, nColumn, regResult);
100123         break;
100124       }
100125     }
100126     if( pOrderBy==0 ){
100127       codeOffset(v, p, iContinue);
100128     }
100129   }
100130 
100131   switch( eDest ){
100132     /* In this mode, write each query result to the key of the temporary
100133     ** table iParm.
100134     */
100135 #ifndef SQLITE_OMIT_COMPOUND_SELECT
100136     case SRT_Union: {
100137       int r1;
100138       r1 = sqlite3GetTempReg(pParse);
100139       sqlite3VdbeAddOp3(v, OP_MakeRecord, regResult, nColumn, r1);
100140       sqlite3VdbeAddOp2(v, OP_IdxInsert, iParm, r1);
100141       sqlite3ReleaseTempReg(pParse, r1);
100142       break;
100143     }
100144 
100145     /* Construct a record from the query result, but instead of
100146     ** saving that record, use it as a key to delete elements from
100147     ** the temporary table iParm.
100148     */
100149     case SRT_Except: {
100150       sqlite3VdbeAddOp3(v, OP_IdxDelete, iParm, regResult, nColumn);
100151       break;
100152     }
100153 #endif
100154 
100155     /* Store the result as data using a unique key.
100156     */
100157     case SRT_Table:
100158     case SRT_EphemTab: {
100159       int r1 = sqlite3GetTempReg(pParse);
100160       testcase( eDest==SRT_Table );
100161       testcase( eDest==SRT_EphemTab );
100162       sqlite3VdbeAddOp3(v, OP_MakeRecord, regResult, nColumn, r1);
100163       if( pOrderBy ){
100164         pushOntoSorter(pParse, pOrderBy, p, r1);
100165       }else{
100166         int r2 = sqlite3GetTempReg(pParse);
100167         sqlite3VdbeAddOp2(v, OP_NewRowid, iParm, r2);
100168         sqlite3VdbeAddOp3(v, OP_Insert, iParm, r1, r2);
100169         sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
100170         sqlite3ReleaseTempReg(pParse, r2);
100171       }
100172       sqlite3ReleaseTempReg(pParse, r1);
100173       break;
100174     }
100175 
100176 #ifndef SQLITE_OMIT_SUBQUERY
100177     /* If we are creating a set for an "expr IN (SELECT ...)" construct,
100178     ** then there should be a single item on the stack.  Write this
100179     ** item into the set table with bogus data.
100180     */
100181     case SRT_Set: {
100182       assert( nColumn==1 );
100183       pDest->affSdst =
100184                   sqlite3CompareAffinity(pEList->a[0].pExpr, pDest->affSdst);
100185       if( pOrderBy ){
100186         /* At first glance you would think we could optimize out the
100187         ** ORDER BY in this case since the order of entries in the set
100188         ** does not matter.  But there might be a LIMIT clause, in which
100189         ** case the order does matter */
100190         pushOntoSorter(pParse, pOrderBy, p, regResult);
100191       }else{
100192         int r1 = sqlite3GetTempReg(pParse);
100193         sqlite3VdbeAddOp4(v, OP_MakeRecord, regResult,1,r1, &pDest->affSdst, 1);
100194         sqlite3ExprCacheAffinityChange(pParse, regResult, 1);
100195         sqlite3VdbeAddOp2(v, OP_IdxInsert, iParm, r1);
100196         sqlite3ReleaseTempReg(pParse, r1);
100197       }
100198       break;
100199     }
100200 
100201     /* If any row exist in the result set, record that fact and abort.
100202     */
100203     case SRT_Exists: {
100204       sqlite3VdbeAddOp2(v, OP_Integer, 1, iParm);
100205       /* The LIMIT clause will terminate the loop for us */
100206       break;
100207     }
100208 
100209     /* If this is a scalar select that is part of an expression, then
100210     ** store the results in the appropriate memory cell and break out
100211     ** of the scan loop.
100212     */
100213     case SRT_Mem: {
100214       assert( nColumn==1 );
100215       if( pOrderBy ){
100216         pushOntoSorter(pParse, pOrderBy, p, regResult);
100217       }else{
100218         sqlite3ExprCodeMove(pParse, regResult, iParm, 1);
100219         /* The LIMIT clause will jump out of the loop for us */
100220       }
100221       break;
100222     }
100223 #endif /* #ifndef SQLITE_OMIT_SUBQUERY */
100224 
100225     /* Send the data to the callback function or to a subroutine.  In the
100226     ** case of a subroutine, the subroutine itself is responsible for
100227     ** popping the data from the stack.
100228     */
100229     case SRT_Coroutine:
100230     case SRT_Output: {
100231       testcase( eDest==SRT_Coroutine );
100232       testcase( eDest==SRT_Output );
100233       if( pOrderBy ){
100234         int r1 = sqlite3GetTempReg(pParse);
100235         sqlite3VdbeAddOp3(v, OP_MakeRecord, regResult, nColumn, r1);
100236         pushOntoSorter(pParse, pOrderBy, p, r1);
100237         sqlite3ReleaseTempReg(pParse, r1);
100238       }else if( eDest==SRT_Coroutine ){
100239         sqlite3VdbeAddOp1(v, OP_Yield, pDest->iSDParm);
100240       }else{
100241         sqlite3VdbeAddOp2(v, OP_ResultRow, regResult, nColumn);
100242         sqlite3ExprCacheAffinityChange(pParse, regResult, nColumn);
100243       }
100244       break;
100245     }
100246 
100247 #if !defined(SQLITE_OMIT_TRIGGER)
100248     /* Discard the results.  This is used for SELECT statements inside
100249     ** the body of a TRIGGER.  The purpose of such selects is to call
100250     ** user-defined functions that have side effects.  We do not care
100251     ** about the actual results of the select.
100252     */
100253     default: {
100254       assert( eDest==SRT_Discard );
100255       break;
100256     }
100257 #endif
100258   }
100259 
100260   /* Jump to the end of the loop if the LIMIT is reached.  Except, if
100261   ** there is a sorter, in which case the sorter has already limited
100262   ** the output for us.
100263   */
100264   if( pOrderBy==0 && p->iLimit ){
100265     sqlite3VdbeAddOp3(v, OP_IfZero, p->iLimit, iBreak, -1);
100266   }
100267 }
100268 
100269 /*
100270 ** Allocate a KeyInfo object sufficient for an index of N key columns and
100271 ** X extra columns.
100272 */
100273 SQLITE_PRIVATE KeyInfo *sqlite3KeyInfoAlloc(sqlite3 *db, int N, int X){
100274   KeyInfo *p = sqlite3DbMallocZero(0, 
100275                    sizeof(KeyInfo) + (N+X)*(sizeof(CollSeq*)+1));
100276   if( p ){
100277     p->aSortOrder = (u8*)&p->aColl[N+X];
100278     p->nField = (u16)N;
100279     p->nXField = (u16)X;
100280     p->enc = ENC(db);
100281     p->db = db;
100282     p->nRef = 1;
100283   }else{
100284     db->mallocFailed = 1;
100285   }
100286   return p;
100287 }
100288 
100289 /*
100290 ** Deallocate a KeyInfo object
100291 */
100292 SQLITE_PRIVATE void sqlite3KeyInfoUnref(KeyInfo *p){
100293   if( p ){
100294     assert( p->nRef>0 );
100295     p->nRef--;
100296     if( p->nRef==0 ) sqlite3DbFree(0, p);
100297   }
100298 }
100299 
100300 /*
100301 ** Make a new pointer to a KeyInfo object
100302 */
100303 SQLITE_PRIVATE KeyInfo *sqlite3KeyInfoRef(KeyInfo *p){
100304   if( p ){
100305     assert( p->nRef>0 );
100306     p->nRef++;
100307   }
100308   return p;
100309 }
100310 
100311 #ifdef SQLITE_DEBUG
100312 /*
100313 ** Return TRUE if a KeyInfo object can be change.  The KeyInfo object
100314 ** can only be changed if this is just a single reference to the object.
100315 **
100316 ** This routine is used only inside of assert() statements.
100317 */
100318 SQLITE_PRIVATE int sqlite3KeyInfoIsWriteable(KeyInfo *p){ return p->nRef==1; }
100319 #endif /* SQLITE_DEBUG */
100320 
100321 /*
100322 ** Given an expression list, generate a KeyInfo structure that records
100323 ** the collating sequence for each expression in that expression list.
100324 **
100325 ** If the ExprList is an ORDER BY or GROUP BY clause then the resulting
100326 ** KeyInfo structure is appropriate for initializing a virtual index to
100327 ** implement that clause.  If the ExprList is the result set of a SELECT
100328 ** then the KeyInfo structure is appropriate for initializing a virtual
100329 ** index to implement a DISTINCT test.
100330 **
100331 ** Space to hold the KeyInfo structure is obtain from malloc.  The calling
100332 ** function is responsible for seeing that this structure is eventually
100333 ** freed.
100334 */
100335 static KeyInfo *keyInfoFromExprList(Parse *pParse, ExprList *pList){
100336   int nExpr;
100337   KeyInfo *pInfo;
100338   struct ExprList_item *pItem;
100339   sqlite3 *db = pParse->db;
100340   int i;
100341 
100342   nExpr = pList->nExpr;
100343   pInfo = sqlite3KeyInfoAlloc(db, nExpr, 1);
100344   if( pInfo ){
100345     assert( sqlite3KeyInfoIsWriteable(pInfo) );
100346     for(i=0, pItem=pList->a; i<nExpr; i++, pItem++){
100347       CollSeq *pColl;
100348       pColl = sqlite3ExprCollSeq(pParse, pItem->pExpr);
100349       if( !pColl ) pColl = db->pDfltColl;
100350       pInfo->aColl[i] = pColl;
100351       pInfo->aSortOrder[i] = pItem->sortOrder;
100352     }
100353   }
100354   return pInfo;
100355 }
100356 
100357 #ifndef SQLITE_OMIT_COMPOUND_SELECT
100358 /*
100359 ** Name of the connection operator, used for error messages.
100360 */
100361 static const char *selectOpName(int id){
100362   char *z;
100363   switch( id ){
100364     case TK_ALL:       z = "UNION ALL";   break;
100365     case TK_INTERSECT: z = "INTERSECT";   break;
100366     case TK_EXCEPT:    z = "EXCEPT";      break;
100367     default:           z = "UNION";       break;
100368   }
100369   return z;
100370 }
100371 #endif /* SQLITE_OMIT_COMPOUND_SELECT */
100372 
100373 #ifndef SQLITE_OMIT_EXPLAIN
100374 /*
100375 ** Unless an "EXPLAIN QUERY PLAN" command is being processed, this function
100376 ** is a no-op. Otherwise, it adds a single row of output to the EQP result,
100377 ** where the caption is of the form:
100378 **
100379 **   "USE TEMP B-TREE FOR xxx"
100380 **
100381 ** where xxx is one of "DISTINCT", "ORDER BY" or "GROUP BY". Exactly which
100382 ** is determined by the zUsage argument.
100383 */
100384 static void explainTempTable(Parse *pParse, const char *zUsage){
100385   if( pParse->explain==2 ){
100386     Vdbe *v = pParse->pVdbe;
100387     char *zMsg = sqlite3MPrintf(pParse->db, "USE TEMP B-TREE FOR %s", zUsage);
100388     sqlite3VdbeAddOp4(v, OP_Explain, pParse->iSelectId, 0, 0, zMsg, P4_DYNAMIC);
100389   }
100390 }
100391 
100392 /*
100393 ** Assign expression b to lvalue a. A second, no-op, version of this macro
100394 ** is provided when SQLITE_OMIT_EXPLAIN is defined. This allows the code
100395 ** in sqlite3Select() to assign values to structure member variables that
100396 ** only exist if SQLITE_OMIT_EXPLAIN is not defined without polluting the
100397 ** code with #ifndef directives.
100398 */
100399 # define explainSetInteger(a, b) a = b
100400 
100401 #else
100402 /* No-op versions of the explainXXX() functions and macros. */
100403 # define explainTempTable(y,z)
100404 # define explainSetInteger(y,z)
100405 #endif
100406 
100407 #if !defined(SQLITE_OMIT_EXPLAIN) && !defined(SQLITE_OMIT_COMPOUND_SELECT)
100408 /*
100409 ** Unless an "EXPLAIN QUERY PLAN" command is being processed, this function
100410 ** is a no-op. Otherwise, it adds a single row of output to the EQP result,
100411 ** where the caption is of one of the two forms:
100412 **
100413 **   "COMPOSITE SUBQUERIES iSub1 and iSub2 (op)"
100414 **   "COMPOSITE SUBQUERIES iSub1 and iSub2 USING TEMP B-TREE (op)"
100415 **
100416 ** where iSub1 and iSub2 are the integers passed as the corresponding
100417 ** function parameters, and op is the text representation of the parameter
100418 ** of the same name. The parameter "op" must be one of TK_UNION, TK_EXCEPT,
100419 ** TK_INTERSECT or TK_ALL. The first form is used if argument bUseTmp is 
100420 ** false, or the second form if it is true.
100421 */
100422 static void explainComposite(
100423   Parse *pParse,                  /* Parse context */
100424   int op,                         /* One of TK_UNION, TK_EXCEPT etc. */
100425   int iSub1,                      /* Subquery id 1 */
100426   int iSub2,                      /* Subquery id 2 */
100427   int bUseTmp                     /* True if a temp table was used */
100428 ){
100429   assert( op==TK_UNION || op==TK_EXCEPT || op==TK_INTERSECT || op==TK_ALL );
100430   if( pParse->explain==2 ){
100431     Vdbe *v = pParse->pVdbe;
100432     char *zMsg = sqlite3MPrintf(
100433         pParse->db, "COMPOUND SUBQUERIES %d AND %d %s(%s)", iSub1, iSub2,
100434         bUseTmp?"USING TEMP B-TREE ":"", selectOpName(op)
100435     );
100436     sqlite3VdbeAddOp4(v, OP_Explain, pParse->iSelectId, 0, 0, zMsg, P4_DYNAMIC);
100437   }
100438 }
100439 #else
100440 /* No-op versions of the explainXXX() functions and macros. */
100441 # define explainComposite(v,w,x,y,z)
100442 #endif
100443 
100444 /*
100445 ** If the inner loop was generated using a non-null pOrderBy argument,
100446 ** then the results were placed in a sorter.  After the loop is terminated
100447 ** we need to run the sorter and output the results.  The following
100448 ** routine generates the code needed to do that.
100449 */
100450 static void generateSortTail(
100451   Parse *pParse,    /* Parsing context */
100452   Select *p,        /* The SELECT statement */
100453   Vdbe *v,          /* Generate code into this VDBE */
100454   int nColumn,      /* Number of columns of data */
100455   SelectDest *pDest /* Write the sorted results here */
100456 ){
100457   int addrBreak = sqlite3VdbeMakeLabel(v);     /* Jump here to exit loop */
100458   int addrContinue = sqlite3VdbeMakeLabel(v);  /* Jump here for next cycle */
100459   int addr;
100460   int iTab;
100461   int pseudoTab = 0;
100462   ExprList *pOrderBy = p->pOrderBy;
100463 
100464   int eDest = pDest->eDest;
100465   int iParm = pDest->iSDParm;
100466 
100467   int regRow;
100468   int regRowid;
100469 
100470   iTab = pOrderBy->iECursor;
100471   regRow = sqlite3GetTempReg(pParse);
100472   if( eDest==SRT_Output || eDest==SRT_Coroutine ){
100473     pseudoTab = pParse->nTab++;
100474     sqlite3VdbeAddOp3(v, OP_OpenPseudo, pseudoTab, regRow, nColumn);
100475     regRowid = 0;
100476   }else{
100477     regRowid = sqlite3GetTempReg(pParse);
100478   }
100479   if( p->selFlags & SF_UseSorter ){
100480     int regSortOut = ++pParse->nMem;
100481     int ptab2 = pParse->nTab++;
100482     sqlite3VdbeAddOp3(v, OP_OpenPseudo, ptab2, regSortOut, pOrderBy->nExpr+2);
100483     addr = 1 + sqlite3VdbeAddOp2(v, OP_SorterSort, iTab, addrBreak);
100484     codeOffset(v, p, addrContinue);
100485     sqlite3VdbeAddOp2(v, OP_SorterData, iTab, regSortOut);
100486     sqlite3VdbeAddOp3(v, OP_Column, ptab2, pOrderBy->nExpr+1, regRow);
100487     sqlite3VdbeChangeP5(v, OPFLAG_CLEARCACHE);
100488   }else{
100489     addr = 1 + sqlite3VdbeAddOp2(v, OP_Sort, iTab, addrBreak);
100490     codeOffset(v, p, addrContinue);
100491     sqlite3VdbeAddOp3(v, OP_Column, iTab, pOrderBy->nExpr+1, regRow);
100492   }
100493   switch( eDest ){
100494     case SRT_Table:
100495     case SRT_EphemTab: {
100496       testcase( eDest==SRT_Table );
100497       testcase( eDest==SRT_EphemTab );
100498       sqlite3VdbeAddOp2(v, OP_NewRowid, iParm, regRowid);
100499       sqlite3VdbeAddOp3(v, OP_Insert, iParm, regRow, regRowid);
100500       sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
100501       break;
100502     }
100503 #ifndef SQLITE_OMIT_SUBQUERY
100504     case SRT_Set: {
100505       assert( nColumn==1 );
100506       sqlite3VdbeAddOp4(v, OP_MakeRecord, regRow, 1, regRowid,
100507                         &pDest->affSdst, 1);
100508       sqlite3ExprCacheAffinityChange(pParse, regRow, 1);
100509       sqlite3VdbeAddOp2(v, OP_IdxInsert, iParm, regRowid);
100510       break;
100511     }
100512     case SRT_Mem: {
100513       assert( nColumn==1 );
100514       sqlite3ExprCodeMove(pParse, regRow, iParm, 1);
100515       /* The LIMIT clause will terminate the loop for us */
100516       break;
100517     }
100518 #endif
100519     default: {
100520       int i;
100521       assert( eDest==SRT_Output || eDest==SRT_Coroutine ); 
100522       testcase( eDest==SRT_Output );
100523       testcase( eDest==SRT_Coroutine );
100524       for(i=0; i<nColumn; i++){
100525         assert( regRow!=pDest->iSdst+i );
100526         sqlite3VdbeAddOp3(v, OP_Column, pseudoTab, i, pDest->iSdst+i);
100527         if( i==0 ){
100528           sqlite3VdbeChangeP5(v, OPFLAG_CLEARCACHE);
100529         }
100530       }
100531       if( eDest==SRT_Output ){
100532         sqlite3VdbeAddOp2(v, OP_ResultRow, pDest->iSdst, nColumn);
100533         sqlite3ExprCacheAffinityChange(pParse, pDest->iSdst, nColumn);
100534       }else{
100535         sqlite3VdbeAddOp1(v, OP_Yield, pDest->iSDParm);
100536       }
100537       break;
100538     }
100539   }
100540   sqlite3ReleaseTempReg(pParse, regRow);
100541   sqlite3ReleaseTempReg(pParse, regRowid);
100542 
100543   /* The bottom of the loop
100544   */
100545   sqlite3VdbeResolveLabel(v, addrContinue);
100546   if( p->selFlags & SF_UseSorter ){
100547     sqlite3VdbeAddOp2(v, OP_SorterNext, iTab, addr);
100548   }else{
100549     sqlite3VdbeAddOp2(v, OP_Next, iTab, addr);
100550   }
100551   sqlite3VdbeResolveLabel(v, addrBreak);
100552   if( eDest==SRT_Output || eDest==SRT_Coroutine ){
100553     sqlite3VdbeAddOp2(v, OP_Close, pseudoTab, 0);
100554   }
100555 }
100556 
100557 /*
100558 ** Return a pointer to a string containing the 'declaration type' of the
100559 ** expression pExpr. The string may be treated as static by the caller.
100560 **
100561 ** Also try to estimate the size of the returned value and return that
100562 ** result in *pEstWidth.
100563 **
100564 ** The declaration type is the exact datatype definition extracted from the
100565 ** original CREATE TABLE statement if the expression is a column. The
100566 ** declaration type for a ROWID field is INTEGER. Exactly when an expression
100567 ** is considered a column can be complex in the presence of subqueries. The
100568 ** result-set expression in all of the following SELECT statements is 
100569 ** considered a column by this function.
100570 **
100571 **   SELECT col FROM tbl;
100572 **   SELECT (SELECT col FROM tbl;
100573 **   SELECT (SELECT col FROM tbl);
100574 **   SELECT abc FROM (SELECT col AS abc FROM tbl);
100575 ** 
100576 ** The declaration type for any expression other than a column is NULL.
100577 **
100578 ** This routine has either 3 or 6 parameters depending on whether or not
100579 ** the SQLITE_ENABLE_COLUMN_METADATA compile-time option is used.
100580 */
100581 #ifdef SQLITE_ENABLE_COLUMN_METADATA
100582 # define columnType(A,B,C,D,E,F) columnTypeImpl(A,B,C,D,E,F)
100583 static const char *columnTypeImpl(
100584   NameContext *pNC, 
100585   Expr *pExpr,
100586   const char **pzOrigDb,
100587   const char **pzOrigTab,
100588   const char **pzOrigCol,
100589   u8 *pEstWidth
100590 ){
100591   char const *zOrigDb = 0;
100592   char const *zOrigTab = 0;
100593   char const *zOrigCol = 0;
100594 #else /* if !defined(SQLITE_ENABLE_COLUMN_METADATA) */
100595 # define columnType(A,B,C,D,E,F) columnTypeImpl(A,B,F)
100596 static const char *columnTypeImpl(
100597   NameContext *pNC, 
100598   Expr *pExpr,
100599   u8 *pEstWidth
100600 ){
100601 #endif /* !defined(SQLITE_ENABLE_COLUMN_METADATA) */
100602   char const *zType = 0;
100603   int j;
100604   u8 estWidth = 1;
100605 
100606   if( NEVER(pExpr==0) || pNC->pSrcList==0 ) return 0;
100607   switch( pExpr->op ){
100608     case TK_AGG_COLUMN:
100609     case TK_COLUMN: {
100610       /* The expression is a column. Locate the table the column is being
100611       ** extracted from in NameContext.pSrcList. This table may be real
100612       ** database table or a subquery.
100613       */
100614       Table *pTab = 0;            /* Table structure column is extracted from */
100615       Select *pS = 0;             /* Select the column is extracted from */
100616       int iCol = pExpr->iColumn;  /* Index of column in pTab */
100617       testcase( pExpr->op==TK_AGG_COLUMN );
100618       testcase( pExpr->op==TK_COLUMN );
100619       while( pNC && !pTab ){
100620         SrcList *pTabList = pNC->pSrcList;
100621         for(j=0;j<pTabList->nSrc && pTabList->a[j].iCursor!=pExpr->iTable;j++);
100622         if( j<pTabList->nSrc ){
100623           pTab = pTabList->a[j].pTab;
100624           pS = pTabList->a[j].pSelect;
100625         }else{
100626           pNC = pNC->pNext;
100627         }
100628       }
100629 
100630       if( pTab==0 ){
100631         /* At one time, code such as "SELECT new.x" within a trigger would
100632         ** cause this condition to run.  Since then, we have restructured how
100633         ** trigger code is generated and so this condition is no longer 
100634         ** possible. However, it can still be true for statements like
100635         ** the following:
100636         **
100637         **   CREATE TABLE t1(col INTEGER);
100638         **   SELECT (SELECT t1.col) FROM FROM t1;
100639         **
100640         ** when columnType() is called on the expression "t1.col" in the 
100641         ** sub-select. In this case, set the column type to NULL, even
100642         ** though it should really be "INTEGER".
100643         **
100644         ** This is not a problem, as the column type of "t1.col" is never
100645         ** used. When columnType() is called on the expression 
100646         ** "(SELECT t1.col)", the correct type is returned (see the TK_SELECT
100647         ** branch below.  */
100648         break;
100649       }
100650 
100651       assert( pTab && pExpr->pTab==pTab );
100652       if( pS ){
100653         /* The "table" is actually a sub-select or a view in the FROM clause
100654         ** of the SELECT statement. Return the declaration type and origin
100655         ** data for the result-set column of the sub-select.
100656         */
100657         if( iCol>=0 && ALWAYS(iCol<pS->pEList->nExpr) ){
100658           /* If iCol is less than zero, then the expression requests the
100659           ** rowid of the sub-select or view. This expression is legal (see 
100660           ** test case misc2.2.2) - it always evaluates to NULL.
100661           */
100662           NameContext sNC;
100663           Expr *p = pS->pEList->a[iCol].pExpr;
100664           sNC.pSrcList = pS->pSrc;
100665           sNC.pNext = pNC;
100666           sNC.pParse = pNC->pParse;
100667           zType = columnType(&sNC, p,&zOrigDb,&zOrigTab,&zOrigCol, &estWidth); 
100668         }
100669       }else if( ALWAYS(pTab->pSchema) ){
100670         /* A real table */
100671         assert( !pS );
100672         if( iCol<0 ) iCol = pTab->iPKey;
100673         assert( iCol==-1 || (iCol>=0 && iCol<pTab->nCol) );
100674 #ifdef SQLITE_ENABLE_COLUMN_METADATA
100675         if( iCol<0 ){
100676           zType = "INTEGER";
100677           zOrigCol = "rowid";
100678         }else{
100679           zType = pTab->aCol[iCol].zType;
100680           zOrigCol = pTab->aCol[iCol].zName;
100681           estWidth = pTab->aCol[iCol].szEst;
100682         }
100683         zOrigTab = pTab->zName;
100684         if( pNC->pParse ){
100685           int iDb = sqlite3SchemaToIndex(pNC->pParse->db, pTab->pSchema);
100686           zOrigDb = pNC->pParse->db->aDb[iDb].zName;
100687         }
100688 #else
100689         if( iCol<0 ){
100690           zType = "INTEGER";
100691         }else{
100692           zType = pTab->aCol[iCol].zType;
100693           estWidth = pTab->aCol[iCol].szEst;
100694         }
100695 #endif
100696       }
100697       break;
100698     }
100699 #ifndef SQLITE_OMIT_SUBQUERY
100700     case TK_SELECT: {
100701       /* The expression is a sub-select. Return the declaration type and
100702       ** origin info for the single column in the result set of the SELECT
100703       ** statement.
100704       */
100705       NameContext sNC;
100706       Select *pS = pExpr->x.pSelect;
100707       Expr *p = pS->pEList->a[0].pExpr;
100708       assert( ExprHasProperty(pExpr, EP_xIsSelect) );
100709       sNC.pSrcList = pS->pSrc;
100710       sNC.pNext = pNC;
100711       sNC.pParse = pNC->pParse;
100712       zType = columnType(&sNC, p, &zOrigDb, &zOrigTab, &zOrigCol, &estWidth); 
100713       break;
100714     }
100715 #endif
100716   }
100717 
100718 #ifdef SQLITE_ENABLE_COLUMN_METADATA  
100719   if( pzOrigDb ){
100720     assert( pzOrigTab && pzOrigCol );
100721     *pzOrigDb = zOrigDb;
100722     *pzOrigTab = zOrigTab;
100723     *pzOrigCol = zOrigCol;
100724   }
100725 #endif
100726   if( pEstWidth ) *pEstWidth = estWidth;
100727   return zType;
100728 }
100729 
100730 /*
100731 ** Generate code that will tell the VDBE the declaration types of columns
100732 ** in the result set.
100733 */
100734 static void generateColumnTypes(
100735   Parse *pParse,      /* Parser context */
100736   SrcList *pTabList,  /* List of tables */
100737   ExprList *pEList    /* Expressions defining the result set */
100738 ){
100739 #ifndef SQLITE_OMIT_DECLTYPE
100740   Vdbe *v = pParse->pVdbe;
100741   int i;
100742   NameContext sNC;
100743   sNC.pSrcList = pTabList;
100744   sNC.pParse = pParse;
100745   for(i=0; i<pEList->nExpr; i++){
100746     Expr *p = pEList->a[i].pExpr;
100747     const char *zType;
100748 #ifdef SQLITE_ENABLE_COLUMN_METADATA
100749     const char *zOrigDb = 0;
100750     const char *zOrigTab = 0;
100751     const char *zOrigCol = 0;
100752     zType = columnType(&sNC, p, &zOrigDb, &zOrigTab, &zOrigCol, 0);
100753 
100754     /* The vdbe must make its own copy of the column-type and other 
100755     ** column specific strings, in case the schema is reset before this
100756     ** virtual machine is deleted.
100757     */
100758     sqlite3VdbeSetColName(v, i, COLNAME_DATABASE, zOrigDb, SQLITE_TRANSIENT);
100759     sqlite3VdbeSetColName(v, i, COLNAME_TABLE, zOrigTab, SQLITE_TRANSIENT);
100760     sqlite3VdbeSetColName(v, i, COLNAME_COLUMN, zOrigCol, SQLITE_TRANSIENT);
100761 #else
100762     zType = columnType(&sNC, p, 0, 0, 0, 0);
100763 #endif
100764     sqlite3VdbeSetColName(v, i, COLNAME_DECLTYPE, zType, SQLITE_TRANSIENT);
100765   }
100766 #endif /* !defined(SQLITE_OMIT_DECLTYPE) */
100767 }
100768 
100769 /*
100770 ** Generate code that will tell the VDBE the names of columns
100771 ** in the result set.  This information is used to provide the
100772 ** azCol[] values in the callback.
100773 */
100774 static void generateColumnNames(
100775   Parse *pParse,      /* Parser context */
100776   SrcList *pTabList,  /* List of tables */
100777   ExprList *pEList    /* Expressions defining the result set */
100778 ){
100779   Vdbe *v = pParse->pVdbe;
100780   int i, j;
100781   sqlite3 *db = pParse->db;
100782   int fullNames, shortNames;
100783 
100784 #ifndef SQLITE_OMIT_EXPLAIN
100785   /* If this is an EXPLAIN, skip this step */
100786   if( pParse->explain ){
100787     return;
100788   }
100789 #endif
100790 
100791   if( pParse->colNamesSet || NEVER(v==0) || db->mallocFailed ) return;
100792   pParse->colNamesSet = 1;
100793   fullNames = (db->flags & SQLITE_FullColNames)!=0;
100794   shortNames = (db->flags & SQLITE_ShortColNames)!=0;
100795   sqlite3VdbeSetNumCols(v, pEList->nExpr);
100796   for(i=0; i<pEList->nExpr; i++){
100797     Expr *p;
100798     p = pEList->a[i].pExpr;
100799     if( NEVER(p==0) ) continue;
100800     if( pEList->a[i].zName ){
100801       char *zName = pEList->a[i].zName;
100802       sqlite3VdbeSetColName(v, i, COLNAME_NAME, zName, SQLITE_TRANSIENT);
100803     }else if( (p->op==TK_COLUMN || p->op==TK_AGG_COLUMN) && pTabList ){
100804       Table *pTab;
100805       char *zCol;
100806       int iCol = p->iColumn;
100807       for(j=0; ALWAYS(j<pTabList->nSrc); j++){
100808         if( pTabList->a[j].iCursor==p->iTable ) break;
100809       }
100810       assert( j<pTabList->nSrc );
100811       pTab = pTabList->a[j].pTab;
100812       if( iCol<0 ) iCol = pTab->iPKey;
100813       assert( iCol==-1 || (iCol>=0 && iCol<pTab->nCol) );
100814       if( iCol<0 ){
100815         zCol = "rowid";
100816       }else{
100817         zCol = pTab->aCol[iCol].zName;
100818       }
100819       if( !shortNames && !fullNames ){
100820         sqlite3VdbeSetColName(v, i, COLNAME_NAME, 
100821             sqlite3DbStrDup(db, pEList->a[i].zSpan), SQLITE_DYNAMIC);
100822       }else if( fullNames ){
100823         char *zName = 0;
100824         zName = sqlite3MPrintf(db, "%s.%s", pTab->zName, zCol);
100825         sqlite3VdbeSetColName(v, i, COLNAME_NAME, zName, SQLITE_DYNAMIC);
100826       }else{
100827         sqlite3VdbeSetColName(v, i, COLNAME_NAME, zCol, SQLITE_TRANSIENT);
100828       }
100829     }else{
100830       sqlite3VdbeSetColName(v, i, COLNAME_NAME, 
100831           sqlite3DbStrDup(db, pEList->a[i].zSpan), SQLITE_DYNAMIC);
100832     }
100833   }
100834   generateColumnTypes(pParse, pTabList, pEList);
100835 }
100836 
100837 /*
100838 ** Given a an expression list (which is really the list of expressions
100839 ** that form the result set of a SELECT statement) compute appropriate
100840 ** column names for a table that would hold the expression list.
100841 **
100842 ** All column names will be unique.
100843 **
100844 ** Only the column names are computed.  Column.zType, Column.zColl,
100845 ** and other fields of Column are zeroed.
100846 **
100847 ** Return SQLITE_OK on success.  If a memory allocation error occurs,
100848 ** store NULL in *paCol and 0 in *pnCol and return SQLITE_NOMEM.
100849 */
100850 static int selectColumnsFromExprList(
100851   Parse *pParse,          /* Parsing context */
100852   ExprList *pEList,       /* Expr list from which to derive column names */
100853   i16 *pnCol,             /* Write the number of columns here */
100854   Column **paCol          /* Write the new column list here */
100855 ){
100856   sqlite3 *db = pParse->db;   /* Database connection */
100857   int i, j;                   /* Loop counters */
100858   int cnt;                    /* Index added to make the name unique */
100859   Column *aCol, *pCol;        /* For looping over result columns */
100860   int nCol;                   /* Number of columns in the result set */
100861   Expr *p;                    /* Expression for a single result column */
100862   char *zName;                /* Column name */
100863   int nName;                  /* Size of name in zName[] */
100864 
100865   if( pEList ){
100866     nCol = pEList->nExpr;
100867     aCol = sqlite3DbMallocZero(db, sizeof(aCol[0])*nCol);
100868     testcase( aCol==0 );
100869   }else{
100870     nCol = 0;
100871     aCol = 0;
100872   }
100873   *pnCol = nCol;
100874   *paCol = aCol;
100875 
100876   for(i=0, pCol=aCol; i<nCol; i++, pCol++){
100877     /* Get an appropriate name for the column
100878     */
100879     p = sqlite3ExprSkipCollate(pEList->a[i].pExpr);
100880     if( (zName = pEList->a[i].zName)!=0 ){
100881       /* If the column contains an "AS <name>" phrase, use <name> as the name */
100882       zName = sqlite3DbStrDup(db, zName);
100883     }else{
100884       Expr *pColExpr = p;  /* The expression that is the result column name */
100885       Table *pTab;         /* Table associated with this expression */
100886       while( pColExpr->op==TK_DOT ){
100887         pColExpr = pColExpr->pRight;
100888         assert( pColExpr!=0 );
100889       }
100890       if( pColExpr->op==TK_COLUMN && ALWAYS(pColExpr->pTab!=0) ){
100891         /* For columns use the column name name */
100892         int iCol = pColExpr->iColumn;
100893         pTab = pColExpr->pTab;
100894         if( iCol<0 ) iCol = pTab->iPKey;
100895         zName = sqlite3MPrintf(db, "%s",
100896                  iCol>=0 ? pTab->aCol[iCol].zName : "rowid");
100897       }else if( pColExpr->op==TK_ID ){
100898         assert( !ExprHasProperty(pColExpr, EP_IntValue) );
100899         zName = sqlite3MPrintf(db, "%s", pColExpr->u.zToken);
100900       }else{
100901         /* Use the original text of the column expression as its name */
100902         zName = sqlite3MPrintf(db, "%s", pEList->a[i].zSpan);
100903       }
100904     }
100905     if( db->mallocFailed ){
100906       sqlite3DbFree(db, zName);
100907       break;
100908     }
100909 
100910     /* Make sure the column name is unique.  If the name is not unique,
100911     ** append a integer to the name so that it becomes unique.
100912     */
100913     nName = sqlite3Strlen30(zName);
100914     for(j=cnt=0; j<i; j++){
100915       if( sqlite3StrICmp(aCol[j].zName, zName)==0 ){
100916         char *zNewName;
100917         int k;
100918         for(k=nName-1; k>1 && sqlite3Isdigit(zName[k]); k--){}
100919         if( zName[k]==':' ) nName = k;
100920         zName[nName] = 0;
100921         zNewName = sqlite3MPrintf(db, "%s:%d", zName, ++cnt);
100922         sqlite3DbFree(db, zName);
100923         zName = zNewName;
100924         j = -1;
100925         if( zName==0 ) break;
100926       }
100927     }
100928     pCol->zName = zName;
100929   }
100930   if( db->mallocFailed ){
100931     for(j=0; j<i; j++){
100932       sqlite3DbFree(db, aCol[j].zName);
100933     }
100934     sqlite3DbFree(db, aCol);
100935     *paCol = 0;
100936     *pnCol = 0;
100937     return SQLITE_NOMEM;
100938   }
100939   return SQLITE_OK;
100940 }
100941 
100942 /*
100943 ** Add type and collation information to a column list based on
100944 ** a SELECT statement.
100945 ** 
100946 ** The column list presumably came from selectColumnNamesFromExprList().
100947 ** The column list has only names, not types or collations.  This
100948 ** routine goes through and adds the types and collations.
100949 **
100950 ** This routine requires that all identifiers in the SELECT
100951 ** statement be resolved.
100952 */
100953 static void selectAddColumnTypeAndCollation(
100954   Parse *pParse,        /* Parsing contexts */
100955   Table *pTab,          /* Add column type information to this table */
100956   Select *pSelect       /* SELECT used to determine types and collations */
100957 ){
100958   sqlite3 *db = pParse->db;
100959   NameContext sNC;
100960   Column *pCol;
100961   CollSeq *pColl;
100962   int i;
100963   Expr *p;
100964   struct ExprList_item *a;
100965   u64 szAll = 0;
100966 
100967   assert( pSelect!=0 );
100968   assert( (pSelect->selFlags & SF_Resolved)!=0 );
100969   assert( pTab->nCol==pSelect->pEList->nExpr || db->mallocFailed );
100970   if( db->mallocFailed ) return;
100971   memset(&sNC, 0, sizeof(sNC));
100972   sNC.pSrcList = pSelect->pSrc;
100973   a = pSelect->pEList->a;
100974   for(i=0, pCol=pTab->aCol; i<pTab->nCol; i++, pCol++){
100975     p = a[i].pExpr;
100976     pCol->zType = sqlite3DbStrDup(db, columnType(&sNC, p,0,0,0, &pCol->szEst));
100977     szAll += pCol->szEst;
100978     pCol->affinity = sqlite3ExprAffinity(p);
100979     if( pCol->affinity==0 ) pCol->affinity = SQLITE_AFF_NONE;
100980     pColl = sqlite3ExprCollSeq(pParse, p);
100981     if( pColl ){
100982       pCol->zColl = sqlite3DbStrDup(db, pColl->zName);
100983     }
100984   }
100985   pTab->szTabRow = sqlite3LogEst(szAll*4);
100986 }
100987 
100988 /*
100989 ** Given a SELECT statement, generate a Table structure that describes
100990 ** the result set of that SELECT.
100991 */
100992 SQLITE_PRIVATE Table *sqlite3ResultSetOfSelect(Parse *pParse, Select *pSelect){
100993   Table *pTab;
100994   sqlite3 *db = pParse->db;
100995   int savedFlags;
100996 
100997   savedFlags = db->flags;
100998   db->flags &= ~SQLITE_FullColNames;
100999   db->flags |= SQLITE_ShortColNames;
101000   sqlite3SelectPrep(pParse, pSelect, 0);
101001   if( pParse->nErr ) return 0;
101002   while( pSelect->pPrior ) pSelect = pSelect->pPrior;
101003   db->flags = savedFlags;
101004   pTab = sqlite3DbMallocZero(db, sizeof(Table) );
101005   if( pTab==0 ){
101006     return 0;
101007   }
101008   /* The sqlite3ResultSetOfSelect() is only used n contexts where lookaside
101009   ** is disabled */
101010   assert( db->lookaside.bEnabled==0 );
101011   pTab->nRef = 1;
101012   pTab->zName = 0;
101013   pTab->nRowEst = 1048576;
101014   selectColumnsFromExprList(pParse, pSelect->pEList, &pTab->nCol, &pTab->aCol);
101015   selectAddColumnTypeAndCollation(pParse, pTab, pSelect);
101016   pTab->iPKey = -1;
101017   if( db->mallocFailed ){
101018     sqlite3DeleteTable(db, pTab);
101019     return 0;
101020   }
101021   return pTab;
101022 }
101023 
101024 /*
101025 ** Get a VDBE for the given parser context.  Create a new one if necessary.
101026 ** If an error occurs, return NULL and leave a message in pParse.
101027 */
101028 SQLITE_PRIVATE Vdbe *sqlite3GetVdbe(Parse *pParse){
101029   Vdbe *v = pParse->pVdbe;
101030   if( v==0 ){
101031     v = pParse->pVdbe = sqlite3VdbeCreate(pParse->db);
101032 #ifndef SQLITE_OMIT_TRACE
101033     if( v ){
101034       sqlite3VdbeAddOp0(v, OP_Trace);
101035     }
101036 #endif
101037   }
101038   return v;
101039 }
101040 
101041 
101042 /*
101043 ** Compute the iLimit and iOffset fields of the SELECT based on the
101044 ** pLimit and pOffset expressions.  pLimit and pOffset hold the expressions
101045 ** that appear in the original SQL statement after the LIMIT and OFFSET
101046 ** keywords.  Or NULL if those keywords are omitted. iLimit and iOffset 
101047 ** are the integer memory register numbers for counters used to compute 
101048 ** the limit and offset.  If there is no limit and/or offset, then 
101049 ** iLimit and iOffset are negative.
101050 **
101051 ** This routine changes the values of iLimit and iOffset only if
101052 ** a limit or offset is defined by pLimit and pOffset.  iLimit and
101053 ** iOffset should have been preset to appropriate default values
101054 ** (usually but not always -1) prior to calling this routine.
101055 ** Only if pLimit!=0 or pOffset!=0 do the limit registers get
101056 ** redefined.  The UNION ALL operator uses this property to force
101057 ** the reuse of the same limit and offset registers across multiple
101058 ** SELECT statements.
101059 */
101060 static void computeLimitRegisters(Parse *pParse, Select *p, int iBreak){
101061   Vdbe *v = 0;
101062   int iLimit = 0;
101063   int iOffset;
101064   int addr1, n;
101065   if( p->iLimit ) return;
101066 
101067   /* 
101068   ** "LIMIT -1" always shows all rows.  There is some
101069   ** controversy about what the correct behavior should be.
101070   ** The current implementation interprets "LIMIT 0" to mean
101071   ** no rows.
101072   */
101073   sqlite3ExprCacheClear(pParse);
101074   assert( p->pOffset==0 || p->pLimit!=0 );
101075   if( p->pLimit ){
101076     p->iLimit = iLimit = ++pParse->nMem;
101077     v = sqlite3GetVdbe(pParse);
101078     if( NEVER(v==0) ) return;  /* VDBE should have already been allocated */
101079     if( sqlite3ExprIsInteger(p->pLimit, &n) ){
101080       sqlite3VdbeAddOp2(v, OP_Integer, n, iLimit);
101081       VdbeComment((v, "LIMIT counter"));
101082       if( n==0 ){
101083         sqlite3VdbeAddOp2(v, OP_Goto, 0, iBreak);
101084       }else if( n>=0 && p->nSelectRow>(u64)n ){
101085         p->nSelectRow = n;
101086       }
101087     }else{
101088       sqlite3ExprCode(pParse, p->pLimit, iLimit);
101089       sqlite3VdbeAddOp1(v, OP_MustBeInt, iLimit);
101090       VdbeComment((v, "LIMIT counter"));
101091       sqlite3VdbeAddOp2(v, OP_IfZero, iLimit, iBreak);
101092     }
101093     if( p->pOffset ){
101094       p->iOffset = iOffset = ++pParse->nMem;
101095       pParse->nMem++;   /* Allocate an extra register for limit+offset */
101096       sqlite3ExprCode(pParse, p->pOffset, iOffset);
101097       sqlite3VdbeAddOp1(v, OP_MustBeInt, iOffset);
101098       VdbeComment((v, "OFFSET counter"));
101099       addr1 = sqlite3VdbeAddOp1(v, OP_IfPos, iOffset);
101100       sqlite3VdbeAddOp2(v, OP_Integer, 0, iOffset);
101101       sqlite3VdbeJumpHere(v, addr1);
101102       sqlite3VdbeAddOp3(v, OP_Add, iLimit, iOffset, iOffset+1);
101103       VdbeComment((v, "LIMIT+OFFSET"));
101104       addr1 = sqlite3VdbeAddOp1(v, OP_IfPos, iLimit);
101105       sqlite3VdbeAddOp2(v, OP_Integer, -1, iOffset+1);
101106       sqlite3VdbeJumpHere(v, addr1);
101107     }
101108   }
101109 }
101110 
101111 #ifndef SQLITE_OMIT_COMPOUND_SELECT
101112 /*
101113 ** Return the appropriate collating sequence for the iCol-th column of
101114 ** the result set for the compound-select statement "p".  Return NULL if
101115 ** the column has no default collating sequence.
101116 **
101117 ** The collating sequence for the compound select is taken from the
101118 ** left-most term of the select that has a collating sequence.
101119 */
101120 static CollSeq *multiSelectCollSeq(Parse *pParse, Select *p, int iCol){
101121   CollSeq *pRet;
101122   if( p->pPrior ){
101123     pRet = multiSelectCollSeq(pParse, p->pPrior, iCol);
101124   }else{
101125     pRet = 0;
101126   }
101127   assert( iCol>=0 );
101128   if( pRet==0 && iCol<p->pEList->nExpr ){
101129     pRet = sqlite3ExprCollSeq(pParse, p->pEList->a[iCol].pExpr);
101130   }
101131   return pRet;
101132 }
101133 #endif /* SQLITE_OMIT_COMPOUND_SELECT */
101134 
101135 /* Forward reference */
101136 static int multiSelectOrderBy(
101137   Parse *pParse,        /* Parsing context */
101138   Select *p,            /* The right-most of SELECTs to be coded */
101139   SelectDest *pDest     /* What to do with query results */
101140 );
101141 
101142 
101143 #ifndef SQLITE_OMIT_COMPOUND_SELECT
101144 /*
101145 ** This routine is called to process a compound query form from
101146 ** two or more separate queries using UNION, UNION ALL, EXCEPT, or
101147 ** INTERSECT
101148 **
101149 ** "p" points to the right-most of the two queries.  the query on the
101150 ** left is p->pPrior.  The left query could also be a compound query
101151 ** in which case this routine will be called recursively. 
101152 **
101153 ** The results of the total query are to be written into a destination
101154 ** of type eDest with parameter iParm.
101155 **
101156 ** Example 1:  Consider a three-way compound SQL statement.
101157 **
101158 **     SELECT a FROM t1 UNION SELECT b FROM t2 UNION SELECT c FROM t3
101159 **
101160 ** This statement is parsed up as follows:
101161 **
101162 **     SELECT c FROM t3
101163 **      |
101164 **      `----->  SELECT b FROM t2
101165 **                |
101166 **                `------>  SELECT a FROM t1
101167 **
101168 ** The arrows in the diagram above represent the Select.pPrior pointer.
101169 ** So if this routine is called with p equal to the t3 query, then
101170 ** pPrior will be the t2 query.  p->op will be TK_UNION in this case.
101171 **
101172 ** Notice that because of the way SQLite parses compound SELECTs, the
101173 ** individual selects always group from left to right.
101174 */
101175 static int multiSelect(
101176   Parse *pParse,        /* Parsing context */
101177   Select *p,            /* The right-most of SELECTs to be coded */
101178   SelectDest *pDest     /* What to do with query results */
101179 ){
101180   int rc = SQLITE_OK;   /* Success code from a subroutine */
101181   Select *pPrior;       /* Another SELECT immediately to our left */
101182   Vdbe *v;              /* Generate code to this VDBE */
101183   SelectDest dest;      /* Alternative data destination */
101184   Select *pDelete = 0;  /* Chain of simple selects to delete */
101185   sqlite3 *db;          /* Database connection */
101186 #ifndef SQLITE_OMIT_EXPLAIN
101187   int iSub1;            /* EQP id of left-hand query */
101188   int iSub2;            /* EQP id of right-hand query */
101189 #endif
101190 
101191   /* Make sure there is no ORDER BY or LIMIT clause on prior SELECTs.  Only
101192   ** the last (right-most) SELECT in the series may have an ORDER BY or LIMIT.
101193   */
101194   assert( p && p->pPrior );  /* Calling function guarantees this much */
101195   db = pParse->db;
101196   pPrior = p->pPrior;
101197   assert( pPrior->pRightmost!=pPrior );
101198   assert( pPrior->pRightmost==p->pRightmost );
101199   dest = *pDest;
101200   if( pPrior->pOrderBy ){
101201     sqlite3ErrorMsg(pParse,"ORDER BY clause should come after %s not before",
101202       selectOpName(p->op));
101203     rc = 1;
101204     goto multi_select_end;
101205   }
101206   if( pPrior->pLimit ){
101207     sqlite3ErrorMsg(pParse,"LIMIT clause should come after %s not before",
101208       selectOpName(p->op));
101209     rc = 1;
101210     goto multi_select_end;
101211   }
101212 
101213   v = sqlite3GetVdbe(pParse);
101214   assert( v!=0 );  /* The VDBE already created by calling function */
101215 
101216   /* Create the destination temporary table if necessary
101217   */
101218   if( dest.eDest==SRT_EphemTab ){
101219     assert( p->pEList );
101220     sqlite3VdbeAddOp2(v, OP_OpenEphemeral, dest.iSDParm, p->pEList->nExpr);
101221     sqlite3VdbeChangeP5(v, BTREE_UNORDERED);
101222     dest.eDest = SRT_Table;
101223   }
101224 
101225   /* Make sure all SELECTs in the statement have the same number of elements
101226   ** in their result sets.
101227   */
101228   assert( p->pEList && pPrior->pEList );
101229   if( p->pEList->nExpr!=pPrior->pEList->nExpr ){
101230     if( p->selFlags & SF_Values ){
101231       sqlite3ErrorMsg(pParse, "all VALUES must have the same number of terms");
101232     }else{
101233       sqlite3ErrorMsg(pParse, "SELECTs to the left and right of %s"
101234         " do not have the same number of result columns", selectOpName(p->op));
101235     }
101236     rc = 1;
101237     goto multi_select_end;
101238   }
101239 
101240   /* Compound SELECTs that have an ORDER BY clause are handled separately.
101241   */
101242   if( p->pOrderBy ){
101243     return multiSelectOrderBy(pParse, p, pDest);
101244   }
101245 
101246   /* Generate code for the left and right SELECT statements.
101247   */
101248   switch( p->op ){
101249     case TK_ALL: {
101250       int addr = 0;
101251       int nLimit;
101252       assert( !pPrior->pLimit );
101253       pPrior->iLimit = p->iLimit;
101254       pPrior->iOffset = p->iOffset;
101255       pPrior->pLimit = p->pLimit;
101256       pPrior->pOffset = p->pOffset;
101257       explainSetInteger(iSub1, pParse->iNextSelectId);
101258       rc = sqlite3Select(pParse, pPrior, &dest);
101259       p->pLimit = 0;
101260       p->pOffset = 0;
101261       if( rc ){
101262         goto multi_select_end;
101263       }
101264       p->pPrior = 0;
101265       p->iLimit = pPrior->iLimit;
101266       p->iOffset = pPrior->iOffset;
101267       if( p->iLimit ){
101268         addr = sqlite3VdbeAddOp1(v, OP_IfZero, p->iLimit);
101269         VdbeComment((v, "Jump ahead if LIMIT reached"));
101270       }
101271       explainSetInteger(iSub2, pParse->iNextSelectId);
101272       rc = sqlite3Select(pParse, p, &dest);
101273       testcase( rc!=SQLITE_OK );
101274       pDelete = p->pPrior;
101275       p->pPrior = pPrior;
101276       p->nSelectRow += pPrior->nSelectRow;
101277       if( pPrior->pLimit
101278        && sqlite3ExprIsInteger(pPrior->pLimit, &nLimit)
101279        && nLimit>0 && p->nSelectRow > (u64)nLimit 
101280       ){
101281         p->nSelectRow = nLimit;
101282       }
101283       if( addr ){
101284         sqlite3VdbeJumpHere(v, addr);
101285       }
101286       break;
101287     }
101288     case TK_EXCEPT:
101289     case TK_UNION: {
101290       int unionTab;    /* Cursor number of the temporary table holding result */
101291       u8 op = 0;       /* One of the SRT_ operations to apply to self */
101292       int priorOp;     /* The SRT_ operation to apply to prior selects */
101293       Expr *pLimit, *pOffset; /* Saved values of p->nLimit and p->nOffset */
101294       int addr;
101295       SelectDest uniondest;
101296 
101297       testcase( p->op==TK_EXCEPT );
101298       testcase( p->op==TK_UNION );
101299       priorOp = SRT_Union;
101300       if( dest.eDest==priorOp && ALWAYS(!p->pLimit &&!p->pOffset) ){
101301         /* We can reuse a temporary table generated by a SELECT to our
101302         ** right.
101303         */
101304         assert( p->pRightmost!=p );  /* Can only happen for leftward elements
101305                                      ** of a 3-way or more compound */
101306         assert( p->pLimit==0 );      /* Not allowed on leftward elements */
101307         assert( p->pOffset==0 );     /* Not allowed on leftward elements */
101308         unionTab = dest.iSDParm;
101309       }else{
101310         /* We will need to create our own temporary table to hold the
101311         ** intermediate results.
101312         */
101313         unionTab = pParse->nTab++;
101314         assert( p->pOrderBy==0 );
101315         addr = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, unionTab, 0);
101316         assert( p->addrOpenEphm[0] == -1 );
101317         p->addrOpenEphm[0] = addr;
101318         p->pRightmost->selFlags |= SF_UsesEphemeral;
101319         assert( p->pEList );
101320       }
101321 
101322       /* Code the SELECT statements to our left
101323       */
101324       assert( !pPrior->pOrderBy );
101325       sqlite3SelectDestInit(&uniondest, priorOp, unionTab);
101326       explainSetInteger(iSub1, pParse->iNextSelectId);
101327       rc = sqlite3Select(pParse, pPrior, &uniondest);
101328       if( rc ){
101329         goto multi_select_end;
101330       }
101331 
101332       /* Code the current SELECT statement
101333       */
101334       if( p->op==TK_EXCEPT ){
101335         op = SRT_Except;
101336       }else{
101337         assert( p->op==TK_UNION );
101338         op = SRT_Union;
101339       }
101340       p->pPrior = 0;
101341       pLimit = p->pLimit;
101342       p->pLimit = 0;
101343       pOffset = p->pOffset;
101344       p->pOffset = 0;
101345       uniondest.eDest = op;
101346       explainSetInteger(iSub2, pParse->iNextSelectId);
101347       rc = sqlite3Select(pParse, p, &uniondest);
101348       testcase( rc!=SQLITE_OK );
101349       /* Query flattening in sqlite3Select() might refill p->pOrderBy.
101350       ** Be sure to delete p->pOrderBy, therefore, to avoid a memory leak. */
101351       sqlite3ExprListDelete(db, p->pOrderBy);
101352       pDelete = p->pPrior;
101353       p->pPrior = pPrior;
101354       p->pOrderBy = 0;
101355       if( p->op==TK_UNION ) p->nSelectRow += pPrior->nSelectRow;
101356       sqlite3ExprDelete(db, p->pLimit);
101357       p->pLimit = pLimit;
101358       p->pOffset = pOffset;
101359       p->iLimit = 0;
101360       p->iOffset = 0;
101361 
101362       /* Convert the data in the temporary table into whatever form
101363       ** it is that we currently need.
101364       */
101365       assert( unionTab==dest.iSDParm || dest.eDest!=priorOp );
101366       if( dest.eDest!=priorOp ){
101367         int iCont, iBreak, iStart;
101368         assert( p->pEList );
101369         if( dest.eDest==SRT_Output ){
101370           Select *pFirst = p;
101371           while( pFirst->pPrior ) pFirst = pFirst->pPrior;
101372           generateColumnNames(pParse, 0, pFirst->pEList);
101373         }
101374         iBreak = sqlite3VdbeMakeLabel(v);
101375         iCont = sqlite3VdbeMakeLabel(v);
101376         computeLimitRegisters(pParse, p, iBreak);
101377         sqlite3VdbeAddOp2(v, OP_Rewind, unionTab, iBreak);
101378         iStart = sqlite3VdbeCurrentAddr(v);
101379         selectInnerLoop(pParse, p, p->pEList, unionTab, p->pEList->nExpr,
101380                         0, 0, &dest, iCont, iBreak);
101381         sqlite3VdbeResolveLabel(v, iCont);
101382         sqlite3VdbeAddOp2(v, OP_Next, unionTab, iStart);
101383         sqlite3VdbeResolveLabel(v, iBreak);
101384         sqlite3VdbeAddOp2(v, OP_Close, unionTab, 0);
101385       }
101386       break;
101387     }
101388     default: assert( p->op==TK_INTERSECT ); {
101389       int tab1, tab2;
101390       int iCont, iBreak, iStart;
101391       Expr *pLimit, *pOffset;
101392       int addr;
101393       SelectDest intersectdest;
101394       int r1;
101395 
101396       /* INTERSECT is different from the others since it requires
101397       ** two temporary tables.  Hence it has its own case.  Begin
101398       ** by allocating the tables we will need.
101399       */
101400       tab1 = pParse->nTab++;
101401       tab2 = pParse->nTab++;
101402       assert( p->pOrderBy==0 );
101403 
101404       addr = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, tab1, 0);
101405       assert( p->addrOpenEphm[0] == -1 );
101406       p->addrOpenEphm[0] = addr;
101407       p->pRightmost->selFlags |= SF_UsesEphemeral;
101408       assert( p->pEList );
101409 
101410       /* Code the SELECTs to our left into temporary table "tab1".
101411       */
101412       sqlite3SelectDestInit(&intersectdest, SRT_Union, tab1);
101413       explainSetInteger(iSub1, pParse->iNextSelectId);
101414       rc = sqlite3Select(pParse, pPrior, &intersectdest);
101415       if( rc ){
101416         goto multi_select_end;
101417       }
101418 
101419       /* Code the current SELECT into temporary table "tab2"
101420       */
101421       addr = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, tab2, 0);
101422       assert( p->addrOpenEphm[1] == -1 );
101423       p->addrOpenEphm[1] = addr;
101424       p->pPrior = 0;
101425       pLimit = p->pLimit;
101426       p->pLimit = 0;
101427       pOffset = p->pOffset;
101428       p->pOffset = 0;
101429       intersectdest.iSDParm = tab2;
101430       explainSetInteger(iSub2, pParse->iNextSelectId);
101431       rc = sqlite3Select(pParse, p, &intersectdest);
101432       testcase( rc!=SQLITE_OK );
101433       pDelete = p->pPrior;
101434       p->pPrior = pPrior;
101435       if( p->nSelectRow>pPrior->nSelectRow ) p->nSelectRow = pPrior->nSelectRow;
101436       sqlite3ExprDelete(db, p->pLimit);
101437       p->pLimit = pLimit;
101438       p->pOffset = pOffset;
101439 
101440       /* Generate code to take the intersection of the two temporary
101441       ** tables.
101442       */
101443       assert( p->pEList );
101444       if( dest.eDest==SRT_Output ){
101445         Select *pFirst = p;
101446         while( pFirst->pPrior ) pFirst = pFirst->pPrior;
101447         generateColumnNames(pParse, 0, pFirst->pEList);
101448       }
101449       iBreak = sqlite3VdbeMakeLabel(v);
101450       iCont = sqlite3VdbeMakeLabel(v);
101451       computeLimitRegisters(pParse, p, iBreak);
101452       sqlite3VdbeAddOp2(v, OP_Rewind, tab1, iBreak);
101453       r1 = sqlite3GetTempReg(pParse);
101454       iStart = sqlite3VdbeAddOp2(v, OP_RowKey, tab1, r1);
101455       sqlite3VdbeAddOp4Int(v, OP_NotFound, tab2, iCont, r1, 0);
101456       sqlite3ReleaseTempReg(pParse, r1);
101457       selectInnerLoop(pParse, p, p->pEList, tab1, p->pEList->nExpr,
101458                       0, 0, &dest, iCont, iBreak);
101459       sqlite3VdbeResolveLabel(v, iCont);
101460       sqlite3VdbeAddOp2(v, OP_Next, tab1, iStart);
101461       sqlite3VdbeResolveLabel(v, iBreak);
101462       sqlite3VdbeAddOp2(v, OP_Close, tab2, 0);
101463       sqlite3VdbeAddOp2(v, OP_Close, tab1, 0);
101464       break;
101465     }
101466   }
101467 
101468   explainComposite(pParse, p->op, iSub1, iSub2, p->op!=TK_ALL);
101469 
101470   /* Compute collating sequences used by 
101471   ** temporary tables needed to implement the compound select.
101472   ** Attach the KeyInfo structure to all temporary tables.
101473   **
101474   ** This section is run by the right-most SELECT statement only.
101475   ** SELECT statements to the left always skip this part.  The right-most
101476   ** SELECT might also skip this part if it has no ORDER BY clause and
101477   ** no temp tables are required.
101478   */
101479   if( p->selFlags & SF_UsesEphemeral ){
101480     int i;                        /* Loop counter */
101481     KeyInfo *pKeyInfo;            /* Collating sequence for the result set */
101482     Select *pLoop;                /* For looping through SELECT statements */
101483     CollSeq **apColl;             /* For looping through pKeyInfo->aColl[] */
101484     int nCol;                     /* Number of columns in result set */
101485 
101486     assert( p->pRightmost==p );
101487     nCol = p->pEList->nExpr;
101488     pKeyInfo = sqlite3KeyInfoAlloc(db, nCol, 1);
101489     if( !pKeyInfo ){
101490       rc = SQLITE_NOMEM;
101491       goto multi_select_end;
101492     }
101493     for(i=0, apColl=pKeyInfo->aColl; i<nCol; i++, apColl++){
101494       *apColl = multiSelectCollSeq(pParse, p, i);
101495       if( 0==*apColl ){
101496         *apColl = db->pDfltColl;
101497       }
101498     }
101499 
101500     for(pLoop=p; pLoop; pLoop=pLoop->pPrior){
101501       for(i=0; i<2; i++){
101502         int addr = pLoop->addrOpenEphm[i];
101503         if( addr<0 ){
101504           /* If [0] is unused then [1] is also unused.  So we can
101505           ** always safely abort as soon as the first unused slot is found */
101506           assert( pLoop->addrOpenEphm[1]<0 );
101507           break;
101508         }
101509         sqlite3VdbeChangeP2(v, addr, nCol);
101510         sqlite3VdbeChangeP4(v, addr, (char*)sqlite3KeyInfoRef(pKeyInfo),
101511                             P4_KEYINFO);
101512         pLoop->addrOpenEphm[i] = -1;
101513       }
101514     }
101515     sqlite3KeyInfoUnref(pKeyInfo);
101516   }
101517 
101518 multi_select_end:
101519   pDest->iSdst = dest.iSdst;
101520   pDest->nSdst = dest.nSdst;
101521   sqlite3SelectDelete(db, pDelete);
101522   return rc;
101523 }
101524 #endif /* SQLITE_OMIT_COMPOUND_SELECT */
101525 
101526 /*
101527 ** Code an output subroutine for a coroutine implementation of a
101528 ** SELECT statment.
101529 **
101530 ** The data to be output is contained in pIn->iSdst.  There are
101531 ** pIn->nSdst columns to be output.  pDest is where the output should
101532 ** be sent.
101533 **
101534 ** regReturn is the number of the register holding the subroutine
101535 ** return address.
101536 **
101537 ** If regPrev>0 then it is the first register in a vector that
101538 ** records the previous output.  mem[regPrev] is a flag that is false
101539 ** if there has been no previous output.  If regPrev>0 then code is
101540 ** generated to suppress duplicates.  pKeyInfo is used for comparing
101541 ** keys.
101542 **
101543 ** If the LIMIT found in p->iLimit is reached, jump immediately to
101544 ** iBreak.
101545 */
101546 static int generateOutputSubroutine(
101547   Parse *pParse,          /* Parsing context */
101548   Select *p,              /* The SELECT statement */
101549   SelectDest *pIn,        /* Coroutine supplying data */
101550   SelectDest *pDest,      /* Where to send the data */
101551   int regReturn,          /* The return address register */
101552   int regPrev,            /* Previous result register.  No uniqueness if 0 */
101553   KeyInfo *pKeyInfo,      /* For comparing with previous entry */
101554   int iBreak              /* Jump here if we hit the LIMIT */
101555 ){
101556   Vdbe *v = pParse->pVdbe;
101557   int iContinue;
101558   int addr;
101559 
101560   addr = sqlite3VdbeCurrentAddr(v);
101561   iContinue = sqlite3VdbeMakeLabel(v);
101562 
101563   /* Suppress duplicates for UNION, EXCEPT, and INTERSECT 
101564   */
101565   if( regPrev ){
101566     int j1, j2;
101567     j1 = sqlite3VdbeAddOp1(v, OP_IfNot, regPrev);
101568     j2 = sqlite3VdbeAddOp4(v, OP_Compare, pIn->iSdst, regPrev+1, pIn->nSdst,
101569                               (char*)sqlite3KeyInfoRef(pKeyInfo), P4_KEYINFO);
101570     sqlite3VdbeAddOp3(v, OP_Jump, j2+2, iContinue, j2+2);
101571     sqlite3VdbeJumpHere(v, j1);
101572     sqlite3VdbeAddOp3(v, OP_Copy, pIn->iSdst, regPrev+1, pIn->nSdst-1);
101573     sqlite3VdbeAddOp2(v, OP_Integer, 1, regPrev);
101574   }
101575   if( pParse->db->mallocFailed ) return 0;
101576 
101577   /* Suppress the first OFFSET entries if there is an OFFSET clause
101578   */
101579   codeOffset(v, p, iContinue);
101580 
101581   switch( pDest->eDest ){
101582     /* Store the result as data using a unique key.
101583     */
101584     case SRT_Table:
101585     case SRT_EphemTab: {
101586       int r1 = sqlite3GetTempReg(pParse);
101587       int r2 = sqlite3GetTempReg(pParse);
101588       testcase( pDest->eDest==SRT_Table );
101589       testcase( pDest->eDest==SRT_EphemTab );
101590       sqlite3VdbeAddOp3(v, OP_MakeRecord, pIn->iSdst, pIn->nSdst, r1);
101591       sqlite3VdbeAddOp2(v, OP_NewRowid, pDest->iSDParm, r2);
101592       sqlite3VdbeAddOp3(v, OP_Insert, pDest->iSDParm, r1, r2);
101593       sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
101594       sqlite3ReleaseTempReg(pParse, r2);
101595       sqlite3ReleaseTempReg(pParse, r1);
101596       break;
101597     }
101598 
101599 #ifndef SQLITE_OMIT_SUBQUERY
101600     /* If we are creating a set for an "expr IN (SELECT ...)" construct,
101601     ** then there should be a single item on the stack.  Write this
101602     ** item into the set table with bogus data.
101603     */
101604     case SRT_Set: {
101605       int r1;
101606       assert( pIn->nSdst==1 );
101607       pDest->affSdst = 
101608          sqlite3CompareAffinity(p->pEList->a[0].pExpr, pDest->affSdst);
101609       r1 = sqlite3GetTempReg(pParse);
101610       sqlite3VdbeAddOp4(v, OP_MakeRecord, pIn->iSdst, 1, r1, &pDest->affSdst,1);
101611       sqlite3ExprCacheAffinityChange(pParse, pIn->iSdst, 1);
101612       sqlite3VdbeAddOp2(v, OP_IdxInsert, pDest->iSDParm, r1);
101613       sqlite3ReleaseTempReg(pParse, r1);
101614       break;
101615     }
101616 
101617 #if 0  /* Never occurs on an ORDER BY query */
101618     /* If any row exist in the result set, record that fact and abort.
101619     */
101620     case SRT_Exists: {
101621       sqlite3VdbeAddOp2(v, OP_Integer, 1, pDest->iSDParm);
101622       /* The LIMIT clause will terminate the loop for us */
101623       break;
101624     }
101625 #endif
101626 
101627     /* If this is a scalar select that is part of an expression, then
101628     ** store the results in the appropriate memory cell and break out
101629     ** of the scan loop.
101630     */
101631     case SRT_Mem: {
101632       assert( pIn->nSdst==1 );
101633       sqlite3ExprCodeMove(pParse, pIn->iSdst, pDest->iSDParm, 1);
101634       /* The LIMIT clause will jump out of the loop for us */
101635       break;
101636     }
101637 #endif /* #ifndef SQLITE_OMIT_SUBQUERY */
101638 
101639     /* The results are stored in a sequence of registers
101640     ** starting at pDest->iSdst.  Then the co-routine yields.
101641     */
101642     case SRT_Coroutine: {
101643       if( pDest->iSdst==0 ){
101644         pDest->iSdst = sqlite3GetTempRange(pParse, pIn->nSdst);
101645         pDest->nSdst = pIn->nSdst;
101646       }
101647       sqlite3ExprCodeMove(pParse, pIn->iSdst, pDest->iSdst, pDest->nSdst);
101648       sqlite3VdbeAddOp1(v, OP_Yield, pDest->iSDParm);
101649       break;
101650     }
101651 
101652     /* If none of the above, then the result destination must be
101653     ** SRT_Output.  This routine is never called with any other
101654     ** destination other than the ones handled above or SRT_Output.
101655     **
101656     ** For SRT_Output, results are stored in a sequence of registers.  
101657     ** Then the OP_ResultRow opcode is used to cause sqlite3_step() to
101658     ** return the next row of result.
101659     */
101660     default: {
101661       assert( pDest->eDest==SRT_Output );
101662       sqlite3VdbeAddOp2(v, OP_ResultRow, pIn->iSdst, pIn->nSdst);
101663       sqlite3ExprCacheAffinityChange(pParse, pIn->iSdst, pIn->nSdst);
101664       break;
101665     }
101666   }
101667 
101668   /* Jump to the end of the loop if the LIMIT is reached.
101669   */
101670   if( p->iLimit ){
101671     sqlite3VdbeAddOp3(v, OP_IfZero, p->iLimit, iBreak, -1);
101672   }
101673 
101674   /* Generate the subroutine return
101675   */
101676   sqlite3VdbeResolveLabel(v, iContinue);
101677   sqlite3VdbeAddOp1(v, OP_Return, regReturn);
101678 
101679   return addr;
101680 }
101681 
101682 /*
101683 ** Alternative compound select code generator for cases when there
101684 ** is an ORDER BY clause.
101685 **
101686 ** We assume a query of the following form:
101687 **
101688 **      <selectA>  <operator>  <selectB>  ORDER BY <orderbylist>
101689 **
101690 ** <operator> is one of UNION ALL, UNION, EXCEPT, or INTERSECT.  The idea
101691 ** is to code both <selectA> and <selectB> with the ORDER BY clause as
101692 ** co-routines.  Then run the co-routines in parallel and merge the results
101693 ** into the output.  In addition to the two coroutines (called selectA and
101694 ** selectB) there are 7 subroutines:
101695 **
101696 **    outA:    Move the output of the selectA coroutine into the output
101697 **             of the compound query.
101698 **
101699 **    outB:    Move the output of the selectB coroutine into the output
101700 **             of the compound query.  (Only generated for UNION and
101701 **             UNION ALL.  EXCEPT and INSERTSECT never output a row that
101702 **             appears only in B.)
101703 **
101704 **    AltB:    Called when there is data from both coroutines and A<B.
101705 **
101706 **    AeqB:    Called when there is data from both coroutines and A==B.
101707 **
101708 **    AgtB:    Called when there is data from both coroutines and A>B.
101709 **
101710 **    EofA:    Called when data is exhausted from selectA.
101711 **
101712 **    EofB:    Called when data is exhausted from selectB.
101713 **
101714 ** The implementation of the latter five subroutines depend on which 
101715 ** <operator> is used:
101716 **
101717 **
101718 **             UNION ALL         UNION            EXCEPT          INTERSECT
101719 **          -------------  -----------------  --------------  -----------------
101720 **   AltB:   outA, nextA      outA, nextA       outA, nextA         nextA
101721 **
101722 **   AeqB:   outA, nextA         nextA             nextA         outA, nextA
101723 **
101724 **   AgtB:   outB, nextB      outB, nextB          nextB            nextB
101725 **
101726 **   EofA:   outB, nextB      outB, nextB          halt             halt
101727 **
101728 **   EofB:   outA, nextA      outA, nextA       outA, nextA         halt
101729 **
101730 ** In the AltB, AeqB, and AgtB subroutines, an EOF on A following nextA
101731 ** causes an immediate jump to EofA and an EOF on B following nextB causes
101732 ** an immediate jump to EofB.  Within EofA and EofB, and EOF on entry or
101733 ** following nextX causes a jump to the end of the select processing.
101734 **
101735 ** Duplicate removal in the UNION, EXCEPT, and INTERSECT cases is handled
101736 ** within the output subroutine.  The regPrev register set holds the previously
101737 ** output value.  A comparison is made against this value and the output
101738 ** is skipped if the next results would be the same as the previous.
101739 **
101740 ** The implementation plan is to implement the two coroutines and seven
101741 ** subroutines first, then put the control logic at the bottom.  Like this:
101742 **
101743 **          goto Init
101744 **     coA: coroutine for left query (A)
101745 **     coB: coroutine for right query (B)
101746 **    outA: output one row of A
101747 **    outB: output one row of B (UNION and UNION ALL only)
101748 **    EofA: ...
101749 **    EofB: ...
101750 **    AltB: ...
101751 **    AeqB: ...
101752 **    AgtB: ...
101753 **    Init: initialize coroutine registers
101754 **          yield coA
101755 **          if eof(A) goto EofA
101756 **          yield coB
101757 **          if eof(B) goto EofB
101758 **    Cmpr: Compare A, B
101759 **          Jump AltB, AeqB, AgtB
101760 **     End: ...
101761 **
101762 ** We call AltB, AeqB, AgtB, EofA, and EofB "subroutines" but they are not
101763 ** actually called using Gosub and they do not Return.  EofA and EofB loop
101764 ** until all data is exhausted then jump to the "end" labe.  AltB, AeqB,
101765 ** and AgtB jump to either L2 or to one of EofA or EofB.
101766 */
101767 #ifndef SQLITE_OMIT_COMPOUND_SELECT
101768 static int multiSelectOrderBy(
101769   Parse *pParse,        /* Parsing context */
101770   Select *p,            /* The right-most of SELECTs to be coded */
101771   SelectDest *pDest     /* What to do with query results */
101772 ){
101773   int i, j;             /* Loop counters */
101774   Select *pPrior;       /* Another SELECT immediately to our left */
101775   Vdbe *v;              /* Generate code to this VDBE */
101776   SelectDest destA;     /* Destination for coroutine A */
101777   SelectDest destB;     /* Destination for coroutine B */
101778   int regAddrA;         /* Address register for select-A coroutine */
101779   int regEofA;          /* Flag to indicate when select-A is complete */
101780   int regAddrB;         /* Address register for select-B coroutine */
101781   int regEofB;          /* Flag to indicate when select-B is complete */
101782   int addrSelectA;      /* Address of the select-A coroutine */
101783   int addrSelectB;      /* Address of the select-B coroutine */
101784   int regOutA;          /* Address register for the output-A subroutine */
101785   int regOutB;          /* Address register for the output-B subroutine */
101786   int addrOutA;         /* Address of the output-A subroutine */
101787   int addrOutB = 0;     /* Address of the output-B subroutine */
101788   int addrEofA;         /* Address of the select-A-exhausted subroutine */
101789   int addrEofB;         /* Address of the select-B-exhausted subroutine */
101790   int addrAltB;         /* Address of the A<B subroutine */
101791   int addrAeqB;         /* Address of the A==B subroutine */
101792   int addrAgtB;         /* Address of the A>B subroutine */
101793   int regLimitA;        /* Limit register for select-A */
101794   int regLimitB;        /* Limit register for select-A */
101795   int regPrev;          /* A range of registers to hold previous output */
101796   int savedLimit;       /* Saved value of p->iLimit */
101797   int savedOffset;      /* Saved value of p->iOffset */
101798   int labelCmpr;        /* Label for the start of the merge algorithm */
101799   int labelEnd;         /* Label for the end of the overall SELECT stmt */
101800   int j1;               /* Jump instructions that get retargetted */
101801   int op;               /* One of TK_ALL, TK_UNION, TK_EXCEPT, TK_INTERSECT */
101802   KeyInfo *pKeyDup = 0; /* Comparison information for duplicate removal */
101803   KeyInfo *pKeyMerge;   /* Comparison information for merging rows */
101804   sqlite3 *db;          /* Database connection */
101805   ExprList *pOrderBy;   /* The ORDER BY clause */
101806   int nOrderBy;         /* Number of terms in the ORDER BY clause */
101807   int *aPermute;        /* Mapping from ORDER BY terms to result set columns */
101808 #ifndef SQLITE_OMIT_EXPLAIN
101809   int iSub1;            /* EQP id of left-hand query */
101810   int iSub2;            /* EQP id of right-hand query */
101811 #endif
101812 
101813   assert( p->pOrderBy!=0 );
101814   assert( pKeyDup==0 ); /* "Managed" code needs this.  Ticket #3382. */
101815   db = pParse->db;
101816   v = pParse->pVdbe;
101817   assert( v!=0 );       /* Already thrown the error if VDBE alloc failed */
101818   labelEnd = sqlite3VdbeMakeLabel(v);
101819   labelCmpr = sqlite3VdbeMakeLabel(v);
101820 
101821 
101822   /* Patch up the ORDER BY clause
101823   */
101824   op = p->op;  
101825   pPrior = p->pPrior;
101826   assert( pPrior->pOrderBy==0 );
101827   pOrderBy = p->pOrderBy;
101828   assert( pOrderBy );
101829   nOrderBy = pOrderBy->nExpr;
101830 
101831   /* For operators other than UNION ALL we have to make sure that
101832   ** the ORDER BY clause covers every term of the result set.  Add
101833   ** terms to the ORDER BY clause as necessary.
101834   */
101835   if( op!=TK_ALL ){
101836     for(i=1; db->mallocFailed==0 && i<=p->pEList->nExpr; i++){
101837       struct ExprList_item *pItem;
101838       for(j=0, pItem=pOrderBy->a; j<nOrderBy; j++, pItem++){
101839         assert( pItem->u.x.iOrderByCol>0 );
101840         if( pItem->u.x.iOrderByCol==i ) break;
101841       }
101842       if( j==nOrderBy ){
101843         Expr *pNew = sqlite3Expr(db, TK_INTEGER, 0);
101844         if( pNew==0 ) return SQLITE_NOMEM;
101845         pNew->flags |= EP_IntValue;
101846         pNew->u.iValue = i;
101847         pOrderBy = sqlite3ExprListAppend(pParse, pOrderBy, pNew);
101848         if( pOrderBy ) pOrderBy->a[nOrderBy++].u.x.iOrderByCol = (u16)i;
101849       }
101850     }
101851   }
101852 
101853   /* Compute the comparison permutation and keyinfo that is used with
101854   ** the permutation used to determine if the next
101855   ** row of results comes from selectA or selectB.  Also add explicit
101856   ** collations to the ORDER BY clause terms so that when the subqueries
101857   ** to the right and the left are evaluated, they use the correct
101858   ** collation.
101859   */
101860   aPermute = sqlite3DbMallocRaw(db, sizeof(int)*nOrderBy);
101861   if( aPermute ){
101862     struct ExprList_item *pItem;
101863     for(i=0, pItem=pOrderBy->a; i<nOrderBy; i++, pItem++){
101864       assert( pItem->u.x.iOrderByCol>0
101865           && pItem->u.x.iOrderByCol<=p->pEList->nExpr );
101866       aPermute[i] = pItem->u.x.iOrderByCol - 1;
101867     }
101868     pKeyMerge = sqlite3KeyInfoAlloc(db, nOrderBy, 1);
101869     if( pKeyMerge ){
101870       for(i=0; i<nOrderBy; i++){
101871         CollSeq *pColl;
101872         Expr *pTerm = pOrderBy->a[i].pExpr;
101873         if( pTerm->flags & EP_Collate ){
101874           pColl = sqlite3ExprCollSeq(pParse, pTerm);
101875         }else{
101876           pColl = multiSelectCollSeq(pParse, p, aPermute[i]);
101877           if( pColl==0 ) pColl = db->pDfltColl;
101878           pOrderBy->a[i].pExpr =
101879              sqlite3ExprAddCollateString(pParse, pTerm, pColl->zName);
101880         }
101881         assert( sqlite3KeyInfoIsWriteable(pKeyMerge) );
101882         pKeyMerge->aColl[i] = pColl;
101883         pKeyMerge->aSortOrder[i] = pOrderBy->a[i].sortOrder;
101884       }
101885     }
101886   }else{
101887     pKeyMerge = 0;
101888   }
101889 
101890   /* Reattach the ORDER BY clause to the query.
101891   */
101892   p->pOrderBy = pOrderBy;
101893   pPrior->pOrderBy = sqlite3ExprListDup(pParse->db, pOrderBy, 0);
101894 
101895   /* Allocate a range of temporary registers and the KeyInfo needed
101896   ** for the logic that removes duplicate result rows when the
101897   ** operator is UNION, EXCEPT, or INTERSECT (but not UNION ALL).
101898   */
101899   if( op==TK_ALL ){
101900     regPrev = 0;
101901   }else{
101902     int nExpr = p->pEList->nExpr;
101903     assert( nOrderBy>=nExpr || db->mallocFailed );
101904     regPrev = pParse->nMem+1;
101905     pParse->nMem += nExpr+1;
101906     sqlite3VdbeAddOp2(v, OP_Integer, 0, regPrev);
101907     pKeyDup = sqlite3KeyInfoAlloc(db, nExpr, 1);
101908     if( pKeyDup ){
101909       assert( sqlite3KeyInfoIsWriteable(pKeyDup) );
101910       for(i=0; i<nExpr; i++){
101911         pKeyDup->aColl[i] = multiSelectCollSeq(pParse, p, i);
101912         pKeyDup->aSortOrder[i] = 0;
101913       }
101914     }
101915   }
101916  
101917   /* Separate the left and the right query from one another
101918   */
101919   p->pPrior = 0;
101920   sqlite3ResolveOrderGroupBy(pParse, p, p->pOrderBy, "ORDER");
101921   if( pPrior->pPrior==0 ){
101922     sqlite3ResolveOrderGroupBy(pParse, pPrior, pPrior->pOrderBy, "ORDER");
101923   }
101924 
101925   /* Compute the limit registers */
101926   computeLimitRegisters(pParse, p, labelEnd);
101927   if( p->iLimit && op==TK_ALL ){
101928     regLimitA = ++pParse->nMem;
101929     regLimitB = ++pParse->nMem;
101930     sqlite3VdbeAddOp2(v, OP_Copy, p->iOffset ? p->iOffset+1 : p->iLimit,
101931                                   regLimitA);
101932     sqlite3VdbeAddOp2(v, OP_Copy, regLimitA, regLimitB);
101933   }else{
101934     regLimitA = regLimitB = 0;
101935   }
101936   sqlite3ExprDelete(db, p->pLimit);
101937   p->pLimit = 0;
101938   sqlite3ExprDelete(db, p->pOffset);
101939   p->pOffset = 0;
101940 
101941   regAddrA = ++pParse->nMem;
101942   regEofA = ++pParse->nMem;
101943   regAddrB = ++pParse->nMem;
101944   regEofB = ++pParse->nMem;
101945   regOutA = ++pParse->nMem;
101946   regOutB = ++pParse->nMem;
101947   sqlite3SelectDestInit(&destA, SRT_Coroutine, regAddrA);
101948   sqlite3SelectDestInit(&destB, SRT_Coroutine, regAddrB);
101949 
101950   /* Jump past the various subroutines and coroutines to the main
101951   ** merge loop
101952   */
101953   j1 = sqlite3VdbeAddOp0(v, OP_Goto);
101954   addrSelectA = sqlite3VdbeCurrentAddr(v);
101955 
101956 
101957   /* Generate a coroutine to evaluate the SELECT statement to the
101958   ** left of the compound operator - the "A" select.
101959   */
101960   VdbeNoopComment((v, "Begin coroutine for left SELECT"));
101961   pPrior->iLimit = regLimitA;
101962   explainSetInteger(iSub1, pParse->iNextSelectId);
101963   sqlite3Select(pParse, pPrior, &destA);
101964   sqlite3VdbeAddOp2(v, OP_Integer, 1, regEofA);
101965   sqlite3VdbeAddOp1(v, OP_Yield, regAddrA);
101966   VdbeNoopComment((v, "End coroutine for left SELECT"));
101967 
101968   /* Generate a coroutine to evaluate the SELECT statement on 
101969   ** the right - the "B" select
101970   */
101971   addrSelectB = sqlite3VdbeCurrentAddr(v);
101972   VdbeNoopComment((v, "Begin coroutine for right SELECT"));
101973   savedLimit = p->iLimit;
101974   savedOffset = p->iOffset;
101975   p->iLimit = regLimitB;
101976   p->iOffset = 0;  
101977   explainSetInteger(iSub2, pParse->iNextSelectId);
101978   sqlite3Select(pParse, p, &destB);
101979   p->iLimit = savedLimit;
101980   p->iOffset = savedOffset;
101981   sqlite3VdbeAddOp2(v, OP_Integer, 1, regEofB);
101982   sqlite3VdbeAddOp1(v, OP_Yield, regAddrB);
101983   VdbeNoopComment((v, "End coroutine for right SELECT"));
101984 
101985   /* Generate a subroutine that outputs the current row of the A
101986   ** select as the next output row of the compound select.
101987   */
101988   VdbeNoopComment((v, "Output routine for A"));
101989   addrOutA = generateOutputSubroutine(pParse,
101990                  p, &destA, pDest, regOutA,
101991                  regPrev, pKeyDup, labelEnd);
101992   
101993   /* Generate a subroutine that outputs the current row of the B
101994   ** select as the next output row of the compound select.
101995   */
101996   if( op==TK_ALL || op==TK_UNION ){
101997     VdbeNoopComment((v, "Output routine for B"));
101998     addrOutB = generateOutputSubroutine(pParse,
101999                  p, &destB, pDest, regOutB,
102000                  regPrev, pKeyDup, labelEnd);
102001   }
102002   sqlite3KeyInfoUnref(pKeyDup);
102003 
102004   /* Generate a subroutine to run when the results from select A
102005   ** are exhausted and only data in select B remains.
102006   */
102007   VdbeNoopComment((v, "eof-A subroutine"));
102008   if( op==TK_EXCEPT || op==TK_INTERSECT ){
102009     addrEofA = sqlite3VdbeAddOp2(v, OP_Goto, 0, labelEnd);
102010   }else{  
102011     addrEofA = sqlite3VdbeAddOp2(v, OP_If, regEofB, labelEnd);
102012     sqlite3VdbeAddOp2(v, OP_Gosub, regOutB, addrOutB);
102013     sqlite3VdbeAddOp1(v, OP_Yield, regAddrB);
102014     sqlite3VdbeAddOp2(v, OP_Goto, 0, addrEofA);
102015     p->nSelectRow += pPrior->nSelectRow;
102016   }
102017 
102018   /* Generate a subroutine to run when the results from select B
102019   ** are exhausted and only data in select A remains.
102020   */
102021   if( op==TK_INTERSECT ){
102022     addrEofB = addrEofA;
102023     if( p->nSelectRow > pPrior->nSelectRow ) p->nSelectRow = pPrior->nSelectRow;
102024   }else{  
102025     VdbeNoopComment((v, "eof-B subroutine"));
102026     addrEofB = sqlite3VdbeAddOp2(v, OP_If, regEofA, labelEnd);
102027     sqlite3VdbeAddOp2(v, OP_Gosub, regOutA, addrOutA);
102028     sqlite3VdbeAddOp1(v, OP_Yield, regAddrA);
102029     sqlite3VdbeAddOp2(v, OP_Goto, 0, addrEofB);
102030   }
102031 
102032   /* Generate code to handle the case of A<B
102033   */
102034   VdbeNoopComment((v, "A-lt-B subroutine"));
102035   addrAltB = sqlite3VdbeAddOp2(v, OP_Gosub, regOutA, addrOutA);
102036   sqlite3VdbeAddOp1(v, OP_Yield, regAddrA);
102037   sqlite3VdbeAddOp2(v, OP_If, regEofA, addrEofA);
102038   sqlite3VdbeAddOp2(v, OP_Goto, 0, labelCmpr);
102039 
102040   /* Generate code to handle the case of A==B
102041   */
102042   if( op==TK_ALL ){
102043     addrAeqB = addrAltB;
102044   }else if( op==TK_INTERSECT ){
102045     addrAeqB = addrAltB;
102046     addrAltB++;
102047   }else{
102048     VdbeNoopComment((v, "A-eq-B subroutine"));
102049     addrAeqB =
102050     sqlite3VdbeAddOp1(v, OP_Yield, regAddrA);
102051     sqlite3VdbeAddOp2(v, OP_If, regEofA, addrEofA);
102052     sqlite3VdbeAddOp2(v, OP_Goto, 0, labelCmpr);
102053   }
102054 
102055   /* Generate code to handle the case of A>B
102056   */
102057   VdbeNoopComment((v, "A-gt-B subroutine"));
102058   addrAgtB = sqlite3VdbeCurrentAddr(v);
102059   if( op==TK_ALL || op==TK_UNION ){
102060     sqlite3VdbeAddOp2(v, OP_Gosub, regOutB, addrOutB);
102061   }
102062   sqlite3VdbeAddOp1(v, OP_Yield, regAddrB);
102063   sqlite3VdbeAddOp2(v, OP_If, regEofB, addrEofB);
102064   sqlite3VdbeAddOp2(v, OP_Goto, 0, labelCmpr);
102065 
102066   /* This code runs once to initialize everything.
102067   */
102068   sqlite3VdbeJumpHere(v, j1);
102069   sqlite3VdbeAddOp2(v, OP_Integer, 0, regEofA);
102070   sqlite3VdbeAddOp2(v, OP_Integer, 0, regEofB);
102071   sqlite3VdbeAddOp2(v, OP_Gosub, regAddrA, addrSelectA);
102072   sqlite3VdbeAddOp2(v, OP_Gosub, regAddrB, addrSelectB);
102073   sqlite3VdbeAddOp2(v, OP_If, regEofA, addrEofA);
102074   sqlite3VdbeAddOp2(v, OP_If, regEofB, addrEofB);
102075 
102076   /* Implement the main merge loop
102077   */
102078   sqlite3VdbeResolveLabel(v, labelCmpr);
102079   sqlite3VdbeAddOp4(v, OP_Permutation, 0, 0, 0, (char*)aPermute, P4_INTARRAY);
102080   sqlite3VdbeAddOp4(v, OP_Compare, destA.iSdst, destB.iSdst, nOrderBy,
102081                          (char*)pKeyMerge, P4_KEYINFO);
102082   sqlite3VdbeChangeP5(v, OPFLAG_PERMUTE);
102083   sqlite3VdbeAddOp3(v, OP_Jump, addrAltB, addrAeqB, addrAgtB);
102084 
102085   /* Jump to the this point in order to terminate the query.
102086   */
102087   sqlite3VdbeResolveLabel(v, labelEnd);
102088 
102089   /* Set the number of output columns
102090   */
102091   if( pDest->eDest==SRT_Output ){
102092     Select *pFirst = pPrior;
102093     while( pFirst->pPrior ) pFirst = pFirst->pPrior;
102094     generateColumnNames(pParse, 0, pFirst->pEList);
102095   }
102096 
102097   /* Reassembly the compound query so that it will be freed correctly
102098   ** by the calling function */
102099   if( p->pPrior ){
102100     sqlite3SelectDelete(db, p->pPrior);
102101   }
102102   p->pPrior = pPrior;
102103 
102104   /*** TBD:  Insert subroutine calls to close cursors on incomplete
102105   **** subqueries ****/
102106   explainComposite(pParse, p->op, iSub1, iSub2, 0);
102107   return SQLITE_OK;
102108 }
102109 #endif
102110 
102111 #if !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW)
102112 /* Forward Declarations */
102113 static void substExprList(sqlite3*, ExprList*, int, ExprList*);
102114 static void substSelect(sqlite3*, Select *, int, ExprList *);
102115 
102116 /*
102117 ** Scan through the expression pExpr.  Replace every reference to
102118 ** a column in table number iTable with a copy of the iColumn-th
102119 ** entry in pEList.  (But leave references to the ROWID column 
102120 ** unchanged.)
102121 **
102122 ** This routine is part of the flattening procedure.  A subquery
102123 ** whose result set is defined by pEList appears as entry in the
102124 ** FROM clause of a SELECT such that the VDBE cursor assigned to that
102125 ** FORM clause entry is iTable.  This routine make the necessary 
102126 ** changes to pExpr so that it refers directly to the source table
102127 ** of the subquery rather the result set of the subquery.
102128 */
102129 static Expr *substExpr(
102130   sqlite3 *db,        /* Report malloc errors to this connection */
102131   Expr *pExpr,        /* Expr in which substitution occurs */
102132   int iTable,         /* Table to be substituted */
102133   ExprList *pEList    /* Substitute expressions */
102134 ){
102135   if( pExpr==0 ) return 0;
102136   if( pExpr->op==TK_COLUMN && pExpr->iTable==iTable ){
102137     if( pExpr->iColumn<0 ){
102138       pExpr->op = TK_NULL;
102139     }else{
102140       Expr *pNew;
102141       assert( pEList!=0 && pExpr->iColumn<pEList->nExpr );
102142       assert( pExpr->pLeft==0 && pExpr->pRight==0 );
102143       pNew = sqlite3ExprDup(db, pEList->a[pExpr->iColumn].pExpr, 0);
102144       sqlite3ExprDelete(db, pExpr);
102145       pExpr = pNew;
102146     }
102147   }else{
102148     pExpr->pLeft = substExpr(db, pExpr->pLeft, iTable, pEList);
102149     pExpr->pRight = substExpr(db, pExpr->pRight, iTable, pEList);
102150     if( ExprHasProperty(pExpr, EP_xIsSelect) ){
102151       substSelect(db, pExpr->x.pSelect, iTable, pEList);
102152     }else{
102153       substExprList(db, pExpr->x.pList, iTable, pEList);
102154     }
102155   }
102156   return pExpr;
102157 }
102158 static void substExprList(
102159   sqlite3 *db,         /* Report malloc errors here */
102160   ExprList *pList,     /* List to scan and in which to make substitutes */
102161   int iTable,          /* Table to be substituted */
102162   ExprList *pEList     /* Substitute values */
102163 ){
102164   int i;
102165   if( pList==0 ) return;
102166   for(i=0; i<pList->nExpr; i++){
102167     pList->a[i].pExpr = substExpr(db, pList->a[i].pExpr, iTable, pEList);
102168   }
102169 }
102170 static void substSelect(
102171   sqlite3 *db,         /* Report malloc errors here */
102172   Select *p,           /* SELECT statement in which to make substitutions */
102173   int iTable,          /* Table to be replaced */
102174   ExprList *pEList     /* Substitute values */
102175 ){
102176   SrcList *pSrc;
102177   struct SrcList_item *pItem;
102178   int i;
102179   if( !p ) return;
102180   substExprList(db, p->pEList, iTable, pEList);
102181   substExprList(db, p->pGroupBy, iTable, pEList);
102182   substExprList(db, p->pOrderBy, iTable, pEList);
102183   p->pHaving = substExpr(db, p->pHaving, iTable, pEList);
102184   p->pWhere = substExpr(db, p->pWhere, iTable, pEList);
102185   substSelect(db, p->pPrior, iTable, pEList);
102186   pSrc = p->pSrc;
102187   assert( pSrc );  /* Even for (SELECT 1) we have: pSrc!=0 but pSrc->nSrc==0 */
102188   if( ALWAYS(pSrc) ){
102189     for(i=pSrc->nSrc, pItem=pSrc->a; i>0; i--, pItem++){
102190       substSelect(db, pItem->pSelect, iTable, pEList);
102191     }
102192   }
102193 }
102194 #endif /* !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW) */
102195 
102196 #if !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW)
102197 /*
102198 ** This routine attempts to flatten subqueries as a performance optimization.
102199 ** This routine returns 1 if it makes changes and 0 if no flattening occurs.
102200 **
102201 ** To understand the concept of flattening, consider the following
102202 ** query:
102203 **
102204 **     SELECT a FROM (SELECT x+y AS a FROM t1 WHERE z<100) WHERE a>5
102205 **
102206 ** The default way of implementing this query is to execute the
102207 ** subquery first and store the results in a temporary table, then
102208 ** run the outer query on that temporary table.  This requires two
102209 ** passes over the data.  Furthermore, because the temporary table
102210 ** has no indices, the WHERE clause on the outer query cannot be
102211 ** optimized.
102212 **
102213 ** This routine attempts to rewrite queries such as the above into
102214 ** a single flat select, like this:
102215 **
102216 **     SELECT x+y AS a FROM t1 WHERE z<100 AND a>5
102217 **
102218 ** The code generated for this simpification gives the same result
102219 ** but only has to scan the data once.  And because indices might 
102220 ** exist on the table t1, a complete scan of the data might be
102221 ** avoided.
102222 **
102223 ** Flattening is only attempted if all of the following are true:
102224 **
102225 **   (1)  The subquery and the outer query do not both use aggregates.
102226 **
102227 **   (2)  The subquery is not an aggregate or the outer query is not a join.
102228 **
102229 **   (3)  The subquery is not the right operand of a left outer join
102230 **        (Originally ticket #306.  Strengthened by ticket #3300)
102231 **
102232 **   (4)  The subquery is not DISTINCT.
102233 **
102234 **  (**)  At one point restrictions (4) and (5) defined a subset of DISTINCT
102235 **        sub-queries that were excluded from this optimization. Restriction 
102236 **        (4) has since been expanded to exclude all DISTINCT subqueries.
102237 **
102238 **   (6)  The subquery does not use aggregates or the outer query is not
102239 **        DISTINCT.
102240 **
102241 **   (7)  The subquery has a FROM clause.  TODO:  For subqueries without
102242 **        A FROM clause, consider adding a FROM close with the special
102243 **        table sqlite_once that consists of a single row containing a
102244 **        single NULL.
102245 **
102246 **   (8)  The subquery does not use LIMIT or the outer query is not a join.
102247 **
102248 **   (9)  The subquery does not use LIMIT or the outer query does not use
102249 **        aggregates.
102250 **
102251 **  (10)  The subquery does not use aggregates or the outer query does not
102252 **        use LIMIT.
102253 **
102254 **  (11)  The subquery and the outer query do not both have ORDER BY clauses.
102255 **
102256 **  (**)  Not implemented.  Subsumed into restriction (3).  Was previously
102257 **        a separate restriction deriving from ticket #350.
102258 **
102259 **  (13)  The subquery and outer query do not both use LIMIT.
102260 **
102261 **  (14)  The subquery does not use OFFSET.
102262 **
102263 **  (15)  The outer query is not part of a compound select or the
102264 **        subquery does not have a LIMIT clause.
102265 **        (See ticket #2339 and ticket [02a8e81d44]).
102266 **
102267 **  (16)  The outer query is not an aggregate or the subquery does
102268 **        not contain ORDER BY.  (Ticket #2942)  This used to not matter
102269 **        until we introduced the group_concat() function.  
102270 **
102271 **  (17)  The sub-query is not a compound select, or it is a UNION ALL 
102272 **        compound clause made up entirely of non-aggregate queries, and 
102273 **        the parent query:
102274 **
102275 **          * is not itself part of a compound select,
102276 **          * is not an aggregate or DISTINCT query, and
102277 **          * is not a join
102278 **
102279 **        The parent and sub-query may contain WHERE clauses. Subject to
102280 **        rules (11), (13) and (14), they may also contain ORDER BY,
102281 **        LIMIT and OFFSET clauses.  The subquery cannot use any compound
102282 **        operator other than UNION ALL because all the other compound
102283 **        operators have an implied DISTINCT which is disallowed by
102284 **        restriction (4).
102285 **
102286 **        Also, each component of the sub-query must return the same number
102287 **        of result columns. This is actually a requirement for any compound
102288 **        SELECT statement, but all the code here does is make sure that no
102289 **        such (illegal) sub-query is flattened. The caller will detect the
102290 **        syntax error and return a detailed message.
102291 **
102292 **  (18)  If the sub-query is a compound select, then all terms of the
102293 **        ORDER by clause of the parent must be simple references to 
102294 **        columns of the sub-query.
102295 **
102296 **  (19)  The subquery does not use LIMIT or the outer query does not
102297 **        have a WHERE clause.
102298 **
102299 **  (20)  If the sub-query is a compound select, then it must not use
102300 **        an ORDER BY clause.  Ticket #3773.  We could relax this constraint
102301 **        somewhat by saying that the terms of the ORDER BY clause must
102302 **        appear as unmodified result columns in the outer query.  But we
102303 **        have other optimizations in mind to deal with that case.
102304 **
102305 **  (21)  The subquery does not use LIMIT or the outer query is not
102306 **        DISTINCT.  (See ticket [752e1646fc]).
102307 **
102308 ** In this routine, the "p" parameter is a pointer to the outer query.
102309 ** The subquery is p->pSrc->a[iFrom].  isAgg is true if the outer query
102310 ** uses aggregates and subqueryIsAgg is true if the subquery uses aggregates.
102311 **
102312 ** If flattening is not attempted, this routine is a no-op and returns 0.
102313 ** If flattening is attempted this routine returns 1.
102314 **
102315 ** All of the expression analysis must occur on both the outer query and
102316 ** the subquery before this routine runs.
102317 */
102318 static int flattenSubquery(
102319   Parse *pParse,       /* Parsing context */
102320   Select *p,           /* The parent or outer SELECT statement */
102321   int iFrom,           /* Index in p->pSrc->a[] of the inner subquery */
102322   int isAgg,           /* True if outer SELECT uses aggregate functions */
102323   int subqueryIsAgg    /* True if the subquery uses aggregate functions */
102324 ){
102325   const char *zSavedAuthContext = pParse->zAuthContext;
102326   Select *pParent;
102327   Select *pSub;       /* The inner query or "subquery" */
102328   Select *pSub1;      /* Pointer to the rightmost select in sub-query */
102329   SrcList *pSrc;      /* The FROM clause of the outer query */
102330   SrcList *pSubSrc;   /* The FROM clause of the subquery */
102331   ExprList *pList;    /* The result set of the outer query */
102332   int iParent;        /* VDBE cursor number of the pSub result set temp table */
102333   int i;              /* Loop counter */
102334   Expr *pWhere;                    /* The WHERE clause */
102335   struct SrcList_item *pSubitem;   /* The subquery */
102336   sqlite3 *db = pParse->db;
102337 
102338   /* Check to see if flattening is permitted.  Return 0 if not.
102339   */
102340   assert( p!=0 );
102341   assert( p->pPrior==0 );  /* Unable to flatten compound queries */
102342   if( OptimizationDisabled(db, SQLITE_QueryFlattener) ) return 0;
102343   pSrc = p->pSrc;
102344   assert( pSrc && iFrom>=0 && iFrom<pSrc->nSrc );
102345   pSubitem = &pSrc->a[iFrom];
102346   iParent = pSubitem->iCursor;
102347   pSub = pSubitem->pSelect;
102348   assert( pSub!=0 );
102349   if( isAgg && subqueryIsAgg ) return 0;                 /* Restriction (1)  */
102350   if( subqueryIsAgg && pSrc->nSrc>1 ) return 0;          /* Restriction (2)  */
102351   pSubSrc = pSub->pSrc;
102352   assert( pSubSrc );
102353   /* Prior to version 3.1.2, when LIMIT and OFFSET had to be simple constants,
102354   ** not arbitrary expresssions, we allowed some combining of LIMIT and OFFSET
102355   ** because they could be computed at compile-time.  But when LIMIT and OFFSET
102356   ** became arbitrary expressions, we were forced to add restrictions (13)
102357   ** and (14). */
102358   if( pSub->pLimit && p->pLimit ) return 0;              /* Restriction (13) */
102359   if( pSub->pOffset ) return 0;                          /* Restriction (14) */
102360   if( p->pRightmost && pSub->pLimit ){
102361     return 0;                                            /* Restriction (15) */
102362   }
102363   if( pSubSrc->nSrc==0 ) return 0;                       /* Restriction (7)  */
102364   if( pSub->selFlags & SF_Distinct ) return 0;           /* Restriction (5)  */
102365   if( pSub->pLimit && (pSrc->nSrc>1 || isAgg) ){
102366      return 0;         /* Restrictions (8)(9) */
102367   }
102368   if( (p->selFlags & SF_Distinct)!=0 && subqueryIsAgg ){
102369      return 0;         /* Restriction (6)  */
102370   }
102371   if( p->pOrderBy && pSub->pOrderBy ){
102372      return 0;                                           /* Restriction (11) */
102373   }
102374   if( isAgg && pSub->pOrderBy ) return 0;                /* Restriction (16) */
102375   if( pSub->pLimit && p->pWhere ) return 0;              /* Restriction (19) */
102376   if( pSub->pLimit && (p->selFlags & SF_Distinct)!=0 ){
102377      return 0;         /* Restriction (21) */
102378   }
102379 
102380   /* OBSOLETE COMMENT 1:
102381   ** Restriction 3:  If the subquery is a join, make sure the subquery is 
102382   ** not used as the right operand of an outer join.  Examples of why this
102383   ** is not allowed:
102384   **
102385   **         t1 LEFT OUTER JOIN (t2 JOIN t3)
102386   **
102387   ** If we flatten the above, we would get
102388   **
102389   **         (t1 LEFT OUTER JOIN t2) JOIN t3
102390   **
102391   ** which is not at all the same thing.
102392   **
102393   ** OBSOLETE COMMENT 2:
102394   ** Restriction 12:  If the subquery is the right operand of a left outer
102395   ** join, make sure the subquery has no WHERE clause.
102396   ** An examples of why this is not allowed:
102397   **
102398   **         t1 LEFT OUTER JOIN (SELECT * FROM t2 WHERE t2.x>0)
102399   **
102400   ** If we flatten the above, we would get
102401   **
102402   **         (t1 LEFT OUTER JOIN t2) WHERE t2.x>0
102403   **
102404   ** But the t2.x>0 test will always fail on a NULL row of t2, which
102405   ** effectively converts the OUTER JOIN into an INNER JOIN.
102406   **
102407   ** THIS OVERRIDES OBSOLETE COMMENTS 1 AND 2 ABOVE:
102408   ** Ticket #3300 shows that flattening the right term of a LEFT JOIN
102409   ** is fraught with danger.  Best to avoid the whole thing.  If the
102410   ** subquery is the right term of a LEFT JOIN, then do not flatten.
102411   */
102412   if( (pSubitem->jointype & JT_OUTER)!=0 ){
102413     return 0;
102414   }
102415 
102416   /* Restriction 17: If the sub-query is a compound SELECT, then it must
102417   ** use only the UNION ALL operator. And none of the simple select queries
102418   ** that make up the compound SELECT are allowed to be aggregate or distinct
102419   ** queries.
102420   */
102421   if( pSub->pPrior ){
102422     if( pSub->pOrderBy ){
102423       return 0;  /* Restriction 20 */
102424     }
102425     if( isAgg || (p->selFlags & SF_Distinct)!=0 || pSrc->nSrc!=1 ){
102426       return 0;
102427     }
102428     for(pSub1=pSub; pSub1; pSub1=pSub1->pPrior){
102429       testcase( (pSub1->selFlags & (SF_Distinct|SF_Aggregate))==SF_Distinct );
102430       testcase( (pSub1->selFlags & (SF_Distinct|SF_Aggregate))==SF_Aggregate );
102431       assert( pSub->pSrc!=0 );
102432       if( (pSub1->selFlags & (SF_Distinct|SF_Aggregate))!=0
102433        || (pSub1->pPrior && pSub1->op!=TK_ALL) 
102434        || pSub1->pSrc->nSrc<1
102435        || pSub->pEList->nExpr!=pSub1->pEList->nExpr
102436       ){
102437         return 0;
102438       }
102439       testcase( pSub1->pSrc->nSrc>1 );
102440     }
102441 
102442     /* Restriction 18. */
102443     if( p->pOrderBy ){
102444       int ii;
102445       for(ii=0; ii<p->pOrderBy->nExpr; ii++){
102446         if( p->pOrderBy->a[ii].u.x.iOrderByCol==0 ) return 0;
102447       }
102448     }
102449   }
102450 
102451   /***** If we reach this point, flattening is permitted. *****/
102452 
102453   /* Authorize the subquery */
102454   pParse->zAuthContext = pSubitem->zName;
102455   TESTONLY(i =) sqlite3AuthCheck(pParse, SQLITE_SELECT, 0, 0, 0);
102456   testcase( i==SQLITE_DENY );
102457   pParse->zAuthContext = zSavedAuthContext;
102458 
102459   /* If the sub-query is a compound SELECT statement, then (by restrictions
102460   ** 17 and 18 above) it must be a UNION ALL and the parent query must 
102461   ** be of the form:
102462   **
102463   **     SELECT <expr-list> FROM (<sub-query>) <where-clause> 
102464   **
102465   ** followed by any ORDER BY, LIMIT and/or OFFSET clauses. This block
102466   ** creates N-1 copies of the parent query without any ORDER BY, LIMIT or 
102467   ** OFFSET clauses and joins them to the left-hand-side of the original
102468   ** using UNION ALL operators. In this case N is the number of simple
102469   ** select statements in the compound sub-query.
102470   **
102471   ** Example:
102472   **
102473   **     SELECT a+1 FROM (
102474   **        SELECT x FROM tab
102475   **        UNION ALL
102476   **        SELECT y FROM tab
102477   **        UNION ALL
102478   **        SELECT abs(z*2) FROM tab2
102479   **     ) WHERE a!=5 ORDER BY 1
102480   **
102481   ** Transformed into:
102482   **
102483   **     SELECT x+1 FROM tab WHERE x+1!=5
102484   **     UNION ALL
102485   **     SELECT y+1 FROM tab WHERE y+1!=5
102486   **     UNION ALL
102487   **     SELECT abs(z*2)+1 FROM tab2 WHERE abs(z*2)+1!=5
102488   **     ORDER BY 1
102489   **
102490   ** We call this the "compound-subquery flattening".
102491   */
102492   for(pSub=pSub->pPrior; pSub; pSub=pSub->pPrior){
102493     Select *pNew;
102494     ExprList *pOrderBy = p->pOrderBy;
102495     Expr *pLimit = p->pLimit;
102496     Expr *pOffset = p->pOffset;
102497     Select *pPrior = p->pPrior;
102498     p->pOrderBy = 0;
102499     p->pSrc = 0;
102500     p->pPrior = 0;
102501     p->pLimit = 0;
102502     p->pOffset = 0;
102503     pNew = sqlite3SelectDup(db, p, 0);
102504     p->pOffset = pOffset;
102505     p->pLimit = pLimit;
102506     p->pOrderBy = pOrderBy;
102507     p->pSrc = pSrc;
102508     p->op = TK_ALL;
102509     p->pRightmost = 0;
102510     if( pNew==0 ){
102511       pNew = pPrior;
102512     }else{
102513       pNew->pPrior = pPrior;
102514       pNew->pRightmost = 0;
102515     }
102516     p->pPrior = pNew;
102517     if( db->mallocFailed ) return 1;
102518   }
102519 
102520   /* Begin flattening the iFrom-th entry of the FROM clause 
102521   ** in the outer query.
102522   */
102523   pSub = pSub1 = pSubitem->pSelect;
102524 
102525   /* Delete the transient table structure associated with the
102526   ** subquery
102527   */
102528   sqlite3DbFree(db, pSubitem->zDatabase);
102529   sqlite3DbFree(db, pSubitem->zName);
102530   sqlite3DbFree(db, pSubitem->zAlias);
102531   pSubitem->zDatabase = 0;
102532   pSubitem->zName = 0;
102533   pSubitem->zAlias = 0;
102534   pSubitem->pSelect = 0;
102535 
102536   /* Defer deleting the Table object associated with the
102537   ** subquery until code generation is
102538   ** complete, since there may still exist Expr.pTab entries that
102539   ** refer to the subquery even after flattening.  Ticket #3346.
102540   **
102541   ** pSubitem->pTab is always non-NULL by test restrictions and tests above.
102542   */
102543   if( ALWAYS(pSubitem->pTab!=0) ){
102544     Table *pTabToDel = pSubitem->pTab;
102545     if( pTabToDel->nRef==1 ){
102546       Parse *pToplevel = sqlite3ParseToplevel(pParse);
102547       pTabToDel->pNextZombie = pToplevel->pZombieTab;
102548       pToplevel->pZombieTab = pTabToDel;
102549     }else{
102550       pTabToDel->nRef--;
102551     }
102552     pSubitem->pTab = 0;
102553   }
102554 
102555   /* The following loop runs once for each term in a compound-subquery
102556   ** flattening (as described above).  If we are doing a different kind
102557   ** of flattening - a flattening other than a compound-subquery flattening -
102558   ** then this loop only runs once.
102559   **
102560   ** This loop moves all of the FROM elements of the subquery into the
102561   ** the FROM clause of the outer query.  Before doing this, remember
102562   ** the cursor number for the original outer query FROM element in
102563   ** iParent.  The iParent cursor will never be used.  Subsequent code
102564   ** will scan expressions looking for iParent references and replace
102565   ** those references with expressions that resolve to the subquery FROM
102566   ** elements we are now copying in.
102567   */
102568   for(pParent=p; pParent; pParent=pParent->pPrior, pSub=pSub->pPrior){
102569     int nSubSrc;
102570     u8 jointype = 0;
102571     pSubSrc = pSub->pSrc;     /* FROM clause of subquery */
102572     nSubSrc = pSubSrc->nSrc;  /* Number of terms in subquery FROM clause */
102573     pSrc = pParent->pSrc;     /* FROM clause of the outer query */
102574 
102575     if( pSrc ){
102576       assert( pParent==p );  /* First time through the loop */
102577       jointype = pSubitem->jointype;
102578     }else{
102579       assert( pParent!=p );  /* 2nd and subsequent times through the loop */
102580       pSrc = pParent->pSrc = sqlite3SrcListAppend(db, 0, 0, 0);
102581       if( pSrc==0 ){
102582         assert( db->mallocFailed );
102583         break;
102584       }
102585     }
102586 
102587     /* The subquery uses a single slot of the FROM clause of the outer
102588     ** query.  If the subquery has more than one element in its FROM clause,
102589     ** then expand the outer query to make space for it to hold all elements
102590     ** of the subquery.
102591     **
102592     ** Example:
102593     **
102594     **    SELECT * FROM tabA, (SELECT * FROM sub1, sub2), tabB;
102595     **
102596     ** The outer query has 3 slots in its FROM clause.  One slot of the
102597     ** outer query (the middle slot) is used by the subquery.  The next
102598     ** block of code will expand the out query to 4 slots.  The middle
102599     ** slot is expanded to two slots in order to make space for the
102600     ** two elements in the FROM clause of the subquery.
102601     */
102602     if( nSubSrc>1 ){
102603       pParent->pSrc = pSrc = sqlite3SrcListEnlarge(db, pSrc, nSubSrc-1,iFrom+1);
102604       if( db->mallocFailed ){
102605         break;
102606       }
102607     }
102608 
102609     /* Transfer the FROM clause terms from the subquery into the
102610     ** outer query.
102611     */
102612     for(i=0; i<nSubSrc; i++){
102613       sqlite3IdListDelete(db, pSrc->a[i+iFrom].pUsing);
102614       pSrc->a[i+iFrom] = pSubSrc->a[i];
102615       memset(&pSubSrc->a[i], 0, sizeof(pSubSrc->a[i]));
102616     }
102617     pSrc->a[iFrom].jointype = jointype;
102618   
102619     /* Now begin substituting subquery result set expressions for 
102620     ** references to the iParent in the outer query.
102621     ** 
102622     ** Example:
102623     **
102624     **   SELECT a+5, b*10 FROM (SELECT x*3 AS a, y+10 AS b FROM t1) WHERE a>b;
102625     **   \                     \_____________ subquery __________/          /
102626     **    \_____________________ outer query ______________________________/
102627     **
102628     ** We look at every expression in the outer query and every place we see
102629     ** "a" we substitute "x*3" and every place we see "b" we substitute "y+10".
102630     */
102631     pList = pParent->pEList;
102632     for(i=0; i<pList->nExpr; i++){
102633       if( pList->a[i].zName==0 ){
102634         char *zName = sqlite3DbStrDup(db, pList->a[i].zSpan);
102635         sqlite3Dequote(zName);
102636         pList->a[i].zName = zName;
102637       }
102638     }
102639     substExprList(db, pParent->pEList, iParent, pSub->pEList);
102640     if( isAgg ){
102641       substExprList(db, pParent->pGroupBy, iParent, pSub->pEList);
102642       pParent->pHaving = substExpr(db, pParent->pHaving, iParent, pSub->pEList);
102643     }
102644     if( pSub->pOrderBy ){
102645       assert( pParent->pOrderBy==0 );
102646       pParent->pOrderBy = pSub->pOrderBy;
102647       pSub->pOrderBy = 0;
102648     }else if( pParent->pOrderBy ){
102649       substExprList(db, pParent->pOrderBy, iParent, pSub->pEList);
102650     }
102651     if( pSub->pWhere ){
102652       pWhere = sqlite3ExprDup(db, pSub->pWhere, 0);
102653     }else{
102654       pWhere = 0;
102655     }
102656     if( subqueryIsAgg ){
102657       assert( pParent->pHaving==0 );
102658       pParent->pHaving = pParent->pWhere;
102659       pParent->pWhere = pWhere;
102660       pParent->pHaving = substExpr(db, pParent->pHaving, iParent, pSub->pEList);
102661       pParent->pHaving = sqlite3ExprAnd(db, pParent->pHaving, 
102662                                   sqlite3ExprDup(db, pSub->pHaving, 0));
102663       assert( pParent->pGroupBy==0 );
102664       pParent->pGroupBy = sqlite3ExprListDup(db, pSub->pGroupBy, 0);
102665     }else{
102666       pParent->pWhere = substExpr(db, pParent->pWhere, iParent, pSub->pEList);
102667       pParent->pWhere = sqlite3ExprAnd(db, pParent->pWhere, pWhere);
102668     }
102669   
102670     /* The flattened query is distinct if either the inner or the
102671     ** outer query is distinct. 
102672     */
102673     pParent->selFlags |= pSub->selFlags & SF_Distinct;
102674   
102675     /*
102676     ** SELECT ... FROM (SELECT ... LIMIT a OFFSET b) LIMIT x OFFSET y;
102677     **
102678     ** One is tempted to try to add a and b to combine the limits.  But this
102679     ** does not work if either limit is negative.
102680     */
102681     if( pSub->pLimit ){
102682       pParent->pLimit = pSub->pLimit;
102683       pSub->pLimit = 0;
102684     }
102685   }
102686 
102687   /* Finially, delete what is left of the subquery and return
102688   ** success.
102689   */
102690   sqlite3SelectDelete(db, pSub1);
102691 
102692   return 1;
102693 }
102694 #endif /* !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW) */
102695 
102696 /*
102697 ** Based on the contents of the AggInfo structure indicated by the first
102698 ** argument, this function checks if the following are true:
102699 **
102700 **    * the query contains just a single aggregate function,
102701 **    * the aggregate function is either min() or max(), and
102702 **    * the argument to the aggregate function is a column value.
102703 **
102704 ** If all of the above are true, then WHERE_ORDERBY_MIN or WHERE_ORDERBY_MAX
102705 ** is returned as appropriate. Also, *ppMinMax is set to point to the 
102706 ** list of arguments passed to the aggregate before returning.
102707 **
102708 ** Or, if the conditions above are not met, *ppMinMax is set to 0 and
102709 ** WHERE_ORDERBY_NORMAL is returned.
102710 */
102711 static u8 minMaxQuery(AggInfo *pAggInfo, ExprList **ppMinMax){
102712   int eRet = WHERE_ORDERBY_NORMAL;          /* Return value */
102713 
102714   *ppMinMax = 0;
102715   if( pAggInfo->nFunc==1 ){
102716     Expr *pExpr = pAggInfo->aFunc[0].pExpr; /* Aggregate function */
102717     ExprList *pEList = pExpr->x.pList;      /* Arguments to agg function */
102718 
102719     assert( pExpr->op==TK_AGG_FUNCTION );
102720     if( pEList && pEList->nExpr==1 && pEList->a[0].pExpr->op==TK_AGG_COLUMN ){
102721       const char *zFunc = pExpr->u.zToken;
102722       if( sqlite3StrICmp(zFunc, "min")==0 ){
102723         eRet = WHERE_ORDERBY_MIN;
102724         *ppMinMax = pEList;
102725       }else if( sqlite3StrICmp(zFunc, "max")==0 ){
102726         eRet = WHERE_ORDERBY_MAX;
102727         *ppMinMax = pEList;
102728       }
102729     }
102730   }
102731 
102732   assert( *ppMinMax==0 || (*ppMinMax)->nExpr==1 );
102733   return eRet;
102734 }
102735 
102736 /*
102737 ** The select statement passed as the first argument is an aggregate query.
102738 ** The second argment is the associated aggregate-info object. This 
102739 ** function tests if the SELECT is of the form:
102740 **
102741 **   SELECT count(*) FROM <tbl>
102742 **
102743 ** where table is a database table, not a sub-select or view. If the query
102744 ** does match this pattern, then a pointer to the Table object representing
102745 ** <tbl> is returned. Otherwise, 0 is returned.
102746 */
102747 static Table *isSimpleCount(Select *p, AggInfo *pAggInfo){
102748   Table *pTab;
102749   Expr *pExpr;
102750 
102751   assert( !p->pGroupBy );
102752 
102753   if( p->pWhere || p->pEList->nExpr!=1 
102754    || p->pSrc->nSrc!=1 || p->pSrc->a[0].pSelect
102755   ){
102756     return 0;
102757   }
102758   pTab = p->pSrc->a[0].pTab;
102759   pExpr = p->pEList->a[0].pExpr;
102760   assert( pTab && !pTab->pSelect && pExpr );
102761 
102762   if( IsVirtual(pTab) ) return 0;
102763   if( pExpr->op!=TK_AGG_FUNCTION ) return 0;
102764   if( NEVER(pAggInfo->nFunc==0) ) return 0;
102765   if( (pAggInfo->aFunc[0].pFunc->funcFlags&SQLITE_FUNC_COUNT)==0 ) return 0;
102766   if( pExpr->flags&EP_Distinct ) return 0;
102767 
102768   return pTab;
102769 }
102770 
102771 /*
102772 ** If the source-list item passed as an argument was augmented with an
102773 ** INDEXED BY clause, then try to locate the specified index. If there
102774 ** was such a clause and the named index cannot be found, return 
102775 ** SQLITE_ERROR and leave an error in pParse. Otherwise, populate 
102776 ** pFrom->pIndex and return SQLITE_OK.
102777 */
102778 SQLITE_PRIVATE int sqlite3IndexedByLookup(Parse *pParse, struct SrcList_item *pFrom){
102779   if( pFrom->pTab && pFrom->zIndex ){
102780     Table *pTab = pFrom->pTab;
102781     char *zIndex = pFrom->zIndex;
102782     Index *pIdx;
102783     for(pIdx=pTab->pIndex; 
102784         pIdx && sqlite3StrICmp(pIdx->zName, zIndex); 
102785         pIdx=pIdx->pNext
102786     );
102787     if( !pIdx ){
102788       sqlite3ErrorMsg(pParse, "no such index: %s", zIndex, 0);
102789       pParse->checkSchema = 1;
102790       return SQLITE_ERROR;
102791     }
102792     pFrom->pIndex = pIdx;
102793   }
102794   return SQLITE_OK;
102795 }
102796 /*
102797 ** Detect compound SELECT statements that use an ORDER BY clause with 
102798 ** an alternative collating sequence.
102799 **
102800 **    SELECT ... FROM t1 EXCEPT SELECT ... FROM t2 ORDER BY .. COLLATE ...
102801 **
102802 ** These are rewritten as a subquery:
102803 **
102804 **    SELECT * FROM (SELECT ... FROM t1 EXCEPT SELECT ... FROM t2)
102805 **     ORDER BY ... COLLATE ...
102806 **
102807 ** This transformation is necessary because the multiSelectOrderBy() routine
102808 ** above that generates the code for a compound SELECT with an ORDER BY clause
102809 ** uses a merge algorithm that requires the same collating sequence on the
102810 ** result columns as on the ORDER BY clause.  See ticket
102811 ** http://www.sqlite.org/src/info/6709574d2a
102812 **
102813 ** This transformation is only needed for EXCEPT, INTERSECT, and UNION.
102814 ** The UNION ALL operator works fine with multiSelectOrderBy() even when
102815 ** there are COLLATE terms in the ORDER BY.
102816 */
102817 static int convertCompoundSelectToSubquery(Walker *pWalker, Select *p){
102818   int i;
102819   Select *pNew;
102820   Select *pX;
102821   sqlite3 *db;
102822   struct ExprList_item *a;
102823   SrcList *pNewSrc;
102824   Parse *pParse;
102825   Token dummy;
102826 
102827   if( p->pPrior==0 ) return WRC_Continue;
102828   if( p->pOrderBy==0 ) return WRC_Continue;
102829   for(pX=p; pX && (pX->op==TK_ALL || pX->op==TK_SELECT); pX=pX->pPrior){}
102830   if( pX==0 ) return WRC_Continue;
102831   a = p->pOrderBy->a;
102832   for(i=p->pOrderBy->nExpr-1; i>=0; i--){
102833     if( a[i].pExpr->flags & EP_Collate ) break;
102834   }
102835   if( i<0 ) return WRC_Continue;
102836 
102837   /* If we reach this point, that means the transformation is required. */
102838 
102839   pParse = pWalker->pParse;
102840   db = pParse->db;
102841   pNew = sqlite3DbMallocZero(db, sizeof(*pNew) );
102842   if( pNew==0 ) return WRC_Abort;
102843   memset(&dummy, 0, sizeof(dummy));
102844   pNewSrc = sqlite3SrcListAppendFromTerm(pParse,0,0,0,&dummy,pNew,0,0);
102845   if( pNewSrc==0 ) return WRC_Abort;
102846   *pNew = *p;
102847   p->pSrc = pNewSrc;
102848   p->pEList = sqlite3ExprListAppend(pParse, 0, sqlite3Expr(db, TK_ALL, 0));
102849   p->op = TK_SELECT;
102850   p->pWhere = 0;
102851   pNew->pGroupBy = 0;
102852   pNew->pHaving = 0;
102853   pNew->pOrderBy = 0;
102854   p->pPrior = 0;
102855   pNew->pLimit = 0;
102856   pNew->pOffset = 0;
102857   return WRC_Continue;
102858 }
102859 
102860 /*
102861 ** This routine is a Walker callback for "expanding" a SELECT statement.
102862 ** "Expanding" means to do the following:
102863 **
102864 **    (1)  Make sure VDBE cursor numbers have been assigned to every
102865 **         element of the FROM clause.
102866 **
102867 **    (2)  Fill in the pTabList->a[].pTab fields in the SrcList that 
102868 **         defines FROM clause.  When views appear in the FROM clause,
102869 **         fill pTabList->a[].pSelect with a copy of the SELECT statement
102870 **         that implements the view.  A copy is made of the view's SELECT
102871 **         statement so that we can freely modify or delete that statement
102872 **         without worrying about messing up the presistent representation
102873 **         of the view.
102874 **
102875 **    (3)  Add terms to the WHERE clause to accomodate the NATURAL keyword
102876 **         on joins and the ON and USING clause of joins.
102877 **
102878 **    (4)  Scan the list of columns in the result set (pEList) looking
102879 **         for instances of the "*" operator or the TABLE.* operator.
102880 **         If found, expand each "*" to be every column in every table
102881 **         and TABLE.* to be every column in TABLE.
102882 **
102883 */
102884 static int selectExpander(Walker *pWalker, Select *p){
102885   Parse *pParse = pWalker->pParse;
102886   int i, j, k;
102887   SrcList *pTabList;
102888   ExprList *pEList;
102889   struct SrcList_item *pFrom;
102890   sqlite3 *db = pParse->db;
102891   Expr *pE, *pRight, *pExpr;
102892   u16 selFlags = p->selFlags;
102893 
102894   p->selFlags |= SF_Expanded;
102895   if( db->mallocFailed  ){
102896     return WRC_Abort;
102897   }
102898   if( NEVER(p->pSrc==0) || (selFlags & SF_Expanded)!=0 ){
102899     return WRC_Prune;
102900   }
102901   pTabList = p->pSrc;
102902   pEList = p->pEList;
102903 
102904   /* Make sure cursor numbers have been assigned to all entries in
102905   ** the FROM clause of the SELECT statement.
102906   */
102907   sqlite3SrcListAssignCursors(pParse, pTabList);
102908 
102909   /* Look up every table named in the FROM clause of the select.  If
102910   ** an entry of the FROM clause is a subquery instead of a table or view,
102911   ** then create a transient table structure to describe the subquery.
102912   */
102913   for(i=0, pFrom=pTabList->a; i<pTabList->nSrc; i++, pFrom++){
102914     Table *pTab;
102915     if( pFrom->pTab!=0 ){
102916       /* This statement has already been prepared.  There is no need
102917       ** to go further. */
102918       assert( i==0 );
102919       return WRC_Prune;
102920     }
102921     if( pFrom->zName==0 ){
102922 #ifndef SQLITE_OMIT_SUBQUERY
102923       Select *pSel = pFrom->pSelect;
102924       /* A sub-query in the FROM clause of a SELECT */
102925       assert( pSel!=0 );
102926       assert( pFrom->pTab==0 );
102927       sqlite3WalkSelect(pWalker, pSel);
102928       pFrom->pTab = pTab = sqlite3DbMallocZero(db, sizeof(Table));
102929       if( pTab==0 ) return WRC_Abort;
102930       pTab->nRef = 1;
102931       pTab->zName = sqlite3MPrintf(db, "sqlite_sq_%p", (void*)pTab);
102932       while( pSel->pPrior ){ pSel = pSel->pPrior; }
102933       selectColumnsFromExprList(pParse, pSel->pEList, &pTab->nCol, &pTab->aCol);
102934       pTab->iPKey = -1;
102935       pTab->nRowEst = 1048576;
102936       pTab->tabFlags |= TF_Ephemeral;
102937 #endif
102938     }else{
102939       /* An ordinary table or view name in the FROM clause */
102940       assert( pFrom->pTab==0 );
102941       pFrom->pTab = pTab = sqlite3LocateTableItem(pParse, 0, pFrom);
102942       if( pTab==0 ) return WRC_Abort;
102943       if( pTab->nRef==0xffff ){
102944         sqlite3ErrorMsg(pParse, "too many references to \"%s\": max 65535",
102945            pTab->zName);
102946         pFrom->pTab = 0;
102947         return WRC_Abort;
102948       }
102949       pTab->nRef++;
102950 #if !defined(SQLITE_OMIT_VIEW) || !defined (SQLITE_OMIT_VIRTUALTABLE)
102951       if( pTab->pSelect || IsVirtual(pTab) ){
102952         /* We reach here if the named table is a really a view */
102953         if( sqlite3ViewGetColumnNames(pParse, pTab) ) return WRC_Abort;
102954         assert( pFrom->pSelect==0 );
102955         pFrom->pSelect = sqlite3SelectDup(db, pTab->pSelect, 0);
102956         sqlite3WalkSelect(pWalker, pFrom->pSelect);
102957       }
102958 #endif
102959     }
102960 
102961     /* Locate the index named by the INDEXED BY clause, if any. */
102962     if( sqlite3IndexedByLookup(pParse, pFrom) ){
102963       return WRC_Abort;
102964     }
102965   }
102966 
102967   /* Process NATURAL keywords, and ON and USING clauses of joins.
102968   */
102969   if( db->mallocFailed || sqliteProcessJoin(pParse, p) ){
102970     return WRC_Abort;
102971   }
102972 
102973   /* For every "*" that occurs in the column list, insert the names of
102974   ** all columns in all tables.  And for every TABLE.* insert the names
102975   ** of all columns in TABLE.  The parser inserted a special expression
102976   ** with the TK_ALL operator for each "*" that it found in the column list.
102977   ** The following code just has to locate the TK_ALL expressions and expand
102978   ** each one to the list of all columns in all tables.
102979   **
102980   ** The first loop just checks to see if there are any "*" operators
102981   ** that need expanding.
102982   */
102983   for(k=0; k<pEList->nExpr; k++){
102984     pE = pEList->a[k].pExpr;
102985     if( pE->op==TK_ALL ) break;
102986     assert( pE->op!=TK_DOT || pE->pRight!=0 );
102987     assert( pE->op!=TK_DOT || (pE->pLeft!=0 && pE->pLeft->op==TK_ID) );
102988     if( pE->op==TK_DOT && pE->pRight->op==TK_ALL ) break;
102989   }
102990   if( k<pEList->nExpr ){
102991     /*
102992     ** If we get here it means the result set contains one or more "*"
102993     ** operators that need to be expanded.  Loop through each expression
102994     ** in the result set and expand them one by one.
102995     */
102996     struct ExprList_item *a = pEList->a;
102997     ExprList *pNew = 0;
102998     int flags = pParse->db->flags;
102999     int longNames = (flags & SQLITE_FullColNames)!=0
103000                       && (flags & SQLITE_ShortColNames)==0;
103001 
103002     /* When processing FROM-clause subqueries, it is always the case
103003     ** that full_column_names=OFF and short_column_names=ON.  The
103004     ** sqlite3ResultSetOfSelect() routine makes it so. */
103005     assert( (p->selFlags & SF_NestedFrom)==0
103006           || ((flags & SQLITE_FullColNames)==0 &&
103007               (flags & SQLITE_ShortColNames)!=0) );
103008 
103009     for(k=0; k<pEList->nExpr; k++){
103010       pE = a[k].pExpr;
103011       pRight = pE->pRight;
103012       assert( pE->op!=TK_DOT || pRight!=0 );
103013       if( pE->op!=TK_ALL && (pE->op!=TK_DOT || pRight->op!=TK_ALL) ){
103014         /* This particular expression does not need to be expanded.
103015         */
103016         pNew = sqlite3ExprListAppend(pParse, pNew, a[k].pExpr);
103017         if( pNew ){
103018           pNew->a[pNew->nExpr-1].zName = a[k].zName;
103019           pNew->a[pNew->nExpr-1].zSpan = a[k].zSpan;
103020           a[k].zName = 0;
103021           a[k].zSpan = 0;
103022         }
103023         a[k].pExpr = 0;
103024       }else{
103025         /* This expression is a "*" or a "TABLE.*" and needs to be
103026         ** expanded. */
103027         int tableSeen = 0;      /* Set to 1 when TABLE matches */
103028         char *zTName = 0;       /* text of name of TABLE */
103029         if( pE->op==TK_DOT ){
103030           assert( pE->pLeft!=0 );
103031           assert( !ExprHasProperty(pE->pLeft, EP_IntValue) );
103032           zTName = pE->pLeft->u.zToken;
103033         }
103034         for(i=0, pFrom=pTabList->a; i<pTabList->nSrc; i++, pFrom++){
103035           Table *pTab = pFrom->pTab;
103036           Select *pSub = pFrom->pSelect;
103037           char *zTabName = pFrom->zAlias;
103038           const char *zSchemaName = 0;
103039           int iDb;
103040           if( zTabName==0 ){
103041             zTabName = pTab->zName;
103042           }
103043           if( db->mallocFailed ) break;
103044           if( pSub==0 || (pSub->selFlags & SF_NestedFrom)==0 ){
103045             pSub = 0;
103046             if( zTName && sqlite3StrICmp(zTName, zTabName)!=0 ){
103047               continue;
103048             }
103049             iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
103050             zSchemaName = iDb>=0 ? db->aDb[iDb].zName : "*";
103051           }
103052           for(j=0; j<pTab->nCol; j++){
103053             char *zName = pTab->aCol[j].zName;
103054             char *zColname;  /* The computed column name */
103055             char *zToFree;   /* Malloced string that needs to be freed */
103056             Token sColname;  /* Computed column name as a token */
103057 
103058             assert( zName );
103059             if( zTName && pSub
103060              && sqlite3MatchSpanName(pSub->pEList->a[j].zSpan, 0, zTName, 0)==0
103061             ){
103062               continue;
103063             }
103064 
103065             /* If a column is marked as 'hidden' (currently only possible
103066             ** for virtual tables), do not include it in the expanded
103067             ** result-set list.
103068             */
103069             if( IsHiddenColumn(&pTab->aCol[j]) ){
103070               assert(IsVirtual(pTab));
103071               continue;
103072             }
103073             tableSeen = 1;
103074 
103075             if( i>0 && zTName==0 ){
103076               if( (pFrom->jointype & JT_NATURAL)!=0
103077                 && tableAndColumnIndex(pTabList, i, zName, 0, 0)
103078               ){
103079                 /* In a NATURAL join, omit the join columns from the 
103080                 ** table to the right of the join */
103081                 continue;
103082               }
103083               if( sqlite3IdListIndex(pFrom->pUsing, zName)>=0 ){
103084                 /* In a join with a USING clause, omit columns in the
103085                 ** using clause from the table on the right. */
103086                 continue;
103087               }
103088             }
103089             pRight = sqlite3Expr(db, TK_ID, zName);
103090             zColname = zName;
103091             zToFree = 0;
103092             if( longNames || pTabList->nSrc>1 ){
103093               Expr *pLeft;
103094               pLeft = sqlite3Expr(db, TK_ID, zTabName);
103095               pExpr = sqlite3PExpr(pParse, TK_DOT, pLeft, pRight, 0);
103096               if( zSchemaName ){
103097                 pLeft = sqlite3Expr(db, TK_ID, zSchemaName);
103098                 pExpr = sqlite3PExpr(pParse, TK_DOT, pLeft, pExpr, 0);
103099               }
103100               if( longNames ){
103101                 zColname = sqlite3MPrintf(db, "%s.%s", zTabName, zName);
103102                 zToFree = zColname;
103103               }
103104             }else{
103105               pExpr = pRight;
103106             }
103107             pNew = sqlite3ExprListAppend(pParse, pNew, pExpr);
103108             sColname.z = zColname;
103109             sColname.n = sqlite3Strlen30(zColname);
103110             sqlite3ExprListSetName(pParse, pNew, &sColname, 0);
103111             if( pNew && (p->selFlags & SF_NestedFrom)!=0 ){
103112               struct ExprList_item *pX = &pNew->a[pNew->nExpr-1];
103113               if( pSub ){
103114                 pX->zSpan = sqlite3DbStrDup(db, pSub->pEList->a[j].zSpan);
103115                 testcase( pX->zSpan==0 );
103116               }else{
103117                 pX->zSpan = sqlite3MPrintf(db, "%s.%s.%s",
103118                                            zSchemaName, zTabName, zColname);
103119                 testcase( pX->zSpan==0 );
103120               }
103121               pX->bSpanIsTab = 1;
103122             }
103123             sqlite3DbFree(db, zToFree);
103124           }
103125         }
103126         if( !tableSeen ){
103127           if( zTName ){
103128             sqlite3ErrorMsg(pParse, "no such table: %s", zTName);
103129           }else{
103130             sqlite3ErrorMsg(pParse, "no tables specified");
103131           }
103132         }
103133       }
103134     }
103135     sqlite3ExprListDelete(db, pEList);
103136     p->pEList = pNew;
103137   }
103138 #if SQLITE_MAX_COLUMN
103139   if( p->pEList && p->pEList->nExpr>db->aLimit[SQLITE_LIMIT_COLUMN] ){
103140     sqlite3ErrorMsg(pParse, "too many columns in result set");
103141   }
103142 #endif
103143   return WRC_Continue;
103144 }
103145 
103146 /*
103147 ** No-op routine for the parse-tree walker.
103148 **
103149 ** When this routine is the Walker.xExprCallback then expression trees
103150 ** are walked without any actions being taken at each node.  Presumably,
103151 ** when this routine is used for Walker.xExprCallback then 
103152 ** Walker.xSelectCallback is set to do something useful for every 
103153 ** subquery in the parser tree.
103154 */
103155 static int exprWalkNoop(Walker *NotUsed, Expr *NotUsed2){
103156   UNUSED_PARAMETER2(NotUsed, NotUsed2);
103157   return WRC_Continue;
103158 }
103159 
103160 /*
103161 ** This routine "expands" a SELECT statement and all of its subqueries.
103162 ** For additional information on what it means to "expand" a SELECT
103163 ** statement, see the comment on the selectExpand worker callback above.
103164 **
103165 ** Expanding a SELECT statement is the first step in processing a
103166 ** SELECT statement.  The SELECT statement must be expanded before
103167 ** name resolution is performed.
103168 **
103169 ** If anything goes wrong, an error message is written into pParse.
103170 ** The calling function can detect the problem by looking at pParse->nErr
103171 ** and/or pParse->db->mallocFailed.
103172 */
103173 static void sqlite3SelectExpand(Parse *pParse, Select *pSelect){
103174   Walker w;
103175   memset(&w, 0, sizeof(w));
103176   w.xExprCallback = exprWalkNoop;
103177   w.pParse = pParse;
103178   if( pParse->hasCompound ){
103179     w.xSelectCallback = convertCompoundSelectToSubquery;
103180     sqlite3WalkSelect(&w, pSelect);
103181   }
103182   w.xSelectCallback = selectExpander;
103183   sqlite3WalkSelect(&w, pSelect);
103184 }
103185 
103186 
103187 #ifndef SQLITE_OMIT_SUBQUERY
103188 /*
103189 ** This is a Walker.xSelectCallback callback for the sqlite3SelectTypeInfo()
103190 ** interface.
103191 **
103192 ** For each FROM-clause subquery, add Column.zType and Column.zColl
103193 ** information to the Table structure that represents the result set
103194 ** of that subquery.
103195 **
103196 ** The Table structure that represents the result set was constructed
103197 ** by selectExpander() but the type and collation information was omitted
103198 ** at that point because identifiers had not yet been resolved.  This
103199 ** routine is called after identifier resolution.
103200 */
103201 static int selectAddSubqueryTypeInfo(Walker *pWalker, Select *p){
103202   Parse *pParse;
103203   int i;
103204   SrcList *pTabList;
103205   struct SrcList_item *pFrom;
103206 
103207   assert( p->selFlags & SF_Resolved );
103208   if( (p->selFlags & SF_HasTypeInfo)==0 ){
103209     p->selFlags |= SF_HasTypeInfo;
103210     pParse = pWalker->pParse;
103211     pTabList = p->pSrc;
103212     for(i=0, pFrom=pTabList->a; i<pTabList->nSrc; i++, pFrom++){
103213       Table *pTab = pFrom->pTab;
103214       if( ALWAYS(pTab!=0) && (pTab->tabFlags & TF_Ephemeral)!=0 ){
103215         /* A sub-query in the FROM clause of a SELECT */
103216         Select *pSel = pFrom->pSelect;
103217         assert( pSel );
103218         while( pSel->pPrior ) pSel = pSel->pPrior;
103219         selectAddColumnTypeAndCollation(pParse, pTab, pSel);
103220       }
103221     }
103222   }
103223   return WRC_Continue;
103224 }
103225 #endif
103226 
103227 
103228 /*
103229 ** This routine adds datatype and collating sequence information to
103230 ** the Table structures of all FROM-clause subqueries in a
103231 ** SELECT statement.
103232 **
103233 ** Use this routine after name resolution.
103234 */
103235 static void sqlite3SelectAddTypeInfo(Parse *pParse, Select *pSelect){
103236 #ifndef SQLITE_OMIT_SUBQUERY
103237   Walker w;
103238   memset(&w, 0, sizeof(w));
103239   w.xSelectCallback = selectAddSubqueryTypeInfo;
103240   w.xExprCallback = exprWalkNoop;
103241   w.pParse = pParse;
103242   w.bSelectDepthFirst = 1;
103243   sqlite3WalkSelect(&w, pSelect);
103244 #endif
103245 }
103246 
103247 
103248 /*
103249 ** This routine sets up a SELECT statement for processing.  The
103250 ** following is accomplished:
103251 **
103252 **     *  VDBE Cursor numbers are assigned to all FROM-clause terms.
103253 **     *  Ephemeral Table objects are created for all FROM-clause subqueries.
103254 **     *  ON and USING clauses are shifted into WHERE statements
103255 **     *  Wildcards "*" and "TABLE.*" in result sets are expanded.
103256 **     *  Identifiers in expression are matched to tables.
103257 **
103258 ** This routine acts recursively on all subqueries within the SELECT.
103259 */
103260 SQLITE_PRIVATE void sqlite3SelectPrep(
103261   Parse *pParse,         /* The parser context */
103262   Select *p,             /* The SELECT statement being coded. */
103263   NameContext *pOuterNC  /* Name context for container */
103264 ){
103265   sqlite3 *db;
103266   if( NEVER(p==0) ) return;
103267   db = pParse->db;
103268   if( db->mallocFailed ) return;
103269   if( p->selFlags & SF_HasTypeInfo ) return;
103270   sqlite3SelectExpand(pParse, p);
103271   if( pParse->nErr || db->mallocFailed ) return;
103272   sqlite3ResolveSelectNames(pParse, p, pOuterNC);
103273   if( pParse->nErr || db->mallocFailed ) return;
103274   sqlite3SelectAddTypeInfo(pParse, p);
103275 }
103276 
103277 /*
103278 ** Reset the aggregate accumulator.
103279 **
103280 ** The aggregate accumulator is a set of memory cells that hold
103281 ** intermediate results while calculating an aggregate.  This
103282 ** routine generates code that stores NULLs in all of those memory
103283 ** cells.
103284 */
103285 static void resetAccumulator(Parse *pParse, AggInfo *pAggInfo){
103286   Vdbe *v = pParse->pVdbe;
103287   int i;
103288   struct AggInfo_func *pFunc;
103289   if( pAggInfo->nFunc+pAggInfo->nColumn==0 ){
103290     return;
103291   }
103292   for(i=0; i<pAggInfo->nColumn; i++){
103293     sqlite3VdbeAddOp2(v, OP_Null, 0, pAggInfo->aCol[i].iMem);
103294   }
103295   for(pFunc=pAggInfo->aFunc, i=0; i<pAggInfo->nFunc; i++, pFunc++){
103296     sqlite3VdbeAddOp2(v, OP_Null, 0, pFunc->iMem);
103297     if( pFunc->iDistinct>=0 ){
103298       Expr *pE = pFunc->pExpr;
103299       assert( !ExprHasProperty(pE, EP_xIsSelect) );
103300       if( pE->x.pList==0 || pE->x.pList->nExpr!=1 ){
103301         sqlite3ErrorMsg(pParse, "DISTINCT aggregates must have exactly one "
103302            "argument");
103303         pFunc->iDistinct = -1;
103304       }else{
103305         KeyInfo *pKeyInfo = keyInfoFromExprList(pParse, pE->x.pList);
103306         sqlite3VdbeAddOp4(v, OP_OpenEphemeral, pFunc->iDistinct, 0, 0,
103307                           (char*)pKeyInfo, P4_KEYINFO);
103308       }
103309     }
103310   }
103311 }
103312 
103313 /*
103314 ** Invoke the OP_AggFinalize opcode for every aggregate function
103315 ** in the AggInfo structure.
103316 */
103317 static void finalizeAggFunctions(Parse *pParse, AggInfo *pAggInfo){
103318   Vdbe *v = pParse->pVdbe;
103319   int i;
103320   struct AggInfo_func *pF;
103321   for(i=0, pF=pAggInfo->aFunc; i<pAggInfo->nFunc; i++, pF++){
103322     ExprList *pList = pF->pExpr->x.pList;
103323     assert( !ExprHasProperty(pF->pExpr, EP_xIsSelect) );
103324     sqlite3VdbeAddOp4(v, OP_AggFinal, pF->iMem, pList ? pList->nExpr : 0, 0,
103325                       (void*)pF->pFunc, P4_FUNCDEF);
103326   }
103327 }
103328 
103329 /*
103330 ** Update the accumulator memory cells for an aggregate based on
103331 ** the current cursor position.
103332 */
103333 static void updateAccumulator(Parse *pParse, AggInfo *pAggInfo){
103334   Vdbe *v = pParse->pVdbe;
103335   int i;
103336   int regHit = 0;
103337   int addrHitTest = 0;
103338   struct AggInfo_func *pF;
103339   struct AggInfo_col *pC;
103340 
103341   pAggInfo->directMode = 1;
103342   sqlite3ExprCacheClear(pParse);
103343   for(i=0, pF=pAggInfo->aFunc; i<pAggInfo->nFunc; i++, pF++){
103344     int nArg;
103345     int addrNext = 0;
103346     int regAgg;
103347     ExprList *pList = pF->pExpr->x.pList;
103348     assert( !ExprHasProperty(pF->pExpr, EP_xIsSelect) );
103349     if( pList ){
103350       nArg = pList->nExpr;
103351       regAgg = sqlite3GetTempRange(pParse, nArg);
103352       sqlite3ExprCodeExprList(pParse, pList, regAgg, SQLITE_ECEL_DUP);
103353     }else{
103354       nArg = 0;
103355       regAgg = 0;
103356     }
103357     if( pF->iDistinct>=0 ){
103358       addrNext = sqlite3VdbeMakeLabel(v);
103359       assert( nArg==1 );
103360       codeDistinct(pParse, pF->iDistinct, addrNext, 1, regAgg);
103361     }
103362     if( pF->pFunc->funcFlags & SQLITE_FUNC_NEEDCOLL ){
103363       CollSeq *pColl = 0;
103364       struct ExprList_item *pItem;
103365       int j;
103366       assert( pList!=0 );  /* pList!=0 if pF->pFunc has NEEDCOLL */
103367       for(j=0, pItem=pList->a; !pColl && j<nArg; j++, pItem++){
103368         pColl = sqlite3ExprCollSeq(pParse, pItem->pExpr);
103369       }
103370       if( !pColl ){
103371         pColl = pParse->db->pDfltColl;
103372       }
103373       if( regHit==0 && pAggInfo->nAccumulator ) regHit = ++pParse->nMem;
103374       sqlite3VdbeAddOp4(v, OP_CollSeq, regHit, 0, 0, (char *)pColl, P4_COLLSEQ);
103375     }
103376     sqlite3VdbeAddOp4(v, OP_AggStep, 0, regAgg, pF->iMem,
103377                       (void*)pF->pFunc, P4_FUNCDEF);
103378     sqlite3VdbeChangeP5(v, (u8)nArg);
103379     sqlite3ExprCacheAffinityChange(pParse, regAgg, nArg);
103380     sqlite3ReleaseTempRange(pParse, regAgg, nArg);
103381     if( addrNext ){
103382       sqlite3VdbeResolveLabel(v, addrNext);
103383       sqlite3ExprCacheClear(pParse);
103384     }
103385   }
103386 
103387   /* Before populating the accumulator registers, clear the column cache.
103388   ** Otherwise, if any of the required column values are already present 
103389   ** in registers, sqlite3ExprCode() may use OP_SCopy to copy the value
103390   ** to pC->iMem. But by the time the value is used, the original register
103391   ** may have been used, invalidating the underlying buffer holding the
103392   ** text or blob value. See ticket [883034dcb5].
103393   **
103394   ** Another solution would be to change the OP_SCopy used to copy cached
103395   ** values to an OP_Copy.
103396   */
103397   if( regHit ){
103398     addrHitTest = sqlite3VdbeAddOp1(v, OP_If, regHit);
103399   }
103400   sqlite3ExprCacheClear(pParse);
103401   for(i=0, pC=pAggInfo->aCol; i<pAggInfo->nAccumulator; i++, pC++){
103402     sqlite3ExprCode(pParse, pC->pExpr, pC->iMem);
103403   }
103404   pAggInfo->directMode = 0;
103405   sqlite3ExprCacheClear(pParse);
103406   if( addrHitTest ){
103407     sqlite3VdbeJumpHere(v, addrHitTest);
103408   }
103409 }
103410 
103411 /*
103412 ** Add a single OP_Explain instruction to the VDBE to explain a simple
103413 ** count(*) query ("SELECT count(*) FROM pTab").
103414 */
103415 #ifndef SQLITE_OMIT_EXPLAIN
103416 static void explainSimpleCount(
103417   Parse *pParse,                  /* Parse context */
103418   Table *pTab,                    /* Table being queried */
103419   Index *pIdx                     /* Index used to optimize scan, or NULL */
103420 ){
103421   if( pParse->explain==2 ){
103422     char *zEqp = sqlite3MPrintf(pParse->db, "SCAN TABLE %s%s%s",
103423         pTab->zName, 
103424         pIdx ? " USING COVERING INDEX " : "",
103425         pIdx ? pIdx->zName : ""
103426     );
103427     sqlite3VdbeAddOp4(
103428         pParse->pVdbe, OP_Explain, pParse->iSelectId, 0, 0, zEqp, P4_DYNAMIC
103429     );
103430   }
103431 }
103432 #else
103433 # define explainSimpleCount(a,b,c)
103434 #endif
103435 
103436 /*
103437 ** Generate code for the SELECT statement given in the p argument.  
103438 **
103439 ** The results are distributed in various ways depending on the
103440 ** contents of the SelectDest structure pointed to by argument pDest
103441 ** as follows:
103442 **
103443 **     pDest->eDest    Result
103444 **     ------------    -------------------------------------------
103445 **     SRT_Output      Generate a row of output (using the OP_ResultRow
103446 **                     opcode) for each row in the result set.
103447 **
103448 **     SRT_Mem         Only valid if the result is a single column.
103449 **                     Store the first column of the first result row
103450 **                     in register pDest->iSDParm then abandon the rest
103451 **                     of the query.  This destination implies "LIMIT 1".
103452 **
103453 **     SRT_Set         The result must be a single column.  Store each
103454 **                     row of result as the key in table pDest->iSDParm. 
103455 **                     Apply the affinity pDest->affSdst before storing
103456 **                     results.  Used to implement "IN (SELECT ...)".
103457 **
103458 **     SRT_Union       Store results as a key in a temporary table 
103459 **                     identified by pDest->iSDParm.
103460 **
103461 **     SRT_Except      Remove results from the temporary table pDest->iSDParm.
103462 **
103463 **     SRT_Table       Store results in temporary table pDest->iSDParm.
103464 **                     This is like SRT_EphemTab except that the table
103465 **                     is assumed to already be open.
103466 **
103467 **     SRT_EphemTab    Create an temporary table pDest->iSDParm and store
103468 **                     the result there. The cursor is left open after
103469 **                     returning.  This is like SRT_Table except that
103470 **                     this destination uses OP_OpenEphemeral to create
103471 **                     the table first.
103472 **
103473 **     SRT_Coroutine   Generate a co-routine that returns a new row of
103474 **                     results each time it is invoked.  The entry point
103475 **                     of the co-routine is stored in register pDest->iSDParm.
103476 **
103477 **     SRT_Exists      Store a 1 in memory cell pDest->iSDParm if the result
103478 **                     set is not empty.
103479 **
103480 **     SRT_Discard     Throw the results away.  This is used by SELECT
103481 **                     statements within triggers whose only purpose is
103482 **                     the side-effects of functions.
103483 **
103484 ** This routine returns the number of errors.  If any errors are
103485 ** encountered, then an appropriate error message is left in
103486 ** pParse->zErrMsg.
103487 **
103488 ** This routine does NOT free the Select structure passed in.  The
103489 ** calling function needs to do that.
103490 */
103491 SQLITE_PRIVATE int sqlite3Select(
103492   Parse *pParse,         /* The parser context */
103493   Select *p,             /* The SELECT statement being coded. */
103494   SelectDest *pDest      /* What to do with the query results */
103495 ){
103496   int i, j;              /* Loop counters */
103497   WhereInfo *pWInfo;     /* Return from sqlite3WhereBegin() */
103498   Vdbe *v;               /* The virtual machine under construction */
103499   int isAgg;             /* True for select lists like "count(*)" */
103500   ExprList *pEList;      /* List of columns to extract. */
103501   SrcList *pTabList;     /* List of tables to select from */
103502   Expr *pWhere;          /* The WHERE clause.  May be NULL */
103503   ExprList *pOrderBy;    /* The ORDER BY clause.  May be NULL */
103504   ExprList *pGroupBy;    /* The GROUP BY clause.  May be NULL */
103505   Expr *pHaving;         /* The HAVING clause.  May be NULL */
103506   int rc = 1;            /* Value to return from this function */
103507   int addrSortIndex;     /* Address of an OP_OpenEphemeral instruction */
103508   DistinctCtx sDistinct; /* Info on how to code the DISTINCT keyword */
103509   AggInfo sAggInfo;      /* Information used by aggregate queries */
103510   int iEnd;              /* Address of the end of the query */
103511   sqlite3 *db;           /* The database connection */
103512 
103513 #ifndef SQLITE_OMIT_EXPLAIN
103514   int iRestoreSelectId = pParse->iSelectId;
103515   pParse->iSelectId = pParse->iNextSelectId++;
103516 #endif
103517 
103518   db = pParse->db;
103519   if( p==0 || db->mallocFailed || pParse->nErr ){
103520     return 1;
103521   }
103522   if( sqlite3AuthCheck(pParse, SQLITE_SELECT, 0, 0, 0) ) return 1;
103523   memset(&sAggInfo, 0, sizeof(sAggInfo));
103524 
103525   if( IgnorableOrderby(pDest) ){
103526     assert(pDest->eDest==SRT_Exists || pDest->eDest==SRT_Union || 
103527            pDest->eDest==SRT_Except || pDest->eDest==SRT_Discard);
103528     /* If ORDER BY makes no difference in the output then neither does
103529     ** DISTINCT so it can be removed too. */
103530     sqlite3ExprListDelete(db, p->pOrderBy);
103531     p->pOrderBy = 0;
103532     p->selFlags &= ~SF_Distinct;
103533   }
103534   sqlite3SelectPrep(pParse, p, 0);
103535   pOrderBy = p->pOrderBy;
103536   pTabList = p->pSrc;
103537   pEList = p->pEList;
103538   if( pParse->nErr || db->mallocFailed ){
103539     goto select_end;
103540   }
103541   isAgg = (p->selFlags & SF_Aggregate)!=0;
103542   assert( pEList!=0 );
103543 
103544   /* Begin generating code.
103545   */
103546   v = sqlite3GetVdbe(pParse);
103547   if( v==0 ) goto select_end;
103548 
103549   /* If writing to memory or generating a set
103550   ** only a single column may be output.
103551   */
103552 #ifndef SQLITE_OMIT_SUBQUERY
103553   if( checkForMultiColumnSelectError(pParse, pDest, pEList->nExpr) ){
103554     goto select_end;
103555   }
103556 #endif
103557 
103558   /* Generate code for all sub-queries in the FROM clause
103559   */
103560 #if !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW)
103561   for(i=0; !p->pPrior && i<pTabList->nSrc; i++){
103562     struct SrcList_item *pItem = &pTabList->a[i];
103563     SelectDest dest;
103564     Select *pSub = pItem->pSelect;
103565     int isAggSub;
103566 
103567     if( pSub==0 ) continue;
103568 
103569     /* Sometimes the code for a subquery will be generated more than
103570     ** once, if the subquery is part of the WHERE clause in a LEFT JOIN,
103571     ** for example.  In that case, do not regenerate the code to manifest
103572     ** a view or the co-routine to implement a view.  The first instance
103573     ** is sufficient, though the subroutine to manifest the view does need
103574     ** to be invoked again. */
103575     if( pItem->addrFillSub ){
103576       if( pItem->viaCoroutine==0 ){
103577         sqlite3VdbeAddOp2(v, OP_Gosub, pItem->regReturn, pItem->addrFillSub);
103578       }
103579       continue;
103580     }
103581 
103582     /* Increment Parse.nHeight by the height of the largest expression
103583     ** tree referred to by this, the parent select. The child select
103584     ** may contain expression trees of at most
103585     ** (SQLITE_MAX_EXPR_DEPTH-Parse.nHeight) height. This is a bit
103586     ** more conservative than necessary, but much easier than enforcing
103587     ** an exact limit.
103588     */
103589     pParse->nHeight += sqlite3SelectExprHeight(p);
103590 
103591     isAggSub = (pSub->selFlags & SF_Aggregate)!=0;
103592     if( flattenSubquery(pParse, p, i, isAgg, isAggSub) ){
103593       /* This subquery can be absorbed into its parent. */
103594       if( isAggSub ){
103595         isAgg = 1;
103596         p->selFlags |= SF_Aggregate;
103597       }
103598       i = -1;
103599     }else if( pTabList->nSrc==1 && (p->selFlags & SF_Materialize)==0
103600       && OptimizationEnabled(db, SQLITE_SubqCoroutine)
103601     ){
103602       /* Implement a co-routine that will return a single row of the result
103603       ** set on each invocation.
103604       */
103605       int addrTop;
103606       int addrEof;
103607       pItem->regReturn = ++pParse->nMem;
103608       addrEof = ++pParse->nMem;
103609       /* Before coding the OP_Goto to jump to the start of the main routine,
103610       ** ensure that the jump to the verify-schema routine has already
103611       ** been coded. Otherwise, the verify-schema would likely be coded as 
103612       ** part of the co-routine. If the main routine then accessed the 
103613       ** database before invoking the co-routine for the first time (for 
103614       ** example to initialize a LIMIT register from a sub-select), it would 
103615       ** be doing so without having verified the schema version and obtained 
103616       ** the required db locks. See ticket d6b36be38.  */
103617       sqlite3CodeVerifySchema(pParse, -1);
103618       sqlite3VdbeAddOp0(v, OP_Goto);
103619       addrTop = sqlite3VdbeAddOp1(v, OP_OpenPseudo, pItem->iCursor);
103620       sqlite3VdbeChangeP5(v, 1);
103621       VdbeComment((v, "coroutine for %s", pItem->pTab->zName));
103622       pItem->addrFillSub = addrTop;
103623       sqlite3VdbeAddOp2(v, OP_Integer, 0, addrEof);
103624       sqlite3VdbeChangeP5(v, 1);
103625       sqlite3SelectDestInit(&dest, SRT_Coroutine, pItem->regReturn);
103626       explainSetInteger(pItem->iSelectId, (u8)pParse->iNextSelectId);
103627       sqlite3Select(pParse, pSub, &dest);
103628       pItem->pTab->nRowEst = (unsigned)pSub->nSelectRow;
103629       pItem->viaCoroutine = 1;
103630       sqlite3VdbeChangeP2(v, addrTop, dest.iSdst);
103631       sqlite3VdbeChangeP3(v, addrTop, dest.nSdst);
103632       sqlite3VdbeAddOp2(v, OP_Integer, 1, addrEof);
103633       sqlite3VdbeAddOp1(v, OP_Yield, pItem->regReturn);
103634       VdbeComment((v, "end %s", pItem->pTab->zName));
103635       sqlite3VdbeJumpHere(v, addrTop-1);
103636       sqlite3ClearTempRegCache(pParse);
103637     }else{
103638       /* Generate a subroutine that will fill an ephemeral table with
103639       ** the content of this subquery.  pItem->addrFillSub will point
103640       ** to the address of the generated subroutine.  pItem->regReturn
103641       ** is a register allocated to hold the subroutine return address
103642       */
103643       int topAddr;
103644       int onceAddr = 0;
103645       int retAddr;
103646       assert( pItem->addrFillSub==0 );
103647       pItem->regReturn = ++pParse->nMem;
103648       topAddr = sqlite3VdbeAddOp2(v, OP_Integer, 0, pItem->regReturn);
103649       pItem->addrFillSub = topAddr+1;
103650       VdbeNoopComment((v, "materialize %s", pItem->pTab->zName));
103651       if( pItem->isCorrelated==0 ){
103652         /* If the subquery is not correlated and if we are not inside of
103653         ** a trigger, then we only need to compute the value of the subquery
103654         ** once. */
103655         onceAddr = sqlite3CodeOnce(pParse);
103656       }
103657       sqlite3SelectDestInit(&dest, SRT_EphemTab, pItem->iCursor);
103658       explainSetInteger(pItem->iSelectId, (u8)pParse->iNextSelectId);
103659       sqlite3Select(pParse, pSub, &dest);
103660       pItem->pTab->nRowEst = (unsigned)pSub->nSelectRow;
103661       if( onceAddr ) sqlite3VdbeJumpHere(v, onceAddr);
103662       retAddr = sqlite3VdbeAddOp1(v, OP_Return, pItem->regReturn);
103663       VdbeComment((v, "end %s", pItem->pTab->zName));
103664       sqlite3VdbeChangeP1(v, topAddr, retAddr);
103665       sqlite3ClearTempRegCache(pParse);
103666     }
103667     if( /*pParse->nErr ||*/ db->mallocFailed ){
103668       goto select_end;
103669     }
103670     pParse->nHeight -= sqlite3SelectExprHeight(p);
103671     pTabList = p->pSrc;
103672     if( !IgnorableOrderby(pDest) ){
103673       pOrderBy = p->pOrderBy;
103674     }
103675   }
103676   pEList = p->pEList;
103677 #endif
103678   pWhere = p->pWhere;
103679   pGroupBy = p->pGroupBy;
103680   pHaving = p->pHaving;
103681   sDistinct.isTnct = (p->selFlags & SF_Distinct)!=0;
103682 
103683 #ifndef SQLITE_OMIT_COMPOUND_SELECT
103684   /* If there is are a sequence of queries, do the earlier ones first.
103685   */
103686   if( p->pPrior ){
103687     if( p->pRightmost==0 ){
103688       Select *pLoop, *pRight = 0;
103689       int cnt = 0;
103690       int mxSelect;
103691       for(pLoop=p; pLoop; pLoop=pLoop->pPrior, cnt++){
103692         pLoop->pRightmost = p;
103693         pLoop->pNext = pRight;
103694         pRight = pLoop;
103695       }
103696       mxSelect = db->aLimit[SQLITE_LIMIT_COMPOUND_SELECT];
103697       if( mxSelect && cnt>mxSelect ){
103698         sqlite3ErrorMsg(pParse, "too many terms in compound SELECT");
103699         goto select_end;
103700       }
103701     }
103702     rc = multiSelect(pParse, p, pDest);
103703     explainSetInteger(pParse->iSelectId, iRestoreSelectId);
103704     return rc;
103705   }
103706 #endif
103707 
103708   /* If there is both a GROUP BY and an ORDER BY clause and they are
103709   ** identical, then disable the ORDER BY clause since the GROUP BY
103710   ** will cause elements to come out in the correct order.  This is
103711   ** an optimization - the correct answer should result regardless.
103712   ** Use the SQLITE_GroupByOrder flag with SQLITE_TESTCTRL_OPTIMIZER
103713   ** to disable this optimization for testing purposes.
103714   */
103715   if( sqlite3ExprListCompare(p->pGroupBy, pOrderBy, -1)==0
103716          && OptimizationEnabled(db, SQLITE_GroupByOrder) ){
103717     pOrderBy = 0;
103718   }
103719 
103720   /* If the query is DISTINCT with an ORDER BY but is not an aggregate, and 
103721   ** if the select-list is the same as the ORDER BY list, then this query
103722   ** can be rewritten as a GROUP BY. In other words, this:
103723   **
103724   **     SELECT DISTINCT xyz FROM ... ORDER BY xyz
103725   **
103726   ** is transformed to:
103727   **
103728   **     SELECT xyz FROM ... GROUP BY xyz
103729   **
103730   ** The second form is preferred as a single index (or temp-table) may be 
103731   ** used for both the ORDER BY and DISTINCT processing. As originally 
103732   ** written the query must use a temp-table for at least one of the ORDER 
103733   ** BY and DISTINCT, and an index or separate temp-table for the other.
103734   */
103735   if( (p->selFlags & (SF_Distinct|SF_Aggregate))==SF_Distinct 
103736    && sqlite3ExprListCompare(pOrderBy, p->pEList, -1)==0
103737   ){
103738     p->selFlags &= ~SF_Distinct;
103739     p->pGroupBy = sqlite3ExprListDup(db, p->pEList, 0);
103740     pGroupBy = p->pGroupBy;
103741     pOrderBy = 0;
103742     /* Notice that even thought SF_Distinct has been cleared from p->selFlags,
103743     ** the sDistinct.isTnct is still set.  Hence, isTnct represents the
103744     ** original setting of the SF_Distinct flag, not the current setting */
103745     assert( sDistinct.isTnct );
103746   }
103747 
103748   /* If there is an ORDER BY clause, then this sorting
103749   ** index might end up being unused if the data can be 
103750   ** extracted in pre-sorted order.  If that is the case, then the
103751   ** OP_OpenEphemeral instruction will be changed to an OP_Noop once
103752   ** we figure out that the sorting index is not needed.  The addrSortIndex
103753   ** variable is used to facilitate that change.
103754   */
103755   if( pOrderBy ){
103756     KeyInfo *pKeyInfo;
103757     pKeyInfo = keyInfoFromExprList(pParse, pOrderBy);
103758     pOrderBy->iECursor = pParse->nTab++;
103759     p->addrOpenEphm[2] = addrSortIndex =
103760       sqlite3VdbeAddOp4(v, OP_OpenEphemeral,
103761                            pOrderBy->iECursor, pOrderBy->nExpr+2, 0,
103762                            (char*)pKeyInfo, P4_KEYINFO);
103763   }else{
103764     addrSortIndex = -1;
103765   }
103766 
103767   /* If the output is destined for a temporary table, open that table.
103768   */
103769   if( pDest->eDest==SRT_EphemTab ){
103770     sqlite3VdbeAddOp2(v, OP_OpenEphemeral, pDest->iSDParm, pEList->nExpr);
103771   }
103772 
103773   /* Set the limiter.
103774   */
103775   iEnd = sqlite3VdbeMakeLabel(v);
103776   p->nSelectRow = LARGEST_INT64;
103777   computeLimitRegisters(pParse, p, iEnd);
103778   if( p->iLimit==0 && addrSortIndex>=0 ){
103779     sqlite3VdbeGetOp(v, addrSortIndex)->opcode = OP_SorterOpen;
103780     p->selFlags |= SF_UseSorter;
103781   }
103782 
103783   /* Open a virtual index to use for the distinct set.
103784   */
103785   if( p->selFlags & SF_Distinct ){
103786     sDistinct.tabTnct = pParse->nTab++;
103787     sDistinct.addrTnct = sqlite3VdbeAddOp4(v, OP_OpenEphemeral,
103788                                 sDistinct.tabTnct, 0, 0,
103789                                 (char*)keyInfoFromExprList(pParse, p->pEList),
103790                                 P4_KEYINFO);
103791     sqlite3VdbeChangeP5(v, BTREE_UNORDERED);
103792     sDistinct.eTnctType = WHERE_DISTINCT_UNORDERED;
103793   }else{
103794     sDistinct.eTnctType = WHERE_DISTINCT_NOOP;
103795   }
103796 
103797   if( !isAgg && pGroupBy==0 ){
103798     /* No aggregate functions and no GROUP BY clause */
103799     u16 wctrlFlags = (sDistinct.isTnct ? WHERE_WANT_DISTINCT : 0);
103800 
103801     /* Begin the database scan. */
103802     pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, pOrderBy, p->pEList,
103803                                wctrlFlags, 0);
103804     if( pWInfo==0 ) goto select_end;
103805     if( sqlite3WhereOutputRowCount(pWInfo) < p->nSelectRow ){
103806       p->nSelectRow = sqlite3WhereOutputRowCount(pWInfo);
103807     }
103808     if( sDistinct.isTnct && sqlite3WhereIsDistinct(pWInfo) ){
103809       sDistinct.eTnctType = sqlite3WhereIsDistinct(pWInfo);
103810     }
103811     if( pOrderBy && sqlite3WhereIsOrdered(pWInfo) ) pOrderBy = 0;
103812 
103813     /* If sorting index that was created by a prior OP_OpenEphemeral 
103814     ** instruction ended up not being needed, then change the OP_OpenEphemeral
103815     ** into an OP_Noop.
103816     */
103817     if( addrSortIndex>=0 && pOrderBy==0 ){
103818       sqlite3VdbeChangeToNoop(v, addrSortIndex);
103819       p->addrOpenEphm[2] = -1;
103820     }
103821 
103822     /* Use the standard inner loop. */
103823     selectInnerLoop(pParse, p, pEList, 0, 0, pOrderBy, &sDistinct, pDest,
103824                     sqlite3WhereContinueLabel(pWInfo),
103825                     sqlite3WhereBreakLabel(pWInfo));
103826 
103827     /* End the database scan loop.
103828     */
103829     sqlite3WhereEnd(pWInfo);
103830   }else{
103831     /* This case when there exist aggregate functions or a GROUP BY clause
103832     ** or both */
103833     NameContext sNC;    /* Name context for processing aggregate information */
103834     int iAMem;          /* First Mem address for storing current GROUP BY */
103835     int iBMem;          /* First Mem address for previous GROUP BY */
103836     int iUseFlag;       /* Mem address holding flag indicating that at least
103837                         ** one row of the input to the aggregator has been
103838                         ** processed */
103839     int iAbortFlag;     /* Mem address which causes query abort if positive */
103840     int groupBySort;    /* Rows come from source in GROUP BY order */
103841     int addrEnd;        /* End of processing for this SELECT */
103842     int sortPTab = 0;   /* Pseudotable used to decode sorting results */
103843     int sortOut = 0;    /* Output register from the sorter */
103844 
103845     /* Remove any and all aliases between the result set and the
103846     ** GROUP BY clause.
103847     */
103848     if( pGroupBy ){
103849       int k;                        /* Loop counter */
103850       struct ExprList_item *pItem;  /* For looping over expression in a list */
103851 
103852       for(k=p->pEList->nExpr, pItem=p->pEList->a; k>0; k--, pItem++){
103853         pItem->u.x.iAlias = 0;
103854       }
103855       for(k=pGroupBy->nExpr, pItem=pGroupBy->a; k>0; k--, pItem++){
103856         pItem->u.x.iAlias = 0;
103857       }
103858       if( p->nSelectRow>100 ) p->nSelectRow = 100;
103859     }else{
103860       p->nSelectRow = 1;
103861     }
103862 
103863  
103864     /* Create a label to jump to when we want to abort the query */
103865     addrEnd = sqlite3VdbeMakeLabel(v);
103866 
103867     /* Convert TK_COLUMN nodes into TK_AGG_COLUMN and make entries in
103868     ** sAggInfo for all TK_AGG_FUNCTION nodes in expressions of the
103869     ** SELECT statement.
103870     */
103871     memset(&sNC, 0, sizeof(sNC));
103872     sNC.pParse = pParse;
103873     sNC.pSrcList = pTabList;
103874     sNC.pAggInfo = &sAggInfo;
103875     sAggInfo.nSortingColumn = pGroupBy ? pGroupBy->nExpr+1 : 0;
103876     sAggInfo.pGroupBy = pGroupBy;
103877     sqlite3ExprAnalyzeAggList(&sNC, pEList);
103878     sqlite3ExprAnalyzeAggList(&sNC, pOrderBy);
103879     if( pHaving ){
103880       sqlite3ExprAnalyzeAggregates(&sNC, pHaving);
103881     }
103882     sAggInfo.nAccumulator = sAggInfo.nColumn;
103883     for(i=0; i<sAggInfo.nFunc; i++){
103884       assert( !ExprHasProperty(sAggInfo.aFunc[i].pExpr, EP_xIsSelect) );
103885       sNC.ncFlags |= NC_InAggFunc;
103886       sqlite3ExprAnalyzeAggList(&sNC, sAggInfo.aFunc[i].pExpr->x.pList);
103887       sNC.ncFlags &= ~NC_InAggFunc;
103888     }
103889     if( db->mallocFailed ) goto select_end;
103890 
103891     /* Processing for aggregates with GROUP BY is very different and
103892     ** much more complex than aggregates without a GROUP BY.
103893     */
103894     if( pGroupBy ){
103895       KeyInfo *pKeyInfo;  /* Keying information for the group by clause */
103896       int j1;             /* A-vs-B comparision jump */
103897       int addrOutputRow;  /* Start of subroutine that outputs a result row */
103898       int regOutputRow;   /* Return address register for output subroutine */
103899       int addrSetAbort;   /* Set the abort flag and return */
103900       int addrTopOfLoop;  /* Top of the input loop */
103901       int addrSortingIdx; /* The OP_OpenEphemeral for the sorting index */
103902       int addrReset;      /* Subroutine for resetting the accumulator */
103903       int regReset;       /* Return address register for reset subroutine */
103904 
103905       /* If there is a GROUP BY clause we might need a sorting index to
103906       ** implement it.  Allocate that sorting index now.  If it turns out
103907       ** that we do not need it after all, the OP_SorterOpen instruction
103908       ** will be converted into a Noop.  
103909       */
103910       sAggInfo.sortingIdx = pParse->nTab++;
103911       pKeyInfo = keyInfoFromExprList(pParse, pGroupBy);
103912       addrSortingIdx = sqlite3VdbeAddOp4(v, OP_SorterOpen, 
103913           sAggInfo.sortingIdx, sAggInfo.nSortingColumn, 
103914           0, (char*)pKeyInfo, P4_KEYINFO);
103915 
103916       /* Initialize memory locations used by GROUP BY aggregate processing
103917       */
103918       iUseFlag = ++pParse->nMem;
103919       iAbortFlag = ++pParse->nMem;
103920       regOutputRow = ++pParse->nMem;
103921       addrOutputRow = sqlite3VdbeMakeLabel(v);
103922       regReset = ++pParse->nMem;
103923       addrReset = sqlite3VdbeMakeLabel(v);
103924       iAMem = pParse->nMem + 1;
103925       pParse->nMem += pGroupBy->nExpr;
103926       iBMem = pParse->nMem + 1;
103927       pParse->nMem += pGroupBy->nExpr;
103928       sqlite3VdbeAddOp2(v, OP_Integer, 0, iAbortFlag);
103929       VdbeComment((v, "clear abort flag"));
103930       sqlite3VdbeAddOp2(v, OP_Integer, 0, iUseFlag);
103931       VdbeComment((v, "indicate accumulator empty"));
103932       sqlite3VdbeAddOp3(v, OP_Null, 0, iAMem, iAMem+pGroupBy->nExpr-1);
103933 
103934       /* Begin a loop that will extract all source rows in GROUP BY order.
103935       ** This might involve two separate loops with an OP_Sort in between, or
103936       ** it might be a single loop that uses an index to extract information
103937       ** in the right order to begin with.
103938       */
103939       sqlite3VdbeAddOp2(v, OP_Gosub, regReset, addrReset);
103940       pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, pGroupBy, 0, 
103941                                  WHERE_GROUPBY, 0);
103942       if( pWInfo==0 ) goto select_end;
103943       if( sqlite3WhereIsOrdered(pWInfo) ){
103944         /* The optimizer is able to deliver rows in group by order so
103945         ** we do not have to sort.  The OP_OpenEphemeral table will be
103946         ** cancelled later because we still need to use the pKeyInfo
103947         */
103948         groupBySort = 0;
103949       }else{
103950         /* Rows are coming out in undetermined order.  We have to push
103951         ** each row into a sorting index, terminate the first loop,
103952         ** then loop over the sorting index in order to get the output
103953         ** in sorted order
103954         */
103955         int regBase;
103956         int regRecord;
103957         int nCol;
103958         int nGroupBy;
103959 
103960         explainTempTable(pParse, 
103961             (sDistinct.isTnct && (p->selFlags&SF_Distinct)==0) ?
103962                     "DISTINCT" : "GROUP BY");
103963 
103964         groupBySort = 1;
103965         nGroupBy = pGroupBy->nExpr;
103966         nCol = nGroupBy + 1;
103967         j = nGroupBy+1;
103968         for(i=0; i<sAggInfo.nColumn; i++){
103969           if( sAggInfo.aCol[i].iSorterColumn>=j ){
103970             nCol++;
103971             j++;
103972           }
103973         }
103974         regBase = sqlite3GetTempRange(pParse, nCol);
103975         sqlite3ExprCacheClear(pParse);
103976         sqlite3ExprCodeExprList(pParse, pGroupBy, regBase, 0);
103977         sqlite3VdbeAddOp2(v, OP_Sequence, sAggInfo.sortingIdx,regBase+nGroupBy);
103978         j = nGroupBy+1;
103979         for(i=0; i<sAggInfo.nColumn; i++){
103980           struct AggInfo_col *pCol = &sAggInfo.aCol[i];
103981           if( pCol->iSorterColumn>=j ){
103982             int r1 = j + regBase;
103983             int r2;
103984 
103985             r2 = sqlite3ExprCodeGetColumn(pParse, 
103986                                pCol->pTab, pCol->iColumn, pCol->iTable, r1, 0);
103987             if( r1!=r2 ){
103988               sqlite3VdbeAddOp2(v, OP_SCopy, r2, r1);
103989             }
103990             j++;
103991           }
103992         }
103993         regRecord = sqlite3GetTempReg(pParse);
103994         sqlite3VdbeAddOp3(v, OP_MakeRecord, regBase, nCol, regRecord);
103995         sqlite3VdbeAddOp2(v, OP_SorterInsert, sAggInfo.sortingIdx, regRecord);
103996         sqlite3ReleaseTempReg(pParse, regRecord);
103997         sqlite3ReleaseTempRange(pParse, regBase, nCol);
103998         sqlite3WhereEnd(pWInfo);
103999         sAggInfo.sortingIdxPTab = sortPTab = pParse->nTab++;
104000         sortOut = sqlite3GetTempReg(pParse);
104001         sqlite3VdbeAddOp3(v, OP_OpenPseudo, sortPTab, sortOut, nCol);
104002         sqlite3VdbeAddOp2(v, OP_SorterSort, sAggInfo.sortingIdx, addrEnd);
104003         VdbeComment((v, "GROUP BY sort"));
104004         sAggInfo.useSortingIdx = 1;
104005         sqlite3ExprCacheClear(pParse);
104006       }
104007 
104008       /* Evaluate the current GROUP BY terms and store in b0, b1, b2...
104009       ** (b0 is memory location iBMem+0, b1 is iBMem+1, and so forth)
104010       ** Then compare the current GROUP BY terms against the GROUP BY terms
104011       ** from the previous row currently stored in a0, a1, a2...
104012       */
104013       addrTopOfLoop = sqlite3VdbeCurrentAddr(v);
104014       sqlite3ExprCacheClear(pParse);
104015       if( groupBySort ){
104016         sqlite3VdbeAddOp2(v, OP_SorterData, sAggInfo.sortingIdx, sortOut);
104017       }
104018       for(j=0; j<pGroupBy->nExpr; j++){
104019         if( groupBySort ){
104020           sqlite3VdbeAddOp3(v, OP_Column, sortPTab, j, iBMem+j);
104021           if( j==0 ) sqlite3VdbeChangeP5(v, OPFLAG_CLEARCACHE);
104022         }else{
104023           sAggInfo.directMode = 1;
104024           sqlite3ExprCode(pParse, pGroupBy->a[j].pExpr, iBMem+j);
104025         }
104026       }
104027       sqlite3VdbeAddOp4(v, OP_Compare, iAMem, iBMem, pGroupBy->nExpr,
104028                           (char*)sqlite3KeyInfoRef(pKeyInfo), P4_KEYINFO);
104029       j1 = sqlite3VdbeCurrentAddr(v);
104030       sqlite3VdbeAddOp3(v, OP_Jump, j1+1, 0, j1+1);
104031 
104032       /* Generate code that runs whenever the GROUP BY changes.
104033       ** Changes in the GROUP BY are detected by the previous code
104034       ** block.  If there were no changes, this block is skipped.
104035       **
104036       ** This code copies current group by terms in b0,b1,b2,...
104037       ** over to a0,a1,a2.  It then calls the output subroutine
104038       ** and resets the aggregate accumulator registers in preparation
104039       ** for the next GROUP BY batch.
104040       */
104041       sqlite3ExprCodeMove(pParse, iBMem, iAMem, pGroupBy->nExpr);
104042       sqlite3VdbeAddOp2(v, OP_Gosub, regOutputRow, addrOutputRow);
104043       VdbeComment((v, "output one row"));
104044       sqlite3VdbeAddOp2(v, OP_IfPos, iAbortFlag, addrEnd);
104045       VdbeComment((v, "check abort flag"));
104046       sqlite3VdbeAddOp2(v, OP_Gosub, regReset, addrReset);
104047       VdbeComment((v, "reset accumulator"));
104048 
104049       /* Update the aggregate accumulators based on the content of
104050       ** the current row
104051       */
104052       sqlite3VdbeJumpHere(v, j1);
104053       updateAccumulator(pParse, &sAggInfo);
104054       sqlite3VdbeAddOp2(v, OP_Integer, 1, iUseFlag);
104055       VdbeComment((v, "indicate data in accumulator"));
104056 
104057       /* End of the loop
104058       */
104059       if( groupBySort ){
104060         sqlite3VdbeAddOp2(v, OP_SorterNext, sAggInfo.sortingIdx, addrTopOfLoop);
104061       }else{
104062         sqlite3WhereEnd(pWInfo);
104063         sqlite3VdbeChangeToNoop(v, addrSortingIdx);
104064       }
104065 
104066       /* Output the final row of result
104067       */
104068       sqlite3VdbeAddOp2(v, OP_Gosub, regOutputRow, addrOutputRow);
104069       VdbeComment((v, "output final row"));
104070 
104071       /* Jump over the subroutines
104072       */
104073       sqlite3VdbeAddOp2(v, OP_Goto, 0, addrEnd);
104074 
104075       /* Generate a subroutine that outputs a single row of the result
104076       ** set.  This subroutine first looks at the iUseFlag.  If iUseFlag
104077       ** is less than or equal to zero, the subroutine is a no-op.  If
104078       ** the processing calls for the query to abort, this subroutine
104079       ** increments the iAbortFlag memory location before returning in
104080       ** order to signal the caller to abort.
104081       */
104082       addrSetAbort = sqlite3VdbeCurrentAddr(v);
104083       sqlite3VdbeAddOp2(v, OP_Integer, 1, iAbortFlag);
104084       VdbeComment((v, "set abort flag"));
104085       sqlite3VdbeAddOp1(v, OP_Return, regOutputRow);
104086       sqlite3VdbeResolveLabel(v, addrOutputRow);
104087       addrOutputRow = sqlite3VdbeCurrentAddr(v);
104088       sqlite3VdbeAddOp2(v, OP_IfPos, iUseFlag, addrOutputRow+2);
104089       VdbeComment((v, "Groupby result generator entry point"));
104090       sqlite3VdbeAddOp1(v, OP_Return, regOutputRow);
104091       finalizeAggFunctions(pParse, &sAggInfo);
104092       sqlite3ExprIfFalse(pParse, pHaving, addrOutputRow+1, SQLITE_JUMPIFNULL);
104093       selectInnerLoop(pParse, p, p->pEList, 0, 0, pOrderBy,
104094                       &sDistinct, pDest,
104095                       addrOutputRow+1, addrSetAbort);
104096       sqlite3VdbeAddOp1(v, OP_Return, regOutputRow);
104097       VdbeComment((v, "end groupby result generator"));
104098 
104099       /* Generate a subroutine that will reset the group-by accumulator
104100       */
104101       sqlite3VdbeResolveLabel(v, addrReset);
104102       resetAccumulator(pParse, &sAggInfo);
104103       sqlite3VdbeAddOp1(v, OP_Return, regReset);
104104      
104105     } /* endif pGroupBy.  Begin aggregate queries without GROUP BY: */
104106     else {
104107       ExprList *pDel = 0;
104108 #ifndef SQLITE_OMIT_BTREECOUNT
104109       Table *pTab;
104110       if( (pTab = isSimpleCount(p, &sAggInfo))!=0 ){
104111         /* If isSimpleCount() returns a pointer to a Table structure, then
104112         ** the SQL statement is of the form:
104113         **
104114         **   SELECT count(*) FROM <tbl>
104115         **
104116         ** where the Table structure returned represents table <tbl>.
104117         **
104118         ** This statement is so common that it is optimized specially. The
104119         ** OP_Count instruction is executed either on the intkey table that
104120         ** contains the data for table <tbl> or on one of its indexes. It
104121         ** is better to execute the op on an index, as indexes are almost
104122         ** always spread across less pages than their corresponding tables.
104123         */
104124         const int iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
104125         const int iCsr = pParse->nTab++;     /* Cursor to scan b-tree */
104126         Index *pIdx;                         /* Iterator variable */
104127         KeyInfo *pKeyInfo = 0;               /* Keyinfo for scanned index */
104128         Index *pBest = 0;                    /* Best index found so far */
104129         int iRoot = pTab->tnum;              /* Root page of scanned b-tree */
104130 
104131         sqlite3CodeVerifySchema(pParse, iDb);
104132         sqlite3TableLock(pParse, iDb, pTab->tnum, 0, pTab->zName);
104133 
104134         /* Search for the index that has the lowest scan cost.
104135         **
104136         ** (2011-04-15) Do not do a full scan of an unordered index.
104137         **
104138         ** (2013-10-03) Do not count the entries in a partial index.
104139         **
104140         ** In practice the KeyInfo structure will not be used. It is only 
104141         ** passed to keep OP_OpenRead happy.
104142         */
104143         if( !HasRowid(pTab) ) pBest = sqlite3PrimaryKeyIndex(pTab);
104144         for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
104145           if( pIdx->bUnordered==0
104146            && pIdx->szIdxRow<pTab->szTabRow
104147            && pIdx->pPartIdxWhere==0
104148            && (!pBest || pIdx->szIdxRow<pBest->szIdxRow)
104149           ){
104150             pBest = pIdx;
104151           }
104152         }
104153         if( pBest ){
104154           iRoot = pBest->tnum;
104155           pKeyInfo = sqlite3KeyInfoOfIndex(pParse, pBest);
104156         }
104157 
104158         /* Open a read-only cursor, execute the OP_Count, close the cursor. */
104159         sqlite3VdbeAddOp4Int(v, OP_OpenRead, iCsr, iRoot, iDb, 1);
104160         if( pKeyInfo ){
104161           sqlite3VdbeChangeP4(v, -1, (char *)pKeyInfo, P4_KEYINFO);
104162         }
104163         sqlite3VdbeAddOp2(v, OP_Count, iCsr, sAggInfo.aFunc[0].iMem);
104164         sqlite3VdbeAddOp1(v, OP_Close, iCsr);
104165         explainSimpleCount(pParse, pTab, pBest);
104166       }else
104167 #endif /* SQLITE_OMIT_BTREECOUNT */
104168       {
104169         /* Check if the query is of one of the following forms:
104170         **
104171         **   SELECT min(x) FROM ...
104172         **   SELECT max(x) FROM ...
104173         **
104174         ** If it is, then ask the code in where.c to attempt to sort results
104175         ** as if there was an "ORDER ON x" or "ORDER ON x DESC" clause. 
104176         ** If where.c is able to produce results sorted in this order, then
104177         ** add vdbe code to break out of the processing loop after the 
104178         ** first iteration (since the first iteration of the loop is 
104179         ** guaranteed to operate on the row with the minimum or maximum 
104180         ** value of x, the only row required).
104181         **
104182         ** A special flag must be passed to sqlite3WhereBegin() to slightly
104183         ** modify behavior as follows:
104184         **
104185         **   + If the query is a "SELECT min(x)", then the loop coded by
104186         **     where.c should not iterate over any values with a NULL value
104187         **     for x.
104188         **
104189         **   + The optimizer code in where.c (the thing that decides which
104190         **     index or indices to use) should place a different priority on 
104191         **     satisfying the 'ORDER BY' clause than it does in other cases.
104192         **     Refer to code and comments in where.c for details.
104193         */
104194         ExprList *pMinMax = 0;
104195         u8 flag = WHERE_ORDERBY_NORMAL;
104196         
104197         assert( p->pGroupBy==0 );
104198         assert( flag==0 );
104199         if( p->pHaving==0 ){
104200           flag = minMaxQuery(&sAggInfo, &pMinMax);
104201         }
104202         assert( flag==0 || (pMinMax!=0 && pMinMax->nExpr==1) );
104203 
104204         if( flag ){
104205           pMinMax = sqlite3ExprListDup(db, pMinMax, 0);
104206           pDel = pMinMax;
104207           if( pMinMax && !db->mallocFailed ){
104208             pMinMax->a[0].sortOrder = flag!=WHERE_ORDERBY_MIN ?1:0;
104209             pMinMax->a[0].pExpr->op = TK_COLUMN;
104210           }
104211         }
104212   
104213         /* This case runs if the aggregate has no GROUP BY clause.  The
104214         ** processing is much simpler since there is only a single row
104215         ** of output.
104216         */
104217         resetAccumulator(pParse, &sAggInfo);
104218         pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, pMinMax,0,flag,0);
104219         if( pWInfo==0 ){
104220           sqlite3ExprListDelete(db, pDel);
104221           goto select_end;
104222         }
104223         updateAccumulator(pParse, &sAggInfo);
104224         assert( pMinMax==0 || pMinMax->nExpr==1 );
104225         if( sqlite3WhereIsOrdered(pWInfo) ){
104226           sqlite3VdbeAddOp2(v, OP_Goto, 0, sqlite3WhereBreakLabel(pWInfo));
104227           VdbeComment((v, "%s() by index",
104228                 (flag==WHERE_ORDERBY_MIN?"min":"max")));
104229         }
104230         sqlite3WhereEnd(pWInfo);
104231         finalizeAggFunctions(pParse, &sAggInfo);
104232       }
104233 
104234       pOrderBy = 0;
104235       sqlite3ExprIfFalse(pParse, pHaving, addrEnd, SQLITE_JUMPIFNULL);
104236       selectInnerLoop(pParse, p, p->pEList, 0, 0, 0, 0, 
104237                       pDest, addrEnd, addrEnd);
104238       sqlite3ExprListDelete(db, pDel);
104239     }
104240     sqlite3VdbeResolveLabel(v, addrEnd);
104241     
104242   } /* endif aggregate query */
104243 
104244   if( sDistinct.eTnctType==WHERE_DISTINCT_UNORDERED ){
104245     explainTempTable(pParse, "DISTINCT");
104246   }
104247 
104248   /* If there is an ORDER BY clause, then we need to sort the results
104249   ** and send them to the callback one by one.
104250   */
104251   if( pOrderBy ){
104252     explainTempTable(pParse, "ORDER BY");
104253     generateSortTail(pParse, p, v, pEList->nExpr, pDest);
104254   }
104255 
104256   /* Jump here to skip this query
104257   */
104258   sqlite3VdbeResolveLabel(v, iEnd);
104259 
104260   /* The SELECT was successfully coded.   Set the return code to 0
104261   ** to indicate no errors.
104262   */
104263   rc = 0;
104264 
104265   /* Control jumps to here if an error is encountered above, or upon
104266   ** successful coding of the SELECT.
104267   */
104268 select_end:
104269   explainSetInteger(pParse->iSelectId, iRestoreSelectId);
104270 
104271   /* Identify column names if results of the SELECT are to be output.
104272   */
104273   if( rc==SQLITE_OK && pDest->eDest==SRT_Output ){
104274     generateColumnNames(pParse, pTabList, pEList);
104275   }
104276 
104277   sqlite3DbFree(db, sAggInfo.aCol);
104278   sqlite3DbFree(db, sAggInfo.aFunc);
104279   return rc;
104280 }
104281 
104282 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
104283 /*
104284 ** Generate a human-readable description of a the Select object.
104285 */
104286 static void explainOneSelect(Vdbe *pVdbe, Select *p){
104287   sqlite3ExplainPrintf(pVdbe, "SELECT ");
104288   if( p->selFlags & (SF_Distinct|SF_Aggregate) ){
104289     if( p->selFlags & SF_Distinct ){
104290       sqlite3ExplainPrintf(pVdbe, "DISTINCT ");
104291     }
104292     if( p->selFlags & SF_Aggregate ){
104293       sqlite3ExplainPrintf(pVdbe, "agg_flag ");
104294     }
104295     sqlite3ExplainNL(pVdbe);
104296     sqlite3ExplainPrintf(pVdbe, "   ");
104297   }
104298   sqlite3ExplainExprList(pVdbe, p->pEList);
104299   sqlite3ExplainNL(pVdbe);
104300   if( p->pSrc && p->pSrc->nSrc ){
104301     int i;
104302     sqlite3ExplainPrintf(pVdbe, "FROM ");
104303     sqlite3ExplainPush(pVdbe);
104304     for(i=0; i<p->pSrc->nSrc; i++){
104305       struct SrcList_item *pItem = &p->pSrc->a[i];
104306       sqlite3ExplainPrintf(pVdbe, "{%d,*} = ", pItem->iCursor);
104307       if( pItem->pSelect ){
104308         sqlite3ExplainSelect(pVdbe, pItem->pSelect);
104309         if( pItem->pTab ){
104310           sqlite3ExplainPrintf(pVdbe, " (tabname=%s)", pItem->pTab->zName);
104311         }
104312       }else if( pItem->zName ){
104313         sqlite3ExplainPrintf(pVdbe, "%s", pItem->zName);
104314       }
104315       if( pItem->zAlias ){
104316         sqlite3ExplainPrintf(pVdbe, " (AS %s)", pItem->zAlias);
104317       }
104318       if( pItem->jointype & JT_LEFT ){
104319         sqlite3ExplainPrintf(pVdbe, " LEFT-JOIN");
104320       }
104321       sqlite3ExplainNL(pVdbe);
104322     }
104323     sqlite3ExplainPop(pVdbe);
104324   }
104325   if( p->pWhere ){
104326     sqlite3ExplainPrintf(pVdbe, "WHERE ");
104327     sqlite3ExplainExpr(pVdbe, p->pWhere);
104328     sqlite3ExplainNL(pVdbe);
104329   }
104330   if( p->pGroupBy ){
104331     sqlite3ExplainPrintf(pVdbe, "GROUPBY ");
104332     sqlite3ExplainExprList(pVdbe, p->pGroupBy);
104333     sqlite3ExplainNL(pVdbe);
104334   }
104335   if( p->pHaving ){
104336     sqlite3ExplainPrintf(pVdbe, "HAVING ");
104337     sqlite3ExplainExpr(pVdbe, p->pHaving);
104338     sqlite3ExplainNL(pVdbe);
104339   }
104340   if( p->pOrderBy ){
104341     sqlite3ExplainPrintf(pVdbe, "ORDERBY ");
104342     sqlite3ExplainExprList(pVdbe, p->pOrderBy);
104343     sqlite3ExplainNL(pVdbe);
104344   }
104345   if( p->pLimit ){
104346     sqlite3ExplainPrintf(pVdbe, "LIMIT ");
104347     sqlite3ExplainExpr(pVdbe, p->pLimit);
104348     sqlite3ExplainNL(pVdbe);
104349   }
104350   if( p->pOffset ){
104351     sqlite3ExplainPrintf(pVdbe, "OFFSET ");
104352     sqlite3ExplainExpr(pVdbe, p->pOffset);
104353     sqlite3ExplainNL(pVdbe);
104354   }
104355 }
104356 SQLITE_PRIVATE void sqlite3ExplainSelect(Vdbe *pVdbe, Select *p){
104357   if( p==0 ){
104358     sqlite3ExplainPrintf(pVdbe, "(null-select)");
104359     return;
104360   }
104361   while( p->pPrior ){
104362     p->pPrior->pNext = p;
104363     p = p->pPrior;
104364   }
104365   sqlite3ExplainPush(pVdbe);
104366   while( p ){
104367     explainOneSelect(pVdbe, p);
104368     p = p->pNext;
104369     if( p==0 ) break;
104370     sqlite3ExplainNL(pVdbe);
104371     sqlite3ExplainPrintf(pVdbe, "%s\n", selectOpName(p->op));
104372   }
104373   sqlite3ExplainPrintf(pVdbe, "END");
104374   sqlite3ExplainPop(pVdbe);
104375 }
104376 
104377 /* End of the structure debug printing code
104378 *****************************************************************************/
104379 #endif /* defined(SQLITE_ENABLE_TREE_EXPLAIN) */
104380 
104381 /************** End of select.c **********************************************/
104382 /************** Begin file table.c *******************************************/
104383 /*
104384 ** 2001 September 15
104385 **
104386 ** The author disclaims copyright to this source code.  In place of
104387 ** a legal notice, here is a blessing:
104388 **
104389 **    May you do good and not evil.
104390 **    May you find forgiveness for yourself and forgive others.
104391 **    May you share freely, never taking more than you give.
104392 **
104393 *************************************************************************
104394 ** This file contains the sqlite3_get_table() and sqlite3_free_table()
104395 ** interface routines.  These are just wrappers around the main
104396 ** interface routine of sqlite3_exec().
104397 **
104398 ** These routines are in a separate files so that they will not be linked
104399 ** if they are not used.
104400 */
104401 /* #include <stdlib.h> */
104402 /* #include <string.h> */
104403 
104404 #ifndef SQLITE_OMIT_GET_TABLE
104405 
104406 /*
104407 ** This structure is used to pass data from sqlite3_get_table() through
104408 ** to the callback function is uses to build the result.
104409 */
104410 typedef struct TabResult {
104411   char **azResult;   /* Accumulated output */
104412   char *zErrMsg;     /* Error message text, if an error occurs */
104413   int nAlloc;        /* Slots allocated for azResult[] */
104414   int nRow;          /* Number of rows in the result */
104415   int nColumn;       /* Number of columns in the result */
104416   int nData;         /* Slots used in azResult[].  (nRow+1)*nColumn */
104417   int rc;            /* Return code from sqlite3_exec() */
104418 } TabResult;
104419 
104420 /*
104421 ** This routine is called once for each row in the result table.  Its job
104422 ** is to fill in the TabResult structure appropriately, allocating new
104423 ** memory as necessary.
104424 */
104425 static int sqlite3_get_table_cb(void *pArg, int nCol, char **argv, char **colv){
104426   TabResult *p = (TabResult*)pArg;  /* Result accumulator */
104427   int need;                         /* Slots needed in p->azResult[] */
104428   int i;                            /* Loop counter */
104429   char *z;                          /* A single column of result */
104430 
104431   /* Make sure there is enough space in p->azResult to hold everything
104432   ** we need to remember from this invocation of the callback.
104433   */
104434   if( p->nRow==0 && argv!=0 ){
104435     need = nCol*2;
104436   }else{
104437     need = nCol;
104438   }
104439   if( p->nData + need > p->nAlloc ){
104440     char **azNew;
104441     p->nAlloc = p->nAlloc*2 + need;
104442     azNew = sqlite3_realloc( p->azResult, sizeof(char*)*p->nAlloc );
104443     if( azNew==0 ) goto malloc_failed;
104444     p->azResult = azNew;
104445   }
104446 
104447   /* If this is the first row, then generate an extra row containing
104448   ** the names of all columns.
104449   */
104450   if( p->nRow==0 ){
104451     p->nColumn = nCol;
104452     for(i=0; i<nCol; i++){
104453       z = sqlite3_mprintf("%s", colv[i]);
104454       if( z==0 ) goto malloc_failed;
104455       p->azResult[p->nData++] = z;
104456     }
104457   }else if( p->nColumn!=nCol ){
104458     sqlite3_free(p->zErrMsg);
104459     p->zErrMsg = sqlite3_mprintf(
104460        "sqlite3_get_table() called with two or more incompatible queries"
104461     );
104462     p->rc = SQLITE_ERROR;
104463     return 1;
104464   }
104465 
104466   /* Copy over the row data
104467   */
104468   if( argv!=0 ){
104469     for(i=0; i<nCol; i++){
104470       if( argv[i]==0 ){
104471         z = 0;
104472       }else{
104473         int n = sqlite3Strlen30(argv[i])+1;
104474         z = sqlite3_malloc( n );
104475         if( z==0 ) goto malloc_failed;
104476         memcpy(z, argv[i], n);
104477       }
104478       p->azResult[p->nData++] = z;
104479     }
104480     p->nRow++;
104481   }
104482   return 0;
104483 
104484 malloc_failed:
104485   p->rc = SQLITE_NOMEM;
104486   return 1;
104487 }
104488 
104489 /*
104490 ** Query the database.  But instead of invoking a callback for each row,
104491 ** malloc() for space to hold the result and return the entire results
104492 ** at the conclusion of the call.
104493 **
104494 ** The result that is written to ***pazResult is held in memory obtained
104495 ** from malloc().  But the caller cannot free this memory directly.  
104496 ** Instead, the entire table should be passed to sqlite3_free_table() when
104497 ** the calling procedure is finished using it.
104498 */
104499 SQLITE_API int sqlite3_get_table(
104500   sqlite3 *db,                /* The database on which the SQL executes */
104501   const char *zSql,           /* The SQL to be executed */
104502   char ***pazResult,          /* Write the result table here */
104503   int *pnRow,                 /* Write the number of rows in the result here */
104504   int *pnColumn,              /* Write the number of columns of result here */
104505   char **pzErrMsg             /* Write error messages here */
104506 ){
104507   int rc;
104508   TabResult res;
104509 
104510   *pazResult = 0;
104511   if( pnColumn ) *pnColumn = 0;
104512   if( pnRow ) *pnRow = 0;
104513   if( pzErrMsg ) *pzErrMsg = 0;
104514   res.zErrMsg = 0;
104515   res.nRow = 0;
104516   res.nColumn = 0;
104517   res.nData = 1;
104518   res.nAlloc = 20;
104519   res.rc = SQLITE_OK;
104520   res.azResult = sqlite3_malloc(sizeof(char*)*res.nAlloc );
104521   if( res.azResult==0 ){
104522      db->errCode = SQLITE_NOMEM;
104523      return SQLITE_NOMEM;
104524   }
104525   res.azResult[0] = 0;
104526   rc = sqlite3_exec(db, zSql, sqlite3_get_table_cb, &res, pzErrMsg);
104527   assert( sizeof(res.azResult[0])>= sizeof(res.nData) );
104528   res.azResult[0] = SQLITE_INT_TO_PTR(res.nData);
104529   if( (rc&0xff)==SQLITE_ABORT ){
104530     sqlite3_free_table(&res.azResult[1]);
104531     if( res.zErrMsg ){
104532       if( pzErrMsg ){
104533         sqlite3_free(*pzErrMsg);
104534         *pzErrMsg = sqlite3_mprintf("%s",res.zErrMsg);
104535       }
104536       sqlite3_free(res.zErrMsg);
104537     }
104538     db->errCode = res.rc;  /* Assume 32-bit assignment is atomic */
104539     return res.rc;
104540   }
104541   sqlite3_free(res.zErrMsg);
104542   if( rc!=SQLITE_OK ){
104543     sqlite3_free_table(&res.azResult[1]);
104544     return rc;
104545   }
104546   if( res.nAlloc>res.nData ){
104547     char **azNew;
104548     azNew = sqlite3_realloc( res.azResult, sizeof(char*)*res.nData );
104549     if( azNew==0 ){
104550       sqlite3_free_table(&res.azResult[1]);
104551       db->errCode = SQLITE_NOMEM;
104552       return SQLITE_NOMEM;
104553     }
104554     res.azResult = azNew;
104555   }
104556   *pazResult = &res.azResult[1];
104557   if( pnColumn ) *pnColumn = res.nColumn;
104558   if( pnRow ) *pnRow = res.nRow;
104559   return rc;
104560 }
104561 
104562 /*
104563 ** This routine frees the space the sqlite3_get_table() malloced.
104564 */
104565 SQLITE_API void sqlite3_free_table(
104566   char **azResult            /* Result returned from from sqlite3_get_table() */
104567 ){
104568   if( azResult ){
104569     int i, n;
104570     azResult--;
104571     assert( azResult!=0 );
104572     n = SQLITE_PTR_TO_INT(azResult[0]);
104573     for(i=1; i<n; i++){ if( azResult[i] ) sqlite3_free(azResult[i]); }
104574     sqlite3_free(azResult);
104575   }
104576 }
104577 
104578 #endif /* SQLITE_OMIT_GET_TABLE */
104579 
104580 /************** End of table.c ***********************************************/
104581 /************** Begin file trigger.c *****************************************/
104582 /*
104583 **
104584 ** The author disclaims copyright to this source code.  In place of
104585 ** a legal notice, here is a blessing:
104586 **
104587 **    May you do good and not evil.
104588 **    May you find forgiveness for yourself and forgive others.
104589 **    May you share freely, never taking more than you give.
104590 **
104591 *************************************************************************
104592 ** This file contains the implementation for TRIGGERs
104593 */
104594 
104595 #ifndef SQLITE_OMIT_TRIGGER
104596 /*
104597 ** Delete a linked list of TriggerStep structures.
104598 */
104599 SQLITE_PRIVATE void sqlite3DeleteTriggerStep(sqlite3 *db, TriggerStep *pTriggerStep){
104600   while( pTriggerStep ){
104601     TriggerStep * pTmp = pTriggerStep;
104602     pTriggerStep = pTriggerStep->pNext;
104603 
104604     sqlite3ExprDelete(db, pTmp->pWhere);
104605     sqlite3ExprListDelete(db, pTmp->pExprList);
104606     sqlite3SelectDelete(db, pTmp->pSelect);
104607     sqlite3IdListDelete(db, pTmp->pIdList);
104608 
104609     sqlite3DbFree(db, pTmp);
104610   }
104611 }
104612 
104613 /*
104614 ** Given table pTab, return a list of all the triggers attached to 
104615 ** the table. The list is connected by Trigger.pNext pointers.
104616 **
104617 ** All of the triggers on pTab that are in the same database as pTab
104618 ** are already attached to pTab->pTrigger.  But there might be additional
104619 ** triggers on pTab in the TEMP schema.  This routine prepends all
104620 ** TEMP triggers on pTab to the beginning of the pTab->pTrigger list
104621 ** and returns the combined list.
104622 **
104623 ** To state it another way:  This routine returns a list of all triggers
104624 ** that fire off of pTab.  The list will include any TEMP triggers on
104625 ** pTab as well as the triggers lised in pTab->pTrigger.
104626 */
104627 SQLITE_PRIVATE Trigger *sqlite3TriggerList(Parse *pParse, Table *pTab){
104628   Schema * const pTmpSchema = pParse->db->aDb[1].pSchema;
104629   Trigger *pList = 0;                  /* List of triggers to return */
104630 
104631   if( pParse->disableTriggers ){
104632     return 0;
104633   }
104634 
104635   if( pTmpSchema!=pTab->pSchema ){
104636     HashElem *p;
104637     assert( sqlite3SchemaMutexHeld(pParse->db, 0, pTmpSchema) );
104638     for(p=sqliteHashFirst(&pTmpSchema->trigHash); p; p=sqliteHashNext(p)){
104639       Trigger *pTrig = (Trigger *)sqliteHashData(p);
104640       if( pTrig->pTabSchema==pTab->pSchema
104641        && 0==sqlite3StrICmp(pTrig->table, pTab->zName) 
104642       ){
104643         pTrig->pNext = (pList ? pList : pTab->pTrigger);
104644         pList = pTrig;
104645       }
104646     }
104647   }
104648 
104649   return (pList ? pList : pTab->pTrigger);
104650 }
104651 
104652 /*
104653 ** This is called by the parser when it sees a CREATE TRIGGER statement
104654 ** up to the point of the BEGIN before the trigger actions.  A Trigger
104655 ** structure is generated based on the information available and stored
104656 ** in pParse->pNewTrigger.  After the trigger actions have been parsed, the
104657 ** sqlite3FinishTrigger() function is called to complete the trigger
104658 ** construction process.
104659 */
104660 SQLITE_PRIVATE void sqlite3BeginTrigger(
104661   Parse *pParse,      /* The parse context of the CREATE TRIGGER statement */
104662   Token *pName1,      /* The name of the trigger */
104663   Token *pName2,      /* The name of the trigger */
104664   int tr_tm,          /* One of TK_BEFORE, TK_AFTER, TK_INSTEAD */
104665   int op,             /* One of TK_INSERT, TK_UPDATE, TK_DELETE */
104666   IdList *pColumns,   /* column list if this is an UPDATE OF trigger */
104667   SrcList *pTableName,/* The name of the table/view the trigger applies to */
104668   Expr *pWhen,        /* WHEN clause */
104669   int isTemp,         /* True if the TEMPORARY keyword is present */
104670   int noErr           /* Suppress errors if the trigger already exists */
104671 ){
104672   Trigger *pTrigger = 0;  /* The new trigger */
104673   Table *pTab;            /* Table that the trigger fires off of */
104674   char *zName = 0;        /* Name of the trigger */
104675   sqlite3 *db = pParse->db;  /* The database connection */
104676   int iDb;                /* The database to store the trigger in */
104677   Token *pName;           /* The unqualified db name */
104678   DbFixer sFix;           /* State vector for the DB fixer */
104679   int iTabDb;             /* Index of the database holding pTab */
104680 
104681   assert( pName1!=0 );   /* pName1->z might be NULL, but not pName1 itself */
104682   assert( pName2!=0 );
104683   assert( op==TK_INSERT || op==TK_UPDATE || op==TK_DELETE );
104684   assert( op>0 && op<0xff );
104685   if( isTemp ){
104686     /* If TEMP was specified, then the trigger name may not be qualified. */
104687     if( pName2->n>0 ){
104688       sqlite3ErrorMsg(pParse, "temporary trigger may not have qualified name");
104689       goto trigger_cleanup;
104690     }
104691     iDb = 1;
104692     pName = pName1;
104693   }else{
104694     /* Figure out the db that the trigger will be created in */
104695     iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pName);
104696     if( iDb<0 ){
104697       goto trigger_cleanup;
104698     }
104699   }
104700   if( !pTableName || db->mallocFailed ){
104701     goto trigger_cleanup;
104702   }
104703 
104704   /* A long-standing parser bug is that this syntax was allowed:
104705   **
104706   **    CREATE TRIGGER attached.demo AFTER INSERT ON attached.tab ....
104707   **                                                 ^^^^^^^^
104708   **
104709   ** To maintain backwards compatibility, ignore the database
104710   ** name on pTableName if we are reparsing our of SQLITE_MASTER.
104711   */
104712   if( db->init.busy && iDb!=1 ){
104713     sqlite3DbFree(db, pTableName->a[0].zDatabase);
104714     pTableName->a[0].zDatabase = 0;
104715   }
104716 
104717   /* If the trigger name was unqualified, and the table is a temp table,
104718   ** then set iDb to 1 to create the trigger in the temporary database.
104719   ** If sqlite3SrcListLookup() returns 0, indicating the table does not
104720   ** exist, the error is caught by the block below.
104721   */
104722   pTab = sqlite3SrcListLookup(pParse, pTableName);
104723   if( db->init.busy==0 && pName2->n==0 && pTab
104724         && pTab->pSchema==db->aDb[1].pSchema ){
104725     iDb = 1;
104726   }
104727 
104728   /* Ensure the table name matches database name and that the table exists */
104729   if( db->mallocFailed ) goto trigger_cleanup;
104730   assert( pTableName->nSrc==1 );
104731   sqlite3FixInit(&sFix, pParse, iDb, "trigger", pName);
104732   if( sqlite3FixSrcList(&sFix, pTableName) ){
104733     goto trigger_cleanup;
104734   }
104735   pTab = sqlite3SrcListLookup(pParse, pTableName);
104736   if( !pTab ){
104737     /* The table does not exist. */
104738     if( db->init.iDb==1 ){
104739       /* Ticket #3810.
104740       ** Normally, whenever a table is dropped, all associated triggers are
104741       ** dropped too.  But if a TEMP trigger is created on a non-TEMP table
104742       ** and the table is dropped by a different database connection, the
104743       ** trigger is not visible to the database connection that does the
104744       ** drop so the trigger cannot be dropped.  This results in an
104745       ** "orphaned trigger" - a trigger whose associated table is missing.
104746       */
104747       db->init.orphanTrigger = 1;
104748     }
104749     goto trigger_cleanup;
104750   }
104751   if( IsVirtual(pTab) ){
104752     sqlite3ErrorMsg(pParse, "cannot create triggers on virtual tables");
104753     goto trigger_cleanup;
104754   }
104755 
104756   /* Check that the trigger name is not reserved and that no trigger of the
104757   ** specified name exists */
104758   zName = sqlite3NameFromToken(db, pName);
104759   if( !zName || SQLITE_OK!=sqlite3CheckObjectName(pParse, zName) ){
104760     goto trigger_cleanup;
104761   }
104762   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
104763   if( sqlite3HashFind(&(db->aDb[iDb].pSchema->trigHash),
104764                       zName, sqlite3Strlen30(zName)) ){
104765     if( !noErr ){
104766       sqlite3ErrorMsg(pParse, "trigger %T already exists", pName);
104767     }else{
104768       assert( !db->init.busy );
104769       sqlite3CodeVerifySchema(pParse, iDb);
104770     }
104771     goto trigger_cleanup;
104772   }
104773 
104774   /* Do not create a trigger on a system table */
104775   if( sqlite3StrNICmp(pTab->zName, "sqlite_", 7)==0 ){
104776     sqlite3ErrorMsg(pParse, "cannot create trigger on system table");
104777     pParse->nErr++;
104778     goto trigger_cleanup;
104779   }
104780 
104781   /* INSTEAD of triggers are only for views and views only support INSTEAD
104782   ** of triggers.
104783   */
104784   if( pTab->pSelect && tr_tm!=TK_INSTEAD ){
104785     sqlite3ErrorMsg(pParse, "cannot create %s trigger on view: %S", 
104786         (tr_tm == TK_BEFORE)?"BEFORE":"AFTER", pTableName, 0);
104787     goto trigger_cleanup;
104788   }
104789   if( !pTab->pSelect && tr_tm==TK_INSTEAD ){
104790     sqlite3ErrorMsg(pParse, "cannot create INSTEAD OF"
104791         " trigger on table: %S", pTableName, 0);
104792     goto trigger_cleanup;
104793   }
104794   iTabDb = sqlite3SchemaToIndex(db, pTab->pSchema);
104795 
104796 #ifndef SQLITE_OMIT_AUTHORIZATION
104797   {
104798     int code = SQLITE_CREATE_TRIGGER;
104799     const char *zDb = db->aDb[iTabDb].zName;
104800     const char *zDbTrig = isTemp ? db->aDb[1].zName : zDb;
104801     if( iTabDb==1 || isTemp ) code = SQLITE_CREATE_TEMP_TRIGGER;
104802     if( sqlite3AuthCheck(pParse, code, zName, pTab->zName, zDbTrig) ){
104803       goto trigger_cleanup;
104804     }
104805     if( sqlite3AuthCheck(pParse, SQLITE_INSERT, SCHEMA_TABLE(iTabDb),0,zDb)){
104806       goto trigger_cleanup;
104807     }
104808   }
104809 #endif
104810 
104811   /* INSTEAD OF triggers can only appear on views and BEFORE triggers
104812   ** cannot appear on views.  So we might as well translate every
104813   ** INSTEAD OF trigger into a BEFORE trigger.  It simplifies code
104814   ** elsewhere.
104815   */
104816   if (tr_tm == TK_INSTEAD){
104817     tr_tm = TK_BEFORE;
104818   }
104819 
104820   /* Build the Trigger object */
104821   pTrigger = (Trigger*)sqlite3DbMallocZero(db, sizeof(Trigger));
104822   if( pTrigger==0 ) goto trigger_cleanup;
104823   pTrigger->zName = zName;
104824   zName = 0;
104825   pTrigger->table = sqlite3DbStrDup(db, pTableName->a[0].zName);
104826   pTrigger->pSchema = db->aDb[iDb].pSchema;
104827   pTrigger->pTabSchema = pTab->pSchema;
104828   pTrigger->op = (u8)op;
104829   pTrigger->tr_tm = tr_tm==TK_BEFORE ? TRIGGER_BEFORE : TRIGGER_AFTER;
104830   pTrigger->pWhen = sqlite3ExprDup(db, pWhen, EXPRDUP_REDUCE);
104831   pTrigger->pColumns = sqlite3IdListDup(db, pColumns);
104832   assert( pParse->pNewTrigger==0 );
104833   pParse->pNewTrigger = pTrigger;
104834 
104835 trigger_cleanup:
104836   sqlite3DbFree(db, zName);
104837   sqlite3SrcListDelete(db, pTableName);
104838   sqlite3IdListDelete(db, pColumns);
104839   sqlite3ExprDelete(db, pWhen);
104840   if( !pParse->pNewTrigger ){
104841     sqlite3DeleteTrigger(db, pTrigger);
104842   }else{
104843     assert( pParse->pNewTrigger==pTrigger );
104844   }
104845 }
104846 
104847 /*
104848 ** This routine is called after all of the trigger actions have been parsed
104849 ** in order to complete the process of building the trigger.
104850 */
104851 SQLITE_PRIVATE void sqlite3FinishTrigger(
104852   Parse *pParse,          /* Parser context */
104853   TriggerStep *pStepList, /* The triggered program */
104854   Token *pAll             /* Token that describes the complete CREATE TRIGGER */
104855 ){
104856   Trigger *pTrig = pParse->pNewTrigger;   /* Trigger being finished */
104857   char *zName;                            /* Name of trigger */
104858   sqlite3 *db = pParse->db;               /* The database */
104859   DbFixer sFix;                           /* Fixer object */
104860   int iDb;                                /* Database containing the trigger */
104861   Token nameToken;                        /* Trigger name for error reporting */
104862 
104863   pParse->pNewTrigger = 0;
104864   if( NEVER(pParse->nErr) || !pTrig ) goto triggerfinish_cleanup;
104865   zName = pTrig->zName;
104866   iDb = sqlite3SchemaToIndex(pParse->db, pTrig->pSchema);
104867   pTrig->step_list = pStepList;
104868   while( pStepList ){
104869     pStepList->pTrig = pTrig;
104870     pStepList = pStepList->pNext;
104871   }
104872   nameToken.z = pTrig->zName;
104873   nameToken.n = sqlite3Strlen30(nameToken.z);
104874   sqlite3FixInit(&sFix, pParse, iDb, "trigger", &nameToken);
104875   if( sqlite3FixTriggerStep(&sFix, pTrig->step_list) 
104876    || sqlite3FixExpr(&sFix, pTrig->pWhen) 
104877   ){
104878     goto triggerfinish_cleanup;
104879   }
104880 
104881   /* if we are not initializing,
104882   ** build the sqlite_master entry
104883   */
104884   if( !db->init.busy ){
104885     Vdbe *v;
104886     char *z;
104887 
104888     /* Make an entry in the sqlite_master table */
104889     v = sqlite3GetVdbe(pParse);
104890     if( v==0 ) goto triggerfinish_cleanup;
104891     sqlite3BeginWriteOperation(pParse, 0, iDb);
104892     z = sqlite3DbStrNDup(db, (char*)pAll->z, pAll->n);
104893     sqlite3NestedParse(pParse,
104894        "INSERT INTO %Q.%s VALUES('trigger',%Q,%Q,0,'CREATE TRIGGER %q')",
104895        db->aDb[iDb].zName, SCHEMA_TABLE(iDb), zName,
104896        pTrig->table, z);
104897     sqlite3DbFree(db, z);
104898     sqlite3ChangeCookie(pParse, iDb);
104899     sqlite3VdbeAddParseSchemaOp(v, iDb,
104900         sqlite3MPrintf(db, "type='trigger' AND name='%q'", zName));
104901   }
104902 
104903   if( db->init.busy ){
104904     Trigger *pLink = pTrig;
104905     Hash *pHash = &db->aDb[iDb].pSchema->trigHash;
104906     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
104907     pTrig = sqlite3HashInsert(pHash, zName, sqlite3Strlen30(zName), pTrig);
104908     if( pTrig ){
104909       db->mallocFailed = 1;
104910     }else if( pLink->pSchema==pLink->pTabSchema ){
104911       Table *pTab;
104912       int n = sqlite3Strlen30(pLink->table);
104913       pTab = sqlite3HashFind(&pLink->pTabSchema->tblHash, pLink->table, n);
104914       assert( pTab!=0 );
104915       pLink->pNext = pTab->pTrigger;
104916       pTab->pTrigger = pLink;
104917     }
104918   }
104919 
104920 triggerfinish_cleanup:
104921   sqlite3DeleteTrigger(db, pTrig);
104922   assert( !pParse->pNewTrigger );
104923   sqlite3DeleteTriggerStep(db, pStepList);
104924 }
104925 
104926 /*
104927 ** Turn a SELECT statement (that the pSelect parameter points to) into
104928 ** a trigger step.  Return a pointer to a TriggerStep structure.
104929 **
104930 ** The parser calls this routine when it finds a SELECT statement in
104931 ** body of a TRIGGER.  
104932 */
104933 SQLITE_PRIVATE TriggerStep *sqlite3TriggerSelectStep(sqlite3 *db, Select *pSelect){
104934   TriggerStep *pTriggerStep = sqlite3DbMallocZero(db, sizeof(TriggerStep));
104935   if( pTriggerStep==0 ) {
104936     sqlite3SelectDelete(db, pSelect);
104937     return 0;
104938   }
104939   pTriggerStep->op = TK_SELECT;
104940   pTriggerStep->pSelect = pSelect;
104941   pTriggerStep->orconf = OE_Default;
104942   return pTriggerStep;
104943 }
104944 
104945 /*
104946 ** Allocate space to hold a new trigger step.  The allocated space
104947 ** holds both the TriggerStep object and the TriggerStep.target.z string.
104948 **
104949 ** If an OOM error occurs, NULL is returned and db->mallocFailed is set.
104950 */
104951 static TriggerStep *triggerStepAllocate(
104952   sqlite3 *db,                /* Database connection */
104953   u8 op,                      /* Trigger opcode */
104954   Token *pName                /* The target name */
104955 ){
104956   TriggerStep *pTriggerStep;
104957 
104958   pTriggerStep = sqlite3DbMallocZero(db, sizeof(TriggerStep) + pName->n);
104959   if( pTriggerStep ){
104960     char *z = (char*)&pTriggerStep[1];
104961     memcpy(z, pName->z, pName->n);
104962     pTriggerStep->target.z = z;
104963     pTriggerStep->target.n = pName->n;
104964     pTriggerStep->op = op;
104965   }
104966   return pTriggerStep;
104967 }
104968 
104969 /*
104970 ** Build a trigger step out of an INSERT statement.  Return a pointer
104971 ** to the new trigger step.
104972 **
104973 ** The parser calls this routine when it sees an INSERT inside the
104974 ** body of a trigger.
104975 */
104976 SQLITE_PRIVATE TriggerStep *sqlite3TriggerInsertStep(
104977   sqlite3 *db,        /* The database connection */
104978   Token *pTableName,  /* Name of the table into which we insert */
104979   IdList *pColumn,    /* List of columns in pTableName to insert into */
104980   ExprList *pEList,   /* The VALUE clause: a list of values to be inserted */
104981   Select *pSelect,    /* A SELECT statement that supplies values */
104982   u8 orconf           /* The conflict algorithm (OE_Abort, OE_Replace, etc.) */
104983 ){
104984   TriggerStep *pTriggerStep;
104985 
104986   assert(pEList == 0 || pSelect == 0);
104987   assert(pEList != 0 || pSelect != 0 || db->mallocFailed);
104988 
104989   pTriggerStep = triggerStepAllocate(db, TK_INSERT, pTableName);
104990   if( pTriggerStep ){
104991     pTriggerStep->pSelect = sqlite3SelectDup(db, pSelect, EXPRDUP_REDUCE);
104992     pTriggerStep->pIdList = pColumn;
104993     pTriggerStep->pExprList = sqlite3ExprListDup(db, pEList, EXPRDUP_REDUCE);
104994     pTriggerStep->orconf = orconf;
104995   }else{
104996     sqlite3IdListDelete(db, pColumn);
104997   }
104998   sqlite3ExprListDelete(db, pEList);
104999   sqlite3SelectDelete(db, pSelect);
105000 
105001   return pTriggerStep;
105002 }
105003 
105004 /*
105005 ** Construct a trigger step that implements an UPDATE statement and return
105006 ** a pointer to that trigger step.  The parser calls this routine when it
105007 ** sees an UPDATE statement inside the body of a CREATE TRIGGER.
105008 */
105009 SQLITE_PRIVATE TriggerStep *sqlite3TriggerUpdateStep(
105010   sqlite3 *db,         /* The database connection */
105011   Token *pTableName,   /* Name of the table to be updated */
105012   ExprList *pEList,    /* The SET clause: list of column and new values */
105013   Expr *pWhere,        /* The WHERE clause */
105014   u8 orconf            /* The conflict algorithm. (OE_Abort, OE_Ignore, etc) */
105015 ){
105016   TriggerStep *pTriggerStep;
105017 
105018   pTriggerStep = triggerStepAllocate(db, TK_UPDATE, pTableName);
105019   if( pTriggerStep ){
105020     pTriggerStep->pExprList = sqlite3ExprListDup(db, pEList, EXPRDUP_REDUCE);
105021     pTriggerStep->pWhere = sqlite3ExprDup(db, pWhere, EXPRDUP_REDUCE);
105022     pTriggerStep->orconf = orconf;
105023   }
105024   sqlite3ExprListDelete(db, pEList);
105025   sqlite3ExprDelete(db, pWhere);
105026   return pTriggerStep;
105027 }
105028 
105029 /*
105030 ** Construct a trigger step that implements a DELETE statement and return
105031 ** a pointer to that trigger step.  The parser calls this routine when it
105032 ** sees a DELETE statement inside the body of a CREATE TRIGGER.
105033 */
105034 SQLITE_PRIVATE TriggerStep *sqlite3TriggerDeleteStep(
105035   sqlite3 *db,            /* Database connection */
105036   Token *pTableName,      /* The table from which rows are deleted */
105037   Expr *pWhere            /* The WHERE clause */
105038 ){
105039   TriggerStep *pTriggerStep;
105040 
105041   pTriggerStep = triggerStepAllocate(db, TK_DELETE, pTableName);
105042   if( pTriggerStep ){
105043     pTriggerStep->pWhere = sqlite3ExprDup(db, pWhere, EXPRDUP_REDUCE);
105044     pTriggerStep->orconf = OE_Default;
105045   }
105046   sqlite3ExprDelete(db, pWhere);
105047   return pTriggerStep;
105048 }
105049 
105050 /* 
105051 ** Recursively delete a Trigger structure
105052 */
105053 SQLITE_PRIVATE void sqlite3DeleteTrigger(sqlite3 *db, Trigger *pTrigger){
105054   if( pTrigger==0 ) return;
105055   sqlite3DeleteTriggerStep(db, pTrigger->step_list);
105056   sqlite3DbFree(db, pTrigger->zName);
105057   sqlite3DbFree(db, pTrigger->table);
105058   sqlite3ExprDelete(db, pTrigger->pWhen);
105059   sqlite3IdListDelete(db, pTrigger->pColumns);
105060   sqlite3DbFree(db, pTrigger);
105061 }
105062 
105063 /*
105064 ** This function is called to drop a trigger from the database schema. 
105065 **
105066 ** This may be called directly from the parser and therefore identifies
105067 ** the trigger by name.  The sqlite3DropTriggerPtr() routine does the
105068 ** same job as this routine except it takes a pointer to the trigger
105069 ** instead of the trigger name.
105070 **/
105071 SQLITE_PRIVATE void sqlite3DropTrigger(Parse *pParse, SrcList *pName, int noErr){
105072   Trigger *pTrigger = 0;
105073   int i;
105074   const char *zDb;
105075   const char *zName;
105076   int nName;
105077   sqlite3 *db = pParse->db;
105078 
105079   if( db->mallocFailed ) goto drop_trigger_cleanup;
105080   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
105081     goto drop_trigger_cleanup;
105082   }
105083 
105084   assert( pName->nSrc==1 );
105085   zDb = pName->a[0].zDatabase;
105086   zName = pName->a[0].zName;
105087   nName = sqlite3Strlen30(zName);
105088   assert( zDb!=0 || sqlite3BtreeHoldsAllMutexes(db) );
105089   for(i=OMIT_TEMPDB; i<db->nDb; i++){
105090     int j = (i<2) ? i^1 : i;  /* Search TEMP before MAIN */
105091     if( zDb && sqlite3StrICmp(db->aDb[j].zName, zDb) ) continue;
105092     assert( sqlite3SchemaMutexHeld(db, j, 0) );
105093     pTrigger = sqlite3HashFind(&(db->aDb[j].pSchema->trigHash), zName, nName);
105094     if( pTrigger ) break;
105095   }
105096   if( !pTrigger ){
105097     if( !noErr ){
105098       sqlite3ErrorMsg(pParse, "no such trigger: %S", pName, 0);
105099     }else{
105100       sqlite3CodeVerifyNamedSchema(pParse, zDb);
105101     }
105102     pParse->checkSchema = 1;
105103     goto drop_trigger_cleanup;
105104   }
105105   sqlite3DropTriggerPtr(pParse, pTrigger);
105106 
105107 drop_trigger_cleanup:
105108   sqlite3SrcListDelete(db, pName);
105109 }
105110 
105111 /*
105112 ** Return a pointer to the Table structure for the table that a trigger
105113 ** is set on.
105114 */
105115 static Table *tableOfTrigger(Trigger *pTrigger){
105116   int n = sqlite3Strlen30(pTrigger->table);
105117   return sqlite3HashFind(&pTrigger->pTabSchema->tblHash, pTrigger->table, n);
105118 }
105119 
105120 
105121 /*
105122 ** Drop a trigger given a pointer to that trigger. 
105123 */
105124 SQLITE_PRIVATE void sqlite3DropTriggerPtr(Parse *pParse, Trigger *pTrigger){
105125   Table   *pTable;
105126   Vdbe *v;
105127   sqlite3 *db = pParse->db;
105128   int iDb;
105129 
105130   iDb = sqlite3SchemaToIndex(pParse->db, pTrigger->pSchema);
105131   assert( iDb>=0 && iDb<db->nDb );
105132   pTable = tableOfTrigger(pTrigger);
105133   assert( pTable );
105134   assert( pTable->pSchema==pTrigger->pSchema || iDb==1 );
105135 #ifndef SQLITE_OMIT_AUTHORIZATION
105136   {
105137     int code = SQLITE_DROP_TRIGGER;
105138     const char *zDb = db->aDb[iDb].zName;
105139     const char *zTab = SCHEMA_TABLE(iDb);
105140     if( iDb==1 ) code = SQLITE_DROP_TEMP_TRIGGER;
105141     if( sqlite3AuthCheck(pParse, code, pTrigger->zName, pTable->zName, zDb) ||
105142       sqlite3AuthCheck(pParse, SQLITE_DELETE, zTab, 0, zDb) ){
105143       return;
105144     }
105145   }
105146 #endif
105147 
105148   /* Generate code to destroy the database record of the trigger.
105149   */
105150   assert( pTable!=0 );
105151   if( (v = sqlite3GetVdbe(pParse))!=0 ){
105152     int base;
105153     static const VdbeOpList dropTrigger[] = {
105154       { OP_Rewind,     0, ADDR(9),  0},
105155       { OP_String8,    0, 1,        0}, /* 1 */
105156       { OP_Column,     0, 1,        2},
105157       { OP_Ne,         2, ADDR(8),  1},
105158       { OP_String8,    0, 1,        0}, /* 4: "trigger" */
105159       { OP_Column,     0, 0,        2},
105160       { OP_Ne,         2, ADDR(8),  1},
105161       { OP_Delete,     0, 0,        0},
105162       { OP_Next,       0, ADDR(1),  0}, /* 8 */
105163     };
105164 
105165     sqlite3BeginWriteOperation(pParse, 0, iDb);
105166     sqlite3OpenMasterTable(pParse, iDb);
105167     base = sqlite3VdbeAddOpList(v,  ArraySize(dropTrigger), dropTrigger);
105168     sqlite3VdbeChangeP4(v, base+1, pTrigger->zName, P4_TRANSIENT);
105169     sqlite3VdbeChangeP4(v, base+4, "trigger", P4_STATIC);
105170     sqlite3ChangeCookie(pParse, iDb);
105171     sqlite3VdbeAddOp2(v, OP_Close, 0, 0);
105172     sqlite3VdbeAddOp4(v, OP_DropTrigger, iDb, 0, 0, pTrigger->zName, 0);
105173     if( pParse->nMem<3 ){
105174       pParse->nMem = 3;
105175     }
105176   }
105177 }
105178 
105179 /*
105180 ** Remove a trigger from the hash tables of the sqlite* pointer.
105181 */
105182 SQLITE_PRIVATE void sqlite3UnlinkAndDeleteTrigger(sqlite3 *db, int iDb, const char *zName){
105183   Trigger *pTrigger;
105184   Hash *pHash;
105185 
105186   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
105187   pHash = &(db->aDb[iDb].pSchema->trigHash);
105188   pTrigger = sqlite3HashInsert(pHash, zName, sqlite3Strlen30(zName), 0);
105189   if( ALWAYS(pTrigger) ){
105190     if( pTrigger->pSchema==pTrigger->pTabSchema ){
105191       Table *pTab = tableOfTrigger(pTrigger);
105192       Trigger **pp;
105193       for(pp=&pTab->pTrigger; *pp!=pTrigger; pp=&((*pp)->pNext));
105194       *pp = (*pp)->pNext;
105195     }
105196     sqlite3DeleteTrigger(db, pTrigger);
105197     db->flags |= SQLITE_InternChanges;
105198   }
105199 }
105200 
105201 /*
105202 ** pEList is the SET clause of an UPDATE statement.  Each entry
105203 ** in pEList is of the format <id>=<expr>.  If any of the entries
105204 ** in pEList have an <id> which matches an identifier in pIdList,
105205 ** then return TRUE.  If pIdList==NULL, then it is considered a
105206 ** wildcard that matches anything.  Likewise if pEList==NULL then
105207 ** it matches anything so always return true.  Return false only
105208 ** if there is no match.
105209 */
105210 static int checkColumnOverlap(IdList *pIdList, ExprList *pEList){
105211   int e;
105212   if( pIdList==0 || NEVER(pEList==0) ) return 1;
105213   for(e=0; e<pEList->nExpr; e++){
105214     if( sqlite3IdListIndex(pIdList, pEList->a[e].zName)>=0 ) return 1;
105215   }
105216   return 0; 
105217 }
105218 
105219 /*
105220 ** Return a list of all triggers on table pTab if there exists at least
105221 ** one trigger that must be fired when an operation of type 'op' is 
105222 ** performed on the table, and, if that operation is an UPDATE, if at
105223 ** least one of the columns in pChanges is being modified.
105224 */
105225 SQLITE_PRIVATE Trigger *sqlite3TriggersExist(
105226   Parse *pParse,          /* Parse context */
105227   Table *pTab,            /* The table the contains the triggers */
105228   int op,                 /* one of TK_DELETE, TK_INSERT, TK_UPDATE */
105229   ExprList *pChanges,     /* Columns that change in an UPDATE statement */
105230   int *pMask              /* OUT: Mask of TRIGGER_BEFORE|TRIGGER_AFTER */
105231 ){
105232   int mask = 0;
105233   Trigger *pList = 0;
105234   Trigger *p;
105235 
105236   if( (pParse->db->flags & SQLITE_EnableTrigger)!=0 ){
105237     pList = sqlite3TriggerList(pParse, pTab);
105238   }
105239   assert( pList==0 || IsVirtual(pTab)==0 );
105240   for(p=pList; p; p=p->pNext){
105241     if( p->op==op && checkColumnOverlap(p->pColumns, pChanges) ){
105242       mask |= p->tr_tm;
105243     }
105244   }
105245   if( pMask ){
105246     *pMask = mask;
105247   }
105248   return (mask ? pList : 0);
105249 }
105250 
105251 /*
105252 ** Convert the pStep->target token into a SrcList and return a pointer
105253 ** to that SrcList.
105254 **
105255 ** This routine adds a specific database name, if needed, to the target when
105256 ** forming the SrcList.  This prevents a trigger in one database from
105257 ** referring to a target in another database.  An exception is when the
105258 ** trigger is in TEMP in which case it can refer to any other database it
105259 ** wants.
105260 */
105261 static SrcList *targetSrcList(
105262   Parse *pParse,       /* The parsing context */
105263   TriggerStep *pStep   /* The trigger containing the target token */
105264 ){
105265   int iDb;             /* Index of the database to use */
105266   SrcList *pSrc;       /* SrcList to be returned */
105267 
105268   pSrc = sqlite3SrcListAppend(pParse->db, 0, &pStep->target, 0);
105269   if( pSrc ){
105270     assert( pSrc->nSrc>0 );
105271     assert( pSrc->a!=0 );
105272     iDb = sqlite3SchemaToIndex(pParse->db, pStep->pTrig->pSchema);
105273     if( iDb==0 || iDb>=2 ){
105274       sqlite3 *db = pParse->db;
105275       assert( iDb<pParse->db->nDb );
105276       pSrc->a[pSrc->nSrc-1].zDatabase = sqlite3DbStrDup(db, db->aDb[iDb].zName);
105277     }
105278   }
105279   return pSrc;
105280 }
105281 
105282 /*
105283 ** Generate VDBE code for the statements inside the body of a single 
105284 ** trigger.
105285 */
105286 static int codeTriggerProgram(
105287   Parse *pParse,            /* The parser context */
105288   TriggerStep *pStepList,   /* List of statements inside the trigger body */
105289   int orconf                /* Conflict algorithm. (OE_Abort, etc) */  
105290 ){
105291   TriggerStep *pStep;
105292   Vdbe *v = pParse->pVdbe;
105293   sqlite3 *db = pParse->db;
105294 
105295   assert( pParse->pTriggerTab && pParse->pToplevel );
105296   assert( pStepList );
105297   assert( v!=0 );
105298   for(pStep=pStepList; pStep; pStep=pStep->pNext){
105299     /* Figure out the ON CONFLICT policy that will be used for this step
105300     ** of the trigger program. If the statement that caused this trigger
105301     ** to fire had an explicit ON CONFLICT, then use it. Otherwise, use
105302     ** the ON CONFLICT policy that was specified as part of the trigger
105303     ** step statement. Example:
105304     **
105305     **   CREATE TRIGGER AFTER INSERT ON t1 BEGIN;
105306     **     INSERT OR REPLACE INTO t2 VALUES(new.a, new.b);
105307     **   END;
105308     **
105309     **   INSERT INTO t1 ... ;            -- insert into t2 uses REPLACE policy
105310     **   INSERT OR IGNORE INTO t1 ... ;  -- insert into t2 uses IGNORE policy
105311     */
105312     pParse->eOrconf = (orconf==OE_Default)?pStep->orconf:(u8)orconf;
105313 
105314     /* Clear the cookieGoto flag. When coding triggers, the cookieGoto 
105315     ** variable is used as a flag to indicate to sqlite3ExprCodeConstants()
105316     ** that it is not safe to refactor constants (this happens after the
105317     ** start of the first loop in the SQL statement is coded - at that 
105318     ** point code may be conditionally executed, so it is no longer safe to 
105319     ** initialize constant register values).  */
105320     assert( pParse->cookieGoto==0 || pParse->cookieGoto==-1 );
105321     pParse->cookieGoto = 0;
105322 
105323     switch( pStep->op ){
105324       case TK_UPDATE: {
105325         sqlite3Update(pParse, 
105326           targetSrcList(pParse, pStep),
105327           sqlite3ExprListDup(db, pStep->pExprList, 0), 
105328           sqlite3ExprDup(db, pStep->pWhere, 0), 
105329           pParse->eOrconf
105330         );
105331         break;
105332       }
105333       case TK_INSERT: {
105334         sqlite3Insert(pParse, 
105335           targetSrcList(pParse, pStep),
105336           sqlite3ExprListDup(db, pStep->pExprList, 0), 
105337           sqlite3SelectDup(db, pStep->pSelect, 0), 
105338           sqlite3IdListDup(db, pStep->pIdList), 
105339           pParse->eOrconf
105340         );
105341         break;
105342       }
105343       case TK_DELETE: {
105344         sqlite3DeleteFrom(pParse, 
105345           targetSrcList(pParse, pStep),
105346           sqlite3ExprDup(db, pStep->pWhere, 0)
105347         );
105348         break;
105349       }
105350       default: assert( pStep->op==TK_SELECT ); {
105351         SelectDest sDest;
105352         Select *pSelect = sqlite3SelectDup(db, pStep->pSelect, 0);
105353         sqlite3SelectDestInit(&sDest, SRT_Discard, 0);
105354         sqlite3Select(pParse, pSelect, &sDest);
105355         sqlite3SelectDelete(db, pSelect);
105356         break;
105357       }
105358     } 
105359     if( pStep->op!=TK_SELECT ){
105360       sqlite3VdbeAddOp0(v, OP_ResetCount);
105361     }
105362   }
105363 
105364   return 0;
105365 }
105366 
105367 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
105368 /*
105369 ** This function is used to add VdbeComment() annotations to a VDBE
105370 ** program. It is not used in production code, only for debugging.
105371 */
105372 static const char *onErrorText(int onError){
105373   switch( onError ){
105374     case OE_Abort:    return "abort";
105375     case OE_Rollback: return "rollback";
105376     case OE_Fail:     return "fail";
105377     case OE_Replace:  return "replace";
105378     case OE_Ignore:   return "ignore";
105379     case OE_Default:  return "default";
105380   }
105381   return "n/a";
105382 }
105383 #endif
105384 
105385 /*
105386 ** Parse context structure pFrom has just been used to create a sub-vdbe
105387 ** (trigger program). If an error has occurred, transfer error information
105388 ** from pFrom to pTo.
105389 */
105390 static void transferParseError(Parse *pTo, Parse *pFrom){
105391   assert( pFrom->zErrMsg==0 || pFrom->nErr );
105392   assert( pTo->zErrMsg==0 || pTo->nErr );
105393   if( pTo->nErr==0 ){
105394     pTo->zErrMsg = pFrom->zErrMsg;
105395     pTo->nErr = pFrom->nErr;
105396   }else{
105397     sqlite3DbFree(pFrom->db, pFrom->zErrMsg);
105398   }
105399 }
105400 
105401 /*
105402 ** Create and populate a new TriggerPrg object with a sub-program 
105403 ** implementing trigger pTrigger with ON CONFLICT policy orconf.
105404 */
105405 static TriggerPrg *codeRowTrigger(
105406   Parse *pParse,       /* Current parse context */
105407   Trigger *pTrigger,   /* Trigger to code */
105408   Table *pTab,         /* The table pTrigger is attached to */
105409   int orconf           /* ON CONFLICT policy to code trigger program with */
105410 ){
105411   Parse *pTop = sqlite3ParseToplevel(pParse);
105412   sqlite3 *db = pParse->db;   /* Database handle */
105413   TriggerPrg *pPrg;           /* Value to return */
105414   Expr *pWhen = 0;            /* Duplicate of trigger WHEN expression */
105415   Vdbe *v;                    /* Temporary VM */
105416   NameContext sNC;            /* Name context for sub-vdbe */
105417   SubProgram *pProgram = 0;   /* Sub-vdbe for trigger program */
105418   Parse *pSubParse;           /* Parse context for sub-vdbe */
105419   int iEndTrigger = 0;        /* Label to jump to if WHEN is false */
105420 
105421   assert( pTrigger->zName==0 || pTab==tableOfTrigger(pTrigger) );
105422   assert( pTop->pVdbe );
105423 
105424   /* Allocate the TriggerPrg and SubProgram objects. To ensure that they
105425   ** are freed if an error occurs, link them into the Parse.pTriggerPrg 
105426   ** list of the top-level Parse object sooner rather than later.  */
105427   pPrg = sqlite3DbMallocZero(db, sizeof(TriggerPrg));
105428   if( !pPrg ) return 0;
105429   pPrg->pNext = pTop->pTriggerPrg;
105430   pTop->pTriggerPrg = pPrg;
105431   pPrg->pProgram = pProgram = sqlite3DbMallocZero(db, sizeof(SubProgram));
105432   if( !pProgram ) return 0;
105433   sqlite3VdbeLinkSubProgram(pTop->pVdbe, pProgram);
105434   pPrg->pTrigger = pTrigger;
105435   pPrg->orconf = orconf;
105436   pPrg->aColmask[0] = 0xffffffff;
105437   pPrg->aColmask[1] = 0xffffffff;
105438 
105439   /* Allocate and populate a new Parse context to use for coding the 
105440   ** trigger sub-program.  */
105441   pSubParse = sqlite3StackAllocZero(db, sizeof(Parse));
105442   if( !pSubParse ) return 0;
105443   memset(&sNC, 0, sizeof(sNC));
105444   sNC.pParse = pSubParse;
105445   pSubParse->db = db;
105446   pSubParse->pTriggerTab = pTab;
105447   pSubParse->pToplevel = pTop;
105448   pSubParse->zAuthContext = pTrigger->zName;
105449   pSubParse->eTriggerOp = pTrigger->op;
105450   pSubParse->nQueryLoop = pParse->nQueryLoop;
105451 
105452   v = sqlite3GetVdbe(pSubParse);
105453   if( v ){
105454     VdbeComment((v, "Start: %s.%s (%s %s%s%s ON %s)", 
105455       pTrigger->zName, onErrorText(orconf),
105456       (pTrigger->tr_tm==TRIGGER_BEFORE ? "BEFORE" : "AFTER"),
105457         (pTrigger->op==TK_UPDATE ? "UPDATE" : ""),
105458         (pTrigger->op==TK_INSERT ? "INSERT" : ""),
105459         (pTrigger->op==TK_DELETE ? "DELETE" : ""),
105460       pTab->zName
105461     ));
105462 #ifndef SQLITE_OMIT_TRACE
105463     sqlite3VdbeChangeP4(v, -1, 
105464       sqlite3MPrintf(db, "-- TRIGGER %s", pTrigger->zName), P4_DYNAMIC
105465     );
105466 #endif
105467 
105468     /* If one was specified, code the WHEN clause. If it evaluates to false
105469     ** (or NULL) the sub-vdbe is immediately halted by jumping to the 
105470     ** OP_Halt inserted at the end of the program.  */
105471     if( pTrigger->pWhen ){
105472       pWhen = sqlite3ExprDup(db, pTrigger->pWhen, 0);
105473       if( SQLITE_OK==sqlite3ResolveExprNames(&sNC, pWhen) 
105474        && db->mallocFailed==0 
105475       ){
105476         iEndTrigger = sqlite3VdbeMakeLabel(v);
105477         sqlite3ExprIfFalse(pSubParse, pWhen, iEndTrigger, SQLITE_JUMPIFNULL);
105478       }
105479       sqlite3ExprDelete(db, pWhen);
105480     }
105481 
105482     /* Code the trigger program into the sub-vdbe. */
105483     codeTriggerProgram(pSubParse, pTrigger->step_list, orconf);
105484 
105485     /* Insert an OP_Halt at the end of the sub-program. */
105486     if( iEndTrigger ){
105487       sqlite3VdbeResolveLabel(v, iEndTrigger);
105488     }
105489     sqlite3VdbeAddOp0(v, OP_Halt);
105490     VdbeComment((v, "End: %s.%s", pTrigger->zName, onErrorText(orconf)));
105491 
105492     transferParseError(pParse, pSubParse);
105493     if( db->mallocFailed==0 ){
105494       pProgram->aOp = sqlite3VdbeTakeOpArray(v, &pProgram->nOp, &pTop->nMaxArg);
105495     }
105496     pProgram->nMem = pSubParse->nMem;
105497     pProgram->nCsr = pSubParse->nTab;
105498     pProgram->nOnce = pSubParse->nOnce;
105499     pProgram->token = (void *)pTrigger;
105500     pPrg->aColmask[0] = pSubParse->oldmask;
105501     pPrg->aColmask[1] = pSubParse->newmask;
105502     sqlite3VdbeDelete(v);
105503   }
105504 
105505   assert( !pSubParse->pAinc       && !pSubParse->pZombieTab );
105506   assert( !pSubParse->pTriggerPrg && !pSubParse->nMaxArg );
105507   sqlite3ParserReset(pSubParse);
105508   sqlite3StackFree(db, pSubParse);
105509 
105510   return pPrg;
105511 }
105512     
105513 /*
105514 ** Return a pointer to a TriggerPrg object containing the sub-program for
105515 ** trigger pTrigger with default ON CONFLICT algorithm orconf. If no such
105516 ** TriggerPrg object exists, a new object is allocated and populated before
105517 ** being returned.
105518 */
105519 static TriggerPrg *getRowTrigger(
105520   Parse *pParse,       /* Current parse context */
105521   Trigger *pTrigger,   /* Trigger to code */
105522   Table *pTab,         /* The table trigger pTrigger is attached to */
105523   int orconf           /* ON CONFLICT algorithm. */
105524 ){
105525   Parse *pRoot = sqlite3ParseToplevel(pParse);
105526   TriggerPrg *pPrg;
105527 
105528   assert( pTrigger->zName==0 || pTab==tableOfTrigger(pTrigger) );
105529 
105530   /* It may be that this trigger has already been coded (or is in the
105531   ** process of being coded). If this is the case, then an entry with
105532   ** a matching TriggerPrg.pTrigger field will be present somewhere
105533   ** in the Parse.pTriggerPrg list. Search for such an entry.  */
105534   for(pPrg=pRoot->pTriggerPrg; 
105535       pPrg && (pPrg->pTrigger!=pTrigger || pPrg->orconf!=orconf); 
105536       pPrg=pPrg->pNext
105537   );
105538 
105539   /* If an existing TriggerPrg could not be located, create a new one. */
105540   if( !pPrg ){
105541     pPrg = codeRowTrigger(pParse, pTrigger, pTab, orconf);
105542   }
105543 
105544   return pPrg;
105545 }
105546 
105547 /*
105548 ** Generate code for the trigger program associated with trigger p on 
105549 ** table pTab. The reg, orconf and ignoreJump parameters passed to this
105550 ** function are the same as those described in the header function for
105551 ** sqlite3CodeRowTrigger()
105552 */
105553 SQLITE_PRIVATE void sqlite3CodeRowTriggerDirect(
105554   Parse *pParse,       /* Parse context */
105555   Trigger *p,          /* Trigger to code */
105556   Table *pTab,         /* The table to code triggers from */
105557   int reg,             /* Reg array containing OLD.* and NEW.* values */
105558   int orconf,          /* ON CONFLICT policy */
105559   int ignoreJump       /* Instruction to jump to for RAISE(IGNORE) */
105560 ){
105561   Vdbe *v = sqlite3GetVdbe(pParse); /* Main VM */
105562   TriggerPrg *pPrg;
105563   pPrg = getRowTrigger(pParse, p, pTab, orconf);
105564   assert( pPrg || pParse->nErr || pParse->db->mallocFailed );
105565 
105566   /* Code the OP_Program opcode in the parent VDBE. P4 of the OP_Program 
105567   ** is a pointer to the sub-vdbe containing the trigger program.  */
105568   if( pPrg ){
105569     int bRecursive = (p->zName && 0==(pParse->db->flags&SQLITE_RecTriggers));
105570 
105571     sqlite3VdbeAddOp3(v, OP_Program, reg, ignoreJump, ++pParse->nMem);
105572     sqlite3VdbeChangeP4(v, -1, (const char *)pPrg->pProgram, P4_SUBPROGRAM);
105573     VdbeComment(
105574         (v, "Call: %s.%s", (p->zName?p->zName:"fkey"), onErrorText(orconf)));
105575 
105576     /* Set the P5 operand of the OP_Program instruction to non-zero if
105577     ** recursive invocation of this trigger program is disallowed. Recursive
105578     ** invocation is disallowed if (a) the sub-program is really a trigger,
105579     ** not a foreign key action, and (b) the flag to enable recursive triggers
105580     ** is clear.  */
105581     sqlite3VdbeChangeP5(v, (u8)bRecursive);
105582   }
105583 }
105584 
105585 /*
105586 ** This is called to code the required FOR EACH ROW triggers for an operation
105587 ** on table pTab. The operation to code triggers for (INSERT, UPDATE or DELETE)
105588 ** is given by the op parameter. The tr_tm parameter determines whether the
105589 ** BEFORE or AFTER triggers are coded. If the operation is an UPDATE, then
105590 ** parameter pChanges is passed the list of columns being modified.
105591 **
105592 ** If there are no triggers that fire at the specified time for the specified
105593 ** operation on pTab, this function is a no-op.
105594 **
105595 ** The reg argument is the address of the first in an array of registers 
105596 ** that contain the values substituted for the new.* and old.* references
105597 ** in the trigger program. If N is the number of columns in table pTab
105598 ** (a copy of pTab->nCol), then registers are populated as follows:
105599 **
105600 **   Register       Contains
105601 **   ------------------------------------------------------
105602 **   reg+0          OLD.rowid
105603 **   reg+1          OLD.* value of left-most column of pTab
105604 **   ...            ...
105605 **   reg+N          OLD.* value of right-most column of pTab
105606 **   reg+N+1        NEW.rowid
105607 **   reg+N+2        OLD.* value of left-most column of pTab
105608 **   ...            ...
105609 **   reg+N+N+1      NEW.* value of right-most column of pTab
105610 **
105611 ** For ON DELETE triggers, the registers containing the NEW.* values will
105612 ** never be accessed by the trigger program, so they are not allocated or 
105613 ** populated by the caller (there is no data to populate them with anyway). 
105614 ** Similarly, for ON INSERT triggers the values stored in the OLD.* registers
105615 ** are never accessed, and so are not allocated by the caller. So, for an
105616 ** ON INSERT trigger, the value passed to this function as parameter reg
105617 ** is not a readable register, although registers (reg+N) through 
105618 ** (reg+N+N+1) are.
105619 **
105620 ** Parameter orconf is the default conflict resolution algorithm for the
105621 ** trigger program to use (REPLACE, IGNORE etc.). Parameter ignoreJump
105622 ** is the instruction that control should jump to if a trigger program
105623 ** raises an IGNORE exception.
105624 */
105625 SQLITE_PRIVATE void sqlite3CodeRowTrigger(
105626   Parse *pParse,       /* Parse context */
105627   Trigger *pTrigger,   /* List of triggers on table pTab */
105628   int op,              /* One of TK_UPDATE, TK_INSERT, TK_DELETE */
105629   ExprList *pChanges,  /* Changes list for any UPDATE OF triggers */
105630   int tr_tm,           /* One of TRIGGER_BEFORE, TRIGGER_AFTER */
105631   Table *pTab,         /* The table to code triggers from */
105632   int reg,             /* The first in an array of registers (see above) */
105633   int orconf,          /* ON CONFLICT policy */
105634   int ignoreJump       /* Instruction to jump to for RAISE(IGNORE) */
105635 ){
105636   Trigger *p;          /* Used to iterate through pTrigger list */
105637 
105638   assert( op==TK_UPDATE || op==TK_INSERT || op==TK_DELETE );
105639   assert( tr_tm==TRIGGER_BEFORE || tr_tm==TRIGGER_AFTER );
105640   assert( (op==TK_UPDATE)==(pChanges!=0) );
105641 
105642   for(p=pTrigger; p; p=p->pNext){
105643 
105644     /* Sanity checking:  The schema for the trigger and for the table are
105645     ** always defined.  The trigger must be in the same schema as the table
105646     ** or else it must be a TEMP trigger. */
105647     assert( p->pSchema!=0 );
105648     assert( p->pTabSchema!=0 );
105649     assert( p->pSchema==p->pTabSchema 
105650          || p->pSchema==pParse->db->aDb[1].pSchema );
105651 
105652     /* Determine whether we should code this trigger */
105653     if( p->op==op 
105654      && p->tr_tm==tr_tm 
105655      && checkColumnOverlap(p->pColumns, pChanges)
105656     ){
105657       sqlite3CodeRowTriggerDirect(pParse, p, pTab, reg, orconf, ignoreJump);
105658     }
105659   }
105660 }
105661 
105662 /*
105663 ** Triggers may access values stored in the old.* or new.* pseudo-table. 
105664 ** This function returns a 32-bit bitmask indicating which columns of the 
105665 ** old.* or new.* tables actually are used by triggers. This information 
105666 ** may be used by the caller, for example, to avoid having to load the entire
105667 ** old.* record into memory when executing an UPDATE or DELETE command.
105668 **
105669 ** Bit 0 of the returned mask is set if the left-most column of the
105670 ** table may be accessed using an [old|new].<col> reference. Bit 1 is set if
105671 ** the second leftmost column value is required, and so on. If there
105672 ** are more than 32 columns in the table, and at least one of the columns
105673 ** with an index greater than 32 may be accessed, 0xffffffff is returned.
105674 **
105675 ** It is not possible to determine if the old.rowid or new.rowid column is 
105676 ** accessed by triggers. The caller must always assume that it is.
105677 **
105678 ** Parameter isNew must be either 1 or 0. If it is 0, then the mask returned
105679 ** applies to the old.* table. If 1, the new.* table.
105680 **
105681 ** Parameter tr_tm must be a mask with one or both of the TRIGGER_BEFORE
105682 ** and TRIGGER_AFTER bits set. Values accessed by BEFORE triggers are only
105683 ** included in the returned mask if the TRIGGER_BEFORE bit is set in the
105684 ** tr_tm parameter. Similarly, values accessed by AFTER triggers are only
105685 ** included in the returned mask if the TRIGGER_AFTER bit is set in tr_tm.
105686 */
105687 SQLITE_PRIVATE u32 sqlite3TriggerColmask(
105688   Parse *pParse,       /* Parse context */
105689   Trigger *pTrigger,   /* List of triggers on table pTab */
105690   ExprList *pChanges,  /* Changes list for any UPDATE OF triggers */
105691   int isNew,           /* 1 for new.* ref mask, 0 for old.* ref mask */
105692   int tr_tm,           /* Mask of TRIGGER_BEFORE|TRIGGER_AFTER */
105693   Table *pTab,         /* The table to code triggers from */
105694   int orconf           /* Default ON CONFLICT policy for trigger steps */
105695 ){
105696   const int op = pChanges ? TK_UPDATE : TK_DELETE;
105697   u32 mask = 0;
105698   Trigger *p;
105699 
105700   assert( isNew==1 || isNew==0 );
105701   for(p=pTrigger; p; p=p->pNext){
105702     if( p->op==op && (tr_tm&p->tr_tm)
105703      && checkColumnOverlap(p->pColumns,pChanges)
105704     ){
105705       TriggerPrg *pPrg;
105706       pPrg = getRowTrigger(pParse, p, pTab, orconf);
105707       if( pPrg ){
105708         mask |= pPrg->aColmask[isNew];
105709       }
105710     }
105711   }
105712 
105713   return mask;
105714 }
105715 
105716 #endif /* !defined(SQLITE_OMIT_TRIGGER) */
105717 
105718 /************** End of trigger.c *********************************************/
105719 /************** Begin file update.c ******************************************/
105720 /*
105721 ** 2001 September 15
105722 **
105723 ** The author disclaims copyright to this source code.  In place of
105724 ** a legal notice, here is a blessing:
105725 **
105726 **    May you do good and not evil.
105727 **    May you find forgiveness for yourself and forgive others.
105728 **    May you share freely, never taking more than you give.
105729 **
105730 *************************************************************************
105731 ** This file contains C code routines that are called by the parser
105732 ** to handle UPDATE statements.
105733 */
105734 
105735 #ifndef SQLITE_OMIT_VIRTUALTABLE
105736 /* Forward declaration */
105737 static void updateVirtualTable(
105738   Parse *pParse,       /* The parsing context */
105739   SrcList *pSrc,       /* The virtual table to be modified */
105740   Table *pTab,         /* The virtual table */
105741   ExprList *pChanges,  /* The columns to change in the UPDATE statement */
105742   Expr *pRowidExpr,    /* Expression used to recompute the rowid */
105743   int *aXRef,          /* Mapping from columns of pTab to entries in pChanges */
105744   Expr *pWhere,        /* WHERE clause of the UPDATE statement */
105745   int onError          /* ON CONFLICT strategy */
105746 );
105747 #endif /* SQLITE_OMIT_VIRTUALTABLE */
105748 
105749 /*
105750 ** The most recently coded instruction was an OP_Column to retrieve the
105751 ** i-th column of table pTab. This routine sets the P4 parameter of the 
105752 ** OP_Column to the default value, if any.
105753 **
105754 ** The default value of a column is specified by a DEFAULT clause in the 
105755 ** column definition. This was either supplied by the user when the table
105756 ** was created, or added later to the table definition by an ALTER TABLE
105757 ** command. If the latter, then the row-records in the table btree on disk
105758 ** may not contain a value for the column and the default value, taken
105759 ** from the P4 parameter of the OP_Column instruction, is returned instead.
105760 ** If the former, then all row-records are guaranteed to include a value
105761 ** for the column and the P4 value is not required.
105762 **
105763 ** Column definitions created by an ALTER TABLE command may only have 
105764 ** literal default values specified: a number, null or a string. (If a more
105765 ** complicated default expression value was provided, it is evaluated 
105766 ** when the ALTER TABLE is executed and one of the literal values written
105767 ** into the sqlite_master table.)
105768 **
105769 ** Therefore, the P4 parameter is only required if the default value for
105770 ** the column is a literal number, string or null. The sqlite3ValueFromExpr()
105771 ** function is capable of transforming these types of expressions into
105772 ** sqlite3_value objects.
105773 **
105774 ** If parameter iReg is not negative, code an OP_RealAffinity instruction
105775 ** on register iReg. This is used when an equivalent integer value is 
105776 ** stored in place of an 8-byte floating point value in order to save 
105777 ** space.
105778 */
105779 SQLITE_PRIVATE void sqlite3ColumnDefault(Vdbe *v, Table *pTab, int i, int iReg){
105780   assert( pTab!=0 );
105781   if( !pTab->pSelect ){
105782     sqlite3_value *pValue = 0;
105783     u8 enc = ENC(sqlite3VdbeDb(v));
105784     Column *pCol = &pTab->aCol[i];
105785     VdbeComment((v, "%s.%s", pTab->zName, pCol->zName));
105786     assert( i<pTab->nCol );
105787     sqlite3ValueFromExpr(sqlite3VdbeDb(v), pCol->pDflt, enc, 
105788                          pCol->affinity, &pValue);
105789     if( pValue ){
105790       sqlite3VdbeChangeP4(v, -1, (const char *)pValue, P4_MEM);
105791     }
105792 #ifndef SQLITE_OMIT_FLOATING_POINT
105793     if( iReg>=0 && pTab->aCol[i].affinity==SQLITE_AFF_REAL ){
105794       sqlite3VdbeAddOp1(v, OP_RealAffinity, iReg);
105795     }
105796 #endif
105797   }
105798 }
105799 
105800 /*
105801 ** Process an UPDATE statement.
105802 **
105803 **   UPDATE OR IGNORE table_wxyz SET a=b, c=d WHERE e<5 AND f NOT NULL;
105804 **          \_______/ \________/     \______/       \________________/
105805 *            onError   pTabList      pChanges             pWhere
105806 */
105807 SQLITE_PRIVATE void sqlite3Update(
105808   Parse *pParse,         /* The parser context */
105809   SrcList *pTabList,     /* The table in which we should change things */
105810   ExprList *pChanges,    /* Things to be changed */
105811   Expr *pWhere,          /* The WHERE clause.  May be null */
105812   int onError            /* How to handle constraint errors */
105813 ){
105814   int i, j;              /* Loop counters */
105815   Table *pTab;           /* The table to be updated */
105816   int addrTop = 0;       /* VDBE instruction address of the start of the loop */
105817   WhereInfo *pWInfo;     /* Information about the WHERE clause */
105818   Vdbe *v;               /* The virtual database engine */
105819   Index *pIdx;           /* For looping over indices */
105820   Index *pPk;            /* The PRIMARY KEY index for WITHOUT ROWID tables */
105821   int nIdx;              /* Number of indices that need updating */
105822   int iBaseCur;          /* Base cursor number */
105823   int iDataCur;          /* Cursor for the canonical data btree */
105824   int iIdxCur;           /* Cursor for the first index */
105825   sqlite3 *db;           /* The database structure */
105826   int *aRegIdx = 0;      /* One register assigned to each index to be updated */
105827   int *aXRef = 0;        /* aXRef[i] is the index in pChanges->a[] of the
105828                          ** an expression for the i-th column of the table.
105829                          ** aXRef[i]==-1 if the i-th column is not changed. */
105830   u8 *aToOpen;           /* 1 for tables and indices to be opened */
105831   u8 chngPk;             /* PRIMARY KEY changed in a WITHOUT ROWID table */
105832   u8 chngRowid;          /* Rowid changed in a normal table */
105833   u8 chngKey;            /* Either chngPk or chngRowid */
105834   Expr *pRowidExpr = 0;  /* Expression defining the new record number */
105835   AuthContext sContext;  /* The authorization context */
105836   NameContext sNC;       /* The name-context to resolve expressions in */
105837   int iDb;               /* Database containing the table being updated */
105838   int okOnePass;         /* True for one-pass algorithm without the FIFO */
105839   int hasFK;             /* True if foreign key processing is required */
105840   int labelBreak;        /* Jump here to break out of UPDATE loop */
105841   int labelContinue;     /* Jump here to continue next step of UPDATE loop */
105842 
105843 #ifndef SQLITE_OMIT_TRIGGER
105844   int isView;            /* True when updating a view (INSTEAD OF trigger) */
105845   Trigger *pTrigger;     /* List of triggers on pTab, if required */
105846   int tmask;             /* Mask of TRIGGER_BEFORE|TRIGGER_AFTER */
105847 #endif
105848   int newmask;           /* Mask of NEW.* columns accessed by BEFORE triggers */
105849   int iEph = 0;          /* Ephemeral table holding all primary key values */
105850   int nKey = 0;          /* Number of elements in regKey for WITHOUT ROWID */
105851   int aiCurOnePass[2];   /* The write cursors opened by WHERE_ONEPASS */
105852 
105853   /* Register Allocations */
105854   int regRowCount = 0;   /* A count of rows changed */
105855   int regOldRowid;       /* The old rowid */
105856   int regNewRowid;       /* The new rowid */
105857   int regNew;            /* Content of the NEW.* table in triggers */
105858   int regOld = 0;        /* Content of OLD.* table in triggers */
105859   int regRowSet = 0;     /* Rowset of rows to be updated */
105860   int regKey = 0;        /* composite PRIMARY KEY value */
105861 
105862   memset(&sContext, 0, sizeof(sContext));
105863   db = pParse->db;
105864   if( pParse->nErr || db->mallocFailed ){
105865     goto update_cleanup;
105866   }
105867   assert( pTabList->nSrc==1 );
105868 
105869   /* Locate the table which we want to update. 
105870   */
105871   pTab = sqlite3SrcListLookup(pParse, pTabList);
105872   if( pTab==0 ) goto update_cleanup;
105873   iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
105874 
105875   /* Figure out if we have any triggers and if the table being
105876   ** updated is a view.
105877   */
105878 #ifndef SQLITE_OMIT_TRIGGER
105879   pTrigger = sqlite3TriggersExist(pParse, pTab, TK_UPDATE, pChanges, &tmask);
105880   isView = pTab->pSelect!=0;
105881   assert( pTrigger || tmask==0 );
105882 #else
105883 # define pTrigger 0
105884 # define isView 0
105885 # define tmask 0
105886 #endif
105887 #ifdef SQLITE_OMIT_VIEW
105888 # undef isView
105889 # define isView 0
105890 #endif
105891 
105892   if( sqlite3ViewGetColumnNames(pParse, pTab) ){
105893     goto update_cleanup;
105894   }
105895   if( sqlite3IsReadOnly(pParse, pTab, tmask) ){
105896     goto update_cleanup;
105897   }
105898 
105899   /* Allocate a cursors for the main database table and for all indices.
105900   ** The index cursors might not be used, but if they are used they
105901   ** need to occur right after the database cursor.  So go ahead and
105902   ** allocate enough space, just in case.
105903   */
105904   pTabList->a[0].iCursor = iBaseCur = iDataCur = pParse->nTab++;
105905   iIdxCur = iDataCur+1;
105906   pPk = HasRowid(pTab) ? 0 : sqlite3PrimaryKeyIndex(pTab);
105907   for(nIdx=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, nIdx++){
105908     if( pIdx->autoIndex==2 && pPk!=0 ){
105909       iDataCur = pParse->nTab;
105910       pTabList->a[0].iCursor = iDataCur;
105911     }
105912     pParse->nTab++;
105913   }
105914 
105915   /* Allocate space for aXRef[], aRegIdx[], and aToOpen[].  
105916   ** Initialize aXRef[] and aToOpen[] to their default values.
105917   */
105918   aXRef = sqlite3DbMallocRaw(db, sizeof(int) * (pTab->nCol+nIdx) + nIdx+2 );
105919   if( aXRef==0 ) goto update_cleanup;
105920   aRegIdx = aXRef+pTab->nCol;
105921   aToOpen = (u8*)(aRegIdx+nIdx);
105922   memset(aToOpen, 1, nIdx+1);
105923   aToOpen[nIdx+1] = 0;
105924   for(i=0; i<pTab->nCol; i++) aXRef[i] = -1;
105925 
105926   /* Initialize the name-context */
105927   memset(&sNC, 0, sizeof(sNC));
105928   sNC.pParse = pParse;
105929   sNC.pSrcList = pTabList;
105930 
105931   /* Resolve the column names in all the expressions of the
105932   ** of the UPDATE statement.  Also find the column index
105933   ** for each column to be updated in the pChanges array.  For each
105934   ** column to be updated, make sure we have authorization to change
105935   ** that column.
105936   */
105937   chngRowid = chngPk = 0;
105938   for(i=0; i<pChanges->nExpr; i++){
105939     if( sqlite3ResolveExprNames(&sNC, pChanges->a[i].pExpr) ){
105940       goto update_cleanup;
105941     }
105942     for(j=0; j<pTab->nCol; j++){
105943       if( sqlite3StrICmp(pTab->aCol[j].zName, pChanges->a[i].zName)==0 ){
105944         if( j==pTab->iPKey ){
105945           chngRowid = 1;
105946           pRowidExpr = pChanges->a[i].pExpr;
105947         }else if( pPk && (pTab->aCol[j].colFlags & COLFLAG_PRIMKEY)!=0 ){
105948           chngPk = 1;
105949         }
105950         aXRef[j] = i;
105951         break;
105952       }
105953     }
105954     if( j>=pTab->nCol ){
105955       if( pPk==0 && sqlite3IsRowid(pChanges->a[i].zName) ){
105956         j = -1;
105957         chngRowid = 1;
105958         pRowidExpr = pChanges->a[i].pExpr;
105959       }else{
105960         sqlite3ErrorMsg(pParse, "no such column: %s", pChanges->a[i].zName);
105961         pParse->checkSchema = 1;
105962         goto update_cleanup;
105963       }
105964     }
105965 #ifndef SQLITE_OMIT_AUTHORIZATION
105966     {
105967       int rc;
105968       rc = sqlite3AuthCheck(pParse, SQLITE_UPDATE, pTab->zName,
105969                             j<0 ? "ROWID" : pTab->aCol[j].zName,
105970                             db->aDb[iDb].zName);
105971       if( rc==SQLITE_DENY ){
105972         goto update_cleanup;
105973       }else if( rc==SQLITE_IGNORE ){
105974         aXRef[j] = -1;
105975       }
105976     }
105977 #endif
105978   }
105979   assert( (chngRowid & chngPk)==0 );
105980   assert( chngRowid==0 || chngRowid==1 );
105981   assert( chngPk==0 || chngPk==1 );
105982   chngKey = chngRowid + chngPk;
105983 
105984   /* The SET expressions are not actually used inside the WHERE loop.
105985   ** So reset the colUsed mask
105986   */
105987   pTabList->a[0].colUsed = 0;
105988 
105989   hasFK = sqlite3FkRequired(pParse, pTab, aXRef, chngKey);
105990 
105991   /* There is one entry in the aRegIdx[] array for each index on the table
105992   ** being updated.  Fill in aRegIdx[] with a register number that will hold
105993   ** the key for accessing each index.  
105994   */
105995   for(j=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, j++){
105996     int reg;
105997     if( chngKey || hasFK || pIdx->pPartIdxWhere || pIdx==pPk ){
105998       reg = ++pParse->nMem;
105999     }else{
106000       reg = 0;
106001       for(i=0; i<pIdx->nKeyCol; i++){
106002         if( aXRef[pIdx->aiColumn[i]]>=0 ){
106003           reg = ++pParse->nMem;
106004           break;
106005         }
106006       }
106007     }
106008     if( reg==0 ) aToOpen[j+1] = 0;
106009     aRegIdx[j] = reg;
106010   }
106011 
106012   /* Begin generating code. */
106013   v = sqlite3GetVdbe(pParse);
106014   if( v==0 ) goto update_cleanup;
106015   if( pParse->nested==0 ) sqlite3VdbeCountChanges(v);
106016   sqlite3BeginWriteOperation(pParse, 1, iDb);
106017 
106018 #ifndef SQLITE_OMIT_VIRTUALTABLE
106019   /* Virtual tables must be handled separately */
106020   if( IsVirtual(pTab) ){
106021     updateVirtualTable(pParse, pTabList, pTab, pChanges, pRowidExpr, aXRef,
106022                        pWhere, onError);
106023     pWhere = 0;
106024     pTabList = 0;
106025     goto update_cleanup;
106026   }
106027 #endif
106028 
106029   /* Allocate required registers. */
106030   regRowSet = ++pParse->nMem;
106031   regOldRowid = regNewRowid = ++pParse->nMem;
106032   if( chngPk || pTrigger || hasFK ){
106033     regOld = pParse->nMem + 1;
106034     pParse->nMem += pTab->nCol;
106035   }
106036   if( chngKey || pTrigger || hasFK ){
106037     regNewRowid = ++pParse->nMem;
106038   }
106039   regNew = pParse->nMem + 1;
106040   pParse->nMem += pTab->nCol;
106041 
106042   /* Start the view context. */
106043   if( isView ){
106044     sqlite3AuthContextPush(pParse, &sContext, pTab->zName);
106045   }
106046 
106047   /* If we are trying to update a view, realize that view into
106048   ** a ephemeral table.
106049   */
106050 #if !defined(SQLITE_OMIT_VIEW) && !defined(SQLITE_OMIT_TRIGGER)
106051   if( isView ){
106052     sqlite3MaterializeView(pParse, pTab, pWhere, iDataCur);
106053   }
106054 #endif
106055 
106056   /* Resolve the column names in all the expressions in the
106057   ** WHERE clause.
106058   */
106059   if( sqlite3ResolveExprNames(&sNC, pWhere) ){
106060     goto update_cleanup;
106061   }
106062 
106063   /* Begin the database scan
106064   */
106065   if( HasRowid(pTab) ){
106066     sqlite3VdbeAddOp3(v, OP_Null, 0, regRowSet, regOldRowid);
106067     pWInfo = sqlite3WhereBegin(
106068         pParse, pTabList, pWhere, 0, 0, WHERE_ONEPASS_DESIRED, iIdxCur
106069     );
106070     if( pWInfo==0 ) goto update_cleanup;
106071     okOnePass = sqlite3WhereOkOnePass(pWInfo, aiCurOnePass);
106072   
106073     /* Remember the rowid of every item to be updated.
106074     */
106075     sqlite3VdbeAddOp2(v, OP_Rowid, iDataCur, regOldRowid);
106076     if( !okOnePass ){
106077       sqlite3VdbeAddOp2(v, OP_RowSetAdd, regRowSet, regOldRowid);
106078     }
106079   
106080     /* End the database scan loop.
106081     */
106082     sqlite3WhereEnd(pWInfo);
106083   }else{
106084     int iPk;         /* First of nPk memory cells holding PRIMARY KEY value */
106085     i16 nPk;         /* Number of components of the PRIMARY KEY */
106086     int addrOpen;    /* Address of the OpenEphemeral instruction */
106087 
106088     assert( pPk!=0 );
106089     nPk = pPk->nKeyCol;
106090     iPk = pParse->nMem+1;
106091     pParse->nMem += nPk;
106092     regKey = ++pParse->nMem;
106093     iEph = pParse->nTab++;
106094     sqlite3VdbeAddOp2(v, OP_Null, 0, iPk);
106095     addrOpen = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, iEph, nPk);
106096     sqlite3VdbeSetP4KeyInfo(pParse, pPk);
106097     pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, 0, 0, 
106098                                WHERE_ONEPASS_DESIRED, iIdxCur);
106099     if( pWInfo==0 ) goto update_cleanup;
106100     okOnePass = sqlite3WhereOkOnePass(pWInfo, aiCurOnePass);
106101     for(i=0; i<nPk; i++){
106102       sqlite3ExprCodeGetColumnOfTable(v, pTab, iDataCur, pPk->aiColumn[i],
106103                                       iPk+i);
106104     }
106105     if( okOnePass ){
106106       sqlite3VdbeChangeToNoop(v, addrOpen);
106107       nKey = nPk;
106108       regKey = iPk;
106109     }else{
106110       sqlite3VdbeAddOp4(v, OP_MakeRecord, iPk, nPk, regKey,
106111                         sqlite3IndexAffinityStr(v, pPk), P4_TRANSIENT);
106112       sqlite3VdbeAddOp2(v, OP_IdxInsert, iEph, regKey);
106113     }
106114     sqlite3WhereEnd(pWInfo);
106115   }
106116 
106117   /* Initialize the count of updated rows
106118   */
106119   if( (db->flags & SQLITE_CountRows) && !pParse->pTriggerTab ){
106120     regRowCount = ++pParse->nMem;
106121     sqlite3VdbeAddOp2(v, OP_Integer, 0, regRowCount);
106122   }
106123 
106124   labelBreak = sqlite3VdbeMakeLabel(v);
106125   if( !isView ){
106126     /* 
106127     ** Open every index that needs updating.  Note that if any
106128     ** index could potentially invoke a REPLACE conflict resolution 
106129     ** action, then we need to open all indices because we might need
106130     ** to be deleting some records.
106131     */
106132     if( onError==OE_Replace ){
106133       memset(aToOpen, 1, nIdx+1);
106134     }else{
106135       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
106136         if( pIdx->onError==OE_Replace ){
106137           memset(aToOpen, 1, nIdx+1);
106138           break;
106139         }
106140       }
106141     }
106142     if( okOnePass ){
106143       if( aiCurOnePass[0]>=0 ) aToOpen[aiCurOnePass[0]-iBaseCur] = 0;
106144       if( aiCurOnePass[1]>=0 ) aToOpen[aiCurOnePass[1]-iBaseCur] = 0;
106145     }
106146     sqlite3OpenTableAndIndices(pParse, pTab, OP_OpenWrite, iBaseCur, aToOpen,
106147                                0, 0);
106148   }
106149 
106150   /* Top of the update loop */
106151   if( okOnePass ){
106152     if( aToOpen[iDataCur-iBaseCur] ){
106153       assert( pPk!=0 );
106154       sqlite3VdbeAddOp4Int(v, OP_NotFound, iDataCur, labelBreak, regKey, nKey);
106155     }
106156     labelContinue = labelBreak;
106157     sqlite3VdbeAddOp2(v, OP_IsNull, pPk ? regKey : regOldRowid, labelBreak);
106158   }else if( pPk ){
106159     labelContinue = sqlite3VdbeMakeLabel(v);
106160     sqlite3VdbeAddOp2(v, OP_Rewind, iEph, labelBreak);
106161     addrTop = sqlite3VdbeAddOp2(v, OP_RowKey, iEph, regKey);
106162     sqlite3VdbeAddOp4Int(v, OP_NotFound, iDataCur, labelContinue, regKey, 0);
106163   }else{
106164     labelContinue = sqlite3VdbeAddOp3(v, OP_RowSetRead, regRowSet, labelBreak,
106165                              regOldRowid);
106166     sqlite3VdbeAddOp3(v, OP_NotExists, iDataCur, labelContinue, regOldRowid);
106167   }
106168 
106169   /* If the record number will change, set register regNewRowid to
106170   ** contain the new value. If the record number is not being modified,
106171   ** then regNewRowid is the same register as regOldRowid, which is
106172   ** already populated.  */
106173   assert( chngKey || pTrigger || hasFK || regOldRowid==regNewRowid );
106174   if( chngRowid ){
106175     sqlite3ExprCode(pParse, pRowidExpr, regNewRowid);
106176     sqlite3VdbeAddOp1(v, OP_MustBeInt, regNewRowid);
106177   }
106178 
106179   /* Compute the old pre-UPDATE content of the row being changed, if that
106180   ** information is needed */
106181   if( chngPk || hasFK || pTrigger ){
106182     u32 oldmask = (hasFK ? sqlite3FkOldmask(pParse, pTab) : 0);
106183     oldmask |= sqlite3TriggerColmask(pParse, 
106184         pTrigger, pChanges, 0, TRIGGER_BEFORE|TRIGGER_AFTER, pTab, onError
106185     );
106186     for(i=0; i<pTab->nCol; i++){
106187       if( oldmask==0xffffffff
106188        || (i<32 && (oldmask & (1<<i)))
106189        || (pTab->aCol[i].colFlags & COLFLAG_PRIMKEY)!=0
106190       ){
106191         sqlite3ExprCodeGetColumnOfTable(v, pTab, iDataCur, i, regOld+i);
106192       }else{
106193         sqlite3VdbeAddOp2(v, OP_Null, 0, regOld+i);
106194       }
106195     }
106196     if( chngRowid==0 && pPk==0 ){
106197       sqlite3VdbeAddOp2(v, OP_Copy, regOldRowid, regNewRowid);
106198     }
106199   }
106200 
106201   /* Populate the array of registers beginning at regNew with the new
106202   ** row data. This array is used to check constaints, create the new
106203   ** table and index records, and as the values for any new.* references
106204   ** made by triggers.
106205   **
106206   ** If there are one or more BEFORE triggers, then do not populate the
106207   ** registers associated with columns that are (a) not modified by
106208   ** this UPDATE statement and (b) not accessed by new.* references. The
106209   ** values for registers not modified by the UPDATE must be reloaded from 
106210   ** the database after the BEFORE triggers are fired anyway (as the trigger 
106211   ** may have modified them). So not loading those that are not going to
106212   ** be used eliminates some redundant opcodes.
106213   */
106214   newmask = sqlite3TriggerColmask(
106215       pParse, pTrigger, pChanges, 1, TRIGGER_BEFORE, pTab, onError
106216   );
106217   sqlite3VdbeAddOp3(v, OP_Null, 0, regNew, regNew+pTab->nCol-1);
106218   for(i=0; i<pTab->nCol; i++){
106219     if( i==pTab->iPKey ){
106220       /*sqlite3VdbeAddOp2(v, OP_Null, 0, regNew+i);*/
106221     }else{
106222       j = aXRef[i];
106223       if( j>=0 ){
106224         sqlite3ExprCode(pParse, pChanges->a[j].pExpr, regNew+i);
106225       }else if( 0==(tmask&TRIGGER_BEFORE) || i>31 || (newmask&(1<<i)) ){
106226         /* This branch loads the value of a column that will not be changed 
106227         ** into a register. This is done if there are no BEFORE triggers, or
106228         ** if there are one or more BEFORE triggers that use this value via
106229         ** a new.* reference in a trigger program.
106230         */
106231         testcase( i==31 );
106232         testcase( i==32 );
106233         sqlite3ExprCodeGetColumnOfTable(v, pTab, iDataCur, i, regNew+i);
106234       }
106235     }
106236   }
106237 
106238   /* Fire any BEFORE UPDATE triggers. This happens before constraints are
106239   ** verified. One could argue that this is wrong.
106240   */
106241   if( tmask&TRIGGER_BEFORE ){
106242     sqlite3VdbeAddOp2(v, OP_Affinity, regNew, pTab->nCol);
106243     sqlite3TableAffinityStr(v, pTab);
106244     sqlite3CodeRowTrigger(pParse, pTrigger, TK_UPDATE, pChanges, 
106245         TRIGGER_BEFORE, pTab, regOldRowid, onError, labelContinue);
106246 
106247     /* The row-trigger may have deleted the row being updated. In this
106248     ** case, jump to the next row. No updates or AFTER triggers are 
106249     ** required. This behavior - what happens when the row being updated
106250     ** is deleted or renamed by a BEFORE trigger - is left undefined in the
106251     ** documentation.
106252     */
106253     if( pPk ){
106254       sqlite3VdbeAddOp4Int(v, OP_NotFound, iDataCur, labelContinue,regKey,nKey);
106255     }else{
106256       sqlite3VdbeAddOp3(v, OP_NotExists, iDataCur, labelContinue, regOldRowid);
106257     }
106258 
106259     /* If it did not delete it, the row-trigger may still have modified 
106260     ** some of the columns of the row being updated. Load the values for 
106261     ** all columns not modified by the update statement into their 
106262     ** registers in case this has happened.
106263     */
106264     for(i=0; i<pTab->nCol; i++){
106265       if( aXRef[i]<0 && i!=pTab->iPKey ){
106266         sqlite3ExprCodeGetColumnOfTable(v, pTab, iDataCur, i, regNew+i);
106267       }
106268     }
106269   }
106270 
106271   if( !isView ){
106272     int j1 = 0;           /* Address of jump instruction */
106273     int bReplace = 0;     /* True if REPLACE conflict resolution might happen */
106274 
106275     /* Do constraint checks. */
106276     assert( regOldRowid>0 );
106277     sqlite3GenerateConstraintChecks(pParse, pTab, aRegIdx, iDataCur, iIdxCur,
106278         regNewRowid, regOldRowid, chngKey, onError, labelContinue, &bReplace);
106279 
106280     /* Do FK constraint checks. */
106281     if( hasFK ){
106282       sqlite3FkCheck(pParse, pTab, regOldRowid, 0, aXRef, chngKey);
106283     }
106284 
106285     /* Delete the index entries associated with the current record.  */
106286     if( bReplace || chngKey ){
106287       if( pPk ){
106288         j1 = sqlite3VdbeAddOp4Int(v, OP_NotFound, iDataCur, 0, regKey, nKey);
106289       }else{
106290         j1 = sqlite3VdbeAddOp3(v, OP_NotExists, iDataCur, 0, regOldRowid);
106291       }
106292     }
106293     sqlite3GenerateRowIndexDelete(pParse, pTab, iDataCur, iIdxCur, aRegIdx);
106294   
106295     /* If changing the record number, delete the old record.  */
106296     if( hasFK || chngKey || pPk!=0 ){
106297       sqlite3VdbeAddOp2(v, OP_Delete, iDataCur, 0);
106298     }
106299     if( bReplace || chngKey ){
106300       sqlite3VdbeJumpHere(v, j1);
106301     }
106302 
106303     if( hasFK ){
106304       sqlite3FkCheck(pParse, pTab, 0, regNewRowid, aXRef, chngKey);
106305     }
106306   
106307     /* Insert the new index entries and the new record. */
106308     sqlite3CompleteInsertion(pParse, pTab, iDataCur, iIdxCur,
106309                              regNewRowid, aRegIdx, 1, 0, 0);
106310 
106311     /* Do any ON CASCADE, SET NULL or SET DEFAULT operations required to
106312     ** handle rows (possibly in other tables) that refer via a foreign key
106313     ** to the row just updated. */ 
106314     if( hasFK ){
106315       sqlite3FkActions(pParse, pTab, pChanges, regOldRowid, aXRef, chngKey);
106316     }
106317   }
106318 
106319   /* Increment the row counter 
106320   */
106321   if( (db->flags & SQLITE_CountRows) && !pParse->pTriggerTab){
106322     sqlite3VdbeAddOp2(v, OP_AddImm, regRowCount, 1);
106323   }
106324 
106325   sqlite3CodeRowTrigger(pParse, pTrigger, TK_UPDATE, pChanges, 
106326       TRIGGER_AFTER, pTab, regOldRowid, onError, labelContinue);
106327 
106328   /* Repeat the above with the next record to be updated, until
106329   ** all record selected by the WHERE clause have been updated.
106330   */
106331   if( okOnePass ){
106332     /* Nothing to do at end-of-loop for a single-pass */
106333   }else if( pPk ){
106334     sqlite3VdbeResolveLabel(v, labelContinue);
106335     sqlite3VdbeAddOp2(v, OP_Next, iEph, addrTop);
106336   }else{
106337     sqlite3VdbeAddOp2(v, OP_Goto, 0, labelContinue);
106338   }
106339   sqlite3VdbeResolveLabel(v, labelBreak);
106340 
106341   /* Close all tables */
106342   for(i=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, i++){
106343     assert( aRegIdx );
106344     if( aToOpen[i+1] ){
106345       sqlite3VdbeAddOp2(v, OP_Close, iIdxCur+i, 0);
106346     }
106347   }
106348   if( iDataCur<iIdxCur ) sqlite3VdbeAddOp2(v, OP_Close, iDataCur, 0);
106349 
106350   /* Update the sqlite_sequence table by storing the content of the
106351   ** maximum rowid counter values recorded while inserting into
106352   ** autoincrement tables.
106353   */
106354   if( pParse->nested==0 && pParse->pTriggerTab==0 ){
106355     sqlite3AutoincrementEnd(pParse);
106356   }
106357 
106358   /*
106359   ** Return the number of rows that were changed. If this routine is 
106360   ** generating code because of a call to sqlite3NestedParse(), do not
106361   ** invoke the callback function.
106362   */
106363   if( (db->flags&SQLITE_CountRows) && !pParse->pTriggerTab && !pParse->nested ){
106364     sqlite3VdbeAddOp2(v, OP_ResultRow, regRowCount, 1);
106365     sqlite3VdbeSetNumCols(v, 1);
106366     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "rows updated", SQLITE_STATIC);
106367   }
106368 
106369 update_cleanup:
106370   sqlite3AuthContextPop(&sContext);
106371   sqlite3DbFree(db, aXRef); /* Also frees aRegIdx[] and aToOpen[] */
106372   sqlite3SrcListDelete(db, pTabList);
106373   sqlite3ExprListDelete(db, pChanges);
106374   sqlite3ExprDelete(db, pWhere);
106375   return;
106376 }
106377 /* Make sure "isView" and other macros defined above are undefined. Otherwise
106378 ** thely may interfere with compilation of other functions in this file
106379 ** (or in another file, if this file becomes part of the amalgamation).  */
106380 #ifdef isView
106381  #undef isView
106382 #endif
106383 #ifdef pTrigger
106384  #undef pTrigger
106385 #endif
106386 
106387 #ifndef SQLITE_OMIT_VIRTUALTABLE
106388 /*
106389 ** Generate code for an UPDATE of a virtual table.
106390 **
106391 ** The strategy is that we create an ephemerial table that contains
106392 ** for each row to be changed:
106393 **
106394 **   (A)  The original rowid of that row.
106395 **   (B)  The revised rowid for the row. (note1)
106396 **   (C)  The content of every column in the row.
106397 **
106398 ** Then we loop over this ephemeral table and for each row in
106399 ** the ephermeral table call VUpdate.
106400 **
106401 ** When finished, drop the ephemeral table.
106402 **
106403 ** (note1) Actually, if we know in advance that (A) is always the same
106404 ** as (B) we only store (A), then duplicate (A) when pulling
106405 ** it out of the ephemeral table before calling VUpdate.
106406 */
106407 static void updateVirtualTable(
106408   Parse *pParse,       /* The parsing context */
106409   SrcList *pSrc,       /* The virtual table to be modified */
106410   Table *pTab,         /* The virtual table */
106411   ExprList *pChanges,  /* The columns to change in the UPDATE statement */
106412   Expr *pRowid,        /* Expression used to recompute the rowid */
106413   int *aXRef,          /* Mapping from columns of pTab to entries in pChanges */
106414   Expr *pWhere,        /* WHERE clause of the UPDATE statement */
106415   int onError          /* ON CONFLICT strategy */
106416 ){
106417   Vdbe *v = pParse->pVdbe;  /* Virtual machine under construction */
106418   ExprList *pEList = 0;     /* The result set of the SELECT statement */
106419   Select *pSelect = 0;      /* The SELECT statement */
106420   Expr *pExpr;              /* Temporary expression */
106421   int ephemTab;             /* Table holding the result of the SELECT */
106422   int i;                    /* Loop counter */
106423   int addr;                 /* Address of top of loop */
106424   int iReg;                 /* First register in set passed to OP_VUpdate */
106425   sqlite3 *db = pParse->db; /* Database connection */
106426   const char *pVTab = (const char*)sqlite3GetVTable(db, pTab);
106427   SelectDest dest;
106428 
106429   /* Construct the SELECT statement that will find the new values for
106430   ** all updated rows. 
106431   */
106432   pEList = sqlite3ExprListAppend(pParse, 0, sqlite3Expr(db, TK_ID, "_rowid_"));
106433   if( pRowid ){
106434     pEList = sqlite3ExprListAppend(pParse, pEList,
106435                                    sqlite3ExprDup(db, pRowid, 0));
106436   }
106437   assert( pTab->iPKey<0 );
106438   for(i=0; i<pTab->nCol; i++){
106439     if( aXRef[i]>=0 ){
106440       pExpr = sqlite3ExprDup(db, pChanges->a[aXRef[i]].pExpr, 0);
106441     }else{
106442       pExpr = sqlite3Expr(db, TK_ID, pTab->aCol[i].zName);
106443     }
106444     pEList = sqlite3ExprListAppend(pParse, pEList, pExpr);
106445   }
106446   pSelect = sqlite3SelectNew(pParse, pEList, pSrc, pWhere, 0, 0, 0, 0, 0, 0);
106447   
106448   /* Create the ephemeral table into which the update results will
106449   ** be stored.
106450   */
106451   assert( v );
106452   ephemTab = pParse->nTab++;
106453   sqlite3VdbeAddOp2(v, OP_OpenEphemeral, ephemTab, pTab->nCol+1+(pRowid!=0));
106454   sqlite3VdbeChangeP5(v, BTREE_UNORDERED);
106455 
106456   /* fill the ephemeral table 
106457   */
106458   sqlite3SelectDestInit(&dest, SRT_Table, ephemTab);
106459   sqlite3Select(pParse, pSelect, &dest);
106460 
106461   /* Generate code to scan the ephemeral table and call VUpdate. */
106462   iReg = ++pParse->nMem;
106463   pParse->nMem += pTab->nCol+1;
106464   addr = sqlite3VdbeAddOp2(v, OP_Rewind, ephemTab, 0);
106465   sqlite3VdbeAddOp3(v, OP_Column,  ephemTab, 0, iReg);
106466   sqlite3VdbeAddOp3(v, OP_Column, ephemTab, (pRowid?1:0), iReg+1);
106467   for(i=0; i<pTab->nCol; i++){
106468     sqlite3VdbeAddOp3(v, OP_Column, ephemTab, i+1+(pRowid!=0), iReg+2+i);
106469   }
106470   sqlite3VtabMakeWritable(pParse, pTab);
106471   sqlite3VdbeAddOp4(v, OP_VUpdate, 0, pTab->nCol+2, iReg, pVTab, P4_VTAB);
106472   sqlite3VdbeChangeP5(v, onError==OE_Default ? OE_Abort : onError);
106473   sqlite3MayAbort(pParse);
106474   sqlite3VdbeAddOp2(v, OP_Next, ephemTab, addr+1);
106475   sqlite3VdbeJumpHere(v, addr);
106476   sqlite3VdbeAddOp2(v, OP_Close, ephemTab, 0);
106477 
106478   /* Cleanup */
106479   sqlite3SelectDelete(db, pSelect);  
106480 }
106481 #endif /* SQLITE_OMIT_VIRTUALTABLE */
106482 
106483 /************** End of update.c **********************************************/
106484 /************** Begin file vacuum.c ******************************************/
106485 /*
106486 ** 2003 April 6
106487 **
106488 ** The author disclaims copyright to this source code.  In place of
106489 ** a legal notice, here is a blessing:
106490 **
106491 **    May you do good and not evil.
106492 **    May you find forgiveness for yourself and forgive others.
106493 **    May you share freely, never taking more than you give.
106494 **
106495 *************************************************************************
106496 ** This file contains code used to implement the VACUUM command.
106497 **
106498 ** Most of the code in this file may be omitted by defining the
106499 ** SQLITE_OMIT_VACUUM macro.
106500 */
106501 
106502 #if !defined(SQLITE_OMIT_VACUUM) && !defined(SQLITE_OMIT_ATTACH)
106503 /*
106504 ** Finalize a prepared statement.  If there was an error, store the
106505 ** text of the error message in *pzErrMsg.  Return the result code.
106506 */
106507 static int vacuumFinalize(sqlite3 *db, sqlite3_stmt *pStmt, char **pzErrMsg){
106508   int rc;
106509   rc = sqlite3VdbeFinalize((Vdbe*)pStmt);
106510   if( rc ){
106511     sqlite3SetString(pzErrMsg, db, sqlite3_errmsg(db));
106512   }
106513   return rc;
106514 }
106515 
106516 /*
106517 ** Execute zSql on database db. Return an error code.
106518 */
106519 static int execSql(sqlite3 *db, char **pzErrMsg, const char *zSql){
106520   sqlite3_stmt *pStmt;
106521   VVA_ONLY( int rc; )
106522   if( !zSql ){
106523     return SQLITE_NOMEM;
106524   }
106525   if( SQLITE_OK!=sqlite3_prepare(db, zSql, -1, &pStmt, 0) ){
106526     sqlite3SetString(pzErrMsg, db, sqlite3_errmsg(db));
106527     return sqlite3_errcode(db);
106528   }
106529   VVA_ONLY( rc = ) sqlite3_step(pStmt);
106530   assert( rc!=SQLITE_ROW || (db->flags&SQLITE_CountRows) );
106531   return vacuumFinalize(db, pStmt, pzErrMsg);
106532 }
106533 
106534 /*
106535 ** Execute zSql on database db. The statement returns exactly
106536 ** one column. Execute this as SQL on the same database.
106537 */
106538 static int execExecSql(sqlite3 *db, char **pzErrMsg, const char *zSql){
106539   sqlite3_stmt *pStmt;
106540   int rc;
106541 
106542   rc = sqlite3_prepare(db, zSql, -1, &pStmt, 0);
106543   if( rc!=SQLITE_OK ) return rc;
106544 
106545   while( SQLITE_ROW==sqlite3_step(pStmt) ){
106546     rc = execSql(db, pzErrMsg, (char*)sqlite3_column_text(pStmt, 0));
106547     if( rc!=SQLITE_OK ){
106548       vacuumFinalize(db, pStmt, pzErrMsg);
106549       return rc;
106550     }
106551   }
106552 
106553   return vacuumFinalize(db, pStmt, pzErrMsg);
106554 }
106555 
106556 /*
106557 ** The VACUUM command is used to clean up the database,
106558 ** collapse free space, etc.  It is modelled after the VACUUM command
106559 ** in PostgreSQL.  The VACUUM command works as follows:
106560 **
106561 **   (1)  Create a new transient database file
106562 **   (2)  Copy all content from the database being vacuumed into
106563 **        the new transient database file
106564 **   (3)  Copy content from the transient database back into the
106565 **        original database.
106566 **
106567 ** The transient database requires temporary disk space approximately
106568 ** equal to the size of the original database.  The copy operation of
106569 ** step (3) requires additional temporary disk space approximately equal
106570 ** to the size of the original database for the rollback journal.
106571 ** Hence, temporary disk space that is approximately 2x the size of the
106572 ** orginal database is required.  Every page of the database is written
106573 ** approximately 3 times:  Once for step (2) and twice for step (3).
106574 ** Two writes per page are required in step (3) because the original
106575 ** database content must be written into the rollback journal prior to
106576 ** overwriting the database with the vacuumed content.
106577 **
106578 ** Only 1x temporary space and only 1x writes would be required if
106579 ** the copy of step (3) were replace by deleting the original database
106580 ** and renaming the transient database as the original.  But that will
106581 ** not work if other processes are attached to the original database.
106582 ** And a power loss in between deleting the original and renaming the
106583 ** transient would cause the database file to appear to be deleted
106584 ** following reboot.
106585 */
106586 SQLITE_PRIVATE void sqlite3Vacuum(Parse *pParse){
106587   Vdbe *v = sqlite3GetVdbe(pParse);
106588   if( v ){
106589     sqlite3VdbeAddOp2(v, OP_Vacuum, 0, 0);
106590     sqlite3VdbeUsesBtree(v, 0);
106591   }
106592   return;
106593 }
106594 
106595 /*
106596 ** This routine implements the OP_Vacuum opcode of the VDBE.
106597 */
106598 SQLITE_PRIVATE int sqlite3RunVacuum(char **pzErrMsg, sqlite3 *db){
106599   int rc = SQLITE_OK;     /* Return code from service routines */
106600   Btree *pMain;           /* The database being vacuumed */
106601   Btree *pTemp;           /* The temporary database we vacuum into */
106602   char *zSql = 0;         /* SQL statements */
106603   int saved_flags;        /* Saved value of the db->flags */
106604   int saved_nChange;      /* Saved value of db->nChange */
106605   int saved_nTotalChange; /* Saved value of db->nTotalChange */
106606   void (*saved_xTrace)(void*,const char*);  /* Saved db->xTrace */
106607   Db *pDb = 0;            /* Database to detach at end of vacuum */
106608   int isMemDb;            /* True if vacuuming a :memory: database */
106609   int nRes;               /* Bytes of reserved space at the end of each page */
106610   int nDb;                /* Number of attached databases */
106611 
106612   if( !db->autoCommit ){
106613     sqlite3SetString(pzErrMsg, db, "cannot VACUUM from within a transaction");
106614     return SQLITE_ERROR;
106615   }
106616   if( db->nVdbeActive>1 ){
106617     sqlite3SetString(pzErrMsg, db,"cannot VACUUM - SQL statements in progress");
106618     return SQLITE_ERROR;
106619   }
106620 
106621   /* Save the current value of the database flags so that it can be 
106622   ** restored before returning. Then set the writable-schema flag, and
106623   ** disable CHECK and foreign key constraints.  */
106624   saved_flags = db->flags;
106625   saved_nChange = db->nChange;
106626   saved_nTotalChange = db->nTotalChange;
106627   saved_xTrace = db->xTrace;
106628   db->flags |= SQLITE_WriteSchema | SQLITE_IgnoreChecks | SQLITE_PreferBuiltin;
106629   db->flags &= ~(SQLITE_ForeignKeys | SQLITE_ReverseOrder);
106630   db->xTrace = 0;
106631 
106632   pMain = db->aDb[0].pBt;
106633   isMemDb = sqlite3PagerIsMemdb(sqlite3BtreePager(pMain));
106634 
106635   /* Attach the temporary database as 'vacuum_db'. The synchronous pragma
106636   ** can be set to 'off' for this file, as it is not recovered if a crash
106637   ** occurs anyway. The integrity of the database is maintained by a
106638   ** (possibly synchronous) transaction opened on the main database before
106639   ** sqlite3BtreeCopyFile() is called.
106640   **
106641   ** An optimisation would be to use a non-journaled pager.
106642   ** (Later:) I tried setting "PRAGMA vacuum_db.journal_mode=OFF" but
106643   ** that actually made the VACUUM run slower.  Very little journalling
106644   ** actually occurs when doing a vacuum since the vacuum_db is initially
106645   ** empty.  Only the journal header is written.  Apparently it takes more
106646   ** time to parse and run the PRAGMA to turn journalling off than it does
106647   ** to write the journal header file.
106648   */
106649   nDb = db->nDb;
106650   if( sqlite3TempInMemory(db) ){
106651     zSql = "ATTACH ':memory:' AS vacuum_db;";
106652   }else{
106653     zSql = "ATTACH '' AS vacuum_db;";
106654   }
106655   rc = execSql(db, pzErrMsg, zSql);
106656   if( db->nDb>nDb ){
106657     pDb = &db->aDb[db->nDb-1];
106658     assert( strcmp(pDb->zName,"vacuum_db")==0 );
106659   }
106660   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106661   pTemp = db->aDb[db->nDb-1].pBt;
106662 
106663   /* The call to execSql() to attach the temp database has left the file
106664   ** locked (as there was more than one active statement when the transaction
106665   ** to read the schema was concluded. Unlock it here so that this doesn't
106666   ** cause problems for the call to BtreeSetPageSize() below.  */
106667   sqlite3BtreeCommit(pTemp);
106668 
106669   nRes = sqlite3BtreeGetReserve(pMain);
106670 
106671   /* A VACUUM cannot change the pagesize of an encrypted database. */
106672 #ifdef SQLITE_HAS_CODEC
106673   if( db->nextPagesize ){
106674     extern void sqlite3CodecGetKey(sqlite3*, int, void**, int*);
106675     int nKey;
106676     char *zKey;
106677     sqlite3CodecGetKey(db, 0, (void**)&zKey, &nKey);
106678     if( nKey ) db->nextPagesize = 0;
106679   }
106680 #endif
106681 
106682   rc = execSql(db, pzErrMsg, "PRAGMA vacuum_db.synchronous=OFF");
106683   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106684 
106685   /* Begin a transaction and take an exclusive lock on the main database
106686   ** file. This is done before the sqlite3BtreeGetPageSize(pMain) call below,
106687   ** to ensure that we do not try to change the page-size on a WAL database.
106688   */
106689   rc = execSql(db, pzErrMsg, "BEGIN;");
106690   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106691   rc = sqlite3BtreeBeginTrans(pMain, 2);
106692   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106693 
106694   /* Do not attempt to change the page size for a WAL database */
106695   if( sqlite3PagerGetJournalMode(sqlite3BtreePager(pMain))
106696                                                ==PAGER_JOURNALMODE_WAL ){
106697     db->nextPagesize = 0;
106698   }
106699 
106700   if( sqlite3BtreeSetPageSize(pTemp, sqlite3BtreeGetPageSize(pMain), nRes, 0)
106701    || (!isMemDb && sqlite3BtreeSetPageSize(pTemp, db->nextPagesize, nRes, 0))
106702    || NEVER(db->mallocFailed)
106703   ){
106704     rc = SQLITE_NOMEM;
106705     goto end_of_vacuum;
106706   }
106707 
106708 #ifndef SQLITE_OMIT_AUTOVACUUM
106709   sqlite3BtreeSetAutoVacuum(pTemp, db->nextAutovac>=0 ? db->nextAutovac :
106710                                            sqlite3BtreeGetAutoVacuum(pMain));
106711 #endif
106712 
106713   /* Query the schema of the main database. Create a mirror schema
106714   ** in the temporary database.
106715   */
106716   rc = execExecSql(db, pzErrMsg,
106717       "SELECT 'CREATE TABLE vacuum_db.' || substr(sql,14) "
106718       "  FROM sqlite_master WHERE type='table' AND name!='sqlite_sequence'"
106719       "   AND coalesce(rootpage,1)>0"
106720   );
106721   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106722   rc = execExecSql(db, pzErrMsg,
106723       "SELECT 'CREATE INDEX vacuum_db.' || substr(sql,14)"
106724       "  FROM sqlite_master WHERE sql LIKE 'CREATE INDEX %' ");
106725   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106726   rc = execExecSql(db, pzErrMsg,
106727       "SELECT 'CREATE UNIQUE INDEX vacuum_db.' || substr(sql,21) "
106728       "  FROM sqlite_master WHERE sql LIKE 'CREATE UNIQUE INDEX %'");
106729   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106730 
106731   /* Loop through the tables in the main database. For each, do
106732   ** an "INSERT INTO vacuum_db.xxx SELECT * FROM main.xxx;" to copy
106733   ** the contents to the temporary database.
106734   */
106735   rc = execExecSql(db, pzErrMsg,
106736       "SELECT 'INSERT INTO vacuum_db.' || quote(name) "
106737       "|| ' SELECT * FROM main.' || quote(name) || ';'"
106738       "FROM main.sqlite_master "
106739       "WHERE type = 'table' AND name!='sqlite_sequence' "
106740       "  AND coalesce(rootpage,1)>0"
106741   );
106742   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106743 
106744   /* Copy over the sequence table
106745   */
106746   rc = execExecSql(db, pzErrMsg,
106747       "SELECT 'DELETE FROM vacuum_db.' || quote(name) || ';' "
106748       "FROM vacuum_db.sqlite_master WHERE name='sqlite_sequence' "
106749   );
106750   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106751   rc = execExecSql(db, pzErrMsg,
106752       "SELECT 'INSERT INTO vacuum_db.' || quote(name) "
106753       "|| ' SELECT * FROM main.' || quote(name) || ';' "
106754       "FROM vacuum_db.sqlite_master WHERE name=='sqlite_sequence';"
106755   );
106756   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106757 
106758 
106759   /* Copy the triggers, views, and virtual tables from the main database
106760   ** over to the temporary database.  None of these objects has any
106761   ** associated storage, so all we have to do is copy their entries
106762   ** from the SQLITE_MASTER table.
106763   */
106764   rc = execSql(db, pzErrMsg,
106765       "INSERT INTO vacuum_db.sqlite_master "
106766       "  SELECT type, name, tbl_name, rootpage, sql"
106767       "    FROM main.sqlite_master"
106768       "   WHERE type='view' OR type='trigger'"
106769       "      OR (type='table' AND rootpage=0)"
106770   );
106771   if( rc ) goto end_of_vacuum;
106772 
106773   /* At this point, there is a write transaction open on both the 
106774   ** vacuum database and the main database. Assuming no error occurs,
106775   ** both transactions are closed by this block - the main database
106776   ** transaction by sqlite3BtreeCopyFile() and the other by an explicit
106777   ** call to sqlite3BtreeCommit().
106778   */
106779   {
106780     u32 meta;
106781     int i;
106782 
106783     /* This array determines which meta meta values are preserved in the
106784     ** vacuum.  Even entries are the meta value number and odd entries
106785     ** are an increment to apply to the meta value after the vacuum.
106786     ** The increment is used to increase the schema cookie so that other
106787     ** connections to the same database will know to reread the schema.
106788     */
106789     static const unsigned char aCopy[] = {
106790        BTREE_SCHEMA_VERSION,     1,  /* Add one to the old schema cookie */
106791        BTREE_DEFAULT_CACHE_SIZE, 0,  /* Preserve the default page cache size */
106792        BTREE_TEXT_ENCODING,      0,  /* Preserve the text encoding */
106793        BTREE_USER_VERSION,       0,  /* Preserve the user version */
106794        BTREE_APPLICATION_ID,     0,  /* Preserve the application id */
106795     };
106796 
106797     assert( 1==sqlite3BtreeIsInTrans(pTemp) );
106798     assert( 1==sqlite3BtreeIsInTrans(pMain) );
106799 
106800     /* Copy Btree meta values */
106801     for(i=0; i<ArraySize(aCopy); i+=2){
106802       /* GetMeta() and UpdateMeta() cannot fail in this context because
106803       ** we already have page 1 loaded into cache and marked dirty. */
106804       sqlite3BtreeGetMeta(pMain, aCopy[i], &meta);
106805       rc = sqlite3BtreeUpdateMeta(pTemp, aCopy[i], meta+aCopy[i+1]);
106806       if( NEVER(rc!=SQLITE_OK) ) goto end_of_vacuum;
106807     }
106808 
106809     rc = sqlite3BtreeCopyFile(pMain, pTemp);
106810     if( rc!=SQLITE_OK ) goto end_of_vacuum;
106811     rc = sqlite3BtreeCommit(pTemp);
106812     if( rc!=SQLITE_OK ) goto end_of_vacuum;
106813 #ifndef SQLITE_OMIT_AUTOVACUUM
106814     sqlite3BtreeSetAutoVacuum(pMain, sqlite3BtreeGetAutoVacuum(pTemp));
106815 #endif
106816   }
106817 
106818   assert( rc==SQLITE_OK );
106819   rc = sqlite3BtreeSetPageSize(pMain, sqlite3BtreeGetPageSize(pTemp), nRes,1);
106820 
106821 end_of_vacuum:
106822   /* Restore the original value of db->flags */
106823   db->flags = saved_flags;
106824   db->nChange = saved_nChange;
106825   db->nTotalChange = saved_nTotalChange;
106826   db->xTrace = saved_xTrace;
106827   sqlite3BtreeSetPageSize(pMain, -1, -1, 1);
106828 
106829   /* Currently there is an SQL level transaction open on the vacuum
106830   ** database. No locks are held on any other files (since the main file
106831   ** was committed at the btree level). So it safe to end the transaction
106832   ** by manually setting the autoCommit flag to true and detaching the
106833   ** vacuum database. The vacuum_db journal file is deleted when the pager
106834   ** is closed by the DETACH.
106835   */
106836   db->autoCommit = 1;
106837 
106838   if( pDb ){
106839     sqlite3BtreeClose(pDb->pBt);
106840     pDb->pBt = 0;
106841     pDb->pSchema = 0;
106842   }
106843 
106844   /* This both clears the schemas and reduces the size of the db->aDb[]
106845   ** array. */ 
106846   sqlite3ResetAllSchemasOfConnection(db);
106847 
106848   return rc;
106849 }
106850 
106851 #endif  /* SQLITE_OMIT_VACUUM && SQLITE_OMIT_ATTACH */
106852 
106853 /************** End of vacuum.c **********************************************/
106854 /************** Begin file vtab.c ********************************************/
106855 /*
106856 ** 2006 June 10
106857 **
106858 ** The author disclaims copyright to this source code.  In place of
106859 ** a legal notice, here is a blessing:
106860 **
106861 **    May you do good and not evil.
106862 **    May you find forgiveness for yourself and forgive others.
106863 **    May you share freely, never taking more than you give.
106864 **
106865 *************************************************************************
106866 ** This file contains code used to help implement virtual tables.
106867 */
106868 #ifndef SQLITE_OMIT_VIRTUALTABLE
106869 
106870 /*
106871 ** Before a virtual table xCreate() or xConnect() method is invoked, the
106872 ** sqlite3.pVtabCtx member variable is set to point to an instance of
106873 ** this struct allocated on the stack. It is used by the implementation of 
106874 ** the sqlite3_declare_vtab() and sqlite3_vtab_config() APIs, both of which
106875 ** are invoked only from within xCreate and xConnect methods.
106876 */
106877 struct VtabCtx {
106878   VTable *pVTable;    /* The virtual table being constructed */
106879   Table *pTab;        /* The Table object to which the virtual table belongs */
106880 };
106881 
106882 /*
106883 ** The actual function that does the work of creating a new module.
106884 ** This function implements the sqlite3_create_module() and
106885 ** sqlite3_create_module_v2() interfaces.
106886 */
106887 static int createModule(
106888   sqlite3 *db,                    /* Database in which module is registered */
106889   const char *zName,              /* Name assigned to this module */
106890   const sqlite3_module *pModule,  /* The definition of the module */
106891   void *pAux,                     /* Context pointer for xCreate/xConnect */
106892   void (*xDestroy)(void *)        /* Module destructor function */
106893 ){
106894   int rc = SQLITE_OK;
106895   int nName;
106896 
106897   sqlite3_mutex_enter(db->mutex);
106898   nName = sqlite3Strlen30(zName);
106899   if( sqlite3HashFind(&db->aModule, zName, nName) ){
106900     rc = SQLITE_MISUSE_BKPT;
106901   }else{
106902     Module *pMod;
106903     pMod = (Module *)sqlite3DbMallocRaw(db, sizeof(Module) + nName + 1);
106904     if( pMod ){
106905       Module *pDel;
106906       char *zCopy = (char *)(&pMod[1]);
106907       memcpy(zCopy, zName, nName+1);
106908       pMod->zName = zCopy;
106909       pMod->pModule = pModule;
106910       pMod->pAux = pAux;
106911       pMod->xDestroy = xDestroy;
106912       pDel = (Module *)sqlite3HashInsert(&db->aModule,zCopy,nName,(void*)pMod);
106913       assert( pDel==0 || pDel==pMod );
106914       if( pDel ){
106915         db->mallocFailed = 1;
106916         sqlite3DbFree(db, pDel);
106917       }
106918     }
106919   }
106920   rc = sqlite3ApiExit(db, rc);
106921   if( rc!=SQLITE_OK && xDestroy ) xDestroy(pAux);
106922 
106923   sqlite3_mutex_leave(db->mutex);
106924   return rc;
106925 }
106926 
106927 
106928 /*
106929 ** External API function used to create a new virtual-table module.
106930 */
106931 SQLITE_API int sqlite3_create_module(
106932   sqlite3 *db,                    /* Database in which module is registered */
106933   const char *zName,              /* Name assigned to this module */
106934   const sqlite3_module *pModule,  /* The definition of the module */
106935   void *pAux                      /* Context pointer for xCreate/xConnect */
106936 ){
106937   return createModule(db, zName, pModule, pAux, 0);
106938 }
106939 
106940 /*
106941 ** External API function used to create a new virtual-table module.
106942 */
106943 SQLITE_API int sqlite3_create_module_v2(
106944   sqlite3 *db,                    /* Database in which module is registered */
106945   const char *zName,              /* Name assigned to this module */
106946   const sqlite3_module *pModule,  /* The definition of the module */
106947   void *pAux,                     /* Context pointer for xCreate/xConnect */
106948   void (*xDestroy)(void *)        /* Module destructor function */
106949 ){
106950   return createModule(db, zName, pModule, pAux, xDestroy);
106951 }
106952 
106953 /*
106954 ** Lock the virtual table so that it cannot be disconnected.
106955 ** Locks nest.  Every lock should have a corresponding unlock.
106956 ** If an unlock is omitted, resources leaks will occur.  
106957 **
106958 ** If a disconnect is attempted while a virtual table is locked,
106959 ** the disconnect is deferred until all locks have been removed.
106960 */
106961 SQLITE_PRIVATE void sqlite3VtabLock(VTable *pVTab){
106962   pVTab->nRef++;
106963 }
106964 
106965 
106966 /*
106967 ** pTab is a pointer to a Table structure representing a virtual-table.
106968 ** Return a pointer to the VTable object used by connection db to access 
106969 ** this virtual-table, if one has been created, or NULL otherwise.
106970 */
106971 SQLITE_PRIVATE VTable *sqlite3GetVTable(sqlite3 *db, Table *pTab){
106972   VTable *pVtab;
106973   assert( IsVirtual(pTab) );
106974   for(pVtab=pTab->pVTable; pVtab && pVtab->db!=db; pVtab=pVtab->pNext);
106975   return pVtab;
106976 }
106977 
106978 /*
106979 ** Decrement the ref-count on a virtual table object. When the ref-count
106980 ** reaches zero, call the xDisconnect() method to delete the object.
106981 */
106982 SQLITE_PRIVATE void sqlite3VtabUnlock(VTable *pVTab){
106983   sqlite3 *db = pVTab->db;
106984 
106985   assert( db );
106986   assert( pVTab->nRef>0 );
106987   assert( db->magic==SQLITE_MAGIC_OPEN || db->magic==SQLITE_MAGIC_ZOMBIE );
106988 
106989   pVTab->nRef--;
106990   if( pVTab->nRef==0 ){
106991     sqlite3_vtab *p = pVTab->pVtab;
106992     if( p ){
106993       p->pModule->xDisconnect(p);
106994     }
106995     sqlite3DbFree(db, pVTab);
106996   }
106997 }
106998 
106999 /*
107000 ** Table p is a virtual table. This function moves all elements in the
107001 ** p->pVTable list to the sqlite3.pDisconnect lists of their associated
107002 ** database connections to be disconnected at the next opportunity. 
107003 ** Except, if argument db is not NULL, then the entry associated with
107004 ** connection db is left in the p->pVTable list.
107005 */
107006 static VTable *vtabDisconnectAll(sqlite3 *db, Table *p){
107007   VTable *pRet = 0;
107008   VTable *pVTable = p->pVTable;
107009   p->pVTable = 0;
107010 
107011   /* Assert that the mutex (if any) associated with the BtShared database 
107012   ** that contains table p is held by the caller. See header comments 
107013   ** above function sqlite3VtabUnlockList() for an explanation of why
107014   ** this makes it safe to access the sqlite3.pDisconnect list of any
107015   ** database connection that may have an entry in the p->pVTable list.
107016   */
107017   assert( db==0 || sqlite3SchemaMutexHeld(db, 0, p->pSchema) );
107018 
107019   while( pVTable ){
107020     sqlite3 *db2 = pVTable->db;
107021     VTable *pNext = pVTable->pNext;
107022     assert( db2 );
107023     if( db2==db ){
107024       pRet = pVTable;
107025       p->pVTable = pRet;
107026       pRet->pNext = 0;
107027     }else{
107028       pVTable->pNext = db2->pDisconnect;
107029       db2->pDisconnect = pVTable;
107030     }
107031     pVTable = pNext;
107032   }
107033 
107034   assert( !db || pRet );
107035   return pRet;
107036 }
107037 
107038 /*
107039 ** Table *p is a virtual table. This function removes the VTable object
107040 ** for table *p associated with database connection db from the linked
107041 ** list in p->pVTab. It also decrements the VTable ref count. This is
107042 ** used when closing database connection db to free all of its VTable
107043 ** objects without disturbing the rest of the Schema object (which may
107044 ** be being used by other shared-cache connections).
107045 */
107046 SQLITE_PRIVATE void sqlite3VtabDisconnect(sqlite3 *db, Table *p){
107047   VTable **ppVTab;
107048 
107049   assert( IsVirtual(p) );
107050   assert( sqlite3BtreeHoldsAllMutexes(db) );
107051   assert( sqlite3_mutex_held(db->mutex) );
107052 
107053   for(ppVTab=&p->pVTable; *ppVTab; ppVTab=&(*ppVTab)->pNext){
107054     if( (*ppVTab)->db==db  ){
107055       VTable *pVTab = *ppVTab;
107056       *ppVTab = pVTab->pNext;
107057       sqlite3VtabUnlock(pVTab);
107058       break;
107059     }
107060   }
107061 }
107062 
107063 
107064 /*
107065 ** Disconnect all the virtual table objects in the sqlite3.pDisconnect list.
107066 **
107067 ** This function may only be called when the mutexes associated with all
107068 ** shared b-tree databases opened using connection db are held by the 
107069 ** caller. This is done to protect the sqlite3.pDisconnect list. The
107070 ** sqlite3.pDisconnect list is accessed only as follows:
107071 **
107072 **   1) By this function. In this case, all BtShared mutexes and the mutex
107073 **      associated with the database handle itself must be held.
107074 **
107075 **   2) By function vtabDisconnectAll(), when it adds a VTable entry to
107076 **      the sqlite3.pDisconnect list. In this case either the BtShared mutex
107077 **      associated with the database the virtual table is stored in is held
107078 **      or, if the virtual table is stored in a non-sharable database, then
107079 **      the database handle mutex is held.
107080 **
107081 ** As a result, a sqlite3.pDisconnect cannot be accessed simultaneously 
107082 ** by multiple threads. It is thread-safe.
107083 */
107084 SQLITE_PRIVATE void sqlite3VtabUnlockList(sqlite3 *db){
107085   VTable *p = db->pDisconnect;
107086   db->pDisconnect = 0;
107087 
107088   assert( sqlite3BtreeHoldsAllMutexes(db) );
107089   assert( sqlite3_mutex_held(db->mutex) );
107090 
107091   if( p ){
107092     sqlite3ExpirePreparedStatements(db);
107093     do {
107094       VTable *pNext = p->pNext;
107095       sqlite3VtabUnlock(p);
107096       p = pNext;
107097     }while( p );
107098   }
107099 }
107100 
107101 /*
107102 ** Clear any and all virtual-table information from the Table record.
107103 ** This routine is called, for example, just before deleting the Table
107104 ** record.
107105 **
107106 ** Since it is a virtual-table, the Table structure contains a pointer
107107 ** to the head of a linked list of VTable structures. Each VTable 
107108 ** structure is associated with a single sqlite3* user of the schema.
107109 ** The reference count of the VTable structure associated with database 
107110 ** connection db is decremented immediately (which may lead to the 
107111 ** structure being xDisconnected and free). Any other VTable structures
107112 ** in the list are moved to the sqlite3.pDisconnect list of the associated 
107113 ** database connection.
107114 */
107115 SQLITE_PRIVATE void sqlite3VtabClear(sqlite3 *db, Table *p){
107116   if( !db || db->pnBytesFreed==0 ) vtabDisconnectAll(0, p);
107117   if( p->azModuleArg ){
107118     int i;
107119     for(i=0; i<p->nModuleArg; i++){
107120       if( i!=1 ) sqlite3DbFree(db, p->azModuleArg[i]);
107121     }
107122     sqlite3DbFree(db, p->azModuleArg);
107123   }
107124 }
107125 
107126 /*
107127 ** Add a new module argument to pTable->azModuleArg[].
107128 ** The string is not copied - the pointer is stored.  The
107129 ** string will be freed automatically when the table is
107130 ** deleted.
107131 */
107132 static void addModuleArgument(sqlite3 *db, Table *pTable, char *zArg){
107133   int i = pTable->nModuleArg++;
107134   int nBytes = sizeof(char *)*(1+pTable->nModuleArg);
107135   char **azModuleArg;
107136   azModuleArg = sqlite3DbRealloc(db, pTable->azModuleArg, nBytes);
107137   if( azModuleArg==0 ){
107138     int j;
107139     for(j=0; j<i; j++){
107140       sqlite3DbFree(db, pTable->azModuleArg[j]);
107141     }
107142     sqlite3DbFree(db, zArg);
107143     sqlite3DbFree(db, pTable->azModuleArg);
107144     pTable->nModuleArg = 0;
107145   }else{
107146     azModuleArg[i] = zArg;
107147     azModuleArg[i+1] = 0;
107148   }
107149   pTable->azModuleArg = azModuleArg;
107150 }
107151 
107152 /*
107153 ** The parser calls this routine when it first sees a CREATE VIRTUAL TABLE
107154 ** statement.  The module name has been parsed, but the optional list
107155 ** of parameters that follow the module name are still pending.
107156 */
107157 SQLITE_PRIVATE void sqlite3VtabBeginParse(
107158   Parse *pParse,        /* Parsing context */
107159   Token *pName1,        /* Name of new table, or database name */
107160   Token *pName2,        /* Name of new table or NULL */
107161   Token *pModuleName,   /* Name of the module for the virtual table */
107162   int ifNotExists       /* No error if the table already exists */
107163 ){
107164   int iDb;              /* The database the table is being created in */
107165   Table *pTable;        /* The new virtual table */
107166   sqlite3 *db;          /* Database connection */
107167 
107168   sqlite3StartTable(pParse, pName1, pName2, 0, 0, 1, ifNotExists);
107169   pTable = pParse->pNewTable;
107170   if( pTable==0 ) return;
107171   assert( 0==pTable->pIndex );
107172 
107173   db = pParse->db;
107174   iDb = sqlite3SchemaToIndex(db, pTable->pSchema);
107175   assert( iDb>=0 );
107176 
107177   pTable->tabFlags |= TF_Virtual;
107178   pTable->nModuleArg = 0;
107179   addModuleArgument(db, pTable, sqlite3NameFromToken(db, pModuleName));
107180   addModuleArgument(db, pTable, 0);
107181   addModuleArgument(db, pTable, sqlite3DbStrDup(db, pTable->zName));
107182   pParse->sNameToken.n = (int)(&pModuleName->z[pModuleName->n] - pName1->z);
107183 
107184 #ifndef SQLITE_OMIT_AUTHORIZATION
107185   /* Creating a virtual table invokes the authorization callback twice.
107186   ** The first invocation, to obtain permission to INSERT a row into the
107187   ** sqlite_master table, has already been made by sqlite3StartTable().
107188   ** The second call, to obtain permission to create the table, is made now.
107189   */
107190   if( pTable->azModuleArg ){
107191     sqlite3AuthCheck(pParse, SQLITE_CREATE_VTABLE, pTable->zName, 
107192             pTable->azModuleArg[0], pParse->db->aDb[iDb].zName);
107193   }
107194 #endif
107195 }
107196 
107197 /*
107198 ** This routine takes the module argument that has been accumulating
107199 ** in pParse->zArg[] and appends it to the list of arguments on the
107200 ** virtual table currently under construction in pParse->pTable.
107201 */
107202 static void addArgumentToVtab(Parse *pParse){
107203   if( pParse->sArg.z && pParse->pNewTable ){
107204     const char *z = (const char*)pParse->sArg.z;
107205     int n = pParse->sArg.n;
107206     sqlite3 *db = pParse->db;
107207     addModuleArgument(db, pParse->pNewTable, sqlite3DbStrNDup(db, z, n));
107208   }
107209 }
107210 
107211 /*
107212 ** The parser calls this routine after the CREATE VIRTUAL TABLE statement
107213 ** has been completely parsed.
107214 */
107215 SQLITE_PRIVATE void sqlite3VtabFinishParse(Parse *pParse, Token *pEnd){
107216   Table *pTab = pParse->pNewTable;  /* The table being constructed */
107217   sqlite3 *db = pParse->db;         /* The database connection */
107218 
107219   if( pTab==0 ) return;
107220   addArgumentToVtab(pParse);
107221   pParse->sArg.z = 0;
107222   if( pTab->nModuleArg<1 ) return;
107223   
107224   /* If the CREATE VIRTUAL TABLE statement is being entered for the
107225   ** first time (in other words if the virtual table is actually being
107226   ** created now instead of just being read out of sqlite_master) then
107227   ** do additional initialization work and store the statement text
107228   ** in the sqlite_master table.
107229   */
107230   if( !db->init.busy ){
107231     char *zStmt;
107232     char *zWhere;
107233     int iDb;
107234     Vdbe *v;
107235 
107236     /* Compute the complete text of the CREATE VIRTUAL TABLE statement */
107237     if( pEnd ){
107238       pParse->sNameToken.n = (int)(pEnd->z - pParse->sNameToken.z) + pEnd->n;
107239     }
107240     zStmt = sqlite3MPrintf(db, "CREATE VIRTUAL TABLE %T", &pParse->sNameToken);
107241 
107242     /* A slot for the record has already been allocated in the 
107243     ** SQLITE_MASTER table.  We just need to update that slot with all
107244     ** the information we've collected.  
107245     **
107246     ** The VM register number pParse->regRowid holds the rowid of an
107247     ** entry in the sqlite_master table tht was created for this vtab
107248     ** by sqlite3StartTable().
107249     */
107250     iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
107251     sqlite3NestedParse(pParse,
107252       "UPDATE %Q.%s "
107253          "SET type='table', name=%Q, tbl_name=%Q, rootpage=0, sql=%Q "
107254        "WHERE rowid=#%d",
107255       db->aDb[iDb].zName, SCHEMA_TABLE(iDb),
107256       pTab->zName,
107257       pTab->zName,
107258       zStmt,
107259       pParse->regRowid
107260     );
107261     sqlite3DbFree(db, zStmt);
107262     v = sqlite3GetVdbe(pParse);
107263     sqlite3ChangeCookie(pParse, iDb);
107264 
107265     sqlite3VdbeAddOp2(v, OP_Expire, 0, 0);
107266     zWhere = sqlite3MPrintf(db, "name='%q' AND type='table'", pTab->zName);
107267     sqlite3VdbeAddParseSchemaOp(v, iDb, zWhere);
107268     sqlite3VdbeAddOp4(v, OP_VCreate, iDb, 0, 0, 
107269                          pTab->zName, sqlite3Strlen30(pTab->zName) + 1);
107270   }
107271 
107272   /* If we are rereading the sqlite_master table create the in-memory
107273   ** record of the table. The xConnect() method is not called until
107274   ** the first time the virtual table is used in an SQL statement. This
107275   ** allows a schema that contains virtual tables to be loaded before
107276   ** the required virtual table implementations are registered.  */
107277   else {
107278     Table *pOld;
107279     Schema *pSchema = pTab->pSchema;
107280     const char *zName = pTab->zName;
107281     int nName = sqlite3Strlen30(zName);
107282     assert( sqlite3SchemaMutexHeld(db, 0, pSchema) );
107283     pOld = sqlite3HashInsert(&pSchema->tblHash, zName, nName, pTab);
107284     if( pOld ){
107285       db->mallocFailed = 1;
107286       assert( pTab==pOld );  /* Malloc must have failed inside HashInsert() */
107287       return;
107288     }
107289     pParse->pNewTable = 0;
107290   }
107291 }
107292 
107293 /*
107294 ** The parser calls this routine when it sees the first token
107295 ** of an argument to the module name in a CREATE VIRTUAL TABLE statement.
107296 */
107297 SQLITE_PRIVATE void sqlite3VtabArgInit(Parse *pParse){
107298   addArgumentToVtab(pParse);
107299   pParse->sArg.z = 0;
107300   pParse->sArg.n = 0;
107301 }
107302 
107303 /*
107304 ** The parser calls this routine for each token after the first token
107305 ** in an argument to the module name in a CREATE VIRTUAL TABLE statement.
107306 */
107307 SQLITE_PRIVATE void sqlite3VtabArgExtend(Parse *pParse, Token *p){
107308   Token *pArg = &pParse->sArg;
107309   if( pArg->z==0 ){
107310     pArg->z = p->z;
107311     pArg->n = p->n;
107312   }else{
107313     assert(pArg->z < p->z);
107314     pArg->n = (int)(&p->z[p->n] - pArg->z);
107315   }
107316 }
107317 
107318 /*
107319 ** Invoke a virtual table constructor (either xCreate or xConnect). The
107320 ** pointer to the function to invoke is passed as the fourth parameter
107321 ** to this procedure.
107322 */
107323 static int vtabCallConstructor(
107324   sqlite3 *db, 
107325   Table *pTab,
107326   Module *pMod,
107327   int (*xConstruct)(sqlite3*,void*,int,const char*const*,sqlite3_vtab**,char**),
107328   char **pzErr
107329 ){
107330   VtabCtx sCtx, *pPriorCtx;
107331   VTable *pVTable;
107332   int rc;
107333   const char *const*azArg = (const char *const*)pTab->azModuleArg;
107334   int nArg = pTab->nModuleArg;
107335   char *zErr = 0;
107336   char *zModuleName = sqlite3MPrintf(db, "%s", pTab->zName);
107337   int iDb;
107338 
107339   if( !zModuleName ){
107340     return SQLITE_NOMEM;
107341   }
107342 
107343   pVTable = sqlite3DbMallocZero(db, sizeof(VTable));
107344   if( !pVTable ){
107345     sqlite3DbFree(db, zModuleName);
107346     return SQLITE_NOMEM;
107347   }
107348   pVTable->db = db;
107349   pVTable->pMod = pMod;
107350 
107351   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
107352   pTab->azModuleArg[1] = db->aDb[iDb].zName;
107353 
107354   /* Invoke the virtual table constructor */
107355   assert( &db->pVtabCtx );
107356   assert( xConstruct );
107357   sCtx.pTab = pTab;
107358   sCtx.pVTable = pVTable;
107359   pPriorCtx = db->pVtabCtx;
107360   db->pVtabCtx = &sCtx;
107361   rc = xConstruct(db, pMod->pAux, nArg, azArg, &pVTable->pVtab, &zErr);
107362   db->pVtabCtx = pPriorCtx;
107363   if( rc==SQLITE_NOMEM ) db->mallocFailed = 1;
107364 
107365   if( SQLITE_OK!=rc ){
107366     if( zErr==0 ){
107367       *pzErr = sqlite3MPrintf(db, "vtable constructor failed: %s", zModuleName);
107368     }else {
107369       *pzErr = sqlite3MPrintf(db, "%s", zErr);
107370       sqlite3_free(zErr);
107371     }
107372     sqlite3DbFree(db, pVTable);
107373   }else if( ALWAYS(pVTable->pVtab) ){
107374     /* Justification of ALWAYS():  A correct vtab constructor must allocate
107375     ** the sqlite3_vtab object if successful.  */
107376     pVTable->pVtab->pModule = pMod->pModule;
107377     pVTable->nRef = 1;
107378     if( sCtx.pTab ){
107379       const char *zFormat = "vtable constructor did not declare schema: %s";
107380       *pzErr = sqlite3MPrintf(db, zFormat, pTab->zName);
107381       sqlite3VtabUnlock(pVTable);
107382       rc = SQLITE_ERROR;
107383     }else{
107384       int iCol;
107385       /* If everything went according to plan, link the new VTable structure
107386       ** into the linked list headed by pTab->pVTable. Then loop through the 
107387       ** columns of the table to see if any of them contain the token "hidden".
107388       ** If so, set the Column COLFLAG_HIDDEN flag and remove the token from
107389       ** the type string.  */
107390       pVTable->pNext = pTab->pVTable;
107391       pTab->pVTable = pVTable;
107392 
107393       for(iCol=0; iCol<pTab->nCol; iCol++){
107394         char *zType = pTab->aCol[iCol].zType;
107395         int nType;
107396         int i = 0;
107397         if( !zType ) continue;
107398         nType = sqlite3Strlen30(zType);
107399         if( sqlite3StrNICmp("hidden", zType, 6)||(zType[6] && zType[6]!=' ') ){
107400           for(i=0; i<nType; i++){
107401             if( (0==sqlite3StrNICmp(" hidden", &zType[i], 7))
107402              && (zType[i+7]=='\0' || zType[i+7]==' ')
107403             ){
107404               i++;
107405               break;
107406             }
107407           }
107408         }
107409         if( i<nType ){
107410           int j;
107411           int nDel = 6 + (zType[i+6] ? 1 : 0);
107412           for(j=i; (j+nDel)<=nType; j++){
107413             zType[j] = zType[j+nDel];
107414           }
107415           if( zType[i]=='\0' && i>0 ){
107416             assert(zType[i-1]==' ');
107417             zType[i-1] = '\0';
107418           }
107419           pTab->aCol[iCol].colFlags |= COLFLAG_HIDDEN;
107420         }
107421       }
107422     }
107423   }
107424 
107425   sqlite3DbFree(db, zModuleName);
107426   return rc;
107427 }
107428 
107429 /*
107430 ** This function is invoked by the parser to call the xConnect() method
107431 ** of the virtual table pTab. If an error occurs, an error code is returned 
107432 ** and an error left in pParse.
107433 **
107434 ** This call is a no-op if table pTab is not a virtual table.
107435 */
107436 SQLITE_PRIVATE int sqlite3VtabCallConnect(Parse *pParse, Table *pTab){
107437   sqlite3 *db = pParse->db;
107438   const char *zMod;
107439   Module *pMod;
107440   int rc;
107441 
107442   assert( pTab );
107443   if( (pTab->tabFlags & TF_Virtual)==0 || sqlite3GetVTable(db, pTab) ){
107444     return SQLITE_OK;
107445   }
107446 
107447   /* Locate the required virtual table module */
107448   zMod = pTab->azModuleArg[0];
107449   pMod = (Module*)sqlite3HashFind(&db->aModule, zMod, sqlite3Strlen30(zMod));
107450 
107451   if( !pMod ){
107452     const char *zModule = pTab->azModuleArg[0];
107453     sqlite3ErrorMsg(pParse, "no such module: %s", zModule);
107454     rc = SQLITE_ERROR;
107455   }else{
107456     char *zErr = 0;
107457     rc = vtabCallConstructor(db, pTab, pMod, pMod->pModule->xConnect, &zErr);
107458     if( rc!=SQLITE_OK ){
107459       sqlite3ErrorMsg(pParse, "%s", zErr);
107460     }
107461     sqlite3DbFree(db, zErr);
107462   }
107463 
107464   return rc;
107465 }
107466 /*
107467 ** Grow the db->aVTrans[] array so that there is room for at least one
107468 ** more v-table. Return SQLITE_NOMEM if a malloc fails, or SQLITE_OK otherwise.
107469 */
107470 static int growVTrans(sqlite3 *db){
107471   const int ARRAY_INCR = 5;
107472 
107473   /* Grow the sqlite3.aVTrans array if required */
107474   if( (db->nVTrans%ARRAY_INCR)==0 ){
107475     VTable **aVTrans;
107476     int nBytes = sizeof(sqlite3_vtab *) * (db->nVTrans + ARRAY_INCR);
107477     aVTrans = sqlite3DbRealloc(db, (void *)db->aVTrans, nBytes);
107478     if( !aVTrans ){
107479       return SQLITE_NOMEM;
107480     }
107481     memset(&aVTrans[db->nVTrans], 0, sizeof(sqlite3_vtab *)*ARRAY_INCR);
107482     db->aVTrans = aVTrans;
107483   }
107484 
107485   return SQLITE_OK;
107486 }
107487 
107488 /*
107489 ** Add the virtual table pVTab to the array sqlite3.aVTrans[]. Space should
107490 ** have already been reserved using growVTrans().
107491 */
107492 static void addToVTrans(sqlite3 *db, VTable *pVTab){
107493   /* Add pVtab to the end of sqlite3.aVTrans */
107494   db->aVTrans[db->nVTrans++] = pVTab;
107495   sqlite3VtabLock(pVTab);
107496 }
107497 
107498 /*
107499 ** This function is invoked by the vdbe to call the xCreate method
107500 ** of the virtual table named zTab in database iDb. 
107501 **
107502 ** If an error occurs, *pzErr is set to point an an English language
107503 ** description of the error and an SQLITE_XXX error code is returned.
107504 ** In this case the caller must call sqlite3DbFree(db, ) on *pzErr.
107505 */
107506 SQLITE_PRIVATE int sqlite3VtabCallCreate(sqlite3 *db, int iDb, const char *zTab, char **pzErr){
107507   int rc = SQLITE_OK;
107508   Table *pTab;
107509   Module *pMod;
107510   const char *zMod;
107511 
107512   pTab = sqlite3FindTable(db, zTab, db->aDb[iDb].zName);
107513   assert( pTab && (pTab->tabFlags & TF_Virtual)!=0 && !pTab->pVTable );
107514 
107515   /* Locate the required virtual table module */
107516   zMod = pTab->azModuleArg[0];
107517   pMod = (Module*)sqlite3HashFind(&db->aModule, zMod, sqlite3Strlen30(zMod));
107518 
107519   /* If the module has been registered and includes a Create method, 
107520   ** invoke it now. If the module has not been registered, return an 
107521   ** error. Otherwise, do nothing.
107522   */
107523   if( !pMod ){
107524     *pzErr = sqlite3MPrintf(db, "no such module: %s", zMod);
107525     rc = SQLITE_ERROR;
107526   }else{
107527     rc = vtabCallConstructor(db, pTab, pMod, pMod->pModule->xCreate, pzErr);
107528   }
107529 
107530   /* Justification of ALWAYS():  The xConstructor method is required to
107531   ** create a valid sqlite3_vtab if it returns SQLITE_OK. */
107532   if( rc==SQLITE_OK && ALWAYS(sqlite3GetVTable(db, pTab)) ){
107533     rc = growVTrans(db);
107534     if( rc==SQLITE_OK ){
107535       addToVTrans(db, sqlite3GetVTable(db, pTab));
107536     }
107537   }
107538 
107539   return rc;
107540 }
107541 
107542 /*
107543 ** This function is used to set the schema of a virtual table.  It is only
107544 ** valid to call this function from within the xCreate() or xConnect() of a
107545 ** virtual table module.
107546 */
107547 SQLITE_API int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable){
107548   Parse *pParse;
107549 
107550   int rc = SQLITE_OK;
107551   Table *pTab;
107552   char *zErr = 0;
107553 
107554   sqlite3_mutex_enter(db->mutex);
107555   if( !db->pVtabCtx || !(pTab = db->pVtabCtx->pTab) ){
107556     sqlite3Error(db, SQLITE_MISUSE, 0);
107557     sqlite3_mutex_leave(db->mutex);
107558     return SQLITE_MISUSE_BKPT;
107559   }
107560   assert( (pTab->tabFlags & TF_Virtual)!=0 );
107561 
107562   pParse = sqlite3StackAllocZero(db, sizeof(*pParse));
107563   if( pParse==0 ){
107564     rc = SQLITE_NOMEM;
107565   }else{
107566     pParse->declareVtab = 1;
107567     pParse->db = db;
107568     pParse->nQueryLoop = 1;
107569   
107570     if( SQLITE_OK==sqlite3RunParser(pParse, zCreateTable, &zErr) 
107571      && pParse->pNewTable
107572      && !db->mallocFailed
107573      && !pParse->pNewTable->pSelect
107574      && (pParse->pNewTable->tabFlags & TF_Virtual)==0
107575     ){
107576       if( !pTab->aCol ){
107577         pTab->aCol = pParse->pNewTable->aCol;
107578         pTab->nCol = pParse->pNewTable->nCol;
107579         pParse->pNewTable->nCol = 0;
107580         pParse->pNewTable->aCol = 0;
107581       }
107582       db->pVtabCtx->pTab = 0;
107583     }else{
107584       sqlite3Error(db, SQLITE_ERROR, (zErr ? "%s" : 0), zErr);
107585       sqlite3DbFree(db, zErr);
107586       rc = SQLITE_ERROR;
107587     }
107588     pParse->declareVtab = 0;
107589   
107590     if( pParse->pVdbe ){
107591       sqlite3VdbeFinalize(pParse->pVdbe);
107592     }
107593     sqlite3DeleteTable(db, pParse->pNewTable);
107594     sqlite3ParserReset(pParse);
107595     sqlite3StackFree(db, pParse);
107596   }
107597 
107598   assert( (rc&0xff)==rc );
107599   rc = sqlite3ApiExit(db, rc);
107600   sqlite3_mutex_leave(db->mutex);
107601   return rc;
107602 }
107603 
107604 /*
107605 ** This function is invoked by the vdbe to call the xDestroy method
107606 ** of the virtual table named zTab in database iDb. This occurs
107607 ** when a DROP TABLE is mentioned.
107608 **
107609 ** This call is a no-op if zTab is not a virtual table.
107610 */
107611 SQLITE_PRIVATE int sqlite3VtabCallDestroy(sqlite3 *db, int iDb, const char *zTab){
107612   int rc = SQLITE_OK;
107613   Table *pTab;
107614 
107615   pTab = sqlite3FindTable(db, zTab, db->aDb[iDb].zName);
107616   if( ALWAYS(pTab!=0 && pTab->pVTable!=0) ){
107617     VTable *p = vtabDisconnectAll(db, pTab);
107618 
107619     assert( rc==SQLITE_OK );
107620     rc = p->pMod->pModule->xDestroy(p->pVtab);
107621 
107622     /* Remove the sqlite3_vtab* from the aVTrans[] array, if applicable */
107623     if( rc==SQLITE_OK ){
107624       assert( pTab->pVTable==p && p->pNext==0 );
107625       p->pVtab = 0;
107626       pTab->pVTable = 0;
107627       sqlite3VtabUnlock(p);
107628     }
107629   }
107630 
107631   return rc;
107632 }
107633 
107634 /*
107635 ** This function invokes either the xRollback or xCommit method
107636 ** of each of the virtual tables in the sqlite3.aVTrans array. The method
107637 ** called is identified by the second argument, "offset", which is
107638 ** the offset of the method to call in the sqlite3_module structure.
107639 **
107640 ** The array is cleared after invoking the callbacks. 
107641 */
107642 static void callFinaliser(sqlite3 *db, int offset){
107643   int i;
107644   if( db->aVTrans ){
107645     for(i=0; i<db->nVTrans; i++){
107646       VTable *pVTab = db->aVTrans[i];
107647       sqlite3_vtab *p = pVTab->pVtab;
107648       if( p ){
107649         int (*x)(sqlite3_vtab *);
107650         x = *(int (**)(sqlite3_vtab *))((char *)p->pModule + offset);
107651         if( x ) x(p);
107652       }
107653       pVTab->iSavepoint = 0;
107654       sqlite3VtabUnlock(pVTab);
107655     }
107656     sqlite3DbFree(db, db->aVTrans);
107657     db->nVTrans = 0;
107658     db->aVTrans = 0;
107659   }
107660 }
107661 
107662 /*
107663 ** Invoke the xSync method of all virtual tables in the sqlite3.aVTrans
107664 ** array. Return the error code for the first error that occurs, or
107665 ** SQLITE_OK if all xSync operations are successful.
107666 **
107667 ** If an error message is available, leave it in p->zErrMsg.
107668 */
107669 SQLITE_PRIVATE int sqlite3VtabSync(sqlite3 *db, Vdbe *p){
107670   int i;
107671   int rc = SQLITE_OK;
107672   VTable **aVTrans = db->aVTrans;
107673 
107674   db->aVTrans = 0;
107675   for(i=0; rc==SQLITE_OK && i<db->nVTrans; i++){
107676     int (*x)(sqlite3_vtab *);
107677     sqlite3_vtab *pVtab = aVTrans[i]->pVtab;
107678     if( pVtab && (x = pVtab->pModule->xSync)!=0 ){
107679       rc = x(pVtab);
107680       sqlite3VtabImportErrmsg(p, pVtab);
107681     }
107682   }
107683   db->aVTrans = aVTrans;
107684   return rc;
107685 }
107686 
107687 /*
107688 ** Invoke the xRollback method of all virtual tables in the 
107689 ** sqlite3.aVTrans array. Then clear the array itself.
107690 */
107691 SQLITE_PRIVATE int sqlite3VtabRollback(sqlite3 *db){
107692   callFinaliser(db, offsetof(sqlite3_module,xRollback));
107693   return SQLITE_OK;
107694 }
107695 
107696 /*
107697 ** Invoke the xCommit method of all virtual tables in the 
107698 ** sqlite3.aVTrans array. Then clear the array itself.
107699 */
107700 SQLITE_PRIVATE int sqlite3VtabCommit(sqlite3 *db){
107701   callFinaliser(db, offsetof(sqlite3_module,xCommit));
107702   return SQLITE_OK;
107703 }
107704 
107705 /*
107706 ** If the virtual table pVtab supports the transaction interface
107707 ** (xBegin/xRollback/xCommit and optionally xSync) and a transaction is
107708 ** not currently open, invoke the xBegin method now.
107709 **
107710 ** If the xBegin call is successful, place the sqlite3_vtab pointer
107711 ** in the sqlite3.aVTrans array.
107712 */
107713 SQLITE_PRIVATE int sqlite3VtabBegin(sqlite3 *db, VTable *pVTab){
107714   int rc = SQLITE_OK;
107715   const sqlite3_module *pModule;
107716 
107717   /* Special case: If db->aVTrans is NULL and db->nVTrans is greater
107718   ** than zero, then this function is being called from within a
107719   ** virtual module xSync() callback. It is illegal to write to 
107720   ** virtual module tables in this case, so return SQLITE_LOCKED.
107721   */
107722   if( sqlite3VtabInSync(db) ){
107723     return SQLITE_LOCKED;
107724   }
107725   if( !pVTab ){
107726     return SQLITE_OK;
107727   } 
107728   pModule = pVTab->pVtab->pModule;
107729 
107730   if( pModule->xBegin ){
107731     int i;
107732 
107733     /* If pVtab is already in the aVTrans array, return early */
107734     for(i=0; i<db->nVTrans; i++){
107735       if( db->aVTrans[i]==pVTab ){
107736         return SQLITE_OK;
107737       }
107738     }
107739 
107740     /* Invoke the xBegin method. If successful, add the vtab to the 
107741     ** sqlite3.aVTrans[] array. */
107742     rc = growVTrans(db);
107743     if( rc==SQLITE_OK ){
107744       rc = pModule->xBegin(pVTab->pVtab);
107745       if( rc==SQLITE_OK ){
107746         addToVTrans(db, pVTab);
107747       }
107748     }
107749   }
107750   return rc;
107751 }
107752 
107753 /*
107754 ** Invoke either the xSavepoint, xRollbackTo or xRelease method of all
107755 ** virtual tables that currently have an open transaction. Pass iSavepoint
107756 ** as the second argument to the virtual table method invoked.
107757 **
107758 ** If op is SAVEPOINT_BEGIN, the xSavepoint method is invoked. If it is
107759 ** SAVEPOINT_ROLLBACK, the xRollbackTo method. Otherwise, if op is 
107760 ** SAVEPOINT_RELEASE, then the xRelease method of each virtual table with
107761 ** an open transaction is invoked.
107762 **
107763 ** If any virtual table method returns an error code other than SQLITE_OK, 
107764 ** processing is abandoned and the error returned to the caller of this
107765 ** function immediately. If all calls to virtual table methods are successful,
107766 ** SQLITE_OK is returned.
107767 */
107768 SQLITE_PRIVATE int sqlite3VtabSavepoint(sqlite3 *db, int op, int iSavepoint){
107769   int rc = SQLITE_OK;
107770 
107771   assert( op==SAVEPOINT_RELEASE||op==SAVEPOINT_ROLLBACK||op==SAVEPOINT_BEGIN );
107772   assert( iSavepoint>=0 );
107773   if( db->aVTrans ){
107774     int i;
107775     for(i=0; rc==SQLITE_OK && i<db->nVTrans; i++){
107776       VTable *pVTab = db->aVTrans[i];
107777       const sqlite3_module *pMod = pVTab->pMod->pModule;
107778       if( pVTab->pVtab && pMod->iVersion>=2 ){
107779         int (*xMethod)(sqlite3_vtab *, int);
107780         switch( op ){
107781           case SAVEPOINT_BEGIN:
107782             xMethod = pMod->xSavepoint;
107783             pVTab->iSavepoint = iSavepoint+1;
107784             break;
107785           case SAVEPOINT_ROLLBACK:
107786             xMethod = pMod->xRollbackTo;
107787             break;
107788           default:
107789             xMethod = pMod->xRelease;
107790             break;
107791         }
107792         if( xMethod && pVTab->iSavepoint>iSavepoint ){
107793           rc = xMethod(pVTab->pVtab, iSavepoint);
107794         }
107795       }
107796     }
107797   }
107798   return rc;
107799 }
107800 
107801 /*
107802 ** The first parameter (pDef) is a function implementation.  The
107803 ** second parameter (pExpr) is the first argument to this function.
107804 ** If pExpr is a column in a virtual table, then let the virtual
107805 ** table implementation have an opportunity to overload the function.
107806 **
107807 ** This routine is used to allow virtual table implementations to
107808 ** overload MATCH, LIKE, GLOB, and REGEXP operators.
107809 **
107810 ** Return either the pDef argument (indicating no change) or a 
107811 ** new FuncDef structure that is marked as ephemeral using the
107812 ** SQLITE_FUNC_EPHEM flag.
107813 */
107814 SQLITE_PRIVATE FuncDef *sqlite3VtabOverloadFunction(
107815   sqlite3 *db,    /* Database connection for reporting malloc problems */
107816   FuncDef *pDef,  /* Function to possibly overload */
107817   int nArg,       /* Number of arguments to the function */
107818   Expr *pExpr     /* First argument to the function */
107819 ){
107820   Table *pTab;
107821   sqlite3_vtab *pVtab;
107822   sqlite3_module *pMod;
107823   void (*xFunc)(sqlite3_context*,int,sqlite3_value**) = 0;
107824   void *pArg = 0;
107825   FuncDef *pNew;
107826   int rc = 0;
107827   char *zLowerName;
107828   unsigned char *z;
107829 
107830 
107831   /* Check to see the left operand is a column in a virtual table */
107832   if( NEVER(pExpr==0) ) return pDef;
107833   if( pExpr->op!=TK_COLUMN ) return pDef;
107834   pTab = pExpr->pTab;
107835   if( NEVER(pTab==0) ) return pDef;
107836   if( (pTab->tabFlags & TF_Virtual)==0 ) return pDef;
107837   pVtab = sqlite3GetVTable(db, pTab)->pVtab;
107838   assert( pVtab!=0 );
107839   assert( pVtab->pModule!=0 );
107840   pMod = (sqlite3_module *)pVtab->pModule;
107841   if( pMod->xFindFunction==0 ) return pDef;
107842  
107843   /* Call the xFindFunction method on the virtual table implementation
107844   ** to see if the implementation wants to overload this function 
107845   */
107846   zLowerName = sqlite3DbStrDup(db, pDef->zName);
107847   if( zLowerName ){
107848     for(z=(unsigned char*)zLowerName; *z; z++){
107849       *z = sqlite3UpperToLower[*z];
107850     }
107851     rc = pMod->xFindFunction(pVtab, nArg, zLowerName, &xFunc, &pArg);
107852     sqlite3DbFree(db, zLowerName);
107853   }
107854   if( rc==0 ){
107855     return pDef;
107856   }
107857 
107858   /* Create a new ephemeral function definition for the overloaded
107859   ** function */
107860   pNew = sqlite3DbMallocZero(db, sizeof(*pNew)
107861                              + sqlite3Strlen30(pDef->zName) + 1);
107862   if( pNew==0 ){
107863     return pDef;
107864   }
107865   *pNew = *pDef;
107866   pNew->zName = (char *)&pNew[1];
107867   memcpy(pNew->zName, pDef->zName, sqlite3Strlen30(pDef->zName)+1);
107868   pNew->xFunc = xFunc;
107869   pNew->pUserData = pArg;
107870   pNew->funcFlags |= SQLITE_FUNC_EPHEM;
107871   return pNew;
107872 }
107873 
107874 /*
107875 ** Make sure virtual table pTab is contained in the pParse->apVirtualLock[]
107876 ** array so that an OP_VBegin will get generated for it.  Add pTab to the
107877 ** array if it is missing.  If pTab is already in the array, this routine
107878 ** is a no-op.
107879 */
107880 SQLITE_PRIVATE void sqlite3VtabMakeWritable(Parse *pParse, Table *pTab){
107881   Parse *pToplevel = sqlite3ParseToplevel(pParse);
107882   int i, n;
107883   Table **apVtabLock;
107884 
107885   assert( IsVirtual(pTab) );
107886   for(i=0; i<pToplevel->nVtabLock; i++){
107887     if( pTab==pToplevel->apVtabLock[i] ) return;
107888   }
107889   n = (pToplevel->nVtabLock+1)*sizeof(pToplevel->apVtabLock[0]);
107890   apVtabLock = sqlite3_realloc(pToplevel->apVtabLock, n);
107891   if( apVtabLock ){
107892     pToplevel->apVtabLock = apVtabLock;
107893     pToplevel->apVtabLock[pToplevel->nVtabLock++] = pTab;
107894   }else{
107895     pToplevel->db->mallocFailed = 1;
107896   }
107897 }
107898 
107899 /*
107900 ** Return the ON CONFLICT resolution mode in effect for the virtual
107901 ** table update operation currently in progress.
107902 **
107903 ** The results of this routine are undefined unless it is called from
107904 ** within an xUpdate method.
107905 */
107906 SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *db){
107907   static const unsigned char aMap[] = { 
107908     SQLITE_ROLLBACK, SQLITE_ABORT, SQLITE_FAIL, SQLITE_IGNORE, SQLITE_REPLACE 
107909   };
107910   assert( OE_Rollback==1 && OE_Abort==2 && OE_Fail==3 );
107911   assert( OE_Ignore==4 && OE_Replace==5 );
107912   assert( db->vtabOnConflict>=1 && db->vtabOnConflict<=5 );
107913   return (int)aMap[db->vtabOnConflict-1];
107914 }
107915 
107916 /*
107917 ** Call from within the xCreate() or xConnect() methods to provide 
107918 ** the SQLite core with additional information about the behavior
107919 ** of the virtual table being implemented.
107920 */
107921 SQLITE_API int sqlite3_vtab_config(sqlite3 *db, int op, ...){
107922   va_list ap;
107923   int rc = SQLITE_OK;
107924 
107925   sqlite3_mutex_enter(db->mutex);
107926 
107927   va_start(ap, op);
107928   switch( op ){
107929     case SQLITE_VTAB_CONSTRAINT_SUPPORT: {
107930       VtabCtx *p = db->pVtabCtx;
107931       if( !p ){
107932         rc = SQLITE_MISUSE_BKPT;
107933       }else{
107934         assert( p->pTab==0 || (p->pTab->tabFlags & TF_Virtual)!=0 );
107935         p->pVTable->bConstraint = (u8)va_arg(ap, int);
107936       }
107937       break;
107938     }
107939     default:
107940       rc = SQLITE_MISUSE_BKPT;
107941       break;
107942   }
107943   va_end(ap);
107944 
107945   if( rc!=SQLITE_OK ) sqlite3Error(db, rc, 0);
107946   sqlite3_mutex_leave(db->mutex);
107947   return rc;
107948 }
107949 
107950 #endif /* SQLITE_OMIT_VIRTUALTABLE */
107951 
107952 /************** End of vtab.c ************************************************/
107953 /************** Begin file where.c *******************************************/
107954 /*
107955 ** 2001 September 15
107956 **
107957 ** The author disclaims copyright to this source code.  In place of
107958 ** a legal notice, here is a blessing:
107959 **
107960 **    May you do good and not evil.
107961 **    May you find forgiveness for yourself and forgive others.
107962 **    May you share freely, never taking more than you give.
107963 **
107964 *************************************************************************
107965 ** This module contains C code that generates VDBE code used to process
107966 ** the WHERE clause of SQL statements.  This module is responsible for
107967 ** generating the code that loops through a table looking for applicable
107968 ** rows.  Indices are selected and used to speed the search when doing
107969 ** so is applicable.  Because this module is responsible for selecting
107970 ** indices, you might also think of this module as the "query optimizer".
107971 */
107972 /************** Include whereInt.h in the middle of where.c ******************/
107973 /************** Begin file whereInt.h ****************************************/
107974 /*
107975 ** 2013-11-12
107976 **
107977 ** The author disclaims copyright to this source code.  In place of
107978 ** a legal notice, here is a blessing:
107979 **
107980 **    May you do good and not evil.
107981 **    May you find forgiveness for yourself and forgive others.
107982 **    May you share freely, never taking more than you give.
107983 **
107984 *************************************************************************
107985 **
107986 ** This file contains structure and macro definitions for the query
107987 ** planner logic in "where.c".  These definitions are broken out into
107988 ** a separate source file for easier editing.
107989 */
107990 
107991 /*
107992 ** Trace output macros
107993 */
107994 #if defined(SQLITE_TEST) || defined(SQLITE_DEBUG)
107995 /***/ int sqlite3WhereTrace = 0;
107996 #endif
107997 #if defined(SQLITE_DEBUG) \
107998     && (defined(SQLITE_TEST) || defined(SQLITE_ENABLE_WHERETRACE))
107999 # define WHERETRACE(K,X)  if(sqlite3WhereTrace&(K)) sqlite3DebugPrintf X
108000 # define WHERETRACE_ENABLED 1
108001 #else
108002 # define WHERETRACE(K,X)
108003 #endif
108004 
108005 /* Forward references
108006 */
108007 typedef struct WhereClause WhereClause;
108008 typedef struct WhereMaskSet WhereMaskSet;
108009 typedef struct WhereOrInfo WhereOrInfo;
108010 typedef struct WhereAndInfo WhereAndInfo;
108011 typedef struct WhereLevel WhereLevel;
108012 typedef struct WhereLoop WhereLoop;
108013 typedef struct WherePath WherePath;
108014 typedef struct WhereTerm WhereTerm;
108015 typedef struct WhereLoopBuilder WhereLoopBuilder;
108016 typedef struct WhereScan WhereScan;
108017 typedef struct WhereOrCost WhereOrCost;
108018 typedef struct WhereOrSet WhereOrSet;
108019 
108020 /*
108021 ** This object contains information needed to implement a single nested
108022 ** loop in WHERE clause.
108023 **
108024 ** Contrast this object with WhereLoop.  This object describes the
108025 ** implementation of the loop.  WhereLoop describes the algorithm.
108026 ** This object contains a pointer to the WhereLoop algorithm as one of
108027 ** its elements.
108028 **
108029 ** The WhereInfo object contains a single instance of this object for
108030 ** each term in the FROM clause (which is to say, for each of the
108031 ** nested loops as implemented).  The order of WhereLevel objects determines
108032 ** the loop nested order, with WhereInfo.a[0] being the outer loop and
108033 ** WhereInfo.a[WhereInfo.nLevel-1] being the inner loop.
108034 */
108035 struct WhereLevel {
108036   int iLeftJoin;        /* Memory cell used to implement LEFT OUTER JOIN */
108037   int iTabCur;          /* The VDBE cursor used to access the table */
108038   int iIdxCur;          /* The VDBE cursor used to access pIdx */
108039   int addrBrk;          /* Jump here to break out of the loop */
108040   int addrNxt;          /* Jump here to start the next IN combination */
108041   int addrSkip;         /* Jump here for next iteration of skip-scan */
108042   int addrCont;         /* Jump here to continue with the next loop cycle */
108043   int addrFirst;        /* First instruction of interior of the loop */
108044   int addrBody;         /* Beginning of the body of this loop */
108045   u8 iFrom;             /* Which entry in the FROM clause */
108046   u8 op, p5;            /* Opcode and P5 of the opcode that ends the loop */
108047   int p1, p2;           /* Operands of the opcode used to ends the loop */
108048   union {               /* Information that depends on pWLoop->wsFlags */
108049     struct {
108050       int nIn;              /* Number of entries in aInLoop[] */
108051       struct InLoop {
108052         int iCur;              /* The VDBE cursor used by this IN operator */
108053         int addrInTop;         /* Top of the IN loop */
108054         u8 eEndLoopOp;         /* IN Loop terminator. OP_Next or OP_Prev */
108055       } *aInLoop;           /* Information about each nested IN operator */
108056     } in;                 /* Used when pWLoop->wsFlags&WHERE_IN_ABLE */
108057     Index *pCovidx;       /* Possible covering index for WHERE_MULTI_OR */
108058   } u;
108059   struct WhereLoop *pWLoop;  /* The selected WhereLoop object */
108060   Bitmask notReady;          /* FROM entries not usable at this level */
108061 };
108062 
108063 /*
108064 ** Each instance of this object represents an algorithm for evaluating one
108065 ** term of a join.  Every term of the FROM clause will have at least
108066 ** one corresponding WhereLoop object (unless INDEXED BY constraints
108067 ** prevent a query solution - which is an error) and many terms of the
108068 ** FROM clause will have multiple WhereLoop objects, each describing a
108069 ** potential way of implementing that FROM-clause term, together with
108070 ** dependencies and cost estimates for using the chosen algorithm.
108071 **
108072 ** Query planning consists of building up a collection of these WhereLoop
108073 ** objects, then computing a particular sequence of WhereLoop objects, with
108074 ** one WhereLoop object per FROM clause term, that satisfy all dependencies
108075 ** and that minimize the overall cost.
108076 */
108077 struct WhereLoop {
108078   Bitmask prereq;       /* Bitmask of other loops that must run first */
108079   Bitmask maskSelf;     /* Bitmask identifying table iTab */
108080 #ifdef SQLITE_DEBUG
108081   char cId;             /* Symbolic ID of this loop for debugging use */
108082 #endif
108083   u8 iTab;              /* Position in FROM clause of table for this loop */
108084   u8 iSortIdx;          /* Sorting index number.  0==None */
108085   LogEst rSetup;        /* One-time setup cost (ex: create transient index) */
108086   LogEst rRun;          /* Cost of running each loop */
108087   LogEst nOut;          /* Estimated number of output rows */
108088   union {
108089     struct {               /* Information for internal btree tables */
108090       u16 nEq;               /* Number of equality constraints */
108091       u16 nSkip;             /* Number of initial index columns to skip */
108092       Index *pIndex;         /* Index used, or NULL */
108093     } btree;
108094     struct {               /* Information for virtual tables */
108095       int idxNum;            /* Index number */
108096       u8 needFree;           /* True if sqlite3_free(idxStr) is needed */
108097       u8 isOrdered;          /* True if satisfies ORDER BY */
108098       u16 omitMask;          /* Terms that may be omitted */
108099       char *idxStr;          /* Index identifier string */
108100     } vtab;
108101   } u;
108102   u32 wsFlags;          /* WHERE_* flags describing the plan */
108103   u16 nLTerm;           /* Number of entries in aLTerm[] */
108104   /**** whereLoopXfer() copies fields above ***********************/
108105 # define WHERE_LOOP_XFER_SZ offsetof(WhereLoop,nLSlot)
108106   u16 nLSlot;           /* Number of slots allocated for aLTerm[] */
108107   WhereTerm **aLTerm;   /* WhereTerms used */
108108   WhereLoop *pNextLoop; /* Next WhereLoop object in the WhereClause */
108109   WhereTerm *aLTermSpace[4];  /* Initial aLTerm[] space */
108110 };
108111 
108112 /* This object holds the prerequisites and the cost of running a
108113 ** subquery on one operand of an OR operator in the WHERE clause.
108114 ** See WhereOrSet for additional information 
108115 */
108116 struct WhereOrCost {
108117   Bitmask prereq;     /* Prerequisites */
108118   LogEst rRun;        /* Cost of running this subquery */
108119   LogEst nOut;        /* Number of outputs for this subquery */
108120 };
108121 
108122 /* The WhereOrSet object holds a set of possible WhereOrCosts that
108123 ** correspond to the subquery(s) of OR-clause processing.  Only the
108124 ** best N_OR_COST elements are retained.
108125 */
108126 #define N_OR_COST 3
108127 struct WhereOrSet {
108128   u16 n;                      /* Number of valid a[] entries */
108129   WhereOrCost a[N_OR_COST];   /* Set of best costs */
108130 };
108131 
108132 
108133 /* Forward declaration of methods */
108134 static int whereLoopResize(sqlite3*, WhereLoop*, int);
108135 
108136 /*
108137 ** Each instance of this object holds a sequence of WhereLoop objects
108138 ** that implement some or all of a query plan.
108139 **
108140 ** Think of each WhereLoop object as a node in a graph with arcs
108141 ** showing dependencies and costs for travelling between nodes.  (That is
108142 ** not a completely accurate description because WhereLoop costs are a
108143 ** vector, not a scalar, and because dependencies are many-to-one, not
108144 ** one-to-one as are graph nodes.  But it is a useful visualization aid.)
108145 ** Then a WherePath object is a path through the graph that visits some
108146 ** or all of the WhereLoop objects once.
108147 **
108148 ** The "solver" works by creating the N best WherePath objects of length
108149 ** 1.  Then using those as a basis to compute the N best WherePath objects
108150 ** of length 2.  And so forth until the length of WherePaths equals the
108151 ** number of nodes in the FROM clause.  The best (lowest cost) WherePath
108152 ** at the end is the choosen query plan.
108153 */
108154 struct WherePath {
108155   Bitmask maskLoop;     /* Bitmask of all WhereLoop objects in this path */
108156   Bitmask revLoop;      /* aLoop[]s that should be reversed for ORDER BY */
108157   LogEst nRow;          /* Estimated number of rows generated by this path */
108158   LogEst rCost;         /* Total cost of this path */
108159   u8 isOrdered;         /* True if this path satisfies ORDER BY */
108160   u8 isOrderedValid;    /* True if the isOrdered field is valid */
108161   WhereLoop **aLoop;    /* Array of WhereLoop objects implementing this path */
108162 };
108163 
108164 /*
108165 ** The query generator uses an array of instances of this structure to
108166 ** help it analyze the subexpressions of the WHERE clause.  Each WHERE
108167 ** clause subexpression is separated from the others by AND operators,
108168 ** usually, or sometimes subexpressions separated by OR.
108169 **
108170 ** All WhereTerms are collected into a single WhereClause structure.  
108171 ** The following identity holds:
108172 **
108173 **        WhereTerm.pWC->a[WhereTerm.idx] == WhereTerm
108174 **
108175 ** When a term is of the form:
108176 **
108177 **              X <op> <expr>
108178 **
108179 ** where X is a column name and <op> is one of certain operators,
108180 ** then WhereTerm.leftCursor and WhereTerm.u.leftColumn record the
108181 ** cursor number and column number for X.  WhereTerm.eOperator records
108182 ** the <op> using a bitmask encoding defined by WO_xxx below.  The
108183 ** use of a bitmask encoding for the operator allows us to search
108184 ** quickly for terms that match any of several different operators.
108185 **
108186 ** A WhereTerm might also be two or more subterms connected by OR:
108187 **
108188 **         (t1.X <op> <expr>) OR (t1.Y <op> <expr>) OR ....
108189 **
108190 ** In this second case, wtFlag has the TERM_ORINFO bit set and eOperator==WO_OR
108191 ** and the WhereTerm.u.pOrInfo field points to auxiliary information that
108192 ** is collected about the OR clause.
108193 **
108194 ** If a term in the WHERE clause does not match either of the two previous
108195 ** categories, then eOperator==0.  The WhereTerm.pExpr field is still set
108196 ** to the original subexpression content and wtFlags is set up appropriately
108197 ** but no other fields in the WhereTerm object are meaningful.
108198 **
108199 ** When eOperator!=0, prereqRight and prereqAll record sets of cursor numbers,
108200 ** but they do so indirectly.  A single WhereMaskSet structure translates
108201 ** cursor number into bits and the translated bit is stored in the prereq
108202 ** fields.  The translation is used in order to maximize the number of
108203 ** bits that will fit in a Bitmask.  The VDBE cursor numbers might be
108204 ** spread out over the non-negative integers.  For example, the cursor
108205 ** numbers might be 3, 8, 9, 10, 20, 23, 41, and 45.  The WhereMaskSet
108206 ** translates these sparse cursor numbers into consecutive integers
108207 ** beginning with 0 in order to make the best possible use of the available
108208 ** bits in the Bitmask.  So, in the example above, the cursor numbers
108209 ** would be mapped into integers 0 through 7.
108210 **
108211 ** The number of terms in a join is limited by the number of bits
108212 ** in prereqRight and prereqAll.  The default is 64 bits, hence SQLite
108213 ** is only able to process joins with 64 or fewer tables.
108214 */
108215 struct WhereTerm {
108216   Expr *pExpr;            /* Pointer to the subexpression that is this term */
108217   int iParent;            /* Disable pWC->a[iParent] when this term disabled */
108218   int leftCursor;         /* Cursor number of X in "X <op> <expr>" */
108219   union {
108220     int leftColumn;         /* Column number of X in "X <op> <expr>" */
108221     WhereOrInfo *pOrInfo;   /* Extra information if (eOperator & WO_OR)!=0 */
108222     WhereAndInfo *pAndInfo; /* Extra information if (eOperator& WO_AND)!=0 */
108223   } u;
108224   LogEst truthProb;       /* Probability of truth for this expression */
108225   u16 eOperator;          /* A WO_xx value describing <op> */
108226   u8 wtFlags;             /* TERM_xxx bit flags.  See below */
108227   u8 nChild;              /* Number of children that must disable us */
108228   WhereClause *pWC;       /* The clause this term is part of */
108229   Bitmask prereqRight;    /* Bitmask of tables used by pExpr->pRight */
108230   Bitmask prereqAll;      /* Bitmask of tables referenced by pExpr */
108231 };
108232 
108233 /*
108234 ** Allowed values of WhereTerm.wtFlags
108235 */
108236 #define TERM_DYNAMIC    0x01   /* Need to call sqlite3ExprDelete(db, pExpr) */
108237 #define TERM_VIRTUAL    0x02   /* Added by the optimizer.  Do not code */
108238 #define TERM_CODED      0x04   /* This term is already coded */
108239 #define TERM_COPIED     0x08   /* Has a child */
108240 #define TERM_ORINFO     0x10   /* Need to free the WhereTerm.u.pOrInfo object */
108241 #define TERM_ANDINFO    0x20   /* Need to free the WhereTerm.u.pAndInfo obj */
108242 #define TERM_OR_OK      0x40   /* Used during OR-clause processing */
108243 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
108244 #  define TERM_VNULL    0x80   /* Manufactured x>NULL or x<=NULL term */
108245 #else
108246 #  define TERM_VNULL    0x00   /* Disabled if not using stat3 */
108247 #endif
108248 
108249 /*
108250 ** An instance of the WhereScan object is used as an iterator for locating
108251 ** terms in the WHERE clause that are useful to the query planner.
108252 */
108253 struct WhereScan {
108254   WhereClause *pOrigWC;      /* Original, innermost WhereClause */
108255   WhereClause *pWC;          /* WhereClause currently being scanned */
108256   char *zCollName;           /* Required collating sequence, if not NULL */
108257   char idxaff;               /* Must match this affinity, if zCollName!=NULL */
108258   unsigned char nEquiv;      /* Number of entries in aEquiv[] */
108259   unsigned char iEquiv;      /* Next unused slot in aEquiv[] */
108260   u32 opMask;                /* Acceptable operators */
108261   int k;                     /* Resume scanning at this->pWC->a[this->k] */
108262   int aEquiv[22];            /* Cursor,Column pairs for equivalence classes */
108263 };
108264 
108265 /*
108266 ** An instance of the following structure holds all information about a
108267 ** WHERE clause.  Mostly this is a container for one or more WhereTerms.
108268 **
108269 ** Explanation of pOuter:  For a WHERE clause of the form
108270 **
108271 **           a AND ((b AND c) OR (d AND e)) AND f
108272 **
108273 ** There are separate WhereClause objects for the whole clause and for
108274 ** the subclauses "(b AND c)" and "(d AND e)".  The pOuter field of the
108275 ** subclauses points to the WhereClause object for the whole clause.
108276 */
108277 struct WhereClause {
108278   WhereInfo *pWInfo;       /* WHERE clause processing context */
108279   WhereClause *pOuter;     /* Outer conjunction */
108280   u8 op;                   /* Split operator.  TK_AND or TK_OR */
108281   int nTerm;               /* Number of terms */
108282   int nSlot;               /* Number of entries in a[] */
108283   WhereTerm *a;            /* Each a[] describes a term of the WHERE cluase */
108284 #if defined(SQLITE_SMALL_STACK)
108285   WhereTerm aStatic[1];    /* Initial static space for a[] */
108286 #else
108287   WhereTerm aStatic[8];    /* Initial static space for a[] */
108288 #endif
108289 };
108290 
108291 /*
108292 ** A WhereTerm with eOperator==WO_OR has its u.pOrInfo pointer set to
108293 ** a dynamically allocated instance of the following structure.
108294 */
108295 struct WhereOrInfo {
108296   WhereClause wc;          /* Decomposition into subterms */
108297   Bitmask indexable;       /* Bitmask of all indexable tables in the clause */
108298 };
108299 
108300 /*
108301 ** A WhereTerm with eOperator==WO_AND has its u.pAndInfo pointer set to
108302 ** a dynamically allocated instance of the following structure.
108303 */
108304 struct WhereAndInfo {
108305   WhereClause wc;          /* The subexpression broken out */
108306 };
108307 
108308 /*
108309 ** An instance of the following structure keeps track of a mapping
108310 ** between VDBE cursor numbers and bits of the bitmasks in WhereTerm.
108311 **
108312 ** The VDBE cursor numbers are small integers contained in 
108313 ** SrcList_item.iCursor and Expr.iTable fields.  For any given WHERE 
108314 ** clause, the cursor numbers might not begin with 0 and they might
108315 ** contain gaps in the numbering sequence.  But we want to make maximum
108316 ** use of the bits in our bitmasks.  This structure provides a mapping
108317 ** from the sparse cursor numbers into consecutive integers beginning
108318 ** with 0.
108319 **
108320 ** If WhereMaskSet.ix[A]==B it means that The A-th bit of a Bitmask
108321 ** corresponds VDBE cursor number B.  The A-th bit of a bitmask is 1<<A.
108322 **
108323 ** For example, if the WHERE clause expression used these VDBE
108324 ** cursors:  4, 5, 8, 29, 57, 73.  Then the  WhereMaskSet structure
108325 ** would map those cursor numbers into bits 0 through 5.
108326 **
108327 ** Note that the mapping is not necessarily ordered.  In the example
108328 ** above, the mapping might go like this:  4->3, 5->1, 8->2, 29->0,
108329 ** 57->5, 73->4.  Or one of 719 other combinations might be used. It
108330 ** does not really matter.  What is important is that sparse cursor
108331 ** numbers all get mapped into bit numbers that begin with 0 and contain
108332 ** no gaps.
108333 */
108334 struct WhereMaskSet {
108335   int n;                        /* Number of assigned cursor values */
108336   int ix[BMS];                  /* Cursor assigned to each bit */
108337 };
108338 
108339 /*
108340 ** This object is a convenience wrapper holding all information needed
108341 ** to construct WhereLoop objects for a particular query.
108342 */
108343 struct WhereLoopBuilder {
108344   WhereInfo *pWInfo;        /* Information about this WHERE */
108345   WhereClause *pWC;         /* WHERE clause terms */
108346   ExprList *pOrderBy;       /* ORDER BY clause */
108347   WhereLoop *pNew;          /* Template WhereLoop */
108348   WhereOrSet *pOrSet;       /* Record best loops here, if not NULL */
108349 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
108350   UnpackedRecord *pRec;     /* Probe for stat4 (if required) */
108351   int nRecValid;            /* Number of valid fields currently in pRec */
108352 #endif
108353 };
108354 
108355 /*
108356 ** The WHERE clause processing routine has two halves.  The
108357 ** first part does the start of the WHERE loop and the second
108358 ** half does the tail of the WHERE loop.  An instance of
108359 ** this structure is returned by the first half and passed
108360 ** into the second half to give some continuity.
108361 **
108362 ** An instance of this object holds the complete state of the query
108363 ** planner.
108364 */
108365 struct WhereInfo {
108366   Parse *pParse;            /* Parsing and code generating context */
108367   SrcList *pTabList;        /* List of tables in the join */
108368   ExprList *pOrderBy;       /* The ORDER BY clause or NULL */
108369   ExprList *pResultSet;     /* Result set. DISTINCT operates on these */
108370   WhereLoop *pLoops;        /* List of all WhereLoop objects */
108371   Bitmask revMask;          /* Mask of ORDER BY terms that need reversing */
108372   LogEst nRowOut;           /* Estimated number of output rows */
108373   u16 wctrlFlags;           /* Flags originally passed to sqlite3WhereBegin() */
108374   u8 bOBSat;                /* ORDER BY satisfied by indices */
108375   u8 okOnePass;             /* Ok to use one-pass algorithm for UPDATE/DELETE */
108376   u8 untestedTerms;         /* Not all WHERE terms resolved by outer loop */
108377   u8 eDistinct;             /* One of the WHERE_DISTINCT_* values below */
108378   u8 nLevel;                /* Number of nested loop */
108379   int iTop;                 /* The very beginning of the WHERE loop */
108380   int iContinue;            /* Jump here to continue with next record */
108381   int iBreak;               /* Jump here to break out of the loop */
108382   int savedNQueryLoop;      /* pParse->nQueryLoop outside the WHERE loop */
108383   int aiCurOnePass[2];      /* OP_OpenWrite cursors for the ONEPASS opt */
108384   WhereMaskSet sMaskSet;    /* Map cursor numbers to bitmasks */
108385   WhereClause sWC;          /* Decomposition of the WHERE clause */
108386   WhereLevel a[1];          /* Information about each nest loop in WHERE */
108387 };
108388 
108389 /*
108390 ** Bitmasks for the operators on WhereTerm objects.  These are all
108391 ** operators that are of interest to the query planner.  An
108392 ** OR-ed combination of these values can be used when searching for
108393 ** particular WhereTerms within a WhereClause.
108394 */
108395 #define WO_IN     0x001
108396 #define WO_EQ     0x002
108397 #define WO_LT     (WO_EQ<<(TK_LT-TK_EQ))
108398 #define WO_LE     (WO_EQ<<(TK_LE-TK_EQ))
108399 #define WO_GT     (WO_EQ<<(TK_GT-TK_EQ))
108400 #define WO_GE     (WO_EQ<<(TK_GE-TK_EQ))
108401 #define WO_MATCH  0x040
108402 #define WO_ISNULL 0x080
108403 #define WO_OR     0x100       /* Two or more OR-connected terms */
108404 #define WO_AND    0x200       /* Two or more AND-connected terms */
108405 #define WO_EQUIV  0x400       /* Of the form A==B, both columns */
108406 #define WO_NOOP   0x800       /* This term does not restrict search space */
108407 
108408 #define WO_ALL    0xfff       /* Mask of all possible WO_* values */
108409 #define WO_SINGLE 0x0ff       /* Mask of all non-compound WO_* values */
108410 
108411 /*
108412 ** These are definitions of bits in the WhereLoop.wsFlags field.
108413 ** The particular combination of bits in each WhereLoop help to
108414 ** determine the algorithm that WhereLoop represents.
108415 */
108416 #define WHERE_COLUMN_EQ    0x00000001  /* x=EXPR */
108417 #define WHERE_COLUMN_RANGE 0x00000002  /* x<EXPR and/or x>EXPR */
108418 #define WHERE_COLUMN_IN    0x00000004  /* x IN (...) */
108419 #define WHERE_COLUMN_NULL  0x00000008  /* x IS NULL */
108420 #define WHERE_CONSTRAINT   0x0000000f  /* Any of the WHERE_COLUMN_xxx values */
108421 #define WHERE_TOP_LIMIT    0x00000010  /* x<EXPR or x<=EXPR constraint */
108422 #define WHERE_BTM_LIMIT    0x00000020  /* x>EXPR or x>=EXPR constraint */
108423 #define WHERE_BOTH_LIMIT   0x00000030  /* Both x>EXPR and x<EXPR */
108424 #define WHERE_IDX_ONLY     0x00000040  /* Use index only - omit table */
108425 #define WHERE_IPK          0x00000100  /* x is the INTEGER PRIMARY KEY */
108426 #define WHERE_INDEXED      0x00000200  /* WhereLoop.u.btree.pIndex is valid */
108427 #define WHERE_VIRTUALTABLE 0x00000400  /* WhereLoop.u.vtab is valid */
108428 #define WHERE_IN_ABLE      0x00000800  /* Able to support an IN operator */
108429 #define WHERE_ONEROW       0x00001000  /* Selects no more than one row */
108430 #define WHERE_MULTI_OR     0x00002000  /* OR using multiple indices */
108431 #define WHERE_AUTO_INDEX   0x00004000  /* Uses an ephemeral index */
108432 #define WHERE_SKIPSCAN     0x00008000  /* Uses the skip-scan algorithm */
108433 
108434 /************** End of whereInt.h ********************************************/
108435 /************** Continuing where we left off in where.c **********************/
108436 
108437 /*
108438 ** Return the estimated number of output rows from a WHERE clause
108439 */
108440 SQLITE_PRIVATE u64 sqlite3WhereOutputRowCount(WhereInfo *pWInfo){
108441   return sqlite3LogEstToInt(pWInfo->nRowOut);
108442 }
108443 
108444 /*
108445 ** Return one of the WHERE_DISTINCT_xxxxx values to indicate how this
108446 ** WHERE clause returns outputs for DISTINCT processing.
108447 */
108448 SQLITE_PRIVATE int sqlite3WhereIsDistinct(WhereInfo *pWInfo){
108449   return pWInfo->eDistinct;
108450 }
108451 
108452 /*
108453 ** Return TRUE if the WHERE clause returns rows in ORDER BY order.
108454 ** Return FALSE if the output needs to be sorted.
108455 */
108456 SQLITE_PRIVATE int sqlite3WhereIsOrdered(WhereInfo *pWInfo){
108457   return pWInfo->bOBSat!=0;
108458 }
108459 
108460 /*
108461 ** Return the VDBE address or label to jump to in order to continue
108462 ** immediately with the next row of a WHERE clause.
108463 */
108464 SQLITE_PRIVATE int sqlite3WhereContinueLabel(WhereInfo *pWInfo){
108465   return pWInfo->iContinue;
108466 }
108467 
108468 /*
108469 ** Return the VDBE address or label to jump to in order to break
108470 ** out of a WHERE loop.
108471 */
108472 SQLITE_PRIVATE int sqlite3WhereBreakLabel(WhereInfo *pWInfo){
108473   return pWInfo->iBreak;
108474 }
108475 
108476 /*
108477 ** Return TRUE if an UPDATE or DELETE statement can operate directly on
108478 ** the rowids returned by a WHERE clause.  Return FALSE if doing an
108479 ** UPDATE or DELETE might change subsequent WHERE clause results.
108480 **
108481 ** If the ONEPASS optimization is used (if this routine returns true)
108482 ** then also write the indices of open cursors used by ONEPASS
108483 ** into aiCur[0] and aiCur[1].  iaCur[0] gets the cursor of the data
108484 ** table and iaCur[1] gets the cursor used by an auxiliary index.
108485 ** Either value may be -1, indicating that cursor is not used.
108486 ** Any cursors returned will have been opened for writing.
108487 **
108488 ** aiCur[0] and aiCur[1] both get -1 if the where-clause logic is
108489 ** unable to use the ONEPASS optimization.
108490 */
108491 SQLITE_PRIVATE int sqlite3WhereOkOnePass(WhereInfo *pWInfo, int *aiCur){
108492   memcpy(aiCur, pWInfo->aiCurOnePass, sizeof(int)*2);
108493   return pWInfo->okOnePass;
108494 }
108495 
108496 /*
108497 ** Move the content of pSrc into pDest
108498 */
108499 static void whereOrMove(WhereOrSet *pDest, WhereOrSet *pSrc){
108500   pDest->n = pSrc->n;
108501   memcpy(pDest->a, pSrc->a, pDest->n*sizeof(pDest->a[0]));
108502 }
108503 
108504 /*
108505 ** Try to insert a new prerequisite/cost entry into the WhereOrSet pSet.
108506 **
108507 ** The new entry might overwrite an existing entry, or it might be
108508 ** appended, or it might be discarded.  Do whatever is the right thing
108509 ** so that pSet keeps the N_OR_COST best entries seen so far.
108510 */
108511 static int whereOrInsert(
108512   WhereOrSet *pSet,      /* The WhereOrSet to be updated */
108513   Bitmask prereq,        /* Prerequisites of the new entry */
108514   LogEst rRun,           /* Run-cost of the new entry */
108515   LogEst nOut            /* Number of outputs for the new entry */
108516 ){
108517   u16 i;
108518   WhereOrCost *p;
108519   for(i=pSet->n, p=pSet->a; i>0; i--, p++){
108520     if( rRun<=p->rRun && (prereq & p->prereq)==prereq ){
108521       goto whereOrInsert_done;
108522     }
108523     if( p->rRun<=rRun && (p->prereq & prereq)==p->prereq ){
108524       return 0;
108525     }
108526   }
108527   if( pSet->n<N_OR_COST ){
108528     p = &pSet->a[pSet->n++];
108529     p->nOut = nOut;
108530   }else{
108531     p = pSet->a;
108532     for(i=1; i<pSet->n; i++){
108533       if( p->rRun>pSet->a[i].rRun ) p = pSet->a + i;
108534     }
108535     if( p->rRun<=rRun ) return 0;
108536   }
108537 whereOrInsert_done:
108538   p->prereq = prereq;
108539   p->rRun = rRun;
108540   if( p->nOut>nOut ) p->nOut = nOut;
108541   return 1;
108542 }
108543 
108544 /*
108545 ** Initialize a preallocated WhereClause structure.
108546 */
108547 static void whereClauseInit(
108548   WhereClause *pWC,        /* The WhereClause to be initialized */
108549   WhereInfo *pWInfo        /* The WHERE processing context */
108550 ){
108551   pWC->pWInfo = pWInfo;
108552   pWC->pOuter = 0;
108553   pWC->nTerm = 0;
108554   pWC->nSlot = ArraySize(pWC->aStatic);
108555   pWC->a = pWC->aStatic;
108556 }
108557 
108558 /* Forward reference */
108559 static void whereClauseClear(WhereClause*);
108560 
108561 /*
108562 ** Deallocate all memory associated with a WhereOrInfo object.
108563 */
108564 static void whereOrInfoDelete(sqlite3 *db, WhereOrInfo *p){
108565   whereClauseClear(&p->wc);
108566   sqlite3DbFree(db, p);
108567 }
108568 
108569 /*
108570 ** Deallocate all memory associated with a WhereAndInfo object.
108571 */
108572 static void whereAndInfoDelete(sqlite3 *db, WhereAndInfo *p){
108573   whereClauseClear(&p->wc);
108574   sqlite3DbFree(db, p);
108575 }
108576 
108577 /*
108578 ** Deallocate a WhereClause structure.  The WhereClause structure
108579 ** itself is not freed.  This routine is the inverse of whereClauseInit().
108580 */
108581 static void whereClauseClear(WhereClause *pWC){
108582   int i;
108583   WhereTerm *a;
108584   sqlite3 *db = pWC->pWInfo->pParse->db;
108585   for(i=pWC->nTerm-1, a=pWC->a; i>=0; i--, a++){
108586     if( a->wtFlags & TERM_DYNAMIC ){
108587       sqlite3ExprDelete(db, a->pExpr);
108588     }
108589     if( a->wtFlags & TERM_ORINFO ){
108590       whereOrInfoDelete(db, a->u.pOrInfo);
108591     }else if( a->wtFlags & TERM_ANDINFO ){
108592       whereAndInfoDelete(db, a->u.pAndInfo);
108593     }
108594   }
108595   if( pWC->a!=pWC->aStatic ){
108596     sqlite3DbFree(db, pWC->a);
108597   }
108598 }
108599 
108600 /*
108601 ** Add a single new WhereTerm entry to the WhereClause object pWC.
108602 ** The new WhereTerm object is constructed from Expr p and with wtFlags.
108603 ** The index in pWC->a[] of the new WhereTerm is returned on success.
108604 ** 0 is returned if the new WhereTerm could not be added due to a memory
108605 ** allocation error.  The memory allocation failure will be recorded in
108606 ** the db->mallocFailed flag so that higher-level functions can detect it.
108607 **
108608 ** This routine will increase the size of the pWC->a[] array as necessary.
108609 **
108610 ** If the wtFlags argument includes TERM_DYNAMIC, then responsibility
108611 ** for freeing the expression p is assumed by the WhereClause object pWC.
108612 ** This is true even if this routine fails to allocate a new WhereTerm.
108613 **
108614 ** WARNING:  This routine might reallocate the space used to store
108615 ** WhereTerms.  All pointers to WhereTerms should be invalidated after
108616 ** calling this routine.  Such pointers may be reinitialized by referencing
108617 ** the pWC->a[] array.
108618 */
108619 static int whereClauseInsert(WhereClause *pWC, Expr *p, u8 wtFlags){
108620   WhereTerm *pTerm;
108621   int idx;
108622   testcase( wtFlags & TERM_VIRTUAL );
108623   if( pWC->nTerm>=pWC->nSlot ){
108624     WhereTerm *pOld = pWC->a;
108625     sqlite3 *db = pWC->pWInfo->pParse->db;
108626     pWC->a = sqlite3DbMallocRaw(db, sizeof(pWC->a[0])*pWC->nSlot*2 );
108627     if( pWC->a==0 ){
108628       if( wtFlags & TERM_DYNAMIC ){
108629         sqlite3ExprDelete(db, p);
108630       }
108631       pWC->a = pOld;
108632       return 0;
108633     }
108634     memcpy(pWC->a, pOld, sizeof(pWC->a[0])*pWC->nTerm);
108635     if( pOld!=pWC->aStatic ){
108636       sqlite3DbFree(db, pOld);
108637     }
108638     pWC->nSlot = sqlite3DbMallocSize(db, pWC->a)/sizeof(pWC->a[0]);
108639   }
108640   pTerm = &pWC->a[idx = pWC->nTerm++];
108641   if( p && ExprHasProperty(p, EP_Unlikely) ){
108642     pTerm->truthProb = sqlite3LogEst(p->iTable) - 99;
108643   }else{
108644     pTerm->truthProb = -1;
108645   }
108646   pTerm->pExpr = sqlite3ExprSkipCollate(p);
108647   pTerm->wtFlags = wtFlags;
108648   pTerm->pWC = pWC;
108649   pTerm->iParent = -1;
108650   return idx;
108651 }
108652 
108653 /*
108654 ** This routine identifies subexpressions in the WHERE clause where
108655 ** each subexpression is separated by the AND operator or some other
108656 ** operator specified in the op parameter.  The WhereClause structure
108657 ** is filled with pointers to subexpressions.  For example:
108658 **
108659 **    WHERE  a=='hello' AND coalesce(b,11)<10 AND (c+12!=d OR c==22)
108660 **           \________/     \_______________/     \________________/
108661 **            slot[0]            slot[1]               slot[2]
108662 **
108663 ** The original WHERE clause in pExpr is unaltered.  All this routine
108664 ** does is make slot[] entries point to substructure within pExpr.
108665 **
108666 ** In the previous sentence and in the diagram, "slot[]" refers to
108667 ** the WhereClause.a[] array.  The slot[] array grows as needed to contain
108668 ** all terms of the WHERE clause.
108669 */
108670 static void whereSplit(WhereClause *pWC, Expr *pExpr, u8 op){
108671   pWC->op = op;
108672   if( pExpr==0 ) return;
108673   if( pExpr->op!=op ){
108674     whereClauseInsert(pWC, pExpr, 0);
108675   }else{
108676     whereSplit(pWC, pExpr->pLeft, op);
108677     whereSplit(pWC, pExpr->pRight, op);
108678   }
108679 }
108680 
108681 /*
108682 ** Initialize a WhereMaskSet object
108683 */
108684 #define initMaskSet(P)  (P)->n=0
108685 
108686 /*
108687 ** Return the bitmask for the given cursor number.  Return 0 if
108688 ** iCursor is not in the set.
108689 */
108690 static Bitmask getMask(WhereMaskSet *pMaskSet, int iCursor){
108691   int i;
108692   assert( pMaskSet->n<=(int)sizeof(Bitmask)*8 );
108693   for(i=0; i<pMaskSet->n; i++){
108694     if( pMaskSet->ix[i]==iCursor ){
108695       return MASKBIT(i);
108696     }
108697   }
108698   return 0;
108699 }
108700 
108701 /*
108702 ** Create a new mask for cursor iCursor.
108703 **
108704 ** There is one cursor per table in the FROM clause.  The number of
108705 ** tables in the FROM clause is limited by a test early in the
108706 ** sqlite3WhereBegin() routine.  So we know that the pMaskSet->ix[]
108707 ** array will never overflow.
108708 */
108709 static void createMask(WhereMaskSet *pMaskSet, int iCursor){
108710   assert( pMaskSet->n < ArraySize(pMaskSet->ix) );
108711   pMaskSet->ix[pMaskSet->n++] = iCursor;
108712 }
108713 
108714 /*
108715 ** These routines walk (recursively) an expression tree and generate
108716 ** a bitmask indicating which tables are used in that expression
108717 ** tree.
108718 */
108719 static Bitmask exprListTableUsage(WhereMaskSet*, ExprList*);
108720 static Bitmask exprSelectTableUsage(WhereMaskSet*, Select*);
108721 static Bitmask exprTableUsage(WhereMaskSet *pMaskSet, Expr *p){
108722   Bitmask mask = 0;
108723   if( p==0 ) return 0;
108724   if( p->op==TK_COLUMN ){
108725     mask = getMask(pMaskSet, p->iTable);
108726     return mask;
108727   }
108728   mask = exprTableUsage(pMaskSet, p->pRight);
108729   mask |= exprTableUsage(pMaskSet, p->pLeft);
108730   if( ExprHasProperty(p, EP_xIsSelect) ){
108731     mask |= exprSelectTableUsage(pMaskSet, p->x.pSelect);
108732   }else{
108733     mask |= exprListTableUsage(pMaskSet, p->x.pList);
108734   }
108735   return mask;
108736 }
108737 static Bitmask exprListTableUsage(WhereMaskSet *pMaskSet, ExprList *pList){
108738   int i;
108739   Bitmask mask = 0;
108740   if( pList ){
108741     for(i=0; i<pList->nExpr; i++){
108742       mask |= exprTableUsage(pMaskSet, pList->a[i].pExpr);
108743     }
108744   }
108745   return mask;
108746 }
108747 static Bitmask exprSelectTableUsage(WhereMaskSet *pMaskSet, Select *pS){
108748   Bitmask mask = 0;
108749   while( pS ){
108750     SrcList *pSrc = pS->pSrc;
108751     mask |= exprListTableUsage(pMaskSet, pS->pEList);
108752     mask |= exprListTableUsage(pMaskSet, pS->pGroupBy);
108753     mask |= exprListTableUsage(pMaskSet, pS->pOrderBy);
108754     mask |= exprTableUsage(pMaskSet, pS->pWhere);
108755     mask |= exprTableUsage(pMaskSet, pS->pHaving);
108756     if( ALWAYS(pSrc!=0) ){
108757       int i;
108758       for(i=0; i<pSrc->nSrc; i++){
108759         mask |= exprSelectTableUsage(pMaskSet, pSrc->a[i].pSelect);
108760         mask |= exprTableUsage(pMaskSet, pSrc->a[i].pOn);
108761       }
108762     }
108763     pS = pS->pPrior;
108764   }
108765   return mask;
108766 }
108767 
108768 /*
108769 ** Return TRUE if the given operator is one of the operators that is
108770 ** allowed for an indexable WHERE clause term.  The allowed operators are
108771 ** "=", "<", ">", "<=", ">=", "IN", and "IS NULL"
108772 */
108773 static int allowedOp(int op){
108774   assert( TK_GT>TK_EQ && TK_GT<TK_GE );
108775   assert( TK_LT>TK_EQ && TK_LT<TK_GE );
108776   assert( TK_LE>TK_EQ && TK_LE<TK_GE );
108777   assert( TK_GE==TK_EQ+4 );
108778   return op==TK_IN || (op>=TK_EQ && op<=TK_GE) || op==TK_ISNULL;
108779 }
108780 
108781 /*
108782 ** Swap two objects of type TYPE.
108783 */
108784 #define SWAP(TYPE,A,B) {TYPE t=A; A=B; B=t;}
108785 
108786 /*
108787 ** Commute a comparison operator.  Expressions of the form "X op Y"
108788 ** are converted into "Y op X".
108789 **
108790 ** If left/right precedence rules come into play when determining the
108791 ** collating sequence, then COLLATE operators are adjusted to ensure
108792 ** that the collating sequence does not change.  For example:
108793 ** "Y collate NOCASE op X" becomes "X op Y" because any collation sequence on
108794 ** the left hand side of a comparison overrides any collation sequence 
108795 ** attached to the right. For the same reason the EP_Collate flag
108796 ** is not commuted.
108797 */
108798 static void exprCommute(Parse *pParse, Expr *pExpr){
108799   u16 expRight = (pExpr->pRight->flags & EP_Collate);
108800   u16 expLeft = (pExpr->pLeft->flags & EP_Collate);
108801   assert( allowedOp(pExpr->op) && pExpr->op!=TK_IN );
108802   if( expRight==expLeft ){
108803     /* Either X and Y both have COLLATE operator or neither do */
108804     if( expRight ){
108805       /* Both X and Y have COLLATE operators.  Make sure X is always
108806       ** used by clearing the EP_Collate flag from Y. */
108807       pExpr->pRight->flags &= ~EP_Collate;
108808     }else if( sqlite3ExprCollSeq(pParse, pExpr->pLeft)!=0 ){
108809       /* Neither X nor Y have COLLATE operators, but X has a non-default
108810       ** collating sequence.  So add the EP_Collate marker on X to cause
108811       ** it to be searched first. */
108812       pExpr->pLeft->flags |= EP_Collate;
108813     }
108814   }
108815   SWAP(Expr*,pExpr->pRight,pExpr->pLeft);
108816   if( pExpr->op>=TK_GT ){
108817     assert( TK_LT==TK_GT+2 );
108818     assert( TK_GE==TK_LE+2 );
108819     assert( TK_GT>TK_EQ );
108820     assert( TK_GT<TK_LE );
108821     assert( pExpr->op>=TK_GT && pExpr->op<=TK_GE );
108822     pExpr->op = ((pExpr->op-TK_GT)^2)+TK_GT;
108823   }
108824 }
108825 
108826 /*
108827 ** Translate from TK_xx operator to WO_xx bitmask.
108828 */
108829 static u16 operatorMask(int op){
108830   u16 c;
108831   assert( allowedOp(op) );
108832   if( op==TK_IN ){
108833     c = WO_IN;
108834   }else if( op==TK_ISNULL ){
108835     c = WO_ISNULL;
108836   }else{
108837     assert( (WO_EQ<<(op-TK_EQ)) < 0x7fff );
108838     c = (u16)(WO_EQ<<(op-TK_EQ));
108839   }
108840   assert( op!=TK_ISNULL || c==WO_ISNULL );
108841   assert( op!=TK_IN || c==WO_IN );
108842   assert( op!=TK_EQ || c==WO_EQ );
108843   assert( op!=TK_LT || c==WO_LT );
108844   assert( op!=TK_LE || c==WO_LE );
108845   assert( op!=TK_GT || c==WO_GT );
108846   assert( op!=TK_GE || c==WO_GE );
108847   return c;
108848 }
108849 
108850 /*
108851 ** Advance to the next WhereTerm that matches according to the criteria
108852 ** established when the pScan object was initialized by whereScanInit().
108853 ** Return NULL if there are no more matching WhereTerms.
108854 */
108855 static WhereTerm *whereScanNext(WhereScan *pScan){
108856   int iCur;            /* The cursor on the LHS of the term */
108857   int iColumn;         /* The column on the LHS of the term.  -1 for IPK */
108858   Expr *pX;            /* An expression being tested */
108859   WhereClause *pWC;    /* Shorthand for pScan->pWC */
108860   WhereTerm *pTerm;    /* The term being tested */
108861   int k = pScan->k;    /* Where to start scanning */
108862 
108863   while( pScan->iEquiv<=pScan->nEquiv ){
108864     iCur = pScan->aEquiv[pScan->iEquiv-2];
108865     iColumn = pScan->aEquiv[pScan->iEquiv-1];
108866     while( (pWC = pScan->pWC)!=0 ){
108867       for(pTerm=pWC->a+k; k<pWC->nTerm; k++, pTerm++){
108868         if( pTerm->leftCursor==iCur
108869          && pTerm->u.leftColumn==iColumn
108870          && (pScan->iEquiv<=2 || !ExprHasProperty(pTerm->pExpr, EP_FromJoin))
108871         ){
108872           if( (pTerm->eOperator & WO_EQUIV)!=0
108873            && pScan->nEquiv<ArraySize(pScan->aEquiv)
108874           ){
108875             int j;
108876             pX = sqlite3ExprSkipCollate(pTerm->pExpr->pRight);
108877             assert( pX->op==TK_COLUMN );
108878             for(j=0; j<pScan->nEquiv; j+=2){
108879               if( pScan->aEquiv[j]==pX->iTable
108880                && pScan->aEquiv[j+1]==pX->iColumn ){
108881                   break;
108882               }
108883             }
108884             if( j==pScan->nEquiv ){
108885               pScan->aEquiv[j] = pX->iTable;
108886               pScan->aEquiv[j+1] = pX->iColumn;
108887               pScan->nEquiv += 2;
108888             }
108889           }
108890           if( (pTerm->eOperator & pScan->opMask)!=0 ){
108891             /* Verify the affinity and collating sequence match */
108892             if( pScan->zCollName && (pTerm->eOperator & WO_ISNULL)==0 ){
108893               CollSeq *pColl;
108894               Parse *pParse = pWC->pWInfo->pParse;
108895               pX = pTerm->pExpr;
108896               if( !sqlite3IndexAffinityOk(pX, pScan->idxaff) ){
108897                 continue;
108898               }
108899               assert(pX->pLeft);
108900               pColl = sqlite3BinaryCompareCollSeq(pParse,
108901                                                   pX->pLeft, pX->pRight);
108902               if( pColl==0 ) pColl = pParse->db->pDfltColl;
108903               if( sqlite3StrICmp(pColl->zName, pScan->zCollName) ){
108904                 continue;
108905               }
108906             }
108907             if( (pTerm->eOperator & WO_EQ)!=0
108908              && (pX = pTerm->pExpr->pRight)->op==TK_COLUMN
108909              && pX->iTable==pScan->aEquiv[0]
108910              && pX->iColumn==pScan->aEquiv[1]
108911             ){
108912               continue;
108913             }
108914             pScan->k = k+1;
108915             return pTerm;
108916           }
108917         }
108918       }
108919       pScan->pWC = pScan->pWC->pOuter;
108920       k = 0;
108921     }
108922     pScan->pWC = pScan->pOrigWC;
108923     k = 0;
108924     pScan->iEquiv += 2;
108925   }
108926   return 0;
108927 }
108928 
108929 /*
108930 ** Initialize a WHERE clause scanner object.  Return a pointer to the
108931 ** first match.  Return NULL if there are no matches.
108932 **
108933 ** The scanner will be searching the WHERE clause pWC.  It will look
108934 ** for terms of the form "X <op> <expr>" where X is column iColumn of table
108935 ** iCur.  The <op> must be one of the operators described by opMask.
108936 **
108937 ** If the search is for X and the WHERE clause contains terms of the
108938 ** form X=Y then this routine might also return terms of the form
108939 ** "Y <op> <expr>".  The number of levels of transitivity is limited,
108940 ** but is enough to handle most commonly occurring SQL statements.
108941 **
108942 ** If X is not the INTEGER PRIMARY KEY then X must be compatible with
108943 ** index pIdx.
108944 */
108945 static WhereTerm *whereScanInit(
108946   WhereScan *pScan,       /* The WhereScan object being initialized */
108947   WhereClause *pWC,       /* The WHERE clause to be scanned */
108948   int iCur,               /* Cursor to scan for */
108949   int iColumn,            /* Column to scan for */
108950   u32 opMask,             /* Operator(s) to scan for */
108951   Index *pIdx             /* Must be compatible with this index */
108952 ){
108953   int j;
108954 
108955   /* memset(pScan, 0, sizeof(*pScan)); */
108956   pScan->pOrigWC = pWC;
108957   pScan->pWC = pWC;
108958   if( pIdx && iColumn>=0 ){
108959     pScan->idxaff = pIdx->pTable->aCol[iColumn].affinity;
108960     for(j=0; pIdx->aiColumn[j]!=iColumn; j++){
108961       if( NEVER(j>=pIdx->nKeyCol) ) return 0;
108962     }
108963     pScan->zCollName = pIdx->azColl[j];
108964   }else{
108965     pScan->idxaff = 0;
108966     pScan->zCollName = 0;
108967   }
108968   pScan->opMask = opMask;
108969   pScan->k = 0;
108970   pScan->aEquiv[0] = iCur;
108971   pScan->aEquiv[1] = iColumn;
108972   pScan->nEquiv = 2;
108973   pScan->iEquiv = 2;
108974   return whereScanNext(pScan);
108975 }
108976 
108977 /*
108978 ** Search for a term in the WHERE clause that is of the form "X <op> <expr>"
108979 ** where X is a reference to the iColumn of table iCur and <op> is one of
108980 ** the WO_xx operator codes specified by the op parameter.
108981 ** Return a pointer to the term.  Return 0 if not found.
108982 **
108983 ** The term returned might by Y=<expr> if there is another constraint in
108984 ** the WHERE clause that specifies that X=Y.  Any such constraints will be
108985 ** identified by the WO_EQUIV bit in the pTerm->eOperator field.  The
108986 ** aEquiv[] array holds X and all its equivalents, with each SQL variable
108987 ** taking up two slots in aEquiv[].  The first slot is for the cursor number
108988 ** and the second is for the column number.  There are 22 slots in aEquiv[]
108989 ** so that means we can look for X plus up to 10 other equivalent values.
108990 ** Hence a search for X will return <expr> if X=A1 and A1=A2 and A2=A3
108991 ** and ... and A9=A10 and A10=<expr>.
108992 **
108993 ** If there are multiple terms in the WHERE clause of the form "X <op> <expr>"
108994 ** then try for the one with no dependencies on <expr> - in other words where
108995 ** <expr> is a constant expression of some kind.  Only return entries of
108996 ** the form "X <op> Y" where Y is a column in another table if no terms of
108997 ** the form "X <op> <const-expr>" exist.   If no terms with a constant RHS
108998 ** exist, try to return a term that does not use WO_EQUIV.
108999 */
109000 static WhereTerm *findTerm(
109001   WhereClause *pWC,     /* The WHERE clause to be searched */
109002   int iCur,             /* Cursor number of LHS */
109003   int iColumn,          /* Column number of LHS */
109004   Bitmask notReady,     /* RHS must not overlap with this mask */
109005   u32 op,               /* Mask of WO_xx values describing operator */
109006   Index *pIdx           /* Must be compatible with this index, if not NULL */
109007 ){
109008   WhereTerm *pResult = 0;
109009   WhereTerm *p;
109010   WhereScan scan;
109011 
109012   p = whereScanInit(&scan, pWC, iCur, iColumn, op, pIdx);
109013   while( p ){
109014     if( (p->prereqRight & notReady)==0 ){
109015       if( p->prereqRight==0 && (p->eOperator&WO_EQ)!=0 ){
109016         return p;
109017       }
109018       if( pResult==0 ) pResult = p;
109019     }
109020     p = whereScanNext(&scan);
109021   }
109022   return pResult;
109023 }
109024 
109025 /* Forward reference */
109026 static void exprAnalyze(SrcList*, WhereClause*, int);
109027 
109028 /*
109029 ** Call exprAnalyze on all terms in a WHERE clause.  
109030 */
109031 static void exprAnalyzeAll(
109032   SrcList *pTabList,       /* the FROM clause */
109033   WhereClause *pWC         /* the WHERE clause to be analyzed */
109034 ){
109035   int i;
109036   for(i=pWC->nTerm-1; i>=0; i--){
109037     exprAnalyze(pTabList, pWC, i);
109038   }
109039 }
109040 
109041 #ifndef SQLITE_OMIT_LIKE_OPTIMIZATION
109042 /*
109043 ** Check to see if the given expression is a LIKE or GLOB operator that
109044 ** can be optimized using inequality constraints.  Return TRUE if it is
109045 ** so and false if not.
109046 **
109047 ** In order for the operator to be optimizible, the RHS must be a string
109048 ** literal that does not begin with a wildcard.  
109049 */
109050 static int isLikeOrGlob(
109051   Parse *pParse,    /* Parsing and code generating context */
109052   Expr *pExpr,      /* Test this expression */
109053   Expr **ppPrefix,  /* Pointer to TK_STRING expression with pattern prefix */
109054   int *pisComplete, /* True if the only wildcard is % in the last character */
109055   int *pnoCase      /* True if uppercase is equivalent to lowercase */
109056 ){
109057   const char *z = 0;         /* String on RHS of LIKE operator */
109058   Expr *pRight, *pLeft;      /* Right and left size of LIKE operator */
109059   ExprList *pList;           /* List of operands to the LIKE operator */
109060   int c;                     /* One character in z[] */
109061   int cnt;                   /* Number of non-wildcard prefix characters */
109062   char wc[3];                /* Wildcard characters */
109063   sqlite3 *db = pParse->db;  /* Database connection */
109064   sqlite3_value *pVal = 0;
109065   int op;                    /* Opcode of pRight */
109066 
109067   if( !sqlite3IsLikeFunction(db, pExpr, pnoCase, wc) ){
109068     return 0;
109069   }
109070 #ifdef SQLITE_EBCDIC
109071   if( *pnoCase ) return 0;
109072 #endif
109073   pList = pExpr->x.pList;
109074   pLeft = pList->a[1].pExpr;
109075   if( pLeft->op!=TK_COLUMN 
109076    || sqlite3ExprAffinity(pLeft)!=SQLITE_AFF_TEXT 
109077    || IsVirtual(pLeft->pTab)
109078   ){
109079     /* IMP: R-02065-49465 The left-hand side of the LIKE or GLOB operator must
109080     ** be the name of an indexed column with TEXT affinity. */
109081     return 0;
109082   }
109083   assert( pLeft->iColumn!=(-1) ); /* Because IPK never has AFF_TEXT */
109084 
109085   pRight = pList->a[0].pExpr;
109086   op = pRight->op;
109087   if( op==TK_VARIABLE ){
109088     Vdbe *pReprepare = pParse->pReprepare;
109089     int iCol = pRight->iColumn;
109090     pVal = sqlite3VdbeGetBoundValue(pReprepare, iCol, SQLITE_AFF_NONE);
109091     if( pVal && sqlite3_value_type(pVal)==SQLITE_TEXT ){
109092       z = (char *)sqlite3_value_text(pVal);
109093     }
109094     sqlite3VdbeSetVarmask(pParse->pVdbe, iCol);
109095     assert( pRight->op==TK_VARIABLE || pRight->op==TK_REGISTER );
109096   }else if( op==TK_STRING ){
109097     z = pRight->u.zToken;
109098   }
109099   if( z ){
109100     cnt = 0;
109101     while( (c=z[cnt])!=0 && c!=wc[0] && c!=wc[1] && c!=wc[2] ){
109102       cnt++;
109103     }
109104     if( cnt!=0 && 255!=(u8)z[cnt-1] ){
109105       Expr *pPrefix;
109106       *pisComplete = c==wc[0] && z[cnt+1]==0;
109107       pPrefix = sqlite3Expr(db, TK_STRING, z);
109108       if( pPrefix ) pPrefix->u.zToken[cnt] = 0;
109109       *ppPrefix = pPrefix;
109110       if( op==TK_VARIABLE ){
109111         Vdbe *v = pParse->pVdbe;
109112         sqlite3VdbeSetVarmask(v, pRight->iColumn);
109113         if( *pisComplete && pRight->u.zToken[1] ){
109114           /* If the rhs of the LIKE expression is a variable, and the current
109115           ** value of the variable means there is no need to invoke the LIKE
109116           ** function, then no OP_Variable will be added to the program.
109117           ** This causes problems for the sqlite3_bind_parameter_name()
109118           ** API. To workaround them, add a dummy OP_Variable here.
109119           */ 
109120           int r1 = sqlite3GetTempReg(pParse);
109121           sqlite3ExprCodeTarget(pParse, pRight, r1);
109122           sqlite3VdbeChangeP3(v, sqlite3VdbeCurrentAddr(v)-1, 0);
109123           sqlite3ReleaseTempReg(pParse, r1);
109124         }
109125       }
109126     }else{
109127       z = 0;
109128     }
109129   }
109130 
109131   sqlite3ValueFree(pVal);
109132   return (z!=0);
109133 }
109134 #endif /* SQLITE_OMIT_LIKE_OPTIMIZATION */
109135 
109136 
109137 #ifndef SQLITE_OMIT_VIRTUALTABLE
109138 /*
109139 ** Check to see if the given expression is of the form
109140 **
109141 **         column MATCH expr
109142 **
109143 ** If it is then return TRUE.  If not, return FALSE.
109144 */
109145 static int isMatchOfColumn(
109146   Expr *pExpr      /* Test this expression */
109147 ){
109148   ExprList *pList;
109149 
109150   if( pExpr->op!=TK_FUNCTION ){
109151     return 0;
109152   }
109153   if( sqlite3StrICmp(pExpr->u.zToken,"match")!=0 ){
109154     return 0;
109155   }
109156   pList = pExpr->x.pList;
109157   if( pList->nExpr!=2 ){
109158     return 0;
109159   }
109160   if( pList->a[1].pExpr->op != TK_COLUMN ){
109161     return 0;
109162   }
109163   return 1;
109164 }
109165 #endif /* SQLITE_OMIT_VIRTUALTABLE */
109166 
109167 /*
109168 ** If the pBase expression originated in the ON or USING clause of
109169 ** a join, then transfer the appropriate markings over to derived.
109170 */
109171 static void transferJoinMarkings(Expr *pDerived, Expr *pBase){
109172   if( pDerived ){
109173     pDerived->flags |= pBase->flags & EP_FromJoin;
109174     pDerived->iRightJoinTable = pBase->iRightJoinTable;
109175   }
109176 }
109177 
109178 #if !defined(SQLITE_OMIT_OR_OPTIMIZATION) && !defined(SQLITE_OMIT_SUBQUERY)
109179 /*
109180 ** Analyze a term that consists of two or more OR-connected
109181 ** subterms.  So in:
109182 **
109183 **     ... WHERE  (a=5) AND (b=7 OR c=9 OR d=13) AND (d=13)
109184 **                          ^^^^^^^^^^^^^^^^^^^^
109185 **
109186 ** This routine analyzes terms such as the middle term in the above example.
109187 ** A WhereOrTerm object is computed and attached to the term under
109188 ** analysis, regardless of the outcome of the analysis.  Hence:
109189 **
109190 **     WhereTerm.wtFlags   |=  TERM_ORINFO
109191 **     WhereTerm.u.pOrInfo  =  a dynamically allocated WhereOrTerm object
109192 **
109193 ** The term being analyzed must have two or more of OR-connected subterms.
109194 ** A single subterm might be a set of AND-connected sub-subterms.
109195 ** Examples of terms under analysis:
109196 **
109197 **     (A)     t1.x=t2.y OR t1.x=t2.z OR t1.y=15 OR t1.z=t3.a+5
109198 **     (B)     x=expr1 OR expr2=x OR x=expr3
109199 **     (C)     t1.x=t2.y OR (t1.x=t2.z AND t1.y=15)
109200 **     (D)     x=expr1 OR (y>11 AND y<22 AND z LIKE '*hello*')
109201 **     (E)     (p.a=1 AND q.b=2 AND r.c=3) OR (p.x=4 AND q.y=5 AND r.z=6)
109202 **
109203 ** CASE 1:
109204 **
109205 ** If all subterms are of the form T.C=expr for some single column of C and
109206 ** a single table T (as shown in example B above) then create a new virtual
109207 ** term that is an equivalent IN expression.  In other words, if the term
109208 ** being analyzed is:
109209 **
109210 **      x = expr1  OR  expr2 = x  OR  x = expr3
109211 **
109212 ** then create a new virtual term like this:
109213 **
109214 **      x IN (expr1,expr2,expr3)
109215 **
109216 ** CASE 2:
109217 **
109218 ** If all subterms are indexable by a single table T, then set
109219 **
109220 **     WhereTerm.eOperator              =  WO_OR
109221 **     WhereTerm.u.pOrInfo->indexable  |=  the cursor number for table T
109222 **
109223 ** A subterm is "indexable" if it is of the form
109224 ** "T.C <op> <expr>" where C is any column of table T and 
109225 ** <op> is one of "=", "<", "<=", ">", ">=", "IS NULL", or "IN".
109226 ** A subterm is also indexable if it is an AND of two or more
109227 ** subsubterms at least one of which is indexable.  Indexable AND 
109228 ** subterms have their eOperator set to WO_AND and they have
109229 ** u.pAndInfo set to a dynamically allocated WhereAndTerm object.
109230 **
109231 ** From another point of view, "indexable" means that the subterm could
109232 ** potentially be used with an index if an appropriate index exists.
109233 ** This analysis does not consider whether or not the index exists; that
109234 ** is decided elsewhere.  This analysis only looks at whether subterms
109235 ** appropriate for indexing exist.
109236 **
109237 ** All examples A through E above satisfy case 2.  But if a term
109238 ** also statisfies case 1 (such as B) we know that the optimizer will
109239 ** always prefer case 1, so in that case we pretend that case 2 is not
109240 ** satisfied.
109241 **
109242 ** It might be the case that multiple tables are indexable.  For example,
109243 ** (E) above is indexable on tables P, Q, and R.
109244 **
109245 ** Terms that satisfy case 2 are candidates for lookup by using
109246 ** separate indices to find rowids for each subterm and composing
109247 ** the union of all rowids using a RowSet object.  This is similar
109248 ** to "bitmap indices" in other database engines.
109249 **
109250 ** OTHERWISE:
109251 **
109252 ** If neither case 1 nor case 2 apply, then leave the eOperator set to
109253 ** zero.  This term is not useful for search.
109254 */
109255 static void exprAnalyzeOrTerm(
109256   SrcList *pSrc,            /* the FROM clause */
109257   WhereClause *pWC,         /* the complete WHERE clause */
109258   int idxTerm               /* Index of the OR-term to be analyzed */
109259 ){
109260   WhereInfo *pWInfo = pWC->pWInfo;        /* WHERE clause processing context */
109261   Parse *pParse = pWInfo->pParse;         /* Parser context */
109262   sqlite3 *db = pParse->db;               /* Database connection */
109263   WhereTerm *pTerm = &pWC->a[idxTerm];    /* The term to be analyzed */
109264   Expr *pExpr = pTerm->pExpr;             /* The expression of the term */
109265   int i;                                  /* Loop counters */
109266   WhereClause *pOrWc;       /* Breakup of pTerm into subterms */
109267   WhereTerm *pOrTerm;       /* A Sub-term within the pOrWc */
109268   WhereOrInfo *pOrInfo;     /* Additional information associated with pTerm */
109269   Bitmask chngToIN;         /* Tables that might satisfy case 1 */
109270   Bitmask indexable;        /* Tables that are indexable, satisfying case 2 */
109271 
109272   /*
109273   ** Break the OR clause into its separate subterms.  The subterms are
109274   ** stored in a WhereClause structure containing within the WhereOrInfo
109275   ** object that is attached to the original OR clause term.
109276   */
109277   assert( (pTerm->wtFlags & (TERM_DYNAMIC|TERM_ORINFO|TERM_ANDINFO))==0 );
109278   assert( pExpr->op==TK_OR );
109279   pTerm->u.pOrInfo = pOrInfo = sqlite3DbMallocZero(db, sizeof(*pOrInfo));
109280   if( pOrInfo==0 ) return;
109281   pTerm->wtFlags |= TERM_ORINFO;
109282   pOrWc = &pOrInfo->wc;
109283   whereClauseInit(pOrWc, pWInfo);
109284   whereSplit(pOrWc, pExpr, TK_OR);
109285   exprAnalyzeAll(pSrc, pOrWc);
109286   if( db->mallocFailed ) return;
109287   assert( pOrWc->nTerm>=2 );
109288 
109289   /*
109290   ** Compute the set of tables that might satisfy cases 1 or 2.
109291   */
109292   indexable = ~(Bitmask)0;
109293   chngToIN = ~(Bitmask)0;
109294   for(i=pOrWc->nTerm-1, pOrTerm=pOrWc->a; i>=0 && indexable; i--, pOrTerm++){
109295     if( (pOrTerm->eOperator & WO_SINGLE)==0 ){
109296       WhereAndInfo *pAndInfo;
109297       assert( (pOrTerm->wtFlags & (TERM_ANDINFO|TERM_ORINFO))==0 );
109298       chngToIN = 0;
109299       pAndInfo = sqlite3DbMallocRaw(db, sizeof(*pAndInfo));
109300       if( pAndInfo ){
109301         WhereClause *pAndWC;
109302         WhereTerm *pAndTerm;
109303         int j;
109304         Bitmask b = 0;
109305         pOrTerm->u.pAndInfo = pAndInfo;
109306         pOrTerm->wtFlags |= TERM_ANDINFO;
109307         pOrTerm->eOperator = WO_AND;
109308         pAndWC = &pAndInfo->wc;
109309         whereClauseInit(pAndWC, pWC->pWInfo);
109310         whereSplit(pAndWC, pOrTerm->pExpr, TK_AND);
109311         exprAnalyzeAll(pSrc, pAndWC);
109312         pAndWC->pOuter = pWC;
109313         testcase( db->mallocFailed );
109314         if( !db->mallocFailed ){
109315           for(j=0, pAndTerm=pAndWC->a; j<pAndWC->nTerm; j++, pAndTerm++){
109316             assert( pAndTerm->pExpr );
109317             if( allowedOp(pAndTerm->pExpr->op) ){
109318               b |= getMask(&pWInfo->sMaskSet, pAndTerm->leftCursor);
109319             }
109320           }
109321         }
109322         indexable &= b;
109323       }
109324     }else if( pOrTerm->wtFlags & TERM_COPIED ){
109325       /* Skip this term for now.  We revisit it when we process the
109326       ** corresponding TERM_VIRTUAL term */
109327     }else{
109328       Bitmask b;
109329       b = getMask(&pWInfo->sMaskSet, pOrTerm->leftCursor);
109330       if( pOrTerm->wtFlags & TERM_VIRTUAL ){
109331         WhereTerm *pOther = &pOrWc->a[pOrTerm->iParent];
109332         b |= getMask(&pWInfo->sMaskSet, pOther->leftCursor);
109333       }
109334       indexable &= b;
109335       if( (pOrTerm->eOperator & WO_EQ)==0 ){
109336         chngToIN = 0;
109337       }else{
109338         chngToIN &= b;
109339       }
109340     }
109341   }
109342 
109343   /*
109344   ** Record the set of tables that satisfy case 2.  The set might be
109345   ** empty.
109346   */
109347   pOrInfo->indexable = indexable;
109348   pTerm->eOperator = indexable==0 ? 0 : WO_OR;
109349 
109350   /*
109351   ** chngToIN holds a set of tables that *might* satisfy case 1.  But
109352   ** we have to do some additional checking to see if case 1 really
109353   ** is satisfied.
109354   **
109355   ** chngToIN will hold either 0, 1, or 2 bits.  The 0-bit case means
109356   ** that there is no possibility of transforming the OR clause into an
109357   ** IN operator because one or more terms in the OR clause contain
109358   ** something other than == on a column in the single table.  The 1-bit
109359   ** case means that every term of the OR clause is of the form
109360   ** "table.column=expr" for some single table.  The one bit that is set
109361   ** will correspond to the common table.  We still need to check to make
109362   ** sure the same column is used on all terms.  The 2-bit case is when
109363   ** the all terms are of the form "table1.column=table2.column".  It
109364   ** might be possible to form an IN operator with either table1.column
109365   ** or table2.column as the LHS if either is common to every term of
109366   ** the OR clause.
109367   **
109368   ** Note that terms of the form "table.column1=table.column2" (the
109369   ** same table on both sizes of the ==) cannot be optimized.
109370   */
109371   if( chngToIN ){
109372     int okToChngToIN = 0;     /* True if the conversion to IN is valid */
109373     int iColumn = -1;         /* Column index on lhs of IN operator */
109374     int iCursor = -1;         /* Table cursor common to all terms */
109375     int j = 0;                /* Loop counter */
109376 
109377     /* Search for a table and column that appears on one side or the
109378     ** other of the == operator in every subterm.  That table and column
109379     ** will be recorded in iCursor and iColumn.  There might not be any
109380     ** such table and column.  Set okToChngToIN if an appropriate table
109381     ** and column is found but leave okToChngToIN false if not found.
109382     */
109383     for(j=0; j<2 && !okToChngToIN; j++){
109384       pOrTerm = pOrWc->a;
109385       for(i=pOrWc->nTerm-1; i>=0; i--, pOrTerm++){
109386         assert( pOrTerm->eOperator & WO_EQ );
109387         pOrTerm->wtFlags &= ~TERM_OR_OK;
109388         if( pOrTerm->leftCursor==iCursor ){
109389           /* This is the 2-bit case and we are on the second iteration and
109390           ** current term is from the first iteration.  So skip this term. */
109391           assert( j==1 );
109392           continue;
109393         }
109394         if( (chngToIN & getMask(&pWInfo->sMaskSet, pOrTerm->leftCursor))==0 ){
109395           /* This term must be of the form t1.a==t2.b where t2 is in the
109396           ** chngToIN set but t1 is not.  This term will be either preceeded
109397           ** or follwed by an inverted copy (t2.b==t1.a).  Skip this term 
109398           ** and use its inversion. */
109399           testcase( pOrTerm->wtFlags & TERM_COPIED );
109400           testcase( pOrTerm->wtFlags & TERM_VIRTUAL );
109401           assert( pOrTerm->wtFlags & (TERM_COPIED|TERM_VIRTUAL) );
109402           continue;
109403         }
109404         iColumn = pOrTerm->u.leftColumn;
109405         iCursor = pOrTerm->leftCursor;
109406         break;
109407       }
109408       if( i<0 ){
109409         /* No candidate table+column was found.  This can only occur
109410         ** on the second iteration */
109411         assert( j==1 );
109412         assert( IsPowerOfTwo(chngToIN) );
109413         assert( chngToIN==getMask(&pWInfo->sMaskSet, iCursor) );
109414         break;
109415       }
109416       testcase( j==1 );
109417 
109418       /* We have found a candidate table and column.  Check to see if that
109419       ** table and column is common to every term in the OR clause */
109420       okToChngToIN = 1;
109421       for(; i>=0 && okToChngToIN; i--, pOrTerm++){
109422         assert( pOrTerm->eOperator & WO_EQ );
109423         if( pOrTerm->leftCursor!=iCursor ){
109424           pOrTerm->wtFlags &= ~TERM_OR_OK;
109425         }else if( pOrTerm->u.leftColumn!=iColumn ){
109426           okToChngToIN = 0;
109427         }else{
109428           int affLeft, affRight;
109429           /* If the right-hand side is also a column, then the affinities
109430           ** of both right and left sides must be such that no type
109431           ** conversions are required on the right.  (Ticket #2249)
109432           */
109433           affRight = sqlite3ExprAffinity(pOrTerm->pExpr->pRight);
109434           affLeft = sqlite3ExprAffinity(pOrTerm->pExpr->pLeft);
109435           if( affRight!=0 && affRight!=affLeft ){
109436             okToChngToIN = 0;
109437           }else{
109438             pOrTerm->wtFlags |= TERM_OR_OK;
109439           }
109440         }
109441       }
109442     }
109443 
109444     /* At this point, okToChngToIN is true if original pTerm satisfies
109445     ** case 1.  In that case, construct a new virtual term that is 
109446     ** pTerm converted into an IN operator.
109447     */
109448     if( okToChngToIN ){
109449       Expr *pDup;            /* A transient duplicate expression */
109450       ExprList *pList = 0;   /* The RHS of the IN operator */
109451       Expr *pLeft = 0;       /* The LHS of the IN operator */
109452       Expr *pNew;            /* The complete IN operator */
109453 
109454       for(i=pOrWc->nTerm-1, pOrTerm=pOrWc->a; i>=0; i--, pOrTerm++){
109455         if( (pOrTerm->wtFlags & TERM_OR_OK)==0 ) continue;
109456         assert( pOrTerm->eOperator & WO_EQ );
109457         assert( pOrTerm->leftCursor==iCursor );
109458         assert( pOrTerm->u.leftColumn==iColumn );
109459         pDup = sqlite3ExprDup(db, pOrTerm->pExpr->pRight, 0);
109460         pList = sqlite3ExprListAppend(pWInfo->pParse, pList, pDup);
109461         pLeft = pOrTerm->pExpr->pLeft;
109462       }
109463       assert( pLeft!=0 );
109464       pDup = sqlite3ExprDup(db, pLeft, 0);
109465       pNew = sqlite3PExpr(pParse, TK_IN, pDup, 0, 0);
109466       if( pNew ){
109467         int idxNew;
109468         transferJoinMarkings(pNew, pExpr);
109469         assert( !ExprHasProperty(pNew, EP_xIsSelect) );
109470         pNew->x.pList = pList;
109471         idxNew = whereClauseInsert(pWC, pNew, TERM_VIRTUAL|TERM_DYNAMIC);
109472         testcase( idxNew==0 );
109473         exprAnalyze(pSrc, pWC, idxNew);
109474         pTerm = &pWC->a[idxTerm];
109475         pWC->a[idxNew].iParent = idxTerm;
109476         pTerm->nChild = 1;
109477       }else{
109478         sqlite3ExprListDelete(db, pList);
109479       }
109480       pTerm->eOperator = WO_NOOP;  /* case 1 trumps case 2 */
109481     }
109482   }
109483 }
109484 #endif /* !SQLITE_OMIT_OR_OPTIMIZATION && !SQLITE_OMIT_SUBQUERY */
109485 
109486 /*
109487 ** The input to this routine is an WhereTerm structure with only the
109488 ** "pExpr" field filled in.  The job of this routine is to analyze the
109489 ** subexpression and populate all the other fields of the WhereTerm
109490 ** structure.
109491 **
109492 ** If the expression is of the form "<expr> <op> X" it gets commuted
109493 ** to the standard form of "X <op> <expr>".
109494 **
109495 ** If the expression is of the form "X <op> Y" where both X and Y are
109496 ** columns, then the original expression is unchanged and a new virtual
109497 ** term of the form "Y <op> X" is added to the WHERE clause and
109498 ** analyzed separately.  The original term is marked with TERM_COPIED
109499 ** and the new term is marked with TERM_DYNAMIC (because it's pExpr
109500 ** needs to be freed with the WhereClause) and TERM_VIRTUAL (because it
109501 ** is a commuted copy of a prior term.)  The original term has nChild=1
109502 ** and the copy has idxParent set to the index of the original term.
109503 */
109504 static void exprAnalyze(
109505   SrcList *pSrc,            /* the FROM clause */
109506   WhereClause *pWC,         /* the WHERE clause */
109507   int idxTerm               /* Index of the term to be analyzed */
109508 ){
109509   WhereInfo *pWInfo = pWC->pWInfo; /* WHERE clause processing context */
109510   WhereTerm *pTerm;                /* The term to be analyzed */
109511   WhereMaskSet *pMaskSet;          /* Set of table index masks */
109512   Expr *pExpr;                     /* The expression to be analyzed */
109513   Bitmask prereqLeft;              /* Prerequesites of the pExpr->pLeft */
109514   Bitmask prereqAll;               /* Prerequesites of pExpr */
109515   Bitmask extraRight = 0;          /* Extra dependencies on LEFT JOIN */
109516   Expr *pStr1 = 0;                 /* RHS of LIKE/GLOB operator */
109517   int isComplete = 0;              /* RHS of LIKE/GLOB ends with wildcard */
109518   int noCase = 0;                  /* LIKE/GLOB distinguishes case */
109519   int op;                          /* Top-level operator.  pExpr->op */
109520   Parse *pParse = pWInfo->pParse;  /* Parsing context */
109521   sqlite3 *db = pParse->db;        /* Database connection */
109522 
109523   if( db->mallocFailed ){
109524     return;
109525   }
109526   pTerm = &pWC->a[idxTerm];
109527   pMaskSet = &pWInfo->sMaskSet;
109528   pExpr = pTerm->pExpr;
109529   assert( pExpr->op!=TK_AS && pExpr->op!=TK_COLLATE );
109530   prereqLeft = exprTableUsage(pMaskSet, pExpr->pLeft);
109531   op = pExpr->op;
109532   if( op==TK_IN ){
109533     assert( pExpr->pRight==0 );
109534     if( ExprHasProperty(pExpr, EP_xIsSelect) ){
109535       pTerm->prereqRight = exprSelectTableUsage(pMaskSet, pExpr->x.pSelect);
109536     }else{
109537       pTerm->prereqRight = exprListTableUsage(pMaskSet, pExpr->x.pList);
109538     }
109539   }else if( op==TK_ISNULL ){
109540     pTerm->prereqRight = 0;
109541   }else{
109542     pTerm->prereqRight = exprTableUsage(pMaskSet, pExpr->pRight);
109543   }
109544   prereqAll = exprTableUsage(pMaskSet, pExpr);
109545   if( ExprHasProperty(pExpr, EP_FromJoin) ){
109546     Bitmask x = getMask(pMaskSet, pExpr->iRightJoinTable);
109547     prereqAll |= x;
109548     extraRight = x-1;  /* ON clause terms may not be used with an index
109549                        ** on left table of a LEFT JOIN.  Ticket #3015 */
109550   }
109551   pTerm->prereqAll = prereqAll;
109552   pTerm->leftCursor = -1;
109553   pTerm->iParent = -1;
109554   pTerm->eOperator = 0;
109555   if( allowedOp(op) ){
109556     Expr *pLeft = sqlite3ExprSkipCollate(pExpr->pLeft);
109557     Expr *pRight = sqlite3ExprSkipCollate(pExpr->pRight);
109558     u16 opMask = (pTerm->prereqRight & prereqLeft)==0 ? WO_ALL : WO_EQUIV;
109559     if( pLeft->op==TK_COLUMN ){
109560       pTerm->leftCursor = pLeft->iTable;
109561       pTerm->u.leftColumn = pLeft->iColumn;
109562       pTerm->eOperator = operatorMask(op) & opMask;
109563     }
109564     if( pRight && pRight->op==TK_COLUMN ){
109565       WhereTerm *pNew;
109566       Expr *pDup;
109567       u16 eExtraOp = 0;        /* Extra bits for pNew->eOperator */
109568       if( pTerm->leftCursor>=0 ){
109569         int idxNew;
109570         pDup = sqlite3ExprDup(db, pExpr, 0);
109571         if( db->mallocFailed ){
109572           sqlite3ExprDelete(db, pDup);
109573           return;
109574         }
109575         idxNew = whereClauseInsert(pWC, pDup, TERM_VIRTUAL|TERM_DYNAMIC);
109576         if( idxNew==0 ) return;
109577         pNew = &pWC->a[idxNew];
109578         pNew->iParent = idxTerm;
109579         pTerm = &pWC->a[idxTerm];
109580         pTerm->nChild = 1;
109581         pTerm->wtFlags |= TERM_COPIED;
109582         if( pExpr->op==TK_EQ
109583          && !ExprHasProperty(pExpr, EP_FromJoin)
109584          && OptimizationEnabled(db, SQLITE_Transitive)
109585         ){
109586           pTerm->eOperator |= WO_EQUIV;
109587           eExtraOp = WO_EQUIV;
109588         }
109589       }else{
109590         pDup = pExpr;
109591         pNew = pTerm;
109592       }
109593       exprCommute(pParse, pDup);
109594       pLeft = sqlite3ExprSkipCollate(pDup->pLeft);
109595       pNew->leftCursor = pLeft->iTable;
109596       pNew->u.leftColumn = pLeft->iColumn;
109597       testcase( (prereqLeft | extraRight) != prereqLeft );
109598       pNew->prereqRight = prereqLeft | extraRight;
109599       pNew->prereqAll = prereqAll;
109600       pNew->eOperator = (operatorMask(pDup->op) + eExtraOp) & opMask;
109601     }
109602   }
109603 
109604 #ifndef SQLITE_OMIT_BETWEEN_OPTIMIZATION
109605   /* If a term is the BETWEEN operator, create two new virtual terms
109606   ** that define the range that the BETWEEN implements.  For example:
109607   **
109608   **      a BETWEEN b AND c
109609   **
109610   ** is converted into:
109611   **
109612   **      (a BETWEEN b AND c) AND (a>=b) AND (a<=c)
109613   **
109614   ** The two new terms are added onto the end of the WhereClause object.
109615   ** The new terms are "dynamic" and are children of the original BETWEEN
109616   ** term.  That means that if the BETWEEN term is coded, the children are
109617   ** skipped.  Or, if the children are satisfied by an index, the original
109618   ** BETWEEN term is skipped.
109619   */
109620   else if( pExpr->op==TK_BETWEEN && pWC->op==TK_AND ){
109621     ExprList *pList = pExpr->x.pList;
109622     int i;
109623     static const u8 ops[] = {TK_GE, TK_LE};
109624     assert( pList!=0 );
109625     assert( pList->nExpr==2 );
109626     for(i=0; i<2; i++){
109627       Expr *pNewExpr;
109628       int idxNew;
109629       pNewExpr = sqlite3PExpr(pParse, ops[i], 
109630                              sqlite3ExprDup(db, pExpr->pLeft, 0),
109631                              sqlite3ExprDup(db, pList->a[i].pExpr, 0), 0);
109632       transferJoinMarkings(pNewExpr, pExpr);
109633       idxNew = whereClauseInsert(pWC, pNewExpr, TERM_VIRTUAL|TERM_DYNAMIC);
109634       testcase( idxNew==0 );
109635       exprAnalyze(pSrc, pWC, idxNew);
109636       pTerm = &pWC->a[idxTerm];
109637       pWC->a[idxNew].iParent = idxTerm;
109638     }
109639     pTerm->nChild = 2;
109640   }
109641 #endif /* SQLITE_OMIT_BETWEEN_OPTIMIZATION */
109642 
109643 #if !defined(SQLITE_OMIT_OR_OPTIMIZATION) && !defined(SQLITE_OMIT_SUBQUERY)
109644   /* Analyze a term that is composed of two or more subterms connected by
109645   ** an OR operator.
109646   */
109647   else if( pExpr->op==TK_OR ){
109648     assert( pWC->op==TK_AND );
109649     exprAnalyzeOrTerm(pSrc, pWC, idxTerm);
109650     pTerm = &pWC->a[idxTerm];
109651   }
109652 #endif /* SQLITE_OMIT_OR_OPTIMIZATION */
109653 
109654 #ifndef SQLITE_OMIT_LIKE_OPTIMIZATION
109655   /* Add constraints to reduce the search space on a LIKE or GLOB
109656   ** operator.
109657   **
109658   ** A like pattern of the form "x LIKE 'abc%'" is changed into constraints
109659   **
109660   **          x>='abc' AND x<'abd' AND x LIKE 'abc%'
109661   **
109662   ** The last character of the prefix "abc" is incremented to form the
109663   ** termination condition "abd".
109664   */
109665   if( pWC->op==TK_AND 
109666    && isLikeOrGlob(pParse, pExpr, &pStr1, &isComplete, &noCase)
109667   ){
109668     Expr *pLeft;       /* LHS of LIKE/GLOB operator */
109669     Expr *pStr2;       /* Copy of pStr1 - RHS of LIKE/GLOB operator */
109670     Expr *pNewExpr1;
109671     Expr *pNewExpr2;
109672     int idxNew1;
109673     int idxNew2;
109674     Token sCollSeqName;  /* Name of collating sequence */
109675 
109676     pLeft = pExpr->x.pList->a[1].pExpr;
109677     pStr2 = sqlite3ExprDup(db, pStr1, 0);
109678     if( !db->mallocFailed ){
109679       u8 c, *pC;       /* Last character before the first wildcard */
109680       pC = (u8*)&pStr2->u.zToken[sqlite3Strlen30(pStr2->u.zToken)-1];
109681       c = *pC;
109682       if( noCase ){
109683         /* The point is to increment the last character before the first
109684         ** wildcard.  But if we increment '@', that will push it into the
109685         ** alphabetic range where case conversions will mess up the 
109686         ** inequality.  To avoid this, make sure to also run the full
109687         ** LIKE on all candidate expressions by clearing the isComplete flag
109688         */
109689         if( c=='A'-1 ) isComplete = 0;
109690         c = sqlite3UpperToLower[c];
109691       }
109692       *pC = c + 1;
109693     }
109694     sCollSeqName.z = noCase ? "NOCASE" : "BINARY";
109695     sCollSeqName.n = 6;
109696     pNewExpr1 = sqlite3ExprDup(db, pLeft, 0);
109697     pNewExpr1 = sqlite3PExpr(pParse, TK_GE, 
109698            sqlite3ExprAddCollateToken(pParse,pNewExpr1,&sCollSeqName),
109699            pStr1, 0);
109700     transferJoinMarkings(pNewExpr1, pExpr);
109701     idxNew1 = whereClauseInsert(pWC, pNewExpr1, TERM_VIRTUAL|TERM_DYNAMIC);
109702     testcase( idxNew1==0 );
109703     exprAnalyze(pSrc, pWC, idxNew1);
109704     pNewExpr2 = sqlite3ExprDup(db, pLeft, 0);
109705     pNewExpr2 = sqlite3PExpr(pParse, TK_LT,
109706            sqlite3ExprAddCollateToken(pParse,pNewExpr2,&sCollSeqName),
109707            pStr2, 0);
109708     transferJoinMarkings(pNewExpr2, pExpr);
109709     idxNew2 = whereClauseInsert(pWC, pNewExpr2, TERM_VIRTUAL|TERM_DYNAMIC);
109710     testcase( idxNew2==0 );
109711     exprAnalyze(pSrc, pWC, idxNew2);
109712     pTerm = &pWC->a[idxTerm];
109713     if( isComplete ){
109714       pWC->a[idxNew1].iParent = idxTerm;
109715       pWC->a[idxNew2].iParent = idxTerm;
109716       pTerm->nChild = 2;
109717     }
109718   }
109719 #endif /* SQLITE_OMIT_LIKE_OPTIMIZATION */
109720 
109721 #ifndef SQLITE_OMIT_VIRTUALTABLE
109722   /* Add a WO_MATCH auxiliary term to the constraint set if the
109723   ** current expression is of the form:  column MATCH expr.
109724   ** This information is used by the xBestIndex methods of
109725   ** virtual tables.  The native query optimizer does not attempt
109726   ** to do anything with MATCH functions.
109727   */
109728   if( isMatchOfColumn(pExpr) ){
109729     int idxNew;
109730     Expr *pRight, *pLeft;
109731     WhereTerm *pNewTerm;
109732     Bitmask prereqColumn, prereqExpr;
109733 
109734     pRight = pExpr->x.pList->a[0].pExpr;
109735     pLeft = pExpr->x.pList->a[1].pExpr;
109736     prereqExpr = exprTableUsage(pMaskSet, pRight);
109737     prereqColumn = exprTableUsage(pMaskSet, pLeft);
109738     if( (prereqExpr & prereqColumn)==0 ){
109739       Expr *pNewExpr;
109740       pNewExpr = sqlite3PExpr(pParse, TK_MATCH, 
109741                               0, sqlite3ExprDup(db, pRight, 0), 0);
109742       idxNew = whereClauseInsert(pWC, pNewExpr, TERM_VIRTUAL|TERM_DYNAMIC);
109743       testcase( idxNew==0 );
109744       pNewTerm = &pWC->a[idxNew];
109745       pNewTerm->prereqRight = prereqExpr;
109746       pNewTerm->leftCursor = pLeft->iTable;
109747       pNewTerm->u.leftColumn = pLeft->iColumn;
109748       pNewTerm->eOperator = WO_MATCH;
109749       pNewTerm->iParent = idxTerm;
109750       pTerm = &pWC->a[idxTerm];
109751       pTerm->nChild = 1;
109752       pTerm->wtFlags |= TERM_COPIED;
109753       pNewTerm->prereqAll = pTerm->prereqAll;
109754     }
109755   }
109756 #endif /* SQLITE_OMIT_VIRTUALTABLE */
109757 
109758 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
109759   /* When sqlite_stat3 histogram data is available an operator of the
109760   ** form "x IS NOT NULL" can sometimes be evaluated more efficiently
109761   ** as "x>NULL" if x is not an INTEGER PRIMARY KEY.  So construct a
109762   ** virtual term of that form.
109763   **
109764   ** Note that the virtual term must be tagged with TERM_VNULL.  This
109765   ** TERM_VNULL tag will suppress the not-null check at the beginning
109766   ** of the loop.  Without the TERM_VNULL flag, the not-null check at
109767   ** the start of the loop will prevent any results from being returned.
109768   */
109769   if( pExpr->op==TK_NOTNULL
109770    && pExpr->pLeft->op==TK_COLUMN
109771    && pExpr->pLeft->iColumn>=0
109772    && OptimizationEnabled(db, SQLITE_Stat3)
109773   ){
109774     Expr *pNewExpr;
109775     Expr *pLeft = pExpr->pLeft;
109776     int idxNew;
109777     WhereTerm *pNewTerm;
109778 
109779     pNewExpr = sqlite3PExpr(pParse, TK_GT,
109780                             sqlite3ExprDup(db, pLeft, 0),
109781                             sqlite3PExpr(pParse, TK_NULL, 0, 0, 0), 0);
109782 
109783     idxNew = whereClauseInsert(pWC, pNewExpr,
109784                               TERM_VIRTUAL|TERM_DYNAMIC|TERM_VNULL);
109785     if( idxNew ){
109786       pNewTerm = &pWC->a[idxNew];
109787       pNewTerm->prereqRight = 0;
109788       pNewTerm->leftCursor = pLeft->iTable;
109789       pNewTerm->u.leftColumn = pLeft->iColumn;
109790       pNewTerm->eOperator = WO_GT;
109791       pNewTerm->iParent = idxTerm;
109792       pTerm = &pWC->a[idxTerm];
109793       pTerm->nChild = 1;
109794       pTerm->wtFlags |= TERM_COPIED;
109795       pNewTerm->prereqAll = pTerm->prereqAll;
109796     }
109797   }
109798 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
109799 
109800   /* Prevent ON clause terms of a LEFT JOIN from being used to drive
109801   ** an index for tables to the left of the join.
109802   */
109803   pTerm->prereqRight |= extraRight;
109804 }
109805 
109806 /*
109807 ** This function searches pList for a entry that matches the iCol-th column
109808 ** of index pIdx.
109809 **
109810 ** If such an expression is found, its index in pList->a[] is returned. If
109811 ** no expression is found, -1 is returned.
109812 */
109813 static int findIndexCol(
109814   Parse *pParse,                  /* Parse context */
109815   ExprList *pList,                /* Expression list to search */
109816   int iBase,                      /* Cursor for table associated with pIdx */
109817   Index *pIdx,                    /* Index to match column of */
109818   int iCol                        /* Column of index to match */
109819 ){
109820   int i;
109821   const char *zColl = pIdx->azColl[iCol];
109822 
109823   for(i=0; i<pList->nExpr; i++){
109824     Expr *p = sqlite3ExprSkipCollate(pList->a[i].pExpr);
109825     if( p->op==TK_COLUMN
109826      && p->iColumn==pIdx->aiColumn[iCol]
109827      && p->iTable==iBase
109828     ){
109829       CollSeq *pColl = sqlite3ExprCollSeq(pParse, pList->a[i].pExpr);
109830       if( ALWAYS(pColl) && 0==sqlite3StrICmp(pColl->zName, zColl) ){
109831         return i;
109832       }
109833     }
109834   }
109835 
109836   return -1;
109837 }
109838 
109839 /*
109840 ** Return true if the DISTINCT expression-list passed as the third argument
109841 ** is redundant.
109842 **
109843 ** A DISTINCT list is redundant if the database contains some subset of
109844 ** columns that are unique and non-null.
109845 */
109846 static int isDistinctRedundant(
109847   Parse *pParse,            /* Parsing context */
109848   SrcList *pTabList,        /* The FROM clause */
109849   WhereClause *pWC,         /* The WHERE clause */
109850   ExprList *pDistinct       /* The result set that needs to be DISTINCT */
109851 ){
109852   Table *pTab;
109853   Index *pIdx;
109854   int i;                          
109855   int iBase;
109856 
109857   /* If there is more than one table or sub-select in the FROM clause of
109858   ** this query, then it will not be possible to show that the DISTINCT 
109859   ** clause is redundant. */
109860   if( pTabList->nSrc!=1 ) return 0;
109861   iBase = pTabList->a[0].iCursor;
109862   pTab = pTabList->a[0].pTab;
109863 
109864   /* If any of the expressions is an IPK column on table iBase, then return 
109865   ** true. Note: The (p->iTable==iBase) part of this test may be false if the
109866   ** current SELECT is a correlated sub-query.
109867   */
109868   for(i=0; i<pDistinct->nExpr; i++){
109869     Expr *p = sqlite3ExprSkipCollate(pDistinct->a[i].pExpr);
109870     if( p->op==TK_COLUMN && p->iTable==iBase && p->iColumn<0 ) return 1;
109871   }
109872 
109873   /* Loop through all indices on the table, checking each to see if it makes
109874   ** the DISTINCT qualifier redundant. It does so if:
109875   **
109876   **   1. The index is itself UNIQUE, and
109877   **
109878   **   2. All of the columns in the index are either part of the pDistinct
109879   **      list, or else the WHERE clause contains a term of the form "col=X",
109880   **      where X is a constant value. The collation sequences of the
109881   **      comparison and select-list expressions must match those of the index.
109882   **
109883   **   3. All of those index columns for which the WHERE clause does not
109884   **      contain a "col=X" term are subject to a NOT NULL constraint.
109885   */
109886   for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
109887     if( pIdx->onError==OE_None ) continue;
109888     for(i=0; i<pIdx->nKeyCol; i++){
109889       i16 iCol = pIdx->aiColumn[i];
109890       if( 0==findTerm(pWC, iBase, iCol, ~(Bitmask)0, WO_EQ, pIdx) ){
109891         int iIdxCol = findIndexCol(pParse, pDistinct, iBase, pIdx, i);
109892         if( iIdxCol<0 || pTab->aCol[iCol].notNull==0 ){
109893           break;
109894         }
109895       }
109896     }
109897     if( i==pIdx->nKeyCol ){
109898       /* This index implies that the DISTINCT qualifier is redundant. */
109899       return 1;
109900     }
109901   }
109902 
109903   return 0;
109904 }
109905 
109906 
109907 /*
109908 ** Estimate the logarithm of the input value to base 2.
109909 */
109910 static LogEst estLog(LogEst N){
109911   LogEst x = sqlite3LogEst(N);
109912   return x>33 ? x - 33 : 0;
109913 }
109914 
109915 /*
109916 ** Two routines for printing the content of an sqlite3_index_info
109917 ** structure.  Used for testing and debugging only.  If neither
109918 ** SQLITE_TEST or SQLITE_DEBUG are defined, then these routines
109919 ** are no-ops.
109920 */
109921 #if !defined(SQLITE_OMIT_VIRTUALTABLE) && defined(WHERETRACE_ENABLED)
109922 static void TRACE_IDX_INPUTS(sqlite3_index_info *p){
109923   int i;
109924   if( !sqlite3WhereTrace ) return;
109925   for(i=0; i<p->nConstraint; i++){
109926     sqlite3DebugPrintf("  constraint[%d]: col=%d termid=%d op=%d usabled=%d\n",
109927        i,
109928        p->aConstraint[i].iColumn,
109929        p->aConstraint[i].iTermOffset,
109930        p->aConstraint[i].op,
109931        p->aConstraint[i].usable);
109932   }
109933   for(i=0; i<p->nOrderBy; i++){
109934     sqlite3DebugPrintf("  orderby[%d]: col=%d desc=%d\n",
109935        i,
109936        p->aOrderBy[i].iColumn,
109937        p->aOrderBy[i].desc);
109938   }
109939 }
109940 static void TRACE_IDX_OUTPUTS(sqlite3_index_info *p){
109941   int i;
109942   if( !sqlite3WhereTrace ) return;
109943   for(i=0; i<p->nConstraint; i++){
109944     sqlite3DebugPrintf("  usage[%d]: argvIdx=%d omit=%d\n",
109945        i,
109946        p->aConstraintUsage[i].argvIndex,
109947        p->aConstraintUsage[i].omit);
109948   }
109949   sqlite3DebugPrintf("  idxNum=%d\n", p->idxNum);
109950   sqlite3DebugPrintf("  idxStr=%s\n", p->idxStr);
109951   sqlite3DebugPrintf("  orderByConsumed=%d\n", p->orderByConsumed);
109952   sqlite3DebugPrintf("  estimatedCost=%g\n", p->estimatedCost);
109953   sqlite3DebugPrintf("  estimatedRows=%lld\n", p->estimatedRows);
109954 }
109955 #else
109956 #define TRACE_IDX_INPUTS(A)
109957 #define TRACE_IDX_OUTPUTS(A)
109958 #endif
109959 
109960 #ifndef SQLITE_OMIT_AUTOMATIC_INDEX
109961 /*
109962 ** Return TRUE if the WHERE clause term pTerm is of a form where it
109963 ** could be used with an index to access pSrc, assuming an appropriate
109964 ** index existed.
109965 */
109966 static int termCanDriveIndex(
109967   WhereTerm *pTerm,              /* WHERE clause term to check */
109968   struct SrcList_item *pSrc,     /* Table we are trying to access */
109969   Bitmask notReady               /* Tables in outer loops of the join */
109970 ){
109971   char aff;
109972   if( pTerm->leftCursor!=pSrc->iCursor ) return 0;
109973   if( (pTerm->eOperator & WO_EQ)==0 ) return 0;
109974   if( (pTerm->prereqRight & notReady)!=0 ) return 0;
109975   if( pTerm->u.leftColumn<0 ) return 0;
109976   aff = pSrc->pTab->aCol[pTerm->u.leftColumn].affinity;
109977   if( !sqlite3IndexAffinityOk(pTerm->pExpr, aff) ) return 0;
109978   return 1;
109979 }
109980 #endif
109981 
109982 
109983 #ifndef SQLITE_OMIT_AUTOMATIC_INDEX
109984 /*
109985 ** Generate code to construct the Index object for an automatic index
109986 ** and to set up the WhereLevel object pLevel so that the code generator
109987 ** makes use of the automatic index.
109988 */
109989 static void constructAutomaticIndex(
109990   Parse *pParse,              /* The parsing context */
109991   WhereClause *pWC,           /* The WHERE clause */
109992   struct SrcList_item *pSrc,  /* The FROM clause term to get the next index */
109993   Bitmask notReady,           /* Mask of cursors that are not available */
109994   WhereLevel *pLevel          /* Write new index here */
109995 ){
109996   int nKeyCol;                /* Number of columns in the constructed index */
109997   WhereTerm *pTerm;           /* A single term of the WHERE clause */
109998   WhereTerm *pWCEnd;          /* End of pWC->a[] */
109999   Index *pIdx;                /* Object describing the transient index */
110000   Vdbe *v;                    /* Prepared statement under construction */
110001   int addrInit;               /* Address of the initialization bypass jump */
110002   Table *pTable;              /* The table being indexed */
110003   int addrTop;                /* Top of the index fill loop */
110004   int regRecord;              /* Register holding an index record */
110005   int n;                      /* Column counter */
110006   int i;                      /* Loop counter */
110007   int mxBitCol;               /* Maximum column in pSrc->colUsed */
110008   CollSeq *pColl;             /* Collating sequence to on a column */
110009   WhereLoop *pLoop;           /* The Loop object */
110010   char *zNotUsed;             /* Extra space on the end of pIdx */
110011   Bitmask idxCols;            /* Bitmap of columns used for indexing */
110012   Bitmask extraCols;          /* Bitmap of additional columns */
110013   u8 sentWarning = 0;         /* True if a warnning has been issued */
110014 
110015   /* Generate code to skip over the creation and initialization of the
110016   ** transient index on 2nd and subsequent iterations of the loop. */
110017   v = pParse->pVdbe;
110018   assert( v!=0 );
110019   addrInit = sqlite3CodeOnce(pParse);
110020 
110021   /* Count the number of columns that will be added to the index
110022   ** and used to match WHERE clause constraints */
110023   nKeyCol = 0;
110024   pTable = pSrc->pTab;
110025   pWCEnd = &pWC->a[pWC->nTerm];
110026   pLoop = pLevel->pWLoop;
110027   idxCols = 0;
110028   for(pTerm=pWC->a; pTerm<pWCEnd; pTerm++){
110029     if( termCanDriveIndex(pTerm, pSrc, notReady) ){
110030       int iCol = pTerm->u.leftColumn;
110031       Bitmask cMask = iCol>=BMS ? MASKBIT(BMS-1) : MASKBIT(iCol);
110032       testcase( iCol==BMS );
110033       testcase( iCol==BMS-1 );
110034       if( !sentWarning ){
110035         sqlite3_log(SQLITE_WARNING_AUTOINDEX,
110036             "automatic index on %s(%s)", pTable->zName,
110037             pTable->aCol[iCol].zName);
110038         sentWarning = 1;
110039       }
110040       if( (idxCols & cMask)==0 ){
110041         if( whereLoopResize(pParse->db, pLoop, nKeyCol+1) ) return;
110042         pLoop->aLTerm[nKeyCol++] = pTerm;
110043         idxCols |= cMask;
110044       }
110045     }
110046   }
110047   assert( nKeyCol>0 );
110048   pLoop->u.btree.nEq = pLoop->nLTerm = nKeyCol;
110049   pLoop->wsFlags = WHERE_COLUMN_EQ | WHERE_IDX_ONLY | WHERE_INDEXED
110050                      | WHERE_AUTO_INDEX;
110051 
110052   /* Count the number of additional columns needed to create a
110053   ** covering index.  A "covering index" is an index that contains all
110054   ** columns that are needed by the query.  With a covering index, the
110055   ** original table never needs to be accessed.  Automatic indices must
110056   ** be a covering index because the index will not be updated if the
110057   ** original table changes and the index and table cannot both be used
110058   ** if they go out of sync.
110059   */
110060   extraCols = pSrc->colUsed & (~idxCols | MASKBIT(BMS-1));
110061   mxBitCol = (pTable->nCol >= BMS-1) ? BMS-1 : pTable->nCol;
110062   testcase( pTable->nCol==BMS-1 );
110063   testcase( pTable->nCol==BMS-2 );
110064   for(i=0; i<mxBitCol; i++){
110065     if( extraCols & MASKBIT(i) ) nKeyCol++;
110066   }
110067   if( pSrc->colUsed & MASKBIT(BMS-1) ){
110068     nKeyCol += pTable->nCol - BMS + 1;
110069   }
110070   pLoop->wsFlags |= WHERE_COLUMN_EQ | WHERE_IDX_ONLY;
110071 
110072   /* Construct the Index object to describe this index */
110073   pIdx = sqlite3AllocateIndexObject(pParse->db, nKeyCol+1, 0, &zNotUsed);
110074   if( pIdx==0 ) return;
110075   pLoop->u.btree.pIndex = pIdx;
110076   pIdx->zName = "auto-index";
110077   pIdx->pTable = pTable;
110078   n = 0;
110079   idxCols = 0;
110080   for(pTerm=pWC->a; pTerm<pWCEnd; pTerm++){
110081     if( termCanDriveIndex(pTerm, pSrc, notReady) ){
110082       int iCol = pTerm->u.leftColumn;
110083       Bitmask cMask = iCol>=BMS ? MASKBIT(BMS-1) : MASKBIT(iCol);
110084       testcase( iCol==BMS-1 );
110085       testcase( iCol==BMS );
110086       if( (idxCols & cMask)==0 ){
110087         Expr *pX = pTerm->pExpr;
110088         idxCols |= cMask;
110089         pIdx->aiColumn[n] = pTerm->u.leftColumn;
110090         pColl = sqlite3BinaryCompareCollSeq(pParse, pX->pLeft, pX->pRight);
110091         pIdx->azColl[n] = ALWAYS(pColl) ? pColl->zName : "BINARY";
110092         n++;
110093       }
110094     }
110095   }
110096   assert( (u32)n==pLoop->u.btree.nEq );
110097 
110098   /* Add additional columns needed to make the automatic index into
110099   ** a covering index */
110100   for(i=0; i<mxBitCol; i++){
110101     if( extraCols & MASKBIT(i) ){
110102       pIdx->aiColumn[n] = i;
110103       pIdx->azColl[n] = "BINARY";
110104       n++;
110105     }
110106   }
110107   if( pSrc->colUsed & MASKBIT(BMS-1) ){
110108     for(i=BMS-1; i<pTable->nCol; i++){
110109       pIdx->aiColumn[n] = i;
110110       pIdx->azColl[n] = "BINARY";
110111       n++;
110112     }
110113   }
110114   assert( n==nKeyCol );
110115   pIdx->aiColumn[n] = -1;
110116   pIdx->azColl[n] = "BINARY";
110117 
110118   /* Create the automatic index */
110119   assert( pLevel->iIdxCur>=0 );
110120   pLevel->iIdxCur = pParse->nTab++;
110121   sqlite3VdbeAddOp2(v, OP_OpenAutoindex, pLevel->iIdxCur, nKeyCol+1);
110122   sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
110123   VdbeComment((v, "for %s", pTable->zName));
110124 
110125   /* Fill the automatic index with content */
110126   addrTop = sqlite3VdbeAddOp1(v, OP_Rewind, pLevel->iTabCur);
110127   regRecord = sqlite3GetTempReg(pParse);
110128   sqlite3GenerateIndexKey(pParse, pIdx, pLevel->iTabCur, regRecord, 0, 0);
110129   sqlite3VdbeAddOp2(v, OP_IdxInsert, pLevel->iIdxCur, regRecord);
110130   sqlite3VdbeChangeP5(v, OPFLAG_USESEEKRESULT);
110131   sqlite3VdbeAddOp2(v, OP_Next, pLevel->iTabCur, addrTop+1);
110132   sqlite3VdbeChangeP5(v, SQLITE_STMTSTATUS_AUTOINDEX);
110133   sqlite3VdbeJumpHere(v, addrTop);
110134   sqlite3ReleaseTempReg(pParse, regRecord);
110135   
110136   /* Jump here when skipping the initialization */
110137   sqlite3VdbeJumpHere(v, addrInit);
110138 }
110139 #endif /* SQLITE_OMIT_AUTOMATIC_INDEX */
110140 
110141 #ifndef SQLITE_OMIT_VIRTUALTABLE
110142 /*
110143 ** Allocate and populate an sqlite3_index_info structure. It is the 
110144 ** responsibility of the caller to eventually release the structure
110145 ** by passing the pointer returned by this function to sqlite3_free().
110146 */
110147 static sqlite3_index_info *allocateIndexInfo(
110148   Parse *pParse,
110149   WhereClause *pWC,
110150   struct SrcList_item *pSrc,
110151   ExprList *pOrderBy
110152 ){
110153   int i, j;
110154   int nTerm;
110155   struct sqlite3_index_constraint *pIdxCons;
110156   struct sqlite3_index_orderby *pIdxOrderBy;
110157   struct sqlite3_index_constraint_usage *pUsage;
110158   WhereTerm *pTerm;
110159   int nOrderBy;
110160   sqlite3_index_info *pIdxInfo;
110161 
110162   /* Count the number of possible WHERE clause constraints referring
110163   ** to this virtual table */
110164   for(i=nTerm=0, pTerm=pWC->a; i<pWC->nTerm; i++, pTerm++){
110165     if( pTerm->leftCursor != pSrc->iCursor ) continue;
110166     assert( IsPowerOfTwo(pTerm->eOperator & ~WO_EQUIV) );
110167     testcase( pTerm->eOperator & WO_IN );
110168     testcase( pTerm->eOperator & WO_ISNULL );
110169     if( pTerm->eOperator & (WO_ISNULL) ) continue;
110170     if( pTerm->wtFlags & TERM_VNULL ) continue;
110171     nTerm++;
110172   }
110173 
110174   /* If the ORDER BY clause contains only columns in the current 
110175   ** virtual table then allocate space for the aOrderBy part of
110176   ** the sqlite3_index_info structure.
110177   */
110178   nOrderBy = 0;
110179   if( pOrderBy ){
110180     int n = pOrderBy->nExpr;
110181     for(i=0; i<n; i++){
110182       Expr *pExpr = pOrderBy->a[i].pExpr;
110183       if( pExpr->op!=TK_COLUMN || pExpr->iTable!=pSrc->iCursor ) break;
110184     }
110185     if( i==n){
110186       nOrderBy = n;
110187     }
110188   }
110189 
110190   /* Allocate the sqlite3_index_info structure
110191   */
110192   pIdxInfo = sqlite3DbMallocZero(pParse->db, sizeof(*pIdxInfo)
110193                            + (sizeof(*pIdxCons) + sizeof(*pUsage))*nTerm
110194                            + sizeof(*pIdxOrderBy)*nOrderBy );
110195   if( pIdxInfo==0 ){
110196     sqlite3ErrorMsg(pParse, "out of memory");
110197     return 0;
110198   }
110199 
110200   /* Initialize the structure.  The sqlite3_index_info structure contains
110201   ** many fields that are declared "const" to prevent xBestIndex from
110202   ** changing them.  We have to do some funky casting in order to
110203   ** initialize those fields.
110204   */
110205   pIdxCons = (struct sqlite3_index_constraint*)&pIdxInfo[1];
110206   pIdxOrderBy = (struct sqlite3_index_orderby*)&pIdxCons[nTerm];
110207   pUsage = (struct sqlite3_index_constraint_usage*)&pIdxOrderBy[nOrderBy];
110208   *(int*)&pIdxInfo->nConstraint = nTerm;
110209   *(int*)&pIdxInfo->nOrderBy = nOrderBy;
110210   *(struct sqlite3_index_constraint**)&pIdxInfo->aConstraint = pIdxCons;
110211   *(struct sqlite3_index_orderby**)&pIdxInfo->aOrderBy = pIdxOrderBy;
110212   *(struct sqlite3_index_constraint_usage**)&pIdxInfo->aConstraintUsage =
110213                                                                    pUsage;
110214 
110215   for(i=j=0, pTerm=pWC->a; i<pWC->nTerm; i++, pTerm++){
110216     u8 op;
110217     if( pTerm->leftCursor != pSrc->iCursor ) continue;
110218     assert( IsPowerOfTwo(pTerm->eOperator & ~WO_EQUIV) );
110219     testcase( pTerm->eOperator & WO_IN );
110220     testcase( pTerm->eOperator & WO_ISNULL );
110221     if( pTerm->eOperator & (WO_ISNULL) ) continue;
110222     if( pTerm->wtFlags & TERM_VNULL ) continue;
110223     pIdxCons[j].iColumn = pTerm->u.leftColumn;
110224     pIdxCons[j].iTermOffset = i;
110225     op = (u8)pTerm->eOperator & WO_ALL;
110226     if( op==WO_IN ) op = WO_EQ;
110227     pIdxCons[j].op = op;
110228     /* The direct assignment in the previous line is possible only because
110229     ** the WO_ and SQLITE_INDEX_CONSTRAINT_ codes are identical.  The
110230     ** following asserts verify this fact. */
110231     assert( WO_EQ==SQLITE_INDEX_CONSTRAINT_EQ );
110232     assert( WO_LT==SQLITE_INDEX_CONSTRAINT_LT );
110233     assert( WO_LE==SQLITE_INDEX_CONSTRAINT_LE );
110234     assert( WO_GT==SQLITE_INDEX_CONSTRAINT_GT );
110235     assert( WO_GE==SQLITE_INDEX_CONSTRAINT_GE );
110236     assert( WO_MATCH==SQLITE_INDEX_CONSTRAINT_MATCH );
110237     assert( pTerm->eOperator & (WO_IN|WO_EQ|WO_LT|WO_LE|WO_GT|WO_GE|WO_MATCH) );
110238     j++;
110239   }
110240   for(i=0; i<nOrderBy; i++){
110241     Expr *pExpr = pOrderBy->a[i].pExpr;
110242     pIdxOrderBy[i].iColumn = pExpr->iColumn;
110243     pIdxOrderBy[i].desc = pOrderBy->a[i].sortOrder;
110244   }
110245 
110246   return pIdxInfo;
110247 }
110248 
110249 /*
110250 ** The table object reference passed as the second argument to this function
110251 ** must represent a virtual table. This function invokes the xBestIndex()
110252 ** method of the virtual table with the sqlite3_index_info object that
110253 ** comes in as the 3rd argument to this function.
110254 **
110255 ** If an error occurs, pParse is populated with an error message and a
110256 ** non-zero value is returned. Otherwise, 0 is returned and the output
110257 ** part of the sqlite3_index_info structure is left populated.
110258 **
110259 ** Whether or not an error is returned, it is the responsibility of the
110260 ** caller to eventually free p->idxStr if p->needToFreeIdxStr indicates
110261 ** that this is required.
110262 */
110263 static int vtabBestIndex(Parse *pParse, Table *pTab, sqlite3_index_info *p){
110264   sqlite3_vtab *pVtab = sqlite3GetVTable(pParse->db, pTab)->pVtab;
110265   int i;
110266   int rc;
110267 
110268   TRACE_IDX_INPUTS(p);
110269   rc = pVtab->pModule->xBestIndex(pVtab, p);
110270   TRACE_IDX_OUTPUTS(p);
110271 
110272   if( rc!=SQLITE_OK ){
110273     if( rc==SQLITE_NOMEM ){
110274       pParse->db->mallocFailed = 1;
110275     }else if( !pVtab->zErrMsg ){
110276       sqlite3ErrorMsg(pParse, "%s", sqlite3ErrStr(rc));
110277     }else{
110278       sqlite3ErrorMsg(pParse, "%s", pVtab->zErrMsg);
110279     }
110280   }
110281   sqlite3_free(pVtab->zErrMsg);
110282   pVtab->zErrMsg = 0;
110283 
110284   for(i=0; i<p->nConstraint; i++){
110285     if( !p->aConstraint[i].usable && p->aConstraintUsage[i].argvIndex>0 ){
110286       sqlite3ErrorMsg(pParse, 
110287           "table %s: xBestIndex returned an invalid plan", pTab->zName);
110288     }
110289   }
110290 
110291   return pParse->nErr;
110292 }
110293 #endif /* !defined(SQLITE_OMIT_VIRTUALTABLE) */
110294 
110295 
110296 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
110297 /*
110298 ** Estimate the location of a particular key among all keys in an
110299 ** index.  Store the results in aStat as follows:
110300 **
110301 **    aStat[0]      Est. number of rows less than pVal
110302 **    aStat[1]      Est. number of rows equal to pVal
110303 **
110304 ** Return SQLITE_OK on success.
110305 */
110306 static void whereKeyStats(
110307   Parse *pParse,              /* Database connection */
110308   Index *pIdx,                /* Index to consider domain of */
110309   UnpackedRecord *pRec,       /* Vector of values to consider */
110310   int roundUp,                /* Round up if true.  Round down if false */
110311   tRowcnt *aStat              /* OUT: stats written here */
110312 ){
110313   IndexSample *aSample = pIdx->aSample;
110314   int iCol;                   /* Index of required stats in anEq[] etc. */
110315   int iMin = 0;               /* Smallest sample not yet tested */
110316   int i = pIdx->nSample;      /* Smallest sample larger than or equal to pRec */
110317   int iTest;                  /* Next sample to test */
110318   int res;                    /* Result of comparison operation */
110319 
110320 #ifndef SQLITE_DEBUG
110321   UNUSED_PARAMETER( pParse );
110322 #endif
110323   assert( pRec!=0 );
110324   iCol = pRec->nField - 1;
110325   assert( pIdx->nSample>0 );
110326   assert( pRec->nField>0 && iCol<pIdx->nSampleCol );
110327   do{
110328     iTest = (iMin+i)/2;
110329     res = sqlite3VdbeRecordCompare(aSample[iTest].n, aSample[iTest].p, pRec);
110330     if( res<0 ){
110331       iMin = iTest+1;
110332     }else{
110333       i = iTest;
110334     }
110335   }while( res && iMin<i );
110336 
110337 #ifdef SQLITE_DEBUG
110338   /* The following assert statements check that the binary search code
110339   ** above found the right answer. This block serves no purpose other
110340   ** than to invoke the asserts.  */
110341   if( res==0 ){
110342     /* If (res==0) is true, then sample $i must be equal to pRec */
110343     assert( i<pIdx->nSample );
110344     assert( 0==sqlite3VdbeRecordCompare(aSample[i].n, aSample[i].p, pRec)
110345          || pParse->db->mallocFailed );
110346   }else{
110347     /* Otherwise, pRec must be smaller than sample $i and larger than
110348     ** sample ($i-1).  */
110349     assert( i==pIdx->nSample 
110350          || sqlite3VdbeRecordCompare(aSample[i].n, aSample[i].p, pRec)>0
110351          || pParse->db->mallocFailed );
110352     assert( i==0
110353          || sqlite3VdbeRecordCompare(aSample[i-1].n, aSample[i-1].p, pRec)<0
110354          || pParse->db->mallocFailed );
110355   }
110356 #endif /* ifdef SQLITE_DEBUG */
110357 
110358   /* At this point, aSample[i] is the first sample that is greater than
110359   ** or equal to pVal.  Or if i==pIdx->nSample, then all samples are less
110360   ** than pVal.  If aSample[i]==pVal, then res==0.
110361   */
110362   if( res==0 ){
110363     aStat[0] = aSample[i].anLt[iCol];
110364     aStat[1] = aSample[i].anEq[iCol];
110365   }else{
110366     tRowcnt iLower, iUpper, iGap;
110367     if( i==0 ){
110368       iLower = 0;
110369       iUpper = aSample[0].anLt[iCol];
110370     }else{
110371       iUpper = i>=pIdx->nSample ? pIdx->aiRowEst[0] : aSample[i].anLt[iCol];
110372       iLower = aSample[i-1].anEq[iCol] + aSample[i-1].anLt[iCol];
110373     }
110374     aStat[1] = (pIdx->nKeyCol>iCol ? pIdx->aAvgEq[iCol] : 1);
110375     if( iLower>=iUpper ){
110376       iGap = 0;
110377     }else{
110378       iGap = iUpper - iLower;
110379     }
110380     if( roundUp ){
110381       iGap = (iGap*2)/3;
110382     }else{
110383       iGap = iGap/3;
110384     }
110385     aStat[0] = iLower + iGap;
110386   }
110387 }
110388 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
110389 
110390 /*
110391 ** This function is used to estimate the number of rows that will be visited
110392 ** by scanning an index for a range of values. The range may have an upper
110393 ** bound, a lower bound, or both. The WHERE clause terms that set the upper
110394 ** and lower bounds are represented by pLower and pUpper respectively. For
110395 ** example, assuming that index p is on t1(a):
110396 **
110397 **   ... FROM t1 WHERE a > ? AND a < ? ...
110398 **                    |_____|   |_____|
110399 **                       |         |
110400 **                     pLower    pUpper
110401 **
110402 ** If either of the upper or lower bound is not present, then NULL is passed in
110403 ** place of the corresponding WhereTerm.
110404 **
110405 ** The value in (pBuilder->pNew->u.btree.nEq) is the index of the index
110406 ** column subject to the range constraint. Or, equivalently, the number of
110407 ** equality constraints optimized by the proposed index scan. For example,
110408 ** assuming index p is on t1(a, b), and the SQL query is:
110409 **
110410 **   ... FROM t1 WHERE a = ? AND b > ? AND b < ? ...
110411 **
110412 ** then nEq is set to 1 (as the range restricted column, b, is the second 
110413 ** left-most column of the index). Or, if the query is:
110414 **
110415 **   ... FROM t1 WHERE a > ? AND a < ? ...
110416 **
110417 ** then nEq is set to 0.
110418 **
110419 ** When this function is called, *pnOut is set to the sqlite3LogEst() of the
110420 ** number of rows that the index scan is expected to visit without 
110421 ** considering the range constraints. If nEq is 0, this is the number of 
110422 ** rows in the index. Assuming no error occurs, *pnOut is adjusted (reduced)
110423 ** to account for the range contraints pLower and pUpper.
110424 ** 
110425 ** In the absence of sqlite_stat4 ANALYZE data, or if such data cannot be
110426 ** used, each range inequality reduces the search space by a factor of 4. 
110427 ** Hence a pair of constraints (x>? AND x<?) reduces the expected number of
110428 ** rows visited by a factor of 16.
110429 */
110430 static int whereRangeScanEst(
110431   Parse *pParse,       /* Parsing & code generating context */
110432   WhereLoopBuilder *pBuilder,
110433   WhereTerm *pLower,   /* Lower bound on the range. ex: "x>123" Might be NULL */
110434   WhereTerm *pUpper,   /* Upper bound on the range. ex: "x<455" Might be NULL */
110435   WhereLoop *pLoop     /* Modify the .nOut and maybe .rRun fields */
110436 ){
110437   int rc = SQLITE_OK;
110438   int nOut = pLoop->nOut;
110439   LogEst nNew;
110440 
110441 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
110442   Index *p = pLoop->u.btree.pIndex;
110443   int nEq = pLoop->u.btree.nEq;
110444 
110445   if( p->nSample>0
110446    && nEq==pBuilder->nRecValid
110447    && nEq<p->nSampleCol
110448    && OptimizationEnabled(pParse->db, SQLITE_Stat3) 
110449   ){
110450     UnpackedRecord *pRec = pBuilder->pRec;
110451     tRowcnt a[2];
110452     u8 aff;
110453 
110454     /* Variable iLower will be set to the estimate of the number of rows in 
110455     ** the index that are less than the lower bound of the range query. The
110456     ** lower bound being the concatenation of $P and $L, where $P is the
110457     ** key-prefix formed by the nEq values matched against the nEq left-most
110458     ** columns of the index, and $L is the value in pLower.
110459     **
110460     ** Or, if pLower is NULL or $L cannot be extracted from it (because it
110461     ** is not a simple variable or literal value), the lower bound of the
110462     ** range is $P. Due to a quirk in the way whereKeyStats() works, even
110463     ** if $L is available, whereKeyStats() is called for both ($P) and 
110464     ** ($P:$L) and the larger of the two returned values used.
110465     **
110466     ** Similarly, iUpper is to be set to the estimate of the number of rows
110467     ** less than the upper bound of the range query. Where the upper bound
110468     ** is either ($P) or ($P:$U). Again, even if $U is available, both values
110469     ** of iUpper are requested of whereKeyStats() and the smaller used.
110470     */
110471     tRowcnt iLower;
110472     tRowcnt iUpper;
110473 
110474     if( nEq==p->nKeyCol ){
110475       aff = SQLITE_AFF_INTEGER;
110476     }else{
110477       aff = p->pTable->aCol[p->aiColumn[nEq]].affinity;
110478     }
110479     /* Determine iLower and iUpper using ($P) only. */
110480     if( nEq==0 ){
110481       iLower = 0;
110482       iUpper = p->aiRowEst[0];
110483     }else{
110484       /* Note: this call could be optimized away - since the same values must 
110485       ** have been requested when testing key $P in whereEqualScanEst().  */
110486       whereKeyStats(pParse, p, pRec, 0, a);
110487       iLower = a[0];
110488       iUpper = a[0] + a[1];
110489     }
110490 
110491     /* If possible, improve on the iLower estimate using ($P:$L). */
110492     if( pLower ){
110493       int bOk;                    /* True if value is extracted from pExpr */
110494       Expr *pExpr = pLower->pExpr->pRight;
110495       assert( (pLower->eOperator & (WO_GT|WO_GE))!=0 );
110496       rc = sqlite3Stat4ProbeSetValue(pParse, p, &pRec, pExpr, aff, nEq, &bOk);
110497       if( rc==SQLITE_OK && bOk ){
110498         tRowcnt iNew;
110499         whereKeyStats(pParse, p, pRec, 0, a);
110500         iNew = a[0] + ((pLower->eOperator & WO_GT) ? a[1] : 0);
110501         if( iNew>iLower ) iLower = iNew;
110502         nOut--;
110503       }
110504     }
110505 
110506     /* If possible, improve on the iUpper estimate using ($P:$U). */
110507     if( pUpper ){
110508       int bOk;                    /* True if value is extracted from pExpr */
110509       Expr *pExpr = pUpper->pExpr->pRight;
110510       assert( (pUpper->eOperator & (WO_LT|WO_LE))!=0 );
110511       rc = sqlite3Stat4ProbeSetValue(pParse, p, &pRec, pExpr, aff, nEq, &bOk);
110512       if( rc==SQLITE_OK && bOk ){
110513         tRowcnt iNew;
110514         whereKeyStats(pParse, p, pRec, 1, a);
110515         iNew = a[0] + ((pUpper->eOperator & WO_LE) ? a[1] : 0);
110516         if( iNew<iUpper ) iUpper = iNew;
110517         nOut--;
110518       }
110519     }
110520 
110521     pBuilder->pRec = pRec;
110522     if( rc==SQLITE_OK ){
110523       if( iUpper>iLower ){
110524         nNew = sqlite3LogEst(iUpper - iLower);
110525       }else{
110526         nNew = 10;        assert( 10==sqlite3LogEst(2) );
110527       }
110528       if( nNew<nOut ){
110529         nOut = nNew;
110530       }
110531       pLoop->nOut = (LogEst)nOut;
110532       WHERETRACE(0x10, ("range scan regions: %u..%u  est=%d\n",
110533                          (u32)iLower, (u32)iUpper, nOut));
110534       return SQLITE_OK;
110535     }
110536   }
110537 #else
110538   UNUSED_PARAMETER(pParse);
110539   UNUSED_PARAMETER(pBuilder);
110540 #endif
110541   assert( pLower || pUpper );
110542   /* TUNING:  Each inequality constraint reduces the search space 4-fold.
110543   ** A BETWEEN operator, therefore, reduces the search space 16-fold */
110544   nNew = nOut;
110545   if( pLower && (pLower->wtFlags & TERM_VNULL)==0 ){
110546     nNew -= 20;        assert( 20==sqlite3LogEst(4) );
110547     nOut--;
110548   }
110549   if( pUpper ){
110550     nNew -= 20;        assert( 20==sqlite3LogEst(4) );
110551     nOut--;
110552   }
110553   if( nNew<10 ) nNew = 10;
110554   if( nNew<nOut ) nOut = nNew;
110555   pLoop->nOut = (LogEst)nOut;
110556   return rc;
110557 }
110558 
110559 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
110560 /*
110561 ** Estimate the number of rows that will be returned based on
110562 ** an equality constraint x=VALUE and where that VALUE occurs in
110563 ** the histogram data.  This only works when x is the left-most
110564 ** column of an index and sqlite_stat3 histogram data is available
110565 ** for that index.  When pExpr==NULL that means the constraint is
110566 ** "x IS NULL" instead of "x=VALUE".
110567 **
110568 ** Write the estimated row count into *pnRow and return SQLITE_OK. 
110569 ** If unable to make an estimate, leave *pnRow unchanged and return
110570 ** non-zero.
110571 **
110572 ** This routine can fail if it is unable to load a collating sequence
110573 ** required for string comparison, or if unable to allocate memory
110574 ** for a UTF conversion required for comparison.  The error is stored
110575 ** in the pParse structure.
110576 */
110577 static int whereEqualScanEst(
110578   Parse *pParse,       /* Parsing & code generating context */
110579   WhereLoopBuilder *pBuilder,
110580   Expr *pExpr,         /* Expression for VALUE in the x=VALUE constraint */
110581   tRowcnt *pnRow       /* Write the revised row estimate here */
110582 ){
110583   Index *p = pBuilder->pNew->u.btree.pIndex;
110584   int nEq = pBuilder->pNew->u.btree.nEq;
110585   UnpackedRecord *pRec = pBuilder->pRec;
110586   u8 aff;                   /* Column affinity */
110587   int rc;                   /* Subfunction return code */
110588   tRowcnt a[2];             /* Statistics */
110589   int bOk;
110590 
110591   assert( nEq>=1 );
110592   assert( nEq<=(p->nKeyCol+1) );
110593   assert( p->aSample!=0 );
110594   assert( p->nSample>0 );
110595   assert( pBuilder->nRecValid<nEq );
110596 
110597   /* If values are not available for all fields of the index to the left
110598   ** of this one, no estimate can be made. Return SQLITE_NOTFOUND. */
110599   if( pBuilder->nRecValid<(nEq-1) ){
110600     return SQLITE_NOTFOUND;
110601   }
110602 
110603   /* This is an optimization only. The call to sqlite3Stat4ProbeSetValue()
110604   ** below would return the same value.  */
110605   if( nEq>p->nKeyCol ){
110606     *pnRow = 1;
110607     return SQLITE_OK;
110608   }
110609 
110610   aff = p->pTable->aCol[p->aiColumn[nEq-1]].affinity;
110611   rc = sqlite3Stat4ProbeSetValue(pParse, p, &pRec, pExpr, aff, nEq-1, &bOk);
110612   pBuilder->pRec = pRec;
110613   if( rc!=SQLITE_OK ) return rc;
110614   if( bOk==0 ) return SQLITE_NOTFOUND;
110615   pBuilder->nRecValid = nEq;
110616 
110617   whereKeyStats(pParse, p, pRec, 0, a);
110618   WHERETRACE(0x10,("equality scan regions: %d\n", (int)a[1]));
110619   *pnRow = a[1];
110620   
110621   return rc;
110622 }
110623 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
110624 
110625 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
110626 /*
110627 ** Estimate the number of rows that will be returned based on
110628 ** an IN constraint where the right-hand side of the IN operator
110629 ** is a list of values.  Example:
110630 **
110631 **        WHERE x IN (1,2,3,4)
110632 **
110633 ** Write the estimated row count into *pnRow and return SQLITE_OK. 
110634 ** If unable to make an estimate, leave *pnRow unchanged and return
110635 ** non-zero.
110636 **
110637 ** This routine can fail if it is unable to load a collating sequence
110638 ** required for string comparison, or if unable to allocate memory
110639 ** for a UTF conversion required for comparison.  The error is stored
110640 ** in the pParse structure.
110641 */
110642 static int whereInScanEst(
110643   Parse *pParse,       /* Parsing & code generating context */
110644   WhereLoopBuilder *pBuilder,
110645   ExprList *pList,     /* The value list on the RHS of "x IN (v1,v2,v3,...)" */
110646   tRowcnt *pnRow       /* Write the revised row estimate here */
110647 ){
110648   Index *p = pBuilder->pNew->u.btree.pIndex;
110649   int nRecValid = pBuilder->nRecValid;
110650   int rc = SQLITE_OK;     /* Subfunction return code */
110651   tRowcnt nEst;           /* Number of rows for a single term */
110652   tRowcnt nRowEst = 0;    /* New estimate of the number of rows */
110653   int i;                  /* Loop counter */
110654 
110655   assert( p->aSample!=0 );
110656   for(i=0; rc==SQLITE_OK && i<pList->nExpr; i++){
110657     nEst = p->aiRowEst[0];
110658     rc = whereEqualScanEst(pParse, pBuilder, pList->a[i].pExpr, &nEst);
110659     nRowEst += nEst;
110660     pBuilder->nRecValid = nRecValid;
110661   }
110662 
110663   if( rc==SQLITE_OK ){
110664     if( nRowEst > p->aiRowEst[0] ) nRowEst = p->aiRowEst[0];
110665     *pnRow = nRowEst;
110666     WHERETRACE(0x10,("IN row estimate: est=%g\n", nRowEst));
110667   }
110668   assert( pBuilder->nRecValid==nRecValid );
110669   return rc;
110670 }
110671 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
110672 
110673 /*
110674 ** Disable a term in the WHERE clause.  Except, do not disable the term
110675 ** if it controls a LEFT OUTER JOIN and it did not originate in the ON
110676 ** or USING clause of that join.
110677 **
110678 ** Consider the term t2.z='ok' in the following queries:
110679 **
110680 **   (1)  SELECT * FROM t1 LEFT JOIN t2 ON t1.a=t2.x WHERE t2.z='ok'
110681 **   (2)  SELECT * FROM t1 LEFT JOIN t2 ON t1.a=t2.x AND t2.z='ok'
110682 **   (3)  SELECT * FROM t1, t2 WHERE t1.a=t2.x AND t2.z='ok'
110683 **
110684 ** The t2.z='ok' is disabled in the in (2) because it originates
110685 ** in the ON clause.  The term is disabled in (3) because it is not part
110686 ** of a LEFT OUTER JOIN.  In (1), the term is not disabled.
110687 **
110688 ** Disabling a term causes that term to not be tested in the inner loop
110689 ** of the join.  Disabling is an optimization.  When terms are satisfied
110690 ** by indices, we disable them to prevent redundant tests in the inner
110691 ** loop.  We would get the correct results if nothing were ever disabled,
110692 ** but joins might run a little slower.  The trick is to disable as much
110693 ** as we can without disabling too much.  If we disabled in (1), we'd get
110694 ** the wrong answer.  See ticket #813.
110695 */
110696 static void disableTerm(WhereLevel *pLevel, WhereTerm *pTerm){
110697   if( pTerm
110698       && (pTerm->wtFlags & TERM_CODED)==0
110699       && (pLevel->iLeftJoin==0 || ExprHasProperty(pTerm->pExpr, EP_FromJoin))
110700       && (pLevel->notReady & pTerm->prereqAll)==0
110701   ){
110702     pTerm->wtFlags |= TERM_CODED;
110703     if( pTerm->iParent>=0 ){
110704       WhereTerm *pOther = &pTerm->pWC->a[pTerm->iParent];
110705       if( (--pOther->nChild)==0 ){
110706         disableTerm(pLevel, pOther);
110707       }
110708     }
110709   }
110710 }
110711 
110712 /*
110713 ** Code an OP_Affinity opcode to apply the column affinity string zAff
110714 ** to the n registers starting at base. 
110715 **
110716 ** As an optimization, SQLITE_AFF_NONE entries (which are no-ops) at the
110717 ** beginning and end of zAff are ignored.  If all entries in zAff are
110718 ** SQLITE_AFF_NONE, then no code gets generated.
110719 **
110720 ** This routine makes its own copy of zAff so that the caller is free
110721 ** to modify zAff after this routine returns.
110722 */
110723 static void codeApplyAffinity(Parse *pParse, int base, int n, char *zAff){
110724   Vdbe *v = pParse->pVdbe;
110725   if( zAff==0 ){
110726     assert( pParse->db->mallocFailed );
110727     return;
110728   }
110729   assert( v!=0 );
110730 
110731   /* Adjust base and n to skip over SQLITE_AFF_NONE entries at the beginning
110732   ** and end of the affinity string.
110733   */
110734   while( n>0 && zAff[0]==SQLITE_AFF_NONE ){
110735     n--;
110736     base++;
110737     zAff++;
110738   }
110739   while( n>1 && zAff[n-1]==SQLITE_AFF_NONE ){
110740     n--;
110741   }
110742 
110743   /* Code the OP_Affinity opcode if there is anything left to do. */
110744   if( n>0 ){
110745     sqlite3VdbeAddOp2(v, OP_Affinity, base, n);
110746     sqlite3VdbeChangeP4(v, -1, zAff, n);
110747     sqlite3ExprCacheAffinityChange(pParse, base, n);
110748   }
110749 }
110750 
110751 
110752 /*
110753 ** Generate code for a single equality term of the WHERE clause.  An equality
110754 ** term can be either X=expr or X IN (...).   pTerm is the term to be 
110755 ** coded.
110756 **
110757 ** The current value for the constraint is left in register iReg.
110758 **
110759 ** For a constraint of the form X=expr, the expression is evaluated and its
110760 ** result is left on the stack.  For constraints of the form X IN (...)
110761 ** this routine sets up a loop that will iterate over all values of X.
110762 */
110763 static int codeEqualityTerm(
110764   Parse *pParse,      /* The parsing context */
110765   WhereTerm *pTerm,   /* The term of the WHERE clause to be coded */
110766   WhereLevel *pLevel, /* The level of the FROM clause we are working on */
110767   int iEq,            /* Index of the equality term within this level */
110768   int bRev,           /* True for reverse-order IN operations */
110769   int iTarget         /* Attempt to leave results in this register */
110770 ){
110771   Expr *pX = pTerm->pExpr;
110772   Vdbe *v = pParse->pVdbe;
110773   int iReg;                  /* Register holding results */
110774 
110775   assert( iTarget>0 );
110776   if( pX->op==TK_EQ ){
110777     iReg = sqlite3ExprCodeTarget(pParse, pX->pRight, iTarget);
110778   }else if( pX->op==TK_ISNULL ){
110779     iReg = iTarget;
110780     sqlite3VdbeAddOp2(v, OP_Null, 0, iReg);
110781 #ifndef SQLITE_OMIT_SUBQUERY
110782   }else{
110783     int eType;
110784     int iTab;
110785     struct InLoop *pIn;
110786     WhereLoop *pLoop = pLevel->pWLoop;
110787 
110788     if( (pLoop->wsFlags & WHERE_VIRTUALTABLE)==0
110789       && pLoop->u.btree.pIndex!=0
110790       && pLoop->u.btree.pIndex->aSortOrder[iEq]
110791     ){
110792       testcase( iEq==0 );
110793       testcase( bRev );
110794       bRev = !bRev;
110795     }
110796     assert( pX->op==TK_IN );
110797     iReg = iTarget;
110798     eType = sqlite3FindInIndex(pParse, pX, 0);
110799     if( eType==IN_INDEX_INDEX_DESC ){
110800       testcase( bRev );
110801       bRev = !bRev;
110802     }
110803     iTab = pX->iTable;
110804     sqlite3VdbeAddOp2(v, bRev ? OP_Last : OP_Rewind, iTab, 0);
110805     assert( (pLoop->wsFlags & WHERE_MULTI_OR)==0 );
110806     pLoop->wsFlags |= WHERE_IN_ABLE;
110807     if( pLevel->u.in.nIn==0 ){
110808       pLevel->addrNxt = sqlite3VdbeMakeLabel(v);
110809     }
110810     pLevel->u.in.nIn++;
110811     pLevel->u.in.aInLoop =
110812        sqlite3DbReallocOrFree(pParse->db, pLevel->u.in.aInLoop,
110813                               sizeof(pLevel->u.in.aInLoop[0])*pLevel->u.in.nIn);
110814     pIn = pLevel->u.in.aInLoop;
110815     if( pIn ){
110816       pIn += pLevel->u.in.nIn - 1;
110817       pIn->iCur = iTab;
110818       if( eType==IN_INDEX_ROWID ){
110819         pIn->addrInTop = sqlite3VdbeAddOp2(v, OP_Rowid, iTab, iReg);
110820       }else{
110821         pIn->addrInTop = sqlite3VdbeAddOp3(v, OP_Column, iTab, 0, iReg);
110822       }
110823       pIn->eEndLoopOp = bRev ? OP_PrevIfOpen : OP_NextIfOpen;
110824       sqlite3VdbeAddOp1(v, OP_IsNull, iReg);
110825     }else{
110826       pLevel->u.in.nIn = 0;
110827     }
110828 #endif
110829   }
110830   disableTerm(pLevel, pTerm);
110831   return iReg;
110832 }
110833 
110834 /*
110835 ** Generate code that will evaluate all == and IN constraints for an
110836 ** index scan.
110837 **
110838 ** For example, consider table t1(a,b,c,d,e,f) with index i1(a,b,c).
110839 ** Suppose the WHERE clause is this:  a==5 AND b IN (1,2,3) AND c>5 AND c<10
110840 ** The index has as many as three equality constraints, but in this
110841 ** example, the third "c" value is an inequality.  So only two 
110842 ** constraints are coded.  This routine will generate code to evaluate
110843 ** a==5 and b IN (1,2,3).  The current values for a and b will be stored
110844 ** in consecutive registers and the index of the first register is returned.
110845 **
110846 ** In the example above nEq==2.  But this subroutine works for any value
110847 ** of nEq including 0.  If nEq==0, this routine is nearly a no-op.
110848 ** The only thing it does is allocate the pLevel->iMem memory cell and
110849 ** compute the affinity string.
110850 **
110851 ** The nExtraReg parameter is 0 or 1.  It is 0 if all WHERE clause constraints
110852 ** are == or IN and are covered by the nEq.  nExtraReg is 1 if there is
110853 ** an inequality constraint (such as the "c>=5 AND c<10" in the example) that
110854 ** occurs after the nEq quality constraints.
110855 **
110856 ** This routine allocates a range of nEq+nExtraReg memory cells and returns
110857 ** the index of the first memory cell in that range. The code that
110858 ** calls this routine will use that memory range to store keys for
110859 ** start and termination conditions of the loop.
110860 ** key value of the loop.  If one or more IN operators appear, then
110861 ** this routine allocates an additional nEq memory cells for internal
110862 ** use.
110863 **
110864 ** Before returning, *pzAff is set to point to a buffer containing a
110865 ** copy of the column affinity string of the index allocated using
110866 ** sqlite3DbMalloc(). Except, entries in the copy of the string associated
110867 ** with equality constraints that use NONE affinity are set to
110868 ** SQLITE_AFF_NONE. This is to deal with SQL such as the following:
110869 **
110870 **   CREATE TABLE t1(a TEXT PRIMARY KEY, b);
110871 **   SELECT ... FROM t1 AS t2, t1 WHERE t1.a = t2.b;
110872 **
110873 ** In the example above, the index on t1(a) has TEXT affinity. But since
110874 ** the right hand side of the equality constraint (t2.b) has NONE affinity,
110875 ** no conversion should be attempted before using a t2.b value as part of
110876 ** a key to search the index. Hence the first byte in the returned affinity
110877 ** string in this example would be set to SQLITE_AFF_NONE.
110878 */
110879 static int codeAllEqualityTerms(
110880   Parse *pParse,        /* Parsing context */
110881   WhereLevel *pLevel,   /* Which nested loop of the FROM we are coding */
110882   int bRev,             /* Reverse the order of IN operators */
110883   int nExtraReg,        /* Number of extra registers to allocate */
110884   char **pzAff          /* OUT: Set to point to affinity string */
110885 ){
110886   u16 nEq;                      /* The number of == or IN constraints to code */
110887   u16 nSkip;                    /* Number of left-most columns to skip */
110888   Vdbe *v = pParse->pVdbe;      /* The vm under construction */
110889   Index *pIdx;                  /* The index being used for this loop */
110890   WhereTerm *pTerm;             /* A single constraint term */
110891   WhereLoop *pLoop;             /* The WhereLoop object */
110892   int j;                        /* Loop counter */
110893   int regBase;                  /* Base register */
110894   int nReg;                     /* Number of registers to allocate */
110895   char *zAff;                   /* Affinity string to return */
110896 
110897   /* This module is only called on query plans that use an index. */
110898   pLoop = pLevel->pWLoop;
110899   assert( (pLoop->wsFlags & WHERE_VIRTUALTABLE)==0 );
110900   nEq = pLoop->u.btree.nEq;
110901   nSkip = pLoop->u.btree.nSkip;
110902   pIdx = pLoop->u.btree.pIndex;
110903   assert( pIdx!=0 );
110904 
110905   /* Figure out how many memory cells we will need then allocate them.
110906   */
110907   regBase = pParse->nMem + 1;
110908   nReg = pLoop->u.btree.nEq + nExtraReg;
110909   pParse->nMem += nReg;
110910 
110911   zAff = sqlite3DbStrDup(pParse->db, sqlite3IndexAffinityStr(v, pIdx));
110912   if( !zAff ){
110913     pParse->db->mallocFailed = 1;
110914   }
110915 
110916   if( nSkip ){
110917     int iIdxCur = pLevel->iIdxCur;
110918     sqlite3VdbeAddOp1(v, (bRev?OP_Last:OP_Rewind), iIdxCur);
110919     VdbeComment((v, "begin skip-scan on %s", pIdx->zName));
110920     j = sqlite3VdbeAddOp0(v, OP_Goto);
110921     pLevel->addrSkip = sqlite3VdbeAddOp4Int(v, (bRev?OP_SeekLt:OP_SeekGt),
110922                             iIdxCur, 0, regBase, nSkip);
110923     sqlite3VdbeJumpHere(v, j);
110924     for(j=0; j<nSkip; j++){
110925       sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, j, regBase+j);
110926       assert( pIdx->aiColumn[j]>=0 );
110927       VdbeComment((v, "%s", pIdx->pTable->aCol[pIdx->aiColumn[j]].zName));
110928     }
110929   }    
110930 
110931   /* Evaluate the equality constraints
110932   */
110933   assert( zAff==0 || (int)strlen(zAff)>=nEq );
110934   for(j=nSkip; j<nEq; j++){
110935     int r1;
110936     pTerm = pLoop->aLTerm[j];
110937     assert( pTerm!=0 );
110938     /* The following testcase is true for indices with redundant columns. 
110939     ** Ex: CREATE INDEX i1 ON t1(a,b,a); SELECT * FROM t1 WHERE a=0 AND b=0; */
110940     testcase( (pTerm->wtFlags & TERM_CODED)!=0 );
110941     testcase( pTerm->wtFlags & TERM_VIRTUAL );
110942     r1 = codeEqualityTerm(pParse, pTerm, pLevel, j, bRev, regBase+j);
110943     if( r1!=regBase+j ){
110944       if( nReg==1 ){
110945         sqlite3ReleaseTempReg(pParse, regBase);
110946         regBase = r1;
110947       }else{
110948         sqlite3VdbeAddOp2(v, OP_SCopy, r1, regBase+j);
110949       }
110950     }
110951     testcase( pTerm->eOperator & WO_ISNULL );
110952     testcase( pTerm->eOperator & WO_IN );
110953     if( (pTerm->eOperator & (WO_ISNULL|WO_IN))==0 ){
110954       Expr *pRight = pTerm->pExpr->pRight;
110955       sqlite3ExprCodeIsNullJump(v, pRight, regBase+j, pLevel->addrBrk);
110956       if( zAff ){
110957         if( sqlite3CompareAffinity(pRight, zAff[j])==SQLITE_AFF_NONE ){
110958           zAff[j] = SQLITE_AFF_NONE;
110959         }
110960         if( sqlite3ExprNeedsNoAffinityChange(pRight, zAff[j]) ){
110961           zAff[j] = SQLITE_AFF_NONE;
110962         }
110963       }
110964     }
110965   }
110966   *pzAff = zAff;
110967   return regBase;
110968 }
110969 
110970 #ifndef SQLITE_OMIT_EXPLAIN
110971 /*
110972 ** This routine is a helper for explainIndexRange() below
110973 **
110974 ** pStr holds the text of an expression that we are building up one term
110975 ** at a time.  This routine adds a new term to the end of the expression.
110976 ** Terms are separated by AND so add the "AND" text for second and subsequent
110977 ** terms only.
110978 */
110979 static void explainAppendTerm(
110980   StrAccum *pStr,             /* The text expression being built */
110981   int iTerm,                  /* Index of this term.  First is zero */
110982   const char *zColumn,        /* Name of the column */
110983   const char *zOp             /* Name of the operator */
110984 ){
110985   if( iTerm ) sqlite3StrAccumAppend(pStr, " AND ", 5);
110986   sqlite3StrAccumAppend(pStr, zColumn, -1);
110987   sqlite3StrAccumAppend(pStr, zOp, 1);
110988   sqlite3StrAccumAppend(pStr, "?", 1);
110989 }
110990 
110991 /*
110992 ** Argument pLevel describes a strategy for scanning table pTab. This 
110993 ** function returns a pointer to a string buffer containing a description
110994 ** of the subset of table rows scanned by the strategy in the form of an
110995 ** SQL expression. Or, if all rows are scanned, NULL is returned.
110996 **
110997 ** For example, if the query:
110998 **
110999 **   SELECT * FROM t1 WHERE a=1 AND b>2;
111000 **
111001 ** is run and there is an index on (a, b), then this function returns a
111002 ** string similar to:
111003 **
111004 **   "a=? AND b>?"
111005 **
111006 ** The returned pointer points to memory obtained from sqlite3DbMalloc().
111007 ** It is the responsibility of the caller to free the buffer when it is
111008 ** no longer required.
111009 */
111010 static char *explainIndexRange(sqlite3 *db, WhereLoop *pLoop, Table *pTab){
111011   Index *pIndex = pLoop->u.btree.pIndex;
111012   u16 nEq = pLoop->u.btree.nEq;
111013   u16 nSkip = pLoop->u.btree.nSkip;
111014   int i, j;
111015   Column *aCol = pTab->aCol;
111016   i16 *aiColumn = pIndex->aiColumn;
111017   StrAccum txt;
111018 
111019   if( nEq==0 && (pLoop->wsFlags & (WHERE_BTM_LIMIT|WHERE_TOP_LIMIT))==0 ){
111020     return 0;
111021   }
111022   sqlite3StrAccumInit(&txt, 0, 0, SQLITE_MAX_LENGTH);
111023   txt.db = db;
111024   sqlite3StrAccumAppend(&txt, " (", 2);
111025   for(i=0; i<nEq; i++){
111026     char *z = (i==pIndex->nKeyCol ) ? "rowid" : aCol[aiColumn[i]].zName;
111027     if( i>=nSkip ){
111028       explainAppendTerm(&txt, i, z, "=");
111029     }else{
111030       if( i ) sqlite3StrAccumAppend(&txt, " AND ", 5);
111031       sqlite3StrAccumAppend(&txt, "ANY(", 4);
111032       sqlite3StrAccumAppend(&txt, z, -1);
111033       sqlite3StrAccumAppend(&txt, ")", 1);
111034     }
111035   }
111036 
111037   j = i;
111038   if( pLoop->wsFlags&WHERE_BTM_LIMIT ){
111039     char *z = (j==pIndex->nKeyCol ) ? "rowid" : aCol[aiColumn[j]].zName;
111040     explainAppendTerm(&txt, i++, z, ">");
111041   }
111042   if( pLoop->wsFlags&WHERE_TOP_LIMIT ){
111043     char *z = (j==pIndex->nKeyCol ) ? "rowid" : aCol[aiColumn[j]].zName;
111044     explainAppendTerm(&txt, i, z, "<");
111045   }
111046   sqlite3StrAccumAppend(&txt, ")", 1);
111047   return sqlite3StrAccumFinish(&txt);
111048 }
111049 
111050 /*
111051 ** This function is a no-op unless currently processing an EXPLAIN QUERY PLAN
111052 ** command. If the query being compiled is an EXPLAIN QUERY PLAN, a single
111053 ** record is added to the output to describe the table scan strategy in 
111054 ** pLevel.
111055 */
111056 static void explainOneScan(
111057   Parse *pParse,                  /* Parse context */
111058   SrcList *pTabList,              /* Table list this loop refers to */
111059   WhereLevel *pLevel,             /* Scan to write OP_Explain opcode for */
111060   int iLevel,                     /* Value for "level" column of output */
111061   int iFrom,                      /* Value for "from" column of output */
111062   u16 wctrlFlags                  /* Flags passed to sqlite3WhereBegin() */
111063 ){
111064 #ifndef SQLITE_DEBUG
111065   if( pParse->explain==2 )
111066 #endif
111067   {
111068     struct SrcList_item *pItem = &pTabList->a[pLevel->iFrom];
111069     Vdbe *v = pParse->pVdbe;      /* VM being constructed */
111070     sqlite3 *db = pParse->db;     /* Database handle */
111071     char *zMsg;                   /* Text to add to EQP output */
111072     int iId = pParse->iSelectId;  /* Select id (left-most output column) */
111073     int isSearch;                 /* True for a SEARCH. False for SCAN. */
111074     WhereLoop *pLoop;             /* The controlling WhereLoop object */
111075     u32 flags;                    /* Flags that describe this loop */
111076 
111077     pLoop = pLevel->pWLoop;
111078     flags = pLoop->wsFlags;
111079     if( (flags&WHERE_MULTI_OR) || (wctrlFlags&WHERE_ONETABLE_ONLY) ) return;
111080 
111081     isSearch = (flags&(WHERE_BTM_LIMIT|WHERE_TOP_LIMIT))!=0
111082             || ((flags&WHERE_VIRTUALTABLE)==0 && (pLoop->u.btree.nEq>0))
111083             || (wctrlFlags&(WHERE_ORDERBY_MIN|WHERE_ORDERBY_MAX));
111084 
111085     zMsg = sqlite3MPrintf(db, "%s", isSearch?"SEARCH":"SCAN");
111086     if( pItem->pSelect ){
111087       zMsg = sqlite3MAppendf(db, zMsg, "%s SUBQUERY %d", zMsg,pItem->iSelectId);
111088     }else{
111089       zMsg = sqlite3MAppendf(db, zMsg, "%s TABLE %s", zMsg, pItem->zName);
111090     }
111091 
111092     if( pItem->zAlias ){
111093       zMsg = sqlite3MAppendf(db, zMsg, "%s AS %s", zMsg, pItem->zAlias);
111094     }
111095     if( (flags & (WHERE_IPK|WHERE_VIRTUALTABLE))==0
111096      && ALWAYS(pLoop->u.btree.pIndex!=0)
111097     ){
111098       char *zWhere = explainIndexRange(db, pLoop, pItem->pTab);
111099       zMsg = sqlite3MAppendf(db, zMsg,
111100                ((flags & WHERE_AUTO_INDEX) ? 
111101                    "%s USING AUTOMATIC %sINDEX%.0s%s" :
111102                    "%s USING %sINDEX %s%s"), 
111103                zMsg, ((flags & WHERE_IDX_ONLY) ? "COVERING " : ""),
111104                pLoop->u.btree.pIndex->zName, zWhere);
111105       sqlite3DbFree(db, zWhere);
111106     }else if( (flags & WHERE_IPK)!=0 && (flags & WHERE_CONSTRAINT)!=0 ){
111107       zMsg = sqlite3MAppendf(db, zMsg, "%s USING INTEGER PRIMARY KEY", zMsg);
111108 
111109       if( flags&(WHERE_COLUMN_EQ|WHERE_COLUMN_IN) ){
111110         zMsg = sqlite3MAppendf(db, zMsg, "%s (rowid=?)", zMsg);
111111       }else if( (flags&WHERE_BOTH_LIMIT)==WHERE_BOTH_LIMIT ){
111112         zMsg = sqlite3MAppendf(db, zMsg, "%s (rowid>? AND rowid<?)", zMsg);
111113       }else if( flags&WHERE_BTM_LIMIT ){
111114         zMsg = sqlite3MAppendf(db, zMsg, "%s (rowid>?)", zMsg);
111115       }else if( ALWAYS(flags&WHERE_TOP_LIMIT) ){
111116         zMsg = sqlite3MAppendf(db, zMsg, "%s (rowid<?)", zMsg);
111117       }
111118     }
111119 #ifndef SQLITE_OMIT_VIRTUALTABLE
111120     else if( (flags & WHERE_VIRTUALTABLE)!=0 ){
111121       zMsg = sqlite3MAppendf(db, zMsg, "%s VIRTUAL TABLE INDEX %d:%s", zMsg,
111122                   pLoop->u.vtab.idxNum, pLoop->u.vtab.idxStr);
111123     }
111124 #endif
111125     zMsg = sqlite3MAppendf(db, zMsg, "%s", zMsg);
111126     sqlite3VdbeAddOp4(v, OP_Explain, iId, iLevel, iFrom, zMsg, P4_DYNAMIC);
111127   }
111128 }
111129 #else
111130 # define explainOneScan(u,v,w,x,y,z)
111131 #endif /* SQLITE_OMIT_EXPLAIN */
111132 
111133 
111134 /*
111135 ** Generate code for the start of the iLevel-th loop in the WHERE clause
111136 ** implementation described by pWInfo.
111137 */
111138 static Bitmask codeOneLoopStart(
111139   WhereInfo *pWInfo,   /* Complete information about the WHERE clause */
111140   int iLevel,          /* Which level of pWInfo->a[] should be coded */
111141   Bitmask notReady     /* Which tables are currently available */
111142 ){
111143   int j, k;            /* Loop counters */
111144   int iCur;            /* The VDBE cursor for the table */
111145   int addrNxt;         /* Where to jump to continue with the next IN case */
111146   int omitTable;       /* True if we use the index only */
111147   int bRev;            /* True if we need to scan in reverse order */
111148   WhereLevel *pLevel;  /* The where level to be coded */
111149   WhereLoop *pLoop;    /* The WhereLoop object being coded */
111150   WhereClause *pWC;    /* Decomposition of the entire WHERE clause */
111151   WhereTerm *pTerm;               /* A WHERE clause term */
111152   Parse *pParse;                  /* Parsing context */
111153   sqlite3 *db;                    /* Database connection */
111154   Vdbe *v;                        /* The prepared stmt under constructions */
111155   struct SrcList_item *pTabItem;  /* FROM clause term being coded */
111156   int addrBrk;                    /* Jump here to break out of the loop */
111157   int addrCont;                   /* Jump here to continue with next cycle */
111158   int iRowidReg = 0;        /* Rowid is stored in this register, if not zero */
111159   int iReleaseReg = 0;      /* Temp register to free before returning */
111160 
111161   pParse = pWInfo->pParse;
111162   v = pParse->pVdbe;
111163   pWC = &pWInfo->sWC;
111164   db = pParse->db;
111165   pLevel = &pWInfo->a[iLevel];
111166   pLoop = pLevel->pWLoop;
111167   pTabItem = &pWInfo->pTabList->a[pLevel->iFrom];
111168   iCur = pTabItem->iCursor;
111169   pLevel->notReady = notReady & ~getMask(&pWInfo->sMaskSet, iCur);
111170   bRev = (pWInfo->revMask>>iLevel)&1;
111171   omitTable = (pLoop->wsFlags & WHERE_IDX_ONLY)!=0 
111172            && (pWInfo->wctrlFlags & WHERE_FORCE_TABLE)==0;
111173   VdbeModuleComment((v, "Begin WHERE-loop%d: %s",iLevel,pTabItem->pTab->zName));
111174 
111175   /* Create labels for the "break" and "continue" instructions
111176   ** for the current loop.  Jump to addrBrk to break out of a loop.
111177   ** Jump to cont to go immediately to the next iteration of the
111178   ** loop.
111179   **
111180   ** When there is an IN operator, we also have a "addrNxt" label that
111181   ** means to continue with the next IN value combination.  When
111182   ** there are no IN operators in the constraints, the "addrNxt" label
111183   ** is the same as "addrBrk".
111184   */
111185   addrBrk = pLevel->addrBrk = pLevel->addrNxt = sqlite3VdbeMakeLabel(v);
111186   addrCont = pLevel->addrCont = sqlite3VdbeMakeLabel(v);
111187 
111188   /* If this is the right table of a LEFT OUTER JOIN, allocate and
111189   ** initialize a memory cell that records if this table matches any
111190   ** row of the left table of the join.
111191   */
111192   if( pLevel->iFrom>0 && (pTabItem[0].jointype & JT_LEFT)!=0 ){
111193     pLevel->iLeftJoin = ++pParse->nMem;
111194     sqlite3VdbeAddOp2(v, OP_Integer, 0, pLevel->iLeftJoin);
111195     VdbeComment((v, "init LEFT JOIN no-match flag"));
111196   }
111197 
111198   /* Special case of a FROM clause subquery implemented as a co-routine */
111199   if( pTabItem->viaCoroutine ){
111200     int regYield = pTabItem->regReturn;
111201     sqlite3VdbeAddOp2(v, OP_Integer, pTabItem->addrFillSub-1, regYield);
111202     pLevel->p2 =  sqlite3VdbeAddOp1(v, OP_Yield, regYield);
111203     VdbeComment((v, "next row of co-routine %s", pTabItem->pTab->zName));
111204     sqlite3VdbeAddOp2(v, OP_If, regYield+1, addrBrk);
111205     pLevel->op = OP_Goto;
111206   }else
111207 
111208 #ifndef SQLITE_OMIT_VIRTUALTABLE
111209   if(  (pLoop->wsFlags & WHERE_VIRTUALTABLE)!=0 ){
111210     /* Case 1:  The table is a virtual-table.  Use the VFilter and VNext
111211     **          to access the data.
111212     */
111213     int iReg;   /* P3 Value for OP_VFilter */
111214     int addrNotFound;
111215     int nConstraint = pLoop->nLTerm;
111216 
111217     sqlite3ExprCachePush(pParse);
111218     iReg = sqlite3GetTempRange(pParse, nConstraint+2);
111219     addrNotFound = pLevel->addrBrk;
111220     for(j=0; j<nConstraint; j++){
111221       int iTarget = iReg+j+2;
111222       pTerm = pLoop->aLTerm[j];
111223       if( pTerm==0 ) continue;
111224       if( pTerm->eOperator & WO_IN ){
111225         codeEqualityTerm(pParse, pTerm, pLevel, j, bRev, iTarget);
111226         addrNotFound = pLevel->addrNxt;
111227       }else{
111228         sqlite3ExprCode(pParse, pTerm->pExpr->pRight, iTarget);
111229       }
111230     }
111231     sqlite3VdbeAddOp2(v, OP_Integer, pLoop->u.vtab.idxNum, iReg);
111232     sqlite3VdbeAddOp2(v, OP_Integer, nConstraint, iReg+1);
111233     sqlite3VdbeAddOp4(v, OP_VFilter, iCur, addrNotFound, iReg,
111234                       pLoop->u.vtab.idxStr,
111235                       pLoop->u.vtab.needFree ? P4_MPRINTF : P4_STATIC);
111236     pLoop->u.vtab.needFree = 0;
111237     for(j=0; j<nConstraint && j<16; j++){
111238       if( (pLoop->u.vtab.omitMask>>j)&1 ){
111239         disableTerm(pLevel, pLoop->aLTerm[j]);
111240       }
111241     }
111242     pLevel->op = OP_VNext;
111243     pLevel->p1 = iCur;
111244     pLevel->p2 = sqlite3VdbeCurrentAddr(v);
111245     sqlite3ReleaseTempRange(pParse, iReg, nConstraint+2);
111246     sqlite3ExprCachePop(pParse, 1);
111247   }else
111248 #endif /* SQLITE_OMIT_VIRTUALTABLE */
111249 
111250   if( (pLoop->wsFlags & WHERE_IPK)!=0
111251    && (pLoop->wsFlags & (WHERE_COLUMN_IN|WHERE_COLUMN_EQ))!=0
111252   ){
111253     /* Case 2:  We can directly reference a single row using an
111254     **          equality comparison against the ROWID field.  Or
111255     **          we reference multiple rows using a "rowid IN (...)"
111256     **          construct.
111257     */
111258     assert( pLoop->u.btree.nEq==1 );
111259     iReleaseReg = sqlite3GetTempReg(pParse);
111260     pTerm = pLoop->aLTerm[0];
111261     assert( pTerm!=0 );
111262     assert( pTerm->pExpr!=0 );
111263     assert( omitTable==0 );
111264     testcase( pTerm->wtFlags & TERM_VIRTUAL );
111265     iRowidReg = codeEqualityTerm(pParse, pTerm, pLevel, 0, bRev, iReleaseReg);
111266     addrNxt = pLevel->addrNxt;
111267     sqlite3VdbeAddOp2(v, OP_MustBeInt, iRowidReg, addrNxt);
111268     sqlite3VdbeAddOp3(v, OP_NotExists, iCur, addrNxt, iRowidReg);
111269     sqlite3ExprCacheAffinityChange(pParse, iRowidReg, 1);
111270     sqlite3ExprCacheStore(pParse, iCur, -1, iRowidReg);
111271     VdbeComment((v, "pk"));
111272     pLevel->op = OP_Noop;
111273   }else if( (pLoop->wsFlags & WHERE_IPK)!=0
111274          && (pLoop->wsFlags & WHERE_COLUMN_RANGE)!=0
111275   ){
111276     /* Case 3:  We have an inequality comparison against the ROWID field.
111277     */
111278     int testOp = OP_Noop;
111279     int start;
111280     int memEndValue = 0;
111281     WhereTerm *pStart, *pEnd;
111282 
111283     assert( omitTable==0 );
111284     j = 0;
111285     pStart = pEnd = 0;
111286     if( pLoop->wsFlags & WHERE_BTM_LIMIT ) pStart = pLoop->aLTerm[j++];
111287     if( pLoop->wsFlags & WHERE_TOP_LIMIT ) pEnd = pLoop->aLTerm[j++];
111288     assert( pStart!=0 || pEnd!=0 );
111289     if( bRev ){
111290       pTerm = pStart;
111291       pStart = pEnd;
111292       pEnd = pTerm;
111293     }
111294     if( pStart ){
111295       Expr *pX;             /* The expression that defines the start bound */
111296       int r1, rTemp;        /* Registers for holding the start boundary */
111297 
111298       /* The following constant maps TK_xx codes into corresponding 
111299       ** seek opcodes.  It depends on a particular ordering of TK_xx
111300       */
111301       const u8 aMoveOp[] = {
111302            /* TK_GT */  OP_SeekGt,
111303            /* TK_LE */  OP_SeekLe,
111304            /* TK_LT */  OP_SeekLt,
111305            /* TK_GE */  OP_SeekGe
111306       };
111307       assert( TK_LE==TK_GT+1 );      /* Make sure the ordering.. */
111308       assert( TK_LT==TK_GT+2 );      /*  ... of the TK_xx values... */
111309       assert( TK_GE==TK_GT+3 );      /*  ... is correcct. */
111310 
111311       assert( (pStart->wtFlags & TERM_VNULL)==0 );
111312       testcase( pStart->wtFlags & TERM_VIRTUAL );
111313       pX = pStart->pExpr;
111314       assert( pX!=0 );
111315       testcase( pStart->leftCursor!=iCur ); /* transitive constraints */
111316       r1 = sqlite3ExprCodeTemp(pParse, pX->pRight, &rTemp);
111317       sqlite3VdbeAddOp3(v, aMoveOp[pX->op-TK_GT], iCur, addrBrk, r1);
111318       VdbeComment((v, "pk"));
111319       sqlite3ExprCacheAffinityChange(pParse, r1, 1);
111320       sqlite3ReleaseTempReg(pParse, rTemp);
111321       disableTerm(pLevel, pStart);
111322     }else{
111323       sqlite3VdbeAddOp2(v, bRev ? OP_Last : OP_Rewind, iCur, addrBrk);
111324     }
111325     if( pEnd ){
111326       Expr *pX;
111327       pX = pEnd->pExpr;
111328       assert( pX!=0 );
111329       assert( (pEnd->wtFlags & TERM_VNULL)==0 );
111330       testcase( pEnd->leftCursor!=iCur ); /* Transitive constraints */
111331       testcase( pEnd->wtFlags & TERM_VIRTUAL );
111332       memEndValue = ++pParse->nMem;
111333       sqlite3ExprCode(pParse, pX->pRight, memEndValue);
111334       if( pX->op==TK_LT || pX->op==TK_GT ){
111335         testOp = bRev ? OP_Le : OP_Ge;
111336       }else{
111337         testOp = bRev ? OP_Lt : OP_Gt;
111338       }
111339       disableTerm(pLevel, pEnd);
111340     }
111341     start = sqlite3VdbeCurrentAddr(v);
111342     pLevel->op = bRev ? OP_Prev : OP_Next;
111343     pLevel->p1 = iCur;
111344     pLevel->p2 = start;
111345     assert( pLevel->p5==0 );
111346     if( testOp!=OP_Noop ){
111347       iRowidReg = iReleaseReg = sqlite3GetTempReg(pParse);
111348       sqlite3VdbeAddOp2(v, OP_Rowid, iCur, iRowidReg);
111349       sqlite3ExprCacheStore(pParse, iCur, -1, iRowidReg);
111350       sqlite3VdbeAddOp3(v, testOp, memEndValue, addrBrk, iRowidReg);
111351       sqlite3VdbeChangeP5(v, SQLITE_AFF_NUMERIC | SQLITE_JUMPIFNULL);
111352     }
111353   }else if( pLoop->wsFlags & WHERE_INDEXED ){
111354     /* Case 4: A scan using an index.
111355     **
111356     **         The WHERE clause may contain zero or more equality 
111357     **         terms ("==" or "IN" operators) that refer to the N
111358     **         left-most columns of the index. It may also contain
111359     **         inequality constraints (>, <, >= or <=) on the indexed
111360     **         column that immediately follows the N equalities. Only 
111361     **         the right-most column can be an inequality - the rest must
111362     **         use the "==" and "IN" operators. For example, if the 
111363     **         index is on (x,y,z), then the following clauses are all 
111364     **         optimized:
111365     **
111366     **            x=5
111367     **            x=5 AND y=10
111368     **            x=5 AND y<10
111369     **            x=5 AND y>5 AND y<10
111370     **            x=5 AND y=5 AND z<=10
111371     **
111372     **         The z<10 term of the following cannot be used, only
111373     **         the x=5 term:
111374     **
111375     **            x=5 AND z<10
111376     **
111377     **         N may be zero if there are inequality constraints.
111378     **         If there are no inequality constraints, then N is at
111379     **         least one.
111380     **
111381     **         This case is also used when there are no WHERE clause
111382     **         constraints but an index is selected anyway, in order
111383     **         to force the output order to conform to an ORDER BY.
111384     */  
111385     static const u8 aStartOp[] = {
111386       0,
111387       0,
111388       OP_Rewind,           /* 2: (!start_constraints && startEq &&  !bRev) */
111389       OP_Last,             /* 3: (!start_constraints && startEq &&   bRev) */
111390       OP_SeekGt,           /* 4: (start_constraints  && !startEq && !bRev) */
111391       OP_SeekLt,           /* 5: (start_constraints  && !startEq &&  bRev) */
111392       OP_SeekGe,           /* 6: (start_constraints  &&  startEq && !bRev) */
111393       OP_SeekLe            /* 7: (start_constraints  &&  startEq &&  bRev) */
111394     };
111395     static const u8 aEndOp[] = {
111396       OP_Noop,             /* 0: (!end_constraints) */
111397       OP_IdxGE,            /* 1: (end_constraints && !bRev) */
111398       OP_IdxLT             /* 2: (end_constraints && bRev) */
111399     };
111400     u16 nEq = pLoop->u.btree.nEq;     /* Number of == or IN terms */
111401     int isMinQuery = 0;          /* If this is an optimized SELECT min(x).. */
111402     int regBase;                 /* Base register holding constraint values */
111403     int r1;                      /* Temp register */
111404     WhereTerm *pRangeStart = 0;  /* Inequality constraint at range start */
111405     WhereTerm *pRangeEnd = 0;    /* Inequality constraint at range end */
111406     int startEq;                 /* True if range start uses ==, >= or <= */
111407     int endEq;                   /* True if range end uses ==, >= or <= */
111408     int start_constraints;       /* Start of range is constrained */
111409     int nConstraint;             /* Number of constraint terms */
111410     Index *pIdx;                 /* The index we will be using */
111411     int iIdxCur;                 /* The VDBE cursor for the index */
111412     int nExtraReg = 0;           /* Number of extra registers needed */
111413     int op;                      /* Instruction opcode */
111414     char *zStartAff;             /* Affinity for start of range constraint */
111415     char cEndAff = 0;            /* Affinity for end of range constraint */
111416 
111417     pIdx = pLoop->u.btree.pIndex;
111418     iIdxCur = pLevel->iIdxCur;
111419     assert( nEq>=pLoop->u.btree.nSkip );
111420 
111421     /* If this loop satisfies a sort order (pOrderBy) request that 
111422     ** was passed to this function to implement a "SELECT min(x) ..." 
111423     ** query, then the caller will only allow the loop to run for
111424     ** a single iteration. This means that the first row returned
111425     ** should not have a NULL value stored in 'x'. If column 'x' is
111426     ** the first one after the nEq equality constraints in the index,
111427     ** this requires some special handling.
111428     */
111429     if( (pWInfo->wctrlFlags&WHERE_ORDERBY_MIN)!=0
111430      && (pWInfo->bOBSat!=0)
111431      && (pIdx->nKeyCol>nEq)
111432     ){
111433       assert( pLoop->u.btree.nSkip==0 );
111434       isMinQuery = 1;
111435       nExtraReg = 1;
111436     }
111437 
111438     /* Find any inequality constraint terms for the start and end 
111439     ** of the range. 
111440     */
111441     j = nEq;
111442     if( pLoop->wsFlags & WHERE_BTM_LIMIT ){
111443       pRangeStart = pLoop->aLTerm[j++];
111444       nExtraReg = 1;
111445     }
111446     if( pLoop->wsFlags & WHERE_TOP_LIMIT ){
111447       pRangeEnd = pLoop->aLTerm[j++];
111448       nExtraReg = 1;
111449     }
111450 
111451     /* Generate code to evaluate all constraint terms using == or IN
111452     ** and store the values of those terms in an array of registers
111453     ** starting at regBase.
111454     */
111455     regBase = codeAllEqualityTerms(pParse,pLevel,bRev,nExtraReg,&zStartAff);
111456     assert( zStartAff==0 || sqlite3Strlen30(zStartAff)>=nEq );
111457     if( zStartAff ) cEndAff = zStartAff[nEq];
111458     addrNxt = pLevel->addrNxt;
111459 
111460     /* If we are doing a reverse order scan on an ascending index, or
111461     ** a forward order scan on a descending index, interchange the 
111462     ** start and end terms (pRangeStart and pRangeEnd).
111463     */
111464     if( (nEq<pIdx->nKeyCol && bRev==(pIdx->aSortOrder[nEq]==SQLITE_SO_ASC))
111465      || (bRev && pIdx->nKeyCol==nEq)
111466     ){
111467       SWAP(WhereTerm *, pRangeEnd, pRangeStart);
111468     }
111469 
111470     testcase( pRangeStart && (pRangeStart->eOperator & WO_LE)!=0 );
111471     testcase( pRangeStart && (pRangeStart->eOperator & WO_GE)!=0 );
111472     testcase( pRangeEnd && (pRangeEnd->eOperator & WO_LE)!=0 );
111473     testcase( pRangeEnd && (pRangeEnd->eOperator & WO_GE)!=0 );
111474     startEq = !pRangeStart || pRangeStart->eOperator & (WO_LE|WO_GE);
111475     endEq =   !pRangeEnd || pRangeEnd->eOperator & (WO_LE|WO_GE);
111476     start_constraints = pRangeStart || nEq>0;
111477 
111478     /* Seek the index cursor to the start of the range. */
111479     nConstraint = nEq;
111480     if( pRangeStart ){
111481       Expr *pRight = pRangeStart->pExpr->pRight;
111482       sqlite3ExprCode(pParse, pRight, regBase+nEq);
111483       if( (pRangeStart->wtFlags & TERM_VNULL)==0 ){
111484         sqlite3ExprCodeIsNullJump(v, pRight, regBase+nEq, addrNxt);
111485       }
111486       if( zStartAff ){
111487         if( sqlite3CompareAffinity(pRight, zStartAff[nEq])==SQLITE_AFF_NONE){
111488           /* Since the comparison is to be performed with no conversions
111489           ** applied to the operands, set the affinity to apply to pRight to 
111490           ** SQLITE_AFF_NONE.  */
111491           zStartAff[nEq] = SQLITE_AFF_NONE;
111492         }
111493         if( sqlite3ExprNeedsNoAffinityChange(pRight, zStartAff[nEq]) ){
111494           zStartAff[nEq] = SQLITE_AFF_NONE;
111495         }
111496       }  
111497       nConstraint++;
111498       testcase( pRangeStart->wtFlags & TERM_VIRTUAL );
111499     }else if( isMinQuery ){
111500       sqlite3VdbeAddOp2(v, OP_Null, 0, regBase+nEq);
111501       nConstraint++;
111502       startEq = 0;
111503       start_constraints = 1;
111504     }
111505     codeApplyAffinity(pParse, regBase, nConstraint, zStartAff);
111506     op = aStartOp[(start_constraints<<2) + (startEq<<1) + bRev];
111507     assert( op!=0 );
111508     testcase( op==OP_Rewind );
111509     testcase( op==OP_Last );
111510     testcase( op==OP_SeekGt );
111511     testcase( op==OP_SeekGe );
111512     testcase( op==OP_SeekLe );
111513     testcase( op==OP_SeekLt );
111514     sqlite3VdbeAddOp4Int(v, op, iIdxCur, addrNxt, regBase, nConstraint);
111515 
111516     /* Load the value for the inequality constraint at the end of the
111517     ** range (if any).
111518     */
111519     nConstraint = nEq;
111520     if( pRangeEnd ){
111521       Expr *pRight = pRangeEnd->pExpr->pRight;
111522       sqlite3ExprCacheRemove(pParse, regBase+nEq, 1);
111523       sqlite3ExprCode(pParse, pRight, regBase+nEq);
111524       if( (pRangeEnd->wtFlags & TERM_VNULL)==0 ){
111525         sqlite3ExprCodeIsNullJump(v, pRight, regBase+nEq, addrNxt);
111526       }
111527       if( sqlite3CompareAffinity(pRight, cEndAff)!=SQLITE_AFF_NONE
111528        && !sqlite3ExprNeedsNoAffinityChange(pRight, cEndAff)
111529       ){
111530         codeApplyAffinity(pParse, regBase+nEq, 1, &cEndAff);
111531       }
111532       nConstraint++;
111533       testcase( pRangeEnd->wtFlags & TERM_VIRTUAL );
111534     }
111535     sqlite3DbFree(db, zStartAff);
111536 
111537     /* Top of the loop body */
111538     pLevel->p2 = sqlite3VdbeCurrentAddr(v);
111539 
111540     /* Check if the index cursor is past the end of the range. */
111541     op = aEndOp[(pRangeEnd || nEq) * (1 + bRev)];
111542     testcase( op==OP_Noop );
111543     testcase( op==OP_IdxGE );
111544     testcase( op==OP_IdxLT );
111545     if( op!=OP_Noop ){
111546       sqlite3VdbeAddOp4Int(v, op, iIdxCur, addrNxt, regBase, nConstraint);
111547       sqlite3VdbeChangeP5(v, endEq!=bRev ?1:0);
111548     }
111549 
111550     /* If there are inequality constraints, check that the value
111551     ** of the table column that the inequality contrains is not NULL.
111552     ** If it is, jump to the next iteration of the loop.
111553     */
111554     r1 = sqlite3GetTempReg(pParse);
111555     testcase( pLoop->wsFlags & WHERE_BTM_LIMIT );
111556     testcase( pLoop->wsFlags & WHERE_TOP_LIMIT );
111557     if( (pLoop->wsFlags & (WHERE_BTM_LIMIT|WHERE_TOP_LIMIT))!=0 
111558      && (j = pIdx->aiColumn[nEq])>=0 
111559      && pIdx->pTable->aCol[j].notNull==0 
111560      && (nEq || (pLoop->wsFlags & WHERE_BTM_LIMIT)==0)
111561     ){
111562       sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, nEq, r1);
111563       VdbeComment((v, "%s", pIdx->pTable->aCol[j].zName));
111564       sqlite3VdbeAddOp2(v, OP_IsNull, r1, addrCont);
111565     }
111566     sqlite3ReleaseTempReg(pParse, r1);
111567 
111568     /* Seek the table cursor, if required */
111569     disableTerm(pLevel, pRangeStart);
111570     disableTerm(pLevel, pRangeEnd);
111571     if( omitTable ){
111572       /* pIdx is a covering index.  No need to access the main table. */
111573     }else if( HasRowid(pIdx->pTable) ){
111574       iRowidReg = iReleaseReg = sqlite3GetTempReg(pParse);
111575       sqlite3VdbeAddOp2(v, OP_IdxRowid, iIdxCur, iRowidReg);
111576       sqlite3ExprCacheStore(pParse, iCur, -1, iRowidReg);
111577       sqlite3VdbeAddOp2(v, OP_Seek, iCur, iRowidReg);  /* Deferred seek */
111578     }else{
111579       Index *pPk = sqlite3PrimaryKeyIndex(pIdx->pTable);
111580       iRowidReg = sqlite3GetTempRange(pParse, pPk->nKeyCol);
111581       for(j=0; j<pPk->nKeyCol; j++){
111582         k = sqlite3ColumnOfIndex(pIdx, pPk->aiColumn[j]);
111583         sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, k, iRowidReg+j);
111584       }
111585       sqlite3VdbeAddOp4Int(v, OP_NotFound, iCur, addrCont,
111586                            iRowidReg, pPk->nKeyCol);
111587     }
111588 
111589     /* Record the instruction used to terminate the loop. Disable 
111590     ** WHERE clause terms made redundant by the index range scan.
111591     */
111592     if( pLoop->wsFlags & WHERE_ONEROW ){
111593       pLevel->op = OP_Noop;
111594     }else if( bRev ){
111595       pLevel->op = OP_Prev;
111596     }else{
111597       pLevel->op = OP_Next;
111598     }
111599     pLevel->p1 = iIdxCur;
111600     if( (pLoop->wsFlags & WHERE_CONSTRAINT)==0 ){
111601       pLevel->p5 = SQLITE_STMTSTATUS_FULLSCAN_STEP;
111602     }else{
111603       assert( pLevel->p5==0 );
111604     }
111605   }else
111606 
111607 #ifndef SQLITE_OMIT_OR_OPTIMIZATION
111608   if( pLoop->wsFlags & WHERE_MULTI_OR ){
111609     /* Case 5:  Two or more separately indexed terms connected by OR
111610     **
111611     ** Example:
111612     **
111613     **   CREATE TABLE t1(a,b,c,d);
111614     **   CREATE INDEX i1 ON t1(a);
111615     **   CREATE INDEX i2 ON t1(b);
111616     **   CREATE INDEX i3 ON t1(c);
111617     **
111618     **   SELECT * FROM t1 WHERE a=5 OR b=7 OR (c=11 AND d=13)
111619     **
111620     ** In the example, there are three indexed terms connected by OR.
111621     ** The top of the loop looks like this:
111622     **
111623     **          Null       1                # Zero the rowset in reg 1
111624     **
111625     ** Then, for each indexed term, the following. The arguments to
111626     ** RowSetTest are such that the rowid of the current row is inserted
111627     ** into the RowSet. If it is already present, control skips the
111628     ** Gosub opcode and jumps straight to the code generated by WhereEnd().
111629     **
111630     **        sqlite3WhereBegin(<term>)
111631     **          RowSetTest                  # Insert rowid into rowset
111632     **          Gosub      2 A
111633     **        sqlite3WhereEnd()
111634     **
111635     ** Following the above, code to terminate the loop. Label A, the target
111636     ** of the Gosub above, jumps to the instruction right after the Goto.
111637     **
111638     **          Null       1                # Zero the rowset in reg 1
111639     **          Goto       B                # The loop is finished.
111640     **
111641     **       A: <loop body>                 # Return data, whatever.
111642     **
111643     **          Return     2                # Jump back to the Gosub
111644     **
111645     **       B: <after the loop>
111646     **
111647     */
111648     WhereClause *pOrWc;    /* The OR-clause broken out into subterms */
111649     SrcList *pOrTab;       /* Shortened table list or OR-clause generation */
111650     Index *pCov = 0;             /* Potential covering index (or NULL) */
111651     int iCovCur = pParse->nTab++;  /* Cursor used for index scans (if any) */
111652 
111653     int regReturn = ++pParse->nMem;           /* Register used with OP_Gosub */
111654     int regRowset = 0;                        /* Register for RowSet object */
111655     int regRowid = 0;                         /* Register holding rowid */
111656     int iLoopBody = sqlite3VdbeMakeLabel(v);  /* Start of loop body */
111657     int iRetInit;                             /* Address of regReturn init */
111658     int untestedTerms = 0;             /* Some terms not completely tested */
111659     int ii;                            /* Loop counter */
111660     Expr *pAndExpr = 0;                /* An ".. AND (...)" expression */
111661    
111662     pTerm = pLoop->aLTerm[0];
111663     assert( pTerm!=0 );
111664     assert( pTerm->eOperator & WO_OR );
111665     assert( (pTerm->wtFlags & TERM_ORINFO)!=0 );
111666     pOrWc = &pTerm->u.pOrInfo->wc;
111667     pLevel->op = OP_Return;
111668     pLevel->p1 = regReturn;
111669 
111670     /* Set up a new SrcList in pOrTab containing the table being scanned
111671     ** by this loop in the a[0] slot and all notReady tables in a[1..] slots.
111672     ** This becomes the SrcList in the recursive call to sqlite3WhereBegin().
111673     */
111674     if( pWInfo->nLevel>1 ){
111675       int nNotReady;                 /* The number of notReady tables */
111676       struct SrcList_item *origSrc;     /* Original list of tables */
111677       nNotReady = pWInfo->nLevel - iLevel - 1;
111678       pOrTab = sqlite3StackAllocRaw(db,
111679                             sizeof(*pOrTab)+ nNotReady*sizeof(pOrTab->a[0]));
111680       if( pOrTab==0 ) return notReady;
111681       pOrTab->nAlloc = (u8)(nNotReady + 1);
111682       pOrTab->nSrc = pOrTab->nAlloc;
111683       memcpy(pOrTab->a, pTabItem, sizeof(*pTabItem));
111684       origSrc = pWInfo->pTabList->a;
111685       for(k=1; k<=nNotReady; k++){
111686         memcpy(&pOrTab->a[k], &origSrc[pLevel[k].iFrom], sizeof(pOrTab->a[k]));
111687       }
111688     }else{
111689       pOrTab = pWInfo->pTabList;
111690     }
111691 
111692     /* Initialize the rowset register to contain NULL. An SQL NULL is 
111693     ** equivalent to an empty rowset.
111694     **
111695     ** Also initialize regReturn to contain the address of the instruction 
111696     ** immediately following the OP_Return at the bottom of the loop. This
111697     ** is required in a few obscure LEFT JOIN cases where control jumps
111698     ** over the top of the loop into the body of it. In this case the 
111699     ** correct response for the end-of-loop code (the OP_Return) is to 
111700     ** fall through to the next instruction, just as an OP_Next does if
111701     ** called on an uninitialized cursor.
111702     */
111703     if( (pWInfo->wctrlFlags & WHERE_DUPLICATES_OK)==0 ){
111704       regRowset = ++pParse->nMem;
111705       regRowid = ++pParse->nMem;
111706       sqlite3VdbeAddOp2(v, OP_Null, 0, regRowset);
111707     }
111708     iRetInit = sqlite3VdbeAddOp2(v, OP_Integer, 0, regReturn);
111709 
111710     /* If the original WHERE clause is z of the form:  (x1 OR x2 OR ...) AND y
111711     ** Then for every term xN, evaluate as the subexpression: xN AND z
111712     ** That way, terms in y that are factored into the disjunction will
111713     ** be picked up by the recursive calls to sqlite3WhereBegin() below.
111714     **
111715     ** Actually, each subexpression is converted to "xN AND w" where w is
111716     ** the "interesting" terms of z - terms that did not originate in the
111717     ** ON or USING clause of a LEFT JOIN, and terms that are usable as 
111718     ** indices.
111719     **
111720     ** This optimization also only applies if the (x1 OR x2 OR ...) term
111721     ** is not contained in the ON clause of a LEFT JOIN.
111722     ** See ticket http://www.sqlite.org/src/info/f2369304e4
111723     */
111724     if( pWC->nTerm>1 ){
111725       int iTerm;
111726       for(iTerm=0; iTerm<pWC->nTerm; iTerm++){
111727         Expr *pExpr = pWC->a[iTerm].pExpr;
111728         if( &pWC->a[iTerm] == pTerm ) continue;
111729         if( ExprHasProperty(pExpr, EP_FromJoin) ) continue;
111730         if( pWC->a[iTerm].wtFlags & (TERM_ORINFO) ) continue;
111731         if( (pWC->a[iTerm].eOperator & WO_ALL)==0 ) continue;
111732         pExpr = sqlite3ExprDup(db, pExpr, 0);
111733         pAndExpr = sqlite3ExprAnd(db, pAndExpr, pExpr);
111734       }
111735       if( pAndExpr ){
111736         pAndExpr = sqlite3PExpr(pParse, TK_AND, 0, pAndExpr, 0);
111737       }
111738     }
111739 
111740     for(ii=0; ii<pOrWc->nTerm; ii++){
111741       WhereTerm *pOrTerm = &pOrWc->a[ii];
111742       if( pOrTerm->leftCursor==iCur || (pOrTerm->eOperator & WO_AND)!=0 ){
111743         WhereInfo *pSubWInfo;          /* Info for single OR-term scan */
111744         Expr *pOrExpr = pOrTerm->pExpr;
111745         if( pAndExpr && !ExprHasProperty(pOrExpr, EP_FromJoin) ){
111746           pAndExpr->pLeft = pOrExpr;
111747           pOrExpr = pAndExpr;
111748         }
111749         /* Loop through table entries that match term pOrTerm. */
111750         pSubWInfo = sqlite3WhereBegin(pParse, pOrTab, pOrExpr, 0, 0,
111751                         WHERE_OMIT_OPEN_CLOSE | WHERE_AND_ONLY |
111752                         WHERE_FORCE_TABLE | WHERE_ONETABLE_ONLY, iCovCur);
111753         assert( pSubWInfo || pParse->nErr || db->mallocFailed );
111754         if( pSubWInfo ){
111755           WhereLoop *pSubLoop;
111756           explainOneScan(
111757               pParse, pOrTab, &pSubWInfo->a[0], iLevel, pLevel->iFrom, 0
111758           );
111759           if( (pWInfo->wctrlFlags & WHERE_DUPLICATES_OK)==0 ){
111760             int iSet = ((ii==pOrWc->nTerm-1)?-1:ii);
111761             int r;
111762             r = sqlite3ExprCodeGetColumn(pParse, pTabItem->pTab, -1, iCur, 
111763                                          regRowid, 0);
111764             sqlite3VdbeAddOp4Int(v, OP_RowSetTest, regRowset,
111765                                  sqlite3VdbeCurrentAddr(v)+2, r, iSet);
111766           }
111767           sqlite3VdbeAddOp2(v, OP_Gosub, regReturn, iLoopBody);
111768 
111769           /* The pSubWInfo->untestedTerms flag means that this OR term
111770           ** contained one or more AND term from a notReady table.  The
111771           ** terms from the notReady table could not be tested and will
111772           ** need to be tested later.
111773           */
111774           if( pSubWInfo->untestedTerms ) untestedTerms = 1;
111775 
111776           /* If all of the OR-connected terms are optimized using the same
111777           ** index, and the index is opened using the same cursor number
111778           ** by each call to sqlite3WhereBegin() made by this loop, it may
111779           ** be possible to use that index as a covering index.
111780           **
111781           ** If the call to sqlite3WhereBegin() above resulted in a scan that
111782           ** uses an index, and this is either the first OR-connected term
111783           ** processed or the index is the same as that used by all previous
111784           ** terms, set pCov to the candidate covering index. Otherwise, set 
111785           ** pCov to NULL to indicate that no candidate covering index will 
111786           ** be available.
111787           */
111788           pSubLoop = pSubWInfo->a[0].pWLoop;
111789           assert( (pSubLoop->wsFlags & WHERE_AUTO_INDEX)==0 );
111790           if( (pSubLoop->wsFlags & WHERE_INDEXED)!=0
111791            && (ii==0 || pSubLoop->u.btree.pIndex==pCov)
111792           ){
111793             assert( pSubWInfo->a[0].iIdxCur==iCovCur );
111794             pCov = pSubLoop->u.btree.pIndex;
111795           }else{
111796             pCov = 0;
111797           }
111798 
111799           /* Finish the loop through table entries that match term pOrTerm. */
111800           sqlite3WhereEnd(pSubWInfo);
111801         }
111802       }
111803     }
111804     pLevel->u.pCovidx = pCov;
111805     if( pCov ) pLevel->iIdxCur = iCovCur;
111806     if( pAndExpr ){
111807       pAndExpr->pLeft = 0;
111808       sqlite3ExprDelete(db, pAndExpr);
111809     }
111810     sqlite3VdbeChangeP1(v, iRetInit, sqlite3VdbeCurrentAddr(v));
111811     sqlite3VdbeAddOp2(v, OP_Goto, 0, pLevel->addrBrk);
111812     sqlite3VdbeResolveLabel(v, iLoopBody);
111813 
111814     if( pWInfo->nLevel>1 ) sqlite3StackFree(db, pOrTab);
111815     if( !untestedTerms ) disableTerm(pLevel, pTerm);
111816   }else
111817 #endif /* SQLITE_OMIT_OR_OPTIMIZATION */
111818 
111819   {
111820     /* Case 6:  There is no usable index.  We must do a complete
111821     **          scan of the entire table.
111822     */
111823     static const u8 aStep[] = { OP_Next, OP_Prev };
111824     static const u8 aStart[] = { OP_Rewind, OP_Last };
111825     assert( bRev==0 || bRev==1 );
111826     pLevel->op = aStep[bRev];
111827     pLevel->p1 = iCur;
111828     pLevel->p2 = 1 + sqlite3VdbeAddOp2(v, aStart[bRev], iCur, addrBrk);
111829     pLevel->p5 = SQLITE_STMTSTATUS_FULLSCAN_STEP;
111830   }
111831 
111832   /* Insert code to test every subexpression that can be completely
111833   ** computed using the current set of tables.
111834   */
111835   for(pTerm=pWC->a, j=pWC->nTerm; j>0; j--, pTerm++){
111836     Expr *pE;
111837     testcase( pTerm->wtFlags & TERM_VIRTUAL );
111838     testcase( pTerm->wtFlags & TERM_CODED );
111839     if( pTerm->wtFlags & (TERM_VIRTUAL|TERM_CODED) ) continue;
111840     if( (pTerm->prereqAll & pLevel->notReady)!=0 ){
111841       testcase( pWInfo->untestedTerms==0
111842                && (pWInfo->wctrlFlags & WHERE_ONETABLE_ONLY)!=0 );
111843       pWInfo->untestedTerms = 1;
111844       continue;
111845     }
111846     pE = pTerm->pExpr;
111847     assert( pE!=0 );
111848     if( pLevel->iLeftJoin && !ExprHasProperty(pE, EP_FromJoin) ){
111849       continue;
111850     }
111851     sqlite3ExprIfFalse(pParse, pE, addrCont, SQLITE_JUMPIFNULL);
111852     pTerm->wtFlags |= TERM_CODED;
111853   }
111854 
111855   /* Insert code to test for implied constraints based on transitivity
111856   ** of the "==" operator.
111857   **
111858   ** Example: If the WHERE clause contains "t1.a=t2.b" and "t2.b=123"
111859   ** and we are coding the t1 loop and the t2 loop has not yet coded,
111860   ** then we cannot use the "t1.a=t2.b" constraint, but we can code
111861   ** the implied "t1.a=123" constraint.
111862   */
111863   for(pTerm=pWC->a, j=pWC->nTerm; j>0; j--, pTerm++){
111864     Expr *pE, *pEAlt;
111865     WhereTerm *pAlt;
111866     if( pTerm->wtFlags & (TERM_VIRTUAL|TERM_CODED) ) continue;
111867     if( pTerm->eOperator!=(WO_EQUIV|WO_EQ) ) continue;
111868     if( pTerm->leftCursor!=iCur ) continue;
111869     if( pLevel->iLeftJoin ) continue;
111870     pE = pTerm->pExpr;
111871     assert( !ExprHasProperty(pE, EP_FromJoin) );
111872     assert( (pTerm->prereqRight & pLevel->notReady)!=0 );
111873     pAlt = findTerm(pWC, iCur, pTerm->u.leftColumn, notReady, WO_EQ|WO_IN, 0);
111874     if( pAlt==0 ) continue;
111875     if( pAlt->wtFlags & (TERM_CODED) ) continue;
111876     testcase( pAlt->eOperator & WO_EQ );
111877     testcase( pAlt->eOperator & WO_IN );
111878     VdbeModuleComment((v, "begin transitive constraint"));
111879     pEAlt = sqlite3StackAllocRaw(db, sizeof(*pEAlt));
111880     if( pEAlt ){
111881       *pEAlt = *pAlt->pExpr;
111882       pEAlt->pLeft = pE->pLeft;
111883       sqlite3ExprIfFalse(pParse, pEAlt, addrCont, SQLITE_JUMPIFNULL);
111884       sqlite3StackFree(db, pEAlt);
111885     }
111886   }
111887 
111888   /* For a LEFT OUTER JOIN, generate code that will record the fact that
111889   ** at least one row of the right table has matched the left table.  
111890   */
111891   if( pLevel->iLeftJoin ){
111892     pLevel->addrFirst = sqlite3VdbeCurrentAddr(v);
111893     sqlite3VdbeAddOp2(v, OP_Integer, 1, pLevel->iLeftJoin);
111894     VdbeComment((v, "record LEFT JOIN hit"));
111895     sqlite3ExprCacheClear(pParse);
111896     for(pTerm=pWC->a, j=0; j<pWC->nTerm; j++, pTerm++){
111897       testcase( pTerm->wtFlags & TERM_VIRTUAL );
111898       testcase( pTerm->wtFlags & TERM_CODED );
111899       if( pTerm->wtFlags & (TERM_VIRTUAL|TERM_CODED) ) continue;
111900       if( (pTerm->prereqAll & pLevel->notReady)!=0 ){
111901         assert( pWInfo->untestedTerms );
111902         continue;
111903       }
111904       assert( pTerm->pExpr );
111905       sqlite3ExprIfFalse(pParse, pTerm->pExpr, addrCont, SQLITE_JUMPIFNULL);
111906       pTerm->wtFlags |= TERM_CODED;
111907     }
111908   }
111909   sqlite3ReleaseTempReg(pParse, iReleaseReg);
111910 
111911   return pLevel->notReady;
111912 }
111913 
111914 #if defined(WHERETRACE_ENABLED) && defined(SQLITE_ENABLE_TREE_EXPLAIN)
111915 /*
111916 ** Generate "Explanation" text for a WhereTerm.
111917 */
111918 static void whereExplainTerm(Vdbe *v, WhereTerm *pTerm){
111919   char zType[4];
111920   memcpy(zType, "...", 4);
111921   if( pTerm->wtFlags & TERM_VIRTUAL ) zType[0] = 'V';
111922   if( pTerm->eOperator & WO_EQUIV  ) zType[1] = 'E';
111923   if( ExprHasProperty(pTerm->pExpr, EP_FromJoin) ) zType[2] = 'L';
111924   sqlite3ExplainPrintf(v, "%s ", zType);
111925   sqlite3ExplainExpr(v, pTerm->pExpr);
111926 }
111927 #endif /* WHERETRACE_ENABLED && SQLITE_ENABLE_TREE_EXPLAIN */
111928 
111929 
111930 #ifdef WHERETRACE_ENABLED
111931 /*
111932 ** Print a WhereLoop object for debugging purposes
111933 */
111934 static void whereLoopPrint(WhereLoop *p, WhereClause *pWC){
111935   WhereInfo *pWInfo = pWC->pWInfo;
111936   int nb = 1+(pWInfo->pTabList->nSrc+7)/8;
111937   struct SrcList_item *pItem = pWInfo->pTabList->a + p->iTab;
111938   Table *pTab = pItem->pTab;
111939   sqlite3DebugPrintf("%c%2d.%0*llx.%0*llx", p->cId,
111940                      p->iTab, nb, p->maskSelf, nb, p->prereq);
111941   sqlite3DebugPrintf(" %12s",
111942                      pItem->zAlias ? pItem->zAlias : pTab->zName);
111943   if( (p->wsFlags & WHERE_VIRTUALTABLE)==0 ){
111944      const char *zName;
111945      if( p->u.btree.pIndex && (zName = p->u.btree.pIndex->zName)!=0 ){
111946       if( strncmp(zName, "sqlite_autoindex_", 17)==0 ){
111947         int i = sqlite3Strlen30(zName) - 1;
111948         while( zName[i]!='_' ) i--;
111949         zName += i;
111950       }
111951       sqlite3DebugPrintf(".%-16s %2d", zName, p->u.btree.nEq);
111952     }else{
111953       sqlite3DebugPrintf("%20s","");
111954     }
111955   }else{
111956     char *z;
111957     if( p->u.vtab.idxStr ){
111958       z = sqlite3_mprintf("(%d,\"%s\",%x)",
111959                 p->u.vtab.idxNum, p->u.vtab.idxStr, p->u.vtab.omitMask);
111960     }else{
111961       z = sqlite3_mprintf("(%d,%x)", p->u.vtab.idxNum, p->u.vtab.omitMask);
111962     }
111963     sqlite3DebugPrintf(" %-19s", z);
111964     sqlite3_free(z);
111965   }
111966   sqlite3DebugPrintf(" f %04x N %d", p->wsFlags, p->nLTerm);
111967   sqlite3DebugPrintf(" cost %d,%d,%d\n", p->rSetup, p->rRun, p->nOut);
111968 #ifdef SQLITE_ENABLE_TREE_EXPLAIN
111969   /* If the 0x100 bit of wheretracing is set, then show all of the constraint
111970   ** expressions in the WhereLoop.aLTerm[] array.
111971   */
111972   if( p->nLTerm && (sqlite3WhereTrace & 0x100)!=0 ){  /* WHERETRACE 0x100 */
111973     int i;
111974     Vdbe *v = pWInfo->pParse->pVdbe;
111975     sqlite3ExplainBegin(v);
111976     for(i=0; i<p->nLTerm; i++){
111977       WhereTerm *pTerm = p->aLTerm[i];
111978       if( pTerm==0 ) continue;
111979       sqlite3ExplainPrintf(v, "  (%d) #%-2d ", i+1, (int)(pTerm-pWC->a));
111980       sqlite3ExplainPush(v);
111981       whereExplainTerm(v, pTerm);
111982       sqlite3ExplainPop(v);
111983       sqlite3ExplainNL(v);
111984     }
111985     sqlite3ExplainFinish(v);
111986     sqlite3DebugPrintf("%s", sqlite3VdbeExplanation(v));
111987   }
111988 #endif
111989 }
111990 #endif
111991 
111992 /*
111993 ** Convert bulk memory into a valid WhereLoop that can be passed
111994 ** to whereLoopClear harmlessly.
111995 */
111996 static void whereLoopInit(WhereLoop *p){
111997   p->aLTerm = p->aLTermSpace;
111998   p->nLTerm = 0;
111999   p->nLSlot = ArraySize(p->aLTermSpace);
112000   p->wsFlags = 0;
112001 }
112002 
112003 /*
112004 ** Clear the WhereLoop.u union.  Leave WhereLoop.pLTerm intact.
112005 */
112006 static void whereLoopClearUnion(sqlite3 *db, WhereLoop *p){
112007   if( p->wsFlags & (WHERE_VIRTUALTABLE|WHERE_AUTO_INDEX) ){
112008     if( (p->wsFlags & WHERE_VIRTUALTABLE)!=0 && p->u.vtab.needFree ){
112009       sqlite3_free(p->u.vtab.idxStr);
112010       p->u.vtab.needFree = 0;
112011       p->u.vtab.idxStr = 0;
112012     }else if( (p->wsFlags & WHERE_AUTO_INDEX)!=0 && p->u.btree.pIndex!=0 ){
112013       sqlite3DbFree(db, p->u.btree.pIndex->zColAff);
112014       sqlite3KeyInfoUnref(p->u.btree.pIndex->pKeyInfo);
112015       sqlite3DbFree(db, p->u.btree.pIndex);
112016       p->u.btree.pIndex = 0;
112017     }
112018   }
112019 }
112020 
112021 /*
112022 ** Deallocate internal memory used by a WhereLoop object
112023 */
112024 static void whereLoopClear(sqlite3 *db, WhereLoop *p){
112025   if( p->aLTerm!=p->aLTermSpace ) sqlite3DbFree(db, p->aLTerm);
112026   whereLoopClearUnion(db, p);
112027   whereLoopInit(p);
112028 }
112029 
112030 /*
112031 ** Increase the memory allocation for pLoop->aLTerm[] to be at least n.
112032 */
112033 static int whereLoopResize(sqlite3 *db, WhereLoop *p, int n){
112034   WhereTerm **paNew;
112035   if( p->nLSlot>=n ) return SQLITE_OK;
112036   n = (n+7)&~7;
112037   paNew = sqlite3DbMallocRaw(db, sizeof(p->aLTerm[0])*n);
112038   if( paNew==0 ) return SQLITE_NOMEM;
112039   memcpy(paNew, p->aLTerm, sizeof(p->aLTerm[0])*p->nLSlot);
112040   if( p->aLTerm!=p->aLTermSpace ) sqlite3DbFree(db, p->aLTerm);
112041   p->aLTerm = paNew;
112042   p->nLSlot = n;
112043   return SQLITE_OK;
112044 }
112045 
112046 /*
112047 ** Transfer content from the second pLoop into the first.
112048 */
112049 static int whereLoopXfer(sqlite3 *db, WhereLoop *pTo, WhereLoop *pFrom){
112050   whereLoopClearUnion(db, pTo);
112051   if( whereLoopResize(db, pTo, pFrom->nLTerm) ){
112052     memset(&pTo->u, 0, sizeof(pTo->u));
112053     return SQLITE_NOMEM;
112054   }
112055   memcpy(pTo, pFrom, WHERE_LOOP_XFER_SZ);
112056   memcpy(pTo->aLTerm, pFrom->aLTerm, pTo->nLTerm*sizeof(pTo->aLTerm[0]));
112057   if( pFrom->wsFlags & WHERE_VIRTUALTABLE ){
112058     pFrom->u.vtab.needFree = 0;
112059   }else if( (pFrom->wsFlags & WHERE_AUTO_INDEX)!=0 ){
112060     pFrom->u.btree.pIndex = 0;
112061   }
112062   return SQLITE_OK;
112063 }
112064 
112065 /*
112066 ** Delete a WhereLoop object
112067 */
112068 static void whereLoopDelete(sqlite3 *db, WhereLoop *p){
112069   whereLoopClear(db, p);
112070   sqlite3DbFree(db, p);
112071 }
112072 
112073 /*
112074 ** Free a WhereInfo structure
112075 */
112076 static void whereInfoFree(sqlite3 *db, WhereInfo *pWInfo){
112077   if( ALWAYS(pWInfo) ){
112078     whereClauseClear(&pWInfo->sWC);
112079     while( pWInfo->pLoops ){
112080       WhereLoop *p = pWInfo->pLoops;
112081       pWInfo->pLoops = p->pNextLoop;
112082       whereLoopDelete(db, p);
112083     }
112084     sqlite3DbFree(db, pWInfo);
112085   }
112086 }
112087 
112088 /*
112089 ** Insert or replace a WhereLoop entry using the template supplied.
112090 **
112091 ** An existing WhereLoop entry might be overwritten if the new template
112092 ** is better and has fewer dependencies.  Or the template will be ignored
112093 ** and no insert will occur if an existing WhereLoop is faster and has
112094 ** fewer dependencies than the template.  Otherwise a new WhereLoop is
112095 ** added based on the template.
112096 **
112097 ** If pBuilder->pOrSet is not NULL then we only care about only the
112098 ** prerequisites and rRun and nOut costs of the N best loops.  That
112099 ** information is gathered in the pBuilder->pOrSet object.  This special
112100 ** processing mode is used only for OR clause processing.
112101 **
112102 ** When accumulating multiple loops (when pBuilder->pOrSet is NULL) we
112103 ** still might overwrite similar loops with the new template if the
112104 ** template is better.  Loops may be overwritten if the following 
112105 ** conditions are met:
112106 **
112107 **    (1)  They have the same iTab.
112108 **    (2)  They have the same iSortIdx.
112109 **    (3)  The template has same or fewer dependencies than the current loop
112110 **    (4)  The template has the same or lower cost than the current loop
112111 **    (5)  The template uses more terms of the same index but has no additional
112112 **         dependencies          
112113 */
112114 static int whereLoopInsert(WhereLoopBuilder *pBuilder, WhereLoop *pTemplate){
112115   WhereLoop **ppPrev, *p, *pNext = 0;
112116   WhereInfo *pWInfo = pBuilder->pWInfo;
112117   sqlite3 *db = pWInfo->pParse->db;
112118 
112119   /* If pBuilder->pOrSet is defined, then only keep track of the costs
112120   ** and prereqs.
112121   */
112122   if( pBuilder->pOrSet!=0 ){
112123 #if WHERETRACE_ENABLED
112124     u16 n = pBuilder->pOrSet->n;
112125     int x =
112126 #endif
112127     whereOrInsert(pBuilder->pOrSet, pTemplate->prereq, pTemplate->rRun,
112128                                     pTemplate->nOut);
112129 #if WHERETRACE_ENABLED /* 0x8 */
112130     if( sqlite3WhereTrace & 0x8 ){
112131       sqlite3DebugPrintf(x?"   or-%d:  ":"   or-X:  ", n);
112132       whereLoopPrint(pTemplate, pBuilder->pWC);
112133     }
112134 #endif
112135     return SQLITE_OK;
112136   }
112137 
112138   /* Search for an existing WhereLoop to overwrite, or which takes
112139   ** priority over pTemplate.
112140   */
112141   for(ppPrev=&pWInfo->pLoops, p=*ppPrev; p; ppPrev=&p->pNextLoop, p=*ppPrev){
112142     if( p->iTab!=pTemplate->iTab || p->iSortIdx!=pTemplate->iSortIdx ){
112143       /* If either the iTab or iSortIdx values for two WhereLoop are different
112144       ** then those WhereLoops need to be considered separately.  Neither is
112145       ** a candidate to replace the other. */
112146       continue;
112147     }
112148     /* In the current implementation, the rSetup value is either zero
112149     ** or the cost of building an automatic index (NlogN) and the NlogN
112150     ** is the same for compatible WhereLoops. */
112151     assert( p->rSetup==0 || pTemplate->rSetup==0 
112152                  || p->rSetup==pTemplate->rSetup );
112153 
112154     /* whereLoopAddBtree() always generates and inserts the automatic index
112155     ** case first.  Hence compatible candidate WhereLoops never have a larger
112156     ** rSetup. Call this SETUP-INVARIANT */
112157     assert( p->rSetup>=pTemplate->rSetup );
112158 
112159     if( (p->prereq & pTemplate->prereq)==p->prereq
112160      && p->rSetup<=pTemplate->rSetup
112161      && p->rRun<=pTemplate->rRun
112162      && p->nOut<=pTemplate->nOut
112163     ){
112164       /* This branch taken when p is equal or better than pTemplate in 
112165       ** all of (1) dependencies (2) setup-cost, (3) run-cost, and
112166       ** (4) number of output rows. */
112167       assert( p->rSetup==pTemplate->rSetup );
112168       if( p->prereq==pTemplate->prereq
112169        && p->nLTerm<pTemplate->nLTerm
112170        && (p->wsFlags & pTemplate->wsFlags & WHERE_INDEXED)!=0
112171        && (p->u.btree.pIndex==pTemplate->u.btree.pIndex
112172           || pTemplate->rRun+p->nLTerm<=p->rRun+pTemplate->nLTerm)
112173       ){
112174         /* Overwrite an existing WhereLoop with an similar one that uses
112175         ** more terms of the index */
112176         pNext = p->pNextLoop;
112177         break;
112178       }else{
112179         /* pTemplate is not helpful.
112180         ** Return without changing or adding anything */
112181         goto whereLoopInsert_noop;
112182       }
112183     }
112184     if( (p->prereq & pTemplate->prereq)==pTemplate->prereq
112185      && p->rRun>=pTemplate->rRun
112186      && p->nOut>=pTemplate->nOut
112187     ){
112188       /* Overwrite an existing WhereLoop with a better one: one that is
112189       ** better at one of (1) dependencies, (2) setup-cost, (3) run-cost
112190       ** or (4) number of output rows, and is no worse in any of those
112191       ** categories. */
112192       assert( p->rSetup>=pTemplate->rSetup ); /* SETUP-INVARIANT above */
112193       pNext = p->pNextLoop;
112194       break;
112195     }
112196   }
112197 
112198   /* If we reach this point it means that either p[] should be overwritten
112199   ** with pTemplate[] if p[] exists, or if p==NULL then allocate a new
112200   ** WhereLoop and insert it.
112201   */
112202 #if WHERETRACE_ENABLED /* 0x8 */
112203   if( sqlite3WhereTrace & 0x8 ){
112204     if( p!=0 ){
112205       sqlite3DebugPrintf("ins-del:  ");
112206       whereLoopPrint(p, pBuilder->pWC);
112207     }
112208     sqlite3DebugPrintf("ins-new:  ");
112209     whereLoopPrint(pTemplate, pBuilder->pWC);
112210   }
112211 #endif
112212   if( p==0 ){
112213     p = sqlite3DbMallocRaw(db, sizeof(WhereLoop));
112214     if( p==0 ) return SQLITE_NOMEM;
112215     whereLoopInit(p);
112216   }
112217   whereLoopXfer(db, p, pTemplate);
112218   p->pNextLoop = pNext;
112219   *ppPrev = p;
112220   if( (p->wsFlags & WHERE_VIRTUALTABLE)==0 ){
112221     Index *pIndex = p->u.btree.pIndex;
112222     if( pIndex && pIndex->tnum==0 ){
112223       p->u.btree.pIndex = 0;
112224     }
112225   }
112226   return SQLITE_OK;
112227 
112228   /* Jump here if the insert is a no-op */
112229 whereLoopInsert_noop:
112230 #if WHERETRACE_ENABLED /* 0x8 */
112231   if( sqlite3WhereTrace & 0x8 ){
112232     sqlite3DebugPrintf("ins-noop: ");
112233     whereLoopPrint(pTemplate, pBuilder->pWC);
112234   }
112235 #endif
112236   return SQLITE_OK;  
112237 }
112238 
112239 /*
112240 ** Adjust the WhereLoop.nOut value downward to account for terms of the
112241 ** WHERE clause that reference the loop but which are not used by an
112242 ** index.
112243 **
112244 ** In the current implementation, the first extra WHERE clause term reduces
112245 ** the number of output rows by a factor of 10 and each additional term
112246 ** reduces the number of output rows by sqrt(2).
112247 */
112248 static void whereLoopOutputAdjust(WhereClause *pWC, WhereLoop *pLoop){
112249   WhereTerm *pTerm, *pX;
112250   Bitmask notAllowed = ~(pLoop->prereq|pLoop->maskSelf);
112251   int i, j;
112252 
112253   if( !OptimizationEnabled(pWC->pWInfo->pParse->db, SQLITE_AdjustOutEst) ){
112254     return;
112255   }
112256   for(i=pWC->nTerm, pTerm=pWC->a; i>0; i--, pTerm++){
112257     if( (pTerm->wtFlags & TERM_VIRTUAL)!=0 ) break;
112258     if( (pTerm->prereqAll & pLoop->maskSelf)==0 ) continue;
112259     if( (pTerm->prereqAll & notAllowed)!=0 ) continue;
112260     for(j=pLoop->nLTerm-1; j>=0; j--){
112261       pX = pLoop->aLTerm[j];
112262       if( pX==0 ) continue;
112263       if( pX==pTerm ) break;
112264       if( pX->iParent>=0 && (&pWC->a[pX->iParent])==pTerm ) break;
112265     }
112266     if( j<0 ) pLoop->nOut += pTerm->truthProb;
112267   }
112268 }
112269 
112270 /*
112271 ** We have so far matched pBuilder->pNew->u.btree.nEq terms of the index pIndex.
112272 ** Try to match one more.
112273 **
112274 ** If pProbe->tnum==0, that means pIndex is a fake index used for the
112275 ** INTEGER PRIMARY KEY.
112276 */
112277 static int whereLoopAddBtreeIndex(
112278   WhereLoopBuilder *pBuilder,     /* The WhereLoop factory */
112279   struct SrcList_item *pSrc,      /* FROM clause term being analyzed */
112280   Index *pProbe,                  /* An index on pSrc */
112281   LogEst nInMul                   /* log(Number of iterations due to IN) */
112282 ){
112283   WhereInfo *pWInfo = pBuilder->pWInfo;  /* WHERE analyse context */
112284   Parse *pParse = pWInfo->pParse;        /* Parsing context */
112285   sqlite3 *db = pParse->db;       /* Database connection malloc context */
112286   WhereLoop *pNew;                /* Template WhereLoop under construction */
112287   WhereTerm *pTerm;               /* A WhereTerm under consideration */
112288   int opMask;                     /* Valid operators for constraints */
112289   WhereScan scan;                 /* Iterator for WHERE terms */
112290   Bitmask saved_prereq;           /* Original value of pNew->prereq */
112291   u16 saved_nLTerm;               /* Original value of pNew->nLTerm */
112292   u16 saved_nEq;                  /* Original value of pNew->u.btree.nEq */
112293   u16 saved_nSkip;                /* Original value of pNew->u.btree.nSkip */
112294   u32 saved_wsFlags;              /* Original value of pNew->wsFlags */
112295   LogEst saved_nOut;              /* Original value of pNew->nOut */
112296   int iCol;                       /* Index of the column in the table */
112297   int rc = SQLITE_OK;             /* Return code */
112298   LogEst nRowEst;                 /* Estimated index selectivity */
112299   LogEst rLogSize;                /* Logarithm of table size */
112300   WhereTerm *pTop = 0, *pBtm = 0; /* Top and bottom range constraints */
112301 
112302   pNew = pBuilder->pNew;
112303   if( db->mallocFailed ) return SQLITE_NOMEM;
112304 
112305   assert( (pNew->wsFlags & WHERE_VIRTUALTABLE)==0 );
112306   assert( (pNew->wsFlags & WHERE_TOP_LIMIT)==0 );
112307   if( pNew->wsFlags & WHERE_BTM_LIMIT ){
112308     opMask = WO_LT|WO_LE;
112309   }else if( pProbe->tnum<=0 || (pSrc->jointype & JT_LEFT)!=0 ){
112310     opMask = WO_EQ|WO_IN|WO_GT|WO_GE|WO_LT|WO_LE;
112311   }else{
112312     opMask = WO_EQ|WO_IN|WO_ISNULL|WO_GT|WO_GE|WO_LT|WO_LE;
112313   }
112314   if( pProbe->bUnordered ) opMask &= ~(WO_GT|WO_GE|WO_LT|WO_LE);
112315 
112316   assert( pNew->u.btree.nEq<=pProbe->nKeyCol );
112317   if( pNew->u.btree.nEq < pProbe->nKeyCol ){
112318     iCol = pProbe->aiColumn[pNew->u.btree.nEq];
112319     nRowEst = sqlite3LogEst(pProbe->aiRowEst[pNew->u.btree.nEq+1]);
112320     if( nRowEst==0 && pProbe->onError==OE_None ) nRowEst = 1;
112321   }else{
112322     iCol = -1;
112323     nRowEst = 0;
112324   }
112325   pTerm = whereScanInit(&scan, pBuilder->pWC, pSrc->iCursor, iCol,
112326                         opMask, pProbe);
112327   saved_nEq = pNew->u.btree.nEq;
112328   saved_nSkip = pNew->u.btree.nSkip;
112329   saved_nLTerm = pNew->nLTerm;
112330   saved_wsFlags = pNew->wsFlags;
112331   saved_prereq = pNew->prereq;
112332   saved_nOut = pNew->nOut;
112333   pNew->rSetup = 0;
112334   rLogSize = estLog(sqlite3LogEst(pProbe->aiRowEst[0]));
112335 
112336   /* Consider using a skip-scan if there are no WHERE clause constraints
112337   ** available for the left-most terms of the index, and if the average
112338   ** number of repeats in the left-most terms is at least 18.  The magic
112339   ** number 18 was found by experimentation to be the payoff point where
112340   ** skip-scan become faster than a full-scan.
112341   */
112342   if( pTerm==0
112343    && saved_nEq==saved_nSkip
112344    && saved_nEq+1<pProbe->nKeyCol
112345    && pProbe->aiRowEst[saved_nEq+1]>=18  /* TUNING: Minimum for skip-scan */
112346   ){
112347     LogEst nIter;
112348     pNew->u.btree.nEq++;
112349     pNew->u.btree.nSkip++;
112350     pNew->aLTerm[pNew->nLTerm++] = 0;
112351     pNew->wsFlags |= WHERE_SKIPSCAN;
112352     nIter = sqlite3LogEst(pProbe->aiRowEst[0]/pProbe->aiRowEst[saved_nEq+1]);
112353     whereLoopAddBtreeIndex(pBuilder, pSrc, pProbe, nIter);
112354   }
112355   for(; rc==SQLITE_OK && pTerm!=0; pTerm = whereScanNext(&scan)){
112356     int nIn = 0;
112357 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
112358     int nRecValid = pBuilder->nRecValid;
112359 #endif
112360     if( (pTerm->eOperator==WO_ISNULL || (pTerm->wtFlags&TERM_VNULL)!=0)
112361      && (iCol<0 || pSrc->pTab->aCol[iCol].notNull)
112362     ){
112363       continue; /* ignore IS [NOT] NULL constraints on NOT NULL columns */
112364     }
112365     if( pTerm->prereqRight & pNew->maskSelf ) continue;
112366 
112367     assert( pNew->nOut==saved_nOut );
112368 
112369     pNew->wsFlags = saved_wsFlags;
112370     pNew->u.btree.nEq = saved_nEq;
112371     pNew->nLTerm = saved_nLTerm;
112372     if( whereLoopResize(db, pNew, pNew->nLTerm+1) ) break; /* OOM */
112373     pNew->aLTerm[pNew->nLTerm++] = pTerm;
112374     pNew->prereq = (saved_prereq | pTerm->prereqRight) & ~pNew->maskSelf;
112375     pNew->rRun = rLogSize; /* Baseline cost is log2(N).  Adjustments below */
112376     if( pTerm->eOperator & WO_IN ){
112377       Expr *pExpr = pTerm->pExpr;
112378       pNew->wsFlags |= WHERE_COLUMN_IN;
112379       if( ExprHasProperty(pExpr, EP_xIsSelect) ){
112380         /* "x IN (SELECT ...)":  TUNING: the SELECT returns 25 rows */
112381         nIn = 46;  assert( 46==sqlite3LogEst(25) );
112382       }else if( ALWAYS(pExpr->x.pList && pExpr->x.pList->nExpr) ){
112383         /* "x IN (value, value, ...)" */
112384         nIn = sqlite3LogEst(pExpr->x.pList->nExpr);
112385       }
112386       pNew->rRun += nIn;
112387       pNew->u.btree.nEq++;
112388       pNew->nOut = nRowEst + nInMul + nIn;
112389     }else if( pTerm->eOperator & (WO_EQ) ){
112390       assert(
112391         (pNew->wsFlags & (WHERE_COLUMN_NULL|WHERE_COLUMN_IN|WHERE_SKIPSCAN))!=0
112392         || nInMul==0
112393       );
112394       pNew->wsFlags |= WHERE_COLUMN_EQ;
112395       if( iCol<0  
112396        || (pProbe->onError!=OE_None && nInMul==0
112397            && pNew->u.btree.nEq==pProbe->nKeyCol-1)
112398       ){
112399         assert( (pNew->wsFlags & WHERE_COLUMN_IN)==0 || iCol<0 );
112400         pNew->wsFlags |= WHERE_ONEROW;
112401       }
112402       pNew->u.btree.nEq++;
112403       pNew->nOut = nRowEst + nInMul;
112404     }else if( pTerm->eOperator & (WO_ISNULL) ){
112405       pNew->wsFlags |= WHERE_COLUMN_NULL;
112406       pNew->u.btree.nEq++;
112407       /* TUNING: IS NULL selects 2 rows */
112408       nIn = 10;  assert( 10==sqlite3LogEst(2) );
112409       pNew->nOut = nRowEst + nInMul + nIn;
112410     }else if( pTerm->eOperator & (WO_GT|WO_GE) ){
112411       testcase( pTerm->eOperator & WO_GT );
112412       testcase( pTerm->eOperator & WO_GE );
112413       pNew->wsFlags |= WHERE_COLUMN_RANGE|WHERE_BTM_LIMIT;
112414       pBtm = pTerm;
112415       pTop = 0;
112416     }else{
112417       assert( pTerm->eOperator & (WO_LT|WO_LE) );
112418       testcase( pTerm->eOperator & WO_LT );
112419       testcase( pTerm->eOperator & WO_LE );
112420       pNew->wsFlags |= WHERE_COLUMN_RANGE|WHERE_TOP_LIMIT;
112421       pTop = pTerm;
112422       pBtm = (pNew->wsFlags & WHERE_BTM_LIMIT)!=0 ?
112423                      pNew->aLTerm[pNew->nLTerm-2] : 0;
112424     }
112425     if( pNew->wsFlags & WHERE_COLUMN_RANGE ){
112426       /* Adjust nOut and rRun for STAT3 range values */
112427       assert( pNew->nOut==saved_nOut );
112428       whereRangeScanEst(pParse, pBuilder, pBtm, pTop, pNew);
112429     }
112430 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
112431     if( nInMul==0 
112432      && pProbe->nSample 
112433      && pNew->u.btree.nEq<=pProbe->nSampleCol
112434      && OptimizationEnabled(db, SQLITE_Stat3) 
112435     ){
112436       Expr *pExpr = pTerm->pExpr;
112437       tRowcnt nOut = 0;
112438       if( (pTerm->eOperator & (WO_EQ|WO_ISNULL))!=0 ){
112439         testcase( pTerm->eOperator & WO_EQ );
112440         testcase( pTerm->eOperator & WO_ISNULL );
112441         rc = whereEqualScanEst(pParse, pBuilder, pExpr->pRight, &nOut);
112442       }else if( (pTerm->eOperator & WO_IN)
112443              &&  !ExprHasProperty(pExpr, EP_xIsSelect)  ){
112444         rc = whereInScanEst(pParse, pBuilder, pExpr->x.pList, &nOut);
112445       }
112446       assert( nOut==0 || rc==SQLITE_OK );
112447       if( nOut ){
112448         pNew->nOut = sqlite3LogEst(nOut);
112449         if( pNew->nOut>saved_nOut ) pNew->nOut = saved_nOut;
112450       }
112451     }
112452 #endif
112453     if( (pNew->wsFlags & (WHERE_IDX_ONLY|WHERE_IPK))==0 ){
112454       /* Each row involves a step of the index, then a binary search of
112455       ** the main table */
112456       pNew->rRun =  sqlite3LogEstAdd(pNew->rRun,rLogSize>27 ? rLogSize-17 : 10);
112457     }
112458     /* Step cost for each output row */
112459     pNew->rRun = sqlite3LogEstAdd(pNew->rRun, pNew->nOut);
112460     whereLoopOutputAdjust(pBuilder->pWC, pNew);
112461     rc = whereLoopInsert(pBuilder, pNew);
112462     if( (pNew->wsFlags & WHERE_TOP_LIMIT)==0
112463      && pNew->u.btree.nEq<(pProbe->nKeyCol + (pProbe->zName!=0))
112464     ){
112465       whereLoopAddBtreeIndex(pBuilder, pSrc, pProbe, nInMul+nIn);
112466     }
112467     pNew->nOut = saved_nOut;
112468 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
112469     pBuilder->nRecValid = nRecValid;
112470 #endif
112471   }
112472   pNew->prereq = saved_prereq;
112473   pNew->u.btree.nEq = saved_nEq;
112474   pNew->u.btree.nSkip = saved_nSkip;
112475   pNew->wsFlags = saved_wsFlags;
112476   pNew->nOut = saved_nOut;
112477   pNew->nLTerm = saved_nLTerm;
112478   return rc;
112479 }
112480 
112481 /*
112482 ** Return True if it is possible that pIndex might be useful in
112483 ** implementing the ORDER BY clause in pBuilder.
112484 **
112485 ** Return False if pBuilder does not contain an ORDER BY clause or
112486 ** if there is no way for pIndex to be useful in implementing that
112487 ** ORDER BY clause.
112488 */
112489 static int indexMightHelpWithOrderBy(
112490   WhereLoopBuilder *pBuilder,
112491   Index *pIndex,
112492   int iCursor
112493 ){
112494   ExprList *pOB;
112495   int ii, jj;
112496 
112497   if( pIndex->bUnordered ) return 0;
112498   if( (pOB = pBuilder->pWInfo->pOrderBy)==0 ) return 0;
112499   for(ii=0; ii<pOB->nExpr; ii++){
112500     Expr *pExpr = sqlite3ExprSkipCollate(pOB->a[ii].pExpr);
112501     if( pExpr->op!=TK_COLUMN ) return 0;
112502     if( pExpr->iTable==iCursor ){
112503       for(jj=0; jj<pIndex->nKeyCol; jj++){
112504         if( pExpr->iColumn==pIndex->aiColumn[jj] ) return 1;
112505       }
112506     }
112507   }
112508   return 0;
112509 }
112510 
112511 /*
112512 ** Return a bitmask where 1s indicate that the corresponding column of
112513 ** the table is used by an index.  Only the first 63 columns are considered.
112514 */
112515 static Bitmask columnsInIndex(Index *pIdx){
112516   Bitmask m = 0;
112517   int j;
112518   for(j=pIdx->nColumn-1; j>=0; j--){
112519     int x = pIdx->aiColumn[j];
112520     if( x>=0 ){
112521       testcase( x==BMS-1 );
112522       testcase( x==BMS-2 );
112523       if( x<BMS-1 ) m |= MASKBIT(x);
112524     }
112525   }
112526   return m;
112527 }
112528 
112529 /* Check to see if a partial index with pPartIndexWhere can be used
112530 ** in the current query.  Return true if it can be and false if not.
112531 */
112532 static int whereUsablePartialIndex(int iTab, WhereClause *pWC, Expr *pWhere){
112533   int i;
112534   WhereTerm *pTerm;
112535   for(i=0, pTerm=pWC->a; i<pWC->nTerm; i++, pTerm++){
112536     if( sqlite3ExprImpliesExpr(pTerm->pExpr, pWhere, iTab) ) return 1;
112537   }
112538   return 0;
112539 }
112540 
112541 /*
112542 ** Add all WhereLoop objects for a single table of the join where the table
112543 ** is idenfied by pBuilder->pNew->iTab.  That table is guaranteed to be
112544 ** a b-tree table, not a virtual table.
112545 */
112546 static int whereLoopAddBtree(
112547   WhereLoopBuilder *pBuilder, /* WHERE clause information */
112548   Bitmask mExtra              /* Extra prerequesites for using this table */
112549 ){
112550   WhereInfo *pWInfo;          /* WHERE analysis context */
112551   Index *pProbe;              /* An index we are evaluating */
112552   Index sPk;                  /* A fake index object for the primary key */
112553   tRowcnt aiRowEstPk[2];      /* The aiRowEst[] value for the sPk index */
112554   i16 aiColumnPk = -1;        /* The aColumn[] value for the sPk index */
112555   SrcList *pTabList;          /* The FROM clause */
112556   struct SrcList_item *pSrc;  /* The FROM clause btree term to add */
112557   WhereLoop *pNew;            /* Template WhereLoop object */
112558   int rc = SQLITE_OK;         /* Return code */
112559   int iSortIdx = 1;           /* Index number */
112560   int b;                      /* A boolean value */
112561   LogEst rSize;               /* number of rows in the table */
112562   LogEst rLogSize;            /* Logarithm of the number of rows in the table */
112563   WhereClause *pWC;           /* The parsed WHERE clause */
112564   Table *pTab;                /* Table being queried */
112565   
112566   pNew = pBuilder->pNew;
112567   pWInfo = pBuilder->pWInfo;
112568   pTabList = pWInfo->pTabList;
112569   pSrc = pTabList->a + pNew->iTab;
112570   pTab = pSrc->pTab;
112571   pWC = pBuilder->pWC;
112572   assert( !IsVirtual(pSrc->pTab) );
112573 
112574   if( pSrc->pIndex ){
112575     /* An INDEXED BY clause specifies a particular index to use */
112576     pProbe = pSrc->pIndex;
112577   }else if( !HasRowid(pTab) ){
112578     pProbe = pTab->pIndex;
112579   }else{
112580     /* There is no INDEXED BY clause.  Create a fake Index object in local
112581     ** variable sPk to represent the rowid primary key index.  Make this
112582     ** fake index the first in a chain of Index objects with all of the real
112583     ** indices to follow */
112584     Index *pFirst;                  /* First of real indices on the table */
112585     memset(&sPk, 0, sizeof(Index));
112586     sPk.nKeyCol = 1;
112587     sPk.aiColumn = &aiColumnPk;
112588     sPk.aiRowEst = aiRowEstPk;
112589     sPk.onError = OE_Replace;
112590     sPk.pTable = pTab;
112591     aiRowEstPk[0] = pTab->nRowEst;
112592     aiRowEstPk[1] = 1;
112593     pFirst = pSrc->pTab->pIndex;
112594     if( pSrc->notIndexed==0 ){
112595       /* The real indices of the table are only considered if the
112596       ** NOT INDEXED qualifier is omitted from the FROM clause */
112597       sPk.pNext = pFirst;
112598     }
112599     pProbe = &sPk;
112600   }
112601   rSize = sqlite3LogEst(pTab->nRowEst);
112602   rLogSize = estLog(rSize);
112603 
112604 #ifndef SQLITE_OMIT_AUTOMATIC_INDEX
112605   /* Automatic indexes */
112606   if( !pBuilder->pOrSet
112607    && (pWInfo->pParse->db->flags & SQLITE_AutoIndex)!=0
112608    && pSrc->pIndex==0
112609    && !pSrc->viaCoroutine
112610    && !pSrc->notIndexed
112611    && HasRowid(pTab)
112612    && !pSrc->isCorrelated
112613   ){
112614     /* Generate auto-index WhereLoops */
112615     WhereTerm *pTerm;
112616     WhereTerm *pWCEnd = pWC->a + pWC->nTerm;
112617     for(pTerm=pWC->a; rc==SQLITE_OK && pTerm<pWCEnd; pTerm++){
112618       if( pTerm->prereqRight & pNew->maskSelf ) continue;
112619       if( termCanDriveIndex(pTerm, pSrc, 0) ){
112620         pNew->u.btree.nEq = 1;
112621         pNew->u.btree.nSkip = 0;
112622         pNew->u.btree.pIndex = 0;
112623         pNew->nLTerm = 1;
112624         pNew->aLTerm[0] = pTerm;
112625         /* TUNING: One-time cost for computing the automatic index is
112626         ** approximately 7*N*log2(N) where N is the number of rows in
112627         ** the table being indexed. */
112628         pNew->rSetup = rLogSize + rSize + 28;  assert( 28==sqlite3LogEst(7) );
112629         /* TUNING: Each index lookup yields 20 rows in the table.  This
112630         ** is more than the usual guess of 10 rows, since we have no way
112631         ** of knowning how selective the index will ultimately be.  It would
112632         ** not be unreasonable to make this value much larger. */
112633         pNew->nOut = 43;  assert( 43==sqlite3LogEst(20) );
112634         pNew->rRun = sqlite3LogEstAdd(rLogSize,pNew->nOut);
112635         pNew->wsFlags = WHERE_AUTO_INDEX;
112636         pNew->prereq = mExtra | pTerm->prereqRight;
112637         rc = whereLoopInsert(pBuilder, pNew);
112638       }
112639     }
112640   }
112641 #endif /* SQLITE_OMIT_AUTOMATIC_INDEX */
112642 
112643   /* Loop over all indices
112644   */
112645   for(; rc==SQLITE_OK && pProbe; pProbe=pProbe->pNext, iSortIdx++){
112646     if( pProbe->pPartIdxWhere!=0
112647      && !whereUsablePartialIndex(pNew->iTab, pWC, pProbe->pPartIdxWhere) ){
112648       continue;  /* Partial index inappropriate for this query */
112649     }
112650     pNew->u.btree.nEq = 0;
112651     pNew->u.btree.nSkip = 0;
112652     pNew->nLTerm = 0;
112653     pNew->iSortIdx = 0;
112654     pNew->rSetup = 0;
112655     pNew->prereq = mExtra;
112656     pNew->nOut = rSize;
112657     pNew->u.btree.pIndex = pProbe;
112658     b = indexMightHelpWithOrderBy(pBuilder, pProbe, pSrc->iCursor);
112659     /* The ONEPASS_DESIRED flags never occurs together with ORDER BY */
112660     assert( (pWInfo->wctrlFlags & WHERE_ONEPASS_DESIRED)==0 || b==0 );
112661     if( pProbe->tnum<=0 ){
112662       /* Integer primary key index */
112663       pNew->wsFlags = WHERE_IPK;
112664 
112665       /* Full table scan */
112666       pNew->iSortIdx = b ? iSortIdx : 0;
112667       /* TUNING: Cost of full table scan is 3*(N + log2(N)).
112668       **  +  The extra 3 factor is to encourage the use of indexed lookups
112669       **     over full scans.  FIXME */
112670       pNew->rRun = sqlite3LogEstAdd(rSize,rLogSize) + 16;
112671       whereLoopOutputAdjust(pWC, pNew);
112672       rc = whereLoopInsert(pBuilder, pNew);
112673       pNew->nOut = rSize;
112674       if( rc ) break;
112675     }else{
112676       Bitmask m;
112677       if( pProbe->isCovering ){
112678         pNew->wsFlags = WHERE_IDX_ONLY | WHERE_INDEXED;
112679         m = 0;
112680       }else{
112681         m = pSrc->colUsed & ~columnsInIndex(pProbe);
112682         pNew->wsFlags = (m==0) ? (WHERE_IDX_ONLY|WHERE_INDEXED) : WHERE_INDEXED;
112683       }
112684 
112685       /* Full scan via index */
112686       if( b
112687        || !HasRowid(pTab)
112688        || ( m==0
112689          && pProbe->bUnordered==0
112690          && (pProbe->szIdxRow<pTab->szTabRow)
112691          && (pWInfo->wctrlFlags & WHERE_ONEPASS_DESIRED)==0
112692          && sqlite3GlobalConfig.bUseCis
112693          && OptimizationEnabled(pWInfo->pParse->db, SQLITE_CoverIdxScan)
112694           )
112695       ){
112696         pNew->iSortIdx = b ? iSortIdx : 0;
112697         if( m==0 ){
112698           /* TUNING: Cost of a covering index scan is K*(N + log2(N)).
112699           **  +  The extra factor K of between 1.1 and 3.0 that depends
112700           **     on the relative sizes of the table and the index.  K
112701           **     is smaller for smaller indices, thus favoring them.
112702           */
112703           pNew->rRun = sqlite3LogEstAdd(rSize,rLogSize) + 1 +
112704                         (15*pProbe->szIdxRow)/pTab->szTabRow;
112705         }else{
112706           /* TUNING: Cost of scanning a non-covering index is (N+1)*log2(N)
112707           ** which we will simplify to just N*log2(N) */
112708           pNew->rRun = rSize + rLogSize;
112709         }
112710         whereLoopOutputAdjust(pWC, pNew);
112711         rc = whereLoopInsert(pBuilder, pNew);
112712         pNew->nOut = rSize;
112713         if( rc ) break;
112714       }
112715     }
112716 
112717     rc = whereLoopAddBtreeIndex(pBuilder, pSrc, pProbe, 0);
112718 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
112719     sqlite3Stat4ProbeFree(pBuilder->pRec);
112720     pBuilder->nRecValid = 0;
112721     pBuilder->pRec = 0;
112722 #endif
112723 
112724     /* If there was an INDEXED BY clause, then only that one index is
112725     ** considered. */
112726     if( pSrc->pIndex ) break;
112727   }
112728   return rc;
112729 }
112730 
112731 #ifndef SQLITE_OMIT_VIRTUALTABLE
112732 /*
112733 ** Add all WhereLoop objects for a table of the join identified by
112734 ** pBuilder->pNew->iTab.  That table is guaranteed to be a virtual table.
112735 */
112736 static int whereLoopAddVirtual(
112737   WhereLoopBuilder *pBuilder,  /* WHERE clause information */
112738   Bitmask mExtra
112739 ){
112740   WhereInfo *pWInfo;           /* WHERE analysis context */
112741   Parse *pParse;               /* The parsing context */
112742   WhereClause *pWC;            /* The WHERE clause */
112743   struct SrcList_item *pSrc;   /* The FROM clause term to search */
112744   Table *pTab;
112745   sqlite3 *db;
112746   sqlite3_index_info *pIdxInfo;
112747   struct sqlite3_index_constraint *pIdxCons;
112748   struct sqlite3_index_constraint_usage *pUsage;
112749   WhereTerm *pTerm;
112750   int i, j;
112751   int iTerm, mxTerm;
112752   int nConstraint;
112753   int seenIn = 0;              /* True if an IN operator is seen */
112754   int seenVar = 0;             /* True if a non-constant constraint is seen */
112755   int iPhase;                  /* 0: const w/o IN, 1: const, 2: no IN,  2: IN */
112756   WhereLoop *pNew;
112757   int rc = SQLITE_OK;
112758 
112759   pWInfo = pBuilder->pWInfo;
112760   pParse = pWInfo->pParse;
112761   db = pParse->db;
112762   pWC = pBuilder->pWC;
112763   pNew = pBuilder->pNew;
112764   pSrc = &pWInfo->pTabList->a[pNew->iTab];
112765   pTab = pSrc->pTab;
112766   assert( IsVirtual(pTab) );
112767   pIdxInfo = allocateIndexInfo(pParse, pWC, pSrc, pBuilder->pOrderBy);
112768   if( pIdxInfo==0 ) return SQLITE_NOMEM;
112769   pNew->prereq = 0;
112770   pNew->rSetup = 0;
112771   pNew->wsFlags = WHERE_VIRTUALTABLE;
112772   pNew->nLTerm = 0;
112773   pNew->u.vtab.needFree = 0;
112774   pUsage = pIdxInfo->aConstraintUsage;
112775   nConstraint = pIdxInfo->nConstraint;
112776   if( whereLoopResize(db, pNew, nConstraint) ){
112777     sqlite3DbFree(db, pIdxInfo);
112778     return SQLITE_NOMEM;
112779   }
112780 
112781   for(iPhase=0; iPhase<=3; iPhase++){
112782     if( !seenIn && (iPhase&1)!=0 ){
112783       iPhase++;
112784       if( iPhase>3 ) break;
112785     }
112786     if( !seenVar && iPhase>1 ) break;
112787     pIdxCons = *(struct sqlite3_index_constraint**)&pIdxInfo->aConstraint;
112788     for(i=0; i<pIdxInfo->nConstraint; i++, pIdxCons++){
112789       j = pIdxCons->iTermOffset;
112790       pTerm = &pWC->a[j];
112791       switch( iPhase ){
112792         case 0:    /* Constants without IN operator */
112793           pIdxCons->usable = 0;
112794           if( (pTerm->eOperator & WO_IN)!=0 ){
112795             seenIn = 1;
112796           }
112797           if( pTerm->prereqRight!=0 ){
112798             seenVar = 1;
112799           }else if( (pTerm->eOperator & WO_IN)==0 ){
112800             pIdxCons->usable = 1;
112801           }
112802           break;
112803         case 1:    /* Constants with IN operators */
112804           assert( seenIn );
112805           pIdxCons->usable = (pTerm->prereqRight==0);
112806           break;
112807         case 2:    /* Variables without IN */
112808           assert( seenVar );
112809           pIdxCons->usable = (pTerm->eOperator & WO_IN)==0;
112810           break;
112811         default:   /* Variables with IN */
112812           assert( seenVar && seenIn );
112813           pIdxCons->usable = 1;
112814           break;
112815       }
112816     }
112817     memset(pUsage, 0, sizeof(pUsage[0])*pIdxInfo->nConstraint);
112818     if( pIdxInfo->needToFreeIdxStr ) sqlite3_free(pIdxInfo->idxStr);
112819     pIdxInfo->idxStr = 0;
112820     pIdxInfo->idxNum = 0;
112821     pIdxInfo->needToFreeIdxStr = 0;
112822     pIdxInfo->orderByConsumed = 0;
112823     pIdxInfo->estimatedCost = SQLITE_BIG_DBL / (double)2;
112824     pIdxInfo->estimatedRows = 25;
112825     rc = vtabBestIndex(pParse, pTab, pIdxInfo);
112826     if( rc ) goto whereLoopAddVtab_exit;
112827     pIdxCons = *(struct sqlite3_index_constraint**)&pIdxInfo->aConstraint;
112828     pNew->prereq = mExtra;
112829     mxTerm = -1;
112830     assert( pNew->nLSlot>=nConstraint );
112831     for(i=0; i<nConstraint; i++) pNew->aLTerm[i] = 0;
112832     pNew->u.vtab.omitMask = 0;
112833     for(i=0; i<nConstraint; i++, pIdxCons++){
112834       if( (iTerm = pUsage[i].argvIndex - 1)>=0 ){
112835         j = pIdxCons->iTermOffset;
112836         if( iTerm>=nConstraint
112837          || j<0
112838          || j>=pWC->nTerm
112839          || pNew->aLTerm[iTerm]!=0
112840         ){
112841           rc = SQLITE_ERROR;
112842           sqlite3ErrorMsg(pParse, "%s.xBestIndex() malfunction", pTab->zName);
112843           goto whereLoopAddVtab_exit;
112844         }
112845         testcase( iTerm==nConstraint-1 );
112846         testcase( j==0 );
112847         testcase( j==pWC->nTerm-1 );
112848         pTerm = &pWC->a[j];
112849         pNew->prereq |= pTerm->prereqRight;
112850         assert( iTerm<pNew->nLSlot );
112851         pNew->aLTerm[iTerm] = pTerm;
112852         if( iTerm>mxTerm ) mxTerm = iTerm;
112853         testcase( iTerm==15 );
112854         testcase( iTerm==16 );
112855         if( iTerm<16 && pUsage[i].omit ) pNew->u.vtab.omitMask |= 1<<iTerm;
112856         if( (pTerm->eOperator & WO_IN)!=0 ){
112857           if( pUsage[i].omit==0 ){
112858             /* Do not attempt to use an IN constraint if the virtual table
112859             ** says that the equivalent EQ constraint cannot be safely omitted.
112860             ** If we do attempt to use such a constraint, some rows might be
112861             ** repeated in the output. */
112862             break;
112863           }
112864           /* A virtual table that is constrained by an IN clause may not
112865           ** consume the ORDER BY clause because (1) the order of IN terms
112866           ** is not necessarily related to the order of output terms and
112867           ** (2) Multiple outputs from a single IN value will not merge
112868           ** together.  */
112869           pIdxInfo->orderByConsumed = 0;
112870         }
112871       }
112872     }
112873     if( i>=nConstraint ){
112874       pNew->nLTerm = mxTerm+1;
112875       assert( pNew->nLTerm<=pNew->nLSlot );
112876       pNew->u.vtab.idxNum = pIdxInfo->idxNum;
112877       pNew->u.vtab.needFree = pIdxInfo->needToFreeIdxStr;
112878       pIdxInfo->needToFreeIdxStr = 0;
112879       pNew->u.vtab.idxStr = pIdxInfo->idxStr;
112880       pNew->u.vtab.isOrdered = (u8)((pIdxInfo->nOrderBy!=0)
112881                                      && pIdxInfo->orderByConsumed);
112882       pNew->rSetup = 0;
112883       pNew->rRun = sqlite3LogEstFromDouble(pIdxInfo->estimatedCost);
112884       pNew->nOut = sqlite3LogEst(pIdxInfo->estimatedRows);
112885       whereLoopInsert(pBuilder, pNew);
112886       if( pNew->u.vtab.needFree ){
112887         sqlite3_free(pNew->u.vtab.idxStr);
112888         pNew->u.vtab.needFree = 0;
112889       }
112890     }
112891   }  
112892 
112893 whereLoopAddVtab_exit:
112894   if( pIdxInfo->needToFreeIdxStr ) sqlite3_free(pIdxInfo->idxStr);
112895   sqlite3DbFree(db, pIdxInfo);
112896   return rc;
112897 }
112898 #endif /* SQLITE_OMIT_VIRTUALTABLE */
112899 
112900 /*
112901 ** Add WhereLoop entries to handle OR terms.  This works for either
112902 ** btrees or virtual tables.
112903 */
112904 static int whereLoopAddOr(WhereLoopBuilder *pBuilder, Bitmask mExtra){
112905   WhereInfo *pWInfo = pBuilder->pWInfo;
112906   WhereClause *pWC;
112907   WhereLoop *pNew;
112908   WhereTerm *pTerm, *pWCEnd;
112909   int rc = SQLITE_OK;
112910   int iCur;
112911   WhereClause tempWC;
112912   WhereLoopBuilder sSubBuild;
112913   WhereOrSet sSum, sCur, sPrev;
112914   struct SrcList_item *pItem;
112915   
112916   pWC = pBuilder->pWC;
112917   if( pWInfo->wctrlFlags & WHERE_AND_ONLY ) return SQLITE_OK;
112918   pWCEnd = pWC->a + pWC->nTerm;
112919   pNew = pBuilder->pNew;
112920   memset(&sSum, 0, sizeof(sSum));
112921   pItem = pWInfo->pTabList->a + pNew->iTab;
112922   if( !HasRowid(pItem->pTab) ) return SQLITE_OK;
112923   iCur = pItem->iCursor;
112924 
112925   for(pTerm=pWC->a; pTerm<pWCEnd && rc==SQLITE_OK; pTerm++){
112926     if( (pTerm->eOperator & WO_OR)!=0
112927      && (pTerm->u.pOrInfo->indexable & pNew->maskSelf)!=0 
112928     ){
112929       WhereClause * const pOrWC = &pTerm->u.pOrInfo->wc;
112930       WhereTerm * const pOrWCEnd = &pOrWC->a[pOrWC->nTerm];
112931       WhereTerm *pOrTerm;
112932       int once = 1;
112933       int i, j;
112934     
112935       sSubBuild = *pBuilder;
112936       sSubBuild.pOrderBy = 0;
112937       sSubBuild.pOrSet = &sCur;
112938 
112939       for(pOrTerm=pOrWC->a; pOrTerm<pOrWCEnd; pOrTerm++){
112940         if( (pOrTerm->eOperator & WO_AND)!=0 ){
112941           sSubBuild.pWC = &pOrTerm->u.pAndInfo->wc;
112942         }else if( pOrTerm->leftCursor==iCur ){
112943           tempWC.pWInfo = pWC->pWInfo;
112944           tempWC.pOuter = pWC;
112945           tempWC.op = TK_AND;
112946           tempWC.nTerm = 1;
112947           tempWC.a = pOrTerm;
112948           sSubBuild.pWC = &tempWC;
112949         }else{
112950           continue;
112951         }
112952         sCur.n = 0;
112953 #ifndef SQLITE_OMIT_VIRTUALTABLE
112954         if( IsVirtual(pItem->pTab) ){
112955           rc = whereLoopAddVirtual(&sSubBuild, mExtra);
112956         }else
112957 #endif
112958         {
112959           rc = whereLoopAddBtree(&sSubBuild, mExtra);
112960         }
112961         assert( rc==SQLITE_OK || sCur.n==0 );
112962         if( sCur.n==0 ){
112963           sSum.n = 0;
112964           break;
112965         }else if( once ){
112966           whereOrMove(&sSum, &sCur);
112967           once = 0;
112968         }else{
112969           whereOrMove(&sPrev, &sSum);
112970           sSum.n = 0;
112971           for(i=0; i<sPrev.n; i++){
112972             for(j=0; j<sCur.n; j++){
112973               whereOrInsert(&sSum, sPrev.a[i].prereq | sCur.a[j].prereq,
112974                             sqlite3LogEstAdd(sPrev.a[i].rRun, sCur.a[j].rRun),
112975                             sqlite3LogEstAdd(sPrev.a[i].nOut, sCur.a[j].nOut));
112976             }
112977           }
112978         }
112979       }
112980       pNew->nLTerm = 1;
112981       pNew->aLTerm[0] = pTerm;
112982       pNew->wsFlags = WHERE_MULTI_OR;
112983       pNew->rSetup = 0;
112984       pNew->iSortIdx = 0;
112985       memset(&pNew->u, 0, sizeof(pNew->u));
112986       for(i=0; rc==SQLITE_OK && i<sSum.n; i++){
112987         /* TUNING: Multiple by 3.5 for the secondary table lookup */
112988         pNew->rRun = sSum.a[i].rRun + 18;
112989         pNew->nOut = sSum.a[i].nOut;
112990         pNew->prereq = sSum.a[i].prereq;
112991         rc = whereLoopInsert(pBuilder, pNew);
112992       }
112993     }
112994   }
112995   return rc;
112996 }
112997 
112998 /*
112999 ** Add all WhereLoop objects for all tables 
113000 */
113001 static int whereLoopAddAll(WhereLoopBuilder *pBuilder){
113002   WhereInfo *pWInfo = pBuilder->pWInfo;
113003   Bitmask mExtra = 0;
113004   Bitmask mPrior = 0;
113005   int iTab;
113006   SrcList *pTabList = pWInfo->pTabList;
113007   struct SrcList_item *pItem;
113008   sqlite3 *db = pWInfo->pParse->db;
113009   int nTabList = pWInfo->nLevel;
113010   int rc = SQLITE_OK;
113011   u8 priorJoinType = 0;
113012   WhereLoop *pNew;
113013 
113014   /* Loop over the tables in the join, from left to right */
113015   pNew = pBuilder->pNew;
113016   whereLoopInit(pNew);
113017   for(iTab=0, pItem=pTabList->a; iTab<nTabList; iTab++, pItem++){
113018     pNew->iTab = iTab;
113019     pNew->maskSelf = getMask(&pWInfo->sMaskSet, pItem->iCursor);
113020     if( ((pItem->jointype|priorJoinType) & (JT_LEFT|JT_CROSS))!=0 ){
113021       mExtra = mPrior;
113022     }
113023     priorJoinType = pItem->jointype;
113024     if( IsVirtual(pItem->pTab) ){
113025       rc = whereLoopAddVirtual(pBuilder, mExtra);
113026     }else{
113027       rc = whereLoopAddBtree(pBuilder, mExtra);
113028     }
113029     if( rc==SQLITE_OK ){
113030       rc = whereLoopAddOr(pBuilder, mExtra);
113031     }
113032     mPrior |= pNew->maskSelf;
113033     if( rc || db->mallocFailed ) break;
113034   }
113035   whereLoopClear(db, pNew);
113036   return rc;
113037 }
113038 
113039 /*
113040 ** Examine a WherePath (with the addition of the extra WhereLoop of the 5th
113041 ** parameters) to see if it outputs rows in the requested ORDER BY
113042 ** (or GROUP BY) without requiring a separate sort operation.  Return:
113043 ** 
113044 **    0:  ORDER BY is not satisfied.  Sorting required
113045 **    1:  ORDER BY is satisfied.      Omit sorting
113046 **   -1:  Unknown at this time
113047 **
113048 ** Note that processing for WHERE_GROUPBY and WHERE_DISTINCTBY is not as
113049 ** strict.  With GROUP BY and DISTINCT the only requirement is that
113050 ** equivalent rows appear immediately adjacent to one another.  GROUP BY
113051 ** and DISTINT do not require rows to appear in any particular order as long
113052 ** as equivelent rows are grouped together.  Thus for GROUP BY and DISTINCT
113053 ** the pOrderBy terms can be matched in any order.  With ORDER BY, the 
113054 ** pOrderBy terms must be matched in strict left-to-right order.
113055 */
113056 static int wherePathSatisfiesOrderBy(
113057   WhereInfo *pWInfo,    /* The WHERE clause */
113058   ExprList *pOrderBy,   /* ORDER BY or GROUP BY or DISTINCT clause to check */
113059   WherePath *pPath,     /* The WherePath to check */
113060   u16 wctrlFlags,       /* Might contain WHERE_GROUPBY or WHERE_DISTINCTBY */
113061   u16 nLoop,            /* Number of entries in pPath->aLoop[] */
113062   WhereLoop *pLast,     /* Add this WhereLoop to the end of pPath->aLoop[] */
113063   Bitmask *pRevMask     /* OUT: Mask of WhereLoops to run in reverse order */
113064 ){
113065   u8 revSet;            /* True if rev is known */
113066   u8 rev;               /* Composite sort order */
113067   u8 revIdx;            /* Index sort order */
113068   u8 isOrderDistinct;   /* All prior WhereLoops are order-distinct */
113069   u8 distinctColumns;   /* True if the loop has UNIQUE NOT NULL columns */
113070   u8 isMatch;           /* iColumn matches a term of the ORDER BY clause */
113071   u16 nKeyCol;          /* Number of key columns in pIndex */
113072   u16 nColumn;          /* Total number of ordered columns in the index */
113073   u16 nOrderBy;         /* Number terms in the ORDER BY clause */
113074   int iLoop;            /* Index of WhereLoop in pPath being processed */
113075   int i, j;             /* Loop counters */
113076   int iCur;             /* Cursor number for current WhereLoop */
113077   int iColumn;          /* A column number within table iCur */
113078   WhereLoop *pLoop = 0; /* Current WhereLoop being processed. */
113079   WhereTerm *pTerm;     /* A single term of the WHERE clause */
113080   Expr *pOBExpr;        /* An expression from the ORDER BY clause */
113081   CollSeq *pColl;       /* COLLATE function from an ORDER BY clause term */
113082   Index *pIndex;        /* The index associated with pLoop */
113083   sqlite3 *db = pWInfo->pParse->db;  /* Database connection */
113084   Bitmask obSat = 0;    /* Mask of ORDER BY terms satisfied so far */
113085   Bitmask obDone;       /* Mask of all ORDER BY terms */
113086   Bitmask orderDistinctMask;  /* Mask of all well-ordered loops */
113087   Bitmask ready;              /* Mask of inner loops */
113088 
113089   /*
113090   ** We say the WhereLoop is "one-row" if it generates no more than one
113091   ** row of output.  A WhereLoop is one-row if all of the following are true:
113092   **  (a) All index columns match with WHERE_COLUMN_EQ.
113093   **  (b) The index is unique
113094   ** Any WhereLoop with an WHERE_COLUMN_EQ constraint on the rowid is one-row.
113095   ** Every one-row WhereLoop will have the WHERE_ONEROW bit set in wsFlags.
113096   **
113097   ** We say the WhereLoop is "order-distinct" if the set of columns from
113098   ** that WhereLoop that are in the ORDER BY clause are different for every
113099   ** row of the WhereLoop.  Every one-row WhereLoop is automatically
113100   ** order-distinct.   A WhereLoop that has no columns in the ORDER BY clause
113101   ** is not order-distinct. To be order-distinct is not quite the same as being
113102   ** UNIQUE since a UNIQUE column or index can have multiple rows that 
113103   ** are NULL and NULL values are equivalent for the purpose of order-distinct.
113104   ** To be order-distinct, the columns must be UNIQUE and NOT NULL.
113105   **
113106   ** The rowid for a table is always UNIQUE and NOT NULL so whenever the
113107   ** rowid appears in the ORDER BY clause, the corresponding WhereLoop is
113108   ** automatically order-distinct.
113109   */
113110 
113111   assert( pOrderBy!=0 );
113112 
113113   /* Sortability of virtual tables is determined by the xBestIndex method
113114   ** of the virtual table itself */
113115   if( pLast->wsFlags & WHERE_VIRTUALTABLE ){
113116     testcase( nLoop>0 );  /* True when outer loops are one-row and match 
113117                           ** no ORDER BY terms */
113118     return pLast->u.vtab.isOrdered;
113119   }
113120   if( nLoop && OptimizationDisabled(db, SQLITE_OrderByIdxJoin) ) return 0;
113121 
113122   nOrderBy = pOrderBy->nExpr;
113123   testcase( nOrderBy==BMS-1 );
113124   if( nOrderBy>BMS-1 ) return 0;  /* Cannot optimize overly large ORDER BYs */
113125   isOrderDistinct = 1;
113126   obDone = MASKBIT(nOrderBy)-1;
113127   orderDistinctMask = 0;
113128   ready = 0;
113129   for(iLoop=0; isOrderDistinct && obSat<obDone && iLoop<=nLoop; iLoop++){
113130     if( iLoop>0 ) ready |= pLoop->maskSelf;
113131     pLoop = iLoop<nLoop ? pPath->aLoop[iLoop] : pLast;
113132     assert( (pLoop->wsFlags & WHERE_VIRTUALTABLE)==0 );
113133     iCur = pWInfo->pTabList->a[pLoop->iTab].iCursor;
113134 
113135     /* Mark off any ORDER BY term X that is a column in the table of
113136     ** the current loop for which there is term in the WHERE
113137     ** clause of the form X IS NULL or X=? that reference only outer
113138     ** loops.
113139     */
113140     for(i=0; i<nOrderBy; i++){
113141       if( MASKBIT(i) & obSat ) continue;
113142       pOBExpr = sqlite3ExprSkipCollate(pOrderBy->a[i].pExpr);
113143       if( pOBExpr->op!=TK_COLUMN ) continue;
113144       if( pOBExpr->iTable!=iCur ) continue;
113145       pTerm = findTerm(&pWInfo->sWC, iCur, pOBExpr->iColumn,
113146                        ~ready, WO_EQ|WO_ISNULL, 0);
113147       if( pTerm==0 ) continue;
113148       if( (pTerm->eOperator&WO_EQ)!=0 && pOBExpr->iColumn>=0 ){
113149         const char *z1, *z2;
113150         pColl = sqlite3ExprCollSeq(pWInfo->pParse, pOrderBy->a[i].pExpr);
113151         if( !pColl ) pColl = db->pDfltColl;
113152         z1 = pColl->zName;
113153         pColl = sqlite3ExprCollSeq(pWInfo->pParse, pTerm->pExpr);
113154         if( !pColl ) pColl = db->pDfltColl;
113155         z2 = pColl->zName;
113156         if( sqlite3StrICmp(z1, z2)!=0 ) continue;
113157       }
113158       obSat |= MASKBIT(i);
113159     }
113160 
113161     if( (pLoop->wsFlags & WHERE_ONEROW)==0 ){
113162       if( pLoop->wsFlags & WHERE_IPK ){
113163         pIndex = 0;
113164         nKeyCol = 0;
113165         nColumn = 1;
113166       }else if( (pIndex = pLoop->u.btree.pIndex)==0 || pIndex->bUnordered ){
113167         return 0;
113168       }else{
113169         nKeyCol = pIndex->nKeyCol;
113170         nColumn = pIndex->nColumn;
113171         assert( nColumn==nKeyCol+1 || !HasRowid(pIndex->pTable) );
113172         assert( pIndex->aiColumn[nColumn-1]==(-1) || !HasRowid(pIndex->pTable));
113173         isOrderDistinct = pIndex->onError!=OE_None;
113174       }
113175 
113176       /* Loop through all columns of the index and deal with the ones
113177       ** that are not constrained by == or IN.
113178       */
113179       rev = revSet = 0;
113180       distinctColumns = 0;
113181       for(j=0; j<nColumn; j++){
113182         u8 bOnce;   /* True to run the ORDER BY search loop */
113183 
113184         /* Skip over == and IS NULL terms */
113185         if( j<pLoop->u.btree.nEq
113186          && pLoop->u.btree.nSkip==0
113187          && ((i = pLoop->aLTerm[j]->eOperator) & (WO_EQ|WO_ISNULL))!=0
113188         ){
113189           if( i & WO_ISNULL ){
113190             testcase( isOrderDistinct );
113191             isOrderDistinct = 0;
113192           }
113193           continue;  
113194         }
113195 
113196         /* Get the column number in the table (iColumn) and sort order
113197         ** (revIdx) for the j-th column of the index.
113198         */
113199         if( pIndex ){
113200           iColumn = pIndex->aiColumn[j];
113201           revIdx = pIndex->aSortOrder[j];
113202           if( iColumn==pIndex->pTable->iPKey ) iColumn = -1;
113203         }else{
113204           iColumn = -1;
113205           revIdx = 0;
113206         }
113207 
113208         /* An unconstrained column that might be NULL means that this
113209         ** WhereLoop is not well-ordered
113210         */
113211         if( isOrderDistinct
113212          && iColumn>=0
113213          && j>=pLoop->u.btree.nEq
113214          && pIndex->pTable->aCol[iColumn].notNull==0
113215         ){
113216           isOrderDistinct = 0;
113217         }
113218 
113219         /* Find the ORDER BY term that corresponds to the j-th column
113220         ** of the index and and mark that ORDER BY term off 
113221         */
113222         bOnce = 1;
113223         isMatch = 0;
113224         for(i=0; bOnce && i<nOrderBy; i++){
113225           if( MASKBIT(i) & obSat ) continue;
113226           pOBExpr = sqlite3ExprSkipCollate(pOrderBy->a[i].pExpr);
113227           testcase( wctrlFlags & WHERE_GROUPBY );
113228           testcase( wctrlFlags & WHERE_DISTINCTBY );
113229           if( (wctrlFlags & (WHERE_GROUPBY|WHERE_DISTINCTBY))==0 ) bOnce = 0;
113230           if( pOBExpr->op!=TK_COLUMN ) continue;
113231           if( pOBExpr->iTable!=iCur ) continue;
113232           if( pOBExpr->iColumn!=iColumn ) continue;
113233           if( iColumn>=0 ){
113234             pColl = sqlite3ExprCollSeq(pWInfo->pParse, pOrderBy->a[i].pExpr);
113235             if( !pColl ) pColl = db->pDfltColl;
113236             if( sqlite3StrICmp(pColl->zName, pIndex->azColl[j])!=0 ) continue;
113237           }
113238           isMatch = 1;
113239           break;
113240         }
113241         if( isMatch ){
113242           if( iColumn<0 ){
113243             testcase( distinctColumns==0 );
113244             distinctColumns = 1;
113245           }
113246           obSat |= MASKBIT(i);
113247           if( (pWInfo->wctrlFlags & WHERE_GROUPBY)==0 ){
113248             /* Make sure the sort order is compatible in an ORDER BY clause.
113249             ** Sort order is irrelevant for a GROUP BY clause. */
113250             if( revSet ){
113251               if( (rev ^ revIdx)!=pOrderBy->a[i].sortOrder ) return 0;
113252             }else{
113253               rev = revIdx ^ pOrderBy->a[i].sortOrder;
113254               if( rev ) *pRevMask |= MASKBIT(iLoop);
113255               revSet = 1;
113256             }
113257           }
113258         }else{
113259           /* No match found */
113260           if( j==0 || j<nKeyCol ){
113261             testcase( isOrderDistinct!=0 );
113262             isOrderDistinct = 0;
113263           }
113264           break;
113265         }
113266       } /* end Loop over all index columns */
113267       if( distinctColumns ){
113268         testcase( isOrderDistinct==0 );
113269         isOrderDistinct = 1;
113270       }
113271     } /* end-if not one-row */
113272 
113273     /* Mark off any other ORDER BY terms that reference pLoop */
113274     if( isOrderDistinct ){
113275       orderDistinctMask |= pLoop->maskSelf;
113276       for(i=0; i<nOrderBy; i++){
113277         Expr *p;
113278         if( MASKBIT(i) & obSat ) continue;
113279         p = pOrderBy->a[i].pExpr;
113280         if( (exprTableUsage(&pWInfo->sMaskSet, p)&~orderDistinctMask)==0 ){
113281           obSat |= MASKBIT(i);
113282         }
113283       }
113284     }
113285   } /* End the loop over all WhereLoops from outer-most down to inner-most */
113286   if( obSat==obDone ) return 1;
113287   if( !isOrderDistinct ) return 0;
113288   return -1;
113289 }
113290 
113291 #ifdef WHERETRACE_ENABLED
113292 /* For debugging use only: */
113293 static const char *wherePathName(WherePath *pPath, int nLoop, WhereLoop *pLast){
113294   static char zName[65];
113295   int i;
113296   for(i=0; i<nLoop; i++){ zName[i] = pPath->aLoop[i]->cId; }
113297   if( pLast ) zName[i++] = pLast->cId;
113298   zName[i] = 0;
113299   return zName;
113300 }
113301 #endif
113302 
113303 
113304 /*
113305 ** Given the list of WhereLoop objects at pWInfo->pLoops, this routine
113306 ** attempts to find the lowest cost path that visits each WhereLoop
113307 ** once.  This path is then loaded into the pWInfo->a[].pWLoop fields.
113308 **
113309 ** Assume that the total number of output rows that will need to be sorted
113310 ** will be nRowEst (in the 10*log2 representation).  Or, ignore sorting
113311 ** costs if nRowEst==0.
113312 **
113313 ** Return SQLITE_OK on success or SQLITE_NOMEM of a memory allocation
113314 ** error occurs.
113315 */
113316 static int wherePathSolver(WhereInfo *pWInfo, LogEst nRowEst){
113317   int mxChoice;             /* Maximum number of simultaneous paths tracked */
113318   int nLoop;                /* Number of terms in the join */
113319   Parse *pParse;            /* Parsing context */
113320   sqlite3 *db;              /* The database connection */
113321   int iLoop;                /* Loop counter over the terms of the join */
113322   int ii, jj;               /* Loop counters */
113323   int mxI = 0;              /* Index of next entry to replace */
113324   LogEst rCost;             /* Cost of a path */
113325   LogEst nOut;              /* Number of outputs */
113326   LogEst mxCost = 0;        /* Maximum cost of a set of paths */
113327   LogEst mxOut = 0;         /* Maximum nOut value on the set of paths */
113328   LogEst rSortCost;         /* Cost to do a sort */
113329   int nTo, nFrom;           /* Number of valid entries in aTo[] and aFrom[] */
113330   WherePath *aFrom;         /* All nFrom paths at the previous level */
113331   WherePath *aTo;           /* The nTo best paths at the current level */
113332   WherePath *pFrom;         /* An element of aFrom[] that we are working on */
113333   WherePath *pTo;           /* An element of aTo[] that we are working on */
113334   WhereLoop *pWLoop;        /* One of the WhereLoop objects */
113335   WhereLoop **pX;           /* Used to divy up the pSpace memory */
113336   char *pSpace;             /* Temporary memory used by this routine */
113337 
113338   pParse = pWInfo->pParse;
113339   db = pParse->db;
113340   nLoop = pWInfo->nLevel;
113341   /* TUNING: For simple queries, only the best path is tracked.
113342   ** For 2-way joins, the 5 best paths are followed.
113343   ** For joins of 3 or more tables, track the 10 best paths */
113344   mxChoice = (nLoop==1) ? 1 : (nLoop==2 ? 5 : 10);
113345   assert( nLoop<=pWInfo->pTabList->nSrc );
113346   WHERETRACE(0x002, ("---- begin solver\n"));
113347 
113348   /* Allocate and initialize space for aTo and aFrom */
113349   ii = (sizeof(WherePath)+sizeof(WhereLoop*)*nLoop)*mxChoice*2;
113350   pSpace = sqlite3DbMallocRaw(db, ii);
113351   if( pSpace==0 ) return SQLITE_NOMEM;
113352   aTo = (WherePath*)pSpace;
113353   aFrom = aTo+mxChoice;
113354   memset(aFrom, 0, sizeof(aFrom[0]));
113355   pX = (WhereLoop**)(aFrom+mxChoice);
113356   for(ii=mxChoice*2, pFrom=aTo; ii>0; ii--, pFrom++, pX += nLoop){
113357     pFrom->aLoop = pX;
113358   }
113359 
113360   /* Seed the search with a single WherePath containing zero WhereLoops.
113361   **
113362   ** TUNING: Do not let the number of iterations go above 25.  If the cost
113363   ** of computing an automatic index is not paid back within the first 25
113364   ** rows, then do not use the automatic index. */
113365   aFrom[0].nRow = MIN(pParse->nQueryLoop, 46);  assert( 46==sqlite3LogEst(25) );
113366   nFrom = 1;
113367 
113368   /* Precompute the cost of sorting the final result set, if the caller
113369   ** to sqlite3WhereBegin() was concerned about sorting */
113370   rSortCost = 0;
113371   if( pWInfo->pOrderBy==0 || nRowEst==0 ){
113372     aFrom[0].isOrderedValid = 1;
113373   }else{
113374     /* TUNING: Estimated cost of sorting is 48*N*log2(N) where N is the
113375     ** number of output rows. The 48 is the expected size of a row to sort. 
113376     ** FIXME:  compute a better estimate of the 48 multiplier based on the
113377     ** result set expressions. */
113378     rSortCost = nRowEst + estLog(nRowEst);
113379     WHERETRACE(0x002,("---- sort cost=%-3d\n", rSortCost));
113380   }
113381 
113382   /* Compute successively longer WherePaths using the previous generation
113383   ** of WherePaths as the basis for the next.  Keep track of the mxChoice
113384   ** best paths at each generation */
113385   for(iLoop=0; iLoop<nLoop; iLoop++){
113386     nTo = 0;
113387     for(ii=0, pFrom=aFrom; ii<nFrom; ii++, pFrom++){
113388       for(pWLoop=pWInfo->pLoops; pWLoop; pWLoop=pWLoop->pNextLoop){
113389         Bitmask maskNew;
113390         Bitmask revMask = 0;
113391         u8 isOrderedValid = pFrom->isOrderedValid;
113392         u8 isOrdered = pFrom->isOrdered;
113393         if( (pWLoop->prereq & ~pFrom->maskLoop)!=0 ) continue;
113394         if( (pWLoop->maskSelf & pFrom->maskLoop)!=0 ) continue;
113395         /* At this point, pWLoop is a candidate to be the next loop. 
113396         ** Compute its cost */
113397         rCost = sqlite3LogEstAdd(pWLoop->rSetup,pWLoop->rRun + pFrom->nRow);
113398         rCost = sqlite3LogEstAdd(rCost, pFrom->rCost);
113399         nOut = pFrom->nRow + pWLoop->nOut;
113400         maskNew = pFrom->maskLoop | pWLoop->maskSelf;
113401         if( !isOrderedValid ){
113402           switch( wherePathSatisfiesOrderBy(pWInfo,
113403                        pWInfo->pOrderBy, pFrom, pWInfo->wctrlFlags,
113404                        iLoop, pWLoop, &revMask) ){
113405             case 1:  /* Yes.  pFrom+pWLoop does satisfy the ORDER BY clause */
113406               isOrdered = 1;
113407               isOrderedValid = 1;
113408               break;
113409             case 0:  /* No.  pFrom+pWLoop will require a separate sort */
113410               isOrdered = 0;
113411               isOrderedValid = 1;
113412               rCost = sqlite3LogEstAdd(rCost, rSortCost);
113413               break;
113414             default: /* Cannot tell yet.  Try again on the next iteration */
113415               break;
113416           }
113417         }else{
113418           revMask = pFrom->revLoop;
113419         }
113420         /* Check to see if pWLoop should be added to the mxChoice best so far */
113421         for(jj=0, pTo=aTo; jj<nTo; jj++, pTo++){
113422           if( pTo->maskLoop==maskNew
113423            && pTo->isOrderedValid==isOrderedValid
113424            && ((pTo->rCost<=rCost && pTo->nRow<=nOut) ||
113425                 (pTo->rCost>=rCost && pTo->nRow>=nOut))
113426           ){
113427             testcase( jj==nTo-1 );
113428             break;
113429           }
113430         }
113431         if( jj>=nTo ){
113432           if( nTo>=mxChoice && rCost>=mxCost ){
113433 #ifdef WHERETRACE_ENABLED /* 0x4 */
113434             if( sqlite3WhereTrace&0x4 ){
113435               sqlite3DebugPrintf("Skip   %s cost=%-3d,%3d order=%c\n",
113436                   wherePathName(pFrom, iLoop, pWLoop), rCost, nOut,
113437                   isOrderedValid ? (isOrdered ? 'Y' : 'N') : '?');
113438             }
113439 #endif
113440             continue;
113441           }
113442           /* Add a new Path to the aTo[] set */
113443           if( nTo<mxChoice ){
113444             /* Increase the size of the aTo set by one */
113445             jj = nTo++;
113446           }else{
113447             /* New path replaces the prior worst to keep count below mxChoice */
113448             jj = mxI;
113449           }
113450           pTo = &aTo[jj];
113451 #ifdef WHERETRACE_ENABLED /* 0x4 */
113452           if( sqlite3WhereTrace&0x4 ){
113453             sqlite3DebugPrintf("New    %s cost=%-3d,%3d order=%c\n",
113454                 wherePathName(pFrom, iLoop, pWLoop), rCost, nOut,
113455                 isOrderedValid ? (isOrdered ? 'Y' : 'N') : '?');
113456           }
113457 #endif
113458         }else{
113459           if( pTo->rCost<=rCost && pTo->nRow<=nOut ){
113460 #ifdef WHERETRACE_ENABLED /* 0x4 */
113461             if( sqlite3WhereTrace&0x4 ){
113462               sqlite3DebugPrintf(
113463                   "Skip   %s cost=%-3d,%3d order=%c",
113464                   wherePathName(pFrom, iLoop, pWLoop), rCost, nOut,
113465                   isOrderedValid ? (isOrdered ? 'Y' : 'N') : '?');
113466               sqlite3DebugPrintf("   vs %s cost=%-3d,%d order=%c\n",
113467                   wherePathName(pTo, iLoop+1, 0), pTo->rCost, pTo->nRow,
113468                   pTo->isOrderedValid ? (pTo->isOrdered ? 'Y' : 'N') : '?');
113469             }
113470 #endif
113471             testcase( pTo->rCost==rCost );
113472             continue;
113473           }
113474           testcase( pTo->rCost==rCost+1 );
113475           /* A new and better score for a previously created equivalent path */
113476 #ifdef WHERETRACE_ENABLED /* 0x4 */
113477           if( sqlite3WhereTrace&0x4 ){
113478             sqlite3DebugPrintf(
113479                 "Update %s cost=%-3d,%3d order=%c",
113480                 wherePathName(pFrom, iLoop, pWLoop), rCost, nOut,
113481                 isOrderedValid ? (isOrdered ? 'Y' : 'N') : '?');
113482             sqlite3DebugPrintf("  was %s cost=%-3d,%3d order=%c\n",
113483                 wherePathName(pTo, iLoop+1, 0), pTo->rCost, pTo->nRow,
113484                 pTo->isOrderedValid ? (pTo->isOrdered ? 'Y' : 'N') : '?');
113485           }
113486 #endif
113487         }
113488         /* pWLoop is a winner.  Add it to the set of best so far */
113489         pTo->maskLoop = pFrom->maskLoop | pWLoop->maskSelf;
113490         pTo->revLoop = revMask;
113491         pTo->nRow = nOut;
113492         pTo->rCost = rCost;
113493         pTo->isOrderedValid = isOrderedValid;
113494         pTo->isOrdered = isOrdered;
113495         memcpy(pTo->aLoop, pFrom->aLoop, sizeof(WhereLoop*)*iLoop);
113496         pTo->aLoop[iLoop] = pWLoop;
113497         if( nTo>=mxChoice ){
113498           mxI = 0;
113499           mxCost = aTo[0].rCost;
113500           mxOut = aTo[0].nRow;
113501           for(jj=1, pTo=&aTo[1]; jj<mxChoice; jj++, pTo++){
113502             if( pTo->rCost>mxCost || (pTo->rCost==mxCost && pTo->nRow>mxOut) ){
113503               mxCost = pTo->rCost;
113504               mxOut = pTo->nRow;
113505               mxI = jj;
113506             }
113507           }
113508         }
113509       }
113510     }
113511 
113512 #ifdef WHERETRACE_ENABLED  /* >=2 */
113513     if( sqlite3WhereTrace>=2 ){
113514       sqlite3DebugPrintf("---- after round %d ----\n", iLoop);
113515       for(ii=0, pTo=aTo; ii<nTo; ii++, pTo++){
113516         sqlite3DebugPrintf(" %s cost=%-3d nrow=%-3d order=%c",
113517            wherePathName(pTo, iLoop+1, 0), pTo->rCost, pTo->nRow,
113518            pTo->isOrderedValid ? (pTo->isOrdered ? 'Y' : 'N') : '?');
113519         if( pTo->isOrderedValid && pTo->isOrdered ){
113520           sqlite3DebugPrintf(" rev=0x%llx\n", pTo->revLoop);
113521         }else{
113522           sqlite3DebugPrintf("\n");
113523         }
113524       }
113525     }
113526 #endif
113527 
113528     /* Swap the roles of aFrom and aTo for the next generation */
113529     pFrom = aTo;
113530     aTo = aFrom;
113531     aFrom = pFrom;
113532     nFrom = nTo;
113533   }
113534 
113535   if( nFrom==0 ){
113536     sqlite3ErrorMsg(pParse, "no query solution");
113537     sqlite3DbFree(db, pSpace);
113538     return SQLITE_ERROR;
113539   }
113540   
113541   /* Find the lowest cost path.  pFrom will be left pointing to that path */
113542   pFrom = aFrom;
113543   for(ii=1; ii<nFrom; ii++){
113544     if( pFrom->rCost>aFrom[ii].rCost ) pFrom = &aFrom[ii];
113545   }
113546   assert( pWInfo->nLevel==nLoop );
113547   /* Load the lowest cost path into pWInfo */
113548   for(iLoop=0; iLoop<nLoop; iLoop++){
113549     WhereLevel *pLevel = pWInfo->a + iLoop;
113550     pLevel->pWLoop = pWLoop = pFrom->aLoop[iLoop];
113551     pLevel->iFrom = pWLoop->iTab;
113552     pLevel->iTabCur = pWInfo->pTabList->a[pLevel->iFrom].iCursor;
113553   }
113554   if( (pWInfo->wctrlFlags & WHERE_WANT_DISTINCT)!=0
113555    && (pWInfo->wctrlFlags & WHERE_DISTINCTBY)==0
113556    && pWInfo->eDistinct==WHERE_DISTINCT_NOOP
113557    && nRowEst
113558   ){
113559     Bitmask notUsed;
113560     int rc = wherePathSatisfiesOrderBy(pWInfo, pWInfo->pResultSet, pFrom,
113561                  WHERE_DISTINCTBY, nLoop-1, pFrom->aLoop[nLoop-1], &notUsed);
113562     if( rc==1 ) pWInfo->eDistinct = WHERE_DISTINCT_ORDERED;
113563   }
113564   if( pFrom->isOrdered ){
113565     if( pWInfo->wctrlFlags & WHERE_DISTINCTBY ){
113566       pWInfo->eDistinct = WHERE_DISTINCT_ORDERED;
113567     }else{
113568       pWInfo->bOBSat = 1;
113569       pWInfo->revMask = pFrom->revLoop;
113570     }
113571   }
113572   pWInfo->nRowOut = pFrom->nRow;
113573 
113574   /* Free temporary memory and return success */
113575   sqlite3DbFree(db, pSpace);
113576   return SQLITE_OK;
113577 }
113578 
113579 /*
113580 ** Most queries use only a single table (they are not joins) and have
113581 ** simple == constraints against indexed fields.  This routine attempts
113582 ** to plan those simple cases using much less ceremony than the
113583 ** general-purpose query planner, and thereby yield faster sqlite3_prepare()
113584 ** times for the common case.
113585 **
113586 ** Return non-zero on success, if this query can be handled by this
113587 ** no-frills query planner.  Return zero if this query needs the 
113588 ** general-purpose query planner.
113589 */
113590 static int whereShortCut(WhereLoopBuilder *pBuilder){
113591   WhereInfo *pWInfo;
113592   struct SrcList_item *pItem;
113593   WhereClause *pWC;
113594   WhereTerm *pTerm;
113595   WhereLoop *pLoop;
113596   int iCur;
113597   int j;
113598   Table *pTab;
113599   Index *pIdx;
113600   
113601   pWInfo = pBuilder->pWInfo;
113602   if( pWInfo->wctrlFlags & WHERE_FORCE_TABLE ) return 0;
113603   assert( pWInfo->pTabList->nSrc>=1 );
113604   pItem = pWInfo->pTabList->a;
113605   pTab = pItem->pTab;
113606   if( IsVirtual(pTab) ) return 0;
113607   if( pItem->zIndex ) return 0;
113608   iCur = pItem->iCursor;
113609   pWC = &pWInfo->sWC;
113610   pLoop = pBuilder->pNew;
113611   pLoop->wsFlags = 0;
113612   pLoop->u.btree.nSkip = 0;
113613   pTerm = findTerm(pWC, iCur, -1, 0, WO_EQ, 0);
113614   if( pTerm ){
113615     pLoop->wsFlags = WHERE_COLUMN_EQ|WHERE_IPK|WHERE_ONEROW;
113616     pLoop->aLTerm[0] = pTerm;
113617     pLoop->nLTerm = 1;
113618     pLoop->u.btree.nEq = 1;
113619     /* TUNING: Cost of a rowid lookup is 10 */
113620     pLoop->rRun = 33;  /* 33==sqlite3LogEst(10) */
113621   }else{
113622     for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
113623       assert( pLoop->aLTermSpace==pLoop->aLTerm );
113624       assert( ArraySize(pLoop->aLTermSpace)==4 );
113625       if( pIdx->onError==OE_None 
113626        || pIdx->pPartIdxWhere!=0 
113627        || pIdx->nKeyCol>ArraySize(pLoop->aLTermSpace) 
113628       ) continue;
113629       for(j=0; j<pIdx->nKeyCol; j++){
113630         pTerm = findTerm(pWC, iCur, pIdx->aiColumn[j], 0, WO_EQ, pIdx);
113631         if( pTerm==0 ) break;
113632         pLoop->aLTerm[j] = pTerm;
113633       }
113634       if( j!=pIdx->nKeyCol ) continue;
113635       pLoop->wsFlags = WHERE_COLUMN_EQ|WHERE_ONEROW|WHERE_INDEXED;
113636       if( pIdx->isCovering || (pItem->colUsed & ~columnsInIndex(pIdx))==0 ){
113637         pLoop->wsFlags |= WHERE_IDX_ONLY;
113638       }
113639       pLoop->nLTerm = j;
113640       pLoop->u.btree.nEq = j;
113641       pLoop->u.btree.pIndex = pIdx;
113642       /* TUNING: Cost of a unique index lookup is 15 */
113643       pLoop->rRun = 39;  /* 39==sqlite3LogEst(15) */
113644       break;
113645     }
113646   }
113647   if( pLoop->wsFlags ){
113648     pLoop->nOut = (LogEst)1;
113649     pWInfo->a[0].pWLoop = pLoop;
113650     pLoop->maskSelf = getMask(&pWInfo->sMaskSet, iCur);
113651     pWInfo->a[0].iTabCur = iCur;
113652     pWInfo->nRowOut = 1;
113653     if( pWInfo->pOrderBy ) pWInfo->bOBSat =  1;
113654     if( pWInfo->wctrlFlags & WHERE_WANT_DISTINCT ){
113655       pWInfo->eDistinct = WHERE_DISTINCT_UNIQUE;
113656     }
113657 #ifdef SQLITE_DEBUG
113658     pLoop->cId = '0';
113659 #endif
113660     return 1;
113661   }
113662   return 0;
113663 }
113664 
113665 /*
113666 ** Generate the beginning of the loop used for WHERE clause processing.
113667 ** The return value is a pointer to an opaque structure that contains
113668 ** information needed to terminate the loop.  Later, the calling routine
113669 ** should invoke sqlite3WhereEnd() with the return value of this function
113670 ** in order to complete the WHERE clause processing.
113671 **
113672 ** If an error occurs, this routine returns NULL.
113673 **
113674 ** The basic idea is to do a nested loop, one loop for each table in
113675 ** the FROM clause of a select.  (INSERT and UPDATE statements are the
113676 ** same as a SELECT with only a single table in the FROM clause.)  For
113677 ** example, if the SQL is this:
113678 **
113679 **       SELECT * FROM t1, t2, t3 WHERE ...;
113680 **
113681 ** Then the code generated is conceptually like the following:
113682 **
113683 **      foreach row1 in t1 do       \    Code generated
113684 **        foreach row2 in t2 do      |-- by sqlite3WhereBegin()
113685 **          foreach row3 in t3 do   /
113686 **            ...
113687 **          end                     \    Code generated
113688 **        end                        |-- by sqlite3WhereEnd()
113689 **      end                         /
113690 **
113691 ** Note that the loops might not be nested in the order in which they
113692 ** appear in the FROM clause if a different order is better able to make
113693 ** use of indices.  Note also that when the IN operator appears in
113694 ** the WHERE clause, it might result in additional nested loops for
113695 ** scanning through all values on the right-hand side of the IN.
113696 **
113697 ** There are Btree cursors associated with each table.  t1 uses cursor
113698 ** number pTabList->a[0].iCursor.  t2 uses the cursor pTabList->a[1].iCursor.
113699 ** And so forth.  This routine generates code to open those VDBE cursors
113700 ** and sqlite3WhereEnd() generates the code to close them.
113701 **
113702 ** The code that sqlite3WhereBegin() generates leaves the cursors named
113703 ** in pTabList pointing at their appropriate entries.  The [...] code
113704 ** can use OP_Column and OP_Rowid opcodes on these cursors to extract
113705 ** data from the various tables of the loop.
113706 **
113707 ** If the WHERE clause is empty, the foreach loops must each scan their
113708 ** entire tables.  Thus a three-way join is an O(N^3) operation.  But if
113709 ** the tables have indices and there are terms in the WHERE clause that
113710 ** refer to those indices, a complete table scan can be avoided and the
113711 ** code will run much faster.  Most of the work of this routine is checking
113712 ** to see if there are indices that can be used to speed up the loop.
113713 **
113714 ** Terms of the WHERE clause are also used to limit which rows actually
113715 ** make it to the "..." in the middle of the loop.  After each "foreach",
113716 ** terms of the WHERE clause that use only terms in that loop and outer
113717 ** loops are evaluated and if false a jump is made around all subsequent
113718 ** inner loops (or around the "..." if the test occurs within the inner-
113719 ** most loop)
113720 **
113721 ** OUTER JOINS
113722 **
113723 ** An outer join of tables t1 and t2 is conceptally coded as follows:
113724 **
113725 **    foreach row1 in t1 do
113726 **      flag = 0
113727 **      foreach row2 in t2 do
113728 **        start:
113729 **          ...
113730 **          flag = 1
113731 **      end
113732 **      if flag==0 then
113733 **        move the row2 cursor to a null row
113734 **        goto start
113735 **      fi
113736 **    end
113737 **
113738 ** ORDER BY CLAUSE PROCESSING
113739 **
113740 ** pOrderBy is a pointer to the ORDER BY clause (or the GROUP BY clause
113741 ** if the WHERE_GROUPBY flag is set in wctrlFlags) of a SELECT statement
113742 ** if there is one.  If there is no ORDER BY clause or if this routine
113743 ** is called from an UPDATE or DELETE statement, then pOrderBy is NULL.
113744 **
113745 ** The iIdxCur parameter is the cursor number of an index.  If 
113746 ** WHERE_ONETABLE_ONLY is set, iIdxCur is the cursor number of an index
113747 ** to use for OR clause processing.  The WHERE clause should use this
113748 ** specific cursor.  If WHERE_ONEPASS_DESIRED is set, then iIdxCur is
113749 ** the first cursor in an array of cursors for all indices.  iIdxCur should
113750 ** be used to compute the appropriate cursor depending on which index is
113751 ** used.
113752 */
113753 SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin(
113754   Parse *pParse,        /* The parser context */
113755   SrcList *pTabList,    /* FROM clause: A list of all tables to be scanned */
113756   Expr *pWhere,         /* The WHERE clause */
113757   ExprList *pOrderBy,   /* An ORDER BY clause, or NULL */
113758   ExprList *pResultSet, /* Result set of the query */
113759   u16 wctrlFlags,       /* One of the WHERE_* flags defined in sqliteInt.h */
113760   int iIdxCur           /* If WHERE_ONETABLE_ONLY is set, index cursor number */
113761 ){
113762   int nByteWInfo;            /* Num. bytes allocated for WhereInfo struct */
113763   int nTabList;              /* Number of elements in pTabList */
113764   WhereInfo *pWInfo;         /* Will become the return value of this function */
113765   Vdbe *v = pParse->pVdbe;   /* The virtual database engine */
113766   Bitmask notReady;          /* Cursors that are not yet positioned */
113767   WhereLoopBuilder sWLB;     /* The WhereLoop builder */
113768   WhereMaskSet *pMaskSet;    /* The expression mask set */
113769   WhereLevel *pLevel;        /* A single level in pWInfo->a[] */
113770   WhereLoop *pLoop;          /* Pointer to a single WhereLoop object */
113771   int ii;                    /* Loop counter */
113772   sqlite3 *db;               /* Database connection */
113773   int rc;                    /* Return code */
113774 
113775 
113776   /* Variable initialization */
113777   db = pParse->db;
113778   memset(&sWLB, 0, sizeof(sWLB));
113779   sWLB.pOrderBy = pOrderBy;
113780 
113781   /* Disable the DISTINCT optimization if SQLITE_DistinctOpt is set via
113782   ** sqlite3_test_ctrl(SQLITE_TESTCTRL_OPTIMIZATIONS,...) */
113783   if( OptimizationDisabled(db, SQLITE_DistinctOpt) ){
113784     wctrlFlags &= ~WHERE_WANT_DISTINCT;
113785   }
113786 
113787   /* The number of tables in the FROM clause is limited by the number of
113788   ** bits in a Bitmask 
113789   */
113790   testcase( pTabList->nSrc==BMS );
113791   if( pTabList->nSrc>BMS ){
113792     sqlite3ErrorMsg(pParse, "at most %d tables in a join", BMS);
113793     return 0;
113794   }
113795 
113796   /* This function normally generates a nested loop for all tables in 
113797   ** pTabList.  But if the WHERE_ONETABLE_ONLY flag is set, then we should
113798   ** only generate code for the first table in pTabList and assume that
113799   ** any cursors associated with subsequent tables are uninitialized.
113800   */
113801   nTabList = (wctrlFlags & WHERE_ONETABLE_ONLY) ? 1 : pTabList->nSrc;
113802 
113803   /* Allocate and initialize the WhereInfo structure that will become the
113804   ** return value. A single allocation is used to store the WhereInfo
113805   ** struct, the contents of WhereInfo.a[], the WhereClause structure
113806   ** and the WhereMaskSet structure. Since WhereClause contains an 8-byte
113807   ** field (type Bitmask) it must be aligned on an 8-byte boundary on
113808   ** some architectures. Hence the ROUND8() below.
113809   */
113810   nByteWInfo = ROUND8(sizeof(WhereInfo)+(nTabList-1)*sizeof(WhereLevel));
113811   pWInfo = sqlite3DbMallocZero(db, nByteWInfo + sizeof(WhereLoop));
113812   if( db->mallocFailed ){
113813     sqlite3DbFree(db, pWInfo);
113814     pWInfo = 0;
113815     goto whereBeginError;
113816   }
113817   pWInfo->aiCurOnePass[0] = pWInfo->aiCurOnePass[1] = -1;
113818   pWInfo->nLevel = nTabList;
113819   pWInfo->pParse = pParse;
113820   pWInfo->pTabList = pTabList;
113821   pWInfo->pOrderBy = pOrderBy;
113822   pWInfo->pResultSet = pResultSet;
113823   pWInfo->iBreak = sqlite3VdbeMakeLabel(v);
113824   pWInfo->wctrlFlags = wctrlFlags;
113825   pWInfo->savedNQueryLoop = pParse->nQueryLoop;
113826   pMaskSet = &pWInfo->sMaskSet;
113827   sWLB.pWInfo = pWInfo;
113828   sWLB.pWC = &pWInfo->sWC;
113829   sWLB.pNew = (WhereLoop*)(((char*)pWInfo)+nByteWInfo);
113830   assert( EIGHT_BYTE_ALIGNMENT(sWLB.pNew) );
113831   whereLoopInit(sWLB.pNew);
113832 #ifdef SQLITE_DEBUG
113833   sWLB.pNew->cId = '*';
113834 #endif
113835 
113836   /* Split the WHERE clause into separate subexpressions where each
113837   ** subexpression is separated by an AND operator.
113838   */
113839   initMaskSet(pMaskSet);
113840   whereClauseInit(&pWInfo->sWC, pWInfo);
113841   whereSplit(&pWInfo->sWC, pWhere, TK_AND);
113842   sqlite3CodeVerifySchema(pParse, -1); /* Insert the cookie verifier Goto */
113843     
113844   /* Special case: a WHERE clause that is constant.  Evaluate the
113845   ** expression and either jump over all of the code or fall thru.
113846   */
113847   if( pWhere && (nTabList==0 || sqlite3ExprIsConstantNotJoin(pWhere)) ){
113848     sqlite3ExprIfFalse(pParse, pWhere, pWInfo->iBreak, SQLITE_JUMPIFNULL);
113849     pWhere = 0;
113850   }
113851 
113852   /* Special case: No FROM clause
113853   */
113854   if( nTabList==0 ){
113855     if( pOrderBy ) pWInfo->bOBSat = 1;
113856     if( wctrlFlags & WHERE_WANT_DISTINCT ){
113857       pWInfo->eDistinct = WHERE_DISTINCT_UNIQUE;
113858     }
113859   }
113860 
113861   /* Assign a bit from the bitmask to every term in the FROM clause.
113862   **
113863   ** When assigning bitmask values to FROM clause cursors, it must be
113864   ** the case that if X is the bitmask for the N-th FROM clause term then
113865   ** the bitmask for all FROM clause terms to the left of the N-th term
113866   ** is (X-1).   An expression from the ON clause of a LEFT JOIN can use
113867   ** its Expr.iRightJoinTable value to find the bitmask of the right table
113868   ** of the join.  Subtracting one from the right table bitmask gives a
113869   ** bitmask for all tables to the left of the join.  Knowing the bitmask
113870   ** for all tables to the left of a left join is important.  Ticket #3015.
113871   **
113872   ** Note that bitmasks are created for all pTabList->nSrc tables in
113873   ** pTabList, not just the first nTabList tables.  nTabList is normally
113874   ** equal to pTabList->nSrc but might be shortened to 1 if the
113875   ** WHERE_ONETABLE_ONLY flag is set.
113876   */
113877   for(ii=0; ii<pTabList->nSrc; ii++){
113878     createMask(pMaskSet, pTabList->a[ii].iCursor);
113879   }
113880 #ifndef NDEBUG
113881   {
113882     Bitmask toTheLeft = 0;
113883     for(ii=0; ii<pTabList->nSrc; ii++){
113884       Bitmask m = getMask(pMaskSet, pTabList->a[ii].iCursor);
113885       assert( (m-1)==toTheLeft );
113886       toTheLeft |= m;
113887     }
113888   }
113889 #endif
113890 
113891   /* Analyze all of the subexpressions.  Note that exprAnalyze() might
113892   ** add new virtual terms onto the end of the WHERE clause.  We do not
113893   ** want to analyze these virtual terms, so start analyzing at the end
113894   ** and work forward so that the added virtual terms are never processed.
113895   */
113896   exprAnalyzeAll(pTabList, &pWInfo->sWC);
113897   if( db->mallocFailed ){
113898     goto whereBeginError;
113899   }
113900 
113901   /* If the ORDER BY (or GROUP BY) clause contains references to general
113902   ** expressions, then we won't be able to satisfy it using indices, so
113903   ** go ahead and disable it now.
113904   */
113905   if( pOrderBy && (wctrlFlags & WHERE_WANT_DISTINCT)!=0 ){
113906     for(ii=0; ii<pOrderBy->nExpr; ii++){
113907       Expr *pExpr = sqlite3ExprSkipCollate(pOrderBy->a[ii].pExpr);
113908       if( pExpr->op!=TK_COLUMN ){
113909         pWInfo->pOrderBy = pOrderBy = 0;
113910         break;
113911       }else if( pExpr->iColumn<0 ){
113912         break;
113913       }
113914     }
113915   }
113916 
113917   if( wctrlFlags & WHERE_WANT_DISTINCT ){
113918     if( isDistinctRedundant(pParse, pTabList, &pWInfo->sWC, pResultSet) ){
113919       /* The DISTINCT marking is pointless.  Ignore it. */
113920       pWInfo->eDistinct = WHERE_DISTINCT_UNIQUE;
113921     }else if( pOrderBy==0 ){
113922       /* Try to ORDER BY the result set to make distinct processing easier */
113923       pWInfo->wctrlFlags |= WHERE_DISTINCTBY;
113924       pWInfo->pOrderBy = pResultSet;
113925     }
113926   }
113927 
113928   /* Construct the WhereLoop objects */
113929   WHERETRACE(0xffff,("*** Optimizer Start ***\n"));
113930   /* Display all terms of the WHERE clause */
113931 #if defined(WHERETRACE_ENABLED) && defined(SQLITE_ENABLE_TREE_EXPLAIN)
113932   if( sqlite3WhereTrace & 0x100 ){
113933     int i;
113934     Vdbe *v = pParse->pVdbe;
113935     sqlite3ExplainBegin(v);
113936     for(i=0; i<sWLB.pWC->nTerm; i++){
113937       sqlite3ExplainPrintf(v, "#%-2d ", i);
113938       sqlite3ExplainPush(v);
113939       whereExplainTerm(v, &sWLB.pWC->a[i]);
113940       sqlite3ExplainPop(v);
113941       sqlite3ExplainNL(v);
113942     }
113943     sqlite3ExplainFinish(v);
113944     sqlite3DebugPrintf("%s", sqlite3VdbeExplanation(v));
113945   }
113946 #endif
113947   if( nTabList!=1 || whereShortCut(&sWLB)==0 ){
113948     rc = whereLoopAddAll(&sWLB);
113949     if( rc ) goto whereBeginError;
113950   
113951     /* Display all of the WhereLoop objects if wheretrace is enabled */
113952 #ifdef WHERETRACE_ENABLED /* !=0 */
113953     if( sqlite3WhereTrace ){
113954       WhereLoop *p;
113955       int i;
113956       static char zLabel[] = "0123456789abcdefghijklmnopqrstuvwyxz"
113957                                        "ABCDEFGHIJKLMNOPQRSTUVWYXZ";
113958       for(p=pWInfo->pLoops, i=0; p; p=p->pNextLoop, i++){
113959         p->cId = zLabel[i%sizeof(zLabel)];
113960         whereLoopPrint(p, sWLB.pWC);
113961       }
113962     }
113963 #endif
113964   
113965     wherePathSolver(pWInfo, 0);
113966     if( db->mallocFailed ) goto whereBeginError;
113967     if( pWInfo->pOrderBy ){
113968        wherePathSolver(pWInfo, pWInfo->nRowOut+1);
113969        if( db->mallocFailed ) goto whereBeginError;
113970     }
113971   }
113972   if( pWInfo->pOrderBy==0 && (db->flags & SQLITE_ReverseOrder)!=0 ){
113973      pWInfo->revMask = (Bitmask)(-1);
113974   }
113975   if( pParse->nErr || NEVER(db->mallocFailed) ){
113976     goto whereBeginError;
113977   }
113978 #ifdef WHERETRACE_ENABLED /* !=0 */
113979   if( sqlite3WhereTrace ){
113980     int ii;
113981     sqlite3DebugPrintf("---- Solution nRow=%d", pWInfo->nRowOut);
113982     if( pWInfo->bOBSat ){
113983       sqlite3DebugPrintf(" ORDERBY=0x%llx", pWInfo->revMask);
113984     }
113985     switch( pWInfo->eDistinct ){
113986       case WHERE_DISTINCT_UNIQUE: {
113987         sqlite3DebugPrintf("  DISTINCT=unique");
113988         break;
113989       }
113990       case WHERE_DISTINCT_ORDERED: {
113991         sqlite3DebugPrintf("  DISTINCT=ordered");
113992         break;
113993       }
113994       case WHERE_DISTINCT_UNORDERED: {
113995         sqlite3DebugPrintf("  DISTINCT=unordered");
113996         break;
113997       }
113998     }
113999     sqlite3DebugPrintf("\n");
114000     for(ii=0; ii<pWInfo->nLevel; ii++){
114001       whereLoopPrint(pWInfo->a[ii].pWLoop, sWLB.pWC);
114002     }
114003   }
114004 #endif
114005   /* Attempt to omit tables from the join that do not effect the result */
114006   if( pWInfo->nLevel>=2
114007    && pResultSet!=0
114008    && OptimizationEnabled(db, SQLITE_OmitNoopJoin)
114009   ){
114010     Bitmask tabUsed = exprListTableUsage(pMaskSet, pResultSet);
114011     if( sWLB.pOrderBy ) tabUsed |= exprListTableUsage(pMaskSet, sWLB.pOrderBy);
114012     while( pWInfo->nLevel>=2 ){
114013       WhereTerm *pTerm, *pEnd;
114014       pLoop = pWInfo->a[pWInfo->nLevel-1].pWLoop;
114015       if( (pWInfo->pTabList->a[pLoop->iTab].jointype & JT_LEFT)==0 ) break;
114016       if( (wctrlFlags & WHERE_WANT_DISTINCT)==0
114017        && (pLoop->wsFlags & WHERE_ONEROW)==0
114018       ){
114019         break;
114020       }
114021       if( (tabUsed & pLoop->maskSelf)!=0 ) break;
114022       pEnd = sWLB.pWC->a + sWLB.pWC->nTerm;
114023       for(pTerm=sWLB.pWC->a; pTerm<pEnd; pTerm++){
114024         if( (pTerm->prereqAll & pLoop->maskSelf)!=0
114025          && !ExprHasProperty(pTerm->pExpr, EP_FromJoin)
114026         ){
114027           break;
114028         }
114029       }
114030       if( pTerm<pEnd ) break;
114031       WHERETRACE(0xffff, ("-> drop loop %c not used\n", pLoop->cId));
114032       pWInfo->nLevel--;
114033       nTabList--;
114034     }
114035   }
114036   WHERETRACE(0xffff,("*** Optimizer Finished ***\n"));
114037   pWInfo->pParse->nQueryLoop += pWInfo->nRowOut;
114038 
114039   /* If the caller is an UPDATE or DELETE statement that is requesting
114040   ** to use a one-pass algorithm, determine if this is appropriate.
114041   ** The one-pass algorithm only works if the WHERE clause constrains
114042   ** the statement to update a single row.
114043   */
114044   assert( (wctrlFlags & WHERE_ONEPASS_DESIRED)==0 || pWInfo->nLevel==1 );
114045   if( (wctrlFlags & WHERE_ONEPASS_DESIRED)!=0 
114046    && (pWInfo->a[0].pWLoop->wsFlags & WHERE_ONEROW)!=0 ){
114047     pWInfo->okOnePass = 1;
114048     if( HasRowid(pTabList->a[0].pTab) ){
114049       pWInfo->a[0].pWLoop->wsFlags &= ~WHERE_IDX_ONLY;
114050     }
114051   }
114052 
114053   /* Open all tables in the pTabList and any indices selected for
114054   ** searching those tables.
114055   */
114056   notReady = ~(Bitmask)0;
114057   for(ii=0, pLevel=pWInfo->a; ii<nTabList; ii++, pLevel++){
114058     Table *pTab;     /* Table to open */
114059     int iDb;         /* Index of database containing table/index */
114060     struct SrcList_item *pTabItem;
114061 
114062     pTabItem = &pTabList->a[pLevel->iFrom];
114063     pTab = pTabItem->pTab;
114064     iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
114065     pLoop = pLevel->pWLoop;
114066     if( (pTab->tabFlags & TF_Ephemeral)!=0 || pTab->pSelect ){
114067       /* Do nothing */
114068     }else
114069 #ifndef SQLITE_OMIT_VIRTUALTABLE
114070     if( (pLoop->wsFlags & WHERE_VIRTUALTABLE)!=0 ){
114071       const char *pVTab = (const char *)sqlite3GetVTable(db, pTab);
114072       int iCur = pTabItem->iCursor;
114073       sqlite3VdbeAddOp4(v, OP_VOpen, iCur, 0, 0, pVTab, P4_VTAB);
114074     }else if( IsVirtual(pTab) ){
114075       /* noop */
114076     }else
114077 #endif
114078     if( (pLoop->wsFlags & WHERE_IDX_ONLY)==0
114079          && (wctrlFlags & WHERE_OMIT_OPEN_CLOSE)==0 ){
114080       int op = OP_OpenRead;
114081       if( pWInfo->okOnePass ){
114082         op = OP_OpenWrite;
114083         pWInfo->aiCurOnePass[0] = pTabItem->iCursor;
114084       };
114085       sqlite3OpenTable(pParse, pTabItem->iCursor, iDb, pTab, op);
114086       assert( pTabItem->iCursor==pLevel->iTabCur );
114087       testcase( !pWInfo->okOnePass && pTab->nCol==BMS-1 );
114088       testcase( !pWInfo->okOnePass && pTab->nCol==BMS );
114089       if( !pWInfo->okOnePass && pTab->nCol<BMS && HasRowid(pTab) ){
114090         Bitmask b = pTabItem->colUsed;
114091         int n = 0;
114092         for(; b; b=b>>1, n++){}
114093         sqlite3VdbeChangeP4(v, sqlite3VdbeCurrentAddr(v)-1, 
114094                             SQLITE_INT_TO_PTR(n), P4_INT32);
114095         assert( n<=pTab->nCol );
114096       }
114097     }else{
114098       sqlite3TableLock(pParse, iDb, pTab->tnum, 0, pTab->zName);
114099     }
114100     if( pLoop->wsFlags & WHERE_INDEXED ){
114101       Index *pIx = pLoop->u.btree.pIndex;
114102       int iIndexCur;
114103       int op = OP_OpenRead;
114104       /* iIdxCur is always set if to a positive value if ONEPASS is possible */
114105       assert( iIdxCur!=0 || (pWInfo->wctrlFlags & WHERE_ONEPASS_DESIRED)==0 );
114106       if( pWInfo->okOnePass ){
114107         Index *pJ = pTabItem->pTab->pIndex;
114108         iIndexCur = iIdxCur;
114109         assert( wctrlFlags & WHERE_ONEPASS_DESIRED );
114110         while( ALWAYS(pJ) && pJ!=pIx ){
114111           iIndexCur++;
114112           pJ = pJ->pNext;
114113         }
114114         op = OP_OpenWrite;
114115         pWInfo->aiCurOnePass[1] = iIndexCur;
114116       }else if( iIdxCur && (wctrlFlags & WHERE_ONETABLE_ONLY)!=0 ){
114117         iIndexCur = iIdxCur;
114118       }else{
114119         iIndexCur = pParse->nTab++;
114120       }
114121       pLevel->iIdxCur = iIndexCur;
114122       assert( pIx->pSchema==pTab->pSchema );
114123       assert( iIndexCur>=0 );
114124       sqlite3VdbeAddOp3(v, op, iIndexCur, pIx->tnum, iDb);
114125       sqlite3VdbeSetP4KeyInfo(pParse, pIx);
114126       VdbeComment((v, "%s", pIx->zName));
114127     }
114128     sqlite3CodeVerifySchema(pParse, iDb);
114129     notReady &= ~getMask(&pWInfo->sMaskSet, pTabItem->iCursor);
114130   }
114131   pWInfo->iTop = sqlite3VdbeCurrentAddr(v);
114132   if( db->mallocFailed ) goto whereBeginError;
114133 
114134   /* Generate the code to do the search.  Each iteration of the for
114135   ** loop below generates code for a single nested loop of the VM
114136   ** program.
114137   */
114138   notReady = ~(Bitmask)0;
114139   for(ii=0; ii<nTabList; ii++){
114140     pLevel = &pWInfo->a[ii];
114141 #ifndef SQLITE_OMIT_AUTOMATIC_INDEX
114142     if( (pLevel->pWLoop->wsFlags & WHERE_AUTO_INDEX)!=0 ){
114143       constructAutomaticIndex(pParse, &pWInfo->sWC,
114144                 &pTabList->a[pLevel->iFrom], notReady, pLevel);
114145       if( db->mallocFailed ) goto whereBeginError;
114146     }
114147 #endif
114148     explainOneScan(pParse, pTabList, pLevel, ii, pLevel->iFrom, wctrlFlags);
114149     pLevel->addrBody = sqlite3VdbeCurrentAddr(v);
114150     notReady = codeOneLoopStart(pWInfo, ii, notReady);
114151     pWInfo->iContinue = pLevel->addrCont;
114152   }
114153 
114154   /* Done. */
114155   VdbeModuleComment((v, "Begin WHERE-core"));
114156   return pWInfo;
114157 
114158   /* Jump here if malloc fails */
114159 whereBeginError:
114160   if( pWInfo ){
114161     pParse->nQueryLoop = pWInfo->savedNQueryLoop;
114162     whereInfoFree(db, pWInfo);
114163   }
114164   return 0;
114165 }
114166 
114167 /*
114168 ** Generate the end of the WHERE loop.  See comments on 
114169 ** sqlite3WhereBegin() for additional information.
114170 */
114171 SQLITE_PRIVATE void sqlite3WhereEnd(WhereInfo *pWInfo){
114172   Parse *pParse = pWInfo->pParse;
114173   Vdbe *v = pParse->pVdbe;
114174   int i;
114175   WhereLevel *pLevel;
114176   WhereLoop *pLoop;
114177   SrcList *pTabList = pWInfo->pTabList;
114178   sqlite3 *db = pParse->db;
114179 
114180   /* Generate loop termination code.
114181   */
114182   VdbeModuleComment((v, "End WHERE-core"));
114183   sqlite3ExprCacheClear(pParse);
114184   for(i=pWInfo->nLevel-1; i>=0; i--){
114185     int addr;
114186     pLevel = &pWInfo->a[i];
114187     pLoop = pLevel->pWLoop;
114188     sqlite3VdbeResolveLabel(v, pLevel->addrCont);
114189     if( pLevel->op!=OP_Noop ){
114190       sqlite3VdbeAddOp2(v, pLevel->op, pLevel->p1, pLevel->p2);
114191       sqlite3VdbeChangeP5(v, pLevel->p5);
114192     }
114193     if( pLoop->wsFlags & WHERE_IN_ABLE && pLevel->u.in.nIn>0 ){
114194       struct InLoop *pIn;
114195       int j;
114196       sqlite3VdbeResolveLabel(v, pLevel->addrNxt);
114197       for(j=pLevel->u.in.nIn, pIn=&pLevel->u.in.aInLoop[j-1]; j>0; j--, pIn--){
114198         sqlite3VdbeJumpHere(v, pIn->addrInTop+1);
114199         sqlite3VdbeAddOp2(v, pIn->eEndLoopOp, pIn->iCur, pIn->addrInTop);
114200         sqlite3VdbeJumpHere(v, pIn->addrInTop-1);
114201       }
114202       sqlite3DbFree(db, pLevel->u.in.aInLoop);
114203     }
114204     sqlite3VdbeResolveLabel(v, pLevel->addrBrk);
114205     if( pLevel->addrSkip ){
114206       sqlite3VdbeAddOp2(v, OP_Goto, 0, pLevel->addrSkip);
114207       VdbeComment((v, "next skip-scan on %s", pLoop->u.btree.pIndex->zName));
114208       sqlite3VdbeJumpHere(v, pLevel->addrSkip);
114209       sqlite3VdbeJumpHere(v, pLevel->addrSkip-2);
114210     }
114211     if( pLevel->iLeftJoin ){
114212       addr = sqlite3VdbeAddOp1(v, OP_IfPos, pLevel->iLeftJoin);
114213       assert( (pLoop->wsFlags & WHERE_IDX_ONLY)==0
114214            || (pLoop->wsFlags & WHERE_INDEXED)!=0 );
114215       if( (pLoop->wsFlags & WHERE_IDX_ONLY)==0 ){
114216         sqlite3VdbeAddOp1(v, OP_NullRow, pTabList->a[i].iCursor);
114217       }
114218       if( pLoop->wsFlags & WHERE_INDEXED ){
114219         sqlite3VdbeAddOp1(v, OP_NullRow, pLevel->iIdxCur);
114220       }
114221       if( pLevel->op==OP_Return ){
114222         sqlite3VdbeAddOp2(v, OP_Gosub, pLevel->p1, pLevel->addrFirst);
114223       }else{
114224         sqlite3VdbeAddOp2(v, OP_Goto, 0, pLevel->addrFirst);
114225       }
114226       sqlite3VdbeJumpHere(v, addr);
114227     }
114228     VdbeModuleComment((v, "End WHERE-loop%d: %s", i,
114229                      pWInfo->pTabList->a[pLevel->iFrom].pTab->zName));
114230   }
114231 
114232   /* The "break" point is here, just past the end of the outer loop.
114233   ** Set it.
114234   */
114235   sqlite3VdbeResolveLabel(v, pWInfo->iBreak);
114236 
114237   assert( pWInfo->nLevel<=pTabList->nSrc );
114238   for(i=0, pLevel=pWInfo->a; i<pWInfo->nLevel; i++, pLevel++){
114239     Index *pIdx = 0;
114240     struct SrcList_item *pTabItem = &pTabList->a[pLevel->iFrom];
114241     Table *pTab = pTabItem->pTab;
114242     assert( pTab!=0 );
114243     pLoop = pLevel->pWLoop;
114244 
114245     /* Close all of the cursors that were opened by sqlite3WhereBegin.
114246     ** Except, do not close cursors that will be reused by the OR optimization
114247     ** (WHERE_OMIT_OPEN_CLOSE).  And do not close the OP_OpenWrite cursors
114248     ** created for the ONEPASS optimization.
114249     */
114250     if( (pTab->tabFlags & TF_Ephemeral)==0
114251      && pTab->pSelect==0
114252      && (pWInfo->wctrlFlags & WHERE_OMIT_OPEN_CLOSE)==0
114253     ){
114254       int ws = pLoop->wsFlags;
114255       if( !pWInfo->okOnePass && (ws & WHERE_IDX_ONLY)==0 ){
114256         sqlite3VdbeAddOp1(v, OP_Close, pTabItem->iCursor);
114257       }
114258       if( (ws & WHERE_INDEXED)!=0
114259        && (ws & (WHERE_IPK|WHERE_AUTO_INDEX))==0 
114260        && pLevel->iIdxCur!=pWInfo->aiCurOnePass[1]
114261       ){
114262         sqlite3VdbeAddOp1(v, OP_Close, pLevel->iIdxCur);
114263       }
114264     }
114265 
114266     /* If this scan uses an index, make VDBE code substitutions to read data
114267     ** from the index instead of from the table where possible.  In some cases
114268     ** this optimization prevents the table from ever being read, which can
114269     ** yield a significant performance boost.
114270     ** 
114271     ** Calls to the code generator in between sqlite3WhereBegin and
114272     ** sqlite3WhereEnd will have created code that references the table
114273     ** directly.  This loop scans all that code looking for opcodes
114274     ** that reference the table and converts them into opcodes that
114275     ** reference the index.
114276     */
114277     if( pLoop->wsFlags & (WHERE_INDEXED|WHERE_IDX_ONLY) ){
114278       pIdx = pLoop->u.btree.pIndex;
114279     }else if( pLoop->wsFlags & WHERE_MULTI_OR ){
114280       pIdx = pLevel->u.pCovidx;
114281     }
114282     if( pIdx && !db->mallocFailed ){
114283       int k, last;
114284       VdbeOp *pOp;
114285 
114286       last = sqlite3VdbeCurrentAddr(v);
114287       k = pLevel->addrBody;
114288       pOp = sqlite3VdbeGetOp(v, k);
114289       for(; k<last; k++, pOp++){
114290         if( pOp->p1!=pLevel->iTabCur ) continue;
114291         if( pOp->opcode==OP_Column ){
114292           int x = pOp->p2;
114293           assert( pIdx->pTable==pTab );
114294           if( !HasRowid(pTab) ){
114295             Index *pPk = sqlite3PrimaryKeyIndex(pTab);
114296             x = pPk->aiColumn[x];
114297           }
114298           x = sqlite3ColumnOfIndex(pIdx, x);
114299           if( x>=0 ){
114300             pOp->p2 = x;
114301             pOp->p1 = pLevel->iIdxCur;
114302           }
114303           assert( (pLoop->wsFlags & WHERE_IDX_ONLY)==0 || x>=0 );
114304         }else if( pOp->opcode==OP_Rowid ){
114305           pOp->p1 = pLevel->iIdxCur;
114306           pOp->opcode = OP_IdxRowid;
114307         }
114308       }
114309     }
114310   }
114311 
114312   /* Final cleanup
114313   */
114314   pParse->nQueryLoop = pWInfo->savedNQueryLoop;
114315   whereInfoFree(db, pWInfo);
114316   return;
114317 }
114318 
114319 /************** End of where.c ***********************************************/
114320 /************** Begin file parse.c *******************************************/
114321 /* Driver template for the LEMON parser generator.
114322 ** The author disclaims copyright to this source code.
114323 **
114324 ** This version of "lempar.c" is modified, slightly, for use by SQLite.
114325 ** The only modifications are the addition of a couple of NEVER()
114326 ** macros to disable tests that are needed in the case of a general
114327 ** LALR(1) grammar but which are always false in the
114328 ** specific grammar used by SQLite.
114329 */
114330 /* First off, code is included that follows the "include" declaration
114331 ** in the input grammar file. */
114332 /* #include <stdio.h> */
114333 
114334 
114335 /*
114336 ** Disable all error recovery processing in the parser push-down
114337 ** automaton.
114338 */
114339 #define YYNOERRORRECOVERY 1
114340 
114341 /*
114342 ** Make yytestcase() the same as testcase()
114343 */
114344 #define yytestcase(X) testcase(X)
114345 
114346 /*
114347 ** An instance of this structure holds information about the
114348 ** LIMIT clause of a SELECT statement.
114349 */
114350 struct LimitVal {
114351   Expr *pLimit;    /* The LIMIT expression.  NULL if there is no limit */
114352   Expr *pOffset;   /* The OFFSET expression.  NULL if there is none */
114353 };
114354 
114355 /*
114356 ** An instance of this structure is used to store the LIKE,
114357 ** GLOB, NOT LIKE, and NOT GLOB operators.
114358 */
114359 struct LikeOp {
114360   Token eOperator;  /* "like" or "glob" or "regexp" */
114361   int bNot;         /* True if the NOT keyword is present */
114362 };
114363 
114364 /*
114365 ** An instance of the following structure describes the event of a
114366 ** TRIGGER.  "a" is the event type, one of TK_UPDATE, TK_INSERT,
114367 ** TK_DELETE, or TK_INSTEAD.  If the event is of the form
114368 **
114369 **      UPDATE ON (a,b,c)
114370 **
114371 ** Then the "b" IdList records the list "a,b,c".
114372 */
114373 struct TrigEvent { int a; IdList * b; };
114374 
114375 /*
114376 ** An instance of this structure holds the ATTACH key and the key type.
114377 */
114378 struct AttachKey { int type;  Token key; };
114379 
114380 /*
114381 ** One or more VALUES claues
114382 */
114383 struct ValueList {
114384   ExprList *pList;
114385   Select *pSelect;
114386 };
114387 
114388 
114389   /* This is a utility routine used to set the ExprSpan.zStart and
114390   ** ExprSpan.zEnd values of pOut so that the span covers the complete
114391   ** range of text beginning with pStart and going to the end of pEnd.
114392   */
114393   static void spanSet(ExprSpan *pOut, Token *pStart, Token *pEnd){
114394     pOut->zStart = pStart->z;
114395     pOut->zEnd = &pEnd->z[pEnd->n];
114396   }
114397 
114398   /* Construct a new Expr object from a single identifier.  Use the
114399   ** new Expr to populate pOut.  Set the span of pOut to be the identifier
114400   ** that created the expression.
114401   */
114402   static void spanExpr(ExprSpan *pOut, Parse *pParse, int op, Token *pValue){
114403     pOut->pExpr = sqlite3PExpr(pParse, op, 0, 0, pValue);
114404     pOut->zStart = pValue->z;
114405     pOut->zEnd = &pValue->z[pValue->n];
114406   }
114407 
114408   /* This routine constructs a binary expression node out of two ExprSpan
114409   ** objects and uses the result to populate a new ExprSpan object.
114410   */
114411   static void spanBinaryExpr(
114412     ExprSpan *pOut,     /* Write the result here */
114413     Parse *pParse,      /* The parsing context.  Errors accumulate here */
114414     int op,             /* The binary operation */
114415     ExprSpan *pLeft,    /* The left operand */
114416     ExprSpan *pRight    /* The right operand */
114417   ){
114418     pOut->pExpr = sqlite3PExpr(pParse, op, pLeft->pExpr, pRight->pExpr, 0);
114419     pOut->zStart = pLeft->zStart;
114420     pOut->zEnd = pRight->zEnd;
114421   }
114422 
114423   /* Construct an expression node for a unary postfix operator
114424   */
114425   static void spanUnaryPostfix(
114426     ExprSpan *pOut,        /* Write the new expression node here */
114427     Parse *pParse,         /* Parsing context to record errors */
114428     int op,                /* The operator */
114429     ExprSpan *pOperand,    /* The operand */
114430     Token *pPostOp         /* The operand token for setting the span */
114431   ){
114432     pOut->pExpr = sqlite3PExpr(pParse, op, pOperand->pExpr, 0, 0);
114433     pOut->zStart = pOperand->zStart;
114434     pOut->zEnd = &pPostOp->z[pPostOp->n];
114435   }                           
114436 
114437   /* A routine to convert a binary TK_IS or TK_ISNOT expression into a
114438   ** unary TK_ISNULL or TK_NOTNULL expression. */
114439   static void binaryToUnaryIfNull(Parse *pParse, Expr *pY, Expr *pA, int op){
114440     sqlite3 *db = pParse->db;
114441     if( db->mallocFailed==0 && pY->op==TK_NULL ){
114442       pA->op = (u8)op;
114443       sqlite3ExprDelete(db, pA->pRight);
114444       pA->pRight = 0;
114445     }
114446   }
114447 
114448   /* Construct an expression node for a unary prefix operator
114449   */
114450   static void spanUnaryPrefix(
114451     ExprSpan *pOut,        /* Write the new expression node here */
114452     Parse *pParse,         /* Parsing context to record errors */
114453     int op,                /* The operator */
114454     ExprSpan *pOperand,    /* The operand */
114455     Token *pPreOp         /* The operand token for setting the span */
114456   ){
114457     pOut->pExpr = sqlite3PExpr(pParse, op, pOperand->pExpr, 0, 0);
114458     pOut->zStart = pPreOp->z;
114459     pOut->zEnd = pOperand->zEnd;
114460   }
114461 /* Next is all token values, in a form suitable for use by makeheaders.
114462 ** This section will be null unless lemon is run with the -m switch.
114463 */
114464 /* 
114465 ** These constants (all generated automatically by the parser generator)
114466 ** specify the various kinds of tokens (terminals) that the parser
114467 ** understands. 
114468 **
114469 ** Each symbol here is a terminal symbol in the grammar.
114470 */
114471 /* Make sure the INTERFACE macro is defined.
114472 */
114473 #ifndef INTERFACE
114474 # define INTERFACE 1
114475 #endif
114476 /* The next thing included is series of defines which control
114477 ** various aspects of the generated parser.
114478 **    YYCODETYPE         is the data type used for storing terminal
114479 **                       and nonterminal numbers.  "unsigned char" is
114480 **                       used if there are fewer than 250 terminals
114481 **                       and nonterminals.  "int" is used otherwise.
114482 **    YYNOCODE           is a number of type YYCODETYPE which corresponds
114483 **                       to no legal terminal or nonterminal number.  This
114484 **                       number is used to fill in empty slots of the hash 
114485 **                       table.
114486 **    YYFALLBACK         If defined, this indicates that one or more tokens
114487 **                       have fall-back values which should be used if the
114488 **                       original value of the token will not parse.
114489 **    YYACTIONTYPE       is the data type used for storing terminal
114490 **                       and nonterminal numbers.  "unsigned char" is
114491 **                       used if there are fewer than 250 rules and
114492 **                       states combined.  "int" is used otherwise.
114493 **    sqlite3ParserTOKENTYPE     is the data type used for minor tokens given 
114494 **                       directly to the parser from the tokenizer.
114495 **    YYMINORTYPE        is the data type used for all minor tokens.
114496 **                       This is typically a union of many types, one of
114497 **                       which is sqlite3ParserTOKENTYPE.  The entry in the union
114498 **                       for base tokens is called "yy0".
114499 **    YYSTACKDEPTH       is the maximum depth of the parser's stack.  If
114500 **                       zero the stack is dynamically sized using realloc()
114501 **    sqlite3ParserARG_SDECL     A static variable declaration for the %extra_argument
114502 **    sqlite3ParserARG_PDECL     A parameter declaration for the %extra_argument
114503 **    sqlite3ParserARG_STORE     Code to store %extra_argument into yypParser
114504 **    sqlite3ParserARG_FETCH     Code to extract %extra_argument from yypParser
114505 **    YYNSTATE           the combined number of states.
114506 **    YYNRULE            the number of rules in the grammar
114507 **    YYERRORSYMBOL      is the code number of the error symbol.  If not
114508 **                       defined, then do no error processing.
114509 */
114510 #define YYCODETYPE unsigned char
114511 #define YYNOCODE 253
114512 #define YYACTIONTYPE unsigned short int
114513 #define YYWILDCARD 68
114514 #define sqlite3ParserTOKENTYPE Token
114515 typedef union {
114516   int yyinit;
114517   sqlite3ParserTOKENTYPE yy0;
114518   int yy4;
114519   struct TrigEvent yy90;
114520   ExprSpan yy118;
114521   u16 yy177;
114522   TriggerStep* yy203;
114523   u8 yy210;
114524   struct {int value; int mask;} yy215;
114525   SrcList* yy259;
114526   struct ValueList yy260;
114527   struct LimitVal yy292;
114528   Expr* yy314;
114529   ExprList* yy322;
114530   struct LikeOp yy342;
114531   IdList* yy384;
114532   Select* yy387;
114533 } YYMINORTYPE;
114534 #ifndef YYSTACKDEPTH
114535 #define YYSTACKDEPTH 100
114536 #endif
114537 #define sqlite3ParserARG_SDECL Parse *pParse;
114538 #define sqlite3ParserARG_PDECL ,Parse *pParse
114539 #define sqlite3ParserARG_FETCH Parse *pParse = yypParser->pParse
114540 #define sqlite3ParserARG_STORE yypParser->pParse = pParse
114541 #define YYNSTATE 631
114542 #define YYNRULE 329
114543 #define YYFALLBACK 1
114544 #define YY_NO_ACTION      (YYNSTATE+YYNRULE+2)
114545 #define YY_ACCEPT_ACTION  (YYNSTATE+YYNRULE+1)
114546 #define YY_ERROR_ACTION   (YYNSTATE+YYNRULE)
114547 
114548 /* The yyzerominor constant is used to initialize instances of
114549 ** YYMINORTYPE objects to zero. */
114550 static const YYMINORTYPE yyzerominor = { 0 };
114551 
114552 /* Define the yytestcase() macro to be a no-op if is not already defined
114553 ** otherwise.
114554 **
114555 ** Applications can choose to define yytestcase() in the %include section
114556 ** to a macro that can assist in verifying code coverage.  For production
114557 ** code the yytestcase() macro should be turned off.  But it is useful
114558 ** for testing.
114559 */
114560 #ifndef yytestcase
114561 # define yytestcase(X)
114562 #endif
114563 
114564 
114565 /* Next are the tables used to determine what action to take based on the
114566 ** current state and lookahead token.  These tables are used to implement
114567 ** functions that take a state number and lookahead value and return an
114568 ** action integer.  
114569 **
114570 ** Suppose the action integer is N.  Then the action is determined as
114571 ** follows
114572 **
114573 **   0 <= N < YYNSTATE                  Shift N.  That is, push the lookahead
114574 **                                      token onto the stack and goto state N.
114575 **
114576 **   YYNSTATE <= N < YYNSTATE+YYNRULE   Reduce by rule N-YYNSTATE.
114577 **
114578 **   N == YYNSTATE+YYNRULE              A syntax error has occurred.
114579 **
114580 **   N == YYNSTATE+YYNRULE+1            The parser accepts its input.
114581 **
114582 **   N == YYNSTATE+YYNRULE+2            No such action.  Denotes unused
114583 **                                      slots in the yy_action[] table.
114584 **
114585 ** The action table is constructed as a single large table named yy_action[].
114586 ** Given state S and lookahead X, the action is computed as
114587 **
114588 **      yy_action[ yy_shift_ofst[S] + X ]
114589 **
114590 ** If the index value yy_shift_ofst[S]+X is out of range or if the value
114591 ** yy_lookahead[yy_shift_ofst[S]+X] is not equal to X or if yy_shift_ofst[S]
114592 ** is equal to YY_SHIFT_USE_DFLT, it means that the action is not in the table
114593 ** and that yy_default[S] should be used instead.  
114594 **
114595 ** The formula above is for computing the action when the lookahead is
114596 ** a terminal symbol.  If the lookahead is a non-terminal (as occurs after
114597 ** a reduce action) then the yy_reduce_ofst[] array is used in place of
114598 ** the yy_shift_ofst[] array and YY_REDUCE_USE_DFLT is used in place of
114599 ** YY_SHIFT_USE_DFLT.
114600 **
114601 ** The following are the tables generated in this section:
114602 **
114603 **  yy_action[]        A single table containing all actions.
114604 **  yy_lookahead[]     A table containing the lookahead for each entry in
114605 **                     yy_action.  Used to detect hash collisions.
114606 **  yy_shift_ofst[]    For each state, the offset into yy_action for
114607 **                     shifting terminals.
114608 **  yy_reduce_ofst[]   For each state, the offset into yy_action for
114609 **                     shifting non-terminals after a reduce.
114610 **  yy_default[]       Default action for each state.
114611 */
114612 #define YY_ACTTAB_COUNT (1582)
114613 static const YYACTIONTYPE yy_action[] = {
114614  /*     0 */   312,  961,  185,  420,    2,  171,  516,  515,  597,   56,
114615  /*    10 */    56,   56,   56,   49,   54,   54,   54,   54,   53,   53,
114616  /*    20 */    52,   52,   52,   51,  234,  197,  196,  195,  624,  623,
114617  /*    30 */   301,  590,  584,   56,   56,   56,   56,  156,   54,   54,
114618  /*    40 */    54,   54,   53,   53,   52,   52,   52,   51,  234,  628,
114619  /*    50 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114620  /*    60 */    56,   56,   56,  466,   54,   54,   54,   54,   53,   53,
114621  /*    70 */    52,   52,   52,   51,  234,  312,  597,   52,   52,   52,
114622  /*    80 */    51,  234,   33,   54,   54,   54,   54,   53,   53,   52,
114623  /*    90 */    52,   52,   51,  234,  624,  623,  621,  620,  165,  624,
114624  /*   100 */   623,  383,  380,  379,  214,  328,  590,  584,  624,  623,
114625  /*   110 */   467,   59,  378,  619,  618,  617,   53,   53,   52,   52,
114626  /*   120 */    52,   51,  234,  506,  507,   57,   58,   48,  582,  581,
114627  /*   130 */   583,  583,   55,   55,   56,   56,   56,   56,   30,   54,
114628  /*   140 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114629  /*   150 */   312,   50,   47,  146,  233,  232,  207,  474,  256,  349,
114630  /*   160 */   255,  475,  621,  620,  554,  438,  298,  621,  620,  236,
114631  /*   170 */   674,  435,  440,  553,  439,  366,  621,  620,  540,  224,
114632  /*   180 */   551,  590,  584,  176,  138,  282,  386,  277,  385,  168,
114633  /*   190 */   600,  422,  951,  548,  622,  951,  273,  572,  572,  566,
114634  /*   200 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114635  /*   210 */    56,   56,   56,  354,   54,   54,   54,   54,   53,   53,
114636  /*   220 */    52,   52,   52,   51,  234,  312,  561,  526,   62,  675,
114637  /*   230 */   132,  595,  410,  348,  579,  579,  492,  426,  577,  419,
114638  /*   240 */   627,   65,  329,  560,  441,  237,  676,  123,  607,   67,
114639  /*   250 */   542,  532,  622,  170,  205,  500,  590,  584,  166,  559,
114640  /*   260 */   622,  403,  593,  593,  593,  442,  443,  271,  422,  950,
114641  /*   270 */   166,  223,  950,  483,  190,   57,   58,   48,  582,  581,
114642  /*   280 */   583,  583,   55,   55,   56,   56,   56,   56,  600,   54,
114643  /*   290 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114644  /*   300 */   312,  441,  412,  376,  175,  165,  166,  391,  383,  380,
114645  /*   310 */   379,  342,  412,  203,  426,   66,  392,  622,  415,  378,
114646  /*   320 */   597,  166,  442,  338,  444,  571,  601,   74,  415,  624,
114647  /*   330 */   623,  590,  584,  624,  623,  174,  601,   92,  333,  171,
114648  /*   340 */     1,  410,  597,  579,  579,  624,  623,  600,  306,  425,
114649  /*   350 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114650  /*   360 */    56,   56,   56,  580,   54,   54,   54,   54,   53,   53,
114651  /*   370 */    52,   52,   52,   51,  234,  312,  472,  262,  399,   68,
114652  /*   380 */   412,  339,  571,  389,  624,  623,  578,  602,  597,  589,
114653  /*   390 */   588,  603,  412,  622,  423,  533,  415,  621,  620,  513,
114654  /*   400 */   257,  621,  620,  166,  601,   91,  590,  584,  415,   45,
114655  /*   410 */   597,  586,  585,  621,  620,  250,  601,   92,   39,  347,
114656  /*   420 */   576,  336,  597,  547,  567,   57,   58,   48,  582,  581,
114657  /*   430 */   583,  583,   55,   55,   56,   56,   56,   56,  587,   54,
114658  /*   440 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114659  /*   450 */   312,  561,  621,  620,  531,  291,  470,  188,  399,  375,
114660  /*   460 */   247,  492,  249,  350,  412,  476,  476,  368,  560,  299,
114661  /*   470 */   334,  412,  281,  482,   67,  565,  410,  622,  579,  579,
114662  /*   480 */   415,  590,  584,  280,  559,  467,  520,  415,  601,   92,
114663  /*   490 */   597,  167,  544,   36,  877,  601,   16,  519,  564,    6,
114664  /*   500 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114665  /*   510 */    56,   56,   56,  200,   54,   54,   54,   54,   53,   53,
114666  /*   520 */    52,   52,   52,   51,  234,  312,  183,  412,  236,  528,
114667  /*   530 */   395,  535,  358,  256,  349,  255,  397,  412,  248,  182,
114668  /*   540 */   353,  359,  549,  415,  236,  317,  563,   50,   47,  146,
114669  /*   550 */   273,  601,   73,  415,    7,  311,  590,  584,  568,  493,
114670  /*   560 */   213,  601,   92,  233,  232,  410,  173,  579,  579,  330,
114671  /*   570 */   575,  574,  631,  629,  332,   57,   58,   48,  582,  581,
114672  /*   580 */   583,  583,   55,   55,   56,   56,   56,   56,  199,   54,
114673  /*   590 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114674  /*   600 */   312,  492,  340,  320,  511,  505,  572,  572,  460,  562,
114675  /*   610 */   549,  170,  145,  430,   67,  558,  410,  622,  579,  579,
114676  /*   620 */   384,  236,  600,  412,  408,  575,  574,  504,  572,  572,
114677  /*   630 */   571,  590,  584,  353,  198,  143,  268,  549,  316,  415,
114678  /*   640 */   306,  424,  207,   50,   47,  146,  167,  601,   69,  546,
114679  /*   650 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114680  /*   660 */    56,   56,   56,  555,   54,   54,   54,   54,   53,   53,
114681  /*   670 */    52,   52,   52,   51,  234,  312,  600,  326,  412,  270,
114682  /*   680 */   145,  264,  274,  266,  459,  571,  423,   35,  412,  568,
114683  /*   690 */   407,  213,  428,  388,  415,  308,  212,  143,  622,  354,
114684  /*   700 */   317,   12,  601,   94,  415,  549,  590,  584,   50,   47,
114685  /*   710 */   146,  365,  601,   97,  552,  362,  318,  147,  602,  361,
114686  /*   720 */   325,   15,  603,  187,  206,   57,   58,   48,  582,  581,
114687  /*   730 */   583,  583,   55,   55,   56,   56,   56,   56,  412,   54,
114688  /*   740 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114689  /*   750 */   312,  412,   35,  412,  415,   22,  630,    2,  600,   50,
114690  /*   760 */    47,  146,  601,   95,  412,  485,  510,  415,  412,  415,
114691  /*   770 */   412,   11,  235,  486,  412,  601,  104,  601,  103,   19,
114692  /*   780 */   415,  590,  584,  352,  415,   40,  415,   38,  601,  105,
114693  /*   790 */   415,   32,  601,  106,  601,  133,  544,  169,  601,  134,
114694  /*   800 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114695  /*   810 */    56,   56,   56,  412,   54,   54,   54,   54,   53,   53,
114696  /*   820 */    52,   52,   52,   51,  234,  312,  412,  274,  412,  415,
114697  /*   830 */   412,  274,  274,  274,  201,  230,  721,  601,   98,  484,
114698  /*   840 */   427,  307,  415,  622,  415,  540,  415,  622,  622,  622,
114699  /*   850 */   601,  102,  601,  101,  601,   93,  590,  584,  262,   21,
114700  /*   860 */   129,  622,  522,  521,  554,  222,  469,  521,  600,  324,
114701  /*   870 */   323,  322,  211,  553,  622,   57,   58,   48,  582,  581,
114702  /*   880 */   583,  583,   55,   55,   56,   56,   56,   56,  412,   54,
114703  /*   890 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114704  /*   900 */   312,  412,  261,  412,  415,  412,  600,  210,  625,  367,
114705  /*   910 */    51,  234,  601,  100,  538,  606,  142,  415,  355,  415,
114706  /*   920 */   412,  415,  412,  496,  622,  601,   77,  601,   96,  601,
114707  /*   930 */   137,  590,  584,  530,  622,  529,  415,  141,  415,   28,
114708  /*   940 */   524,  600,  229,  544,  601,  136,  601,  135,  604,  204,
114709  /*   950 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114710  /*   960 */    56,   56,   56,  412,   54,   54,   54,   54,   53,   53,
114711  /*   970 */    52,   52,   52,   51,  234,  312,  412,  360,  412,  415,
114712  /*   980 */   412,  360,  286,  600,  503,  220,  127,  601,   76,  629,
114713  /*   990 */   332,  382,  415,  622,  415,  540,  415,  622,  412,  613,
114714  /*  1000 */   601,   90,  601,   89,  601,   75,  590,  584,  341,  272,
114715  /*  1010 */   377,  622,  126,   27,  415,  622,  164,  544,  125,  280,
114716  /*  1020 */   373,  122,  601,   88,  480,   57,   46,   48,  582,  581,
114717  /*  1030 */   583,  583,   55,   55,   56,   56,   56,   56,  412,   54,
114718  /*  1040 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114719  /*  1050 */   312,  412,  360,  412,  415,  412,  284,  186,  369,  321,
114720  /*  1060 */   477,  170,  601,   87,  121,  473,  221,  415,  622,  415,
114721  /*  1070 */   254,  415,  412,  355,  412,  601,   99,  601,   86,  601,
114722  /*  1080 */    17,  590,  584,  259,  612,  120,  159,  158,  415,  622,
114723  /*  1090 */   415,   14,  465,  157,  462,   25,  601,   85,  601,   84,
114724  /*  1100 */   622,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114725  /*  1110 */    56,   56,   56,  412,   54,   54,   54,   54,   53,   53,
114726  /*  1120 */    52,   52,   52,   51,  234,  312,  412,  262,  412,  415,
114727  /*  1130 */   412,  262,  118,  611,  117,   24,   10,  601,   83,  351,
114728  /*  1140 */   216,  219,  415,  622,  415,  608,  415,  622,  412,  622,
114729  /*  1150 */   601,   72,  601,   71,  601,   82,  590,  584,  262,    4,
114730  /*  1160 */   605,  622,  458,  115,  415,  456,  252,  154,  452,  110,
114731  /*  1170 */   108,  453,  601,   81,  622,  451,  622,   48,  582,  581,
114732  /*  1180 */   583,  583,   55,   55,   56,   56,   56,   56,  412,   54,
114733  /*  1190 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114734  /*  1200 */    44,  406,  450,    3,  415,  412,  262,  107,  416,  623,
114735  /*  1210 */   446,  437,  601,   80,  436,  335,  238,  189,  411,  409,
114736  /*  1220 */   594,  415,  622,   44,  406,  401,    3,  412,  557,  601,
114737  /*  1230 */    70,  416,  623,  412,  622,  149,  622,  421,  404,   64,
114738  /*  1240 */   412,  622,  409,  415,  622,  331,  139,  148,  566,  415,
114739  /*  1250 */   449,  601,   18,  228,  124,  626,  415,  601,   79,  315,
114740  /*  1260 */   181,  404,  412,  545,  601,   78,  262,  541,   41,   42,
114741  /*  1270 */   534,  566,  390,  202,  262,   43,  414,  413,  415,  622,
114742  /*  1280 */   595,  314,  622,  622,  180,  539,  601,   92,  415,  276,
114743  /*  1290 */   622,   41,   42,  509,  616,  615,  601,    9,   43,  414,
114744  /*  1300 */   413,  622,  418,  595,  262,  622,  275,  600,  614,  622,
114745  /*  1310 */   218,  593,  593,  593,  592,  591,   13,  178,  217,  417,
114746  /*  1320 */   622,  236,  622,   44,  406,  490,    3,  269,  399,  267,
114747  /*  1330 */   609,  416,  623,  400,  593,  593,  593,  592,  591,   13,
114748  /*  1340 */   265,  622,  409,  622,  263,  622,   34,  406,  244,    3,
114749  /*  1350 */   258,  363,  464,  463,  416,  623,  622,  356,  251,    8,
114750  /*  1360 */   622,  404,  177,  599,  455,  409,  622,  622,  622,  622,
114751  /*  1370 */   445,  566,  243,  622,  622,  236,  295,  240,   31,  239,
114752  /*  1380 */   622,  431,   30,  396,  404,  290,  622,  294,  622,  293,
114753  /*  1390 */   144,   41,   42,  622,  566,  622,  394,  622,   43,  414,
114754  /*  1400 */   413,  622,  289,  595,  398,   60,  622,  292,   37,  231,
114755  /*  1410 */   598,  172,  622,   29,   41,   42,  393,  523,  622,  556,
114756  /*  1420 */   184,   43,  414,  413,  287,  387,  595,  543,  285,  518,
114757  /*  1430 */   537,  536,  517,  327,  593,  593,  593,  592,  591,   13,
114758  /*  1440 */   215,  283,  278,  514,  513,  304,  303,  302,  179,  300,
114759  /*  1450 */   512,  310,  454,  128,  227,  226,  309,  593,  593,  593,
114760  /*  1460 */   592,  591,   13,  494,  489,  225,  488,  150,  487,  242,
114761  /*  1470 */   163,   61,  374,  481,  162,  161,  624,  623,  241,  372,
114762  /*  1480 */   209,  479,  370,  260,   26,  160,  478,  364,  468,  471,
114763  /*  1490 */   140,  152,  119,  467,  131,  116,  155,  153,  345,  457,
114764  /*  1500 */   151,  346,  130,  114,  113,  112,  111,  448,  319,   23,
114765  /*  1510 */   109,  434,   20,  433,  432,  429,  566,  610,  573,  596,
114766  /*  1520 */    63,  405,  191,  279,  510,  296,  498,  288,  570,  495,
114767  /*  1530 */   499,  497,  461,  194,    5,  305,  193,  192,  381,  569,
114768  /*  1540 */   357,  256,  344,  245,  526,  246,  253,  313,  595,  343,
114769  /*  1550 */   447,  297,  236,  402,  550,  491,  508,  502,  501,  527,
114770  /*  1560 */   234,  208,  525,  962,  962,  962,  371,  962,  962,  962,
114771  /*  1570 */   962,  962,  962,  962,  962,  337,  962,  962,  962,  593,
114772  /*  1580 */   593,  593,
114773 };
114774 static const YYCODETYPE yy_lookahead[] = {
114775  /*     0 */    19,  143,  144,  145,  146,   24,    7,    8,   27,   78,
114776  /*    10 */    79,   80,   81,   82,   83,   84,   85,   86,   87,   88,
114777  /*    20 */    89,   90,   91,   92,   93,  106,  107,  108,   27,   28,
114778  /*    30 */    15,   50,   51,   78,   79,   80,   81,   26,   83,   84,
114779  /*    40 */    85,   86,   87,   88,   89,   90,   91,   92,   93,    1,
114780  /*    50 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114781  /*    60 */    79,   80,   81,   11,   83,   84,   85,   86,   87,   88,
114782  /*    70 */    89,   90,   91,   92,   93,   19,   95,   89,   90,   91,
114783  /*    80 */    92,   93,   26,   83,   84,   85,   86,   87,   88,   89,
114784  /*    90 */    90,   91,   92,   93,   27,   28,   95,   96,   97,   27,
114785  /*   100 */    28,  100,  101,  102,   22,   19,   50,   51,   27,   28,
114786  /*   110 */    58,   55,  111,    7,    8,    9,   87,   88,   89,   90,
114787  /*   120 */    91,   92,   93,   98,   99,   69,   70,   71,   72,   73,
114788  /*   130 */    74,   75,   76,   77,   78,   79,   80,   81,  127,   83,
114789  /*   140 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114790  /*   150 */    19,  223,  224,  225,   87,   88,  162,   31,  106,  107,
114791  /*   160 */   108,   35,   95,   96,   33,   98,   23,   95,   96,  117,
114792  /*   170 */   119,  243,  105,   42,  107,   49,   95,   96,  151,   93,
114793  /*   180 */    26,   50,   51,   97,   98,   99,  100,  101,  102,  103,
114794  /*   190 */   196,   22,   23,  121,  167,   26,  110,  130,  131,   67,
114795  /*   200 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114796  /*   210 */    79,   80,   81,  219,   83,   84,   85,   86,   87,   88,
114797  /*   220 */    89,   90,   91,   92,   93,   19,   12,   95,  234,  119,
114798  /*   230 */    24,   99,  113,  239,  115,  116,  151,   68,   23,  147,
114799  /*   240 */   148,   26,  215,   29,  151,  153,  119,  155,  163,  164,
114800  /*   250 */    23,   23,  167,   26,  162,   23,   50,   51,   26,   45,
114801  /*   260 */   167,   47,  130,  131,  132,  172,  173,   23,   22,   23,
114802  /*   270 */    26,  186,   26,  188,  120,   69,   70,   71,   72,   73,
114803  /*   280 */    74,   75,   76,   77,   78,   79,   80,   81,  196,   83,
114804  /*   290 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114805  /*   300 */    19,  151,  151,   23,  119,   97,   26,   19,  100,  101,
114806  /*   310 */   102,  219,  151,  162,   68,   22,   28,  167,  167,  111,
114807  /*   320 */    27,   26,  172,  173,  231,  232,  175,  176,  167,   27,
114808  /*   330 */    28,   50,   51,   27,   28,  119,  175,  176,  246,   24,
114809  /*   340 */    22,  113,   27,  115,  116,   27,   28,  196,   22,   23,
114810  /*   350 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114811  /*   360 */    79,   80,   81,  114,   83,   84,   85,   86,   87,   88,
114812  /*   370 */    89,   90,   91,   92,   93,   19,   21,  151,  217,   22,
114813  /*   380 */   151,  231,  232,  222,   27,   28,   23,  114,   95,   50,
114814  /*   390 */    51,  118,  151,  167,   68,   89,  167,   95,   96,  104,
114815  /*   400 */    23,   95,   96,   26,  175,  176,   50,   51,  167,   22,
114816  /*   410 */    95,   72,   73,   95,   96,   16,  175,  176,  137,   64,
114817  /*   420 */    23,  195,   27,  121,   23,   69,   70,   71,   72,   73,
114818  /*   430 */    74,   75,   76,   77,   78,   79,   80,   81,   99,   83,
114819  /*   440 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114820  /*   450 */    19,   12,   95,   96,   23,  226,  101,   22,  217,   19,
114821  /*   460 */    61,  151,   63,  222,  151,  106,  107,  108,   29,  159,
114822  /*   470 */   244,  151,   99,  163,  164,   23,  113,  167,  115,  116,
114823  /*   480 */   167,   50,   51,  110,   45,   58,   47,  167,  175,  176,
114824  /*   490 */    95,   51,  168,  137,  139,  175,  176,   58,   11,   22,
114825  /*   500 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114826  /*   510 */    79,   80,   81,   22,   83,   84,   85,   86,   87,   88,
114827  /*   520 */    89,   90,   91,   92,   93,   19,   23,  151,  117,   23,
114828  /*   530 */   217,  207,   19,  106,  107,  108,  216,  151,  139,   23,
114829  /*   540 */   129,   28,   26,  167,  117,  105,   23,  223,  224,  225,
114830  /*   550 */   110,  175,  176,  167,   77,  165,   50,   51,  168,  169,
114831  /*   560 */   170,  175,  176,   87,   88,  113,   26,  115,  116,  171,
114832  /*   570 */   172,  173,    0,    1,    2,   69,   70,   71,   72,   73,
114833  /*   580 */    74,   75,   76,   77,   78,   79,   80,   81,  162,   83,
114834  /*   590 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114835  /*   600 */    19,  151,   98,  217,   23,   37,  130,  131,   23,   23,
114836  /*   610 */    26,   26,   96,  163,  164,   23,  113,  167,  115,  116,
114837  /*   620 */    52,  117,  196,  151,  171,  172,  173,   59,  130,  131,
114838  /*   630 */   232,   50,   51,  129,  208,  209,   16,  121,  156,  167,
114839  /*   640 */    22,   23,  162,  223,  224,  225,   51,  175,  176,  121,
114840  /*   650 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114841  /*   660 */    79,   80,   81,  178,   83,   84,   85,   86,   87,   88,
114842  /*   670 */    89,   90,   91,   92,   93,   19,  196,  109,  151,   23,
114843  /*   680 */    96,   61,  151,   63,   23,  232,   68,   26,  151,  168,
114844  /*   690 */   169,  170,   23,   89,  167,   26,  208,  209,  167,  219,
114845  /*   700 */   105,   36,  175,  176,  167,  121,   50,   51,  223,  224,
114846  /*   710 */   225,  229,  175,  176,  178,  233,  247,  248,  114,  239,
114847  /*   720 */   189,   22,  118,   24,  162,   69,   70,   71,   72,   73,
114848  /*   730 */    74,   75,   76,   77,   78,   79,   80,   81,  151,   83,
114849  /*   740 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114850  /*   750 */    19,  151,   26,  151,  167,   24,  145,  146,  196,  223,
114851  /*   760 */   224,  225,  175,  176,  151,  182,  183,  167,  151,  167,
114852  /*   770 */   151,   36,  199,  190,  151,  175,  176,  175,  176,  206,
114853  /*   780 */   167,   50,   51,  221,  167,  136,  167,  138,  175,  176,
114854  /*   790 */   167,   26,  175,  176,  175,  176,  168,   36,  175,  176,
114855  /*   800 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114856  /*   810 */    79,   80,   81,  151,   83,   84,   85,   86,   87,   88,
114857  /*   820 */    89,   90,   91,   92,   93,   19,  151,  151,  151,  167,
114858  /*   830 */   151,  151,  151,  151,  162,  207,   23,  175,  176,   26,
114859  /*   840 */   249,  250,  167,  167,  167,  151,  167,  167,  167,  167,
114860  /*   850 */   175,  176,  175,  176,  175,  176,   50,   51,  151,   53,
114861  /*   860 */    22,  167,  192,  193,   33,  189,  192,  193,  196,  189,
114862  /*   870 */   189,  189,  162,   42,  167,   69,   70,   71,   72,   73,
114863  /*   880 */    74,   75,   76,   77,   78,   79,   80,   81,  151,   83,
114864  /*   890 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114865  /*   900 */    19,  151,  195,  151,  167,  151,  196,  162,  151,  215,
114866  /*   910 */    92,   93,  175,  176,   28,  174,  119,  167,  151,  167,
114867  /*   920 */   151,  167,  151,  182,  167,  175,  176,  175,  176,  175,
114868  /*   930 */   176,   50,   51,   23,  167,   23,  167,   40,  167,   22,
114869  /*   940 */   167,  196,   53,  168,  175,  176,  175,  176,  175,  162,
114870  /*   950 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114871  /*   960 */    79,   80,   81,  151,   83,   84,   85,   86,   87,   88,
114872  /*   970 */    89,   90,   91,   92,   93,   19,  151,  151,  151,  167,
114873  /*   980 */   151,  151,  207,  196,   30,  218,   22,  175,  176,    1,
114874  /*   990 */     2,   53,  167,  167,  167,  151,  167,  167,  151,  151,
114875  /*  1000 */   175,  176,  175,  176,  175,  176,   50,   51,  221,   23,
114876  /*  1010 */    53,  167,   22,   22,  167,  167,  103,  168,   22,  110,
114877  /*  1020 */    19,  105,  175,  176,   20,   69,   70,   71,   72,   73,
114878  /*  1030 */    74,   75,   76,   77,   78,   79,   80,   81,  151,   83,
114879  /*  1040 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114880  /*  1050 */    19,  151,  151,  151,  167,  151,  207,   24,   44,  215,
114881  /*  1060 */    60,   26,  175,  176,   54,   54,  240,  167,  167,  167,
114882  /*  1070 */   240,  167,  151,  151,  151,  175,  176,  175,  176,  175,
114883  /*  1080 */   176,   50,   51,  139,  151,   22,  105,  119,  167,  167,
114884  /*  1090 */   167,    5,    1,   36,   28,   77,  175,  176,  175,  176,
114885  /*  1100 */   167,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114886  /*  1110 */    79,   80,   81,  151,   83,   84,   85,   86,   87,   88,
114887  /*  1120 */    89,   90,   91,   92,   93,   19,  151,  151,  151,  167,
114888  /*  1130 */   151,  151,  109,  151,  128,   77,   22,  175,  176,   26,
114889  /*  1140 */   218,  240,  167,  167,  167,  151,  167,  167,  151,  167,
114890  /*  1150 */   175,  176,  175,  176,  175,  176,   50,   51,  151,   22,
114891  /*  1160 */   151,  167,   23,  120,  167,    1,   16,  122,   20,  120,
114892  /*  1170 */   109,  195,  175,  176,  167,  195,  167,   71,   72,   73,
114893  /*  1180 */    74,   75,   76,   77,   78,   79,   80,   81,  151,   83,
114894  /*  1190 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114895  /*  1200 */    19,   20,  195,   22,  167,  151,  151,  128,   27,   28,
114896  /*  1210 */   129,   23,  175,  176,   23,   66,  141,   22,  151,   38,
114897  /*  1220 */   151,  167,  167,   19,   20,  151,   22,  151,  151,  175,
114898  /*  1230 */   176,   27,   28,  151,  167,   15,  167,    4,   57,   16,
114899  /*  1240 */   151,  167,   38,  167,  167,    3,  166,  248,   67,  167,
114900  /*  1250 */   195,  175,  176,  181,  181,  150,  167,  175,  176,  251,
114901  /*  1260 */     6,   57,  151,  151,  175,  176,  151,  151,   87,   88,
114902  /*  1270 */    89,   67,  151,  162,  151,   94,   95,   96,  167,  167,
114903  /*  1280 */    99,  251,  167,  167,  152,  151,  175,  176,  167,  151,
114904  /*  1290 */   167,   87,   88,  151,  150,  150,  175,  176,   94,   95,
114905  /*  1300 */    96,  167,  150,   99,  151,  167,  151,  196,   13,  167,
114906  /*  1310 */   195,  130,  131,  132,  133,  134,  135,  152,  195,  160,
114907  /*  1320 */   167,  117,  167,   19,   20,  151,   22,  151,  217,  151,
114908  /*  1330 */   161,   27,   28,  222,  130,  131,  132,  133,  134,  135,
114909  /*  1340 */   151,  167,   38,  167,  151,  167,   19,   20,  195,   22,
114910  /*  1350 */   151,  151,  151,  151,   27,   28,  167,  151,  151,   26,
114911  /*  1360 */   167,   57,   25,  196,  151,   38,  167,  167,  167,  167,
114912  /*  1370 */   151,   67,  151,  167,  167,  117,  201,  151,  125,  151,
114913  /*  1380 */   167,  151,  127,  124,   57,  151,  167,  202,  167,  203,
114914  /*  1390 */   151,   87,   88,  167,   67,  167,  151,  167,   94,   95,
114915  /*  1400 */    96,  167,  151,   99,  123,  126,  167,  204,  136,  227,
114916  /*  1410 */   205,  119,  167,  105,   87,   88,  122,  177,  167,  158,
114917  /*  1420 */   158,   94,   95,   96,  212,  105,   99,  213,  212,  177,
114918  /*  1430 */   213,  213,  185,   48,  130,  131,  132,  133,  134,  135,
114919  /*  1440 */     5,  212,  177,  179,  104,   10,   11,   12,   13,   14,
114920  /*  1450 */   177,  180,   17,   22,  230,   93,  180,  130,  131,  132,
114921  /*  1460 */   133,  134,  135,  185,  177,  230,  177,   32,  177,   34,
114922  /*  1470 */   157,   22,   18,  158,  157,  157,   27,   28,   43,  158,
114923  /*  1480 */   158,  158,   46,  237,  136,  157,  238,  158,  191,  201,
114924  /*  1490 */    69,   56,  191,   58,  220,   22,  157,   62,   18,  201,
114925  /*  1500 */    65,  158,  220,  194,  194,  194,  194,  201,  158,  242,
114926  /*  1510 */   191,   41,  242,  158,  158,   39,   67,  154,  232,  168,
114927  /*  1520 */   245,  228,  198,  178,  183,  200,  168,  211,  232,  168,
114928  /*  1530 */   178,  178,  201,  187,  198,  149,   87,   88,  179,  168,
114929  /*  1540 */   241,  106,  107,  108,   95,  211,  241,  112,   99,  211,
114930  /*  1550 */   201,  197,  117,  193,  210,  188,  184,  184,  184,  175,
114931  /*  1560 */    93,  235,  175,  252,  252,  252,  236,  252,  252,  252,
114932  /*  1570 */   252,  252,  252,  252,  252,  140,  252,  252,  252,  130,
114933  /*  1580 */   131,  132,
114934 };
114935 #define YY_SHIFT_USE_DFLT (-82)
114936 #define YY_SHIFT_COUNT (419)
114937 #define YY_SHIFT_MIN   (-81)
114938 #define YY_SHIFT_MAX   (1480)
114939 static const short yy_shift_ofst[] = {
114940  /*     0 */   988, 1204, 1435, 1204, 1304, 1304,   67,   67,    1,  -19,
114941  /*    10 */  1304, 1304, 1304, 1304,  427,   81,  131,  131,  806, 1181,
114942  /*    20 */  1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304,
114943  /*    30 */  1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304,
114944  /*    40 */  1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1327, 1304,
114945  /*    50 */  1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304,
114946  /*    60 */  1304, 1304,   52,   81,   81,  476,  476,  395, 1258,   56,
114947  /*    70 */   731,  656,  581,  506,  431,  356,  281,  206,  881,  881,
114948  /*    80 */   881,  881,  881,  881,  881,  881,  881,  881,  881,  881,
114949  /*    90 */   881,  881,  881,  956,  881, 1031, 1106, 1106,  -69,  -45,
114950  /*   100 */   -45,  -45,  -45,  -45,    0,   29,  -12,   81,   81,   81,
114951  /*   110 */    81,   81,   81,   81,   81,   81,   81,   81,   81,   81,
114952  /*   120 */    81,   81,   81,  355,  440,   81,   81,   81,   81,   81,
114953  /*   130 */   504,  411,  395,  818, 1467,  -82,  -82,  -82, 1449,   86,
114954  /*   140 */   439,  439,  306,  357,  302,   72,  318,  246,  169,   81,
114955  /*   150 */    81,   81,   81,   81,   81,   81,   81,   81,   81,   81,
114956  /*   160 */    81,   81,   81,   81,   81,   81,   81,   81,   81,   81,
114957  /*   170 */    81,   81,   81,   81,   81,   81,   81,   81,   81,   81,
114958  /*   180 */    81,   81,  315,  315,  315,  572, 1258, 1258, 1258,  -82,
114959  /*   190 */   -82,  -82,  132,  132,  208,  568,  568,  568,  516,  503,
114960  /*   200 */   214,  452,  363,  228,  119,  119,  119,  119,  359,  126,
114961  /*   210 */   119,  119,  584,  293,  604,  106,   11,  288,  288,  513,
114962  /*   220 */    11,  513,  295,  813,  395,  831,  395,  831,  595,  831,
114963  /*   230 */   288,  649,  498,  498,  395,  154,  273,  699, 1476, 1292,
114964  /*   240 */  1292, 1470, 1470, 1292, 1473, 1421, 1255, 1480, 1480, 1480,
114965  /*   250 */  1480, 1292, 1454, 1255, 1473, 1421, 1421, 1255, 1292, 1454,
114966  /*   260 */  1348, 1436, 1292, 1292, 1454, 1292, 1454, 1292, 1454, 1431,
114967  /*   270 */  1320, 1320, 1320, 1385, 1362, 1362, 1431, 1320, 1340, 1320,
114968  /*   280 */  1385, 1320, 1320, 1294, 1308, 1294, 1308, 1294, 1308, 1292,
114969  /*   290 */  1292, 1272, 1279, 1281, 1253, 1259, 1255, 1258, 1337, 1333,
114970  /*   300 */  1295, 1295, 1254, 1254, 1254, 1254,  -82,  -82,  -82,  -82,
114971  /*   310 */   -82,  -82,  339,  399,  618,  326,  620,  -81,  669,  477,
114972  /*   320 */   661,  585,  377,  280,  244,  232,   25,   -1,  373,  227,
114973  /*   330 */   215, 1233, 1242, 1195, 1075, 1220, 1149, 1223, 1191, 1188,
114974  /*   340 */  1081, 1113, 1079, 1061, 1049, 1148, 1045, 1150, 1164, 1043,
114975  /*   350 */  1139, 1137, 1113, 1114, 1006, 1058, 1018, 1023, 1066, 1057,
114976  /*   360 */   968, 1091, 1086, 1063,  981,  944, 1011, 1035, 1010, 1000,
114977  /*   370 */  1014,  916, 1033, 1004, 1001,  909,  913,  996,  957,  991,
114978  /*   380 */   990,  986,  964,  938,  954,  917,  889,  897,  912,  910,
114979  /*   390 */   797,  886,  761,  838,  528,  726,  735,  765,  665,  726,
114980  /*   400 */   592,  586,  540,  523,  491,  487,  435,  401,  397,  387,
114981  /*   410 */   249,  216,  185,  127,  110,   51,   82,  143,   15,   48,
114982 };
114983 #define YY_REDUCE_USE_DFLT (-143)
114984 #define YY_REDUCE_COUNT (311)
114985 #define YY_REDUCE_MIN   (-142)
114986 #define YY_REDUCE_MAX   (1387)
114987 static const short yy_reduce_ofst[] = {
114988  /*     0 */  -142, 1111,   92,  151,  241,  161,  150,   93,   85,  324,
114989  /*    10 */   386,  313,  320,  229,   -6,  310,  536,  485,  -72, 1121,
114990  /*    20 */  1089, 1082, 1076, 1054, 1037,  997,  979,  977,  975,  962,
114991  /*    30 */   923,  921,  904,  902,  900,  887,  847,  829,  827,  825,
114992  /*    40 */   812,  771,  769,  754,  752,  750,  737,  679,  677,  675,
114993  /*    50 */   662,  623,  619,  617,  613,  602,  600,  587,  537,  527,
114994  /*    60 */   472,  376,  480,  450,  226,  453,  398,  390,  426,  420,
114995  /*    70 */   420,  420,  420,  420,  420,  420,  420,  420,  420,  420,
114996  /*    80 */   420,  420,  420,  420,  420,  420,  420,  420,  420,  420,
114997  /*    90 */   420,  420,  420,  420,  420,  420,  420,  420,  420,  420,
114998  /*   100 */   420,  420,  420,  420,  420,  420,  420, 1153,  922, 1123,
114999  /*   110 */  1115, 1055, 1007,  980,  976,  901,  844,  830,  767,  826,
115000  /*   120 */   682,  694,  707,  482,  583,  681,  680,  676,  531,   27,
115001  /*   130 */   787,  562,  521,  420,  420,  420,  420,  420,  773,  741,
115002  /*   140 */   674,  670, 1067, 1251, 1245, 1239, 1234,  591,  591, 1230,
115003  /*   150 */  1228, 1226, 1221, 1219, 1213, 1207, 1206, 1202, 1201, 1200,
115004  /*   160 */  1199, 1193, 1189, 1178, 1176, 1174, 1155, 1142, 1138, 1134,
115005  /*   170 */  1116, 1112, 1077, 1074, 1069, 1067, 1009,  994,  982,  933,
115006  /*   180 */   848,  757,  849,  775,  628,  611,  745,  710,  672,  469,
115007  /*   190 */   488,  573, 1387, 1384, 1367, 1374, 1373, 1372, 1344, 1354,
115008  /*   200 */  1360, 1354, 1354, 1354, 1354, 1354, 1354, 1354, 1330, 1326,
115009  /*   210 */  1354, 1354, 1344, 1371, 1336, 1386, 1349, 1338, 1334, 1305,
115010  /*   220 */  1331, 1299, 1359, 1346, 1361, 1353, 1358, 1352, 1341, 1345,
115011  /*   230 */  1316, 1293, 1296, 1286, 1351, 1325, 1324, 1363, 1275, 1356,
115012  /*   240 */  1355, 1270, 1267, 1350, 1282, 1319, 1306, 1312, 1311, 1310,
115013  /*   250 */  1309, 1343, 1339, 1298, 1274, 1301, 1297, 1288, 1329, 1328,
115014  /*   260 */  1248, 1246, 1323, 1322, 1318, 1321, 1317, 1315, 1313, 1276,
115015  /*   270 */  1291, 1289, 1287, 1278, 1235, 1224, 1271, 1273, 1264, 1265,
115016  /*   280 */  1247, 1252, 1240, 1218, 1229, 1217, 1216, 1214, 1212, 1262,
115017  /*   290 */  1261, 1182, 1205, 1203, 1186, 1185, 1175, 1167, 1169, 1159,
115018  /*   300 */  1165, 1132, 1152, 1145, 1144, 1105, 1030, 1008,  999, 1073,
115019  /*   310 */  1072, 1080,
115020 };
115021 static const YYACTIONTYPE yy_default[] = {
115022  /*     0 */   636,  872,  960,  960,  872,  872,  960,  960,  960,  762,
115023  /*    10 */   960,  960,  960,  870,  960,  960,  790,  790,  934,  960,
115024  /*    20 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115025  /*    30 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115026  /*    40 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115027  /*    50 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115028  /*    60 */   960,  960,  960,  960,  960,  960,  960,  677,  766,  796,
115029  /*    70 */   960,  960,  960,  960,  960,  960,  960,  960,  933,  935,
115030  /*    80 */   804,  803,  913,  777,  801,  794,  798,  873,  866,  867,
115031  /*    90 */   865,  869,  874,  960,  797,  833,  850,  832,  844,  849,
115032  /*   100 */   856,  848,  845,  835,  834,  836,  837,  960,  960,  960,
115033  /*   110 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115034  /*   120 */   960,  960,  960,  662,  731,  960,  960,  960,  960,  960,
115035  /*   130 */   960,  960,  960,  838,  839,  853,  852,  851,  960,  669,
115036  /*   140 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115037  /*   150 */   940,  938,  960,  885,  960,  960,  960,  960,  960,  960,
115038  /*   160 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115039  /*   170 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115040  /*   180 */   960,  642,  762,  762,  762,  636,  960,  960,  960,  952,
115041  /*   190 */   766,  756,  960,  960,  960,  960,  960,  960,  960,  960,
115042  /*   200 */   960,  960,  960,  960,  806,  745,  923,  925,  960,  906,
115043  /*   210 */   743,  664,  764,  679,  754,  644,  800,  779,  779,  918,
115044  /*   220 */   800,  918,  702,  725,  960,  790,  960,  790,  699,  790,
115045  /*   230 */   779,  868,  960,  960,  960,  763,  754,  960,  945,  770,
115046  /*   240 */   770,  937,  937,  770,  812,  735,  800,  742,  742,  742,
115047  /*   250 */   742,  770,  659,  800,  812,  735,  735,  800,  770,  659,
115048  /*   260 */   912,  910,  770,  770,  659,  770,  659,  770,  659,  878,
115049  /*   270 */   733,  733,  733,  717,  882,  882,  878,  733,  702,  733,
115050  /*   280 */   717,  733,  733,  783,  778,  783,  778,  783,  778,  770,
115051  /*   290 */   770,  960,  795,  784,  793,  791,  800,  960,  665,  720,
115052  /*   300 */   652,  652,  641,  641,  641,  641,  957,  957,  952,  704,
115053  /*   310 */   704,  687,  960,  960,  960,  960,  960,  960,  960,  887,
115054  /*   320 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115055  /*   330 */   960,  960,  637,  947,  960,  960,  944,  960,  960,  960,
115056  /*   340 */   960,  805,  960,  960,  960,  960,  960,  960,  960,  960,
115057  /*   350 */   960,  960,  922,  960,  960,  960,  960,  960,  960,  960,
115058  /*   360 */   916,  960,  960,  960,  960,  960,  960,  909,  908,  960,
115059  /*   370 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115060  /*   380 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115061  /*   390 */   960,  960,  960,  960,  960,  792,  960,  785,  960,  871,
115062  /*   400 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115063  /*   410 */   748,  821,  960,  820,  824,  819,  671,  960,  650,  960,
115064  /*   420 */   633,  638,  956,  959,  958,  955,  954,  953,  948,  946,
115065  /*   430 */   943,  942,  941,  939,  936,  932,  891,  889,  896,  895,
115066  /*   440 */   894,  893,  892,  890,  888,  886,  807,  802,  799,  931,
115067  /*   450 */   884,  744,  741,  740,  658,  949,  915,  924,  811,  810,
115068  /*   460 */   813,  921,  920,  919,  917,  914,  901,  809,  808,  736,
115069  /*   470 */   876,  875,  661,  905,  904,  903,  907,  911,  902,  772,
115070  /*   480 */   660,  657,  668,  723,  724,  732,  730,  729,  728,  727,
115071  /*   490 */   726,  722,  670,  678,  716,  701,  700,  881,  883,  880,
115072  /*   500 */   879,  709,  708,  714,  713,  712,  711,  710,  707,  706,
115073  /*   510 */   705,  698,  697,  703,  696,  719,  718,  715,  695,  739,
115074  /*   520 */   738,  737,  734,  694,  693,  692,  824,  691,  690,  830,
115075  /*   530 */   829,  817,  860,  759,  758,  757,  769,  768,  781,  780,
115076  /*   540 */   815,  814,  782,  767,  761,  760,  776,  775,  774,  773,
115077  /*   550 */   765,  755,  787,  789,  788,  786,  862,  771,  859,  930,
115078  /*   560 */   929,  928,  927,  926,  864,  863,  831,  828,  682,  683,
115079  /*   570 */   899,  898,  900,  897,  685,  684,  681,  680,  861,  750,
115080  /*   580 */   749,  857,  854,  846,  842,  858,  855,  847,  843,  841,
115081  /*   590 */   840,  826,  825,  823,  822,  818,  827,  673,  751,  747,
115082  /*   600 */   746,  816,  753,  752,  689,  688,  686,  667,  666,  663,
115083  /*   610 */   656,  654,  653,  655,  651,  649,  648,  647,  646,  645,
115084  /*   620 */   676,  675,  674,  672,  671,  643,  640,  639,  635,  634,
115085  /*   630 */   632,
115086 };
115087 
115088 /* The next table maps tokens into fallback tokens.  If a construct
115089 ** like the following:
115090 ** 
115091 **      %fallback ID X Y Z.
115092 **
115093 ** appears in the grammar, then ID becomes a fallback token for X, Y,
115094 ** and Z.  Whenever one of the tokens X, Y, or Z is input to the parser
115095 ** but it does not parse, the type of the token is changed to ID and
115096 ** the parse is retried before an error is thrown.
115097 */
115098 #ifdef YYFALLBACK
115099 static const YYCODETYPE yyFallback[] = {
115100     0,  /*          $ => nothing */
115101     0,  /*       SEMI => nothing */
115102    27,  /*    EXPLAIN => ID */
115103    27,  /*      QUERY => ID */
115104    27,  /*       PLAN => ID */
115105    27,  /*      BEGIN => ID */
115106     0,  /* TRANSACTION => nothing */
115107    27,  /*   DEFERRED => ID */
115108    27,  /*  IMMEDIATE => ID */
115109    27,  /*  EXCLUSIVE => ID */
115110     0,  /*     COMMIT => nothing */
115111    27,  /*        END => ID */
115112    27,  /*   ROLLBACK => ID */
115113    27,  /*  SAVEPOINT => ID */
115114    27,  /*    RELEASE => ID */
115115     0,  /*         TO => nothing */
115116     0,  /*      TABLE => nothing */
115117     0,  /*     CREATE => nothing */
115118    27,  /*         IF => ID */
115119     0,  /*        NOT => nothing */
115120     0,  /*     EXISTS => nothing */
115121    27,  /*       TEMP => ID */
115122     0,  /*         LP => nothing */
115123     0,  /*         RP => nothing */
115124     0,  /*         AS => nothing */
115125    27,  /*    WITHOUT => ID */
115126     0,  /*      COMMA => nothing */
115127     0,  /*         ID => nothing */
115128     0,  /*    INDEXED => nothing */
115129    27,  /*      ABORT => ID */
115130    27,  /*     ACTION => ID */
115131    27,  /*      AFTER => ID */
115132    27,  /*    ANALYZE => ID */
115133    27,  /*        ASC => ID */
115134    27,  /*     ATTACH => ID */
115135    27,  /*     BEFORE => ID */
115136    27,  /*         BY => ID */
115137    27,  /*    CASCADE => ID */
115138    27,  /*       CAST => ID */
115139    27,  /*   COLUMNKW => ID */
115140    27,  /*   CONFLICT => ID */
115141    27,  /*   DATABASE => ID */
115142    27,  /*       DESC => ID */
115143    27,  /*     DETACH => ID */
115144    27,  /*       EACH => ID */
115145    27,  /*       FAIL => ID */
115146    27,  /*        FOR => ID */
115147    27,  /*     IGNORE => ID */
115148    27,  /*  INITIALLY => ID */
115149    27,  /*    INSTEAD => ID */
115150    27,  /*    LIKE_KW => ID */
115151    27,  /*      MATCH => ID */
115152    27,  /*         NO => ID */
115153    27,  /*        KEY => ID */
115154    27,  /*         OF => ID */
115155    27,  /*     OFFSET => ID */
115156    27,  /*     PRAGMA => ID */
115157    27,  /*      RAISE => ID */
115158    27,  /*    REPLACE => ID */
115159    27,  /*   RESTRICT => ID */
115160    27,  /*        ROW => ID */
115161    27,  /*    TRIGGER => ID */
115162    27,  /*     VACUUM => ID */
115163    27,  /*       VIEW => ID */
115164    27,  /*    VIRTUAL => ID */
115165    27,  /*    REINDEX => ID */
115166    27,  /*     RENAME => ID */
115167    27,  /*   CTIME_KW => ID */
115168 };
115169 #endif /* YYFALLBACK */
115170 
115171 /* The following structure represents a single element of the
115172 ** parser's stack.  Information stored includes:
115173 **
115174 **   +  The state number for the parser at this level of the stack.
115175 **
115176 **   +  The value of the token stored at this level of the stack.
115177 **      (In other words, the "major" token.)
115178 **
115179 **   +  The semantic value stored at this level of the stack.  This is
115180 **      the information used by the action routines in the grammar.
115181 **      It is sometimes called the "minor" token.
115182 */
115183 struct yyStackEntry {
115184   YYACTIONTYPE stateno;  /* The state-number */
115185   YYCODETYPE major;      /* The major token value.  This is the code
115186                          ** number for the token at this stack level */
115187   YYMINORTYPE minor;     /* The user-supplied minor token value.  This
115188                          ** is the value of the token  */
115189 };
115190 typedef struct yyStackEntry yyStackEntry;
115191 
115192 /* The state of the parser is completely contained in an instance of
115193 ** the following structure */
115194 struct yyParser {
115195   int yyidx;                    /* Index of top element in stack */
115196 #ifdef YYTRACKMAXSTACKDEPTH
115197   int yyidxMax;                 /* Maximum value of yyidx */
115198 #endif
115199   int yyerrcnt;                 /* Shifts left before out of the error */
115200   sqlite3ParserARG_SDECL                /* A place to hold %extra_argument */
115201 #if YYSTACKDEPTH<=0
115202   int yystksz;                  /* Current side of the stack */
115203   yyStackEntry *yystack;        /* The parser's stack */
115204 #else
115205   yyStackEntry yystack[YYSTACKDEPTH];  /* The parser's stack */
115206 #endif
115207 };
115208 typedef struct yyParser yyParser;
115209 
115210 #ifndef NDEBUG
115211 /* #include <stdio.h> */
115212 static FILE *yyTraceFILE = 0;
115213 static char *yyTracePrompt = 0;
115214 #endif /* NDEBUG */
115215 
115216 #ifndef NDEBUG
115217 /* 
115218 ** Turn parser tracing on by giving a stream to which to write the trace
115219 ** and a prompt to preface each trace message.  Tracing is turned off
115220 ** by making either argument NULL 
115221 **
115222 ** Inputs:
115223 ** <ul>
115224 ** <li> A FILE* to which trace output should be written.
115225 **      If NULL, then tracing is turned off.
115226 ** <li> A prefix string written at the beginning of every
115227 **      line of trace output.  If NULL, then tracing is
115228 **      turned off.
115229 ** </ul>
115230 **
115231 ** Outputs:
115232 ** None.
115233 */
115234 SQLITE_PRIVATE void sqlite3ParserTrace(FILE *TraceFILE, char *zTracePrompt){
115235   yyTraceFILE = TraceFILE;
115236   yyTracePrompt = zTracePrompt;
115237   if( yyTraceFILE==0 ) yyTracePrompt = 0;
115238   else if( yyTracePrompt==0 ) yyTraceFILE = 0;
115239 }
115240 #endif /* NDEBUG */
115241 
115242 #ifndef NDEBUG
115243 /* For tracing shifts, the names of all terminals and nonterminals
115244 ** are required.  The following table supplies these names */
115245 static const char *const yyTokenName[] = { 
115246   "$",             "SEMI",          "EXPLAIN",       "QUERY",       
115247   "PLAN",          "BEGIN",         "TRANSACTION",   "DEFERRED",    
115248   "IMMEDIATE",     "EXCLUSIVE",     "COMMIT",        "END",         
115249   "ROLLBACK",      "SAVEPOINT",     "RELEASE",       "TO",          
115250   "TABLE",         "CREATE",        "IF",            "NOT",         
115251   "EXISTS",        "TEMP",          "LP",            "RP",          
115252   "AS",            "WITHOUT",       "COMMA",         "ID",          
115253   "INDEXED",       "ABORT",         "ACTION",        "AFTER",       
115254   "ANALYZE",       "ASC",           "ATTACH",        "BEFORE",      
115255   "BY",            "CASCADE",       "CAST",          "COLUMNKW",    
115256   "CONFLICT",      "DATABASE",      "DESC",          "DETACH",      
115257   "EACH",          "FAIL",          "FOR",           "IGNORE",      
115258   "INITIALLY",     "INSTEAD",       "LIKE_KW",       "MATCH",       
115259   "NO",            "KEY",           "OF",            "OFFSET",      
115260   "PRAGMA",        "RAISE",         "REPLACE",       "RESTRICT",    
115261   "ROW",           "TRIGGER",       "VACUUM",        "VIEW",        
115262   "VIRTUAL",       "REINDEX",       "RENAME",        "CTIME_KW",    
115263   "ANY",           "OR",            "AND",           "IS",          
115264   "BETWEEN",       "IN",            "ISNULL",        "NOTNULL",     
115265   "NE",            "EQ",            "GT",            "LE",          
115266   "LT",            "GE",            "ESCAPE",        "BITAND",      
115267   "BITOR",         "LSHIFT",        "RSHIFT",        "PLUS",        
115268   "MINUS",         "STAR",          "SLASH",         "REM",         
115269   "CONCAT",        "COLLATE",       "BITNOT",        "STRING",      
115270   "JOIN_KW",       "CONSTRAINT",    "DEFAULT",       "NULL",        
115271   "PRIMARY",       "UNIQUE",        "CHECK",         "REFERENCES",  
115272   "AUTOINCR",      "ON",            "INSERT",        "DELETE",      
115273   "UPDATE",        "SET",           "DEFERRABLE",    "FOREIGN",     
115274   "DROP",          "UNION",         "ALL",           "EXCEPT",      
115275   "INTERSECT",     "SELECT",        "DISTINCT",      "DOT",         
115276   "FROM",          "JOIN",          "USING",         "ORDER",       
115277   "GROUP",         "HAVING",        "LIMIT",         "WHERE",       
115278   "INTO",          "VALUES",        "INTEGER",       "FLOAT",       
115279   "BLOB",          "REGISTER",      "VARIABLE",      "CASE",        
115280   "WHEN",          "THEN",          "ELSE",          "INDEX",       
115281   "ALTER",         "ADD",           "error",         "input",       
115282   "cmdlist",       "ecmd",          "explain",       "cmdx",        
115283   "cmd",           "transtype",     "trans_opt",     "nm",          
115284   "savepoint_opt",  "create_table",  "create_table_args",  "createkw",    
115285   "temp",          "ifnotexists",   "dbnm",          "columnlist",  
115286   "conslist_opt",  "table_options",  "select",        "column",      
115287   "columnid",      "type",          "carglist",      "id",          
115288   "ids",           "typetoken",     "typename",      "signed",      
115289   "plus_num",      "minus_num",     "ccons",         "term",        
115290   "expr",          "onconf",        "sortorder",     "autoinc",     
115291   "idxlist_opt",   "refargs",       "defer_subclause",  "refarg",      
115292   "refact",        "init_deferred_pred_opt",  "conslist",      "tconscomma",  
115293   "tcons",         "idxlist",       "defer_subclause_opt",  "orconf",      
115294   "resolvetype",   "raisetype",     "ifexists",      "fullname",    
115295   "oneselect",     "multiselect_op",  "distinct",      "selcollist",  
115296   "from",          "where_opt",     "groupby_opt",   "having_opt",  
115297   "orderby_opt",   "limit_opt",     "sclp",          "as",          
115298   "seltablist",    "stl_prefix",    "joinop",        "indexed_opt", 
115299   "on_opt",        "using_opt",     "joinop2",       "idlist",      
115300   "sortlist",      "nexprlist",     "setlist",       "insert_cmd",  
115301   "inscollist_opt",  "valuelist",     "exprlist",      "likeop",      
115302   "between_op",    "in_op",         "case_operand",  "case_exprlist",
115303   "case_else",     "uniqueflag",    "collate",       "nmnum",       
115304   "number",        "trigger_decl",  "trigger_cmd_list",  "trigger_time",
115305   "trigger_event",  "foreach_clause",  "when_clause",   "trigger_cmd", 
115306   "trnm",          "tridxby",       "database_kw_opt",  "key_opt",     
115307   "add_column_fullname",  "kwcolumn_opt",  "create_vtab",   "vtabarglist", 
115308   "vtabarg",       "vtabargtoken",  "lp",            "anylist",     
115309 };
115310 #endif /* NDEBUG */
115311 
115312 #ifndef NDEBUG
115313 /* For tracing reduce actions, the names of all rules are required.
115314 */
115315 static const char *const yyRuleName[] = {
115316  /*   0 */ "input ::= cmdlist",
115317  /*   1 */ "cmdlist ::= cmdlist ecmd",
115318  /*   2 */ "cmdlist ::= ecmd",
115319  /*   3 */ "ecmd ::= SEMI",
115320  /*   4 */ "ecmd ::= explain cmdx SEMI",
115321  /*   5 */ "explain ::=",
115322  /*   6 */ "explain ::= EXPLAIN",
115323  /*   7 */ "explain ::= EXPLAIN QUERY PLAN",
115324  /*   8 */ "cmdx ::= cmd",
115325  /*   9 */ "cmd ::= BEGIN transtype trans_opt",
115326  /*  10 */ "trans_opt ::=",
115327  /*  11 */ "trans_opt ::= TRANSACTION",
115328  /*  12 */ "trans_opt ::= TRANSACTION nm",
115329  /*  13 */ "transtype ::=",
115330  /*  14 */ "transtype ::= DEFERRED",
115331  /*  15 */ "transtype ::= IMMEDIATE",
115332  /*  16 */ "transtype ::= EXCLUSIVE",
115333  /*  17 */ "cmd ::= COMMIT trans_opt",
115334  /*  18 */ "cmd ::= END trans_opt",
115335  /*  19 */ "cmd ::= ROLLBACK trans_opt",
115336  /*  20 */ "savepoint_opt ::= SAVEPOINT",
115337  /*  21 */ "savepoint_opt ::=",
115338  /*  22 */ "cmd ::= SAVEPOINT nm",
115339  /*  23 */ "cmd ::= RELEASE savepoint_opt nm",
115340  /*  24 */ "cmd ::= ROLLBACK trans_opt TO savepoint_opt nm",
115341  /*  25 */ "cmd ::= create_table create_table_args",
115342  /*  26 */ "create_table ::= createkw temp TABLE ifnotexists nm dbnm",
115343  /*  27 */ "createkw ::= CREATE",
115344  /*  28 */ "ifnotexists ::=",
115345  /*  29 */ "ifnotexists ::= IF NOT EXISTS",
115346  /*  30 */ "temp ::= TEMP",
115347  /*  31 */ "temp ::=",
115348  /*  32 */ "create_table_args ::= LP columnlist conslist_opt RP table_options",
115349  /*  33 */ "create_table_args ::= AS select",
115350  /*  34 */ "table_options ::=",
115351  /*  35 */ "table_options ::= WITHOUT nm",
115352  /*  36 */ "columnlist ::= columnlist COMMA column",
115353  /*  37 */ "columnlist ::= column",
115354  /*  38 */ "column ::= columnid type carglist",
115355  /*  39 */ "columnid ::= nm",
115356  /*  40 */ "id ::= ID",
115357  /*  41 */ "id ::= INDEXED",
115358  /*  42 */ "ids ::= ID|STRING",
115359  /*  43 */ "nm ::= id",
115360  /*  44 */ "nm ::= STRING",
115361  /*  45 */ "nm ::= JOIN_KW",
115362  /*  46 */ "type ::=",
115363  /*  47 */ "type ::= typetoken",
115364  /*  48 */ "typetoken ::= typename",
115365  /*  49 */ "typetoken ::= typename LP signed RP",
115366  /*  50 */ "typetoken ::= typename LP signed COMMA signed RP",
115367  /*  51 */ "typename ::= ids",
115368  /*  52 */ "typename ::= typename ids",
115369  /*  53 */ "signed ::= plus_num",
115370  /*  54 */ "signed ::= minus_num",
115371  /*  55 */ "carglist ::= carglist ccons",
115372  /*  56 */ "carglist ::=",
115373  /*  57 */ "ccons ::= CONSTRAINT nm",
115374  /*  58 */ "ccons ::= DEFAULT term",
115375  /*  59 */ "ccons ::= DEFAULT LP expr RP",
115376  /*  60 */ "ccons ::= DEFAULT PLUS term",
115377  /*  61 */ "ccons ::= DEFAULT MINUS term",
115378  /*  62 */ "ccons ::= DEFAULT id",
115379  /*  63 */ "ccons ::= NULL onconf",
115380  /*  64 */ "ccons ::= NOT NULL onconf",
115381  /*  65 */ "ccons ::= PRIMARY KEY sortorder onconf autoinc",
115382  /*  66 */ "ccons ::= UNIQUE onconf",
115383  /*  67 */ "ccons ::= CHECK LP expr RP",
115384  /*  68 */ "ccons ::= REFERENCES nm idxlist_opt refargs",
115385  /*  69 */ "ccons ::= defer_subclause",
115386  /*  70 */ "ccons ::= COLLATE ids",
115387  /*  71 */ "autoinc ::=",
115388  /*  72 */ "autoinc ::= AUTOINCR",
115389  /*  73 */ "refargs ::=",
115390  /*  74 */ "refargs ::= refargs refarg",
115391  /*  75 */ "refarg ::= MATCH nm",
115392  /*  76 */ "refarg ::= ON INSERT refact",
115393  /*  77 */ "refarg ::= ON DELETE refact",
115394  /*  78 */ "refarg ::= ON UPDATE refact",
115395  /*  79 */ "refact ::= SET NULL",
115396  /*  80 */ "refact ::= SET DEFAULT",
115397  /*  81 */ "refact ::= CASCADE",
115398  /*  82 */ "refact ::= RESTRICT",
115399  /*  83 */ "refact ::= NO ACTION",
115400  /*  84 */ "defer_subclause ::= NOT DEFERRABLE init_deferred_pred_opt",
115401  /*  85 */ "defer_subclause ::= DEFERRABLE init_deferred_pred_opt",
115402  /*  86 */ "init_deferred_pred_opt ::=",
115403  /*  87 */ "init_deferred_pred_opt ::= INITIALLY DEFERRED",
115404  /*  88 */ "init_deferred_pred_opt ::= INITIALLY IMMEDIATE",
115405  /*  89 */ "conslist_opt ::=",
115406  /*  90 */ "conslist_opt ::= COMMA conslist",
115407  /*  91 */ "conslist ::= conslist tconscomma tcons",
115408  /*  92 */ "conslist ::= tcons",
115409  /*  93 */ "tconscomma ::= COMMA",
115410  /*  94 */ "tconscomma ::=",
115411  /*  95 */ "tcons ::= CONSTRAINT nm",
115412  /*  96 */ "tcons ::= PRIMARY KEY LP idxlist autoinc RP onconf",
115413  /*  97 */ "tcons ::= UNIQUE LP idxlist RP onconf",
115414  /*  98 */ "tcons ::= CHECK LP expr RP onconf",
115415  /*  99 */ "tcons ::= FOREIGN KEY LP idxlist RP REFERENCES nm idxlist_opt refargs defer_subclause_opt",
115416  /* 100 */ "defer_subclause_opt ::=",
115417  /* 101 */ "defer_subclause_opt ::= defer_subclause",
115418  /* 102 */ "onconf ::=",
115419  /* 103 */ "onconf ::= ON CONFLICT resolvetype",
115420  /* 104 */ "orconf ::=",
115421  /* 105 */ "orconf ::= OR resolvetype",
115422  /* 106 */ "resolvetype ::= raisetype",
115423  /* 107 */ "resolvetype ::= IGNORE",
115424  /* 108 */ "resolvetype ::= REPLACE",
115425  /* 109 */ "cmd ::= DROP TABLE ifexists fullname",
115426  /* 110 */ "ifexists ::= IF EXISTS",
115427  /* 111 */ "ifexists ::=",
115428  /* 112 */ "cmd ::= createkw temp VIEW ifnotexists nm dbnm AS select",
115429  /* 113 */ "cmd ::= DROP VIEW ifexists fullname",
115430  /* 114 */ "cmd ::= select",
115431  /* 115 */ "select ::= oneselect",
115432  /* 116 */ "select ::= select multiselect_op oneselect",
115433  /* 117 */ "multiselect_op ::= UNION",
115434  /* 118 */ "multiselect_op ::= UNION ALL",
115435  /* 119 */ "multiselect_op ::= EXCEPT|INTERSECT",
115436  /* 120 */ "oneselect ::= SELECT distinct selcollist from where_opt groupby_opt having_opt orderby_opt limit_opt",
115437  /* 121 */ "distinct ::= DISTINCT",
115438  /* 122 */ "distinct ::= ALL",
115439  /* 123 */ "distinct ::=",
115440  /* 124 */ "sclp ::= selcollist COMMA",
115441  /* 125 */ "sclp ::=",
115442  /* 126 */ "selcollist ::= sclp expr as",
115443  /* 127 */ "selcollist ::= sclp STAR",
115444  /* 128 */ "selcollist ::= sclp nm DOT STAR",
115445  /* 129 */ "as ::= AS nm",
115446  /* 130 */ "as ::= ids",
115447  /* 131 */ "as ::=",
115448  /* 132 */ "from ::=",
115449  /* 133 */ "from ::= FROM seltablist",
115450  /* 134 */ "stl_prefix ::= seltablist joinop",
115451  /* 135 */ "stl_prefix ::=",
115452  /* 136 */ "seltablist ::= stl_prefix nm dbnm as indexed_opt on_opt using_opt",
115453  /* 137 */ "seltablist ::= stl_prefix LP select RP as on_opt using_opt",
115454  /* 138 */ "seltablist ::= stl_prefix LP seltablist RP as on_opt using_opt",
115455  /* 139 */ "dbnm ::=",
115456  /* 140 */ "dbnm ::= DOT nm",
115457  /* 141 */ "fullname ::= nm dbnm",
115458  /* 142 */ "joinop ::= COMMA|JOIN",
115459  /* 143 */ "joinop ::= JOIN_KW JOIN",
115460  /* 144 */ "joinop ::= JOIN_KW nm JOIN",
115461  /* 145 */ "joinop ::= JOIN_KW nm nm JOIN",
115462  /* 146 */ "on_opt ::= ON expr",
115463  /* 147 */ "on_opt ::=",
115464  /* 148 */ "indexed_opt ::=",
115465  /* 149 */ "indexed_opt ::= INDEXED BY nm",
115466  /* 150 */ "indexed_opt ::= NOT INDEXED",
115467  /* 151 */ "using_opt ::= USING LP idlist RP",
115468  /* 152 */ "using_opt ::=",
115469  /* 153 */ "orderby_opt ::=",
115470  /* 154 */ "orderby_opt ::= ORDER BY sortlist",
115471  /* 155 */ "sortlist ::= sortlist COMMA expr sortorder",
115472  /* 156 */ "sortlist ::= expr sortorder",
115473  /* 157 */ "sortorder ::= ASC",
115474  /* 158 */ "sortorder ::= DESC",
115475  /* 159 */ "sortorder ::=",
115476  /* 160 */ "groupby_opt ::=",
115477  /* 161 */ "groupby_opt ::= GROUP BY nexprlist",
115478  /* 162 */ "having_opt ::=",
115479  /* 163 */ "having_opt ::= HAVING expr",
115480  /* 164 */ "limit_opt ::=",
115481  /* 165 */ "limit_opt ::= LIMIT expr",
115482  /* 166 */ "limit_opt ::= LIMIT expr OFFSET expr",
115483  /* 167 */ "limit_opt ::= LIMIT expr COMMA expr",
115484  /* 168 */ "cmd ::= DELETE FROM fullname indexed_opt where_opt",
115485  /* 169 */ "where_opt ::=",
115486  /* 170 */ "where_opt ::= WHERE expr",
115487  /* 171 */ "cmd ::= UPDATE orconf fullname indexed_opt SET setlist where_opt",
115488  /* 172 */ "setlist ::= setlist COMMA nm EQ expr",
115489  /* 173 */ "setlist ::= nm EQ expr",
115490  /* 174 */ "cmd ::= insert_cmd INTO fullname inscollist_opt valuelist",
115491  /* 175 */ "cmd ::= insert_cmd INTO fullname inscollist_opt select",
115492  /* 176 */ "cmd ::= insert_cmd INTO fullname inscollist_opt DEFAULT VALUES",
115493  /* 177 */ "insert_cmd ::= INSERT orconf",
115494  /* 178 */ "insert_cmd ::= REPLACE",
115495  /* 179 */ "valuelist ::= VALUES LP nexprlist RP",
115496  /* 180 */ "valuelist ::= valuelist COMMA LP exprlist RP",
115497  /* 181 */ "inscollist_opt ::=",
115498  /* 182 */ "inscollist_opt ::= LP idlist RP",
115499  /* 183 */ "idlist ::= idlist COMMA nm",
115500  /* 184 */ "idlist ::= nm",
115501  /* 185 */ "expr ::= term",
115502  /* 186 */ "expr ::= LP expr RP",
115503  /* 187 */ "term ::= NULL",
115504  /* 188 */ "expr ::= id",
115505  /* 189 */ "expr ::= JOIN_KW",
115506  /* 190 */ "expr ::= nm DOT nm",
115507  /* 191 */ "expr ::= nm DOT nm DOT nm",
115508  /* 192 */ "term ::= INTEGER|FLOAT|BLOB",
115509  /* 193 */ "term ::= STRING",
115510  /* 194 */ "expr ::= REGISTER",
115511  /* 195 */ "expr ::= VARIABLE",
115512  /* 196 */ "expr ::= expr COLLATE ids",
115513  /* 197 */ "expr ::= CAST LP expr AS typetoken RP",
115514  /* 198 */ "expr ::= ID LP distinct exprlist RP",
115515  /* 199 */ "expr ::= ID LP STAR RP",
115516  /* 200 */ "term ::= CTIME_KW",
115517  /* 201 */ "expr ::= expr AND expr",
115518  /* 202 */ "expr ::= expr OR expr",
115519  /* 203 */ "expr ::= expr LT|GT|GE|LE expr",
115520  /* 204 */ "expr ::= expr EQ|NE expr",
115521  /* 205 */ "expr ::= expr BITAND|BITOR|LSHIFT|RSHIFT expr",
115522  /* 206 */ "expr ::= expr PLUS|MINUS expr",
115523  /* 207 */ "expr ::= expr STAR|SLASH|REM expr",
115524  /* 208 */ "expr ::= expr CONCAT expr",
115525  /* 209 */ "likeop ::= LIKE_KW",
115526  /* 210 */ "likeop ::= NOT LIKE_KW",
115527  /* 211 */ "likeop ::= MATCH",
115528  /* 212 */ "likeop ::= NOT MATCH",
115529  /* 213 */ "expr ::= expr likeop expr",
115530  /* 214 */ "expr ::= expr likeop expr ESCAPE expr",
115531  /* 215 */ "expr ::= expr ISNULL|NOTNULL",
115532  /* 216 */ "expr ::= expr NOT NULL",
115533  /* 217 */ "expr ::= expr IS expr",
115534  /* 218 */ "expr ::= expr IS NOT expr",
115535  /* 219 */ "expr ::= NOT expr",
115536  /* 220 */ "expr ::= BITNOT expr",
115537  /* 221 */ "expr ::= MINUS expr",
115538  /* 222 */ "expr ::= PLUS expr",
115539  /* 223 */ "between_op ::= BETWEEN",
115540  /* 224 */ "between_op ::= NOT BETWEEN",
115541  /* 225 */ "expr ::= expr between_op expr AND expr",
115542  /* 226 */ "in_op ::= IN",
115543  /* 227 */ "in_op ::= NOT IN",
115544  /* 228 */ "expr ::= expr in_op LP exprlist RP",
115545  /* 229 */ "expr ::= LP select RP",
115546  /* 230 */ "expr ::= expr in_op LP select RP",
115547  /* 231 */ "expr ::= expr in_op nm dbnm",
115548  /* 232 */ "expr ::= EXISTS LP select RP",
115549  /* 233 */ "expr ::= CASE case_operand case_exprlist case_else END",
115550  /* 234 */ "case_exprlist ::= case_exprlist WHEN expr THEN expr",
115551  /* 235 */ "case_exprlist ::= WHEN expr THEN expr",
115552  /* 236 */ "case_else ::= ELSE expr",
115553  /* 237 */ "case_else ::=",
115554  /* 238 */ "case_operand ::= expr",
115555  /* 239 */ "case_operand ::=",
115556  /* 240 */ "exprlist ::= nexprlist",
115557  /* 241 */ "exprlist ::=",
115558  /* 242 */ "nexprlist ::= nexprlist COMMA expr",
115559  /* 243 */ "nexprlist ::= expr",
115560  /* 244 */ "cmd ::= createkw uniqueflag INDEX ifnotexists nm dbnm ON nm LP idxlist RP where_opt",
115561  /* 245 */ "uniqueflag ::= UNIQUE",
115562  /* 246 */ "uniqueflag ::=",
115563  /* 247 */ "idxlist_opt ::=",
115564  /* 248 */ "idxlist_opt ::= LP idxlist RP",
115565  /* 249 */ "idxlist ::= idxlist COMMA nm collate sortorder",
115566  /* 250 */ "idxlist ::= nm collate sortorder",
115567  /* 251 */ "collate ::=",
115568  /* 252 */ "collate ::= COLLATE ids",
115569  /* 253 */ "cmd ::= DROP INDEX ifexists fullname",
115570  /* 254 */ "cmd ::= VACUUM",
115571  /* 255 */ "cmd ::= VACUUM nm",
115572  /* 256 */ "cmd ::= PRAGMA nm dbnm",
115573  /* 257 */ "cmd ::= PRAGMA nm dbnm EQ nmnum",
115574  /* 258 */ "cmd ::= PRAGMA nm dbnm LP nmnum RP",
115575  /* 259 */ "cmd ::= PRAGMA nm dbnm EQ minus_num",
115576  /* 260 */ "cmd ::= PRAGMA nm dbnm LP minus_num RP",
115577  /* 261 */ "nmnum ::= plus_num",
115578  /* 262 */ "nmnum ::= nm",
115579  /* 263 */ "nmnum ::= ON",
115580  /* 264 */ "nmnum ::= DELETE",
115581  /* 265 */ "nmnum ::= DEFAULT",
115582  /* 266 */ "plus_num ::= PLUS number",
115583  /* 267 */ "plus_num ::= number",
115584  /* 268 */ "minus_num ::= MINUS number",
115585  /* 269 */ "number ::= INTEGER|FLOAT",
115586  /* 270 */ "cmd ::= createkw trigger_decl BEGIN trigger_cmd_list END",
115587  /* 271 */ "trigger_decl ::= temp TRIGGER ifnotexists nm dbnm trigger_time trigger_event ON fullname foreach_clause when_clause",
115588  /* 272 */ "trigger_time ::= BEFORE",
115589  /* 273 */ "trigger_time ::= AFTER",
115590  /* 274 */ "trigger_time ::= INSTEAD OF",
115591  /* 275 */ "trigger_time ::=",
115592  /* 276 */ "trigger_event ::= DELETE|INSERT",
115593  /* 277 */ "trigger_event ::= UPDATE",
115594  /* 278 */ "trigger_event ::= UPDATE OF idlist",
115595  /* 279 */ "foreach_clause ::=",
115596  /* 280 */ "foreach_clause ::= FOR EACH ROW",
115597  /* 281 */ "when_clause ::=",
115598  /* 282 */ "when_clause ::= WHEN expr",
115599  /* 283 */ "trigger_cmd_list ::= trigger_cmd_list trigger_cmd SEMI",
115600  /* 284 */ "trigger_cmd_list ::= trigger_cmd SEMI",
115601  /* 285 */ "trnm ::= nm",
115602  /* 286 */ "trnm ::= nm DOT nm",
115603  /* 287 */ "tridxby ::=",
115604  /* 288 */ "tridxby ::= INDEXED BY nm",
115605  /* 289 */ "tridxby ::= NOT INDEXED",
115606  /* 290 */ "trigger_cmd ::= UPDATE orconf trnm tridxby SET setlist where_opt",
115607  /* 291 */ "trigger_cmd ::= insert_cmd INTO trnm inscollist_opt valuelist",
115608  /* 292 */ "trigger_cmd ::= insert_cmd INTO trnm inscollist_opt select",
115609  /* 293 */ "trigger_cmd ::= DELETE FROM trnm tridxby where_opt",
115610  /* 294 */ "trigger_cmd ::= select",
115611  /* 295 */ "expr ::= RAISE LP IGNORE RP",
115612  /* 296 */ "expr ::= RAISE LP raisetype COMMA nm RP",
115613  /* 297 */ "raisetype ::= ROLLBACK",
115614  /* 298 */ "raisetype ::= ABORT",
115615  /* 299 */ "raisetype ::= FAIL",
115616  /* 300 */ "cmd ::= DROP TRIGGER ifexists fullname",
115617  /* 301 */ "cmd ::= ATTACH database_kw_opt expr AS expr key_opt",
115618  /* 302 */ "cmd ::= DETACH database_kw_opt expr",
115619  /* 303 */ "key_opt ::=",
115620  /* 304 */ "key_opt ::= KEY expr",
115621  /* 305 */ "database_kw_opt ::= DATABASE",
115622  /* 306 */ "database_kw_opt ::=",
115623  /* 307 */ "cmd ::= REINDEX",
115624  /* 308 */ "cmd ::= REINDEX nm dbnm",
115625  /* 309 */ "cmd ::= ANALYZE",
115626  /* 310 */ "cmd ::= ANALYZE nm dbnm",
115627  /* 311 */ "cmd ::= ALTER TABLE fullname RENAME TO nm",
115628  /* 312 */ "cmd ::= ALTER TABLE add_column_fullname ADD kwcolumn_opt column",
115629  /* 313 */ "add_column_fullname ::= fullname",
115630  /* 314 */ "kwcolumn_opt ::=",
115631  /* 315 */ "kwcolumn_opt ::= COLUMNKW",
115632  /* 316 */ "cmd ::= create_vtab",
115633  /* 317 */ "cmd ::= create_vtab LP vtabarglist RP",
115634  /* 318 */ "create_vtab ::= createkw VIRTUAL TABLE ifnotexists nm dbnm USING nm",
115635  /* 319 */ "vtabarglist ::= vtabarg",
115636  /* 320 */ "vtabarglist ::= vtabarglist COMMA vtabarg",
115637  /* 321 */ "vtabarg ::=",
115638  /* 322 */ "vtabarg ::= vtabarg vtabargtoken",
115639  /* 323 */ "vtabargtoken ::= ANY",
115640  /* 324 */ "vtabargtoken ::= lp anylist RP",
115641  /* 325 */ "lp ::= LP",
115642  /* 326 */ "anylist ::=",
115643  /* 327 */ "anylist ::= anylist LP anylist RP",
115644  /* 328 */ "anylist ::= anylist ANY",
115645 };
115646 #endif /* NDEBUG */
115647 
115648 
115649 #if YYSTACKDEPTH<=0
115650 /*
115651 ** Try to increase the size of the parser stack.
115652 */
115653 static void yyGrowStack(yyParser *p){
115654   int newSize;
115655   yyStackEntry *pNew;
115656 
115657   newSize = p->yystksz*2 + 100;
115658   pNew = realloc(p->yystack, newSize*sizeof(pNew[0]));
115659   if( pNew ){
115660     p->yystack = pNew;
115661     p->yystksz = newSize;
115662 #ifndef NDEBUG
115663     if( yyTraceFILE ){
115664       fprintf(yyTraceFILE,"%sStack grows to %d entries!\n",
115665               yyTracePrompt, p->yystksz);
115666     }
115667 #endif
115668   }
115669 }
115670 #endif
115671 
115672 /* 
115673 ** This function allocates a new parser.
115674 ** The only argument is a pointer to a function which works like
115675 ** malloc.
115676 **
115677 ** Inputs:
115678 ** A pointer to the function used to allocate memory.
115679 **
115680 ** Outputs:
115681 ** A pointer to a parser.  This pointer is used in subsequent calls
115682 ** to sqlite3Parser and sqlite3ParserFree.
115683 */
115684 SQLITE_PRIVATE void *sqlite3ParserAlloc(void *(*mallocProc)(size_t)){
115685   yyParser *pParser;
115686   pParser = (yyParser*)(*mallocProc)( (size_t)sizeof(yyParser) );
115687   if( pParser ){
115688     pParser->yyidx = -1;
115689 #ifdef YYTRACKMAXSTACKDEPTH
115690     pParser->yyidxMax = 0;
115691 #endif
115692 #if YYSTACKDEPTH<=0
115693     pParser->yystack = NULL;
115694     pParser->yystksz = 0;
115695     yyGrowStack(pParser);
115696 #endif
115697   }
115698   return pParser;
115699 }
115700 
115701 /* The following function deletes the value associated with a
115702 ** symbol.  The symbol can be either a terminal or nonterminal.
115703 ** "yymajor" is the symbol code, and "yypminor" is a pointer to
115704 ** the value.
115705 */
115706 static void yy_destructor(
115707   yyParser *yypParser,    /* The parser */
115708   YYCODETYPE yymajor,     /* Type code for object to destroy */
115709   YYMINORTYPE *yypminor   /* The object to be destroyed */
115710 ){
115711   sqlite3ParserARG_FETCH;
115712   switch( yymajor ){
115713     /* Here is inserted the actions which take place when a
115714     ** terminal or non-terminal is destroyed.  This can happen
115715     ** when the symbol is popped from the stack during a
115716     ** reduce or during error processing or when a parser is 
115717     ** being destroyed before it is finished parsing.
115718     **
115719     ** Note: during a reduce, the only symbols destroyed are those
115720     ** which appear on the RHS of the rule, but which are not used
115721     ** inside the C code.
115722     */
115723     case 162: /* select */
115724     case 196: /* oneselect */
115725 {
115726 sqlite3SelectDelete(pParse->db, (yypminor->yy387));
115727 }
115728       break;
115729     case 175: /* term */
115730     case 176: /* expr */
115731 {
115732 sqlite3ExprDelete(pParse->db, (yypminor->yy118).pExpr);
115733 }
115734       break;
115735     case 180: /* idxlist_opt */
115736     case 189: /* idxlist */
115737     case 199: /* selcollist */
115738     case 202: /* groupby_opt */
115739     case 204: /* orderby_opt */
115740     case 206: /* sclp */
115741     case 216: /* sortlist */
115742     case 217: /* nexprlist */
115743     case 218: /* setlist */
115744     case 222: /* exprlist */
115745     case 227: /* case_exprlist */
115746 {
115747 sqlite3ExprListDelete(pParse->db, (yypminor->yy322));
115748 }
115749       break;
115750     case 195: /* fullname */
115751     case 200: /* from */
115752     case 208: /* seltablist */
115753     case 209: /* stl_prefix */
115754 {
115755 sqlite3SrcListDelete(pParse->db, (yypminor->yy259));
115756 }
115757       break;
115758     case 201: /* where_opt */
115759     case 203: /* having_opt */
115760     case 212: /* on_opt */
115761     case 226: /* case_operand */
115762     case 228: /* case_else */
115763     case 238: /* when_clause */
115764     case 243: /* key_opt */
115765 {
115766 sqlite3ExprDelete(pParse->db, (yypminor->yy314));
115767 }
115768       break;
115769     case 213: /* using_opt */
115770     case 215: /* idlist */
115771     case 220: /* inscollist_opt */
115772 {
115773 sqlite3IdListDelete(pParse->db, (yypminor->yy384));
115774 }
115775       break;
115776     case 221: /* valuelist */
115777 {
115778 
115779   sqlite3ExprListDelete(pParse->db, (yypminor->yy260).pList);
115780   sqlite3SelectDelete(pParse->db, (yypminor->yy260).pSelect);
115781 
115782 }
115783       break;
115784     case 234: /* trigger_cmd_list */
115785     case 239: /* trigger_cmd */
115786 {
115787 sqlite3DeleteTriggerStep(pParse->db, (yypminor->yy203));
115788 }
115789       break;
115790     case 236: /* trigger_event */
115791 {
115792 sqlite3IdListDelete(pParse->db, (yypminor->yy90).b);
115793 }
115794       break;
115795     default:  break;   /* If no destructor action specified: do nothing */
115796   }
115797 }
115798 
115799 /*
115800 ** Pop the parser's stack once.
115801 **
115802 ** If there is a destructor routine associated with the token which
115803 ** is popped from the stack, then call it.
115804 **
115805 ** Return the major token number for the symbol popped.
115806 */
115807 static int yy_pop_parser_stack(yyParser *pParser){
115808   YYCODETYPE yymajor;
115809   yyStackEntry *yytos = &pParser->yystack[pParser->yyidx];
115810 
115811   /* There is no mechanism by which the parser stack can be popped below
115812   ** empty in SQLite.  */
115813   if( NEVER(pParser->yyidx<0) ) return 0;
115814 #ifndef NDEBUG
115815   if( yyTraceFILE && pParser->yyidx>=0 ){
115816     fprintf(yyTraceFILE,"%sPopping %s\n",
115817       yyTracePrompt,
115818       yyTokenName[yytos->major]);
115819   }
115820 #endif
115821   yymajor = yytos->major;
115822   yy_destructor(pParser, yymajor, &yytos->minor);
115823   pParser->yyidx--;
115824   return yymajor;
115825 }
115826 
115827 /* 
115828 ** Deallocate and destroy a parser.  Destructors are all called for
115829 ** all stack elements before shutting the parser down.
115830 **
115831 ** Inputs:
115832 ** <ul>
115833 ** <li>  A pointer to the parser.  This should be a pointer
115834 **       obtained from sqlite3ParserAlloc.
115835 ** <li>  A pointer to a function used to reclaim memory obtained
115836 **       from malloc.
115837 ** </ul>
115838 */
115839 SQLITE_PRIVATE void sqlite3ParserFree(
115840   void *p,                    /* The parser to be deleted */
115841   void (*freeProc)(void*)     /* Function used to reclaim memory */
115842 ){
115843   yyParser *pParser = (yyParser*)p;
115844   /* In SQLite, we never try to destroy a parser that was not successfully
115845   ** created in the first place. */
115846   if( NEVER(pParser==0) ) return;
115847   while( pParser->yyidx>=0 ) yy_pop_parser_stack(pParser);
115848 #if YYSTACKDEPTH<=0
115849   free(pParser->yystack);
115850 #endif
115851   (*freeProc)((void*)pParser);
115852 }
115853 
115854 /*
115855 ** Return the peak depth of the stack for a parser.
115856 */
115857 #ifdef YYTRACKMAXSTACKDEPTH
115858 SQLITE_PRIVATE int sqlite3ParserStackPeak(void *p){
115859   yyParser *pParser = (yyParser*)p;
115860   return pParser->yyidxMax;
115861 }
115862 #endif
115863 
115864 /*
115865 ** Find the appropriate action for a parser given the terminal
115866 ** look-ahead token iLookAhead.
115867 **
115868 ** If the look-ahead token is YYNOCODE, then check to see if the action is
115869 ** independent of the look-ahead.  If it is, return the action, otherwise
115870 ** return YY_NO_ACTION.
115871 */
115872 static int yy_find_shift_action(
115873   yyParser *pParser,        /* The parser */
115874   YYCODETYPE iLookAhead     /* The look-ahead token */
115875 ){
115876   int i;
115877   int stateno = pParser->yystack[pParser->yyidx].stateno;
115878  
115879   if( stateno>YY_SHIFT_COUNT
115880    || (i = yy_shift_ofst[stateno])==YY_SHIFT_USE_DFLT ){
115881     return yy_default[stateno];
115882   }
115883   assert( iLookAhead!=YYNOCODE );
115884   i += iLookAhead;
115885   if( i<0 || i>=YY_ACTTAB_COUNT || yy_lookahead[i]!=iLookAhead ){
115886     if( iLookAhead>0 ){
115887 #ifdef YYFALLBACK
115888       YYCODETYPE iFallback;            /* Fallback token */
115889       if( iLookAhead<sizeof(yyFallback)/sizeof(yyFallback[0])
115890              && (iFallback = yyFallback[iLookAhead])!=0 ){
115891 #ifndef NDEBUG
115892         if( yyTraceFILE ){
115893           fprintf(yyTraceFILE, "%sFALLBACK %s => %s\n",
115894              yyTracePrompt, yyTokenName[iLookAhead], yyTokenName[iFallback]);
115895         }
115896 #endif
115897         return yy_find_shift_action(pParser, iFallback);
115898       }
115899 #endif
115900 #ifdef YYWILDCARD
115901       {
115902         int j = i - iLookAhead + YYWILDCARD;
115903         if( 
115904 #if YY_SHIFT_MIN+YYWILDCARD<0
115905           j>=0 &&
115906 #endif
115907 #if YY_SHIFT_MAX+YYWILDCARD>=YY_ACTTAB_COUNT
115908           j<YY_ACTTAB_COUNT &&
115909 #endif
115910           yy_lookahead[j]==YYWILDCARD
115911         ){
115912 #ifndef NDEBUG
115913           if( yyTraceFILE ){
115914             fprintf(yyTraceFILE, "%sWILDCARD %s => %s\n",
115915                yyTracePrompt, yyTokenName[iLookAhead], yyTokenName[YYWILDCARD]);
115916           }
115917 #endif /* NDEBUG */
115918           return yy_action[j];
115919         }
115920       }
115921 #endif /* YYWILDCARD */
115922     }
115923     return yy_default[stateno];
115924   }else{
115925     return yy_action[i];
115926   }
115927 }
115928 
115929 /*
115930 ** Find the appropriate action for a parser given the non-terminal
115931 ** look-ahead token iLookAhead.
115932 **
115933 ** If the look-ahead token is YYNOCODE, then check to see if the action is
115934 ** independent of the look-ahead.  If it is, return the action, otherwise
115935 ** return YY_NO_ACTION.
115936 */
115937 static int yy_find_reduce_action(
115938   int stateno,              /* Current state number */
115939   YYCODETYPE iLookAhead     /* The look-ahead token */
115940 ){
115941   int i;
115942 #ifdef YYERRORSYMBOL
115943   if( stateno>YY_REDUCE_COUNT ){
115944     return yy_default[stateno];
115945   }
115946 #else
115947   assert( stateno<=YY_REDUCE_COUNT );
115948 #endif
115949   i = yy_reduce_ofst[stateno];
115950   assert( i!=YY_REDUCE_USE_DFLT );
115951   assert( iLookAhead!=YYNOCODE );
115952   i += iLookAhead;
115953 #ifdef YYERRORSYMBOL
115954   if( i<0 || i>=YY_ACTTAB_COUNT || yy_lookahead[i]!=iLookAhead ){
115955     return yy_default[stateno];
115956   }
115957 #else
115958   assert( i>=0 && i<YY_ACTTAB_COUNT );
115959   assert( yy_lookahead[i]==iLookAhead );
115960 #endif
115961   return yy_action[i];
115962 }
115963 
115964 /*
115965 ** The following routine is called if the stack overflows.
115966 */
115967 static void yyStackOverflow(yyParser *yypParser, YYMINORTYPE *yypMinor){
115968    sqlite3ParserARG_FETCH;
115969    yypParser->yyidx--;
115970 #ifndef NDEBUG
115971    if( yyTraceFILE ){
115972      fprintf(yyTraceFILE,"%sStack Overflow!\n",yyTracePrompt);
115973    }
115974 #endif
115975    while( yypParser->yyidx>=0 ) yy_pop_parser_stack(yypParser);
115976    /* Here code is inserted which will execute if the parser
115977    ** stack every overflows */
115978 
115979   UNUSED_PARAMETER(yypMinor); /* Silence some compiler warnings */
115980   sqlite3ErrorMsg(pParse, "parser stack overflow");
115981    sqlite3ParserARG_STORE; /* Suppress warning about unused %extra_argument var */
115982 }
115983 
115984 /*
115985 ** Perform a shift action.
115986 */
115987 static void yy_shift(
115988   yyParser *yypParser,          /* The parser to be shifted */
115989   int yyNewState,               /* The new state to shift in */
115990   int yyMajor,                  /* The major token to shift in */
115991   YYMINORTYPE *yypMinor         /* Pointer to the minor token to shift in */
115992 ){
115993   yyStackEntry *yytos;
115994   yypParser->yyidx++;
115995 #ifdef YYTRACKMAXSTACKDEPTH
115996   if( yypParser->yyidx>yypParser->yyidxMax ){
115997     yypParser->yyidxMax = yypParser->yyidx;
115998   }
115999 #endif
116000 #if YYSTACKDEPTH>0 
116001   if( yypParser->yyidx>=YYSTACKDEPTH ){
116002     yyStackOverflow(yypParser, yypMinor);
116003     return;
116004   }
116005 #else
116006   if( yypParser->yyidx>=yypParser->yystksz ){
116007     yyGrowStack(yypParser);
116008     if( yypParser->yyidx>=yypParser->yystksz ){
116009       yyStackOverflow(yypParser, yypMinor);
116010       return;
116011     }
116012   }
116013 #endif
116014   yytos = &yypParser->yystack[yypParser->yyidx];
116015   yytos->stateno = (YYACTIONTYPE)yyNewState;
116016   yytos->major = (YYCODETYPE)yyMajor;
116017   yytos->minor = *yypMinor;
116018 #ifndef NDEBUG
116019   if( yyTraceFILE && yypParser->yyidx>0 ){
116020     int i;
116021     fprintf(yyTraceFILE,"%sShift %d\n",yyTracePrompt,yyNewState);
116022     fprintf(yyTraceFILE,"%sStack:",yyTracePrompt);
116023     for(i=1; i<=yypParser->yyidx; i++)
116024       fprintf(yyTraceFILE," %s",yyTokenName[yypParser->yystack[i].major]);
116025     fprintf(yyTraceFILE,"\n");
116026   }
116027 #endif
116028 }
116029 
116030 /* The following table contains information about every rule that
116031 ** is used during the reduce.
116032 */
116033 static const struct {
116034   YYCODETYPE lhs;         /* Symbol on the left-hand side of the rule */
116035   unsigned char nrhs;     /* Number of right-hand side symbols in the rule */
116036 } yyRuleInfo[] = {
116037   { 143, 1 },
116038   { 144, 2 },
116039   { 144, 1 },
116040   { 145, 1 },
116041   { 145, 3 },
116042   { 146, 0 },
116043   { 146, 1 },
116044   { 146, 3 },
116045   { 147, 1 },
116046   { 148, 3 },
116047   { 150, 0 },
116048   { 150, 1 },
116049   { 150, 2 },
116050   { 149, 0 },
116051   { 149, 1 },
116052   { 149, 1 },
116053   { 149, 1 },
116054   { 148, 2 },
116055   { 148, 2 },
116056   { 148, 2 },
116057   { 152, 1 },
116058   { 152, 0 },
116059   { 148, 2 },
116060   { 148, 3 },
116061   { 148, 5 },
116062   { 148, 2 },
116063   { 153, 6 },
116064   { 155, 1 },
116065   { 157, 0 },
116066   { 157, 3 },
116067   { 156, 1 },
116068   { 156, 0 },
116069   { 154, 5 },
116070   { 154, 2 },
116071   { 161, 0 },
116072   { 161, 2 },
116073   { 159, 3 },
116074   { 159, 1 },
116075   { 163, 3 },
116076   { 164, 1 },
116077   { 167, 1 },
116078   { 167, 1 },
116079   { 168, 1 },
116080   { 151, 1 },
116081   { 151, 1 },
116082   { 151, 1 },
116083   { 165, 0 },
116084   { 165, 1 },
116085   { 169, 1 },
116086   { 169, 4 },
116087   { 169, 6 },
116088   { 170, 1 },
116089   { 170, 2 },
116090   { 171, 1 },
116091   { 171, 1 },
116092   { 166, 2 },
116093   { 166, 0 },
116094   { 174, 2 },
116095   { 174, 2 },
116096   { 174, 4 },
116097   { 174, 3 },
116098   { 174, 3 },
116099   { 174, 2 },
116100   { 174, 2 },
116101   { 174, 3 },
116102   { 174, 5 },
116103   { 174, 2 },
116104   { 174, 4 },
116105   { 174, 4 },
116106   { 174, 1 },
116107   { 174, 2 },
116108   { 179, 0 },
116109   { 179, 1 },
116110   { 181, 0 },
116111   { 181, 2 },
116112   { 183, 2 },
116113   { 183, 3 },
116114   { 183, 3 },
116115   { 183, 3 },
116116   { 184, 2 },
116117   { 184, 2 },
116118   { 184, 1 },
116119   { 184, 1 },
116120   { 184, 2 },
116121   { 182, 3 },
116122   { 182, 2 },
116123   { 185, 0 },
116124   { 185, 2 },
116125   { 185, 2 },
116126   { 160, 0 },
116127   { 160, 2 },
116128   { 186, 3 },
116129   { 186, 1 },
116130   { 187, 1 },
116131   { 187, 0 },
116132   { 188, 2 },
116133   { 188, 7 },
116134   { 188, 5 },
116135   { 188, 5 },
116136   { 188, 10 },
116137   { 190, 0 },
116138   { 190, 1 },
116139   { 177, 0 },
116140   { 177, 3 },
116141   { 191, 0 },
116142   { 191, 2 },
116143   { 192, 1 },
116144   { 192, 1 },
116145   { 192, 1 },
116146   { 148, 4 },
116147   { 194, 2 },
116148   { 194, 0 },
116149   { 148, 8 },
116150   { 148, 4 },
116151   { 148, 1 },
116152   { 162, 1 },
116153   { 162, 3 },
116154   { 197, 1 },
116155   { 197, 2 },
116156   { 197, 1 },
116157   { 196, 9 },
116158   { 198, 1 },
116159   { 198, 1 },
116160   { 198, 0 },
116161   { 206, 2 },
116162   { 206, 0 },
116163   { 199, 3 },
116164   { 199, 2 },
116165   { 199, 4 },
116166   { 207, 2 },
116167   { 207, 1 },
116168   { 207, 0 },
116169   { 200, 0 },
116170   { 200, 2 },
116171   { 209, 2 },
116172   { 209, 0 },
116173   { 208, 7 },
116174   { 208, 7 },
116175   { 208, 7 },
116176   { 158, 0 },
116177   { 158, 2 },
116178   { 195, 2 },
116179   { 210, 1 },
116180   { 210, 2 },
116181   { 210, 3 },
116182   { 210, 4 },
116183   { 212, 2 },
116184   { 212, 0 },
116185   { 211, 0 },
116186   { 211, 3 },
116187   { 211, 2 },
116188   { 213, 4 },
116189   { 213, 0 },
116190   { 204, 0 },
116191   { 204, 3 },
116192   { 216, 4 },
116193   { 216, 2 },
116194   { 178, 1 },
116195   { 178, 1 },
116196   { 178, 0 },
116197   { 202, 0 },
116198   { 202, 3 },
116199   { 203, 0 },
116200   { 203, 2 },
116201   { 205, 0 },
116202   { 205, 2 },
116203   { 205, 4 },
116204   { 205, 4 },
116205   { 148, 5 },
116206   { 201, 0 },
116207   { 201, 2 },
116208   { 148, 7 },
116209   { 218, 5 },
116210   { 218, 3 },
116211   { 148, 5 },
116212   { 148, 5 },
116213   { 148, 6 },
116214   { 219, 2 },
116215   { 219, 1 },
116216   { 221, 4 },
116217   { 221, 5 },
116218   { 220, 0 },
116219   { 220, 3 },
116220   { 215, 3 },
116221   { 215, 1 },
116222   { 176, 1 },
116223   { 176, 3 },
116224   { 175, 1 },
116225   { 176, 1 },
116226   { 176, 1 },
116227   { 176, 3 },
116228   { 176, 5 },
116229   { 175, 1 },
116230   { 175, 1 },
116231   { 176, 1 },
116232   { 176, 1 },
116233   { 176, 3 },
116234   { 176, 6 },
116235   { 176, 5 },
116236   { 176, 4 },
116237   { 175, 1 },
116238   { 176, 3 },
116239   { 176, 3 },
116240   { 176, 3 },
116241   { 176, 3 },
116242   { 176, 3 },
116243   { 176, 3 },
116244   { 176, 3 },
116245   { 176, 3 },
116246   { 223, 1 },
116247   { 223, 2 },
116248   { 223, 1 },
116249   { 223, 2 },
116250   { 176, 3 },
116251   { 176, 5 },
116252   { 176, 2 },
116253   { 176, 3 },
116254   { 176, 3 },
116255   { 176, 4 },
116256   { 176, 2 },
116257   { 176, 2 },
116258   { 176, 2 },
116259   { 176, 2 },
116260   { 224, 1 },
116261   { 224, 2 },
116262   { 176, 5 },
116263   { 225, 1 },
116264   { 225, 2 },
116265   { 176, 5 },
116266   { 176, 3 },
116267   { 176, 5 },
116268   { 176, 4 },
116269   { 176, 4 },
116270   { 176, 5 },
116271   { 227, 5 },
116272   { 227, 4 },
116273   { 228, 2 },
116274   { 228, 0 },
116275   { 226, 1 },
116276   { 226, 0 },
116277   { 222, 1 },
116278   { 222, 0 },
116279   { 217, 3 },
116280   { 217, 1 },
116281   { 148, 12 },
116282   { 229, 1 },
116283   { 229, 0 },
116284   { 180, 0 },
116285   { 180, 3 },
116286   { 189, 5 },
116287   { 189, 3 },
116288   { 230, 0 },
116289   { 230, 2 },
116290   { 148, 4 },
116291   { 148, 1 },
116292   { 148, 2 },
116293   { 148, 3 },
116294   { 148, 5 },
116295   { 148, 6 },
116296   { 148, 5 },
116297   { 148, 6 },
116298   { 231, 1 },
116299   { 231, 1 },
116300   { 231, 1 },
116301   { 231, 1 },
116302   { 231, 1 },
116303   { 172, 2 },
116304   { 172, 1 },
116305   { 173, 2 },
116306   { 232, 1 },
116307   { 148, 5 },
116308   { 233, 11 },
116309   { 235, 1 },
116310   { 235, 1 },
116311   { 235, 2 },
116312   { 235, 0 },
116313   { 236, 1 },
116314   { 236, 1 },
116315   { 236, 3 },
116316   { 237, 0 },
116317   { 237, 3 },
116318   { 238, 0 },
116319   { 238, 2 },
116320   { 234, 3 },
116321   { 234, 2 },
116322   { 240, 1 },
116323   { 240, 3 },
116324   { 241, 0 },
116325   { 241, 3 },
116326   { 241, 2 },
116327   { 239, 7 },
116328   { 239, 5 },
116329   { 239, 5 },
116330   { 239, 5 },
116331   { 239, 1 },
116332   { 176, 4 },
116333   { 176, 6 },
116334   { 193, 1 },
116335   { 193, 1 },
116336   { 193, 1 },
116337   { 148, 4 },
116338   { 148, 6 },
116339   { 148, 3 },
116340   { 243, 0 },
116341   { 243, 2 },
116342   { 242, 1 },
116343   { 242, 0 },
116344   { 148, 1 },
116345   { 148, 3 },
116346   { 148, 1 },
116347   { 148, 3 },
116348   { 148, 6 },
116349   { 148, 6 },
116350   { 244, 1 },
116351   { 245, 0 },
116352   { 245, 1 },
116353   { 148, 1 },
116354   { 148, 4 },
116355   { 246, 8 },
116356   { 247, 1 },
116357   { 247, 3 },
116358   { 248, 0 },
116359   { 248, 2 },
116360   { 249, 1 },
116361   { 249, 3 },
116362   { 250, 1 },
116363   { 251, 0 },
116364   { 251, 4 },
116365   { 251, 2 },
116366 };
116367 
116368 static void yy_accept(yyParser*);  /* Forward Declaration */
116369 
116370 /*
116371 ** Perform a reduce action and the shift that must immediately
116372 ** follow the reduce.
116373 */
116374 static void yy_reduce(
116375   yyParser *yypParser,         /* The parser */
116376   int yyruleno                 /* Number of the rule by which to reduce */
116377 ){
116378   int yygoto;                     /* The next state */
116379   int yyact;                      /* The next action */
116380   YYMINORTYPE yygotominor;        /* The LHS of the rule reduced */
116381   yyStackEntry *yymsp;            /* The top of the parser's stack */
116382   int yysize;                     /* Amount to pop the stack */
116383   sqlite3ParserARG_FETCH;
116384   yymsp = &yypParser->yystack[yypParser->yyidx];
116385 #ifndef NDEBUG
116386   if( yyTraceFILE && yyruleno>=0 
116387         && yyruleno<(int)(sizeof(yyRuleName)/sizeof(yyRuleName[0])) ){
116388     fprintf(yyTraceFILE, "%sReduce [%s].\n", yyTracePrompt,
116389       yyRuleName[yyruleno]);
116390   }
116391 #endif /* NDEBUG */
116392 
116393   /* Silence complaints from purify about yygotominor being uninitialized
116394   ** in some cases when it is copied into the stack after the following
116395   ** switch.  yygotominor is uninitialized when a rule reduces that does
116396   ** not set the value of its left-hand side nonterminal.  Leaving the
116397   ** value of the nonterminal uninitialized is utterly harmless as long
116398   ** as the value is never used.  So really the only thing this code
116399   ** accomplishes is to quieten purify.  
116400   **
116401   ** 2007-01-16:  The wireshark project (www.wireshark.org) reports that
116402   ** without this code, their parser segfaults.  I'm not sure what there
116403   ** parser is doing to make this happen.  This is the second bug report
116404   ** from wireshark this week.  Clearly they are stressing Lemon in ways
116405   ** that it has not been previously stressed...  (SQLite ticket #2172)
116406   */
116407   /*memset(&yygotominor, 0, sizeof(yygotominor));*/
116408   yygotominor = yyzerominor;
116409 
116410 
116411   switch( yyruleno ){
116412   /* Beginning here are the reduction cases.  A typical example
116413   ** follows:
116414   **   case 0:
116415   **  #line <lineno> <grammarfile>
116416   **     { ... }           // User supplied code
116417   **  #line <lineno> <thisfile>
116418   **     break;
116419   */
116420       case 5: /* explain ::= */
116421 { sqlite3BeginParse(pParse, 0); }
116422         break;
116423       case 6: /* explain ::= EXPLAIN */
116424 { sqlite3BeginParse(pParse, 1); }
116425         break;
116426       case 7: /* explain ::= EXPLAIN QUERY PLAN */
116427 { sqlite3BeginParse(pParse, 2); }
116428         break;
116429       case 8: /* cmdx ::= cmd */
116430 { sqlite3FinishCoding(pParse); }
116431         break;
116432       case 9: /* cmd ::= BEGIN transtype trans_opt */
116433 {sqlite3BeginTransaction(pParse, yymsp[-1].minor.yy4);}
116434         break;
116435       case 13: /* transtype ::= */
116436 {yygotominor.yy4 = TK_DEFERRED;}
116437         break;
116438       case 14: /* transtype ::= DEFERRED */
116439       case 15: /* transtype ::= IMMEDIATE */ yytestcase(yyruleno==15);
116440       case 16: /* transtype ::= EXCLUSIVE */ yytestcase(yyruleno==16);
116441       case 117: /* multiselect_op ::= UNION */ yytestcase(yyruleno==117);
116442       case 119: /* multiselect_op ::= EXCEPT|INTERSECT */ yytestcase(yyruleno==119);
116443 {yygotominor.yy4 = yymsp[0].major;}
116444         break;
116445       case 17: /* cmd ::= COMMIT trans_opt */
116446       case 18: /* cmd ::= END trans_opt */ yytestcase(yyruleno==18);
116447 {sqlite3CommitTransaction(pParse);}
116448         break;
116449       case 19: /* cmd ::= ROLLBACK trans_opt */
116450 {sqlite3RollbackTransaction(pParse);}
116451         break;
116452       case 22: /* cmd ::= SAVEPOINT nm */
116453 {
116454   sqlite3Savepoint(pParse, SAVEPOINT_BEGIN, &yymsp[0].minor.yy0);
116455 }
116456         break;
116457       case 23: /* cmd ::= RELEASE savepoint_opt nm */
116458 {
116459   sqlite3Savepoint(pParse, SAVEPOINT_RELEASE, &yymsp[0].minor.yy0);
116460 }
116461         break;
116462       case 24: /* cmd ::= ROLLBACK trans_opt TO savepoint_opt nm */
116463 {
116464   sqlite3Savepoint(pParse, SAVEPOINT_ROLLBACK, &yymsp[0].minor.yy0);
116465 }
116466         break;
116467       case 26: /* create_table ::= createkw temp TABLE ifnotexists nm dbnm */
116468 {
116469    sqlite3StartTable(pParse,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0,yymsp[-4].minor.yy4,0,0,yymsp[-2].minor.yy4);
116470 }
116471         break;
116472       case 27: /* createkw ::= CREATE */
116473 {
116474   pParse->db->lookaside.bEnabled = 0;
116475   yygotominor.yy0 = yymsp[0].minor.yy0;
116476 }
116477         break;
116478       case 28: /* ifnotexists ::= */
116479       case 31: /* temp ::= */ yytestcase(yyruleno==31);
116480       case 71: /* autoinc ::= */ yytestcase(yyruleno==71);
116481       case 84: /* defer_subclause ::= NOT DEFERRABLE init_deferred_pred_opt */ yytestcase(yyruleno==84);
116482       case 86: /* init_deferred_pred_opt ::= */ yytestcase(yyruleno==86);
116483       case 88: /* init_deferred_pred_opt ::= INITIALLY IMMEDIATE */ yytestcase(yyruleno==88);
116484       case 100: /* defer_subclause_opt ::= */ yytestcase(yyruleno==100);
116485       case 111: /* ifexists ::= */ yytestcase(yyruleno==111);
116486       case 223: /* between_op ::= BETWEEN */ yytestcase(yyruleno==223);
116487       case 226: /* in_op ::= IN */ yytestcase(yyruleno==226);
116488 {yygotominor.yy4 = 0;}
116489         break;
116490       case 29: /* ifnotexists ::= IF NOT EXISTS */
116491       case 30: /* temp ::= TEMP */ yytestcase(yyruleno==30);
116492       case 72: /* autoinc ::= AUTOINCR */ yytestcase(yyruleno==72);
116493       case 87: /* init_deferred_pred_opt ::= INITIALLY DEFERRED */ yytestcase(yyruleno==87);
116494       case 110: /* ifexists ::= IF EXISTS */ yytestcase(yyruleno==110);
116495       case 224: /* between_op ::= NOT BETWEEN */ yytestcase(yyruleno==224);
116496       case 227: /* in_op ::= NOT IN */ yytestcase(yyruleno==227);
116497 {yygotominor.yy4 = 1;}
116498         break;
116499       case 32: /* create_table_args ::= LP columnlist conslist_opt RP table_options */
116500 {
116501   sqlite3EndTable(pParse,&yymsp[-2].minor.yy0,&yymsp[-1].minor.yy0,yymsp[0].minor.yy210,0);
116502 }
116503         break;
116504       case 33: /* create_table_args ::= AS select */
116505 {
116506   sqlite3EndTable(pParse,0,0,0,yymsp[0].minor.yy387);
116507   sqlite3SelectDelete(pParse->db, yymsp[0].minor.yy387);
116508 }
116509         break;
116510       case 34: /* table_options ::= */
116511 {yygotominor.yy210 = 0;}
116512         break;
116513       case 35: /* table_options ::= WITHOUT nm */
116514 {
116515   if( yymsp[0].minor.yy0.n==5 && sqlite3_strnicmp(yymsp[0].minor.yy0.z,"rowid",5)==0 ){
116516     yygotominor.yy210 = TF_WithoutRowid;
116517   }else{
116518     yygotominor.yy210 = 0;
116519     sqlite3ErrorMsg(pParse, "unknown table option: %.*s", yymsp[0].minor.yy0.n, yymsp[0].minor.yy0.z);
116520   }
116521 }
116522         break;
116523       case 38: /* column ::= columnid type carglist */
116524 {
116525   yygotominor.yy0.z = yymsp[-2].minor.yy0.z;
116526   yygotominor.yy0.n = (int)(pParse->sLastToken.z-yymsp[-2].minor.yy0.z) + pParse->sLastToken.n;
116527 }
116528         break;
116529       case 39: /* columnid ::= nm */
116530 {
116531   sqlite3AddColumn(pParse,&yymsp[0].minor.yy0);
116532   yygotominor.yy0 = yymsp[0].minor.yy0;
116533   pParse->constraintName.n = 0;
116534 }
116535         break;
116536       case 40: /* id ::= ID */
116537       case 41: /* id ::= INDEXED */ yytestcase(yyruleno==41);
116538       case 42: /* ids ::= ID|STRING */ yytestcase(yyruleno==42);
116539       case 43: /* nm ::= id */ yytestcase(yyruleno==43);
116540       case 44: /* nm ::= STRING */ yytestcase(yyruleno==44);
116541       case 45: /* nm ::= JOIN_KW */ yytestcase(yyruleno==45);
116542       case 48: /* typetoken ::= typename */ yytestcase(yyruleno==48);
116543       case 51: /* typename ::= ids */ yytestcase(yyruleno==51);
116544       case 129: /* as ::= AS nm */ yytestcase(yyruleno==129);
116545       case 130: /* as ::= ids */ yytestcase(yyruleno==130);
116546       case 140: /* dbnm ::= DOT nm */ yytestcase(yyruleno==140);
116547       case 149: /* indexed_opt ::= INDEXED BY nm */ yytestcase(yyruleno==149);
116548       case 252: /* collate ::= COLLATE ids */ yytestcase(yyruleno==252);
116549       case 261: /* nmnum ::= plus_num */ yytestcase(yyruleno==261);
116550       case 262: /* nmnum ::= nm */ yytestcase(yyruleno==262);
116551       case 263: /* nmnum ::= ON */ yytestcase(yyruleno==263);
116552       case 264: /* nmnum ::= DELETE */ yytestcase(yyruleno==264);
116553       case 265: /* nmnum ::= DEFAULT */ yytestcase(yyruleno==265);
116554       case 266: /* plus_num ::= PLUS number */ yytestcase(yyruleno==266);
116555       case 267: /* plus_num ::= number */ yytestcase(yyruleno==267);
116556       case 268: /* minus_num ::= MINUS number */ yytestcase(yyruleno==268);
116557       case 269: /* number ::= INTEGER|FLOAT */ yytestcase(yyruleno==269);
116558       case 285: /* trnm ::= nm */ yytestcase(yyruleno==285);
116559 {yygotominor.yy0 = yymsp[0].minor.yy0;}
116560         break;
116561       case 47: /* type ::= typetoken */
116562 {sqlite3AddColumnType(pParse,&yymsp[0].minor.yy0);}
116563         break;
116564       case 49: /* typetoken ::= typename LP signed RP */
116565 {
116566   yygotominor.yy0.z = yymsp[-3].minor.yy0.z;
116567   yygotominor.yy0.n = (int)(&yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n] - yymsp[-3].minor.yy0.z);
116568 }
116569         break;
116570       case 50: /* typetoken ::= typename LP signed COMMA signed RP */
116571 {
116572   yygotominor.yy0.z = yymsp[-5].minor.yy0.z;
116573   yygotominor.yy0.n = (int)(&yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n] - yymsp[-5].minor.yy0.z);
116574 }
116575         break;
116576       case 52: /* typename ::= typename ids */
116577 {yygotominor.yy0.z=yymsp[-1].minor.yy0.z; yygotominor.yy0.n=yymsp[0].minor.yy0.n+(int)(yymsp[0].minor.yy0.z-yymsp[-1].minor.yy0.z);}
116578         break;
116579       case 57: /* ccons ::= CONSTRAINT nm */
116580       case 95: /* tcons ::= CONSTRAINT nm */ yytestcase(yyruleno==95);
116581 {pParse->constraintName = yymsp[0].minor.yy0;}
116582         break;
116583       case 58: /* ccons ::= DEFAULT term */
116584       case 60: /* ccons ::= DEFAULT PLUS term */ yytestcase(yyruleno==60);
116585 {sqlite3AddDefaultValue(pParse,&yymsp[0].minor.yy118);}
116586         break;
116587       case 59: /* ccons ::= DEFAULT LP expr RP */
116588 {sqlite3AddDefaultValue(pParse,&yymsp[-1].minor.yy118);}
116589         break;
116590       case 61: /* ccons ::= DEFAULT MINUS term */
116591 {
116592   ExprSpan v;
116593   v.pExpr = sqlite3PExpr(pParse, TK_UMINUS, yymsp[0].minor.yy118.pExpr, 0, 0);
116594   v.zStart = yymsp[-1].minor.yy0.z;
116595   v.zEnd = yymsp[0].minor.yy118.zEnd;
116596   sqlite3AddDefaultValue(pParse,&v);
116597 }
116598         break;
116599       case 62: /* ccons ::= DEFAULT id */
116600 {
116601   ExprSpan v;
116602   spanExpr(&v, pParse, TK_STRING, &yymsp[0].minor.yy0);
116603   sqlite3AddDefaultValue(pParse,&v);
116604 }
116605         break;
116606       case 64: /* ccons ::= NOT NULL onconf */
116607 {sqlite3AddNotNull(pParse, yymsp[0].minor.yy4);}
116608         break;
116609       case 65: /* ccons ::= PRIMARY KEY sortorder onconf autoinc */
116610 {sqlite3AddPrimaryKey(pParse,0,yymsp[-1].minor.yy4,yymsp[0].minor.yy4,yymsp[-2].minor.yy4);}
116611         break;
116612       case 66: /* ccons ::= UNIQUE onconf */
116613 {sqlite3CreateIndex(pParse,0,0,0,0,yymsp[0].minor.yy4,0,0,0,0);}
116614         break;
116615       case 67: /* ccons ::= CHECK LP expr RP */
116616 {sqlite3AddCheckConstraint(pParse,yymsp[-1].minor.yy118.pExpr);}
116617         break;
116618       case 68: /* ccons ::= REFERENCES nm idxlist_opt refargs */
116619 {sqlite3CreateForeignKey(pParse,0,&yymsp[-2].minor.yy0,yymsp[-1].minor.yy322,yymsp[0].minor.yy4);}
116620         break;
116621       case 69: /* ccons ::= defer_subclause */
116622 {sqlite3DeferForeignKey(pParse,yymsp[0].minor.yy4);}
116623         break;
116624       case 70: /* ccons ::= COLLATE ids */
116625 {sqlite3AddCollateType(pParse, &yymsp[0].minor.yy0);}
116626         break;
116627       case 73: /* refargs ::= */
116628 { yygotominor.yy4 = OE_None*0x0101; /* EV: R-19803-45884 */}
116629         break;
116630       case 74: /* refargs ::= refargs refarg */
116631 { yygotominor.yy4 = (yymsp[-1].minor.yy4 & ~yymsp[0].minor.yy215.mask) | yymsp[0].minor.yy215.value; }
116632         break;
116633       case 75: /* refarg ::= MATCH nm */
116634       case 76: /* refarg ::= ON INSERT refact */ yytestcase(yyruleno==76);
116635 { yygotominor.yy215.value = 0;     yygotominor.yy215.mask = 0x000000; }
116636         break;
116637       case 77: /* refarg ::= ON DELETE refact */
116638 { yygotominor.yy215.value = yymsp[0].minor.yy4;     yygotominor.yy215.mask = 0x0000ff; }
116639         break;
116640       case 78: /* refarg ::= ON UPDATE refact */
116641 { yygotominor.yy215.value = yymsp[0].minor.yy4<<8;  yygotominor.yy215.mask = 0x00ff00; }
116642         break;
116643       case 79: /* refact ::= SET NULL */
116644 { yygotominor.yy4 = OE_SetNull;  /* EV: R-33326-45252 */}
116645         break;
116646       case 80: /* refact ::= SET DEFAULT */
116647 { yygotominor.yy4 = OE_SetDflt;  /* EV: R-33326-45252 */}
116648         break;
116649       case 81: /* refact ::= CASCADE */
116650 { yygotominor.yy4 = OE_Cascade;  /* EV: R-33326-45252 */}
116651         break;
116652       case 82: /* refact ::= RESTRICT */
116653 { yygotominor.yy4 = OE_Restrict; /* EV: R-33326-45252 */}
116654         break;
116655       case 83: /* refact ::= NO ACTION */
116656 { yygotominor.yy4 = OE_None;     /* EV: R-33326-45252 */}
116657         break;
116658       case 85: /* defer_subclause ::= DEFERRABLE init_deferred_pred_opt */
116659       case 101: /* defer_subclause_opt ::= defer_subclause */ yytestcase(yyruleno==101);
116660       case 103: /* onconf ::= ON CONFLICT resolvetype */ yytestcase(yyruleno==103);
116661       case 106: /* resolvetype ::= raisetype */ yytestcase(yyruleno==106);
116662 {yygotominor.yy4 = yymsp[0].minor.yy4;}
116663         break;
116664       case 89: /* conslist_opt ::= */
116665 {yygotominor.yy0.n = 0; yygotominor.yy0.z = 0;}
116666         break;
116667       case 90: /* conslist_opt ::= COMMA conslist */
116668 {yygotominor.yy0 = yymsp[-1].minor.yy0;}
116669         break;
116670       case 93: /* tconscomma ::= COMMA */
116671 {pParse->constraintName.n = 0;}
116672         break;
116673       case 96: /* tcons ::= PRIMARY KEY LP idxlist autoinc RP onconf */
116674 {sqlite3AddPrimaryKey(pParse,yymsp[-3].minor.yy322,yymsp[0].minor.yy4,yymsp[-2].minor.yy4,0);}
116675         break;
116676       case 97: /* tcons ::= UNIQUE LP idxlist RP onconf */
116677 {sqlite3CreateIndex(pParse,0,0,0,yymsp[-2].minor.yy322,yymsp[0].minor.yy4,0,0,0,0);}
116678         break;
116679       case 98: /* tcons ::= CHECK LP expr RP onconf */
116680 {sqlite3AddCheckConstraint(pParse,yymsp[-2].minor.yy118.pExpr);}
116681         break;
116682       case 99: /* tcons ::= FOREIGN KEY LP idxlist RP REFERENCES nm idxlist_opt refargs defer_subclause_opt */
116683 {
116684     sqlite3CreateForeignKey(pParse, yymsp[-6].minor.yy322, &yymsp[-3].minor.yy0, yymsp[-2].minor.yy322, yymsp[-1].minor.yy4);
116685     sqlite3DeferForeignKey(pParse, yymsp[0].minor.yy4);
116686 }
116687         break;
116688       case 102: /* onconf ::= */
116689 {yygotominor.yy4 = OE_Default;}
116690         break;
116691       case 104: /* orconf ::= */
116692 {yygotominor.yy210 = OE_Default;}
116693         break;
116694       case 105: /* orconf ::= OR resolvetype */
116695 {yygotominor.yy210 = (u8)yymsp[0].minor.yy4;}
116696         break;
116697       case 107: /* resolvetype ::= IGNORE */
116698 {yygotominor.yy4 = OE_Ignore;}
116699         break;
116700       case 108: /* resolvetype ::= REPLACE */
116701 {yygotominor.yy4 = OE_Replace;}
116702         break;
116703       case 109: /* cmd ::= DROP TABLE ifexists fullname */
116704 {
116705   sqlite3DropTable(pParse, yymsp[0].minor.yy259, 0, yymsp[-1].minor.yy4);
116706 }
116707         break;
116708       case 112: /* cmd ::= createkw temp VIEW ifnotexists nm dbnm AS select */
116709 {
116710   sqlite3CreateView(pParse, &yymsp[-7].minor.yy0, &yymsp[-3].minor.yy0, &yymsp[-2].minor.yy0, yymsp[0].minor.yy387, yymsp[-6].minor.yy4, yymsp[-4].minor.yy4);
116711 }
116712         break;
116713       case 113: /* cmd ::= DROP VIEW ifexists fullname */
116714 {
116715   sqlite3DropTable(pParse, yymsp[0].minor.yy259, 1, yymsp[-1].minor.yy4);
116716 }
116717         break;
116718       case 114: /* cmd ::= select */
116719 {
116720   SelectDest dest = {SRT_Output, 0, 0, 0, 0};
116721   sqlite3Select(pParse, yymsp[0].minor.yy387, &dest);
116722   sqlite3ExplainBegin(pParse->pVdbe);
116723   sqlite3ExplainSelect(pParse->pVdbe, yymsp[0].minor.yy387);
116724   sqlite3ExplainFinish(pParse->pVdbe);
116725   sqlite3SelectDelete(pParse->db, yymsp[0].minor.yy387);
116726 }
116727         break;
116728       case 115: /* select ::= oneselect */
116729 {yygotominor.yy387 = yymsp[0].minor.yy387;}
116730         break;
116731       case 116: /* select ::= select multiselect_op oneselect */
116732 {
116733   if( yymsp[0].minor.yy387 ){
116734     yymsp[0].minor.yy387->op = (u8)yymsp[-1].minor.yy4;
116735     yymsp[0].minor.yy387->pPrior = yymsp[-2].minor.yy387;
116736     if( yymsp[-1].minor.yy4!=TK_ALL ) pParse->hasCompound = 1;
116737   }else{
116738     sqlite3SelectDelete(pParse->db, yymsp[-2].minor.yy387);
116739   }
116740   yygotominor.yy387 = yymsp[0].minor.yy387;
116741 }
116742         break;
116743       case 118: /* multiselect_op ::= UNION ALL */
116744 {yygotominor.yy4 = TK_ALL;}
116745         break;
116746       case 120: /* oneselect ::= SELECT distinct selcollist from where_opt groupby_opt having_opt orderby_opt limit_opt */
116747 {
116748   yygotominor.yy387 = sqlite3SelectNew(pParse,yymsp[-6].minor.yy322,yymsp[-5].minor.yy259,yymsp[-4].minor.yy314,yymsp[-3].minor.yy322,yymsp[-2].minor.yy314,yymsp[-1].minor.yy322,yymsp[-7].minor.yy177,yymsp[0].minor.yy292.pLimit,yymsp[0].minor.yy292.pOffset);
116749 }
116750         break;
116751       case 121: /* distinct ::= DISTINCT */
116752 {yygotominor.yy177 = SF_Distinct;}
116753         break;
116754       case 122: /* distinct ::= ALL */
116755       case 123: /* distinct ::= */ yytestcase(yyruleno==123);
116756 {yygotominor.yy177 = 0;}
116757         break;
116758       case 124: /* sclp ::= selcollist COMMA */
116759       case 248: /* idxlist_opt ::= LP idxlist RP */ yytestcase(yyruleno==248);
116760 {yygotominor.yy322 = yymsp[-1].minor.yy322;}
116761         break;
116762       case 125: /* sclp ::= */
116763       case 153: /* orderby_opt ::= */ yytestcase(yyruleno==153);
116764       case 160: /* groupby_opt ::= */ yytestcase(yyruleno==160);
116765       case 241: /* exprlist ::= */ yytestcase(yyruleno==241);
116766       case 247: /* idxlist_opt ::= */ yytestcase(yyruleno==247);
116767 {yygotominor.yy322 = 0;}
116768         break;
116769       case 126: /* selcollist ::= sclp expr as */
116770 {
116771    yygotominor.yy322 = sqlite3ExprListAppend(pParse, yymsp[-2].minor.yy322, yymsp[-1].minor.yy118.pExpr);
116772    if( yymsp[0].minor.yy0.n>0 ) sqlite3ExprListSetName(pParse, yygotominor.yy322, &yymsp[0].minor.yy0, 1);
116773    sqlite3ExprListSetSpan(pParse,yygotominor.yy322,&yymsp[-1].minor.yy118);
116774 }
116775         break;
116776       case 127: /* selcollist ::= sclp STAR */
116777 {
116778   Expr *p = sqlite3Expr(pParse->db, TK_ALL, 0);
116779   yygotominor.yy322 = sqlite3ExprListAppend(pParse, yymsp[-1].minor.yy322, p);
116780 }
116781         break;
116782       case 128: /* selcollist ::= sclp nm DOT STAR */
116783 {
116784   Expr *pRight = sqlite3PExpr(pParse, TK_ALL, 0, 0, &yymsp[0].minor.yy0);
116785   Expr *pLeft = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy0);
116786   Expr *pDot = sqlite3PExpr(pParse, TK_DOT, pLeft, pRight, 0);
116787   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yymsp[-3].minor.yy322, pDot);
116788 }
116789         break;
116790       case 131: /* as ::= */
116791 {yygotominor.yy0.n = 0;}
116792         break;
116793       case 132: /* from ::= */
116794 {yygotominor.yy259 = sqlite3DbMallocZero(pParse->db, sizeof(*yygotominor.yy259));}
116795         break;
116796       case 133: /* from ::= FROM seltablist */
116797 {
116798   yygotominor.yy259 = yymsp[0].minor.yy259;
116799   sqlite3SrcListShiftJoinType(yygotominor.yy259);
116800 }
116801         break;
116802       case 134: /* stl_prefix ::= seltablist joinop */
116803 {
116804    yygotominor.yy259 = yymsp[-1].minor.yy259;
116805    if( ALWAYS(yygotominor.yy259 && yygotominor.yy259->nSrc>0) ) yygotominor.yy259->a[yygotominor.yy259->nSrc-1].jointype = (u8)yymsp[0].minor.yy4;
116806 }
116807         break;
116808       case 135: /* stl_prefix ::= */
116809 {yygotominor.yy259 = 0;}
116810         break;
116811       case 136: /* seltablist ::= stl_prefix nm dbnm as indexed_opt on_opt using_opt */
116812 {
116813   yygotominor.yy259 = sqlite3SrcListAppendFromTerm(pParse,yymsp[-6].minor.yy259,&yymsp[-5].minor.yy0,&yymsp[-4].minor.yy0,&yymsp[-3].minor.yy0,0,yymsp[-1].minor.yy314,yymsp[0].minor.yy384);
116814   sqlite3SrcListIndexedBy(pParse, yygotominor.yy259, &yymsp[-2].minor.yy0);
116815 }
116816         break;
116817       case 137: /* seltablist ::= stl_prefix LP select RP as on_opt using_opt */
116818 {
116819     yygotominor.yy259 = sqlite3SrcListAppendFromTerm(pParse,yymsp[-6].minor.yy259,0,0,&yymsp[-2].minor.yy0,yymsp[-4].minor.yy387,yymsp[-1].minor.yy314,yymsp[0].minor.yy384);
116820   }
116821         break;
116822       case 138: /* seltablist ::= stl_prefix LP seltablist RP as on_opt using_opt */
116823 {
116824     if( yymsp[-6].minor.yy259==0 && yymsp[-2].minor.yy0.n==0 && yymsp[-1].minor.yy314==0 && yymsp[0].minor.yy384==0 ){
116825       yygotominor.yy259 = yymsp[-4].minor.yy259;
116826     }else if( yymsp[-4].minor.yy259->nSrc==1 ){
116827       yygotominor.yy259 = sqlite3SrcListAppendFromTerm(pParse,yymsp[-6].minor.yy259,0,0,&yymsp[-2].minor.yy0,0,yymsp[-1].minor.yy314,yymsp[0].minor.yy384);
116828       if( yygotominor.yy259 ){
116829         struct SrcList_item *pNew = &yygotominor.yy259->a[yygotominor.yy259->nSrc-1];
116830         struct SrcList_item *pOld = yymsp[-4].minor.yy259->a;
116831         pNew->zName = pOld->zName;
116832         pNew->zDatabase = pOld->zDatabase;
116833         pNew->pSelect = pOld->pSelect;
116834         pOld->zName = pOld->zDatabase = 0;
116835         pOld->pSelect = 0;
116836       }
116837       sqlite3SrcListDelete(pParse->db, yymsp[-4].minor.yy259);
116838     }else{
116839       Select *pSubquery;
116840       sqlite3SrcListShiftJoinType(yymsp[-4].minor.yy259);
116841       pSubquery = sqlite3SelectNew(pParse,0,yymsp[-4].minor.yy259,0,0,0,0,SF_NestedFrom,0,0);
116842       yygotominor.yy259 = sqlite3SrcListAppendFromTerm(pParse,yymsp[-6].minor.yy259,0,0,&yymsp[-2].minor.yy0,pSubquery,yymsp[-1].minor.yy314,yymsp[0].minor.yy384);
116843     }
116844   }
116845         break;
116846       case 139: /* dbnm ::= */
116847       case 148: /* indexed_opt ::= */ yytestcase(yyruleno==148);
116848 {yygotominor.yy0.z=0; yygotominor.yy0.n=0;}
116849         break;
116850       case 141: /* fullname ::= nm dbnm */
116851 {yygotominor.yy259 = sqlite3SrcListAppend(pParse->db,0,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0);}
116852         break;
116853       case 142: /* joinop ::= COMMA|JOIN */
116854 { yygotominor.yy4 = JT_INNER; }
116855         break;
116856       case 143: /* joinop ::= JOIN_KW JOIN */
116857 { yygotominor.yy4 = sqlite3JoinType(pParse,&yymsp[-1].minor.yy0,0,0); }
116858         break;
116859       case 144: /* joinop ::= JOIN_KW nm JOIN */
116860 { yygotominor.yy4 = sqlite3JoinType(pParse,&yymsp[-2].minor.yy0,&yymsp[-1].minor.yy0,0); }
116861         break;
116862       case 145: /* joinop ::= JOIN_KW nm nm JOIN */
116863 { yygotominor.yy4 = sqlite3JoinType(pParse,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy0,&yymsp[-1].minor.yy0); }
116864         break;
116865       case 146: /* on_opt ::= ON expr */
116866       case 163: /* having_opt ::= HAVING expr */ yytestcase(yyruleno==163);
116867       case 170: /* where_opt ::= WHERE expr */ yytestcase(yyruleno==170);
116868       case 236: /* case_else ::= ELSE expr */ yytestcase(yyruleno==236);
116869       case 238: /* case_operand ::= expr */ yytestcase(yyruleno==238);
116870 {yygotominor.yy314 = yymsp[0].minor.yy118.pExpr;}
116871         break;
116872       case 147: /* on_opt ::= */
116873       case 162: /* having_opt ::= */ yytestcase(yyruleno==162);
116874       case 169: /* where_opt ::= */ yytestcase(yyruleno==169);
116875       case 237: /* case_else ::= */ yytestcase(yyruleno==237);
116876       case 239: /* case_operand ::= */ yytestcase(yyruleno==239);
116877 {yygotominor.yy314 = 0;}
116878         break;
116879       case 150: /* indexed_opt ::= NOT INDEXED */
116880 {yygotominor.yy0.z=0; yygotominor.yy0.n=1;}
116881         break;
116882       case 151: /* using_opt ::= USING LP idlist RP */
116883       case 182: /* inscollist_opt ::= LP idlist RP */ yytestcase(yyruleno==182);
116884 {yygotominor.yy384 = yymsp[-1].minor.yy384;}
116885         break;
116886       case 152: /* using_opt ::= */
116887       case 181: /* inscollist_opt ::= */ yytestcase(yyruleno==181);
116888 {yygotominor.yy384 = 0;}
116889         break;
116890       case 154: /* orderby_opt ::= ORDER BY sortlist */
116891       case 161: /* groupby_opt ::= GROUP BY nexprlist */ yytestcase(yyruleno==161);
116892       case 240: /* exprlist ::= nexprlist */ yytestcase(yyruleno==240);
116893 {yygotominor.yy322 = yymsp[0].minor.yy322;}
116894         break;
116895       case 155: /* sortlist ::= sortlist COMMA expr sortorder */
116896 {
116897   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yymsp[-3].minor.yy322,yymsp[-1].minor.yy118.pExpr);
116898   if( yygotominor.yy322 ) yygotominor.yy322->a[yygotominor.yy322->nExpr-1].sortOrder = (u8)yymsp[0].minor.yy4;
116899 }
116900         break;
116901       case 156: /* sortlist ::= expr sortorder */
116902 {
116903   yygotominor.yy322 = sqlite3ExprListAppend(pParse,0,yymsp[-1].minor.yy118.pExpr);
116904   if( yygotominor.yy322 && ALWAYS(yygotominor.yy322->a) ) yygotominor.yy322->a[0].sortOrder = (u8)yymsp[0].minor.yy4;
116905 }
116906         break;
116907       case 157: /* sortorder ::= ASC */
116908       case 159: /* sortorder ::= */ yytestcase(yyruleno==159);
116909 {yygotominor.yy4 = SQLITE_SO_ASC;}
116910         break;
116911       case 158: /* sortorder ::= DESC */
116912 {yygotominor.yy4 = SQLITE_SO_DESC;}
116913         break;
116914       case 164: /* limit_opt ::= */
116915 {yygotominor.yy292.pLimit = 0; yygotominor.yy292.pOffset = 0;}
116916         break;
116917       case 165: /* limit_opt ::= LIMIT expr */
116918 {yygotominor.yy292.pLimit = yymsp[0].minor.yy118.pExpr; yygotominor.yy292.pOffset = 0;}
116919         break;
116920       case 166: /* limit_opt ::= LIMIT expr OFFSET expr */
116921 {yygotominor.yy292.pLimit = yymsp[-2].minor.yy118.pExpr; yygotominor.yy292.pOffset = yymsp[0].minor.yy118.pExpr;}
116922         break;
116923       case 167: /* limit_opt ::= LIMIT expr COMMA expr */
116924 {yygotominor.yy292.pOffset = yymsp[-2].minor.yy118.pExpr; yygotominor.yy292.pLimit = yymsp[0].minor.yy118.pExpr;}
116925         break;
116926       case 168: /* cmd ::= DELETE FROM fullname indexed_opt where_opt */
116927 {
116928   sqlite3SrcListIndexedBy(pParse, yymsp[-2].minor.yy259, &yymsp[-1].minor.yy0);
116929   sqlite3DeleteFrom(pParse,yymsp[-2].minor.yy259,yymsp[0].minor.yy314);
116930 }
116931         break;
116932       case 171: /* cmd ::= UPDATE orconf fullname indexed_opt SET setlist where_opt */
116933 {
116934   sqlite3SrcListIndexedBy(pParse, yymsp[-4].minor.yy259, &yymsp[-3].minor.yy0);
116935   sqlite3ExprListCheckLength(pParse,yymsp[-1].minor.yy322,"set list"); 
116936   sqlite3Update(pParse,yymsp[-4].minor.yy259,yymsp[-1].minor.yy322,yymsp[0].minor.yy314,yymsp[-5].minor.yy210);
116937 }
116938         break;
116939       case 172: /* setlist ::= setlist COMMA nm EQ expr */
116940 {
116941   yygotominor.yy322 = sqlite3ExprListAppend(pParse, yymsp[-4].minor.yy322, yymsp[0].minor.yy118.pExpr);
116942   sqlite3ExprListSetName(pParse, yygotominor.yy322, &yymsp[-2].minor.yy0, 1);
116943 }
116944         break;
116945       case 173: /* setlist ::= nm EQ expr */
116946 {
116947   yygotominor.yy322 = sqlite3ExprListAppend(pParse, 0, yymsp[0].minor.yy118.pExpr);
116948   sqlite3ExprListSetName(pParse, yygotominor.yy322, &yymsp[-2].minor.yy0, 1);
116949 }
116950         break;
116951       case 174: /* cmd ::= insert_cmd INTO fullname inscollist_opt valuelist */
116952 {sqlite3Insert(pParse, yymsp[-2].minor.yy259, yymsp[0].minor.yy260.pList, yymsp[0].minor.yy260.pSelect, yymsp[-1].minor.yy384, yymsp[-4].minor.yy210);}
116953         break;
116954       case 175: /* cmd ::= insert_cmd INTO fullname inscollist_opt select */
116955 {sqlite3Insert(pParse, yymsp[-2].minor.yy259, 0, yymsp[0].minor.yy387, yymsp[-1].minor.yy384, yymsp[-4].minor.yy210);}
116956         break;
116957       case 176: /* cmd ::= insert_cmd INTO fullname inscollist_opt DEFAULT VALUES */
116958 {sqlite3Insert(pParse, yymsp[-3].minor.yy259, 0, 0, yymsp[-2].minor.yy384, yymsp[-5].minor.yy210);}
116959         break;
116960       case 177: /* insert_cmd ::= INSERT orconf */
116961 {yygotominor.yy210 = yymsp[0].minor.yy210;}
116962         break;
116963       case 178: /* insert_cmd ::= REPLACE */
116964 {yygotominor.yy210 = OE_Replace;}
116965         break;
116966       case 179: /* valuelist ::= VALUES LP nexprlist RP */
116967 {
116968   yygotominor.yy260.pList = yymsp[-1].minor.yy322;
116969   yygotominor.yy260.pSelect = 0;
116970 }
116971         break;
116972       case 180: /* valuelist ::= valuelist COMMA LP exprlist RP */
116973 {
116974   Select *pRight = sqlite3SelectNew(pParse, yymsp[-1].minor.yy322, 0, 0, 0, 0, 0, 0, 0, 0);
116975   if( yymsp[-4].minor.yy260.pList ){
116976     yymsp[-4].minor.yy260.pSelect = sqlite3SelectNew(pParse, yymsp[-4].minor.yy260.pList, 0, 0, 0, 0, 0, 0, 0, 0);
116977     yymsp[-4].minor.yy260.pList = 0;
116978   }
116979   yygotominor.yy260.pList = 0;
116980   if( yymsp[-4].minor.yy260.pSelect==0 || pRight==0 ){
116981     sqlite3SelectDelete(pParse->db, pRight);
116982     sqlite3SelectDelete(pParse->db, yymsp[-4].minor.yy260.pSelect);
116983     yygotominor.yy260.pSelect = 0;
116984   }else{
116985     pRight->op = TK_ALL;
116986     pRight->pPrior = yymsp[-4].minor.yy260.pSelect;
116987     pRight->selFlags |= SF_Values;
116988     pRight->pPrior->selFlags |= SF_Values;
116989     yygotominor.yy260.pSelect = pRight;
116990   }
116991 }
116992         break;
116993       case 183: /* idlist ::= idlist COMMA nm */
116994 {yygotominor.yy384 = sqlite3IdListAppend(pParse->db,yymsp[-2].minor.yy384,&yymsp[0].minor.yy0);}
116995         break;
116996       case 184: /* idlist ::= nm */
116997 {yygotominor.yy384 = sqlite3IdListAppend(pParse->db,0,&yymsp[0].minor.yy0);}
116998         break;
116999       case 185: /* expr ::= term */
117000 {yygotominor.yy118 = yymsp[0].minor.yy118;}
117001         break;
117002       case 186: /* expr ::= LP expr RP */
117003 {yygotominor.yy118.pExpr = yymsp[-1].minor.yy118.pExpr; spanSet(&yygotominor.yy118,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0);}
117004         break;
117005       case 187: /* term ::= NULL */
117006       case 192: /* term ::= INTEGER|FLOAT|BLOB */ yytestcase(yyruleno==192);
117007       case 193: /* term ::= STRING */ yytestcase(yyruleno==193);
117008 {spanExpr(&yygotominor.yy118, pParse, yymsp[0].major, &yymsp[0].minor.yy0);}
117009         break;
117010       case 188: /* expr ::= id */
117011       case 189: /* expr ::= JOIN_KW */ yytestcase(yyruleno==189);
117012 {spanExpr(&yygotominor.yy118, pParse, TK_ID, &yymsp[0].minor.yy0);}
117013         break;
117014       case 190: /* expr ::= nm DOT nm */
117015 {
117016   Expr *temp1 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy0);
117017   Expr *temp2 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[0].minor.yy0);
117018   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_DOT, temp1, temp2, 0);
117019   spanSet(&yygotominor.yy118,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0);
117020 }
117021         break;
117022       case 191: /* expr ::= nm DOT nm DOT nm */
117023 {
117024   Expr *temp1 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-4].minor.yy0);
117025   Expr *temp2 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy0);
117026   Expr *temp3 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[0].minor.yy0);
117027   Expr *temp4 = sqlite3PExpr(pParse, TK_DOT, temp2, temp3, 0);
117028   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_DOT, temp1, temp4, 0);
117029   spanSet(&yygotominor.yy118,&yymsp[-4].minor.yy0,&yymsp[0].minor.yy0);
117030 }
117031         break;
117032       case 194: /* expr ::= REGISTER */
117033 {
117034   /* When doing a nested parse, one can include terms in an expression
117035   ** that look like this:   #1 #2 ...  These terms refer to registers
117036   ** in the virtual machine.  #N is the N-th register. */
117037   if( pParse->nested==0 ){
117038     sqlite3ErrorMsg(pParse, "near \"%T\": syntax error", &yymsp[0].minor.yy0);
117039     yygotominor.yy118.pExpr = 0;
117040   }else{
117041     yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_REGISTER, 0, 0, &yymsp[0].minor.yy0);
117042     if( yygotominor.yy118.pExpr ) sqlite3GetInt32(&yymsp[0].minor.yy0.z[1], &yygotominor.yy118.pExpr->iTable);
117043   }
117044   spanSet(&yygotominor.yy118, &yymsp[0].minor.yy0, &yymsp[0].minor.yy0);
117045 }
117046         break;
117047       case 195: /* expr ::= VARIABLE */
117048 {
117049   spanExpr(&yygotominor.yy118, pParse, TK_VARIABLE, &yymsp[0].minor.yy0);
117050   sqlite3ExprAssignVarNumber(pParse, yygotominor.yy118.pExpr);
117051   spanSet(&yygotominor.yy118, &yymsp[0].minor.yy0, &yymsp[0].minor.yy0);
117052 }
117053         break;
117054       case 196: /* expr ::= expr COLLATE ids */
117055 {
117056   yygotominor.yy118.pExpr = sqlite3ExprAddCollateToken(pParse, yymsp[-2].minor.yy118.pExpr, &yymsp[0].minor.yy0);
117057   yygotominor.yy118.zStart = yymsp[-2].minor.yy118.zStart;
117058   yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117059 }
117060         break;
117061       case 197: /* expr ::= CAST LP expr AS typetoken RP */
117062 {
117063   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_CAST, yymsp[-3].minor.yy118.pExpr, 0, &yymsp[-1].minor.yy0);
117064   spanSet(&yygotominor.yy118,&yymsp[-5].minor.yy0,&yymsp[0].minor.yy0);
117065 }
117066         break;
117067       case 198: /* expr ::= ID LP distinct exprlist RP */
117068 {
117069   if( yymsp[-1].minor.yy322 && yymsp[-1].minor.yy322->nExpr>pParse->db->aLimit[SQLITE_LIMIT_FUNCTION_ARG] ){
117070     sqlite3ErrorMsg(pParse, "too many arguments on function %T", &yymsp[-4].minor.yy0);
117071   }
117072   yygotominor.yy118.pExpr = sqlite3ExprFunction(pParse, yymsp[-1].minor.yy322, &yymsp[-4].minor.yy0);
117073   spanSet(&yygotominor.yy118,&yymsp[-4].minor.yy0,&yymsp[0].minor.yy0);
117074   if( yymsp[-2].minor.yy177 && yygotominor.yy118.pExpr ){
117075     yygotominor.yy118.pExpr->flags |= EP_Distinct;
117076   }
117077 }
117078         break;
117079       case 199: /* expr ::= ID LP STAR RP */
117080 {
117081   yygotominor.yy118.pExpr = sqlite3ExprFunction(pParse, 0, &yymsp[-3].minor.yy0);
117082   spanSet(&yygotominor.yy118,&yymsp[-3].minor.yy0,&yymsp[0].minor.yy0);
117083 }
117084         break;
117085       case 200: /* term ::= CTIME_KW */
117086 {
117087   yygotominor.yy118.pExpr = sqlite3ExprFunction(pParse, 0, &yymsp[0].minor.yy0);
117088   spanSet(&yygotominor.yy118, &yymsp[0].minor.yy0, &yymsp[0].minor.yy0);
117089 }
117090         break;
117091       case 201: /* expr ::= expr AND expr */
117092       case 202: /* expr ::= expr OR expr */ yytestcase(yyruleno==202);
117093       case 203: /* expr ::= expr LT|GT|GE|LE expr */ yytestcase(yyruleno==203);
117094       case 204: /* expr ::= expr EQ|NE expr */ yytestcase(yyruleno==204);
117095       case 205: /* expr ::= expr BITAND|BITOR|LSHIFT|RSHIFT expr */ yytestcase(yyruleno==205);
117096       case 206: /* expr ::= expr PLUS|MINUS expr */ yytestcase(yyruleno==206);
117097       case 207: /* expr ::= expr STAR|SLASH|REM expr */ yytestcase(yyruleno==207);
117098       case 208: /* expr ::= expr CONCAT expr */ yytestcase(yyruleno==208);
117099 {spanBinaryExpr(&yygotominor.yy118,pParse,yymsp[-1].major,&yymsp[-2].minor.yy118,&yymsp[0].minor.yy118);}
117100         break;
117101       case 209: /* likeop ::= LIKE_KW */
117102       case 211: /* likeop ::= MATCH */ yytestcase(yyruleno==211);
117103 {yygotominor.yy342.eOperator = yymsp[0].minor.yy0; yygotominor.yy342.bNot = 0;}
117104         break;
117105       case 210: /* likeop ::= NOT LIKE_KW */
117106       case 212: /* likeop ::= NOT MATCH */ yytestcase(yyruleno==212);
117107 {yygotominor.yy342.eOperator = yymsp[0].minor.yy0; yygotominor.yy342.bNot = 1;}
117108         break;
117109       case 213: /* expr ::= expr likeop expr */
117110 {
117111   ExprList *pList;
117112   pList = sqlite3ExprListAppend(pParse,0, yymsp[0].minor.yy118.pExpr);
117113   pList = sqlite3ExprListAppend(pParse,pList, yymsp[-2].minor.yy118.pExpr);
117114   yygotominor.yy118.pExpr = sqlite3ExprFunction(pParse, pList, &yymsp[-1].minor.yy342.eOperator);
117115   if( yymsp[-1].minor.yy342.bNot ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117116   yygotominor.yy118.zStart = yymsp[-2].minor.yy118.zStart;
117117   yygotominor.yy118.zEnd = yymsp[0].minor.yy118.zEnd;
117118   if( yygotominor.yy118.pExpr ) yygotominor.yy118.pExpr->flags |= EP_InfixFunc;
117119 }
117120         break;
117121       case 214: /* expr ::= expr likeop expr ESCAPE expr */
117122 {
117123   ExprList *pList;
117124   pList = sqlite3ExprListAppend(pParse,0, yymsp[-2].minor.yy118.pExpr);
117125   pList = sqlite3ExprListAppend(pParse,pList, yymsp[-4].minor.yy118.pExpr);
117126   pList = sqlite3ExprListAppend(pParse,pList, yymsp[0].minor.yy118.pExpr);
117127   yygotominor.yy118.pExpr = sqlite3ExprFunction(pParse, pList, &yymsp[-3].minor.yy342.eOperator);
117128   if( yymsp[-3].minor.yy342.bNot ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117129   yygotominor.yy118.zStart = yymsp[-4].minor.yy118.zStart;
117130   yygotominor.yy118.zEnd = yymsp[0].minor.yy118.zEnd;
117131   if( yygotominor.yy118.pExpr ) yygotominor.yy118.pExpr->flags |= EP_InfixFunc;
117132 }
117133         break;
117134       case 215: /* expr ::= expr ISNULL|NOTNULL */
117135 {spanUnaryPostfix(&yygotominor.yy118,pParse,yymsp[0].major,&yymsp[-1].minor.yy118,&yymsp[0].minor.yy0);}
117136         break;
117137       case 216: /* expr ::= expr NOT NULL */
117138 {spanUnaryPostfix(&yygotominor.yy118,pParse,TK_NOTNULL,&yymsp[-2].minor.yy118,&yymsp[0].minor.yy0);}
117139         break;
117140       case 217: /* expr ::= expr IS expr */
117141 {
117142   spanBinaryExpr(&yygotominor.yy118,pParse,TK_IS,&yymsp[-2].minor.yy118,&yymsp[0].minor.yy118);
117143   binaryToUnaryIfNull(pParse, yymsp[0].minor.yy118.pExpr, yygotominor.yy118.pExpr, TK_ISNULL);
117144 }
117145         break;
117146       case 218: /* expr ::= expr IS NOT expr */
117147 {
117148   spanBinaryExpr(&yygotominor.yy118,pParse,TK_ISNOT,&yymsp[-3].minor.yy118,&yymsp[0].minor.yy118);
117149   binaryToUnaryIfNull(pParse, yymsp[0].minor.yy118.pExpr, yygotominor.yy118.pExpr, TK_NOTNULL);
117150 }
117151         break;
117152       case 219: /* expr ::= NOT expr */
117153       case 220: /* expr ::= BITNOT expr */ yytestcase(yyruleno==220);
117154 {spanUnaryPrefix(&yygotominor.yy118,pParse,yymsp[-1].major,&yymsp[0].minor.yy118,&yymsp[-1].minor.yy0);}
117155         break;
117156       case 221: /* expr ::= MINUS expr */
117157 {spanUnaryPrefix(&yygotominor.yy118,pParse,TK_UMINUS,&yymsp[0].minor.yy118,&yymsp[-1].minor.yy0);}
117158         break;
117159       case 222: /* expr ::= PLUS expr */
117160 {spanUnaryPrefix(&yygotominor.yy118,pParse,TK_UPLUS,&yymsp[0].minor.yy118,&yymsp[-1].minor.yy0);}
117161         break;
117162       case 225: /* expr ::= expr between_op expr AND expr */
117163 {
117164   ExprList *pList = sqlite3ExprListAppend(pParse,0, yymsp[-2].minor.yy118.pExpr);
117165   pList = sqlite3ExprListAppend(pParse,pList, yymsp[0].minor.yy118.pExpr);
117166   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_BETWEEN, yymsp[-4].minor.yy118.pExpr, 0, 0);
117167   if( yygotominor.yy118.pExpr ){
117168     yygotominor.yy118.pExpr->x.pList = pList;
117169   }else{
117170     sqlite3ExprListDelete(pParse->db, pList);
117171   } 
117172   if( yymsp[-3].minor.yy4 ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117173   yygotominor.yy118.zStart = yymsp[-4].minor.yy118.zStart;
117174   yygotominor.yy118.zEnd = yymsp[0].minor.yy118.zEnd;
117175 }
117176         break;
117177       case 228: /* expr ::= expr in_op LP exprlist RP */
117178 {
117179     if( yymsp[-1].minor.yy322==0 ){
117180       /* Expressions of the form
117181       **
117182       **      expr1 IN ()
117183       **      expr1 NOT IN ()
117184       **
117185       ** simplify to constants 0 (false) and 1 (true), respectively,
117186       ** regardless of the value of expr1.
117187       */
117188       yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_INTEGER, 0, 0, &sqlite3IntTokens[yymsp[-3].minor.yy4]);
117189       sqlite3ExprDelete(pParse->db, yymsp[-4].minor.yy118.pExpr);
117190     }else{
117191       yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_IN, yymsp[-4].minor.yy118.pExpr, 0, 0);
117192       if( yygotominor.yy118.pExpr ){
117193         yygotominor.yy118.pExpr->x.pList = yymsp[-1].minor.yy322;
117194         sqlite3ExprSetHeight(pParse, yygotominor.yy118.pExpr);
117195       }else{
117196         sqlite3ExprListDelete(pParse->db, yymsp[-1].minor.yy322);
117197       }
117198       if( yymsp[-3].minor.yy4 ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117199     }
117200     yygotominor.yy118.zStart = yymsp[-4].minor.yy118.zStart;
117201     yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117202   }
117203         break;
117204       case 229: /* expr ::= LP select RP */
117205 {
117206     yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_SELECT, 0, 0, 0);
117207     if( yygotominor.yy118.pExpr ){
117208       yygotominor.yy118.pExpr->x.pSelect = yymsp[-1].minor.yy387;
117209       ExprSetProperty(yygotominor.yy118.pExpr, EP_xIsSelect);
117210       sqlite3ExprSetHeight(pParse, yygotominor.yy118.pExpr);
117211     }else{
117212       sqlite3SelectDelete(pParse->db, yymsp[-1].minor.yy387);
117213     }
117214     yygotominor.yy118.zStart = yymsp[-2].minor.yy0.z;
117215     yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117216   }
117217         break;
117218       case 230: /* expr ::= expr in_op LP select RP */
117219 {
117220     yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_IN, yymsp[-4].minor.yy118.pExpr, 0, 0);
117221     if( yygotominor.yy118.pExpr ){
117222       yygotominor.yy118.pExpr->x.pSelect = yymsp[-1].minor.yy387;
117223       ExprSetProperty(yygotominor.yy118.pExpr, EP_xIsSelect);
117224       sqlite3ExprSetHeight(pParse, yygotominor.yy118.pExpr);
117225     }else{
117226       sqlite3SelectDelete(pParse->db, yymsp[-1].minor.yy387);
117227     }
117228     if( yymsp[-3].minor.yy4 ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117229     yygotominor.yy118.zStart = yymsp[-4].minor.yy118.zStart;
117230     yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117231   }
117232         break;
117233       case 231: /* expr ::= expr in_op nm dbnm */
117234 {
117235     SrcList *pSrc = sqlite3SrcListAppend(pParse->db, 0,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0);
117236     yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_IN, yymsp[-3].minor.yy118.pExpr, 0, 0);
117237     if( yygotominor.yy118.pExpr ){
117238       yygotominor.yy118.pExpr->x.pSelect = sqlite3SelectNew(pParse, 0,pSrc,0,0,0,0,0,0,0);
117239       ExprSetProperty(yygotominor.yy118.pExpr, EP_xIsSelect);
117240       sqlite3ExprSetHeight(pParse, yygotominor.yy118.pExpr);
117241     }else{
117242       sqlite3SrcListDelete(pParse->db, pSrc);
117243     }
117244     if( yymsp[-2].minor.yy4 ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117245     yygotominor.yy118.zStart = yymsp[-3].minor.yy118.zStart;
117246     yygotominor.yy118.zEnd = yymsp[0].minor.yy0.z ? &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n] : &yymsp[-1].minor.yy0.z[yymsp[-1].minor.yy0.n];
117247   }
117248         break;
117249       case 232: /* expr ::= EXISTS LP select RP */
117250 {
117251     Expr *p = yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_EXISTS, 0, 0, 0);
117252     if( p ){
117253       p->x.pSelect = yymsp[-1].minor.yy387;
117254       ExprSetProperty(p, EP_xIsSelect);
117255       sqlite3ExprSetHeight(pParse, p);
117256     }else{
117257       sqlite3SelectDelete(pParse->db, yymsp[-1].minor.yy387);
117258     }
117259     yygotominor.yy118.zStart = yymsp[-3].minor.yy0.z;
117260     yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117261   }
117262         break;
117263       case 233: /* expr ::= CASE case_operand case_exprlist case_else END */
117264 {
117265   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_CASE, yymsp[-3].minor.yy314, 0, 0);
117266   if( yygotominor.yy118.pExpr ){
117267     yygotominor.yy118.pExpr->x.pList = yymsp[-1].minor.yy314 ? sqlite3ExprListAppend(pParse,yymsp[-2].minor.yy322,yymsp[-1].minor.yy314) : yymsp[-2].minor.yy322;
117268     sqlite3ExprSetHeight(pParse, yygotominor.yy118.pExpr);
117269   }else{
117270     sqlite3ExprListDelete(pParse->db, yymsp[-2].minor.yy322);
117271     sqlite3ExprDelete(pParse->db, yymsp[-1].minor.yy314);
117272   }
117273   yygotominor.yy118.zStart = yymsp[-4].minor.yy0.z;
117274   yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117275 }
117276         break;
117277       case 234: /* case_exprlist ::= case_exprlist WHEN expr THEN expr */
117278 {
117279   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yymsp[-4].minor.yy322, yymsp[-2].minor.yy118.pExpr);
117280   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yygotominor.yy322, yymsp[0].minor.yy118.pExpr);
117281 }
117282         break;
117283       case 235: /* case_exprlist ::= WHEN expr THEN expr */
117284 {
117285   yygotominor.yy322 = sqlite3ExprListAppend(pParse,0, yymsp[-2].minor.yy118.pExpr);
117286   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yygotominor.yy322, yymsp[0].minor.yy118.pExpr);
117287 }
117288         break;
117289       case 242: /* nexprlist ::= nexprlist COMMA expr */
117290 {yygotominor.yy322 = sqlite3ExprListAppend(pParse,yymsp[-2].minor.yy322,yymsp[0].minor.yy118.pExpr);}
117291         break;
117292       case 243: /* nexprlist ::= expr */
117293 {yygotominor.yy322 = sqlite3ExprListAppend(pParse,0,yymsp[0].minor.yy118.pExpr);}
117294         break;
117295       case 244: /* cmd ::= createkw uniqueflag INDEX ifnotexists nm dbnm ON nm LP idxlist RP where_opt */
117296 {
117297   sqlite3CreateIndex(pParse, &yymsp[-7].minor.yy0, &yymsp[-6].minor.yy0, 
117298                      sqlite3SrcListAppend(pParse->db,0,&yymsp[-4].minor.yy0,0), yymsp[-2].minor.yy322, yymsp[-10].minor.yy4,
117299                       &yymsp[-11].minor.yy0, yymsp[0].minor.yy314, SQLITE_SO_ASC, yymsp[-8].minor.yy4);
117300 }
117301         break;
117302       case 245: /* uniqueflag ::= UNIQUE */
117303       case 298: /* raisetype ::= ABORT */ yytestcase(yyruleno==298);
117304 {yygotominor.yy4 = OE_Abort;}
117305         break;
117306       case 246: /* uniqueflag ::= */
117307 {yygotominor.yy4 = OE_None;}
117308         break;
117309       case 249: /* idxlist ::= idxlist COMMA nm collate sortorder */
117310 {
117311   Expr *p = sqlite3ExprAddCollateToken(pParse, 0, &yymsp[-1].minor.yy0);
117312   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yymsp[-4].minor.yy322, p);
117313   sqlite3ExprListSetName(pParse,yygotominor.yy322,&yymsp[-2].minor.yy0,1);
117314   sqlite3ExprListCheckLength(pParse, yygotominor.yy322, "index");
117315   if( yygotominor.yy322 ) yygotominor.yy322->a[yygotominor.yy322->nExpr-1].sortOrder = (u8)yymsp[0].minor.yy4;
117316 }
117317         break;
117318       case 250: /* idxlist ::= nm collate sortorder */
117319 {
117320   Expr *p = sqlite3ExprAddCollateToken(pParse, 0, &yymsp[-1].minor.yy0);
117321   yygotominor.yy322 = sqlite3ExprListAppend(pParse,0, p);
117322   sqlite3ExprListSetName(pParse, yygotominor.yy322, &yymsp[-2].minor.yy0, 1);
117323   sqlite3ExprListCheckLength(pParse, yygotominor.yy322, "index");
117324   if( yygotominor.yy322 ) yygotominor.yy322->a[yygotominor.yy322->nExpr-1].sortOrder = (u8)yymsp[0].minor.yy4;
117325 }
117326         break;
117327       case 251: /* collate ::= */
117328 {yygotominor.yy0.z = 0; yygotominor.yy0.n = 0;}
117329         break;
117330       case 253: /* cmd ::= DROP INDEX ifexists fullname */
117331 {sqlite3DropIndex(pParse, yymsp[0].minor.yy259, yymsp[-1].minor.yy4);}
117332         break;
117333       case 254: /* cmd ::= VACUUM */
117334       case 255: /* cmd ::= VACUUM nm */ yytestcase(yyruleno==255);
117335 {sqlite3Vacuum(pParse);}
117336         break;
117337       case 256: /* cmd ::= PRAGMA nm dbnm */
117338 {sqlite3Pragma(pParse,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0,0,0);}
117339         break;
117340       case 257: /* cmd ::= PRAGMA nm dbnm EQ nmnum */
117341 {sqlite3Pragma(pParse,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0,0);}
117342         break;
117343       case 258: /* cmd ::= PRAGMA nm dbnm LP nmnum RP */
117344 {sqlite3Pragma(pParse,&yymsp[-4].minor.yy0,&yymsp[-3].minor.yy0,&yymsp[-1].minor.yy0,0);}
117345         break;
117346       case 259: /* cmd ::= PRAGMA nm dbnm EQ minus_num */
117347 {sqlite3Pragma(pParse,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0,1);}
117348         break;
117349       case 260: /* cmd ::= PRAGMA nm dbnm LP minus_num RP */
117350 {sqlite3Pragma(pParse,&yymsp[-4].minor.yy0,&yymsp[-3].minor.yy0,&yymsp[-1].minor.yy0,1);}
117351         break;
117352       case 270: /* cmd ::= createkw trigger_decl BEGIN trigger_cmd_list END */
117353 {
117354   Token all;
117355   all.z = yymsp[-3].minor.yy0.z;
117356   all.n = (int)(yymsp[0].minor.yy0.z - yymsp[-3].minor.yy0.z) + yymsp[0].minor.yy0.n;
117357   sqlite3FinishTrigger(pParse, yymsp[-1].minor.yy203, &all);
117358 }
117359         break;
117360       case 271: /* trigger_decl ::= temp TRIGGER ifnotexists nm dbnm trigger_time trigger_event ON fullname foreach_clause when_clause */
117361 {
117362   sqlite3BeginTrigger(pParse, &yymsp[-7].minor.yy0, &yymsp[-6].minor.yy0, yymsp[-5].minor.yy4, yymsp[-4].minor.yy90.a, yymsp[-4].minor.yy90.b, yymsp[-2].minor.yy259, yymsp[0].minor.yy314, yymsp[-10].minor.yy4, yymsp[-8].minor.yy4);
117363   yygotominor.yy0 = (yymsp[-6].minor.yy0.n==0?yymsp[-7].minor.yy0:yymsp[-6].minor.yy0);
117364 }
117365         break;
117366       case 272: /* trigger_time ::= BEFORE */
117367       case 275: /* trigger_time ::= */ yytestcase(yyruleno==275);
117368 { yygotominor.yy4 = TK_BEFORE; }
117369         break;
117370       case 273: /* trigger_time ::= AFTER */
117371 { yygotominor.yy4 = TK_AFTER;  }
117372         break;
117373       case 274: /* trigger_time ::= INSTEAD OF */
117374 { yygotominor.yy4 = TK_INSTEAD;}
117375         break;
117376       case 276: /* trigger_event ::= DELETE|INSERT */
117377       case 277: /* trigger_event ::= UPDATE */ yytestcase(yyruleno==277);
117378 {yygotominor.yy90.a = yymsp[0].major; yygotominor.yy90.b = 0;}
117379         break;
117380       case 278: /* trigger_event ::= UPDATE OF idlist */
117381 {yygotominor.yy90.a = TK_UPDATE; yygotominor.yy90.b = yymsp[0].minor.yy384;}
117382         break;
117383       case 281: /* when_clause ::= */
117384       case 303: /* key_opt ::= */ yytestcase(yyruleno==303);
117385 { yygotominor.yy314 = 0; }
117386         break;
117387       case 282: /* when_clause ::= WHEN expr */
117388       case 304: /* key_opt ::= KEY expr */ yytestcase(yyruleno==304);
117389 { yygotominor.yy314 = yymsp[0].minor.yy118.pExpr; }
117390         break;
117391       case 283: /* trigger_cmd_list ::= trigger_cmd_list trigger_cmd SEMI */
117392 {
117393   assert( yymsp[-2].minor.yy203!=0 );
117394   yymsp[-2].minor.yy203->pLast->pNext = yymsp[-1].minor.yy203;
117395   yymsp[-2].minor.yy203->pLast = yymsp[-1].minor.yy203;
117396   yygotominor.yy203 = yymsp[-2].minor.yy203;
117397 }
117398         break;
117399       case 284: /* trigger_cmd_list ::= trigger_cmd SEMI */
117400 { 
117401   assert( yymsp[-1].minor.yy203!=0 );
117402   yymsp[-1].minor.yy203->pLast = yymsp[-1].minor.yy203;
117403   yygotominor.yy203 = yymsp[-1].minor.yy203;
117404 }
117405         break;
117406       case 286: /* trnm ::= nm DOT nm */
117407 {
117408   yygotominor.yy0 = yymsp[0].minor.yy0;
117409   sqlite3ErrorMsg(pParse, 
117410         "qualified table names are not allowed on INSERT, UPDATE, and DELETE "
117411         "statements within triggers");
117412 }
117413         break;
117414       case 288: /* tridxby ::= INDEXED BY nm */
117415 {
117416   sqlite3ErrorMsg(pParse,
117417         "the INDEXED BY clause is not allowed on UPDATE or DELETE statements "
117418         "within triggers");
117419 }
117420         break;
117421       case 289: /* tridxby ::= NOT INDEXED */
117422 {
117423   sqlite3ErrorMsg(pParse,
117424         "the NOT INDEXED clause is not allowed on UPDATE or DELETE statements "
117425         "within triggers");
117426 }
117427         break;
117428       case 290: /* trigger_cmd ::= UPDATE orconf trnm tridxby SET setlist where_opt */
117429 { yygotominor.yy203 = sqlite3TriggerUpdateStep(pParse->db, &yymsp[-4].minor.yy0, yymsp[-1].minor.yy322, yymsp[0].minor.yy314, yymsp[-5].minor.yy210); }
117430         break;
117431       case 291: /* trigger_cmd ::= insert_cmd INTO trnm inscollist_opt valuelist */
117432 {yygotominor.yy203 = sqlite3TriggerInsertStep(pParse->db, &yymsp[-2].minor.yy0, yymsp[-1].minor.yy384, yymsp[0].minor.yy260.pList, yymsp[0].minor.yy260.pSelect, yymsp[-4].minor.yy210);}
117433         break;
117434       case 292: /* trigger_cmd ::= insert_cmd INTO trnm inscollist_opt select */
117435 {yygotominor.yy203 = sqlite3TriggerInsertStep(pParse->db, &yymsp[-2].minor.yy0, yymsp[-1].minor.yy384, 0, yymsp[0].minor.yy387, yymsp[-4].minor.yy210);}
117436         break;
117437       case 293: /* trigger_cmd ::= DELETE FROM trnm tridxby where_opt */
117438 {yygotominor.yy203 = sqlite3TriggerDeleteStep(pParse->db, &yymsp[-2].minor.yy0, yymsp[0].minor.yy314);}
117439         break;
117440       case 294: /* trigger_cmd ::= select */
117441 {yygotominor.yy203 = sqlite3TriggerSelectStep(pParse->db, yymsp[0].minor.yy387); }
117442         break;
117443       case 295: /* expr ::= RAISE LP IGNORE RP */
117444 {
117445   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_RAISE, 0, 0, 0); 
117446   if( yygotominor.yy118.pExpr ){
117447     yygotominor.yy118.pExpr->affinity = OE_Ignore;
117448   }
117449   yygotominor.yy118.zStart = yymsp[-3].minor.yy0.z;
117450   yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117451 }
117452         break;
117453       case 296: /* expr ::= RAISE LP raisetype COMMA nm RP */
117454 {
117455   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_RAISE, 0, 0, &yymsp[-1].minor.yy0); 
117456   if( yygotominor.yy118.pExpr ) {
117457     yygotominor.yy118.pExpr->affinity = (char)yymsp[-3].minor.yy4;
117458   }
117459   yygotominor.yy118.zStart = yymsp[-5].minor.yy0.z;
117460   yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117461 }
117462         break;
117463       case 297: /* raisetype ::= ROLLBACK */
117464 {yygotominor.yy4 = OE_Rollback;}
117465         break;
117466       case 299: /* raisetype ::= FAIL */
117467 {yygotominor.yy4 = OE_Fail;}
117468         break;
117469       case 300: /* cmd ::= DROP TRIGGER ifexists fullname */
117470 {
117471   sqlite3DropTrigger(pParse,yymsp[0].minor.yy259,yymsp[-1].minor.yy4);
117472 }
117473         break;
117474       case 301: /* cmd ::= ATTACH database_kw_opt expr AS expr key_opt */
117475 {
117476   sqlite3Attach(pParse, yymsp[-3].minor.yy118.pExpr, yymsp[-1].minor.yy118.pExpr, yymsp[0].minor.yy314);
117477 }
117478         break;
117479       case 302: /* cmd ::= DETACH database_kw_opt expr */
117480 {
117481   sqlite3Detach(pParse, yymsp[0].minor.yy118.pExpr);
117482 }
117483         break;
117484       case 307: /* cmd ::= REINDEX */
117485 {sqlite3Reindex(pParse, 0, 0);}
117486         break;
117487       case 308: /* cmd ::= REINDEX nm dbnm */
117488 {sqlite3Reindex(pParse, &yymsp[-1].minor.yy0, &yymsp[0].minor.yy0);}
117489         break;
117490       case 309: /* cmd ::= ANALYZE */
117491 {sqlite3Analyze(pParse, 0, 0);}
117492         break;
117493       case 310: /* cmd ::= ANALYZE nm dbnm */
117494 {sqlite3Analyze(pParse, &yymsp[-1].minor.yy0, &yymsp[0].minor.yy0);}
117495         break;
117496       case 311: /* cmd ::= ALTER TABLE fullname RENAME TO nm */
117497 {
117498   sqlite3AlterRenameTable(pParse,yymsp[-3].minor.yy259,&yymsp[0].minor.yy0);
117499 }
117500         break;
117501       case 312: /* cmd ::= ALTER TABLE add_column_fullname ADD kwcolumn_opt column */
117502 {
117503   sqlite3AlterFinishAddColumn(pParse, &yymsp[0].minor.yy0);
117504 }
117505         break;
117506       case 313: /* add_column_fullname ::= fullname */
117507 {
117508   pParse->db->lookaside.bEnabled = 0;
117509   sqlite3AlterBeginAddColumn(pParse, yymsp[0].minor.yy259);
117510 }
117511         break;
117512       case 316: /* cmd ::= create_vtab */
117513 {sqlite3VtabFinishParse(pParse,0);}
117514         break;
117515       case 317: /* cmd ::= create_vtab LP vtabarglist RP */
117516 {sqlite3VtabFinishParse(pParse,&yymsp[0].minor.yy0);}
117517         break;
117518       case 318: /* create_vtab ::= createkw VIRTUAL TABLE ifnotexists nm dbnm USING nm */
117519 {
117520     sqlite3VtabBeginParse(pParse, &yymsp[-3].minor.yy0, &yymsp[-2].minor.yy0, &yymsp[0].minor.yy0, yymsp[-4].minor.yy4);
117521 }
117522         break;
117523       case 321: /* vtabarg ::= */
117524 {sqlite3VtabArgInit(pParse);}
117525         break;
117526       case 323: /* vtabargtoken ::= ANY */
117527       case 324: /* vtabargtoken ::= lp anylist RP */ yytestcase(yyruleno==324);
117528       case 325: /* lp ::= LP */ yytestcase(yyruleno==325);
117529 {sqlite3VtabArgExtend(pParse,&yymsp[0].minor.yy0);}
117530         break;
117531       default:
117532       /* (0) input ::= cmdlist */ yytestcase(yyruleno==0);
117533       /* (1) cmdlist ::= cmdlist ecmd */ yytestcase(yyruleno==1);
117534       /* (2) cmdlist ::= ecmd */ yytestcase(yyruleno==2);
117535       /* (3) ecmd ::= SEMI */ yytestcase(yyruleno==3);
117536       /* (4) ecmd ::= explain cmdx SEMI */ yytestcase(yyruleno==4);
117537       /* (10) trans_opt ::= */ yytestcase(yyruleno==10);
117538       /* (11) trans_opt ::= TRANSACTION */ yytestcase(yyruleno==11);
117539       /* (12) trans_opt ::= TRANSACTION nm */ yytestcase(yyruleno==12);
117540       /* (20) savepoint_opt ::= SAVEPOINT */ yytestcase(yyruleno==20);
117541       /* (21) savepoint_opt ::= */ yytestcase(yyruleno==21);
117542       /* (25) cmd ::= create_table create_table_args */ yytestcase(yyruleno==25);
117543       /* (36) columnlist ::= columnlist COMMA column */ yytestcase(yyruleno==36);
117544       /* (37) columnlist ::= column */ yytestcase(yyruleno==37);
117545       /* (46) type ::= */ yytestcase(yyruleno==46);
117546       /* (53) signed ::= plus_num */ yytestcase(yyruleno==53);
117547       /* (54) signed ::= minus_num */ yytestcase(yyruleno==54);
117548       /* (55) carglist ::= carglist ccons */ yytestcase(yyruleno==55);
117549       /* (56) carglist ::= */ yytestcase(yyruleno==56);
117550       /* (63) ccons ::= NULL onconf */ yytestcase(yyruleno==63);
117551       /* (91) conslist ::= conslist tconscomma tcons */ yytestcase(yyruleno==91);
117552       /* (92) conslist ::= tcons */ yytestcase(yyruleno==92);
117553       /* (94) tconscomma ::= */ yytestcase(yyruleno==94);
117554       /* (279) foreach_clause ::= */ yytestcase(yyruleno==279);
117555       /* (280) foreach_clause ::= FOR EACH ROW */ yytestcase(yyruleno==280);
117556       /* (287) tridxby ::= */ yytestcase(yyruleno==287);
117557       /* (305) database_kw_opt ::= DATABASE */ yytestcase(yyruleno==305);
117558       /* (306) database_kw_opt ::= */ yytestcase(yyruleno==306);
117559       /* (314) kwcolumn_opt ::= */ yytestcase(yyruleno==314);
117560       /* (315) kwcolumn_opt ::= COLUMNKW */ yytestcase(yyruleno==315);
117561       /* (319) vtabarglist ::= vtabarg */ yytestcase(yyruleno==319);
117562       /* (320) vtabarglist ::= vtabarglist COMMA vtabarg */ yytestcase(yyruleno==320);
117563       /* (322) vtabarg ::= vtabarg vtabargtoken */ yytestcase(yyruleno==322);
117564       /* (326) anylist ::= */ yytestcase(yyruleno==326);
117565       /* (327) anylist ::= anylist LP anylist RP */ yytestcase(yyruleno==327);
117566       /* (328) anylist ::= anylist ANY */ yytestcase(yyruleno==328);
117567         break;
117568   };
117569   assert( yyruleno>=0 && yyruleno<sizeof(yyRuleInfo)/sizeof(yyRuleInfo[0]) );
117570   yygoto = yyRuleInfo[yyruleno].lhs;
117571   yysize = yyRuleInfo[yyruleno].nrhs;
117572   yypParser->yyidx -= yysize;
117573   yyact = yy_find_reduce_action(yymsp[-yysize].stateno,(YYCODETYPE)yygoto);
117574   if( yyact < YYNSTATE ){
117575 #ifdef NDEBUG
117576     /* If we are not debugging and the reduce action popped at least
117577     ** one element off the stack, then we can push the new element back
117578     ** onto the stack here, and skip the stack overflow test in yy_shift().
117579     ** That gives a significant speed improvement. */
117580     if( yysize ){
117581       yypParser->yyidx++;
117582       yymsp -= yysize-1;
117583       yymsp->stateno = (YYACTIONTYPE)yyact;
117584       yymsp->major = (YYCODETYPE)yygoto;
117585       yymsp->minor = yygotominor;
117586     }else
117587 #endif
117588     {
117589       yy_shift(yypParser,yyact,yygoto,&yygotominor);
117590     }
117591   }else{
117592     assert( yyact == YYNSTATE + YYNRULE + 1 );
117593     yy_accept(yypParser);
117594   }
117595 }
117596 
117597 /*
117598 ** The following code executes when the parse fails
117599 */
117600 #ifndef YYNOERRORRECOVERY
117601 static void yy_parse_failed(
117602   yyParser *yypParser           /* The parser */
117603 ){
117604   sqlite3ParserARG_FETCH;
117605 #ifndef NDEBUG
117606   if( yyTraceFILE ){
117607     fprintf(yyTraceFILE,"%sFail!\n",yyTracePrompt);
117608   }
117609 #endif
117610   while( yypParser->yyidx>=0 ) yy_pop_parser_stack(yypParser);
117611   /* Here code is inserted which will be executed whenever the
117612   ** parser fails */
117613   sqlite3ParserARG_STORE; /* Suppress warning about unused %extra_argument variable */
117614 }
117615 #endif /* YYNOERRORRECOVERY */
117616 
117617 /*
117618 ** The following code executes when a syntax error first occurs.
117619 */
117620 static void yy_syntax_error(
117621   yyParser *yypParser,           /* The parser */
117622   int yymajor,                   /* The major type of the error token */
117623   YYMINORTYPE yyminor            /* The minor type of the error token */
117624 ){
117625   sqlite3ParserARG_FETCH;
117626 #define TOKEN (yyminor.yy0)
117627 
117628   UNUSED_PARAMETER(yymajor);  /* Silence some compiler warnings */
117629   assert( TOKEN.z[0] );  /* The tokenizer always gives us a token */
117630   sqlite3ErrorMsg(pParse, "near \"%T\": syntax error", &TOKEN);
117631   sqlite3ParserARG_STORE; /* Suppress warning about unused %extra_argument variable */
117632 }
117633 
117634 /*
117635 ** The following is executed when the parser accepts
117636 */
117637 static void yy_accept(
117638   yyParser *yypParser           /* The parser */
117639 ){
117640   sqlite3ParserARG_FETCH;
117641 #ifndef NDEBUG
117642   if( yyTraceFILE ){
117643     fprintf(yyTraceFILE,"%sAccept!\n",yyTracePrompt);
117644   }
117645 #endif
117646   while( yypParser->yyidx>=0 ) yy_pop_parser_stack(yypParser);
117647   /* Here code is inserted which will be executed whenever the
117648   ** parser accepts */
117649   sqlite3ParserARG_STORE; /* Suppress warning about unused %extra_argument variable */
117650 }
117651 
117652 /* The main parser program.
117653 ** The first argument is a pointer to a structure obtained from
117654 ** "sqlite3ParserAlloc" which describes the current state of the parser.
117655 ** The second argument is the major token number.  The third is
117656 ** the minor token.  The fourth optional argument is whatever the
117657 ** user wants (and specified in the grammar) and is available for
117658 ** use by the action routines.
117659 **
117660 ** Inputs:
117661 ** <ul>
117662 ** <li> A pointer to the parser (an opaque structure.)
117663 ** <li> The major token number.
117664 ** <li> The minor token number.
117665 ** <li> An option argument of a grammar-specified type.
117666 ** </ul>
117667 **
117668 ** Outputs:
117669 ** None.
117670 */
117671 SQLITE_PRIVATE void sqlite3Parser(
117672   void *yyp,                   /* The parser */
117673   int yymajor,                 /* The major token code number */
117674   sqlite3ParserTOKENTYPE yyminor       /* The value for the token */
117675   sqlite3ParserARG_PDECL               /* Optional %extra_argument parameter */
117676 ){
117677   YYMINORTYPE yyminorunion;
117678   int yyact;            /* The parser action. */
117679 #if !defined(YYERRORSYMBOL) && !defined(YYNOERRORRECOVERY)
117680   int yyendofinput;     /* True if we are at the end of input */
117681 #endif
117682 #ifdef YYERRORSYMBOL
117683   int yyerrorhit = 0;   /* True if yymajor has invoked an error */
117684 #endif
117685   yyParser *yypParser;  /* The parser */
117686 
117687   /* (re)initialize the parser, if necessary */
117688   yypParser = (yyParser*)yyp;
117689   if( yypParser->yyidx<0 ){
117690 #if YYSTACKDEPTH<=0
117691     if( yypParser->yystksz <=0 ){
117692       /*memset(&yyminorunion, 0, sizeof(yyminorunion));*/
117693       yyminorunion = yyzerominor;
117694       yyStackOverflow(yypParser, &yyminorunion);
117695       return;
117696     }
117697 #endif
117698     yypParser->yyidx = 0;
117699     yypParser->yyerrcnt = -1;
117700     yypParser->yystack[0].stateno = 0;
117701     yypParser->yystack[0].major = 0;
117702   }
117703   yyminorunion.yy0 = yyminor;
117704 #if !defined(YYERRORSYMBOL) && !defined(YYNOERRORRECOVERY)
117705   yyendofinput = (yymajor==0);
117706 #endif
117707   sqlite3ParserARG_STORE;
117708 
117709 #ifndef NDEBUG
117710   if( yyTraceFILE ){
117711     fprintf(yyTraceFILE,"%sInput %s\n",yyTracePrompt,yyTokenName[yymajor]);
117712   }
117713 #endif
117714 
117715   do{
117716     yyact = yy_find_shift_action(yypParser,(YYCODETYPE)yymajor);
117717     if( yyact<YYNSTATE ){
117718       yy_shift(yypParser,yyact,yymajor,&yyminorunion);
117719       yypParser->yyerrcnt--;
117720       yymajor = YYNOCODE;
117721     }else if( yyact < YYNSTATE + YYNRULE ){
117722       yy_reduce(yypParser,yyact-YYNSTATE);
117723     }else{
117724       assert( yyact == YY_ERROR_ACTION );
117725 #ifdef YYERRORSYMBOL
117726       int yymx;
117727 #endif
117728 #ifndef NDEBUG
117729       if( yyTraceFILE ){
117730         fprintf(yyTraceFILE,"%sSyntax Error!\n",yyTracePrompt);
117731       }
117732 #endif
117733 #ifdef YYERRORSYMBOL
117734       /* A syntax error has occurred.
117735       ** The response to an error depends upon whether or not the
117736       ** grammar defines an error token "ERROR".  
117737       **
117738       ** This is what we do if the grammar does define ERROR:
117739       **
117740       **  * Call the %syntax_error function.
117741       **
117742       **  * Begin popping the stack until we enter a state where
117743       **    it is legal to shift the error symbol, then shift
117744       **    the error symbol.
117745       **
117746       **  * Set the error count to three.
117747       **
117748       **  * Begin accepting and shifting new tokens.  No new error
117749       **    processing will occur until three tokens have been
117750       **    shifted successfully.
117751       **
117752       */
117753       if( yypParser->yyerrcnt<0 ){
117754         yy_syntax_error(yypParser,yymajor,yyminorunion);
117755       }
117756       yymx = yypParser->yystack[yypParser->yyidx].major;
117757       if( yymx==YYERRORSYMBOL || yyerrorhit ){
117758 #ifndef NDEBUG
117759         if( yyTraceFILE ){
117760           fprintf(yyTraceFILE,"%sDiscard input token %s\n",
117761              yyTracePrompt,yyTokenName[yymajor]);
117762         }
117763 #endif
117764         yy_destructor(yypParser, (YYCODETYPE)yymajor,&yyminorunion);
117765         yymajor = YYNOCODE;
117766       }else{
117767          while(
117768           yypParser->yyidx >= 0 &&
117769           yymx != YYERRORSYMBOL &&
117770           (yyact = yy_find_reduce_action(
117771                         yypParser->yystack[yypParser->yyidx].stateno,
117772                         YYERRORSYMBOL)) >= YYNSTATE
117773         ){
117774           yy_pop_parser_stack(yypParser);
117775         }
117776         if( yypParser->yyidx < 0 || yymajor==0 ){
117777           yy_destructor(yypParser,(YYCODETYPE)yymajor,&yyminorunion);
117778           yy_parse_failed(yypParser);
117779           yymajor = YYNOCODE;
117780         }else if( yymx!=YYERRORSYMBOL ){
117781           YYMINORTYPE u2;
117782           u2.YYERRSYMDT = 0;
117783           yy_shift(yypParser,yyact,YYERRORSYMBOL,&u2);
117784         }
117785       }
117786       yypParser->yyerrcnt = 3;
117787       yyerrorhit = 1;
117788 #elif defined(YYNOERRORRECOVERY)
117789       /* If the YYNOERRORRECOVERY macro is defined, then do not attempt to
117790       ** do any kind of error recovery.  Instead, simply invoke the syntax
117791       ** error routine and continue going as if nothing had happened.
117792       **
117793       ** Applications can set this macro (for example inside %include) if
117794       ** they intend to abandon the parse upon the first syntax error seen.
117795       */
117796       yy_syntax_error(yypParser,yymajor,yyminorunion);
117797       yy_destructor(yypParser,(YYCODETYPE)yymajor,&yyminorunion);
117798       yymajor = YYNOCODE;
117799       
117800 #else  /* YYERRORSYMBOL is not defined */
117801       /* This is what we do if the grammar does not define ERROR:
117802       **
117803       **  * Report an error message, and throw away the input token.
117804       **
117805       **  * If the input token is $, then fail the parse.
117806       **
117807       ** As before, subsequent error messages are suppressed until
117808       ** three input tokens have been successfully shifted.
117809       */
117810       if( yypParser->yyerrcnt<=0 ){
117811         yy_syntax_error(yypParser,yymajor,yyminorunion);
117812       }
117813       yypParser->yyerrcnt = 3;
117814       yy_destructor(yypParser,(YYCODETYPE)yymajor,&yyminorunion);
117815       if( yyendofinput ){
117816         yy_parse_failed(yypParser);
117817       }
117818       yymajor = YYNOCODE;
117819 #endif
117820     }
117821   }while( yymajor!=YYNOCODE && yypParser->yyidx>=0 );
117822   return;
117823 }
117824 
117825 /************** End of parse.c ***********************************************/
117826 /************** Begin file tokenize.c ****************************************/
117827 /*
117828 ** 2001 September 15
117829 **
117830 ** The author disclaims copyright to this source code.  In place of
117831 ** a legal notice, here is a blessing:
117832 **
117833 **    May you do good and not evil.
117834 **    May you find forgiveness for yourself and forgive others.
117835 **    May you share freely, never taking more than you give.
117836 **
117837 *************************************************************************
117838 ** An tokenizer for SQL
117839 **
117840 ** This file contains C code that splits an SQL input string up into
117841 ** individual tokens and sends those tokens one-by-one over to the
117842 ** parser for analysis.
117843 */
117844 /* #include <stdlib.h> */
117845 
117846 /*
117847 ** The charMap() macro maps alphabetic characters into their
117848 ** lower-case ASCII equivalent.  On ASCII machines, this is just
117849 ** an upper-to-lower case map.  On EBCDIC machines we also need
117850 ** to adjust the encoding.  Only alphabetic characters and underscores
117851 ** need to be translated.
117852 */
117853 #ifdef SQLITE_ASCII
117854 # define charMap(X) sqlite3UpperToLower[(unsigned char)X]
117855 #endif
117856 #ifdef SQLITE_EBCDIC
117857 # define charMap(X) ebcdicToAscii[(unsigned char)X]
117858 const unsigned char ebcdicToAscii[] = {
117859 /* 0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F */
117860    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 0x */
117861    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 1x */
117862    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 2x */
117863    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 3x */
117864    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 4x */
117865    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 5x */
117866    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0, 95,  0,  0,  /* 6x */
117867    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 7x */
117868    0, 97, 98, 99,100,101,102,103,104,105,  0,  0,  0,  0,  0,  0,  /* 8x */
117869    0,106,107,108,109,110,111,112,113,114,  0,  0,  0,  0,  0,  0,  /* 9x */
117870    0,  0,115,116,117,118,119,120,121,122,  0,  0,  0,  0,  0,  0,  /* Ax */
117871    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* Bx */
117872    0, 97, 98, 99,100,101,102,103,104,105,  0,  0,  0,  0,  0,  0,  /* Cx */
117873    0,106,107,108,109,110,111,112,113,114,  0,  0,  0,  0,  0,  0,  /* Dx */
117874    0,  0,115,116,117,118,119,120,121,122,  0,  0,  0,  0,  0,  0,  /* Ex */
117875    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* Fx */
117876 };
117877 #endif
117878 
117879 /*
117880 ** The sqlite3KeywordCode function looks up an identifier to determine if
117881 ** it is a keyword.  If it is a keyword, the token code of that keyword is 
117882 ** returned.  If the input is not a keyword, TK_ID is returned.
117883 **
117884 ** The implementation of this routine was generated by a program,
117885 ** mkkeywordhash.h, located in the tool subdirectory of the distribution.
117886 ** The output of the mkkeywordhash.c program is written into a file
117887 ** named keywordhash.h and then included into this source file by
117888 ** the #include below.
117889 */
117890 /************** Include keywordhash.h in the middle of tokenize.c ************/
117891 /************** Begin file keywordhash.h *************************************/
117892 /***** This file contains automatically generated code ******
117893 **
117894 ** The code in this file has been automatically generated by
117895 **
117896 **   sqlite/tool/mkkeywordhash.c
117897 **
117898 ** The code in this file implements a function that determines whether
117899 ** or not a given identifier is really an SQL keyword.  The same thing
117900 ** might be implemented more directly using a hand-written hash table.
117901 ** But by using this automatically generated code, the size of the code
117902 ** is substantially reduced.  This is important for embedded applications
117903 ** on platforms with limited memory.
117904 */
117905 /* Hash score: 177 */
117906 static int keywordCode(const char *z, int n){
117907   /* zText[] encodes 819 bytes of keywords in 545 bytes */
117908   /*   REINDEXEDESCAPEACHECKEYBEFOREIGNOREGEXPLAINSTEADDATABASELECT       */
117909   /*   ABLEFTHENDEFERRABLELSEXCEPTRANSACTIONATURALTERAISEXCLUSIVE         */
117910   /*   XISTSAVEPOINTERSECTRIGGEREFERENCESCONSTRAINTOFFSETEMPORARY         */
117911   /*   UNIQUERYWITHOUTERELEASEATTACHAVINGROUPDATEBEGINNERENAMEBETWEEN     */
117912   /*   OTNULLIKECASCADELETECASECOLLATECREATECURRENT_DATEDETACH            */
117913   /*   IMMEDIATEJOINSERTMATCHPLANALYZEPRAGMABORTVALUESVIRTUALIMITWHEN     */
117914   /*   WHEREPLACEAFTERESTRICTANDEFAULTAUTOINCREMENTCASTCOLUMNCOMMIT       */
117915   /*   CONFLICTCROSSCURRENT_TIMESTAMPRIMARYDEFERREDISTINCTDROPFAIL        */
117916   /*   FROMFULLGLOBYIFISNULLORDERIGHTROLLBACKROWUNIONUSINGVACUUMVIEW      */
117917   /*   INITIALLY                                                          */
117918   static const char zText[544] = {
117919     'R','E','I','N','D','E','X','E','D','E','S','C','A','P','E','A','C','H',
117920     'E','C','K','E','Y','B','E','F','O','R','E','I','G','N','O','R','E','G',
117921     'E','X','P','L','A','I','N','S','T','E','A','D','D','A','T','A','B','A',
117922     'S','E','L','E','C','T','A','B','L','E','F','T','H','E','N','D','E','F',
117923     'E','R','R','A','B','L','E','L','S','E','X','C','E','P','T','R','A','N',
117924     'S','A','C','T','I','O','N','A','T','U','R','A','L','T','E','R','A','I',
117925     'S','E','X','C','L','U','S','I','V','E','X','I','S','T','S','A','V','E',
117926     'P','O','I','N','T','E','R','S','E','C','T','R','I','G','G','E','R','E',
117927     'F','E','R','E','N','C','E','S','C','O','N','S','T','R','A','I','N','T',
117928     'O','F','F','S','E','T','E','M','P','O','R','A','R','Y','U','N','I','Q',
117929     'U','E','R','Y','W','I','T','H','O','U','T','E','R','E','L','E','A','S',
117930     'E','A','T','T','A','C','H','A','V','I','N','G','R','O','U','P','D','A',
117931     'T','E','B','E','G','I','N','N','E','R','E','N','A','M','E','B','E','T',
117932     'W','E','E','N','O','T','N','U','L','L','I','K','E','C','A','S','C','A',
117933     'D','E','L','E','T','E','C','A','S','E','C','O','L','L','A','T','E','C',
117934     'R','E','A','T','E','C','U','R','R','E','N','T','_','D','A','T','E','D',
117935     'E','T','A','C','H','I','M','M','E','D','I','A','T','E','J','O','I','N',
117936     'S','E','R','T','M','A','T','C','H','P','L','A','N','A','L','Y','Z','E',
117937     'P','R','A','G','M','A','B','O','R','T','V','A','L','U','E','S','V','I',
117938     'R','T','U','A','L','I','M','I','T','W','H','E','N','W','H','E','R','E',
117939     'P','L','A','C','E','A','F','T','E','R','E','S','T','R','I','C','T','A',
117940     'N','D','E','F','A','U','L','T','A','U','T','O','I','N','C','R','E','M',
117941     'E','N','T','C','A','S','T','C','O','L','U','M','N','C','O','M','M','I',
117942     'T','C','O','N','F','L','I','C','T','C','R','O','S','S','C','U','R','R',
117943     'E','N','T','_','T','I','M','E','S','T','A','M','P','R','I','M','A','R',
117944     'Y','D','E','F','E','R','R','E','D','I','S','T','I','N','C','T','D','R',
117945     'O','P','F','A','I','L','F','R','O','M','F','U','L','L','G','L','O','B',
117946     'Y','I','F','I','S','N','U','L','L','O','R','D','E','R','I','G','H','T',
117947     'R','O','L','L','B','A','C','K','R','O','W','U','N','I','O','N','U','S',
117948     'I','N','G','V','A','C','U','U','M','V','I','E','W','I','N','I','T','I',
117949     'A','L','L','Y',
117950   };
117951   static const unsigned char aHash[127] = {
117952       75, 104, 115,  73,   0,  45,   0,   0,  81,   0,  76,   0,   0,
117953       42,  12,  77,  15,   0, 114,  84,  53, 111,   0,  19,   0,   0,
117954      119,   0, 117,  88,   0,  22,  92,   0,   9,   0,   0,  69,  70,
117955        0,  68,   6,   0,  48,  89, 101,   0, 116, 100,   0,   0,  44,
117956        0, 102,  24,   0,  17,   0, 120,  52,  23,   0,   5, 109,  25,
117957       95,   0,   0, 122, 105,  59, 121,  56,  28,  54,   0,  90,   0,
117958       99,  26,   0,  98,   0,   0,   0,  94,  91,  96,  87, 108,  14,
117959       39, 107,   0,  80,   0,  18,  86, 110,  32,   0, 118,  79, 112,
117960       61,  46,  83,   0,   0,  93,  40,   0, 113,   0,  36,   0,   0,
117961       29,   0,  85,  62,  63,   0,  20,  60,   0,  55,
117962   };
117963   static const unsigned char aNext[122] = {
117964        0,   0,   0,   0,   4,   0,   0,   0,   0,   0,   0,   0,   0,
117965        0,   2,   0,   0,   0,   0,   0,   0,  13,   0,   0,   0,   0,
117966        0,   7,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
117967        0,   0,   0,   0,  33,   0,  21,   0,   0,   0,   0,   0,   0,
117968       43,   3,  47,   0,   0,   0,   0,  30,   0,  57,   0,  38,   0,
117969        0,   0,   1,  65,   0,   0,  66,   0,  41,   0,   0,   0,   0,
117970        0,   0,  49,  64,   0,   0,   0,  51,  31,   0,  16,  34,  10,
117971        0,   0,   0,   0,   0,   0,   0,  11,  71,  78,   0,   8,   0,
117972      103,  97,   0, 106,   0,  58,   0,  74,  50,  27,  37,  72,  82,
117973        0,  35,  67,   0,   0,
117974   };
117975   static const unsigned char aLen[122] = {
117976        7,   7,   5,   4,   6,   4,   5,   3,   6,   7,   3,   6,   6,
117977        7,   7,   3,   8,   2,   6,   5,   4,   4,   3,  10,   4,   6,
117978       11,   6,   2,   7,   5,   5,   9,   6,   9,   9,   7,  10,  10,
117979        4,   6,   2,   3,   9,   4,   2,   6,   5,   7,   5,   7,   6,
117980        6,   5,   6,   5,   5,   6,   7,   7,   3,   2,   4,   4,   7,
117981        3,   6,   4,   7,   6,  12,   6,   9,   4,   6,   5,   4,   7,
117982        6,   5,   6,   7,   5,   4,   5,   7,   5,   8,   3,   7,  13,
117983        2,   2,   4,   6,   6,   8,   5,  17,  12,   7,   8,   8,   2,
117984        4,   4,   4,   4,   4,   2,   2,   6,   5,   5,   8,   3,   5,
117985        5,   6,   4,   9,   3,
117986   };
117987   static const unsigned short int aOffset[122] = {
117988        0,   2,   2,   8,   9,  14,  16,  20,  23,  25,  25,  29,  33,
117989       36,  41,  46,  48,  53,  54,  59,  62,  65,  67,  69,  78,  81,
117990       86,  91,  95,  96, 101, 105, 109, 117, 122, 128, 136, 142, 152,
117991      159, 162, 162, 165, 167, 167, 171, 176, 179, 184, 188, 192, 199,
117992      204, 209, 212, 218, 221, 225, 231, 237, 237, 237, 240, 243, 247,
117993      248, 252, 258, 262, 269, 275, 287, 293, 302, 304, 310, 315, 317,
117994      324, 329, 334, 340, 346, 351, 355, 358, 365, 369, 377, 379, 386,
117995      388, 390, 399, 403, 409, 415, 423, 428, 428, 444, 451, 458, 459,
117996      466, 470, 474, 478, 482, 485, 487, 489, 495, 499, 504, 512, 515,
117997      520, 525, 531, 535, 540,
117998   };
117999   static const unsigned char aCode[122] = {
118000     TK_REINDEX,    TK_INDEXED,    TK_INDEX,      TK_DESC,       TK_ESCAPE,     
118001     TK_EACH,       TK_CHECK,      TK_KEY,        TK_BEFORE,     TK_FOREIGN,    
118002     TK_FOR,        TK_IGNORE,     TK_LIKE_KW,    TK_EXPLAIN,    TK_INSTEAD,    
118003     TK_ADD,        TK_DATABASE,   TK_AS,         TK_SELECT,     TK_TABLE,      
118004     TK_JOIN_KW,    TK_THEN,       TK_END,        TK_DEFERRABLE, TK_ELSE,       
118005     TK_EXCEPT,     TK_TRANSACTION,TK_ACTION,     TK_ON,         TK_JOIN_KW,    
118006     TK_ALTER,      TK_RAISE,      TK_EXCLUSIVE,  TK_EXISTS,     TK_SAVEPOINT,  
118007     TK_INTERSECT,  TK_TRIGGER,    TK_REFERENCES, TK_CONSTRAINT, TK_INTO,       
118008     TK_OFFSET,     TK_OF,         TK_SET,        TK_TEMP,       TK_TEMP,       
118009     TK_OR,         TK_UNIQUE,     TK_QUERY,      TK_WITHOUT,    TK_JOIN_KW,    
118010     TK_RELEASE,    TK_ATTACH,     TK_HAVING,     TK_GROUP,      TK_UPDATE,     
118011     TK_BEGIN,      TK_JOIN_KW,    TK_RENAME,     TK_BETWEEN,    TK_NOTNULL,    
118012     TK_NOT,        TK_NO,         TK_NULL,       TK_LIKE_KW,    TK_CASCADE,    
118013     TK_ASC,        TK_DELETE,     TK_CASE,       TK_COLLATE,    TK_CREATE,     
118014     TK_CTIME_KW,   TK_DETACH,     TK_IMMEDIATE,  TK_JOIN,       TK_INSERT,     
118015     TK_MATCH,      TK_PLAN,       TK_ANALYZE,    TK_PRAGMA,     TK_ABORT,      
118016     TK_VALUES,     TK_VIRTUAL,    TK_LIMIT,      TK_WHEN,       TK_WHERE,      
118017     TK_REPLACE,    TK_AFTER,      TK_RESTRICT,   TK_AND,        TK_DEFAULT,    
118018     TK_AUTOINCR,   TK_TO,         TK_IN,         TK_CAST,       TK_COLUMNKW,   
118019     TK_COMMIT,     TK_CONFLICT,   TK_JOIN_KW,    TK_CTIME_KW,   TK_CTIME_KW,   
118020     TK_PRIMARY,    TK_DEFERRED,   TK_DISTINCT,   TK_IS,         TK_DROP,       
118021     TK_FAIL,       TK_FROM,       TK_JOIN_KW,    TK_LIKE_KW,    TK_BY,         
118022     TK_IF,         TK_ISNULL,     TK_ORDER,      TK_JOIN_KW,    TK_ROLLBACK,   
118023     TK_ROW,        TK_UNION,      TK_USING,      TK_VACUUM,     TK_VIEW,       
118024     TK_INITIALLY,  TK_ALL,        
118025   };
118026   int h, i;
118027   if( n<2 ) return TK_ID;
118028   h = ((charMap(z[0])*4) ^
118029       (charMap(z[n-1])*3) ^
118030       n) % 127;
118031   for(i=((int)aHash[h])-1; i>=0; i=((int)aNext[i])-1){
118032     if( aLen[i]==n && sqlite3StrNICmp(&zText[aOffset[i]],z,n)==0 ){
118033       testcase( i==0 ); /* REINDEX */
118034       testcase( i==1 ); /* INDEXED */
118035       testcase( i==2 ); /* INDEX */
118036       testcase( i==3 ); /* DESC */
118037       testcase( i==4 ); /* ESCAPE */
118038       testcase( i==5 ); /* EACH */
118039       testcase( i==6 ); /* CHECK */
118040       testcase( i==7 ); /* KEY */
118041       testcase( i==8 ); /* BEFORE */
118042       testcase( i==9 ); /* FOREIGN */
118043       testcase( i==10 ); /* FOR */
118044       testcase( i==11 ); /* IGNORE */
118045       testcase( i==12 ); /* REGEXP */
118046       testcase( i==13 ); /* EXPLAIN */
118047       testcase( i==14 ); /* INSTEAD */
118048       testcase( i==15 ); /* ADD */
118049       testcase( i==16 ); /* DATABASE */
118050       testcase( i==17 ); /* AS */
118051       testcase( i==18 ); /* SELECT */
118052       testcase( i==19 ); /* TABLE */
118053       testcase( i==20 ); /* LEFT */
118054       testcase( i==21 ); /* THEN */
118055       testcase( i==22 ); /* END */
118056       testcase( i==23 ); /* DEFERRABLE */
118057       testcase( i==24 ); /* ELSE */
118058       testcase( i==25 ); /* EXCEPT */
118059       testcase( i==26 ); /* TRANSACTION */
118060       testcase( i==27 ); /* ACTION */
118061       testcase( i==28 ); /* ON */
118062       testcase( i==29 ); /* NATURAL */
118063       testcase( i==30 ); /* ALTER */
118064       testcase( i==31 ); /* RAISE */
118065       testcase( i==32 ); /* EXCLUSIVE */
118066       testcase( i==33 ); /* EXISTS */
118067       testcase( i==34 ); /* SAVEPOINT */
118068       testcase( i==35 ); /* INTERSECT */
118069       testcase( i==36 ); /* TRIGGER */
118070       testcase( i==37 ); /* REFERENCES */
118071       testcase( i==38 ); /* CONSTRAINT */
118072       testcase( i==39 ); /* INTO */
118073       testcase( i==40 ); /* OFFSET */
118074       testcase( i==41 ); /* OF */
118075       testcase( i==42 ); /* SET */
118076       testcase( i==43 ); /* TEMPORARY */
118077       testcase( i==44 ); /* TEMP */
118078       testcase( i==45 ); /* OR */
118079       testcase( i==46 ); /* UNIQUE */
118080       testcase( i==47 ); /* QUERY */
118081       testcase( i==48 ); /* WITHOUT */
118082       testcase( i==49 ); /* OUTER */
118083       testcase( i==50 ); /* RELEASE */
118084       testcase( i==51 ); /* ATTACH */
118085       testcase( i==52 ); /* HAVING */
118086       testcase( i==53 ); /* GROUP */
118087       testcase( i==54 ); /* UPDATE */
118088       testcase( i==55 ); /* BEGIN */
118089       testcase( i==56 ); /* INNER */
118090       testcase( i==57 ); /* RENAME */
118091       testcase( i==58 ); /* BETWEEN */
118092       testcase( i==59 ); /* NOTNULL */
118093       testcase( i==60 ); /* NOT */
118094       testcase( i==61 ); /* NO */
118095       testcase( i==62 ); /* NULL */
118096       testcase( i==63 ); /* LIKE */
118097       testcase( i==64 ); /* CASCADE */
118098       testcase( i==65 ); /* ASC */
118099       testcase( i==66 ); /* DELETE */
118100       testcase( i==67 ); /* CASE */
118101       testcase( i==68 ); /* COLLATE */
118102       testcase( i==69 ); /* CREATE */
118103       testcase( i==70 ); /* CURRENT_DATE */
118104       testcase( i==71 ); /* DETACH */
118105       testcase( i==72 ); /* IMMEDIATE */
118106       testcase( i==73 ); /* JOIN */
118107       testcase( i==74 ); /* INSERT */
118108       testcase( i==75 ); /* MATCH */
118109       testcase( i==76 ); /* PLAN */
118110       testcase( i==77 ); /* ANALYZE */
118111       testcase( i==78 ); /* PRAGMA */
118112       testcase( i==79 ); /* ABORT */
118113       testcase( i==80 ); /* VALUES */
118114       testcase( i==81 ); /* VIRTUAL */
118115       testcase( i==82 ); /* LIMIT */
118116       testcase( i==83 ); /* WHEN */
118117       testcase( i==84 ); /* WHERE */
118118       testcase( i==85 ); /* REPLACE */
118119       testcase( i==86 ); /* AFTER */
118120       testcase( i==87 ); /* RESTRICT */
118121       testcase( i==88 ); /* AND */
118122       testcase( i==89 ); /* DEFAULT */
118123       testcase( i==90 ); /* AUTOINCREMENT */
118124       testcase( i==91 ); /* TO */
118125       testcase( i==92 ); /* IN */
118126       testcase( i==93 ); /* CAST */
118127       testcase( i==94 ); /* COLUMN */
118128       testcase( i==95 ); /* COMMIT */
118129       testcase( i==96 ); /* CONFLICT */
118130       testcase( i==97 ); /* CROSS */
118131       testcase( i==98 ); /* CURRENT_TIMESTAMP */
118132       testcase( i==99 ); /* CURRENT_TIME */
118133       testcase( i==100 ); /* PRIMARY */
118134       testcase( i==101 ); /* DEFERRED */
118135       testcase( i==102 ); /* DISTINCT */
118136       testcase( i==103 ); /* IS */
118137       testcase( i==104 ); /* DROP */
118138       testcase( i==105 ); /* FAIL */
118139       testcase( i==106 ); /* FROM */
118140       testcase( i==107 ); /* FULL */
118141       testcase( i==108 ); /* GLOB */
118142       testcase( i==109 ); /* BY */
118143       testcase( i==110 ); /* IF */
118144       testcase( i==111 ); /* ISNULL */
118145       testcase( i==112 ); /* ORDER */
118146       testcase( i==113 ); /* RIGHT */
118147       testcase( i==114 ); /* ROLLBACK */
118148       testcase( i==115 ); /* ROW */
118149       testcase( i==116 ); /* UNION */
118150       testcase( i==117 ); /* USING */
118151       testcase( i==118 ); /* VACUUM */
118152       testcase( i==119 ); /* VIEW */
118153       testcase( i==120 ); /* INITIALLY */
118154       testcase( i==121 ); /* ALL */
118155       return aCode[i];
118156     }
118157   }
118158   return TK_ID;
118159 }
118160 SQLITE_PRIVATE int sqlite3KeywordCode(const unsigned char *z, int n){
118161   return keywordCode((char*)z, n);
118162 }
118163 #define SQLITE_N_KEYWORD 122
118164 
118165 /************** End of keywordhash.h *****************************************/
118166 /************** Continuing where we left off in tokenize.c *******************/
118167 
118168 
118169 /*
118170 ** If X is a character that can be used in an identifier then
118171 ** IdChar(X) will be true.  Otherwise it is false.
118172 **
118173 ** For ASCII, any character with the high-order bit set is
118174 ** allowed in an identifier.  For 7-bit characters, 
118175 ** sqlite3IsIdChar[X] must be 1.
118176 **
118177 ** For EBCDIC, the rules are more complex but have the same
118178 ** end result.
118179 **
118180 ** Ticket #1066.  the SQL standard does not allow '$' in the
118181 ** middle of identfiers.  But many SQL implementations do. 
118182 ** SQLite will allow '$' in identifiers for compatibility.
118183 ** But the feature is undocumented.
118184 */
118185 #ifdef SQLITE_ASCII
118186 #define IdChar(C)  ((sqlite3CtypeMap[(unsigned char)C]&0x46)!=0)
118187 #endif
118188 #ifdef SQLITE_EBCDIC
118189 SQLITE_PRIVATE const char sqlite3IsEbcdicIdChar[] = {
118190 /* x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF */
118191     0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0,  /* 4x */
118192     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 0, 0, 0, 0,  /* 5x */
118193     0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 1, 0, 0,  /* 6x */
118194     0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0,  /* 7x */
118195     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 1, 1, 1, 0,  /* 8x */
118196     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 1, 0, 1, 0,  /* 9x */
118197     1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0,  /* Ax */
118198     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,  /* Bx */
118199     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 1,  /* Cx */
118200     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 1,  /* Dx */
118201     0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 1,  /* Ex */
118202     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0,  /* Fx */
118203 };
118204 #define IdChar(C)  (((c=C)>=0x42 && sqlite3IsEbcdicIdChar[c-0x40]))
118205 #endif
118206 
118207 
118208 /*
118209 ** Return the length of the token that begins at z[0]. 
118210 ** Store the token type in *tokenType before returning.
118211 */
118212 SQLITE_PRIVATE int sqlite3GetToken(const unsigned char *z, int *tokenType){
118213   int i, c;
118214   switch( *z ){
118215     case ' ': case '\t': case '\n': case '\f': case '\r': {
118216       testcase( z[0]==' ' );
118217       testcase( z[0]=='\t' );
118218       testcase( z[0]=='\n' );
118219       testcase( z[0]=='\f' );
118220       testcase( z[0]=='\r' );
118221       for(i=1; sqlite3Isspace(z[i]); i++){}
118222       *tokenType = TK_SPACE;
118223       return i;
118224     }
118225     case '-': {
118226       if( z[1]=='-' ){
118227         for(i=2; (c=z[i])!=0 && c!='\n'; i++){}
118228         *tokenType = TK_SPACE;   /* IMP: R-22934-25134 */
118229         return i;
118230       }
118231       *tokenType = TK_MINUS;
118232       return 1;
118233     }
118234     case '(': {
118235       *tokenType = TK_LP;
118236       return 1;
118237     }
118238     case ')': {
118239       *tokenType = TK_RP;
118240       return 1;
118241     }
118242     case ';': {
118243       *tokenType = TK_SEMI;
118244       return 1;
118245     }
118246     case '+': {
118247       *tokenType = TK_PLUS;
118248       return 1;
118249     }
118250     case '*': {
118251       *tokenType = TK_STAR;
118252       return 1;
118253     }
118254     case '/': {
118255       if( z[1]!='*' || z[2]==0 ){
118256         *tokenType = TK_SLASH;
118257         return 1;
118258       }
118259       for(i=3, c=z[2]; (c!='*' || z[i]!='/') && (c=z[i])!=0; i++){}
118260       if( c ) i++;
118261       *tokenType = TK_SPACE;   /* IMP: R-22934-25134 */
118262       return i;
118263     }
118264     case '%': {
118265       *tokenType = TK_REM;
118266       return 1;
118267     }
118268     case '=': {
118269       *tokenType = TK_EQ;
118270       return 1 + (z[1]=='=');
118271     }
118272     case '<': {
118273       if( (c=z[1])=='=' ){
118274         *tokenType = TK_LE;
118275         return 2;
118276       }else if( c=='>' ){
118277         *tokenType = TK_NE;
118278         return 2;
118279       }else if( c=='<' ){
118280         *tokenType = TK_LSHIFT;
118281         return 2;
118282       }else{
118283         *tokenType = TK_LT;
118284         return 1;
118285       }
118286     }
118287     case '>': {
118288       if( (c=z[1])=='=' ){
118289         *tokenType = TK_GE;
118290         return 2;
118291       }else if( c=='>' ){
118292         *tokenType = TK_RSHIFT;
118293         return 2;
118294       }else{
118295         *tokenType = TK_GT;
118296         return 1;
118297       }
118298     }
118299     case '!': {
118300       if( z[1]!='=' ){
118301         *tokenType = TK_ILLEGAL;
118302         return 2;
118303       }else{
118304         *tokenType = TK_NE;
118305         return 2;
118306       }
118307     }
118308     case '|': {
118309       if( z[1]!='|' ){
118310         *tokenType = TK_BITOR;
118311         return 1;
118312       }else{
118313         *tokenType = TK_CONCAT;
118314         return 2;
118315       }
118316     }
118317     case ',': {
118318       *tokenType = TK_COMMA;
118319       return 1;
118320     }
118321     case '&': {
118322       *tokenType = TK_BITAND;
118323       return 1;
118324     }
118325     case '~': {
118326       *tokenType = TK_BITNOT;
118327       return 1;
118328     }
118329     case '`':
118330     case '\'':
118331     case '"': {
118332       int delim = z[0];
118333       testcase( delim=='`' );
118334       testcase( delim=='\'' );
118335       testcase( delim=='"' );
118336       for(i=1; (c=z[i])!=0; i++){
118337         if( c==delim ){
118338           if( z[i+1]==delim ){
118339             i++;
118340           }else{
118341             break;
118342           }
118343         }
118344       }
118345       if( c=='\'' ){
118346         *tokenType = TK_STRING;
118347         return i+1;
118348       }else if( c!=0 ){
118349         *tokenType = TK_ID;
118350         return i+1;
118351       }else{
118352         *tokenType = TK_ILLEGAL;
118353         return i;
118354       }
118355     }
118356     case '.': {
118357 #ifndef SQLITE_OMIT_FLOATING_POINT
118358       if( !sqlite3Isdigit(z[1]) )
118359 #endif
118360       {
118361         *tokenType = TK_DOT;
118362         return 1;
118363       }
118364       /* If the next character is a digit, this is a floating point
118365       ** number that begins with ".".  Fall thru into the next case */
118366     }
118367     case '0': case '1': case '2': case '3': case '4':
118368     case '5': case '6': case '7': case '8': case '9': {
118369       testcase( z[0]=='0' );  testcase( z[0]=='1' );  testcase( z[0]=='2' );
118370       testcase( z[0]=='3' );  testcase( z[0]=='4' );  testcase( z[0]=='5' );
118371       testcase( z[0]=='6' );  testcase( z[0]=='7' );  testcase( z[0]=='8' );
118372       testcase( z[0]=='9' );
118373       *tokenType = TK_INTEGER;
118374       for(i=0; sqlite3Isdigit(z[i]); i++){}
118375 #ifndef SQLITE_OMIT_FLOATING_POINT
118376       if( z[i]=='.' ){
118377         i++;
118378         while( sqlite3Isdigit(z[i]) ){ i++; }
118379         *tokenType = TK_FLOAT;
118380       }
118381       if( (z[i]=='e' || z[i]=='E') &&
118382            ( sqlite3Isdigit(z[i+1]) 
118383             || ((z[i+1]=='+' || z[i+1]=='-') && sqlite3Isdigit(z[i+2]))
118384            )
118385       ){
118386         i += 2;
118387         while( sqlite3Isdigit(z[i]) ){ i++; }
118388         *tokenType = TK_FLOAT;
118389       }
118390 #endif
118391       while( IdChar(z[i]) ){
118392         *tokenType = TK_ILLEGAL;
118393         i++;
118394       }
118395       return i;
118396     }
118397     case '[': {
118398       for(i=1, c=z[0]; c!=']' && (c=z[i])!=0; i++){}
118399       *tokenType = c==']' ? TK_ID : TK_ILLEGAL;
118400       return i;
118401     }
118402     case '?': {
118403       *tokenType = TK_VARIABLE;
118404       for(i=1; sqlite3Isdigit(z[i]); i++){}
118405       return i;
118406     }
118407     case '#': {
118408       for(i=1; sqlite3Isdigit(z[i]); i++){}
118409       if( i>1 ){
118410         /* Parameters of the form #NNN (where NNN is a number) are used
118411         ** internally by sqlite3NestedParse.  */
118412         *tokenType = TK_REGISTER;
118413         return i;
118414       }
118415       /* Fall through into the next case if the '#' is not followed by
118416       ** a digit. Try to match #AAAA where AAAA is a parameter name. */
118417     }
118418 #ifndef SQLITE_OMIT_TCL_VARIABLE
118419     case '$':
118420 #endif
118421     case '@':  /* For compatibility with MS SQL Server */
118422     case ':': {
118423       int n = 0;
118424       testcase( z[0]=='$' );  testcase( z[0]=='@' );  testcase( z[0]==':' );
118425       *tokenType = TK_VARIABLE;
118426       for(i=1; (c=z[i])!=0; i++){
118427         if( IdChar(c) ){
118428           n++;
118429 #ifndef SQLITE_OMIT_TCL_VARIABLE
118430         }else if( c=='(' && n>0 ){
118431           do{
118432             i++;
118433           }while( (c=z[i])!=0 && !sqlite3Isspace(c) && c!=')' );
118434           if( c==')' ){
118435             i++;
118436           }else{
118437             *tokenType = TK_ILLEGAL;
118438           }
118439           break;
118440         }else if( c==':' && z[i+1]==':' ){
118441           i++;
118442 #endif
118443         }else{
118444           break;
118445         }
118446       }
118447       if( n==0 ) *tokenType = TK_ILLEGAL;
118448       return i;
118449     }
118450 #ifndef SQLITE_OMIT_BLOB_LITERAL
118451     case 'x': case 'X': {
118452       testcase( z[0]=='x' ); testcase( z[0]=='X' );
118453       if( z[1]=='\'' ){
118454         *tokenType = TK_BLOB;
118455         for(i=2; sqlite3Isxdigit(z[i]); i++){}
118456         if( z[i]!='\'' || i%2 ){
118457           *tokenType = TK_ILLEGAL;
118458           while( z[i] && z[i]!='\'' ){ i++; }
118459         }
118460         if( z[i] ) i++;
118461         return i;
118462       }
118463       /* Otherwise fall through to the next case */
118464     }
118465 #endif
118466     default: {
118467       if( !IdChar(*z) ){
118468         break;
118469       }
118470       for(i=1; IdChar(z[i]); i++){}
118471       *tokenType = keywordCode((char*)z, i);
118472       return i;
118473     }
118474   }
118475   *tokenType = TK_ILLEGAL;
118476   return 1;
118477 }
118478 
118479 /*
118480 ** Run the parser on the given SQL string.  The parser structure is
118481 ** passed in.  An SQLITE_ status code is returned.  If an error occurs
118482 ** then an and attempt is made to write an error message into 
118483 ** memory obtained from sqlite3_malloc() and to make *pzErrMsg point to that
118484 ** error message.
118485 */
118486 SQLITE_PRIVATE int sqlite3RunParser(Parse *pParse, const char *zSql, char **pzErrMsg){
118487   int nErr = 0;                   /* Number of errors encountered */
118488   int i;                          /* Loop counter */
118489   void *pEngine;                  /* The LEMON-generated LALR(1) parser */
118490   int tokenType;                  /* type of the next token */
118491   int lastTokenParsed = -1;       /* type of the previous token */
118492   u8 enableLookaside;             /* Saved value of db->lookaside.bEnabled */
118493   sqlite3 *db = pParse->db;       /* The database connection */
118494   int mxSqlLen;                   /* Max length of an SQL string */
118495 
118496 
118497   mxSqlLen = db->aLimit[SQLITE_LIMIT_SQL_LENGTH];
118498   if( db->nVdbeActive==0 ){
118499     db->u1.isInterrupted = 0;
118500   }
118501   pParse->rc = SQLITE_OK;
118502   pParse->zTail = zSql;
118503   i = 0;
118504   assert( pzErrMsg!=0 );
118505   pEngine = sqlite3ParserAlloc((void*(*)(size_t))sqlite3Malloc);
118506   if( pEngine==0 ){
118507     db->mallocFailed = 1;
118508     return SQLITE_NOMEM;
118509   }
118510   assert( pParse->pNewTable==0 );
118511   assert( pParse->pNewTrigger==0 );
118512   assert( pParse->nVar==0 );
118513   assert( pParse->nzVar==0 );
118514   assert( pParse->azVar==0 );
118515   enableLookaside = db->lookaside.bEnabled;
118516   if( db->lookaside.pStart ) db->lookaside.bEnabled = 1;
118517   while( !db->mallocFailed && zSql[i]!=0 ){
118518     assert( i>=0 );
118519     pParse->sLastToken.z = &zSql[i];
118520     pParse->sLastToken.n = sqlite3GetToken((unsigned char*)&zSql[i],&tokenType);
118521     i += pParse->sLastToken.n;
118522     if( i>mxSqlLen ){
118523       pParse->rc = SQLITE_TOOBIG;
118524       break;
118525     }
118526     switch( tokenType ){
118527       case TK_SPACE: {
118528         if( db->u1.isInterrupted ){
118529           sqlite3ErrorMsg(pParse, "interrupt");
118530           pParse->rc = SQLITE_INTERRUPT;
118531           goto abort_parse;
118532         }
118533         break;
118534       }
118535       case TK_ILLEGAL: {
118536         sqlite3DbFree(db, *pzErrMsg);
118537         *pzErrMsg = sqlite3MPrintf(db, "unrecognized token: \"%T\"",
118538                         &pParse->sLastToken);
118539         nErr++;
118540         goto abort_parse;
118541       }
118542       case TK_SEMI: {
118543         pParse->zTail = &zSql[i];
118544         /* Fall thru into the default case */
118545       }
118546       default: {
118547         sqlite3Parser(pEngine, tokenType, pParse->sLastToken, pParse);
118548         lastTokenParsed = tokenType;
118549         if( pParse->rc!=SQLITE_OK ){
118550           goto abort_parse;
118551         }
118552         break;
118553       }
118554     }
118555   }
118556 abort_parse:
118557   if( zSql[i]==0 && nErr==0 && pParse->rc==SQLITE_OK ){
118558     if( lastTokenParsed!=TK_SEMI ){
118559       sqlite3Parser(pEngine, TK_SEMI, pParse->sLastToken, pParse);
118560       pParse->zTail = &zSql[i];
118561     }
118562     sqlite3Parser(pEngine, 0, pParse->sLastToken, pParse);
118563   }
118564 #ifdef YYTRACKMAXSTACKDEPTH
118565   sqlite3StatusSet(SQLITE_STATUS_PARSER_STACK,
118566       sqlite3ParserStackPeak(pEngine)
118567   );
118568 #endif /* YYDEBUG */
118569   sqlite3ParserFree(pEngine, sqlite3_free);
118570   db->lookaside.bEnabled = enableLookaside;
118571   if( db->mallocFailed ){
118572     pParse->rc = SQLITE_NOMEM;
118573   }
118574   if( pParse->rc!=SQLITE_OK && pParse->rc!=SQLITE_DONE && pParse->zErrMsg==0 ){
118575     sqlite3SetString(&pParse->zErrMsg, db, "%s", sqlite3ErrStr(pParse->rc));
118576   }
118577   assert( pzErrMsg!=0 );
118578   if( pParse->zErrMsg ){
118579     *pzErrMsg = pParse->zErrMsg;
118580     sqlite3_log(pParse->rc, "%s", *pzErrMsg);
118581     pParse->zErrMsg = 0;
118582     nErr++;
118583   }
118584   if( pParse->pVdbe && pParse->nErr>0 && pParse->nested==0 ){
118585     sqlite3VdbeDelete(pParse->pVdbe);
118586     pParse->pVdbe = 0;
118587   }
118588 #ifndef SQLITE_OMIT_SHARED_CACHE
118589   if( pParse->nested==0 ){
118590     sqlite3DbFree(db, pParse->aTableLock);
118591     pParse->aTableLock = 0;
118592     pParse->nTableLock = 0;
118593   }
118594 #endif
118595 #ifndef SQLITE_OMIT_VIRTUALTABLE
118596   sqlite3_free(pParse->apVtabLock);
118597 #endif
118598 
118599   if( !IN_DECLARE_VTAB ){
118600     /* If the pParse->declareVtab flag is set, do not delete any table 
118601     ** structure built up in pParse->pNewTable. The calling code (see vtab.c)
118602     ** will take responsibility for freeing the Table structure.
118603     */
118604     sqlite3DeleteTable(db, pParse->pNewTable);
118605   }
118606 
118607   sqlite3DeleteTrigger(db, pParse->pNewTrigger);
118608   for(i=pParse->nzVar-1; i>=0; i--) sqlite3DbFree(db, pParse->azVar[i]);
118609   sqlite3DbFree(db, pParse->azVar);
118610   while( pParse->pAinc ){
118611     AutoincInfo *p = pParse->pAinc;
118612     pParse->pAinc = p->pNext;
118613     sqlite3DbFree(db, p);
118614   }
118615   while( pParse->pZombieTab ){
118616     Table *p = pParse->pZombieTab;
118617     pParse->pZombieTab = p->pNextZombie;
118618     sqlite3DeleteTable(db, p);
118619   }
118620   if( nErr>0 && pParse->rc==SQLITE_OK ){
118621     pParse->rc = SQLITE_ERROR;
118622   }
118623   return nErr;
118624 }
118625 
118626 /************** End of tokenize.c ********************************************/
118627 /************** Begin file complete.c ****************************************/
118628 /*
118629 ** 2001 September 15
118630 **
118631 ** The author disclaims copyright to this source code.  In place of
118632 ** a legal notice, here is a blessing:
118633 **
118634 **    May you do good and not evil.
118635 **    May you find forgiveness for yourself and forgive others.
118636 **    May you share freely, never taking more than you give.
118637 **
118638 *************************************************************************
118639 ** An tokenizer for SQL
118640 **
118641 ** This file contains C code that implements the sqlite3_complete() API.
118642 ** This code used to be part of the tokenizer.c source file.  But by
118643 ** separating it out, the code will be automatically omitted from
118644 ** static links that do not use it.
118645 */
118646 #ifndef SQLITE_OMIT_COMPLETE
118647 
118648 /*
118649 ** This is defined in tokenize.c.  We just have to import the definition.
118650 */
118651 #ifndef SQLITE_AMALGAMATION
118652 #ifdef SQLITE_ASCII
118653 #define IdChar(C)  ((sqlite3CtypeMap[(unsigned char)C]&0x46)!=0)
118654 #endif
118655 #ifdef SQLITE_EBCDIC
118656 SQLITE_PRIVATE const char sqlite3IsEbcdicIdChar[];
118657 #define IdChar(C)  (((c=C)>=0x42 && sqlite3IsEbcdicIdChar[c-0x40]))
118658 #endif
118659 #endif /* SQLITE_AMALGAMATION */
118660 
118661 
118662 /*
118663 ** Token types used by the sqlite3_complete() routine.  See the header
118664 ** comments on that procedure for additional information.
118665 */
118666 #define tkSEMI    0
118667 #define tkWS      1
118668 #define tkOTHER   2
118669 #ifndef SQLITE_OMIT_TRIGGER
118670 #define tkEXPLAIN 3
118671 #define tkCREATE  4
118672 #define tkTEMP    5
118673 #define tkTRIGGER 6
118674 #define tkEND     7
118675 #endif
118676 
118677 /*
118678 ** Return TRUE if the given SQL string ends in a semicolon.
118679 **
118680 ** Special handling is require for CREATE TRIGGER statements.
118681 ** Whenever the CREATE TRIGGER keywords are seen, the statement
118682 ** must end with ";END;".
118683 **
118684 ** This implementation uses a state machine with 8 states:
118685 **
118686 **   (0) INVALID   We have not yet seen a non-whitespace character.
118687 **
118688 **   (1) START     At the beginning or end of an SQL statement.  This routine
118689 **                 returns 1 if it ends in the START state and 0 if it ends
118690 **                 in any other state.
118691 **
118692 **   (2) NORMAL    We are in the middle of statement which ends with a single
118693 **                 semicolon.
118694 **
118695 **   (3) EXPLAIN   The keyword EXPLAIN has been seen at the beginning of 
118696 **                 a statement.
118697 **
118698 **   (4) CREATE    The keyword CREATE has been seen at the beginning of a
118699 **                 statement, possibly preceeded by EXPLAIN and/or followed by
118700 **                 TEMP or TEMPORARY
118701 **
118702 **   (5) TRIGGER   We are in the middle of a trigger definition that must be
118703 **                 ended by a semicolon, the keyword END, and another semicolon.
118704 **
118705 **   (6) SEMI      We've seen the first semicolon in the ";END;" that occurs at
118706 **                 the end of a trigger definition.
118707 **
118708 **   (7) END       We've seen the ";END" of the ";END;" that occurs at the end
118709 **                 of a trigger difinition.
118710 **
118711 ** Transitions between states above are determined by tokens extracted
118712 ** from the input.  The following tokens are significant:
118713 **
118714 **   (0) tkSEMI      A semicolon.
118715 **   (1) tkWS        Whitespace.
118716 **   (2) tkOTHER     Any other SQL token.
118717 **   (3) tkEXPLAIN   The "explain" keyword.
118718 **   (4) tkCREATE    The "create" keyword.
118719 **   (5) tkTEMP      The "temp" or "temporary" keyword.
118720 **   (6) tkTRIGGER   The "trigger" keyword.
118721 **   (7) tkEND       The "end" keyword.
118722 **
118723 ** Whitespace never causes a state transition and is always ignored.
118724 ** This means that a SQL string of all whitespace is invalid.
118725 **
118726 ** If we compile with SQLITE_OMIT_TRIGGER, all of the computation needed
118727 ** to recognize the end of a trigger can be omitted.  All we have to do
118728 ** is look for a semicolon that is not part of an string or comment.
118729 */
118730 SQLITE_API int sqlite3_complete(const char *zSql){
118731   u8 state = 0;   /* Current state, using numbers defined in header comment */
118732   u8 token;       /* Value of the next token */
118733 
118734 #ifndef SQLITE_OMIT_TRIGGER
118735   /* A complex statement machine used to detect the end of a CREATE TRIGGER
118736   ** statement.  This is the normal case.
118737   */
118738   static const u8 trans[8][8] = {
118739                      /* Token:                                                */
118740      /* State:       **  SEMI  WS  OTHER  EXPLAIN  CREATE  TEMP  TRIGGER  END */
118741      /* 0 INVALID: */ {    1,  0,     2,       3,      4,    2,       2,   2, },
118742      /* 1   START: */ {    1,  1,     2,       3,      4,    2,       2,   2, },
118743      /* 2  NORMAL: */ {    1,  2,     2,       2,      2,    2,       2,   2, },
118744      /* 3 EXPLAIN: */ {    1,  3,     3,       2,      4,    2,       2,   2, },
118745      /* 4  CREATE: */ {    1,  4,     2,       2,      2,    4,       5,   2, },
118746      /* 5 TRIGGER: */ {    6,  5,     5,       5,      5,    5,       5,   5, },
118747      /* 6    SEMI: */ {    6,  6,     5,       5,      5,    5,       5,   7, },
118748      /* 7     END: */ {    1,  7,     5,       5,      5,    5,       5,   5, },
118749   };
118750 #else
118751   /* If triggers are not supported by this compile then the statement machine
118752   ** used to detect the end of a statement is much simplier
118753   */
118754   static const u8 trans[3][3] = {
118755                      /* Token:           */
118756      /* State:       **  SEMI  WS  OTHER */
118757      /* 0 INVALID: */ {    1,  0,     2, },
118758      /* 1   START: */ {    1,  1,     2, },
118759      /* 2  NORMAL: */ {    1,  2,     2, },
118760   };
118761 #endif /* SQLITE_OMIT_TRIGGER */
118762 
118763   while( *zSql ){
118764     switch( *zSql ){
118765       case ';': {  /* A semicolon */
118766         token = tkSEMI;
118767         break;
118768       }
118769       case ' ':
118770       case '\r':
118771       case '\t':
118772       case '\n':
118773       case '\f': {  /* White space is ignored */
118774         token = tkWS;
118775         break;
118776       }
118777       case '/': {   /* C-style comments */
118778         if( zSql[1]!='*' ){
118779           token = tkOTHER;
118780           break;
118781         }
118782         zSql += 2;
118783         while( zSql[0] && (zSql[0]!='*' || zSql[1]!='/') ){ zSql++; }
118784         if( zSql[0]==0 ) return 0;
118785         zSql++;
118786         token = tkWS;
118787         break;
118788       }
118789       case '-': {   /* SQL-style comments from "--" to end of line */
118790         if( zSql[1]!='-' ){
118791           token = tkOTHER;
118792           break;
118793         }
118794         while( *zSql && *zSql!='\n' ){ zSql++; }
118795         if( *zSql==0 ) return state==1;
118796         token = tkWS;
118797         break;
118798       }
118799       case '[': {   /* Microsoft-style identifiers in [...] */
118800         zSql++;
118801         while( *zSql && *zSql!=']' ){ zSql++; }
118802         if( *zSql==0 ) return 0;
118803         token = tkOTHER;
118804         break;
118805       }
118806       case '`':     /* Grave-accent quoted symbols used by MySQL */
118807       case '"':     /* single- and double-quoted strings */
118808       case '\'': {
118809         int c = *zSql;
118810         zSql++;
118811         while( *zSql && *zSql!=c ){ zSql++; }
118812         if( *zSql==0 ) return 0;
118813         token = tkOTHER;
118814         break;
118815       }
118816       default: {
118817 #ifdef SQLITE_EBCDIC
118818         unsigned char c;
118819 #endif
118820         if( IdChar((u8)*zSql) ){
118821           /* Keywords and unquoted identifiers */
118822           int nId;
118823           for(nId=1; IdChar(zSql[nId]); nId++){}
118824 #ifdef SQLITE_OMIT_TRIGGER
118825           token = tkOTHER;
118826 #else
118827           switch( *zSql ){
118828             case 'c': case 'C': {
118829               if( nId==6 && sqlite3StrNICmp(zSql, "create", 6)==0 ){
118830                 token = tkCREATE;
118831               }else{
118832                 token = tkOTHER;
118833               }
118834               break;
118835             }
118836             case 't': case 'T': {
118837               if( nId==7 && sqlite3StrNICmp(zSql, "trigger", 7)==0 ){
118838                 token = tkTRIGGER;
118839               }else if( nId==4 && sqlite3StrNICmp(zSql, "temp", 4)==0 ){
118840                 token = tkTEMP;
118841               }else if( nId==9 && sqlite3StrNICmp(zSql, "temporary", 9)==0 ){
118842                 token = tkTEMP;
118843               }else{
118844                 token = tkOTHER;
118845               }
118846               break;
118847             }
118848             case 'e':  case 'E': {
118849               if( nId==3 && sqlite3StrNICmp(zSql, "end", 3)==0 ){
118850                 token = tkEND;
118851               }else
118852 #ifndef SQLITE_OMIT_EXPLAIN
118853               if( nId==7 && sqlite3StrNICmp(zSql, "explain", 7)==0 ){
118854                 token = tkEXPLAIN;
118855               }else
118856 #endif
118857               {
118858                 token = tkOTHER;
118859               }
118860               break;
118861             }
118862             default: {
118863               token = tkOTHER;
118864               break;
118865             }
118866           }
118867 #endif /* SQLITE_OMIT_TRIGGER */
118868           zSql += nId-1;
118869         }else{
118870           /* Operators and special symbols */
118871           token = tkOTHER;
118872         }
118873         break;
118874       }
118875     }
118876     state = trans[state][token];
118877     zSql++;
118878   }
118879   return state==1;
118880 }
118881 
118882 #ifndef SQLITE_OMIT_UTF16
118883 /*
118884 ** This routine is the same as the sqlite3_complete() routine described
118885 ** above, except that the parameter is required to be UTF-16 encoded, not
118886 ** UTF-8.
118887 */
118888 SQLITE_API int sqlite3_complete16(const void *zSql){
118889   sqlite3_value *pVal;
118890   char const *zSql8;
118891   int rc = SQLITE_NOMEM;
118892 
118893 #ifndef SQLITE_OMIT_AUTOINIT
118894   rc = sqlite3_initialize();
118895   if( rc ) return rc;
118896 #endif
118897   pVal = sqlite3ValueNew(0);
118898   sqlite3ValueSetStr(pVal, -1, zSql, SQLITE_UTF16NATIVE, SQLITE_STATIC);
118899   zSql8 = sqlite3ValueText(pVal, SQLITE_UTF8);
118900   if( zSql8 ){
118901     rc = sqlite3_complete(zSql8);
118902   }else{
118903     rc = SQLITE_NOMEM;
118904   }
118905   sqlite3ValueFree(pVal);
118906   return sqlite3ApiExit(0, rc);
118907 }
118908 #endif /* SQLITE_OMIT_UTF16 */
118909 #endif /* SQLITE_OMIT_COMPLETE */
118910 
118911 /************** End of complete.c ********************************************/
118912 /************** Begin file main.c ********************************************/
118913 /*
118914 ** 2001 September 15
118915 **
118916 ** The author disclaims copyright to this source code.  In place of
118917 ** a legal notice, here is a blessing:
118918 **
118919 **    May you do good and not evil.
118920 **    May you find forgiveness for yourself and forgive others.
118921 **    May you share freely, never taking more than you give.
118922 **
118923 *************************************************************************
118924 ** Main file for the SQLite library.  The routines in this file
118925 ** implement the programmer interface to the library.  Routines in
118926 ** other files are for internal use by SQLite and should not be
118927 ** accessed by users of the library.
118928 */
118929 
118930 #ifdef SQLITE_ENABLE_FTS3
118931 /************** Include fts3.h in the middle of main.c ***********************/
118932 /************** Begin file fts3.h ********************************************/
118933 /*
118934 ** 2006 Oct 10
118935 **
118936 ** The author disclaims copyright to this source code.  In place of
118937 ** a legal notice, here is a blessing:
118938 **
118939 **    May you do good and not evil.
118940 **    May you find forgiveness for yourself and forgive others.
118941 **    May you share freely, never taking more than you give.
118942 **
118943 ******************************************************************************
118944 **
118945 ** This header file is used by programs that want to link against the
118946 ** FTS3 library.  All it does is declare the sqlite3Fts3Init() interface.
118947 */
118948 
118949 #if 0
118950 extern "C" {
118951 #endif  /* __cplusplus */
118952 
118953 SQLITE_PRIVATE int sqlite3Fts3Init(sqlite3 *db);
118954 
118955 #if 0
118956 }  /* extern "C" */
118957 #endif  /* __cplusplus */
118958 
118959 /************** End of fts3.h ************************************************/
118960 /************** Continuing where we left off in main.c ***********************/
118961 #endif
118962 #ifdef SQLITE_ENABLE_RTREE
118963 /************** Include rtree.h in the middle of main.c **********************/
118964 /************** Begin file rtree.h *******************************************/
118965 /*
118966 ** 2008 May 26
118967 **
118968 ** The author disclaims copyright to this source code.  In place of
118969 ** a legal notice, here is a blessing:
118970 **
118971 **    May you do good and not evil.
118972 **    May you find forgiveness for yourself and forgive others.
118973 **    May you share freely, never taking more than you give.
118974 **
118975 ******************************************************************************
118976 **
118977 ** This header file is used by programs that want to link against the
118978 ** RTREE library.  All it does is declare the sqlite3RtreeInit() interface.
118979 */
118980 
118981 #if 0
118982 extern "C" {
118983 #endif  /* __cplusplus */
118984 
118985 SQLITE_PRIVATE int sqlite3RtreeInit(sqlite3 *db);
118986 
118987 #if 0
118988 }  /* extern "C" */
118989 #endif  /* __cplusplus */
118990 
118991 /************** End of rtree.h ***********************************************/
118992 /************** Continuing where we left off in main.c ***********************/
118993 #endif
118994 #ifdef SQLITE_ENABLE_ICU
118995 /************** Include sqliteicu.h in the middle of main.c ******************/
118996 /************** Begin file sqliteicu.h ***************************************/
118997 /*
118998 ** 2008 May 26
118999 **
119000 ** The author disclaims copyright to this source code.  In place of
119001 ** a legal notice, here is a blessing:
119002 **
119003 **    May you do good and not evil.
119004 **    May you find forgiveness for yourself and forgive others.
119005 **    May you share freely, never taking more than you give.
119006 **
119007 ******************************************************************************
119008 **
119009 ** This header file is used by programs that want to link against the
119010 ** ICU extension.  All it does is declare the sqlite3IcuInit() interface.
119011 */
119012 
119013 #if 0
119014 extern "C" {
119015 #endif  /* __cplusplus */
119016 
119017 SQLITE_PRIVATE int sqlite3IcuInit(sqlite3 *db);
119018 
119019 #if 0
119020 }  /* extern "C" */
119021 #endif  /* __cplusplus */
119022 
119023 
119024 /************** End of sqliteicu.h *******************************************/
119025 /************** Continuing where we left off in main.c ***********************/
119026 #endif
119027 
119028 #ifndef SQLITE_AMALGAMATION
119029 /* IMPLEMENTATION-OF: R-46656-45156 The sqlite3_version[] string constant
119030 ** contains the text of SQLITE_VERSION macro. 
119031 */
119032 SQLITE_API const char sqlite3_version[] = SQLITE_VERSION;
119033 #endif
119034 
119035 /* IMPLEMENTATION-OF: R-53536-42575 The sqlite3_libversion() function returns
119036 ** a pointer to the to the sqlite3_version[] string constant. 
119037 */
119038 SQLITE_API const char *sqlite3_libversion(void){ return sqlite3_version; }
119039 
119040 /* IMPLEMENTATION-OF: R-63124-39300 The sqlite3_sourceid() function returns a
119041 ** pointer to a string constant whose value is the same as the
119042 ** SQLITE_SOURCE_ID C preprocessor macro. 
119043 */
119044 SQLITE_API const char *sqlite3_sourceid(void){ return SQLITE_SOURCE_ID; }
119045 
119046 /* IMPLEMENTATION-OF: R-35210-63508 The sqlite3_libversion_number() function
119047 ** returns an integer equal to SQLITE_VERSION_NUMBER.
119048 */
119049 SQLITE_API int sqlite3_libversion_number(void){ return SQLITE_VERSION_NUMBER; }
119050 
119051 /* IMPLEMENTATION-OF: R-20790-14025 The sqlite3_threadsafe() function returns
119052 ** zero if and only if SQLite was compiled with mutexing code omitted due to
119053 ** the SQLITE_THREADSAFE compile-time option being set to 0.
119054 */
119055 SQLITE_API int sqlite3_threadsafe(void){ return SQLITE_THREADSAFE; }
119056 
119057 #if !defined(SQLITE_OMIT_TRACE) && defined(SQLITE_ENABLE_IOTRACE)
119058 /*
119059 ** If the following function pointer is not NULL and if
119060 ** SQLITE_ENABLE_IOTRACE is enabled, then messages describing
119061 ** I/O active are written using this function.  These messages
119062 ** are intended for debugging activity only.
119063 */
119064 SQLITE_PRIVATE void (*sqlite3IoTrace)(const char*, ...) = 0;
119065 #endif
119066 
119067 /*
119068 ** If the following global variable points to a string which is the
119069 ** name of a directory, then that directory will be used to store
119070 ** temporary files.
119071 **
119072 ** See also the "PRAGMA temp_store_directory" SQL command.
119073 */
119074 SQLITE_API char *sqlite3_temp_directory = 0;
119075 
119076 /*
119077 ** If the following global variable points to a string which is the
119078 ** name of a directory, then that directory will be used to store
119079 ** all database files specified with a relative pathname.
119080 **
119081 ** See also the "PRAGMA data_store_directory" SQL command.
119082 */
119083 SQLITE_API char *sqlite3_data_directory = 0;
119084 
119085 /*
119086 ** Initialize SQLite.  
119087 **
119088 ** This routine must be called to initialize the memory allocation,
119089 ** VFS, and mutex subsystems prior to doing any serious work with
119090 ** SQLite.  But as long as you do not compile with SQLITE_OMIT_AUTOINIT
119091 ** this routine will be called automatically by key routines such as
119092 ** sqlite3_open().  
119093 **
119094 ** This routine is a no-op except on its very first call for the process,
119095 ** or for the first call after a call to sqlite3_shutdown.
119096 **
119097 ** The first thread to call this routine runs the initialization to
119098 ** completion.  If subsequent threads call this routine before the first
119099 ** thread has finished the initialization process, then the subsequent
119100 ** threads must block until the first thread finishes with the initialization.
119101 **
119102 ** The first thread might call this routine recursively.  Recursive
119103 ** calls to this routine should not block, of course.  Otherwise the
119104 ** initialization process would never complete.
119105 **
119106 ** Let X be the first thread to enter this routine.  Let Y be some other
119107 ** thread.  Then while the initial invocation of this routine by X is
119108 ** incomplete, it is required that:
119109 **
119110 **    *  Calls to this routine from Y must block until the outer-most
119111 **       call by X completes.
119112 **
119113 **    *  Recursive calls to this routine from thread X return immediately
119114 **       without blocking.
119115 */
119116 SQLITE_API int sqlite3_initialize(void){
119117   MUTEX_LOGIC( sqlite3_mutex *pMaster; )       /* The main static mutex */
119118   int rc;                                      /* Result code */
119119 #ifdef SQLITE_EXTRA_INIT
119120   int bRunExtraInit = 0;                       /* Extra initialization needed */
119121 #endif
119122 
119123 #ifdef SQLITE_OMIT_WSD
119124   rc = sqlite3_wsd_init(4096, 24);
119125   if( rc!=SQLITE_OK ){
119126     return rc;
119127   }
119128 #endif
119129 
119130   /* If SQLite is already completely initialized, then this call
119131   ** to sqlite3_initialize() should be a no-op.  But the initialization
119132   ** must be complete.  So isInit must not be set until the very end
119133   ** of this routine.
119134   */
119135   if( sqlite3GlobalConfig.isInit ) return SQLITE_OK;
119136 
119137 #ifdef SQLITE_ENABLE_SQLLOG
119138   {
119139     extern void sqlite3_init_sqllog(void);
119140     sqlite3_init_sqllog();
119141   }
119142 #endif
119143 
119144   /* Make sure the mutex subsystem is initialized.  If unable to 
119145   ** initialize the mutex subsystem, return early with the error.
119146   ** If the system is so sick that we are unable to allocate a mutex,
119147   ** there is not much SQLite is going to be able to do.
119148   **
119149   ** The mutex subsystem must take care of serializing its own
119150   ** initialization.
119151   */
119152   rc = sqlite3MutexInit();
119153   if( rc ) return rc;
119154 
119155   /* Initialize the malloc() system and the recursive pInitMutex mutex.
119156   ** This operation is protected by the STATIC_MASTER mutex.  Note that
119157   ** MutexAlloc() is called for a static mutex prior to initializing the
119158   ** malloc subsystem - this implies that the allocation of a static
119159   ** mutex must not require support from the malloc subsystem.
119160   */
119161   MUTEX_LOGIC( pMaster = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); )
119162   sqlite3_mutex_enter(pMaster);
119163   sqlite3GlobalConfig.isMutexInit = 1;
119164   if( !sqlite3GlobalConfig.isMallocInit ){
119165     rc = sqlite3MallocInit();
119166   }
119167   if( rc==SQLITE_OK ){
119168     sqlite3GlobalConfig.isMallocInit = 1;
119169     if( !sqlite3GlobalConfig.pInitMutex ){
119170       sqlite3GlobalConfig.pInitMutex =
119171            sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE);
119172       if( sqlite3GlobalConfig.bCoreMutex && !sqlite3GlobalConfig.pInitMutex ){
119173         rc = SQLITE_NOMEM;
119174       }
119175     }
119176   }
119177   if( rc==SQLITE_OK ){
119178     sqlite3GlobalConfig.nRefInitMutex++;
119179   }
119180   sqlite3_mutex_leave(pMaster);
119181 
119182   /* If rc is not SQLITE_OK at this point, then either the malloc
119183   ** subsystem could not be initialized or the system failed to allocate
119184   ** the pInitMutex mutex. Return an error in either case.  */
119185   if( rc!=SQLITE_OK ){
119186     return rc;
119187   }
119188 
119189   /* Do the rest of the initialization under the recursive mutex so
119190   ** that we will be able to handle recursive calls into
119191   ** sqlite3_initialize().  The recursive calls normally come through
119192   ** sqlite3_os_init() when it invokes sqlite3_vfs_register(), but other
119193   ** recursive calls might also be possible.
119194   **
119195   ** IMPLEMENTATION-OF: R-00140-37445 SQLite automatically serializes calls
119196   ** to the xInit method, so the xInit method need not be threadsafe.
119197   **
119198   ** The following mutex is what serializes access to the appdef pcache xInit
119199   ** methods.  The sqlite3_pcache_methods.xInit() all is embedded in the
119200   ** call to sqlite3PcacheInitialize().
119201   */
119202   sqlite3_mutex_enter(sqlite3GlobalConfig.pInitMutex);
119203   if( sqlite3GlobalConfig.isInit==0 && sqlite3GlobalConfig.inProgress==0 ){
119204     FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
119205     sqlite3GlobalConfig.inProgress = 1;
119206     memset(pHash, 0, sizeof(sqlite3GlobalFunctions));
119207     sqlite3RegisterGlobalFunctions();
119208     if( sqlite3GlobalConfig.isPCacheInit==0 ){
119209       rc = sqlite3PcacheInitialize();
119210     }
119211     if( rc==SQLITE_OK ){
119212       sqlite3GlobalConfig.isPCacheInit = 1;
119213       rc = sqlite3OsInit();
119214     }
119215     if( rc==SQLITE_OK ){
119216       sqlite3PCacheBufferSetup( sqlite3GlobalConfig.pPage, 
119217           sqlite3GlobalConfig.szPage, sqlite3GlobalConfig.nPage);
119218       sqlite3GlobalConfig.isInit = 1;
119219 #ifdef SQLITE_EXTRA_INIT
119220       bRunExtraInit = 1;
119221 #endif
119222     }
119223     sqlite3GlobalConfig.inProgress = 0;
119224   }
119225   sqlite3_mutex_leave(sqlite3GlobalConfig.pInitMutex);
119226 
119227   /* Go back under the static mutex and clean up the recursive
119228   ** mutex to prevent a resource leak.
119229   */
119230   sqlite3_mutex_enter(pMaster);
119231   sqlite3GlobalConfig.nRefInitMutex--;
119232   if( sqlite3GlobalConfig.nRefInitMutex<=0 ){
119233     assert( sqlite3GlobalConfig.nRefInitMutex==0 );
119234     sqlite3_mutex_free(sqlite3GlobalConfig.pInitMutex);
119235     sqlite3GlobalConfig.pInitMutex = 0;
119236   }
119237   sqlite3_mutex_leave(pMaster);
119238 
119239   /* The following is just a sanity check to make sure SQLite has
119240   ** been compiled correctly.  It is important to run this code, but
119241   ** we don't want to run it too often and soak up CPU cycles for no
119242   ** reason.  So we run it once during initialization.
119243   */
119244 #ifndef NDEBUG
119245 #ifndef SQLITE_OMIT_FLOATING_POINT
119246   /* This section of code's only "output" is via assert() statements. */
119247   if ( rc==SQLITE_OK ){
119248     u64 x = (((u64)1)<<63)-1;
119249     double y;
119250     assert(sizeof(x)==8);
119251     assert(sizeof(x)==sizeof(y));
119252     memcpy(&y, &x, 8);
119253     assert( sqlite3IsNaN(y) );
119254   }
119255 #endif
119256 #endif
119257 
119258   /* Do extra initialization steps requested by the SQLITE_EXTRA_INIT
119259   ** compile-time option.
119260   */
119261 #ifdef SQLITE_EXTRA_INIT
119262   if( bRunExtraInit ){
119263     int SQLITE_EXTRA_INIT(const char*);
119264     rc = SQLITE_EXTRA_INIT(0);
119265   }
119266 #endif
119267 
119268   return rc;
119269 }
119270 
119271 /*
119272 ** Undo the effects of sqlite3_initialize().  Must not be called while
119273 ** there are outstanding database connections or memory allocations or
119274 ** while any part of SQLite is otherwise in use in any thread.  This
119275 ** routine is not threadsafe.  But it is safe to invoke this routine
119276 ** on when SQLite is already shut down.  If SQLite is already shut down
119277 ** when this routine is invoked, then this routine is a harmless no-op.
119278 */
119279 SQLITE_API int sqlite3_shutdown(void){
119280   if( sqlite3GlobalConfig.isInit ){
119281 #ifdef SQLITE_EXTRA_SHUTDOWN
119282     void SQLITE_EXTRA_SHUTDOWN(void);
119283     SQLITE_EXTRA_SHUTDOWN();
119284 #endif
119285     sqlite3_os_end();
119286     sqlite3_reset_auto_extension();
119287     sqlite3GlobalConfig.isInit = 0;
119288   }
119289   if( sqlite3GlobalConfig.isPCacheInit ){
119290     sqlite3PcacheShutdown();
119291     sqlite3GlobalConfig.isPCacheInit = 0;
119292   }
119293   if( sqlite3GlobalConfig.isMallocInit ){
119294     sqlite3MallocEnd();
119295     sqlite3GlobalConfig.isMallocInit = 0;
119296 
119297 #ifndef SQLITE_OMIT_SHUTDOWN_DIRECTORIES
119298     /* The heap subsystem has now been shutdown and these values are supposed
119299     ** to be NULL or point to memory that was obtained from sqlite3_malloc(),
119300     ** which would rely on that heap subsystem; therefore, make sure these
119301     ** values cannot refer to heap memory that was just invalidated when the
119302     ** heap subsystem was shutdown.  This is only done if the current call to
119303     ** this function resulted in the heap subsystem actually being shutdown.
119304     */
119305     sqlite3_data_directory = 0;
119306     sqlite3_temp_directory = 0;
119307 #endif
119308   }
119309   if( sqlite3GlobalConfig.isMutexInit ){
119310     sqlite3MutexEnd();
119311     sqlite3GlobalConfig.isMutexInit = 0;
119312   }
119313 
119314   return SQLITE_OK;
119315 }
119316 
119317 /*
119318 ** This API allows applications to modify the global configuration of
119319 ** the SQLite library at run-time.
119320 **
119321 ** This routine should only be called when there are no outstanding
119322 ** database connections or memory allocations.  This routine is not
119323 ** threadsafe.  Failure to heed these warnings can lead to unpredictable
119324 ** behavior.
119325 */
119326 SQLITE_API int sqlite3_config(int op, ...){
119327   va_list ap;
119328   int rc = SQLITE_OK;
119329 
119330   /* sqlite3_config() shall return SQLITE_MISUSE if it is invoked while
119331   ** the SQLite library is in use. */
119332   if( sqlite3GlobalConfig.isInit ) return SQLITE_MISUSE_BKPT;
119333 
119334   va_start(ap, op);
119335   switch( op ){
119336 
119337     /* Mutex configuration options are only available in a threadsafe
119338     ** compile. 
119339     */
119340 #if defined(SQLITE_THREADSAFE) && SQLITE_THREADSAFE>0
119341     case SQLITE_CONFIG_SINGLETHREAD: {
119342       /* Disable all mutexing */
119343       sqlite3GlobalConfig.bCoreMutex = 0;
119344       sqlite3GlobalConfig.bFullMutex = 0;
119345       break;
119346     }
119347     case SQLITE_CONFIG_MULTITHREAD: {
119348       /* Disable mutexing of database connections */
119349       /* Enable mutexing of core data structures */
119350       sqlite3GlobalConfig.bCoreMutex = 1;
119351       sqlite3GlobalConfig.bFullMutex = 0;
119352       break;
119353     }
119354     case SQLITE_CONFIG_SERIALIZED: {
119355       /* Enable all mutexing */
119356       sqlite3GlobalConfig.bCoreMutex = 1;
119357       sqlite3GlobalConfig.bFullMutex = 1;
119358       break;
119359     }
119360     case SQLITE_CONFIG_MUTEX: {
119361       /* Specify an alternative mutex implementation */
119362       sqlite3GlobalConfig.mutex = *va_arg(ap, sqlite3_mutex_methods*);
119363       break;
119364     }
119365     case SQLITE_CONFIG_GETMUTEX: {
119366       /* Retrieve the current mutex implementation */
119367       *va_arg(ap, sqlite3_mutex_methods*) = sqlite3GlobalConfig.mutex;
119368       break;
119369     }
119370 #endif
119371 
119372 
119373     case SQLITE_CONFIG_MALLOC: {
119374       /* Specify an alternative malloc implementation */
119375       sqlite3GlobalConfig.m = *va_arg(ap, sqlite3_mem_methods*);
119376       break;
119377     }
119378     case SQLITE_CONFIG_GETMALLOC: {
119379       /* Retrieve the current malloc() implementation */
119380       if( sqlite3GlobalConfig.m.xMalloc==0 ) sqlite3MemSetDefault();
119381       *va_arg(ap, sqlite3_mem_methods*) = sqlite3GlobalConfig.m;
119382       break;
119383     }
119384     case SQLITE_CONFIG_MEMSTATUS: {
119385       /* Enable or disable the malloc status collection */
119386       sqlite3GlobalConfig.bMemstat = va_arg(ap, int);
119387       break;
119388     }
119389     case SQLITE_CONFIG_SCRATCH: {
119390       /* Designate a buffer for scratch memory space */
119391       sqlite3GlobalConfig.pScratch = va_arg(ap, void*);
119392       sqlite3GlobalConfig.szScratch = va_arg(ap, int);
119393       sqlite3GlobalConfig.nScratch = va_arg(ap, int);
119394       break;
119395     }
119396     case SQLITE_CONFIG_PAGECACHE: {
119397       /* Designate a buffer for page cache memory space */
119398       sqlite3GlobalConfig.pPage = va_arg(ap, void*);
119399       sqlite3GlobalConfig.szPage = va_arg(ap, int);
119400       sqlite3GlobalConfig.nPage = va_arg(ap, int);
119401       break;
119402     }
119403 
119404     case SQLITE_CONFIG_PCACHE: {
119405       /* no-op */
119406       break;
119407     }
119408     case SQLITE_CONFIG_GETPCACHE: {
119409       /* now an error */
119410       rc = SQLITE_ERROR;
119411       break;
119412     }
119413 
119414     case SQLITE_CONFIG_PCACHE2: {
119415       /* Specify an alternative page cache implementation */
119416       sqlite3GlobalConfig.pcache2 = *va_arg(ap, sqlite3_pcache_methods2*);
119417       break;
119418     }
119419     case SQLITE_CONFIG_GETPCACHE2: {
119420       if( sqlite3GlobalConfig.pcache2.xInit==0 ){
119421         sqlite3PCacheSetDefault();
119422       }
119423       *va_arg(ap, sqlite3_pcache_methods2*) = sqlite3GlobalConfig.pcache2;
119424       break;
119425     }
119426 
119427 #if defined(SQLITE_ENABLE_MEMSYS3) || defined(SQLITE_ENABLE_MEMSYS5)
119428     case SQLITE_CONFIG_HEAP: {
119429       /* Designate a buffer for heap memory space */
119430       sqlite3GlobalConfig.pHeap = va_arg(ap, void*);
119431       sqlite3GlobalConfig.nHeap = va_arg(ap, int);
119432       sqlite3GlobalConfig.mnReq = va_arg(ap, int);
119433 
119434       if( sqlite3GlobalConfig.mnReq<1 ){
119435         sqlite3GlobalConfig.mnReq = 1;
119436       }else if( sqlite3GlobalConfig.mnReq>(1<<12) ){
119437         /* cap min request size at 2^12 */
119438         sqlite3GlobalConfig.mnReq = (1<<12);
119439       }
119440 
119441       if( sqlite3GlobalConfig.pHeap==0 ){
119442         /* If the heap pointer is NULL, then restore the malloc implementation
119443         ** back to NULL pointers too.  This will cause the malloc to go
119444         ** back to its default implementation when sqlite3_initialize() is
119445         ** run.
119446         */
119447         memset(&sqlite3GlobalConfig.m, 0, sizeof(sqlite3GlobalConfig.m));
119448       }else{
119449         /* The heap pointer is not NULL, then install one of the
119450         ** mem5.c/mem3.c methods.  The enclosing #if guarantees at
119451         ** least one of these methods is currently enabled.
119452         */
119453 #ifdef SQLITE_ENABLE_MEMSYS3
119454         sqlite3GlobalConfig.m = *sqlite3MemGetMemsys3();
119455 #endif
119456 #ifdef SQLITE_ENABLE_MEMSYS5
119457         sqlite3GlobalConfig.m = *sqlite3MemGetMemsys5();
119458 #endif
119459       }
119460       break;
119461     }
119462 #endif
119463 
119464     case SQLITE_CONFIG_LOOKASIDE: {
119465       sqlite3GlobalConfig.szLookaside = va_arg(ap, int);
119466       sqlite3GlobalConfig.nLookaside = va_arg(ap, int);
119467       break;
119468     }
119469     
119470     /* Record a pointer to the logger function and its first argument.
119471     ** The default is NULL.  Logging is disabled if the function pointer is
119472     ** NULL.
119473     */
119474     case SQLITE_CONFIG_LOG: {
119475       /* MSVC is picky about pulling func ptrs from va lists.
119476       ** http://support.microsoft.com/kb/47961
119477       ** sqlite3GlobalConfig.xLog = va_arg(ap, void(*)(void*,int,const char*));
119478       */
119479       typedef void(*LOGFUNC_t)(void*,int,const char*);
119480       sqlite3GlobalConfig.xLog = va_arg(ap, LOGFUNC_t);
119481       sqlite3GlobalConfig.pLogArg = va_arg(ap, void*);
119482       break;
119483     }
119484 
119485     case SQLITE_CONFIG_URI: {
119486       sqlite3GlobalConfig.bOpenUri = va_arg(ap, int);
119487       break;
119488     }
119489 
119490     case SQLITE_CONFIG_COVERING_INDEX_SCAN: {
119491       sqlite3GlobalConfig.bUseCis = va_arg(ap, int);
119492       break;
119493     }
119494 
119495 #ifdef SQLITE_ENABLE_SQLLOG
119496     case SQLITE_CONFIG_SQLLOG: {
119497       typedef void(*SQLLOGFUNC_t)(void*, sqlite3*, const char*, int);
119498       sqlite3GlobalConfig.xSqllog = va_arg(ap, SQLLOGFUNC_t);
119499       sqlite3GlobalConfig.pSqllogArg = va_arg(ap, void *);
119500       break;
119501     }
119502 #endif
119503 
119504     case SQLITE_CONFIG_MMAP_SIZE: {
119505       sqlite3_int64 szMmap = va_arg(ap, sqlite3_int64);
119506       sqlite3_int64 mxMmap = va_arg(ap, sqlite3_int64);
119507       if( mxMmap<0 || mxMmap>SQLITE_MAX_MMAP_SIZE ){
119508         mxMmap = SQLITE_MAX_MMAP_SIZE;
119509       }
119510       sqlite3GlobalConfig.mxMmap = mxMmap;
119511       if( szMmap<0 ) szMmap = SQLITE_DEFAULT_MMAP_SIZE;
119512       if( szMmap>mxMmap) szMmap = mxMmap;
119513       sqlite3GlobalConfig.szMmap = szMmap;
119514       break;
119515     }
119516 
119517 #if SQLITE_OS_WIN && defined(SQLITE_WIN32_MALLOC)
119518     case SQLITE_CONFIG_WIN32_HEAPSIZE: {
119519       sqlite3GlobalConfig.nHeap = va_arg(ap, int);
119520       break;
119521     }
119522 #endif
119523 
119524     default: {
119525       rc = SQLITE_ERROR;
119526       break;
119527     }
119528   }
119529   va_end(ap);
119530   return rc;
119531 }
119532 
119533 /*
119534 ** Set up the lookaside buffers for a database connection.
119535 ** Return SQLITE_OK on success.  
119536 ** If lookaside is already active, return SQLITE_BUSY.
119537 **
119538 ** The sz parameter is the number of bytes in each lookaside slot.
119539 ** The cnt parameter is the number of slots.  If pStart is NULL the
119540 ** space for the lookaside memory is obtained from sqlite3_malloc().
119541 ** If pStart is not NULL then it is sz*cnt bytes of memory to use for
119542 ** the lookaside memory.
119543 */
119544 static int setupLookaside(sqlite3 *db, void *pBuf, int sz, int cnt){
119545   void *pStart;
119546   if( db->lookaside.nOut ){
119547     return SQLITE_BUSY;
119548   }
119549   /* Free any existing lookaside buffer for this handle before
119550   ** allocating a new one so we don't have to have space for 
119551   ** both at the same time.
119552   */
119553   if( db->lookaside.bMalloced ){
119554     sqlite3_free(db->lookaside.pStart);
119555   }
119556   /* The size of a lookaside slot after ROUNDDOWN8 needs to be larger
119557   ** than a pointer to be useful.
119558   */
119559   sz = ROUNDDOWN8(sz);  /* IMP: R-33038-09382 */
119560   if( sz<=(int)sizeof(LookasideSlot*) ) sz = 0;
119561   if( cnt<0 ) cnt = 0;
119562   if( sz==0 || cnt==0 ){
119563     sz = 0;
119564     pStart = 0;
119565   }else if( pBuf==0 ){
119566     sqlite3BeginBenignMalloc();
119567     pStart = sqlite3Malloc( sz*cnt );  /* IMP: R-61949-35727 */
119568     sqlite3EndBenignMalloc();
119569     if( pStart ) cnt = sqlite3MallocSize(pStart)/sz;
119570   }else{
119571     pStart = pBuf;
119572   }
119573   db->lookaside.pStart = pStart;
119574   db->lookaside.pFree = 0;
119575   db->lookaside.sz = (u16)sz;
119576   if( pStart ){
119577     int i;
119578     LookasideSlot *p;
119579     assert( sz > (int)sizeof(LookasideSlot*) );
119580     p = (LookasideSlot*)pStart;
119581     for(i=cnt-1; i>=0; i--){
119582       p->pNext = db->lookaside.pFree;
119583       db->lookaside.pFree = p;
119584       p = (LookasideSlot*)&((u8*)p)[sz];
119585     }
119586     db->lookaside.pEnd = p;
119587     db->lookaside.bEnabled = 1;
119588     db->lookaside.bMalloced = pBuf==0 ?1:0;
119589   }else{
119590     db->lookaside.pEnd = 0;
119591     db->lookaside.bEnabled = 0;
119592     db->lookaside.bMalloced = 0;
119593   }
119594   return SQLITE_OK;
119595 }
119596 
119597 /*
119598 ** Return the mutex associated with a database connection.
119599 */
119600 SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3 *db){
119601   return db->mutex;
119602 }
119603 
119604 /*
119605 ** Free up as much memory as we can from the given database
119606 ** connection.
119607 */
119608 SQLITE_API int sqlite3_db_release_memory(sqlite3 *db){
119609   int i;
119610   sqlite3_mutex_enter(db->mutex);
119611   sqlite3BtreeEnterAll(db);
119612   for(i=0; i<db->nDb; i++){
119613     Btree *pBt = db->aDb[i].pBt;
119614     if( pBt ){
119615       Pager *pPager = sqlite3BtreePager(pBt);
119616       sqlite3PagerShrink(pPager);
119617     }
119618   }
119619   sqlite3BtreeLeaveAll(db);
119620   sqlite3_mutex_leave(db->mutex);
119621   return SQLITE_OK;
119622 }
119623 
119624 /*
119625 ** Configuration settings for an individual database connection
119626 */
119627 SQLITE_API int sqlite3_db_config(sqlite3 *db, int op, ...){
119628   va_list ap;
119629   int rc;
119630   va_start(ap, op);
119631   switch( op ){
119632     case SQLITE_DBCONFIG_LOOKASIDE: {
119633       void *pBuf = va_arg(ap, void*); /* IMP: R-26835-10964 */
119634       int sz = va_arg(ap, int);       /* IMP: R-47871-25994 */
119635       int cnt = va_arg(ap, int);      /* IMP: R-04460-53386 */
119636       rc = setupLookaside(db, pBuf, sz, cnt);
119637       break;
119638     }
119639     default: {
119640       static const struct {
119641         int op;      /* The opcode */
119642         u32 mask;    /* Mask of the bit in sqlite3.flags to set/clear */
119643       } aFlagOp[] = {
119644         { SQLITE_DBCONFIG_ENABLE_FKEY,    SQLITE_ForeignKeys    },
119645         { SQLITE_DBCONFIG_ENABLE_TRIGGER, SQLITE_EnableTrigger  },
119646       };
119647       unsigned int i;
119648       rc = SQLITE_ERROR; /* IMP: R-42790-23372 */
119649       for(i=0; i<ArraySize(aFlagOp); i++){
119650         if( aFlagOp[i].op==op ){
119651           int onoff = va_arg(ap, int);
119652           int *pRes = va_arg(ap, int*);
119653           int oldFlags = db->flags;
119654           if( onoff>0 ){
119655             db->flags |= aFlagOp[i].mask;
119656           }else if( onoff==0 ){
119657             db->flags &= ~aFlagOp[i].mask;
119658           }
119659           if( oldFlags!=db->flags ){
119660             sqlite3ExpirePreparedStatements(db);
119661           }
119662           if( pRes ){
119663             *pRes = (db->flags & aFlagOp[i].mask)!=0;
119664           }
119665           rc = SQLITE_OK;
119666           break;
119667         }
119668       }
119669       break;
119670     }
119671   }
119672   va_end(ap);
119673   return rc;
119674 }
119675 
119676 
119677 /*
119678 ** Return true if the buffer z[0..n-1] contains all spaces.
119679 */
119680 static int allSpaces(const char *z, int n){
119681   while( n>0 && z[n-1]==' ' ){ n--; }
119682   return n==0;
119683 }
119684 
119685 /*
119686 ** This is the default collating function named "BINARY" which is always
119687 ** available.
119688 **
119689 ** If the padFlag argument is not NULL then space padding at the end
119690 ** of strings is ignored.  This implements the RTRIM collation.
119691 */
119692 static int binCollFunc(
119693   void *padFlag,
119694   int nKey1, const void *pKey1,
119695   int nKey2, const void *pKey2
119696 ){
119697   int rc, n;
119698   n = nKey1<nKey2 ? nKey1 : nKey2;
119699   rc = memcmp(pKey1, pKey2, n);
119700   if( rc==0 ){
119701     if( padFlag
119702      && allSpaces(((char*)pKey1)+n, nKey1-n)
119703      && allSpaces(((char*)pKey2)+n, nKey2-n)
119704     ){
119705       /* Leave rc unchanged at 0 */
119706     }else{
119707       rc = nKey1 - nKey2;
119708     }
119709   }
119710   return rc;
119711 }
119712 
119713 /*
119714 ** Another built-in collating sequence: NOCASE. 
119715 **
119716 ** This collating sequence is intended to be used for "case independent
119717 ** comparison". SQLite's knowledge of upper and lower case equivalents
119718 ** extends only to the 26 characters used in the English language.
119719 **
119720 ** At the moment there is only a UTF-8 implementation.
119721 */
119722 static int nocaseCollatingFunc(
119723   void *NotUsed,
119724   int nKey1, const void *pKey1,
119725   int nKey2, const void *pKey2
119726 ){
119727   int r = sqlite3StrNICmp(
119728       (const char *)pKey1, (const char *)pKey2, (nKey1<nKey2)?nKey1:nKey2);
119729   UNUSED_PARAMETER(NotUsed);
119730   if( 0==r ){
119731     r = nKey1-nKey2;
119732   }
119733   return r;
119734 }
119735 
119736 /*
119737 ** Return the ROWID of the most recent insert
119738 */
119739 SQLITE_API sqlite_int64 sqlite3_last_insert_rowid(sqlite3 *db){
119740   return db->lastRowid;
119741 }
119742 
119743 /*
119744 ** Return the number of changes in the most recent call to sqlite3_exec().
119745 */
119746 SQLITE_API int sqlite3_changes(sqlite3 *db){
119747   return db->nChange;
119748 }
119749 
119750 /*
119751 ** Return the number of changes since the database handle was opened.
119752 */
119753 SQLITE_API int sqlite3_total_changes(sqlite3 *db){
119754   return db->nTotalChange;
119755 }
119756 
119757 /*
119758 ** Close all open savepoints. This function only manipulates fields of the
119759 ** database handle object, it does not close any savepoints that may be open
119760 ** at the b-tree/pager level.
119761 */
119762 SQLITE_PRIVATE void sqlite3CloseSavepoints(sqlite3 *db){
119763   while( db->pSavepoint ){
119764     Savepoint *pTmp = db->pSavepoint;
119765     db->pSavepoint = pTmp->pNext;
119766     sqlite3DbFree(db, pTmp);
119767   }
119768   db->nSavepoint = 0;
119769   db->nStatement = 0;
119770   db->isTransactionSavepoint = 0;
119771 }
119772 
119773 /*
119774 ** Invoke the destructor function associated with FuncDef p, if any. Except,
119775 ** if this is not the last copy of the function, do not invoke it. Multiple
119776 ** copies of a single function are created when create_function() is called
119777 ** with SQLITE_ANY as the encoding.
119778 */
119779 static void functionDestroy(sqlite3 *db, FuncDef *p){
119780   FuncDestructor *pDestructor = p->pDestructor;
119781   if( pDestructor ){
119782     pDestructor->nRef--;
119783     if( pDestructor->nRef==0 ){
119784       pDestructor->xDestroy(pDestructor->pUserData);
119785       sqlite3DbFree(db, pDestructor);
119786     }
119787   }
119788 }
119789 
119790 /*
119791 ** Disconnect all sqlite3_vtab objects that belong to database connection
119792 ** db. This is called when db is being closed.
119793 */
119794 static void disconnectAllVtab(sqlite3 *db){
119795 #ifndef SQLITE_OMIT_VIRTUALTABLE
119796   int i;
119797   sqlite3BtreeEnterAll(db);
119798   for(i=0; i<db->nDb; i++){
119799     Schema *pSchema = db->aDb[i].pSchema;
119800     if( db->aDb[i].pSchema ){
119801       HashElem *p;
119802       for(p=sqliteHashFirst(&pSchema->tblHash); p; p=sqliteHashNext(p)){
119803         Table *pTab = (Table *)sqliteHashData(p);
119804         if( IsVirtual(pTab) ) sqlite3VtabDisconnect(db, pTab);
119805       }
119806     }
119807   }
119808   sqlite3BtreeLeaveAll(db);
119809 #else
119810   UNUSED_PARAMETER(db);
119811 #endif
119812 }
119813 
119814 /*
119815 ** Return TRUE if database connection db has unfinalized prepared
119816 ** statements or unfinished sqlite3_backup objects.  
119817 */
119818 static int connectionIsBusy(sqlite3 *db){
119819   int j;
119820   assert( sqlite3_mutex_held(db->mutex) );
119821   if( db->pVdbe ) return 1;
119822   for(j=0; j<db->nDb; j++){
119823     Btree *pBt = db->aDb[j].pBt;
119824     if( pBt && sqlite3BtreeIsInBackup(pBt) ) return 1;
119825   }
119826   return 0;
119827 }
119828 
119829 /*
119830 ** Close an existing SQLite database
119831 */
119832 static int sqlite3Close(sqlite3 *db, int forceZombie){
119833   if( !db ){
119834     return SQLITE_OK;
119835   }
119836   if( !sqlite3SafetyCheckSickOrOk(db) ){
119837     return SQLITE_MISUSE_BKPT;
119838   }
119839   sqlite3_mutex_enter(db->mutex);
119840 
119841   /* Force xDisconnect calls on all virtual tables */
119842   disconnectAllVtab(db);
119843 
119844   /* If a transaction is open, the disconnectAllVtab() call above
119845   ** will not have called the xDisconnect() method on any virtual
119846   ** tables in the db->aVTrans[] array. The following sqlite3VtabRollback()
119847   ** call will do so. We need to do this before the check for active
119848   ** SQL statements below, as the v-table implementation may be storing
119849   ** some prepared statements internally.
119850   */
119851   sqlite3VtabRollback(db);
119852 
119853   /* Legacy behavior (sqlite3_close() behavior) is to return
119854   ** SQLITE_BUSY if the connection can not be closed immediately.
119855   */
119856   if( !forceZombie && connectionIsBusy(db) ){
119857     sqlite3Error(db, SQLITE_BUSY, "unable to close due to unfinalized "
119858        "statements or unfinished backups");
119859     sqlite3_mutex_leave(db->mutex);
119860     return SQLITE_BUSY;
119861   }
119862 
119863 #ifdef SQLITE_ENABLE_SQLLOG
119864   if( sqlite3GlobalConfig.xSqllog ){
119865     /* Closing the handle. Fourth parameter is passed the value 2. */
119866     sqlite3GlobalConfig.xSqllog(sqlite3GlobalConfig.pSqllogArg, db, 0, 2);
119867   }
119868 #endif
119869 
119870   /* Convert the connection into a zombie and then close it.
119871   */
119872   db->magic = SQLITE_MAGIC_ZOMBIE;
119873   sqlite3LeaveMutexAndCloseZombie(db);
119874   return SQLITE_OK;
119875 }
119876 
119877 /*
119878 ** Two variations on the public interface for closing a database
119879 ** connection. The sqlite3_close() version returns SQLITE_BUSY and
119880 ** leaves the connection option if there are unfinalized prepared
119881 ** statements or unfinished sqlite3_backups.  The sqlite3_close_v2()
119882 ** version forces the connection to become a zombie if there are
119883 ** unclosed resources, and arranges for deallocation when the last
119884 ** prepare statement or sqlite3_backup closes.
119885 */
119886 SQLITE_API int sqlite3_close(sqlite3 *db){ return sqlite3Close(db,0); }
119887 SQLITE_API int sqlite3_close_v2(sqlite3 *db){ return sqlite3Close(db,1); }
119888 
119889 
119890 /*
119891 ** Close the mutex on database connection db.
119892 **
119893 ** Furthermore, if database connection db is a zombie (meaning that there
119894 ** has been a prior call to sqlite3_close(db) or sqlite3_close_v2(db)) and
119895 ** every sqlite3_stmt has now been finalized and every sqlite3_backup has
119896 ** finished, then free all resources.
119897 */
119898 SQLITE_PRIVATE void sqlite3LeaveMutexAndCloseZombie(sqlite3 *db){
119899   HashElem *i;                    /* Hash table iterator */
119900   int j;
119901 
119902   /* If there are outstanding sqlite3_stmt or sqlite3_backup objects
119903   ** or if the connection has not yet been closed by sqlite3_close_v2(),
119904   ** then just leave the mutex and return.
119905   */
119906   if( db->magic!=SQLITE_MAGIC_ZOMBIE || connectionIsBusy(db) ){
119907     sqlite3_mutex_leave(db->mutex);
119908     return;
119909   }
119910 
119911   /* If we reach this point, it means that the database connection has
119912   ** closed all sqlite3_stmt and sqlite3_backup objects and has been
119913   ** passed to sqlite3_close (meaning that it is a zombie).  Therefore,
119914   ** go ahead and free all resources.
119915   */
119916 
119917   /* If a transaction is open, roll it back. This also ensures that if
119918   ** any database schemas have been modified by an uncommitted transaction
119919   ** they are reset. And that the required b-tree mutex is held to make
119920   ** the pager rollback and schema reset an atomic operation. */
119921   sqlite3RollbackAll(db, SQLITE_OK);
119922 
119923   /* Free any outstanding Savepoint structures. */
119924   sqlite3CloseSavepoints(db);
119925 
119926   /* Close all database connections */
119927   for(j=0; j<db->nDb; j++){
119928     struct Db *pDb = &db->aDb[j];
119929     if( pDb->pBt ){
119930       sqlite3BtreeClose(pDb->pBt);
119931       pDb->pBt = 0;
119932       if( j!=1 ){
119933         pDb->pSchema = 0;
119934       }
119935     }
119936   }
119937   /* Clear the TEMP schema separately and last */
119938   if( db->aDb[1].pSchema ){
119939     sqlite3SchemaClear(db->aDb[1].pSchema);
119940   }
119941   sqlite3VtabUnlockList(db);
119942 
119943   /* Free up the array of auxiliary databases */
119944   sqlite3CollapseDatabaseArray(db);
119945   assert( db->nDb<=2 );
119946   assert( db->aDb==db->aDbStatic );
119947 
119948   /* Tell the code in notify.c that the connection no longer holds any
119949   ** locks and does not require any further unlock-notify callbacks.
119950   */
119951   sqlite3ConnectionClosed(db);
119952 
119953   for(j=0; j<ArraySize(db->aFunc.a); j++){
119954     FuncDef *pNext, *pHash, *p;
119955     for(p=db->aFunc.a[j]; p; p=pHash){
119956       pHash = p->pHash;
119957       while( p ){
119958         functionDestroy(db, p);
119959         pNext = p->pNext;
119960         sqlite3DbFree(db, p);
119961         p = pNext;
119962       }
119963     }
119964   }
119965   for(i=sqliteHashFirst(&db->aCollSeq); i; i=sqliteHashNext(i)){
119966     CollSeq *pColl = (CollSeq *)sqliteHashData(i);
119967     /* Invoke any destructors registered for collation sequence user data. */
119968     for(j=0; j<3; j++){
119969       if( pColl[j].xDel ){
119970         pColl[j].xDel(pColl[j].pUser);
119971       }
119972     }
119973     sqlite3DbFree(db, pColl);
119974   }
119975   sqlite3HashClear(&db->aCollSeq);
119976 #ifndef SQLITE_OMIT_VIRTUALTABLE
119977   for(i=sqliteHashFirst(&db->aModule); i; i=sqliteHashNext(i)){
119978     Module *pMod = (Module *)sqliteHashData(i);
119979     if( pMod->xDestroy ){
119980       pMod->xDestroy(pMod->pAux);
119981     }
119982     sqlite3DbFree(db, pMod);
119983   }
119984   sqlite3HashClear(&db->aModule);
119985 #endif
119986 
119987   sqlite3Error(db, SQLITE_OK, 0); /* Deallocates any cached error strings. */
119988   if( db->pErr ){
119989     sqlite3ValueFree(db->pErr);
119990   }
119991   sqlite3CloseExtensions(db);
119992 
119993   db->magic = SQLITE_MAGIC_ERROR;
119994 
119995   /* The temp-database schema is allocated differently from the other schema
119996   ** objects (using sqliteMalloc() directly, instead of sqlite3BtreeSchema()).
119997   ** So it needs to be freed here. Todo: Why not roll the temp schema into
119998   ** the same sqliteMalloc() as the one that allocates the database 
119999   ** structure?
120000   */
120001   sqlite3DbFree(db, db->aDb[1].pSchema);
120002   sqlite3_mutex_leave(db->mutex);
120003   db->magic = SQLITE_MAGIC_CLOSED;
120004   sqlite3_mutex_free(db->mutex);
120005   assert( db->lookaside.nOut==0 );  /* Fails on a lookaside memory leak */
120006   if( db->lookaside.bMalloced ){
120007     sqlite3_free(db->lookaside.pStart);
120008   }
120009   sqlite3_free(db);
120010 }
120011 
120012 /*
120013 ** Rollback all database files.  If tripCode is not SQLITE_OK, then
120014 ** any open cursors are invalidated ("tripped" - as in "tripping a circuit
120015 ** breaker") and made to return tripCode if there are any further
120016 ** attempts to use that cursor.
120017 */
120018 SQLITE_PRIVATE void sqlite3RollbackAll(sqlite3 *db, int tripCode){
120019   int i;
120020   int inTrans = 0;
120021   assert( sqlite3_mutex_held(db->mutex) );
120022   sqlite3BeginBenignMalloc();
120023 
120024   /* Obtain all b-tree mutexes before making any calls to BtreeRollback(). 
120025   ** This is important in case the transaction being rolled back has
120026   ** modified the database schema. If the b-tree mutexes are not taken
120027   ** here, then another shared-cache connection might sneak in between
120028   ** the database rollback and schema reset, which can cause false
120029   ** corruption reports in some cases.  */
120030   sqlite3BtreeEnterAll(db);
120031 
120032   for(i=0; i<db->nDb; i++){
120033     Btree *p = db->aDb[i].pBt;
120034     if( p ){
120035       if( sqlite3BtreeIsInTrans(p) ){
120036         inTrans = 1;
120037       }
120038       sqlite3BtreeRollback(p, tripCode);
120039     }
120040   }
120041   sqlite3VtabRollback(db);
120042   sqlite3EndBenignMalloc();
120043 
120044   if( (db->flags&SQLITE_InternChanges)!=0 && db->init.busy==0 ){
120045     sqlite3ExpirePreparedStatements(db);
120046     sqlite3ResetAllSchemasOfConnection(db);
120047   }
120048   sqlite3BtreeLeaveAll(db);
120049 
120050   /* Any deferred constraint violations have now been resolved. */
120051   db->nDeferredCons = 0;
120052   db->nDeferredImmCons = 0;
120053   db->flags &= ~SQLITE_DeferFKs;
120054 
120055   /* If one has been configured, invoke the rollback-hook callback */
120056   if( db->xRollbackCallback && (inTrans || !db->autoCommit) ){
120057     db->xRollbackCallback(db->pRollbackArg);
120058   }
120059 }
120060 
120061 /*
120062 ** Return a static string containing the name corresponding to the error code
120063 ** specified in the argument.
120064 */
120065 #if defined(SQLITE_DEBUG) || defined(SQLITE_TEST) || \
120066     defined(SQLITE_DEBUG_OS_TRACE)
120067 SQLITE_PRIVATE const char *sqlite3ErrName(int rc){
120068   const char *zName = 0;
120069   int i, origRc = rc;
120070   for(i=0; i<2 && zName==0; i++, rc &= 0xff){
120071     switch( rc ){
120072       case SQLITE_OK:                 zName = "SQLITE_OK";                break;
120073       case SQLITE_ERROR:              zName = "SQLITE_ERROR";             break;
120074       case SQLITE_INTERNAL:           zName = "SQLITE_INTERNAL";          break;
120075       case SQLITE_PERM:               zName = "SQLITE_PERM";              break;
120076       case SQLITE_ABORT:              zName = "SQLITE_ABORT";             break;
120077       case SQLITE_ABORT_ROLLBACK:     zName = "SQLITE_ABORT_ROLLBACK";    break;
120078       case SQLITE_BUSY:               zName = "SQLITE_BUSY";              break;
120079       case SQLITE_BUSY_RECOVERY:      zName = "SQLITE_BUSY_RECOVERY";     break;
120080       case SQLITE_BUSY_SNAPSHOT:      zName = "SQLITE_BUSY_SNAPSHOT";     break;
120081       case SQLITE_LOCKED:             zName = "SQLITE_LOCKED";            break;
120082       case SQLITE_LOCKED_SHAREDCACHE: zName = "SQLITE_LOCKED_SHAREDCACHE";break;
120083       case SQLITE_NOMEM:              zName = "SQLITE_NOMEM";             break;
120084       case SQLITE_READONLY:           zName = "SQLITE_READONLY";          break;
120085       case SQLITE_READONLY_RECOVERY:  zName = "SQLITE_READONLY_RECOVERY"; break;
120086       case SQLITE_READONLY_CANTLOCK:  zName = "SQLITE_READONLY_CANTLOCK"; break;
120087       case SQLITE_READONLY_ROLLBACK:  zName = "SQLITE_READONLY_ROLLBACK"; break;
120088       case SQLITE_INTERRUPT:          zName = "SQLITE_INTERRUPT";         break;
120089       case SQLITE_IOERR:              zName = "SQLITE_IOERR";             break;
120090       case SQLITE_IOERR_READ:         zName = "SQLITE_IOERR_READ";        break;
120091       case SQLITE_IOERR_SHORT_READ:   zName = "SQLITE_IOERR_SHORT_READ";  break;
120092       case SQLITE_IOERR_WRITE:        zName = "SQLITE_IOERR_WRITE";       break;
120093       case SQLITE_IOERR_FSYNC:        zName = "SQLITE_IOERR_FSYNC";       break;
120094       case SQLITE_IOERR_DIR_FSYNC:    zName = "SQLITE_IOERR_DIR_FSYNC";   break;
120095       case SQLITE_IOERR_TRUNCATE:     zName = "SQLITE_IOERR_TRUNCATE";    break;
120096       case SQLITE_IOERR_FSTAT:        zName = "SQLITE_IOERR_FSTAT";       break;
120097       case SQLITE_IOERR_UNLOCK:       zName = "SQLITE_IOERR_UNLOCK";      break;
120098       case SQLITE_IOERR_RDLOCK:       zName = "SQLITE_IOERR_RDLOCK";      break;
120099       case SQLITE_IOERR_DELETE:       zName = "SQLITE_IOERR_DELETE";      break;
120100       case SQLITE_IOERR_BLOCKED:      zName = "SQLITE_IOERR_BLOCKED";     break;
120101       case SQLITE_IOERR_NOMEM:        zName = "SQLITE_IOERR_NOMEM";       break;
120102       case SQLITE_IOERR_ACCESS:       zName = "SQLITE_IOERR_ACCESS";      break;
120103       case SQLITE_IOERR_CHECKRESERVEDLOCK:
120104                                 zName = "SQLITE_IOERR_CHECKRESERVEDLOCK"; break;
120105       case SQLITE_IOERR_LOCK:         zName = "SQLITE_IOERR_LOCK";        break;
120106       case SQLITE_IOERR_CLOSE:        zName = "SQLITE_IOERR_CLOSE";       break;
120107       case SQLITE_IOERR_DIR_CLOSE:    zName = "SQLITE_IOERR_DIR_CLOSE";   break;
120108       case SQLITE_IOERR_SHMOPEN:      zName = "SQLITE_IOERR_SHMOPEN";     break;
120109       case SQLITE_IOERR_SHMSIZE:      zName = "SQLITE_IOERR_SHMSIZE";     break;
120110       case SQLITE_IOERR_SHMLOCK:      zName = "SQLITE_IOERR_SHMLOCK";     break;
120111       case SQLITE_IOERR_SHMMAP:       zName = "SQLITE_IOERR_SHMMAP";      break;
120112       case SQLITE_IOERR_SEEK:         zName = "SQLITE_IOERR_SEEK";        break;
120113       case SQLITE_IOERR_DELETE_NOENT: zName = "SQLITE_IOERR_DELETE_NOENT";break;
120114       case SQLITE_IOERR_MMAP:         zName = "SQLITE_IOERR_MMAP";        break;
120115       case SQLITE_IOERR_GETTEMPPATH:  zName = "SQLITE_IOERR_GETTEMPPATH"; break;
120116       case SQLITE_IOERR_CONVPATH:     zName = "SQLITE_IOERR_CONVPATH";    break;
120117       case SQLITE_CORRUPT:            zName = "SQLITE_CORRUPT";           break;
120118       case SQLITE_CORRUPT_VTAB:       zName = "SQLITE_CORRUPT_VTAB";      break;
120119       case SQLITE_NOTFOUND:           zName = "SQLITE_NOTFOUND";          break;
120120       case SQLITE_FULL:               zName = "SQLITE_FULL";              break;
120121       case SQLITE_CANTOPEN:           zName = "SQLITE_CANTOPEN";          break;
120122       case SQLITE_CANTOPEN_NOTEMPDIR: zName = "SQLITE_CANTOPEN_NOTEMPDIR";break;
120123       case SQLITE_CANTOPEN_ISDIR:     zName = "SQLITE_CANTOPEN_ISDIR";    break;
120124       case SQLITE_CANTOPEN_FULLPATH:  zName = "SQLITE_CANTOPEN_FULLPATH"; break;
120125       case SQLITE_CANTOPEN_CONVPATH:  zName = "SQLITE_CANTOPEN_CONVPATH"; break;
120126       case SQLITE_PROTOCOL:           zName = "SQLITE_PROTOCOL";          break;
120127       case SQLITE_EMPTY:              zName = "SQLITE_EMPTY";             break;
120128       case SQLITE_SCHEMA:             zName = "SQLITE_SCHEMA";            break;
120129       case SQLITE_TOOBIG:             zName = "SQLITE_TOOBIG";            break;
120130       case SQLITE_CONSTRAINT:         zName = "SQLITE_CONSTRAINT";        break;
120131       case SQLITE_CONSTRAINT_UNIQUE:  zName = "SQLITE_CONSTRAINT_UNIQUE"; break;
120132       case SQLITE_CONSTRAINT_TRIGGER: zName = "SQLITE_CONSTRAINT_TRIGGER";break;
120133       case SQLITE_CONSTRAINT_FOREIGNKEY:
120134                                 zName = "SQLITE_CONSTRAINT_FOREIGNKEY";   break;
120135       case SQLITE_CONSTRAINT_CHECK:   zName = "SQLITE_CONSTRAINT_CHECK";  break;
120136       case SQLITE_CONSTRAINT_PRIMARYKEY:
120137                                 zName = "SQLITE_CONSTRAINT_PRIMARYKEY";   break;
120138       case SQLITE_CONSTRAINT_NOTNULL: zName = "SQLITE_CONSTRAINT_NOTNULL";break;
120139       case SQLITE_CONSTRAINT_COMMITHOOK:
120140                                 zName = "SQLITE_CONSTRAINT_COMMITHOOK";   break;
120141       case SQLITE_CONSTRAINT_VTAB:    zName = "SQLITE_CONSTRAINT_VTAB";   break;
120142       case SQLITE_CONSTRAINT_FUNCTION:
120143                                 zName = "SQLITE_CONSTRAINT_FUNCTION";     break;
120144       case SQLITE_CONSTRAINT_ROWID:   zName = "SQLITE_CONSTRAINT_ROWID";  break;
120145       case SQLITE_MISMATCH:           zName = "SQLITE_MISMATCH";          break;
120146       case SQLITE_MISUSE:             zName = "SQLITE_MISUSE";            break;
120147       case SQLITE_NOLFS:              zName = "SQLITE_NOLFS";             break;
120148       case SQLITE_AUTH:               zName = "SQLITE_AUTH";              break;
120149       case SQLITE_FORMAT:             zName = "SQLITE_FORMAT";            break;
120150       case SQLITE_RANGE:              zName = "SQLITE_RANGE";             break;
120151       case SQLITE_NOTADB:             zName = "SQLITE_NOTADB";            break;
120152       case SQLITE_ROW:                zName = "SQLITE_ROW";               break;
120153       case SQLITE_NOTICE:             zName = "SQLITE_NOTICE";            break;
120154       case SQLITE_NOTICE_RECOVER_WAL: zName = "SQLITE_NOTICE_RECOVER_WAL";break;
120155       case SQLITE_NOTICE_RECOVER_ROLLBACK:
120156                                 zName = "SQLITE_NOTICE_RECOVER_ROLLBACK"; break;
120157       case SQLITE_WARNING:            zName = "SQLITE_WARNING";           break;
120158       case SQLITE_WARNING_AUTOINDEX:  zName = "SQLITE_WARNING_AUTOINDEX"; break;
120159       case SQLITE_DONE:               zName = "SQLITE_DONE";              break;
120160     }
120161   }
120162   if( zName==0 ){
120163     static char zBuf[50];
120164     sqlite3_snprintf(sizeof(zBuf), zBuf, "SQLITE_UNKNOWN(%d)", origRc);
120165     zName = zBuf;
120166   }
120167   return zName;
120168 }
120169 #endif
120170 
120171 /*
120172 ** Return a static string that describes the kind of error specified in the
120173 ** argument.
120174 */
120175 SQLITE_PRIVATE const char *sqlite3ErrStr(int rc){
120176   static const char* const aMsg[] = {
120177     /* SQLITE_OK          */ "not an error",
120178     /* SQLITE_ERROR       */ "SQL logic error or missing database",
120179     /* SQLITE_INTERNAL    */ 0,
120180     /* SQLITE_PERM        */ "access permission denied",
120181     /* SQLITE_ABORT       */ "callback requested query abort",
120182     /* SQLITE_BUSY        */ "database is locked",
120183     /* SQLITE_LOCKED      */ "database table is locked",
120184     /* SQLITE_NOMEM       */ "out of memory",
120185     /* SQLITE_READONLY    */ "attempt to write a readonly database",
120186     /* SQLITE_INTERRUPT   */ "interrupted",
120187     /* SQLITE_IOERR       */ "disk I/O error",
120188     /* SQLITE_CORRUPT     */ "database disk image is malformed",
120189     /* SQLITE_NOTFOUND    */ "unknown operation",
120190     /* SQLITE_FULL        */ "database or disk is full",
120191     /* SQLITE_CANTOPEN    */ "unable to open database file",
120192     /* SQLITE_PROTOCOL    */ "locking protocol",
120193     /* SQLITE_EMPTY       */ "table contains no data",
120194     /* SQLITE_SCHEMA      */ "database schema has changed",
120195     /* SQLITE_TOOBIG      */ "string or blob too big",
120196     /* SQLITE_CONSTRAINT  */ "constraint failed",
120197     /* SQLITE_MISMATCH    */ "datatype mismatch",
120198     /* SQLITE_MISUSE      */ "library routine called out of sequence",
120199     /* SQLITE_NOLFS       */ "large file support is disabled",
120200     /* SQLITE_AUTH        */ "authorization denied",
120201     /* SQLITE_FORMAT      */ "auxiliary database format error",
120202     /* SQLITE_RANGE       */ "bind or column index out of range",
120203     /* SQLITE_NOTADB      */ "file is encrypted or is not a database",
120204   };
120205   const char *zErr = "unknown error";
120206   switch( rc ){
120207     case SQLITE_ABORT_ROLLBACK: {
120208       zErr = "abort due to ROLLBACK";
120209       break;
120210     }
120211     default: {
120212       rc &= 0xff;
120213       if( ALWAYS(rc>=0) && rc<ArraySize(aMsg) && aMsg[rc]!=0 ){
120214         zErr = aMsg[rc];
120215       }
120216       break;
120217     }
120218   }
120219   return zErr;
120220 }
120221 
120222 /*
120223 ** This routine implements a busy callback that sleeps and tries
120224 ** again until a timeout value is reached.  The timeout value is
120225 ** an integer number of milliseconds passed in as the first
120226 ** argument.
120227 */
120228 static int sqliteDefaultBusyCallback(
120229  void *ptr,               /* Database connection */
120230  int count                /* Number of times table has been busy */
120231 ){
120232 #if SQLITE_OS_WIN || (defined(HAVE_USLEEP) && HAVE_USLEEP)
120233   static const u8 delays[] =
120234      { 1, 2, 5, 10, 15, 20, 25, 25,  25,  50,  50, 100 };
120235   static const u8 totals[] =
120236      { 0, 1, 3,  8, 18, 33, 53, 78, 103, 128, 178, 228 };
120237 # define NDELAY ArraySize(delays)
120238   sqlite3 *db = (sqlite3 *)ptr;
120239   int timeout = db->busyTimeout;
120240   int delay, prior;
120241 
120242   assert( count>=0 );
120243   if( count < NDELAY ){
120244     delay = delays[count];
120245     prior = totals[count];
120246   }else{
120247     delay = delays[NDELAY-1];
120248     prior = totals[NDELAY-1] + delay*(count-(NDELAY-1));
120249   }
120250   if( prior + delay > timeout ){
120251     delay = timeout - prior;
120252     if( delay<=0 ) return 0;
120253   }
120254   sqlite3OsSleep(db->pVfs, delay*1000);
120255   return 1;
120256 #else
120257   sqlite3 *db = (sqlite3 *)ptr;
120258   int timeout = ((sqlite3 *)ptr)->busyTimeout;
120259   if( (count+1)*1000 > timeout ){
120260     return 0;
120261   }
120262   sqlite3OsSleep(db->pVfs, 1000000);
120263   return 1;
120264 #endif
120265 }
120266 
120267 /*
120268 ** Invoke the given busy handler.
120269 **
120270 ** This routine is called when an operation failed with a lock.
120271 ** If this routine returns non-zero, the lock is retried.  If it
120272 ** returns 0, the operation aborts with an SQLITE_BUSY error.
120273 */
120274 SQLITE_PRIVATE int sqlite3InvokeBusyHandler(BusyHandler *p){
120275   int rc;
120276   if( NEVER(p==0) || p->xFunc==0 || p->nBusy<0 ) return 0;
120277   rc = p->xFunc(p->pArg, p->nBusy);
120278   if( rc==0 ){
120279     p->nBusy = -1;
120280   }else{
120281     p->nBusy++;
120282   }
120283   return rc; 
120284 }
120285 
120286 /*
120287 ** This routine sets the busy callback for an Sqlite database to the
120288 ** given callback function with the given argument.
120289 */
120290 SQLITE_API int sqlite3_busy_handler(
120291   sqlite3 *db,
120292   int (*xBusy)(void*,int),
120293   void *pArg
120294 ){
120295   sqlite3_mutex_enter(db->mutex);
120296   db->busyHandler.xFunc = xBusy;
120297   db->busyHandler.pArg = pArg;
120298   db->busyHandler.nBusy = 0;
120299   db->busyTimeout = 0;
120300   sqlite3_mutex_leave(db->mutex);
120301   return SQLITE_OK;
120302 }
120303 
120304 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
120305 /*
120306 ** This routine sets the progress callback for an Sqlite database to the
120307 ** given callback function with the given argument. The progress callback will
120308 ** be invoked every nOps opcodes.
120309 */
120310 SQLITE_API void sqlite3_progress_handler(
120311   sqlite3 *db, 
120312   int nOps,
120313   int (*xProgress)(void*), 
120314   void *pArg
120315 ){
120316   sqlite3_mutex_enter(db->mutex);
120317   if( nOps>0 ){
120318     db->xProgress = xProgress;
120319     db->nProgressOps = (unsigned)nOps;
120320     db->pProgressArg = pArg;
120321   }else{
120322     db->xProgress = 0;
120323     db->nProgressOps = 0;
120324     db->pProgressArg = 0;
120325   }
120326   sqlite3_mutex_leave(db->mutex);
120327 }
120328 #endif
120329 
120330 
120331 /*
120332 ** This routine installs a default busy handler that waits for the
120333 ** specified number of milliseconds before returning 0.
120334 */
120335 SQLITE_API int sqlite3_busy_timeout(sqlite3 *db, int ms){
120336   if( ms>0 ){
120337     sqlite3_busy_handler(db, sqliteDefaultBusyCallback, (void*)db);
120338     db->busyTimeout = ms;
120339   }else{
120340     sqlite3_busy_handler(db, 0, 0);
120341   }
120342   return SQLITE_OK;
120343 }
120344 
120345 /*
120346 ** Cause any pending operation to stop at its earliest opportunity.
120347 */
120348 SQLITE_API void sqlite3_interrupt(sqlite3 *db){
120349   db->u1.isInterrupted = 1;
120350 }
120351 
120352 
120353 /*
120354 ** This function is exactly the same as sqlite3_create_function(), except
120355 ** that it is designed to be called by internal code. The difference is
120356 ** that if a malloc() fails in sqlite3_create_function(), an error code
120357 ** is returned and the mallocFailed flag cleared. 
120358 */
120359 SQLITE_PRIVATE int sqlite3CreateFunc(
120360   sqlite3 *db,
120361   const char *zFunctionName,
120362   int nArg,
120363   int enc,
120364   void *pUserData,
120365   void (*xFunc)(sqlite3_context*,int,sqlite3_value **),
120366   void (*xStep)(sqlite3_context*,int,sqlite3_value **),
120367   void (*xFinal)(sqlite3_context*),
120368   FuncDestructor *pDestructor
120369 ){
120370   FuncDef *p;
120371   int nName;
120372 
120373   assert( sqlite3_mutex_held(db->mutex) );
120374   if( zFunctionName==0 ||
120375       (xFunc && (xFinal || xStep)) || 
120376       (!xFunc && (xFinal && !xStep)) ||
120377       (!xFunc && (!xFinal && xStep)) ||
120378       (nArg<-1 || nArg>SQLITE_MAX_FUNCTION_ARG) ||
120379       (255<(nName = sqlite3Strlen30( zFunctionName))) ){
120380     return SQLITE_MISUSE_BKPT;
120381   }
120382   
120383 #ifndef SQLITE_OMIT_UTF16
120384   /* If SQLITE_UTF16 is specified as the encoding type, transform this
120385   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the
120386   ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
120387   **
120388   ** If SQLITE_ANY is specified, add three versions of the function
120389   ** to the hash table.
120390   */
120391   if( enc==SQLITE_UTF16 ){
120392     enc = SQLITE_UTF16NATIVE;
120393   }else if( enc==SQLITE_ANY ){
120394     int rc;
120395     rc = sqlite3CreateFunc(db, zFunctionName, nArg, SQLITE_UTF8,
120396          pUserData, xFunc, xStep, xFinal, pDestructor);
120397     if( rc==SQLITE_OK ){
120398       rc = sqlite3CreateFunc(db, zFunctionName, nArg, SQLITE_UTF16LE,
120399           pUserData, xFunc, xStep, xFinal, pDestructor);
120400     }
120401     if( rc!=SQLITE_OK ){
120402       return rc;
120403     }
120404     enc = SQLITE_UTF16BE;
120405   }
120406 #else
120407   enc = SQLITE_UTF8;
120408 #endif
120409   
120410   /* Check if an existing function is being overridden or deleted. If so,
120411   ** and there are active VMs, then return SQLITE_BUSY. If a function
120412   ** is being overridden/deleted but there are no active VMs, allow the
120413   ** operation to continue but invalidate all precompiled statements.
120414   */
120415   p = sqlite3FindFunction(db, zFunctionName, nName, nArg, (u8)enc, 0);
120416   if( p && (p->funcFlags & SQLITE_FUNC_ENCMASK)==enc && p->nArg==nArg ){
120417     if( db->nVdbeActive ){
120418       sqlite3Error(db, SQLITE_BUSY, 
120419         "unable to delete/modify user-function due to active statements");
120420       assert( !db->mallocFailed );
120421       return SQLITE_BUSY;
120422     }else{
120423       sqlite3ExpirePreparedStatements(db);
120424     }
120425   }
120426 
120427   p = sqlite3FindFunction(db, zFunctionName, nName, nArg, (u8)enc, 1);
120428   assert(p || db->mallocFailed);
120429   if( !p ){
120430     return SQLITE_NOMEM;
120431   }
120432 
120433   /* If an older version of the function with a configured destructor is
120434   ** being replaced invoke the destructor function here. */
120435   functionDestroy(db, p);
120436 
120437   if( pDestructor ){
120438     pDestructor->nRef++;
120439   }
120440   p->pDestructor = pDestructor;
120441   p->funcFlags &= SQLITE_FUNC_ENCMASK;
120442   p->xFunc = xFunc;
120443   p->xStep = xStep;
120444   p->xFinalize = xFinal;
120445   p->pUserData = pUserData;
120446   p->nArg = (u16)nArg;
120447   return SQLITE_OK;
120448 }
120449 
120450 /*
120451 ** Create new user functions.
120452 */
120453 SQLITE_API int sqlite3_create_function(
120454   sqlite3 *db,
120455   const char *zFunc,
120456   int nArg,
120457   int enc,
120458   void *p,
120459   void (*xFunc)(sqlite3_context*,int,sqlite3_value **),
120460   void (*xStep)(sqlite3_context*,int,sqlite3_value **),
120461   void (*xFinal)(sqlite3_context*)
120462 ){
120463   return sqlite3_create_function_v2(db, zFunc, nArg, enc, p, xFunc, xStep,
120464                                     xFinal, 0);
120465 }
120466 
120467 SQLITE_API int sqlite3_create_function_v2(
120468   sqlite3 *db,
120469   const char *zFunc,
120470   int nArg,
120471   int enc,
120472   void *p,
120473   void (*xFunc)(sqlite3_context*,int,sqlite3_value **),
120474   void (*xStep)(sqlite3_context*,int,sqlite3_value **),
120475   void (*xFinal)(sqlite3_context*),
120476   void (*xDestroy)(void *)
120477 ){
120478   int rc = SQLITE_ERROR;
120479   FuncDestructor *pArg = 0;
120480   sqlite3_mutex_enter(db->mutex);
120481   if( xDestroy ){
120482     pArg = (FuncDestructor *)sqlite3DbMallocZero(db, sizeof(FuncDestructor));
120483     if( !pArg ){
120484       xDestroy(p);
120485       goto out;
120486     }
120487     pArg->xDestroy = xDestroy;
120488     pArg->pUserData = p;
120489   }
120490   rc = sqlite3CreateFunc(db, zFunc, nArg, enc, p, xFunc, xStep, xFinal, pArg);
120491   if( pArg && pArg->nRef==0 ){
120492     assert( rc!=SQLITE_OK );
120493     xDestroy(p);
120494     sqlite3DbFree(db, pArg);
120495   }
120496 
120497  out:
120498   rc = sqlite3ApiExit(db, rc);
120499   sqlite3_mutex_leave(db->mutex);
120500   return rc;
120501 }
120502 
120503 #ifndef SQLITE_OMIT_UTF16
120504 SQLITE_API int sqlite3_create_function16(
120505   sqlite3 *db,
120506   const void *zFunctionName,
120507   int nArg,
120508   int eTextRep,
120509   void *p,
120510   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
120511   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
120512   void (*xFinal)(sqlite3_context*)
120513 ){
120514   int rc;
120515   char *zFunc8;
120516   sqlite3_mutex_enter(db->mutex);
120517   assert( !db->mallocFailed );
120518   zFunc8 = sqlite3Utf16to8(db, zFunctionName, -1, SQLITE_UTF16NATIVE);
120519   rc = sqlite3CreateFunc(db, zFunc8, nArg, eTextRep, p, xFunc, xStep, xFinal,0);
120520   sqlite3DbFree(db, zFunc8);
120521   rc = sqlite3ApiExit(db, rc);
120522   sqlite3_mutex_leave(db->mutex);
120523   return rc;
120524 }
120525 #endif
120526 
120527 
120528 /*
120529 ** Declare that a function has been overloaded by a virtual table.
120530 **
120531 ** If the function already exists as a regular global function, then
120532 ** this routine is a no-op.  If the function does not exist, then create
120533 ** a new one that always throws a run-time error.  
120534 **
120535 ** When virtual tables intend to provide an overloaded function, they
120536 ** should call this routine to make sure the global function exists.
120537 ** A global function must exist in order for name resolution to work
120538 ** properly.
120539 */
120540 SQLITE_API int sqlite3_overload_function(
120541   sqlite3 *db,
120542   const char *zName,
120543   int nArg
120544 ){
120545   int nName = sqlite3Strlen30(zName);
120546   int rc = SQLITE_OK;
120547   sqlite3_mutex_enter(db->mutex);
120548   if( sqlite3FindFunction(db, zName, nName, nArg, SQLITE_UTF8, 0)==0 ){
120549     rc = sqlite3CreateFunc(db, zName, nArg, SQLITE_UTF8,
120550                            0, sqlite3InvalidFunction, 0, 0, 0);
120551   }
120552   rc = sqlite3ApiExit(db, rc);
120553   sqlite3_mutex_leave(db->mutex);
120554   return rc;
120555 }
120556 
120557 #ifndef SQLITE_OMIT_TRACE
120558 /*
120559 ** Register a trace function.  The pArg from the previously registered trace
120560 ** is returned.  
120561 **
120562 ** A NULL trace function means that no tracing is executes.  A non-NULL
120563 ** trace is a pointer to a function that is invoked at the start of each
120564 ** SQL statement.
120565 */
120566 SQLITE_API void *sqlite3_trace(sqlite3 *db, void (*xTrace)(void*,const char*), void *pArg){
120567   void *pOld;
120568   sqlite3_mutex_enter(db->mutex);
120569   pOld = db->pTraceArg;
120570   db->xTrace = xTrace;
120571   db->pTraceArg = pArg;
120572   sqlite3_mutex_leave(db->mutex);
120573   return pOld;
120574 }
120575 /*
120576 ** Register a profile function.  The pArg from the previously registered 
120577 ** profile function is returned.  
120578 **
120579 ** A NULL profile function means that no profiling is executes.  A non-NULL
120580 ** profile is a pointer to a function that is invoked at the conclusion of
120581 ** each SQL statement that is run.
120582 */
120583 SQLITE_API void *sqlite3_profile(
120584   sqlite3 *db,
120585   void (*xProfile)(void*,const char*,sqlite_uint64),
120586   void *pArg
120587 ){
120588   void *pOld;
120589   sqlite3_mutex_enter(db->mutex);
120590   pOld = db->pProfileArg;
120591   db->xProfile = xProfile;
120592   db->pProfileArg = pArg;
120593   sqlite3_mutex_leave(db->mutex);
120594   return pOld;
120595 }
120596 #endif /* SQLITE_OMIT_TRACE */
120597 
120598 /*
120599 ** Register a function to be invoked when a transaction commits.
120600 ** If the invoked function returns non-zero, then the commit becomes a
120601 ** rollback.
120602 */
120603 SQLITE_API void *sqlite3_commit_hook(
120604   sqlite3 *db,              /* Attach the hook to this database */
120605   int (*xCallback)(void*),  /* Function to invoke on each commit */
120606   void *pArg                /* Argument to the function */
120607 ){
120608   void *pOld;
120609   sqlite3_mutex_enter(db->mutex);
120610   pOld = db->pCommitArg;
120611   db->xCommitCallback = xCallback;
120612   db->pCommitArg = pArg;
120613   sqlite3_mutex_leave(db->mutex);
120614   return pOld;
120615 }
120616 
120617 /*
120618 ** Register a callback to be invoked each time a row is updated,
120619 ** inserted or deleted using this database connection.
120620 */
120621 SQLITE_API void *sqlite3_update_hook(
120622   sqlite3 *db,              /* Attach the hook to this database */
120623   void (*xCallback)(void*,int,char const *,char const *,sqlite_int64),
120624   void *pArg                /* Argument to the function */
120625 ){
120626   void *pRet;
120627   sqlite3_mutex_enter(db->mutex);
120628   pRet = db->pUpdateArg;
120629   db->xUpdateCallback = xCallback;
120630   db->pUpdateArg = pArg;
120631   sqlite3_mutex_leave(db->mutex);
120632   return pRet;
120633 }
120634 
120635 /*
120636 ** Register a callback to be invoked each time a transaction is rolled
120637 ** back by this database connection.
120638 */
120639 SQLITE_API void *sqlite3_rollback_hook(
120640   sqlite3 *db,              /* Attach the hook to this database */
120641   void (*xCallback)(void*), /* Callback function */
120642   void *pArg                /* Argument to the function */
120643 ){
120644   void *pRet;
120645   sqlite3_mutex_enter(db->mutex);
120646   pRet = db->pRollbackArg;
120647   db->xRollbackCallback = xCallback;
120648   db->pRollbackArg = pArg;
120649   sqlite3_mutex_leave(db->mutex);
120650   return pRet;
120651 }
120652 
120653 #ifndef SQLITE_OMIT_WAL
120654 /*
120655 ** The sqlite3_wal_hook() callback registered by sqlite3_wal_autocheckpoint().
120656 ** Invoke sqlite3_wal_checkpoint if the number of frames in the log file
120657 ** is greater than sqlite3.pWalArg cast to an integer (the value configured by
120658 ** wal_autocheckpoint()).
120659 */ 
120660 SQLITE_PRIVATE int sqlite3WalDefaultHook(
120661   void *pClientData,     /* Argument */
120662   sqlite3 *db,           /* Connection */
120663   const char *zDb,       /* Database */
120664   int nFrame             /* Size of WAL */
120665 ){
120666   if( nFrame>=SQLITE_PTR_TO_INT(pClientData) ){
120667     sqlite3BeginBenignMalloc();
120668     sqlite3_wal_checkpoint(db, zDb);
120669     sqlite3EndBenignMalloc();
120670   }
120671   return SQLITE_OK;
120672 }
120673 #endif /* SQLITE_OMIT_WAL */
120674 
120675 /*
120676 ** Configure an sqlite3_wal_hook() callback to automatically checkpoint
120677 ** a database after committing a transaction if there are nFrame or
120678 ** more frames in the log file. Passing zero or a negative value as the
120679 ** nFrame parameter disables automatic checkpoints entirely.
120680 **
120681 ** The callback registered by this function replaces any existing callback
120682 ** registered using sqlite3_wal_hook(). Likewise, registering a callback
120683 ** using sqlite3_wal_hook() disables the automatic checkpoint mechanism
120684 ** configured by this function.
120685 */
120686 SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int nFrame){
120687 #ifdef SQLITE_OMIT_WAL
120688   UNUSED_PARAMETER(db);
120689   UNUSED_PARAMETER(nFrame);
120690 #else
120691   if( nFrame>0 ){
120692     sqlite3_wal_hook(db, sqlite3WalDefaultHook, SQLITE_INT_TO_PTR(nFrame));
120693   }else{
120694     sqlite3_wal_hook(db, 0, 0);
120695   }
120696 #endif
120697   return SQLITE_OK;
120698 }
120699 
120700 /*
120701 ** Register a callback to be invoked each time a transaction is written
120702 ** into the write-ahead-log by this database connection.
120703 */
120704 SQLITE_API void *sqlite3_wal_hook(
120705   sqlite3 *db,                    /* Attach the hook to this db handle */
120706   int(*xCallback)(void *, sqlite3*, const char*, int),
120707   void *pArg                      /* First argument passed to xCallback() */
120708 ){
120709 #ifndef SQLITE_OMIT_WAL
120710   void *pRet;
120711   sqlite3_mutex_enter(db->mutex);
120712   pRet = db->pWalArg;
120713   db->xWalCallback = xCallback;
120714   db->pWalArg = pArg;
120715   sqlite3_mutex_leave(db->mutex);
120716   return pRet;
120717 #else
120718   return 0;
120719 #endif
120720 }
120721 
120722 /*
120723 ** Checkpoint database zDb.
120724 */
120725 SQLITE_API int sqlite3_wal_checkpoint_v2(
120726   sqlite3 *db,                    /* Database handle */
120727   const char *zDb,                /* Name of attached database (or NULL) */
120728   int eMode,                      /* SQLITE_CHECKPOINT_* value */
120729   int *pnLog,                     /* OUT: Size of WAL log in frames */
120730   int *pnCkpt                     /* OUT: Total number of frames checkpointed */
120731 ){
120732 #ifdef SQLITE_OMIT_WAL
120733   return SQLITE_OK;
120734 #else
120735   int rc;                         /* Return code */
120736   int iDb = SQLITE_MAX_ATTACHED;  /* sqlite3.aDb[] index of db to checkpoint */
120737 
120738   /* Initialize the output variables to -1 in case an error occurs. */
120739   if( pnLog ) *pnLog = -1;
120740   if( pnCkpt ) *pnCkpt = -1;
120741 
120742   assert( SQLITE_CHECKPOINT_FULL>SQLITE_CHECKPOINT_PASSIVE );
120743   assert( SQLITE_CHECKPOINT_FULL<SQLITE_CHECKPOINT_RESTART );
120744   assert( SQLITE_CHECKPOINT_PASSIVE+2==SQLITE_CHECKPOINT_RESTART );
120745   if( eMode<SQLITE_CHECKPOINT_PASSIVE || eMode>SQLITE_CHECKPOINT_RESTART ){
120746     return SQLITE_MISUSE;
120747   }
120748 
120749   sqlite3_mutex_enter(db->mutex);
120750   if( zDb && zDb[0] ){
120751     iDb = sqlite3FindDbName(db, zDb);
120752   }
120753   if( iDb<0 ){
120754     rc = SQLITE_ERROR;
120755     sqlite3Error(db, SQLITE_ERROR, "unknown database: %s", zDb);
120756   }else{
120757     rc = sqlite3Checkpoint(db, iDb, eMode, pnLog, pnCkpt);
120758     sqlite3Error(db, rc, 0);
120759   }
120760   rc = sqlite3ApiExit(db, rc);
120761   sqlite3_mutex_leave(db->mutex);
120762   return rc;
120763 #endif
120764 }
120765 
120766 
120767 /*
120768 ** Checkpoint database zDb. If zDb is NULL, or if the buffer zDb points
120769 ** to contains a zero-length string, all attached databases are 
120770 ** checkpointed.
120771 */
120772 SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb){
120773   return sqlite3_wal_checkpoint_v2(db, zDb, SQLITE_CHECKPOINT_PASSIVE, 0, 0);
120774 }
120775 
120776 #ifndef SQLITE_OMIT_WAL
120777 /*
120778 ** Run a checkpoint on database iDb. This is a no-op if database iDb is
120779 ** not currently open in WAL mode.
120780 **
120781 ** If a transaction is open on the database being checkpointed, this 
120782 ** function returns SQLITE_LOCKED and a checkpoint is not attempted. If 
120783 ** an error occurs while running the checkpoint, an SQLite error code is 
120784 ** returned (i.e. SQLITE_IOERR). Otherwise, SQLITE_OK.
120785 **
120786 ** The mutex on database handle db should be held by the caller. The mutex
120787 ** associated with the specific b-tree being checkpointed is taken by
120788 ** this function while the checkpoint is running.
120789 **
120790 ** If iDb is passed SQLITE_MAX_ATTACHED, then all attached databases are
120791 ** checkpointed. If an error is encountered it is returned immediately -
120792 ** no attempt is made to checkpoint any remaining databases.
120793 **
120794 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
120795 */
120796 SQLITE_PRIVATE int sqlite3Checkpoint(sqlite3 *db, int iDb, int eMode, int *pnLog, int *pnCkpt){
120797   int rc = SQLITE_OK;             /* Return code */
120798   int i;                          /* Used to iterate through attached dbs */
120799   int bBusy = 0;                  /* True if SQLITE_BUSY has been encountered */
120800 
120801   assert( sqlite3_mutex_held(db->mutex) );
120802   assert( !pnLog || *pnLog==-1 );
120803   assert( !pnCkpt || *pnCkpt==-1 );
120804 
120805   for(i=0; i<db->nDb && rc==SQLITE_OK; i++){
120806     if( i==iDb || iDb==SQLITE_MAX_ATTACHED ){
120807       rc = sqlite3BtreeCheckpoint(db->aDb[i].pBt, eMode, pnLog, pnCkpt);
120808       pnLog = 0;
120809       pnCkpt = 0;
120810       if( rc==SQLITE_BUSY ){
120811         bBusy = 1;
120812         rc = SQLITE_OK;
120813       }
120814     }
120815   }
120816 
120817   return (rc==SQLITE_OK && bBusy) ? SQLITE_BUSY : rc;
120818 }
120819 #endif /* SQLITE_OMIT_WAL */
120820 
120821 /*
120822 ** This function returns true if main-memory should be used instead of
120823 ** a temporary file for transient pager files and statement journals.
120824 ** The value returned depends on the value of db->temp_store (runtime
120825 ** parameter) and the compile time value of SQLITE_TEMP_STORE. The
120826 ** following table describes the relationship between these two values
120827 ** and this functions return value.
120828 **
120829 **   SQLITE_TEMP_STORE     db->temp_store     Location of temporary database
120830 **   -----------------     --------------     ------------------------------
120831 **   0                     any                file      (return 0)
120832 **   1                     1                  file      (return 0)
120833 **   1                     2                  memory    (return 1)
120834 **   1                     0                  file      (return 0)
120835 **   2                     1                  file      (return 0)
120836 **   2                     2                  memory    (return 1)
120837 **   2                     0                  memory    (return 1)
120838 **   3                     any                memory    (return 1)
120839 */
120840 SQLITE_PRIVATE int sqlite3TempInMemory(const sqlite3 *db){
120841 #if SQLITE_TEMP_STORE==1
120842   return ( db->temp_store==2 );
120843 #endif
120844 #if SQLITE_TEMP_STORE==2
120845   return ( db->temp_store!=1 );
120846 #endif
120847 #if SQLITE_TEMP_STORE==3
120848   return 1;
120849 #endif
120850 #if SQLITE_TEMP_STORE<1 || SQLITE_TEMP_STORE>3
120851   return 0;
120852 #endif
120853 }
120854 
120855 /*
120856 ** Return UTF-8 encoded English language explanation of the most recent
120857 ** error.
120858 */
120859 SQLITE_API const char *sqlite3_errmsg(sqlite3 *db){
120860   const char *z;
120861   if( !db ){
120862     return sqlite3ErrStr(SQLITE_NOMEM);
120863   }
120864   if( !sqlite3SafetyCheckSickOrOk(db) ){
120865     return sqlite3ErrStr(SQLITE_MISUSE_BKPT);
120866   }
120867   sqlite3_mutex_enter(db->mutex);
120868   if( db->mallocFailed ){
120869     z = sqlite3ErrStr(SQLITE_NOMEM);
120870   }else{
120871     z = (char*)sqlite3_value_text(db->pErr);
120872     assert( !db->mallocFailed );
120873     if( z==0 ){
120874       z = sqlite3ErrStr(db->errCode);
120875     }
120876   }
120877   sqlite3_mutex_leave(db->mutex);
120878   return z;
120879 }
120880 
120881 #ifndef SQLITE_OMIT_UTF16
120882 /*
120883 ** Return UTF-16 encoded English language explanation of the most recent
120884 ** error.
120885 */
120886 SQLITE_API const void *sqlite3_errmsg16(sqlite3 *db){
120887   static const u16 outOfMem[] = {
120888     'o', 'u', 't', ' ', 'o', 'f', ' ', 'm', 'e', 'm', 'o', 'r', 'y', 0
120889   };
120890   static const u16 misuse[] = {
120891     'l', 'i', 'b', 'r', 'a', 'r', 'y', ' ', 
120892     'r', 'o', 'u', 't', 'i', 'n', 'e', ' ', 
120893     'c', 'a', 'l', 'l', 'e', 'd', ' ', 
120894     'o', 'u', 't', ' ', 
120895     'o', 'f', ' ', 
120896     's', 'e', 'q', 'u', 'e', 'n', 'c', 'e', 0
120897   };
120898 
120899   const void *z;
120900   if( !db ){
120901     return (void *)outOfMem;
120902   }
120903   if( !sqlite3SafetyCheckSickOrOk(db) ){
120904     return (void *)misuse;
120905   }
120906   sqlite3_mutex_enter(db->mutex);
120907   if( db->mallocFailed ){
120908     z = (void *)outOfMem;
120909   }else{
120910     z = sqlite3_value_text16(db->pErr);
120911     if( z==0 ){
120912       sqlite3ValueSetStr(db->pErr, -1, sqlite3ErrStr(db->errCode),
120913            SQLITE_UTF8, SQLITE_STATIC);
120914       z = sqlite3_value_text16(db->pErr);
120915     }
120916     /* A malloc() may have failed within the call to sqlite3_value_text16()
120917     ** above. If this is the case, then the db->mallocFailed flag needs to
120918     ** be cleared before returning. Do this directly, instead of via
120919     ** sqlite3ApiExit(), to avoid setting the database handle error message.
120920     */
120921     db->mallocFailed = 0;
120922   }
120923   sqlite3_mutex_leave(db->mutex);
120924   return z;
120925 }
120926 #endif /* SQLITE_OMIT_UTF16 */
120927 
120928 /*
120929 ** Return the most recent error code generated by an SQLite routine. If NULL is
120930 ** passed to this function, we assume a malloc() failed during sqlite3_open().
120931 */
120932 SQLITE_API int sqlite3_errcode(sqlite3 *db){
120933   if( db && !sqlite3SafetyCheckSickOrOk(db) ){
120934     return SQLITE_MISUSE_BKPT;
120935   }
120936   if( !db || db->mallocFailed ){
120937     return SQLITE_NOMEM;
120938   }
120939   return db->errCode & db->errMask;
120940 }
120941 SQLITE_API int sqlite3_extended_errcode(sqlite3 *db){
120942   if( db && !sqlite3SafetyCheckSickOrOk(db) ){
120943     return SQLITE_MISUSE_BKPT;
120944   }
120945   if( !db || db->mallocFailed ){
120946     return SQLITE_NOMEM;
120947   }
120948   return db->errCode;
120949 }
120950 
120951 /*
120952 ** Return a string that describes the kind of error specified in the
120953 ** argument.  For now, this simply calls the internal sqlite3ErrStr()
120954 ** function.
120955 */
120956 SQLITE_API const char *sqlite3_errstr(int rc){
120957   return sqlite3ErrStr(rc);
120958 }
120959 
120960 /*
120961 ** Invalidate all cached KeyInfo objects for database connection "db"
120962 */
120963 static void invalidateCachedKeyInfo(sqlite3 *db){
120964   Db *pDb;                    /* A single database */
120965   int iDb;                    /* The database index number */
120966   HashElem *k;                /* For looping over tables in pDb */
120967   Table *pTab;                /* A table in the database */
120968   Index *pIdx;                /* Each index */
120969 
120970   for(iDb=0, pDb=db->aDb; iDb<db->nDb; iDb++, pDb++){
120971     if( pDb->pBt==0 ) continue;
120972     sqlite3BtreeEnter(pDb->pBt);
120973     for(k=sqliteHashFirst(&pDb->pSchema->tblHash);  k; k=sqliteHashNext(k)){
120974       pTab = (Table*)sqliteHashData(k);
120975       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
120976         if( pIdx->pKeyInfo && pIdx->pKeyInfo->db==db ){
120977           sqlite3KeyInfoUnref(pIdx->pKeyInfo);
120978           pIdx->pKeyInfo = 0;
120979         }
120980       }
120981     }
120982     sqlite3BtreeLeave(pDb->pBt);
120983   }
120984 }
120985 
120986 /*
120987 ** Create a new collating function for database "db".  The name is zName
120988 ** and the encoding is enc.
120989 */
120990 static int createCollation(
120991   sqlite3* db,
120992   const char *zName, 
120993   u8 enc,
120994   void* pCtx,
120995   int(*xCompare)(void*,int,const void*,int,const void*),
120996   void(*xDel)(void*)
120997 ){
120998   CollSeq *pColl;
120999   int enc2;
121000   int nName = sqlite3Strlen30(zName);
121001   
121002   assert( sqlite3_mutex_held(db->mutex) );
121003 
121004   /* If SQLITE_UTF16 is specified as the encoding type, transform this
121005   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the
121006   ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
121007   */
121008   enc2 = enc;
121009   testcase( enc2==SQLITE_UTF16 );
121010   testcase( enc2==SQLITE_UTF16_ALIGNED );
121011   if( enc2==SQLITE_UTF16 || enc2==SQLITE_UTF16_ALIGNED ){
121012     enc2 = SQLITE_UTF16NATIVE;
121013   }
121014   if( enc2<SQLITE_UTF8 || enc2>SQLITE_UTF16BE ){
121015     return SQLITE_MISUSE_BKPT;
121016   }
121017 
121018   /* Check if this call is removing or replacing an existing collation 
121019   ** sequence. If so, and there are active VMs, return busy. If there
121020   ** are no active VMs, invalidate any pre-compiled statements.
121021   */
121022   pColl = sqlite3FindCollSeq(db, (u8)enc2, zName, 0);
121023   if( pColl && pColl->xCmp ){
121024     if( db->nVdbeActive ){
121025       sqlite3Error(db, SQLITE_BUSY, 
121026         "unable to delete/modify collation sequence due to active statements");
121027       return SQLITE_BUSY;
121028     }
121029     sqlite3ExpirePreparedStatements(db);
121030     invalidateCachedKeyInfo(db);
121031 
121032     /* If collation sequence pColl was created directly by a call to
121033     ** sqlite3_create_collation, and not generated by synthCollSeq(),
121034     ** then any copies made by synthCollSeq() need to be invalidated.
121035     ** Also, collation destructor - CollSeq.xDel() - function may need
121036     ** to be called.
121037     */ 
121038     if( (pColl->enc & ~SQLITE_UTF16_ALIGNED)==enc2 ){
121039       CollSeq *aColl = sqlite3HashFind(&db->aCollSeq, zName, nName);
121040       int j;
121041       for(j=0; j<3; j++){
121042         CollSeq *p = &aColl[j];
121043         if( p->enc==pColl->enc ){
121044           if( p->xDel ){
121045             p->xDel(p->pUser);
121046           }
121047           p->xCmp = 0;
121048         }
121049       }
121050     }
121051   }
121052 
121053   pColl = sqlite3FindCollSeq(db, (u8)enc2, zName, 1);
121054   if( pColl==0 ) return SQLITE_NOMEM;
121055   pColl->xCmp = xCompare;
121056   pColl->pUser = pCtx;
121057   pColl->xDel = xDel;
121058   pColl->enc = (u8)(enc2 | (enc & SQLITE_UTF16_ALIGNED));
121059   sqlite3Error(db, SQLITE_OK, 0);
121060   return SQLITE_OK;
121061 }
121062 
121063 
121064 /*
121065 ** This array defines hard upper bounds on limit values.  The
121066 ** initializer must be kept in sync with the SQLITE_LIMIT_*
121067 ** #defines in sqlite3.h.
121068 */
121069 static const int aHardLimit[] = {
121070   SQLITE_MAX_LENGTH,
121071   SQLITE_MAX_SQL_LENGTH,
121072   SQLITE_MAX_COLUMN,
121073   SQLITE_MAX_EXPR_DEPTH,
121074   SQLITE_MAX_COMPOUND_SELECT,
121075   SQLITE_MAX_VDBE_OP,
121076   SQLITE_MAX_FUNCTION_ARG,
121077   SQLITE_MAX_ATTACHED,
121078   SQLITE_MAX_LIKE_PATTERN_LENGTH,
121079   SQLITE_MAX_VARIABLE_NUMBER,
121080   SQLITE_MAX_TRIGGER_DEPTH,
121081 };
121082 
121083 /*
121084 ** Make sure the hard limits are set to reasonable values
121085 */
121086 #if SQLITE_MAX_LENGTH<100
121087 # error SQLITE_MAX_LENGTH must be at least 100
121088 #endif
121089 #if SQLITE_MAX_SQL_LENGTH<100
121090 # error SQLITE_MAX_SQL_LENGTH must be at least 100
121091 #endif
121092 #if SQLITE_MAX_SQL_LENGTH>SQLITE_MAX_LENGTH
121093 # error SQLITE_MAX_SQL_LENGTH must not be greater than SQLITE_MAX_LENGTH
121094 #endif
121095 #if SQLITE_MAX_COMPOUND_SELECT<2
121096 # error SQLITE_MAX_COMPOUND_SELECT must be at least 2
121097 #endif
121098 #if SQLITE_MAX_VDBE_OP<40
121099 # error SQLITE_MAX_VDBE_OP must be at least 40
121100 #endif
121101 #if SQLITE_MAX_FUNCTION_ARG<0 || SQLITE_MAX_FUNCTION_ARG>1000
121102 # error SQLITE_MAX_FUNCTION_ARG must be between 0 and 1000
121103 #endif
121104 #if SQLITE_MAX_ATTACHED<0 || SQLITE_MAX_ATTACHED>62
121105 # error SQLITE_MAX_ATTACHED must be between 0 and 62
121106 #endif
121107 #if SQLITE_MAX_LIKE_PATTERN_LENGTH<1
121108 # error SQLITE_MAX_LIKE_PATTERN_LENGTH must be at least 1
121109 #endif
121110 #if SQLITE_MAX_COLUMN>32767
121111 # error SQLITE_MAX_COLUMN must not exceed 32767
121112 #endif
121113 #if SQLITE_MAX_TRIGGER_DEPTH<1
121114 # error SQLITE_MAX_TRIGGER_DEPTH must be at least 1
121115 #endif
121116 
121117 
121118 /*
121119 ** Change the value of a limit.  Report the old value.
121120 ** If an invalid limit index is supplied, report -1.
121121 ** Make no changes but still report the old value if the
121122 ** new limit is negative.
121123 **
121124 ** A new lower limit does not shrink existing constructs.
121125 ** It merely prevents new constructs that exceed the limit
121126 ** from forming.
121127 */
121128 SQLITE_API int sqlite3_limit(sqlite3 *db, int limitId, int newLimit){
121129   int oldLimit;
121130 
121131 
121132   /* EVIDENCE-OF: R-30189-54097 For each limit category SQLITE_LIMIT_NAME
121133   ** there is a hard upper bound set at compile-time by a C preprocessor
121134   ** macro called SQLITE_MAX_NAME. (The "_LIMIT_" in the name is changed to
121135   ** "_MAX_".)
121136   */
121137   assert( aHardLimit[SQLITE_LIMIT_LENGTH]==SQLITE_MAX_LENGTH );
121138   assert( aHardLimit[SQLITE_LIMIT_SQL_LENGTH]==SQLITE_MAX_SQL_LENGTH );
121139   assert( aHardLimit[SQLITE_LIMIT_COLUMN]==SQLITE_MAX_COLUMN );
121140   assert( aHardLimit[SQLITE_LIMIT_EXPR_DEPTH]==SQLITE_MAX_EXPR_DEPTH );
121141   assert( aHardLimit[SQLITE_LIMIT_COMPOUND_SELECT]==SQLITE_MAX_COMPOUND_SELECT);
121142   assert( aHardLimit[SQLITE_LIMIT_VDBE_OP]==SQLITE_MAX_VDBE_OP );
121143   assert( aHardLimit[SQLITE_LIMIT_FUNCTION_ARG]==SQLITE_MAX_FUNCTION_ARG );
121144   assert( aHardLimit[SQLITE_LIMIT_ATTACHED]==SQLITE_MAX_ATTACHED );
121145   assert( aHardLimit[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]==
121146                                                SQLITE_MAX_LIKE_PATTERN_LENGTH );
121147   assert( aHardLimit[SQLITE_LIMIT_VARIABLE_NUMBER]==SQLITE_MAX_VARIABLE_NUMBER);
121148   assert( aHardLimit[SQLITE_LIMIT_TRIGGER_DEPTH]==SQLITE_MAX_TRIGGER_DEPTH );
121149   assert( SQLITE_LIMIT_TRIGGER_DEPTH==(SQLITE_N_LIMIT-1) );
121150 
121151 
121152   if( limitId<0 || limitId>=SQLITE_N_LIMIT ){
121153     return -1;
121154   }
121155   oldLimit = db->aLimit[limitId];
121156   if( newLimit>=0 ){                   /* IMP: R-52476-28732 */
121157     if( newLimit>aHardLimit[limitId] ){
121158       newLimit = aHardLimit[limitId];  /* IMP: R-51463-25634 */
121159     }
121160     db->aLimit[limitId] = newLimit;
121161   }
121162   return oldLimit;                     /* IMP: R-53341-35419 */
121163 }
121164 
121165 /*
121166 ** This function is used to parse both URIs and non-URI filenames passed by the
121167 ** user to API functions sqlite3_open() or sqlite3_open_v2(), and for database
121168 ** URIs specified as part of ATTACH statements.
121169 **
121170 ** The first argument to this function is the name of the VFS to use (or
121171 ** a NULL to signify the default VFS) if the URI does not contain a "vfs=xxx"
121172 ** query parameter. The second argument contains the URI (or non-URI filename)
121173 ** itself. When this function is called the *pFlags variable should contain
121174 ** the default flags to open the database handle with. The value stored in
121175 ** *pFlags may be updated before returning if the URI filename contains 
121176 ** "cache=xxx" or "mode=xxx" query parameters.
121177 **
121178 ** If successful, SQLITE_OK is returned. In this case *ppVfs is set to point to
121179 ** the VFS that should be used to open the database file. *pzFile is set to
121180 ** point to a buffer containing the name of the file to open. It is the 
121181 ** responsibility of the caller to eventually call sqlite3_free() to release
121182 ** this buffer.
121183 **
121184 ** If an error occurs, then an SQLite error code is returned and *pzErrMsg
121185 ** may be set to point to a buffer containing an English language error 
121186 ** message. It is the responsibility of the caller to eventually release
121187 ** this buffer by calling sqlite3_free().
121188 */
121189 SQLITE_PRIVATE int sqlite3ParseUri(
121190   const char *zDefaultVfs,        /* VFS to use if no "vfs=xxx" query option */
121191   const char *zUri,               /* Nul-terminated URI to parse */
121192   unsigned int *pFlags,           /* IN/OUT: SQLITE_OPEN_XXX flags */
121193   sqlite3_vfs **ppVfs,            /* OUT: VFS to use */ 
121194   char **pzFile,                  /* OUT: Filename component of URI */
121195   char **pzErrMsg                 /* OUT: Error message (if rc!=SQLITE_OK) */
121196 ){
121197   int rc = SQLITE_OK;
121198   unsigned int flags = *pFlags;
121199   const char *zVfs = zDefaultVfs;
121200   char *zFile;
121201   char c;
121202   int nUri = sqlite3Strlen30(zUri);
121203 
121204   assert( *pzErrMsg==0 );
121205 
121206   if( ((flags & SQLITE_OPEN_URI) || sqlite3GlobalConfig.bOpenUri) 
121207    && nUri>=5 && memcmp(zUri, "file:", 5)==0 
121208   ){
121209     char *zOpt;
121210     int eState;                   /* Parser state when parsing URI */
121211     int iIn;                      /* Input character index */
121212     int iOut = 0;                 /* Output character index */
121213     int nByte = nUri+2;           /* Bytes of space to allocate */
121214 
121215     /* Make sure the SQLITE_OPEN_URI flag is set to indicate to the VFS xOpen 
121216     ** method that there may be extra parameters following the file-name.  */
121217     flags |= SQLITE_OPEN_URI;
121218 
121219     for(iIn=0; iIn<nUri; iIn++) nByte += (zUri[iIn]=='&');
121220     zFile = sqlite3_malloc(nByte);
121221     if( !zFile ) return SQLITE_NOMEM;
121222 
121223     iIn = 5;
121224 #ifndef SQLITE_ALLOW_URI_AUTHORITY
121225     /* Discard the scheme and authority segments of the URI. */
121226     if( zUri[5]=='/' && zUri[6]=='/' ){
121227       iIn = 7;
121228       while( zUri[iIn] && zUri[iIn]!='/' ) iIn++;
121229       if( iIn!=7 && (iIn!=16 || memcmp("localhost", &zUri[7], 9)) ){
121230         *pzErrMsg = sqlite3_mprintf("invalid uri authority: %.*s", 
121231             iIn-7, &zUri[7]);
121232         rc = SQLITE_ERROR;
121233         goto parse_uri_out;
121234       }
121235     }
121236 #endif
121237 
121238     /* Copy the filename and any query parameters into the zFile buffer. 
121239     ** Decode %HH escape codes along the way. 
121240     **
121241     ** Within this loop, variable eState may be set to 0, 1 or 2, depending
121242     ** on the parsing context. As follows:
121243     **
121244     **   0: Parsing file-name.
121245     **   1: Parsing name section of a name=value query parameter.
121246     **   2: Parsing value section of a name=value query parameter.
121247     */
121248     eState = 0;
121249     while( (c = zUri[iIn])!=0 && c!='#' ){
121250       iIn++;
121251       if( c=='%' 
121252        && sqlite3Isxdigit(zUri[iIn]) 
121253        && sqlite3Isxdigit(zUri[iIn+1]) 
121254       ){
121255         int octet = (sqlite3HexToInt(zUri[iIn++]) << 4);
121256         octet += sqlite3HexToInt(zUri[iIn++]);
121257 
121258         assert( octet>=0 && octet<256 );
121259         if( octet==0 ){
121260           /* This branch is taken when "%00" appears within the URI. In this
121261           ** case we ignore all text in the remainder of the path, name or
121262           ** value currently being parsed. So ignore the current character
121263           ** and skip to the next "?", "=" or "&", as appropriate. */
121264           while( (c = zUri[iIn])!=0 && c!='#' 
121265               && (eState!=0 || c!='?')
121266               && (eState!=1 || (c!='=' && c!='&'))
121267               && (eState!=2 || c!='&')
121268           ){
121269             iIn++;
121270           }
121271           continue;
121272         }
121273         c = octet;
121274       }else if( eState==1 && (c=='&' || c=='=') ){
121275         if( zFile[iOut-1]==0 ){
121276           /* An empty option name. Ignore this option altogether. */
121277           while( zUri[iIn] && zUri[iIn]!='#' && zUri[iIn-1]!='&' ) iIn++;
121278           continue;
121279         }
121280         if( c=='&' ){
121281           zFile[iOut++] = '\0';
121282         }else{
121283           eState = 2;
121284         }
121285         c = 0;
121286       }else if( (eState==0 && c=='?') || (eState==2 && c=='&') ){
121287         c = 0;
121288         eState = 1;
121289       }
121290       zFile[iOut++] = c;
121291     }
121292     if( eState==1 ) zFile[iOut++] = '\0';
121293     zFile[iOut++] = '\0';
121294     zFile[iOut++] = '\0';
121295 
121296     /* Check if there were any options specified that should be interpreted 
121297     ** here. Options that are interpreted here include "vfs" and those that
121298     ** correspond to flags that may be passed to the sqlite3_open_v2()
121299     ** method. */
121300     zOpt = &zFile[sqlite3Strlen30(zFile)+1];
121301     while( zOpt[0] ){
121302       int nOpt = sqlite3Strlen30(zOpt);
121303       char *zVal = &zOpt[nOpt+1];
121304       int nVal = sqlite3Strlen30(zVal);
121305 
121306       if( nOpt==3 && memcmp("vfs", zOpt, 3)==0 ){
121307         zVfs = zVal;
121308       }else{
121309         struct OpenMode {
121310           const char *z;
121311           int mode;
121312         } *aMode = 0;
121313         char *zModeType = 0;
121314         int mask = 0;
121315         int limit = 0;
121316 
121317         if( nOpt==5 && memcmp("cache", zOpt, 5)==0 ){
121318           static struct OpenMode aCacheMode[] = {
121319             { "shared",  SQLITE_OPEN_SHAREDCACHE },
121320             { "private", SQLITE_OPEN_PRIVATECACHE },
121321             { 0, 0 }
121322           };
121323 
121324           mask = SQLITE_OPEN_SHAREDCACHE|SQLITE_OPEN_PRIVATECACHE;
121325           aMode = aCacheMode;
121326           limit = mask;
121327           zModeType = "cache";
121328         }
121329         if( nOpt==4 && memcmp("mode", zOpt, 4)==0 ){
121330           static struct OpenMode aOpenMode[] = {
121331             { "ro",  SQLITE_OPEN_READONLY },
121332             { "rw",  SQLITE_OPEN_READWRITE }, 
121333             { "rwc", SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE },
121334             { "memory", SQLITE_OPEN_MEMORY },
121335             { 0, 0 }
121336           };
121337 
121338           mask = SQLITE_OPEN_READONLY | SQLITE_OPEN_READWRITE
121339                    | SQLITE_OPEN_CREATE | SQLITE_OPEN_MEMORY;
121340           aMode = aOpenMode;
121341           limit = mask & flags;
121342           zModeType = "access";
121343         }
121344 
121345         if( aMode ){
121346           int i;
121347           int mode = 0;
121348           for(i=0; aMode[i].z; i++){
121349             const char *z = aMode[i].z;
121350             if( nVal==sqlite3Strlen30(z) && 0==memcmp(zVal, z, nVal) ){
121351               mode = aMode[i].mode;
121352               break;
121353             }
121354           }
121355           if( mode==0 ){
121356             *pzErrMsg = sqlite3_mprintf("no such %s mode: %s", zModeType, zVal);
121357             rc = SQLITE_ERROR;
121358             goto parse_uri_out;
121359           }
121360           if( (mode & ~SQLITE_OPEN_MEMORY)>limit ){
121361             *pzErrMsg = sqlite3_mprintf("%s mode not allowed: %s",
121362                                         zModeType, zVal);
121363             rc = SQLITE_PERM;
121364             goto parse_uri_out;
121365           }
121366           flags = (flags & ~mask) | mode;
121367         }
121368       }
121369 
121370       zOpt = &zVal[nVal+1];
121371     }
121372 
121373   }else{
121374     zFile = sqlite3_malloc(nUri+2);
121375     if( !zFile ) return SQLITE_NOMEM;
121376     memcpy(zFile, zUri, nUri);
121377     zFile[nUri] = '\0';
121378     zFile[nUri+1] = '\0';
121379     flags &= ~SQLITE_OPEN_URI;
121380   }
121381 
121382   *ppVfs = sqlite3_vfs_find(zVfs);
121383   if( *ppVfs==0 ){
121384     *pzErrMsg = sqlite3_mprintf("no such vfs: %s", zVfs);
121385     rc = SQLITE_ERROR;
121386   }
121387  parse_uri_out:
121388   if( rc!=SQLITE_OK ){
121389     sqlite3_free(zFile);
121390     zFile = 0;
121391   }
121392   *pFlags = flags;
121393   *pzFile = zFile;
121394   return rc;
121395 }
121396 
121397 
121398 /*
121399 ** This routine does the work of opening a database on behalf of
121400 ** sqlite3_open() and sqlite3_open16(). The database filename "zFilename"  
121401 ** is UTF-8 encoded.
121402 */
121403 static int openDatabase(
121404   const char *zFilename, /* Database filename UTF-8 encoded */
121405   sqlite3 **ppDb,        /* OUT: Returned database handle */
121406   unsigned int flags,    /* Operational flags */
121407   const char *zVfs       /* Name of the VFS to use */
121408 ){
121409   sqlite3 *db;                    /* Store allocated handle here */
121410   int rc;                         /* Return code */
121411   int isThreadsafe;               /* True for threadsafe connections */
121412   char *zOpen = 0;                /* Filename argument to pass to BtreeOpen() */
121413   char *zErrMsg = 0;              /* Error message from sqlite3ParseUri() */
121414 
121415   *ppDb = 0;
121416 #ifndef SQLITE_OMIT_AUTOINIT
121417   rc = sqlite3_initialize();
121418   if( rc ) return rc;
121419 #endif
121420 
121421   /* Only allow sensible combinations of bits in the flags argument.  
121422   ** Throw an error if any non-sense combination is used.  If we
121423   ** do not block illegal combinations here, it could trigger
121424   ** assert() statements in deeper layers.  Sensible combinations
121425   ** are:
121426   **
121427   **  1:  SQLITE_OPEN_READONLY
121428   **  2:  SQLITE_OPEN_READWRITE
121429   **  6:  SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
121430   */
121431   assert( SQLITE_OPEN_READONLY  == 0x01 );
121432   assert( SQLITE_OPEN_READWRITE == 0x02 );
121433   assert( SQLITE_OPEN_CREATE    == 0x04 );
121434   testcase( (1<<(flags&7))==0x02 ); /* READONLY */
121435   testcase( (1<<(flags&7))==0x04 ); /* READWRITE */
121436   testcase( (1<<(flags&7))==0x40 ); /* READWRITE | CREATE */
121437   if( ((1<<(flags&7)) & 0x46)==0 ) return SQLITE_MISUSE_BKPT;
121438 
121439   if( sqlite3GlobalConfig.bCoreMutex==0 ){
121440     isThreadsafe = 0;
121441   }else if( flags & SQLITE_OPEN_NOMUTEX ){
121442     isThreadsafe = 0;
121443   }else if( flags & SQLITE_OPEN_FULLMUTEX ){
121444     isThreadsafe = 1;
121445   }else{
121446     isThreadsafe = sqlite3GlobalConfig.bFullMutex;
121447   }
121448   if( flags & SQLITE_OPEN_PRIVATECACHE ){
121449     flags &= ~SQLITE_OPEN_SHAREDCACHE;
121450   }else if( sqlite3GlobalConfig.sharedCacheEnabled ){
121451     flags |= SQLITE_OPEN_SHAREDCACHE;
121452   }
121453 
121454   /* Remove harmful bits from the flags parameter
121455   **
121456   ** The SQLITE_OPEN_NOMUTEX and SQLITE_OPEN_FULLMUTEX flags were
121457   ** dealt with in the previous code block.  Besides these, the only
121458   ** valid input flags for sqlite3_open_v2() are SQLITE_OPEN_READONLY,
121459   ** SQLITE_OPEN_READWRITE, SQLITE_OPEN_CREATE, SQLITE_OPEN_SHAREDCACHE,
121460   ** SQLITE_OPEN_PRIVATECACHE, and some reserved bits.  Silently mask
121461   ** off all other flags.
121462   */
121463   flags &=  ~( SQLITE_OPEN_DELETEONCLOSE |
121464                SQLITE_OPEN_EXCLUSIVE |
121465                SQLITE_OPEN_MAIN_DB |
121466                SQLITE_OPEN_TEMP_DB | 
121467                SQLITE_OPEN_TRANSIENT_DB | 
121468                SQLITE_OPEN_MAIN_JOURNAL | 
121469                SQLITE_OPEN_TEMP_JOURNAL | 
121470                SQLITE_OPEN_SUBJOURNAL | 
121471                SQLITE_OPEN_MASTER_JOURNAL |
121472                SQLITE_OPEN_NOMUTEX |
121473                SQLITE_OPEN_FULLMUTEX |
121474                SQLITE_OPEN_WAL
121475              );
121476 
121477   /* Allocate the sqlite data structure */
121478   db = sqlite3MallocZero( sizeof(sqlite3) );
121479   if( db==0 ) goto opendb_out;
121480   if( isThreadsafe ){
121481     db->mutex = sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE);
121482     if( db->mutex==0 ){
121483       sqlite3_free(db);
121484       db = 0;
121485       goto opendb_out;
121486     }
121487   }
121488   sqlite3_mutex_enter(db->mutex);
121489   db->errMask = 0xff;
121490   db->nDb = 2;
121491   db->magic = SQLITE_MAGIC_BUSY;
121492   db->aDb = db->aDbStatic;
121493 
121494   assert( sizeof(db->aLimit)==sizeof(aHardLimit) );
121495   memcpy(db->aLimit, aHardLimit, sizeof(db->aLimit));
121496   db->autoCommit = 1;
121497   db->nextAutovac = -1;
121498   db->szMmap = sqlite3GlobalConfig.szMmap;
121499   db->nextPagesize = 0;
121500   db->flags |= SQLITE_ShortColNames | SQLITE_EnableTrigger | SQLITE_CacheSpill
121501 #if !defined(SQLITE_DEFAULT_AUTOMATIC_INDEX) || SQLITE_DEFAULT_AUTOMATIC_INDEX
121502                  | SQLITE_AutoIndex
121503 #endif
121504 #if SQLITE_DEFAULT_FILE_FORMAT<4
121505                  | SQLITE_LegacyFileFmt
121506 #endif
121507 #ifdef SQLITE_ENABLE_LOAD_EXTENSION
121508                  | SQLITE_LoadExtension
121509 #endif
121510 #if SQLITE_DEFAULT_RECURSIVE_TRIGGERS
121511                  | SQLITE_RecTriggers
121512 #endif
121513 #if defined(SQLITE_DEFAULT_FOREIGN_KEYS) && SQLITE_DEFAULT_FOREIGN_KEYS
121514                  | SQLITE_ForeignKeys
121515 #endif
121516       ;
121517   sqlite3HashInit(&db->aCollSeq);
121518 #ifndef SQLITE_OMIT_VIRTUALTABLE
121519   sqlite3HashInit(&db->aModule);
121520 #endif
121521 
121522   /* Add the default collation sequence BINARY. BINARY works for both UTF-8
121523   ** and UTF-16, so add a version for each to avoid any unnecessary
121524   ** conversions. The only error that can occur here is a malloc() failure.
121525   */
121526   createCollation(db, "BINARY", SQLITE_UTF8, 0, binCollFunc, 0);
121527   createCollation(db, "BINARY", SQLITE_UTF16BE, 0, binCollFunc, 0);
121528   createCollation(db, "BINARY", SQLITE_UTF16LE, 0, binCollFunc, 0);
121529   createCollation(db, "RTRIM", SQLITE_UTF8, (void*)1, binCollFunc, 0);
121530   if( db->mallocFailed ){
121531     goto opendb_out;
121532   }
121533   db->pDfltColl = sqlite3FindCollSeq(db, SQLITE_UTF8, "BINARY", 0);
121534   assert( db->pDfltColl!=0 );
121535 
121536   /* Also add a UTF-8 case-insensitive collation sequence. */
121537   createCollation(db, "NOCASE", SQLITE_UTF8, 0, nocaseCollatingFunc, 0);
121538 
121539   /* Parse the filename/URI argument. */
121540   db->openFlags = flags;
121541   rc = sqlite3ParseUri(zVfs, zFilename, &flags, &db->pVfs, &zOpen, &zErrMsg);
121542   if( rc!=SQLITE_OK ){
121543     if( rc==SQLITE_NOMEM ) db->mallocFailed = 1;
121544     sqlite3Error(db, rc, zErrMsg ? "%s" : 0, zErrMsg);
121545     sqlite3_free(zErrMsg);
121546     goto opendb_out;
121547   }
121548 
121549   /* Open the backend database driver */
121550   rc = sqlite3BtreeOpen(db->pVfs, zOpen, db, &db->aDb[0].pBt, 0,
121551                         flags | SQLITE_OPEN_MAIN_DB);
121552   if( rc!=SQLITE_OK ){
121553     if( rc==SQLITE_IOERR_NOMEM ){
121554       rc = SQLITE_NOMEM;
121555     }
121556     sqlite3Error(db, rc, 0);
121557     goto opendb_out;
121558   }
121559   db->aDb[0].pSchema = sqlite3SchemaGet(db, db->aDb[0].pBt);
121560   db->aDb[1].pSchema = sqlite3SchemaGet(db, 0);
121561 
121562 
121563   /* The default safety_level for the main database is 'full'; for the temp
121564   ** database it is 'NONE'. This matches the pager layer defaults.  
121565   */
121566   db->aDb[0].zName = "main";
121567   db->aDb[0].safety_level = 3;
121568   db->aDb[1].zName = "temp";
121569   db->aDb[1].safety_level = 1;
121570 
121571   db->magic = SQLITE_MAGIC_OPEN;
121572   if( db->mallocFailed ){
121573     goto opendb_out;
121574   }
121575 
121576   /* Register all built-in functions, but do not attempt to read the
121577   ** database schema yet. This is delayed until the first time the database
121578   ** is accessed.
121579   */
121580   sqlite3Error(db, SQLITE_OK, 0);
121581   sqlite3RegisterBuiltinFunctions(db);
121582 
121583   /* Load automatic extensions - extensions that have been registered
121584   ** using the sqlite3_automatic_extension() API.
121585   */
121586   rc = sqlite3_errcode(db);
121587   if( rc==SQLITE_OK ){
121588     sqlite3AutoLoadExtensions(db);
121589     rc = sqlite3_errcode(db);
121590     if( rc!=SQLITE_OK ){
121591       goto opendb_out;
121592     }
121593   }
121594 
121595 #ifdef SQLITE_ENABLE_FTS1
121596   if( !db->mallocFailed ){
121597     extern int sqlite3Fts1Init(sqlite3*);
121598     rc = sqlite3Fts1Init(db);
121599   }
121600 #endif
121601 
121602 #ifdef SQLITE_ENABLE_FTS2
121603   if( !db->mallocFailed && rc==SQLITE_OK ){
121604     extern int sqlite3Fts2Init(sqlite3*);
121605     rc = sqlite3Fts2Init(db);
121606   }
121607 #endif
121608 
121609 #ifdef SQLITE_ENABLE_FTS3
121610   if( !db->mallocFailed && rc==SQLITE_OK ){
121611     rc = sqlite3Fts3Init(db);
121612   }
121613 #endif
121614 
121615 #ifdef SQLITE_ENABLE_ICU
121616   if( !db->mallocFailed && rc==SQLITE_OK ){
121617     rc = sqlite3IcuInit(db);
121618   }
121619 #endif
121620 
121621 #ifdef SQLITE_ENABLE_RTREE
121622   if( !db->mallocFailed && rc==SQLITE_OK){
121623     rc = sqlite3RtreeInit(db);
121624   }
121625 #endif
121626 
121627   sqlite3Error(db, rc, 0);
121628 
121629   /* -DSQLITE_DEFAULT_LOCKING_MODE=1 makes EXCLUSIVE the default locking
121630   ** mode.  -DSQLITE_DEFAULT_LOCKING_MODE=0 make NORMAL the default locking
121631   ** mode.  Doing nothing at all also makes NORMAL the default.
121632   */
121633 #ifdef SQLITE_DEFAULT_LOCKING_MODE
121634   db->dfltLockMode = SQLITE_DEFAULT_LOCKING_MODE;
121635   sqlite3PagerLockingMode(sqlite3BtreePager(db->aDb[0].pBt),
121636                           SQLITE_DEFAULT_LOCKING_MODE);
121637 #endif
121638 
121639   /* Enable the lookaside-malloc subsystem */
121640   setupLookaside(db, 0, sqlite3GlobalConfig.szLookaside,
121641                         sqlite3GlobalConfig.nLookaside);
121642 
121643   sqlite3_wal_autocheckpoint(db, SQLITE_DEFAULT_WAL_AUTOCHECKPOINT);
121644 
121645 opendb_out:
121646   sqlite3_free(zOpen);
121647   if( db ){
121648     assert( db->mutex!=0 || isThreadsafe==0 || sqlite3GlobalConfig.bFullMutex==0 );
121649     sqlite3_mutex_leave(db->mutex);
121650   }
121651   rc = sqlite3_errcode(db);
121652   assert( db!=0 || rc==SQLITE_NOMEM );
121653   if( rc==SQLITE_NOMEM ){
121654     sqlite3_close(db);
121655     db = 0;
121656   }else if( rc!=SQLITE_OK ){
121657     db->magic = SQLITE_MAGIC_SICK;
121658   }
121659   *ppDb = db;
121660 #ifdef SQLITE_ENABLE_SQLLOG
121661   if( sqlite3GlobalConfig.xSqllog ){
121662     /* Opening a db handle. Fourth parameter is passed 0. */
121663     void *pArg = sqlite3GlobalConfig.pSqllogArg;
121664     sqlite3GlobalConfig.xSqllog(pArg, db, zFilename, 0);
121665   }
121666 #endif
121667   return sqlite3ApiExit(0, rc);
121668 }
121669 
121670 /*
121671 ** Open a new database handle.
121672 */
121673 SQLITE_API int sqlite3_open(
121674   const char *zFilename, 
121675   sqlite3 **ppDb 
121676 ){
121677   return openDatabase(zFilename, ppDb,
121678                       SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, 0);
121679 }
121680 SQLITE_API int sqlite3_open_v2(
121681   const char *filename,   /* Database filename (UTF-8) */
121682   sqlite3 **ppDb,         /* OUT: SQLite db handle */
121683   int flags,              /* Flags */
121684   const char *zVfs        /* Name of VFS module to use */
121685 ){
121686   return openDatabase(filename, ppDb, (unsigned int)flags, zVfs);
121687 }
121688 
121689 #ifndef SQLITE_OMIT_UTF16
121690 /*
121691 ** Open a new database handle.
121692 */
121693 SQLITE_API int sqlite3_open16(
121694   const void *zFilename, 
121695   sqlite3 **ppDb
121696 ){
121697   char const *zFilename8;   /* zFilename encoded in UTF-8 instead of UTF-16 */
121698   sqlite3_value *pVal;
121699   int rc;
121700 
121701   assert( zFilename );
121702   assert( ppDb );
121703   *ppDb = 0;
121704 #ifndef SQLITE_OMIT_AUTOINIT
121705   rc = sqlite3_initialize();
121706   if( rc ) return rc;
121707 #endif
121708   pVal = sqlite3ValueNew(0);
121709   sqlite3ValueSetStr(pVal, -1, zFilename, SQLITE_UTF16NATIVE, SQLITE_STATIC);
121710   zFilename8 = sqlite3ValueText(pVal, SQLITE_UTF8);
121711   if( zFilename8 ){
121712     rc = openDatabase(zFilename8, ppDb,
121713                       SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, 0);
121714     assert( *ppDb || rc==SQLITE_NOMEM );
121715     if( rc==SQLITE_OK && !DbHasProperty(*ppDb, 0, DB_SchemaLoaded) ){
121716       ENC(*ppDb) = SQLITE_UTF16NATIVE;
121717     }
121718   }else{
121719     rc = SQLITE_NOMEM;
121720   }
121721   sqlite3ValueFree(pVal);
121722 
121723   return sqlite3ApiExit(0, rc);
121724 }
121725 #endif /* SQLITE_OMIT_UTF16 */
121726 
121727 /*
121728 ** Register a new collation sequence with the database handle db.
121729 */
121730 SQLITE_API int sqlite3_create_collation(
121731   sqlite3* db, 
121732   const char *zName, 
121733   int enc, 
121734   void* pCtx,
121735   int(*xCompare)(void*,int,const void*,int,const void*)
121736 ){
121737   int rc;
121738   sqlite3_mutex_enter(db->mutex);
121739   assert( !db->mallocFailed );
121740   rc = createCollation(db, zName, (u8)enc, pCtx, xCompare, 0);
121741   rc = sqlite3ApiExit(db, rc);
121742   sqlite3_mutex_leave(db->mutex);
121743   return rc;
121744 }
121745 
121746 /*
121747 ** Register a new collation sequence with the database handle db.
121748 */
121749 SQLITE_API int sqlite3_create_collation_v2(
121750   sqlite3* db, 
121751   const char *zName, 
121752   int enc, 
121753   void* pCtx,
121754   int(*xCompare)(void*,int,const void*,int,const void*),
121755   void(*xDel)(void*)
121756 ){
121757   int rc;
121758   sqlite3_mutex_enter(db->mutex);
121759   assert( !db->mallocFailed );
121760   rc = createCollation(db, zName, (u8)enc, pCtx, xCompare, xDel);
121761   rc = sqlite3ApiExit(db, rc);
121762   sqlite3_mutex_leave(db->mutex);
121763   return rc;
121764 }
121765 
121766 #ifndef SQLITE_OMIT_UTF16
121767 /*
121768 ** Register a new collation sequence with the database handle db.
121769 */
121770 SQLITE_API int sqlite3_create_collation16(
121771   sqlite3* db, 
121772   const void *zName,
121773   int enc, 
121774   void* pCtx,
121775   int(*xCompare)(void*,int,const void*,int,const void*)
121776 ){
121777   int rc = SQLITE_OK;
121778   char *zName8;
121779   sqlite3_mutex_enter(db->mutex);
121780   assert( !db->mallocFailed );
121781   zName8 = sqlite3Utf16to8(db, zName, -1, SQLITE_UTF16NATIVE);
121782   if( zName8 ){
121783     rc = createCollation(db, zName8, (u8)enc, pCtx, xCompare, 0);
121784     sqlite3DbFree(db, zName8);
121785   }
121786   rc = sqlite3ApiExit(db, rc);
121787   sqlite3_mutex_leave(db->mutex);
121788   return rc;
121789 }
121790 #endif /* SQLITE_OMIT_UTF16 */
121791 
121792 /*
121793 ** Register a collation sequence factory callback with the database handle
121794 ** db. Replace any previously installed collation sequence factory.
121795 */
121796 SQLITE_API int sqlite3_collation_needed(
121797   sqlite3 *db, 
121798   void *pCollNeededArg, 
121799   void(*xCollNeeded)(void*,sqlite3*,int eTextRep,const char*)
121800 ){
121801   sqlite3_mutex_enter(db->mutex);
121802   db->xCollNeeded = xCollNeeded;
121803   db->xCollNeeded16 = 0;
121804   db->pCollNeededArg = pCollNeededArg;
121805   sqlite3_mutex_leave(db->mutex);
121806   return SQLITE_OK;
121807 }
121808 
121809 #ifndef SQLITE_OMIT_UTF16
121810 /*
121811 ** Register a collation sequence factory callback with the database handle
121812 ** db. Replace any previously installed collation sequence factory.
121813 */
121814 SQLITE_API int sqlite3_collation_needed16(
121815   sqlite3 *db, 
121816   void *pCollNeededArg, 
121817   void(*xCollNeeded16)(void*,sqlite3*,int eTextRep,const void*)
121818 ){
121819   sqlite3_mutex_enter(db->mutex);
121820   db->xCollNeeded = 0;
121821   db->xCollNeeded16 = xCollNeeded16;
121822   db->pCollNeededArg = pCollNeededArg;
121823   sqlite3_mutex_leave(db->mutex);
121824   return SQLITE_OK;
121825 }
121826 #endif /* SQLITE_OMIT_UTF16 */
121827 
121828 #ifndef SQLITE_OMIT_DEPRECATED
121829 /*
121830 ** This function is now an anachronism. It used to be used to recover from a
121831 ** malloc() failure, but SQLite now does this automatically.
121832 */
121833 SQLITE_API int sqlite3_global_recover(void){
121834   return SQLITE_OK;
121835 }
121836 #endif
121837 
121838 /*
121839 ** Test to see whether or not the database connection is in autocommit
121840 ** mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
121841 ** by default.  Autocommit is disabled by a BEGIN statement and reenabled
121842 ** by the next COMMIT or ROLLBACK.
121843 */
121844 SQLITE_API int sqlite3_get_autocommit(sqlite3 *db){
121845   return db->autoCommit;
121846 }
121847 
121848 /*
121849 ** The following routines are subtitutes for constants SQLITE_CORRUPT,
121850 ** SQLITE_MISUSE, SQLITE_CANTOPEN, SQLITE_IOERR and possibly other error
121851 ** constants.  They server two purposes:
121852 **
121853 **   1.  Serve as a convenient place to set a breakpoint in a debugger
121854 **       to detect when version error conditions occurs.
121855 **
121856 **   2.  Invoke sqlite3_log() to provide the source code location where
121857 **       a low-level error is first detected.
121858 */
121859 SQLITE_PRIVATE int sqlite3CorruptError(int lineno){
121860   testcase( sqlite3GlobalConfig.xLog!=0 );
121861   sqlite3_log(SQLITE_CORRUPT,
121862               "database corruption at line %d of [%.10s]",
121863               lineno, 20+sqlite3_sourceid());
121864   return SQLITE_CORRUPT;
121865 }
121866 SQLITE_PRIVATE int sqlite3MisuseError(int lineno){
121867   testcase( sqlite3GlobalConfig.xLog!=0 );
121868   sqlite3_log(SQLITE_MISUSE, 
121869               "misuse at line %d of [%.10s]",
121870               lineno, 20+sqlite3_sourceid());
121871   return SQLITE_MISUSE;
121872 }
121873 SQLITE_PRIVATE int sqlite3CantopenError(int lineno){
121874   testcase( sqlite3GlobalConfig.xLog!=0 );
121875   sqlite3_log(SQLITE_CANTOPEN, 
121876               "cannot open file at line %d of [%.10s]",
121877               lineno, 20+sqlite3_sourceid());
121878   return SQLITE_CANTOPEN;
121879 }
121880 
121881 
121882 #ifndef SQLITE_OMIT_DEPRECATED
121883 /*
121884 ** This is a convenience routine that makes sure that all thread-specific
121885 ** data for this thread has been deallocated.
121886 **
121887 ** SQLite no longer uses thread-specific data so this routine is now a
121888 ** no-op.  It is retained for historical compatibility.
121889 */
121890 SQLITE_API void sqlite3_thread_cleanup(void){
121891 }
121892 #endif
121893 
121894 /*
121895 ** Return meta information about a specific column of a database table.
121896 ** See comment in sqlite3.h (sqlite.h.in) for details.
121897 */
121898 #ifdef SQLITE_ENABLE_COLUMN_METADATA
121899 SQLITE_API int sqlite3_table_column_metadata(
121900   sqlite3 *db,                /* Connection handle */
121901   const char *zDbName,        /* Database name or NULL */
121902   const char *zTableName,     /* Table name */
121903   const char *zColumnName,    /* Column name */
121904   char const **pzDataType,    /* OUTPUT: Declared data type */
121905   char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
121906   int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
121907   int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
121908   int *pAutoinc               /* OUTPUT: True if column is auto-increment */
121909 ){
121910   int rc;
121911   char *zErrMsg = 0;
121912   Table *pTab = 0;
121913   Column *pCol = 0;
121914   int iCol;
121915 
121916   char const *zDataType = 0;
121917   char const *zCollSeq = 0;
121918   int notnull = 0;
121919   int primarykey = 0;
121920   int autoinc = 0;
121921 
121922   /* Ensure the database schema has been loaded */
121923   sqlite3_mutex_enter(db->mutex);
121924   sqlite3BtreeEnterAll(db);
121925   rc = sqlite3Init(db, &zErrMsg);
121926   if( SQLITE_OK!=rc ){
121927     goto error_out;
121928   }
121929 
121930   /* Locate the table in question */
121931   pTab = sqlite3FindTable(db, zTableName, zDbName);
121932   if( !pTab || pTab->pSelect ){
121933     pTab = 0;
121934     goto error_out;
121935   }
121936 
121937   /* Find the column for which info is requested */
121938   if( sqlite3IsRowid(zColumnName) ){
121939     iCol = pTab->iPKey;
121940     if( iCol>=0 ){
121941       pCol = &pTab->aCol[iCol];
121942     }
121943   }else{
121944     for(iCol=0; iCol<pTab->nCol; iCol++){
121945       pCol = &pTab->aCol[iCol];
121946       if( 0==sqlite3StrICmp(pCol->zName, zColumnName) ){
121947         break;
121948       }
121949     }
121950     if( iCol==pTab->nCol ){
121951       pTab = 0;
121952       goto error_out;
121953     }
121954   }
121955 
121956   /* The following block stores the meta information that will be returned
121957   ** to the caller in local variables zDataType, zCollSeq, notnull, primarykey
121958   ** and autoinc. At this point there are two possibilities:
121959   ** 
121960   **     1. The specified column name was rowid", "oid" or "_rowid_" 
121961   **        and there is no explicitly declared IPK column. 
121962   **
121963   **     2. The table is not a view and the column name identified an 
121964   **        explicitly declared column. Copy meta information from *pCol.
121965   */ 
121966   if( pCol ){
121967     zDataType = pCol->zType;
121968     zCollSeq = pCol->zColl;
121969     notnull = pCol->notNull!=0;
121970     primarykey  = (pCol->colFlags & COLFLAG_PRIMKEY)!=0;
121971     autoinc = pTab->iPKey==iCol && (pTab->tabFlags & TF_Autoincrement)!=0;
121972   }else{
121973     zDataType = "INTEGER";
121974     primarykey = 1;
121975   }
121976   if( !zCollSeq ){
121977     zCollSeq = "BINARY";
121978   }
121979 
121980 error_out:
121981   sqlite3BtreeLeaveAll(db);
121982 
121983   /* Whether the function call succeeded or failed, set the output parameters
121984   ** to whatever their local counterparts contain. If an error did occur,
121985   ** this has the effect of zeroing all output parameters.
121986   */
121987   if( pzDataType ) *pzDataType = zDataType;
121988   if( pzCollSeq ) *pzCollSeq = zCollSeq;
121989   if( pNotNull ) *pNotNull = notnull;
121990   if( pPrimaryKey ) *pPrimaryKey = primarykey;
121991   if( pAutoinc ) *pAutoinc = autoinc;
121992 
121993   if( SQLITE_OK==rc && !pTab ){
121994     sqlite3DbFree(db, zErrMsg);
121995     zErrMsg = sqlite3MPrintf(db, "no such table column: %s.%s", zTableName,
121996         zColumnName);
121997     rc = SQLITE_ERROR;
121998   }
121999   sqlite3Error(db, rc, (zErrMsg?"%s":0), zErrMsg);
122000   sqlite3DbFree(db, zErrMsg);
122001   rc = sqlite3ApiExit(db, rc);
122002   sqlite3_mutex_leave(db->mutex);
122003   return rc;
122004 }
122005 #endif
122006 
122007 /*
122008 ** Sleep for a little while.  Return the amount of time slept.
122009 */
122010 SQLITE_API int sqlite3_sleep(int ms){
122011   sqlite3_vfs *pVfs;
122012   int rc;
122013   pVfs = sqlite3_vfs_find(0);
122014   if( pVfs==0 ) return 0;
122015 
122016   /* This function works in milliseconds, but the underlying OsSleep() 
122017   ** API uses microseconds. Hence the 1000's.
122018   */
122019   rc = (sqlite3OsSleep(pVfs, 1000*ms)/1000);
122020   return rc;
122021 }
122022 
122023 /*
122024 ** Enable or disable the extended result codes.
122025 */
122026 SQLITE_API int sqlite3_extended_result_codes(sqlite3 *db, int onoff){
122027   sqlite3_mutex_enter(db->mutex);
122028   db->errMask = onoff ? 0xffffffff : 0xff;
122029   sqlite3_mutex_leave(db->mutex);
122030   return SQLITE_OK;
122031 }
122032 
122033 /*
122034 ** Invoke the xFileControl method on a particular database.
122035 */
122036 SQLITE_API int sqlite3_file_control(sqlite3 *db, const char *zDbName, int op, void *pArg){
122037   int rc = SQLITE_ERROR;
122038   Btree *pBtree;
122039 
122040   sqlite3_mutex_enter(db->mutex);
122041   pBtree = sqlite3DbNameToBtree(db, zDbName);
122042   if( pBtree ){
122043     Pager *pPager;
122044     sqlite3_file *fd;
122045     sqlite3BtreeEnter(pBtree);
122046     pPager = sqlite3BtreePager(pBtree);
122047     assert( pPager!=0 );
122048     fd = sqlite3PagerFile(pPager);
122049     assert( fd!=0 );
122050     if( op==SQLITE_FCNTL_FILE_POINTER ){
122051       *(sqlite3_file**)pArg = fd;
122052       rc = SQLITE_OK;
122053     }else if( fd->pMethods ){
122054       rc = sqlite3OsFileControl(fd, op, pArg);
122055     }else{
122056       rc = SQLITE_NOTFOUND;
122057     }
122058     sqlite3BtreeLeave(pBtree);
122059   }
122060   sqlite3_mutex_leave(db->mutex);
122061   return rc;   
122062 }
122063 
122064 /*
122065 ** Interface to the testing logic.
122066 */
122067 SQLITE_API int sqlite3_test_control(int op, ...){
122068   int rc = 0;
122069 #ifndef SQLITE_OMIT_BUILTIN_TEST
122070   va_list ap;
122071   va_start(ap, op);
122072   switch( op ){
122073 
122074     /*
122075     ** Save the current state of the PRNG.
122076     */
122077     case SQLITE_TESTCTRL_PRNG_SAVE: {
122078       sqlite3PrngSaveState();
122079       break;
122080     }
122081 
122082     /*
122083     ** Restore the state of the PRNG to the last state saved using
122084     ** PRNG_SAVE.  If PRNG_SAVE has never before been called, then
122085     ** this verb acts like PRNG_RESET.
122086     */
122087     case SQLITE_TESTCTRL_PRNG_RESTORE: {
122088       sqlite3PrngRestoreState();
122089       break;
122090     }
122091 
122092     /*
122093     ** Reset the PRNG back to its uninitialized state.  The next call
122094     ** to sqlite3_randomness() will reseed the PRNG using a single call
122095     ** to the xRandomness method of the default VFS.
122096     */
122097     case SQLITE_TESTCTRL_PRNG_RESET: {
122098       sqlite3PrngResetState();
122099       break;
122100     }
122101 
122102     /*
122103     **  sqlite3_test_control(BITVEC_TEST, size, program)
122104     **
122105     ** Run a test against a Bitvec object of size.  The program argument
122106     ** is an array of integers that defines the test.  Return -1 on a
122107     ** memory allocation error, 0 on success, or non-zero for an error.
122108     ** See the sqlite3BitvecBuiltinTest() for additional information.
122109     */
122110     case SQLITE_TESTCTRL_BITVEC_TEST: {
122111       int sz = va_arg(ap, int);
122112       int *aProg = va_arg(ap, int*);
122113       rc = sqlite3BitvecBuiltinTest(sz, aProg);
122114       break;
122115     }
122116 
122117     /*
122118     **  sqlite3_test_control(BENIGN_MALLOC_HOOKS, xBegin, xEnd)
122119     **
122120     ** Register hooks to call to indicate which malloc() failures 
122121     ** are benign.
122122     */
122123     case SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS: {
122124       typedef void (*void_function)(void);
122125       void_function xBenignBegin;
122126       void_function xBenignEnd;
122127       xBenignBegin = va_arg(ap, void_function);
122128       xBenignEnd = va_arg(ap, void_function);
122129       sqlite3BenignMallocHooks(xBenignBegin, xBenignEnd);
122130       break;
122131     }
122132 
122133     /*
122134     **  sqlite3_test_control(SQLITE_TESTCTRL_PENDING_BYTE, unsigned int X)
122135     **
122136     ** Set the PENDING byte to the value in the argument, if X>0.
122137     ** Make no changes if X==0.  Return the value of the pending byte
122138     ** as it existing before this routine was called.
122139     **
122140     ** IMPORTANT:  Changing the PENDING byte from 0x40000000 results in
122141     ** an incompatible database file format.  Changing the PENDING byte
122142     ** while any database connection is open results in undefined and
122143     ** dileterious behavior.
122144     */
122145     case SQLITE_TESTCTRL_PENDING_BYTE: {
122146       rc = PENDING_BYTE;
122147 #ifndef SQLITE_OMIT_WSD
122148       {
122149         unsigned int newVal = va_arg(ap, unsigned int);
122150         if( newVal ) sqlite3PendingByte = newVal;
122151       }
122152 #endif
122153       break;
122154     }
122155 
122156     /*
122157     **  sqlite3_test_control(SQLITE_TESTCTRL_ASSERT, int X)
122158     **
122159     ** This action provides a run-time test to see whether or not
122160     ** assert() was enabled at compile-time.  If X is true and assert()
122161     ** is enabled, then the return value is true.  If X is true and
122162     ** assert() is disabled, then the return value is zero.  If X is
122163     ** false and assert() is enabled, then the assertion fires and the
122164     ** process aborts.  If X is false and assert() is disabled, then the
122165     ** return value is zero.
122166     */
122167     case SQLITE_TESTCTRL_ASSERT: {
122168       volatile int x = 0;
122169       assert( (x = va_arg(ap,int))!=0 );
122170       rc = x;
122171       break;
122172     }
122173 
122174 
122175     /*
122176     **  sqlite3_test_control(SQLITE_TESTCTRL_ALWAYS, int X)
122177     **
122178     ** This action provides a run-time test to see how the ALWAYS and
122179     ** NEVER macros were defined at compile-time.
122180     **
122181     ** The return value is ALWAYS(X).  
122182     **
122183     ** The recommended test is X==2.  If the return value is 2, that means
122184     ** ALWAYS() and NEVER() are both no-op pass-through macros, which is the
122185     ** default setting.  If the return value is 1, then ALWAYS() is either
122186     ** hard-coded to true or else it asserts if its argument is false.
122187     ** The first behavior (hard-coded to true) is the case if
122188     ** SQLITE_TESTCTRL_ASSERT shows that assert() is disabled and the second
122189     ** behavior (assert if the argument to ALWAYS() is false) is the case if
122190     ** SQLITE_TESTCTRL_ASSERT shows that assert() is enabled.
122191     **
122192     ** The run-time test procedure might look something like this:
122193     **
122194     **    if( sqlite3_test_control(SQLITE_TESTCTRL_ALWAYS, 2)==2 ){
122195     **      // ALWAYS() and NEVER() are no-op pass-through macros
122196     **    }else if( sqlite3_test_control(SQLITE_TESTCTRL_ASSERT, 1) ){
122197     **      // ALWAYS(x) asserts that x is true. NEVER(x) asserts x is false.
122198     **    }else{
122199     **      // ALWAYS(x) is a constant 1.  NEVER(x) is a constant 0.
122200     **    }
122201     */
122202     case SQLITE_TESTCTRL_ALWAYS: {
122203       int x = va_arg(ap,int);
122204       rc = ALWAYS(x);
122205       break;
122206     }
122207 
122208     /*   sqlite3_test_control(SQLITE_TESTCTRL_RESERVE, sqlite3 *db, int N)
122209     **
122210     ** Set the nReserve size to N for the main database on the database
122211     ** connection db.
122212     */
122213     case SQLITE_TESTCTRL_RESERVE: {
122214       sqlite3 *db = va_arg(ap, sqlite3*);
122215       int x = va_arg(ap,int);
122216       sqlite3_mutex_enter(db->mutex);
122217       sqlite3BtreeSetPageSize(db->aDb[0].pBt, 0, x, 0);
122218       sqlite3_mutex_leave(db->mutex);
122219       break;
122220     }
122221 
122222     /*  sqlite3_test_control(SQLITE_TESTCTRL_OPTIMIZATIONS, sqlite3 *db, int N)
122223     **
122224     ** Enable or disable various optimizations for testing purposes.  The 
122225     ** argument N is a bitmask of optimizations to be disabled.  For normal
122226     ** operation N should be 0.  The idea is that a test program (like the
122227     ** SQL Logic Test or SLT test module) can run the same SQL multiple times
122228     ** with various optimizations disabled to verify that the same answer
122229     ** is obtained in every case.
122230     */
122231     case SQLITE_TESTCTRL_OPTIMIZATIONS: {
122232       sqlite3 *db = va_arg(ap, sqlite3*);
122233       db->dbOptFlags = (u16)(va_arg(ap, int) & 0xffff);
122234       break;
122235     }
122236 
122237 #ifdef SQLITE_N_KEYWORD
122238     /* sqlite3_test_control(SQLITE_TESTCTRL_ISKEYWORD, const char *zWord)
122239     **
122240     ** If zWord is a keyword recognized by the parser, then return the
122241     ** number of keywords.  Or if zWord is not a keyword, return 0.
122242     ** 
122243     ** This test feature is only available in the amalgamation since
122244     ** the SQLITE_N_KEYWORD macro is not defined in this file if SQLite
122245     ** is built using separate source files.
122246     */
122247     case SQLITE_TESTCTRL_ISKEYWORD: {
122248       const char *zWord = va_arg(ap, const char*);
122249       int n = sqlite3Strlen30(zWord);
122250       rc = (sqlite3KeywordCode((u8*)zWord, n)!=TK_ID) ? SQLITE_N_KEYWORD : 0;
122251       break;
122252     }
122253 #endif 
122254 
122255     /* sqlite3_test_control(SQLITE_TESTCTRL_SCRATCHMALLOC, sz, &pNew, pFree);
122256     **
122257     ** Pass pFree into sqlite3ScratchFree(). 
122258     ** If sz>0 then allocate a scratch buffer into pNew.  
122259     */
122260     case SQLITE_TESTCTRL_SCRATCHMALLOC: {
122261       void *pFree, **ppNew;
122262       int sz;
122263       sz = va_arg(ap, int);
122264       ppNew = va_arg(ap, void**);
122265       pFree = va_arg(ap, void*);
122266       if( sz ) *ppNew = sqlite3ScratchMalloc(sz);
122267       sqlite3ScratchFree(pFree);
122268       break;
122269     }
122270 
122271     /*   sqlite3_test_control(SQLITE_TESTCTRL_LOCALTIME_FAULT, int onoff);
122272     **
122273     ** If parameter onoff is non-zero, configure the wrappers so that all
122274     ** subsequent calls to localtime() and variants fail. If onoff is zero,
122275     ** undo this setting.
122276     */
122277     case SQLITE_TESTCTRL_LOCALTIME_FAULT: {
122278       sqlite3GlobalConfig.bLocaltimeFault = va_arg(ap, int);
122279       break;
122280     }
122281 
122282 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
122283     /*   sqlite3_test_control(SQLITE_TESTCTRL_EXPLAIN_STMT,
122284     **                        sqlite3_stmt*,const char**);
122285     **
122286     ** If compiled with SQLITE_ENABLE_TREE_EXPLAIN, each sqlite3_stmt holds
122287     ** a string that describes the optimized parse tree.  This test-control
122288     ** returns a pointer to that string.
122289     */
122290     case SQLITE_TESTCTRL_EXPLAIN_STMT: {
122291       sqlite3_stmt *pStmt = va_arg(ap, sqlite3_stmt*);
122292       const char **pzRet = va_arg(ap, const char**);
122293       *pzRet = sqlite3VdbeExplanation((Vdbe*)pStmt);
122294       break;
122295     }
122296 #endif
122297 
122298     /*   sqlite3_test_control(SQLITE_TESTCTRL_NEVER_CORRUPT, int);
122299     **
122300     ** Set or clear a flag that indicates that the database file is always well-
122301     ** formed and never corrupt.  This flag is clear by default, indicating that
122302     ** database files might have arbitrary corruption.  Setting the flag during
122303     ** testing causes certain assert() statements in the code to be activated
122304     ** that demonstrat invariants on well-formed database files.
122305     */
122306     case SQLITE_TESTCTRL_NEVER_CORRUPT: {
122307       sqlite3Config.neverCorrupt = va_arg(ap, int);
122308       break;
122309     }
122310 
122311   }
122312   va_end(ap);
122313 #endif /* SQLITE_OMIT_BUILTIN_TEST */
122314   return rc;
122315 }
122316 
122317 /*
122318 ** This is a utility routine, useful to VFS implementations, that checks
122319 ** to see if a database file was a URI that contained a specific query 
122320 ** parameter, and if so obtains the value of the query parameter.
122321 **
122322 ** The zFilename argument is the filename pointer passed into the xOpen()
122323 ** method of a VFS implementation.  The zParam argument is the name of the
122324 ** query parameter we seek.  This routine returns the value of the zParam
122325 ** parameter if it exists.  If the parameter does not exist, this routine
122326 ** returns a NULL pointer.
122327 */
122328 SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam){
122329   if( zFilename==0 ) return 0;
122330   zFilename += sqlite3Strlen30(zFilename) + 1;
122331   while( zFilename[0] ){
122332     int x = strcmp(zFilename, zParam);
122333     zFilename += sqlite3Strlen30(zFilename) + 1;
122334     if( x==0 ) return zFilename;
122335     zFilename += sqlite3Strlen30(zFilename) + 1;
122336   }
122337   return 0;
122338 }
122339 
122340 /*
122341 ** Return a boolean value for a query parameter.
122342 */
122343 SQLITE_API int sqlite3_uri_boolean(const char *zFilename, const char *zParam, int bDflt){
122344   const char *z = sqlite3_uri_parameter(zFilename, zParam);
122345   bDflt = bDflt!=0;
122346   return z ? sqlite3GetBoolean(z, bDflt) : bDflt;
122347 }
122348 
122349 /*
122350 ** Return a 64-bit integer value for a query parameter.
122351 */
122352 SQLITE_API sqlite3_int64 sqlite3_uri_int64(
122353   const char *zFilename,    /* Filename as passed to xOpen */
122354   const char *zParam,       /* URI parameter sought */
122355   sqlite3_int64 bDflt       /* return if parameter is missing */
122356 ){
122357   const char *z = sqlite3_uri_parameter(zFilename, zParam);
122358   sqlite3_int64 v;
122359   if( z && sqlite3Atoi64(z, &v, sqlite3Strlen30(z), SQLITE_UTF8)==SQLITE_OK ){
122360     bDflt = v;
122361   }
122362   return bDflt;
122363 }
122364 
122365 /*
122366 ** Return the Btree pointer identified by zDbName.  Return NULL if not found.
122367 */
122368 SQLITE_PRIVATE Btree *sqlite3DbNameToBtree(sqlite3 *db, const char *zDbName){
122369   int i;
122370   for(i=0; i<db->nDb; i++){
122371     if( db->aDb[i].pBt
122372      && (zDbName==0 || sqlite3StrICmp(zDbName, db->aDb[i].zName)==0)
122373     ){
122374       return db->aDb[i].pBt;
122375     }
122376   }
122377   return 0;
122378 }
122379 
122380 /*
122381 ** Return the filename of the database associated with a database
122382 ** connection.
122383 */
122384 SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName){
122385   Btree *pBt = sqlite3DbNameToBtree(db, zDbName);
122386   return pBt ? sqlite3BtreeGetFilename(pBt) : 0;
122387 }
122388 
122389 /*
122390 ** Return 1 if database is read-only or 0 if read/write.  Return -1 if
122391 ** no such database exists.
122392 */
122393 SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName){
122394   Btree *pBt = sqlite3DbNameToBtree(db, zDbName);
122395   return pBt ? sqlite3PagerIsreadonly(sqlite3BtreePager(pBt)) : -1;
122396 }
122397 
122398 /************** End of main.c ************************************************/
122399 /************** Begin file notify.c ******************************************/
122400 /*
122401 ** 2009 March 3
122402 **
122403 ** The author disclaims copyright to this source code.  In place of
122404 ** a legal notice, here is a blessing:
122405 **
122406 **    May you do good and not evil.
122407 **    May you find forgiveness for yourself and forgive others.
122408 **    May you share freely, never taking more than you give.
122409 **
122410 *************************************************************************
122411 **
122412 ** This file contains the implementation of the sqlite3_unlock_notify()
122413 ** API method and its associated functionality.
122414 */
122415 
122416 /* Omit this entire file if SQLITE_ENABLE_UNLOCK_NOTIFY is not defined. */
122417 #ifdef SQLITE_ENABLE_UNLOCK_NOTIFY
122418 
122419 /*
122420 ** Public interfaces:
122421 **
122422 **   sqlite3ConnectionBlocked()
122423 **   sqlite3ConnectionUnlocked()
122424 **   sqlite3ConnectionClosed()
122425 **   sqlite3_unlock_notify()
122426 */
122427 
122428 #define assertMutexHeld() \
122429   assert( sqlite3_mutex_held(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)) )
122430 
122431 /*
122432 ** Head of a linked list of all sqlite3 objects created by this process
122433 ** for which either sqlite3.pBlockingConnection or sqlite3.pUnlockConnection
122434 ** is not NULL. This variable may only accessed while the STATIC_MASTER
122435 ** mutex is held.
122436 */
122437 static sqlite3 *SQLITE_WSD sqlite3BlockedList = 0;
122438 
122439 #ifndef NDEBUG
122440 /*
122441 ** This function is a complex assert() that verifies the following 
122442 ** properties of the blocked connections list:
122443 **
122444 **   1) Each entry in the list has a non-NULL value for either 
122445 **      pUnlockConnection or pBlockingConnection, or both.
122446 **
122447 **   2) All entries in the list that share a common value for 
122448 **      xUnlockNotify are grouped together.
122449 **
122450 **   3) If the argument db is not NULL, then none of the entries in the
122451 **      blocked connections list have pUnlockConnection or pBlockingConnection
122452 **      set to db. This is used when closing connection db.
122453 */
122454 static void checkListProperties(sqlite3 *db){
122455   sqlite3 *p;
122456   for(p=sqlite3BlockedList; p; p=p->pNextBlocked){
122457     int seen = 0;
122458     sqlite3 *p2;
122459 
122460     /* Verify property (1) */
122461     assert( p->pUnlockConnection || p->pBlockingConnection );
122462 
122463     /* Verify property (2) */
122464     for(p2=sqlite3BlockedList; p2!=p; p2=p2->pNextBlocked){
122465       if( p2->xUnlockNotify==p->xUnlockNotify ) seen = 1;
122466       assert( p2->xUnlockNotify==p->xUnlockNotify || !seen );
122467       assert( db==0 || p->pUnlockConnection!=db );
122468       assert( db==0 || p->pBlockingConnection!=db );
122469     }
122470   }
122471 }
122472 #else
122473 # define checkListProperties(x)
122474 #endif
122475 
122476 /*
122477 ** Remove connection db from the blocked connections list. If connection
122478 ** db is not currently a part of the list, this function is a no-op.
122479 */
122480 static void removeFromBlockedList(sqlite3 *db){
122481   sqlite3 **pp;
122482   assertMutexHeld();
122483   for(pp=&sqlite3BlockedList; *pp; pp = &(*pp)->pNextBlocked){
122484     if( *pp==db ){
122485       *pp = (*pp)->pNextBlocked;
122486       break;
122487     }
122488   }
122489 }
122490 
122491 /*
122492 ** Add connection db to the blocked connections list. It is assumed
122493 ** that it is not already a part of the list.
122494 */
122495 static void addToBlockedList(sqlite3 *db){
122496   sqlite3 **pp;
122497   assertMutexHeld();
122498   for(
122499     pp=&sqlite3BlockedList; 
122500     *pp && (*pp)->xUnlockNotify!=db->xUnlockNotify; 
122501     pp=&(*pp)->pNextBlocked
122502   );
122503   db->pNextBlocked = *pp;
122504   *pp = db;
122505 }
122506 
122507 /*
122508 ** Obtain the STATIC_MASTER mutex.
122509 */
122510 static void enterMutex(void){
122511   sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
122512   checkListProperties(0);
122513 }
122514 
122515 /*
122516 ** Release the STATIC_MASTER mutex.
122517 */
122518 static void leaveMutex(void){
122519   assertMutexHeld();
122520   checkListProperties(0);
122521   sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
122522 }
122523 
122524 /*
122525 ** Register an unlock-notify callback.
122526 **
122527 ** This is called after connection "db" has attempted some operation
122528 ** but has received an SQLITE_LOCKED error because another connection
122529 ** (call it pOther) in the same process was busy using the same shared
122530 ** cache.  pOther is found by looking at db->pBlockingConnection.
122531 **
122532 ** If there is no blocking connection, the callback is invoked immediately,
122533 ** before this routine returns.
122534 **
122535 ** If pOther is already blocked on db, then report SQLITE_LOCKED, to indicate
122536 ** a deadlock.
122537 **
122538 ** Otherwise, make arrangements to invoke xNotify when pOther drops
122539 ** its locks.
122540 **
122541 ** Each call to this routine overrides any prior callbacks registered
122542 ** on the same "db".  If xNotify==0 then any prior callbacks are immediately
122543 ** cancelled.
122544 */
122545 SQLITE_API int sqlite3_unlock_notify(
122546   sqlite3 *db,
122547   void (*xNotify)(void **, int),
122548   void *pArg
122549 ){
122550   int rc = SQLITE_OK;
122551 
122552   sqlite3_mutex_enter(db->mutex);
122553   enterMutex();
122554 
122555   if( xNotify==0 ){
122556     removeFromBlockedList(db);
122557     db->pBlockingConnection = 0;
122558     db->pUnlockConnection = 0;
122559     db->xUnlockNotify = 0;
122560     db->pUnlockArg = 0;
122561   }else if( 0==db->pBlockingConnection ){
122562     /* The blocking transaction has been concluded. Or there never was a 
122563     ** blocking transaction. In either case, invoke the notify callback
122564     ** immediately. 
122565     */
122566     xNotify(&pArg, 1);
122567   }else{
122568     sqlite3 *p;
122569 
122570     for(p=db->pBlockingConnection; p && p!=db; p=p->pUnlockConnection){}
122571     if( p ){
122572       rc = SQLITE_LOCKED;              /* Deadlock detected. */
122573     }else{
122574       db->pUnlockConnection = db->pBlockingConnection;
122575       db->xUnlockNotify = xNotify;
122576       db->pUnlockArg = pArg;
122577       removeFromBlockedList(db);
122578       addToBlockedList(db);
122579     }
122580   }
122581 
122582   leaveMutex();
122583   assert( !db->mallocFailed );
122584   sqlite3Error(db, rc, (rc?"database is deadlocked":0));
122585   sqlite3_mutex_leave(db->mutex);
122586   return rc;
122587 }
122588 
122589 /*
122590 ** This function is called while stepping or preparing a statement 
122591 ** associated with connection db. The operation will return SQLITE_LOCKED
122592 ** to the user because it requires a lock that will not be available
122593 ** until connection pBlocker concludes its current transaction.
122594 */
122595 SQLITE_PRIVATE void sqlite3ConnectionBlocked(sqlite3 *db, sqlite3 *pBlocker){
122596   enterMutex();
122597   if( db->pBlockingConnection==0 && db->pUnlockConnection==0 ){
122598     addToBlockedList(db);
122599   }
122600   db->pBlockingConnection = pBlocker;
122601   leaveMutex();
122602 }
122603 
122604 /*
122605 ** This function is called when
122606 ** the transaction opened by database db has just finished. Locks held 
122607 ** by database connection db have been released.
122608 **
122609 ** This function loops through each entry in the blocked connections
122610 ** list and does the following:
122611 **
122612 **   1) If the sqlite3.pBlockingConnection member of a list entry is
122613 **      set to db, then set pBlockingConnection=0.
122614 **
122615 **   2) If the sqlite3.pUnlockConnection member of a list entry is
122616 **      set to db, then invoke the configured unlock-notify callback and
122617 **      set pUnlockConnection=0.
122618 **
122619 **   3) If the two steps above mean that pBlockingConnection==0 and
122620 **      pUnlockConnection==0, remove the entry from the blocked connections
122621 **      list.
122622 */
122623 SQLITE_PRIVATE void sqlite3ConnectionUnlocked(sqlite3 *db){
122624   void (*xUnlockNotify)(void **, int) = 0; /* Unlock-notify cb to invoke */
122625   int nArg = 0;                            /* Number of entries in aArg[] */
122626   sqlite3 **pp;                            /* Iterator variable */
122627   void **aArg;               /* Arguments to the unlock callback */
122628   void **aDyn = 0;           /* Dynamically allocated space for aArg[] */
122629   void *aStatic[16];         /* Starter space for aArg[].  No malloc required */
122630 
122631   aArg = aStatic;
122632   enterMutex();         /* Enter STATIC_MASTER mutex */
122633 
122634   /* This loop runs once for each entry in the blocked-connections list. */
122635   for(pp=&sqlite3BlockedList; *pp; /* no-op */ ){
122636     sqlite3 *p = *pp;
122637 
122638     /* Step 1. */
122639     if( p->pBlockingConnection==db ){
122640       p->pBlockingConnection = 0;
122641     }
122642 
122643     /* Step 2. */
122644     if( p->pUnlockConnection==db ){
122645       assert( p->xUnlockNotify );
122646       if( p->xUnlockNotify!=xUnlockNotify && nArg!=0 ){
122647         xUnlockNotify(aArg, nArg);
122648         nArg = 0;
122649       }
122650 
122651       sqlite3BeginBenignMalloc();
122652       assert( aArg==aDyn || (aDyn==0 && aArg==aStatic) );
122653       assert( nArg<=(int)ArraySize(aStatic) || aArg==aDyn );
122654       if( (!aDyn && nArg==(int)ArraySize(aStatic))
122655        || (aDyn && nArg==(int)(sqlite3MallocSize(aDyn)/sizeof(void*)))
122656       ){
122657         /* The aArg[] array needs to grow. */
122658         void **pNew = (void **)sqlite3Malloc(nArg*sizeof(void *)*2);
122659         if( pNew ){
122660           memcpy(pNew, aArg, nArg*sizeof(void *));
122661           sqlite3_free(aDyn);
122662           aDyn = aArg = pNew;
122663         }else{
122664           /* This occurs when the array of context pointers that need to
122665           ** be passed to the unlock-notify callback is larger than the
122666           ** aStatic[] array allocated on the stack and the attempt to 
122667           ** allocate a larger array from the heap has failed.
122668           **
122669           ** This is a difficult situation to handle. Returning an error
122670           ** code to the caller is insufficient, as even if an error code
122671           ** is returned the transaction on connection db will still be
122672           ** closed and the unlock-notify callbacks on blocked connections
122673           ** will go unissued. This might cause the application to wait
122674           ** indefinitely for an unlock-notify callback that will never 
122675           ** arrive.
122676           **
122677           ** Instead, invoke the unlock-notify callback with the context
122678           ** array already accumulated. We can then clear the array and
122679           ** begin accumulating any further context pointers without 
122680           ** requiring any dynamic allocation. This is sub-optimal because
122681           ** it means that instead of one callback with a large array of
122682           ** context pointers the application will receive two or more
122683           ** callbacks with smaller arrays of context pointers, which will
122684           ** reduce the applications ability to prioritize multiple 
122685           ** connections. But it is the best that can be done under the
122686           ** circumstances.
122687           */
122688           xUnlockNotify(aArg, nArg);
122689           nArg = 0;
122690         }
122691       }
122692       sqlite3EndBenignMalloc();
122693 
122694       aArg[nArg++] = p->pUnlockArg;
122695       xUnlockNotify = p->xUnlockNotify;
122696       p->pUnlockConnection = 0;
122697       p->xUnlockNotify = 0;
122698       p->pUnlockArg = 0;
122699     }
122700 
122701     /* Step 3. */
122702     if( p->pBlockingConnection==0 && p->pUnlockConnection==0 ){
122703       /* Remove connection p from the blocked connections list. */
122704       *pp = p->pNextBlocked;
122705       p->pNextBlocked = 0;
122706     }else{
122707       pp = &p->pNextBlocked;
122708     }
122709   }
122710 
122711   if( nArg!=0 ){
122712     xUnlockNotify(aArg, nArg);
122713   }
122714   sqlite3_free(aDyn);
122715   leaveMutex();         /* Leave STATIC_MASTER mutex */
122716 }
122717 
122718 /*
122719 ** This is called when the database connection passed as an argument is 
122720 ** being closed. The connection is removed from the blocked list.
122721 */
122722 SQLITE_PRIVATE void sqlite3ConnectionClosed(sqlite3 *db){
122723   sqlite3ConnectionUnlocked(db);
122724   enterMutex();
122725   removeFromBlockedList(db);
122726   checkListProperties(db);
122727   leaveMutex();
122728 }
122729 #endif
122730 
122731 /************** End of notify.c **********************************************/
122732 /************** Begin file fts3.c ********************************************/
122733 /*
122734 ** 2006 Oct 10
122735 **
122736 ** The author disclaims copyright to this source code.  In place of
122737 ** a legal notice, here is a blessing:
122738 **
122739 **    May you do good and not evil.
122740 **    May you find forgiveness for yourself and forgive others.
122741 **    May you share freely, never taking more than you give.
122742 **
122743 ******************************************************************************
122744 **
122745 ** This is an SQLite module implementing full-text search.
122746 */
122747 
122748 /*
122749 ** The code in this file is only compiled if:
122750 **
122751 **     * The FTS3 module is being built as an extension
122752 **       (in which case SQLITE_CORE is not defined), or
122753 **
122754 **     * The FTS3 module is being built into the core of
122755 **       SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
122756 */
122757 
122758 /* The full-text index is stored in a series of b+tree (-like)
122759 ** structures called segments which map terms to doclists.  The
122760 ** structures are like b+trees in layout, but are constructed from the
122761 ** bottom up in optimal fashion and are not updatable.  Since trees
122762 ** are built from the bottom up, things will be described from the
122763 ** bottom up.
122764 **
122765 **
122766 **** Varints ****
122767 ** The basic unit of encoding is a variable-length integer called a
122768 ** varint.  We encode variable-length integers in little-endian order
122769 ** using seven bits * per byte as follows:
122770 **
122771 ** KEY:
122772 **         A = 0xxxxxxx    7 bits of data and one flag bit
122773 **         B = 1xxxxxxx    7 bits of data and one flag bit
122774 **
122775 **  7 bits - A
122776 ** 14 bits - BA
122777 ** 21 bits - BBA
122778 ** and so on.
122779 **
122780 ** This is similar in concept to how sqlite encodes "varints" but
122781 ** the encoding is not the same.  SQLite varints are big-endian
122782 ** are are limited to 9 bytes in length whereas FTS3 varints are
122783 ** little-endian and can be up to 10 bytes in length (in theory).
122784 **
122785 ** Example encodings:
122786 **
122787 **     1:    0x01
122788 **   127:    0x7f
122789 **   128:    0x81 0x00
122790 **
122791 **
122792 **** Document lists ****
122793 ** A doclist (document list) holds a docid-sorted list of hits for a
122794 ** given term.  Doclists hold docids and associated token positions.
122795 ** A docid is the unique integer identifier for a single document.
122796 ** A position is the index of a word within the document.  The first 
122797 ** word of the document has a position of 0.
122798 **
122799 ** FTS3 used to optionally store character offsets using a compile-time
122800 ** option.  But that functionality is no longer supported.
122801 **
122802 ** A doclist is stored like this:
122803 **
122804 ** array {
122805 **   varint docid;          (delta from previous doclist)
122806 **   array {                (position list for column 0)
122807 **     varint position;     (2 more than the delta from previous position)
122808 **   }
122809 **   array {
122810 **     varint POS_COLUMN;   (marks start of position list for new column)
122811 **     varint column;       (index of new column)
122812 **     array {
122813 **       varint position;   (2 more than the delta from previous position)
122814 **     }
122815 **   }
122816 **   varint POS_END;        (marks end of positions for this document.
122817 ** }
122818 **
122819 ** Here, array { X } means zero or more occurrences of X, adjacent in
122820 ** memory.  A "position" is an index of a token in the token stream
122821 ** generated by the tokenizer. Note that POS_END and POS_COLUMN occur 
122822 ** in the same logical place as the position element, and act as sentinals
122823 ** ending a position list array.  POS_END is 0.  POS_COLUMN is 1.
122824 ** The positions numbers are not stored literally but rather as two more
122825 ** than the difference from the prior position, or the just the position plus
122826 ** 2 for the first position.  Example:
122827 **
122828 **   label:       A B C D E  F  G H   I  J K
122829 **   value:     123 5 9 1 1 14 35 0 234 72 0
122830 **
122831 ** The 123 value is the first docid.  For column zero in this document
122832 ** there are two matches at positions 3 and 10 (5-2 and 9-2+3).  The 1
122833 ** at D signals the start of a new column; the 1 at E indicates that the
122834 ** new column is column number 1.  There are two positions at 12 and 45
122835 ** (14-2 and 35-2+12).  The 0 at H indicate the end-of-document.  The
122836 ** 234 at I is the delta to next docid (357).  It has one position 70
122837 ** (72-2) and then terminates with the 0 at K.
122838 **
122839 ** A "position-list" is the list of positions for multiple columns for
122840 ** a single docid.  A "column-list" is the set of positions for a single
122841 ** column.  Hence, a position-list consists of one or more column-lists,
122842 ** a document record consists of a docid followed by a position-list and
122843 ** a doclist consists of one or more document records.
122844 **
122845 ** A bare doclist omits the position information, becoming an 
122846 ** array of varint-encoded docids.
122847 **
122848 **** Segment leaf nodes ****
122849 ** Segment leaf nodes store terms and doclists, ordered by term.  Leaf
122850 ** nodes are written using LeafWriter, and read using LeafReader (to
122851 ** iterate through a single leaf node's data) and LeavesReader (to
122852 ** iterate through a segment's entire leaf layer).  Leaf nodes have
122853 ** the format:
122854 **
122855 ** varint iHeight;             (height from leaf level, always 0)
122856 ** varint nTerm;               (length of first term)
122857 ** char pTerm[nTerm];          (content of first term)
122858 ** varint nDoclist;            (length of term's associated doclist)
122859 ** char pDoclist[nDoclist];    (content of doclist)
122860 ** array {
122861 **                             (further terms are delta-encoded)
122862 **   varint nPrefix;           (length of prefix shared with previous term)
122863 **   varint nSuffix;           (length of unshared suffix)
122864 **   char pTermSuffix[nSuffix];(unshared suffix of next term)
122865 **   varint nDoclist;          (length of term's associated doclist)
122866 **   char pDoclist[nDoclist];  (content of doclist)
122867 ** }
122868 **
122869 ** Here, array { X } means zero or more occurrences of X, adjacent in
122870 ** memory.
122871 **
122872 ** Leaf nodes are broken into blocks which are stored contiguously in
122873 ** the %_segments table in sorted order.  This means that when the end
122874 ** of a node is reached, the next term is in the node with the next
122875 ** greater node id.
122876 **
122877 ** New data is spilled to a new leaf node when the current node
122878 ** exceeds LEAF_MAX bytes (default 2048).  New data which itself is
122879 ** larger than STANDALONE_MIN (default 1024) is placed in a standalone
122880 ** node (a leaf node with a single term and doclist).  The goal of
122881 ** these settings is to pack together groups of small doclists while
122882 ** making it efficient to directly access large doclists.  The
122883 ** assumption is that large doclists represent terms which are more
122884 ** likely to be query targets.
122885 **
122886 ** TODO(shess) It may be useful for blocking decisions to be more
122887 ** dynamic.  For instance, it may make more sense to have a 2.5k leaf
122888 ** node rather than splitting into 2k and .5k nodes.  My intuition is
122889 ** that this might extend through 2x or 4x the pagesize.
122890 **
122891 **
122892 **** Segment interior nodes ****
122893 ** Segment interior nodes store blockids for subtree nodes and terms
122894 ** to describe what data is stored by the each subtree.  Interior
122895 ** nodes are written using InteriorWriter, and read using
122896 ** InteriorReader.  InteriorWriters are created as needed when
122897 ** SegmentWriter creates new leaf nodes, or when an interior node
122898 ** itself grows too big and must be split.  The format of interior
122899 ** nodes:
122900 **
122901 ** varint iHeight;           (height from leaf level, always >0)
122902 ** varint iBlockid;          (block id of node's leftmost subtree)
122903 ** optional {
122904 **   varint nTerm;           (length of first term)
122905 **   char pTerm[nTerm];      (content of first term)
122906 **   array {
122907 **                                (further terms are delta-encoded)
122908 **     varint nPrefix;            (length of shared prefix with previous term)
122909 **     varint nSuffix;            (length of unshared suffix)
122910 **     char pTermSuffix[nSuffix]; (unshared suffix of next term)
122911 **   }
122912 ** }
122913 **
122914 ** Here, optional { X } means an optional element, while array { X }
122915 ** means zero or more occurrences of X, adjacent in memory.
122916 **
122917 ** An interior node encodes n terms separating n+1 subtrees.  The
122918 ** subtree blocks are contiguous, so only the first subtree's blockid
122919 ** is encoded.  The subtree at iBlockid will contain all terms less
122920 ** than the first term encoded (or all terms if no term is encoded).
122921 ** Otherwise, for terms greater than or equal to pTerm[i] but less
122922 ** than pTerm[i+1], the subtree for that term will be rooted at
122923 ** iBlockid+i.  Interior nodes only store enough term data to
122924 ** distinguish adjacent children (if the rightmost term of the left
122925 ** child is "something", and the leftmost term of the right child is
122926 ** "wicked", only "w" is stored).
122927 **
122928 ** New data is spilled to a new interior node at the same height when
122929 ** the current node exceeds INTERIOR_MAX bytes (default 2048).
122930 ** INTERIOR_MIN_TERMS (default 7) keeps large terms from monopolizing
122931 ** interior nodes and making the tree too skinny.  The interior nodes
122932 ** at a given height are naturally tracked by interior nodes at
122933 ** height+1, and so on.
122934 **
122935 **
122936 **** Segment directory ****
122937 ** The segment directory in table %_segdir stores meta-information for
122938 ** merging and deleting segments, and also the root node of the
122939 ** segment's tree.
122940 **
122941 ** The root node is the top node of the segment's tree after encoding
122942 ** the entire segment, restricted to ROOT_MAX bytes (default 1024).
122943 ** This could be either a leaf node or an interior node.  If the top
122944 ** node requires more than ROOT_MAX bytes, it is flushed to %_segments
122945 ** and a new root interior node is generated (which should always fit
122946 ** within ROOT_MAX because it only needs space for 2 varints, the
122947 ** height and the blockid of the previous root).
122948 **
122949 ** The meta-information in the segment directory is:
122950 **   level               - segment level (see below)
122951 **   idx                 - index within level
122952 **                       - (level,idx uniquely identify a segment)
122953 **   start_block         - first leaf node
122954 **   leaves_end_block    - last leaf node
122955 **   end_block           - last block (including interior nodes)
122956 **   root                - contents of root node
122957 **
122958 ** If the root node is a leaf node, then start_block,
122959 ** leaves_end_block, and end_block are all 0.
122960 **
122961 **
122962 **** Segment merging ****
122963 ** To amortize update costs, segments are grouped into levels and
122964 ** merged in batches.  Each increase in level represents exponentially
122965 ** more documents.
122966 **
122967 ** New documents (actually, document updates) are tokenized and
122968 ** written individually (using LeafWriter) to a level 0 segment, with
122969 ** incrementing idx.  When idx reaches MERGE_COUNT (default 16), all
122970 ** level 0 segments are merged into a single level 1 segment.  Level 1
122971 ** is populated like level 0, and eventually MERGE_COUNT level 1
122972 ** segments are merged to a single level 2 segment (representing
122973 ** MERGE_COUNT^2 updates), and so on.
122974 **
122975 ** A segment merge traverses all segments at a given level in
122976 ** parallel, performing a straightforward sorted merge.  Since segment
122977 ** leaf nodes are written in to the %_segments table in order, this
122978 ** merge traverses the underlying sqlite disk structures efficiently.
122979 ** After the merge, all segment blocks from the merged level are
122980 ** deleted.
122981 **
122982 ** MERGE_COUNT controls how often we merge segments.  16 seems to be
122983 ** somewhat of a sweet spot for insertion performance.  32 and 64 show
122984 ** very similar performance numbers to 16 on insertion, though they're
122985 ** a tiny bit slower (perhaps due to more overhead in merge-time
122986 ** sorting).  8 is about 20% slower than 16, 4 about 50% slower than
122987 ** 16, 2 about 66% slower than 16.
122988 **
122989 ** At query time, high MERGE_COUNT increases the number of segments
122990 ** which need to be scanned and merged.  For instance, with 100k docs
122991 ** inserted:
122992 **
122993 **    MERGE_COUNT   segments
122994 **       16           25
122995 **        8           12
122996 **        4           10
122997 **        2            6
122998 **
122999 ** This appears to have only a moderate impact on queries for very
123000 ** frequent terms (which are somewhat dominated by segment merge
123001 ** costs), and infrequent and non-existent terms still seem to be fast
123002 ** even with many segments.
123003 **
123004 ** TODO(shess) That said, it would be nice to have a better query-side
123005 ** argument for MERGE_COUNT of 16.  Also, it is possible/likely that
123006 ** optimizations to things like doclist merging will swing the sweet
123007 ** spot around.
123008 **
123009 **
123010 **
123011 **** Handling of deletions and updates ****
123012 ** Since we're using a segmented structure, with no docid-oriented
123013 ** index into the term index, we clearly cannot simply update the term
123014 ** index when a document is deleted or updated.  For deletions, we
123015 ** write an empty doclist (varint(docid) varint(POS_END)), for updates
123016 ** we simply write the new doclist.  Segment merges overwrite older
123017 ** data for a particular docid with newer data, so deletes or updates
123018 ** will eventually overtake the earlier data and knock it out.  The
123019 ** query logic likewise merges doclists so that newer data knocks out
123020 ** older data.
123021 */
123022 
123023 /************** Include fts3Int.h in the middle of fts3.c ********************/
123024 /************** Begin file fts3Int.h *****************************************/
123025 /*
123026 ** 2009 Nov 12
123027 **
123028 ** The author disclaims copyright to this source code.  In place of
123029 ** a legal notice, here is a blessing:
123030 **
123031 **    May you do good and not evil.
123032 **    May you find forgiveness for yourself and forgive others.
123033 **    May you share freely, never taking more than you give.
123034 **
123035 ******************************************************************************
123036 **
123037 */
123038 #ifndef _FTSINT_H
123039 #define _FTSINT_H
123040 
123041 #if !defined(NDEBUG) && !defined(SQLITE_DEBUG) 
123042 # define NDEBUG 1
123043 #endif
123044 
123045 /*
123046 ** FTS4 is really an extension for FTS3.  It is enabled using the
123047 ** SQLITE_ENABLE_FTS3 macro.  But to avoid confusion we also all
123048 ** the SQLITE_ENABLE_FTS4 macro to serve as an alisse for SQLITE_ENABLE_FTS3.
123049 */
123050 #if defined(SQLITE_ENABLE_FTS4) && !defined(SQLITE_ENABLE_FTS3)
123051 # define SQLITE_ENABLE_FTS3
123052 #endif
123053 
123054 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
123055 
123056 /* If not building as part of the core, include sqlite3ext.h. */
123057 #ifndef SQLITE_CORE
123058 SQLITE_EXTENSION_INIT3
123059 #endif
123060 
123061 /************** Include fts3_tokenizer.h in the middle of fts3Int.h **********/
123062 /************** Begin file fts3_tokenizer.h **********************************/
123063 /*
123064 ** 2006 July 10
123065 **
123066 ** The author disclaims copyright to this source code.
123067 **
123068 *************************************************************************
123069 ** Defines the interface to tokenizers used by fulltext-search.  There
123070 ** are three basic components:
123071 **
123072 ** sqlite3_tokenizer_module is a singleton defining the tokenizer
123073 ** interface functions.  This is essentially the class structure for
123074 ** tokenizers.
123075 **
123076 ** sqlite3_tokenizer is used to define a particular tokenizer, perhaps
123077 ** including customization information defined at creation time.
123078 **
123079 ** sqlite3_tokenizer_cursor is generated by a tokenizer to generate
123080 ** tokens from a particular input.
123081 */
123082 #ifndef _FTS3_TOKENIZER_H_
123083 #define _FTS3_TOKENIZER_H_
123084 
123085 /* TODO(shess) Only used for SQLITE_OK and SQLITE_DONE at this time.
123086 ** If tokenizers are to be allowed to call sqlite3_*() functions, then
123087 ** we will need a way to register the API consistently.
123088 */
123089 
123090 /*
123091 ** Structures used by the tokenizer interface. When a new tokenizer
123092 ** implementation is registered, the caller provides a pointer to
123093 ** an sqlite3_tokenizer_module containing pointers to the callback
123094 ** functions that make up an implementation.
123095 **
123096 ** When an fts3 table is created, it passes any arguments passed to
123097 ** the tokenizer clause of the CREATE VIRTUAL TABLE statement to the
123098 ** sqlite3_tokenizer_module.xCreate() function of the requested tokenizer
123099 ** implementation. The xCreate() function in turn returns an 
123100 ** sqlite3_tokenizer structure representing the specific tokenizer to
123101 ** be used for the fts3 table (customized by the tokenizer clause arguments).
123102 **
123103 ** To tokenize an input buffer, the sqlite3_tokenizer_module.xOpen()
123104 ** method is called. It returns an sqlite3_tokenizer_cursor object
123105 ** that may be used to tokenize a specific input buffer based on
123106 ** the tokenization rules supplied by a specific sqlite3_tokenizer
123107 ** object.
123108 */
123109 typedef struct sqlite3_tokenizer_module sqlite3_tokenizer_module;
123110 typedef struct sqlite3_tokenizer sqlite3_tokenizer;
123111 typedef struct sqlite3_tokenizer_cursor sqlite3_tokenizer_cursor;
123112 
123113 struct sqlite3_tokenizer_module {
123114 
123115   /*
123116   ** Structure version. Should always be set to 0 or 1.
123117   */
123118   int iVersion;
123119 
123120   /*
123121   ** Create a new tokenizer. The values in the argv[] array are the
123122   ** arguments passed to the "tokenizer" clause of the CREATE VIRTUAL
123123   ** TABLE statement that created the fts3 table. For example, if
123124   ** the following SQL is executed:
123125   **
123126   **   CREATE .. USING fts3( ... , tokenizer <tokenizer-name> arg1 arg2)
123127   **
123128   ** then argc is set to 2, and the argv[] array contains pointers
123129   ** to the strings "arg1" and "arg2".
123130   **
123131   ** This method should return either SQLITE_OK (0), or an SQLite error 
123132   ** code. If SQLITE_OK is returned, then *ppTokenizer should be set
123133   ** to point at the newly created tokenizer structure. The generic
123134   ** sqlite3_tokenizer.pModule variable should not be initialized by
123135   ** this callback. The caller will do so.
123136   */
123137   int (*xCreate)(
123138     int argc,                           /* Size of argv array */
123139     const char *const*argv,             /* Tokenizer argument strings */
123140     sqlite3_tokenizer **ppTokenizer     /* OUT: Created tokenizer */
123141   );
123142 
123143   /*
123144   ** Destroy an existing tokenizer. The fts3 module calls this method
123145   ** exactly once for each successful call to xCreate().
123146   */
123147   int (*xDestroy)(sqlite3_tokenizer *pTokenizer);
123148 
123149   /*
123150   ** Create a tokenizer cursor to tokenize an input buffer. The caller
123151   ** is responsible for ensuring that the input buffer remains valid
123152   ** until the cursor is closed (using the xClose() method). 
123153   */
123154   int (*xOpen)(
123155     sqlite3_tokenizer *pTokenizer,       /* Tokenizer object */
123156     const char *pInput, int nBytes,      /* Input buffer */
123157     sqlite3_tokenizer_cursor **ppCursor  /* OUT: Created tokenizer cursor */
123158   );
123159 
123160   /*
123161   ** Destroy an existing tokenizer cursor. The fts3 module calls this 
123162   ** method exactly once for each successful call to xOpen().
123163   */
123164   int (*xClose)(sqlite3_tokenizer_cursor *pCursor);
123165 
123166   /*
123167   ** Retrieve the next token from the tokenizer cursor pCursor. This
123168   ** method should either return SQLITE_OK and set the values of the
123169   ** "OUT" variables identified below, or SQLITE_DONE to indicate that
123170   ** the end of the buffer has been reached, or an SQLite error code.
123171   **
123172   ** *ppToken should be set to point at a buffer containing the 
123173   ** normalized version of the token (i.e. after any case-folding and/or
123174   ** stemming has been performed). *pnBytes should be set to the length
123175   ** of this buffer in bytes. The input text that generated the token is
123176   ** identified by the byte offsets returned in *piStartOffset and
123177   ** *piEndOffset. *piStartOffset should be set to the index of the first
123178   ** byte of the token in the input buffer. *piEndOffset should be set
123179   ** to the index of the first byte just past the end of the token in
123180   ** the input buffer.
123181   **
123182   ** The buffer *ppToken is set to point at is managed by the tokenizer
123183   ** implementation. It is only required to be valid until the next call
123184   ** to xNext() or xClose(). 
123185   */
123186   /* TODO(shess) current implementation requires pInput to be
123187   ** nul-terminated.  This should either be fixed, or pInput/nBytes
123188   ** should be converted to zInput.
123189   */
123190   int (*xNext)(
123191     sqlite3_tokenizer_cursor *pCursor,   /* Tokenizer cursor */
123192     const char **ppToken, int *pnBytes,  /* OUT: Normalized text for token */
123193     int *piStartOffset,  /* OUT: Byte offset of token in input buffer */
123194     int *piEndOffset,    /* OUT: Byte offset of end of token in input buffer */
123195     int *piPosition      /* OUT: Number of tokens returned before this one */
123196   );
123197 
123198   /***********************************************************************
123199   ** Methods below this point are only available if iVersion>=1.
123200   */
123201 
123202   /* 
123203   ** Configure the language id of a tokenizer cursor.
123204   */
123205   int (*xLanguageid)(sqlite3_tokenizer_cursor *pCsr, int iLangid);
123206 };
123207 
123208 struct sqlite3_tokenizer {
123209   const sqlite3_tokenizer_module *pModule;  /* The module for this tokenizer */
123210   /* Tokenizer implementations will typically add additional fields */
123211 };
123212 
123213 struct sqlite3_tokenizer_cursor {
123214   sqlite3_tokenizer *pTokenizer;       /* Tokenizer for this cursor. */
123215   /* Tokenizer implementations will typically add additional fields */
123216 };
123217 
123218 int fts3_global_term_cnt(int iTerm, int iCol);
123219 int fts3_term_cnt(int iTerm, int iCol);
123220 
123221 
123222 #endif /* _FTS3_TOKENIZER_H_ */
123223 
123224 /************** End of fts3_tokenizer.h **************************************/
123225 /************** Continuing where we left off in fts3Int.h ********************/
123226 /************** Include fts3_hash.h in the middle of fts3Int.h ***************/
123227 /************** Begin file fts3_hash.h ***************************************/
123228 /*
123229 ** 2001 September 22
123230 **
123231 ** The author disclaims copyright to this source code.  In place of
123232 ** a legal notice, here is a blessing:
123233 **
123234 **    May you do good and not evil.
123235 **    May you find forgiveness for yourself and forgive others.
123236 **    May you share freely, never taking more than you give.
123237 **
123238 *************************************************************************
123239 ** This is the header file for the generic hash-table implementation
123240 ** used in SQLite.  We've modified it slightly to serve as a standalone
123241 ** hash table implementation for the full-text indexing module.
123242 **
123243 */
123244 #ifndef _FTS3_HASH_H_
123245 #define _FTS3_HASH_H_
123246 
123247 /* Forward declarations of structures. */
123248 typedef struct Fts3Hash Fts3Hash;
123249 typedef struct Fts3HashElem Fts3HashElem;
123250 
123251 /* A complete hash table is an instance of the following structure.
123252 ** The internals of this structure are intended to be opaque -- client
123253 ** code should not attempt to access or modify the fields of this structure
123254 ** directly.  Change this structure only by using the routines below.
123255 ** However, many of the "procedures" and "functions" for modifying and
123256 ** accessing this structure are really macros, so we can't really make
123257 ** this structure opaque.
123258 */
123259 struct Fts3Hash {
123260   char keyClass;          /* HASH_INT, _POINTER, _STRING, _BINARY */
123261   char copyKey;           /* True if copy of key made on insert */
123262   int count;              /* Number of entries in this table */
123263   Fts3HashElem *first;    /* The first element of the array */
123264   int htsize;             /* Number of buckets in the hash table */
123265   struct _fts3ht {        /* the hash table */
123266     int count;               /* Number of entries with this hash */
123267     Fts3HashElem *chain;     /* Pointer to first entry with this hash */
123268   } *ht;
123269 };
123270 
123271 /* Each element in the hash table is an instance of the following 
123272 ** structure.  All elements are stored on a single doubly-linked list.
123273 **
123274 ** Again, this structure is intended to be opaque, but it can't really
123275 ** be opaque because it is used by macros.
123276 */
123277 struct Fts3HashElem {
123278   Fts3HashElem *next, *prev; /* Next and previous elements in the table */
123279   void *data;                /* Data associated with this element */
123280   void *pKey; int nKey;      /* Key associated with this element */
123281 };
123282 
123283 /*
123284 ** There are 2 different modes of operation for a hash table:
123285 **
123286 **   FTS3_HASH_STRING        pKey points to a string that is nKey bytes long
123287 **                           (including the null-terminator, if any).  Case
123288 **                           is respected in comparisons.
123289 **
123290 **   FTS3_HASH_BINARY        pKey points to binary data nKey bytes long. 
123291 **                           memcmp() is used to compare keys.
123292 **
123293 ** A copy of the key is made if the copyKey parameter to fts3HashInit is 1.  
123294 */
123295 #define FTS3_HASH_STRING    1
123296 #define FTS3_HASH_BINARY    2
123297 
123298 /*
123299 ** Access routines.  To delete, insert a NULL pointer.
123300 */
123301 SQLITE_PRIVATE void sqlite3Fts3HashInit(Fts3Hash *pNew, char keyClass, char copyKey);
123302 SQLITE_PRIVATE void *sqlite3Fts3HashInsert(Fts3Hash*, const void *pKey, int nKey, void *pData);
123303 SQLITE_PRIVATE void *sqlite3Fts3HashFind(const Fts3Hash*, const void *pKey, int nKey);
123304 SQLITE_PRIVATE void sqlite3Fts3HashClear(Fts3Hash*);
123305 SQLITE_PRIVATE Fts3HashElem *sqlite3Fts3HashFindElem(const Fts3Hash *, const void *, int);
123306 
123307 /*
123308 ** Shorthand for the functions above
123309 */
123310 #define fts3HashInit     sqlite3Fts3HashInit
123311 #define fts3HashInsert   sqlite3Fts3HashInsert
123312 #define fts3HashFind     sqlite3Fts3HashFind
123313 #define fts3HashClear    sqlite3Fts3HashClear
123314 #define fts3HashFindElem sqlite3Fts3HashFindElem
123315 
123316 /*
123317 ** Macros for looping over all elements of a hash table.  The idiom is
123318 ** like this:
123319 **
123320 **   Fts3Hash h;
123321 **   Fts3HashElem *p;
123322 **   ...
123323 **   for(p=fts3HashFirst(&h); p; p=fts3HashNext(p)){
123324 **     SomeStructure *pData = fts3HashData(p);
123325 **     // do something with pData
123326 **   }
123327 */
123328 #define fts3HashFirst(H)  ((H)->first)
123329 #define fts3HashNext(E)   ((E)->next)
123330 #define fts3HashData(E)   ((E)->data)
123331 #define fts3HashKey(E)    ((E)->pKey)
123332 #define fts3HashKeysize(E) ((E)->nKey)
123333 
123334 /*
123335 ** Number of entries in a hash table
123336 */
123337 #define fts3HashCount(H)  ((H)->count)
123338 
123339 #endif /* _FTS3_HASH_H_ */
123340 
123341 /************** End of fts3_hash.h *******************************************/
123342 /************** Continuing where we left off in fts3Int.h ********************/
123343 
123344 /*
123345 ** This constant determines the maximum depth of an FTS expression tree
123346 ** that the library will create and use. FTS uses recursion to perform 
123347 ** various operations on the query tree, so the disadvantage of a large
123348 ** limit is that it may allow very large queries to use large amounts
123349 ** of stack space (perhaps causing a stack overflow).
123350 */
123351 #ifndef SQLITE_FTS3_MAX_EXPR_DEPTH
123352 # define SQLITE_FTS3_MAX_EXPR_DEPTH 12
123353 #endif
123354 
123355 
123356 /*
123357 ** This constant controls how often segments are merged. Once there are
123358 ** FTS3_MERGE_COUNT segments of level N, they are merged into a single
123359 ** segment of level N+1.
123360 */
123361 #define FTS3_MERGE_COUNT 16
123362 
123363 /*
123364 ** This is the maximum amount of data (in bytes) to store in the 
123365 ** Fts3Table.pendingTerms hash table. Normally, the hash table is
123366 ** populated as documents are inserted/updated/deleted in a transaction
123367 ** and used to create a new segment when the transaction is committed.
123368 ** However if this limit is reached midway through a transaction, a new 
123369 ** segment is created and the hash table cleared immediately.
123370 */
123371 #define FTS3_MAX_PENDING_DATA (1*1024*1024)
123372 
123373 /*
123374 ** Macro to return the number of elements in an array. SQLite has a
123375 ** similar macro called ArraySize(). Use a different name to avoid
123376 ** a collision when building an amalgamation with built-in FTS3.
123377 */
123378 #define SizeofArray(X) ((int)(sizeof(X)/sizeof(X[0])))
123379 
123380 
123381 #ifndef MIN
123382 # define MIN(x,y) ((x)<(y)?(x):(y))
123383 #endif
123384 #ifndef MAX
123385 # define MAX(x,y) ((x)>(y)?(x):(y))
123386 #endif
123387 
123388 /*
123389 ** Maximum length of a varint encoded integer. The varint format is different
123390 ** from that used by SQLite, so the maximum length is 10, not 9.
123391 */
123392 #define FTS3_VARINT_MAX 10
123393 
123394 /*
123395 ** FTS4 virtual tables may maintain multiple indexes - one index of all terms
123396 ** in the document set and zero or more prefix indexes. All indexes are stored
123397 ** as one or more b+-trees in the %_segments and %_segdir tables. 
123398 **
123399 ** It is possible to determine which index a b+-tree belongs to based on the
123400 ** value stored in the "%_segdir.level" column. Given this value L, the index
123401 ** that the b+-tree belongs to is (L<<10). In other words, all b+-trees with
123402 ** level values between 0 and 1023 (inclusive) belong to index 0, all levels
123403 ** between 1024 and 2047 to index 1, and so on.
123404 **
123405 ** It is considered impossible for an index to use more than 1024 levels. In 
123406 ** theory though this may happen, but only after at least 
123407 ** (FTS3_MERGE_COUNT^1024) separate flushes of the pending-terms tables.
123408 */
123409 #define FTS3_SEGDIR_MAXLEVEL      1024
123410 #define FTS3_SEGDIR_MAXLEVEL_STR "1024"
123411 
123412 /*
123413 ** The testcase() macro is only used by the amalgamation.  If undefined,
123414 ** make it a no-op.
123415 */
123416 #ifndef testcase
123417 # define testcase(X)
123418 #endif
123419 
123420 /*
123421 ** Terminator values for position-lists and column-lists.
123422 */
123423 #define POS_COLUMN  (1)     /* Column-list terminator */
123424 #define POS_END     (0)     /* Position-list terminator */ 
123425 
123426 /*
123427 ** This section provides definitions to allow the
123428 ** FTS3 extension to be compiled outside of the 
123429 ** amalgamation.
123430 */
123431 #ifndef SQLITE_AMALGAMATION
123432 /*
123433 ** Macros indicating that conditional expressions are always true or
123434 ** false.
123435 */
123436 #ifdef SQLITE_COVERAGE_TEST
123437 # define ALWAYS(x) (1)
123438 # define NEVER(X)  (0)
123439 #else
123440 # define ALWAYS(x) (x)
123441 # define NEVER(x)  (x)
123442 #endif
123443 
123444 /*
123445 ** Internal types used by SQLite.
123446 */
123447 typedef unsigned char u8;         /* 1-byte (or larger) unsigned integer */
123448 typedef short int i16;            /* 2-byte (or larger) signed integer */
123449 typedef unsigned int u32;         /* 4-byte unsigned integer */
123450 typedef sqlite3_uint64 u64;       /* 8-byte unsigned integer */
123451 typedef sqlite3_int64 i64;        /* 8-byte signed integer */
123452 
123453 /*
123454 ** Macro used to suppress compiler warnings for unused parameters.
123455 */
123456 #define UNUSED_PARAMETER(x) (void)(x)
123457 
123458 /*
123459 ** Activate assert() only if SQLITE_TEST is enabled.
123460 */
123461 #if !defined(NDEBUG) && !defined(SQLITE_DEBUG) 
123462 # define NDEBUG 1
123463 #endif
123464 
123465 /*
123466 ** The TESTONLY macro is used to enclose variable declarations or
123467 ** other bits of code that are needed to support the arguments
123468 ** within testcase() and assert() macros.
123469 */
123470 #if defined(SQLITE_DEBUG) || defined(SQLITE_COVERAGE_TEST)
123471 # define TESTONLY(X)  X
123472 #else
123473 # define TESTONLY(X)
123474 #endif
123475 
123476 #endif /* SQLITE_AMALGAMATION */
123477 
123478 #ifdef SQLITE_DEBUG
123479 SQLITE_PRIVATE int sqlite3Fts3Corrupt(void);
123480 # define FTS_CORRUPT_VTAB sqlite3Fts3Corrupt()
123481 #else
123482 # define FTS_CORRUPT_VTAB SQLITE_CORRUPT_VTAB
123483 #endif
123484 
123485 typedef struct Fts3Table Fts3Table;
123486 typedef struct Fts3Cursor Fts3Cursor;
123487 typedef struct Fts3Expr Fts3Expr;
123488 typedef struct Fts3Phrase Fts3Phrase;
123489 typedef struct Fts3PhraseToken Fts3PhraseToken;
123490 
123491 typedef struct Fts3Doclist Fts3Doclist;
123492 typedef struct Fts3SegFilter Fts3SegFilter;
123493 typedef struct Fts3DeferredToken Fts3DeferredToken;
123494 typedef struct Fts3SegReader Fts3SegReader;
123495 typedef struct Fts3MultiSegReader Fts3MultiSegReader;
123496 
123497 /*
123498 ** A connection to a fulltext index is an instance of the following
123499 ** structure. The xCreate and xConnect methods create an instance
123500 ** of this structure and xDestroy and xDisconnect free that instance.
123501 ** All other methods receive a pointer to the structure as one of their
123502 ** arguments.
123503 */
123504 struct Fts3Table {
123505   sqlite3_vtab base;              /* Base class used by SQLite core */
123506   sqlite3 *db;                    /* The database connection */
123507   const char *zDb;                /* logical database name */
123508   const char *zName;              /* virtual table name */
123509   int nColumn;                    /* number of named columns in virtual table */
123510   char **azColumn;                /* column names.  malloced */
123511   u8 *abNotindexed;               /* True for 'notindexed' columns */
123512   sqlite3_tokenizer *pTokenizer;  /* tokenizer for inserts and queries */
123513   char *zContentTbl;              /* content=xxx option, or NULL */
123514   char *zLanguageid;              /* languageid=xxx option, or NULL */
123515   u8 bAutoincrmerge;              /* True if automerge=1 */
123516   u32 nLeafAdd;                   /* Number of leaf blocks added this trans */
123517 
123518   /* Precompiled statements used by the implementation. Each of these 
123519   ** statements is run and reset within a single virtual table API call. 
123520   */
123521   sqlite3_stmt *aStmt[37];
123522 
123523   char *zReadExprlist;
123524   char *zWriteExprlist;
123525 
123526   int nNodeSize;                  /* Soft limit for node size */
123527   u8 bFts4;                       /* True for FTS4, false for FTS3 */
123528   u8 bHasStat;                    /* True if %_stat table exists */
123529   u8 bHasDocsize;                 /* True if %_docsize table exists */
123530   u8 bDescIdx;                    /* True if doclists are in reverse order */
123531   u8 bIgnoreSavepoint;            /* True to ignore xSavepoint invocations */
123532   int nPgsz;                      /* Page size for host database */
123533   char *zSegmentsTbl;             /* Name of %_segments table */
123534   sqlite3_blob *pSegments;        /* Blob handle open on %_segments table */
123535 
123536   /* 
123537   ** The following array of hash tables is used to buffer pending index 
123538   ** updates during transactions. All pending updates buffered at any one
123539   ** time must share a common language-id (see the FTS4 langid= feature).
123540   ** The current language id is stored in variable iPrevLangid.
123541   **
123542   ** A single FTS4 table may have multiple full-text indexes. For each index
123543   ** there is an entry in the aIndex[] array. Index 0 is an index of all the
123544   ** terms that appear in the document set. Each subsequent index in aIndex[]
123545   ** is an index of prefixes of a specific length.
123546   **
123547   ** Variable nPendingData contains an estimate the memory consumed by the 
123548   ** pending data structures, including hash table overhead, but not including
123549   ** malloc overhead.  When nPendingData exceeds nMaxPendingData, all hash
123550   ** tables are flushed to disk. Variable iPrevDocid is the docid of the most 
123551   ** recently inserted record.
123552   */
123553   int nIndex;                     /* Size of aIndex[] */
123554   struct Fts3Index {
123555     int nPrefix;                  /* Prefix length (0 for main terms index) */
123556     Fts3Hash hPending;            /* Pending terms table for this index */
123557   } *aIndex;
123558   int nMaxPendingData;            /* Max pending data before flush to disk */
123559   int nPendingData;               /* Current bytes of pending data */
123560   sqlite_int64 iPrevDocid;        /* Docid of most recently inserted document */
123561   int iPrevLangid;                /* Langid of recently inserted document */
123562 
123563 #if defined(SQLITE_DEBUG) || defined(SQLITE_COVERAGE_TEST)
123564   /* State variables used for validating that the transaction control
123565   ** methods of the virtual table are called at appropriate times.  These
123566   ** values do not contribute to FTS functionality; they are used for
123567   ** verifying the operation of the SQLite core.
123568   */
123569   int inTransaction;     /* True after xBegin but before xCommit/xRollback */
123570   int mxSavepoint;       /* Largest valid xSavepoint integer */
123571 #endif
123572 
123573 #ifdef SQLITE_TEST
123574   /* True to disable the incremental doclist optimization. This is controled
123575   ** by special insert command 'test-no-incr-doclist'.  */
123576   int bNoIncrDoclist;
123577 #endif
123578 };
123579 
123580 /*
123581 ** When the core wants to read from the virtual table, it creates a
123582 ** virtual table cursor (an instance of the following structure) using
123583 ** the xOpen method. Cursors are destroyed using the xClose method.
123584 */
123585 struct Fts3Cursor {
123586   sqlite3_vtab_cursor base;       /* Base class used by SQLite core */
123587   i16 eSearch;                    /* Search strategy (see below) */
123588   u8 isEof;                       /* True if at End Of Results */
123589   u8 isRequireSeek;               /* True if must seek pStmt to %_content row */
123590   sqlite3_stmt *pStmt;            /* Prepared statement in use by the cursor */
123591   Fts3Expr *pExpr;                /* Parsed MATCH query string */
123592   int iLangid;                    /* Language being queried for */
123593   int nPhrase;                    /* Number of matchable phrases in query */
123594   Fts3DeferredToken *pDeferred;   /* Deferred search tokens, if any */
123595   sqlite3_int64 iPrevId;          /* Previous id read from aDoclist */
123596   char *pNextId;                  /* Pointer into the body of aDoclist */
123597   char *aDoclist;                 /* List of docids for full-text queries */
123598   int nDoclist;                   /* Size of buffer at aDoclist */
123599   u8 bDesc;                       /* True to sort in descending order */
123600   int eEvalmode;                  /* An FTS3_EVAL_XX constant */
123601   int nRowAvg;                    /* Average size of database rows, in pages */
123602   sqlite3_int64 nDoc;             /* Documents in table */
123603   i64 iMinDocid;                  /* Minimum docid to return */
123604   i64 iMaxDocid;                  /* Maximum docid to return */
123605   int isMatchinfoNeeded;          /* True when aMatchinfo[] needs filling in */
123606   u32 *aMatchinfo;                /* Information about most recent match */
123607   int nMatchinfo;                 /* Number of elements in aMatchinfo[] */
123608   char *zMatchinfo;               /* Matchinfo specification */
123609 };
123610 
123611 #define FTS3_EVAL_FILTER    0
123612 #define FTS3_EVAL_NEXT      1
123613 #define FTS3_EVAL_MATCHINFO 2
123614 
123615 /*
123616 ** The Fts3Cursor.eSearch member is always set to one of the following.
123617 ** Actualy, Fts3Cursor.eSearch can be greater than or equal to
123618 ** FTS3_FULLTEXT_SEARCH.  If so, then Fts3Cursor.eSearch - 2 is the index
123619 ** of the column to be searched.  For example, in
123620 **
123621 **     CREATE VIRTUAL TABLE ex1 USING fts3(a,b,c,d);
123622 **     SELECT docid FROM ex1 WHERE b MATCH 'one two three';
123623 ** 
123624 ** Because the LHS of the MATCH operator is 2nd column "b",
123625 ** Fts3Cursor.eSearch will be set to FTS3_FULLTEXT_SEARCH+1.  (+0 for a,
123626 ** +1 for b, +2 for c, +3 for d.)  If the LHS of MATCH were "ex1" 
123627 ** indicating that all columns should be searched,
123628 ** then eSearch would be set to FTS3_FULLTEXT_SEARCH+4.
123629 */
123630 #define FTS3_FULLSCAN_SEARCH 0    /* Linear scan of %_content table */
123631 #define FTS3_DOCID_SEARCH    1    /* Lookup by rowid on %_content table */
123632 #define FTS3_FULLTEXT_SEARCH 2    /* Full-text index search */
123633 
123634 /*
123635 ** The lower 16-bits of the sqlite3_index_info.idxNum value set by
123636 ** the xBestIndex() method contains the Fts3Cursor.eSearch value described
123637 ** above. The upper 16-bits contain a combination of the following
123638 ** bits, used to describe extra constraints on full-text searches.
123639 */
123640 #define FTS3_HAVE_LANGID    0x00010000      /* languageid=? */
123641 #define FTS3_HAVE_DOCID_GE  0x00020000      /* docid>=? */
123642 #define FTS3_HAVE_DOCID_LE  0x00040000      /* docid<=? */
123643 
123644 struct Fts3Doclist {
123645   char *aAll;                    /* Array containing doclist (or NULL) */
123646   int nAll;                      /* Size of a[] in bytes */
123647   char *pNextDocid;              /* Pointer to next docid */
123648 
123649   sqlite3_int64 iDocid;          /* Current docid (if pList!=0) */
123650   int bFreeList;                 /* True if pList should be sqlite3_free()d */
123651   char *pList;                   /* Pointer to position list following iDocid */
123652   int nList;                     /* Length of position list */
123653 };
123654 
123655 /*
123656 ** A "phrase" is a sequence of one or more tokens that must match in
123657 ** sequence.  A single token is the base case and the most common case.
123658 ** For a sequence of tokens contained in double-quotes (i.e. "one two three")
123659 ** nToken will be the number of tokens in the string.
123660 */
123661 struct Fts3PhraseToken {
123662   char *z;                        /* Text of the token */
123663   int n;                          /* Number of bytes in buffer z */
123664   int isPrefix;                   /* True if token ends with a "*" character */
123665   int bFirst;                     /* True if token must appear at position 0 */
123666 
123667   /* Variables above this point are populated when the expression is
123668   ** parsed (by code in fts3_expr.c). Below this point the variables are
123669   ** used when evaluating the expression. */
123670   Fts3DeferredToken *pDeferred;   /* Deferred token object for this token */
123671   Fts3MultiSegReader *pSegcsr;    /* Segment-reader for this token */
123672 };
123673 
123674 struct Fts3Phrase {
123675   /* Cache of doclist for this phrase. */
123676   Fts3Doclist doclist;
123677   int bIncr;                 /* True if doclist is loaded incrementally */
123678   int iDoclistToken;
123679 
123680   /* Variables below this point are populated by fts3_expr.c when parsing 
123681   ** a MATCH expression. Everything above is part of the evaluation phase. 
123682   */
123683   int nToken;                /* Number of tokens in the phrase */
123684   int iColumn;               /* Index of column this phrase must match */
123685   Fts3PhraseToken aToken[1]; /* One entry for each token in the phrase */
123686 };
123687 
123688 /*
123689 ** A tree of these objects forms the RHS of a MATCH operator.
123690 **
123691 ** If Fts3Expr.eType is FTSQUERY_PHRASE and isLoaded is true, then aDoclist 
123692 ** points to a malloced buffer, size nDoclist bytes, containing the results 
123693 ** of this phrase query in FTS3 doclist format. As usual, the initial 
123694 ** "Length" field found in doclists stored on disk is omitted from this 
123695 ** buffer.
123696 **
123697 ** Variable aMI is used only for FTSQUERY_NEAR nodes to store the global
123698 ** matchinfo data. If it is not NULL, it points to an array of size nCol*3,
123699 ** where nCol is the number of columns in the queried FTS table. The array
123700 ** is populated as follows:
123701 **
123702 **   aMI[iCol*3 + 0] = Undefined
123703 **   aMI[iCol*3 + 1] = Number of occurrences
123704 **   aMI[iCol*3 + 2] = Number of rows containing at least one instance
123705 **
123706 ** The aMI array is allocated using sqlite3_malloc(). It should be freed 
123707 ** when the expression node is.
123708 */
123709 struct Fts3Expr {
123710   int eType;                 /* One of the FTSQUERY_XXX values defined below */
123711   int nNear;                 /* Valid if eType==FTSQUERY_NEAR */
123712   Fts3Expr *pParent;         /* pParent->pLeft==this or pParent->pRight==this */
123713   Fts3Expr *pLeft;           /* Left operand */
123714   Fts3Expr *pRight;          /* Right operand */
123715   Fts3Phrase *pPhrase;       /* Valid if eType==FTSQUERY_PHRASE */
123716 
123717   /* The following are used by the fts3_eval.c module. */
123718   sqlite3_int64 iDocid;      /* Current docid */
123719   u8 bEof;                   /* True this expression is at EOF already */
123720   u8 bStart;                 /* True if iDocid is valid */
123721   u8 bDeferred;              /* True if this expression is entirely deferred */
123722 
123723   u32 *aMI;
123724 };
123725 
123726 /*
123727 ** Candidate values for Fts3Query.eType. Note that the order of the first
123728 ** four values is in order of precedence when parsing expressions. For 
123729 ** example, the following:
123730 **
123731 **   "a OR b AND c NOT d NEAR e"
123732 **
123733 ** is equivalent to:
123734 **
123735 **   "a OR (b AND (c NOT (d NEAR e)))"
123736 */
123737 #define FTSQUERY_NEAR   1
123738 #define FTSQUERY_NOT    2
123739 #define FTSQUERY_AND    3
123740 #define FTSQUERY_OR     4
123741 #define FTSQUERY_PHRASE 5
123742 
123743 
123744 /* fts3_write.c */
123745 SQLITE_PRIVATE int sqlite3Fts3UpdateMethod(sqlite3_vtab*,int,sqlite3_value**,sqlite3_int64*);
123746 SQLITE_PRIVATE int sqlite3Fts3PendingTermsFlush(Fts3Table *);
123747 SQLITE_PRIVATE void sqlite3Fts3PendingTermsClear(Fts3Table *);
123748 SQLITE_PRIVATE int sqlite3Fts3Optimize(Fts3Table *);
123749 SQLITE_PRIVATE int sqlite3Fts3SegReaderNew(int, int, sqlite3_int64,
123750   sqlite3_int64, sqlite3_int64, const char *, int, Fts3SegReader**);
123751 SQLITE_PRIVATE int sqlite3Fts3SegReaderPending(
123752   Fts3Table*,int,const char*,int,int,Fts3SegReader**);
123753 SQLITE_PRIVATE void sqlite3Fts3SegReaderFree(Fts3SegReader *);
123754 SQLITE_PRIVATE int sqlite3Fts3AllSegdirs(Fts3Table*, int, int, int, sqlite3_stmt **);
123755 SQLITE_PRIVATE int sqlite3Fts3ReadBlock(Fts3Table*, sqlite3_int64, char **, int*, int*);
123756 
123757 SQLITE_PRIVATE int sqlite3Fts3SelectDoctotal(Fts3Table *, sqlite3_stmt **);
123758 SQLITE_PRIVATE int sqlite3Fts3SelectDocsize(Fts3Table *, sqlite3_int64, sqlite3_stmt **);
123759 
123760 #ifndef SQLITE_DISABLE_FTS4_DEFERRED
123761 SQLITE_PRIVATE void sqlite3Fts3FreeDeferredTokens(Fts3Cursor *);
123762 SQLITE_PRIVATE int sqlite3Fts3DeferToken(Fts3Cursor *, Fts3PhraseToken *, int);
123763 SQLITE_PRIVATE int sqlite3Fts3CacheDeferredDoclists(Fts3Cursor *);
123764 SQLITE_PRIVATE void sqlite3Fts3FreeDeferredDoclists(Fts3Cursor *);
123765 SQLITE_PRIVATE int sqlite3Fts3DeferredTokenList(Fts3DeferredToken *, char **, int *);
123766 #else
123767 # define sqlite3Fts3FreeDeferredTokens(x)
123768 # define sqlite3Fts3DeferToken(x,y,z) SQLITE_OK
123769 # define sqlite3Fts3CacheDeferredDoclists(x) SQLITE_OK
123770 # define sqlite3Fts3FreeDeferredDoclists(x)
123771 # define sqlite3Fts3DeferredTokenList(x,y,z) SQLITE_OK
123772 #endif
123773 
123774 SQLITE_PRIVATE void sqlite3Fts3SegmentsClose(Fts3Table *);
123775 SQLITE_PRIVATE int sqlite3Fts3MaxLevel(Fts3Table *, int *);
123776 
123777 /* Special values interpreted by sqlite3SegReaderCursor() */
123778 #define FTS3_SEGCURSOR_PENDING        -1
123779 #define FTS3_SEGCURSOR_ALL            -2
123780 
123781 SQLITE_PRIVATE int sqlite3Fts3SegReaderStart(Fts3Table*, Fts3MultiSegReader*, Fts3SegFilter*);
123782 SQLITE_PRIVATE int sqlite3Fts3SegReaderStep(Fts3Table *, Fts3MultiSegReader *);
123783 SQLITE_PRIVATE void sqlite3Fts3SegReaderFinish(Fts3MultiSegReader *);
123784 
123785 SQLITE_PRIVATE int sqlite3Fts3SegReaderCursor(Fts3Table *, 
123786     int, int, int, const char *, int, int, int, Fts3MultiSegReader *);
123787 
123788 /* Flags allowed as part of the 4th argument to SegmentReaderIterate() */
123789 #define FTS3_SEGMENT_REQUIRE_POS   0x00000001
123790 #define FTS3_SEGMENT_IGNORE_EMPTY  0x00000002
123791 #define FTS3_SEGMENT_COLUMN_FILTER 0x00000004
123792 #define FTS3_SEGMENT_PREFIX        0x00000008
123793 #define FTS3_SEGMENT_SCAN          0x00000010
123794 #define FTS3_SEGMENT_FIRST         0x00000020
123795 
123796 /* Type passed as 4th argument to SegmentReaderIterate() */
123797 struct Fts3SegFilter {
123798   const char *zTerm;
123799   int nTerm;
123800   int iCol;
123801   int flags;
123802 };
123803 
123804 struct Fts3MultiSegReader {
123805   /* Used internally by sqlite3Fts3SegReaderXXX() calls */
123806   Fts3SegReader **apSegment;      /* Array of Fts3SegReader objects */
123807   int nSegment;                   /* Size of apSegment array */
123808   int nAdvance;                   /* How many seg-readers to advance */
123809   Fts3SegFilter *pFilter;         /* Pointer to filter object */
123810   char *aBuffer;                  /* Buffer to merge doclists in */
123811   int nBuffer;                    /* Allocated size of aBuffer[] in bytes */
123812 
123813   int iColFilter;                 /* If >=0, filter for this column */
123814   int bRestart;
123815 
123816   /* Used by fts3.c only. */
123817   int nCost;                      /* Cost of running iterator */
123818   int bLookup;                    /* True if a lookup of a single entry. */
123819 
123820   /* Output values. Valid only after Fts3SegReaderStep() returns SQLITE_ROW. */
123821   char *zTerm;                    /* Pointer to term buffer */
123822   int nTerm;                      /* Size of zTerm in bytes */
123823   char *aDoclist;                 /* Pointer to doclist buffer */
123824   int nDoclist;                   /* Size of aDoclist[] in bytes */
123825 };
123826 
123827 SQLITE_PRIVATE int sqlite3Fts3Incrmerge(Fts3Table*,int,int);
123828 
123829 #define fts3GetVarint32(p, piVal) (                                           \
123830   (*(u8*)(p)&0x80) ? sqlite3Fts3GetVarint32(p, piVal) : (*piVal=*(u8*)(p), 1) \
123831 )
123832 
123833 /* fts3.c */
123834 SQLITE_PRIVATE int sqlite3Fts3PutVarint(char *, sqlite3_int64);
123835 SQLITE_PRIVATE int sqlite3Fts3GetVarint(const char *, sqlite_int64 *);
123836 SQLITE_PRIVATE int sqlite3Fts3GetVarint32(const char *, int *);
123837 SQLITE_PRIVATE int sqlite3Fts3VarintLen(sqlite3_uint64);
123838 SQLITE_PRIVATE void sqlite3Fts3Dequote(char *);
123839 SQLITE_PRIVATE void sqlite3Fts3DoclistPrev(int,char*,int,char**,sqlite3_int64*,int*,u8*);
123840 SQLITE_PRIVATE int sqlite3Fts3EvalPhraseStats(Fts3Cursor *, Fts3Expr *, u32 *);
123841 SQLITE_PRIVATE int sqlite3Fts3FirstFilter(sqlite3_int64, char *, int, char *);
123842 SQLITE_PRIVATE void sqlite3Fts3CreateStatTable(int*, Fts3Table*);
123843 
123844 /* fts3_tokenizer.c */
123845 SQLITE_PRIVATE const char *sqlite3Fts3NextToken(const char *, int *);
123846 SQLITE_PRIVATE int sqlite3Fts3InitHashTable(sqlite3 *, Fts3Hash *, const char *);
123847 SQLITE_PRIVATE int sqlite3Fts3InitTokenizer(Fts3Hash *pHash, const char *, 
123848     sqlite3_tokenizer **, char **
123849 );
123850 SQLITE_PRIVATE int sqlite3Fts3IsIdChar(char);
123851 
123852 /* fts3_snippet.c */
123853 SQLITE_PRIVATE void sqlite3Fts3Offsets(sqlite3_context*, Fts3Cursor*);
123854 SQLITE_PRIVATE void sqlite3Fts3Snippet(sqlite3_context *, Fts3Cursor *, const char *,
123855   const char *, const char *, int, int
123856 );
123857 SQLITE_PRIVATE void sqlite3Fts3Matchinfo(sqlite3_context *, Fts3Cursor *, const char *);
123858 
123859 /* fts3_expr.c */
123860 SQLITE_PRIVATE int sqlite3Fts3ExprParse(sqlite3_tokenizer *, int,
123861   char **, int, int, int, const char *, int, Fts3Expr **, char **
123862 );
123863 SQLITE_PRIVATE void sqlite3Fts3ExprFree(Fts3Expr *);
123864 #ifdef SQLITE_TEST
123865 SQLITE_PRIVATE int sqlite3Fts3ExprInitTestInterface(sqlite3 *db);
123866 SQLITE_PRIVATE int sqlite3Fts3InitTerm(sqlite3 *db);
123867 #endif
123868 
123869 SQLITE_PRIVATE int sqlite3Fts3OpenTokenizer(sqlite3_tokenizer *, int, const char *, int,
123870   sqlite3_tokenizer_cursor **
123871 );
123872 
123873 /* fts3_aux.c */
123874 SQLITE_PRIVATE int sqlite3Fts3InitAux(sqlite3 *db);
123875 
123876 SQLITE_PRIVATE void sqlite3Fts3EvalPhraseCleanup(Fts3Phrase *);
123877 
123878 SQLITE_PRIVATE int sqlite3Fts3MsrIncrStart(
123879     Fts3Table*, Fts3MultiSegReader*, int, const char*, int);
123880 SQLITE_PRIVATE int sqlite3Fts3MsrIncrNext(
123881     Fts3Table *, Fts3MultiSegReader *, sqlite3_int64 *, char **, int *);
123882 SQLITE_PRIVATE int sqlite3Fts3EvalPhrasePoslist(Fts3Cursor *, Fts3Expr *, int iCol, char **); 
123883 SQLITE_PRIVATE int sqlite3Fts3MsrOvfl(Fts3Cursor *, Fts3MultiSegReader *, int *);
123884 SQLITE_PRIVATE int sqlite3Fts3MsrIncrRestart(Fts3MultiSegReader *pCsr);
123885 
123886 /* fts3_tokenize_vtab.c */
123887 SQLITE_PRIVATE int sqlite3Fts3InitTok(sqlite3*, Fts3Hash *);
123888 
123889 /* fts3_unicode2.c (functions generated by parsing unicode text files) */
123890 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
123891 SQLITE_PRIVATE int sqlite3FtsUnicodeFold(int, int);
123892 SQLITE_PRIVATE int sqlite3FtsUnicodeIsalnum(int);
123893 SQLITE_PRIVATE int sqlite3FtsUnicodeIsdiacritic(int);
123894 #endif
123895 
123896 #endif /* !SQLITE_CORE || SQLITE_ENABLE_FTS3 */
123897 #endif /* _FTSINT_H */
123898 
123899 /************** End of fts3Int.h *********************************************/
123900 /************** Continuing where we left off in fts3.c ***********************/
123901 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
123902 
123903 #if defined(SQLITE_ENABLE_FTS3) && !defined(SQLITE_CORE)
123904 # define SQLITE_CORE 1
123905 #endif
123906 
123907 /* #include <assert.h> */
123908 /* #include <stdlib.h> */
123909 /* #include <stddef.h> */
123910 /* #include <stdio.h> */
123911 /* #include <string.h> */
123912 /* #include <stdarg.h> */
123913 
123914 #ifndef SQLITE_CORE 
123915   SQLITE_EXTENSION_INIT1
123916 #endif
123917 
123918 static int fts3EvalNext(Fts3Cursor *pCsr);
123919 static int fts3EvalStart(Fts3Cursor *pCsr);
123920 static int fts3TermSegReaderCursor(
123921     Fts3Cursor *, const char *, int, int, Fts3MultiSegReader **);
123922 
123923 /* 
123924 ** Write a 64-bit variable-length integer to memory starting at p[0].
123925 ** The length of data written will be between 1 and FTS3_VARINT_MAX bytes.
123926 ** The number of bytes written is returned.
123927 */
123928 SQLITE_PRIVATE int sqlite3Fts3PutVarint(char *p, sqlite_int64 v){
123929   unsigned char *q = (unsigned char *) p;
123930   sqlite_uint64 vu = v;
123931   do{
123932     *q++ = (unsigned char) ((vu & 0x7f) | 0x80);
123933     vu >>= 7;
123934   }while( vu!=0 );
123935   q[-1] &= 0x7f;  /* turn off high bit in final byte */
123936   assert( q - (unsigned char *)p <= FTS3_VARINT_MAX );
123937   return (int) (q - (unsigned char *)p);
123938 }
123939 
123940 #define GETVARINT_STEP(v, ptr, shift, mask1, mask2, var, ret) \
123941   v = (v & mask1) | ( (*ptr++) << shift );                    \
123942   if( (v & mask2)==0 ){ var = v; return ret; }
123943 #define GETVARINT_INIT(v, ptr, shift, mask1, mask2, var, ret) \
123944   v = (*ptr++);                                               \
123945   if( (v & mask2)==0 ){ var = v; return ret; }
123946 
123947 /* 
123948 ** Read a 64-bit variable-length integer from memory starting at p[0].
123949 ** Return the number of bytes read, or 0 on error.
123950 ** The value is stored in *v.
123951 */
123952 SQLITE_PRIVATE int sqlite3Fts3GetVarint(const char *p, sqlite_int64 *v){
123953   const char *pStart = p;
123954   u32 a;
123955   u64 b;
123956   int shift;
123957 
123958   GETVARINT_INIT(a, p, 0,  0x00,     0x80, *v, 1);
123959   GETVARINT_STEP(a, p, 7,  0x7F,     0x4000, *v, 2);
123960   GETVARINT_STEP(a, p, 14, 0x3FFF,   0x200000, *v, 3);
123961   GETVARINT_STEP(a, p, 21, 0x1FFFFF, 0x10000000, *v, 4);
123962   b = (a & 0x0FFFFFFF );
123963 
123964   for(shift=28; shift<=63; shift+=7){
123965     u64 c = *p++;
123966     b += (c&0x7F) << shift;
123967     if( (c & 0x80)==0 ) break;
123968   }
123969   *v = b;
123970   return (int)(p - pStart);
123971 }
123972 
123973 /*
123974 ** Similar to sqlite3Fts3GetVarint(), except that the output is truncated to a
123975 ** 32-bit integer before it is returned.
123976 */
123977 SQLITE_PRIVATE int sqlite3Fts3GetVarint32(const char *p, int *pi){
123978   u32 a;
123979 
123980 #ifndef fts3GetVarint32
123981   GETVARINT_INIT(a, p, 0,  0x00,     0x80, *pi, 1);
123982 #else
123983   a = (*p++);
123984   assert( a & 0x80 );
123985 #endif
123986 
123987   GETVARINT_STEP(a, p, 7,  0x7F,     0x4000, *pi, 2);
123988   GETVARINT_STEP(a, p, 14, 0x3FFF,   0x200000, *pi, 3);
123989   GETVARINT_STEP(a, p, 21, 0x1FFFFF, 0x10000000, *pi, 4);
123990   a = (a & 0x0FFFFFFF );
123991   *pi = (int)(a | ((u32)(*p & 0x0F) << 28));
123992   return 5;
123993 }
123994 
123995 /*
123996 ** Return the number of bytes required to encode v as a varint
123997 */
123998 SQLITE_PRIVATE int sqlite3Fts3VarintLen(sqlite3_uint64 v){
123999   int i = 0;
124000   do{
124001     i++;
124002     v >>= 7;
124003   }while( v!=0 );
124004   return i;
124005 }
124006 
124007 /*
124008 ** Convert an SQL-style quoted string into a normal string by removing
124009 ** the quote characters.  The conversion is done in-place.  If the
124010 ** input does not begin with a quote character, then this routine
124011 ** is a no-op.
124012 **
124013 ** Examples:
124014 **
124015 **     "abc"   becomes   abc
124016 **     'xyz'   becomes   xyz
124017 **     [pqr]   becomes   pqr
124018 **     `mno`   becomes   mno
124019 **
124020 */
124021 SQLITE_PRIVATE void sqlite3Fts3Dequote(char *z){
124022   char quote;                     /* Quote character (if any ) */
124023 
124024   quote = z[0];
124025   if( quote=='[' || quote=='\'' || quote=='"' || quote=='`' ){
124026     int iIn = 1;                  /* Index of next byte to read from input */
124027     int iOut = 0;                 /* Index of next byte to write to output */
124028 
124029     /* If the first byte was a '[', then the close-quote character is a ']' */
124030     if( quote=='[' ) quote = ']';  
124031 
124032     while( ALWAYS(z[iIn]) ){
124033       if( z[iIn]==quote ){
124034         if( z[iIn+1]!=quote ) break;
124035         z[iOut++] = quote;
124036         iIn += 2;
124037       }else{
124038         z[iOut++] = z[iIn++];
124039       }
124040     }
124041     z[iOut] = '\0';
124042   }
124043 }
124044 
124045 /*
124046 ** Read a single varint from the doclist at *pp and advance *pp to point
124047 ** to the first byte past the end of the varint.  Add the value of the varint
124048 ** to *pVal.
124049 */
124050 static void fts3GetDeltaVarint(char **pp, sqlite3_int64 *pVal){
124051   sqlite3_int64 iVal;
124052   *pp += sqlite3Fts3GetVarint(*pp, &iVal);
124053   *pVal += iVal;
124054 }
124055 
124056 /*
124057 ** When this function is called, *pp points to the first byte following a
124058 ** varint that is part of a doclist (or position-list, or any other list
124059 ** of varints). This function moves *pp to point to the start of that varint,
124060 ** and sets *pVal by the varint value.
124061 **
124062 ** Argument pStart points to the first byte of the doclist that the
124063 ** varint is part of.
124064 */
124065 static void fts3GetReverseVarint(
124066   char **pp, 
124067   char *pStart, 
124068   sqlite3_int64 *pVal
124069 ){
124070   sqlite3_int64 iVal;
124071   char *p;
124072 
124073   /* Pointer p now points at the first byte past the varint we are 
124074   ** interested in. So, unless the doclist is corrupt, the 0x80 bit is
124075   ** clear on character p[-1]. */
124076   for(p = (*pp)-2; p>=pStart && *p&0x80; p--);
124077   p++;
124078   *pp = p;
124079 
124080   sqlite3Fts3GetVarint(p, &iVal);
124081   *pVal = iVal;
124082 }
124083 
124084 /*
124085 ** The xDisconnect() virtual table method.
124086 */
124087 static int fts3DisconnectMethod(sqlite3_vtab *pVtab){
124088   Fts3Table *p = (Fts3Table *)pVtab;
124089   int i;
124090 
124091   assert( p->nPendingData==0 );
124092   assert( p->pSegments==0 );
124093 
124094   /* Free any prepared statements held */
124095   for(i=0; i<SizeofArray(p->aStmt); i++){
124096     sqlite3_finalize(p->aStmt[i]);
124097   }
124098   sqlite3_free(p->zSegmentsTbl);
124099   sqlite3_free(p->zReadExprlist);
124100   sqlite3_free(p->zWriteExprlist);
124101   sqlite3_free(p->zContentTbl);
124102   sqlite3_free(p->zLanguageid);
124103 
124104   /* Invoke the tokenizer destructor to free the tokenizer. */
124105   p->pTokenizer->pModule->xDestroy(p->pTokenizer);
124106 
124107   sqlite3_free(p);
124108   return SQLITE_OK;
124109 }
124110 
124111 /*
124112 ** Construct one or more SQL statements from the format string given
124113 ** and then evaluate those statements. The success code is written
124114 ** into *pRc.
124115 **
124116 ** If *pRc is initially non-zero then this routine is a no-op.
124117 */
124118 static void fts3DbExec(
124119   int *pRc,              /* Success code */
124120   sqlite3 *db,           /* Database in which to run SQL */
124121   const char *zFormat,   /* Format string for SQL */
124122   ...                    /* Arguments to the format string */
124123 ){
124124   va_list ap;
124125   char *zSql;
124126   if( *pRc ) return;
124127   va_start(ap, zFormat);
124128   zSql = sqlite3_vmprintf(zFormat, ap);
124129   va_end(ap);
124130   if( zSql==0 ){
124131     *pRc = SQLITE_NOMEM;
124132   }else{
124133     *pRc = sqlite3_exec(db, zSql, 0, 0, 0);
124134     sqlite3_free(zSql);
124135   }
124136 }
124137 
124138 /*
124139 ** The xDestroy() virtual table method.
124140 */
124141 static int fts3DestroyMethod(sqlite3_vtab *pVtab){
124142   Fts3Table *p = (Fts3Table *)pVtab;
124143   int rc = SQLITE_OK;              /* Return code */
124144   const char *zDb = p->zDb;        /* Name of database (e.g. "main", "temp") */
124145   sqlite3 *db = p->db;             /* Database handle */
124146 
124147   /* Drop the shadow tables */
124148   if( p->zContentTbl==0 ){
124149     fts3DbExec(&rc, db, "DROP TABLE IF EXISTS %Q.'%q_content'", zDb, p->zName);
124150   }
124151   fts3DbExec(&rc, db, "DROP TABLE IF EXISTS %Q.'%q_segments'", zDb,p->zName);
124152   fts3DbExec(&rc, db, "DROP TABLE IF EXISTS %Q.'%q_segdir'", zDb, p->zName);
124153   fts3DbExec(&rc, db, "DROP TABLE IF EXISTS %Q.'%q_docsize'", zDb, p->zName);
124154   fts3DbExec(&rc, db, "DROP TABLE IF EXISTS %Q.'%q_stat'", zDb, p->zName);
124155 
124156   /* If everything has worked, invoke fts3DisconnectMethod() to free the
124157   ** memory associated with the Fts3Table structure and return SQLITE_OK.
124158   ** Otherwise, return an SQLite error code.
124159   */
124160   return (rc==SQLITE_OK ? fts3DisconnectMethod(pVtab) : rc);
124161 }
124162 
124163 
124164 /*
124165 ** Invoke sqlite3_declare_vtab() to declare the schema for the FTS3 table
124166 ** passed as the first argument. This is done as part of the xConnect()
124167 ** and xCreate() methods.
124168 **
124169 ** If *pRc is non-zero when this function is called, it is a no-op. 
124170 ** Otherwise, if an error occurs, an SQLite error code is stored in *pRc
124171 ** before returning.
124172 */
124173 static void fts3DeclareVtab(int *pRc, Fts3Table *p){
124174   if( *pRc==SQLITE_OK ){
124175     int i;                        /* Iterator variable */
124176     int rc;                       /* Return code */
124177     char *zSql;                   /* SQL statement passed to declare_vtab() */
124178     char *zCols;                  /* List of user defined columns */
124179     const char *zLanguageid;
124180 
124181     zLanguageid = (p->zLanguageid ? p->zLanguageid : "__langid");
124182     sqlite3_vtab_config(p->db, SQLITE_VTAB_CONSTRAINT_SUPPORT, 1);
124183 
124184     /* Create a list of user columns for the virtual table */
124185     zCols = sqlite3_mprintf("%Q, ", p->azColumn[0]);
124186     for(i=1; zCols && i<p->nColumn; i++){
124187       zCols = sqlite3_mprintf("%z%Q, ", zCols, p->azColumn[i]);
124188     }
124189 
124190     /* Create the whole "CREATE TABLE" statement to pass to SQLite */
124191     zSql = sqlite3_mprintf(
124192         "CREATE TABLE x(%s %Q HIDDEN, docid HIDDEN, %Q HIDDEN)", 
124193         zCols, p->zName, zLanguageid
124194     );
124195     if( !zCols || !zSql ){
124196       rc = SQLITE_NOMEM;
124197     }else{
124198       rc = sqlite3_declare_vtab(p->db, zSql);
124199     }
124200 
124201     sqlite3_free(zSql);
124202     sqlite3_free(zCols);
124203     *pRc = rc;
124204   }
124205 }
124206 
124207 /*
124208 ** Create the %_stat table if it does not already exist.
124209 */
124210 SQLITE_PRIVATE void sqlite3Fts3CreateStatTable(int *pRc, Fts3Table *p){
124211   fts3DbExec(pRc, p->db, 
124212       "CREATE TABLE IF NOT EXISTS %Q.'%q_stat'"
124213           "(id INTEGER PRIMARY KEY, value BLOB);",
124214       p->zDb, p->zName
124215   );
124216   if( (*pRc)==SQLITE_OK ) p->bHasStat = 1;
124217 }
124218 
124219 /*
124220 ** Create the backing store tables (%_content, %_segments and %_segdir)
124221 ** required by the FTS3 table passed as the only argument. This is done
124222 ** as part of the vtab xCreate() method.
124223 **
124224 ** If the p->bHasDocsize boolean is true (indicating that this is an
124225 ** FTS4 table, not an FTS3 table) then also create the %_docsize and
124226 ** %_stat tables required by FTS4.
124227 */
124228 static int fts3CreateTables(Fts3Table *p){
124229   int rc = SQLITE_OK;             /* Return code */
124230   int i;                          /* Iterator variable */
124231   sqlite3 *db = p->db;            /* The database connection */
124232 
124233   if( p->zContentTbl==0 ){
124234     const char *zLanguageid = p->zLanguageid;
124235     char *zContentCols;           /* Columns of %_content table */
124236 
124237     /* Create a list of user columns for the content table */
124238     zContentCols = sqlite3_mprintf("docid INTEGER PRIMARY KEY");
124239     for(i=0; zContentCols && i<p->nColumn; i++){
124240       char *z = p->azColumn[i];
124241       zContentCols = sqlite3_mprintf("%z, 'c%d%q'", zContentCols, i, z);
124242     }
124243     if( zLanguageid && zContentCols ){
124244       zContentCols = sqlite3_mprintf("%z, langid", zContentCols, zLanguageid);
124245     }
124246     if( zContentCols==0 ) rc = SQLITE_NOMEM;
124247   
124248     /* Create the content table */
124249     fts3DbExec(&rc, db, 
124250        "CREATE TABLE %Q.'%q_content'(%s)",
124251        p->zDb, p->zName, zContentCols
124252     );
124253     sqlite3_free(zContentCols);
124254   }
124255 
124256   /* Create other tables */
124257   fts3DbExec(&rc, db, 
124258       "CREATE TABLE %Q.'%q_segments'(blockid INTEGER PRIMARY KEY, block BLOB);",
124259       p->zDb, p->zName
124260   );
124261   fts3DbExec(&rc, db, 
124262       "CREATE TABLE %Q.'%q_segdir'("
124263         "level INTEGER,"
124264         "idx INTEGER,"
124265         "start_block INTEGER,"
124266         "leaves_end_block INTEGER,"
124267         "end_block INTEGER,"
124268         "root BLOB,"
124269         "PRIMARY KEY(level, idx)"
124270       ");",
124271       p->zDb, p->zName
124272   );
124273   if( p->bHasDocsize ){
124274     fts3DbExec(&rc, db, 
124275         "CREATE TABLE %Q.'%q_docsize'(docid INTEGER PRIMARY KEY, size BLOB);",
124276         p->zDb, p->zName
124277     );
124278   }
124279   assert( p->bHasStat==p->bFts4 );
124280   if( p->bHasStat ){
124281     sqlite3Fts3CreateStatTable(&rc, p);
124282   }
124283   return rc;
124284 }
124285 
124286 /*
124287 ** Store the current database page-size in bytes in p->nPgsz.
124288 **
124289 ** If *pRc is non-zero when this function is called, it is a no-op. 
124290 ** Otherwise, if an error occurs, an SQLite error code is stored in *pRc
124291 ** before returning.
124292 */
124293 static void fts3DatabasePageSize(int *pRc, Fts3Table *p){
124294   if( *pRc==SQLITE_OK ){
124295     int rc;                       /* Return code */
124296     char *zSql;                   /* SQL text "PRAGMA %Q.page_size" */
124297     sqlite3_stmt *pStmt;          /* Compiled "PRAGMA %Q.page_size" statement */
124298   
124299     zSql = sqlite3_mprintf("PRAGMA %Q.page_size", p->zDb);
124300     if( !zSql ){
124301       rc = SQLITE_NOMEM;
124302     }else{
124303       rc = sqlite3_prepare(p->db, zSql, -1, &pStmt, 0);
124304       if( rc==SQLITE_OK ){
124305         sqlite3_step(pStmt);
124306         p->nPgsz = sqlite3_column_int(pStmt, 0);
124307         rc = sqlite3_finalize(pStmt);
124308       }else if( rc==SQLITE_AUTH ){
124309         p->nPgsz = 1024;
124310         rc = SQLITE_OK;
124311       }
124312     }
124313     assert( p->nPgsz>0 || rc!=SQLITE_OK );
124314     sqlite3_free(zSql);
124315     *pRc = rc;
124316   }
124317 }
124318 
124319 /*
124320 ** "Special" FTS4 arguments are column specifications of the following form:
124321 **
124322 **   <key> = <value>
124323 **
124324 ** There may not be whitespace surrounding the "=" character. The <value> 
124325 ** term may be quoted, but the <key> may not.
124326 */
124327 static int fts3IsSpecialColumn(
124328   const char *z, 
124329   int *pnKey,
124330   char **pzValue
124331 ){
124332   char *zValue;
124333   const char *zCsr = z;
124334 
124335   while( *zCsr!='=' ){
124336     if( *zCsr=='\0' ) return 0;
124337     zCsr++;
124338   }
124339 
124340   *pnKey = (int)(zCsr-z);
124341   zValue = sqlite3_mprintf("%s", &zCsr[1]);
124342   if( zValue ){
124343     sqlite3Fts3Dequote(zValue);
124344   }
124345   *pzValue = zValue;
124346   return 1;
124347 }
124348 
124349 /*
124350 ** Append the output of a printf() style formatting to an existing string.
124351 */
124352 static void fts3Appendf(
124353   int *pRc,                       /* IN/OUT: Error code */
124354   char **pz,                      /* IN/OUT: Pointer to string buffer */
124355   const char *zFormat,            /* Printf format string to append */
124356   ...                             /* Arguments for printf format string */
124357 ){
124358   if( *pRc==SQLITE_OK ){
124359     va_list ap;
124360     char *z;
124361     va_start(ap, zFormat);
124362     z = sqlite3_vmprintf(zFormat, ap);
124363     va_end(ap);
124364     if( z && *pz ){
124365       char *z2 = sqlite3_mprintf("%s%s", *pz, z);
124366       sqlite3_free(z);
124367       z = z2;
124368     }
124369     if( z==0 ) *pRc = SQLITE_NOMEM;
124370     sqlite3_free(*pz);
124371     *pz = z;
124372   }
124373 }
124374 
124375 /*
124376 ** Return a copy of input string zInput enclosed in double-quotes (") and
124377 ** with all double quote characters escaped. For example:
124378 **
124379 **     fts3QuoteId("un \"zip\"")   ->    "un \"\"zip\"\""
124380 **
124381 ** The pointer returned points to memory obtained from sqlite3_malloc(). It
124382 ** is the callers responsibility to call sqlite3_free() to release this
124383 ** memory.
124384 */
124385 static char *fts3QuoteId(char const *zInput){
124386   int nRet;
124387   char *zRet;
124388   nRet = 2 + (int)strlen(zInput)*2 + 1;
124389   zRet = sqlite3_malloc(nRet);
124390   if( zRet ){
124391     int i;
124392     char *z = zRet;
124393     *(z++) = '"';
124394     for(i=0; zInput[i]; i++){
124395       if( zInput[i]=='"' ) *(z++) = '"';
124396       *(z++) = zInput[i];
124397     }
124398     *(z++) = '"';
124399     *(z++) = '\0';
124400   }
124401   return zRet;
124402 }
124403 
124404 /*
124405 ** Return a list of comma separated SQL expressions and a FROM clause that 
124406 ** could be used in a SELECT statement such as the following:
124407 **
124408 **     SELECT <list of expressions> FROM %_content AS x ...
124409 **
124410 ** to return the docid, followed by each column of text data in order
124411 ** from left to write. If parameter zFunc is not NULL, then instead of
124412 ** being returned directly each column of text data is passed to an SQL
124413 ** function named zFunc first. For example, if zFunc is "unzip" and the
124414 ** table has the three user-defined columns "a", "b", and "c", the following
124415 ** string is returned:
124416 **
124417 **     "docid, unzip(x.'a'), unzip(x.'b'), unzip(x.'c') FROM %_content AS x"
124418 **
124419 ** The pointer returned points to a buffer allocated by sqlite3_malloc(). It
124420 ** is the responsibility of the caller to eventually free it.
124421 **
124422 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op (and
124423 ** a NULL pointer is returned). Otherwise, if an OOM error is encountered
124424 ** by this function, NULL is returned and *pRc is set to SQLITE_NOMEM. If
124425 ** no error occurs, *pRc is left unmodified.
124426 */
124427 static char *fts3ReadExprList(Fts3Table *p, const char *zFunc, int *pRc){
124428   char *zRet = 0;
124429   char *zFree = 0;
124430   char *zFunction;
124431   int i;
124432 
124433   if( p->zContentTbl==0 ){
124434     if( !zFunc ){
124435       zFunction = "";
124436     }else{
124437       zFree = zFunction = fts3QuoteId(zFunc);
124438     }
124439     fts3Appendf(pRc, &zRet, "docid");
124440     for(i=0; i<p->nColumn; i++){
124441       fts3Appendf(pRc, &zRet, ",%s(x.'c%d%q')", zFunction, i, p->azColumn[i]);
124442     }
124443     if( p->zLanguageid ){
124444       fts3Appendf(pRc, &zRet, ", x.%Q", "langid");
124445     }
124446     sqlite3_free(zFree);
124447   }else{
124448     fts3Appendf(pRc, &zRet, "rowid");
124449     for(i=0; i<p->nColumn; i++){
124450       fts3Appendf(pRc, &zRet, ", x.'%q'", p->azColumn[i]);
124451     }
124452     if( p->zLanguageid ){
124453       fts3Appendf(pRc, &zRet, ", x.%Q", p->zLanguageid);
124454     }
124455   }
124456   fts3Appendf(pRc, &zRet, " FROM '%q'.'%q%s' AS x", 
124457       p->zDb,
124458       (p->zContentTbl ? p->zContentTbl : p->zName),
124459       (p->zContentTbl ? "" : "_content")
124460   );
124461   return zRet;
124462 }
124463 
124464 /*
124465 ** Return a list of N comma separated question marks, where N is the number
124466 ** of columns in the %_content table (one for the docid plus one for each
124467 ** user-defined text column).
124468 **
124469 ** If argument zFunc is not NULL, then all but the first question mark
124470 ** is preceded by zFunc and an open bracket, and followed by a closed
124471 ** bracket. For example, if zFunc is "zip" and the FTS3 table has three 
124472 ** user-defined text columns, the following string is returned:
124473 **
124474 **     "?, zip(?), zip(?), zip(?)"
124475 **
124476 ** The pointer returned points to a buffer allocated by sqlite3_malloc(). It
124477 ** is the responsibility of the caller to eventually free it.
124478 **
124479 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op (and
124480 ** a NULL pointer is returned). Otherwise, if an OOM error is encountered
124481 ** by this function, NULL is returned and *pRc is set to SQLITE_NOMEM. If
124482 ** no error occurs, *pRc is left unmodified.
124483 */
124484 static char *fts3WriteExprList(Fts3Table *p, const char *zFunc, int *pRc){
124485   char *zRet = 0;
124486   char *zFree = 0;
124487   char *zFunction;
124488   int i;
124489 
124490   if( !zFunc ){
124491     zFunction = "";
124492   }else{
124493     zFree = zFunction = fts3QuoteId(zFunc);
124494   }
124495   fts3Appendf(pRc, &zRet, "?");
124496   for(i=0; i<p->nColumn; i++){
124497     fts3Appendf(pRc, &zRet, ",%s(?)", zFunction);
124498   }
124499   if( p->zLanguageid ){
124500     fts3Appendf(pRc, &zRet, ", ?");
124501   }
124502   sqlite3_free(zFree);
124503   return zRet;
124504 }
124505 
124506 /*
124507 ** This function interprets the string at (*pp) as a non-negative integer
124508 ** value. It reads the integer and sets *pnOut to the value read, then 
124509 ** sets *pp to point to the byte immediately following the last byte of
124510 ** the integer value.
124511 **
124512 ** Only decimal digits ('0'..'9') may be part of an integer value. 
124513 **
124514 ** If *pp does not being with a decimal digit SQLITE_ERROR is returned and
124515 ** the output value undefined. Otherwise SQLITE_OK is returned.
124516 **
124517 ** This function is used when parsing the "prefix=" FTS4 parameter.
124518 */
124519 static int fts3GobbleInt(const char **pp, int *pnOut){
124520   const char *p;                  /* Iterator pointer */
124521   int nInt = 0;                   /* Output value */
124522 
124523   for(p=*pp; p[0]>='0' && p[0]<='9'; p++){
124524     nInt = nInt * 10 + (p[0] - '0');
124525   }
124526   if( p==*pp ) return SQLITE_ERROR;
124527   *pnOut = nInt;
124528   *pp = p;
124529   return SQLITE_OK;
124530 }
124531 
124532 /*
124533 ** This function is called to allocate an array of Fts3Index structures
124534 ** representing the indexes maintained by the current FTS table. FTS tables
124535 ** always maintain the main "terms" index, but may also maintain one or
124536 ** more "prefix" indexes, depending on the value of the "prefix=" parameter
124537 ** (if any) specified as part of the CREATE VIRTUAL TABLE statement.
124538 **
124539 ** Argument zParam is passed the value of the "prefix=" option if one was
124540 ** specified, or NULL otherwise.
124541 **
124542 ** If no error occurs, SQLITE_OK is returned and *apIndex set to point to
124543 ** the allocated array. *pnIndex is set to the number of elements in the
124544 ** array. If an error does occur, an SQLite error code is returned.
124545 **
124546 ** Regardless of whether or not an error is returned, it is the responsibility
124547 ** of the caller to call sqlite3_free() on the output array to free it.
124548 */
124549 static int fts3PrefixParameter(
124550   const char *zParam,             /* ABC in prefix=ABC parameter to parse */
124551   int *pnIndex,                   /* OUT: size of *apIndex[] array */
124552   struct Fts3Index **apIndex      /* OUT: Array of indexes for this table */
124553 ){
124554   struct Fts3Index *aIndex;       /* Allocated array */
124555   int nIndex = 1;                 /* Number of entries in array */
124556 
124557   if( zParam && zParam[0] ){
124558     const char *p;
124559     nIndex++;
124560     for(p=zParam; *p; p++){
124561       if( *p==',' ) nIndex++;
124562     }
124563   }
124564 
124565   aIndex = sqlite3_malloc(sizeof(struct Fts3Index) * nIndex);
124566   *apIndex = aIndex;
124567   *pnIndex = nIndex;
124568   if( !aIndex ){
124569     return SQLITE_NOMEM;
124570   }
124571 
124572   memset(aIndex, 0, sizeof(struct Fts3Index) * nIndex);
124573   if( zParam ){
124574     const char *p = zParam;
124575     int i;
124576     for(i=1; i<nIndex; i++){
124577       int nPrefix;
124578       if( fts3GobbleInt(&p, &nPrefix) ) return SQLITE_ERROR;
124579       aIndex[i].nPrefix = nPrefix;
124580       p++;
124581     }
124582   }
124583 
124584   return SQLITE_OK;
124585 }
124586 
124587 /*
124588 ** This function is called when initializing an FTS4 table that uses the
124589 ** content=xxx option. It determines the number of and names of the columns
124590 ** of the new FTS4 table.
124591 **
124592 ** The third argument passed to this function is the value passed to the
124593 ** config=xxx option (i.e. "xxx"). This function queries the database for
124594 ** a table of that name. If found, the output variables are populated
124595 ** as follows:
124596 **
124597 **   *pnCol:   Set to the number of columns table xxx has,
124598 **
124599 **   *pnStr:   Set to the total amount of space required to store a copy
124600 **             of each columns name, including the nul-terminator.
124601 **
124602 **   *pazCol:  Set to point to an array of *pnCol strings. Each string is
124603 **             the name of the corresponding column in table xxx. The array
124604 **             and its contents are allocated using a single allocation. It
124605 **             is the responsibility of the caller to free this allocation
124606 **             by eventually passing the *pazCol value to sqlite3_free().
124607 **
124608 ** If the table cannot be found, an error code is returned and the output
124609 ** variables are undefined. Or, if an OOM is encountered, SQLITE_NOMEM is
124610 ** returned (and the output variables are undefined).
124611 */
124612 static int fts3ContentColumns(
124613   sqlite3 *db,                    /* Database handle */
124614   const char *zDb,                /* Name of db (i.e. "main", "temp" etc.) */
124615   const char *zTbl,               /* Name of content table */
124616   const char ***pazCol,           /* OUT: Malloc'd array of column names */
124617   int *pnCol,                     /* OUT: Size of array *pazCol */
124618   int *pnStr                      /* OUT: Bytes of string content */
124619 ){
124620   int rc = SQLITE_OK;             /* Return code */
124621   char *zSql;                     /* "SELECT *" statement on zTbl */  
124622   sqlite3_stmt *pStmt = 0;        /* Compiled version of zSql */
124623 
124624   zSql = sqlite3_mprintf("SELECT * FROM %Q.%Q", zDb, zTbl);
124625   if( !zSql ){
124626     rc = SQLITE_NOMEM;
124627   }else{
124628     rc = sqlite3_prepare(db, zSql, -1, &pStmt, 0);
124629   }
124630   sqlite3_free(zSql);
124631 
124632   if( rc==SQLITE_OK ){
124633     const char **azCol;           /* Output array */
124634     int nStr = 0;                 /* Size of all column names (incl. 0x00) */
124635     int nCol;                     /* Number of table columns */
124636     int i;                        /* Used to iterate through columns */
124637 
124638     /* Loop through the returned columns. Set nStr to the number of bytes of
124639     ** space required to store a copy of each column name, including the
124640     ** nul-terminator byte.  */
124641     nCol = sqlite3_column_count(pStmt);
124642     for(i=0; i<nCol; i++){
124643       const char *zCol = sqlite3_column_name(pStmt, i);
124644       nStr += (int)strlen(zCol) + 1;
124645     }
124646 
124647     /* Allocate and populate the array to return. */
124648     azCol = (const char **)sqlite3_malloc(sizeof(char *) * nCol + nStr);
124649     if( azCol==0 ){
124650       rc = SQLITE_NOMEM;
124651     }else{
124652       char *p = (char *)&azCol[nCol];
124653       for(i=0; i<nCol; i++){
124654         const char *zCol = sqlite3_column_name(pStmt, i);
124655         int n = (int)strlen(zCol)+1;
124656         memcpy(p, zCol, n);
124657         azCol[i] = p;
124658         p += n;
124659       }
124660     }
124661     sqlite3_finalize(pStmt);
124662 
124663     /* Set the output variables. */
124664     *pnCol = nCol;
124665     *pnStr = nStr;
124666     *pazCol = azCol;
124667   }
124668 
124669   return rc;
124670 }
124671 
124672 /*
124673 ** This function is the implementation of both the xConnect and xCreate
124674 ** methods of the FTS3 virtual table.
124675 **
124676 ** The argv[] array contains the following:
124677 **
124678 **   argv[0]   -> module name  ("fts3" or "fts4")
124679 **   argv[1]   -> database name
124680 **   argv[2]   -> table name
124681 **   argv[...] -> "column name" and other module argument fields.
124682 */
124683 static int fts3InitVtab(
124684   int isCreate,                   /* True for xCreate, false for xConnect */
124685   sqlite3 *db,                    /* The SQLite database connection */
124686   void *pAux,                     /* Hash table containing tokenizers */
124687   int argc,                       /* Number of elements in argv array */
124688   const char * const *argv,       /* xCreate/xConnect argument array */
124689   sqlite3_vtab **ppVTab,          /* Write the resulting vtab structure here */
124690   char **pzErr                    /* Write any error message here */
124691 ){
124692   Fts3Hash *pHash = (Fts3Hash *)pAux;
124693   Fts3Table *p = 0;               /* Pointer to allocated vtab */
124694   int rc = SQLITE_OK;             /* Return code */
124695   int i;                          /* Iterator variable */
124696   int nByte;                      /* Size of allocation used for *p */
124697   int iCol;                       /* Column index */
124698   int nString = 0;                /* Bytes required to hold all column names */
124699   int nCol = 0;                   /* Number of columns in the FTS table */
124700   char *zCsr;                     /* Space for holding column names */
124701   int nDb;                        /* Bytes required to hold database name */
124702   int nName;                      /* Bytes required to hold table name */
124703   int isFts4 = (argv[0][3]=='4'); /* True for FTS4, false for FTS3 */
124704   const char **aCol;              /* Array of column names */
124705   sqlite3_tokenizer *pTokenizer = 0;        /* Tokenizer for this table */
124706 
124707   int nIndex;                     /* Size of aIndex[] array */
124708   struct Fts3Index *aIndex = 0;   /* Array of indexes for this table */
124709 
124710   /* The results of parsing supported FTS4 key=value options: */
124711   int bNoDocsize = 0;             /* True to omit %_docsize table */
124712   int bDescIdx = 0;               /* True to store descending indexes */
124713   char *zPrefix = 0;              /* Prefix parameter value (or NULL) */
124714   char *zCompress = 0;            /* compress=? parameter (or NULL) */
124715   char *zUncompress = 0;          /* uncompress=? parameter (or NULL) */
124716   char *zContent = 0;             /* content=? parameter (or NULL) */
124717   char *zLanguageid = 0;          /* languageid=? parameter (or NULL) */
124718   char **azNotindexed = 0;        /* The set of notindexed= columns */
124719   int nNotindexed = 0;            /* Size of azNotindexed[] array */
124720 
124721   assert( strlen(argv[0])==4 );
124722   assert( (sqlite3_strnicmp(argv[0], "fts4", 4)==0 && isFts4)
124723        || (sqlite3_strnicmp(argv[0], "fts3", 4)==0 && !isFts4)
124724   );
124725 
124726   nDb = (int)strlen(argv[1]) + 1;
124727   nName = (int)strlen(argv[2]) + 1;
124728 
124729   nByte = sizeof(const char *) * (argc-2);
124730   aCol = (const char **)sqlite3_malloc(nByte);
124731   if( aCol ){
124732     memset((void*)aCol, 0, nByte);
124733     azNotindexed = (char **)sqlite3_malloc(nByte);
124734   }
124735   if( azNotindexed ){
124736     memset(azNotindexed, 0, nByte);
124737   }
124738   if( !aCol || !azNotindexed ){
124739     rc = SQLITE_NOMEM;
124740     goto fts3_init_out;
124741   }
124742 
124743   /* Loop through all of the arguments passed by the user to the FTS3/4
124744   ** module (i.e. all the column names and special arguments). This loop
124745   ** does the following:
124746   **
124747   **   + Figures out the number of columns the FTSX table will have, and
124748   **     the number of bytes of space that must be allocated to store copies
124749   **     of the column names.
124750   **
124751   **   + If there is a tokenizer specification included in the arguments,
124752   **     initializes the tokenizer pTokenizer.
124753   */
124754   for(i=3; rc==SQLITE_OK && i<argc; i++){
124755     char const *z = argv[i];
124756     int nKey;
124757     char *zVal;
124758 
124759     /* Check if this is a tokenizer specification */
124760     if( !pTokenizer 
124761      && strlen(z)>8
124762      && 0==sqlite3_strnicmp(z, "tokenize", 8) 
124763      && 0==sqlite3Fts3IsIdChar(z[8])
124764     ){
124765       rc = sqlite3Fts3InitTokenizer(pHash, &z[9], &pTokenizer, pzErr);
124766     }
124767 
124768     /* Check if it is an FTS4 special argument. */
124769     else if( isFts4 && fts3IsSpecialColumn(z, &nKey, &zVal) ){
124770       struct Fts4Option {
124771         const char *zOpt;
124772         int nOpt;
124773       } aFts4Opt[] = {
124774         { "matchinfo",   9 },     /* 0 -> MATCHINFO */
124775         { "prefix",      6 },     /* 1 -> PREFIX */
124776         { "compress",    8 },     /* 2 -> COMPRESS */
124777         { "uncompress", 10 },     /* 3 -> UNCOMPRESS */
124778         { "order",       5 },     /* 4 -> ORDER */
124779         { "content",     7 },     /* 5 -> CONTENT */
124780         { "languageid", 10 },     /* 6 -> LANGUAGEID */
124781         { "notindexed", 10 }      /* 7 -> NOTINDEXED */
124782       };
124783 
124784       int iOpt;
124785       if( !zVal ){
124786         rc = SQLITE_NOMEM;
124787       }else{
124788         for(iOpt=0; iOpt<SizeofArray(aFts4Opt); iOpt++){
124789           struct Fts4Option *pOp = &aFts4Opt[iOpt];
124790           if( nKey==pOp->nOpt && !sqlite3_strnicmp(z, pOp->zOpt, pOp->nOpt) ){
124791             break;
124792           }
124793         }
124794         if( iOpt==SizeofArray(aFts4Opt) ){
124795           *pzErr = sqlite3_mprintf("unrecognized parameter: %s", z);
124796           rc = SQLITE_ERROR;
124797         }else{
124798           switch( iOpt ){
124799             case 0:               /* MATCHINFO */
124800               if( strlen(zVal)!=4 || sqlite3_strnicmp(zVal, "fts3", 4) ){
124801                 *pzErr = sqlite3_mprintf("unrecognized matchinfo: %s", zVal);
124802                 rc = SQLITE_ERROR;
124803               }
124804               bNoDocsize = 1;
124805               break;
124806 
124807             case 1:               /* PREFIX */
124808               sqlite3_free(zPrefix);
124809               zPrefix = zVal;
124810               zVal = 0;
124811               break;
124812 
124813             case 2:               /* COMPRESS */
124814               sqlite3_free(zCompress);
124815               zCompress = zVal;
124816               zVal = 0;
124817               break;
124818 
124819             case 3:               /* UNCOMPRESS */
124820               sqlite3_free(zUncompress);
124821               zUncompress = zVal;
124822               zVal = 0;
124823               break;
124824 
124825             case 4:               /* ORDER */
124826               if( (strlen(zVal)!=3 || sqlite3_strnicmp(zVal, "asc", 3)) 
124827                && (strlen(zVal)!=4 || sqlite3_strnicmp(zVal, "desc", 4)) 
124828               ){
124829                 *pzErr = sqlite3_mprintf("unrecognized order: %s", zVal);
124830                 rc = SQLITE_ERROR;
124831               }
124832               bDescIdx = (zVal[0]=='d' || zVal[0]=='D');
124833               break;
124834 
124835             case 5:              /* CONTENT */
124836               sqlite3_free(zContent);
124837               zContent = zVal;
124838               zVal = 0;
124839               break;
124840 
124841             case 6:              /* LANGUAGEID */
124842               assert( iOpt==6 );
124843               sqlite3_free(zLanguageid);
124844               zLanguageid = zVal;
124845               zVal = 0;
124846               break;
124847 
124848             case 7:              /* NOTINDEXED */
124849               azNotindexed[nNotindexed++] = zVal;
124850               zVal = 0;
124851               break;
124852           }
124853         }
124854         sqlite3_free(zVal);
124855       }
124856     }
124857 
124858     /* Otherwise, the argument is a column name. */
124859     else {
124860       nString += (int)(strlen(z) + 1);
124861       aCol[nCol++] = z;
124862     }
124863   }
124864 
124865   /* If a content=xxx option was specified, the following:
124866   **
124867   **   1. Ignore any compress= and uncompress= options.
124868   **
124869   **   2. If no column names were specified as part of the CREATE VIRTUAL
124870   **      TABLE statement, use all columns from the content table.
124871   */
124872   if( rc==SQLITE_OK && zContent ){
124873     sqlite3_free(zCompress); 
124874     sqlite3_free(zUncompress); 
124875     zCompress = 0;
124876     zUncompress = 0;
124877     if( nCol==0 ){
124878       sqlite3_free((void*)aCol); 
124879       aCol = 0;
124880       rc = fts3ContentColumns(db, argv[1], zContent, &aCol, &nCol, &nString);
124881 
124882       /* If a languageid= option was specified, remove the language id
124883       ** column from the aCol[] array. */ 
124884       if( rc==SQLITE_OK && zLanguageid ){
124885         int j;
124886         for(j=0; j<nCol; j++){
124887           if( sqlite3_stricmp(zLanguageid, aCol[j])==0 ){
124888             int k;
124889             for(k=j; k<nCol; k++) aCol[k] = aCol[k+1];
124890             nCol--;
124891             break;
124892           }
124893         }
124894       }
124895     }
124896   }
124897   if( rc!=SQLITE_OK ) goto fts3_init_out;
124898 
124899   if( nCol==0 ){
124900     assert( nString==0 );
124901     aCol[0] = "content";
124902     nString = 8;
124903     nCol = 1;
124904   }
124905 
124906   if( pTokenizer==0 ){
124907     rc = sqlite3Fts3InitTokenizer(pHash, "simple", &pTokenizer, pzErr);
124908     if( rc!=SQLITE_OK ) goto fts3_init_out;
124909   }
124910   assert( pTokenizer );
124911 
124912   rc = fts3PrefixParameter(zPrefix, &nIndex, &aIndex);
124913   if( rc==SQLITE_ERROR ){
124914     assert( zPrefix );
124915     *pzErr = sqlite3_mprintf("error parsing prefix parameter: %s", zPrefix);
124916   }
124917   if( rc!=SQLITE_OK ) goto fts3_init_out;
124918 
124919   /* Allocate and populate the Fts3Table structure. */
124920   nByte = sizeof(Fts3Table) +                  /* Fts3Table */
124921           nCol * sizeof(char *) +              /* azColumn */
124922           nIndex * sizeof(struct Fts3Index) +  /* aIndex */
124923           nCol * sizeof(u8) +                  /* abNotindexed */
124924           nName +                              /* zName */
124925           nDb +                                /* zDb */
124926           nString;                             /* Space for azColumn strings */
124927   p = (Fts3Table*)sqlite3_malloc(nByte);
124928   if( p==0 ){
124929     rc = SQLITE_NOMEM;
124930     goto fts3_init_out;
124931   }
124932   memset(p, 0, nByte);
124933   p->db = db;
124934   p->nColumn = nCol;
124935   p->nPendingData = 0;
124936   p->azColumn = (char **)&p[1];
124937   p->pTokenizer = pTokenizer;
124938   p->nMaxPendingData = FTS3_MAX_PENDING_DATA;
124939   p->bHasDocsize = (isFts4 && bNoDocsize==0);
124940   p->bHasStat = isFts4;
124941   p->bFts4 = isFts4;
124942   p->bDescIdx = bDescIdx;
124943   p->bAutoincrmerge = 0xff;   /* 0xff means setting unknown */
124944   p->zContentTbl = zContent;
124945   p->zLanguageid = zLanguageid;
124946   zContent = 0;
124947   zLanguageid = 0;
124948   TESTONLY( p->inTransaction = -1 );
124949   TESTONLY( p->mxSavepoint = -1 );
124950 
124951   p->aIndex = (struct Fts3Index *)&p->azColumn[nCol];
124952   memcpy(p->aIndex, aIndex, sizeof(struct Fts3Index) * nIndex);
124953   p->nIndex = nIndex;
124954   for(i=0; i<nIndex; i++){
124955     fts3HashInit(&p->aIndex[i].hPending, FTS3_HASH_STRING, 1);
124956   }
124957   p->abNotindexed = (u8 *)&p->aIndex[nIndex];
124958 
124959   /* Fill in the zName and zDb fields of the vtab structure. */
124960   zCsr = (char *)&p->abNotindexed[nCol];
124961   p->zName = zCsr;
124962   memcpy(zCsr, argv[2], nName);
124963   zCsr += nName;
124964   p->zDb = zCsr;
124965   memcpy(zCsr, argv[1], nDb);
124966   zCsr += nDb;
124967 
124968   /* Fill in the azColumn array */
124969   for(iCol=0; iCol<nCol; iCol++){
124970     char *z; 
124971     int n = 0;
124972     z = (char *)sqlite3Fts3NextToken(aCol[iCol], &n);
124973     memcpy(zCsr, z, n);
124974     zCsr[n] = '\0';
124975     sqlite3Fts3Dequote(zCsr);
124976     p->azColumn[iCol] = zCsr;
124977     zCsr += n+1;
124978     assert( zCsr <= &((char *)p)[nByte] );
124979   }
124980 
124981   /* Fill in the abNotindexed array */
124982   for(iCol=0; iCol<nCol; iCol++){
124983     int n = (int)strlen(p->azColumn[iCol]);
124984     for(i=0; i<nNotindexed; i++){
124985       char *zNot = azNotindexed[i];
124986       if( zNot && 0==sqlite3_strnicmp(p->azColumn[iCol], zNot, n) ){
124987         p->abNotindexed[iCol] = 1;
124988         sqlite3_free(zNot);
124989         azNotindexed[i] = 0;
124990       }
124991     }
124992   }
124993   for(i=0; i<nNotindexed; i++){
124994     if( azNotindexed[i] ){
124995       *pzErr = sqlite3_mprintf("no such column: %s", azNotindexed[i]);
124996       rc = SQLITE_ERROR;
124997     }
124998   }
124999 
125000   if( rc==SQLITE_OK && (zCompress==0)!=(zUncompress==0) ){
125001     char const *zMiss = (zCompress==0 ? "compress" : "uncompress");
125002     rc = SQLITE_ERROR;
125003     *pzErr = sqlite3_mprintf("missing %s parameter in fts4 constructor", zMiss);
125004   }
125005   p->zReadExprlist = fts3ReadExprList(p, zUncompress, &rc);
125006   p->zWriteExprlist = fts3WriteExprList(p, zCompress, &rc);
125007   if( rc!=SQLITE_OK ) goto fts3_init_out;
125008 
125009   /* If this is an xCreate call, create the underlying tables in the 
125010   ** database. TODO: For xConnect(), it could verify that said tables exist.
125011   */
125012   if( isCreate ){
125013     rc = fts3CreateTables(p);
125014   }
125015 
125016   /* Check to see if a legacy fts3 table has been "upgraded" by the
125017   ** addition of a %_stat table so that it can use incremental merge.
125018   */
125019   if( !isFts4 && !isCreate ){
125020     int rc2 = SQLITE_OK;
125021     fts3DbExec(&rc2, db, "SELECT 1 FROM %Q.'%q_stat' WHERE id=2",
125022                p->zDb, p->zName);
125023     if( rc2==SQLITE_OK ) p->bHasStat = 1;
125024   }
125025 
125026   /* Figure out the page-size for the database. This is required in order to
125027   ** estimate the cost of loading large doclists from the database.  */
125028   fts3DatabasePageSize(&rc, p);
125029   p->nNodeSize = p->nPgsz-35;
125030 
125031   /* Declare the table schema to SQLite. */
125032   fts3DeclareVtab(&rc, p);
125033 
125034 fts3_init_out:
125035   sqlite3_free(zPrefix);
125036   sqlite3_free(aIndex);
125037   sqlite3_free(zCompress);
125038   sqlite3_free(zUncompress);
125039   sqlite3_free(zContent);
125040   sqlite3_free(zLanguageid);
125041   for(i=0; i<nNotindexed; i++) sqlite3_free(azNotindexed[i]);
125042   sqlite3_free((void *)aCol);
125043   sqlite3_free((void *)azNotindexed);
125044   if( rc!=SQLITE_OK ){
125045     if( p ){
125046       fts3DisconnectMethod((sqlite3_vtab *)p);
125047     }else if( pTokenizer ){
125048       pTokenizer->pModule->xDestroy(pTokenizer);
125049     }
125050   }else{
125051     assert( p->pSegments==0 );
125052     *ppVTab = &p->base;
125053   }
125054   return rc;
125055 }
125056 
125057 /*
125058 ** The xConnect() and xCreate() methods for the virtual table. All the
125059 ** work is done in function fts3InitVtab().
125060 */
125061 static int fts3ConnectMethod(
125062   sqlite3 *db,                    /* Database connection */
125063   void *pAux,                     /* Pointer to tokenizer hash table */
125064   int argc,                       /* Number of elements in argv array */
125065   const char * const *argv,       /* xCreate/xConnect argument array */
125066   sqlite3_vtab **ppVtab,          /* OUT: New sqlite3_vtab object */
125067   char **pzErr                    /* OUT: sqlite3_malloc'd error message */
125068 ){
125069   return fts3InitVtab(0, db, pAux, argc, argv, ppVtab, pzErr);
125070 }
125071 static int fts3CreateMethod(
125072   sqlite3 *db,                    /* Database connection */
125073   void *pAux,                     /* Pointer to tokenizer hash table */
125074   int argc,                       /* Number of elements in argv array */
125075   const char * const *argv,       /* xCreate/xConnect argument array */
125076   sqlite3_vtab **ppVtab,          /* OUT: New sqlite3_vtab object */
125077   char **pzErr                    /* OUT: sqlite3_malloc'd error message */
125078 ){
125079   return fts3InitVtab(1, db, pAux, argc, argv, ppVtab, pzErr);
125080 }
125081 
125082 /* 
125083 ** Implementation of the xBestIndex method for FTS3 tables. There
125084 ** are three possible strategies, in order of preference:
125085 **
125086 **   1. Direct lookup by rowid or docid. 
125087 **   2. Full-text search using a MATCH operator on a non-docid column.
125088 **   3. Linear scan of %_content table.
125089 */
125090 static int fts3BestIndexMethod(sqlite3_vtab *pVTab, sqlite3_index_info *pInfo){
125091   Fts3Table *p = (Fts3Table *)pVTab;
125092   int i;                          /* Iterator variable */
125093   int iCons = -1;                 /* Index of constraint to use */
125094 
125095   int iLangidCons = -1;           /* Index of langid=x constraint, if present */
125096   int iDocidGe = -1;              /* Index of docid>=x constraint, if present */
125097   int iDocidLe = -1;              /* Index of docid<=x constraint, if present */
125098   int iIdx;
125099 
125100   /* By default use a full table scan. This is an expensive option,
125101   ** so search through the constraints to see if a more efficient 
125102   ** strategy is possible.
125103   */
125104   pInfo->idxNum = FTS3_FULLSCAN_SEARCH;
125105   pInfo->estimatedCost = 5000000;
125106   for(i=0; i<pInfo->nConstraint; i++){
125107     int bDocid;                 /* True if this constraint is on docid */
125108     struct sqlite3_index_constraint *pCons = &pInfo->aConstraint[i];
125109     if( pCons->usable==0 ) continue;
125110 
125111     bDocid = (pCons->iColumn<0 || pCons->iColumn==p->nColumn+1);
125112 
125113     /* A direct lookup on the rowid or docid column. Assign a cost of 1.0. */
125114     if( iCons<0 && pCons->op==SQLITE_INDEX_CONSTRAINT_EQ && bDocid ){
125115       pInfo->idxNum = FTS3_DOCID_SEARCH;
125116       pInfo->estimatedCost = 1.0;
125117       iCons = i;
125118     }
125119 
125120     /* A MATCH constraint. Use a full-text search.
125121     **
125122     ** If there is more than one MATCH constraint available, use the first
125123     ** one encountered. If there is both a MATCH constraint and a direct
125124     ** rowid/docid lookup, prefer the MATCH strategy. This is done even 
125125     ** though the rowid/docid lookup is faster than a MATCH query, selecting
125126     ** it would lead to an "unable to use function MATCH in the requested 
125127     ** context" error.
125128     */
125129     if( pCons->op==SQLITE_INDEX_CONSTRAINT_MATCH 
125130      && pCons->iColumn>=0 && pCons->iColumn<=p->nColumn
125131     ){
125132       pInfo->idxNum = FTS3_FULLTEXT_SEARCH + pCons->iColumn;
125133       pInfo->estimatedCost = 2.0;
125134       iCons = i;
125135     }
125136 
125137     /* Equality constraint on the langid column */
125138     if( pCons->op==SQLITE_INDEX_CONSTRAINT_EQ 
125139      && pCons->iColumn==p->nColumn + 2
125140     ){
125141       iLangidCons = i;
125142     }
125143 
125144     if( bDocid ){
125145       switch( pCons->op ){
125146         case SQLITE_INDEX_CONSTRAINT_GE:
125147         case SQLITE_INDEX_CONSTRAINT_GT:
125148           iDocidGe = i;
125149           break;
125150 
125151         case SQLITE_INDEX_CONSTRAINT_LE:
125152         case SQLITE_INDEX_CONSTRAINT_LT:
125153           iDocidLe = i;
125154           break;
125155       }
125156     }
125157   }
125158 
125159   iIdx = 1;
125160   if( iCons>=0 ){
125161     pInfo->aConstraintUsage[iCons].argvIndex = iIdx++;
125162     pInfo->aConstraintUsage[iCons].omit = 1;
125163   } 
125164   if( iLangidCons>=0 ){
125165     pInfo->idxNum |= FTS3_HAVE_LANGID;
125166     pInfo->aConstraintUsage[iLangidCons].argvIndex = iIdx++;
125167   } 
125168   if( iDocidGe>=0 ){
125169     pInfo->idxNum |= FTS3_HAVE_DOCID_GE;
125170     pInfo->aConstraintUsage[iDocidGe].argvIndex = iIdx++;
125171   } 
125172   if( iDocidLe>=0 ){
125173     pInfo->idxNum |= FTS3_HAVE_DOCID_LE;
125174     pInfo->aConstraintUsage[iDocidLe].argvIndex = iIdx++;
125175   } 
125176 
125177   /* Regardless of the strategy selected, FTS can deliver rows in rowid (or
125178   ** docid) order. Both ascending and descending are possible. 
125179   */
125180   if( pInfo->nOrderBy==1 ){
125181     struct sqlite3_index_orderby *pOrder = &pInfo->aOrderBy[0];
125182     if( pOrder->iColumn<0 || pOrder->iColumn==p->nColumn+1 ){
125183       if( pOrder->desc ){
125184         pInfo->idxStr = "DESC";
125185       }else{
125186         pInfo->idxStr = "ASC";
125187       }
125188       pInfo->orderByConsumed = 1;
125189     }
125190   }
125191 
125192   assert( p->pSegments==0 );
125193   return SQLITE_OK;
125194 }
125195 
125196 /*
125197 ** Implementation of xOpen method.
125198 */
125199 static int fts3OpenMethod(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCsr){
125200   sqlite3_vtab_cursor *pCsr;               /* Allocated cursor */
125201 
125202   UNUSED_PARAMETER(pVTab);
125203 
125204   /* Allocate a buffer large enough for an Fts3Cursor structure. If the
125205   ** allocation succeeds, zero it and return SQLITE_OK. Otherwise, 
125206   ** if the allocation fails, return SQLITE_NOMEM.
125207   */
125208   *ppCsr = pCsr = (sqlite3_vtab_cursor *)sqlite3_malloc(sizeof(Fts3Cursor));
125209   if( !pCsr ){
125210     return SQLITE_NOMEM;
125211   }
125212   memset(pCsr, 0, sizeof(Fts3Cursor));
125213   return SQLITE_OK;
125214 }
125215 
125216 /*
125217 ** Close the cursor.  For additional information see the documentation
125218 ** on the xClose method of the virtual table interface.
125219 */
125220 static int fts3CloseMethod(sqlite3_vtab_cursor *pCursor){
125221   Fts3Cursor *pCsr = (Fts3Cursor *)pCursor;
125222   assert( ((Fts3Table *)pCsr->base.pVtab)->pSegments==0 );
125223   sqlite3_finalize(pCsr->pStmt);
125224   sqlite3Fts3ExprFree(pCsr->pExpr);
125225   sqlite3Fts3FreeDeferredTokens(pCsr);
125226   sqlite3_free(pCsr->aDoclist);
125227   sqlite3_free(pCsr->aMatchinfo);
125228   assert( ((Fts3Table *)pCsr->base.pVtab)->pSegments==0 );
125229   sqlite3_free(pCsr);
125230   return SQLITE_OK;
125231 }
125232 
125233 /*
125234 ** If pCsr->pStmt has not been prepared (i.e. if pCsr->pStmt==0), then
125235 ** compose and prepare an SQL statement of the form:
125236 **
125237 **    "SELECT <columns> FROM %_content WHERE rowid = ?"
125238 **
125239 ** (or the equivalent for a content=xxx table) and set pCsr->pStmt to
125240 ** it. If an error occurs, return an SQLite error code.
125241 **
125242 ** Otherwise, set *ppStmt to point to pCsr->pStmt and return SQLITE_OK.
125243 */
125244 static int fts3CursorSeekStmt(Fts3Cursor *pCsr, sqlite3_stmt **ppStmt){
125245   int rc = SQLITE_OK;
125246   if( pCsr->pStmt==0 ){
125247     Fts3Table *p = (Fts3Table *)pCsr->base.pVtab;
125248     char *zSql;
125249     zSql = sqlite3_mprintf("SELECT %s WHERE rowid = ?", p->zReadExprlist);
125250     if( !zSql ) return SQLITE_NOMEM;
125251     rc = sqlite3_prepare_v2(p->db, zSql, -1, &pCsr->pStmt, 0);
125252     sqlite3_free(zSql);
125253   }
125254   *ppStmt = pCsr->pStmt;
125255   return rc;
125256 }
125257 
125258 /*
125259 ** Position the pCsr->pStmt statement so that it is on the row
125260 ** of the %_content table that contains the last match.  Return
125261 ** SQLITE_OK on success.  
125262 */
125263 static int fts3CursorSeek(sqlite3_context *pContext, Fts3Cursor *pCsr){
125264   int rc = SQLITE_OK;
125265   if( pCsr->isRequireSeek ){
125266     sqlite3_stmt *pStmt = 0;
125267 
125268     rc = fts3CursorSeekStmt(pCsr, &pStmt);
125269     if( rc==SQLITE_OK ){
125270       sqlite3_bind_int64(pCsr->pStmt, 1, pCsr->iPrevId);
125271       pCsr->isRequireSeek = 0;
125272       if( SQLITE_ROW==sqlite3_step(pCsr->pStmt) ){
125273         return SQLITE_OK;
125274       }else{
125275         rc = sqlite3_reset(pCsr->pStmt);
125276         if( rc==SQLITE_OK && ((Fts3Table *)pCsr->base.pVtab)->zContentTbl==0 ){
125277           /* If no row was found and no error has occurred, then the %_content
125278           ** table is missing a row that is present in the full-text index.
125279           ** The data structures are corrupt.  */
125280           rc = FTS_CORRUPT_VTAB;
125281           pCsr->isEof = 1;
125282         }
125283       }
125284     }
125285   }
125286 
125287   if( rc!=SQLITE_OK && pContext ){
125288     sqlite3_result_error_code(pContext, rc);
125289   }
125290   return rc;
125291 }
125292 
125293 /*
125294 ** This function is used to process a single interior node when searching
125295 ** a b-tree for a term or term prefix. The node data is passed to this 
125296 ** function via the zNode/nNode parameters. The term to search for is
125297 ** passed in zTerm/nTerm.
125298 **
125299 ** If piFirst is not NULL, then this function sets *piFirst to the blockid
125300 ** of the child node that heads the sub-tree that may contain the term.
125301 **
125302 ** If piLast is not NULL, then *piLast is set to the right-most child node
125303 ** that heads a sub-tree that may contain a term for which zTerm/nTerm is
125304 ** a prefix.
125305 **
125306 ** If an OOM error occurs, SQLITE_NOMEM is returned. Otherwise, SQLITE_OK.
125307 */
125308 static int fts3ScanInteriorNode(
125309   const char *zTerm,              /* Term to select leaves for */
125310   int nTerm,                      /* Size of term zTerm in bytes */
125311   const char *zNode,              /* Buffer containing segment interior node */
125312   int nNode,                      /* Size of buffer at zNode */
125313   sqlite3_int64 *piFirst,         /* OUT: Selected child node */
125314   sqlite3_int64 *piLast           /* OUT: Selected child node */
125315 ){
125316   int rc = SQLITE_OK;             /* Return code */
125317   const char *zCsr = zNode;       /* Cursor to iterate through node */
125318   const char *zEnd = &zCsr[nNode];/* End of interior node buffer */
125319   char *zBuffer = 0;              /* Buffer to load terms into */
125320   int nAlloc = 0;                 /* Size of allocated buffer */
125321   int isFirstTerm = 1;            /* True when processing first term on page */
125322   sqlite3_int64 iChild;           /* Block id of child node to descend to */
125323 
125324   /* Skip over the 'height' varint that occurs at the start of every 
125325   ** interior node. Then load the blockid of the left-child of the b-tree
125326   ** node into variable iChild.  
125327   **
125328   ** Even if the data structure on disk is corrupted, this (reading two
125329   ** varints from the buffer) does not risk an overread. If zNode is a
125330   ** root node, then the buffer comes from a SELECT statement. SQLite does
125331   ** not make this guarantee explicitly, but in practice there are always
125332   ** either more than 20 bytes of allocated space following the nNode bytes of
125333   ** contents, or two zero bytes. Or, if the node is read from the %_segments
125334   ** table, then there are always 20 bytes of zeroed padding following the
125335   ** nNode bytes of content (see sqlite3Fts3ReadBlock() for details).
125336   */
125337   zCsr += sqlite3Fts3GetVarint(zCsr, &iChild);
125338   zCsr += sqlite3Fts3GetVarint(zCsr, &iChild);
125339   if( zCsr>zEnd ){
125340     return FTS_CORRUPT_VTAB;
125341   }
125342   
125343   while( zCsr<zEnd && (piFirst || piLast) ){
125344     int cmp;                      /* memcmp() result */
125345     int nSuffix;                  /* Size of term suffix */
125346     int nPrefix = 0;              /* Size of term prefix */
125347     int nBuffer;                  /* Total term size */
125348   
125349     /* Load the next term on the node into zBuffer. Use realloc() to expand
125350     ** the size of zBuffer if required.  */
125351     if( !isFirstTerm ){
125352       zCsr += fts3GetVarint32(zCsr, &nPrefix);
125353     }
125354     isFirstTerm = 0;
125355     zCsr += fts3GetVarint32(zCsr, &nSuffix);
125356     
125357     if( nPrefix<0 || nSuffix<0 || &zCsr[nSuffix]>zEnd ){
125358       rc = FTS_CORRUPT_VTAB;
125359       goto finish_scan;
125360     }
125361     if( nPrefix+nSuffix>nAlloc ){
125362       char *zNew;
125363       nAlloc = (nPrefix+nSuffix) * 2;
125364       zNew = (char *)sqlite3_realloc(zBuffer, nAlloc);
125365       if( !zNew ){
125366         rc = SQLITE_NOMEM;
125367         goto finish_scan;
125368       }
125369       zBuffer = zNew;
125370     }
125371     assert( zBuffer );
125372     memcpy(&zBuffer[nPrefix], zCsr, nSuffix);
125373     nBuffer = nPrefix + nSuffix;
125374     zCsr += nSuffix;
125375 
125376     /* Compare the term we are searching for with the term just loaded from
125377     ** the interior node. If the specified term is greater than or equal
125378     ** to the term from the interior node, then all terms on the sub-tree 
125379     ** headed by node iChild are smaller than zTerm. No need to search 
125380     ** iChild.
125381     **
125382     ** If the interior node term is larger than the specified term, then
125383     ** the tree headed by iChild may contain the specified term.
125384     */
125385     cmp = memcmp(zTerm, zBuffer, (nBuffer>nTerm ? nTerm : nBuffer));
125386     if( piFirst && (cmp<0 || (cmp==0 && nBuffer>nTerm)) ){
125387       *piFirst = iChild;
125388       piFirst = 0;
125389     }
125390 
125391     if( piLast && cmp<0 ){
125392       *piLast = iChild;
125393       piLast = 0;
125394     }
125395 
125396     iChild++;
125397   };
125398 
125399   if( piFirst ) *piFirst = iChild;
125400   if( piLast ) *piLast = iChild;
125401 
125402  finish_scan:
125403   sqlite3_free(zBuffer);
125404   return rc;
125405 }
125406 
125407 
125408 /*
125409 ** The buffer pointed to by argument zNode (size nNode bytes) contains an
125410 ** interior node of a b-tree segment. The zTerm buffer (size nTerm bytes)
125411 ** contains a term. This function searches the sub-tree headed by the zNode
125412 ** node for the range of leaf nodes that may contain the specified term
125413 ** or terms for which the specified term is a prefix.
125414 **
125415 ** If piLeaf is not NULL, then *piLeaf is set to the blockid of the 
125416 ** left-most leaf node in the tree that may contain the specified term.
125417 ** If piLeaf2 is not NULL, then *piLeaf2 is set to the blockid of the
125418 ** right-most leaf node that may contain a term for which the specified
125419 ** term is a prefix.
125420 **
125421 ** It is possible that the range of returned leaf nodes does not contain 
125422 ** the specified term or any terms for which it is a prefix. However, if the 
125423 ** segment does contain any such terms, they are stored within the identified
125424 ** range. Because this function only inspects interior segment nodes (and
125425 ** never loads leaf nodes into memory), it is not possible to be sure.
125426 **
125427 ** If an error occurs, an error code other than SQLITE_OK is returned.
125428 */ 
125429 static int fts3SelectLeaf(
125430   Fts3Table *p,                   /* Virtual table handle */
125431   const char *zTerm,              /* Term to select leaves for */
125432   int nTerm,                      /* Size of term zTerm in bytes */
125433   const char *zNode,              /* Buffer containing segment interior node */
125434   int nNode,                      /* Size of buffer at zNode */
125435   sqlite3_int64 *piLeaf,          /* Selected leaf node */
125436   sqlite3_int64 *piLeaf2          /* Selected leaf node */
125437 ){
125438   int rc;                         /* Return code */
125439   int iHeight;                    /* Height of this node in tree */
125440 
125441   assert( piLeaf || piLeaf2 );
125442 
125443   fts3GetVarint32(zNode, &iHeight);
125444   rc = fts3ScanInteriorNode(zTerm, nTerm, zNode, nNode, piLeaf, piLeaf2);
125445   assert( !piLeaf2 || !piLeaf || rc!=SQLITE_OK || (*piLeaf<=*piLeaf2) );
125446 
125447   if( rc==SQLITE_OK && iHeight>1 ){
125448     char *zBlob = 0;              /* Blob read from %_segments table */
125449     int nBlob;                    /* Size of zBlob in bytes */
125450 
125451     if( piLeaf && piLeaf2 && (*piLeaf!=*piLeaf2) ){
125452       rc = sqlite3Fts3ReadBlock(p, *piLeaf, &zBlob, &nBlob, 0);
125453       if( rc==SQLITE_OK ){
125454         rc = fts3SelectLeaf(p, zTerm, nTerm, zBlob, nBlob, piLeaf, 0);
125455       }
125456       sqlite3_free(zBlob);
125457       piLeaf = 0;
125458       zBlob = 0;
125459     }
125460 
125461     if( rc==SQLITE_OK ){
125462       rc = sqlite3Fts3ReadBlock(p, piLeaf?*piLeaf:*piLeaf2, &zBlob, &nBlob, 0);
125463     }
125464     if( rc==SQLITE_OK ){
125465       rc = fts3SelectLeaf(p, zTerm, nTerm, zBlob, nBlob, piLeaf, piLeaf2);
125466     }
125467     sqlite3_free(zBlob);
125468   }
125469 
125470   return rc;
125471 }
125472 
125473 /*
125474 ** This function is used to create delta-encoded serialized lists of FTS3 
125475 ** varints. Each call to this function appends a single varint to a list.
125476 */
125477 static void fts3PutDeltaVarint(
125478   char **pp,                      /* IN/OUT: Output pointer */
125479   sqlite3_int64 *piPrev,          /* IN/OUT: Previous value written to list */
125480   sqlite3_int64 iVal              /* Write this value to the list */
125481 ){
125482   assert( iVal-*piPrev > 0 || (*piPrev==0 && iVal==0) );
125483   *pp += sqlite3Fts3PutVarint(*pp, iVal-*piPrev);
125484   *piPrev = iVal;
125485 }
125486 
125487 /*
125488 ** When this function is called, *ppPoslist is assumed to point to the 
125489 ** start of a position-list. After it returns, *ppPoslist points to the
125490 ** first byte after the position-list.
125491 **
125492 ** A position list is list of positions (delta encoded) and columns for 
125493 ** a single document record of a doclist.  So, in other words, this
125494 ** routine advances *ppPoslist so that it points to the next docid in
125495 ** the doclist, or to the first byte past the end of the doclist.
125496 **
125497 ** If pp is not NULL, then the contents of the position list are copied
125498 ** to *pp. *pp is set to point to the first byte past the last byte copied
125499 ** before this function returns.
125500 */
125501 static void fts3PoslistCopy(char **pp, char **ppPoslist){
125502   char *pEnd = *ppPoslist;
125503   char c = 0;
125504 
125505   /* The end of a position list is marked by a zero encoded as an FTS3 
125506   ** varint. A single POS_END (0) byte. Except, if the 0 byte is preceded by
125507   ** a byte with the 0x80 bit set, then it is not a varint 0, but the tail
125508   ** of some other, multi-byte, value.
125509   **
125510   ** The following while-loop moves pEnd to point to the first byte that is not 
125511   ** immediately preceded by a byte with the 0x80 bit set. Then increments
125512   ** pEnd once more so that it points to the byte immediately following the
125513   ** last byte in the position-list.
125514   */
125515   while( *pEnd | c ){
125516     c = *pEnd++ & 0x80;
125517     testcase( c!=0 && (*pEnd)==0 );
125518   }
125519   pEnd++;  /* Advance past the POS_END terminator byte */
125520 
125521   if( pp ){
125522     int n = (int)(pEnd - *ppPoslist);
125523     char *p = *pp;
125524     memcpy(p, *ppPoslist, n);
125525     p += n;
125526     *pp = p;
125527   }
125528   *ppPoslist = pEnd;
125529 }
125530 
125531 /*
125532 ** When this function is called, *ppPoslist is assumed to point to the 
125533 ** start of a column-list. After it returns, *ppPoslist points to the
125534 ** to the terminator (POS_COLUMN or POS_END) byte of the column-list.
125535 **
125536 ** A column-list is list of delta-encoded positions for a single column
125537 ** within a single document within a doclist.
125538 **
125539 ** The column-list is terminated either by a POS_COLUMN varint (1) or
125540 ** a POS_END varint (0).  This routine leaves *ppPoslist pointing to
125541 ** the POS_COLUMN or POS_END that terminates the column-list.
125542 **
125543 ** If pp is not NULL, then the contents of the column-list are copied
125544 ** to *pp. *pp is set to point to the first byte past the last byte copied
125545 ** before this function returns.  The POS_COLUMN or POS_END terminator
125546 ** is not copied into *pp.
125547 */
125548 static void fts3ColumnlistCopy(char **pp, char **ppPoslist){
125549   char *pEnd = *ppPoslist;
125550   char c = 0;
125551 
125552   /* A column-list is terminated by either a 0x01 or 0x00 byte that is
125553   ** not part of a multi-byte varint.
125554   */
125555   while( 0xFE & (*pEnd | c) ){
125556     c = *pEnd++ & 0x80;
125557     testcase( c!=0 && ((*pEnd)&0xfe)==0 );
125558   }
125559   if( pp ){
125560     int n = (int)(pEnd - *ppPoslist);
125561     char *p = *pp;
125562     memcpy(p, *ppPoslist, n);
125563     p += n;
125564     *pp = p;
125565   }
125566   *ppPoslist = pEnd;
125567 }
125568 
125569 /*
125570 ** Value used to signify the end of an position-list. This is safe because
125571 ** it is not possible to have a document with 2^31 terms.
125572 */
125573 #define POSITION_LIST_END 0x7fffffff
125574 
125575 /*
125576 ** This function is used to help parse position-lists. When this function is
125577 ** called, *pp may point to the start of the next varint in the position-list
125578 ** being parsed, or it may point to 1 byte past the end of the position-list
125579 ** (in which case **pp will be a terminator bytes POS_END (0) or
125580 ** (1)).
125581 **
125582 ** If *pp points past the end of the current position-list, set *pi to 
125583 ** POSITION_LIST_END and return. Otherwise, read the next varint from *pp,
125584 ** increment the current value of *pi by the value read, and set *pp to
125585 ** point to the next value before returning.
125586 **
125587 ** Before calling this routine *pi must be initialized to the value of
125588 ** the previous position, or zero if we are reading the first position
125589 ** in the position-list.  Because positions are delta-encoded, the value
125590 ** of the previous position is needed in order to compute the value of
125591 ** the next position.
125592 */
125593 static void fts3ReadNextPos(
125594   char **pp,                    /* IN/OUT: Pointer into position-list buffer */
125595   sqlite3_int64 *pi             /* IN/OUT: Value read from position-list */
125596 ){
125597   if( (**pp)&0xFE ){
125598     fts3GetDeltaVarint(pp, pi);
125599     *pi -= 2;
125600   }else{
125601     *pi = POSITION_LIST_END;
125602   }
125603 }
125604 
125605 /*
125606 ** If parameter iCol is not 0, write an POS_COLUMN (1) byte followed by
125607 ** the value of iCol encoded as a varint to *pp.   This will start a new
125608 ** column list.
125609 **
125610 ** Set *pp to point to the byte just after the last byte written before 
125611 ** returning (do not modify it if iCol==0). Return the total number of bytes
125612 ** written (0 if iCol==0).
125613 */
125614 static int fts3PutColNumber(char **pp, int iCol){
125615   int n = 0;                      /* Number of bytes written */
125616   if( iCol ){
125617     char *p = *pp;                /* Output pointer */
125618     n = 1 + sqlite3Fts3PutVarint(&p[1], iCol);
125619     *p = 0x01;
125620     *pp = &p[n];
125621   }
125622   return n;
125623 }
125624 
125625 /*
125626 ** Compute the union of two position lists.  The output written
125627 ** into *pp contains all positions of both *pp1 and *pp2 in sorted
125628 ** order and with any duplicates removed.  All pointers are
125629 ** updated appropriately.   The caller is responsible for insuring
125630 ** that there is enough space in *pp to hold the complete output.
125631 */
125632 static void fts3PoslistMerge(
125633   char **pp,                      /* Output buffer */
125634   char **pp1,                     /* Left input list */
125635   char **pp2                      /* Right input list */
125636 ){
125637   char *p = *pp;
125638   char *p1 = *pp1;
125639   char *p2 = *pp2;
125640 
125641   while( *p1 || *p2 ){
125642     int iCol1;         /* The current column index in pp1 */
125643     int iCol2;         /* The current column index in pp2 */
125644 
125645     if( *p1==POS_COLUMN ) fts3GetVarint32(&p1[1], &iCol1);
125646     else if( *p1==POS_END ) iCol1 = POSITION_LIST_END;
125647     else iCol1 = 0;
125648 
125649     if( *p2==POS_COLUMN ) fts3GetVarint32(&p2[1], &iCol2);
125650     else if( *p2==POS_END ) iCol2 = POSITION_LIST_END;
125651     else iCol2 = 0;
125652 
125653     if( iCol1==iCol2 ){
125654       sqlite3_int64 i1 = 0;       /* Last position from pp1 */
125655       sqlite3_int64 i2 = 0;       /* Last position from pp2 */
125656       sqlite3_int64 iPrev = 0;
125657       int n = fts3PutColNumber(&p, iCol1);
125658       p1 += n;
125659       p2 += n;
125660 
125661       /* At this point, both p1 and p2 point to the start of column-lists
125662       ** for the same column (the column with index iCol1 and iCol2).
125663       ** A column-list is a list of non-negative delta-encoded varints, each 
125664       ** incremented by 2 before being stored. Each list is terminated by a
125665       ** POS_END (0) or POS_COLUMN (1). The following block merges the two lists
125666       ** and writes the results to buffer p. p is left pointing to the byte
125667       ** after the list written. No terminator (POS_END or POS_COLUMN) is
125668       ** written to the output.
125669       */
125670       fts3GetDeltaVarint(&p1, &i1);
125671       fts3GetDeltaVarint(&p2, &i2);
125672       do {
125673         fts3PutDeltaVarint(&p, &iPrev, (i1<i2) ? i1 : i2); 
125674         iPrev -= 2;
125675         if( i1==i2 ){
125676           fts3ReadNextPos(&p1, &i1);
125677           fts3ReadNextPos(&p2, &i2);
125678         }else if( i1<i2 ){
125679           fts3ReadNextPos(&p1, &i1);
125680         }else{
125681           fts3ReadNextPos(&p2, &i2);
125682         }
125683       }while( i1!=POSITION_LIST_END || i2!=POSITION_LIST_END );
125684     }else if( iCol1<iCol2 ){
125685       p1 += fts3PutColNumber(&p, iCol1);
125686       fts3ColumnlistCopy(&p, &p1);
125687     }else{
125688       p2 += fts3PutColNumber(&p, iCol2);
125689       fts3ColumnlistCopy(&p, &p2);
125690     }
125691   }
125692 
125693   *p++ = POS_END;
125694   *pp = p;
125695   *pp1 = p1 + 1;
125696   *pp2 = p2 + 1;
125697 }
125698 
125699 /*
125700 ** This function is used to merge two position lists into one. When it is
125701 ** called, *pp1 and *pp2 must both point to position lists. A position-list is
125702 ** the part of a doclist that follows each document id. For example, if a row
125703 ** contains:
125704 **
125705 **     'a b c'|'x y z'|'a b b a'
125706 **
125707 ** Then the position list for this row for token 'b' would consist of:
125708 **
125709 **     0x02 0x01 0x02 0x03 0x03 0x00
125710 **
125711 ** When this function returns, both *pp1 and *pp2 are left pointing to the
125712 ** byte following the 0x00 terminator of their respective position lists.
125713 **
125714 ** If isSaveLeft is 0, an entry is added to the output position list for 
125715 ** each position in *pp2 for which there exists one or more positions in
125716 ** *pp1 so that (pos(*pp2)>pos(*pp1) && pos(*pp2)-pos(*pp1)<=nToken). i.e.
125717 ** when the *pp1 token appears before the *pp2 token, but not more than nToken
125718 ** slots before it.
125719 **
125720 ** e.g. nToken==1 searches for adjacent positions.
125721 */
125722 static int fts3PoslistPhraseMerge(
125723   char **pp,                      /* IN/OUT: Preallocated output buffer */
125724   int nToken,                     /* Maximum difference in token positions */
125725   int isSaveLeft,                 /* Save the left position */
125726   int isExact,                    /* If *pp1 is exactly nTokens before *pp2 */
125727   char **pp1,                     /* IN/OUT: Left input list */
125728   char **pp2                      /* IN/OUT: Right input list */
125729 ){
125730   char *p = *pp;
125731   char *p1 = *pp1;
125732   char *p2 = *pp2;
125733   int iCol1 = 0;
125734   int iCol2 = 0;
125735 
125736   /* Never set both isSaveLeft and isExact for the same invocation. */
125737   assert( isSaveLeft==0 || isExact==0 );
125738 
125739   assert( p!=0 && *p1!=0 && *p2!=0 );
125740   if( *p1==POS_COLUMN ){ 
125741     p1++;
125742     p1 += fts3GetVarint32(p1, &iCol1);
125743   }
125744   if( *p2==POS_COLUMN ){ 
125745     p2++;
125746     p2 += fts3GetVarint32(p2, &iCol2);
125747   }
125748 
125749   while( 1 ){
125750     if( iCol1==iCol2 ){
125751       char *pSave = p;
125752       sqlite3_int64 iPrev = 0;
125753       sqlite3_int64 iPos1 = 0;
125754       sqlite3_int64 iPos2 = 0;
125755 
125756       if( iCol1 ){
125757         *p++ = POS_COLUMN;
125758         p += sqlite3Fts3PutVarint(p, iCol1);
125759       }
125760 
125761       assert( *p1!=POS_END && *p1!=POS_COLUMN );
125762       assert( *p2!=POS_END && *p2!=POS_COLUMN );
125763       fts3GetDeltaVarint(&p1, &iPos1); iPos1 -= 2;
125764       fts3GetDeltaVarint(&p2, &iPos2); iPos2 -= 2;
125765 
125766       while( 1 ){
125767         if( iPos2==iPos1+nToken 
125768          || (isExact==0 && iPos2>iPos1 && iPos2<=iPos1+nToken) 
125769         ){
125770           sqlite3_int64 iSave;
125771           iSave = isSaveLeft ? iPos1 : iPos2;
125772           fts3PutDeltaVarint(&p, &iPrev, iSave+2); iPrev -= 2;
125773           pSave = 0;
125774           assert( p );
125775         }
125776         if( (!isSaveLeft && iPos2<=(iPos1+nToken)) || iPos2<=iPos1 ){
125777           if( (*p2&0xFE)==0 ) break;
125778           fts3GetDeltaVarint(&p2, &iPos2); iPos2 -= 2;
125779         }else{
125780           if( (*p1&0xFE)==0 ) break;
125781           fts3GetDeltaVarint(&p1, &iPos1); iPos1 -= 2;
125782         }
125783       }
125784 
125785       if( pSave ){
125786         assert( pp && p );
125787         p = pSave;
125788       }
125789 
125790       fts3ColumnlistCopy(0, &p1);
125791       fts3ColumnlistCopy(0, &p2);
125792       assert( (*p1&0xFE)==0 && (*p2&0xFE)==0 );
125793       if( 0==*p1 || 0==*p2 ) break;
125794 
125795       p1++;
125796       p1 += fts3GetVarint32(p1, &iCol1);
125797       p2++;
125798       p2 += fts3GetVarint32(p2, &iCol2);
125799     }
125800 
125801     /* Advance pointer p1 or p2 (whichever corresponds to the smaller of
125802     ** iCol1 and iCol2) so that it points to either the 0x00 that marks the
125803     ** end of the position list, or the 0x01 that precedes the next 
125804     ** column-number in the position list. 
125805     */
125806     else if( iCol1<iCol2 ){
125807       fts3ColumnlistCopy(0, &p1);
125808       if( 0==*p1 ) break;
125809       p1++;
125810       p1 += fts3GetVarint32(p1, &iCol1);
125811     }else{
125812       fts3ColumnlistCopy(0, &p2);
125813       if( 0==*p2 ) break;
125814       p2++;
125815       p2 += fts3GetVarint32(p2, &iCol2);
125816     }
125817   }
125818 
125819   fts3PoslistCopy(0, &p2);
125820   fts3PoslistCopy(0, &p1);
125821   *pp1 = p1;
125822   *pp2 = p2;
125823   if( *pp==p ){
125824     return 0;
125825   }
125826   *p++ = 0x00;
125827   *pp = p;
125828   return 1;
125829 }
125830 
125831 /*
125832 ** Merge two position-lists as required by the NEAR operator. The argument
125833 ** position lists correspond to the left and right phrases of an expression 
125834 ** like:
125835 **
125836 **     "phrase 1" NEAR "phrase number 2"
125837 **
125838 ** Position list *pp1 corresponds to the left-hand side of the NEAR 
125839 ** expression and *pp2 to the right. As usual, the indexes in the position 
125840 ** lists are the offsets of the last token in each phrase (tokens "1" and "2" 
125841 ** in the example above).
125842 **
125843 ** The output position list - written to *pp - is a copy of *pp2 with those
125844 ** entries that are not sufficiently NEAR entries in *pp1 removed.
125845 */
125846 static int fts3PoslistNearMerge(
125847   char **pp,                      /* Output buffer */
125848   char *aTmp,                     /* Temporary buffer space */
125849   int nRight,                     /* Maximum difference in token positions */
125850   int nLeft,                      /* Maximum difference in token positions */
125851   char **pp1,                     /* IN/OUT: Left input list */
125852   char **pp2                      /* IN/OUT: Right input list */
125853 ){
125854   char *p1 = *pp1;
125855   char *p2 = *pp2;
125856 
125857   char *pTmp1 = aTmp;
125858   char *pTmp2;
125859   char *aTmp2;
125860   int res = 1;
125861 
125862   fts3PoslistPhraseMerge(&pTmp1, nRight, 0, 0, pp1, pp2);
125863   aTmp2 = pTmp2 = pTmp1;
125864   *pp1 = p1;
125865   *pp2 = p2;
125866   fts3PoslistPhraseMerge(&pTmp2, nLeft, 1, 0, pp2, pp1);
125867   if( pTmp1!=aTmp && pTmp2!=aTmp2 ){
125868     fts3PoslistMerge(pp, &aTmp, &aTmp2);
125869   }else if( pTmp1!=aTmp ){
125870     fts3PoslistCopy(pp, &aTmp);
125871   }else if( pTmp2!=aTmp2 ){
125872     fts3PoslistCopy(pp, &aTmp2);
125873   }else{
125874     res = 0;
125875   }
125876 
125877   return res;
125878 }
125879 
125880 /* 
125881 ** An instance of this function is used to merge together the (potentially
125882 ** large number of) doclists for each term that matches a prefix query.
125883 ** See function fts3TermSelectMerge() for details.
125884 */
125885 typedef struct TermSelect TermSelect;
125886 struct TermSelect {
125887   char *aaOutput[16];             /* Malloc'd output buffers */
125888   int anOutput[16];               /* Size each output buffer in bytes */
125889 };
125890 
125891 /*
125892 ** This function is used to read a single varint from a buffer. Parameter
125893 ** pEnd points 1 byte past the end of the buffer. When this function is
125894 ** called, if *pp points to pEnd or greater, then the end of the buffer
125895 ** has been reached. In this case *pp is set to 0 and the function returns.
125896 **
125897 ** If *pp does not point to or past pEnd, then a single varint is read
125898 ** from *pp. *pp is then set to point 1 byte past the end of the read varint.
125899 **
125900 ** If bDescIdx is false, the value read is added to *pVal before returning.
125901 ** If it is true, the value read is subtracted from *pVal before this 
125902 ** function returns.
125903 */
125904 static void fts3GetDeltaVarint3(
125905   char **pp,                      /* IN/OUT: Point to read varint from */
125906   char *pEnd,                     /* End of buffer */
125907   int bDescIdx,                   /* True if docids are descending */
125908   sqlite3_int64 *pVal             /* IN/OUT: Integer value */
125909 ){
125910   if( *pp>=pEnd ){
125911     *pp = 0;
125912   }else{
125913     sqlite3_int64 iVal;
125914     *pp += sqlite3Fts3GetVarint(*pp, &iVal);
125915     if( bDescIdx ){
125916       *pVal -= iVal;
125917     }else{
125918       *pVal += iVal;
125919     }
125920   }
125921 }
125922 
125923 /*
125924 ** This function is used to write a single varint to a buffer. The varint
125925 ** is written to *pp. Before returning, *pp is set to point 1 byte past the
125926 ** end of the value written.
125927 **
125928 ** If *pbFirst is zero when this function is called, the value written to
125929 ** the buffer is that of parameter iVal. 
125930 **
125931 ** If *pbFirst is non-zero when this function is called, then the value 
125932 ** written is either (iVal-*piPrev) (if bDescIdx is zero) or (*piPrev-iVal)
125933 ** (if bDescIdx is non-zero).
125934 **
125935 ** Before returning, this function always sets *pbFirst to 1 and *piPrev
125936 ** to the value of parameter iVal.
125937 */
125938 static void fts3PutDeltaVarint3(
125939   char **pp,                      /* IN/OUT: Output pointer */
125940   int bDescIdx,                   /* True for descending docids */
125941   sqlite3_int64 *piPrev,          /* IN/OUT: Previous value written to list */
125942   int *pbFirst,                   /* IN/OUT: True after first int written */
125943   sqlite3_int64 iVal              /* Write this value to the list */
125944 ){
125945   sqlite3_int64 iWrite;
125946   if( bDescIdx==0 || *pbFirst==0 ){
125947     iWrite = iVal - *piPrev;
125948   }else{
125949     iWrite = *piPrev - iVal;
125950   }
125951   assert( *pbFirst || *piPrev==0 );
125952   assert( *pbFirst==0 || iWrite>0 );
125953   *pp += sqlite3Fts3PutVarint(*pp, iWrite);
125954   *piPrev = iVal;
125955   *pbFirst = 1;
125956 }
125957 
125958 
125959 /*
125960 ** This macro is used by various functions that merge doclists. The two
125961 ** arguments are 64-bit docid values. If the value of the stack variable
125962 ** bDescDoclist is 0 when this macro is invoked, then it returns (i1-i2). 
125963 ** Otherwise, (i2-i1).
125964 **
125965 ** Using this makes it easier to write code that can merge doclists that are
125966 ** sorted in either ascending or descending order.
125967 */
125968 #define DOCID_CMP(i1, i2) ((bDescDoclist?-1:1) * (i1-i2))
125969 
125970 /*
125971 ** This function does an "OR" merge of two doclists (output contains all
125972 ** positions contained in either argument doclist). If the docids in the 
125973 ** input doclists are sorted in ascending order, parameter bDescDoclist
125974 ** should be false. If they are sorted in ascending order, it should be
125975 ** passed a non-zero value.
125976 **
125977 ** If no error occurs, *paOut is set to point at an sqlite3_malloc'd buffer
125978 ** containing the output doclist and SQLITE_OK is returned. In this case
125979 ** *pnOut is set to the number of bytes in the output doclist.
125980 **
125981 ** If an error occurs, an SQLite error code is returned. The output values
125982 ** are undefined in this case.
125983 */
125984 static int fts3DoclistOrMerge(
125985   int bDescDoclist,               /* True if arguments are desc */
125986   char *a1, int n1,               /* First doclist */
125987   char *a2, int n2,               /* Second doclist */
125988   char **paOut, int *pnOut        /* OUT: Malloc'd doclist */
125989 ){
125990   sqlite3_int64 i1 = 0;
125991   sqlite3_int64 i2 = 0;
125992   sqlite3_int64 iPrev = 0;
125993   char *pEnd1 = &a1[n1];
125994   char *pEnd2 = &a2[n2];
125995   char *p1 = a1;
125996   char *p2 = a2;
125997   char *p;
125998   char *aOut;
125999   int bFirstOut = 0;
126000 
126001   *paOut = 0;
126002   *pnOut = 0;
126003 
126004   /* Allocate space for the output. Both the input and output doclists
126005   ** are delta encoded. If they are in ascending order (bDescDoclist==0),
126006   ** then the first docid in each list is simply encoded as a varint. For
126007   ** each subsequent docid, the varint stored is the difference between the
126008   ** current and previous docid (a positive number - since the list is in
126009   ** ascending order).
126010   **
126011   ** The first docid written to the output is therefore encoded using the 
126012   ** same number of bytes as it is in whichever of the input lists it is
126013   ** read from. And each subsequent docid read from the same input list 
126014   ** consumes either the same or less bytes as it did in the input (since
126015   ** the difference between it and the previous value in the output must
126016   ** be a positive value less than or equal to the delta value read from 
126017   ** the input list). The same argument applies to all but the first docid
126018   ** read from the 'other' list. And to the contents of all position lists
126019   ** that will be copied and merged from the input to the output.
126020   **
126021   ** However, if the first docid copied to the output is a negative number,
126022   ** then the encoding of the first docid from the 'other' input list may
126023   ** be larger in the output than it was in the input (since the delta value
126024   ** may be a larger positive integer than the actual docid).
126025   **
126026   ** The space required to store the output is therefore the sum of the
126027   ** sizes of the two inputs, plus enough space for exactly one of the input
126028   ** docids to grow. 
126029   **
126030   ** A symetric argument may be made if the doclists are in descending 
126031   ** order.
126032   */
126033   aOut = sqlite3_malloc(n1+n2+FTS3_VARINT_MAX-1);
126034   if( !aOut ) return SQLITE_NOMEM;
126035 
126036   p = aOut;
126037   fts3GetDeltaVarint3(&p1, pEnd1, 0, &i1);
126038   fts3GetDeltaVarint3(&p2, pEnd2, 0, &i2);
126039   while( p1 || p2 ){
126040     sqlite3_int64 iDiff = DOCID_CMP(i1, i2);
126041 
126042     if( p2 && p1 && iDiff==0 ){
126043       fts3PutDeltaVarint3(&p, bDescDoclist, &iPrev, &bFirstOut, i1);
126044       fts3PoslistMerge(&p, &p1, &p2);
126045       fts3GetDeltaVarint3(&p1, pEnd1, bDescDoclist, &i1);
126046       fts3GetDeltaVarint3(&p2, pEnd2, bDescDoclist, &i2);
126047     }else if( !p2 || (p1 && iDiff<0) ){
126048       fts3PutDeltaVarint3(&p, bDescDoclist, &iPrev, &bFirstOut, i1);
126049       fts3PoslistCopy(&p, &p1);
126050       fts3GetDeltaVarint3(&p1, pEnd1, bDescDoclist, &i1);
126051     }else{
126052       fts3PutDeltaVarint3(&p, bDescDoclist, &iPrev, &bFirstOut, i2);
126053       fts3PoslistCopy(&p, &p2);
126054       fts3GetDeltaVarint3(&p2, pEnd2, bDescDoclist, &i2);
126055     }
126056   }
126057 
126058   *paOut = aOut;
126059   *pnOut = (int)(p-aOut);
126060   assert( *pnOut<=n1+n2+FTS3_VARINT_MAX-1 );
126061   return SQLITE_OK;
126062 }
126063 
126064 /*
126065 ** This function does a "phrase" merge of two doclists. In a phrase merge,
126066 ** the output contains a copy of each position from the right-hand input
126067 ** doclist for which there is a position in the left-hand input doclist
126068 ** exactly nDist tokens before it.
126069 **
126070 ** If the docids in the input doclists are sorted in ascending order,
126071 ** parameter bDescDoclist should be false. If they are sorted in ascending 
126072 ** order, it should be passed a non-zero value.
126073 **
126074 ** The right-hand input doclist is overwritten by this function.
126075 */
126076 static void fts3DoclistPhraseMerge(
126077   int bDescDoclist,               /* True if arguments are desc */
126078   int nDist,                      /* Distance from left to right (1=adjacent) */
126079   char *aLeft, int nLeft,         /* Left doclist */
126080   char *aRight, int *pnRight      /* IN/OUT: Right/output doclist */
126081 ){
126082   sqlite3_int64 i1 = 0;
126083   sqlite3_int64 i2 = 0;
126084   sqlite3_int64 iPrev = 0;
126085   char *pEnd1 = &aLeft[nLeft];
126086   char *pEnd2 = &aRight[*pnRight];
126087   char *p1 = aLeft;
126088   char *p2 = aRight;
126089   char *p;
126090   int bFirstOut = 0;
126091   char *aOut = aRight;
126092 
126093   assert( nDist>0 );
126094 
126095   p = aOut;
126096   fts3GetDeltaVarint3(&p1, pEnd1, 0, &i1);
126097   fts3GetDeltaVarint3(&p2, pEnd2, 0, &i2);
126098 
126099   while( p1 && p2 ){
126100     sqlite3_int64 iDiff = DOCID_CMP(i1, i2);
126101     if( iDiff==0 ){
126102       char *pSave = p;
126103       sqlite3_int64 iPrevSave = iPrev;
126104       int bFirstOutSave = bFirstOut;
126105 
126106       fts3PutDeltaVarint3(&p, bDescDoclist, &iPrev, &bFirstOut, i1);
126107       if( 0==fts3PoslistPhraseMerge(&p, nDist, 0, 1, &p1, &p2) ){
126108         p = pSave;
126109         iPrev = iPrevSave;
126110         bFirstOut = bFirstOutSave;
126111       }
126112       fts3GetDeltaVarint3(&p1, pEnd1, bDescDoclist, &i1);
126113       fts3GetDeltaVarint3(&p2, pEnd2, bDescDoclist, &i2);
126114     }else if( iDiff<0 ){
126115       fts3PoslistCopy(0, &p1);
126116       fts3GetDeltaVarint3(&p1, pEnd1, bDescDoclist, &i1);
126117     }else{
126118       fts3PoslistCopy(0, &p2);
126119       fts3GetDeltaVarint3(&p2, pEnd2, bDescDoclist, &i2);
126120     }
126121   }
126122 
126123   *pnRight = (int)(p - aOut);
126124 }
126125 
126126 /*
126127 ** Argument pList points to a position list nList bytes in size. This
126128 ** function checks to see if the position list contains any entries for
126129 ** a token in position 0 (of any column). If so, it writes argument iDelta
126130 ** to the output buffer pOut, followed by a position list consisting only
126131 ** of the entries from pList at position 0, and terminated by an 0x00 byte.
126132 ** The value returned is the number of bytes written to pOut (if any).
126133 */
126134 SQLITE_PRIVATE int sqlite3Fts3FirstFilter(
126135   sqlite3_int64 iDelta,           /* Varint that may be written to pOut */
126136   char *pList,                    /* Position list (no 0x00 term) */
126137   int nList,                      /* Size of pList in bytes */
126138   char *pOut                      /* Write output here */
126139 ){
126140   int nOut = 0;
126141   int bWritten = 0;               /* True once iDelta has been written */
126142   char *p = pList;
126143   char *pEnd = &pList[nList];
126144 
126145   if( *p!=0x01 ){
126146     if( *p==0x02 ){
126147       nOut += sqlite3Fts3PutVarint(&pOut[nOut], iDelta);
126148       pOut[nOut++] = 0x02;
126149       bWritten = 1;
126150     }
126151     fts3ColumnlistCopy(0, &p);
126152   }
126153 
126154   while( p<pEnd && *p==0x01 ){
126155     sqlite3_int64 iCol;
126156     p++;
126157     p += sqlite3Fts3GetVarint(p, &iCol);
126158     if( *p==0x02 ){
126159       if( bWritten==0 ){
126160         nOut += sqlite3Fts3PutVarint(&pOut[nOut], iDelta);
126161         bWritten = 1;
126162       }
126163       pOut[nOut++] = 0x01;
126164       nOut += sqlite3Fts3PutVarint(&pOut[nOut], iCol);
126165       pOut[nOut++] = 0x02;
126166     }
126167     fts3ColumnlistCopy(0, &p);
126168   }
126169   if( bWritten ){
126170     pOut[nOut++] = 0x00;
126171   }
126172 
126173   return nOut;
126174 }
126175 
126176 
126177 /*
126178 ** Merge all doclists in the TermSelect.aaOutput[] array into a single
126179 ** doclist stored in TermSelect.aaOutput[0]. If successful, delete all
126180 ** other doclists (except the aaOutput[0] one) and return SQLITE_OK.
126181 **
126182 ** If an OOM error occurs, return SQLITE_NOMEM. In this case it is
126183 ** the responsibility of the caller to free any doclists left in the
126184 ** TermSelect.aaOutput[] array.
126185 */
126186 static int fts3TermSelectFinishMerge(Fts3Table *p, TermSelect *pTS){
126187   char *aOut = 0;
126188   int nOut = 0;
126189   int i;
126190 
126191   /* Loop through the doclists in the aaOutput[] array. Merge them all
126192   ** into a single doclist.
126193   */
126194   for(i=0; i<SizeofArray(pTS->aaOutput); i++){
126195     if( pTS->aaOutput[i] ){
126196       if( !aOut ){
126197         aOut = pTS->aaOutput[i];
126198         nOut = pTS->anOutput[i];
126199         pTS->aaOutput[i] = 0;
126200       }else{
126201         int nNew;
126202         char *aNew;
126203 
126204         int rc = fts3DoclistOrMerge(p->bDescIdx, 
126205             pTS->aaOutput[i], pTS->anOutput[i], aOut, nOut, &aNew, &nNew
126206         );
126207         if( rc!=SQLITE_OK ){
126208           sqlite3_free(aOut);
126209           return rc;
126210         }
126211 
126212         sqlite3_free(pTS->aaOutput[i]);
126213         sqlite3_free(aOut);
126214         pTS->aaOutput[i] = 0;
126215         aOut = aNew;
126216         nOut = nNew;
126217       }
126218     }
126219   }
126220 
126221   pTS->aaOutput[0] = aOut;
126222   pTS->anOutput[0] = nOut;
126223   return SQLITE_OK;
126224 }
126225 
126226 /*
126227 ** Merge the doclist aDoclist/nDoclist into the TermSelect object passed
126228 ** as the first argument. The merge is an "OR" merge (see function
126229 ** fts3DoclistOrMerge() for details).
126230 **
126231 ** This function is called with the doclist for each term that matches
126232 ** a queried prefix. It merges all these doclists into one, the doclist
126233 ** for the specified prefix. Since there can be a very large number of
126234 ** doclists to merge, the merging is done pair-wise using the TermSelect
126235 ** object.
126236 **
126237 ** This function returns SQLITE_OK if the merge is successful, or an
126238 ** SQLite error code (SQLITE_NOMEM) if an error occurs.
126239 */
126240 static int fts3TermSelectMerge(
126241   Fts3Table *p,                   /* FTS table handle */
126242   TermSelect *pTS,                /* TermSelect object to merge into */
126243   char *aDoclist,                 /* Pointer to doclist */
126244   int nDoclist                    /* Size of aDoclist in bytes */
126245 ){
126246   if( pTS->aaOutput[0]==0 ){
126247     /* If this is the first term selected, copy the doclist to the output
126248     ** buffer using memcpy(). */
126249     pTS->aaOutput[0] = sqlite3_malloc(nDoclist);
126250     pTS->anOutput[0] = nDoclist;
126251     if( pTS->aaOutput[0] ){
126252       memcpy(pTS->aaOutput[0], aDoclist, nDoclist);
126253     }else{
126254       return SQLITE_NOMEM;
126255     }
126256   }else{
126257     char *aMerge = aDoclist;
126258     int nMerge = nDoclist;
126259     int iOut;
126260 
126261     for(iOut=0; iOut<SizeofArray(pTS->aaOutput); iOut++){
126262       if( pTS->aaOutput[iOut]==0 ){
126263         assert( iOut>0 );
126264         pTS->aaOutput[iOut] = aMerge;
126265         pTS->anOutput[iOut] = nMerge;
126266         break;
126267       }else{
126268         char *aNew;
126269         int nNew;
126270 
126271         int rc = fts3DoclistOrMerge(p->bDescIdx, aMerge, nMerge, 
126272             pTS->aaOutput[iOut], pTS->anOutput[iOut], &aNew, &nNew
126273         );
126274         if( rc!=SQLITE_OK ){
126275           if( aMerge!=aDoclist ) sqlite3_free(aMerge);
126276           return rc;
126277         }
126278 
126279         if( aMerge!=aDoclist ) sqlite3_free(aMerge);
126280         sqlite3_free(pTS->aaOutput[iOut]);
126281         pTS->aaOutput[iOut] = 0;
126282   
126283         aMerge = aNew;
126284         nMerge = nNew;
126285         if( (iOut+1)==SizeofArray(pTS->aaOutput) ){
126286           pTS->aaOutput[iOut] = aMerge;
126287           pTS->anOutput[iOut] = nMerge;
126288         }
126289       }
126290     }
126291   }
126292   return SQLITE_OK;
126293 }
126294 
126295 /*
126296 ** Append SegReader object pNew to the end of the pCsr->apSegment[] array.
126297 */
126298 static int fts3SegReaderCursorAppend(
126299   Fts3MultiSegReader *pCsr, 
126300   Fts3SegReader *pNew
126301 ){
126302   if( (pCsr->nSegment%16)==0 ){
126303     Fts3SegReader **apNew;
126304     int nByte = (pCsr->nSegment + 16)*sizeof(Fts3SegReader*);
126305     apNew = (Fts3SegReader **)sqlite3_realloc(pCsr->apSegment, nByte);
126306     if( !apNew ){
126307       sqlite3Fts3SegReaderFree(pNew);
126308       return SQLITE_NOMEM;
126309     }
126310     pCsr->apSegment = apNew;
126311   }
126312   pCsr->apSegment[pCsr->nSegment++] = pNew;
126313   return SQLITE_OK;
126314 }
126315 
126316 /*
126317 ** Add seg-reader objects to the Fts3MultiSegReader object passed as the
126318 ** 8th argument.
126319 **
126320 ** This function returns SQLITE_OK if successful, or an SQLite error code
126321 ** otherwise.
126322 */
126323 static int fts3SegReaderCursor(
126324   Fts3Table *p,                   /* FTS3 table handle */
126325   int iLangid,                    /* Language id */
126326   int iIndex,                     /* Index to search (from 0 to p->nIndex-1) */
126327   int iLevel,                     /* Level of segments to scan */
126328   const char *zTerm,              /* Term to query for */
126329   int nTerm,                      /* Size of zTerm in bytes */
126330   int isPrefix,                   /* True for a prefix search */
126331   int isScan,                     /* True to scan from zTerm to EOF */
126332   Fts3MultiSegReader *pCsr        /* Cursor object to populate */
126333 ){
126334   int rc = SQLITE_OK;             /* Error code */
126335   sqlite3_stmt *pStmt = 0;        /* Statement to iterate through segments */
126336   int rc2;                        /* Result of sqlite3_reset() */
126337 
126338   /* If iLevel is less than 0 and this is not a scan, include a seg-reader 
126339   ** for the pending-terms. If this is a scan, then this call must be being
126340   ** made by an fts4aux module, not an FTS table. In this case calling
126341   ** Fts3SegReaderPending might segfault, as the data structures used by 
126342   ** fts4aux are not completely populated. So it's easiest to filter these
126343   ** calls out here.  */
126344   if( iLevel<0 && p->aIndex ){
126345     Fts3SegReader *pSeg = 0;
126346     rc = sqlite3Fts3SegReaderPending(p, iIndex, zTerm, nTerm, isPrefix, &pSeg);
126347     if( rc==SQLITE_OK && pSeg ){
126348       rc = fts3SegReaderCursorAppend(pCsr, pSeg);
126349     }
126350   }
126351 
126352   if( iLevel!=FTS3_SEGCURSOR_PENDING ){
126353     if( rc==SQLITE_OK ){
126354       rc = sqlite3Fts3AllSegdirs(p, iLangid, iIndex, iLevel, &pStmt);
126355     }
126356 
126357     while( rc==SQLITE_OK && SQLITE_ROW==(rc = sqlite3_step(pStmt)) ){
126358       Fts3SegReader *pSeg = 0;
126359 
126360       /* Read the values returned by the SELECT into local variables. */
126361       sqlite3_int64 iStartBlock = sqlite3_column_int64(pStmt, 1);
126362       sqlite3_int64 iLeavesEndBlock = sqlite3_column_int64(pStmt, 2);
126363       sqlite3_int64 iEndBlock = sqlite3_column_int64(pStmt, 3);
126364       int nRoot = sqlite3_column_bytes(pStmt, 4);
126365       char const *zRoot = sqlite3_column_blob(pStmt, 4);
126366 
126367       /* If zTerm is not NULL, and this segment is not stored entirely on its
126368       ** root node, the range of leaves scanned can be reduced. Do this. */
126369       if( iStartBlock && zTerm ){
126370         sqlite3_int64 *pi = (isPrefix ? &iLeavesEndBlock : 0);
126371         rc = fts3SelectLeaf(p, zTerm, nTerm, zRoot, nRoot, &iStartBlock, pi);
126372         if( rc!=SQLITE_OK ) goto finished;
126373         if( isPrefix==0 && isScan==0 ) iLeavesEndBlock = iStartBlock;
126374       }
126375  
126376       rc = sqlite3Fts3SegReaderNew(pCsr->nSegment+1, 
126377           (isPrefix==0 && isScan==0),
126378           iStartBlock, iLeavesEndBlock, 
126379           iEndBlock, zRoot, nRoot, &pSeg
126380       );
126381       if( rc!=SQLITE_OK ) goto finished;
126382       rc = fts3SegReaderCursorAppend(pCsr, pSeg);
126383     }
126384   }
126385 
126386  finished:
126387   rc2 = sqlite3_reset(pStmt);
126388   if( rc==SQLITE_DONE ) rc = rc2;
126389 
126390   return rc;
126391 }
126392 
126393 /*
126394 ** Set up a cursor object for iterating through a full-text index or a 
126395 ** single level therein.
126396 */
126397 SQLITE_PRIVATE int sqlite3Fts3SegReaderCursor(
126398   Fts3Table *p,                   /* FTS3 table handle */
126399   int iLangid,                    /* Language-id to search */
126400   int iIndex,                     /* Index to search (from 0 to p->nIndex-1) */
126401   int iLevel,                     /* Level of segments to scan */
126402   const char *zTerm,              /* Term to query for */
126403   int nTerm,                      /* Size of zTerm in bytes */
126404   int isPrefix,                   /* True for a prefix search */
126405   int isScan,                     /* True to scan from zTerm to EOF */
126406   Fts3MultiSegReader *pCsr       /* Cursor object to populate */
126407 ){
126408   assert( iIndex>=0 && iIndex<p->nIndex );
126409   assert( iLevel==FTS3_SEGCURSOR_ALL
126410       ||  iLevel==FTS3_SEGCURSOR_PENDING 
126411       ||  iLevel>=0
126412   );
126413   assert( iLevel<FTS3_SEGDIR_MAXLEVEL );
126414   assert( FTS3_SEGCURSOR_ALL<0 && FTS3_SEGCURSOR_PENDING<0 );
126415   assert( isPrefix==0 || isScan==0 );
126416 
126417   memset(pCsr, 0, sizeof(Fts3MultiSegReader));
126418   return fts3SegReaderCursor(
126419       p, iLangid, iIndex, iLevel, zTerm, nTerm, isPrefix, isScan, pCsr
126420   );
126421 }
126422 
126423 /*
126424 ** In addition to its current configuration, have the Fts3MultiSegReader
126425 ** passed as the 4th argument also scan the doclist for term zTerm/nTerm.
126426 **
126427 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
126428 */
126429 static int fts3SegReaderCursorAddZero(
126430   Fts3Table *p,                   /* FTS virtual table handle */
126431   int iLangid,
126432   const char *zTerm,              /* Term to scan doclist of */
126433   int nTerm,                      /* Number of bytes in zTerm */
126434   Fts3MultiSegReader *pCsr        /* Fts3MultiSegReader to modify */
126435 ){
126436   return fts3SegReaderCursor(p, 
126437       iLangid, 0, FTS3_SEGCURSOR_ALL, zTerm, nTerm, 0, 0,pCsr
126438   );
126439 }
126440 
126441 /*
126442 ** Open an Fts3MultiSegReader to scan the doclist for term zTerm/nTerm. Or,
126443 ** if isPrefix is true, to scan the doclist for all terms for which 
126444 ** zTerm/nTerm is a prefix. If successful, return SQLITE_OK and write
126445 ** a pointer to the new Fts3MultiSegReader to *ppSegcsr. Otherwise, return
126446 ** an SQLite error code.
126447 **
126448 ** It is the responsibility of the caller to free this object by eventually
126449 ** passing it to fts3SegReaderCursorFree() 
126450 **
126451 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
126452 ** Output parameter *ppSegcsr is set to 0 if an error occurs.
126453 */
126454 static int fts3TermSegReaderCursor(
126455   Fts3Cursor *pCsr,               /* Virtual table cursor handle */
126456   const char *zTerm,              /* Term to query for */
126457   int nTerm,                      /* Size of zTerm in bytes */
126458   int isPrefix,                   /* True for a prefix search */
126459   Fts3MultiSegReader **ppSegcsr   /* OUT: Allocated seg-reader cursor */
126460 ){
126461   Fts3MultiSegReader *pSegcsr;    /* Object to allocate and return */
126462   int rc = SQLITE_NOMEM;          /* Return code */
126463 
126464   pSegcsr = sqlite3_malloc(sizeof(Fts3MultiSegReader));
126465   if( pSegcsr ){
126466     int i;
126467     int bFound = 0;               /* True once an index has been found */
126468     Fts3Table *p = (Fts3Table *)pCsr->base.pVtab;
126469 
126470     if( isPrefix ){
126471       for(i=1; bFound==0 && i<p->nIndex; i++){
126472         if( p->aIndex[i].nPrefix==nTerm ){
126473           bFound = 1;
126474           rc = sqlite3Fts3SegReaderCursor(p, pCsr->iLangid, 
126475               i, FTS3_SEGCURSOR_ALL, zTerm, nTerm, 0, 0, pSegcsr
126476           );
126477           pSegcsr->bLookup = 1;
126478         }
126479       }
126480 
126481       for(i=1; bFound==0 && i<p->nIndex; i++){
126482         if( p->aIndex[i].nPrefix==nTerm+1 ){
126483           bFound = 1;
126484           rc = sqlite3Fts3SegReaderCursor(p, pCsr->iLangid, 
126485               i, FTS3_SEGCURSOR_ALL, zTerm, nTerm, 1, 0, pSegcsr
126486           );
126487           if( rc==SQLITE_OK ){
126488             rc = fts3SegReaderCursorAddZero(
126489                 p, pCsr->iLangid, zTerm, nTerm, pSegcsr
126490             );
126491           }
126492         }
126493       }
126494     }
126495 
126496     if( bFound==0 ){
126497       rc = sqlite3Fts3SegReaderCursor(p, pCsr->iLangid, 
126498           0, FTS3_SEGCURSOR_ALL, zTerm, nTerm, isPrefix, 0, pSegcsr
126499       );
126500       pSegcsr->bLookup = !isPrefix;
126501     }
126502   }
126503 
126504   *ppSegcsr = pSegcsr;
126505   return rc;
126506 }
126507 
126508 /*
126509 ** Free an Fts3MultiSegReader allocated by fts3TermSegReaderCursor().
126510 */
126511 static void fts3SegReaderCursorFree(Fts3MultiSegReader *pSegcsr){
126512   sqlite3Fts3SegReaderFinish(pSegcsr);
126513   sqlite3_free(pSegcsr);
126514 }
126515 
126516 /*
126517 ** This function retrieves the doclist for the specified term (or term
126518 ** prefix) from the database.
126519 */
126520 static int fts3TermSelect(
126521   Fts3Table *p,                   /* Virtual table handle */
126522   Fts3PhraseToken *pTok,          /* Token to query for */
126523   int iColumn,                    /* Column to query (or -ve for all columns) */
126524   int *pnOut,                     /* OUT: Size of buffer at *ppOut */
126525   char **ppOut                    /* OUT: Malloced result buffer */
126526 ){
126527   int rc;                         /* Return code */
126528   Fts3MultiSegReader *pSegcsr;    /* Seg-reader cursor for this term */
126529   TermSelect tsc;                 /* Object for pair-wise doclist merging */
126530   Fts3SegFilter filter;           /* Segment term filter configuration */
126531 
126532   pSegcsr = pTok->pSegcsr;
126533   memset(&tsc, 0, sizeof(TermSelect));
126534 
126535   filter.flags = FTS3_SEGMENT_IGNORE_EMPTY | FTS3_SEGMENT_REQUIRE_POS
126536         | (pTok->isPrefix ? FTS3_SEGMENT_PREFIX : 0)
126537         | (pTok->bFirst ? FTS3_SEGMENT_FIRST : 0)
126538         | (iColumn<p->nColumn ? FTS3_SEGMENT_COLUMN_FILTER : 0);
126539   filter.iCol = iColumn;
126540   filter.zTerm = pTok->z;
126541   filter.nTerm = pTok->n;
126542 
126543   rc = sqlite3Fts3SegReaderStart(p, pSegcsr, &filter);
126544   while( SQLITE_OK==rc
126545       && SQLITE_ROW==(rc = sqlite3Fts3SegReaderStep(p, pSegcsr)) 
126546   ){
126547     rc = fts3TermSelectMerge(p, &tsc, pSegcsr->aDoclist, pSegcsr->nDoclist);
126548   }
126549 
126550   if( rc==SQLITE_OK ){
126551     rc = fts3TermSelectFinishMerge(p, &tsc);
126552   }
126553   if( rc==SQLITE_OK ){
126554     *ppOut = tsc.aaOutput[0];
126555     *pnOut = tsc.anOutput[0];
126556   }else{
126557     int i;
126558     for(i=0; i<SizeofArray(tsc.aaOutput); i++){
126559       sqlite3_free(tsc.aaOutput[i]);
126560     }
126561   }
126562 
126563   fts3SegReaderCursorFree(pSegcsr);
126564   pTok->pSegcsr = 0;
126565   return rc;
126566 }
126567 
126568 /*
126569 ** This function counts the total number of docids in the doclist stored
126570 ** in buffer aList[], size nList bytes.
126571 **
126572 ** If the isPoslist argument is true, then it is assumed that the doclist
126573 ** contains a position-list following each docid. Otherwise, it is assumed
126574 ** that the doclist is simply a list of docids stored as delta encoded 
126575 ** varints.
126576 */
126577 static int fts3DoclistCountDocids(char *aList, int nList){
126578   int nDoc = 0;                   /* Return value */
126579   if( aList ){
126580     char *aEnd = &aList[nList];   /* Pointer to one byte after EOF */
126581     char *p = aList;              /* Cursor */
126582     while( p<aEnd ){
126583       nDoc++;
126584       while( (*p++)&0x80 );     /* Skip docid varint */
126585       fts3PoslistCopy(0, &p);   /* Skip over position list */
126586     }
126587   }
126588 
126589   return nDoc;
126590 }
126591 
126592 /*
126593 ** Advance the cursor to the next row in the %_content table that
126594 ** matches the search criteria.  For a MATCH search, this will be
126595 ** the next row that matches. For a full-table scan, this will be
126596 ** simply the next row in the %_content table.  For a docid lookup,
126597 ** this routine simply sets the EOF flag.
126598 **
126599 ** Return SQLITE_OK if nothing goes wrong.  SQLITE_OK is returned
126600 ** even if we reach end-of-file.  The fts3EofMethod() will be called
126601 ** subsequently to determine whether or not an EOF was hit.
126602 */
126603 static int fts3NextMethod(sqlite3_vtab_cursor *pCursor){
126604   int rc;
126605   Fts3Cursor *pCsr = (Fts3Cursor *)pCursor;
126606   if( pCsr->eSearch==FTS3_DOCID_SEARCH || pCsr->eSearch==FTS3_FULLSCAN_SEARCH ){
126607     if( SQLITE_ROW!=sqlite3_step(pCsr->pStmt) ){
126608       pCsr->isEof = 1;
126609       rc = sqlite3_reset(pCsr->pStmt);
126610     }else{
126611       pCsr->iPrevId = sqlite3_column_int64(pCsr->pStmt, 0);
126612       rc = SQLITE_OK;
126613     }
126614   }else{
126615     rc = fts3EvalNext((Fts3Cursor *)pCursor);
126616   }
126617   assert( ((Fts3Table *)pCsr->base.pVtab)->pSegments==0 );
126618   return rc;
126619 }
126620 
126621 /*
126622 ** The following are copied from sqliteInt.h.
126623 **
126624 ** Constants for the largest and smallest possible 64-bit signed integers.
126625 ** These macros are designed to work correctly on both 32-bit and 64-bit
126626 ** compilers.
126627 */
126628 #ifndef SQLITE_AMALGAMATION
126629 # define LARGEST_INT64  (0xffffffff|(((sqlite3_int64)0x7fffffff)<<32))
126630 # define SMALLEST_INT64 (((sqlite3_int64)-1) - LARGEST_INT64)
126631 #endif
126632 
126633 /*
126634 ** If the numeric type of argument pVal is "integer", then return it
126635 ** converted to a 64-bit signed integer. Otherwise, return a copy of
126636 ** the second parameter, iDefault.
126637 */
126638 static sqlite3_int64 fts3DocidRange(sqlite3_value *pVal, i64 iDefault){
126639   if( pVal ){
126640     int eType = sqlite3_value_numeric_type(pVal);
126641     if( eType==SQLITE_INTEGER ){
126642       return sqlite3_value_int64(pVal);
126643     }
126644   }
126645   return iDefault;
126646 }
126647 
126648 /*
126649 ** This is the xFilter interface for the virtual table.  See
126650 ** the virtual table xFilter method documentation for additional
126651 ** information.
126652 **
126653 ** If idxNum==FTS3_FULLSCAN_SEARCH then do a full table scan against
126654 ** the %_content table.
126655 **
126656 ** If idxNum==FTS3_DOCID_SEARCH then do a docid lookup for a single entry
126657 ** in the %_content table.
126658 **
126659 ** If idxNum>=FTS3_FULLTEXT_SEARCH then use the full text index.  The
126660 ** column on the left-hand side of the MATCH operator is column
126661 ** number idxNum-FTS3_FULLTEXT_SEARCH, 0 indexed.  argv[0] is the right-hand
126662 ** side of the MATCH operator.
126663 */
126664 static int fts3FilterMethod(
126665   sqlite3_vtab_cursor *pCursor,   /* The cursor used for this query */
126666   int idxNum,                     /* Strategy index */
126667   const char *idxStr,             /* Unused */
126668   int nVal,                       /* Number of elements in apVal */
126669   sqlite3_value **apVal           /* Arguments for the indexing scheme */
126670 ){
126671   int rc;
126672   char *zSql;                     /* SQL statement used to access %_content */
126673   int eSearch;
126674   Fts3Table *p = (Fts3Table *)pCursor->pVtab;
126675   Fts3Cursor *pCsr = (Fts3Cursor *)pCursor;
126676 
126677   sqlite3_value *pCons = 0;       /* The MATCH or rowid constraint, if any */
126678   sqlite3_value *pLangid = 0;     /* The "langid = ?" constraint, if any */
126679   sqlite3_value *pDocidGe = 0;    /* The "docid >= ?" constraint, if any */
126680   sqlite3_value *pDocidLe = 0;    /* The "docid <= ?" constraint, if any */
126681   int iIdx;
126682 
126683   UNUSED_PARAMETER(idxStr);
126684   UNUSED_PARAMETER(nVal);
126685 
126686   eSearch = (idxNum & 0x0000FFFF);
126687   assert( eSearch>=0 && eSearch<=(FTS3_FULLTEXT_SEARCH+p->nColumn) );
126688   assert( p->pSegments==0 );
126689 
126690   /* Collect arguments into local variables */
126691   iIdx = 0;
126692   if( eSearch!=FTS3_FULLSCAN_SEARCH ) pCons = apVal[iIdx++];
126693   if( idxNum & FTS3_HAVE_LANGID ) pLangid = apVal[iIdx++];
126694   if( idxNum & FTS3_HAVE_DOCID_GE ) pDocidGe = apVal[iIdx++];
126695   if( idxNum & FTS3_HAVE_DOCID_LE ) pDocidLe = apVal[iIdx++];
126696   assert( iIdx==nVal );
126697 
126698   /* In case the cursor has been used before, clear it now. */
126699   sqlite3_finalize(pCsr->pStmt);
126700   sqlite3_free(pCsr->aDoclist);
126701   sqlite3Fts3ExprFree(pCsr->pExpr);
126702   memset(&pCursor[1], 0, sizeof(Fts3Cursor)-sizeof(sqlite3_vtab_cursor));
126703 
126704   /* Set the lower and upper bounds on docids to return */
126705   pCsr->iMinDocid = fts3DocidRange(pDocidGe, SMALLEST_INT64);
126706   pCsr->iMaxDocid = fts3DocidRange(pDocidLe, LARGEST_INT64);
126707 
126708   if( idxStr ){
126709     pCsr->bDesc = (idxStr[0]=='D');
126710   }else{
126711     pCsr->bDesc = p->bDescIdx;
126712   }
126713   pCsr->eSearch = (i16)eSearch;
126714 
126715   if( eSearch!=FTS3_DOCID_SEARCH && eSearch!=FTS3_FULLSCAN_SEARCH ){
126716     int iCol = eSearch-FTS3_FULLTEXT_SEARCH;
126717     const char *zQuery = (const char *)sqlite3_value_text(pCons);
126718 
126719     if( zQuery==0 && sqlite3_value_type(pCons)!=SQLITE_NULL ){
126720       return SQLITE_NOMEM;
126721     }
126722 
126723     pCsr->iLangid = 0;
126724     if( pLangid ) pCsr->iLangid = sqlite3_value_int(pLangid);
126725 
126726     assert( p->base.zErrMsg==0 );
126727     rc = sqlite3Fts3ExprParse(p->pTokenizer, pCsr->iLangid,
126728         p->azColumn, p->bFts4, p->nColumn, iCol, zQuery, -1, &pCsr->pExpr, 
126729         &p->base.zErrMsg
126730     );
126731     if( rc!=SQLITE_OK ){
126732       return rc;
126733     }
126734 
126735     rc = fts3EvalStart(pCsr);
126736     sqlite3Fts3SegmentsClose(p);
126737     if( rc!=SQLITE_OK ) return rc;
126738     pCsr->pNextId = pCsr->aDoclist;
126739     pCsr->iPrevId = 0;
126740   }
126741 
126742   /* Compile a SELECT statement for this cursor. For a full-table-scan, the
126743   ** statement loops through all rows of the %_content table. For a
126744   ** full-text query or docid lookup, the statement retrieves a single
126745   ** row by docid.
126746   */
126747   if( eSearch==FTS3_FULLSCAN_SEARCH ){
126748     zSql = sqlite3_mprintf(
126749         "SELECT %s ORDER BY rowid %s",
126750         p->zReadExprlist, (pCsr->bDesc ? "DESC" : "ASC")
126751     );
126752     if( zSql ){
126753       rc = sqlite3_prepare_v2(p->db, zSql, -1, &pCsr->pStmt, 0);
126754       sqlite3_free(zSql);
126755     }else{
126756       rc = SQLITE_NOMEM;
126757     }
126758   }else if( eSearch==FTS3_DOCID_SEARCH ){
126759     rc = fts3CursorSeekStmt(pCsr, &pCsr->pStmt);
126760     if( rc==SQLITE_OK ){
126761       rc = sqlite3_bind_value(pCsr->pStmt, 1, pCons);
126762     }
126763   }
126764   if( rc!=SQLITE_OK ) return rc;
126765 
126766   return fts3NextMethod(pCursor);
126767 }
126768 
126769 /* 
126770 ** This is the xEof method of the virtual table. SQLite calls this 
126771 ** routine to find out if it has reached the end of a result set.
126772 */
126773 static int fts3EofMethod(sqlite3_vtab_cursor *pCursor){
126774   return ((Fts3Cursor *)pCursor)->isEof;
126775 }
126776 
126777 /* 
126778 ** This is the xRowid method. The SQLite core calls this routine to
126779 ** retrieve the rowid for the current row of the result set. fts3
126780 ** exposes %_content.docid as the rowid for the virtual table. The
126781 ** rowid should be written to *pRowid.
126782 */
126783 static int fts3RowidMethod(sqlite3_vtab_cursor *pCursor, sqlite_int64 *pRowid){
126784   Fts3Cursor *pCsr = (Fts3Cursor *) pCursor;
126785   *pRowid = pCsr->iPrevId;
126786   return SQLITE_OK;
126787 }
126788 
126789 /* 
126790 ** This is the xColumn method, called by SQLite to request a value from
126791 ** the row that the supplied cursor currently points to.
126792 **
126793 ** If:
126794 **
126795 **   (iCol <  p->nColumn)   -> The value of the iCol'th user column.
126796 **   (iCol == p->nColumn)   -> Magic column with the same name as the table.
126797 **   (iCol == p->nColumn+1) -> Docid column
126798 **   (iCol == p->nColumn+2) -> Langid column
126799 */
126800 static int fts3ColumnMethod(
126801   sqlite3_vtab_cursor *pCursor,   /* Cursor to retrieve value from */
126802   sqlite3_context *pCtx,          /* Context for sqlite3_result_xxx() calls */
126803   int iCol                        /* Index of column to read value from */
126804 ){
126805   int rc = SQLITE_OK;             /* Return Code */
126806   Fts3Cursor *pCsr = (Fts3Cursor *) pCursor;
126807   Fts3Table *p = (Fts3Table *)pCursor->pVtab;
126808 
126809   /* The column value supplied by SQLite must be in range. */
126810   assert( iCol>=0 && iCol<=p->nColumn+2 );
126811 
126812   if( iCol==p->nColumn+1 ){
126813     /* This call is a request for the "docid" column. Since "docid" is an 
126814     ** alias for "rowid", use the xRowid() method to obtain the value.
126815     */
126816     sqlite3_result_int64(pCtx, pCsr->iPrevId);
126817   }else if( iCol==p->nColumn ){
126818     /* The extra column whose name is the same as the table.
126819     ** Return a blob which is a pointer to the cursor.  */
126820     sqlite3_result_blob(pCtx, &pCsr, sizeof(pCsr), SQLITE_TRANSIENT);
126821   }else if( iCol==p->nColumn+2 && pCsr->pExpr ){
126822     sqlite3_result_int64(pCtx, pCsr->iLangid);
126823   }else{
126824     /* The requested column is either a user column (one that contains 
126825     ** indexed data), or the language-id column.  */
126826     rc = fts3CursorSeek(0, pCsr);
126827 
126828     if( rc==SQLITE_OK ){
126829       if( iCol==p->nColumn+2 ){
126830         int iLangid = 0;
126831         if( p->zLanguageid ){
126832           iLangid = sqlite3_column_int(pCsr->pStmt, p->nColumn+1);
126833         }
126834         sqlite3_result_int(pCtx, iLangid);
126835       }else if( sqlite3_data_count(pCsr->pStmt)>(iCol+1) ){
126836         sqlite3_result_value(pCtx, sqlite3_column_value(pCsr->pStmt, iCol+1));
126837       }
126838     }
126839   }
126840 
126841   assert( ((Fts3Table *)pCsr->base.pVtab)->pSegments==0 );
126842   return rc;
126843 }
126844 
126845 /* 
126846 ** This function is the implementation of the xUpdate callback used by 
126847 ** FTS3 virtual tables. It is invoked by SQLite each time a row is to be
126848 ** inserted, updated or deleted.
126849 */
126850 static int fts3UpdateMethod(
126851   sqlite3_vtab *pVtab,            /* Virtual table handle */
126852   int nArg,                       /* Size of argument array */
126853   sqlite3_value **apVal,          /* Array of arguments */
126854   sqlite_int64 *pRowid            /* OUT: The affected (or effected) rowid */
126855 ){
126856   return sqlite3Fts3UpdateMethod(pVtab, nArg, apVal, pRowid);
126857 }
126858 
126859 /*
126860 ** Implementation of xSync() method. Flush the contents of the pending-terms
126861 ** hash-table to the database.
126862 */
126863 static int fts3SyncMethod(sqlite3_vtab *pVtab){
126864 
126865   /* Following an incremental-merge operation, assuming that the input
126866   ** segments are not completely consumed (the usual case), they are updated
126867   ** in place to remove the entries that have already been merged. This
126868   ** involves updating the leaf block that contains the smallest unmerged
126869   ** entry and each block (if any) between the leaf and the root node. So
126870   ** if the height of the input segment b-trees is N, and input segments
126871   ** are merged eight at a time, updating the input segments at the end
126872   ** of an incremental-merge requires writing (8*(1+N)) blocks. N is usually
126873   ** small - often between 0 and 2. So the overhead of the incremental
126874   ** merge is somewhere between 8 and 24 blocks. To avoid this overhead
126875   ** dwarfing the actual productive work accomplished, the incremental merge
126876   ** is only attempted if it will write at least 64 leaf blocks. Hence
126877   ** nMinMerge.
126878   **
126879   ** Of course, updating the input segments also involves deleting a bunch
126880   ** of blocks from the segments table. But this is not considered overhead
126881   ** as it would also be required by a crisis-merge that used the same input 
126882   ** segments.
126883   */
126884   const u32 nMinMerge = 64;       /* Minimum amount of incr-merge work to do */
126885 
126886   Fts3Table *p = (Fts3Table*)pVtab;
126887   int rc = sqlite3Fts3PendingTermsFlush(p);
126888 
126889   if( rc==SQLITE_OK && p->bAutoincrmerge==1 && p->nLeafAdd>(nMinMerge/16) ){
126890     int mxLevel = 0;              /* Maximum relative level value in db */
126891     int A;                        /* Incr-merge parameter A */
126892 
126893     rc = sqlite3Fts3MaxLevel(p, &mxLevel);
126894     assert( rc==SQLITE_OK || mxLevel==0 );
126895     A = p->nLeafAdd * mxLevel;
126896     A += (A/2);
126897     if( A>(int)nMinMerge ) rc = sqlite3Fts3Incrmerge(p, A, 8);
126898   }
126899   sqlite3Fts3SegmentsClose(p);
126900   return rc;
126901 }
126902 
126903 /*
126904 ** Implementation of xBegin() method. This is a no-op.
126905 */
126906 static int fts3BeginMethod(sqlite3_vtab *pVtab){
126907   Fts3Table *p = (Fts3Table*)pVtab;
126908   UNUSED_PARAMETER(pVtab);
126909   assert( p->pSegments==0 );
126910   assert( p->nPendingData==0 );
126911   assert( p->inTransaction!=1 );
126912   TESTONLY( p->inTransaction = 1 );
126913   TESTONLY( p->mxSavepoint = -1; );
126914   p->nLeafAdd = 0;
126915   return SQLITE_OK;
126916 }
126917 
126918 /*
126919 ** Implementation of xCommit() method. This is a no-op. The contents of
126920 ** the pending-terms hash-table have already been flushed into the database
126921 ** by fts3SyncMethod().
126922 */
126923 static int fts3CommitMethod(sqlite3_vtab *pVtab){
126924   TESTONLY( Fts3Table *p = (Fts3Table*)pVtab );
126925   UNUSED_PARAMETER(pVtab);
126926   assert( p->nPendingData==0 );
126927   assert( p->inTransaction!=0 );
126928   assert( p->pSegments==0 );
126929   TESTONLY( p->inTransaction = 0 );
126930   TESTONLY( p->mxSavepoint = -1; );
126931   return SQLITE_OK;
126932 }
126933 
126934 /*
126935 ** Implementation of xRollback(). Discard the contents of the pending-terms
126936 ** hash-table. Any changes made to the database are reverted by SQLite.
126937 */
126938 static int fts3RollbackMethod(sqlite3_vtab *pVtab){
126939   Fts3Table *p = (Fts3Table*)pVtab;
126940   sqlite3Fts3PendingTermsClear(p);
126941   assert( p->inTransaction!=0 );
126942   TESTONLY( p->inTransaction = 0 );
126943   TESTONLY( p->mxSavepoint = -1; );
126944   return SQLITE_OK;
126945 }
126946 
126947 /*
126948 ** When called, *ppPoslist must point to the byte immediately following the
126949 ** end of a position-list. i.e. ( (*ppPoslist)[-1]==POS_END ). This function
126950 ** moves *ppPoslist so that it instead points to the first byte of the
126951 ** same position list.
126952 */
126953 static void fts3ReversePoslist(char *pStart, char **ppPoslist){
126954   char *p = &(*ppPoslist)[-2];
126955   char c = 0;
126956 
126957   while( p>pStart && (c=*p--)==0 );
126958   while( p>pStart && (*p & 0x80) | c ){ 
126959     c = *p--; 
126960   }
126961   if( p>pStart ){ p = &p[2]; }
126962   while( *p++&0x80 );
126963   *ppPoslist = p;
126964 }
126965 
126966 /*
126967 ** Helper function used by the implementation of the overloaded snippet(),
126968 ** offsets() and optimize() SQL functions.
126969 **
126970 ** If the value passed as the third argument is a blob of size
126971 ** sizeof(Fts3Cursor*), then the blob contents are copied to the 
126972 ** output variable *ppCsr and SQLITE_OK is returned. Otherwise, an error
126973 ** message is written to context pContext and SQLITE_ERROR returned. The
126974 ** string passed via zFunc is used as part of the error message.
126975 */
126976 static int fts3FunctionArg(
126977   sqlite3_context *pContext,      /* SQL function call context */
126978   const char *zFunc,              /* Function name */
126979   sqlite3_value *pVal,            /* argv[0] passed to function */
126980   Fts3Cursor **ppCsr              /* OUT: Store cursor handle here */
126981 ){
126982   Fts3Cursor *pRet;
126983   if( sqlite3_value_type(pVal)!=SQLITE_BLOB 
126984    || sqlite3_value_bytes(pVal)!=sizeof(Fts3Cursor *)
126985   ){
126986     char *zErr = sqlite3_mprintf("illegal first argument to %s", zFunc);
126987     sqlite3_result_error(pContext, zErr, -1);
126988     sqlite3_free(zErr);
126989     return SQLITE_ERROR;
126990   }
126991   memcpy(&pRet, sqlite3_value_blob(pVal), sizeof(Fts3Cursor *));
126992   *ppCsr = pRet;
126993   return SQLITE_OK;
126994 }
126995 
126996 /*
126997 ** Implementation of the snippet() function for FTS3
126998 */
126999 static void fts3SnippetFunc(
127000   sqlite3_context *pContext,      /* SQLite function call context */
127001   int nVal,                       /* Size of apVal[] array */
127002   sqlite3_value **apVal           /* Array of arguments */
127003 ){
127004   Fts3Cursor *pCsr;               /* Cursor handle passed through apVal[0] */
127005   const char *zStart = "<b>";
127006   const char *zEnd = "</b>";
127007   const char *zEllipsis = "<b>...</b>";
127008   int iCol = -1;
127009   int nToken = 15;                /* Default number of tokens in snippet */
127010 
127011   /* There must be at least one argument passed to this function (otherwise
127012   ** the non-overloaded version would have been called instead of this one).
127013   */
127014   assert( nVal>=1 );
127015 
127016   if( nVal>6 ){
127017     sqlite3_result_error(pContext, 
127018         "wrong number of arguments to function snippet()", -1);
127019     return;
127020   }
127021   if( fts3FunctionArg(pContext, "snippet", apVal[0], &pCsr) ) return;
127022 
127023   switch( nVal ){
127024     case 6: nToken = sqlite3_value_int(apVal[5]);
127025     case 5: iCol = sqlite3_value_int(apVal[4]);
127026     case 4: zEllipsis = (const char*)sqlite3_value_text(apVal[3]);
127027     case 3: zEnd = (const char*)sqlite3_value_text(apVal[2]);
127028     case 2: zStart = (const char*)sqlite3_value_text(apVal[1]);
127029   }
127030   if( !zEllipsis || !zEnd || !zStart ){
127031     sqlite3_result_error_nomem(pContext);
127032   }else if( SQLITE_OK==fts3CursorSeek(pContext, pCsr) ){
127033     sqlite3Fts3Snippet(pContext, pCsr, zStart, zEnd, zEllipsis, iCol, nToken);
127034   }
127035 }
127036 
127037 /*
127038 ** Implementation of the offsets() function for FTS3
127039 */
127040 static void fts3OffsetsFunc(
127041   sqlite3_context *pContext,      /* SQLite function call context */
127042   int nVal,                       /* Size of argument array */
127043   sqlite3_value **apVal           /* Array of arguments */
127044 ){
127045   Fts3Cursor *pCsr;               /* Cursor handle passed through apVal[0] */
127046 
127047   UNUSED_PARAMETER(nVal);
127048 
127049   assert( nVal==1 );
127050   if( fts3FunctionArg(pContext, "offsets", apVal[0], &pCsr) ) return;
127051   assert( pCsr );
127052   if( SQLITE_OK==fts3CursorSeek(pContext, pCsr) ){
127053     sqlite3Fts3Offsets(pContext, pCsr);
127054   }
127055 }
127056 
127057 /* 
127058 ** Implementation of the special optimize() function for FTS3. This 
127059 ** function merges all segments in the database to a single segment.
127060 ** Example usage is:
127061 **
127062 **   SELECT optimize(t) FROM t LIMIT 1;
127063 **
127064 ** where 't' is the name of an FTS3 table.
127065 */
127066 static void fts3OptimizeFunc(
127067   sqlite3_context *pContext,      /* SQLite function call context */
127068   int nVal,                       /* Size of argument array */
127069   sqlite3_value **apVal           /* Array of arguments */
127070 ){
127071   int rc;                         /* Return code */
127072   Fts3Table *p;                   /* Virtual table handle */
127073   Fts3Cursor *pCursor;            /* Cursor handle passed through apVal[0] */
127074 
127075   UNUSED_PARAMETER(nVal);
127076 
127077   assert( nVal==1 );
127078   if( fts3FunctionArg(pContext, "optimize", apVal[0], &pCursor) ) return;
127079   p = (Fts3Table *)pCursor->base.pVtab;
127080   assert( p );
127081 
127082   rc = sqlite3Fts3Optimize(p);
127083 
127084   switch( rc ){
127085     case SQLITE_OK:
127086       sqlite3_result_text(pContext, "Index optimized", -1, SQLITE_STATIC);
127087       break;
127088     case SQLITE_DONE:
127089       sqlite3_result_text(pContext, "Index already optimal", -1, SQLITE_STATIC);
127090       break;
127091     default:
127092       sqlite3_result_error_code(pContext, rc);
127093       break;
127094   }
127095 }
127096 
127097 /*
127098 ** Implementation of the matchinfo() function for FTS3
127099 */
127100 static void fts3MatchinfoFunc(
127101   sqlite3_context *pContext,      /* SQLite function call context */
127102   int nVal,                       /* Size of argument array */
127103   sqlite3_value **apVal           /* Array of arguments */
127104 ){
127105   Fts3Cursor *pCsr;               /* Cursor handle passed through apVal[0] */
127106   assert( nVal==1 || nVal==2 );
127107   if( SQLITE_OK==fts3FunctionArg(pContext, "matchinfo", apVal[0], &pCsr) ){
127108     const char *zArg = 0;
127109     if( nVal>1 ){
127110       zArg = (const char *)sqlite3_value_text(apVal[1]);
127111     }
127112     sqlite3Fts3Matchinfo(pContext, pCsr, zArg);
127113   }
127114 }
127115 
127116 /*
127117 ** This routine implements the xFindFunction method for the FTS3
127118 ** virtual table.
127119 */
127120 static int fts3FindFunctionMethod(
127121   sqlite3_vtab *pVtab,            /* Virtual table handle */
127122   int nArg,                       /* Number of SQL function arguments */
127123   const char *zName,              /* Name of SQL function */
127124   void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), /* OUT: Result */
127125   void **ppArg                    /* Unused */
127126 ){
127127   struct Overloaded {
127128     const char *zName;
127129     void (*xFunc)(sqlite3_context*,int,sqlite3_value**);
127130   } aOverload[] = {
127131     { "snippet", fts3SnippetFunc },
127132     { "offsets", fts3OffsetsFunc },
127133     { "optimize", fts3OptimizeFunc },
127134     { "matchinfo", fts3MatchinfoFunc },
127135   };
127136   int i;                          /* Iterator variable */
127137 
127138   UNUSED_PARAMETER(pVtab);
127139   UNUSED_PARAMETER(nArg);
127140   UNUSED_PARAMETER(ppArg);
127141 
127142   for(i=0; i<SizeofArray(aOverload); i++){
127143     if( strcmp(zName, aOverload[i].zName)==0 ){
127144       *pxFunc = aOverload[i].xFunc;
127145       return 1;
127146     }
127147   }
127148 
127149   /* No function of the specified name was found. Return 0. */
127150   return 0;
127151 }
127152 
127153 /*
127154 ** Implementation of FTS3 xRename method. Rename an fts3 table.
127155 */
127156 static int fts3RenameMethod(
127157   sqlite3_vtab *pVtab,            /* Virtual table handle */
127158   const char *zName               /* New name of table */
127159 ){
127160   Fts3Table *p = (Fts3Table *)pVtab;
127161   sqlite3 *db = p->db;            /* Database connection */
127162   int rc;                         /* Return Code */
127163 
127164   /* As it happens, the pending terms table is always empty here. This is
127165   ** because an "ALTER TABLE RENAME TABLE" statement inside a transaction 
127166   ** always opens a savepoint transaction. And the xSavepoint() method 
127167   ** flushes the pending terms table. But leave the (no-op) call to
127168   ** PendingTermsFlush() in in case that changes.
127169   */
127170   assert( p->nPendingData==0 );
127171   rc = sqlite3Fts3PendingTermsFlush(p);
127172 
127173   if( p->zContentTbl==0 ){
127174     fts3DbExec(&rc, db,
127175       "ALTER TABLE %Q.'%q_content'  RENAME TO '%q_content';",
127176       p->zDb, p->zName, zName
127177     );
127178   }
127179 
127180   if( p->bHasDocsize ){
127181     fts3DbExec(&rc, db,
127182       "ALTER TABLE %Q.'%q_docsize'  RENAME TO '%q_docsize';",
127183       p->zDb, p->zName, zName
127184     );
127185   }
127186   if( p->bHasStat ){
127187     fts3DbExec(&rc, db,
127188       "ALTER TABLE %Q.'%q_stat'  RENAME TO '%q_stat';",
127189       p->zDb, p->zName, zName
127190     );
127191   }
127192   fts3DbExec(&rc, db,
127193     "ALTER TABLE %Q.'%q_segments' RENAME TO '%q_segments';",
127194     p->zDb, p->zName, zName
127195   );
127196   fts3DbExec(&rc, db,
127197     "ALTER TABLE %Q.'%q_segdir'   RENAME TO '%q_segdir';",
127198     p->zDb, p->zName, zName
127199   );
127200   return rc;
127201 }
127202 
127203 /*
127204 ** The xSavepoint() method.
127205 **
127206 ** Flush the contents of the pending-terms table to disk.
127207 */
127208 static int fts3SavepointMethod(sqlite3_vtab *pVtab, int iSavepoint){
127209   int rc = SQLITE_OK;
127210   UNUSED_PARAMETER(iSavepoint);
127211   assert( ((Fts3Table *)pVtab)->inTransaction );
127212   assert( ((Fts3Table *)pVtab)->mxSavepoint < iSavepoint );
127213   TESTONLY( ((Fts3Table *)pVtab)->mxSavepoint = iSavepoint );
127214   if( ((Fts3Table *)pVtab)->bIgnoreSavepoint==0 ){
127215     rc = fts3SyncMethod(pVtab);
127216   }
127217   return rc;
127218 }
127219 
127220 /*
127221 ** The xRelease() method.
127222 **
127223 ** This is a no-op.
127224 */
127225 static int fts3ReleaseMethod(sqlite3_vtab *pVtab, int iSavepoint){
127226   TESTONLY( Fts3Table *p = (Fts3Table*)pVtab );
127227   UNUSED_PARAMETER(iSavepoint);
127228   UNUSED_PARAMETER(pVtab);
127229   assert( p->inTransaction );
127230   assert( p->mxSavepoint >= iSavepoint );
127231   TESTONLY( p->mxSavepoint = iSavepoint-1 );
127232   return SQLITE_OK;
127233 }
127234 
127235 /*
127236 ** The xRollbackTo() method.
127237 **
127238 ** Discard the contents of the pending terms table.
127239 */
127240 static int fts3RollbackToMethod(sqlite3_vtab *pVtab, int iSavepoint){
127241   Fts3Table *p = (Fts3Table*)pVtab;
127242   UNUSED_PARAMETER(iSavepoint);
127243   assert( p->inTransaction );
127244   assert( p->mxSavepoint >= iSavepoint );
127245   TESTONLY( p->mxSavepoint = iSavepoint );
127246   sqlite3Fts3PendingTermsClear(p);
127247   return SQLITE_OK;
127248 }
127249 
127250 static const sqlite3_module fts3Module = {
127251   /* iVersion      */ 2,
127252   /* xCreate       */ fts3CreateMethod,
127253   /* xConnect      */ fts3ConnectMethod,
127254   /* xBestIndex    */ fts3BestIndexMethod,
127255   /* xDisconnect   */ fts3DisconnectMethod,
127256   /* xDestroy      */ fts3DestroyMethod,
127257   /* xOpen         */ fts3OpenMethod,
127258   /* xClose        */ fts3CloseMethod,
127259   /* xFilter       */ fts3FilterMethod,
127260   /* xNext         */ fts3NextMethod,
127261   /* xEof          */ fts3EofMethod,
127262   /* xColumn       */ fts3ColumnMethod,
127263   /* xRowid        */ fts3RowidMethod,
127264   /* xUpdate       */ fts3UpdateMethod,
127265   /* xBegin        */ fts3BeginMethod,
127266   /* xSync         */ fts3SyncMethod,
127267   /* xCommit       */ fts3CommitMethod,
127268   /* xRollback     */ fts3RollbackMethod,
127269   /* xFindFunction */ fts3FindFunctionMethod,
127270   /* xRename */       fts3RenameMethod,
127271   /* xSavepoint    */ fts3SavepointMethod,
127272   /* xRelease      */ fts3ReleaseMethod,
127273   /* xRollbackTo   */ fts3RollbackToMethod,
127274 };
127275 
127276 /*
127277 ** This function is registered as the module destructor (called when an
127278 ** FTS3 enabled database connection is closed). It frees the memory
127279 ** allocated for the tokenizer hash table.
127280 */
127281 static void hashDestroy(void *p){
127282   Fts3Hash *pHash = (Fts3Hash *)p;
127283   sqlite3Fts3HashClear(pHash);
127284   sqlite3_free(pHash);
127285 }
127286 
127287 /*
127288 ** The fts3 built-in tokenizers - "simple", "porter" and "icu"- are 
127289 ** implemented in files fts3_tokenizer1.c, fts3_porter.c and fts3_icu.c
127290 ** respectively. The following three forward declarations are for functions
127291 ** declared in these files used to retrieve the respective implementations.
127292 **
127293 ** Calling sqlite3Fts3SimpleTokenizerModule() sets the value pointed
127294 ** to by the argument to point to the "simple" tokenizer implementation.
127295 ** And so on.
127296 */
127297 SQLITE_PRIVATE void sqlite3Fts3SimpleTokenizerModule(sqlite3_tokenizer_module const**ppModule);
127298 SQLITE_PRIVATE void sqlite3Fts3PorterTokenizerModule(sqlite3_tokenizer_module const**ppModule);
127299 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
127300 SQLITE_PRIVATE void sqlite3Fts3UnicodeTokenizer(sqlite3_tokenizer_module const**ppModule);
127301 #endif
127302 #ifdef SQLITE_ENABLE_ICU
127303 SQLITE_PRIVATE void sqlite3Fts3IcuTokenizerModule(sqlite3_tokenizer_module const**ppModule);
127304 #endif
127305 
127306 /*
127307 ** Initialize the fts3 extension. If this extension is built as part
127308 ** of the sqlite library, then this function is called directly by
127309 ** SQLite. If fts3 is built as a dynamically loadable extension, this
127310 ** function is called by the sqlite3_extension_init() entry point.
127311 */
127312 SQLITE_PRIVATE int sqlite3Fts3Init(sqlite3 *db){
127313   int rc = SQLITE_OK;
127314   Fts3Hash *pHash = 0;
127315   const sqlite3_tokenizer_module *pSimple = 0;
127316   const sqlite3_tokenizer_module *pPorter = 0;
127317 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
127318   const sqlite3_tokenizer_module *pUnicode = 0;
127319 #endif
127320 
127321 #ifdef SQLITE_ENABLE_ICU
127322   const sqlite3_tokenizer_module *pIcu = 0;
127323   sqlite3Fts3IcuTokenizerModule(&pIcu);
127324 #endif
127325 
127326 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
127327   sqlite3Fts3UnicodeTokenizer(&pUnicode);
127328 #endif
127329 
127330 #ifdef SQLITE_TEST
127331   rc = sqlite3Fts3InitTerm(db);
127332   if( rc!=SQLITE_OK ) return rc;
127333 #endif
127334 
127335   rc = sqlite3Fts3InitAux(db);
127336   if( rc!=SQLITE_OK ) return rc;
127337 
127338   sqlite3Fts3SimpleTokenizerModule(&pSimple);
127339   sqlite3Fts3PorterTokenizerModule(&pPorter);
127340 
127341   /* Allocate and initialize the hash-table used to store tokenizers. */
127342   pHash = sqlite3_malloc(sizeof(Fts3Hash));
127343   if( !pHash ){
127344     rc = SQLITE_NOMEM;
127345   }else{
127346     sqlite3Fts3HashInit(pHash, FTS3_HASH_STRING, 1);
127347   }
127348 
127349   /* Load the built-in tokenizers into the hash table */
127350   if( rc==SQLITE_OK ){
127351     if( sqlite3Fts3HashInsert(pHash, "simple", 7, (void *)pSimple)
127352      || sqlite3Fts3HashInsert(pHash, "porter", 7, (void *)pPorter) 
127353 
127354 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
127355      || sqlite3Fts3HashInsert(pHash, "unicode61", 10, (void *)pUnicode) 
127356 #endif
127357 #ifdef SQLITE_ENABLE_ICU
127358      || (pIcu && sqlite3Fts3HashInsert(pHash, "icu", 4, (void *)pIcu))
127359 #endif
127360     ){
127361       rc = SQLITE_NOMEM;
127362     }
127363   }
127364 
127365 #ifdef SQLITE_TEST
127366   if( rc==SQLITE_OK ){
127367     rc = sqlite3Fts3ExprInitTestInterface(db);
127368   }
127369 #endif
127370 
127371   /* Create the virtual table wrapper around the hash-table and overload 
127372   ** the two scalar functions. If this is successful, register the
127373   ** module with sqlite.
127374   */
127375   if( SQLITE_OK==rc 
127376    && SQLITE_OK==(rc = sqlite3Fts3InitHashTable(db, pHash, "fts3_tokenizer"))
127377    && SQLITE_OK==(rc = sqlite3_overload_function(db, "snippet", -1))
127378    && SQLITE_OK==(rc = sqlite3_overload_function(db, "offsets", 1))
127379    && SQLITE_OK==(rc = sqlite3_overload_function(db, "matchinfo", 1))
127380    && SQLITE_OK==(rc = sqlite3_overload_function(db, "matchinfo", 2))
127381    && SQLITE_OK==(rc = sqlite3_overload_function(db, "optimize", 1))
127382   ){
127383     rc = sqlite3_create_module_v2(
127384         db, "fts3", &fts3Module, (void *)pHash, hashDestroy
127385     );
127386     if( rc==SQLITE_OK ){
127387       rc = sqlite3_create_module_v2(
127388           db, "fts4", &fts3Module, (void *)pHash, 0
127389       );
127390     }
127391     if( rc==SQLITE_OK ){
127392       rc = sqlite3Fts3InitTok(db, (void *)pHash);
127393     }
127394     return rc;
127395   }
127396 
127397 
127398   /* An error has occurred. Delete the hash table and return the error code. */
127399   assert( rc!=SQLITE_OK );
127400   if( pHash ){
127401     sqlite3Fts3HashClear(pHash);
127402     sqlite3_free(pHash);
127403   }
127404   return rc;
127405 }
127406 
127407 /*
127408 ** Allocate an Fts3MultiSegReader for each token in the expression headed
127409 ** by pExpr. 
127410 **
127411 ** An Fts3SegReader object is a cursor that can seek or scan a range of
127412 ** entries within a single segment b-tree. An Fts3MultiSegReader uses multiple
127413 ** Fts3SegReader objects internally to provide an interface to seek or scan
127414 ** within the union of all segments of a b-tree. Hence the name.
127415 **
127416 ** If the allocated Fts3MultiSegReader just seeks to a single entry in a
127417 ** segment b-tree (if the term is not a prefix or it is a prefix for which
127418 ** there exists prefix b-tree of the right length) then it may be traversed
127419 ** and merged incrementally. Otherwise, it has to be merged into an in-memory 
127420 ** doclist and then traversed.
127421 */
127422 static void fts3EvalAllocateReaders(
127423   Fts3Cursor *pCsr,               /* FTS cursor handle */
127424   Fts3Expr *pExpr,                /* Allocate readers for this expression */
127425   int *pnToken,                   /* OUT: Total number of tokens in phrase. */
127426   int *pnOr,                      /* OUT: Total number of OR nodes in expr. */
127427   int *pRc                        /* IN/OUT: Error code */
127428 ){
127429   if( pExpr && SQLITE_OK==*pRc ){
127430     if( pExpr->eType==FTSQUERY_PHRASE ){
127431       int i;
127432       int nToken = pExpr->pPhrase->nToken;
127433       *pnToken += nToken;
127434       for(i=0; i<nToken; i++){
127435         Fts3PhraseToken *pToken = &pExpr->pPhrase->aToken[i];
127436         int rc = fts3TermSegReaderCursor(pCsr, 
127437             pToken->z, pToken->n, pToken->isPrefix, &pToken->pSegcsr
127438         );
127439         if( rc!=SQLITE_OK ){
127440           *pRc = rc;
127441           return;
127442         }
127443       }
127444       assert( pExpr->pPhrase->iDoclistToken==0 );
127445       pExpr->pPhrase->iDoclistToken = -1;
127446     }else{
127447       *pnOr += (pExpr->eType==FTSQUERY_OR);
127448       fts3EvalAllocateReaders(pCsr, pExpr->pLeft, pnToken, pnOr, pRc);
127449       fts3EvalAllocateReaders(pCsr, pExpr->pRight, pnToken, pnOr, pRc);
127450     }
127451   }
127452 }
127453 
127454 /*
127455 ** Arguments pList/nList contain the doclist for token iToken of phrase p.
127456 ** It is merged into the main doclist stored in p->doclist.aAll/nAll.
127457 **
127458 ** This function assumes that pList points to a buffer allocated using
127459 ** sqlite3_malloc(). This function takes responsibility for eventually
127460 ** freeing the buffer.
127461 */
127462 static void fts3EvalPhraseMergeToken(
127463   Fts3Table *pTab,                /* FTS Table pointer */
127464   Fts3Phrase *p,                  /* Phrase to merge pList/nList into */
127465   int iToken,                     /* Token pList/nList corresponds to */
127466   char *pList,                    /* Pointer to doclist */
127467   int nList                       /* Number of bytes in pList */
127468 ){
127469   assert( iToken!=p->iDoclistToken );
127470 
127471   if( pList==0 ){
127472     sqlite3_free(p->doclist.aAll);
127473     p->doclist.aAll = 0;
127474     p->doclist.nAll = 0;
127475   }
127476 
127477   else if( p->iDoclistToken<0 ){
127478     p->doclist.aAll = pList;
127479     p->doclist.nAll = nList;
127480   }
127481 
127482   else if( p->doclist.aAll==0 ){
127483     sqlite3_free(pList);
127484   }
127485 
127486   else {
127487     char *pLeft;
127488     char *pRight;
127489     int nLeft;
127490     int nRight;
127491     int nDiff;
127492 
127493     if( p->iDoclistToken<iToken ){
127494       pLeft = p->doclist.aAll;
127495       nLeft = p->doclist.nAll;
127496       pRight = pList;
127497       nRight = nList;
127498       nDiff = iToken - p->iDoclistToken;
127499     }else{
127500       pRight = p->doclist.aAll;
127501       nRight = p->doclist.nAll;
127502       pLeft = pList;
127503       nLeft = nList;
127504       nDiff = p->iDoclistToken - iToken;
127505     }
127506 
127507     fts3DoclistPhraseMerge(pTab->bDescIdx, nDiff, pLeft, nLeft, pRight,&nRight);
127508     sqlite3_free(pLeft);
127509     p->doclist.aAll = pRight;
127510     p->doclist.nAll = nRight;
127511   }
127512 
127513   if( iToken>p->iDoclistToken ) p->iDoclistToken = iToken;
127514 }
127515 
127516 /*
127517 ** Load the doclist for phrase p into p->doclist.aAll/nAll. The loaded doclist
127518 ** does not take deferred tokens into account.
127519 **
127520 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
127521 */
127522 static int fts3EvalPhraseLoad(
127523   Fts3Cursor *pCsr,               /* FTS Cursor handle */
127524   Fts3Phrase *p                   /* Phrase object */
127525 ){
127526   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
127527   int iToken;
127528   int rc = SQLITE_OK;
127529 
127530   for(iToken=0; rc==SQLITE_OK && iToken<p->nToken; iToken++){
127531     Fts3PhraseToken *pToken = &p->aToken[iToken];
127532     assert( pToken->pDeferred==0 || pToken->pSegcsr==0 );
127533 
127534     if( pToken->pSegcsr ){
127535       int nThis = 0;
127536       char *pThis = 0;
127537       rc = fts3TermSelect(pTab, pToken, p->iColumn, &nThis, &pThis);
127538       if( rc==SQLITE_OK ){
127539         fts3EvalPhraseMergeToken(pTab, p, iToken, pThis, nThis);
127540       }
127541     }
127542     assert( pToken->pSegcsr==0 );
127543   }
127544 
127545   return rc;
127546 }
127547 
127548 /*
127549 ** This function is called on each phrase after the position lists for
127550 ** any deferred tokens have been loaded into memory. It updates the phrases
127551 ** current position list to include only those positions that are really
127552 ** instances of the phrase (after considering deferred tokens). If this
127553 ** means that the phrase does not appear in the current row, doclist.pList
127554 ** and doclist.nList are both zeroed.
127555 **
127556 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
127557 */
127558 static int fts3EvalDeferredPhrase(Fts3Cursor *pCsr, Fts3Phrase *pPhrase){
127559   int iToken;                     /* Used to iterate through phrase tokens */
127560   char *aPoslist = 0;             /* Position list for deferred tokens */
127561   int nPoslist = 0;               /* Number of bytes in aPoslist */
127562   int iPrev = -1;                 /* Token number of previous deferred token */
127563 
127564   assert( pPhrase->doclist.bFreeList==0 );
127565 
127566   for(iToken=0; iToken<pPhrase->nToken; iToken++){
127567     Fts3PhraseToken *pToken = &pPhrase->aToken[iToken];
127568     Fts3DeferredToken *pDeferred = pToken->pDeferred;
127569 
127570     if( pDeferred ){
127571       char *pList;
127572       int nList;
127573       int rc = sqlite3Fts3DeferredTokenList(pDeferred, &pList, &nList);
127574       if( rc!=SQLITE_OK ) return rc;
127575 
127576       if( pList==0 ){
127577         sqlite3_free(aPoslist);
127578         pPhrase->doclist.pList = 0;
127579         pPhrase->doclist.nList = 0;
127580         return SQLITE_OK;
127581 
127582       }else if( aPoslist==0 ){
127583         aPoslist = pList;
127584         nPoslist = nList;
127585 
127586       }else{
127587         char *aOut = pList;
127588         char *p1 = aPoslist;
127589         char *p2 = aOut;
127590 
127591         assert( iPrev>=0 );
127592         fts3PoslistPhraseMerge(&aOut, iToken-iPrev, 0, 1, &p1, &p2);
127593         sqlite3_free(aPoslist);
127594         aPoslist = pList;
127595         nPoslist = (int)(aOut - aPoslist);
127596         if( nPoslist==0 ){
127597           sqlite3_free(aPoslist);
127598           pPhrase->doclist.pList = 0;
127599           pPhrase->doclist.nList = 0;
127600           return SQLITE_OK;
127601         }
127602       }
127603       iPrev = iToken;
127604     }
127605   }
127606 
127607   if( iPrev>=0 ){
127608     int nMaxUndeferred = pPhrase->iDoclistToken;
127609     if( nMaxUndeferred<0 ){
127610       pPhrase->doclist.pList = aPoslist;
127611       pPhrase->doclist.nList = nPoslist;
127612       pPhrase->doclist.iDocid = pCsr->iPrevId;
127613       pPhrase->doclist.bFreeList = 1;
127614     }else{
127615       int nDistance;
127616       char *p1;
127617       char *p2;
127618       char *aOut;
127619 
127620       if( nMaxUndeferred>iPrev ){
127621         p1 = aPoslist;
127622         p2 = pPhrase->doclist.pList;
127623         nDistance = nMaxUndeferred - iPrev;
127624       }else{
127625         p1 = pPhrase->doclist.pList;
127626         p2 = aPoslist;
127627         nDistance = iPrev - nMaxUndeferred;
127628       }
127629 
127630       aOut = (char *)sqlite3_malloc(nPoslist+8);
127631       if( !aOut ){
127632         sqlite3_free(aPoslist);
127633         return SQLITE_NOMEM;
127634       }
127635       
127636       pPhrase->doclist.pList = aOut;
127637       if( fts3PoslistPhraseMerge(&aOut, nDistance, 0, 1, &p1, &p2) ){
127638         pPhrase->doclist.bFreeList = 1;
127639         pPhrase->doclist.nList = (int)(aOut - pPhrase->doclist.pList);
127640       }else{
127641         sqlite3_free(aOut);
127642         pPhrase->doclist.pList = 0;
127643         pPhrase->doclist.nList = 0;
127644       }
127645       sqlite3_free(aPoslist);
127646     }
127647   }
127648 
127649   return SQLITE_OK;
127650 }
127651 
127652 /*
127653 ** Maximum number of tokens a phrase may have to be considered for the
127654 ** incremental doclists strategy.
127655 */
127656 #define MAX_INCR_PHRASE_TOKENS 4
127657 
127658 /*
127659 ** This function is called for each Fts3Phrase in a full-text query 
127660 ** expression to initialize the mechanism for returning rows. Once this
127661 ** function has been called successfully on an Fts3Phrase, it may be
127662 ** used with fts3EvalPhraseNext() to iterate through the matching docids.
127663 **
127664 ** If parameter bOptOk is true, then the phrase may (or may not) use the
127665 ** incremental loading strategy. Otherwise, the entire doclist is loaded into
127666 ** memory within this call.
127667 **
127668 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
127669 */
127670 static int fts3EvalPhraseStart(Fts3Cursor *pCsr, int bOptOk, Fts3Phrase *p){
127671   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
127672   int rc = SQLITE_OK;             /* Error code */
127673   int i;
127674 
127675   /* Determine if doclists may be loaded from disk incrementally. This is
127676   ** possible if the bOptOk argument is true, the FTS doclists will be
127677   ** scanned in forward order, and the phrase consists of 
127678   ** MAX_INCR_PHRASE_TOKENS or fewer tokens, none of which are are "^first"
127679   ** tokens or prefix tokens that cannot use a prefix-index.  */
127680   int bHaveIncr = 0;
127681   int bIncrOk = (bOptOk 
127682    && pCsr->bDesc==pTab->bDescIdx 
127683    && p->nToken<=MAX_INCR_PHRASE_TOKENS && p->nToken>0
127684    && p->nToken<=MAX_INCR_PHRASE_TOKENS && p->nToken>0
127685 #ifdef SQLITE_TEST
127686    && pTab->bNoIncrDoclist==0
127687 #endif
127688   );
127689   for(i=0; bIncrOk==1 && i<p->nToken; i++){
127690     Fts3PhraseToken *pToken = &p->aToken[i];
127691     if( pToken->bFirst || (pToken->pSegcsr!=0 && !pToken->pSegcsr->bLookup) ){
127692       bIncrOk = 0;
127693     }
127694     if( pToken->pSegcsr ) bHaveIncr = 1;
127695   }
127696 
127697   if( bIncrOk && bHaveIncr ){
127698     /* Use the incremental approach. */
127699     int iCol = (p->iColumn >= pTab->nColumn ? -1 : p->iColumn);
127700     for(i=0; rc==SQLITE_OK && i<p->nToken; i++){
127701       Fts3PhraseToken *pToken = &p->aToken[i];
127702       Fts3MultiSegReader *pSegcsr = pToken->pSegcsr;
127703       if( pSegcsr ){
127704         rc = sqlite3Fts3MsrIncrStart(pTab, pSegcsr, iCol, pToken->z, pToken->n);
127705       }
127706     }
127707     p->bIncr = 1;
127708   }else{
127709     /* Load the full doclist for the phrase into memory. */
127710     rc = fts3EvalPhraseLoad(pCsr, p);
127711     p->bIncr = 0;
127712   }
127713 
127714   assert( rc!=SQLITE_OK || p->nToken<1 || p->aToken[0].pSegcsr==0 || p->bIncr );
127715   return rc;
127716 }
127717 
127718 /*
127719 ** This function is used to iterate backwards (from the end to start) 
127720 ** through doclists. It is used by this module to iterate through phrase
127721 ** doclists in reverse and by the fts3_write.c module to iterate through
127722 ** pending-terms lists when writing to databases with "order=desc".
127723 **
127724 ** The doclist may be sorted in ascending (parameter bDescIdx==0) or 
127725 ** descending (parameter bDescIdx==1) order of docid. Regardless, this
127726 ** function iterates from the end of the doclist to the beginning.
127727 */
127728 SQLITE_PRIVATE void sqlite3Fts3DoclistPrev(
127729   int bDescIdx,                   /* True if the doclist is desc */
127730   char *aDoclist,                 /* Pointer to entire doclist */
127731   int nDoclist,                   /* Length of aDoclist in bytes */
127732   char **ppIter,                  /* IN/OUT: Iterator pointer */
127733   sqlite3_int64 *piDocid,         /* IN/OUT: Docid pointer */
127734   int *pnList,                    /* OUT: List length pointer */
127735   u8 *pbEof                       /* OUT: End-of-file flag */
127736 ){
127737   char *p = *ppIter;
127738 
127739   assert( nDoclist>0 );
127740   assert( *pbEof==0 );
127741   assert( p || *piDocid==0 );
127742   assert( !p || (p>aDoclist && p<&aDoclist[nDoclist]) );
127743 
127744   if( p==0 ){
127745     sqlite3_int64 iDocid = 0;
127746     char *pNext = 0;
127747     char *pDocid = aDoclist;
127748     char *pEnd = &aDoclist[nDoclist];
127749     int iMul = 1;
127750 
127751     while( pDocid<pEnd ){
127752       sqlite3_int64 iDelta;
127753       pDocid += sqlite3Fts3GetVarint(pDocid, &iDelta);
127754       iDocid += (iMul * iDelta);
127755       pNext = pDocid;
127756       fts3PoslistCopy(0, &pDocid);
127757       while( pDocid<pEnd && *pDocid==0 ) pDocid++;
127758       iMul = (bDescIdx ? -1 : 1);
127759     }
127760 
127761     *pnList = (int)(pEnd - pNext);
127762     *ppIter = pNext;
127763     *piDocid = iDocid;
127764   }else{
127765     int iMul = (bDescIdx ? -1 : 1);
127766     sqlite3_int64 iDelta;
127767     fts3GetReverseVarint(&p, aDoclist, &iDelta);
127768     *piDocid -= (iMul * iDelta);
127769 
127770     if( p==aDoclist ){
127771       *pbEof = 1;
127772     }else{
127773       char *pSave = p;
127774       fts3ReversePoslist(aDoclist, &p);
127775       *pnList = (int)(pSave - p);
127776     }
127777     *ppIter = p;
127778   }
127779 }
127780 
127781 /*
127782 ** Iterate forwards through a doclist.
127783 */
127784 SQLITE_PRIVATE void sqlite3Fts3DoclistNext(
127785   int bDescIdx,                   /* True if the doclist is desc */
127786   char *aDoclist,                 /* Pointer to entire doclist */
127787   int nDoclist,                   /* Length of aDoclist in bytes */
127788   char **ppIter,                  /* IN/OUT: Iterator pointer */
127789   sqlite3_int64 *piDocid,         /* IN/OUT: Docid pointer */
127790   u8 *pbEof                       /* OUT: End-of-file flag */
127791 ){
127792   char *p = *ppIter;
127793 
127794   assert( nDoclist>0 );
127795   assert( *pbEof==0 );
127796   assert( p || *piDocid==0 );
127797   assert( !p || (p>=aDoclist && p<=&aDoclist[nDoclist]) );
127798 
127799   if( p==0 ){
127800     p = aDoclist;
127801     p += sqlite3Fts3GetVarint(p, piDocid);
127802   }else{
127803     fts3PoslistCopy(0, &p);
127804     if( p>=&aDoclist[nDoclist] ){
127805       *pbEof = 1;
127806     }else{
127807       sqlite3_int64 iVar;
127808       p += sqlite3Fts3GetVarint(p, &iVar);
127809       *piDocid += ((bDescIdx ? -1 : 1) * iVar);
127810     }
127811   }
127812 
127813   *ppIter = p;
127814 }
127815 
127816 /*
127817 ** Advance the iterator pDL to the next entry in pDL->aAll/nAll. Set *pbEof
127818 ** to true if EOF is reached.
127819 */
127820 static void fts3EvalDlPhraseNext(
127821   Fts3Table *pTab,
127822   Fts3Doclist *pDL,
127823   u8 *pbEof
127824 ){
127825   char *pIter;                            /* Used to iterate through aAll */
127826   char *pEnd = &pDL->aAll[pDL->nAll];     /* 1 byte past end of aAll */
127827  
127828   if( pDL->pNextDocid ){
127829     pIter = pDL->pNextDocid;
127830   }else{
127831     pIter = pDL->aAll;
127832   }
127833 
127834   if( pIter>=pEnd ){
127835     /* We have already reached the end of this doclist. EOF. */
127836     *pbEof = 1;
127837   }else{
127838     sqlite3_int64 iDelta;
127839     pIter += sqlite3Fts3GetVarint(pIter, &iDelta);
127840     if( pTab->bDescIdx==0 || pDL->pNextDocid==0 ){
127841       pDL->iDocid += iDelta;
127842     }else{
127843       pDL->iDocid -= iDelta;
127844     }
127845     pDL->pList = pIter;
127846     fts3PoslistCopy(0, &pIter);
127847     pDL->nList = (int)(pIter - pDL->pList);
127848 
127849     /* pIter now points just past the 0x00 that terminates the position-
127850     ** list for document pDL->iDocid. However, if this position-list was
127851     ** edited in place by fts3EvalNearTrim(), then pIter may not actually
127852     ** point to the start of the next docid value. The following line deals
127853     ** with this case by advancing pIter past the zero-padding added by
127854     ** fts3EvalNearTrim().  */
127855     while( pIter<pEnd && *pIter==0 ) pIter++;
127856 
127857     pDL->pNextDocid = pIter;
127858     assert( pIter>=&pDL->aAll[pDL->nAll] || *pIter );
127859     *pbEof = 0;
127860   }
127861 }
127862 
127863 /*
127864 ** Helper type used by fts3EvalIncrPhraseNext() and incrPhraseTokenNext().
127865 */
127866 typedef struct TokenDoclist TokenDoclist;
127867 struct TokenDoclist {
127868   int bIgnore;
127869   sqlite3_int64 iDocid;
127870   char *pList;
127871   int nList;
127872 };
127873 
127874 /*
127875 ** Token pToken is an incrementally loaded token that is part of a 
127876 ** multi-token phrase. Advance it to the next matching document in the
127877 ** database and populate output variable *p with the details of the new
127878 ** entry. Or, if the iterator has reached EOF, set *pbEof to true.
127879 **
127880 ** If an error occurs, return an SQLite error code. Otherwise, return 
127881 ** SQLITE_OK.
127882 */
127883 static int incrPhraseTokenNext(
127884   Fts3Table *pTab,                /* Virtual table handle */
127885   Fts3Phrase *pPhrase,            /* Phrase to advance token of */
127886   int iToken,                     /* Specific token to advance */
127887   TokenDoclist *p,                /* OUT: Docid and doclist for new entry */
127888   u8 *pbEof                       /* OUT: True if iterator is at EOF */
127889 ){
127890   int rc = SQLITE_OK;
127891 
127892   if( pPhrase->iDoclistToken==iToken ){
127893     assert( p->bIgnore==0 );
127894     assert( pPhrase->aToken[iToken].pSegcsr==0 );
127895     fts3EvalDlPhraseNext(pTab, &pPhrase->doclist, pbEof);
127896     p->pList = pPhrase->doclist.pList;
127897     p->nList = pPhrase->doclist.nList;
127898     p->iDocid = pPhrase->doclist.iDocid;
127899   }else{
127900     Fts3PhraseToken *pToken = &pPhrase->aToken[iToken];
127901     assert( pToken->pDeferred==0 );
127902     assert( pToken->pSegcsr || pPhrase->iDoclistToken>=0 );
127903     if( pToken->pSegcsr ){
127904       assert( p->bIgnore==0 );
127905       rc = sqlite3Fts3MsrIncrNext(
127906           pTab, pToken->pSegcsr, &p->iDocid, &p->pList, &p->nList
127907       );
127908       if( p->pList==0 ) *pbEof = 1;
127909     }else{
127910       p->bIgnore = 1;
127911     }
127912   }
127913 
127914   return rc;
127915 }
127916 
127917 
127918 /*
127919 ** The phrase iterator passed as the second argument:
127920 **
127921 **   * features at least one token that uses an incremental doclist, and 
127922 **
127923 **   * does not contain any deferred tokens.
127924 **
127925 ** Advance it to the next matching documnent in the database and populate
127926 ** the Fts3Doclist.pList and nList fields. 
127927 **
127928 ** If there is no "next" entry and no error occurs, then *pbEof is set to
127929 ** 1 before returning. Otherwise, if no error occurs and the iterator is
127930 ** successfully advanced, *pbEof is set to 0.
127931 **
127932 ** If an error occurs, return an SQLite error code. Otherwise, return 
127933 ** SQLITE_OK.
127934 */
127935 static int fts3EvalIncrPhraseNext(
127936   Fts3Cursor *pCsr,               /* FTS Cursor handle */
127937   Fts3Phrase *p,                  /* Phrase object to advance to next docid */
127938   u8 *pbEof                       /* OUT: Set to 1 if EOF */
127939 ){
127940   int rc = SQLITE_OK;
127941   Fts3Doclist *pDL = &p->doclist;
127942   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
127943   u8 bEof = 0;
127944 
127945   /* This is only called if it is guaranteed that the phrase has at least
127946   ** one incremental token. In which case the bIncr flag is set. */
127947   assert( p->bIncr==1 );
127948 
127949   if( p->nToken==1 && p->bIncr ){
127950     rc = sqlite3Fts3MsrIncrNext(pTab, p->aToken[0].pSegcsr, 
127951         &pDL->iDocid, &pDL->pList, &pDL->nList
127952     );
127953     if( pDL->pList==0 ) bEof = 1;
127954   }else{
127955     int bDescDoclist = pCsr->bDesc;
127956     struct TokenDoclist a[MAX_INCR_PHRASE_TOKENS];
127957 
127958     memset(a, 0, sizeof(a));
127959     assert( p->nToken<=MAX_INCR_PHRASE_TOKENS );
127960     assert( p->iDoclistToken<MAX_INCR_PHRASE_TOKENS );
127961 
127962     while( bEof==0 ){
127963       int bMaxSet = 0;
127964       sqlite3_int64 iMax = 0;     /* Largest docid for all iterators */
127965       int i;                      /* Used to iterate through tokens */
127966 
127967       /* Advance the iterator for each token in the phrase once. */
127968       for(i=0; rc==SQLITE_OK && i<p->nToken && bEof==0; i++){
127969         rc = incrPhraseTokenNext(pTab, p, i, &a[i], &bEof);
127970         if( a[i].bIgnore==0 && (bMaxSet==0 || DOCID_CMP(iMax, a[i].iDocid)<0) ){
127971           iMax = a[i].iDocid;
127972           bMaxSet = 1;
127973         }
127974       }
127975       assert( rc!=SQLITE_OK || a[p->nToken-1].bIgnore==0 );
127976       assert( rc!=SQLITE_OK || bMaxSet );
127977 
127978       /* Keep advancing iterators until they all point to the same document */
127979       for(i=0; i<p->nToken; i++){
127980         while( rc==SQLITE_OK && bEof==0 
127981             && a[i].bIgnore==0 && DOCID_CMP(a[i].iDocid, iMax)<0 
127982         ){
127983           rc = incrPhraseTokenNext(pTab, p, i, &a[i], &bEof);
127984           if( DOCID_CMP(a[i].iDocid, iMax)>0 ){
127985             iMax = a[i].iDocid;
127986             i = 0;
127987           }
127988         }
127989       }
127990 
127991       /* Check if the current entries really are a phrase match */
127992       if( bEof==0 ){
127993         int nList = 0;
127994         int nByte = a[p->nToken-1].nList;
127995         char *aDoclist = sqlite3_malloc(nByte+1);
127996         if( !aDoclist ) return SQLITE_NOMEM;
127997         memcpy(aDoclist, a[p->nToken-1].pList, nByte+1);
127998 
127999         for(i=0; i<(p->nToken-1); i++){
128000           if( a[i].bIgnore==0 ){
128001             char *pL = a[i].pList;
128002             char *pR = aDoclist;
128003             char *pOut = aDoclist;
128004             int nDist = p->nToken-1-i;
128005             int res = fts3PoslistPhraseMerge(&pOut, nDist, 0, 1, &pL, &pR);
128006             if( res==0 ) break;
128007             nList = (int)(pOut - aDoclist);
128008           }
128009         }
128010         if( i==(p->nToken-1) ){
128011           pDL->iDocid = iMax;
128012           pDL->pList = aDoclist;
128013           pDL->nList = nList;
128014           pDL->bFreeList = 1;
128015           break;
128016         }
128017         sqlite3_free(aDoclist);
128018       }
128019     }
128020   }
128021 
128022   *pbEof = bEof;
128023   return rc;
128024 }
128025 
128026 /*
128027 ** Attempt to move the phrase iterator to point to the next matching docid. 
128028 ** If an error occurs, return an SQLite error code. Otherwise, return 
128029 ** SQLITE_OK.
128030 **
128031 ** If there is no "next" entry and no error occurs, then *pbEof is set to
128032 ** 1 before returning. Otherwise, if no error occurs and the iterator is
128033 ** successfully advanced, *pbEof is set to 0.
128034 */
128035 static int fts3EvalPhraseNext(
128036   Fts3Cursor *pCsr,               /* FTS Cursor handle */
128037   Fts3Phrase *p,                  /* Phrase object to advance to next docid */
128038   u8 *pbEof                       /* OUT: Set to 1 if EOF */
128039 ){
128040   int rc = SQLITE_OK;
128041   Fts3Doclist *pDL = &p->doclist;
128042   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
128043 
128044   if( p->bIncr ){
128045     rc = fts3EvalIncrPhraseNext(pCsr, p, pbEof);
128046   }else if( pCsr->bDesc!=pTab->bDescIdx && pDL->nAll ){
128047     sqlite3Fts3DoclistPrev(pTab->bDescIdx, pDL->aAll, pDL->nAll, 
128048         &pDL->pNextDocid, &pDL->iDocid, &pDL->nList, pbEof
128049     );
128050     pDL->pList = pDL->pNextDocid;
128051   }else{
128052     fts3EvalDlPhraseNext(pTab, pDL, pbEof);
128053   }
128054 
128055   return rc;
128056 }
128057 
128058 /*
128059 **
128060 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
128061 ** Otherwise, fts3EvalPhraseStart() is called on all phrases within the
128062 ** expression. Also the Fts3Expr.bDeferred variable is set to true for any
128063 ** expressions for which all descendent tokens are deferred.
128064 **
128065 ** If parameter bOptOk is zero, then it is guaranteed that the
128066 ** Fts3Phrase.doclist.aAll/nAll variables contain the entire doclist for
128067 ** each phrase in the expression (subject to deferred token processing).
128068 ** Or, if bOptOk is non-zero, then one or more tokens within the expression
128069 ** may be loaded incrementally, meaning doclist.aAll/nAll is not available.
128070 **
128071 ** If an error occurs within this function, *pRc is set to an SQLite error
128072 ** code before returning.
128073 */
128074 static void fts3EvalStartReaders(
128075   Fts3Cursor *pCsr,               /* FTS Cursor handle */
128076   Fts3Expr *pExpr,                /* Expression to initialize phrases in */
128077   int *pRc                        /* IN/OUT: Error code */
128078 ){
128079   if( pExpr && SQLITE_OK==*pRc ){
128080     if( pExpr->eType==FTSQUERY_PHRASE ){
128081       int i;
128082       int nToken = pExpr->pPhrase->nToken;
128083       for(i=0; i<nToken; i++){
128084         if( pExpr->pPhrase->aToken[i].pDeferred==0 ) break;
128085       }
128086       pExpr->bDeferred = (i==nToken);
128087       *pRc = fts3EvalPhraseStart(pCsr, 1, pExpr->pPhrase);
128088     }else{
128089       fts3EvalStartReaders(pCsr, pExpr->pLeft, pRc);
128090       fts3EvalStartReaders(pCsr, pExpr->pRight, pRc);
128091       pExpr->bDeferred = (pExpr->pLeft->bDeferred && pExpr->pRight->bDeferred);
128092     }
128093   }
128094 }
128095 
128096 /*
128097 ** An array of the following structures is assembled as part of the process
128098 ** of selecting tokens to defer before the query starts executing (as part
128099 ** of the xFilter() method). There is one element in the array for each
128100 ** token in the FTS expression.
128101 **
128102 ** Tokens are divided into AND/NEAR clusters. All tokens in a cluster belong
128103 ** to phrases that are connected only by AND and NEAR operators (not OR or
128104 ** NOT). When determining tokens to defer, each AND/NEAR cluster is considered
128105 ** separately. The root of a tokens AND/NEAR cluster is stored in 
128106 ** Fts3TokenAndCost.pRoot.
128107 */
128108 typedef struct Fts3TokenAndCost Fts3TokenAndCost;
128109 struct Fts3TokenAndCost {
128110   Fts3Phrase *pPhrase;            /* The phrase the token belongs to */
128111   int iToken;                     /* Position of token in phrase */
128112   Fts3PhraseToken *pToken;        /* The token itself */
128113   Fts3Expr *pRoot;                /* Root of NEAR/AND cluster */
128114   int nOvfl;                      /* Number of overflow pages to load doclist */
128115   int iCol;                       /* The column the token must match */
128116 };
128117 
128118 /*
128119 ** This function is used to populate an allocated Fts3TokenAndCost array.
128120 **
128121 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
128122 ** Otherwise, if an error occurs during execution, *pRc is set to an
128123 ** SQLite error code.
128124 */
128125 static void fts3EvalTokenCosts(
128126   Fts3Cursor *pCsr,               /* FTS Cursor handle */
128127   Fts3Expr *pRoot,                /* Root of current AND/NEAR cluster */
128128   Fts3Expr *pExpr,                /* Expression to consider */
128129   Fts3TokenAndCost **ppTC,        /* Write new entries to *(*ppTC)++ */
128130   Fts3Expr ***ppOr,               /* Write new OR root to *(*ppOr)++ */
128131   int *pRc                        /* IN/OUT: Error code */
128132 ){
128133   if( *pRc==SQLITE_OK ){
128134     if( pExpr->eType==FTSQUERY_PHRASE ){
128135       Fts3Phrase *pPhrase = pExpr->pPhrase;
128136       int i;
128137       for(i=0; *pRc==SQLITE_OK && i<pPhrase->nToken; i++){
128138         Fts3TokenAndCost *pTC = (*ppTC)++;
128139         pTC->pPhrase = pPhrase;
128140         pTC->iToken = i;
128141         pTC->pRoot = pRoot;
128142         pTC->pToken = &pPhrase->aToken[i];
128143         pTC->iCol = pPhrase->iColumn;
128144         *pRc = sqlite3Fts3MsrOvfl(pCsr, pTC->pToken->pSegcsr, &pTC->nOvfl);
128145       }
128146     }else if( pExpr->eType!=FTSQUERY_NOT ){
128147       assert( pExpr->eType==FTSQUERY_OR
128148            || pExpr->eType==FTSQUERY_AND
128149            || pExpr->eType==FTSQUERY_NEAR
128150       );
128151       assert( pExpr->pLeft && pExpr->pRight );
128152       if( pExpr->eType==FTSQUERY_OR ){
128153         pRoot = pExpr->pLeft;
128154         **ppOr = pRoot;
128155         (*ppOr)++;
128156       }
128157       fts3EvalTokenCosts(pCsr, pRoot, pExpr->pLeft, ppTC, ppOr, pRc);
128158       if( pExpr->eType==FTSQUERY_OR ){
128159         pRoot = pExpr->pRight;
128160         **ppOr = pRoot;
128161         (*ppOr)++;
128162       }
128163       fts3EvalTokenCosts(pCsr, pRoot, pExpr->pRight, ppTC, ppOr, pRc);
128164     }
128165   }
128166 }
128167 
128168 /*
128169 ** Determine the average document (row) size in pages. If successful,
128170 ** write this value to *pnPage and return SQLITE_OK. Otherwise, return
128171 ** an SQLite error code.
128172 **
128173 ** The average document size in pages is calculated by first calculating 
128174 ** determining the average size in bytes, B. If B is less than the amount
128175 ** of data that will fit on a single leaf page of an intkey table in
128176 ** this database, then the average docsize is 1. Otherwise, it is 1 plus
128177 ** the number of overflow pages consumed by a record B bytes in size.
128178 */
128179 static int fts3EvalAverageDocsize(Fts3Cursor *pCsr, int *pnPage){
128180   if( pCsr->nRowAvg==0 ){
128181     /* The average document size, which is required to calculate the cost
128182     ** of each doclist, has not yet been determined. Read the required 
128183     ** data from the %_stat table to calculate it.
128184     **
128185     ** Entry 0 of the %_stat table is a blob containing (nCol+1) FTS3 
128186     ** varints, where nCol is the number of columns in the FTS3 table.
128187     ** The first varint is the number of documents currently stored in
128188     ** the table. The following nCol varints contain the total amount of
128189     ** data stored in all rows of each column of the table, from left
128190     ** to right.
128191     */
128192     int rc;
128193     Fts3Table *p = (Fts3Table*)pCsr->base.pVtab;
128194     sqlite3_stmt *pStmt;
128195     sqlite3_int64 nDoc = 0;
128196     sqlite3_int64 nByte = 0;
128197     const char *pEnd;
128198     const char *a;
128199 
128200     rc = sqlite3Fts3SelectDoctotal(p, &pStmt);
128201     if( rc!=SQLITE_OK ) return rc;
128202     a = sqlite3_column_blob(pStmt, 0);
128203     assert( a );
128204 
128205     pEnd = &a[sqlite3_column_bytes(pStmt, 0)];
128206     a += sqlite3Fts3GetVarint(a, &nDoc);
128207     while( a<pEnd ){
128208       a += sqlite3Fts3GetVarint(a, &nByte);
128209     }
128210     if( nDoc==0 || nByte==0 ){
128211       sqlite3_reset(pStmt);
128212       return FTS_CORRUPT_VTAB;
128213     }
128214 
128215     pCsr->nDoc = nDoc;
128216     pCsr->nRowAvg = (int)(((nByte / nDoc) + p->nPgsz) / p->nPgsz);
128217     assert( pCsr->nRowAvg>0 ); 
128218     rc = sqlite3_reset(pStmt);
128219     if( rc!=SQLITE_OK ) return rc;
128220   }
128221 
128222   *pnPage = pCsr->nRowAvg;
128223   return SQLITE_OK;
128224 }
128225 
128226 /*
128227 ** This function is called to select the tokens (if any) that will be 
128228 ** deferred. The array aTC[] has already been populated when this is
128229 ** called.
128230 **
128231 ** This function is called once for each AND/NEAR cluster in the 
128232 ** expression. Each invocation determines which tokens to defer within
128233 ** the cluster with root node pRoot. See comments above the definition
128234 ** of struct Fts3TokenAndCost for more details.
128235 **
128236 ** If no error occurs, SQLITE_OK is returned and sqlite3Fts3DeferToken()
128237 ** called on each token to defer. Otherwise, an SQLite error code is
128238 ** returned.
128239 */
128240 static int fts3EvalSelectDeferred(
128241   Fts3Cursor *pCsr,               /* FTS Cursor handle */
128242   Fts3Expr *pRoot,                /* Consider tokens with this root node */
128243   Fts3TokenAndCost *aTC,          /* Array of expression tokens and costs */
128244   int nTC                         /* Number of entries in aTC[] */
128245 ){
128246   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
128247   int nDocSize = 0;               /* Number of pages per doc loaded */
128248   int rc = SQLITE_OK;             /* Return code */
128249   int ii;                         /* Iterator variable for various purposes */
128250   int nOvfl = 0;                  /* Total overflow pages used by doclists */
128251   int nToken = 0;                 /* Total number of tokens in cluster */
128252 
128253   int nMinEst = 0;                /* The minimum count for any phrase so far. */
128254   int nLoad4 = 1;                 /* (Phrases that will be loaded)^4. */
128255 
128256   /* Tokens are never deferred for FTS tables created using the content=xxx
128257   ** option. The reason being that it is not guaranteed that the content
128258   ** table actually contains the same data as the index. To prevent this from
128259   ** causing any problems, the deferred token optimization is completely
128260   ** disabled for content=xxx tables. */
128261   if( pTab->zContentTbl ){
128262     return SQLITE_OK;
128263   }
128264 
128265   /* Count the tokens in this AND/NEAR cluster. If none of the doclists
128266   ** associated with the tokens spill onto overflow pages, or if there is
128267   ** only 1 token, exit early. No tokens to defer in this case. */
128268   for(ii=0; ii<nTC; ii++){
128269     if( aTC[ii].pRoot==pRoot ){
128270       nOvfl += aTC[ii].nOvfl;
128271       nToken++;
128272     }
128273   }
128274   if( nOvfl==0 || nToken<2 ) return SQLITE_OK;
128275 
128276   /* Obtain the average docsize (in pages). */
128277   rc = fts3EvalAverageDocsize(pCsr, &nDocSize);
128278   assert( rc!=SQLITE_OK || nDocSize>0 );
128279 
128280 
128281   /* Iterate through all tokens in this AND/NEAR cluster, in ascending order 
128282   ** of the number of overflow pages that will be loaded by the pager layer 
128283   ** to retrieve the entire doclist for the token from the full-text index.
128284   ** Load the doclists for tokens that are either:
128285   **
128286   **   a. The cheapest token in the entire query (i.e. the one visited by the
128287   **      first iteration of this loop), or
128288   **
128289   **   b. Part of a multi-token phrase.
128290   **
128291   ** After each token doclist is loaded, merge it with the others from the
128292   ** same phrase and count the number of documents that the merged doclist
128293   ** contains. Set variable "nMinEst" to the smallest number of documents in 
128294   ** any phrase doclist for which 1 or more token doclists have been loaded.
128295   ** Let nOther be the number of other phrases for which it is certain that
128296   ** one or more tokens will not be deferred.
128297   **
128298   ** Then, for each token, defer it if loading the doclist would result in
128299   ** loading N or more overflow pages into memory, where N is computed as:
128300   **
128301   **    (nMinEst + 4^nOther - 1) / (4^nOther)
128302   */
128303   for(ii=0; ii<nToken && rc==SQLITE_OK; ii++){
128304     int iTC;                      /* Used to iterate through aTC[] array. */
128305     Fts3TokenAndCost *pTC = 0;    /* Set to cheapest remaining token. */
128306 
128307     /* Set pTC to point to the cheapest remaining token. */
128308     for(iTC=0; iTC<nTC; iTC++){
128309       if( aTC[iTC].pToken && aTC[iTC].pRoot==pRoot 
128310        && (!pTC || aTC[iTC].nOvfl<pTC->nOvfl) 
128311       ){
128312         pTC = &aTC[iTC];
128313       }
128314     }
128315     assert( pTC );
128316 
128317     if( ii && pTC->nOvfl>=((nMinEst+(nLoad4/4)-1)/(nLoad4/4))*nDocSize ){
128318       /* The number of overflow pages to load for this (and therefore all
128319       ** subsequent) tokens is greater than the estimated number of pages 
128320       ** that will be loaded if all subsequent tokens are deferred.
128321       */
128322       Fts3PhraseToken *pToken = pTC->pToken;
128323       rc = sqlite3Fts3DeferToken(pCsr, pToken, pTC->iCol);
128324       fts3SegReaderCursorFree(pToken->pSegcsr);
128325       pToken->pSegcsr = 0;
128326     }else{
128327       /* Set nLoad4 to the value of (4^nOther) for the next iteration of the
128328       ** for-loop. Except, limit the value to 2^24 to prevent it from 
128329       ** overflowing the 32-bit integer it is stored in. */
128330       if( ii<12 ) nLoad4 = nLoad4*4;
128331 
128332       if( ii==0 || (pTC->pPhrase->nToken>1 && ii!=nToken-1) ){
128333         /* Either this is the cheapest token in the entire query, or it is
128334         ** part of a multi-token phrase. Either way, the entire doclist will
128335         ** (eventually) be loaded into memory. It may as well be now. */
128336         Fts3PhraseToken *pToken = pTC->pToken;
128337         int nList = 0;
128338         char *pList = 0;
128339         rc = fts3TermSelect(pTab, pToken, pTC->iCol, &nList, &pList);
128340         assert( rc==SQLITE_OK || pList==0 );
128341         if( rc==SQLITE_OK ){
128342           int nCount;
128343           fts3EvalPhraseMergeToken(pTab, pTC->pPhrase, pTC->iToken,pList,nList);
128344           nCount = fts3DoclistCountDocids(
128345               pTC->pPhrase->doclist.aAll, pTC->pPhrase->doclist.nAll
128346           );
128347           if( ii==0 || nCount<nMinEst ) nMinEst = nCount;
128348         }
128349       }
128350     }
128351     pTC->pToken = 0;
128352   }
128353 
128354   return rc;
128355 }
128356 
128357 /*
128358 ** This function is called from within the xFilter method. It initializes
128359 ** the full-text query currently stored in pCsr->pExpr. To iterate through
128360 ** the results of a query, the caller does:
128361 **
128362 **    fts3EvalStart(pCsr);
128363 **    while( 1 ){
128364 **      fts3EvalNext(pCsr);
128365 **      if( pCsr->bEof ) break;
128366 **      ... return row pCsr->iPrevId to the caller ...
128367 **    }
128368 */
128369 static int fts3EvalStart(Fts3Cursor *pCsr){
128370   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
128371   int rc = SQLITE_OK;
128372   int nToken = 0;
128373   int nOr = 0;
128374 
128375   /* Allocate a MultiSegReader for each token in the expression. */
128376   fts3EvalAllocateReaders(pCsr, pCsr->pExpr, &nToken, &nOr, &rc);
128377 
128378   /* Determine which, if any, tokens in the expression should be deferred. */
128379 #ifndef SQLITE_DISABLE_FTS4_DEFERRED
128380   if( rc==SQLITE_OK && nToken>1 && pTab->bFts4 ){
128381     Fts3TokenAndCost *aTC;
128382     Fts3Expr **apOr;
128383     aTC = (Fts3TokenAndCost *)sqlite3_malloc(
128384         sizeof(Fts3TokenAndCost) * nToken
128385       + sizeof(Fts3Expr *) * nOr * 2
128386     );
128387     apOr = (Fts3Expr **)&aTC[nToken];
128388 
128389     if( !aTC ){
128390       rc = SQLITE_NOMEM;
128391     }else{
128392       int ii;
128393       Fts3TokenAndCost *pTC = aTC;
128394       Fts3Expr **ppOr = apOr;
128395 
128396       fts3EvalTokenCosts(pCsr, 0, pCsr->pExpr, &pTC, &ppOr, &rc);
128397       nToken = (int)(pTC-aTC);
128398       nOr = (int)(ppOr-apOr);
128399 
128400       if( rc==SQLITE_OK ){
128401         rc = fts3EvalSelectDeferred(pCsr, 0, aTC, nToken);
128402         for(ii=0; rc==SQLITE_OK && ii<nOr; ii++){
128403           rc = fts3EvalSelectDeferred(pCsr, apOr[ii], aTC, nToken);
128404         }
128405       }
128406 
128407       sqlite3_free(aTC);
128408     }
128409   }
128410 #endif
128411 
128412   fts3EvalStartReaders(pCsr, pCsr->pExpr, &rc);
128413   return rc;
128414 }
128415 
128416 /*
128417 ** Invalidate the current position list for phrase pPhrase.
128418 */
128419 static void fts3EvalInvalidatePoslist(Fts3Phrase *pPhrase){
128420   if( pPhrase->doclist.bFreeList ){
128421     sqlite3_free(pPhrase->doclist.pList);
128422   }
128423   pPhrase->doclist.pList = 0;
128424   pPhrase->doclist.nList = 0;
128425   pPhrase->doclist.bFreeList = 0;
128426 }
128427 
128428 /*
128429 ** This function is called to edit the position list associated with
128430 ** the phrase object passed as the fifth argument according to a NEAR
128431 ** condition. For example:
128432 **
128433 **     abc NEAR/5 "def ghi"
128434 **
128435 ** Parameter nNear is passed the NEAR distance of the expression (5 in
128436 ** the example above). When this function is called, *paPoslist points to
128437 ** the position list, and *pnToken is the number of phrase tokens in, the
128438 ** phrase on the other side of the NEAR operator to pPhrase. For example,
128439 ** if pPhrase refers to the "def ghi" phrase, then *paPoslist points to
128440 ** the position list associated with phrase "abc".
128441 **
128442 ** All positions in the pPhrase position list that are not sufficiently
128443 ** close to a position in the *paPoslist position list are removed. If this
128444 ** leaves 0 positions, zero is returned. Otherwise, non-zero.
128445 **
128446 ** Before returning, *paPoslist is set to point to the position lsit 
128447 ** associated with pPhrase. And *pnToken is set to the number of tokens in
128448 ** pPhrase.
128449 */
128450 static int fts3EvalNearTrim(
128451   int nNear,                      /* NEAR distance. As in "NEAR/nNear". */
128452   char *aTmp,                     /* Temporary space to use */
128453   char **paPoslist,               /* IN/OUT: Position list */
128454   int *pnToken,                   /* IN/OUT: Tokens in phrase of *paPoslist */
128455   Fts3Phrase *pPhrase             /* The phrase object to trim the doclist of */
128456 ){
128457   int nParam1 = nNear + pPhrase->nToken;
128458   int nParam2 = nNear + *pnToken;
128459   int nNew;
128460   char *p2; 
128461   char *pOut; 
128462   int res;
128463 
128464   assert( pPhrase->doclist.pList );
128465 
128466   p2 = pOut = pPhrase->doclist.pList;
128467   res = fts3PoslistNearMerge(
128468     &pOut, aTmp, nParam1, nParam2, paPoslist, &p2
128469   );
128470   if( res ){
128471     nNew = (int)(pOut - pPhrase->doclist.pList) - 1;
128472     assert( pPhrase->doclist.pList[nNew]=='\0' );
128473     assert( nNew<=pPhrase->doclist.nList && nNew>0 );
128474     memset(&pPhrase->doclist.pList[nNew], 0, pPhrase->doclist.nList - nNew);
128475     pPhrase->doclist.nList = nNew;
128476     *paPoslist = pPhrase->doclist.pList;
128477     *pnToken = pPhrase->nToken;
128478   }
128479 
128480   return res;
128481 }
128482 
128483 /*
128484 ** This function is a no-op if *pRc is other than SQLITE_OK when it is called.
128485 ** Otherwise, it advances the expression passed as the second argument to
128486 ** point to the next matching row in the database. Expressions iterate through
128487 ** matching rows in docid order. Ascending order if Fts3Cursor.bDesc is zero,
128488 ** or descending if it is non-zero.
128489 **
128490 ** If an error occurs, *pRc is set to an SQLite error code. Otherwise, if
128491 ** successful, the following variables in pExpr are set:
128492 **
128493 **   Fts3Expr.bEof                (non-zero if EOF - there is no next row)
128494 **   Fts3Expr.iDocid              (valid if bEof==0. The docid of the next row)
128495 **
128496 ** If the expression is of type FTSQUERY_PHRASE, and the expression is not
128497 ** at EOF, then the following variables are populated with the position list
128498 ** for the phrase for the visited row:
128499 **
128500 **   FTs3Expr.pPhrase->doclist.nList        (length of pList in bytes)
128501 **   FTs3Expr.pPhrase->doclist.pList        (pointer to position list)
128502 **
128503 ** It says above that this function advances the expression to the next
128504 ** matching row. This is usually true, but there are the following exceptions:
128505 **
128506 **   1. Deferred tokens are not taken into account. If a phrase consists
128507 **      entirely of deferred tokens, it is assumed to match every row in
128508 **      the db. In this case the position-list is not populated at all. 
128509 **
128510 **      Or, if a phrase contains one or more deferred tokens and one or
128511 **      more non-deferred tokens, then the expression is advanced to the 
128512 **      next possible match, considering only non-deferred tokens. In other
128513 **      words, if the phrase is "A B C", and "B" is deferred, the expression
128514 **      is advanced to the next row that contains an instance of "A * C", 
128515 **      where "*" may match any single token. The position list in this case
128516 **      is populated as for "A * C" before returning.
128517 **
128518 **   2. NEAR is treated as AND. If the expression is "x NEAR y", it is 
128519 **      advanced to point to the next row that matches "x AND y".
128520 ** 
128521 ** See fts3EvalTestDeferredAndNear() for details on testing if a row is
128522 ** really a match, taking into account deferred tokens and NEAR operators.
128523 */
128524 static void fts3EvalNextRow(
128525   Fts3Cursor *pCsr,               /* FTS Cursor handle */
128526   Fts3Expr *pExpr,                /* Expr. to advance to next matching row */
128527   int *pRc                        /* IN/OUT: Error code */
128528 ){
128529   if( *pRc==SQLITE_OK ){
128530     int bDescDoclist = pCsr->bDesc;         /* Used by DOCID_CMP() macro */
128531     assert( pExpr->bEof==0 );
128532     pExpr->bStart = 1;
128533 
128534     switch( pExpr->eType ){
128535       case FTSQUERY_NEAR:
128536       case FTSQUERY_AND: {
128537         Fts3Expr *pLeft = pExpr->pLeft;
128538         Fts3Expr *pRight = pExpr->pRight;
128539         assert( !pLeft->bDeferred || !pRight->bDeferred );
128540 
128541         if( pLeft->bDeferred ){
128542           /* LHS is entirely deferred. So we assume it matches every row.
128543           ** Advance the RHS iterator to find the next row visited. */
128544           fts3EvalNextRow(pCsr, pRight, pRc);
128545           pExpr->iDocid = pRight->iDocid;
128546           pExpr->bEof = pRight->bEof;
128547         }else if( pRight->bDeferred ){
128548           /* RHS is entirely deferred. So we assume it matches every row.
128549           ** Advance the LHS iterator to find the next row visited. */
128550           fts3EvalNextRow(pCsr, pLeft, pRc);
128551           pExpr->iDocid = pLeft->iDocid;
128552           pExpr->bEof = pLeft->bEof;
128553         }else{
128554           /* Neither the RHS or LHS are deferred. */
128555           fts3EvalNextRow(pCsr, pLeft, pRc);
128556           fts3EvalNextRow(pCsr, pRight, pRc);
128557           while( !pLeft->bEof && !pRight->bEof && *pRc==SQLITE_OK ){
128558             sqlite3_int64 iDiff = DOCID_CMP(pLeft->iDocid, pRight->iDocid);
128559             if( iDiff==0 ) break;
128560             if( iDiff<0 ){
128561               fts3EvalNextRow(pCsr, pLeft, pRc);
128562             }else{
128563               fts3EvalNextRow(pCsr, pRight, pRc);
128564             }
128565           }
128566           pExpr->iDocid = pLeft->iDocid;
128567           pExpr->bEof = (pLeft->bEof || pRight->bEof);
128568         }
128569         break;
128570       }
128571   
128572       case FTSQUERY_OR: {
128573         Fts3Expr *pLeft = pExpr->pLeft;
128574         Fts3Expr *pRight = pExpr->pRight;
128575         sqlite3_int64 iCmp = DOCID_CMP(pLeft->iDocid, pRight->iDocid);
128576 
128577         assert( pLeft->bStart || pLeft->iDocid==pRight->iDocid );
128578         assert( pRight->bStart || pLeft->iDocid==pRight->iDocid );
128579 
128580         if( pRight->bEof || (pLeft->bEof==0 && iCmp<0) ){
128581           fts3EvalNextRow(pCsr, pLeft, pRc);
128582         }else if( pLeft->bEof || (pRight->bEof==0 && iCmp>0) ){
128583           fts3EvalNextRow(pCsr, pRight, pRc);
128584         }else{
128585           fts3EvalNextRow(pCsr, pLeft, pRc);
128586           fts3EvalNextRow(pCsr, pRight, pRc);
128587         }
128588 
128589         pExpr->bEof = (pLeft->bEof && pRight->bEof);
128590         iCmp = DOCID_CMP(pLeft->iDocid, pRight->iDocid);
128591         if( pRight->bEof || (pLeft->bEof==0 &&  iCmp<0) ){
128592           pExpr->iDocid = pLeft->iDocid;
128593         }else{
128594           pExpr->iDocid = pRight->iDocid;
128595         }
128596 
128597         break;
128598       }
128599 
128600       case FTSQUERY_NOT: {
128601         Fts3Expr *pLeft = pExpr->pLeft;
128602         Fts3Expr *pRight = pExpr->pRight;
128603 
128604         if( pRight->bStart==0 ){
128605           fts3EvalNextRow(pCsr, pRight, pRc);
128606           assert( *pRc!=SQLITE_OK || pRight->bStart );
128607         }
128608 
128609         fts3EvalNextRow(pCsr, pLeft, pRc);
128610         if( pLeft->bEof==0 ){
128611           while( !*pRc 
128612               && !pRight->bEof 
128613               && DOCID_CMP(pLeft->iDocid, pRight->iDocid)>0 
128614           ){
128615             fts3EvalNextRow(pCsr, pRight, pRc);
128616           }
128617         }
128618         pExpr->iDocid = pLeft->iDocid;
128619         pExpr->bEof = pLeft->bEof;
128620         break;
128621       }
128622 
128623       default: {
128624         Fts3Phrase *pPhrase = pExpr->pPhrase;
128625         fts3EvalInvalidatePoslist(pPhrase);
128626         *pRc = fts3EvalPhraseNext(pCsr, pPhrase, &pExpr->bEof);
128627         pExpr->iDocid = pPhrase->doclist.iDocid;
128628         break;
128629       }
128630     }
128631   }
128632 }
128633 
128634 /*
128635 ** If *pRc is not SQLITE_OK, or if pExpr is not the root node of a NEAR
128636 ** cluster, then this function returns 1 immediately.
128637 **
128638 ** Otherwise, it checks if the current row really does match the NEAR 
128639 ** expression, using the data currently stored in the position lists 
128640 ** (Fts3Expr->pPhrase.doclist.pList/nList) for each phrase in the expression. 
128641 **
128642 ** If the current row is a match, the position list associated with each
128643 ** phrase in the NEAR expression is edited in place to contain only those
128644 ** phrase instances sufficiently close to their peers to satisfy all NEAR
128645 ** constraints. In this case it returns 1. If the NEAR expression does not 
128646 ** match the current row, 0 is returned. The position lists may or may not
128647 ** be edited if 0 is returned.
128648 */
128649 static int fts3EvalNearTest(Fts3Expr *pExpr, int *pRc){
128650   int res = 1;
128651 
128652   /* The following block runs if pExpr is the root of a NEAR query.
128653   ** For example, the query:
128654   **
128655   **         "w" NEAR "x" NEAR "y" NEAR "z"
128656   **
128657   ** which is represented in tree form as:
128658   **
128659   **                               |
128660   **                          +--NEAR--+      <-- root of NEAR query
128661   **                          |        |
128662   **                     +--NEAR--+   "z"
128663   **                     |        |
128664   **                +--NEAR--+   "y"
128665   **                |        |
128666   **               "w"      "x"
128667   **
128668   ** The right-hand child of a NEAR node is always a phrase. The 
128669   ** left-hand child may be either a phrase or a NEAR node. There are
128670   ** no exceptions to this - it's the way the parser in fts3_expr.c works.
128671   */
128672   if( *pRc==SQLITE_OK 
128673    && pExpr->eType==FTSQUERY_NEAR 
128674    && pExpr->bEof==0
128675    && (pExpr->pParent==0 || pExpr->pParent->eType!=FTSQUERY_NEAR)
128676   ){
128677     Fts3Expr *p; 
128678     int nTmp = 0;                 /* Bytes of temp space */
128679     char *aTmp;                   /* Temp space for PoslistNearMerge() */
128680 
128681     /* Allocate temporary working space. */
128682     for(p=pExpr; p->pLeft; p=p->pLeft){
128683       nTmp += p->pRight->pPhrase->doclist.nList;
128684     }
128685     nTmp += p->pPhrase->doclist.nList;
128686     if( nTmp==0 ){
128687       res = 0;
128688     }else{
128689       aTmp = sqlite3_malloc(nTmp*2);
128690       if( !aTmp ){
128691         *pRc = SQLITE_NOMEM;
128692         res = 0;
128693       }else{
128694         char *aPoslist = p->pPhrase->doclist.pList;
128695         int nToken = p->pPhrase->nToken;
128696 
128697         for(p=p->pParent;res && p && p->eType==FTSQUERY_NEAR; p=p->pParent){
128698           Fts3Phrase *pPhrase = p->pRight->pPhrase;
128699           int nNear = p->nNear;
128700           res = fts3EvalNearTrim(nNear, aTmp, &aPoslist, &nToken, pPhrase);
128701         }
128702 
128703         aPoslist = pExpr->pRight->pPhrase->doclist.pList;
128704         nToken = pExpr->pRight->pPhrase->nToken;
128705         for(p=pExpr->pLeft; p && res; p=p->pLeft){
128706           int nNear;
128707           Fts3Phrase *pPhrase;
128708           assert( p->pParent && p->pParent->pLeft==p );
128709           nNear = p->pParent->nNear;
128710           pPhrase = (
128711               p->eType==FTSQUERY_NEAR ? p->pRight->pPhrase : p->pPhrase
128712               );
128713           res = fts3EvalNearTrim(nNear, aTmp, &aPoslist, &nToken, pPhrase);
128714         }
128715       }
128716 
128717       sqlite3_free(aTmp);
128718     }
128719   }
128720 
128721   return res;
128722 }
128723 
128724 /*
128725 ** This function is a helper function for fts3EvalTestDeferredAndNear().
128726 ** Assuming no error occurs or has occurred, It returns non-zero if the
128727 ** expression passed as the second argument matches the row that pCsr 
128728 ** currently points to, or zero if it does not.
128729 **
128730 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
128731 ** If an error occurs during execution of this function, *pRc is set to 
128732 ** the appropriate SQLite error code. In this case the returned value is 
128733 ** undefined.
128734 */
128735 static int fts3EvalTestExpr(
128736   Fts3Cursor *pCsr,               /* FTS cursor handle */
128737   Fts3Expr *pExpr,                /* Expr to test. May or may not be root. */
128738   int *pRc                        /* IN/OUT: Error code */
128739 ){
128740   int bHit = 1;                   /* Return value */
128741   if( *pRc==SQLITE_OK ){
128742     switch( pExpr->eType ){
128743       case FTSQUERY_NEAR:
128744       case FTSQUERY_AND:
128745         bHit = (
128746             fts3EvalTestExpr(pCsr, pExpr->pLeft, pRc)
128747          && fts3EvalTestExpr(pCsr, pExpr->pRight, pRc)
128748          && fts3EvalNearTest(pExpr, pRc)
128749         );
128750 
128751         /* If the NEAR expression does not match any rows, zero the doclist for 
128752         ** all phrases involved in the NEAR. This is because the snippet(),
128753         ** offsets() and matchinfo() functions are not supposed to recognize 
128754         ** any instances of phrases that are part of unmatched NEAR queries. 
128755         ** For example if this expression:
128756         **
128757         **    ... MATCH 'a OR (b NEAR c)'
128758         **
128759         ** is matched against a row containing:
128760         **
128761         **        'a b d e'
128762         **
128763         ** then any snippet() should ony highlight the "a" term, not the "b"
128764         ** (as "b" is part of a non-matching NEAR clause).
128765         */
128766         if( bHit==0 
128767          && pExpr->eType==FTSQUERY_NEAR 
128768          && (pExpr->pParent==0 || pExpr->pParent->eType!=FTSQUERY_NEAR)
128769         ){
128770           Fts3Expr *p;
128771           for(p=pExpr; p->pPhrase==0; p=p->pLeft){
128772             if( p->pRight->iDocid==pCsr->iPrevId ){
128773               fts3EvalInvalidatePoslist(p->pRight->pPhrase);
128774             }
128775           }
128776           if( p->iDocid==pCsr->iPrevId ){
128777             fts3EvalInvalidatePoslist(p->pPhrase);
128778           }
128779         }
128780 
128781         break;
128782 
128783       case FTSQUERY_OR: {
128784         int bHit1 = fts3EvalTestExpr(pCsr, pExpr->pLeft, pRc);
128785         int bHit2 = fts3EvalTestExpr(pCsr, pExpr->pRight, pRc);
128786         bHit = bHit1 || bHit2;
128787         break;
128788       }
128789 
128790       case FTSQUERY_NOT:
128791         bHit = (
128792             fts3EvalTestExpr(pCsr, pExpr->pLeft, pRc)
128793          && !fts3EvalTestExpr(pCsr, pExpr->pRight, pRc)
128794         );
128795         break;
128796 
128797       default: {
128798 #ifndef SQLITE_DISABLE_FTS4_DEFERRED
128799         if( pCsr->pDeferred 
128800          && (pExpr->iDocid==pCsr->iPrevId || pExpr->bDeferred)
128801         ){
128802           Fts3Phrase *pPhrase = pExpr->pPhrase;
128803           assert( pExpr->bDeferred || pPhrase->doclist.bFreeList==0 );
128804           if( pExpr->bDeferred ){
128805             fts3EvalInvalidatePoslist(pPhrase);
128806           }
128807           *pRc = fts3EvalDeferredPhrase(pCsr, pPhrase);
128808           bHit = (pPhrase->doclist.pList!=0);
128809           pExpr->iDocid = pCsr->iPrevId;
128810         }else
128811 #endif
128812         {
128813           bHit = (pExpr->bEof==0 && pExpr->iDocid==pCsr->iPrevId);
128814         }
128815         break;
128816       }
128817     }
128818   }
128819   return bHit;
128820 }
128821 
128822 /*
128823 ** This function is called as the second part of each xNext operation when
128824 ** iterating through the results of a full-text query. At this point the
128825 ** cursor points to a row that matches the query expression, with the
128826 ** following caveats:
128827 **
128828 **   * Up until this point, "NEAR" operators in the expression have been
128829 **     treated as "AND".
128830 **
128831 **   * Deferred tokens have not yet been considered.
128832 **
128833 ** If *pRc is not SQLITE_OK when this function is called, it immediately
128834 ** returns 0. Otherwise, it tests whether or not after considering NEAR
128835 ** operators and deferred tokens the current row is still a match for the
128836 ** expression. It returns 1 if both of the following are true:
128837 **
128838 **   1. *pRc is SQLITE_OK when this function returns, and
128839 **
128840 **   2. After scanning the current FTS table row for the deferred tokens,
128841 **      it is determined that the row does *not* match the query.
128842 **
128843 ** Or, if no error occurs and it seems the current row does match the FTS
128844 ** query, return 0.
128845 */
128846 static int fts3EvalTestDeferredAndNear(Fts3Cursor *pCsr, int *pRc){
128847   int rc = *pRc;
128848   int bMiss = 0;
128849   if( rc==SQLITE_OK ){
128850 
128851     /* If there are one or more deferred tokens, load the current row into
128852     ** memory and scan it to determine the position list for each deferred
128853     ** token. Then, see if this row is really a match, considering deferred
128854     ** tokens and NEAR operators (neither of which were taken into account
128855     ** earlier, by fts3EvalNextRow()). 
128856     */
128857     if( pCsr->pDeferred ){
128858       rc = fts3CursorSeek(0, pCsr);
128859       if( rc==SQLITE_OK ){
128860         rc = sqlite3Fts3CacheDeferredDoclists(pCsr);
128861       }
128862     }
128863     bMiss = (0==fts3EvalTestExpr(pCsr, pCsr->pExpr, &rc));
128864 
128865     /* Free the position-lists accumulated for each deferred token above. */
128866     sqlite3Fts3FreeDeferredDoclists(pCsr);
128867     *pRc = rc;
128868   }
128869   return (rc==SQLITE_OK && bMiss);
128870 }
128871 
128872 /*
128873 ** Advance to the next document that matches the FTS expression in
128874 ** Fts3Cursor.pExpr.
128875 */
128876 static int fts3EvalNext(Fts3Cursor *pCsr){
128877   int rc = SQLITE_OK;             /* Return Code */
128878   Fts3Expr *pExpr = pCsr->pExpr;
128879   assert( pCsr->isEof==0 );
128880   if( pExpr==0 ){
128881     pCsr->isEof = 1;
128882   }else{
128883     do {
128884       if( pCsr->isRequireSeek==0 ){
128885         sqlite3_reset(pCsr->pStmt);
128886       }
128887       assert( sqlite3_data_count(pCsr->pStmt)==0 );
128888       fts3EvalNextRow(pCsr, pExpr, &rc);
128889       pCsr->isEof = pExpr->bEof;
128890       pCsr->isRequireSeek = 1;
128891       pCsr->isMatchinfoNeeded = 1;
128892       pCsr->iPrevId = pExpr->iDocid;
128893     }while( pCsr->isEof==0 && fts3EvalTestDeferredAndNear(pCsr, &rc) );
128894   }
128895 
128896   /* Check if the cursor is past the end of the docid range specified
128897   ** by Fts3Cursor.iMinDocid/iMaxDocid. If so, set the EOF flag.  */
128898   if( rc==SQLITE_OK && (
128899         (pCsr->bDesc==0 && pCsr->iPrevId>pCsr->iMaxDocid)
128900      || (pCsr->bDesc!=0 && pCsr->iPrevId<pCsr->iMinDocid)
128901   )){
128902     pCsr->isEof = 1;
128903   }
128904 
128905   return rc;
128906 }
128907 
128908 /*
128909 ** Restart interation for expression pExpr so that the next call to
128910 ** fts3EvalNext() visits the first row. Do not allow incremental 
128911 ** loading or merging of phrase doclists for this iteration.
128912 **
128913 ** If *pRc is other than SQLITE_OK when this function is called, it is
128914 ** a no-op. If an error occurs within this function, *pRc is set to an
128915 ** SQLite error code before returning.
128916 */
128917 static void fts3EvalRestart(
128918   Fts3Cursor *pCsr,
128919   Fts3Expr *pExpr,
128920   int *pRc
128921 ){
128922   if( pExpr && *pRc==SQLITE_OK ){
128923     Fts3Phrase *pPhrase = pExpr->pPhrase;
128924 
128925     if( pPhrase ){
128926       fts3EvalInvalidatePoslist(pPhrase);
128927       if( pPhrase->bIncr ){
128928         int i;
128929         for(i=0; i<pPhrase->nToken; i++){
128930           Fts3PhraseToken *pToken = &pPhrase->aToken[i];
128931           assert( pToken->pDeferred==0 );
128932           if( pToken->pSegcsr ){
128933             sqlite3Fts3MsrIncrRestart(pToken->pSegcsr);
128934           }
128935         }
128936         *pRc = fts3EvalPhraseStart(pCsr, 0, pPhrase);
128937       }
128938       pPhrase->doclist.pNextDocid = 0;
128939       pPhrase->doclist.iDocid = 0;
128940     }
128941 
128942     pExpr->iDocid = 0;
128943     pExpr->bEof = 0;
128944     pExpr->bStart = 0;
128945 
128946     fts3EvalRestart(pCsr, pExpr->pLeft, pRc);
128947     fts3EvalRestart(pCsr, pExpr->pRight, pRc);
128948   }
128949 }
128950 
128951 /*
128952 ** After allocating the Fts3Expr.aMI[] array for each phrase in the 
128953 ** expression rooted at pExpr, the cursor iterates through all rows matched
128954 ** by pExpr, calling this function for each row. This function increments
128955 ** the values in Fts3Expr.aMI[] according to the position-list currently
128956 ** found in Fts3Expr.pPhrase->doclist.pList for each of the phrase 
128957 ** expression nodes.
128958 */
128959 static void fts3EvalUpdateCounts(Fts3Expr *pExpr){
128960   if( pExpr ){
128961     Fts3Phrase *pPhrase = pExpr->pPhrase;
128962     if( pPhrase && pPhrase->doclist.pList ){
128963       int iCol = 0;
128964       char *p = pPhrase->doclist.pList;
128965 
128966       assert( *p );
128967       while( 1 ){
128968         u8 c = 0;
128969         int iCnt = 0;
128970         while( 0xFE & (*p | c) ){
128971           if( (c&0x80)==0 ) iCnt++;
128972           c = *p++ & 0x80;
128973         }
128974 
128975         /* aMI[iCol*3 + 1] = Number of occurrences
128976         ** aMI[iCol*3 + 2] = Number of rows containing at least one instance
128977         */
128978         pExpr->aMI[iCol*3 + 1] += iCnt;
128979         pExpr->aMI[iCol*3 + 2] += (iCnt>0);
128980         if( *p==0x00 ) break;
128981         p++;
128982         p += fts3GetVarint32(p, &iCol);
128983       }
128984     }
128985 
128986     fts3EvalUpdateCounts(pExpr->pLeft);
128987     fts3EvalUpdateCounts(pExpr->pRight);
128988   }
128989 }
128990 
128991 /*
128992 ** Expression pExpr must be of type FTSQUERY_PHRASE.
128993 **
128994 ** If it is not already allocated and populated, this function allocates and
128995 ** populates the Fts3Expr.aMI[] array for expression pExpr. If pExpr is part
128996 ** of a NEAR expression, then it also allocates and populates the same array
128997 ** for all other phrases that are part of the NEAR expression.
128998 **
128999 ** SQLITE_OK is returned if the aMI[] array is successfully allocated and
129000 ** populated. Otherwise, if an error occurs, an SQLite error code is returned.
129001 */
129002 static int fts3EvalGatherStats(
129003   Fts3Cursor *pCsr,               /* Cursor object */
129004   Fts3Expr *pExpr                 /* FTSQUERY_PHRASE expression */
129005 ){
129006   int rc = SQLITE_OK;             /* Return code */
129007 
129008   assert( pExpr->eType==FTSQUERY_PHRASE );
129009   if( pExpr->aMI==0 ){
129010     Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
129011     Fts3Expr *pRoot;                /* Root of NEAR expression */
129012     Fts3Expr *p;                    /* Iterator used for several purposes */
129013 
129014     sqlite3_int64 iPrevId = pCsr->iPrevId;
129015     sqlite3_int64 iDocid;
129016     u8 bEof;
129017 
129018     /* Find the root of the NEAR expression */
129019     pRoot = pExpr;
129020     while( pRoot->pParent && pRoot->pParent->eType==FTSQUERY_NEAR ){
129021       pRoot = pRoot->pParent;
129022     }
129023     iDocid = pRoot->iDocid;
129024     bEof = pRoot->bEof;
129025     assert( pRoot->bStart );
129026 
129027     /* Allocate space for the aMSI[] array of each FTSQUERY_PHRASE node */
129028     for(p=pRoot; p; p=p->pLeft){
129029       Fts3Expr *pE = (p->eType==FTSQUERY_PHRASE?p:p->pRight);
129030       assert( pE->aMI==0 );
129031       pE->aMI = (u32 *)sqlite3_malloc(pTab->nColumn * 3 * sizeof(u32));
129032       if( !pE->aMI ) return SQLITE_NOMEM;
129033       memset(pE->aMI, 0, pTab->nColumn * 3 * sizeof(u32));
129034     }
129035 
129036     fts3EvalRestart(pCsr, pRoot, &rc);
129037 
129038     while( pCsr->isEof==0 && rc==SQLITE_OK ){
129039 
129040       do {
129041         /* Ensure the %_content statement is reset. */
129042         if( pCsr->isRequireSeek==0 ) sqlite3_reset(pCsr->pStmt);
129043         assert( sqlite3_data_count(pCsr->pStmt)==0 );
129044 
129045         /* Advance to the next document */
129046         fts3EvalNextRow(pCsr, pRoot, &rc);
129047         pCsr->isEof = pRoot->bEof;
129048         pCsr->isRequireSeek = 1;
129049         pCsr->isMatchinfoNeeded = 1;
129050         pCsr->iPrevId = pRoot->iDocid;
129051       }while( pCsr->isEof==0 
129052            && pRoot->eType==FTSQUERY_NEAR 
129053            && fts3EvalTestDeferredAndNear(pCsr, &rc) 
129054       );
129055 
129056       if( rc==SQLITE_OK && pCsr->isEof==0 ){
129057         fts3EvalUpdateCounts(pRoot);
129058       }
129059     }
129060 
129061     pCsr->isEof = 0;
129062     pCsr->iPrevId = iPrevId;
129063 
129064     if( bEof ){
129065       pRoot->bEof = bEof;
129066     }else{
129067       /* Caution: pRoot may iterate through docids in ascending or descending
129068       ** order. For this reason, even though it seems more defensive, the 
129069       ** do loop can not be written:
129070       **
129071       **   do {...} while( pRoot->iDocid<iDocid && rc==SQLITE_OK );
129072       */
129073       fts3EvalRestart(pCsr, pRoot, &rc);
129074       do {
129075         fts3EvalNextRow(pCsr, pRoot, &rc);
129076         assert( pRoot->bEof==0 );
129077       }while( pRoot->iDocid!=iDocid && rc==SQLITE_OK );
129078       fts3EvalTestDeferredAndNear(pCsr, &rc);
129079     }
129080   }
129081   return rc;
129082 }
129083 
129084 /*
129085 ** This function is used by the matchinfo() module to query a phrase 
129086 ** expression node for the following information:
129087 **
129088 **   1. The total number of occurrences of the phrase in each column of 
129089 **      the FTS table (considering all rows), and
129090 **
129091 **   2. For each column, the number of rows in the table for which the
129092 **      column contains at least one instance of the phrase.
129093 **
129094 ** If no error occurs, SQLITE_OK is returned and the values for each column
129095 ** written into the array aiOut as follows:
129096 **
129097 **   aiOut[iCol*3 + 1] = Number of occurrences
129098 **   aiOut[iCol*3 + 2] = Number of rows containing at least one instance
129099 **
129100 ** Caveats:
129101 **
129102 **   * If a phrase consists entirely of deferred tokens, then all output 
129103 **     values are set to the number of documents in the table. In other
129104 **     words we assume that very common tokens occur exactly once in each 
129105 **     column of each row of the table.
129106 **
129107 **   * If a phrase contains some deferred tokens (and some non-deferred 
129108 **     tokens), count the potential occurrence identified by considering
129109 **     the non-deferred tokens instead of actual phrase occurrences.
129110 **
129111 **   * If the phrase is part of a NEAR expression, then only phrase instances
129112 **     that meet the NEAR constraint are included in the counts.
129113 */
129114 SQLITE_PRIVATE int sqlite3Fts3EvalPhraseStats(
129115   Fts3Cursor *pCsr,               /* FTS cursor handle */
129116   Fts3Expr *pExpr,                /* Phrase expression */
129117   u32 *aiOut                      /* Array to write results into (see above) */
129118 ){
129119   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
129120   int rc = SQLITE_OK;
129121   int iCol;
129122 
129123   if( pExpr->bDeferred && pExpr->pParent->eType!=FTSQUERY_NEAR ){
129124     assert( pCsr->nDoc>0 );
129125     for(iCol=0; iCol<pTab->nColumn; iCol++){
129126       aiOut[iCol*3 + 1] = (u32)pCsr->nDoc;
129127       aiOut[iCol*3 + 2] = (u32)pCsr->nDoc;
129128     }
129129   }else{
129130     rc = fts3EvalGatherStats(pCsr, pExpr);
129131     if( rc==SQLITE_OK ){
129132       assert( pExpr->aMI );
129133       for(iCol=0; iCol<pTab->nColumn; iCol++){
129134         aiOut[iCol*3 + 1] = pExpr->aMI[iCol*3 + 1];
129135         aiOut[iCol*3 + 2] = pExpr->aMI[iCol*3 + 2];
129136       }
129137     }
129138   }
129139 
129140   return rc;
129141 }
129142 
129143 /*
129144 ** The expression pExpr passed as the second argument to this function
129145 ** must be of type FTSQUERY_PHRASE. 
129146 **
129147 ** The returned value is either NULL or a pointer to a buffer containing
129148 ** a position-list indicating the occurrences of the phrase in column iCol
129149 ** of the current row. 
129150 **
129151 ** More specifically, the returned buffer contains 1 varint for each 
129152 ** occurrence of the phrase in the column, stored using the normal (delta+2) 
129153 ** compression and is terminated by either an 0x01 or 0x00 byte. For example,
129154 ** if the requested column contains "a b X c d X X" and the position-list
129155 ** for 'X' is requested, the buffer returned may contain:
129156 **
129157 **     0x04 0x05 0x03 0x01   or   0x04 0x05 0x03 0x00
129158 **
129159 ** This function works regardless of whether or not the phrase is deferred,
129160 ** incremental, or neither.
129161 */
129162 SQLITE_PRIVATE int sqlite3Fts3EvalPhrasePoslist(
129163   Fts3Cursor *pCsr,               /* FTS3 cursor object */
129164   Fts3Expr *pExpr,                /* Phrase to return doclist for */
129165   int iCol,                       /* Column to return position list for */
129166   char **ppOut                    /* OUT: Pointer to position list */
129167 ){
129168   Fts3Phrase *pPhrase = pExpr->pPhrase;
129169   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
129170   char *pIter;
129171   int iThis;
129172   sqlite3_int64 iDocid;
129173 
129174   /* If this phrase is applies specifically to some column other than 
129175   ** column iCol, return a NULL pointer.  */
129176   *ppOut = 0;
129177   assert( iCol>=0 && iCol<pTab->nColumn );
129178   if( (pPhrase->iColumn<pTab->nColumn && pPhrase->iColumn!=iCol) ){
129179     return SQLITE_OK;
129180   }
129181 
129182   iDocid = pExpr->iDocid;
129183   pIter = pPhrase->doclist.pList;
129184   if( iDocid!=pCsr->iPrevId || pExpr->bEof ){
129185     int bDescDoclist = pTab->bDescIdx;      /* For DOCID_CMP macro */
129186     int iMul;                     /* +1 if csr dir matches index dir, else -1 */
129187     int bOr = 0;
129188     u8 bEof = 0;
129189     u8 bTreeEof = 0;
129190     Fts3Expr *p;                  /* Used to iterate from pExpr to root */
129191     Fts3Expr *pNear;              /* Most senior NEAR ancestor (or pExpr) */
129192 
129193     /* Check if this phrase descends from an OR expression node. If not, 
129194     ** return NULL. Otherwise, the entry that corresponds to docid 
129195     ** pCsr->iPrevId may lie earlier in the doclist buffer. Or, if the
129196     ** tree that the node is part of has been marked as EOF, but the node
129197     ** itself is not EOF, then it may point to an earlier entry. */
129198     pNear = pExpr;
129199     for(p=pExpr->pParent; p; p=p->pParent){
129200       if( p->eType==FTSQUERY_OR ) bOr = 1;
129201       if( p->eType==FTSQUERY_NEAR ) pNear = p;
129202       if( p->bEof ) bTreeEof = 1;
129203     }
129204     if( bOr==0 ) return SQLITE_OK;
129205 
129206     /* This is the descendent of an OR node. In this case we cannot use
129207     ** an incremental phrase. Load the entire doclist for the phrase
129208     ** into memory in this case.  */
129209     if( pPhrase->bIncr ){
129210       int rc = SQLITE_OK;
129211       int bEofSave = pExpr->bEof;
129212       fts3EvalRestart(pCsr, pExpr, &rc);
129213       while( rc==SQLITE_OK && !pExpr->bEof ){
129214         fts3EvalNextRow(pCsr, pExpr, &rc);
129215         if( bEofSave==0 && pExpr->iDocid==iDocid ) break;
129216       }
129217       pIter = pPhrase->doclist.pList;
129218       assert( rc!=SQLITE_OK || pPhrase->bIncr==0 );
129219       if( rc!=SQLITE_OK ) return rc;
129220     }
129221     
129222     iMul = ((pCsr->bDesc==bDescDoclist) ? 1 : -1);
129223     while( bTreeEof==1 
129224         && pNear->bEof==0
129225         && (DOCID_CMP(pNear->iDocid, pCsr->iPrevId) * iMul)<0
129226     ){
129227       int rc = SQLITE_OK;
129228       fts3EvalNextRow(pCsr, pExpr, &rc);
129229       if( rc!=SQLITE_OK ) return rc;
129230       iDocid = pExpr->iDocid;
129231       pIter = pPhrase->doclist.pList;
129232     }
129233 
129234     bEof = (pPhrase->doclist.nAll==0);
129235     assert( bDescDoclist==0 || bDescDoclist==1 );
129236     assert( pCsr->bDesc==0 || pCsr->bDesc==1 );
129237 
129238     if( bEof==0 ){
129239       if( pCsr->bDesc==bDescDoclist ){
129240         int dummy;
129241         if( pNear->bEof ){
129242           /* This expression is already at EOF. So position it to point to the
129243           ** last entry in the doclist at pPhrase->doclist.aAll[]. Variable
129244           ** iDocid is already set for this entry, so all that is required is
129245           ** to set pIter to point to the first byte of the last position-list
129246           ** in the doclist. 
129247           **
129248           ** It would also be correct to set pIter and iDocid to zero. In
129249           ** this case, the first call to sqltie3Fts4DoclistPrev() below
129250           ** would also move the iterator to point to the last entry in the 
129251           ** doclist. However, this is expensive, as to do so it has to 
129252           ** iterate through the entire doclist from start to finish (since
129253           ** it does not know the docid for the last entry).  */
129254           pIter = &pPhrase->doclist.aAll[pPhrase->doclist.nAll-1];
129255           fts3ReversePoslist(pPhrase->doclist.aAll, &pIter);
129256         }
129257         while( (pIter==0 || DOCID_CMP(iDocid, pCsr->iPrevId)>0 ) && bEof==0 ){
129258           sqlite3Fts3DoclistPrev(
129259               bDescDoclist, pPhrase->doclist.aAll, pPhrase->doclist.nAll, 
129260               &pIter, &iDocid, &dummy, &bEof
129261           );
129262         }
129263       }else{
129264         if( pNear->bEof ){
129265           pIter = 0;
129266           iDocid = 0;
129267         }
129268         while( (pIter==0 || DOCID_CMP(iDocid, pCsr->iPrevId)<0 ) && bEof==0 ){
129269           sqlite3Fts3DoclistNext(
129270               bDescDoclist, pPhrase->doclist.aAll, pPhrase->doclist.nAll, 
129271               &pIter, &iDocid, &bEof
129272           );
129273         }
129274       }
129275     }
129276 
129277     if( bEof || iDocid!=pCsr->iPrevId ) pIter = 0;
129278   }
129279   if( pIter==0 ) return SQLITE_OK;
129280 
129281   if( *pIter==0x01 ){
129282     pIter++;
129283     pIter += fts3GetVarint32(pIter, &iThis);
129284   }else{
129285     iThis = 0;
129286   }
129287   while( iThis<iCol ){
129288     fts3ColumnlistCopy(0, &pIter);
129289     if( *pIter==0x00 ) return 0;
129290     pIter++;
129291     pIter += fts3GetVarint32(pIter, &iThis);
129292   }
129293 
129294   *ppOut = ((iCol==iThis)?pIter:0);
129295   return SQLITE_OK;
129296 }
129297 
129298 /*
129299 ** Free all components of the Fts3Phrase structure that were allocated by
129300 ** the eval module. Specifically, this means to free:
129301 **
129302 **   * the contents of pPhrase->doclist, and
129303 **   * any Fts3MultiSegReader objects held by phrase tokens.
129304 */
129305 SQLITE_PRIVATE void sqlite3Fts3EvalPhraseCleanup(Fts3Phrase *pPhrase){
129306   if( pPhrase ){
129307     int i;
129308     sqlite3_free(pPhrase->doclist.aAll);
129309     fts3EvalInvalidatePoslist(pPhrase);
129310     memset(&pPhrase->doclist, 0, sizeof(Fts3Doclist));
129311     for(i=0; i<pPhrase->nToken; i++){
129312       fts3SegReaderCursorFree(pPhrase->aToken[i].pSegcsr);
129313       pPhrase->aToken[i].pSegcsr = 0;
129314     }
129315   }
129316 }
129317 
129318 
129319 /*
129320 ** Return SQLITE_CORRUPT_VTAB.
129321 */
129322 #ifdef SQLITE_DEBUG
129323 SQLITE_PRIVATE int sqlite3Fts3Corrupt(){
129324   return SQLITE_CORRUPT_VTAB;
129325 }
129326 #endif
129327 
129328 #if !SQLITE_CORE
129329 /*
129330 ** Initialize API pointer table, if required.
129331 */
129332 #ifdef _WIN32
129333 __declspec(dllexport)
129334 #endif
129335 SQLITE_API int sqlite3_fts3_init(
129336   sqlite3 *db, 
129337   char **pzErrMsg,
129338   const sqlite3_api_routines *pApi
129339 ){
129340   SQLITE_EXTENSION_INIT2(pApi)
129341   return sqlite3Fts3Init(db);
129342 }
129343 #endif
129344 
129345 #endif
129346 
129347 /************** End of fts3.c ************************************************/
129348 /************** Begin file fts3_aux.c ****************************************/
129349 /*
129350 ** 2011 Jan 27
129351 **
129352 ** The author disclaims copyright to this source code.  In place of
129353 ** a legal notice, here is a blessing:
129354 **
129355 **    May you do good and not evil.
129356 **    May you find forgiveness for yourself and forgive others.
129357 **    May you share freely, never taking more than you give.
129358 **
129359 ******************************************************************************
129360 **
129361 */
129362 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
129363 
129364 /* #include <string.h> */
129365 /* #include <assert.h> */
129366 
129367 typedef struct Fts3auxTable Fts3auxTable;
129368 typedef struct Fts3auxCursor Fts3auxCursor;
129369 
129370 struct Fts3auxTable {
129371   sqlite3_vtab base;              /* Base class used by SQLite core */
129372   Fts3Table *pFts3Tab;
129373 };
129374 
129375 struct Fts3auxCursor {
129376   sqlite3_vtab_cursor base;       /* Base class used by SQLite core */
129377   Fts3MultiSegReader csr;        /* Must be right after "base" */
129378   Fts3SegFilter filter;
129379   char *zStop;
129380   int nStop;                      /* Byte-length of string zStop */
129381   int iLangid;                    /* Language id to query */
129382   int isEof;                      /* True if cursor is at EOF */
129383   sqlite3_int64 iRowid;           /* Current rowid */
129384 
129385   int iCol;                       /* Current value of 'col' column */
129386   int nStat;                      /* Size of aStat[] array */
129387   struct Fts3auxColstats {
129388     sqlite3_int64 nDoc;           /* 'documents' values for current csr row */
129389     sqlite3_int64 nOcc;           /* 'occurrences' values for current csr row */
129390   } *aStat;
129391 };
129392 
129393 /*
129394 ** Schema of the terms table.
129395 */
129396 #define FTS3_AUX_SCHEMA \
129397   "CREATE TABLE x(term, col, documents, occurrences, languageid HIDDEN)"
129398 
129399 /*
129400 ** This function does all the work for both the xConnect and xCreate methods.
129401 ** These tables have no persistent representation of their own, so xConnect
129402 ** and xCreate are identical operations.
129403 */
129404 static int fts3auxConnectMethod(
129405   sqlite3 *db,                    /* Database connection */
129406   void *pUnused,                  /* Unused */
129407   int argc,                       /* Number of elements in argv array */
129408   const char * const *argv,       /* xCreate/xConnect argument array */
129409   sqlite3_vtab **ppVtab,          /* OUT: New sqlite3_vtab object */
129410   char **pzErr                    /* OUT: sqlite3_malloc'd error message */
129411 ){
129412   char const *zDb;                /* Name of database (e.g. "main") */
129413   char const *zFts3;              /* Name of fts3 table */
129414   int nDb;                        /* Result of strlen(zDb) */
129415   int nFts3;                      /* Result of strlen(zFts3) */
129416   int nByte;                      /* Bytes of space to allocate here */
129417   int rc;                         /* value returned by declare_vtab() */
129418   Fts3auxTable *p;                /* Virtual table object to return */
129419 
129420   UNUSED_PARAMETER(pUnused);
129421 
129422   /* The user should invoke this in one of two forms:
129423   **
129424   **     CREATE VIRTUAL TABLE xxx USING fts4aux(fts4-table);
129425   **     CREATE VIRTUAL TABLE xxx USING fts4aux(fts4-table-db, fts4-table);
129426   */
129427   if( argc!=4 && argc!=5 ) goto bad_args;
129428 
129429   zDb = argv[1]; 
129430   nDb = (int)strlen(zDb);
129431   if( argc==5 ){
129432     if( nDb==4 && 0==sqlite3_strnicmp("temp", zDb, 4) ){
129433       zDb = argv[3]; 
129434       nDb = (int)strlen(zDb);
129435       zFts3 = argv[4];
129436     }else{
129437       goto bad_args;
129438     }
129439   }else{
129440     zFts3 = argv[3];
129441   }
129442   nFts3 = (int)strlen(zFts3);
129443 
129444   rc = sqlite3_declare_vtab(db, FTS3_AUX_SCHEMA);
129445   if( rc!=SQLITE_OK ) return rc;
129446 
129447   nByte = sizeof(Fts3auxTable) + sizeof(Fts3Table) + nDb + nFts3 + 2;
129448   p = (Fts3auxTable *)sqlite3_malloc(nByte);
129449   if( !p ) return SQLITE_NOMEM;
129450   memset(p, 0, nByte);
129451 
129452   p->pFts3Tab = (Fts3Table *)&p[1];
129453   p->pFts3Tab->zDb = (char *)&p->pFts3Tab[1];
129454   p->pFts3Tab->zName = &p->pFts3Tab->zDb[nDb+1];
129455   p->pFts3Tab->db = db;
129456   p->pFts3Tab->nIndex = 1;
129457 
129458   memcpy((char *)p->pFts3Tab->zDb, zDb, nDb);
129459   memcpy((char *)p->pFts3Tab->zName, zFts3, nFts3);
129460   sqlite3Fts3Dequote((char *)p->pFts3Tab->zName);
129461 
129462   *ppVtab = (sqlite3_vtab *)p;
129463   return SQLITE_OK;
129464 
129465  bad_args:
129466   *pzErr = sqlite3_mprintf("invalid arguments to fts4aux constructor");
129467   return SQLITE_ERROR;
129468 }
129469 
129470 /*
129471 ** This function does the work for both the xDisconnect and xDestroy methods.
129472 ** These tables have no persistent representation of their own, so xDisconnect
129473 ** and xDestroy are identical operations.
129474 */
129475 static int fts3auxDisconnectMethod(sqlite3_vtab *pVtab){
129476   Fts3auxTable *p = (Fts3auxTable *)pVtab;
129477   Fts3Table *pFts3 = p->pFts3Tab;
129478   int i;
129479 
129480   /* Free any prepared statements held */
129481   for(i=0; i<SizeofArray(pFts3->aStmt); i++){
129482     sqlite3_finalize(pFts3->aStmt[i]);
129483   }
129484   sqlite3_free(pFts3->zSegmentsTbl);
129485   sqlite3_free(p);
129486   return SQLITE_OK;
129487 }
129488 
129489 #define FTS4AUX_EQ_CONSTRAINT 1
129490 #define FTS4AUX_GE_CONSTRAINT 2
129491 #define FTS4AUX_LE_CONSTRAINT 4
129492 
129493 /*
129494 ** xBestIndex - Analyze a WHERE and ORDER BY clause.
129495 */
129496 static int fts3auxBestIndexMethod(
129497   sqlite3_vtab *pVTab, 
129498   sqlite3_index_info *pInfo
129499 ){
129500   int i;
129501   int iEq = -1;
129502   int iGe = -1;
129503   int iLe = -1;
129504   int iLangid = -1;
129505   int iNext = 1;                  /* Next free argvIndex value */
129506 
129507   UNUSED_PARAMETER(pVTab);
129508 
129509   /* This vtab delivers always results in "ORDER BY term ASC" order. */
129510   if( pInfo->nOrderBy==1 
129511    && pInfo->aOrderBy[0].iColumn==0 
129512    && pInfo->aOrderBy[0].desc==0
129513   ){
129514     pInfo->orderByConsumed = 1;
129515   }
129516 
129517   /* Search for equality and range constraints on the "term" column. 
129518   ** And equality constraints on the hidden "languageid" column. */
129519   for(i=0; i<pInfo->nConstraint; i++){
129520     if( pInfo->aConstraint[i].usable ){
129521       int op = pInfo->aConstraint[i].op;
129522       int iCol = pInfo->aConstraint[i].iColumn;
129523 
129524       if( iCol==0 ){
129525         if( op==SQLITE_INDEX_CONSTRAINT_EQ ) iEq = i;
129526         if( op==SQLITE_INDEX_CONSTRAINT_LT ) iLe = i;
129527         if( op==SQLITE_INDEX_CONSTRAINT_LE ) iLe = i;
129528         if( op==SQLITE_INDEX_CONSTRAINT_GT ) iGe = i;
129529         if( op==SQLITE_INDEX_CONSTRAINT_GE ) iGe = i;
129530       }
129531       if( iCol==4 ){
129532         if( op==SQLITE_INDEX_CONSTRAINT_EQ ) iLangid = i;
129533       }
129534     }
129535   }
129536 
129537   if( iEq>=0 ){
129538     pInfo->idxNum = FTS4AUX_EQ_CONSTRAINT;
129539     pInfo->aConstraintUsage[iEq].argvIndex = iNext++;
129540     pInfo->estimatedCost = 5;
129541   }else{
129542     pInfo->idxNum = 0;
129543     pInfo->estimatedCost = 20000;
129544     if( iGe>=0 ){
129545       pInfo->idxNum += FTS4AUX_GE_CONSTRAINT;
129546       pInfo->aConstraintUsage[iGe].argvIndex = iNext++;
129547       pInfo->estimatedCost /= 2;
129548     }
129549     if( iLe>=0 ){
129550       pInfo->idxNum += FTS4AUX_LE_CONSTRAINT;
129551       pInfo->aConstraintUsage[iLe].argvIndex = iNext++;
129552       pInfo->estimatedCost /= 2;
129553     }
129554   }
129555   if( iLangid>=0 ){
129556     pInfo->aConstraintUsage[iLangid].argvIndex = iNext++;
129557     pInfo->estimatedCost--;
129558   }
129559 
129560   return SQLITE_OK;
129561 }
129562 
129563 /*
129564 ** xOpen - Open a cursor.
129565 */
129566 static int fts3auxOpenMethod(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCsr){
129567   Fts3auxCursor *pCsr;            /* Pointer to cursor object to return */
129568 
129569   UNUSED_PARAMETER(pVTab);
129570 
129571   pCsr = (Fts3auxCursor *)sqlite3_malloc(sizeof(Fts3auxCursor));
129572   if( !pCsr ) return SQLITE_NOMEM;
129573   memset(pCsr, 0, sizeof(Fts3auxCursor));
129574 
129575   *ppCsr = (sqlite3_vtab_cursor *)pCsr;
129576   return SQLITE_OK;
129577 }
129578 
129579 /*
129580 ** xClose - Close a cursor.
129581 */
129582 static int fts3auxCloseMethod(sqlite3_vtab_cursor *pCursor){
129583   Fts3Table *pFts3 = ((Fts3auxTable *)pCursor->pVtab)->pFts3Tab;
129584   Fts3auxCursor *pCsr = (Fts3auxCursor *)pCursor;
129585 
129586   sqlite3Fts3SegmentsClose(pFts3);
129587   sqlite3Fts3SegReaderFinish(&pCsr->csr);
129588   sqlite3_free((void *)pCsr->filter.zTerm);
129589   sqlite3_free(pCsr->zStop);
129590   sqlite3_free(pCsr->aStat);
129591   sqlite3_free(pCsr);
129592   return SQLITE_OK;
129593 }
129594 
129595 static int fts3auxGrowStatArray(Fts3auxCursor *pCsr, int nSize){
129596   if( nSize>pCsr->nStat ){
129597     struct Fts3auxColstats *aNew;
129598     aNew = (struct Fts3auxColstats *)sqlite3_realloc(pCsr->aStat, 
129599         sizeof(struct Fts3auxColstats) * nSize
129600     );
129601     if( aNew==0 ) return SQLITE_NOMEM;
129602     memset(&aNew[pCsr->nStat], 0, 
129603         sizeof(struct Fts3auxColstats) * (nSize - pCsr->nStat)
129604     );
129605     pCsr->aStat = aNew;
129606     pCsr->nStat = nSize;
129607   }
129608   return SQLITE_OK;
129609 }
129610 
129611 /*
129612 ** xNext - Advance the cursor to the next row, if any.
129613 */
129614 static int fts3auxNextMethod(sqlite3_vtab_cursor *pCursor){
129615   Fts3auxCursor *pCsr = (Fts3auxCursor *)pCursor;
129616   Fts3Table *pFts3 = ((Fts3auxTable *)pCursor->pVtab)->pFts3Tab;
129617   int rc;
129618 
129619   /* Increment our pretend rowid value. */
129620   pCsr->iRowid++;
129621 
129622   for(pCsr->iCol++; pCsr->iCol<pCsr->nStat; pCsr->iCol++){
129623     if( pCsr->aStat[pCsr->iCol].nDoc>0 ) return SQLITE_OK;
129624   }
129625 
129626   rc = sqlite3Fts3SegReaderStep(pFts3, &pCsr->csr);
129627   if( rc==SQLITE_ROW ){
129628     int i = 0;
129629     int nDoclist = pCsr->csr.nDoclist;
129630     char *aDoclist = pCsr->csr.aDoclist;
129631     int iCol;
129632 
129633     int eState = 0;
129634 
129635     if( pCsr->zStop ){
129636       int n = (pCsr->nStop<pCsr->csr.nTerm) ? pCsr->nStop : pCsr->csr.nTerm;
129637       int mc = memcmp(pCsr->zStop, pCsr->csr.zTerm, n);
129638       if( mc<0 || (mc==0 && pCsr->csr.nTerm>pCsr->nStop) ){
129639         pCsr->isEof = 1;
129640         return SQLITE_OK;
129641       }
129642     }
129643 
129644     if( fts3auxGrowStatArray(pCsr, 2) ) return SQLITE_NOMEM;
129645     memset(pCsr->aStat, 0, sizeof(struct Fts3auxColstats) * pCsr->nStat);
129646     iCol = 0;
129647 
129648     while( i<nDoclist ){
129649       sqlite3_int64 v = 0;
129650 
129651       i += sqlite3Fts3GetVarint(&aDoclist[i], &v);
129652       switch( eState ){
129653         /* State 0. In this state the integer just read was a docid. */
129654         case 0:
129655           pCsr->aStat[0].nDoc++;
129656           eState = 1;
129657           iCol = 0;
129658           break;
129659 
129660         /* State 1. In this state we are expecting either a 1, indicating
129661         ** that the following integer will be a column number, or the
129662         ** start of a position list for column 0.  
129663         ** 
129664         ** The only difference between state 1 and state 2 is that if the
129665         ** integer encountered in state 1 is not 0 or 1, then we need to
129666         ** increment the column 0 "nDoc" count for this term.
129667         */
129668         case 1:
129669           assert( iCol==0 );
129670           if( v>1 ){
129671             pCsr->aStat[1].nDoc++;
129672           }
129673           eState = 2;
129674           /* fall through */
129675 
129676         case 2:
129677           if( v==0 ){       /* 0x00. Next integer will be a docid. */
129678             eState = 0;
129679           }else if( v==1 ){ /* 0x01. Next integer will be a column number. */
129680             eState = 3;
129681           }else{            /* 2 or greater. A position. */
129682             pCsr->aStat[iCol+1].nOcc++;
129683             pCsr->aStat[0].nOcc++;
129684           }
129685           break;
129686 
129687         /* State 3. The integer just read is a column number. */
129688         default: assert( eState==3 );
129689           iCol = (int)v;
129690           if( fts3auxGrowStatArray(pCsr, iCol+2) ) return SQLITE_NOMEM;
129691           pCsr->aStat[iCol+1].nDoc++;
129692           eState = 2;
129693           break;
129694       }
129695     }
129696 
129697     pCsr->iCol = 0;
129698     rc = SQLITE_OK;
129699   }else{
129700     pCsr->isEof = 1;
129701   }
129702   return rc;
129703 }
129704 
129705 /*
129706 ** xFilter - Initialize a cursor to point at the start of its data.
129707 */
129708 static int fts3auxFilterMethod(
129709   sqlite3_vtab_cursor *pCursor,   /* The cursor used for this query */
129710   int idxNum,                     /* Strategy index */
129711   const char *idxStr,             /* Unused */
129712   int nVal,                       /* Number of elements in apVal */
129713   sqlite3_value **apVal           /* Arguments for the indexing scheme */
129714 ){
129715   Fts3auxCursor *pCsr = (Fts3auxCursor *)pCursor;
129716   Fts3Table *pFts3 = ((Fts3auxTable *)pCursor->pVtab)->pFts3Tab;
129717   int rc;
129718   int isScan = 0;
129719   int iLangVal = 0;               /* Language id to query */
129720 
129721   int iEq = -1;                   /* Index of term=? value in apVal */
129722   int iGe = -1;                   /* Index of term>=? value in apVal */
129723   int iLe = -1;                   /* Index of term<=? value in apVal */
129724   int iLangid = -1;               /* Index of languageid=? value in apVal */
129725   int iNext = 0;
129726 
129727   UNUSED_PARAMETER(nVal);
129728   UNUSED_PARAMETER(idxStr);
129729 
129730   assert( idxStr==0 );
129731   assert( idxNum==FTS4AUX_EQ_CONSTRAINT || idxNum==0
129732        || idxNum==FTS4AUX_LE_CONSTRAINT || idxNum==FTS4AUX_GE_CONSTRAINT
129733        || idxNum==(FTS4AUX_LE_CONSTRAINT|FTS4AUX_GE_CONSTRAINT)
129734   );
129735 
129736   if( idxNum==FTS4AUX_EQ_CONSTRAINT ){
129737     iEq = iNext++;
129738   }else{
129739     isScan = 1;
129740     if( idxNum & FTS4AUX_GE_CONSTRAINT ){
129741       iGe = iNext++;
129742     }
129743     if( idxNum & FTS4AUX_LE_CONSTRAINT ){
129744       iLe = iNext++;
129745     }
129746   }
129747   if( iNext<nVal ){
129748     iLangid = iNext++;
129749   }
129750 
129751   /* In case this cursor is being reused, close and zero it. */
129752   testcase(pCsr->filter.zTerm);
129753   sqlite3Fts3SegReaderFinish(&pCsr->csr);
129754   sqlite3_free((void *)pCsr->filter.zTerm);
129755   sqlite3_free(pCsr->aStat);
129756   memset(&pCsr->csr, 0, ((u8*)&pCsr[1]) - (u8*)&pCsr->csr);
129757 
129758   pCsr->filter.flags = FTS3_SEGMENT_REQUIRE_POS|FTS3_SEGMENT_IGNORE_EMPTY;
129759   if( isScan ) pCsr->filter.flags |= FTS3_SEGMENT_SCAN;
129760 
129761   if( iEq>=0 || iGe>=0 ){
129762     const unsigned char *zStr = sqlite3_value_text(apVal[0]);
129763     assert( (iEq==0 && iGe==-1) || (iEq==-1 && iGe==0) );
129764     if( zStr ){
129765       pCsr->filter.zTerm = sqlite3_mprintf("%s", zStr);
129766       pCsr->filter.nTerm = sqlite3_value_bytes(apVal[0]);
129767       if( pCsr->filter.zTerm==0 ) return SQLITE_NOMEM;
129768     }
129769   }
129770 
129771   if( iLe>=0 ){
129772     pCsr->zStop = sqlite3_mprintf("%s", sqlite3_value_text(apVal[iLe]));
129773     pCsr->nStop = sqlite3_value_bytes(apVal[iLe]);
129774     if( pCsr->zStop==0 ) return SQLITE_NOMEM;
129775   }
129776   
129777   if( iLangid>=0 ){
129778     iLangVal = sqlite3_value_int(apVal[iLangid]);
129779 
129780     /* If the user specified a negative value for the languageid, use zero
129781     ** instead. This works, as the "languageid=?" constraint will also
129782     ** be tested by the VDBE layer. The test will always be false (since
129783     ** this module will not return a row with a negative languageid), and
129784     ** so the overall query will return zero rows.  */
129785     if( iLangVal<0 ) iLangVal = 0;
129786   }
129787   pCsr->iLangid = iLangVal;
129788 
129789   rc = sqlite3Fts3SegReaderCursor(pFts3, iLangVal, 0, FTS3_SEGCURSOR_ALL,
129790       pCsr->filter.zTerm, pCsr->filter.nTerm, 0, isScan, &pCsr->csr
129791   );
129792   if( rc==SQLITE_OK ){
129793     rc = sqlite3Fts3SegReaderStart(pFts3, &pCsr->csr, &pCsr->filter);
129794   }
129795 
129796   if( rc==SQLITE_OK ) rc = fts3auxNextMethod(pCursor);
129797   return rc;
129798 }
129799 
129800 /*
129801 ** xEof - Return true if the cursor is at EOF, or false otherwise.
129802 */
129803 static int fts3auxEofMethod(sqlite3_vtab_cursor *pCursor){
129804   Fts3auxCursor *pCsr = (Fts3auxCursor *)pCursor;
129805   return pCsr->isEof;
129806 }
129807 
129808 /*
129809 ** xColumn - Return a column value.
129810 */
129811 static int fts3auxColumnMethod(
129812   sqlite3_vtab_cursor *pCursor,   /* Cursor to retrieve value from */
129813   sqlite3_context *pCtx,          /* Context for sqlite3_result_xxx() calls */
129814   int iCol                        /* Index of column to read value from */
129815 ){
129816   Fts3auxCursor *p = (Fts3auxCursor *)pCursor;
129817 
129818   assert( p->isEof==0 );
129819   switch( iCol ){
129820     case 0: /* term */
129821       sqlite3_result_text(pCtx, p->csr.zTerm, p->csr.nTerm, SQLITE_TRANSIENT);
129822       break;
129823 
129824     case 1: /* col */
129825       if( p->iCol ){
129826         sqlite3_result_int(pCtx, p->iCol-1);
129827       }else{
129828         sqlite3_result_text(pCtx, "*", -1, SQLITE_STATIC);
129829       }
129830       break;
129831 
129832     case 2: /* documents */
129833       sqlite3_result_int64(pCtx, p->aStat[p->iCol].nDoc);
129834       break;
129835 
129836     case 3: /* occurrences */
129837       sqlite3_result_int64(pCtx, p->aStat[p->iCol].nOcc);
129838       break;
129839 
129840     default: /* languageid */
129841       assert( iCol==4 );
129842       sqlite3_result_int(pCtx, p->iLangid);
129843       break;
129844   }
129845 
129846   return SQLITE_OK;
129847 }
129848 
129849 /*
129850 ** xRowid - Return the current rowid for the cursor.
129851 */
129852 static int fts3auxRowidMethod(
129853   sqlite3_vtab_cursor *pCursor,   /* Cursor to retrieve value from */
129854   sqlite_int64 *pRowid            /* OUT: Rowid value */
129855 ){
129856   Fts3auxCursor *pCsr = (Fts3auxCursor *)pCursor;
129857   *pRowid = pCsr->iRowid;
129858   return SQLITE_OK;
129859 }
129860 
129861 /*
129862 ** Register the fts3aux module with database connection db. Return SQLITE_OK
129863 ** if successful or an error code if sqlite3_create_module() fails.
129864 */
129865 SQLITE_PRIVATE int sqlite3Fts3InitAux(sqlite3 *db){
129866   static const sqlite3_module fts3aux_module = {
129867      0,                           /* iVersion      */
129868      fts3auxConnectMethod,        /* xCreate       */
129869      fts3auxConnectMethod,        /* xConnect      */
129870      fts3auxBestIndexMethod,      /* xBestIndex    */
129871      fts3auxDisconnectMethod,     /* xDisconnect   */
129872      fts3auxDisconnectMethod,     /* xDestroy      */
129873      fts3auxOpenMethod,           /* xOpen         */
129874      fts3auxCloseMethod,          /* xClose        */
129875      fts3auxFilterMethod,         /* xFilter       */
129876      fts3auxNextMethod,           /* xNext         */
129877      fts3auxEofMethod,            /* xEof          */
129878      fts3auxColumnMethod,         /* xColumn       */
129879      fts3auxRowidMethod,          /* xRowid        */
129880      0,                           /* xUpdate       */
129881      0,                           /* xBegin        */
129882      0,                           /* xSync         */
129883      0,                           /* xCommit       */
129884      0,                           /* xRollback     */
129885      0,                           /* xFindFunction */
129886      0,                           /* xRename       */
129887      0,                           /* xSavepoint    */
129888      0,                           /* xRelease      */
129889      0                            /* xRollbackTo   */
129890   };
129891   int rc;                         /* Return code */
129892 
129893   rc = sqlite3_create_module(db, "fts4aux", &fts3aux_module, 0);
129894   return rc;
129895 }
129896 
129897 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
129898 
129899 /************** End of fts3_aux.c ********************************************/
129900 /************** Begin file fts3_expr.c ***************************************/
129901 /*
129902 ** 2008 Nov 28
129903 **
129904 ** The author disclaims copyright to this source code.  In place of
129905 ** a legal notice, here is a blessing:
129906 **
129907 **    May you do good and not evil.
129908 **    May you find forgiveness for yourself and forgive others.
129909 **    May you share freely, never taking more than you give.
129910 **
129911 ******************************************************************************
129912 **
129913 ** This module contains code that implements a parser for fts3 query strings
129914 ** (the right-hand argument to the MATCH operator). Because the supported 
129915 ** syntax is relatively simple, the whole tokenizer/parser system is
129916 ** hand-coded. 
129917 */
129918 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
129919 
129920 /*
129921 ** By default, this module parses the legacy syntax that has been 
129922 ** traditionally used by fts3. Or, if SQLITE_ENABLE_FTS3_PARENTHESIS
129923 ** is defined, then it uses the new syntax. The differences between
129924 ** the new and the old syntaxes are:
129925 **
129926 **  a) The new syntax supports parenthesis. The old does not.
129927 **
129928 **  b) The new syntax supports the AND and NOT operators. The old does not.
129929 **
129930 **  c) The old syntax supports the "-" token qualifier. This is not 
129931 **     supported by the new syntax (it is replaced by the NOT operator).
129932 **
129933 **  d) When using the old syntax, the OR operator has a greater precedence
129934 **     than an implicit AND. When using the new, both implicity and explicit
129935 **     AND operators have a higher precedence than OR.
129936 **
129937 ** If compiled with SQLITE_TEST defined, then this module exports the
129938 ** symbol "int sqlite3_fts3_enable_parentheses". Setting this variable
129939 ** to zero causes the module to use the old syntax. If it is set to 
129940 ** non-zero the new syntax is activated. This is so both syntaxes can
129941 ** be tested using a single build of testfixture.
129942 **
129943 ** The following describes the syntax supported by the fts3 MATCH
129944 ** operator in a similar format to that used by the lemon parser
129945 ** generator. This module does not use actually lemon, it uses a
129946 ** custom parser.
129947 **
129948 **   query ::= andexpr (OR andexpr)*.
129949 **
129950 **   andexpr ::= notexpr (AND? notexpr)*.
129951 **
129952 **   notexpr ::= nearexpr (NOT nearexpr|-TOKEN)*.
129953 **   notexpr ::= LP query RP.
129954 **
129955 **   nearexpr ::= phrase (NEAR distance_opt nearexpr)*.
129956 **
129957 **   distance_opt ::= .
129958 **   distance_opt ::= / INTEGER.
129959 **
129960 **   phrase ::= TOKEN.
129961 **   phrase ::= COLUMN:TOKEN.
129962 **   phrase ::= "TOKEN TOKEN TOKEN...".
129963 */
129964 
129965 #ifdef SQLITE_TEST
129966 SQLITE_API int sqlite3_fts3_enable_parentheses = 0;
129967 #else
129968 # ifdef SQLITE_ENABLE_FTS3_PARENTHESIS 
129969 #  define sqlite3_fts3_enable_parentheses 1
129970 # else
129971 #  define sqlite3_fts3_enable_parentheses 0
129972 # endif
129973 #endif
129974 
129975 /*
129976 ** Default span for NEAR operators.
129977 */
129978 #define SQLITE_FTS3_DEFAULT_NEAR_PARAM 10
129979 
129980 /* #include <string.h> */
129981 /* #include <assert.h> */
129982 
129983 /*
129984 ** isNot:
129985 **   This variable is used by function getNextNode(). When getNextNode() is
129986 **   called, it sets ParseContext.isNot to true if the 'next node' is a 
129987 **   FTSQUERY_PHRASE with a unary "-" attached to it. i.e. "mysql" in the
129988 **   FTS3 query "sqlite -mysql". Otherwise, ParseContext.isNot is set to
129989 **   zero.
129990 */
129991 typedef struct ParseContext ParseContext;
129992 struct ParseContext {
129993   sqlite3_tokenizer *pTokenizer;      /* Tokenizer module */
129994   int iLangid;                        /* Language id used with tokenizer */
129995   const char **azCol;                 /* Array of column names for fts3 table */
129996   int bFts4;                          /* True to allow FTS4-only syntax */
129997   int nCol;                           /* Number of entries in azCol[] */
129998   int iDefaultCol;                    /* Default column to query */
129999   int isNot;                          /* True if getNextNode() sees a unary - */
130000   sqlite3_context *pCtx;              /* Write error message here */
130001   int nNest;                          /* Number of nested brackets */
130002 };
130003 
130004 /*
130005 ** This function is equivalent to the standard isspace() function. 
130006 **
130007 ** The standard isspace() can be awkward to use safely, because although it
130008 ** is defined to accept an argument of type int, its behavior when passed
130009 ** an integer that falls outside of the range of the unsigned char type
130010 ** is undefined (and sometimes, "undefined" means segfault). This wrapper
130011 ** is defined to accept an argument of type char, and always returns 0 for
130012 ** any values that fall outside of the range of the unsigned char type (i.e.
130013 ** negative values).
130014 */
130015 static int fts3isspace(char c){
130016   return c==' ' || c=='\t' || c=='\n' || c=='\r' || c=='\v' || c=='\f';
130017 }
130018 
130019 /*
130020 ** Allocate nByte bytes of memory using sqlite3_malloc(). If successful,
130021 ** zero the memory before returning a pointer to it. If unsuccessful, 
130022 ** return NULL.
130023 */
130024 static void *fts3MallocZero(int nByte){
130025   void *pRet = sqlite3_malloc(nByte);
130026   if( pRet ) memset(pRet, 0, nByte);
130027   return pRet;
130028 }
130029 
130030 SQLITE_PRIVATE int sqlite3Fts3OpenTokenizer(
130031   sqlite3_tokenizer *pTokenizer,
130032   int iLangid,
130033   const char *z,
130034   int n,
130035   sqlite3_tokenizer_cursor **ppCsr
130036 ){
130037   sqlite3_tokenizer_module const *pModule = pTokenizer->pModule;
130038   sqlite3_tokenizer_cursor *pCsr = 0;
130039   int rc;
130040 
130041   rc = pModule->xOpen(pTokenizer, z, n, &pCsr);
130042   assert( rc==SQLITE_OK || pCsr==0 );
130043   if( rc==SQLITE_OK ){
130044     pCsr->pTokenizer = pTokenizer;
130045     if( pModule->iVersion>=1 ){
130046       rc = pModule->xLanguageid(pCsr, iLangid);
130047       if( rc!=SQLITE_OK ){
130048         pModule->xClose(pCsr);
130049         pCsr = 0;
130050       }
130051     }
130052   }
130053   *ppCsr = pCsr;
130054   return rc;
130055 }
130056 
130057 /*
130058 ** Function getNextNode(), which is called by fts3ExprParse(), may itself
130059 ** call fts3ExprParse(). So this forward declaration is required.
130060 */
130061 static int fts3ExprParse(ParseContext *, const char *, int, Fts3Expr **, int *);
130062 
130063 /*
130064 ** Extract the next token from buffer z (length n) using the tokenizer
130065 ** and other information (column names etc.) in pParse. Create an Fts3Expr
130066 ** structure of type FTSQUERY_PHRASE containing a phrase consisting of this
130067 ** single token and set *ppExpr to point to it. If the end of the buffer is
130068 ** reached before a token is found, set *ppExpr to zero. It is the
130069 ** responsibility of the caller to eventually deallocate the allocated 
130070 ** Fts3Expr structure (if any) by passing it to sqlite3_free().
130071 **
130072 ** Return SQLITE_OK if successful, or SQLITE_NOMEM if a memory allocation
130073 ** fails.
130074 */
130075 static int getNextToken(
130076   ParseContext *pParse,                   /* fts3 query parse context */
130077   int iCol,                               /* Value for Fts3Phrase.iColumn */
130078   const char *z, int n,                   /* Input string */
130079   Fts3Expr **ppExpr,                      /* OUT: expression */
130080   int *pnConsumed                         /* OUT: Number of bytes consumed */
130081 ){
130082   sqlite3_tokenizer *pTokenizer = pParse->pTokenizer;
130083   sqlite3_tokenizer_module const *pModule = pTokenizer->pModule;
130084   int rc;
130085   sqlite3_tokenizer_cursor *pCursor;
130086   Fts3Expr *pRet = 0;
130087   int nConsumed = 0;
130088 
130089   rc = sqlite3Fts3OpenTokenizer(pTokenizer, pParse->iLangid, z, n, &pCursor);
130090   if( rc==SQLITE_OK ){
130091     const char *zToken;
130092     int nToken = 0, iStart = 0, iEnd = 0, iPosition = 0;
130093     int nByte;                               /* total space to allocate */
130094 
130095     rc = pModule->xNext(pCursor, &zToken, &nToken, &iStart, &iEnd, &iPosition);
130096 
130097     if( (rc==SQLITE_OK || rc==SQLITE_DONE) && sqlite3_fts3_enable_parentheses ){
130098       int i;
130099       if( rc==SQLITE_DONE ) iStart = n;
130100       for(i=0; i<iStart; i++){
130101         if( z[i]=='(' ){
130102           pParse->nNest++;
130103           rc = fts3ExprParse(pParse, &z[i+1], n-i-1, &pRet, &nConsumed);
130104           if( rc==SQLITE_OK && !pRet ){
130105             rc = SQLITE_DONE;
130106           }
130107           nConsumed = (int)(i + 1 + nConsumed);
130108           break;
130109         }
130110 
130111         if( z[i]==')' ){
130112           rc = SQLITE_DONE;
130113           pParse->nNest--;
130114           nConsumed = i+1;
130115           break;
130116         }
130117       }
130118     }
130119 
130120     if( nConsumed==0 && rc==SQLITE_OK ){
130121       nByte = sizeof(Fts3Expr) + sizeof(Fts3Phrase) + nToken;
130122       pRet = (Fts3Expr *)fts3MallocZero(nByte);
130123       if( !pRet ){
130124         rc = SQLITE_NOMEM;
130125       }else{
130126         pRet->eType = FTSQUERY_PHRASE;
130127         pRet->pPhrase = (Fts3Phrase *)&pRet[1];
130128         pRet->pPhrase->nToken = 1;
130129         pRet->pPhrase->iColumn = iCol;
130130         pRet->pPhrase->aToken[0].n = nToken;
130131         pRet->pPhrase->aToken[0].z = (char *)&pRet->pPhrase[1];
130132         memcpy(pRet->pPhrase->aToken[0].z, zToken, nToken);
130133 
130134         if( iEnd<n && z[iEnd]=='*' ){
130135           pRet->pPhrase->aToken[0].isPrefix = 1;
130136           iEnd++;
130137         }
130138 
130139         while( 1 ){
130140           if( !sqlite3_fts3_enable_parentheses 
130141            && iStart>0 && z[iStart-1]=='-' 
130142           ){
130143             pParse->isNot = 1;
130144             iStart--;
130145           }else if( pParse->bFts4 && iStart>0 && z[iStart-1]=='^' ){
130146             pRet->pPhrase->aToken[0].bFirst = 1;
130147             iStart--;
130148           }else{
130149             break;
130150           }
130151         }
130152 
130153       }
130154       nConsumed = iEnd;
130155     }
130156 
130157     pModule->xClose(pCursor);
130158   }
130159   
130160   *pnConsumed = nConsumed;
130161   *ppExpr = pRet;
130162   return rc;
130163 }
130164 
130165 
130166 /*
130167 ** Enlarge a memory allocation.  If an out-of-memory allocation occurs,
130168 ** then free the old allocation.
130169 */
130170 static void *fts3ReallocOrFree(void *pOrig, int nNew){
130171   void *pRet = sqlite3_realloc(pOrig, nNew);
130172   if( !pRet ){
130173     sqlite3_free(pOrig);
130174   }
130175   return pRet;
130176 }
130177 
130178 /*
130179 ** Buffer zInput, length nInput, contains the contents of a quoted string
130180 ** that appeared as part of an fts3 query expression. Neither quote character
130181 ** is included in the buffer. This function attempts to tokenize the entire
130182 ** input buffer and create an Fts3Expr structure of type FTSQUERY_PHRASE 
130183 ** containing the results.
130184 **
130185 ** If successful, SQLITE_OK is returned and *ppExpr set to point at the
130186 ** allocated Fts3Expr structure. Otherwise, either SQLITE_NOMEM (out of memory
130187 ** error) or SQLITE_ERROR (tokenization error) is returned and *ppExpr set
130188 ** to 0.
130189 */
130190 static int getNextString(
130191   ParseContext *pParse,                   /* fts3 query parse context */
130192   const char *zInput, int nInput,         /* Input string */
130193   Fts3Expr **ppExpr                       /* OUT: expression */
130194 ){
130195   sqlite3_tokenizer *pTokenizer = pParse->pTokenizer;
130196   sqlite3_tokenizer_module const *pModule = pTokenizer->pModule;
130197   int rc;
130198   Fts3Expr *p = 0;
130199   sqlite3_tokenizer_cursor *pCursor = 0;
130200   char *zTemp = 0;
130201   int nTemp = 0;
130202 
130203   const int nSpace = sizeof(Fts3Expr) + sizeof(Fts3Phrase);
130204   int nToken = 0;
130205 
130206   /* The final Fts3Expr data structure, including the Fts3Phrase,
130207   ** Fts3PhraseToken structures token buffers are all stored as a single 
130208   ** allocation so that the expression can be freed with a single call to
130209   ** sqlite3_free(). Setting this up requires a two pass approach.
130210   **
130211   ** The first pass, in the block below, uses a tokenizer cursor to iterate
130212   ** through the tokens in the expression. This pass uses fts3ReallocOrFree()
130213   ** to assemble data in two dynamic buffers:
130214   **
130215   **   Buffer p: Points to the Fts3Expr structure, followed by the Fts3Phrase
130216   **             structure, followed by the array of Fts3PhraseToken 
130217   **             structures. This pass only populates the Fts3PhraseToken array.
130218   **
130219   **   Buffer zTemp: Contains copies of all tokens.
130220   **
130221   ** The second pass, in the block that begins "if( rc==SQLITE_DONE )" below,
130222   ** appends buffer zTemp to buffer p, and fills in the Fts3Expr and Fts3Phrase
130223   ** structures.
130224   */
130225   rc = sqlite3Fts3OpenTokenizer(
130226       pTokenizer, pParse->iLangid, zInput, nInput, &pCursor);
130227   if( rc==SQLITE_OK ){
130228     int ii;
130229     for(ii=0; rc==SQLITE_OK; ii++){
130230       const char *zByte;
130231       int nByte = 0, iBegin = 0, iEnd = 0, iPos = 0;
130232       rc = pModule->xNext(pCursor, &zByte, &nByte, &iBegin, &iEnd, &iPos);
130233       if( rc==SQLITE_OK ){
130234         Fts3PhraseToken *pToken;
130235 
130236         p = fts3ReallocOrFree(p, nSpace + ii*sizeof(Fts3PhraseToken));
130237         if( !p ) goto no_mem;
130238 
130239         zTemp = fts3ReallocOrFree(zTemp, nTemp + nByte);
130240         if( !zTemp ) goto no_mem;
130241 
130242         assert( nToken==ii );
130243         pToken = &((Fts3Phrase *)(&p[1]))->aToken[ii];
130244         memset(pToken, 0, sizeof(Fts3PhraseToken));
130245 
130246         memcpy(&zTemp[nTemp], zByte, nByte);
130247         nTemp += nByte;
130248 
130249         pToken->n = nByte;
130250         pToken->isPrefix = (iEnd<nInput && zInput[iEnd]=='*');
130251         pToken->bFirst = (iBegin>0 && zInput[iBegin-1]=='^');
130252         nToken = ii+1;
130253       }
130254     }
130255 
130256     pModule->xClose(pCursor);
130257     pCursor = 0;
130258   }
130259 
130260   if( rc==SQLITE_DONE ){
130261     int jj;
130262     char *zBuf = 0;
130263 
130264     p = fts3ReallocOrFree(p, nSpace + nToken*sizeof(Fts3PhraseToken) + nTemp);
130265     if( !p ) goto no_mem;
130266     memset(p, 0, (char *)&(((Fts3Phrase *)&p[1])->aToken[0])-(char *)p);
130267     p->eType = FTSQUERY_PHRASE;
130268     p->pPhrase = (Fts3Phrase *)&p[1];
130269     p->pPhrase->iColumn = pParse->iDefaultCol;
130270     p->pPhrase->nToken = nToken;
130271 
130272     zBuf = (char *)&p->pPhrase->aToken[nToken];
130273     if( zTemp ){
130274       memcpy(zBuf, zTemp, nTemp);
130275       sqlite3_free(zTemp);
130276     }else{
130277       assert( nTemp==0 );
130278     }
130279 
130280     for(jj=0; jj<p->pPhrase->nToken; jj++){
130281       p->pPhrase->aToken[jj].z = zBuf;
130282       zBuf += p->pPhrase->aToken[jj].n;
130283     }
130284     rc = SQLITE_OK;
130285   }
130286 
130287   *ppExpr = p;
130288   return rc;
130289 no_mem:
130290 
130291   if( pCursor ){
130292     pModule->xClose(pCursor);
130293   }
130294   sqlite3_free(zTemp);
130295   sqlite3_free(p);
130296   *ppExpr = 0;
130297   return SQLITE_NOMEM;
130298 }
130299 
130300 /*
130301 ** The output variable *ppExpr is populated with an allocated Fts3Expr 
130302 ** structure, or set to 0 if the end of the input buffer is reached.
130303 **
130304 ** Returns an SQLite error code. SQLITE_OK if everything works, SQLITE_NOMEM
130305 ** if a malloc failure occurs, or SQLITE_ERROR if a parse error is encountered.
130306 ** If SQLITE_ERROR is returned, pContext is populated with an error message.
130307 */
130308 static int getNextNode(
130309   ParseContext *pParse,                   /* fts3 query parse context */
130310   const char *z, int n,                   /* Input string */
130311   Fts3Expr **ppExpr,                      /* OUT: expression */
130312   int *pnConsumed                         /* OUT: Number of bytes consumed */
130313 ){
130314   static const struct Fts3Keyword {
130315     char *z;                              /* Keyword text */
130316     unsigned char n;                      /* Length of the keyword */
130317     unsigned char parenOnly;              /* Only valid in paren mode */
130318     unsigned char eType;                  /* Keyword code */
130319   } aKeyword[] = {
130320     { "OR" ,  2, 0, FTSQUERY_OR   },
130321     { "AND",  3, 1, FTSQUERY_AND  },
130322     { "NOT",  3, 1, FTSQUERY_NOT  },
130323     { "NEAR", 4, 0, FTSQUERY_NEAR }
130324   };
130325   int ii;
130326   int iCol;
130327   int iColLen;
130328   int rc;
130329   Fts3Expr *pRet = 0;
130330 
130331   const char *zInput = z;
130332   int nInput = n;
130333 
130334   pParse->isNot = 0;
130335 
130336   /* Skip over any whitespace before checking for a keyword, an open or
130337   ** close bracket, or a quoted string. 
130338   */
130339   while( nInput>0 && fts3isspace(*zInput) ){
130340     nInput--;
130341     zInput++;
130342   }
130343   if( nInput==0 ){
130344     return SQLITE_DONE;
130345   }
130346 
130347   /* See if we are dealing with a keyword. */
130348   for(ii=0; ii<(int)(sizeof(aKeyword)/sizeof(struct Fts3Keyword)); ii++){
130349     const struct Fts3Keyword *pKey = &aKeyword[ii];
130350 
130351     if( (pKey->parenOnly & ~sqlite3_fts3_enable_parentheses)!=0 ){
130352       continue;
130353     }
130354 
130355     if( nInput>=pKey->n && 0==memcmp(zInput, pKey->z, pKey->n) ){
130356       int nNear = SQLITE_FTS3_DEFAULT_NEAR_PARAM;
130357       int nKey = pKey->n;
130358       char cNext;
130359 
130360       /* If this is a "NEAR" keyword, check for an explicit nearness. */
130361       if( pKey->eType==FTSQUERY_NEAR ){
130362         assert( nKey==4 );
130363         if( zInput[4]=='/' && zInput[5]>='0' && zInput[5]<='9' ){
130364           nNear = 0;
130365           for(nKey=5; zInput[nKey]>='0' && zInput[nKey]<='9'; nKey++){
130366             nNear = nNear * 10 + (zInput[nKey] - '0');
130367           }
130368         }
130369       }
130370 
130371       /* At this point this is probably a keyword. But for that to be true,
130372       ** the next byte must contain either whitespace, an open or close
130373       ** parenthesis, a quote character, or EOF. 
130374       */
130375       cNext = zInput[nKey];
130376       if( fts3isspace(cNext) 
130377        || cNext=='"' || cNext=='(' || cNext==')' || cNext==0
130378       ){
130379         pRet = (Fts3Expr *)fts3MallocZero(sizeof(Fts3Expr));
130380         if( !pRet ){
130381           return SQLITE_NOMEM;
130382         }
130383         pRet->eType = pKey->eType;
130384         pRet->nNear = nNear;
130385         *ppExpr = pRet;
130386         *pnConsumed = (int)((zInput - z) + nKey);
130387         return SQLITE_OK;
130388       }
130389 
130390       /* Turns out that wasn't a keyword after all. This happens if the
130391       ** user has supplied a token such as "ORacle". Continue.
130392       */
130393     }
130394   }
130395 
130396   /* See if we are dealing with a quoted phrase. If this is the case, then
130397   ** search for the closing quote and pass the whole string to getNextString()
130398   ** for processing. This is easy to do, as fts3 has no syntax for escaping
130399   ** a quote character embedded in a string.
130400   */
130401   if( *zInput=='"' ){
130402     for(ii=1; ii<nInput && zInput[ii]!='"'; ii++);
130403     *pnConsumed = (int)((zInput - z) + ii + 1);
130404     if( ii==nInput ){
130405       return SQLITE_ERROR;
130406     }
130407     return getNextString(pParse, &zInput[1], ii-1, ppExpr);
130408   }
130409 
130410 
130411   /* If control flows to this point, this must be a regular token, or 
130412   ** the end of the input. Read a regular token using the sqlite3_tokenizer
130413   ** interface. Before doing so, figure out if there is an explicit
130414   ** column specifier for the token. 
130415   **
130416   ** TODO: Strangely, it is not possible to associate a column specifier
130417   ** with a quoted phrase, only with a single token. Not sure if this was
130418   ** an implementation artifact or an intentional decision when fts3 was
130419   ** first implemented. Whichever it was, this module duplicates the 
130420   ** limitation.
130421   */
130422   iCol = pParse->iDefaultCol;
130423   iColLen = 0;
130424   for(ii=0; ii<pParse->nCol; ii++){
130425     const char *zStr = pParse->azCol[ii];
130426     int nStr = (int)strlen(zStr);
130427     if( nInput>nStr && zInput[nStr]==':' 
130428      && sqlite3_strnicmp(zStr, zInput, nStr)==0 
130429     ){
130430       iCol = ii;
130431       iColLen = (int)((zInput - z) + nStr + 1);
130432       break;
130433     }
130434   }
130435   rc = getNextToken(pParse, iCol, &z[iColLen], n-iColLen, ppExpr, pnConsumed);
130436   *pnConsumed += iColLen;
130437   return rc;
130438 }
130439 
130440 /*
130441 ** The argument is an Fts3Expr structure for a binary operator (any type
130442 ** except an FTSQUERY_PHRASE). Return an integer value representing the
130443 ** precedence of the operator. Lower values have a higher precedence (i.e.
130444 ** group more tightly). For example, in the C language, the == operator
130445 ** groups more tightly than ||, and would therefore have a higher precedence.
130446 **
130447 ** When using the new fts3 query syntax (when SQLITE_ENABLE_FTS3_PARENTHESIS
130448 ** is defined), the order of the operators in precedence from highest to
130449 ** lowest is:
130450 **
130451 **   NEAR
130452 **   NOT
130453 **   AND (including implicit ANDs)
130454 **   OR
130455 **
130456 ** Note that when using the old query syntax, the OR operator has a higher
130457 ** precedence than the AND operator.
130458 */
130459 static int opPrecedence(Fts3Expr *p){
130460   assert( p->eType!=FTSQUERY_PHRASE );
130461   if( sqlite3_fts3_enable_parentheses ){
130462     return p->eType;
130463   }else if( p->eType==FTSQUERY_NEAR ){
130464     return 1;
130465   }else if( p->eType==FTSQUERY_OR ){
130466     return 2;
130467   }
130468   assert( p->eType==FTSQUERY_AND );
130469   return 3;
130470 }
130471 
130472 /*
130473 ** Argument ppHead contains a pointer to the current head of a query 
130474 ** expression tree being parsed. pPrev is the expression node most recently
130475 ** inserted into the tree. This function adds pNew, which is always a binary
130476 ** operator node, into the expression tree based on the relative precedence
130477 ** of pNew and the existing nodes of the tree. This may result in the head
130478 ** of the tree changing, in which case *ppHead is set to the new root node.
130479 */
130480 static void insertBinaryOperator(
130481   Fts3Expr **ppHead,       /* Pointer to the root node of a tree */
130482   Fts3Expr *pPrev,         /* Node most recently inserted into the tree */
130483   Fts3Expr *pNew           /* New binary node to insert into expression tree */
130484 ){
130485   Fts3Expr *pSplit = pPrev;
130486   while( pSplit->pParent && opPrecedence(pSplit->pParent)<=opPrecedence(pNew) ){
130487     pSplit = pSplit->pParent;
130488   }
130489 
130490   if( pSplit->pParent ){
130491     assert( pSplit->pParent->pRight==pSplit );
130492     pSplit->pParent->pRight = pNew;
130493     pNew->pParent = pSplit->pParent;
130494   }else{
130495     *ppHead = pNew;
130496   }
130497   pNew->pLeft = pSplit;
130498   pSplit->pParent = pNew;
130499 }
130500 
130501 /*
130502 ** Parse the fts3 query expression found in buffer z, length n. This function
130503 ** returns either when the end of the buffer is reached or an unmatched 
130504 ** closing bracket - ')' - is encountered.
130505 **
130506 ** If successful, SQLITE_OK is returned, *ppExpr is set to point to the
130507 ** parsed form of the expression and *pnConsumed is set to the number of
130508 ** bytes read from buffer z. Otherwise, *ppExpr is set to 0 and SQLITE_NOMEM
130509 ** (out of memory error) or SQLITE_ERROR (parse error) is returned.
130510 */
130511 static int fts3ExprParse(
130512   ParseContext *pParse,                   /* fts3 query parse context */
130513   const char *z, int n,                   /* Text of MATCH query */
130514   Fts3Expr **ppExpr,                      /* OUT: Parsed query structure */
130515   int *pnConsumed                         /* OUT: Number of bytes consumed */
130516 ){
130517   Fts3Expr *pRet = 0;
130518   Fts3Expr *pPrev = 0;
130519   Fts3Expr *pNotBranch = 0;               /* Only used in legacy parse mode */
130520   int nIn = n;
130521   const char *zIn = z;
130522   int rc = SQLITE_OK;
130523   int isRequirePhrase = 1;
130524 
130525   while( rc==SQLITE_OK ){
130526     Fts3Expr *p = 0;
130527     int nByte = 0;
130528     rc = getNextNode(pParse, zIn, nIn, &p, &nByte);
130529     if( rc==SQLITE_OK ){
130530       int isPhrase;
130531 
130532       if( !sqlite3_fts3_enable_parentheses 
130533        && p->eType==FTSQUERY_PHRASE && pParse->isNot 
130534       ){
130535         /* Create an implicit NOT operator. */
130536         Fts3Expr *pNot = fts3MallocZero(sizeof(Fts3Expr));
130537         if( !pNot ){
130538           sqlite3Fts3ExprFree(p);
130539           rc = SQLITE_NOMEM;
130540           goto exprparse_out;
130541         }
130542         pNot->eType = FTSQUERY_NOT;
130543         pNot->pRight = p;
130544         p->pParent = pNot;
130545         if( pNotBranch ){
130546           pNot->pLeft = pNotBranch;
130547           pNotBranch->pParent = pNot;
130548         }
130549         pNotBranch = pNot;
130550         p = pPrev;
130551       }else{
130552         int eType = p->eType;
130553         isPhrase = (eType==FTSQUERY_PHRASE || p->pLeft);
130554 
130555         /* The isRequirePhrase variable is set to true if a phrase or
130556         ** an expression contained in parenthesis is required. If a
130557         ** binary operator (AND, OR, NOT or NEAR) is encounted when
130558         ** isRequirePhrase is set, this is a syntax error.
130559         */
130560         if( !isPhrase && isRequirePhrase ){
130561           sqlite3Fts3ExprFree(p);
130562           rc = SQLITE_ERROR;
130563           goto exprparse_out;
130564         }
130565   
130566         if( isPhrase && !isRequirePhrase ){
130567           /* Insert an implicit AND operator. */
130568           Fts3Expr *pAnd;
130569           assert( pRet && pPrev );
130570           pAnd = fts3MallocZero(sizeof(Fts3Expr));
130571           if( !pAnd ){
130572             sqlite3Fts3ExprFree(p);
130573             rc = SQLITE_NOMEM;
130574             goto exprparse_out;
130575           }
130576           pAnd->eType = FTSQUERY_AND;
130577           insertBinaryOperator(&pRet, pPrev, pAnd);
130578           pPrev = pAnd;
130579         }
130580 
130581         /* This test catches attempts to make either operand of a NEAR
130582         ** operator something other than a phrase. For example, either of
130583         ** the following:
130584         **
130585         **    (bracketed expression) NEAR phrase
130586         **    phrase NEAR (bracketed expression)
130587         **
130588         ** Return an error in either case.
130589         */
130590         if( pPrev && (
130591             (eType==FTSQUERY_NEAR && !isPhrase && pPrev->eType!=FTSQUERY_PHRASE)
130592          || (eType!=FTSQUERY_PHRASE && isPhrase && pPrev->eType==FTSQUERY_NEAR)
130593         )){
130594           sqlite3Fts3ExprFree(p);
130595           rc = SQLITE_ERROR;
130596           goto exprparse_out;
130597         }
130598   
130599         if( isPhrase ){
130600           if( pRet ){
130601             assert( pPrev && pPrev->pLeft && pPrev->pRight==0 );
130602             pPrev->pRight = p;
130603             p->pParent = pPrev;
130604           }else{
130605             pRet = p;
130606           }
130607         }else{
130608           insertBinaryOperator(&pRet, pPrev, p);
130609         }
130610         isRequirePhrase = !isPhrase;
130611       }
130612       assert( nByte>0 );
130613     }
130614     assert( rc!=SQLITE_OK || (nByte>0 && nByte<=nIn) );
130615     nIn -= nByte;
130616     zIn += nByte;
130617     pPrev = p;
130618   }
130619 
130620   if( rc==SQLITE_DONE && pRet && isRequirePhrase ){
130621     rc = SQLITE_ERROR;
130622   }
130623 
130624   if( rc==SQLITE_DONE ){
130625     rc = SQLITE_OK;
130626     if( !sqlite3_fts3_enable_parentheses && pNotBranch ){
130627       if( !pRet ){
130628         rc = SQLITE_ERROR;
130629       }else{
130630         Fts3Expr *pIter = pNotBranch;
130631         while( pIter->pLeft ){
130632           pIter = pIter->pLeft;
130633         }
130634         pIter->pLeft = pRet;
130635         pRet->pParent = pIter;
130636         pRet = pNotBranch;
130637       }
130638     }
130639   }
130640   *pnConsumed = n - nIn;
130641 
130642 exprparse_out:
130643   if( rc!=SQLITE_OK ){
130644     sqlite3Fts3ExprFree(pRet);
130645     sqlite3Fts3ExprFree(pNotBranch);
130646     pRet = 0;
130647   }
130648   *ppExpr = pRet;
130649   return rc;
130650 }
130651 
130652 /*
130653 ** Return SQLITE_ERROR if the maximum depth of the expression tree passed 
130654 ** as the only argument is more than nMaxDepth.
130655 */
130656 static int fts3ExprCheckDepth(Fts3Expr *p, int nMaxDepth){
130657   int rc = SQLITE_OK;
130658   if( p ){
130659     if( nMaxDepth<0 ){ 
130660       rc = SQLITE_TOOBIG;
130661     }else{
130662       rc = fts3ExprCheckDepth(p->pLeft, nMaxDepth-1);
130663       if( rc==SQLITE_OK ){
130664         rc = fts3ExprCheckDepth(p->pRight, nMaxDepth-1);
130665       }
130666     }
130667   }
130668   return rc;
130669 }
130670 
130671 /*
130672 ** This function attempts to transform the expression tree at (*pp) to
130673 ** an equivalent but more balanced form. The tree is modified in place.
130674 ** If successful, SQLITE_OK is returned and (*pp) set to point to the 
130675 ** new root expression node. 
130676 **
130677 ** nMaxDepth is the maximum allowable depth of the balanced sub-tree.
130678 **
130679 ** Otherwise, if an error occurs, an SQLite error code is returned and 
130680 ** expression (*pp) freed.
130681 */
130682 static int fts3ExprBalance(Fts3Expr **pp, int nMaxDepth){
130683   int rc = SQLITE_OK;             /* Return code */
130684   Fts3Expr *pRoot = *pp;          /* Initial root node */
130685   Fts3Expr *pFree = 0;            /* List of free nodes. Linked by pParent. */
130686   int eType = pRoot->eType;       /* Type of node in this tree */
130687 
130688   if( nMaxDepth==0 ){
130689     rc = SQLITE_ERROR;
130690   }
130691 
130692   if( rc==SQLITE_OK && (eType==FTSQUERY_AND || eType==FTSQUERY_OR) ){
130693     Fts3Expr **apLeaf;
130694     apLeaf = (Fts3Expr **)sqlite3_malloc(sizeof(Fts3Expr *) * nMaxDepth);
130695     if( 0==apLeaf ){
130696       rc = SQLITE_NOMEM;
130697     }else{
130698       memset(apLeaf, 0, sizeof(Fts3Expr *) * nMaxDepth);
130699     }
130700 
130701     if( rc==SQLITE_OK ){
130702       int i;
130703       Fts3Expr *p;
130704 
130705       /* Set $p to point to the left-most leaf in the tree of eType nodes. */
130706       for(p=pRoot; p->eType==eType; p=p->pLeft){
130707         assert( p->pParent==0 || p->pParent->pLeft==p );
130708         assert( p->pLeft && p->pRight );
130709       }
130710 
130711       /* This loop runs once for each leaf in the tree of eType nodes. */
130712       while( 1 ){
130713         int iLvl;
130714         Fts3Expr *pParent = p->pParent;     /* Current parent of p */
130715 
130716         assert( pParent==0 || pParent->pLeft==p );
130717         p->pParent = 0;
130718         if( pParent ){
130719           pParent->pLeft = 0;
130720         }else{
130721           pRoot = 0;
130722         }
130723         rc = fts3ExprBalance(&p, nMaxDepth-1);
130724         if( rc!=SQLITE_OK ) break;
130725 
130726         for(iLvl=0; p && iLvl<nMaxDepth; iLvl++){
130727           if( apLeaf[iLvl]==0 ){
130728             apLeaf[iLvl] = p;
130729             p = 0;
130730           }else{
130731             assert( pFree );
130732             pFree->pLeft = apLeaf[iLvl];
130733             pFree->pRight = p;
130734             pFree->pLeft->pParent = pFree;
130735             pFree->pRight->pParent = pFree;
130736 
130737             p = pFree;
130738             pFree = pFree->pParent;
130739             p->pParent = 0;
130740             apLeaf[iLvl] = 0;
130741           }
130742         }
130743         if( p ){
130744           sqlite3Fts3ExprFree(p);
130745           rc = SQLITE_TOOBIG;
130746           break;
130747         }
130748 
130749         /* If that was the last leaf node, break out of the loop */
130750         if( pParent==0 ) break;
130751 
130752         /* Set $p to point to the next leaf in the tree of eType nodes */
130753         for(p=pParent->pRight; p->eType==eType; p=p->pLeft);
130754 
130755         /* Remove pParent from the original tree. */
130756         assert( pParent->pParent==0 || pParent->pParent->pLeft==pParent );
130757         pParent->pRight->pParent = pParent->pParent;
130758         if( pParent->pParent ){
130759           pParent->pParent->pLeft = pParent->pRight;
130760         }else{
130761           assert( pParent==pRoot );
130762           pRoot = pParent->pRight;
130763         }
130764 
130765         /* Link pParent into the free node list. It will be used as an
130766         ** internal node of the new tree.  */
130767         pParent->pParent = pFree;
130768         pFree = pParent;
130769       }
130770 
130771       if( rc==SQLITE_OK ){
130772         p = 0;
130773         for(i=0; i<nMaxDepth; i++){
130774           if( apLeaf[i] ){
130775             if( p==0 ){
130776               p = apLeaf[i];
130777               p->pParent = 0;
130778             }else{
130779               assert( pFree!=0 );
130780               pFree->pRight = p;
130781               pFree->pLeft = apLeaf[i];
130782               pFree->pLeft->pParent = pFree;
130783               pFree->pRight->pParent = pFree;
130784 
130785               p = pFree;
130786               pFree = pFree->pParent;
130787               p->pParent = 0;
130788             }
130789           }
130790         }
130791         pRoot = p;
130792       }else{
130793         /* An error occurred. Delete the contents of the apLeaf[] array 
130794         ** and pFree list. Everything else is cleaned up by the call to
130795         ** sqlite3Fts3ExprFree(pRoot) below.  */
130796         Fts3Expr *pDel;
130797         for(i=0; i<nMaxDepth; i++){
130798           sqlite3Fts3ExprFree(apLeaf[i]);
130799         }
130800         while( (pDel=pFree)!=0 ){
130801           pFree = pDel->pParent;
130802           sqlite3_free(pDel);
130803         }
130804       }
130805 
130806       assert( pFree==0 );
130807       sqlite3_free( apLeaf );
130808     }
130809   }
130810 
130811   if( rc!=SQLITE_OK ){
130812     sqlite3Fts3ExprFree(pRoot);
130813     pRoot = 0;
130814   }
130815   *pp = pRoot;
130816   return rc;
130817 }
130818 
130819 /*
130820 ** This function is similar to sqlite3Fts3ExprParse(), with the following
130821 ** differences:
130822 **
130823 **   1. It does not do expression rebalancing.
130824 **   2. It does not check that the expression does not exceed the 
130825 **      maximum allowable depth.
130826 **   3. Even if it fails, *ppExpr may still be set to point to an 
130827 **      expression tree. It should be deleted using sqlite3Fts3ExprFree()
130828 **      in this case.
130829 */
130830 static int fts3ExprParseUnbalanced(
130831   sqlite3_tokenizer *pTokenizer,      /* Tokenizer module */
130832   int iLangid,                        /* Language id for tokenizer */
130833   char **azCol,                       /* Array of column names for fts3 table */
130834   int bFts4,                          /* True to allow FTS4-only syntax */
130835   int nCol,                           /* Number of entries in azCol[] */
130836   int iDefaultCol,                    /* Default column to query */
130837   const char *z, int n,               /* Text of MATCH query */
130838   Fts3Expr **ppExpr                   /* OUT: Parsed query structure */
130839 ){
130840   int nParsed;
130841   int rc;
130842   ParseContext sParse;
130843 
130844   memset(&sParse, 0, sizeof(ParseContext));
130845   sParse.pTokenizer = pTokenizer;
130846   sParse.iLangid = iLangid;
130847   sParse.azCol = (const char **)azCol;
130848   sParse.nCol = nCol;
130849   sParse.iDefaultCol = iDefaultCol;
130850   sParse.bFts4 = bFts4;
130851   if( z==0 ){
130852     *ppExpr = 0;
130853     return SQLITE_OK;
130854   }
130855   if( n<0 ){
130856     n = (int)strlen(z);
130857   }
130858   rc = fts3ExprParse(&sParse, z, n, ppExpr, &nParsed);
130859   assert( rc==SQLITE_OK || *ppExpr==0 );
130860 
130861   /* Check for mismatched parenthesis */
130862   if( rc==SQLITE_OK && sParse.nNest ){
130863     rc = SQLITE_ERROR;
130864   }
130865   
130866   return rc;
130867 }
130868 
130869 /*
130870 ** Parameters z and n contain a pointer to and length of a buffer containing
130871 ** an fts3 query expression, respectively. This function attempts to parse the
130872 ** query expression and create a tree of Fts3Expr structures representing the
130873 ** parsed expression. If successful, *ppExpr is set to point to the head
130874 ** of the parsed expression tree and SQLITE_OK is returned. If an error
130875 ** occurs, either SQLITE_NOMEM (out-of-memory error) or SQLITE_ERROR (parse
130876 ** error) is returned and *ppExpr is set to 0.
130877 **
130878 ** If parameter n is a negative number, then z is assumed to point to a
130879 ** nul-terminated string and the length is determined using strlen().
130880 **
130881 ** The first parameter, pTokenizer, is passed the fts3 tokenizer module to
130882 ** use to normalize query tokens while parsing the expression. The azCol[]
130883 ** array, which is assumed to contain nCol entries, should contain the names
130884 ** of each column in the target fts3 table, in order from left to right. 
130885 ** Column names must be nul-terminated strings.
130886 **
130887 ** The iDefaultCol parameter should be passed the index of the table column
130888 ** that appears on the left-hand-side of the MATCH operator (the default
130889 ** column to match against for tokens for which a column name is not explicitly
130890 ** specified as part of the query string), or -1 if tokens may by default
130891 ** match any table column.
130892 */
130893 SQLITE_PRIVATE int sqlite3Fts3ExprParse(
130894   sqlite3_tokenizer *pTokenizer,      /* Tokenizer module */
130895   int iLangid,                        /* Language id for tokenizer */
130896   char **azCol,                       /* Array of column names for fts3 table */
130897   int bFts4,                          /* True to allow FTS4-only syntax */
130898   int nCol,                           /* Number of entries in azCol[] */
130899   int iDefaultCol,                    /* Default column to query */
130900   const char *z, int n,               /* Text of MATCH query */
130901   Fts3Expr **ppExpr,                  /* OUT: Parsed query structure */
130902   char **pzErr                        /* OUT: Error message (sqlite3_malloc) */
130903 ){
130904   int rc = fts3ExprParseUnbalanced(
130905       pTokenizer, iLangid, azCol, bFts4, nCol, iDefaultCol, z, n, ppExpr
130906   );
130907   
130908   /* Rebalance the expression. And check that its depth does not exceed
130909   ** SQLITE_FTS3_MAX_EXPR_DEPTH.  */
130910   if( rc==SQLITE_OK && *ppExpr ){
130911     rc = fts3ExprBalance(ppExpr, SQLITE_FTS3_MAX_EXPR_DEPTH);
130912     if( rc==SQLITE_OK ){
130913       rc = fts3ExprCheckDepth(*ppExpr, SQLITE_FTS3_MAX_EXPR_DEPTH);
130914     }
130915   }
130916 
130917   if( rc!=SQLITE_OK ){
130918     sqlite3Fts3ExprFree(*ppExpr);
130919     *ppExpr = 0;
130920     if( rc==SQLITE_TOOBIG ){
130921       *pzErr = sqlite3_mprintf(
130922           "FTS expression tree is too large (maximum depth %d)", 
130923           SQLITE_FTS3_MAX_EXPR_DEPTH
130924       );
130925       rc = SQLITE_ERROR;
130926     }else if( rc==SQLITE_ERROR ){
130927       *pzErr = sqlite3_mprintf("malformed MATCH expression: [%s]", z);
130928     }
130929   }
130930 
130931   return rc;
130932 }
130933 
130934 /*
130935 ** Free a single node of an expression tree.
130936 */
130937 static void fts3FreeExprNode(Fts3Expr *p){
130938   assert( p->eType==FTSQUERY_PHRASE || p->pPhrase==0 );
130939   sqlite3Fts3EvalPhraseCleanup(p->pPhrase);
130940   sqlite3_free(p->aMI);
130941   sqlite3_free(p);
130942 }
130943 
130944 /*
130945 ** Free a parsed fts3 query expression allocated by sqlite3Fts3ExprParse().
130946 **
130947 ** This function would be simpler if it recursively called itself. But
130948 ** that would mean passing a sufficiently large expression to ExprParse()
130949 ** could cause a stack overflow.
130950 */
130951 SQLITE_PRIVATE void sqlite3Fts3ExprFree(Fts3Expr *pDel){
130952   Fts3Expr *p;
130953   assert( pDel==0 || pDel->pParent==0 );
130954   for(p=pDel; p && (p->pLeft||p->pRight); p=(p->pLeft ? p->pLeft : p->pRight)){
130955     assert( p->pParent==0 || p==p->pParent->pRight || p==p->pParent->pLeft );
130956   }
130957   while( p ){
130958     Fts3Expr *pParent = p->pParent;
130959     fts3FreeExprNode(p);
130960     if( pParent && p==pParent->pLeft && pParent->pRight ){
130961       p = pParent->pRight;
130962       while( p && (p->pLeft || p->pRight) ){
130963         assert( p==p->pParent->pRight || p==p->pParent->pLeft );
130964         p = (p->pLeft ? p->pLeft : p->pRight);
130965       }
130966     }else{
130967       p = pParent;
130968     }
130969   }
130970 }
130971 
130972 /****************************************************************************
130973 *****************************************************************************
130974 ** Everything after this point is just test code.
130975 */
130976 
130977 #ifdef SQLITE_TEST
130978 
130979 /* #include <stdio.h> */
130980 
130981 /*
130982 ** Function to query the hash-table of tokenizers (see README.tokenizers).
130983 */
130984 static int queryTestTokenizer(
130985   sqlite3 *db, 
130986   const char *zName,  
130987   const sqlite3_tokenizer_module **pp
130988 ){
130989   int rc;
130990   sqlite3_stmt *pStmt;
130991   const char zSql[] = "SELECT fts3_tokenizer(?)";
130992 
130993   *pp = 0;
130994   rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);
130995   if( rc!=SQLITE_OK ){
130996     return rc;
130997   }
130998 
130999   sqlite3_bind_text(pStmt, 1, zName, -1, SQLITE_STATIC);
131000   if( SQLITE_ROW==sqlite3_step(pStmt) ){
131001     if( sqlite3_column_type(pStmt, 0)==SQLITE_BLOB ){
131002       memcpy((void *)pp, sqlite3_column_blob(pStmt, 0), sizeof(*pp));
131003     }
131004   }
131005 
131006   return sqlite3_finalize(pStmt);
131007 }
131008 
131009 /*
131010 ** Return a pointer to a buffer containing a text representation of the
131011 ** expression passed as the first argument. The buffer is obtained from
131012 ** sqlite3_malloc(). It is the responsibility of the caller to use 
131013 ** sqlite3_free() to release the memory. If an OOM condition is encountered,
131014 ** NULL is returned.
131015 **
131016 ** If the second argument is not NULL, then its contents are prepended to 
131017 ** the returned expression text and then freed using sqlite3_free().
131018 */
131019 static char *exprToString(Fts3Expr *pExpr, char *zBuf){
131020   if( pExpr==0 ){
131021     return sqlite3_mprintf("");
131022   }
131023   switch( pExpr->eType ){
131024     case FTSQUERY_PHRASE: {
131025       Fts3Phrase *pPhrase = pExpr->pPhrase;
131026       int i;
131027       zBuf = sqlite3_mprintf(
131028           "%zPHRASE %d 0", zBuf, pPhrase->iColumn);
131029       for(i=0; zBuf && i<pPhrase->nToken; i++){
131030         zBuf = sqlite3_mprintf("%z %.*s%s", zBuf, 
131031             pPhrase->aToken[i].n, pPhrase->aToken[i].z,
131032             (pPhrase->aToken[i].isPrefix?"+":"")
131033         );
131034       }
131035       return zBuf;
131036     }
131037 
131038     case FTSQUERY_NEAR:
131039       zBuf = sqlite3_mprintf("%zNEAR/%d ", zBuf, pExpr->nNear);
131040       break;
131041     case FTSQUERY_NOT:
131042       zBuf = sqlite3_mprintf("%zNOT ", zBuf);
131043       break;
131044     case FTSQUERY_AND:
131045       zBuf = sqlite3_mprintf("%zAND ", zBuf);
131046       break;
131047     case FTSQUERY_OR:
131048       zBuf = sqlite3_mprintf("%zOR ", zBuf);
131049       break;
131050   }
131051 
131052   if( zBuf ) zBuf = sqlite3_mprintf("%z{", zBuf);
131053   if( zBuf ) zBuf = exprToString(pExpr->pLeft, zBuf);
131054   if( zBuf ) zBuf = sqlite3_mprintf("%z} {", zBuf);
131055 
131056   if( zBuf ) zBuf = exprToString(pExpr->pRight, zBuf);
131057   if( zBuf ) zBuf = sqlite3_mprintf("%z}", zBuf);
131058 
131059   return zBuf;
131060 }
131061 
131062 /*
131063 ** This is the implementation of a scalar SQL function used to test the 
131064 ** expression parser. It should be called as follows:
131065 **
131066 **   fts3_exprtest(<tokenizer>, <expr>, <column 1>, ...);
131067 **
131068 ** The first argument, <tokenizer>, is the name of the fts3 tokenizer used
131069 ** to parse the query expression (see README.tokenizers). The second argument
131070 ** is the query expression to parse. Each subsequent argument is the name
131071 ** of a column of the fts3 table that the query expression may refer to.
131072 ** For example:
131073 **
131074 **   SELECT fts3_exprtest('simple', 'Bill col2:Bloggs', 'col1', 'col2');
131075 */
131076 static void fts3ExprTest(
131077   sqlite3_context *context,
131078   int argc,
131079   sqlite3_value **argv
131080 ){
131081   sqlite3_tokenizer_module const *pModule = 0;
131082   sqlite3_tokenizer *pTokenizer = 0;
131083   int rc;
131084   char **azCol = 0;
131085   const char *zExpr;
131086   int nExpr;
131087   int nCol;
131088   int ii;
131089   Fts3Expr *pExpr;
131090   char *zBuf = 0;
131091   sqlite3 *db = sqlite3_context_db_handle(context);
131092 
131093   if( argc<3 ){
131094     sqlite3_result_error(context, 
131095         "Usage: fts3_exprtest(tokenizer, expr, col1, ...", -1
131096     );
131097     return;
131098   }
131099 
131100   rc = queryTestTokenizer(db,
131101                           (const char *)sqlite3_value_text(argv[0]), &pModule);
131102   if( rc==SQLITE_NOMEM ){
131103     sqlite3_result_error_nomem(context);
131104     goto exprtest_out;
131105   }else if( !pModule ){
131106     sqlite3_result_error(context, "No such tokenizer module", -1);
131107     goto exprtest_out;
131108   }
131109 
131110   rc = pModule->xCreate(0, 0, &pTokenizer);
131111   assert( rc==SQLITE_NOMEM || rc==SQLITE_OK );
131112   if( rc==SQLITE_NOMEM ){
131113     sqlite3_result_error_nomem(context);
131114     goto exprtest_out;
131115   }
131116   pTokenizer->pModule = pModule;
131117 
131118   zExpr = (const char *)sqlite3_value_text(argv[1]);
131119   nExpr = sqlite3_value_bytes(argv[1]);
131120   nCol = argc-2;
131121   azCol = (char **)sqlite3_malloc(nCol*sizeof(char *));
131122   if( !azCol ){
131123     sqlite3_result_error_nomem(context);
131124     goto exprtest_out;
131125   }
131126   for(ii=0; ii<nCol; ii++){
131127     azCol[ii] = (char *)sqlite3_value_text(argv[ii+2]);
131128   }
131129 
131130   if( sqlite3_user_data(context) ){
131131     char *zDummy = 0;
131132     rc = sqlite3Fts3ExprParse(
131133         pTokenizer, 0, azCol, 0, nCol, nCol, zExpr, nExpr, &pExpr, &zDummy
131134     );
131135     assert( rc==SQLITE_OK || pExpr==0 );
131136     sqlite3_free(zDummy);
131137   }else{
131138     rc = fts3ExprParseUnbalanced(
131139         pTokenizer, 0, azCol, 0, nCol, nCol, zExpr, nExpr, &pExpr
131140     );
131141   }
131142 
131143   if( rc!=SQLITE_OK && rc!=SQLITE_NOMEM ){
131144     sqlite3Fts3ExprFree(pExpr);
131145     sqlite3_result_error(context, "Error parsing expression", -1);
131146   }else if( rc==SQLITE_NOMEM || !(zBuf = exprToString(pExpr, 0)) ){
131147     sqlite3_result_error_nomem(context);
131148   }else{
131149     sqlite3_result_text(context, zBuf, -1, SQLITE_TRANSIENT);
131150     sqlite3_free(zBuf);
131151   }
131152 
131153   sqlite3Fts3ExprFree(pExpr);
131154 
131155 exprtest_out:
131156   if( pModule && pTokenizer ){
131157     rc = pModule->xDestroy(pTokenizer);
131158   }
131159   sqlite3_free(azCol);
131160 }
131161 
131162 /*
131163 ** Register the query expression parser test function fts3_exprtest() 
131164 ** with database connection db. 
131165 */
131166 SQLITE_PRIVATE int sqlite3Fts3ExprInitTestInterface(sqlite3* db){
131167   int rc = sqlite3_create_function(
131168       db, "fts3_exprtest", -1, SQLITE_UTF8, 0, fts3ExprTest, 0, 0
131169   );
131170   if( rc==SQLITE_OK ){
131171     rc = sqlite3_create_function(db, "fts3_exprtest_rebalance", 
131172         -1, SQLITE_UTF8, (void *)1, fts3ExprTest, 0, 0
131173     );
131174   }
131175   return rc;
131176 }
131177 
131178 #endif
131179 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
131180 
131181 /************** End of fts3_expr.c *******************************************/
131182 /************** Begin file fts3_hash.c ***************************************/
131183 /*
131184 ** 2001 September 22
131185 **
131186 ** The author disclaims copyright to this source code.  In place of
131187 ** a legal notice, here is a blessing:
131188 **
131189 **    May you do good and not evil.
131190 **    May you find forgiveness for yourself and forgive others.
131191 **    May you share freely, never taking more than you give.
131192 **
131193 *************************************************************************
131194 ** This is the implementation of generic hash-tables used in SQLite.
131195 ** We've modified it slightly to serve as a standalone hash table
131196 ** implementation for the full-text indexing module.
131197 */
131198 
131199 /*
131200 ** The code in this file is only compiled if:
131201 **
131202 **     * The FTS3 module is being built as an extension
131203 **       (in which case SQLITE_CORE is not defined), or
131204 **
131205 **     * The FTS3 module is being built into the core of
131206 **       SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
131207 */
131208 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
131209 
131210 /* #include <assert.h> */
131211 /* #include <stdlib.h> */
131212 /* #include <string.h> */
131213 
131214 
131215 /*
131216 ** Malloc and Free functions
131217 */
131218 static void *fts3HashMalloc(int n){
131219   void *p = sqlite3_malloc(n);
131220   if( p ){
131221     memset(p, 0, n);
131222   }
131223   return p;
131224 }
131225 static void fts3HashFree(void *p){
131226   sqlite3_free(p);
131227 }
131228 
131229 /* Turn bulk memory into a hash table object by initializing the
131230 ** fields of the Hash structure.
131231 **
131232 ** "pNew" is a pointer to the hash table that is to be initialized.
131233 ** keyClass is one of the constants 
131234 ** FTS3_HASH_BINARY or FTS3_HASH_STRING.  The value of keyClass 
131235 ** determines what kind of key the hash table will use.  "copyKey" is
131236 ** true if the hash table should make its own private copy of keys and
131237 ** false if it should just use the supplied pointer.
131238 */
131239 SQLITE_PRIVATE void sqlite3Fts3HashInit(Fts3Hash *pNew, char keyClass, char copyKey){
131240   assert( pNew!=0 );
131241   assert( keyClass>=FTS3_HASH_STRING && keyClass<=FTS3_HASH_BINARY );
131242   pNew->keyClass = keyClass;
131243   pNew->copyKey = copyKey;
131244   pNew->first = 0;
131245   pNew->count = 0;
131246   pNew->htsize = 0;
131247   pNew->ht = 0;
131248 }
131249 
131250 /* Remove all entries from a hash table.  Reclaim all memory.
131251 ** Call this routine to delete a hash table or to reset a hash table
131252 ** to the empty state.
131253 */
131254 SQLITE_PRIVATE void sqlite3Fts3HashClear(Fts3Hash *pH){
131255   Fts3HashElem *elem;         /* For looping over all elements of the table */
131256 
131257   assert( pH!=0 );
131258   elem = pH->first;
131259   pH->first = 0;
131260   fts3HashFree(pH->ht);
131261   pH->ht = 0;
131262   pH->htsize = 0;
131263   while( elem ){
131264     Fts3HashElem *next_elem = elem->next;
131265     if( pH->copyKey && elem->pKey ){
131266       fts3HashFree(elem->pKey);
131267     }
131268     fts3HashFree(elem);
131269     elem = next_elem;
131270   }
131271   pH->count = 0;
131272 }
131273 
131274 /*
131275 ** Hash and comparison functions when the mode is FTS3_HASH_STRING
131276 */
131277 static int fts3StrHash(const void *pKey, int nKey){
131278   const char *z = (const char *)pKey;
131279   int h = 0;
131280   if( nKey<=0 ) nKey = (int) strlen(z);
131281   while( nKey > 0  ){
131282     h = (h<<3) ^ h ^ *z++;
131283     nKey--;
131284   }
131285   return h & 0x7fffffff;
131286 }
131287 static int fts3StrCompare(const void *pKey1, int n1, const void *pKey2, int n2){
131288   if( n1!=n2 ) return 1;
131289   return strncmp((const char*)pKey1,(const char*)pKey2,n1);
131290 }
131291 
131292 /*
131293 ** Hash and comparison functions when the mode is FTS3_HASH_BINARY
131294 */
131295 static int fts3BinHash(const void *pKey, int nKey){
131296   int h = 0;
131297   const char *z = (const char *)pKey;
131298   while( nKey-- > 0 ){
131299     h = (h<<3) ^ h ^ *(z++);
131300   }
131301   return h & 0x7fffffff;
131302 }
131303 static int fts3BinCompare(const void *pKey1, int n1, const void *pKey2, int n2){
131304   if( n1!=n2 ) return 1;
131305   return memcmp(pKey1,pKey2,n1);
131306 }
131307 
131308 /*
131309 ** Return a pointer to the appropriate hash function given the key class.
131310 **
131311 ** The C syntax in this function definition may be unfamilar to some 
131312 ** programmers, so we provide the following additional explanation:
131313 **
131314 ** The name of the function is "ftsHashFunction".  The function takes a
131315 ** single parameter "keyClass".  The return value of ftsHashFunction()
131316 ** is a pointer to another function.  Specifically, the return value
131317 ** of ftsHashFunction() is a pointer to a function that takes two parameters
131318 ** with types "const void*" and "int" and returns an "int".
131319 */
131320 static int (*ftsHashFunction(int keyClass))(const void*,int){
131321   if( keyClass==FTS3_HASH_STRING ){
131322     return &fts3StrHash;
131323   }else{
131324     assert( keyClass==FTS3_HASH_BINARY );
131325     return &fts3BinHash;
131326   }
131327 }
131328 
131329 /*
131330 ** Return a pointer to the appropriate hash function given the key class.
131331 **
131332 ** For help in interpreted the obscure C code in the function definition,
131333 ** see the header comment on the previous function.
131334 */
131335 static int (*ftsCompareFunction(int keyClass))(const void*,int,const void*,int){
131336   if( keyClass==FTS3_HASH_STRING ){
131337     return &fts3StrCompare;
131338   }else{
131339     assert( keyClass==FTS3_HASH_BINARY );
131340     return &fts3BinCompare;
131341   }
131342 }
131343 
131344 /* Link an element into the hash table
131345 */
131346 static void fts3HashInsertElement(
131347   Fts3Hash *pH,            /* The complete hash table */
131348   struct _fts3ht *pEntry,  /* The entry into which pNew is inserted */
131349   Fts3HashElem *pNew       /* The element to be inserted */
131350 ){
131351   Fts3HashElem *pHead;     /* First element already in pEntry */
131352   pHead = pEntry->chain;
131353   if( pHead ){
131354     pNew->next = pHead;
131355     pNew->prev = pHead->prev;
131356     if( pHead->prev ){ pHead->prev->next = pNew; }
131357     else             { pH->first = pNew; }
131358     pHead->prev = pNew;
131359   }else{
131360     pNew->next = pH->first;
131361     if( pH->first ){ pH->first->prev = pNew; }
131362     pNew->prev = 0;
131363     pH->first = pNew;
131364   }
131365   pEntry->count++;
131366   pEntry->chain = pNew;
131367 }
131368 
131369 
131370 /* Resize the hash table so that it cantains "new_size" buckets.
131371 ** "new_size" must be a power of 2.  The hash table might fail 
131372 ** to resize if sqliteMalloc() fails.
131373 **
131374 ** Return non-zero if a memory allocation error occurs.
131375 */
131376 static int fts3Rehash(Fts3Hash *pH, int new_size){
131377   struct _fts3ht *new_ht;          /* The new hash table */
131378   Fts3HashElem *elem, *next_elem;  /* For looping over existing elements */
131379   int (*xHash)(const void*,int);   /* The hash function */
131380 
131381   assert( (new_size & (new_size-1))==0 );
131382   new_ht = (struct _fts3ht *)fts3HashMalloc( new_size*sizeof(struct _fts3ht) );
131383   if( new_ht==0 ) return 1;
131384   fts3HashFree(pH->ht);
131385   pH->ht = new_ht;
131386   pH->htsize = new_size;
131387   xHash = ftsHashFunction(pH->keyClass);
131388   for(elem=pH->first, pH->first=0; elem; elem = next_elem){
131389     int h = (*xHash)(elem->pKey, elem->nKey) & (new_size-1);
131390     next_elem = elem->next;
131391     fts3HashInsertElement(pH, &new_ht[h], elem);
131392   }
131393   return 0;
131394 }
131395 
131396 /* This function (for internal use only) locates an element in an
131397 ** hash table that matches the given key.  The hash for this key has
131398 ** already been computed and is passed as the 4th parameter.
131399 */
131400 static Fts3HashElem *fts3FindElementByHash(
131401   const Fts3Hash *pH, /* The pH to be searched */
131402   const void *pKey,   /* The key we are searching for */
131403   int nKey,
131404   int h               /* The hash for this key. */
131405 ){
131406   Fts3HashElem *elem;            /* Used to loop thru the element list */
131407   int count;                     /* Number of elements left to test */
131408   int (*xCompare)(const void*,int,const void*,int);  /* comparison function */
131409 
131410   if( pH->ht ){
131411     struct _fts3ht *pEntry = &pH->ht[h];
131412     elem = pEntry->chain;
131413     count = pEntry->count;
131414     xCompare = ftsCompareFunction(pH->keyClass);
131415     while( count-- && elem ){
131416       if( (*xCompare)(elem->pKey,elem->nKey,pKey,nKey)==0 ){ 
131417         return elem;
131418       }
131419       elem = elem->next;
131420     }
131421   }
131422   return 0;
131423 }
131424 
131425 /* Remove a single entry from the hash table given a pointer to that
131426 ** element and a hash on the element's key.
131427 */
131428 static void fts3RemoveElementByHash(
131429   Fts3Hash *pH,         /* The pH containing "elem" */
131430   Fts3HashElem* elem,   /* The element to be removed from the pH */
131431   int h                 /* Hash value for the element */
131432 ){
131433   struct _fts3ht *pEntry;
131434   if( elem->prev ){
131435     elem->prev->next = elem->next; 
131436   }else{
131437     pH->first = elem->next;
131438   }
131439   if( elem->next ){
131440     elem->next->prev = elem->prev;
131441   }
131442   pEntry = &pH->ht[h];
131443   if( pEntry->chain==elem ){
131444     pEntry->chain = elem->next;
131445   }
131446   pEntry->count--;
131447   if( pEntry->count<=0 ){
131448     pEntry->chain = 0;
131449   }
131450   if( pH->copyKey && elem->pKey ){
131451     fts3HashFree(elem->pKey);
131452   }
131453   fts3HashFree( elem );
131454   pH->count--;
131455   if( pH->count<=0 ){
131456     assert( pH->first==0 );
131457     assert( pH->count==0 );
131458     fts3HashClear(pH);
131459   }
131460 }
131461 
131462 SQLITE_PRIVATE Fts3HashElem *sqlite3Fts3HashFindElem(
131463   const Fts3Hash *pH, 
131464   const void *pKey, 
131465   int nKey
131466 ){
131467   int h;                          /* A hash on key */
131468   int (*xHash)(const void*,int);  /* The hash function */
131469 
131470   if( pH==0 || pH->ht==0 ) return 0;
131471   xHash = ftsHashFunction(pH->keyClass);
131472   assert( xHash!=0 );
131473   h = (*xHash)(pKey,nKey);
131474   assert( (pH->htsize & (pH->htsize-1))==0 );
131475   return fts3FindElementByHash(pH,pKey,nKey, h & (pH->htsize-1));
131476 }
131477 
131478 /* 
131479 ** Attempt to locate an element of the hash table pH with a key
131480 ** that matches pKey,nKey.  Return the data for this element if it is
131481 ** found, or NULL if there is no match.
131482 */
131483 SQLITE_PRIVATE void *sqlite3Fts3HashFind(const Fts3Hash *pH, const void *pKey, int nKey){
131484   Fts3HashElem *pElem;            /* The element that matches key (if any) */
131485 
131486   pElem = sqlite3Fts3HashFindElem(pH, pKey, nKey);
131487   return pElem ? pElem->data : 0;
131488 }
131489 
131490 /* Insert an element into the hash table pH.  The key is pKey,nKey
131491 ** and the data is "data".
131492 **
131493 ** If no element exists with a matching key, then a new
131494 ** element is created.  A copy of the key is made if the copyKey
131495 ** flag is set.  NULL is returned.
131496 **
131497 ** If another element already exists with the same key, then the
131498 ** new data replaces the old data and the old data is returned.
131499 ** The key is not copied in this instance.  If a malloc fails, then
131500 ** the new data is returned and the hash table is unchanged.
131501 **
131502 ** If the "data" parameter to this function is NULL, then the
131503 ** element corresponding to "key" is removed from the hash table.
131504 */
131505 SQLITE_PRIVATE void *sqlite3Fts3HashInsert(
131506   Fts3Hash *pH,        /* The hash table to insert into */
131507   const void *pKey,    /* The key */
131508   int nKey,            /* Number of bytes in the key */
131509   void *data           /* The data */
131510 ){
131511   int hraw;                 /* Raw hash value of the key */
131512   int h;                    /* the hash of the key modulo hash table size */
131513   Fts3HashElem *elem;       /* Used to loop thru the element list */
131514   Fts3HashElem *new_elem;   /* New element added to the pH */
131515   int (*xHash)(const void*,int);  /* The hash function */
131516 
131517   assert( pH!=0 );
131518   xHash = ftsHashFunction(pH->keyClass);
131519   assert( xHash!=0 );
131520   hraw = (*xHash)(pKey, nKey);
131521   assert( (pH->htsize & (pH->htsize-1))==0 );
131522   h = hraw & (pH->htsize-1);
131523   elem = fts3FindElementByHash(pH,pKey,nKey,h);
131524   if( elem ){
131525     void *old_data = elem->data;
131526     if( data==0 ){
131527       fts3RemoveElementByHash(pH,elem,h);
131528     }else{
131529       elem->data = data;
131530     }
131531     return old_data;
131532   }
131533   if( data==0 ) return 0;
131534   if( (pH->htsize==0 && fts3Rehash(pH,8))
131535    || (pH->count>=pH->htsize && fts3Rehash(pH, pH->htsize*2))
131536   ){
131537     pH->count = 0;
131538     return data;
131539   }
131540   assert( pH->htsize>0 );
131541   new_elem = (Fts3HashElem*)fts3HashMalloc( sizeof(Fts3HashElem) );
131542   if( new_elem==0 ) return data;
131543   if( pH->copyKey && pKey!=0 ){
131544     new_elem->pKey = fts3HashMalloc( nKey );
131545     if( new_elem->pKey==0 ){
131546       fts3HashFree(new_elem);
131547       return data;
131548     }
131549     memcpy((void*)new_elem->pKey, pKey, nKey);
131550   }else{
131551     new_elem->pKey = (void*)pKey;
131552   }
131553   new_elem->nKey = nKey;
131554   pH->count++;
131555   assert( pH->htsize>0 );
131556   assert( (pH->htsize & (pH->htsize-1))==0 );
131557   h = hraw & (pH->htsize-1);
131558   fts3HashInsertElement(pH, &pH->ht[h], new_elem);
131559   new_elem->data = data;
131560   return 0;
131561 }
131562 
131563 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
131564 
131565 /************** End of fts3_hash.c *******************************************/
131566 /************** Begin file fts3_porter.c *************************************/
131567 /*
131568 ** 2006 September 30
131569 **
131570 ** The author disclaims copyright to this source code.  In place of
131571 ** a legal notice, here is a blessing:
131572 **
131573 **    May you do good and not evil.
131574 **    May you find forgiveness for yourself and forgive others.
131575 **    May you share freely, never taking more than you give.
131576 **
131577 *************************************************************************
131578 ** Implementation of the full-text-search tokenizer that implements
131579 ** a Porter stemmer.
131580 */
131581 
131582 /*
131583 ** The code in this file is only compiled if:
131584 **
131585 **     * The FTS3 module is being built as an extension
131586 **       (in which case SQLITE_CORE is not defined), or
131587 **
131588 **     * The FTS3 module is being built into the core of
131589 **       SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
131590 */
131591 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
131592 
131593 /* #include <assert.h> */
131594 /* #include <stdlib.h> */
131595 /* #include <stdio.h> */
131596 /* #include <string.h> */
131597 
131598 
131599 /*
131600 ** Class derived from sqlite3_tokenizer
131601 */
131602 typedef struct porter_tokenizer {
131603   sqlite3_tokenizer base;      /* Base class */
131604 } porter_tokenizer;
131605 
131606 /*
131607 ** Class derived from sqlite3_tokenizer_cursor
131608 */
131609 typedef struct porter_tokenizer_cursor {
131610   sqlite3_tokenizer_cursor base;
131611   const char *zInput;          /* input we are tokenizing */
131612   int nInput;                  /* size of the input */
131613   int iOffset;                 /* current position in zInput */
131614   int iToken;                  /* index of next token to be returned */
131615   char *zToken;                /* storage for current token */
131616   int nAllocated;              /* space allocated to zToken buffer */
131617 } porter_tokenizer_cursor;
131618 
131619 
131620 /*
131621 ** Create a new tokenizer instance.
131622 */
131623 static int porterCreate(
131624   int argc, const char * const *argv,
131625   sqlite3_tokenizer **ppTokenizer
131626 ){
131627   porter_tokenizer *t;
131628 
131629   UNUSED_PARAMETER(argc);
131630   UNUSED_PARAMETER(argv);
131631 
131632   t = (porter_tokenizer *) sqlite3_malloc(sizeof(*t));
131633   if( t==NULL ) return SQLITE_NOMEM;
131634   memset(t, 0, sizeof(*t));
131635   *ppTokenizer = &t->base;
131636   return SQLITE_OK;
131637 }
131638 
131639 /*
131640 ** Destroy a tokenizer
131641 */
131642 static int porterDestroy(sqlite3_tokenizer *pTokenizer){
131643   sqlite3_free(pTokenizer);
131644   return SQLITE_OK;
131645 }
131646 
131647 /*
131648 ** Prepare to begin tokenizing a particular string.  The input
131649 ** string to be tokenized is zInput[0..nInput-1].  A cursor
131650 ** used to incrementally tokenize this string is returned in 
131651 ** *ppCursor.
131652 */
131653 static int porterOpen(
131654   sqlite3_tokenizer *pTokenizer,         /* The tokenizer */
131655   const char *zInput, int nInput,        /* String to be tokenized */
131656   sqlite3_tokenizer_cursor **ppCursor    /* OUT: Tokenization cursor */
131657 ){
131658   porter_tokenizer_cursor *c;
131659 
131660   UNUSED_PARAMETER(pTokenizer);
131661 
131662   c = (porter_tokenizer_cursor *) sqlite3_malloc(sizeof(*c));
131663   if( c==NULL ) return SQLITE_NOMEM;
131664 
131665   c->zInput = zInput;
131666   if( zInput==0 ){
131667     c->nInput = 0;
131668   }else if( nInput<0 ){
131669     c->nInput = (int)strlen(zInput);
131670   }else{
131671     c->nInput = nInput;
131672   }
131673   c->iOffset = 0;                 /* start tokenizing at the beginning */
131674   c->iToken = 0;
131675   c->zToken = NULL;               /* no space allocated, yet. */
131676   c->nAllocated = 0;
131677 
131678   *ppCursor = &c->base;
131679   return SQLITE_OK;
131680 }
131681 
131682 /*
131683 ** Close a tokenization cursor previously opened by a call to
131684 ** porterOpen() above.
131685 */
131686 static int porterClose(sqlite3_tokenizer_cursor *pCursor){
131687   porter_tokenizer_cursor *c = (porter_tokenizer_cursor *) pCursor;
131688   sqlite3_free(c->zToken);
131689   sqlite3_free(c);
131690   return SQLITE_OK;
131691 }
131692 /*
131693 ** Vowel or consonant
131694 */
131695 static const char cType[] = {
131696    0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 1, 0,
131697    1, 1, 1, 2, 1
131698 };
131699 
131700 /*
131701 ** isConsonant() and isVowel() determine if their first character in
131702 ** the string they point to is a consonant or a vowel, according
131703 ** to Porter ruls.  
131704 **
131705 ** A consonate is any letter other than 'a', 'e', 'i', 'o', or 'u'.
131706 ** 'Y' is a consonant unless it follows another consonant,
131707 ** in which case it is a vowel.
131708 **
131709 ** In these routine, the letters are in reverse order.  So the 'y' rule
131710 ** is that 'y' is a consonant unless it is followed by another
131711 ** consonent.
131712 */
131713 static int isVowel(const char*);
131714 static int isConsonant(const char *z){
131715   int j;
131716   char x = *z;
131717   if( x==0 ) return 0;
131718   assert( x>='a' && x<='z' );
131719   j = cType[x-'a'];
131720   if( j<2 ) return j;
131721   return z[1]==0 || isVowel(z + 1);
131722 }
131723 static int isVowel(const char *z){
131724   int j;
131725   char x = *z;
131726   if( x==0 ) return 0;
131727   assert( x>='a' && x<='z' );
131728   j = cType[x-'a'];
131729   if( j<2 ) return 1-j;
131730   return isConsonant(z + 1);
131731 }
131732 
131733 /*
131734 ** Let any sequence of one or more vowels be represented by V and let
131735 ** C be sequence of one or more consonants.  Then every word can be
131736 ** represented as:
131737 **
131738 **           [C] (VC){m} [V]
131739 **
131740 ** In prose:  A word is an optional consonant followed by zero or
131741 ** vowel-consonant pairs followed by an optional vowel.  "m" is the
131742 ** number of vowel consonant pairs.  This routine computes the value
131743 ** of m for the first i bytes of a word.
131744 **
131745 ** Return true if the m-value for z is 1 or more.  In other words,
131746 ** return true if z contains at least one vowel that is followed
131747 ** by a consonant.
131748 **
131749 ** In this routine z[] is in reverse order.  So we are really looking
131750 ** for an instance of of a consonant followed by a vowel.
131751 */
131752 static int m_gt_0(const char *z){
131753   while( isVowel(z) ){ z++; }
131754   if( *z==0 ) return 0;
131755   while( isConsonant(z) ){ z++; }
131756   return *z!=0;
131757 }
131758 
131759 /* Like mgt0 above except we are looking for a value of m which is
131760 ** exactly 1
131761 */
131762 static int m_eq_1(const char *z){
131763   while( isVowel(z) ){ z++; }
131764   if( *z==0 ) return 0;
131765   while( isConsonant(z) ){ z++; }
131766   if( *z==0 ) return 0;
131767   while( isVowel(z) ){ z++; }
131768   if( *z==0 ) return 1;
131769   while( isConsonant(z) ){ z++; }
131770   return *z==0;
131771 }
131772 
131773 /* Like mgt0 above except we are looking for a value of m>1 instead
131774 ** or m>0
131775 */
131776 static int m_gt_1(const char *z){
131777   while( isVowel(z) ){ z++; }
131778   if( *z==0 ) return 0;
131779   while( isConsonant(z) ){ z++; }
131780   if( *z==0 ) return 0;
131781   while( isVowel(z) ){ z++; }
131782   if( *z==0 ) return 0;
131783   while( isConsonant(z) ){ z++; }
131784   return *z!=0;
131785 }
131786 
131787 /*
131788 ** Return TRUE if there is a vowel anywhere within z[0..n-1]
131789 */
131790 static int hasVowel(const char *z){
131791   while( isConsonant(z) ){ z++; }
131792   return *z!=0;
131793 }
131794 
131795 /*
131796 ** Return TRUE if the word ends in a double consonant.
131797 **
131798 ** The text is reversed here. So we are really looking at
131799 ** the first two characters of z[].
131800 */
131801 static int doubleConsonant(const char *z){
131802   return isConsonant(z) && z[0]==z[1];
131803 }
131804 
131805 /*
131806 ** Return TRUE if the word ends with three letters which
131807 ** are consonant-vowel-consonent and where the final consonant
131808 ** is not 'w', 'x', or 'y'.
131809 **
131810 ** The word is reversed here.  So we are really checking the
131811 ** first three letters and the first one cannot be in [wxy].
131812 */
131813 static int star_oh(const char *z){
131814   return
131815     isConsonant(z) &&
131816     z[0]!='w' && z[0]!='x' && z[0]!='y' &&
131817     isVowel(z+1) &&
131818     isConsonant(z+2);
131819 }
131820 
131821 /*
131822 ** If the word ends with zFrom and xCond() is true for the stem
131823 ** of the word that preceeds the zFrom ending, then change the 
131824 ** ending to zTo.
131825 **
131826 ** The input word *pz and zFrom are both in reverse order.  zTo
131827 ** is in normal order. 
131828 **
131829 ** Return TRUE if zFrom matches.  Return FALSE if zFrom does not
131830 ** match.  Not that TRUE is returned even if xCond() fails and
131831 ** no substitution occurs.
131832 */
131833 static int stem(
131834   char **pz,             /* The word being stemmed (Reversed) */
131835   const char *zFrom,     /* If the ending matches this... (Reversed) */
131836   const char *zTo,       /* ... change the ending to this (not reversed) */
131837   int (*xCond)(const char*)   /* Condition that must be true */
131838 ){
131839   char *z = *pz;
131840   while( *zFrom && *zFrom==*z ){ z++; zFrom++; }
131841   if( *zFrom!=0 ) return 0;
131842   if( xCond && !xCond(z) ) return 1;
131843   while( *zTo ){
131844     *(--z) = *(zTo++);
131845   }
131846   *pz = z;
131847   return 1;
131848 }
131849 
131850 /*
131851 ** This is the fallback stemmer used when the porter stemmer is
131852 ** inappropriate.  The input word is copied into the output with
131853 ** US-ASCII case folding.  If the input word is too long (more
131854 ** than 20 bytes if it contains no digits or more than 6 bytes if
131855 ** it contains digits) then word is truncated to 20 or 6 bytes
131856 ** by taking 10 or 3 bytes from the beginning and end.
131857 */
131858 static void copy_stemmer(const char *zIn, int nIn, char *zOut, int *pnOut){
131859   int i, mx, j;
131860   int hasDigit = 0;
131861   for(i=0; i<nIn; i++){
131862     char c = zIn[i];
131863     if( c>='A' && c<='Z' ){
131864       zOut[i] = c - 'A' + 'a';
131865     }else{
131866       if( c>='0' && c<='9' ) hasDigit = 1;
131867       zOut[i] = c;
131868     }
131869   }
131870   mx = hasDigit ? 3 : 10;
131871   if( nIn>mx*2 ){
131872     for(j=mx, i=nIn-mx; i<nIn; i++, j++){
131873       zOut[j] = zOut[i];
131874     }
131875     i = j;
131876   }
131877   zOut[i] = 0;
131878   *pnOut = i;
131879 }
131880 
131881 
131882 /*
131883 ** Stem the input word zIn[0..nIn-1].  Store the output in zOut.
131884 ** zOut is at least big enough to hold nIn bytes.  Write the actual
131885 ** size of the output word (exclusive of the '\0' terminator) into *pnOut.
131886 **
131887 ** Any upper-case characters in the US-ASCII character set ([A-Z])
131888 ** are converted to lower case.  Upper-case UTF characters are
131889 ** unchanged.
131890 **
131891 ** Words that are longer than about 20 bytes are stemmed by retaining
131892 ** a few bytes from the beginning and the end of the word.  If the
131893 ** word contains digits, 3 bytes are taken from the beginning and
131894 ** 3 bytes from the end.  For long words without digits, 10 bytes
131895 ** are taken from each end.  US-ASCII case folding still applies.
131896 ** 
131897 ** If the input word contains not digits but does characters not 
131898 ** in [a-zA-Z] then no stemming is attempted and this routine just 
131899 ** copies the input into the input into the output with US-ASCII
131900 ** case folding.
131901 **
131902 ** Stemming never increases the length of the word.  So there is
131903 ** no chance of overflowing the zOut buffer.
131904 */
131905 static void porter_stemmer(const char *zIn, int nIn, char *zOut, int *pnOut){
131906   int i, j;
131907   char zReverse[28];
131908   char *z, *z2;
131909   if( nIn<3 || nIn>=(int)sizeof(zReverse)-7 ){
131910     /* The word is too big or too small for the porter stemmer.
131911     ** Fallback to the copy stemmer */
131912     copy_stemmer(zIn, nIn, zOut, pnOut);
131913     return;
131914   }
131915   for(i=0, j=sizeof(zReverse)-6; i<nIn; i++, j--){
131916     char c = zIn[i];
131917     if( c>='A' && c<='Z' ){
131918       zReverse[j] = c + 'a' - 'A';
131919     }else if( c>='a' && c<='z' ){
131920       zReverse[j] = c;
131921     }else{
131922       /* The use of a character not in [a-zA-Z] means that we fallback
131923       ** to the copy stemmer */
131924       copy_stemmer(zIn, nIn, zOut, pnOut);
131925       return;
131926     }
131927   }
131928   memset(&zReverse[sizeof(zReverse)-5], 0, 5);
131929   z = &zReverse[j+1];
131930 
131931 
131932   /* Step 1a */
131933   if( z[0]=='s' ){
131934     if(
131935      !stem(&z, "sess", "ss", 0) &&
131936      !stem(&z, "sei", "i", 0)  &&
131937      !stem(&z, "ss", "ss", 0)
131938     ){
131939       z++;
131940     }
131941   }
131942 
131943   /* Step 1b */  
131944   z2 = z;
131945   if( stem(&z, "dee", "ee", m_gt_0) ){
131946     /* Do nothing.  The work was all in the test */
131947   }else if( 
131948      (stem(&z, "gni", "", hasVowel) || stem(&z, "de", "", hasVowel))
131949       && z!=z2
131950   ){
131951      if( stem(&z, "ta", "ate", 0) ||
131952          stem(&z, "lb", "ble", 0) ||
131953          stem(&z, "zi", "ize", 0) ){
131954        /* Do nothing.  The work was all in the test */
131955      }else if( doubleConsonant(z) && (*z!='l' && *z!='s' && *z!='z') ){
131956        z++;
131957      }else if( m_eq_1(z) && star_oh(z) ){
131958        *(--z) = 'e';
131959      }
131960   }
131961 
131962   /* Step 1c */
131963   if( z[0]=='y' && hasVowel(z+1) ){
131964     z[0] = 'i';
131965   }
131966 
131967   /* Step 2 */
131968   switch( z[1] ){
131969    case 'a':
131970      stem(&z, "lanoita", "ate", m_gt_0) ||
131971      stem(&z, "lanoit", "tion", m_gt_0);
131972      break;
131973    case 'c':
131974      stem(&z, "icne", "ence", m_gt_0) ||
131975      stem(&z, "icna", "ance", m_gt_0);
131976      break;
131977    case 'e':
131978      stem(&z, "rezi", "ize", m_gt_0);
131979      break;
131980    case 'g':
131981      stem(&z, "igol", "log", m_gt_0);
131982      break;
131983    case 'l':
131984      stem(&z, "ilb", "ble", m_gt_0) ||
131985      stem(&z, "illa", "al", m_gt_0) ||
131986      stem(&z, "iltne", "ent", m_gt_0) ||
131987      stem(&z, "ile", "e", m_gt_0) ||
131988      stem(&z, "ilsuo", "ous", m_gt_0);
131989      break;
131990    case 'o':
131991      stem(&z, "noitazi", "ize", m_gt_0) ||
131992      stem(&z, "noita", "ate", m_gt_0) ||
131993      stem(&z, "rota", "ate", m_gt_0);
131994      break;
131995    case 's':
131996      stem(&z, "msila", "al", m_gt_0) ||
131997      stem(&z, "ssenevi", "ive", m_gt_0) ||
131998      stem(&z, "ssenluf", "ful", m_gt_0) ||
131999      stem(&z, "ssensuo", "ous", m_gt_0);
132000      break;
132001    case 't':
132002      stem(&z, "itila", "al", m_gt_0) ||
132003      stem(&z, "itivi", "ive", m_gt_0) ||
132004      stem(&z, "itilib", "ble", m_gt_0);
132005      break;
132006   }
132007 
132008   /* Step 3 */
132009   switch( z[0] ){
132010    case 'e':
132011      stem(&z, "etaci", "ic", m_gt_0) ||
132012      stem(&z, "evita", "", m_gt_0)   ||
132013      stem(&z, "ezila", "al", m_gt_0);
132014      break;
132015    case 'i':
132016      stem(&z, "itici", "ic", m_gt_0);
132017      break;
132018    case 'l':
132019      stem(&z, "laci", "ic", m_gt_0) ||
132020      stem(&z, "luf", "", m_gt_0);
132021      break;
132022    case 's':
132023      stem(&z, "ssen", "", m_gt_0);
132024      break;
132025   }
132026 
132027   /* Step 4 */
132028   switch( z[1] ){
132029    case 'a':
132030      if( z[0]=='l' && m_gt_1(z+2) ){
132031        z += 2;
132032      }
132033      break;
132034    case 'c':
132035      if( z[0]=='e' && z[2]=='n' && (z[3]=='a' || z[3]=='e')  && m_gt_1(z+4)  ){
132036        z += 4;
132037      }
132038      break;
132039    case 'e':
132040      if( z[0]=='r' && m_gt_1(z+2) ){
132041        z += 2;
132042      }
132043      break;
132044    case 'i':
132045      if( z[0]=='c' && m_gt_1(z+2) ){
132046        z += 2;
132047      }
132048      break;
132049    case 'l':
132050      if( z[0]=='e' && z[2]=='b' && (z[3]=='a' || z[3]=='i') && m_gt_1(z+4) ){
132051        z += 4;
132052      }
132053      break;
132054    case 'n':
132055      if( z[0]=='t' ){
132056        if( z[2]=='a' ){
132057          if( m_gt_1(z+3) ){
132058            z += 3;
132059          }
132060        }else if( z[2]=='e' ){
132061          stem(&z, "tneme", "", m_gt_1) ||
132062          stem(&z, "tnem", "", m_gt_1) ||
132063          stem(&z, "tne", "", m_gt_1);
132064        }
132065      }
132066      break;
132067    case 'o':
132068      if( z[0]=='u' ){
132069        if( m_gt_1(z+2) ){
132070          z += 2;
132071        }
132072      }else if( z[3]=='s' || z[3]=='t' ){
132073        stem(&z, "noi", "", m_gt_1);
132074      }
132075      break;
132076    case 's':
132077      if( z[0]=='m' && z[2]=='i' && m_gt_1(z+3) ){
132078        z += 3;
132079      }
132080      break;
132081    case 't':
132082      stem(&z, "eta", "", m_gt_1) ||
132083      stem(&z, "iti", "", m_gt_1);
132084      break;
132085    case 'u':
132086      if( z[0]=='s' && z[2]=='o' && m_gt_1(z+3) ){
132087        z += 3;
132088      }
132089      break;
132090    case 'v':
132091    case 'z':
132092      if( z[0]=='e' && z[2]=='i' && m_gt_1(z+3) ){
132093        z += 3;
132094      }
132095      break;
132096   }
132097 
132098   /* Step 5a */
132099   if( z[0]=='e' ){
132100     if( m_gt_1(z+1) ){
132101       z++;
132102     }else if( m_eq_1(z+1) && !star_oh(z+1) ){
132103       z++;
132104     }
132105   }
132106 
132107   /* Step 5b */
132108   if( m_gt_1(z) && z[0]=='l' && z[1]=='l' ){
132109     z++;
132110   }
132111 
132112   /* z[] is now the stemmed word in reverse order.  Flip it back
132113   ** around into forward order and return.
132114   */
132115   *pnOut = i = (int)strlen(z);
132116   zOut[i] = 0;
132117   while( *z ){
132118     zOut[--i] = *(z++);
132119   }
132120 }
132121 
132122 /*
132123 ** Characters that can be part of a token.  We assume any character
132124 ** whose value is greater than 0x80 (any UTF character) can be
132125 ** part of a token.  In other words, delimiters all must have
132126 ** values of 0x7f or lower.
132127 */
132128 static const char porterIdChar[] = {
132129 /* x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF */
132130     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0,  /* 3x */
132131     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,  /* 4x */
132132     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1,  /* 5x */
132133     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,  /* 6x */
132134     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0,  /* 7x */
132135 };
132136 #define isDelim(C) (((ch=C)&0x80)==0 && (ch<0x30 || !porterIdChar[ch-0x30]))
132137 
132138 /*
132139 ** Extract the next token from a tokenization cursor.  The cursor must
132140 ** have been opened by a prior call to porterOpen().
132141 */
132142 static int porterNext(
132143   sqlite3_tokenizer_cursor *pCursor,  /* Cursor returned by porterOpen */
132144   const char **pzToken,               /* OUT: *pzToken is the token text */
132145   int *pnBytes,                       /* OUT: Number of bytes in token */
132146   int *piStartOffset,                 /* OUT: Starting offset of token */
132147   int *piEndOffset,                   /* OUT: Ending offset of token */
132148   int *piPosition                     /* OUT: Position integer of token */
132149 ){
132150   porter_tokenizer_cursor *c = (porter_tokenizer_cursor *) pCursor;
132151   const char *z = c->zInput;
132152 
132153   while( c->iOffset<c->nInput ){
132154     int iStartOffset, ch;
132155 
132156     /* Scan past delimiter characters */
132157     while( c->iOffset<c->nInput && isDelim(z[c->iOffset]) ){
132158       c->iOffset++;
132159     }
132160 
132161     /* Count non-delimiter characters. */
132162     iStartOffset = c->iOffset;
132163     while( c->iOffset<c->nInput && !isDelim(z[c->iOffset]) ){
132164       c->iOffset++;
132165     }
132166 
132167     if( c->iOffset>iStartOffset ){
132168       int n = c->iOffset-iStartOffset;
132169       if( n>c->nAllocated ){
132170         char *pNew;
132171         c->nAllocated = n+20;
132172         pNew = sqlite3_realloc(c->zToken, c->nAllocated);
132173         if( !pNew ) return SQLITE_NOMEM;
132174         c->zToken = pNew;
132175       }
132176       porter_stemmer(&z[iStartOffset], n, c->zToken, pnBytes);
132177       *pzToken = c->zToken;
132178       *piStartOffset = iStartOffset;
132179       *piEndOffset = c->iOffset;
132180       *piPosition = c->iToken++;
132181       return SQLITE_OK;
132182     }
132183   }
132184   return SQLITE_DONE;
132185 }
132186 
132187 /*
132188 ** The set of routines that implement the porter-stemmer tokenizer
132189 */
132190 static const sqlite3_tokenizer_module porterTokenizerModule = {
132191   0,
132192   porterCreate,
132193   porterDestroy,
132194   porterOpen,
132195   porterClose,
132196   porterNext,
132197   0
132198 };
132199 
132200 /*
132201 ** Allocate a new porter tokenizer.  Return a pointer to the new
132202 ** tokenizer in *ppModule
132203 */
132204 SQLITE_PRIVATE void sqlite3Fts3PorterTokenizerModule(
132205   sqlite3_tokenizer_module const**ppModule
132206 ){
132207   *ppModule = &porterTokenizerModule;
132208 }
132209 
132210 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
132211 
132212 /************** End of fts3_porter.c *****************************************/
132213 /************** Begin file fts3_tokenizer.c **********************************/
132214 /*
132215 ** 2007 June 22
132216 **
132217 ** The author disclaims copyright to this source code.  In place of
132218 ** a legal notice, here is a blessing:
132219 **
132220 **    May you do good and not evil.
132221 **    May you find forgiveness for yourself and forgive others.
132222 **    May you share freely, never taking more than you give.
132223 **
132224 ******************************************************************************
132225 **
132226 ** This is part of an SQLite module implementing full-text search.
132227 ** This particular file implements the generic tokenizer interface.
132228 */
132229 
132230 /*
132231 ** The code in this file is only compiled if:
132232 **
132233 **     * The FTS3 module is being built as an extension
132234 **       (in which case SQLITE_CORE is not defined), or
132235 **
132236 **     * The FTS3 module is being built into the core of
132237 **       SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
132238 */
132239 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
132240 
132241 /* #include <assert.h> */
132242 /* #include <string.h> */
132243 
132244 /*
132245 ** Implementation of the SQL scalar function for accessing the underlying 
132246 ** hash table. This function may be called as follows:
132247 **
132248 **   SELECT <function-name>(<key-name>);
132249 **   SELECT <function-name>(<key-name>, <pointer>);
132250 **
132251 ** where <function-name> is the name passed as the second argument
132252 ** to the sqlite3Fts3InitHashTable() function (e.g. 'fts3_tokenizer').
132253 **
132254 ** If the <pointer> argument is specified, it must be a blob value
132255 ** containing a pointer to be stored as the hash data corresponding
132256 ** to the string <key-name>. If <pointer> is not specified, then
132257 ** the string <key-name> must already exist in the has table. Otherwise,
132258 ** an error is returned.
132259 **
132260 ** Whether or not the <pointer> argument is specified, the value returned
132261 ** is a blob containing the pointer stored as the hash data corresponding
132262 ** to string <key-name> (after the hash-table is updated, if applicable).
132263 */
132264 static void scalarFunc(
132265   sqlite3_context *context,
132266   int argc,
132267   sqlite3_value **argv
132268 ){
132269   Fts3Hash *pHash;
132270   void *pPtr = 0;
132271   const unsigned char *zName;
132272   int nName;
132273 
132274   assert( argc==1 || argc==2 );
132275 
132276   pHash = (Fts3Hash *)sqlite3_user_data(context);
132277 
132278   zName = sqlite3_value_text(argv[0]);
132279   nName = sqlite3_value_bytes(argv[0])+1;
132280 
132281   if( argc==2 ){
132282     void *pOld;
132283     int n = sqlite3_value_bytes(argv[1]);
132284     if( n!=sizeof(pPtr) ){
132285       sqlite3_result_error(context, "argument type mismatch", -1);
132286       return;
132287     }
132288     pPtr = *(void **)sqlite3_value_blob(argv[1]);
132289     pOld = sqlite3Fts3HashInsert(pHash, (void *)zName, nName, pPtr);
132290     if( pOld==pPtr ){
132291       sqlite3_result_error(context, "out of memory", -1);
132292       return;
132293     }
132294   }else{
132295     pPtr = sqlite3Fts3HashFind(pHash, zName, nName);
132296     if( !pPtr ){
132297       char *zErr = sqlite3_mprintf("unknown tokenizer: %s", zName);
132298       sqlite3_result_error(context, zErr, -1);
132299       sqlite3_free(zErr);
132300       return;
132301     }
132302   }
132303 
132304   sqlite3_result_blob(context, (void *)&pPtr, sizeof(pPtr), SQLITE_TRANSIENT);
132305 }
132306 
132307 SQLITE_PRIVATE int sqlite3Fts3IsIdChar(char c){
132308   static const char isFtsIdChar[] = {
132309       0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,  /* 0x */
132310       0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,  /* 1x */
132311       0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,  /* 2x */
132312       1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0,  /* 3x */
132313       0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,  /* 4x */
132314       1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1,  /* 5x */
132315       0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,  /* 6x */
132316       1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0,  /* 7x */
132317   };
132318   return (c&0x80 || isFtsIdChar[(int)(c)]);
132319 }
132320 
132321 SQLITE_PRIVATE const char *sqlite3Fts3NextToken(const char *zStr, int *pn){
132322   const char *z1;
132323   const char *z2 = 0;
132324 
132325   /* Find the start of the next token. */
132326   z1 = zStr;
132327   while( z2==0 ){
132328     char c = *z1;
132329     switch( c ){
132330       case '\0': return 0;        /* No more tokens here */
132331       case '\'':
132332       case '"':
132333       case '`': {
132334         z2 = z1;
132335         while( *++z2 && (*z2!=c || *++z2==c) );
132336         break;
132337       }
132338       case '[':
132339         z2 = &z1[1];
132340         while( *z2 && z2[0]!=']' ) z2++;
132341         if( *z2 ) z2++;
132342         break;
132343 
132344       default:
132345         if( sqlite3Fts3IsIdChar(*z1) ){
132346           z2 = &z1[1];
132347           while( sqlite3Fts3IsIdChar(*z2) ) z2++;
132348         }else{
132349           z1++;
132350         }
132351     }
132352   }
132353 
132354   *pn = (int)(z2-z1);
132355   return z1;
132356 }
132357 
132358 SQLITE_PRIVATE int sqlite3Fts3InitTokenizer(
132359   Fts3Hash *pHash,                /* Tokenizer hash table */
132360   const char *zArg,               /* Tokenizer name */
132361   sqlite3_tokenizer **ppTok,      /* OUT: Tokenizer (if applicable) */
132362   char **pzErr                    /* OUT: Set to malloced error message */
132363 ){
132364   int rc;
132365   char *z = (char *)zArg;
132366   int n = 0;
132367   char *zCopy;
132368   char *zEnd;                     /* Pointer to nul-term of zCopy */
132369   sqlite3_tokenizer_module *m;
132370 
132371   zCopy = sqlite3_mprintf("%s", zArg);
132372   if( !zCopy ) return SQLITE_NOMEM;
132373   zEnd = &zCopy[strlen(zCopy)];
132374 
132375   z = (char *)sqlite3Fts3NextToken(zCopy, &n);
132376   z[n] = '\0';
132377   sqlite3Fts3Dequote(z);
132378 
132379   m = (sqlite3_tokenizer_module *)sqlite3Fts3HashFind(pHash,z,(int)strlen(z)+1);
132380   if( !m ){
132381     *pzErr = sqlite3_mprintf("unknown tokenizer: %s", z);
132382     rc = SQLITE_ERROR;
132383   }else{
132384     char const **aArg = 0;
132385     int iArg = 0;
132386     z = &z[n+1];
132387     while( z<zEnd && (NULL!=(z = (char *)sqlite3Fts3NextToken(z, &n))) ){
132388       int nNew = sizeof(char *)*(iArg+1);
132389       char const **aNew = (const char **)sqlite3_realloc((void *)aArg, nNew);
132390       if( !aNew ){
132391         sqlite3_free(zCopy);
132392         sqlite3_free((void *)aArg);
132393         return SQLITE_NOMEM;
132394       }
132395       aArg = aNew;
132396       aArg[iArg++] = z;
132397       z[n] = '\0';
132398       sqlite3Fts3Dequote(z);
132399       z = &z[n+1];
132400     }
132401     rc = m->xCreate(iArg, aArg, ppTok);
132402     assert( rc!=SQLITE_OK || *ppTok );
132403     if( rc!=SQLITE_OK ){
132404       *pzErr = sqlite3_mprintf("unknown tokenizer");
132405     }else{
132406       (*ppTok)->pModule = m; 
132407     }
132408     sqlite3_free((void *)aArg);
132409   }
132410 
132411   sqlite3_free(zCopy);
132412   return rc;
132413 }
132414 
132415 
132416 #ifdef SQLITE_TEST
132417 
132418 #include <tcl.h>
132419 /* #include <string.h> */
132420 
132421 /*
132422 ** Implementation of a special SQL scalar function for testing tokenizers 
132423 ** designed to be used in concert with the Tcl testing framework. This
132424 ** function must be called with two or more arguments:
132425 **
132426 **   SELECT <function-name>(<key-name>, ..., <input-string>);
132427 **
132428 ** where <function-name> is the name passed as the second argument
132429 ** to the sqlite3Fts3InitHashTable() function (e.g. 'fts3_tokenizer')
132430 ** concatenated with the string '_test' (e.g. 'fts3_tokenizer_test').
132431 **
132432 ** The return value is a string that may be interpreted as a Tcl
132433 ** list. For each token in the <input-string>, three elements are
132434 ** added to the returned list. The first is the token position, the 
132435 ** second is the token text (folded, stemmed, etc.) and the third is the
132436 ** substring of <input-string> associated with the token. For example, 
132437 ** using the built-in "simple" tokenizer:
132438 **
132439 **   SELECT fts_tokenizer_test('simple', 'I don't see how');
132440 **
132441 ** will return the string:
132442 **
132443 **   "{0 i I 1 dont don't 2 see see 3 how how}"
132444 **   
132445 */
132446 static void testFunc(
132447   sqlite3_context *context,
132448   int argc,
132449   sqlite3_value **argv
132450 ){
132451   Fts3Hash *pHash;
132452   sqlite3_tokenizer_module *p;
132453   sqlite3_tokenizer *pTokenizer = 0;
132454   sqlite3_tokenizer_cursor *pCsr = 0;
132455 
132456   const char *zErr = 0;
132457 
132458   const char *zName;
132459   int nName;
132460   const char *zInput;
132461   int nInput;
132462 
132463   const char *azArg[64];
132464 
132465   const char *zToken;
132466   int nToken = 0;
132467   int iStart = 0;
132468   int iEnd = 0;
132469   int iPos = 0;
132470   int i;
132471 
132472   Tcl_Obj *pRet;
132473 
132474   if( argc<2 ){
132475     sqlite3_result_error(context, "insufficient arguments", -1);
132476     return;
132477   }
132478 
132479   nName = sqlite3_value_bytes(argv[0]);
132480   zName = (const char *)sqlite3_value_text(argv[0]);
132481   nInput = sqlite3_value_bytes(argv[argc-1]);
132482   zInput = (const char *)sqlite3_value_text(argv[argc-1]);
132483 
132484   pHash = (Fts3Hash *)sqlite3_user_data(context);
132485   p = (sqlite3_tokenizer_module *)sqlite3Fts3HashFind(pHash, zName, nName+1);
132486 
132487   if( !p ){
132488     char *zErr = sqlite3_mprintf("unknown tokenizer: %s", zName);
132489     sqlite3_result_error(context, zErr, -1);
132490     sqlite3_free(zErr);
132491     return;
132492   }
132493 
132494   pRet = Tcl_NewObj();
132495   Tcl_IncrRefCount(pRet);
132496 
132497   for(i=1; i<argc-1; i++){
132498     azArg[i-1] = (const char *)sqlite3_value_text(argv[i]);
132499   }
132500 
132501   if( SQLITE_OK!=p->xCreate(argc-2, azArg, &pTokenizer) ){
132502     zErr = "error in xCreate()";
132503     goto finish;
132504   }
132505   pTokenizer->pModule = p;
132506   if( sqlite3Fts3OpenTokenizer(pTokenizer, 0, zInput, nInput, &pCsr) ){
132507     zErr = "error in xOpen()";
132508     goto finish;
132509   }
132510 
132511   while( SQLITE_OK==p->xNext(pCsr, &zToken, &nToken, &iStart, &iEnd, &iPos) ){
132512     Tcl_ListObjAppendElement(0, pRet, Tcl_NewIntObj(iPos));
132513     Tcl_ListObjAppendElement(0, pRet, Tcl_NewStringObj(zToken, nToken));
132514     zToken = &zInput[iStart];
132515     nToken = iEnd-iStart;
132516     Tcl_ListObjAppendElement(0, pRet, Tcl_NewStringObj(zToken, nToken));
132517   }
132518 
132519   if( SQLITE_OK!=p->xClose(pCsr) ){
132520     zErr = "error in xClose()";
132521     goto finish;
132522   }
132523   if( SQLITE_OK!=p->xDestroy(pTokenizer) ){
132524     zErr = "error in xDestroy()";
132525     goto finish;
132526   }
132527 
132528 finish:
132529   if( zErr ){
132530     sqlite3_result_error(context, zErr, -1);
132531   }else{
132532     sqlite3_result_text(context, Tcl_GetString(pRet), -1, SQLITE_TRANSIENT);
132533   }
132534   Tcl_DecrRefCount(pRet);
132535 }
132536 
132537 static
132538 int registerTokenizer(
132539   sqlite3 *db, 
132540   char *zName, 
132541   const sqlite3_tokenizer_module *p
132542 ){
132543   int rc;
132544   sqlite3_stmt *pStmt;
132545   const char zSql[] = "SELECT fts3_tokenizer(?, ?)";
132546 
132547   rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);
132548   if( rc!=SQLITE_OK ){
132549     return rc;
132550   }
132551 
132552   sqlite3_bind_text(pStmt, 1, zName, -1, SQLITE_STATIC);
132553   sqlite3_bind_blob(pStmt, 2, &p, sizeof(p), SQLITE_STATIC);
132554   sqlite3_step(pStmt);
132555 
132556   return sqlite3_finalize(pStmt);
132557 }
132558 
132559 static
132560 int queryTokenizer(
132561   sqlite3 *db, 
132562   char *zName,  
132563   const sqlite3_tokenizer_module **pp
132564 ){
132565   int rc;
132566   sqlite3_stmt *pStmt;
132567   const char zSql[] = "SELECT fts3_tokenizer(?)";
132568 
132569   *pp = 0;
132570   rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);
132571   if( rc!=SQLITE_OK ){
132572     return rc;
132573   }
132574 
132575   sqlite3_bind_text(pStmt, 1, zName, -1, SQLITE_STATIC);
132576   if( SQLITE_ROW==sqlite3_step(pStmt) ){
132577     if( sqlite3_column_type(pStmt, 0)==SQLITE_BLOB ){
132578       memcpy((void *)pp, sqlite3_column_blob(pStmt, 0), sizeof(*pp));
132579     }
132580   }
132581 
132582   return sqlite3_finalize(pStmt);
132583 }
132584 
132585 SQLITE_PRIVATE void sqlite3Fts3SimpleTokenizerModule(sqlite3_tokenizer_module const**ppModule);
132586 
132587 /*
132588 ** Implementation of the scalar function fts3_tokenizer_internal_test().
132589 ** This function is used for testing only, it is not included in the
132590 ** build unless SQLITE_TEST is defined.
132591 **
132592 ** The purpose of this is to test that the fts3_tokenizer() function
132593 ** can be used as designed by the C-code in the queryTokenizer and
132594 ** registerTokenizer() functions above. These two functions are repeated
132595 ** in the README.tokenizer file as an example, so it is important to
132596 ** test them.
132597 **
132598 ** To run the tests, evaluate the fts3_tokenizer_internal_test() scalar
132599 ** function with no arguments. An assert() will fail if a problem is
132600 ** detected. i.e.:
132601 **
132602 **     SELECT fts3_tokenizer_internal_test();
132603 **
132604 */
132605 static void intTestFunc(
132606   sqlite3_context *context,
132607   int argc,
132608   sqlite3_value **argv
132609 ){
132610   int rc;
132611   const sqlite3_tokenizer_module *p1;
132612   const sqlite3_tokenizer_module *p2;
132613   sqlite3 *db = (sqlite3 *)sqlite3_user_data(context);
132614 
132615   UNUSED_PARAMETER(argc);
132616   UNUSED_PARAMETER(argv);
132617 
132618   /* Test the query function */
132619   sqlite3Fts3SimpleTokenizerModule(&p1);
132620   rc = queryTokenizer(db, "simple", &p2);
132621   assert( rc==SQLITE_OK );
132622   assert( p1==p2 );
132623   rc = queryTokenizer(db, "nosuchtokenizer", &p2);
132624   assert( rc==SQLITE_ERROR );
132625   assert( p2==0 );
132626   assert( 0==strcmp(sqlite3_errmsg(db), "unknown tokenizer: nosuchtokenizer") );
132627 
132628   /* Test the storage function */
132629   rc = registerTokenizer(db, "nosuchtokenizer", p1);
132630   assert( rc==SQLITE_OK );
132631   rc = queryTokenizer(db, "nosuchtokenizer", &p2);
132632   assert( rc==SQLITE_OK );
132633   assert( p2==p1 );
132634 
132635   sqlite3_result_text(context, "ok", -1, SQLITE_STATIC);
132636 }
132637 
132638 #endif
132639 
132640 /*
132641 ** Set up SQL objects in database db used to access the contents of
132642 ** the hash table pointed to by argument pHash. The hash table must
132643 ** been initialized to use string keys, and to take a private copy 
132644 ** of the key when a value is inserted. i.e. by a call similar to:
132645 **
132646 **    sqlite3Fts3HashInit(pHash, FTS3_HASH_STRING, 1);
132647 **
132648 ** This function adds a scalar function (see header comment above
132649 ** scalarFunc() in this file for details) and, if ENABLE_TABLE is
132650 ** defined at compilation time, a temporary virtual table (see header 
132651 ** comment above struct HashTableVtab) to the database schema. Both 
132652 ** provide read/write access to the contents of *pHash.
132653 **
132654 ** The third argument to this function, zName, is used as the name
132655 ** of both the scalar and, if created, the virtual table.
132656 */
132657 SQLITE_PRIVATE int sqlite3Fts3InitHashTable(
132658   sqlite3 *db, 
132659   Fts3Hash *pHash, 
132660   const char *zName
132661 ){
132662   int rc = SQLITE_OK;
132663   void *p = (void *)pHash;
132664   const int any = SQLITE_ANY;
132665 
132666 #ifdef SQLITE_TEST
132667   char *zTest = 0;
132668   char *zTest2 = 0;
132669   void *pdb = (void *)db;
132670   zTest = sqlite3_mprintf("%s_test", zName);
132671   zTest2 = sqlite3_mprintf("%s_internal_test", zName);
132672   if( !zTest || !zTest2 ){
132673     rc = SQLITE_NOMEM;
132674   }
132675 #endif
132676 
132677   if( SQLITE_OK==rc ){
132678     rc = sqlite3_create_function(db, zName, 1, any, p, scalarFunc, 0, 0);
132679   }
132680   if( SQLITE_OK==rc ){
132681     rc = sqlite3_create_function(db, zName, 2, any, p, scalarFunc, 0, 0);
132682   }
132683 #ifdef SQLITE_TEST
132684   if( SQLITE_OK==rc ){
132685     rc = sqlite3_create_function(db, zTest, -1, any, p, testFunc, 0, 0);
132686   }
132687   if( SQLITE_OK==rc ){
132688     rc = sqlite3_create_function(db, zTest2, 0, any, pdb, intTestFunc, 0, 0);
132689   }
132690 #endif
132691 
132692 #ifdef SQLITE_TEST
132693   sqlite3_free(zTest);
132694   sqlite3_free(zTest2);
132695 #endif
132696 
132697   return rc;
132698 }
132699 
132700 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
132701 
132702 /************** End of fts3_tokenizer.c **************************************/
132703 /************** Begin file fts3_tokenizer1.c *********************************/
132704 /*
132705 ** 2006 Oct 10
132706 **
132707 ** The author disclaims copyright to this source code.  In place of
132708 ** a legal notice, here is a blessing:
132709 **
132710 **    May you do good and not evil.
132711 **    May you find forgiveness for yourself and forgive others.
132712 **    May you share freely, never taking more than you give.
132713 **
132714 ******************************************************************************
132715 **
132716 ** Implementation of the "simple" full-text-search tokenizer.
132717 */
132718 
132719 /*
132720 ** The code in this file is only compiled if:
132721 **
132722 **     * The FTS3 module is being built as an extension
132723 **       (in which case SQLITE_CORE is not defined), or
132724 **
132725 **     * The FTS3 module is being built into the core of
132726 **       SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
132727 */
132728 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
132729 
132730 /* #include <assert.h> */
132731 /* #include <stdlib.h> */
132732 /* #include <stdio.h> */
132733 /* #include <string.h> */
132734 
132735 
132736 typedef struct simple_tokenizer {
132737   sqlite3_tokenizer base;
132738   char delim[128];             /* flag ASCII delimiters */
132739 } simple_tokenizer;
132740 
132741 typedef struct simple_tokenizer_cursor {
132742   sqlite3_tokenizer_cursor base;
132743   const char *pInput;          /* input we are tokenizing */
132744   int nBytes;                  /* size of the input */
132745   int iOffset;                 /* current position in pInput */
132746   int iToken;                  /* index of next token to be returned */
132747   char *pToken;                /* storage for current token */
132748   int nTokenAllocated;         /* space allocated to zToken buffer */
132749 } simple_tokenizer_cursor;
132750 
132751 
132752 static int simpleDelim(simple_tokenizer *t, unsigned char c){
132753   return c<0x80 && t->delim[c];
132754 }
132755 static int fts3_isalnum(int x){
132756   return (x>='0' && x<='9') || (x>='A' && x<='Z') || (x>='a' && x<='z');
132757 }
132758 
132759 /*
132760 ** Create a new tokenizer instance.
132761 */
132762 static int simpleCreate(
132763   int argc, const char * const *argv,
132764   sqlite3_tokenizer **ppTokenizer
132765 ){
132766   simple_tokenizer *t;
132767 
132768   t = (simple_tokenizer *) sqlite3_malloc(sizeof(*t));
132769   if( t==NULL ) return SQLITE_NOMEM;
132770   memset(t, 0, sizeof(*t));
132771 
132772   /* TODO(shess) Delimiters need to remain the same from run to run,
132773   ** else we need to reindex.  One solution would be a meta-table to
132774   ** track such information in the database, then we'd only want this
132775   ** information on the initial create.
132776   */
132777   if( argc>1 ){
132778     int i, n = (int)strlen(argv[1]);
132779     for(i=0; i<n; i++){
132780       unsigned char ch = argv[1][i];
132781       /* We explicitly don't support UTF-8 delimiters for now. */
132782       if( ch>=0x80 ){
132783         sqlite3_free(t);
132784         return SQLITE_ERROR;
132785       }
132786       t->delim[ch] = 1;
132787     }
132788   } else {
132789     /* Mark non-alphanumeric ASCII characters as delimiters */
132790     int i;
132791     for(i=1; i<0x80; i++){
132792       t->delim[i] = !fts3_isalnum(i) ? -1 : 0;
132793     }
132794   }
132795 
132796   *ppTokenizer = &t->base;
132797   return SQLITE_OK;
132798 }
132799 
132800 /*
132801 ** Destroy a tokenizer
132802 */
132803 static int simpleDestroy(sqlite3_tokenizer *pTokenizer){
132804   sqlite3_free(pTokenizer);
132805   return SQLITE_OK;
132806 }
132807 
132808 /*
132809 ** Prepare to begin tokenizing a particular string.  The input
132810 ** string to be tokenized is pInput[0..nBytes-1].  A cursor
132811 ** used to incrementally tokenize this string is returned in 
132812 ** *ppCursor.
132813 */
132814 static int simpleOpen(
132815   sqlite3_tokenizer *pTokenizer,         /* The tokenizer */
132816   const char *pInput, int nBytes,        /* String to be tokenized */
132817   sqlite3_tokenizer_cursor **ppCursor    /* OUT: Tokenization cursor */
132818 ){
132819   simple_tokenizer_cursor *c;
132820 
132821   UNUSED_PARAMETER(pTokenizer);
132822 
132823   c = (simple_tokenizer_cursor *) sqlite3_malloc(sizeof(*c));
132824   if( c==NULL ) return SQLITE_NOMEM;
132825 
132826   c->pInput = pInput;
132827   if( pInput==0 ){
132828     c->nBytes = 0;
132829   }else if( nBytes<0 ){
132830     c->nBytes = (int)strlen(pInput);
132831   }else{
132832     c->nBytes = nBytes;
132833   }
132834   c->iOffset = 0;                 /* start tokenizing at the beginning */
132835   c->iToken = 0;
132836   c->pToken = NULL;               /* no space allocated, yet. */
132837   c->nTokenAllocated = 0;
132838 
132839   *ppCursor = &c->base;
132840   return SQLITE_OK;
132841 }
132842 
132843 /*
132844 ** Close a tokenization cursor previously opened by a call to
132845 ** simpleOpen() above.
132846 */
132847 static int simpleClose(sqlite3_tokenizer_cursor *pCursor){
132848   simple_tokenizer_cursor *c = (simple_tokenizer_cursor *) pCursor;
132849   sqlite3_free(c->pToken);
132850   sqlite3_free(c);
132851   return SQLITE_OK;
132852 }
132853 
132854 /*
132855 ** Extract the next token from a tokenization cursor.  The cursor must
132856 ** have been opened by a prior call to simpleOpen().
132857 */
132858 static int simpleNext(
132859   sqlite3_tokenizer_cursor *pCursor,  /* Cursor returned by simpleOpen */
132860   const char **ppToken,               /* OUT: *ppToken is the token text */
132861   int *pnBytes,                       /* OUT: Number of bytes in token */
132862   int *piStartOffset,                 /* OUT: Starting offset of token */
132863   int *piEndOffset,                   /* OUT: Ending offset of token */
132864   int *piPosition                     /* OUT: Position integer of token */
132865 ){
132866   simple_tokenizer_cursor *c = (simple_tokenizer_cursor *) pCursor;
132867   simple_tokenizer *t = (simple_tokenizer *) pCursor->pTokenizer;
132868   unsigned char *p = (unsigned char *)c->pInput;
132869 
132870   while( c->iOffset<c->nBytes ){
132871     int iStartOffset;
132872 
132873     /* Scan past delimiter characters */
132874     while( c->iOffset<c->nBytes && simpleDelim(t, p[c->iOffset]) ){
132875       c->iOffset++;
132876     }
132877 
132878     /* Count non-delimiter characters. */
132879     iStartOffset = c->iOffset;
132880     while( c->iOffset<c->nBytes && !simpleDelim(t, p[c->iOffset]) ){
132881       c->iOffset++;
132882     }
132883 
132884     if( c->iOffset>iStartOffset ){
132885       int i, n = c->iOffset-iStartOffset;
132886       if( n>c->nTokenAllocated ){
132887         char *pNew;
132888         c->nTokenAllocated = n+20;
132889         pNew = sqlite3_realloc(c->pToken, c->nTokenAllocated);
132890         if( !pNew ) return SQLITE_NOMEM;
132891         c->pToken = pNew;
132892       }
132893       for(i=0; i<n; i++){
132894         /* TODO(shess) This needs expansion to handle UTF-8
132895         ** case-insensitivity.
132896         */
132897         unsigned char ch = p[iStartOffset+i];
132898         c->pToken[i] = (char)((ch>='A' && ch<='Z') ? ch-'A'+'a' : ch);
132899       }
132900       *ppToken = c->pToken;
132901       *pnBytes = n;
132902       *piStartOffset = iStartOffset;
132903       *piEndOffset = c->iOffset;
132904       *piPosition = c->iToken++;
132905 
132906       return SQLITE_OK;
132907     }
132908   }
132909   return SQLITE_DONE;
132910 }
132911 
132912 /*
132913 ** The set of routines that implement the simple tokenizer
132914 */
132915 static const sqlite3_tokenizer_module simpleTokenizerModule = {
132916   0,
132917   simpleCreate,
132918   simpleDestroy,
132919   simpleOpen,
132920   simpleClose,
132921   simpleNext,
132922   0,
132923 };
132924 
132925 /*
132926 ** Allocate a new simple tokenizer.  Return a pointer to the new
132927 ** tokenizer in *ppModule
132928 */
132929 SQLITE_PRIVATE void sqlite3Fts3SimpleTokenizerModule(
132930   sqlite3_tokenizer_module const**ppModule
132931 ){
132932   *ppModule = &simpleTokenizerModule;
132933 }
132934 
132935 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
132936 
132937 /************** End of fts3_tokenizer1.c *************************************/
132938 /************** Begin file fts3_tokenize_vtab.c ******************************/
132939 /*
132940 ** 2013 Apr 22
132941 **
132942 ** The author disclaims copyright to this source code.  In place of
132943 ** a legal notice, here is a blessing:
132944 **
132945 **    May you do good and not evil.
132946 **    May you find forgiveness for yourself and forgive others.
132947 **    May you share freely, never taking more than you give.
132948 **
132949 ******************************************************************************
132950 **
132951 ** This file contains code for the "fts3tokenize" virtual table module.
132952 ** An fts3tokenize virtual table is created as follows:
132953 **
132954 **   CREATE VIRTUAL TABLE <tbl> USING fts3tokenize(
132955 **       <tokenizer-name>, <arg-1>, ...
132956 **   );
132957 **
132958 ** The table created has the following schema:
132959 **
132960 **   CREATE TABLE <tbl>(input, token, start, end, position)
132961 **
132962 ** When queried, the query must include a WHERE clause of type:
132963 **
132964 **   input = <string>
132965 **
132966 ** The virtual table module tokenizes this <string>, using the FTS3 
132967 ** tokenizer specified by the arguments to the CREATE VIRTUAL TABLE 
132968 ** statement and returns one row for each token in the result. With
132969 ** fields set as follows:
132970 **
132971 **   input:   Always set to a copy of <string>
132972 **   token:   A token from the input.
132973 **   start:   Byte offset of the token within the input <string>.
132974 **   end:     Byte offset of the byte immediately following the end of the
132975 **            token within the input string.
132976 **   pos:     Token offset of token within input.
132977 **
132978 */
132979 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
132980 
132981 /* #include <string.h> */
132982 /* #include <assert.h> */
132983 
132984 typedef struct Fts3tokTable Fts3tokTable;
132985 typedef struct Fts3tokCursor Fts3tokCursor;
132986 
132987 /*
132988 ** Virtual table structure.
132989 */
132990 struct Fts3tokTable {
132991   sqlite3_vtab base;              /* Base class used by SQLite core */
132992   const sqlite3_tokenizer_module *pMod;
132993   sqlite3_tokenizer *pTok;
132994 };
132995 
132996 /*
132997 ** Virtual table cursor structure.
132998 */
132999 struct Fts3tokCursor {
133000   sqlite3_vtab_cursor base;       /* Base class used by SQLite core */
133001   char *zInput;                   /* Input string */
133002   sqlite3_tokenizer_cursor *pCsr; /* Cursor to iterate through zInput */
133003   int iRowid;                     /* Current 'rowid' value */
133004   const char *zToken;             /* Current 'token' value */
133005   int nToken;                     /* Size of zToken in bytes */
133006   int iStart;                     /* Current 'start' value */
133007   int iEnd;                       /* Current 'end' value */
133008   int iPos;                       /* Current 'pos' value */
133009 };
133010 
133011 /*
133012 ** Query FTS for the tokenizer implementation named zName.
133013 */
133014 static int fts3tokQueryTokenizer(
133015   Fts3Hash *pHash,
133016   const char *zName,
133017   const sqlite3_tokenizer_module **pp,
133018   char **pzErr
133019 ){
133020   sqlite3_tokenizer_module *p;
133021   int nName = (int)strlen(zName);
133022 
133023   p = (sqlite3_tokenizer_module *)sqlite3Fts3HashFind(pHash, zName, nName+1);
133024   if( !p ){
133025     *pzErr = sqlite3_mprintf("unknown tokenizer: %s", zName);
133026     return SQLITE_ERROR;
133027   }
133028 
133029   *pp = p;
133030   return SQLITE_OK;
133031 }
133032 
133033 /*
133034 ** The second argument, argv[], is an array of pointers to nul-terminated
133035 ** strings. This function makes a copy of the array and strings into a 
133036 ** single block of memory. It then dequotes any of the strings that appear
133037 ** to be quoted.
133038 **
133039 ** If successful, output parameter *pazDequote is set to point at the
133040 ** array of dequoted strings and SQLITE_OK is returned. The caller is
133041 ** responsible for eventually calling sqlite3_free() to free the array
133042 ** in this case. Or, if an error occurs, an SQLite error code is returned.
133043 ** The final value of *pazDequote is undefined in this case.
133044 */
133045 static int fts3tokDequoteArray(
133046   int argc,                       /* Number of elements in argv[] */
133047   const char * const *argv,       /* Input array */
133048   char ***pazDequote              /* Output array */
133049 ){
133050   int rc = SQLITE_OK;             /* Return code */
133051   if( argc==0 ){
133052     *pazDequote = 0;
133053   }else{
133054     int i;
133055     int nByte = 0;
133056     char **azDequote;
133057 
133058     for(i=0; i<argc; i++){
133059       nByte += (int)(strlen(argv[i]) + 1);
133060     }
133061 
133062     *pazDequote = azDequote = sqlite3_malloc(sizeof(char *)*argc + nByte);
133063     if( azDequote==0 ){
133064       rc = SQLITE_NOMEM;
133065     }else{
133066       char *pSpace = (char *)&azDequote[argc];
133067       for(i=0; i<argc; i++){
133068         int n = (int)strlen(argv[i]);
133069         azDequote[i] = pSpace;
133070         memcpy(pSpace, argv[i], n+1);
133071         sqlite3Fts3Dequote(pSpace);
133072         pSpace += (n+1);
133073       }
133074     }
133075   }
133076 
133077   return rc;
133078 }
133079 
133080 /*
133081 ** Schema of the tokenizer table.
133082 */
133083 #define FTS3_TOK_SCHEMA "CREATE TABLE x(input, token, start, end, position)"
133084 
133085 /*
133086 ** This function does all the work for both the xConnect and xCreate methods.
133087 ** These tables have no persistent representation of their own, so xConnect
133088 ** and xCreate are identical operations.
133089 **
133090 **   argv[0]: module name
133091 **   argv[1]: database name 
133092 **   argv[2]: table name
133093 **   argv[3]: first argument (tokenizer name)
133094 */
133095 static int fts3tokConnectMethod(
133096   sqlite3 *db,                    /* Database connection */
133097   void *pHash,                    /* Hash table of tokenizers */
133098   int argc,                       /* Number of elements in argv array */
133099   const char * const *argv,       /* xCreate/xConnect argument array */
133100   sqlite3_vtab **ppVtab,          /* OUT: New sqlite3_vtab object */
133101   char **pzErr                    /* OUT: sqlite3_malloc'd error message */
133102 ){
133103   Fts3tokTable *pTab;
133104   const sqlite3_tokenizer_module *pMod = 0;
133105   sqlite3_tokenizer *pTok = 0;
133106   int rc;
133107   char **azDequote = 0;
133108   int nDequote;
133109 
133110   rc = sqlite3_declare_vtab(db, FTS3_TOK_SCHEMA);
133111   if( rc!=SQLITE_OK ) return rc;
133112 
133113   nDequote = argc-3;
133114   rc = fts3tokDequoteArray(nDequote, &argv[3], &azDequote);
133115 
133116   if( rc==SQLITE_OK ){
133117     const char *zModule;
133118     if( nDequote<1 ){
133119       zModule = "simple";
133120     }else{
133121       zModule = azDequote[0];
133122     }
133123     rc = fts3tokQueryTokenizer((Fts3Hash*)pHash, zModule, &pMod, pzErr);
133124   }
133125 
133126   assert( (rc==SQLITE_OK)==(pMod!=0) );
133127   if( rc==SQLITE_OK ){
133128     const char * const *azArg = (const char * const *)&azDequote[1];
133129     rc = pMod->xCreate((nDequote>1 ? nDequote-1 : 0), azArg, &pTok);
133130   }
133131 
133132   if( rc==SQLITE_OK ){
133133     pTab = (Fts3tokTable *)sqlite3_malloc(sizeof(Fts3tokTable));
133134     if( pTab==0 ){
133135       rc = SQLITE_NOMEM;
133136     }
133137   }
133138 
133139   if( rc==SQLITE_OK ){
133140     memset(pTab, 0, sizeof(Fts3tokTable));
133141     pTab->pMod = pMod;
133142     pTab->pTok = pTok;
133143     *ppVtab = &pTab->base;
133144   }else{
133145     if( pTok ){
133146       pMod->xDestroy(pTok);
133147     }
133148   }
133149 
133150   sqlite3_free(azDequote);
133151   return rc;
133152 }
133153 
133154 /*
133155 ** This function does the work for both the xDisconnect and xDestroy methods.
133156 ** These tables have no persistent representation of their own, so xDisconnect
133157 ** and xDestroy are identical operations.
133158 */
133159 static int fts3tokDisconnectMethod(sqlite3_vtab *pVtab){
133160   Fts3tokTable *pTab = (Fts3tokTable *)pVtab;
133161 
133162   pTab->pMod->xDestroy(pTab->pTok);
133163   sqlite3_free(pTab);
133164   return SQLITE_OK;
133165 }
133166 
133167 /*
133168 ** xBestIndex - Analyze a WHERE and ORDER BY clause.
133169 */
133170 static int fts3tokBestIndexMethod(
133171   sqlite3_vtab *pVTab, 
133172   sqlite3_index_info *pInfo
133173 ){
133174   int i;
133175   UNUSED_PARAMETER(pVTab);
133176 
133177   for(i=0; i<pInfo->nConstraint; i++){
133178     if( pInfo->aConstraint[i].usable 
133179      && pInfo->aConstraint[i].iColumn==0 
133180      && pInfo->aConstraint[i].op==SQLITE_INDEX_CONSTRAINT_EQ 
133181     ){
133182       pInfo->idxNum = 1;
133183       pInfo->aConstraintUsage[i].argvIndex = 1;
133184       pInfo->aConstraintUsage[i].omit = 1;
133185       pInfo->estimatedCost = 1;
133186       return SQLITE_OK;
133187     }
133188   }
133189 
133190   pInfo->idxNum = 0;
133191   assert( pInfo->estimatedCost>1000000.0 );
133192 
133193   return SQLITE_OK;
133194 }
133195 
133196 /*
133197 ** xOpen - Open a cursor.
133198 */
133199 static int fts3tokOpenMethod(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCsr){
133200   Fts3tokCursor *pCsr;
133201   UNUSED_PARAMETER(pVTab);
133202 
133203   pCsr = (Fts3tokCursor *)sqlite3_malloc(sizeof(Fts3tokCursor));
133204   if( pCsr==0 ){
133205     return SQLITE_NOMEM;
133206   }
133207   memset(pCsr, 0, sizeof(Fts3tokCursor));
133208 
133209   *ppCsr = (sqlite3_vtab_cursor *)pCsr;
133210   return SQLITE_OK;
133211 }
133212 
133213 /*
133214 ** Reset the tokenizer cursor passed as the only argument. As if it had
133215 ** just been returned by fts3tokOpenMethod().
133216 */
133217 static void fts3tokResetCursor(Fts3tokCursor *pCsr){
133218   if( pCsr->pCsr ){
133219     Fts3tokTable *pTab = (Fts3tokTable *)(pCsr->base.pVtab);
133220     pTab->pMod->xClose(pCsr->pCsr);
133221     pCsr->pCsr = 0;
133222   }
133223   sqlite3_free(pCsr->zInput);
133224   pCsr->zInput = 0;
133225   pCsr->zToken = 0;
133226   pCsr->nToken = 0;
133227   pCsr->iStart = 0;
133228   pCsr->iEnd = 0;
133229   pCsr->iPos = 0;
133230   pCsr->iRowid = 0;
133231 }
133232 
133233 /*
133234 ** xClose - Close a cursor.
133235 */
133236 static int fts3tokCloseMethod(sqlite3_vtab_cursor *pCursor){
133237   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133238 
133239   fts3tokResetCursor(pCsr);
133240   sqlite3_free(pCsr);
133241   return SQLITE_OK;
133242 }
133243 
133244 /*
133245 ** xNext - Advance the cursor to the next row, if any.
133246 */
133247 static int fts3tokNextMethod(sqlite3_vtab_cursor *pCursor){
133248   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133249   Fts3tokTable *pTab = (Fts3tokTable *)(pCursor->pVtab);
133250   int rc;                         /* Return code */
133251 
133252   pCsr->iRowid++;
133253   rc = pTab->pMod->xNext(pCsr->pCsr,
133254       &pCsr->zToken, &pCsr->nToken,
133255       &pCsr->iStart, &pCsr->iEnd, &pCsr->iPos
133256   );
133257 
133258   if( rc!=SQLITE_OK ){
133259     fts3tokResetCursor(pCsr);
133260     if( rc==SQLITE_DONE ) rc = SQLITE_OK;
133261   }
133262 
133263   return rc;
133264 }
133265 
133266 /*
133267 ** xFilter - Initialize a cursor to point at the start of its data.
133268 */
133269 static int fts3tokFilterMethod(
133270   sqlite3_vtab_cursor *pCursor,   /* The cursor used for this query */
133271   int idxNum,                     /* Strategy index */
133272   const char *idxStr,             /* Unused */
133273   int nVal,                       /* Number of elements in apVal */
133274   sqlite3_value **apVal           /* Arguments for the indexing scheme */
133275 ){
133276   int rc = SQLITE_ERROR;
133277   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133278   Fts3tokTable *pTab = (Fts3tokTable *)(pCursor->pVtab);
133279   UNUSED_PARAMETER(idxStr);
133280   UNUSED_PARAMETER(nVal);
133281 
133282   fts3tokResetCursor(pCsr);
133283   if( idxNum==1 ){
133284     const char *zByte = (const char *)sqlite3_value_text(apVal[0]);
133285     int nByte = sqlite3_value_bytes(apVal[0]);
133286     pCsr->zInput = sqlite3_malloc(nByte+1);
133287     if( pCsr->zInput==0 ){
133288       rc = SQLITE_NOMEM;
133289     }else{
133290       memcpy(pCsr->zInput, zByte, nByte);
133291       pCsr->zInput[nByte] = 0;
133292       rc = pTab->pMod->xOpen(pTab->pTok, pCsr->zInput, nByte, &pCsr->pCsr);
133293       if( rc==SQLITE_OK ){
133294         pCsr->pCsr->pTokenizer = pTab->pTok;
133295       }
133296     }
133297   }
133298 
133299   if( rc!=SQLITE_OK ) return rc;
133300   return fts3tokNextMethod(pCursor);
133301 }
133302 
133303 /*
133304 ** xEof - Return true if the cursor is at EOF, or false otherwise.
133305 */
133306 static int fts3tokEofMethod(sqlite3_vtab_cursor *pCursor){
133307   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133308   return (pCsr->zToken==0);
133309 }
133310 
133311 /*
133312 ** xColumn - Return a column value.
133313 */
133314 static int fts3tokColumnMethod(
133315   sqlite3_vtab_cursor *pCursor,   /* Cursor to retrieve value from */
133316   sqlite3_context *pCtx,          /* Context for sqlite3_result_xxx() calls */
133317   int iCol                        /* Index of column to read value from */
133318 ){
133319   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133320 
133321   /* CREATE TABLE x(input, token, start, end, position) */
133322   switch( iCol ){
133323     case 0:
133324       sqlite3_result_text(pCtx, pCsr->zInput, -1, SQLITE_TRANSIENT);
133325       break;
133326     case 1:
133327       sqlite3_result_text(pCtx, pCsr->zToken, pCsr->nToken, SQLITE_TRANSIENT);
133328       break;
133329     case 2:
133330       sqlite3_result_int(pCtx, pCsr->iStart);
133331       break;
133332     case 3:
133333       sqlite3_result_int(pCtx, pCsr->iEnd);
133334       break;
133335     default:
133336       assert( iCol==4 );
133337       sqlite3_result_int(pCtx, pCsr->iPos);
133338       break;
133339   }
133340   return SQLITE_OK;
133341 }
133342 
133343 /*
133344 ** xRowid - Return the current rowid for the cursor.
133345 */
133346 static int fts3tokRowidMethod(
133347   sqlite3_vtab_cursor *pCursor,   /* Cursor to retrieve value from */
133348   sqlite_int64 *pRowid            /* OUT: Rowid value */
133349 ){
133350   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133351   *pRowid = (sqlite3_int64)pCsr->iRowid;
133352   return SQLITE_OK;
133353 }
133354 
133355 /*
133356 ** Register the fts3tok module with database connection db. Return SQLITE_OK
133357 ** if successful or an error code if sqlite3_create_module() fails.
133358 */
133359 SQLITE_PRIVATE int sqlite3Fts3InitTok(sqlite3 *db, Fts3Hash *pHash){
133360   static const sqlite3_module fts3tok_module = {
133361      0,                           /* iVersion      */
133362      fts3tokConnectMethod,        /* xCreate       */
133363      fts3tokConnectMethod,        /* xConnect      */
133364      fts3tokBestIndexMethod,      /* xBestIndex    */
133365      fts3tokDisconnectMethod,     /* xDisconnect   */
133366      fts3tokDisconnectMethod,     /* xDestroy      */
133367      fts3tokOpenMethod,           /* xOpen         */
133368      fts3tokCloseMethod,          /* xClose        */
133369      fts3tokFilterMethod,         /* xFilter       */
133370      fts3tokNextMethod,           /* xNext         */
133371      fts3tokEofMethod,            /* xEof          */
133372      fts3tokColumnMethod,         /* xColumn       */
133373      fts3tokRowidMethod,          /* xRowid        */
133374      0,                           /* xUpdate       */
133375      0,                           /* xBegin        */
133376      0,                           /* xSync         */
133377      0,                           /* xCommit       */
133378      0,                           /* xRollback     */
133379      0,                           /* xFindFunction */
133380      0,                           /* xRename       */
133381      0,                           /* xSavepoint    */
133382      0,                           /* xRelease      */
133383      0                            /* xRollbackTo   */
133384   };
133385   int rc;                         /* Return code */
133386 
133387   rc = sqlite3_create_module(db, "fts3tokenize", &fts3tok_module, (void*)pHash);
133388   return rc;
133389 }
133390 
133391 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
133392 
133393 /************** End of fts3_tokenize_vtab.c **********************************/
133394 /************** Begin file fts3_write.c **************************************/
133395 /*
133396 ** 2009 Oct 23
133397 **
133398 ** The author disclaims copyright to this source code.  In place of
133399 ** a legal notice, here is a blessing:
133400 **
133401 **    May you do good and not evil.
133402 **    May you find forgiveness for yourself and forgive others.
133403 **    May you share freely, never taking more than you give.
133404 **
133405 ******************************************************************************
133406 **
133407 ** This file is part of the SQLite FTS3 extension module. Specifically,
133408 ** this file contains code to insert, update and delete rows from FTS3
133409 ** tables. It also contains code to merge FTS3 b-tree segments. Some
133410 ** of the sub-routines used to merge segments are also used by the query 
133411 ** code in fts3.c.
133412 */
133413 
133414 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
133415 
133416 /* #include <string.h> */
133417 /* #include <assert.h> */
133418 /* #include <stdlib.h> */
133419 
133420 
133421 #define FTS_MAX_APPENDABLE_HEIGHT 16
133422 
133423 /*
133424 ** When full-text index nodes are loaded from disk, the buffer that they
133425 ** are loaded into has the following number of bytes of padding at the end 
133426 ** of it. i.e. if a full-text index node is 900 bytes in size, then a buffer
133427 ** of 920 bytes is allocated for it.
133428 **
133429 ** This means that if we have a pointer into a buffer containing node data,
133430 ** it is always safe to read up to two varints from it without risking an
133431 ** overread, even if the node data is corrupted.
133432 */
133433 #define FTS3_NODE_PADDING (FTS3_VARINT_MAX*2)
133434 
133435 /*
133436 ** Under certain circumstances, b-tree nodes (doclists) can be loaded into
133437 ** memory incrementally instead of all at once. This can be a big performance
133438 ** win (reduced IO and CPU) if SQLite stops calling the virtual table xNext()
133439 ** method before retrieving all query results (as may happen, for example,
133440 ** if a query has a LIMIT clause).
133441 **
133442 ** Incremental loading is used for b-tree nodes FTS3_NODE_CHUNK_THRESHOLD 
133443 ** bytes and larger. Nodes are loaded in chunks of FTS3_NODE_CHUNKSIZE bytes.
133444 ** The code is written so that the hard lower-limit for each of these values 
133445 ** is 1. Clearly such small values would be inefficient, but can be useful 
133446 ** for testing purposes.
133447 **
133448 ** If this module is built with SQLITE_TEST defined, these constants may
133449 ** be overridden at runtime for testing purposes. File fts3_test.c contains
133450 ** a Tcl interface to read and write the values.
133451 */
133452 #ifdef SQLITE_TEST
133453 int test_fts3_node_chunksize = (4*1024);
133454 int test_fts3_node_chunk_threshold = (4*1024)*4;
133455 # define FTS3_NODE_CHUNKSIZE       test_fts3_node_chunksize
133456 # define FTS3_NODE_CHUNK_THRESHOLD test_fts3_node_chunk_threshold
133457 #else
133458 # define FTS3_NODE_CHUNKSIZE (4*1024) 
133459 # define FTS3_NODE_CHUNK_THRESHOLD (FTS3_NODE_CHUNKSIZE*4)
133460 #endif
133461 
133462 /*
133463 ** The two values that may be meaningfully bound to the :1 parameter in
133464 ** statements SQL_REPLACE_STAT and SQL_SELECT_STAT.
133465 */
133466 #define FTS_STAT_DOCTOTAL      0
133467 #define FTS_STAT_INCRMERGEHINT 1
133468 #define FTS_STAT_AUTOINCRMERGE 2
133469 
133470 /*
133471 ** If FTS_LOG_MERGES is defined, call sqlite3_log() to report each automatic
133472 ** and incremental merge operation that takes place. This is used for 
133473 ** debugging FTS only, it should not usually be turned on in production
133474 ** systems.
133475 */
133476 #ifdef FTS3_LOG_MERGES
133477 static void fts3LogMerge(int nMerge, sqlite3_int64 iAbsLevel){
133478   sqlite3_log(SQLITE_OK, "%d-way merge from level %d", nMerge, (int)iAbsLevel);
133479 }
133480 #else
133481 #define fts3LogMerge(x, y)
133482 #endif
133483 
133484 
133485 typedef struct PendingList PendingList;
133486 typedef struct SegmentNode SegmentNode;
133487 typedef struct SegmentWriter SegmentWriter;
133488 
133489 /*
133490 ** An instance of the following data structure is used to build doclists
133491 ** incrementally. See function fts3PendingListAppend() for details.
133492 */
133493 struct PendingList {
133494   int nData;
133495   char *aData;
133496   int nSpace;
133497   sqlite3_int64 iLastDocid;
133498   sqlite3_int64 iLastCol;
133499   sqlite3_int64 iLastPos;
133500 };
133501 
133502 
133503 /*
133504 ** Each cursor has a (possibly empty) linked list of the following objects.
133505 */
133506 struct Fts3DeferredToken {
133507   Fts3PhraseToken *pToken;        /* Pointer to corresponding expr token */
133508   int iCol;                       /* Column token must occur in */
133509   Fts3DeferredToken *pNext;       /* Next in list of deferred tokens */
133510   PendingList *pList;             /* Doclist is assembled here */
133511 };
133512 
133513 /*
133514 ** An instance of this structure is used to iterate through the terms on
133515 ** a contiguous set of segment b-tree leaf nodes. Although the details of
133516 ** this structure are only manipulated by code in this file, opaque handles
133517 ** of type Fts3SegReader* are also used by code in fts3.c to iterate through
133518 ** terms when querying the full-text index. See functions:
133519 **
133520 **   sqlite3Fts3SegReaderNew()
133521 **   sqlite3Fts3SegReaderFree()
133522 **   sqlite3Fts3SegReaderIterate()
133523 **
133524 ** Methods used to manipulate Fts3SegReader structures:
133525 **
133526 **   fts3SegReaderNext()
133527 **   fts3SegReaderFirstDocid()
133528 **   fts3SegReaderNextDocid()
133529 */
133530 struct Fts3SegReader {
133531   int iIdx;                       /* Index within level, or 0x7FFFFFFF for PT */
133532   u8 bLookup;                     /* True for a lookup only */
133533   u8 rootOnly;                    /* True for a root-only reader */
133534 
133535   sqlite3_int64 iStartBlock;      /* Rowid of first leaf block to traverse */
133536   sqlite3_int64 iLeafEndBlock;    /* Rowid of final leaf block to traverse */
133537   sqlite3_int64 iEndBlock;        /* Rowid of final block in segment (or 0) */
133538   sqlite3_int64 iCurrentBlock;    /* Current leaf block (or 0) */
133539 
133540   char *aNode;                    /* Pointer to node data (or NULL) */
133541   int nNode;                      /* Size of buffer at aNode (or 0) */
133542   int nPopulate;                  /* If >0, bytes of buffer aNode[] loaded */
133543   sqlite3_blob *pBlob;            /* If not NULL, blob handle to read node */
133544 
133545   Fts3HashElem **ppNextElem;
133546 
133547   /* Variables set by fts3SegReaderNext(). These may be read directly
133548   ** by the caller. They are valid from the time SegmentReaderNew() returns
133549   ** until SegmentReaderNext() returns something other than SQLITE_OK
133550   ** (i.e. SQLITE_DONE).
133551   */
133552   int nTerm;                      /* Number of bytes in current term */
133553   char *zTerm;                    /* Pointer to current term */
133554   int nTermAlloc;                 /* Allocated size of zTerm buffer */
133555   char *aDoclist;                 /* Pointer to doclist of current entry */
133556   int nDoclist;                   /* Size of doclist in current entry */
133557 
133558   /* The following variables are used by fts3SegReaderNextDocid() to iterate 
133559   ** through the current doclist (aDoclist/nDoclist).
133560   */
133561   char *pOffsetList;
133562   int nOffsetList;                /* For descending pending seg-readers only */
133563   sqlite3_int64 iDocid;
133564 };
133565 
133566 #define fts3SegReaderIsPending(p) ((p)->ppNextElem!=0)
133567 #define fts3SegReaderIsRootOnly(p) ((p)->rootOnly!=0)
133568 
133569 /*
133570 ** An instance of this structure is used to create a segment b-tree in the
133571 ** database. The internal details of this type are only accessed by the
133572 ** following functions:
133573 **
133574 **   fts3SegWriterAdd()
133575 **   fts3SegWriterFlush()
133576 **   fts3SegWriterFree()
133577 */
133578 struct SegmentWriter {
133579   SegmentNode *pTree;             /* Pointer to interior tree structure */
133580   sqlite3_int64 iFirst;           /* First slot in %_segments written */
133581   sqlite3_int64 iFree;            /* Next free slot in %_segments */
133582   char *zTerm;                    /* Pointer to previous term buffer */
133583   int nTerm;                      /* Number of bytes in zTerm */
133584   int nMalloc;                    /* Size of malloc'd buffer at zMalloc */
133585   char *zMalloc;                  /* Malloc'd space (possibly) used for zTerm */
133586   int nSize;                      /* Size of allocation at aData */
133587   int nData;                      /* Bytes of data in aData */
133588   char *aData;                    /* Pointer to block from malloc() */
133589 };
133590 
133591 /*
133592 ** Type SegmentNode is used by the following three functions to create
133593 ** the interior part of the segment b+-tree structures (everything except
133594 ** the leaf nodes). These functions and type are only ever used by code
133595 ** within the fts3SegWriterXXX() family of functions described above.
133596 **
133597 **   fts3NodeAddTerm()
133598 **   fts3NodeWrite()
133599 **   fts3NodeFree()
133600 **
133601 ** When a b+tree is written to the database (either as a result of a merge
133602 ** or the pending-terms table being flushed), leaves are written into the 
133603 ** database file as soon as they are completely populated. The interior of
133604 ** the tree is assembled in memory and written out only once all leaves have
133605 ** been populated and stored. This is Ok, as the b+-tree fanout is usually
133606 ** very large, meaning that the interior of the tree consumes relatively 
133607 ** little memory.
133608 */
133609 struct SegmentNode {
133610   SegmentNode *pParent;           /* Parent node (or NULL for root node) */
133611   SegmentNode *pRight;            /* Pointer to right-sibling */
133612   SegmentNode *pLeftmost;         /* Pointer to left-most node of this depth */
133613   int nEntry;                     /* Number of terms written to node so far */
133614   char *zTerm;                    /* Pointer to previous term buffer */
133615   int nTerm;                      /* Number of bytes in zTerm */
133616   int nMalloc;                    /* Size of malloc'd buffer at zMalloc */
133617   char *zMalloc;                  /* Malloc'd space (possibly) used for zTerm */
133618   int nData;                      /* Bytes of valid data so far */
133619   char *aData;                    /* Node data */
133620 };
133621 
133622 /*
133623 ** Valid values for the second argument to fts3SqlStmt().
133624 */
133625 #define SQL_DELETE_CONTENT             0
133626 #define SQL_IS_EMPTY                   1
133627 #define SQL_DELETE_ALL_CONTENT         2 
133628 #define SQL_DELETE_ALL_SEGMENTS        3
133629 #define SQL_DELETE_ALL_SEGDIR          4
133630 #define SQL_DELETE_ALL_DOCSIZE         5
133631 #define SQL_DELETE_ALL_STAT            6
133632 #define SQL_SELECT_CONTENT_BY_ROWID    7
133633 #define SQL_NEXT_SEGMENT_INDEX         8
133634 #define SQL_INSERT_SEGMENTS            9
133635 #define SQL_NEXT_SEGMENTS_ID          10
133636 #define SQL_INSERT_SEGDIR             11
133637 #define SQL_SELECT_LEVEL              12
133638 #define SQL_SELECT_LEVEL_RANGE        13
133639 #define SQL_SELECT_LEVEL_COUNT        14
133640 #define SQL_SELECT_SEGDIR_MAX_LEVEL   15
133641 #define SQL_DELETE_SEGDIR_LEVEL       16
133642 #define SQL_DELETE_SEGMENTS_RANGE     17
133643 #define SQL_CONTENT_INSERT            18
133644 #define SQL_DELETE_DOCSIZE            19
133645 #define SQL_REPLACE_DOCSIZE           20
133646 #define SQL_SELECT_DOCSIZE            21
133647 #define SQL_SELECT_STAT               22
133648 #define SQL_REPLACE_STAT              23
133649 
133650 #define SQL_SELECT_ALL_PREFIX_LEVEL   24
133651 #define SQL_DELETE_ALL_TERMS_SEGDIR   25
133652 #define SQL_DELETE_SEGDIR_RANGE       26
133653 #define SQL_SELECT_ALL_LANGID         27
133654 #define SQL_FIND_MERGE_LEVEL          28
133655 #define SQL_MAX_LEAF_NODE_ESTIMATE    29
133656 #define SQL_DELETE_SEGDIR_ENTRY       30
133657 #define SQL_SHIFT_SEGDIR_ENTRY        31
133658 #define SQL_SELECT_SEGDIR             32
133659 #define SQL_CHOMP_SEGDIR              33
133660 #define SQL_SEGMENT_IS_APPENDABLE     34
133661 #define SQL_SELECT_INDEXES            35
133662 #define SQL_SELECT_MXLEVEL            36
133663 
133664 /*
133665 ** This function is used to obtain an SQLite prepared statement handle
133666 ** for the statement identified by the second argument. If successful,
133667 ** *pp is set to the requested statement handle and SQLITE_OK returned.
133668 ** Otherwise, an SQLite error code is returned and *pp is set to 0.
133669 **
133670 ** If argument apVal is not NULL, then it must point to an array with
133671 ** at least as many entries as the requested statement has bound 
133672 ** parameters. The values are bound to the statements parameters before
133673 ** returning.
133674 */
133675 static int fts3SqlStmt(
133676   Fts3Table *p,                   /* Virtual table handle */
133677   int eStmt,                      /* One of the SQL_XXX constants above */
133678   sqlite3_stmt **pp,              /* OUT: Statement handle */
133679   sqlite3_value **apVal           /* Values to bind to statement */
133680 ){
133681   const char *azSql[] = {
133682 /* 0  */  "DELETE FROM %Q.'%q_content' WHERE rowid = ?",
133683 /* 1  */  "SELECT NOT EXISTS(SELECT docid FROM %Q.'%q_content' WHERE rowid!=?)",
133684 /* 2  */  "DELETE FROM %Q.'%q_content'",
133685 /* 3  */  "DELETE FROM %Q.'%q_segments'",
133686 /* 4  */  "DELETE FROM %Q.'%q_segdir'",
133687 /* 5  */  "DELETE FROM %Q.'%q_docsize'",
133688 /* 6  */  "DELETE FROM %Q.'%q_stat'",
133689 /* 7  */  "SELECT %s WHERE rowid=?",
133690 /* 8  */  "SELECT (SELECT max(idx) FROM %Q.'%q_segdir' WHERE level = ?) + 1",
133691 /* 9  */  "REPLACE INTO %Q.'%q_segments'(blockid, block) VALUES(?, ?)",
133692 /* 10 */  "SELECT coalesce((SELECT max(blockid) FROM %Q.'%q_segments') + 1, 1)",
133693 /* 11 */  "REPLACE INTO %Q.'%q_segdir' VALUES(?,?,?,?,?,?)",
133694 
133695           /* Return segments in order from oldest to newest.*/ 
133696 /* 12 */  "SELECT idx, start_block, leaves_end_block, end_block, root "
133697             "FROM %Q.'%q_segdir' WHERE level = ? ORDER BY idx ASC",
133698 /* 13 */  "SELECT idx, start_block, leaves_end_block, end_block, root "
133699             "FROM %Q.'%q_segdir' WHERE level BETWEEN ? AND ?"
133700             "ORDER BY level DESC, idx ASC",
133701 
133702 /* 14 */  "SELECT count(*) FROM %Q.'%q_segdir' WHERE level = ?",
133703 /* 15 */  "SELECT max(level) FROM %Q.'%q_segdir' WHERE level BETWEEN ? AND ?",
133704 
133705 /* 16 */  "DELETE FROM %Q.'%q_segdir' WHERE level = ?",
133706 /* 17 */  "DELETE FROM %Q.'%q_segments' WHERE blockid BETWEEN ? AND ?",
133707 /* 18 */  "INSERT INTO %Q.'%q_content' VALUES(%s)",
133708 /* 19 */  "DELETE FROM %Q.'%q_docsize' WHERE docid = ?",
133709 /* 20 */  "REPLACE INTO %Q.'%q_docsize' VALUES(?,?)",
133710 /* 21 */  "SELECT size FROM %Q.'%q_docsize' WHERE docid=?",
133711 /* 22 */  "SELECT value FROM %Q.'%q_stat' WHERE id=?",
133712 /* 23 */  "REPLACE INTO %Q.'%q_stat' VALUES(?,?)",
133713 /* 24 */  "",
133714 /* 25 */  "",
133715 
133716 /* 26 */ "DELETE FROM %Q.'%q_segdir' WHERE level BETWEEN ? AND ?",
133717 /* 27 */ "SELECT DISTINCT level / (1024 * ?) FROM %Q.'%q_segdir'",
133718 
133719 /* This statement is used to determine which level to read the input from
133720 ** when performing an incremental merge. It returns the absolute level number
133721 ** of the oldest level in the db that contains at least ? segments. Or,
133722 ** if no level in the FTS index contains more than ? segments, the statement
133723 ** returns zero rows.  */
133724 /* 28 */ "SELECT level FROM %Q.'%q_segdir' GROUP BY level HAVING count(*)>=?"
133725          "  ORDER BY (level %% 1024) ASC LIMIT 1",
133726 
133727 /* Estimate the upper limit on the number of leaf nodes in a new segment
133728 ** created by merging the oldest :2 segments from absolute level :1. See 
133729 ** function sqlite3Fts3Incrmerge() for details.  */
133730 /* 29 */ "SELECT 2 * total(1 + leaves_end_block - start_block) "
133731          "  FROM %Q.'%q_segdir' WHERE level = ? AND idx < ?",
133732 
133733 /* SQL_DELETE_SEGDIR_ENTRY
133734 **   Delete the %_segdir entry on absolute level :1 with index :2.  */
133735 /* 30 */ "DELETE FROM %Q.'%q_segdir' WHERE level = ? AND idx = ?",
133736 
133737 /* SQL_SHIFT_SEGDIR_ENTRY
133738 **   Modify the idx value for the segment with idx=:3 on absolute level :2
133739 **   to :1.  */
133740 /* 31 */ "UPDATE %Q.'%q_segdir' SET idx = ? WHERE level=? AND idx=?",
133741 
133742 /* SQL_SELECT_SEGDIR
133743 **   Read a single entry from the %_segdir table. The entry from absolute 
133744 **   level :1 with index value :2.  */
133745 /* 32 */  "SELECT idx, start_block, leaves_end_block, end_block, root "
133746             "FROM %Q.'%q_segdir' WHERE level = ? AND idx = ?",
133747 
133748 /* SQL_CHOMP_SEGDIR
133749 **   Update the start_block (:1) and root (:2) fields of the %_segdir
133750 **   entry located on absolute level :3 with index :4.  */
133751 /* 33 */  "UPDATE %Q.'%q_segdir' SET start_block = ?, root = ?"
133752             "WHERE level = ? AND idx = ?",
133753 
133754 /* SQL_SEGMENT_IS_APPENDABLE
133755 **   Return a single row if the segment with end_block=? is appendable. Or
133756 **   no rows otherwise.  */
133757 /* 34 */  "SELECT 1 FROM %Q.'%q_segments' WHERE blockid=? AND block IS NULL",
133758 
133759 /* SQL_SELECT_INDEXES
133760 **   Return the list of valid segment indexes for absolute level ?  */
133761 /* 35 */  "SELECT idx FROM %Q.'%q_segdir' WHERE level=? ORDER BY 1 ASC",
133762 
133763 /* SQL_SELECT_MXLEVEL
133764 **   Return the largest relative level in the FTS index or indexes.  */
133765 /* 36 */  "SELECT max( level %% 1024 ) FROM %Q.'%q_segdir'"
133766   };
133767   int rc = SQLITE_OK;
133768   sqlite3_stmt *pStmt;
133769 
133770   assert( SizeofArray(azSql)==SizeofArray(p->aStmt) );
133771   assert( eStmt<SizeofArray(azSql) && eStmt>=0 );
133772   
133773   pStmt = p->aStmt[eStmt];
133774   if( !pStmt ){
133775     char *zSql;
133776     if( eStmt==SQL_CONTENT_INSERT ){
133777       zSql = sqlite3_mprintf(azSql[eStmt], p->zDb, p->zName, p->zWriteExprlist);
133778     }else if( eStmt==SQL_SELECT_CONTENT_BY_ROWID ){
133779       zSql = sqlite3_mprintf(azSql[eStmt], p->zReadExprlist);
133780     }else{
133781       zSql = sqlite3_mprintf(azSql[eStmt], p->zDb, p->zName);
133782     }
133783     if( !zSql ){
133784       rc = SQLITE_NOMEM;
133785     }else{
133786       rc = sqlite3_prepare_v2(p->db, zSql, -1, &pStmt, NULL);
133787       sqlite3_free(zSql);
133788       assert( rc==SQLITE_OK || pStmt==0 );
133789       p->aStmt[eStmt] = pStmt;
133790     }
133791   }
133792   if( apVal ){
133793     int i;
133794     int nParam = sqlite3_bind_parameter_count(pStmt);
133795     for(i=0; rc==SQLITE_OK && i<nParam; i++){
133796       rc = sqlite3_bind_value(pStmt, i+1, apVal[i]);
133797     }
133798   }
133799   *pp = pStmt;
133800   return rc;
133801 }
133802 
133803 
133804 static int fts3SelectDocsize(
133805   Fts3Table *pTab,                /* FTS3 table handle */
133806   sqlite3_int64 iDocid,           /* Docid to bind for SQL_SELECT_DOCSIZE */
133807   sqlite3_stmt **ppStmt           /* OUT: Statement handle */
133808 ){
133809   sqlite3_stmt *pStmt = 0;        /* Statement requested from fts3SqlStmt() */
133810   int rc;                         /* Return code */
133811 
133812   rc = fts3SqlStmt(pTab, SQL_SELECT_DOCSIZE, &pStmt, 0);
133813   if( rc==SQLITE_OK ){
133814     sqlite3_bind_int64(pStmt, 1, iDocid);
133815     rc = sqlite3_step(pStmt);
133816     if( rc!=SQLITE_ROW || sqlite3_column_type(pStmt, 0)!=SQLITE_BLOB ){
133817       rc = sqlite3_reset(pStmt);
133818       if( rc==SQLITE_OK ) rc = FTS_CORRUPT_VTAB;
133819       pStmt = 0;
133820     }else{
133821       rc = SQLITE_OK;
133822     }
133823   }
133824 
133825   *ppStmt = pStmt;
133826   return rc;
133827 }
133828 
133829 SQLITE_PRIVATE int sqlite3Fts3SelectDoctotal(
133830   Fts3Table *pTab,                /* Fts3 table handle */
133831   sqlite3_stmt **ppStmt           /* OUT: Statement handle */
133832 ){
133833   sqlite3_stmt *pStmt = 0;
133834   int rc;
133835   rc = fts3SqlStmt(pTab, SQL_SELECT_STAT, &pStmt, 0);
133836   if( rc==SQLITE_OK ){
133837     sqlite3_bind_int(pStmt, 1, FTS_STAT_DOCTOTAL);
133838     if( sqlite3_step(pStmt)!=SQLITE_ROW
133839      || sqlite3_column_type(pStmt, 0)!=SQLITE_BLOB
133840     ){
133841       rc = sqlite3_reset(pStmt);
133842       if( rc==SQLITE_OK ) rc = FTS_CORRUPT_VTAB;
133843       pStmt = 0;
133844     }
133845   }
133846   *ppStmt = pStmt;
133847   return rc;
133848 }
133849 
133850 SQLITE_PRIVATE int sqlite3Fts3SelectDocsize(
133851   Fts3Table *pTab,                /* Fts3 table handle */
133852   sqlite3_int64 iDocid,           /* Docid to read size data for */
133853   sqlite3_stmt **ppStmt           /* OUT: Statement handle */
133854 ){
133855   return fts3SelectDocsize(pTab, iDocid, ppStmt);
133856 }
133857 
133858 /*
133859 ** Similar to fts3SqlStmt(). Except, after binding the parameters in
133860 ** array apVal[] to the SQL statement identified by eStmt, the statement
133861 ** is executed.
133862 **
133863 ** Returns SQLITE_OK if the statement is successfully executed, or an
133864 ** SQLite error code otherwise.
133865 */
133866 static void fts3SqlExec(
133867   int *pRC,                /* Result code */
133868   Fts3Table *p,            /* The FTS3 table */
133869   int eStmt,               /* Index of statement to evaluate */
133870   sqlite3_value **apVal    /* Parameters to bind */
133871 ){
133872   sqlite3_stmt *pStmt;
133873   int rc;
133874   if( *pRC ) return;
133875   rc = fts3SqlStmt(p, eStmt, &pStmt, apVal); 
133876   if( rc==SQLITE_OK ){
133877     sqlite3_step(pStmt);
133878     rc = sqlite3_reset(pStmt);
133879   }
133880   *pRC = rc;
133881 }
133882 
133883 
133884 /*
133885 ** This function ensures that the caller has obtained an exclusive 
133886 ** shared-cache table-lock on the %_segdir table. This is required before 
133887 ** writing data to the fts3 table. If this lock is not acquired first, then
133888 ** the caller may end up attempting to take this lock as part of committing
133889 ** a transaction, causing SQLite to return SQLITE_LOCKED or 
133890 ** LOCKED_SHAREDCACHEto a COMMIT command.
133891 **
133892 ** It is best to avoid this because if FTS3 returns any error when 
133893 ** committing a transaction, the whole transaction will be rolled back. 
133894 ** And this is not what users expect when they get SQLITE_LOCKED_SHAREDCACHE. 
133895 ** It can still happen if the user locks the underlying tables directly 
133896 ** instead of accessing them via FTS.
133897 */
133898 static int fts3Writelock(Fts3Table *p){
133899   int rc = SQLITE_OK;
133900   
133901   if( p->nPendingData==0 ){
133902     sqlite3_stmt *pStmt;
133903     rc = fts3SqlStmt(p, SQL_DELETE_SEGDIR_LEVEL, &pStmt, 0);
133904     if( rc==SQLITE_OK ){
133905       sqlite3_bind_null(pStmt, 1);
133906       sqlite3_step(pStmt);
133907       rc = sqlite3_reset(pStmt);
133908     }
133909   }
133910 
133911   return rc;
133912 }
133913 
133914 /*
133915 ** FTS maintains a separate indexes for each language-id (a 32-bit integer).
133916 ** Within each language id, a separate index is maintained to store the
133917 ** document terms, and each configured prefix size (configured the FTS 
133918 ** "prefix=" option). And each index consists of multiple levels ("relative
133919 ** levels").
133920 **
133921 ** All three of these values (the language id, the specific index and the
133922 ** level within the index) are encoded in 64-bit integer values stored
133923 ** in the %_segdir table on disk. This function is used to convert three
133924 ** separate component values into the single 64-bit integer value that
133925 ** can be used to query the %_segdir table.
133926 **
133927 ** Specifically, each language-id/index combination is allocated 1024 
133928 ** 64-bit integer level values ("absolute levels"). The main terms index
133929 ** for language-id 0 is allocate values 0-1023. The first prefix index
133930 ** (if any) for language-id 0 is allocated values 1024-2047. And so on.
133931 ** Language 1 indexes are allocated immediately following language 0.
133932 **
133933 ** So, for a system with nPrefix prefix indexes configured, the block of
133934 ** absolute levels that corresponds to language-id iLangid and index 
133935 ** iIndex starts at absolute level ((iLangid * (nPrefix+1) + iIndex) * 1024).
133936 */
133937 static sqlite3_int64 getAbsoluteLevel(
133938   Fts3Table *p,                   /* FTS3 table handle */
133939   int iLangid,                    /* Language id */
133940   int iIndex,                     /* Index in p->aIndex[] */
133941   int iLevel                      /* Level of segments */
133942 ){
133943   sqlite3_int64 iBase;            /* First absolute level for iLangid/iIndex */
133944   assert( iLangid>=0 );
133945   assert( p->nIndex>0 );
133946   assert( iIndex>=0 && iIndex<p->nIndex );
133947 
133948   iBase = ((sqlite3_int64)iLangid * p->nIndex + iIndex) * FTS3_SEGDIR_MAXLEVEL;
133949   return iBase + iLevel;
133950 }
133951 
133952 /*
133953 ** Set *ppStmt to a statement handle that may be used to iterate through
133954 ** all rows in the %_segdir table, from oldest to newest. If successful,
133955 ** return SQLITE_OK. If an error occurs while preparing the statement, 
133956 ** return an SQLite error code.
133957 **
133958 ** There is only ever one instance of this SQL statement compiled for
133959 ** each FTS3 table.
133960 **
133961 ** The statement returns the following columns from the %_segdir table:
133962 **
133963 **   0: idx
133964 **   1: start_block
133965 **   2: leaves_end_block
133966 **   3: end_block
133967 **   4: root
133968 */
133969 SQLITE_PRIVATE int sqlite3Fts3AllSegdirs(
133970   Fts3Table *p,                   /* FTS3 table */
133971   int iLangid,                    /* Language being queried */
133972   int iIndex,                     /* Index for p->aIndex[] */
133973   int iLevel,                     /* Level to select (relative level) */
133974   sqlite3_stmt **ppStmt           /* OUT: Compiled statement */
133975 ){
133976   int rc;
133977   sqlite3_stmt *pStmt = 0;
133978 
133979   assert( iLevel==FTS3_SEGCURSOR_ALL || iLevel>=0 );
133980   assert( iLevel<FTS3_SEGDIR_MAXLEVEL );
133981   assert( iIndex>=0 && iIndex<p->nIndex );
133982 
133983   if( iLevel<0 ){
133984     /* "SELECT * FROM %_segdir WHERE level BETWEEN ? AND ? ORDER BY ..." */
133985     rc = fts3SqlStmt(p, SQL_SELECT_LEVEL_RANGE, &pStmt, 0);
133986     if( rc==SQLITE_OK ){ 
133987       sqlite3_bind_int64(pStmt, 1, getAbsoluteLevel(p, iLangid, iIndex, 0));
133988       sqlite3_bind_int64(pStmt, 2, 
133989           getAbsoluteLevel(p, iLangid, iIndex, FTS3_SEGDIR_MAXLEVEL-1)
133990       );
133991     }
133992   }else{
133993     /* "SELECT * FROM %_segdir WHERE level = ? ORDER BY ..." */
133994     rc = fts3SqlStmt(p, SQL_SELECT_LEVEL, &pStmt, 0);
133995     if( rc==SQLITE_OK ){ 
133996       sqlite3_bind_int64(pStmt, 1, getAbsoluteLevel(p, iLangid, iIndex,iLevel));
133997     }
133998   }
133999   *ppStmt = pStmt;
134000   return rc;
134001 }
134002 
134003 
134004 /*
134005 ** Append a single varint to a PendingList buffer. SQLITE_OK is returned
134006 ** if successful, or an SQLite error code otherwise.
134007 **
134008 ** This function also serves to allocate the PendingList structure itself.
134009 ** For example, to create a new PendingList structure containing two
134010 ** varints:
134011 **
134012 **   PendingList *p = 0;
134013 **   fts3PendingListAppendVarint(&p, 1);
134014 **   fts3PendingListAppendVarint(&p, 2);
134015 */
134016 static int fts3PendingListAppendVarint(
134017   PendingList **pp,               /* IN/OUT: Pointer to PendingList struct */
134018   sqlite3_int64 i                 /* Value to append to data */
134019 ){
134020   PendingList *p = *pp;
134021 
134022   /* Allocate or grow the PendingList as required. */
134023   if( !p ){
134024     p = sqlite3_malloc(sizeof(*p) + 100);
134025     if( !p ){
134026       return SQLITE_NOMEM;
134027     }
134028     p->nSpace = 100;
134029     p->aData = (char *)&p[1];
134030     p->nData = 0;
134031   }
134032   else if( p->nData+FTS3_VARINT_MAX+1>p->nSpace ){
134033     int nNew = p->nSpace * 2;
134034     p = sqlite3_realloc(p, sizeof(*p) + nNew);
134035     if( !p ){
134036       sqlite3_free(*pp);
134037       *pp = 0;
134038       return SQLITE_NOMEM;
134039     }
134040     p->nSpace = nNew;
134041     p->aData = (char *)&p[1];
134042   }
134043 
134044   /* Append the new serialized varint to the end of the list. */
134045   p->nData += sqlite3Fts3PutVarint(&p->aData[p->nData], i);
134046   p->aData[p->nData] = '\0';
134047   *pp = p;
134048   return SQLITE_OK;
134049 }
134050 
134051 /*
134052 ** Add a docid/column/position entry to a PendingList structure. Non-zero
134053 ** is returned if the structure is sqlite3_realloced as part of adding
134054 ** the entry. Otherwise, zero.
134055 **
134056 ** If an OOM error occurs, *pRc is set to SQLITE_NOMEM before returning.
134057 ** Zero is always returned in this case. Otherwise, if no OOM error occurs,
134058 ** it is set to SQLITE_OK.
134059 */
134060 static int fts3PendingListAppend(
134061   PendingList **pp,               /* IN/OUT: PendingList structure */
134062   sqlite3_int64 iDocid,           /* Docid for entry to add */
134063   sqlite3_int64 iCol,             /* Column for entry to add */
134064   sqlite3_int64 iPos,             /* Position of term for entry to add */
134065   int *pRc                        /* OUT: Return code */
134066 ){
134067   PendingList *p = *pp;
134068   int rc = SQLITE_OK;
134069 
134070   assert( !p || p->iLastDocid<=iDocid );
134071 
134072   if( !p || p->iLastDocid!=iDocid ){
134073     sqlite3_int64 iDelta = iDocid - (p ? p->iLastDocid : 0);
134074     if( p ){
134075       assert( p->nData<p->nSpace );
134076       assert( p->aData[p->nData]==0 );
134077       p->nData++;
134078     }
134079     if( SQLITE_OK!=(rc = fts3PendingListAppendVarint(&p, iDelta)) ){
134080       goto pendinglistappend_out;
134081     }
134082     p->iLastCol = -1;
134083     p->iLastPos = 0;
134084     p->iLastDocid = iDocid;
134085   }
134086   if( iCol>0 && p->iLastCol!=iCol ){
134087     if( SQLITE_OK!=(rc = fts3PendingListAppendVarint(&p, 1))
134088      || SQLITE_OK!=(rc = fts3PendingListAppendVarint(&p, iCol))
134089     ){
134090       goto pendinglistappend_out;
134091     }
134092     p->iLastCol = iCol;
134093     p->iLastPos = 0;
134094   }
134095   if( iCol>=0 ){
134096     assert( iPos>p->iLastPos || (iPos==0 && p->iLastPos==0) );
134097     rc = fts3PendingListAppendVarint(&p, 2+iPos-p->iLastPos);
134098     if( rc==SQLITE_OK ){
134099       p->iLastPos = iPos;
134100     }
134101   }
134102 
134103  pendinglistappend_out:
134104   *pRc = rc;
134105   if( p!=*pp ){
134106     *pp = p;
134107     return 1;
134108   }
134109   return 0;
134110 }
134111 
134112 /*
134113 ** Free a PendingList object allocated by fts3PendingListAppend().
134114 */
134115 static void fts3PendingListDelete(PendingList *pList){
134116   sqlite3_free(pList);
134117 }
134118 
134119 /*
134120 ** Add an entry to one of the pending-terms hash tables.
134121 */
134122 static int fts3PendingTermsAddOne(
134123   Fts3Table *p,
134124   int iCol,
134125   int iPos,
134126   Fts3Hash *pHash,                /* Pending terms hash table to add entry to */
134127   const char *zToken,
134128   int nToken
134129 ){
134130   PendingList *pList;
134131   int rc = SQLITE_OK;
134132 
134133   pList = (PendingList *)fts3HashFind(pHash, zToken, nToken);
134134   if( pList ){
134135     p->nPendingData -= (pList->nData + nToken + sizeof(Fts3HashElem));
134136   }
134137   if( fts3PendingListAppend(&pList, p->iPrevDocid, iCol, iPos, &rc) ){
134138     if( pList==fts3HashInsert(pHash, zToken, nToken, pList) ){
134139       /* Malloc failed while inserting the new entry. This can only 
134140       ** happen if there was no previous entry for this token.
134141       */
134142       assert( 0==fts3HashFind(pHash, zToken, nToken) );
134143       sqlite3_free(pList);
134144       rc = SQLITE_NOMEM;
134145     }
134146   }
134147   if( rc==SQLITE_OK ){
134148     p->nPendingData += (pList->nData + nToken + sizeof(Fts3HashElem));
134149   }
134150   return rc;
134151 }
134152 
134153 /*
134154 ** Tokenize the nul-terminated string zText and add all tokens to the
134155 ** pending-terms hash-table. The docid used is that currently stored in
134156 ** p->iPrevDocid, and the column is specified by argument iCol.
134157 **
134158 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code.
134159 */
134160 static int fts3PendingTermsAdd(
134161   Fts3Table *p,                   /* Table into which text will be inserted */
134162   int iLangid,                    /* Language id to use */
134163   const char *zText,              /* Text of document to be inserted */
134164   int iCol,                       /* Column into which text is being inserted */
134165   u32 *pnWord                     /* IN/OUT: Incr. by number tokens inserted */
134166 ){
134167   int rc;
134168   int iStart = 0;
134169   int iEnd = 0;
134170   int iPos = 0;
134171   int nWord = 0;
134172 
134173   char const *zToken;
134174   int nToken = 0;
134175 
134176   sqlite3_tokenizer *pTokenizer = p->pTokenizer;
134177   sqlite3_tokenizer_module const *pModule = pTokenizer->pModule;
134178   sqlite3_tokenizer_cursor *pCsr;
134179   int (*xNext)(sqlite3_tokenizer_cursor *pCursor,
134180       const char**,int*,int*,int*,int*);
134181 
134182   assert( pTokenizer && pModule );
134183 
134184   /* If the user has inserted a NULL value, this function may be called with
134185   ** zText==0. In this case, add zero token entries to the hash table and 
134186   ** return early. */
134187   if( zText==0 ){
134188     *pnWord = 0;
134189     return SQLITE_OK;
134190   }
134191 
134192   rc = sqlite3Fts3OpenTokenizer(pTokenizer, iLangid, zText, -1, &pCsr);
134193   if( rc!=SQLITE_OK ){
134194     return rc;
134195   }
134196 
134197   xNext = pModule->xNext;
134198   while( SQLITE_OK==rc
134199       && SQLITE_OK==(rc = xNext(pCsr, &zToken, &nToken, &iStart, &iEnd, &iPos))
134200   ){
134201     int i;
134202     if( iPos>=nWord ) nWord = iPos+1;
134203 
134204     /* Positions cannot be negative; we use -1 as a terminator internally.
134205     ** Tokens must have a non-zero length.
134206     */
134207     if( iPos<0 || !zToken || nToken<=0 ){
134208       rc = SQLITE_ERROR;
134209       break;
134210     }
134211 
134212     /* Add the term to the terms index */
134213     rc = fts3PendingTermsAddOne(
134214         p, iCol, iPos, &p->aIndex[0].hPending, zToken, nToken
134215     );
134216     
134217     /* Add the term to each of the prefix indexes that it is not too 
134218     ** short for. */
134219     for(i=1; rc==SQLITE_OK && i<p->nIndex; i++){
134220       struct Fts3Index *pIndex = &p->aIndex[i];
134221       if( nToken<pIndex->nPrefix ) continue;
134222       rc = fts3PendingTermsAddOne(
134223           p, iCol, iPos, &pIndex->hPending, zToken, pIndex->nPrefix
134224       );
134225     }
134226   }
134227 
134228   pModule->xClose(pCsr);
134229   *pnWord += nWord;
134230   return (rc==SQLITE_DONE ? SQLITE_OK : rc);
134231 }
134232 
134233 /* 
134234 ** Calling this function indicates that subsequent calls to 
134235 ** fts3PendingTermsAdd() are to add term/position-list pairs for the
134236 ** contents of the document with docid iDocid.
134237 */
134238 static int fts3PendingTermsDocid(
134239   Fts3Table *p,                   /* Full-text table handle */
134240   int iLangid,                    /* Language id of row being written */
134241   sqlite_int64 iDocid             /* Docid of row being written */
134242 ){
134243   assert( iLangid>=0 );
134244 
134245   /* TODO(shess) Explore whether partially flushing the buffer on
134246   ** forced-flush would provide better performance.  I suspect that if
134247   ** we ordered the doclists by size and flushed the largest until the
134248   ** buffer was half empty, that would let the less frequent terms
134249   ** generate longer doclists.
134250   */
134251   if( iDocid<=p->iPrevDocid 
134252    || p->iPrevLangid!=iLangid
134253    || p->nPendingData>p->nMaxPendingData 
134254   ){
134255     int rc = sqlite3Fts3PendingTermsFlush(p);
134256     if( rc!=SQLITE_OK ) return rc;
134257   }
134258   p->iPrevDocid = iDocid;
134259   p->iPrevLangid = iLangid;
134260   return SQLITE_OK;
134261 }
134262 
134263 /*
134264 ** Discard the contents of the pending-terms hash tables. 
134265 */
134266 SQLITE_PRIVATE void sqlite3Fts3PendingTermsClear(Fts3Table *p){
134267   int i;
134268   for(i=0; i<p->nIndex; i++){
134269     Fts3HashElem *pElem;
134270     Fts3Hash *pHash = &p->aIndex[i].hPending;
134271     for(pElem=fts3HashFirst(pHash); pElem; pElem=fts3HashNext(pElem)){
134272       PendingList *pList = (PendingList *)fts3HashData(pElem);
134273       fts3PendingListDelete(pList);
134274     }
134275     fts3HashClear(pHash);
134276   }
134277   p->nPendingData = 0;
134278 }
134279 
134280 /*
134281 ** This function is called by the xUpdate() method as part of an INSERT
134282 ** operation. It adds entries for each term in the new record to the
134283 ** pendingTerms hash table.
134284 **
134285 ** Argument apVal is the same as the similarly named argument passed to
134286 ** fts3InsertData(). Parameter iDocid is the docid of the new row.
134287 */
134288 static int fts3InsertTerms(
134289   Fts3Table *p, 
134290   int iLangid, 
134291   sqlite3_value **apVal, 
134292   u32 *aSz
134293 ){
134294   int i;                          /* Iterator variable */
134295   for(i=2; i<p->nColumn+2; i++){
134296     int iCol = i-2;
134297     if( p->abNotindexed[iCol]==0 ){
134298       const char *zText = (const char *)sqlite3_value_text(apVal[i]);
134299       int rc = fts3PendingTermsAdd(p, iLangid, zText, iCol, &aSz[iCol]);
134300       if( rc!=SQLITE_OK ){
134301         return rc;
134302       }
134303       aSz[p->nColumn] += sqlite3_value_bytes(apVal[i]);
134304     }
134305   }
134306   return SQLITE_OK;
134307 }
134308 
134309 /*
134310 ** This function is called by the xUpdate() method for an INSERT operation.
134311 ** The apVal parameter is passed a copy of the apVal argument passed by
134312 ** SQLite to the xUpdate() method. i.e:
134313 **
134314 **   apVal[0]                Not used for INSERT.
134315 **   apVal[1]                rowid
134316 **   apVal[2]                Left-most user-defined column
134317 **   ...
134318 **   apVal[p->nColumn+1]     Right-most user-defined column
134319 **   apVal[p->nColumn+2]     Hidden column with same name as table
134320 **   apVal[p->nColumn+3]     Hidden "docid" column (alias for rowid)
134321 **   apVal[p->nColumn+4]     Hidden languageid column
134322 */
134323 static int fts3InsertData(
134324   Fts3Table *p,                   /* Full-text table */
134325   sqlite3_value **apVal,          /* Array of values to insert */
134326   sqlite3_int64 *piDocid          /* OUT: Docid for row just inserted */
134327 ){
134328   int rc;                         /* Return code */
134329   sqlite3_stmt *pContentInsert;   /* INSERT INTO %_content VALUES(...) */
134330 
134331   if( p->zContentTbl ){
134332     sqlite3_value *pRowid = apVal[p->nColumn+3];
134333     if( sqlite3_value_type(pRowid)==SQLITE_NULL ){
134334       pRowid = apVal[1];
134335     }
134336     if( sqlite3_value_type(pRowid)!=SQLITE_INTEGER ){
134337       return SQLITE_CONSTRAINT;
134338     }
134339     *piDocid = sqlite3_value_int64(pRowid);
134340     return SQLITE_OK;
134341   }
134342 
134343   /* Locate the statement handle used to insert data into the %_content
134344   ** table. The SQL for this statement is:
134345   **
134346   **   INSERT INTO %_content VALUES(?, ?, ?, ...)
134347   **
134348   ** The statement features N '?' variables, where N is the number of user
134349   ** defined columns in the FTS3 table, plus one for the docid field.
134350   */
134351   rc = fts3SqlStmt(p, SQL_CONTENT_INSERT, &pContentInsert, &apVal[1]);
134352   if( rc==SQLITE_OK && p->zLanguageid ){
134353     rc = sqlite3_bind_int(
134354         pContentInsert, p->nColumn+2, 
134355         sqlite3_value_int(apVal[p->nColumn+4])
134356     );
134357   }
134358   if( rc!=SQLITE_OK ) return rc;
134359 
134360   /* There is a quirk here. The users INSERT statement may have specified
134361   ** a value for the "rowid" field, for the "docid" field, or for both.
134362   ** Which is a problem, since "rowid" and "docid" are aliases for the
134363   ** same value. For example:
134364   **
134365   **   INSERT INTO fts3tbl(rowid, docid) VALUES(1, 2);
134366   **
134367   ** In FTS3, this is an error. It is an error to specify non-NULL values
134368   ** for both docid and some other rowid alias.
134369   */
134370   if( SQLITE_NULL!=sqlite3_value_type(apVal[3+p->nColumn]) ){
134371     if( SQLITE_NULL==sqlite3_value_type(apVal[0])
134372      && SQLITE_NULL!=sqlite3_value_type(apVal[1])
134373     ){
134374       /* A rowid/docid conflict. */
134375       return SQLITE_ERROR;
134376     }
134377     rc = sqlite3_bind_value(pContentInsert, 1, apVal[3+p->nColumn]);
134378     if( rc!=SQLITE_OK ) return rc;
134379   }
134380 
134381   /* Execute the statement to insert the record. Set *piDocid to the 
134382   ** new docid value. 
134383   */
134384   sqlite3_step(pContentInsert);
134385   rc = sqlite3_reset(pContentInsert);
134386 
134387   *piDocid = sqlite3_last_insert_rowid(p->db);
134388   return rc;
134389 }
134390 
134391 
134392 
134393 /*
134394 ** Remove all data from the FTS3 table. Clear the hash table containing
134395 ** pending terms.
134396 */
134397 static int fts3DeleteAll(Fts3Table *p, int bContent){
134398   int rc = SQLITE_OK;             /* Return code */
134399 
134400   /* Discard the contents of the pending-terms hash table. */
134401   sqlite3Fts3PendingTermsClear(p);
134402 
134403   /* Delete everything from the shadow tables. Except, leave %_content as
134404   ** is if bContent is false.  */
134405   assert( p->zContentTbl==0 || bContent==0 );
134406   if( bContent ) fts3SqlExec(&rc, p, SQL_DELETE_ALL_CONTENT, 0);
134407   fts3SqlExec(&rc, p, SQL_DELETE_ALL_SEGMENTS, 0);
134408   fts3SqlExec(&rc, p, SQL_DELETE_ALL_SEGDIR, 0);
134409   if( p->bHasDocsize ){
134410     fts3SqlExec(&rc, p, SQL_DELETE_ALL_DOCSIZE, 0);
134411   }
134412   if( p->bHasStat ){
134413     fts3SqlExec(&rc, p, SQL_DELETE_ALL_STAT, 0);
134414   }
134415   return rc;
134416 }
134417 
134418 /*
134419 **
134420 */
134421 static int langidFromSelect(Fts3Table *p, sqlite3_stmt *pSelect){
134422   int iLangid = 0;
134423   if( p->zLanguageid ) iLangid = sqlite3_column_int(pSelect, p->nColumn+1);
134424   return iLangid;
134425 }
134426 
134427 /*
134428 ** The first element in the apVal[] array is assumed to contain the docid
134429 ** (an integer) of a row about to be deleted. Remove all terms from the
134430 ** full-text index.
134431 */
134432 static void fts3DeleteTerms( 
134433   int *pRC,               /* Result code */
134434   Fts3Table *p,           /* The FTS table to delete from */
134435   sqlite3_value *pRowid,  /* The docid to be deleted */
134436   u32 *aSz,               /* Sizes of deleted document written here */
134437   int *pbFound            /* OUT: Set to true if row really does exist */
134438 ){
134439   int rc;
134440   sqlite3_stmt *pSelect;
134441 
134442   assert( *pbFound==0 );
134443   if( *pRC ) return;
134444   rc = fts3SqlStmt(p, SQL_SELECT_CONTENT_BY_ROWID, &pSelect, &pRowid);
134445   if( rc==SQLITE_OK ){
134446     if( SQLITE_ROW==sqlite3_step(pSelect) ){
134447       int i;
134448       int iLangid = langidFromSelect(p, pSelect);
134449       rc = fts3PendingTermsDocid(p, iLangid, sqlite3_column_int64(pSelect, 0));
134450       for(i=1; rc==SQLITE_OK && i<=p->nColumn; i++){
134451         int iCol = i-1;
134452         if( p->abNotindexed[iCol]==0 ){
134453           const char *zText = (const char *)sqlite3_column_text(pSelect, i);
134454           rc = fts3PendingTermsAdd(p, iLangid, zText, -1, &aSz[iCol]);
134455           aSz[p->nColumn] += sqlite3_column_bytes(pSelect, i);
134456         }
134457       }
134458       if( rc!=SQLITE_OK ){
134459         sqlite3_reset(pSelect);
134460         *pRC = rc;
134461         return;
134462       }
134463       *pbFound = 1;
134464     }
134465     rc = sqlite3_reset(pSelect);
134466   }else{
134467     sqlite3_reset(pSelect);
134468   }
134469   *pRC = rc;
134470 }
134471 
134472 /*
134473 ** Forward declaration to account for the circular dependency between
134474 ** functions fts3SegmentMerge() and fts3AllocateSegdirIdx().
134475 */
134476 static int fts3SegmentMerge(Fts3Table *, int, int, int);
134477 
134478 /* 
134479 ** This function allocates a new level iLevel index in the segdir table.
134480 ** Usually, indexes are allocated within a level sequentially starting
134481 ** with 0, so the allocated index is one greater than the value returned
134482 ** by:
134483 **
134484 **   SELECT max(idx) FROM %_segdir WHERE level = :iLevel
134485 **
134486 ** However, if there are already FTS3_MERGE_COUNT indexes at the requested
134487 ** level, they are merged into a single level (iLevel+1) segment and the 
134488 ** allocated index is 0.
134489 **
134490 ** If successful, *piIdx is set to the allocated index slot and SQLITE_OK
134491 ** returned. Otherwise, an SQLite error code is returned.
134492 */
134493 static int fts3AllocateSegdirIdx(
134494   Fts3Table *p, 
134495   int iLangid,                    /* Language id */
134496   int iIndex,                     /* Index for p->aIndex */
134497   int iLevel, 
134498   int *piIdx
134499 ){
134500   int rc;                         /* Return Code */
134501   sqlite3_stmt *pNextIdx;         /* Query for next idx at level iLevel */
134502   int iNext = 0;                  /* Result of query pNextIdx */
134503 
134504   assert( iLangid>=0 );
134505   assert( p->nIndex>=1 );
134506 
134507   /* Set variable iNext to the next available segdir index at level iLevel. */
134508   rc = fts3SqlStmt(p, SQL_NEXT_SEGMENT_INDEX, &pNextIdx, 0);
134509   if( rc==SQLITE_OK ){
134510     sqlite3_bind_int64(
134511         pNextIdx, 1, getAbsoluteLevel(p, iLangid, iIndex, iLevel)
134512     );
134513     if( SQLITE_ROW==sqlite3_step(pNextIdx) ){
134514       iNext = sqlite3_column_int(pNextIdx, 0);
134515     }
134516     rc = sqlite3_reset(pNextIdx);
134517   }
134518 
134519   if( rc==SQLITE_OK ){
134520     /* If iNext is FTS3_MERGE_COUNT, indicating that level iLevel is already
134521     ** full, merge all segments in level iLevel into a single iLevel+1
134522     ** segment and allocate (newly freed) index 0 at level iLevel. Otherwise,
134523     ** if iNext is less than FTS3_MERGE_COUNT, allocate index iNext.
134524     */
134525     if( iNext>=FTS3_MERGE_COUNT ){
134526       fts3LogMerge(16, getAbsoluteLevel(p, iLangid, iIndex, iLevel));
134527       rc = fts3SegmentMerge(p, iLangid, iIndex, iLevel);
134528       *piIdx = 0;
134529     }else{
134530       *piIdx = iNext;
134531     }
134532   }
134533 
134534   return rc;
134535 }
134536 
134537 /*
134538 ** The %_segments table is declared as follows:
134539 **
134540 **   CREATE TABLE %_segments(blockid INTEGER PRIMARY KEY, block BLOB)
134541 **
134542 ** This function reads data from a single row of the %_segments table. The
134543 ** specific row is identified by the iBlockid parameter. If paBlob is not
134544 ** NULL, then a buffer is allocated using sqlite3_malloc() and populated
134545 ** with the contents of the blob stored in the "block" column of the 
134546 ** identified table row is. Whether or not paBlob is NULL, *pnBlob is set
134547 ** to the size of the blob in bytes before returning.
134548 **
134549 ** If an error occurs, or the table does not contain the specified row,
134550 ** an SQLite error code is returned. Otherwise, SQLITE_OK is returned. If
134551 ** paBlob is non-NULL, then it is the responsibility of the caller to
134552 ** eventually free the returned buffer.
134553 **
134554 ** This function may leave an open sqlite3_blob* handle in the
134555 ** Fts3Table.pSegments variable. This handle is reused by subsequent calls
134556 ** to this function. The handle may be closed by calling the
134557 ** sqlite3Fts3SegmentsClose() function. Reusing a blob handle is a handy
134558 ** performance improvement, but the blob handle should always be closed
134559 ** before control is returned to the user (to prevent a lock being held
134560 ** on the database file for longer than necessary). Thus, any virtual table
134561 ** method (xFilter etc.) that may directly or indirectly call this function
134562 ** must call sqlite3Fts3SegmentsClose() before returning.
134563 */
134564 SQLITE_PRIVATE int sqlite3Fts3ReadBlock(
134565   Fts3Table *p,                   /* FTS3 table handle */
134566   sqlite3_int64 iBlockid,         /* Access the row with blockid=$iBlockid */
134567   char **paBlob,                  /* OUT: Blob data in malloc'd buffer */
134568   int *pnBlob,                    /* OUT: Size of blob data */
134569   int *pnLoad                     /* OUT: Bytes actually loaded */
134570 ){
134571   int rc;                         /* Return code */
134572 
134573   /* pnBlob must be non-NULL. paBlob may be NULL or non-NULL. */
134574   assert( pnBlob );
134575 
134576   if( p->pSegments ){
134577     rc = sqlite3_blob_reopen(p->pSegments, iBlockid);
134578   }else{
134579     if( 0==p->zSegmentsTbl ){
134580       p->zSegmentsTbl = sqlite3_mprintf("%s_segments", p->zName);
134581       if( 0==p->zSegmentsTbl ) return SQLITE_NOMEM;
134582     }
134583     rc = sqlite3_blob_open(
134584        p->db, p->zDb, p->zSegmentsTbl, "block", iBlockid, 0, &p->pSegments
134585     );
134586   }
134587 
134588   if( rc==SQLITE_OK ){
134589     int nByte = sqlite3_blob_bytes(p->pSegments);
134590     *pnBlob = nByte;
134591     if( paBlob ){
134592       char *aByte = sqlite3_malloc(nByte + FTS3_NODE_PADDING);
134593       if( !aByte ){
134594         rc = SQLITE_NOMEM;
134595       }else{
134596         if( pnLoad && nByte>(FTS3_NODE_CHUNK_THRESHOLD) ){
134597           nByte = FTS3_NODE_CHUNKSIZE;
134598           *pnLoad = nByte;
134599         }
134600         rc = sqlite3_blob_read(p->pSegments, aByte, nByte, 0);
134601         memset(&aByte[nByte], 0, FTS3_NODE_PADDING);
134602         if( rc!=SQLITE_OK ){
134603           sqlite3_free(aByte);
134604           aByte = 0;
134605         }
134606       }
134607       *paBlob = aByte;
134608     }
134609   }
134610 
134611   return rc;
134612 }
134613 
134614 /*
134615 ** Close the blob handle at p->pSegments, if it is open. See comments above
134616 ** the sqlite3Fts3ReadBlock() function for details.
134617 */
134618 SQLITE_PRIVATE void sqlite3Fts3SegmentsClose(Fts3Table *p){
134619   sqlite3_blob_close(p->pSegments);
134620   p->pSegments = 0;
134621 }
134622     
134623 static int fts3SegReaderIncrRead(Fts3SegReader *pReader){
134624   int nRead;                      /* Number of bytes to read */
134625   int rc;                         /* Return code */
134626 
134627   nRead = MIN(pReader->nNode - pReader->nPopulate, FTS3_NODE_CHUNKSIZE);
134628   rc = sqlite3_blob_read(
134629       pReader->pBlob, 
134630       &pReader->aNode[pReader->nPopulate],
134631       nRead,
134632       pReader->nPopulate
134633   );
134634 
134635   if( rc==SQLITE_OK ){
134636     pReader->nPopulate += nRead;
134637     memset(&pReader->aNode[pReader->nPopulate], 0, FTS3_NODE_PADDING);
134638     if( pReader->nPopulate==pReader->nNode ){
134639       sqlite3_blob_close(pReader->pBlob);
134640       pReader->pBlob = 0;
134641       pReader->nPopulate = 0;
134642     }
134643   }
134644   return rc;
134645 }
134646 
134647 static int fts3SegReaderRequire(Fts3SegReader *pReader, char *pFrom, int nByte){
134648   int rc = SQLITE_OK;
134649   assert( !pReader->pBlob 
134650        || (pFrom>=pReader->aNode && pFrom<&pReader->aNode[pReader->nNode])
134651   );
134652   while( pReader->pBlob && rc==SQLITE_OK 
134653      &&  (pFrom - pReader->aNode + nByte)>pReader->nPopulate
134654   ){
134655     rc = fts3SegReaderIncrRead(pReader);
134656   }
134657   return rc;
134658 }
134659 
134660 /*
134661 ** Set an Fts3SegReader cursor to point at EOF.
134662 */
134663 static void fts3SegReaderSetEof(Fts3SegReader *pSeg){
134664   if( !fts3SegReaderIsRootOnly(pSeg) ){
134665     sqlite3_free(pSeg->aNode);
134666     sqlite3_blob_close(pSeg->pBlob);
134667     pSeg->pBlob = 0;
134668   }
134669   pSeg->aNode = 0;
134670 }
134671 
134672 /*
134673 ** Move the iterator passed as the first argument to the next term in the
134674 ** segment. If successful, SQLITE_OK is returned. If there is no next term,
134675 ** SQLITE_DONE. Otherwise, an SQLite error code.
134676 */
134677 static int fts3SegReaderNext(
134678   Fts3Table *p, 
134679   Fts3SegReader *pReader,
134680   int bIncr
134681 ){
134682   int rc;                         /* Return code of various sub-routines */
134683   char *pNext;                    /* Cursor variable */
134684   int nPrefix;                    /* Number of bytes in term prefix */
134685   int nSuffix;                    /* Number of bytes in term suffix */
134686 
134687   if( !pReader->aDoclist ){
134688     pNext = pReader->aNode;
134689   }else{
134690     pNext = &pReader->aDoclist[pReader->nDoclist];
134691   }
134692 
134693   if( !pNext || pNext>=&pReader->aNode[pReader->nNode] ){
134694 
134695     if( fts3SegReaderIsPending(pReader) ){
134696       Fts3HashElem *pElem = *(pReader->ppNextElem);
134697       if( pElem==0 ){
134698         pReader->aNode = 0;
134699       }else{
134700         PendingList *pList = (PendingList *)fts3HashData(pElem);
134701         pReader->zTerm = (char *)fts3HashKey(pElem);
134702         pReader->nTerm = fts3HashKeysize(pElem);
134703         pReader->nNode = pReader->nDoclist = pList->nData + 1;
134704         pReader->aNode = pReader->aDoclist = pList->aData;
134705         pReader->ppNextElem++;
134706         assert( pReader->aNode );
134707       }
134708       return SQLITE_OK;
134709     }
134710 
134711     fts3SegReaderSetEof(pReader);
134712 
134713     /* If iCurrentBlock>=iLeafEndBlock, this is an EOF condition. All leaf 
134714     ** blocks have already been traversed.  */
134715     assert( pReader->iCurrentBlock<=pReader->iLeafEndBlock );
134716     if( pReader->iCurrentBlock>=pReader->iLeafEndBlock ){
134717       return SQLITE_OK;
134718     }
134719 
134720     rc = sqlite3Fts3ReadBlock(
134721         p, ++pReader->iCurrentBlock, &pReader->aNode, &pReader->nNode, 
134722         (bIncr ? &pReader->nPopulate : 0)
134723     );
134724     if( rc!=SQLITE_OK ) return rc;
134725     assert( pReader->pBlob==0 );
134726     if( bIncr && pReader->nPopulate<pReader->nNode ){
134727       pReader->pBlob = p->pSegments;
134728       p->pSegments = 0;
134729     }
134730     pNext = pReader->aNode;
134731   }
134732 
134733   assert( !fts3SegReaderIsPending(pReader) );
134734 
134735   rc = fts3SegReaderRequire(pReader, pNext, FTS3_VARINT_MAX*2);
134736   if( rc!=SQLITE_OK ) return rc;
134737   
134738   /* Because of the FTS3_NODE_PADDING bytes of padding, the following is 
134739   ** safe (no risk of overread) even if the node data is corrupted. */
134740   pNext += fts3GetVarint32(pNext, &nPrefix);
134741   pNext += fts3GetVarint32(pNext, &nSuffix);
134742   if( nPrefix<0 || nSuffix<=0 
134743    || &pNext[nSuffix]>&pReader->aNode[pReader->nNode] 
134744   ){
134745     return FTS_CORRUPT_VTAB;
134746   }
134747 
134748   if( nPrefix+nSuffix>pReader->nTermAlloc ){
134749     int nNew = (nPrefix+nSuffix)*2;
134750     char *zNew = sqlite3_realloc(pReader->zTerm, nNew);
134751     if( !zNew ){
134752       return SQLITE_NOMEM;
134753     }
134754     pReader->zTerm = zNew;
134755     pReader->nTermAlloc = nNew;
134756   }
134757 
134758   rc = fts3SegReaderRequire(pReader, pNext, nSuffix+FTS3_VARINT_MAX);
134759   if( rc!=SQLITE_OK ) return rc;
134760 
134761   memcpy(&pReader->zTerm[nPrefix], pNext, nSuffix);
134762   pReader->nTerm = nPrefix+nSuffix;
134763   pNext += nSuffix;
134764   pNext += fts3GetVarint32(pNext, &pReader->nDoclist);
134765   pReader->aDoclist = pNext;
134766   pReader->pOffsetList = 0;
134767 
134768   /* Check that the doclist does not appear to extend past the end of the
134769   ** b-tree node. And that the final byte of the doclist is 0x00. If either 
134770   ** of these statements is untrue, then the data structure is corrupt.
134771   */
134772   if( &pReader->aDoclist[pReader->nDoclist]>&pReader->aNode[pReader->nNode] 
134773    || (pReader->nPopulate==0 && pReader->aDoclist[pReader->nDoclist-1])
134774   ){
134775     return FTS_CORRUPT_VTAB;
134776   }
134777   return SQLITE_OK;
134778 }
134779 
134780 /*
134781 ** Set the SegReader to point to the first docid in the doclist associated
134782 ** with the current term.
134783 */
134784 static int fts3SegReaderFirstDocid(Fts3Table *pTab, Fts3SegReader *pReader){
134785   int rc = SQLITE_OK;
134786   assert( pReader->aDoclist );
134787   assert( !pReader->pOffsetList );
134788   if( pTab->bDescIdx && fts3SegReaderIsPending(pReader) ){
134789     u8 bEof = 0;
134790     pReader->iDocid = 0;
134791     pReader->nOffsetList = 0;
134792     sqlite3Fts3DoclistPrev(0,
134793         pReader->aDoclist, pReader->nDoclist, &pReader->pOffsetList, 
134794         &pReader->iDocid, &pReader->nOffsetList, &bEof
134795     );
134796   }else{
134797     rc = fts3SegReaderRequire(pReader, pReader->aDoclist, FTS3_VARINT_MAX);
134798     if( rc==SQLITE_OK ){
134799       int n = sqlite3Fts3GetVarint(pReader->aDoclist, &pReader->iDocid);
134800       pReader->pOffsetList = &pReader->aDoclist[n];
134801     }
134802   }
134803   return rc;
134804 }
134805 
134806 /*
134807 ** Advance the SegReader to point to the next docid in the doclist
134808 ** associated with the current term.
134809 ** 
134810 ** If arguments ppOffsetList and pnOffsetList are not NULL, then 
134811 ** *ppOffsetList is set to point to the first column-offset list
134812 ** in the doclist entry (i.e. immediately past the docid varint).
134813 ** *pnOffsetList is set to the length of the set of column-offset
134814 ** lists, not including the nul-terminator byte. For example:
134815 */
134816 static int fts3SegReaderNextDocid(
134817   Fts3Table *pTab,
134818   Fts3SegReader *pReader,         /* Reader to advance to next docid */
134819   char **ppOffsetList,            /* OUT: Pointer to current position-list */
134820   int *pnOffsetList               /* OUT: Length of *ppOffsetList in bytes */
134821 ){
134822   int rc = SQLITE_OK;
134823   char *p = pReader->pOffsetList;
134824   char c = 0;
134825 
134826   assert( p );
134827 
134828   if( pTab->bDescIdx && fts3SegReaderIsPending(pReader) ){
134829     /* A pending-terms seg-reader for an FTS4 table that uses order=desc.
134830     ** Pending-terms doclists are always built up in ascending order, so
134831     ** we have to iterate through them backwards here. */
134832     u8 bEof = 0;
134833     if( ppOffsetList ){
134834       *ppOffsetList = pReader->pOffsetList;
134835       *pnOffsetList = pReader->nOffsetList - 1;
134836     }
134837     sqlite3Fts3DoclistPrev(0,
134838         pReader->aDoclist, pReader->nDoclist, &p, &pReader->iDocid,
134839         &pReader->nOffsetList, &bEof
134840     );
134841     if( bEof ){
134842       pReader->pOffsetList = 0;
134843     }else{
134844       pReader->pOffsetList = p;
134845     }
134846   }else{
134847     char *pEnd = &pReader->aDoclist[pReader->nDoclist];
134848 
134849     /* Pointer p currently points at the first byte of an offset list. The
134850     ** following block advances it to point one byte past the end of
134851     ** the same offset list. */
134852     while( 1 ){
134853   
134854       /* The following line of code (and the "p++" below the while() loop) is
134855       ** normally all that is required to move pointer p to the desired 
134856       ** position. The exception is if this node is being loaded from disk
134857       ** incrementally and pointer "p" now points to the first byte past
134858       ** the populated part of pReader->aNode[].
134859       */
134860       while( *p | c ) c = *p++ & 0x80;
134861       assert( *p==0 );
134862   
134863       if( pReader->pBlob==0 || p<&pReader->aNode[pReader->nPopulate] ) break;
134864       rc = fts3SegReaderIncrRead(pReader);
134865       if( rc!=SQLITE_OK ) return rc;
134866     }
134867     p++;
134868   
134869     /* If required, populate the output variables with a pointer to and the
134870     ** size of the previous offset-list.
134871     */
134872     if( ppOffsetList ){
134873       *ppOffsetList = pReader->pOffsetList;
134874       *pnOffsetList = (int)(p - pReader->pOffsetList - 1);
134875     }
134876 
134877     /* List may have been edited in place by fts3EvalNearTrim() */
134878     while( p<pEnd && *p==0 ) p++;
134879   
134880     /* If there are no more entries in the doclist, set pOffsetList to
134881     ** NULL. Otherwise, set Fts3SegReader.iDocid to the next docid and
134882     ** Fts3SegReader.pOffsetList to point to the next offset list before
134883     ** returning.
134884     */
134885     if( p>=pEnd ){
134886       pReader->pOffsetList = 0;
134887     }else{
134888       rc = fts3SegReaderRequire(pReader, p, FTS3_VARINT_MAX);
134889       if( rc==SQLITE_OK ){
134890         sqlite3_int64 iDelta;
134891         pReader->pOffsetList = p + sqlite3Fts3GetVarint(p, &iDelta);
134892         if( pTab->bDescIdx ){
134893           pReader->iDocid -= iDelta;
134894         }else{
134895           pReader->iDocid += iDelta;
134896         }
134897       }
134898     }
134899   }
134900 
134901   return SQLITE_OK;
134902 }
134903 
134904 
134905 SQLITE_PRIVATE int sqlite3Fts3MsrOvfl(
134906   Fts3Cursor *pCsr, 
134907   Fts3MultiSegReader *pMsr,
134908   int *pnOvfl
134909 ){
134910   Fts3Table *p = (Fts3Table*)pCsr->base.pVtab;
134911   int nOvfl = 0;
134912   int ii;
134913   int rc = SQLITE_OK;
134914   int pgsz = p->nPgsz;
134915 
134916   assert( p->bFts4 );
134917   assert( pgsz>0 );
134918 
134919   for(ii=0; rc==SQLITE_OK && ii<pMsr->nSegment; ii++){
134920     Fts3SegReader *pReader = pMsr->apSegment[ii];
134921     if( !fts3SegReaderIsPending(pReader) 
134922      && !fts3SegReaderIsRootOnly(pReader) 
134923     ){
134924       sqlite3_int64 jj;
134925       for(jj=pReader->iStartBlock; jj<=pReader->iLeafEndBlock; jj++){
134926         int nBlob;
134927         rc = sqlite3Fts3ReadBlock(p, jj, 0, &nBlob, 0);
134928         if( rc!=SQLITE_OK ) break;
134929         if( (nBlob+35)>pgsz ){
134930           nOvfl += (nBlob + 34)/pgsz;
134931         }
134932       }
134933     }
134934   }
134935   *pnOvfl = nOvfl;
134936   return rc;
134937 }
134938 
134939 /*
134940 ** Free all allocations associated with the iterator passed as the 
134941 ** second argument.
134942 */
134943 SQLITE_PRIVATE void sqlite3Fts3SegReaderFree(Fts3SegReader *pReader){
134944   if( pReader && !fts3SegReaderIsPending(pReader) ){
134945     sqlite3_free(pReader->zTerm);
134946     if( !fts3SegReaderIsRootOnly(pReader) ){
134947       sqlite3_free(pReader->aNode);
134948       sqlite3_blob_close(pReader->pBlob);
134949     }
134950   }
134951   sqlite3_free(pReader);
134952 }
134953 
134954 /*
134955 ** Allocate a new SegReader object.
134956 */
134957 SQLITE_PRIVATE int sqlite3Fts3SegReaderNew(
134958   int iAge,                       /* Segment "age". */
134959   int bLookup,                    /* True for a lookup only */
134960   sqlite3_int64 iStartLeaf,       /* First leaf to traverse */
134961   sqlite3_int64 iEndLeaf,         /* Final leaf to traverse */
134962   sqlite3_int64 iEndBlock,        /* Final block of segment */
134963   const char *zRoot,              /* Buffer containing root node */
134964   int nRoot,                      /* Size of buffer containing root node */
134965   Fts3SegReader **ppReader        /* OUT: Allocated Fts3SegReader */
134966 ){
134967   Fts3SegReader *pReader;         /* Newly allocated SegReader object */
134968   int nExtra = 0;                 /* Bytes to allocate segment root node */
134969 
134970   assert( iStartLeaf<=iEndLeaf );
134971   if( iStartLeaf==0 ){
134972     nExtra = nRoot + FTS3_NODE_PADDING;
134973   }
134974 
134975   pReader = (Fts3SegReader *)sqlite3_malloc(sizeof(Fts3SegReader) + nExtra);
134976   if( !pReader ){
134977     return SQLITE_NOMEM;
134978   }
134979   memset(pReader, 0, sizeof(Fts3SegReader));
134980   pReader->iIdx = iAge;
134981   pReader->bLookup = bLookup!=0;
134982   pReader->iStartBlock = iStartLeaf;
134983   pReader->iLeafEndBlock = iEndLeaf;
134984   pReader->iEndBlock = iEndBlock;
134985 
134986   if( nExtra ){
134987     /* The entire segment is stored in the root node. */
134988     pReader->aNode = (char *)&pReader[1];
134989     pReader->rootOnly = 1;
134990     pReader->nNode = nRoot;
134991     memcpy(pReader->aNode, zRoot, nRoot);
134992     memset(&pReader->aNode[nRoot], 0, FTS3_NODE_PADDING);
134993   }else{
134994     pReader->iCurrentBlock = iStartLeaf-1;
134995   }
134996   *ppReader = pReader;
134997   return SQLITE_OK;
134998 }
134999 
135000 /*
135001 ** This is a comparison function used as a qsort() callback when sorting
135002 ** an array of pending terms by term. This occurs as part of flushing
135003 ** the contents of the pending-terms hash table to the database.
135004 */
135005 static int fts3CompareElemByTerm(const void *lhs, const void *rhs){
135006   char *z1 = fts3HashKey(*(Fts3HashElem **)lhs);
135007   char *z2 = fts3HashKey(*(Fts3HashElem **)rhs);
135008   int n1 = fts3HashKeysize(*(Fts3HashElem **)lhs);
135009   int n2 = fts3HashKeysize(*(Fts3HashElem **)rhs);
135010 
135011   int n = (n1<n2 ? n1 : n2);
135012   int c = memcmp(z1, z2, n);
135013   if( c==0 ){
135014     c = n1 - n2;
135015   }
135016   return c;
135017 }
135018 
135019 /*
135020 ** This function is used to allocate an Fts3SegReader that iterates through
135021 ** a subset of the terms stored in the Fts3Table.pendingTerms array.
135022 **
135023 ** If the isPrefixIter parameter is zero, then the returned SegReader iterates
135024 ** through each term in the pending-terms table. Or, if isPrefixIter is
135025 ** non-zero, it iterates through each term and its prefixes. For example, if
135026 ** the pending terms hash table contains the terms "sqlite", "mysql" and
135027 ** "firebird", then the iterator visits the following 'terms' (in the order
135028 ** shown):
135029 **
135030 **   f fi fir fire fireb firebi firebir firebird
135031 **   m my mys mysq mysql
135032 **   s sq sql sqli sqlit sqlite
135033 **
135034 ** Whereas if isPrefixIter is zero, the terms visited are:
135035 **
135036 **   firebird mysql sqlite
135037 */
135038 SQLITE_PRIVATE int sqlite3Fts3SegReaderPending(
135039   Fts3Table *p,                   /* Virtual table handle */
135040   int iIndex,                     /* Index for p->aIndex */
135041   const char *zTerm,              /* Term to search for */
135042   int nTerm,                      /* Size of buffer zTerm */
135043   int bPrefix,                    /* True for a prefix iterator */
135044   Fts3SegReader **ppReader        /* OUT: SegReader for pending-terms */
135045 ){
135046   Fts3SegReader *pReader = 0;     /* Fts3SegReader object to return */
135047   Fts3HashElem *pE;               /* Iterator variable */
135048   Fts3HashElem **aElem = 0;       /* Array of term hash entries to scan */
135049   int nElem = 0;                  /* Size of array at aElem */
135050   int rc = SQLITE_OK;             /* Return Code */
135051   Fts3Hash *pHash;
135052 
135053   pHash = &p->aIndex[iIndex].hPending;
135054   if( bPrefix ){
135055     int nAlloc = 0;               /* Size of allocated array at aElem */
135056 
135057     for(pE=fts3HashFirst(pHash); pE; pE=fts3HashNext(pE)){
135058       char *zKey = (char *)fts3HashKey(pE);
135059       int nKey = fts3HashKeysize(pE);
135060       if( nTerm==0 || (nKey>=nTerm && 0==memcmp(zKey, zTerm, nTerm)) ){
135061         if( nElem==nAlloc ){
135062           Fts3HashElem **aElem2;
135063           nAlloc += 16;
135064           aElem2 = (Fts3HashElem **)sqlite3_realloc(
135065               aElem, nAlloc*sizeof(Fts3HashElem *)
135066           );
135067           if( !aElem2 ){
135068             rc = SQLITE_NOMEM;
135069             nElem = 0;
135070             break;
135071           }
135072           aElem = aElem2;
135073         }
135074 
135075         aElem[nElem++] = pE;
135076       }
135077     }
135078 
135079     /* If more than one term matches the prefix, sort the Fts3HashElem
135080     ** objects in term order using qsort(). This uses the same comparison
135081     ** callback as is used when flushing terms to disk.
135082     */
135083     if( nElem>1 ){
135084       qsort(aElem, nElem, sizeof(Fts3HashElem *), fts3CompareElemByTerm);
135085     }
135086 
135087   }else{
135088     /* The query is a simple term lookup that matches at most one term in
135089     ** the index. All that is required is a straight hash-lookup. 
135090     **
135091     ** Because the stack address of pE may be accessed via the aElem pointer
135092     ** below, the "Fts3HashElem *pE" must be declared so that it is valid
135093     ** within this entire function, not just this "else{...}" block.
135094     */
135095     pE = fts3HashFindElem(pHash, zTerm, nTerm);
135096     if( pE ){
135097       aElem = &pE;
135098       nElem = 1;
135099     }
135100   }
135101 
135102   if( nElem>0 ){
135103     int nByte = sizeof(Fts3SegReader) + (nElem+1)*sizeof(Fts3HashElem *);
135104     pReader = (Fts3SegReader *)sqlite3_malloc(nByte);
135105     if( !pReader ){
135106       rc = SQLITE_NOMEM;
135107     }else{
135108       memset(pReader, 0, nByte);
135109       pReader->iIdx = 0x7FFFFFFF;
135110       pReader->ppNextElem = (Fts3HashElem **)&pReader[1];
135111       memcpy(pReader->ppNextElem, aElem, nElem*sizeof(Fts3HashElem *));
135112     }
135113   }
135114 
135115   if( bPrefix ){
135116     sqlite3_free(aElem);
135117   }
135118   *ppReader = pReader;
135119   return rc;
135120 }
135121 
135122 /*
135123 ** Compare the entries pointed to by two Fts3SegReader structures. 
135124 ** Comparison is as follows:
135125 **
135126 **   1) EOF is greater than not EOF.
135127 **
135128 **   2) The current terms (if any) are compared using memcmp(). If one
135129 **      term is a prefix of another, the longer term is considered the
135130 **      larger.
135131 **
135132 **   3) By segment age. An older segment is considered larger.
135133 */
135134 static int fts3SegReaderCmp(Fts3SegReader *pLhs, Fts3SegReader *pRhs){
135135   int rc;
135136   if( pLhs->aNode && pRhs->aNode ){
135137     int rc2 = pLhs->nTerm - pRhs->nTerm;
135138     if( rc2<0 ){
135139       rc = memcmp(pLhs->zTerm, pRhs->zTerm, pLhs->nTerm);
135140     }else{
135141       rc = memcmp(pLhs->zTerm, pRhs->zTerm, pRhs->nTerm);
135142     }
135143     if( rc==0 ){
135144       rc = rc2;
135145     }
135146   }else{
135147     rc = (pLhs->aNode==0) - (pRhs->aNode==0);
135148   }
135149   if( rc==0 ){
135150     rc = pRhs->iIdx - pLhs->iIdx;
135151   }
135152   assert( rc!=0 );
135153   return rc;
135154 }
135155 
135156 /*
135157 ** A different comparison function for SegReader structures. In this
135158 ** version, it is assumed that each SegReader points to an entry in
135159 ** a doclist for identical terms. Comparison is made as follows:
135160 **
135161 **   1) EOF (end of doclist in this case) is greater than not EOF.
135162 **
135163 **   2) By current docid.
135164 **
135165 **   3) By segment age. An older segment is considered larger.
135166 */
135167 static int fts3SegReaderDoclistCmp(Fts3SegReader *pLhs, Fts3SegReader *pRhs){
135168   int rc = (pLhs->pOffsetList==0)-(pRhs->pOffsetList==0);
135169   if( rc==0 ){
135170     if( pLhs->iDocid==pRhs->iDocid ){
135171       rc = pRhs->iIdx - pLhs->iIdx;
135172     }else{
135173       rc = (pLhs->iDocid > pRhs->iDocid) ? 1 : -1;
135174     }
135175   }
135176   assert( pLhs->aNode && pRhs->aNode );
135177   return rc;
135178 }
135179 static int fts3SegReaderDoclistCmpRev(Fts3SegReader *pLhs, Fts3SegReader *pRhs){
135180   int rc = (pLhs->pOffsetList==0)-(pRhs->pOffsetList==0);
135181   if( rc==0 ){
135182     if( pLhs->iDocid==pRhs->iDocid ){
135183       rc = pRhs->iIdx - pLhs->iIdx;
135184     }else{
135185       rc = (pLhs->iDocid < pRhs->iDocid) ? 1 : -1;
135186     }
135187   }
135188   assert( pLhs->aNode && pRhs->aNode );
135189   return rc;
135190 }
135191 
135192 /*
135193 ** Compare the term that the Fts3SegReader object passed as the first argument
135194 ** points to with the term specified by arguments zTerm and nTerm. 
135195 **
135196 ** If the pSeg iterator is already at EOF, return 0. Otherwise, return
135197 ** -ve if the pSeg term is less than zTerm/nTerm, 0 if the two terms are
135198 ** equal, or +ve if the pSeg term is greater than zTerm/nTerm.
135199 */
135200 static int fts3SegReaderTermCmp(
135201   Fts3SegReader *pSeg,            /* Segment reader object */
135202   const char *zTerm,              /* Term to compare to */
135203   int nTerm                       /* Size of term zTerm in bytes */
135204 ){
135205   int res = 0;
135206   if( pSeg->aNode ){
135207     if( pSeg->nTerm>nTerm ){
135208       res = memcmp(pSeg->zTerm, zTerm, nTerm);
135209     }else{
135210       res = memcmp(pSeg->zTerm, zTerm, pSeg->nTerm);
135211     }
135212     if( res==0 ){
135213       res = pSeg->nTerm-nTerm;
135214     }
135215   }
135216   return res;
135217 }
135218 
135219 /*
135220 ** Argument apSegment is an array of nSegment elements. It is known that
135221 ** the final (nSegment-nSuspect) members are already in sorted order
135222 ** (according to the comparison function provided). This function shuffles
135223 ** the array around until all entries are in sorted order.
135224 */
135225 static void fts3SegReaderSort(
135226   Fts3SegReader **apSegment,                     /* Array to sort entries of */
135227   int nSegment,                                  /* Size of apSegment array */
135228   int nSuspect,                                  /* Unsorted entry count */
135229   int (*xCmp)(Fts3SegReader *, Fts3SegReader *)  /* Comparison function */
135230 ){
135231   int i;                          /* Iterator variable */
135232 
135233   assert( nSuspect<=nSegment );
135234 
135235   if( nSuspect==nSegment ) nSuspect--;
135236   for(i=nSuspect-1; i>=0; i--){
135237     int j;
135238     for(j=i; j<(nSegment-1); j++){
135239       Fts3SegReader *pTmp;
135240       if( xCmp(apSegment[j], apSegment[j+1])<0 ) break;
135241       pTmp = apSegment[j+1];
135242       apSegment[j+1] = apSegment[j];
135243       apSegment[j] = pTmp;
135244     }
135245   }
135246 
135247 #ifndef NDEBUG
135248   /* Check that the list really is sorted now. */
135249   for(i=0; i<(nSuspect-1); i++){
135250     assert( xCmp(apSegment[i], apSegment[i+1])<0 );
135251   }
135252 #endif
135253 }
135254 
135255 /* 
135256 ** Insert a record into the %_segments table.
135257 */
135258 static int fts3WriteSegment(
135259   Fts3Table *p,                   /* Virtual table handle */
135260   sqlite3_int64 iBlock,           /* Block id for new block */
135261   char *z,                        /* Pointer to buffer containing block data */
135262   int n                           /* Size of buffer z in bytes */
135263 ){
135264   sqlite3_stmt *pStmt;
135265   int rc = fts3SqlStmt(p, SQL_INSERT_SEGMENTS, &pStmt, 0);
135266   if( rc==SQLITE_OK ){
135267     sqlite3_bind_int64(pStmt, 1, iBlock);
135268     sqlite3_bind_blob(pStmt, 2, z, n, SQLITE_STATIC);
135269     sqlite3_step(pStmt);
135270     rc = sqlite3_reset(pStmt);
135271   }
135272   return rc;
135273 }
135274 
135275 /*
135276 ** Find the largest relative level number in the table. If successful, set
135277 ** *pnMax to this value and return SQLITE_OK. Otherwise, if an error occurs,
135278 ** set *pnMax to zero and return an SQLite error code.
135279 */
135280 SQLITE_PRIVATE int sqlite3Fts3MaxLevel(Fts3Table *p, int *pnMax){
135281   int rc;
135282   int mxLevel = 0;
135283   sqlite3_stmt *pStmt = 0;
135284 
135285   rc = fts3SqlStmt(p, SQL_SELECT_MXLEVEL, &pStmt, 0);
135286   if( rc==SQLITE_OK ){
135287     if( SQLITE_ROW==sqlite3_step(pStmt) ){
135288       mxLevel = sqlite3_column_int(pStmt, 0);
135289     }
135290     rc = sqlite3_reset(pStmt);
135291   }
135292   *pnMax = mxLevel;
135293   return rc;
135294 }
135295 
135296 /* 
135297 ** Insert a record into the %_segdir table.
135298 */
135299 static int fts3WriteSegdir(
135300   Fts3Table *p,                   /* Virtual table handle */
135301   sqlite3_int64 iLevel,           /* Value for "level" field (absolute level) */
135302   int iIdx,                       /* Value for "idx" field */
135303   sqlite3_int64 iStartBlock,      /* Value for "start_block" field */
135304   sqlite3_int64 iLeafEndBlock,    /* Value for "leaves_end_block" field */
135305   sqlite3_int64 iEndBlock,        /* Value for "end_block" field */
135306   char *zRoot,                    /* Blob value for "root" field */
135307   int nRoot                       /* Number of bytes in buffer zRoot */
135308 ){
135309   sqlite3_stmt *pStmt;
135310   int rc = fts3SqlStmt(p, SQL_INSERT_SEGDIR, &pStmt, 0);
135311   if( rc==SQLITE_OK ){
135312     sqlite3_bind_int64(pStmt, 1, iLevel);
135313     sqlite3_bind_int(pStmt, 2, iIdx);
135314     sqlite3_bind_int64(pStmt, 3, iStartBlock);
135315     sqlite3_bind_int64(pStmt, 4, iLeafEndBlock);
135316     sqlite3_bind_int64(pStmt, 5, iEndBlock);
135317     sqlite3_bind_blob(pStmt, 6, zRoot, nRoot, SQLITE_STATIC);
135318     sqlite3_step(pStmt);
135319     rc = sqlite3_reset(pStmt);
135320   }
135321   return rc;
135322 }
135323 
135324 /*
135325 ** Return the size of the common prefix (if any) shared by zPrev and
135326 ** zNext, in bytes. For example, 
135327 **
135328 **   fts3PrefixCompress("abc", 3, "abcdef", 6)   // returns 3
135329 **   fts3PrefixCompress("abX", 3, "abcdef", 6)   // returns 2
135330 **   fts3PrefixCompress("abX", 3, "Xbcdef", 6)   // returns 0
135331 */
135332 static int fts3PrefixCompress(
135333   const char *zPrev,              /* Buffer containing previous term */
135334   int nPrev,                      /* Size of buffer zPrev in bytes */
135335   const char *zNext,              /* Buffer containing next term */
135336   int nNext                       /* Size of buffer zNext in bytes */
135337 ){
135338   int n;
135339   UNUSED_PARAMETER(nNext);
135340   for(n=0; n<nPrev && zPrev[n]==zNext[n]; n++);
135341   return n;
135342 }
135343 
135344 /*
135345 ** Add term zTerm to the SegmentNode. It is guaranteed that zTerm is larger
135346 ** (according to memcmp) than the previous term.
135347 */
135348 static int fts3NodeAddTerm(
135349   Fts3Table *p,                   /* Virtual table handle */
135350   SegmentNode **ppTree,           /* IN/OUT: SegmentNode handle */ 
135351   int isCopyTerm,                 /* True if zTerm/nTerm is transient */
135352   const char *zTerm,              /* Pointer to buffer containing term */
135353   int nTerm                       /* Size of term in bytes */
135354 ){
135355   SegmentNode *pTree = *ppTree;
135356   int rc;
135357   SegmentNode *pNew;
135358 
135359   /* First try to append the term to the current node. Return early if 
135360   ** this is possible.
135361   */
135362   if( pTree ){
135363     int nData = pTree->nData;     /* Current size of node in bytes */
135364     int nReq = nData;             /* Required space after adding zTerm */
135365     int nPrefix;                  /* Number of bytes of prefix compression */
135366     int nSuffix;                  /* Suffix length */
135367 
135368     nPrefix = fts3PrefixCompress(pTree->zTerm, pTree->nTerm, zTerm, nTerm);
135369     nSuffix = nTerm-nPrefix;
135370 
135371     nReq += sqlite3Fts3VarintLen(nPrefix)+sqlite3Fts3VarintLen(nSuffix)+nSuffix;
135372     if( nReq<=p->nNodeSize || !pTree->zTerm ){
135373 
135374       if( nReq>p->nNodeSize ){
135375         /* An unusual case: this is the first term to be added to the node
135376         ** and the static node buffer (p->nNodeSize bytes) is not large
135377         ** enough. Use a separately malloced buffer instead This wastes
135378         ** p->nNodeSize bytes, but since this scenario only comes about when
135379         ** the database contain two terms that share a prefix of almost 2KB, 
135380         ** this is not expected to be a serious problem. 
135381         */
135382         assert( pTree->aData==(char *)&pTree[1] );
135383         pTree->aData = (char *)sqlite3_malloc(nReq);
135384         if( !pTree->aData ){
135385           return SQLITE_NOMEM;
135386         }
135387       }
135388 
135389       if( pTree->zTerm ){
135390         /* There is no prefix-length field for first term in a node */
135391         nData += sqlite3Fts3PutVarint(&pTree->aData[nData], nPrefix);
135392       }
135393 
135394       nData += sqlite3Fts3PutVarint(&pTree->aData[nData], nSuffix);
135395       memcpy(&pTree->aData[nData], &zTerm[nPrefix], nSuffix);
135396       pTree->nData = nData + nSuffix;
135397       pTree->nEntry++;
135398 
135399       if( isCopyTerm ){
135400         if( pTree->nMalloc<nTerm ){
135401           char *zNew = sqlite3_realloc(pTree->zMalloc, nTerm*2);
135402           if( !zNew ){
135403             return SQLITE_NOMEM;
135404           }
135405           pTree->nMalloc = nTerm*2;
135406           pTree->zMalloc = zNew;
135407         }
135408         pTree->zTerm = pTree->zMalloc;
135409         memcpy(pTree->zTerm, zTerm, nTerm);
135410         pTree->nTerm = nTerm;
135411       }else{
135412         pTree->zTerm = (char *)zTerm;
135413         pTree->nTerm = nTerm;
135414       }
135415       return SQLITE_OK;
135416     }
135417   }
135418 
135419   /* If control flows to here, it was not possible to append zTerm to the
135420   ** current node. Create a new node (a right-sibling of the current node).
135421   ** If this is the first node in the tree, the term is added to it.
135422   **
135423   ** Otherwise, the term is not added to the new node, it is left empty for
135424   ** now. Instead, the term is inserted into the parent of pTree. If pTree 
135425   ** has no parent, one is created here.
135426   */
135427   pNew = (SegmentNode *)sqlite3_malloc(sizeof(SegmentNode) + p->nNodeSize);
135428   if( !pNew ){
135429     return SQLITE_NOMEM;
135430   }
135431   memset(pNew, 0, sizeof(SegmentNode));
135432   pNew->nData = 1 + FTS3_VARINT_MAX;
135433   pNew->aData = (char *)&pNew[1];
135434 
135435   if( pTree ){
135436     SegmentNode *pParent = pTree->pParent;
135437     rc = fts3NodeAddTerm(p, &pParent, isCopyTerm, zTerm, nTerm);
135438     if( pTree->pParent==0 ){
135439       pTree->pParent = pParent;
135440     }
135441     pTree->pRight = pNew;
135442     pNew->pLeftmost = pTree->pLeftmost;
135443     pNew->pParent = pParent;
135444     pNew->zMalloc = pTree->zMalloc;
135445     pNew->nMalloc = pTree->nMalloc;
135446     pTree->zMalloc = 0;
135447   }else{
135448     pNew->pLeftmost = pNew;
135449     rc = fts3NodeAddTerm(p, &pNew, isCopyTerm, zTerm, nTerm); 
135450   }
135451 
135452   *ppTree = pNew;
135453   return rc;
135454 }
135455 
135456 /*
135457 ** Helper function for fts3NodeWrite().
135458 */
135459 static int fts3TreeFinishNode(
135460   SegmentNode *pTree, 
135461   int iHeight, 
135462   sqlite3_int64 iLeftChild
135463 ){
135464   int nStart;
135465   assert( iHeight>=1 && iHeight<128 );
135466   nStart = FTS3_VARINT_MAX - sqlite3Fts3VarintLen(iLeftChild);
135467   pTree->aData[nStart] = (char)iHeight;
135468   sqlite3Fts3PutVarint(&pTree->aData[nStart+1], iLeftChild);
135469   return nStart;
135470 }
135471 
135472 /*
135473 ** Write the buffer for the segment node pTree and all of its peers to the
135474 ** database. Then call this function recursively to write the parent of 
135475 ** pTree and its peers to the database. 
135476 **
135477 ** Except, if pTree is a root node, do not write it to the database. Instead,
135478 ** set output variables *paRoot and *pnRoot to contain the root node.
135479 **
135480 ** If successful, SQLITE_OK is returned and output variable *piLast is
135481 ** set to the largest blockid written to the database (or zero if no
135482 ** blocks were written to the db). Otherwise, an SQLite error code is 
135483 ** returned.
135484 */
135485 static int fts3NodeWrite(
135486   Fts3Table *p,                   /* Virtual table handle */
135487   SegmentNode *pTree,             /* SegmentNode handle */
135488   int iHeight,                    /* Height of this node in tree */
135489   sqlite3_int64 iLeaf,            /* Block id of first leaf node */
135490   sqlite3_int64 iFree,            /* Block id of next free slot in %_segments */
135491   sqlite3_int64 *piLast,          /* OUT: Block id of last entry written */
135492   char **paRoot,                  /* OUT: Data for root node */
135493   int *pnRoot                     /* OUT: Size of root node in bytes */
135494 ){
135495   int rc = SQLITE_OK;
135496 
135497   if( !pTree->pParent ){
135498     /* Root node of the tree. */
135499     int nStart = fts3TreeFinishNode(pTree, iHeight, iLeaf);
135500     *piLast = iFree-1;
135501     *pnRoot = pTree->nData - nStart;
135502     *paRoot = &pTree->aData[nStart];
135503   }else{
135504     SegmentNode *pIter;
135505     sqlite3_int64 iNextFree = iFree;
135506     sqlite3_int64 iNextLeaf = iLeaf;
135507     for(pIter=pTree->pLeftmost; pIter && rc==SQLITE_OK; pIter=pIter->pRight){
135508       int nStart = fts3TreeFinishNode(pIter, iHeight, iNextLeaf);
135509       int nWrite = pIter->nData - nStart;
135510   
135511       rc = fts3WriteSegment(p, iNextFree, &pIter->aData[nStart], nWrite);
135512       iNextFree++;
135513       iNextLeaf += (pIter->nEntry+1);
135514     }
135515     if( rc==SQLITE_OK ){
135516       assert( iNextLeaf==iFree );
135517       rc = fts3NodeWrite(
135518           p, pTree->pParent, iHeight+1, iFree, iNextFree, piLast, paRoot, pnRoot
135519       );
135520     }
135521   }
135522 
135523   return rc;
135524 }
135525 
135526 /*
135527 ** Free all memory allocations associated with the tree pTree.
135528 */
135529 static void fts3NodeFree(SegmentNode *pTree){
135530   if( pTree ){
135531     SegmentNode *p = pTree->pLeftmost;
135532     fts3NodeFree(p->pParent);
135533     while( p ){
135534       SegmentNode *pRight = p->pRight;
135535       if( p->aData!=(char *)&p[1] ){
135536         sqlite3_free(p->aData);
135537       }
135538       assert( pRight==0 || p->zMalloc==0 );
135539       sqlite3_free(p->zMalloc);
135540       sqlite3_free(p);
135541       p = pRight;
135542     }
135543   }
135544 }
135545 
135546 /*
135547 ** Add a term to the segment being constructed by the SegmentWriter object
135548 ** *ppWriter. When adding the first term to a segment, *ppWriter should
135549 ** be passed NULL. This function will allocate a new SegmentWriter object
135550 ** and return it via the input/output variable *ppWriter in this case.
135551 **
135552 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code.
135553 */
135554 static int fts3SegWriterAdd(
135555   Fts3Table *p,                   /* Virtual table handle */
135556   SegmentWriter **ppWriter,       /* IN/OUT: SegmentWriter handle */ 
135557   int isCopyTerm,                 /* True if buffer zTerm must be copied */
135558   const char *zTerm,              /* Pointer to buffer containing term */
135559   int nTerm,                      /* Size of term in bytes */
135560   const char *aDoclist,           /* Pointer to buffer containing doclist */
135561   int nDoclist                    /* Size of doclist in bytes */
135562 ){
135563   int nPrefix;                    /* Size of term prefix in bytes */
135564   int nSuffix;                    /* Size of term suffix in bytes */
135565   int nReq;                       /* Number of bytes required on leaf page */
135566   int nData;
135567   SegmentWriter *pWriter = *ppWriter;
135568 
135569   if( !pWriter ){
135570     int rc;
135571     sqlite3_stmt *pStmt;
135572 
135573     /* Allocate the SegmentWriter structure */
135574     pWriter = (SegmentWriter *)sqlite3_malloc(sizeof(SegmentWriter));
135575     if( !pWriter ) return SQLITE_NOMEM;
135576     memset(pWriter, 0, sizeof(SegmentWriter));
135577     *ppWriter = pWriter;
135578 
135579     /* Allocate a buffer in which to accumulate data */
135580     pWriter->aData = (char *)sqlite3_malloc(p->nNodeSize);
135581     if( !pWriter->aData ) return SQLITE_NOMEM;
135582     pWriter->nSize = p->nNodeSize;
135583 
135584     /* Find the next free blockid in the %_segments table */
135585     rc = fts3SqlStmt(p, SQL_NEXT_SEGMENTS_ID, &pStmt, 0);
135586     if( rc!=SQLITE_OK ) return rc;
135587     if( SQLITE_ROW==sqlite3_step(pStmt) ){
135588       pWriter->iFree = sqlite3_column_int64(pStmt, 0);
135589       pWriter->iFirst = pWriter->iFree;
135590     }
135591     rc = sqlite3_reset(pStmt);
135592     if( rc!=SQLITE_OK ) return rc;
135593   }
135594   nData = pWriter->nData;
135595 
135596   nPrefix = fts3PrefixCompress(pWriter->zTerm, pWriter->nTerm, zTerm, nTerm);
135597   nSuffix = nTerm-nPrefix;
135598 
135599   /* Figure out how many bytes are required by this new entry */
135600   nReq = sqlite3Fts3VarintLen(nPrefix) +    /* varint containing prefix size */
135601     sqlite3Fts3VarintLen(nSuffix) +         /* varint containing suffix size */
135602     nSuffix +                               /* Term suffix */
135603     sqlite3Fts3VarintLen(nDoclist) +        /* Size of doclist */
135604     nDoclist;                               /* Doclist data */
135605 
135606   if( nData>0 && nData+nReq>p->nNodeSize ){
135607     int rc;
135608 
135609     /* The current leaf node is full. Write it out to the database. */
135610     rc = fts3WriteSegment(p, pWriter->iFree++, pWriter->aData, nData);
135611     if( rc!=SQLITE_OK ) return rc;
135612     p->nLeafAdd++;
135613 
135614     /* Add the current term to the interior node tree. The term added to
135615     ** the interior tree must:
135616     **
135617     **   a) be greater than the largest term on the leaf node just written
135618     **      to the database (still available in pWriter->zTerm), and
135619     **
135620     **   b) be less than or equal to the term about to be added to the new
135621     **      leaf node (zTerm/nTerm).
135622     **
135623     ** In other words, it must be the prefix of zTerm 1 byte longer than
135624     ** the common prefix (if any) of zTerm and pWriter->zTerm.
135625     */
135626     assert( nPrefix<nTerm );
135627     rc = fts3NodeAddTerm(p, &pWriter->pTree, isCopyTerm, zTerm, nPrefix+1);
135628     if( rc!=SQLITE_OK ) return rc;
135629 
135630     nData = 0;
135631     pWriter->nTerm = 0;
135632 
135633     nPrefix = 0;
135634     nSuffix = nTerm;
135635     nReq = 1 +                              /* varint containing prefix size */
135636       sqlite3Fts3VarintLen(nTerm) +         /* varint containing suffix size */
135637       nTerm +                               /* Term suffix */
135638       sqlite3Fts3VarintLen(nDoclist) +      /* Size of doclist */
135639       nDoclist;                             /* Doclist data */
135640   }
135641 
135642   /* If the buffer currently allocated is too small for this entry, realloc
135643   ** the buffer to make it large enough.
135644   */
135645   if( nReq>pWriter->nSize ){
135646     char *aNew = sqlite3_realloc(pWriter->aData, nReq);
135647     if( !aNew ) return SQLITE_NOMEM;
135648     pWriter->aData = aNew;
135649     pWriter->nSize = nReq;
135650   }
135651   assert( nData+nReq<=pWriter->nSize );
135652 
135653   /* Append the prefix-compressed term and doclist to the buffer. */
135654   nData += sqlite3Fts3PutVarint(&pWriter->aData[nData], nPrefix);
135655   nData += sqlite3Fts3PutVarint(&pWriter->aData[nData], nSuffix);
135656   memcpy(&pWriter->aData[nData], &zTerm[nPrefix], nSuffix);
135657   nData += nSuffix;
135658   nData += sqlite3Fts3PutVarint(&pWriter->aData[nData], nDoclist);
135659   memcpy(&pWriter->aData[nData], aDoclist, nDoclist);
135660   pWriter->nData = nData + nDoclist;
135661 
135662   /* Save the current term so that it can be used to prefix-compress the next.
135663   ** If the isCopyTerm parameter is true, then the buffer pointed to by
135664   ** zTerm is transient, so take a copy of the term data. Otherwise, just
135665   ** store a copy of the pointer.
135666   */
135667   if( isCopyTerm ){
135668     if( nTerm>pWriter->nMalloc ){
135669       char *zNew = sqlite3_realloc(pWriter->zMalloc, nTerm*2);
135670       if( !zNew ){
135671         return SQLITE_NOMEM;
135672       }
135673       pWriter->nMalloc = nTerm*2;
135674       pWriter->zMalloc = zNew;
135675       pWriter->zTerm = zNew;
135676     }
135677     assert( pWriter->zTerm==pWriter->zMalloc );
135678     memcpy(pWriter->zTerm, zTerm, nTerm);
135679   }else{
135680     pWriter->zTerm = (char *)zTerm;
135681   }
135682   pWriter->nTerm = nTerm;
135683 
135684   return SQLITE_OK;
135685 }
135686 
135687 /*
135688 ** Flush all data associated with the SegmentWriter object pWriter to the
135689 ** database. This function must be called after all terms have been added
135690 ** to the segment using fts3SegWriterAdd(). If successful, SQLITE_OK is
135691 ** returned. Otherwise, an SQLite error code.
135692 */
135693 static int fts3SegWriterFlush(
135694   Fts3Table *p,                   /* Virtual table handle */
135695   SegmentWriter *pWriter,         /* SegmentWriter to flush to the db */
135696   sqlite3_int64 iLevel,           /* Value for 'level' column of %_segdir */
135697   int iIdx                        /* Value for 'idx' column of %_segdir */
135698 ){
135699   int rc;                         /* Return code */
135700   if( pWriter->pTree ){
135701     sqlite3_int64 iLast = 0;      /* Largest block id written to database */
135702     sqlite3_int64 iLastLeaf;      /* Largest leaf block id written to db */
135703     char *zRoot = NULL;           /* Pointer to buffer containing root node */
135704     int nRoot = 0;                /* Size of buffer zRoot */
135705 
135706     iLastLeaf = pWriter->iFree;
135707     rc = fts3WriteSegment(p, pWriter->iFree++, pWriter->aData, pWriter->nData);
135708     if( rc==SQLITE_OK ){
135709       rc = fts3NodeWrite(p, pWriter->pTree, 1,
135710           pWriter->iFirst, pWriter->iFree, &iLast, &zRoot, &nRoot);
135711     }
135712     if( rc==SQLITE_OK ){
135713       rc = fts3WriteSegdir(
135714           p, iLevel, iIdx, pWriter->iFirst, iLastLeaf, iLast, zRoot, nRoot);
135715     }
135716   }else{
135717     /* The entire tree fits on the root node. Write it to the segdir table. */
135718     rc = fts3WriteSegdir(
135719         p, iLevel, iIdx, 0, 0, 0, pWriter->aData, pWriter->nData);
135720   }
135721   p->nLeafAdd++;
135722   return rc;
135723 }
135724 
135725 /*
135726 ** Release all memory held by the SegmentWriter object passed as the 
135727 ** first argument.
135728 */
135729 static void fts3SegWriterFree(SegmentWriter *pWriter){
135730   if( pWriter ){
135731     sqlite3_free(pWriter->aData);
135732     sqlite3_free(pWriter->zMalloc);
135733     fts3NodeFree(pWriter->pTree);
135734     sqlite3_free(pWriter);
135735   }
135736 }
135737 
135738 /*
135739 ** The first value in the apVal[] array is assumed to contain an integer.
135740 ** This function tests if there exist any documents with docid values that
135741 ** are different from that integer. i.e. if deleting the document with docid
135742 ** pRowid would mean the FTS3 table were empty.
135743 **
135744 ** If successful, *pisEmpty is set to true if the table is empty except for
135745 ** document pRowid, or false otherwise, and SQLITE_OK is returned. If an
135746 ** error occurs, an SQLite error code is returned.
135747 */
135748 static int fts3IsEmpty(Fts3Table *p, sqlite3_value *pRowid, int *pisEmpty){
135749   sqlite3_stmt *pStmt;
135750   int rc;
135751   if( p->zContentTbl ){
135752     /* If using the content=xxx option, assume the table is never empty */
135753     *pisEmpty = 0;
135754     rc = SQLITE_OK;
135755   }else{
135756     rc = fts3SqlStmt(p, SQL_IS_EMPTY, &pStmt, &pRowid);
135757     if( rc==SQLITE_OK ){
135758       if( SQLITE_ROW==sqlite3_step(pStmt) ){
135759         *pisEmpty = sqlite3_column_int(pStmt, 0);
135760       }
135761       rc = sqlite3_reset(pStmt);
135762     }
135763   }
135764   return rc;
135765 }
135766 
135767 /*
135768 ** Set *pnMax to the largest segment level in the database for the index
135769 ** iIndex.
135770 **
135771 ** Segment levels are stored in the 'level' column of the %_segdir table.
135772 **
135773 ** Return SQLITE_OK if successful, or an SQLite error code if not.
135774 */
135775 static int fts3SegmentMaxLevel(
135776   Fts3Table *p, 
135777   int iLangid,
135778   int iIndex, 
135779   sqlite3_int64 *pnMax
135780 ){
135781   sqlite3_stmt *pStmt;
135782   int rc;
135783   assert( iIndex>=0 && iIndex<p->nIndex );
135784 
135785   /* Set pStmt to the compiled version of:
135786   **
135787   **   SELECT max(level) FROM %Q.'%q_segdir' WHERE level BETWEEN ? AND ?
135788   **
135789   ** (1024 is actually the value of macro FTS3_SEGDIR_PREFIXLEVEL_STR).
135790   */
135791   rc = fts3SqlStmt(p, SQL_SELECT_SEGDIR_MAX_LEVEL, &pStmt, 0);
135792   if( rc!=SQLITE_OK ) return rc;
135793   sqlite3_bind_int64(pStmt, 1, getAbsoluteLevel(p, iLangid, iIndex, 0));
135794   sqlite3_bind_int64(pStmt, 2, 
135795       getAbsoluteLevel(p, iLangid, iIndex, FTS3_SEGDIR_MAXLEVEL-1)
135796   );
135797   if( SQLITE_ROW==sqlite3_step(pStmt) ){
135798     *pnMax = sqlite3_column_int64(pStmt, 0);
135799   }
135800   return sqlite3_reset(pStmt);
135801 }
135802 
135803 /*
135804 ** Delete all entries in the %_segments table associated with the segment
135805 ** opened with seg-reader pSeg. This function does not affect the contents
135806 ** of the %_segdir table.
135807 */
135808 static int fts3DeleteSegment(
135809   Fts3Table *p,                   /* FTS table handle */
135810   Fts3SegReader *pSeg             /* Segment to delete */
135811 ){
135812   int rc = SQLITE_OK;             /* Return code */
135813   if( pSeg->iStartBlock ){
135814     sqlite3_stmt *pDelete;        /* SQL statement to delete rows */
135815     rc = fts3SqlStmt(p, SQL_DELETE_SEGMENTS_RANGE, &pDelete, 0);
135816     if( rc==SQLITE_OK ){
135817       sqlite3_bind_int64(pDelete, 1, pSeg->iStartBlock);
135818       sqlite3_bind_int64(pDelete, 2, pSeg->iEndBlock);
135819       sqlite3_step(pDelete);
135820       rc = sqlite3_reset(pDelete);
135821     }
135822   }
135823   return rc;
135824 }
135825 
135826 /*
135827 ** This function is used after merging multiple segments into a single large
135828 ** segment to delete the old, now redundant, segment b-trees. Specifically,
135829 ** it:
135830 ** 
135831 **   1) Deletes all %_segments entries for the segments associated with 
135832 **      each of the SegReader objects in the array passed as the third 
135833 **      argument, and
135834 **
135835 **   2) deletes all %_segdir entries with level iLevel, or all %_segdir
135836 **      entries regardless of level if (iLevel<0).
135837 **
135838 ** SQLITE_OK is returned if successful, otherwise an SQLite error code.
135839 */
135840 static int fts3DeleteSegdir(
135841   Fts3Table *p,                   /* Virtual table handle */
135842   int iLangid,                    /* Language id */
135843   int iIndex,                     /* Index for p->aIndex */
135844   int iLevel,                     /* Level of %_segdir entries to delete */
135845   Fts3SegReader **apSegment,      /* Array of SegReader objects */
135846   int nReader                     /* Size of array apSegment */
135847 ){
135848   int rc = SQLITE_OK;             /* Return Code */
135849   int i;                          /* Iterator variable */
135850   sqlite3_stmt *pDelete = 0;      /* SQL statement to delete rows */
135851 
135852   for(i=0; rc==SQLITE_OK && i<nReader; i++){
135853     rc = fts3DeleteSegment(p, apSegment[i]);
135854   }
135855   if( rc!=SQLITE_OK ){
135856     return rc;
135857   }
135858 
135859   assert( iLevel>=0 || iLevel==FTS3_SEGCURSOR_ALL );
135860   if( iLevel==FTS3_SEGCURSOR_ALL ){
135861     rc = fts3SqlStmt(p, SQL_DELETE_SEGDIR_RANGE, &pDelete, 0);
135862     if( rc==SQLITE_OK ){
135863       sqlite3_bind_int64(pDelete, 1, getAbsoluteLevel(p, iLangid, iIndex, 0));
135864       sqlite3_bind_int64(pDelete, 2, 
135865           getAbsoluteLevel(p, iLangid, iIndex, FTS3_SEGDIR_MAXLEVEL-1)
135866       );
135867     }
135868   }else{
135869     rc = fts3SqlStmt(p, SQL_DELETE_SEGDIR_LEVEL, &pDelete, 0);
135870     if( rc==SQLITE_OK ){
135871       sqlite3_bind_int64(
135872           pDelete, 1, getAbsoluteLevel(p, iLangid, iIndex, iLevel)
135873       );
135874     }
135875   }
135876 
135877   if( rc==SQLITE_OK ){
135878     sqlite3_step(pDelete);
135879     rc = sqlite3_reset(pDelete);
135880   }
135881 
135882   return rc;
135883 }
135884 
135885 /*
135886 ** When this function is called, buffer *ppList (size *pnList bytes) contains 
135887 ** a position list that may (or may not) feature multiple columns. This
135888 ** function adjusts the pointer *ppList and the length *pnList so that they
135889 ** identify the subset of the position list that corresponds to column iCol.
135890 **
135891 ** If there are no entries in the input position list for column iCol, then
135892 ** *pnList is set to zero before returning.
135893 **
135894 ** If parameter bZero is non-zero, then any part of the input list following
135895 ** the end of the output list is zeroed before returning.
135896 */
135897 static void fts3ColumnFilter(
135898   int iCol,                       /* Column to filter on */
135899   int bZero,                      /* Zero out anything following *ppList */
135900   char **ppList,                  /* IN/OUT: Pointer to position list */
135901   int *pnList                     /* IN/OUT: Size of buffer *ppList in bytes */
135902 ){
135903   char *pList = *ppList;
135904   int nList = *pnList;
135905   char *pEnd = &pList[nList];
135906   int iCurrent = 0;
135907   char *p = pList;
135908 
135909   assert( iCol>=0 );
135910   while( 1 ){
135911     char c = 0;
135912     while( p<pEnd && (c | *p)&0xFE ) c = *p++ & 0x80;
135913   
135914     if( iCol==iCurrent ){
135915       nList = (int)(p - pList);
135916       break;
135917     }
135918 
135919     nList -= (int)(p - pList);
135920     pList = p;
135921     if( nList==0 ){
135922       break;
135923     }
135924     p = &pList[1];
135925     p += fts3GetVarint32(p, &iCurrent);
135926   }
135927 
135928   if( bZero && &pList[nList]!=pEnd ){
135929     memset(&pList[nList], 0, pEnd - &pList[nList]);
135930   }
135931   *ppList = pList;
135932   *pnList = nList;
135933 }
135934 
135935 /*
135936 ** Cache data in the Fts3MultiSegReader.aBuffer[] buffer (overwriting any
135937 ** existing data). Grow the buffer if required.
135938 **
135939 ** If successful, return SQLITE_OK. Otherwise, if an OOM error is encountered
135940 ** trying to resize the buffer, return SQLITE_NOMEM.
135941 */
135942 static int fts3MsrBufferData(
135943   Fts3MultiSegReader *pMsr,       /* Multi-segment-reader handle */
135944   char *pList,
135945   int nList
135946 ){
135947   if( nList>pMsr->nBuffer ){
135948     char *pNew;
135949     pMsr->nBuffer = nList*2;
135950     pNew = (char *)sqlite3_realloc(pMsr->aBuffer, pMsr->nBuffer);
135951     if( !pNew ) return SQLITE_NOMEM;
135952     pMsr->aBuffer = pNew;
135953   }
135954 
135955   memcpy(pMsr->aBuffer, pList, nList);
135956   return SQLITE_OK;
135957 }
135958 
135959 SQLITE_PRIVATE int sqlite3Fts3MsrIncrNext(
135960   Fts3Table *p,                   /* Virtual table handle */
135961   Fts3MultiSegReader *pMsr,       /* Multi-segment-reader handle */
135962   sqlite3_int64 *piDocid,         /* OUT: Docid value */
135963   char **paPoslist,               /* OUT: Pointer to position list */
135964   int *pnPoslist                  /* OUT: Size of position list in bytes */
135965 ){
135966   int nMerge = pMsr->nAdvance;
135967   Fts3SegReader **apSegment = pMsr->apSegment;
135968   int (*xCmp)(Fts3SegReader *, Fts3SegReader *) = (
135969     p->bDescIdx ? fts3SegReaderDoclistCmpRev : fts3SegReaderDoclistCmp
135970   );
135971 
135972   if( nMerge==0 ){
135973     *paPoslist = 0;
135974     return SQLITE_OK;
135975   }
135976 
135977   while( 1 ){
135978     Fts3SegReader *pSeg;
135979     pSeg = pMsr->apSegment[0];
135980 
135981     if( pSeg->pOffsetList==0 ){
135982       *paPoslist = 0;
135983       break;
135984     }else{
135985       int rc;
135986       char *pList;
135987       int nList;
135988       int j;
135989       sqlite3_int64 iDocid = apSegment[0]->iDocid;
135990 
135991       rc = fts3SegReaderNextDocid(p, apSegment[0], &pList, &nList);
135992       j = 1;
135993       while( rc==SQLITE_OK 
135994         && j<nMerge
135995         && apSegment[j]->pOffsetList
135996         && apSegment[j]->iDocid==iDocid
135997       ){
135998         rc = fts3SegReaderNextDocid(p, apSegment[j], 0, 0);
135999         j++;
136000       }
136001       if( rc!=SQLITE_OK ) return rc;
136002       fts3SegReaderSort(pMsr->apSegment, nMerge, j, xCmp);
136003 
136004       if( nList>0 && fts3SegReaderIsPending(apSegment[0]) ){
136005         rc = fts3MsrBufferData(pMsr, pList, nList+1);
136006         if( rc!=SQLITE_OK ) return rc;
136007         assert( (pMsr->aBuffer[nList] & 0xFE)==0x00 );
136008         pList = pMsr->aBuffer;
136009       }
136010 
136011       if( pMsr->iColFilter>=0 ){
136012         fts3ColumnFilter(pMsr->iColFilter, 1, &pList, &nList);
136013       }
136014 
136015       if( nList>0 ){
136016         *paPoslist = pList;
136017         *piDocid = iDocid;
136018         *pnPoslist = nList;
136019         break;
136020       }
136021     }
136022   }
136023 
136024   return SQLITE_OK;
136025 }
136026 
136027 static int fts3SegReaderStart(
136028   Fts3Table *p,                   /* Virtual table handle */
136029   Fts3MultiSegReader *pCsr,       /* Cursor object */
136030   const char *zTerm,              /* Term searched for (or NULL) */
136031   int nTerm                       /* Length of zTerm in bytes */
136032 ){
136033   int i;
136034   int nSeg = pCsr->nSegment;
136035 
136036   /* If the Fts3SegFilter defines a specific term (or term prefix) to search 
136037   ** for, then advance each segment iterator until it points to a term of
136038   ** equal or greater value than the specified term. This prevents many
136039   ** unnecessary merge/sort operations for the case where single segment
136040   ** b-tree leaf nodes contain more than one term.
136041   */
136042   for(i=0; pCsr->bRestart==0 && i<pCsr->nSegment; i++){
136043     int res = 0;
136044     Fts3SegReader *pSeg = pCsr->apSegment[i];
136045     do {
136046       int rc = fts3SegReaderNext(p, pSeg, 0);
136047       if( rc!=SQLITE_OK ) return rc;
136048     }while( zTerm && (res = fts3SegReaderTermCmp(pSeg, zTerm, nTerm))<0 );
136049 
136050     if( pSeg->bLookup && res!=0 ){
136051       fts3SegReaderSetEof(pSeg);
136052     }
136053   }
136054   fts3SegReaderSort(pCsr->apSegment, nSeg, nSeg, fts3SegReaderCmp);
136055 
136056   return SQLITE_OK;
136057 }
136058 
136059 SQLITE_PRIVATE int sqlite3Fts3SegReaderStart(
136060   Fts3Table *p,                   /* Virtual table handle */
136061   Fts3MultiSegReader *pCsr,       /* Cursor object */
136062   Fts3SegFilter *pFilter          /* Restrictions on range of iteration */
136063 ){
136064   pCsr->pFilter = pFilter;
136065   return fts3SegReaderStart(p, pCsr, pFilter->zTerm, pFilter->nTerm);
136066 }
136067 
136068 SQLITE_PRIVATE int sqlite3Fts3MsrIncrStart(
136069   Fts3Table *p,                   /* Virtual table handle */
136070   Fts3MultiSegReader *pCsr,       /* Cursor object */
136071   int iCol,                       /* Column to match on. */
136072   const char *zTerm,              /* Term to iterate through a doclist for */
136073   int nTerm                       /* Number of bytes in zTerm */
136074 ){
136075   int i;
136076   int rc;
136077   int nSegment = pCsr->nSegment;
136078   int (*xCmp)(Fts3SegReader *, Fts3SegReader *) = (
136079     p->bDescIdx ? fts3SegReaderDoclistCmpRev : fts3SegReaderDoclistCmp
136080   );
136081 
136082   assert( pCsr->pFilter==0 );
136083   assert( zTerm && nTerm>0 );
136084 
136085   /* Advance each segment iterator until it points to the term zTerm/nTerm. */
136086   rc = fts3SegReaderStart(p, pCsr, zTerm, nTerm);
136087   if( rc!=SQLITE_OK ) return rc;
136088 
136089   /* Determine how many of the segments actually point to zTerm/nTerm. */
136090   for(i=0; i<nSegment; i++){
136091     Fts3SegReader *pSeg = pCsr->apSegment[i];
136092     if( !pSeg->aNode || fts3SegReaderTermCmp(pSeg, zTerm, nTerm) ){
136093       break;
136094     }
136095   }
136096   pCsr->nAdvance = i;
136097 
136098   /* Advance each of the segments to point to the first docid. */
136099   for(i=0; i<pCsr->nAdvance; i++){
136100     rc = fts3SegReaderFirstDocid(p, pCsr->apSegment[i]);
136101     if( rc!=SQLITE_OK ) return rc;
136102   }
136103   fts3SegReaderSort(pCsr->apSegment, i, i, xCmp);
136104 
136105   assert( iCol<0 || iCol<p->nColumn );
136106   pCsr->iColFilter = iCol;
136107 
136108   return SQLITE_OK;
136109 }
136110 
136111 /*
136112 ** This function is called on a MultiSegReader that has been started using
136113 ** sqlite3Fts3MsrIncrStart(). One or more calls to MsrIncrNext() may also
136114 ** have been made. Calling this function puts the MultiSegReader in such
136115 ** a state that if the next two calls are:
136116 **
136117 **   sqlite3Fts3SegReaderStart()
136118 **   sqlite3Fts3SegReaderStep()
136119 **
136120 ** then the entire doclist for the term is available in 
136121 ** MultiSegReader.aDoclist/nDoclist.
136122 */
136123 SQLITE_PRIVATE int sqlite3Fts3MsrIncrRestart(Fts3MultiSegReader *pCsr){
136124   int i;                          /* Used to iterate through segment-readers */
136125 
136126   assert( pCsr->zTerm==0 );
136127   assert( pCsr->nTerm==0 );
136128   assert( pCsr->aDoclist==0 );
136129   assert( pCsr->nDoclist==0 );
136130 
136131   pCsr->nAdvance = 0;
136132   pCsr->bRestart = 1;
136133   for(i=0; i<pCsr->nSegment; i++){
136134     pCsr->apSegment[i]->pOffsetList = 0;
136135     pCsr->apSegment[i]->nOffsetList = 0;
136136     pCsr->apSegment[i]->iDocid = 0;
136137   }
136138 
136139   return SQLITE_OK;
136140 }
136141 
136142 
136143 SQLITE_PRIVATE int sqlite3Fts3SegReaderStep(
136144   Fts3Table *p,                   /* Virtual table handle */
136145   Fts3MultiSegReader *pCsr        /* Cursor object */
136146 ){
136147   int rc = SQLITE_OK;
136148 
136149   int isIgnoreEmpty =  (pCsr->pFilter->flags & FTS3_SEGMENT_IGNORE_EMPTY);
136150   int isRequirePos =   (pCsr->pFilter->flags & FTS3_SEGMENT_REQUIRE_POS);
136151   int isColFilter =    (pCsr->pFilter->flags & FTS3_SEGMENT_COLUMN_FILTER);
136152   int isPrefix =       (pCsr->pFilter->flags & FTS3_SEGMENT_PREFIX);
136153   int isScan =         (pCsr->pFilter->flags & FTS3_SEGMENT_SCAN);
136154   int isFirst =        (pCsr->pFilter->flags & FTS3_SEGMENT_FIRST);
136155 
136156   Fts3SegReader **apSegment = pCsr->apSegment;
136157   int nSegment = pCsr->nSegment;
136158   Fts3SegFilter *pFilter = pCsr->pFilter;
136159   int (*xCmp)(Fts3SegReader *, Fts3SegReader *) = (
136160     p->bDescIdx ? fts3SegReaderDoclistCmpRev : fts3SegReaderDoclistCmp
136161   );
136162 
136163   if( pCsr->nSegment==0 ) return SQLITE_OK;
136164 
136165   do {
136166     int nMerge;
136167     int i;
136168   
136169     /* Advance the first pCsr->nAdvance entries in the apSegment[] array
136170     ** forward. Then sort the list in order of current term again.  
136171     */
136172     for(i=0; i<pCsr->nAdvance; i++){
136173       Fts3SegReader *pSeg = apSegment[i];
136174       if( pSeg->bLookup ){
136175         fts3SegReaderSetEof(pSeg);
136176       }else{
136177         rc = fts3SegReaderNext(p, pSeg, 0);
136178       }
136179       if( rc!=SQLITE_OK ) return rc;
136180     }
136181     fts3SegReaderSort(apSegment, nSegment, pCsr->nAdvance, fts3SegReaderCmp);
136182     pCsr->nAdvance = 0;
136183 
136184     /* If all the seg-readers are at EOF, we're finished. return SQLITE_OK. */
136185     assert( rc==SQLITE_OK );
136186     if( apSegment[0]->aNode==0 ) break;
136187 
136188     pCsr->nTerm = apSegment[0]->nTerm;
136189     pCsr->zTerm = apSegment[0]->zTerm;
136190 
136191     /* If this is a prefix-search, and if the term that apSegment[0] points
136192     ** to does not share a suffix with pFilter->zTerm/nTerm, then all 
136193     ** required callbacks have been made. In this case exit early.
136194     **
136195     ** Similarly, if this is a search for an exact match, and the first term
136196     ** of segment apSegment[0] is not a match, exit early.
136197     */
136198     if( pFilter->zTerm && !isScan ){
136199       if( pCsr->nTerm<pFilter->nTerm 
136200        || (!isPrefix && pCsr->nTerm>pFilter->nTerm)
136201        || memcmp(pCsr->zTerm, pFilter->zTerm, pFilter->nTerm) 
136202       ){
136203         break;
136204       }
136205     }
136206 
136207     nMerge = 1;
136208     while( nMerge<nSegment 
136209         && apSegment[nMerge]->aNode
136210         && apSegment[nMerge]->nTerm==pCsr->nTerm 
136211         && 0==memcmp(pCsr->zTerm, apSegment[nMerge]->zTerm, pCsr->nTerm)
136212     ){
136213       nMerge++;
136214     }
136215 
136216     assert( isIgnoreEmpty || (isRequirePos && !isColFilter) );
136217     if( nMerge==1 
136218      && !isIgnoreEmpty 
136219      && !isFirst 
136220      && (p->bDescIdx==0 || fts3SegReaderIsPending(apSegment[0])==0)
136221     ){
136222       pCsr->nDoclist = apSegment[0]->nDoclist;
136223       if( fts3SegReaderIsPending(apSegment[0]) ){
136224         rc = fts3MsrBufferData(pCsr, apSegment[0]->aDoclist, pCsr->nDoclist);
136225         pCsr->aDoclist = pCsr->aBuffer;
136226       }else{
136227         pCsr->aDoclist = apSegment[0]->aDoclist;
136228       }
136229       if( rc==SQLITE_OK ) rc = SQLITE_ROW;
136230     }else{
136231       int nDoclist = 0;           /* Size of doclist */
136232       sqlite3_int64 iPrev = 0;    /* Previous docid stored in doclist */
136233 
136234       /* The current term of the first nMerge entries in the array
136235       ** of Fts3SegReader objects is the same. The doclists must be merged
136236       ** and a single term returned with the merged doclist.
136237       */
136238       for(i=0; i<nMerge; i++){
136239         fts3SegReaderFirstDocid(p, apSegment[i]);
136240       }
136241       fts3SegReaderSort(apSegment, nMerge, nMerge, xCmp);
136242       while( apSegment[0]->pOffsetList ){
136243         int j;                    /* Number of segments that share a docid */
136244         char *pList = 0;
136245         int nList = 0;
136246         int nByte;
136247         sqlite3_int64 iDocid = apSegment[0]->iDocid;
136248         fts3SegReaderNextDocid(p, apSegment[0], &pList, &nList);
136249         j = 1;
136250         while( j<nMerge
136251             && apSegment[j]->pOffsetList
136252             && apSegment[j]->iDocid==iDocid
136253         ){
136254           fts3SegReaderNextDocid(p, apSegment[j], 0, 0);
136255           j++;
136256         }
136257 
136258         if( isColFilter ){
136259           fts3ColumnFilter(pFilter->iCol, 0, &pList, &nList);
136260         }
136261 
136262         if( !isIgnoreEmpty || nList>0 ){
136263 
136264           /* Calculate the 'docid' delta value to write into the merged 
136265           ** doclist. */
136266           sqlite3_int64 iDelta;
136267           if( p->bDescIdx && nDoclist>0 ){
136268             iDelta = iPrev - iDocid;
136269           }else{
136270             iDelta = iDocid - iPrev;
136271           }
136272           assert( iDelta>0 || (nDoclist==0 && iDelta==iDocid) );
136273           assert( nDoclist>0 || iDelta==iDocid );
136274 
136275           nByte = sqlite3Fts3VarintLen(iDelta) + (isRequirePos?nList+1:0);
136276           if( nDoclist+nByte>pCsr->nBuffer ){
136277             char *aNew;
136278             pCsr->nBuffer = (nDoclist+nByte)*2;
136279             aNew = sqlite3_realloc(pCsr->aBuffer, pCsr->nBuffer);
136280             if( !aNew ){
136281               return SQLITE_NOMEM;
136282             }
136283             pCsr->aBuffer = aNew;
136284           }
136285 
136286           if( isFirst ){
136287             char *a = &pCsr->aBuffer[nDoclist];
136288             int nWrite;
136289            
136290             nWrite = sqlite3Fts3FirstFilter(iDelta, pList, nList, a);
136291             if( nWrite ){
136292               iPrev = iDocid;
136293               nDoclist += nWrite;
136294             }
136295           }else{
136296             nDoclist += sqlite3Fts3PutVarint(&pCsr->aBuffer[nDoclist], iDelta);
136297             iPrev = iDocid;
136298             if( isRequirePos ){
136299               memcpy(&pCsr->aBuffer[nDoclist], pList, nList);
136300               nDoclist += nList;
136301               pCsr->aBuffer[nDoclist++] = '\0';
136302             }
136303           }
136304         }
136305 
136306         fts3SegReaderSort(apSegment, nMerge, j, xCmp);
136307       }
136308       if( nDoclist>0 ){
136309         pCsr->aDoclist = pCsr->aBuffer;
136310         pCsr->nDoclist = nDoclist;
136311         rc = SQLITE_ROW;
136312       }
136313     }
136314     pCsr->nAdvance = nMerge;
136315   }while( rc==SQLITE_OK );
136316 
136317   return rc;
136318 }
136319 
136320 
136321 SQLITE_PRIVATE void sqlite3Fts3SegReaderFinish(
136322   Fts3MultiSegReader *pCsr       /* Cursor object */
136323 ){
136324   if( pCsr ){
136325     int i;
136326     for(i=0; i<pCsr->nSegment; i++){
136327       sqlite3Fts3SegReaderFree(pCsr->apSegment[i]);
136328     }
136329     sqlite3_free(pCsr->apSegment);
136330     sqlite3_free(pCsr->aBuffer);
136331 
136332     pCsr->nSegment = 0;
136333     pCsr->apSegment = 0;
136334     pCsr->aBuffer = 0;
136335   }
136336 }
136337 
136338 /*
136339 ** Merge all level iLevel segments in the database into a single 
136340 ** iLevel+1 segment. Or, if iLevel<0, merge all segments into a
136341 ** single segment with a level equal to the numerically largest level 
136342 ** currently present in the database.
136343 **
136344 ** If this function is called with iLevel<0, but there is only one
136345 ** segment in the database, SQLITE_DONE is returned immediately. 
136346 ** Otherwise, if successful, SQLITE_OK is returned. If an error occurs, 
136347 ** an SQLite error code is returned.
136348 */
136349 static int fts3SegmentMerge(
136350   Fts3Table *p, 
136351   int iLangid,                    /* Language id to merge */
136352   int iIndex,                     /* Index in p->aIndex[] to merge */
136353   int iLevel                      /* Level to merge */
136354 ){
136355   int rc;                         /* Return code */
136356   int iIdx = 0;                   /* Index of new segment */
136357   sqlite3_int64 iNewLevel = 0;    /* Level/index to create new segment at */
136358   SegmentWriter *pWriter = 0;     /* Used to write the new, merged, segment */
136359   Fts3SegFilter filter;           /* Segment term filter condition */
136360   Fts3MultiSegReader csr;         /* Cursor to iterate through level(s) */
136361   int bIgnoreEmpty = 0;           /* True to ignore empty segments */
136362 
136363   assert( iLevel==FTS3_SEGCURSOR_ALL
136364        || iLevel==FTS3_SEGCURSOR_PENDING
136365        || iLevel>=0
136366   );
136367   assert( iLevel<FTS3_SEGDIR_MAXLEVEL );
136368   assert( iIndex>=0 && iIndex<p->nIndex );
136369 
136370   rc = sqlite3Fts3SegReaderCursor(p, iLangid, iIndex, iLevel, 0, 0, 1, 0, &csr);
136371   if( rc!=SQLITE_OK || csr.nSegment==0 ) goto finished;
136372 
136373   if( iLevel==FTS3_SEGCURSOR_ALL ){
136374     /* This call is to merge all segments in the database to a single
136375     ** segment. The level of the new segment is equal to the numerically
136376     ** greatest segment level currently present in the database for this
136377     ** index. The idx of the new segment is always 0.  */
136378     if( csr.nSegment==1 ){
136379       rc = SQLITE_DONE;
136380       goto finished;
136381     }
136382     rc = fts3SegmentMaxLevel(p, iLangid, iIndex, &iNewLevel);
136383     bIgnoreEmpty = 1;
136384 
136385   }else if( iLevel==FTS3_SEGCURSOR_PENDING ){
136386     iNewLevel = getAbsoluteLevel(p, iLangid, iIndex, 0);
136387     rc = fts3AllocateSegdirIdx(p, iLangid, iIndex, 0, &iIdx);
136388   }else{
136389     /* This call is to merge all segments at level iLevel. find the next
136390     ** available segment index at level iLevel+1. The call to
136391     ** fts3AllocateSegdirIdx() will merge the segments at level iLevel+1 to 
136392     ** a single iLevel+2 segment if necessary.  */
136393     rc = fts3AllocateSegdirIdx(p, iLangid, iIndex, iLevel+1, &iIdx);
136394     iNewLevel = getAbsoluteLevel(p, iLangid, iIndex, iLevel+1);
136395   }
136396   if( rc!=SQLITE_OK ) goto finished;
136397   assert( csr.nSegment>0 );
136398   assert( iNewLevel>=getAbsoluteLevel(p, iLangid, iIndex, 0) );
136399   assert( iNewLevel<getAbsoluteLevel(p, iLangid, iIndex,FTS3_SEGDIR_MAXLEVEL) );
136400 
136401   memset(&filter, 0, sizeof(Fts3SegFilter));
136402   filter.flags = FTS3_SEGMENT_REQUIRE_POS;
136403   filter.flags |= (bIgnoreEmpty ? FTS3_SEGMENT_IGNORE_EMPTY : 0);
136404 
136405   rc = sqlite3Fts3SegReaderStart(p, &csr, &filter);
136406   while( SQLITE_OK==rc ){
136407     rc = sqlite3Fts3SegReaderStep(p, &csr);
136408     if( rc!=SQLITE_ROW ) break;
136409     rc = fts3SegWriterAdd(p, &pWriter, 1, 
136410         csr.zTerm, csr.nTerm, csr.aDoclist, csr.nDoclist);
136411   }
136412   if( rc!=SQLITE_OK ) goto finished;
136413   assert( pWriter );
136414 
136415   if( iLevel!=FTS3_SEGCURSOR_PENDING ){
136416     rc = fts3DeleteSegdir(
136417         p, iLangid, iIndex, iLevel, csr.apSegment, csr.nSegment
136418     );
136419     if( rc!=SQLITE_OK ) goto finished;
136420   }
136421   rc = fts3SegWriterFlush(p, pWriter, iNewLevel, iIdx);
136422 
136423  finished:
136424   fts3SegWriterFree(pWriter);
136425   sqlite3Fts3SegReaderFinish(&csr);
136426   return rc;
136427 }
136428 
136429 
136430 /* 
136431 ** Flush the contents of pendingTerms to level 0 segments.
136432 */
136433 SQLITE_PRIVATE int sqlite3Fts3PendingTermsFlush(Fts3Table *p){
136434   int rc = SQLITE_OK;
136435   int i;
136436         
136437   for(i=0; rc==SQLITE_OK && i<p->nIndex; i++){
136438     rc = fts3SegmentMerge(p, p->iPrevLangid, i, FTS3_SEGCURSOR_PENDING);
136439     if( rc==SQLITE_DONE ) rc = SQLITE_OK;
136440   }
136441   sqlite3Fts3PendingTermsClear(p);
136442 
136443   /* Determine the auto-incr-merge setting if unknown.  If enabled,
136444   ** estimate the number of leaf blocks of content to be written
136445   */
136446   if( rc==SQLITE_OK && p->bHasStat
136447    && p->bAutoincrmerge==0xff && p->nLeafAdd>0
136448   ){
136449     sqlite3_stmt *pStmt = 0;
136450     rc = fts3SqlStmt(p, SQL_SELECT_STAT, &pStmt, 0);
136451     if( rc==SQLITE_OK ){
136452       sqlite3_bind_int(pStmt, 1, FTS_STAT_AUTOINCRMERGE);
136453       rc = sqlite3_step(pStmt);
136454       p->bAutoincrmerge = (rc==SQLITE_ROW && sqlite3_column_int(pStmt, 0));
136455       rc = sqlite3_reset(pStmt);
136456     }
136457   }
136458   return rc;
136459 }
136460 
136461 /*
136462 ** Encode N integers as varints into a blob.
136463 */
136464 static void fts3EncodeIntArray(
136465   int N,             /* The number of integers to encode */
136466   u32 *a,            /* The integer values */
136467   char *zBuf,        /* Write the BLOB here */
136468   int *pNBuf         /* Write number of bytes if zBuf[] used here */
136469 ){
136470   int i, j;
136471   for(i=j=0; i<N; i++){
136472     j += sqlite3Fts3PutVarint(&zBuf[j], (sqlite3_int64)a[i]);
136473   }
136474   *pNBuf = j;
136475 }
136476 
136477 /*
136478 ** Decode a blob of varints into N integers
136479 */
136480 static void fts3DecodeIntArray(
136481   int N,             /* The number of integers to decode */
136482   u32 *a,            /* Write the integer values */
136483   const char *zBuf,  /* The BLOB containing the varints */
136484   int nBuf           /* size of the BLOB */
136485 ){
136486   int i, j;
136487   UNUSED_PARAMETER(nBuf);
136488   for(i=j=0; i<N; i++){
136489     sqlite3_int64 x;
136490     j += sqlite3Fts3GetVarint(&zBuf[j], &x);
136491     assert(j<=nBuf);
136492     a[i] = (u32)(x & 0xffffffff);
136493   }
136494 }
136495 
136496 /*
136497 ** Insert the sizes (in tokens) for each column of the document
136498 ** with docid equal to p->iPrevDocid.  The sizes are encoded as
136499 ** a blob of varints.
136500 */
136501 static void fts3InsertDocsize(
136502   int *pRC,                       /* Result code */
136503   Fts3Table *p,                   /* Table into which to insert */
136504   u32 *aSz                        /* Sizes of each column, in tokens */
136505 ){
136506   char *pBlob;             /* The BLOB encoding of the document size */
136507   int nBlob;               /* Number of bytes in the BLOB */
136508   sqlite3_stmt *pStmt;     /* Statement used to insert the encoding */
136509   int rc;                  /* Result code from subfunctions */
136510 
136511   if( *pRC ) return;
136512   pBlob = sqlite3_malloc( 10*p->nColumn );
136513   if( pBlob==0 ){
136514     *pRC = SQLITE_NOMEM;
136515     return;
136516   }
136517   fts3EncodeIntArray(p->nColumn, aSz, pBlob, &nBlob);
136518   rc = fts3SqlStmt(p, SQL_REPLACE_DOCSIZE, &pStmt, 0);
136519   if( rc ){
136520     sqlite3_free(pBlob);
136521     *pRC = rc;
136522     return;
136523   }
136524   sqlite3_bind_int64(pStmt, 1, p->iPrevDocid);
136525   sqlite3_bind_blob(pStmt, 2, pBlob, nBlob, sqlite3_free);
136526   sqlite3_step(pStmt);
136527   *pRC = sqlite3_reset(pStmt);
136528 }
136529 
136530 /*
136531 ** Record 0 of the %_stat table contains a blob consisting of N varints,
136532 ** where N is the number of user defined columns in the fts3 table plus
136533 ** two. If nCol is the number of user defined columns, then values of the 
136534 ** varints are set as follows:
136535 **
136536 **   Varint 0:       Total number of rows in the table.
136537 **
136538 **   Varint 1..nCol: For each column, the total number of tokens stored in
136539 **                   the column for all rows of the table.
136540 **
136541 **   Varint 1+nCol:  The total size, in bytes, of all text values in all
136542 **                   columns of all rows of the table.
136543 **
136544 */
136545 static void fts3UpdateDocTotals(
136546   int *pRC,                       /* The result code */
136547   Fts3Table *p,                   /* Table being updated */
136548   u32 *aSzIns,                    /* Size increases */
136549   u32 *aSzDel,                    /* Size decreases */
136550   int nChng                       /* Change in the number of documents */
136551 ){
136552   char *pBlob;             /* Storage for BLOB written into %_stat */
136553   int nBlob;               /* Size of BLOB written into %_stat */
136554   u32 *a;                  /* Array of integers that becomes the BLOB */
136555   sqlite3_stmt *pStmt;     /* Statement for reading and writing */
136556   int i;                   /* Loop counter */
136557   int rc;                  /* Result code from subfunctions */
136558 
136559   const int nStat = p->nColumn+2;
136560 
136561   if( *pRC ) return;
136562   a = sqlite3_malloc( (sizeof(u32)+10)*nStat );
136563   if( a==0 ){
136564     *pRC = SQLITE_NOMEM;
136565     return;
136566   }
136567   pBlob = (char*)&a[nStat];
136568   rc = fts3SqlStmt(p, SQL_SELECT_STAT, &pStmt, 0);
136569   if( rc ){
136570     sqlite3_free(a);
136571     *pRC = rc;
136572     return;
136573   }
136574   sqlite3_bind_int(pStmt, 1, FTS_STAT_DOCTOTAL);
136575   if( sqlite3_step(pStmt)==SQLITE_ROW ){
136576     fts3DecodeIntArray(nStat, a,
136577          sqlite3_column_blob(pStmt, 0),
136578          sqlite3_column_bytes(pStmt, 0));
136579   }else{
136580     memset(a, 0, sizeof(u32)*(nStat) );
136581   }
136582   rc = sqlite3_reset(pStmt);
136583   if( rc!=SQLITE_OK ){
136584     sqlite3_free(a);
136585     *pRC = rc;
136586     return;
136587   }
136588   if( nChng<0 && a[0]<(u32)(-nChng) ){
136589     a[0] = 0;
136590   }else{
136591     a[0] += nChng;
136592   }
136593   for(i=0; i<p->nColumn+1; i++){
136594     u32 x = a[i+1];
136595     if( x+aSzIns[i] < aSzDel[i] ){
136596       x = 0;
136597     }else{
136598       x = x + aSzIns[i] - aSzDel[i];
136599     }
136600     a[i+1] = x;
136601   }
136602   fts3EncodeIntArray(nStat, a, pBlob, &nBlob);
136603   rc = fts3SqlStmt(p, SQL_REPLACE_STAT, &pStmt, 0);
136604   if( rc ){
136605     sqlite3_free(a);
136606     *pRC = rc;
136607     return;
136608   }
136609   sqlite3_bind_int(pStmt, 1, FTS_STAT_DOCTOTAL);
136610   sqlite3_bind_blob(pStmt, 2, pBlob, nBlob, SQLITE_STATIC);
136611   sqlite3_step(pStmt);
136612   *pRC = sqlite3_reset(pStmt);
136613   sqlite3_free(a);
136614 }
136615 
136616 /*
136617 ** Merge the entire database so that there is one segment for each 
136618 ** iIndex/iLangid combination.
136619 */
136620 static int fts3DoOptimize(Fts3Table *p, int bReturnDone){
136621   int bSeenDone = 0;
136622   int rc;
136623   sqlite3_stmt *pAllLangid = 0;
136624 
136625   rc = fts3SqlStmt(p, SQL_SELECT_ALL_LANGID, &pAllLangid, 0);
136626   if( rc==SQLITE_OK ){
136627     int rc2;
136628     sqlite3_bind_int(pAllLangid, 1, p->nIndex);
136629     while( sqlite3_step(pAllLangid)==SQLITE_ROW ){
136630       int i;
136631       int iLangid = sqlite3_column_int(pAllLangid, 0);
136632       for(i=0; rc==SQLITE_OK && i<p->nIndex; i++){
136633         rc = fts3SegmentMerge(p, iLangid, i, FTS3_SEGCURSOR_ALL);
136634         if( rc==SQLITE_DONE ){
136635           bSeenDone = 1;
136636           rc = SQLITE_OK;
136637         }
136638       }
136639     }
136640     rc2 = sqlite3_reset(pAllLangid);
136641     if( rc==SQLITE_OK ) rc = rc2;
136642   }
136643 
136644   sqlite3Fts3SegmentsClose(p);
136645   sqlite3Fts3PendingTermsClear(p);
136646 
136647   return (rc==SQLITE_OK && bReturnDone && bSeenDone) ? SQLITE_DONE : rc;
136648 }
136649 
136650 /*
136651 ** This function is called when the user executes the following statement:
136652 **
136653 **     INSERT INTO <tbl>(<tbl>) VALUES('rebuild');
136654 **
136655 ** The entire FTS index is discarded and rebuilt. If the table is one 
136656 ** created using the content=xxx option, then the new index is based on
136657 ** the current contents of the xxx table. Otherwise, it is rebuilt based
136658 ** on the contents of the %_content table.
136659 */
136660 static int fts3DoRebuild(Fts3Table *p){
136661   int rc;                         /* Return Code */
136662 
136663   rc = fts3DeleteAll(p, 0);
136664   if( rc==SQLITE_OK ){
136665     u32 *aSz = 0;
136666     u32 *aSzIns = 0;
136667     u32 *aSzDel = 0;
136668     sqlite3_stmt *pStmt = 0;
136669     int nEntry = 0;
136670 
136671     /* Compose and prepare an SQL statement to loop through the content table */
136672     char *zSql = sqlite3_mprintf("SELECT %s" , p->zReadExprlist);
136673     if( !zSql ){
136674       rc = SQLITE_NOMEM;
136675     }else{
136676       rc = sqlite3_prepare_v2(p->db, zSql, -1, &pStmt, 0);
136677       sqlite3_free(zSql);
136678     }
136679 
136680     if( rc==SQLITE_OK ){
136681       int nByte = sizeof(u32) * (p->nColumn+1)*3;
136682       aSz = (u32 *)sqlite3_malloc(nByte);
136683       if( aSz==0 ){
136684         rc = SQLITE_NOMEM;
136685       }else{
136686         memset(aSz, 0, nByte);
136687         aSzIns = &aSz[p->nColumn+1];
136688         aSzDel = &aSzIns[p->nColumn+1];
136689       }
136690     }
136691 
136692     while( rc==SQLITE_OK && SQLITE_ROW==sqlite3_step(pStmt) ){
136693       int iCol;
136694       int iLangid = langidFromSelect(p, pStmt);
136695       rc = fts3PendingTermsDocid(p, iLangid, sqlite3_column_int64(pStmt, 0));
136696       memset(aSz, 0, sizeof(aSz[0]) * (p->nColumn+1));
136697       for(iCol=0; rc==SQLITE_OK && iCol<p->nColumn; iCol++){
136698         if( p->abNotindexed[iCol]==0 ){
136699           const char *z = (const char *) sqlite3_column_text(pStmt, iCol+1);
136700           rc = fts3PendingTermsAdd(p, iLangid, z, iCol, &aSz[iCol]);
136701           aSz[p->nColumn] += sqlite3_column_bytes(pStmt, iCol+1);
136702         }
136703       }
136704       if( p->bHasDocsize ){
136705         fts3InsertDocsize(&rc, p, aSz);
136706       }
136707       if( rc!=SQLITE_OK ){
136708         sqlite3_finalize(pStmt);
136709         pStmt = 0;
136710       }else{
136711         nEntry++;
136712         for(iCol=0; iCol<=p->nColumn; iCol++){
136713           aSzIns[iCol] += aSz[iCol];
136714         }
136715       }
136716     }
136717     if( p->bFts4 ){
136718       fts3UpdateDocTotals(&rc, p, aSzIns, aSzDel, nEntry);
136719     }
136720     sqlite3_free(aSz);
136721 
136722     if( pStmt ){
136723       int rc2 = sqlite3_finalize(pStmt);
136724       if( rc==SQLITE_OK ){
136725         rc = rc2;
136726       }
136727     }
136728   }
136729 
136730   return rc;
136731 }
136732 
136733 
136734 /*
136735 ** This function opens a cursor used to read the input data for an 
136736 ** incremental merge operation. Specifically, it opens a cursor to scan
136737 ** the oldest nSeg segments (idx=0 through idx=(nSeg-1)) in absolute 
136738 ** level iAbsLevel.
136739 */
136740 static int fts3IncrmergeCsr(
136741   Fts3Table *p,                   /* FTS3 table handle */
136742   sqlite3_int64 iAbsLevel,        /* Absolute level to open */
136743   int nSeg,                       /* Number of segments to merge */
136744   Fts3MultiSegReader *pCsr        /* Cursor object to populate */
136745 ){
136746   int rc;                         /* Return Code */
136747   sqlite3_stmt *pStmt = 0;        /* Statement used to read %_segdir entry */  
136748   int nByte;                      /* Bytes allocated at pCsr->apSegment[] */
136749 
136750   /* Allocate space for the Fts3MultiSegReader.aCsr[] array */
136751   memset(pCsr, 0, sizeof(*pCsr));
136752   nByte = sizeof(Fts3SegReader *) * nSeg;
136753   pCsr->apSegment = (Fts3SegReader **)sqlite3_malloc(nByte);
136754 
136755   if( pCsr->apSegment==0 ){
136756     rc = SQLITE_NOMEM;
136757   }else{
136758     memset(pCsr->apSegment, 0, nByte);
136759     rc = fts3SqlStmt(p, SQL_SELECT_LEVEL, &pStmt, 0);
136760   }
136761   if( rc==SQLITE_OK ){
136762     int i;
136763     int rc2;
136764     sqlite3_bind_int64(pStmt, 1, iAbsLevel);
136765     assert( pCsr->nSegment==0 );
136766     for(i=0; rc==SQLITE_OK && sqlite3_step(pStmt)==SQLITE_ROW && i<nSeg; i++){
136767       rc = sqlite3Fts3SegReaderNew(i, 0,
136768           sqlite3_column_int64(pStmt, 1),        /* segdir.start_block */
136769           sqlite3_column_int64(pStmt, 2),        /* segdir.leaves_end_block */
136770           sqlite3_column_int64(pStmt, 3),        /* segdir.end_block */
136771           sqlite3_column_blob(pStmt, 4),         /* segdir.root */
136772           sqlite3_column_bytes(pStmt, 4),        /* segdir.root */
136773           &pCsr->apSegment[i]
136774       );
136775       pCsr->nSegment++;
136776     }
136777     rc2 = sqlite3_reset(pStmt);
136778     if( rc==SQLITE_OK ) rc = rc2;
136779   }
136780 
136781   return rc;
136782 }
136783 
136784 typedef struct IncrmergeWriter IncrmergeWriter;
136785 typedef struct NodeWriter NodeWriter;
136786 typedef struct Blob Blob;
136787 typedef struct NodeReader NodeReader;
136788 
136789 /*
136790 ** An instance of the following structure is used as a dynamic buffer
136791 ** to build up nodes or other blobs of data in.
136792 **
136793 ** The function blobGrowBuffer() is used to extend the allocation.
136794 */
136795 struct Blob {
136796   char *a;                        /* Pointer to allocation */
136797   int n;                          /* Number of valid bytes of data in a[] */
136798   int nAlloc;                     /* Allocated size of a[] (nAlloc>=n) */
136799 };
136800 
136801 /*
136802 ** This structure is used to build up buffers containing segment b-tree 
136803 ** nodes (blocks).
136804 */
136805 struct NodeWriter {
136806   sqlite3_int64 iBlock;           /* Current block id */
136807   Blob key;                       /* Last key written to the current block */
136808   Blob block;                     /* Current block image */
136809 };
136810 
136811 /*
136812 ** An object of this type contains the state required to create or append
136813 ** to an appendable b-tree segment.
136814 */
136815 struct IncrmergeWriter {
136816   int nLeafEst;                   /* Space allocated for leaf blocks */
136817   int nWork;                      /* Number of leaf pages flushed */
136818   sqlite3_int64 iAbsLevel;        /* Absolute level of input segments */
136819   int iIdx;                       /* Index of *output* segment in iAbsLevel+1 */
136820   sqlite3_int64 iStart;           /* Block number of first allocated block */
136821   sqlite3_int64 iEnd;             /* Block number of last allocated block */
136822   NodeWriter aNodeWriter[FTS_MAX_APPENDABLE_HEIGHT];
136823 };
136824 
136825 /*
136826 ** An object of the following type is used to read data from a single
136827 ** FTS segment node. See the following functions:
136828 **
136829 **     nodeReaderInit()
136830 **     nodeReaderNext()
136831 **     nodeReaderRelease()
136832 */
136833 struct NodeReader {
136834   const char *aNode;
136835   int nNode;
136836   int iOff;                       /* Current offset within aNode[] */
136837 
136838   /* Output variables. Containing the current node entry. */
136839   sqlite3_int64 iChild;           /* Pointer to child node */
136840   Blob term;                      /* Current term */
136841   const char *aDoclist;           /* Pointer to doclist */
136842   int nDoclist;                   /* Size of doclist in bytes */
136843 };
136844 
136845 /*
136846 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
136847 ** Otherwise, if the allocation at pBlob->a is not already at least nMin
136848 ** bytes in size, extend (realloc) it to be so.
136849 **
136850 ** If an OOM error occurs, set *pRc to SQLITE_NOMEM and leave pBlob->a
136851 ** unmodified. Otherwise, if the allocation succeeds, update pBlob->nAlloc
136852 ** to reflect the new size of the pBlob->a[] buffer.
136853 */
136854 static void blobGrowBuffer(Blob *pBlob, int nMin, int *pRc){
136855   if( *pRc==SQLITE_OK && nMin>pBlob->nAlloc ){
136856     int nAlloc = nMin;
136857     char *a = (char *)sqlite3_realloc(pBlob->a, nAlloc);
136858     if( a ){
136859       pBlob->nAlloc = nAlloc;
136860       pBlob->a = a;
136861     }else{
136862       *pRc = SQLITE_NOMEM;
136863     }
136864   }
136865 }
136866 
136867 /*
136868 ** Attempt to advance the node-reader object passed as the first argument to
136869 ** the next entry on the node. 
136870 **
136871 ** Return an error code if an error occurs (SQLITE_NOMEM is possible). 
136872 ** Otherwise return SQLITE_OK. If there is no next entry on the node
136873 ** (e.g. because the current entry is the last) set NodeReader->aNode to
136874 ** NULL to indicate EOF. Otherwise, populate the NodeReader structure output 
136875 ** variables for the new entry.
136876 */
136877 static int nodeReaderNext(NodeReader *p){
136878   int bFirst = (p->term.n==0);    /* True for first term on the node */
136879   int nPrefix = 0;                /* Bytes to copy from previous term */
136880   int nSuffix = 0;                /* Bytes to append to the prefix */
136881   int rc = SQLITE_OK;             /* Return code */
136882 
136883   assert( p->aNode );
136884   if( p->iChild && bFirst==0 ) p->iChild++;
136885   if( p->iOff>=p->nNode ){
136886     /* EOF */
136887     p->aNode = 0;
136888   }else{
136889     if( bFirst==0 ){
136890       p->iOff += fts3GetVarint32(&p->aNode[p->iOff], &nPrefix);
136891     }
136892     p->iOff += fts3GetVarint32(&p->aNode[p->iOff], &nSuffix);
136893 
136894     blobGrowBuffer(&p->term, nPrefix+nSuffix, &rc);
136895     if( rc==SQLITE_OK ){
136896       memcpy(&p->term.a[nPrefix], &p->aNode[p->iOff], nSuffix);
136897       p->term.n = nPrefix+nSuffix;
136898       p->iOff += nSuffix;
136899       if( p->iChild==0 ){
136900         p->iOff += fts3GetVarint32(&p->aNode[p->iOff], &p->nDoclist);
136901         p->aDoclist = &p->aNode[p->iOff];
136902         p->iOff += p->nDoclist;
136903       }
136904     }
136905   }
136906 
136907   assert( p->iOff<=p->nNode );
136908 
136909   return rc;
136910 }
136911 
136912 /*
136913 ** Release all dynamic resources held by node-reader object *p.
136914 */
136915 static void nodeReaderRelease(NodeReader *p){
136916   sqlite3_free(p->term.a);
136917 }
136918 
136919 /*
136920 ** Initialize a node-reader object to read the node in buffer aNode/nNode.
136921 **
136922 ** If successful, SQLITE_OK is returned and the NodeReader object set to 
136923 ** point to the first entry on the node (if any). Otherwise, an SQLite
136924 ** error code is returned.
136925 */
136926 static int nodeReaderInit(NodeReader *p, const char *aNode, int nNode){
136927   memset(p, 0, sizeof(NodeReader));
136928   p->aNode = aNode;
136929   p->nNode = nNode;
136930 
136931   /* Figure out if this is a leaf or an internal node. */
136932   if( p->aNode[0] ){
136933     /* An internal node. */
136934     p->iOff = 1 + sqlite3Fts3GetVarint(&p->aNode[1], &p->iChild);
136935   }else{
136936     p->iOff = 1;
136937   }
136938 
136939   return nodeReaderNext(p);
136940 }
136941 
136942 /*
136943 ** This function is called while writing an FTS segment each time a leaf o
136944 ** node is finished and written to disk. The key (zTerm/nTerm) is guaranteed
136945 ** to be greater than the largest key on the node just written, but smaller
136946 ** than or equal to the first key that will be written to the next leaf
136947 ** node.
136948 **
136949 ** The block id of the leaf node just written to disk may be found in
136950 ** (pWriter->aNodeWriter[0].iBlock) when this function is called.
136951 */
136952 static int fts3IncrmergePush(
136953   Fts3Table *p,                   /* Fts3 table handle */
136954   IncrmergeWriter *pWriter,       /* Writer object */
136955   const char *zTerm,              /* Term to write to internal node */
136956   int nTerm                       /* Bytes at zTerm */
136957 ){
136958   sqlite3_int64 iPtr = pWriter->aNodeWriter[0].iBlock;
136959   int iLayer;
136960 
136961   assert( nTerm>0 );
136962   for(iLayer=1; ALWAYS(iLayer<FTS_MAX_APPENDABLE_HEIGHT); iLayer++){
136963     sqlite3_int64 iNextPtr = 0;
136964     NodeWriter *pNode = &pWriter->aNodeWriter[iLayer];
136965     int rc = SQLITE_OK;
136966     int nPrefix;
136967     int nSuffix;
136968     int nSpace;
136969 
136970     /* Figure out how much space the key will consume if it is written to
136971     ** the current node of layer iLayer. Due to the prefix compression, 
136972     ** the space required changes depending on which node the key is to
136973     ** be added to.  */
136974     nPrefix = fts3PrefixCompress(pNode->key.a, pNode->key.n, zTerm, nTerm);
136975     nSuffix = nTerm - nPrefix;
136976     nSpace  = sqlite3Fts3VarintLen(nPrefix);
136977     nSpace += sqlite3Fts3VarintLen(nSuffix) + nSuffix;
136978 
136979     if( pNode->key.n==0 || (pNode->block.n + nSpace)<=p->nNodeSize ){ 
136980       /* If the current node of layer iLayer contains zero keys, or if adding
136981       ** the key to it will not cause it to grow to larger than nNodeSize 
136982       ** bytes in size, write the key here.  */
136983 
136984       Blob *pBlk = &pNode->block;
136985       if( pBlk->n==0 ){
136986         blobGrowBuffer(pBlk, p->nNodeSize, &rc);
136987         if( rc==SQLITE_OK ){
136988           pBlk->a[0] = (char)iLayer;
136989           pBlk->n = 1 + sqlite3Fts3PutVarint(&pBlk->a[1], iPtr);
136990         }
136991       }
136992       blobGrowBuffer(pBlk, pBlk->n + nSpace, &rc);
136993       blobGrowBuffer(&pNode->key, nTerm, &rc);
136994 
136995       if( rc==SQLITE_OK ){
136996         if( pNode->key.n ){
136997           pBlk->n += sqlite3Fts3PutVarint(&pBlk->a[pBlk->n], nPrefix);
136998         }
136999         pBlk->n += sqlite3Fts3PutVarint(&pBlk->a[pBlk->n], nSuffix);
137000         memcpy(&pBlk->a[pBlk->n], &zTerm[nPrefix], nSuffix);
137001         pBlk->n += nSuffix;
137002 
137003         memcpy(pNode->key.a, zTerm, nTerm);
137004         pNode->key.n = nTerm;
137005       }
137006     }else{
137007       /* Otherwise, flush the current node of layer iLayer to disk.
137008       ** Then allocate a new, empty sibling node. The key will be written
137009       ** into the parent of this node. */
137010       rc = fts3WriteSegment(p, pNode->iBlock, pNode->block.a, pNode->block.n);
137011 
137012       assert( pNode->block.nAlloc>=p->nNodeSize );
137013       pNode->block.a[0] = (char)iLayer;
137014       pNode->block.n = 1 + sqlite3Fts3PutVarint(&pNode->block.a[1], iPtr+1);
137015 
137016       iNextPtr = pNode->iBlock;
137017       pNode->iBlock++;
137018       pNode->key.n = 0;
137019     }
137020 
137021     if( rc!=SQLITE_OK || iNextPtr==0 ) return rc;
137022     iPtr = iNextPtr;
137023   }
137024 
137025   assert( 0 );
137026   return 0;
137027 }
137028 
137029 /*
137030 ** Append a term and (optionally) doclist to the FTS segment node currently
137031 ** stored in blob *pNode. The node need not contain any terms, but the
137032 ** header must be written before this function is called.
137033 **
137034 ** A node header is a single 0x00 byte for a leaf node, or a height varint
137035 ** followed by the left-hand-child varint for an internal node.
137036 **
137037 ** The term to be appended is passed via arguments zTerm/nTerm. For a 
137038 ** leaf node, the doclist is passed as aDoclist/nDoclist. For an internal
137039 ** node, both aDoclist and nDoclist must be passed 0.
137040 **
137041 ** If the size of the value in blob pPrev is zero, then this is the first
137042 ** term written to the node. Otherwise, pPrev contains a copy of the 
137043 ** previous term. Before this function returns, it is updated to contain a
137044 ** copy of zTerm/nTerm.
137045 **
137046 ** It is assumed that the buffer associated with pNode is already large
137047 ** enough to accommodate the new entry. The buffer associated with pPrev
137048 ** is extended by this function if requrired.
137049 **
137050 ** If an error (i.e. OOM condition) occurs, an SQLite error code is
137051 ** returned. Otherwise, SQLITE_OK.
137052 */
137053 static int fts3AppendToNode(
137054   Blob *pNode,                    /* Current node image to append to */
137055   Blob *pPrev,                    /* Buffer containing previous term written */
137056   const char *zTerm,              /* New term to write */
137057   int nTerm,                      /* Size of zTerm in bytes */
137058   const char *aDoclist,           /* Doclist (or NULL) to write */
137059   int nDoclist                    /* Size of aDoclist in bytes */ 
137060 ){
137061   int rc = SQLITE_OK;             /* Return code */
137062   int bFirst = (pPrev->n==0);     /* True if this is the first term written */
137063   int nPrefix;                    /* Size of term prefix in bytes */
137064   int nSuffix;                    /* Size of term suffix in bytes */
137065 
137066   /* Node must have already been started. There must be a doclist for a
137067   ** leaf node, and there must not be a doclist for an internal node.  */
137068   assert( pNode->n>0 );
137069   assert( (pNode->a[0]=='\0')==(aDoclist!=0) );
137070 
137071   blobGrowBuffer(pPrev, nTerm, &rc);
137072   if( rc!=SQLITE_OK ) return rc;
137073 
137074   nPrefix = fts3PrefixCompress(pPrev->a, pPrev->n, zTerm, nTerm);
137075   nSuffix = nTerm - nPrefix;
137076   memcpy(pPrev->a, zTerm, nTerm);
137077   pPrev->n = nTerm;
137078 
137079   if( bFirst==0 ){
137080     pNode->n += sqlite3Fts3PutVarint(&pNode->a[pNode->n], nPrefix);
137081   }
137082   pNode->n += sqlite3Fts3PutVarint(&pNode->a[pNode->n], nSuffix);
137083   memcpy(&pNode->a[pNode->n], &zTerm[nPrefix], nSuffix);
137084   pNode->n += nSuffix;
137085 
137086   if( aDoclist ){
137087     pNode->n += sqlite3Fts3PutVarint(&pNode->a[pNode->n], nDoclist);
137088     memcpy(&pNode->a[pNode->n], aDoclist, nDoclist);
137089     pNode->n += nDoclist;
137090   }
137091 
137092   assert( pNode->n<=pNode->nAlloc );
137093 
137094   return SQLITE_OK;
137095 }
137096 
137097 /*
137098 ** Append the current term and doclist pointed to by cursor pCsr to the
137099 ** appendable b-tree segment opened for writing by pWriter.
137100 **
137101 ** Return SQLITE_OK if successful, or an SQLite error code otherwise.
137102 */
137103 static int fts3IncrmergeAppend(
137104   Fts3Table *p,                   /* Fts3 table handle */
137105   IncrmergeWriter *pWriter,       /* Writer object */
137106   Fts3MultiSegReader *pCsr        /* Cursor containing term and doclist */
137107 ){
137108   const char *zTerm = pCsr->zTerm;
137109   int nTerm = pCsr->nTerm;
137110   const char *aDoclist = pCsr->aDoclist;
137111   int nDoclist = pCsr->nDoclist;
137112   int rc = SQLITE_OK;           /* Return code */
137113   int nSpace;                   /* Total space in bytes required on leaf */
137114   int nPrefix;                  /* Size of prefix shared with previous term */
137115   int nSuffix;                  /* Size of suffix (nTerm - nPrefix) */
137116   NodeWriter *pLeaf;            /* Object used to write leaf nodes */
137117 
137118   pLeaf = &pWriter->aNodeWriter[0];
137119   nPrefix = fts3PrefixCompress(pLeaf->key.a, pLeaf->key.n, zTerm, nTerm);
137120   nSuffix = nTerm - nPrefix;
137121 
137122   nSpace  = sqlite3Fts3VarintLen(nPrefix);
137123   nSpace += sqlite3Fts3VarintLen(nSuffix) + nSuffix;
137124   nSpace += sqlite3Fts3VarintLen(nDoclist) + nDoclist;
137125 
137126   /* If the current block is not empty, and if adding this term/doclist
137127   ** to the current block would make it larger than Fts3Table.nNodeSize
137128   ** bytes, write this block out to the database. */
137129   if( pLeaf->block.n>0 && (pLeaf->block.n + nSpace)>p->nNodeSize ){
137130     rc = fts3WriteSegment(p, pLeaf->iBlock, pLeaf->block.a, pLeaf->block.n);
137131     pWriter->nWork++;
137132 
137133     /* Add the current term to the parent node. The term added to the 
137134     ** parent must:
137135     **
137136     **   a) be greater than the largest term on the leaf node just written
137137     **      to the database (still available in pLeaf->key), and
137138     **
137139     **   b) be less than or equal to the term about to be added to the new
137140     **      leaf node (zTerm/nTerm).
137141     **
137142     ** In other words, it must be the prefix of zTerm 1 byte longer than
137143     ** the common prefix (if any) of zTerm and pWriter->zTerm.
137144     */
137145     if( rc==SQLITE_OK ){
137146       rc = fts3IncrmergePush(p, pWriter, zTerm, nPrefix+1);
137147     }
137148 
137149     /* Advance to the next output block */
137150     pLeaf->iBlock++;
137151     pLeaf->key.n = 0;
137152     pLeaf->block.n = 0;
137153 
137154     nSuffix = nTerm;
137155     nSpace  = 1;
137156     nSpace += sqlite3Fts3VarintLen(nSuffix) + nSuffix;
137157     nSpace += sqlite3Fts3VarintLen(nDoclist) + nDoclist;
137158   }
137159 
137160   blobGrowBuffer(&pLeaf->block, pLeaf->block.n + nSpace, &rc);
137161 
137162   if( rc==SQLITE_OK ){
137163     if( pLeaf->block.n==0 ){
137164       pLeaf->block.n = 1;
137165       pLeaf->block.a[0] = '\0';
137166     }
137167     rc = fts3AppendToNode(
137168         &pLeaf->block, &pLeaf->key, zTerm, nTerm, aDoclist, nDoclist
137169     );
137170   }
137171 
137172   return rc;
137173 }
137174 
137175 /*
137176 ** This function is called to release all dynamic resources held by the
137177 ** merge-writer object pWriter, and if no error has occurred, to flush
137178 ** all outstanding node buffers held by pWriter to disk.
137179 **
137180 ** If *pRc is not SQLITE_OK when this function is called, then no attempt
137181 ** is made to write any data to disk. Instead, this function serves only
137182 ** to release outstanding resources.
137183 **
137184 ** Otherwise, if *pRc is initially SQLITE_OK and an error occurs while
137185 ** flushing buffers to disk, *pRc is set to an SQLite error code before
137186 ** returning.
137187 */
137188 static void fts3IncrmergeRelease(
137189   Fts3Table *p,                   /* FTS3 table handle */
137190   IncrmergeWriter *pWriter,       /* Merge-writer object */
137191   int *pRc                        /* IN/OUT: Error code */
137192 ){
137193   int i;                          /* Used to iterate through non-root layers */
137194   int iRoot;                      /* Index of root in pWriter->aNodeWriter */
137195   NodeWriter *pRoot;              /* NodeWriter for root node */
137196   int rc = *pRc;                  /* Error code */
137197 
137198   /* Set iRoot to the index in pWriter->aNodeWriter[] of the output segment 
137199   ** root node. If the segment fits entirely on a single leaf node, iRoot
137200   ** will be set to 0. If the root node is the parent of the leaves, iRoot
137201   ** will be 1. And so on.  */
137202   for(iRoot=FTS_MAX_APPENDABLE_HEIGHT-1; iRoot>=0; iRoot--){
137203     NodeWriter *pNode = &pWriter->aNodeWriter[iRoot];
137204     if( pNode->block.n>0 ) break;
137205     assert( *pRc || pNode->block.nAlloc==0 );
137206     assert( *pRc || pNode->key.nAlloc==0 );
137207     sqlite3_free(pNode->block.a);
137208     sqlite3_free(pNode->key.a);
137209   }
137210 
137211   /* Empty output segment. This is a no-op. */
137212   if( iRoot<0 ) return;
137213 
137214   /* The entire output segment fits on a single node. Normally, this means
137215   ** the node would be stored as a blob in the "root" column of the %_segdir
137216   ** table. However, this is not permitted in this case. The problem is that 
137217   ** space has already been reserved in the %_segments table, and so the 
137218   ** start_block and end_block fields of the %_segdir table must be populated. 
137219   ** And, by design or by accident, released versions of FTS cannot handle 
137220   ** segments that fit entirely on the root node with start_block!=0.
137221   **
137222   ** Instead, create a synthetic root node that contains nothing but a 
137223   ** pointer to the single content node. So that the segment consists of a
137224   ** single leaf and a single interior (root) node.
137225   **
137226   ** Todo: Better might be to defer allocating space in the %_segments 
137227   ** table until we are sure it is needed.
137228   */
137229   if( iRoot==0 ){
137230     Blob *pBlock = &pWriter->aNodeWriter[1].block;
137231     blobGrowBuffer(pBlock, 1 + FTS3_VARINT_MAX, &rc);
137232     if( rc==SQLITE_OK ){
137233       pBlock->a[0] = 0x01;
137234       pBlock->n = 1 + sqlite3Fts3PutVarint(
137235           &pBlock->a[1], pWriter->aNodeWriter[0].iBlock
137236       );
137237     }
137238     iRoot = 1;
137239   }
137240   pRoot = &pWriter->aNodeWriter[iRoot];
137241 
137242   /* Flush all currently outstanding nodes to disk. */
137243   for(i=0; i<iRoot; i++){
137244     NodeWriter *pNode = &pWriter->aNodeWriter[i];
137245     if( pNode->block.n>0 && rc==SQLITE_OK ){
137246       rc = fts3WriteSegment(p, pNode->iBlock, pNode->block.a, pNode->block.n);
137247     }
137248     sqlite3_free(pNode->block.a);
137249     sqlite3_free(pNode->key.a);
137250   }
137251 
137252   /* Write the %_segdir record. */
137253   if( rc==SQLITE_OK ){
137254     rc = fts3WriteSegdir(p, 
137255         pWriter->iAbsLevel+1,               /* level */
137256         pWriter->iIdx,                      /* idx */
137257         pWriter->iStart,                    /* start_block */
137258         pWriter->aNodeWriter[0].iBlock,     /* leaves_end_block */
137259         pWriter->iEnd,                      /* end_block */
137260         pRoot->block.a, pRoot->block.n      /* root */
137261     );
137262   }
137263   sqlite3_free(pRoot->block.a);
137264   sqlite3_free(pRoot->key.a);
137265 
137266   *pRc = rc;
137267 }
137268 
137269 /*
137270 ** Compare the term in buffer zLhs (size in bytes nLhs) with that in
137271 ** zRhs (size in bytes nRhs) using memcmp. If one term is a prefix of
137272 ** the other, it is considered to be smaller than the other.
137273 **
137274 ** Return -ve if zLhs is smaller than zRhs, 0 if it is equal, or +ve
137275 ** if it is greater.
137276 */
137277 static int fts3TermCmp(
137278   const char *zLhs, int nLhs,     /* LHS of comparison */
137279   const char *zRhs, int nRhs      /* RHS of comparison */
137280 ){
137281   int nCmp = MIN(nLhs, nRhs);
137282   int res;
137283 
137284   res = memcmp(zLhs, zRhs, nCmp);
137285   if( res==0 ) res = nLhs - nRhs;
137286 
137287   return res;
137288 }
137289 
137290 
137291 /*
137292 ** Query to see if the entry in the %_segments table with blockid iEnd is 
137293 ** NULL. If no error occurs and the entry is NULL, set *pbRes 1 before
137294 ** returning. Otherwise, set *pbRes to 0. 
137295 **
137296 ** Or, if an error occurs while querying the database, return an SQLite 
137297 ** error code. The final value of *pbRes is undefined in this case.
137298 **
137299 ** This is used to test if a segment is an "appendable" segment. If it
137300 ** is, then a NULL entry has been inserted into the %_segments table
137301 ** with blockid %_segdir.end_block.
137302 */
137303 static int fts3IsAppendable(Fts3Table *p, sqlite3_int64 iEnd, int *pbRes){
137304   int bRes = 0;                   /* Result to set *pbRes to */
137305   sqlite3_stmt *pCheck = 0;       /* Statement to query database with */
137306   int rc;                         /* Return code */
137307 
137308   rc = fts3SqlStmt(p, SQL_SEGMENT_IS_APPENDABLE, &pCheck, 0);
137309   if( rc==SQLITE_OK ){
137310     sqlite3_bind_int64(pCheck, 1, iEnd);
137311     if( SQLITE_ROW==sqlite3_step(pCheck) ) bRes = 1;
137312     rc = sqlite3_reset(pCheck);
137313   }
137314   
137315   *pbRes = bRes;
137316   return rc;
137317 }
137318 
137319 /*
137320 ** This function is called when initializing an incremental-merge operation.
137321 ** It checks if the existing segment with index value iIdx at absolute level 
137322 ** (iAbsLevel+1) can be appended to by the incremental merge. If it can, the
137323 ** merge-writer object *pWriter is initialized to write to it.
137324 **
137325 ** An existing segment can be appended to by an incremental merge if:
137326 **
137327 **   * It was initially created as an appendable segment (with all required
137328 **     space pre-allocated), and
137329 **
137330 **   * The first key read from the input (arguments zKey and nKey) is 
137331 **     greater than the largest key currently stored in the potential
137332 **     output segment.
137333 */
137334 static int fts3IncrmergeLoad(
137335   Fts3Table *p,                   /* Fts3 table handle */
137336   sqlite3_int64 iAbsLevel,        /* Absolute level of input segments */
137337   int iIdx,                       /* Index of candidate output segment */
137338   const char *zKey,               /* First key to write */
137339   int nKey,                       /* Number of bytes in nKey */
137340   IncrmergeWriter *pWriter        /* Populate this object */
137341 ){
137342   int rc;                         /* Return code */
137343   sqlite3_stmt *pSelect = 0;      /* SELECT to read %_segdir entry */
137344 
137345   rc = fts3SqlStmt(p, SQL_SELECT_SEGDIR, &pSelect, 0);
137346   if( rc==SQLITE_OK ){
137347     sqlite3_int64 iStart = 0;     /* Value of %_segdir.start_block */
137348     sqlite3_int64 iLeafEnd = 0;   /* Value of %_segdir.leaves_end_block */
137349     sqlite3_int64 iEnd = 0;       /* Value of %_segdir.end_block */
137350     const char *aRoot = 0;        /* Pointer to %_segdir.root buffer */
137351     int nRoot = 0;                /* Size of aRoot[] in bytes */
137352     int rc2;                      /* Return code from sqlite3_reset() */
137353     int bAppendable = 0;          /* Set to true if segment is appendable */
137354 
137355     /* Read the %_segdir entry for index iIdx absolute level (iAbsLevel+1) */
137356     sqlite3_bind_int64(pSelect, 1, iAbsLevel+1);
137357     sqlite3_bind_int(pSelect, 2, iIdx);
137358     if( sqlite3_step(pSelect)==SQLITE_ROW ){
137359       iStart = sqlite3_column_int64(pSelect, 1);
137360       iLeafEnd = sqlite3_column_int64(pSelect, 2);
137361       iEnd = sqlite3_column_int64(pSelect, 3);
137362       nRoot = sqlite3_column_bytes(pSelect, 4);
137363       aRoot = sqlite3_column_blob(pSelect, 4);
137364     }else{
137365       return sqlite3_reset(pSelect);
137366     }
137367 
137368     /* Check for the zero-length marker in the %_segments table */
137369     rc = fts3IsAppendable(p, iEnd, &bAppendable);
137370 
137371     /* Check that zKey/nKey is larger than the largest key the candidate */
137372     if( rc==SQLITE_OK && bAppendable ){
137373       char *aLeaf = 0;
137374       int nLeaf = 0;
137375 
137376       rc = sqlite3Fts3ReadBlock(p, iLeafEnd, &aLeaf, &nLeaf, 0);
137377       if( rc==SQLITE_OK ){
137378         NodeReader reader;
137379         for(rc = nodeReaderInit(&reader, aLeaf, nLeaf);
137380             rc==SQLITE_OK && reader.aNode;
137381             rc = nodeReaderNext(&reader)
137382         ){
137383           assert( reader.aNode );
137384         }
137385         if( fts3TermCmp(zKey, nKey, reader.term.a, reader.term.n)<=0 ){
137386           bAppendable = 0;
137387         }
137388         nodeReaderRelease(&reader);
137389       }
137390       sqlite3_free(aLeaf);
137391     }
137392 
137393     if( rc==SQLITE_OK && bAppendable ){
137394       /* It is possible to append to this segment. Set up the IncrmergeWriter
137395       ** object to do so.  */
137396       int i;
137397       int nHeight = (int)aRoot[0];
137398       NodeWriter *pNode;
137399 
137400       pWriter->nLeafEst = (int)((iEnd - iStart) + 1)/FTS_MAX_APPENDABLE_HEIGHT;
137401       pWriter->iStart = iStart;
137402       pWriter->iEnd = iEnd;
137403       pWriter->iAbsLevel = iAbsLevel;
137404       pWriter->iIdx = iIdx;
137405 
137406       for(i=nHeight+1; i<FTS_MAX_APPENDABLE_HEIGHT; i++){
137407         pWriter->aNodeWriter[i].iBlock = pWriter->iStart + i*pWriter->nLeafEst;
137408       }
137409 
137410       pNode = &pWriter->aNodeWriter[nHeight];
137411       pNode->iBlock = pWriter->iStart + pWriter->nLeafEst*nHeight;
137412       blobGrowBuffer(&pNode->block, MAX(nRoot, p->nNodeSize), &rc);
137413       if( rc==SQLITE_OK ){
137414         memcpy(pNode->block.a, aRoot, nRoot);
137415         pNode->block.n = nRoot;
137416       }
137417 
137418       for(i=nHeight; i>=0 && rc==SQLITE_OK; i--){
137419         NodeReader reader;
137420         pNode = &pWriter->aNodeWriter[i];
137421 
137422         rc = nodeReaderInit(&reader, pNode->block.a, pNode->block.n);
137423         while( reader.aNode && rc==SQLITE_OK ) rc = nodeReaderNext(&reader);
137424         blobGrowBuffer(&pNode->key, reader.term.n, &rc);
137425         if( rc==SQLITE_OK ){
137426           memcpy(pNode->key.a, reader.term.a, reader.term.n);
137427           pNode->key.n = reader.term.n;
137428           if( i>0 ){
137429             char *aBlock = 0;
137430             int nBlock = 0;
137431             pNode = &pWriter->aNodeWriter[i-1];
137432             pNode->iBlock = reader.iChild;
137433             rc = sqlite3Fts3ReadBlock(p, reader.iChild, &aBlock, &nBlock, 0);
137434             blobGrowBuffer(&pNode->block, MAX(nBlock, p->nNodeSize), &rc);
137435             if( rc==SQLITE_OK ){
137436               memcpy(pNode->block.a, aBlock, nBlock);
137437               pNode->block.n = nBlock;
137438             }
137439             sqlite3_free(aBlock);
137440           }
137441         }
137442         nodeReaderRelease(&reader);
137443       }
137444     }
137445 
137446     rc2 = sqlite3_reset(pSelect);
137447     if( rc==SQLITE_OK ) rc = rc2;
137448   }
137449 
137450   return rc;
137451 }
137452 
137453 /*
137454 ** Determine the largest segment index value that exists within absolute
137455 ** level iAbsLevel+1. If no error occurs, set *piIdx to this value plus
137456 ** one before returning SQLITE_OK. Or, if there are no segments at all 
137457 ** within level iAbsLevel, set *piIdx to zero.
137458 **
137459 ** If an error occurs, return an SQLite error code. The final value of
137460 ** *piIdx is undefined in this case.
137461 */
137462 static int fts3IncrmergeOutputIdx( 
137463   Fts3Table *p,                   /* FTS Table handle */
137464   sqlite3_int64 iAbsLevel,        /* Absolute index of input segments */
137465   int *piIdx                      /* OUT: Next free index at iAbsLevel+1 */
137466 ){
137467   int rc;
137468   sqlite3_stmt *pOutputIdx = 0;   /* SQL used to find output index */
137469 
137470   rc = fts3SqlStmt(p, SQL_NEXT_SEGMENT_INDEX, &pOutputIdx, 0);
137471   if( rc==SQLITE_OK ){
137472     sqlite3_bind_int64(pOutputIdx, 1, iAbsLevel+1);
137473     sqlite3_step(pOutputIdx);
137474     *piIdx = sqlite3_column_int(pOutputIdx, 0);
137475     rc = sqlite3_reset(pOutputIdx);
137476   }
137477 
137478   return rc;
137479 }
137480 
137481 /* 
137482 ** Allocate an appendable output segment on absolute level iAbsLevel+1
137483 ** with idx value iIdx.
137484 **
137485 ** In the %_segdir table, a segment is defined by the values in three
137486 ** columns:
137487 **
137488 **     start_block
137489 **     leaves_end_block
137490 **     end_block
137491 **
137492 ** When an appendable segment is allocated, it is estimated that the
137493 ** maximum number of leaf blocks that may be required is the sum of the
137494 ** number of leaf blocks consumed by the input segments, plus the number
137495 ** of input segments, multiplied by two. This value is stored in stack 
137496 ** variable nLeafEst.
137497 **
137498 ** A total of 16*nLeafEst blocks are allocated when an appendable segment
137499 ** is created ((1 + end_block - start_block)==16*nLeafEst). The contiguous
137500 ** array of leaf nodes starts at the first block allocated. The array
137501 ** of interior nodes that are parents of the leaf nodes start at block
137502 ** (start_block + (1 + end_block - start_block) / 16). And so on.
137503 **
137504 ** In the actual code below, the value "16" is replaced with the 
137505 ** pre-processor macro FTS_MAX_APPENDABLE_HEIGHT.
137506 */
137507 static int fts3IncrmergeWriter( 
137508   Fts3Table *p,                   /* Fts3 table handle */
137509   sqlite3_int64 iAbsLevel,        /* Absolute level of input segments */
137510   int iIdx,                       /* Index of new output segment */
137511   Fts3MultiSegReader *pCsr,       /* Cursor that data will be read from */
137512   IncrmergeWriter *pWriter        /* Populate this object */
137513 ){
137514   int rc;                         /* Return Code */
137515   int i;                          /* Iterator variable */
137516   int nLeafEst = 0;               /* Blocks allocated for leaf nodes */
137517   sqlite3_stmt *pLeafEst = 0;     /* SQL used to determine nLeafEst */
137518   sqlite3_stmt *pFirstBlock = 0;  /* SQL used to determine first block */
137519 
137520   /* Calculate nLeafEst. */
137521   rc = fts3SqlStmt(p, SQL_MAX_LEAF_NODE_ESTIMATE, &pLeafEst, 0);
137522   if( rc==SQLITE_OK ){
137523     sqlite3_bind_int64(pLeafEst, 1, iAbsLevel);
137524     sqlite3_bind_int64(pLeafEst, 2, pCsr->nSegment);
137525     if( SQLITE_ROW==sqlite3_step(pLeafEst) ){
137526       nLeafEst = sqlite3_column_int(pLeafEst, 0);
137527     }
137528     rc = sqlite3_reset(pLeafEst);
137529   }
137530   if( rc!=SQLITE_OK ) return rc;
137531 
137532   /* Calculate the first block to use in the output segment */
137533   rc = fts3SqlStmt(p, SQL_NEXT_SEGMENTS_ID, &pFirstBlock, 0);
137534   if( rc==SQLITE_OK ){
137535     if( SQLITE_ROW==sqlite3_step(pFirstBlock) ){
137536       pWriter->iStart = sqlite3_column_int64(pFirstBlock, 0);
137537       pWriter->iEnd = pWriter->iStart - 1;
137538       pWriter->iEnd += nLeafEst * FTS_MAX_APPENDABLE_HEIGHT;
137539     }
137540     rc = sqlite3_reset(pFirstBlock);
137541   }
137542   if( rc!=SQLITE_OK ) return rc;
137543 
137544   /* Insert the marker in the %_segments table to make sure nobody tries
137545   ** to steal the space just allocated. This is also used to identify 
137546   ** appendable segments.  */
137547   rc = fts3WriteSegment(p, pWriter->iEnd, 0, 0);
137548   if( rc!=SQLITE_OK ) return rc;
137549 
137550   pWriter->iAbsLevel = iAbsLevel;
137551   pWriter->nLeafEst = nLeafEst;
137552   pWriter->iIdx = iIdx;
137553 
137554   /* Set up the array of NodeWriter objects */
137555   for(i=0; i<FTS_MAX_APPENDABLE_HEIGHT; i++){
137556     pWriter->aNodeWriter[i].iBlock = pWriter->iStart + i*pWriter->nLeafEst;
137557   }
137558   return SQLITE_OK;
137559 }
137560 
137561 /*
137562 ** Remove an entry from the %_segdir table. This involves running the 
137563 ** following two statements:
137564 **
137565 **   DELETE FROM %_segdir WHERE level = :iAbsLevel AND idx = :iIdx
137566 **   UPDATE %_segdir SET idx = idx - 1 WHERE level = :iAbsLevel AND idx > :iIdx
137567 **
137568 ** The DELETE statement removes the specific %_segdir level. The UPDATE 
137569 ** statement ensures that the remaining segments have contiguously allocated
137570 ** idx values.
137571 */
137572 static int fts3RemoveSegdirEntry(
137573   Fts3Table *p,                   /* FTS3 table handle */
137574   sqlite3_int64 iAbsLevel,        /* Absolute level to delete from */
137575   int iIdx                        /* Index of %_segdir entry to delete */
137576 ){
137577   int rc;                         /* Return code */
137578   sqlite3_stmt *pDelete = 0;      /* DELETE statement */
137579 
137580   rc = fts3SqlStmt(p, SQL_DELETE_SEGDIR_ENTRY, &pDelete, 0);
137581   if( rc==SQLITE_OK ){
137582     sqlite3_bind_int64(pDelete, 1, iAbsLevel);
137583     sqlite3_bind_int(pDelete, 2, iIdx);
137584     sqlite3_step(pDelete);
137585     rc = sqlite3_reset(pDelete);
137586   }
137587 
137588   return rc;
137589 }
137590 
137591 /*
137592 ** One or more segments have just been removed from absolute level iAbsLevel.
137593 ** Update the 'idx' values of the remaining segments in the level so that
137594 ** the idx values are a contiguous sequence starting from 0.
137595 */
137596 static int fts3RepackSegdirLevel(
137597   Fts3Table *p,                   /* FTS3 table handle */
137598   sqlite3_int64 iAbsLevel         /* Absolute level to repack */
137599 ){
137600   int rc;                         /* Return code */
137601   int *aIdx = 0;                  /* Array of remaining idx values */
137602   int nIdx = 0;                   /* Valid entries in aIdx[] */
137603   int nAlloc = 0;                 /* Allocated size of aIdx[] */
137604   int i;                          /* Iterator variable */
137605   sqlite3_stmt *pSelect = 0;      /* Select statement to read idx values */
137606   sqlite3_stmt *pUpdate = 0;      /* Update statement to modify idx values */
137607 
137608   rc = fts3SqlStmt(p, SQL_SELECT_INDEXES, &pSelect, 0);
137609   if( rc==SQLITE_OK ){
137610     int rc2;
137611     sqlite3_bind_int64(pSelect, 1, iAbsLevel);
137612     while( SQLITE_ROW==sqlite3_step(pSelect) ){
137613       if( nIdx>=nAlloc ){
137614         int *aNew;
137615         nAlloc += 16;
137616         aNew = sqlite3_realloc(aIdx, nAlloc*sizeof(int));
137617         if( !aNew ){
137618           rc = SQLITE_NOMEM;
137619           break;
137620         }
137621         aIdx = aNew;
137622       }
137623       aIdx[nIdx++] = sqlite3_column_int(pSelect, 0);
137624     }
137625     rc2 = sqlite3_reset(pSelect);
137626     if( rc==SQLITE_OK ) rc = rc2;
137627   }
137628 
137629   if( rc==SQLITE_OK ){
137630     rc = fts3SqlStmt(p, SQL_SHIFT_SEGDIR_ENTRY, &pUpdate, 0);
137631   }
137632   if( rc==SQLITE_OK ){
137633     sqlite3_bind_int64(pUpdate, 2, iAbsLevel);
137634   }
137635 
137636   assert( p->bIgnoreSavepoint==0 );
137637   p->bIgnoreSavepoint = 1;
137638   for(i=0; rc==SQLITE_OK && i<nIdx; i++){
137639     if( aIdx[i]!=i ){
137640       sqlite3_bind_int(pUpdate, 3, aIdx[i]);
137641       sqlite3_bind_int(pUpdate, 1, i);
137642       sqlite3_step(pUpdate);
137643       rc = sqlite3_reset(pUpdate);
137644     }
137645   }
137646   p->bIgnoreSavepoint = 0;
137647 
137648   sqlite3_free(aIdx);
137649   return rc;
137650 }
137651 
137652 static void fts3StartNode(Blob *pNode, int iHeight, sqlite3_int64 iChild){
137653   pNode->a[0] = (char)iHeight;
137654   if( iChild ){
137655     assert( pNode->nAlloc>=1+sqlite3Fts3VarintLen(iChild) );
137656     pNode->n = 1 + sqlite3Fts3PutVarint(&pNode->a[1], iChild);
137657   }else{
137658     assert( pNode->nAlloc>=1 );
137659     pNode->n = 1;
137660   }
137661 }
137662 
137663 /*
137664 ** The first two arguments are a pointer to and the size of a segment b-tree
137665 ** node. The node may be a leaf or an internal node.
137666 **
137667 ** This function creates a new node image in blob object *pNew by copying
137668 ** all terms that are greater than or equal to zTerm/nTerm (for leaf nodes)
137669 ** or greater than zTerm/nTerm (for internal nodes) from aNode/nNode.
137670 */
137671 static int fts3TruncateNode(
137672   const char *aNode,              /* Current node image */
137673   int nNode,                      /* Size of aNode in bytes */
137674   Blob *pNew,                     /* OUT: Write new node image here */
137675   const char *zTerm,              /* Omit all terms smaller than this */
137676   int nTerm,                      /* Size of zTerm in bytes */
137677   sqlite3_int64 *piBlock          /* OUT: Block number in next layer down */
137678 ){
137679   NodeReader reader;              /* Reader object */
137680   Blob prev = {0, 0, 0};          /* Previous term written to new node */
137681   int rc = SQLITE_OK;             /* Return code */
137682   int bLeaf = aNode[0]=='\0';     /* True for a leaf node */
137683 
137684   /* Allocate required output space */
137685   blobGrowBuffer(pNew, nNode, &rc);
137686   if( rc!=SQLITE_OK ) return rc;
137687   pNew->n = 0;
137688 
137689   /* Populate new node buffer */
137690   for(rc = nodeReaderInit(&reader, aNode, nNode); 
137691       rc==SQLITE_OK && reader.aNode; 
137692       rc = nodeReaderNext(&reader)
137693   ){
137694     if( pNew->n==0 ){
137695       int res = fts3TermCmp(reader.term.a, reader.term.n, zTerm, nTerm);
137696       if( res<0 || (bLeaf==0 && res==0) ) continue;
137697       fts3StartNode(pNew, (int)aNode[0], reader.iChild);
137698       *piBlock = reader.iChild;
137699     }
137700     rc = fts3AppendToNode(
137701         pNew, &prev, reader.term.a, reader.term.n,
137702         reader.aDoclist, reader.nDoclist
137703     );
137704     if( rc!=SQLITE_OK ) break;
137705   }
137706   if( pNew->n==0 ){
137707     fts3StartNode(pNew, (int)aNode[0], reader.iChild);
137708     *piBlock = reader.iChild;
137709   }
137710   assert( pNew->n<=pNew->nAlloc );
137711 
137712   nodeReaderRelease(&reader);
137713   sqlite3_free(prev.a);
137714   return rc;
137715 }
137716 
137717 /*
137718 ** Remove all terms smaller than zTerm/nTerm from segment iIdx in absolute 
137719 ** level iAbsLevel. This may involve deleting entries from the %_segments
137720 ** table, and modifying existing entries in both the %_segments and %_segdir
137721 ** tables.
137722 **
137723 ** SQLITE_OK is returned if the segment is updated successfully. Or an
137724 ** SQLite error code otherwise.
137725 */
137726 static int fts3TruncateSegment(
137727   Fts3Table *p,                   /* FTS3 table handle */
137728   sqlite3_int64 iAbsLevel,        /* Absolute level of segment to modify */
137729   int iIdx,                       /* Index within level of segment to modify */
137730   const char *zTerm,              /* Remove terms smaller than this */
137731   int nTerm                      /* Number of bytes in buffer zTerm */
137732 ){
137733   int rc = SQLITE_OK;             /* Return code */
137734   Blob root = {0,0,0};            /* New root page image */
137735   Blob block = {0,0,0};           /* Buffer used for any other block */
137736   sqlite3_int64 iBlock = 0;       /* Block id */
137737   sqlite3_int64 iNewStart = 0;    /* New value for iStartBlock */
137738   sqlite3_int64 iOldStart = 0;    /* Old value for iStartBlock */
137739   sqlite3_stmt *pFetch = 0;       /* Statement used to fetch segdir */
137740 
137741   rc = fts3SqlStmt(p, SQL_SELECT_SEGDIR, &pFetch, 0);
137742   if( rc==SQLITE_OK ){
137743     int rc2;                      /* sqlite3_reset() return code */
137744     sqlite3_bind_int64(pFetch, 1, iAbsLevel);
137745     sqlite3_bind_int(pFetch, 2, iIdx);
137746     if( SQLITE_ROW==sqlite3_step(pFetch) ){
137747       const char *aRoot = sqlite3_column_blob(pFetch, 4);
137748       int nRoot = sqlite3_column_bytes(pFetch, 4);
137749       iOldStart = sqlite3_column_int64(pFetch, 1);
137750       rc = fts3TruncateNode(aRoot, nRoot, &root, zTerm, nTerm, &iBlock);
137751     }
137752     rc2 = sqlite3_reset(pFetch);
137753     if( rc==SQLITE_OK ) rc = rc2;
137754   }
137755 
137756   while( rc==SQLITE_OK && iBlock ){
137757     char *aBlock = 0;
137758     int nBlock = 0;
137759     iNewStart = iBlock;
137760 
137761     rc = sqlite3Fts3ReadBlock(p, iBlock, &aBlock, &nBlock, 0);
137762     if( rc==SQLITE_OK ){
137763       rc = fts3TruncateNode(aBlock, nBlock, &block, zTerm, nTerm, &iBlock);
137764     }
137765     if( rc==SQLITE_OK ){
137766       rc = fts3WriteSegment(p, iNewStart, block.a, block.n);
137767     }
137768     sqlite3_free(aBlock);
137769   }
137770 
137771   /* Variable iNewStart now contains the first valid leaf node. */
137772   if( rc==SQLITE_OK && iNewStart ){
137773     sqlite3_stmt *pDel = 0;
137774     rc = fts3SqlStmt(p, SQL_DELETE_SEGMENTS_RANGE, &pDel, 0);
137775     if( rc==SQLITE_OK ){
137776       sqlite3_bind_int64(pDel, 1, iOldStart);
137777       sqlite3_bind_int64(pDel, 2, iNewStart-1);
137778       sqlite3_step(pDel);
137779       rc = sqlite3_reset(pDel);
137780     }
137781   }
137782 
137783   if( rc==SQLITE_OK ){
137784     sqlite3_stmt *pChomp = 0;
137785     rc = fts3SqlStmt(p, SQL_CHOMP_SEGDIR, &pChomp, 0);
137786     if( rc==SQLITE_OK ){
137787       sqlite3_bind_int64(pChomp, 1, iNewStart);
137788       sqlite3_bind_blob(pChomp, 2, root.a, root.n, SQLITE_STATIC);
137789       sqlite3_bind_int64(pChomp, 3, iAbsLevel);
137790       sqlite3_bind_int(pChomp, 4, iIdx);
137791       sqlite3_step(pChomp);
137792       rc = sqlite3_reset(pChomp);
137793     }
137794   }
137795 
137796   sqlite3_free(root.a);
137797   sqlite3_free(block.a);
137798   return rc;
137799 }
137800 
137801 /*
137802 ** This function is called after an incrmental-merge operation has run to
137803 ** merge (or partially merge) two or more segments from absolute level
137804 ** iAbsLevel.
137805 **
137806 ** Each input segment is either removed from the db completely (if all of
137807 ** its data was copied to the output segment by the incrmerge operation)
137808 ** or modified in place so that it no longer contains those entries that
137809 ** have been duplicated in the output segment.
137810 */
137811 static int fts3IncrmergeChomp(
137812   Fts3Table *p,                   /* FTS table handle */
137813   sqlite3_int64 iAbsLevel,        /* Absolute level containing segments */
137814   Fts3MultiSegReader *pCsr,       /* Chomp all segments opened by this cursor */
137815   int *pnRem                      /* Number of segments not deleted */
137816 ){
137817   int i;
137818   int nRem = 0;
137819   int rc = SQLITE_OK;
137820 
137821   for(i=pCsr->nSegment-1; i>=0 && rc==SQLITE_OK; i--){
137822     Fts3SegReader *pSeg = 0;
137823     int j;
137824 
137825     /* Find the Fts3SegReader object with Fts3SegReader.iIdx==i. It is hiding
137826     ** somewhere in the pCsr->apSegment[] array.  */
137827     for(j=0; ALWAYS(j<pCsr->nSegment); j++){
137828       pSeg = pCsr->apSegment[j];
137829       if( pSeg->iIdx==i ) break;
137830     }
137831     assert( j<pCsr->nSegment && pSeg->iIdx==i );
137832 
137833     if( pSeg->aNode==0 ){
137834       /* Seg-reader is at EOF. Remove the entire input segment. */
137835       rc = fts3DeleteSegment(p, pSeg);
137836       if( rc==SQLITE_OK ){
137837         rc = fts3RemoveSegdirEntry(p, iAbsLevel, pSeg->iIdx);
137838       }
137839       *pnRem = 0;
137840     }else{
137841       /* The incremental merge did not copy all the data from this 
137842       ** segment to the upper level. The segment is modified in place
137843       ** so that it contains no keys smaller than zTerm/nTerm. */ 
137844       const char *zTerm = pSeg->zTerm;
137845       int nTerm = pSeg->nTerm;
137846       rc = fts3TruncateSegment(p, iAbsLevel, pSeg->iIdx, zTerm, nTerm);
137847       nRem++;
137848     }
137849   }
137850 
137851   if( rc==SQLITE_OK && nRem!=pCsr->nSegment ){
137852     rc = fts3RepackSegdirLevel(p, iAbsLevel);
137853   }
137854 
137855   *pnRem = nRem;
137856   return rc;
137857 }
137858 
137859 /*
137860 ** Store an incr-merge hint in the database.
137861 */
137862 static int fts3IncrmergeHintStore(Fts3Table *p, Blob *pHint){
137863   sqlite3_stmt *pReplace = 0;
137864   int rc;                         /* Return code */
137865 
137866   rc = fts3SqlStmt(p, SQL_REPLACE_STAT, &pReplace, 0);
137867   if( rc==SQLITE_OK ){
137868     sqlite3_bind_int(pReplace, 1, FTS_STAT_INCRMERGEHINT);
137869     sqlite3_bind_blob(pReplace, 2, pHint->a, pHint->n, SQLITE_STATIC);
137870     sqlite3_step(pReplace);
137871     rc = sqlite3_reset(pReplace);
137872   }
137873 
137874   return rc;
137875 }
137876 
137877 /*
137878 ** Load an incr-merge hint from the database. The incr-merge hint, if one 
137879 ** exists, is stored in the rowid==1 row of the %_stat table.
137880 **
137881 ** If successful, populate blob *pHint with the value read from the %_stat
137882 ** table and return SQLITE_OK. Otherwise, if an error occurs, return an
137883 ** SQLite error code.
137884 */
137885 static int fts3IncrmergeHintLoad(Fts3Table *p, Blob *pHint){
137886   sqlite3_stmt *pSelect = 0;
137887   int rc;
137888 
137889   pHint->n = 0;
137890   rc = fts3SqlStmt(p, SQL_SELECT_STAT, &pSelect, 0);
137891   if( rc==SQLITE_OK ){
137892     int rc2;
137893     sqlite3_bind_int(pSelect, 1, FTS_STAT_INCRMERGEHINT);
137894     if( SQLITE_ROW==sqlite3_step(pSelect) ){
137895       const char *aHint = sqlite3_column_blob(pSelect, 0);
137896       int nHint = sqlite3_column_bytes(pSelect, 0);
137897       if( aHint ){
137898         blobGrowBuffer(pHint, nHint, &rc);
137899         if( rc==SQLITE_OK ){
137900           memcpy(pHint->a, aHint, nHint);
137901           pHint->n = nHint;
137902         }
137903       }
137904     }
137905     rc2 = sqlite3_reset(pSelect);
137906     if( rc==SQLITE_OK ) rc = rc2;
137907   }
137908 
137909   return rc;
137910 }
137911 
137912 /*
137913 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
137914 ** Otherwise, append an entry to the hint stored in blob *pHint. Each entry
137915 ** consists of two varints, the absolute level number of the input segments 
137916 ** and the number of input segments.
137917 **
137918 ** If successful, leave *pRc set to SQLITE_OK and return. If an error occurs,
137919 ** set *pRc to an SQLite error code before returning.
137920 */
137921 static void fts3IncrmergeHintPush(
137922   Blob *pHint,                    /* Hint blob to append to */
137923   i64 iAbsLevel,                  /* First varint to store in hint */
137924   int nInput,                     /* Second varint to store in hint */
137925   int *pRc                        /* IN/OUT: Error code */
137926 ){
137927   blobGrowBuffer(pHint, pHint->n + 2*FTS3_VARINT_MAX, pRc);
137928   if( *pRc==SQLITE_OK ){
137929     pHint->n += sqlite3Fts3PutVarint(&pHint->a[pHint->n], iAbsLevel);
137930     pHint->n += sqlite3Fts3PutVarint(&pHint->a[pHint->n], (i64)nInput);
137931   }
137932 }
137933 
137934 /*
137935 ** Read the last entry (most recently pushed) from the hint blob *pHint
137936 ** and then remove the entry. Write the two values read to *piAbsLevel and 
137937 ** *pnInput before returning.
137938 **
137939 ** If no error occurs, return SQLITE_OK. If the hint blob in *pHint does
137940 ** not contain at least two valid varints, return SQLITE_CORRUPT_VTAB.
137941 */
137942 static int fts3IncrmergeHintPop(Blob *pHint, i64 *piAbsLevel, int *pnInput){
137943   const int nHint = pHint->n;
137944   int i;
137945 
137946   i = pHint->n-2;
137947   while( i>0 && (pHint->a[i-1] & 0x80) ) i--;
137948   while( i>0 && (pHint->a[i-1] & 0x80) ) i--;
137949 
137950   pHint->n = i;
137951   i += sqlite3Fts3GetVarint(&pHint->a[i], piAbsLevel);
137952   i += fts3GetVarint32(&pHint->a[i], pnInput);
137953   if( i!=nHint ) return SQLITE_CORRUPT_VTAB;
137954 
137955   return SQLITE_OK;
137956 }
137957 
137958 
137959 /*
137960 ** Attempt an incremental merge that writes nMerge leaf blocks.
137961 **
137962 ** Incremental merges happen nMin segments at a time. The two
137963 ** segments to be merged are the nMin oldest segments (the ones with
137964 ** the smallest indexes) in the highest level that contains at least
137965 ** nMin segments. Multiple merges might occur in an attempt to write the 
137966 ** quota of nMerge leaf blocks.
137967 */
137968 SQLITE_PRIVATE int sqlite3Fts3Incrmerge(Fts3Table *p, int nMerge, int nMin){
137969   int rc;                         /* Return code */
137970   int nRem = nMerge;              /* Number of leaf pages yet to  be written */
137971   Fts3MultiSegReader *pCsr;       /* Cursor used to read input data */
137972   Fts3SegFilter *pFilter;         /* Filter used with cursor pCsr */
137973   IncrmergeWriter *pWriter;       /* Writer object */
137974   int nSeg = 0;                   /* Number of input segments */
137975   sqlite3_int64 iAbsLevel = 0;    /* Absolute level number to work on */
137976   Blob hint = {0, 0, 0};          /* Hint read from %_stat table */
137977   int bDirtyHint = 0;             /* True if blob 'hint' has been modified */
137978 
137979   /* Allocate space for the cursor, filter and writer objects */
137980   const int nAlloc = sizeof(*pCsr) + sizeof(*pFilter) + sizeof(*pWriter);
137981   pWriter = (IncrmergeWriter *)sqlite3_malloc(nAlloc);
137982   if( !pWriter ) return SQLITE_NOMEM;
137983   pFilter = (Fts3SegFilter *)&pWriter[1];
137984   pCsr = (Fts3MultiSegReader *)&pFilter[1];
137985 
137986   rc = fts3IncrmergeHintLoad(p, &hint);
137987   while( rc==SQLITE_OK && nRem>0 ){
137988     const i64 nMod = FTS3_SEGDIR_MAXLEVEL * p->nIndex;
137989     sqlite3_stmt *pFindLevel = 0; /* SQL used to determine iAbsLevel */
137990     int bUseHint = 0;             /* True if attempting to append */
137991 
137992     /* Search the %_segdir table for the absolute level with the smallest
137993     ** relative level number that contains at least nMin segments, if any.
137994     ** If one is found, set iAbsLevel to the absolute level number and
137995     ** nSeg to nMin. If no level with at least nMin segments can be found, 
137996     ** set nSeg to -1.
137997     */
137998     rc = fts3SqlStmt(p, SQL_FIND_MERGE_LEVEL, &pFindLevel, 0);
137999     sqlite3_bind_int(pFindLevel, 1, nMin);
138000     if( sqlite3_step(pFindLevel)==SQLITE_ROW ){
138001       iAbsLevel = sqlite3_column_int64(pFindLevel, 0);
138002       nSeg = nMin;
138003     }else{
138004       nSeg = -1;
138005     }
138006     rc = sqlite3_reset(pFindLevel);
138007 
138008     /* If the hint read from the %_stat table is not empty, check if the
138009     ** last entry in it specifies a relative level smaller than or equal
138010     ** to the level identified by the block above (if any). If so, this 
138011     ** iteration of the loop will work on merging at the hinted level.
138012     */
138013     if( rc==SQLITE_OK && hint.n ){
138014       int nHint = hint.n;
138015       sqlite3_int64 iHintAbsLevel = 0;      /* Hint level */
138016       int nHintSeg = 0;                     /* Hint number of segments */
138017 
138018       rc = fts3IncrmergeHintPop(&hint, &iHintAbsLevel, &nHintSeg);
138019       if( nSeg<0 || (iAbsLevel % nMod) >= (iHintAbsLevel % nMod) ){
138020         iAbsLevel = iHintAbsLevel;
138021         nSeg = nHintSeg;
138022         bUseHint = 1;
138023         bDirtyHint = 1;
138024       }else{
138025         /* This undoes the effect of the HintPop() above - so that no entry
138026         ** is removed from the hint blob.  */
138027         hint.n = nHint;
138028       }
138029     }
138030 
138031     /* If nSeg is less that zero, then there is no level with at least
138032     ** nMin segments and no hint in the %_stat table. No work to do.
138033     ** Exit early in this case.  */
138034     if( nSeg<0 ) break;
138035 
138036     /* Open a cursor to iterate through the contents of the oldest nSeg 
138037     ** indexes of absolute level iAbsLevel. If this cursor is opened using 
138038     ** the 'hint' parameters, it is possible that there are less than nSeg
138039     ** segments available in level iAbsLevel. In this case, no work is
138040     ** done on iAbsLevel - fall through to the next iteration of the loop 
138041     ** to start work on some other level.  */
138042     memset(pWriter, 0, nAlloc);
138043     pFilter->flags = FTS3_SEGMENT_REQUIRE_POS;
138044     if( rc==SQLITE_OK ){
138045       rc = fts3IncrmergeCsr(p, iAbsLevel, nSeg, pCsr);
138046     }
138047     if( SQLITE_OK==rc && pCsr->nSegment==nSeg
138048      && SQLITE_OK==(rc = sqlite3Fts3SegReaderStart(p, pCsr, pFilter))
138049      && SQLITE_ROW==(rc = sqlite3Fts3SegReaderStep(p, pCsr))
138050     ){
138051       int iIdx = 0;               /* Largest idx in level (iAbsLevel+1) */
138052       rc = fts3IncrmergeOutputIdx(p, iAbsLevel, &iIdx);
138053       if( rc==SQLITE_OK ){
138054         if( bUseHint && iIdx>0 ){
138055           const char *zKey = pCsr->zTerm;
138056           int nKey = pCsr->nTerm;
138057           rc = fts3IncrmergeLoad(p, iAbsLevel, iIdx-1, zKey, nKey, pWriter);
138058         }else{
138059           rc = fts3IncrmergeWriter(p, iAbsLevel, iIdx, pCsr, pWriter);
138060         }
138061       }
138062 
138063       if( rc==SQLITE_OK && pWriter->nLeafEst ){
138064         fts3LogMerge(nSeg, iAbsLevel);
138065         do {
138066           rc = fts3IncrmergeAppend(p, pWriter, pCsr);
138067           if( rc==SQLITE_OK ) rc = sqlite3Fts3SegReaderStep(p, pCsr);
138068           if( pWriter->nWork>=nRem && rc==SQLITE_ROW ) rc = SQLITE_OK;
138069         }while( rc==SQLITE_ROW );
138070 
138071         /* Update or delete the input segments */
138072         if( rc==SQLITE_OK ){
138073           nRem -= (1 + pWriter->nWork);
138074           rc = fts3IncrmergeChomp(p, iAbsLevel, pCsr, &nSeg);
138075           if( nSeg!=0 ){
138076             bDirtyHint = 1;
138077             fts3IncrmergeHintPush(&hint, iAbsLevel, nSeg, &rc);
138078           }
138079         }
138080       }
138081 
138082       fts3IncrmergeRelease(p, pWriter, &rc);
138083     }
138084 
138085     sqlite3Fts3SegReaderFinish(pCsr);
138086   }
138087 
138088   /* Write the hint values into the %_stat table for the next incr-merger */
138089   if( bDirtyHint && rc==SQLITE_OK ){
138090     rc = fts3IncrmergeHintStore(p, &hint);
138091   }
138092 
138093   sqlite3_free(pWriter);
138094   sqlite3_free(hint.a);
138095   return rc;
138096 }
138097 
138098 /*
138099 ** Convert the text beginning at *pz into an integer and return
138100 ** its value.  Advance *pz to point to the first character past
138101 ** the integer.
138102 */
138103 static int fts3Getint(const char **pz){
138104   const char *z = *pz;
138105   int i = 0;
138106   while( (*z)>='0' && (*z)<='9' ) i = 10*i + *(z++) - '0';
138107   *pz = z;
138108   return i;
138109 }
138110 
138111 /*
138112 ** Process statements of the form:
138113 **
138114 **    INSERT INTO table(table) VALUES('merge=A,B');
138115 **
138116 ** A and B are integers that decode to be the number of leaf pages
138117 ** written for the merge, and the minimum number of segments on a level
138118 ** before it will be selected for a merge, respectively.
138119 */
138120 static int fts3DoIncrmerge(
138121   Fts3Table *p,                   /* FTS3 table handle */
138122   const char *zParam              /* Nul-terminated string containing "A,B" */
138123 ){
138124   int rc;
138125   int nMin = (FTS3_MERGE_COUNT / 2);
138126   int nMerge = 0;
138127   const char *z = zParam;
138128 
138129   /* Read the first integer value */
138130   nMerge = fts3Getint(&z);
138131 
138132   /* If the first integer value is followed by a ',',  read the second
138133   ** integer value. */
138134   if( z[0]==',' && z[1]!='\0' ){
138135     z++;
138136     nMin = fts3Getint(&z);
138137   }
138138 
138139   if( z[0]!='\0' || nMin<2 ){
138140     rc = SQLITE_ERROR;
138141   }else{
138142     rc = SQLITE_OK;
138143     if( !p->bHasStat ){
138144       assert( p->bFts4==0 );
138145       sqlite3Fts3CreateStatTable(&rc, p);
138146     }
138147     if( rc==SQLITE_OK ){
138148       rc = sqlite3Fts3Incrmerge(p, nMerge, nMin);
138149     }
138150     sqlite3Fts3SegmentsClose(p);
138151   }
138152   return rc;
138153 }
138154 
138155 /*
138156 ** Process statements of the form:
138157 **
138158 **    INSERT INTO table(table) VALUES('automerge=X');
138159 **
138160 ** where X is an integer.  X==0 means to turn automerge off.  X!=0 means
138161 ** turn it on.  The setting is persistent.
138162 */
138163 static int fts3DoAutoincrmerge(
138164   Fts3Table *p,                   /* FTS3 table handle */
138165   const char *zParam              /* Nul-terminated string containing boolean */
138166 ){
138167   int rc = SQLITE_OK;
138168   sqlite3_stmt *pStmt = 0;
138169   p->bAutoincrmerge = fts3Getint(&zParam)!=0;
138170   if( !p->bHasStat ){
138171     assert( p->bFts4==0 );
138172     sqlite3Fts3CreateStatTable(&rc, p);
138173     if( rc ) return rc;
138174   }
138175   rc = fts3SqlStmt(p, SQL_REPLACE_STAT, &pStmt, 0);
138176   if( rc ) return rc;
138177   sqlite3_bind_int(pStmt, 1, FTS_STAT_AUTOINCRMERGE);
138178   sqlite3_bind_int(pStmt, 2, p->bAutoincrmerge);
138179   sqlite3_step(pStmt);
138180   rc = sqlite3_reset(pStmt);
138181   return rc;
138182 }
138183 
138184 /*
138185 ** Return a 64-bit checksum for the FTS index entry specified by the
138186 ** arguments to this function.
138187 */
138188 static u64 fts3ChecksumEntry(
138189   const char *zTerm,              /* Pointer to buffer containing term */
138190   int nTerm,                      /* Size of zTerm in bytes */
138191   int iLangid,                    /* Language id for current row */
138192   int iIndex,                     /* Index (0..Fts3Table.nIndex-1) */
138193   i64 iDocid,                     /* Docid for current row. */
138194   int iCol,                       /* Column number */
138195   int iPos                        /* Position */
138196 ){
138197   int i;
138198   u64 ret = (u64)iDocid;
138199 
138200   ret += (ret<<3) + iLangid;
138201   ret += (ret<<3) + iIndex;
138202   ret += (ret<<3) + iCol;
138203   ret += (ret<<3) + iPos;
138204   for(i=0; i<nTerm; i++) ret += (ret<<3) + zTerm[i];
138205 
138206   return ret;
138207 }
138208 
138209 /*
138210 ** Return a checksum of all entries in the FTS index that correspond to
138211 ** language id iLangid. The checksum is calculated by XORing the checksums
138212 ** of each individual entry (see fts3ChecksumEntry()) together.
138213 **
138214 ** If successful, the checksum value is returned and *pRc set to SQLITE_OK.
138215 ** Otherwise, if an error occurs, *pRc is set to an SQLite error code. The
138216 ** return value is undefined in this case.
138217 */
138218 static u64 fts3ChecksumIndex(
138219   Fts3Table *p,                   /* FTS3 table handle */
138220   int iLangid,                    /* Language id to return cksum for */
138221   int iIndex,                     /* Index to cksum (0..p->nIndex-1) */
138222   int *pRc                        /* OUT: Return code */
138223 ){
138224   Fts3SegFilter filter;
138225   Fts3MultiSegReader csr;
138226   int rc;
138227   u64 cksum = 0;
138228 
138229   assert( *pRc==SQLITE_OK );
138230 
138231   memset(&filter, 0, sizeof(filter));
138232   memset(&csr, 0, sizeof(csr));
138233   filter.flags =  FTS3_SEGMENT_REQUIRE_POS|FTS3_SEGMENT_IGNORE_EMPTY;
138234   filter.flags |= FTS3_SEGMENT_SCAN;
138235 
138236   rc = sqlite3Fts3SegReaderCursor(
138237       p, iLangid, iIndex, FTS3_SEGCURSOR_ALL, 0, 0, 0, 1,&csr
138238   );
138239   if( rc==SQLITE_OK ){
138240     rc = sqlite3Fts3SegReaderStart(p, &csr, &filter);
138241   }
138242 
138243   if( rc==SQLITE_OK ){
138244     while( SQLITE_ROW==(rc = sqlite3Fts3SegReaderStep(p, &csr)) ){
138245       char *pCsr = csr.aDoclist;
138246       char *pEnd = &pCsr[csr.nDoclist];
138247 
138248       i64 iDocid = 0;
138249       i64 iCol = 0;
138250       i64 iPos = 0;
138251 
138252       pCsr += sqlite3Fts3GetVarint(pCsr, &iDocid);
138253       while( pCsr<pEnd ){
138254         i64 iVal = 0;
138255         pCsr += sqlite3Fts3GetVarint(pCsr, &iVal);
138256         if( pCsr<pEnd ){
138257           if( iVal==0 || iVal==1 ){
138258             iCol = 0;
138259             iPos = 0;
138260             if( iVal ){
138261               pCsr += sqlite3Fts3GetVarint(pCsr, &iCol);
138262             }else{
138263               pCsr += sqlite3Fts3GetVarint(pCsr, &iVal);
138264               iDocid += iVal;
138265             }
138266           }else{
138267             iPos += (iVal - 2);
138268             cksum = cksum ^ fts3ChecksumEntry(
138269                 csr.zTerm, csr.nTerm, iLangid, iIndex, iDocid,
138270                 (int)iCol, (int)iPos
138271             );
138272           }
138273         }
138274       }
138275     }
138276   }
138277   sqlite3Fts3SegReaderFinish(&csr);
138278 
138279   *pRc = rc;
138280   return cksum;
138281 }
138282 
138283 /*
138284 ** Check if the contents of the FTS index match the current contents of the
138285 ** content table. If no error occurs and the contents do match, set *pbOk
138286 ** to true and return SQLITE_OK. Or if the contents do not match, set *pbOk
138287 ** to false before returning.
138288 **
138289 ** If an error occurs (e.g. an OOM or IO error), return an SQLite error 
138290 ** code. The final value of *pbOk is undefined in this case.
138291 */
138292 static int fts3IntegrityCheck(Fts3Table *p, int *pbOk){
138293   int rc = SQLITE_OK;             /* Return code */
138294   u64 cksum1 = 0;                 /* Checksum based on FTS index contents */
138295   u64 cksum2 = 0;                 /* Checksum based on %_content contents */
138296   sqlite3_stmt *pAllLangid = 0;   /* Statement to return all language-ids */
138297 
138298   /* This block calculates the checksum according to the FTS index. */
138299   rc = fts3SqlStmt(p, SQL_SELECT_ALL_LANGID, &pAllLangid, 0);
138300   if( rc==SQLITE_OK ){
138301     int rc2;
138302     sqlite3_bind_int(pAllLangid, 1, p->nIndex);
138303     while( rc==SQLITE_OK && sqlite3_step(pAllLangid)==SQLITE_ROW ){
138304       int iLangid = sqlite3_column_int(pAllLangid, 0);
138305       int i;
138306       for(i=0; i<p->nIndex; i++){
138307         cksum1 = cksum1 ^ fts3ChecksumIndex(p, iLangid, i, &rc);
138308       }
138309     }
138310     rc2 = sqlite3_reset(pAllLangid);
138311     if( rc==SQLITE_OK ) rc = rc2;
138312   }
138313 
138314   /* This block calculates the checksum according to the %_content table */
138315   rc = fts3SqlStmt(p, SQL_SELECT_ALL_LANGID, &pAllLangid, 0);
138316   if( rc==SQLITE_OK ){
138317     sqlite3_tokenizer_module const *pModule = p->pTokenizer->pModule;
138318     sqlite3_stmt *pStmt = 0;
138319     char *zSql;
138320    
138321     zSql = sqlite3_mprintf("SELECT %s" , p->zReadExprlist);
138322     if( !zSql ){
138323       rc = SQLITE_NOMEM;
138324     }else{
138325       rc = sqlite3_prepare_v2(p->db, zSql, -1, &pStmt, 0);
138326       sqlite3_free(zSql);
138327     }
138328 
138329     while( rc==SQLITE_OK && SQLITE_ROW==sqlite3_step(pStmt) ){
138330       i64 iDocid = sqlite3_column_int64(pStmt, 0);
138331       int iLang = langidFromSelect(p, pStmt);
138332       int iCol;
138333 
138334       for(iCol=0; rc==SQLITE_OK && iCol<p->nColumn; iCol++){
138335         const char *zText = (const char *)sqlite3_column_text(pStmt, iCol+1);
138336         int nText = sqlite3_column_bytes(pStmt, iCol+1);
138337         sqlite3_tokenizer_cursor *pT = 0;
138338 
138339         rc = sqlite3Fts3OpenTokenizer(p->pTokenizer, iLang, zText, nText, &pT);
138340         while( rc==SQLITE_OK ){
138341           char const *zToken;       /* Buffer containing token */
138342           int nToken = 0;           /* Number of bytes in token */
138343           int iDum1 = 0, iDum2 = 0; /* Dummy variables */
138344           int iPos = 0;             /* Position of token in zText */
138345 
138346           rc = pModule->xNext(pT, &zToken, &nToken, &iDum1, &iDum2, &iPos);
138347           if( rc==SQLITE_OK ){
138348             int i;
138349             cksum2 = cksum2 ^ fts3ChecksumEntry(
138350                 zToken, nToken, iLang, 0, iDocid, iCol, iPos
138351             );
138352             for(i=1; i<p->nIndex; i++){
138353               if( p->aIndex[i].nPrefix<=nToken ){
138354                 cksum2 = cksum2 ^ fts3ChecksumEntry(
138355                   zToken, p->aIndex[i].nPrefix, iLang, i, iDocid, iCol, iPos
138356                 );
138357               }
138358             }
138359           }
138360         }
138361         if( pT ) pModule->xClose(pT);
138362         if( rc==SQLITE_DONE ) rc = SQLITE_OK;
138363       }
138364     }
138365 
138366     sqlite3_finalize(pStmt);
138367   }
138368 
138369   *pbOk = (cksum1==cksum2);
138370   return rc;
138371 }
138372 
138373 /*
138374 ** Run the integrity-check. If no error occurs and the current contents of
138375 ** the FTS index are correct, return SQLITE_OK. Or, if the contents of the
138376 ** FTS index are incorrect, return SQLITE_CORRUPT_VTAB.
138377 **
138378 ** Or, if an error (e.g. an OOM or IO error) occurs, return an SQLite 
138379 ** error code.
138380 **
138381 ** The integrity-check works as follows. For each token and indexed token
138382 ** prefix in the document set, a 64-bit checksum is calculated (by code
138383 ** in fts3ChecksumEntry()) based on the following:
138384 **
138385 **     + The index number (0 for the main index, 1 for the first prefix
138386 **       index etc.),
138387 **     + The token (or token prefix) text itself, 
138388 **     + The language-id of the row it appears in,
138389 **     + The docid of the row it appears in,
138390 **     + The column it appears in, and
138391 **     + The tokens position within that column.
138392 **
138393 ** The checksums for all entries in the index are XORed together to create
138394 ** a single checksum for the entire index.
138395 **
138396 ** The integrity-check code calculates the same checksum in two ways:
138397 **
138398 **     1. By scanning the contents of the FTS index, and 
138399 **     2. By scanning and tokenizing the content table.
138400 **
138401 ** If the two checksums are identical, the integrity-check is deemed to have
138402 ** passed.
138403 */
138404 static int fts3DoIntegrityCheck(
138405   Fts3Table *p                    /* FTS3 table handle */
138406 ){
138407   int rc;
138408   int bOk = 0;
138409   rc = fts3IntegrityCheck(p, &bOk);
138410   if( rc==SQLITE_OK && bOk==0 ) rc = SQLITE_CORRUPT_VTAB;
138411   return rc;
138412 }
138413 
138414 /*
138415 ** Handle a 'special' INSERT of the form:
138416 **
138417 **   "INSERT INTO tbl(tbl) VALUES(<expr>)"
138418 **
138419 ** Argument pVal contains the result of <expr>. Currently the only 
138420 ** meaningful value to insert is the text 'optimize'.
138421 */
138422 static int fts3SpecialInsert(Fts3Table *p, sqlite3_value *pVal){
138423   int rc;                         /* Return Code */
138424   const char *zVal = (const char *)sqlite3_value_text(pVal);
138425   int nVal = sqlite3_value_bytes(pVal);
138426 
138427   if( !zVal ){
138428     return SQLITE_NOMEM;
138429   }else if( nVal==8 && 0==sqlite3_strnicmp(zVal, "optimize", 8) ){
138430     rc = fts3DoOptimize(p, 0);
138431   }else if( nVal==7 && 0==sqlite3_strnicmp(zVal, "rebuild", 7) ){
138432     rc = fts3DoRebuild(p);
138433   }else if( nVal==15 && 0==sqlite3_strnicmp(zVal, "integrity-check", 15) ){
138434     rc = fts3DoIntegrityCheck(p);
138435   }else if( nVal>6 && 0==sqlite3_strnicmp(zVal, "merge=", 6) ){
138436     rc = fts3DoIncrmerge(p, &zVal[6]);
138437   }else if( nVal>10 && 0==sqlite3_strnicmp(zVal, "automerge=", 10) ){
138438     rc = fts3DoAutoincrmerge(p, &zVal[10]);
138439 #ifdef SQLITE_TEST
138440   }else if( nVal>9 && 0==sqlite3_strnicmp(zVal, "nodesize=", 9) ){
138441     p->nNodeSize = atoi(&zVal[9]);
138442     rc = SQLITE_OK;
138443   }else if( nVal>11 && 0==sqlite3_strnicmp(zVal, "maxpending=", 9) ){
138444     p->nMaxPendingData = atoi(&zVal[11]);
138445     rc = SQLITE_OK;
138446   }else if( nVal>21 && 0==sqlite3_strnicmp(zVal, "test-no-incr-doclist=", 21) ){
138447     p->bNoIncrDoclist = atoi(&zVal[21]);
138448     rc = SQLITE_OK;
138449 #endif
138450   }else{
138451     rc = SQLITE_ERROR;
138452   }
138453 
138454   return rc;
138455 }
138456 
138457 #ifndef SQLITE_DISABLE_FTS4_DEFERRED
138458 /*
138459 ** Delete all cached deferred doclists. Deferred doclists are cached
138460 ** (allocated) by the sqlite3Fts3CacheDeferredDoclists() function.
138461 */
138462 SQLITE_PRIVATE void sqlite3Fts3FreeDeferredDoclists(Fts3Cursor *pCsr){
138463   Fts3DeferredToken *pDef;
138464   for(pDef=pCsr->pDeferred; pDef; pDef=pDef->pNext){
138465     fts3PendingListDelete(pDef->pList);
138466     pDef->pList = 0;
138467   }
138468 }
138469 
138470 /*
138471 ** Free all entries in the pCsr->pDeffered list. Entries are added to 
138472 ** this list using sqlite3Fts3DeferToken().
138473 */
138474 SQLITE_PRIVATE void sqlite3Fts3FreeDeferredTokens(Fts3Cursor *pCsr){
138475   Fts3DeferredToken *pDef;
138476   Fts3DeferredToken *pNext;
138477   for(pDef=pCsr->pDeferred; pDef; pDef=pNext){
138478     pNext = pDef->pNext;
138479     fts3PendingListDelete(pDef->pList);
138480     sqlite3_free(pDef);
138481   }
138482   pCsr->pDeferred = 0;
138483 }
138484 
138485 /*
138486 ** Generate deferred-doclists for all tokens in the pCsr->pDeferred list
138487 ** based on the row that pCsr currently points to.
138488 **
138489 ** A deferred-doclist is like any other doclist with position information
138490 ** included, except that it only contains entries for a single row of the
138491 ** table, not for all rows.
138492 */
138493 SQLITE_PRIVATE int sqlite3Fts3CacheDeferredDoclists(Fts3Cursor *pCsr){
138494   int rc = SQLITE_OK;             /* Return code */
138495   if( pCsr->pDeferred ){
138496     int i;                        /* Used to iterate through table columns */
138497     sqlite3_int64 iDocid;         /* Docid of the row pCsr points to */
138498     Fts3DeferredToken *pDef;      /* Used to iterate through deferred tokens */
138499   
138500     Fts3Table *p = (Fts3Table *)pCsr->base.pVtab;
138501     sqlite3_tokenizer *pT = p->pTokenizer;
138502     sqlite3_tokenizer_module const *pModule = pT->pModule;
138503    
138504     assert( pCsr->isRequireSeek==0 );
138505     iDocid = sqlite3_column_int64(pCsr->pStmt, 0);
138506   
138507     for(i=0; i<p->nColumn && rc==SQLITE_OK; i++){
138508       if( p->abNotindexed[i]==0 ){
138509         const char *zText = (const char *)sqlite3_column_text(pCsr->pStmt, i+1);
138510         sqlite3_tokenizer_cursor *pTC = 0;
138511 
138512         rc = sqlite3Fts3OpenTokenizer(pT, pCsr->iLangid, zText, -1, &pTC);
138513         while( rc==SQLITE_OK ){
138514           char const *zToken;       /* Buffer containing token */
138515           int nToken = 0;           /* Number of bytes in token */
138516           int iDum1 = 0, iDum2 = 0; /* Dummy variables */
138517           int iPos = 0;             /* Position of token in zText */
138518 
138519           rc = pModule->xNext(pTC, &zToken, &nToken, &iDum1, &iDum2, &iPos);
138520           for(pDef=pCsr->pDeferred; pDef && rc==SQLITE_OK; pDef=pDef->pNext){
138521             Fts3PhraseToken *pPT = pDef->pToken;
138522             if( (pDef->iCol>=p->nColumn || pDef->iCol==i)
138523                 && (pPT->bFirst==0 || iPos==0)
138524                 && (pPT->n==nToken || (pPT->isPrefix && pPT->n<nToken))
138525                 && (0==memcmp(zToken, pPT->z, pPT->n))
138526               ){
138527               fts3PendingListAppend(&pDef->pList, iDocid, i, iPos, &rc);
138528             }
138529           }
138530         }
138531         if( pTC ) pModule->xClose(pTC);
138532         if( rc==SQLITE_DONE ) rc = SQLITE_OK;
138533       }
138534     }
138535 
138536     for(pDef=pCsr->pDeferred; pDef && rc==SQLITE_OK; pDef=pDef->pNext){
138537       if( pDef->pList ){
138538         rc = fts3PendingListAppendVarint(&pDef->pList, 0);
138539       }
138540     }
138541   }
138542 
138543   return rc;
138544 }
138545 
138546 SQLITE_PRIVATE int sqlite3Fts3DeferredTokenList(
138547   Fts3DeferredToken *p, 
138548   char **ppData, 
138549   int *pnData
138550 ){
138551   char *pRet;
138552   int nSkip;
138553   sqlite3_int64 dummy;
138554 
138555   *ppData = 0;
138556   *pnData = 0;
138557 
138558   if( p->pList==0 ){
138559     return SQLITE_OK;
138560   }
138561 
138562   pRet = (char *)sqlite3_malloc(p->pList->nData);
138563   if( !pRet ) return SQLITE_NOMEM;
138564 
138565   nSkip = sqlite3Fts3GetVarint(p->pList->aData, &dummy);
138566   *pnData = p->pList->nData - nSkip;
138567   *ppData = pRet;
138568   
138569   memcpy(pRet, &p->pList->aData[nSkip], *pnData);
138570   return SQLITE_OK;
138571 }
138572 
138573 /*
138574 ** Add an entry for token pToken to the pCsr->pDeferred list.
138575 */
138576 SQLITE_PRIVATE int sqlite3Fts3DeferToken(
138577   Fts3Cursor *pCsr,               /* Fts3 table cursor */
138578   Fts3PhraseToken *pToken,        /* Token to defer */
138579   int iCol                        /* Column that token must appear in (or -1) */
138580 ){
138581   Fts3DeferredToken *pDeferred;
138582   pDeferred = sqlite3_malloc(sizeof(*pDeferred));
138583   if( !pDeferred ){
138584     return SQLITE_NOMEM;
138585   }
138586   memset(pDeferred, 0, sizeof(*pDeferred));
138587   pDeferred->pToken = pToken;
138588   pDeferred->pNext = pCsr->pDeferred; 
138589   pDeferred->iCol = iCol;
138590   pCsr->pDeferred = pDeferred;
138591 
138592   assert( pToken->pDeferred==0 );
138593   pToken->pDeferred = pDeferred;
138594 
138595   return SQLITE_OK;
138596 }
138597 #endif
138598 
138599 /*
138600 ** SQLite value pRowid contains the rowid of a row that may or may not be
138601 ** present in the FTS3 table. If it is, delete it and adjust the contents
138602 ** of subsiduary data structures accordingly.
138603 */
138604 static int fts3DeleteByRowid(
138605   Fts3Table *p, 
138606   sqlite3_value *pRowid, 
138607   int *pnChng,                    /* IN/OUT: Decrement if row is deleted */
138608   u32 *aSzDel
138609 ){
138610   int rc = SQLITE_OK;             /* Return code */
138611   int bFound = 0;                 /* True if *pRowid really is in the table */
138612 
138613   fts3DeleteTerms(&rc, p, pRowid, aSzDel, &bFound);
138614   if( bFound && rc==SQLITE_OK ){
138615     int isEmpty = 0;              /* Deleting *pRowid leaves the table empty */
138616     rc = fts3IsEmpty(p, pRowid, &isEmpty);
138617     if( rc==SQLITE_OK ){
138618       if( isEmpty ){
138619         /* Deleting this row means the whole table is empty. In this case
138620         ** delete the contents of all three tables and throw away any
138621         ** data in the pendingTerms hash table.  */
138622         rc = fts3DeleteAll(p, 1);
138623         *pnChng = 0;
138624         memset(aSzDel, 0, sizeof(u32) * (p->nColumn+1) * 2);
138625       }else{
138626         *pnChng = *pnChng - 1;
138627         if( p->zContentTbl==0 ){
138628           fts3SqlExec(&rc, p, SQL_DELETE_CONTENT, &pRowid);
138629         }
138630         if( p->bHasDocsize ){
138631           fts3SqlExec(&rc, p, SQL_DELETE_DOCSIZE, &pRowid);
138632         }
138633       }
138634     }
138635   }
138636 
138637   return rc;
138638 }
138639 
138640 /*
138641 ** This function does the work for the xUpdate method of FTS3 virtual
138642 ** tables. The schema of the virtual table being:
138643 **
138644 **     CREATE TABLE <table name>( 
138645 **       <user columns>,
138646 **       <table name> HIDDEN, 
138647 **       docid HIDDEN, 
138648 **       <langid> HIDDEN
138649 **     );
138650 **
138651 ** 
138652 */
138653 SQLITE_PRIVATE int sqlite3Fts3UpdateMethod(
138654   sqlite3_vtab *pVtab,            /* FTS3 vtab object */
138655   int nArg,                       /* Size of argument array */
138656   sqlite3_value **apVal,          /* Array of arguments */
138657   sqlite_int64 *pRowid            /* OUT: The affected (or effected) rowid */
138658 ){
138659   Fts3Table *p = (Fts3Table *)pVtab;
138660   int rc = SQLITE_OK;             /* Return Code */
138661   int isRemove = 0;               /* True for an UPDATE or DELETE */
138662   u32 *aSzIns = 0;                /* Sizes of inserted documents */
138663   u32 *aSzDel = 0;                /* Sizes of deleted documents */
138664   int nChng = 0;                  /* Net change in number of documents */
138665   int bInsertDone = 0;
138666 
138667   assert( p->pSegments==0 );
138668   assert( 
138669       nArg==1                     /* DELETE operations */
138670    || nArg==(2 + p->nColumn + 3)  /* INSERT or UPDATE operations */
138671   );
138672 
138673   /* Check for a "special" INSERT operation. One of the form:
138674   **
138675   **   INSERT INTO xyz(xyz) VALUES('command');
138676   */
138677   if( nArg>1 
138678    && sqlite3_value_type(apVal[0])==SQLITE_NULL 
138679    && sqlite3_value_type(apVal[p->nColumn+2])!=SQLITE_NULL 
138680   ){
138681     rc = fts3SpecialInsert(p, apVal[p->nColumn+2]);
138682     goto update_out;
138683   }
138684 
138685   if( nArg>1 && sqlite3_value_int(apVal[2 + p->nColumn + 2])<0 ){
138686     rc = SQLITE_CONSTRAINT;
138687     goto update_out;
138688   }
138689 
138690   /* Allocate space to hold the change in document sizes */
138691   aSzDel = sqlite3_malloc( sizeof(aSzDel[0])*(p->nColumn+1)*2 );
138692   if( aSzDel==0 ){
138693     rc = SQLITE_NOMEM;
138694     goto update_out;
138695   }
138696   aSzIns = &aSzDel[p->nColumn+1];
138697   memset(aSzDel, 0, sizeof(aSzDel[0])*(p->nColumn+1)*2);
138698 
138699   rc = fts3Writelock(p);
138700   if( rc!=SQLITE_OK ) goto update_out;
138701 
138702   /* If this is an INSERT operation, or an UPDATE that modifies the rowid
138703   ** value, then this operation requires constraint handling.
138704   **
138705   ** If the on-conflict mode is REPLACE, this means that the existing row
138706   ** should be deleted from the database before inserting the new row. Or,
138707   ** if the on-conflict mode is other than REPLACE, then this method must
138708   ** detect the conflict and return SQLITE_CONSTRAINT before beginning to
138709   ** modify the database file.
138710   */
138711   if( nArg>1 && p->zContentTbl==0 ){
138712     /* Find the value object that holds the new rowid value. */
138713     sqlite3_value *pNewRowid = apVal[3+p->nColumn];
138714     if( sqlite3_value_type(pNewRowid)==SQLITE_NULL ){
138715       pNewRowid = apVal[1];
138716     }
138717 
138718     if( sqlite3_value_type(pNewRowid)!=SQLITE_NULL && ( 
138719         sqlite3_value_type(apVal[0])==SQLITE_NULL
138720      || sqlite3_value_int64(apVal[0])!=sqlite3_value_int64(pNewRowid)
138721     )){
138722       /* The new rowid is not NULL (in this case the rowid will be
138723       ** automatically assigned and there is no chance of a conflict), and 
138724       ** the statement is either an INSERT or an UPDATE that modifies the
138725       ** rowid column. So if the conflict mode is REPLACE, then delete any
138726       ** existing row with rowid=pNewRowid. 
138727       **
138728       ** Or, if the conflict mode is not REPLACE, insert the new record into 
138729       ** the %_content table. If we hit the duplicate rowid constraint (or any
138730       ** other error) while doing so, return immediately.
138731       **
138732       ** This branch may also run if pNewRowid contains a value that cannot
138733       ** be losslessly converted to an integer. In this case, the eventual 
138734       ** call to fts3InsertData() (either just below or further on in this
138735       ** function) will return SQLITE_MISMATCH. If fts3DeleteByRowid is 
138736       ** invoked, it will delete zero rows (since no row will have
138737       ** docid=$pNewRowid if $pNewRowid is not an integer value).
138738       */
138739       if( sqlite3_vtab_on_conflict(p->db)==SQLITE_REPLACE ){
138740         rc = fts3DeleteByRowid(p, pNewRowid, &nChng, aSzDel);
138741       }else{
138742         rc = fts3InsertData(p, apVal, pRowid);
138743         bInsertDone = 1;
138744       }
138745     }
138746   }
138747   if( rc!=SQLITE_OK ){
138748     goto update_out;
138749   }
138750 
138751   /* If this is a DELETE or UPDATE operation, remove the old record. */
138752   if( sqlite3_value_type(apVal[0])!=SQLITE_NULL ){
138753     assert( sqlite3_value_type(apVal[0])==SQLITE_INTEGER );
138754     rc = fts3DeleteByRowid(p, apVal[0], &nChng, aSzDel);
138755     isRemove = 1;
138756   }
138757   
138758   /* If this is an INSERT or UPDATE operation, insert the new record. */
138759   if( nArg>1 && rc==SQLITE_OK ){
138760     int iLangid = sqlite3_value_int(apVal[2 + p->nColumn + 2]);
138761     if( bInsertDone==0 ){
138762       rc = fts3InsertData(p, apVal, pRowid);
138763       if( rc==SQLITE_CONSTRAINT && p->zContentTbl==0 ){
138764         rc = FTS_CORRUPT_VTAB;
138765       }
138766     }
138767     if( rc==SQLITE_OK && (!isRemove || *pRowid!=p->iPrevDocid ) ){
138768       rc = fts3PendingTermsDocid(p, iLangid, *pRowid);
138769     }
138770     if( rc==SQLITE_OK ){
138771       assert( p->iPrevDocid==*pRowid );
138772       rc = fts3InsertTerms(p, iLangid, apVal, aSzIns);
138773     }
138774     if( p->bHasDocsize ){
138775       fts3InsertDocsize(&rc, p, aSzIns);
138776     }
138777     nChng++;
138778   }
138779 
138780   if( p->bFts4 ){
138781     fts3UpdateDocTotals(&rc, p, aSzIns, aSzDel, nChng);
138782   }
138783 
138784  update_out:
138785   sqlite3_free(aSzDel);
138786   sqlite3Fts3SegmentsClose(p);
138787   return rc;
138788 }
138789 
138790 /* 
138791 ** Flush any data in the pending-terms hash table to disk. If successful,
138792 ** merge all segments in the database (including the new segment, if 
138793 ** there was any data to flush) into a single segment. 
138794 */
138795 SQLITE_PRIVATE int sqlite3Fts3Optimize(Fts3Table *p){
138796   int rc;
138797   rc = sqlite3_exec(p->db, "SAVEPOINT fts3", 0, 0, 0);
138798   if( rc==SQLITE_OK ){
138799     rc = fts3DoOptimize(p, 1);
138800     if( rc==SQLITE_OK || rc==SQLITE_DONE ){
138801       int rc2 = sqlite3_exec(p->db, "RELEASE fts3", 0, 0, 0);
138802       if( rc2!=SQLITE_OK ) rc = rc2;
138803     }else{
138804       sqlite3_exec(p->db, "ROLLBACK TO fts3", 0, 0, 0);
138805       sqlite3_exec(p->db, "RELEASE fts3", 0, 0, 0);
138806     }
138807   }
138808   sqlite3Fts3SegmentsClose(p);
138809   return rc;
138810 }
138811 
138812 #endif
138813 
138814 /************** End of fts3_write.c ******************************************/
138815 /************** Begin file fts3_snippet.c ************************************/
138816 /*
138817 ** 2009 Oct 23
138818 **
138819 ** The author disclaims copyright to this source code.  In place of
138820 ** a legal notice, here is a blessing:
138821 **
138822 **    May you do good and not evil.
138823 **    May you find forgiveness for yourself and forgive others.
138824 **    May you share freely, never taking more than you give.
138825 **
138826 ******************************************************************************
138827 */
138828 
138829 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
138830 
138831 /* #include <string.h> */
138832 /* #include <assert.h> */
138833 
138834 /*
138835 ** Characters that may appear in the second argument to matchinfo().
138836 */
138837 #define FTS3_MATCHINFO_NPHRASE   'p'        /* 1 value */
138838 #define FTS3_MATCHINFO_NCOL      'c'        /* 1 value */
138839 #define FTS3_MATCHINFO_NDOC      'n'        /* 1 value */
138840 #define FTS3_MATCHINFO_AVGLENGTH 'a'        /* nCol values */
138841 #define FTS3_MATCHINFO_LENGTH    'l'        /* nCol values */
138842 #define FTS3_MATCHINFO_LCS       's'        /* nCol values */
138843 #define FTS3_MATCHINFO_HITS      'x'        /* 3*nCol*nPhrase values */
138844 
138845 /*
138846 ** The default value for the second argument to matchinfo(). 
138847 */
138848 #define FTS3_MATCHINFO_DEFAULT   "pcx"
138849 
138850 
138851 /*
138852 ** Used as an fts3ExprIterate() context when loading phrase doclists to
138853 ** Fts3Expr.aDoclist[]/nDoclist.
138854 */
138855 typedef struct LoadDoclistCtx LoadDoclistCtx;
138856 struct LoadDoclistCtx {
138857   Fts3Cursor *pCsr;               /* FTS3 Cursor */
138858   int nPhrase;                    /* Number of phrases seen so far */
138859   int nToken;                     /* Number of tokens seen so far */
138860 };
138861 
138862 /*
138863 ** The following types are used as part of the implementation of the 
138864 ** fts3BestSnippet() routine.
138865 */
138866 typedef struct SnippetIter SnippetIter;
138867 typedef struct SnippetPhrase SnippetPhrase;
138868 typedef struct SnippetFragment SnippetFragment;
138869 
138870 struct SnippetIter {
138871   Fts3Cursor *pCsr;               /* Cursor snippet is being generated from */
138872   int iCol;                       /* Extract snippet from this column */
138873   int nSnippet;                   /* Requested snippet length (in tokens) */
138874   int nPhrase;                    /* Number of phrases in query */
138875   SnippetPhrase *aPhrase;         /* Array of size nPhrase */
138876   int iCurrent;                   /* First token of current snippet */
138877 };
138878 
138879 struct SnippetPhrase {
138880   int nToken;                     /* Number of tokens in phrase */
138881   char *pList;                    /* Pointer to start of phrase position list */
138882   int iHead;                      /* Next value in position list */
138883   char *pHead;                    /* Position list data following iHead */
138884   int iTail;                      /* Next value in trailing position list */
138885   char *pTail;                    /* Position list data following iTail */
138886 };
138887 
138888 struct SnippetFragment {
138889   int iCol;                       /* Column snippet is extracted from */
138890   int iPos;                       /* Index of first token in snippet */
138891   u64 covered;                    /* Mask of query phrases covered */
138892   u64 hlmask;                     /* Mask of snippet terms to highlight */
138893 };
138894 
138895 /*
138896 ** This type is used as an fts3ExprIterate() context object while 
138897 ** accumulating the data returned by the matchinfo() function.
138898 */
138899 typedef struct MatchInfo MatchInfo;
138900 struct MatchInfo {
138901   Fts3Cursor *pCursor;            /* FTS3 Cursor */
138902   int nCol;                       /* Number of columns in table */
138903   int nPhrase;                    /* Number of matchable phrases in query */
138904   sqlite3_int64 nDoc;             /* Number of docs in database */
138905   u32 *aMatchinfo;                /* Pre-allocated buffer */
138906 };
138907 
138908 
138909 
138910 /*
138911 ** The snippet() and offsets() functions both return text values. An instance
138912 ** of the following structure is used to accumulate those values while the
138913 ** functions are running. See fts3StringAppend() for details.
138914 */
138915 typedef struct StrBuffer StrBuffer;
138916 struct StrBuffer {
138917   char *z;                        /* Pointer to buffer containing string */
138918   int n;                          /* Length of z in bytes (excl. nul-term) */
138919   int nAlloc;                     /* Allocated size of buffer z in bytes */
138920 };
138921 
138922 
138923 /*
138924 ** This function is used to help iterate through a position-list. A position
138925 ** list is a list of unique integers, sorted from smallest to largest. Each
138926 ** element of the list is represented by an FTS3 varint that takes the value
138927 ** of the difference between the current element and the previous one plus
138928 ** two. For example, to store the position-list:
138929 **
138930 **     4 9 113
138931 **
138932 ** the three varints:
138933 **
138934 **     6 7 106
138935 **
138936 ** are encoded.
138937 **
138938 ** When this function is called, *pp points to the start of an element of
138939 ** the list. *piPos contains the value of the previous entry in the list.
138940 ** After it returns, *piPos contains the value of the next element of the
138941 ** list and *pp is advanced to the following varint.
138942 */
138943 static void fts3GetDeltaPosition(char **pp, int *piPos){
138944   int iVal;
138945   *pp += fts3GetVarint32(*pp, &iVal);
138946   *piPos += (iVal-2);
138947 }
138948 
138949 /*
138950 ** Helper function for fts3ExprIterate() (see below).
138951 */
138952 static int fts3ExprIterate2(
138953   Fts3Expr *pExpr,                /* Expression to iterate phrases of */
138954   int *piPhrase,                  /* Pointer to phrase counter */
138955   int (*x)(Fts3Expr*,int,void*),  /* Callback function to invoke for phrases */
138956   void *pCtx                      /* Second argument to pass to callback */
138957 ){
138958   int rc;                         /* Return code */
138959   int eType = pExpr->eType;       /* Type of expression node pExpr */
138960 
138961   if( eType!=FTSQUERY_PHRASE ){
138962     assert( pExpr->pLeft && pExpr->pRight );
138963     rc = fts3ExprIterate2(pExpr->pLeft, piPhrase, x, pCtx);
138964     if( rc==SQLITE_OK && eType!=FTSQUERY_NOT ){
138965       rc = fts3ExprIterate2(pExpr->pRight, piPhrase, x, pCtx);
138966     }
138967   }else{
138968     rc = x(pExpr, *piPhrase, pCtx);
138969     (*piPhrase)++;
138970   }
138971   return rc;
138972 }
138973 
138974 /*
138975 ** Iterate through all phrase nodes in an FTS3 query, except those that
138976 ** are part of a sub-tree that is the right-hand-side of a NOT operator.
138977 ** For each phrase node found, the supplied callback function is invoked.
138978 **
138979 ** If the callback function returns anything other than SQLITE_OK, 
138980 ** the iteration is abandoned and the error code returned immediately.
138981 ** Otherwise, SQLITE_OK is returned after a callback has been made for
138982 ** all eligible phrase nodes.
138983 */
138984 static int fts3ExprIterate(
138985   Fts3Expr *pExpr,                /* Expression to iterate phrases of */
138986   int (*x)(Fts3Expr*,int,void*),  /* Callback function to invoke for phrases */
138987   void *pCtx                      /* Second argument to pass to callback */
138988 ){
138989   int iPhrase = 0;                /* Variable used as the phrase counter */
138990   return fts3ExprIterate2(pExpr, &iPhrase, x, pCtx);
138991 }
138992 
138993 /*
138994 ** This is an fts3ExprIterate() callback used while loading the doclists
138995 ** for each phrase into Fts3Expr.aDoclist[]/nDoclist. See also
138996 ** fts3ExprLoadDoclists().
138997 */
138998 static int fts3ExprLoadDoclistsCb(Fts3Expr *pExpr, int iPhrase, void *ctx){
138999   int rc = SQLITE_OK;
139000   Fts3Phrase *pPhrase = pExpr->pPhrase;
139001   LoadDoclistCtx *p = (LoadDoclistCtx *)ctx;
139002 
139003   UNUSED_PARAMETER(iPhrase);
139004 
139005   p->nPhrase++;
139006   p->nToken += pPhrase->nToken;
139007 
139008   return rc;
139009 }
139010 
139011 /*
139012 ** Load the doclists for each phrase in the query associated with FTS3 cursor
139013 ** pCsr. 
139014 **
139015 ** If pnPhrase is not NULL, then *pnPhrase is set to the number of matchable 
139016 ** phrases in the expression (all phrases except those directly or 
139017 ** indirectly descended from the right-hand-side of a NOT operator). If 
139018 ** pnToken is not NULL, then it is set to the number of tokens in all
139019 ** matchable phrases of the expression.
139020 */
139021 static int fts3ExprLoadDoclists(
139022   Fts3Cursor *pCsr,               /* Fts3 cursor for current query */
139023   int *pnPhrase,                  /* OUT: Number of phrases in query */
139024   int *pnToken                    /* OUT: Number of tokens in query */
139025 ){
139026   int rc;                         /* Return Code */
139027   LoadDoclistCtx sCtx = {0,0,0};  /* Context for fts3ExprIterate() */
139028   sCtx.pCsr = pCsr;
139029   rc = fts3ExprIterate(pCsr->pExpr, fts3ExprLoadDoclistsCb, (void *)&sCtx);
139030   if( pnPhrase ) *pnPhrase = sCtx.nPhrase;
139031   if( pnToken ) *pnToken = sCtx.nToken;
139032   return rc;
139033 }
139034 
139035 static int fts3ExprPhraseCountCb(Fts3Expr *pExpr, int iPhrase, void *ctx){
139036   (*(int *)ctx)++;
139037   UNUSED_PARAMETER(pExpr);
139038   UNUSED_PARAMETER(iPhrase);
139039   return SQLITE_OK;
139040 }
139041 static int fts3ExprPhraseCount(Fts3Expr *pExpr){
139042   int nPhrase = 0;
139043   (void)fts3ExprIterate(pExpr, fts3ExprPhraseCountCb, (void *)&nPhrase);
139044   return nPhrase;
139045 }
139046 
139047 /*
139048 ** Advance the position list iterator specified by the first two 
139049 ** arguments so that it points to the first element with a value greater
139050 ** than or equal to parameter iNext.
139051 */
139052 static void fts3SnippetAdvance(char **ppIter, int *piIter, int iNext){
139053   char *pIter = *ppIter;
139054   if( pIter ){
139055     int iIter = *piIter;
139056 
139057     while( iIter<iNext ){
139058       if( 0==(*pIter & 0xFE) ){
139059         iIter = -1;
139060         pIter = 0;
139061         break;
139062       }
139063       fts3GetDeltaPosition(&pIter, &iIter);
139064     }
139065 
139066     *piIter = iIter;
139067     *ppIter = pIter;
139068   }
139069 }
139070 
139071 /*
139072 ** Advance the snippet iterator to the next candidate snippet.
139073 */
139074 static int fts3SnippetNextCandidate(SnippetIter *pIter){
139075   int i;                          /* Loop counter */
139076 
139077   if( pIter->iCurrent<0 ){
139078     /* The SnippetIter object has just been initialized. The first snippet
139079     ** candidate always starts at offset 0 (even if this candidate has a
139080     ** score of 0.0).
139081     */
139082     pIter->iCurrent = 0;
139083 
139084     /* Advance the 'head' iterator of each phrase to the first offset that
139085     ** is greater than or equal to (iNext+nSnippet).
139086     */
139087     for(i=0; i<pIter->nPhrase; i++){
139088       SnippetPhrase *pPhrase = &pIter->aPhrase[i];
139089       fts3SnippetAdvance(&pPhrase->pHead, &pPhrase->iHead, pIter->nSnippet);
139090     }
139091   }else{
139092     int iStart;
139093     int iEnd = 0x7FFFFFFF;
139094 
139095     for(i=0; i<pIter->nPhrase; i++){
139096       SnippetPhrase *pPhrase = &pIter->aPhrase[i];
139097       if( pPhrase->pHead && pPhrase->iHead<iEnd ){
139098         iEnd = pPhrase->iHead;
139099       }
139100     }
139101     if( iEnd==0x7FFFFFFF ){
139102       return 1;
139103     }
139104 
139105     pIter->iCurrent = iStart = iEnd - pIter->nSnippet + 1;
139106     for(i=0; i<pIter->nPhrase; i++){
139107       SnippetPhrase *pPhrase = &pIter->aPhrase[i];
139108       fts3SnippetAdvance(&pPhrase->pHead, &pPhrase->iHead, iEnd+1);
139109       fts3SnippetAdvance(&pPhrase->pTail, &pPhrase->iTail, iStart);
139110     }
139111   }
139112 
139113   return 0;
139114 }
139115 
139116 /*
139117 ** Retrieve information about the current candidate snippet of snippet 
139118 ** iterator pIter.
139119 */
139120 static void fts3SnippetDetails(
139121   SnippetIter *pIter,             /* Snippet iterator */
139122   u64 mCovered,                   /* Bitmask of phrases already covered */
139123   int *piToken,                   /* OUT: First token of proposed snippet */
139124   int *piScore,                   /* OUT: "Score" for this snippet */
139125   u64 *pmCover,                   /* OUT: Bitmask of phrases covered */
139126   u64 *pmHighlight                /* OUT: Bitmask of terms to highlight */
139127 ){
139128   int iStart = pIter->iCurrent;   /* First token of snippet */
139129   int iScore = 0;                 /* Score of this snippet */
139130   int i;                          /* Loop counter */
139131   u64 mCover = 0;                 /* Mask of phrases covered by this snippet */
139132   u64 mHighlight = 0;             /* Mask of tokens to highlight in snippet */
139133 
139134   for(i=0; i<pIter->nPhrase; i++){
139135     SnippetPhrase *pPhrase = &pIter->aPhrase[i];
139136     if( pPhrase->pTail ){
139137       char *pCsr = pPhrase->pTail;
139138       int iCsr = pPhrase->iTail;
139139 
139140       while( iCsr<(iStart+pIter->nSnippet) ){
139141         int j;
139142         u64 mPhrase = (u64)1 << i;
139143         u64 mPos = (u64)1 << (iCsr - iStart);
139144         assert( iCsr>=iStart );
139145         if( (mCover|mCovered)&mPhrase ){
139146           iScore++;
139147         }else{
139148           iScore += 1000;
139149         }
139150         mCover |= mPhrase;
139151 
139152         for(j=0; j<pPhrase->nToken; j++){
139153           mHighlight |= (mPos>>j);
139154         }
139155 
139156         if( 0==(*pCsr & 0x0FE) ) break;
139157         fts3GetDeltaPosition(&pCsr, &iCsr);
139158       }
139159     }
139160   }
139161 
139162   /* Set the output variables before returning. */
139163   *piToken = iStart;
139164   *piScore = iScore;
139165   *pmCover = mCover;
139166   *pmHighlight = mHighlight;
139167 }
139168 
139169 /*
139170 ** This function is an fts3ExprIterate() callback used by fts3BestSnippet().
139171 ** Each invocation populates an element of the SnippetIter.aPhrase[] array.
139172 */
139173 static int fts3SnippetFindPositions(Fts3Expr *pExpr, int iPhrase, void *ctx){
139174   SnippetIter *p = (SnippetIter *)ctx;
139175   SnippetPhrase *pPhrase = &p->aPhrase[iPhrase];
139176   char *pCsr;
139177   int rc;
139178 
139179   pPhrase->nToken = pExpr->pPhrase->nToken;
139180   rc = sqlite3Fts3EvalPhrasePoslist(p->pCsr, pExpr, p->iCol, &pCsr);
139181   assert( rc==SQLITE_OK || pCsr==0 );
139182   if( pCsr ){
139183     int iFirst = 0;
139184     pPhrase->pList = pCsr;
139185     fts3GetDeltaPosition(&pCsr, &iFirst);
139186     assert( iFirst>=0 );
139187     pPhrase->pHead = pCsr;
139188     pPhrase->pTail = pCsr;
139189     pPhrase->iHead = iFirst;
139190     pPhrase->iTail = iFirst;
139191   }else{
139192     assert( rc!=SQLITE_OK || (
139193        pPhrase->pList==0 && pPhrase->pHead==0 && pPhrase->pTail==0 
139194     ));
139195   }
139196 
139197   return rc;
139198 }
139199 
139200 /*
139201 ** Select the fragment of text consisting of nFragment contiguous tokens 
139202 ** from column iCol that represent the "best" snippet. The best snippet
139203 ** is the snippet with the highest score, where scores are calculated
139204 ** by adding:
139205 **
139206 **   (a) +1 point for each occurrence of a matchable phrase in the snippet.
139207 **
139208 **   (b) +1000 points for the first occurrence of each matchable phrase in 
139209 **       the snippet for which the corresponding mCovered bit is not set.
139210 **
139211 ** The selected snippet parameters are stored in structure *pFragment before
139212 ** returning. The score of the selected snippet is stored in *piScore
139213 ** before returning.
139214 */
139215 static int fts3BestSnippet(
139216   int nSnippet,                   /* Desired snippet length */
139217   Fts3Cursor *pCsr,               /* Cursor to create snippet for */
139218   int iCol,                       /* Index of column to create snippet from */
139219   u64 mCovered,                   /* Mask of phrases already covered */
139220   u64 *pmSeen,                    /* IN/OUT: Mask of phrases seen */
139221   SnippetFragment *pFragment,     /* OUT: Best snippet found */
139222   int *piScore                    /* OUT: Score of snippet pFragment */
139223 ){
139224   int rc;                         /* Return Code */
139225   int nList;                      /* Number of phrases in expression */
139226   SnippetIter sIter;              /* Iterates through snippet candidates */
139227   int nByte;                      /* Number of bytes of space to allocate */
139228   int iBestScore = -1;            /* Best snippet score found so far */
139229   int i;                          /* Loop counter */
139230 
139231   memset(&sIter, 0, sizeof(sIter));
139232 
139233   /* Iterate through the phrases in the expression to count them. The same
139234   ** callback makes sure the doclists are loaded for each phrase.
139235   */
139236   rc = fts3ExprLoadDoclists(pCsr, &nList, 0);
139237   if( rc!=SQLITE_OK ){
139238     return rc;
139239   }
139240 
139241   /* Now that it is known how many phrases there are, allocate and zero
139242   ** the required space using malloc().
139243   */
139244   nByte = sizeof(SnippetPhrase) * nList;
139245   sIter.aPhrase = (SnippetPhrase *)sqlite3_malloc(nByte);
139246   if( !sIter.aPhrase ){
139247     return SQLITE_NOMEM;
139248   }
139249   memset(sIter.aPhrase, 0, nByte);
139250 
139251   /* Initialize the contents of the SnippetIter object. Then iterate through
139252   ** the set of phrases in the expression to populate the aPhrase[] array.
139253   */
139254   sIter.pCsr = pCsr;
139255   sIter.iCol = iCol;
139256   sIter.nSnippet = nSnippet;
139257   sIter.nPhrase = nList;
139258   sIter.iCurrent = -1;
139259   (void)fts3ExprIterate(pCsr->pExpr, fts3SnippetFindPositions, (void *)&sIter);
139260 
139261   /* Set the *pmSeen output variable. */
139262   for(i=0; i<nList; i++){
139263     if( sIter.aPhrase[i].pHead ){
139264       *pmSeen |= (u64)1 << i;
139265     }
139266   }
139267 
139268   /* Loop through all candidate snippets. Store the best snippet in 
139269   ** *pFragment. Store its associated 'score' in iBestScore.
139270   */
139271   pFragment->iCol = iCol;
139272   while( !fts3SnippetNextCandidate(&sIter) ){
139273     int iPos;
139274     int iScore;
139275     u64 mCover;
139276     u64 mHighlight;
139277     fts3SnippetDetails(&sIter, mCovered, &iPos, &iScore, &mCover, &mHighlight);
139278     assert( iScore>=0 );
139279     if( iScore>iBestScore ){
139280       pFragment->iPos = iPos;
139281       pFragment->hlmask = mHighlight;
139282       pFragment->covered = mCover;
139283       iBestScore = iScore;
139284     }
139285   }
139286 
139287   sqlite3_free(sIter.aPhrase);
139288   *piScore = iBestScore;
139289   return SQLITE_OK;
139290 }
139291 
139292 
139293 /*
139294 ** Append a string to the string-buffer passed as the first argument.
139295 **
139296 ** If nAppend is negative, then the length of the string zAppend is
139297 ** determined using strlen().
139298 */
139299 static int fts3StringAppend(
139300   StrBuffer *pStr,                /* Buffer to append to */
139301   const char *zAppend,            /* Pointer to data to append to buffer */
139302   int nAppend                     /* Size of zAppend in bytes (or -1) */
139303 ){
139304   if( nAppend<0 ){
139305     nAppend = (int)strlen(zAppend);
139306   }
139307 
139308   /* If there is insufficient space allocated at StrBuffer.z, use realloc()
139309   ** to grow the buffer until so that it is big enough to accomadate the
139310   ** appended data.
139311   */
139312   if( pStr->n+nAppend+1>=pStr->nAlloc ){
139313     int nAlloc = pStr->nAlloc+nAppend+100;
139314     char *zNew = sqlite3_realloc(pStr->z, nAlloc);
139315     if( !zNew ){
139316       return SQLITE_NOMEM;
139317     }
139318     pStr->z = zNew;
139319     pStr->nAlloc = nAlloc;
139320   }
139321   assert( pStr->z!=0 && (pStr->nAlloc >= pStr->n+nAppend+1) );
139322 
139323   /* Append the data to the string buffer. */
139324   memcpy(&pStr->z[pStr->n], zAppend, nAppend);
139325   pStr->n += nAppend;
139326   pStr->z[pStr->n] = '\0';
139327 
139328   return SQLITE_OK;
139329 }
139330 
139331 /*
139332 ** The fts3BestSnippet() function often selects snippets that end with a
139333 ** query term. That is, the final term of the snippet is always a term
139334 ** that requires highlighting. For example, if 'X' is a highlighted term
139335 ** and '.' is a non-highlighted term, BestSnippet() may select:
139336 **
139337 **     ........X.....X
139338 **
139339 ** This function "shifts" the beginning of the snippet forward in the 
139340 ** document so that there are approximately the same number of 
139341 ** non-highlighted terms to the right of the final highlighted term as there
139342 ** are to the left of the first highlighted term. For example, to this:
139343 **
139344 **     ....X.....X....
139345 **
139346 ** This is done as part of extracting the snippet text, not when selecting
139347 ** the snippet. Snippet selection is done based on doclists only, so there
139348 ** is no way for fts3BestSnippet() to know whether or not the document 
139349 ** actually contains terms that follow the final highlighted term. 
139350 */
139351 static int fts3SnippetShift(
139352   Fts3Table *pTab,                /* FTS3 table snippet comes from */
139353   int iLangid,                    /* Language id to use in tokenizing */
139354   int nSnippet,                   /* Number of tokens desired for snippet */
139355   const char *zDoc,               /* Document text to extract snippet from */
139356   int nDoc,                       /* Size of buffer zDoc in bytes */
139357   int *piPos,                     /* IN/OUT: First token of snippet */
139358   u64 *pHlmask                    /* IN/OUT: Mask of tokens to highlight */
139359 ){
139360   u64 hlmask = *pHlmask;          /* Local copy of initial highlight-mask */
139361 
139362   if( hlmask ){
139363     int nLeft;                    /* Tokens to the left of first highlight */
139364     int nRight;                   /* Tokens to the right of last highlight */
139365     int nDesired;                 /* Ideal number of tokens to shift forward */
139366 
139367     for(nLeft=0; !(hlmask & ((u64)1 << nLeft)); nLeft++);
139368     for(nRight=0; !(hlmask & ((u64)1 << (nSnippet-1-nRight))); nRight++);
139369     nDesired = (nLeft-nRight)/2;
139370 
139371     /* Ideally, the start of the snippet should be pushed forward in the
139372     ** document nDesired tokens. This block checks if there are actually
139373     ** nDesired tokens to the right of the snippet. If so, *piPos and
139374     ** *pHlMask are updated to shift the snippet nDesired tokens to the
139375     ** right. Otherwise, the snippet is shifted by the number of tokens
139376     ** available.
139377     */
139378     if( nDesired>0 ){
139379       int nShift;                 /* Number of tokens to shift snippet by */
139380       int iCurrent = 0;           /* Token counter */
139381       int rc;                     /* Return Code */
139382       sqlite3_tokenizer_module *pMod;
139383       sqlite3_tokenizer_cursor *pC;
139384       pMod = (sqlite3_tokenizer_module *)pTab->pTokenizer->pModule;
139385 
139386       /* Open a cursor on zDoc/nDoc. Check if there are (nSnippet+nDesired)
139387       ** or more tokens in zDoc/nDoc.
139388       */
139389       rc = sqlite3Fts3OpenTokenizer(pTab->pTokenizer, iLangid, zDoc, nDoc, &pC);
139390       if( rc!=SQLITE_OK ){
139391         return rc;
139392       }
139393       while( rc==SQLITE_OK && iCurrent<(nSnippet+nDesired) ){
139394         const char *ZDUMMY; int DUMMY1 = 0, DUMMY2 = 0, DUMMY3 = 0;
139395         rc = pMod->xNext(pC, &ZDUMMY, &DUMMY1, &DUMMY2, &DUMMY3, &iCurrent);
139396       }
139397       pMod->xClose(pC);
139398       if( rc!=SQLITE_OK && rc!=SQLITE_DONE ){ return rc; }
139399 
139400       nShift = (rc==SQLITE_DONE)+iCurrent-nSnippet;
139401       assert( nShift<=nDesired );
139402       if( nShift>0 ){
139403         *piPos += nShift;
139404         *pHlmask = hlmask >> nShift;
139405       }
139406     }
139407   }
139408   return SQLITE_OK;
139409 }
139410 
139411 /*
139412 ** Extract the snippet text for fragment pFragment from cursor pCsr and
139413 ** append it to string buffer pOut.
139414 */
139415 static int fts3SnippetText(
139416   Fts3Cursor *pCsr,               /* FTS3 Cursor */
139417   SnippetFragment *pFragment,     /* Snippet to extract */
139418   int iFragment,                  /* Fragment number */
139419   int isLast,                     /* True for final fragment in snippet */
139420   int nSnippet,                   /* Number of tokens in extracted snippet */
139421   const char *zOpen,              /* String inserted before highlighted term */
139422   const char *zClose,             /* String inserted after highlighted term */
139423   const char *zEllipsis,          /* String inserted between snippets */
139424   StrBuffer *pOut                 /* Write output here */
139425 ){
139426   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
139427   int rc;                         /* Return code */
139428   const char *zDoc;               /* Document text to extract snippet from */
139429   int nDoc;                       /* Size of zDoc in bytes */
139430   int iCurrent = 0;               /* Current token number of document */
139431   int iEnd = 0;                   /* Byte offset of end of current token */
139432   int isShiftDone = 0;            /* True after snippet is shifted */
139433   int iPos = pFragment->iPos;     /* First token of snippet */
139434   u64 hlmask = pFragment->hlmask; /* Highlight-mask for snippet */
139435   int iCol = pFragment->iCol+1;   /* Query column to extract text from */
139436   sqlite3_tokenizer_module *pMod; /* Tokenizer module methods object */
139437   sqlite3_tokenizer_cursor *pC;   /* Tokenizer cursor open on zDoc/nDoc */
139438   
139439   zDoc = (const char *)sqlite3_column_text(pCsr->pStmt, iCol);
139440   if( zDoc==0 ){
139441     if( sqlite3_column_type(pCsr->pStmt, iCol)!=SQLITE_NULL ){
139442       return SQLITE_NOMEM;
139443     }
139444     return SQLITE_OK;
139445   }
139446   nDoc = sqlite3_column_bytes(pCsr->pStmt, iCol);
139447 
139448   /* Open a token cursor on the document. */
139449   pMod = (sqlite3_tokenizer_module *)pTab->pTokenizer->pModule;
139450   rc = sqlite3Fts3OpenTokenizer(pTab->pTokenizer, pCsr->iLangid, zDoc,nDoc,&pC);
139451   if( rc!=SQLITE_OK ){
139452     return rc;
139453   }
139454 
139455   while( rc==SQLITE_OK ){
139456     const char *ZDUMMY;           /* Dummy argument used with tokenizer */
139457     int DUMMY1 = -1;              /* Dummy argument used with tokenizer */
139458     int iBegin = 0;               /* Offset in zDoc of start of token */
139459     int iFin = 0;                 /* Offset in zDoc of end of token */
139460     int isHighlight = 0;          /* True for highlighted terms */
139461 
139462     /* Variable DUMMY1 is initialized to a negative value above. Elsewhere
139463     ** in the FTS code the variable that the third argument to xNext points to
139464     ** is initialized to zero before the first (*but not necessarily
139465     ** subsequent*) call to xNext(). This is done for a particular application
139466     ** that needs to know whether or not the tokenizer is being used for
139467     ** snippet generation or for some other purpose.
139468     **
139469     ** Extreme care is required when writing code to depend on this
139470     ** initialization. It is not a documented part of the tokenizer interface.
139471     ** If a tokenizer is used directly by any code outside of FTS, this
139472     ** convention might not be respected.  */
139473     rc = pMod->xNext(pC, &ZDUMMY, &DUMMY1, &iBegin, &iFin, &iCurrent);
139474     if( rc!=SQLITE_OK ){
139475       if( rc==SQLITE_DONE ){
139476         /* Special case - the last token of the snippet is also the last token
139477         ** of the column. Append any punctuation that occurred between the end
139478         ** of the previous token and the end of the document to the output. 
139479         ** Then break out of the loop. */
139480         rc = fts3StringAppend(pOut, &zDoc[iEnd], -1);
139481       }
139482       break;
139483     }
139484     if( iCurrent<iPos ){ continue; }
139485 
139486     if( !isShiftDone ){
139487       int n = nDoc - iBegin;
139488       rc = fts3SnippetShift(
139489           pTab, pCsr->iLangid, nSnippet, &zDoc[iBegin], n, &iPos, &hlmask
139490       );
139491       isShiftDone = 1;
139492 
139493       /* Now that the shift has been done, check if the initial "..." are
139494       ** required. They are required if (a) this is not the first fragment,
139495       ** or (b) this fragment does not begin at position 0 of its column. 
139496       */
139497       if( rc==SQLITE_OK && (iPos>0 || iFragment>0) ){
139498         rc = fts3StringAppend(pOut, zEllipsis, -1);
139499       }
139500       if( rc!=SQLITE_OK || iCurrent<iPos ) continue;
139501     }
139502 
139503     if( iCurrent>=(iPos+nSnippet) ){
139504       if( isLast ){
139505         rc = fts3StringAppend(pOut, zEllipsis, -1);
139506       }
139507       break;
139508     }
139509 
139510     /* Set isHighlight to true if this term should be highlighted. */
139511     isHighlight = (hlmask & ((u64)1 << (iCurrent-iPos)))!=0;
139512 
139513     if( iCurrent>iPos ) rc = fts3StringAppend(pOut, &zDoc[iEnd], iBegin-iEnd);
139514     if( rc==SQLITE_OK && isHighlight ) rc = fts3StringAppend(pOut, zOpen, -1);
139515     if( rc==SQLITE_OK ) rc = fts3StringAppend(pOut, &zDoc[iBegin], iFin-iBegin);
139516     if( rc==SQLITE_OK && isHighlight ) rc = fts3StringAppend(pOut, zClose, -1);
139517 
139518     iEnd = iFin;
139519   }
139520 
139521   pMod->xClose(pC);
139522   return rc;
139523 }
139524 
139525 
139526 /*
139527 ** This function is used to count the entries in a column-list (a 
139528 ** delta-encoded list of term offsets within a single column of a single 
139529 ** row). When this function is called, *ppCollist should point to the
139530 ** beginning of the first varint in the column-list (the varint that
139531 ** contains the position of the first matching term in the column data).
139532 ** Before returning, *ppCollist is set to point to the first byte after
139533 ** the last varint in the column-list (either the 0x00 signifying the end
139534 ** of the position-list, or the 0x01 that precedes the column number of
139535 ** the next column in the position-list).
139536 **
139537 ** The number of elements in the column-list is returned.
139538 */
139539 static int fts3ColumnlistCount(char **ppCollist){
139540   char *pEnd = *ppCollist;
139541   char c = 0;
139542   int nEntry = 0;
139543 
139544   /* A column-list is terminated by either a 0x01 or 0x00. */
139545   while( 0xFE & (*pEnd | c) ){
139546     c = *pEnd++ & 0x80;
139547     if( !c ) nEntry++;
139548   }
139549 
139550   *ppCollist = pEnd;
139551   return nEntry;
139552 }
139553 
139554 /*
139555 ** fts3ExprIterate() callback used to collect the "global" matchinfo stats
139556 ** for a single query. 
139557 **
139558 ** fts3ExprIterate() callback to load the 'global' elements of a
139559 ** FTS3_MATCHINFO_HITS matchinfo array. The global stats are those elements 
139560 ** of the matchinfo array that are constant for all rows returned by the 
139561 ** current query.
139562 **
139563 ** Argument pCtx is actually a pointer to a struct of type MatchInfo. This
139564 ** function populates Matchinfo.aMatchinfo[] as follows:
139565 **
139566 **   for(iCol=0; iCol<nCol; iCol++){
139567 **     aMatchinfo[3*iPhrase*nCol + 3*iCol + 1] = X;
139568 **     aMatchinfo[3*iPhrase*nCol + 3*iCol + 2] = Y;
139569 **   }
139570 **
139571 ** where X is the number of matches for phrase iPhrase is column iCol of all
139572 ** rows of the table. Y is the number of rows for which column iCol contains
139573 ** at least one instance of phrase iPhrase.
139574 **
139575 ** If the phrase pExpr consists entirely of deferred tokens, then all X and
139576 ** Y values are set to nDoc, where nDoc is the number of documents in the 
139577 ** file system. This is done because the full-text index doclist is required
139578 ** to calculate these values properly, and the full-text index doclist is
139579 ** not available for deferred tokens.
139580 */
139581 static int fts3ExprGlobalHitsCb(
139582   Fts3Expr *pExpr,                /* Phrase expression node */
139583   int iPhrase,                    /* Phrase number (numbered from zero) */
139584   void *pCtx                      /* Pointer to MatchInfo structure */
139585 ){
139586   MatchInfo *p = (MatchInfo *)pCtx;
139587   return sqlite3Fts3EvalPhraseStats(
139588       p->pCursor, pExpr, &p->aMatchinfo[3*iPhrase*p->nCol]
139589   );
139590 }
139591 
139592 /*
139593 ** fts3ExprIterate() callback used to collect the "local" part of the
139594 ** FTS3_MATCHINFO_HITS array. The local stats are those elements of the 
139595 ** array that are different for each row returned by the query.
139596 */
139597 static int fts3ExprLocalHitsCb(
139598   Fts3Expr *pExpr,                /* Phrase expression node */
139599   int iPhrase,                    /* Phrase number */
139600   void *pCtx                      /* Pointer to MatchInfo structure */
139601 ){
139602   int rc = SQLITE_OK;
139603   MatchInfo *p = (MatchInfo *)pCtx;
139604   int iStart = iPhrase * p->nCol * 3;
139605   int i;
139606 
139607   for(i=0; i<p->nCol && rc==SQLITE_OK; i++){
139608     char *pCsr;
139609     rc = sqlite3Fts3EvalPhrasePoslist(p->pCursor, pExpr, i, &pCsr);
139610     if( pCsr ){
139611       p->aMatchinfo[iStart+i*3] = fts3ColumnlistCount(&pCsr);
139612     }else{
139613       p->aMatchinfo[iStart+i*3] = 0;
139614     }
139615   }
139616 
139617   return rc;
139618 }
139619 
139620 static int fts3MatchinfoCheck(
139621   Fts3Table *pTab, 
139622   char cArg,
139623   char **pzErr
139624 ){
139625   if( (cArg==FTS3_MATCHINFO_NPHRASE)
139626    || (cArg==FTS3_MATCHINFO_NCOL)
139627    || (cArg==FTS3_MATCHINFO_NDOC && pTab->bFts4)
139628    || (cArg==FTS3_MATCHINFO_AVGLENGTH && pTab->bFts4)
139629    || (cArg==FTS3_MATCHINFO_LENGTH && pTab->bHasDocsize)
139630    || (cArg==FTS3_MATCHINFO_LCS)
139631    || (cArg==FTS3_MATCHINFO_HITS)
139632   ){
139633     return SQLITE_OK;
139634   }
139635   *pzErr = sqlite3_mprintf("unrecognized matchinfo request: %c", cArg);
139636   return SQLITE_ERROR;
139637 }
139638 
139639 static int fts3MatchinfoSize(MatchInfo *pInfo, char cArg){
139640   int nVal;                       /* Number of integers output by cArg */
139641 
139642   switch( cArg ){
139643     case FTS3_MATCHINFO_NDOC:
139644     case FTS3_MATCHINFO_NPHRASE: 
139645     case FTS3_MATCHINFO_NCOL: 
139646       nVal = 1;
139647       break;
139648 
139649     case FTS3_MATCHINFO_AVGLENGTH:
139650     case FTS3_MATCHINFO_LENGTH:
139651     case FTS3_MATCHINFO_LCS:
139652       nVal = pInfo->nCol;
139653       break;
139654 
139655     default:
139656       assert( cArg==FTS3_MATCHINFO_HITS );
139657       nVal = pInfo->nCol * pInfo->nPhrase * 3;
139658       break;
139659   }
139660 
139661   return nVal;
139662 }
139663 
139664 static int fts3MatchinfoSelectDoctotal(
139665   Fts3Table *pTab,
139666   sqlite3_stmt **ppStmt,
139667   sqlite3_int64 *pnDoc,
139668   const char **paLen
139669 ){
139670   sqlite3_stmt *pStmt;
139671   const char *a;
139672   sqlite3_int64 nDoc;
139673 
139674   if( !*ppStmt ){
139675     int rc = sqlite3Fts3SelectDoctotal(pTab, ppStmt);
139676     if( rc!=SQLITE_OK ) return rc;
139677   }
139678   pStmt = *ppStmt;
139679   assert( sqlite3_data_count(pStmt)==1 );
139680 
139681   a = sqlite3_column_blob(pStmt, 0);
139682   a += sqlite3Fts3GetVarint(a, &nDoc);
139683   if( nDoc==0 ) return FTS_CORRUPT_VTAB;
139684   *pnDoc = (u32)nDoc;
139685 
139686   if( paLen ) *paLen = a;
139687   return SQLITE_OK;
139688 }
139689 
139690 /*
139691 ** An instance of the following structure is used to store state while 
139692 ** iterating through a multi-column position-list corresponding to the
139693 ** hits for a single phrase on a single row in order to calculate the
139694 ** values for a matchinfo() FTS3_MATCHINFO_LCS request.
139695 */
139696 typedef struct LcsIterator LcsIterator;
139697 struct LcsIterator {
139698   Fts3Expr *pExpr;                /* Pointer to phrase expression */
139699   int iPosOffset;                 /* Tokens count up to end of this phrase */
139700   char *pRead;                    /* Cursor used to iterate through aDoclist */
139701   int iPos;                       /* Current position */
139702 };
139703 
139704 /* 
139705 ** If LcsIterator.iCol is set to the following value, the iterator has
139706 ** finished iterating through all offsets for all columns.
139707 */
139708 #define LCS_ITERATOR_FINISHED 0x7FFFFFFF;
139709 
139710 static int fts3MatchinfoLcsCb(
139711   Fts3Expr *pExpr,                /* Phrase expression node */
139712   int iPhrase,                    /* Phrase number (numbered from zero) */
139713   void *pCtx                      /* Pointer to MatchInfo structure */
139714 ){
139715   LcsIterator *aIter = (LcsIterator *)pCtx;
139716   aIter[iPhrase].pExpr = pExpr;
139717   return SQLITE_OK;
139718 }
139719 
139720 /*
139721 ** Advance the iterator passed as an argument to the next position. Return
139722 ** 1 if the iterator is at EOF or if it now points to the start of the
139723 ** position list for the next column.
139724 */
139725 static int fts3LcsIteratorAdvance(LcsIterator *pIter){
139726   char *pRead = pIter->pRead;
139727   sqlite3_int64 iRead;
139728   int rc = 0;
139729 
139730   pRead += sqlite3Fts3GetVarint(pRead, &iRead);
139731   if( iRead==0 || iRead==1 ){
139732     pRead = 0;
139733     rc = 1;
139734   }else{
139735     pIter->iPos += (int)(iRead-2);
139736   }
139737 
139738   pIter->pRead = pRead;
139739   return rc;
139740 }
139741   
139742 /*
139743 ** This function implements the FTS3_MATCHINFO_LCS matchinfo() flag. 
139744 **
139745 ** If the call is successful, the longest-common-substring lengths for each
139746 ** column are written into the first nCol elements of the pInfo->aMatchinfo[] 
139747 ** array before returning. SQLITE_OK is returned in this case.
139748 **
139749 ** Otherwise, if an error occurs, an SQLite error code is returned and the
139750 ** data written to the first nCol elements of pInfo->aMatchinfo[] is 
139751 ** undefined.
139752 */
139753 static int fts3MatchinfoLcs(Fts3Cursor *pCsr, MatchInfo *pInfo){
139754   LcsIterator *aIter;
139755   int i;
139756   int iCol;
139757   int nToken = 0;
139758 
139759   /* Allocate and populate the array of LcsIterator objects. The array
139760   ** contains one element for each matchable phrase in the query.
139761   **/
139762   aIter = sqlite3_malloc(sizeof(LcsIterator) * pCsr->nPhrase);
139763   if( !aIter ) return SQLITE_NOMEM;
139764   memset(aIter, 0, sizeof(LcsIterator) * pCsr->nPhrase);
139765   (void)fts3ExprIterate(pCsr->pExpr, fts3MatchinfoLcsCb, (void*)aIter);
139766 
139767   for(i=0; i<pInfo->nPhrase; i++){
139768     LcsIterator *pIter = &aIter[i];
139769     nToken -= pIter->pExpr->pPhrase->nToken;
139770     pIter->iPosOffset = nToken;
139771   }
139772 
139773   for(iCol=0; iCol<pInfo->nCol; iCol++){
139774     int nLcs = 0;                 /* LCS value for this column */
139775     int nLive = 0;                /* Number of iterators in aIter not at EOF */
139776 
139777     for(i=0; i<pInfo->nPhrase; i++){
139778       int rc;
139779       LcsIterator *pIt = &aIter[i];
139780       rc = sqlite3Fts3EvalPhrasePoslist(pCsr, pIt->pExpr, iCol, &pIt->pRead);
139781       if( rc!=SQLITE_OK ) return rc;
139782       if( pIt->pRead ){
139783         pIt->iPos = pIt->iPosOffset;
139784         fts3LcsIteratorAdvance(&aIter[i]);
139785         nLive++;
139786       }
139787     }
139788 
139789     while( nLive>0 ){
139790       LcsIterator *pAdv = 0;      /* The iterator to advance by one position */
139791       int nThisLcs = 0;           /* LCS for the current iterator positions */
139792 
139793       for(i=0; i<pInfo->nPhrase; i++){
139794         LcsIterator *pIter = &aIter[i];
139795         if( pIter->pRead==0 ){
139796           /* This iterator is already at EOF for this column. */
139797           nThisLcs = 0;
139798         }else{
139799           if( pAdv==0 || pIter->iPos<pAdv->iPos ){
139800             pAdv = pIter;
139801           }
139802           if( nThisLcs==0 || pIter->iPos==pIter[-1].iPos ){
139803             nThisLcs++;
139804           }else{
139805             nThisLcs = 1;
139806           }
139807           if( nThisLcs>nLcs ) nLcs = nThisLcs;
139808         }
139809       }
139810       if( fts3LcsIteratorAdvance(pAdv) ) nLive--;
139811     }
139812 
139813     pInfo->aMatchinfo[iCol] = nLcs;
139814   }
139815 
139816   sqlite3_free(aIter);
139817   return SQLITE_OK;
139818 }
139819 
139820 /*
139821 ** Populate the buffer pInfo->aMatchinfo[] with an array of integers to
139822 ** be returned by the matchinfo() function. Argument zArg contains the 
139823 ** format string passed as the second argument to matchinfo (or the
139824 ** default value "pcx" if no second argument was specified). The format
139825 ** string has already been validated and the pInfo->aMatchinfo[] array
139826 ** is guaranteed to be large enough for the output.
139827 **
139828 ** If bGlobal is true, then populate all fields of the matchinfo() output.
139829 ** If it is false, then assume that those fields that do not change between
139830 ** rows (i.e. FTS3_MATCHINFO_NPHRASE, NCOL, NDOC, AVGLENGTH and part of HITS)
139831 ** have already been populated.
139832 **
139833 ** Return SQLITE_OK if successful, or an SQLite error code if an error 
139834 ** occurs. If a value other than SQLITE_OK is returned, the state the
139835 ** pInfo->aMatchinfo[] buffer is left in is undefined.
139836 */
139837 static int fts3MatchinfoValues(
139838   Fts3Cursor *pCsr,               /* FTS3 cursor object */
139839   int bGlobal,                    /* True to grab the global stats */
139840   MatchInfo *pInfo,               /* Matchinfo context object */
139841   const char *zArg                /* Matchinfo format string */
139842 ){
139843   int rc = SQLITE_OK;
139844   int i;
139845   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
139846   sqlite3_stmt *pSelect = 0;
139847 
139848   for(i=0; rc==SQLITE_OK && zArg[i]; i++){
139849 
139850     switch( zArg[i] ){
139851       case FTS3_MATCHINFO_NPHRASE:
139852         if( bGlobal ) pInfo->aMatchinfo[0] = pInfo->nPhrase;
139853         break;
139854 
139855       case FTS3_MATCHINFO_NCOL:
139856         if( bGlobal ) pInfo->aMatchinfo[0] = pInfo->nCol;
139857         break;
139858         
139859       case FTS3_MATCHINFO_NDOC:
139860         if( bGlobal ){
139861           sqlite3_int64 nDoc = 0;
139862           rc = fts3MatchinfoSelectDoctotal(pTab, &pSelect, &nDoc, 0);
139863           pInfo->aMatchinfo[0] = (u32)nDoc;
139864         }
139865         break;
139866 
139867       case FTS3_MATCHINFO_AVGLENGTH: 
139868         if( bGlobal ){
139869           sqlite3_int64 nDoc;     /* Number of rows in table */
139870           const char *a;          /* Aggregate column length array */
139871 
139872           rc = fts3MatchinfoSelectDoctotal(pTab, &pSelect, &nDoc, &a);
139873           if( rc==SQLITE_OK ){
139874             int iCol;
139875             for(iCol=0; iCol<pInfo->nCol; iCol++){
139876               u32 iVal;
139877               sqlite3_int64 nToken;
139878               a += sqlite3Fts3GetVarint(a, &nToken);
139879               iVal = (u32)(((u32)(nToken&0xffffffff)+nDoc/2)/nDoc);
139880               pInfo->aMatchinfo[iCol] = iVal;
139881             }
139882           }
139883         }
139884         break;
139885 
139886       case FTS3_MATCHINFO_LENGTH: {
139887         sqlite3_stmt *pSelectDocsize = 0;
139888         rc = sqlite3Fts3SelectDocsize(pTab, pCsr->iPrevId, &pSelectDocsize);
139889         if( rc==SQLITE_OK ){
139890           int iCol;
139891           const char *a = sqlite3_column_blob(pSelectDocsize, 0);
139892           for(iCol=0; iCol<pInfo->nCol; iCol++){
139893             sqlite3_int64 nToken;
139894             a += sqlite3Fts3GetVarint(a, &nToken);
139895             pInfo->aMatchinfo[iCol] = (u32)nToken;
139896           }
139897         }
139898         sqlite3_reset(pSelectDocsize);
139899         break;
139900       }
139901 
139902       case FTS3_MATCHINFO_LCS:
139903         rc = fts3ExprLoadDoclists(pCsr, 0, 0);
139904         if( rc==SQLITE_OK ){
139905           rc = fts3MatchinfoLcs(pCsr, pInfo);
139906         }
139907         break;
139908 
139909       default: {
139910         Fts3Expr *pExpr;
139911         assert( zArg[i]==FTS3_MATCHINFO_HITS );
139912         pExpr = pCsr->pExpr;
139913         rc = fts3ExprLoadDoclists(pCsr, 0, 0);
139914         if( rc!=SQLITE_OK ) break;
139915         if( bGlobal ){
139916           if( pCsr->pDeferred ){
139917             rc = fts3MatchinfoSelectDoctotal(pTab, &pSelect, &pInfo->nDoc, 0);
139918             if( rc!=SQLITE_OK ) break;
139919           }
139920           rc = fts3ExprIterate(pExpr, fts3ExprGlobalHitsCb,(void*)pInfo);
139921           if( rc!=SQLITE_OK ) break;
139922         }
139923         (void)fts3ExprIterate(pExpr, fts3ExprLocalHitsCb,(void*)pInfo);
139924         break;
139925       }
139926     }
139927 
139928     pInfo->aMatchinfo += fts3MatchinfoSize(pInfo, zArg[i]);
139929   }
139930 
139931   sqlite3_reset(pSelect);
139932   return rc;
139933 }
139934 
139935 
139936 /*
139937 ** Populate pCsr->aMatchinfo[] with data for the current row. The 
139938 ** 'matchinfo' data is an array of 32-bit unsigned integers (C type u32).
139939 */
139940 static int fts3GetMatchinfo(
139941   Fts3Cursor *pCsr,               /* FTS3 Cursor object */
139942   const char *zArg                /* Second argument to matchinfo() function */
139943 ){
139944   MatchInfo sInfo;
139945   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
139946   int rc = SQLITE_OK;
139947   int bGlobal = 0;                /* Collect 'global' stats as well as local */
139948 
139949   memset(&sInfo, 0, sizeof(MatchInfo));
139950   sInfo.pCursor = pCsr;
139951   sInfo.nCol = pTab->nColumn;
139952 
139953   /* If there is cached matchinfo() data, but the format string for the 
139954   ** cache does not match the format string for this request, discard 
139955   ** the cached data. */
139956   if( pCsr->zMatchinfo && strcmp(pCsr->zMatchinfo, zArg) ){
139957     assert( pCsr->aMatchinfo );
139958     sqlite3_free(pCsr->aMatchinfo);
139959     pCsr->zMatchinfo = 0;
139960     pCsr->aMatchinfo = 0;
139961   }
139962 
139963   /* If Fts3Cursor.aMatchinfo[] is NULL, then this is the first time the
139964   ** matchinfo function has been called for this query. In this case 
139965   ** allocate the array used to accumulate the matchinfo data and
139966   ** initialize those elements that are constant for every row.
139967   */
139968   if( pCsr->aMatchinfo==0 ){
139969     int nMatchinfo = 0;           /* Number of u32 elements in match-info */
139970     int nArg;                     /* Bytes in zArg */
139971     int i;                        /* Used to iterate through zArg */
139972 
139973     /* Determine the number of phrases in the query */
139974     pCsr->nPhrase = fts3ExprPhraseCount(pCsr->pExpr);
139975     sInfo.nPhrase = pCsr->nPhrase;
139976 
139977     /* Determine the number of integers in the buffer returned by this call. */
139978     for(i=0; zArg[i]; i++){
139979       nMatchinfo += fts3MatchinfoSize(&sInfo, zArg[i]);
139980     }
139981 
139982     /* Allocate space for Fts3Cursor.aMatchinfo[] and Fts3Cursor.zMatchinfo. */
139983     nArg = (int)strlen(zArg);
139984     pCsr->aMatchinfo = (u32 *)sqlite3_malloc(sizeof(u32)*nMatchinfo + nArg + 1);
139985     if( !pCsr->aMatchinfo ) return SQLITE_NOMEM;
139986 
139987     pCsr->zMatchinfo = (char *)&pCsr->aMatchinfo[nMatchinfo];
139988     pCsr->nMatchinfo = nMatchinfo;
139989     memcpy(pCsr->zMatchinfo, zArg, nArg+1);
139990     memset(pCsr->aMatchinfo, 0, sizeof(u32)*nMatchinfo);
139991     pCsr->isMatchinfoNeeded = 1;
139992     bGlobal = 1;
139993   }
139994 
139995   sInfo.aMatchinfo = pCsr->aMatchinfo;
139996   sInfo.nPhrase = pCsr->nPhrase;
139997   if( pCsr->isMatchinfoNeeded ){
139998     rc = fts3MatchinfoValues(pCsr, bGlobal, &sInfo, zArg);
139999     pCsr->isMatchinfoNeeded = 0;
140000   }
140001 
140002   return rc;
140003 }
140004 
140005 /*
140006 ** Implementation of snippet() function.
140007 */
140008 SQLITE_PRIVATE void sqlite3Fts3Snippet(
140009   sqlite3_context *pCtx,          /* SQLite function call context */
140010   Fts3Cursor *pCsr,               /* Cursor object */
140011   const char *zStart,             /* Snippet start text - "<b>" */
140012   const char *zEnd,               /* Snippet end text - "</b>" */
140013   const char *zEllipsis,          /* Snippet ellipsis text - "<b>...</b>" */
140014   int iCol,                       /* Extract snippet from this column */
140015   int nToken                      /* Approximate number of tokens in snippet */
140016 ){
140017   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
140018   int rc = SQLITE_OK;
140019   int i;
140020   StrBuffer res = {0, 0, 0};
140021 
140022   /* The returned text includes up to four fragments of text extracted from
140023   ** the data in the current row. The first iteration of the for(...) loop
140024   ** below attempts to locate a single fragment of text nToken tokens in 
140025   ** size that contains at least one instance of all phrases in the query
140026   ** expression that appear in the current row. If such a fragment of text
140027   ** cannot be found, the second iteration of the loop attempts to locate
140028   ** a pair of fragments, and so on.
140029   */
140030   int nSnippet = 0;               /* Number of fragments in this snippet */
140031   SnippetFragment aSnippet[4];    /* Maximum of 4 fragments per snippet */
140032   int nFToken = -1;               /* Number of tokens in each fragment */
140033 
140034   if( !pCsr->pExpr ){
140035     sqlite3_result_text(pCtx, "", 0, SQLITE_STATIC);
140036     return;
140037   }
140038 
140039   for(nSnippet=1; 1; nSnippet++){
140040 
140041     int iSnip;                    /* Loop counter 0..nSnippet-1 */
140042     u64 mCovered = 0;             /* Bitmask of phrases covered by snippet */
140043     u64 mSeen = 0;                /* Bitmask of phrases seen by BestSnippet() */
140044 
140045     if( nToken>=0 ){
140046       nFToken = (nToken+nSnippet-1) / nSnippet;
140047     }else{
140048       nFToken = -1 * nToken;
140049     }
140050 
140051     for(iSnip=0; iSnip<nSnippet; iSnip++){
140052       int iBestScore = -1;        /* Best score of columns checked so far */
140053       int iRead;                  /* Used to iterate through columns */
140054       SnippetFragment *pFragment = &aSnippet[iSnip];
140055 
140056       memset(pFragment, 0, sizeof(*pFragment));
140057 
140058       /* Loop through all columns of the table being considered for snippets.
140059       ** If the iCol argument to this function was negative, this means all
140060       ** columns of the FTS3 table. Otherwise, only column iCol is considered.
140061       */
140062       for(iRead=0; iRead<pTab->nColumn; iRead++){
140063         SnippetFragment sF = {0, 0, 0, 0};
140064         int iS;
140065         if( iCol>=0 && iRead!=iCol ) continue;
140066 
140067         /* Find the best snippet of nFToken tokens in column iRead. */
140068         rc = fts3BestSnippet(nFToken, pCsr, iRead, mCovered, &mSeen, &sF, &iS);
140069         if( rc!=SQLITE_OK ){
140070           goto snippet_out;
140071         }
140072         if( iS>iBestScore ){
140073           *pFragment = sF;
140074           iBestScore = iS;
140075         }
140076       }
140077 
140078       mCovered |= pFragment->covered;
140079     }
140080 
140081     /* If all query phrases seen by fts3BestSnippet() are present in at least
140082     ** one of the nSnippet snippet fragments, break out of the loop.
140083     */
140084     assert( (mCovered&mSeen)==mCovered );
140085     if( mSeen==mCovered || nSnippet==SizeofArray(aSnippet) ) break;
140086   }
140087 
140088   assert( nFToken>0 );
140089 
140090   for(i=0; i<nSnippet && rc==SQLITE_OK; i++){
140091     rc = fts3SnippetText(pCsr, &aSnippet[i], 
140092         i, (i==nSnippet-1), nFToken, zStart, zEnd, zEllipsis, &res
140093     );
140094   }
140095 
140096  snippet_out:
140097   sqlite3Fts3SegmentsClose(pTab);
140098   if( rc!=SQLITE_OK ){
140099     sqlite3_result_error_code(pCtx, rc);
140100     sqlite3_free(res.z);
140101   }else{
140102     sqlite3_result_text(pCtx, res.z, -1, sqlite3_free);
140103   }
140104 }
140105 
140106 
140107 typedef struct TermOffset TermOffset;
140108 typedef struct TermOffsetCtx TermOffsetCtx;
140109 
140110 struct TermOffset {
140111   char *pList;                    /* Position-list */
140112   int iPos;                       /* Position just read from pList */
140113   int iOff;                       /* Offset of this term from read positions */
140114 };
140115 
140116 struct TermOffsetCtx {
140117   Fts3Cursor *pCsr;
140118   int iCol;                       /* Column of table to populate aTerm for */
140119   int iTerm;
140120   sqlite3_int64 iDocid;
140121   TermOffset *aTerm;
140122 };
140123 
140124 /*
140125 ** This function is an fts3ExprIterate() callback used by sqlite3Fts3Offsets().
140126 */
140127 static int fts3ExprTermOffsetInit(Fts3Expr *pExpr, int iPhrase, void *ctx){
140128   TermOffsetCtx *p = (TermOffsetCtx *)ctx;
140129   int nTerm;                      /* Number of tokens in phrase */
140130   int iTerm;                      /* For looping through nTerm phrase terms */
140131   char *pList;                    /* Pointer to position list for phrase */
140132   int iPos = 0;                   /* First position in position-list */
140133   int rc;
140134 
140135   UNUSED_PARAMETER(iPhrase);
140136   rc = sqlite3Fts3EvalPhrasePoslist(p->pCsr, pExpr, p->iCol, &pList);
140137   nTerm = pExpr->pPhrase->nToken;
140138   if( pList ){
140139     fts3GetDeltaPosition(&pList, &iPos);
140140     assert( iPos>=0 );
140141   }
140142 
140143   for(iTerm=0; iTerm<nTerm; iTerm++){
140144     TermOffset *pT = &p->aTerm[p->iTerm++];
140145     pT->iOff = nTerm-iTerm-1;
140146     pT->pList = pList;
140147     pT->iPos = iPos;
140148   }
140149 
140150   return rc;
140151 }
140152 
140153 /*
140154 ** Implementation of offsets() function.
140155 */
140156 SQLITE_PRIVATE void sqlite3Fts3Offsets(
140157   sqlite3_context *pCtx,          /* SQLite function call context */
140158   Fts3Cursor *pCsr                /* Cursor object */
140159 ){
140160   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
140161   sqlite3_tokenizer_module const *pMod = pTab->pTokenizer->pModule;
140162   int rc;                         /* Return Code */
140163   int nToken;                     /* Number of tokens in query */
140164   int iCol;                       /* Column currently being processed */
140165   StrBuffer res = {0, 0, 0};      /* Result string */
140166   TermOffsetCtx sCtx;             /* Context for fts3ExprTermOffsetInit() */
140167 
140168   if( !pCsr->pExpr ){
140169     sqlite3_result_text(pCtx, "", 0, SQLITE_STATIC);
140170     return;
140171   }
140172 
140173   memset(&sCtx, 0, sizeof(sCtx));
140174   assert( pCsr->isRequireSeek==0 );
140175 
140176   /* Count the number of terms in the query */
140177   rc = fts3ExprLoadDoclists(pCsr, 0, &nToken);
140178   if( rc!=SQLITE_OK ) goto offsets_out;
140179 
140180   /* Allocate the array of TermOffset iterators. */
140181   sCtx.aTerm = (TermOffset *)sqlite3_malloc(sizeof(TermOffset)*nToken);
140182   if( 0==sCtx.aTerm ){
140183     rc = SQLITE_NOMEM;
140184     goto offsets_out;
140185   }
140186   sCtx.iDocid = pCsr->iPrevId;
140187   sCtx.pCsr = pCsr;
140188 
140189   /* Loop through the table columns, appending offset information to 
140190   ** string-buffer res for each column.
140191   */
140192   for(iCol=0; iCol<pTab->nColumn; iCol++){
140193     sqlite3_tokenizer_cursor *pC; /* Tokenizer cursor */
140194     const char *ZDUMMY;           /* Dummy argument used with xNext() */
140195     int NDUMMY = 0;               /* Dummy argument used with xNext() */
140196     int iStart = 0;
140197     int iEnd = 0;
140198     int iCurrent = 0;
140199     const char *zDoc;
140200     int nDoc;
140201 
140202     /* Initialize the contents of sCtx.aTerm[] for column iCol. There is 
140203     ** no way that this operation can fail, so the return code from
140204     ** fts3ExprIterate() can be discarded.
140205     */
140206     sCtx.iCol = iCol;
140207     sCtx.iTerm = 0;
140208     (void)fts3ExprIterate(pCsr->pExpr, fts3ExprTermOffsetInit, (void *)&sCtx);
140209 
140210     /* Retreive the text stored in column iCol. If an SQL NULL is stored 
140211     ** in column iCol, jump immediately to the next iteration of the loop.
140212     ** If an OOM occurs while retrieving the data (this can happen if SQLite
140213     ** needs to transform the data from utf-16 to utf-8), return SQLITE_NOMEM 
140214     ** to the caller. 
140215     */
140216     zDoc = (const char *)sqlite3_column_text(pCsr->pStmt, iCol+1);
140217     nDoc = sqlite3_column_bytes(pCsr->pStmt, iCol+1);
140218     if( zDoc==0 ){
140219       if( sqlite3_column_type(pCsr->pStmt, iCol+1)==SQLITE_NULL ){
140220         continue;
140221       }
140222       rc = SQLITE_NOMEM;
140223       goto offsets_out;
140224     }
140225 
140226     /* Initialize a tokenizer iterator to iterate through column iCol. */
140227     rc = sqlite3Fts3OpenTokenizer(pTab->pTokenizer, pCsr->iLangid,
140228         zDoc, nDoc, &pC
140229     );
140230     if( rc!=SQLITE_OK ) goto offsets_out;
140231 
140232     rc = pMod->xNext(pC, &ZDUMMY, &NDUMMY, &iStart, &iEnd, &iCurrent);
140233     while( rc==SQLITE_OK ){
140234       int i;                      /* Used to loop through terms */
140235       int iMinPos = 0x7FFFFFFF;   /* Position of next token */
140236       TermOffset *pTerm = 0;      /* TermOffset associated with next token */
140237 
140238       for(i=0; i<nToken; i++){
140239         TermOffset *pT = &sCtx.aTerm[i];
140240         if( pT->pList && (pT->iPos-pT->iOff)<iMinPos ){
140241           iMinPos = pT->iPos-pT->iOff;
140242           pTerm = pT;
140243         }
140244       }
140245 
140246       if( !pTerm ){
140247         /* All offsets for this column have been gathered. */
140248         rc = SQLITE_DONE;
140249       }else{
140250         assert( iCurrent<=iMinPos );
140251         if( 0==(0xFE&*pTerm->pList) ){
140252           pTerm->pList = 0;
140253         }else{
140254           fts3GetDeltaPosition(&pTerm->pList, &pTerm->iPos);
140255         }
140256         while( rc==SQLITE_OK && iCurrent<iMinPos ){
140257           rc = pMod->xNext(pC, &ZDUMMY, &NDUMMY, &iStart, &iEnd, &iCurrent);
140258         }
140259         if( rc==SQLITE_OK ){
140260           char aBuffer[64];
140261           sqlite3_snprintf(sizeof(aBuffer), aBuffer, 
140262               "%d %d %d %d ", iCol, pTerm-sCtx.aTerm, iStart, iEnd-iStart
140263           );
140264           rc = fts3StringAppend(&res, aBuffer, -1);
140265         }else if( rc==SQLITE_DONE && pTab->zContentTbl==0 ){
140266           rc = FTS_CORRUPT_VTAB;
140267         }
140268       }
140269     }
140270     if( rc==SQLITE_DONE ){
140271       rc = SQLITE_OK;
140272     }
140273 
140274     pMod->xClose(pC);
140275     if( rc!=SQLITE_OK ) goto offsets_out;
140276   }
140277 
140278  offsets_out:
140279   sqlite3_free(sCtx.aTerm);
140280   assert( rc!=SQLITE_DONE );
140281   sqlite3Fts3SegmentsClose(pTab);
140282   if( rc!=SQLITE_OK ){
140283     sqlite3_result_error_code(pCtx,  rc);
140284     sqlite3_free(res.z);
140285   }else{
140286     sqlite3_result_text(pCtx, res.z, res.n-1, sqlite3_free);
140287   }
140288   return;
140289 }
140290 
140291 /*
140292 ** Implementation of matchinfo() function.
140293 */
140294 SQLITE_PRIVATE void sqlite3Fts3Matchinfo(
140295   sqlite3_context *pContext,      /* Function call context */
140296   Fts3Cursor *pCsr,               /* FTS3 table cursor */
140297   const char *zArg                /* Second arg to matchinfo() function */
140298 ){
140299   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
140300   int rc;
140301   int i;
140302   const char *zFormat;
140303 
140304   if( zArg ){
140305     for(i=0; zArg[i]; i++){
140306       char *zErr = 0;
140307       if( fts3MatchinfoCheck(pTab, zArg[i], &zErr) ){
140308         sqlite3_result_error(pContext, zErr, -1);
140309         sqlite3_free(zErr);
140310         return;
140311       }
140312     }
140313     zFormat = zArg;
140314   }else{
140315     zFormat = FTS3_MATCHINFO_DEFAULT;
140316   }
140317 
140318   if( !pCsr->pExpr ){
140319     sqlite3_result_blob(pContext, "", 0, SQLITE_STATIC);
140320     return;
140321   }
140322 
140323   /* Retrieve matchinfo() data. */
140324   rc = fts3GetMatchinfo(pCsr, zFormat);
140325   sqlite3Fts3SegmentsClose(pTab);
140326 
140327   if( rc!=SQLITE_OK ){
140328     sqlite3_result_error_code(pContext, rc);
140329   }else{
140330     int n = pCsr->nMatchinfo * sizeof(u32);
140331     sqlite3_result_blob(pContext, pCsr->aMatchinfo, n, SQLITE_TRANSIENT);
140332   }
140333 }
140334 
140335 #endif
140336 
140337 /************** End of fts3_snippet.c ****************************************/
140338 /************** Begin file fts3_unicode.c ************************************/
140339 /*
140340 ** 2012 May 24
140341 **
140342 ** The author disclaims copyright to this source code.  In place of
140343 ** a legal notice, here is a blessing:
140344 **
140345 **    May you do good and not evil.
140346 **    May you find forgiveness for yourself and forgive others.
140347 **    May you share freely, never taking more than you give.
140348 **
140349 ******************************************************************************
140350 **
140351 ** Implementation of the "unicode" full-text-search tokenizer.
140352 */
140353 
140354 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
140355 
140356 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
140357 
140358 /* #include <assert.h> */
140359 /* #include <stdlib.h> */
140360 /* #include <stdio.h> */
140361 /* #include <string.h> */
140362 
140363 
140364 /*
140365 ** The following two macros - READ_UTF8 and WRITE_UTF8 - have been copied
140366 ** from the sqlite3 source file utf.c. If this file is compiled as part
140367 ** of the amalgamation, they are not required.
140368 */
140369 #ifndef SQLITE_AMALGAMATION
140370 
140371 static const unsigned char sqlite3Utf8Trans1[] = {
140372   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
140373   0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
140374   0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
140375   0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
140376   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
140377   0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
140378   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
140379   0x00, 0x01, 0x02, 0x03, 0x00, 0x01, 0x00, 0x00,
140380 };
140381 
140382 #define READ_UTF8(zIn, zTerm, c)                           \
140383   c = *(zIn++);                                            \
140384   if( c>=0xc0 ){                                           \
140385     c = sqlite3Utf8Trans1[c-0xc0];                         \
140386     while( zIn!=zTerm && (*zIn & 0xc0)==0x80 ){            \
140387       c = (c<<6) + (0x3f & *(zIn++));                      \
140388     }                                                      \
140389     if( c<0x80                                             \
140390         || (c&0xFFFFF800)==0xD800                          \
140391         || (c&0xFFFFFFFE)==0xFFFE ){  c = 0xFFFD; }        \
140392   }
140393 
140394 #define WRITE_UTF8(zOut, c) {                          \
140395   if( c<0x00080 ){                                     \
140396     *zOut++ = (u8)(c&0xFF);                            \
140397   }                                                    \
140398   else if( c<0x00800 ){                                \
140399     *zOut++ = 0xC0 + (u8)((c>>6)&0x1F);                \
140400     *zOut++ = 0x80 + (u8)(c & 0x3F);                   \
140401   }                                                    \
140402   else if( c<0x10000 ){                                \
140403     *zOut++ = 0xE0 + (u8)((c>>12)&0x0F);               \
140404     *zOut++ = 0x80 + (u8)((c>>6) & 0x3F);              \
140405     *zOut++ = 0x80 + (u8)(c & 0x3F);                   \
140406   }else{                                               \
140407     *zOut++ = 0xF0 + (u8)((c>>18) & 0x07);             \
140408     *zOut++ = 0x80 + (u8)((c>>12) & 0x3F);             \
140409     *zOut++ = 0x80 + (u8)((c>>6) & 0x3F);              \
140410     *zOut++ = 0x80 + (u8)(c & 0x3F);                   \
140411   }                                                    \
140412 }
140413 
140414 #endif /* ifndef SQLITE_AMALGAMATION */
140415 
140416 typedef struct unicode_tokenizer unicode_tokenizer;
140417 typedef struct unicode_cursor unicode_cursor;
140418 
140419 struct unicode_tokenizer {
140420   sqlite3_tokenizer base;
140421   int bRemoveDiacritic;
140422   int nException;
140423   int *aiException;
140424 };
140425 
140426 struct unicode_cursor {
140427   sqlite3_tokenizer_cursor base;
140428   const unsigned char *aInput;    /* Input text being tokenized */
140429   int nInput;                     /* Size of aInput[] in bytes */
140430   int iOff;                       /* Current offset within aInput[] */
140431   int iToken;                     /* Index of next token to be returned */
140432   char *zToken;                   /* storage for current token */
140433   int nAlloc;                     /* space allocated at zToken */
140434 };
140435 
140436 
140437 /*
140438 ** Destroy a tokenizer allocated by unicodeCreate().
140439 */
140440 static int unicodeDestroy(sqlite3_tokenizer *pTokenizer){
140441   if( pTokenizer ){
140442     unicode_tokenizer *p = (unicode_tokenizer *)pTokenizer;
140443     sqlite3_free(p->aiException);
140444     sqlite3_free(p);
140445   }
140446   return SQLITE_OK;
140447 }
140448 
140449 /*
140450 ** As part of a tokenchars= or separators= option, the CREATE VIRTUAL TABLE
140451 ** statement has specified that the tokenizer for this table shall consider
140452 ** all characters in string zIn/nIn to be separators (if bAlnum==0) or
140453 ** token characters (if bAlnum==1).
140454 **
140455 ** For each codepoint in the zIn/nIn string, this function checks if the
140456 ** sqlite3FtsUnicodeIsalnum() function already returns the desired result.
140457 ** If so, no action is taken. Otherwise, the codepoint is added to the 
140458 ** unicode_tokenizer.aiException[] array. For the purposes of tokenization,
140459 ** the return value of sqlite3FtsUnicodeIsalnum() is inverted for all
140460 ** codepoints in the aiException[] array.
140461 **
140462 ** If a standalone diacritic mark (one that sqlite3FtsUnicodeIsdiacritic()
140463 ** identifies as a diacritic) occurs in the zIn/nIn string it is ignored.
140464 ** It is not possible to change the behavior of the tokenizer with respect
140465 ** to these codepoints.
140466 */
140467 static int unicodeAddExceptions(
140468   unicode_tokenizer *p,           /* Tokenizer to add exceptions to */
140469   int bAlnum,                     /* Replace Isalnum() return value with this */
140470   const char *zIn,                /* Array of characters to make exceptions */
140471   int nIn                         /* Length of z in bytes */
140472 ){
140473   const unsigned char *z = (const unsigned char *)zIn;
140474   const unsigned char *zTerm = &z[nIn];
140475   int iCode;
140476   int nEntry = 0;
140477 
140478   assert( bAlnum==0 || bAlnum==1 );
140479 
140480   while( z<zTerm ){
140481     READ_UTF8(z, zTerm, iCode);
140482     assert( (sqlite3FtsUnicodeIsalnum(iCode) & 0xFFFFFFFE)==0 );
140483     if( sqlite3FtsUnicodeIsalnum(iCode)!=bAlnum 
140484      && sqlite3FtsUnicodeIsdiacritic(iCode)==0 
140485     ){
140486       nEntry++;
140487     }
140488   }
140489 
140490   if( nEntry ){
140491     int *aNew;                    /* New aiException[] array */
140492     int nNew;                     /* Number of valid entries in array aNew[] */
140493 
140494     aNew = sqlite3_realloc(p->aiException, (p->nException+nEntry)*sizeof(int));
140495     if( aNew==0 ) return SQLITE_NOMEM;
140496     nNew = p->nException;
140497 
140498     z = (const unsigned char *)zIn;
140499     while( z<zTerm ){
140500       READ_UTF8(z, zTerm, iCode);
140501       if( sqlite3FtsUnicodeIsalnum(iCode)!=bAlnum 
140502        && sqlite3FtsUnicodeIsdiacritic(iCode)==0
140503       ){
140504         int i, j;
140505         for(i=0; i<nNew && aNew[i]<iCode; i++);
140506         for(j=nNew; j>i; j--) aNew[j] = aNew[j-1];
140507         aNew[i] = iCode;
140508         nNew++;
140509       }
140510     }
140511     p->aiException = aNew;
140512     p->nException = nNew;
140513   }
140514 
140515   return SQLITE_OK;
140516 }
140517 
140518 /*
140519 ** Return true if the p->aiException[] array contains the value iCode.
140520 */
140521 static int unicodeIsException(unicode_tokenizer *p, int iCode){
140522   if( p->nException>0 ){
140523     int *a = p->aiException;
140524     int iLo = 0;
140525     int iHi = p->nException-1;
140526 
140527     while( iHi>=iLo ){
140528       int iTest = (iHi + iLo) / 2;
140529       if( iCode==a[iTest] ){
140530         return 1;
140531       }else if( iCode>a[iTest] ){
140532         iLo = iTest+1;
140533       }else{
140534         iHi = iTest-1;
140535       }
140536     }
140537   }
140538 
140539   return 0;
140540 }
140541 
140542 /*
140543 ** Return true if, for the purposes of tokenization, codepoint iCode is
140544 ** considered a token character (not a separator).
140545 */
140546 static int unicodeIsAlnum(unicode_tokenizer *p, int iCode){
140547   assert( (sqlite3FtsUnicodeIsalnum(iCode) & 0xFFFFFFFE)==0 );
140548   return sqlite3FtsUnicodeIsalnum(iCode) ^ unicodeIsException(p, iCode);
140549 }
140550 
140551 /*
140552 ** Create a new tokenizer instance.
140553 */
140554 static int unicodeCreate(
140555   int nArg,                       /* Size of array argv[] */
140556   const char * const *azArg,      /* Tokenizer creation arguments */
140557   sqlite3_tokenizer **pp          /* OUT: New tokenizer handle */
140558 ){
140559   unicode_tokenizer *pNew;        /* New tokenizer object */
140560   int i;
140561   int rc = SQLITE_OK;
140562 
140563   pNew = (unicode_tokenizer *) sqlite3_malloc(sizeof(unicode_tokenizer));
140564   if( pNew==NULL ) return SQLITE_NOMEM;
140565   memset(pNew, 0, sizeof(unicode_tokenizer));
140566   pNew->bRemoveDiacritic = 1;
140567 
140568   for(i=0; rc==SQLITE_OK && i<nArg; i++){
140569     const char *z = azArg[i];
140570     int n = strlen(z);
140571 
140572     if( n==19 && memcmp("remove_diacritics=1", z, 19)==0 ){
140573       pNew->bRemoveDiacritic = 1;
140574     }
140575     else if( n==19 && memcmp("remove_diacritics=0", z, 19)==0 ){
140576       pNew->bRemoveDiacritic = 0;
140577     }
140578     else if( n>=11 && memcmp("tokenchars=", z, 11)==0 ){
140579       rc = unicodeAddExceptions(pNew, 1, &z[11], n-11);
140580     }
140581     else if( n>=11 && memcmp("separators=", z, 11)==0 ){
140582       rc = unicodeAddExceptions(pNew, 0, &z[11], n-11);
140583     }
140584     else{
140585       /* Unrecognized argument */
140586       rc  = SQLITE_ERROR;
140587     }
140588   }
140589 
140590   if( rc!=SQLITE_OK ){
140591     unicodeDestroy((sqlite3_tokenizer *)pNew);
140592     pNew = 0;
140593   }
140594   *pp = (sqlite3_tokenizer *)pNew;
140595   return rc;
140596 }
140597 
140598 /*
140599 ** Prepare to begin tokenizing a particular string.  The input
140600 ** string to be tokenized is pInput[0..nBytes-1].  A cursor
140601 ** used to incrementally tokenize this string is returned in 
140602 ** *ppCursor.
140603 */
140604 static int unicodeOpen(
140605   sqlite3_tokenizer *p,           /* The tokenizer */
140606   const char *aInput,             /* Input string */
140607   int nInput,                     /* Size of string aInput in bytes */
140608   sqlite3_tokenizer_cursor **pp   /* OUT: New cursor object */
140609 ){
140610   unicode_cursor *pCsr;
140611 
140612   pCsr = (unicode_cursor *)sqlite3_malloc(sizeof(unicode_cursor));
140613   if( pCsr==0 ){
140614     return SQLITE_NOMEM;
140615   }
140616   memset(pCsr, 0, sizeof(unicode_cursor));
140617 
140618   pCsr->aInput = (const unsigned char *)aInput;
140619   if( aInput==0 ){
140620     pCsr->nInput = 0;
140621   }else if( nInput<0 ){
140622     pCsr->nInput = (int)strlen(aInput);
140623   }else{
140624     pCsr->nInput = nInput;
140625   }
140626 
140627   *pp = &pCsr->base;
140628   UNUSED_PARAMETER(p);
140629   return SQLITE_OK;
140630 }
140631 
140632 /*
140633 ** Close a tokenization cursor previously opened by a call to
140634 ** simpleOpen() above.
140635 */
140636 static int unicodeClose(sqlite3_tokenizer_cursor *pCursor){
140637   unicode_cursor *pCsr = (unicode_cursor *) pCursor;
140638   sqlite3_free(pCsr->zToken);
140639   sqlite3_free(pCsr);
140640   return SQLITE_OK;
140641 }
140642 
140643 /*
140644 ** Extract the next token from a tokenization cursor.  The cursor must
140645 ** have been opened by a prior call to simpleOpen().
140646 */
140647 static int unicodeNext(
140648   sqlite3_tokenizer_cursor *pC,   /* Cursor returned by simpleOpen */
140649   const char **paToken,           /* OUT: Token text */
140650   int *pnToken,                   /* OUT: Number of bytes at *paToken */
140651   int *piStart,                   /* OUT: Starting offset of token */
140652   int *piEnd,                     /* OUT: Ending offset of token */
140653   int *piPos                      /* OUT: Position integer of token */
140654 ){
140655   unicode_cursor *pCsr = (unicode_cursor *)pC;
140656   unicode_tokenizer *p = ((unicode_tokenizer *)pCsr->base.pTokenizer);
140657   int iCode;
140658   char *zOut;
140659   const unsigned char *z = &pCsr->aInput[pCsr->iOff];
140660   const unsigned char *zStart = z;
140661   const unsigned char *zEnd;
140662   const unsigned char *zTerm = &pCsr->aInput[pCsr->nInput];
140663 
140664   /* Scan past any delimiter characters before the start of the next token.
140665   ** Return SQLITE_DONE early if this takes us all the way to the end of 
140666   ** the input.  */
140667   while( z<zTerm ){
140668     READ_UTF8(z, zTerm, iCode);
140669     if( unicodeIsAlnum(p, iCode) ) break;
140670     zStart = z;
140671   }
140672   if( zStart>=zTerm ) return SQLITE_DONE;
140673 
140674   zOut = pCsr->zToken;
140675   do {
140676     int iOut;
140677 
140678     /* Grow the output buffer if required. */
140679     if( (zOut-pCsr->zToken)>=(pCsr->nAlloc-4) ){
140680       char *zNew = sqlite3_realloc(pCsr->zToken, pCsr->nAlloc+64);
140681       if( !zNew ) return SQLITE_NOMEM;
140682       zOut = &zNew[zOut - pCsr->zToken];
140683       pCsr->zToken = zNew;
140684       pCsr->nAlloc += 64;
140685     }
140686 
140687     /* Write the folded case of the last character read to the output */
140688     zEnd = z;
140689     iOut = sqlite3FtsUnicodeFold(iCode, p->bRemoveDiacritic);
140690     if( iOut ){
140691       WRITE_UTF8(zOut, iOut);
140692     }
140693 
140694     /* If the cursor is not at EOF, read the next character */
140695     if( z>=zTerm ) break;
140696     READ_UTF8(z, zTerm, iCode);
140697   }while( unicodeIsAlnum(p, iCode) 
140698        || sqlite3FtsUnicodeIsdiacritic(iCode)
140699   );
140700 
140701   /* Set the output variables and return. */
140702   pCsr->iOff = (z - pCsr->aInput);
140703   *paToken = pCsr->zToken;
140704   *pnToken = zOut - pCsr->zToken;
140705   *piStart = (zStart - pCsr->aInput);
140706   *piEnd = (zEnd - pCsr->aInput);
140707   *piPos = pCsr->iToken++;
140708   return SQLITE_OK;
140709 }
140710 
140711 /*
140712 ** Set *ppModule to a pointer to the sqlite3_tokenizer_module 
140713 ** structure for the unicode tokenizer.
140714 */
140715 SQLITE_PRIVATE void sqlite3Fts3UnicodeTokenizer(sqlite3_tokenizer_module const **ppModule){
140716   static const sqlite3_tokenizer_module module = {
140717     0,
140718     unicodeCreate,
140719     unicodeDestroy,
140720     unicodeOpen,
140721     unicodeClose,
140722     unicodeNext,
140723     0,
140724   };
140725   *ppModule = &module;
140726 }
140727 
140728 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
140729 #endif /* ifndef SQLITE_ENABLE_FTS4_UNICODE61 */
140730 
140731 /************** End of fts3_unicode.c ****************************************/
140732 /************** Begin file fts3_unicode2.c ***********************************/
140733 /*
140734 ** 2012 May 25
140735 **
140736 ** The author disclaims copyright to this source code.  In place of
140737 ** a legal notice, here is a blessing:
140738 **
140739 **    May you do good and not evil.
140740 **    May you find forgiveness for yourself and forgive others.
140741 **    May you share freely, never taking more than you give.
140742 **
140743 ******************************************************************************
140744 */
140745 
140746 /*
140747 ** DO NOT EDIT THIS MACHINE GENERATED FILE.
140748 */
140749 
140750 #if defined(SQLITE_ENABLE_FTS4_UNICODE61)
140751 #if defined(SQLITE_ENABLE_FTS3) || defined(SQLITE_ENABLE_FTS4)
140752 
140753 /* #include <assert.h> */
140754 
140755 /*
140756 ** Return true if the argument corresponds to a unicode codepoint
140757 ** classified as either a letter or a number. Otherwise false.
140758 **
140759 ** The results are undefined if the value passed to this function
140760 ** is less than zero.
140761 */
140762 SQLITE_PRIVATE int sqlite3FtsUnicodeIsalnum(int c){
140763   /* Each unsigned integer in the following array corresponds to a contiguous
140764   ** range of unicode codepoints that are not either letters or numbers (i.e.
140765   ** codepoints for which this function should return 0).
140766   **
140767   ** The most significant 22 bits in each 32-bit value contain the first 
140768   ** codepoint in the range. The least significant 10 bits are used to store
140769   ** the size of the range (always at least 1). In other words, the value 
140770   ** ((C<<22) + N) represents a range of N codepoints starting with codepoint 
140771   ** C. It is not possible to represent a range larger than 1023 codepoints 
140772   ** using this format.
140773   */
140774   const static unsigned int aEntry[] = {
140775     0x00000030, 0x0000E807, 0x00016C06, 0x0001EC2F, 0x0002AC07,
140776     0x0002D001, 0x0002D803, 0x0002EC01, 0x0002FC01, 0x00035C01,
140777     0x0003DC01, 0x000B0804, 0x000B480E, 0x000B9407, 0x000BB401,
140778     0x000BBC81, 0x000DD401, 0x000DF801, 0x000E1002, 0x000E1C01,
140779     0x000FD801, 0x00120808, 0x00156806, 0x00162402, 0x00163C01,
140780     0x00164437, 0x0017CC02, 0x00180005, 0x00181816, 0x00187802,
140781     0x00192C15, 0x0019A804, 0x0019C001, 0x001B5001, 0x001B580F,
140782     0x001B9C07, 0x001BF402, 0x001C000E, 0x001C3C01, 0x001C4401,
140783     0x001CC01B, 0x001E980B, 0x001FAC09, 0x001FD804, 0x00205804,
140784     0x00206C09, 0x00209403, 0x0020A405, 0x0020C00F, 0x00216403,
140785     0x00217801, 0x0023901B, 0x00240004, 0x0024E803, 0x0024F812,
140786     0x00254407, 0x00258804, 0x0025C001, 0x00260403, 0x0026F001,
140787     0x0026F807, 0x00271C02, 0x00272C03, 0x00275C01, 0x00278802,
140788     0x0027C802, 0x0027E802, 0x00280403, 0x0028F001, 0x0028F805,
140789     0x00291C02, 0x00292C03, 0x00294401, 0x0029C002, 0x0029D401,
140790     0x002A0403, 0x002AF001, 0x002AF808, 0x002B1C03, 0x002B2C03,
140791     0x002B8802, 0x002BC002, 0x002C0403, 0x002CF001, 0x002CF807,
140792     0x002D1C02, 0x002D2C03, 0x002D5802, 0x002D8802, 0x002DC001,
140793     0x002E0801, 0x002EF805, 0x002F1803, 0x002F2804, 0x002F5C01,
140794     0x002FCC08, 0x00300403, 0x0030F807, 0x00311803, 0x00312804,
140795     0x00315402, 0x00318802, 0x0031FC01, 0x00320802, 0x0032F001,
140796     0x0032F807, 0x00331803, 0x00332804, 0x00335402, 0x00338802,
140797     0x00340802, 0x0034F807, 0x00351803, 0x00352804, 0x00355C01,
140798     0x00358802, 0x0035E401, 0x00360802, 0x00372801, 0x00373C06,
140799     0x00375801, 0x00376008, 0x0037C803, 0x0038C401, 0x0038D007,
140800     0x0038FC01, 0x00391C09, 0x00396802, 0x003AC401, 0x003AD006,
140801     0x003AEC02, 0x003B2006, 0x003C041F, 0x003CD00C, 0x003DC417,
140802     0x003E340B, 0x003E6424, 0x003EF80F, 0x003F380D, 0x0040AC14,
140803     0x00412806, 0x00415804, 0x00417803, 0x00418803, 0x00419C07,
140804     0x0041C404, 0x0042080C, 0x00423C01, 0x00426806, 0x0043EC01,
140805     0x004D740C, 0x004E400A, 0x00500001, 0x0059B402, 0x005A0001,
140806     0x005A6C02, 0x005BAC03, 0x005C4803, 0x005CC805, 0x005D4802,
140807     0x005DC802, 0x005ED023, 0x005F6004, 0x005F7401, 0x0060000F,
140808     0x0062A401, 0x0064800C, 0x0064C00C, 0x00650001, 0x00651002,
140809     0x0066C011, 0x00672002, 0x00677822, 0x00685C05, 0x00687802,
140810     0x0069540A, 0x0069801D, 0x0069FC01, 0x006A8007, 0x006AA006,
140811     0x006C0005, 0x006CD011, 0x006D6823, 0x006E0003, 0x006E840D,
140812     0x006F980E, 0x006FF004, 0x00709014, 0x0070EC05, 0x0071F802,
140813     0x00730008, 0x00734019, 0x0073B401, 0x0073C803, 0x00770027,
140814     0x0077F004, 0x007EF401, 0x007EFC03, 0x007F3403, 0x007F7403,
140815     0x007FB403, 0x007FF402, 0x00800065, 0x0081A806, 0x0081E805,
140816     0x00822805, 0x0082801A, 0x00834021, 0x00840002, 0x00840C04,
140817     0x00842002, 0x00845001, 0x00845803, 0x00847806, 0x00849401,
140818     0x00849C01, 0x0084A401, 0x0084B801, 0x0084E802, 0x00850005,
140819     0x00852804, 0x00853C01, 0x00864264, 0x00900027, 0x0091000B,
140820     0x0092704E, 0x00940200, 0x009C0475, 0x009E53B9, 0x00AD400A,
140821     0x00B39406, 0x00B3BC03, 0x00B3E404, 0x00B3F802, 0x00B5C001,
140822     0x00B5FC01, 0x00B7804F, 0x00B8C00C, 0x00BA001A, 0x00BA6C59,
140823     0x00BC00D6, 0x00BFC00C, 0x00C00005, 0x00C02019, 0x00C0A807,
140824     0x00C0D802, 0x00C0F403, 0x00C26404, 0x00C28001, 0x00C3EC01,
140825     0x00C64002, 0x00C6580A, 0x00C70024, 0x00C8001F, 0x00C8A81E,
140826     0x00C94001, 0x00C98020, 0x00CA2827, 0x00CB003F, 0x00CC0100,
140827     0x01370040, 0x02924037, 0x0293F802, 0x02983403, 0x0299BC10,
140828     0x029A7C01, 0x029BC008, 0x029C0017, 0x029C8002, 0x029E2402,
140829     0x02A00801, 0x02A01801, 0x02A02C01, 0x02A08C09, 0x02A0D804,
140830     0x02A1D004, 0x02A20002, 0x02A2D011, 0x02A33802, 0x02A38012,
140831     0x02A3E003, 0x02A4980A, 0x02A51C0D, 0x02A57C01, 0x02A60004,
140832     0x02A6CC1B, 0x02A77802, 0x02A8A40E, 0x02A90C01, 0x02A93002,
140833     0x02A97004, 0x02A9DC03, 0x02A9EC01, 0x02AAC001, 0x02AAC803,
140834     0x02AADC02, 0x02AAF802, 0x02AB0401, 0x02AB7802, 0x02ABAC07,
140835     0x02ABD402, 0x02AF8C0B, 0x03600001, 0x036DFC02, 0x036FFC02,
140836     0x037FFC01, 0x03EC7801, 0x03ECA401, 0x03EEC810, 0x03F4F802,
140837     0x03F7F002, 0x03F8001A, 0x03F88007, 0x03F8C023, 0x03F95013,
140838     0x03F9A004, 0x03FBFC01, 0x03FC040F, 0x03FC6807, 0x03FCEC06,
140839     0x03FD6C0B, 0x03FF8007, 0x03FFA007, 0x03FFE405, 0x04040003,
140840     0x0404DC09, 0x0405E411, 0x0406400C, 0x0407402E, 0x040E7C01,
140841     0x040F4001, 0x04215C01, 0x04247C01, 0x0424FC01, 0x04280403,
140842     0x04281402, 0x04283004, 0x0428E003, 0x0428FC01, 0x04294009,
140843     0x0429FC01, 0x042CE407, 0x04400003, 0x0440E016, 0x04420003,
140844     0x0442C012, 0x04440003, 0x04449C0E, 0x04450004, 0x04460003,
140845     0x0446CC0E, 0x04471404, 0x045AAC0D, 0x0491C004, 0x05BD442E,
140846     0x05BE3C04, 0x074000F6, 0x07440027, 0x0744A4B5, 0x07480046,
140847     0x074C0057, 0x075B0401, 0x075B6C01, 0x075BEC01, 0x075C5401,
140848     0x075CD401, 0x075D3C01, 0x075DBC01, 0x075E2401, 0x075EA401,
140849     0x075F0C01, 0x07BBC002, 0x07C0002C, 0x07C0C064, 0x07C2800F,
140850     0x07C2C40E, 0x07C3040F, 0x07C3440F, 0x07C4401F, 0x07C4C03C,
140851     0x07C5C02B, 0x07C7981D, 0x07C8402B, 0x07C90009, 0x07C94002,
140852     0x07CC0021, 0x07CCC006, 0x07CCDC46, 0x07CE0014, 0x07CE8025,
140853     0x07CF1805, 0x07CF8011, 0x07D0003F, 0x07D10001, 0x07D108B6,
140854     0x07D3E404, 0x07D4003E, 0x07D50004, 0x07D54018, 0x07D7EC46,
140855     0x07D9140B, 0x07DA0046, 0x07DC0074, 0x38000401, 0x38008060,
140856     0x380400F0,
140857   };
140858   static const unsigned int aAscii[4] = {
140859     0xFFFFFFFF, 0xFC00FFFF, 0xF8000001, 0xF8000001,
140860   };
140861 
140862   if( c<128 ){
140863     return ( (aAscii[c >> 5] & (1 << (c & 0x001F)))==0 );
140864   }else if( c<(1<<22) ){
140865     unsigned int key = (((unsigned int)c)<<10) | 0x000003FF;
140866     int iRes;
140867     int iHi = sizeof(aEntry)/sizeof(aEntry[0]) - 1;
140868     int iLo = 0;
140869     while( iHi>=iLo ){
140870       int iTest = (iHi + iLo) / 2;
140871       if( key >= aEntry[iTest] ){
140872         iRes = iTest;
140873         iLo = iTest+1;
140874       }else{
140875         iHi = iTest-1;
140876       }
140877     }
140878     assert( aEntry[0]<key );
140879     assert( key>=aEntry[iRes] );
140880     return (((unsigned int)c) >= ((aEntry[iRes]>>10) + (aEntry[iRes]&0x3FF)));
140881   }
140882   return 1;
140883 }
140884 
140885 
140886 /*
140887 ** If the argument is a codepoint corresponding to a lowercase letter
140888 ** in the ASCII range with a diacritic added, return the codepoint
140889 ** of the ASCII letter only. For example, if passed 235 - "LATIN
140890 ** SMALL LETTER E WITH DIAERESIS" - return 65 ("LATIN SMALL LETTER
140891 ** E"). The resuls of passing a codepoint that corresponds to an
140892 ** uppercase letter are undefined.
140893 */
140894 static int remove_diacritic(int c){
140895   unsigned short aDia[] = {
140896         0,  1797,  1848,  1859,  1891,  1928,  1940,  1995, 
140897      2024,  2040,  2060,  2110,  2168,  2206,  2264,  2286, 
140898      2344,  2383,  2472,  2488,  2516,  2596,  2668,  2732, 
140899      2782,  2842,  2894,  2954,  2984,  3000,  3028,  3336, 
140900      3456,  3696,  3712,  3728,  3744,  3896,  3912,  3928, 
140901      3968,  4008,  4040,  4106,  4138,  4170,  4202,  4234, 
140902      4266,  4296,  4312,  4344,  4408,  4424,  4472,  4504, 
140903      6148,  6198,  6264,  6280,  6360,  6429,  6505,  6529, 
140904     61448, 61468, 61534, 61592, 61642, 61688, 61704, 61726, 
140905     61784, 61800, 61836, 61880, 61914, 61948, 61998, 62122, 
140906     62154, 62200, 62218, 62302, 62364, 62442, 62478, 62536, 
140907     62554, 62584, 62604, 62640, 62648, 62656, 62664, 62730, 
140908     62924, 63050, 63082, 63274, 63390, 
140909   };
140910   char aChar[] = {
140911     '\0', 'a',  'c',  'e',  'i',  'n',  'o',  'u',  'y',  'y',  'a',  'c',  
140912     'd',  'e',  'e',  'g',  'h',  'i',  'j',  'k',  'l',  'n',  'o',  'r',  
140913     's',  't',  'u',  'u',  'w',  'y',  'z',  'o',  'u',  'a',  'i',  'o',  
140914     'u',  'g',  'k',  'o',  'j',  'g',  'n',  'a',  'e',  'i',  'o',  'r',  
140915     'u',  's',  't',  'h',  'a',  'e',  'o',  'y',  '\0', '\0', '\0', '\0', 
140916     '\0', '\0', '\0', '\0', 'a',  'b',  'd',  'd',  'e',  'f',  'g',  'h',  
140917     'h',  'i',  'k',  'l',  'l',  'm',  'n',  'p',  'r',  'r',  's',  't',  
140918     'u',  'v',  'w',  'w',  'x',  'y',  'z',  'h',  't',  'w',  'y',  'a',  
140919     'e',  'i',  'o',  'u',  'y',  
140920   };
140921 
140922   unsigned int key = (((unsigned int)c)<<3) | 0x00000007;
140923   int iRes = 0;
140924   int iHi = sizeof(aDia)/sizeof(aDia[0]) - 1;
140925   int iLo = 0;
140926   while( iHi>=iLo ){
140927     int iTest = (iHi + iLo) / 2;
140928     if( key >= aDia[iTest] ){
140929       iRes = iTest;
140930       iLo = iTest+1;
140931     }else{
140932       iHi = iTest-1;
140933     }
140934   }
140935   assert( key>=aDia[iRes] );
140936   return ((c > (aDia[iRes]>>3) + (aDia[iRes]&0x07)) ? c : (int)aChar[iRes]);
140937 };
140938 
140939 
140940 /*
140941 ** Return true if the argument interpreted as a unicode codepoint
140942 ** is a diacritical modifier character.
140943 */
140944 SQLITE_PRIVATE int sqlite3FtsUnicodeIsdiacritic(int c){
140945   unsigned int mask0 = 0x08029FDF;
140946   unsigned int mask1 = 0x000361F8;
140947   if( c<768 || c>817 ) return 0;
140948   return (c < 768+32) ?
140949       (mask0 & (1 << (c-768))) :
140950       (mask1 & (1 << (c-768-32)));
140951 }
140952 
140953 
140954 /*
140955 ** Interpret the argument as a unicode codepoint. If the codepoint
140956 ** is an upper case character that has a lower case equivalent,
140957 ** return the codepoint corresponding to the lower case version.
140958 ** Otherwise, return a copy of the argument.
140959 **
140960 ** The results are undefined if the value passed to this function
140961 ** is less than zero.
140962 */
140963 SQLITE_PRIVATE int sqlite3FtsUnicodeFold(int c, int bRemoveDiacritic){
140964   /* Each entry in the following array defines a rule for folding a range
140965   ** of codepoints to lower case. The rule applies to a range of nRange
140966   ** codepoints starting at codepoint iCode.
140967   **
140968   ** If the least significant bit in flags is clear, then the rule applies
140969   ** to all nRange codepoints (i.e. all nRange codepoints are upper case and
140970   ** need to be folded). Or, if it is set, then the rule only applies to
140971   ** every second codepoint in the range, starting with codepoint C.
140972   **
140973   ** The 7 most significant bits in flags are an index into the aiOff[]
140974   ** array. If a specific codepoint C does require folding, then its lower
140975   ** case equivalent is ((C + aiOff[flags>>1]) & 0xFFFF).
140976   **
140977   ** The contents of this array are generated by parsing the CaseFolding.txt
140978   ** file distributed as part of the "Unicode Character Database". See
140979   ** http://www.unicode.org for details.
140980   */
140981   static const struct TableEntry {
140982     unsigned short iCode;
140983     unsigned char flags;
140984     unsigned char nRange;
140985   } aEntry[] = {
140986     {65, 14, 26},          {181, 64, 1},          {192, 14, 23},
140987     {216, 14, 7},          {256, 1, 48},          {306, 1, 6},
140988     {313, 1, 16},          {330, 1, 46},          {376, 116, 1},
140989     {377, 1, 6},           {383, 104, 1},         {385, 50, 1},
140990     {386, 1, 4},           {390, 44, 1},          {391, 0, 1},
140991     {393, 42, 2},          {395, 0, 1},           {398, 32, 1},
140992     {399, 38, 1},          {400, 40, 1},          {401, 0, 1},
140993     {403, 42, 1},          {404, 46, 1},          {406, 52, 1},
140994     {407, 48, 1},          {408, 0, 1},           {412, 52, 1},
140995     {413, 54, 1},          {415, 56, 1},          {416, 1, 6},
140996     {422, 60, 1},          {423, 0, 1},           {425, 60, 1},
140997     {428, 0, 1},           {430, 60, 1},          {431, 0, 1},
140998     {433, 58, 2},          {435, 1, 4},           {439, 62, 1},
140999     {440, 0, 1},           {444, 0, 1},           {452, 2, 1},
141000     {453, 0, 1},           {455, 2, 1},           {456, 0, 1},
141001     {458, 2, 1},           {459, 1, 18},          {478, 1, 18},
141002     {497, 2, 1},           {498, 1, 4},           {502, 122, 1},
141003     {503, 134, 1},         {504, 1, 40},          {544, 110, 1},
141004     {546, 1, 18},          {570, 70, 1},          {571, 0, 1},
141005     {573, 108, 1},         {574, 68, 1},          {577, 0, 1},
141006     {579, 106, 1},         {580, 28, 1},          {581, 30, 1},
141007     {582, 1, 10},          {837, 36, 1},          {880, 1, 4},
141008     {886, 0, 1},           {902, 18, 1},          {904, 16, 3},
141009     {908, 26, 1},          {910, 24, 2},          {913, 14, 17},
141010     {931, 14, 9},          {962, 0, 1},           {975, 4, 1},
141011     {976, 140, 1},         {977, 142, 1},         {981, 146, 1},
141012     {982, 144, 1},         {984, 1, 24},          {1008, 136, 1},
141013     {1009, 138, 1},        {1012, 130, 1},        {1013, 128, 1},
141014     {1015, 0, 1},          {1017, 152, 1},        {1018, 0, 1},
141015     {1021, 110, 3},        {1024, 34, 16},        {1040, 14, 32},
141016     {1120, 1, 34},         {1162, 1, 54},         {1216, 6, 1},
141017     {1217, 1, 14},         {1232, 1, 88},         {1329, 22, 38},
141018     {4256, 66, 38},        {4295, 66, 1},         {4301, 66, 1},
141019     {7680, 1, 150},        {7835, 132, 1},        {7838, 96, 1},
141020     {7840, 1, 96},         {7944, 150, 8},        {7960, 150, 6},
141021     {7976, 150, 8},        {7992, 150, 8},        {8008, 150, 6},
141022     {8025, 151, 8},        {8040, 150, 8},        {8072, 150, 8},
141023     {8088, 150, 8},        {8104, 150, 8},        {8120, 150, 2},
141024     {8122, 126, 2},        {8124, 148, 1},        {8126, 100, 1},
141025     {8136, 124, 4},        {8140, 148, 1},        {8152, 150, 2},
141026     {8154, 120, 2},        {8168, 150, 2},        {8170, 118, 2},
141027     {8172, 152, 1},        {8184, 112, 2},        {8186, 114, 2},
141028     {8188, 148, 1},        {8486, 98, 1},         {8490, 92, 1},
141029     {8491, 94, 1},         {8498, 12, 1},         {8544, 8, 16},
141030     {8579, 0, 1},          {9398, 10, 26},        {11264, 22, 47},
141031     {11360, 0, 1},         {11362, 88, 1},        {11363, 102, 1},
141032     {11364, 90, 1},        {11367, 1, 6},         {11373, 84, 1},
141033     {11374, 86, 1},        {11375, 80, 1},        {11376, 82, 1},
141034     {11378, 0, 1},         {11381, 0, 1},         {11390, 78, 2},
141035     {11392, 1, 100},       {11499, 1, 4},         {11506, 0, 1},
141036     {42560, 1, 46},        {42624, 1, 24},        {42786, 1, 14},
141037     {42802, 1, 62},        {42873, 1, 4},         {42877, 76, 1},
141038     {42878, 1, 10},        {42891, 0, 1},         {42893, 74, 1},
141039     {42896, 1, 4},         {42912, 1, 10},        {42922, 72, 1},
141040     {65313, 14, 26},       
141041   };
141042   static const unsigned short aiOff[] = {
141043    1,     2,     8,     15,    16,    26,    28,    32,    
141044    37,    38,    40,    48,    63,    64,    69,    71,    
141045    79,    80,    116,   202,   203,   205,   206,   207,   
141046    209,   210,   211,   213,   214,   217,   218,   219,   
141047    775,   7264,  10792, 10795, 23228, 23256, 30204, 54721, 
141048    54753, 54754, 54756, 54787, 54793, 54809, 57153, 57274, 
141049    57921, 58019, 58363, 61722, 65268, 65341, 65373, 65406, 
141050    65408, 65410, 65415, 65424, 65436, 65439, 65450, 65462, 
141051    65472, 65476, 65478, 65480, 65482, 65488, 65506, 65511, 
141052    65514, 65521, 65527, 65528, 65529, 
141053   };
141054 
141055   int ret = c;
141056 
141057   assert( c>=0 );
141058   assert( sizeof(unsigned short)==2 && sizeof(unsigned char)==1 );
141059 
141060   if( c<128 ){
141061     if( c>='A' && c<='Z' ) ret = c + ('a' - 'A');
141062   }else if( c<65536 ){
141063     int iHi = sizeof(aEntry)/sizeof(aEntry[0]) - 1;
141064     int iLo = 0;
141065     int iRes = -1;
141066 
141067     while( iHi>=iLo ){
141068       int iTest = (iHi + iLo) / 2;
141069       int cmp = (c - aEntry[iTest].iCode);
141070       if( cmp>=0 ){
141071         iRes = iTest;
141072         iLo = iTest+1;
141073       }else{
141074         iHi = iTest-1;
141075       }
141076     }
141077     assert( iRes<0 || c>=aEntry[iRes].iCode );
141078 
141079     if( iRes>=0 ){
141080       const struct TableEntry *p = &aEntry[iRes];
141081       if( c<(p->iCode + p->nRange) && 0==(0x01 & p->flags & (p->iCode ^ c)) ){
141082         ret = (c + (aiOff[p->flags>>1])) & 0x0000FFFF;
141083         assert( ret>0 );
141084       }
141085     }
141086 
141087     if( bRemoveDiacritic ) ret = remove_diacritic(ret);
141088   }
141089   
141090   else if( c>=66560 && c<66600 ){
141091     ret = c + 40;
141092   }
141093 
141094   return ret;
141095 }
141096 #endif /* defined(SQLITE_ENABLE_FTS3) || defined(SQLITE_ENABLE_FTS4) */
141097 #endif /* !defined(SQLITE_ENABLE_FTS4_UNICODE61) */
141098 
141099 /************** End of fts3_unicode2.c ***************************************/
141100 /************** Begin file rtree.c *******************************************/
141101 /*
141102 ** 2001 September 15
141103 **
141104 ** The author disclaims copyright to this source code.  In place of
141105 ** a legal notice, here is a blessing:
141106 **
141107 **    May you do good and not evil.
141108 **    May you find forgiveness for yourself and forgive others.
141109 **    May you share freely, never taking more than you give.
141110 **
141111 *************************************************************************
141112 ** This file contains code for implementations of the r-tree and r*-tree
141113 ** algorithms packaged as an SQLite virtual table module.
141114 */
141115 
141116 /*
141117 ** Database Format of R-Tree Tables
141118 ** --------------------------------
141119 **
141120 ** The data structure for a single virtual r-tree table is stored in three 
141121 ** native SQLite tables declared as follows. In each case, the '%' character
141122 ** in the table name is replaced with the user-supplied name of the r-tree
141123 ** table.
141124 **
141125 **   CREATE TABLE %_node(nodeno INTEGER PRIMARY KEY, data BLOB)
141126 **   CREATE TABLE %_parent(nodeno INTEGER PRIMARY KEY, parentnode INTEGER)
141127 **   CREATE TABLE %_rowid(rowid INTEGER PRIMARY KEY, nodeno INTEGER)
141128 **
141129 ** The data for each node of the r-tree structure is stored in the %_node
141130 ** table. For each node that is not the root node of the r-tree, there is
141131 ** an entry in the %_parent table associating the node with its parent.
141132 ** And for each row of data in the table, there is an entry in the %_rowid
141133 ** table that maps from the entries rowid to the id of the node that it
141134 ** is stored on.
141135 **
141136 ** The root node of an r-tree always exists, even if the r-tree table is
141137 ** empty. The nodeno of the root node is always 1. All other nodes in the
141138 ** table must be the same size as the root node. The content of each node
141139 ** is formatted as follows:
141140 **
141141 **   1. If the node is the root node (node 1), then the first 2 bytes
141142 **      of the node contain the tree depth as a big-endian integer.
141143 **      For non-root nodes, the first 2 bytes are left unused.
141144 **
141145 **   2. The next 2 bytes contain the number of entries currently 
141146 **      stored in the node.
141147 **
141148 **   3. The remainder of the node contains the node entries. Each entry
141149 **      consists of a single 8-byte integer followed by an even number
141150 **      of 4-byte coordinates. For leaf nodes the integer is the rowid
141151 **      of a record. For internal nodes it is the node number of a
141152 **      child page.
141153 */
141154 
141155 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_RTREE)
141156 
141157 /*
141158 ** This file contains an implementation of a couple of different variants
141159 ** of the r-tree algorithm. See the README file for further details. The 
141160 ** same data-structure is used for all, but the algorithms for insert and
141161 ** delete operations vary. The variants used are selected at compile time 
141162 ** by defining the following symbols:
141163 */
141164 
141165 /* Either, both or none of the following may be set to activate 
141166 ** r*tree variant algorithms.
141167 */
141168 #define VARIANT_RSTARTREE_CHOOSESUBTREE 0
141169 #define VARIANT_RSTARTREE_REINSERT      1
141170 
141171 /* 
141172 ** Exactly one of the following must be set to 1.
141173 */
141174 #define VARIANT_GUTTMAN_QUADRATIC_SPLIT 0
141175 #define VARIANT_GUTTMAN_LINEAR_SPLIT    0
141176 #define VARIANT_RSTARTREE_SPLIT         1
141177 
141178 #define VARIANT_GUTTMAN_SPLIT \
141179         (VARIANT_GUTTMAN_LINEAR_SPLIT||VARIANT_GUTTMAN_QUADRATIC_SPLIT)
141180 
141181 #if VARIANT_GUTTMAN_QUADRATIC_SPLIT
141182   #define PickNext QuadraticPickNext
141183   #define PickSeeds QuadraticPickSeeds
141184   #define AssignCells splitNodeGuttman
141185 #endif
141186 #if VARIANT_GUTTMAN_LINEAR_SPLIT
141187   #define PickNext LinearPickNext
141188   #define PickSeeds LinearPickSeeds
141189   #define AssignCells splitNodeGuttman
141190 #endif
141191 #if VARIANT_RSTARTREE_SPLIT
141192   #define AssignCells splitNodeStartree
141193 #endif
141194 
141195 #if !defined(NDEBUG) && !defined(SQLITE_DEBUG) 
141196 # define NDEBUG 1
141197 #endif
141198 
141199 #ifndef SQLITE_CORE
141200   SQLITE_EXTENSION_INIT1
141201 #else
141202 #endif
141203 
141204 /* #include <string.h> */
141205 /* #include <assert.h> */
141206 
141207 #ifndef SQLITE_AMALGAMATION
141208 #include "sqlite3rtree.h"
141209 typedef sqlite3_int64 i64;
141210 typedef unsigned char u8;
141211 typedef unsigned int u32;
141212 #endif
141213 
141214 /*  The following macro is used to suppress compiler warnings.
141215 */
141216 #ifndef UNUSED_PARAMETER
141217 # define UNUSED_PARAMETER(x) (void)(x)
141218 #endif
141219 
141220 typedef struct Rtree Rtree;
141221 typedef struct RtreeCursor RtreeCursor;
141222 typedef struct RtreeNode RtreeNode;
141223 typedef struct RtreeCell RtreeCell;
141224 typedef struct RtreeConstraint RtreeConstraint;
141225 typedef struct RtreeMatchArg RtreeMatchArg;
141226 typedef struct RtreeGeomCallback RtreeGeomCallback;
141227 typedef union RtreeCoord RtreeCoord;
141228 
141229 /* The rtree may have between 1 and RTREE_MAX_DIMENSIONS dimensions. */
141230 #define RTREE_MAX_DIMENSIONS 5
141231 
141232 /* Size of hash table Rtree.aHash. This hash table is not expected to
141233 ** ever contain very many entries, so a fixed number of buckets is 
141234 ** used.
141235 */
141236 #define HASHSIZE 128
141237 
141238 /* The xBestIndex method of this virtual table requires an estimate of
141239 ** the number of rows in the virtual table to calculate the costs of
141240 ** various strategies. If possible, this estimate is loaded from the
141241 ** sqlite_stat1 table (with RTREE_MIN_ROWEST as a hard-coded minimum).
141242 ** Otherwise, if no sqlite_stat1 entry is available, use 
141243 ** RTREE_DEFAULT_ROWEST.
141244 */
141245 #define RTREE_DEFAULT_ROWEST 1048576
141246 #define RTREE_MIN_ROWEST         100
141247 
141248 /* 
141249 ** An rtree virtual-table object.
141250 */
141251 struct Rtree {
141252   sqlite3_vtab base;
141253   sqlite3 *db;                /* Host database connection */
141254   int iNodeSize;              /* Size in bytes of each node in the node table */
141255   int nDim;                   /* Number of dimensions */
141256   int nBytesPerCell;          /* Bytes consumed per cell */
141257   int iDepth;                 /* Current depth of the r-tree structure */
141258   char *zDb;                  /* Name of database containing r-tree table */
141259   char *zName;                /* Name of r-tree table */ 
141260   RtreeNode *aHash[HASHSIZE]; /* Hash table of in-memory nodes. */ 
141261   int nBusy;                  /* Current number of users of this structure */
141262   i64 nRowEst;                /* Estimated number of rows in this table */
141263 
141264   /* List of nodes removed during a CondenseTree operation. List is
141265   ** linked together via the pointer normally used for hash chains -
141266   ** RtreeNode.pNext. RtreeNode.iNode stores the depth of the sub-tree 
141267   ** headed by the node (leaf nodes have RtreeNode.iNode==0).
141268   */
141269   RtreeNode *pDeleted;
141270   int iReinsertHeight;        /* Height of sub-trees Reinsert() has run on */
141271 
141272   /* Statements to read/write/delete a record from xxx_node */
141273   sqlite3_stmt *pReadNode;
141274   sqlite3_stmt *pWriteNode;
141275   sqlite3_stmt *pDeleteNode;
141276 
141277   /* Statements to read/write/delete a record from xxx_rowid */
141278   sqlite3_stmt *pReadRowid;
141279   sqlite3_stmt *pWriteRowid;
141280   sqlite3_stmt *pDeleteRowid;
141281 
141282   /* Statements to read/write/delete a record from xxx_parent */
141283   sqlite3_stmt *pReadParent;
141284   sqlite3_stmt *pWriteParent;
141285   sqlite3_stmt *pDeleteParent;
141286 
141287   int eCoordType;
141288 };
141289 
141290 /* Possible values for eCoordType: */
141291 #define RTREE_COORD_REAL32 0
141292 #define RTREE_COORD_INT32  1
141293 
141294 /*
141295 ** If SQLITE_RTREE_INT_ONLY is defined, then this virtual table will
141296 ** only deal with integer coordinates.  No floating point operations
141297 ** will be done.
141298 */
141299 #ifdef SQLITE_RTREE_INT_ONLY
141300   typedef sqlite3_int64 RtreeDValue;       /* High accuracy coordinate */
141301   typedef int RtreeValue;                  /* Low accuracy coordinate */
141302 #else
141303   typedef double RtreeDValue;              /* High accuracy coordinate */
141304   typedef float RtreeValue;                /* Low accuracy coordinate */
141305 #endif
141306 
141307 /*
141308 ** The minimum number of cells allowed for a node is a third of the 
141309 ** maximum. In Gutman's notation:
141310 **
141311 **     m = M/3
141312 **
141313 ** If an R*-tree "Reinsert" operation is required, the same number of
141314 ** cells are removed from the overfull node and reinserted into the tree.
141315 */
141316 #define RTREE_MINCELLS(p) ((((p)->iNodeSize-4)/(p)->nBytesPerCell)/3)
141317 #define RTREE_REINSERT(p) RTREE_MINCELLS(p)
141318 #define RTREE_MAXCELLS 51
141319 
141320 /*
141321 ** The smallest possible node-size is (512-64)==448 bytes. And the largest
141322 ** supported cell size is 48 bytes (8 byte rowid + ten 4 byte coordinates).
141323 ** Therefore all non-root nodes must contain at least 3 entries. Since 
141324 ** 2^40 is greater than 2^64, an r-tree structure always has a depth of
141325 ** 40 or less.
141326 */
141327 #define RTREE_MAX_DEPTH 40
141328 
141329 /* 
141330 ** An rtree cursor object.
141331 */
141332 struct RtreeCursor {
141333   sqlite3_vtab_cursor base;
141334   RtreeNode *pNode;                 /* Node cursor is currently pointing at */
141335   int iCell;                        /* Index of current cell in pNode */
141336   int iStrategy;                    /* Copy of idxNum search parameter */
141337   int nConstraint;                  /* Number of entries in aConstraint */
141338   RtreeConstraint *aConstraint;     /* Search constraints. */
141339 };
141340 
141341 union RtreeCoord {
141342   RtreeValue f;
141343   int i;
141344 };
141345 
141346 /*
141347 ** The argument is an RtreeCoord. Return the value stored within the RtreeCoord
141348 ** formatted as a RtreeDValue (double or int64). This macro assumes that local
141349 ** variable pRtree points to the Rtree structure associated with the
141350 ** RtreeCoord.
141351 */
141352 #ifdef SQLITE_RTREE_INT_ONLY
141353 # define DCOORD(coord) ((RtreeDValue)coord.i)
141354 #else
141355 # define DCOORD(coord) (                           \
141356     (pRtree->eCoordType==RTREE_COORD_REAL32) ?      \
141357       ((double)coord.f) :                           \
141358       ((double)coord.i)                             \
141359   )
141360 #endif
141361 
141362 /*
141363 ** A search constraint.
141364 */
141365 struct RtreeConstraint {
141366   int iCoord;                     /* Index of constrained coordinate */
141367   int op;                         /* Constraining operation */
141368   RtreeDValue rValue;             /* Constraint value. */
141369   int (*xGeom)(sqlite3_rtree_geometry*, int, RtreeDValue*, int*);
141370   sqlite3_rtree_geometry *pGeom;  /* Constraint callback argument for a MATCH */
141371 };
141372 
141373 /* Possible values for RtreeConstraint.op */
141374 #define RTREE_EQ    0x41
141375 #define RTREE_LE    0x42
141376 #define RTREE_LT    0x43
141377 #define RTREE_GE    0x44
141378 #define RTREE_GT    0x45
141379 #define RTREE_MATCH 0x46
141380 
141381 /* 
141382 ** An rtree structure node.
141383 */
141384 struct RtreeNode {
141385   RtreeNode *pParent;               /* Parent node */
141386   i64 iNode;
141387   int nRef;
141388   int isDirty;
141389   u8 *zData;
141390   RtreeNode *pNext;                 /* Next node in this hash chain */
141391 };
141392 #define NCELL(pNode) readInt16(&(pNode)->zData[2])
141393 
141394 /* 
141395 ** Structure to store a deserialized rtree record.
141396 */
141397 struct RtreeCell {
141398   i64 iRowid;
141399   RtreeCoord aCoord[RTREE_MAX_DIMENSIONS*2];
141400 };
141401 
141402 
141403 /*
141404 ** Value for the first field of every RtreeMatchArg object. The MATCH
141405 ** operator tests that the first field of a blob operand matches this
141406 ** value to avoid operating on invalid blobs (which could cause a segfault).
141407 */
141408 #define RTREE_GEOMETRY_MAGIC 0x891245AB
141409 
141410 /*
141411 ** An instance of this structure must be supplied as a blob argument to
141412 ** the right-hand-side of an SQL MATCH operator used to constrain an
141413 ** r-tree query.
141414 */
141415 struct RtreeMatchArg {
141416   u32 magic;                      /* Always RTREE_GEOMETRY_MAGIC */
141417   int (*xGeom)(sqlite3_rtree_geometry *, int, RtreeDValue*, int *);
141418   void *pContext;
141419   int nParam;
141420   RtreeDValue aParam[1];
141421 };
141422 
141423 /*
141424 ** When a geometry callback is created (see sqlite3_rtree_geometry_callback),
141425 ** a single instance of the following structure is allocated. It is used
141426 ** as the context for the user-function created by by s_r_g_c(). The object
141427 ** is eventually deleted by the destructor mechanism provided by
141428 ** sqlite3_create_function_v2() (which is called by s_r_g_c() to create
141429 ** the geometry callback function).
141430 */
141431 struct RtreeGeomCallback {
141432   int (*xGeom)(sqlite3_rtree_geometry*, int, RtreeDValue*, int*);
141433   void *pContext;
141434 };
141435 
141436 #ifndef MAX
141437 # define MAX(x,y) ((x) < (y) ? (y) : (x))
141438 #endif
141439 #ifndef MIN
141440 # define MIN(x,y) ((x) > (y) ? (y) : (x))
141441 #endif
141442 
141443 /*
141444 ** Functions to deserialize a 16 bit integer, 32 bit real number and
141445 ** 64 bit integer. The deserialized value is returned.
141446 */
141447 static int readInt16(u8 *p){
141448   return (p[0]<<8) + p[1];
141449 }
141450 static void readCoord(u8 *p, RtreeCoord *pCoord){
141451   u32 i = (
141452     (((u32)p[0]) << 24) + 
141453     (((u32)p[1]) << 16) + 
141454     (((u32)p[2]) <<  8) + 
141455     (((u32)p[3]) <<  0)
141456   );
141457   *(u32 *)pCoord = i;
141458 }
141459 static i64 readInt64(u8 *p){
141460   return (
141461     (((i64)p[0]) << 56) + 
141462     (((i64)p[1]) << 48) + 
141463     (((i64)p[2]) << 40) + 
141464     (((i64)p[3]) << 32) + 
141465     (((i64)p[4]) << 24) + 
141466     (((i64)p[5]) << 16) + 
141467     (((i64)p[6]) <<  8) + 
141468     (((i64)p[7]) <<  0)
141469   );
141470 }
141471 
141472 /*
141473 ** Functions to serialize a 16 bit integer, 32 bit real number and
141474 ** 64 bit integer. The value returned is the number of bytes written
141475 ** to the argument buffer (always 2, 4 and 8 respectively).
141476 */
141477 static int writeInt16(u8 *p, int i){
141478   p[0] = (i>> 8)&0xFF;
141479   p[1] = (i>> 0)&0xFF;
141480   return 2;
141481 }
141482 static int writeCoord(u8 *p, RtreeCoord *pCoord){
141483   u32 i;
141484   assert( sizeof(RtreeCoord)==4 );
141485   assert( sizeof(u32)==4 );
141486   i = *(u32 *)pCoord;
141487   p[0] = (i>>24)&0xFF;
141488   p[1] = (i>>16)&0xFF;
141489   p[2] = (i>> 8)&0xFF;
141490   p[3] = (i>> 0)&0xFF;
141491   return 4;
141492 }
141493 static int writeInt64(u8 *p, i64 i){
141494   p[0] = (i>>56)&0xFF;
141495   p[1] = (i>>48)&0xFF;
141496   p[2] = (i>>40)&0xFF;
141497   p[3] = (i>>32)&0xFF;
141498   p[4] = (i>>24)&0xFF;
141499   p[5] = (i>>16)&0xFF;
141500   p[6] = (i>> 8)&0xFF;
141501   p[7] = (i>> 0)&0xFF;
141502   return 8;
141503 }
141504 
141505 /*
141506 ** Increment the reference count of node p.
141507 */
141508 static void nodeReference(RtreeNode *p){
141509   if( p ){
141510     p->nRef++;
141511   }
141512 }
141513 
141514 /*
141515 ** Clear the content of node p (set all bytes to 0x00).
141516 */
141517 static void nodeZero(Rtree *pRtree, RtreeNode *p){
141518   memset(&p->zData[2], 0, pRtree->iNodeSize-2);
141519   p->isDirty = 1;
141520 }
141521 
141522 /*
141523 ** Given a node number iNode, return the corresponding key to use
141524 ** in the Rtree.aHash table.
141525 */
141526 static int nodeHash(i64 iNode){
141527   return (
141528     (iNode>>56) ^ (iNode>>48) ^ (iNode>>40) ^ (iNode>>32) ^ 
141529     (iNode>>24) ^ (iNode>>16) ^ (iNode>> 8) ^ (iNode>> 0)
141530   ) % HASHSIZE;
141531 }
141532 
141533 /*
141534 ** Search the node hash table for node iNode. If found, return a pointer
141535 ** to it. Otherwise, return 0.
141536 */
141537 static RtreeNode *nodeHashLookup(Rtree *pRtree, i64 iNode){
141538   RtreeNode *p;
141539   for(p=pRtree->aHash[nodeHash(iNode)]; p && p->iNode!=iNode; p=p->pNext);
141540   return p;
141541 }
141542 
141543 /*
141544 ** Add node pNode to the node hash table.
141545 */
141546 static void nodeHashInsert(Rtree *pRtree, RtreeNode *pNode){
141547   int iHash;
141548   assert( pNode->pNext==0 );
141549   iHash = nodeHash(pNode->iNode);
141550   pNode->pNext = pRtree->aHash[iHash];
141551   pRtree->aHash[iHash] = pNode;
141552 }
141553 
141554 /*
141555 ** Remove node pNode from the node hash table.
141556 */
141557 static void nodeHashDelete(Rtree *pRtree, RtreeNode *pNode){
141558   RtreeNode **pp;
141559   if( pNode->iNode!=0 ){
141560     pp = &pRtree->aHash[nodeHash(pNode->iNode)];
141561     for( ; (*pp)!=pNode; pp = &(*pp)->pNext){ assert(*pp); }
141562     *pp = pNode->pNext;
141563     pNode->pNext = 0;
141564   }
141565 }
141566 
141567 /*
141568 ** Allocate and return new r-tree node. Initially, (RtreeNode.iNode==0),
141569 ** indicating that node has not yet been assigned a node number. It is
141570 ** assigned a node number when nodeWrite() is called to write the
141571 ** node contents out to the database.
141572 */
141573 static RtreeNode *nodeNew(Rtree *pRtree, RtreeNode *pParent){
141574   RtreeNode *pNode;
141575   pNode = (RtreeNode *)sqlite3_malloc(sizeof(RtreeNode) + pRtree->iNodeSize);
141576   if( pNode ){
141577     memset(pNode, 0, sizeof(RtreeNode) + pRtree->iNodeSize);
141578     pNode->zData = (u8 *)&pNode[1];
141579     pNode->nRef = 1;
141580     pNode->pParent = pParent;
141581     pNode->isDirty = 1;
141582     nodeReference(pParent);
141583   }
141584   return pNode;
141585 }
141586 
141587 /*
141588 ** Obtain a reference to an r-tree node.
141589 */
141590 static int
141591 nodeAcquire(
141592   Rtree *pRtree,             /* R-tree structure */
141593   i64 iNode,                 /* Node number to load */
141594   RtreeNode *pParent,        /* Either the parent node or NULL */
141595   RtreeNode **ppNode         /* OUT: Acquired node */
141596 ){
141597   int rc;
141598   int rc2 = SQLITE_OK;
141599   RtreeNode *pNode;
141600 
141601   /* Check if the requested node is already in the hash table. If so,
141602   ** increase its reference count and return it.
141603   */
141604   if( (pNode = nodeHashLookup(pRtree, iNode)) ){
141605     assert( !pParent || !pNode->pParent || pNode->pParent==pParent );
141606     if( pParent && !pNode->pParent ){
141607       nodeReference(pParent);
141608       pNode->pParent = pParent;
141609     }
141610     pNode->nRef++;
141611     *ppNode = pNode;
141612     return SQLITE_OK;
141613   }
141614 
141615   sqlite3_bind_int64(pRtree->pReadNode, 1, iNode);
141616   rc = sqlite3_step(pRtree->pReadNode);
141617   if( rc==SQLITE_ROW ){
141618     const u8 *zBlob = sqlite3_column_blob(pRtree->pReadNode, 0);
141619     if( pRtree->iNodeSize==sqlite3_column_bytes(pRtree->pReadNode, 0) ){
141620       pNode = (RtreeNode *)sqlite3_malloc(sizeof(RtreeNode)+pRtree->iNodeSize);
141621       if( !pNode ){
141622         rc2 = SQLITE_NOMEM;
141623       }else{
141624         pNode->pParent = pParent;
141625         pNode->zData = (u8 *)&pNode[1];
141626         pNode->nRef = 1;
141627         pNode->iNode = iNode;
141628         pNode->isDirty = 0;
141629         pNode->pNext = 0;
141630         memcpy(pNode->zData, zBlob, pRtree->iNodeSize);
141631         nodeReference(pParent);
141632       }
141633     }
141634   }
141635   rc = sqlite3_reset(pRtree->pReadNode);
141636   if( rc==SQLITE_OK ) rc = rc2;
141637 
141638   /* If the root node was just loaded, set pRtree->iDepth to the height
141639   ** of the r-tree structure. A height of zero means all data is stored on
141640   ** the root node. A height of one means the children of the root node
141641   ** are the leaves, and so on. If the depth as specified on the root node
141642   ** is greater than RTREE_MAX_DEPTH, the r-tree structure must be corrupt.
141643   */
141644   if( pNode && iNode==1 ){
141645     pRtree->iDepth = readInt16(pNode->zData);
141646     if( pRtree->iDepth>RTREE_MAX_DEPTH ){
141647       rc = SQLITE_CORRUPT_VTAB;
141648     }
141649   }
141650 
141651   /* If no error has occurred so far, check if the "number of entries"
141652   ** field on the node is too large. If so, set the return code to 
141653   ** SQLITE_CORRUPT_VTAB.
141654   */
141655   if( pNode && rc==SQLITE_OK ){
141656     if( NCELL(pNode)>((pRtree->iNodeSize-4)/pRtree->nBytesPerCell) ){
141657       rc = SQLITE_CORRUPT_VTAB;
141658     }
141659   }
141660 
141661   if( rc==SQLITE_OK ){
141662     if( pNode!=0 ){
141663       nodeHashInsert(pRtree, pNode);
141664     }else{
141665       rc = SQLITE_CORRUPT_VTAB;
141666     }
141667     *ppNode = pNode;
141668   }else{
141669     sqlite3_free(pNode);
141670     *ppNode = 0;
141671   }
141672 
141673   return rc;
141674 }
141675 
141676 /*
141677 ** Overwrite cell iCell of node pNode with the contents of pCell.
141678 */
141679 static void nodeOverwriteCell(
141680   Rtree *pRtree, 
141681   RtreeNode *pNode,  
141682   RtreeCell *pCell, 
141683   int iCell
141684 ){
141685   int ii;
141686   u8 *p = &pNode->zData[4 + pRtree->nBytesPerCell*iCell];
141687   p += writeInt64(p, pCell->iRowid);
141688   for(ii=0; ii<(pRtree->nDim*2); ii++){
141689     p += writeCoord(p, &pCell->aCoord[ii]);
141690   }
141691   pNode->isDirty = 1;
141692 }
141693 
141694 /*
141695 ** Remove cell the cell with index iCell from node pNode.
141696 */
141697 static void nodeDeleteCell(Rtree *pRtree, RtreeNode *pNode, int iCell){
141698   u8 *pDst = &pNode->zData[4 + pRtree->nBytesPerCell*iCell];
141699   u8 *pSrc = &pDst[pRtree->nBytesPerCell];
141700   int nByte = (NCELL(pNode) - iCell - 1) * pRtree->nBytesPerCell;
141701   memmove(pDst, pSrc, nByte);
141702   writeInt16(&pNode->zData[2], NCELL(pNode)-1);
141703   pNode->isDirty = 1;
141704 }
141705 
141706 /*
141707 ** Insert the contents of cell pCell into node pNode. If the insert
141708 ** is successful, return SQLITE_OK.
141709 **
141710 ** If there is not enough free space in pNode, return SQLITE_FULL.
141711 */
141712 static int
141713 nodeInsertCell(
141714   Rtree *pRtree, 
141715   RtreeNode *pNode, 
141716   RtreeCell *pCell 
141717 ){
141718   int nCell;                    /* Current number of cells in pNode */
141719   int nMaxCell;                 /* Maximum number of cells for pNode */
141720 
141721   nMaxCell = (pRtree->iNodeSize-4)/pRtree->nBytesPerCell;
141722   nCell = NCELL(pNode);
141723 
141724   assert( nCell<=nMaxCell );
141725   if( nCell<nMaxCell ){
141726     nodeOverwriteCell(pRtree, pNode, pCell, nCell);
141727     writeInt16(&pNode->zData[2], nCell+1);
141728     pNode->isDirty = 1;
141729   }
141730 
141731   return (nCell==nMaxCell);
141732 }
141733 
141734 /*
141735 ** If the node is dirty, write it out to the database.
141736 */
141737 static int
141738 nodeWrite(Rtree *pRtree, RtreeNode *pNode){
141739   int rc = SQLITE_OK;
141740   if( pNode->isDirty ){
141741     sqlite3_stmt *p = pRtree->pWriteNode;
141742     if( pNode->iNode ){
141743       sqlite3_bind_int64(p, 1, pNode->iNode);
141744     }else{
141745       sqlite3_bind_null(p, 1);
141746     }
141747     sqlite3_bind_blob(p, 2, pNode->zData, pRtree->iNodeSize, SQLITE_STATIC);
141748     sqlite3_step(p);
141749     pNode->isDirty = 0;
141750     rc = sqlite3_reset(p);
141751     if( pNode->iNode==0 && rc==SQLITE_OK ){
141752       pNode->iNode = sqlite3_last_insert_rowid(pRtree->db);
141753       nodeHashInsert(pRtree, pNode);
141754     }
141755   }
141756   return rc;
141757 }
141758 
141759 /*
141760 ** Release a reference to a node. If the node is dirty and the reference
141761 ** count drops to zero, the node data is written to the database.
141762 */
141763 static int
141764 nodeRelease(Rtree *pRtree, RtreeNode *pNode){
141765   int rc = SQLITE_OK;
141766   if( pNode ){
141767     assert( pNode->nRef>0 );
141768     pNode->nRef--;
141769     if( pNode->nRef==0 ){
141770       if( pNode->iNode==1 ){
141771         pRtree->iDepth = -1;
141772       }
141773       if( pNode->pParent ){
141774         rc = nodeRelease(pRtree, pNode->pParent);
141775       }
141776       if( rc==SQLITE_OK ){
141777         rc = nodeWrite(pRtree, pNode);
141778       }
141779       nodeHashDelete(pRtree, pNode);
141780       sqlite3_free(pNode);
141781     }
141782   }
141783   return rc;
141784 }
141785 
141786 /*
141787 ** Return the 64-bit integer value associated with cell iCell of
141788 ** node pNode. If pNode is a leaf node, this is a rowid. If it is
141789 ** an internal node, then the 64-bit integer is a child page number.
141790 */
141791 static i64 nodeGetRowid(
141792   Rtree *pRtree, 
141793   RtreeNode *pNode, 
141794   int iCell
141795 ){
141796   assert( iCell<NCELL(pNode) );
141797   return readInt64(&pNode->zData[4 + pRtree->nBytesPerCell*iCell]);
141798 }
141799 
141800 /*
141801 ** Return coordinate iCoord from cell iCell in node pNode.
141802 */
141803 static void nodeGetCoord(
141804   Rtree *pRtree, 
141805   RtreeNode *pNode, 
141806   int iCell,
141807   int iCoord,
141808   RtreeCoord *pCoord           /* Space to write result to */
141809 ){
141810   readCoord(&pNode->zData[12 + pRtree->nBytesPerCell*iCell + 4*iCoord], pCoord);
141811 }
141812 
141813 /*
141814 ** Deserialize cell iCell of node pNode. Populate the structure pointed
141815 ** to by pCell with the results.
141816 */
141817 static void nodeGetCell(
141818   Rtree *pRtree, 
141819   RtreeNode *pNode, 
141820   int iCell,
141821   RtreeCell *pCell
141822 ){
141823   int ii;
141824   pCell->iRowid = nodeGetRowid(pRtree, pNode, iCell);
141825   for(ii=0; ii<pRtree->nDim*2; ii++){
141826     nodeGetCoord(pRtree, pNode, iCell, ii, &pCell->aCoord[ii]);
141827   }
141828 }
141829 
141830 
141831 /* Forward declaration for the function that does the work of
141832 ** the virtual table module xCreate() and xConnect() methods.
141833 */
141834 static int rtreeInit(
141835   sqlite3 *, void *, int, const char *const*, sqlite3_vtab **, char **, int
141836 );
141837 
141838 /* 
141839 ** Rtree virtual table module xCreate method.
141840 */
141841 static int rtreeCreate(
141842   sqlite3 *db,
141843   void *pAux,
141844   int argc, const char *const*argv,
141845   sqlite3_vtab **ppVtab,
141846   char **pzErr
141847 ){
141848   return rtreeInit(db, pAux, argc, argv, ppVtab, pzErr, 1);
141849 }
141850 
141851 /* 
141852 ** Rtree virtual table module xConnect method.
141853 */
141854 static int rtreeConnect(
141855   sqlite3 *db,
141856   void *pAux,
141857   int argc, const char *const*argv,
141858   sqlite3_vtab **ppVtab,
141859   char **pzErr
141860 ){
141861   return rtreeInit(db, pAux, argc, argv, ppVtab, pzErr, 0);
141862 }
141863 
141864 /*
141865 ** Increment the r-tree reference count.
141866 */
141867 static void rtreeReference(Rtree *pRtree){
141868   pRtree->nBusy++;
141869 }
141870 
141871 /*
141872 ** Decrement the r-tree reference count. When the reference count reaches
141873 ** zero the structure is deleted.
141874 */
141875 static void rtreeRelease(Rtree *pRtree){
141876   pRtree->nBusy--;
141877   if( pRtree->nBusy==0 ){
141878     sqlite3_finalize(pRtree->pReadNode);
141879     sqlite3_finalize(pRtree->pWriteNode);
141880     sqlite3_finalize(pRtree->pDeleteNode);
141881     sqlite3_finalize(pRtree->pReadRowid);
141882     sqlite3_finalize(pRtree->pWriteRowid);
141883     sqlite3_finalize(pRtree->pDeleteRowid);
141884     sqlite3_finalize(pRtree->pReadParent);
141885     sqlite3_finalize(pRtree->pWriteParent);
141886     sqlite3_finalize(pRtree->pDeleteParent);
141887     sqlite3_free(pRtree);
141888   }
141889 }
141890 
141891 /* 
141892 ** Rtree virtual table module xDisconnect method.
141893 */
141894 static int rtreeDisconnect(sqlite3_vtab *pVtab){
141895   rtreeRelease((Rtree *)pVtab);
141896   return SQLITE_OK;
141897 }
141898 
141899 /* 
141900 ** Rtree virtual table module xDestroy method.
141901 */
141902 static int rtreeDestroy(sqlite3_vtab *pVtab){
141903   Rtree *pRtree = (Rtree *)pVtab;
141904   int rc;
141905   char *zCreate = sqlite3_mprintf(
141906     "DROP TABLE '%q'.'%q_node';"
141907     "DROP TABLE '%q'.'%q_rowid';"
141908     "DROP TABLE '%q'.'%q_parent';",
141909     pRtree->zDb, pRtree->zName, 
141910     pRtree->zDb, pRtree->zName,
141911     pRtree->zDb, pRtree->zName
141912   );
141913   if( !zCreate ){
141914     rc = SQLITE_NOMEM;
141915   }else{
141916     rc = sqlite3_exec(pRtree->db, zCreate, 0, 0, 0);
141917     sqlite3_free(zCreate);
141918   }
141919   if( rc==SQLITE_OK ){
141920     rtreeRelease(pRtree);
141921   }
141922 
141923   return rc;
141924 }
141925 
141926 /* 
141927 ** Rtree virtual table module xOpen method.
141928 */
141929 static int rtreeOpen(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor){
141930   int rc = SQLITE_NOMEM;
141931   RtreeCursor *pCsr;
141932 
141933   pCsr = (RtreeCursor *)sqlite3_malloc(sizeof(RtreeCursor));
141934   if( pCsr ){
141935     memset(pCsr, 0, sizeof(RtreeCursor));
141936     pCsr->base.pVtab = pVTab;
141937     rc = SQLITE_OK;
141938   }
141939   *ppCursor = (sqlite3_vtab_cursor *)pCsr;
141940 
141941   return rc;
141942 }
141943 
141944 
141945 /*
141946 ** Free the RtreeCursor.aConstraint[] array and its contents.
141947 */
141948 static void freeCursorConstraints(RtreeCursor *pCsr){
141949   if( pCsr->aConstraint ){
141950     int i;                        /* Used to iterate through constraint array */
141951     for(i=0; i<pCsr->nConstraint; i++){
141952       sqlite3_rtree_geometry *pGeom = pCsr->aConstraint[i].pGeom;
141953       if( pGeom ){
141954         if( pGeom->xDelUser ) pGeom->xDelUser(pGeom->pUser);
141955         sqlite3_free(pGeom);
141956       }
141957     }
141958     sqlite3_free(pCsr->aConstraint);
141959     pCsr->aConstraint = 0;
141960   }
141961 }
141962 
141963 /* 
141964 ** Rtree virtual table module xClose method.
141965 */
141966 static int rtreeClose(sqlite3_vtab_cursor *cur){
141967   Rtree *pRtree = (Rtree *)(cur->pVtab);
141968   int rc;
141969   RtreeCursor *pCsr = (RtreeCursor *)cur;
141970   freeCursorConstraints(pCsr);
141971   rc = nodeRelease(pRtree, pCsr->pNode);
141972   sqlite3_free(pCsr);
141973   return rc;
141974 }
141975 
141976 /*
141977 ** Rtree virtual table module xEof method.
141978 **
141979 ** Return non-zero if the cursor does not currently point to a valid 
141980 ** record (i.e if the scan has finished), or zero otherwise.
141981 */
141982 static int rtreeEof(sqlite3_vtab_cursor *cur){
141983   RtreeCursor *pCsr = (RtreeCursor *)cur;
141984   return (pCsr->pNode==0);
141985 }
141986 
141987 /*
141988 ** The r-tree constraint passed as the second argument to this function is
141989 ** guaranteed to be a MATCH constraint.
141990 */
141991 static int testRtreeGeom(
141992   Rtree *pRtree,                  /* R-Tree object */
141993   RtreeConstraint *pConstraint,   /* MATCH constraint to test */
141994   RtreeCell *pCell,               /* Cell to test */
141995   int *pbRes                      /* OUT: Test result */
141996 ){
141997   int i;
141998   RtreeDValue aCoord[RTREE_MAX_DIMENSIONS*2];
141999   int nCoord = pRtree->nDim*2;
142000 
142001   assert( pConstraint->op==RTREE_MATCH );
142002   assert( pConstraint->pGeom );
142003 
142004   for(i=0; i<nCoord; i++){
142005     aCoord[i] = DCOORD(pCell->aCoord[i]);
142006   }
142007   return pConstraint->xGeom(pConstraint->pGeom, nCoord, aCoord, pbRes);
142008 }
142009 
142010 /* 
142011 ** Cursor pCursor currently points to a cell in a non-leaf page.
142012 ** Set *pbEof to true if the sub-tree headed by the cell is filtered
142013 ** (excluded) by the constraints in the pCursor->aConstraint[] 
142014 ** array, or false otherwise.
142015 **
142016 ** Return SQLITE_OK if successful or an SQLite error code if an error
142017 ** occurs within a geometry callback.
142018 */
142019 static int testRtreeCell(Rtree *pRtree, RtreeCursor *pCursor, int *pbEof){
142020   RtreeCell cell;
142021   int ii;
142022   int bRes = 0;
142023   int rc = SQLITE_OK;
142024 
142025   nodeGetCell(pRtree, pCursor->pNode, pCursor->iCell, &cell);
142026   for(ii=0; bRes==0 && ii<pCursor->nConstraint; ii++){
142027     RtreeConstraint *p = &pCursor->aConstraint[ii];
142028     RtreeDValue cell_min = DCOORD(cell.aCoord[(p->iCoord>>1)*2]);
142029     RtreeDValue cell_max = DCOORD(cell.aCoord[(p->iCoord>>1)*2+1]);
142030 
142031     assert(p->op==RTREE_LE || p->op==RTREE_LT || p->op==RTREE_GE 
142032         || p->op==RTREE_GT || p->op==RTREE_EQ || p->op==RTREE_MATCH
142033     );
142034 
142035     switch( p->op ){
142036       case RTREE_LE: case RTREE_LT: 
142037         bRes = p->rValue<cell_min; 
142038         break;
142039 
142040       case RTREE_GE: case RTREE_GT: 
142041         bRes = p->rValue>cell_max; 
142042         break;
142043 
142044       case RTREE_EQ:
142045         bRes = (p->rValue>cell_max || p->rValue<cell_min);
142046         break;
142047 
142048       default: {
142049         assert( p->op==RTREE_MATCH );
142050         rc = testRtreeGeom(pRtree, p, &cell, &bRes);
142051         bRes = !bRes;
142052         break;
142053       }
142054     }
142055   }
142056 
142057   *pbEof = bRes;
142058   return rc;
142059 }
142060 
142061 /* 
142062 ** Test if the cell that cursor pCursor currently points to
142063 ** would be filtered (excluded) by the constraints in the 
142064 ** pCursor->aConstraint[] array. If so, set *pbEof to true before
142065 ** returning. If the cell is not filtered (excluded) by the constraints,
142066 ** set pbEof to zero.
142067 **
142068 ** Return SQLITE_OK if successful or an SQLite error code if an error
142069 ** occurs within a geometry callback.
142070 **
142071 ** This function assumes that the cell is part of a leaf node.
142072 */
142073 static int testRtreeEntry(Rtree *pRtree, RtreeCursor *pCursor, int *pbEof){
142074   RtreeCell cell;
142075   int ii;
142076   *pbEof = 0;
142077 
142078   nodeGetCell(pRtree, pCursor->pNode, pCursor->iCell, &cell);
142079   for(ii=0; ii<pCursor->nConstraint; ii++){
142080     RtreeConstraint *p = &pCursor->aConstraint[ii];
142081     RtreeDValue coord = DCOORD(cell.aCoord[p->iCoord]);
142082     int res;
142083     assert(p->op==RTREE_LE || p->op==RTREE_LT || p->op==RTREE_GE 
142084         || p->op==RTREE_GT || p->op==RTREE_EQ || p->op==RTREE_MATCH
142085     );
142086     switch( p->op ){
142087       case RTREE_LE: res = (coord<=p->rValue); break;
142088       case RTREE_LT: res = (coord<p->rValue);  break;
142089       case RTREE_GE: res = (coord>=p->rValue); break;
142090       case RTREE_GT: res = (coord>p->rValue);  break;
142091       case RTREE_EQ: res = (coord==p->rValue); break;
142092       default: {
142093         int rc;
142094         assert( p->op==RTREE_MATCH );
142095         rc = testRtreeGeom(pRtree, p, &cell, &res);
142096         if( rc!=SQLITE_OK ){
142097           return rc;
142098         }
142099         break;
142100       }
142101     }
142102 
142103     if( !res ){
142104       *pbEof = 1;
142105       return SQLITE_OK;
142106     }
142107   }
142108 
142109   return SQLITE_OK;
142110 }
142111 
142112 /*
142113 ** Cursor pCursor currently points at a node that heads a sub-tree of
142114 ** height iHeight (if iHeight==0, then the node is a leaf). Descend
142115 ** to point to the left-most cell of the sub-tree that matches the 
142116 ** configured constraints.
142117 */
142118 static int descendToCell(
142119   Rtree *pRtree, 
142120   RtreeCursor *pCursor, 
142121   int iHeight,
142122   int *pEof                 /* OUT: Set to true if cannot descend */
142123 ){
142124   int isEof;
142125   int rc;
142126   int ii;
142127   RtreeNode *pChild;
142128   sqlite3_int64 iRowid;
142129 
142130   RtreeNode *pSavedNode = pCursor->pNode;
142131   int iSavedCell = pCursor->iCell;
142132 
142133   assert( iHeight>=0 );
142134 
142135   if( iHeight==0 ){
142136     rc = testRtreeEntry(pRtree, pCursor, &isEof);
142137   }else{
142138     rc = testRtreeCell(pRtree, pCursor, &isEof);
142139   }
142140   if( rc!=SQLITE_OK || isEof || iHeight==0 ){
142141     goto descend_to_cell_out;
142142   }
142143 
142144   iRowid = nodeGetRowid(pRtree, pCursor->pNode, pCursor->iCell);
142145   rc = nodeAcquire(pRtree, iRowid, pCursor->pNode, &pChild);
142146   if( rc!=SQLITE_OK ){
142147     goto descend_to_cell_out;
142148   }
142149 
142150   nodeRelease(pRtree, pCursor->pNode);
142151   pCursor->pNode = pChild;
142152   isEof = 1;
142153   for(ii=0; isEof && ii<NCELL(pChild); ii++){
142154     pCursor->iCell = ii;
142155     rc = descendToCell(pRtree, pCursor, iHeight-1, &isEof);
142156     if( rc!=SQLITE_OK ){
142157       goto descend_to_cell_out;
142158     }
142159   }
142160 
142161   if( isEof ){
142162     assert( pCursor->pNode==pChild );
142163     nodeReference(pSavedNode);
142164     nodeRelease(pRtree, pChild);
142165     pCursor->pNode = pSavedNode;
142166     pCursor->iCell = iSavedCell;
142167   }
142168 
142169 descend_to_cell_out:
142170   *pEof = isEof;
142171   return rc;
142172 }
142173 
142174 /*
142175 ** One of the cells in node pNode is guaranteed to have a 64-bit 
142176 ** integer value equal to iRowid. Return the index of this cell.
142177 */
142178 static int nodeRowidIndex(
142179   Rtree *pRtree, 
142180   RtreeNode *pNode, 
142181   i64 iRowid,
142182   int *piIndex
142183 ){
142184   int ii;
142185   int nCell = NCELL(pNode);
142186   for(ii=0; ii<nCell; ii++){
142187     if( nodeGetRowid(pRtree, pNode, ii)==iRowid ){
142188       *piIndex = ii;
142189       return SQLITE_OK;
142190     }
142191   }
142192   return SQLITE_CORRUPT_VTAB;
142193 }
142194 
142195 /*
142196 ** Return the index of the cell containing a pointer to node pNode
142197 ** in its parent. If pNode is the root node, return -1.
142198 */
142199 static int nodeParentIndex(Rtree *pRtree, RtreeNode *pNode, int *piIndex){
142200   RtreeNode *pParent = pNode->pParent;
142201   if( pParent ){
142202     return nodeRowidIndex(pRtree, pParent, pNode->iNode, piIndex);
142203   }
142204   *piIndex = -1;
142205   return SQLITE_OK;
142206 }
142207 
142208 /* 
142209 ** Rtree virtual table module xNext method.
142210 */
142211 static int rtreeNext(sqlite3_vtab_cursor *pVtabCursor){
142212   Rtree *pRtree = (Rtree *)(pVtabCursor->pVtab);
142213   RtreeCursor *pCsr = (RtreeCursor *)pVtabCursor;
142214   int rc = SQLITE_OK;
142215 
142216   /* RtreeCursor.pNode must not be NULL. If is is NULL, then this cursor is
142217   ** already at EOF. It is against the rules to call the xNext() method of
142218   ** a cursor that has already reached EOF.
142219   */
142220   assert( pCsr->pNode );
142221 
142222   if( pCsr->iStrategy==1 ){
142223     /* This "scan" is a direct lookup by rowid. There is no next entry. */
142224     nodeRelease(pRtree, pCsr->pNode);
142225     pCsr->pNode = 0;
142226   }else{
142227     /* Move to the next entry that matches the configured constraints. */
142228     int iHeight = 0;
142229     while( pCsr->pNode ){
142230       RtreeNode *pNode = pCsr->pNode;
142231       int nCell = NCELL(pNode);
142232       for(pCsr->iCell++; pCsr->iCell<nCell; pCsr->iCell++){
142233         int isEof;
142234         rc = descendToCell(pRtree, pCsr, iHeight, &isEof);
142235         if( rc!=SQLITE_OK || !isEof ){
142236           return rc;
142237         }
142238       }
142239       pCsr->pNode = pNode->pParent;
142240       rc = nodeParentIndex(pRtree, pNode, &pCsr->iCell);
142241       if( rc!=SQLITE_OK ){
142242         return rc;
142243       }
142244       nodeReference(pCsr->pNode);
142245       nodeRelease(pRtree, pNode);
142246       iHeight++;
142247     }
142248   }
142249 
142250   return rc;
142251 }
142252 
142253 /* 
142254 ** Rtree virtual table module xRowid method.
142255 */
142256 static int rtreeRowid(sqlite3_vtab_cursor *pVtabCursor, sqlite_int64 *pRowid){
142257   Rtree *pRtree = (Rtree *)pVtabCursor->pVtab;
142258   RtreeCursor *pCsr = (RtreeCursor *)pVtabCursor;
142259 
142260   assert(pCsr->pNode);
142261   *pRowid = nodeGetRowid(pRtree, pCsr->pNode, pCsr->iCell);
142262 
142263   return SQLITE_OK;
142264 }
142265 
142266 /* 
142267 ** Rtree virtual table module xColumn method.
142268 */
142269 static int rtreeColumn(sqlite3_vtab_cursor *cur, sqlite3_context *ctx, int i){
142270   Rtree *pRtree = (Rtree *)cur->pVtab;
142271   RtreeCursor *pCsr = (RtreeCursor *)cur;
142272 
142273   if( i==0 ){
142274     i64 iRowid = nodeGetRowid(pRtree, pCsr->pNode, pCsr->iCell);
142275     sqlite3_result_int64(ctx, iRowid);
142276   }else{
142277     RtreeCoord c;
142278     nodeGetCoord(pRtree, pCsr->pNode, pCsr->iCell, i-1, &c);
142279 #ifndef SQLITE_RTREE_INT_ONLY
142280     if( pRtree->eCoordType==RTREE_COORD_REAL32 ){
142281       sqlite3_result_double(ctx, c.f);
142282     }else
142283 #endif
142284     {
142285       assert( pRtree->eCoordType==RTREE_COORD_INT32 );
142286       sqlite3_result_int(ctx, c.i);
142287     }
142288   }
142289 
142290   return SQLITE_OK;
142291 }
142292 
142293 /* 
142294 ** Use nodeAcquire() to obtain the leaf node containing the record with 
142295 ** rowid iRowid. If successful, set *ppLeaf to point to the node and
142296 ** return SQLITE_OK. If there is no such record in the table, set
142297 ** *ppLeaf to 0 and return SQLITE_OK. If an error occurs, set *ppLeaf
142298 ** to zero and return an SQLite error code.
142299 */
142300 static int findLeafNode(Rtree *pRtree, i64 iRowid, RtreeNode **ppLeaf){
142301   int rc;
142302   *ppLeaf = 0;
142303   sqlite3_bind_int64(pRtree->pReadRowid, 1, iRowid);
142304   if( sqlite3_step(pRtree->pReadRowid)==SQLITE_ROW ){
142305     i64 iNode = sqlite3_column_int64(pRtree->pReadRowid, 0);
142306     rc = nodeAcquire(pRtree, iNode, 0, ppLeaf);
142307     sqlite3_reset(pRtree->pReadRowid);
142308   }else{
142309     rc = sqlite3_reset(pRtree->pReadRowid);
142310   }
142311   return rc;
142312 }
142313 
142314 /*
142315 ** This function is called to configure the RtreeConstraint object passed
142316 ** as the second argument for a MATCH constraint. The value passed as the
142317 ** first argument to this function is the right-hand operand to the MATCH
142318 ** operator.
142319 */
142320 static int deserializeGeometry(sqlite3_value *pValue, RtreeConstraint *pCons){
142321   RtreeMatchArg *p;
142322   sqlite3_rtree_geometry *pGeom;
142323   int nBlob;
142324 
142325   /* Check that value is actually a blob. */
142326   if( sqlite3_value_type(pValue)!=SQLITE_BLOB ) return SQLITE_ERROR;
142327 
142328   /* Check that the blob is roughly the right size. */
142329   nBlob = sqlite3_value_bytes(pValue);
142330   if( nBlob<(int)sizeof(RtreeMatchArg) 
142331    || ((nBlob-sizeof(RtreeMatchArg))%sizeof(RtreeDValue))!=0
142332   ){
142333     return SQLITE_ERROR;
142334   }
142335 
142336   pGeom = (sqlite3_rtree_geometry *)sqlite3_malloc(
142337       sizeof(sqlite3_rtree_geometry) + nBlob
142338   );
142339   if( !pGeom ) return SQLITE_NOMEM;
142340   memset(pGeom, 0, sizeof(sqlite3_rtree_geometry));
142341   p = (RtreeMatchArg *)&pGeom[1];
142342 
142343   memcpy(p, sqlite3_value_blob(pValue), nBlob);
142344   if( p->magic!=RTREE_GEOMETRY_MAGIC 
142345    || nBlob!=(int)(sizeof(RtreeMatchArg) + (p->nParam-1)*sizeof(RtreeDValue))
142346   ){
142347     sqlite3_free(pGeom);
142348     return SQLITE_ERROR;
142349   }
142350 
142351   pGeom->pContext = p->pContext;
142352   pGeom->nParam = p->nParam;
142353   pGeom->aParam = p->aParam;
142354 
142355   pCons->xGeom = p->xGeom;
142356   pCons->pGeom = pGeom;
142357   return SQLITE_OK;
142358 }
142359 
142360 /* 
142361 ** Rtree virtual table module xFilter method.
142362 */
142363 static int rtreeFilter(
142364   sqlite3_vtab_cursor *pVtabCursor, 
142365   int idxNum, const char *idxStr,
142366   int argc, sqlite3_value **argv
142367 ){
142368   Rtree *pRtree = (Rtree *)pVtabCursor->pVtab;
142369   RtreeCursor *pCsr = (RtreeCursor *)pVtabCursor;
142370 
142371   RtreeNode *pRoot = 0;
142372   int ii;
142373   int rc = SQLITE_OK;
142374 
142375   rtreeReference(pRtree);
142376 
142377   freeCursorConstraints(pCsr);
142378   pCsr->iStrategy = idxNum;
142379 
142380   if( idxNum==1 ){
142381     /* Special case - lookup by rowid. */
142382     RtreeNode *pLeaf;        /* Leaf on which the required cell resides */
142383     i64 iRowid = sqlite3_value_int64(argv[0]);
142384     rc = findLeafNode(pRtree, iRowid, &pLeaf);
142385     pCsr->pNode = pLeaf; 
142386     if( pLeaf ){
142387       assert( rc==SQLITE_OK );
142388       rc = nodeRowidIndex(pRtree, pLeaf, iRowid, &pCsr->iCell);
142389     }
142390   }else{
142391     /* Normal case - r-tree scan. Set up the RtreeCursor.aConstraint array 
142392     ** with the configured constraints. 
142393     */
142394     if( argc>0 ){
142395       pCsr->aConstraint = sqlite3_malloc(sizeof(RtreeConstraint)*argc);
142396       pCsr->nConstraint = argc;
142397       if( !pCsr->aConstraint ){
142398         rc = SQLITE_NOMEM;
142399       }else{
142400         memset(pCsr->aConstraint, 0, sizeof(RtreeConstraint)*argc);
142401         assert( (idxStr==0 && argc==0)
142402                 || (idxStr && (int)strlen(idxStr)==argc*2) );
142403         for(ii=0; ii<argc; ii++){
142404           RtreeConstraint *p = &pCsr->aConstraint[ii];
142405           p->op = idxStr[ii*2];
142406           p->iCoord = idxStr[ii*2+1]-'a';
142407           if( p->op==RTREE_MATCH ){
142408             /* A MATCH operator. The right-hand-side must be a blob that
142409             ** can be cast into an RtreeMatchArg object. One created using
142410             ** an sqlite3_rtree_geometry_callback() SQL user function.
142411             */
142412             rc = deserializeGeometry(argv[ii], p);
142413             if( rc!=SQLITE_OK ){
142414               break;
142415             }
142416           }else{
142417 #ifdef SQLITE_RTREE_INT_ONLY
142418             p->rValue = sqlite3_value_int64(argv[ii]);
142419 #else
142420             p->rValue = sqlite3_value_double(argv[ii]);
142421 #endif
142422           }
142423         }
142424       }
142425     }
142426   
142427     if( rc==SQLITE_OK ){
142428       pCsr->pNode = 0;
142429       rc = nodeAcquire(pRtree, 1, 0, &pRoot);
142430     }
142431     if( rc==SQLITE_OK ){
142432       int isEof = 1;
142433       int nCell = NCELL(pRoot);
142434       pCsr->pNode = pRoot;
142435       for(pCsr->iCell=0; rc==SQLITE_OK && pCsr->iCell<nCell; pCsr->iCell++){
142436         assert( pCsr->pNode==pRoot );
142437         rc = descendToCell(pRtree, pCsr, pRtree->iDepth, &isEof);
142438         if( !isEof ){
142439           break;
142440         }
142441       }
142442       if( rc==SQLITE_OK && isEof ){
142443         assert( pCsr->pNode==pRoot );
142444         nodeRelease(pRtree, pRoot);
142445         pCsr->pNode = 0;
142446       }
142447       assert( rc!=SQLITE_OK || !pCsr->pNode || pCsr->iCell<NCELL(pCsr->pNode) );
142448     }
142449   }
142450 
142451   rtreeRelease(pRtree);
142452   return rc;
142453 }
142454 
142455 /*
142456 ** Set the pIdxInfo->estimatedRows variable to nRow. Unless this
142457 ** extension is currently being used by a version of SQLite too old to
142458 ** support estimatedRows. In that case this function is a no-op.
142459 */
142460 static void setEstimatedRows(sqlite3_index_info *pIdxInfo, i64 nRow){
142461 #if SQLITE_VERSION_NUMBER>=3008002
142462   if( sqlite3_libversion_number()>=3008002 ){
142463     pIdxInfo->estimatedRows = nRow;
142464   }
142465 #endif
142466 }
142467 
142468 /*
142469 ** Rtree virtual table module xBestIndex method. There are three
142470 ** table scan strategies to choose from (in order from most to 
142471 ** least desirable):
142472 **
142473 **   idxNum     idxStr        Strategy
142474 **   ------------------------------------------------
142475 **     1        Unused        Direct lookup by rowid.
142476 **     2        See below     R-tree query or full-table scan.
142477 **   ------------------------------------------------
142478 **
142479 ** If strategy 1 is used, then idxStr is not meaningful. If strategy
142480 ** 2 is used, idxStr is formatted to contain 2 bytes for each 
142481 ** constraint used. The first two bytes of idxStr correspond to 
142482 ** the constraint in sqlite3_index_info.aConstraintUsage[] with
142483 ** (argvIndex==1) etc.
142484 **
142485 ** The first of each pair of bytes in idxStr identifies the constraint
142486 ** operator as follows:
142487 **
142488 **   Operator    Byte Value
142489 **   ----------------------
142490 **      =        0x41 ('A')
142491 **     <=        0x42 ('B')
142492 **      <        0x43 ('C')
142493 **     >=        0x44 ('D')
142494 **      >        0x45 ('E')
142495 **   MATCH       0x46 ('F')
142496 **   ----------------------
142497 **
142498 ** The second of each pair of bytes identifies the coordinate column
142499 ** to which the constraint applies. The leftmost coordinate column
142500 ** is 'a', the second from the left 'b' etc.
142501 */
142502 static int rtreeBestIndex(sqlite3_vtab *tab, sqlite3_index_info *pIdxInfo){
142503   Rtree *pRtree = (Rtree*)tab;
142504   int rc = SQLITE_OK;
142505   int ii;
142506   i64 nRow;                       /* Estimated rows returned by this scan */
142507 
142508   int iIdx = 0;
142509   char zIdxStr[RTREE_MAX_DIMENSIONS*8+1];
142510   memset(zIdxStr, 0, sizeof(zIdxStr));
142511 
142512   assert( pIdxInfo->idxStr==0 );
142513   for(ii=0; ii<pIdxInfo->nConstraint && iIdx<(int)(sizeof(zIdxStr)-1); ii++){
142514     struct sqlite3_index_constraint *p = &pIdxInfo->aConstraint[ii];
142515 
142516     if( p->usable && p->iColumn==0 && p->op==SQLITE_INDEX_CONSTRAINT_EQ ){
142517       /* We have an equality constraint on the rowid. Use strategy 1. */
142518       int jj;
142519       for(jj=0; jj<ii; jj++){
142520         pIdxInfo->aConstraintUsage[jj].argvIndex = 0;
142521         pIdxInfo->aConstraintUsage[jj].omit = 0;
142522       }
142523       pIdxInfo->idxNum = 1;
142524       pIdxInfo->aConstraintUsage[ii].argvIndex = 1;
142525       pIdxInfo->aConstraintUsage[jj].omit = 1;
142526 
142527       /* This strategy involves a two rowid lookups on an B-Tree structures
142528       ** and then a linear search of an R-Tree node. This should be 
142529       ** considered almost as quick as a direct rowid lookup (for which 
142530       ** sqlite uses an internal cost of 0.0). It is expected to return
142531       ** a single row.
142532       */ 
142533       pIdxInfo->estimatedCost = 30.0;
142534       setEstimatedRows(pIdxInfo, 1);
142535       return SQLITE_OK;
142536     }
142537 
142538     if( p->usable && (p->iColumn>0 || p->op==SQLITE_INDEX_CONSTRAINT_MATCH) ){
142539       u8 op;
142540       switch( p->op ){
142541         case SQLITE_INDEX_CONSTRAINT_EQ: op = RTREE_EQ; break;
142542         case SQLITE_INDEX_CONSTRAINT_GT: op = RTREE_GT; break;
142543         case SQLITE_INDEX_CONSTRAINT_LE: op = RTREE_LE; break;
142544         case SQLITE_INDEX_CONSTRAINT_LT: op = RTREE_LT; break;
142545         case SQLITE_INDEX_CONSTRAINT_GE: op = RTREE_GE; break;
142546         default:
142547           assert( p->op==SQLITE_INDEX_CONSTRAINT_MATCH );
142548           op = RTREE_MATCH; 
142549           break;
142550       }
142551       zIdxStr[iIdx++] = op;
142552       zIdxStr[iIdx++] = p->iColumn - 1 + 'a';
142553       pIdxInfo->aConstraintUsage[ii].argvIndex = (iIdx/2);
142554       pIdxInfo->aConstraintUsage[ii].omit = 1;
142555     }
142556   }
142557 
142558   pIdxInfo->idxNum = 2;
142559   pIdxInfo->needToFreeIdxStr = 1;
142560   if( iIdx>0 && 0==(pIdxInfo->idxStr = sqlite3_mprintf("%s", zIdxStr)) ){
142561     return SQLITE_NOMEM;
142562   }
142563 
142564   nRow = pRtree->nRowEst / (iIdx + 1);
142565   pIdxInfo->estimatedCost = (double)6.0 * (double)nRow;
142566   setEstimatedRows(pIdxInfo, nRow);
142567 
142568   return rc;
142569 }
142570 
142571 /*
142572 ** Return the N-dimensional volumn of the cell stored in *p.
142573 */
142574 static RtreeDValue cellArea(Rtree *pRtree, RtreeCell *p){
142575   RtreeDValue area = (RtreeDValue)1;
142576   int ii;
142577   for(ii=0; ii<(pRtree->nDim*2); ii+=2){
142578     area = (area * (DCOORD(p->aCoord[ii+1]) - DCOORD(p->aCoord[ii])));
142579   }
142580   return area;
142581 }
142582 
142583 /*
142584 ** Return the margin length of cell p. The margin length is the sum
142585 ** of the objects size in each dimension.
142586 */
142587 static RtreeDValue cellMargin(Rtree *pRtree, RtreeCell *p){
142588   RtreeDValue margin = (RtreeDValue)0;
142589   int ii;
142590   for(ii=0; ii<(pRtree->nDim*2); ii+=2){
142591     margin += (DCOORD(p->aCoord[ii+1]) - DCOORD(p->aCoord[ii]));
142592   }
142593   return margin;
142594 }
142595 
142596 /*
142597 ** Store the union of cells p1 and p2 in p1.
142598 */
142599 static void cellUnion(Rtree *pRtree, RtreeCell *p1, RtreeCell *p2){
142600   int ii;
142601   if( pRtree->eCoordType==RTREE_COORD_REAL32 ){
142602     for(ii=0; ii<(pRtree->nDim*2); ii+=2){
142603       p1->aCoord[ii].f = MIN(p1->aCoord[ii].f, p2->aCoord[ii].f);
142604       p1->aCoord[ii+1].f = MAX(p1->aCoord[ii+1].f, p2->aCoord[ii+1].f);
142605     }
142606   }else{
142607     for(ii=0; ii<(pRtree->nDim*2); ii+=2){
142608       p1->aCoord[ii].i = MIN(p1->aCoord[ii].i, p2->aCoord[ii].i);
142609       p1->aCoord[ii+1].i = MAX(p1->aCoord[ii+1].i, p2->aCoord[ii+1].i);
142610     }
142611   }
142612 }
142613 
142614 /*
142615 ** Return true if the area covered by p2 is a subset of the area covered
142616 ** by p1. False otherwise.
142617 */
142618 static int cellContains(Rtree *pRtree, RtreeCell *p1, RtreeCell *p2){
142619   int ii;
142620   int isInt = (pRtree->eCoordType==RTREE_COORD_INT32);
142621   for(ii=0; ii<(pRtree->nDim*2); ii+=2){
142622     RtreeCoord *a1 = &p1->aCoord[ii];
142623     RtreeCoord *a2 = &p2->aCoord[ii];
142624     if( (!isInt && (a2[0].f<a1[0].f || a2[1].f>a1[1].f)) 
142625      || ( isInt && (a2[0].i<a1[0].i || a2[1].i>a1[1].i)) 
142626     ){
142627       return 0;
142628     }
142629   }
142630   return 1;
142631 }
142632 
142633 /*
142634 ** Return the amount cell p would grow by if it were unioned with pCell.
142635 */
142636 static RtreeDValue cellGrowth(Rtree *pRtree, RtreeCell *p, RtreeCell *pCell){
142637   RtreeDValue area;
142638   RtreeCell cell;
142639   memcpy(&cell, p, sizeof(RtreeCell));
142640   area = cellArea(pRtree, &cell);
142641   cellUnion(pRtree, &cell, pCell);
142642   return (cellArea(pRtree, &cell)-area);
142643 }
142644 
142645 #if VARIANT_RSTARTREE_CHOOSESUBTREE || VARIANT_RSTARTREE_SPLIT
142646 static RtreeDValue cellOverlap(
142647   Rtree *pRtree, 
142648   RtreeCell *p, 
142649   RtreeCell *aCell, 
142650   int nCell, 
142651   int iExclude
142652 ){
142653   int ii;
142654   RtreeDValue overlap = 0.0;
142655   for(ii=0; ii<nCell; ii++){
142656 #if VARIANT_RSTARTREE_CHOOSESUBTREE
142657     if( ii!=iExclude )
142658 #else
142659     assert( iExclude==-1 );
142660     UNUSED_PARAMETER(iExclude);
142661 #endif
142662     {
142663       int jj;
142664       RtreeDValue o = (RtreeDValue)1;
142665       for(jj=0; jj<(pRtree->nDim*2); jj+=2){
142666         RtreeDValue x1, x2;
142667 
142668         x1 = MAX(DCOORD(p->aCoord[jj]), DCOORD(aCell[ii].aCoord[jj]));
142669         x2 = MIN(DCOORD(p->aCoord[jj+1]), DCOORD(aCell[ii].aCoord[jj+1]));
142670 
142671         if( x2<x1 ){
142672           o = 0.0;
142673           break;
142674         }else{
142675           o = o * (x2-x1);
142676         }
142677       }
142678       overlap += o;
142679     }
142680   }
142681   return overlap;
142682 }
142683 #endif
142684 
142685 #if VARIANT_RSTARTREE_CHOOSESUBTREE
142686 static RtreeDValue cellOverlapEnlargement(
142687   Rtree *pRtree, 
142688   RtreeCell *p, 
142689   RtreeCell *pInsert, 
142690   RtreeCell *aCell, 
142691   int nCell, 
142692   int iExclude
142693 ){
142694   RtreeDValue before, after;
142695   before = cellOverlap(pRtree, p, aCell, nCell, iExclude);
142696   cellUnion(pRtree, p, pInsert);
142697   after = cellOverlap(pRtree, p, aCell, nCell, iExclude);
142698   return (after-before);
142699 }
142700 #endif
142701 
142702 
142703 /*
142704 ** This function implements the ChooseLeaf algorithm from Gutman[84].
142705 ** ChooseSubTree in r*tree terminology.
142706 */
142707 static int ChooseLeaf(
142708   Rtree *pRtree,               /* Rtree table */
142709   RtreeCell *pCell,            /* Cell to insert into rtree */
142710   int iHeight,                 /* Height of sub-tree rooted at pCell */
142711   RtreeNode **ppLeaf           /* OUT: Selected leaf page */
142712 ){
142713   int rc;
142714   int ii;
142715   RtreeNode *pNode;
142716   rc = nodeAcquire(pRtree, 1, 0, &pNode);
142717 
142718   for(ii=0; rc==SQLITE_OK && ii<(pRtree->iDepth-iHeight); ii++){
142719     int iCell;
142720     sqlite3_int64 iBest = 0;
142721 
142722     RtreeDValue fMinGrowth = 0.0;
142723     RtreeDValue fMinArea = 0.0;
142724 #if VARIANT_RSTARTREE_CHOOSESUBTREE
142725     RtreeDValue fMinOverlap = 0.0;
142726     RtreeDValue overlap;
142727 #endif
142728 
142729     int nCell = NCELL(pNode);
142730     RtreeCell cell;
142731     RtreeNode *pChild;
142732 
142733     RtreeCell *aCell = 0;
142734 
142735 #if VARIANT_RSTARTREE_CHOOSESUBTREE
142736     if( ii==(pRtree->iDepth-1) ){
142737       int jj;
142738       aCell = sqlite3_malloc(sizeof(RtreeCell)*nCell);
142739       if( !aCell ){
142740         rc = SQLITE_NOMEM;
142741         nodeRelease(pRtree, pNode);
142742         pNode = 0;
142743         continue;
142744       }
142745       for(jj=0; jj<nCell; jj++){
142746         nodeGetCell(pRtree, pNode, jj, &aCell[jj]);
142747       }
142748     }
142749 #endif
142750 
142751     /* Select the child node which will be enlarged the least if pCell
142752     ** is inserted into it. Resolve ties by choosing the entry with
142753     ** the smallest area.
142754     */
142755     for(iCell=0; iCell<nCell; iCell++){
142756       int bBest = 0;
142757       RtreeDValue growth;
142758       RtreeDValue area;
142759       nodeGetCell(pRtree, pNode, iCell, &cell);
142760       growth = cellGrowth(pRtree, &cell, pCell);
142761       area = cellArea(pRtree, &cell);
142762 
142763 #if VARIANT_RSTARTREE_CHOOSESUBTREE
142764       if( ii==(pRtree->iDepth-1) ){
142765         overlap = cellOverlapEnlargement(pRtree,&cell,pCell,aCell,nCell,iCell);
142766       }else{
142767         overlap = 0.0;
142768       }
142769       if( (iCell==0) 
142770        || (overlap<fMinOverlap) 
142771        || (overlap==fMinOverlap && growth<fMinGrowth)
142772        || (overlap==fMinOverlap && growth==fMinGrowth && area<fMinArea)
142773       ){
142774         bBest = 1;
142775         fMinOverlap = overlap;
142776       }
142777 #else
142778       if( iCell==0||growth<fMinGrowth||(growth==fMinGrowth && area<fMinArea) ){
142779         bBest = 1;
142780       }
142781 #endif
142782       if( bBest ){
142783         fMinGrowth = growth;
142784         fMinArea = area;
142785         iBest = cell.iRowid;
142786       }
142787     }
142788 
142789     sqlite3_free(aCell);
142790     rc = nodeAcquire(pRtree, iBest, pNode, &pChild);
142791     nodeRelease(pRtree, pNode);
142792     pNode = pChild;
142793   }
142794 
142795   *ppLeaf = pNode;
142796   return rc;
142797 }
142798 
142799 /*
142800 ** A cell with the same content as pCell has just been inserted into
142801 ** the node pNode. This function updates the bounding box cells in
142802 ** all ancestor elements.
142803 */
142804 static int AdjustTree(
142805   Rtree *pRtree,                    /* Rtree table */
142806   RtreeNode *pNode,                 /* Adjust ancestry of this node. */
142807   RtreeCell *pCell                  /* This cell was just inserted */
142808 ){
142809   RtreeNode *p = pNode;
142810   while( p->pParent ){
142811     RtreeNode *pParent = p->pParent;
142812     RtreeCell cell;
142813     int iCell;
142814 
142815     if( nodeParentIndex(pRtree, p, &iCell) ){
142816       return SQLITE_CORRUPT_VTAB;
142817     }
142818 
142819     nodeGetCell(pRtree, pParent, iCell, &cell);
142820     if( !cellContains(pRtree, &cell, pCell) ){
142821       cellUnion(pRtree, &cell, pCell);
142822       nodeOverwriteCell(pRtree, pParent, &cell, iCell);
142823     }
142824  
142825     p = pParent;
142826   }
142827   return SQLITE_OK;
142828 }
142829 
142830 /*
142831 ** Write mapping (iRowid->iNode) to the <rtree>_rowid table.
142832 */
142833 static int rowidWrite(Rtree *pRtree, sqlite3_int64 iRowid, sqlite3_int64 iNode){
142834   sqlite3_bind_int64(pRtree->pWriteRowid, 1, iRowid);
142835   sqlite3_bind_int64(pRtree->pWriteRowid, 2, iNode);
142836   sqlite3_step(pRtree->pWriteRowid);
142837   return sqlite3_reset(pRtree->pWriteRowid);
142838 }
142839 
142840 /*
142841 ** Write mapping (iNode->iPar) to the <rtree>_parent table.
142842 */
142843 static int parentWrite(Rtree *pRtree, sqlite3_int64 iNode, sqlite3_int64 iPar){
142844   sqlite3_bind_int64(pRtree->pWriteParent, 1, iNode);
142845   sqlite3_bind_int64(pRtree->pWriteParent, 2, iPar);
142846   sqlite3_step(pRtree->pWriteParent);
142847   return sqlite3_reset(pRtree->pWriteParent);
142848 }
142849 
142850 static int rtreeInsertCell(Rtree *, RtreeNode *, RtreeCell *, int);
142851 
142852 #if VARIANT_GUTTMAN_LINEAR_SPLIT
142853 /*
142854 ** Implementation of the linear variant of the PickNext() function from
142855 ** Guttman[84].
142856 */
142857 static RtreeCell *LinearPickNext(
142858   Rtree *pRtree,
142859   RtreeCell *aCell, 
142860   int nCell, 
142861   RtreeCell *pLeftBox, 
142862   RtreeCell *pRightBox,
142863   int *aiUsed
142864 ){
142865   int ii;
142866   for(ii=0; aiUsed[ii]; ii++);
142867   aiUsed[ii] = 1;
142868   return &aCell[ii];
142869 }
142870 
142871 /*
142872 ** Implementation of the linear variant of the PickSeeds() function from
142873 ** Guttman[84].
142874 */
142875 static void LinearPickSeeds(
142876   Rtree *pRtree,
142877   RtreeCell *aCell, 
142878   int nCell, 
142879   int *piLeftSeed, 
142880   int *piRightSeed
142881 ){
142882   int i;
142883   int iLeftSeed = 0;
142884   int iRightSeed = 1;
142885   RtreeDValue maxNormalInnerWidth = (RtreeDValue)0;
142886 
142887   /* Pick two "seed" cells from the array of cells. The algorithm used
142888   ** here is the LinearPickSeeds algorithm from Gutman[1984]. The 
142889   ** indices of the two seed cells in the array are stored in local
142890   ** variables iLeftSeek and iRightSeed.
142891   */
142892   for(i=0; i<pRtree->nDim; i++){
142893     RtreeDValue x1 = DCOORD(aCell[0].aCoord[i*2]);
142894     RtreeDValue x2 = DCOORD(aCell[0].aCoord[i*2+1]);
142895     RtreeDValue x3 = x1;
142896     RtreeDValue x4 = x2;
142897     int jj;
142898 
142899     int iCellLeft = 0;
142900     int iCellRight = 0;
142901 
142902     for(jj=1; jj<nCell; jj++){
142903       RtreeDValue left = DCOORD(aCell[jj].aCoord[i*2]);
142904       RtreeDValue right = DCOORD(aCell[jj].aCoord[i*2+1]);
142905 
142906       if( left<x1 ) x1 = left;
142907       if( right>x4 ) x4 = right;
142908       if( left>x3 ){
142909         x3 = left;
142910         iCellRight = jj;
142911       }
142912       if( right<x2 ){
142913         x2 = right;
142914         iCellLeft = jj;
142915       }
142916     }
142917 
142918     if( x4!=x1 ){
142919       RtreeDValue normalwidth = (x3 - x2) / (x4 - x1);
142920       if( normalwidth>maxNormalInnerWidth ){
142921         iLeftSeed = iCellLeft;
142922         iRightSeed = iCellRight;
142923       }
142924     }
142925   }
142926 
142927   *piLeftSeed = iLeftSeed;
142928   *piRightSeed = iRightSeed;
142929 }
142930 #endif /* VARIANT_GUTTMAN_LINEAR_SPLIT */
142931 
142932 #if VARIANT_GUTTMAN_QUADRATIC_SPLIT
142933 /*
142934 ** Implementation of the quadratic variant of the PickNext() function from
142935 ** Guttman[84].
142936 */
142937 static RtreeCell *QuadraticPickNext(
142938   Rtree *pRtree,
142939   RtreeCell *aCell, 
142940   int nCell, 
142941   RtreeCell *pLeftBox, 
142942   RtreeCell *pRightBox,
142943   int *aiUsed
142944 ){
142945   #define FABS(a) ((a)<0.0?-1.0*(a):(a))
142946 
142947   int iSelect = -1;
142948   RtreeDValue fDiff;
142949   int ii;
142950   for(ii=0; ii<nCell; ii++){
142951     if( aiUsed[ii]==0 ){
142952       RtreeDValue left = cellGrowth(pRtree, pLeftBox, &aCell[ii]);
142953       RtreeDValue right = cellGrowth(pRtree, pLeftBox, &aCell[ii]);
142954       RtreeDValue diff = FABS(right-left);
142955       if( iSelect<0 || diff>fDiff ){
142956         fDiff = diff;
142957         iSelect = ii;
142958       }
142959     }
142960   }
142961   aiUsed[iSelect] = 1;
142962   return &aCell[iSelect];
142963 }
142964 
142965 /*
142966 ** Implementation of the quadratic variant of the PickSeeds() function from
142967 ** Guttman[84].
142968 */
142969 static void QuadraticPickSeeds(
142970   Rtree *pRtree,
142971   RtreeCell *aCell, 
142972   int nCell, 
142973   int *piLeftSeed, 
142974   int *piRightSeed
142975 ){
142976   int ii;
142977   int jj;
142978 
142979   int iLeftSeed = 0;
142980   int iRightSeed = 1;
142981   RtreeDValue fWaste = 0.0;
142982 
142983   for(ii=0; ii<nCell; ii++){
142984     for(jj=ii+1; jj<nCell; jj++){
142985       RtreeDValue right = cellArea(pRtree, &aCell[jj]);
142986       RtreeDValue growth = cellGrowth(pRtree, &aCell[ii], &aCell[jj]);
142987       RtreeDValue waste = growth - right;
142988 
142989       if( waste>fWaste ){
142990         iLeftSeed = ii;
142991         iRightSeed = jj;
142992         fWaste = waste;
142993       }
142994     }
142995   }
142996 
142997   *piLeftSeed = iLeftSeed;
142998   *piRightSeed = iRightSeed;
142999 }
143000 #endif /* VARIANT_GUTTMAN_QUADRATIC_SPLIT */
143001 
143002 /*
143003 ** Arguments aIdx, aDistance and aSpare all point to arrays of size
143004 ** nIdx. The aIdx array contains the set of integers from 0 to 
143005 ** (nIdx-1) in no particular order. This function sorts the values
143006 ** in aIdx according to the indexed values in aDistance. For
143007 ** example, assuming the inputs:
143008 **
143009 **   aIdx      = { 0,   1,   2,   3 }
143010 **   aDistance = { 5.0, 2.0, 7.0, 6.0 }
143011 **
143012 ** this function sets the aIdx array to contain:
143013 **
143014 **   aIdx      = { 0,   1,   2,   3 }
143015 **
143016 ** The aSpare array is used as temporary working space by the
143017 ** sorting algorithm.
143018 */
143019 static void SortByDistance(
143020   int *aIdx, 
143021   int nIdx, 
143022   RtreeDValue *aDistance, 
143023   int *aSpare
143024 ){
143025   if( nIdx>1 ){
143026     int iLeft = 0;
143027     int iRight = 0;
143028 
143029     int nLeft = nIdx/2;
143030     int nRight = nIdx-nLeft;
143031     int *aLeft = aIdx;
143032     int *aRight = &aIdx[nLeft];
143033 
143034     SortByDistance(aLeft, nLeft, aDistance, aSpare);
143035     SortByDistance(aRight, nRight, aDistance, aSpare);
143036 
143037     memcpy(aSpare, aLeft, sizeof(int)*nLeft);
143038     aLeft = aSpare;
143039 
143040     while( iLeft<nLeft || iRight<nRight ){
143041       if( iLeft==nLeft ){
143042         aIdx[iLeft+iRight] = aRight[iRight];
143043         iRight++;
143044       }else if( iRight==nRight ){
143045         aIdx[iLeft+iRight] = aLeft[iLeft];
143046         iLeft++;
143047       }else{
143048         RtreeDValue fLeft = aDistance[aLeft[iLeft]];
143049         RtreeDValue fRight = aDistance[aRight[iRight]];
143050         if( fLeft<fRight ){
143051           aIdx[iLeft+iRight] = aLeft[iLeft];
143052           iLeft++;
143053         }else{
143054           aIdx[iLeft+iRight] = aRight[iRight];
143055           iRight++;
143056         }
143057       }
143058     }
143059 
143060 #if 0
143061     /* Check that the sort worked */
143062     {
143063       int jj;
143064       for(jj=1; jj<nIdx; jj++){
143065         RtreeDValue left = aDistance[aIdx[jj-1]];
143066         RtreeDValue right = aDistance[aIdx[jj]];
143067         assert( left<=right );
143068       }
143069     }
143070 #endif
143071   }
143072 }
143073 
143074 /*
143075 ** Arguments aIdx, aCell and aSpare all point to arrays of size
143076 ** nIdx. The aIdx array contains the set of integers from 0 to 
143077 ** (nIdx-1) in no particular order. This function sorts the values
143078 ** in aIdx according to dimension iDim of the cells in aCell. The
143079 ** minimum value of dimension iDim is considered first, the
143080 ** maximum used to break ties.
143081 **
143082 ** The aSpare array is used as temporary working space by the
143083 ** sorting algorithm.
143084 */
143085 static void SortByDimension(
143086   Rtree *pRtree,
143087   int *aIdx, 
143088   int nIdx, 
143089   int iDim, 
143090   RtreeCell *aCell, 
143091   int *aSpare
143092 ){
143093   if( nIdx>1 ){
143094 
143095     int iLeft = 0;
143096     int iRight = 0;
143097 
143098     int nLeft = nIdx/2;
143099     int nRight = nIdx-nLeft;
143100     int *aLeft = aIdx;
143101     int *aRight = &aIdx[nLeft];
143102 
143103     SortByDimension(pRtree, aLeft, nLeft, iDim, aCell, aSpare);
143104     SortByDimension(pRtree, aRight, nRight, iDim, aCell, aSpare);
143105 
143106     memcpy(aSpare, aLeft, sizeof(int)*nLeft);
143107     aLeft = aSpare;
143108     while( iLeft<nLeft || iRight<nRight ){
143109       RtreeDValue xleft1 = DCOORD(aCell[aLeft[iLeft]].aCoord[iDim*2]);
143110       RtreeDValue xleft2 = DCOORD(aCell[aLeft[iLeft]].aCoord[iDim*2+1]);
143111       RtreeDValue xright1 = DCOORD(aCell[aRight[iRight]].aCoord[iDim*2]);
143112       RtreeDValue xright2 = DCOORD(aCell[aRight[iRight]].aCoord[iDim*2+1]);
143113       if( (iLeft!=nLeft) && ((iRight==nRight)
143114        || (xleft1<xright1)
143115        || (xleft1==xright1 && xleft2<xright2)
143116       )){
143117         aIdx[iLeft+iRight] = aLeft[iLeft];
143118         iLeft++;
143119       }else{
143120         aIdx[iLeft+iRight] = aRight[iRight];
143121         iRight++;
143122       }
143123     }
143124 
143125 #if 0
143126     /* Check that the sort worked */
143127     {
143128       int jj;
143129       for(jj=1; jj<nIdx; jj++){
143130         RtreeDValue xleft1 = aCell[aIdx[jj-1]].aCoord[iDim*2];
143131         RtreeDValue xleft2 = aCell[aIdx[jj-1]].aCoord[iDim*2+1];
143132         RtreeDValue xright1 = aCell[aIdx[jj]].aCoord[iDim*2];
143133         RtreeDValue xright2 = aCell[aIdx[jj]].aCoord[iDim*2+1];
143134         assert( xleft1<=xright1 && (xleft1<xright1 || xleft2<=xright2) );
143135       }
143136     }
143137 #endif
143138   }
143139 }
143140 
143141 #if VARIANT_RSTARTREE_SPLIT
143142 /*
143143 ** Implementation of the R*-tree variant of SplitNode from Beckman[1990].
143144 */
143145 static int splitNodeStartree(
143146   Rtree *pRtree,
143147   RtreeCell *aCell,
143148   int nCell,
143149   RtreeNode *pLeft,
143150   RtreeNode *pRight,
143151   RtreeCell *pBboxLeft,
143152   RtreeCell *pBboxRight
143153 ){
143154   int **aaSorted;
143155   int *aSpare;
143156   int ii;
143157 
143158   int iBestDim = 0;
143159   int iBestSplit = 0;
143160   RtreeDValue fBestMargin = 0.0;
143161 
143162   int nByte = (pRtree->nDim+1)*(sizeof(int*)+nCell*sizeof(int));
143163 
143164   aaSorted = (int **)sqlite3_malloc(nByte);
143165   if( !aaSorted ){
143166     return SQLITE_NOMEM;
143167   }
143168 
143169   aSpare = &((int *)&aaSorted[pRtree->nDim])[pRtree->nDim*nCell];
143170   memset(aaSorted, 0, nByte);
143171   for(ii=0; ii<pRtree->nDim; ii++){
143172     int jj;
143173     aaSorted[ii] = &((int *)&aaSorted[pRtree->nDim])[ii*nCell];
143174     for(jj=0; jj<nCell; jj++){
143175       aaSorted[ii][jj] = jj;
143176     }
143177     SortByDimension(pRtree, aaSorted[ii], nCell, ii, aCell, aSpare);
143178   }
143179 
143180   for(ii=0; ii<pRtree->nDim; ii++){
143181     RtreeDValue margin = 0.0;
143182     RtreeDValue fBestOverlap = 0.0;
143183     RtreeDValue fBestArea = 0.0;
143184     int iBestLeft = 0;
143185     int nLeft;
143186 
143187     for(
143188       nLeft=RTREE_MINCELLS(pRtree); 
143189       nLeft<=(nCell-RTREE_MINCELLS(pRtree)); 
143190       nLeft++
143191     ){
143192       RtreeCell left;
143193       RtreeCell right;
143194       int kk;
143195       RtreeDValue overlap;
143196       RtreeDValue area;
143197 
143198       memcpy(&left, &aCell[aaSorted[ii][0]], sizeof(RtreeCell));
143199       memcpy(&right, &aCell[aaSorted[ii][nCell-1]], sizeof(RtreeCell));
143200       for(kk=1; kk<(nCell-1); kk++){
143201         if( kk<nLeft ){
143202           cellUnion(pRtree, &left, &aCell[aaSorted[ii][kk]]);
143203         }else{
143204           cellUnion(pRtree, &right, &aCell[aaSorted[ii][kk]]);
143205         }
143206       }
143207       margin += cellMargin(pRtree, &left);
143208       margin += cellMargin(pRtree, &right);
143209       overlap = cellOverlap(pRtree, &left, &right, 1, -1);
143210       area = cellArea(pRtree, &left) + cellArea(pRtree, &right);
143211       if( (nLeft==RTREE_MINCELLS(pRtree))
143212        || (overlap<fBestOverlap)
143213        || (overlap==fBestOverlap && area<fBestArea)
143214       ){
143215         iBestLeft = nLeft;
143216         fBestOverlap = overlap;
143217         fBestArea = area;
143218       }
143219     }
143220 
143221     if( ii==0 || margin<fBestMargin ){
143222       iBestDim = ii;
143223       fBestMargin = margin;
143224       iBestSplit = iBestLeft;
143225     }
143226   }
143227 
143228   memcpy(pBboxLeft, &aCell[aaSorted[iBestDim][0]], sizeof(RtreeCell));
143229   memcpy(pBboxRight, &aCell[aaSorted[iBestDim][iBestSplit]], sizeof(RtreeCell));
143230   for(ii=0; ii<nCell; ii++){
143231     RtreeNode *pTarget = (ii<iBestSplit)?pLeft:pRight;
143232     RtreeCell *pBbox = (ii<iBestSplit)?pBboxLeft:pBboxRight;
143233     RtreeCell *pCell = &aCell[aaSorted[iBestDim][ii]];
143234     nodeInsertCell(pRtree, pTarget, pCell);
143235     cellUnion(pRtree, pBbox, pCell);
143236   }
143237 
143238   sqlite3_free(aaSorted);
143239   return SQLITE_OK;
143240 }
143241 #endif
143242 
143243 #if VARIANT_GUTTMAN_SPLIT
143244 /*
143245 ** Implementation of the regular R-tree SplitNode from Guttman[1984].
143246 */
143247 static int splitNodeGuttman(
143248   Rtree *pRtree,
143249   RtreeCell *aCell,
143250   int nCell,
143251   RtreeNode *pLeft,
143252   RtreeNode *pRight,
143253   RtreeCell *pBboxLeft,
143254   RtreeCell *pBboxRight
143255 ){
143256   int iLeftSeed = 0;
143257   int iRightSeed = 1;
143258   int *aiUsed;
143259   int i;
143260 
143261   aiUsed = sqlite3_malloc(sizeof(int)*nCell);
143262   if( !aiUsed ){
143263     return SQLITE_NOMEM;
143264   }
143265   memset(aiUsed, 0, sizeof(int)*nCell);
143266 
143267   PickSeeds(pRtree, aCell, nCell, &iLeftSeed, &iRightSeed);
143268 
143269   memcpy(pBboxLeft, &aCell[iLeftSeed], sizeof(RtreeCell));
143270   memcpy(pBboxRight, &aCell[iRightSeed], sizeof(RtreeCell));
143271   nodeInsertCell(pRtree, pLeft, &aCell[iLeftSeed]);
143272   nodeInsertCell(pRtree, pRight, &aCell[iRightSeed]);
143273   aiUsed[iLeftSeed] = 1;
143274   aiUsed[iRightSeed] = 1;
143275 
143276   for(i=nCell-2; i>0; i--){
143277     RtreeCell *pNext;
143278     pNext = PickNext(pRtree, aCell, nCell, pBboxLeft, pBboxRight, aiUsed);
143279     RtreeDValue diff =  
143280       cellGrowth(pRtree, pBboxLeft, pNext) - 
143281       cellGrowth(pRtree, pBboxRight, pNext)
143282     ;
143283     if( (RTREE_MINCELLS(pRtree)-NCELL(pRight)==i)
143284      || (diff>0.0 && (RTREE_MINCELLS(pRtree)-NCELL(pLeft)!=i))
143285     ){
143286       nodeInsertCell(pRtree, pRight, pNext);
143287       cellUnion(pRtree, pBboxRight, pNext);
143288     }else{
143289       nodeInsertCell(pRtree, pLeft, pNext);
143290       cellUnion(pRtree, pBboxLeft, pNext);
143291     }
143292   }
143293 
143294   sqlite3_free(aiUsed);
143295   return SQLITE_OK;
143296 }
143297 #endif
143298 
143299 static int updateMapping(
143300   Rtree *pRtree, 
143301   i64 iRowid, 
143302   RtreeNode *pNode, 
143303   int iHeight
143304 ){
143305   int (*xSetMapping)(Rtree *, sqlite3_int64, sqlite3_int64);
143306   xSetMapping = ((iHeight==0)?rowidWrite:parentWrite);
143307   if( iHeight>0 ){
143308     RtreeNode *pChild = nodeHashLookup(pRtree, iRowid);
143309     if( pChild ){
143310       nodeRelease(pRtree, pChild->pParent);
143311       nodeReference(pNode);
143312       pChild->pParent = pNode;
143313     }
143314   }
143315   return xSetMapping(pRtree, iRowid, pNode->iNode);
143316 }
143317 
143318 static int SplitNode(
143319   Rtree *pRtree,
143320   RtreeNode *pNode,
143321   RtreeCell *pCell,
143322   int iHeight
143323 ){
143324   int i;
143325   int newCellIsRight = 0;
143326 
143327   int rc = SQLITE_OK;
143328   int nCell = NCELL(pNode);
143329   RtreeCell *aCell;
143330   int *aiUsed;
143331 
143332   RtreeNode *pLeft = 0;
143333   RtreeNode *pRight = 0;
143334 
143335   RtreeCell leftbbox;
143336   RtreeCell rightbbox;
143337 
143338   /* Allocate an array and populate it with a copy of pCell and 
143339   ** all cells from node pLeft. Then zero the original node.
143340   */
143341   aCell = sqlite3_malloc((sizeof(RtreeCell)+sizeof(int))*(nCell+1));
143342   if( !aCell ){
143343     rc = SQLITE_NOMEM;
143344     goto splitnode_out;
143345   }
143346   aiUsed = (int *)&aCell[nCell+1];
143347   memset(aiUsed, 0, sizeof(int)*(nCell+1));
143348   for(i=0; i<nCell; i++){
143349     nodeGetCell(pRtree, pNode, i, &aCell[i]);
143350   }
143351   nodeZero(pRtree, pNode);
143352   memcpy(&aCell[nCell], pCell, sizeof(RtreeCell));
143353   nCell++;
143354 
143355   if( pNode->iNode==1 ){
143356     pRight = nodeNew(pRtree, pNode);
143357     pLeft = nodeNew(pRtree, pNode);
143358     pRtree->iDepth++;
143359     pNode->isDirty = 1;
143360     writeInt16(pNode->zData, pRtree->iDepth);
143361   }else{
143362     pLeft = pNode;
143363     pRight = nodeNew(pRtree, pLeft->pParent);
143364     nodeReference(pLeft);
143365   }
143366 
143367   if( !pLeft || !pRight ){
143368     rc = SQLITE_NOMEM;
143369     goto splitnode_out;
143370   }
143371 
143372   memset(pLeft->zData, 0, pRtree->iNodeSize);
143373   memset(pRight->zData, 0, pRtree->iNodeSize);
143374 
143375   rc = AssignCells(pRtree, aCell, nCell, pLeft, pRight, &leftbbox, &rightbbox);
143376   if( rc!=SQLITE_OK ){
143377     goto splitnode_out;
143378   }
143379 
143380   /* Ensure both child nodes have node numbers assigned to them by calling
143381   ** nodeWrite(). Node pRight always needs a node number, as it was created
143382   ** by nodeNew() above. But node pLeft sometimes already has a node number.
143383   ** In this case avoid the all to nodeWrite().
143384   */
143385   if( SQLITE_OK!=(rc = nodeWrite(pRtree, pRight))
143386    || (0==pLeft->iNode && SQLITE_OK!=(rc = nodeWrite(pRtree, pLeft)))
143387   ){
143388     goto splitnode_out;
143389   }
143390 
143391   rightbbox.iRowid = pRight->iNode;
143392   leftbbox.iRowid = pLeft->iNode;
143393 
143394   if( pNode->iNode==1 ){
143395     rc = rtreeInsertCell(pRtree, pLeft->pParent, &leftbbox, iHeight+1);
143396     if( rc!=SQLITE_OK ){
143397       goto splitnode_out;
143398     }
143399   }else{
143400     RtreeNode *pParent = pLeft->pParent;
143401     int iCell;
143402     rc = nodeParentIndex(pRtree, pLeft, &iCell);
143403     if( rc==SQLITE_OK ){
143404       nodeOverwriteCell(pRtree, pParent, &leftbbox, iCell);
143405       rc = AdjustTree(pRtree, pParent, &leftbbox);
143406     }
143407     if( rc!=SQLITE_OK ){
143408       goto splitnode_out;
143409     }
143410   }
143411   if( (rc = rtreeInsertCell(pRtree, pRight->pParent, &rightbbox, iHeight+1)) ){
143412     goto splitnode_out;
143413   }
143414 
143415   for(i=0; i<NCELL(pRight); i++){
143416     i64 iRowid = nodeGetRowid(pRtree, pRight, i);
143417     rc = updateMapping(pRtree, iRowid, pRight, iHeight);
143418     if( iRowid==pCell->iRowid ){
143419       newCellIsRight = 1;
143420     }
143421     if( rc!=SQLITE_OK ){
143422       goto splitnode_out;
143423     }
143424   }
143425   if( pNode->iNode==1 ){
143426     for(i=0; i<NCELL(pLeft); i++){
143427       i64 iRowid = nodeGetRowid(pRtree, pLeft, i);
143428       rc = updateMapping(pRtree, iRowid, pLeft, iHeight);
143429       if( rc!=SQLITE_OK ){
143430         goto splitnode_out;
143431       }
143432     }
143433   }else if( newCellIsRight==0 ){
143434     rc = updateMapping(pRtree, pCell->iRowid, pLeft, iHeight);
143435   }
143436 
143437   if( rc==SQLITE_OK ){
143438     rc = nodeRelease(pRtree, pRight);
143439     pRight = 0;
143440   }
143441   if( rc==SQLITE_OK ){
143442     rc = nodeRelease(pRtree, pLeft);
143443     pLeft = 0;
143444   }
143445 
143446 splitnode_out:
143447   nodeRelease(pRtree, pRight);
143448   nodeRelease(pRtree, pLeft);
143449   sqlite3_free(aCell);
143450   return rc;
143451 }
143452 
143453 /*
143454 ** If node pLeaf is not the root of the r-tree and its pParent pointer is 
143455 ** still NULL, load all ancestor nodes of pLeaf into memory and populate
143456 ** the pLeaf->pParent chain all the way up to the root node.
143457 **
143458 ** This operation is required when a row is deleted (or updated - an update
143459 ** is implemented as a delete followed by an insert). SQLite provides the
143460 ** rowid of the row to delete, which can be used to find the leaf on which
143461 ** the entry resides (argument pLeaf). Once the leaf is located, this 
143462 ** function is called to determine its ancestry.
143463 */
143464 static int fixLeafParent(Rtree *pRtree, RtreeNode *pLeaf){
143465   int rc = SQLITE_OK;
143466   RtreeNode *pChild = pLeaf;
143467   while( rc==SQLITE_OK && pChild->iNode!=1 && pChild->pParent==0 ){
143468     int rc2 = SQLITE_OK;          /* sqlite3_reset() return code */
143469     sqlite3_bind_int64(pRtree->pReadParent, 1, pChild->iNode);
143470     rc = sqlite3_step(pRtree->pReadParent);
143471     if( rc==SQLITE_ROW ){
143472       RtreeNode *pTest;           /* Used to test for reference loops */
143473       i64 iNode;                  /* Node number of parent node */
143474 
143475       /* Before setting pChild->pParent, test that we are not creating a
143476       ** loop of references (as we would if, say, pChild==pParent). We don't
143477       ** want to do this as it leads to a memory leak when trying to delete
143478       ** the referenced counted node structures.
143479       */
143480       iNode = sqlite3_column_int64(pRtree->pReadParent, 0);
143481       for(pTest=pLeaf; pTest && pTest->iNode!=iNode; pTest=pTest->pParent);
143482       if( !pTest ){
143483         rc2 = nodeAcquire(pRtree, iNode, 0, &pChild->pParent);
143484       }
143485     }
143486     rc = sqlite3_reset(pRtree->pReadParent);
143487     if( rc==SQLITE_OK ) rc = rc2;
143488     if( rc==SQLITE_OK && !pChild->pParent ) rc = SQLITE_CORRUPT_VTAB;
143489     pChild = pChild->pParent;
143490   }
143491   return rc;
143492 }
143493 
143494 static int deleteCell(Rtree *, RtreeNode *, int, int);
143495 
143496 static int removeNode(Rtree *pRtree, RtreeNode *pNode, int iHeight){
143497   int rc;
143498   int rc2;
143499   RtreeNode *pParent = 0;
143500   int iCell;
143501 
143502   assert( pNode->nRef==1 );
143503 
143504   /* Remove the entry in the parent cell. */
143505   rc = nodeParentIndex(pRtree, pNode, &iCell);
143506   if( rc==SQLITE_OK ){
143507     pParent = pNode->pParent;
143508     pNode->pParent = 0;
143509     rc = deleteCell(pRtree, pParent, iCell, iHeight+1);
143510   }
143511   rc2 = nodeRelease(pRtree, pParent);
143512   if( rc==SQLITE_OK ){
143513     rc = rc2;
143514   }
143515   if( rc!=SQLITE_OK ){
143516     return rc;
143517   }
143518 
143519   /* Remove the xxx_node entry. */
143520   sqlite3_bind_int64(pRtree->pDeleteNode, 1, pNode->iNode);
143521   sqlite3_step(pRtree->pDeleteNode);
143522   if( SQLITE_OK!=(rc = sqlite3_reset(pRtree->pDeleteNode)) ){
143523     return rc;
143524   }
143525 
143526   /* Remove the xxx_parent entry. */
143527   sqlite3_bind_int64(pRtree->pDeleteParent, 1, pNode->iNode);
143528   sqlite3_step(pRtree->pDeleteParent);
143529   if( SQLITE_OK!=(rc = sqlite3_reset(pRtree->pDeleteParent)) ){
143530     return rc;
143531   }
143532   
143533   /* Remove the node from the in-memory hash table and link it into
143534   ** the Rtree.pDeleted list. Its contents will be re-inserted later on.
143535   */
143536   nodeHashDelete(pRtree, pNode);
143537   pNode->iNode = iHeight;
143538   pNode->pNext = pRtree->pDeleted;
143539   pNode->nRef++;
143540   pRtree->pDeleted = pNode;
143541 
143542   return SQLITE_OK;
143543 }
143544 
143545 static int fixBoundingBox(Rtree *pRtree, RtreeNode *pNode){
143546   RtreeNode *pParent = pNode->pParent;
143547   int rc = SQLITE_OK; 
143548   if( pParent ){
143549     int ii; 
143550     int nCell = NCELL(pNode);
143551     RtreeCell box;                            /* Bounding box for pNode */
143552     nodeGetCell(pRtree, pNode, 0, &box);
143553     for(ii=1; ii<nCell; ii++){
143554       RtreeCell cell;
143555       nodeGetCell(pRtree, pNode, ii, &cell);
143556       cellUnion(pRtree, &box, &cell);
143557     }
143558     box.iRowid = pNode->iNode;
143559     rc = nodeParentIndex(pRtree, pNode, &ii);
143560     if( rc==SQLITE_OK ){
143561       nodeOverwriteCell(pRtree, pParent, &box, ii);
143562       rc = fixBoundingBox(pRtree, pParent);
143563     }
143564   }
143565   return rc;
143566 }
143567 
143568 /*
143569 ** Delete the cell at index iCell of node pNode. After removing the
143570 ** cell, adjust the r-tree data structure if required.
143571 */
143572 static int deleteCell(Rtree *pRtree, RtreeNode *pNode, int iCell, int iHeight){
143573   RtreeNode *pParent;
143574   int rc;
143575 
143576   if( SQLITE_OK!=(rc = fixLeafParent(pRtree, pNode)) ){
143577     return rc;
143578   }
143579 
143580   /* Remove the cell from the node. This call just moves bytes around
143581   ** the in-memory node image, so it cannot fail.
143582   */
143583   nodeDeleteCell(pRtree, pNode, iCell);
143584 
143585   /* If the node is not the tree root and now has less than the minimum
143586   ** number of cells, remove it from the tree. Otherwise, update the
143587   ** cell in the parent node so that it tightly contains the updated
143588   ** node.
143589   */
143590   pParent = pNode->pParent;
143591   assert( pParent || pNode->iNode==1 );
143592   if( pParent ){
143593     if( NCELL(pNode)<RTREE_MINCELLS(pRtree) ){
143594       rc = removeNode(pRtree, pNode, iHeight);
143595     }else{
143596       rc = fixBoundingBox(pRtree, pNode);
143597     }
143598   }
143599 
143600   return rc;
143601 }
143602 
143603 static int Reinsert(
143604   Rtree *pRtree, 
143605   RtreeNode *pNode, 
143606   RtreeCell *pCell, 
143607   int iHeight
143608 ){
143609   int *aOrder;
143610   int *aSpare;
143611   RtreeCell *aCell;
143612   RtreeDValue *aDistance;
143613   int nCell;
143614   RtreeDValue aCenterCoord[RTREE_MAX_DIMENSIONS];
143615   int iDim;
143616   int ii;
143617   int rc = SQLITE_OK;
143618   int n;
143619 
143620   memset(aCenterCoord, 0, sizeof(RtreeDValue)*RTREE_MAX_DIMENSIONS);
143621 
143622   nCell = NCELL(pNode)+1;
143623   n = (nCell+1)&(~1);
143624 
143625   /* Allocate the buffers used by this operation. The allocation is
143626   ** relinquished before this function returns.
143627   */
143628   aCell = (RtreeCell *)sqlite3_malloc(n * (
143629     sizeof(RtreeCell)     +         /* aCell array */
143630     sizeof(int)           +         /* aOrder array */
143631     sizeof(int)           +         /* aSpare array */
143632     sizeof(RtreeDValue)             /* aDistance array */
143633   ));
143634   if( !aCell ){
143635     return SQLITE_NOMEM;
143636   }
143637   aOrder    = (int *)&aCell[n];
143638   aSpare    = (int *)&aOrder[n];
143639   aDistance = (RtreeDValue *)&aSpare[n];
143640 
143641   for(ii=0; ii<nCell; ii++){
143642     if( ii==(nCell-1) ){
143643       memcpy(&aCell[ii], pCell, sizeof(RtreeCell));
143644     }else{
143645       nodeGetCell(pRtree, pNode, ii, &aCell[ii]);
143646     }
143647     aOrder[ii] = ii;
143648     for(iDim=0; iDim<pRtree->nDim; iDim++){
143649       aCenterCoord[iDim] += DCOORD(aCell[ii].aCoord[iDim*2]);
143650       aCenterCoord[iDim] += DCOORD(aCell[ii].aCoord[iDim*2+1]);
143651     }
143652   }
143653   for(iDim=0; iDim<pRtree->nDim; iDim++){
143654     aCenterCoord[iDim] = (aCenterCoord[iDim]/(nCell*(RtreeDValue)2));
143655   }
143656 
143657   for(ii=0; ii<nCell; ii++){
143658     aDistance[ii] = 0.0;
143659     for(iDim=0; iDim<pRtree->nDim; iDim++){
143660       RtreeDValue coord = (DCOORD(aCell[ii].aCoord[iDim*2+1]) - 
143661                                DCOORD(aCell[ii].aCoord[iDim*2]));
143662       aDistance[ii] += (coord-aCenterCoord[iDim])*(coord-aCenterCoord[iDim]);
143663     }
143664   }
143665 
143666   SortByDistance(aOrder, nCell, aDistance, aSpare);
143667   nodeZero(pRtree, pNode);
143668 
143669   for(ii=0; rc==SQLITE_OK && ii<(nCell-(RTREE_MINCELLS(pRtree)+1)); ii++){
143670     RtreeCell *p = &aCell[aOrder[ii]];
143671     nodeInsertCell(pRtree, pNode, p);
143672     if( p->iRowid==pCell->iRowid ){
143673       if( iHeight==0 ){
143674         rc = rowidWrite(pRtree, p->iRowid, pNode->iNode);
143675       }else{
143676         rc = parentWrite(pRtree, p->iRowid, pNode->iNode);
143677       }
143678     }
143679   }
143680   if( rc==SQLITE_OK ){
143681     rc = fixBoundingBox(pRtree, pNode);
143682   }
143683   for(; rc==SQLITE_OK && ii<nCell; ii++){
143684     /* Find a node to store this cell in. pNode->iNode currently contains
143685     ** the height of the sub-tree headed by the cell.
143686     */
143687     RtreeNode *pInsert;
143688     RtreeCell *p = &aCell[aOrder[ii]];
143689     rc = ChooseLeaf(pRtree, p, iHeight, &pInsert);
143690     if( rc==SQLITE_OK ){
143691       int rc2;
143692       rc = rtreeInsertCell(pRtree, pInsert, p, iHeight);
143693       rc2 = nodeRelease(pRtree, pInsert);
143694       if( rc==SQLITE_OK ){
143695         rc = rc2;
143696       }
143697     }
143698   }
143699 
143700   sqlite3_free(aCell);
143701   return rc;
143702 }
143703 
143704 /*
143705 ** Insert cell pCell into node pNode. Node pNode is the head of a 
143706 ** subtree iHeight high (leaf nodes have iHeight==0).
143707 */
143708 static int rtreeInsertCell(
143709   Rtree *pRtree,
143710   RtreeNode *pNode,
143711   RtreeCell *pCell,
143712   int iHeight
143713 ){
143714   int rc = SQLITE_OK;
143715   if( iHeight>0 ){
143716     RtreeNode *pChild = nodeHashLookup(pRtree, pCell->iRowid);
143717     if( pChild ){
143718       nodeRelease(pRtree, pChild->pParent);
143719       nodeReference(pNode);
143720       pChild->pParent = pNode;
143721     }
143722   }
143723   if( nodeInsertCell(pRtree, pNode, pCell) ){
143724 #if VARIANT_RSTARTREE_REINSERT
143725     if( iHeight<=pRtree->iReinsertHeight || pNode->iNode==1){
143726       rc = SplitNode(pRtree, pNode, pCell, iHeight);
143727     }else{
143728       pRtree->iReinsertHeight = iHeight;
143729       rc = Reinsert(pRtree, pNode, pCell, iHeight);
143730     }
143731 #else
143732     rc = SplitNode(pRtree, pNode, pCell, iHeight);
143733 #endif
143734   }else{
143735     rc = AdjustTree(pRtree, pNode, pCell);
143736     if( rc==SQLITE_OK ){
143737       if( iHeight==0 ){
143738         rc = rowidWrite(pRtree, pCell->iRowid, pNode->iNode);
143739       }else{
143740         rc = parentWrite(pRtree, pCell->iRowid, pNode->iNode);
143741       }
143742     }
143743   }
143744   return rc;
143745 }
143746 
143747 static int reinsertNodeContent(Rtree *pRtree, RtreeNode *pNode){
143748   int ii;
143749   int rc = SQLITE_OK;
143750   int nCell = NCELL(pNode);
143751 
143752   for(ii=0; rc==SQLITE_OK && ii<nCell; ii++){
143753     RtreeNode *pInsert;
143754     RtreeCell cell;
143755     nodeGetCell(pRtree, pNode, ii, &cell);
143756 
143757     /* Find a node to store this cell in. pNode->iNode currently contains
143758     ** the height of the sub-tree headed by the cell.
143759     */
143760     rc = ChooseLeaf(pRtree, &cell, (int)pNode->iNode, &pInsert);
143761     if( rc==SQLITE_OK ){
143762       int rc2;
143763       rc = rtreeInsertCell(pRtree, pInsert, &cell, (int)pNode->iNode);
143764       rc2 = nodeRelease(pRtree, pInsert);
143765       if( rc==SQLITE_OK ){
143766         rc = rc2;
143767       }
143768     }
143769   }
143770   return rc;
143771 }
143772 
143773 /*
143774 ** Select a currently unused rowid for a new r-tree record.
143775 */
143776 static int newRowid(Rtree *pRtree, i64 *piRowid){
143777   int rc;
143778   sqlite3_bind_null(pRtree->pWriteRowid, 1);
143779   sqlite3_bind_null(pRtree->pWriteRowid, 2);
143780   sqlite3_step(pRtree->pWriteRowid);
143781   rc = sqlite3_reset(pRtree->pWriteRowid);
143782   *piRowid = sqlite3_last_insert_rowid(pRtree->db);
143783   return rc;
143784 }
143785 
143786 /*
143787 ** Remove the entry with rowid=iDelete from the r-tree structure.
143788 */
143789 static int rtreeDeleteRowid(Rtree *pRtree, sqlite3_int64 iDelete){
143790   int rc;                         /* Return code */
143791   RtreeNode *pLeaf = 0;           /* Leaf node containing record iDelete */
143792   int iCell;                      /* Index of iDelete cell in pLeaf */
143793   RtreeNode *pRoot;               /* Root node of rtree structure */
143794 
143795 
143796   /* Obtain a reference to the root node to initialize Rtree.iDepth */
143797   rc = nodeAcquire(pRtree, 1, 0, &pRoot);
143798 
143799   /* Obtain a reference to the leaf node that contains the entry 
143800   ** about to be deleted. 
143801   */
143802   if( rc==SQLITE_OK ){
143803     rc = findLeafNode(pRtree, iDelete, &pLeaf);
143804   }
143805 
143806   /* Delete the cell in question from the leaf node. */
143807   if( rc==SQLITE_OK ){
143808     int rc2;
143809     rc = nodeRowidIndex(pRtree, pLeaf, iDelete, &iCell);
143810     if( rc==SQLITE_OK ){
143811       rc = deleteCell(pRtree, pLeaf, iCell, 0);
143812     }
143813     rc2 = nodeRelease(pRtree, pLeaf);
143814     if( rc==SQLITE_OK ){
143815       rc = rc2;
143816     }
143817   }
143818 
143819   /* Delete the corresponding entry in the <rtree>_rowid table. */
143820   if( rc==SQLITE_OK ){
143821     sqlite3_bind_int64(pRtree->pDeleteRowid, 1, iDelete);
143822     sqlite3_step(pRtree->pDeleteRowid);
143823     rc = sqlite3_reset(pRtree->pDeleteRowid);
143824   }
143825 
143826   /* Check if the root node now has exactly one child. If so, remove
143827   ** it, schedule the contents of the child for reinsertion and 
143828   ** reduce the tree height by one.
143829   **
143830   ** This is equivalent to copying the contents of the child into
143831   ** the root node (the operation that Gutman's paper says to perform 
143832   ** in this scenario).
143833   */
143834   if( rc==SQLITE_OK && pRtree->iDepth>0 && NCELL(pRoot)==1 ){
143835     int rc2;
143836     RtreeNode *pChild;
143837     i64 iChild = nodeGetRowid(pRtree, pRoot, 0);
143838     rc = nodeAcquire(pRtree, iChild, pRoot, &pChild);
143839     if( rc==SQLITE_OK ){
143840       rc = removeNode(pRtree, pChild, pRtree->iDepth-1);
143841     }
143842     rc2 = nodeRelease(pRtree, pChild);
143843     if( rc==SQLITE_OK ) rc = rc2;
143844     if( rc==SQLITE_OK ){
143845       pRtree->iDepth--;
143846       writeInt16(pRoot->zData, pRtree->iDepth);
143847       pRoot->isDirty = 1;
143848     }
143849   }
143850 
143851   /* Re-insert the contents of any underfull nodes removed from the tree. */
143852   for(pLeaf=pRtree->pDeleted; pLeaf; pLeaf=pRtree->pDeleted){
143853     if( rc==SQLITE_OK ){
143854       rc = reinsertNodeContent(pRtree, pLeaf);
143855     }
143856     pRtree->pDeleted = pLeaf->pNext;
143857     sqlite3_free(pLeaf);
143858   }
143859 
143860   /* Release the reference to the root node. */
143861   if( rc==SQLITE_OK ){
143862     rc = nodeRelease(pRtree, pRoot);
143863   }else{
143864     nodeRelease(pRtree, pRoot);
143865   }
143866 
143867   return rc;
143868 }
143869 
143870 /*
143871 ** Rounding constants for float->double conversion.
143872 */
143873 #define RNDTOWARDS  (1.0 - 1.0/8388608.0)  /* Round towards zero */
143874 #define RNDAWAY     (1.0 + 1.0/8388608.0)  /* Round away from zero */
143875 
143876 #if !defined(SQLITE_RTREE_INT_ONLY)
143877 /*
143878 ** Convert an sqlite3_value into an RtreeValue (presumably a float)
143879 ** while taking care to round toward negative or positive, respectively.
143880 */
143881 static RtreeValue rtreeValueDown(sqlite3_value *v){
143882   double d = sqlite3_value_double(v);
143883   float f = (float)d;
143884   if( f>d ){
143885     f = (float)(d*(d<0 ? RNDAWAY : RNDTOWARDS));
143886   }
143887   return f;
143888 }
143889 static RtreeValue rtreeValueUp(sqlite3_value *v){
143890   double d = sqlite3_value_double(v);
143891   float f = (float)d;
143892   if( f<d ){
143893     f = (float)(d*(d<0 ? RNDTOWARDS : RNDAWAY));
143894   }
143895   return f;
143896 }
143897 #endif /* !defined(SQLITE_RTREE_INT_ONLY) */
143898 
143899 
143900 /*
143901 ** The xUpdate method for rtree module virtual tables.
143902 */
143903 static int rtreeUpdate(
143904   sqlite3_vtab *pVtab, 
143905   int nData, 
143906   sqlite3_value **azData, 
143907   sqlite_int64 *pRowid
143908 ){
143909   Rtree *pRtree = (Rtree *)pVtab;
143910   int rc = SQLITE_OK;
143911   RtreeCell cell;                 /* New cell to insert if nData>1 */
143912   int bHaveRowid = 0;             /* Set to 1 after new rowid is determined */
143913 
143914   rtreeReference(pRtree);
143915   assert(nData>=1);
143916 
143917   /* Constraint handling. A write operation on an r-tree table may return
143918   ** SQLITE_CONSTRAINT for two reasons:
143919   **
143920   **   1. A duplicate rowid value, or
143921   **   2. The supplied data violates the "x2>=x1" constraint.
143922   **
143923   ** In the first case, if the conflict-handling mode is REPLACE, then
143924   ** the conflicting row can be removed before proceeding. In the second
143925   ** case, SQLITE_CONSTRAINT must be returned regardless of the
143926   ** conflict-handling mode specified by the user.
143927   */
143928   if( nData>1 ){
143929     int ii;
143930 
143931     /* Populate the cell.aCoord[] array. The first coordinate is azData[3]. */
143932     assert( nData==(pRtree->nDim*2 + 3) );
143933 #ifndef SQLITE_RTREE_INT_ONLY
143934     if( pRtree->eCoordType==RTREE_COORD_REAL32 ){
143935       for(ii=0; ii<(pRtree->nDim*2); ii+=2){
143936         cell.aCoord[ii].f = rtreeValueDown(azData[ii+3]);
143937         cell.aCoord[ii+1].f = rtreeValueUp(azData[ii+4]);
143938         if( cell.aCoord[ii].f>cell.aCoord[ii+1].f ){
143939           rc = SQLITE_CONSTRAINT;
143940           goto constraint;
143941         }
143942       }
143943     }else
143944 #endif
143945     {
143946       for(ii=0; ii<(pRtree->nDim*2); ii+=2){
143947         cell.aCoord[ii].i = sqlite3_value_int(azData[ii+3]);
143948         cell.aCoord[ii+1].i = sqlite3_value_int(azData[ii+4]);
143949         if( cell.aCoord[ii].i>cell.aCoord[ii+1].i ){
143950           rc = SQLITE_CONSTRAINT;
143951           goto constraint;
143952         }
143953       }
143954     }
143955 
143956     /* If a rowid value was supplied, check if it is already present in 
143957     ** the table. If so, the constraint has failed. */
143958     if( sqlite3_value_type(azData[2])!=SQLITE_NULL ){
143959       cell.iRowid = sqlite3_value_int64(azData[2]);
143960       if( sqlite3_value_type(azData[0])==SQLITE_NULL
143961        || sqlite3_value_int64(azData[0])!=cell.iRowid
143962       ){
143963         int steprc;
143964         sqlite3_bind_int64(pRtree->pReadRowid, 1, cell.iRowid);
143965         steprc = sqlite3_step(pRtree->pReadRowid);
143966         rc = sqlite3_reset(pRtree->pReadRowid);
143967         if( SQLITE_ROW==steprc ){
143968           if( sqlite3_vtab_on_conflict(pRtree->db)==SQLITE_REPLACE ){
143969             rc = rtreeDeleteRowid(pRtree, cell.iRowid);
143970           }else{
143971             rc = SQLITE_CONSTRAINT;
143972             goto constraint;
143973           }
143974         }
143975       }
143976       bHaveRowid = 1;
143977     }
143978   }
143979 
143980   /* If azData[0] is not an SQL NULL value, it is the rowid of a
143981   ** record to delete from the r-tree table. The following block does
143982   ** just that.
143983   */
143984   if( sqlite3_value_type(azData[0])!=SQLITE_NULL ){
143985     rc = rtreeDeleteRowid(pRtree, sqlite3_value_int64(azData[0]));
143986   }
143987 
143988   /* If the azData[] array contains more than one element, elements
143989   ** (azData[2]..azData[argc-1]) contain a new record to insert into
143990   ** the r-tree structure.
143991   */
143992   if( rc==SQLITE_OK && nData>1 ){
143993     /* Insert the new record into the r-tree */
143994     RtreeNode *pLeaf = 0;
143995 
143996     /* Figure out the rowid of the new row. */
143997     if( bHaveRowid==0 ){
143998       rc = newRowid(pRtree, &cell.iRowid);
143999     }
144000     *pRowid = cell.iRowid;
144001 
144002     if( rc==SQLITE_OK ){
144003       rc = ChooseLeaf(pRtree, &cell, 0, &pLeaf);
144004     }
144005     if( rc==SQLITE_OK ){
144006       int rc2;
144007       pRtree->iReinsertHeight = -1;
144008       rc = rtreeInsertCell(pRtree, pLeaf, &cell, 0);
144009       rc2 = nodeRelease(pRtree, pLeaf);
144010       if( rc==SQLITE_OK ){
144011         rc = rc2;
144012       }
144013     }
144014   }
144015 
144016 constraint:
144017   rtreeRelease(pRtree);
144018   return rc;
144019 }
144020 
144021 /*
144022 ** The xRename method for rtree module virtual tables.
144023 */
144024 static int rtreeRename(sqlite3_vtab *pVtab, const char *zNewName){
144025   Rtree *pRtree = (Rtree *)pVtab;
144026   int rc = SQLITE_NOMEM;
144027   char *zSql = sqlite3_mprintf(
144028     "ALTER TABLE %Q.'%q_node'   RENAME TO \"%w_node\";"
144029     "ALTER TABLE %Q.'%q_parent' RENAME TO \"%w_parent\";"
144030     "ALTER TABLE %Q.'%q_rowid'  RENAME TO \"%w_rowid\";"
144031     , pRtree->zDb, pRtree->zName, zNewName 
144032     , pRtree->zDb, pRtree->zName, zNewName 
144033     , pRtree->zDb, pRtree->zName, zNewName
144034   );
144035   if( zSql ){
144036     rc = sqlite3_exec(pRtree->db, zSql, 0, 0, 0);
144037     sqlite3_free(zSql);
144038   }
144039   return rc;
144040 }
144041 
144042 /*
144043 ** This function populates the pRtree->nRowEst variable with an estimate
144044 ** of the number of rows in the virtual table. If possible, this is based
144045 ** on sqlite_stat1 data. Otherwise, use RTREE_DEFAULT_ROWEST.
144046 */
144047 static int rtreeQueryStat1(sqlite3 *db, Rtree *pRtree){
144048   const char *zSql = "SELECT stat FROM sqlite_stat1 WHERE tbl= ? || '_rowid'";
144049   sqlite3_stmt *p;
144050   int rc;
144051   i64 nRow = 0;
144052 
144053   rc = sqlite3_prepare_v2(db, zSql, -1, &p, 0);
144054   if( rc==SQLITE_OK ){
144055     sqlite3_bind_text(p, 1, pRtree->zName, -1, SQLITE_STATIC);
144056     if( sqlite3_step(p)==SQLITE_ROW ) nRow = sqlite3_column_int64(p, 0);
144057     rc = sqlite3_finalize(p);
144058   }else if( rc!=SQLITE_NOMEM ){
144059     rc = SQLITE_OK;
144060   }
144061 
144062   if( rc==SQLITE_OK ){
144063     if( nRow==0 ){
144064       pRtree->nRowEst = RTREE_DEFAULT_ROWEST;
144065     }else{
144066       pRtree->nRowEst = MAX(nRow, RTREE_MIN_ROWEST);
144067     }
144068   }
144069 
144070   return rc;
144071 }
144072 
144073 static sqlite3_module rtreeModule = {
144074   0,                          /* iVersion */
144075   rtreeCreate,                /* xCreate - create a table */
144076   rtreeConnect,               /* xConnect - connect to an existing table */
144077   rtreeBestIndex,             /* xBestIndex - Determine search strategy */
144078   rtreeDisconnect,            /* xDisconnect - Disconnect from a table */
144079   rtreeDestroy,               /* xDestroy - Drop a table */
144080   rtreeOpen,                  /* xOpen - open a cursor */
144081   rtreeClose,                 /* xClose - close a cursor */
144082   rtreeFilter,                /* xFilter - configure scan constraints */
144083   rtreeNext,                  /* xNext - advance a cursor */
144084   rtreeEof,                   /* xEof */
144085   rtreeColumn,                /* xColumn - read data */
144086   rtreeRowid,                 /* xRowid - read data */
144087   rtreeUpdate,                /* xUpdate - write data */
144088   0,                          /* xBegin - begin transaction */
144089   0,                          /* xSync - sync transaction */
144090   0,                          /* xCommit - commit transaction */
144091   0,                          /* xRollback - rollback transaction */
144092   0,                          /* xFindFunction - function overloading */
144093   rtreeRename,                /* xRename - rename the table */
144094   0,                          /* xSavepoint */
144095   0,                          /* xRelease */
144096   0                           /* xRollbackTo */
144097 };
144098 
144099 static int rtreeSqlInit(
144100   Rtree *pRtree, 
144101   sqlite3 *db, 
144102   const char *zDb, 
144103   const char *zPrefix, 
144104   int isCreate
144105 ){
144106   int rc = SQLITE_OK;
144107 
144108   #define N_STATEMENT 9
144109   static const char *azSql[N_STATEMENT] = {
144110     /* Read and write the xxx_node table */
144111     "SELECT data FROM '%q'.'%q_node' WHERE nodeno = :1",
144112     "INSERT OR REPLACE INTO '%q'.'%q_node' VALUES(:1, :2)",
144113     "DELETE FROM '%q'.'%q_node' WHERE nodeno = :1",
144114 
144115     /* Read and write the xxx_rowid table */
144116     "SELECT nodeno FROM '%q'.'%q_rowid' WHERE rowid = :1",
144117     "INSERT OR REPLACE INTO '%q'.'%q_rowid' VALUES(:1, :2)",
144118     "DELETE FROM '%q'.'%q_rowid' WHERE rowid = :1",
144119 
144120     /* Read and write the xxx_parent table */
144121     "SELECT parentnode FROM '%q'.'%q_parent' WHERE nodeno = :1",
144122     "INSERT OR REPLACE INTO '%q'.'%q_parent' VALUES(:1, :2)",
144123     "DELETE FROM '%q'.'%q_parent' WHERE nodeno = :1"
144124   };
144125   sqlite3_stmt **appStmt[N_STATEMENT];
144126   int i;
144127 
144128   pRtree->db = db;
144129 
144130   if( isCreate ){
144131     char *zCreate = sqlite3_mprintf(
144132 "CREATE TABLE \"%w\".\"%w_node\"(nodeno INTEGER PRIMARY KEY, data BLOB);"
144133 "CREATE TABLE \"%w\".\"%w_rowid\"(rowid INTEGER PRIMARY KEY, nodeno INTEGER);"
144134 "CREATE TABLE \"%w\".\"%w_parent\"(nodeno INTEGER PRIMARY KEY, parentnode INTEGER);"
144135 "INSERT INTO '%q'.'%q_node' VALUES(1, zeroblob(%d))",
144136       zDb, zPrefix, zDb, zPrefix, zDb, zPrefix, zDb, zPrefix, pRtree->iNodeSize
144137     );
144138     if( !zCreate ){
144139       return SQLITE_NOMEM;
144140     }
144141     rc = sqlite3_exec(db, zCreate, 0, 0, 0);
144142     sqlite3_free(zCreate);
144143     if( rc!=SQLITE_OK ){
144144       return rc;
144145     }
144146   }
144147 
144148   appStmt[0] = &pRtree->pReadNode;
144149   appStmt[1] = &pRtree->pWriteNode;
144150   appStmt[2] = &pRtree->pDeleteNode;
144151   appStmt[3] = &pRtree->pReadRowid;
144152   appStmt[4] = &pRtree->pWriteRowid;
144153   appStmt[5] = &pRtree->pDeleteRowid;
144154   appStmt[6] = &pRtree->pReadParent;
144155   appStmt[7] = &pRtree->pWriteParent;
144156   appStmt[8] = &pRtree->pDeleteParent;
144157 
144158   rc = rtreeQueryStat1(db, pRtree);
144159   for(i=0; i<N_STATEMENT && rc==SQLITE_OK; i++){
144160     char *zSql = sqlite3_mprintf(azSql[i], zDb, zPrefix);
144161     if( zSql ){
144162       rc = sqlite3_prepare_v2(db, zSql, -1, appStmt[i], 0); 
144163     }else{
144164       rc = SQLITE_NOMEM;
144165     }
144166     sqlite3_free(zSql);
144167   }
144168 
144169   return rc;
144170 }
144171 
144172 /*
144173 ** The second argument to this function contains the text of an SQL statement
144174 ** that returns a single integer value. The statement is compiled and executed
144175 ** using database connection db. If successful, the integer value returned
144176 ** is written to *piVal and SQLITE_OK returned. Otherwise, an SQLite error
144177 ** code is returned and the value of *piVal after returning is not defined.
144178 */
144179 static int getIntFromStmt(sqlite3 *db, const char *zSql, int *piVal){
144180   int rc = SQLITE_NOMEM;
144181   if( zSql ){
144182     sqlite3_stmt *pStmt = 0;
144183     rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);
144184     if( rc==SQLITE_OK ){
144185       if( SQLITE_ROW==sqlite3_step(pStmt) ){
144186         *piVal = sqlite3_column_int(pStmt, 0);
144187       }
144188       rc = sqlite3_finalize(pStmt);
144189     }
144190   }
144191   return rc;
144192 }
144193 
144194 /*
144195 ** This function is called from within the xConnect() or xCreate() method to
144196 ** determine the node-size used by the rtree table being created or connected
144197 ** to. If successful, pRtree->iNodeSize is populated and SQLITE_OK returned.
144198 ** Otherwise, an SQLite error code is returned.
144199 **
144200 ** If this function is being called as part of an xConnect(), then the rtree
144201 ** table already exists. In this case the node-size is determined by inspecting
144202 ** the root node of the tree.
144203 **
144204 ** Otherwise, for an xCreate(), use 64 bytes less than the database page-size. 
144205 ** This ensures that each node is stored on a single database page. If the 
144206 ** database page-size is so large that more than RTREE_MAXCELLS entries 
144207 ** would fit in a single node, use a smaller node-size.
144208 */
144209 static int getNodeSize(
144210   sqlite3 *db,                    /* Database handle */
144211   Rtree *pRtree,                  /* Rtree handle */
144212   int isCreate,                   /* True for xCreate, false for xConnect */
144213   char **pzErr                    /* OUT: Error message, if any */
144214 ){
144215   int rc;
144216   char *zSql;
144217   if( isCreate ){
144218     int iPageSize = 0;
144219     zSql = sqlite3_mprintf("PRAGMA %Q.page_size", pRtree->zDb);
144220     rc = getIntFromStmt(db, zSql, &iPageSize);
144221     if( rc==SQLITE_OK ){
144222       pRtree->iNodeSize = iPageSize-64;
144223       if( (4+pRtree->nBytesPerCell*RTREE_MAXCELLS)<pRtree->iNodeSize ){
144224         pRtree->iNodeSize = 4+pRtree->nBytesPerCell*RTREE_MAXCELLS;
144225       }
144226     }else{
144227       *pzErr = sqlite3_mprintf("%s", sqlite3_errmsg(db));
144228     }
144229   }else{
144230     zSql = sqlite3_mprintf(
144231         "SELECT length(data) FROM '%q'.'%q_node' WHERE nodeno = 1",
144232         pRtree->zDb, pRtree->zName
144233     );
144234     rc = getIntFromStmt(db, zSql, &pRtree->iNodeSize);
144235     if( rc!=SQLITE_OK ){
144236       *pzErr = sqlite3_mprintf("%s", sqlite3_errmsg(db));
144237     }
144238   }
144239 
144240   sqlite3_free(zSql);
144241   return rc;
144242 }
144243 
144244 /* 
144245 ** This function is the implementation of both the xConnect and xCreate
144246 ** methods of the r-tree virtual table.
144247 **
144248 **   argv[0]   -> module name
144249 **   argv[1]   -> database name
144250 **   argv[2]   -> table name
144251 **   argv[...] -> column names...
144252 */
144253 static int rtreeInit(
144254   sqlite3 *db,                        /* Database connection */
144255   void *pAux,                         /* One of the RTREE_COORD_* constants */
144256   int argc, const char *const*argv,   /* Parameters to CREATE TABLE statement */
144257   sqlite3_vtab **ppVtab,              /* OUT: New virtual table */
144258   char **pzErr,                       /* OUT: Error message, if any */
144259   int isCreate                        /* True for xCreate, false for xConnect */
144260 ){
144261   int rc = SQLITE_OK;
144262   Rtree *pRtree;
144263   int nDb;              /* Length of string argv[1] */
144264   int nName;            /* Length of string argv[2] */
144265   int eCoordType = (pAux ? RTREE_COORD_INT32 : RTREE_COORD_REAL32);
144266 
144267   const char *aErrMsg[] = {
144268     0,                                                    /* 0 */
144269     "Wrong number of columns for an rtree table",         /* 1 */
144270     "Too few columns for an rtree table",                 /* 2 */
144271     "Too many columns for an rtree table"                 /* 3 */
144272   };
144273 
144274   int iErr = (argc<6) ? 2 : argc>(RTREE_MAX_DIMENSIONS*2+4) ? 3 : argc%2;
144275   if( aErrMsg[iErr] ){
144276     *pzErr = sqlite3_mprintf("%s", aErrMsg[iErr]);
144277     return SQLITE_ERROR;
144278   }
144279 
144280   sqlite3_vtab_config(db, SQLITE_VTAB_CONSTRAINT_SUPPORT, 1);
144281 
144282   /* Allocate the sqlite3_vtab structure */
144283   nDb = (int)strlen(argv[1]);
144284   nName = (int)strlen(argv[2]);
144285   pRtree = (Rtree *)sqlite3_malloc(sizeof(Rtree)+nDb+nName+2);
144286   if( !pRtree ){
144287     return SQLITE_NOMEM;
144288   }
144289   memset(pRtree, 0, sizeof(Rtree)+nDb+nName+2);
144290   pRtree->nBusy = 1;
144291   pRtree->base.pModule = &rtreeModule;
144292   pRtree->zDb = (char *)&pRtree[1];
144293   pRtree->zName = &pRtree->zDb[nDb+1];
144294   pRtree->nDim = (argc-4)/2;
144295   pRtree->nBytesPerCell = 8 + pRtree->nDim*4*2;
144296   pRtree->eCoordType = eCoordType;
144297   memcpy(pRtree->zDb, argv[1], nDb);
144298   memcpy(pRtree->zName, argv[2], nName);
144299 
144300   /* Figure out the node size to use. */
144301   rc = getNodeSize(db, pRtree, isCreate, pzErr);
144302 
144303   /* Create/Connect to the underlying relational database schema. If
144304   ** that is successful, call sqlite3_declare_vtab() to configure
144305   ** the r-tree table schema.
144306   */
144307   if( rc==SQLITE_OK ){
144308     if( (rc = rtreeSqlInit(pRtree, db, argv[1], argv[2], isCreate)) ){
144309       *pzErr = sqlite3_mprintf("%s", sqlite3_errmsg(db));
144310     }else{
144311       char *zSql = sqlite3_mprintf("CREATE TABLE x(%s", argv[3]);
144312       char *zTmp;
144313       int ii;
144314       for(ii=4; zSql && ii<argc; ii++){
144315         zTmp = zSql;
144316         zSql = sqlite3_mprintf("%s, %s", zTmp, argv[ii]);
144317         sqlite3_free(zTmp);
144318       }
144319       if( zSql ){
144320         zTmp = zSql;
144321         zSql = sqlite3_mprintf("%s);", zTmp);
144322         sqlite3_free(zTmp);
144323       }
144324       if( !zSql ){
144325         rc = SQLITE_NOMEM;
144326       }else if( SQLITE_OK!=(rc = sqlite3_declare_vtab(db, zSql)) ){
144327         *pzErr = sqlite3_mprintf("%s", sqlite3_errmsg(db));
144328       }
144329       sqlite3_free(zSql);
144330     }
144331   }
144332 
144333   if( rc==SQLITE_OK ){
144334     *ppVtab = (sqlite3_vtab *)pRtree;
144335   }else{
144336     rtreeRelease(pRtree);
144337   }
144338   return rc;
144339 }
144340 
144341 
144342 /*
144343 ** Implementation of a scalar function that decodes r-tree nodes to
144344 ** human readable strings. This can be used for debugging and analysis.
144345 **
144346 ** The scalar function takes two arguments, a blob of data containing
144347 ** an r-tree node, and the number of dimensions the r-tree indexes.
144348 ** For a two-dimensional r-tree structure called "rt", to deserialize
144349 ** all nodes, a statement like:
144350 **
144351 **   SELECT rtreenode(2, data) FROM rt_node;
144352 **
144353 ** The human readable string takes the form of a Tcl list with one
144354 ** entry for each cell in the r-tree node. Each entry is itself a
144355 ** list, containing the 8-byte rowid/pageno followed by the 
144356 ** <num-dimension>*2 coordinates.
144357 */
144358 static void rtreenode(sqlite3_context *ctx, int nArg, sqlite3_value **apArg){
144359   char *zText = 0;
144360   RtreeNode node;
144361   Rtree tree;
144362   int ii;
144363 
144364   UNUSED_PARAMETER(nArg);
144365   memset(&node, 0, sizeof(RtreeNode));
144366   memset(&tree, 0, sizeof(Rtree));
144367   tree.nDim = sqlite3_value_int(apArg[0]);
144368   tree.nBytesPerCell = 8 + 8 * tree.nDim;
144369   node.zData = (u8 *)sqlite3_value_blob(apArg[1]);
144370 
144371   for(ii=0; ii<NCELL(&node); ii++){
144372     char zCell[512];
144373     int nCell = 0;
144374     RtreeCell cell;
144375     int jj;
144376 
144377     nodeGetCell(&tree, &node, ii, &cell);
144378     sqlite3_snprintf(512-nCell,&zCell[nCell],"%lld", cell.iRowid);
144379     nCell = (int)strlen(zCell);
144380     for(jj=0; jj<tree.nDim*2; jj++){
144381 #ifndef SQLITE_RTREE_INT_ONLY
144382       sqlite3_snprintf(512-nCell,&zCell[nCell], " %f",
144383                        (double)cell.aCoord[jj].f);
144384 #else
144385       sqlite3_snprintf(512-nCell,&zCell[nCell], " %d",
144386                        cell.aCoord[jj].i);
144387 #endif
144388       nCell = (int)strlen(zCell);
144389     }
144390 
144391     if( zText ){
144392       char *zTextNew = sqlite3_mprintf("%s {%s}", zText, zCell);
144393       sqlite3_free(zText);
144394       zText = zTextNew;
144395     }else{
144396       zText = sqlite3_mprintf("{%s}", zCell);
144397     }
144398   }
144399   
144400   sqlite3_result_text(ctx, zText, -1, sqlite3_free);
144401 }
144402 
144403 static void rtreedepth(sqlite3_context *ctx, int nArg, sqlite3_value **apArg){
144404   UNUSED_PARAMETER(nArg);
144405   if( sqlite3_value_type(apArg[0])!=SQLITE_BLOB 
144406    || sqlite3_value_bytes(apArg[0])<2
144407   ){
144408     sqlite3_result_error(ctx, "Invalid argument to rtreedepth()", -1); 
144409   }else{
144410     u8 *zBlob = (u8 *)sqlite3_value_blob(apArg[0]);
144411     sqlite3_result_int(ctx, readInt16(zBlob));
144412   }
144413 }
144414 
144415 /*
144416 ** Register the r-tree module with database handle db. This creates the
144417 ** virtual table module "rtree" and the debugging/analysis scalar 
144418 ** function "rtreenode".
144419 */
144420 SQLITE_PRIVATE int sqlite3RtreeInit(sqlite3 *db){
144421   const int utf8 = SQLITE_UTF8;
144422   int rc;
144423 
144424   rc = sqlite3_create_function(db, "rtreenode", 2, utf8, 0, rtreenode, 0, 0);
144425   if( rc==SQLITE_OK ){
144426     rc = sqlite3_create_function(db, "rtreedepth", 1, utf8, 0,rtreedepth, 0, 0);
144427   }
144428   if( rc==SQLITE_OK ){
144429 #ifdef SQLITE_RTREE_INT_ONLY
144430     void *c = (void *)RTREE_COORD_INT32;
144431 #else
144432     void *c = (void *)RTREE_COORD_REAL32;
144433 #endif
144434     rc = sqlite3_create_module_v2(db, "rtree", &rtreeModule, c, 0);
144435   }
144436   if( rc==SQLITE_OK ){
144437     void *c = (void *)RTREE_COORD_INT32;
144438     rc = sqlite3_create_module_v2(db, "rtree_i32", &rtreeModule, c, 0);
144439   }
144440 
144441   return rc;
144442 }
144443 
144444 /*
144445 ** A version of sqlite3_free() that can be used as a callback. This is used
144446 ** in two places - as the destructor for the blob value returned by the
144447 ** invocation of a geometry function, and as the destructor for the geometry
144448 ** functions themselves.
144449 */
144450 static void doSqlite3Free(void *p){
144451   sqlite3_free(p);
144452 }
144453 
144454 /*
144455 ** Each call to sqlite3_rtree_geometry_callback() creates an ordinary SQLite
144456 ** scalar user function. This C function is the callback used for all such
144457 ** registered SQL functions.
144458 **
144459 ** The scalar user functions return a blob that is interpreted by r-tree
144460 ** table MATCH operators.
144461 */
144462 static void geomCallback(sqlite3_context *ctx, int nArg, sqlite3_value **aArg){
144463   RtreeGeomCallback *pGeomCtx = (RtreeGeomCallback *)sqlite3_user_data(ctx);
144464   RtreeMatchArg *pBlob;
144465   int nBlob;
144466 
144467   nBlob = sizeof(RtreeMatchArg) + (nArg-1)*sizeof(RtreeDValue);
144468   pBlob = (RtreeMatchArg *)sqlite3_malloc(nBlob);
144469   if( !pBlob ){
144470     sqlite3_result_error_nomem(ctx);
144471   }else{
144472     int i;
144473     pBlob->magic = RTREE_GEOMETRY_MAGIC;
144474     pBlob->xGeom = pGeomCtx->xGeom;
144475     pBlob->pContext = pGeomCtx->pContext;
144476     pBlob->nParam = nArg;
144477     for(i=0; i<nArg; i++){
144478 #ifdef SQLITE_RTREE_INT_ONLY
144479       pBlob->aParam[i] = sqlite3_value_int64(aArg[i]);
144480 #else
144481       pBlob->aParam[i] = sqlite3_value_double(aArg[i]);
144482 #endif
144483     }
144484     sqlite3_result_blob(ctx, pBlob, nBlob, doSqlite3Free);
144485   }
144486 }
144487 
144488 /*
144489 ** Register a new geometry function for use with the r-tree MATCH operator.
144490 */
144491 SQLITE_API int sqlite3_rtree_geometry_callback(
144492   sqlite3 *db,
144493   const char *zGeom,
144494   int (*xGeom)(sqlite3_rtree_geometry *, int, RtreeDValue *, int *),
144495   void *pContext
144496 ){
144497   RtreeGeomCallback *pGeomCtx;      /* Context object for new user-function */
144498 
144499   /* Allocate and populate the context object. */
144500   pGeomCtx = (RtreeGeomCallback *)sqlite3_malloc(sizeof(RtreeGeomCallback));
144501   if( !pGeomCtx ) return SQLITE_NOMEM;
144502   pGeomCtx->xGeom = xGeom;
144503   pGeomCtx->pContext = pContext;
144504 
144505   /* Create the new user-function. Register a destructor function to delete
144506   ** the context object when it is no longer required.  */
144507   return sqlite3_create_function_v2(db, zGeom, -1, SQLITE_ANY, 
144508       (void *)pGeomCtx, geomCallback, 0, 0, doSqlite3Free
144509   );
144510 }
144511 
144512 #if !SQLITE_CORE
144513 #ifdef _WIN32
144514 __declspec(dllexport)
144515 #endif
144516 SQLITE_API int sqlite3_rtree_init(
144517   sqlite3 *db,
144518   char **pzErrMsg,
144519   const sqlite3_api_routines *pApi
144520 ){
144521   SQLITE_EXTENSION_INIT2(pApi)
144522   return sqlite3RtreeInit(db);
144523 }
144524 #endif
144525 
144526 #endif
144527 
144528 /************** End of rtree.c ***********************************************/
144529 /************** Begin file icu.c *********************************************/
144530 /*
144531 ** 2007 May 6
144532 **
144533 ** The author disclaims copyright to this source code.  In place of
144534 ** a legal notice, here is a blessing:
144535 **
144536 **    May you do good and not evil.
144537 **    May you find forgiveness for yourself and forgive others.
144538 **    May you share freely, never taking more than you give.
144539 **
144540 *************************************************************************
144541 ** $Id: icu.c,v 1.7 2007/12/13 21:54:11 drh Exp $
144542 **
144543 ** This file implements an integration between the ICU library 
144544 ** ("International Components for Unicode", an open-source library 
144545 ** for handling unicode data) and SQLite. The integration uses 
144546 ** ICU to provide the following to SQLite:
144547 **
144548 **   * An implementation of the SQL regexp() function (and hence REGEXP
144549 **     operator) using the ICU uregex_XX() APIs.
144550 **
144551 **   * Implementations of the SQL scalar upper() and lower() functions
144552 **     for case mapping.
144553 **
144554 **   * Integration of ICU and SQLite collation sequences.
144555 **
144556 **   * An implementation of the LIKE operator that uses ICU to 
144557 **     provide case-independent matching.
144558 */
144559 
144560 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_ICU)
144561 
144562 /* Include ICU headers */
144563 #include <unicode/utypes.h>
144564 #include <unicode/uregex.h>
144565 #include <unicode/ustring.h>
144566 #include <unicode/ucol.h>
144567 
144568 /* #include <assert.h> */
144569 
144570 #ifndef SQLITE_CORE
144571   SQLITE_EXTENSION_INIT1
144572 #else
144573 #endif
144574 
144575 /*
144576 ** Maximum length (in bytes) of the pattern in a LIKE or GLOB
144577 ** operator.
144578 */
144579 #ifndef SQLITE_MAX_LIKE_PATTERN_LENGTH
144580 # define SQLITE_MAX_LIKE_PATTERN_LENGTH 50000
144581 #endif
144582 
144583 /*
144584 ** Version of sqlite3_free() that is always a function, never a macro.
144585 */
144586 static void xFree(void *p){
144587   sqlite3_free(p);
144588 }
144589 
144590 /*
144591 ** Compare two UTF-8 strings for equality where the first string is
144592 ** a "LIKE" expression. Return true (1) if they are the same and 
144593 ** false (0) if they are different.
144594 */
144595 static int icuLikeCompare(
144596   const uint8_t *zPattern,   /* LIKE pattern */
144597   const uint8_t *zString,    /* The UTF-8 string to compare against */
144598   const UChar32 uEsc         /* The escape character */
144599 ){
144600   static const int MATCH_ONE = (UChar32)'_';
144601   static const int MATCH_ALL = (UChar32)'%';
144602 
144603   int iPattern = 0;       /* Current byte index in zPattern */
144604   int iString = 0;        /* Current byte index in zString */
144605 
144606   int prevEscape = 0;     /* True if the previous character was uEsc */
144607 
144608   while( zPattern[iPattern]!=0 ){
144609 
144610     /* Read (and consume) the next character from the input pattern. */
144611     UChar32 uPattern;
144612     U8_NEXT_UNSAFE(zPattern, iPattern, uPattern);
144613     assert(uPattern!=0);
144614 
144615     /* There are now 4 possibilities:
144616     **
144617     **     1. uPattern is an unescaped match-all character "%",
144618     **     2. uPattern is an unescaped match-one character "_",
144619     **     3. uPattern is an unescaped escape character, or
144620     **     4. uPattern is to be handled as an ordinary character
144621     */
144622     if( !prevEscape && uPattern==MATCH_ALL ){
144623       /* Case 1. */
144624       uint8_t c;
144625 
144626       /* Skip any MATCH_ALL or MATCH_ONE characters that follow a
144627       ** MATCH_ALL. For each MATCH_ONE, skip one character in the 
144628       ** test string.
144629       */
144630       while( (c=zPattern[iPattern]) == MATCH_ALL || c == MATCH_ONE ){
144631         if( c==MATCH_ONE ){
144632           if( zString[iString]==0 ) return 0;
144633           U8_FWD_1_UNSAFE(zString, iString);
144634         }
144635         iPattern++;
144636       }
144637 
144638       if( zPattern[iPattern]==0 ) return 1;
144639 
144640       while( zString[iString] ){
144641         if( icuLikeCompare(&zPattern[iPattern], &zString[iString], uEsc) ){
144642           return 1;
144643         }
144644         U8_FWD_1_UNSAFE(zString, iString);
144645       }
144646       return 0;
144647 
144648     }else if( !prevEscape && uPattern==MATCH_ONE ){
144649       /* Case 2. */
144650       if( zString[iString]==0 ) return 0;
144651       U8_FWD_1_UNSAFE(zString, iString);
144652 
144653     }else if( !prevEscape && uPattern==uEsc){
144654       /* Case 3. */
144655       prevEscape = 1;
144656 
144657     }else{
144658       /* Case 4. */
144659       UChar32 uString;
144660       U8_NEXT_UNSAFE(zString, iString, uString);
144661       uString = u_foldCase(uString, U_FOLD_CASE_DEFAULT);
144662       uPattern = u_foldCase(uPattern, U_FOLD_CASE_DEFAULT);
144663       if( uString!=uPattern ){
144664         return 0;
144665       }
144666       prevEscape = 0;
144667     }
144668   }
144669 
144670   return zString[iString]==0;
144671 }
144672 
144673 /*
144674 ** Implementation of the like() SQL function.  This function implements
144675 ** the build-in LIKE operator.  The first argument to the function is the
144676 ** pattern and the second argument is the string.  So, the SQL statements:
144677 **
144678 **       A LIKE B
144679 **
144680 ** is implemented as like(B, A). If there is an escape character E, 
144681 **
144682 **       A LIKE B ESCAPE E
144683 **
144684 ** is mapped to like(B, A, E).
144685 */
144686 static void icuLikeFunc(
144687   sqlite3_context *context, 
144688   int argc, 
144689   sqlite3_value **argv
144690 ){
144691   const unsigned char *zA = sqlite3_value_text(argv[0]);
144692   const unsigned char *zB = sqlite3_value_text(argv[1]);
144693   UChar32 uEsc = 0;
144694 
144695   /* Limit the length of the LIKE or GLOB pattern to avoid problems
144696   ** of deep recursion and N*N behavior in patternCompare().
144697   */
144698   if( sqlite3_value_bytes(argv[0])>SQLITE_MAX_LIKE_PATTERN_LENGTH ){
144699     sqlite3_result_error(context, "LIKE or GLOB pattern too complex", -1);
144700     return;
144701   }
144702 
144703 
144704   if( argc==3 ){
144705     /* The escape character string must consist of a single UTF-8 character.
144706     ** Otherwise, return an error.
144707     */
144708     int nE= sqlite3_value_bytes(argv[2]);
144709     const unsigned char *zE = sqlite3_value_text(argv[2]);
144710     int i = 0;
144711     if( zE==0 ) return;
144712     U8_NEXT(zE, i, nE, uEsc);
144713     if( i!=nE){
144714       sqlite3_result_error(context, 
144715           "ESCAPE expression must be a single character", -1);
144716       return;
144717     }
144718   }
144719 
144720   if( zA && zB ){
144721     sqlite3_result_int(context, icuLikeCompare(zA, zB, uEsc));
144722   }
144723 }
144724 
144725 /*
144726 ** This function is called when an ICU function called from within
144727 ** the implementation of an SQL scalar function returns an error.
144728 **
144729 ** The scalar function context passed as the first argument is 
144730 ** loaded with an error message based on the following two args.
144731 */
144732 static void icuFunctionError(
144733   sqlite3_context *pCtx,       /* SQLite scalar function context */
144734   const char *zName,           /* Name of ICU function that failed */
144735   UErrorCode e                 /* Error code returned by ICU function */
144736 ){
144737   char zBuf[128];
144738   sqlite3_snprintf(128, zBuf, "ICU error: %s(): %s", zName, u_errorName(e));
144739   zBuf[127] = '\0';
144740   sqlite3_result_error(pCtx, zBuf, -1);
144741 }
144742 
144743 /*
144744 ** Function to delete compiled regexp objects. Registered as
144745 ** a destructor function with sqlite3_set_auxdata().
144746 */
144747 static void icuRegexpDelete(void *p){
144748   URegularExpression *pExpr = (URegularExpression *)p;
144749   uregex_close(pExpr);
144750 }
144751 
144752 /*
144753 ** Implementation of SQLite REGEXP operator. This scalar function takes
144754 ** two arguments. The first is a regular expression pattern to compile
144755 ** the second is a string to match against that pattern. If either 
144756 ** argument is an SQL NULL, then NULL Is returned. Otherwise, the result
144757 ** is 1 if the string matches the pattern, or 0 otherwise.
144758 **
144759 ** SQLite maps the regexp() function to the regexp() operator such
144760 ** that the following two are equivalent:
144761 **
144762 **     zString REGEXP zPattern
144763 **     regexp(zPattern, zString)
144764 **
144765 ** Uses the following ICU regexp APIs:
144766 **
144767 **     uregex_open()
144768 **     uregex_matches()
144769 **     uregex_close()
144770 */
144771 static void icuRegexpFunc(sqlite3_context *p, int nArg, sqlite3_value **apArg){
144772   UErrorCode status = U_ZERO_ERROR;
144773   URegularExpression *pExpr;
144774   UBool res;
144775   const UChar *zString = sqlite3_value_text16(apArg[1]);
144776 
144777   (void)nArg;  /* Unused parameter */
144778 
144779   /* If the left hand side of the regexp operator is NULL, 
144780   ** then the result is also NULL. 
144781   */
144782   if( !zString ){
144783     return;
144784   }
144785 
144786   pExpr = sqlite3_get_auxdata(p, 0);
144787   if( !pExpr ){
144788     const UChar *zPattern = sqlite3_value_text16(apArg[0]);
144789     if( !zPattern ){
144790       return;
144791     }
144792     pExpr = uregex_open(zPattern, -1, 0, 0, &status);
144793 
144794     if( U_SUCCESS(status) ){
144795       sqlite3_set_auxdata(p, 0, pExpr, icuRegexpDelete);
144796     }else{
144797       assert(!pExpr);
144798       icuFunctionError(p, "uregex_open", status);
144799       return;
144800     }
144801   }
144802 
144803   /* Configure the text that the regular expression operates on. */
144804   uregex_setText(pExpr, zString, -1, &status);
144805   if( !U_SUCCESS(status) ){
144806     icuFunctionError(p, "uregex_setText", status);
144807     return;
144808   }
144809 
144810   /* Attempt the match */
144811   res = uregex_matches(pExpr, 0, &status);
144812   if( !U_SUCCESS(status) ){
144813     icuFunctionError(p, "uregex_matches", status);
144814     return;
144815   }
144816 
144817   /* Set the text that the regular expression operates on to a NULL
144818   ** pointer. This is not really necessary, but it is tidier than 
144819   ** leaving the regular expression object configured with an invalid
144820   ** pointer after this function returns.
144821   */
144822   uregex_setText(pExpr, 0, 0, &status);
144823 
144824   /* Return 1 or 0. */
144825   sqlite3_result_int(p, res ? 1 : 0);
144826 }
144827 
144828 /*
144829 ** Implementations of scalar functions for case mapping - upper() and 
144830 ** lower(). Function upper() converts its input to upper-case (ABC).
144831 ** Function lower() converts to lower-case (abc).
144832 **
144833 ** ICU provides two types of case mapping, "general" case mapping and
144834 ** "language specific". Refer to ICU documentation for the differences
144835 ** between the two.
144836 **
144837 ** To utilise "general" case mapping, the upper() or lower() scalar 
144838 ** functions are invoked with one argument:
144839 **
144840 **     upper('ABC') -> 'abc'
144841 **     lower('abc') -> 'ABC'
144842 **
144843 ** To access ICU "language specific" case mapping, upper() or lower()
144844 ** should be invoked with two arguments. The second argument is the name
144845 ** of the locale to use. Passing an empty string ("") or SQL NULL value
144846 ** as the second argument is the same as invoking the 1 argument version
144847 ** of upper() or lower().
144848 **
144849 **     lower('I', 'en_us') -> 'i'
144850 **     lower('I', 'tr_tr') -> 'ı' (small dotless i)
144851 **
144852 ** http://www.icu-project.org/userguide/posix.html#case_mappings
144853 */
144854 static void icuCaseFunc16(sqlite3_context *p, int nArg, sqlite3_value **apArg){
144855   const UChar *zInput;
144856   UChar *zOutput;
144857   int nInput;
144858   int nOutput;
144859 
144860   UErrorCode status = U_ZERO_ERROR;
144861   const char *zLocale = 0;
144862 
144863   assert(nArg==1 || nArg==2);
144864   if( nArg==2 ){
144865     zLocale = (const char *)sqlite3_value_text(apArg[1]);
144866   }
144867 
144868   zInput = sqlite3_value_text16(apArg[0]);
144869   if( !zInput ){
144870     return;
144871   }
144872   nInput = sqlite3_value_bytes16(apArg[0]);
144873 
144874   nOutput = nInput * 2 + 2;
144875   zOutput = sqlite3_malloc(nOutput);
144876   if( !zOutput ){
144877     return;
144878   }
144879 
144880   if( sqlite3_user_data(p) ){
144881     u_strToUpper(zOutput, nOutput/2, zInput, nInput/2, zLocale, &status);
144882   }else{
144883     u_strToLower(zOutput, nOutput/2, zInput, nInput/2, zLocale, &status);
144884   }
144885 
144886   if( !U_SUCCESS(status) ){
144887     icuFunctionError(p, "u_strToLower()/u_strToUpper", status);
144888     return;
144889   }
144890 
144891   sqlite3_result_text16(p, zOutput, -1, xFree);
144892 }
144893 
144894 /*
144895 ** Collation sequence destructor function. The pCtx argument points to
144896 ** a UCollator structure previously allocated using ucol_open().
144897 */
144898 static void icuCollationDel(void *pCtx){
144899   UCollator *p = (UCollator *)pCtx;
144900   ucol_close(p);
144901 }
144902 
144903 /*
144904 ** Collation sequence comparison function. The pCtx argument points to
144905 ** a UCollator structure previously allocated using ucol_open().
144906 */
144907 static int icuCollationColl(
144908   void *pCtx,
144909   int nLeft,
144910   const void *zLeft,
144911   int nRight,
144912   const void *zRight
144913 ){
144914   UCollationResult res;
144915   UCollator *p = (UCollator *)pCtx;
144916   res = ucol_strcoll(p, (UChar *)zLeft, nLeft/2, (UChar *)zRight, nRight/2);
144917   switch( res ){
144918     case UCOL_LESS:    return -1;
144919     case UCOL_GREATER: return +1;
144920     case UCOL_EQUAL:   return 0;
144921   }
144922   assert(!"Unexpected return value from ucol_strcoll()");
144923   return 0;
144924 }
144925 
144926 /*
144927 ** Implementation of the scalar function icu_load_collation().
144928 **
144929 ** This scalar function is used to add ICU collation based collation 
144930 ** types to an SQLite database connection. It is intended to be called
144931 ** as follows:
144932 **
144933 **     SELECT icu_load_collation(<locale>, <collation-name>);
144934 **
144935 ** Where <locale> is a string containing an ICU locale identifier (i.e.
144936 ** "en_AU", "tr_TR" etc.) and <collation-name> is the name of the
144937 ** collation sequence to create.
144938 */
144939 static void icuLoadCollation(
144940   sqlite3_context *p, 
144941   int nArg, 
144942   sqlite3_value **apArg
144943 ){
144944   sqlite3 *db = (sqlite3 *)sqlite3_user_data(p);
144945   UErrorCode status = U_ZERO_ERROR;
144946   const char *zLocale;      /* Locale identifier - (eg. "jp_JP") */
144947   const char *zName;        /* SQL Collation sequence name (eg. "japanese") */
144948   UCollator *pUCollator;    /* ICU library collation object */
144949   int rc;                   /* Return code from sqlite3_create_collation_x() */
144950 
144951   assert(nArg==2);
144952   zLocale = (const char *)sqlite3_value_text(apArg[0]);
144953   zName = (const char *)sqlite3_value_text(apArg[1]);
144954 
144955   if( !zLocale || !zName ){
144956     return;
144957   }
144958 
144959   pUCollator = ucol_open(zLocale, &status);
144960   if( !U_SUCCESS(status) ){
144961     icuFunctionError(p, "ucol_open", status);
144962     return;
144963   }
144964   assert(p);
144965 
144966   rc = sqlite3_create_collation_v2(db, zName, SQLITE_UTF16, (void *)pUCollator, 
144967       icuCollationColl, icuCollationDel
144968   );
144969   if( rc!=SQLITE_OK ){
144970     ucol_close(pUCollator);
144971     sqlite3_result_error(p, "Error registering collation function", -1);
144972   }
144973 }
144974 
144975 /*
144976 ** Register the ICU extension functions with database db.
144977 */
144978 SQLITE_PRIVATE int sqlite3IcuInit(sqlite3 *db){
144979   struct IcuScalar {
144980     const char *zName;                        /* Function name */
144981     int nArg;                                 /* Number of arguments */
144982     int enc;                                  /* Optimal text encoding */
144983     void *pContext;                           /* sqlite3_user_data() context */
144984     void (*xFunc)(sqlite3_context*,int,sqlite3_value**);
144985   } scalars[] = {
144986     {"regexp", 2, SQLITE_ANY,          0, icuRegexpFunc},
144987 
144988     {"lower",  1, SQLITE_UTF16,        0, icuCaseFunc16},
144989     {"lower",  2, SQLITE_UTF16,        0, icuCaseFunc16},
144990     {"upper",  1, SQLITE_UTF16, (void*)1, icuCaseFunc16},
144991     {"upper",  2, SQLITE_UTF16, (void*)1, icuCaseFunc16},
144992 
144993     {"lower",  1, SQLITE_UTF8,         0, icuCaseFunc16},
144994     {"lower",  2, SQLITE_UTF8,         0, icuCaseFunc16},
144995     {"upper",  1, SQLITE_UTF8,  (void*)1, icuCaseFunc16},
144996     {"upper",  2, SQLITE_UTF8,  (void*)1, icuCaseFunc16},
144997 
144998     {"like",   2, SQLITE_UTF8,         0, icuLikeFunc},
144999     {"like",   3, SQLITE_UTF8,         0, icuLikeFunc},
145000 
145001     {"icu_load_collation",  2, SQLITE_UTF8, (void*)db, icuLoadCollation},
145002   };
145003 
145004   int rc = SQLITE_OK;
145005   int i;
145006 
145007   for(i=0; rc==SQLITE_OK && i<(int)(sizeof(scalars)/sizeof(scalars[0])); i++){
145008     struct IcuScalar *p = &scalars[i];
145009     rc = sqlite3_create_function(
145010         db, p->zName, p->nArg, p->enc, p->pContext, p->xFunc, 0, 0
145011     );
145012   }
145013 
145014   return rc;
145015 }
145016 
145017 #if !SQLITE_CORE
145018 #ifdef _WIN32
145019 __declspec(dllexport)
145020 #endif
145021 SQLITE_API int sqlite3_icu_init(
145022   sqlite3 *db, 
145023   char **pzErrMsg,
145024   const sqlite3_api_routines *pApi
145025 ){
145026   SQLITE_EXTENSION_INIT2(pApi)
145027   return sqlite3IcuInit(db);
145028 }
145029 #endif
145030 
145031 #endif
145032 
145033 /************** End of icu.c *************************************************/
145034 /************** Begin file fts3_icu.c ****************************************/
145035 /*
145036 ** 2007 June 22
145037 **
145038 ** The author disclaims copyright to this source code.  In place of
145039 ** a legal notice, here is a blessing:
145040 **
145041 **    May you do good and not evil.
145042 **    May you find forgiveness for yourself and forgive others.
145043 **    May you share freely, never taking more than you give.
145044 **
145045 *************************************************************************
145046 ** This file implements a tokenizer for fts3 based on the ICU library.
145047 */
145048 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
145049 #ifdef SQLITE_ENABLE_ICU
145050 
145051 /* #include <assert.h> */
145052 /* #include <string.h> */
145053 
145054 #include <unicode/ubrk.h>
145055 /* #include <unicode/ucol.h> */
145056 /* #include <unicode/ustring.h> */
145057 #include <unicode/utf16.h>
145058 
145059 typedef struct IcuTokenizer IcuTokenizer;
145060 typedef struct IcuCursor IcuCursor;
145061 
145062 struct IcuTokenizer {
145063   sqlite3_tokenizer base;
145064   char *zLocale;
145065 };
145066 
145067 struct IcuCursor {
145068   sqlite3_tokenizer_cursor base;
145069 
145070   UBreakIterator *pIter;      /* ICU break-iterator object */
145071   int nChar;                  /* Number of UChar elements in pInput */
145072   UChar *aChar;               /* Copy of input using utf-16 encoding */
145073   int *aOffset;               /* Offsets of each character in utf-8 input */
145074 
145075   int nBuffer;
145076   char *zBuffer;
145077 
145078   int iToken;
145079 };
145080 
145081 /*
145082 ** Create a new tokenizer instance.
145083 */
145084 static int icuCreate(
145085   int argc,                            /* Number of entries in argv[] */
145086   const char * const *argv,            /* Tokenizer creation arguments */
145087   sqlite3_tokenizer **ppTokenizer      /* OUT: Created tokenizer */
145088 ){
145089   IcuTokenizer *p;
145090   int n = 0;
145091 
145092   if( argc>0 ){
145093     n = strlen(argv[0])+1;
145094   }
145095   p = (IcuTokenizer *)sqlite3_malloc(sizeof(IcuTokenizer)+n);
145096   if( !p ){
145097     return SQLITE_NOMEM;
145098   }
145099   memset(p, 0, sizeof(IcuTokenizer));
145100 
145101   if( n ){
145102     p->zLocale = (char *)&p[1];
145103     memcpy(p->zLocale, argv[0], n);
145104   }
145105 
145106   *ppTokenizer = (sqlite3_tokenizer *)p;
145107 
145108   return SQLITE_OK;
145109 }
145110 
145111 /*
145112 ** Destroy a tokenizer
145113 */
145114 static int icuDestroy(sqlite3_tokenizer *pTokenizer){
145115   IcuTokenizer *p = (IcuTokenizer *)pTokenizer;
145116   sqlite3_free(p);
145117   return SQLITE_OK;
145118 }
145119 
145120 /*
145121 ** Prepare to begin tokenizing a particular string.  The input
145122 ** string to be tokenized is pInput[0..nBytes-1].  A cursor
145123 ** used to incrementally tokenize this string is returned in 
145124 ** *ppCursor.
145125 */
145126 static int icuOpen(
145127   sqlite3_tokenizer *pTokenizer,         /* The tokenizer */
145128   const char *zInput,                    /* Input string */
145129   int nInput,                            /* Length of zInput in bytes */
145130   sqlite3_tokenizer_cursor **ppCursor    /* OUT: Tokenization cursor */
145131 ){
145132   IcuTokenizer *p = (IcuTokenizer *)pTokenizer;
145133   IcuCursor *pCsr;
145134 
145135   const int32_t opt = U_FOLD_CASE_DEFAULT;
145136   UErrorCode status = U_ZERO_ERROR;
145137   int nChar;
145138 
145139   UChar32 c;
145140   int iInput = 0;
145141   int iOut = 0;
145142 
145143   *ppCursor = 0;
145144 
145145   if( zInput==0 ){
145146     nInput = 0;
145147     zInput = "";
145148   }else if( nInput<0 ){
145149     nInput = strlen(zInput);
145150   }
145151   nChar = nInput+1;
145152   pCsr = (IcuCursor *)sqlite3_malloc(
145153       sizeof(IcuCursor) +                /* IcuCursor */
145154       ((nChar+3)&~3) * sizeof(UChar) +   /* IcuCursor.aChar[] */
145155       (nChar+1) * sizeof(int)            /* IcuCursor.aOffset[] */
145156   );
145157   if( !pCsr ){
145158     return SQLITE_NOMEM;
145159   }
145160   memset(pCsr, 0, sizeof(IcuCursor));
145161   pCsr->aChar = (UChar *)&pCsr[1];
145162   pCsr->aOffset = (int *)&pCsr->aChar[(nChar+3)&~3];
145163 
145164   pCsr->aOffset[iOut] = iInput;
145165   U8_NEXT(zInput, iInput, nInput, c); 
145166   while( c>0 ){
145167     int isError = 0;
145168     c = u_foldCase(c, opt);
145169     U16_APPEND(pCsr->aChar, iOut, nChar, c, isError);
145170     if( isError ){
145171       sqlite3_free(pCsr);
145172       return SQLITE_ERROR;
145173     }
145174     pCsr->aOffset[iOut] = iInput;
145175 
145176     if( iInput<nInput ){
145177       U8_NEXT(zInput, iInput, nInput, c);
145178     }else{
145179       c = 0;
145180     }
145181   }
145182 
145183   pCsr->pIter = ubrk_open(UBRK_WORD, p->zLocale, pCsr->aChar, iOut, &status);
145184   if( !U_SUCCESS(status) ){
145185     sqlite3_free(pCsr);
145186     return SQLITE_ERROR;
145187   }
145188   pCsr->nChar = iOut;
145189 
145190   ubrk_first(pCsr->pIter);
145191   *ppCursor = (sqlite3_tokenizer_cursor *)pCsr;
145192   return SQLITE_OK;
145193 }
145194 
145195 /*
145196 ** Close a tokenization cursor previously opened by a call to icuOpen().
145197 */
145198 static int icuClose(sqlite3_tokenizer_cursor *pCursor){
145199   IcuCursor *pCsr = (IcuCursor *)pCursor;
145200   ubrk_close(pCsr->pIter);
145201   sqlite3_free(pCsr->zBuffer);
145202   sqlite3_free(pCsr);
145203   return SQLITE_OK;
145204 }
145205 
145206 /*
145207 ** Extract the next token from a tokenization cursor.
145208 */
145209 static int icuNext(
145210   sqlite3_tokenizer_cursor *pCursor,  /* Cursor returned by simpleOpen */
145211   const char **ppToken,               /* OUT: *ppToken is the token text */
145212   int *pnBytes,                       /* OUT: Number of bytes in token */
145213   int *piStartOffset,                 /* OUT: Starting offset of token */
145214   int *piEndOffset,                   /* OUT: Ending offset of token */
145215   int *piPosition                     /* OUT: Position integer of token */
145216 ){
145217   IcuCursor *pCsr = (IcuCursor *)pCursor;
145218 
145219   int iStart = 0;
145220   int iEnd = 0;
145221   int nByte = 0;
145222 
145223   while( iStart==iEnd ){
145224     UChar32 c;
145225 
145226     iStart = ubrk_current(pCsr->pIter);
145227     iEnd = ubrk_next(pCsr->pIter);
145228     if( iEnd==UBRK_DONE ){
145229       return SQLITE_DONE;
145230     }
145231 
145232     while( iStart<iEnd ){
145233       int iWhite = iStart;
145234       U16_NEXT(pCsr->aChar, iWhite, pCsr->nChar, c);
145235       if( u_isspace(c) ){
145236         iStart = iWhite;
145237       }else{
145238         break;
145239       }
145240     }
145241     assert(iStart<=iEnd);
145242   }
145243 
145244   do {
145245     UErrorCode status = U_ZERO_ERROR;
145246     if( nByte ){
145247       char *zNew = sqlite3_realloc(pCsr->zBuffer, nByte);
145248       if( !zNew ){
145249         return SQLITE_NOMEM;
145250       }
145251       pCsr->zBuffer = zNew;
145252       pCsr->nBuffer = nByte;
145253     }
145254 
145255     u_strToUTF8(
145256         pCsr->zBuffer, pCsr->nBuffer, &nByte,    /* Output vars */
145257         &pCsr->aChar[iStart], iEnd-iStart,       /* Input vars */
145258         &status                                  /* Output success/failure */
145259     );
145260   } while( nByte>pCsr->nBuffer );
145261 
145262   *ppToken = pCsr->zBuffer;
145263   *pnBytes = nByte;
145264   *piStartOffset = pCsr->aOffset[iStart];
145265   *piEndOffset = pCsr->aOffset[iEnd];
145266   *piPosition = pCsr->iToken++;
145267 
145268   return SQLITE_OK;
145269 }
145270 
145271 /*
145272 ** The set of routines that implement the simple tokenizer
145273 */
145274 static const sqlite3_tokenizer_module icuTokenizerModule = {
145275   0,                           /* iVersion */
145276   icuCreate,                   /* xCreate  */
145277   icuDestroy,                  /* xCreate  */
145278   icuOpen,                     /* xOpen    */
145279   icuClose,                    /* xClose   */
145280   icuNext,                     /* xNext    */
145281 };
145282 
145283 /*
145284 ** Set *ppModule to point at the implementation of the ICU tokenizer.
145285 */
145286 SQLITE_PRIVATE void sqlite3Fts3IcuTokenizerModule(
145287   sqlite3_tokenizer_module const**ppModule
145288 ){
145289   *ppModule = &icuTokenizerModule;
145290 }
145291 
145292 #endif /* defined(SQLITE_ENABLE_ICU) */
145293 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
145294 
145295 /************** End of fts3_icu.c ********************************************/